rushes 0.8.1 → 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-DhS2fPd_.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
package/dist/mcp/tools.js CHANGED
@@ -5,6 +5,7 @@ import { VERSION } from "../server/app.js";
5
5
  import { BRING_IN_MAX } from "../server/found.js";
6
6
  import { LABEL_MAX, oneLineOf } from "../core/labels.js";
7
7
  import { LOG_AREAS } from "../core/logText.js";
8
+ import { NOTE_STATES } from "../core/noteState.js";
8
9
  const project = z.string().optional().describe("Project folder. Defaults to the current working directory.");
9
10
  const stage = z.enum(["script", "picture", "voice", "music", "sfx", "mix", "visuals"]);
10
11
  const fileKind = z.enum(["doc", "image", "caption", "export", "delivery", "edit"]);
@@ -146,7 +147,7 @@ export function createMcpServer(ctx) {
146
147
  }, safe(async ({ project, video, version }) => (await ctx.client(project)).put(`/api/videos/${encodeURIComponent(video)}/lock`, { version })));
147
148
  server.registerTool("rushes_status", {
148
149
  title: "Rushes status",
149
- description: "Which tabs are unlocked and how many open items each has. Also `brief`: whether brief.md exists, its status (draft or approved, set when the user presses Approve) and how many sections the user changed; `storyboard`: whether storyboard.md exists, how many shots there are, how many are approved and how many the user changed; and `build`: whether planning has begun (`started`), whether the brief, every script section (when there is a script) and every shot are approved (`ready`), and what it is `waitingOn`. Also `films`: every film with `shelved` (the time the user shelved it, or null). A shelved film is one the user has set aside: leave it alone, make no new cuts of it and fix none of its notes unless the user says to. Its open notes are not counted in the tabs.",
150
+ description: "Which tabs are unlocked and how many open items each has (`todo`), and how many of those notes the user has already sent you (`sent`). Also `brief`: whether brief.md exists, its status (draft or approved, set when the user presses Approve) and how many sections the user changed; `storyboard`: whether storyboard.md exists, how many shots there are, how many are approved and how many the user changed; and `build`: whether planning has begun (`started`), whether the brief, every script section (when there is a script) and every shot are approved (`ready`), and what it is `waitingOn`. Also `films`: every film with `shelved` (the time the user shelved it, or null). A shelved film is one the user has set aside: leave it alone, make no new cuts of it and fix none of its notes unless the user says to. Its open notes are not counted in the tabs.",
150
151
  inputSchema: { project },
151
152
  }, safe(async ({ project }) => (await ctx.client(project)).get("/api/tabs")));
152
153
  server.registerTool("rushes_add_version", {
@@ -227,7 +228,7 @@ export function createMcpServer(ctx) {
227
228
  }, safe(async ({ project, ...b }) => (await ctx.client(project)).post("/api/formats", b)));
228
229
  server.registerTool("rushes_add_variant", {
229
230
  title: "Add an audio variant",
230
- description: "Add a voice read (in a round), music bed or SFX pass for side-by-side review. Returns its lane and variant ids: a note on it is `on` \"<lane id>/<variant id>\".",
231
+ description: "Add a voice read, music bed or SFX pass for side-by-side review, each in a round. A take you add is not in use and is not heard in the mix until the user picks it. Returns its lane and variant ids: a note on it is `on` \"<lane id>/<variant id>\".",
231
232
  inputSchema: {
232
233
  project,
233
234
  stage: z.enum(["voice", "music", "sfx"]),
@@ -239,7 +240,7 @@ export function createMcpServer(ctx) {
239
240
  .min(1)
240
241
  .max(64)
241
242
  .optional()
242
- .describe('Round name for voice reads (up to 64 characters), e.g. "Round 2 · Gerald, tone". Reads in one round are compared side by side; a new direction gets a new round.'),
243
+ .describe('Round name (up to 64 characters) for a read, a bed or an effects pass, e.g. "Round 2 · Gerald, tone" or "Round 2 · softer middle". Takes in one round are compared side by side; a new direction gets a new round.'),
243
244
  meta: z.record(z.string(), z.union([z.string(), z.number()])).optional().describe("e.g. {\"bpm\": 120, \"key\": \"A minor\"}"),
244
245
  description: z
245
246
  .string()
@@ -298,11 +299,12 @@ export function createMcpServer(ctx) {
298
299
  }, safe(async ({ project, section, file }) => (await ctx.client(project)).post(`/api/script/${encodeURIComponent(section)}/takes`, { file })));
299
300
  server.registerTool("rushes_list_notes", {
300
301
  title: "List notes",
301
- description: "Notes left in Rushes, filtered by tab, status, batch or version. A note's `on` says what it's about: null on Picture or for the whole mix, \"<lane>/<variant>\" for a music bed, SFX pass or voice variant, \"<lane>/<variant>:<cue>\" for an SFX cue, \"vo\" for the VO lane on Mix. Older notes may carry a bare variant id, \"vo\" for the assembled read, \"<section>:<take>\" for a take, or a section id. On Picture, a note's `format` is null when it's for every format, or a format id such as \"9x16\" when it's for that shape only. Notes on a shelved film (one the user has set aside) are left out.",
302
+ description: "Notes left in Rushes, filtered by tab, state, status, batch or version. Each note has a `state`: \"todo\" (the user's, not sent yet), \"sent\" (in a batch the user sent: yours to fix) or \"done\". `state: \"sent\"` lists everything you have been given and not finished, whichever batch it came in. A note's `on` says what it's about: null on Picture or for the whole mix, \"<lane>/<variant>\" for a music bed, SFX pass or voice variant, \"<lane>/<variant>:<cue>\" for an SFX cue, \"vo\" for the VO lane on Mix. Older notes may carry a bare variant id, \"vo\" for the assembled read, \"<section>:<take>\" for a take, or a section id. On Picture, a note's `format` is null when it's for every format, or a format id such as \"9x16\" when it's for that shape only. Notes on a shelved film (one the user has set aside) are left out.",
302
303
  inputSchema: {
303
304
  project,
304
305
  stage: stage.optional(),
305
- status: z.enum(["todo", "done"]).optional(),
306
+ state: z.enum(NOTE_STATES).optional().describe('"todo": not sent yet; "sent": sent to you and not done; "done".'),
307
+ status: z.enum(["todo", "done"]).optional().describe('"todo" is both unsent and sent notes; prefer `state`.'),
306
308
  batch: z.string().optional(),
307
309
  version: z.string().optional(),
308
310
  format: z
@@ -325,12 +327,12 @@ export function createMcpServer(ctx) {
325
327
  }));
326
328
  server.registerTool("rushes_get_batch", {
327
329
  title: "Get a batch",
328
- description: "The batch the user sent with Send to agent (latest by default), with its notes and script sections. It holds every open note from every tab and every film in play: `stage` is the tab when they all came from one, or null when it spans tabs, and each note carries its own `stage` and `video`. A note's `on` says what it's about: null on Picture or for the whole mix, \"<lane>/<variant>\" for a music bed, SFX pass or voice variant, \"<lane>/<variant>:<cue>\" for an SFX cue, \"vo\" for the VO lane on Mix. Older notes may carry a bare variant id, \"vo\" for the assembled read, \"<section>:<take>\" for a take, or a section id.",
330
+ description: "The batch the user sent by pressing Send, at the foot of the notes panel (latest by default), with its notes and script sections. It holds every open note from every tab and every film in play: `stage` is the tab when they all came from one, or null when it spans tabs, and each note carries its own `stage` and `video`. A note's `on` says what it's about: null on Picture or for the whole mix, \"<lane>/<variant>\" for a music bed, SFX pass or voice variant, \"<lane>/<variant>:<cue>\" for an SFX cue, \"vo\" for the VO lane on Mix, and on a Script note, the section id of its line (null: the script as a whole). Older notes may carry a bare variant id, \"vo\" for the assembled read, \"<section>:<take>\" for a take, or a section id.",
329
331
  inputSchema: { project, id: z.string().optional() },
330
332
  }, safe(async ({ project, id }) => (await ctx.client(project)).get(`/api/batches/${encodeURIComponent(id ?? "latest")}`)));
331
333
  server.registerTool("rushes_reply", {
332
334
  title: "Reply to notes",
333
- description: "Reply to one or more notes. Set status \"done\" when fixed, fixT to the time the fix is visible in the new cut, and fixVersion to that cut.",
335
+ description: "Reply to one or more notes. Set status \"done\" when fixed, fixT to the time the fix is visible in the new cut, and fixVersion to that cut. A reply without a status leaves its state as it was (a sent note stays with you); status \"todo\" on a done note reopens it for the user's next Send. Each note comes back with its new `state`.",
334
336
  inputSchema: {
335
337
  project,
336
338
  replies: z
@@ -351,7 +353,7 @@ export function createMcpServer(ctx) {
351
353
  }, safe(async ({ project, kind }) => (await ctx.client(project)).get(`/api/assets${kind ? `?kind=${encodeURIComponent(kind)}` : ""}`)));
352
354
  server.registerTool("rushes_get_picks", {
353
355
  title: "Get picks",
354
- description: "Which variant is in use per audio lane (per round on Voiceover), and each Mix lane's level in dB (where the user wants voice, music and sfx to sit). Picks and levels belong to one film: pass `video` (the film's id, as in the note you are fixing) to read that film's own; without it you get the whole file, each film's under `videos`. Section take picks are kept for older projects but not used.",
356
+ description: "Which read, bed and effects pass is in use for a film (`use.voice`, `use.music`, `use.sfx`: one each, or absent when nothing is picked), and each sound's level in dB (where the user wants voice, music and sfx to sit). A take you add is not in use until the user picks it. `lanes` still lists the pick inside each round. `takes` lists every read, bed and effects pass per sound, newest round first, each with its `state`: \"in-use\", \"new\" (arrived since the pick and waiting to be heard), \"earlier\" or \"put-away\" (the user set it aside: don't offer it again), and `madeFor`/`stale` (the cut it was made for, and whether the film has a later one). Picks and levels belong to one film: pass `video` (the film's id, as in the note you are fixing) to read that film's own; without it you get the whole file, each film's under `videos` (with its own `takes`). Section take picks are kept for older projects but not used.",
355
357
  inputSchema: { project, video: z.string().optional().describe("The film's id. Picks and levels are per film.") },
356
358
  }, safe(async ({ project, video }) => (await ctx.client(project)).get(`/api/picks${video ? `?video=${encodeURIComponent(video)}` : ""}`)));
357
359
  server.registerTool("rushes_add_file", {
@@ -7,6 +7,7 @@ import { addTake, editSection, setSections } from "../core/script.js";
7
7
  import { addNote, applyReply, applyUserEdit, checkNoteFormat, filterNotes } from "../core/notes.js";
8
8
  import { FORMAT_ID_RE, MAX_FORMATS, isPictureSize, labelOfId, versionFormats } from "../core/formats.js";
9
9
  import { createBatch, latestBatch } from "../core/batches.js";
10
+ import { markSent, NOTE_STATES, withState } from "../core/noteState.js";
10
11
  import { exportFileName, notesMarkdown } from "../core/exportNotes.js";
11
12
  import { tabStates } from "../core/tabs.js";
12
13
  import { addVisualVersion, checkVisualNote, registerVisual, visualNoteView, visualRatios } from "../core/visuals.js";
@@ -24,6 +25,8 @@ import { GRAB_PATH, OUTSIDE_CUT_EXT, OUTSIDE_MEDIA_EXT, SCREENSHOT_PATH, content
24
25
  import { BRING_IN_MAX, FoundScanner, ffprobeDuration, foundAnnouncer } from "./found.js";
25
26
  import { candidatePaths, listAssets, fpsFor, screenshotName } from "./assets.js";
26
27
  import { osRevealer, osOpener, OPEN_SAFE_EXT } from "./reveal.js";
28
+ import { inUse, setInUse } from "../core/picks.js";
29
+ import { filmTakes, putAway } from "../core/takes.js";
27
30
  import { LaneStageSchema, SectionStatusSchema, StageSchema, BoxSchema, PinSchema, FileKindSchema, MarkSchema, ProjectIdSchema, ShotSchema, LEVEL_MIN, LEVEL_MAX, LEVEL_STEP, lanesForVideo, picksForVideo, variantFilms } from "../core/schema.js";
28
31
  import { LABEL_MAX, oneLineOf } from "../core/labels.js";
29
32
  import { byOf, logBookFor } from "./logbook.js";
@@ -33,7 +36,7 @@ import { buildState, planWarning } from "../core/plan.js";
33
36
  import { broughtInEvent, cutEvent, fileEvent, filmEvent, formatEvent, lineEvent, lockEvent, notesSentEvent, picksEvent, repliesEvent, scriptEvent, takeEvent, variantEvent, variantFilmsEvent, visualEvent, } from "../core/logEvents.js";
34
37
  import { LOG_AREAS, LOG_MAX, changeLogFileName, logText, recentChanges } from "../core/logText.js";
35
38
  import { defaultRunner, measureMix } from "./loudness.js";
36
- export const VERSION = "0.8.1";
39
+ export const VERSION = "0.9.0";
37
40
  async function body(c, schema) {
38
41
  let json;
39
42
  try {
@@ -53,8 +56,9 @@ const formatId = z.string().max(16).regex(FORMAT_ID_RE);
53
56
  /** The longest path a format may be registered under (FoundItem and FoundPathsBody use the same). */
54
57
  const MAX_PATH = 1024;
55
58
  /** §25.5: a note on a visual with where it is, in words, and the picture to open: what an agent reading the batch needs. */
59
+ // Every note the server hands out carries its lifecycle state (noteState.ts), worked out, never stored.
56
60
  function withVisualViews(notes, visuals) {
57
- return notes.map((n) => (n.stage === "visuals" ? { ...n, visual: visualNoteView(n, visuals) } : n));
61
+ return notes.map((n) => (n.stage === "visuals" ? { ...withState(n), visual: visualNoteView(n, visuals) } : withState(n)));
58
62
  }
59
63
  const NewNoteBody = z.object({
60
64
  stage: StageSchema,
@@ -171,12 +175,14 @@ const PickMap = z.record(z.string(), z.string().nullable());
171
175
  // §19.6: a level is −24..6 dB in 0.5 dB steps; null resets it to 0 (removes the key).
172
176
  const LevelValue = z.number().min(LEVEL_MIN).max(LEVEL_MAX).multipleOf(LEVEL_STEP);
173
177
  const LevelsBody = z.object({ voice: LevelValue.nullable(), music: LevelValue.nullable(), sfx: LevelValue.nullable() }).partial();
178
+ const PutAwayBody = z.object({ away: z.boolean() });
174
179
  const PicksBody = z.object({ video: z.string().min(1).max(200).optional(), lanes: PickMap.optional(), sections: PickMap.optional(), levels: LevelsBody.optional() });
175
- // No stage: every tab's open notes (Send to agent). A stage: that tab's only.
180
+ // No stage: every tab's open notes (Send). A stage: that tab's only.
176
181
  const BatchBody = z.object({ stage: StageSchema.optional() });
177
182
  const NoteQuery = z.object({
178
183
  stage: StageSchema.optional(),
179
184
  status: z.enum(["todo", "done"]).optional(),
185
+ state: z.enum(NOTE_STATES).optional(),
180
186
  batch: z.string().optional(),
181
187
  version: z.string().optional(),
182
188
  // §21.4: a format's notes, with the all-format notes unless onlyThisFormat (R14: Picture only).
@@ -673,7 +679,7 @@ export function createApp(store, opts = {}) {
673
679
  ...v,
674
680
  versions: await Promise.all(v.versions.map(async (ver) => ({ ...ver, proxyNeed: await jobs.needNow(fromManifestPath(store.root, ver.file)) }))),
675
681
  })));
676
- return c.json({ version: VERSION, project: { ...project, videos }, script, notes, picks, batches, tabs, visuals, proxies: { ffmpeg, jobs: jobs.list() }, found: foundSummary, log: logHead, brief: briefView, storyboard: storyboardView, build: buildState({ brief: briefView, script: script.sections, storyboard: storyboardView }) });
682
+ return c.json({ version: VERSION, project: { ...project, videos }, script, notes, picks: withUse(project, picks), batches, tabs, visuals, proxies: { ffmpeg, jobs: jobs.list() }, found: foundSummary, log: logHead, brief: briefView, storyboard: storyboardView, build: buildState({ brief: briefView, script: script.sections, storyboard: storyboardView }) });
677
683
  });
678
684
  // ---- found: the project's other files (§20) ----
679
685
  app.get("/api/found", async (c) => {
@@ -821,7 +827,7 @@ export function createApp(store, opts = {}) {
821
827
  }
822
828
  }
823
829
  const { result } = await store.update("notes", (f) => addNote(f, { ...b, shot, by: "user" }));
824
- return c.json({ note: result }, 201);
830
+ return c.json({ note: withState(result) }, 201);
825
831
  });
826
832
  app.patch("/api/notes/:id", async (c) => {
827
833
  const b = await body(c, UserEditBody);
@@ -830,13 +836,13 @@ export function createApp(store, opts = {}) {
830
836
  const visuals = project ? await store.read("visuals") : null;
831
837
  const check = project && visuals ? (next, prev) => (next.stage === "visuals" ? checkVisualNote(next, visuals) : checkNoteFormat({ next, prev, boxRedrawn: b.box !== undefined }, project)) : undefined;
832
838
  const { result } = await store.update("notes", (f) => applyUserEdit(f, { id: c.req.param("id"), ...b }, check));
833
- return c.json({ note: result });
839
+ return c.json({ note: withState(result) });
834
840
  });
835
841
  app.post("/api/replies", async (c) => {
836
842
  const b = await body(c, RepliesBody);
837
843
  const { result } = await store.update("notes", (f) => b.replies.map((r) => applyReply(f, r)));
838
844
  await log.add(() => repliesEvent(result), by(c));
839
- return c.json({ notes: result });
845
+ return c.json({ notes: result.map(withState) });
840
846
  });
841
847
  // ---- media ----
842
848
  app.post("/api/versions", async (c) => {
@@ -1151,8 +1157,9 @@ export function createApp(store, opts = {}) {
1151
1157
  await store.update("picks", (k) => {
1152
1158
  for (const film of result.left) {
1153
1159
  const own = k.videos[film];
1160
+ // Through setInUse, so the take in use for that sound goes with the pick (§27.6).
1154
1161
  if (own?.lanes[result.lane.id] === result.variant.id)
1155
- delete own.lanes[result.lane.id];
1162
+ setInUse(own, data.lanes, result.lane, null, new Date());
1156
1163
  }
1157
1164
  });
1158
1165
  }
@@ -1160,6 +1167,23 @@ export function createApp(store, opts = {}) {
1160
1167
  await log.add(() => variantFilmsEvent(result.lane, result.variant, names), by(c));
1161
1168
  return c.json({ lane: result.lane, variant: result.variant });
1162
1169
  });
1170
+ // §27.6: put a read, bed or pass away (hidden, never deleted), or bring it back. The take in use
1171
+ // on any film stays where it can be seen: choose another first.
1172
+ app.put("/api/variants/:lane/:variant/put-away", async (c) => {
1173
+ const b = await body(c, PutAwayBody);
1174
+ const laneId = c.req.param("lane");
1175
+ const variantId = c.req.param("variant");
1176
+ const picks = await store.read("picks");
1177
+ const { result } = await store.update("project", (p) => {
1178
+ const stage = p.lanes.find((l) => l.id === laneId)?.stage;
1179
+ const isIt = (use) => stage !== undefined && use[stage]?.lane === laneId && use[stage]?.variant === variantId;
1180
+ const usedOn = p.videos.filter((v) => isIt(filmUse(p, picks, v.id))).map((v) => v.name);
1181
+ if (p.videos.length === 0 && isIt(filmUse(p, picks, undefined)))
1182
+ usedOn.push("this film");
1183
+ return putAway(p, laneId, variantId, b.away, usedOn);
1184
+ });
1185
+ return c.json({ variant: result });
1186
+ });
1163
1187
  // ---- script ----
1164
1188
  app.get("/api/script", async (c) => c.json({ script: await store.read("script") }));
1165
1189
  app.put("/api/script", async (c) => {
@@ -1190,10 +1214,33 @@ export function createApp(store, opts = {}) {
1190
1214
  });
1191
1215
  // ---- picks ----
1192
1216
  // ?video=<id> reads one film's picks as a plain picks file (lanes and levels are that film's own).
1217
+ // §27.6: every reader gets the take in use already worked out, per film, so the dashboard, an
1218
+ // agent and the loudness readout can never disagree about it.
1219
+ // Always among the takes the film hears (lanesForVideo), which is what Mix plays and the readout
1220
+ // measures: a take that has left the film is never its take in use.
1221
+ const filmUse = (project, picks, video) => inUse({ lanes: lanesForVideo(project.lanes, video, project.videos.length) }, picksForVideo(picks, video));
1222
+ const withUse = (project, picks, video) => {
1223
+ if (video)
1224
+ return { ...picksForVideo(picks, video), use: filmUse(project, picks, video) };
1225
+ const videos = {};
1226
+ for (const [id, v] of Object.entries(picks.videos))
1227
+ videos[id] = { ...v, use: filmUse(project, picks, id) };
1228
+ return { ...picks, use: filmUse(project, picks, undefined), videos };
1229
+ };
1230
+ // An agent's reading also lists every take with its state (in-use, new, earlier, put-away: takes.ts), as the
1231
+ // desk's lists show them: per film, or for one film with ?video=.
1193
1232
  app.get("/api/picks", async (c) => {
1194
- const picks = await store.read("picks");
1233
+ const [project, picks] = await Promise.all([store.read("project"), store.read("picks")]);
1195
1234
  const video = c.req.query("video");
1196
- return c.json(video ? picksForVideo(picks, video) : picks);
1235
+ const read = withUse(project, picks, video);
1236
+ if (video)
1237
+ return c.json({ ...read, takes: filmTakes(project, picks, video) });
1238
+ const videos = {};
1239
+ for (const [id, v] of Object.entries(read.videos))
1240
+ videos[id] = { ...v, takes: filmTakes(project, picks, id) };
1241
+ for (const v of project.videos)
1242
+ videos[v.id] ??= { lanes: {}, levels: {}, takes: filmTakes(project, picks, v.id) };
1243
+ return c.json({ ...read, takes: filmTakes(project, picks, undefined), videos });
1197
1244
  });
1198
1245
  app.put("/api/picks", async (c) => {
1199
1246
  const b = await body(c, PicksBody);
@@ -1220,32 +1267,58 @@ export function createApp(store, opts = {}) {
1220
1267
  }
1221
1268
  };
1222
1269
  let before = {};
1270
+ // The lanes' sounds come from project.json: a pick in a lane it knows also settles which take
1271
+ // is in use for that sound (§27.6). If it can't be read now, the pick still stands, plainly.
1272
+ const projectBefore = await store.read("project").catch(() => null);
1273
+ const lanes = projectBefore?.lanes ?? [];
1274
+ const now = new Date();
1275
+ let usedBefore = {};
1223
1276
  const { data } = await store.update("picks", (p) => {
1277
+ if (projectBefore)
1278
+ usedBefore = filmUse(projectBefore, p, b.video);
1224
1279
  merge(p.sections, b.sections);
1225
1280
  if (b.video) {
1226
1281
  // A film's picks and levels are its own: another film's are never touched.
1227
1282
  const own = (p.videos[b.video] ??= { lanes: {}, levels: {} });
1228
1283
  before = { ...own.lanes };
1229
- merge(own.lanes, b.lanes);
1284
+ for (const [k, v] of Object.entries(b.lanes ?? {})) {
1285
+ const lane = lanes.find((l) => l.id === k);
1286
+ if (lane)
1287
+ setInUse(own, lanes, lane, v, now);
1288
+ else
1289
+ merge(own.lanes, { [k]: v });
1290
+ }
1230
1291
  mergeLevels(own.levels);
1231
1292
  return;
1232
1293
  }
1294
+ // No film named: a project with no cut yet (or an older client). The same rule, in the project-wide set.
1233
1295
  before = { ...p.lanes };
1234
- merge(p.lanes, b.lanes);
1296
+ for (const [k, v] of Object.entries(b.lanes ?? {})) {
1297
+ const lane = lanes.find((l) => l.id === k);
1298
+ if (lane)
1299
+ setInUse(p, lanes, lane, v, now);
1300
+ else
1301
+ merge(p.lanes, { [k]: v });
1302
+ }
1235
1303
  mergeLevels(p.levels);
1236
1304
  });
1237
- const now = b.video ? (data.videos[b.video]?.lanes ?? {}) : data.lanes;
1305
+ const after = b.video ? (data.videos[b.video]?.lanes ?? {}) : data.lanes;
1238
1306
  // §22.5: a change of what's picked is logged; levels alone aren't (R10).
1239
- const changed = Object.keys({ ...before, ...now }).some((k) => before[k] !== now[k]);
1307
+ // The names come from project.json; if it can't be read now, the pick still stands (ruling e).
1308
+ const project = await store.read("project").catch(() => null);
1309
+ // §27.6: what the log tells is the take in use for each sound, so a pick that changes nothing in
1310
+ // `lanes` (an earlier take brought back) is still a change, and a round's leftover pick is not news.
1311
+ const usedNow = project ? filmUse(project, data, b.video) : {};
1312
+ const sameUse = ["voice", "music", "sfx"].every((s) => usedBefore[s]?.lane === usedNow[s]?.lane && usedBefore[s]?.variant === usedNow[s]?.variant);
1313
+ const changed = Object.keys({ ...before, ...after }).some((k) => before[k] !== after[k]) || !sameUse;
1240
1314
  if (changed) {
1241
- // The names come from project.json; if it can't be read now, the pick still stands (ruling e).
1242
- const project = await store.read("project").catch(() => null);
1315
+ const inUseLanes = Object.fromEntries(Object.values(usedNow).map((u) => [u.lane, u.variant]));
1243
1316
  if (project)
1244
- await log.add(() => picksEvent(project, now, project.videos.find((v) => v.id === b.video)), by(c));
1317
+ await log.add(() => picksEvent(project, inUseLanes, project.videos.find((v) => v.id === b.video)), by(c));
1245
1318
  else
1246
1319
  log.failures += 1;
1247
1320
  }
1248
- return c.json(b.video ? picksForVideo(data, b.video) : data);
1321
+ return c.json(project ? withUse(project, data, b.video) : b.video ? picksForVideo(data, b.video) : data);
1249
1322
  });
1250
1323
  // ---- mix loudness (§17.6) ----
1251
1324
  app.post("/api/mix/loudness", async (c) => {
@@ -1278,11 +1351,7 @@ export function createApp(store, opts = {}) {
1278
1351
  if (recent)
1279
1352
  result.prompt = `${result.prompt}\n\n${recent}`;
1280
1353
  await store.update("batches", (f) => { f.batches.push(result); });
1281
- await store.update("notes", (f) => {
1282
- for (const n of f.notes)
1283
- if (n.batch === null && result.noteIds.includes(n.id))
1284
- n.batch = result.id;
1285
- });
1354
+ await store.update("notes", (f) => markSent(f.notes, result));
1286
1355
  await log.add(() => notesSentEvent(result), by(c));
1287
1356
  return result;
1288
1357
  });
@@ -1,3 +1,4 @@
1
+ import { statusAfterEdit } from "../core/approval.js";
1
2
  import { BRIEF_FILE, hashText, parseBrief, setSectionBody, setStatus } from "../core/brief.js";
2
3
  import { InvalidError, RushesError } from "../core/errors.js";
3
4
  import { RecordFile } from "./record.js";
@@ -32,7 +33,7 @@ export class BriefService extends RecordFile {
32
33
  view() {
33
34
  return this.run(async () => this.build(await this.readText(), await this.store.read("brief")));
34
35
  }
35
- /** Saves one section. An edit to an approved brief reopens it: the status line goes back to draft. */
36
+ /** Saves one section. A change to an approved brief's words reopens it: the status line goes back to draft. */
36
37
  setSection(index, heading, text, expectHash) {
37
38
  return this.run(async () => {
38
39
  const prev = await this.current(expectHash);
@@ -43,7 +44,9 @@ export class BriefService extends RecordFile {
43
44
  catch (e) {
44
45
  throw new InvalidError(e.message);
45
46
  }
46
- if (parseBrief(next).status === "approved")
47
+ // approval.ts: an approved brief reopens when a section's words change, not on a save of the same words.
48
+ const was = parseBrief(next).status;
49
+ if (was === "approved" && statusAfterEdit(was, { wordsChanged: next !== prev }) === "draft")
47
50
  next = setStatus(next, "draft");
48
51
  if (next !== prev)
49
52
  await this.write(prev, next);
@@ -4,6 +4,7 @@ import { stat } from "node:fs/promises";
4
4
  import { RushesError } from "../core/errors.js";
5
5
  import { AUDIO_FORMATS, probe } from "../core/media.js";
6
6
  import { fromManifestPath } from "../core/paths.js";
7
+ import { inUse, inUseVariant } from "../core/picks.js";
7
8
  /** Grace period between SIGTERM and SIGKILL when a run is aborted. */
8
9
  const KILL_GRACE_MS = 2_000;
9
10
  /**
@@ -62,53 +63,29 @@ export function ffmpegAvailable(run = defaultRunner) {
62
63
  }
63
64
  return cached;
64
65
  }
65
- function voiceSource(project, picks) {
66
- // §18.4: the newest round (lane) with a pick; takes are never mixed.
67
- const voice = project.lanes.filter((l) => l.stage === "voice");
68
- for (let i = voice.length - 1; i >= 0; i--) {
69
- const pickedId = picks.lanes[voice[i].id];
70
- const variant = pickedId ? voice[i].variants.find((v) => v.id === pickedId) : undefined;
71
- if (variant)
72
- return { kind: "variant", variant };
73
- }
74
- return { kind: "none" };
75
- }
76
66
  /**
77
- * The files and offsets a mix of `lanes` is made from (§17.6, §18.4) -- exactly what the Mix tab
78
- * plays:
79
- * - voice: the pick of the newest round (voice lane) that has one. With no round picked, there is
80
- * no voice input at all -- takes are never mixed, however many a script section has.
81
- * - music: the picked variant of each music lane, at 0;
82
- * - sfx: the picked variant of each sfx lane, at 0.
67
+ * The files and offsets a mix of `lanes` is made from (§17.6, §18.4, §27.6) -- exactly what Mix plays:
68
+ * for each sound asked for, the one take in use (picks.ts `inUse`), at 0. At most one input per sound.
83
69
  *
84
- * A music or sfx lane with nothing picked is left out, never stood in for by its first variant:
85
- * Mix plays only explicit picks, so the readout must measure only them. A manifest entry whose
86
- * file is missing from disk is left out too, rather than handed to ffmpeg.
70
+ * - voice: a read from a round, never a section's takes, however many a script section has.
71
+ * - A sound with nothing in use is left out, never stood in for by a lane's first variant: Mix plays
72
+ * only what was picked, so the readout must measure only that.
73
+ * - A project from before §27 with a pick in several lanes of one sound plays the newest lane's.
74
+ * - A manifest entry whose file is missing from disk is left out too, rather than handed to ffmpeg.
87
75
  */
88
76
  export function mixInputs(project, picks, lanes, root) {
89
- const want = new Set(lanes);
77
+ const use = inUse(project, picks);
90
78
  const out = [];
91
- const add = (file, offset, stage) => {
92
- const abs = fromManifestPath(root, file);
93
- if (existsSync(abs))
94
- out.push({ file: abs, offset, stage, gainDb: picks.levels[stage] ?? 0 });
95
- };
96
- if (want.has("voice")) {
97
- const voice = voiceSource(project, picks);
98
- if (voice.kind === "variant")
99
- add(voice.variant.file, 0, "voice");
100
- }
101
- for (const stage of ["music", "sfx"]) {
102
- if (!want.has(stage))
79
+ // Voice first, then music, then effects: the order the readout's inputs have always had.
80
+ for (const stage of ["voice", "music", "sfx"]) {
81
+ if (!lanes.includes(stage))
103
82
  continue;
104
- for (const lane of project.lanes) {
105
- if (lane.stage !== stage)
106
- continue;
107
- const pickedId = picks.lanes[lane.id];
108
- const variant = pickedId ? lane.variants.find((v) => v.id === pickedId) : undefined;
109
- if (variant)
110
- add(variant.file, 0, stage);
111
- }
83
+ const taken = inUseVariant(project, use, stage);
84
+ if (!taken)
85
+ continue;
86
+ const abs = fromManifestPath(root, taken.variant.file);
87
+ if (existsSync(abs))
88
+ out.push({ file: abs, offset: 0, stage, gainDb: picks.levels[stage] ?? 0 });
112
89
  }
113
90
  return out;
114
91
  }
@@ -178,10 +155,8 @@ async function runWithTimeout(run, args, timeoutMs) {
178
155
  }
179
156
  const probeDuration = async (file) => (await probe(file, { formats: AUDIO_FORMATS })).duration;
180
157
  function voSpan(project, picks, root) {
181
- const voice = voiceSource(project, picks);
182
- if (voice.kind === "variant")
183
- return { kind: "variant", file: fromManifestPath(root, voice.variant.file) };
184
- return null;
158
+ const voice = inUseVariant(project, inUse(project, picks), "voice");
159
+ return voice ? { kind: "variant", file: fromManifestPath(root, voice.variant.file) } : null;
185
160
  }
186
161
  async function voSpanSeconds(span, durationOf) {
187
162
  if (span === null)
@@ -1,3 +1,4 @@
1
+ import { statusAfterEdit } from "../core/approval.js";
1
2
  import { hashText } from "../core/brief.js";
2
3
  import { InvalidError, RushesError } from "../core/errors.js";
3
4
  import { STORYBOARD_FILE, cutShots, editShot, parseStoryboard } from "../core/storyboard.js";
@@ -58,7 +59,9 @@ export class StoryboardService extends RecordFile {
58
59
  const prev = await this.current(expectHash);
59
60
  const was = parseStoryboard(prev).shots.find((s) => s.index === index);
60
61
  const changesWords = was && ((edit.description !== undefined && edit.description.trim() !== was.description) || (edit.direction !== undefined && edit.direction.replace(/\s*\r?\n\s*/g, " ").trim() !== was.direction));
61
- const full = was?.status === "approved" && changesWords && edit.status === undefined ? { ...edit, status: "draft" } : edit;
62
+ // approval.ts: only a status that changes is written, so a shot with no Status line keeps none.
63
+ const status = was ? statusAfterEdit(was.status, { wordsChanged: !!changesWords, status: edit.status }) : edit.status;
64
+ const full = status !== undefined && (edit.status !== undefined || status !== was?.status) ? { ...edit, status } : edit;
62
65
  let next;
63
66
  try {
64
67
  next = editShot(prev, index, heading, full);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rushes",
3
- "version": "0.8.1",
3
+ "version": "0.9.0",
4
4
  "description": "A local review desk for video made with AI agents: timecoded notes, script edits and audio picks your agent can read and act on.",
5
5
  "keywords": [
6
6
  "video",
@@ -61,8 +61,8 @@
61
61
  "zod": "^4.1.0"
62
62
  },
63
63
  "devDependencies": {
64
- "@fontsource/figtree": "^5.3.0",
65
- "@fontsource/jetbrains-mono": "^5.3.0",
64
+ "@fontsource/geist": "^5.3.0",
65
+ "@fontsource/geist-mono": "^5.3.0",
66
66
  "@playwright/test": "^1.63.0",
67
67
  "@types/node": "^22.10.0",
68
68
  "preact": "^10.29.8",
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: rushes
3
- description: Plan and review video work with the user in Rushes, a local review desk. Use when the user wants to start a new film or video (plan it with them first, then build), when they want to bring a film they started in the chat into Rushes (rebuild the plan from the conversation), when you've rendered a cut, written a VO script, recorded voice reads, music beds or SFX passes and the user should review them, or when the user says they left notes, pressed Send to agent, or pastes a Rushes batch prompt.
3
+ description: Plan and review video work with the user in Rushes, a local review desk. Use when the user wants to start a new film or video (plan it with them first, then build), when they want to bring a film they started in the chat into Rushes (rebuild the plan from the conversation), when you've rendered a cut, written a VO script, recorded voice reads, music beds or SFX passes and the user should review them, or when the user says they left notes, pressed Send in Rushes, or pastes a Rushes batch prompt.
4
4
  ---
5
5
 
6
6
  # Rushes
@@ -15,8 +15,8 @@ When the user wants a new video ("start a new film", "make a launch video", "a n
15
15
 
16
16
  1. **Create the project** unless one exists: `npx -y rushes new <folder> --no-browser`, then `rushes_open` with `project: "<folder>"`. It makes the folders and a `brief.md` to fill in. Always pass `--no-browser`: without it the command stays running as the server and never returns.
17
17
  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.
18
- 3. **Write `brief.md`.** Fill every section and leave `Status: draft`. 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.
19
- 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`.
18
+ 3. **Write `brief.md`.** Fill every section and leave `Status: draft`. 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.
19
+ 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`.
20
20
  5. **Storyboard.** Write `storyboard.md` in the project root: a `# Storyboard: <film>` title, then one section per shot, in this shape:
21
21
 
22
22
  ```markdown
@@ -30,10 +30,10 @@ When the user wants a new video ("start a new film", "make a launch video", "a n
30
30
  A folder of clips lands in the window from the right.
31
31
  ```
32
32
 
33
- `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.
33
+ `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.
34
34
  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.
35
35
 
36
- The brief and the storyboard are Markdown files the user reads and approves on their own pages under Planning.
36
+ The brief and the storyboard are Markdown files the user reads and approves on their own pages under Plan.
37
37
 
38
38
  ## Picking up a film that's underway
39
39
 
@@ -41,7 +41,7 @@ When the user asks to open or review a film they started in the chat, or the pro
41
41
 
42
42
  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`.
43
43
  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.
44
- 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.
44
+ 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.
45
45
  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.
46
46
  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.
47
47
 
@@ -49,7 +49,7 @@ When a user starts briefing in the chat, offer to keep `brief.md` up to date as
49
49
 
50
50
  ## Visuals
51
51
 
52
- For stills, standalone images and carousels, register one visual per post with `rushes_add_visual`: a `name` and `pages`, each page with its pictures, one per aspect ratio, in every aspect ratio the post comes in (Rushes reads each ratio from the picture). The user marks a region, a point or the whole image in the Visuals tab and sends a batch; each note names its visual, version, page, ratio, where on the picture it is (`words`) and the `file` to open. A note with no ratio is for every ratio. Fix the pictures, register a new version with `rushes_add_visual` (`visual` and only the pages that changed, each with `n`), then `rushes_reply` to each note you fixed with `status: "done"` and `fixVersion` set to it (a note you did not fix stays `todo`, with the reason in `reply`). The full contract is in `AGENTS.md`.
52
+ For stills, standalone images and carousels, register one visual per post with `rushes_add_visual`: a `name` and `pages`, each page with its pictures, one per aspect ratio, in every aspect ratio the post comes in (Rushes reads each ratio from the picture). The user marks a region, a point or the whole image in the Visuals workspace and sends a batch; each note names its visual, version, page, ratio, where on the picture it is (`words`) and the `file` to open. A note with no ratio is for every ratio. Fix the pictures, register a new version with `rushes_add_visual` (`visual` and only the pages that changed, each with `n`), then `rushes_reply` to each note you fixed with `status: "done"` and `fixVersion` set to it (a note you did not fix stays `todo`, with the reason in `reply`). The full contract is in `AGENTS.md`.
53
53
 
54
54
  ## Shelved films
55
55
 
@@ -58,15 +58,15 @@ For stills, standalone images and carousels, register one visual per post with `
58
58
  ## Reviewing and fixing
59
59
 
60
60
  1. Register what you made:
61
- - `rushes_add_version` for a render. Give every cut a short `label` (48 characters at most) saying what changed, and put the detail in `note`. If the cut is likely to play badly in a browser, the reply carries `proxySuggested: true` and `proxyReason`; Picture offers the user a proxy. Prefer H.264 MP4 to avoid this;
61
+ - `rushes_add_version` for a render. Give every cut a short `label` (48 characters at most) saying what changed, and put the detail in `note`. If the cut is likely to play badly in a browser, the reply carries `proxySuggested: true` and `proxyReason`; the Timeline tab offers the user a proxy. Prefer H.264 MP4 to avoid this;
62
62
  - `rushes_add_format` for each other shape of a cut (a 9:16, 1:1 or 4:5 of the same edit): register every shape you rendered, main one first, or pass `formats: [{ file }]` to `rushes_add_version`. Its `label` is only a ratio hint such as 2.39:1, never the cut's short label;
63
63
  - `rushes_set_script` for the VO script. It merges by `id`, so send only the sections you changed; sections you leave out are kept. `rushes_get_script` reads the whole script;
64
- - `rushes_add_variant` for each voice read, music bed or SFX pass, with `video` set to the film it is for, or a list of films when one bed is fitted to several (only those films' tabs list it; with more than one film, one without `video` is on no film until it is put on one, and `rushes_set_films` moves an existing one). Voice reads carry `stage: "voice"` and a `round` (its name — reads in one round are compared side by side; a new direction gets a new round); say what the read is, or what changed, in `description`. Music and SFX carry `meta.description` for their lane card, and SFX passes carry `cues` as `{name, t, file?}`: the same name each time a sound comes back, and `file` (an audio file) when you know which sample you placed;
64
+ - `rushes_add_variant` for each voice read, music bed or SFX pass, with `video` set to the film it is for, or a list of films when one bed is fitted to several (only those films' tabs list it; with more than one film, one without `video` is on no film until it is put on one, and `rushes_set_films` moves an existing one). Voice reads carry `stage: "voice"` and a `round` (its name — reads in one round are compared side by side; a new direction gets a new round); say what the read is, or what changed, in `description`. Music and SFX take a `round` too (each new batch is a round). A take you add is not in use until the user picks it. Music and SFX carry `meta.description` for their row in the list of takes, and SFX passes carry `cues` as `{name, t, file?}`: the same name each time a sound comes back, and `file` (an audio file) when you know which sample you placed;
65
65
  - `rushes_set_shots` for the storyboard's shots, once you have the first cut; send new timings when a later cut moves them.
66
66
  2. Call `rushes_open` and tell the user it's ready, with what it brought in and what it left (below). Each project's dashboard lives at its own address, `/p/<id>/`.
67
- 3. When the user sends a batch, call `rushes_get_batch` and fix every note in it. A batch holds every open note from every tab and film, so each note's own `stage` and `video` say where it belongs. A note carries the `shot` it falls in; on an audio stage, call `rushes_get_picks` first — on Mix it also returns `levels` (dB per lane), which you read, not set. Its `on` says what it's about: `"<lane>/<variant>"` for a bed, pass or voice read (on Voiceover the lane names the round), `"<lane>/<variant>:<cue>"` for an SFX cue, `"vo"` for the Mix VO lane, or `null` for the whole mix; older notes may carry a section id or `"<section>:<take>"`. On Music, Sound effects and Mix treat `marks` (e.g. "Fall", "Quieter 3 dB") as part of the note; Voiceover notes carry none — they're Whole (`Speaker`, `Pacing`, `Tone`, `Overall`) or Point (`Fix this`, `Keep this`) instead. A Picture note's `format` is null for every format, or a format id such as `"9x16"`: when it isn't null, fix only that format. Picks are set from the dashboard only — no tool or CLI command sets one.
67
+ 3. When the user sends a batch, call `rushes_get_batch` and fix every note in it. A batch holds every open note from every tab and film, so each note's own `stage` and `video` say where it belongs. A note carries the `shot` it falls in; on an audio stage, call `rushes_get_picks` first — for a mix note (stage `mix`, made on the Timeline tab) it also returns `levels` (dB per sound), which you read, not set. Its `on` says what it's about: `"<lane>/<variant>"` for a bed, pass or voice read (for a voice read the lane names the round), `"<lane>/<variant>:<cue>"` for an SFX cue, `"vo"` for the voice in the mix, or `null` for the whole mix; older notes may carry a section id or `"<section>:<take>"`. On music, sfx and mix notes treat `marks` (e.g. "Fall", "Quieter 3 dB") as part of the note; voice notes carry none — they're on the whole read, a point in it, or a range of it (`t` to `tOut`: replace or fix just that stretch), and the `text` says what to change. A note on the cut (stage `picture`) has a `format` that is null for every format, or a format id such as `"9x16"`: when it isn't null, fix only that format. Picks are set from the dashboard only — no tool or CLI command sets one.
68
68
  4. Register the new cut with `rushes_add_version`. On a locked video the reply carries a `warning`.
69
- 5. Reply to all the notes in one `rushes_reply` call. For each note set `status: "done"`, a one-line `reply`, `fixT` (when the fix is visible in the new cut, in seconds) and `fixVersion`.
69
+ 5. Reply to all the notes in one `rushes_reply` call. For each note set `status: "done"`, a one-line `reply`, `fixT` (when the fix is visible in the new cut, in seconds) and `fixVersion`. Each note has a `state`: `todo` (not sent yet), `sent` (yours to fix) or `done`; `rushes_list_notes` with `state: "sent"` finds every note you still owe. `rushes_get_picks` lists each take's `state` too (`in-use`, `new`, `earlier`, `put-away`): never offer a put-away take again.
70
70
  6. For script batches: when a section's `proposed` differs from `current`, adopt it with `rushes_set_script`, sending just that section with its `id`. 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.
71
71
  7. Lock picture with `rushes_lock_picture` only when the user says picture is locked; `version: null` unlocks it.
72
72
 
@@ -74,9 +74,9 @@ At the start of a session, call `rushes_get_log` to catch up (newest first; `lim
74
74
 
75
75
  Save renders, voice reads, beds and passes under the project's `renders/`, `audio/voiceover/`, `audio/music/` and `audio/sfx/` folders. Screenshots the user grabs with G or the camera button land in `screenshots/`. Use `rushes_list_assets` (optional `kind`) to find a file the user refers to but hasn't given you a path for, such as "use the screenshot I just took".
76
76
 
77
- The **Assets** tab is a library: Screenshots, Cuts, Voiceover, Music, Sound effects, Scripts & docs, Images, Captions, Exports, Delivery, Edit files and Proxies. Top-level `.md`, `.txt`, `.pdf`, `.srt` and `.vtt` files, and anything in `exports/`, are found automatically. Register everything else with `rushes_add_file` (`kind`, `file`, optional `name`, `note`, `video`): deliverables and platform exports as `delivery`, NLE project files as `edit`, storyboards/references/logos as `image`, briefs as `doc`. When the user wants to share notes, call `rushes_export_notes` — it writes a dated Markdown file to `exports/` and returns the path.
77
+ The **Assets** workspace is a library: Screenshots, Cuts, Voiceover, Music, Sound effects, Scripts & docs, Images, Captions, Exports, Delivery, Edit files and Proxies. Top-level `.md`, `.txt`, `.pdf`, `.srt` and `.vtt` files, and anything in `exports/`, are found automatically. Register everything else with `rushes_add_file` (`kind`, `file`, optional `name`, `note`, `video`): deliverables and platform exports as `delivery`, NLE project files as `edit`, storyboards/references/logos as `image`, briefs as `doc`. When the user wants to share notes, call `rushes_export_notes` — it writes a dated Markdown file to `exports/` and returns the path.
78
78
 
79
- 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 brings in the current set of files that go with the newest cut (at most one voice read, one music bed and one sound effects pass, unpicked), leaving the rest in Assets › Found. `rushes_open` returns `broughtIn` (with each file's `origin`), `alreadyIn`, `failed` and `found` (counts by kind, called `counts` by `rushes_scan`), and waits about 20 seconds, answering `scanning: true` if the folder is big. Pass `include` for files you made for this cut — `include: [{ path, kind?, round? }]` — and they come in whatever they score, and win over the scoring, for that cut, on later scans too. `rushes_open` also takes `film`. `rushes_scan` (CLI `rushes scan`) looks again, also brings in the current set, and lists the candidates left, with reasons; `rushes_bring_in` (CLI `rushes bring-in <file>...`) brings chosen files in (up to 12 files of each kind per call) and refuses any path outside the project folder. Nothing is ever picked. The user reviews the rest in Assets › Found (**Bring in**, **Not these**, **Look again**); a locked Voiceover, Music or Sound effects tab shows "14 music files found in this project" with a **Review** button when files of its kind were found.
79
+ 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 brings in the current set of files that go with the newest cut (at most one voice read, one music bed and one sound effects pass, unpicked), leaving the rest in Assets › Found. `rushes_open` returns `broughtIn` (with each file's `origin`), `alreadyIn`, `failed` and `found` (counts by kind, called `counts` by `rushes_scan`), and waits about 20 seconds, answering `scanning: true` if the folder is big. Pass `include` for files you made for this cut — `include: [{ path, kind?, round? }]` — and they come in whatever they score, and win over the scoring, for that cut, on later scans too. `rushes_open` also takes `film`. `rushes_scan` (CLI `rushes scan`) looks again, also brings in the current set, and lists the candidates left, with reasons; `rushes_bring_in` (CLI `rushes bring-in <file>...`) brings chosen files in (up to 12 files of each kind per call) and refuses any path outside the project folder. Nothing is ever picked. The user reviews the rest in Assets › Found (**Bring in**, **Not these**, **Look again**); a locked Voice, Music or Effects tab shows "14 music files found in this project" with a **Review** button when files of its kind were found.
80
80
 
81
81
  No project to show yet? Run `npx -y rushes demo <folder> --no-browser`, then `rushes_open` with `project: "<folder>"`. The demo builds a complete working example on the user's machine, with a cut, script, voice reads, music and notes already in place. Always pass `--no-browser`: without it the command stays running as the server and never returns.
82
82