create-obsidian-arrow 0.1.8 → 0.2.1

package/README.md

@@ -24,10 +24,11 @@ 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`.
 
-### Install the bundled skills
+### Install the agent skills
 
-The scaffold ships agent skills and installs them via the [`skills`](https://github.com/vercel-labs/skills)
-CLI:
+Skills aren't vendored into the scaffold — `skills:install` pulls them from the
+published repo (source of truth, always current) via the
+[`skills`](https://github.com/vercel-labs/skills) CLI:
 
 ```sh
 pnpm skills:install --yes                       # non-interactive — installs all
@@ -68,8 +69,9 @@ node create-obsidian-arrow/index.mjs update ../my-app   # update
 
 A full sandbox: client-only Vite + TS, `@arrow-js/core` + `@arrow-js/framework`
 (no SSR), `routeToPage` + Navigation-API router with an `/example` demo, Biome +
-husky pre-commit + `node:test` + GitHub Actions CI, bundled agent skills, and the
-`pull-css` script that extracts Obsidian's `app.css`.
+husky pre-commit + `node:test` + GitHub Actions CI, a `skills:install` that pulls
+the agent skills from the published repo, and the `pull-css` script that extracts
+Obsidian's `app.css`.
 
 ## Maintaining the template
 

package/index.mjs

@@ -27,17 +27,10 @@ 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",
-];
+// port-parity.json, …) is treated as user-owned and left alone. Skills aren't
+// here — they're pulled from the published repo via `pnpm skills:update`, not
+// vendored into the scaffold.
+const MANAGED = ["scripts", "docs", ".github", ".husky", "biome.json", "AGENTS.md", "CLAUDE.md"];
 
 const argv = process.argv.slice(2);
 const dryRun = argv.includes("--dry-run");
@@ -182,7 +175,7 @@ function update(targetArg) {
 	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"
+			: "\nLeft alone: src/, public/, index.html, vite.config.ts, tsconfig.json, .gitignore.\nRun `pnpm install` then `pnpm check`. Update skills separately with `pnpm skills:update`.\n"
 	);
 }
 

package/package.json

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

package/template/AGENTS.md

@@ -13,8 +13,8 @@ This file is the hub — everything else is linked from here:
   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).
+- [`docs/prompts/`](docs/prompts/) — copy-paste agent prompts: `agent-setup.md`
+  (scaffold + orient) and `update-existing.md` (update tooling + skills, keep src).
 
 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.
@@ -41,8 +41,9 @@ 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
+Install the skills (pulled from the published repo, not vendored):
+`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

package/template/README.md

@@ -33,15 +33,18 @@ 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.
+> **Nested in another repo?** If you scaffold inside an existing repo, skills
+> install scoped to the scaffold folder (the `skills` CLI is cwd-relative), so the
+> session/`skill://` registry — which only indexes the **repo root** + global —
+> won't see them. Install at the outer repo instead:
+> `pnpm skills:install --yes --project-dir=<outer-repo>` (or, from the outer repo,
+> `npx skills add kylebrodeur/obsidian-arrow-sandbox --all --yes`), then **reload
+> the session**. 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).
+> `create-obsidian-arrow/` initializer is. Copy-paste agent prompts live in
+> [`docs/prompts/`](docs/prompts/): `agent-setup.md` (scaffold + orient) and
+> `update-existing.md` (update tooling + skills, keeping `src/` intact).
 
 ## Quick start
 
@@ -81,10 +84,12 @@ Obsidian install.
 A husky `pre-commit` hook runs `lint-staged` (Biome on staged files) + a full
 typecheck. CI (`.github/workflows/ci.yml`) runs the `ci` script on push/PR.
 
-## Bundled agent skills
+## Agent skills
 
-This repo ships [`skills`](https://github.com/vercel-labs/skills)-compatible skills
-under [`skills/`](skills/) — it doubles as a local skill marketplace:
+This repo is the source of truth for five [`skills`](https://github.com/vercel-labs/skills)-compatible
+skills under [`skills/`](skills/) — it's a skill marketplace. Scaffolds **don't
+vendor copies**; they pull from this published repo, so installs are always
+current.
 
 - `obsidian-arrow-sandbox` — running and using this sandbox, and porting to a plugin.
 - `arrow-js-obsidian-templates` — Arrow v1.0.6 template rules + footguns.
@@ -96,19 +101,23 @@ under [`skills/`](skills/) — it doubles as a local skill marketplace:
 - `obsidian-arrow-maintenance` — updating an existing project: `create-obsidian-arrow
   update`, `skills:update`, nesting/`--project-dir`, re-pull styling.
 
-Install them into your agent:
+Install them into your agent (pulls from the published repo; the sandbox repo
+itself uses its local `skills/`):
 
 ```sh
 pnpm skills:install                                 # interactive picker (TUI) on a terminal
-pnpm skills:install --yes                           # non-interactive — installs ALL bundled skills
+pnpm skills:install --yes                           # non-interactive — installs all 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
 ```
 
+Anywhere, with no project at all:
+`npx skills add kylebrodeur/obsidian-arrow-sandbox --all --yes`.
+
 `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`).
+hangs). For agents/CI, use `--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

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

@@ -32,8 +32,8 @@ 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 --yes   # install ALL bundled agent skills non-interactively
-                              # (runs `npx skills add . --all --yes`) — this loads
+  pnpm skills:install --yes   # install all agent skills non-interactively, pulled
+                              # from the published repo (not vendored) — 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

package/template/docs/prompts/update-existing.md

@@ -0,0 +1,78 @@
+# Update-existing-project prompt
+
+Copy the block below and give it to a coding agent to bring an **existing**
+Obsidian Arrow project fully up to date — tooling, skills, styling — **without
+touching your source code**.
+
+---
+
+```text
+Update this existing Obsidian Arrow project to the latest tooling and agent
+skills. Do NOT change any of my source code.
+
+HARD CONSTRAINTS
+- Never modify src/, public/, index.html, vite.config.ts, tsconfig.json, or my
+  component/app code. Only managed tooling, skills, and docs may change.
+- Preview before applying anything destructive; don't commit unless I ask.
+- At the end, prove src/ was untouched (`git diff --stat` shows no src/ changes).
+
+CONTEXT
+Scaffolded from create-obsidian-arrow. Tooling + agent skills come from the
+published repo kylebrodeur/obsidian-arrow-sandbox; skills install via the
+`skills` CLI and are NOT vendored in the project.
+
+STEPS (in order)
+
+1. Locate + nesting check
+   - Find the project root (has package.json + scripts/).
+   - Is it nested in a larger repo? Compare `git rev-parse --show-toplevel` to the
+     project dir. If the OUTER root differs, that's where skills must be installed
+     so the session's skill:// registry (repo-root + global only) can find them.
+
+2. Refresh tooling — preserves src/
+   - Preview:  npx create-obsidian-arrow update --dry-run
+   - Apply:    npx create-obsidian-arrow update
+   - Then:     pnpm install
+   Refreshes scripts/, docs/, .github/, .husky/, biome.json, AGENTS.md, CLAUDE.md
+   and merges package.json scripts/deps. It never touches src/, public/, or configs.
+
+3. Reset agent skills to the current set
+   - Audit:   npx skills list
+   - Remove any stale/old ones (older setups were missing some skills):
+       npx skills remove obsidian-arrow-sandbox arrow-js-obsidian-templates \
+         arrow-js-obsidian-patterns arrow-js-obsidian-porting obsidian-arrow-maintenance
+   - Install the current set from the published repo, AT THE RIGHT ROOT (the OUTER
+     repo root if nested):
+       npx skills add kylebrodeur/obsidian-arrow-sandbox --all --yes
+     (equivalently from the project: pnpm skills:install --yes
+      [--project-dir=<outer-repo>])
+   - Reload the agent session so skill:// resolves them.
+
+4. Refresh Obsidian styling
+   - pnpm pull-css        (needs a local Obsidian; macOS auto-detected, else --path)
+
+5. Clean stray install artifacts
+   - git status — untracked .agents/ (now git-ignored) or stray skills-lock.json?
+   - Broken symlinks:  find .agents ~/.claude/skills -type l ! -exec test -e {} \; -print
+
+6. Re-check porting parity (only if you keep a port-parity manifest)
+   - node scripts/component-hash.mjs --check port-parity.json
+
+7. Verify
+   - pnpm run ci          (biome + typecheck + tests + build)
+   - pnpm dev             and confirm /example renders with a clean console
+
+REPORT
+- What `update` changed, which skills are now installed and where, the pull-css
+  result, and `git diff --stat` confirming src/ is untouched.
+```
+
+---
+
+## Notes
+- Skills are pulled from the published repo, so step 3 is location-independent for
+  the *source* — only the *install location* matters (run it at the repo root the
+  agent uses; reload after).
+- `npx create-obsidian-arrow update` is **create-only-safe**: it refreshes managed
+  files and merges `package.json`, but never overwrites `src/`, `public/`,
+  `index.html`, or build configs. See the `obsidian-arrow-maintenance` skill.

package/template/docs/workflow.md

@@ -37,7 +37,7 @@ 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:install --yes    # non-interactive — installs all skills from the published repo (agents/CI)
 pnpm skills:update           # update an already-installed setup to the latest
 ```
 

package/template/scripts/install-skills.mjs

@@ -1,30 +1,33 @@
 #!/usr/bin/env node
 /**
- * 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.
+ * Install / update the obsidian-arrow agent skills via the `skills` CLI
+ * (https://github.com/vercel-labs/skills).
+ *
+ * Skills are NOT vendored into scaffolds — they're pulled from the published
+ * repo (the source of truth), so installs are always current and don't depend on
+ * a bundled copy. The sandbox repo itself (which has a local `skills/` dir) uses
+ * that local copy instead, so you can test edits before publishing.
  *
  * Modes (auto-detected):
  *   - Interactive terminal       → opens the picker TUI (choose what to install).
- *   - Non-interactive / CI / -y  → installs ALL bundled skills, no prompts.
+ *   - Non-interactive / CI / -y  → installs ALL skills, no prompts.
  *   - --update                   → updates an already-installed setup in place.
  *
  * 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.
+ *   - `pnpm skills:install [--yes]`  → picker, or non-interactive install of all.
+ *   - `pnpm skills:update`           → update installed skills to the latest.
  *
  * Flags / env:
+ *   --source <ref> | SKILLS_SOURCE=<ref>   where to pull skills from (default: the
+ *                          published repo; a local `skills/` dir is used if present)
  *   --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
+ *   --yes / -y              non-interactive install of all skills
+ *   --agent <name> | --agent=<name>   install for one agent instead of all
  *   --project-dir=<path>    install into another project root (e.g. the outer repo
  *                          a scaffold is nested in); project-scoped there
- *   --global / -g           install at user level (~/.<agent>/…), available
- *                          everywhere; some agents don't support global
+ *   --global / -g           install at user level (~/.<agent>/…), everywhere
  *   SKILLS_AGENT / SKILLS_PROJECT_DIR / SKILLS_GLOBAL   env forms (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
@@ -35,8 +38,9 @@ import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 
-const BUNDLED =
-	"obsidian-arrow-sandbox, arrow-js-obsidian-templates, arrow-js-obsidian-patterns, arrow-js-obsidian-porting";
+const REPO = "kylebrodeur/obsidian-arrow-sandbox";
+const SKILLS =
+	"obsidian-arrow-sandbox, arrow-js-obsidian-templates, arrow-js-obsidian-patterns, arrow-js-obsidian-porting, obsidian-arrow-maintenance";
 
 const has = (flag) => process.argv.includes(flag);
 // Accepts both `--flag value` and `--flag=value`.
@@ -49,9 +53,7 @@ const flagValue = (flag) => {
 	return i >= 0 ? process.argv[i + 1] : undefined;
 };
 
-/** Nearest ancestor *above* `dir` that is a git repo, or null. Used to warn
- * when this project is nested inside another repo (skills install per-project,
- * relative to cwd — not the outer root). */
+/** 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;
@@ -75,10 +77,14 @@ const isCI = Boolean(process.env.CI);
 const interactive = Boolean(process.stdout.isTTY && process.stdin.isTTY);
 const optedOut = process.env.SKIP_SKILLS_INSTALL === "1";
 
-// `skills add` installs project-scope relative to cwd. To install into another
-// root (e.g. the outer repo a scaffold is nested in), run the CLI there while
-// sourcing the skills from THIS folder by absolute path.
-const skillsSource = projectDir ? path.resolve(".") : ".";
+// Pull from the published repo by default; prefer a local `skills/` dir if
+// present (the sandbox repo itself); honor an explicit --source override.
+const explicitSource = flagValue("--source") || process.env.SKILLS_SOURCE;
+const hasLocalSkills = fs.existsSync(path.join(process.cwd(), "skills"));
+const baseSource = explicitSource ?? (hasLocalSkills ? "." : REPO);
+// A repo ref is cwd-independent; a local "." must be made absolute when
+// --project-dir redirects cwd so it still resolves.
+const source = projectDir && baseSource === "." ? path.resolve(".") : baseSource;
 const targetCwd = projectDir ? path.resolve(projectDir) : process.cwd();
 
 if (projectDir && !fs.existsSync(targetCwd)) {
@@ -101,7 +107,7 @@ function run(args, cwd = process.cwd()) {
 	});
 	if (result.error) {
 		console.error(
-			`[skills] could not run npx skills (${result.error.message}). Install manually: npx skills add . --all --yes`
+			`[skills] could not run npx skills (${result.error.message}). Install manually: npx skills add ${REPO} --all --yes`
 		);
 		process.exit(0); // never fail an install over an optional convenience step
 	}
@@ -123,27 +129,24 @@ if (update) {
 // `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`
+		`[skills] Agent skills: ${SKILLS}\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);
 }
 
 // Non-interactive (CI/agent/no TTY, or --yes, or an agent/global target): install
-// ALL bundled skills with no prompts. Target one agent if asked, else all agents.
+// ALL skills with no prompts. Target one agent if asked, else all agents.
 if (!interactive || yes || agent || global || projectDir) {
-	console.log(`[skills] Installing all bundled skills non-interactively: ${BUNDLED}`);
+	console.log(`[skills] Installing all skills non-interactively from ${source}: ${SKILLS}`);
 	const outer = global || projectDir ? null : outerRepoAbove(process.cwd());
 	if (outer) {
 		console.log(
-			`[skills] note: this folder is nested inside ${outer}. Skills install here, scoped to THIS project. To install at the outer repo instead, re-run with --project-dir=${outer} (or --global for user-level).`
+			`[skills] note: this folder is nested inside ${outer}, and skills install scoped to cwd. For session/skill:// discovery they must live at the repo root — install there with:\n         pnpm skills:install --yes --project-dir=${outer}\n         (or, from ${outer}: npx skills add ${REPO} --all --yes). Reload the session afterwards.`
 		);
 	}
 	// `--all` is shorthand for `-s * -a * -y`; to target one agent we spell out
-	// all-skills + that agent explicitly. `skillsSource` is absolute when
-	// --project-dir redirects cwd elsewhere.
-	const args = agent
-		? ["add", skillsSource, "-s", "*", "-a", agent, "-y"]
-		: ["add", skillsSource, "--all"];
+	// all-skills + that agent explicitly.
+	const args = agent ? ["add", source, "-s", "*", "-a", agent, "-y"] : ["add", source, "--all"];
 	if (global) {
 		args.push("--global");
 	}
@@ -151,5 +154,5 @@ if (!interactive || yes || agent || global || projectDir) {
 }
 
 // Interactive terminal: let the user pick in the TUI.
-console.log(`[skills] Opening the skills picker. Bundled: ${BUNDLED}`);
-run(["add", "."]);
+console.log(`[skills] Opening the skills picker (source: ${source}). Skills: ${SKILLS}`);
+run(["add", source]);

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

@@ -1,94 +0,0 @@
----
-name: arrow-js-obsidian-patterns
-description: Use when building reactive Obsidian plugin UI with @arrow-js/core beyond basic templates — icons (Obsidian uses Lucide; the data-icon sweep since setIcon can't run inside templates), CSS scoping/specificity against Obsidian's global rules, component mount/unmount lifecycle in an ItemView, and organizing shared reactive state. Complements arrow-js-obsidian-templates (syntax) with integration patterns.
----
-
-# Arrow.js + Obsidian integration patterns
-
-How to build real components (not just template syntax) for an Obsidian plugin
-view with `@arrow-js/core`. Pairs with **arrow-js-obsidian-templates** (the
-template rules + footguns).
-
-## Mount / unmount lifecycle
-
-A view mounts a component imperatively, the same call the sandbox makes:
-
-```ts
-import { html } from "@arrow-js/core"
-// in ItemView.onOpen():
-this.contentEl.empty()
-html`${MyComponent()}`(this.contentEl)
-```
-
-- `html\`\`(container)` does **not** reliably return an unmount function — don't
-  gate cleanup on its return value. Always `container.empty()` before remounting.
-- Re-rendering on route/state change: clear the container, then mount fresh.
-  Reactive bindings (`${() => …}`) update in place — don't remount the whole tree
-  on every state change; let Arrow patch the slots that read changed state.
-
-## Shared reactive state
-
-One `reactive()` object is the single source of truth; components read it via
-getters so they stay in sync without prop-drilling.
-
-```ts
-import { reactive } from "@arrow-js/core"
-export const state = reactive({ model: "", streaming: false, items: [] })
-// pass getters into components: Toggle(() => state.streaming, () => { ... })
-```
-
-## Icons (Obsidian uses Lucide)
-
-`setIcon(el, name)` needs a real DOM element, so it **cannot** be called inside
-an Arrow template expression (the element doesn't exist yet). Two options:
-
-1. **In-plugin — the data-icon sweep.** Emit a placeholder, then sweep after
-   mount:
-
-   ```ts
-   html`<span class="svg-icon" data-icon="copy"></span>`
-   // after template(container) — scope the query to the container, not document:
-   for (const el of Array.from(container.querySelectorAll<HTMLElement>("[data-icon]"))) {
-     const name = el.getAttribute("data-icon")
-     if (name) setIcon(el, name)  // setIcon from "obsidian"
-   }
-   ```
-   For sections that open after mount (dropdowns/popovers), run the sweep in a
-   `nextTick(...)` after they render, scoped to that section's element.
-
-2. **In the sandbox (no `obsidian` module).** Use a Lucide import or inline SVG,
-   or plain text/emoji for chrome. The baseline uses text glyphs to stay
-   shim-free; add a Lucide-backed `setIcon` shim (aliased as `obsidian`) when you
-   port icon-using components in.
-
-## CSS scoping & specificity (the big one)
-
-Obsidian's `app.css` applies global rules like
-`button:not(.clickable-icon) { background: var(--interactive-normal) }` at
-specificity **(0,1,1)**. A plain `.my-btn` selector is **(0,1,0)** and loses
-regardless of cascade order.
-
-```css
-/* (0,1,0) — LOSES to Obsidian's global button rule */
-.my-action { background: var(--interactive-accent); }
-
-/* (0,2,1) — WINS, and can't leak */
-.my-panel button.my-action { background: var(--interactive-accent); }
-```
-
-Rules: prefer Obsidian's own classes (`.setting-item`, `.clickable-icon`,
-`.workspace-leaf`, `.vertical-tab-*`, `.modal`) and `var(--…)` tokens first; only
-add custom CSS where there's no Obsidian class; always scope custom rules under a
-container class + element type.
-
-## Common Obsidian layout classes
-
-- `.workspace-leaf` > `.workspace-leaf-content` — a view pane.
-- `.view-header` / `.view-content` — pane header + body.
-- `.setting-item` (+ `.setting-item-info` / `.setting-item-name` /
-  `.setting-item-description` / `.setting-item-control`) — settings rows.
-- `.checkbox-container` (+ `.is-enabled`) — toggle.
-- `.clickable-icon` — icon button (escapes the global button background rule).
-- `.vertical-tab-header` / `.vertical-tab-nav-item` (+ `.is-active`) — tab nav.
-- `.modal-container` > `.modal` — modal/popover.
-- `.mod-cta` — primary call-to-action button.

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

@@ -1,92 +0,0 @@
----
-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,101 +0,0 @@
----
-name: arrow-js-obsidian-templates
-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)
-
-Rules for writing `html\`\`` templates that render correctly in the browser and
-inside an Obsidian plugin. Several of these are hard runtime errors, not style.
-
-## Reactive vs static — the core rule
-
-```ts
-import { html, reactive } from "@arrow-js/core"
-const data = reactive({ count: 0 })
-
-html`<span>${data.count}</span>`        // ❌ renders ONCE — never updates
-html`<span>${() => data.count}</span>`  // ✅ tracked — updates only this slot
-```
-
-`${value}` is read once at mount. `${() => value}` is tracked: Arrow records the
-reactive reads inside the function and re-runs **only that slot** when they
-change. Forgetting `() =>` is the #1 "why isn't it updating" bug.
-
-## Attributes
-
-An attribute expression must be the **entire** attribute value:
-
-```ts
-html`<div class="${() => (active() ? "tab is-active" : "tab")}">`  // ✅
-html`<div class="tab ${() => active() ? "is-active" : ""}">`        // ❌ THROWS
-```
-
-Partial values (`"static ${…}"`) are not registered as placeholders and throw
-`Invalid HTML position`. Build the full string in one expression.
-
-Returning `false` from an attribute expression **removes** the attribute (vs `""`
-which keeps it present-but-empty) — the clean way to toggle `disabled`/`hidden`:
-
-```ts
-html`<button disabled="${() => !canSubmit()}">Save</button>`
-```
-
-## Properties, events, lists
-
-```ts
-html`<input .value="${() => data.text}" />`                 // .prop = IDL property
-html`<button @click="${() => data.count++}">+</button>`     // @event
-html`${() => data.items.map((i) => html`<li>${i.text}</li>`.key(i.id))}`  // keyed list
-```
-
-Keyed lists preserve DOM across reorders; mutate item fields in place for
-fine-grained updates instead of replacing the whole array.
-
-## Async sections
-
-```ts
-import { boundary } from "@arrow-js/framework"
-const Card = component(
-  async () => { const d = await load(); return html`<div>${d.label}</div>` },
-  { fallback: html`<div>Loading…</div>` }   // shown while pending
-)
-html`${boundary(Card())}`
-```
-
-Works client-side with no SSR. `boundary()` only takes `{ idPrefix }`; the
-visible loading state comes from the async component's `fallback` option.
-
-## Event handler typing
-
-An `@event` handler must be assignable to `(e: Event) => void`. A handler typed
-with a narrowed subtype fails (parameter contravariance) — `tsc` reports
-`TS2345 … not assignable to 'ArrowExpression'`. Type the param `Event` and
-narrow inside; no-arg handlers are always fine.
-
-```ts
-// ❌ TS2345 — narrowed param
-html`<div @mousedown="${(e: MouseEvent) => resize(e)}">`
-// ✅ widen, narrow inside
-html`<div @mousedown="${(e: Event) => resize(e as MouseEvent)}">`
-```
-
-(document.addEventListener handlers are unaffected — they're DOM-lib typed.)
-
-## Hard footguns
-
-Render-time (pass `tsc`, fail only at render — always verify in a browser):
-
-1. **No literal HTML comments inside templates.** Arrow uses HTML comments as
-   expression-slot markers, so a literal `<!-- … -->` inflates the slot count and
-   throws `Invalid HTML position`. Use JS `//` comments outside the template.
-2. **No partial attribute values** — the expression must be the whole value
-   (see Attributes above), else `Invalid HTML position`.
-
-Type-time (caught by `tsc`):
-
-3. **No narrowed `Event` subtype in `@event` handlers** (see Event handler
-   typing above).
-
-CI guards all three: `test/template-footguns.test.mjs` scans for `<!--` and for
-inline handlers typed with a narrowed Event subtype; `tsc` covers the rest.

package/template/skills/obsidian-arrow-maintenance/SKILL.md

@@ -1,69 +0,0 @@
----
-name: obsidian-arrow-maintenance
-description: Use when updating or maintaining an EXISTING scaffolded obsidian-arrow project — refresh the managed tooling with create-obsidian-arrow update, update installed agent skills with pnpm skills:update, fix skills scoping when the project is nested inside another repo (--project-dir / --global), and re-pull Obsidian styling. Only tooling/skills/docs are refreshed; your src is preserved.
----
-
-# Maintaining an existing Obsidian Arrow project
-
-How to bring an already-scaffolded project up to date. The scaffolder is
-create-only (it refuses a non-empty dir), so updates split into three tracks:
-**tooling files**, **agent skills**, and **styling**. None of these touch your
-`src/`.
-
-## 1. Refresh the tooling (scripts, skills files, docs, CI, config)
-
-```sh
-npx create-obsidian-arrow update            # in the project root (or: update <dir>)
-npx create-obsidian-arrow update --dry-run  # preview what would change first
-```
-
-Refreshes the **managed** files from the latest template — `scripts/`, `skills/`,
-`docs/`, `.github/`, `.husky/`, `biome.json`, `AGENTS.md`, `CLAUDE.md` — and
-**merges** `package.json` scripts + any missing deps. It **never** touches `src/`,
-`public/`, `index.html`, `vite.config.ts`, `tsconfig.json`, or `.gitignore`. After
-it runs: `pnpm install && pnpm check`.
-
-## 2. Update the installed agent skills
-
-```sh
-pnpm skills:update    # = npx skills update -y  (updates installed skills in place)
-```
-
-Or reinstall the latest straight from the published repo (works from anywhere,
-even if the project predates the skill scripts):
-
-```sh
-npx skills add kylebrodeur/obsidian-arrow-sandbox --all --yes
-```
-
-## 3. Nested inside another repo? Fix skills scoping
-
-The `skills` CLI installs project-scope **relative to cwd**. If this project sits
-inside a larger repo and your agent runs from the **outer** repo, skills installed
-here won't be found. Install them where the agent looks:
-
-```sh
-pnpm skills:install --yes --project-dir=<outer-repo>   # project-scoped at the outer root
-pnpm skills:install --yes --global                     # or user-level (all projects)
-```
-
-(`SKILLS_PROJECT_DIR` / `SKILLS_GLOBAL` env forms drive the auto `postinstall`
-step, which takes no CLI args.)
-
-## 4. Re-pull Obsidian styling after Obsidian updates
-
-`public/app.css` is a local snapshot (git-ignored). If Obsidian updated or the
-sandbox renders stale, refresh it:
-
-```sh
-pnpm pull-css
-```
-
-## 5. Re-check porting parity
-
-After updating, re-run the porting-parity check so plugin copies still match the
-sandbox source (see the **arrow-js-obsidian-porting** skill):
-
-```sh
-node scripts/component-hash.mjs --check port-parity.json
-```

package/template/skills/obsidian-arrow-sandbox/SKILL.md

@@ -1,77 +0,0 @@
----
-name: obsidian-arrow-sandbox
-description: Use when prototyping or building Arrow.js UI for an Obsidian plugin in the obsidian-arrow-sandbox project — covers running the sandbox, pulling Obsidian's real app.css from the local install, the dev/verify workflow, CSS scoping, and porting a finished component into a plugin's ItemView with near-zero refactoring.
----
-
-# Obsidian Arrow Sandbox
-
-A client-only Vite + TypeScript environment for building [Arrow.js](https://arrow-js.com/)
-UI that drops into an Obsidian plugin. Components render against Obsidian's real
-`app.css`, so what you see in the browser is what you get in a plugin view.
-
-## Mental model
-
-- **Client-only, no SSR.** Components use `@arrow-js/core` (`reactive`, `html`,
-  `component`, `watch`) plus `@arrow-js/framework` (`boundary` for async
-  sections), mounted via `template(container)` — the exact call an Obsidian
-  `ItemView.onOpen()` makes. Do **not** add `@arrow-js/ssr` or `@arrow-js/hydrate`;
-  an Obsidian plugin has no server and nothing to hydrate.
-- **Styling is Obsidian's, not yours.** `index.html` puts Obsidian body classes
-  (`theme-dark mod-macos …`) on `<body>` and loads the extracted `app.css`, which
-  defines every `var(--…)` token and semantic class (`.setting-item`,
-  `.clickable-icon`, `.vertical-tab-*`).
-
-## Run it
-
-```sh
-pnpm install
-pnpm pull-css     # extract Obsidian's app.css (macOS auto-detect)
-pnpm dev          # Vite + HMR; open the printed URL
-```
-
-`pnpm pull-css` reads `app.css` out of `obsidian.asar`. macOS is auto-detected;
-elsewhere pass `--path <obsidian.asar|app.css>` or set `OBSIDIAN_ASAR=<path>`.
-`public/app.css` is **git-ignored** (Obsidian's proprietary CSS — not
-redistributed), so run `pnpm pull-css` once before `pnpm dev`.
-
-## Install the bundled skills
-
-```sh
-pnpm skills:install --yes   # non-interactive: install ALL bundled skills (agents/CI)
-pnpm skills:install         # interactive picker on a terminal
-pnpm skills:update          # update an already-installed setup
-```
-
-Scope flags: `--agent <name>`, `--project-dir=<path>` (install into another repo
-root — use this when the project is **nested** inside a larger repo), `--global`.
-To update an existing project's tooling later, see the **obsidian-arrow-maintenance**
-skill (`npx create-obsidian-arrow update`).
-
-## Build a component
-
-Add `src/components/MyThing.ts` exporting an Arrow `component()`, then mount it
-from `src/main.ts`. Use Obsidian classes + `var(--…)` tokens first; add custom
-CSS only when there's no Obsidian class, and scope it under a container class +
-element type (e.g. `.oas-frame button.oas-x`) so it beats Obsidian's global
-`button:not(.clickable-icon)` rule. Sandbox-only chrome lives in
-`src/sandbox/sandbox.css`.
-
-For the template-writing rules and Arrow's hard footguns, use the companion
-skill **arrow-js-obsidian-templates**.
-
-## Verify before claiming done
-
-```sh
-pnpm typecheck && pnpm test && pnpm lint   # or: pnpm check
-```
-
-Then open the `pnpm dev` URL and confirm the console is clean and the component
-looks like a real Obsidian pane. Arrow's footguns only surface at render, so
-typecheck passing is **not** proof a component works.
-
-## Port into the plugin
-
-Copy the component 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 sandbox chrome (`src/sandbox/*`) behind.