@senseihq/emaki-cli 0.0.0-stage → 0.1.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 (102) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +69 -2
  3. package/package.json +44 -4
  4. package/plugin/.claude-plugin/plugin.json +19 -0
  5. package/plugin/PLAYBOOK.md +137 -0
  6. package/plugin/README.md +51 -0
  7. package/plugin/agents/fact-checker.md +28 -0
  8. package/plugin/agents/localizer.md +34 -0
  9. package/plugin/agents/scene-builder.md +43 -0
  10. package/plugin/agents/story-planner.md +42 -0
  11. package/plugin/agents/story-writer.md +34 -0
  12. package/plugin/agents/visual-reviewer.md +33 -0
  13. package/plugin/modules/campaign/README.md +30 -0
  14. package/plugin/modules/campaign/calendar.csv +2 -0
  15. package/plugin/modules/campaign/day-script.template.md +42 -0
  16. package/plugin/modules/posting-desk/README.md +37 -0
  17. package/plugin/skills/emaki/SKILL.md +107 -0
  18. package/plugin/skills/emaki/references/01-interview.md +68 -0
  19. package/plugin/skills/emaki/references/02-architecture.md +69 -0
  20. package/plugin/skills/emaki/references/03-content-model.md +68 -0
  21. package/plugin/skills/emaki/references/04-scene-authoring.md +99 -0
  22. package/plugin/skills/emaki/references/05-voice-and-video.md +97 -0
  23. package/plugin/skills/emaki/references/06-i18n.md +37 -0
  24. package/plugin/skills/emaki/references/07-quality-gates.md +44 -0
  25. package/plugin/skills/emaki/references/08-feedback-loop.md +32 -0
  26. package/plugin/skills/emaki/references/09-publishing.md +14 -0
  27. package/plugin/skills/story-build/SKILL.md +37 -0
  28. package/plugin/skills/story-localize/SKILL.md +24 -0
  29. package/plugin/skills/story-media/SKILL.md +38 -0
  30. package/plugin/skills/story-publish/SKILL.md +36 -0
  31. package/plugin/skills/story-review/SKILL.md +29 -0
  32. package/plugin/templates/brief.md +32 -0
  33. package/plugin/templates/change-request.md +7 -0
  34. package/plugin/templates/changelog.md +4 -0
  35. package/plugin/templates/decisions.md +5 -0
  36. package/plugin/templates/glossary.md +4 -0
  37. package/plugin/templates/item-card.md +34 -0
  38. package/plugin/templates/outline.md +19 -0
  39. package/plugin/templates/review-sheet.md +12 -0
  40. package/plugin/templates/style-guide.md +21 -0
  41. package/plugin/templates/tracker.md +11 -0
  42. package/src/api.js +20 -0
  43. package/src/campaign.js +157 -0
  44. package/src/capture.js +205 -0
  45. package/src/carousel.js +91 -0
  46. package/src/config.js +32 -0
  47. package/src/day-script.js +66 -0
  48. package/src/desk-client.js +37 -0
  49. package/src/desk-plan.js +57 -0
  50. package/src/films.js +152 -0
  51. package/src/http.js +30 -0
  52. package/src/index.js +353 -0
  53. package/src/init.js +110 -0
  54. package/src/media.js +236 -0
  55. package/src/migrate.js +67 -0
  56. package/src/plugin.js +106 -0
  57. package/src/publish.js +118 -0
  58. package/src/stage.js +107 -0
  59. package/src/stories.js +66 -0
  60. package/src/tts.js +290 -0
  61. package/src/upload/instagram.js +34 -0
  62. package/src/upload/youtube.js +90 -0
  63. package/src/util.js +66 -0
  64. package/src/voice.js +295 -0
  65. package/src/youtube-text.js +58 -0
  66. package/templates/content/films/index.json +1 -0
  67. package/templates/content/films/measure-the-right-work/film.json +68 -0
  68. package/templates/content/films/measure-the-right-work/look.css +17 -0
  69. package/templates/content/films/measure-the-right-work/scene-close.json +153 -0
  70. package/templates/content/films/measure-the-right-work/scene-groups.json +99 -0
  71. package/templates/content/films/measure-the-right-work/scene-hook.json +96 -0
  72. package/templates/content/films/measure-the-right-work/scene-pair.json +190 -0
  73. package/templates/content/films/measure-the-right-work/scene-problem.json +162 -0
  74. package/templates/content/films/measure-the-right-work/score.js +19 -0
  75. package/templates/content/films/measure-the-right-work/strings/en.json +50 -0
  76. package/templates/content/films/measure-the-right-work/strings/es.json +50 -0
  77. package/templates/content/films/measure-the-right-work/timing.en.json +24 -0
  78. package/templates/content/films/measure-the-right-work/timing.es.json +24 -0
  79. package/templates/content/films/measure-the-right-work/voice/en/close.m4a +0 -0
  80. package/templates/content/films/measure-the-right-work/voice/en/groups.m4a +0 -0
  81. package/templates/content/films/measure-the-right-work/voice/en/hook.m4a +0 -0
  82. package/templates/content/films/measure-the-right-work/voice/en/pair.m4a +0 -0
  83. package/templates/content/films/measure-the-right-work/voice/en/problem.m4a +0 -0
  84. package/templates/content/films/measure-the-right-work/voice/en.json +7 -0
  85. package/templates/content/films/measure-the-right-work/voice/es/close.m4a +0 -0
  86. package/templates/content/films/measure-the-right-work/voice/es/groups.m4a +0 -0
  87. package/templates/content/films/measure-the-right-work/voice/es/hook.m4a +0 -0
  88. package/templates/content/films/measure-the-right-work/voice/es/pair.m4a +0 -0
  89. package/templates/content/films/measure-the-right-work/voice/es/problem.m4a +0 -0
  90. package/templates/content/films/measure-the-right-work/voice/es.json +7 -0
  91. package/templates/content/logos/brand.svg +1 -0
  92. package/templates/content/site.json +10 -0
  93. package/templates/content/stories/en/measure-the-right-work.json +13 -0
  94. package/templates/content/stories/es/measure-the-right-work.json +13 -0
  95. package/templates/content/stories/index.json +12 -0
  96. package/templates/content/ui/en.json +1 -0
  97. package/templates/content/ui/es.json +1 -0
  98. package/templates/emaki.config.json +67 -0
  99. package/templates/film/look.css +17 -0
  100. package/templates/film/scene-close.json +153 -0
  101. package/templates/film/scene-template.json +71 -0
  102. package/templates/film/score.js +12 -0
@@ -0,0 +1,44 @@
1
+ # Quality gates
2
+
3
+ Every gate ends with evidence the owner can see: a contact sheet, a page screenshot, a validation report, a video.
4
+ Never report something as done that has not been looked at. Use the `visual-reviewer` and `fact-checker` agents for
5
+ an independent pass before showing the owner.
6
+
7
+ ## Gate A · Outline approved
8
+ Catalogue complete; pilot chosen; locales, stack, media scope and roles recorded in `project/decisions.md`.
9
+
10
+ ## Gate B · Theme verified (on the pilot)
11
+ - Brand: logo, colours, fonts, tone match the brief; text contrast ≥ 4.5:1 (3:1 for large text).
12
+ - The article page, story index and player render in every launch locale at 375, 768, 1280 px widths; no
13
+ horizontal scroll; dark mode if in scope.
14
+ - One scene of each kind shown in landscape, portrait and figure.
15
+
16
+ ## Gate C · Approach approved (the pilot story, end to end)
17
+ - Item card fulfilled: the one message is clear in 10 seconds; the punchline is the last thing seen and heard.
18
+ - Scene grammar (04-scene-authoring.md) holds; motion is calm; beats land on words.
19
+ - Layout: nothing overlaps or clips in either orientation; connectors meet edges at centres; repeated cards are the
20
+ same size; text has room in the longest locale.
21
+ - Accuracy: every claim traced to a source; illustrative data labelled.
22
+ - Video (if in scope): durations, loudness, captions, covers per the delivery checklist.
23
+ The pilot's decisions become the **style guide** (`project/style-guide.md`) every later story follows.
24
+
25
+ ## Gate D · Each story (batch build)
26
+ 1. `emaki validate <slug>` passes.
27
+ 2. Contact sheet in each locale reviewed by Claude against the checklist below; fixes applied; sheet re-made.
28
+ 3. Article page screenshot (desktop + mobile) in the default locale.
29
+ 4. The owner reviews in the review sheet; changes go through the feedback loop until approved.
30
+
31
+ ### Per-scene checklist
32
+ - [ ] Head says the idea in ≤ 9 words; sub ≤ 20 words.
33
+ - [ ] The picture shows the idea without the words.
34
+ - [ ] Nothing overlaps, clips, or crowds an edge (40 px margin), in landscape and portrait.
35
+ - [ ] Connectors attach at edge centres; alignment and spacing are even; sizes consistent.
36
+ - [ ] Final frame holds ≥ 1.5 s; the frame at the cover time is the punchline card.
37
+ - [ ] Text fits in every locale; diacritics render correctly in the display face.
38
+ - [ ] Colour use: one accent for what matters; success colour for what's right; no meaning by colour alone.
39
+
40
+ ## Gate E · Release
41
+ - Site builds; every published story prerendered per locale; links, hreflang, sitemap, og images.
42
+ - Accessibility: keyboard (player: ←/→, space, M), focus visible, captions, `prefers-reduced-motion` (figures show
43
+ the final frame, the player doesn't autoplay), alt text for covers, language attributes.
44
+ - Performance: pages ≤ 200 KB JS before media; figures start only when visible; videos lazy-loaded.
@@ -0,0 +1,32 @@
1
+ # Inspect, give feedback, correct
2
+
3
+ The owner and reviewers should never have to describe a fix twice. Make feedback precise, track it, and show the
4
+ result next to the request.
5
+
6
+ ## How reviewers see the work
7
+
8
+ - **Review page**: `/review/<slug>` (or the admin preview) shows the article, the player, and the latest contact
9
+ sheet per locale, with the item card beside it. Without a review route, send the sheet image and the page
10
+ screenshot in chat, plus the dev URL.
11
+ - **Review sheet** (`templates/review-sheet.md`) per story: one row per scene × locale, columns for content,
12
+ look, motion, text; each reviewer marks ✓ or writes a change request.
13
+
14
+ ## Change requests
15
+
16
+ Write each request as `templates/change-request.md`: story, scene, locale, orientation, time (or "final frame"),
17
+ what is wrong, what it should be, severity (blocker / should / nice). Claude restates ambiguous requests in one
18
+ line before changing anything when the fix could go two ways; otherwise it just fixes.
19
+
20
+ ## Applying fixes
21
+
22
+ 1. Group requests by story; fix the data (strings, scene JSON, story body), never by patching a render.
23
+ 2. Re-run `validate`, re-make the sheet (only the affected scenes with `--at`), and look at it.
24
+ 3. Reply per request with the before/after frames and one line on what changed. Mark it done in the review sheet.
25
+ 4. When a fix generalises (a spacing rule, a colour use, a wording rule), add it to `project/style-guide.md` and apply
26
+ it to the other stories in the next batch.
27
+ 5. Text changes after voice was recorded mean re-recording that take: say so and list the takes affected.
28
+
29
+ ## Versioning
30
+
31
+ Commit content changes in small, named commits (`story(<slug>): …`). Tag a story's approved state
32
+ (`<slug>@approved-<date>`). `project/changelog.md` lists what changed per story and why.
@@ -0,0 +1,14 @@
1
+ # Publishing, posting and campaigns
2
+
3
+ - **Site**: prerender every published story per locale; rebuild daily (a scheduled build) so date-gated stories go
4
+ live on their day in the site's time zone. Drafts are visible only in preview/admin.
5
+ - **Posting desk** (`modules/posting-desk/`): private admin with preview, reorder ("make next"), change requests and
6
+ approval bound to a content hash; a scheduled poster publishes approved media to YouTube, Instagram and X. Start
7
+ paused, dry-run, YouTube private. The producing machine stages with `emaki stage <slug>` (and reports
8
+ `emaki stage status`, answers `emaki stage requests` / `emaki stage reply`).
9
+ - **Direct**: `emaki publish youtube|instagram <slug>` (`--verify`, `--dry-run` first) posts without the desk and records
10
+ the link in the stories index.
11
+ - **Campaign** (`modules/campaign/`): a calendar of daily shorts with a day script per day (voice table + channel copy),
12
+ built with the same per-item loop: `emaki campaign shortfilm`, `emaki carousel`, `emaki stage`, `emaki campaign status`.
13
+ - **Analytics**: per story and locale: views, read depth, player starts, sound-on rate, video completion; feed the
14
+ numbers into the next batch's priorities.
@@ -0,0 +1,37 @@
1
+ ---
2
+ name: story-build
3
+ description: >
4
+ This skill should be used when the user asks to "build a story", "build the next item", "make the scenes for
5
+ <topic>", "add a new story", "create the motion for this article", or when the emaki program reaches an
6
+ approved item card. It turns one item card into a story body, a film of JSON scenes, strings, sound and a verified
7
+ contact sheet.
8
+ metadata:
9
+ version: "0.1.0"
10
+ ---
11
+
12
+ # Build one story
13
+
14
+ Input: an approved item card (`project/items/<slug>.md`), the style guide (`project/style-guide.md`, if the pilot is
15
+ done), and the plugin's `skills/emaki/references/04-scene-authoring.md`.
16
+
17
+ 1. **Scaffold**: `emaki new <slug> --scenes <ids> --title "<title>" --date <publish_date>`. Scene
18
+ ids come from the card; `hook` first, `close` last.
19
+ 2. **Story body** (default locale): title, dek, one section per idea scene (same ids), points where the card lists
20
+ steps, captions for figures, takeaway = punchline, takeawaySub = the close sub, sources. Plain, direct sentences.
21
+ 3. **film.json**: `look` (copy the site's), scene `name`, `dur` (voice words ÷ 2.5 + 2 s, at least 6 s; close 5.5),
22
+ `desc` (one sentence each: what the scene shows).
23
+ 4. **Scenes**: for each, write `scene-<id>.json`: board; head (`{{id.eyebrow}}`, `{{id.line}}`, `{{id.sub}}`); the
24
+ artwork from components; tracks timed to the voice line (the head from −0.4 s; each element when the voice names
25
+ it); scene CSS prefixed with the id; the portrait block. Start from the pilot's or the starter's scenes; reuse
26
+ their CSS and patterns. Put every visible word in `strings/<locale>.json`.
27
+ 5. **Close**: copy the starter's close scene; set `close.title` (the punchline) and `close.sub`.
28
+ 6. **Sound**: `score.js` with a note on each beat and the closing chord; no bed.
29
+ 7. **Voice script**: `voice/<locale>.json`, one line per scene, ≤ the scene's speakable time; `say` for hard words.
30
+ 8. **Check**: `emaki validate <slug>` must pass; `emaki sheet <slug>` and Read the
31
+ sheet image. Fix overlaps, clipping, misaligned connectors, uneven sizes, crowded edges, missing portrait fit,
32
+ then re-sheet. Check a mid-animation frame for each key beat with `--at`.
33
+ 9. **Page**: open the article page (dev server) and screenshot desktop and mobile.
34
+ 10. **Report**: the sheet, the page screenshots, one line per scene on what it shows, and anything you assumed. Update
35
+ `project/tracker.md`.
36
+
37
+ Large batches: dispatch the `scene-builder` agent per story with steps 3–8 and the card; do 1–2 and 9–10 yourself.
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: story-localize
3
+ description: >
4
+ This skill should be used when the user asks to "translate the stories", "add Spanish", "localise this story",
5
+ "add a language", or "check the French version". It produces a locale's story bodies, scene strings, voice scripts
6
+ and UI strings, validates every key, and verifies the layout in that language.
7
+ metadata:
8
+ version: "0.1.0"
9
+ ---
10
+
11
+ # Add or update a locale
12
+
13
+ 1. Confirm the locale code (BCP 47) is in `content/site.json` `locales` (add it, plus `rtl` if needed) and that the
14
+ fonts cover its script.
15
+ 2. For each story approved in the default locale, dispatch the `localizer` agent with: the default-locale story body,
16
+ `strings/<default>.json`, `voice/<default>.json`, the style guide's wording rules, and any glossary
17
+ (`project/glossary.md`). It writes `stories/<locale>/<slug>.json`, `strings/<locale>.json`, `voice/<locale>.json`
18
+ with identical keys and scene order, adapting idioms and examples, keeping punchlines short.
19
+ 3. UI strings: `content/ui/<locale>.json` with the same keys as the default.
20
+ 4. `emaki validate` (no missing or unused keys), then `emaki sheet <slug> --locale <locale>`; Read it. Fix
21
+ overflow with wrapping or a `locales.<code>.css` block in the scene, not by shortening the meaning.
22
+ 5. RTL locales: check the page direction, the head placement, and any directional art (arrows, timelines).
23
+ 6. List what needs a native reviewer (legal or regulated wording always does) and record the review status per story
24
+ in `project/tracker.md`. Media for the locale follows with `story-media`.
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: story-media
3
+ description: >
4
+ This skill should be used when the user asks to "record the voiceover", "choose a voice", "set up text to speech", "render the video", "make the Short",
5
+ "build the videos", "fit the timing to the voice", or "make the covers" for a story. It runs voice, fit, render and
6
+ build per locale and checks the delivery list.
7
+ metadata:
8
+ version: "0.1.0"
9
+ ---
10
+
11
+ # Voice, timing, video
12
+
13
+ Prerequisites: ffmpeg, Playwright with Chromium (`npm i -D playwright`), the dev server command in `emaki.config.json`, and a voice
14
+ provider per locale (the `emaki` CLI's TTS providers). Never ask for, print or store a key: providers read them from the environment.
15
+
16
+ 0. **Voice provider.** Run `emaki tts-check`. For each locale without a provider, ask the user with
17
+ AskUserQuestion (one question, these options, recommended first): *Your organisation's cloud platform: Azure,
18
+ Google Cloud or AWS Polly (Recommended when they have one)*, *Piper: free, offline, private (Recommended
19
+ otherwise)*, *Kokoro: free, offline, most natural (heavier install)*, *ElevenLabs or OpenAI (premium)*, plus
20
+ *Recorded by a person* via the free-text option. Then: install what it needs (pip, a Piper voice file for the
21
+ language), list voices (`emaki voices --locale <l> --provider <p>`), let the user pick or recommend one, save it
22
+ with `emaki set-voice --locale <l> --provider <p> --opt voice=…` (or `--opt model=…` for Piper), and make one
23
+ short sample take for approval before voicing a whole story. A provider that is "not ready" because of a missing key:
24
+ tell the user which environment variable to set and stop; do not continue with a different provider silently.
25
+ Draft timing passes may use `--provider macos` or `espeak`; never publish those takes.
26
+ 1. Review `voice/<locale>.json` against the scenes: one line each, spoken length fits, `say` spellings for names.
27
+ 2. `emaki voice <slug> --locale <l>` (or `--only 3,5` to redo takes; `--provider manual` prints the
28
+ recording list for a person). Report each take's length; for manual takes, wait for the files.
29
+ 3. `emaki fit <slug> --locale <l>`; read the table. If a beat must land on a word, retime the
30
+ scene's tracks (and `score.js`) or add a hold in `timing.<l>.json`, then fit again.
31
+ Then `emaki voice-web <slug> --locale <l>` so the site's player and figures speak the same takes (commit the
32
+ `voice/<l>/*.m4a` files and `timing.<l>.json` with the story).
33
+ 4. `emaki render <slug> --locale <l> --o both` (picture + score + covers; the 16:9 cover goes to the
34
+ site's covers folder).
35
+ 5. `emaki build <slug> --locale <l>` (voice, ducked score, -14 LUFS, captions).
36
+ 6. Check the delivery list in `skills/emaki/references/05-voice-and-video.md`: extract frames at the start,
37
+ each scene change and the end with ffmpeg and look at them; confirm durations and captions.
38
+ 7. Report the files (paths under `production/<slug>/<l>/out/`), durations, and anything to re-record.
@@ -0,0 +1,36 @@
1
+ ---
2
+ name: story-publish
3
+ description: >
4
+ This skill should be used when the user asks to "publish", "release the site", "set up posting", "schedule the
5
+ stories", "set up the posting desk", "plan a campaign", or "post the videos". It runs the release checklist, deploys,
6
+ and sets up the optional posting desk and daily campaign modules.
7
+ metadata:
8
+ version: "0.1.0"
9
+ ---
10
+
11
+ # Release and distribution
12
+
13
+ 1. **Release checklist** (`skills/emaki/references/07-quality-gates.md`, Gate E): build, prerender per
14
+ locale, hreflang, sitemap, og images, accessibility, performance. Fix before deploying.
15
+ 2. **Daily rebuild**: a scheduled build so date-gated stories publish on their day in the site's time zone.
16
+ 3. **Posting desk** (only if in scope): follow `modules/posting-desk/README.md`. Ask which identity proxy, database,
17
+ object storage and scheduler the organisation uses; port the reference logic; set it up paused, dry-run,
18
+ YouTube private; test the approval-voids-on-change path; go live one channel at a time with the owner.
19
+ From the producing machine: `emaki stage <slug> --dry-run` (read the posts), then `emaki stage <slug>` (uploads
20
+ the media with its sha256 and stages each channel; a film's text is drafted into
21
+ `content/films/<slug>/post.<locale>.json` on the first run: have the owner read it, then stage again);
22
+ `emaki stage status` keeps the desk's plan current; `emaki stage requests` and
23
+ `emaki stage reply <id> "…" --working|--done` answer the owner's motion requests.
24
+ 4. **Straight to a platform** (no desk; only when the owner asks): `emaki publish youtube|instagram --verify` (names
25
+ the account), `emaki publish <channel> <slug> --dry-run`, show the owner the output, then run it without
26
+ `--dry-run`. YouTube stays `--privacy unlisted` until the owner says public; a film already on YouTube is refreshed
27
+ with `--update <id>`, never uploaded twice. The link goes into `content/stories/index.json`.
28
+ 5. **Campaign** (only if in scope): follow `modules/campaign/README.md`: plan the calendar with the owner, write day
29
+ scripts in batches for approval, `emaki campaign shortfilm <slug>` for each day's Short, build it with
30
+ `story-build` and `story-media` (`--o portrait`), `emaki carousel <slug>`, then `emaki stage <slug>`.
31
+ `emaki campaign status` shows what each day still needs; `emaki campaign posted <slug> --youtube … --x …` records
32
+ links posted by hand.
33
+ 6. Keys: never ask for, print or store one. Name the environment variable that is missing (`STAGER_CLIENT_ID`,
34
+ `STAGER_CLIENT_SECRET`, `MEDIA_URL_SECRET`, `YT_CLIENT_ID`, `YT_CLIENT_SECRET`, `YT_REFRESH_TOKEN`, `IG_USER_ID`,
35
+ `IG_ACCESS_TOKEN`) and stop until the owner has set it.
36
+ 7. Record what was released in `project/changelog.md` and hand over the runbook (how to add a story, approve, post).
@@ -0,0 +1,29 @@
1
+ ---
2
+ name: story-review
3
+ description: >
4
+ This skill should be used when the user gives feedback on a story ("scene 2 the cards overlap", "make the title
5
+ shorter", "the arrow is off"), asks to "review the stories", "inspect the batch", "check the scenes", or attaches a
6
+ filled review sheet. It inspects stories against the quality gates, turns feedback into change requests, applies
7
+ them in the data, and shows before/after evidence.
8
+ metadata:
9
+ version: "0.1.0"
10
+ ---
11
+
12
+ # Inspect, correct, show
13
+
14
+ 1. **Collect**: turn each piece of feedback into a change request (story, scene, locale, orientation, time, problem,
15
+ wanted, severity) in `project/reviews/<slug>.md`. Restate a request in one line only when it could be fixed two
16
+ different ways; otherwise proceed.
17
+ 2. **Locate**: map the scene name the reviewer used to its id (film.json `name`), and find the component(s). When
18
+ geometry is involved, measure: open the capture page with Playwright and read element boxes (getBoundingClientRect
19
+ relative to the stage) rather than guessing coordinates.
20
+ 3. **Fix in the data**: scene JSON (positions, sizes, tracks, CSS), strings, story body. Keep shared rules shared: if
21
+ a fix is a rule (centre connectors on edges; equal card sizes; more space under column headers), apply it to
22
+ similar scenes and add it to `project/style-guide.md`.
23
+ 4. **Verify**: `emaki validate`, then `emaki sheet <slug> --at <scene>:<t>` for the affected scenes, in each
24
+ affected locale and both orientations. Read the image; if it is not right, fix again before replying.
25
+ 5. **Reply** per request: the after frame (and the before frame when useful), one line on what changed, and any
26
+ knock-on work (a voice take to re-record, a render to redo). Mark requests done in the review file and the tracker.
27
+ 6. For an inspection without feedback: run the per-scene checklist in
28
+ `skills/emaki/references/07-quality-gates.md` over every scene's sheet, plus the `visual-reviewer` agent,
29
+ and report findings ranked by severity before fixing.
@@ -0,0 +1,32 @@
1
+ # Project brief
2
+
3
+ **Site:** <name> · <url> · owner: <name, role> · start: <date>
4
+
5
+ ## Purpose and audience
6
+ - Purpose: <learning portal / awareness or alert site / product explainers / onboarding>
7
+ - Readers: <who>, on <devices>, arriving from <email / LMS / social / search>
8
+ - Success looks like: <measurable outcome>
9
+
10
+ ## Languages
11
+ - Launch: <en, es> · later: <…> · default: <en> · right-to-left: <none>
12
+ - Translation: <Claude drafts, native reviewer approves: name> · voice localised: <yes/no>
13
+
14
+ ## Stack and hosting
15
+ - Framework: <React/Next · Svelte/SvelteKit · Vue/Nuxt · Astro> · hosting: <…> · repo: <…>
16
+
17
+ ## Media scope
18
+ - Stories: <films 60–90 s / shorts 30–60 s / articles only> · video: <16:9, 9:16>
19
+ - Voice: provider <piper / kokoro / azure / google / polly / openai / elevenlabs / recorded> · voice per locale: <en: …, es: …> · sample approved: <date>
20
+ - Posting desk: <yes/no> · campaign: <yes/no>
21
+
22
+ ## Brand and tone
23
+ - Logo: <file> · colours: <…> · fonts: <…> · references: <…>
24
+ - Tone: <plain, direct, …> · reading level: <…> · words/claims to avoid: <…>
25
+
26
+ ## Roles
27
+ | Role | Person | Approves |
28
+ |---|---|---|
29
+ | Owner | | outline, item cards, look, pilot, each story |
30
+ | Subject expert | | facts |
31
+ | Language reviewer (per locale) | | translations |
32
+ | Legal / compliance | | regulated wording |
@@ -0,0 +1,7 @@
1
+ # Change request <slug>-<n>
2
+
3
+ - **Where:** scene <id or name> · locale <xx> · orientation <16:9 / 9:16 / figure / page> · time <s or final frame>
4
+ - **Problem:** <what is wrong, as seen>
5
+ - **Wanted:** <what it should be>
6
+ - **Severity:** blocker | should | nice
7
+ - **Status:** open → fixed (by <who>, <date>; before/after: <paths>) → verified
@@ -0,0 +1,4 @@
1
+ # Changelog
2
+
3
+ | Date | Story | Change | Why |
4
+ |---|---|---|---|
@@ -0,0 +1,5 @@
1
+ # Decisions
2
+
3
+ | # | Date | Decision | Why | Decided by |
4
+ |---|---|---|---|---|
5
+ | 1 | | | | |
@@ -0,0 +1,4 @@
1
+ # Glossary
2
+
3
+ | Term (default locale) | Use | Avoid | <locale>: term |
4
+ |---|---|---|---|
@@ -0,0 +1,34 @@
1
+ # Item card · <slug>
2
+
3
+ **Title:** <working title> · **Format:** film | short | article · **Topic:** <> · **Publish:** <YYYY-MM-DD>
4
+ **Owner/SME:** <> · **Status:** draft | approved
5
+
6
+ ## Audience and objective
7
+ - Audience: <who, what they already know>
8
+ - After this, they will: <know / feel / do, one sentence>
9
+
10
+ ## The one message
11
+ <≤ 20 words>
12
+
13
+ ## Punchline (closing card, cover, takeaway, last voice line)
14
+ <3–9 words> · sub: <one line>
15
+
16
+ ## Scenes
17
+ | # | id | The point (one line) | The picture | Article section | Voice line (draft) |
18
+ |---|---|---|---|---|---|
19
+ | 1 | hook | | | intro | |
20
+ | … | | | | | |
21
+ | n | close | punchline | title + bar + sub, mark right | takeaway | |
22
+
23
+ ## Facts and sources
24
+ | Claim | Source (doc, section, URL) | Verified |
25
+ |---|---|---|
26
+
27
+ ## Call to action and links
28
+ <what the reader should do next>
29
+
30
+ ## Must not say / sensitivities
31
+ <legal wording, claims to avoid>
32
+
33
+ ## Open questions
34
+ - <…>
@@ -0,0 +1,19 @@
1
+ # Outline
2
+
3
+ ## Site map
4
+ - `/<locale>/` home: featured stories, topics
5
+ - `/<locale>/stories` index: filter by topic, search
6
+ - `/<locale>/stories/<slug>` story: header, film player, sections with figures, takeaway, sources, related
7
+ - `/show/<slug>` story player (and the video capture route)
8
+ - <other pages>
9
+
10
+ ## Catalogue
11
+ | # | Slug | Working title | Format | Topic | Priority | Target date | Sources | SME | Status |
12
+ |---|---|---|---|---|---|---|---|---|---|
13
+ | 1 | | | film | | pilot | | | | outline |
14
+
15
+ Status: outline → card drafted → card approved → built → reviewed → approved → localised → media → published.
16
+
17
+ ## Order of work
18
+ - **Pilot:** <slug> (why: exercises <cards, a chart, a flow, a list, the close>)
19
+ - **Batch 1:** <slugs> · **Batch 2:** <slugs> · …
@@ -0,0 +1,12 @@
1
+ # Review · <slug> · round <n>
2
+
3
+ Sheet: <path or link> · Page: <url> · Player: <url> · Video: <path>
4
+
5
+ | Scene | Locale | Orientation | Content | Look | Motion | Text | Notes / change request # |
6
+ |---|---|---|---|---|---|---|---|
7
+ | hook | en | 16:9 | ✓ | ✓ | ✓ | ✓ | |
8
+ | hook | en | 9:16 | | | | | |
9
+
10
+ Article: ✓ / changes · Takeaway: ✓ / changes · Sources: ✓ / changes
11
+
12
+ Decision: approved | changes requested · Reviewer: <name> · Date: <>
@@ -0,0 +1,21 @@
1
+ # Style guide (settled on the pilot; every story follows it)
2
+
3
+ ## Look
4
+ - Board, palette, fonts, the accent's use (what matters), the success colour (what's right).
5
+ - Card style, tag style, connector style, chart style.
6
+
7
+ ## Layout rules
8
+ - Words left (x 110, w ≈ 700); art right (x 880–1820, y 150–830); 40 px margins.
9
+ - Connectors end on edge centres; repeated cards one size; even spacing; column headers ≥ 40 px above items.
10
+
11
+ ## Motion grammar
12
+ - Head arrives at −0.4 s; art builds in the order the voice names it; holds ≥ 1.5 s; camera push 1.00→1.02.
13
+
14
+ ## Words
15
+ - Headlines ≤ 9 words; subs ≤ 20; punchlines 3–9; plain, direct, no hype; glossary terms.
16
+
17
+ ## Sound
18
+ - Action tones only; a note per beat; the closing chord.
19
+
20
+ ## Rules added from reviews
21
+ - <date> <rule> (from change request <id>)
@@ -0,0 +1,11 @@
1
+ # Tracker
2
+
3
+ | Gate | Status | Date | Evidence |
4
+ |---|---|---|---|
5
+ | A · outline approved | | | |
6
+ | B · theme verified | | | |
7
+ | C · pilot approved | | | |
8
+ | E · release | | | |
9
+
10
+ | Slug | Card | Built | Reviewed | Approved | Locales | Media | Published |
11
+ |---|---|---|---|---|---|---|---|
package/src/api.js ADDED
@@ -0,0 +1,20 @@
1
+ // The same steps as the CLI, as functions (for scripts and CI): project() reads emaki.config.json and content/.
2
+ export { project, SIZES, SUFFIX } from './config.js'
3
+ export { manifest, validate, validateFilm, validateStory, newFilm, keysIn } from './films.js'
4
+ export { voice, voiceWeb, fit, build, captions, ttsCheck, setVoice, listVoices, takesFor } from './voice.js'
5
+ export { sheet, render, openSite } from './capture.js'
6
+ export { PROVIDERS, OFFLINE, provider, voiceConfig, TTSError } from './tts.js'
7
+ export { installPlugin, installSkills, installAgents, listSkills, listAgents, parseFrontmatter } from './plugin.js'
8
+ export { init, detectFramework } from './init.js'
9
+ export { migrate } from './migrate.js'
10
+ export { MotionError } from './util.js'
11
+ export { stage, postsFor, pngToJpeg } from './stage.js'
12
+ export { deskClient } from './desk-client.js'
13
+ export { storyFor, storyUrl, filmFiles, recordLinks } from './stories.js'
14
+ export { productionStatus, deskRequests, deskReply, pieceStatus } from './desk-plan.js'
15
+ export { youtube } from './upload/youtube.js'
16
+ export { instagram } from './upload/instagram.js'
17
+ export { publish } from './publish.js'
18
+ export { chapters, mergeDescription, youtubeDescription, scenePlan } from './youtube-text.js'
19
+ export { parseCsv, todayIn, calendarRows, campaignStatus, campaignDue, campaignPosted, shortFilm, campaignCalendar } from './campaign.js'
20
+ export { carousel, carouselSlides, slideHtml } from './carousel.js'
@@ -0,0 +1,157 @@
1
+ // emaki campaign status | shortfilm | posted | due | calendar: a daily series around a theme, from the command line.
2
+ // Sources: <campaign>/calendar.csv (one row per day: the website's date,product,theme,title,status,script or the
3
+ // plugin template's date,day,slug,topic,title,…), <campaign>/days/*.md (the day scripts), content/stories/index.json
4
+ // and <campaign>/published.json (where each piece was posted). <campaign> is emaki.config.json "campaign".
5
+ import { readFileSync, readdirSync, writeFileSync } from 'node:fs'
6
+ import { join, relative } from 'node:path'
7
+ import { SUFFIX } from './config.js'
8
+ import { beatsOf, campaignDir, dayScriptPath, slugOfScript } from './day-script.js'
9
+ import { newFilm } from './films.js'
10
+ import { filmFiles, recordLinks, storiesIndex, storyUrl } from './stories.js'
11
+ import { die, exists, load, save } from './util.js'
12
+
13
+ /** Rows of a CSV with a header line, as objects. Quoted fields may hold commas, newlines and "" quotes. */
14
+ export function parseCsv(text) {
15
+ const rows = []
16
+ let row = [], cell = '', quoted = false
17
+ for (let i = 0; i < text.length; i++) {
18
+ const c = text[i]
19
+ if (quoted) {
20
+ if (c === '"' && text[i + 1] === '"') { cell += '"'; i++ }
21
+ else if (c === '"') quoted = false
22
+ else cell += c
23
+ } else if (c === '"') quoted = true
24
+ else if (c === ',') { row.push(cell); cell = '' }
25
+ else if (c === '\n' || c === '\r') {
26
+ if (c === '\r' && text[i + 1] === '\n') i++
27
+ row.push(cell); rows.push(row); row = []; cell = ''
28
+ } else cell += c
29
+ }
30
+ if (cell || row.length) { row.push(cell); rows.push(row) }
31
+ const [head = [], ...body] = rows.filter((r) => r.some((x) => x !== ''))
32
+ return body.map((r) => Object.fromEntries(head.map((h, i) => [h.trim(), r[i] ?? ''])))
33
+ }
34
+
35
+ /** Today (YYYY-MM-DD) in a time zone. */
36
+ export const todayIn = (timeZone = 'UTC', now = new Date()) =>
37
+ new Intl.DateTimeFormat('en-CA', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' }).format(now)
38
+ const siteToday = (p) => todayIn(p.site.timeZone ?? 'UTC')
39
+
40
+ /** The calendar, one normalised row per day: { date, topic, theme, title, slug, script (path or null) }. */
41
+ export function calendarRows(p, locale = p.site.defaultLocale) {
42
+ const f = join(campaignDir(p), 'calendar.csv')
43
+ if (!exists(f)) die(`no ${p.rel(f)}; start one from the plugin's modules/campaign/calendar.csv`)
44
+ return parseCsv(readFileSync(f, 'utf-8')).map((r) => {
45
+ const slug = r.slug || (r.script ? slugOfScript(r.script) : null)
46
+ const named = r.script ? join(campaignDir(p), r.script) : null
47
+ const script = named && exists(named) ? named : slug ? dayScriptPath(p, slug, locale) : null
48
+ return { date: r.date, topic: r.product ?? r.topic ?? '', theme: r.theme ?? '', title: r.title ?? '', slug, script }
49
+ })
50
+ }
51
+
52
+ const ledgerPath = (p) => join(campaignDir(p), 'published.json')
53
+ const ledger = (p) => (exists(ledgerPath(p)) ? load(ledgerPath(p)) : {})
54
+ const stories = (p) => new Set((exists(storiesIndex(p)) ? load(storiesIndex(p)) : []).map((e) => e.slug))
55
+ const pngs = (dir) => (exists(dir) ? readdirSync(dir).filter((n) => n.endsWith('.png')).length : 0)
56
+
57
+ /** What is due from a date (default today, in the site's time zone), and for each day what exists. */
58
+ export function campaignStatus(p, { from, days = 14, locale = p.site.defaultLocale } = {}) {
59
+ from ??= siteToday(p)
60
+ const known = stories(p), led = ledger(p)
61
+ return calendarRows(p, locale).filter((r) => r.date >= from).slice(0, Number(days)).map((r) => {
62
+ const s = r.slug, takes = s ? p.prod(s, locale, 'takes') : null, posted = (s && led[s]) || {}
63
+ return {
64
+ date: r.date, topic: r.topic, title: r.title, slug: s,
65
+ story: Boolean(s && known.has(s)), script: Boolean(r.script),
66
+ film: Boolean(s && exists(join(p.films, s, 'film.json'))),
67
+ takes: takes && exists(takes) ? readdirSync(takes).filter((n) => /^take-\d+\./.test(n)).length : 0,
68
+ render: Boolean(s && exists(p.prod(s, locale, 'render', `${s}-${locale}-${SUFFIX.portrait}.mp4`))),
69
+ built: Boolean(s && filmFiles(p, s, locale).tall),
70
+ carousel: s ? pngs(join(campaignDir(p), 'carousels', s)) : 0,
71
+ posts: { youtube: Boolean(posted.youtube), instagram: Boolean(posted.instagram), x: Boolean(posted.x) }
72
+ }
73
+ })
74
+ }
75
+
76
+ /** One day's piece as JSON, for automation (default today in the site's time zone). */
77
+ export function campaignDue(p, { date, locale = p.site.defaultLocale } = {}) {
78
+ date ??= siteToday(p)
79
+ const r = calendarRows(p, locale).find((x) => x.date === date)
80
+ if (!r) die(`nothing scheduled on ${date}`)
81
+ const s = r.slug
82
+ return {
83
+ date, topic: r.topic, title: r.title, slug: s,
84
+ script: r.script ? p.rel(r.script) : null,
85
+ story: s ? storyUrl(p, s, locale) : null,
86
+ short: s ? p.rel(filmFiles(p, s, locale).expect.tall) : null,
87
+ carousel: s ? p.rel(join(campaignDir(p), 'carousels', s)) : null,
88
+ posted: (s && ledger(p)[s]) || {}
89
+ }
90
+ }
91
+
92
+ /** Records where a piece was posted: <campaign>/published.json and the story's social links (replacing them). */
93
+ export function campaignPosted(p, slug, links = {}, { today } = {}) {
94
+ const ip = storiesIndex(p)
95
+ const entry = (exists(ip) ? load(ip) : []).find((e) => e.slug === slug)
96
+ if (!entry) die(`${slug} is not in ${p.rel(ip)}`)
97
+ const vals = Object.fromEntries(['youtube', 'instagram', 'x'].filter((k) => links[k]).map((k) => [k, links[k]]))
98
+ if (!Object.keys(vals).length) die('nothing to record: pass --youtube ID, --instagram URL and/or --x URL')
99
+ const led = ledger(p)
100
+ led[slug] = { ...led[slug], ...vals, updated: today ?? siteToday(p) }
101
+ save(ledgerPath(p), led)
102
+ const yt = vals.youtube && !/^https?:/.test(vals.youtube)
103
+ ? (entry.video === 'short' ? `https://www.youtube.com/shorts/${vals.youtube}` : `https://www.youtube.com/watch?v=${vals.youtube}`)
104
+ : vals.youtube
105
+ recordLinks(p, slug, { youtube: yt, instagram: vals.instagram, x: vals.x }, { overwrite: true })
106
+ return led[slug]
107
+ }
108
+
109
+ /**
110
+ * Sets up a Short's film from its day script: one scene per voiceover beat (the on-screen column is the scene id when
111
+ * it is one, else beat-N; the last beat is the close), the voice lines from the table, 6 s per scene until
112
+ * `emaki fit` times them to the takes. An existing story keeps its index entry and body; an existing film is refused.
113
+ */
114
+ export function shortFilm(p, slug, { locale = p.site.defaultLocale } = {}) {
115
+ const f = dayScriptPath(p, slug, locale)
116
+ if (!f) die(`no day script for ${slug} in ${p.rel(join(campaignDir(p), 'days'))}/`)
117
+ if (exists(join(p.films, slug))) die(`${p.rel(join(p.films, slug))} already exists; edit its film.json and voice/${locale}.json`)
118
+ const md = readFileSync(f, 'utf-8'), beats = beatsOf(md)
119
+ if (!beats.length) die(`${p.rel(f)} has no voiceover table (| # | Voiceover | On screen |)`)
120
+ const seen = new Set()
121
+ const ids = beats.map((b, i) => {
122
+ let id = i === beats.length - 1 ? 'close' : /^[a-z][a-z0-9-]*$/.test(b.screen) && b.screen !== 'close' ? b.screen : `beat-${b.n}`
123
+ while (seen.has(id)) id = `${id}-${b.n}`
124
+ seen.add(id)
125
+ return id
126
+ })
127
+ const title = md.match(/^# Day \d+ · .+? · .+?: (.+)$/m)?.[1]?.trim()
128
+ newFilm(p, slug, { scenes: ids.join(','), title })
129
+ const fp = join(p.films, slug, 'film.json'), film = load(fp)
130
+ film.scenes = film.scenes.map((s, i) => ({ ...s, name: beats[i].screen.slice(0, 40), dur: 6 }))
131
+ save(fp, film)
132
+ save(join(p.films, slug, 'voice', `${locale}.json`), beats.map((b, i) => ({ scene: ids[i], text: b.text, say: null })))
133
+ return { slug, scenes: ids.length, path: p.rel(fp) }
134
+ }
135
+
136
+ const DAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'], MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
137
+ const dayLabel = (iso) => { const d = new Date(iso + 'T00:00:00Z'); return `${DAYS[d.getUTCDay()]} ${MONTHS[d.getUTCMonth()]} ${String(d.getUTCDate()).padStart(2, '0')}` }
138
+
139
+ /** Rewrites <campaign>/CALENDAR.md from calendar.csv: a section per week, a row per day, links to the day scripts. */
140
+ export function campaignCalendar(p) {
141
+ const rows = calendarRows(p), dir = campaignDir(p)
142
+ if (!rows.length) die('calendar.csv has no days')
143
+ const t0 = Date.parse(rows[0].date + 'T00:00:00Z')
144
+ const md = ['# Campaign calendar', '', `${rows.length} days, ${rows[0].date} → ${rows.at(-1).date}. Expanded: ${rows.filter((r) => r.script).length}. Edit calendar.csv, then \`emaki campaign calendar\` to rewrite this file.`]
145
+ let week = 0
146
+ for (const r of rows) {
147
+ const wk = Math.floor((Date.parse(r.date + 'T00:00:00Z') - t0) / 86400000 / 7) + 1
148
+ if (wk !== week) {
149
+ week = wk
150
+ md.push('', `## Week ${wk} · ${r.date} · ${r.topic}${r.theme ? `: ${r.theme}` : ''}`, '', '| Date | Title | |', '|---|---|---|')
151
+ }
152
+ md.push(`| ${dayLabel(r.date)} | ${r.title} | ${r.script ? `[script](${relative(dir, r.script)})` : ''} |`)
153
+ }
154
+ const out = join(dir, 'CALENDAR.md')
155
+ writeFileSync(out, md.join('\n') + '\n')
156
+ return { path: p.rel(out), days: rows.length }
157
+ }