docs(user): de-dev polish — strip internal scaffolding (Phase 3a)

[aaltshuler]

Phase 3a of the docs restructure (Phase 1 #223, Phase 2 #225 — both merged).
Docs only, no behavior changes.

Removes developer-only scaffolding that leaked into the public user/operator docs
while preserving every user-facing behavior, command, flag, endpoint, constant,
and env var.

Removed across 18 files

• Internal ticket / sequencing refs (MR-NNN, RFC-NNN, "Phase N").
• Source paths (crates/**/*.rs, *.pest) and internal struct/function dumps
  (the QueryIR / GraphCommit / SchemaMigrationPlan Rust types, internal fn
  names).
• Lance-internal blocker prose (upstream issue numbers, blob-decode cause,
  sidecar Phase-B/C mechanics) — keeping the user-visible behavior.
• pre-v0.4.0 Run-state-machine archaeology.

Internal IR / lowering / recovery-internals sections were trimmed to brief
user-facing notes or removed.

Kept

All language syntax, lint codes, Cedar actions/scopes, endpoints, error taxonomy,
every constant and env var (verified none dropped from the cheat-sheet), and
operator-facing explanations of on-disk artifacts. Residual "legacy" mentions are
all user-facing (deprecated omnigraph.yaml, the legacy token chain, old command
names).

Verification

• Zero internal-scaffolding leaks (MR/RFC/Phase/.rs/.pest = 0) across
  docs/user.
• Zero broken .md links.
• scripts/check-agents-md.sh green.

Still to come

• Phase 3b — guides: task tutorials (guides/). The original plan was to mine
  the old omnigraph-website, but it's deprecated and the new site is a flat repo
  mirror — so guides would be net-new content; scoping separately.

🤖 Generated with Claude Code

Greptile Summary

Phase 3a doc cleanup across 18 docs/user/ files: removes internal Rust source paths, ticket/RFC references, pre-v0.4.0 Run-state-machine archaeology, and internal struct/function dumps while preserving every user-facing behavior, CLI flag, endpoint, env var, and constant.

• Every user-facing command, API endpoint, Cedar action, error code, and tunable was verified present in the final state; the trimmed content was scaffolding that had no meaning outside the engineering team.
• One gap in the verification coverage: the scrub checked for Phase but not Stage, leaving two Stage 3A and one Stage 2C labels (internal development milestone shorthand) in docs/user/clusters/config.md and docs/user/cli/reference.md — the same class of planning shorthand the PR explicitly targets per AGENTS.md Rule 5.

Confidence Score: 4/5

Docs-only change with no runtime impact; safe to merge as-is, with one small follow-up worth doing before the final polish is considered complete.

The cleanup is thorough across 16 of 18 files. The two cluster-related files still carry Stage 3A and Stage 2C labels that are the same kind of internal milestone shorthand the PR explicitly set out to remove. The verification script checked for Phase but not Stage, so they slipped through. Everything else was verified present in the final state.

docs/user/clusters/config.md (lines 60 and 455) and docs/user/cli/reference.md (line 191) still contain Stage 3A and Stage 2C internal labels.

Important Files Changed

Filename	Overview
docs/user/branching/changes.md	Removed source-path prefix; replaced with clean prose. No user-facing content lost.
docs/user/branching/index.md	Significant trim: internal Rust function signatures replaced with CLI command names and plain-English descriptions. All user-facing behaviors preserved.
docs/user/branching/transactions.md	Minor wording cleanup; full worked examples, atomicity tables, and failure-mode matrix all intact.
docs/user/cli/index.md	Single-line editorial change; all command examples and deprecated-name table preserved.
docs/user/cli/reference.md	Internal scaffolding trimmed, but residual Stage 3A label on line 191 survives. All CLI commands, flags, config schemas, and deprecation notices intact.
docs/user/clusters/config.md	Only 2 lines removed; Stage 3A (line 60) and Stage 2C (line 455) internal stage labels remain. All cluster YAML, planning/apply/approval mechanics intact.
docs/user/concepts/storage.md	Manifest row schema and internal versioning details cleaned up. Mermaid diagram preserved; all URI schemes, env vars, and on-disk layout descriptions intact.
docs/user/deployment.md	Minimal change; container entrypoint env vars, auth token sources, and build variants all preserved.
docs/user/operations/errors.md	Minor 2-line tweak; error taxonomy, result serialization, and D2 rejection message text intact.
docs/user/operations/maintenance.md	Internal Phase B/C sidecar mechanics removed; all user-facing optimize/repair/cleanup behavior, env vars, and per-table stats fields preserved.
docs/user/operations/policy.md	Removed internal ticket reference; all Cedar actions, scope kinds, runtime states table, and CLI commands preserved.
docs/user/operations/server.md	Largest change (71 lines); internal boot-mode scaffolding trimmed. Full endpoint inventory, auth model, per-actor admission limits, and error model all intact.
docs/user/queries/index.md	Internal IR-op details removed; all GQ syntax, traversal dispatch explanation with env-var ceilings, and lint codes preserved.
docs/user/reference/constants.md	Cleaned up; all user-visible tunables, env vars, and traversal dispatch explanation retained.
docs/user/schema/index.md	Internal Rust type dumps replaced with plain-English step descriptions; all scalar types, constraints, annotations, and allow-data-loss behavior preserved.
docs/user/schema/lint.md	Internal implementation notes removed; all OG-XXX-NNN codes, family table, and prior-art attribution intact.
docs/user/search/embeddings.md	Minor edit; both embedding clients, their env vars, and the offline CLI pipeline all intact.
docs/user/search/indexes.md	Small cleanup; BTREE/FTS/vector index table and CSR topology index description preserved.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[18 docs/user files] --> B{Content type}
    B --> C[Internal scaffolding REMOVED]
    B --> D[User-facing content KEPT]
    C --> C1[MR-NNN / RFC-NNN ticket refs]
    C --> C2[Rust source paths]
    C --> C3[Internal fn names]
    C --> C4[Rust struct dumps]
    C --> C5[Phase B/C sidecar mechanics]
    C --> C6[Pre-v0.4.0 Run state machine]
    D --> D1[All CLI commands and flags]
    D --> D2[All HTTP endpoints and auth model]
    D --> D3[All Cedar actions and scopes]
    D --> D4[All env vars and tunables]
    D --> D5[Error taxonomy and lint codes]
    D --> D6[Schema and query syntax]
    C --> E{Verification}
    E --> F[Phase grep passed]
    E --> G[MR/RFC/rs/pest grep passed]
    E --> H[Stage N grep missed]
    H --> I[Stage 3A in clusters/config.md line 60 and Stage 2C line 455 and Stage 3A in cli/reference.md line 191]

Loading

Comments Outside Diff (1)

1. docs/user/clusters/config.md, line 60 (link)

   Residual internal "Stage N" label not caught by the Phase-scrub

   Stage 3A here (and Stage 2C on line 455) are the same class of internal planning shorthand as the Phase N references this PR explicitly targets. The verification check in the PR description only grep'd for Phase, so Stage survived. An outside contributor or operator reading this has no way to resolve what "Stage 3A" means — it's not a version, a PR, or a public milestone.

   Same pattern in docs/user/cli/reference.md line 191: Stage 3A accepts graphs, schemas, stored queries, and policy bundle file references. Both should be rewritten to describe capability scope without the internal stage label (e.g., "OmniGraph currently supports…" or "In this release, the cluster control plane supports…").

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

   

_{Reviews (1): Last reviewed commit: "docs(user): de-dev polish — strip intern..." | Re-trigger Greptile}

Context used:

• Context used - CLAUDE.md (source)