From bf71f4a0e1dc64dff543380c976b71107c828a23 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 22:53:00 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20close-out=20=E2=80=94=20honest=20user?= =?UTF-8?q?=20quickstart,=20sketch=20guides/ADRs,=20wiki=20seed,=20planned?= =?UTF-8?q?=20scaffolding?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01UCnxjXkN6uDj9YSANuGEgR --- .machine_readable/6a2/STATE.a2ml | 30 +++- QUICKSTART-USER.adoc | 138 ++++-------------- docs/README.adoc | 30 +++- docs/USER-API-GUIDE.adoc | 41 ++++++ docs/decisions/0001-pointer-authority.adoc | 40 +++++ docs/decisions/0002-clade-taxonomy.adoc | 35 +++++ .../0003-verisimdb-kv-architecture.adoc | 35 +++++ docs/decisions/0004-api-versioning.adoc | 33 +++++ .../decisions/0005-governance-exceptions.adoc | 30 ++++ docs/decisions/README.adoc | 17 ++- docs/developer/README.adoc | 12 +- docs/developer/REPO-ONBOARDING.adoc | 39 +++++ docs/developer/VERISIM-QUERY-GUIDE.adoc | 43 ++++++ docs/governance/INCIDENT-RESPONSE.adoc | 33 +++++ docs/governance/README.adoc | 15 ++ docs/governance/audit/README.adoc | 5 + docs/governance/audit/compliance/README.adoc | 5 + docs/governance/audit/effects/README.adoc | 5 + docs/governance/audit/systems/README.adoc | 5 + docs/governance/maintenance/README.adoc | 5 + .../maintenance/adaptive/README.adoc | 5 + .../maintenance/corrective/README.adoc | 5 + .../maintenance/perfective/README.adoc | 5 + docs/governance/planning/README.adoc | 5 + docs/governance/planning/could/README.adoc | 5 + docs/governance/planning/must/README.adoc | 5 + docs/governance/planning/should/README.adoc | 5 + docs/practice/README.adoc | 10 +- docs/reports/README.adoc | 5 + docs/reports/compliance/README.adoc | 5 + docs/reports/maintenance/README.adoc | 5 + docs/reports/performance/README.adoc | 5 + docs/reports/quality/README.adoc | 5 + docs/reports/security/README.adoc | 5 + docs/standards/README.adoc | 5 + docs/theory/README.adoc | 5 + docs/theory/computing/README.adoc | 5 + docs/theory/formalisms/README.adoc | 5 + docs/theory/mathematics/README.adoc | 5 + docs/theory/ontologies/README.adoc | 5 + docs/theory/other/README.adoc | 5 + docs/theory/socio-technical/README.adoc | 5 + docs/whitepapers/README.adoc | 5 + docs/whitepapers/academic/README.adoc | 5 + docs/whitepapers/industry/README.adoc | 5 + docs/wikis/Core-Concepts.adoc | 39 +++++ docs/wikis/Glossary.adoc | 26 ++++ docs/wikis/README.adoc | 25 +++- docs/wikis/Workflows.adoc | 15 ++ 49 files changed, 703 insertions(+), 128 deletions(-) create mode 100644 docs/USER-API-GUIDE.adoc create mode 100644 docs/decisions/0001-pointer-authority.adoc create mode 100644 docs/decisions/0002-clade-taxonomy.adoc create mode 100644 docs/decisions/0003-verisimdb-kv-architecture.adoc create mode 100644 docs/decisions/0004-api-versioning.adoc create mode 100644 docs/decisions/0005-governance-exceptions.adoc create mode 100644 docs/developer/REPO-ONBOARDING.adoc create mode 100644 docs/developer/VERISIM-QUERY-GUIDE.adoc create mode 100644 docs/governance/INCIDENT-RESPONSE.adoc create mode 100644 docs/wikis/Core-Concepts.adoc create mode 100644 docs/wikis/Glossary.adoc create mode 100644 docs/wikis/Workflows.adoc diff --git a/.machine_readable/6a2/STATE.a2ml b/.machine_readable/6a2/STATE.a2ml index 5fe6d7a..99fb2b1 100644 --- a/.machine_readable/6a2/STATE.a2ml +++ b/.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", +] diff --git a/QUICKSTART-USER.adoc b/QUICKSTART-USER.adoc index ffc6645..29cb7dd 100644 --- a/QUICKSTART-USER.adoc +++ b/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] diff --git a/docs/README.adoc b/docs/README.adoc index df45be7..fc2daac 100644 --- a/docs/README.adoc +++ b/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] diff --git a/docs/USER-API-GUIDE.adoc b/docs/USER-API-GUIDE.adoc new file mode 100644 index 0000000..0ad7a40 --- /dev/null +++ b/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 diff --git a/docs/decisions/0001-pointer-authority.adoc b/docs/decisions/0001-pointer-authority.adoc new file mode 100644 index 0000000..80b9be1 --- /dev/null +++ b/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._ diff --git a/docs/decisions/0002-clade-taxonomy.adoc b/docs/decisions/0002-clade-taxonomy.adoc new file mode 100644 index 0000000..4cc8c2e --- /dev/null +++ b/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._ diff --git a/docs/decisions/0003-verisimdb-kv-architecture.adoc b/docs/decisions/0003-verisimdb-kv-architecture.adoc new file mode 100644 index 0000000..1b71507 --- /dev/null +++ b/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`)._ diff --git a/docs/decisions/0004-api-versioning.adoc b/docs/decisions/0004-api-versioning.adoc new file mode 100644 index 0000000..9d57ec4 --- /dev/null +++ b/docs/decisions/0004-api-versioning.adoc @@ -0,0 +1,33 @@ +// SPDX-License-Identifier: MPL-2.0 += ADR 0004 — API Versioning Strategy + +Date: 2026-06-21 + +[NOTE] +==== +*Status: SKETCH — OPEN decision, not yet made. Outline only.* +==== + +== Status + +Proposed (needs a decision before the API is published). + +== Context + +Once the Worker API is public (Phase 3+) and consumed by LLMs, dashboards, and +external contributors, the response shapes become a contract. We need a +versioning approach decided *before* publication to avoid breaking consumers. + +== Decision + +_To be decided._ Options to weigh: + +* URL-path versioning (`/v1/...`). +* Header/content-negotiation versioning. +* Additive-only evolution with no explicit version. + +Should be settled alongside the OpenAPI 3.1 contract (tracked issue). + +== Consequences + +_To be completed once decided._ diff --git a/docs/decisions/0005-governance-exceptions.adoc b/docs/decisions/0005-governance-exceptions.adoc new file mode 100644 index 0000000..d312224 --- /dev/null +++ b/docs/decisions/0005-governance-exceptions.adoc @@ -0,0 +1,30 @@ +// SPDX-License-Identifier: MPL-2.0 += ADR 0005 — Org-wide Governance Exceptions + +Date: 2026-06-21 + +[NOTE] +==== +*Status: SKETCH — OPEN decision, not yet made. Outline only.* +==== + +== Status + +Proposed. + +== Context + +As the central registry for the ecosystem, this repo's standards (clade hygiene, +contractiles, reusable workflows) are applied org-wide. Some repos will need +sanctioned, recorded exceptions — and there must be a principled way to grant +and review them rather than silent drift. + +== Decision + +_To be decided._ Outline: who may grant an exception, where it is recorded +(per-repo `CLADE.a2ml`? a central `local` table in VeriSimDB?), expiry/review +cadence, and how exceptions surface in governance queries. + +== Consequences + +_To be completed once decided._ diff --git a/docs/decisions/README.adoc b/docs/decisions/README.adoc index 153a5e7..ec3918a 100644 --- a/docs/decisions/README.adoc +++ b/docs/decisions/README.adoc @@ -1 +1,16 @@ -= decisions Unit +// SPDX-License-Identifier: MPL-2.0 += Architecture Decision Records (ADRs) + +Records of significant architectural decisions. New ADRs follow +link:0000-template.adoc[the template]. + +[cols="1,4,2"] +|=== +| ADR | Title | Status + +| link:0001-pointer-authority.adoc[0001] | Pointer Authority Model | Accepted _(sketch)_ +| link:0002-clade-taxonomy.adoc[0002] | Clade Taxonomy (12 codes) | Accepted _(sketch)_ +| link:0003-verisimdb-kv-architecture.adoc[0003] | VeriSimDB + KV Architecture | Accepted _(sketch)_ +| link:0004-api-versioning.adoc[0004] | API Versioning Strategy | Proposed _(open)_ +| link:0005-governance-exceptions.adoc[0005] | Org-wide Governance Exceptions | Proposed _(open)_ +|=== diff --git a/docs/developer/README.adoc b/docs/developer/README.adoc index 1d00529..f53c564 100644 --- a/docs/developer/README.adoc +++ b/docs/developer/README.adoc @@ -1 +1,11 @@ -= developer Unit +// SPDX-License-Identifier: MPL-2.0 += Developer Documentation + +Start here if you are building on or extending the clade index. + +* link:../../QUICKSTART-DEV.adoc[Quick Start for Developers] — local setup +* link:VERISIM-QUERY-GUIDE.adoc[VeriSimDB Query Guide] — schema & VCL queries _(sketch)_ +* link:REPO-ONBOARDING.adoc[Repo Onboarding] — adding a repository _(sketch)_ +* link:ABI-FFI-README.adoc[ABI/FFI] — not applicable (no native FFI surface) +* link:../SPEC-clade-verisim-portal.adoc[Full Specification] — data model & portal architecture +* link:../decisions/README.adoc[Architecture Decision Records] diff --git a/docs/developer/REPO-ONBOARDING.adoc b/docs/developer/REPO-ONBOARDING.adoc new file mode 100644 index 0000000..89987ff --- /dev/null +++ b/docs/developer/REPO-ONBOARDING.adoc @@ -0,0 +1,39 @@ +// SPDX-License-Identifier: MPL-2.0 += Repo Onboarding — Adding a Repository to the Registry +:toc: +:icons: font + +[NOTE] +==== +*Status: SKETCH / planned — not yet complete.* Scaffolded outline. The data +model behind these steps is already specified in +`docs/SPEC-clade-verisim-portal.adoc` and `README.adoc`; this guide will turn +that into a procedure. +==== + +== Purpose + +A step-by-step for registering a new repository (e.g. the "201st") in the clade +index. + +== Outline (to be completed) + +. *Add `.machine_readable/CLADE.a2ml`* to the new repo, satisfying the + clade-hygiene contractile (CLADE-001 present, CLADE-002 primary clade declared, + CLADE-003 code is one of the 12 valid codes). +. *Choose clade codes* — one primary + zero-or-more secondary (the 12 codes are + listed in `README.adoc`). +. *Register in seed data* (`verisim/seed/repos.a2ml`): primary key + (`gh:hyperpolymath/{name}`), foreign keys (GitLab/Bitbucket/Codeberg/SourceHut + mirrors), and the deterministic UUIDv5. +. *Set lineage* — standalone / monorepo / monorepo-child / inflated / deflated, + and when each applies. +. *Deploy & ingest* — `sync/deploy-clade-a2ml.sh`, then `sync/seed-verisim.sh`. +. *Verify* — clade-hygiene contractile passes and the repo appears in + `dashboard.vcl` (and not in `orphans.vcl`). + +== See also + +* `README.adoc` — identity model & clade taxonomy +* `docs/SPEC-clade-verisim-portal.adoc` — full spec +* `.machine_readable/CLADE.a2ml` — this repo's own declaration (worked example) diff --git a/docs/developer/VERISIM-QUERY-GUIDE.adoc b/docs/developer/VERISIM-QUERY-GUIDE.adoc new file mode 100644 index 0000000..97ae5a9 --- /dev/null +++ b/docs/developer/VERISIM-QUERY-GUIDE.adoc @@ -0,0 +1,43 @@ +// SPDX-License-Identifier: MPL-2.0 += VeriSimDB Query Guide (VCL) +:toc: +:icons: font + +[NOTE] +==== +*Status: SKETCH / planned — not yet complete.* This is a scaffolded outline that +captures the intended structure so it can be filled in (by a contributor or +agent) as Phases 2–3 land. Source material already in the repo: +`verisim/schema/*.vcl`, `verisim/queries/*.vcl`, and +`docs/SPEC-clade-verisim-portal.adoc`. +==== + +== Purpose + +Teach a developer to read the registry schema and write VCL queries against +VeriSimDB — going beyond the pre-built queries in `verisim/queries/`. + +== Audience + +Developers extending the registry, or building dashboards / drift detection. + +== Outline (to be completed) + +. *The entity model* — how a repository is represented (`verisim/schema/repo.vcl`) + and the seven entity types: repo, clade, todo, observation, feedback, lineage, + forge-identity. +. *Reading the seed data* — `verisim/seed/{clades,repos,forges}.a2ml`. +. *Basic queries* — filter repos by clade / language / status; walk through + `dashboard.vcl`, `stale.vcl`, `orphans.vcl`. +. *Pointer authority in practice* — `pointer` vs `local` vs `derived`, and how + drift detection uses it (`drift.vcl`). +. *Authoring a new query* — naming conventions, where it lives, and how the + Worker surfaces it. +. *Cross-clade analysis* — `cross-clade-deps.vcl`, `bot-findings.vcl`, + `blocked.vcl`, `feedback-status.vcl`. + +== See also + +* `docs/SPEC-clade-verisim-portal.adoc` — full data model +* `README.adoc` — identity & pointer-authority overview +* `docs/developer/REPO-ONBOARDING.adoc` — registering a new repo diff --git a/docs/governance/INCIDENT-RESPONSE.adoc b/docs/governance/INCIDENT-RESPONSE.adoc new file mode 100644 index 0000000..5ad8cac --- /dev/null +++ b/docs/governance/INCIDENT-RESPONSE.adoc @@ -0,0 +1,33 @@ +// SPDX-License-Identifier: MPL-2.0 += Incident Response & Rollback +:toc: +:icons: font + +[NOTE] +==== +*Status: SKETCH / planned — not yet complete.* Scaffolded outline for +maintainers. Complements the STRIDE analysis in +`docs/architecture/THREAT-MODEL.adoc` and the runbook in +`docs/governance/MAINTENANCE-CHECKLIST.adoc`. +==== + +== Purpose + +Recovery procedures for the registry and its Cloudflare Worker. + +== Outline (to be completed) + +. *Architecture recap* — Worker → VeriSimDB (VPS), with a KV snapshot as the + read fallback. +. *VeriSimDB unavailable* — expected KV-fallback behaviour and how to confirm it + (handlers in `worker/src/`). +. *Stale KV snapshot* — detection and refresh procedure. +. *Seed / data corruption* — restore from the repositories themselves; pointer + authority means repos are the source of truth, the registry only caches. +. *Bad Worker deploy* — rollback (`wrangler rollback`) or revert-and-redeploy. +. *Escalation & ownership* — see `docs/attribution/MAINTAINERS.adoc`. + +== See also + +* `docs/architecture/THREAT-MODEL.adoc` +* `docs/governance/MAINTENANCE-CHECKLIST.adoc` diff --git a/docs/governance/README.adoc b/docs/governance/README.adoc index 114ee94..b0ff9dd 100644 --- a/docs/governance/README.adoc +++ b/docs/governance/README.adoc @@ -1 +1,16 @@ +// SPDX-License-Identifier: MPL-2.0 = Governance Pillar (TSDM) + +Policy, decision gates, and operational runbooks for the project. + +* link:SOFTWARE-DEVELOPMENT-APPROACH.adoc[Software Development Approach] — policy & priority rules +* link:TSDM.adoc[TSDM] — the three-scale development model +* link:CRG-CRITERIA.adoc[CRG Criteria] — change-review gates +* link:MAINTENANCE-CHECKLIST.adoc[Maintenance Checklist] — three-axis maintenance runbook +* link:INCIDENT-RESPONSE.adoc[Incident Response & Rollback] _(sketch)_ + +Sub-areas (planned scaffolding): + +* `planning/` — must / should / could work prioritisation +* `audit/` — systems / compliance / effects audit outputs +* `maintenance/` — adaptive / corrective / perfective maintenance records diff --git a/docs/governance/audit/README.adoc b/docs/governance/audit/README.adoc index fac3740..52a17fb 100644 --- a/docs/governance/audit/README.adoc +++ b/docs/governance/audit/README.adoc @@ -1 +1,6 @@ = Audit Axis + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/governance/audit/compliance/README.adoc b/docs/governance/audit/compliance/README.adoc index 876954f..40dee33 100644 --- a/docs/governance/audit/compliance/README.adoc +++ b/docs/governance/audit/compliance/README.adoc @@ -1 +1,6 @@ = Compliance Unit + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/governance/audit/effects/README.adoc b/docs/governance/audit/effects/README.adoc index 3634799..a687bee 100644 --- a/docs/governance/audit/effects/README.adoc +++ b/docs/governance/audit/effects/README.adoc @@ -1 +1,6 @@ = Effects Unit + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/governance/audit/systems/README.adoc b/docs/governance/audit/systems/README.adoc index 8d179b4..e87b77a 100644 --- a/docs/governance/audit/systems/README.adoc +++ b/docs/governance/audit/systems/README.adoc @@ -1 +1,6 @@ = Systems Unit + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/governance/maintenance/README.adoc b/docs/governance/maintenance/README.adoc index 0ed2f1b..49b8380 100644 --- a/docs/governance/maintenance/README.adoc +++ b/docs/governance/maintenance/README.adoc @@ -1 +1,6 @@ = Maintenance Axis + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/governance/maintenance/adaptive/README.adoc b/docs/governance/maintenance/adaptive/README.adoc index 7b60992..0b087cc 100644 --- a/docs/governance/maintenance/adaptive/README.adoc +++ b/docs/governance/maintenance/adaptive/README.adoc @@ -1 +1,6 @@ = Adaptive Unit + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/governance/maintenance/corrective/README.adoc b/docs/governance/maintenance/corrective/README.adoc index ed904a8..4037c35 100644 --- a/docs/governance/maintenance/corrective/README.adoc +++ b/docs/governance/maintenance/corrective/README.adoc @@ -1 +1,6 @@ = Corrective Unit + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/governance/maintenance/perfective/README.adoc b/docs/governance/maintenance/perfective/README.adoc index 8759d74..40dbb79 100644 --- a/docs/governance/maintenance/perfective/README.adoc +++ b/docs/governance/maintenance/perfective/README.adoc @@ -1 +1,6 @@ = Perfective Unit + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/governance/planning/README.adoc b/docs/governance/planning/README.adoc index 62aa375..8f5ad94 100644 --- a/docs/governance/planning/README.adoc +++ b/docs/governance/planning/README.adoc @@ -1 +1,6 @@ = Planning Axis + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/governance/planning/could/README.adoc b/docs/governance/planning/could/README.adoc index ad5a6b8..fc65fcd 100644 --- a/docs/governance/planning/could/README.adoc +++ b/docs/governance/planning/could/README.adoc @@ -1 +1,6 @@ = Could Unit + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/governance/planning/must/README.adoc b/docs/governance/planning/must/README.adoc index 47eb46d..b0ede12 100644 --- a/docs/governance/planning/must/README.adoc +++ b/docs/governance/planning/must/README.adoc @@ -1 +1,6 @@ = Must Unit + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/governance/planning/should/README.adoc b/docs/governance/planning/should/README.adoc index 605489c..e089fca 100644 --- a/docs/governance/planning/should/README.adoc +++ b/docs/governance/planning/should/README.adoc @@ -1 +1,6 @@ = Should Unit + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/practice/README.adoc b/docs/practice/README.adoc index ae3326b..dcbdae5 100644 --- a/docs/practice/README.adoc +++ b/docs/practice/README.adoc @@ -1 +1,9 @@ -= practice Unit +// SPDX-License-Identifier: MPL-2.0 += Practice + +Operational and implementation material. + +* link:AI-CONVENTIONS.adoc[AI Conventions] — rules and banned patterns for agents working in this repo +* link:STATE-VISUALIZER-GUIDE.adoc[State Visualizer Guide] — how project status is tracked + +See also: link:../governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc[Software Development Approach]. diff --git a/docs/reports/README.adoc b/docs/reports/README.adoc index 0c06c31..a2a223f 100644 --- a/docs/reports/README.adoc +++ b/docs/reports/README.adoc @@ -1 +1,6 @@ = reports Unit + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/reports/compliance/README.adoc b/docs/reports/compliance/README.adoc index c38c66a..f93713b 100644 --- a/docs/reports/compliance/README.adoc +++ b/docs/reports/compliance/README.adoc @@ -1 +1,6 @@ = Compliance Reports + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/reports/maintenance/README.adoc b/docs/reports/maintenance/README.adoc index f13abf7..24d3f3a 100644 --- a/docs/reports/maintenance/README.adoc +++ b/docs/reports/maintenance/README.adoc @@ -1 +1,6 @@ = Maintenance Reports + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/reports/performance/README.adoc b/docs/reports/performance/README.adoc index 037767d..81eb111 100644 --- a/docs/reports/performance/README.adoc +++ b/docs/reports/performance/README.adoc @@ -1 +1,6 @@ = Performance Reports + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/reports/quality/README.adoc b/docs/reports/quality/README.adoc index d1be848..d617c1a 100644 --- a/docs/reports/quality/README.adoc +++ b/docs/reports/quality/README.adoc @@ -1 +1,6 @@ = Quality Reports + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/reports/security/README.adoc b/docs/reports/security/README.adoc index 9a78a8b..14e76dc 100644 --- a/docs/reports/security/README.adoc +++ b/docs/reports/security/README.adoc @@ -1 +1,6 @@ = Security Reports + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/standards/README.adoc b/docs/standards/README.adoc index 34a94c4..714d05e 100644 --- a/docs/standards/README.adoc +++ b/docs/standards/README.adoc @@ -1 +1,6 @@ = Standards Unit + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/theory/README.adoc b/docs/theory/README.adoc index c0ddf28..ec83a0f 100644 --- a/docs/theory/README.adoc +++ b/docs/theory/README.adoc @@ -1 +1,6 @@ = theory Unit + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/theory/computing/README.adoc b/docs/theory/computing/README.adoc index 4d0db25..8615fb8 100644 --- a/docs/theory/computing/README.adoc +++ b/docs/theory/computing/README.adoc @@ -1 +1,6 @@ = Computing Theory + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/theory/formalisms/README.adoc b/docs/theory/formalisms/README.adoc index 5d064c3..156e011 100644 --- a/docs/theory/formalisms/README.adoc +++ b/docs/theory/formalisms/README.adoc @@ -1 +1,6 @@ = Formalisms Theory + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/theory/mathematics/README.adoc b/docs/theory/mathematics/README.adoc index 356236f..86b5947 100644 --- a/docs/theory/mathematics/README.adoc +++ b/docs/theory/mathematics/README.adoc @@ -1 +1,6 @@ = Mathematics Theory + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/theory/ontologies/README.adoc b/docs/theory/ontologies/README.adoc index 6d16ecf..3cae87e 100644 --- a/docs/theory/ontologies/README.adoc +++ b/docs/theory/ontologies/README.adoc @@ -1 +1,6 @@ = Ontologies Theory + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/theory/other/README.adoc b/docs/theory/other/README.adoc index 1861d6d..3068f4c 100644 --- a/docs/theory/other/README.adoc +++ b/docs/theory/other/README.adoc @@ -1 +1,6 @@ = Other Theory + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/theory/socio-technical/README.adoc b/docs/theory/socio-technical/README.adoc index 9ab4ee0..4ffb8f2 100644 --- a/docs/theory/socio-technical/README.adoc +++ b/docs/theory/socio-technical/README.adoc @@ -1 +1,6 @@ = Socio technical Theory + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/whitepapers/README.adoc b/docs/whitepapers/README.adoc index 88e83c5..8f292cc 100644 --- a/docs/whitepapers/README.adoc +++ b/docs/whitepapers/README.adoc @@ -1 +1,6 @@ = whitepapers Unit + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/whitepapers/academic/README.adoc b/docs/whitepapers/academic/README.adoc index 16c3f45..a61dfc7 100644 --- a/docs/whitepapers/academic/README.adoc +++ b/docs/whitepapers/academic/README.adoc @@ -1 +1,6 @@ = Academic Logic + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/whitepapers/industry/README.adoc b/docs/whitepapers/industry/README.adoc index 7bc7fcd..9ff738e 100644 --- a/docs/whitepapers/industry/README.adoc +++ b/docs/whitepapers/industry/README.adoc @@ -1 +1,6 @@ = Industry Logic + +[NOTE] +==== +*Planned - not yet written.* RSR scaffold slot reserved for future content; intentionally empty for now. See `.machine_readable/6a2/STATE.a2ml` for roadmap status. +==== diff --git a/docs/wikis/Core-Concepts.adoc b/docs/wikis/Core-Concepts.adoc new file mode 100644 index 0000000..66beab7 --- /dev/null +++ b/docs/wikis/Core-Concepts.adoc @@ -0,0 +1,39 @@ +// SPDX-License-Identifier: MPL-2.0 += Core Concepts +:icons: font + +[NOTE] +==== +*Status: SKETCH — seed content; expand into full deep-dives.* +==== + +== Map vs Territory + +The registry is the *map* — queryable, presentable, always clean. The +repositories are the *territory*. Editing the map never damages the territory. + +== Clades + +The ecosystem is classified by twelve two-letter clade codes (see the table in +`README.adoc`). Each repo has one primary clade and zero-or-more secondary +clades. + +== Pointer Authority + +Every cached value declares its canonical source: `pointer` (lives in the repo), +`local` (owned by the registry), or `derived` (computed). See +`docs/decisions/0001-pointer-authority.adoc`. + +== Identity Model + +Primary key `gh:hyperpolymath/{name}`; foreign keys for mirrors; deterministic +UUIDv5; lineage (standalone / monorepo / monorepo-child / inflated / deflated). + +== Portal Architecture + +`github.io` (ReScript/WASM) → Cloudflare Worker (API gateway) → VeriSimDB +(Rust + Elixir, VPS), with a KV snapshot for edge-fast public reads. + +== See also + +* `README.adoc`, `docs/SPEC-clade-verisim-portal.adoc`, `docs/decisions/` diff --git a/docs/wikis/Glossary.adoc b/docs/wikis/Glossary.adoc new file mode 100644 index 0000000..8dbabe1 --- /dev/null +++ b/docs/wikis/Glossary.adoc @@ -0,0 +1,26 @@ +// SPDX-License-Identifier: MPL-2.0 += Glossary +:icons: font + +[NOTE] +==== +*Status: SKETCH — extend as new terms appear.* +==== + +Clade:: One of twelve two-letter classification codes for the ecosystem. +Primary / secondary clade:: A repo's main classification (one) plus optional + additional ones (zero or more). +Entity model:: The seven VeriSimDB entity types — repo, clade, todo, observation, + feedback, lineage, forge-identity (see `verisim/schema/`). +Pointer authority:: Whether a cached value is a `pointer`, `local`, or `derived` + (see ADR 0001). +Lineage:: A repo's structural history — standalone, monorepo, monorepo-child, + inflated, or deflated. +Contractile:: A machine-readable policy contract (e.g. `must`, `trust`, `dust`, + `bust`) under `.machine_readable/contractiles/`. +CLADE.a2ml:: The per-repo clade declaration; clade-hygiene rules CLADE-001..003. +VeriSimDB:: The backing database (Rust + Elixir) that holds the registry. +VCL:: The VeriSim schema/query language (`verisim/schema/`, `verisim/queries/`). +KV snapshot:: The edge cache the Worker serves public reads from. +Map vs territory:: The registry (map) versus the repositories (territory). +RSR:: The repository standard this project is scaffolded on. diff --git a/docs/wikis/README.adoc b/docs/wikis/README.adoc index 71b60d1..6c6bf15 100644 --- a/docs/wikis/README.adoc +++ b/docs/wikis/README.adoc @@ -1,15 +1,26 @@ +// SPDX-License-Identifier: MPL-2.0 = Project Wikis :toc: preamble :icons: font -This directory contains the source files for the project wiki. It is intended for long-form documentation, deep-dives, and community-maintained knowledge. +[NOTE] +==== +*Status: SKETCH.* The pages below are seeded starters. Deeper content and +automated synchronisation to the forge-hosted wiki are tracked as a follow-up +(see the "wiki sync" issue). +==== -== Structure +This directory holds the source files for the project wiki — long-form +documentation, deep-dives, and community-maintained knowledge. It is the source +of truth; the forge-hosted wiki (GitHub/GitLab) is a published mirror. -* **Core Concepts:** Fundamental architectural ideas. -* **Workflows:** Step-by-step guides for contributors. -* **Glossary:** Definitions of project-specific terminology. +== Pages -== Wiki Synchronization +* link:Core-Concepts.adoc[Core Concepts] — the fundamental architectural ideas +* link:Workflows.adoc[Workflows] — step-by-step contributor guides +* link:Glossary.adoc[Glossary] — project terminology -Changes made here should be synchronised with the forge-hosted wiki (GitHub/GitLab) using the project's sync scripts. +== Wiki synchronisation + +Content here should be synchronised to the forge-hosted wiki. The sync +automation is *not yet wired up* — tracked as a follow-up task. diff --git a/docs/wikis/Workflows.adoc b/docs/wikis/Workflows.adoc new file mode 100644 index 0000000..7bf47fa --- /dev/null +++ b/docs/wikis/Workflows.adoc @@ -0,0 +1,15 @@ +// SPDX-License-Identifier: MPL-2.0 += Workflows +:icons: font + +[NOTE] +==== +*Status: SKETCH — index of contributor workflows; each links to its guide.* +==== + +* *Add a repository to the registry* → `docs/developer/REPO-ONBOARDING.adoc` +* *Write a registry query* → `docs/developer/VERISIM-QUERY-GUIDE.adoc` +* *Consume the API as a user* → `docs/USER-API-GUIDE.adoc` +* *Respond to an incident / roll back* → `docs/governance/INCIDENT-RESPONSE.adoc`, + `docs/governance/MAINTENANCE-CHECKLIST.adoc` +* *Contribute code* → `CONTRIBUTING.md`, `docs/practice/AI-CONVENTIONS.adoc`