docs: rebuild the technical documentation as architecture reference, not project history#165
Merged
EtienneLescot merged 17 commits intoJul 26, 2026
Conversation
…eleton git mv only: surviving docs land on their target names so history follows, everything that is migration/merge/POC narrative moves to _harvest/ to be harvested and deleted. Adds scripts/check-docs.mjs as the gate.
…d reference README.md is the index (by type, then subsystem); decisions.md is the ledger of what is settled and what was measured and rejected, and the one place allowed to name removed surfaces. Also fixes two live errors found on the way: poc-d3d/README told you to fetch a floating ffmpeg master-latest build when .cargo/config.toml pins n8.1.2 (a mismatch makes the addon's require() fail), and drops a stale worktree handoff that was tracked in .worktrees/.
Salvaged from two worker runs that overran their step budget. Drops the process leakage from overview.md and replaces its subsystem table with a reading order, since README.md is already the index.
…docs Corrects a claim the old roadmap had backwards: AI_FEATURES_ENABLED defaults to true, not off.
The timeline doc was a French plan for a refactor that has since shipped; it is now a description of the model in force, and it names three coordinate frames rather than the two the plan discussed.
…49 lines Keeps every measured number, the G0 gate and the measurement hazards; compresses each rejected route (wgpu, Tauri, renderer-driven native encode, encoder pipelining, software VP9) to one paragraph with the reason not to re-propose it. Corrects a stale Known-gaps entry: the concurrent-save data-loss bug it described as open is fixed — DocumentService serialises saves per project and writes atomically. Only the one corrupt bench fixture survives.
… architecture Moves the performance material out of export-pipeline.md and drops its supersedes preamble. Two stale claims corrected against the code: audio.rs now mixes every audio stream (the av_find_best_stream single-track defect that dropped the macOS mic is fixed), and the concurrent-save corruption is fixed — what survives is the rule that a partial document which parses is worse than one that does not.
recording.md merges the Windows and macOS recorder docs into one description with a per-platform helper-contract table, replacing two roadmaps' worth of goals, phases and ship criteria.
Locates the cursor settings UI where it actually is (CursorPane in RightPanes.tsx, reached through the v4 inspector's cursor facet) instead of the deleted panel the old inventory named.
Widens the STT spec into the whole audio-to-captions path and documents the caption layer for the first time: cues are a rendering of the transcript, not a parallel edit surface. Drops the CTranslate2 history and the changelog.
Replaces 19 sequenced spec files (~4,800 lines) that targeted a deleted editor shell with 198 surface-organised checks derived from the components that exist, merged with the RC smoke checklist.
Everything worth keeping from the merge roadmaps, the collision analysis, the two source-repo inventories, the STT migration and POC plans, the recorder roadmaps, the poc-d3d stage logs and the 26 spec files has been folded into the architecture, engineering and testing docs. The rest was history, and git already has it.
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
ci.yml was scoped to main only, so every PR landing on the long-lived feat/ai-edition integration branch merged with no lint, no typecheck, no tests and no PR-title check. Adds a Docs job running check-docs.mjs. It skips the shared setup action on purpose: the script imports only node builtins, so npm ci would cost a minute for nothing. Drops this branch's comment edit to tests/e2e/roadmap-coverage.spec.ts — #166 deletes that file, and modify-vs-delete is a conflict for no gain.
…ear lint Turning CI on for feat/ai-edition surfaced failures that had been invisible because ci.yml only ran on main. None were caused by the docs work. compositorViewService: the absolute-pin test hardcoded "C:/vendor/ffmpeg", which path.isAbsolute rejects on POSIX, so the pin got nested under the crate dir. Spell it through path.resolve and assert the behaviour instead of one platform's drive letter. The production code was right. whisperServer: two tests wrote a fake helper binary with the default mode, which is not executable on POSIX, so the manager refused it before reaching the assertion under test. Write it 0o755. Lint: biome format across 11 files, plus five dead variables it would only remove under --unsafe. Each checked for side effects first — run_wcpp's reported_rtf was written and never read (rtf is recomputed from wall_s), and e2e-pipeline-smoke keeps its dynamic import, only dropping the unused binding.
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 free
to 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.
Renames
./docsto./technical-documentationand rebuilds it as architecture and engineering reference organised by type, then by subsystem.Net: −14,939 / +3,533 lines. 22 docs, 12 Mermaid diagrams.
What was swept
The tree had accumulated the shape of its own history: a merge roadmap with
T01–T25andP1–P3task tables carrying commit hashes, a collision analysis, inventories of both source repos, a main-vs-branch audit and its remediation spec, two STT migration/POC plans, two recorder roadmaps, thepoc-d3dS0–S8 stage logs, and 26 spec files. All of it is gone. Files that survived moved withgit mv, sogit log --followstill works on them.The 19
specs/computer-use/files (~4,800 lines) were replaced by a single 198-check manual E2E checklist. They were unrunnable: they targetedTimelinePane,Bottombar,RightPanelStack,TitlebarandTranscriptEditor, none of which exist any more.Structure
architecture/(14) — overview, document-model, timeline-model, editor-shell, preview, native-compositor, export-pipeline, recording, cursor, transcription-and-captions, ai-agent, llm-providers, native-bridge, decisionsengineering/(4) — rendering-performance, build-and-packaging, ci-workflows, release-and-secretstesting/(3) — writing-tests, manual-e2e-checklist, native-cursor-diagnosticsThree subsystems were undocumented and now are: the preview path, the native compositor, and the caption layer.
architecture/decisions.mdis the decision ledger — what is settled, and what was measured and rejected, with the number that killed it. It is the antidote to re-proposing a route every quarter.Stale claims corrected against the code
Every factual claim was checked against the file that implements it. Five were wrong:
AI_FEATURES_ENABLEDdefaults offtrueaudio.rsdecodes one stream, dropping the macOS micpoc-d3dneeds ffmpegmaster-latestn8.1.2; a mismatch breaks the addon'srequire()package.jsonThe last two were live errors rather than doc rot.
poc-d3d/README.md's build instruction would have sent someone after the wrong ffmpeg build.Also in here
architecture/overview.mdas Mermaid — it renders on GitHub, diffs, and follows the reader's theme.build.yml,AGENTS.md,.harness/,poc-d3d/README.md,tools/stt-eval/.npm run docs:check(scripts/check-docs.mjs) fails on a broken relative link, a staledocs/prefix, or any doc presenting a removed component as current. Not wired into CI — happy to add a job if wanted..worktrees/.Risk
Documentation only. The sole code changes are comment text and one string literal in
scripts/fetch-ffmpeg.mjs(a path in an error message) — verified with a non-comment diff filter. No behaviour is touched.Known follow-up
tests/e2e/roadmap-coverage.spec.tscannot pass: it targets the deleted shell with aschemaVersion: 3fixture. Its comment now says so; rewriting or dropping it is tracked separately rather than smuggled into a docs PR.