agent-wiki AGENTS.md

AGENTS.md — agent-wiki

What This Is

A documentation standard and supporting service for per-project agent-readable wikis. Each project in your workspace gets a single AGENTS.md describing intent, architecture, deployment, gotchas, and cross-project links. This repo defines the spec, hosts cross-cutting topics, and runs a small read-only browser/API.

Status

Spec + indexer + server + UI + sweeper. All pieces working:

• Spec defined (spec/schema.md), template (spec/template.md), topics tier rules (spec/topics.md).
• Indexer parses frontmatter + sections + links, validates, writes index/{projects,topics,backlinks,search,validation}.json. Also writes generated backlinks footers back into source AGENTS.md files (write_backlinks.ts).
• Read-only HTTP API in service/src/server/ with Google OAuth (allowlist) + file-based sessions, mounted at PATH_PREFIX (default /wiki). JSON endpoints for projects, topics, search, validation, raw doc bodies.
• React + Vite UI in ui/, served by the Express process from ui/dist/. Pages: Home, Project, Topic, Search, Validation, Login. Markdown rendered with react-markdown + remark-gfm; cross-doc links rewritten to in-app routes.
• Sweeper service in service/src/sweeper/: gathers per-project git activity since last_updated, calls the Claude API (streaming, 32k max_tokens, string-aware brace-counter parser), applies section-level patches, updates frontmatter. CLI supports per-project runs, --all fan-out, and --dry-run.
• Optional automation: a daily user-mode systemd timer (agent-wiki-sweeper.timer) runs sweeper --all && indexer build; a Claude Code Stop-hook (deploy/sweep-on-stop.sh) fires per-project sweeps async, debounced to 60 min/project.

Repository Layout

agent-wiki/
├── AGENTS.md                  this file (own dogfood)
├── README.md                  human-facing intro
├── LICENSE                    MIT
├── spec/
│   ├── schema.md              the AGENTS.md spec — sections, frontmatter, links
│   ├── template.md            starter file for new projects
│   ├── initial-AGENTS.md      minimal bootstrap doc for programmatic project init
│   └── topics.md              when to use a topic vs a project gotcha
├── topics/                    cross-cutting knowledge files (scaffolded; populate as needed)
├── index/                     generated by the indexer (gitignored)
│   ├── projects.json          per-project metadata, sections, links
│   ├── topics.json            per-topic metadata
│   ├── backlinks.json         reverse link graph
│   ├── search.json            flat per-section search entries
│   └── validation.json        spec-compliance issues
├── service/                   Node + TypeScript backend
│   ├── package.json
│   ├── tsconfig.json
│   ├── .env.example           copy to .env and fill in for deploy
│   └── src/
│       ├── indexer/           build index/*.json from AGENTS.md files
│       │   ├── cli.ts         CLI: build | validate
│       │   ├── build.ts       orchestration
│       │   ├── parse.ts       frontmatter, sections, links
│       │   ├── validate.ts    spec-compliance checks
│       │   ├── write_backlinks.ts  rewrite generated backlinks footers in source files
│       │   ├── types.ts       shared types + canonical section list
│       │   └── sources/       Source interface + filesystem impl
│       │       ├── types.ts   pluggable for future GitHub-backed source
│       │       └── fs.ts      walks PROJECTS_ROOT
│       ├── server/            Express + Passport (Google OAuth) + JSON API
│       │   ├── index.ts       app entry; mounts PATH_PREFIX, listens on PORT
│       │   ├── config.ts      env-driven config; required()/optional()
│       │   ├── auth.ts        Google OAuth + ALLOWED_EMAILS allowlist
│       │   ├── api.ts         JSON endpoints under /api
│       │   └── data.ts        reads index JSON + raw markdown (path-traversal safe)
│       └── sweeper/           per-project doc maintenance via Claude API
│           ├── cli.ts         CLI: run | dry-run; per-project or all
│           ├── run.ts         orchestrates one project's sweep
│           ├── gather.ts      git log + diffstat + changed files since last_updated
│           ├── prompt.ts      assembles the system + user prompt
│           ├── claude.ts      Claude API client wrapper
│           ├── apply.ts       applies section-level patches + frontmatter updates
│           ├── diff.ts        shows the proposed change
│           └── types.ts       shared sweeper types
├── ui/                        React + Vite SPA, served by the backend
│   ├── package.json
│   ├── vite.config.ts         base: PATH_PREFIX, dev proxy → backend
│   ├── index.html
│   └── src/
│       ├── main.tsx           BrowserRouter basename=PATH_PREFIX
│       ├── App.tsx            auth gate + routes
│       ├── api.ts             typed fetch client for ${PATH_PREFIX}/api/*
│       ├── styles.css
│       ├── components/
│       │   ├── Layout.tsx     topbar + search box + nav + user
│       │   └── Markdown.tsx   react-markdown w/ in-app link rewriting
│       └── pages/             Home, Project, Topic, Search, Validation, Login
└── deploy/
    ├── agent-wiki.service           systemd unit for the web service (hardened)
    ├── agent-wiki-sweeper.service   user-mode unit invoked by the timer / Stop-hook
    ├── agent-wiki-sweeper.timer     daily 03:00 fan-out sweep + reindex
    ├── run-daily.sh                 timer entrypoint: sweeper --all then indexer build
    ├── sweep-on-stop.sh             Claude Code Stop-hook: debounced async per-project sweep
    ├── sweep-project.sh             single-project sweep helper used by hook + systemd-run
    ├── apache.conf                  ProxyPass example
    └── setup.md                     step-by-step install walkthrough