create-obsidian-arrow 0.1.0 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-obsidian-arrow",
-  "version": "0.1.0",
+  "version": "0.1.5",
   "description": "Scaffold an Obsidian-styled Arrow.js UI sandbox (pnpm create obsidian-arrow <dir>).",
   "type": "module",
   "bin": {

package/template/AGENTS.md

@@ -4,8 +4,19 @@ Operating guide for AI agents working in **obsidian-arrow-sandbox** — a
 client-only environment for prototyping [Arrow.js](https://arrow-js.com/) UI that
 ports into an Obsidian plugin with near-zero refactoring.
 
-Full design + rationale: [`docs/superpowers/specs`](docs/superpowers/specs/2026-06-29-obsidian-arrow-sandbox-design.md).
-Deeper how-to skills: [`skills/`](skills/) (install via `npx skills`).
+## Docs map (start here)
+
+This file is the hub — everything else is linked from here:
+
+- [`docs/workflow.md`](docs/workflow.md) — fresh-machine → running workflow.
+- [`skills/`](skills/) — installable domain skills (`pnpm skills:install`):
+  obsidian-arrow-sandbox, arrow-js-obsidian-templates, arrow-js-obsidian-patterns,
+  arrow-js-obsidian-porting (sandbox→plugin parity check).
+- [`docs/prompts/agent-setup.md`](docs/prompts/agent-setup.md) — prompt for
+  briefing a fresh agent (scaffold + orient).
+
+Design rationale (why `core`+`framework`, no SSR, how `app.css` is sourced) is
+summarized in "What this is (and isn't)" below and in the README.
 
 ## What this is (and isn't)
 

package/template/CLAUDE.md

@@ -0,0 +1,4 @@
+# CLAUDE.md
+
+Read @AGENTS.md first — it's the operating guide and docs map (workflow, skills,
+footguns, conventions, and the design record are all linked from there).

package/template/README.md

@@ -6,8 +6,8 @@ written with `@arrow-js/core` (+ `@arrow-js/framework` for async boundaries) and
 styled entirely by Obsidian's real `app.css`, so what you see here is what you
 get inside a plugin view.
 
-See the design + decision record in
-[`docs/superpowers/specs`](docs/superpowers/specs/2026-06-29-obsidian-arrow-sandbox-design.md).
+New machine? See [`docs/workflow.md`](docs/workflow.md) for the full
+fresh-checkout-to-running workflow.
 
 ## Scaffold a new project
 
@@ -75,17 +75,26 @@ under [`skills/`](skills/) — it doubles as a local skill marketplace:
 - `arrow-js-obsidian-templates` — Arrow v1.0.6 template rules + footguns.
 - `arrow-js-obsidian-patterns` — integration patterns: icons (Lucide / data-icon
   sweep), CSS scoping vs Obsidian globals, mount/unmount lifecycle, reactive state.
+- `arrow-js-obsidian-porting` — content-addressed porting parity: the
+  `component-hash` tool + a husky/CI check that the plugin copy hasn't drifted
+  from the sandbox source.
 
-Install them into your agent via the interactive TUI:
+Install them into your agent:
 
 ```sh
-pnpm skills:install      # = npx skills add .  (pick skills in the TUI)
+pnpm skills:install                            # interactive picker (TUI) on a terminal
+pnpm skills:install --yes                      # non-interactive — installs ALL bundled skills
+pnpm skills:install --yes --agent claude-code  # install for one agent only
+pnpm skills:update                             # update an existing setup to the latest
 ```
 
-`postinstall` offers this automatically after `pnpm install`, but only in an
-interactive terminal — it skips in CI / non-TTY (set `SKIP_SKILLS_INSTALL=1` to
-opt out entirely). You can also add this repo from anywhere with
-`npx skills add <git-url-or-path>`.
+`postinstall` offers the picker automatically after `pnpm install`, but only in
+an interactive terminal — in CI / non-TTY it just prints how to install (never
+hangs). For agents/CI, use `--yes` (it runs `npx skills add . --all --yes`);
+`--agent <name>` (or `--agent=<name>`) targets one agent instead of all.
+`pnpm skills:update` runs `npx skills update -y`. The auto `postinstall` step
+takes no CLI args, so use `SKILLS_AGENT=<name>` (and `SKIP_SKILLS_INSTALL=1` to
+opt out) to influence *that* path.
 
 ## Porting a component into the plugin
 

package/template/docs/prompts/agent-setup.md

@@ -32,15 +32,16 @@ Then:
                     # or set OBSIDIAN_ASAR=<path>.
   pnpm dev          # open the printed URL: / is the examples index, /example the demo.
                     # The toolbar slider/presets + edge drag handle resize the panel.
-  pnpm skills:install   # install the bundled agent skills (npx skills add .) — pick
-                        # them in the TUI; this is how you load the domain knowledge.
+  pnpm skills:install --yes   # install ALL bundled agent skills non-interactively
+                              # (runs `npx skills add . --all --yes`) — this loads
+                              # the domain knowledge. Drop --yes for an interactive picker.
 
 READ FIRST
-- AGENTS.md (root) — operating guide: run, footguns, CSS scoping, verify, port.
+- AGENTS.md (root) — operating guide + docs map (links everything below).
+- docs/workflow.md — fresh-machine → running workflow.
 - skills/*/SKILL.md — obsidian-arrow-sandbox (workflow), arrow-js-obsidian-
   templates (template syntax + footguns), arrow-js-obsidian-patterns (icons via
   Lucide/data-icon sweep, CSS scoping, mount/unmount lifecycle, reactive state).
-- docs/superpowers/specs/ — design + decision record (why core+framework, no SSR).
 
 ARROW v1.0.6 FOOTGUNS — do not relearn these the hard way:
 1. NO literal HTML comments inside html`` templates — Arrow treats HTML comments

package/template/docs/workflow.md

@@ -0,0 +1,78 @@
+# Workflow
+
+How to go from a fresh machine to building Obsidian plugin UI in the sandbox.
+
+## Prerequisites (one-time, per machine)
+
+- **Node ≥ 18** and **pnpm** — `corepack enable` (ships with Node) or `npm i -g pnpm`.
+- **Obsidian desktop app installed** — required by `pull-css` to extract `app.css`.
+  macOS is auto-detected; Windows/WSL needs an explicit path (see below).
+
+## Spin up a sandbox
+
+```sh
+# 1. Scaffold from the published initializer (any one of these)
+pnpm create obsidian-arrow my-ui        # or: npm create obsidian-arrow@latest my-ui
+                                         # or: npx create-obsidian-arrow my-ui
+cd my-ui
+
+# 2. Install dependencies
+pnpm install
+
+# 3. Pull Obsidian's styling locally — REQUIRED before dev (needs Obsidian installed)
+pnpm pull-css                            # macOS: auto-detects /Applications/Obsidian.app
+                                         # else:  pnpm pull-css --path <obsidian.asar|app.css>
+                                         #        or  OBSIDIAN_ASAR=<path> pnpm pull-css
+
+# 4. Run it
+pnpm dev                                 # open the printed URL — / is the index, /example the demo
+```
+
+`public/app.css` is **git-ignored and never shipped** (it's Obsidian's proprietary
+CSS), so step 3 must run on every fresh checkout, or the sandbox renders unstyled.
+
+## Make your agent aware (optional)
+
+From inside the scaffolded project:
+
+```sh
+pnpm skills:install          # interactive picker (TUI) on a terminal
+pnpm skills:install --yes    # non-interactive — installs ALL bundled skills (for agents/CI)
+pnpm skills:update           # update an already-installed setup to the latest
+```
+
+Then point the agent at [`AGENTS.md`](../AGENTS.md), or brief a fresh agent with
+[`docs/prompts/agent-setup.md`](prompts/agent-setup.md).
+
+## Build → verify → port loop
+
+```sh
+# add a component in src/components/, register it in src/examples/registry.ts
+pnpm dev          # iterate with HMR
+pnpm run ci       # biome + typecheck + tests + build before trusting it
+```
+
+Always confirm the actual render in the browser — Arrow's footguns surface only
+at render, so a passing `tsc` is not proof a component works. See the footguns in
+[`AGENTS.md`](../AGENTS.md) and the `arrow-js-obsidian-templates` skill.
+
+**Port a component into a plugin:** copy the file into the plugin's view directory
+and mount it from `ItemView.onOpen()` via `template(this.contentEl)`. If it uses
+`boundary()`/async components, add `@arrow-js/framework` to the plugin and the
+side-effect `import '@arrow-js/framework'`. Leave `src/sandbox/*` behind.
+
+## Scaffold vs. clone
+
+- **Scaffold** (`pnpm create obsidian-arrow`) when you want to **build plugin UI** —
+  the normal use.
+- **Clone** this repo (`kylebrodeur/obsidian-arrow-sandbox`) only to **change the
+  sandbox or the initializer itself**, then `pnpm create:sync` and publish the
+  `create-obsidian-arrow/` package (`cd create-obsidian-arrow && pnpm publish`).
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `pnpm dev` renders unstyled / `var(--…)` not resolving | Run `pnpm pull-css` (step 3). |
+| `pull-css` can't find Obsidian | Pass `--path <obsidian.asar\|app.css>` or set `OBSIDIAN_ASAR` (Windows/WSL not auto-detected). |
+| `Invalid HTML position` at render | An Arrow footgun — no HTML comments in templates; attribute expressions must be the whole value. See `AGENTS.md`. |

package/template/package.json

@@ -18,6 +18,7 @@
 		"check": "biome check --write . && pnpm typecheck && pnpm test",
 		"ci": "biome ci . && pnpm typecheck && pnpm test && pnpm build",
 		"skills:install": "node scripts/install-skills.mjs --force",
+		"skills:update": "node scripts/install-skills.mjs --update",
 		"postinstall": "node scripts/install-skills.mjs",
 		"prepare": "husky"
 	},

package/template/scripts/component-hash.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * component-hash — sandbox -> plugin porting parity check.
+ *
+ * The sandbox is the source of truth for a component; the plugin gets a
+ * near-verbatim copy. This hashes the canonical *portable body* (imports +
+ * whitespace normalized out; see lib/canonical-source.mjs) so the hook flags
+ * only meaningful drift, not benign import/mount deltas.
+ *
+ * Usage:
+ *   node scripts/component-hash.mjs <file>
+ *       print the canonical hash of one component.
+ *
+ *   node scripts/component-hash.mjs --verify <sandbox-file> <plugin-file>
+ *       compare two files; exit 0 (PARITY OK) or 1 (DRIFT).
+ *
+ *   node scripts/component-hash.mjs --check <manifest.json> [--update]
+ *       check every entry; exit 1 on any drift. --update re-records the baseline
+ *       from the source of truth (sandbox if present, else the plugin copy).
+ *
+ * Manifest shape (paths resolved relative to the manifest file):
+ *   { "entries": [
+ *       { "plugin": "src/chat/arrow/Foo.ts",
+ *         "sandbox": "../obsidian-arrow-sandbox/src/components/Foo.ts",  // optional
+ *         "hash": "<sha256>" }                                          // optional fallback
+ *   ] }
+ *
+ * Pure Node, no dependencies. Runs at the dev/commit boundary (husky/CI).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { hashSource } from "./lib/canonical-source.mjs";
+
+function fail(message) {
+	console.error(`component-hash: ${message}`);
+	process.exit(2);
+}
+
+function hashFile(file) {
+	try {
+		return hashSource(fs.readFileSync(file, "utf8"));
+	} catch (error) {
+		fail(`cannot read ${file} (${error.code ?? error.message})`);
+		return ""; // unreachable; fail() exits
+	}
+}
+
+const argv = process.argv.slice(2);
+
+if (argv.length === 0) {
+	fail("usage: component-hash <file> | --verify <a> <b> | --check <manifest> [--update]");
+}
+
+if (argv[0] === "--verify") {
+	const [, a, b] = argv;
+	if (!a || !b) {
+		fail("--verify needs <sandbox-file> <plugin-file>");
+	}
+	const ha = hashFile(a);
+	const hb = hashFile(b);
+	if (ha === hb) {
+		console.log(`PARITY OK  ${path.basename(b)}  ${ha.slice(0, 12)}`);
+		process.exit(0);
+	}
+	console.error(`DRIFT  ${b}\n  sandbox ${ha.slice(0, 12)}  !=  plugin ${hb.slice(0, 12)}`);
+	console.error("  -> edit the sandbox component and re-port (don't hand-edit the copy).");
+	process.exit(1);
+}
+
+if (argv[0] === "--check") {
+	const manifestPath = argv[1];
+	const update = argv.includes("--update");
+	if (!manifestPath) {
+		fail("--check needs <manifest.json>");
+	}
+	const manifestDir = path.dirname(path.resolve(manifestPath));
+	const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+	const entries = manifest.entries ?? [];
+	const resolve = (p) => path.resolve(manifestDir, p);
+
+	const drifts = [];
+	for (const entry of entries) {
+		const pluginHash = hashFile(resolve(entry.plugin));
+		const hasSandbox = entry.sandbox && fs.existsSync(resolve(entry.sandbox));
+		const sourceHash = hasSandbox ? hashFile(resolve(entry.sandbox)) : undefined;
+		const expected = sourceHash ?? entry.hash;
+
+		if (update) {
+			entry.hash = sourceHash ?? pluginHash;
+			continue;
+		}
+		if (expected === undefined) {
+			drifts.push(`${entry.plugin}: no reference (add a sandbox path or a recorded hash)`);
+		} else if (pluginHash !== expected) {
+			const ref = hasSandbox ? "sandbox" : "recorded";
+			drifts.push(
+				`${entry.plugin}: DRIFT (plugin ${pluginHash.slice(0, 12)} != ${ref} ${expected.slice(0, 12)})`
+			);
+		}
+	}
+
+	if (update) {
+		fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, "\t")}\n`);
+		console.log(
+			`Re-recorded ${entries.length} baseline hash(es) in ${path.basename(manifestPath)}.`
+		);
+		process.exit(0);
+	}
+
+	if (drifts.length > 0) {
+		console.error(`Port parity: ${drifts.length} drift(s).`);
+		for (const d of drifts) {
+			console.error(`  ${d}`);
+		}
+		console.error("  -> edit the sandbox component and re-port, or --update to re-bless.");
+		process.exit(1);
+	}
+	console.log(`Port parity OK (${entries.length} component(s)).`);
+	process.exit(0);
+}
+
+// Default: print the hash of one file.
+console.log(hashFile(argv[0]));

package/template/scripts/install-skills.mjs

@@ -1,47 +1,109 @@
 #!/usr/bin/env node
 /**
- * Install the skills bundled in this repo (skills/*) into the developer's agent
- * via the `skills` CLI (https://github.com/vercel-labs/skills). This repo acts
- * as a local marketplace: `skills add .` discovers skills/<name>/SKILL.md and
- * lets the user pick which to install through the interactive TUI.
+ * Install / update the skills bundled in this repo (skills/*) via the `skills`
+ * CLI (https://github.com/vercel-labs/skills). This repo is a local skills
+ * marketplace: the source `.` resolves to skills/<name>/SKILL.md.
  *
- * Wired as `postinstall`, so it runs after `pnpm install`. To keep that safe it
- * only launches the interactive TUI when attached to a real terminal — in CI or
- * any non-interactive context it prints a hint and exits 0 instead of hanging.
- * Run it on demand with `pnpm skills:install` (which passes --force).
+ * Modes (auto-detected):
+ *   - Interactive terminal       → opens the picker TUI (choose what to install).
+ *   - Non-interactive / CI / -y  → installs ALL bundled skills, no prompts.
+ *   - --update                   → updates an already-installed setup in place.
  *
- *   SKIP_SKILLS_INSTALL=1   opt out entirely
- *   pnpm skills:install      force the interactive install
+ * Wiring:
+ *   - `postinstall` (auto on `pnpm install`): only acts in an interactive
+ *     terminal; in CI/non-TTY it prints how to install and exits 0 (never hangs).
+ *   - `pnpm skills:install`        → picker (TUI) on a terminal, else installs all.
+ *   - `pnpm skills:install --yes`  → always non-interactive: install all skills.
+ *   - `pnpm skills:update`         → update installed skills to the latest.
+ *
+ * Flags / env:
+ *   --update / -u           update installed skills (runs `skills update -y`)
+ *   --yes / -y              non-interactive install of all bundled skills
+ *   --agent <name> | --agent=<name>   install for one agent (e.g. claude-code)
+ *                          instead of all detected agents
+ *   SKILLS_AGENT=<name>     same as --agent, for the auto `postinstall` step
+ *                          (which can't take CLI args) and CI
+ *   --dry-run / SKILLS_DRY_RUN=1   print the command instead of running it
+ *   SKIP_SKILLS_INSTALL=1   opt out of the postinstall auto-step
  */
 import { spawnSync } from "node:child_process";
 import process from "node:process";
 
-const forced = process.argv.includes("--force");
+const BUNDLED =
+	"obsidian-arrow-sandbox, arrow-js-obsidian-templates, arrow-js-obsidian-patterns, arrow-js-obsidian-porting";
+
+const has = (flag) => process.argv.includes(flag);
+// Accepts both `--flag value` and `--flag=value`.
+const flagValue = (flag) => {
+	const eq = process.argv.find((a) => a.startsWith(`${flag}=`));
+	if (eq) {
+		return eq.slice(flag.length + 1);
+	}
+	const i = process.argv.indexOf(flag);
+	return i >= 0 ? process.argv[i + 1] : undefined;
+};
+
+const forced = has("--force"); // set by `pnpm skills:install`
+const update = has("--update") || has("-u");
+const yes = has("--yes") || has("-y");
+const agent = flagValue("--agent") || process.env.SKILLS_AGENT;
+const dryRun = has("--dry-run") || process.env.SKILLS_DRY_RUN === "1";
 const isCI = Boolean(process.env.CI);
 const interactive = Boolean(process.stdout.isTTY && process.stdin.isTTY);
 const optedOut = process.env.SKIP_SKILLS_INSTALL === "1";
 
-if (!forced && (isCI || optedOut || !interactive)) {
-	console.log(
-		"[skills] Skipping interactive skill install (non-interactive/CI/opt-out).\n         Run `pnpm skills:install` to install the bundled skills via the npx skills TUI."
-	);
-	process.exit(0);
+function run(args) {
+	const pretty = ["npx", "skills", ...args].join(" ");
+	if (dryRun) {
+		console.log(`[skills] (dry-run) would run: ${pretty}`);
+		process.exit(0);
+	}
+	console.log(`[skills] ${pretty}`);
+	const result = spawnSync("npx", ["--yes", "skills", ...args], {
+		stdio: "inherit",
+		shell: process.platform === "win32",
+	});
+	if (result.error) {
+		console.error(
+			`[skills] could not run npx skills (${result.error.message}). Install manually: npx skills add . --all --yes`
+		);
+		process.exit(0); // never fail an install over an optional convenience step
+	}
+	process.exit(result.status ?? 0);
 }
 
-console.log("[skills] Launching `npx skills add .` — pick the skills to install in the TUI…\n");
+if (optedOut && !update && !forced) {
+	console.log("[skills] SKIP_SKILLS_INSTALL=1 — skipping skill install.");
+	process.exit(0);
+}
 
-// `--yes` only auto-confirms npx fetching the `skills` package; the skills CLI's
-// own selection TUI still shows (we deliberately do not pass skills' `-y`).
-const result = spawnSync("npx", ["--yes", "skills", "add", "."], {
-	stdio: "inherit",
-	shell: process.platform === "win32",
-});
+// Update an existing setup to the latest (works in any context).
+if (update) {
+	console.log("[skills] Updating installed skills to the latest…");
+	run(["update", "-y"]);
+}
 
-if (result.error) {
-	console.error(
-		`[skills] Could not run npx skills (${result.error.message}).\n         Install manually: npx skills add .`
+// Conservative postinstall: only auto-run when a human is at the terminal so
+// `pnpm install` in CI never hangs or installs things unprompted.
+if (!forced && (isCI || !interactive)) {
+	console.log(
+		`[skills] Bundled skills: ${BUNDLED}\n         Install:  pnpm skills:install        (interactive picker on a terminal)\n                   pnpm skills:install --yes  (non-interactive — installs all)\n         Update:   pnpm skills:update`
 	);
-	process.exit(0); // never fail an install over an optional convenience step
+	process.exit(0);
+}
+
+// Non-interactive (CI/agent/no TTY, or --yes, or an agent target): install ALL
+// bundled skills with no prompts. Target one agent if asked, else all agents.
+if (!interactive || yes || agent) {
+	console.log(`[skills] Installing all bundled skills non-interactively: ${BUNDLED}`);
+	if (agent) {
+		// `--all` is shorthand for `-s * -a * -y`, so to target one agent we
+		// spell out all-skills + that agent explicitly.
+		run(["add", ".", "-s", "*", "-a", agent, "-y"]);
+	}
+	run(["add", ".", "--all"]);
 }
 
-process.exit(result.status ?? 0);
+// Interactive terminal: let the user pick in the TUI.
+console.log(`[skills] Opening the skills picker. Bundled: ${BUNDLED}`);
+run(["add", "."]);

package/template/scripts/lib/canonical-source.mjs

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Canonical source hashing for sandbox -> plugin porting parity.
+ *
+ * The sandbox is the source of truth for a component; the plugin gets a
+ * near-verbatim copy. This hashes the component's *portable body* so the only
+ * thing that can change the hash is meaningful drift in the component — not the
+ * bits that legitimately differ on the way into a plugin.
+ *
+ * Canonical form (define it so both sides agree by construction):
+ *   1. Drop `import …;` statements (single- or multi-line). Imports are the main
+ *      legit delta: the sandbox imports stub data / no obsidian; the plugin
+ *      imports the obsidian API / real data wiring. The component body is what
+ *      must match.
+ *   2. Normalize line endings to \n, strip trailing whitespace per line, collapse
+ *      runs of blank lines to one, trim leading/trailing blank lines.
+ *   3. SHA-256 the result.
+ *
+ * Note: comments are intentionally kept (they're part of the component; the
+ * sandbox is the source of truth for them too). To keep parity clean, write
+ * portable components that take data via props/getters so the body is identical
+ * across sandbox and plugin and only the mount site differs.
+ */
+
+// Matches a whole `import …;` statement. `[^;]*` crosses newlines (the negated
+// class matches \n) so multi-line imports are captured up to the first semicolon.
+const IMPORT_STATEMENT = /^[ \t]*import\b[^;]*;[ \t]*$/gm;
+
+export function canonicalizeSource(text) {
+	const withoutImports = text.replace(IMPORT_STATEMENT, "");
+	const lines = withoutImports
+		.replace(/\r\n/g, "\n")
+		.split("\n")
+		.map((line) => line.replace(/[ \t]+$/, ""));
+
+	// Collapse runs of blank lines to a single blank line.
+	const collapsed = [];
+	let lastBlank = false;
+	for (const line of lines) {
+		const blank = line === "";
+		if (blank && lastBlank) {
+			continue;
+		}
+		collapsed.push(line);
+		lastBlank = blank;
+	}
+
+	// Trim leading/trailing blank lines.
+	while (collapsed.length > 0 && collapsed[0] === "") {
+		collapsed.shift();
+	}
+	while (collapsed.length > 0 && collapsed[collapsed.length - 1] === "") {
+		collapsed.pop();
+	}
+
+	return `${collapsed.join("\n")}\n`;
+}
+
+/** SHA-256 hex of the canonical source. */
+export function hashSource(text) {
+	return createHash("sha256").update(canonicalizeSource(text), "utf8").digest("hex");
+}

package/template/skills/arrow-js-obsidian-porting/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: arrow-js-obsidian-porting
+description: Use when porting an Arrow component from the obsidian-arrow-sandbox into the real Obsidian plugin, or wiring a check that the plugin copy hasn't drifted from the sandbox source. Covers the content-addressed porting-parity tool (scripts/component-hash.mjs), the canonical-form rules, a port-parity manifest, and a husky/CI pre-commit hook. The sandbox is the source of truth; the plugin copy must match.
+---
+
+# Porting parity (sandbox → Obsidian plugin)
+
+The sandbox is the **source of truth** for a component; the plugin gets a
+near-verbatim copy. The risk is **drift** — someone hand-edits the plugin copy,
+or a port silently diverges. This makes components **content-addressed**: a
+canonical hash of the component's portable body must match on both sides, the
+same idea as "never hand-edit generated artifacts."
+
+## Write portable components
+
+So the body is byte-identical across sandbox and plugin and only the *mount site*
+differs:
+
+- Take data via **props / getters**, not hard-wired sources. The sandbox passes a
+  stub (`loadStatus()`); the plugin passes the real source (rpc) — but that wiring
+  lives at the **call site** (`main.ts` / `ItemView.onOpen()`), not in the
+  component body.
+- Use Obsidian classes + `var(--…)` tokens (already the rule). Keep
+  `obsidian`-API calls (`setIcon`, …) out of the component body where possible.
+
+## The tool: `scripts/component-hash.mjs`
+
+Dependency-free Node; canonicalizer in `scripts/lib/canonical-source.mjs`.
+
+```sh
+node scripts/component-hash.mjs <file>                       # print canonical hash
+node scripts/component-hash.mjs --verify <sandbox> <plugin>  # PARITY OK | DRIFT (exit 0/1)
+node scripts/component-hash.mjs --check port-parity.json     # check all; exit 1 on drift
+node scripts/component-hash.mjs --check port-parity.json --update   # re-bless baselines
+```
+
+**Canonical form** (define it so both sides agree by construction):
+- `import …;` statements are stripped (single- and multi-line) — imports are the
+  main legit delta (stub vs real data, the `obsidian` API).
+- Line endings → `\n`, trailing whitespace trimmed, blank-line runs collapsed,
+  leading/trailing blanks trimmed.
+- Comments are **kept** (they're part of the component; the sandbox owns them too).
+- SHA-256 of the result.
+
+So two copies that differ only in imports/formatting hash equal; any change to
+the body/template/comments shows as drift.
+
+## Wiring the check in the plugin
+
+The hook lives in the **plugin** repo (that's where ported copies drift). Copy the
+two dependency-free files in (`scripts/lib/canonical-source.mjs`,
+`scripts/component-hash.mjs`) and add a manifest:
+
+```jsonc
+// port-parity.json — paths resolve relative to THIS file
+{
+  "entries": [
+    {
+      "plugin": "src/chat/arrow/SettingsPanel.ts",
+      "sandbox": "../../arrow-ui/obsidian-arrow-sandbox/src/components/SettingsPanel.ts", // optional
+      "hash": "<sha256>"                                                                  // fallback when sandbox isn't checked out
+    }
+  ]
+}
+```
+
+- If the `sandbox` path exists (sibling checkout), the check compares **plugin
+  copy ↔ live sandbox source** — catches drift in both directions.
+- If it doesn't, it falls back to the recorded `hash` (catches hand-edits to the
+  plugin copy). Record/refresh it with `--update` after an intentional re-port.
+
+husky `pre-commit` (and CI):
+
+```sh
+node scripts/component-hash.mjs --check port-parity.json
+```
+
+On drift the commit fails: *edit the sandbox component and re-port* (don't
+hand-edit the copy); use `--update` only to intentionally re-bless.
+
+## What this does NOT do (by design)
+
+- **No runtime component-DOM hashing in Obsidian.** Source parity already
+  guarantees same code → same Arrow DOM, and the sandbox vs real Obsidian DOM
+  *intentionally* differ (icon stub vs `setIcon`, `MarkdownRenderer` nodes, live
+  theme), so a runtime markup hash would be tautological *and* full of false
+  mismatches. The real runtime risk is visual/CSS — verify that by **loading in
+  Obsidian and looking**, not with a hash.
+- **Planned (not built): a styling-freshness check.** A small helper that hashes
+  the *live Obsidian token set* and compares it to the sandbox's pulled `app.css`
+  snapshot, to flag "re-run `pnpm pull-css`." That's the one runtime hash worth
+  having — environment parity, not component parity. Add it when needed.

package/template/skills/arrow-js-obsidian-templates/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: arrow-js-obsidian-templates
-description: Use when writing @arrow-js/core (v1.0.6) html`` templates — the reactive-vs-static rule, full-value attribute binding (returning false removes the attribute), .property and @event binding, keyed lists, async component(fn, { fallback }) wrapped in boundary(), and the footguns: no literal HTML comments inside templates and no partial attribute values (both throw "Invalid HTML position" at render), plus @event handlers must type the param as Event not a narrowed subtype like MouseEvent (TS2345).
+description: Use when writing @arrow-js/core (v1.0.6) html template literals — reactive vs static (wrap reactive reads in arrow functions), full-value attribute binding where returning false removes the attribute, .property and @event binding, keyed lists, and async component(fn, { fallback }) via boundary(); plus the footguns — no literal HTML comments and no partial attribute values (both throw Invalid HTML position at render), and @event handlers must type the param as Event not a narrowed subtype like MouseEvent (TS2345).
 ---
 
 # Arrow.js Templates (v1.0.6)

package/template/test/component-hash.test.mjs

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { canonicalizeSource, hashSource } from "../scripts/lib/canonical-source.mjs";
+
+/**
+ * Porting-parity canonicalization. The hash must ignore the bits that
+ * legitimately differ when a component is ported sandbox -> plugin (imports,
+ * whitespace) and flag everything else (the component body/template).
+ */
+
+const SANDBOX = `import { component, html } from "@arrow-js/core";
+import { loadStatus } from "../data/loadStatus";
+
+export const Card = component(() => html\`<div class="setting-item">\${() => loadStatus()}</div>\`);
+`;
+
+// Same body, plugin-flavored imports (obsidian + real data wiring).
+const PLUGIN = `import { component, html } from "@arrow-js/core";
+import { loadStatus } from "./rpc";
+import { setIcon } from "obsidian";
+
+export const Card = component(() => html\`<div class="setting-item">\${() => loadStatus()}</div>\`);
+`;
+
+test("imports are stripped — same body hashes equal across sandbox and plugin", () => {
+	assert.equal(hashSource(SANDBOX), hashSource(PLUGIN));
+});
+
+test("a body change is detected as drift", () => {
+	const drifted = PLUGIN.replace("setting-item", "setting-item is-hacked");
+	assert.notEqual(hashSource(SANDBOX), hashSource(drifted));
+});
+
+test("whitespace and blank-line differences are normalized away", () => {
+	const messy = `${SANDBOX.replace(/\n/g, "\n\n")}   \n`;
+	assert.equal(hashSource(SANDBOX), hashSource(messy));
+});
+
+test("multi-line imports are stripped", () => {
+	const multiline = `import {\n\tcomponent,\n\thtml,\n} from "@arrow-js/core";\n\nexport const X = 1;\n`;
+	const singleline = `import { component, html } from "@arrow-js/core";\n\nexport const X = 1;\n`;
+	assert.equal(hashSource(multiline), hashSource(singleline));
+	assert.match(canonicalizeSource(multiline), /^export const X = 1;\n$/);
+});
+
+test("hash is stable sha256 hex", () => {
+	assert.match(hashSource(SANDBOX), /^[0-9a-f]{64}$/);
+});

package/template/test/skills-frontmatter.test.mjs

@@ -0,0 +1,57 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The `skills` CLI parses each SKILL.md's YAML frontmatter; if it can't, the
+ * skill is silently skipped (not installed). An unquoted plain-scalar
+ * `description:` that contains `: ` (read as a nested key) or an unescaped
+ * double-quote breaks the parse — that's a real footgun (it skipped
+ * arrow-js-obsidian-templates until caught). These guards keep descriptions
+ * installable.
+ */
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const skillsDir = path.join(root, "skills");
+
+function skillFiles() {
+	if (!fs.existsSync(skillsDir)) {
+		return [];
+	}
+	return fs
+		.readdirSync(skillsDir, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory())
+		.map((entry) => path.join(skillsDir, entry.name, "SKILL.md"))
+		.filter((file) => fs.existsSync(file));
+}
+
+function frontmatter(text) {
+	const match = text.match(/^---\n([\s\S]*?)\n---/);
+	return match ? match[1] : "";
+}
+
+test("every skill has name + description frontmatter", () => {
+	for (const file of skillFiles()) {
+		const fm = frontmatter(fs.readFileSync(file, "utf8"));
+		assert.match(fm, /^name:\s+\S/m, `${path.relative(root, file)}: missing name`);
+		assert.match(fm, /^description:\s+\S/m, `${path.relative(root, file)}: missing description`);
+	}
+});
+
+test("skill descriptions are YAML-safe so the skills CLI installs them", () => {
+	const offenders = [];
+	for (const file of skillFiles()) {
+		const fm = frontmatter(fs.readFileSync(file, "utf8"));
+		const desc = (fm.match(/^description:\s+(.*)$/m) ?? [])[1] ?? "";
+		const quoted = /^["']/.test(desc);
+		if (!quoted && (/: /.test(desc) || desc.includes('"'))) {
+			offenders.push(path.relative(root, file));
+		}
+	}
+	assert.deepEqual(
+		offenders,
+		[],
+		"unquoted description must not contain ': ' or a double-quote (breaks YAML; the skills CLI skips it)"
+	);
+});

package/template/docs/superpowers/specs/2026-06-29-obsidian-arrow-sandbox-design.md

@@ -1,206 +0,0 @@
-# Obsidian-Arrow Sandbox — Design
-
-**Date:** 2026-06-29
-**Location:** `/Users/kylebrodeur/workspace/arrow-ui/obsidian-arrow-sandbox`
-**Status:** Draft for review
-
-## Purpose
-
-A minimal, Obsidian-styled prototyping environment for building plugin UI with
-[Arrow.js](https://arrow-js.com/), so we can iterate on UI/UX fast in the
-browser without building/loading into Obsidian on every change. Components are
-written so they copy-paste into an Obsidian `ItemView`/`Modal`/settings tab with
-near-zero refactoring, and a separate agent later reconciles them into the real
-plugin (`pi-vault-mind/packages/obsidian`).
-
-Success = `pnpm dev` opens a browser page that looks like a real Obsidian pane,
-rendering **one** working, reactive, Obsidian-styled Arrow component, where the
-component source is plugin-ready as-is.
-
-## Scope
-
-**In scope (baseline):**
-- Client-only Vite + TypeScript dev environment (`pnpm dev`).
-- `@arrow-js/core` **+ `@arrow-js/framework`** (client-side only). Core supplies
-  `reactive`, `html`, `component`, `watch`, `nextTick`; framework supplies
-  `boundary()` for async fallback sections. Mounted via `template(container)` —
-  the same call an Obsidian `ItemView.onOpen()` makes. **No `ssr`/`hydrate`.**
-- A deliberate **templates showcase** exercising Arrow's template features:
-  reactive `${() => …}` vs static `${…}`, attribute sync with `false`-removal
-  (`disabled="${() => …}"`), `.property` binding (`.checked`), `@event`
-  (`@click`), and keyed lists (`.key(id)`).
-- An async section wrapped in `boundary()` (fallback → resolved) so the baseline
-  itself **is** the framework evaluation — we can judge `boundary()` ergonomics
-  against plain reactive flags on real code.
-- `index.html` wrapped in Obsidian's body classes, loading the extracted
-  `app.css` for full fidelity (tokens **and** semantic component classes).
-- A puller script that extracts `app.css` from the local Obsidian install.
-- One baseline component: a settings panel (vertical tabs + `.setting-item` +
-  `.checkbox-container` toggle + token-colored status line) proving the pipeline.
-- A light/dark theme toggle for eyeballing both themes.
-
-**Out of scope (deferred, additive later):**
-- `@arrow-js/ssr` + `@arrow-js/hydrate` — **cut, not deferred.** See the Arrow
-  Layering decision record below for the reasoning.
-- Porting the full chat composer (`input.ts`, `message-feed`, `model-select`,
-  …). The composer is the *next* component after the baseline proves out.
-- An `obsidian` API shim (`setIcon`, `Notice`, …). Not needed until we port a
-  component that calls Obsidian APIs; the baseline uses none.
-- CDP-based token capture (see "Token sourcing", option B).
-
-## Decision record — Arrow layering
-
-Evidence from the installed `@arrow-js` packages (v1.0.6) + how an Obsidian
-plugin runs (Electron renderer, client-only; view DOM built imperatively in
-`ItemView.onOpen()`, no server, no server-rendered HTML to adopt):
-
-| Package | Key exports | Server needed? | Verdict |
-|---|---|---|---|
-| `core` (13.5KB min, 0 deps) | `reactive`, `html`, `component`, `watch`, `nextTick` | no | **Use** |
-| `framework` (client entry, 1.4KB, no jsdom) | `boundary()`, `render`, `toTemplate` | no | **Use** (client only) |
-| `framework/ssr` | server render runtime | yes (pulls **jsdom**, Node-only) | unused |
-| `ssr` | `renderToString`, `serializePayload` | yes | **Cut** |
-| `hydrate` (12.7KB) | `hydrate`, `readPayload` | yes (needs SSR output) | **Cut** |
-
-- **Cut `ssr` + `hydrate`:** they are a server→client pair. `renderToString`
-  needs a server to run on; `hydrate` needs server HTML + payload to adopt.
-  Obsidian has neither — `onOpen()` already builds the DOM client-side, so
-  `hydrate` would only add indirection over `template(container)`. The SSR path
-  also depends on `jsdom` (Node) and cannot sanely run in the renderer bundle.
-- **Use `framework` client-side:** its only client-relevant feature is
-  `boundary()` (async fallback). Client entry is tiny and does **not** import
-  jsdom, so it bundles cleanly into a plugin. Adopting it now makes the baseline
-  double as the "should the plugin upgrade?" evaluation, scoped to `boundary()`.
-- **Note:** `component()` lives in core, so reusable components don't require
-  framework. Porting a framework-using component to the plugin requires adding
-  `@arrow-js/framework` as a plugin dependency + the side-effect runtime import.
-
-## CSS scoping convention
-
-1. Components use **Obsidian's own semantic classes** (`.setting-item`,
-   `.clickable-icon`, `.workspace-leaf`, `.vertical-tab-nav-item`) and `var(--…)`
-   tokens first; add custom CSS only where Obsidian offers no class.
-2. Any custom CSS is **scoped under a container class + element type** (e.g.
-   `.oas-frame button.oas-theme-toggle`, specificity ≥ (0,2,1)) so it beats
-   Obsidian's global `button:not(.clickable-icon)` rule and never leaks — per the
-   `arrow-js-obsidian` skill's specificity lesson. Sandbox-only chrome lives in a
-   scoped `src/sandbox/sandbox.css`; component styling stays on Obsidian classes.
-
-## Architecture
-
-Plain client-side single-page sandbox. No server, no SSR. Vite serves
-`index.html`, which loads `public/app.css` (extracted locally via `pull-css`,
-git-ignored) and a TS entry that mounts an Arrow component into `#app`.
-
-```
-obsidian-arrow-sandbox/
-├── index.html                 # Obsidian body-class wrapper + app.css link + #app
-├── public/
-│   └── app.css                # extracted from Obsidian via pull-css (git-ignored, not redistributed)
-├── src/
-│   ├── main.ts                # mounts the baseline component into #app
-│   ├── sandbox/
-│   │   ├── frame.ts           # workspace-leaf frame + theme toggle chrome
-│   │   ├── theme.ts           # flip body theme-dark/theme-light
-│   │   └── sandbox.css        # scoped sandbox-only chrome styles
-│   ├── data/
-│   │   └── loadStatus.ts      # async data for the boundary() demo
-│   └── components/
-│       └── SettingsPanel.ts   # the baseline Arrow component (+ boundary section)
-├── scripts/
-│   └── pull-app-css.mjs       # extract app.css from local Obsidian install
-├── docs/superpowers/specs/    # this spec
-├── package.json
-├── tsconfig.json
-└── vite.config.ts
-```
-
-### `index.html`
-
-```html
-<body class="theme-dark mod-macos is-frameless is-hidden-frameless obsidian-app
-             show-view-header show-inline-title">
-  <div id="app"></div>
-  <script type="module" src="/src/main.ts"></script>
-</body>
-```
-
-The body classes activate Obsidian's variable scope; without them `var(--…)`
-lookups in `app.css` don't resolve. `app.css` is loaded via `<link>` in `<head>`.
-
-### Component model
-
-```ts
-import '@arrow-js/framework'                    // side-effect: install framework runtime
-import { html, reactive, component } from '@arrow-js/core'
-import { boundary } from '@arrow-js/framework'  // async fallback boundary
-
-const state = reactive({ activeTab: 'general', developerMode: true })
-export const SettingsPanel = component(() => html`…`)   // returns an Arrow template
-
-// main.ts
-import { SettingsPanel } from './components/SettingsPanel'
-SettingsPanel()(document.getElementById('app')!)   // == ItemView.onOpen mount
-```
-
-Reactive expressions use the `() => …` form per Arrow rules
-(`${() => state.activeTab === 'general' ? 'is-active' : ''}`), events via
-`@click`, properties via `.checked`, matching the production
-`arrow-js-obsidian` skill conventions.
-
-## Token sourcing — extract `app.css`
-
-The sandbox loads the **full** authored `app.css` (not a slimmed token file) so
-both `var(--…)` tokens and semantic component rules render faithfully.
-
-**Option A — asar extraction (default, validated):**
-On macOS `app.css` is bundled inside
-`/Applications/Obsidian.app/Contents/Resources/obsidian.asar`. `pull-app-css.mjs`
-parses the asar header (a Chromium Pickle: JSON length at byte 12, JSON header at
-byte 16, file data section after the 4-byte-aligned header pickle), locates
-`/app.css`, slices its bytes, and writes `public/app.css`. Pure Node, no deps, no
-running Obsidian.
-
-*Validated 2026-06-29:* extracted `app.css` = 586KB, ~1948 var declarations,
-contains `body.theme-dark`, `.theme-light`, `--text-accent`, `--size-4-4`,
-`--interactive-accent`, `--radius-m`. (Implementation note: handle 4-byte
-alignment of the data offset so the slice isn't a few bytes off.)
-
-CLI: `pnpm pull-css` (with `--path <asar>` override and an env-var fallback for
-non-default install locations). Output is **git-ignored** — Obsidian's CSS is
-proprietary, so each developer extracts it from their own licensed install rather
-than us redistributing it. Run `pull-css` once before `pnpm dev`.
-
-**Option B — CDP capture (deferred, optional `--source cdp`):**
-Launch/attach to a running Obsidian via Chrome DevTools Protocol
-(`--remote-debugging-port`), `Runtime.evaluate` in the renderer to dump the live
-stylesheet text or `getComputedStyle` variable set. Captures the user's *active*
-community theme / snippets / resolved values rather than stock defaults. Useful
-later for testing against a real themed environment; not part of the baseline.
-
-## Dev workflow
-
-- `pnpm pull-css` — refresh `public/app.css` from the local Obsidian install.
-- `pnpm dev` — Vite dev server with HMR; open the printed URL.
-- Edit `src/components/*.ts`; HMR re-renders instantly.
-- `pnpm typecheck` — `tsc --noEmit`.
-
-## Porting / reconcile story
-
-Components are framework-free `@arrow-js/core` + Obsidian CSS classes, so moving
-one into the plugin is: copy the file into `src/chat/arrow/` (or appropriate
-view dir) and mount it from `ItemView.onOpen()` via `template(this.contentEl)`.
-Strip any U-of-D references per project notes. No build-system translation needed
-(plugin bundles `@arrow-js/core` via esbuild; sandbox imports the same package).
-
-## Risks / open notes
-
-- `app.css` is ~586KB; fine for a local sandbox loaded once. Not slimming it
-  keeps full component-class fidelity.
-- asar data-offset alignment must be correct (off-by-a-few-bytes corrupts the
-  slice). Validated approach; nail alignment in implementation.
-- Exact set of Obsidian body classes may need tweaking to match a real pane;
-  start from a known-good set and adjust visually.
-- Community-theme fidelity is not captured by asar extraction — that's what the
-  optional CDP mode is for, later.
-```