create-obsidian-arrow 0.1.0 → 0.1.8

package/README.md

@@ -24,10 +24,44 @@ pnpm dev
 > `public/app.css` is git-ignored and never bundled — it's Obsidian's proprietary
 > CSS, so each developer extracts it from their own install via `pnpm pull-css`.
 
-Local dev of the initializer itself (from the sandbox repo, before publishing):
+### Install the bundled skills
+
+The scaffold ships agent skills and installs them via the [`skills`](https://github.com/vercel-labs/skills)
+CLI:
+
+```sh
+pnpm skills:install --yes                       # non-interactive — installs all
+pnpm skills:install                             # interactive picker
+pnpm skills:install --yes --project-dir=<root>  # install at another repo root (nesting)
+pnpm skills:update                              # update an existing setup
+```
+
+If you scaffold **inside an existing repo**, skills install scoped to the
+scaffold folder (the CLI is cwd-relative); use `--project-dir=<outer-repo>` (or
+`--global`) to install where an agent at the outer repo looks. The scaffolder
+prints this hint when it detects nesting.
+
+## Update an existing project
+
+The scaffolder is create-only, but `update` refreshes an existing project's
+**managed** tooling (`scripts/`, `skills/`, `docs/`, `.github/`, `.husky/`,
+`biome.json`, agent guides) and merges new `package.json` scripts/deps — it never
+touches your `src/`, `public/`, `index.html`, or build configs:
+
+```sh
+npx create-obsidian-arrow update            # in the project (or: update <dir>)
+npx create-obsidian-arrow update --dry-run  # preview
+```
+
+Then `pnpm install && pnpm check`.
+
+## Local dev of the initializer
+
+From the sandbox repo, before publishing:
 
 ```sh
-node create-obsidian-arrow/index.mjs ../my-app
+node create-obsidian-arrow/index.mjs ../my-app          # scaffold
+node create-obsidian-arrow/index.mjs update ../my-app   # update
 ```
 
 ## What you get

package/index.mjs

@@ -1,13 +1,21 @@
 #!/usr/bin/env node
 /**
- * create-obsidian-arrow — scaffold a new Obsidian-styled Arrow.js UI sandbox.
+ * create-obsidian-arrow — scaffold or update an Obsidian-styled Arrow.js sandbox.
  *
- *   pnpm create obsidian-arrow my-app      # once published
- *   node create-obsidian-arrow/index.mjs my-app   # locally, before publishing
+ *   create-obsidian-arrow <dir>            scaffold a new project into <dir>
+ *   create-obsidian-arrow update [dir]     refresh an existing project's tooling
+ *                                          (default dir: cwd) — preserves your code
  *
- * Copies the vendored template/ into <dir>, restores .gitignore (npm strips it
- * from packages, so it's vendored as _gitignore), rewrites the project name,
- * and runs `git init`. The template is a full, verified sandbox — see template/.
+ *   pnpm create obsidian-arrow my-app
+ *   node create-obsidian-arrow/index.mjs my-app          # locally
+ *   node create-obsidian-arrow/index.mjs update ./my-app
+ *
+ * Scaffold copies the vendored template/, restores .gitignore (vendored as
+ * _gitignore), names the project, and runs `git init`.
+ *
+ * Update refreshes only the *managed* tooling files from the template and merges
+ * package.json scripts + missing deps — it never touches your src/, public/,
+ * index.html, or the core build configs. Use --dry-run to preview.
  */
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
@@ -17,60 +25,172 @@ import { fileURLToPath } from "node:url";
 const here = path.dirname(fileURLToPath(import.meta.url));
 const templateDir = path.join(here, "template");
 
+// Files/dirs the template owns and `update` may overwrite/merge. Everything else
+// (src/, public/, index.html, vite.config.ts, tsconfig.json, lockfile, .gitignore,
+// port-parity.json, …) is treated as user-owned and left alone.
+const MANAGED = [
+	"scripts",
+	"skills",
+	"docs",
+	".github",
+	".husky",
+	"biome.json",
+	"AGENTS.md",
+	"CLAUDE.md",
+];
+
+const argv = process.argv.slice(2);
+const dryRun = argv.includes("--dry-run");
+
 function fail(message) {
 	console.error(`create-obsidian-arrow: ${message}`);
 	process.exit(1);
 }
 
-const targetArg = process.argv[2];
-if (!targetArg) {
-	fail("usage: create-obsidian-arrow <directory>");
+if (!fs.existsSync(templateDir)) {
+	fail("template/ is missing — run scripts/sync-template.mjs to build it.");
 }
 
-const destRoot = path.resolve(process.cwd(), targetArg);
-const appName = path.basename(destRoot);
+/** Nearest ancestor *above* `dir` that is a git repo, or null. */
+function outerRepoAbove(dir) {
+	let current = path.dirname(path.resolve(dir));
+	const fsRoot = path.parse(current).root;
+	while (current && current !== fsRoot) {
+		if (fs.existsSync(path.join(current, ".git"))) {
+			return current;
+		}
+		current = path.dirname(current);
+	}
+	return null;
+}
 
-if (fs.existsSync(destRoot) && fs.readdirSync(destRoot).length > 0) {
-	fail(`target "${targetArg}" already exists and is not empty.`);
+/** Recursively copy src→dest; returns the list of written file paths (relative
+ * to `base`). Honors --dry-run (records but doesn't write). */
+function copyTree(src, dest, base, written) {
+	const stat = fs.statSync(src);
+	if (stat.isDirectory()) {
+		if (!dryRun) {
+			fs.mkdirSync(dest, { recursive: true });
+		}
+		for (const entry of fs.readdirSync(src)) {
+			copyTree(path.join(src, entry), path.join(dest, entry), base, written);
+		}
+		return;
+	}
+	written.push(path.relative(base, dest));
+	if (!dryRun) {
+		fs.mkdirSync(path.dirname(dest), { recursive: true });
+		fs.copyFileSync(src, dest);
+	}
 }
-if (!fs.existsSync(templateDir)) {
-	fail("template/ is missing — run scripts/sync-template.mjs to build it.");
+
+function scaffold(targetArg) {
+	const destRoot = path.resolve(process.cwd(), targetArg);
+	const appName = path.basename(destRoot);
+
+	if (fs.existsSync(destRoot) && fs.readdirSync(destRoot).length > 0) {
+		fail(`target "${targetArg}" already exists and is not empty (use \`update\` to refresh it).`);
+	}
+
+	const written = [];
+	copyTree(templateDir, destRoot, destRoot, written);
+	// Restore .gitignore (npm omits .gitignore from packages; vendored as _gitignore).
+	const vendoredIgnore = path.join(destRoot, "_gitignore");
+	if (fs.existsSync(vendoredIgnore)) {
+		fs.renameSync(vendoredIgnore, path.join(destRoot, ".gitignore"));
+	}
+
+	// Personalize the project name via targeted replace (keeps Biome formatting).
+	const pkgPath = path.join(destRoot, "package.json");
+	const renamed = fs
+		.readFileSync(pkgPath, "utf8")
+		.replace(/("name":\s*)"[^"]*"/, (_m, prefix) => `${prefix}${JSON.stringify(appName)}`);
+	fs.writeFileSync(pkgPath, renamed);
+
+	spawnSync("git", ["init", "-q"], { cwd: destRoot, stdio: "ignore" });
+
+	console.log(`\nScaffolded ${appName} in ${path.relative(process.cwd(), destRoot) || "."}\n`);
+	console.log("Next steps:");
+	console.log(`  cd ${targetArg}`);
+	console.log("  pnpm install");
+	console.log("  pnpm pull-css     # extract Obsidian's app.css (macOS auto-detect)");
+	console.log("  pnpm dev\n");
+
+	const outer = outerRepoAbove(destRoot);
+	if (outer) {
+		console.log(`Note: this project is nested inside the repo at ${outer}.`);
+		console.log("  Bundled skills install scoped to THIS project. To install them at the");
+		console.log(`  outer repo instead:  pnpm skills:install --yes --project-dir=${outer}\n`);
+	}
+}
+
+/** Merge template package.json scripts + missing deps into the target's,
+ * preserving name/version/identity and existing dep versions. */
+function mergePackageJson(targetPkgPath) {
+	const tpl = JSON.parse(fs.readFileSync(path.join(templateDir, "package.json"), "utf8"));
+	const pkg = JSON.parse(fs.readFileSync(targetPkgPath, "utf8"));
+	const changes = [];
+
+	pkg.scripts ??= {};
+	for (const [name, cmd] of Object.entries(tpl.scripts ?? {})) {
+		if (pkg.scripts[name] !== cmd) {
+			changes.push(`script ${name}`);
+			pkg.scripts[name] = cmd;
+		}
+	}
+	for (const field of ["dependencies", "devDependencies"]) {
+		pkg[field] ??= {};
+		for (const [name, version] of Object.entries(tpl[field] ?? {})) {
+			if (!(name in pkg[field])) {
+				changes.push(`${field}: ${name}`);
+				pkg[field][name] = version;
+			}
+		}
+	}
+
+	if (changes.length > 0 && !dryRun) {
+		fs.writeFileSync(targetPkgPath, `${JSON.stringify(pkg, null, "\t")}\n`);
+	}
+	return changes;
 }
 
-function copyDir(src, dest) {
-	fs.mkdirSync(dest, { recursive: true });
-	for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-		const srcPath = path.join(src, entry.name);
-		// Vendored as _gitignore because npm omits .gitignore from published tarballs.
-		const destName = entry.name === "_gitignore" ? ".gitignore" : entry.name;
-		const destPath = path.join(dest, destName);
-		if (entry.isDirectory()) {
-			copyDir(srcPath, destPath);
-		} else {
-			fs.copyFileSync(srcPath, destPath);
+function update(targetArg) {
+	const root = path.resolve(process.cwd(), targetArg ?? ".");
+	if (!fs.existsSync(path.join(root, "package.json"))) {
+		fail(`no package.json in ${root} — is this a scaffolded project?`);
+	}
+
+	const written = [];
+	for (const name of MANAGED) {
+		const src = path.join(templateDir, name);
+		if (fs.existsSync(src)) {
+			copyTree(src, path.join(root, name), root, written);
 		}
 	}
+	const pkgChanges = mergePackageJson(path.join(root, "package.json"));
+
+	const verb = dryRun ? "Would refresh" : "Refreshed";
+	console.log(
+		`${verb} ${written.length} managed file(s) in ${path.relative(process.cwd(), root) || "."}:`
+	);
+	for (const file of written) {
+		console.log(`  ${file}`);
+	}
+	if (pkgChanges.length > 0) {
+		console.log(`package.json: ${dryRun ? "would update" : "updated"} ${pkgChanges.join(", ")}`);
+	}
+	console.log(
+		dryRun
+			? "\n(dry run — nothing written.)"
+			: "\nLeft alone: src/, public/, index.html, vite.config.ts, tsconfig.json, .gitignore.\nRun `pnpm install` then `pnpm check`.\n"
+	);
 }
 
-copyDir(templateDir, destRoot);
-
-// Personalize the project name. Use a targeted replace (not JSON.parse +
-// stringify) so the template's existing Biome formatting stays byte-identical
-// and the fresh project passes `pnpm lint` out of the box.
-const pkgPath = path.join(destRoot, "package.json");
-const pkgText = fs.readFileSync(pkgPath, "utf8");
-const renamed = pkgText.replace(
-	/("name":\s*)"[^"]*"/,
-	(_match, prefix) => `${prefix}${JSON.stringify(appName)}`
-);
-fs.writeFileSync(pkgPath, renamed);
-
-// Initialize a git repo (best-effort; ignore if git is unavailable).
-spawnSync("git", ["init", "-q"], { cwd: destRoot, stdio: "ignore" });
-
-console.log(`\nScaffolded ${appName} in ${path.relative(process.cwd(), destRoot) || "."}\n`);
-console.log("Next steps:");
-console.log(`  cd ${targetArg}`);
-console.log("  pnpm install");
-console.log("  pnpm pull-css     # extract Obsidian's app.css (macOS auto-detect)");
-console.log("  pnpm dev\n");
+const command = argv[0];
+if (command === "update") {
+	update(argv.find((a) => a !== "update" && !a.startsWith("--")));
+} else if (!command || command.startsWith("--")) {
+	fail("usage: create-obsidian-arrow <directory> | update [directory]");
+} else {
+	scaffold(command);
+}

package/package.json

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

package/template/AGENTS.md

@@ -4,8 +4,20 @@ 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), obsidian-arrow-maintenance
+  (updating an existing project).
+- [`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)
 
@@ -29,6 +41,14 @@ pnpm dev          # Vite + HMR
 `public/app.css` is **git-ignored** (Obsidian's proprietary CSS — not
 redistributed); run `pnpm pull-css` once before `pnpm dev`.
 
+Install the bundled skills: `pnpm skills:install --yes` (non-interactive, all
+skills) or `pnpm skills:install` (TUI); update with `pnpm skills:update`. Scope
+flags: `--agent <name>`, `--project-dir=<path>`, `--global`. **Nested inside
+another repo?** Skills install cwd-relative — use `--project-dir=<outer-repo>` so
+they land where an agent at the outer repo looks. To refresh an existing
+project's tooling, run `npx create-obsidian-arrow update` (see the
+obsidian-arrow-maintenance skill).
+
 ## Arrow v1.0.6 footguns — READ BEFORE WRITING TEMPLATES
 
 These are hard runtime errors, not style nits. They are encoded in CI

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
 
@@ -24,6 +24,21 @@ Then `cd my-app && pnpm install && pnpm pull-css && pnpm dev`. A freshly
 scaffolded project passes `pnpm run ci` out of the box. The initializer's
 template is generated from this repo (`pnpm create:sync`), so it never drifts.
 
+**Update an existing project's tooling** (refreshes the managed files — scripts,
+skills, docs, agent guides, CI, `biome.json` — and merges new `package.json`
+scripts/deps; never touches `src/`, `public/`, `index.html`, or build configs):
+
+```sh
+npx create-obsidian-arrow update            # in the project (or: update <dir>)
+npx create-obsidian-arrow update --dry-run  # preview first
+```
+
+> **Nested in another repo?** If you scaffold inside an existing repo, bundled
+> skills install scoped to the scaffold folder (the `skills` CLI is cwd-relative).
+> To install them at the outer repo instead:
+> `pnpm skills:install --yes --project-dir=<outer-repo>` (or `--global` for
+> user-level). The scaffolder prints this hint when it detects nesting.
+
 > This repo (the full sandbox) is **not** published to npm — only the
 > `create-obsidian-arrow/` initializer is. An agent-onboarding prompt lives in
 > [`docs/prompts/agent-setup.md`](docs/prompts/agent-setup.md).
@@ -75,17 +90,31 @@ 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.
+- `obsidian-arrow-maintenance` — updating an existing project: `create-obsidian-arrow
+  update`, `skills:update`, nesting/`--project-dir`, re-pull styling.
 
-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:install --yes --project-dir=<repo-root> # install into another project root
+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`).
+Scope flags: `--agent <name>` (one agent), `--project-dir=<path>` (install into a
+different project root, e.g. an outer repo a scaffold is nested in), `--global`
+(user-level, available everywhere). `pnpm skills:update` runs
+`npx skills update -y`. The auto `postinstall` step takes no CLI args, so the env
+forms `SKILLS_AGENT` / `SKILLS_PROJECT_DIR` / `SKILLS_GLOBAL` (and
+`SKIP_SKILLS_INSTALL=1`) influence *that* path.
 
 ## Porting a component into the plugin
 

package/template/_gitignore

@@ -3,6 +3,10 @@ dist
 .DS_Store
 *.tgz
 
+# `skills` install artifacts (regenerated by `pnpm skills:install`); the source
+# of truth is skills/. (skills-lock.json is intentionally kept tracked.)
+.agents/
+
 # Obsidian's app.css is proprietary — extract it locally with `pnpm pull-css`,
 # don't commit/redistribute it.
 public/app.css

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

@@ -32,15 +32,21 @@ 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.
+                              # NESTED inside another repo? Skills install cwd-relative,
+                              # so add --project-dir=<outer-repo> (or --global) to put them
+                              # where an agent at the outer repo will find them.
 
 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).
+  Lucide/data-icon sweep, CSS scoping, mount/unmount lifecycle, reactive state),
+  arrow-js-obsidian-porting (sandbox→plugin parity check),
+  obsidian-arrow-maintenance (updating an existing project).
 
 ARROW v1.0.6 FOOTGUNS — do not relearn these the hard way:
 1. NO literal HTML comments inside html`` templates — Arrow treats HTML comments
@@ -75,7 +81,12 @@ PORTING TO A PLUGIN
 Copy the component file into the plugin's view dir and mount 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.
+`import '@arrow-js/framework'`. Leave src/sandbox/* behind. Guard against drift
+with the porting-parity check (see the arrow-js-obsidian-porting skill).
+
+MAINTENANCE (existing project)
+Refresh tooling later with `npx create-obsidian-arrow update` (preserves src/),
+update skills with `pnpm skills:update`. See the obsidian-arrow-maintenance skill.
 
 Start by scaffolding, running setup steps, then read AGENTS.md and confirm
 `pnpm dev` renders /example correctly. Report what you see.

package/template/docs/workflow.md

@@ -0,0 +1,85 @@
+# 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).
+
+**Nested inside another repo?** Skills install scoped to the current folder (the
+`skills` CLI is cwd-relative). To install them at the outer repo instead:
+`pnpm skills:install --yes --project-dir=<outer-repo>` (or `--global`).
+
+**Refresh an existing project's tooling** (scripts, skills, docs, CI — never your
+`src/`): `npx create-obsidian-arrow update` (add `--dry-run` to preview).
+
+## 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"
 	},