Documentation Index
Fetch the complete documentation index at: https://na-36-merge-docs-v2-dev-draft-into-docs-v2-clean-20260525.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
Automations
The automation layer is the repo’s operating system. The repo is ownerless and self-governed – there is no single human responsible for keeping content fresh, links unbroken, navigation in sync, or generated artefacts aligned with their sources. The automation layer fills that role. It validates new contributions before they land, regenerates derived artefacts the moment a source changes, ingests live data from external services, repairs deterministic drift, and surfaces what it cannot fix as backlog.
This page documents what’s live as of 2026-05-23. The canonical published framework is at docs-guide/frameworks/github-actions.mdx (with the internal working spec at .github/workspace/framework-canonical.md).
The 4-tier composable architecture (D-GOV-08, 2026-05-22)
A major refactor on 2026-05-22 consolidated 53 standalone workflows → 11 active workflows under a 4-tier composable model. Workflow YAML files are dispatchers only; the typed work lives in scripts. The type classification comes from what the script does, not the workflow filename. Smoke test passing 66/66 dispatchers per framework-canonical.md Status line.
| Tier | Layer | What lives here | Count (2026-05-23) |
|---|
| 1 | .github/workflows/*.yml | Pure dispatchers (trigger + permissions + orchestration only) | 11 active (6 dispatch-{concern} + 5 interface-governance-*) |
| 2 | operations/scripts/dispatch/{concern}/ | Meta-dispatchers (per-mode entry: check / generate / scan / update / repair / sync) | 102 dispatcher scripts |
| 3 | operations/scripts/{type}/{concern}/{niche}/ | Atomic scripts (validator / generator / integrator / remediator / audit / interface) | 219 atomic scripts |
| 4 | tools/lib/ | Shared libraries imported by atomics (governance, copy-governance, docs, docs-usefulness, ai, bootstrap) | 6 lib subtrees |
.github/workspace/decisions-log.mdx.
The 11 active workflows
6 concern dispatchers (dispatch-{concern}.yml)
Each follows an identical 4-mode shape per D-ACT-08 + D-GOV-08:
- PR check (
pull_request) – dispatch-{concern}-check.js --staged
- Post-merge (
push to docs-v2) – dispatch-{concern}-generate.js --write (or -sync.js)
- Scheduled (cron) –
dispatch-{concern}-update.js or -scan.js with FLAGS pattern (⚠️ see §The cron-is-dry-run bug)
- Manual repair (
workflow_dispatch with mode=manual) – dispatch-{concern}-repair.js with FLAGS pattern
| File | Concern | Cron | Path filters (PR/push) |
|---|
dispatch-brand.yml | brand | Mon 06:30 UTC | v2/**/*.mdx, snippets/**/*.mdx, snippets/components/** |
dispatch-copy.yml | copy | daily 03:00 UTC | v2/**/*.mdx, snippets/data/** |
dispatch-discoverability.yml | discoverability | daily 04:00 UTC | v2/**, snippets/**, docs.json |
dispatch-governance.yml | governance | daily 07:00 UTC | .github/**, operations/scripts/**, docs-guide/**, tools/config/**, snippets/** |
dispatch-health.yml | health | daily 06:00 UTC | v2/**, snippets/**, content/scripts paths |
dispatch-maintenance.yml | maintenance | daily 05:00 UTC | snippets/components/**, snippets/data/**, docs.json |
dispatch-governance.yml has an additional fifth job: pipeline-tests runs operations/tests/integration/pipeline-smoke-test.js (66/66 dispatcher smoke test) + pipeline-functional-tests.js (synthetic violation cycles per D-GOV-03). dispatch-health.yml and dispatch-brand.yml open a PR on manual repair via peter-evans/create-pull-request@v7.
5 governance interfaces (interface-governance-*.yml)
| File | Trigger | What it does |
|---|
assign-reviewers.yml | pull_request (opened/reopened/ready/edited/labeled) | Codex PR eligibility gate; request Copilot reviewer; fallback assign via gh CLI |
close-linked-issues.yml | push to docs-v2 | Close issues linked to merged PRs |
index-issues.yml | issues events + cron every 6h | Rolling docs-v2 issue index (marker-based discovery, single canonical index issue) |
intake-discord-issues.yml | repository_dispatch (type: discord-issue-intake) | Discord webhook → GitHub issue conversion |
label-issues.yml | issues events | Auto-label new issues by parsed body headings (area:* + priority:*) |
# pipeline: P7 in their header comment – distinct from the P2-P6 dispatcher taxonomy.
Pipeline patterns (A–G)
Every pipeline follows one of these shapes. Source: .github/workspace/framework-canonical.md.
| Pattern | Trigger | Flow | Example |
|---|
| A – Integrate | cron / dispatch / manual | Fetch external API → transform → diff → commit + push → on failure create issue | contracts addresses; exchanges data; social feeds |
| B – Generate | push to deploy branch / manual | Read repo data → generate output → diff → commit + push | catalogs; component registry; docs-index; llms files; AI sitemap |
| C – Check | pull_request / push | Run validator(s) → report pass/fail → P2 block or P3 advise | docs-quality; OpenAPI reference audit; link health |
| D – Scan, Report, Act | cron / manual | Scan → report → route findings (auto-remediate / create issue / re-dispatch). “No headless scans – every finding gets a response.” | content-quality scheduled scan + manual repair pair |
| E – Repair | cron / manual | Scan for drift → fix → commit or PR | brand sweep; styles sweep |
| F, G | – | reserved; see framework canonical for full spec | – |
--check rerun.
Operations scripts taxonomy
321 active scripts under operations/scripts/, 38 in archive. Every script declares @type / @concern / @niche via an 11-tag JSDoc header.
| Type | Live count | Purpose |
|---|
dispatch | 102 | Meta-dispatchers + per-concern entries (-check, -update, -scan, -generate, -repair, -sync) per D-ACT-08 |
integrators | 58 | Pull/transform external + internal data into repo |
validators | 55 | Exit-code checks for hooks, CI, manual validation |
remediators | 37 | Deterministic repairs to existing files |
generators | 31 | Produce derived files from canonical sources |
audits | 25 | Read-only scans and reports |
interfaces | 8 | Issue/PR/Discord event handlers |
archive + x-archive | 38 | Deprecated or legacy scripts retained for review/compatibility |
- 327 of 321 active scripts have
@purpose (canonical) – basically 100%
- 81% have
@type, 81% have @concern (sampled 100)
- 45 scripts repo-wide still use retired
@category
- 4 scripts use retired
@domain
- The retired tags (
@category, @domain, @needs, @purpose-statement, @owner) are explicitly banned per docs-guide/policies/script-governance.mdx lines 195-205
The previously documented “218 non-compliant scripts” figure (from gap-analysis.mdx as of 2026-05-14) is stale. Actual non-compliance as of 2026-05-23 is ~45-50 scripts with retired tags – a 4× improvement from the documented baseline.
Hook pipeline (.githooks/)
5 active hooks + 4 docs + 4 utility files in .githooks/. Hard gates run on every commit, scoped to a 60-second runtime budget.
| Hook | What it enforces |
|---|
pre-commit | MDX syntax; docs.json redirect integrity; no-deletion guard; .allowlist + v1/ protection; Codex branch isolation. 22.8 KB; the entry-point. |
pre-push | Codex codex/* branch contract; lock overlap; AI-stash policy; non-fast-forward push guard |
pre-commit-no-deletions | Deletion guard (alternative variant – wiring status unclear; flagged in SLICE-03 as dead code) |
install.sh | Wires .git/hooks/pre-commit → .githooks/pre-commit |
verify.sh | One-shot verification runner (7 internal checks: MDX, JSON, JS, shell, mintlify, snippets-import, browser); orphan in pre-commit per SLICE-03 – defined but not invoked |
.githooks/BYPASS.md. Pre-commit has an undocumented carve-out: allows deletion without --trailer "allow-deletions=true" if the blob hash matches a v2/x-archived/ follow-up.
Gate layers
| Layer | Belongs here | Does not belong here |
|---|
| Pre-commit | Fast staged checks; generated artefact drift checks; root structure guardrails; v1 frozen-file guard | Browser sweeps; network calls; long full-site audits |
| Pre-push | Codex branch contract; lock checks; issue readiness; branch safety | Style checks already handled by pre-commit or PR CI |
| PR CI | Changed-file quality; docs-index; OpenAPI references; component + governance checks | Local-only setup checks |
| Scheduled CI | Broad freshness; links; page integrity; data refresh; advisory scans | Mutating source files without deterministic PR or repair path |
| Manual dispatch | One-off migrations; approvals; repair waves; large data updates | Routine drift that should be covered by a gate |
Ownerless automation contract
Each production automation must declare (per docs-guide/policies/ownerless-governance.mdx):
| Requirement | Implementation target |
|---|
| Canonical source | Policy, config, source data, docs tree, or workflow definition that owns truth |
| Validator | Local or CI command that fails deterministically when drift exists |
| Repair command | Exact command or workflow that restores derived state |
| Primary gate | One layer only (pre-commit / PR / scheduled / manual) |
| Output contract | Where reports, generated files, or PR comments are written |
| Retention policy | Whether outputs are committed, archived, summarised, or purged |
operations/governance/config/repo-governance-surfaces.json with 5 unified surfaces, 4 ownerless-ready, 1 advisory (github-workspace-governance). The file’s bridge_mode is "retired" and legacy_bridge_inventory is empty – migration complete. The legacy 8-entry ownerless-governance-surfaces.json remains on disk for reference but is superseded.
Locked decisions (18)
10 D-ACT decisions + 8 D-GOV decisions, split across two logs by date:
| ID | What it locks |
|---|
| D-ACT-01 | interface is a 7th type (issue/PR event handlers – not a subtype of automation) |
| D-ACT-02 | P5-auto is a distinct pipeline tag from P5 (scheduled writes vs scheduled read-only) |
| D-ACT-03 | 7 social-data workflows consolidate into 1 matrix update-social-feeds.yml |
| D-ACT-04 | Workflow naming type-concern-function-name.yml with closed-enum 11 function verbs |
| D-ACT-05 | Concern taxonomy expanded from 4 to 7 (integrations, copy, maintenance, health, discoverability, governance, brand) |
| D-ACT-06 | Migrate .github/scripts/ into operations/scripts/ governance – .github/scripts/ is intentionally empty as a result |
| D-ACT-07 | Rename automation type to integrator (script + workflow side) |
| D-ACT-08 | Workflows are dispatchers; type reflects the script. No inline logic in YAML |
| D-ACT-09 | Pipeline output locations (per type/concern) |
| D-ACT-10 | Unified governance registry replaces ownerless-governance-surfaces.json (single source of truth) |
| D-GOV-01 | Governance is enforcement infrastructure, not content rules |
| D-GOV-02 | Categories are enforcement layers, not surfaces (pre-commit, PR, post-merge, scheduled, self-heal, hooks, lifecycle) |
| D-GOV-03 | Every detection must self-repair or escalate (auto-fix > PR > issue > block) |
| D-GOV-04 | Tooling makes correct the default (templates, scaffolding, IDE snippets) |
| D-GOV-05 | Advisory before hard gate (P3 first, promote to P2 after baseline clean) |
| D-GOV-06 | Align script framework to actions framework (7 types, 7 concerns) |
| D-GOV-07 | Every workflow dispatcher must have a local CLI equivalent |
| D-GOV-08 | Every folder is governed. No commit of files that do not belong |
integrations, copy, maintenance, health, discoverability, governance, brand.
Type taxonomy (7): integrator, generator, validator, audit, remediator, dispatch, interface.
Recently shipped (May 2026)
Veracity dispatcher tranche
Three new dispatchers under operations/scripts/dispatch/content/veracity/ (type dispatch, concern health, niche veracity) close the long-standing “veracity-pass DRAFT blocks Phase 6” gap noted in the Checks Framework:
| Script | Pipeline | Purpose |
|---|
docs-research-packet.js | manual packet generator | Generic engine: derives nav/manifest/path scope, runs the research stack tranche-by-tranche, writes reusable packet reports + master rollup |
orchestrator-guides-research-review.js | manual wrapper | Delegates to docs-research-packet.js with live Orchestrators Guides nav scope and legacy output root |
docs-page-research-pr-report.js | manual, experimental advisory PR integration, non-blocking | Runs fact-check research runner on changed docs pages; emits PR artefact summarising claim families, contradictions, unresolved factual risk, propagation follow-up |
workspace/research/claims/ + workspace/reports/. Unit-tested under operations/tests/unit/.
Local social-feed dispatcher
operations/scripts/dispatch/content/data/run-solutions-social-fetch.js (type dispatch, concern integrations, niche social-feeds) mirrors dispatch-social-feeds.yml for local workstation use: loads .env, supports --mode forum,youtube, --dry-run, --skip discord. Iterates the 7 fetchers under operations/scripts/integrators/copy/social-feeds/. Local-only, not in any GitHub Actions workflow (a deliberate contributor tool, not a duplicate CI surface). Closes the gap where contributors couldn’t fetch live forum/discord/blog/YouTube/GitHub data on their workstation before pushing snippets that depended on freshly-generated outputs.
Known gaps
Cron-is-dry-run-by-default bug – FIXED 2026-05-25
Status: Fixed in commit e42946cdf on docs-v2-dev-draft. Pending merge to docs-v2.
Every dispatch-{concern}.yml scheduled job previously had this pattern:
- name: {concern} scheduled meta
run: |
FLAGS=""
if [[ "${{ inputs.dry_run }}" == "false" ]]; then FLAGS="--write --verify"; fi
node operations/scripts/dispatch/.../dispatch-{concern}-update.js $FLAGS
schedule event did not pass inputs.dry_run – it was empty, never the literal string "false". So FLAGS stayed empty and the script ran with no --write --verify. Cron physically could not trigger the write mode. Only workflow_dispatch with explicit dry_run: false actually wrote.
Net effect (pre-fix): the entire daily cron schedule was check-only theatre. Root cause of:
- Contract addresses last written 2026-05-04 (19 days stale on 2026-05-23) despite
_health-checks.json confirming the pipeline ran daily
llms.txt + sitemap-ai.xml 47 days stale (no manual dispatch with dry_run: false)generate-og-images.js + generate-seo.js classified “manual-only” in 2026-03-30 P0 flag – they’re CI-wired but cron defaulted to dry-run
Fix shipped: inverted FLAGS default in all 6 dispatch-{concern}.yml (FLAGS="--write --verify"; if ... == "true" then FLAGS=""). Manual-repair jobs deliberately unchanged (safe-by-default for human-triggered repairs). Post-merge jobs unaffected (already hardcode --write).
Archive sprawl
Three archive lanes in .github/:
.github/workflows/deprecated/ (1 file: update-blog-data.yml).github/workflows/x-archive/ (61 files: 56 .archived + 5 non-.archived).github/x-archive/ (separate at .github root, contents not enumerated)
The script-framework declares one lane (x-archive/). Plus operations/scripts/archive/ and operations/scripts/x-archive/ – two more for scripts.
Path drift from pre-refactor docs
.github/scripts/ is intentionally empty per D-ACT-06 (migration locked 2026-04-04). Stale references in older docs need updating:
- Contracts pipeline doc references
.github/scripts/fetch-contract-addresses.js. Current path: operations/scripts/integrators/maintenance/contracts/fetch-contract-addresses.js.
agent-governance-framework.mdx lines 137 + 228 reference validators/governance/check-agent-docs-freshness.js; actual path is validators/governance/compliance/check-agent-docs-freshness.js (missing /compliance/ subfolder). AGENTS.md line 98 has the right path.
Published framework lags the 2026-05-22 refactor
.github/workspace/framework-canonical.md says: “Canonical published framework: docs-guide/frameworks/github-actions.mdx – read that first.” But the published framework likely predates the 2026-05-22 refactor. Sync state undocumented.
Stale governance map
node operations/scripts/generators/governance/reports/generate-repo-governance-status.js --check reports docs-guide/repo-ops/config/repo-governance-map.mdx is stale. Self-detection works; auto-repair doesn’t run.
.githooks orphan + dead code
verify.sh is defined with 7 internal checks but not invoked by active pre-commit – dead enforcement (per SLICE-03)pre-commit-no-deletions is unwired dead code per its own JSDoc (@pipeline manual – not yet in pipeline).githooks/post-commit.disabled has NO JSDoc header at all.githooks/script-index.md only catalogues 3 of 7 hook scripts (generator filter broken)
actions-library/ per-action MDX catalogue not enumerated
.github/workspace/actions-library/{type}/{concern}/{niche}/*.mdx – one MDX file per atomic action. Mostly auto-generated from script JSDoc headers. Full enumeration not done; freshness vs source not verified.
Phase 4 workflow consolidation pending
framework-canonical.md Status line says “Phase 4 consolidation shipped” but Phase 6 (renames, inline-script extraction, consolidation) is explicitly noted as pending per the 2026-04-08 component-governance row in CLAUDE.md.
