Initial wiki structure

2026-04-19 03:57:03 +00:00
commit 31c3083ff4
11 changed files with 1041 additions and 0 deletions
--- a/docs/infrastructure/git-sync.md
+++ b/docs/infrastructure/git-sync.md
@@ -0,0 +1,50 @@
+# Git Sync Protocol & Repository Structure
+
+The Git repository serves as the **Single Source of Truth (SSOT)** for all wiki content. This document defines how data is structured and synchronized.
+
+## 1. Repository Layout
+
+```text
+/
+├── content/              # All Markdown wiki pages
+│   ├── ships/
+│   ├── modules/
+│   └── ...
+├── assets/               # Images, PDFs, and static files
+│   ├── images/
+│   └── ...
+├── schema/               # Shared validation schemas (JSON Schema)
+├── metadata/             # Global metadata (e.g., typeID mapping table)
+│   └── mapping.json
+└── .wikijsignore         # Files to be ignored by Wiki.js sync
+```
+
+## 2. Synchronization Flow
+
+### Primary Write Path (Agent -> Git -> Wiki.js)
+1. **Agent Modification:** An agent (A, B, or C) generates or updates a Markdown file.
+2. **Local Commit:** The agent commits the change to its local clone of the repository.
+3. **Push to Origin:** The agent pushes to the `main` branch.
+4. **Wiki.js Sync:**
+   - Wiki.js is configured with the "Git" storage target.
+   - It pulls changes from the `main` branch at a set interval (default: 5 minutes) or via Webhook.
+   - Wiki.js renders the new Markdown content in the UI.
+
+### Wiki.js to Git (Optional / Prohibited)
+- **Status:** DISABLED
+- **Rationale:** Since human editing is disabled, there should be no writes originating from the Wiki.js UI. This prevents merge conflicts and ensures the Agent pipeline remains the sole source of content.
+
+## 3. Commit Standards
+
+To ensure a clean audit trail, all commits must follow the Conventional Commits-style with agent identifiers:
+
+**Format:** `[AGENT_ID] action: description (hash: source_hash)`
+
+**Examples:**
+- `[AGENT_A] seed: ships/caldari/condor (hash: sha256_...)`
+- `[AGENT_B] update: ships/amarr/abaddon (patch: 2026-04-16)`
+- `[AGENT_G] asset: images/ships/condor.png`
+
+## 4. Conflict Resolution
+- **Strategy:** Last-Write-Wins (LWW) based on Git commit timestamp.
+- **Merge Logic:** Automated merges are preferred. If a conflict occurs (rare in agent-only environments), the pipeline will halt and trigger a "System Alert" for manual intervention.
--- a/docs/infrastructure/wikijs-auth.md
+++ b/docs/infrastructure/wikijs-auth.md
@@ -0,0 +1,36 @@
+# Wiki.js API Authentication & Security Strategy
+
+## 1. Authentication Method
+- **Token Type:** Permanent API Keys (Bearer Tokens)
+- **Generation:** Generated via the Wiki.js Administration Area -> API Keys
+- **Storage:** Stored as environment variables in the agent runtime environment (e.g., `WIKIJS_API_TOKEN`).
+
+## 2. Permission Scopes
+To maintain security, the API token used by agents will be restricted to the minimum necessary scopes:
+
+| Scope | Requirement | Justification |
+|-------|-------------|---------------|
+| `write:pages` | Mandatory | Allows agents to create and update content |
+| `read:pages` | Mandatory | Allows agents to check existing content before updates |
+| `write:assets` | Mandatory | Allows Agent G to upload images/files |
+| `read:assets` | Mandatory | Allows checking for existing assets |
+| `read:tags` | Optional | Allows metadata tagging |
+| `manage:system` | **Prohibited** | Agents must NOT have administrative system access |
+
+## 3. Token Rotation Policy
+- **Frequency:** Tokens should be rotated every 90 days.
+- **Process:**
+  1. Generate new token in Wiki.js.
+  2. Update environment variable in agent deployment (Komodo/Docker).
+  3. Verify connectivity.
+  4. Revoke old token.
+
+## 4. Write Access Control
+- **Human Editing:** All human accounts in Wiki.js will be assigned to a "Read-Only" group.
+- **Agent Editing:** Only the API account (associated with the token) will have write permissions.
+- **Emergency Bypass:** A single "Admin" account will be maintained for emergency manual intervention, protected by 2FA.
+
+## 5. Security Best Practices
+- **TLS:** All API calls MUST be made over HTTPS.
+- **IP Whitelisting:** If possible, Wiki.js should be configured to only accept API requests from the IP of the agent runner.
+- **Audit Logs:** Enable Wiki.js audit logging to track all changes made via the API token.
--- a/docs/schema/hierarchy.md
+++ b/docs/schema/hierarchy.md
@@ -0,0 +1,41 @@
+# Wiki Page Hierarchy & URL Structure
+
+To ensure a structured and navigable wiki, all pages must follow this hierarchical pathing and categorization schema.
+
+## 1. Top-Level Categories
+
+| Directory | Content Type | URL Pattern |
+|-----------|--------------|-------------|
+| `ships/` | All ship hulls | `/ships/{race}/{group}/{ship_name}` |
+| `modules/`| All ship modules | `/modules/{category}/{group}/{module_name}` |
+| `mechanics/`| Game mechanics/guides | `/mechanics/{category}/{topic}` |
+| `items/` | General items (ammo, etc) | `/items/{category}/{item_name}` |
+| `skills/` | Character skills | `/skills/{category}/{skill_name}` |
+| `factions/`| NPC Factions | `/factions/{faction_name}` |
+
+## 2. Detailed Pathing Examples
+
+### Ships
+- **Path:** `/ships/caldari/interceptors/raptor`
+- **Breadcrumb:** Ships > Caldari > Interceptors > Raptor
+
+### Modules
+- **Path:** `/modules/shield/shield-extenders/large-shield-extender-ii`
+- **Breadcrumb:** Modules > Shield > Shield Extenders > Large Shield Extender II
+
+### Mechanics
+- **Path:** `/mechanics/combat/tracking-guide`
+- **Breadcrumb:** Mechanics > Combat > Tracking Guide
+
+## 3. Redirect & Alias Strategy
+- **TypeID Redirects:** Every page must be aliased by its ESI TypeID (e.g., `/id/603` -> `/ships/caldari/interceptors/raptor`) to allow easy linking from external tools.
+- **Lowercase Enforcement:** All URLs must be strictly lowercase.
+- **Slugification:** Spaces replaced by hyphens, special characters removed.
+
+## 4. Metadata Requirement
+Each page MUST include the following metadata in its frontmatter to support the hierarchy:
+```yaml
+path: "ships/caldari/interceptors/raptor"
+parent: "ships/caldari/interceptors"
+order: 10 # Optional: for sorting in lists
+```
--- a/docs/schema/state-schema.md
+++ b/docs/schema/state-schema.md
@@ -0,0 +1,83 @@
+# LangGraph State Schema Definition
+
+This document defines the shared state object used by the LangGraph orchestration layer.
+
+## 1. Shared State Object (`WikiState`)
+
+```python
+from typing import List, Optional, Dict, Annotated
+from pydantic import BaseModel, Field
+from datetime import datetime
+
+class ContentSource(BaseModel):
+    name: str  # e.g., "eve-university", "wckg", "esi"
+    url: str
+    content_hash: str
+    extracted_at: datetime
+
+class ValidationResult(BaseModel):
+    category: str  # "structural", "content", "numerical", "cross-reference"
+    passed: bool
+    score: float  # 0.0 to 1.0
+    feedback: Optional[str] = None
+    details: Dict = {}
+
+class PageMetadata(BaseModel):
+    page_type: str  # "ship", "module", "mechanic", "guide"
+    source: str
+    source_url: str
+    imported_date: datetime
+    last_updated: datetime
+    last_validated: datetime
+    update_frequency: str
+    validation_score: float
+    categories: List[str]
+
+class WikiPage(BaseModel):
+    path: str  # e.g., "ships/frigates/condor"
+    title: str
+    content_markdown: str
+    metadata: PageMetadata
+    frontmatter: Dict
+    assets: List[str]  # List of local asset paths
+
+class WikiState(BaseModel):
+    # Core processing data
+    current_page: Optional[WikiPage] = None
+    proposed_changes: List[WikiPage] = []
+    
+    # Pipeline tracking
+    sources: List[ContentSource] = []
+    validation_pipeline_results: List[ValidationResult] = []
+    
+    # Control flow
+    retry_count: int = 0
+    max_retries: int = 3
+    is_approved: bool = False
+    error: Optional[str] = None
+    
+    # Checkpointing metadata
+    thread_id: str
+    checkpoint_id: Optional[str] = None
+```
+
+## 2. Page Type Schemas
+
+### Ship Schema Overlay
+Extends the numerical validation requirements.
+
+```python
+class ShipData(BaseModel):
+    type_id: int
+    group: str
+    race: str
+    hull_stats: Dict[str, int]
+    fitting_stats: Dict[str, int]
+    velocity: int
+    skill_requirements: List[Dict[str, int]]
+```
+
+## 3. Storage Strategy
+- **State Persistence:** Redis (via `RedisSaver` for LangGraph)
+- **Content Persistence:** Git (Markdown + YAML Frontmatter)
+- **Asset Persistence:** Local filesystem / S3-compatible storage
--- a/docs/validation/quality-control.md
+++ b/docs/validation/quality-control.md
@@ -0,0 +1,60 @@
+# Quality Control & Operations Protocol
+
+This document defines the automated decision-making logic for content validation and the system-wide response to operational failures.
+
+## 1. Validation Scoring Formula (Blocker #6)
+
+Agent E (Validation) and Agent F (Numerical) calculate a combined **Confidence Score (0-100%)**. A score of **95% or higher** is required for auto-publication to the `main` branch.
+
+### 1.1 Weighted Categories
+
+| Category | Weight | Must Pass? | Criteria |
+|----------|--------|------------|----------|
+| **Numerical (ESI)** | 40% | **YES** | Stats (HP, Slots, PG/CPU) must match ESI ±0%. |
+| **Structural** | 20% | **YES** | Valid YAML, required fields present, correct URL path. |
+| **Relational** | 20% | NO | Internal links resolve, TypeIDs are valid. |
+| **Semantic** | 20% | NO | Prose description matches structured data intent. |
+
+### 1.2 The "Must Pass" Rule
+If any **"Must Pass"** category fails (score < 100% in that category), the total Confidence Score is immediately capped at **0%**, regardless of other categories. This prevents LLM hallucinations from overriding official game data.
+
+### 1.3 Scoring Logic
+`Total Score = (ESI * 0.4) + (Struct * 0.2) + (Relat * 0.2) + (Semant * 0.2)`
+
+---
+
+## 2. Failure Handling Matrix (Blocker #8)
+
+The system distinguishes between transient infrastructure issues and content quality failures.
+
+### 2.1 Tiered Response Matrix
+
+| Error Type | Tier | Initial Action | Max Retries | Escalation |
+|------------|------|----------------|-------------|------------|
+| **API Timeout / 5xx** | 1 | Exponential Backoff (1m, 5m, 15m) | 3 | Tier 3 Alert |
+| **Validation Fail (70-94%)** | 2 | Regeneration with Error Feedback | 2 | Tier 3 Alert |
+| **Validation Fail (<70%)** | 2 | Immediate Rejection | 1 | Tier 3 Alert |
+| **Auth Failure / 401** | 3 | Halt Pipeline | 0 | **Critical System Alert** |
+| **Git Conflict** | 3 | Halt Pipeline | 0 | **Critical System Alert** |
+
+### 2.2 Feedback Loop (Tier 2)
+When a page fails validation with a score of 70-94%, Agent E sends a "Correction Request" back to the source agent (A, B, or C) containing:
+1. The specific field that failed.
+2. The expected value (from ESI or Schema).
+3. The current value produced.
+
+### 2.3 Critical System Alerting
+Tier 3 failures trigger a webhook notification to the system administrator. The LangGraph state is persisted as a "Suspended" checkpoint, allowing for manual inspection and resume via LangSmith.
+
+---
+
+## 3. Rate Limiting Policy (Blocker #11)
+
+To ensure stability and prevent IP bans, the following global limits are enforced at the transport layer:
+
+| Target | Rate Limit | Burst |
+|--------|------------|-------|
+| **ESI API** | 20 req / sec | 50 |
+| **MediaWiki API** | 2 req / sec | 5 |
+| **Wiki.js API** | 5 req / sec | 10 |
+| **LLM APIs** | Per Provider Tier | N/A |