Prepare LinaAI project memory

Docs/AI/LinaAIKnowledgeMap.md

@@ -0,0 +1,90 @@
+# LinaAI Knowledge Map
+
+This map defines the project memory LinaAI should consult before working. It is
+not a replacement for reading source files. It is the first-read order for
+context.
+
+## First Read For Agrarian
+
+1. `Docs/AI/LinaAIOperatingManual.md`
+2. `Docs/AI/LocalAgentGuardrails.md`
+3. `Docs/AI/LinaAISecretsPolicy.md`
+4. `Docs/Ops/HANDOFF.md`
+5. `AGRARIAN_DEVELOPMENT_ROADMAP.md`
+6. `Docs/CoreDesignDocument.md`
+7. `Docs/TechnicalDesignDocument.md`
+8. `Docs/SixMonthMvpDefinition.md`
+9. `Docs/MvpSurvivalReadinessCriteria.md`
+10. `Docs/Investor/InvestorDemoAcceptanceGate.md`
+
+## System-Specific Internal Docs
+
+Use these before touching the named area.
+
+- Visuals and assets:
+  `Docs/Art/AgrarianAssetPipeline.md`,
+  `Docs/Art/AssetLicenses.md`,
+  `Docs/Art/GroundZeroAssetAcquisitionQueue.md`,
+  `Docs/Rendering/InvestorRenderingPresets.md`.
+- Terrain and world generation:
+  `Docs/Terrain/GroundZeroTile.md`,
+  `Docs/Terrain/GroundZeroNaturalEnvironmentPass.md`,
+  `Docs/Terrain/UnrealLandscapeImportPlan.md`,
+  `Docs/World/BiomeAndNaturalResourceGenerationPlan.md`.
+- Persistence:
+  `Docs/PersistenceDesignDocument.md`,
+  `Docs/Ops/PersistenceSaveRecoveryPlan.md`.
+- Multiplayer:
+  `Docs/MultiplayerNetworkingDesign.md`,
+  `Docs/Ops/DedicatedServerBuildRunbook.md`,
+  `Docs/Ops/MultiplayerLatencyTestPlan.md`.
+- Economy and AGR:
+  `Docs/EconomyAndAgrDesignDocument.md`.
+- Infrastructure and repo policy:
+  `Docs/RepositoryStoragePolicy.md`,
+  `Docs/BranchingConventions.md`,
+  `Docs/CommitMessageConventions.md`,
+  `Docs/BackupExpectations.md`.
+
+## Official Vendor Documentation
+
+Refresh local cached copies with `Scripts/linaai_refresh_knowledge.sh`. The
+tracked repo stores URLs and notes; downloaded vendor pages stay under ignored
+`Saved/LinaAIKnowledge/`.
+
+- Unraid docs: `https://docs.unraid.net/`
+- Unreal Engine 5.7 docs: `https://dev.epicgames.com/documentation/en-us/unreal-engine`
+- Laravel 12 docs: `https://laravel.com/docs/12.x`
+- MySQL 8.4 Reference Manual: `https://dev.mysql.com/doc/refman/8.4/en/`
+- Gitea docs: `https://docs.gitea.com/`
+- Ollama docs: `https://docs.ollama.com/`
+- Open WebUI docs: `https://docs.openwebui.com/`
+- Aider docs: `https://aider.chat/docs/`
+
+## Infrastructure Map
+
+- Gitea: `http://192.168.5.21:3000`
+- Agrarian game repo:
+  `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`
+- LinaAI VM: `192.168.5.27`
+- Unreal build VM: `192.168.5.20`
+- Unraid host: `192.168.5.8`
+
+Credentials are intentionally not listed here. See
+`Docs/AI/LinaAISecretsPolicy.md`.
+
+## Knowledge Refresh Rule
+
+Run a knowledge refresh before large planning, repo migrations, infrastructure
+changes, or when vendor behavior matters:
+
+```bash
+Scripts/linaai_refresh_knowledge.sh
+Scripts/linaai_bootstrap_context.sh
+```
+
+If downloaded docs are unavailable, LinaAI should continue with tracked project
+docs and state the gap in its evidence.
+

Docs/AI/LinaAIOperatingManual.md

@@ -0,0 +1,100 @@
+# 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."
+```
+

Docs/AI/LinaAISecretsPolicy.md

@@ -0,0 +1,56 @@
+# LinaAI Secrets Policy
+
+LinaAI must never store raw secrets in tracked docs, model prompts, logs,
+knowledge caches, commits, issue bodies, or handoff summaries.
+
+This includes:
+
+- Passwords.
+- API keys and tokens.
+- SSH private keys.
+- Wallet private keys, seed phrases, or recovery phrases.
+- Database passwords.
+- Production webhook secrets.
+- Cloud provider credentials.
+
+## Allowed Context
+
+LinaAI may store and use non-secret operational context:
+
+- Hostnames and IP addresses.
+- Public ports.
+- Repository URLs.
+- Service roles.
+- Usernames when needed for operational clarity.
+- Credential source names, such as "human approval required" or "use existing
+  SSH agent".
+
+## Disallowed Context
+
+LinaAI must not copy plaintext credentials from chat, terminal history, handoff
+files, screenshots, `.env` files, config files, or password managers into its
+own docs or prompts.
+
+If a task requires a secret, LinaAI should:
+
+1. Explain which credential is needed.
+2. Use an existing secure mechanism if already configured, such as SSH keys,
+   an OS credential store, or an environment variable.
+3. Ask the human to perform the login or provide the credential interactively.
+4. Redact the credential from logs and summaries.
+
+## Repo And Cache Hygiene
+
+- `Saved/` is ignored and may hold local task state, but it is still not a safe
+  place for raw secrets.
+- Knowledge refresh scripts must not scrape or package `.env`, private key,
+  wallet, token, browser profile, or password manager files.
+- Before commits, run `git status --short` and inspect any newly tracked docs or
+  scripts for accidental secrets.
+
+## AI Prompt Rule
+
+When prompting Qwen, Aider, or Codex, include service names and endpoints only.
+Do not include passwords or tokens. If Codex needs a privileged action, use the
+existing shell/SSH session or ask for explicit human approval.
+

Docs/AI/SelfHostedAiDevelopmentStack.md

@@ -30,15 +30,25 @@ Codex escalation when local tooling is over its head.
 
 ## Operating Model
 
-1. Start with `Scripts/linaai_task.sh`, not raw Aider, for normal work.
+1. Refresh LinaAI project memory when context may be stale:
-2. Qwen/Ollama performs a preflight risk and confidence check.
+   `Scripts/linaai_refresh_knowledge.sh`.
-3. Default confidence threshold is `0.75`.
+2. Build a compact local context pack when needed:
-4. High-risk tasks or low-confidence tasks route to Codex automatically.
+   `Scripts/linaai_bootstrap_context.sh`.
-5. Aider runs only for acceptable supervised local work.
+3. Start with `Scripts/linaai_task.sh`, not raw Aider, for normal work.
-6. If Aider fails, `Scripts/linaai_task.sh` writes a status file and calls
+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`.
-7. Codex escalation uses the npm Codex CLI, not the API.
+9. Codex escalation uses the npm Codex CLI, not the API.
-8. Human review controls merges.
+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
 
@@ -50,6 +60,8 @@ 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"
 ```
 

Scripts/linaai_bootstrap_context.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$ROOT"
+
+CACHE_DIR="${LINAAI_KNOWLEDGE_DIR:-Saved/LinaAIKnowledge}"
+OUT="${CACHE_DIR}/context.md"
+mkdir -p "$CACHE_DIR"
+
+: > "$OUT"
+printf '# LinaAI Bootstrap Context\n\n' >> "$OUT"
+printf 'Generated: %s\n\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$OUT"
+printf 'This is a compact, local-only context pack built from tracked project docs. It intentionally excludes raw secrets.\n\n' >> "$OUT"
+
+include_doc() {
+  local doc="$1"
+  local lines="${2:-120}"
+  if [[ -f "$doc" ]]; then
+    printf '\n---\n\n## %s\n\n' "$doc" >> "$OUT"
+    sed -n "1,${lines}p" "$doc" >> "$OUT"
+    printf '\n' >> "$OUT"
+  else
+    printf '\n---\n\n## Missing: %s\n\n' "$doc" >> "$OUT"
+  fi
+}
+
+include_doc "Docs/AI/LinaAIOperatingManual.md" 220
+include_doc "Docs/AI/LocalAgentGuardrails.md" 180
+include_doc "Docs/AI/LinaAISecretsPolicy.md" 180
+include_doc "Docs/AI/LinaAIKnowledgeMap.md" 220
+include_doc "Docs/Ops/HANDOFF.md" 220
+include_doc "AGRARIAN_DEVELOPMENT_ROADMAP.md" 260
+include_doc "Docs/CoreDesignDocument.md" 160
+include_doc "Docs/TechnicalDesignDocument.md" 160
+include_doc "Docs/SixMonthMvpDefinition.md" 160
+include_doc "Docs/Investor/InvestorDemoAcceptanceGate.md" 160
+
+printf 'LinaAI bootstrap context written: %s\n' "$OUT"
+

Scripts/linaai_refresh_knowledge.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$ROOT"
+
+CACHE_DIR="${LINAAI_KNOWLEDGE_DIR:-Saved/LinaAIKnowledge}"
+RAW_DIR="${CACHE_DIR}/vendor/raw"
+INTERNAL_DIR="${CACHE_DIR}/internal"
+INDEX="${CACHE_DIR}/INDEX.md"
+
+mkdir -p "$RAW_DIR" "$INTERNAL_DIR"
+
+write_line() {
+  printf '%s\n' "$1" >> "$INDEX"
+}
+
+: > "$INDEX"
+write_line "# LinaAI Knowledge Cache"
+write_line ""
+write_line "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+write_line ""
+write_line "This directory is ignored by Git. It is a local retrieval/cache area for LinaAI."
+write_line "Do not place raw credentials here."
+write_line ""
+
+write_line "## Tracked Project Memory"
+write_line ""
+
+project_docs=(
+  "Docs/AI/LinaAIOperatingManual.md"
+  "Docs/AI/LocalAgentGuardrails.md"
+  "Docs/AI/LinaAISecretsPolicy.md"
+  "Docs/AI/LinaAIKnowledgeMap.md"
+  "Docs/Ops/HANDOFF.md"
+  "AGRARIAN_DEVELOPMENT_ROADMAP.md"
+  "Docs/CoreDesignDocument.md"
+  "Docs/TechnicalDesignDocument.md"
+  "Docs/SixMonthMvpDefinition.md"
+  "Docs/MvpSurvivalReadinessCriteria.md"
+  "Docs/Investor/InvestorDemoAcceptanceGate.md"
+  "Docs/Art/AgrarianAssetPipeline.md"
+  "Docs/Terrain/GroundZeroTile.md"
+  "Docs/World/BiomeAndNaturalResourceGenerationPlan.md"
+  "Docs/EconomyAndAgrDesignDocument.md"
+  "Docs/MultiplayerNetworkingDesign.md"
+  "Docs/PersistenceDesignDocument.md"
+)
+
+for doc in "${project_docs[@]}"; do
+  if [[ -f "$doc" ]]; then
+    safe_name="$(printf '%s' "$doc" | tr '/ ' '__')"
+    {
+      printf '# %s\n\n' "$doc"
+      grep -E '^(#|##|###) ' "$doc" 2>/dev/null || true
+    } > "${INTERNAL_DIR}/${safe_name}.headings.md"
+    write_line "- ${doc} -> ${INTERNAL_DIR}/${safe_name}.headings.md"
+  else
+    write_line "- missing: ${doc}"
+  fi
+done
+
+write_line ""
+write_line "## Official Vendor Docs"
+write_line ""
+
+fetch_doc() {
+  local name="$1"
+  local url="$2"
+  local out="${RAW_DIR}/${name}.html"
+  if curl -L --fail --retry 2 --connect-timeout 10 --max-time 45 -o "$out" "$url"; then
+    write_line "- ${name}: ${url} -> ${out}"
+  else
+    write_line "- ${name}: ${url} -> fetch failed"
+    rm -f "$out"
+  fi
+}
+
+fetch_doc "unraid" "https://docs.unraid.net/"
+fetch_doc "unreal-engine-5-7" "https://dev.epicgames.com/documentation/en-us/unreal-engine"
+fetch_doc "laravel-12" "https://laravel.com/docs/12.x"
+fetch_doc "mysql-8-4" "https://dev.mysql.com/doc/refman/8.4/en/"
+fetch_doc "gitea" "https://docs.gitea.com/"
+fetch_doc "ollama" "https://docs.ollama.com/"
+fetch_doc "open-webui" "https://docs.openwebui.com/"
+fetch_doc "aider" "https://aider.chat/docs/"
+
+write_line ""
+write_line "## Usage"
+write_line ""
+write_line "- Use this index as evidence that project/vendor docs were refreshed."
+write_line "- Use tracked docs as the source of truth for project policy."
+write_line "- Treat fetched vendor docs as reference material; verify details before risky edits."
+
+printf 'LinaAI knowledge cache refreshed: %s\n' "$INDEX"
+

Scripts/linaai_task.sh

@@ -87,13 +87,27 @@ repo_evidence="$(
     test -d Scripts && echo "Scripts/"
     test -d Docs && echo "Docs/"
     echo "script_samples:"
-    find Scripts -maxdepth 1 -type f -printf "%f\n" 2>/dev/null | sort | head -40
+    find Scripts -maxdepth 1 -type f -printf "%f\n" 2>/dev/null | sort | head -25
     echo "doc_samples:"
-    find Docs -maxdepth 2 -type f -printf "%p\n" 2>/dev/null | sort | head -40
+    find Docs -maxdepth 2 -type f -printf "%p\n" 2>/dev/null | sort | head -25
+    echo "linaai_required_docs:"
+    for doc in \
+      Docs/AI/LinaAIOperatingManual.md \
+      Docs/AI/LocalAgentGuardrails.md \
+      Docs/AI/LinaAISecretsPolicy.md \
+      Docs/AI/LinaAIKnowledgeMap.md \
+      Docs/Ops/HANDOFF.md \
+      AGRARIAN_DEVELOPMENT_ROADMAP.md
+    do
+      test -f "$doc" && echo "$doc"
+    done
+    echo "linaai_cache:"
+    test -f Saved/LinaAIKnowledge/INDEX.md && echo "Saved/LinaAIKnowledge/INDEX.md"
+    test -f Saved/LinaAIKnowledge/context.md && echo "Saved/LinaAIKnowledge/context.md"
   } | sed 's/"/'\''/g'
 )"
 
-system_prompt='You are LinaAI, a supervised local coding assistant for Agrarian. You must not pretend certainty. Classify task risk and confidence before any edits. Confidence must be based on concrete evidence. If you lack evidence, confidence must be below 0.65. High-risk areas include Unreal core architecture, save/load, multiplayer, networking/replication, AGR wallet/payments, marketplace/economy transfer logic, auth, security, migrations, deployment secrets, and broad refactors. Return JSON only.'
+system_prompt='You are LinaAI, a supervised local coding assistant for Agrarian. Follow Docs/AI/LinaAIOperatingManual.md, Docs/AI/LocalAgentGuardrails.md, Docs/AI/LinaAISecretsPolicy.md, and Docs/AI/LinaAIKnowledgeMap.md when present. You must not pretend certainty. Classify task risk and confidence before any edits. Confidence must be based on concrete evidence. If you lack evidence, confidence must be below 0.65. Do not include raw secrets in prompts, docs, logs, or commits. High-risk areas include Unreal core architecture, save/load, multiplayer, networking/replication, AGR wallet/payments, marketplace/economy transfer logic, auth, security, migrations, deployment secrets, and broad refactors. Return JSON only.'
 
 user_prompt=$(cat <<EOF
 Task:
@@ -123,13 +137,18 @@ print(json.dumps({
         {"role": "system", "content": system_prompt},
         {"role": "user", "content": user_prompt},
     ],
+    "options": {
+        "num_ctx": 4096,
+        "num_predict": 220,
+        "temperature": 0.1
+    },
     "stream": False,
 }))
 PY
 )"
 
 echo "LinaAI preflight with ${MODEL}..."
-response="$(curl -fsS "${OLLAMA_URL}/api/chat" -H "Content-Type: application/json" -d "$payload")"
+response="$(curl -fsS --max-time "${LINAAI_PREFLIGHT_TIMEOUT:-120}" "${OLLAMA_URL}/api/chat" -H "Content-Type: application/json" -d "$payload")"
 content="$(printf '%s' "$response" | python3 -c 'import json,sys; print(json.load(sys.stdin)["message"]["content"])')"
 
 python3 - "$content" "$PREFLIGHT_JSON" <<'PY'
@@ -238,6 +257,11 @@ if [[ "$should_escalate" -eq 1 ]]; then
   exec Scripts/ai_codex_escalate.sh "$STATUS_JSON"
 fi
 
+if [[ -x Scripts/linaai_bootstrap_context.sh && ! -f Saved/LinaAIKnowledge/context.md ]]; then
+  echo "Building LinaAI bootstrap context..."
+  Scripts/linaai_bootstrap_context.sh >/dev/null || true
+fi
+
 if [[ "$DRY_RUN" -eq 1 ]]; then
   echo "Dry run: would run Aider locally."
   exit 0