docs: final cleanup and accuracy pass before public push

- Fix const inference bug: wrap inferred contracts with status-code guards
- Add integration test for status-guarded contract inference
- Tighten and deduplicate docs across verify, qualify, getting-started, cli
- Fix broken cross-references and TypeScript→JavaScript conversions
- Fix factual errors: license, Date.now(), sampling defaults, cache env
- Add missing features: --workspace, --generation-profile, json-summary formats
- Move stale extension docs (AUTH-RATE-LIMIT-REVISED, HTTP-EXTENSIONS) to attic
- Update PLUGIN_CONTRACTS_SPEC status to Implemented
- Build: clean | Tests: 849 pass, 0 fail

docs/cli.md

@@ -10,15 +10,17 @@ Every command accepts these flags:
 |---|---|---|
 | `--config <path>` | Config file path | Auto-detect |
 | `--profile <name>` | Profile name from config | First profile |
-| `--generation-profile <name>` | Generation budget profile (built-in or config alias) | Depth-derived |
+| `--generation-profile <name>` | Generation budget profile (built-in: quick, standard, deep) | Depth-derived |
 | `--cwd <path>` | Working directory override | `process.cwd()` |
 | `--format <mode>` | Output format: `human`, `json`, `ndjson`, `json-summary`, `ndjson-summary` | `human` |
 | `--color <mode>` | Color mode: `auto`, `always`, `never` | `auto` |
 | `--quiet` | Suppress non-error output | false |
 | `--verbose` | Enable verbose logging | false |
-| `--artifact-dir <path>` | Directory for artifact output | `reports/apophis/` |
+| `--artifact-dir <path>` | Directory for artifact output. Artifacts written on failure or when explicitly configured. | `reports/apophis/` |
 | `--workspace` | Run supported commands across workspace packages | false |
 
+Note: `json-summary` and `ndjson-summary` are only supported by `verify` and `qualify` commands.
+
 ## Commands
 
 ### `apophis init`
@@ -37,8 +39,8 @@ apophis init --preset safe-ci
 
 | Flag | Description |
 |---|---|
-| `--preset <name>` | Preset name: `safe-ci`, `platform-observe`, `llm-safe`, `protocol-lab` |
-| `--force` | Overwrite existing files |
+| `-p, --preset <name>` | Preset name: `safe-ci`, `platform-observe`, `llm-safe`, `protocol-lab` |
+| `-f, --force` | Overwrite existing files |
 | `--noninteractive` | Skip all prompts, require explicit flags |
 
 **Examples:**
@@ -64,6 +66,7 @@ apophis verify --profile quick --routes "POST /users"
 | `--routes <filter>` | Route filter pattern (comma-separated, supports wildcards) |
 | `--seed <number>` | Deterministic seed (generated and printed if omitted) |
 | `--changed` | Filter to git-modified routes only |
+| `--workspace` | Run across all workspace packages |
 | `--format <mode>` | Output format: `human`, `json`, `ndjson`, `json-summary`, `ndjson-summary` |
 
 **Examples:**
@@ -171,6 +174,7 @@ apophis doctor [--mode verify|observe|qualify] [--strict]
 |---|---|
 | `--mode <mode>` | Filter checks to a specific mode |
 | `--strict` | Treat warnings as failures |
+| `--workspace` | Run across all workspace packages |
 
 **Checks:**
 
@@ -210,6 +214,31 @@ apophis migrate --dry-run
 apophis migrate --write
 ```
 
+## Common Tasks
+
+### CI workflow with machine output
+```bash
+apophis verify --profile ci --format json-summary --artifact-dir reports/apophis
+```
+
+### Monorepo workspace verification
+```bash
+apophis verify --workspace --profile quick
+apophis doctor --workspace
+```
+
+### Replay a failure
+```bash
+apophis replay --artifact reports/apophis/failure-*.json
+```
+
+## Gotchas
+
+- `--changed` requires a git repository
+- `migrate` defaults to `--dry-run` (safe by default)
+- `--workspace` is only supported by `verify` and `doctor` commands
+- Seeds ensure deterministic generation; handler nondeterminism (e.g., `Date.now()`) can still cause replay divergence
+
 ## Exit Codes
 
 | Code | Meaning |