What this is. Part 1 sets documentation priorities for the current audience. Parts 2 and 3 record the original documentation audit and the reconciliation work that followed. This document is the source of truth for the doc set. The docs index is the reader-facing navigation.
The primary readers are accountable technical operators who run work for their own organizations or on behalf of client organizations. Documentation follows their journey from deciding and understanding to standing up, operating, extending, and maintaining Ateles.
Specify the documentation this repo should have for its intended operators and preserve the audit and reconciliation history that informed the catalog.
Part 1 is the prioritized outline. Part 2 records how the audit classified the docs/ tree at the time.
Part 3 lists the reconciliation actions and follow-ups. Excludes editing the design-note bodies themselves.
Ordered by audience priority. P0 is what a prospective adopter needs in the first five minutes. P5 is deep reference consulted occasionally. The status column records the catalog's reconciliation status (see Part 2).
| # | Doc | Purpose | Status |
|---|---|---|---|
| 1 | README | One-screen accurate picture: dual nature (substrate + ops suite), what it does, who it's for | ✅ rewritten |
| 2 | ICP | Intended technical operators and adoption limits, with audit evidence from the original profile (2026-06-25 revision) | ✅ updated |
| 3 | Architecture overview (architecture.md) |
Entity model, four tiers, substrate, Neotoma integration | ✅ exists |
| 4 | Documentation index (docs/README.md) |
Navigation map of the whole doc set, organized by the ICP journey |
| # | Doc | Purpose | Status |
|---|---|---|---|
| 5 | Capabilities / operational surface (capabilities.md) |
What the 18 daemons + 87 skills actually do, by life/work domain — the under-documented operational half | 🆕 created |
| 6 | Agent taxonomy (taxonomy.md) |
The full roster: tiers, genera, status | ✅ exists |
| 7 | Data types (data_types.md) |
The Neotoma entity-type catalog the swarm reads/writes | ✅ exists |
| 8 | Substrate choice (neotoma_vs_alternatives.md) |
Why Neotoma as the canonical layer vs. alternatives | ✅ exists |
| # | Doc | Purpose | Status |
|---|---|---|---|
| 9 | Forking & adoption guide (forking.md) |
What is operator-specific vs. portable; the context entities, secrets, identities, and grants a new operator must supply | 🆕 created |
| 10 | Setup (setup.md) |
Neotoma + venv + AAuth keypairs + grants + first daemon under launchd | ✅ exists |
| 11 | Secrets management (secrets_management.md) |
SOPS+age model, offline materialization | ✅ exists |
| 12 | AAuth & keys (aauth.md, aauth/keys.md) |
Identity provisioning, keypair format, signing | ✅ exists |
| 13 | Cloud hosting (cloud_hosting.md) |
docker-compose on a small ARM host over Tailscale | ✅ exists |
| # | Doc | Purpose | Status |
|---|---|---|---|
| 14 | Gates and workflows (foundation/gates_and_workflows.md) |
workflow / batch / sign-off / step_status; one step set; the action gate. Supersedes swarm_orchestration.md and swarm_hitl_checkpoints_design.md (archived 2026-09-02) |
✅ foundation |
| 15 | Agent execution (agent_execution_runbook.md, foundation/work_model.md) |
How a dispatch runs end-to-end; the pull work model. task_execution_loop.md described the retired push model (archived 2026-09-02) |
✅ exists |
| 16 | HITL & gating (foundation/gates_and_workflows.md, foundation/authority_model.md) |
Blast tiers, checkpoint_brief approval, who may resolve; what is built as of a date is foundation/status.md |
✅ foundation |
| 17 | GitHub interaction (pr_review_routing.md, swarm-trigger-layer.md, swarm_github_interaction_design.md) |
Issue/PR triage, PR-review routing, webhook→Apis | ✅ exists |
| 18 | A2A gateway (a2a.md) |
Inbound agent-to-agent task receiver | ✅ exists |
| 19 | Session integrity (session_integrity.md) |
Plan-link / conversation-capture / artifact-linkage invariant + hooks | ✅ exists |
| # | Doc | Purpose | Status |
|---|---|---|---|
| 20 | MCP server development (mcp_server_development_guide.md) |
Building/extending the harness + grant proxy | ✅ exists |
| 21 | Linting & tests (linting-guide.md, test-setup-guide.md, testing/) |
The 8 linters, git hooks, test patterns | ✅ exists |
| 22 | RC autodeploy (daemon_rc_autodeploy.md) |
Rolling-main = RC deployment of daemons | ✅ exists |
| 23 | Credential health (credential_health.md, credential_management.md) |
Proactive re-auth across the swarm | ✅ exists |
| # | Doc | Purpose | Status |
|---|---|---|---|
| 24 | QA evals design (swarm_qa_evals_design.md, swarm_qa_evals_qe3_design.md) |
Agents-as-users eval framework | ✅ exists (design) |
| 25 | Durable execution (durable_execution_substrate.md) |
Neotoma as a durable-execution substrate | ✅ exists |
| 26 | Multi-tenant (foundation/multi_tenant.md) |
The tenancy axis; moved into the foundation set by decision 77 | ✅ exists |
| 27 | Data publishing (data_publishing_transformation.md, data_publishing_privacy_guidelines.md) |
How operator data is transformed/published | ✅ exists |
| 28 | Operator runbooks (runbooks/, developer/) |
Operator-specific operational notes | ✅ exists (see Part 2 caveats) |
At the time of the audit, docs/ held 294 files across 43 directories. Many files served purposes
other than documentation. The audit also found stale material from the pre-swarm "three-layer" /
Cursor-rules era, off-topic material such as home-automation troubleshooting and a conference
transcript, and operator-personal material such as health plans and an outreach contact list.
The audit proposed separating the durable architecture and operating docs from these other files.
Architecture/operating docs that match the audited reality:
architecture.md, taxonomy.md, phases.md, data_types.md, neotoma_vs_alternatives.md,
foundation/* (28 authored documents: a 3-document always-read kernel; 14 path-keyed documents, five of
them one per external system — github.md, gmail.md, calendar.md, telegram.md, payments.md, one
the acceptance suite's design, conformance_suite.md, one the layered planning records above a task,
planning_model.md, and one the tenancy boundary, multi_tenant.md; and 11
companions — charter.md, the purpose the corpus serves; harness_carriers.md, which carrier delivers
which payload into each harness; application.md, the application on an instance of the record and where its parts live; scenarios.md, workflows.md,
migration.md, revisions.md, decision_state.md, the register projected onto ruled/merged/implemented,
foundation/status.md, the dated implementation-gap measurement, foundation/skill_inventory.md, the
dated skill-corpus measurement (stage 0 for the skills migration), and foundation/rule_inventory.md,
every place a rule is stated across the harnesses and stores, generated by
execution/scripts/render_rule_inventory.py and kept as the historical Stage-0 snapshot (later
measurements are the private milestone audit in runbooks/rule_inventory_audit.md). foundation/projection/ is generated by
execution/scripts/render_reading_projection.py (decision 66) and is not authored documentation, so it is
not counted here), swarm_smoke_test_plan.md, smoke_test_runbook.md,
agent_execution_runbook.md, agent_execution_architecture.md, a2a.md, pr_review_routing.md,
swarm-trigger-layer.md, swarm_github_interaction_design.md,
swarm_qa_evals_design.md, swarm_qa_evals_qe3_design.md, durable_execution_substrate.md, aauth.md,
aauth/keys.md, secrets_management.md, credential_management.md, credential_health.md,
session_integrity.md, setup.md, cloud_hosting.md, daemon_rc_autodeploy.md,
mcp_server_development_guide.md, linting-guide.md, test-setup-guide.md, testing/*,
data_publishing_transformation.md, data_publishing_privacy_guidelines.md, agents/* (generated),
runbooks/agent-rename-and-isolation.md.
| Item | Problem | Disposition |
|---|---|---|
docs/README.md |
Index describes an old Asana/Cursor-rules repo (data_rules.md, /reports/asana-api-coverage-analysis.md, /plans/neotoma-architecture-integration.md) that no longer exists |
Rewrite as a real index (done — see README.md) |
docs/shared/** (31 files) |
Legacy "three-layer Strategy/Execution/Truth" foundation + 9 cursor agent-policy files; superseded by the entity/agent_policy model. Doubled path docs/shared/docs/... |
Archive under docs/archive/ or delete after confirming nothing references it |
cursor_directory.md, foundation-vs-ateles-rules.md, skills-and-hooks-before-after.md, skills-and-hooks-guide.md, cursor_rules/* |
Cursor/foundation-era guidance, largely pre-swarm | Archive; fold any still-true bits into linting-guide.md/setup.md |
legacy_data_types_inventory.md |
Self-described legacy; superseded by data_types.md |
Archive (keep as historical inventory) |
| Item | Problem | Disposition |
|---|---|---|
docs/mcp/** (145 files: 56 .py, shell, CI, requirements.txt) |
These are full MCP server projects/code (asana, onepassword, homekit, parquet, google-search-console, whatsapp, x_api, typefully, interviews_admin, google-maps), not docs. They dominate the docs/ file count and pollute every docs metric. |
Relocate to a top-level mcp-servers/ (or execution/mcp/vendor/); keep only true per-server README.md docs under docs/mcp/ if desired |
docs/developer/* |
Operator-specific operational rules (chatgpt-share, formica issue processing, finances-dashboard diagnostics, cloudflare token directive) | Relocate to docs/runbooks/ (operator runbooks) and de-PII |
| Item | Problem | Disposition |
|---|---|---|
transcript_peter_thiel_sxsw_2013_*.md |
A 2013 conference transcript — not repo documentation | Remove from docs/ (belongs in Neotoma as a transcription/source entity, not the public doc set) |
homekit_*.md (4), docker_vs_native_homeassistant.md, why_mdns_reflector_may_not_work.md, tunnel_processes_cleanup.md |
Home-automation troubleshooting notes — operator's smart-home, unrelated to the swarm | Move to docs/runbooks/home-automation/ or out of the repo |
generic_pdf_form_filler_guide.md |
A standalone how-to unrelated to the swarm core | Move to docs/runbooks/ |
neotoma_developer_release_tester_* (2), neotoma_io_redirect.md, neotoma_post_lookup.md, agent_dependency_discovery_signal_loss.md |
Neotoma-product GTM / essay artifacts, not Ateles architecture | Move to the neotoma repo |
A first-principles PII audit of the working tree and all 51 commits found the third-party exposure was
bounded and shallow: one file, in one commit (94aa438), plus operator-own health notes. No secrets,
IBANs, national IDs, or real third-party emails/phones anywhere; the 2 Bitcoin matches are a public
"onboarding buddy" tip address in loop-start, not operator PII.
| Item | Concern | Action taken |
|---|---|---|
docs/outreach/LINKEDIN_ICP_PRIORITY_LIST.md (814 people) |
Third-party names + LinkedIn profiles in a public repo → RGPD Art. 6(1)(f) | Removed from the working tree; docs/outreach/ gitignored. History scrub pending — see runbooks/pii-history-scrub.md |
docs/health/lean_bulk_8_week_plan_2026.md, docs/health/facial_puffiness_mitigation_checklist.md |
Operator's personal health data | Removed from the working tree; docs/health/ gitignored. History scrub pending (same runbook) |
docs/developer/neotoma_finances_dashboard_neotoma_side_diagnostics.md |
Suspected financial specifics | Re-assessed: not PII. It is a technical API-diagnostics runbook (HTTP checks, endpoint contracts) — kept |
Why the working-tree removal isn't enough. On a public repo the file remains fully browsable in the old commit until
main's history is rewritten and force-pushed, and GitHub purges its cached views. That irreversible step is the operator's to run — the history-scrub runbook has the exact commands, a GitHub Support request template, and a PR/fork checklist.
language_command.md, learn_neotoma_command.md, neotoma_learn_command.md, store_neotoma_command.md,
agent_auto_invocation.md overlap with their .claude/skills/<name>/SKILL.md. Keep only if they add
operator-facing context the SKILL.md omits; otherwise link to the skill from a single "skills" reference.
- Rewrote
README.mdfrom the functionality audit — dual framing, accurate daemon/agent counts, honest maturity, corrected the launchd claims, fixed the "MIT" claim by adding a realLICENSE. - Created the original
docs/icp.mdfrom the functionality audit. - Rewrote
docs/README.md— a true documentation index organized by the ICP journey (replacing the stale Asana/Cursor-era index). - Created
docs/capabilities.md— the operational surface (18 daemons + skill categories by domain), documenting the previously under-represented half of the repo. - Created
docs/forking.md— the adopt-by-forking guide: what's operator-specific vs. portable. - Created this plan (
docs/documentation_plan.md). - Added
LICENSE(MIT) to match the README's repeated license claim. - Removed the PII files (Part 2.E) from the working tree, gitignored
docs/outreach/anddocs/health/to prevent recurrence, and wrote the history-scrub runbook for the operator to finish the job onmain.
Done (2026-06-25):
- ✅ Ran the history scrub —
main+ 45 branches rewritten withgit filter-repoand force-pushed; the PII is unreachable in a fresh clone, and the PR-ref + cache purge is requested from GitHub Support. See runbooks/pii-history-scrub.md. - ✅ Moved off-topic docs out of the doc set — HomeKit/home-automation (7) + the PDF-form-filler guide
relocated under runbooks/ (
runbooks/home-automation/); the SXSW transcript, the agent-discovery essay, and the 2 Neotoma developer-release GTM docs archived under archive/ (to be re-homed to the neotoma repo / Neotoma). The 2 Neotoma ops runbooks (neotoma_io_redirect,neotoma_post_lookup) were kept as operator runbooks under runbooks/ —io_redirectdrives a live script in this repo. - ✅ Folded the command-docs (Part 2.F) — the 5 SKILL.md-duplicating command docs archived under
archive/; the
.claude/skills/<name>/SKILL.mdmirror is the source of truth. - ✅ Archived the dead Cursor-era docs (Part 2.B, partial) —
foundation-vs-ateles-rules,skills-and-hooks-{before-after,guide},legacy_data_types_inventory,cursor_directory,cursor_rules/→ archive/ (gitleaks allowlist paths updated). (docs/shared/**itself was handled separately — see the next bullet.) - ✅ Relocated
docs/mcp/**(145 files, Part 2.C) → top-levelmcp-servers/— gitleaks allowlist + index note updated; no submodules / imports / CI affected. Side effect: doc-lint failures 160 → 101. - ✅ Reconciled
docs/shared/**(Part 2.B, option 2) — relocated the 3 live policy docs to policies/ (agent-workflow-requirements,agent-mcp-access-policy,agent-data-rules, now withPurpose/Scopeheaders) and repointed their 9 citations across 3 linters,.gitleaks.toml, andlinting-guide.md; archived the other 28 files → archive/shared/. Doc-lint failures 101 → 70.
Still pending:
- (nicety) Build a single consolidated skills reference if the archived command-docs' context is still wanted.
All the planned relocations (Parts 2.B–2.F) are now done; only the optional consolidated skills reference
remains. The residual doc-lint debt (70 files) is mostly pre-existing top-level docs that predate the
Purpose/Scope requirement — a separate, lower-priority cleanup.