docs: per-feature reference notes for the sage-app-foundations work

[spencerwozniak]

Summary

Split out of #37 — pure docs, one markdown file per feature area introduced across #41 / #42 / #43.

• docs/README.md — index
• docs/agentation.md — dev-only feedback overlay (chore: requirements.txt + Agentation dev panel #41)
• docs/chat-backend-integration.md — ChatWidget ↔ /api/chat (feat(frontend): API client, KB UI, live views, chat routing, history panel #43)
• docs/knowledge-base-ui.md — upload modal + KB browser (feat(frontend): API client, KB UI, live views, chat routing, history panel #43)
• docs/in-chat-command-routing.md — shared detectView() + capability section of the chat system prompt (feat(backend): generation + audio endpoints, session listing, capability prompt #42, feat(frontend): API client, KB UI, live views, chat routing, history panel #43)
• docs/generation-endpoints.md — /api/generate/{flashcards,quiz} (feat(backend): generation + audio endpoints, session listing, capability prompt #42)
• docs/audio-generation.md — /api/generate/audio + TTS playback (feat(backend): generation + audio endpoints, session listing, capability prompt #42, feat(frontend): API client, KB UI, live views, chat routing, history panel #43)
• docs/history-panel.md — live session list (feat(backend): generation + audio endpoints, session listing, capability prompt #42, feat(frontend): API client, KB UI, live views, chat routing, history panel #43)

Each doc has a "Files touched" section so reviewers can map features to diffs quickly. Best merged last so the references line up with what's actually on main.

Test plan

• Skim each doc; cross-check "Files touched" against actual file paths post-merge
• Ensure no broken intra-doc links

[zeapsu]

Thanks for splitting the docs into their own PR. I like the idea of having one reference note per feature area, especially for a multi-PR foundations change.

I reviewed this as a docs-only PR in an isolated checkout.

Checks:

• docs-only diff confirmed
• no backend/frontend checks run because no code changed
• relative Markdown link check found one broken link
• “Files touched” sections were spot-checked against current main

I would hold this until the companion PRs land or the docs are adjusted to clearly describe planned companion work.

Main issues:

1. Broken link in docs/README.md

The index links to:

./agentation-install.md

but the PR adds:

docs/agentation.md

Suggested fix: update the link to ./agentation.md, or rename the file to match.

2. Docs reference files that are not present on current main

Examples include:

• frontend/src/components/AgentationDev.tsx
• backend/api/generate.py
• backend/api/audio.py
• frontend/src/components/UploadModal.tsx
• frontend/src/components/KnowledgeBaseWidget.tsx
• frontend/src/components/FlashcardsView.tsx
• frontend/src/components/QuizView.tsx
• frontend/src/components/AudioView.tsx

This may be expected if #41, #42, and #43 land first, but it means this docs PR is not accurate as a standalone merge into current main.

3. docs/README.md has stale branch/base wording

It references an older branch/base context. I’d make this timeless, something like:

Reference notes for Sage feature areas. Each file documents one feature area: what was added, where it lives, and how to use it.

4. history-panel.md is missing from the docs index

The PR adds docs/history-panel.md, but the index does not list it.

5. Audio/history wording is slightly inconsistent

history-panel.md says audio and report views still render sample fixtures, while audio-generation.md describes generated audio playback. If the intended meaning is that audio/report generations are not persisted into history yet, I’d clarify that directly.

Recommended path:

• merge this last, after any companion feature PRs that it documents
• rebase/update the docs once the final file paths are known
• fix the broken link and stale index wording
• include history-panel.md in the index

Great Sage likes the per-feature docs approach. I think this just needs synchronization with the actual merge order so the docs are trustworthy when they hit main.

[zeapsu]

Reviewed after PR #46 merged as 53b83e0. I am leaving this open: #46 explicitly kept the per-feature docs for a later pass, and the docs in this PR are not present on current main. They likely need a refresh against the integrated mainline before merge/closure.