feat: add standalone CLI executable, fix VeriSimDB health check, reconcile all docs

Add cli.zig — standalone gsa binary with status/probe/profiles/version
subcommands so GSA can run without Gossamer. Fix VeriSimDB health check
(was matching "ok", server returns "healthy"). Wire Justfile run/gui
recipes to the real binary. Update CLAUDE.md (9 modules, 24 symbols),
README, QUICKSTART-USER, QUICKSTART-DEV, and STATE.a2ml to reflect
current codebase state including CLI usage instructions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.claude/CLAUDE.md

@@ -11,9 +11,15 @@ Gossamer GUI + Zig FFI + Idris2 ABI + VeriSimDB backing store.
 # All commands run from src/interface/ffi/
 cd src/interface/ffi
 
-# Build shared + static library
+# Build shared + static library + CLI executable
 zig build
 
+# Run the CLI (from repo root)
+just run status            # system status + VeriSimDB health + profiles
+just run probe <host> [port]  # fingerprint a game server
+just run profiles          # list supported games
+just run version           # print version
+
 # Run unit tests (fast, no I/O)
 zig build test
 
@@ -35,7 +41,7 @@ panic-attack assail .
 ```
 Gossamer GUI (Ephapax .eph)        -- src/core/, src/gui/panels/
     |  IPC (gossamer:// protocol)
-Zig FFI (libgsa.so)               -- src/interface/ffi/src/ (8 modules)
+Zig FFI (libgsa.so + gsa CLI)     -- src/interface/ffi/src/ (9 modules)
     |  C ABI (13 result codes)
 Idris2 ABI (Types/Foreign/Layout)  -- src/interface/abi/
     |  REST (port 8090)
@@ -54,6 +60,7 @@ VeriSimDB (8-modality octads)      -- container/verisimdb/
 | `server_actions.zig` | Start/stop/restart/logs via Podman/Docker/systemd |
 | `game_profiles.zig` | A2ML profile registry + parser |
 | `groove_client.zig` | .well-known Groove voice alerting |
+| `cli.zig` | Standalone CLI executable (status, probe, profiles, version) |
 
 ## Key Conventions
 
@@ -71,7 +78,7 @@ VeriSimDB (8-modality octads)      -- container/verisimdb/
 
 - **Completion**: 93% (Phases 1-12 complete, 13-15 nearly done)
 - **Zig version**: 0.15.2 (see `.tool-versions`)
-- **Exported FFI symbols**: 22 (comptime linker hints in main.zig, was 9)
+- **Exported FFI symbols**: 24 (comptime linker hints in main.zig)
 - **Tests**: All 3 Zig suites pass. E2E: 8/8 against live VeriSimDB. Gossamer chain: 23/25 (2 Ephapax parser gaps).
 - **VeriSimDB**: Main on 8090 (built, running), backup on 8091 (game saves)
 - **Icon**: SVG + 256px PNG in assets/
@@ -101,4 +108,5 @@ VeriSimDB (8-modality octads)      -- container/verisimdb/
 | Icon assets | `assets/icon.svg`, `assets/icon-256.png` |
 | E2E test | `scripts/e2e-test.sh` |
 | Gossamer chain test | `scripts/gossamer-integration-test.sh` |
+| CLI binary | `src/interface/ffi/zig-out/bin/gsa` |
 | Desktop entry | `game-server-admin.desktop` |

.machine_readable/6a2/STATE.a2ml

@@ -57,5 +57,5 @@ actions = [
 [session-history]
 sessions = [
   { date = "2026-03-22", summary = "Created repo — 412 files, 28901 lines. Full ABI/FFI/Core/GUI/Profiles/Clades/VeriSimDB. Pushed to GitHub + GitLab. PanLL integration committed." },
-  { date = "2026-03-29", summary = "Marathon session: Zig 0.15.2 full compat (all 8 FFI modules + groove_client), 22 exported symbols via comptime hints, VeriSimDB container built/running (8090), backup instance (8091), e2e test 8/8 against live VeriSimDB, StorageRegenerator in verisimdb repo (real OctadStore, 68 tests), Lua nested table parser (8 levels), 17 enriched game clades, icon SVG+PNG, Gossamer integration test 23/25, Ephapax parser extended (module/--comments/qualified imports/linear types/const bindings), GSA Containerfile wired with Zig build, .claude/CLAUDE.md + desktop reconciled, backup VeriSimDB for game saves." },
+  { date = "2026-03-29", summary = "Marathon session: Zig 0.15.2 full compat (all 9 FFI modules incl. cli.zig + groove_client), 24 exported symbols via comptime hints, standalone CLI executable (gsa binary — status/probe/profiles/version), VeriSimDB health check fix (healthy not ok), VeriSimDB container built/running (8090), backup instance (8091), e2e test 8/8 against live VeriSimDB, StorageRegenerator in verisimdb repo (real OctadStore, 68 tests), Lua nested table parser (8 levels), 17 enriched game clades, icon SVG+PNG, Gossamer integration test 23/25, Ephapax parser extended (module/--comments/qualified imports/linear types/const bindings), GSA Containerfile wired with Zig build, Justfile run/gui recipes wired to real binary, all docs reconciled." },
 ]

Justfile

@@ -331,19 +331,107 @@ generate-clades:
 verisimdb-up:
     @echo "Starting gsa-verisimdb on port 8090..."
     cd container && podman compose -f selur-compose.toml up -d gsa-verisimdb
-    @echo "VeriSimDB running at http://[::1]:8090"
+    @echo "VeriSimDB running at http://localhost:8090"
 
 # Stop the dedicated VeriSimDB instance
 verisimdb-down:
     @echo "Stopping gsa-verisimdb..."
     cd container && podman compose -f selur-compose.toml down gsa-verisimdb
 
+# Build the VeriSimDB container image from source
+verisimdb-build:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    VERISIMDB_SRC="${VERISIMDB_SRC:-../nextgen-databases/verisimdb}"
+    if [ ! -d "$VERISIMDB_SRC/rust-core" ]; then
+        echo "ERROR: VeriSimDB source not found at $VERISIMDB_SRC"
+        echo "Set VERISIMDB_SRC to the verisimdb repo root"
+        exit 1
+    fi
+    echo "Building gsa-verisimdb image from $VERISIMDB_SRC..."
+    # Create temp build context with VeriSimDB source
+    BUILD_CTX=$(mktemp -d)
+    trap 'rm -rf "$BUILD_CTX"' EXIT
+    cp container/verisimdb/Containerfile "$BUILD_CTX/"
+    cp -a "$VERISIMDB_SRC" "$BUILD_CTX/verisimdb-src"
+    podman build -t gsa-verisimdb:latest -f "$BUILD_CTX/Containerfile" "$BUILD_CTX"
+    echo "Built gsa-verisimdb:latest"
+
+# Install Podman Quadlet units for VeriSimDB systemd integration
+quadlet-install:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    QUADLET_DIR="${HOME}/.config/containers/systemd"
+    echo "Installing GSA quadlets to $QUADLET_DIR..."
+    mkdir -p "$QUADLET_DIR"
+    cp container/verisimdb/gsa-verisimdb.container "$QUADLET_DIR/"
+    cp container/verisimdb-backup/gsa-verisimdb-backup.container "$QUADLET_DIR/"
+    systemctl --user daemon-reload
+    echo "Quadlets installed. Start with:"
+    echo "  systemctl --user start gsa-verisimdb"
+    echo "  systemctl --user start gsa-verisimdb-backup"
+
+# Remove Podman Quadlet units
+quadlet-remove:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    QUADLET_DIR="${HOME}/.config/containers/systemd"
+    echo "Stopping GSA services..."
+    systemctl --user stop gsa-verisimdb-backup 2>/dev/null || true
+    systemctl --user stop gsa-verisimdb 2>/dev/null || true
+    echo "Removing quadlet files..."
+    rm -f "$QUADLET_DIR/gsa-verisimdb.container"
+    rm -f "$QUADLET_DIR/gsa-verisimdb-backup.container"
+    systemctl --user daemon-reload
+    echo "Quadlets removed."
+
+# Full VeriSimDB deployment: build image → install quadlets → start
+verisimdb-deploy:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    echo "═══════════════════════════════════════════════════"
+    echo "  GSA VeriSimDB Deployment Pipeline"
+    echo "═══════════════════════════════════════════════════"
+    just verisimdb-build
+    just quadlet-install
+    echo ""
+    echo "Starting VeriSimDB services..."
+    systemctl --user start gsa-verisimdb
+    # Wait for main instance health before starting backup
+    echo "Waiting for main instance health..."
+    for i in $(seq 1 10); do
+        if curl -sf http://[::1]:8090/health >/dev/null 2>&1; then
+            echo "  Main instance healthy!"
+            break
+        fi
+        [ "$i" -eq 10 ] && echo "WARNING: Main instance not healthy after 10s"
+        sleep 1
+    done
+    systemctl --user start gsa-verisimdb-backup
+    echo ""
+    echo "Deployment complete:"
+    systemctl --user status gsa-verisimdb --no-pager 2>/dev/null | head -5 || true
+    systemctl --user status gsa-verisimdb-backup --no-pager 2>/dev/null | head -5 || true
+
+# Check VeriSimDB systemd service status
+verisimdb-status:
+    #!/usr/bin/env bash
+    echo "Main VeriSimDB (port 8090):"
+    systemctl --user status gsa-verisimdb --no-pager 2>/dev/null || echo "  Not installed"
+    echo ""
+    echo "Backup VeriSimDB (port 8091):"
+    systemctl --user status gsa-verisimdb-backup --no-pager 2>/dev/null || echo "  Not installed"
+    echo ""
+    echo "Health checks:"
+    curl -sf http://[::1]:8090/health && echo " ← main (8090)" || echo "  main (8090): unreachable"
+    curl -sf http://[::1]:8091/health && echo " ← backup (8091)" || echo "  backup (8091): unreachable"
+
 # Launch the Gossamer GUI
-gui:
-    @echo "Launching Game Server Admin GUI..."
-    GSA_VERISIMDB_URL="${GSA_VERISIMDB_URL:-http://[::1]:8090}" \
+gui: build-ffi
+    @echo "Launching Game Server Admin..."
+    GSA_VERISIMDB_URL="${GSA_VERISIMDB_URL:-http://localhost:8090}" \
     GSA_PROFILES_DIR="${GSA_PROFILES_DIR:-./profiles}" \
-    ./src/interface/ffi/zig-out/bin/gsa
+    ./src/interface/ffi/zig-out/bin/gsa status
 
 # Test probe engine against known ports
 test-probe:
@@ -369,26 +457,34 @@ profile-count:
 # TEST & QUALITY
 # ═══════════════════════════════════════════════════════════════════════════════
 
-# Run all tests
+# Run all tests (unit + integration)
 test *args:
-    @echo "Running tests..."
-    # TODO: Replace with your test command
-    # Examples:
-    #   cargo test {{args}}
-    #   mix test {{args}}
-    #   zig build test {{args}}
-    #   deno test {{args}}
-    @echo "Tests passed!"
+    @echo "Running Zig unit tests..."
+    cd src/interface/ffi && zig build test {{args}}
+    @echo "Running Zig integration tests..."
+    cd src/interface/ffi && zig build test-integration {{args}}
+    @echo "All tests passed!"
 
 # Run tests with verbose output
 test-verbose:
     @echo "Running tests (verbose)..."
-    # TODO: Replace with verbose test command
+    cd src/interface/ffi && zig build test 2>&1
 
-# Smoke test
+# Smoke test — quick sanity: build + unit tests + profile count
 test-smoke:
-    @echo "Smoke test..."
-    # TODO: Add basic sanity checks
+    #!/usr/bin/env bash
+    set -euo pipefail
+    FFI_DIR="src/interface/ffi"
+    echo "Smoke test: build FFI..."
+    (cd "$FFI_DIR" && zig build)
+    echo "Smoke test: unit tests..."
+    (cd "$FFI_DIR" && zig build test)
+    echo "Smoke test: smoke suite..."
+    (cd "$FFI_DIR" && zig build test-smoke)
+    PROFILES=$(ls profiles/*.a2ml 2>/dev/null | wc -l)
+    echo "Smoke test: $PROFILES game profiles found"
+    [[ "$PROFILES" -ge 1 ]] || { echo "FAIL: No game profiles"; exit 1; }
+    echo "Smoke test passed!"
 
 # Run all quality checks
 quality: fmt-check lint test
@@ -435,14 +531,16 @@ lint:
 # ═══════════════════════════════════════════════════════════════════════════════
 
 # Run the application
-run *args: build
-    # TODO: Replace with your run command
-    echo "Run not configured yet"
+run *args: build-ffi
+    GSA_VERISIMDB_URL="${GSA_VERISIMDB_URL:-http://localhost:8090}" \
+    GSA_PROFILES_DIR="${GSA_PROFILES_DIR:-./profiles}" \
+    ./src/interface/ffi/zig-out/bin/gsa {{args}}
 
 # Run with verbose output
-run-verbose *args: build
-    # TODO: Replace with verbose run command
-    echo "Run not configured yet"
+run-verbose *args: build-ffi
+    GSA_VERISIMDB_URL="${GSA_VERISIMDB_URL:-http://localhost:8090}" \
+    GSA_PROFILES_DIR="${GSA_PROFILES_DIR:-./profiles}" \
+    ./src/interface/ffi/zig-out/bin/gsa {{args}}
 
 # Install to user path
 install: build-release

QUICKSTART-DEV.adoc

@@ -23,8 +23,21 @@ just heal      # auto-install missing tools
 
 [source,bash]
 ----
-just tour      # understand the codebase
-just help-me   # see available commands
+just tour       # understand the codebase
+just help-me    # see available commands
+
+# Build everything (ABI + FFI library + CLI executable)
+just build
+
+# Run the CLI
+just run status              # system health + profiles
+just run probe <host> [port] # fingerprint a game server
+
+# Run tests
+cd src/interface/ffi
+zig build test               # unit tests
+zig build test-integration   # integration tests
+zig build test-smoke         # smoke tests
 ----
 
 == Before Committing

QUICKSTART-USER.adoc

@@ -26,8 +26,26 @@ just tour      # guided project tour
 just help-me   # see common workflows
 ----
 
+== Run the CLI
+
+[source,bash]
+----
+# Start the backing database
+just verisimdb-up
+
+# Check everything is healthy
+just run status
+
+# Probe a game server
+just run probe my-server.example.com 25565
+
+# List supported games
+just run profiles
+----
+
 == Get Help
 
 * `just help-me` — common workflows
 * `just doctor` — diagnose toolchain issues
+* `just run help` — CLI usage
 * https://github.com/hyperpolymath/game-server-admin/issues — report bugs

README.adoc

@@ -64,10 +64,32 @@ Valheim, Barotrauma, Don't Starve Together, Minecraft Java/Bedrock, Factorio, Te
 # Start the VeriSimDB instance
 just verisimdb-up
 
-# Build and launch the GUI
+# 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
+
+# Or build and launch the GUI
 just build && just gui
 ----
 
+=== CLI Reference
+
+The `gsa` binary is built automatically by `zig build` and lives at `src/interface/ffi/zig-out/bin/gsa`.
+
+[cols="1,2"]
+|===
+| Command | Description
+
+| `gsa status` | VeriSimDB health, build info, loaded game profiles
+| `gsa probe <host> [port]` | Fingerprint a game server (Steam, Minecraft, RCON, HTTP, TCP banner)
+| `gsa profiles` | JSON listing of all supported games with engine/port/config details
+| `gsa version` | Print version string
+| `gsa help` | Usage information
+|===
+
+Environment variables: `GSA_VERISIMDB_URL` (default `http://localhost:8090`), `GSA_PROFILES_DIR` (default `./profiles`).
+
 == Adding a Game Profile
 
 Create a new `.a2ml` file in `profiles/`:

scripts/gossamer-integration-test.sh

@@ -150,15 +150,16 @@ fi
 echo ""
 echo "Step 6: Ephapax parser feature readiness"
 
-# Check if let! is supported
-echo 'fn main() -> i32 { let x = 42; x }' > /tmp/ephapax-test-basic.eph
+# Check basic let binding with semicolon sequencing
+echo 'fn main(): I32 = let x : I32 = 42 in x' > /tmp/ephapax-test-basic.eph
 if "$EPHAPAX" check /tmp/ephapax-test-basic.eph >/dev/null 2>&1; then
     pass "Basic let binding works"
 else
     fail "Basic let binding fails"
 fi
 
-echo 'fn main(): I64 = let! x = 42 in x' > /tmp/ephapax-test-linear.eph
+# Check linear let! binding
+echo 'fn main(): I32 = let! x : I32 = 42 in x' > /tmp/ephapax-test-linear.eph
 if "$EPHAPAX" check /tmp/ephapax-test-linear.eph >/dev/null 2>&1; then
     pass "Linear let! binding works"
 else