docs(research): split api/ vs design/, inline external citations - #51
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
The flat `docs/research/` layout muddled two genuinely different artifact types: outward-facing notes describing the Anthropic API surface, and inward-facing surveys of reference projects that informed oxide-code design choices. Splitting into `api/` and `design/` subdirectories matches that natural cleavage; the README index becomes two tables. Within `design/`, the survey shape is now consistent: - `## Reference Implementations` everywhere (was `Reference Projects` in `tui.md`). - Alphabetical project order: Claude Code → OpenAI Codex → opencode. - `### Project (Language)` subheadings, framework parenthetical kept only in `tui.md` where the framework is the topic. - Per-project `**Sources:**` footer co-locates external citations with the prose that introduces them; the bottom `## Sources` section collapses to a single flat list of oxide-code references (drops the `### oxide-code` / `### Reference projects` subheading split that had the same project names appearing twice on one page — once Title-Case at top, once lowercase under Sources). - `learn-claude-code` dropped from `session-persistence.md` — it's a tutorial repo, not a peer reference project. Cross-doc links normalized: drop the `./` prefix, give each link a `Document Title § Section Name` body that matches the README's friendly title (`anthropic-api § ...` → `Anthropic API § ...`, etc.). The `file-tracking.md` self-link to session-persistence picks up an actual anchor (`#forward-compatibility`) instead of plain-text `§`. Inbound code references in `actor.rs` and `betas.rs` updated to point at the new paths.
hakula139force-pushed
the
docs/research-restructure
branch
from
April 29, 2026 10:42
ca74011 to
0371268CompareUh oh!
There was an error while loading. Please reload this page.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 intoapi/anddesign/subdirectories matches that natural cleavage; the README index becomes two tables.The redundancy that prompted this PR —
Reference Implementationsnear the top of each survey, thenReference projectsagain 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## Sourcessection collapses to a single flat list of oxide-code references.Design decisions
Reference Implementationssections or strip design surveys of their motivating analysis. Conventions are scoped per-subdir.**Sources:**footers, not a separateReference projectssection. 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.tui.md. Other design docs use### Project (Language)since the framework isn't the topic;tui.mdkeeps### Claude Code (TypeScript / Ink)and### OpenAI Codex (Rust / ratatui)because the framework is the topic.tui.mdhad Codex and opencode swapped; reordered.learn-claude-codedropped fromsession-persistence.md. It's a tutorial repo, not an actual peer reference project.Changes
docs/research/README.mdapi/) and Design surveys (4 docs indesign/).docs/research/api/anthropic-api.md,docs/research/api/extended-thinking.md,docs/research/api/system-prompt.mdapi/subdir. Cross-doc links lose the./prefix and adopt theDocument Title § Section Namelink text convention so each rendered link reads as a friendly reference.docs/research/design/file-tracking.md,docs/research/design/tool-truncation.mddesign/. External citations moved up into per-project**Sources:**footers; bottom## Sourcesflattened to oxide-code-only entries. opencode subsection drops the(TypeScript / Effect)parenthetical —Effectisn't the topic of these surveys.docs/research/design/tui.mddesign/.## Reference Projectsrenamed 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.mddesign/. Droppedlearn-claude-codefrom 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.rsTest plan
cargo buildcompiles cleanly (inbound code references resolve)pnpm lint— markdownlint passes on all 19 filespnpm spellcheck— 0 issues**Sources:**footers carry the same content the deleted bottom subsections did