panopticon init

CLAUDE.md

@@ -0,0 +1,45 @@
+# Panopticon — Automated Project Documentation Registry
+
+## Overview
+
+Panopticon is a nightly batch system that maintains up-to-date, LLM-optimized project documentation as pi skill files. It analyzes git diffs since the last run, dispatches parallel LLM workers to update documentation sections, synthesizes the results, and writes pi-compatible skill directories into each project's `.pi/skills/panopticon/` folder.
+
+## Architecture
+
+- **CLI entry point:** `src/index.ts` — handles `--full-analysis <name>`, `--project <name>`, `--dry-run`
+- **Config:** `src/config.ts` — loads `config.json` with project registry, model config, limits
+- **Git:** `src/git.ts` — git operations (pull, diff, log, file tree, churn)
+- **Structural:** `src/structural.ts` — regex-based AST extraction, import graph, file hashing
+- **Session:** `src/session.ts` — pi SDK session factory for orchestrator/worker/synthesizer roles
+- **Orchestrator:** `src/orchestrator.ts` — analyzes diffs, plans work units
+- **Worker:** `src/worker.ts` — generates/updates doc sections with read tool access
+- **Synthesizer:** `src/synthesizer.ts` — reconciles worker outputs, generates SKILL.md
+- **Writer:** `src/writer.ts` — writes skill files to `<project>/.pi/skills/panopticon/`
+- **Reporter:** `src/reporter.ts` — generates run reports, detects anomalies
+- **Metrics:** `src/metrics.ts` — pushes Prometheus metrics to Victoria Metrics
+- **State:** `src/state.ts` — per-project state persistence (last SHA, file hashes)
+- **Types:** `src/types.ts` — shared type definitions
+
+## Key Conventions
+
+- All pi SDK sessions are created via `createSession()` in `session.ts`
+- Workers get read-only tools; orchestrator and synthesizer get no tools
+- Prompts live in `prompts/` directory as standalone markdown files
+- Models default to Anthropic (claude-sonnet-4-5 for smart, claude-haiku-4-5 for cheap)
+- Config is in `config.json` at project root
+- State persisted in `state/` directory, run reports in `runs/`
+
+## Build & Run
+
+```bash
+npm run build          # Compile TypeScript
+npm start              # Run incremental (all projects)
+node dist/index.js --full-analysis snow_trail_sdl   # Full analysis
+node dist/index.js --dry-run                         # Test without writing
+```
+
+## Dependencies
+
+- `@mariozechner/pi-coding-agent` — pi SDK for LLM sessions
+- `@mariozechner/pi-ai` — model resolution and streaming
+- Node.js 20+, TypeScript 5.7+