docs: classify command stability

README.md

@@ -628,6 +628,8 @@ The automation-facing compatibility policy is documented in
 [`docs/compatibility.md`](docs/compatibility.md). It defines the intended
 stability rules for CLI commands, `--json` output, the local control JSONL
 protocol, Iroh peer wire protocols, SQLite metadata, and signed operation logs.
+Command-family stability levels are tracked in
+[`docs/command-stability.md`](docs/command-stability.md).
 
 GitHub Actions workflows live under `.github/workflows/`:
 

docs/command-stability.md

@@ -0,0 +1,78 @@
+# Command Stability
+
+This document classifies the current `geth` CLI surface for scripts and
+downstream projects. The compatibility rules in `docs/compatibility.md` apply
+to stable commands after the first deployment tag.
+
+## Stability Levels
+
+- Stable: intended for scripts once the first deployment tag exists. Command
+  names, flag names, argument meanings, and `--json` field meanings should not
+  change within a major release.
+- Experimental: useful and tested, but the command may still change as the
+  subsystem is hardened. Scripts should pin a geth version and expect migration
+  notes.
+- Prototype: proves a shape or workflow. Do not build durable automation on it
+  without expecting replacement or incompatible changes.
+
+## Stable
+
+The following command families are intended to be stable automation surfaces:
+
+- `geth init`
+- `geth daemon run`
+- `geth daemon service install|uninstall|start|stop|status|print`
+- `geth status`
+- `geth node id`
+- `geth node list|rename|revoke|grant|revoke-grant|endpoint-add|endpoint-revoke`
+- `geth node enroll request|submit|import|list|approve|sync`
+- `geth peer export|import|list|ping|auth-check`
+- `geth keychain init|status|admin-add|admin-revoke|allowed-signers|verify`
+- `geth keychain sign-file|verify-file`
+- `geth keychain sigchain|verify-sigchain|import-sigchain|verify-checkpoint|fetch|explain|explain-signer`
+- `geth auth explain|grant|revoke|sync`
+- `geth sync status|now`
+- `geth secret status|create|rotate|bearer`
+- Local CAS object commands: `geth cas add|get|hash|has|pin|unpin|cleanup|providers|list|fetch`
+- File-root metadata commands: `geth cas root add|list|scan|sync|apply`
+- File-conflict metadata commands: `geth cas conflict record|list|resolve`
+- SSH certificate and revocation metadata commands under `geth ssh cert ...`
+  and `geth ssh revocation ...`
+- `geth ssh proxy`
+- Restricted `geth ssh admin-shell help|status|node-id`
+- `geth db add|status|changes|sync`
+- `geth kv create|set|get|sync`
+- `geth document create|status|set|get|sync`
+- `geth pubsub pub|sub`
+- `geth pipe listen|connect|send|recv|forward-tcp|forward-unix`
+- `geth completions`
+- `geth guide`
+
+## Experimental
+
+The following commands are tested but may still change while the subsystem
+settles:
+
+- `geth overlay status|plan|join|leave|interface-plan|up|down|peers|send|recv`
+
+Migration expectation: overlay membership records and authorization resources
+should remain readable, but packet runtime flags, platform activation details,
+and route metadata may change before the first deployment tag.
+
+## Prototype
+
+The following commands intentionally do not claim a stable security or storage
+contract yet:
+
+- `geth cas add-private`
+- `geth cas get-private`
+
+Migration expectation: prototype private CAS envelopes may be replaced by an
+audited AEAD/key-envelope design. Existing prototype blobs may need an explicit
+re-encryption or export/import workflow.
+
+## Adding Commands
+
+New commands should enter this file in the same change that introduces the CLI
+surface. Experimental and prototype commands should include a migration or
+removal expectation before users are encouraged to automate against them.

docs/production-readiness-roadmap.md

@@ -109,11 +109,11 @@ and downstream projects.
   - `[ ]` Pipe and overlay wire protocol variants roundtrip.
   - `[x]` Unknown or malformed protocol inputs fail safely.
 
-- `[ ]` Classify command stability.
+- `[x]` Classify command stability.
   Acceptance criteria:
-  - `[ ]` Commands are marked stable, experimental, or prototype in docs.
+  - `[x]` Commands are marked stable, experimental, or prototype in docs.
-  - `[ ]` Help text avoids production claims for experimental paths.
+  - `[x]` Help text avoids production claims for experimental paths.
-  - `[ ]` Prototype paths have explicit migration or removal expectations.
+  - `[x]` Prototype paths have explicit migration or removal expectations.
 
 ## Phase 3: Storage And Migration Hardening