# Agrarian Self-Hosted AI Development Stack

This stack is meant to reduce pressure on Codex over time, not replace it
immediately. The first production target is supervised local assistance:
repository awareness, documentation, small safe edits, tests/builds, and clear
Codex escalation when local tooling is over its head.

## Current Services

- Gitea:
  `http://192.168.5.21:3000/nathan/agrarian-game.git`
- Ollama:
  `http://192.168.5.23:11434`
- Open WebUI:
  `http://192.168.5.26:8085`
- Local AI worker VM:
  `LinaAI / 192.168.5.27`
- Primary Unreal/Linux development VM:
  `unreal-engine / 192.168.5.20`

## Current Local Model

- `qwen2.5-coder:7b`
- Role:
  repo summaries, documentation, small patch suggestions, test generation,
  straightforward scripts, and structured handoff preparation.
- Not the role:
  broad Unreal architecture changes, risky save/multiplayer/economy rewrites,
  security-sensitive code, or autonomous merges.

## Operating Model

1. Refresh LinaAI project memory when context may be stale:
   `Scripts/linaai_refresh_knowledge.sh`.
2. Build a compact local context pack when needed:
   `Scripts/linaai_bootstrap_context.sh`.
3. Start with `Scripts/linaai_task.sh`, not raw Aider, for normal work.
4. Qwen/Ollama performs a preflight risk and confidence check.
5. Default confidence threshold is `0.75`.
6. High-risk tasks or low-confidence tasks route to Codex automatically.
7. Aider runs only for acceptable supervised local work.
8. If Aider fails, `Scripts/linaai_task.sh` writes a status file and calls
   Codex through `Scripts/ai_codex_escalate.sh`.
9. Codex escalation uses the npm Codex CLI, not the API.
10. Human review controls merges.

The operating manual, knowledge map, and secrets policy live in:

- `Docs/AI/LinaAIOperatingManual.md`
- `Docs/AI/LinaAIKnowledgeMap.md`
- `Docs/AI/LinaAISecretsPolicy.md`

## Codex Escalation

Use `Scripts/ai_codex_escalate.sh` with a completed task status file. The
script prefers a locally installed `codex` command and falls back to
`npx -y @openai/codex exec`.

For normal tasks, use:

```bash
cd ~/repos/AgrarianGame
Scripts/linaai_refresh_knowledge.sh
Scripts/linaai_bootstrap_context.sh
Scripts/linaai_task.sh "your task here"
```

To test automatic escalation without editing files:

```bash
Scripts/linaai_task.sh --dry-run --force-escalate "Test escalation path only."
```

On `LinaAI`, the npm Codex CLI is installed, but it still needs an authenticated
Codex login before cloud escalation can run:

```bash
ssh nathan@192.168.5.27
codex login
```

Codex should be called for:

- confidence below `0.75`,
- two failed build/test attempts,
- Unreal compile errors that persist,
- tasks touching save systems, multiplayer, auth, payments, AGR wallet
  integration, marketplace logic, migrations, or core architecture,
- patches that grow beyond the intended small scope,
- contradictions between local model output and official/project docs.

## VM Boundaries

- `LinaAI` owns local AI coding tools, Aider, Codex CLI escalation wrappers,
  repo indexing, documentation generation, and small supervised branch work.
- `unreal-engine` owns Unreal Engine source, editor builds, commandlets, and
  game compile/package verification.
- Keep these roles separated so AI tooling experiments do not destabilize the
  Unreal build host.

## Immediate Next Work

- Verify Open WebUI model selection uses the Ollama backend at
  `http://192.168.5.23:11434`.
- Use Aider from `LinaAI`, not from `unreal-engine`.
- Authenticate the npm Codex CLI on `LinaAI` so escalation can run from the AI
  worker VM.
- Build project memory inside this repo under `Docs/` rather than creating a
  separate documentation repository.
- Add small local-agent tasks first: summarize systems, write docs, generate
  tests, inspect logs, and prepare Codex handoffs.