@senseihq/emaki-cli 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +34 -2
- package/package.json +42 -4
- package/plugin/.claude-plugin/plugin.json +19 -0
- package/plugin/PLAYBOOK.md +137 -0
- package/plugin/README.md +51 -0
- package/plugin/agents/fact-checker.md +28 -0
- package/plugin/agents/localizer.md +34 -0
- package/plugin/agents/scene-builder.md +43 -0
- package/plugin/agents/story-planner.md +42 -0
- package/plugin/agents/story-writer.md +34 -0
- package/plugin/agents/visual-reviewer.md +33 -0
- package/plugin/modules/campaign/README.md +23 -0
- package/plugin/modules/campaign/calendar.csv +2 -0
- package/plugin/modules/campaign/day-script.template.md +41 -0
- package/plugin/modules/posting-desk/README.md +37 -0
- package/plugin/skills/emaki/SKILL.md +107 -0
- package/plugin/skills/emaki/references/01-interview.md +68 -0
- package/plugin/skills/emaki/references/02-architecture.md +69 -0
- package/plugin/skills/emaki/references/03-content-model.md +65 -0
- package/plugin/skills/emaki/references/04-scene-authoring.md +96 -0
- package/plugin/skills/emaki/references/05-voice-and-video.md +64 -0
- package/plugin/skills/emaki/references/06-i18n.md +37 -0
- package/plugin/skills/emaki/references/07-quality-gates.md +44 -0
- package/plugin/skills/emaki/references/08-feedback-loop.md +32 -0
- package/plugin/skills/emaki/references/09-publishing.md +11 -0
- package/plugin/skills/story-build/SKILL.md +37 -0
- package/plugin/skills/story-localize/SKILL.md +24 -0
- package/plugin/skills/story-media/SKILL.md +36 -0
- package/plugin/skills/story-publish/SKILL.md +22 -0
- package/plugin/skills/story-review/SKILL.md +29 -0
- package/plugin/templates/brief.md +32 -0
- package/plugin/templates/change-request.md +7 -0
- package/plugin/templates/changelog.md +4 -0
- package/plugin/templates/decisions.md +5 -0
- package/plugin/templates/glossary.md +4 -0
- package/plugin/templates/item-card.md +34 -0
- package/plugin/templates/outline.md +19 -0
- package/plugin/templates/review-sheet.md +12 -0
- package/plugin/templates/style-guide.md +21 -0
- package/plugin/templates/tracker.md +11 -0
- package/src/api.js +9 -0
- package/src/capture.js +169 -0
- package/src/config.js +32 -0
- package/src/films.js +145 -0
- package/src/index.js +195 -0
- package/src/init.js +109 -0
- package/src/plugin.js +106 -0
- package/src/tts.js +290 -0
- package/src/util.js +59 -0
- package/src/voice.js +216 -0
- package/templates/content/films/index.json +1 -0
- package/templates/content/films/measure-the-right-work/film.json +59 -0
- package/templates/content/films/measure-the-right-work/look.css +16 -0
- package/templates/content/films/measure-the-right-work/scene-close.json +153 -0
- package/templates/content/films/measure-the-right-work/scene-groups.json +99 -0
- package/templates/content/films/measure-the-right-work/scene-hook.json +96 -0
- package/templates/content/films/measure-the-right-work/scene-pair.json +190 -0
- package/templates/content/films/measure-the-right-work/scene-problem.json +162 -0
- package/templates/content/films/measure-the-right-work/score.js +19 -0
- package/templates/content/films/measure-the-right-work/strings/en.json +50 -0
- package/templates/content/films/measure-the-right-work/strings/es.json +50 -0
- package/templates/content/films/measure-the-right-work/voice/en.json +7 -0
- package/templates/content/films/measure-the-right-work/voice/es.json +7 -0
- package/templates/content/logos/brand.svg +1 -0
- package/templates/content/site.json +10 -0
- package/templates/content/stories/en/measure-the-right-work.json +13 -0
- package/templates/content/stories/es/measure-the-right-work.json +13 -0
- package/templates/content/stories/index.json +12 -0
- package/templates/content/ui/en.json +1 -0
- package/templates/content/ui/es.json +1 -0
- package/templates/emaki.config.json +67 -0
- package/templates/film/look.css +16 -0
- package/templates/film/scene-close.json +153 -0
- package/templates/film/scene-template.json +71 -0
- package/templates/film/score.js +12 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 SenecaGlobal
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,35 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @senseihq/emaki-cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`emaki`: set a project up for motion stories, install the Claude plugin, and run the production steps per film and
|
|
4
|
+
per locale.
|
|
5
|
+
|
|
6
|
+
```sh
|
|
7
|
+
npm i -D @senseihq/emaki-cli playwright && npx playwright install chromium
|
|
8
|
+
npx emaki init # sample content, emaki.config.json, film source, /show capture route, the plugin
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
| Command | What |
|
|
12
|
+
|---|---|
|
|
13
|
+
| `init [--framework x] [--no-sample] [--no-plugin]` | detects SvelteKit / Svelte / React / Next / Vue / Nuxt / plain; never overwrites |
|
|
14
|
+
| `plugin install [--force]` | skills, agents, playbook and templates into `.claude/` |
|
|
15
|
+
| `skills [add <name…> \| --all]`, `agents [add …]` | list or install single skills and agents |
|
|
16
|
+
| `manifest` | `content/films/index.json` (for the fetch loader) |
|
|
17
|
+
| `validate [slug]` | files, scene ids, `{{keys}}` in every locale, voice lines, story bodies |
|
|
18
|
+
| `new <slug> --scenes a,b,c [--title] [--date]` | scaffold a story + film in every locale |
|
|
19
|
+
| `sheet <slug> [--locale] [--at scene:t,…]` | contact sheet, both orientations |
|
|
20
|
+
| `tts-check` | each locale's voice provider and whether it's ready; offline engines on this machine |
|
|
21
|
+
| `set-voice --locale x --provider p [--opt k=v]` | choose the voice; keys are refused (environment only) |
|
|
22
|
+
| `voices [--locale] [--provider]` | the voices a provider offers |
|
|
23
|
+
| `voice <slug> [--locale] [--only 2,5] [--provider] [--opt]` | narration takes from `voice/<locale>.json` |
|
|
24
|
+
| `fit <slug> [--locale] [--check]` | scene times fitted to the takes: `timing.<locale>.json` |
|
|
25
|
+
| `render <slug> [--locale] [--o both] [--fps 30]` | picture + score + covers |
|
|
26
|
+
| `build <slug> [--locale] [--no-captions]` | voice + ducked score, −14 LUFS, captions (.srt/.vtt, burned in) |
|
|
27
|
+
|
|
28
|
+
Voice providers, set per locale in `emaki.config.json` (`default` → language → locale): **offline** `piper`,
|
|
29
|
+
`kokoro`, `macos` (`say`), `espeak`; **cloud** `elevenlabs`, `openai` (or Azure OpenAI), `azure`, `google`, `polly`
|
|
30
|
+
(via the `aws` CLI); **a person** `manual`. Keys come from environment variables only.
|
|
31
|
+
|
|
32
|
+
Needs Node 20.10+, ffmpeg, and Playwright with Chromium for `sheet` and `render`. The same steps are importable as
|
|
33
|
+
functions from `@senseihq/emaki-cli` (`project`, `validate`, `voice`, `fit`, `render`, `build`, …).
|
|
34
|
+
|
|
35
|
+
MIT © SenecaGlobal
|
package/package.json
CHANGED
|
@@ -1,6 +1,44 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@senseihq/emaki-cli",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "The motion stories command line: set a project up, install the Claude plugin (skills, agents, playbook), and run the production steps (validate, sheet, voice, fit, render, build) per film and locale.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"author": "SenecaGlobal",
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "git+https://github.com/sensei-hq/emaki.git",
|
|
11
|
+
"directory": "packages/emaki-cli"
|
|
12
|
+
},
|
|
13
|
+
"keywords": ["emaki", "cli", "motion", "video", "tts", "claude", "plugin", "skills"],
|
|
14
|
+
"bin": {
|
|
15
|
+
"emaki": "src/index.js"
|
|
16
|
+
},
|
|
17
|
+
"engines": {
|
|
18
|
+
"node": ">=20.10"
|
|
19
|
+
},
|
|
20
|
+
"files": ["src/**/*.js", "templates/**", "plugin/**", "README.md", "LICENSE"],
|
|
21
|
+
"exports": {
|
|
22
|
+
"./package.json": "./package.json",
|
|
23
|
+
".": "./src/api.js"
|
|
24
|
+
},
|
|
25
|
+
"scripts": {
|
|
26
|
+
"build": "node --check src/index.js",
|
|
27
|
+
"prepublishOnly": "cp ../../LICENSE . && bun run build",
|
|
28
|
+
"postpublish": "rm -f LICENSE"
|
|
29
|
+
},
|
|
30
|
+
"dependencies": {
|
|
31
|
+
"sade": "^1.8.1"
|
|
32
|
+
},
|
|
33
|
+
"peerDependencies": {
|
|
34
|
+
"playwright": ">=1.40"
|
|
35
|
+
},
|
|
36
|
+
"peerDependenciesMeta": {
|
|
37
|
+
"playwright": {
|
|
38
|
+
"optional": true
|
|
39
|
+
}
|
|
40
|
+
},
|
|
41
|
+
"publishConfig": {
|
|
42
|
+
"access": "public"
|
|
43
|
+
}
|
|
44
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "emaki",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Build a multilingual site of motion stories (articles, story player and narrated videos from one set of JSON scenes) through a guided, gated program: interview, outline, item cards, pilot, automated batches, review loop.",
|
|
5
|
+
"author": {
|
|
6
|
+
"name": "SenecaGlobal"
|
|
7
|
+
},
|
|
8
|
+
"keywords": [
|
|
9
|
+
"learning",
|
|
10
|
+
"explainers",
|
|
11
|
+
"animation",
|
|
12
|
+
"i18n",
|
|
13
|
+
"video",
|
|
14
|
+
"content"
|
|
15
|
+
],
|
|
16
|
+
"homepage": "https://github.com/sensei-hq/emaki",
|
|
17
|
+
"repository": "https://github.com/sensei-hq/emaki",
|
|
18
|
+
"license": "MIT"
|
|
19
|
+
}
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# Motion Stories Playbook
|
|
2
|
+
|
|
3
|
+
How to build a site of **stories**, each one a reader-friendly article, a presentation-ready story player and
|
|
4
|
+
(optionally) narrated videos, all from one set of data files, in every language you need. Written for the team
|
|
5
|
+
that owns the site (L&D, communications, a product or alert team) and for Claude, who builds it with you.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1 · What you get
|
|
10
|
+
|
|
11
|
+
| Output | For | Notes |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| **Story pages** | Readers on any device; search | Text first; each section illustrated by a looping animated figure; a "short version" band at the end. |
|
|
14
|
+
| **Story player** | Presenters, kiosks, the top of each story | The story's scenes as slides, 16:9 or 9:16, with optional sound; full screen with ←/→. |
|
|
15
|
+
| **Videos** | YouTube, Shorts/Reels, your LMS | The player recorded frame by frame with voiceover, sound and captions, per language; covers from the closing card. |
|
|
16
|
+
| **Every language** | Your audiences | Text, on-screen words, voice and captions per locale; falls back cleanly when a translation is missing. |
|
|
17
|
+
| *Optional:* posting desk | The comms team | Preview, reorder, request changes, approve; approved posts go out on schedule to YouTube, Instagram, X. |
|
|
18
|
+
| *Optional:* daily campaign | Marketing / awareness | A calendar of daily shorts with channel copy per day. |
|
|
19
|
+
|
|
20
|
+
The site can be built in React/Next.js, Svelte/SvelteKit, Vue/Nuxt, Astro or plain HTML: the stories are data and the
|
|
21
|
+
animation engine is a framework-free core with web components.
|
|
22
|
+
|
|
23
|
+
## 2 · The core idea
|
|
24
|
+
|
|
25
|
+
A story is **written once as data**:
|
|
26
|
+
|
|
27
|
+
- the **article**: title, summary, sections, the takeaway (per language);
|
|
28
|
+
- the **film**: 5–8 **scenes**, each a JSON file describing what is on screen and how it moves over time; every word
|
|
29
|
+
comes from a per-language strings file;
|
|
30
|
+
- the **voice script**: one line per scene (per language);
|
|
31
|
+
- the **sound**: a few soft tones timed to what happens on screen.
|
|
32
|
+
|
|
33
|
+
Because a scene is a pure function of time, the same file is the article's figure, a slide in the player and a
|
|
34
|
+
stretch of video. Change a word or a position once and every output follows.
|
|
35
|
+
|
|
36
|
+
## 3 · Roles
|
|
37
|
+
|
|
38
|
+
| Role | Does | Approves |
|
|
39
|
+
|---|---|---|
|
|
40
|
+
| **Owner** (product owner, L&D lead) | Sets purpose and scope; answers questions; reviews | Outline, item cards, look, pilot, each story, release |
|
|
41
|
+
| **Subject expert** | Supplies sources; checks facts | Accuracy |
|
|
42
|
+
| **Language reviewer** (per locale) | Reviews translations | Each locale's text and voice |
|
|
43
|
+
| **Legal / compliance** (when needed) | Reviews regulated wording | Sensitive claims |
|
|
44
|
+
| **Claude** (with this plugin) | Interviews, plans, writes, builds, renders, verifies, fixes | Nothing: it shows evidence and asks |
|
|
45
|
+
|
|
46
|
+
## 4 · The program, phase by phase
|
|
47
|
+
|
|
48
|
+
Each phase ends at a **gate**: the owner sees evidence (screenshots, contact sheets, videos) and approves before the
|
|
49
|
+
next phase starts. Claude keeps a tracker of gates and items in `project/tracker.md`.
|
|
50
|
+
|
|
51
|
+
| Phase | What happens | Gate (approved by the owner) |
|
|
52
|
+
|---|---|---|
|
|
53
|
+
| **0 · Start** | Import the plugin; say "build our story site" (or "build the learning portal"). Claude creates `project/` and asks its first questions. | |
|
|
54
|
+
| **1 · Interview & outline** | Purpose, audience, languages, stack, media scope; brand and tone; sources and topics. Claude drafts the site map and the **catalogue** (every story with format, topic, priority, sources) and picks a **pilot**. | **A** · outline approved |
|
|
55
|
+
| **2 · Item cards** | For the pilot and the first batch: audience, objective, the one message, the punchline, the scene plan with the picture for each scene, facts with sources, voice draft. Fact-checked. | cards approved (in batches) |
|
|
56
|
+
| **3 · Foundation** | The app in your stack, the kit installed, routes (home, index, story, player), the brand applied, all launch languages wired. Shown with the sample story at phone, tablet and desktop widths. | **B** · look approved |
|
|
57
|
+
| **4 · Pilot** | One story end to end: article, scenes, sound, contact sheets in each language, video if in scope. Iterated with you until it's right. Its settled rules become the **style guide**. | **C** · approach approved |
|
|
58
|
+
| **5 · Batches** | Stories built in batches of 3–5 (scene builders work in parallel), each self-checked and visually reviewed before you see it. You review with the review sheet; Claude fixes and shows before/after. | each story approved |
|
|
59
|
+
| **6 · Languages** | Each approved story drafted in the other locales, validated, laid out and checked; native review. | each locale approved |
|
|
60
|
+
| **7 · Media** | Voice per locale, timing fitted to the voice, video rendered and built with captions and covers. | videos approved |
|
|
61
|
+
| **8 · Release** | Accessibility, SEO, performance, prerendering per locale, daily rebuild; optional posting desk and campaign. | **E** · release |
|
|
62
|
+
| **9 · Run** | New stories through the same loop; feedback and analytics feed the next batch. | |
|
|
63
|
+
|
|
64
|
+
## 5 · How you review and give feedback
|
|
65
|
+
|
|
66
|
+
- You get, per story: the **contact sheet** (every scene's final picture, landscape and portrait, per language), the
|
|
67
|
+
**page** (desktop and phone), the **player** link and, when made, the **video**.
|
|
68
|
+
- Mark each scene in the **review sheet** (content, look, motion, text) or just say what's wrong in plain words:
|
|
69
|
+
"scene 3, the arrow should attach to the middle of the card", "make the title shorter in German".
|
|
70
|
+
- Claude turns each remark into a change request, fixes it in the data, re-checks it visually, and replies with the
|
|
71
|
+
after image. Rules that generalise go into the style guide and are applied to other stories.
|
|
72
|
+
- Changing text after voice was recorded means re-recording those lines; Claude will say which.
|
|
73
|
+
|
|
74
|
+
## 6 · Conventions that keep it consistent
|
|
75
|
+
|
|
76
|
+
- **Slugs and scene ids** are permanent kebab-case names (`spot-a-phish`, `hook`, `signs`, `close`).
|
|
77
|
+
- **Scene grammar:** words on the left, the picture on the right; one idea per scene; the head arrives first, the
|
|
78
|
+
picture builds in the order the voice names things; each scene ends on a held picture; calm motion.
|
|
79
|
+
- **The closing scene** is the punchline (3–9 words) with one line under it and your logo, nothing else: it is the
|
|
80
|
+
last thing seen and heard, the video cover, the social preview image and the article's "short version".
|
|
81
|
+
- **Every claim has a source**; made-up example numbers say "Illustrative" on screen.
|
|
82
|
+
- **Sound** is a few soft tones on the moments that matter, never background music, and always off until the viewer
|
|
83
|
+
turns it on.
|
|
84
|
+
- **Languages:** no words inside scene geometry; every word is a key in a strings file; layouts are sized for the
|
|
85
|
+
longest language; dates and numbers formatted per locale.
|
|
86
|
+
|
|
87
|
+
## 7 · What's in the box
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
The code is on npm: @senseihq/emaki (core, web components, loaders, JSON Schemas), @senseihq/emaki-svelte |
|
|
91
|
+
-react | -vue (components and player state), @senseihq/emaki-posting (the desk), @senseihq/emaki-cli (the `emaki`
|
|
92
|
+
command: init, plugin install, validate, new, sheet, voice, fit, render, build; it carries this plugin and a complete
|
|
93
|
+
bilingual sample story).
|
|
94
|
+
|
|
95
|
+
emaki/ (installed as .claude/emaki/ plus .claude/skills and .claude/agents)
|
|
96
|
+
PLAYBOOK.md this document
|
|
97
|
+
README.md install, share, quick start
|
|
98
|
+
skills/ emaki (the program) · story-build · story-review · story-localize
|
|
99
|
+
· story-media · story-publish (+ references: interview, architecture, content model,
|
|
100
|
+
scene authoring, voice & video, i18n, quality gates, feedback loop, publishing)
|
|
101
|
+
agents/ story-planner · scene-builder · story-writer · visual-reviewer · fact-checker · localizer
|
|
102
|
+
templates/ brief, decisions, outline, item card, review sheet, change request, style guide,
|
|
103
|
+
tracker, changelog, glossary
|
|
104
|
+
modules/ posting-desk (reference implementation + security model) · campaign (templates)
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## 8 · Prerequisites
|
|
108
|
+
|
|
109
|
+
- Node 20+ and your framework's toolchain; `playwright` (Chromium) for contact sheets and video; ffmpeg. Python only
|
|
110
|
+
for Piper/Kokoro voices and the posting desk's poster.
|
|
111
|
+
- For narrated video, one voice engine per language: free and offline (Piper, Kokoro), your organisation's cloud
|
|
112
|
+
(Azure AI Speech, Google Cloud Text-to-Speech, Amazon Polly, OpenAI), ElevenLabs, or a person recording. Claude
|
|
113
|
+
asks which when video comes up and records the choice; it writes and times the script either way.
|
|
114
|
+
- For the posting desk: an identity proxy (Cloudflare Access, Google IAP, Azure AD), a small database, object storage,
|
|
115
|
+
a scheduler (GitHub Actions or similar), and the platform accounts.
|
|
116
|
+
- Secrets live in environment variables or your CI's secret store, never in files.
|
|
117
|
+
|
|
118
|
+
## 9 · FAQ
|
|
119
|
+
|
|
120
|
+
**Can we start without video?** Yes. Articles and the player need no voice or rendering; add media later per story.
|
|
121
|
+
|
|
122
|
+
**Do we need a text-to-speech subscription?** No. Piper and Kokoro run free and offline on a laptop with good
|
|
123
|
+
quality, which also keeps unreleased content private. If your organisation already uses Azure, Google Cloud or AWS,
|
|
124
|
+
their voices are excellent and are usually already approved for use. Claude doesn't produce audio itself: it writes the
|
|
125
|
+
script, the pronunciations and the translations, and drives whichever engine you pick.
|
|
126
|
+
|
|
127
|
+
**Can we use our own design system?** Yes. The site pages are yours; scenes take their colours and fonts from one
|
|
128
|
+
`look.css` per film, which you set to your tokens on the pilot.
|
|
129
|
+
|
|
130
|
+
**What if a picture can't be expressed in the JSON format?** Scenes can fall back to a small JavaScript module with the
|
|
131
|
+
same rules; when a need repeats, it becomes a new JSON component instead.
|
|
132
|
+
|
|
133
|
+
**How long does a story take?** After the pilot, a batch of 3–5 stories typically takes a day of building plus your
|
|
134
|
+
review time; translations and videos are mostly automated after approval.
|
|
135
|
+
|
|
136
|
+
**Who owns what after handover?** Your team owns `content/` (the stories) and `project/` (the decisions and style
|
|
137
|
+
guide); adding a story is `emaki new` plus the per-story loop, with Claude or by hand.
|
package/plugin/README.md
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# emaki
|
|
2
|
+
|
|
3
|
+
A Claude (Code / Cowork) plugin for building a site of **motion stories**: reader-friendly
|
|
4
|
+
articles, a presentation-ready story player and narrated videos, all rendered from the same JSON scenes, in every
|
|
5
|
+
language you configure. Framework-agnostic (React, Svelte, Vue, Astro, plain HTML).
|
|
6
|
+
|
|
7
|
+
Built for teams like L&D (a learning portal) or communications and alert teams (an awareness or advisory site).
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npx @senseihq/emaki-cli init # in your app: sample content, config, film source, /show route, and this plugin
|
|
13
|
+
npx @senseihq/emaki-cli plugin install # or just the plugin, into .claude/ (skills, agents, playbook, templates)
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Then, in Claude with the project open, say: *"Build our learning portal with the emaki playbook."*
|
|
17
|
+
In Cowork you can also add this folder as a plugin.
|
|
18
|
+
|
|
19
|
+
## What happens next
|
|
20
|
+
|
|
21
|
+
Claude interviews you (purpose, audience, languages, stack, media, brand, sources), proposes an outline and a
|
|
22
|
+
catalogue of stories, agrees each story's details with you, builds the foundation and one pilot story for you to
|
|
23
|
+
approve, then builds the rest in batches you review, with translations and videos as you choose. Every step shows
|
|
24
|
+
evidence (contact sheets, screenshots, videos) and waits for your approval at the gates. See `PLAYBOOK.md`.
|
|
25
|
+
|
|
26
|
+
## Contents
|
|
27
|
+
|
|
28
|
+
| Folder | What |
|
|
29
|
+
|---|---|
|
|
30
|
+
| `PLAYBOOK.md` | The method: roles, phases, gates, review loop, conventions, FAQ |
|
|
31
|
+
| `skills/` | `emaki` (the program), `story-build`, `story-review`, `story-localize`, `story-media`, `story-publish` |
|
|
32
|
+
| `agents/` | `story-planner`, `scene-builder`, `story-writer`, `visual-reviewer`, `fact-checker`, `localizer` |
|
|
33
|
+
| `templates/` | Brief, decisions, outline, item card, review sheet, change request, style guide, tracker, changelog, glossary |
|
|
34
|
+
| npm `@senseihq/*` | The code: `emaki` (core, web components, loaders, schemas), `motion-svelte` / `-react` / `-vue`, `motion-posting`, `motion-cli` (the `emaki` command, which also installs this plugin) |
|
|
35
|
+
| `modules/` | `posting-desk` (approval-gated social posting, reference implementation) and `campaign` (daily shorts) |
|
|
36
|
+
|
|
37
|
+
## Try the sample in two minutes
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
npm create vite@latest my-stories -- --template svelte-ts && cd my-stories
|
|
41
|
+
npx @senseihq/emaki-cli init && npm i @senseihq/emaki @senseihq/emaki-svelte
|
|
42
|
+
npx emaki validate # the sample film, en + es
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Requirements
|
|
46
|
+
|
|
47
|
+
Node 20+; `npm i -D playwright && npx playwright install chromium` (contact sheets, video); ffmpeg (video). For voice, any one of: Piper or Kokoro (free, offline), macOS `say` (drafts), Azure AI Speech,
|
|
48
|
+
Google Cloud TTS, Amazon Polly, OpenAI, ElevenLabs, or recorded takes; Claude asks which. Keys are read from
|
|
49
|
+
environment variables; no secrets are stored in this kit.
|
|
50
|
+
|
|
51
|
+
Version 0.2.0 (pluggable voice: offline and organisation platforms).
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: fact-checker
|
|
3
|
+
description: Use this agent to verify every factual claim in an item card, story body, scene strings or voice script against its cited source, and to flag unsupported or overstated claims.
|
|
4
|
+
|
|
5
|
+
<example>
|
|
6
|
+
Context: Item cards are drafted for approval.
|
|
7
|
+
user: "Check the facts in these cards before I send them to legal."
|
|
8
|
+
assistant: "I'll run the fact-checker agent on each card's claims."
|
|
9
|
+
<commentary>Claims must trace to sources before content is approved.</commentary>
|
|
10
|
+
</example>
|
|
11
|
+
|
|
12
|
+
<example>
|
|
13
|
+
Context: A story is about to be published.
|
|
14
|
+
user: "Is everything in the ransomware story accurate?"
|
|
15
|
+
assistant: "Let me run the fact-checker agent across the article, scenes and script."
|
|
16
|
+
<commentary>A final accuracy pass across every surface of the story.</commentary>
|
|
17
|
+
</example>
|
|
18
|
+
|
|
19
|
+
model: inherit
|
|
20
|
+
color: red
|
|
21
|
+
tools: ["Read", "Glob", "Grep", "WebFetch"]
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
You verify claims. List every factual statement (numbers, names, rules, dates, causal claims) across the item card,
|
|
25
|
+
`stories/<locale>/<slug>.json`, `strings/<locale>.json` and `voice/<locale>.json`. For each, find the supporting passage
|
|
26
|
+
in the cited source (quote it) or mark it: unsupported, overstated, outdated, or illustrative-but-unlabelled.
|
|
27
|
+
Check that on-screen illustrative data says "Illustrative". Output a table: claim, where it appears, status, source
|
|
28
|
+
quote or fix. Never mark a claim supported without a quote.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: localizer
|
|
3
|
+
description: Use this agent to translate and adapt a story's article, scene strings, voice script and UI strings into another locale, keeping every key and scene mapping intact.
|
|
4
|
+
|
|
5
|
+
<example>
|
|
6
|
+
Context: A story is approved in English and Spanish is a launch locale.
|
|
7
|
+
user: "Make the Spanish versions of the approved stories."
|
|
8
|
+
assistant: "I'll run the localizer agent per story for es, then validate and sheet them."
|
|
9
|
+
<commentary>Per-locale drafting with identical keys is this agent's job.</commentary>
|
|
10
|
+
</example>
|
|
11
|
+
|
|
12
|
+
<example>
|
|
13
|
+
Context: A glossary changed.
|
|
14
|
+
user: "We now say 'suplantación' not 'phishing' in Spanish; update everything."
|
|
15
|
+
assistant: "I'll have the localizer agent apply the glossary change across the Spanish files."
|
|
16
|
+
<commentary>Consistent terminology across a locale.</commentary>
|
|
17
|
+
</example>
|
|
18
|
+
|
|
19
|
+
model: inherit
|
|
20
|
+
color: cyan
|
|
21
|
+
tools: ["Read", "Write", "Edit", "Glob", "Grep"]
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
You localise motion stories. Inputs: the default-locale story body, `strings/<default>.json`, `voice/<default>.json`,
|
|
25
|
+
the target locale, `project/glossary.md` and the style guide.
|
|
26
|
+
|
|
27
|
+
**Rules:** keep every key, section id and voice line order identical; adapt idioms, examples, units and formats for the
|
|
28
|
+
locale rather than translating word for word; keep the punchline short and natural; keep inline `<b>`/`<em>` markup
|
|
29
|
+
balanced; keep the voice lines speakable within the same time (≈ the same syllable count; flag lines that run long);
|
|
30
|
+
use `say` for pronunciations; do not translate product names unless the glossary says so.
|
|
31
|
+
|
|
32
|
+
**Write:** `stories/<locale>/<slug>.json`, `strings/<locale>.json`, `voice/<locale>.json`.
|
|
33
|
+
**Output:** the files, lines likely to overflow on screen (≥ 30% longer than the source), and terms a native reviewer
|
|
34
|
+
must confirm.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: scene-builder
|
|
3
|
+
description: Use this agent to write a story's film as JSON scenes (components, tracks, CSS, portrait block, strings, score) from an approved item card, and to verify it with contact sheets.
|
|
4
|
+
|
|
5
|
+
<example>
|
|
6
|
+
Context: A batch of approved item cards is ready.
|
|
7
|
+
user: "Build the scenes for the next three stories."
|
|
8
|
+
assistant: "I'll run a scene-builder agent per story in parallel, each with its item card and the style guide."
|
|
9
|
+
<commentary>Scene writing is the bulk of each story's build and parallelises cleanly per story.</commentary>
|
|
10
|
+
</example>
|
|
11
|
+
|
|
12
|
+
<example>
|
|
13
|
+
Context: The owner wants a scene reworked substantially.
|
|
14
|
+
user: "Redo the 'report it' scene as a three-step flow."
|
|
15
|
+
assistant: "I'll have the scene-builder agent rewrite that scene and re-sheet it."
|
|
16
|
+
<commentary>A substantial scene rewrite follows the same authoring rules.</commentary>
|
|
17
|
+
</example>
|
|
18
|
+
|
|
19
|
+
model: inherit
|
|
20
|
+
color: magenta
|
|
21
|
+
tools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash"]
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
You write motion scenes as data for the emaki kit and verify them visually.
|
|
25
|
+
|
|
26
|
+
**Read first:** the item card, `project/style-guide.md`, `skills/emaki/references/04-scene-authoring.md`,
|
|
27
|
+
`node_modules/@senseihq/emaki/src/scene-schema.ts`, and two existing scenes (the pilot's, or `content/films/measure-the-right-work/scene-*.json` from `emaki init`).
|
|
28
|
+
|
|
29
|
+
**Process (per story):**
|
|
30
|
+
1. Set `film.json` scene names, durations and descriptions from the card.
|
|
31
|
+
2. Write each `scene-<id>.json`: the board, a head with `{{id.eyebrow}}/{{id.line}}/{{id.sub}}`, the artwork, tracks
|
|
32
|
+
timed to the voice line, CSS prefixed with the scene id, and a `portrait` block (hoist the head; crop the art).
|
|
33
|
+
Every visible word goes through `strings/<locale>.json`. Prefer `text`/`box` components for text and cards so
|
|
34
|
+
translations reflow; use `svg` for shapes and charts; avoid `raw` unless nothing else fits.
|
|
35
|
+
3. Geometry: author on 1920×1080; words left (x 110, w ≈ 700), art right (x 880–1820, y 150–830); 40 px margins;
|
|
36
|
+
connectors end on edge centres; repeated cards share one size; nothing overlaps.
|
|
37
|
+
4. Write `score.js` beats and the closing chord.
|
|
38
|
+
5. Run `emaki validate <slug>` until clean; run `emaki sheet <slug>`; Read the image.
|
|
39
|
+
Fix every overlap, clip, misalignment and crowding in both orientations; check key beats mid-animation with
|
|
40
|
+
`--at`. Repeat until the sheet is clean.
|
|
41
|
+
|
|
42
|
+
**Output:** the files written, the final sheet path, and per scene one line on what it shows. Report any rule you had to
|
|
43
|
+
bend and why.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: story-planner
|
|
3
|
+
description: Use this agent to turn source material and a topic into a draft item card (audience, objective, one message, punchline, scene plan with pictures, facts with sources, voice draft) for a motion story.
|
|
4
|
+
|
|
5
|
+
<example>
|
|
6
|
+
Context: The outline is approved and the first batch needs item cards.
|
|
7
|
+
user: "Draft the item cards for the five phishing stories from the policy PDF."
|
|
8
|
+
assistant: "I'll dispatch the story-planner agent for each story with the policy and the outline row."
|
|
9
|
+
<commentary>Item cards are structured drafting from sources, which this agent specialises in.</commentary>
|
|
10
|
+
</example>
|
|
11
|
+
|
|
12
|
+
<example>
|
|
13
|
+
Context: The owner adds a topic mid-program.
|
|
14
|
+
user: "Add a story on password managers."
|
|
15
|
+
assistant: "Let me have the story-planner agent draft its item card for your review."
|
|
16
|
+
<commentary>A new catalogue item needs a card before any build.</commentary>
|
|
17
|
+
</example>
|
|
18
|
+
|
|
19
|
+
model: inherit
|
|
20
|
+
color: magenta
|
|
21
|
+
tools: ["Read", "Glob", "Grep", "Write", "WebFetch"]
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
You draft item cards for motion stories: short explainer stories that render as an article, a story player and a
|
|
25
|
+
narrated video from the same scenes.
|
|
26
|
+
|
|
27
|
+
**Inputs:** the outline row (slug, title, format, audience, sources), the source documents, the style guide if it
|
|
28
|
+
exists, and `templates/item-card.md`.
|
|
29
|
+
|
|
30
|
+
**Process:**
|
|
31
|
+
1. Read the sources. Extract the facts the story needs, each with a precise citation (document, section/page, URL).
|
|
32
|
+
2. State the audience and the objective (what they should know, feel or do) in one sentence each.
|
|
33
|
+
3. Write the one message (≤ 20 words) and the punchline (3–9 words, memorable, true).
|
|
34
|
+
4. Plan 5–8 scenes (film) or 4–6 (short): `hook` (a question, a surprise, a familiar pain), the problem/why, 2–4
|
|
35
|
+
idea scenes, the what-to-do scene, `close`. For each: id (kebab-case), the point in one line, **the picture that
|
|
36
|
+
shows it** (cards, a chart, a flow, a before/after, a list that ticks, a timeline), and the article section it
|
|
37
|
+
illustrates.
|
|
38
|
+
5. Draft the voice script, one line per scene, at 150 words a minute, ≤ the scene's length minus 2 s.
|
|
39
|
+
6. Flag anything unverified, illustrative data, sensitive wording, and questions for the owner.
|
|
40
|
+
|
|
41
|
+
**Output:** the filled `project/items/<slug>.md`, and a short summary listing open questions. Never invent facts or
|
|
42
|
+
sources; mark gaps instead.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: story-writer
|
|
3
|
+
description: Use this agent to write a story's reader-friendly article body and its voiceover script from an item card, in the site's voice.
|
|
4
|
+
|
|
5
|
+
<example>
|
|
6
|
+
Context: Scenes are being built for a batch; the article text is needed too.
|
|
7
|
+
user: "Write the articles for this batch."
|
|
8
|
+
assistant: "I'll use the story-writer agent for each story's body and voice script."
|
|
9
|
+
<commentary>Article and voice copy follow the item card and the style guide.</commentary>
|
|
10
|
+
</example>
|
|
11
|
+
|
|
12
|
+
<example>
|
|
13
|
+
Context: The owner wants an article tightened.
|
|
14
|
+
user: "The phishing article is too long; cut it to a three-minute read."
|
|
15
|
+
assistant: "I'll have the story-writer agent tighten it and keep the section ids."
|
|
16
|
+
<commentary>Rewriting copy while preserving the scene mapping is this agent's job.</commentary>
|
|
17
|
+
</example>
|
|
18
|
+
|
|
19
|
+
model: inherit
|
|
20
|
+
color: green
|
|
21
|
+
tools: ["Read", "Write", "Edit", "Glob", "Grep"]
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
You write the reader's article and the narrator's script for a motion story.
|
|
25
|
+
|
|
26
|
+
**Rules:** plain, direct sentences; the point first; no filler, no hype; active voice; one idea per paragraph; numbers
|
|
27
|
+
with their source; lists in `points`; sections keep the scene ids so figures attach. The takeaway is the punchline
|
|
28
|
+
exactly; `takeawaySub` is the close card's sub. Respect the style guide's wording rules and the glossary.
|
|
29
|
+
|
|
30
|
+
**Write:** `content/stories/<locale>/<slug>.json` (title ≤ 60 characters, dek ≤ 2 sentences, 3–6 sections, takeaway,
|
|
31
|
+
takeawaySub, sources) and `content/films/<slug>/voice/<locale>.json` (one line per scene, 150 words a minute, each line
|
|
32
|
+
fits its scene minus 2 s; `say` for names and acronyms).
|
|
33
|
+
|
|
34
|
+
**Output:** the files, the reading time (words ÷ 220), the voice total in seconds, and anything you could not source.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: visual-reviewer
|
|
3
|
+
description: Use this agent to inspect a story's contact sheets and page screenshots against the quality checklist and report layout, motion and text problems with exact fixes.
|
|
4
|
+
|
|
5
|
+
<example>
|
|
6
|
+
Context: A scene-builder has finished a story.
|
|
7
|
+
user: "Check the sheets before I show the owner."
|
|
8
|
+
assistant: "I'll run the visual-reviewer agent over the sheets and screenshots first."
|
|
9
|
+
<commentary>An independent visual pass catches overlaps and misalignments before the owner sees them.</commentary>
|
|
10
|
+
</example>
|
|
11
|
+
|
|
12
|
+
<example>
|
|
13
|
+
Context: A batch is ready for review.
|
|
14
|
+
user: "Review all five stories' scenes."
|
|
15
|
+
assistant: "Let me run the visual-reviewer agent on each story's sheet."
|
|
16
|
+
<commentary>Systematic inspection against the checklist is this agent's role.</commentary>
|
|
17
|
+
</example>
|
|
18
|
+
|
|
19
|
+
model: inherit
|
|
20
|
+
color: yellow
|
|
21
|
+
tools: ["Read", "Glob", "Grep", "Bash"]
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
You are a strict visual reviewer for motion stories. You look at images; you do not guess.
|
|
25
|
+
|
|
26
|
+
**Process:** Read each contact sheet (landscape and portrait per scene) and page screenshot. For each scene apply the
|
|
27
|
+
per-scene checklist in `skills/emaki/references/07-quality-gates.md`: overlaps, clipping, 40 px margins,
|
|
28
|
+
connectors on edge centres, equal sizes for repeated elements, even spacing, text fit and wrapping, diacritics, colour
|
|
29
|
+
use, the hold frame, the close card as cover. When a coordinate is in doubt, measure element boxes with Playwright on the
|
|
30
|
+
capture page.
|
|
31
|
+
|
|
32
|
+
**Output:** findings ranked blocker / should / nice, each with: scene id, orientation, locale, what is wrong, and the
|
|
33
|
+
exact change (component id, property, new value). Say "clean" when a scene passes. No praise, no vague advice.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Daily campaign (optional module)
|
|
2
|
+
|
|
3
|
+
A run of short pieces (one a day for N weeks) around a theme. Each day has one story (usually a Short: 5–6 scenes,
|
|
4
|
+
30–60 s, 9:16 first) and the copy for every channel, in one **day script** the producer and the poster both read.
|
|
5
|
+
|
|
6
|
+
## Files
|
|
7
|
+
|
|
8
|
+
| File | Purpose |
|
|
9
|
+
|---|---|
|
|
10
|
+
| `calendar.csv` | One row per day: date, slug, product/topic, title, the hook line, status. The plan at a glance. |
|
|
11
|
+
| `days/day-NN-<slug>.md` | The day script, from `day-script.template.md`: the voiceover table (one line per scene), the YouTube title and description, the Instagram carousel (6–7 slides) and caption, the X post and thread, and the posting step. |
|
|
12
|
+
| `carousels/<slug>/*.png` | Carousel slides, rendered from the film's scenes (`emaki sheet` frames, or a dedicated carousel layout). |
|
|
13
|
+
|
|
14
|
+
## Flow
|
|
15
|
+
|
|
16
|
+
1. Plan the calendar with the owner (topics, order, cadence, which days are Shorts vs. articles only).
|
|
17
|
+
2. Write the day scripts in batches of 5–7; the owner approves the batch.
|
|
18
|
+
3. For each day: build the story (the orchestrator's per-item loop), voice, render the 9:16 (and 16:9), build.
|
|
19
|
+
4. Stage it to the posting desk; the owner approves; the scheduled poster publishes on the day.
|
|
20
|
+
5. Weekly: read the numbers back into the calendar (views, saves, clicks to the article) and adjust the next batch.
|
|
21
|
+
|
|
22
|
+
Translations: one day script per locale (`days/<locale>/...`) or a column per locale in the voiceover table; the
|
|
23
|
+
story's strings and voice files carry the language, the day script carries the channel copy.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Day NN · <Weekday Mon D> · <Topic>: <Title>
|
|
2
|
+
|
|
3
|
+
**Story:** <site>/<locale>/stories/<slug> (goes live YYYY-MM-DD)
|
|
4
|
+
**Tags:** tag-one, tag-two, tag-three
|
|
5
|
+
|
|
6
|
+
## 1 · Short video (9:16, about 45 s, YouTube Shorts + Instagram Reels)
|
|
7
|
+
|
|
8
|
+
The motion film `content/films/<slug>/` rendered 9:16, the same scenes as the story's figures. Action tones only;
|
|
9
|
+
voiceover per scene; captions burned in. The voice lines below are the copy of record (`voice/<locale>.json`).
|
|
10
|
+
|
|
11
|
+
| # | Voiceover | On screen (scene) |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| 1 | The hook, as a question or a surprising claim. | hook |
|
|
14
|
+
| 2 | … | … |
|
|
15
|
+
| N | The punchline. | close |
|
|
16
|
+
|
|
17
|
+
## 2 · YouTube
|
|
18
|
+
|
|
19
|
+
**Title:** <title> #shorts
|
|
20
|
+
**Description:** <one or two sentences>. Read the full story: <link>
|
|
21
|
+
#hashtag #hashtag
|
|
22
|
+
|
|
23
|
+
## 3 · Instagram carousel (1080×1350, 6 slides)
|
|
24
|
+
|
|
25
|
+
1. <hook>
|
|
26
|
+
2. …
|
|
27
|
+
6. <punchline>
|
|
28
|
+
|
|
29
|
+
**Caption:** <two lines + "link in bio">
|
|
30
|
+
**Hashtags:** #… #…
|
|
31
|
+
|
|
32
|
+
## 4 · X
|
|
33
|
+
|
|
34
|
+
**Post:** <one sentence that stands alone> 👇
|
|
35
|
+
**Thread:**
|
|
36
|
+
1. …
|
|
37
|
+
2. Full story: <link>
|
|
38
|
+
|
|
39
|
+
## 5 · Posting
|
|
40
|
+
|
|
41
|
+
After the build: stage to the posting desk; the owner approves; the scheduled job posts on the day and records the links.
|