hyperpolymath
diff --git a/‎.github/workflows/cross-platform.yml‎
Lines changed: 12 additions & 0 deletions b/‎.github/workflows/cross-platform.yml‎
Lines changed: 12 additions & 0 deletions
diff --git a/‎.machine_readable/6a2/ECOSYSTEM.a2ml‎
Lines changed: 16 additions & 6 deletions b/‎.machine_readable/6a2/ECOSYSTEM.a2ml‎
Lines changed: 16 additions & 6 deletions
diff --git a/‎.machine_readable/6a2/META.a2ml‎
Lines changed: 8 additions & 2 deletions b/‎.machine_readable/6a2/META.a2ml‎
Lines changed: 8 additions & 2 deletions
diff --git a/‎ROADMAP.adoc‎
Lines changed: 1 addition & 1 deletion b/‎ROADMAP.adoc‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎docs/INDEX.adoc‎
Lines changed: 10 additions & 2 deletions b/‎docs/INDEX.adoc‎
Lines changed: 10 additions & 2 deletions
diff --git a/‎docs/developer/CONFIG-FORMATS.adoc‎
Lines changed: 96 additions & 0 deletions b/‎docs/developer/CONFIG-FORMATS.adoc‎
Lines changed: 96 additions & 0 deletions
diff --git a/‎docs/maintainer/RELEASE-CHECKLIST.adoc‎
Lines changed: 78 additions & 0 deletions b/‎docs/maintainer/RELEASE-CHECKLIST.adoc‎
Lines changed: 78 additions & 0 deletions
diff --git a/‎panel-clades/gsa-nexus-setup/GsaNexusSetup.a2ml‎
Lines changed: 42 additions & 0 deletions b/‎panel-clades/gsa-nexus-setup/GsaNexusSetup.a2ml‎
Lines changed: 42 additions & 0 deletions
diff --git a/‎panel-clades/gsa-nexus-setup/config.k9.ncl‎
Lines changed: 28 additions & 0 deletions b/‎panel-clades/gsa-nexus-setup/config.k9.ncl‎
Lines changed: 28 additions & 0 deletions
diff --git a/‎panels/manifest.json‎
Lines changed: 2 additions & 1 deletion b/‎panels/manifest.json‎
Lines changed: 2 additions & 1 deletion
@@ -68,3 +68,15 @@ jobs:
       - name: Property Tests
         working-directory: src/interface/ffi
         run: zig build test-property
+
+      - name: Behavioral Tests (mock servers)
+        working-directory: src/interface/ffi
+        run: zig build test-behavioral
+
+      - name: CLI Tests
+        working-directory: src/interface/ffi
+        run: zig build test-cli
+
+      - name: Fuzz seed corpus
+        working-directory: src/interface/ffi
+        run: zig build fuzz
@@ -6,21 +6,31 @@
 
 [metadata]
 version = "0.1.0"
-last-updated = "2026-03-22"
+last-updated = "2026-07-02"
 
 [project]
 name = "game-server-admin"
-purpose = ""  # TODO: describe project purpose
-role = ""  # TODO: describe project role  # e.g. ffi-infrastructure, cli-tool, library, service
+purpose = "Universal game server probe, configuration management, and administration via Gossamer webview + VeriSimDB backing store. Extracts config into A2ML format with full provenance tracking. The client half of a multi-repo ecosystem."
+role = "ffi-infrastructure"
 
 [position-in-ecosystem]
 tier = "infrastructure"  # 1 | 2 | infrastructure
 
 [related-projects]
 # relationship types: sibling-standard, dependency, dependent, inspiration, potential-consumer
-# - { name = "language-bridges", relationship = "sibling-standard" }
-# - { name = "hypatia", relationship = "potential-consumer" }
+related = [
+  { name = "gossamer", relationship = "dependency" },        # webview shell; loads libgsa via dlopen
+  { name = "ephapax", relationship = "dependency" },          # .eph GUI/bridge source language
+  { name = "verisimdb", relationship = "dependency" },        # 8-modality backing store (REST :8090)
+  { name = "groove", relationship = "potential-consumer" },   # voice/text alerting over .well-known
+  { name = "standards", relationship = "sibling-standard" },  # org reusable CI workflows
+]
 
 [integration-points]
 # External systems this project connects to
-# - { system = "gitbot-fleet", direction = "outbound", protocol = "repository_dispatch" }
+integrations = [
+  { system = "verisimdb", direction = "outbound", protocol = "REST" },
+  { system = "steam-web-api", direction = "outbound", protocol = "HTTPS" },
+  { system = "groove", direction = "outbound", protocol = "HTTP" },
+  { system = "podman", direction = "outbound", protocol = "cli-exec" },
+]
@@ -9,8 +9,14 @@ version = "0.1.0"
 last-updated = "2026-03-22"
 
 [project-info]
-type = "library"  # TODO: update type (library|binary|service|website|monorepo)  # library | binary | monorepo | service | website
-languages = []             # e.g. ["rust", "zig", "idris2"]
+type = "library"  # libgsa.so is the primary artifact (+ the gsa CLI binary)
+languages = ["zig", "idris2", "ephapax"]
+# NOTE: license is unsettled and pending a maintainer decision. The LICENSE
+# file body and all Zig/Idris source SPDX headers are currently MPL-2.0, while
+# the panel descriptors declare AGPL-3.0-or-later and this field says AGPL —
+# a genuine conflict. See the human checklist / docs/legal (to be added once
+# the direction is chosen). Left as-is deliberately; do not mass-edit headers
+# without that decision.
 license = "AGPL-3.0-or-later"
 author = "Jonathan D.A. Jewell (hyperpolymath)"
 
 
@@ -65,6 +65,6 @@ Test suites:
 
 == Future
 
-* Additional game profiles beyond 17
+* Additional game profiles beyond the current 18
 * Live server monitoring dashboard
 * Multi-server fleet management
@@ -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.
@@ -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.
@@ -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.
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
+
+[clade-metadata]
+id = "gsa-nexus-setup"
+name = "GSA Nexus Setup"
+short-name = "Nexus"
+version = "1.0.0"
+kind = "wizard"
+icon = "wand-sparkles"
+description = "Guided 7-step wizard to deploy a new managed game server: profile selection, Steam operators, configuration, target host, file staging, provisioning, and health verification. Mirrors the scripts/wizard.sh flow in the Gossamer GUI."
+
+[clade-traits]
+has-backend = true
+has-scanning = false
+has-persistence = false
+has-work-items = false
+has-real-time = true
+is-directive = true
+is-readonly = false
+is-ambient = false
+
+[clade-capabilities]
+capabilities = ["Network", "Shell", "ProcessSpawn", "Containerised"]
+
+[clade-protocols]
+protocols = ["REST", "TauriIPC"]
+
+[clade-taxonomy]
+inherits-from = "gsa"
+sibling-clades = ["gsa-actions", "gsa-config", "gsa-browser"]
+supersedes = ""
+
+[clade-fli]
+fli-inherits = ["fli-terminal"]
+
+[clade-panel-integration]
+panel-id = "PanelGsaNexusSetup"
+model-module = "GsaNexusSetupModel"
+component-module = "GsaNexusSetup"
+command-module = "GsaNexusSetupCmd"
+module-module = "GsaNexusSetupModule"
@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: MPL-2.0
+{
+  pedigree = {
+    name = "gsa-nexus-setup-config",
+    version = "1.0.0",
+    author = "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>",
+    leash = 'Kennel,
+  },
+  panel = {
+    id = "GsaNexusSetup",
+    short_name = "Nexus",
+    description = "Guided 7-step wizard to deploy a new managed game server",
+    has_backend = true,
+    clade_id = "gsa-nexus-setup",
+    isolation_tier = "native",
+  },
+  wiring = {
+    model_slice = "gsaNexusSetup",
+    msg_namespace = "gsaNexusSetupMsg",
+    view_route = "PanelGsaNexusSetup",
+    module_name = "GsaNexusSetup",
+  },
+  obligations = {
+    requires_tests = true,
+    requires_backend_health = true,
+    requires_clade_manifest = true,
+  },
+}
@@ -92,7 +92,8 @@
     "panels/live-logs/panel.json",
     "panels/health-dashboard/panel.json",
     "panels/config-history/panel.json",
-    "panels/cross-search/panel.json"
+    "panels/cross-search/panel.json",
+    "panels/nexus-setup/panel.json"
   ],
   "capabilities": [
     "Network",