docs: add progressive disclosure documentation

[BenWeekes]

Summary

• Add docs/ai/ progressive disclosure documentation following the ai-devkit standard
• L0 repo card with identity and L1 index
• 8 L1 structured summaries (setup, architecture, code map, conventions, workflows, interfaces, gotchas, security)
• 3 L2 deep dives (rendering controller, event system, build pipeline)
• AGENTS.md at repo root as portable AI entry point
• Updated CLAUDE.md to reference @AGENTS.md

Test plan

• Verify all relative links between L0/L1/L2 resolve correctly
• Verify L0 is under 50 lines, each L1 is 80-200 lines, total L1 under 1600 lines
• Verify L2 files are self-contained with "When to Read This" callouts
• Spot-check: can an agent answer "How do I add a new event type?" from L1 alone?

[digitallysavvy]

Reviewed the latest PR on docs/progressive-disclosure against main.

PR summary under review:

• Add docs/ai/ progressive disclosure documentation
• Add L0 repo card
• Add 8 L1 summaries
• Add 3 deep dives described as L2
• Add AGENTS.md
• Update CLAUDE.md to reference @AGENTS.md

High-Level Summary

This PR is documentation-only and is directionally strong. The new material gives good repo orientation, captures the monorepo/source-layout quirk, and reflects several important runtime behaviors correctly, especially around RTM optionality, rendering modes, and the CI release gate.

The main problem is accuracy drift in a few places. Some of the new docs describe commands or source locations that do not exist, and the attached validation file claims acceptance criteria were satisfied without actually testing the stated condition. Because these files are meant to guide future agents and contributors, those inaccuracies matter more than they would in ordinary prose docs.

Findings

1. Invalid root typecheck command is documented as a standard workflow

• Severity: medium
• Files:
  • docs/ai/L1/01_setup.md:32
  • docs/ai/L1/05_workflows.md:51
  • package.json:1

The docs tell readers to run pnpm typecheck, but the root package.json does not define a typecheck script. The available root scripts are build, test, test:coverage, lint, lint:fix, format, format:check, and clean.

Why this matters:

• This is the kind of command an agent or maintainer will copy verbatim.
• It will fail immediately and undermines trust in the new progressive docs.

Suggested fix:

• Either add a real root typecheck script, or update the docs to the commands that actually exist:
  • pnpm --filter agora-agent-client-toolkit typecheck
  • pnpm --filter agora-agent-client-toolkit-react typecheck

2. “Add a new event type” workflow points to the wrong file for handler definitions

• Severity: medium
• Files:
  • docs/ai/L1/05_workflows.md:8
  • src/core/events.ts:31

The workflow says to add the handler signature to AgoraVoiceAIEventHandlers in src/core/types.ts, but that interface is actually defined in src/core/events.ts.

Why this matters:

• This is one of the explicit spot-check tasks in the PR test plan.
• A maintainer following the current instructions from L1 will go to the wrong file.

Suggested fix:

• Change step 2 to reference src/core/events.ts.
• Consider tightening the full sequence to:
  • add enum member in src/core/events.ts
  • add handler signature in src/core/events.ts
  • add payload type in src/core/types.ts if needed
  • emit from src/core/conversational-ai.ts
  • export from src/index.ts

3. The attached test-results file does not prove the stated L1-only acceptance criterion

• Severity: medium
• Files:
  • docs/ai/test-results.md:59
  • docs/ai/test-results.md:26-30

The PR test plan says:

Spot-check: can an agent answer "How do I add a new event type?" from L1 alone?

But the recorded result for that question explicitly used deep_dives/event_system, meaning L2 was consulted. The file still reports L1 gaps: 0 and all structural checks passed.

Why this matters:

• The validation artifact is overstating confidence.
• The most important “can L1 stand on its own?” check was not actually demonstrated.

Suggested fix:

• Re-run that spot-check with L0 + L1 only and record it separately.
• If L1 is insufficient, fix L1 and keep the test artifact honest.

4. L2 is described as a distinct level, but the files live under docs/ai/L1/deep_dives/

• Severity: low
• Files:
  • AGENTS.md:3-10
  • docs/ai/test-results.md:26-28
  • docs/ai/L1/deep_dives/_index.md:1

The repo-level guidance says the docs are organized in three levels and that readers should follow “L2 deep-dive links”, while the actual deep-dive files live inside the L1 directory tree as docs/ai/L1/deep_dives/*.md. The test results also refer to these as “L2”.

Why this matters:

• Humans can probably infer the intent.
• Automated loaders or contributors following the folder convention literally may look for docs/ai/L2/ and not find it.

Suggested fix:

• Pick one scheme and use it consistently:
  • either move deep dives to docs/ai/L2/
  • or reword AGENTS/test-results to describe them as deep dives nested under L1

5. Conventions doc overstates the repo’s actual any policy

• Severity: low
• Files:
  • docs/ai/L1/04_conventions.md:8-10
  • src/core/events.ts:1
  • src/core/config.ts:26-29
  • src/utils/metrics.ts:27-28

The doc says “No any”, but the current codebase explicitly uses any in a few real implementation paths, including the event helper generics, RTM listener signatures, and metrics reporter loading.

Why this matters:

• A conventions doc should describe the repo as it exists, not just the desired style.
• Agents using this doc for edits may assume the current codebase is stricter than it really is.

Suggested fix:

• Rephrase this section to something like:
  • “Avoid any by default; prefer unknown and type guards.”
  • “A few compatibility boundaries currently use targeted any with inline suppression.”

Test Plan Assessment

What appears correct:

• Relative links I checked resolve.
• L0 is under 50 lines.
• All 8 L1 files exist and each is within the stated size range.
• Total L1 line count is under 1600.
• Deep dives are self-contained and include “When to Read This” callouts.
• CLAUDE.md correctly points to @AGENTS.md.

What is not fully satisfied:

• The “answer add new event type from L1 alone” acceptance check is not substantiated by docs/ai/test-results.md.

Recommendation

1. Fix the invalid typecheck command references.
2. Fix the wrong file reference in the event workflow.
3. Correct the validation artifact so it reflects what was actually tested.
4. Normalize the L2/deep-dive location terminology.

Overall Verdict

The documentation set is useful and close, but there are enough factual mismatches in the “how to work here” guidance that it should be tightened before it becomes the canonical AI entry point.