docs: align AI-facing discovery surfaces after architecture vNext

[garagon]

Summary

The 2026-05-11 Architecture vNext fresh retest spec confirmed the round is functionally closed on main (PRs #209-#215, all seven contracts retested green) and surfaced three P2 documentation drifts as a follow-up. This PR resolves all three and adds a lint lock per finding so the drift cannot return.

What changes

Finding 1 — Telemetry doc path. llms.txt and bin/about.sh --print pointed agents at reference/telemetry.md, a file that does not exist. The canonical file the READMEs already linked to is TELEMETRY.md. Both surfaces now point at TELEMETRY.md.

Finding 2 — AGENTS.md inventory. AGENTS.md claimed to list every shipped skill but the table only had eight entries (think, nano, review, qa, security, ship, guard, conductor). The README sells 13 built-in skills. Took Option A from the retest spec (complete inventory) and grouped the table into three sections:

• Default sprint: think, nano, review, qa, security, ship, compound.
• Orchestration and safety: guard, conductor.
• Onboarding and entry points: feature, nano-run, nano-help, nano-doctor.

Finding 3 — README reflects Architecture vNext guarantees. README.md mentioned auto-saved artifacts and the resolver but did not reflect the contracts the retest just proved. Tightened three existing sections in place (no marketing churn, no banned public-copy claims):

• Artifacts section now mentions the SHA-256 integrity field, bin/find-artifact.sh --require-integrity for strict consumers, and the schema_legacy: true marker on legacy --from-session artifacts.
• Resolver section now mentions upstream_status (verified / integrity_missing / integrity_mismatch / missing) and the phase_context block that lets custom skills declare trust: strict, max_age_days, required vs optional upstreams, and tagged solution / diarization lookup. The applied context comes back in routing so consumers see what the resolver did.
• Write/Edit guard section now mentions the credential JSON basenames the write hook blocks (credentials.json, secrets.json, service-account*.json, firebase-adminsdk*.json, google-credentials*.json, aws-credentials*.json) and the safe-template exception (.env.example, credentials.example.json, service-account.template.json). Match is case-insensitive and mirrors the read-side G-035 rule.

Lint. New architecture-vnext-doc-locks job with three steps:

1. reference/telemetry.md does not appear in any AI-facing surface, and llms.txt + bin/about.sh both contain TELEMETRY.md.
2. AGENTS.md mentions compound, feature, nano-run, nano-help, and a doctor variant.
3. README.md mentions --require-integrity, phase_context, upstream_status, at least one credential JSON name, and at least one safe-template shape.

Each lock was sabotage-tested locally:

• Reintroducing reference/telemetry.md → caught.
• Deleting compound from AGENTS.md → caught.
• Stripping --require-integrity from README → caught.

What does not change

• No runtime behavior changes. This is documentation plus lint locks only.
• All existing E2E suites pass without modification: user-flows (100), custom-stack-flows (40), custom-stack-examples (51), graph-aware-session (61), custom-routing (35), adapter-freshness (43), artifact-trust (29), structured-artifacts (31), think-flows (32), think-archetypes (25), onboarding-flows (34), delivery-matrix (17), examples (40), plus tests/run.sh (83) and tests/e2e-user-flows.sh (5).
• No banned public-copy claims reintroduced (no marketplace / certification / always-on E2E / unsupported adapter language).
• README.es.md is not modified in this PR — the retest spec scopes Finding 3 to README.md, and Finding 1's acceptance was met by the English-side fix (Spanish README already linked TELEMETRY.md correctly).

Codex review

Single pass clean: "The changes are documentation and CI lock additions that are syntactically valid and consistent with the referenced files. I did not find a discrete introduced issue that would break existing behavior or tests."

Spec

Follow-up to the 2026-05-11 Architecture vNext fresh retest. Closes the three P2 documentation findings in that spec:

• Broken telemetry doc link in AI-facing surfaces.
• AGENTS.md is not a complete built-in skill inventory.
• README reflects the product shift but not the full Architecture vNext guarantees.

Architecture vNext itself (PRs #209-#215) stays closed.

Test plan

• .github/workflows/lint.yml architecture-vnext-doc-locks job passes on CI.
• bin/about.sh --print | grep TELEMETRY.md finds the corrected path.
• grep -nF 'reference/telemetry.md' llms.txt bin/about.sh AGENTS.md README.md README.es.md returns nothing.
• All existing E2E and lint suites still pass.
• Sabotage check (manual): re-introduce reference/telemetry.md in llms.txt and confirm the new lock fails CI.