@hajimism/dek 0.3.3 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,142 @@
 
 Release notes for `@hajimism/dek`. From 0.1.0 on, release-please writes this file from the Conventional Commits on `main`.
 
+## [0.5.0](https://github.com/hajimism/dek/compare/v0.4.0...v0.5.0) (2026-10-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* **ref:** a dek.toml that pins a ref whose name holds a control character or a character a person cannot see no longer loads until that line is removed; `dekc pack` refuses a deck so named until its folder is renamed; and `dekc new` and `dekc init --deck` refuse such a name, which they took before. Every other name works as before.
+* where Chromium's sandbox does not start, `dekc shot <ref>` fails until DEK_ALLOW_UNSANDBOXED=1 is set.
+
+### Features
+
+* **ref:** report the characters in a ref that a person cannot see ([5ca233e](https://github.com/hajimism/dek/commit/5ca233e186125e821f1341cc790636f26654274a))
+
+
+### Bug Fixes
+
+* **build:** keep a minified stylesheet reading as its source where an escape meets a newline or a comment ([41fd1ba](https://github.com/hajimism/dek/commit/41fd1ba08abc63c8af1d9deb8e2b9d70bb5ceab5))
+* **build:** minify a stylesheet into one that reads as its source does ([bdcffb9](https://github.com/hajimism/dek/commit/bdcffb9edaf7238b33bdf740dc4072c6f8cdaaa1))
+* **cli:** at the project root, hint a command only for the decks that have what it names ([fe3f8fb](https://github.com/hajimism/dek/commit/fe3f8fb12c178a7d8bfcb40b4ed16b52d03a08ae))
+* **cli:** hint `dekc ls` for a deck that is not there, not `dekc ls <it>` ([1ee4554](https://github.com/hajimism/dek/commit/1ee455439734f57eaf03c6c91fd78a9423f4812f))
+* **cli:** name a ref by the ref in the hints about it ([e9d1a47](https://github.com/hajimism/dek/commit/e9d1a47fe282b766bed189212891f1aafcc38a94))
+* **dev:** print a failure of the dev server's lint or voice run instead of dropping it ([14a8e8c](https://github.com/hajimism/dek/commit/14a8e8ceb75247d850407aeeef3bba56f5525a88))
+* give up on a voice engine, a dev server, or a rumdl that never answers ([19023f2](https://github.com/hajimism/dek/commit/19023f2c3987c4e60f2fe7440d4e1d5369ec2f10))
+* keep a file's mode when dek writes it anew ([085d7e8](https://github.com/hajimism/dek/commit/085d7e8e4be2895c975cd76668d4c7af91937d96))
+* **lint:** list rumdl as skipped when what it printed is not SARIF ([74582e0](https://github.com/hajimism/dek/commit/74582e07153aeb77211083e87309cbe6214e8ba3))
+* **lint:** name the path beside a stray space in DEK021's hint only when it is a plain word ([b030691](https://github.com/hajimism/dek/commit/b03069178ab6b318749c0296aca5fc916ebc2cec))
+* **lint:** read a URL in DEK011 as the browser's URL parser reads it ([c0950a5](https://github.com/hajimism/dek/commit/c0950a59b6c25f1c561c101a07750b89c0a87283))
+* **lint:** say to run lint --visual again after lint --visual fails ([a00da44](https://github.com/hajimism/dek/commit/a00da4437aadf6373a4e888213f26d6efdd7462a))
+* **ls:** keep a ref's title, event, and date to one line, as AGENTS.md does ([af85b6e](https://github.com/hajimism/dek/commit/af85b6e8ef63175cfb3166465e533e6b361f166e))
+* **mv:** write script.md, slides, and voice.toml whole, never over the old file ([a7a22b3](https://github.com/hajimism/dek/commit/a7a22b34a1fb073181966bec4a7c7e88b88757ce))
+* print no color code a deck or a ref wrote, only dek's own ([27b6751](https://github.com/hajimism/dek/commit/27b6751eb48d84e2538983c618889f74389d5caa))
+* read a pack's or a GitHub tarball's tar with dek's own reader, so it unpacks no more than was counted ([bdda596](https://github.com/hajimism/dek/commit/bdda596bf5974e6c30f5d273090327d0ed114a6b))
+* read each attribute value as the browser does, its character references decoded ([65a58d1](https://github.com/hajimism/dek/commit/65a58d11497648690c539c8caa4bbe49c246a4c8))
+* read the keys after an array or inline table written over several lines ([fa8f268](https://github.com/hajimism/dek/commit/fa8f2680bec36c3b092f5b7eef5749cd4146d64a))
+* read url() and a string cut short by CR or FF where the browser does ([55296f2](https://github.com/hajimism/dek/commit/55296f2a8f04ffdea958b835132bc2ad4c8054d5))
+* **ref:** keep a ref's names out of hints, and to one short line in messages ([67f7d19](https://github.com/hajimism/dek/commit/67f7d19268cb1032978d62a1a0fe1ec2a209197c))
+* **ref:** refuse a pack whose deck's name holds a control character or one a person cannot see ([373f14f](https://github.com/hajimism/dek/commit/373f14f368057677c33d9c8bbaccc427e048d790))
+* **sample:** set the note on why-dek's read-only card in ink ([586d09d](https://github.com/hajimism/dek/commit/586d09d7e706ae56b731ee9c5a4b6f1b03406d2e))
+* say whenever Chromium draws without its sandbox, and draw a ref there only when asked ([293b3ff](https://github.com/hajimism/dek/commit/293b3ffd0fd12ff042831fc4816e96025d7336af))
+* **server:** keep what the dev server serves out of other sites' pages and frames ([260b0f0](https://github.com/hajimism/dek/commit/260b0f081de5d9821312456abbec2849dfac7fd7))
+* **shot:** send a ref's broken slide script to its author, not to lint ([c1045fa](https://github.com/hajimism/dek/commit/c1045faf8583ca61281b825811a172a72ec0bb6c))
+* **show:** keep the name of keyframes written as a string in the theme excerpt ([072b078](https://github.com/hajimism/dek/commit/072b07848a2799f7d2e98f42962330c2e407bbee))
+* **show:** say a slide is a ref's, and start a part on a line no file can write ([b6b2389](https://github.com/hajimism/dek/commit/b6b2389fe5cf8dfc9dac4fefa1eab88737d7075a))
+* sort dict.toml, decks, and slide files the same way on every machine ([29a3f3c](https://github.com/hajimism/dek/commit/29a3f3c4c6073fbdc5808c9921d296fa8e4125cf))
+* start every program dek runs with the environment as it is now ([ee6b319](https://github.com/hajimism/dek/commit/ee6b319d2772ff39ea82cf3dd8fd763d4fb130c8))
+* stop a command at its timeout, even one that ignores SIGTERM or leaves a process behind ([3b05db7](https://github.com/hajimism/dek/commit/3b05db7ee9c17e68e5d580d744dc457856c29678))
+* **tar:** leave AppleDouble names out, and number that record 27 ([c4fb0ef](https://github.com/hajimism/dek/commit/c4fb0efbb9cd0a73f5335f078fb9b08bca1d35ef))
+* **video:** give up on an ffmpeg that never answers -version ([c0d3c6a](https://github.com/hajimism/dek/commit/c0d3c6a22d0dd8328782661ebc22384313d33487))
+* **visual:** stop sending a DEK031 to theme.css when the theme alone was never measured ([b3321b3](https://github.com/hajimism/dek/commit/b3321b3302389743dd5f0606e2a6367e2635f14d))
+* **voice:** stop waiting on a player that never ends after a say clip ([fc1082b](https://github.com/hajimism/dek/commit/fc1082bf3e8eb012bda822256fe51a067eb086b8))
+
+
+### Refactoring
+
+* write the link preview image and remove the dev server's lock through safe-fs ([3ae94c8](https://github.com/hajimism/dek/commit/3ae94c8db6ae9bef4243bec3cc334e1a4a2b9e11))
+
+
+### Documentation
+
+* **adr:** keep a ref's words out of dek's hints, and mark what a ref wrote wherever dek prints it ([e4f0787](https://github.com/hajimism/dek/commit/e4f07878aee0f0f887484b800778324a55e0f97d))
+* **adr:** number the --json contract record 31 ([8108f37](https://github.com/hajimism/dek/commit/8108f3770b3c2b24efb57b2ed1064949a998e95b))
+* **adr:** number the fast-check record 26, where this stack adds it ([389948e](https://github.com/hajimism/dek/commit/389948e6e8ef79842d8b429fac5e2d8e5d2ddeb2))
+* **adr:** number the ref-words record 30, and point it at the trust record ([6925755](https://github.com/hajimism/dek/commit/692575572ab5a235ac1256c7b7b11e31a4ddc01f))
+* **adr:** number the sandbox record 29, and point it at the trust record ([e082487](https://github.com/hajimism/dek/commit/e08248711777c3acabd8ac46c1c8a080302de961))
+* **adr:** number the trust record 28, after the records already on this branch ([7a7fbd8](https://github.com/hajimism/dek/commit/7a7fbd8b9cb6f18af2d27f26a1fb962c3e85f30a))
+* **adr:** read a pack's or a repository's tar with dek's own reader ([ba896c8](https://github.com/hajimism/dek/commit/ba896c84daec4a39fdc5d7fdd34c1cf5ccb52394))
+* **adr:** read every attribute value as the browser does ([6a1c698](https://github.com/hajimism/dek/commit/6a1c698fbc74da129c034f175063d8c99a83f9bc))
+* **adr:** say what dek does where Chromium's sandbox cannot start ([f2f940a](https://github.com/hajimism/dek/commit/f2f940ad4c0a216f9f0ec0085da72cfd15414282))
+* **adr:** say whom dek trusts, and what each of them may make it do ([8f26099](https://github.com/hajimism/dek/commit/8f260990674b3c3105b40b276f9e90c6e013e1db))
+* pass the suite timeout on every bun test line in CONTRIBUTING ([6c7182c](https://github.com/hajimism/dek/commit/6c7182cab0564f91088be06b5209c32b6f191efa))
+* say how dek keeps a ref's words apart from its own ([756ba7c](https://github.com/hajimism/dek/commit/756ba7ca74ff05cbd109ef0eab270dea92c52b78))
+* say how long dek waits on rumdl, a voice engine, and the dev server, and how large a ref may be ([e196cd8](https://github.com/hajimism/dek/commit/e196cd81ad83cd90286a91977258bb7c0882eaee))
+* say lint reads an attribute's value and URL as the browser does ([4c67184](https://github.com/hajimism/dek/commit/4c671849309e7ff8015341862b9fc8ec860d0cb7))
+
+## [0.4.0](https://github.com/hajimism/dek/compare/v0.3.4...v0.4.0) (2026-10-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* **theme:** `dekc theme --json` lists in `layouts` only layouts whose names are plain words: letters, marks, and digits of any script and `@%+=:,./_-`, not starting with `=`. A layout whose name holds anything else, such as a space, a quote, `$`, `;`, or a backtick, is no longer in `layouts`; `unprintedLayouts`, present only when there are some, says how many were left out. `dekc theme <layout>` still prints such a layout's example.
+* **ref:** a dek.toml whose [refs] pins a deck name with any other character, starting with a dash, not in NFC, or longer than 64 characters or 200 bytes, such as `owner/repo/talk(1)` or `file/a+b`, no longer loads. Delete the line the error points at, and for a pack its packs/<deck>.tgz and refs/file/<deck>, then pin the deck again under a name a ref can carry.
+
+### Bug Fixes
+
+* **annotations:** show a deck, slide, or beat that is no plain word as a placeholder in the notes ([3b04e89](https://github.com/hajimism/dek/commit/3b04e89dc22f9ea421919c920594f53a9c02d3be))
+* **cli:** say once where to find a deck's name a retyped command leaves as &lt;deck&gt; ([d4a57d9](https://github.com/hajimism/dek/commit/d4a57d9f7836b2ba2433dc634a136bb7e97be509))
+* **config:** show a key that is no plain word as &lt;key&gt; in an error ([22476a7](https://github.com/hajimism/dek/commit/22476a712ecf0ee4e3c552b1e0fe6f35ac10cacf))
+* **dev:** read .dek/server.json only as the dev server writes it ([c402cb6](https://github.com/hajimism/dek/commit/c402cb6282783425611274fbc0337cd6652add7e))
+* **dev:** read the lock a dev server on port 80 writes ([665e0e2](https://github.com/hajimism/dek/commit/665e0e237c3a639a45fa36dc14ed8bd2e7ad9168))
+* keep reads, writes, and suggested commands inside what the project and dek wrote ([23a667d](https://github.com/hajimism/dek/commit/23a667d199ee5f0b34040c4c33f0c0bcfd47f819))
+* **lint:** name a remote file in DEK020's hint only when it is a plain word ([fb77d02](https://github.com/hajimism/dek/commit/fb77d028db1bb38bea6b43695838d52776b192a7))
+* **lint:** name a slide or asset file in a hint only when it is a plain word ([eeb240c](https://github.com/hajimism/dek/commit/eeb240c418b615067bd66ff45ac6b70361d3bd1b))
+* **lint:** show an unknown key that is no plain word as &lt;key&gt; in DEK008 ([f950def](https://github.com/hajimism/dek/commit/f950def7f80f06da46bd8c913ae84c8c849d5ddf))
+* never follow a link under refs/ when writing a snapshot ([0c843ea](https://github.com/hajimism/dek/commit/0c843ea4193270dd1cc0fde4a04768e210efd911))
+* never write or remove a pack's copy through a link under packs/ ([95980a6](https://github.com/hajimism/dek/commit/95980a631e90ee97eda24784ded50b042111512d))
+* quote every name in a command dek suggests ([d1e608d](https://github.com/hajimism/dek/commit/d1e608d5676e46b7947bd5f43a3315269fd27773))
+* read a project's files only through links that stay inside it ([7ae3815](https://github.com/hajimism/dek/commit/7ae38152eadd6f58d67034169ade9dd749038002))
+* **ref:** accept only letters, digits, dots, dashes, and underscores in a ref's deck name ([1b430e1](https://github.com/hajimism/dek/commit/1b430e1ea3d0f66af2642a5f257af1cefcae3ac0))
+* **ref:** fold names as macOS does when telling whether two refs share a folder ([fdb32ee](https://github.com/hajimism/dek/commit/fdb32ee103facc5a661f20dabf79fe8f91ae48cd))
+* **ref:** refuse a pin whose folders another ref already takes ([0d550d8](https://github.com/hajimism/dek/commit/0d550d897b0cdad86ac3de181bf7fd031061bd66))
+* refuse a decks folder that links out of the project ([83f2ff0](https://github.com/hajimism/dek/commit/83f2ff00079893b8e2dbb2fc5d5b7588435aa4dd))
+* refuse to serve or write inside a ref, as every other command does ([665b2de](https://github.com/hajimism/dek/commit/665b2de7a3e6aa3b67ce6140d3eb2a15fb398ee6))
+* serve a deck's assets only from inside the project ([86743cf](https://github.com/hajimism/dek/commit/86743cf731d97f664e95b75f1441dd238f0eeb11))
+* take a folder for a ref only where dek wrote one, and name it from there ([62cc8df](https://github.com/hajimism/dek/commit/62cc8df0a509a99a55d9db7698683bc3be5523d4))
+* **theme:** leave layouts whose names are no plain word out of --json ([625f6d3](https://github.com/hajimism/dek/commit/625f6d3dab0dfe16dacb272e371b551214621a86))
+* **theme:** print only layout names that are plain words ([62b15d1](https://github.com/hajimism/dek/commit/62b15d18afb91d6adbc2641376d9ca899cb6bf20))
+
+
+### Documentation
+
+* say dek follows no link under packs/ either ([5a11b2c](https://github.com/hajimism/dek/commit/5a11b2ca9960a134e261f09f80408fc770aa44da))
+
+## [0.3.4](https://github.com/hajimism/dek/compare/v0.3.3...v0.3.4) (2026-10-27)
+
+
+### Features
+
+* **pptx:** lay out boxes, pictures, text, the theme, and backgrounds as PowerPoint's own ([#27](https://github.com/hajimism/dek/issues/27)) ([eb854e9](https://github.com/hajimism/dek/commit/eb854e9835508792d3e8cfb9dd4046e8750dab7f))
+* **skills:** teach the review in the browser, and add an optional dek-design skill ([2c18b0e](https://github.com/hajimism/dek/commit/2c18b0e339160fb03ca6ce3915b89e37d82c9522))
+* **skills:** teach the review in the browser, and add an optional dek-design skill ([1b04394](https://github.com/hajimism/dek/commit/1b04394023a239706a2fa29d168811e1a1be05d2))
+* **visual:** report awkward line breaks and edges a few pixels off (DEK035, DEK036) ([#28](https://github.com/hajimism/dek/issues/28)) ([ce75fc1](https://github.com/hajimism/dek/commit/ce75fc14937d76ab457298a5aca9116a0fe3778e))
+
+
+### Bug Fixes
+
+* refuse a slide script's imports before Bun reads it, so none runs while dek compiles ([2752356](https://github.com/hajimism/dek/commit/275235647869f1e0a040c080476141d3aaa1aaa6))
+* refuse a slide script's imports before Bun reads it, so none runs while dek compiles ([198930c](https://github.com/hajimism/dek/commit/198930c1d41639cc9943f36a3a187ff6eab0f364))
+
+
+### Documentation
+
+* **adr:** keep dependency code away from the tokens that publish ([103f17c](https://github.com/hajimism/dek/commit/103f17cebb37dd1750caa4cc242acedf55703809))
+* **adr:** renumber the PPTX records after the line-break ones ([ca43352](https://github.com/hajimism/dek/commit/ca4335267b6eeed7131c4123a8a543a230d65875))
+* **adr:** renumber the PPTX records after the line-break ones ([bef6e12](https://github.com/hajimism/dek/commit/bef6e12915ac301843297fb972cf36288bbf612c))
+* **adr:** ship an optional design skill and raise the official skill's floor to 0.2.2 ([6f39dd1](https://github.com/hajimism/dek/commit/6f39dd1e8234297cb0fb72d93722a419d1921f23))
+* name the optional dek-design skill, and the review the official skill teaches ([6908fa1](https://github.com/hajimism/dek/commit/6908fa195e16d79c75d5b77cda72f708798de34c))
+
 ## [0.3.3](https://github.com/hajimism/dek/compare/v0.3.2...v0.3.3) (2026-10-21)
 
 

package/README.ja.md

@@ -44,7 +44,7 @@ bunx dekc build     # 3. dist/2026-04-vite.html — トーク全体がこの 1
 
 台本を書いて `dekc` を叩けば、HTML を一行も書かずに同梱テーマで発表できます。
 
-エージェントと作るなら、公式スキルを `npx skills add hajimism/dek` で、Claude Code なら `/plugin marketplace add hajimism/dek` と `/plugin install dek@dek` で入れてください。プロジェクトの外にいるエージェントは [llms.txt](https://hajimism.github.io/dek/llms.txt) から始められます。[AI エージェントと作る](https://hajimism.github.io/dek/ja/guide/ai.html)を参照してください。
+エージェントと作るなら、公式スキルを `npx skills add hajimism/dek --skill dek` で、Claude Code なら `/plugin marketplace add hajimism/dek` と `/plugin install dek@dek` で入れてください。`dek-design` も、同じ方法で選んで入れられます。プロジェクトの外にいるエージェントは [llms.txt](https://hajimism.github.io/dek/llms.txt) から始められます。[AI エージェントと作る](https://hajimism.github.io/dek/ja/guide/ai.html)を参照してください。
 
 続きは [はじめる](https://hajimism.github.io/dek/ja/guide/getting-started.html)へ。通しで 1 本作るなら [チュートリアル](https://hajimism.github.io/dek/ja/guide/tutorial.html)。コマンドの一覧は [CLI リファレンス](https://hajimism.github.io/dek/ja/reference/cli.html)にあります。
 
@@ -64,7 +64,7 @@ bun run dev            # または bun run lint:visual / bun run build
 ```bash
 bun install
 bunx playwright install chromium   # 最初に一度。実ブラウザを動かすテストに使う
-bun test --watch
+bun test --watch --timeout=20000
 bun run typecheck
 bun run check             # Biome の format + lint
 bun run docs:dev          # VitePress

package/README.md

@@ -44,7 +44,7 @@ bunx dekc build     # 3. dist/2026-04-vite.html — the whole talk in one file
 
 Write the script, run `dekc`, and you can present with the bundled theme without writing a line of HTML.
 
-Working with an agent? Install the official skill with `npx skills add hajimism/dek`, or in Claude Code with `/plugin marketplace add hajimism/dek` and `/plugin install dek@dek`; an agent outside any project can start from [llms.txt](https://hajimism.github.io/dek/llms.txt). See [Working with AI Agents](https://hajimism.github.io/dek/guide/ai.html).
+Working with an agent? Install the official skill with `npx skills add hajimism/dek --skill dek`, or in Claude Code with `/plugin marketplace add hajimism/dek` and `/plugin install dek@dek`; `dek-design` is an optional skill installed the same way; an agent outside any project can start from [llms.txt](https://hajimism.github.io/dek/llms.txt). See [Working with AI Agents](https://hajimism.github.io/dek/guide/ai.html).
 
 Continue with [Getting Started](https://hajimism.github.io/dek/guide/getting-started.html), or build a real deck end to end in the [Tutorial](https://hajimism.github.io/dek/guide/tutorial.html). Every command is listed in the [CLI reference](https://hajimism.github.io/dek/reference/cli.html).
 
@@ -64,7 +64,7 @@ bun run dev            # or bun run lint:visual / bun run build
 ```bash
 bun install
 bunx playwright install chromium   # once, for the tests that drive a real browser
-bun test --watch
+bun test --watch --timeout=20000
 bun run typecheck
 bun run check             # Biome format + lint
 bun run docs:dev          # VitePress

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hajimism/dek",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "description": "A build system for talks.",
   "license": "MIT",
   "author": "Hajime Nakagawa (https://github.com/hajimism)",
@@ -43,8 +43,8 @@
     "ai-agents"
   ],
   "scripts": {
-    "test": "bun test --parallel=4",
-    "test:watch": "bun test --watch",
+    "test": "bun test --parallel=4 --timeout=20000",
+    "test:watch": "bun test --watch --timeout=20000",
     "typecheck": "tsc --noEmit",
     "knip": "knip",
     "schema": "bun scripts/cli-schema.ts",
@@ -64,9 +64,11 @@
     "@biomejs/biome": "2.5.15",
     "@happy-dom/global-registrator": "21.0.1",
     "@types/bun": "^1.4.2",
+    "fast-check": "4.10.2",
     "happy-dom": "21.0.1",
     "knip": "6.41.0",
     "playwright": "^1.63.0",
+    "publint": "0.3.25",
     "typescript": "^7.0.2",
     "vitepress": "^1.6.4"
   },

package/skills/dek/SKILL.md

@@ -16,7 +16,7 @@ dek builds a talk from its script. `script.md` holds what will be said, in order
 
 ## First, ask the dek you have
 
-1. `bunx dekc --version` and `bunx dekc help --agent`: every command and flag of the dek installed in this project. This file names few on purpose; use only what that list shows.
+1. `bunx dekc --version` and `bunx dekc help --agent`: every command and flag of the dek installed in this project. This file names few on purpose; use only what that list shows. It is written for dek 0.2.2 or newer; with an older one, follow only that list and `AGENTS.md`.
 2. Read dek's block in `AGENTS.md`. dek rewrites it for the installed version: the conventions lint checks, how to check a slide, and what to do before reporting a deck as done. Follow it as written.
 3. In the deck, `bunx dekc theme`: the classes, tokens, and layouts this deck's theme defines, and `bunx dekc theme <layout>` for a layout's markup. Use nothing else.
 
@@ -39,6 +39,13 @@ A hint that sends a fix to `theme.css` means every slide of the deck shares the
 - You have looked at `bunx dekc shot --sheet` and judged the deck's balance.
 - Say what you could not judge, such as the argument and how the timing feels when spoken, and hand it back to the author. Passing lint means nothing measurable is wrong, not that the talk is good.
 
-## When the human points at something
+## When the human reviews the deck
 
-If the human marked beats while rehearsing or pointed at elements of a slide, `bunx dekc help --agent` lists the commands that read those notes, and `AGENTS.md` says how to use them. Leave clearing them to the human.
+The human sees what lint cannot. Let them point at it:
+
+1. Start the dev server in the background, since it keeps running: `bunx dekc <deck> --port <free port>`, or your harness's preview tool if it has one.
+2. Give them the URL and ask them to press `a`, click what they want changed, write a note, and tell you when they are done. They may not know dek: name the keys, not the commands.
+3. `bunx dekc annotations <deck> --json`, and fix every note. Shoot the slide again with `bunx dekc shot <slug>` and compare it with the note's `shot`. Tell them in short what you changed.
+4. Ask them to look again, until they say the deck is done. Stop the dev server you started.
+
+Leave `dekc annotations clear` to the human. If they marked beats while rehearsing, `AGENTS.md` says how to read those too.

package/skills/dek-design/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: dek-design
+description: Make dek slides that read at a glance - a heading that states a claim, one focal point, and no visual difference without a meaning. Use when writing or reviewing the look of slides in a dek deck, or when a deck lints clean but still looks off.
+---
+
+# dek-design
+
+The audience sees a slide, holds it in mind, then understands it. Make each step cost as little as it can. Lint measures what a rule can decide, such as overflow and contrast; this skill is for what it cannot. Use only the classes, tokens, and layouts `bunx dekc theme` lists.
+
+## Before you start
+
+- Projected or read: a talk is spoken, so the words live in `script.md` and a slide shows what the voice cannot. A deck sent to be read alone needs sentences that stand without the speaker.
+- What the audience knows: do not use a term they do not know. If you must, tie it to something they do.
+
+## One slide
+
+- The `##` heading is the slide's claim, in one sentence: "Builds fail on cold caches", not "Problems". Read in order, the headings tell the whole talk.
+- The body is the evidence for the heading. Show it as a figure, a chart, or a short table where you can.
+- Keep about four groups on a slide at most. With more, nest them or split the slide.
+
+## How it looks
+
+- One thing stands out most on each slide, and it is the main point. Emphasis used everywhere is emphasis nowhere.
+- Change color, type, or layout only when the meaning changes; the audience looks for a reason in every change, so never vary for variety. Mark sections with one layout used the same way each time.
+- When things differ, make them differ clearly. A small difference is not seen as one.
+- Line things up. Items side by side share their top, their bottom, and the line their text starts on; a row of cards is one height even when one holds less. Items stacked share their left edge. An edge a little off reads as a mistake, not a choice, and a shot shows it where markup does not.
+- What sits close, aligns, or shares a color reads as one group. Do not set items of different rank as a row of equal cards.
+- Position means something: time and steps run left to right, more or better goes up, the general sits above the specific. A person or anything with a direction faces into the slide or toward what it points at.
+- The eye goes from the heading at top left, to the body in the middle, to the conclusion or next step at bottom right.
+
+## Charts
+
+- A line for a trend, bars to compare values. Show amounts by position or length, not by area, angle, or hue.
+- Label lines and bars directly instead of using a legend. Put each note next to what it explains.
+- No icon or picture that only decorates.
+
+## Check
+
+1. `bunx dekc ls <deck>` lists the headings in order. Read only them: does the talk hold?
+2. `bunx dekc shot --sheet`, then each slide's own shot: where does the eye land first, and is that the main point? Read `fill` in `bunx dekc check <slug> --json` for where the slide is empty.
+3. In each slide's shot, edges line up: in a row, tops, bottoms, and the first lines of text; in a column, left edges. Fix any that do not.
+4. Every difference in position, color, size, and look has a reason you can say. Remove the ones that do not.

package/src/cli/address.ts

@@ -1,7 +1,9 @@
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
+import { shellName } from "../core/escape.ts";
 import { isInside } from "../core/path.ts";
-import { COMMANDS } from "./commands.ts";
+import { snapshotName } from "../core/ref.ts";
+import { type AnySpec, COMMANDS, subcommandsOf } from "./commands.ts";
 
 /** A deck a hint is about: the name a command takes, and the directory that makes it implicit. */
 export type HintDeck = { name: string; dir: string };
@@ -10,20 +12,72 @@ export type HintDeck = { name: string; dir: string };
  * A hint's commands as they run from `cwd`. Hints are written as if run inside the deck they are
  * about, where a command finds its deck by itself. Run anywhere else, a command that takes a deck
  * needs its name: as the first word outside every deck, and as `--deck` inside another deck,
- * where a first word names something in that deck instead. A command that already names a deck,
- * or takes none, is left as written.
+ * where a first word names something in that deck instead, or where the name would read as a
+ * subcommand or a flag. The name is one shell word, however it is spelled, or `<deck>` when no
+ * word holds it alike in every shell, with where to find it unless `note` is false, for a hint
+ * that joins several and says it once. A command that already names a deck, or takes none, is
+ * left as written.
  */
-export function addressHint(hint: string, deck: HintDeck | undefined, cwd: string): string {
+export function addressHint(
+  hint: string,
+  deck: HintDeck | undefined,
+  cwd: string,
+  { note: noted = true }: { note?: boolean } = {},
+): string {
   if (deck === undefined || isInside(cwd, deck.dir)) {
     return hint;
   }
-  const naming = deckAround(cwd) === undefined ? deck.name : `--deck ${deck.name}`;
-  return hint.replace(COMMAND_RE, (whole, command: string, rest: string) => {
-    if (!DECK_COMMANDS.has(command) || namesDeck(rest, deck.name)) {
-      return whole;
-    }
-    return `\`dekc ${command} ${naming}${rest}\``;
-  });
+  const word = shellName(deck.name) ?? DECK_PLACEHOLDER;
+  const inOther = deckAround(cwd) !== undefined;
+  // The note a placeholder adds names `dekc ls` for the project, not for the deck.
+  const note = hint.indexOf(PLACEHOLDER_NOTE);
+  let placed = false;
+  const addressed = hint.replace(
+    COMMAND_RE,
+    (whole, command: string, rest: string, offset: number) => {
+      const subcommand = SUBCOMMAND_WORDS.get(command)?.has(deck.name) === true;
+      // A first word that is a subcommand, or a flag, is never the deck's name.
+      const positional = !subcommand && !deck.name.startsWith("-");
+      if (
+        !DECK_COMMANDS.has(command) ||
+        namesDeck(rest, positional ? word : undefined) ||
+        (note >= 0 && offset >= note && offset < note + PLACEHOLDER_NOTE.length)
+      ) {
+        return whole;
+      }
+      placed ||= word === DECK_PLACEHOLDER;
+      const flag = inOther || subcommand;
+      return `\`dekc ${command} ${flag ? deckFlag(deck.name) : deckWord(deck.name)}${rest}\``;
+    },
+  );
+  return placed && note < 0 && noted ? `${addressed}${PLACEHOLDER_NOTE}` : addressed;
+}
+
+/** `hint` with where to find a deck's name, once, when one of its commands has `<deck>` for it. */
+export function withPlaceholderNote(hint: string): string {
+  return hint.includes(DECK_PLACEHOLDER) && !hint.includes(PLACEHOLDER_NOTE)
+    ? `${hint}${PLACEHOLDER_NOTE}`
+    : hint;
+}
+
+/** Where a hint with `<deck>` in it says to find the deck's name. */
+const PLACEHOLDER_NOTE = "; for <deck>, name the deck as `dekc ls` lists it";
+
+/** What a command shows for a deck no word holds alike in every shell. */
+const DECK_PLACEHOLDER = "<deck>";
+
+/**
+ * A deck's name as the first word of a command: one shell word, `<deck>` when there is none, or
+ * `--deck=` when the name starts with a dash, which a first word would read as a flag.
+ */
+export function deckWord(name: string): string {
+  return name.startsWith("-") ? deckFlag(name) : (shellName(name) ?? DECK_PLACEHOLDER);
+}
+
+/** A deck's name as `--deck`, joined with `=` when it starts with a dash, as a value must be. */
+export function deckFlag(name: string): string {
+  const word = shellName(name) ?? DECK_PLACEHOLDER;
+  return name.startsWith("-") ? `--deck=${word}` : `--deck ${word}`;
 }
 
 /** A backquoted command: `dekc`, a command word, and what follows it up to the closing quote. */
@@ -33,20 +87,43 @@ const DECK_COMMANDS = new Set(
   Object.entries(COMMANDS).flatMap(([name, spec]) => ("scope" in spec && spec.scope ? [name] : [])),
 );
 
-function namesDeck(rest: string, name: string): boolean {
-  const [first] = rest.trim().split(/\s+/);
-  return first === name || first?.includes("/") === true || /(?:^| )--deck(?: |$)/.test(rest);
+/** The first word of each command's subcommands, which a deck's name in its place would read as. */
+const SUBCOMMAND_WORDS = new Map(
+  Object.entries(COMMANDS).map(([name, spec]) => [
+    name,
+    new Set(Object.keys(subcommandsOf(spec as AnySpec)).map((sub) => sub.split(" ")[0])),
+  ]),
+);
+
+/**
+ * Whether a command's words already name a deck: as `word`, the deck's name as one shell word,
+ * when the deck can be named first, as a ref, or with --deck.
+ */
+function namesDeck(rest: string, word: string | undefined): boolean {
+  const words = rest.trim();
+  const [first] = words.split(/\s+/);
+  return (
+    (word !== undefined && (words === word || words.startsWith(`${word} `))) ||
+    first?.includes("/") === true ||
+    /(?:^| )--deck(?:[ =]|$)/.test(rest)
+  );
 }
 
 /**
  * The deck `path` lies in: the directory under a project's `decks/`, found from the path alone.
- * A source path dek reports is absolute, so no project needs to be resolved to address it.
+ * A source path dek reports is absolute, so no project needs to be resolved to address it. A
+ * deck that is not there, such as the one a `deck "nope" not found` points at, is none, and a
+ * ref's deck, in a snapshot as dek writes one, is named by the ref, as every command that reads
+ * one takes it.
  */
 export function deckAround(path: string): HintDeck | undefined {
   for (let dir = path; dirname(dir) !== dir; dir = dirname(dir)) {
     const parent = dirname(dir);
-    if (basename(parent) === "decks" && existsSync(join(dirname(parent), "dek.toml"))) {
-      return { name: basename(dir), dir };
+    const root = dirname(parent);
+    if (basename(parent) === "decks" && existsSync(join(root, "dek.toml"))) {
+      return statSync(dir, { throwIfNoEntry: false })?.isDirectory()
+        ? { name: snapshotName(root) ?? basename(dir), dir }
+        : undefined;
     }
   }
   return undefined;

package/src/cli/build.ts

@@ -5,7 +5,7 @@ import { lintDeck, lintProject } from "../core/lint.ts";
 import { parsePublicUrl } from "../core/ogp.ts";
 import { PLAYWRIGHT_INSTALL, type PlaywrightRunner } from "../core/playwright.ts";
 import { playerScript } from "../runtime/player.ts";
-import { type SkippedCheck, skippedChecks, visualSkipped } from "./result.ts";
+import { RENDERED_RULES, type SkippedCheck, skippedChecks, visualSkipped } from "./result.ts";
 import type { DecksTarget } from "./scope.ts";
 
 /**
@@ -77,7 +77,7 @@ export async function buildCommand(
     ...skippedChecks([
       ...skipped,
       visualSkipped("dekc lint --visual", {
-        reason: "overflow and contrast are measured only by `dekc lint --visual`",
+        reason: `${RENDERED_RULES} are measured only by \`dekc lint --visual\``,
         ...(options.runner ? { runner: options.runner } : {}),
       }),
     ]),

package/src/cli/check.ts

@@ -1,5 +1,6 @@
 import type { Diagnostic } from "../core/diagnostic.ts";
 import { DekError } from "../core/error.ts";
+import { shellQuote } from "../core/escape.ts";
 import type { Fill } from "../core/fill.ts";
 import { lintDeck } from "../core/lint.ts";
 import { type PlaywrightRunner, playwrightMissingError } from "../core/playwright.ts";
@@ -53,7 +54,7 @@ export async function checkCommand(
 
   const skipped: SkippedCheck[] = visual
     ? []
-    : [visualSkipped(`dekc check ${slug}`, { reason: "Playwright is not installed" })];
+    : [visualSkipped(`dekc check ${shellQuote(slug)}`, { reason: "Playwright is not installed" })];
 
   // A live-only deck is done without voice, so asking for it skips the check rather than failing,
   // the way a missing Playwright skips visual.