@marver-design/marver 0.22.1 → 0.23.1

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 (65) hide show
  1. package/CHANGELOG.md +117 -0
  2. package/README.md +14 -10
  3. package/dist/agent-BsieQGTD.mjs +99 -0
  4. package/dist/{bake-CvY8QR3L.mjs → bake-DQtnDB8-.mjs} +1 -1
  5. package/dist/{board-status-CWGHIdo_.mjs → board-status-BZSzc9Hp.mjs} +69 -610
  6. package/dist/boards-BRLnoTC3.mjs +620 -0
  7. package/dist/{boards-BwKI0qWd.mjs → boards-Dv-Ipd8G.mjs} +13 -5
  8. package/dist/{build-B1kavcpc.mjs → build-_ndp_dXn.mjs} +18 -10
  9. package/dist/cli.mjs +20 -11
  10. package/dist/{comments-ClVgfQib.mjs → comments-BlqyZh3D.mjs} +71 -9
  11. package/dist/{config-DJxMRVD8.mjs → config-BUKprFAp.mjs} +5 -97
  12. package/dist/{context-D4t59wDi.mjs → context-CdkNiKdJ.mjs} +3 -2
  13. package/dist/{daemon-PmNqoOAk.mjs → daemon-BvMPdQ3k.mjs} +78 -19
  14. package/dist/{dev-Cf4wLGe2.mjs → dev-Cf-4eqaC.mjs} +50 -10
  15. package/dist/{init-C_K-cjBQ.mjs → init-hfZV7TwY.mjs} +10 -4
  16. package/dist/{ledger-Bu0BjqIe.mjs → ledger-BNXW14Xw.mjs} +1 -6
  17. package/dist/link-BodAbIQz.mjs +132 -0
  18. package/dist/{manifest-CcdWx7ud.mjs → manifest-TpfDWldB.mjs} +56 -6
  19. package/dist/{plugin-C5u07Yhv.mjs → plugin-DoXql0ZZ.mjs} +400 -48
  20. package/dist/{poster-BduzQBYz.mjs → poster-XBmUvQiL.mjs} +1 -1
  21. package/dist/{profile-BjAPAJSb.mjs → profile-CrZohD6g.mjs} +1 -1
  22. package/dist/{publish-bakes-b0jUwvM_.mjs → publish-bakes-KKTHWqq3.mjs} +2 -2
  23. package/dist/{share--bdSc4G5.mjs → share-BD-wcDQq.mjs} +1 -1
  24. package/dist/{shot-BAR8hmU9.mjs → shot-DOD8v6fJ.mjs} +2 -2
  25. package/dist/{shot-BFEuYbaz.mjs → shot-Dh6fV1Lm.mjs} +1 -1
  26. package/dist/{sync-BZaCWqK-.mjs → sync-DoA1vf4u.mjs} +15 -1
  27. package/dist/{work-0YopuMt9.mjs → work-ClFFq0Qh.mjs} +9 -3
  28. package/dist/{work-CLrmY-vQ.mjs → work-ayuL_9Kk.mjs} +72 -1
  29. package/docs/boards-and-folders.md +60 -7
  30. package/docs/context.md +10 -2
  31. package/docs/live-jam.md +11 -0
  32. package/docs/sticky-notes.md +1 -1
  33. package/package.json +1 -1
  34. package/src/client/content/diagram.tsx +7 -1
  35. package/src/client/content/img-lod.ts +12 -2
  36. package/src/client/content/index.tsx +73 -6
  37. package/src/client/content/md.ts +3 -2
  38. package/src/client/frame-host/inspect.js +23 -0
  39. package/src/client/shell/App.tsx +21 -10
  40. package/src/client/shell/BoardList.tsx +26 -6
  41. package/src/client/shell/LockedApp.tsx +2 -2
  42. package/src/client/shell/Play.tsx +5 -1
  43. package/src/client/shell/StatusPicker.tsx +12 -5
  44. package/src/client/shell/Tip.tsx +25 -5
  45. package/src/client/shell/board-icons.tsx +15 -1
  46. package/src/client/shell/canvas/Canvas.tsx +42 -6
  47. package/src/client/shell/canvas/anchor.ts +41 -0
  48. package/src/client/shell/canvas/ctl.ts +6 -0
  49. package/src/client/shell/comments-store.ts +8 -5
  50. package/src/client/shell/goto.ts +52 -3
  51. package/src/client/shell/hash.ts +24 -3
  52. package/src/client/shell/store.ts +261 -36
  53. package/src/client/shell/styles.css +20 -2
  54. package/src/client/shell/tidy.ts +34 -3
  55. package/src/shared/board-types.ts +10 -6
  56. package/src/shared/frames.ts +3 -0
  57. package/src/shared/status.ts +17 -8
  58. package/templates/AGENTS-embedded.md +43 -8
  59. package/templates/AGENTS-studio.md +43 -8
  60. package/templates/instructions/boards.md +13 -3
  61. package/templates/instructions/context.md +6 -2
  62. package/templates/instructions/iterate.md +29 -16
  63. package/templates/instructions/jam.md +9 -2
  64. package/templates/instructions/reference/deck-layouts.md +2 -1
  65. package/templates/instructions/reference/deck-story.md +2 -1
@@ -21,6 +21,19 @@ export interface BoardLayout extends Flow { scenes?: Record<string, Flow> }
21
21
  export type Warn = (msg: string) => void
22
22
 
23
23
  const isSpace = (x: unknown): x is Space => !!x && typeof x === 'object' && !Array.isArray(x)
24
+ /** Drop the items `isGone` names, each with the spacer that led into it (or, at the start, the
25
+ * one that followed it) - what is left reads as if the item was never there. */
26
+ function dropGone<T>(items: T[], isGone: (x: T) => boolean): T[] {
27
+ const out: T[] = []
28
+ let skip = false
29
+ for (const it of items) {
30
+ if (isGone(it)) { if (isSpace(out[out.length - 1])) out.pop(); else if (!out.length) skip = true; continue }
31
+ if (skip && isSpace(it)) { skip = false; continue }
32
+ skip = false
33
+ out.push(it)
34
+ }
35
+ return out
36
+ }
24
37
  const units = (s: Space, warn: Warn): number =>
25
38
  Number.isInteger(s.space) && s.space > 0 ? s.space : (warn(`invalid space ${JSON.stringify(s.space)} - using 1`), 1)
26
39
 
@@ -268,7 +281,9 @@ function layoutScene(scene: string, members: TidyNode[], flow: Flow | undefined,
268
281
  * array is never reordered (iframe law G-1). Two passes: each scene lays out its
269
282
  * frames (recipe or default lane), then the board flow places the scene boxes.
270
283
  */
271
- export function tidy(nodes: TidyNode[], layout?: BoardLayout, warn: Warn = () => {}): Placed[] {
284
+ /** `known`: every scene of the project. A layout naming a known scene with no node on this board
285
+ * (an empty phase scene, frames not pinned here) skips it quietly; only an unknown name warns (#18). */
286
+ export function tidy(nodes: TidyNode[], layout?: BoardLayout, warn: Warn = () => {}, known?: ReadonlySet<string>): Placed[] {
272
287
  const scenes = [...new Set(nodes.map((n) => n.scene))]
273
288
 
274
289
  // pass 1: per-scene relative layouts + bounding boxes
@@ -300,7 +315,23 @@ export function tidy(nodes: TidyNode[], layout?: BoardLayout, warn: Warn = () =>
300
315
  // PLAIN tidy (default trailing lanes), never a silent pick
301
316
  let boardFlow: Flow
302
317
  if (layout && layout.rows && layout.columns) { warn('layout has rows AND columns - ignoring it (plain tidy)'); boardFlow = { rows: [] } }
303
- else if (layout && (layout.rows || layout.columns)) boardFlow = { rows: layout.rows, columns: layout.columns }
318
+ else if (layout && (layout.rows || layout.columns)) {
319
+ // #18: a known scene with nothing on this board (an empty phase scene) leaves the recipe
320
+ // with the spacer that went with it, so the rest lays out as if it was never named - quietly
321
+ const gone = (a: unknown) => typeof a === 'string' && !!known?.has(a) && !sceneBoxes.has(a)
322
+ const prune = (flow?: Array<Lane | Space>) => {
323
+ if (!flow || !known) return flow
324
+ const emptied = new Set<unknown>()
325
+ const lanes = flow.map((e) => {
326
+ if (!Array.isArray(e) || !e.some(gone)) return e
327
+ const kept = dropGone(e, gone)
328
+ if (kept.every(isSpace)) emptied.add(kept)
329
+ return kept
330
+ })
331
+ return dropGone(lanes, (e) => emptied.has(e))
332
+ }
333
+ boardFlow = { rows: prune(layout.rows), columns: prune(layout.columns) }
334
+ }
304
335
  else boardFlow = { rows: [] } // default: every scene its own trailing lane (alphabetical)
305
336
 
306
337
  const listed = new Set<string>()
@@ -315,7 +346,7 @@ export function tidy(nodes: TidyNode[], layout?: BoardLayout, warn: Warn = () =>
315
346
  boardFlow,
316
347
  (atom) => {
317
348
  const b = sceneBoxes.get(atom)
318
- if (!b) warn(`unknown scene "${atom}" in layout - skipped`)
349
+ if (!b && !known?.has(atom)) warn(`unknown scene "${atom}" in layout - skipped`)
319
350
  return b ?? null
320
351
  },
321
352
  trailing,
@@ -56,18 +56,22 @@ export const PROPOSED_PUBLISH: Partial<Record<BoardType, 'slides' | 'refs' | 'do
56
56
  export const HAS_STATUS: readonly BoardType[] = ['feature', 'project']
57
57
 
58
58
  /** The decisions a board may state by hand. `done` is never one: Done comes only from the shipped
59
- * record. `todo`, `backlog` and `in-progress` count only where there is no `context/`. */
59
+ * record. `todo`, `backlog`, `in-progress` and `building` count only where there is no `context/`. */
60
60
  export const DECISIONS = ['archived', 'paused', 'blocked'] as const
61
- export const BY_HAND = ['in-progress', 'todo', 'backlog'] as const
61
+ export const BY_HAND = ['in-progress', 'building', 'todo', 'backlog'] as const
62
62
  export const STATUS_WORDS = [...DECISIONS, ...BY_HAND, 'done'] as const
63
63
  export type StatusWord = (typeof STATUS_WORDS)[number]
64
64
  export const readStatusWord = (v: unknown): StatusWord | undefined =>
65
65
  (STATUS_WORDS as readonly string[]).includes(v as string) ? (v as StatusWord) : undefined
66
66
  /** The statuses a person may set on a feature or project board, in the order a picker lists them:
67
- * the three decisions always; Backlog, To do and In progress only where there is no `context/`
68
- * (with it they are read from the evidence). Never Done - that is the shipped record's alone. */
69
- export const settableStatuses = (contextPresent: boolean): StatusWord[] =>
70
- contextPresent ? ['blocked', 'paused', 'archived'] : ['backlog', 'todo', 'in-progress', 'blocked', 'paused', 'archived']
67
+ * the three decisions always; Backlog, To do, In progress and Building where there is no `context/`
68
+ * (with it they are read from the evidence). With it, In progress and Building where an open plan
69
+ * names the capability - choosing one writes that plan's `stage`, the evidence they are read from.
70
+ * Never Done - that is the shipped record's alone. */
71
+ export const settableStatuses = (contextPresent: boolean, openPlan = false): StatusWord[] =>
72
+ contextPresent
73
+ ? [...(openPlan ? (['in-progress', 'building'] as const) : []), 'blocked', 'paused', 'archived']
74
+ : ['backlog', 'todo', 'in-progress', 'building', 'blocked', 'paused', 'archived']
71
75
 
72
76
  /** A capability slug - the same grammar as a board name, so a feature board and its contract
73
77
  * share it. */
@@ -0,0 +1,3 @@
1
+ /** A canvas made of content frames alone (Doc, Md, Diagram ship their own styling) needs no theme -
2
+ * only an app frame does (#4). Empty counts as not content-only: the warning still helps there. */
3
+ export const contentOnly = (frames: readonly { intent?: string }[]): boolean => frames.length > 0 && frames.every((f) => !!f.intent)
@@ -5,22 +5,23 @@
5
5
  *
6
6
  * 1-3 the board says archived, paused or blocked (with its reason) - a decision, by hand
7
7
  * 4 the evidence it needs cannot be read - Unknown, never a stale Done
8
- * 5 an open plan names the capability - In progress, filling by phase
8
+ * 5 an open plan names the capability - Building when it says `stage: build`,
9
+ * else In progress, filling by phase
9
10
  * 6 the shipped record shows it available, `confirmed` - Done
10
11
  * 7 ... `reported` only - Done, reported
11
12
  * 8 an accepted contract (`state: current`), no availability - To do
12
13
  * 9 anything else - Backlog
13
14
  *
14
- * Without `context/`, a board may also say in-progress, todo or backlog by hand. Done is never
15
+ * Without `context/`, a board may also say in-progress, building, todo or backlog by hand. Done is never
15
16
  * set by hand: `"status": "done"` is ignored here and reported by `marver context check`.
16
17
  */
17
18
  import { DECISIONS, HAS_STATUS, type BoardType, type StatusWord } from './board-types.ts'
18
19
  import { strictest, type Audience, type Level } from './context.ts'
19
20
 
20
- export type Status = 'archived' | 'paused' | 'blocked' | 'unknown' | 'in-progress' | 'done' | 'done-reported' | 'todo' | 'backlog'
21
+ export type Status = 'archived' | 'paused' | 'blocked' | 'unknown' | 'in-progress' | 'building' | 'done' | 'done-reported' | 'todo' | 'backlog'
21
22
  export const STATUS_LABEL: Record<Status, string> = {
22
23
  archived: 'Archived', paused: 'Paused', blocked: 'Blocked', unknown: 'Unknown', 'in-progress': 'In progress',
23
- done: 'Done', 'done-reported': 'Done, reported', todo: 'To do', backlog: 'Backlog',
24
+ building: 'Building', done: 'Done', 'done-reported': 'Done, reported', todo: 'To do', backlog: 'Backlog',
24
25
  }
25
26
 
26
27
  /** A phase, as the fill reads it: 1 spec, 2 lo-fi, 3 hi-fi. */
@@ -37,8 +38,8 @@ export interface ContextFacts {
37
38
  shipped: Map<string, { levels: Level[]; where: string; audience: Audience }>
38
39
  /** capability -> its contract's state, where, and its audience */
39
40
  contracts: Map<string, { state: string; where: string; audience: Audience }>
40
- /** capability -> its open plans, each with its audience */
41
- plans: Map<string, { where: string; audience: Audience }[]>
41
+ /** capability -> its open plans, each with its audience - and `stage: 'build'` once its code is underway */
42
+ plans: Map<string, { where: string; audience: Audience; stage?: 'build' }[]>
42
43
  }
43
44
  export const NO_CONTEXT: ContextFacts = { present: false, unreadable: new Map(), shipped: new Map(), contracts: new Map(), plans: new Map() }
44
45
 
@@ -107,6 +108,7 @@ export function resolveStatus(b: BoardInput, ctx: ContextFacts): StatusResult |
107
108
  const f = fillOf(capability, b.scenes)
108
109
  return out('in-progress', 5, [`design/boards/${b.name}.json: by hand`, ...f.evidence], strictest('publishable', ...f.audience), f.fill)
109
110
  }
111
+ if (b.status === 'building') return out('building', 5, [`design/boards/${b.name}.json: by hand`], 'publishable')
110
112
  if (b.status === 'todo') return out('todo', 8, [`design/boards/${b.name}.json: by hand`], 'publishable')
111
113
  return out('backlog', 9, [b.status === 'backlog' ? `design/boards/${b.name}.json: by hand` : 'no context/ - nothing records it'], 'publishable')
112
114
  }
@@ -118,9 +120,16 @@ export function resolveStatus(b: BoardInput, ctx: ContextFacts): StatusResult |
118
120
  const row = ctx.shipped.get(capability)
119
121
  const live = row?.levels.includes('confirmed') ? 'confirmed' : row?.levels.includes('reported') ? 'reported' : null
120
122
 
121
- // 5: an open plan - work on a shipped capability is version two being built, and says so
123
+ // 5: an open plan - work on a shipped capability is version two being built, and says so. A plan
124
+ // whose code is underway (`stage: build`) makes it Building: the design agreed, the code being written
122
125
  const plans = ctx.plans.get(capability)
123
126
  if (plans?.length) {
127
+ const building = plans.filter((p) => p.stage === 'build')
128
+ if (building.length) {
129
+ const ev = building.map((p) => `${p.where}: stage build`)
130
+ if (live && row) ev.push(`${row.where}: available, \`${live}\` - this is the next version`)
131
+ return out('building', 5, ev, strictest(...building.map((p) => p.audience), ...(live && row ? [row.audience] : [])))
132
+ }
124
133
  const f = fillOf(capability, b.scenes)
125
134
  const ev = [...plans.map((p) => `${p.where}: an open plan`), ...f.evidence]
126
135
  if (live && row) ev.push(`${row.where}: available, \`${live}\` - this is the next version`)
@@ -154,4 +163,4 @@ export function publishableStatus(r: { status: Status; row?: number; fill?: Phas
154
163
  return { status: r.status, ...(r.fill ? { fill: r.fill } : {}) }
155
164
  }
156
165
  /** The statuses rows 5-9 produce - the only ones a published canvas may show. */
157
- export const PUBLISHABLE: ReadonlySet<Status> = new Set(['in-progress', 'done', 'done-reported', 'todo', 'backlog'])
166
+ export const PUBLISHABLE: ReadonlySet<Status> = new Set(['in-progress', 'building', 'done', 'done-reported', 'todo', 'backlog'])
@@ -89,19 +89,50 @@ planning. The human should see the request land on the canvas within the first m
89
89
  JSON - adding is always yours, only rearranging belongs to the shell; auto boards pick
90
90
  new frames up on their own). Changing existing frames only? Skip this step.
91
91
  2. **Light them up**: `npx marver work start <scene/frame ...>` - each frame wears the
92
- live working shimmer. Only now do research, discovery, and planning begin - under a
93
- lit frame, never before one.
94
- 3. Build. Independent frames can go in parallel - one subagent per frame, each marking
92
+ live working shimmer, and its board's icon in the sidebar. Only now do research,
93
+ discovery, and planning begin - under a lit frame, never before one.
94
+ 3. **Make the board's status true.** The glow says someone is on it now; the status says
95
+ where it stands when nobody is - so a feature or project board you work on never stays
96
+ Backlog or To do. With `context/`: an open plan in `context/plans/` names its capability -
97
+ In progress. None does? Write one, in the form of the plans already there - it opens with
98
+ front matter (`---`, `state: proposed`, `capability: <slug>`, `---`), then what you are
99
+ building and why, a few lines; a plan without front matter leaves every status Unknown.
100
+ Once its code starts, add `stage: build` to that front matter - Building. No `context/`:
101
+ once the human has answered the context line, `"status": "in-progress"` (or `"building"`)
102
+ on the board. `work start` names any board still behind; `npx marver boards` shows every
103
+ status.
104
+ 4. Build. Independent frames can go in parallel - one subagent per frame, each marking
95
105
  its own; frames that depend on one another go in order.
96
- 4. **Look before you say done**: `npx marver shot --scene <scene>` (or `<scene/frame ...>`,
106
+ 5. **Look before you say done**: `npx marver shot --scene <scene>` (or `<scene/frame ...>`,
97
107
  `--all`) renders the frames headless in one go - one PNG path per line - and you READ
98
108
  the PNGs. No shell? instructions/jam.md has the file-drop way (`{"scene":"..."}`).
99
- 5. **Clear as you finish**: `npx marver work done <scene/frame ...>` (or `--all`). Marks
109
+ 6. **Clear as you finish**: `npx marver work done <scene/frame ...>` (or `--all`). Marks
100
110
  self-expire (default 10 min; `--ttl <min>` up to 30) - re-run `start` on long jobs,
101
- and never lean on expiry instead of `done`.
111
+ and never lean on expiry instead of `done`. `done` prints the canvas link to the
112
+ frames it cleared (`on the canvas: ...`).
102
113
 
103
- Report where the request came from: chat requests get chat replies; only comment-born
104
- (`@marver`) work replies in its thread.
114
+ ## Hand it back on the canvas
115
+
116
+ The human reviews on the canvas, not in the chat - so the reply puts them there:
117
+
118
+ - **Every reply in which you created or changed frames ends with their canvas link**, on its
119
+ own line: the `on the canvas:` line `work done` printed, or `npx marver link <scene/frame |
120
+ scene ...>` for any set. It opens the board they sit on with them selected and in view -
121
+ the human finds the work at once on a board of fifty frames. Never a full-screen focus link
122
+ (`#/f/...`) unless they ask for full screen. No `marver dev` running? End with
123
+ `npx marver dev` instead - the link carries its port.
124
+ - **Answer each comment thread you addressed, in the thread**: `npx marver comments reply
125
+ <thread> --body "<what changed>"` - one line, no longer than their comment. On a thread
126
+ the human started it posts as Marver and pings them on the frame.
127
+ - **A question or a decision about a frame goes ON that frame**, not only in the chat:
128
+ `npx marver comments new <scene/frame> --body "..." [--on "<words on screen>"]` pins it where
129
+ it applies, so the human answers in place. Also for a judgment call you took that they should
130
+ check, or a change they would not spot. Nothing else - never a changelog, at most one note per
131
+ frame per turn; the chat keeps the summary and can say "question on the form". Never resolve
132
+ your own notes: the human resolves them as they review, and a reply in one comes back to you
133
+ (Live Jam).
134
+ - A comment-born (`@marver`) job hands back through its reply block alone
135
+ (instructions/jam.md): no link, no CLI reply to its own thread.
105
136
 
106
137
  ## Frames
107
138
  - A frame = one file: design/scenes/<scene>/<name>.tsx or .html. One frame, one surface.
@@ -198,6 +229,10 @@ Report where the request came from: chat requests get chat replies; only comment
198
229
  - The screen already lives in src/features/. Implementation wires routes, data, and handlers
199
230
  into the same component - fixtures are the only thing replaced. The frame stays, so the
200
231
  canvas remains living documentation of every screen and state.
232
+ - **The feature board turns Building** (blue) when its code starts: write `stage: build` in the
233
+ front matter of the open plan in `context/plans/` that names the capability - write the plan if
234
+ none does. No `context/`: `"status": "building"` on the board. Done still comes only from
235
+ `context/shipped.md`, when it ships.
201
236
 
202
237
  ## Boards (curated canvases)
203
238
 
@@ -89,19 +89,50 @@ planning. The human should see the request land on the canvas within the first m
89
89
  JSON - adding is always yours, only rearranging belongs to the shell; auto boards pick
90
90
  new frames up on their own). Changing existing frames only? Skip this step.
91
91
  2. **Light them up**: `npx marver work start <scene/frame ...>` - each frame wears the
92
- live working shimmer. Only now do research, discovery, and planning begin - under a
93
- lit frame, never before one.
94
- 3. Build. Independent frames can go in parallel - one subagent per frame, each marking
92
+ live working shimmer, and its board's icon in the sidebar. Only now do research,
93
+ discovery, and planning begin - under a lit frame, never before one.
94
+ 3. **Make the board's status true.** The glow says someone is on it now; the status says
95
+ where it stands when nobody is - so a feature or project board you work on never stays
96
+ Backlog or To do. With `context/`: an open plan in `context/plans/` names its capability -
97
+ In progress. None does? Write one, in the form of the plans already there - it opens with
98
+ front matter (`---`, `state: proposed`, `capability: <slug>`, `---`), then what you are
99
+ building and why, a few lines; a plan without front matter leaves every status Unknown.
100
+ Once its code starts, add `stage: build` to that front matter - Building. No `context/`:
101
+ once the human has answered the context line, `"status": "in-progress"` (or `"building"`)
102
+ on the board. `work start` names any board still behind; `npx marver boards` shows every
103
+ status.
104
+ 4. Build. Independent frames can go in parallel - one subagent per frame, each marking
95
105
  its own; frames that depend on one another go in order.
96
- 4. **Look before you say done**: `npx marver shot --scene <scene>` (or `<scene/frame ...>`,
106
+ 5. **Look before you say done**: `npx marver shot --scene <scene>` (or `<scene/frame ...>`,
97
107
  `--all`) renders the frames headless in one go - one PNG path per line - and you READ
98
108
  the PNGs. No shell? instructions/jam.md has the file-drop way (`{"scene":"..."}`).
99
- 5. **Clear as you finish**: `npx marver work done <scene/frame ...>` (or `--all`). Marks
109
+ 6. **Clear as you finish**: `npx marver work done <scene/frame ...>` (or `--all`). Marks
100
110
  self-expire (default 10 min; `--ttl <min>` up to 30) - re-run `start` on long jobs,
101
- and never lean on expiry instead of `done`.
111
+ and never lean on expiry instead of `done`. `done` prints the canvas link to the
112
+ frames it cleared (`on the canvas: ...`).
102
113
 
103
- Report where the request came from: chat requests get chat replies; only comment-born
104
- (`@marver`) work replies in its thread.
114
+ ## Hand it back on the canvas
115
+
116
+ The human reviews on the canvas, not in the chat - so the reply puts them there:
117
+
118
+ - **Every reply in which you created or changed frames ends with their canvas link**, on its
119
+ own line: the `on the canvas:` line `work done` printed, or `npx marver link <scene/frame |
120
+ scene ...>` for any set. It opens the board they sit on with them selected and in view -
121
+ the human finds the work at once on a board of fifty frames. Never a full-screen focus link
122
+ (`#/f/...`) unless they ask for full screen. No `marver dev` running? End with
123
+ `npx marver dev` instead - the link carries its port.
124
+ - **Answer each comment thread you addressed, in the thread**: `npx marver comments reply
125
+ <thread> --body "<what changed>"` - one line, no longer than their comment. On a thread
126
+ the human started it posts as Marver and pings them on the frame.
127
+ - **A question or a decision about a frame goes ON that frame**, not only in the chat:
128
+ `npx marver comments new <scene/frame> --body "..." [--on "<words on screen>"]` pins it where
129
+ it applies, so the human answers in place. Also for a judgment call you took that they should
130
+ check, or a change they would not spot. Nothing else - never a changelog, at most one note per
131
+ frame per turn; the chat keeps the summary and can say "question on the form". Never resolve
132
+ your own notes: the human resolves them as they review, and a reply in one comes back to you
133
+ (Live Jam).
134
+ - A comment-born (`@marver`) job hands back through its reply block alone
135
+ (instructions/jam.md): no link, no CLI reply to its own thread.
105
136
 
106
137
  ## Frames
107
138
  - A frame = one file: design/scenes/<scene>/<name>.tsx or .html. One frame, one surface.
@@ -198,6 +229,10 @@ Report where the request came from: chat requests get chat replies; only comment
198
229
  - Move the screen from design/screens/ into the app (src/features/...), replace fixture
199
230
  props with live data/handlers, replace data-goto with the router's navigation.
200
231
  - Leave the frame in place, importing from its new home, so the canvas stays true.
232
+ - **The feature board turns Building** (blue) when its code starts: write `stage: build` in the
233
+ front matter of the open plan in `context/plans/` that names the capability - write the plan if
234
+ none does. No `context/`: `"status": "building"` on the board. Done still comes only from
235
+ `context/shipped.md`, when it ships.
201
236
 
202
237
  ## Boards (curated canvases)
203
238
 
@@ -15,6 +15,12 @@ viewport and lays it out:
15
15
  "nodes": [ { "frame": "checkout-a/cart" }, { "frame": "checkout-b/cart" } ] }
16
16
  ```
17
17
 
18
+ Never write `w`/`h` on a content frame's node (a `Doc`): its height is measured, and
19
+ `design/boards/_sizes.json` - machine-written, committed, never edited by hand - keeps it so
20
+ the board opens at its final size (a board's `laidOut` is the canvas's note of the heights its
21
+ rows were laid out around - leave it too). Commit it with your changes; a merge conflict in it
22
+ is safe to resolve either way.
23
+
18
24
  - **The file name is the board's identity** - what you, `publish.json`, URLs and
19
25
  comment threads address (`board: checkout-compare`). It is a slug
20
26
  (`^[a-z0-9][a-z0-9-]*$`) and never moves on a rename.
@@ -178,11 +184,15 @@ boards fall back to the parent folder's type). Moving a board changes an inherit
178
184
  **Never write `"status": "done"`** - Done comes from `context/shipped.md`, and the check fails it.
179
185
  **No `context/`? Your reply ends with the context line** from design/AGENTS.md ("Before the method")
180
186
  - every feature board reads Backlog until there is one. Only when the human declines may a board
181
- say `"todo"`, `"backlog"` or `"in-progress"` by hand.
187
+ say `"todo"`, `"backlog"`, `"in-progress"` or `"building"` by hand.
182
188
  A person sets the same from the sidebar (right-click, Change status…) - it rewrites only `status`
183
- and `reason`, so re-read a board before you edit it.
189
+ and `reason`; with `context/`, its In progress and Building rewrite the `stage:` line of every open
190
+ plan naming the capability instead (and clear the board's decision). So re-read a board, and its
191
+ plan, before you edit them.
184
192
  - In progress fills by phase: the phase scenes above, or `phase: spec | lofi | hifi` in a scene's
185
- `_brief.md` front matter - never by where a row sits.
193
+ `_brief.md` front matter - never by where a row sits. **Building** (blue) follows it: the design
194
+ agreed, the code underway - `stage: build` in the open plan (instructions/context.md). While you
195
+ work on a board's frames (`marver work start`), its sidebar icon shimmers blue on its own.
186
196
  - `npx marver boards` prints every board's type and status with what decided it.
187
197
 
188
198
  ## The default composition: one horizontal band
@@ -62,6 +62,9 @@ proposed; and `## Availability` pointing at its row in `shipped.md`.
62
62
 
63
63
  - **Behaviour** - update its contract in the same change. A change that leaves behaviour alone says
64
64
  `no-contract-change: <capability> - <why>` in the pull request body.
65
+ - **Work starting on a feature** - an open plan in `plans/` names its capability (In progress on its
66
+ board); `stage: build` in it once the code starts (Building). The board's status is how anyone
67
+ who is not watching knows; never leave a feature you are working on reading Backlog.
65
68
  - **A deploy** - write its row in `shipped.md` with the run that proves it (`playbooks/` usually
66
69
  has the release recipe).
67
70
  - **A decision** - in the project's decision log, numbered, with what it applies to.
@@ -74,8 +77,9 @@ proposed; and `## Availability` pointing at its row in `shipped.md`.
74
77
 
75
78
  Feature and project boards wear a status read from these files (the first that matches wins):
76
79
  the board's own `"status"` - `archived`, `paused`, or `blocked` with a `"reason"`; Unknown when the
77
- evidence cannot be read; In progress when an open plan in `plans/` names the capability (filling by
78
- phase: `<cap>-specs`, `<cap>-lofi`, `<cap>`); Done when `shipped.md` shows it `confirmed` in an
80
+ evidence cannot be read; when an open plan in `plans/` names the capability, Building if the plan
81
+ says `stage: build` (its code is underway - write it as you start implementing), else In progress
82
+ (filling by phase: `<cap>-specs`, `<cap>-lofi`, `<cap>`); Done when `shipped.md` shows it `confirmed` in an
79
83
  availability clause (one per `;`) with no negation or pending word ("nowhere", "not yet", "rolled
80
84
  back", "planned") and no pre-production place (staging, preview, dev, local, testing) unless it also
81
85
  names production; Done, reported when only `reported`; To do when its contract is `state: current`; else Backlog.
@@ -75,13 +75,18 @@ to step 4.
75
75
  ```
76
76
  4. **Now do the round on the live scene**, in place - the snapshot is the
77
77
  before. Keep each anchored element's tag, `data-testid` and visible text
78
- where you can, so pins self-heal; when a change must remove an anchored
79
- element, reply and close that thread FIRST, then make the change (resolve
80
- first, restructure second). Reply per thread with one line: what changed,
81
- and that `v<N>` is on the archive board. Who closes the thread depends on
82
- how the work arrived: from the CLI queue (`comments list --open`), you
83
- resolve with `--addressed-in <scene>/<frame>`; from a comment-born jam job,
84
- you never resolve - the owner does (instructions/jam.md).
78
+ where you can, so pins self-heal. Reply per thread with one line: what
79
+ changed, and that `v<N>` is on the archive board. Who closes the thread
80
+ depends on who started it: a thread the owner started (`comments reply`
81
+ printed "as Marver") stays OPEN - the owner reviews your change on the
82
+ canvas, in the thread, and resolves it; a collaborator's thread (the reply
83
+ printed "in your voice") you resolve with `--addressed-in <scene>/<frame>`;
84
+ from a comment-born jam job you never resolve - the owner does
85
+ (instructions/jam.md). A change that removes an anchored element: a
86
+ collaborator's thread is replied to and resolved FIRST, then the change
87
+ (resolve first, restructure second); the owner's stays open - say in the
88
+ reply what replaced the element (its pin parks at the frame's corner, still
89
+ in view).
85
90
 
86
91
  Never wait for the human to ask for this. They should be able to say "make the
87
92
  cards denser", "drop the sidebar", "try a warmer palette" three times in a row
@@ -140,6 +145,7 @@ the open list as a queue:
140
145
  npx marver comments list --open --json # what needs you (anchors included)
141
146
  npx marver comments reply <thread> --body "…"
142
147
  npx marver comments resolve <thread> --addressed-in <scene/frame>
148
+ npx marver comments new <scene/frame> --body "…" [--on "<words on screen>"] # a note where you need them
143
149
  ```
144
150
 
145
151
  The discipline:
@@ -164,10 +170,14 @@ The discipline:
164
170
  iterate the live frames in place. A single frame going in a new direction:
165
171
  fork a variant (the letter convention) and iterate there - the commented
166
172
  frame stays as the before, your variant is the after.
167
- 4. **Resolve with the receipt.** `--addressed-in <the-new-variant>` records
168
- WHICH frame answered the feedback - the thread becomes an auditable link
169
- from complaint to fix. Reply first when the change deserves a sentence of
170
- explanation; resolve silently only for trivial mechanical fixes.
173
+ 4. **Reply where they look, resolve with the receipt.** Reply in the thread -
174
+ one line, what changed. The owner's own threads stay open after your reply:
175
+ they review the change on the canvas and close it (a resolved thread leaves
176
+ the canvas, and your reply with it). A collaborator's thread, you resolve:
177
+ `--addressed-in <the-new-variant>` records WHICH frame answered the feedback -
178
+ the thread becomes an auditable link from complaint to fix. `comments reply`
179
+ says which it was: "as Marver" (the owner's) or "in your voice" (a
180
+ collaborator's - the voice that reaches them on the published canvas).
171
181
  5. **Never resolve what you didn't address.** Disagree? Reply with your
172
182
  reasoning and leave the thread open - the human closes debates, you close
173
183
  completed work.
@@ -176,9 +186,12 @@ The discipline:
176
186
  frame and the anchors strand (a dead anchor parks the pin at the frame
177
187
  edge; deleting the whole frame strands the thread off-canvas entirely -
178
188
  never lost from the log, but invisible until the frame returns). So: with a
179
- version snapshot taken, edit the live frame and resolve each thread right
180
- after its change, so no pin sits stranded; without one, fork the variant
181
- and iterate THERE, leave the commented frame untouched as the before, and
182
- only once you `resolve --addressed-in <variant>` its threads may it move to
183
- `archive/`. Resolve first, restructure second - never the reverse. Check `comments list --board <b>` (no `--open`) to see resolved
189
+ version snapshot taken, edit the live frame and close out each thread right
190
+ after its change - a collaborator's resolved, the owner's replied to and left
191
+ open for them (step 4 above); without one, fork the variant and iterate
192
+ THERE, leave the commented frame untouched as the before, and only once its
193
+ threads are closed (`resolve --addressed-in <variant>` for a collaborator's;
194
+ the owner's, once the owner has resolved them after your reply naming the
195
+ variant) may it move to `archive/`. Answer first, restructure second - never
196
+ the reverse. Check `comments list --board <b>` (no `--open`) to see resolved
184
197
  threads too; the full history lives in the append-only log and in git.
@@ -184,8 +184,15 @@ tells you which mode you are in - when it says to work on a single agent, do tha
184
184
  `jam.subagents` is off, or your CLI has no subagents to spawn).
185
185
 
186
186
  ## Reading comments without the daemon
187
- `npx marver comments list [<board>]` prints the threads on demand - use it to catch up or answer
188
- a one-off question without the live jam loop.
187
+ `npx marver comments list [--board <board>]` prints the threads on demand - use it to catch up or
188
+ answer a one-off question without the live jam loop.
189
+
190
+ ## Notes Marver pinned from chat
191
+ A chat agent leaves notes on frames it changed (`marver comments new`, design/AGENTS.md "Hand it
192
+ back on the canvas"). The owner's reply in one of those threads is a job like any other - no tag
193
+ needed, the same as a reply to Marver - and the note is the context: it says what was changed
194
+ and what the agent wanted from them. While a chat agent has that frame lit (`marver work start`)
195
+ the job waits, so two agents never edit one file at once.
189
196
 
190
197
  ## When jam misbehaves - diagnose, fix, report upstream
191
198
 
@@ -146,7 +146,8 @@ mode - and default to faithful:
146
146
 
147
147
  - **Faithful** - their order, their words, exactly. You may normalise
148
148
  punctuation and number formats; you may not change a word. Suggested
149
- rewrites go in a comment on the frame, never on the slide.
149
+ rewrites go in a note on the frame (`npx marver comments new <scene/frame>
150
+ --on "<their words>" --body "Suggest: ..."`), never on the slide.
150
151
  - **Editorial** (opt-in) - order kept, copy passed through the slides
151
152
  guide's words: jargon, hedges and filler out; numbers, names and dates
152
153
  verbatim; titles turned into claims where the source supports them.
@@ -82,7 +82,8 @@ one-sentence slides on the canvas) a missing fact is a visible `[PLACEHOLDER:
82
82
  what belongs here]`. In the build, a factual placeholder BLOCKS its slide -
83
83
  answered, or the slide is cut - never filled with plausible prose. Editorial
84
84
  gaps (a tagline, a caption, a transition line) you DO draft, labelled as
85
- proposed in the frame's comment - that is writing, not invention.
85
+ proposed in a note on the frame (`npx marver comments new <scene/frame>`) - that
86
+ is writing, not invention.
86
87
 
87
88
  ## Writing that carries
88
89