docs(cli): add a CLI docs section generated from the command tree (#6762)

* docs(cli): add a CLI section, generated from the command tree

The `sim` CLI shipped with no coverage in the docs site. Adds a fourth
top-level tab for it, and moves Academy last.

The command reference is generated. `sim` exposes 147 leaf commands across
33 groups, most of them derived at runtime from the v2 route contracts, so a
hand-written reference would be wrong the week after it was written. The
generator walks the command tree `buildProgram()` hands to commander — the
same tree the terminal parses — rather than re-deriving it from the contract,
which would be a second implementation free to describe commands nobody can
invoke. `check:cli-docs` is a zero-arg `check:*` script, so the existing audit
runner picks it up and stale pages fail CI.

Generating against the real tree surfaced a collision it had been hiding:
`bulkUpdateKnowledgeDocuments` and `updateKnowledgeDocument` both derived to
`sim knowledge documents update`. Commander resolves a duplicate to the first
match, so the bulk form shadowed the single-document one and its flags were
unreachable while still appearing in `--help`. The bulk form is now
`batch-update`, matching how `tables rows batch-delete`/`batch-update` already
handle the same REST overload, and the generator fails on any duplicate path
so the next one cannot land silently.

Five hand-written guides cover install, auth, configuration, output formats,
and scripting. Also corrects two commands in the package README that do not
exist as documented (`tables columns <tableId>`, and `--sort score:desc`,
which is JSON).

* docs(cli): document every flag from the contracts, add troubleshooting and a single-page reference

The command reference was structurally complete but said almost nothing: 223 of
377 flags rendered as "Set sort by" because the CLI only ever read flag help
from its own contract overrides, and fell back to restating the flag name.

The prose already existed. The v2 route contracts carry 931 `.describe()` calls
and the OpenAPI specs publish all of them — 327 parameters and 282 body
properties, 100% coverage — but the generated operation table dropped every one,
carrying only a per-operation summary. It now carries the field descriptions,
the path-parameter descriptions, and positional help, so `--help` and the docs
explain a flag the same way the API reference does. Placeholder descriptions are
now zero, and 147/147 commands, 377/377 flags and 130/130 arguments are
documented.

`check:cli-docs` fails on a request field with no `.describe()` rather than
letting it render as documentation that says nothing.

Also in this pass:

- Commands are root-level sidebar entries under a Commands heading rather than
  a folder, and headings are the command's description, so the table of
  contents distinguishes entries at the first word instead of repeating
  "sim knowledge documents …" fourteen times. A guard fails the build if two
  descriptions on a page collide, since they would share an anchor.
- A single-page `Complete reference` carrying all 147 commands, for in-page
  search and for agents fetching `/cli/reference.mdx`. It keys on exact command
  paths because descriptions are only unique within a group.
- A troubleshooting page, with every message copied from the source.
- Table columns are sized by a local component; the flag column was starved
  while descriptions kept most of the row empty.
- The prerelease install channels are dropped from the docs and the package
  README, which is what npm renders.

* fix(docs): match the CLI tab by path segment, and escape backslashes before pipes

`pathname.includes('/cli')` also matches `/integrations/clickup` and
`/integrations/clickhouse`, so both existing integration pages lit the CLI tab
and unlit Documentation. Matching is now per path segment. Anchoring to the
start would not work either — a non-default locale prefixes the path, as in
`/ja/cli` — so the segment is matched wherever it sits.

Table cells now double a backslash before escaping pipes. A value ending in one
turned `a\` + `|` into `a\\|`, which the table parser reads as an escaped
backslash followed by an unescaped pipe, splitting the cell early. Nothing in
the command surface contains a backslash today, so this was latent rather than
visible.

The reference page's global options table is two-column and was being wrapped in
`CommandTable`, which sizes the second column for the `Required` cell of the
three-column tables and crushed the description into 5.5rem. It now matches the
overview page, which leaves that table unsized.

Author: waleedlatif1

apps/docs/app/[lang]/[[...slug]]/page.tsx

@@ -113,14 +113,21 @@ export default async function Page(props: { params: Promise<{ slug?: string[]; l
   // Academy lessons are video-first: drop the "On this page" TOC and go full
   // width so the lesson hero/video gets the room (chapters live in-page instead).
   const isAcademy = slug?.[0] === 'academy'
+  const isCli = slug?.[0] === 'cli'
 
   const pageTreeRecord = source.pageTree as Record<string, Root>
   const pageTree = pageTreeRecord[lang] ?? pageTreeRecord.en ?? Object.values(pageTreeRecord)[0]
   const rawNeighbours = pageTree ? findNeighbour(pageTree, page.url) : null
-  // Academy and API Reference are self-contained sections; keep prev/next inside
-  // the section instead of spilling into the main documentation tree. Match both
-  // the section's pages (`/<slug>/...`) and its index (`/<slug>`).
-  const sectionSlug = isApiReference ? 'api-reference' : isAcademy ? 'academy' : null
+  // Academy, API Reference, and CLI are self-contained sections; keep prev/next
+  // inside the section instead of spilling into the main documentation tree.
+  // Match both the section's pages (`/<slug>/...`) and its index (`/<slug>`).
+  const sectionSlug = isApiReference
+    ? 'api-reference'
+    : isAcademy
+      ? 'academy'
+      : isCli
+        ? 'cli'
+        : null
   const inSection = (url?: string) =>
     url != null && (url.includes(`/${sectionSlug}/`) || url.endsWith(`/${sectionSlug}`))
   const neighbours = sectionSlug

apps/docs/components/navbar/navbar.tsx

@@ -8,23 +8,53 @@ import { SimWordmark } from '@/components/ui/sim-logo'
 import { ThemeToggle } from '@/components/ui/theme-toggle'
 import { cn } from '@/lib/utils'
 
+/**
+ * Sections that own a tab, in reading order: the main docs, then the two
+ * reference surfaces, then Academy. `Documentation` matches by exclusion, so
+ * every section listed here is one it must not claim.
+ */
+const SECTION_TABS = ['api-reference', 'academy', 'cli'] as const
+
+/**
+ * Whether a pathname is inside a section, matched by whole path segment.
+ *
+ * A substring test is wrong: `/integrations/clickup` and
+ * `/integrations/clickhouse` both contain `/cli`, which lit the CLI tab and
+ * unlit Documentation on two existing integration pages. Anchoring to the start
+ * is also wrong, because a non-default locale prefixes the path (`/ja/cli`), so
+ * the segment can sit anywhere.
+ */
+function isInSection(pathname: string, section: string): boolean {
+  return (
+    pathname === `/${section}` ||
+    pathname.endsWith(`/${section}`) ||
+    pathname.includes(`/${section}/`)
+  )
+}
+
 const NAV_TABS = [
   {
     label: 'Documentation',
     href: '/introduction',
-    match: (p: string) => !p.includes('/api-reference') && !p.includes('/academy'),
+    match: (p: string) => !SECTION_TABS.some((section) => isInSection(p, section)),
     external: false,
   },
   {
-    label: 'Academy',
-    href: '/academy',
-    match: (p: string) => p.includes('/academy'),
+    label: 'API Reference',
+    href: '/api-reference/getting-started',
+    match: (p: string) => isInSection(p, 'api-reference'),
     external: false,
   },
   {
-    label: 'API Reference',
-    href: '/api-reference/getting-started',
-    match: (p: string) => p.includes('/api-reference'),
+    label: 'CLI',
+    href: '/cli',
+    match: (p: string) => isInSection(p, 'cli'),
+    external: false,
+  },
+  {
+    label: 'Academy',
+    href: '/academy',
+    match: (p: string) => isInSection(p, 'academy'),
     external: false,
   },
 ] as const

apps/docs/components/ui/command-table.tsx

@@ -0,0 +1,34 @@
+import type { ReactNode } from 'react'
+
+interface CommandTableProps {
+  children: ReactNode
+}
+
+/**
+ * Column sizing for the generated CLI reference tables.
+ *
+ * Auto layout gives a column width in proportion to its content, which is
+ * backwards here: descriptions are sentences and flags are short, so the flag
+ * column collapsed until `--enabled-filter <value>` wrapped across three lines
+ * while the description beside it kept most of the row empty. A fixed layout
+ * with explicit widths reserves the space the flag actually needs.
+ *
+ * Cells align to the top because a wrapped four-line description would
+ * otherwise float its flag into the middle of the row, away from the line it
+ * belongs to.
+ */
+export function CommandTable({ children }: CommandTableProps) {
+  return (
+    <div
+      className={[
+        '[&_table]:w-full [&_table]:table-fixed',
+        '[&_th:nth-child(1)]:w-[30%] [&_th:nth-child(2)]:w-[5.5rem]',
+        '[&_td]:align-top [&_th]:align-bottom',
+        // Long flags and dotted paths have no spaces to break on.
+        '[&_td:nth-child(1)_code]:break-words',
+      ].join(' ')}
+    >
+      {children}
+    </div>
+  )
+}

apps/docs/content/docs/en/cli/audit-logs.mdx

@@ -0,0 +1,62 @@
+---
+title: Audit Logs
+description: Manage audit logs — every subcommand, argument, and flag
+---
+
+import { CommandTable } from '@/components/ui/command-table'
+
+`sim audit-logs` is also spelled `sim audit-log`.
+
+Every command below also accepts the [global options](/cli/commands#global-options).
+
+## Get audit log
+
+```bash
+sim audit-logs get <id> [options]
+```
+
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `id` | Yes | Audit-log entry identifier. |
+
+</CommandTable>
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--organization <value>` | Yes | Organization ID (personal API key required). |
+
+</CommandTable>
+
+## List audit logs
+
+```bash
+sim audit-logs list [options]
+```
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--action <value>` | No | Filter by exact action name. |
+| `--resource-type <value>` | No | Filter by resource type. Accepts a comma-separated set; members are trimmed and deduplicated, and member order affects neither the result nor the cursor. |
+| `--resource-id <value>` | No | Filter by exact resource identifier. |
+| `--start-date <value>` | No | Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
+| `--end-date <value>` | No | Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
+| `--include-departed` | No | Include actions by users who have left the organization. |
+| `--no-include-departed` | No | Send --include-departed as false. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--organization <value>` | Yes | Organization ID (personal API key required). |
+| `--actor-email <value>` | No | Filter by actor email address. |
+| `--all-workspaces` | No | Do not filter to the configured workspace (personal API key required for account-wide access). |
+
+</CommandTable>

apps/docs/content/docs/en/cli/authentication.mdx

@@ -0,0 +1,167 @@
+---
+title: Authentication
+description: Sign in from the terminal, authenticate CI with an API key, and keep several accounts side by side
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+
+The CLI authenticates with a Sim API key. On a workstation, `sim login` mints and
+stores one for you. In CI, you supply one through the environment and nothing
+touches the filesystem.
+
+## Signing in
+
+```bash
+sim login
+```
+
+The terminal prints a pairing code and a URL:
+
+```
+Pairing code: K7M2-P9XT
+Confirm this code matches what the browser shows before approving.
+
+https://sim.ai/cli/auth?request=…&scope=platform
+Waiting for approval…
+
+✓ Logged in. Key stored in /Users/you/.sim/credentials
+  Personal key, defaulting to ws_abc123. Override per command with --workspace.
+```
+
+This is the same browser handoff shape as `gh auth login`. Nothing redeemable
+crosses the browser leg, and there is no loopback listener — so it works over
+SSH and inside containers.
+
+<Callout type="warn">
+Confirm the pairing code in your terminal matches the one the browser shows
+before you approve. That check is what binds the approval to *your* terminal.
+</Callout>
+
+| Option | What it does |
+| --- | --- |
+| `--no-browser` | Print the URL instead of opening a browser |
+| `--scope <scope>` | Key space to mint from: `platform` (default) or `copilot` |
+| `-y, --yes` | Overwrite an existing profile without prompting |
+
+### Picking a workspace
+
+The approval page is where you choose the workspace — the terminal has no key
+yet, so it cannot list them for you.
+
+`sim login` issues a **personal** key. The workspace you pick becomes the
+profile's default `workspace`; it does **not** restrict the key to that
+workspace. Target another workspace the key can reach with `--workspace`:
+
+```bash
+sim workflows list --workspace ws_other
+```
+
+`sim login --workspace <id>` preselects a workspace in the picker, and
+re-logging into an existing profile preselects the one already configured.
+
+## Checking who you are
+
+```bash
+sim whoami
+```
+
+This prints the resolved endpoint, workspace, output format, and account — and
+which source each value came from. Reach for it first whenever a command targets
+something you did not expect.
+
+## Signing out
+
+```bash
+sim logout           # remove the stored key
+sim logout --all     # remove the profile entirely, including its settings
+```
+
+<Callout type="warn">
+`sim logout` removes the key from disk but does **not** revoke it. Revoke keys in
+Sim under **Settings → API keys**.
+</Callout>
+
+## Authenticating CI
+
+Skip `sim login` entirely. Set the key and workspace in the environment and the
+CLI never reads or writes a config file:
+
+```bash
+export SIM_API_KEY="sim_…"
+export SIM_WORKSPACE="ws_abc123"
+
+sim workflows run wf_7Yb2 --input '{"source":"nightly"}' --output json
+```
+
+Create the key in Sim under **Settings → API keys**. Store it as a secret in your
+CI provider — never commit it.
+
+<Callout type="info">
+`SIM_CONFIG_DIR` relocates both files if you do need them somewhere other than
+`~/.sim` — a container image, or a runner with no writable home directory.
+</Callout>
+
+### GitHub Actions
+
+```yaml title=".github/workflows/nightly.yml"
+jobs:
+  digest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install --global sim
+      - run: sim workflows run wf_7Yb2 --output json
+        env:
+          SIM_API_KEY: ${{ secrets.SIM_API_KEY }}
+          SIM_WORKSPACE: ${{ vars.SIM_WORKSPACE }}
+```
+
+## Several accounts at once
+
+Each profile holds one identity and one set of defaults, so a production account
+and a local stack can coexist without re-authenticating:
+
+```bash
+sim login --profile dev --endpoint http://localhost:3000
+sim login --profile prod
+
+sim workflows list --profile dev
+sim workflows list --profile prod
+```
+
+See [Configuration](/cli/configuration) for how profiles are stored and resolved.
+
+## Self-hosted and non-production deployments
+
+Point the CLI at any Sim deployment with `--endpoint`, then sign in against it:
+
+```bash
+sim login --profile local --endpoint http://localhost:3000
+```
+
+Save it so you do not have to repeat the flag:
+
+```bash
+sim configure --set-endpoint http://localhost:3000 --profile local
+```
+
+## Where the key is stored
+
+Keys live in `~/.sim/credentials`, written with `0600` permissions, kept apart
+from the non-secret `~/.sim/config` so the two can be handled differently — you
+can commit `config` to a dotfiles repo, and never `credentials`.
+
+```ini title="~/.sim/credentials"
+[default]
+api_key = sim_…
+
+[dev]
+api_key = sim_…
+```
+
+## Organization audit logs
+
+`sim audit-logs` requires a **personal** API key — the kind `sim login` issues.
+A workspace-scoped key cannot read organization-level audit logs.

apps/docs/content/docs/en/cli/billing.mdx

@@ -0,0 +1,45 @@
+---
+title: Billing
+description: Manage billing — every subcommand, argument, and flag
+---
+
+import { CommandTable } from '@/components/ui/command-table'
+
+Every command below also accepts the [global options](/cli/commands#global-options).
+
+## Show billing status and current-period credit usage
+
+```bash
+sim billing status [options]
+```
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--all-workspaces` | No | Do not filter to the configured workspace (personal API key required for account-wide access). |
+
+</CommandTable>
+
+## List credit usage events
+
+```bash
+sim billing logs [options]
+```
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--source <value>` | No | Filter by usage source; sim-chat combines Copilot and workspace chat. Accepted values: `workflow`, `wand`, `sim-chat`, `mcp_copilot`, `mothership_block`, `knowledge-base`, `voice-input`, `enrichment`, `voice-output`. |
+| `--period <value>` | No | Billing period. Accepted values: `1d`, `7d`, `30d`, `all`, `custom`. |
+| `--start-date <value>` | No | Custom period start (ISO 8601). |
+| `--end-date <value>` | No | Custom period end (ISO 8601). |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--all-workspaces` | No | Do not filter to the configured workspace (personal API key required for account-wide access). |
+
+</CommandTable>