docs: parity audit — sync all docs with v1.0.3 code state

[thomaschristory]

Documentation parity audit (post-v1.0.2 → v1.0.3 code state)

Executes the approved documentation-audit design spec (docs/superpowers/specs/2026-05-12-documentation-audit-design.md). Brings all hand-written user-facing and contributor docs into parity with the current code on main (952570f, version 1.0.3 in nsc/_version.py).

Method

1. Phase 1 — Ground-truth capture. Built a definitive, source-cited CLI inventory (meta-commands + flags, Config/Profile/Defaults, OutputFormat, SchemaRefresh, exit codes, env vars, bundled schemas) directly from nsc/ source. Surprising facts spot-verified against source.
2. Phase 2/3 — File-by-file audit + fix, in 6 batches, every change traced to a specific source fact. Conservative rule: a flagged uncertainty beats a wrong "fix". No restructuring, no style-only churn, auto-generated files untouched.

Notable corrections (things agents/users would have gotten wrong)

• nsc describe does not exist — was referenced ~10× across SKILL.md, using-with-ai-agents.md, working-with-plugins.md. Removed/replaced with nsc commands --schema … --output json.
• nsc commands requires --schema — examples that omitted it would fail. Fixed everywhere.
• replace (PUT-with-id) verb — a real registered verb (build.py:178, registration.py:66-68) that was missing from the verb lists; restored in concepts.md/SKILL.md, documented in command-generation.md.
• HTTP retry policy (safety-relevant) — http-client.md claimed "retries 5xx, 3 attempts". Writes are never retried on 5xx; corrected to the actual method-aware policy.
• Schema cache invalidation — docs implied per-invocation hash check + "regenerating…" notice. Corrected to the TTL fast-path: default policy is daily, freshness keyed off the <hash>.meta.json sidecar fetched_at, forced via --refresh-schema / nsc login --fetch-schema.
• nsc init is offline-safe — docs claimed it fetches the schema; it does not. Wizard prompt order corrected.
• nsc login — documented --fetch-schema and the post---new "Fetch and cache the live schema now?" auto-prompt (default yes); --rotate does not prompt/fetch.
• nsc skill export <dir> — newly documented in CHANGELOG/README/guides; clarified it writes <dir>/netbox-super-cli/SKILL.md and is dry-run unless --apply.
• Bundled schemas — corrected stale lists to 4.5.10 + 4.6.0 (4.6.0-beta2 dropped); offline fallback is the newest manifest entry, not a version match.
• nsc refresh / bundled-default sentinel — non-existent; removed.
• Misc: env vars are NSC_* only (no NETBOX_*); nsc cache only has prune; non-TTY output auto-switches to JSON; exit-code contract restated from source.

The CHANGELOG already carried a dated ## v1.0.3 section (from aa8fccf chore(release): 1.0.3); existing entries were refined for accuracy, none duplicated.

Verification

• uv run mkdocs build --strict — passes (no broken links / missing nav).
• Full test suite — 628 passed, 1 skipped (skip = NSC_BENCH benchmark gate).
• scripts/gen_docs.py re-run — no drift; auto-generated docs/reference/{cli,config,schemas,exit-codes}.md are current and were left untouched (they are all generated, not just cli.md/schemas.md).

⚠️ Documentation website deploy is NOT triggered by this merge

.github/workflows/docs.yml deploys GitHub Pages only on a v* tag push (if: github.ref_type == 'tag'); PR/docs/** runs are build-only (mkdocs build --strict). No v1.0.3 tag exists (tags stop at v1.0.2; main is v1.0.2-18-g…). So merging this PR makes the docs CI green but does not publish the live site. Publishing requires cutting the v1.0.3 release tag — a full release (also triggers PyPI publish via release.yml) — which was deliberately not done autonomously. Tag v1.0.3 when ready to release; the corrected docs will deploy then.

Scope

Out of scope per spec: CLAUDE.md, AGENTS.md, auto-generated reference pages, new pages/guides.

🤖 Generated with Claude Code

[thomaschristory]

Adversarial review completed (2 independent reviewers)

Two skeptical reviewers re-derived facts from source, ignoring the working ground-truth file (which itself had a known error). CI is green on all platforms.

Real issues found & fixed in 9ded6ab:

1. using-with-ai-agents.md — nsc commands --output json missing required --schema (the one spot the audit missed; fixed everywhere else).
2. SKILL.md + writes-and-safety.md — malformed single JSON/YAML input is client/exit 6, not input_error/exit 4; only a bad NDJSON/JSONL line is exit 4 (handlers.py:321 vs :329).
3. SKILL.md — invented 2 usage/bootstrap inside the typed scripting contract; no such code/type in errors.py:EXIT_CODES and it contradicted generated exit-codes.md. Footnoted code 2 instead.
4. ci-and-automation.md — --max-age prune does remove aged adhoc files (no guard in store.py:_find_aged_files); only the default prune spares adhoc.

Verified clean: scope (no auto-gen/CLAUDE.md/AGENTS.md edits), cross-file consistency (replace verb, TTL/daily, skill-export path, env namespace), all spec success criteria, mkdocs build --strict, 628 tests.

Note: concepts.md nets to a zero diff (a wrong batch-2 removal of the replace line, corrected in 7747dc2); harmless under squash-merge.

⚠️ Reminder: docs Pages deploy is v*-tag-gated; no v1.0.3 tag exists. Merging makes CI green but does not publish the live site — cut v1.0.3 to deploy (also triggers PyPI release).