#Eko Documentation

Documentation for developers building and maintaining Eko v2.

Quick Navigation:

• Debugging production? Start in Runbooks
• Building features? Start in Product
• Setting up locally? Start in Development
• Understanding the system? See Product Bible

#Quick Links

• Local Development Setup - Get started developing
• Architecture Overview - System design
• Rules Index - All rules and conventions
• Glossary - Term definitions
• Conventions - Documentation standards

#Documentation Workflow

#Creating Documents

bun run docs:new --scope <scope> --title "Title"
bun run docs:new --list-scopes  # Show available scopes

#CI Validation

Command	Purpose	CI Behavior
docs:lint	Validates front-matter	Errors block build
docs:staleness --pr	Detects stale docs	Warnings only (PR summary)

#Document Classes

CONTRACT (scopes: architecture, product, specification, policy):

• Defines system behavior; must stay in sync with code
• Required fields: related_code, version
• Recommended: changelog
• Violations: errors on new/modified docs, warnings on existing

GUIDE (scopes: dev, operations, reference, design, assessment):

• Explains how to use the system
• All fields optional (warnings only)

#Code Binding Policy

• Primary source: Front-matter related_code field
• Secondary source: docs-code-mapping.yml (additive only)
• Mapping file may ADD paths but must NOT remove front-matter paths
• Use front-matter when doc author owns the mapping
• Use mapping file for central/cross-cutting mappings

#Documentation Structure

#Product

Product documentation for the Eko v2 fact engine.

• News Pipeline — Detailed Flow - End-to-end flow from news APIs to feed
• Evergreen Pipeline — Detailed Flow - AI-generated timeless facts
• Seeding Pipeline — Detailed Flow - Entity explosion and enrichment
• News & Fact Engine - System reference: providers, costs, config
• Fact Ingestion — Source of Truth Map - SOT file pointers for all pipelines
• Fact-Challenge Anatomy - How facts become challenges across 5 layers
• News-to-Challenge Ingestion Guide - Full pipeline walkthrough
• Evergreen Ingestion - Evergreen + challenge content generation
• Gemini Batch API Strategy - Batch discount strategy

#Architecture

Technical design and decision records.

• Overview - V2 fact engine architecture, tables, queues, workers
• Decisions - Architecture Decision Records (ADR-001 through ADR-017)
• Tools - V2 runtime capabilities (20+ evidence APIs, AI model router)
• Table Flow Diagram - Visual 6-phase data flow
• Model Code Isolation - AI provider switching patterns
• Monorepo Structure - Codebase layout
• Schema Naming Contracts - Naming conventions

#Design System

Design system tokens and component guidelines. Wireframes and token extraction are in progress — see docs/projects/design-system/ for current status.

#Development

Guides for developers working on Eko.

• Local Development - Setup guide
• Database - Schema, migrations, caching
• Drizzle ORM - Type-safe query patterns
• Deployments - CI/CD and environments
• Testing - V2 E2E verification
• Observability - Logging, Sentry, AI cost tracking
• Cron Actions - Scheduled tasks and maintenance reference

#Runbooks

Operational procedures for production systems.

• Incident Playbook - Triage and response
• Ingestion - News API fetching, deduplication, clustering
• Fact Extraction - AI extraction, evergreen, seed pipeline
• Validation - Multi-phase verification and evidence APIs
• Queue - Job processing issues
• Scheduling - Cron and dispatch issues

#Policies

Legal and compliance documentation.

• Fair Use - Non-substitutive output rules
• AI Safety - LLM usage safety guidelines

#Rules

Central index for all rules, conventions, and standards.

• Rules Index - Complete rules reference
• Error Handling - Error handling standards
• Testing - Testing patterns and coverage
• Security - Security patterns and SSRF prevention
• Dependencies - Dependency management rules

#Reports

Summary reports and documentation health.

• Doc Health - Documentation health reports
• Features - New features and enhancements

#Proposals

Design proposals for features, functionality improvements, and fixes before implementation.

#Changelog

Detailed changelog entries for releases, auto-generated from git commits.

bun run changelog:generate              # Generate unreleased changelog
bun run changelog:generate --update-root  # Also update root CHANGELOG.md

#Repository-Level Docs

These files live at the repo root:

• CONTRIBUTING.md - How to contribute
• SECURITY.md - Security policy
• CHANGELOG.md - Version history
• STACK.md - Technology stack

#Agent System

Claude Code agents are documented in .claude/agents/README.md — the authoritative source for agent ownership, routing, and capabilities.