project-docs

The project is ready to be shared with the broader Qpoint team (Tyler, Andrew, Jon, Devin, et al.), but the documentation is inconsistent and incomplete. New team members need to understand the data's limitations, how to pull new calls, run extraction, and ask analytical questions. CLAUDE.md is current, but AGENTS.md is corrupted (find-replace errors), .agents/skills duplicates .claude/skills, and key operational workflows (fetch, upload, extract, index) are undocumented. Additionally, CYCLES.md lists dormant cycles (c3, c4, c7) as active, confusing the board. This cycle cleans up documentation in two phases: Phase 1 (pivot-independent) focuses on structure, hygiene, and operations; Phase 2 (pivot-dependent, after c8) rewrites content affected by the agent-security pivot.

Create a clean, consistent, and navigable documentation suite for team members accessing the repo for the first time. Phase 1 done means: AGENTS.md fixed, .agents/ resolved, setup docs complete, command surface fully documented, root tidied, and cycle board accurate. Phase 2 (deferred) will rewrite README and operations runbook once c8's pivot is finalized.

Phase 1 (pivot-independent, now):

1. Fix AGENTS.md — correct Codex/Claude confusion and align with CLAUDE.md
2. Resolve .agents/skills vs .claude/skills duplication
3. Add .env.example + README Setup section (Node 22, API keys, npm install)
4. Document full command surface (fetch, upload:sagetap, generate, preview, extract, extract:batch, index, analyze) in CLAUDE.md
5. Document missing pipeline scripts (avoma-notes.ts, backfill-speakers.ts, known-entities.ts)
6. Root cleanup: archive DEMO-SUMMARY.md, avoma-summary.txt, fold TODO.md into c8, triage inbox/
7. Cycle board hygiene: park c3.oauth, c4.refinement, c7.avoma-notes (each gets PICKUP.md)
8. Commit pending CLAUDE.md edits

Phase 2 (pivot-dependent, after c8 completes; deferred):

• Rewrite README "How to Interpret the Data" with phase-2 use-case lens
• Write operations runbook (adding new conversations loop)
• Update skill docs + agent tour for post-pivot /analyze and /extract
• Refresh cost/time benchmarks

Out of scope:

• Pipeline/schema/site code changes (c8)
• OAuth/dashboard access control (c3 — parked)

• Phase 1 execution completed 2026-08-20 — commit adb585b (AGENTS.md fixed, .agents/skills resolved, .env.example + README setup section added, command surface documented in CLAUDE.md, root cleanup done, c3/c4/c7 parked with PICKUP.md re-entry notes)
• Phase 2 execution completed 2026-08-20 (same day, integrated with c8's Workstream B):
  • README.md fully rewritten with agent-security framing, phase-1 archive callout, "How to Interpret the Data" section rebuilt around observations[] stream, source-type taxonomy, use-case-evidence patterns (direction + evidenceKind), refreshed limitations (vocabularies encode thesis, restarted-sample caveats), skills tour (/analyze /extract /classify /pickup), and "Adding New Conversations" runbook with registry pre-flight (team roster, companies.json sourceType/domains allowlist, fetch flags, streaming/32K notes)
  • goals.md rewritten for phase-2 use-case-honing lens: evidence weighting rules, use-case scoreboard questions; flagged as user-maintained draft for Mark to tune (closes c8's pending B4 decision item)
  • .claude/skills/analyze/SKILL.md updated to phase-2 schema (loads use-cases.json, observation stream, evidence-kind weighting, phase-1 archive rules)
  • .claude/skills/extract/SKILL.md updated with fetch-first note, registry pre-flight step, streaming/failure notes, phase-2 key files (vocabularies.ts, prompt.ts, use-cases.json)
  • CLAUDE.md updated: pivot framing (QControl = internal code name only), architecture tree (vocabularies.ts, prompt.ts, model.ts, registries, archive/), sourceType resolution in data flow, phase-2 Key Schema section, vocabulary single-source + registry-completeness conventions

Both phases delivered. Project documentation now aligns with team-sharing readiness and the agent-security pivot. Phase 1 established structural hygiene (AGENTS.md corrected, skills consolidated, setup runbook complete, cycle board accurate, root tidy). Phase 2 rewrote the content surface (README, goals, skill guides, CLAUDE.md) to reflect phase-2 vocabulary and use-case-centric framing. New team members can now navigate the repo, understand data interpretation (observations stream, evidence kinds, phase-1 vs. phase-2 schema), run pipelines with confidence (fetch pre-flight, registry validation, streaming notes), and explore via /analyze /extract skills with phase-2 semantics. Outstanding items (not blockers to completion): cost/time benchmark refresh deferred until first phase-2 batch run (phase-1 numbers noted as historical in README); dashboard phase-2 views still under construction in c8 (README carries honest note about phase-1-only views; when c8's C6 site pass lands, remove that caveat from README intro).