rushes 0.8.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/AGENTS.md +26 -26
  3. package/README.md +60 -56
  4. package/dist/cli/demo.js +20 -8
  5. package/dist/cli/main.js +1 -1
  6. package/dist/core/approval.js +15 -0
  7. package/dist/core/batches.js +5 -4
  8. package/dist/core/exportNotes.js +6 -4
  9. package/dist/core/logText.js +1 -1
  10. package/dist/core/noteState.js +46 -0
  11. package/dist/core/notes.js +20 -12
  12. package/dist/core/picks.js +79 -0
  13. package/dist/core/project.js +27 -2
  14. package/dist/core/schema.js +20 -2
  15. package/dist/core/script.js +6 -2
  16. package/dist/core/tabs.js +3 -2
  17. package/dist/core/takes.js +73 -0
  18. package/dist/mcp/tools.js +10 -8
  19. package/dist/server/app.js +92 -23
  20. package/dist/server/brief.js +5 -2
  21. package/dist/server/loudness.js +20 -45
  22. package/dist/server/storyboard.js +4 -1
  23. package/package.json +3 -3
  24. package/skills/rushes/SKILL.md +13 -13
  25. package/web-dist/assets/geist-cyrillic-400-normal-DXusLSnH.woff2 +0 -0
  26. package/web-dist/assets/geist-cyrillic-400-normal-DkrqoNl2.woff +0 -0
  27. package/web-dist/assets/geist-cyrillic-500-normal-BboVsk8R.woff +0 -0
  28. package/web-dist/assets/geist-cyrillic-500-normal-NWpm63d5.woff2 +0 -0
  29. package/web-dist/assets/geist-cyrillic-600-normal-BeW5VFD_.woff2 +0 -0
  30. package/web-dist/assets/geist-cyrillic-600-normal-CnEeIcMC.woff +0 -0
  31. package/web-dist/assets/geist-cyrillic-700-normal-BH7gZKkM.woff +0 -0
  32. package/web-dist/assets/geist-cyrillic-700-normal-BSHy2ewF.woff2 +0 -0
  33. package/web-dist/assets/geist-cyrillic-ext-400-normal-ChfpGzr5.woff +0 -0
  34. package/web-dist/assets/geist-cyrillic-ext-500-normal-BXrH8YSv.woff +0 -0
  35. package/web-dist/assets/geist-cyrillic-ext-600-normal-PR76dHFV.woff +0 -0
  36. package/web-dist/assets/geist-cyrillic-ext-700-normal-CBIC21Ex.woff +0 -0
  37. package/web-dist/assets/geist-latin-400-normal-B40WzpMT.woff2 +0 -0
  38. package/web-dist/assets/geist-latin-400-normal-akEymXtG.woff +0 -0
  39. package/web-dist/assets/geist-latin-500-normal-BDXIbFrL.woff +0 -0
  40. package/web-dist/assets/geist-latin-500-normal-CTWBw9NS.woff2 +0 -0
  41. package/web-dist/assets/geist-latin-600-normal-CSETrqM2.woff2 +0 -0
  42. package/web-dist/assets/geist-latin-600-normal-DsPlZH-9.woff +0 -0
  43. package/web-dist/assets/geist-latin-700-normal-Bod5GerT.woff +0 -0
  44. package/web-dist/assets/geist-latin-700-normal-CFi8mLqe.woff2 +0 -0
  45. package/web-dist/assets/geist-latin-ext-400-normal-Bz1pQMyt.woff +0 -0
  46. package/web-dist/assets/geist-latin-ext-400-normal-CND6cjiG.woff2 +0 -0
  47. package/web-dist/assets/geist-latin-ext-500-normal-BovoTgeE.woff2 +0 -0
  48. package/web-dist/assets/geist-latin-ext-500-normal-C9fx-R30.woff +0 -0
  49. package/web-dist/assets/geist-latin-ext-600-normal-CVFbg5dS.woff2 +0 -0
  50. package/web-dist/assets/geist-latin-ext-600-normal-TmIUreF9.woff +0 -0
  51. package/web-dist/assets/geist-latin-ext-700-normal-BnofTsEi.woff2 +0 -0
  52. package/web-dist/assets/geist-latin-ext-700-normal-DKAtFBEc.woff +0 -0
  53. package/web-dist/assets/geist-mono-cyrillic-400-normal-C51Di1Mf.woff2 +0 -0
  54. package/web-dist/assets/geist-mono-cyrillic-400-normal-CPJFfJgk.woff +0 -0
  55. package/web-dist/assets/geist-mono-cyrillic-500-normal-D2cXvDHF.woff2 +0 -0
  56. package/web-dist/assets/geist-mono-cyrillic-500-normal-DfuvdVgn.woff +0 -0
  57. package/web-dist/assets/geist-mono-latin-400-normal-B2yvC1Cq.woff +0 -0
  58. package/web-dist/assets/geist-mono-latin-400-normal-DTRLJnHl.woff2 +0 -0
  59. package/web-dist/assets/geist-mono-latin-500-normal-D-GG86Jb.woff +0 -0
  60. package/web-dist/assets/geist-mono-latin-500-normal-YINYabwD.woff2 +0 -0
  61. package/web-dist/assets/geist-mono-latin-ext-400-normal-CfzLURNc.woff +0 -0
  62. package/web-dist/assets/geist-mono-latin-ext-400-normal-DI-rJ0UV.woff2 +0 -0
  63. package/web-dist/assets/geist-mono-latin-ext-500-normal-Buglb9-a.woff2 +0 -0
  64. package/web-dist/assets/geist-mono-latin-ext-500-normal-CrWEgvU_.woff +0 -0
  65. package/web-dist/assets/geist-mono-symbols2-400-normal-DjbiTEEA.woff +0 -0
  66. package/web-dist/assets/geist-mono-symbols2-500-normal-CmnCPGa0.woff +0 -0
  67. package/web-dist/assets/geist-mono-vietnamese-400-normal-CZEPLOgu.woff +0 -0
  68. package/web-dist/assets/geist-mono-vietnamese-500-normal-Dx9-epDo.woff +0 -0
  69. package/web-dist/assets/geist-vietnamese-400-normal-C8xY9-dI.woff +0 -0
  70. package/web-dist/assets/geist-vietnamese-500-normal-_b1ojCbH.woff +0 -0
  71. package/web-dist/assets/geist-vietnamese-600-normal-B5MZcNo4.woff +0 -0
  72. package/web-dist/assets/geist-vietnamese-600-normal-BFUgqsz8.woff2 +0 -0
  73. package/web-dist/assets/geist-vietnamese-700-normal-Dm6ODIDG.woff +0 -0
  74. package/web-dist/assets/index-D-520-nU.js +67 -0
  75. package/web-dist/assets/index-DebHxWrg.css +1 -0
  76. package/web-dist/index.html +2 -2
  77. package/web-dist/assets/figtree-latin-400-normal-BD4aNku5.woff +0 -0
  78. package/web-dist/assets/figtree-latin-400-normal-g7Dtegnw.woff2 +0 -0
  79. package/web-dist/assets/figtree-latin-500-normal-BWnGEVsr.woff2 +0 -0
  80. package/web-dist/assets/figtree-latin-500-normal-B_yy1phn.woff +0 -0
  81. package/web-dist/assets/figtree-latin-600-normal-BM_oTo4n.woff +0 -0
  82. package/web-dist/assets/figtree-latin-600-normal-Cv_xCTDl.woff2 +0 -0
  83. package/web-dist/assets/figtree-latin-700-normal-BCCt2T1q.woff +0 -0
  84. package/web-dist/assets/figtree-latin-700-normal-th6qEP7c.woff2 +0 -0
  85. package/web-dist/assets/figtree-latin-ext-400-normal-CXAzuTZb.woff2 +0 -0
  86. package/web-dist/assets/figtree-latin-ext-400-normal-Gbh-3PTk.woff +0 -0
  87. package/web-dist/assets/figtree-latin-ext-500-normal-BOEJvrb_.woff +0 -0
  88. package/web-dist/assets/figtree-latin-ext-500-normal-Du0rIuHj.woff2 +0 -0
  89. package/web-dist/assets/figtree-latin-ext-600-normal-CQqsimlV.woff +0 -0
  90. package/web-dist/assets/figtree-latin-ext-600-normal-DJlfifZj.woff2 +0 -0
  91. package/web-dist/assets/figtree-latin-ext-700-normal-BoDi4KL2.woff +0 -0
  92. package/web-dist/assets/figtree-latin-ext-700-normal-CS4sQkGV.woff2 +0 -0
  93. package/web-dist/assets/index-B31CnCOm.js +0 -11
  94. package/web-dist/assets/index-jf-RHBPN.css +0 -1
  95. package/web-dist/assets/jetbrains-mono-cyrillic-400-normal-BEIGL1Tu.woff2 +0 -0
  96. package/web-dist/assets/jetbrains-mono-cyrillic-400-normal-ugxPyKxw.woff +0 -0
  97. package/web-dist/assets/jetbrains-mono-cyrillic-500-normal-DJqRU3vO.woff +0 -0
  98. package/web-dist/assets/jetbrains-mono-cyrillic-500-normal-DmUKJPL_.woff2 +0 -0
  99. package/web-dist/assets/jetbrains-mono-greek-400-normal-B9oWc5Lo.woff +0 -0
  100. package/web-dist/assets/jetbrains-mono-greek-400-normal-C190GLew.woff2 +0 -0
  101. package/web-dist/assets/jetbrains-mono-greek-500-normal-D7SFKleX.woff +0 -0
  102. package/web-dist/assets/jetbrains-mono-greek-500-normal-JpySY46c.woff2 +0 -0
  103. package/web-dist/assets/jetbrains-mono-latin-400-normal-6-qcROiO.woff +0 -0
  104. package/web-dist/assets/jetbrains-mono-latin-400-normal-V6pRDFza.woff2 +0 -0
  105. package/web-dist/assets/jetbrains-mono-latin-500-normal-BWZEU5yA.woff2 +0 -0
  106. package/web-dist/assets/jetbrains-mono-latin-500-normal-CJOVTJB7.woff +0 -0
  107. package/web-dist/assets/jetbrains-mono-latin-ext-400-normal-Bc8Ftmh3.woff2 +0 -0
  108. package/web-dist/assets/jetbrains-mono-latin-ext-400-normal-fXTG6kC5.woff +0 -0
  109. package/web-dist/assets/jetbrains-mono-latin-ext-500-normal-Cut-4mMH.woff2 +0 -0
  110. package/web-dist/assets/jetbrains-mono-latin-ext-500-normal-ckzbgY84.woff +0 -0
  111. package/web-dist/assets/jetbrains-mono-vietnamese-400-normal-CqNFfHCs.woff +0 -0
  112. package/web-dist/assets/jetbrains-mono-vietnamese-500-normal-DNRqzVM1.woff +0 -0
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "rushes",
3
3
  "description": "A local review desk for video made with AI agents: timecoded notes, script edits and audio picks your agent reads and acts on.",
4
- "version": "0.8.0",
4
+ "version": "0.9.0",
5
5
  "author": { "name": "Red Morley Hewitt" },
6
6
  "homepage": "https://github.com/iamredmh/rushes",
7
7
  "repository": "https://github.com/iamredmh/rushes",
package/AGENTS.md CHANGED
@@ -32,7 +32,7 @@ Save renders to `renders/`, voice reads to `audio/voiceover/`, music beds to `au
32
32
 
33
33
  ## The Assets library
34
34
 
35
- The **Assets** tab is a library of every project file, organised into folders: Screenshots, Cuts, Voiceover, Music, Sound effects, Scripts & docs, Images, Captions, Exports, Delivery, Edit files and, once a cut has one, Proxies. Proxies are listed and deleted from there; you never register or remove one yourself — see proxies, below.
35
+ The **Assets** workspace is a library of every project file, organised into folders: Screenshots, Cuts, Voiceover, Music, Sound effects, Scripts & docs, Images, Captions, Exports, Delivery, Edit files and, once a cut has one, Proxies. Proxies are listed and deleted from there; you never register or remove one yourself — see proxies, below.
36
36
 
37
37
  Some of it needs no registering. A `*.md`, `*.txt`, `*.pdf`, `*.srt` or `*.vtt` file directly in the project root, and anything saved directly into `exports/`, are found automatically.
38
38
 
@@ -53,8 +53,8 @@ When the user wants a new video ("start a new film", "make a launch video", "a n
53
53
 
54
54
  1. **Create the project** unless one exists: `npx -y rushes new <folder> --no-browser`, then `rushes_open` with `project: "<folder>"`. It makes the project, `renders/` and `audio/voiceover`, `audio/music` and `audio/sfx`, and a `brief.md` to fill in. It refuses a folder that is already a Rushes project and never overwrites a `brief.md` that is there. Always pass `--no-browser`: without it the command stays running as the server and never returns.
55
55
  2. **Interview, briefly.** Ask at most three questions, and only ones whose answer changes the film: length and formats, who it is for, tone. Give each a recommended answer with its trade-off ("30 seconds fits a feed; 60 leaves room for the demo"). Never send a list of ten.
56
- 3. **Write `brief.md`.** Its sections, in order, are Title, Purpose, Audience, Length and formats, Tone, Include and avoid, Built with, Open questions and References. Fill every one, keep the `Status: draft` line, and tell the user to open Planning › Brief in Rushes, change any row and press **Approve brief**. Rushes then sets `Status: approved` in the file itself. Never approve it yourself or change that line, and if they say it's approved in chat while the file still says `draft`, ask them to press Approve. When they press **Send to agent** on the Brief page, read `brief.md` again and keep their wording: your last version is shown as Current, so read the file before you rewrite it.
57
- 4. **Script.** Add it with `rushes_set_script`. The user edits and approves each section in Planning › Script. Read `rushes_get_script` and wait until every section is `approved`.
56
+ 3. **Write `brief.md`.** Its sections, in order, are Title, Purpose, Audience, Length and formats, Tone, Include and avoid, Built with, Open questions and References. Fill every one, keep the `Status: draft` line, and tell the user to open Plan › Brief in Rushes, change any section and press **Approve brief**. Rushes then sets `Status: approved` in the file itself. Never approve it yourself or change that line, and if they say it's approved in chat while the file still says `draft`, ask them to press Approve. When they press **Send** on the Brief page, read `brief.md` again and keep their wording: a section they changed shows "Edited by you" with your last version struck through beneath it, so read the file before you rewrite it.
57
+ 4. **Script.** Add it with `rushes_set_script`. The user edits and approves each section in Plan › Script. Read `rushes_get_script` and wait until every section is `approved`.
58
58
  5. **Storyboard.** Write `storyboard.md` in the project root: a `# Storyboard: <film>` title, then one section per shot, in this shape:
59
59
 
60
60
  ```markdown
@@ -68,10 +68,10 @@ When the user wants a new video ("start a new film", "make a launch video", "a n
68
68
  A folder of clips lands in the window from the right.
69
69
  ```
70
70
 
71
- `Length` is planned seconds (they become the cut's shot starts), `Still` is a project-relative picture (png, jpg, webp or gif), best saved under `storyboard/`, and `Direction` is the user's line. Make a still for each shot if your tools can; the Storyboard page shows any still the file names, registered or not. The user reads and approves each shot in Planning › Storyboard, and Rushes sets `Status: approved` itself: never set or change a shot's status yourself. When they press **Send to agent** there, read `storyboard.md` again, keep their wording, and update the still if what happens has changed.
71
+ `Length` is planned seconds (they become the cut's shot starts), `Still` is a project-relative picture (png, jpg, webp or gif), best saved under `storyboard/`, and `Direction` is the user's line. Make a still for each shot if your tools can; the Storyboard page shows any still the file names, registered or not. The user reads and approves each shot in Plan › Storyboard, and Rushes sets `Status: approved` itself: never set or change a shot's status yourself. When they press **Send** there, read `storyboard.md` again, keep their wording, and update the still if what happens has changed.
72
72
  6. **Build only when all three are approved** (`rushes_status` reports `build`: `ready`, and what it is `waitingOn`). If the user says "just build it", do. Build in whatever tool suits the film, and name each scene after its planned shot. Then register the cut with `rushes_add_version`: a film's first cut starts with the storyboard's shots by itself (each `start` the running total of the lengths before it), so call `rushes_set_shots` only when the real timings differ (a cut brought in with `rushes_scan` or `rushes_bring_in` does not: send its shots with `rushes_set_shots`). A film with no script has nothing to wait on there: the script is only waited on when the film has one. While the plan isn't all approved the reply carries `planWarning`: a nudge, not a refusal.
73
73
 
74
- The brief and the storyboard are Markdown files the user reads and approves on their own pages under Planning. Use the same file names so the next session finds them.
74
+ The brief and the storyboard are Markdown files the user reads and approves on their own pages under Plan. Use the same file names so the next session finds them.
75
75
 
76
76
  ## Picking up a film that's underway
77
77
 
@@ -79,7 +79,7 @@ When the user asks to open or review a film they started in the chat, or the pro
79
79
 
80
80
  1. **Open the project**, or create it where the work is: `npx -y rushes new <folder> --no-browser` (it never overwrites a `brief.md` and leaves every other file alone), then `rushes_open`.
81
81
  2. **Write `brief.md` from the conversation.** Fill each section from what the user actually said. Mark anything you had to infer with `(inferred)` so they can check it. Where the chat never touched a section, write `Not discussed yet.` rather than inventing something. Put ideas they floated but didn't settle, and anything you couldn't answer, under Open questions. Keep `Status: draft`, and never approve it yourself.
82
- 3. **Register what you already made.** A script from the chat goes in with `rushes_set_script` (the user approves it in Planning › Script). Copy storyboard stills into a `storyboard/` folder in the project: copy them, never move them, so the originals stay where the user's other tools expect them. Write the shots into `storyboard.md` in the shot format above, each with `Status: draft` and a `Still:` line naming its copy (the Storyboard page shows any still the file names). Register other reference images with `rushes_add_file` (`kind: "image"`). Renders, voice reads and music beds go in as usual (`rushes_add_version`, `rushes_add_variant`). Run `rushes_scan` for audio and cuts in the folder; it doesn't look for images, so naming the stills in `storyboard.md` (or registering other images) is yours to do: you know where you saved them.
82
+ 3. **Register what you already made.** A script from the chat goes in with `rushes_set_script` (the user approves it in Plan › Script). Copy storyboard stills into a `storyboard/` folder in the project: copy them, never move them, so the originals stay where the user's other tools expect them. Write the shots into `storyboard.md` in the shot format above, each with `Status: draft` and a `Still:` line naming its copy (the Storyboard page shows any still the file names). Register other reference images with `rushes_add_file` (`kind: "image"`). Renders, voice reads and music beds go in as usual (`rushes_add_version`, `rushes_add_variant`). Run `rushes_scan` for audio and cuts in the folder; it doesn't look for images, so naming the stills in `storyboard.md` (or registering other images) is yours to do: you know where you saved them.
83
83
  4. **Say what you filled in:** what came from the user's words, what you inferred, what you registered, and what you looked for and couldn't find ("I found four of the six stills"). Ask them to read `brief.md` under Assets › Scripts & docs.
84
84
  5. **If the chat is one you can't see** (another session, another tool), say so and ask the user to paste it or point you to it. Don't reconstruct a brief from memory of a conversation you didn't have.
85
85
 
@@ -91,13 +91,13 @@ No project to show yet? Run `npx -y rushes demo <folder> --no-browser`, then `ru
91
91
 
92
92
  ## Locked tabs and the prompts they copy
93
93
 
94
- Every tab is visible from the start, in workflow order, even before it has anything in it. Opening a locked tab explains what it's for and what unlocks it, and offers a **Copy prompt for your agent** button. When Rushes has found files for a locked Voiceover, Music or Sound effects tab in the project folder, the page adds a line under the prompt, such as "14 music files found in this project", with a **Review** button that opens Assets › Found filtered to that kind. So a user may open a locked tab, see files you haven't brought in, and ask you about them: call `rushes_scan` to list them, and `rushes_bring_in` for the ones that belong. If the user pastes you one of these, it's a direct, already-scoped request — act on it the same as any other instruction, e.g.:
94
+ Every tab is visible from the start, in workflow order, even before it has anything in it. Opening a locked tab explains what it's for and what unlocks it, and offers a **Copy prompt for your agent** button. When Rushes has found files for a locked Voice, Music or Effects tab in the project folder, the page adds a line under the prompt, such as "14 music files found in this project", with a **Review** button that opens Assets › Found filtered to that kind. So a user may open a locked tab, see files you haven't brought in, and ask you about them: call `rushes_scan` to list them, and `rushes_bring_in` for the ones that belong. If the user pastes you one of these, it's a direct, already-scoped request — act on it the same as any other instruction, e.g.:
95
95
 
96
96
  > In Rushes project "Launch", make two or three music beds for "Hero" and add each with rushes_add_variant (stage "music") with a one-line description.
97
97
 
98
98
  ## Visuals: stills and carousels
99
99
 
100
- When the user makes stills, standalone images or carousels (posts), register them so they can mark them up in the **Visuals** tab, the way they mark a cut in Picture. Call `rushes_add_visual` with one visual per post: a `name` and `pages`, each page with its pictures, one per aspect ratio it comes in (a png, jpg, webp or gif inside the project; Rushes reads each ratio from the picture's own size, so never name one). A still is a visual with one page; a carousel has many. Every page must come in the same ratios, and every page needs a picture in every aspect ratio.
100
+ When the user makes stills, standalone images or carousels (posts), register them so they can mark them up in the **Visuals** workspace, the way they mark a cut on the Timeline. Call `rushes_add_visual` with one visual per post: a `name` and `pages`, each page with its pictures, one per aspect ratio it comes in (a png, jpg, webp or gif inside the project; Rushes reads each ratio from the picture's own size, so never name one). A still is a visual with one page; a carousel has many. Every page must come in the same ratios, and every page needs a picture in every aspect ratio.
101
101
 
102
102
  The user drags to mark a region on the picture, clicks for a point, or adds a note for the whole image, and sends a batch. `rushes_get_batch` and `rushes_list_notes` return each Visuals note with a `visual` object: the visual's id and name, its `version`, the `page`, the `ratio` as a label (null when the note is for every ratio), the `shape` (`region`, `pin` or `image`), the `region` or `pin` as fractions of the picture, `words` saying where it is ("left third, top third"), and the `file` to open. A note with no ratio is for every ratio: say in your reply which ratios you fixed.
103
103
 
@@ -105,33 +105,33 @@ To answer feedback, change the marked pictures and register the result as a new
105
105
 
106
106
  ## Shelved films
107
107
 
108
- The user can shelve a film they have set aside (the **Film actions** menu in the dashboard). `rushes_status` returns `films`, each with `shelved`: the time it was shelved, or null. A shelved film is the user's decision: leave it alone, make no new cuts of it and fix none of its notes unless the user asks. Its open notes are not counted in the tabs or sent in batches, and `rushes_list_notes` leaves them out. A new cut of a shelved film brings it back (the reply has `restored: true`), so make one only when the user wants that film worked on again. You never shelve or restore a film: that is the user's to do.
108
+ The user can shelve a film they have set aside (**Shelve film** in the dashboard's **More** menu, or Shift+S). `rushes_status` returns `films`, each with `shelved`: the time it was shelved, or null. A shelved film is the user's decision: leave it alone, make no new cuts of it and fix none of its notes unless the user asks. Its open notes are not counted in the tabs or sent in batches, and `rushes_list_notes` leaves them out. A new cut of a shelved film brings it back (the reply has `restored: true`), so make one only when the user wants that film worked on again. You never shelve or restore a film: that is the user's to do.
109
109
 
110
110
  ## The loop
111
111
 
112
112
  1. **Register what you made.**
113
- - A render: `rushes_add_version` with `video` and `file`. Run it again for each new cut. Give every cut a short `label` (48 characters at most) that says what changed, e.g. `"launch 1.45x slower"`, and put the detail in `note`: the version list shows the label, and a longer one is refused. When the cut is likely to play badly in a browser (4K or larger, over 1.5 GB, or a codec such as ProRes), the reply carries `proxySuggested: true` and `proxyReason`; Picture then offers the user a proxy. Prefer H.264 MP4 to begin with and this won't come up.
113
+ - A render: `rushes_add_version` with `video` and `file`. Run it again for each new cut. Give every cut a short `label` (48 characters at most) that says what changed, e.g. `"launch 1.45x slower"`, and put the detail in `note`: the Cut menu's version list shows the label, and a longer one is refused. When the cut is likely to play badly in a browser (4K or larger, over 1.5 GB, or a codec such as ProRes), the reply carries `proxySuggested: true` and `proxyReason`; the Timeline tab then offers the user a proxy (**Create proxy**, under the player). Prefer H.264 MP4 to begin with and this won't come up.
114
114
  - Other shapes of the same cut (a 9:16, 1:1 or 4:5 of the 16:9: same edit, same length): register every shape you rendered, main one first. `rushes_add_version` with `file` (the main one) and `formats: [{ file }, …]` registers them all in one call; `rushes_add_format` (`file`, optional `video`, `version` and `label`) adds one to a cut already registered. Rushes measures each ratio with ffprobe; here `label` is only a ratio hint for an unusual shape such as 2.39:1 (not the cut's short label, which belongs to `rushes_add_version`). A second render with a ratio the cut already has is refused: a re-render is a new version. A shape more than 0.1 s off the cut's length is still registered, with a warning: `rushes_add_format` returns it as `warning`, and `rushes_add_version` returns a list as `formatWarnings` (there, `warning` means "Picture is locked").
115
115
  - A VO script: `rushes_set_script` with sections `{start, end, current}` in seconds. It merges by `id`: send only the sections you changed, with their ids, plus any new ones without an id. Sections you leave out are kept, with their takes. Pass `replace: true` only when you mean to replace the whole script. `rushes_get_script` reads the whole script back.
116
116
  - A voice read: `rushes_add_variant` with `stage: "voice"`, `video` (the film it is for) and `round` (the round's name, e.g. "Round 2 · Gerald, tone" — reads in one round are compared side by side; a new direction gets a new round, a small fix to a marked word can stay in the current one). Say in `description` what the read is, or what changed from the one it's based on. `rushes_add_take` stays in the file format and API for compatibility only; voiceover work doesn't use it.
117
- - Music beds or SFX passes: `rushes_add_variant` with `stage` `music` or `sfx`, and `video`. Give it `meta: {description: "..."}`, shown on its lane card in place of `bpm`/`key`; SFX passes also take `cues` (`{name, t, file?}`: `t` in seconds, and `file` the sample you placed there, an audio file, optional), labelled on the waveform. Give a sound the same name every time it comes back (`thud`, not `thud 2`): the Sound effects tab groups cues by name into layers, one per sound, and shows a cue's `file` on its card, where the user can play that sample on its own.
118
- - Every voice read, music bed and SFX pass belongs to one film or several: pass its `video` (an id or name, or a list of them when one bed is fitted to several films) to `rushes_add_variant`, and the Voiceover, Music, Sound effects and Mix tabs list it only on those films. In a project with more than one film, one without a `video` is on no film: it waits, folded, under "Not on this film" on each film's tab (with the ones on other films) until someone puts it on one. `rushes_set_films` (`lane`, `variant`, `videos`) moves an existing one; the user does the same from the **Films** button on its card. `rushes_bring_in` and `rushes_open` give the files they bring in the `film` you name (or, for the files they match to the newest cut, that cut's film).
117
+ - Music beds or SFX passes: `rushes_add_variant` with `stage` `music` or `sfx`, `video`, and `round` as for a voice read (each new batch of beds or passes is a round, e.g. "Round 2 · softer middle"). Give it `meta: {description: "..."}` (and `bpm`, `key` or `lufs` when you know them), shown in its details: the tooltip on its name in the tab's list of takes and the line its details button opens; SFX passes also take `cues` (`{name, t, file?}`: `t` in seconds, and `file` the sample you placed there, an audio file, optional), labelled on the waveform. Give a sound the same name every time it comes back (`thud`, not `thud 2`): the Effects tab groups cues by name into layers, one per sound, and shows a cue's `file` on its card, where the user can play that sample on its own.
118
+ - Every voice read, music bed and SFX pass belongs to one film or several: pass its `video` (an id or name, or a list of them when one bed is fitted to several films) to `rushes_add_variant`, and the Voice, Music and Effects tabs (and the Timeline) list it only on those films. In a project with more than one film, one without a `video` is on no film: it waits, folded, under "Not on this film" on each film's tab (with the ones on other films) until someone puts it on one. `rushes_set_films` (`lane`, `variant`, `videos`) moves an existing one; the user does the same from the **Films** button on its card. `rushes_bring_in` and `rushes_open` give the files they bring in the `film` you name (or, for the files they match to the newest cut, that cut's film).
119
119
  - The storyboard's shots, once you have the first cut: `rushes_set_shots` with `video`, optional `version` (defaults to the newest) and `shots` as `{start, name, tag?}`. Send new timings whenever a later cut moves them.
120
120
  2. **Open it for the user:** `rushes_open`. It also looks through the project folder and brings in the files that go with the cut (next section). Each project's dashboard lives at its own address, `/p/<id>/` — safe to run more than one project at once. A tab unlocks as soon as it has something in it.
121
- 3. **Wait for feedback.** The user presses **Send to agent**, which saves a batch and gives them a prompt to paste to you. Whichever tab they press it on, the batch holds every open note from every tab and every film in play, plus any changed script sections; its `stage` is the tab when everything came from one, or `null` when it spans tabs. Each note carries its own `stage` and `video`: fix each one on its own tab and film. Call `rushes_get_batch` to read the latest batch, its notes and any changed script sections. When the brief or the storyboard changed too, the prompt the user pastes ends with a line about each.
122
- 4. **Fix each note.** A note has `stage`, `scope` (`point`, `range` or `whole` — Voiceover only ever uses `point` or `whole`; it has no Range scope), `t`, `tOut`, `on` (the lane, variant, take, cue or section it's about), `text`, and optionally `box` (normalised 0 to 1), `grab` (a PNG path in `screenshots/`; older notes may point to `.rushes/grabs/`), `shot` (the shot it falls in, `{n, name}`, worked out by the server from the version's shots — not yours to set) and, on Picture, `format` (`null` when the note is for every format, or a format id such as `"9x16"` when it's for that shape only). When a note's `format` is not null, fix only that format and leave the others alone; an all-format note is for every shape, so fix each and say in `reply` which formats you fixed. `rushes_list_notes` takes `format` (an id such as `9x16`, or its label `9:16`: that format's Picture notes plus the all-format ones) and `onlyThisFormat: true` (only that format's). On an audio stage, `on` is `"<laneId>/<variantId>"` for a music bed, SFX pass or voice read (the lane and variant ids `rushes_add_variant` returns) — on Voiceover the lane id is the round's slugged name, so `on` names the round and the read together — or `"<laneId>/<variantId>:<cueId>"` for an SFX cue. On Mix it's `null` for the whole mix, `"vo"` for the VO lane (the newest round with a pick), or `"<laneId>/<variantId>"` for the music or SFX lane. Older notes may carry a bare variant id, `"vo"` on Voiceover itself, a section id, `"<sectionId>:<takeId>"` for a take, `"<variantId>:<cueId>"` or a bare cue id; Rushes still lists these with a sensible label, but none of them name a read any more. On Music, Sound effects and Mix, a note can also carry `marks` — short feedback like `Fall` (bring the level down over the range) or `Quieter 3 dB` (3 dB lower over the range). `rushes_list_notes`, `rushes_get_batch` and exported notes all show them. Marks are the user's, like a note's text and times — you read and act on them, you don't set them. Voiceover notes carry no marks: a note there is **Whole** (`Speaker`, `Pacing`, `Tone` or `Overall` — about the read as a whole) or **Point** (`Fix this` or `Keep this`, marked at the playhead).
121
+ 3. **Wait for feedback.** The user presses **Send**, at the foot of the notes panel, which saves a batch and gives them a prompt to paste to you. Wherever they press it, the batch holds every open note from every tab and every film in play, plus any changed script sections; its `stage` is the tab when everything came from one, or `null` when it spans tabs. Each note carries its own `stage` and `video`: fix each one on its own tab and film. Call `rushes_get_batch` to read the latest batch, its notes and any changed script sections. When the brief or the storyboard changed too, the prompt the user pastes ends with a line about each.
122
+ 4. **Fix each note.** A note has `stage`, `scope` (`point`, `range` or `whole` — on every tab, a voice read included: a voice range note is about that stretch of the read), `t`, `tOut`, `on` (the lane, variant, take, cue or section it's about), `text`, and optionally `box` (normalised 0 to 1), `grab` (a PNG path in `screenshots/`; older notes may point to `.rushes/grabs/`), `shot` (the shot it falls in, `{n, name}`, worked out by the server from the version's shots — not yours to set) and, on Picture, `format` (`null` when the note is for every format, or a format id such as `"9x16"` when it's for that shape only). When a note's `format` is not null, fix only that format and leave the others alone; an all-format note is for every shape, so fix each and say in `reply` which formats you fixed. `rushes_list_notes` takes `format` (an id such as `9x16`, or its label `9:16`: that format's Picture notes plus the all-format ones) and `onlyThisFormat: true` (only that format's). On an audio stage, `on` is `"<laneId>/<variantId>"` for a music bed, SFX pass or voice read (the lane and variant ids `rushes_add_variant` returns) — for a voice read the lane id is the round's slugged name, so `on` names the round and the read together — or `"<laneId>/<variantId>:<cueId>"` for an SFX cue. On a mix note (stage `mix`, made on the Timeline tab) it's `null` for the whole mix, `"vo"` for the voice (the newest round with a pick), or `"<laneId>/<variantId>"` for the music or the effects. Older notes may carry a bare variant id, `"vo"` on a voice note itself, a section id, `"<sectionId>:<takeId>"` for a take, `"<variantId>:<cueId>"` or a bare cue id; Rushes still lists these with a sensible label, but none of them name a read any more. A music, sfx or mix note can also carry `marks` — short feedback like `Fall` (bring the level down over the range) or `Quieter 3 dB` (3 dB lower over the range). `rushes_list_notes`, `rushes_get_batch` and exported notes all show them. Marks are the user's, like a note's text and times — you read and act on them, you don't set them. Voice notes carry no marks: a voice note is about the whole read (`scope: "whole"`), a point in it (`t`) or a range of it (`t` to `tOut`: replace or fix just that stretch), and its `text` says what to change. Older voice notes may begin with a word such as `Speaker`, `Pacing`, `Tone`, `Fix this` or `Keep this`, from quick-start buttons the dashboard no longer has.
123
123
  5. **Register the new cut** with `rushes_add_version`, with a short `label` and the detail in `note`. If the video is locked, the reply carries `warning: "Picture is locked at vN"`; the version is still added.
124
- 6. **Reply to every note** in one `rushes_reply` call. For each, set `status: "done"`, a one-line `reply`, `fixT` (when the fix is visible in the new cut, in seconds) and `fixVersion`. If you didn't fix a note, leave it `todo` and say why in `reply`.
125
- 7. **Audio batches.** On Voiceover, Music, Sound effects or Mix, call `rushes_get_picks` first (pass the note's film as `video`: picks and levels are per film), so you know which read or variant is in use before you fix anything. On Mix, it also returns `levels: { voice?, music?, sfx? }` in dB — where the user wants each lane to sit. Don't try to change these; they're set from the dashboard's sliders and only tell you the balance the user has already chosen. Then fix each note:
126
- - **Voiceover:** register a new whole read with `rushes_add_variant` (`stage: "voice"`) — a new round for a new direction (another voice, a different tone), or the current round for a small fix to a marked word. Say in `description` what changed.
127
- - **Music or Sound effects:** make the new bed or pass the text and marks ask for, and register it as in step 1.
124
+ 6. **Reply to every note** in one `rushes_reply` call. For each, set `status: "done"`, a one-line `reply`, `fixT` (when the fix is visible in the new cut, in seconds) and `fixVersion`. If you didn't fix a note, leave it `todo` and say why in `reply`. Every note comes back with its `state`: `todo` (the user's, not sent yet), `sent` (in a batch the user sent: yours, and shown to them as "With your agent") or `done`. `rushes_list_notes` with `state: "sent"` lists everything you have been given and not finished, whichever batch it came in. A done note the user opens again is `todo` and goes out in their next batch.
125
+ 7. **Audio batches.** For a note on the voice, the music, the effects or the mix (stage `mix` is the Timeline tab, where every take in use plays together), call `rushes_get_picks` first (pass the note's film as `video`: picks and levels are per film), so you know which read or variant is in use before you fix anything. It also returns `levels: { voice?, music?, sfx? }` in dB — where the user wants each sound to sit. Don't try to change these; they're set from the level on each sound's row of the Timeline tab and only tell you the balance the user has already chosen. Then fix each note:
126
+ - **Voice:** register a new whole read with `rushes_add_variant` (`stage: "voice"`) — a new round for a new direction (another voice, a different tone), or the current round for a small fix to a marked word. Say in `description` what changed.
127
+ - **Music or effects:** make the new bed or pass the text and marks ask for, and register it as in step 1.
128
128
 
129
- Then reply as in step 6. Mix plays the newest round's picked voice read; takes are never mixed.
130
- 8. **Script batches.** When a section's `proposed` differs from `current`, the user rewrote the line. Adopt it by calling `rushes_set_script` with just that section's `id`, `start`, `end` and the new `current`; the other sections stay as they are. The proposal then clears itself, and the section goes back to draft, as any section does when you change its line: a flag has been acted on, and the user approved the old words, not the new ones, so they approve again. If voiceover already exists, re-record the picked voice with the corrected script and register it with `rushes_add_variant` as a new read in a new round.
129
+ Then reply as in step 6. The mix plays one read, one bed and one effects pass per film: the one the user picked last (`use` in `rushes_get_picks`). A take you add is not in use, and is not heard, until they pick it. `rushes_get_picks` also lists every take per sound in `takes`, each with its `state`: `in-use`, `new` (arrived since the pick, waiting to be heard), `earlier` or `put-away` (the user set it aside: don't offer it again), plus `madeFor` and `stale` (made for a cut the film has replaced). Section takes are never mixed.
130
+ 8. **Script batches.** When a section's `proposed` differs from `current`, the user rewrote the line. Adopt it by calling `rushes_set_script` with just that section's `id`, `start`, `end` and the new `current`; the other sections stay as they are. The proposal then clears itself, and the section goes back to draft, as any section does when you change its line: a flag has been acted on, and the user approved the old words, not the new ones, so they approve again. The same holds on their side: when the user changes the words or direction of an approved line, brief section or shot, it goes back to draft, so `build.ready` in `rushes_status` is only true for words the user approved as they stand. If voiceover already exists, re-record the picked voice with the corrected script and register it with `rushes_add_variant` as a new read in a new round.
131
131
 
132
132
  ## Opening a project, and the files that go with the cut
133
133
 
134
- When asked to open or review work in Rushes, call `rushes_open`, then tell the user what it brought in and what it left. Rushes looks through the project folder itself, and only inside it: it never follows a link out and never reads a file's contents. It brings in the current set of files that go with the newest cut, unpicked, so Voiceover, Music and Sound effects have something to review, and leaves everything else one step away in Assets › Found. At most one file per kind comes in, and only when it clearly matches the cut by length, time and name. Nothing is ever picked; the user chooses in the dashboard.
134
+ When asked to open or review work in Rushes, call `rushes_open`, then tell the user what it brought in and what it left. Rushes looks through the project folder itself, and only inside it: it never follows a link out and never reads a file's contents. It brings in the current set of files that go with the newest cut, unpicked, so Voice, Music and Effects have something to review, and leaves everything else one step away in Assets › Found. At most one file per kind comes in, and only when it clearly matches the cut by length, time and name. Nothing is ever picked; the user chooses in the dashboard.
135
135
 
136
136
  `rushes_open` returns `broughtIn` (every file Rushes has brought in since it started, so it can include files from earlier calls and ones the user brought in by hand; each has its kind, lane, reasons and `origin`: `auto` for the scoring, `include` for yours, `hand` for the user's), `alreadyIn` (your `include` files that were already registered), `failed` (files that couldn't come in, with the reason) and `found` (counts of what it left, by kind; `rushes_scan` calls the same counts `counts`). It waits about 20 seconds for the folder to be looked through. On a big folder it answers with `scanning: true` and carries on in the background; call `rushes_scan` or `rushes_open` again later for the rest. Say it plainly, for example: "I brought in `vo_jules/read.wav` as a voice read and `bed/theme.wav` as music. 14 more files are in Assets › Found."
137
137
 
@@ -139,17 +139,17 @@ Pass `include` for files you made for this cut: `include: [{ path, kind?, round?
139
139
 
140
140
  `rushes_scan` (CLI `rushes scan [--film NAME] [--json]`) looks again, brings in the current set as opening does, and returns the candidates that are left, best score first, up to 200 (default 100), each with its reasons. `rushes_bring_in` (CLI `rushes bring-in <file>... [--kind K] [--round NAME] [--film NAME]`, which exits 1 if any file can't come in) brings chosen files in: voice, music and sfx as variants, video as cuts, `md`, `txt` and `pdf` as docs. It refuses any path outside the project folder, reports each file it can't bring in with the reason, and takes up to 60 files at a time and up to 12 files of each kind per call (the dashboard's **Bring in** has the same cap per click, so the tabs stay quick). Each refusal is `{ path, reason, code }`: match on `code` (`outside`, `gone`, `already`, `cap`, `link`, `folder`, `hiddenFile`, `skippedFolder`, `chooseKind`, `notAudio`, `notVideo`, `notDoc`, `unknownType`, or `other`), never on the words.
141
141
 
142
- The user sees the rest in **Assets › Found**, the first folder in Assets: files grouped by folder with their reasons, a play button to audition each one, **Bring in N** (the ticked files, up to 12 of each kind per click), **Not these** (hides them for good, with a **Hidden** list and **Restore**), **Look again** (the same scan as `rushes_scan`) and a header chip, "3 brought in · 118 more found", while something is new. Files in Found are never an agent's to pick for the user; whatever comes in, by you or by Rushes, is unpicked.
142
+ The user sees the rest in **Assets › Found**, the first folder in Assets: files grouped by folder with their reasons, a play button to audition each one, **Bring in N** (the ticked files, up to 12 of each kind per click), **Not these** (hides them for good, with a **Hidden** list and **Restore**), **Look again** (the same scan as `rushes_scan`) and, while something is new, a count on the Assets tab and a line such as "3 brought in · 118 more found" beside **Bring in new files** in the **More** menu. Files in Found are never an agent's to pick for the user; whatever comes in, by you or by Rushes, is unpicked.
143
143
 
144
144
  ## The Change Log
145
145
 
146
- Rushes keeps a log of what happened in the project, written as it happens (`.rushes/log.json`, oldest first on disk; every view of it is newest first): cuts, formats (another shape of a cut, e.g. "9:16 added to v2"), voice reads, music beds, sound-effects passes, takes, the script, picks, picture lock and unlock, notes sent, your replies, files added and bring-ins. A burst of registrations is one line. The user opens it from the **Change Log** button.
146
+ Rushes keeps a log of what happened in the project, written as it happens (`.rushes/log.json`, oldest first on disk; every view of it is newest first): cuts, formats (another shape of a cut, e.g. "9:16 added to v2"), voice reads, music beds, sound-effects passes, takes, the script, picks, picture lock and unlock, notes sent, your replies, files added and bring-ins. A burst of registrations is one line. The user reads it in the **Activity** tab of the notes panel.
147
147
 
148
148
  - **At the start of a session, call `rushes_get_log`** to catch up on what changed since you last worked on the project. It takes `limit` (default 30, at most 200), `area` and `since` (a date and time). It returns `entries` newest first, `earlier` (how many it left out), `undated` (audio from before the log) and `dropped` (lines removed past 5000).
149
149
  - **When you change direction or make a decision**, add one line with `rushes_log` (`text`, optional `area`, `video`, `version`, `ref`), e.g. "Slowed the zooms: the first cut felt rushed". One line per decision, not a running commentary, 160 characters at most. The log is exported and shared, so never copy a note's or reply's text into it. Don't log what Rushes logs itself.
150
150
  - **Give every cut a short `label`** (step 1 of the loop).
151
151
  - CLI: `rushes log [--limit N] [--area A] [--md]` and `rushes log add "text" [--area A]`. Flags go before the text; text that starts with a dash goes after `--`: `rushes log add --area mix -- "-3 dB on the bed"`. `rushes_export_notes` also writes `exports/change-log-<date>.md`.
152
- - Send to agent's prompt ends with the last five lines, under "Recent changes".
152
+ - The prompt Send gives ends with the last five lines, under "Recent changes".
153
153
 
154
154
  ## Tools
155
155
 
@@ -158,8 +158,8 @@ The MCP server has twenty-four tools: `rushes_open`, `rushes_status`, `rushes_ad
158
158
  ## Rules
159
159
 
160
160
  - Never edit `.rushes/*.json` by hand while the server is running. Use the tools, or the CLI (`rushes add`, `rushes notes`, `rushes reply`).
161
- - Picks — which variant is in use per lane, for each film on its own — are set from the dashboard only (**Use** / **Unpick**). No tool or CLI command sets one; read them with `rushes_get_picks`. Section take picks remain in the file format for compatibility only; nothing sets them any more.
162
- - A project whose voiceover exists only as takes from before rounds keeps Voiceover locked until a voice read exists, but open notes on those takes still count towards Send to agent and can be answered with `rushes_reply`.
161
+ - Picks — which read, bed and effects pass is in use, one of each, for each film on its own — are set from the dashboard only (**Use** / **Unpick**). No tool or CLI command sets one; read them with `rushes_get_picks`. Section take picks remain in the file format for compatibility only; nothing sets them any more.
162
+ - A project whose voiceover exists only as takes from before rounds keeps Voice locked until a voice read exists, but open notes on those takes still count towards Send and can be answered with `rushes_reply`.
163
163
  - You own a note's `reply`, `fixT` and `fixVersion`. The user owns its text, times and box. Either of you can set `status`.
164
164
  - After the first cut, send the storyboard's shots with `rushes_set_shots`; when a new cut moves them, send new timings.
165
165
  - Lock picture with `rushes_lock_picture` only when the user says picture is locked. Pass `version: null` to unlock.
package/README.md CHANGED
@@ -23,7 +23,7 @@
23
23
  <p align="center">
24
24
  <a href="#get-started">Get started</a> &nbsp;·&nbsp;
25
25
  <a href="#how-it-works">How it works</a> &nbsp;·&nbsp;
26
- <a href="#every-stage-in-one-place">The tabs</a> &nbsp;·&nbsp;
26
+ <a href="#every-stage-in-one-place">The desk</a> &nbsp;·&nbsp;
27
27
  <a href="#your-notes-are-plain-files">Plain files</a> &nbsp;·&nbsp;
28
28
  <a href="#faq">FAQ</a> &nbsp;·&nbsp;
29
29
  <a href="#for-agents-set-yourself-up">For agents</a>
@@ -59,7 +59,7 @@ It runs on your machine. There's no account, no API key and no server to sign up
59
59
 
60
60
  No project to hand? `npx -y rushes demo` builds an example on your machine and opens it.
61
61
 
62
- > Status: early. The Script, Picture, Voiceover, Music, Sound effects, Mix and Visuals tabs, the MCP tools and the CLI all work today.
62
+ > Status: early. The Plan, Review, Visuals and Assets workspaces, the MCP tools and the CLI all work today.
63
63
 
64
64
  ## How it works
65
65
 
@@ -67,78 +67,78 @@ No project to hand? `npx -y rushes demo` builds an example on your machine and o
67
67
  <img src="docs/assets/loop.png" alt="The loop in four steps. One, the agent registers a cut, a script or a mix. Two, you review it in the browser and pin notes. Three, you press Send to agent and your notes go as one batch. Four, the agent fixes each note and replies on it. The next version comes back to step two until picture is locked." width="880">
68
68
  </p>
69
69
 
70
- Your agent registers what it makes. You review it in the browser. When you press **Send to agent**, your notes go as one batch, saved as plain files in your project. The agent reads the batch, fixes each note and replies on it, and you see each reply arrive.
70
+ Your agent registers what it makes. You review it in the browser. When you press **Send**, at the foot of the notes panel, your notes go as one batch, saved as plain files in your project. The agent reads the batch, fixes each note and replies on it, and you see each reply arrive.
71
71
 
72
72
  ## Every stage in one place
73
73
 
74
- Six tabs, in the order the work happens; the first, Planning, is a menu that holds Brief and Script. A tab unlocks as soon as it has something in it, and a locked tab tells you what to ask your agent for.
74
+ Four workspaces in the top bar, in the order the work happens; the first, Plan, has a switch for Brief, Script and Storyboard. **Review** holds the cut on the **Timeline** tab and a tab for each sound: **Voice**, **Music** and **Effects**. Then come **Visuals** and **Assets**. A tab unlocks as soon as it has something in it, and a locked tab tells you what to ask your agent for. The notes panel sits on the right, with its **Notes** and **Activity** tabs and **Send** at its foot. On Visuals and Assets, which have no notes panel, the status bar at the bottom offers **Send** while anything is waiting.
75
75
 
76
- ### Picture: point at the exact frame
76
+ ### Timeline: point at the exact frame
77
77
 
78
- <img src="docs/assets/screens/picture-review.jpg" alt="The Picture tab on the first cut of a launch film, paused at 0:03.00. A dashed box is drawn round the word 'shot.' at the end of the headline. Four open notes are listed beside the video, two with frame grabs." width="880">
78
+ <img src="docs/assets/screens/picture-review.jpg" alt="The Review workspace's Timeline tab on cut v1 of the demo film, paused at 0:03.00 on a test pattern of colour bars. A dashed box is drawn round a checker block in the lower right of the frame. The notes panel on the right lists the open notes, with the boxed note selected; under the monitor, the ruler marks each note above the Picture track and a row each for Voice, Music and Effects." width="880">
79
79
 
80
80
  Pin a note to a moment, to a range, or to a box drawn on the frame. Grab a frame to show what you mean. Every note records the shot it falls in.
81
81
 
82
82
  ### The agent replies on every note
83
83
 
84
- <img src="docs/assets/screens/picture-fixed.jpg" alt="The Picture tab on version two of the film, paused at 0:14.40 on a count-up that now lands on '11 min'. In the notes, a green tick and the agent's reply sit under the note that asked for the change." width="880">
84
+ <img src="docs/assets/screens/picture-fixed.jpg" alt="The Timeline tab on cut v2, the hue pass of the same test pattern. In the notes panel the note about the checker block, carried over from v1 at 0:03.00, has a green tick and the agent's reply under it: v2 is a hue pass, and the block and the bars shift together now." width="880">
85
85
 
86
86
  When the agent delivers a new cut, each note shows where it landed in the new version and what the agent did about it. A green tick means it's done. Anything the agent didn't fix stays open, with a reason.
87
87
 
88
- ### Planning: the brief, then your edits beside the agent's lines
88
+ ### Plan: the brief, the script and the storyboard
89
89
 
90
- <img src="docs/assets/screens/script-review.jpg" alt="The Script tab. Each section shows the agent's current line on the left and the user's rewrite on the right. Two sections are outlined as changed, each with a short direction such as 'Two short sentences. Easier to say.'" width="880">
90
+ <img src="docs/assets/screens/script-review.jpg" alt="The Script page in the Plan workspace, with the Brief, Script and Storyboard switch above it. Each of the four lines sits in a field with its timing and a fit bar. The second line is marked Edited by you, with the agent's wording struck through beneath it and the direction 'Two short sentences. Easier to say.'; the third has a direction of its own. The foot reads 0 of 4 lines approved, 1 edited, and the status bar says Next: send 7 changes." width="880">
91
91
 
92
- Rewrite a line, add a direction, flag it or approve it. The bar on each row shows whether the line still fits its slot. When the agent adopts your edit, it records the next voice read from the corrected script.
92
+ Rewrite a line, add a direction, flag it or approve it. Every line sits in a field; once you change one, its row says **Edited by you**, with the agent's wording struck through beneath it and a button to go back to it, and the change goes with your next **Send**. The bar on each row shows whether the line still fits its slot. When the agent adopts your edit, it records the next voice read from the corrected script.
93
93
 
94
- Planning is one tab with a menu, so planning never crowds the review stages. **Brief** shows `brief.md` in your project folder: the agent's version of each section beside yours. Edit a row and Rushes writes it into the file; press **Approve brief** and it sets the file's status line. If your agent rewrites `brief.md`, the page follows without a reload. **Storyboard** works the same way over `storyboard.md`: a row per shot with its still (click it to enlarge), the agent's description beside yours, a direction line and a tick to approve it. When the brief, every script line (if the film has a script) and every shot are approved, the Planning tab shows a green check and its menu says **Ready to build**, with a prompt to copy. Rushes never stops your agent building before then: it only says what is still waiting.
94
+ Plan is one workspace, so planning never crowds the review. A switch at its top opens **Brief**, **Script** and **Storyboard**, each with a tick once it is approved and a dot while it has edits you haven't sent; key `1` comes back to the page you used last. **Brief** shows `brief.md` in your project folder, one field per section. Edit a section and Rushes writes it into the file; press **Approve brief** and it sets the file's status line. If your agent rewrites `brief.md`, the page follows without a reload. **Storyboard** works the same way over `storyboard.md`: a row per shot with its still (click it to enlarge), its description, a direction line and a tick to approve it. A line at the foot of each page counts what is approved and what you have edited. When the brief, every script line (if the film has a script) and every shot are approved, the Plan tab in the top bar shows a green check and the row above the page says **Ready to build**, with a prompt to copy. Rushes never stops your agent building before then: it only says what is still waiting.
95
95
 
96
- ### Voiceover: compare reads, round by round
96
+ ### Voice: compare reads, round by round
97
97
 
98
- <img src="docs/assets/screens/voiceover.jpg" alt="The Voiceover tab. The current round, 'George, slower', is picked and in use. The earlier round is open below it with two reads, George and Eliza, side by side. A note on the earlier round has the agent's reply: Round 2 is George at 93% pace." width="880">
98
+ <img src="docs/assets/screens/voiceover.jpg" alt="The Voice tab. Under the monitor, Round 2's read, Voice A slower, is In use, and Earlier lists Round 1's two reads, Voice A and Voice B, each with its waveform and description. In the notes panel, the note on Round 1's Voice A has a green tick and the agent's reply: Round 2 is Voice A at a slower pace." width="880">
99
99
 
100
- Reads of the same script sit side by side in rounds. Switch between them with no gap in playback, or turn on **Blind** to hide which is which. Leave a note on a whole read, or at a point in it.
100
+ Reads of the same script sit side by side in rounds. Switch between them with no gap in playback, or turn on **Blind** to hide which is which. Leave a note on a whole read, or at a point in it. Each sound's tab lists its takes as **New**, **In use**, **Earlier** and **Put away**; a take isn't on the timeline until you pick it.
101
101
 
102
102
  ### Music: audition the beds
103
103
 
104
- <img src="docs/assets/screens/music.jpg" alt="The Music tab with three beds, each with its waveform. Bed B is in use. Two open notes are marked on the waveforms: a 'Fall' on bed A and a 'Rise' on bed B." width="880">
104
+ <img src="docs/assets/screens/music.jpg" alt="The Music tab with two beds, each with its waveform: Warm pad is In use, Pulse is listed under Earlier. Two open notes are marked on the waveforms and listed in the notes panel: a point on Pulse at 0:02 and a 'Fall' range on Warm pad from 0:06 to 0:09." width="880">
105
105
 
106
106
  Switch beds instantly while the picture plays. Mark a range as **Rise**, **Fall**, **Louder** or **Quieter**, and your agent gets it as a note it can act on.
107
107
 
108
108
  ### Visuals: mark up stills and carousels
109
109
 
110
- The **Visuals** tab (key `7`) is for the stills, standalone images and carousels your agent makes next to a video. Each is a visual: one post, in the aspect ratios it comes in, shown one page at a time in a large frame. The tab scrolls from one visual to the next, and whichever visual crosses the middle of the view is the current one: it gets the outline, and it is the only one you can add a note to. A carousel has Previous and Next, a count, **Full screen** (for looking closely; you mark in the tab) and a strip of its pages with the open notes on each.
110
+ The **Visuals** workspace (key `7`) is for the stills, standalone images and carousels your agent makes next to a video. Each is a visual: one post, in the aspect ratios it comes in, shown one page at a time in a large frame. It scrolls from one visual to the next, and whichever visual crosses the middle of the view is the current one: it gets the outline, and it is the only one you can add a note to. A carousel has Previous and Next, a count, **Full screen** (for looking closely; you mark in the workspace) and a strip of its pages with the open notes on each.
111
111
 
112
- **Drag** on the picture to mark a region, click to drop a point, or press **Whole image** for a note about all of it. The composer always says where the note will go ("Adding to: Launch carousel · page 3 · 4:5 · v2"), and a draft stays with the visual you began it on. Notes belong to a page, a ratio and a version, never to where you have scrolled, so every mark is still there when you come back. The notes column lists the whole tab, grouped by visual and page, with the visual you are looking at highlighted and the rest faded; click a note to jump to it. When your agent registers a new version, your old notes stay with the version they were made on ("from v1"), marked until you tick them done.
112
+ **Drag** on the picture to mark a region, click to drop a point, or press **Whole image** for a note about all of it. The composer always says where the note will go ("Adding to: Launch carousel · page 3 · 4:5 · v2"), and a draft stays with the visual you began it on. Notes belong to a page, a ratio and a version, never to where you have scrolled, so every mark is still there when you come back. The notes column lists the whole workspace, grouped by visual and page, with the visual you are looking at highlighted and the rest faded; click a note to jump to it. When your agent registers a new version, your old notes stay with the version they were made on ("from v1"), marked until you tick them done.
113
113
 
114
114
  ### Shelve a film
115
115
 
116
- A film that went nowhere can be set aside without losing it. Open the **⋯** button beside the Change Log ("Film actions · Hero") and choose **Shelve film**, or press **Shift+S**. The film leaves the bar, a toast offers **Undo**, and its open notes stop counting: they leave the Send to agent count, the tab to-do counts, batches and Export notes, and they come back when you restore the film. Nothing is deleted: its cuts, notes, picks and files stay as they were.
116
+ A film that went nowhere can be set aside without losing it. Open the **More** menu (**⋯**, at the right of the top bar) and choose **Shelve film**, or press **Shift+S**. The film leaves the **Film** menu's films in play, a toast offers **Undo**, and its open notes stop counting: they leave the Send count, the tab to-do counts, batches and Export notes, and they come back when you restore the film. Nothing is deleted: its cuts, notes, picks and files stay as they were.
117
117
 
118
- Pills only switch films. When the films still in play do not fit the bar, the rest fold into a **+N** list (the film you are on is always shown). **Shelved (N)** at the end of the bar lists the shelved films: choose one to look at it, view-only, under a "Shelved" banner, and **Restore** it from the list or the banner. A new cut from your agent also brings a shelved film back. Your agent can see which films are shelved, but never shelves or restores one.
118
+ The **Film** menu in the top bar switches films, each listed with its open notes. **Shelved (N)** at its foot lists the shelved films: choose one to look at it, view-only, under a "Shelved" banner, and **Restore** it from the menu or the banner. A new cut from your agent also brings a shelved film back. Your agent can see which films are shelved, but never shelves or restores one.
119
119
 
120
- ### Sound effects: layers by sound
120
+ ### Effects: layers by sound
121
121
 
122
- <img src="docs/assets/screens/sound-effects.jpg" alt="The Sound effects tab with one pass open into its layers. There is one row per sound (tick, thud, blip, chime, whoosh, counter, thump, snap), each with a count and a mark wherever it plays." width="880">
122
+ <img src="docs/assets/screens/sound-effects.jpg" alt="The Effects tab with the pass in use, Pass A, open into its layers: one row per sound (Whoosh 1, Whoosh 2 and Whoosh 3), each with a count and a mark where it plays, under the pass's waveform with its three cues labelled." width="880">
123
123
 
124
124
  Every cue is labelled on the waveform. Open the pass into **layers by sound**: one row per sound, with a count, and a tick wherever it plays. Click a layer's file to hear that sample on its own.
125
125
 
126
- ### Mix: everything together
126
+ ### Everything together on the Timeline
127
127
 
128
- <img src="docs/assets/screens/mix.jpg" alt="The Mix tab. Voiceover, music and sound effects each have a lane with mute and solo buttons and a level slider. Below them, integrated loudness, true peak and the level of the music under the voice are shown. A note asks for the music to be 2 dB quieter through the middle." width="880">
128
+ <img src="docs/assets/screens/timeline-sound.jpg" alt="The Timeline tab with a take in use for each sound: rows for Voice, Music and Effects under the Picture track, each with its take's waveform, mute (M) and solo (S) buttons and a level, the music at -12 dB. The transport above them reads the loudness of what you hear: -18.8 LUFS, the true peak in dBTP and the music 6 dB under the voice." width="880">
129
129
 
130
- Voiceover, music and effects play together against the picture. Set each lane's level, mute or solo it, and read the loudness and true peak (with ffmpeg installed).
130
+ There is no separate mix: the takes in use play together against the picture on the **Timeline** tab. Each sound has its own row there with mute (**M**), solo (**S**) and a level, and the tab reads the loudness and true peak (with ffmpeg installed).
131
131
 
132
- ### The Change Log
132
+ ### Activity: the Change Log
133
133
 
134
- <img src="docs/assets/screens/change-log.jpg" alt="The Change Log drawer open over the Picture tab. It lists, newest first, the picks, the sound effects pass, the music beds, the picture lock, the agent's replies to five notes, the voiceover reads and the script, each marked as by the agent or by you." width="880">
134
+ <img src="docs/assets/screens/activity.jpg" alt="The notes panel's Activity tab beside the Timeline: an 'Add a line to the log' box, filters by area (All, Picture, Voice, Music, Effects, Mix, Visuals, Notes, Files), and today's entries newest first: the agent's replies to two notes, the picks for the film, and the two cuts added, each marked as by the agent or by Rushes, with Export as Markdown at the foot." width="880">
135
135
 
136
- Rushes keeps a running log of what happened: each cut, read, bed and pass as it arrives, notes sent, and the agent's replies. Export it as Markdown for whoever needs to catch up.
136
+ Rushes keeps a running log of what happened, in the **Activity** tab of the notes panel: each cut, read, bed and pass as it arrives, notes sent, and the agent's replies. Export it as Markdown for whoever needs to catch up.
137
137
 
138
138
  ## Why Rushes
139
139
 
140
140
  - **Notes your agent can act on.** Each one carries its stage, a timecode or range, an optional box on the frame, a frame grab, and the shot it falls in.
141
- - **Everything in one batch.** **Send to agent** sends every open note from every tab and every film, whichever tab you press it on, so nothing waits behind.
141
+ - **Everything in one batch.** **Send** sends every open note from every tab and every film, wherever you press it, so nothing waits behind.
142
142
  - **Versions keep their history.** Notes follow the work from cut to cut, and you can lock picture when it's done.
143
143
  - **Local, with no sign-up.** No account, no API key, nothing uploaded. It runs on your machine.
144
144
  - **Works with the agent you already use.** One MCP server for Claude Code, Codex, Cursor, Claude Desktop and Gemini CLI, a plugin and skill for Claude Code, and a command line for anything else.
@@ -160,7 +160,7 @@ Rushes keeps your review in a `.rushes/` folder in the project. The agent reads
160
160
 
161
161
  **Can I use it without an agent?** Yes. Review, leave notes, and run **Export notes** for a dated Markdown file you can send to a person. The agent loop is where it pays off most.
162
162
 
163
- **Does it need ffmpeg?** No, but it helps. With ffmpeg installed Rushes reads frame rates and durations, makes browser-playable proxies of heavy cuts, and measures loudness on Mix. Run `rushes doctor` to check.
163
+ **Does it need ffmpeg?** No, but it helps. With ffmpeg installed Rushes reads frame rates and durations, makes browser-playable proxies of heavy cuts, and measures loudness on the Timeline tab. Run `rushes doctor` to check.
164
164
 
165
165
  **Can it handle big files?** Cuts that play badly in a browser (4K and above, huge files, ProRes and similar) get an offer of a light 1080p proxy. Your original is never changed. See [Proxies](#proxies).
166
166
 
@@ -184,7 +184,7 @@ If your user asked you to use Rushes, do this:
184
184
 
185
185
  It prints one line per harness. Existing config is kept and a `.rushes.bak` backup is written first. Run it with `--dry-run` first if you want to show the user the changes before making them. A machine already set up through the GitHub form is recognised as Rushes too — setup switches it to the npm launch instead of adding a second registration.
186
186
  2. If it added anything, tell the user to restart the app (or start a new session) so the `rushes_*` tools load.
187
- 3. From then on, follow [AGENTS.md](AGENTS.md). If the user wants a new film, start with **Starting a film** in AGENTS.md: plan it with them first, then build. Otherwise, in short: register what you made, call `rushes_open`, wait for the user to press **Send to agent**, then `rushes_get_batch`, fix the notes, and `rushes_reply`.
187
+ 3. From then on, follow [AGENTS.md](AGENTS.md). If the user wants a new film, start with **Starting a film** in AGENTS.md: plan it with them first, then build. Otherwise, in short: register what you made, call `rushes_open`, wait for the user to press **Send**, then `rushes_get_batch`, fix the notes, and `rushes_reply`.
188
188
 
189
189
  The MCP server has twenty-four tools: `rushes_open`, `rushes_status`, `rushes_add_version`, `rushes_add_format`, `rushes_add_visual`, `rushes_add_variant`, `rushes_set_films`, `rushes_set_script`, `rushes_get_script`, `rushes_add_take`, `rushes_list_notes`, `rushes_list_assets`, `rushes_get_batch`, `rushes_reply`, `rushes_get_picks`, `rushes_set_shots`, `rushes_lock_picture`, `rushes_add_file`, `rushes_export_notes`, `rushes_log`, `rushes_get_log`, `rushes_scan`, `rushes_bring_in` and `rushes_doctor`.
190
190
 
@@ -237,7 +237,7 @@ No project to hand? Build one:
237
237
  npx -y rushes demo # creates ./rushes-demo and opens it
238
238
  ```
239
239
 
240
- It generates a complete example on your machine — a 30 s test film in two cuts, a short script, voice reads in two rounds, two music beds, an SFX pass, and example notes on Picture, Voiceover, Music and Mix — so every tab has something in it from the start. Nothing is downloaded and nothing ships with Rushes; it's all made locally with ffmpeg and, where available, your system's text-to-speech. It needs ffmpeg — without it, `demo` says so and points you at `rushes doctor`. It refuses to write into a folder that isn't empty. Pass a folder name to put it somewhere else, and `--no-browser` to skip opening it.
240
+ It generates a complete example on your machine — a 30 s test film in two cuts, a short script, voice reads in two rounds, two music beds, an SFX pass, and example notes on the cut, the voice reads, the music and the mix — so every tab has something in it from the start. Nothing is downloaded and nothing ships with Rushes; it's all made locally with ffmpeg and, where available, your system's text-to-speech. It needs ffmpeg — without it, `demo` says so and points you at `rushes doctor`. It refuses to write into a folder that isn't empty. Pass a folder name to put it somewhere else, and `--no-browser` to skip opening it.
241
241
 
242
242
  ### Health check: `rushes doctor`
243
243
 
@@ -250,7 +250,7 @@ Each check prints ✓ or ✗ with a plain fix, e.g. `✗ Claude Code — the Rus
250
250
 
251
251
  ## Shortcuts
252
252
 
253
- In the Picture tab:
253
+ On the Timeline tab:
254
254
 
255
255
  - **Space** play or pause
256
256
  - **←/→** step one frame (Shift: ten)
@@ -258,8 +258,10 @@ In the Picture tab:
258
258
  - **B** draw a box
259
259
  - **G** grab a frame
260
260
  - **N** new note
261
+ - **V** the select tool
262
+ - **F** full screen
261
263
 
262
- In the Voiceover, Music, Sound effects and Mix tabs:
264
+ On the Voice, Music and Effects tabs:
263
265
 
264
266
  - **Space** play or pause
265
267
  - **←/→** step one frame (Shift: ten)
@@ -269,10 +271,11 @@ In the Voiceover, Music, Sound effects and Mix tabs:
269
271
 
270
272
  Anywhere:
271
273
 
272
- - **1–8** switch tab (1: Planning, which opens the page you used last; 7: Visuals; 8: Assets)
274
+ - **1–8** switch place (1: Plan, which opens the page you used last; 2 and 6: Timeline; 3, 4, 5: Voice, Music, Effects; 7: Visuals; 8: Assets)
275
+ - **\\** hide or show the notes panel
273
276
  - **[ / ]** previous/next film in play
274
277
  - **Shift+S** shelve the current film, or restore it if it is shelved
275
- - **Alt+←/→** previous/next format (Picture)
278
+ - **Alt+←/→** previous/next format (Timeline)
276
279
  - **?** shortcuts
277
280
  - **Esc** close
278
281
 
@@ -282,13 +285,13 @@ Every tab is visible from the start, in workflow order, even before there's anyt
282
285
 
283
286
  > In Rushes project "Launch", make two or three music beds for "Hero" and add each with rushes_add_variant (stage "music") with a one-line description.
284
287
 
285
- When the project's folder already holds files for a locked Voiceover, Music or Sound effects tab, its page also says how many were found and offers a **Review** button, such as "14 music files found in this project". See **Finding your other files**, below.
288
+ When the project's folder already holds files for a locked Voice, Music or Effects tab, its page also says how many were found and offers a **Review** button, such as "14 music files found in this project". See **Finding your other files**, below.
286
289
 
287
- Hovering a locked tab shows a short tooltip, e.g. "Locked: ask your agent for music beds". The Assets tab follows the same rule.
290
+ Hovering a locked tab shows a short tooltip, e.g. "Locked: ask your agent for music beds". The Assets workspace follows the same rule.
288
291
 
289
292
  ## The Change Log
290
293
 
291
- The **Change Log** button in the header opens a log of what happened, newest first and grouped by day:
294
+ The **Activity** tab of the notes panel (what was the Change Log button) is a log of what happened, newest first and grouped by day:
292
295
 
293
296
  - each cut, format (another shape of a cut: "9:16 added to v2"), voice read, music bed, sound-effects pass and take as it arrives;
294
297
  - the script, picks and notes sent;
@@ -300,9 +303,9 @@ Rushes writes it itself, one short line per event, and a burst of registrations
300
303
  - filter by tab;
301
304
  - click a line to open that cut or variant.
302
305
 
303
- A dot on the button means new lines since you last looked. **Export as Markdown** writes `exports/change-log-<date>.md`; **Export notes** on the Exports tab writes it too, beside the notes. A project made before the log existed starts it from the dates it already has (cuts, notes sent and files); its older audio is listed undated, under "Before the log".
306
+ A dot on the Activity tab means new lines since you last looked. **Export as Markdown** writes `exports/change-log-<date>.md`; **Export notes** (in the More menu, or in Assets › Exports) writes it too, beside the notes. A project made before the log existed starts it from the dates it already has (cuts, notes sent and files); its older audio is listed undated, under "Before the log".
304
307
 
305
- Picture's version list shows each cut's short label (the agent's, or one taken from its note) and how long ago it arrived, with its full note beside the list and under the picture.
308
+ The Cut menu's version list shows each cut's short label (the agent's, or one taken from its note) and how long ago it arrived, with its full note beside the list.
306
309
 
307
310
  Agents read and write the same log with `rushes_get_log` and `rushes_log`, or from the command line:
308
311
 
@@ -322,7 +325,7 @@ An agent only shows what it registers, but the work that goes with a cut usually
322
325
  - **Where.** Only inside the project folder, up to eight folders deep. It never follows a symlink out of it, never reads a file's contents, and skips hidden folders, `node_modules` and Rushes' own `.rushes`, `proxies`, `screenshots` and `exports`. It examines up to 5,000 files. The dashboard never waits for it: a big folder shows "Looking through the folder…" and fills in as it goes.
323
326
  - **What each file probably is.** The nearest folder or file-name word decides: `vo`, `voice`, `narration` for voiceover; `bed`, `music`, `score` for music; `sfx`, `foley`, `whoosh` for sound effects. Audio with no such word is "Other audio", and you choose its kind. Video files other than the registered cut are offered as other cuts.
324
327
  - **The current set.** Each audio file is scored against the cut: a similar length, being made around the same time, and sharing a word or version (such as `v20`) with its name. For each kind, the best file comes in on its own only when it clearly beats the rest. That's at most one voice read, one music bed and one sound effects pass, and nothing else. Nothing is ever picked: files come in unpicked, and you choose in the dashboard. Each one carries its reasons, in plain words.
325
- - **Assets › Found.** Everything else stays one step away, in the **Found** folder at the top of Assets. Files are grouped by folder, with their length, size and reasons, and you can play one before you bring it in. A chip in the header ("3 brought in · 118 more found") opens it while there's something new to look at.
328
+ - **Assets › Found.** Everything else stays one step away, in the **Found** folder at the top of Assets. Files are grouped by folder, with their length, size and reasons, and you can play one before you bring it in. The Assets tab in the top bar carries the count of files found until you've looked, and **Bring in new files** in the More menu opens it.
326
329
  - **Bring in** registers the ticked files: voiceover, music and sound effects as variants, and video as cuts. It takes up to 12 files of each kind at a time, so the tabs stay quick; each voiceover folder becomes its own round.
327
330
  - **Not these** hides the ticked files for good. A **Hidden** list brings them back with **Restore**.
328
331
  - **Look again** runs the scan once more, and a filter box and kind buttons narrow the list.
@@ -365,39 +368,40 @@ Rushes creates `screenshots/` itself on the first grab. It never creates the oth
365
368
 
366
369
  ## Packs, picture lock and shots
367
370
 
368
- A project with more than one film gets numbered pills in the header — `[`/`]` switch between them, and each film remembers its own version and playhead. The header reads **Picture vN**, with a lock button beside it: lock a film at a cut and the dashboard opens on that cut until you unlock it. A version can carry a shot list from the storyboard, shown as a strip under the timeline, and every Picture note records the shot it falls in.
371
+ A project with more than one film gets a **Film** menu in the top bar — `[`/`]` switch between the films in play, and each film remembers its own version and playhead. The **Cut** menu beside it lists the film's cuts, with **Lock picture** at its foot: lock a film at a cut and the dashboard opens on that cut until you unlock it. A version can carry a shot list from the storyboard, shown on the timeline's picture row, and every note on the cut records the shot it falls in.
369
372
 
370
373
  ## Formats
371
374
 
372
- A piece often ships in several shapes — 9:16, 4:5, 1:1, 16:9 — the same edit reframed. Your agent registers each shape with `rushes_add_format` (or all of them at once with `rushes_add_version`'s `formats`, or `rushes add format <file>` from the command line); Rushes measures each ratio itself. Picture then shows a toggle beside the version, always in the same order (9:16, 4:5, 1:1, 4:3, 16:9), with a count of open notes on each. Switching keeps your place and whether it's playing. **Alt+←/→** steps through them.
375
+ A piece often ships in several shapes — 9:16, 4:5, 1:1, 16:9 — the same edit reframed. Your agent registers each shape with `rushes_add_format` (or all of them at once with `rushes_add_version`'s `formats`, or `rushes add format <file>` from the command line); Rushes measures each ratio itself. The monitor then shows a switch, always in the same order (9:16, 4:5, 1:1, 4:3, 16:9), with a count of open notes on each. Switching keeps your place and whether it's playing. **Alt+←/→** steps through them.
373
376
 
374
377
  A new note belongs to the format on screen: the switch above the note box reads **This format** | **All formats**, and you can change it on the note afterwards. A note for one format shows only there; notes for the other formats wait in a quiet **Other formats** row at the foot of the list. A drawn box always stays on the format it was drawn on. With one format there's no switch, and nothing changes. Assets › Cuts lists each format under its cut, and a frame grab is named with its ratio, such as `hero_v1_9x16_00m01.00s_f30.png`.
375
378
 
376
379
  A format's file can sit outside the project folder, like any registered cut, and plays by the same rules. A second render of a shape the cut already has is refused: a re-render is a new version.
377
380
 
378
- The format keys never fire while you're typing a note. In a text field, Alt+←/→ keeps its usual meaning: on macOS it jumps a word, and on Windows and Linux the browser may take it as Back, so click outside the note box first (or use the toggle) to switch format.
381
+ The format keys never fire while you're typing a note. In a text field, Alt+←/→ keeps its usual meaning: on macOS it jumps a word, and on Windows and Linux the browser may take it as Back, so click outside the note box first (or use the switch on the monitor) to switch format.
379
382
 
380
383
  ## Proxies
381
384
 
382
385
  Some cuts play badly in a browser: 4K or larger, over 1.5 GB, a codec browsers can't play reliably (ProRes, DNx, HEVC 10-bit — anything that isn't H.264, VP9 or AV1), or one that threw a playback error. Rushes checks with ffprobe as the cut is added, and if it's likely to struggle, a bar appears under the player saying why in a few words, with a **Create proxy** button. It makes a lightweight 1080p H.264 copy on your drive — your original file is never changed — with visible progress and **Cancel**. Notes, timecodes and frame numbers are identical on the proxy and the original.
383
386
 
384
- Once it's ready, a **Proxy / Original** switch appears on the player (defaults to Proxy, remembered per film). **Grab Frame** always takes the still from the original at full quality, whichever one you're watching. Tick "Create proxies for new cuts like this automatically" (off by default, saved per project) to skip the offer next time. The **Assets** tab has a **Proxies** folder listing each one with its size and a **Delete proxy** button; deleting removes only the proxy file, never the original.
387
+ Once it's ready, a **Proxy / Original** switch appears on the player (defaults to Proxy, remembered per film). **Grab this frame** (**G**) always takes the still from the original at full quality, whichever one you're watching. Turn on **Make lighter copies of new cuts automatically** in the More menu (off by default, saved per project) to skip the offer next time. The **Assets** tab has a **Proxies** folder listing each one with its size and a **Delete proxy** button; deleting removes only the proxy file, never the original.
385
388
 
386
389
  Without ffmpeg, no proxy is ever offered.
387
390
 
388
391
  ## Audio review
389
392
 
390
- The Voiceover, Music, Sound effects and Mix tabs share one audio engine, so switching what you hear is instant and never restarts playback or knocks picture out of sync.
393
+ On the Timeline, Voice, Music and Effects tabs, switching what you hear is instant and never restarts playback or knocks picture out of sync.
391
394
 
392
- Voiceover works in rounds: the same script read by a few voices, then variations of whichever one you pick. The current round is open; earlier rounds fold into one row each, and clicking a row opens it so its reads play too.
395
+ Voice works in rounds: the same script read by a few voices, then variations of whichever one you pick. Each sound's tab lists its takes in four groups: **New** (on Voice, a heading per round), **In use**, **Earlier** and **Put away**.
393
396
 
394
- - **Use** picks a music bed, SFX pass or voice read — shown as **In use**. Clicking a lane auditions it without changing the pick. An **Unpick** button beside In use clears the pick. On Music and Sound effects the first bed or pass is auditioned; on Mix the lane is empty; on Voiceover, with nothing clicked, the current round's pick plays, or else its first read.
395
- - **Blind** (Music and Voiceover) renames the beds `Bed 1`, `Bed 2`… — on Voiceover, each round's reads `Read 1`, `Read 2`… — in a shuffled order and masks their descriptions, so you can compare without knowing which is which.
396
- - On Voiceover, a note is **Whole** (`Speaker`, `Pacing`, `Tone` or `Overall` — the read as a whole) or **Point** (`Fix this` or `Keep this`, marked at the playhead). There's no Range scope and no Rise/Fall/Louder/Quieter marks there.
397
- - On Music, Sound effects and Mix, a note can carry marks: toggle **Rise**, **Fall**, **Louder** or **Quieter** (with a dB amount, 3 by default) to say how a range should change — "Fall" or "Quieter 3 dB".
398
- - **Mix** shows a loudness readout — integrated LUFS, true peak, and the music's level under the VO — measured over exactly what Mix plays, using the newest round's picked voice read. It needs **ffmpeg** on your PATH; without it, the readout shows "—". After a timeout or an error, click the readout to measure again.
399
- - Each **Mix** lane (Voiceover, Music, Sound effects) has a level slider, −24 dB to +6 dB in 0.5 dB steps, shown as e.g. `−14.0 dB`. Double-click resets it to 0; arrow keys move it 0.5 dB at a time. Levels are saved with your picks, never change a file, and the loudness readout is measured with them applied.
400
- - On **Sound effects**, rest the pointer on a cue's label or tick (or Tab to it) for a card with its full name, its time, where it falls in the pass (`cue 5 of 80`) and, when your agent sent one, its source file. The arrow beside a pass's name opens its **layers by sound**: one row per sound, in the order it first comes in, with a count (`thud ×19`) and a tick everywhere it plays. Click a tick to move the playhead there; click a layer's file name to hear that sample on its own (it stops the tab, and Play stops it). The layers stay open while you work, until you reload. Mix's Sound effects lane has the card too.
397
+ - The circle beside a take (**Use this one**) picks a music bed, SFX pass or voice read, which then shows as **In use** and plays on the Timeline tab. Clicking a take's block auditions it without changing the pick. **Unpick** on the take in use clears the pick, and **Put away** moves a take you don't want out of the list's way (**Bring back** returns it).
398
+ - **Blind** (Voice and Music) renames the beds `Bed 1`, `Bed 2`… — on Voice, each round's reads `Read 1`, `Read 2`… — in a shuffled order and masks their descriptions, so you can compare without knowing which is which.
399
+ - On Voice, a note is on the whole read, a point (marked at the playhead) or a **range** of the read (I and O), to have a stretch replaced. There are no Rise/Fall/Louder/Quieter marks there. Say what you want in the note itself: there are no preset prompts.
400
+ - On the Timeline tab a note is on the film (this frame, or the whole mix), never on one sound's take: to note a take, open its sound's tab.
401
+ - On a range of a music bed or an effects pass, a note can carry marks: toggle **Rise**, **Fall**, **Louder** or **Quieter** (with a dB amount, 3 by default) to say how a range should change — "Fall" or "Quieter 3 dB".
402
+ - The **Timeline** tab shows a loudness readout — integrated LUFS, true peak, and the music's level under the VO — measured over exactly what the timeline plays, using the newest round's picked voice read. It needs **ffmpeg** on your PATH; without it, the readout shows "—". After a timeout or an error, click the readout to measure again.
403
+ - Each sound's row on the Timeline tab (Voice, Music, Effects) has mute (**M**), solo (**S**) and a level slider, −24 dB to +6 dB in 0.5 dB steps, shown as e.g. `−14.0 dB`. Double-click resets it to 0; arrow keys move it 0.5 dB at a time. Levels are saved with your picks, never change a file, and the loudness readout is measured with them applied.
404
+ - On **Effects**, rest the pointer on a cue's label or tick (or Tab to it) for a card with its full name, its time, where it falls in the pass (`cue 5 of 80`) and, when your agent sent one, its source file. The arrow beside a pass's name opens its **layers by sound**: one row per sound, in the order it first comes in, with a count (`thud ×19`) and a tick everywhere it plays. Click a tick to move the playhead there; click a layer's file name to hear that sample on its own (it stops the tab, and Play stops it). The layers stay open while you work, until you reload. The Effects row on the Timeline tab has the card too.
401
405
 
402
406
  ## What gets saved
403
407
 
@@ -406,9 +410,9 @@ your-project/.rushes/
406
410
  project.json videos, versions, audio lanes and variants
407
411
  script.json VO sections: the agent's line, your version, direction, takes
408
412
  notes.json every note, with the agent's replies
409
- picks.json which variant or take is in use, and each Mix lane's level
413
+ picks.json which variant or take is in use, and each sound's level
410
414
  batches.json what you sent to the agent
411
- log.json the Change Log: what happened, one line each
415
+ log.json the Change Log (the Activity tab): what happened, one line each
412
416
  ```
413
417
 
414
418
  Add `.rushes/` to git if you want your review history kept with the project — and `screenshots/` alongside it, since notes point to the grabs there. Keep `proxies/` out of git: proxies can run to gigabytes, and Rushes can always make them again. Rushes ignores its own temporary files.