OpenTokenMini Get the code → Docs For agents GitHub
00-docs/agents/repo-map.md · raw · GitHub

Repo map and editing rules

Layout

Top-level directories are numbered in install order: 00-docs/, 01-deploy/, 02-measure/, 03-analyze/, 04-auto-analysis/, 05-dashboards/, 06-optional/. 04-auto-analysis/ holds the readers that pull data from git, deployments, cloud logs and other systems into 02-measure/'s records, one per system. 06-optional/ holds what only some setups need: corporate login, the MCP server for agents, decision models. Numbers are tentative; renumbering means renaming the directory and fixing links, which the docs build checks. At most two levels. Each directory has an AGENTS.md that opens with what it does, its input, its output, and what data it touches; keep it accurate, nothing is hidden or obfuscated. Stages with a method keep it in METHOD.md, separate from the implementation. A piece becomes its own directory only when one file gets too big.

  • 00-docs/agents/ technical notes for agents.
  • 00-docs/humans/ human pages: landing.html (served at /), logo, flow graph, share image. <lang>/strings.json is the phrase table per language (es, zh); <lang>/README.md is generated from it, never edited by hand.
  • 00-docs/use-case-reports/ measured results from deployments, one file per case, any language, from TEMPLATE.md.
  • 00-docs/demo/ walkthrough with screenshots, once dashboard mockups exist.
  • 00-docs/humans/ will also hold the dashboard screenshot used by every README (pending).
  • The site: opentokenmini.org serves the landing, /docs/ serves this repo (raw files plus one page per .md), /llms.txt indexes it for agents. Built by .github/pages/build.py.

Section numbers

Used in the checklist and diagrams; the first digit is the directory number.

  • 1 Deploy: 1.1 host, 1.2 auth, 1.3 storage, 1.4 checklist
  • 2 Measure: 2.1 collector, 2.2 harnesses, 2.3 transcripts, 2.4 intent labels, 2.5 adoption
  • 3 Analyze: 3.1 levels, 3.2 summary and outliers, 3.3 recommendations
  • 4 Auto-analysis: 4.1 git, 4.2 deployments, 4.3 issue trackers, 4.4 billing, 4.5 cloud logs, 4.6 MCP usage, 4.7 docs, 4.8 chat usage, 4.9 quality
  • 5 Dashboards: 5.1 standalone, 5.2 inside the user's monitoring (Datadog, Grafana)
  • 6 Optional: 6.1 MCP server, 6.2 identity, 6.3 decision models

Rules

  • Placeholders share one shape: what it reads, coverage (first, next, long tail), workflow, pitfalls.

  • Code for what must give the same number everywhere (collector, schemas, metrics, outliers, MCP tools); specs for what touches each org's infra (integrations, deploy, vendors).

  • Agent-facing content (AGENTS.md, METHOD.md, 00-docs/agents/, code comments): English only.

  • Human-facing content (landing, READMEs, dashboard UI): en, zh, es. Edit English only, then run python3 .github/pages/i18n.py: it lists new phrases with an empty translation in each strings.json; fill them in and rerun. The build fails if a generated README is out of date and shows English for any empty phrase.
  • Root stays clean: AGENTS.md, README.md, LICENSE and the pipeline directories. .github/ publishes the site (build, translations, docs viewer, llms.txt header, workflow).
  • No savings figure in any doc unless it comes from a report in 00-docs/use-case-reports/.

Status

  • Working: Claude Code → 02-measure/collector.py → embedded dashboard; past Claude Code usage via 02-measure/from-transcripts.py.
  • Draft: 00-docs/demo/ guided walkthrough with real usage data (not published yet).
  • Drafted: other harnesses, token configs, deploy options.
  • Placeholder: transcripts push, storage, all integrations, analyze and its output, decision models, quality checks, metric catalog, standalone dashboard, MCP server, demo, dashboard i18n.