# 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
- 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+