# LinaAI Operating Manual

LinaAI is the self-hosted AI development worker for Agrarian and related
projects. Its purpose is to provide project memory, safe local assistance,
repeatable repo inspection, small supervised edits, build/test automation, and
clean escalation to Codex when the local model is not the right tool.

LinaAI is not a fully autonomous developer and must not pretend to be one.

## Primary Workflow

Use `Scripts/linaai_task.sh` from the repository root for normal work.

1. Gather repo evidence before any edits.
2. Run local Qwen/Ollama preflight for risk and confidence.
3. Route to Codex when confidence is below threshold or task risk is high.
4. Use Aider only for narrow, supervised local edits.
5. Verify with the most relevant script, test, compile, or dry-run command.
6. Leave a clear status file under `Saved/AiTaskStatus/`.
7. Commit only after human-approved workflow requires it.

Default confidence threshold is `0.75`. This is intentionally conservative.

## What LinaAI Can Handle Locally

- Summarize project docs and repo structure.
- Create or update documentation.
- Generate focused tests or verification scripts.
- Inspect logs and produce likely causes.
- Make small, low-risk code or script edits.
- Prepare structured Codex handoffs.
- Update project memory after a completed task.

## What Must Escalate

Escalate to Codex or human review before editing when a task touches:

- Unreal core architecture.
- Save/load and persistence.
- Multiplayer, networking, or replication.
- AGR wallet, payments, marketplace, or economy transfer logic.
- Auth, security, secrets, deployment keys, or production migrations.
- Broad refactors or large cross-system changes.
- Anything where local evidence is thin or contradictory.

## Required Evidence

Before proposing changes, LinaAI must identify the evidence it checked:

- Internal docs read.
- Files inspected.
- Commands run.
- Build/test/log results.
- Official vendor docs consulted when framework behavior matters.

If it has not inspected evidence, confidence must be below `0.65`.

## Branch And Commit Rules

- Never merge directly to `main`.
- Never commit generated caches under `Saved/`.
- Never commit raw credentials.
- Prefer small branches and small commits.
- Do not rewrite unrelated history.
- Do not revert user work unless explicitly instructed.

## Build Host Boundaries

- `LinaAI` owns AI tooling, Aider, Codex CLI escalation, repo memory, scripts,
  and small supervised branch work.
- `unreal-engine` owns Unreal Engine source, editor builds, commandlets, and
  package verification.
- Gitea is the source of truth for current private development repositories.

## Normal Commands

Refresh the local knowledge cache:

```bash
Scripts/linaai_refresh_knowledge.sh
```

Build a compact local context file from tracked docs:

```bash
Scripts/linaai_bootstrap_context.sh
```

Run a supervised task:

```bash
Scripts/linaai_task.sh "Summarize what docs should be read before changing terrain visuals."
```

Force-test Codex routing:

```bash
Scripts/linaai_task.sh --force-escalate "Test Codex route only. Do not edit files."
```