docs(research): split api/ vs design/, inline external citations

[hakula139]

Summary

The flat docs/research/ layout muddled two genuinely different artifact types: outward-facing notes describing the Anthropic API surface, and inward-facing surveys that informed oxide-code design choices. Splitting into api/ and design/ subdirectories matches that natural cleavage; the README index becomes two tables.

The redundancy that prompted this PR — Reference Implementations near the top of each survey, then Reference projects again under the bottom ## Sources (with the same project names appearing twice on one page, once Title-Case and once lowercase) — is gone. External citations now live in a **Sources:** footer at the end of each project subsection; the bottom ## Sources section collapses to a single flat list of oxide-code references.

Design decisions

• Two subdirs, not one canonical skeleton. API references and design surveys have different natural shapes. Forcing every doc into one template would either bloat API refs with empty Reference Implementations sections or strip design surveys of their motivating analysis. Conventions are scoped per-subdir.
• Per-project **Sources:** footers, not a separate Reference projects section. Inline citations co-locate evidence with the prose that introduces it; the bottom of each design doc no longer repeats the project list with file paths.
• Framework parenthetical kept only in tui.md. Other design docs use ### Project (Language) since the framework isn't the topic; tui.md keeps ### Claude Code (TypeScript / Ink) and ### OpenAI Codex (Rust / ratatui) because the framework is the topic.
• Alphabetical project order: Claude Code → OpenAI Codex → opencode. tui.md had Codex and opencode swapped; reordered.
• learn-claude-code dropped from session-persistence.md. It's a tutorial repo, not an actual peer reference project.

Changes

File	Description
docs/research/README.md	Rewritten as a two-table index: API references (3 docs in api/) and Design surveys (4 docs in design/).
docs/research/api/anthropic-api.md, docs/research/api/extended-thinking.md, docs/research/api/system-prompt.md	Moved into api/ subdir. Cross-doc links lose the ./ prefix and adopt the Document Title § Section Name link text convention so each rendered link reads as a friendly reference.
docs/research/design/file-tracking.md, docs/research/design/tool-truncation.md	Moved into design/. External citations moved up into per-project **Sources:** footers; bottom ## Sources flattened to oxide-code-only entries. opencode subsection drops the (TypeScript / Effect) parenthetical — Effect isn't the topic of these surveys.
docs/research/design/tui.md	Moved into design/. ## Reference Projects renamed to ## Reference Implementations; OpenAI Codex and opencode subsections swapped to land alphabetical order; intro paragraph project list reordered. Framework parenthetical kept (/ Ink, / ratatui, / @opentui + Solid.js) since the framework is the topic.
docs/research/design/session-persistence.md	Moved into design/. Dropped learn-claude-code from the intro list and removed the ### learn-claude-code (Python) subsection.
crates/oxide-code/src/client/anthropic/betas.rs, crates/oxide-code/src/session/actor.rs	Two inbound code-comment references updated to the new doc paths.

Test plan

• cargo build compiles cleanly (inbound code references resolve)
• pnpm lint — markdownlint passes on all 19 files
• pnpm spellcheck — 0 issues
• Manual review: every internal cross-doc link still resolves; inline **Sources:** footers carry the same content the deleted bottom subsections did

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!