INDEX.md

TeaAgent Documentation Index

2026-06-17

Last reviewed: 2026-06-17 Review trigger: New front-door docs, supersession links, or validation command changes.

This is the curated front door for TeaAgent documentation. It is intentionally not an exhaustive file list. Use it to find the current source of truth, then follow dated evidence documents only when you need the reasoning trail.

Reading Model

TeaAgent docs are organized as three shelves:

Shelf	Purpose	Reader rule
Current truth	Stable files that describe what to trust or do now.	Read these first; update them when behavior, status, or gates change.
Active work	Ticket indexes, plans, and ledgers that still drive execution.	Read only when choosing or verifying current work.
Historical evidence	Dated audits, reviews, surveys, completed plans, and reasoning packages.	Do not reread by default; use Historical Evidence Index when you need provenance.

No historical file is deleted or moved by this model. The generated Docs Inventory remains the exhaustive catalog.

Start Here

Need	Start here	Status rule
What can the owner-operator trust today?	Daily-Driver Current Status	Current truth for owner-operated daily use; update whenever TUI, chat, agent mode, approval, cost, undo, or resume behavior changes.
Which docs should I read, skip, or treat as history?	Historical Evidence Index	Curated map for dated/completed/high-overlap packages; preserves history without making it current truth.
What is the documentation operating model?	Documentation Operating Model	Governance rulebook for claim types, TTL, owners, supersession, and CI guard targets.
What should be done next?	Work Direction Execution Index	Sprint 1 truth pass (WDA-001, WDB-001, WDB-003, WDG-001/002) after the June 10 critical review.
How should ADR 0032 M1-M6 be executed?	ADR 0032 M1-M6 Work Plan	Event-spine migration plan for audit, receipts/evidence, gates, hooks, ContextBus, and webhooks.
Exhaustive docs inventory (generated)	Docs Inventory	Deterministic catalog; not current truth — use this index table first.
Documentation aging dashboard (generated)	Docs Aging Dashboard	Current-truth review freshness grouped by owner surface.
Command snippet inventory (generated)	Command Snippet Inventory	Guide command coverage vs smoke/manual registry.

Status vocabulary

Active indexes and work-item ledgers use the canonical states in Document State Model. When updating a ledger row, map legacy labels instead of introducing new synonyms:

Legacy label	Canonical state
OPEN	Active
DONE / Complete / Closed	Fixed
Pending	Proposed
In Progress	Active
PARTIAL	Partially fixed
Stale	Superseded

Roadmap tables may keep horizon-specific wording (In Progress, Pending) but governance ledgers should prefer the canonical set above.

Current Truth

Question	Canonical source
Project identity and scope	Harness-First Direction
Current owner-operated daily behavior	Daily-Driver Current Status
Acceptance flow inventory	Acceptance Coverage
Roadmap state	Roadmap Status
Ticket execution order for current harness work	Ticket Execution Plans
Work direction Sprint 1 tickets	Work Direction Execution Index
Module ownership and inspection paths	Module Documentation Index
Release gates	Release Checklist and Daily-Driver Release Gates
Permission and approval behavior	Permission And Approval Playbook
Operator trust model	Operator Trust Model
Owner friction intake	Operator Friction Log
Historical evidence and completed/redundant packages	Historical Evidence Index

Evidence And Review

Evidence packages are historical unless this index names them as current truth. Use this short list instead of scanning every dated analysis file.

Need	Start here	Status
Current direction and scope	Harness-First Direction	Current direction record.
Latest broad review package	System Critical Review Package 2026-06-10	Current dated evidence package; not timeless truth.
Reflective intent review	Intent Critical Review And Worklist	Historical input to harness-first direction.
Documentation system review	Historical Evidence Index	Completed/redundant docs optimization package; read through the archive index.
Older review packages, competitor surveys, daily-driver packages, and completed plans	Historical Evidence Index	Preserved provenance; do not treat as current status.

Processes

Process	Document
Signal-to-acceptance-gap conversion	Signal To Acceptance Gap
Competitor gap watch	OpenCode Gap Watch
Community presence and dev-rel	Community Presence
Post-fix re-audit	Postfix Reaudit Process
Owner-operated daily verification	Daily-Driver Verification
Owner-operated manual QA smoke	Daily-Driver Manual QA Smoke
Quarterly competitor refresh	Quarterly Competitor Refresh Process · Release Checklist
Trust and audit whitepaper	Trust and Audit Whitepaper
When not to use TeaAgent	When Not to Use TeaAgent

Governance

Rule surface	Purpose
Governance Index	Standards and process entry point.
Document State Model	Canonical state vocabulary for findings, risks, issues, tickets, and roadmap rows.
Risk Issue Roadmap Workflow	Pipeline from finding to issue, ticket, roadmap, verification, and supersession.
Documentation Taxonomy And Ownership	Where each document type belongs and who owns it.
Documentation Maintenance Policy	Short policy for adding, updating, and validating docs.
Documentation Operating Model	Practical rules for claim classes, freshness windows, source-of-truth conflicts, and CI guard scope.
Documentation Audit Cadence	When to run docs gates and which evidence artifacts to keep.
Command Snippet Registry	Smoke vs manual coverage for high-value guide commands.
Coverage Omit Ledger	Governance ledger for files and directories omitted from test coverage reporting.
Architecture Decision Records	Index of ADRs and their current accepted/closed states.

Plans And Work

Plan	Use it for
Work Direction Execution Index	Current execution order: Sprint 1 truth pass (WDA/WDB/WDG) after June 10 review.
ADR 0032 M1-M6 Work Plan	Event-spine migration slices from AuditLogger consumer through ContextBus/webhook cleanup.
Work Direction Decomposition	Full WD-A … WD-H backlog with acceptance gates.
Documentation Optimization Master Plan	Prioritizing documentation work by stability, UX, risk, and ROI.
Documentation Optimization Work Items	Concrete task execution ledger.
Daily-Driver Complete Work Plan	Historical daily-driver risk, feasibility, ROI, and sequence; use harness-first direction for current persona claims.
Roadmap Work Items	Product roadmap work items and acceptance criteria.
Phase 0 Priority Work Items	Trust-repair tasks derived from project-state review.
Phase 0 Governance Closure Report	Closure evidence for coverage omit, dependency audit, and ADR-state governance.
Dynamic Skill E2E Test Roadmap	Test roadmap for generated skills, RSS fixture checks, and long result handling.
Dynamic Skill And Long Result Work Items	Task ledger for lifecycle states, direct-write quarantine, RSS acceptance, long-result envelopes, and behavioral evals.
Dynamic Skill Lifecycle And Result Flow	Architecture target for candidate install, activation, long-result preservation, and output verification.
Seven Control Loops Work Items	Cross-cutting task ledger for spec-first, dynamic workflow, goal loops, model routing, review, memory, and human gates.
Seven Control Loops Integration Map	Architecture map for integrating the seven control loops into existing TeaAgent surfaces.
Community Pain Points Response Plan	Work plan for routing opacity, memory pollution, review cost, long-task drift, hook confusion, skill/MCP risk, and fake success.
System Improvement Work Directions	2026-06-06 workstream and ticket decomposition for trust claims, conversation UX, multi-agent safety, observability, integration contracts, docs governance, and competitive positioning.
System Review Workstream Traceability	Evidence-to-workstream trace for the June 6 critique package, including proof gates and validation commands.

Historical Reference Plans

The following plans are historical evidence from earlier passes. They have supersession notes linking to current work. Use them for reasoning trail, not for current status.

Plan	Historical value
Competitive Positioning Plan	May 2026 competitive baseline; superseded by Competitor Signal Survey.
Remediation Roadmap	Post-audit remediation from 2026-05-29; absorbed into Phase 0 trust repair.
Governance Hardening	Early governance plan (2026-05-28); superseded by Documentation Operating Model.
Comprehensive Plan All Aspects	Phase 0 audit consolidation; superseded by Complete Work Plan.
UX Improvement Roadmap	Early UX gap survey; absorbed into P0-A through P1-D workstreams.
System Transparency Engineering Plan	Transparency pass; absorbed into P0-B, P0-D, P1-B, P2-B.
Future Roadmap Backlog	Phase 0 horizon roadmap; restructured into P0–P3 priority stack.
Agent Ecosystem Acceptance Roadmap	Early ecosystem roadmap; acceptance tracking now in ticket index.

Security And Reliability

Topic	Start here
Threat model	Threat Model
Security risk register	Risk Register And Threat Model
Phase 0 trust repair	Phase 0 Trust Repair Risk Brief
Severity calibration	Security Severity Calibration Rubric
Dependency audit scope refresh	Dependency Audit Scope Refresh
FMEA	FMEA
Trust-sensitive invariants	Trust Sensitive Invariants
UX stability contract	UX Stability Contract
Dependency audit policy	Dependency Audit Policy

Guides And References

Surface	Documentation
CLI	CLI and USAGE
Conversation UX	Chat Surface Semantics and Background/Resume Vocabulary
TUI	TUI Daily-Driver Guide and TUI Chat Reference
Agent mode	Agent Mode Operator Guide
APIs	API Index
Module references	Module Documentation Index
Tools	Tool Authoring Guide
Providers	Provider Authoring Guide

Rules For Reading Dated Documents

• Dated analysis, reviews, surveys, audits, and work logs are evidence snapshots.
• Stable entry points and ledgers own current truth.
• If a dated document contradicts a stable current source, prefer the stable source and add a supersession note if the contradiction could mislead.
• Supersession notes follow the convention defined in Documentation Operating Model: > Supersession note, YYYY-MM-DD: This file is historical evidence. For current status, use <new-source>. The relevant item is now <State> because <short evidence>.
• Test counts, full-suite claims, dependency audit results, and competitor observations must include a date, command, and commit or they should be treated as stale.
• When adding a new document, link it from one active front door or explicitly mark it as archived evidence.

Validation

After governance-sensitive documentation edits, run:

python3 scripts/verify_docs.sh