docs: config-format guide + release checklist; honest INDEX statuses

Two concrete, accurate docs written from the code hardened in this series:

- docs/developer/CONFIG-FORMATS.adoc — the 8 formats, most-specific-first
  detection order (incl. the INI-vs-JSON and YAML-vs-KeyValue disambiguation),
  the addField invariants (non-empty keys, secret redaction), the YAML subset
  scope, and how to add a parser. Marked live in INDEX (was 'planned').
- docs/maintainer/RELEASE-CHECKLIST.adoc — the actual CI gates (six test
  suites + the ABI-contract regen/diff/comptime + Idris typecheck), the
  version/license/docs pre-tag gates, the manual gates, and the tag steps.
  Marked live in INDEX (was 'planned').

INDEX also records why the empty-scaffolding prune is deferred: verification/,
docs/theory/, docs/reports/, docs/wikis/ are referenced by the governance layer
(ANCHOR.a2ml, MAINTENANCE-CHECKLIST, panic-attacker), so deleting them needs a
reviewed change that updates those references in lockstep — not an automated
docs pass. The remaining planned docs (FFI module reference, panel-extension
guide, architecture rationale, CI/CD guide, security runbook) stay 'planned'.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TaWWedv6VQqeZaPvc94keN

Author: claude

docs/INDEX.adoc

@@ -40,7 +40,7 @@ _You build GSA, extend it, or contribute code across the Gossamer GUI → Zig FF
 | FFI module reference | *planned* | Per-module docs for the 11 FFI modules (signatures, the 18 result codes, examples)
 | Panel extension guide | *planned* | The PanLL clade system; registering a new panel; inheriting base clades
 | Game-profile authoring | *thin* | Expand the README snippet: field types, validation, port/protocol, debugging
-| Config-format guide | *planned* | How to add a parser to the 8-format `config_extract`
+| `docs/developer/CONFIG-FORMATS.adoc` | live | The 8 formats, detection order, `addField` invariants, YAML scope, and how to add a parser
 | Architecture rationale | *planned* | Why Ephapax / Idris2 / Zig / VeriSimDB; when to touch each layer
 |===
 
@@ -55,7 +55,7 @@ _You release, run CI/CD, operate containers, and manage governance + security sc
 | `docs/architecture/THREAT-MODEL.adoc` | live | STRIDE, assets, trust boundaries, mitigations
 | `docs/DEPLOYMENT-RUNBOOK.adoc` | live | Build, container, VeriSimDB main+backup, health, backup/restore
 | `SECURITY.md` | live | Vulnerability reporting
-| Release checklist | *planned* | v1.0.0 must/should/could + sign-off criteria
+| `docs/maintainer/RELEASE-CHECKLIST.adoc` | live | CI gates (6 suites + ABI contract), version/license/docs gates, manual gates, tag steps
 | CI/CD guide | *planned* | `.github/workflows/` structure, standards-estate reusables (pins `4ddc926`), staleness check, adding a check
 | Security-scanning runbook | *planned* | Running/interpreting Hypatia + panic-attack + Scorecard; the `.hypatia-ignore` suppression mechanism (NOT `.hypatia-baseline.json` — see `NEUROSYM.a2ml`)
 | Container/quadlet ops | *thin* | Expand the runbook: `.container` format, systemd user units, day-to-day ops
@@ -78,3 +78,11 @@ subtrees (`theory/`, `reports/`, parts of `practice/`).
 *Decision pending:* either populate `docs/wikis/` and sync it, **or** (recommended)
 consolidate all narrative under `docs/` using the three audience paths above and
 prune the empty scaffolding. Until then, this index is the single navigation point.
+
+NOTE: a mechanical prune is **not** clean — `verification/`, `docs/theory/`,
+`docs/reports/`, and `docs/wikis/` are referenced by the governance layer
+(`.machine_readable/anchors/ANCHOR.a2ml`, `docs/governance/MAINTENANCE-CHECKLIST`,
+`features/panic-attacker/`). Deleting the trees without updating those references
+risks breaking governance/CI expectations, so the prune is deferred to a
+dedicated, reviewed change that updates the references in lockstep rather than
+bundled into an automated docs pass.

docs/developer/CONFIG-FORMATS.adoc

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+= GSA Config-Format Guide
+:toc:
+:source-highlighter: rouge
+
+How `src/interface/ffi/src/config_extract.zig` detects and parses game-server
+configuration files, and how to add support for a new format.
+
+== Overview
+
+GSA extracts a game server's configuration into a flat list of typed fields
+(`ParsedConfig.fields`), which the A2ML emitter then serialises with provenance.
+Every server config — whatever its on-disk syntax — is normalised into the same
+`ConfigField { key, value, field_type, label, default_val, range_min,
+range_max, is_secret }` shape.
+
+Two entry points:
+
+* `detectFormat(data) ConfigFormat` — sniff the format from the bytes.
+* `parseAuto(allocator, data) !ParsedConfig` — detect, then dispatch to the
+  matching parser.
+
+== The eight formats
+
+[cols="1,3,2",options="header"]
+|===
+| `ConfigFormat` | Detection signal | Parser
+| `XML`      | `<?xml` prefix, or `<` followed by a letter | `parseXML`
+| `JSON`     | leading `{`, or `[` followed by `{`/`"`/digit/`-`/`tr`/`fa`/`nu` | `parseJSON` (delegates to `std.json`)
+| `TOML`     | `[[table]]` headers, or `[section]` + dotted `a.b = c` keys | `parseTOML`
+| `INI`      | `[section]` headers (no dotted keys) | `parseINI`
+| `ENV`      | `export KEY=...` lines | `parseENV`
+| `Lua`      | `key = { ... }` table literals | `parseLua`
+| `YAML`     | leading `---`, or `key: value` mappings / `- item` sequences with **no** `=` lines | `parseYAML`
+| `KeyValue` | fallback: `key=value` / `key: value` with no other signal | `parseKeyValue`
+|===
+
+Detection is deliberately ordered most-specific-first. The ambiguous cases are
+handled explicitly:
+
+* `[network]` is INI, not a JSON array — the JSON branch requires a 2-character
+  lookahead (`[tr`, `[fa`, `[nu`) before treating `[` + letter as JSON.
+* A `key: value` file with no `=` and no `[section]` is YAML, not KeyValue — but
+  a bare `a=1` file stays KeyValue. `eq_lines == 0` is the discriminator, so a
+  colon in a value (a URL, a sentence) does not trip YAML detection.
+
+== Parser conventions
+
+All parsers funnel field creation through `ParsedConfig.addField`. Two
+invariants are enforced there, once, for every format:
+
+* **Non-empty keys.** A field whose key is empty (a lone `=value` line, a JSON
+  key of `""`) is silently dropped — it would break `getField` lookup and A2ML
+  emission. This invariant is asserted by the config fuzz harness
+  (`zig build fuzz`).
+* **Secret redaction.** Keys containing `password`, `secret`, `token`, or
+  `rcon.password` are flagged `is_secret = true`; the A2ML emitter renders their
+  values as `[REDACTED]`.
+
+Nested structures flatten to dotted keys: `server.rcon.password`,
+`worlds.0`, `worlds.1`. This is uniform across TOML, Lua, JSON, and YAML so
+downstream code never has to care which syntax a value came from.
+
+=== YAML scope
+
+`parseYAML` is a *scoped subset*, not a full YAML 1.2 implementation — the same
+level as `parseTOML`/`parseLua`. It handles:
+
+* block mappings (indentation → dotted keys),
+* block sequences of scalars (`- item` → `parent.N`),
+* scalar values with optional single/double quotes,
+* `#` comments and `---` / `...` document markers.
+
+Out of scope (documented, not silently wrong): anchors/aliases, flow
+collections (`{a: 1}`, `[1, 2]`), and multi-line/folded scalars.
+
+== Adding a new format
+
+. Add a variant to `ConfigFormat` (keep the integer stable — it crosses the
+  ABI as a `u8`; mirror it in `GameServerAdmin.ABI.Types.ConfigFormat`).
+. Write `parseXYZ(allocator, data) !ParsedConfig`, routing every field through
+  `addField` so the invariants above hold for free.
+. Add a detection branch to `detectFormat`, ordered by specificity, and be
+  explicit about any ambiguity with existing formats.
+. Add the dispatch arm to `parseAuto`.
+. Add tests: a detection test (including a negative case proving you don't
+  steal from an adjacent format) and a parse test asserting the flattened keys.
+  The fuzz harness (`src/fuzz_config.zig`) will exercise the new parser on
+  arbitrary bytes automatically once it is reachable from `parseAuto`.
+
+== See also
+
+* `docs/developer/ABI-FFI-README.adoc` — the ABI these fields cross.
+* `src/interface/ffi/test/integration_test.zig` — per-format parse tests.
+* `src/interface/ffi/src/fuzz_config.zig` — the fuzz harnesses.

docs/maintainer/RELEASE-CHECKLIST.adoc

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+= GSA Release Checklist
+:toc:
+
+The steps to cut a GSA release. The release itself is automated —
+`.github/workflows/release.yml` fires on a `v*` tag, builds `libgsa` + the
+`gsa` CLI with Zig, packages a tarball, generates a `git-cliff` changelog, and
+attaches SLSA build-provenance. This checklist is what to verify *before*
+pushing the tag.
+
+== Gate 1 — CI is green on `main`
+
+All must pass on the commit you intend to tag:
+
+* `Cross-Platform Build & Test` — `zig build` + the six test suites: `test`,
+  `test-integration`, `test-smoke`, `test-property`, `test-behavioral`,
+  `test-cli` (plus the `fuzz` seed corpus).
+* `ABI Contract` — `zig-contract` (regenerates `abi_layout_expected.zig` +
+  `result_codes_expected.zig` from the Idris2 model and fails on drift; runs the
+  comptime cross-check) **and** `idris-typecheck` (type-checks
+  `src/interface/abi/gsa-abi.ipkg` in the pinned `idris2-pack` container).
+* `CodeQL`, `Scorecard`, SonarCloud quality gate, Hypatia scan (critical=0,
+  high=0).
+
+`panic-attack assail .` is the local pre-commit gate; the static-analysis CI
+workflow covers it when the estate tool is installed.
+
+== Gate 2 — Version is reconciled
+
+There is not yet a single-source-of-truth version. Before tagging, confirm the
+following agree on the release number: `src/interface/ffi/src/main.zig`
+(`VERSION`, `BUILD_INFO`), `src/interface/ffi/build.zig` (`.version` ×2),
+`run.js`, `panels/manifest.json`, `panels/*/panel.json`, and
+`.machine_readable/6a2/*.a2ml`. (Follow-up: a `scripts/check_version_drift.sh`
+CI gate once the canonical location is chosen.)
+
+== Gate 3 — License is settled
+
+*Blocking, one-time.* The LICENSE file + all Zig/Idris source SPDX headers are
+MPL-2.0; the panel descriptors and `META.a2ml` declare AGPL-3.0-or-later. Pick a
+direction, reconcile every artifact, and record it in `docs/legal/` before the
+first tagged release. See `.machine_readable/6a2/META.a2ml` for the flagged
+conflict.
+
+== Gate 4 — Docs reflect reality
+
+* `.machine_readable/6a2/STATE.a2ml` completion % and session history updated.
+* `docs/INDEX.adoc` statuses (`live`/`thin`/`planned`) match the tree.
+* `CHANGELOG` / release notes — `git-cliff` generates these from Conventional
+  Commit messages, so confirm the commit log is clean.
+
+== Manual gates (outside CI — see also the project human checklist)
+
+These cannot be done by an agent and gate a *feature-complete* v1.0.0, not the
+mechanics of tagging:
+
+[cols="1,3",options="header"]
+|===
+| Gate | Action
+| CryoFall staging (B4) | `STEAM_USER=… just cryofall-stage-verpex` (Steam password + Guard 2FA, ~3 GB, on Verpex), then `just cryofall-watchdog-install`
+| Bitbucket mirror (B2) | provision the SSH key / token; `mirror.yml` is already wired
+| OpenSSF badge | register at bestpractices.dev, add the badge to `README.md`
+| Merged-branch cleanup | `git push origin --delete <branch>` for the merged feature branches (Hypatia GS007)
+| Ephapax parser gaps | tracked externally (`nextgen-languages/ephapax`) — 2/25 Gossamer chain tests
+|===
+
+== Cut the release
+
+[source,bash]
+----
+git checkout main && git pull
+git tag -a vX.Y.Z -m "GSA vX.Y.Z"
+git push origin vX.Y.Z          # release.yml does the rest
+----
+
+Then verify the GitHub Release has the tarball, changelog, and provenance
+attestation attached, and that the `mirror.yml` run propagated the tag.