correx/docs/qa/ENV.md

Correx live-QA environment — bring-up runbook

The plans in docs/qa/QA-*.md cite observable signals (events, logs, files, TUI renders). This runbook stands up the stack that produces them. Run it on a capable box (JDK 21, Go ≥ 1.24, Docker, a GPU + GGUF model for any model-dependent plan).

Helper scripts live in scripts/qa/ (see scripts/qa/README.md).

Low-RAM note: a machine-local ~/.gradle/gradle.properties on the dev box caps the Gradle/Kotlin heap (-Xmx768m, parallel=false) for a 1.9 GB machine. It is not committed. On a QA box with real RAM, delete it (or ignore it) so builds aren't throttled.

---

Prerequisites

• JDK 21 (java -version → 21).
• Go ≥ 1.24 — the TUI builds via GOTOOLCHAIN=auto (go.mod pins go 1.24.2); the toolchain auto-downloads if your go is older.
• Docker — only for SearXNG (research-workflow QA).
• llama-server binary + at least one GGUF model — for any model-dependent plan.
• (optional) an embedder model/endpoint — required for the architect-contradiction plan and any L3-retrieval-dependent behavior ([router.embedder] backend = "llamacpp").

---

1. Config

Correx reads ~/.config/correx/config.toml plus workflows/, prompts/, schemas/ alongside it. Stale copies cause silent bugs (BACKLOG ops note), so sync from the repo:

scripts/qa/sync-config.sh        # copies examples/workflows + prompts + docs/schemas
                                 # and seeds config.toml from docs/sample-config.toml IF ABSENT

Then edit ~/.config/correx/config.toml for the plan you're running:

• Model — pick ONE:
  • Managed ([[models]] + [models]): correx spawns llama-server at [models].host:port (default 127.0.0.1:10000) and kills it on shutdown. Simplest.
  • Static ([[providers]], type llamacpp, url): you run llama-server yourself. Use this for the llama-health plan so you can stop the server independently of correx.
• [project] enabled = true — required for project memory + the architect-contradiction plan (it queries the project:<repoRoot> L3 namespace written at session end).
• [router.embedder] backend = "llamacpp" (not noop) — required wherever embeddings matter (architect contradiction, L3 retrieval). noop makes every distance meaningless.
• [tools.research] enabled = true + searxng_url — for the research/egress plan.
• [health] enabled = true — for the llama-health plan; note interval_ms (probe cadence).

A [[artifacts]] entry must exist for every LLM-emitted artifact kind a workflow produces (schemas under ~/.config/correx/schemas/). sync-config.sh copies the schemas; confirm the [[artifacts]] table in config.toml references the kinds your workflow uses.

2. llama-server

• Managed: nothing to start — correx launches it. The health probe pings http://<[models].host>:<[models].port>/health.
• External/static: start your llama-server on the url host:port; its /health must 2xx.

  llama-server -m ~/models/<model>.gguf --host 127.0.0.1 --port 10000
  

3. SearXNG (research-workflow QA only)

scripts/qa/searxng-up.sh         # http://localhost:8888, JSON format enabled
# ... run research QA ...
scripts/qa/searxng-down.sh

Gotcha: SearXNG ships with only the html output format; the research web_search needs the JSON API. searxng-up.sh writes a settings.yml enabling formats: [html, json] and mounts it. Without that, web_search returns nothing and the workflow stalls.

4. Start the server

./gradlew :apps:server:run        # mainClass com.correx.apps.server.MainKt, listens on :8090
# or build a runnable dist once and reuse it:
./gradlew :apps:server:installDist
apps/server/build/install/server/bin/server

Gotcha: do not rebuild jars while the server JVM is running — lazy classloading breaks (NoClassDefFoundError). Stop the server first, rebuild, restart.

5. Start the TUI

cd apps/tui-go
GOTOOLCHAIN=auto go build -o correx-tui .
./correx-tui -host localhost -port 8090      # flags default to localhost:8090

6. Evidence tools (what the plans cite)

Source	Command / where
Event log (the truth)	./gradlew :apps:cli:run --args="events <sessionId>" or GET /sessions/{id}/events
Deterministic replay	./gradlew :apps:cli:run --args="replay <sessionId>"
System health	./gradlew :apps:cli:run --args="health"
Server logs	stdout of :apps:server:run — MDC carries sessionId
Files on disk	e.g. <workspaceRoot>/.correx/project.toml (idea-promotion plan)
TUI render	the running correx-tui

(Once :apps:cli:installDist is built, apps/cli/build/install/cli/bin/cli events <id> works too.)

Teardown

1. Stop the server (Ctrl-C) — a managed [[models]] llama-server is killed by the shutdown hook.
2. scripts/qa/searxng-down.sh if you started it.
3. External llama-server: stop it yourself.

---

Per-plan env matrix

QA plan	model	embedder=llamacpp	SearXNG	project.enabled	workspace .correx/
QA-research-egress	yes (tool-calling)	no	yes	no	no
QA-architect-contradiction	yes	yes	no	yes	repo root, 2 sessions same process
QA-llama-health-probe	yes (static path to kill)	no	no	no	no
QA-idea-promotion	router only (or seed event)	no	no	no	yes (bound workspace)
QA-reviewer-static-first	yes	no	no	no	seed StaticFindingsRecordedEvent
QA-brief-echo-gate	yes (the prod candidate)	no	no	no	analyst brief with criteria