diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..dfa57df --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,41 @@ +# Agent Operational Guidance (AGENTS.md) + +This document provides critical context and operational mandates for AI agents working on the EVE Online Automated Wiki project. **Read this first in case of context loss.** + +## 1. Core Architectural Mandates + +### 1.1 Dual-Repository Strategy +The project is strictly separated into two repositories: +- **`eve-wiki-system` (Current Workspace):** Contains the "Engine" (Python code, LangGraph agents, clients, infrastructure configs). +- **`eve-wiki-content` (Data Repo):** Contains the "Content" (Markdown files and images). +- **Mandate:** Agents must NEVER commit code to the content repo or content to the system repo. The `git_sync_node` in `src/main.py` is the only authorized pathway for moving data into the content repo. + +### 1.2 Single Source of Truth (SSOT) +- **Git is the SSOT.** Wiki.js is a renderer that pulls from the `eve-wiki-content` repository. +- Human editing is disabled in Wiki.js. All updates must flow through the agent pipeline to maintain data integrity. + +## 2. Source Extraction Protocols + +- **EVE University:** Use the MediaWiki API (`api.php`). Avoid HTML scraping. +- **WCKG (wckg.net):** Requires real-browser rendering (Google Sites). Use the `browser_agent` for extractions or implement a headless browser (Playwright/Selenium). Standard `httpx` requests will return 404s. +- **CCP Support:** Requires browser-like headers to bypass Cloudflare protection. + +## 3. Implementation Standards + +- **Environment:** Use `uv` for all dependency management and execution. +- **Secrets:** All keys (Wiki.js API, Gitea tokens) are stored in `.env`. Never commit this file. +- **Orchestration:** Use LangGraph for the pipeline. The state model is defined in `src/schema/state.py`. +- **Validation:** Content MUST meet a 95% confidence score to be published. Numerical (ESI) and Structural (Markdown) checks are "Must Pass" (failure sets total score to 0%). + +## 4. Infrastructure Map + +| Component | URL / Target | +|-----------|--------------| +| Wiki Primary | `https://eve.tar.nz` | +| Wiki API | `https://eve.tar.nz/graphql` | +| Git Server | `git.local.ben.io` (SSH) | +| Target Server | `local.ben.io` (SSH alias: `docker-test`) | +| Stack Name | `eve-wiki` (Postgres, Redis, Wiki.js) | + +## 5. Resuming Work +To resume implementation, always check `.private/ROADMAP.md` for the current phase and task status.