better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/creative/creative-social-media-content-calendar.md

@@ -0,0 +1,88 @@
+---
+title: "Social Media Content Calendar — Plan multi-platform social campaigns: briefs to posting"
+sidebar_label: "Social Media Content Calendar"
+description: "Plan multi-platform social campaigns: briefs to posting"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Social Media Content Calendar
+
+Plan multi-platform social campaigns: briefs to posting.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/creative/social-media-content-calendar` |
+| Path | `optional-skills/creative\social-media-content-calendar` |
+| Version | `0.1.0` |
+| Author | Ben Barclay (benbarclay), Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `Social-Media`, `Content-Calendar`, `Campaigns`, `Publishing` |
+| Related skills | [`xurl`](/docs/user-guide/skills/bundled/social-media/social-media-xurl), [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Social Media Content Calendar
+
+Plan a concrete calendar across selected social platforms. This skill owns campaign structure, post briefs, channel adaptation, approvals, and publishing verification; platform skills such as `xurl` own API commands. For platforms without a connector, the verified handoff ends at approved drafts for the user's scheduler — say so rather than claiming publication.
+
+## When to Use
+
+- "Build next month's social calendar."
+- "Turn this launch into posts for X, LinkedIn, Instagram, and TikTok."
+- "Draft and schedule a campaign."
+- "Repurpose these articles/videos into social content."
+
+Don't use for: single one-off posts (use the platform skill directly).
+
+## Procedure
+
+### 1. Define campaign constraints
+
+Record objective, audience, offer/message, platforms, date range, cadence, voice, mandatory/prohibited claims, links, tracking convention, localization, and approval/publishing authority. Done when each proposed post has a clear business purpose.
+
+### 2. Inventory source material
+
+Collect verified product facts, launches, articles, media, testimonials with permission, brand assets, and key dates using `read_file` and `web_extract`. Mark claim owners and expiration. Done when unsupported claims and missing assets are visible.
+
+### 3. Build themes and calendar slots
+
+Create a balanced mix such as education, proof, product, community, event, behind-the-scenes, and conversation. Account for platform cadence and campaign milestones. Done when dates, platforms, themes, and objectives form a coherent calendar rather than duplicate cross-posts.
+
+### 4. Write platform-specific briefs
+
+For each post specify hook, core message, format, copy length, CTA, link, asset dimensions/content, accessibility text, tags/mentions, and success metric. Adapt rather than copy-paste between platforms. Done when a creator can produce the asset without hidden context.
+
+### 5. Draft copy and assets
+
+Load `humanizer` for voice; generate visuals with the `image_generate` tool where assets are needed. Preserve factual claims and shared campaign identity while respecting platform norms. Done when every calendar slot has draft copy and asset status.
+
+### 6. Run editorial and risk review
+
+Check factual accuracy, tone, repetition, rights/permissions, accessibility, disclosures, link destination, date relevance, and crisis sensitivity. Mark `draft`, `needs review`, or `approved`; do not publish from draft. Done when every post has a disposition and owner.
+
+### 7. Schedule or hand off
+
+Present the approval batch. Publish/schedule only approved posts using available platform skills (`xurl` for X); for platforms without a connector, deliver the approved package (copy, assets, timing) for the user's scheduling tool and mark those slots handed-off, not published. Read back scheduled time, account, content preview, and provider post/job ID for anything actually published. Done when the calendar reflects verified publishing or handoff status per slot.
+
+## Pitfalls
+
+- Identical copy on every platform.
+- Filling cadence with low-value repetitive posts.
+- Publishing unverified metrics, testimonials, or future claims.
+- Confusing generated asset completion with scheduled publication.
+- Claiming "scheduled" for platforms where the handoff ended at drafts.
+
+## Verification
+
+- [ ] Every post traces to a campaign objective and a verified claim inventory.
+- [ ] No post was published from `draft` or `needs review` state.
+- [ ] Published slots have provider-confirmed IDs; handed-off slots are marked as such.
+- [ ] Rights, permissions, and disclosures checked before any publish.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/creative/creative-system-atlas.md

@@ -0,0 +1,105 @@
+---
+title: "System Atlas — Build explorable isometric architecture atlases as HTML"
+sidebar_label: "System Atlas"
+description: "Build explorable isometric architecture atlases as HTML"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# System Atlas
+
+Build explorable isometric architecture atlases as HTML.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/creative/system-atlas` |
+| Path | `optional-skills/creative/system-atlas` |
+| Version | `1.0.0` |
+| Author | Harshyt Goel (adapted by Nous Research) |
+| License | MIT |
+| Platforms | linux, macos |
+| Tags | `architecture`, `diagrams`, `isometric`, `documentation` |
+| Related skills | [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# System Atlas Skill
+
+An atlas is one data file (`data.mjs`) that renders two views: an **interactive isometric map** (a single self-contained `atlas.html` — hover to read, click to pin, go inside for steps, moving data packets you can inspect, chapters that reveal the system a few structures at a time), and a **generated text twin** (`SYSTEM.md`) with the decisions table, every structure, the flows, and the open questions by ID. The data file is the only thing anyone edits; both views rebuild from it. It sits beside a hand-written glossary (`CONTEXT.md`) and ADRs.
+
+**Does:** interactive architecture maps with progressive disclosure, question tracking across feedback rounds, a generated text twin, and a repeatable update loop.
+**Doesn't:** static one-off diagrams (use the architecture-diagram or excalidraw skill), finished systems that only need a README, or a single diagram for a PR.
+
+## When to Use
+
+Use whenever someone wants to discuss, design, review, or explain an architecture visually — "make an atlas", "map the system", "make the architecture explorable", "visualize the codebase/agent/pipeline so we can talk about it", "a diagram I can click around", "walk me through how it fits together" — or when an architecture discussion is producing a pile of open questions that need tracking across feedback rounds. Also use it to update an existing atlas after decisions change. Best when the system is new enough that vocabulary, decisions, and questions are still moving and there will be more than one feedback round.
+
+## Prerequisites
+
+- Node.js (any recent version; the build uses only `node:fs`, `node:path`, `node:url` — no npm install needed).
+- A static server for verification (`npx serve` or `python3 -m http.server`).
+
+## How to Run
+
+```bash
+mkdir -p <atlas home>/atlas
+cp <skill>/assets/{template.html,build.mjs} <atlas home>/atlas/
+cp <skill>/assets/data.example.mjs <atlas home>/atlas/data.mjs   # then fill it in
+node <atlas home>/atlas/build.mjs   # writes ../SYSTEM.md and ../atlas.html
+```
+
+Every field of the data file is documented in `assets/data.example.mjs`.
+
+## Quick Reference
+
+| File | Role | Edit it? |
+|---|---|---|
+| `atlas/data.mjs` | Single source of truth: structures, flows, chapters, decisions, questions, prose | Yes |
+| `atlas/template.html` + `atlas/build.mjs` | Renderer + generator | Presentation only |
+| `atlas.html` | Built atlas; republish at the same URL after every rebuild | No (generated) |
+| `SYSTEM.md` | Built text twin | No (generated) |
+| `CONTEXT.md` | Glossary, one line per noun | By hand |
+| `adr/` | Hard-to-reverse decisions | By hand |
+| `research/` | Deep-dive evidence | Append-only |
+
+## Procedure
+
+Follow the order — each step was earned by a correction the first time round.
+
+1. **Read the inputs before drawing.** The vision doc, the repo's existing surfaces, and whatever prior art the user allows (ask — they may forbid a branch or a source). If you will build on a framework, read its docs first; hand long docs to a subagent via `delegate_task` with your specific design questions and have it return a primer with gotchas and a "what it does not give us" list. Drawing before this produces boxes that don't map to anything real.
+2. **Discuss before drawing.** Propose the structure in chat, mapped to the runtime's real primitives, and ask only the questions you cannot derive from the repo. Take defaults for the rest and say which.
+3. **First atlas — the whole system.** Copy `assets/` into the atlas home (rename `data.example.mjs` to `data.mjs`), fill the data, build with `node`, publish. **Where the atlas home is depends on the repo's docs policy** — ask before committing anything. Docs-friendly repos: `docs/<system>/atlas/` in-tree. Repos that commit only ADRs and `CONTEXT.md`: put the atlas, `SYSTEM.md`, and `research/` in a git-ignored scratch dir and attach `SYSTEM.md` + research to the spec issue when published. (Committing the whole set once produced a 3,900-line docs PR and four review rounds reconciling three restatements of one design.) Load the design-md or architecture-diagram skill via skill_view for HTML-artifact guidance if useful; read `references/design-language.md` for the visual rules either way.
+4. **Progressive disclosure.** A whole system at once reads as noise. Ten-ish chapters; each adds at most three structures and runs one small flow that only touches revealed structures; the last chapter shows everything with a flow picker. Unrevealed structures stay in the index, dimmed, with their chapter number. Panels are summary-first: one sentence, then *Read more* and *Steps* folded.
+5. **Shapes and labels.** Letters on boxes are not enough. Give each role a shape and put a readable name label on the canvas under every structure — see design-language.
+6. **Text twin.** `CONTEXT.md` is a glossary and nothing else (the nouns, one line each); ADRs only for decisions that are hard to reverse, surprising without context, and the result of a real trade-off — these two are the in-tree pieces. `SYSTEM.md` is generated and `research/` holds evidence; both live with the atlas (scratch dir or `docs/`, per step 3). Don't open issues unless asked.
+7. **Feedback by question ID.** Every question is `Q-<code><n>` with a state: open (a string), resolved `{q, r}` (answer + date), or routed `{q, to}` (handed to a named next step). Record the user's words. If they call something "not a question", drop it; if they say "I don't get this", explain with a concrete example *before* resolving. After each round: rebuild, republish, update memory.
+8. **Deep dives feed back.** Research with subagents (`delegate_task`) against one shared brief (the interface we own, the requirements that separate candidates, a usage model for cost, a fixed deliverable shape). Write a synthesis with a normalized cost/fit grid. Fold resolutions into the data as `{q, r: '… (from the deep dive, date)'}`. If the user rejects a proposal, sweep *every* file and rewrite — a banner on top of a stale section is not enough.
+9. **Keep it current.** One source, rebuild and republish after every change, never hand-edit generated files, and leave a `README.md` in the docs folder explaining the set (table in `references/process-and-lessons.md`).
+
+## Publishing
+
+`atlas.html` is one self-contained file — no build step, no external assets beyond a Google Fonts stylesheet. Serve the folder with any static server (`npx serve`, `python3 -m http.server`) and hand over the URL, or let the repo's pages host serve the committed file. One URL, republished after every data change, never a second copy. If you keep a stable published URL, put it in `META.artifactUrl` so `SYSTEM.md` links to it.
+
+## Pitfalls
+
+- Keep `<!doctype html>` first and `<meta charset="utf-8">` immediately after — otherwise quirks mode and mojibake arrows.
+- The renderer rebuilds its whole scene on every draw: a stray `render()` in a hover handler detaches the element under the cursor and the browser stops synthesising clicks — the map looks perfect in a screenshot while nothing responds.
+- Some in-app browsers render `file://` as a static snapshot; verify via a static server, not from disk.
+- Never delete a question — resolve or mark it dropped, so IDs stay stable.
+- After every decision, grep the outputs for stale words (`pending`, the old model name, the rejected design) — the person reads everything.
+- Large HTML/JS via shell heredocs is brittle; use `write_file` and keep the data block JSON-serializable.
+
+## Verification
+
+- `node <atlas home>/atlas/build.mjs` exits 0 and writes both `SYSTEM.md` and `atlas.html`.
+- Syntax-check the built script (`new Function(js)`), then open the served page in a real browser at ~1280×800; check a first chapter, a middle chapter, the last chapter, an inside view, and the light theme.
+- Click a structure and confirm the panel says **pinned** and offers *Go inside*; click a packet dot and confirm the payload opens.
+- Every structure has `one`, `what`, `how`, a `short` label, a role `kind`, and its questions; ghosts are marked; chapters exist with per-chapter flows; the last chapter is the whole system.
+- `SYSTEM.md` carries the decisions table, the question index with IDs and states, and the "how this file is maintained" footer.
+- Project memory records the atlas URL, docs paths, locked decisions with dates, what the user rejected and why, and the next step.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/creative/creative-tldraw-offline.md

@@ -0,0 +1,294 @@
+---
+title: "Tldraw Offline — Drive and script tldraw offline canvases with an agent"
+sidebar_label: "Tldraw Offline"
+description: "Drive and script tldraw offline canvases with an agent"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Tldraw Offline
+
+Drive and script tldraw offline canvases with an agent.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/creative/tldraw-offline` |
+| Path | `optional-skills/creative\tldraw-offline` |
+| Version | `1.0.0` |
+| Author | Teknium + Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `tldraw`, `canvas`, `whiteboard`, `document-script`, `diagramming` |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# tldraw offline Skill
+
+Work with the tldraw offline desktop app (offline.tldraw.com): read the open
+canvas, make edits, and write **document scripts** — JavaScript embedded in a
+`.tldraw` file that runs on load and gives the file durable behavior. The app
+runs a **local HTTP API** (default `localhost:7236`) that a coding agent drives
+with plain `curl` from its terminal — this is exactly how the app's own homepage
+demo (Codex editing a canvas live) works. The agent does NOT use computer-use /
+GUI clicking, and does NOT hand-edit the `.tldraw` file directly. Keep tldraw
+offline open while you work.
+
+## When to Use
+
+- The user has tldraw offline open and asks you to build or modify a canvas
+  (diagrams, wireframes, layouts).
+- You want to add durable behavior to a drawing (reactive shapes, interactive
+  buttons, animation, connection logic) via an embedded document script.
+
+Do NOT hand-place shapes to imitate a drawing — write the code that generates
+them. Agents are far better at scripting the canvas than at drawing on it.
+
+## Prerequisites
+
+- **tldraw offline installed and running**, with a document open. Releases:
+  https://github.com/tldraw/tldraw-offline/releases/latest (macOS DMG, Windows
+  x64/Arm64, Linux `x86_64`/`arm64` AppImage or amd64/arm64 `.deb`).
+- **Agent skills installed in the app**: `Develop → Install Agent Skills`. The
+  app writes its own tldraw skill into `~/.codex/skills/`, `~/.claude/skills/`,
+  `~/.cursor/skills/`, and `~/.gemini/skills/` — teaching that agent the `curl`
+  recipes below. (This Hermes skill mirrors that guidance for Hermes.)
+- **The local control API.** On launch the app writes `server.json` to its config
+  dir (Linux `~/.config/tldraw/`, macOS `~/Library/Application Support/tldraw/`,
+  Windows `%APPDATA%\tldraw\`) with `port` (default `7236`), a bearer `token`,
+  `pid`, and `startedAt`. Every request except `GET /` needs
+  `Authorization: Bearer <token>`. A clean quit removes `server.json`; if it's
+  present but the port doesn't answer, the app quit uncleanly — treat as not
+  running.
+- **Re-read port + token on EVERY shell call.** Each terminal call is a fresh
+  shell, so an `export`ed token does not persist — "export once and reuse" sends
+  an empty token and 401s. Read both inline at the top of each call:
+  `PORT=$(jq -r .port <server.json>); TOKEN=$(jq -r .token <server.json>)`.
+- No account or network needed for local editing.
+
+## How to Run
+
+Two distinct workflows. Pick by whether the change must survive a reload.
+
+**A. One-off canvas edits (`/exec`)** — layout, generating shapes, cleanup. This
+is a live edit, not saved script:
+
+```bash
+BASE=http://localhost:7236
+TOKEN=$(python -c "import json;print(json.load(open('$HOME/.config/tldraw/server.json'))['token'])")
+# find the focused document id
+DOC=$(curl -s "$BASE/api/search" -X POST -H 'content-type: application/json' \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"code":"return (await api.getFocusedDoc()).id"}' | python -c "import sys,json;print(json.load(sys.stdin)['result'])")
+# run code with the live `editor` + `helpers` in scope
+curl -s "$BASE/api/doc/$DOC/exec" -X POST -H 'content-type: application/json' \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"code":"const {createShapeId,toRichText}=await import(\"tldraw\"); editor.createShape({id:createShapeId(),type:\"geo\",x:0,y:0,props:{geo:\"rectangle\",w:200,h:100,color:\"blue\",fill:\"solid\",richText:toRichText(\"hello\")}}); return editor.getCurrentPageShapes().length"}'
+```
+
+**B. Durable behavior (`script/main.js`)** — reactive/interactive logic that must
+survive reload. Edit the file on disk; the app's watcher applies it:
+
+```bash
+# get the live script file path for the doc
+curl -s "$BASE/api/doc/$DOC/script-workspace" -X POST \
+  -H "Authorization: Bearer $TOKEN"          # -> result.mainJsPath, result.isDefaultScript
+# edit result.mainJsPath with read_file / patch / write_file (see scripts/main.js)
+# then confirm the watcher applied it:
+curl -s "$BASE/api/doc/$DOC/script-status" -H "Authorization: Bearer $TOKEN"
+```
+
+The ready-to-adapt document script is `scripts/main.js`.
+
+## Quick Reference
+
+The document-script contract (verified against the app's bundled
+`script-context.d.ts`):
+
+```js
+import { createShapeId, toRichText } from 'tldraw'   // primitives: import, not globals
+
+export default function ({ editor, helpers, signal }) {
+  editor.run(() => {                                 // batch = one undo step
+    helpers.createShapeIfMissing({                   // idempotent furniture
+      id: createShapeId('node-1'), type: 'geo', x: 0, y: 0,
+      props: { geo: 'rectangle', w: 200, h: 100, richText: toRichText('hi') },
+    })
+  })
+
+  const stop = editor.store.listen(() => { /* react */ })  // fires the tick AFTER a commit
+  signal.addEventListener('abort', () => stop())           // REQUIRED cleanup on rerun/close
+}
+```
+
+- `ctx.editor` — the live `Editor` (`createShape`, `updateShape`, `deleteShapes`,
+  `getCurrentPageShapes`, `getShape`, `getBindingsFromShape`, `zoomToFit`,
+  `on('tick'|'event', fn)`, `run(fn, { history: 'ignore' })`).
+- `ctx.helpers` — `createShapeIfMissing`, `createShapesIfMissing`,
+  `createArrowBetweenShapes(from, to, { arrowheadEnd })`, `translateShapes`,
+  `onShapeTranslate(id, fn, { signal })`, `richTextToPlainText`, `boxShapes`,
+  `getLints`.
+- `ctx.signal` — `AbortSignal`; attach every listener/interval teardown to it.
+- `config.js` (separate file) registers custom shape/tool/component utils and
+  runs before mount; `main.js` runs against the mounted editor and reruns on save.
+
+## Interactive UI (clickable buttons that drive state)
+
+Drawn shapes can behave like a real app — the thing a static whiteboard can't do.
+Full example: `scripts/counter.js` (a number display + MINUS/RESET/PLUS buttons).
+
+Verification boundary — read this before claiming interaction works or doesn't.
+The app's OWN agent playbook says to verify a clickable-UI script with "one
+simulated click and one state read" via `/exec` (`editor.dispatch` a pointer
+event, await a tick, read the shape's state) — NOT by driving a real mouse. By
+that standard the counter is verified: dispatched clicks stepped it
+`0 → 1 → 2 → 1 → 0`. Two caveats worth writing down:
+- **The script only runs once the app's file-watcher applies it.** On Linux that
+  watcher uses inotify; a host with an exhausted `fs.inotify.max_user_instances`
+  logs `inotify_add_watch ... No space left on device`, `script-status` shows
+  `state: "not-watching"` / `hasEntry: false`, and the script never executes.
+  This is a host limit, not a script bug — a normal desktop is unaffected.
+- **Driving the canvas with computer-use needs FOREGROUND delivery, not
+  background.** cua-driver's default `background` delivery returns
+  `background_unavailable` against Electron's occluded renderer — but that is the
+  first rung, not a wall. cua-driver returns an `escalation: "foreground"` hint;
+  set `delivery_mode: "foreground"` (pair with `bring_to_front`) and its X11 XTest
+  path (`x11_xtest_fg`) clicks land — this dismisses the "Run Script" consent
+  dialog and clicks the canvas. Verified by the Cua team on this exact v1.11.0
+  AppImage (Linux/X11). Do NOT conclude "Electron rejects synthetic clicks" and
+  give up in background mode — climb to foreground. (The real product path is
+  still `/exec`, not clicks; this note is for computer-use-driven testing.)
+
+The pattern:
+
+```js
+export default function ({ editor, helpers, signal }) {
+  // 1. Build buttons idempotently; tag each with meta so the handler finds them.
+  //    Give buttons a visible label AND a meta.action.
+  // 2. Hit-test pointer_down in PAGE coordinates against the button bounds:
+  const inside = (b, p) => p.x >= b.x && p.x <= b.x + b.w && p.y >= b.y && p.y <= b.y + b.h
+  function onEvent(info) {
+    if (!info || info.name !== 'pointer_down') return
+    let p = null
+    try { if (info.point && editor.screenToPage) p = editor.screenToPage(info.point) } catch {}
+    p = p ?? editor.inputs?.currentPagePoint
+    if (!p) return
+    const hit = editor.getCurrentPageShapes().find(
+      (s) => s.meta?.ui === 'button' &&
+        inside({ x: s.x, y: s.y, w: s.props.w, h: s.props.h }, p)
+    )
+    if (hit) runAction(hit.meta.action)   // mutate state; store it in a shape's meta
+  }
+  editor.on('event', onEvent)
+  signal.addEventListener('abort', () => editor.off('event', onEvent))  // REQUIRED
+}
+```
+
+- Find buttons by `meta` (or visible label via `helpers.richTextToPlainText`),
+  not by hard-coded coordinates.
+- **One script owns both build and read.** If the shapes are created by one code
+  path (with `meta.action: 'inc'`) and the handler reads another convention
+  (`meta.action === 'PLUS'`), clicks silently do nothing. Ship the buttons built
+  by the same script that handles them, or ship an empty canvas so the script
+  builds them fresh — never pre-bake mismatched shapes into the file's db.
+- Keep app state in a shape's `meta` (e.g. `meta.count`) and render it as that
+  shape's `richText` label, so it survives save and is readable for verification.
+- **Detach the listener on `signal` abort.** Skipping this is not cosmetic: on
+  the next save the old `onEvent` stays attached alongside the new one, so every
+  click fires twice and a counter jumps by 2 instead of 1.
+- For continuous motion use `editor.on('tick', fn)`; for a moving anchor with
+  attached pieces use `helpers.onShapeTranslate(id, fn, { signal })`.
+
+### Shipping a self-running scripted `.tldraw`
+
+A `.tldraw` is a zip of `metadata.json` + `session.json` + `db.sqlite` + `assets/`
++ `script/` (only those entries are packable). For the script to auto-run without
+the "This document contains a script → Run Script" consent dialog:
+
+- `metadata.json` must carry a `script` manifest: `{ "sha256": "<digest>" }`, where
+  the digest is `sha256` over each sorted `script/` path as `` `${path}\0${sha256hex(bytes)}\n` ``.
+  A mismatch is rejected as tampered.
+- Pre-trust the digest by adding it to `~/.tldraw/script-trust.json`
+  (`{ "trusted": ["<digest>"] }`, or `$TLDRAW_SCRIPT_TRUST`). The app skips consent
+  when `isScriptTrusted(digest)` is true.
+
+## Procedure
+
+1. Read the current token/port from `server.json`. Find the target doc with
+   `api.getFocusedDoc()` (or `api.getDocs()`); name it explicitly if several are
+   open.
+2. For layout/generation, use `/exec`. For durable behavior, edit
+   `script/main.js` via `/script-workspace`.
+3. Make scripts idempotent: create durable shapes with `helpers.createShapeIfMissing`
+   and stable `createShapeId('name')` ids. Scripts rerun on every load.
+4. Keep script-owned writes out of the user's undo stack:
+   `editor.run(fn, { history: 'ignore' })` (or `helpers.translateShapes`, which
+   already does).
+5. For reactivity, `editor.store.listen(cb)` and tear it down on `signal` abort.
+   For interaction, `editor.on('event', h)` (hit-test `pointer_down` in page
+   coords); for animation, `editor.on('tick', h)`.
+6. For a single moving anchor + attached internals, prefer
+   `helpers.onShapeTranslate(anchorId, fn, { signal })` over a broad store
+   listener — a broad listener can turn your own writes into feedback loops.
+
+## Shape props (validated against tldraw SDK v5 schema)
+
+`editor.createShape` / `createShapeIfMissing` accept partial props (shape utils
+fill defaults). When building **raw records** for a file snapshot, every prop
+below is required (run `scripts/validate_shapes.mjs`):
+
+| Shape | Required props |
+|-------|----------------|
+| `note`  | `richText`, `color`, `labelColor`, `size`, `font`, `align`, `verticalAlign`, `growY`, `fontSizeAdjustment`, `url`, `scale`, `textLastEditedBy` |
+| `text`  | `richText`, `color`, `size`, `font`, `textAlign`, `w`, `scale`, `autoSize` |
+| `frame` | `w`, `h`, `name`, `color` |
+| `geo`   | `geo`, `w`, `h`, `color`, `fill`, `richText` (+ dash/size/etc. defaulted) |
+
+`richText` must be `toRichText('...')` — a bare string is rejected. `color` enum:
+`black grey light-violet violet blue light-blue yellow orange green light-green
+light-red red white`. `font` enum: `draw sans serif mono`.
+
+## Pitfalls
+
+- **`store.listen` fires on the tick AFTER a commit, not synchronously.** If you
+  write a shape and immediately read state expecting the listener to have run, it
+  hasn't. Verified live: an in-turn read shows 0 fires; after one `setTimeout`
+  tick it shows 1. Same reason the app notes `editor.dispatch` is async — await a
+  tick before verifying.
+- **`ctx`, not globals.** The entry is `export default function ({ editor,
+  helpers, signal })`. There is no bare `editor` global in a document script.
+  `createShapeId` / `toRichText` / `Vec` come from `import ... from 'tldraw'`.
+- **`richText`, not `text`.** Text/note/geo labels use `richText: toRichText(s)`.
+- **Raw records need every prop; `createShape` does not.** In-app pass only the
+  props you care about; a hand-built `.tldraw` snapshot needs the full set (table).
+- **Scripts rerun on every load — be idempotent.** Use `createShapeIfMissing`
+  with stable ids or you duplicate content and clobber user edits.
+- **Clean up on `signal`.** `signal.addEventListener('abort', () => stop())` for
+  every `store.listen` / `editor.on` / `setInterval`; the signal fires before
+  rerun and on close.
+- **Keep script writes out of undo:** `editor.run(fn, { history: 'ignore' })`.
+- **`editor.on('tick')` pauses when the window is hidden** (it is a RAF loop);
+  `setInterval` keeps firing but Electron throttles it to ~1/s in the background.
+- **The API needs the bearer token** from `server.json`; the port can be non-default
+  (`server.listen(0)` picks one) — always read the file, don't hardcode `7236`.
+- **Only `tldraw` / `react` / `react-dom` import** — not a Node project.
+
+## Verification
+
+- **Shape schema (offline, no app):** `node scripts/validate_shapes.mjs` — builds
+  the real tldraw schema and validates note/text/frame. Passing prints `3/3`.
+- **Live canvas edits:** after `/exec`, read back with `/api/search` →
+  `api.getShapes(docId)` (returns `{ page, viewport, shapes }`) and
+  `api.getBindings(docId)` (array). Confirm expected shapes/bindings exist. Grab
+  `api.getScreenshot(docId)` (returns `{ filePath, ... }`) and inspect the PNG/JPEG
+  with `vision_analyze`.
+- **Durable script applied:** `GET /api/doc/:id/script-status`. Success is
+  `state: "applied"` (`currentDiskDigest === lastAppliedDigest === manifestSha256`,
+  `pendingApply === false`, `lastApplyError === null`). If it stays `"pending"`
+  after a short retry, report that instead of claiming success; `"error"` means
+  the apply failed — read `errorLogPath`.