docs(wikis): scaffold audience-split education layer (Users/Developers/Maintainers) (#398)

hyperpolymath · claude · web-flow · commit 09e7023d2468 · 2026-06-21T20:28:08.000+01:00
## What Adds `docs/wikis/` — a long-form, **audience-segmented education layer** for `standards`, deeper than the `QUICKSTART-*.adoc` setup guides. Follow-up to the #397 close-out (the staleness work), addressing the gap that `standards` had **no education layer beyond quickstart and no wiki mirror**. Follows the estate pattern already used in `k9-svc/*/docs/wikis/` (audience split + machine manifest). ## Contents - `docs/wikis/README.adoc` — wiki home + audience routing + format/sync rules. - `docs/wikis/{users,developers,maintainers}/index.adoc` — three learning paths. Each is a **complete link spine** into the canonical docs (README, EXPLAINME, CLAUDE.md, the ADRs, the policies, the registry) with explicit `TODO` markers where prose still needs writing — an honest scaffold, not an empty stub. - `docs/wikis/0.2-AI-MANIFEST.a2ml` — machine mirror of the track (so it's in **both** human and machine docs). - `README.adoc` + `0-AI-MANIFEST.a2ml` — each gains an "education layer" front-door row. ## Audience split - **Users** — consuming/adopting the standards (reusable workflows incl. the pin-freshness window from ADR-003, A2ML, readiness grades). - **Developers** — building to the standards (language policy, A2ML/K9 authoring, Hypatia rules, the CI gates). - **Maintainers** — evolving the standards (registry generator, the licence Manual-Only guardrail, drift/staleness automation, the 6a2/contractile stack). ## Notes - Registry + topology stay in sync (`docs/` is not a spec home — verified). - SPDX from birth: `CC-BY-SA-4.0` for the `.adoc` docs (matching the existing docs), `MPL-2.0` for the `.a2ml` manifest. - Full per-track prose is intentionally deferred — tracked as a follow-up issue (the docs/wiki education audit). - The pre-existing estate-wide Hypatia checks (`governance` / `hypatia-scan`) are red on `main` independently of this PR; this change is docs-only. Kept **draft** pending review of structure/scope before the prose is written. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01BKyi8Bht8xdXyajpkaTdYP --- _Generated by [Claude Code](https://claude.ai/code/session_01BKyi8Bht8xdXyajpkaTdYP)_ Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/0-AI-MANIFEST.a2ml b/0-AI-MANIFEST.a2ml
@@ -29,6 +29,7 @@ content-addressed `source_hash`. Prose explanation: `REGISTRY.adoc`.
 | Drift / staleness automation | `REGISTRY.adoc`, `hypatia-rules/` (HYP-S006); reusable-pin freshness: `docs/decisions/ADR-003-workflow-pin-staleness-window.adoc`, `scripts/check-workflow-staleness.sh`, `scripts/propagate-workflow-pins.sh` |
 | Derived architecture map | `TOPOLOGY.md` (generated — do not edit) |
 | Current project state | `.machine_readable/6a2/STATE.a2ml` |
+| Education layer (deep docs, by audience) | `docs/wikis/` (Users / Developers / Maintainers); machine mirror `docs/wikis/0.2-AI-MANIFEST.a2ml` |
 
 ## CANONICAL LOCATIONS (UNIVERSAL RULE)
 
diff --git a/README.adoc b/README.adoc
@@ -61,6 +61,9 @@ Every other "what is this repo" doc is now a thin pointer back to these two
 
 | To **stand up a new repo** to these standards
 | link:A2ML-REPO-TEMPLATE.adoc[A2ML-REPO-TEMPLATE.adoc] + <<Usage>>
+
+| The **education layer** — audience-split deep docs (beyond quickstart)
+| link:docs/wikis/[docs/wikis/] — link:docs/wikis/users/index.adoc[Users] · link:docs/wikis/developers/index.adoc[Developers] · link:docs/wikis/maintainers/index.adoc[Maintainers]
 |===
 
 NOTE: link:.machine_readable/REGISTRY.a2ml[REGISTRY.a2ml] and
diff --git a/docs/wikis/0.2-AI-MANIFEST.a2ml b/docs/wikis/0.2-AI-MANIFEST.a2ml
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: MPL-2.0
+# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# Machine pointer for the standards education layer (the wiki track).
+# Human entry: docs/wikis/README.adoc. This file mirrors that structure so an
+# agent can route a "teach me X for audience Y" request without scraping prose.
+
+id: "wikis-track"
+status: "scaffold"
+version: "0.1.0"
+updated: "2026-06-21"
+
+description: >
+  Audience-segmented, long-form education layer for hyperpolymath/standards.
+  Deeper than the QUICKSTART-*.adoc files (which cover setup + basic run): the
+  wiki teaches the model, the why, and how to engage fully.
+
+format:
+  primary: "asciidoc"          # estate doc policy; no .md duplicates
+  source_of_truth: "in-repo"   # synced OUT to any forge wiki, never hand-edited there
+
+front_doors:
+  human: "README.adoc"
+  machine: "0-AI-MANIFEST.a2ml"
+  verifiable_index: ".machine_readable/REGISTRY.a2ml"
+
+tracks:
+  - audience: "users"
+    home: "docs/wikis/users/index.adoc"
+    quickstart: "QUICKSTART-USER.adoc"
+    for: "consuming / adopting the standards (reusable workflows, A2ML, grades)"
+  - audience: "developers"
+    home: "docs/wikis/developers/index.adoc"
+    quickstart: "QUICKSTART-DEV.adoc"
+    for: "building to the standards; authoring A2ML/K9; writing Hypatia rules"
+  - audience: "maintainers"
+    home: "docs/wikis/maintainers/index.adoc"
+    quickstart: "QUICKSTART-MAINTAINER.adoc"
+    for: "evolving the standards: registry generator, guardrails, drift automation"
+
+todo:
+  - "Flesh out per-track core-concept prose beyond the link spine"
+  - "Decide forge-wiki vs in-repo-only hosting"
+  - "Add glossary + per-track worked examples"
diff --git a/docs/wikis/README.adoc b/docs/wikis/README.adoc
@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath)
+= Standards Wiki — the education layer
+:toc:
+:toc-placement: preamble
+:status: Scaffold v0.1.0 (2026-06-21)
+
+This directory is the **long-form, audience-segmented education layer** for
+`hyperpolymath/standards`. It is deliberately *deeper* than the
+`QUICKSTART-*.adoc` files: those get you set up and running; these explain the
+*why*, the model, and how to engage with the materials fully.
+
+[IMPORTANT]
+====
+*Status: scaffold.* This is a starting skeleton (standards#docs-wiki-audit).
+Each track below has a structured learning path and links to the canonical
+sources, with `TODO` markers where prose still needs writing. It is honest
+about being incomplete — contributions fill the gaps, they do not start from
+zero.
+====
+
+== The two front doors (unchanged)
+
+The wiki does not replace the canonical front doors — it *teaches* them:
+
+* Human front door: `README.adoc`
+* Machine front door: `0-AI-MANIFEST.a2ml`
+* Verifiable index of every spec: `.machine_readable/REGISTRY.a2ml`
+
+== Tracks by audience
+
+[cols="1,3,1",options="header"]
+|===
+| Track | For whom | Start
+
+| link:users/index.adoc[Users]
+| People *consuming / adopting* the standards in their own repos — reusable
+  workflows, A2ML artefacts, the policies, the readiness grades.
+| link:../../QUICKSTART-USER.adoc[QUICKSTART-USER]
+
+| link:developers/index.adoc[Developers]
+| People *building to* the standards, or extending the tooling — language
+  policy, A2ML/K9 authoring, Hypatia rules, the CI gates.
+| link:../../QUICKSTART-DEV.adoc[QUICKSTART-DEV]
+
+| link:maintainers/index.adoc[Maintainers]
+| People *evolving* this repo — the registry generator, the guardrails, the
+  licence policy, the drift/staleness automation, the innervation stack.
+| link:../../QUICKSTART-MAINTAINER.adoc[QUICKSTART-MAINTAINER]
+|===
+
+== Format & sync rules
+
+* Primary format is **AsciiDoc (`.adoc`)** (estate doc policy; no `.md`
+  duplicates).
+* The machine mirror of this track is `0.2-AI-MANIFEST.a2ml` in this
+  directory — keep it in step when tracks are added.
+* If/when a forge-hosted wiki (GitHub/GitLab) is adopted, this directory is
+  the source of truth and is synced *out* to the forge, never hand-edited
+  there. (Mirrors the estate pattern in `k9-svc/*/docs/wikis/`.)
+
+== TODO (scaffold → complete)
+
+* [ ] Flesh out each track's "core concepts" prose beyond the link lists.
+* [ ] Decide forge-wiki vs in-repo-only hosting.
+* [ ] Add a "glossary" page (A2ML, K9, RSR, CRG, contractile, innervation, 6a2).
+* [ ] Add worked examples per track (adopt a repo / write a rule / cut a change).
diff --git a/docs/wikis/developers/index.adoc b/docs/wikis/developers/index.adoc
@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath)
+= Developers track — building to the standards
+:toc:
+:toc-placement: preamble
+:status: Scaffold v0.1.0 (2026-06-21)
+
+For developers writing repos, tools, or rules that must **comply with** and
+**extend** the standards. You author code/metadata that the gates will judge.
+
+NOTE: Scaffold. The link spine is complete; the connective prose is `TODO`.
+
+== Learning path
+
+=== 1. The language policy (read first)
+
+* `.claude/CLAUDE.md` (canonical) — allowed/banned languages, the AffineScript
+  stance, the carve-out tables (TS/ReScript/npm/JS exemptions).
+* TODO: "choosing a language for a new component" decision flow.
+
+=== 2. Build system
+
+* Mustfile / `justfile` (no Makefiles): https://github.com/hyperpolymath/mustfile
+* `Justfile` here — `just --list`; package mgmt via Guix → Nix → Deno.
+* TODO: "wire a new sub-project into the monorepo build/test".
+
+=== 3. Author the machine-readable metadata
+
+* A2ML family: `a2ml/`, the `*-a2ml/` homes, `a2ml-templates/`.
+* K9 self-validating components: `k9-svc/`, `k9-coordination-protocol/`.
+* TODO: "write a valid STATE/META set and pass Validate A2ML".
+
+=== 4. The protocols
+
+* `avow-protocol/`, `axel-protocol/`, `overlay-protocol/`,
+  `consent-aware-http/`, `0-ai-gatekeeper-protocol/`.
+* TODO: per-protocol "when would I implement this" summary.
+
+=== 5. Write & extend Hypatia rules
+
+* `hypatia-rules/` (e.g. HYP-S006 `registry-staleness`) — the estate-side
+  detection rules and the hybrid automation router (`:auto_execute` vs
+  `:review`, with licence findings capped to `:review`).
+* TODO: "anatomy of a rule + how to add one".
+
+=== 6. The CI gates (what blocks a bad change)
+
+* `.github/workflows/` + `hooks/`.
+* The workflow-pin staleness gate: `scripts/check-workflow-staleness.sh`
+  (recency window — link:../../decisions/ADR-003-workflow-pin-staleness-window.adoc[ADR-003]).
+* Registry/topology sync, language policy, no-JS, secret scanning, SPARK gate.
+* TODO: "decode a red gate and the fastest green path".
+
+=== 7. Reference
+
+* `QUICKSTART-DEV.adoc`, `llm-warmup-dev.md`, `CONTRIBUTING.md`,
+  `docs/decisions/` (ADRs), `docs/*-POLICY.adoc`.
diff --git a/docs/wikis/maintainers/index.adoc b/docs/wikis/maintainers/index.adoc
@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath)
+= Maintainers track — evolving the standards
+:toc:
+:toc-placement: preamble
+:status: Scaffold v0.1.0 (2026-06-21)
+
+For maintainers of **this repo** — the people who change the standards, run
+the generators, and uphold the guardrails. Highest blast radius; read the
+guardrails before touching anything.
+
+NOTE: Scaffold. The link spine is complete; the connective prose is `TODO`.
+
+== Guardrails (non-negotiable, read first)
+
+=== Licence is Manual-Only for agents
+
+* `.claude/CLAUDE.md` (§License Policy) + `LICENCE-POLICY.adoc`.
+* Never sweep SPDX/licence headers; licence-drift findings are *flag-only*.
+  New files may carry correct SPDX from birth, matching the repo's
+  classification. (Root cause: neurophone#99.)
+* TODO: the five-way classification cheat-sheet (MPL / ARR / AGPL / forks / PMPL).
+
+=== Generated files are never hand-edited
+
+* `.machine_readable/REGISTRY.a2ml` and `TOPOLOGY.md` are *generated* by
+  `scripts/build-registry.sh` (`just registry`); edit the `SPECS` table in the
+  generator, then regenerate. CI `registry-verify.yml` fails on drift.
+* TODO: "add a new spec home end-to-end".
+
+== Learning path
+
+=== 1. The registry + topology pipeline
+
+* `scripts/build-registry.sh`, `just registry` / `just registry-check`,
+  `REGISTRY.adoc`, `TOPOLOGY.md` (derived).
+
+=== 2. Drift / staleness automation
+
+* HYP-S006 `registry-staleness` (`hypatia-rules/`) — the time-window idiom.
+* Reusable-pin freshness: link:../../decisions/ADR-003-workflow-pin-staleness-window.adoc[ADR-003],
+  `scripts/check-workflow-staleness.sh`, `scripts/propagate-workflow-pins.sh`.
+* Deferred cross-repo auto-bump: `docs/FUTURE-WORK.adoc` (#16).
+
+=== 3. Readiness-grade governance
+
+* `component-readiness-grades/` (+ ARG/FRG/TRG), `CRG-SELF-ASSESSMENT.adoc`,
+  the demotion/overclaim detectors in `hypatia-rules/`.
+
+=== 4. Decision records & policy
+
+* `docs/decisions/` (ADR process), the `*-POLICY.adoc` set
+  (DEPENDABOT, TRUSTED-BASE, REMOTE-URL, CODEOWNERS, TOOLING-VERSION-INTEGRITY).
+* TODO: "when to write an ADR vs a policy".
+
+=== 5. The innervation / contractile stack (6a2)
+
+* `.machine_readable/6a2/` (STATE/META/…), `contractiles/`, `contractile.just`,
+  `coordination.k9`, `.verisimdb/`, and Hypatia as the estate-side analyser.
+* TODO: "how a contractile is registered and fires"; whether estate scripts
+  (e.g. the staleness/propagation pair) should be registered as contractiles.
+
+=== 6. Release & ownership
+
+* `release-pre-flight/`, `publication-pre-flight/`, `just v1-audit`,
+  `MAINTAINERS.adoc`, `CODEOWNERS-POLICY.adoc`, `SECURITY.md`.
diff --git a/docs/wikis/users/index.adoc b/docs/wikis/users/index.adoc
@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath)
+= Users track — consuming & adopting the standards
+:toc:
+:toc-placement: preamble
+:status: Scaffold v0.1.0 (2026-06-21)
+
+For repo owners and teams who **adopt** the Hyperpolymath standards or
+**consume** their outputs (reusable workflows, A2ML metadata, policies,
+readiness grades). You are not editing the standards themselves — you are
+applying them.
+
+NOTE: Scaffold. The link spine is complete; the connective prose is `TODO`.
+
+== Learning path
+
+=== 1. Orient — what *are* these standards?
+
+* `README.adoc` (§Overview) — the human front door.
+* `EXPLAINME.adoc` — the architecture-decisions narrative.
+* TODO: one-paragraph "standards in plain language" for newcomers.
+
+=== 2. The machine-readable artefacts (6a2)
+
+Every Hyperpolymath repo carries six A2ML files (`STATE`, `META`, `ECOSYSTEM`,
+`AGENTIC`, `NEUROSYM`, `PLAYBOOK`) plus `ANCHOR`.
+
+* Canonical layout + meaning: `0-AI-MANIFEST.a2ml` (§CANONICAL LOCATIONS).
+* TODO: "what each artefact is for, as a consumer reading someone else's repo".
+
+=== 3. Adopt the standards in your repo
+
+* `A2ML-REPO-TEMPLATE.adoc` — the template to stand a repo up.
+* `setup.sh` — bootstrap.
+* `TEMPLATE-APPLICABILITY-POLICY.adoc` — which parts apply to which repo shapes.
+* TODO: a 10-minute "adopt on an existing repo" worked example.
+
+=== 4. Consume the reusable workflows
+
+Standards hosts reusable CI workflows you pin by SHA
+(`governance-reusable.yml`, `hypatia-scan-reusable.yml`,
+`scorecard-reusable.yml`, …).
+
+* How pinning + *pin freshness* works — and why your CI no longer reds on
+  every standards commit: link:../../decisions/ADR-003-workflow-pin-staleness-window.adoc[ADR-003].
+* Bumping a pin deliberately: `scripts/propagate-workflow-pins.sh` (audit-first).
+* TODO: copy-paste consumer workflow snippets per reusable.
+
+=== 5. Readiness grades — reading the labels
+
+ARG / FRG / CRG / TRG tell you how mature a repo/component is.
+
+* `adoption-readiness-grades/`, `foundations-readiness-grades/`,
+  `component-readiness-grades/`, `toolchain-readiness-grades/`.
+* TODO: "how to read a grade badge and what it promises you".
+
+=== 6. Get help
+
+* `QUICKSTART-USER.adoc`, `llm-warmup-user.md`.
+* Issues: https://github.com/hyperpolymath/standards/issues
