@liebstoeckel/cli 0.3.7

package/skill/references/authoring.md

@@ -0,0 +1,81 @@
+# Slide authoring conventions
+
+A deck is a project (under `presentations/<name>/`) with:
+
+- `index.html` — the page shell (a `<div id="root">` + the entry script). Rarely edited.
+- `main.tsx` — the **entry**: renders `<Present>` with the ordered slide list.
+- `slides/NN-name.tsx` (or `.mdx`) — one file per slide.
+- `charts/` — scaffolded components (owned source from `liebstoeckel add`). Most
+  registry items are charts and land here, but `add` writes each item to its manifest's
+  `target` (see `references/components.md`), so other component types may land elsewhere.
+- `package.json`, `build.ts`, `server.ts`, `bunfig.toml`.
+
+## A slide
+
+A slide is a module with a **default-exported React component**, optionally a
+**`notes`** export (presenter notes). The component renders onto a fixed
+**1280×720** canvas that is scaled to fit (author at that size; don't set your own
+viewport units for layout).
+
+```tsx
+// slides/02-growth.tsx
+import { BarChart } from "../charts/BarChart";
+
+export const notes = (
+  <div><p>Revenue tripled; call out Q4.</p></div>
+);
+
+export default function Growth() {
+  return (
+    <div className="flex h-full w-full flex-col justify-center px-24">
+      <h2 className="font-heading text-5xl text-text">Revenue grew 3×</h2>
+      <BarChart data={[{ label: "Q1", value: 128 }, { label: "Q4", value: 384 }]} />
+    </div>
+  );
+}
+```
+
+Use Tailwind classes and the brand tokens (`text-text`, `bg-surface`, `text-accent`,
+`border-border`, `font-heading`, `font-mono`). Charts already read the brand palette.
+
+## Wiring a slide into the deck (required)
+
+A new slide file does nothing until it's listed in `main.tsx`. Add an import and put
+it in the `slides` array **in display order**. To include a slide's `notes`, import it
+as a namespace; for component-only, a default import is fine:
+
+```tsx
+// main.tsx
+import * as intro from "./slides/01-intro";
+import * as growth from "./slides/02-growth";   // namespace → carries `notes`
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <Present title="Q4 Review" brands={["nocturne"]} slides={[intro, growth]} />
+  </StrictMode>,
+);
+```
+
+## Steps (progressive reveal)
+
+Wrap content in `<Step>` (from `@liebstoeckel/engine`) to reveal it across key
+presses:
+
+```tsx
+import { Step } from "@liebstoeckel/engine";
+// …
+<Step>▹ First point</Step>
+<Step>▹ Second point</Step>
+```
+
+## Brands
+
+`<Present brands={["nocturne"]} />` selects the active brand; `liebstoeckel new
+--brand <brand>` sets the default. Re-theming a deck = change the brand; every
+component and token follows. Don't hard-code hex colors — use tokens / `useBrandColors`.
+
+## MDX slides
+
+A slide can be `.mdx` instead of `.tsx` for prose-heavy content; it still
+default-exports its content and may `export const notes`. Import components at the top
+of the MDX as usual.

package/skill/references/build-plugins.md

@@ -0,0 +1,116 @@
+# Building a custom plugin
+
+Reach for this only when none of the built-ins (`poll`, `qa`, `reactions` — see
+`references/plugins.md`) fits. A custom plugin is a `definePlugin({ … })` value placed
+and registered exactly like a built-in; the three built-ins are good templates to copy.
+
+## Anatomy
+
+```tsx
+import { definePlugin, schema, t, type Infer, type ClientProps } from "@liebstoeckel/plugin-sdk";
+
+const mySchema = schema({
+  votes: t.record(t.string),   // participantId -> choice
+  closed: t.boolean,
+});
+type MyState = Infer<typeof mySchema>;
+
+export default definePlugin<MyState>({
+  id: "myplugin",              // what authors write as <Plugin id="myplugin" />
+  state: mySchema,             // the typed, synced CRDT state
+  client: {
+    Slide: MySlide,            // interactive UI (live)
+    fallback: MyFallback,      // static preview (offline + thumbnails)
+  },
+});
+```
+
+`definePlugin<T>({ id, state, server?, client })` — `id` names the plugin (and
+namespaces its state at `plugin:<id>`); the rest are below.
+
+## State schema (`state`)
+
+Build it with `schema({...})` and the `t` primitives:
+
+- `t.string`, `t.number`, `t.boolean`
+- `t.array(item)`
+- `t.object({ … })`
+- `t.record(value)` — a string-keyed map
+
+**Concurrency rule:** anything many participants write at once must be a **top-level
+`t.record`**, keyed by a composite string — there is no nested-record setter. For
+example, store votes as a top-level `votes: t.record(t.string)` keyed by `participantId`
+(or `"${questionId}|${participantId}"`), not as a nested object.
+
+### Reading & writing state
+
+The client and server receive a typed `state` accessor:
+
+```ts
+state.snapshot();                       // current value as plain JS (defaults filled in)
+state.set("closed", true);              // replace a whole top-level field
+state.recordSet("votes", pid, "Yes");   // set one entry of a top-level record field
+state.recordDelete("votes", pid);       // remove one entry
+state.ensureDefaults({ … });            // seed defaults once, only if state is empty
+const off = state.subscribe((snap) => …);   // observe deep changes; returns unsubscribe
+```
+
+## Client surfaces (`client`)
+
+`ClientProps<T>` is passed to every client component:
+`{ doc, state, snapshot, role, live, participantId, theme, ui, props, instance }`
+(`role` is `"presenter" | "viewer"`; `props` is the author's `<Plugin props={…}>`).
+
+| field          | renders when / what                                                      |
+|----------------|--------------------------------------------------------------------------|
+| `Slide`        | live: the interactive in-deck UI (audience + presenter)                  |
+| `fallback?`    | offline `.html` + thumbnails — show real content from `snapshot`/`props` |
+| `presenter?`   | a tab in the presenter view: `{ label, icon?, badge?, title?, Console }` for live readout + privileged moderation |
+| `global?`      | deck-wide surfaces: an `Overlay`, plus a chrome control (`icon`+`label`) toggling a `Panel`. `pinned` keeps it in the mobile rail; `panelMode: "sheet"` opens full-viewport on touch |
+| `surfaces?`    | named override points an author may replace per placement (`<Plugin components={{ … }}>`) |
+| `interactive?` | `false` to suppress the mobile tap-to-interact breakout (display-only)   |
+
+### Canvas constraint
+
+A slide renders on a fixed **1280×720 canvas** that is scaled to fit and **clipped**
+(`overflow: hidden`) — it never scrolls, so the audience, presenter, and thumbnail views
+stay pixel-identical. **Pin your header/input and scroll the growing part yourself**
+using `ScrollArea` from `@liebstoeckel/plugin-ui`.
+
+## UI kit — `@liebstoeckel/plugin-ui`
+
+Brand-token-aware primitives so plugin UI matches the active theme automatically:
+
+`Card`, `Button`, `Bar` (result bar), `Stack`, `ScrollArea`, `Eyebrow`, `ChromeButton`,
+plus `useTheme()` / `readTheme()` for the resolved tokens. Prefer these over raw markup.
+
+## Optional server part (`server`)
+
+Only if the plugin needs host-side logic the audience's browsers can't do (compute an
+official result, reach a secret/external HTTP). It runs **once**, on the machine running
+`liebstoeckel live` — never in audience browsers, never on the relay.
+
+```ts
+import type { PluginServerCtx } from "@liebstoeckel/plugin-sdk";
+import { pluginState } from "@liebstoeckel/plugin-sdk";
+
+export default function server(ctx: PluginServerCtx<MyState>) {
+  const state = pluginState(ctx.doc, "myplugin", mySchema);
+  const stop = state.subscribe((snap) => {
+    // host-only work; write results back to shared state
+  });
+  return () => stop();   // optional teardown
+}
+```
+
+`PluginServerCtx<T>` = `{ doc, state, session: { id }, instance }`. At build time the
+server entry is bundled and embedded in the deck; a live server decodes and runs it with
+an injected `ctx`. Because it executes on the presenter's machine, decks are trust-gated
+(`references/plugins.md`).
+
+## After authoring
+
+Register and place it like any built-in (see `references/plugins.md`), then run the
+`liebstoeckel build --check` loop until clean.
+
+Full guide with worked examples: https://docs.liebstoeckel.app/llms.txt

package/skill/references/components.md

@@ -0,0 +1,107 @@
+# Components: discover, scaffold, wire data
+
+Components come from the registry as **owned source** — `liebstoeckel add` copies the
+file into the deck and installs whatever npm packages it needs. After that the file is
+yours to edit.
+
+## Component types
+
+The registry is not just charts. Each item declares a `type` (one of the categories
+below), and `add` writes it to wherever that item's manifest points — the **target path
+is the manifest author's choice, not a fixed `charts/` rule**.
+
+| category   | `type`              | what it is                                        |
+|------------|---------------------|---------------------------------------------------|
+| `chart`    | `registry:chart`    | a data-viz component (visx-based)                 |
+| `element`  | `registry:element`  | a smaller building block (axis, legend, …)        |
+| `hook`     | `registry:hook`     | a reusable hook (e.g. brand palette access)       |
+| `component`| `registry:component`| a general UI component                            |
+| `layout`   | `registry:layout`   | a slide-layout component                          |
+| `motion`   | `registry:motion`   | an animation helper                               |
+| `brand`    | `registry:brand`    | brand/theme tokens                                |
+
+Today the catalog is **chart-heavy** — most items are charts, alongside a couple of
+chart `element`s (`brand-axis`, `legend`) and the `use-brand-colors` `hook` — and those
+all land under the deck's `charts/`. But more types can be added, and they land wherever
+their manifest's `target` says. **Don't assume the category from the folder; read the
+`type` from the registry.**
+
+`liebstoeckel add` also resolves `registryDependencies`, so adding a chart pulls in the
+`element`s and `hook`s it depends on automatically — you rarely add those by hand.
+
+## 1. Discover (always, before using a component)
+
+```bash
+liebstoeckel registry list --json          # whole catalog: name, type, dataShape
+liebstoeckel registry view <name> --json   # one item: exports, props, dataShape, example
+```
+
+`registry view` returns the authoritative contract:
+
+```jsonc
+{
+  "name": "bar-chart",
+  "type": "registry:chart",
+  "meta": {
+    "exports": "BarChart",
+    "props": "{ data?: BarChartDatum[]; width?: number; height?: number }",
+    "dataShape": "{ label: string; value: number }[]",
+    "example": "<BarChart data={[{ label: 'Q1', value: 128 }]} />"
+  }
+}
+```
+
+Use `exports` for the import name (note some differ from the id — e.g. the `treemap`
+item exports **`TreemapChart`**), and shape your data to `dataShape` exactly. A `hook`
+or `element` has the same `meta` contract — read `exports`/`props`/`example` the same
+way; only `chart`s carry a `dataShape`.
+
+## 2. Scaffold
+
+```bash
+liebstoeckel add <name> --dir ./presentations/<deck>
+liebstoeckel add <category> <name> --dir …   # optional sugar: `add chart bar-chart`
+# JSON when piped: { action, wrote[], skipped[], dependencies[], installed }
+```
+
+`add` is idempotent — existing files are reported as `skipped` (pass `--force` to
+overwrite something you've since edited). It also pulls in any `registryDependencies`
+(e.g. every chart pulls `use-brand-colors`). Preview without writing: `add <name>
+--dry --json` — the `wrote[]`/plan shows the exact target paths, so you never have to
+guess where a component landed.
+
+## 3. Use it in a slide
+
+Import from wherever `add` wrote it (the `wrote[]` paths) and pass data matching
+`dataShape`:
+
+```tsx
+import { BarChart } from "../charts/BarChart";
+// …
+<BarChart data={[{ label: "Q1", value: 128 }, { label: "Q2", value: 174 }]} />
+```
+
+Notes (chart specifics):
+
+- Charts size to a `width`/`height` prop (defaults provided); wrap in a sized
+  container or pass explicit numbers for grids of charts.
+- `sparkline` requires a unique `id` prop.
+- `stacked-bar-chart` / `grouped-bar-chart` take a `keys: string[]` listing the series.
+- All charts read the active brand palette — no color props needed.
+
+## 4. Adjust the component to fit the slide (encouraged)
+
+A scaffolded file is **the deck's own source**, not a fixed package API. Wiring data
+through props is the common case, but when the slide needs more, **open the file and
+change it** — that's why it was copied in, not imported. Common adjustments (charts):
+
+- **Palette** — recolor a series, or map a category to a brand color (`useBrandColors`
+  gives `c.viz[]`, `c.accent`, …).
+- **Shape** — add/remove a series, change the axis range, add a reference line,
+  threshold band, or label/annotation.
+- **Chrome** — drop the legend, change the value-label format, restyle the axis.
+- **Motion** — retime or remove the entrance animation.
+
+Re-running `liebstoeckel add <name>` will **not** overwrite your edits unless you pass
+`--force` (which restores the pristine registry version). So edit freely — your copy is
+yours. Prefer adjusting the component over contorting the data or fighting the props.

package/skill/references/editing.md

@@ -0,0 +1,78 @@
+# Editing an existing deck
+
+Find the deck (a dir with `main.tsx` + `slides/`). The slide order is the `slides`
+array in `main.tsx`.
+
+## Trust: building runs the deck's code
+
+A deck is **code**. Building it (`build`, `build --check`, the `eject` rebuild,
+`licenses` from source) executes the deck's build-time modules on this machine with
+full filesystem and network access. A deck scaffolded here via `liebstoeckel new` is
+trusted automatically; a deck you did **not** create here (cloned, downloaded, handed
+over) is **untrusted**, and a non-interactive build of it fails fast:
+
+```json
+{ "ok": false, "error": "untrusted deck", "hint": "…re-run with --trust…" }
+```
+
+**You MUST NOT silence this yourself.** Never pass `--trust` or set
+`LIEBSTOECKEL_TRUST_BUILD=1` on your own initiative — that is a security decision the
+user owns, not you. When you hit this error, **stop and ask the user** whether they
+trust this specific deck, and only re-run with `--trust` after they explicitly say yes.
+If they don't confirm, do not build it.
+
+## Add a slide
+
+1. Create `slides/NN-name.tsx` (pick `NN` for its position) with a default-exported
+   component (see `authoring.md`).
+2. Import it in `main.tsx` and insert it into the `slides` array at the right spot.
+3. `liebstoeckel build --check` until clean.
+
+## Replace / rewrite a slide
+
+Edit the slide file in place. If you change what data a chart needs, keep the data
+matching the chart's `dataShape` (`registry view <name> --json`).
+
+## Add a chart to an existing slide
+
+```bash
+liebstoeckel registry view <name> --json
+liebstoeckel add <name> --dir <deck>
+```
+Then import it from `../charts/` and pass data. If `add` reports the file as
+`skipped`, the chart is already in the deck — just import and use it.
+
+## Remove a slide
+
+Delete the file and remove its import + array entry from `main.tsx`.
+
+## Re-theme
+
+Change the brand in `main.tsx`'s `<Present brands={["…"]}>` (and/or run with a
+different brand). Every chart and token follows; don't hand-edit colors.
+
+## Recover source from a built `.html` (eject)
+
+`eject` reverses a `build`: it unpacks the editable project (the `main.tsx`, `slides/`,
+`charts/`, assets) that was inlined into a single `.html`, so you can edit a deck you
+only have as a built file. The result is a normal deck directory — edit it with the
+workflows above, then rebuild.
+
+```bash
+liebstoeckel eject <deck.html> [outdir]   # default outdir: <deck>-source; --force to overwrite
+cd <outdir>
+bun install --ignore-scripts             # installs deps WITHOUT running npm lifecycle scripts
+liebstoeckel build                       # rebuild to a single .html
+```
+
+`--ignore-scripts` only blocks npm lifecycle scripts — it does **not** sandbox the deck:
+`build` still runs the deck's own macros and build plugins. An ejected deck is **not**
+trusted (only `liebstoeckel new` auto-trusts), so this rebuild hits the trust gate. Per
+the trust rule above: if it fails with `untrusted deck`, **ask the user** — never add
+`--trust` yourself.
+
+## Always finish with the check loop
+
+```bash
+liebstoeckel build --check --dir <deck>   # fix diagnostics, repeat until ok:true
+```

package/skill/references/plugins.md

@@ -0,0 +1,121 @@
+# Adding live plugins to a deck
+
+Plugins make a deck **interactive when presented live**: poll voting, an audience
+Q&A queue, floating reactions. The same deck still builds to one self-contained
+`.html` — offline it renders a static **fallback** preview of each plugin; in a live
+session the real, synced UI takes over.
+
+**Plugins are not in the registry.** Don't run `registry list/view` for them — that
+catalog is charts/elements/hooks only. The built-ins and their props are listed here
+and in `SKILL.md`; that is the contract.
+
+## The built-ins
+
+| id          | package                          | props                                  |
+|-------------|----------------------------------|----------------------------------------|
+| `poll`      | `@liebstoeckel/plugin-poll`      | `{ question: string; options: string[] }` |
+| `qa`        | `@liebstoeckel/plugin-qa`        | `{ prompt?: string }` (default `"Ask a question"`) |
+| `reactions` | `@liebstoeckel/plugin-reactions` | _none_                                 |
+
+## Wiring is two steps (both required)
+
+A `<Plugin>` tag alone does nothing. The plugin must also be a dependency **and**
+registered on `<Present>`.
+
+### 1. Depend + register in `main.tsx`
+
+Scaffolded decks ship **no** plugin packages, so add the ones you use:
+
+```bash
+bun add @liebstoeckel/plugin-poll @liebstoeckel/plugin-qa @liebstoeckel/plugin-reactions
+```
+
+Then import each (default export) and pass the set to `<Present plugins={…}>`:
+
+```tsx
+// main.tsx
+import { Present } from "@liebstoeckel/engine";
+import poll from "@liebstoeckel/plugin-poll";
+import qa from "@liebstoeckel/plugin-qa";
+import reactions from "@liebstoeckel/plugin-reactions";
+
+<Present
+  title="Q4 Review"
+  brands={["nocturne"]}
+  plugins={[poll, qa, reactions]}   // ← register every plugin you place
+  slides={[…]}
+/>
+```
+
+### 2. Place `<Plugin>` on a slide
+
+```tsx
+import { Plugin } from "@liebstoeckel/engine";
+
+// poll
+<Plugin id="poll" props={{ question: "What should we build next?", options: ["A", "B", "C"] }} />
+
+// q&a
+<Plugin id="qa" props={{ prompt: "What should we dig into?" }} />
+
+// reactions (no props)
+<Plugin id="reactions" />
+```
+
+`<Plugin>` full signature:
+
+```tsx
+<Plugin
+  id="poll"                 // required — matches the plugin's id
+  instance="pace"           // optional — independent state slice (see below)
+  title="…"                 // optional — presenter-tab label for sibling instances
+  props={{ … }}             // optional — author config passed to the plugin
+  components={{ … }}        // optional — per-placement surface overrides
+/>
+```
+
+## Per-plugin notes
+
+- **poll** — one shared poll per `id`. For **several independent polls**, give each a
+  stable `instance` (their votes/options stay separate, and each gets its own presenter
+  tab):
+  ```tsx
+  <Plugin id="poll" instance="pace" props={{ question: "How's the pace?", options: ["Slow", "Right", "Fast"] }} />
+  ```
+- **qa** — also exposes a deck-wide 💬 panel, so the audience can ask from **any
+  slide**; a dedicated Q&A slide is optional. The presenter moderates (mark answered /
+  dismiss) from the presenter console.
+- **reactions** — emoji float deck-wide over **every** slide once placed; ephemeral
+  (self-pruning, rate-limited). No configuration, no presenter tab.
+
+## Validate: registration is not build-checked
+
+`liebstoeckel build --check` catches a missing **import** (`Could not resolve
+"@liebstoeckel/plugin-poll"`), but it does **not** catch a `<Plugin id="poll">` that
+was never added to `<Present plugins>` — that placement silently falls back to the
+offline preview. So after the check passes, confirm by eye: **every `id` you placed
+appears in the `plugins={[…]}` array.**
+
+## Present it live (how to see plugins activate)
+
+Built or opened directly, a deck shows only fallbacks. Plugins go live with:
+
+```bash
+liebstoeckel live <deck-dir|deck.html>     # LAN: prints presenter + audience links
+```
+
+Open the **presenter** link yourself; share the **audience** link (or its QR). Slide
+navigation and all plugin state sync in real time. Present to a remote audience through
+a public relay:
+
+```bash
+liebstoeckel live <deck> --relay <https://relay-host> --relay-token <token>
+```
+
+**Trust model:** a deck's server-side plugin code (if any) runs **on the presenter's
+machine** — never on the relay. `liebstoeckel live` prints a trust warning for this
+reason; only run decks you trust.
+
+## Building your own plugin
+
+See `references/build-plugins.md` — only needed when no built-in fits.

package/skill/references/troubleshooting.md

@@ -0,0 +1,39 @@
+# The check loop & common errors
+
+`liebstoeckel build --check` is your correctness gate. It validates the deck
+**bundles** (imports resolve, MDX/TSX transforms, visx interop holds) and returns
+structured diagnostics. It does **not** type-check.
+
+```bash
+liebstoeckel build --check --dir <deck>
+# { "ok": true, "diagnostics": [] }
+# or
+# { "ok": false, "diagnostics": [ { "level": "error", "message": "...", "file": "...", "line": 12 } ] }
+```
+
+Loop: run it, fix each `diagnostic` (use `file`/`line`/`message`), re-run until
+`ok` is `true`. Only then `build` / `export`.
+
+## Common diagnostics
+
+- **`Could not resolve "X"`** — a missing dependency. If `X` is a chart you used,
+  run `liebstoeckel add <chart> --dir <deck>`. If it's a node module, run
+  `bun install` in the deck. A relative path means a wrong import path to a slide or
+  `charts/` file.
+- **`Could not resolve "../charts/Foo"`** — you imported a chart you haven't
+  scaffolded, or used the wrong export name. Check `registry view <name> --json`
+  (the `exports` field is the symbol; the file is `charts/<Exports>.tsx`).
+- **Element type is invalid / undefined component** — usually a wrong import name
+  (default vs named) or a chart used before `add`. Confirm the export name from
+  `registry view`.
+- **A blank or mis-laid-out slide** — author to the 1280×720 canvas; don't rely on
+  `vh`/`vw` for layout, and give charts a sized container or explicit `width`/`height`.
+
+## Verifying the visual result
+
+`build --check` proves it compiles, not that it looks right. To eyeball it, build and
+export a slide to PNG:
+
+```bash
+liebstoeckel export <deck> --slides 1 -o ./out     # PNG of slide 1 at 2560×1440
+```