docs: add public architecture handbook

[sumitake]

Summary

Add a sanitized, indexed public architecture handbook and refocus the root README on general users. The handbook now explains the package mental model, capabilities, governance and family-independence controls, sealed authorities, installation and operations, repository/release structure, and the evidence states that separate source, tags, releases, installed packages, and active routes.

The documentation is deliberately layered and human-first. It gives users complete lifecycle guidance but does not publish a single turnkey executor specification, raw provider recipes, private producer internals, operator paths, host identities, or secret-bearing discovery commands.

This change also:

• adds a design-evidence registry so historical and superseded reviews are not read as current contracts;
• removes duplicated low-level material from the landing page while preserving the package technical reference;
• corrects stale statements about the committed activation artifact, signing-policy anchor, package version, and schema-3/contract-3 manifest;
• advances the public package to 4.9.1 with regenerated marketplaces and 50 generated skill headers; and
• adds the required fragment without editing the release-generated CHANGELOG.md.

Boundary declaration

• No provider executor source, raw provider command, credential, private absolute path, retired package tree, downloader, or post-install hook is included.
• Native-runtime changes, if any, contain only a final signed artifact and reviewed public verification metadata; implementation and credentials remain private. (No native artifact bytes changed.)
• The change does not create a host-specific preset or provider-specific plugin.

Generated and release surfaces

• Skill specs and generated SKILL.md files are in parity.
• Claude and Codex marketplaces/manifests are in parity.
• A unique changelog.d/2026-08-06-public-architecture-handbook.md fragment is present; generated CHANGELOG.md is unchanged.
• All seven 4.9.1 version surfaces moved together and release consistency passes against origin/main 4.9.0.

Verification

• python3 scripts/build_skills.py --check — 50 generated skills match.
• python3 scripts/build_marketplace.py --check — both marketplace views match.
• python3 scripts/build-changelog.py --dry-run — preview succeeds; --check is release-PR-only under the fragment-only convention and correctly reports the uncompiled fragments.
• python3 -m unittest discover -s tests -t . -v — 660 tests, OK.
• python3 -m unittest discover -s scripts -p 'test_*.py' -v — 333 tests, OK.
• python3 scripts/check_release_consistency.py --against-ref origin/main — RESULT: OK.
• python3 scripts/secret_scan.py — 369 source text files, clean.
• python3 scripts/check-public-export-safety.py --active-tree — SAFE in the publication worktree.
• python3 scripts/check-public-export-safety.py --active-tree --history — the linked clone retains pre-sanitization lineage and correctly fails history mode; no output from that scan is reproduced here. A disposable full clone of the canonical remote at publication HEAD 11caf3f29271b34c597665f313d942b3025d2a9e, origin/main 465c70ecfe7672be53c9624907a363775c2f9eb9, all fetched remote heads, and tags through v4.6.0 returned RESULT: SAFE FOR REQUESTED PUBLIC EXPORT CHECKS.
• Local Markdown link/anchor checker — 14 entry-point and handbook files, all local targets and anchors resolve.
• git diff --check — clean.
• GitHub commit verification — signature valid and verified for 11caf3f29271b34c597665f313d942b3025d2a9e.

Review and post-condition

Tier 2: user-visible distributed documentation and compatible metadata corrections.

Two exact-head governance calls exposed a verdict-adapter mismatch: both used native repository reads, found zero material issues, and said PROCEED in their review prose, while the closed field remained NEEDS_DISCUSSION. They are recorded as non-converged and do not supply approval.

The accepted Tier-2 path is the independent review.repository contract. It inspected the unchanged exact head through a provider-neutral receipt with Google-family lineage distinct from the OpenAI author, read the README, handbook, governance, design registry, changelog, and host manifests natively, and returned zero actionable findings with NO_FINDINGS_VERIFIED. Primary verification of that closed no-findings artifact plus the deterministic gates above yields the final operative verdict: PROCEED.

Post-merge: fetch and verify origin/main contains the merged handbook and 4.9.1 surfaces; verify the merge workflow conclusion. No release or tag is expected from a documentation PR merge alone. Merge only after required checks are green, review threads are resolved, compliance is merge-eligible, and without --admin.

Compliance trace

author: Codex (OpenAI) on behalf of @sumitake
standing_directives: AGENTS.md source and validation boundaries; docs/public-governance.md; signed-commit, exact-head review, clean-history comparison, normal-merge, and no-admin-bypass requirements
tier: 2
cross_check: rounds 1-2 governance adapter recorded NEEDS_DISCUSSION despite zero findings and were excluded; final exact-head review.repository used independent Google-family native reads and a provider-neutral receipt, returned 0 findings and NO_FINDINGS_VERIFIED; primary synthesis PROCEED
post_condition: required CI green; threads resolved; normal squash merge without admin bypass; origin/main and merge automation verified; no release expected without a signed tag
mcp_coverage_gap: NONE
contributor_rights: OWNER-AUTHORED
operator_reserved: no