[Ecosystem 13][HITL] Approve and roll out the public README and package documentation profiles

[EmersonBraun]

Parent PRD

#1198

Slice type

HITL

What to build

Define testable README profiles for top-level repositories, public apps, major packages, and concise packages, prove the profile on AgentsKit, and coordinate repository-specific rollout tickets without replacing accurate product knowledge with cosmetic templates.

Acceptance criteria

• Profiles define required promise, proof, examples, visuals, maturity, compatibility, contribution, metadata, and contextual ecosystem relationships.
• Visual requirements allow documented exceptions when an image adds no understanding.
• Badge, image, accessibility, dark-mode, command-verification, and freshness budgets are explicit.
• The AgentsKit top-level README passes the profile with verified examples.
• A deterministic gate reports applicable profile, failures, and exceptions.
• Repository-specific rollout work is independently trackable.
• HITL approval locks README Standard v1 before broad rollout.

Blocked by

• Blocked by [Ecosystem 01][AFK] Publish the canonical ecosystem manifest and verifiable claims #1200
• Blocked by [Ecosystem 02][HITL] Ship Documentation Standard v1 as an executable Doc Bridge conformance gate doc-bridge#27
• Blocked by [Ecosystem 03][HITL] Make AgentsKit the reference Fumadocs brand and documentation vertical #1201

User stories addressed

• User story 5
• User story 8
• User story 9
• User story 29
• User story 30
• User story 31

Required delivery evidence

• Architecture impact and upstream-adoption record completed where applicable.
• QA plan posted before implementation.
• Repository-specific checks and documentation gates pass.
• Pull request links back to this issue and the parent PRD.

[EmersonBraun]

Architecture, QA plan, and HITL lock record

The product owner explicitly approved continuing to the complete professional outcome on 2026-07-13. This records that approval for README Standard v1 with the rule set below; rollout remains repository-specific and evidence-driven.

Data-first architecture

• Add one versioned README Standard v1 manifest defining four profiles: top-level repository, public app, major package, and concise package.
• Keep applicability explicit per surface; the gate never guesses package importance from prose.
• Add one deterministic local gate that reports profile, every failure, verified evidence, and approved exceptions without network, model, or API key.
• Dogfood the top-level repository profile on README.md. Examples and commands link to committed executable evidence rather than being trusted because they look plausible.
• Reuse ecosystem.json, ecosystem-claims.json, docs/STABILITY.md, CONTRIBUTING.md, and Doc Bridge outputs as canonical knowledge. Do not copy product facts into an opaque template.
• No runtime or public package contract changes; this is repository governance and documentation infrastructure.

Locked profile requirements

Every applicable profile declares requirements for:

1. promise and intended user;
2. proof linked to canonical evidence;
3. copy-ready install/usage examples;
4. visual explanation or a documented no-image exception;
5. maturity and stability disclosure;
6. runtime/package compatibility;
7. contribution and license paths;
8. discoverability metadata/tags;
9. contextual ecosystem relationships.

Locked budgets

• Badges: repository <= 12, public app <= 8, major package <= 8, concise package <= 6.
• Images: repository 1–6, public app 1–5, major package 1–4, concise package 0–2. Zero images requires an approved exception explaining why an image adds no understanding.
• Accessibility: zero missing/empty alt text; decorative images must be explicitly marked; local visual evidence must resolve.
• Dark mode: every explanatory image declares a dark-safe strategy or paired light/dark assets.
• Commands/examples: zero unverified primary commands and zero unlinked primary examples.
• Freshness: source-hash invalidation is immediate; review cadence is 90 days for repositories/apps, 120 days for major packages, and 180 days for concise packages.

An exception is valid only with rule ID, surface, reason, approver, tracking URL, and expiry/review date. The report says excepted rather than silently passing.

AgentsKit proof slice

• Replace stale hand-maintained top-level counts with current verified ledger values or conservative claims linked to evidence.
• Make promise, proof, maturity, compatibility, contribution, tags, and ecosystem journey explicit.
• Bind README commands/examples to a clean deterministic fixture and test command.
• Keep the existing meaningful brand/demo/architecture visuals; declare their accessibility and dark-mode treatment.

QA plan

• Schema/config: version, profile IDs, budgets, surface applicability, exception completeness, deterministic ordering.
• Gate pass: AgentsKit root reports its profile and all required dimensions with evidence.
• Gate fail fixtures: missing promise, proof, example, visual, maturity, compatibility, contribution, metadata, ecosystem link, inaccessible image, excessive badges/images, unverified command, stale hash, and invalid exception.
• Command/example proof: clean fixture executes without credentials or network; README snippet remains byte-synchronized with its fixture.
• Output: stable JSON and human-readable text include profile, evidence paths, failures, remediation, and exceptions; required failures exit 1.
• Regression: current badge, ecosystem, Doc Bridge, MDX, link, build, lint, unit, and E2E gates remain green.
• Rollout: one independently trackable issue per ecosystem repository/surface, each referencing the locked standard and retaining repository-specific context.

Implementation starts only after this posted plan. Broad rollout PRs remain separate from the standard/proof PR.