reelson 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to reelson. The format follows [Keep a Changelog](https://ke
 versions follow [Semantic Versioning](https://semver.org/) (before 1.0, a minor version may change
 `video.json` or `demo.config.json`; the notes say how to update).
 
+## 0.7.2 — 2026-09-23
+
+The first release published by CI (staged, then approved on npm).
+
+### Changed
+- The README clip is re-rendered by CI on every push to main and served from the rolling `demo`
+  pre-release, so the npm package no longer ships it (2.6 MB → about 0.3 MB).
+- Hardened publishing: actions pinned to commit SHAs (Dependabot keeps them current, npm updates
+  after a 7-day cooldown), npm pinned, no install scripts or cache in the publish job, no token left
+  in the checkout, and the publish runs in the `npm` environment (approval before each release).
+  CI only **stages** a release (`npm stage publish`); it goes live once approved on npm with 2FA.
+- README: a pipeline diagram that renders the same in every font, commands with their notes above them.
+
+## 0.7.1 — 2026-09-23
+
+### Changed
+- **Works with any agent that reads Agent Skills**, not only Claude Code: `reelson install` links the
+  skills into `.agents/skills/` (Codex and others) and links `.claude/skills/` to them (nothing to do
+  when the whole `.claude/skills` folder already links to `.agents/skills`); `--global` does the same
+  in the home folder. New `demo.config.json` `$schema` paths and scenario imports go through
+  `.agents/skills`; existing `.claude/skills` paths keep working. The `.gitignore` hint adds the links.
+- **`reelson install` asks where** when neither `--global` nor a folder is given: every project
+  (the default: `~/.agents/skills` + `~/.claude/skills`), this project, or another folder. `-y` takes
+  the default; without a terminal it never asks. (0.7.0 installed into the current folder.)
+- Agent-neutral wording in the README, the skills and the prompting guide.
+
 ## 0.7.0 — 2026-09-23
 
 The first release on npm.

package/README.md

@@ -1,7 +1,8 @@
 # reelson
 
 Turn a prompt into a finished, branded demo video of a web app. Two
-[Claude Code](https://claude.com/claude-code) skills plus a `reelson` CLI:
+[Agent Skills](https://agentskills.io) plus a `reelson` CLI, for Claude Code, Codex or any agent
+that reads `SKILL.md` skills:
 
 | Skill                                    | Does                                                                        | Output                                   |
 |------------------------------------------|-----------------------------------------------------------------------------|------------------------------------------|
@@ -11,16 +12,24 @@ Turn a prompt into a finished, branded demo video of a web app. Two
 The same prompt re-creates the video after a UI change: a scenario re-records in ~20 s,
 headless, with identical pacing, and callouts/zooms follow their markers and clicks.
 
-![The TodoMVC example: poster intro, the recorded walkthrough with callouts and zooms, recap and outro](https://cdn.jsdelivr.net/npm/reelson/docs/demo.webp)
+![The TodoMVC example: poster intro, the recorded walkthrough with callouts and zooms, recap and outro](https://github.com/reelson/reelson/releases/download/demo/demo.webp)
 
-<sub>The [example](examples/todo-add-item/scenario.ts), rendered by CI on every push
-(`docs/demo.webp` is a 960 px cut of it).</sub>
+<sub>The [TodoMVC example](examples/todo-add-item/scenario.ts), recorded and rendered by CI on every
+push to main.</sub>
 
 ```
-scenario.ts ──reelson record──▶ recording.mp4 + markers.json
-                                          │
-video.json (title, trim, callouts, zooms) ┴──reelson build──▶ video/ ──reelson render──▶ .mp4 / .gif
-          demo.config.json (brand, logo, language, music) + template + sections ┘
+scenario.ts
+    |  reelson record
+    v
+recording.mp4 + markers.json
+    |  reelson build  <--  video.json        (title, trim, callouts, zooms)
+    |                 <--  demo.config.json  (brand, logo, language, music)
+    |                 <--  template + sections
+    v
+video/                     a HyperFrames project
+    |  reelson render
+    v
+video/renders/<slug>.mp4   + .gif, portrait, square, .srt/.vtt captions
 ```
 
 ## Requirements
@@ -34,24 +43,33 @@ video.json (title, trim, callouts, zooms) ┴──reelson build──▶ video/
 
 ```bash
 npm install -g reelson
-reelson install ~/code/my-app     # or: reelson install --global  (~/.claude/skills, every project)
+reelson install        # asks: every project (default), this project, or another folder
 ```
 
-`reelson install` downloads Playwright's Chromium, links both skills into
-`my-app/.claude/skills/`, creates `my-app/demo.config.json` and prints the `.gitignore` lines.
-The links point at the installed package, so `npm update -g reelson` updates every project.
+`reelson install` downloads Playwright's Chromium and links both skills into `.agents/skills/`
+(Codex and the other agents that read Agent Skills) and `.claude/skills/` (Claude Code, linked to
+the first — or nothing to do when the whole folder already links to `.agents/skills`):
+
+- **every project**: in `~/.agents/skills` and `~/.claude/skills` (`reelson install --global`);
+  run `reelson init` in a project for its `demo.config.json`;
+- **one project**: in `my-app/.agents/skills` and `my-app/.claude/skills`
+  (`reelson install ~/code/my-app`); also creates `my-app/demo.config.json` and prints the
+  `.gitignore` lines.
+
+`-y` takes the default without asking; without a terminal (CI, scripts) it never asks. The links
+point at the installed package, so `npm update -g reelson` updates every project.
 
 To work on reelson itself, install from a checkout instead: the `reelson` command then runs the
 TypeScript sources directly and `git pull` updates every project.
 
 ```bash
 git clone git@github.com:reelson/reelson.git ~/reelson
-~/reelson/install.sh ~/code/my-app     # npm link + reelson install
+~/reelson/install.sh     # npm link + reelson install (same question; or --global / <project-dir>)
 ```
 
 reelson was called reelkit before 0.7. Re-run `reelson install` (or `install.sh`) for each project: it drops the old
 `reelkit` command and `reelkit-*` skill links. Then point scenario imports and `$schema` paths
-at `.claude/skills/reelson-*`.
+at `.agents/skills/reelson-*` (`.claude/skills/reelson-*` works too).
 
 ## Configure per project — `demo.config.json`
 
@@ -87,7 +105,7 @@ typo is an error with a "did you mean" hint).
 
 ## Use
 
-Ask Claude in the project, e.g.:
+Ask your agent in the project, e.g.:
 
 > Make a demo video of searching a customer. Admin area on https://app.test as the admin.
 > Steps: open Customers, type a name in the table search, hover the match. Title "Find a
@@ -97,18 +115,30 @@ More prompts in [docs/prompting.md](docs/prompting.md); the rules every video fo
 [docs/style-guide.md](docs/style-guide.md). By hand:
 
 ```bash
-reelson doctor                                          # tools + cursor/footage sync on this machine
-reelson new customers-search --url https://app.test    # scenario stub
-reelson record customers-search [--headed]            # --mobile / --square: the takes for --portrait / --square; --all-takes: all three
-reelson build customers-search --title "Find a customer"   # creates video.json on first run
-#   edit video.json: callout wording, { "clicks": [2, 3], "scale": 1.8 } zooms, trim ("auto" or a marker)
-reelson voice customers-search                          # "voice": true in video.json: speak the callouts (voice.provider: openai, elevenlabs, piper, command)
-reelson check customers-search                          # schemas, zoom timing, hyperframes lint
-reelson verify --all                                    # after an app change: every demo still records and fits
-reelson studio customers-search                         # preview + edit on a layer timeline (saves video.json)
-reelson templates                                       # templates and intro/recap/outro sections
-reelson render customers-search [--gif] [--square] [--portrait] [--all-formats] [--draft]   # + .srt/.vtt captions
-reelson render --all                                    # every demo; skips the unchanged ones
+# tools + cursor/footage sync on this machine
+reelson doctor
+# a scenario stub
+reelson new customers-search --url https://app.test
+# --mobile / --square: the takes for --portrait / --square; --all-takes: all three
+reelson record customers-search [--headed]
+# creates video.json on the first run; then edit it: callout wording,
+# { "clicks": [2, 3], "scale": 1.8 } zooms, trim ("auto" or a marker)
+reelson build customers-search --title "Find a customer"
+# "voice": true in video.json: speak the callouts
+# (voice.provider: openai, elevenlabs, piper, command)
+reelson voice customers-search
+# schemas, zoom timing, hyperframes lint
+reelson check customers-search
+# after an app change: every demo still records and fits
+reelson verify --all
+# preview + edit on a layer timeline (saves video.json)
+reelson studio customers-search
+# templates and intro/recap/outro sections
+reelson templates
+# the MP4 + .srt/.vtt captions; --gif, --square, --portrait, --all-formats, --draft
+reelson render customers-search
+# every demo; skips the unchanged ones
+reelson render --all
 ```
 
 Per video, commit `scenario.ts`, `markers.json` and `video.json`; everything else is generated.
@@ -155,10 +185,28 @@ Node will not run TypeScript from under `node_modules`, so the package ships `.j
 each `.ts` (`npm run build`; `npm pack` / `npm publish` build first and clean up after).
 `bin/run.js` picks the compiled CLI when installed from npm and the sources in a checkout.
 
-1. Bump `version` in package.json, commit, tag `vX.Y.Z` and push the tag.
-2. [.github/workflows/publish.yml](.github/workflows/publish.yml) runs the checks and publishes
-   with npm trusted publishing (OIDC, with provenance; no token). Set it up once on npmjs.com →
-   the package → Settings → Trusted publishing: GitHub Actions, `reelson/reelson`, `publish.yml`.
+1. Add the release to CHANGELOG.md, then `npm version patch` (or `minor` / `major`: bumps
+   package.json, commits, tags `vX.Y.Z`) and `git push --follow-tags`.
+2. [.github/workflows/publish.yml](.github/workflows/publish.yml) checks the tag matches
+   package.json, runs the checks and **stages** the release with npm trusted publishing (OIDC: no
+   npm token exists anywhere; with provenance). It runs in the `npm` environment, so it first
+   waits for a required reviewer on GitHub.
+3. Approve it on npm with 2FA: `npm stage list reelson`, then `npm stage approve <id>` (or on
+   npmjs.com). Until then nobody can install it.
+
+One-time setup:
+
+- npmjs.com → the package → Settings → **Trusted publisher**: GitHub Actions, `reelson` /
+  `reelson`, workflow `publish.yml`, environment `npm`, **"Allow npm publish" off** (it may only
+  stage). Under **Publishing access**, pick "Require two-factor authentication and disallow
+  bypass 2fa tokens".
+- GitHub → Settings → **Environments** → `npm`: add yourself as a required reviewer and allow
+  only `v*` tags to deploy. Settings → Rules → **Rulesets**: restrict creating `v*` tags to
+  yourself. (Both need a public repository, or a paid plan for a private one.)
+
+The workflows pin every action to a commit SHA ([Dependabot](.github/dependabot.yml) proposes
+updates weekly, npm packages after a 7-day cooldown), install dependencies without install
+scripts when publishing, and never leave a token in the checkout.
 
 The very first release has to be published by hand (trusted publishing needs the package to
 exist): `npm login && npm publish`. Check the contents first with `npm pack --dry-run`.
@@ -171,7 +219,7 @@ skills/
   reelson-record/  SKILL.md, scripts/ (record, scenario, cursor-overlay, config, validate), schemas/
   reelson-compose/   SKILL.md, scripts/ (build, check, timeline, zooms, composition, project, hyperframes),
                 schemas/, templates/<name>/ (stages), sections/<slot>/<name>/
-docs/           style-guide.md, prompting.md, demo.webp (the README clip)
+docs/           style-guide.md, prompting.md
 examples/       demo.config.json + todo-add-item/ (scenario, markers, video.json)
 test/           unit + golden tests, fixtures
 music/          local-only tracks (git-ignored; licences are per project)

package/bin/reelson.js

@@ -5,12 +5,13 @@
  * demo.config.json (walking up from the working directory).
  */
 import { spawnSync } from 'node:child_process';
-import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
+import { createInterface } from 'node:readline/promises';
 import { basename, relative, resolve } from 'node:path';
 import { parseArgs, parseEnv } from 'node:util';
-import { CONFIG_SCHEMA_PATH, ConfigError, fromRoot, loadConfig } from "../skills/reelson-record/scripts/config.js";
+import { CONFIG_SCHEMA_PATH, ConfigError, fromRoot, loadConfig, viaProjectSkills } from "../skills/reelson-record/scripts/config.js";
 import { doctor } from "../skills/reelson-record/scripts/doctor.js";
 import { build, plan } from "../skills/reelson-compose/scripts/build.js";
 import { captionCues, toSrt, toVtt } from "../skills/reelson-compose/scripts/captions.js";
@@ -26,11 +27,13 @@ const HELP = `reelson — scripted walkthroughs → branded demo videos
 
 Usage: reelson <command> [options]
 
-  install [<project-dir>] [--global] [--no-browser]
+  install [<project-dir> | --global] [-y] [--no-browser]
                                 link the reelson-record + reelson-compose skills into
-                                <project>/.claude/skills/ (default: this directory; --global:
-                                ~/.claude/skills/), create demo.config.json if missing and
-                                download Playwright's Chromium (--no-browser: skip it)
+                                .agents/skills/ (Codex and other agents) and .claude/skills/
+                                (Claude Code): --global in ~/ for every project, or in a
+                                project (which also gets a demo.config.json); asks which when
+                                neither is given (-y, or no terminal: --global). Downloads
+                                Playwright's Chromium (--no-browser: skip it)
   init                          create demo.config.json in this directory
   doctor                        check the tools and that the cursor layer lines up here
   new <slug> [--url <origin>]   start <videosDir>/<slug>/scenario.ts
@@ -119,7 +122,7 @@ async function run(cmd, argv) {
             console.log(JSON.parse(readFileSync(resolve(KIT_ROOT, 'package.json'), 'utf8')).version);
             return 0;
         case 'install':
-            return install(argv);
+            return await install(argv);
         case 'init':
             return init();
         case 'doctor':
@@ -176,22 +179,25 @@ function one(positionals, usage) {
     return positionals[0];
 }
 /**
- * `reelson install`: links the skills into a project (or ~/.claude) and prepares the machine. The links
+ * `reelson install`: links the skills into a project (or the home folder) and prepares the machine. The links
  * point at this installation, so `npm update -g reelson` (or `git pull` in a checkout) updates every project.
  */
-function install(argv) {
+async function install(argv) {
     const skillNames = ['reelson-record', 'reelson-compose'];
     // Names used before 0.7 (demo-* before that): their links are dropped when they point at a reelson install.
     const oldNames = ['demo-record', 'demo-video', 'reelkit-record', 'reelkit-compose'];
     const { values, positionals } = parseArgs({
         args: argv,
         allowPositionals: true,
-        options: { global: { type: 'boolean' }, 'no-browser': { type: 'boolean' } },
+        options: { global: { type: 'boolean' }, yes: { type: 'boolean', short: 'y' }, 'no-browser': { type: 'boolean' } },
     });
     if (positionals.length > 1 || (values.global && positionals.length)) {
-        throw new ReelsonError('usage: reelson install [<project-dir> | --global] [--no-browser]');
+        throw new ReelsonError('usage: reelson install [<project-dir> | --global] [-y] [--no-browser]');
     }
-    const target = values.global ? homedir() : resolve(positionals[0] ?? '.');
+    // Asked only when neither --global nor a folder is given and someone is at the terminal.
+    const where = values.global ? null : positionals.length ? resolve(positionals[0]) : values.yes || !process.stdin.isTTY ? null : await askWhere();
+    const global = where === null;
+    const target = where ?? homedir();
     if (!existsSync(target)) {
         throw new ReelsonError(`${target} does not exist`);
     }
@@ -206,43 +212,94 @@ function install(argv) {
             throw new ReelsonError('could not install Chromium — run `npx playwright install chromium`');
         }
     }
-    const skills = resolve(target, '.claude/skills');
-    mkdirSync(skills, { recursive: true });
+    // .agents/skills links to this installation; .claude/skills links to .agents/skills (unless the
+    // whole folder already is a link to it), so both agents see the same skills.
+    const agents = resolve(target, '.agents/skills');
+    const claude = resolve(target, '.claude/skills');
+    mkdirSync(agents, { recursive: true });
+    mkdirSync(claude, { recursive: true });
+    const shared = realpathSync(agents) === realpathSync(claude);
     const isLink = (path) => lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink() ?? false;
-    for (const old of oldNames) {
-        const link = resolve(skills, old);
-        if (isLink(link) && (resolve(skills, readlinkSync(link)).startsWith(`${KIT_ROOT}/`) || /[\\/]skills[\\/](reelkit|reelson)-/.test(readlinkSync(link)))) {
-            rmSync(link);
-            console.log(`  removed old link ${link}`);
+    const link = (path, to) => {
+        if (existsSync(path) && !isLink(path)) {
+            throw new ReelsonError(`${path} is a folder, not a link to reelson — move it away and run install again`);
+        }
+        if (isLink(path)) {
+            rmSync(path);
+        }
+        symlinkSync(to, path, 'dir');
+        console.log(`  linked ${path} → ${to}`);
+    };
+    for (const dir of shared ? [agents] : [agents, claude]) {
+        for (const old of oldNames) {
+            const path = resolve(dir, old);
+            if (isLink(path) && (resolve(dir, readlinkSync(path)).startsWith(`${KIT_ROOT}/`) || /[\\/]skills[\\/](reelkit|reelson)-/.test(readlinkSync(path)))) {
+                rmSync(path);
+                console.log(`  removed old link ${path}`);
+            }
         }
     }
     for (const skill of skillNames) {
-        const link = resolve(skills, skill);
-        if (existsSync(link) && !isLink(link)) {
-            throw new ReelsonError(`${link} is a folder, not a link to reelson — move it away and run install again`);
+        link(resolve(agents, skill), resolve(KIT_ROOT, 'skills', skill));
+        if (!shared) {
+            link(resolve(claude, skill), relative(claude, resolve(agents, skill)));
         }
-        if (isLink(link)) {
-            rmSync(link);
-        }
-        symlinkSync(resolve(KIT_ROOT, 'skills', skill), link, 'dir');
-        console.log(`  linked ${link}`);
     }
-    if (!values.global) {
+    if (!global) {
         if (!existsSync(resolve(target, 'demo.config.json'))) {
             init(target);
         }
         const videos = loadConfig(target).videosDir.replace(/^\.?\/+|\/+$/g, '');
         console.log(`
-Add to ${resolve(target, '.gitignore')}:
+Add to ${resolve(target, '.gitignore')} (the skill links point at this machine's reelson):
 
+    /.agents/skills/reelson-*
+    /.claude/skills/reelson-*
     /${videos}/**/recording*.mp4
     /${videos}/**/.raw*/
     /${videos}/**/video/
     /${videos}/**/*.openscreen`);
     }
-    console.log('\nDone. Try: reelson doctor');
+    console.log(global ? '\nDone — every project sees the skills. In a project: reelson init, then reelson doctor' : '\nDone. Try: reelson doctor');
     return 0;
 }
+/** `reelson install`'s question: every project (the default), this one, or another folder → null for global, else the project. */
+async function askWhere() {
+    const home = (path) => (path.startsWith(homedir()) ? `~${path.slice(homedir().length)}` : path);
+    const here = process.cwd();
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log(`Where should reelson install its skills?
+  1. Every project (default): ~/.agents/skills, linked from ~/.claude/skills
+  2. This project: ${home(here)}/.agents/skills, linked from .claude/skills
+  3. Another project…`);
+        for (;;) {
+            const answer = (await rl.question('Choose [1]: ')).trim();
+            if (answer === '' || answer === '1')
+                return null;
+            if (answer === '2')
+                return here;
+            if (answer === '3') {
+                const dir = (await rl.question('Project folder: ')).trim().replace(/^~(?=$|\/)/, homedir());
+                if (dir && existsSync(dir))
+                    return resolve(dir);
+                console.log(`  no folder ${dir || '(empty)'}`);
+                continue;
+            }
+            console.log('  type 1, 2 or 3 (Enter: 1)');
+        }
+    }
+    catch (error) {
+        // Ctrl+D (or Ctrl+C) at the question: stop quietly, nothing linked yet.
+        if (error.name === 'AbortError') {
+            throw new ReelsonError('install cancelled — nothing was changed');
+        }
+        throw error;
+    }
+    finally {
+        rl.close();
+    }
+}
 function init(dir = process.cwd()) {
     const target = resolve(dir, 'demo.config.json');
     if (existsSync(target)) {
@@ -251,8 +308,7 @@ function init(dir = process.cwd()) {
     const example = JSON.parse(readFileSync(resolve(KIT_ROOT, 'demo.config.example.json'), 'utf8'));
     delete example.$comment;
     delete example.$schema;
-    const viaProject = resolve(dir, '.claude/skills/reelson-record/schemas/demo.config.schema.json');
-    const schema = existsSync(viaProject) ? viaProject : CONFIG_SCHEMA_PATH;
+    const schema = viaProjectSkills(dir, 'reelson-record/schemas/demo.config.schema.json') ?? CONFIG_SCHEMA_PATH;
     let schemaRef = relative(dir, schema);
     if (!/^\.{1,2}\//.test(schemaRef) && !schemaRef.startsWith('/')) {
         schemaRef = `./${schemaRef}`;
@@ -275,8 +331,7 @@ function create(argv) {
         throw new ReelsonError(`${scenario} already exists`);
     }
     mkdirSync(dir, { recursive: true });
-    const viaProject = resolve(cfg.root, '.claude/skills/reelson-record/scripts/scenario.ts');
-    const typesFile = existsSync(viaProject) ? viaProject : resolve(KIT_ROOT, 'skills/reelson-record/scripts/scenario.ts');
+    const typesFile = viaProjectSkills(cfg.root, 'reelson-record/scripts/scenario.ts') ?? resolve(KIT_ROOT, 'skills/reelson-record/scripts/scenario.ts');
     let importPath = relative(dir, typesFile);
     if (!/^\.{1,2}\//.test(importPath)) {
         importPath = `./${importPath}`;

package/bin/reelson.ts

@@ -5,12 +5,13 @@
  * demo.config.json (walking up from the working directory).
  */
 import { spawnSync } from 'node:child_process'
-import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { homedir } from 'node:os'
+import { createInterface } from 'node:readline/promises'
 import { basename, relative, resolve } from 'node:path'
 import { parseArgs, parseEnv } from 'node:util'
-import { CONFIG_SCHEMA_PATH, ConfigError, fromRoot, loadConfig, type LoadedConfig } from '../skills/reelson-record/scripts/config.ts'
+import { CONFIG_SCHEMA_PATH, ConfigError, fromRoot, loadConfig, viaProjectSkills, type LoadedConfig } from '../skills/reelson-record/scripts/config.ts'
 import { doctor } from '../skills/reelson-record/scripts/doctor.ts'
 import { build, plan, type BuildOptions } from '../skills/reelson-compose/scripts/build.ts'
 import { captionCues, toSrt, toVtt } from '../skills/reelson-compose/scripts/captions.ts'
@@ -27,11 +28,13 @@ const HELP = `reelson — scripted walkthroughs → branded demo videos
 
 Usage: reelson <command> [options]
 
-  install [<project-dir>] [--global] [--no-browser]
+  install [<project-dir> | --global] [-y] [--no-browser]
                                 link the reelson-record + reelson-compose skills into
-                                <project>/.claude/skills/ (default: this directory; --global:
-                                ~/.claude/skills/), create demo.config.json if missing and
-                                download Playwright's Chromium (--no-browser: skip it)
+                                .agents/skills/ (Codex and other agents) and .claude/skills/
+                                (Claude Code): --global in ~/ for every project, or in a
+                                project (which also gets a demo.config.json); asks which when
+                                neither is given (-y, or no terminal: --global). Downloads
+                                Playwright's Chromium (--no-browser: skip it)
   init                          create demo.config.json in this directory
   doctor                        check the tools and that the cursor layer lines up here
   new <slug> [--url <origin>]   start <videosDir>/<slug>/scenario.ts
@@ -122,7 +125,7 @@ async function run(cmd: string | undefined, argv: string[]): Promise<number> {
             console.log(JSON.parse(readFileSync(resolve(KIT_ROOT, 'package.json'), 'utf8')).version)
             return 0
         case 'install':
-            return install(argv)
+            return await install(argv)
         case 'init':
             return init()
         case 'doctor':
@@ -183,22 +186,25 @@ function one(positionals: string[], usage: string): string {
 }
 
 /**
- * `reelson install`: links the skills into a project (or ~/.claude) and prepares the machine. The links
+ * `reelson install`: links the skills into a project (or the home folder) and prepares the machine. The links
  * point at this installation, so `npm update -g reelson` (or `git pull` in a checkout) updates every project.
  */
-function install(argv: string[]): number {
+async function install(argv: string[]): Promise<number> {
     const skillNames = ['reelson-record', 'reelson-compose']
     // Names used before 0.7 (demo-* before that): their links are dropped when they point at a reelson install.
     const oldNames = ['demo-record', 'demo-video', 'reelkit-record', 'reelkit-compose']
     const { values, positionals } = parseArgs({
         args: argv,
         allowPositionals: true,
-        options: { global: { type: 'boolean' }, 'no-browser': { type: 'boolean' } },
+        options: { global: { type: 'boolean' }, yes: { type: 'boolean', short: 'y' }, 'no-browser': { type: 'boolean' } },
     })
     if (positionals.length > 1 || (values.global && positionals.length)) {
-        throw new ReelsonError('usage: reelson install [<project-dir> | --global] [--no-browser]')
+        throw new ReelsonError('usage: reelson install [<project-dir> | --global] [-y] [--no-browser]')
     }
-    const target = values.global ? homedir() : resolve(positionals[0] ?? '.')
+    // Asked only when neither --global nor a folder is given and someone is at the terminal.
+    const where = values.global ? null : positionals.length ? resolve(positionals[0]) : values.yes || !process.stdin.isTTY ? null : await askWhere()
+    const global = where === null
+    const target = where ?? homedir()
     if (!existsSync(target)) {
         throw new ReelsonError(`${target} does not exist`)
     }
@@ -214,45 +220,92 @@ function install(argv: string[]): number {
         }
     }
 
-    const skills = resolve(target, '.claude/skills')
-    mkdirSync(skills, { recursive: true })
+    // .agents/skills links to this installation; .claude/skills links to .agents/skills (unless the
+    // whole folder already is a link to it), so both agents see the same skills.
+    const agents = resolve(target, '.agents/skills')
+    const claude = resolve(target, '.claude/skills')
+    mkdirSync(agents, { recursive: true })
+    mkdirSync(claude, { recursive: true })
+    const shared = realpathSync(agents) === realpathSync(claude)
     const isLink = (path: string): boolean => lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink() ?? false
-    for (const old of oldNames) {
-        const link = resolve(skills, old)
-        if (isLink(link) && (resolve(skills, readlinkSync(link)).startsWith(`${KIT_ROOT}/`) || /[\\/]skills[\\/](reelkit|reelson)-/.test(readlinkSync(link)))) {
-            rmSync(link)
-            console.log(`  removed old link ${link}`)
+    const link = (path: string, to: string): void => {
+        if (existsSync(path) && !isLink(path)) {
+            throw new ReelsonError(`${path} is a folder, not a link to reelson — move it away and run install again`)
+        }
+        if (isLink(path)) {
+            rmSync(path)
+        }
+        symlinkSync(to, path, 'dir')
+        console.log(`  linked ${path} → ${to}`)
+    }
+    for (const dir of shared ? [agents] : [agents, claude]) {
+        for (const old of oldNames) {
+            const path = resolve(dir, old)
+            if (isLink(path) && (resolve(dir, readlinkSync(path)).startsWith(`${KIT_ROOT}/`) || /[\\/]skills[\\/](reelkit|reelson)-/.test(readlinkSync(path)))) {
+                rmSync(path)
+                console.log(`  removed old link ${path}`)
+            }
         }
     }
     for (const skill of skillNames) {
-        const link = resolve(skills, skill)
-        if (existsSync(link) && !isLink(link)) {
-            throw new ReelsonError(`${link} is a folder, not a link to reelson — move it away and run install again`)
-        }
-        if (isLink(link)) {
-            rmSync(link)
+        link(resolve(agents, skill), resolve(KIT_ROOT, 'skills', skill))
+        if (!shared) {
+            link(resolve(claude, skill), relative(claude, resolve(agents, skill)))
         }
-        symlinkSync(resolve(KIT_ROOT, 'skills', skill), link, 'dir')
-        console.log(`  linked ${link}`)
     }
 
-    if (!values.global) {
+    if (!global) {
         if (!existsSync(resolve(target, 'demo.config.json'))) {
             init(target)
         }
         const videos = loadConfig(target).videosDir.replace(/^\.?\/+|\/+$/g, '')
         console.log(`
-Add to ${resolve(target, '.gitignore')}:
+Add to ${resolve(target, '.gitignore')} (the skill links point at this machine's reelson):
 
+    /.agents/skills/reelson-*
+    /.claude/skills/reelson-*
     /${videos}/**/recording*.mp4
     /${videos}/**/.raw*/
     /${videos}/**/video/
     /${videos}/**/*.openscreen`)
     }
-    console.log('\nDone. Try: reelson doctor')
+    console.log(global ? '\nDone — every project sees the skills. In a project: reelson init, then reelson doctor' : '\nDone. Try: reelson doctor')
     return 0
 }
 
+/** `reelson install`'s question: every project (the default), this one, or another folder → null for global, else the project. */
+async function askWhere(): Promise<string | null> {
+    const home = (path: string): string => (path.startsWith(homedir()) ? `~${path.slice(homedir().length)}` : path)
+    const here = process.cwd()
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    try {
+        console.log(`Where should reelson install its skills?
+  1. Every project (default): ~/.agents/skills, linked from ~/.claude/skills
+  2. This project: ${home(here)}/.agents/skills, linked from .claude/skills
+  3. Another project…`)
+        for (;;) {
+            const answer = (await rl.question('Choose [1]: ')).trim()
+            if (answer === '' || answer === '1') return null
+            if (answer === '2') return here
+            if (answer === '3') {
+                const dir = (await rl.question('Project folder: ')).trim().replace(/^~(?=$|\/)/, homedir())
+                if (dir && existsSync(dir)) return resolve(dir)
+                console.log(`  no folder ${dir || '(empty)'}`)
+                continue
+            }
+            console.log('  type 1, 2 or 3 (Enter: 1)')
+        }
+    } catch (error) {
+        // Ctrl+D (or Ctrl+C) at the question: stop quietly, nothing linked yet.
+        if ((error as Error).name === 'AbortError') {
+            throw new ReelsonError('install cancelled — nothing was changed')
+        }
+        throw error
+    } finally {
+        rl.close()
+    }
+}
+
 function init(dir = process.cwd()): number {
     const target = resolve(dir, 'demo.config.json')
     if (existsSync(target)) {
@@ -261,8 +314,7 @@ function init(dir = process.cwd()): number {
     const example = JSON.parse(readFileSync(resolve(KIT_ROOT, 'demo.config.example.json'), 'utf8'))
     delete example.$comment
     delete example.$schema
-    const viaProject = resolve(dir, '.claude/skills/reelson-record/schemas/demo.config.schema.json')
-    const schema = existsSync(viaProject) ? viaProject : CONFIG_SCHEMA_PATH
+    const schema = viaProjectSkills(dir, 'reelson-record/schemas/demo.config.schema.json') ?? CONFIG_SCHEMA_PATH
     let schemaRef = relative(dir, schema)
     if (!/^\.{1,2}\//.test(schemaRef) && !schemaRef.startsWith('/')) {
         schemaRef = `./${schemaRef}`
@@ -286,8 +338,8 @@ function create(argv: string[]): number {
         throw new ReelsonError(`${scenario} already exists`)
     }
     mkdirSync(dir, { recursive: true })
-    const viaProject = resolve(cfg.root, '.claude/skills/reelson-record/scripts/scenario.ts')
-    const typesFile = existsSync(viaProject) ? viaProject : resolve(KIT_ROOT, 'skills/reelson-record/scripts/scenario.ts')
+    const typesFile =
+        viaProjectSkills(cfg.root, 'reelson-record/scripts/scenario.ts') ?? resolve(KIT_ROOT, 'skills/reelson-record/scripts/scenario.ts')
     let importPath = relative(dir, typesFile)
     if (!/^\.{1,2}\//.test(importPath)) {
         importPath = `./${importPath}`

package/docs/prompting.md

@@ -1,7 +1,7 @@
 # How to ask for a video
 
 The prompt is the spec. A complete prompt has six parts; the more you give, the fewer guesses
-Claude makes and the fewer re-renders you need.
+the agent makes and the fewer re-renders you need.
 
 ```
 Make a demo video of <FEATURE>.
@@ -14,7 +14,7 @@ Emphasis:   zoom on <what> during step <n>     only where the UI is small
 Output:     mp4 (default) / also gif           slug: <kebab-case>
 ```
 
-Claude writes the scenario, records, verifies frames, builds the composition, words the
+The agent writes the scenario, records, verifies frames, builds the composition, words the
 callouts in video.json, checks, renders, and reports the file path with a few extracted frames.
 
 ## Example prompts

package/package.json

@@ -1,8 +1,8 @@
 {
     "name": "reelson",
-    "version": "0.7.0",
+    "version": "0.7.2",
     "type": "module",
-    "description": "Claude Code skills + CLI that turn a scripted Playwright walkthrough into a branded HyperFrames demo video.",
+    "description": "Agent Skills (Claude Code, Codex, …) + CLI that turn a scripted Playwright walkthrough into a branded HyperFrames demo video.",
     "keywords": [
         "demo-video",
         "screencast",
@@ -11,7 +11,9 @@
         "claude-code",
         "skills",
         "product-demo",
-        "video"
+        "video",
+        "agent-skills",
+        "codex"
     ],
     "license": "MIT",
     "author": "Ion Caliman <icaliman92@gmail.com>",

package/skills/reelson-compose/scripts/project.js

@@ -6,7 +6,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
 import { basename, dirname, extname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { fromRoot } from "../../reelson-record/scripts/config.js";
+import { fromRoot, viaProjectSkills } from "../../reelson-record/scripts/config.js";
 import { closest, loadSchema, validate } from "../../reelson-record/scripts/validate.js";
 import { SECTION_TIMING, SLOTS, STAGE_TIMING, } from "./timeline.js";
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -81,12 +81,12 @@ export function validateVideoSpec(raw, where) {
     return raw;
 }
 /**
- * `$schema` for a new video.json: through the project's .claude/skills link
- * when there is one (portable), else straight to the kit.
+ * `$schema` for a new video.json: through the project's skill link (.agents/skills or
+ * .claude/skills) when it points at this reelson (portable), else straight to the kit.
  */
 export function videoSchemaRef(demoDir, config) {
-    const viaProject = resolve(config.root, '.claude/skills/reelson-compose/schemas/video.schema.json');
-    const target = existsSync(viaProject) && realpathSync(viaProject) === realpathSync(VIDEO_SCHEMA_PATH)
+    const viaProject = viaProjectSkills(config.root, 'reelson-compose/schemas/video.schema.json');
+    const target = viaProject && realpathSync(viaProject) === realpathSync(VIDEO_SCHEMA_PATH)
         ? viaProject
         : VIDEO_SCHEMA_PATH;
     return relative(demoDir, target);

package/skills/reelson-compose/scripts/project.ts

@@ -6,7 +6,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
 import { basename, dirname, extname, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { fromRoot, type LoadedConfig } from '../../reelson-record/scripts/config.ts'
+import { fromRoot, viaProjectSkills, type LoadedConfig } from '../../reelson-record/scripts/config.ts'
 import { closest, loadSchema, validate } from '../../reelson-record/scripts/validate.ts'
 import type { SectionSource } from './composition.ts'
 import {
@@ -102,13 +102,13 @@ export function validateVideoSpec(raw: unknown, where: string): VideoSpec {
 }
 
 /**
- * `$schema` for a new video.json: through the project's .claude/skills link
- * when there is one (portable), else straight to the kit.
+ * `$schema` for a new video.json: through the project's skill link (.agents/skills or
+ * .claude/skills) when it points at this reelson (portable), else straight to the kit.
  */
 export function videoSchemaRef(demoDir: string, config: LoadedConfig): string {
-    const viaProject = resolve(config.root, '.claude/skills/reelson-compose/schemas/video.schema.json')
+    const viaProject = viaProjectSkills(config.root, 'reelson-compose/schemas/video.schema.json')
     const target =
-        existsSync(viaProject) && realpathSync(viaProject) === realpathSync(VIDEO_SCHEMA_PATH)
+        viaProject && realpathSync(viaProject) === realpathSync(VIDEO_SCHEMA_PATH)
             ? viaProject
             : VIDEO_SCHEMA_PATH
 

package/skills/reelson-compose/studio/studio.js

@@ -33,7 +33,7 @@ async function load() {
   if (!body.data) return
   const first = !data
   data = body.data
-  // Undo writes back a whole earlier video.json; after a change from elsewhere (Claude, an
+  // Undo writes back a whole earlier video.json; after a change from elsewhere (the agent, an
   // editor) that would silently revert it, so the history starts over.
   if (!first && body.revision !== revision && (history.undo.length || history.redo.length)) {
     history.undo = []

package/skills/reelson-record/SKILL.md

@@ -75,8 +75,9 @@ Common dev overlays (Laravel Debugbar, Vite/Next.js/webpack error overlays) are
 ## Prerequisites
 
 - The app running and reachable at the scenario's `baseURL`.
-- reelson installed once per machine (`npm install -g reelson`, then `reelson install` in the
-  project: Playwright's Chromium and the skill links; a kit checkout's `install.sh` does both).
+- reelson installed once per machine (`npm install -g reelson`, then `reelson install --global`
+  for every project or `reelson install <project>` for one: Playwright's Chromium and the skill
+  links; a kit checkout's `install.sh` does both). Pass one of them: without either it asks the user.
 - `ffmpeg` on PATH (`brew install ffmpeg`). Node 22.18+ (TypeScript runs directly).
 - `reelson doctor` checks the tools and films a local test page to confirm the cursor layer
   lines up with the footage on this machine (offset and px error; run it on a new machine).
@@ -85,7 +86,7 @@ Common dev overlays (Laravel Debugbar, Vite/Next.js/webpack error overlays) are
 
 1. **Pick the origin, panel and account.** Look for existing e2e helpers in the project
    (login, table/modal locators) and reuse them from the scenario — a scenario is mostly an
-   e2e test with a cursor. Check the project's CLAUDE.md / e2e docs for seeded accounts.
+   e2e test with a cursor. Check the project's AGENTS.md / CLAUDE.md / e2e docs for seeded accounts.
 
 2. **Write `<videosDir>/<slug>/scenario.ts`.** `reelson new <slug> --url <origin>` creates a
    stub with the right type import; the kit's `examples/todo-add-item/scenario.ts` is a full

package/skills/reelson-record/scripts/config.js

@@ -113,6 +113,21 @@ export function countLabel(count, label, language) {
     return `${count} ${label[category] ?? label.other}`;
 }
 /** Resolves a path from the config against the project root. */
+/**
+ * Where a project links the skills, in order: .agents/skills (Codex and the other agents that read
+ * Agent Skills), then .claude/skills (Claude Code; `reelson install` links it to the first).
+ */
+export const SKILL_DIRS = ['.agents/skills', '.claude/skills'];
+/** `<skill>/<path>` inside the project's first skill folder that has it (a portable path to commit), else null. */
+export function viaProjectSkills(root, path) {
+    for (const dir of SKILL_DIRS) {
+        const candidate = resolve(root, dir, path);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
 export function fromRoot(config, path) {
     return isAbsolute(path) ? path : resolve(config.root, path);
 }

package/skills/reelson-record/scripts/config.ts

@@ -225,6 +225,23 @@ export function countLabel(count: number, label: Label, language: string): strin
 }
 
 /** Resolves a path from the config against the project root. */
+/**
+ * Where a project links the skills, in order: .agents/skills (Codex and the other agents that read
+ * Agent Skills), then .claude/skills (Claude Code; `reelson install` links it to the first).
+ */
+export const SKILL_DIRS = ['.agents/skills', '.claude/skills']
+
+/** `<skill>/<path>` inside the project's first skill folder that has it (a portable path to commit), else null. */
+export function viaProjectSkills(root: string, path: string): string | null {
+    for (const dir of SKILL_DIRS) {
+        const candidate = resolve(root, dir, path)
+        if (existsSync(candidate)) {
+            return candidate
+        }
+    }
+    return null
+}
+
 export function fromRoot(config: LoadedConfig, path: string): string {
     return isAbsolute(path) ? path : resolve(config.root, path)
 }