docs: close-out — honest user quickstart, sketch guides/ADRs, wiki seed, planned scaffolding (#29)

Documentation close-out pass. No functional/code changes.

- QUICKSTART-USER.adoc: replace the generic RSR CLI-app boilerplate (just
  setup/run/doctor/heal/tour/uninstall — none of which exist for a Worker/registry)
  with an honest registry/API quickstart, marked alpha.
- Index the 1-line "Unit" stub READMEs that sit atop real content:
  docs/practice, docs/developer, docs/governance, docs/decisions, docs/README.
- Add sketch guides (honest "planned" outlines): developer/VERISIM-QUERY-GUIDE,
  developer/REPO-ONBOARDING, USER-API-GUIDE, governance/INCIDENT-RESPONSE.
- Add 5 ADR sketches: 0001 pointer authority, 0002 clade taxonomy, 0003
  VeriSimDB+KV (accepted/retro-documented), 0004 API versioning, 0005 governance
  exceptions (open).
- Seed docs/wikis/ (Core-Concepts, Workflows, Glossary) + index; sync automation
  tracked separately.
- Mark 29 empty RSR scaffold READMEs (theory/, whitepapers/, reports/, governance
  planning|audit|maintenance substubs, standards) as "planned — not yet written"
  so they stop implying false completeness (guarded: real content untouched).
- STATE.a2ml: bump last-updated; register sketches + recent CI/docs changes.

Follow-up issues: Worker API contract (OpenAPI), release runbook (Phases 3-8),
wiki sync automation.


Claude-Session: https://claude.ai/code/session_01UCnxjXkN6uDj9YSANuGEgR

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

.machine_readable/6a2/STATE.a2ml

@@ -6,7 +6,7 @@
 [metadata]
 project = "gv-clade-index"
 version = "0.1.0"
-last-updated = "2026-06-20"
+last-updated = "2026-06-21"
 status = "active"
 
 [project-context]
@@ -49,3 +49,31 @@ actions = [
   "Deploy CLADE.a2ml to all 200 repos (sync/deploy-clade-a2ml.sh)",
   "Write sync/ingest tooling in Rust",
 ]
+
+[recent-changes]
+notes = [
+  "2026-06-21: CI/docs hardening — standards reusables bumped (#26); Hypatia advisory findings cleared (#27, 11->3, all remaining are scanner false-positives); upstream fixes tracked in #28.",
+  "2026-06-21: Docs close-out — branch cleanup; added sketch guides + ADRs (see [documentation.sketches]); marked empty RSR scaffold dirs as planned; seeded docs/wikis/.",
+]
+
+# Sketch/planned docs scaffolded 2026-06-21 — honest outlines present, content to be filled.
+[documentation.sketches]
+developer = [
+  "docs/developer/VERISIM-QUERY-GUIDE.adoc",
+  "docs/developer/REPO-ONBOARDING.adoc",
+]
+user = ["docs/USER-API-GUIDE.adoc"]
+maintainer = ["docs/governance/INCIDENT-RESPONSE.adoc"]
+decisions = [
+  "docs/decisions/0001-pointer-authority.adoc (accepted; expand)",
+  "docs/decisions/0002-clade-taxonomy.adoc (accepted; expand)",
+  "docs/decisions/0003-verisimdb-kv-architecture.adoc (accepted; expand)",
+  "docs/decisions/0004-api-versioning.adoc (open)",
+  "docs/decisions/0005-governance-exceptions.adoc (open)",
+]
+wiki = ["docs/wikis/Core-Concepts.adoc", "docs/wikis/Workflows.adoc", "docs/wikis/Glossary.adoc"]
+tracked-issues = [
+  "Worker HTTP API contract (OpenAPI 3.1)",
+  "Release runbook: Phases 3-8",
+  "Wiki sync automation",
+]

QUICKSTART-USER.adoc

@@ -1,124 +1,44 @@
 // SPDX-License-Identifier: MPL-2.0
-// Template: QUICKSTART-USER.adoc — 5-minute path to working software
-// Replace gv-clade-index, Gv Clade Index — See README.adoc for details., just run, Gv Clade Index started successfully. with actuals
 = gv-clade-index — Quick Start for Users
 :toc:
-:toclevels: 2
+:icons: font
 
 == What is gv-clade-index?
 
-Gv Clade Index — See README.adoc for details.
+The clade index is the central *registry* for the hyperpolymath ecosystem — a
+queryable taxonomy of 200+ repositories across 12 clades. It is the *map*:
+read-only and always clean. You *consume* it; you do not install or run it
+locally. (For local development, see link:QUICKSTART-DEV.adoc[QUICKSTART-DEV].)
 
-== Prerequisites
+[IMPORTANT]
+====
+*Alpha / in development (~18%).* The public HTTP API is Phase 3 and is *not yet
+deployed* — it needs a Cloudflare token and a live VeriSimDB instance (see
+`.machine_readable/6a2/STATE.a2ml`). Until then, browse the registry data and
+docs directly in this repository.
+====
 
-Before you begin, ensure you have:
+== Use it today (in-repo)
 
-* **just** — task runner (https://github.com/casey/just[install guide])
-* Platform-specific requirements listed below
+* Browse the taxonomy and architecture: link:README.adoc[README]
+* Inspect the registry data: `verisim/seed/` (clades, repos, forges) and the
+  pre-built queries in `verisim/queries/`
+* See how a repo is classified: its `.machine_readable/CLADE.a2ml`
 
-[cols="1,3"]
-|===
-| Platform | Additional Requirements
+== Use it later (the API)
 
-| Linux
-| See README.adoc
+Once deployed, external consumers will query the registry over HTTP — list repos
+by clade, find stale/orphan repos, fetch dashboard snapshots. The intended
+experience is sketched in link:docs/USER-API-GUIDE.adoc[the User API Guide]; the
+endpoint contract will be published as OpenAPI.
 
-| macOS
-| See README.adoc
+== Get help
 
-| Windows
-| See README.adoc
-|===
+* Overview & taxonomy: link:README.adoc[README]
+* Architecture & design: link:EXPLAINME.adoc[EXPLAINME]
+* Concepts & glossary: `docs/wikis/`
 
-== Install
+== Next steps
 
-=== Option 1: Standard Install (recommended)
-
-[source,bash]
-----
-# Clone and set up
-git clone https://github.com/hyperpolymath/gv-clade-index.git
-cd gv-clade-index
-just setup
-----
-
-The setup script will:
-
-* Detect your platform and shell
-* Install missing dependencies (with your permission)
-* Configure the application
-* Offer install location choices
-* Run a self-diagnostic to verify everything works
-
-=== Option 2: Container (via Stapeln)
-
-[source,bash]
-----
-just stapeln-run
-----
-
-=== Option 3: Portable (no system changes)
-
-[source,bash]
-----
-just install --portable --prefix=./gv-clade-index-portable
-----
-
-== First Run
-
-[source,bash]
-----
-just run
-----
-
-Expected output:
-
-[source]
-----
-Gv Clade Index started successfully.
-----
-
-== Self-Diagnostic
-
-If something isn't working:
-
-[source,bash]
-----
-just doctor
-----
-
-This checks all dependencies, permissions, paths, and connectivity.
-If it finds issues, it will suggest fixes.
-
-To attempt automatic repair:
-
-[source,bash]
-----
-just heal
-----
-
-== Get Help
-
-* **In-app**: `just run --help`
-* **Guided tour**: `just tour`
-* **Report a problem**: `just help-me` (pre-fills diagnostic context)
-* **Wiki**: https://github.com/hyperpolymath/gv-clade-index/wiki
-
-== Uninstall
-
-[source,bash]
-----
-just uninstall
-----
-
-You will be asked:
-
-1. Which uninstall tier (Bennett reversible, parameter-based, standard, or secure)
-2. Whether to include or exclude your data
-3. Whether to clear caches and LLM models
-
-== Next Steps
-
-* Read the link:README.adoc[README] for full feature overview
-* Read the link:EXPLAINME.adoc[EXPLAINME] for architecture and design decisions
-* Try `just tour` for a guided walkthrough
+* Developers: link:QUICKSTART-DEV.adoc[Quick Start for Developers]
+* Full data model: link:docs/SPEC-clade-verisim-portal.adoc[the Specification]

docs/README.adoc

@@ -1,14 +1,28 @@
+// SPDX-License-Identifier: MPL-2.0
 = Documentation Layout
 
 Primary tracks:
 
-* `theory/` for formal and conceptual material
-* `practice/` for operational and implementation material
-* `maintenance/` for baseline checklists and release hard-pass runbooks
-* `whitepapers/academic/` for research-facing whitepapers
-* `whitepapers/industry/` for industry/outreach whitepapers
+* `developer/` — building on and extending the index (see link:developer/README.adoc[developer/])
+* `practice/` — operational & implementation material (conventions, state tracking)
+* `governance/` — policy, maintenance checklists, release & incident runbooks
+* `decisions/` — Architecture Decision Records (ADRs)
+* `architecture/` — threat model and architectural notes
+* `theory/` — formal and conceptual material _(largely planned/sketch)_
+* `whitepapers/` — research- and industry-facing papers _(planned)_
+* `reports/` — generated quality/compliance/security/perf reports _(planned)_
+* `wikis/` — long-form, community-facing deep-dives (source for the forge wiki)
 
-Core docs:
+Key documents:
 
-* `maintenance/MAINTENANCE-CHECKLIST.md`
-* `practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc`
+* link:SPEC-clade-verisim-portal.adoc[Specification] — full data model & portal architecture
+* link:governance/MAINTENANCE-CHECKLIST.adoc[Maintenance Checklist]
+* link:governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc[Software Development Approach]
+* link:architecture/THREAT-MODEL.adoc[Threat Model]
+* link:practice/AI-CONVENTIONS.adoc[AI Conventions]
+
+Audience entry points (repo root):
+link:../README.adoc[README] ·
+link:../QUICKSTART-USER.adoc[Quick Start — Users] ·
+link:../QUICKSTART-DEV.adoc[Quick Start — Developers] ·
+link:../EXPLAINME.adoc[EXPLAINME]

docs/USER-API-GUIDE.adoc

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MPL-2.0
+= Registry API — User Guide
+:toc:
+:icons: font
+
+[NOTE]
+====
+*Status: SKETCH / planned — and alpha.* The HTTP API is Phase 3 (~60% built) and
+is *not yet publicly deployed* (blocked on a `CLOUDFLARE_API_TOKEN` secret and a
+VeriSimDB instance — see `.machine_readable/6a2/STATE.a2ml`). This guide
+describes the *intended* consumer experience; treat endpoints/shapes as
+provisional until the OpenAPI contract is published.
+====
+
+== Purpose
+
+For external consumers who want to *query* the clade registry over HTTP
+(the read-only public tier) — not to run it locally (for that, see
+`QUICKSTART-DEV.adoc`).
+
+== What this is
+
+The clade index is a queryable registry — the *map* of the hyperpolymath
+ecosystem (200+ repos, 12 clades). It is read-only and always clean; editing the
+map never touches the repositories themselves.
+
+== Outline (to be completed)
+
+. *Base URL & status* — currently in development; no public endpoint yet.
+. *Endpoints* — enumerated authoritatively once the OpenAPI 3.1 contract lands
+  (tracked separately). The handlers live in `worker/src/index.js`.
+. *Common queries* — list repos by clade, find stale/orphan repos, fetch the
+  dashboard snapshot.
+. *Response shapes & error codes.*
+. *Auth tiers & rate limits* — public-read (no key) / LLM (API key) /
+  bot (signed JWT) / contributor (OAuth).
+
+== See also
+
+* `README.adoc` — what the registry is and the portal architecture
+* `docs/SPEC-clade-verisim-portal.adoc` — data model & auth tiers

docs/decisions/0001-pointer-authority.adoc

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: MPL-2.0
+= ADR 0001 — Pointer Authority Model
+
+Date: 2026-06-21
+
+[NOTE]
+====
+*Status: SKETCH — documents an already-implemented decision; expand context &
+consequences, then ratify.*
+====
+
+== Status
+
+Accepted (retroactively documented).
+
+== Context
+
+The registry caches values that actually live in 200+ repositories. Without a
+declared canonical source, cached data drifts silently and it becomes unclear
+who may write what.
+
+== Decision
+
+Every cached value in VeriSimDB declares its authority:
+
+* `pointer` — the value lives in the repo; VeriSimDB caches it and drift-detects.
+* `local` — VeriSimDB owns it (TODOs, bot observations).
+* `derived` — computed from other values (e.g. clade health scores).
+
+"Map vs territory": the registry is the map; repos are the territory; editing the
+map never mutates the territory.
+
+== Consequences
+
+=== Positive
+- Drift detection is well-defined (`verisim/queries/drift.vcl`).
+- Clear write-ownership per field.
+
+=== Negative / Neutral
+- _To be completed: caching staleness windows, conflict resolution._

docs/decisions/0002-clade-taxonomy.adoc

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: MPL-2.0
+= ADR 0002 — Clade Taxonomy (12 codes)
+
+Date: 2026-06-21
+
+[NOTE]
+====
+*Status: SKETCH — documents an already-implemented decision; expand rationale &
+the stability/immutability policy, then ratify.*
+====
+
+== Status
+
+Accepted (retroactively documented).
+
+== Context
+
+200+ repositories need a stable, low-cardinality classification that humans and
+bots can reason about, and that query tooling can rely on not changing
+underneath it.
+
+== Decision
+
+Twelve two-letter clade codes (see `README.adoc` for the table): `fv nl rm gv db
+ap ix dx pt ax gm sc`. Each repo declares one primary clade and zero-or-more
+secondary clades.
+
+== Consequences
+
+=== Positive
+- Fixed, memorable vocabulary; cheap to validate (clade-hygiene CLADE-003).
+
+=== Negative / Neutral
+- _To be completed: the immutability/versioning policy — what happens if a 13th
+  clade is ever needed; whether codes can be retired; migration rules._

docs/decisions/0003-verisimdb-kv-architecture.adoc

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: MPL-2.0
+= ADR 0003 — VeriSimDB + KV Architecture
+
+Date: 2026-06-21
+
+[NOTE]
+====
+*Status: SKETCH — documents an already-implemented decision; expand consequences
+(consistency, fallback semantics), then ratify.*
+====
+
+== Status
+
+Accepted (retroactively documented).
+
+== Context
+
+The portal needs fast, globally-available reads for public/LLM consumers, while
+the authoritative store (VeriSimDB) runs on a single VPS that may be slow or
+unavailable.
+
+== Decision
+
+A Cloudflare Worker fronts VeriSimDB and serves reads from a KV snapshot, with
+VeriSimDB (Rust + Elixir) as the source of record. Tiered access: public read,
+LLM (API key), contributor (OAuth), bot (signed JWT).
+
+== Consequences
+
+=== Positive
+- Edge-fast reads; VPS outages degrade gracefully to the KV snapshot.
+
+=== Negative / Neutral
+- _To be completed: snapshot refresh cadence, staleness bounds, and the exact
+  fallback behaviour (cross-reference `docs/governance/INCIDENT-RESPONSE.adoc`)._