From 0098fdae922c439bfcff3cdf28539b0da86efbba Mon Sep 17 00:00:00 2001
From: Tien Pham <tien@clockworklabs.io>
Date: Fri, 16 Oct 2026 16:52:08 +0300
Subject: [PATCH] feat: nest subcommands in the CLI reference TOC and fix
 squeezed step text

---
 .../00100-cli-reference.md                    | 93 ++++++++++---------
 docs/scripts/generate-cli-docs.mjs            | 19 +++-
 docs/src/css/custom.css                       | 11 ++-
 3 files changed, 72 insertions(+), 51 deletions(-)

diff --git a/docs/docs/00300-resources/00200-reference/00100-cli-reference/00100-cli-reference.md b/docs/docs/00300-resources/00200-reference/00100-cli-reference/00100-cli-reference.md
index 0266e5f203c..c1e25e3993d 100644
--- a/docs/docs/00300-resources/00200-reference/00100-cli-reference/00100-cli-reference.md
+++ b/docs/docs/00300-resources/00200-reference/00100-cli-reference/00100-cli-reference.md
@@ -1,6 +1,7 @@
 ---
 title: CLI Reference
 slug: /cli-reference
+toc_max_heading_level: 4
 ---
 
 # Command-Line Help for `spacetime`
@@ -12,8 +13,8 @@ This document contains the help content for the `spacetime` command-line program
 * [`spacetime`↴](#spacetime)
 * [`spacetime publish`↴](#spacetime-publish)
 * [`spacetime env`↴](#spacetime-env)
-* [`spacetime env get`↴](#spacetime-env-get)
-* [`spacetime env list`↴](#spacetime-env-list)
+  * [`spacetime env get`↴](#spacetime-env-get)
+  * [`spacetime env list`↴](#spacetime-env-list)
 * [`spacetime delete`↴](#spacetime-delete)
 * [`spacetime logs`↴](#spacetime-logs)
 * [`spacetime call`↴](#spacetime-call)
@@ -25,36 +26,36 @@ This document contains the help content for the `spacetime` command-line program
 * [`spacetime generate`↴](#spacetime-generate)
 * [`spacetime list`↴](#spacetime-list)
 * [`spacetime login`↴](#spacetime-login)
-* [`spacetime login show`↴](#spacetime-login-show)
+  * [`spacetime login show`↴](#spacetime-login-show)
 * [`spacetime logout`↴](#spacetime-logout)
 * [`spacetime init`↴](#spacetime-init)
 * [`spacetime build`↴](#spacetime-build)
 * [`spacetime server`↴](#spacetime-server)
-* [`spacetime server list`↴](#spacetime-server-list)
-* [`spacetime server set-default`↴](#spacetime-server-set-default)
-* [`spacetime server add`↴](#spacetime-server-add)
-* [`spacetime server remove`↴](#spacetime-server-remove)
-* [`spacetime server fingerprint`↴](#spacetime-server-fingerprint)
-* [`spacetime server ping`↴](#spacetime-server-ping)
-* [`spacetime server edit`↴](#spacetime-server-edit)
-* [`spacetime server clear`↴](#spacetime-server-clear)
+  * [`spacetime server list`↴](#spacetime-server-list)
+  * [`spacetime server set-default`↴](#spacetime-server-set-default)
+  * [`spacetime server add`↴](#spacetime-server-add)
+  * [`spacetime server remove`↴](#spacetime-server-remove)
+  * [`spacetime server fingerprint`↴](#spacetime-server-fingerprint)
+  * [`spacetime server ping`↴](#spacetime-server-ping)
+  * [`spacetime server edit`↴](#spacetime-server-edit)
+  * [`spacetime server clear`↴](#spacetime-server-clear)
 * [`spacetime subscribe`↴](#spacetime-subscribe)
 * [`spacetime start`↴](#spacetime-start)
 * [`spacetime lock`↴](#spacetime-lock)
 * [`spacetime unlock`↴](#spacetime-unlock)
 * [`spacetime auth`↴](#spacetime-auth)
-* [`spacetime auth config`↴](#spacetime-auth-config)
-* [`spacetime auth config set`↴](#spacetime-auth-config-set)
-* [`spacetime auth config reset`↴](#spacetime-auth-config-reset)
-* [`spacetime auth idp`↴](#spacetime-auth-idp)
-* [`spacetime auth idp set`↴](#spacetime-auth-idp-set)
-* [`spacetime auth idp enable`↴](#spacetime-auth-idp-enable)
-* [`spacetime auth idp disable`↴](#spacetime-auth-idp-disable)
-* [`spacetime auth client`↴](#spacetime-auth-client)
-* [`spacetime auth client create`↴](#spacetime-auth-client-create)
-* [`spacetime auth client delete`↴](#spacetime-auth-client-delete)
-* [`spacetime auth client get`↴](#spacetime-auth-client-get)
-* [`spacetime auth client set`↴](#spacetime-auth-client-set)
+  * [`spacetime auth config`↴](#spacetime-auth-config)
+    * [`spacetime auth config set`↴](#spacetime-auth-config-set)
+    * [`spacetime auth config reset`↴](#spacetime-auth-config-reset)
+  * [`spacetime auth idp`↴](#spacetime-auth-idp)
+    * [`spacetime auth idp set`↴](#spacetime-auth-idp-set)
+    * [`spacetime auth idp enable`↴](#spacetime-auth-idp-enable)
+    * [`spacetime auth idp disable`↴](#spacetime-auth-idp-disable)
+  * [`spacetime auth client`↴](#spacetime-auth-client)
+    * [`spacetime auth client create`↴](#spacetime-auth-client-create)
+    * [`spacetime auth client delete`↴](#spacetime-auth-client-delete)
+    * [`spacetime auth client get`↴](#spacetime-auth-client-get)
+    * [`spacetime auth client set`↴](#spacetime-auth-client-set)
 * [`spacetime version`↴](#spacetime-version)
 
 ## `spacetime`
@@ -171,7 +172,7 @@ Inspect published database environment variables
 
 
 
-## `spacetime env get`
+### `spacetime env get`
 
 Read one published environment value
 
@@ -195,7 +196,7 @@ Read one published environment value
 
 
 
-## `spacetime env list`
+### `spacetime env list`
 
 List published environment keys and values
 
@@ -514,7 +515,7 @@ Manage your login to the SpacetimeDB CLI
 
 
 
-## `spacetime login show`
+### `spacetime login show`
 
 Show the current login info
 
@@ -598,7 +599,7 @@ Manage the connection to the SpacetimeDB server. WARNING: This command is UNSTAB
 
 
 
-## `spacetime server list`
+### `spacetime server list`
 
 List stored server configurations
 
@@ -606,7 +607,7 @@ List stored server configurations
 
 
 
-## `spacetime server set-default`
+### `spacetime server set-default`
 
 Set the default server for future operations
 
@@ -618,7 +619,7 @@ Set the default server for future operations
 
 
 
-## `spacetime server add`
+### `spacetime server add`
 
 Add a new server configuration
 
@@ -636,7 +637,7 @@ Add a new server configuration
 
 
 
-## `spacetime server remove`
+### `spacetime server remove`
 
 Remove a saved server configuration
 
@@ -652,7 +653,7 @@ Remove a saved server configuration
 
 
 
-## `spacetime server fingerprint`
+### `spacetime server fingerprint`
 
 Show or update a saved server's fingerprint
 
@@ -668,7 +669,7 @@ Show or update a saved server's fingerprint
 
 
 
-## `spacetime server ping`
+### `spacetime server ping`
 
 Checks to see if a SpacetimeDB host is online
 
@@ -680,7 +681,7 @@ Checks to see if a SpacetimeDB host is online
 
 
 
-## `spacetime server edit`
+### `spacetime server edit`
 
 Update a saved server's nickname, host name or protocol
 
@@ -699,7 +700,7 @@ Update a saved server's nickname, host name or protocol
 
 
 
-## `spacetime server clear`
+### `spacetime server clear`
 
 Deletes all data from all local databases
 
@@ -825,7 +826,7 @@ Manage SpacetimeAuth for a database
 
 
 
-## `spacetime auth config`
+### `spacetime auth config`
 
 Manage SpacetimeAuth configuration for a database
 
@@ -838,7 +839,7 @@ Manage SpacetimeAuth configuration for a database
 
 
 
-## `spacetime auth config set`
+#### `spacetime auth config set`
 
 Set a SpacetimeAuth configuration value for a database
 
@@ -855,7 +856,7 @@ Set a SpacetimeAuth configuration value for a database
 
 
 
-## `spacetime auth config reset`
+#### `spacetime auth config reset`
 
 Reset the SpacetimeAuth configuration of a database to its defaults, keeping the display name and Steam settings
 
@@ -867,7 +868,7 @@ Reset the SpacetimeAuth configuration of a database to its defaults, keeping the
 
 
 
-## `spacetime auth idp`
+### `spacetime auth idp`
 
 Manage identity providers for a database
 
@@ -881,7 +882,7 @@ Manage identity providers for a database
 
 
 
-## `spacetime auth idp set`
+#### `spacetime auth idp set`
 
 Configure and enable an identity provider for a database
 
@@ -899,7 +900,7 @@ Configure and enable an identity provider for a database
 
 
 
-## `spacetime auth idp enable`
+#### `spacetime auth idp enable`
 
 Enable an identity provider for a database
 
@@ -915,7 +916,7 @@ Enable an identity provider for a database
 
 
 
-## `spacetime auth idp disable`
+#### `spacetime auth idp disable`
 
 Disable an identity provider for a database
 
@@ -931,7 +932,7 @@ Disable an identity provider for a database
 
 
 
-## `spacetime auth client`
+### `spacetime auth client`
 
 Manage OAuth clients for a database
 
@@ -946,7 +947,7 @@ Manage OAuth clients for a database
 
 
 
-## `spacetime auth client create`
+#### `spacetime auth client create`
 
 Create a new OAuth client
 
@@ -965,7 +966,7 @@ Create a new OAuth client
 
 
 
-## `spacetime auth client delete`
+#### `spacetime auth client delete`
 
 Delete an OAuth client
 
@@ -983,7 +984,7 @@ Delete an OAuth client
 
 
 
-## `spacetime auth client get`
+#### `spacetime auth client get`
 
 Get an OAuth client
 
@@ -1002,7 +1003,7 @@ Get an OAuth client
 
 
 
-## `spacetime auth client set`
+#### `spacetime auth client set`
 
 Set a configuration value for an OAuth client
 
diff --git a/docs/scripts/generate-cli-docs.mjs b/docs/scripts/generate-cli-docs.mjs
index 75e5f213767..b43c177a930 100755
--- a/docs/scripts/generate-cli-docs.mjs
+++ b/docs/scripts/generate-cli-docs.mjs
@@ -61,6 +61,20 @@ function escapeAngleBracketsOutsideBackticks(content) {
     .join('\n');
 }
 
+// clap-markdown renders subcommands flat so need to nest them
+function nestSubcommands(content) {
+  const depth = command => Math.max(0, command.split(' ').length - 2);
+  return content
+    .replace(
+      /^\* (\[`(spacetime[^`]*)`↴\])/gm,
+      (_, link, command) => `${'  '.repeat(depth(command))}* ${link}`
+    )
+    .replace(
+      /^## (`(spacetime[^`]*)`)$/gm,
+      (_, title, command) => `${'#'.repeat(2 + depth(command))} ${title}`
+    );
+}
+
 async function main() {
   const repoRoot = getRepoRoot();
 
@@ -74,7 +88,7 @@ async function main() {
     '00100-cli-reference.md',
   );
 
-  const header = `---\ntitle: CLI Reference\nslug: /cli-reference\n---\n\n`;
+  const header = `---\ntitle: CLI Reference\nslug: /cli-reference\ntoc_max_heading_level: 4\n---\n\n`;
 
   await fs.writeFile(outFile, header, 'utf8');
   await runCargoAndAppend({ cwd: repoRoot, outFilePath: outFile });
@@ -82,7 +96,8 @@ async function main() {
   // Post-process: escape angle-bracket placeholders outside backtick spans for MDX
   const raw = await fs.readFile(outFile, 'utf8');
   const escaped = escapeAngleBracketsOutsideBackticks(raw);
-  await fs.writeFile(outFile, `${escaped.trimEnd()}\n`, 'utf8');
+  const nested = nestSubcommands(escaped);
+  await fs.writeFile(outFile, `${nested.trimEnd()}\n`, 'utf8');
 }
 
 main().catch(err => {
diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css
index 98a8f824d86..87ed565c4c3 100644
--- a/docs/src/css/custom.css
+++ b/docs/src/css/custom.css
@@ -336,6 +336,11 @@ p {
   margin-bottom: 1.25rem;
 }
 
+.markdown li > ul,
+.markdown li > ol {
+  margin-bottom: 0;
+}
+
 /* Code 3 - per the style guide */
 .tmp {
   font-family: var(--clockworklabs-font-source);
@@ -988,7 +993,7 @@ a.card {
 
 .step {
   display: grid;
-  grid-template-columns: 1fr 1fr;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
   gap: 32px;
   align-items: start;
   counter-increment: step-counter;
@@ -1046,9 +1051,9 @@ a.card {
 }
 
 /* Responsive: stack on smaller screens */
-@media screen and (max-width: 996px) {
+@media screen and (max-width: 1279px) {
   .step {
-    grid-template-columns: 1fr;
+    grid-template-columns: minmax(0, 1fr);
   }
 
   .step-code {