docs/state: closeout freshness — correct counts, refresh machine-readable, add doc index (#46)

Verified factual corrections (independently grepped/counted, not from memory):
- Exported FFI symbols 38 -> 40; game profiles 17 -> 18; GUI panels 7 -> 8
  (nexus-setup is the 8th) across CLAUDE.md, README.adoc, ROADMAP.adoc, STATE.a2ml.

Machine-readable freshness:
- STATE.a2ml: last-updated 2026-06-21 + a session-history entry for the #41-#45
  CI/governance + Hypatia sweep, recording the outstanding items (branch prune,
  the stale estate-standardization branch, doc gaps).
- NEUROSYM.a2ml: last-updated 2026-06-21 + records .hypatia-ignore as the active
  suppression mechanism (NOT .hypatia-baseline.json) and the 4ddc926 pins.
- CLAUDE.md: Current State dated 2026-06-21 + a CI/Governance bullet.

New:
- docs/INDEX.adoc — audience-segmented documentation map (users / developers /
  maintainers) marking what exists and the known gaps, plus the wiki decision.

The test-count line (124) is left unchanged pending a verified `zig build test`
run (no Zig toolchain in this container); flagged for follow-up.


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

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

Author: hyperpolymath

.claude/CLAUDE.md

@@ -79,11 +79,12 @@ VeriSimDB (8-modality octads)      -- container/verisimdb/
   - **Backup** (port 8091, `GSA_BACKUP_VERISIMDB_URL`): game save metadata, snapshots, restore points
 - **Container images** use Chainguard Wolfi base, Podman, `Containerfile` (never Docker/Dockerfile)
 
-## Current State (2026-06-20)
+## Current State (2026-06-21)
 
 - **Completion**: 93% (15 phases built; v1.0.0 gates still open — see Remaining)
+- **CI/Governance (2026-06-21, PRs #41–#45)**: workflows hardened (Scorecard wrapper job perms, presence-gated instant-sync, CodeQL `actions`, scoped `deno` perms); standards reusable pins at `4ddc926`; Hypatia false positives suppressed via `.hypatia-ignore` (the inert `.hypatia-baseline.json` was removed — `hypatia scan` never applied it); advisory scan at critical=0/high=0. Doc map + gaps: `docs/INDEX.adoc`.
 - **Zig version**: 0.15.2 (see `.tool-versions`)
-- **Exported FFI symbols**: 38 (comptime linker hints in main.zig)
+- **Exported FFI symbols**: 40 (comptime linker hints in main.zig)
 - **Tests**: 124 Zig tests across 3 suites (unit: 80, integration: 39, smoke: 5). All passing.
   - Security tests for command injection in server_actions
   - Config parser edge cases for all 8 formats
@@ -113,8 +114,8 @@ VeriSimDB (8-modality octads)      -- container/verisimdb/
 |------|-------|
 | AI manifest | `0-AI-MANIFEST.a2ml` (read FIRST) |
 | State checkpoint | `.machine_readable/6a2/STATE.a2ml` |
-| Game profiles | `profiles/*.a2ml` (17 games) |
-| GUI panels | `src/gui/panels/` (7 panels) |
+| Game profiles | `profiles/*.a2ml` (18 games) |
+| GUI panels | `src/gui/panels/` (8 panels) |
 | Panel clades | `panel-clades/` (9 base + game children) |
 | Ephapax core | `src/core/` (Shell, Bridge, Types, Capabilities) |
 | VeriSimDB (main, port 8090) | `container/verisimdb/` |

.machine_readable/6a2/NEUROSYM.a2ml

@@ -6,12 +6,19 @@
 
 [metadata]
 version = "0.1.0"
-last-updated = "2026-03-22"
+last-updated = "2026-06-21"
 
 [hypatia-config]
 scan-enabled = true
 scan-depth = "standard"  # quick | standard | deep
 report-format = "logtalk"
+# Active suppression mechanism (PR #43-#44). NOTE: `.hypatia-baseline.json` is
+# NOT honoured by `hypatia scan` — it only excludes the file itself from being
+# scanned. The working mechanism is the repo-root `.hypatia-ignore`, consulted
+# by Hypatia.ScannerSuppression (code_safety + secret-detection paths).
+# Standards reusable pins: 4ddc926 (PR #45).
+suppression-file = ".hypatia-ignore"
+suppression-scope = "7 reviewed false positives: 2 test-fixture secrets (fuzz_config.zig, .envrc), 3 escaped-markup innerHTML sinks (src/gui/fli/*.js), 1 loopback HTTP URL (template-hunt.k9.ncl), 1 syscall bitCast (probe.zig); plus a self-exemption so the file's own docs are not re-flagged"
 
 [symbolic-rules]
 # Custom symbolic rules for this project

.machine_readable/6a2/STATE.a2ml

@@ -6,7 +6,7 @@
 [metadata]
 project = "game-server-admin"
 version = "0.1.0"
-last-updated = "2026-06-20"
+last-updated = "2026-06-21"
 status = "active"
 
 [project-context]
@@ -24,8 +24,8 @@ milestones = [
   { name = "Phase 2: Idris2 ABI layer (Types, Foreign, Layout)", completion = 100 },
   { name = "Phase 3: Zig FFI layer (probe, extract, emit, VeriSimDB, actions, profiles)", completion = 100 },
   { name = "Phase 4: Ephapax core (Shell, Bridge, Types, Capabilities)", completion = 100 },
-  { name = "Phase 5: 17 game profiles (A2ML definitions)", completion = 100 },
-  { name = "Phase 6: Gossamer GUI (host + 7 panels)", completion = 100 },
+  { name = "Phase 5: 18 game profiles (A2ML definitions)", completion = 100 },
+  { name = "Phase 6: Gossamer GUI (host + 8 panels)", completion = 100 },
   { name = "Phase 7: Panel clade definitions (9 clades + 17 game children)", completion = 100 },
   { name = "Phase 8: PanLL integration (registry, engine, clade files)", completion = 100 },
   { name = "Phase 9: VeriSimDB dedicated instance config", completion = 100 },
@@ -64,4 +64,5 @@ sessions = [
   { date = "2026-04-03b", summary = "Security hardening: replaced 427 AGPL-3.0-or-later headers with MPL-2.0, replaced LICENSE with PMPL text. Fixed critical vuln (executeSSH shell injection — refactored to argv slice + -- separator). Fixed temp-file TOCTOU in gossamer-integration-test.sh (mktemp). Removed dangling-ref getWriter function. Replaced hardcoded test credentials. Added escapeXml to fli-gauge.js, escapeHtml+data-tip escaping to fli-tooltip.js, DOM node clone in fli-editable.js cancelEdit. Eliminated all 8 @ptrCast calls across FFI layer (string literals + [N:0]u8 sentinel buffers). Filled K9 template-hunt.k9.ncl TODO placeholders with GSA deployment content. All 111 Zig tests pass. panic-attack: 0 weak points (was 21)." },
   { date = "2026-04-04b", summary = "Nexus Setup GUI panel: full 7-step graphical wizard added as nav item 2 in Gossamer GUI (between Server Browser and Config Editor). src/gui/panels/nexus-setup/panel.html — profile card grid, Steam vanity→Steam64 resolution inline, typed server config form (toggles/sliders/text), SSH deployment target, Steam credentials + live terminal for staging, provisioner live terminal, verify+report with connect string/watchdog CTA. src/gui/panels/nexus-setup/nexus-setup.eph — IPC contract docs. src/core/Bridge.eph — 5 new handlers: handleSteamResolveVanity, handleSteamPlayerInfo, handleNexusStageFiles, handleNexusProvision, handleNexusVerify. src/gui/host.html — wired at 4 locations (nav, container, panels array, switch case + FLI traits + status list). Operator slots pre-filled: pengie5 + hyperpolymath. Committed f26deda, pushed to GitHub." },
   { date = "2026-06-20", summary = "Maintenance pass (axis-1 must>intend>like, axis-2 corrective>adaptive>perfective). CORRECTIVE: re-stamped 24 .zig/.idr source SPDX headers MPL-2.0 -> AGPL-3.0-or-later to match LICENSE + META.a2ml + steam_client.zig (machine-readable .a2ml/.contractile stay MPL by carve-out); filled INTENT.contractile (was raw template — purpose/anti-purpose/architectural-invariants/ask-before-touching/ecosystem). ADAPTIVE: exported-symbol count 24/22 -> 27 (Steam +3, Nexus run_script/write_server_config +2) in CLAUDE.md + ROADMAP; completion 100% -> honest 93% to match ROADMAP; struck stale critical-next-action (Nexus FFI exports already exist at server_actions.zig:573/:713), replaced with the real open item (Ephapax parser gaps); refreshed ROADMAP revdate + April additions. Test counts (111/112, integration 36/39) left for a verified 'zig build test' run — zig not installed in this container." },
+  { date = "2026-06-21", summary = "CI/governance + Hypatia advisory sweep (PRs #41-#45). #41: hardened workflows — explicit Scorecard wrapper job permissions (contents:read/security-events:write/id-token:write), presence-gated instant-sync repository-dispatch on FARM_DISPATCH_TOKEN, added CodeQL actions language, scoped run.js/Justfile deno perms (allow-read/run/env), fli-editable.js innerHTML to replaceChildren. #42: refreshed standards reusable pins; fixed a staleness-check grep bug (a reusable-pin token in a comment double-matched the single-pin SHA compare). #43: replaced the inert .hypatia-baseline.json (hypatia scan never applies it — only excludes the file itself) with a working .hypatia-ignore suppressing 7 reviewed false positives (2 test-fixture secrets, 3 escaped-markup innerHTML, loopback HTTP, syscall bitCast). #44: stopped .hypatia-ignore tripping its own secret scanner (self-exempt entry + reworded comments). #45: fixed 7 stale src/abi/ to src/interface/abi/ doc refs (SD022); bumped pins to 4ddc926. Result: advisory scan critical=0/high=0, governance staleness green, Validate-Baseline green-by-skip. Verified .hypatia-ignore matching + the staleness script locally (no Zig/Elixir/Hypatia in container). Outstanding: 10 merged branches need manual git push --delete (the git proxy 403s deletions here); estate-standardization-20260607 (2026-06-07, pre-#38) is stale/superseded (its AGPL migration already landed 2026-06-20) — reconcile before any merge; documentation gaps (user panel guides, dev extension guide, maintainer CI/release runbooks) tracked in docs/INDEX.adoc." },
 ]

README.adoc

@@ -24,7 +24,7 @@ GSA can attach to _any_ game server, fingerprint it via protocol probing, extrac
 ----
 ┌─────────────────────────────────────────────────┐
 │  Gossamer GUI (Ephapax + HTML/JS)               │
-│  7 panels, each a Clade citizen with inheritance │
+│  8 panels, each a Clade citizen with inheritance │
 └────────────────────┬────────────────────────────┘
                      │ IPC (gossamer:// bridge)
 ┌────────────────────┴────────────────────────────┐
@@ -69,7 +69,7 @@ just verisimdb-up
 # Build and run the CLI
 just run status              # system status, VeriSimDB health, loaded profiles
 just run probe <host> [port] # fingerprint a game server (default port 27015)
-just run profiles            # list all 17 supported game profiles
+just run profiles            # list all 18 supported game profiles
 
 # Or build and launch the GUI
 just build && just gui

ROADMAP.adoc

@@ -14,8 +14,8 @@ Key capabilities delivered:
 * 10 FFI modules: lifecycle, probe, config_extract, a2ml_emit, verisimdb_client, server_actions, game_profiles, groove_client, steam_client, cli
 * Protocol fingerprinting (8 protocols, 20+ known ports)
 * Config parsing (8 formats: XML, INI, JSON, ENV, YAML, TOML, Lua, KV)
-* 17 game profiles (A2ML files in profiles/)
-* 7 Gossamer GUI panels + 9 panel clades
+* 18 game profiles (A2ML files in profiles/)
+* 8 Gossamer GUI panels + 9 panel clades
 * VeriSimDB on 2 ports (main 8090, backup 8091 for game saves)
 * A2ML serialisation, parsing, and config diff
 * Groove voice alerting via .well-known
@@ -44,7 +44,7 @@ Test suites:
 * [x] Server actions (start/stop/restart/logs)
 * [x] Game profile registry and parser
 * [x] Groove client for voice alerting
-* [x] Gossamer GUI panels (7 panels)
+* [x] Gossamer GUI panels (8 panels)
 * [x] Panel clade system (9 base + game children)
 * [x] Idris2 ABI definitions (Types, Foreign, Layout)
 * [x] VeriSimDB dual-instance deployment (main + backup)

docs/INDEX.adoc

@@ -0,0 +1,80 @@
+= Game Server Admin — Documentation Index
+:revdate: 2026-06-21
+
+Audience-segmented map of the GSA documentation. Start here, then pick your role.
+
+[NOTE]
+====
+Status legend: *live* = written and current; *thin* = exists but covers only
+setup/basic-run; *planned* = a known gap, scoped below, tracked for the v1.0.0
+documentation pass. See `ROADMAP.adoc` for release gates and `.claude/CLAUDE.md`
+for the codebase quick-context.
+====
+
+== End users
+_You run and administer game servers via the Gossamer GUI and the `gsa` CLI._
+
+[cols="2,1,4"]
+|===
+| Document | Status | Covers
+
+| `README.adoc` | live | Overview, quick-start, `gsa` CLI reference, supported games
+| `USER-CONFIG.md` | live | Nickel config: defaults, favourites, troubleshooting
+| `docs/QUICKSTART.adoc` | thin | One-liner pointer — not a real getting-started
+| GUI panel guide | *planned* | One section per panel (8: server-browser, config-editor, server-actions, live-logs, health-dashboard, config-history, cross-search, nexus-setup). **`nexus-setup`, the 7-step provisioning wizard, is entirely undocumented.**
+| Game-profile selection | *planned* | Which game → which of the 18 profiles; port/protocol table
+| Admin workflows | *planned* | Add a server; manage config across servers; roll back via config history
+|===
+
+== Developers
+_You build GSA, extend it, or contribute code across the Gossamer GUI → Zig FFI → Idris2 ABI → VeriSimDB stack._
+
+[cols="2,1,4"]
+|===
+| Document | Status | Covers
+
+| `README.adoc` | live | Architecture diagram, module map, "Adding a Game Profile" snippet
+| `docs/developer/ABI-FFI-README.adoc` | live | Idris2 ABI + Zig FFI standard; C/Idris2/Rust/Julia examples (strong)
+| `TOPOLOGY.md` | live | System architecture + data flow
+| `docs/decisions/` | live | Architecture decision records (RSR adoption)
+| FFI module reference | *planned* | Per-module docs for the 11 FFI modules (signatures, the 13 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`
+| Architecture rationale | *planned* | Why Ephapax / Idris2 / Zig / VeriSimDB; when to touch each layer
+|===
+
+== Maintainers
+_You release, run CI/CD, operate containers, and manage governance + security scanning._
+
+[cols="2,1,4"]
+|===
+| Document | Status | Covers
+
+| `docs/governance/MAINTENANCE-CHECKLIST.adoc` | live | Three-axis model, hygiene, ABI purity, panic-attack (strong)
+| `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
+| 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
+|===
+
+== Machine-readable layer
+_For AI agents and tooling. Read `0-AI-MANIFEST.a2ml` FIRST._
+
+* `0-AI-MANIFEST.a2ml` — canonical entry point, invariants, startup checklist.
+* `.machine_readable/6a2/` — `STATE.a2ml` (status, blockers, session history), `META`, `ECOSYSTEM`, `AGENTIC`, `NEUROSYM` (Hypatia config + `.hypatia-ignore` scope), `PLAYBOOK`.
+* `.machine_readable/` contractiles — `INTENT`/`MUST`/`TRUST`/`DUST` (purpose, hard CI rules, trust boundaries, cleanup).
+* `.hypatia-ignore` — reviewed false-positive suppressions (the active mechanism).
+* `.claude/CLAUDE.md` — human-friendly codebase guide.
+
+== Wiki status
+`docs/wikis/` is a stub that declares an intent to sync to a forge-hosted wiki but
+is **unpopulated**. The `docs/` tree also carries several empty placeholder
+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.