diff --git a/lfs.c b/lfs.c
index c49e9e0c..5fcfb04f 100644
--- a/lfs.c
+++ b/lfs.c
@@ -15227,6 +15227,12 @@ static int lfs_init(lfs_t *lfs, const struct lfs_config *cfg) {
     // wear-leveling.
     LFS_ASSERT(lfs->cfg->block_cycles != 0);
 
+    // inline_size must be <= block_size/4
+    LFS_ASSERT(lfs->cfg->inline_size <= lfs->cfg->block_size/4);
+    // shrub_size must be <= block_size/4
+    LFS_ASSERT(lfs->cfg->shrub_size <= lfs->cfg->block_size/4);
+    // fragment_size must be <= block_size/8
+    LFS_ASSERT(lfs->cfg->fragment_size <= lfs->cfg->block_size/8);
 
     // setup read cache
     lfs->rcache.block = 0;
diff --git a/lfs.h b/lfs.h
index f15a4741..6d51b3e6 100644
--- a/lfs.h
+++ b/lfs.h
@@ -267,10 +267,34 @@ struct lfs_config {
 //    // Defaults to block_size when zero.
 //    lfs_size_t metadata_max;
 
-    // TODO document
+    // TODO these are pretty low-level details, should we have reasonable
+    // defaults? need to benchmark.
+
+    // Maximum size on inlined files in bytes. Inlined files decrease storage
+    // requirements, but may impact metadata-related performance. Must be <=
+    // block_size/4.
+    //
+    // 0 disables inline files.
     lfs_size_t inline_size;
+
+    // Maximum size of inlined trees (shrubs) in bytes. Shrubs reduce B-tree
+    // root overhead, but may impact metadata-related performance. Must be <=
+    // blocksize/4.
+    //
+    // 0 disables shrubs.
     lfs_size_t shrub_size;
+
+    // Maximum size of a non-block B-tree leaf in bytes. Smaller values may
+    // make small random-writes cheaper, but increase metadata overhead. Must
+    // be <= block_size/8.
     lfs_size_t fragment_size;
+
+    // Threshold for compacting multiple fragments into a block. Smaller
+    // values will compact more frequently, reducing disk usage, but
+    // increasing the cost of random-writes.
+    //
+    // 0 only writes blocks, minimizing disk usage, while -1 or any value >=
+    // block_size only writes fragments, minimizing random-write cost.
     lfs_size_t crystal_thresh;
 };
 
diff --git a/runners/bench_runner.h b/runners/bench_runner.h
index f891d81a..d91f8a78 100644
--- a/runners/bench_runner.h
+++ b/runners/bench_runner.h
@@ -119,7 +119,7 @@ void bench_permutation(size_t i, uint32_t *buffer, size_t size);
         lfs_max(16, lfs_max(READ_SIZE, PROG_SIZE))) \
     BENCH_DEFINE(INLINE_SIZE,        BLOCK_SIZE/4                           ) \
     BENCH_DEFINE(SHRUB_SIZE,         INLINE_SIZE                            ) \
-    BENCH_DEFINE(FRAGMENT_SIZE,      CACHE_SIZE                             ) \
+    BENCH_DEFINE(FRAGMENT_SIZE,      BLOCK_SIZE/8                           ) \
     BENCH_DEFINE(CRYSTAL_THRESH,     BLOCK_SIZE/8                           ) \
     BENCH_DEFINE(LOOKAHEAD_SIZE,     16                                     ) \
     BENCH_DEFINE(BLOCK_CYCLES,       -1                                     ) \
diff --git a/runners/test_runner.h b/runners/test_runner.h
index 40b06346..2d6760c7 100644
--- a/runners/test_runner.h
+++ b/runners/test_runner.h
@@ -103,7 +103,7 @@ void test_permutation(size_t i, uint32_t *buffer, size_t size);
         lfs_max(16, lfs_max(READ_SIZE, PROG_SIZE))                          ) \
     TEST_DEFINE(INLINE_SIZE,        BLOCK_SIZE/4                            ) \
     TEST_DEFINE(SHRUB_SIZE,         INLINE_SIZE                             ) \
-    TEST_DEFINE(FRAGMENT_SIZE,      CACHE_SIZE                              ) \
+    TEST_DEFINE(FRAGMENT_SIZE,      BLOCK_SIZE/8                            ) \
     TEST_DEFINE(CRYSTAL_THRESH,     BLOCK_SIZE/8                            ) \
     TEST_DEFINE(LOOKAHEAD_SIZE,     16                                      ) \
     TEST_DEFINE(BLOCK_CYCLES,       -1                                      ) \