rshow 0.0.4 → 0.0.6

package/dist/main.js

@@ -13,7 +13,7 @@ import process from "node:process";
 // src/version.ts
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-var VERSION = true ? "0.0.4" : versionFromPackage();
+var VERSION = true ? "0.0.6" : versionFromPackage();
 
 // src/binary.ts
 var ASSET_MANIFEST = "assets.json";
@@ -969,6 +969,7 @@ commands:
   delete <slug> --yes     delete an artifact
   login [--url u]         save the API token for this account
   logout [--url u]        remove the saved token for a server
+  completion <shell>      print a completion script for bash, zsh or fish
 
 global:
   --json                  print the API reply JSON
@@ -1243,6 +1244,19 @@ var LOGOUT_USAGE = `usage: rshow logout [--url u]
 
 Removes the token this server has from every store that holds it: the macOS
 Keychain, the Linux keyring and the 0600 credentials file.`;
+var COMPLETION_USAGE = `usage: rshow completion <bash|zsh|fish>
+
+Prints a completion script for that shell on stdout. It lists every command
+and its long options, and it completes files and folders for the commands that
+take one. It is static: a completion never calls the API.
+
+load it once per machine:
+  bash  rshow completion bash > ~/.local/share/bash-completion/completions/rshow
+  zsh   rshow completion zsh > ~/.local/share/zsh/site-functions/_rshow
+        (that folder must be on $fpath, before compinit)
+  fish  rshow completion fish > ~/.config/fish/completions/rshow.fish
+
+The curl installer writes all three, and an npm install runs one of them.`;
 var PROJECT_USAGE = `usage: rshow project <create|list|show|share|delete> [options]
 
   project create <slug> [--title t] [--description d]
@@ -8388,7 +8402,8 @@ var USAGE = {
   pin: PIN_USAGE,
   delete: DELETE_USAGE,
   login: LOGIN_USAGE,
-  logout: LOGOUT_USAGE
+  logout: LOGOUT_USAGE,
+  completion: COMPLETION_USAGE
 };
 var WHEN = {
   ok: "the work was done.",
@@ -8716,6 +8731,328 @@ async function run18(argv, ctx) {
   ctx.out.line(`wrote ${path24.join(out, "exit-codes.md")}`);
 }
 
+// src/commands/completion.ts
+var SHELLS = ["bash", "zsh", "fish"];
+var GLOBAL_OPTIONS = [
+  { name: "--json", description: "print the API reply JSON" },
+  { name: "--help", description: "show this help" },
+  { name: "--version", description: "print rshow <version>" }
+];
+var SKILL_TARGETS2 = ["claude", "pi", "codex"];
+var SPECS = {
+  publish: { usage: PUBLISH_USAGE, path: true },
+  check: { usage: CHECK_USAGE, path: true },
+  handoff: { usage: HANDOFF_USAGE, path: true },
+  compare: { usage: COMPARE_USAGE },
+  preview: { usage: PREVIEW_USAGE, path: true },
+  config: { usage: CONFIG_USAGE, path: true },
+  init: { usage: INIT_USAGE },
+  doctor: { usage: DOCTOR_USAGE, path: true },
+  theme: { usage: THEME_USAGE },
+  "theme new": { usage: THEME_NEW_USAGE },
+  "theme check": { usage: THEME_CHECK_USAGE, path: true },
+  "theme preview": { usage: THEME_PREVIEW_USAGE, path: true },
+  "theme publish": { usage: THEME_PUBLISH_USAGE, path: true },
+  "theme list": { usage: THEME_LIST_USAGE },
+  skills: { usage: SKILLS_USAGE },
+  "skills install": { usage: SKILLS_INSTALL_USAGE, choices: SKILL_TARGETS2 },
+  "skills uninstall": { usage: SKILLS_UNINSTALL_USAGE, choices: SKILL_TARGETS2 },
+  "skills status": { usage: SKILLS_STATUS_USAGE, choices: SKILL_TARGETS2 },
+  project: { usage: PROJECT_USAGE },
+  "project create": { usage: PROJECT_CREATE_USAGE },
+  "project list": { usage: PROJECT_LIST_USAGE },
+  "project show": { usage: PROJECT_SHOW_USAGE },
+  "project share": { usage: PROJECT_SHARE_USAGE },
+  "project delete": { usage: PROJECT_DELETE_USAGE },
+  tag: { usage: TAG_USAGE },
+  list: { usage: LIST_USAGE },
+  show: { usage: SHOW_USAGE },
+  share: { usage: SHARE_USAGE },
+  pin: { usage: PIN_USAGE },
+  delete: { usage: DELETE_USAGE },
+  login: { usage: LOGIN_USAGE },
+  logout: { usage: LOGOUT_USAGE },
+  completion: { usage: COMPLETION_USAGE, choices: [...SHELLS] }
+};
+function optionsOf(usage) {
+  const out = [];
+  for (const found of usageLine(usage).matchAll(/--([a-z][a-z0-9-]*)(?:\s+([^[\]\s|]+))?/g)) {
+    out.push({ name: `--${found[1]}`, value: found[2] });
+  }
+  return out;
+}
+function summaryOf2(name) {
+  const words = name.split(" ");
+  const parent = SPECS[words[0]];
+  const text = words.length === 1 || parent === void 0 ? GENERAL_USAGE : parent.usage;
+  for (const line of text.split("\n")) {
+    if (!/^ {2}\S/.test(line)) continue;
+    const parts2 = line.trim().split(/ {2,}/);
+    const spec = (parts2[0] ?? "").split(" ");
+    if (spec[0] !== words[0]) continue;
+    if (words.length === 2 && spec[1] !== words[1]) continue;
+    if (parts2.length > 1) return parts2.slice(1).join(" ").trim();
+    let index = 1;
+    while (index < spec.length && /^(?:<[^>]+>|\[[^\]]*\]|--?\S+)$/.test(spec[index])) index += 1;
+    const summary = spec.slice(index).join(" ").trim();
+    return summary.startsWith("[") ? "" : summary;
+  }
+  return "";
+}
+function specs() {
+  return Object.entries(SPECS).map(([name, entry]) => ({
+    words: name.split(" "),
+    options: optionsOf(entry.usage),
+    path: entry.path === true,
+    choices: entry.choices ?? [],
+    summary: summaryOf2(name)
+  }));
+}
+function childrenOf(all, parent) {
+  return all.filter((spec) => spec.words.length === 2 && spec.words[0] === parent);
+}
+function quoted2(text) {
+  return `'${text.replace(/'/g, "'\\''")}'`;
+}
+function described(name, summary) {
+  return quoted2(summary === "" ? name : `${name}:${summary}`);
+}
+function bashScript() {
+  const all = specs();
+  const top = all.filter((spec) => spec.words.length === 1);
+  const arms = all.map((spec) => {
+    const key2 = quoted2(spec.words.join(" "));
+    const children = childrenOf(all, spec.words[0]);
+    const names = spec.options.map((option) => option.name);
+    const values = spec.options.filter((option) => option.value !== void 0).map((option) => option.name);
+    const parts2 = [];
+    const choices = spec.words.length === 1 && children.length > 0 ? children.map((child) => child.words[1]) : spec.choices;
+    if (choices.length > 0) parts2.push(`choices='${choices.join(" ")}'`);
+    if (names.length > 0) parts2.push(`opts="$opts ${names.join(" ")}"`);
+    if (values.length > 0) parts2.push(`vals='${values.join(" ")}'`);
+    if (spec.path) parts2.push("paths=1");
+    return `    ${key2}) ${parts2.length === 0 ? ":" : parts2.join("; ")} ;;`;
+  });
+  return [
+    "# bash completion for rshow, printed by `rshow completion bash`.",
+    "# Load it with",
+    "#   rshow completion bash > ~/.local/share/bash-completion/completions/rshow",
+    "",
+    `_rshow_commands='${top.map((spec) => spec.words[0]).join(" ")}'`,
+    `_rshow_options='${GLOBAL_OPTIONS.map((option) => option.name).join(" ")}'`,
+    "",
+    "_rshow() {",
+    "  local cur prev cmd sub key word opts vals paths choices i",
+    "  COMPREPLY=()",
+    '  cur="${COMP_WORDS[COMP_CWORD]}"',
+    "  prev=''",
+    '  if [ "$COMP_CWORD" -gt 0 ]; then',
+    '    prev="${COMP_WORDS[COMP_CWORD-1]}"',
+    "  fi",
+    "",
+    "  i=1",
+    '  while [ "$i" -lt "$COMP_CWORD" ]; do',
+    '    word="${COMP_WORDS[i]}"',
+    '    case "$word" in',
+    "      -*) ;;",
+    "      *)",
+    '        if [ -z "$cmd" ]; then',
+    '          cmd="$word"',
+    '        elif [ -z "$sub" ]; then',
+    '          sub="$word"',
+    "        fi",
+    "        ;;",
+    "    esac",
+    "    i=$((i + 1))",
+    "  done",
+    "",
+    '  if [ -z "$cmd" ]; then',
+    '    COMPREPLY=( $(compgen -W "$_rshow_commands $_rshow_options" -- "$cur") )',
+    "    return 0",
+    "  fi",
+    "",
+    '  key="$cmd"',
+    '  if [ -n "$sub" ]; then',
+    '    key="$cmd $sub"',
+    "  fi",
+    "",
+    '  opts="$_rshow_options"',
+    "  vals=''",
+    "  paths=''",
+    "  choices=''",
+    '  case "$key" in',
+    ...arms,
+    "    *) return 0 ;;",
+    "  esac",
+    "",
+    "  # A flag that takes a value completes nothing: the value is a slug or a",
+    "  # folder, and this script never asks the API.",
+    '  if [ -n "$vals" ]; then',
+    '    case " $vals " in',
+    '      *" $prev "*) return 0 ;;',
+    "    esac",
+    "  fi",
+    "",
+    '  case "$cur" in',
+    "    -*)",
+    '      COMPREPLY=( $(compgen -W "$opts" -- "$cur") )',
+    "      return 0",
+    "      ;;",
+    "  esac",
+    "",
+    '  if [ -n "$choices" ]; then',
+    '    COMPREPLY=( $(compgen -W "$choices" -- "$cur") )',
+    "    return 0",
+    "  fi",
+    '  if [ -n "$paths" ]; then',
+    '    COMPREPLY=( $(compgen -f -- "$cur") )',
+    "    return 0",
+    "  fi",
+    "  return 0",
+    "}",
+    "",
+    "complete -F _rshow rshow"
+  ].join("\n");
+}
+function zshArguments(spec) {
+  const parts2 = GLOBAL_OPTIONS.map((option) => quoted2(`${option.name}[${option.description}]`));
+  for (const option of spec.options) {
+    parts2.push(quoted2(option.value === void 0 ? option.name : `${option.name}=`));
+  }
+  if (spec.choices.length > 0) parts2.push(quoted2(`*: :(${spec.choices.join(" ")})`));
+  else if (spec.path) parts2.push(quoted2("*:file or folder:_files"));
+  return `_arguments ${parts2.join(" ")}`;
+}
+function zshScript() {
+  const all = specs();
+  const top = all.filter((spec) => spec.words.length === 1);
+  const groups = top.filter((spec) => childrenOf(all, spec.words[0]).length > 0);
+  const arms = all.map((spec) => {
+    const children = childrenOf(all, spec.words[0]);
+    const key2 = quoted2(spec.words.join(" "));
+    if (spec.words.length === 1 && children.length > 0) {
+      const subs = children.map((child) => `          ${described(child.words[1], child.summary)}`);
+      return [
+        `        ${key2})`,
+        "          subs=(",
+        ...subs,
+        "          )",
+        `          _describe -t commands ${quoted2(`${spec.words[0]} command`)} subs`,
+        "          ;;"
+      ].join("\n");
+    }
+    return `        ${key2}) ${zshArguments(spec)} ;;`;
+  });
+  return [
+    "#compdef rshow",
+    "",
+    "# Completion for rshow, printed by `rshow completion zsh`.",
+    "# Load it with",
+    "#   rshow completion zsh > ~/.local/share/zsh/site-functions/_rshow",
+    "# and keep that folder on $fpath, before compinit.",
+    "",
+    "_rshow() {",
+    "  local -a commands subs groups",
+    "  local state key",
+    "",
+    "  groups=(",
+    ...groups.map((spec) => `    ${quoted2(spec.words[0])}`),
+    "  )",
+    "",
+    "  _arguments -C \\",
+    ...GLOBAL_OPTIONS.map((option) => `    ${quoted2(`${option.name}[${option.description}]`)} \\`),
+    "    '1: :->command' \\",
+    "    '*:: :->args' && return 0",
+    "",
+    "  case $state in",
+    "    command)",
+    "      commands=(",
+    ...top.map((spec) => `        ${described(spec.words[0], spec.summary)}`),
+    "      )",
+    "      _describe -t commands 'rshow command' commands",
+    "      ;;",
+    "    args)",
+    "      key=$words[1]",
+    "      if (( $groups[(Ie)$words[1]] )); then",
+    "        case $words[2] in",
+    "          ''|-*) ;;",
+    '          *) key="$words[1] $words[2]" ;;',
+    "        esac",
+    "      fi",
+    "      case $key in",
+    ...arms,
+    "      esac",
+    "      ;;",
+    "  esac",
+    "}",
+    "",
+    "# Sourced from a shell that runs compinit as well as autoloaded from $fpath.",
+    "if (( $+functions[compdef] )); then",
+    "  compdef _rshow rshow",
+    "fi"
+  ].join("\n");
+}
+function fishScript() {
+  const all = specs();
+  const top = all.filter((spec) => spec.words.length === 1);
+  const condition = (words) => words.map((word) => `__fish_seen_subcommand_from ${word}`).join("; and ");
+  const lines = [
+    "# fish completion for rshow, printed by `rshow completion fish`.",
+    "# Load it with",
+    "#   rshow completion fish > ~/.config/fish/completions/rshow.fish",
+    "",
+    "complete -c rshow -f",
+    "",
+    "# commands"
+  ];
+  for (const spec of top) {
+    const summary = spec.summary === "" ? "" : ` -d ${quoted2(spec.summary)}`;
+    lines.push(`complete -c rshow -n __fish_use_subcommand -a ${quoted2(spec.words[0])}${summary}`);
+  }
+  for (const spec of all.filter((entry) => entry.words.length === 2)) {
+    const parent = spec.words[0];
+    const siblings = childrenOf(all, parent).map((child) => child.words[1]);
+    const summary = spec.summary === "" ? "" : ` -d ${quoted2(spec.summary)}`;
+    lines.push(
+      `complete -c rshow -n ${quoted2(
+        `__fish_seen_subcommand_from ${parent}; and not __fish_seen_subcommand_from ${siblings.join(" ")}`
+      )} -a ${quoted2(spec.words[1])}${summary}`
+    );
+  }
+  lines.push("", "# options");
+  for (const option of GLOBAL_OPTIONS) {
+    lines.push(`complete -c rshow -l ${option.name.slice(2)} -d ${quoted2(option.description)}`);
+  }
+  for (const spec of all) {
+    const seen = quoted2(condition(spec.words));
+    for (const option of spec.options) {
+      const value = option.value === void 0 ? "" : " -r";
+      lines.push(`complete -c rshow -n ${seen} -l ${option.name.slice(2)}${value}`);
+    }
+    if (spec.choices.length > 0) lines.push(`complete -c rshow -n ${seen} -a ${quoted2(spec.choices.join(" "))}`);
+    else if (spec.path) lines.push(`complete -c rshow -n ${seen} -F`);
+  }
+  return lines.join("\n");
+}
+function script(shell) {
+  if (shell === "bash") return bashScript();
+  if (shell === "zsh") return zshScript();
+  return fishScript();
+}
+function isShell(value) {
+  return SHELLS.includes(value);
+}
+async function run19(argv, ctx) {
+  const args = parseCommandArgs(argv, {}, 0, 1, COMPLETION_USAGE);
+  const shell = args.positionals[0];
+  if (shell === void 0) {
+    throw new UsageError(`completion needs a shell: bash, zsh or fish (try: ${usageLine(COMPLETION_USAGE)})`);
+  }
+  if (!isShell(shell)) throw new UsageError(`unknown shell: ${shell} (use bash, zsh or fish)`);
+  ctx.out.raw(script(shell));
+  return EXIT.ok;
+}
+
 // src/commands/login.ts
 import process21 from "node:process";
 async function hiddenLine() {
@@ -8773,7 +9110,7 @@ function reasonOf(err) {
   const lines = text.split("\n").map((part) => part.trim()).filter((part) => part !== "");
   return lines.at(-1) ?? "";
 }
-async function run19(argv, ctx, platform = process21.platform) {
+async function run20(argv, ctx, platform = process21.platform) {
   const args = parseCommandArgs(argv, { url: { type: "string" } }, 0, 0, LOGIN_USAGE);
   const settings = await ctx.config();
   const given = (stringValue(args, "url") ?? "").trim();
@@ -8802,7 +9139,7 @@ async function run19(argv, ctx, platform = process21.platform) {
 
 // src/commands/logout.ts
 import process22 from "node:process";
-async function run20(argv, ctx, platform = process22.platform) {
+async function run21(argv, ctx, platform = process22.platform) {
   const args = parseCommandArgs(argv, { url: { type: "string" } }, 0, 0, LOGOUT_USAGE);
   const settings = await ctx.config();
   const given = (stringValue(args, "url") ?? "").trim();
@@ -8837,8 +9174,9 @@ var COMMANDS = {
   share: { usage: SHARE_USAGE, run: run11 },
   pin: { usage: PIN_USAGE, run: run12 },
   delete: { usage: DELETE_USAGE, run: run13 },
-  login: { usage: LOGIN_USAGE, run: run19 },
-  logout: { usage: LOGOUT_USAGE, run: run20 },
+  login: { usage: LOGIN_USAGE, run: run20 },
+  logout: { usage: LOGOUT_USAGE, run: run21 },
+  completion: { usage: COMPLETION_USAGE, run: run19 },
   // Kept out of the general help: the docs site runs it, a person rarely does.
   docs: { usage: DOCS_USAGE, run: run18 }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rshow",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Publish static artifacts to rshow",
   "license": "MIT",
   "homepage": "https://rslib.github.io/rshow",

package/skills/rshow/SKILL.md

@@ -47,8 +47,13 @@ Copy this checklist into the reply and tick it as you go.
   The only exceptions are `/_themes/...` and `/_data/...`.
 - Link the theme, never copy it.
   The stylesheet links and `mode.js` in the head all carry the same `<name>@<n>` version.
-- Override tokens in one `:root` block, five declarations at most.
-  No selectors, no rules, no `!important`.
+- The theme is the base, not a cage.
+  A page may carry one inline `<style>` block with its own classes and its own layouts when the content needs them.
+  Own CSS takes colour, type and space from the theme tokens with `var(--...)`, so light, dark, print and a theme swap keep working.
+  A hard-coded colour sits inside a figure only.
+- Own CSS adds a class and never restyles a theme class globally.
+  Scope a new deck layout as `.slide.<name>` and scope a page part under its own class name, and use no `!important`.
+- A token override still goes in one `:root` block, with no limit on the declarations.
 - Keep the script and the styles inline.
   Add a framework only when the page needs one.
 - `connect-src` is `'self'`.
@@ -64,9 +69,10 @@ Copy this checklist into the reply and tick it as you go.
   Print `[PLACEHOLDER]` and say so in the footer.
 - The look is IBM Carbon on IBM Plex, and every colour has one job.
   `themes/DESIGN.md` in the rshow repo holds the system, the type scale and the layout set.
-- Fixed templates carry decks, reports, posters, project pages and dashboards, so the sections are set and the content is the work.
+- Documented templates carry decks, reports, posters, project pages and dashboards, so the markup is documented and the content is the work.
+  The markup is the starting point, and a page adds its own parts with its own classes when it needs them.
 - Guided kits carry mockups, sketches and TUIs, so the kit gives you a frame, a floor and a checklist and the drawing is the work.
-  Starting a kit at its highest fidelity is the same mistake as decorating a fixed template.
+  Starting a kit at its highest fidelity is the same mistake as decorating a documented template.
 
 ## Audience
 

package/skills/rshow/reference/dashboard.md

@@ -11,7 +11,7 @@
 - Checks
 
 A results dashboard is the page a reader works in rather than reads: a filter bar, a summary, small multiples and the table of rows behind them.
-It is a fixed template, so the four blocks are set and the data is the work.
+It is a documented template, so the four blocks are the starting point and the data is the work, and a page may add its own parts with its own classes.
 `dashboard.css` sets the look and `dashboard.js` reads the data, draws the chart and keeps the view in the link.
 
 ## What it is for

package/skills/rshow/reference/mockups.md

@@ -13,15 +13,17 @@
 - Look at it
 
 A mockup is a drawing of a product that does not exist yet, so it follows that product and not rshow.
-Decks, reports, posters, project pages and dashboards are fixed templates, while a mockup is a guided kit: the kit gives you a frame, a floor and a checklist, and the drawing is the work.
+Decks, reports, posters, project pages and dashboards are documented templates, while a mockup is a guided kit: the kit gives you a frame, a floor and a checklist, and the drawing is the work.
 `themes/MOCKUPS.md` in the rshow repo holds the kit itself, and this file is what to do with it.
 
 ## A guided kit
 
-- Start in `wire` every time, because a tidy drawing invites a room to argue about the colour of a button instead of the order of the steps.
-- Move to `sketch` when the room is too polite about a finished looking picture.
-- Move to a platform skin only when the look of the product is the decision.
+- Pick the skin from the question.
+- Use `wire` when the flow or the order of the layout is the question, because a tidy drawing invites a room to argue about the colour of a button instead of the order of the steps.
+- Use `sketch` for an early rough idea, or when the room is too polite about a finished looking picture.
+- Use a platform skin, or `tui` and `terminal` for a terminal, when the look is the decision or the person asks for the look.
 - Keep the inventing to layout, spacing, hierarchy and the order of steps.
+  Own CSS inside a screen is allowed for the part the kit lacks, and it takes colour from the `--mk-*` and theme tokens so a skin swap and dark mode still read.
   Data, copy, names and prices are placeholders and say so.
 
 ## Markup
@@ -108,6 +110,7 @@ Never present invented data as if somebody measured it.
 
 - `rshow check <dir>` exits 0, then `rshow preview <dir>`.
 - Look at the canvas, the focus view and Play mode, in both modes, at desktop width and at 360px.
+- Press `?` on the page for the keys: `w` `a` `s` `d` or the arrows pan, `[` `]` step between screens, `Enter` opens one, `1` to `9` pick a state, so tell the person about that list.
 - Switch the skin in the toolbar and check the drawing still reads.
 - Print puts one artboard on a page with no tool chrome, which is what a review meeting wants on paper.
 - `rshow publish <dir> --slug <slug> --label "<what changed>"`, then read `rshow-implement` before anybody writes code from it.

package/skills/rshow/reference/pages.md

@@ -71,9 +71,11 @@ Every link carries the same version on purpose, because a mixed version renders
 ```
 
 `page.css` gives you `lede`, `table`, `num-cell`, `muted`, `small` and `mono`, plus the heading, list, figure, table and code rules.
-Use them and keep your own CSS to the one `:root` block.
+The theme is the base, not a cage.
+Use these classes first, and add a class of your own in one inline `<style>` block when the page needs a part the theme does not carry.
+Own CSS takes colour, type and space from the tokens with `var(--...)`, and it never restyles a theme class globally.
 There is no card class, no label class and no number tile.
-A page that needs one is usually a page with a table it has not written yet.
+A page that needs one writes it, and a page that needs only a table writes the table.
 
 The theme carries both modes, so the same page reads on white and on g100 with nothing in the page itself.
 
@@ -96,8 +98,8 @@ Print is always light, whatever the screen was.
 
 ## Token overrides
 
-Override a token instead of writing rules.
-Five declarations cover most restyling.
+Override a token instead of restyling a theme class.
+A few declarations cover most restyling, and there is no limit on how many.
 
 ```html
 <style>:root{

package/skills/rshow/reference/poster.md

@@ -11,7 +11,7 @@
 - Checks
 
 A poster is one sheet that prints from the browser, in the same theme as a page, a report and a project page.
-It is a fixed template, so the sheet, the columns and the print are set and the blocks are the work.
+It is a documented template, so the sheet, the columns and the print are set and the blocks are the starting point, and a page may add its own parts with its own classes.
 `poster.css` sets the look and `poster.js` sets the scale, the QR code and the one page print.
 
 ## The sheet

package/skills/rshow/reference/project-page.md

@@ -11,7 +11,7 @@
 - Checks
 
 A project page is the landing page of a paper, and it uses the same theme as a page, a report and a poster.
-It is a fixed template, so the sections are set and the content is the work.
+It is a documented template, so the sections are the starting point and the content is the work, and a page may add its own parts with its own classes.
 `project.css` sets the look and `project.js` does one thing, the copy button on the BibTeX entry.
 
 A project page is not a project.

package/skills/rshow/reference/sketch.md

@@ -11,7 +11,7 @@
 - Checks
 
 A sketch is a hand drawn figure from Excalidraw, read in the page and edited in place.
-It is a guided kit rather than a fixed template: `sketch.css` is the bar around the canvas and `sketch.js` is the canvas.
+It is a guided kit rather than a documented template: `sketch.css` is the bar around the canvas and `sketch.js` is the canvas.
 Use it for an architecture drawing, a flow of systems or an idea that should look unfinished.
 
 ## When a sketch

package/skills/rshow-slides/SKILL.md

@@ -6,8 +6,8 @@ description: Load before you build or revise a talk, deck or presentation. Load
 # rshow slides
 
 A deck is a folder with one `index.html` in it, published to `https://art.example.com/<slug>/`.
-It links the deck half of a published theme, so the folder holds no CSS, no font and no script of its own.
-The theme does the layout, and the deck only picks a layout per slide.
+It links the deck half of a published theme, so the folder holds no copy of the theme, no font and no script of its own.
+The theme does the layout, and the deck picks a layout per slide or adds one of its own in an inline `<style>` block.
 The look is IBM Carbon on IBM Plex, and `themes/DESIGN.md` in the rshow repo holds the whole system.
 
 ## 1. Outline first
@@ -23,6 +23,7 @@ A topic on its own is not a slide.
 - Open with a `title` slide and close with a `title` slide or a `big-number` that says what to do next.
 - Put one `section` slide before each move in the argument.
 - Give the evidence slides the layout that carries the claim: `figure`, `chart`, `table` or `figure-two` for a research or systems talk.
+- Name the layout of each line in the outline, including any layout the deck adds for itself.
 - In a research talk the figure, the plot and the table are the hero.
   The title says what the evidence shows and the type stays out of the way.
 - Say which slide carries the headline number, and put the number in it once.
@@ -71,11 +72,12 @@ Replace `<name>@<n>` with the `theme` value that `rshow config <dir>` prints, wh
 
 The three stylesheet links and the script carry the same `<n>` on purpose, because a mixed version renders somewhere between two designs.
 The deck needs no `mode.js`, because `deck.js` reads the same key and `t` does the same work.
-Override a token in one `:root` block after the theme links when the deck needs its own accent, and keep it to a few declarations.
+Override a token in one `:root` block after the theme links when the deck needs its own accent, with no limit on the declarations.
+An inline `<style>` block after the theme links may also carry a layout of the deck's own, as section 3 says.
 
 ## 3. Layouts
 
-Every slide is a `<section class="slide ...">`, and the second class is one of twelve.
+Every slide is a `<section class="slide ...">`, and the second class is one of twelve or one the deck adds.
 
 - `title` for the opener, `section` for a divider and `statement` for one claim set large.
 - `bullets` for a takeaway title and at most five short points.
@@ -89,8 +91,11 @@ A bullets slide puts its points under the title at 28px with a 1.4 line, five at
 A figure slide starts at the top and lets the figure take the rest.
 A figure is `<figure>` with a `figcaption`, and two figures are `<div class="pair">` with two `<figure>` inside.
 A big number is `<p class="value">` plus `<p class="caption">`, and the value is a short statement with the figure inside it, never a bare digit.
-Do not invent a thirteenth layout and do not write the layout CSS yourself, because the theme owns it and a copy drifts.
-[layouts](reference/layouts.md) holds one markup example per layout. Read it before you write a slide that is not `title`, `bullets` or `section`.
+The twelve layouts are a starting set and not a ceiling.
+Invent a layout when none of them carries the claim, such as an annotated figure, a figure with a callout, a diagram built in HTML or SVG, a timeline, a before and after or a comparison grid.
+Give it a short class name and put its CSS in the deck's own `<style>` block, scoped to `.slide.<name>` and taken from the tokens.
+Vary the rhythm: do not run more than three text slides (`two-col` or `bullets`) in a row, and turn a text slide that explains a figure into an annotated figure.
+[layouts](reference/layouts.md) holds one markup example per layout and one worked example of your own layout. Read it before you write a slide that is not `title`, `bullets` or `section`.
 
 ## 4. Notes and steps
 
@@ -99,13 +104,16 @@ Do not invent a thirteenth layout and do not write the layout CSS yourself, beca
   It is what you say, not what the room reads.
 - Press `n` for the notes window, which also names the next slide.
 - Press `p` for the presenter view: the current slide, the next slide, the notes and an elapsed timer, kept in step with the deck.
-- Put `class="step"` on an `<li>` to reveal it one press later.
+- Put `class="step"` on any element inside a slide to reveal it one press later, because `deck.js` selects every `.step` in the slide.
+  That is how a diagram builds up in steps.
 - Every step is a reveal, so a slide with four steps needs four presses.
   Five is the ceiling before the slide drags.
 - Press `f` for fullscreen and arrows or space to advance.
   Press `Ctrl` and `P` for a print sheet when someone wants a pdf.
 - Press `t` to cycle the mode: system, light, dark, with the mode shown in the counter for a moment.
   The choice is remembered for every rshow document and print is always light.
+- On a phone held upright the deck reads as a stack of slides, each one reflowed to the width of the screen at phone sizes with a rule and an `n / total` label between slides, and a `Present` button goes back to one slide at a time.
+  `Esc` comes back to reading, and the arrows, space and a `#n` link work in both.
 
 ## 5. Check, preview, publish
 
@@ -132,5 +140,6 @@ Publish again after a fix instead of making a second slug, because the link in t
 - Never use a hairline rule as decoration.
 - Never use Inter, Space Grotesk, Geist, Fraunces or Instrument Serif as the gesture.
 - Never use gradient text, glass, a large shadow or an emoji.
-- Never animate a slide in, because a reveal is the only motion a deck needs.
+- Never animate a slide in for decoration.
+  Motion is allowed when it explains something, such as a step that builds a diagram or a short transition that shows a change.
 - Never invent a number and never present example data without saying so in the caption.