Prepare LinaAI project memory
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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."
|
||||
```
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
2. Qwen/Ollama performs a preflight risk and confidence check.
|
||||
3. Default confidence threshold is `0.75`.
|
||||
4. High-risk tasks or low-confidence tasks route to Codex automatically.
|
||||
5. Aider runs only for acceptable supervised local work.
|
||||
6. If Aider fails, `Scripts/linaai_task.sh` writes a status file and calls
|
||||
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`.
|
||||
7. Codex escalation uses the npm Codex CLI, not the API.
|
||||
8. Human review controls merges.
|
||||
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
|
||||
|
||||
@@ -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"
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user