docs: align README/EXPLAINME/TOPOLOGY around two-purpose framing

Per ADR-0001 (repo purpose) the repository serves two explicit
purposes: flat-file scan/drift data store, and ABI dogfood for the
hyperpolymath Idris2 + Zig standard. The three top-level docs each
described a different subset of this; bringing them into agreement.

- README.adoc — rewritten with explicit two-purpose intro, a
  layout-by-purpose table, a Related-repos cross-link to verisimiser,
  and an index-freshness pointer (the CI lane added in a sibling
  commit). Preserves the existing scan ingest workflow + JSON format
  documentation under Purpose 1.
- EXPLAINME.adoc — quote at top reflects both purposes; file map
  expanded to call out which subtrees serve which purpose; pointer
  to verisimiser added.
- TOPOLOGY.md — Purpose section restated; module map updated to
  reflect the actual directory layout (no `hardware/` or `drift/`
  dirs — those were placeholders in the old doc); ffi/zig/ called
  out; integration points include verisimiser.

Closes #2 (V-L1-J1 implementation; the ADR was the decision).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: hyperpolymath

EXPLAINME.adoc

@@ -7,36 +7,54 @@ The README makes claims. This file backs them up.
 
 [quote, README]
 ____
-Git-backed flat-file storage for scan results and drift detection data.
+This repository serves two explicit purposes: (1) a flat-file data
+store for panic-attacker scan results, hardware-crash-team findings,
+and drift snapshots; (2) an ABI dogfood site for the hyperpolymath
+Idris2 + Zig ABI shared with `proven`, `burble`, `gossamer`.
 ____
 
-== Technology Choices
+See `docs/decisions/ADR-0001-repo-purpose.adoc` for why both purposes
+live in one repo.
+
+== Technology choices (Purpose 2 — ABI)
 
 [cols="1,2"]
 |===
 | Technology | Learn More
 
-| **Zig** | https://ziglang.org
+| **Zig**       | https://ziglang.org
 | **Idris2 ABI** | https://www.idris-lang.org
 |===
 
-== Dogfooded Across The Account
-
-Uses the hyperpolymath ABI/FFI standard (Idris2 + Zig). Same pattern used across
+The Zig FFI implementation lives in `ffi/zig/` and follows the same
+pattern as
 https://github.com/hyperpolymath/proven[proven],
 https://github.com/hyperpolymath/burble[burble], and
 https://github.com/hyperpolymath/gossamer[gossamer].
 
-== File Map
+== File map
 
-[cols="1,2"]
+[cols="1,2,1"]
 |===
-| Path | What's There
-
-| `src/` | Source code
-| `ffi/` | Foreign function interface
+| Path | What's there | Purpose
+
+| `scans/`           | Per-repo scan results (JSON; ~301 files) | data
+| `dispatch/`        | Dispatch records                          | data
+| `patterns/`        | Drift / scan pattern definitions          | data
+| `recipes/`         | Ingest and aggregation recipes            | data
+| `outcomes/`        | Outcome records                           | data
+| `policy/`          | Storage and retention policy notes        | data
+| `health/`          | Health-state snapshots                    | data
+| `index.json`       | Master index of stored data               | data
+| `ffi/zig/`         | Zig FFI implementation                    | ABI dogfood
 |===
 
+== Related
+
+`verisimiser` (https://github.com/hyperpolymath/verisimiser) is the
+augmentation CLI; this repo holds its scan/drift output but is not a
+runtime dependency.
+
 == Questions?
 
 Open an issue or reach out directly — happy to explain anything in more detail.

README.adoc

@@ -1,25 +1,49 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 = VeriSimDB Data Repository
 
-Git-backed flat-file storage for scan results and drift detection data.
+This repository serves *two explicit purposes*, per
+`docs/decisions/ADR-0001-repo-purpose.adoc`:
 
-== Structure
+. **Flat-file data store** for panic-attacker scan results,
+  hardware-crash-team findings, and drift snapshots.
+. **ABI dogfood** for the hyperpolymath Idris2 + Zig ABI standard
+  shared with https://github.com/hyperpolymath/proven[`proven`],
+  https://github.com/hyperpolymath/burble[`burble`], and
+  https://github.com/hyperpolymath/gossamer[`gossamer`].
 
-- `scans/` - panic-attack scan results per repo
-- `hardware/` - hardware-crash-team findings
-- `drift/` - drift detection snapshots
-- `index.json` - Master index of all stored data
+== Related repos
 
-== Usage
+* https://github.com/hyperpolymath/verisimiser[`verisimiser`] — the
+  augmentation CLI. This repo holds its scan and drift output;
+  standalone consumers (`panic-attacker`, `hardware-crash-team`) also
+  write here. Verisimiser does not require this repo at runtime.
 
-This repo receives scan results via GitHub Actions workflow_dispatch events
-and stores them as JSON files. The ingest workflow updates the index
-automatically.
+== Layout (by purpose)
 
-== Integration
+[cols="1,2,1"]
+|===
+| Path | What's there | Purpose
 
-=== Sending Scan Results
+| `scans/`               | Per-repo scan results (JSON; ~301 files)         | data
+| `dispatch/`            | Dispatch records                                  | data
+| `patterns/`            | Drift / scan pattern definitions                  | data
+| `recipes/`             | Ingest and aggregation recipes                    | data
+| `outcomes/`            | Outcome records                                   | data
+| `policy/`              | Storage and retention policy notes                | data
+| `health/`              | Health-state snapshots                             | data
+| `index.json`           | Master index of stored data                        | data
+| `ffi/zig/`             | Zig FFI implementation                             | ABI dogfood
+| `.machine_readable/`   | Contractile machinery (org-wide)                  | both
+| `.github/workflows/`   | CI (ingest, mirrors, governance)                  | both
+| `docs/decisions/`      | ADRs                                              | both
+|===
 
-Other repos can send scan results using the reusable workflow:
+== Purpose 1 — flat-file data store
+
+=== Receiving scan results
+
+Other repos send scan results using the reusable workflow:
 
 [source,yaml]
 ----
@@ -35,19 +59,19 @@ jobs:
     uses: hyperpolymath/panic-attacker/.github/workflows/scan-and-report.yml@main
 ----
 
-=== Querying Results
+=== Querying results
 
 Clone this repo and read the JSON files:
 
 [source,bash]
 ----
 git clone https://github.com/hyperpolymath/verisimdb-data
 cd verisimdb-data
-cat scans/echidna.json  # View specific repo results
-jq '.repos' index.json   # View all scan summaries
+cat scans/echidna.json  # specific repo
+jq '.repos' index.json   # all scan summaries
 ----
 
-== File Format
+=== File format
 
 Each scan result in `scans/` is a JSON file with the structure:
 
@@ -75,6 +99,19 @@ Each scan result in `scans/` is a JSON file with the structure:
 }
 ----
 
+=== Index freshness
+
+`index.json` is the master summary. A CI lane regenerates it from
+`scans/` on every push and fails if the working tree changes (i.e. the
+committed index must match what the regen script produces from the
+files on disk). See `scripts/regen-index.sh`.
+
+== Purpose 2 — ABI dogfood
+
+`ffi/zig/` is a working Zig FFI implementation of the hyperpolymath
+Idris2 + Zig ABI standard. The same pattern is used in `proven`,
+`burble`, and `gossamer`; this repo serves as the dogfood instance.
+
 == License
 
 SPDX-License-Identifier: PMPL-1.0-or-later

TOPOLOGY.md

@@ -5,30 +5,50 @@
 
 ## Purpose
 
-VeriSimDB Data Repository is a git-backed flat-file storage system for scan results and drift detection data. Receives panic-attack scan results, hardware-crash-team findings, and drift detection snapshots via GitHub Actions workflow_dispatch events. Maintains master index and enables historical analysis of repository health and compliance drift over time.
+This repository serves two explicit purposes per
+[`docs/decisions/ADR-0001-repo-purpose.adoc`](docs/decisions/ADR-0001-repo-purpose.adoc):
 
-## Module Map
+1. **Flat-file data store** for panic-attacker scan results,
+   hardware-crash-team findings, and drift snapshots received via
+   GitHub Actions `workflow_dispatch` events. Maintains a master
+   index for historical analysis of repository health and compliance
+   drift over time.
+2. **ABI dogfood** for the hyperpolymath Idris2 + Zig ABI standard
+   (shared with `proven`, `burble`, `gossamer`). Lives in `ffi/zig/`.
+
+## Module map
 
 ```
 verisimdb-data/
-├── scans/               # panic-attack scan results per repo
-├── hardware/            # hardware-crash-team findings
-├── drift/               # drift detection snapshots
-├── index.json           # Master index of all stored data
-└── .github/workflows/   # Ingest workflows (receive results)
+├── scans/             # panic-attacker scan results per repo (data)
+├── dispatch/          # dispatch records (data)
+├── patterns/          # drift / scan pattern definitions (data)
+├── recipes/           # ingest and aggregation recipes (data)
+├── outcomes/          # outcome records (data)
+├── policy/            # storage and retention policy notes (data)
+├── health/            # health-state snapshots (data)
+├── index.json         # master index of stored data (data)
+├── ffi/
+│   └── zig/           # Zig FFI implementation (ABI dogfood)
+├── scripts/           # ingest + index regen scripts (data)
+├── docs/
+│   └── decisions/     # ADRs
+└── .github/workflows/ # ingest + governance workflows
 ```
 
-## Data Flow
+## Data flow (Purpose 1)
 
 ```
 [Workflow Dispatch] ──► [Ingest Handler] ──► [JSON Validation] ──► [File Storage]
-                                                    ↓
-                                            [Index Update] ──► [Query Ready]
+                                                                    │
+                                                        [Index Regen on push] ──► [Query Ready]
 ```
 
-## Integration Points
+## Integration points
 
-- **panic-attack**: Upstream scanner sending results
-- **hardware-crash-team**: Hardware failure analysis
-- **Drift detection**: Compliance change tracking
-- **Hyperpolymath CI/CD**: Automated data aggregation
+- **panic-attacker**: Upstream scanner sending results into `scans/`.
+- **hardware-crash-team**: Hardware failure analysis (Purpose 1 consumer).
+- **Drift detection**: Compliance change tracking against `scans/` history.
+- **verisimiser**: Consumes scan/drift data when wired to this repo as
+  its sidecar storage. Not a runtime dependency.
+- **hyperpolymath CI/CD**: Automated data aggregation.