[isamu]

Summary

Closes #7. The README's first command-line example worked neither inside a clone of this repo nor outside one. This PR:

• ships examples/*.avs in the npm package and adds --script example:<name> to read one (src/examples.ts, wired in src/cli.ts; --help lists the bundled names, and an unknown name fails with the list)
• makes the first README example npx-only: avatar from the mulmocast-media URL, --script example:hello-ja
• adds a prominent README note right under that example: npx avatarscript fails inside a clone with command not found, even after npm run build, plus the three commands that do work there

Items to Confirm / Review

• README wording of the in-clone warning — the main thing this PR wants readers to see. Is it prominent enough, and placed right?
• Package contents: files gains examples/*.avs (the three .avs files only; examples/make-video.ts stays out). npm pack --dry-run shows them.
• Score provenance: for a bundled script, provenance.script records example:<name> instead of a path into the npx cache. Other scripts are unchanged (path relative to the score).
• The examples folder is located relative to the CLI file (<pkg>/examples next to dist/ or src/), so it works both from source and from the installed package.
• Not done (out of scope, per the issue): a default --avatar; fetching scripts from URLs.

Verification

• npm run lint, npm run typecheck, npm test pass (new tests/examples.test.ts covers valid names, pass-through of other values, and unknown/empty/path-like names).
• scripts/smoke.sh avatars/ani passes; it now also compiles --script example:hello-en from the installed tarball and checks the provenance.
• The real user path: packed the tarball, ran npx --package=<tgz> avatarscript make --avatar <mulmocast-media URL> --script example:hello-ja --tts mock from an empty folder outside the repo → an H.264 + AAC MP4; an extracted frame shows the avatar.
• Inside the clone: confirmed npx avatarscript still fails after npm run build, and that npm run avatarscript -- ..., node dist/cli.js ... and npx avatarscript@latest ... work.
• Not exercised: --tts elevenlabs (needs a key); mock runs the same script path.

Approach

Bundled rather than fetched from a URL: the scripts are tiny, always match the installed CLI's syntax, and a fetched script would also need its relative background images fetched (src/view.ts resolves them against the script's folder). src/examples.ts is pure (no fs) so the name mapping is unit-tested; the CLI supplies the directory listing.

User Prompt

• npx avatarscript make --avatar avatars/ani --script examples/hello-ja.avs ... fails with sh: avatarscript: command not found — does npx require installing avatarscript first?
• Run outside the repo, it fails because the avatar/script files are missing. To work with npx alone, should the script also be fetchable?
• Go with bundling; create an issue (describing the current problem) and proceed.
• Also note that it does not work inside the repository. Does building fix it? The key message for the README is that it does not work. Write down the working alternatives too.
• Create the PR.

🤖 Generated with Claude Code