@a-company/atelier 0.37.0 → 0.38.0

package/templates/workspace/SETUP.md

@@ -0,0 +1,127 @@
+# Workspace setup runbook
+
+> **For the agent team.** When the creator asks to "get set up" (or "run the
+> setup checklist", "am I ready to render", "check my environment"), work
+> through this file top to bottom. For each item: run the **Check**, judge it
+> against **Pass**, and if it fails, walk the creator through the **Fix** — then
+> re-run the Check to confirm. Do NOT skip steps silently. End with the
+> **Report** at the bottom: a ✓/✗/– line per item plus the single next action.
+>
+> Run the checks with the `Bash` tool. Surface command output verbatim when an
+> item fails — don't paraphrase errors. Detect the OS first (`uname`) so you
+> give the right install command (the Fixes below show macOS/Homebrew; on Linux
+> use the distro package manager, on Windows use winget/scoop or the installer
+> links).
+
+---
+
+## Required — the creator cannot render without these
+
+### 1. Claude Code
+- **Check:** You're running inside it, so this passes by definition.
+- **Pass:** This session exists.
+- **Fix:** n/a.
+
+### 2. Node.js 22+
+- **Check:** `node --version`
+- **Pass:** major version ≥ 22. (Everything below runs through `npx`, which needs
+  Node — so check this first.)
+- **Fix:** Install Node 22 LTS from <https://nodejs.org> (or `nvm install 22 && nvm use 22`).
+  Re-run the Check.
+
+### 3. Hyperframes + the render toolchain  ← the important one
+Hyperframes is the render engine (Iris drives it via `npx hyperframes preview` /
+`render`). There is **no manual install** — `npx` auto-fetches the published
+`hyperframes` package on first run. It ships its own dependency checker; use it
+as the authoritative check for the whole render toolchain:
+
+- **Check:** `npx --yes hyperframes doctor`
+- **Pass:** read the `✓ / ✗` lines it prints. You want `✓` on **FFmpeg**,
+  **FFprobe**, and **Chrome** (the three render-critical deps), plus Node and
+  adequate Disk/Memory.
+  > ⚠️ **`doctor` exits 0 even when a check fails.** Do NOT trust the exit code —
+  > judge by the `✗` markers in the output. Surface any `✗` line verbatim.
+- **Fix**, per failing line:
+  - **FFmpeg / FFprobe ✗** → macOS `brew install ffmpeg` (ships both); Debian/Ubuntu
+    `sudo apt install ffmpeg`; Windows `winget install Gyan.FFmpeg`. Required for the
+    render → `.mp4`/`.mov`/`.webm` mux and all audio. Re-run `doctor`.
+  - **Chrome ✗** → `npx --yes hyperframes browser install` (Hyperframes renders by
+    driving headless Chrome). Re-run `doctor`.
+  - **Low Memory / Disk ⚠** → renders may fail or run slowly; have the creator free
+    resources. Not a hard blocker.
+  - **`npx hyperframes` errors entirely** → confirm step 2 passed and the first run
+    can reach the npm registry (a corporate proxy may need `npm config set proxy`).
+
+---
+
+## Optional — enhances the workflow, not required to render
+
+### 5. Whisper (transcription)
+- **Check:** `whisper-cli --help 2>/dev/null || whisper-cpp --help 2>/dev/null || echo MISSING`
+- **Pass:** either binary responds. (Only needed if the creator will drop raw
+  recordings into `projects/<name>/media/` for auto-transcription.)
+- **Fix:** macOS `brew install whisper-cpp`; otherwise build whisper.cpp from
+  <https://github.com/ggerganov/whisper.cpp>. Safe to skip until the first recording.
+
+### 6. Paradigm learning loop (cross-session memory)
+- **Check:** `ls ~/.paradigm/notebooks/quill ~/.paradigm/notebooks/lux ~/.paradigm/notebooks/iris 2>/dev/null || echo MISSING`
+- **Pass:** all three notebook dirs exist → the team accumulates learning across
+  sessions. If MISSING, the agents still work fully from their workspace shims;
+  they just don't persist learning between sessions.
+- **Fix:** Install the Paradigm plugin and the Atelier personas (Quill / Lux /
+  Iris) into `~/.paradigm/`. This is optional — only set it up if the creator
+  wants the agents to get smarter over time. Don't block setup on it.
+
+---
+
+## Workspace verification — is THIS workspace intact?
+
+### 7. Scaffold integrity
+- **Check:** confirm these exist (use `Glob`/`ls`):
+  `workspace.atelier`, `_brand/`, `_packs/`, `projects/`,
+  `.claude/agents/atelier-quill.md`, `atelier-lux.md`, `atelier-iris.md`,
+  `.paradigm/personas/_shared/cascade-merge.md`, `CLAUDE.md`.
+- **Pass:** all present.
+- **Fix:** re-run `atelier workspace` in this folder — it's idempotent and
+  refreshes scaffold files without touching authored brand artifacts.
+
+### 8. Brand artifacts authored (not placeholders)
+- **Check:** read `_brand/DESIGN.md`, `_brand/SCRIPT.md`, `_brand/STORYBOARD.md`
+  and `_brand/.atelier-brand.yaml`; look for remaining `TODO` markers or template
+  placeholder text.
+- **Pass:** the brand reflects the creator's real palette / typography / voice.
+- **Fix:** offer to have **@atelier-quill** (voice + design) and **@atelier-lux**
+  (visual patterns) interview the creator and fill these in. Placeholders are not
+  a hard failure — flag them and move on.
+
+### 9. Fonts staged (if the brand uses custom fonts)
+- **Check:** if `_brand/.atelier-brand.yaml` names non-system fonts, confirm the
+  files exist under `_assets/fonts/<family>/`.
+- **Pass:** every named custom font is present locally.
+- **Fix:** stage the font files into `_assets/fonts/<family>/`. This is the
+  font-staging pattern — Hyperframes' render step does NOT reliably load web-CDN
+  fonts, so brand fonts must be local or renders fall back to a generic sans.
+
+---
+
+## Report
+
+Summarize like this, then state the single next action:
+
+```
+Atelier setup check
+  ✓ Node.js 22+              v22.x
+  ✓ Hyperframes             0.6.x (npx)
+  ✓ ffmpeg                  present
+  – Whisper                 not installed (optional — needed for transcription)
+  – Paradigm learning loop  not installed (optional)
+  ✓ Workspace scaffold      intact
+  ⚠ Brand artifacts         still has TODO placeholders
+  ✓ Fonts                   n/a (system fonts only)
+
+Next: your brand still has placeholders — want @atelier-quill to draft your
+voice + @atelier-lux your visual patterns? Or jump straight to a first project.
+```
+
+Use ✓ pass, ✗ required-and-failing (must fix before render), ⚠ works-but-attention,
+– optional-and-absent.

package/templates/workspace/_brand/.atelier-brand.yaml

@@ -0,0 +1,34 @@
+# {{WORKSPACE_NAME}} — structured brand overlay
+#
+# Agents read this for fields the markdown doesn't structure cleanly.
+# DESIGN.md / SCRIPT.md / STORYBOARD.md are the source of truth for prose;
+# this overlay captures the things agents query as data (palette, fonts,
+# whitelists, etc).
+#
+# Cascade: project-tier `projects/<name>/.atelier-overlay.yaml` extends this
+# per `.paradigm/personas/_shared/cascade-merge.md` (lists extend, scalars
+# override, maps override-at-key).
+
+name: "{{WORKSPACE_NAME}}"
+
+voice:
+  register: TODO         # one short phrase, e.g. clinical-editorial
+  tone: TODO             # e.g. confident-not-cocky
+  exemplars: []          # quill mirrors these tonally
+  do: []                 # tonal moves to make
+  dont: []               # tonal moves to never make
+
+visual:
+  primary_palette: [paper, ink, accent]
+  typography:
+    display: Inter
+    body: Inter
+  treatment:
+    photos: TODO         # e.g. high-key, generous negative space
+    motion: TODO         # e.g. gentle ease-out, never bounce
+  aspect: 9:16           # default canvas aspect (1080:1920); override per project
+
+techniques_whitelist:
+  - TODO
+techniques_blacklist:
+  - TODO

package/templates/workspace/_brand/DESIGN.md

@@ -0,0 +1,56 @@
+# {{WORKSPACE_NAME}} — Brand Design
+
+> **Workspace-tier brand design.** This file describes the durable visual + tonal
+> brand identity for **every** project under this workspace. Project-tier
+> `projects/<name>/DESIGN.md` overrides + extends per the cascade rules
+> (`.paradigm/personas/_shared/cascade-merge.md`).
+
+## Audience
+
+<!-- Who is this brand FOR? Specifics, not generics. Replace this placeholder. -->
+TODO — who watches / reads / interacts with this brand?
+
+## Voice register
+
+<!-- The tonal posture. One short paragraph. Examples: "clinical-editorial,
+     confident-not-cocky" / "warm-conversational, never preachy" / etc. -->
+TODO — describe the voice register.
+
+## Visual register
+
+<!-- The visual posture. One short paragraph. Examples: "editorial generosity,
+     restrained palette, type-led" / "kinetic-bold with primary-color blocks" -->
+TODO — describe the visual register.
+
+## Palette
+
+<!-- Brand colors with semantic roles. Hex values. Lux reads these to make
+     palette decisions; Iris emits these as `--brand-palette-<role>` CSS vars
+     in every Hyperframes scaffold. -->
+- `paper` — `#FFFFFF` — primary background
+- `ink` — `#000000` — primary foreground / text
+- `accent` — `#FF6B35` — single accent color used sparingly
+
+## Typography
+
+<!-- Brand fonts with usage. Lux reads these for typography staging; Iris emits
+     these as `--brand-font-<usage>` CSS vars. Use Hyperframes-compatible
+     fonts when possible (see https://hyperframes.mintlify.app/docs/fonts). -->
+- `display` — Inter — large headlines, hero copy
+- `body` — Inter — captions, body text, secondary copy
+
+## Constraints
+
+<!-- Hard rules. Lux and Iris MUST respect these. Examples:
+     - never use stock photography
+     - aspect is portrait 9:16 unless explicitly requested otherwise
+     - no exclamation marks in any on-screen copy -->
+- TODO — list the brand hard rules.
+
+## Success criteria
+
+<!-- How do we know a finished video is "on brand"? Specific signals creator
+     uses to evaluate output. Examples:
+     - viewer can identify the brand from the first 1.5s without a logo
+     - palette restraint never exceeds 3 hues per frame -->
+- TODO — list signals of brand-correct output.

package/templates/workspace/_brand/SCRIPT.md

@@ -0,0 +1,41 @@
+# {{WORKSPACE_NAME}} — Brand Voice
+
+> **Workspace-tier voice exemplars + do/don't.** Quill reads this as the
+> default voice for every project. Project-tier `projects/<name>/SCRIPT.md`
+> overrides + extends per the cascade rules.
+
+## Voice exemplars
+
+<!-- Real phrases that exemplify the brand voice. Quill mirrors these tonally
+     when drafting. Concrete > abstract. Three to five is enough.
+     Replace these placeholders with actual brand-voice samples. -->
+- TODO — exemplar 1 (real phrase the brand would say)
+- TODO — exemplar 2
+- TODO — exemplar 3
+
+## Do
+
+<!-- Tonal moves the brand SHOULD make. -->
+- TODO — e.g. "lead with the metric, not the brag"
+- TODO — e.g. "end on the actionable beat, not the inspirational one"
+
+## Don't
+
+<!-- Tonal moves the brand should NEVER make. -->
+- TODO — e.g. "no exclamation marks"
+- TODO — e.g. "no hype adjectives (amazing, incredible, game-changing)"
+
+## Default structure
+
+<!-- The brand's default short-form structure. Quill uses this unless overridden.
+     Default is hook → story → proof → CTA — replace if the brand prefers
+     a different shape. -->
+- hook
+- story
+- proof
+- CTA
+
+## Sign-off
+
+<!-- The brand's canonical closing beat / tagline / sign-off. Optional. -->
+TODO — closing beat if the brand has one (otherwise delete this section).

package/templates/workspace/_brand/STORYBOARD.md

@@ -0,0 +1,33 @@
+# {{WORKSPACE_NAME}} — Brand Storyboard Patterns
+
+> **Workspace-tier visual patterns.** Lux reads this for recurring storyboard
+> primitives the brand favors. Project-tier `projects/<name>/STORYBOARD.md`
+> overrides + extends per the cascade rules.
+
+## Signature transitions
+
+<!-- Named transitions the brand uses. Lux selects from this whitelist when
+     deciding scene-to-scene transitions. Each entry: name + when-to-use. -->
+- TODO — e.g. "hard-cut: between distinct beats"
+- TODO — e.g. "fade-under-vo: when voiceover continues across visual change"
+
+## Recurring frames
+
+<!-- Named frames the brand uses across episodes (intro shells, outro shells,
+     hero compositions). Lux references these by name in project storyboards
+     instead of redescribing each time. -->
+- TODO — e.g. "swiss-grid-3up: 3-column comparison hero"
+- TODO — e.g. "ken-burns-restrained: photographic still with gentle zoom"
+
+## Technique whitelist
+
+<!-- Visual techniques the brand allows. Lux picks from this list. -->
+- TODO — e.g. swiss-grid
+- TODO — e.g. ken-burns-restrained
+- TODO — e.g. fade-under-vo
+
+## Technique blacklist
+
+<!-- Visual techniques the brand never uses (overrides any whitelist). -->
+- TODO — e.g. glitch
+- TODO — e.g. kinetic-typography-heavy

package/templates/workspace/_packs/README.md

@@ -0,0 +1,54 @@
+# Asset Packs
+
+Asset packs are **folders + sidecars**. Each subdirectory here is a pack.
+Anywhere else on disk works too — register external folders via:
+
+```sh
+atelier pack register ~/Dropbox/Shared/CompanyBrand
+```
+
+(`atelier pack register` ships in a later release. For now, register by
+editing `workspace.atelier`'s `packs.external` list.)
+
+## Pack structure
+
+```
+_packs/<pack-name>/
+├── .atelier-pack.yaml         # required — sidecar describes what/when/how
+├── logos/                     # category folders (yours to name)
+├── photos/
+├── transitions/
+└── ...
+```
+
+## Sidecar shape
+
+See `.paradigm/personas/lux/skills/walk-asset-packs.md` for the canonical
+schema. Quick reference:
+
+```yaml
+name: swiss-grid
+owner: you
+vibe: editorial, clinical, generous whitespace
+categories:
+  logos:
+    when: full-screen reveals, watermarks
+    when_not: inline with body copy
+    treatment: monochrome on photos; full color on solid paper
+restrictions:
+  - never combine logos/ with grids/ in same frame
+```
+
+## Who reads packs
+
+- **Lux** (Cinematographer) walks `_packs/*/` to resolve asset slots when
+  storyboarding. Cites pack-relative paths or category descriptors in
+  STORYBOARD.md.
+- **Iris** (Composer) symlinks the cited pack assets into
+  `projects/<name>/assets/` at scaffold time.
+
+## What NOT to put here
+
+- Bytes you want to share publicly — packs are local-first (`TD-2026-05-26-271`)
+- Generated outputs — those live in `projects/<name>/out/`
+- Per-project raw recordings — those live in `projects/<name>/media/`

package/templates/workspace/projects/README.md

@@ -0,0 +1,49 @@
+# Projects
+
+Each subdirectory here is one **output series** — typically one video or a
+small batch of related variants (teaser-15s / trailer-30s / full-spot-60s
+sharing the same beat).
+
+## Project structure
+
+```
+projects/<name>/
+├── DESIGN.md                  # project overrides to workspace _brand/DESIGN.md
+├── SCRIPT.md                  # this project's actual script
+├── STORYBOARD.md              # this project's shot list
+├── .atelier-overlay.yaml      # optional — structured overrides to brand .yaml
+├── media/                     # raw recordings for this project
+├── transcripts/               # auto-generated from media/
+├── _packs/                    # optional — project-only packs (rare)
+└── (Iris emits these as needed)
+    ├── index.html             # Hyperframes composition
+    ├── assets/                # symlinks into media/ + _packs/
+    └── out/                   # final renders
+```
+
+## Creating a project
+
+Ask Quill in a Claude Code session:
+
+> @atelier-quill draft a 15s teaser for `<project-name>`
+
+Quill will scaffold `projects/<name>/` with starter DESIGN.md / SCRIPT.md /
+STORYBOARD.md that inherit the workspace `_brand/` voice + visual register
+via the cascade rules.
+
+## Cascade rules (TL;DR)
+
+When agents work in `projects/<name>/`, the **effective brand** they read is
+`_brand/<file>` (workspace) overlaid with `projects/<name>/<file>`:
+
+- **Strings** → project overrides workspace
+- **Lists** → project extends workspace (additive)
+- **Map bindings** → project overrides at the key, leaves siblings intact
+
+Full rules: `.paradigm/personas/_shared/cascade-merge.md`.
+
+## What NOT to put here
+
+- Brand-level rules (those go in `_brand/` — agents will prompt promotion when
+  they see something repeat across projects)
+- Pack bytes (those go in `_packs/<pack-name>/` or external pack folders)

package/templates/workspace/workspace.atelier

@@ -0,0 +1,22 @@
+# Atelier v2 workspace manifest.
+# Created by `atelier workspace`. Edit fields freely.
+#
+# A workspace is a brand container. It holds:
+#   - _brand/      brand artifacts (DESIGN/SCRIPT/STORYBOARD + .atelier-brand.yaml)
+#                  inherited by every project
+#   - _packs/      asset packs (folders with .atelier-pack.yaml sidecars)
+#                  visible to every project
+#   - projects/    output series (each a self-contained brief + Hyperframes scaffold)
+#
+# Agents (Quill / Lux / Iris) read the workspace from cwd. There is no
+# `.atelier/active.yaml` in v2 — explicit project arg or cwd determines scope.
+
+version: 2.0.0
+name: "{{WORKSPACE_NAME}}"
+created: "{{ISO_DATE}}"
+
+# External pack pointers — register folders anywhere on disk so agents can
+# resolve them under `_packs/<pack>/`. Add via `atelier pack register <dir>`.
+# (`atelier pack register` ships in a later release; for now edit by hand.)
+packs:
+  external: []

package/university/index.yaml

@@ -1,5 +1,5 @@
 version: '1.0'
-generatedAt: '2026-05-22T18:49:49.832Z'
+generatedAt: '2026-05-28T18:57:39.967Z'
 totalContent: 53
 entries:
   - id: N-atel-001-first-render