Merge branch 'jeffhorn/agent-contributor-docs' into contribution-workflow-skills

Bring #5 onto the rewritten #4 (AGENTS.md trimmed, Architecture and CI moved to
path-scoped .claude/rules/). Resolved the AGENTS.md conflict by taking #4's
restructured file and re-applying #5's additions: the create-pr and create-issue
skill references and the no-hard-wrap formatting note. Those references are valid
here because #5 provides both skills.

Author: jeffhorn-nava

.claude/rules/architecture.md

@@ -0,0 +1,77 @@
+---
+paths:
+  - "scripts/**"
+  - "tests/**"
+  - "sources.md"
+  - "skills/generate-strata-docs/**"
+  - "docs/**"
+  - "docs/.verification/**"
+  - "docs/.curation/**"
+---
+
+# Architecture
+
+Reference for the documentation pipeline, auto-loaded by Claude Code when you edit the scripts, the
+`generate-strata-docs` skill, the manifest, or anything under `docs/`. Always-on orientation and the
+command list live in `AGENTS.md`.
+
+**The manifest drives everything.** `sources.md` is a markdown table (one row per source: `id`,
+`type`, `repo`, `ref`, `subpaths`, `notes`). A source's `type` selects a profile in
+`skills/generate-strata-docs/references/profiles/<type>.md` telling the documenter how to treat that
+repo. `lint_manifest` rejects a `type` with no matching profile, so a new source type needs both a
+manifest row and a profile file.
+
+**Skill orchestration:**
+
+```
+Setup (clone to .sources/) → Run 1 DOCUMENT → build graph
+  → Run 2 VERIFY→ADJUDICATE→FIX (per doc) → rebuild graph → CURATE → report
+```
+
+- **Run 1** (`workflows/run-1-document.mjs`): one `general-purpose` agent per source in parallel,
+  each reading `skills/generate-strata-docs/references/agents/source-doc.md` + its profile + the
+  registries, then writing docs to `docs/sources/<id>/` and a distillation log to
+  `.logs/<id>.distillation.md`.
+- **Run 2** (`workflows/run-2-verify-fix.mjs`): per doc, a bounded verify → adjudicate → fix loop
+  (`max_rounds`, default 2); residual findings mark the doc `verified: needs-review`, audit trail in
+  `docs/.verification/`. Agent role specs live under `skills/generate-strata-docs/references/agents/`.
+- The skill commits to `Workflow` with no fallback: if unavailable it stops and escalates. Subagents
+  never talk to the user.
+- **full** mode documents every source; **update** mode only new + changed (`scripts/source_delta.py`),
+  detecting drift by the clone's resolved SHA vs the `source_ref.ref` in existing docs and throttling
+  re-documentation until a drifted source's docs are a week old.
+
+**Frontmatter is the single source of truth for the graph.** Every doc under `docs/sources/<id>/`
+starts with YAML frontmatter (contract:
+`skills/generate-strata-docs/references/doc-frontmatter-schema.md`). `build_graph.py` derives
+`docs/INDEX.md` and `docs/graph.json` purely from it; never edit those two by hand.
+
+Two cross-link axes, both resolved through registries (fenced kebab-case key lists the linter parses):
+
+- **Feature axis** (`skills/generate-strata-docs/references/feature-keys.md`): an `sdk` doc owns a
+  key via `feature_keys`; an `example` doc uses it via `demonstrates`. The builder resolves each
+  `demonstrates` to the owning SDK doc and emits an `example-of` edge.
+- **Platform axis** (`skills/generate-strata-docs/references/platform-components.md`): a doc owns a
+  component id via `component_keys`; `platform-cli` docs declare `manages`, app/infra docs declare
+  `integrates_with`, both resolved to the owning doc.
+
+`lint_docs` hard-fails on any `feature_keys`/`demonstrates`/`component_keys`/`manages`/
+`integrates_with` value not in its registry. Add the key to the registry before writing any doc that
+references it.
+
+**"Never silently drop" invariant.** The pipeline surfaces every gap rather than hiding it. When
+editing the graph builder, linter, or delta classifier, emit a visible record rather than discarding:
+
+- Clone failure: source recorded **skipped**, not dropped.
+- Registry-valid key with no owning doc: `build_graph` prints a `GAP:` line.
+- Unresolved findings: doc marked `verified: needs-review`.
+- Source removed from `sources.md` with docs still present: `source_delta` reports **orphaned**.
+- Drifted source documented under a week ago: `source_delta` reports **throttled**.
+
+## Conventions
+
+- `docs/.verification/` and `docs/.curation/` are audit trail. Keep them.
+- `scripts/frontmatter.py` is the shared YAML parser for linter and graph builder. Change it in one
+  place.
+- The design spec and plan live in `docs/superpowers/{specs,plans}/`; section references like `§3.3`
+  in code and the skill point back to that spec.

.claude/rules/ci.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - ".github/workflows/**"
+  - "docs/**"
+---
+
+# CI
+
+Auto-loaded by Claude Code when you edit a workflow or regenerate the graph. Always-on orientation
+lives in `AGENTS.md`.
+
+- **lint.yml**: pytest → lint_manifest → lint_docs → graph freshness (`build_graph` then
+  `git diff --exit-code` on `docs/INDEX.md` + `docs/graph.json`). Commit regenerated
+  `INDEX.md`/`graph.json` whenever doc frontmatter changes or CI fails.
+- **generate-docs.yml** / **update-docs.yml**: manual only; full-mode and update-mode skill runs
+  opening PRs on `docs/full-regen` / `docs/auto-update`. Both need `ANTHROPIC_API_KEY` and
+  `SOURCES_READ_TOKEN` secrets.