Open source CapCut alternative.
TypeScript
docs: tighten the plain-writing rule and refresh guide style notes
David Le33bf6e69855e
diff --git a/AGENTS.md b/AGENTS.mdindex 3651c174..22fc127c 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -25,7 +25,7 @@ Before changing `site/` UI, routes, API handlers, or data access patterns:- Do not touch repository-root `prototype/` unless the user explicitly asks for that filesystem path. By default, assume requested product changes are for the Mac app or the site/landing page.- Ask before creating any new plan document.- When writing or editing any engineering doc under `docs/`, follow `docs/guides/eng-doc-style.md`.-- Write straight up — in prompts, docs, and summaries. State what to do affirmatively and once; cut filler and negated foils (e.g. "…, which is exactly what not to do", "never re-create it").+- Write straight up — in prompts, docs, commits, code comments, summaries, and UI copy. State what a thing is, once, and stop. Never frame it against what it is not: no "X, not Y", no "X rather than Y", no "instead of Z", no "…, which is exactly what not to do". Cut filler.- Update guides in `docs/guides/` only for major features or durable supported-behavior changes. Do not update guide docs for small styling tweaks, layout adjustments, copy changes, or implementation-only refactors.- Keep guides explanatory. They should teach what the system is, how it works, and which boundaries matter; do not turn guides into feature inventories, implementation logs, duplicated code, or long file lists.- Optimize guides for readability: use plain language, short sections, and only the detail a maintainer needs to understand the supported boundary. Prefer trimming outdated or repetitive detail over adding more paragraphs.diff --git a/CLAUDE.md b/CLAUDE.mdindex 3651c174..22fc127c 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -25,7 +25,7 @@ Before changing `site/` UI, routes, API handlers, or data access patterns:- Do not touch repository-root `prototype/` unless the user explicitly asks for that filesystem path. By default, assume requested product changes are for the Mac app or the site/landing page.- Ask before creating any new plan document.- When writing or editing any engineering doc under `docs/`, follow `docs/guides/eng-doc-style.md`.-- Write straight up — in prompts, docs, and summaries. State what to do affirmatively and once; cut filler and negated foils (e.g. "…, which is exactly what not to do", "never re-create it").+- Write straight up — in prompts, docs, commits, code comments, summaries, and UI copy. State what a thing is, once, and stop. Never frame it against what it is not: no "X, not Y", no "X rather than Y", no "instead of Z", no "…, which is exactly what not to do". Cut filler.- Update guides in `docs/guides/` only for major features or durable supported-behavior changes. Do not update guide docs for small styling tweaks, layout adjustments, copy changes, or implementation-only refactors.- Keep guides explanatory. They should teach what the system is, how it works, and which boundaries matter; do not turn guides into feature inventories, implementation logs, duplicated code, or long file lists.- Optimize guides for readability: use plain language, short sections, and only the detail a maintainer needs to understand the supported boundary. Prefer trimming outdated or repetitive detail over adding more paragraphs.diff --git a/docs/guides/cut/ai-assistant.md b/docs/guides/cut/ai-assistant.mdindex 108f2226..bbe58675 100644--- a/docs/guides/cut/ai-assistant.md+++ b/docs/guides/cut/ai-assistant.md@@ -46,7 +46,7 @@ Every knowledge surface is defined once — the catalog file ships in the engine| The rendered frame | One 640px JPEG | The capture-frame tool, for visual judgment at the playhead. || The footage itself | Up to four 3×3 contact sheets per call | The watch-video tool: the engine samples a source at scene changes plus a steady floor (ffmpeg), the page stamps each cell with its source time, and the result carries the scene-change times. Detect-silence reports dead air the same way, numbers only. |-The system prompt is deliberately small: the voice, the deliverable rule (below), id discipline, the undo-versus-credits asymmetry, and pointers into the skills. The skills carry the deep per-area documentation — editor overview, timeline editing, watching and cutting by content, transitions, titles, audio and subtitles, stock and generation, publish and export — so the always-on cost stays near 12K tokens and detail is pulled only when the model works in that area.+The system prompt is deliberately small: the voice, the deliverable rule (below), id discipline, the undo-versus-credits asymmetry, and pointers into the skills. The skills carry the deep per-area documentation — editor overview, timeline editing, watching and cutting by content, transitions, graphics (titles, shapes, stickers), audio and subtitles, stock and generation, publish and export — so the always-on cost stays near 12K tokens and detail is pulled only when the model works in that area.The snapshot is a compact JSON picture of everything user-visible: project meta, playhead, selection, every media asset with its origin tag, the video track with gaps and transitions, overlay video, soundtrack, titles, subtitle tracks with the first 60 cues, publish metadata, and view state. Numbers are rounded to two decimals and empty fields are omitted. When a list is truncated the snapshot says so, which is the model's cue to call get-state.diff --git a/docs/guides/eng-doc-style.md b/docs/guides/eng-doc-style.mdindex d8b86702..bb58e485 100644--- a/docs/guides/eng-doc-style.md+++ b/docs/guides/eng-doc-style.md@@ -52,21 +52,27 @@ into short ones with space between, so a reader can scan.## Sentences-- Say it straight: "adapters never hold task state," not "adapters should- generally avoid holding task state."+- **State what a thing is, then stop.** Never frame it against what it is not.+ Cut every "X, not Y", "X rather than Y", "X instead of Z", and "*not* the+ other thing" aside. If a reader would not have assumed Y, naming Y teaches+ them a wrong idea on the way to the right one. This holds everywhere prose+ goes: guides, code comments, commit messages, tooltips, and UI copy.+ - Write: the safety class decides whether the action stops.+ - Cut: the class, *not the tool's name*, decides.+ - Write: the preset plays on top of any keyframes.+ - Cut: the preset plays on top of keyframes rather than replacing them.+- Say it straight, with the strong verb.+ - Write: adapters never hold task state.+ - Cut: adapters should generally avoid holding task state.- Short sentences for rules, longer ones for the why. A rule over ~20 words isprobably two.-- Active voice, named actor: "the planner picks the tool," not "the tool is- selected."-- Bold only for rule names and key contrasts. If half the paragraph is bold,- none of it is.+- Active voice, named actor.+ - Write: the planner picks the tool.+ - Cut: the tool is selected.+- Bold only for rule names. If half the paragraph is bold, none of it is.- Italics only for word-level contrast (*what* vs *whether*).-- State what a thing is; skip the strawman. Write "the safety class decides- whether the action stops," not "the class, *not the tool's name*, decides." (A- real two-actor contrast like the model/runtime split above is fine — the foil- is only bad when nobody would have assumed the opposite.)- Code font only for what someone will actually type — a real command or flag.- Tool names, types, and paths get described, not back-ticked.+ Tool names, types, and paths get described in prose.## Shape of a Doc