wand-decks-kit 0.8.7 → 0.10.0

package/PROMPT.md

@@ -10,6 +10,70 @@ is the workflow and the design system; the skill is the source of truth for comm
 
 ---
 
+
+
+## Session decks — the Kearney standard (0.10)
+
+`Wand_x_Kearney_SF_Leadership_Session_29Sep2026_v2.pptx` is the reference for a
+deck that is *run in a room*. What makes it that quality is not the slides
+alone:
+
+- **A spine.** Five Parts, each opened by a divider with a client-specific
+  *working question*, and a session slide that reads as a clock (minutes per
+  part). The kit: `divider` gains `part`, and uses the deck's own section art
+  (`divider-art.png`); `coDelivery` / `agenda` items gain `meta`.
+- **A run-of-show in the notes.** Every content slide carries its time window,
+  CORE when it carries the argument, what to say, and who in the room will test
+  it; the session slide carries checkpoints and what to cut if late. The kit:
+  `notes` on any slide, written through pptxgenjs `addNotes`.
+- **Backups behind the close**, hidden and uncounted. The kit: `backup: true`.
+- **Two slides every Wand session uses**: the today-vs-with-Wand flow (the
+  agents' steps filled) and the transformation timeline. The kit:
+  `flowCompare`, `timeline`.
+
+Where the reference is weaker than the kit, the kit wins: it embeds fonts
+subsetted (`saveSubsetFonts="1"`, which garbles digits in exported PDFs), and
+1,834 text runs are Calibri. `audit` flags both on it.
+
+**Edits are commands, not rewrites.** `wand.js show` and `wand.js edit` exist
+because a salesperson's changes are small and the old edit path cost two full
+copies of the spec in the chat. A spec's `confidential` now reaches the footer
+— it never did; every deck said STRICTLY CONFIDENTIAL.
+
+## The guideline deck (0.9)
+
+Since 2026-09-23 the design source of truth is a real deck —
+`Vivicta_Session_Deck.pptx`, the standard Wand sales deck as it is actually sent
+— not the earlier reference PDFs. Everything below was **measured from it**, and
+`brand/BRAND.md` and the kit's `T` carry the counts:
+
+- **Tokens.** Dark ground is `240F48`, flat. Titles `FFFFFF`, body `F5F5F5`,
+  captions `BBBBBB`, lists in cards `C6BFE4`. Cards: solid `2A1F5C`, muted
+  `1B1738`, stroke `5B4BB0`. Accent text on dark `9481FF`. The old
+  `0F0C26 / B7B0DC / 2C2460` set was the reference PDFs' rendering, not the deck.
+- **Interior dark slides carry no art.** The gradient compositions belong to
+  the cover (`cover-art.png`, orb baked in) and the closing (`closing-art.png`
+  plus `orb-glow.png` centred). `background()` paints a flat colour.
+- **Chrome.** Tag at `0.42, 0.24`; mark at `9.40, 0.26`; footer band at
+  `y 5.29, h 0.34`, 7pt: `WAND · <deck>` left, `<confidential> · nn/NN` right.
+- **Cover.** Title at `0.42, 1.79`, 39pt shrinking to 30; body at `3.15`; a
+  `PRESENTED TO` block bottom-right (`presentedTo: [name, title]`).
+- **Closing.** Orb at `3.98, 0.69, 2.03²`; the line at 33pt shrinking to 22 —
+  a real ask is a sentence, not "Thank You".
+- **Five layouts the deck has and the kit did not:** `agenda`, `team` (with a
+  headshot slot), `fourCards`, `deliverColumns`, `coDelivery`. They are the
+  slides a sales session adds to the standard deck; a tester had to hand-build
+  all five.
+- **The brand gate.** `wand.js audit` runs `tools/brandlint.py`: every text run
+  in Geist, every colour a token, the 10 × 5.625 canvas, a footer on every
+  content slide. On the guideline deck itself it names exactly the slides the
+  tester retexted by hand (Arial on S14, Calibri on S07) — which is the point:
+  an edit-only job reports those and asks, rather than restyling unasked.
+
+`card()` variants are theme-aware now: `solid` on a light slide is a white
+card with a hairline, not a dark purple box hiding light ink — the agenda in
+the template rendered as four black boxes before that fix.
+
 ## 0. Ground truth: the reference decks
 
 Two decks in Project knowledge define the target output. **They are the specification.** When this

package/SKILL.md

@@ -4,7 +4,7 @@ description: Rebrand, merge, edit or author a PowerPoint deck on the Wand design
 compatibility: Requires Node.js 18+ and code execution enabled in claude.ai (Settings > Features). No network access needed - dependencies are bundled. Python 3 is used to read a source .pptx and to embed fonts; without it the kit can still author and check a deck, but the output will render in Arial on machines without Geist.
 license: Proprietary - Wand AI
 metadata:
-  version: "0.8.7"
+  version: "0.10.0"
 ---
 
 
@@ -34,16 +34,27 @@ output.
 
 Every path below is relative to the kit folder.
 
-A deck engine: 28 layouts, real font metrics, embedded Geist, and six gates that
-each catch something the others cannot.
+A deck engine: 35 layouts, real font metrics, embedded Geist, speaker notes,
+and gates that each catch something the others cannot.
 
-**Read `PROMPT.md` before making any design decision.** It is the source of
-truth on canvas, colour, type, layout choice and content rules. This file is
-only the operating procedure.
+## Read only what the job needs
+
+Sales teams run this. Every file you read and every spec you write is paid for
+in the chat, so the job decides the reading:
+
+| Job | Read | Never |
+|---|---|---|
+| Edit a deck this kit built | `node wand.js show <deck>` (one line per slide), then `show <deck> <n>` for the slide you change | read or rewrite the whole spec; read `PROMPT.md` |
+| Edit a deck built elsewhere | the slide you change, then `audit` | restyle anything unasked |
+| Rebuild, merge, author | `PROMPT.md` once, `work/PLAN.md`, `node wand.js layouts` | re-read them per slide |
+
+Look at the contact sheet once; open a single slide only where something looks
+off. `PROMPT.md` is the source of truth on design — read it for design
+decisions, not for edits.
 
 ## Available scripts
 
-- **`wand.js`** — the front door - doctor, rebuild, layouts, glyphs, validate, check, preview, ship, spec, inspect
+- **`wand.js`** — the front door - doctor, rebuild, layouts, glyphs, validate, check, preview, ship, show, edit, audit, spec, inspect
 - **`build.js`** — spec -> .pptx, or --check, or --preview
 - **`tools/extract.py`** — read a source deck: verbatim dump, geometry, analysis
 - **`embed_fonts.py`** — embed Geist unsubsetted, and carry the spec inside the deck
@@ -70,7 +81,7 @@ thing, and paid a full second pass. This is not optional for a rebuild, a merge
 or an adaptation; only "author from a brief" with fewer than eight slides may
 go straight to the spec.
 
-## The five jobs
+## The seven jobs
 
 ### Rebrand a deck they attached
 
@@ -116,15 +127,65 @@ node wand.js audit <edited-deck>.pptx --dump work/visible_dump.txt   # + coverag
 has been checked by nobody. Say which slides were lifted unchanged, which were
 retexted, and that the source's fonts (not Geist) carry through.
 
+### Edit a deck they attached — not built here
+
+"Change the date on the cover", "swap slide 4's title", "add our logo to the
+partner slide". They want *that*, and nothing else touched.
+
+1. Do exactly the edit, directly in the `.pptx` with the pptx tools. Do not
+   rebuild, do not restyle, do not "tidy" anything nearby.
+2. Then run the guideline over the whole deck:
+
+   ```bash
+   node wand.js audit <their-deck>.pptx
+   ```
+
+   The **brand** gate lists every slide where a text run is not Geist, a colour
+   is not a token, the canvas is not the 10 × 5.625 grid, or a content slide
+   has no footer.
+3. Deliver the edited deck first. Then report the inconsistencies the gate
+   found — per slide, in one line each — and **ask whether to fix them**. Do not
+   fix them unasked: an edit-only job that comes back restyled is a broken
+   promise, even when the restyle is right.
+
 ### Edit a deck this kit built
 
+Decks built here carry their spec inside the file, so an edit is one command —
+not reading the spec, not writing it back:
+
 ```bash
-node wand.js spec <their-deck>.pptx work/deck.json
+node wand.js show  deck.pptx                 # one line per slide
+node wand.js show  deck.pptx 4               # slide 4's fields, only if you need them
+node wand.js edit  deck.pptx --set '1.tag=Presented to Acme  ·  6 October 2026' \
+                             --set 2.items.4.meta='40 min' \
+                             --set '7.notes.text=Lead with the Foundation phase.'
 ```
 
-Decks built here carry their own spec inside the file. Change only what was
-asked, then `ship`. If the deck carries no spec it was not built here — treat it
-as a rebrand.
+Paths are 1-based, the way the room counts: `2.items.4.meta` is slide 2, item 4.
+Also `--del N`, `--move N M`, `--add N '<slide json>'`, `--dry` to preview. The
+result is saved as the next version (`Deck_v2.pptx` → `Deck_v3.pptx`), every
+gate runs, the original is never overwritten. If `show` says the deck carries
+no spec, it was not built here — use the job above.
+
+### Build a session deck
+
+When the deck will be *run* in a room — a leadership session, a workshop, a
+partner meeting — give it the shape of the Kearney example (the reference for
+this kind of deck, `examples/session.json`):
+
+- **Cover** with `presentedTo`. **Session slide** next: `coDelivery` with a
+  `meta` duration on every item ("15 min") — the room reads it as a clock.
+- **Part dividers** (`divider` with `part: "Part II"` and `body: "Working
+  question: …"`) — one question per part, written for this client.
+- **Speaker notes on every content slide**: `notes: { time: "00:21 to 00:25",
+  core: true, text, watch }`. `time` is the run-of-show window; `core` marks the
+  slides that carry the argument; `watch` names who in the room will push. The
+  session slide's notes carry the checkpoints and what to cut if late.
+- **Backups after the closing**, `backup: true` — hidden, uncounted ("31 of 31",
+  not "of 34"), footer says BACKUP.
+
+Timings, attendee names and "watch for" lines come from the user or the brief.
+Never invent them — leave `notes` out rather than guess.
 
 ## Spend tool calls like they are metered — they are
 
@@ -151,6 +212,13 @@ optional — **sweep the entire spec for that pattern before re-running anything
 Paying a full cycle per instance is the slow way to learn the same fact
 repeatedly.
 
+## One skill at a time
+
+If `wand-decks` or `wand-docs` is installed beside `wand-design`, both may
+fire on the same file. **`wand-design` leads; this file yields.** Do not run
+two setups, and tell the user once: remove the older per-family skill, the
+combined one covers it.
+
 ## Rules that decide whether the output is usable
 
 1. **Faithful means verbatim.** No consolidating slides, no paraphrasing to
@@ -185,7 +253,9 @@ repeatedly.
 | `node wand.js check <spec>` | fit in real Geist, bounds, assets |
 | `node wand.js preview <spec>` | writes `preview/trace.js` for the browser preview |
 | `node wand.js inspect <deck>` | parts, relationships, embedded fonts |
-| `node wand.js audit <deck> [--dump f]` | every spec-free gate on any .pptx — use on decks edited outside the kit |
+| `node wand.js show <deck> [n]` | the deck in one line per slide, or one slide's fields |
+| `node wand.js edit <deck> --set N.path=v` | change a kit-built deck in one command; saves `_vN+1`, runs every gate |
+| `node wand.js audit <deck> [--dump f]` | every spec-free gate on any .pptx, including the **brand** gate (fonts, colours, canvas, footer) — use on decks edited outside the kit |
 
 ## Deliver
 

package/build.js

@@ -30,16 +30,27 @@ function loadSpec(p) {
 /** Build the .pptx. */
 function build(spec, out) {
   const pres = W.newDeck(pptxgen);
-  const total = spec.slides.length;
+  // Backups are hidden and uncounted: the room sees 31 of 31, not 31 of 34.
+  const total = spec.slides.filter((x) => !x.backup).length;
+  let n = 0;
   spec.slides.forEach((sl, i) => {
     const fn = W[sl.layout];
     if (typeof fn !== "function") throw new Error(`slide ${i + 1}: unknown layout "${sl.layout}"`);
-    const args = { ...sl, n: i + 1, total };
+    const args = { ...sl, n: sl.backup ? null : ++n, total };
     if (!FULL_BLEED.has(sl.layout)) {
       args.deck = sl.deck || spec.deck;
       args.confidential = sl.confidential || spec.confidential;
     }
+    W.context({ confidential: args.confidential || "STRICTLY CONFIDENTIAL" });
+    const before = pres.slides.length;
     fn(pres, args);
+    // Not every layout returns its slide, so take the one it just added.
+    const slide = pres.slides.length > before ? pres.slides[pres.slides.length - 1] : null;
+    if (slide) {
+      const nt = W.notesText(sl.notes);
+      if (nt) slide.addNotes(nt);
+      if (sl.backup) slide.hidden = true;
+    }
   });
   return pres.writeFile({ fileName: out }).then(() => {
     console.log(`wrote ${out} (${total} slides)`);

package/docs/LAYOUTS.md

@@ -17,13 +17,21 @@ full-bleed three) `deck` / `n` / `total` for the footer.
 | Layout | Params | Use for |
 |---|---|---|
 | `cover` | `eyebrow, titleLines[], body, kickerPlain, kickerBold` | Slide 1. Dark, full bleed, no footer |
-| `divider` | `eyebrow, titleText, body` | Section breaks and the agenda. Keeps the tag, drops the footer |
+| `divider` | `eyebrow, titleText, body, part` | Section breaks and the agenda. Keeps the tag, drops the footer |
 | `closing` | `eyebrow, line1, line2, body, url` | Last slide. Centred, full bleed |
 
 ## Content
 
 | Layout | Params | Use for |
 |---|---|---|
+| `agenda` | `items[{title,body,meta}]` | What we'll cover — 2–5 numbered cards (guideline S03) |
+| `team` | `items[{name,role,initials}]` | Who's in the room — headshot slot per person (guideline S02) |
+| `fourCards` | `items[{title,body}]` | Demo objectives, pillars — four titled cards under a lede (S12) |
+| `deliverColumns` | `columns[{heading,lead,body}]` | How we deliver — three flat columns with an accent bar (S14) |
+| `coDelivery` | `items[{title,body,meta}]` | Numbered rows in two columns, up to six. With `meta: "15 min"` it is the session agenda (Kearney S02) |
+| `flowCompare` | `lanes[{label,caption,steps[{who,step,human}]}]` | Today vs with Wand — two lanes of 3–5 steps; the machine steps are filled (Kearney S08) |
+| `timeline` | `phases[{when,label,bullets}]` | A journey in 2–4 phases on a line (Kearney S16) |
+| — every layout — | `notes`, `backup` | Speaker notes (`{time, core, text, watch}` or a string); `backup: true` hides the slide after the close |
 | `threeUp` | `items[{eyebrow,title,pill,body,emph}], arrows` | 3 comparable things. `arrows: true` for a progression |
 | `fourUpIcon` | `items[{icon,title,body}], kickerText` | 4 attributes or capabilities |
 | `sixUpIcon` | `items[{icon,title,body}]` | 6 features. Don't use it three slides running |

package/examples/session.json

@@ -0,0 +1,92 @@
+{
+  "deck": "WAND × CLIENT · LEADERSHIP SESSION",
+  "confidential": "WAND · CONFIDENTIAL",
+  "slides": [
+    { "layout": "cover", "tag": "Presented to Client  ·  29 September 2026",
+      "titleLines": ["Expand human possibility", "beyond human capacity."],
+      "body": "For all of history, what organizations could accomplish was constrained by the number of people available to do the work. AI labor changes that.",
+      "presentedTo": ["First Last, Managing Partner", "First Last, Head of Transformation"],
+      "notes": { "text": "On screen while the room settles. Frame it the way the client asked: a working conversation about a change in the nature of production, not a product pitch." } },
+
+    { "layout": "coDelivery", "tag": "The session", "titleText": "A working conversation, not a presentation.",
+      "items": [
+        { "title": "When software becomes labor", "body": "The threshold between a tool and a worker.", "meta": "15 min" },
+        { "title": "The organization has to change", "body": "From the individual agent to the Hybrid Organization.", "meta": "10 min" },
+        { "title": "Why transformations succeed, or die", "body": "Resistance is operating-model design.", "meta": "10 min" },
+        { "title": "From architecture to production", "body": "Inside an agent, then one real process, live.", "meta": "35 min" },
+        { "title": "When capacity decouples from labor", "body": "From the firm to the economy.", "meta": "5 min" },
+        { "title": "Wand × Client", "body": "Designing the Hybrid Organization together.", "meta": "10 min" }
+      ],
+      "notes": { "time": "00:00, under one minute", "text": "Walk the spine, not the rows. 90 minutes core, then 30 minutes of open discussion. Checkpoints: 00:20 Part II, 00:40 Part IV, 01:15 Part V. If late, compress Part III and Part V — never the live walkthrough." } },
+
+    { "layout": "divider", "titleText": "When software becomes labor",
+      "part": "Part I", "body": "Working question: which of your problems are being treated as AI productivity when they are really a chance to add a new source of labor?",
+      "notes": { "time": "00:01 to 00:03", "text": "Read the working question aloud and leave it on screen. Do not answer it yet." } },
+
+    { "layout": "flowCompare", "tag": "Why three years of AI spend has not moved the operating line",
+      "titleText": "Every AI tool you own ends at a person.",
+      "lanes": [
+        { "label": "Today — AI as a tool", "caption": "Capacity = your people. Four of five steps wait on a person; that person is the ceiling.",
+          "steps": [ { "who": "Person", "step": "Notices", "human": true }, { "who": "Person", "step": "Gathers context", "human": true },
+                     { "who": "Person", "step": "Instructs", "human": true }, { "who": "AI", "step": "Drafts" },
+                     { "who": "Person", "step": "Checks", "human": true } ] },
+        { "label": "With Wand — AI as labor", "caption": "Capacity = people + agents. The person moves from every step to the one step that needs judgment.",
+          "steps": [ { "who": "Agent", "step": "Notices" }, { "who": "Agent", "step": "Plans" }, { "who": "Agent", "step": "Executes" },
+                     { "who": "Agent", "step": "Grades" }, { "who": "Manager", "step": "Approves", "human": true } ] }
+      ],
+      "notes": { "time": "00:11 to 00:14", "core": true, "text": "This is the difference between an efficiency programme and a capacity programme. Point at the top row: every step waits on a person.", "watch": "whoever owns the current copilot rollout — expect them to defend adoption numbers." } },
+
+    { "layout": "fourCards", "tag": "Agent behavior", "titleText": "A worker, not just a good tool.",
+      "subtitleText": "A tool responds to prompts. A worker pursues goals, decides what matters, acts within constraints, and is judged by outcomes.",
+      "items": [
+        { "title": "Pursues goals", "body": "Carries objectives and KPIs like any employee, and works toward them without being asked." },
+        { "title": "Decides what matters", "body": "Notices, prioritizes and plans inside the boundaries policy sets." },
+        { "title": "Is graded", "body": "Every output reviewed against a baseline agreed before it started." },
+        { "title": "Gets better", "body": "Banks what it learns, so a year in it is categorically better, not older." }
+      ],
+      "notes": { "time": "00:43 to 00:47", "core": true, "text": "Land the word 'worker'. Everything after this slide assumes the room accepts it." } },
+
+    { "layout": "divider", "titleText": "Why transformations die",
+      "part": "Part III", "body": "Working question: what would your methodology look like if org redesign, workforce redesign and agent deployment were one program, not three?",
+      "notes": { "time": "00:30 to 00:31" } },
+
+    { "layout": "timeline", "tag": "Transformation journey", "titleText": "The transformation timeline.",
+      "subtitleText": "From the starting line, month over month, compounding.",
+      "phases": [
+        { "when": "3–6 months", "label": "Foundation", "bullets": ["A core transformation team of 7–10 people", "One registry covering people and agents", "5–10 core processes rebuilt for the dual workforce", "Dozens of agents in production with named managers"] },
+        { "when": "6–12 months", "label": "Scale", "bullets": ["Agents across dozens of core functions", "Management structure rebalanced; spans widened", "Hundreds of agents in production"] },
+        { "when": "12–24 months", "label": "Accelerate", "bullets": ["Most processes designed for a dual workforce from the start", "Whole functions run by agent teams", "Cost per unit of work structurally below the market"] }
+      ],
+      "notes": { "time": "00:37 to 00:40", "core": true, "text": "Timelines are directional. The commitment is the Foundation phase; everything after it is earned by the telemetry." } },
+
+    { "layout": "deliverColumns", "tag": "The build", "titleText": "The client designs the transformation. Wand operates it.",
+      "subtitleText": "Who does each part, and how it is governed.",
+      "columns": [
+        { "heading": "1 · Change management", "lead": "Led by your people, supported by ours", "body": "A small core team who pick where to start and carry the early wins back." },
+        { "heading": "2 · Deployment", "lead": "Led by our solution architect with your technical team", "body": "Cloud, deployment model, security review, and reaching the systems you run." },
+        { "heading": "3 · Building the workforce", "lead": "Led by our forward-deployed engineers", "body": "Build the agents and processes with your team, then shift to supporting as your people take it on." }
+      ],
+      "notes": { "time": "01:23 to 01:25", "text": "Their methodology, our operating system. Say it in that order." } },
+
+    { "layout": "fourCards", "tag": "Next steps", "titleText": "What happens next.",
+      "subtitleText": "This room builds the momentum. The partnership work happens in a smaller session, with named owners and dates.",
+      "items": [
+        { "title": "Partnership session", "body": "Named leads on both sides; one process chosen and its baseline written down." },
+        { "title": "Architecture deep-dive", "body": "Under NDA, for your technology team: deployment posture, identity, audit." },
+        { "title": "Sandbox access", "body": "A governed environment your team can build in, with our engineers alongside." },
+        { "title": "First client reunion", "body": "Where the first agents in production are shown against the baseline." }
+      ],
+      "notes": { "time": "01:29 to 01:30", "text": "Leave the room with one date agreed. Anything else is a follow-up email." } },
+
+    { "layout": "closing", "line1": "Thank you.", "body": "The operating system for the human + agent workforce.", "url": "September 2026  |  Strictly Confidential" },
+
+    { "layout": "fourCards", "backup": true, "tag": "Why this is a category", "titleText": "Five advantages, not five features.",
+      "items": [
+        { "title": "Governance & orchestration", "body": "One policy, one identity, one audit trail across the whole estate." },
+        { "title": "Institutional IP", "body": "Every lesson compounds inside your perimeter, not ours." },
+        { "title": "Model agnostic", "body": "Any model, any cloud — no lock-in, sovereignty-friendly by design." },
+        { "title": "One registry", "body": "People and agents managed in the same system, by the same managers." }
+      ],
+      "notes": "BACKUP. Use only if the room asks why this is not another agent platform." }
+  ]
+}