create-obsidian-arrow 0.5.0 → 0.5.2

package/template/AGENTS.md

@@ -11,6 +11,7 @@ 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` — running the sandbox, CSS scoping, porting basics.
+  - `obsidian-arrow-composition` — **run before designing any view area**: surveys codebase, shows file trees for confirmation, asks questions, checks DRY/primitive use, produces a locked hierarchy doc.
   - `obsidian-arrow-stories` — **component + story authoring workflow**: `defineStories` API, variants, children, status flag, DRY patterns, utilities.
   - `obsidian-arrow-css` — **CSS decision hierarchy**: Obsidian classes → oas-* utilities → custom CSS; token reference; specificity scoping; overrides via variables; auditing for excess CSS.
   - `arrow-js-obsidian-templates` — Arrow v1.0.6 template syntax + footguns.
@@ -19,6 +20,9 @@ This file is the hub — everything else is linked from here:
   - `obsidian-arrow-maintenance` — updating an existing project.
 - [`docs/prompts/`](docs/prompts/) — copy-paste agent prompts: `agent-setup.md`
   (scaffold + orient) and `update-existing.md` (update tooling + skills, keep src).
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — source-repo and tool development (monorepo layout,
+  `oasbox`/`create-obsidian-arrow` package dev, `pnpm create:sync`). **Project-level work
+  does not require reading this.**
 
 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.
@@ -37,23 +41,64 @@ summarized in "What this is (and isn't)" below and in the README.
 ## Run it
 
 ```sh
-pnpm install
-pnpm pull-css     # macOS-only auto-detect; else --path <asar|css> / OBSIDIAN_ASAR=<path>
-pnpm dev          # Vite + HMR
+<pm> install
+<pm> run pull-css   # macOS-only auto-detect; else --path <asar|css> / OBSIDIAN_ASAR=<path>
+<pm> run dev        # Vite + HMR
 ```
 
+(`<pm>` = `pnpm` / `npm` / `bun` — any package manager works.)
+
 `public/app.css` is **git-ignored** (Obsidian's proprietary CSS — not
-redistributed); run `pnpm pull-css` once before `pnpm dev`.
+redistributed); run `pull-css` once before `dev`.
 
 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
+`<pm> run skills:install --yes` (non-interactive, all skills) or `<pm> run skills:install`
+(TUI); update with `<pm> run 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
+project's tooling, run `npx create-obsidian-arrow refresh` (see the
 obsidian-arrow-maintenance skill).
 
+## oasbox — in-project CLI
+
+`oasbox` is installed as a local devDependency by the scaffold. Run it via
+`npx oasbox …`, `pnpm oasbox …`, or `bunx oasbox …` — works under any package manager.
+
+### generate
+
+```sh
+oasbox generate component <Name> [--css]       # flat or Parent/Child (view-scoped)
+oasbox generate view <Name> [--editor]         # --editor → surface:"editor", readable line width
+oasbox generate story <Name> [--kind view|component]
+```
+
+`pnpm create:view <Name>` and `pnpm create:component <Name>` are convenience aliases
+that delegate to `oasbox generate` — use whichever you prefer.
+
+### validate & test
+
+```sh
+oasbox validate          # check:css + check:scope + check:imports + typecheck
+oasbox validate --json   # machine-readable output
+oasbox test              # pass-through to project test runner
+oasbox dev               # pass-through to project dev server
+```
+
+## create-obsidian-arrow lifecycle
+
+`create-obsidian-arrow` is the **project lifecycle** CLI — run it ephemerally (no
+local install needed):
+
+```sh
+npx create-obsidian-arrow create <dir>    # scaffold a new project
+npx create-obsidian-arrow refresh [dir]   # refresh managed tooling files from the current template
+```
+
+`refresh` (formerly `update`) pulls fresh managed files; `--dry-run` shows what
+would change without writing. Genuine version bumps (skills, dependencies) are
+handled separately. Works with any PM: `npx` / `pnpm dlx` / `bunx`.
+
 ## Arrow v1.0.6 footguns — READ BEFORE WRITING TEMPLATES
 
 These are hard runtime errors, not style nits. They are encoded in CI
@@ -106,8 +151,9 @@ in `boundary()`.
 - `stories/components/` — stories for primitives (`kind: "component"`)
 - Mirror the `src/` structure. `kind` auto-detected from path; set explicitly to override.
 - `kind` — specifies story type (`"view"` or `"component"`).
+- `surface?: "panel" | "editor"` — which Obsidian surface a view replicates (orthogonal to `kind`). `"panel"` (default) is full-bleed (workspace leaf); `"editor"` is readable line width for note/document views. Scaffold with `pnpm create:view <Name> --editor` — it wraps the body in the portable `oas-readable-width` utility (ports 1:1) and sets the flag; the flag only widens the sandbox pane so the centering shows. Use that utility — don't write your own `max-width: var(--file-line-width)` container.
 - `decorator?: (content: ArrowExpression) => ArrowExpression` — wraps the rendered variant in ancestor context when a component requires a parent class to render correctly.
-- Scaffold: `pnpm create:view <Name>` / `pnpm create:component <Name>`
+- Scaffold: `pnpm create:view <Name>` (add `--editor` for readable-width) / `pnpm create:component <Name>`
 
 ### Composition analysis (extracting shared primitives)
 
@@ -131,10 +177,10 @@ When multiple views share a pattern, extract a primitive — but do it in this o
 ## Verify before claiming done
 
 ```sh
-pnpm typecheck    # tsc --noEmit
-pnpm test         # node:test
-pnpm lint         # biome
-pnpm check        # all of the above + CSS orphan + import boundary + scope checks
+<pm> run typecheck    # tsc --noEmit
+<pm> run test         # node:test
+<pm> run lint         # biome
+<pm> run check        # all of the above + CSS orphan + import boundary + scope checks
 ```
 
 Then confirm the actual render:

package/template/README.md

@@ -7,31 +7,33 @@ styled entirely by Obsidian's real `app.css`, so what you see here is what you
 get inside a plugin view.
 
 New machine? See [`docs/workflow.md`](docs/workflow.md) for the full
-fresh-checkout-to-running workflow.
+fresh-checkout-to-running workflow. **Working on the tooling itself?** See
+[`CONTRIBUTING.md`](CONTRIBUTING.md) for the monorepo dev workflow.
 
 ## Scaffold a new project
 
-Scaffold a fresh sandbox with the published initializer
-([`create-obsidian-arrow`](create-obsidian-arrow/)):
+Scaffold a fresh sandbox with the published initializer:
 
 ```sh
 npm create obsidian-arrow@latest my-app
-# or:  pnpm create obsidian-arrow my-app
-# or:  npx create-obsidian-arrow my-app
+# or:  npx create-obsidian-arrow create my-app
+# or:  pnpm dlx create-obsidian-arrow create my-app
+# or:  bunx create-obsidian-arrow create my-app
 ```
 
-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.
+Then `cd my-app && <pm> install && <pm> run pull-css && <pm> run dev`. A freshly
+scaffolded project passes the full `check` suite out of the box.
 
-**Update an existing project's tooling** (refreshes managed files — scripts,
+**Refresh an existing project's tooling** (pulls fresh managed files — scripts,
 docs, CI, `biome.json`, agent guides, and the viewer/router/sandbox
 infrastructure in `src/` — merges new `package.json` scripts/deps; never
 touches `src/components/`, `stories/`, `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
+npx create-obsidian-arrow refresh            # in the project (or: refresh <dir>)
+npx create-obsidian-arrow refresh --dry-run  # preview first
+# also: pnpm dlx create-obsidian-arrow refresh
+# also: bunx create-obsidian-arrow refresh
 ```
 
 > **Nested in another repo?** If you scaffold inside an existing repo, skills
@@ -43,55 +45,84 @@ npx create-obsidian-arrow update --dry-run  # preview first
 > 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. Copy-paste agent prompts live in
+> `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).
+> `update-existing.md` (refresh tooling + skills, keeping `src/` intact).
 
 ## Quick start
 
 ```sh
-pnpm install
-pnpm pull-css     # extract Obsidian's app.css from your local install (required)
-pnpm dev          # Vite dev server with HMR
+<pm> install
+<pm> run pull-css   # extract Obsidian's app.css from your local install (required)
+<pm> run dev        # Vite dev server with HMR
 ```
 
+(`<pm>` = `npm`, `pnpm`, `bun`, or `yarn` — whichever you prefer.)
+
 `pull-css` reads `app.css` out of `Obsidian.app/.../obsidian.asar` (macOS) and
 writes `public/app.css`. Override the location with `--path <obsidian.asar|app.css>`
-or `OBSIDIAN_ASAR=<path>`. **Run it once before `pnpm dev`** — it needs a local
+or `OBSIDIAN_ASAR=<path>`. **Run it once before `dev`** — it needs a local
 Obsidian install.
 
 > **Why it isn't committed:** `public/app.css` is **git-ignored**. It's
 > Obsidian's proprietary stylesheet, so we don't redistribute it — each developer
-> extracts it from their own licensed Obsidian install via `pnpm pull-css`.
+> extracts it from their own licensed Obsidian install via `pull-css`.
 
 > **Platform note:** automatic Obsidian discovery is currently **macOS-only** —
 > `pull-css` knows where `Obsidian.app` lives on macOS. Windows and WSL paths are
 > not auto-detected yet (planned). On those platforms, point the script at the
 > file explicitly via `--path <obsidian.asar|app.css>` or `OBSIDIAN_ASAR=<path>`.
 
+## Daily driver: `oasbox`
+
+`oasbox` is the in-project CLI — installed as a local devDependency by the scaffold.
+Run it via your package manager or `npx`:
+
+```sh
+# Generate scaffolding
+oasbox generate view ChatView            # new view (full-pane)
+oasbox generate view ChatView --editor   # readable line-width (surface: "editor")
+oasbox generate component Composer      # primitive → src/components/Composer/
+oasbox generate component ChatView/Widget  # view-scoped → src/views/ChatView/Widget.ts
+oasbox generate story MyWidget --kind component
+
+# Validate (runs CSS orphan/scope/import checks + typecheck)
+oasbox validate
+oasbox validate --json   # machine-readable output
+
+# Pass-throughs
+oasbox test
+oasbox dev
+```
+
+Invoke via your PM if `oasbox` isn't on your PATH: `pnpm oasbox …` / `npx oasbox …` / `bunx oasbox …`.
+
+The `create:view` / `create:component` scripts delegate to `oasbox generate` — both forms work.
+
 ## Scripts
 
 | Script | What it does |
 |---|---|
-| `pnpm dev` | Vite dev server (client-only, HMR) |
-| `pnpm build` / `pnpm preview` | Production build / preview |
-| `pnpm typecheck` | `tsc --noEmit` |
-| `pnpm test` | Node built-in test runner (`test/*.test.mjs`) |
-| `pnpm lint` / `pnpm format` | Biome check / check-and-write |
-| `pnpm check` | format + typecheck + test (local pre-flight) |
-| `pnpm ci` | Biome CI + typecheck + test + build (what CI runs) |
-| `pnpm pull-css` | refresh `public/app.css` from the local Obsidian install |
+| `dev` | Vite dev server (client-only, HMR) |
+| `build` / `preview` | Production build / preview |
+| `typecheck` | `tsc --noEmit` |
+| `test` | Node built-in test runner (`test/*.test.mjs`) |
+| `lint` / `format` | Biome check / check-and-write |
+| `check` | Biome + typecheck + test + CSS-orphan/scope/import checks (local pre-flight) |
+| `ci` | Biome CI + typecheck + test + CSS-orphan/scope/import checks + build (what CI runs) |
+| `pull-css` | refresh `public/app.css` from the local 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.
 
 ## Agent skills
 
-This repo is the source of truth for seven [`skills`](https://github.com/vercel-labs/skills)-compatible
+This repo is the source of truth for eight [`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-composition` — **run before designing any view area**: surveys codebase, shows proposed file trees, asks targeted questions, checks DRY and primitive use, produces a locked hierarchy doc for the migration agent to execute.
 - `obsidian-arrow-sandbox` — running and using this sandbox, CSS scoping, porting basics.
 - `obsidian-arrow-stories` — **component + story authoring workflow**: the complete `defineStories` API (variants, children, status flag, notes), DRY patterns, utility classes, story viewing, and how to structure sub-components.
 - `obsidian-arrow-css` — **CSS decision hierarchy**: Obsidian classes first, `oas-*` utilities second, custom CSS last; the live token reference (`/reference`), class catalog (`/reference/classes`), specificity scoping, overrides via CSS variables, and auditing components to minimize hand-written CSS.
@@ -101,8 +132,8 @@ current.
 - `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.
+- `obsidian-arrow-maintenance` — refreshing an existing project: `create-obsidian-arrow
+  refresh`, `skills:update`, nesting/`--project-dir`, re-pull styling.
 
 Install them into your agent (pulls from the published repo; the sandbox repo
 itself uses its local `skills/`):
@@ -118,7 +149,7 @@ pnpm skills:update                                  # update an existing setup t
 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
+`postinstall` offers the picker automatically after `<pm> install`, but only in
 an interactive terminal — in CI / non-TTY it just prints how to install (never
 hangs). For agents/CI, use `--yes`.
 Scope flags: `--agent <name>` (one agent), `--project-dir=<path>` (install into a
@@ -146,6 +177,7 @@ with live previews.
 
 ```sh
 pnpm create:view ChatView
+# or: oasbox generate view ChatView
 ```
 
 Creates `src/views/ChatView/` (ts + css + state.ts) and `stories/views/ChatView.stories.ts`.
@@ -155,9 +187,13 @@ Creates `src/views/ChatView/` (ts + css + state.ts) and `stories/views/ChatView.
 ```sh
 pnpm create:component Composer         # primitive → src/components/Composer/
 pnpm create:component ChatView/Widget  # view-specific → src/views/ChatView/Widget.ts
+# or: oasbox generate component Composer
 ```
 
-View stories use `kind: "view"` — full pane frame. Component stories use `kind: "component"` — centered canvas. Both auto-detected from the `stories/views/` vs `stories/components/` path.
+View stories use `kind: "view"` — full pane frame with `surface: "panel"` (default) for
+full-bleed or `surface: "editor"` for readable line width. Component stories use
+`kind: "component"` — centered canvas. Both auto-detected from the `stories/views/` vs
+`stories/components/` path.
 
 ## Porting a component into the plugin
 

package/template/_gitignore

@@ -9,7 +9,10 @@ dist
 
 # Obsidian's app.css is proprietary — extract it locally with `pnpm pull-css`,
 # don't commit/redistribute it.
-public/app.css
+**/public/app.css
+
+# CodeGraph index (per-machine, regenerated by `codegraph index`).
+.codegraph/
 
 # subagent-driven-development scratch (briefs, reports, ledger)
 .superpowers/

package/template/biome.json

@@ -25,6 +25,12 @@
 		}
 	},
 	"files": {
-		"ignore": ["dist", "node_modules", "public", "pnpm-lock.yaml", "create-obsidian-arrow/template"]
+		"ignore": [
+			"dist",
+			"node_modules",
+			"public",
+			"pnpm-lock.yaml",
+			"packages/create-obsidian-arrow/template"
+		]
 	}
 }

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

@@ -24,26 +24,29 @@ SCAFFOLD IT (use the published tool — pick one)
 
 Then:
   cd my-app
-  pnpm install
-  pnpm pull-css     # REQUIRED before dev — extracts Obsidian's app.css from your
-                    # LOCAL install into public/app.css (git-ignored, never
-                    # committed; it's Obsidian's proprietary CSS). Auto-detect is
-                    # macOS-only; on Windows/WSL pass --path <obsidian.asar|app.css>
-                    # or set OBSIDIAN_ASAR=<path>.
-  pnpm dev          # open the printed URL: / is home, /components the story viewer,
-                    # /reference the Obsidian token/class index.
-                    # The toolbar slider/presets + edge drag handle resize the panel.
-  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
-                              # where an agent at the outer repo will find them.
+  <pm> install                            # npm install, pnpm install, or bun install
+  <pm> run pull-css                       # REQUIRED before dev — extracts Obsidian's app.css from your
+                                          # LOCAL install into public/app.css (git-ignored, never
+                                          # committed; it's Obsidian's proprietary CSS). Auto-detect is
+                                          # macOS-only; on Windows/WSL pass --path <obsidian.asar|app.css>
+                                          # or set OBSIDIAN_ASAR=<path>.
+  <pm> run dev                            # open the printed URL: / is home, /components the story viewer,
+                                          # /reference the Obsidian token/class index.
+                                          # The toolbar slider/presets + edge drag handle resize the panel.
+  oasbox generate view MyView    # scaffold a new view (or component/story)
+  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
+                                          # where an agent at the outer repo will find them.
 
 READ FIRST
 - AGENTS.md (root) — operating guide + docs map (links everything below).
 - docs/workflow.md — fresh-machine → running workflow.
-- skills/*/SKILL.md — seven installable skills:
+- skills/*/SKILL.md — eight installable skills:
+    obsidian-arrow-composition  design component hierarchy: surveys codebase, shows file trees,
+                              asks questions, checks DRY/primitives, produces locked plan
     obsidian-arrow-sandbox    running the sandbox, CSS scoping, porting basics
     obsidian-arrow-stories    component + story authoring: defineStories API,
                               variants, children, status, DRY patterns, utilities
@@ -75,9 +78,10 @@ CONVENTIONS
   only when Obsidian has no class, scoped under a container class + element type
   (e.g. `.my-panel button.my-action`) so it beats Obsidian's global button rule.
 - Sandbox-only chrome lives in tools/sandbox/* — it does NOT port to a plugin.
-- Add a story by creating `stories/MyThing.stories.ts` (top-level `stories/`
-  dir, NOT in `src/`). Import: `"../tools/viewer/stories"` and
-  `"../src/components/MyThing"`. It appears at `/components/<slug>` automatically.
+- Add a story by creating `stories/components/MyThing.stories.ts` (or
+  `stories/views/MyView/MyView.stories.ts` for a view) — under `stories/`, NOT in
+  `src/`. Import (depth follows nesting): `"../../tools/viewer/stories"` and
+  `"../../src/components/MyThing"`. It appears at `/components/<slug>` automatically.
   Browse tokens at `/reference`, curated classes at `/reference/classes`.
 
 VERIFY BEFORE CLAIMING DONE
@@ -97,7 +101,7 @@ Leave tools/sandbox/* behind. Guard against drift with the porting-parity check
 (see the arrow-js-obsidian-porting skill).
 
 MAINTENANCE (existing project)
-Refresh tooling with `npx create-obsidian-arrow update` (preserves src/components/
+Refresh tooling with `npx create-obsidian-arrow refresh` (preserves src/components/
 and stories/ — updates viewer, router, sandbox, utilities, and tooling files),
 update skills with `pnpm skills:update`. See the obsidian-arrow-maintenance skill.
 

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

@@ -32,8 +32,8 @@ STEPS (in order)
      so the session's skill:// registry (repo-root + global only) can find them.
 
 2. Refresh tooling — preserves src/components/ only
-   - Preview:  npx create-obsidian-arrow update --dry-run
-   - Apply:    npx create-obsidian-arrow update
+   - Preview:  npx create-obsidian-arrow refresh --dry-run
+   - Apply:    npx create-obsidian-arrow refresh
    - Then:     pnpm install
    Refreshes scripts/, docs/, .github/, .husky/, biome.json, AGENTS.md, CLAUDE.md,
    tools/, src/main.ts, src/utilities.css, test/,
@@ -77,6 +77,6 @@ REPORT
 - 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` refreshes managed files and merges
+- `npx create-obsidian-arrow refresh` refreshes managed files and merges
   `package.json`, but never overwrites `src/components/`, `stories/`, `public/`,
   `index.html`, or build configs. See the `obsidian-arrow-maintenance` skill.

package/template/docs/workflow.md

@@ -51,25 +51,29 @@ Then point the agent at [`AGENTS.md`](../AGENTS.md), or brief a fresh agent with
 
 **Refresh an existing project's tooling** (scripts, docs, CI, viewer/router/sandbox
 in `src/` — never `src/components/` or `stories/`):
-`npx create-obsidian-arrow update` (add `--dry-run` to preview).
+`npx create-obsidian-arrow refresh` (add `--dry-run` to preview).
 
 ## Build → verify → port loop
 
 ```sh
 # 1. Check /reference/classes in the running sandbox — does Obsidian have a class
 #    for your pattern? Use it before writing custom CSS.
-# 2. Scaffold (or add manually):
-pnpm create:view ChatView              # full-pane view → src/views/ChatView/ + stories/views/
-pnpm create:component Composer         # reusable primitive → src/components/Composer/ + stories/components/
-pnpm create:component ChatView/Widget  # view-specific sub-component (not promoted yet)
+# 2. Generate components, views, and stories (using oasbox or the npm scripts):
+oasbox generate view ChatView          # full-pane view → src/views/ChatView/ + stories/views/
+oasbox generate component Composer     # reusable primitive → src/components/Composer/ + stories/components/
+oasbox generate component ChatView/Widget  # view-specific sub-component (not promoted yet)
+# Alternatively, the npm scripts delegate to oasbox:
+<pm> run create:view ChatView
+<pm> run create:component Composer
 # 3. Iterate with HMR
-pnpm dev
+<pm> run dev
 #    /components          → index of all discovered stories
 #    /components/my-thing → story for MyThing (kind: "component" → centered canvas)
 #    /components/chat-view → story for ChatView (kind: "view" → full pane)
 #    /reference           → live Obsidian token reference
 #    /reference/classes   → curated class catalog with live previews
-pnpm run ci       # biome + typecheck + tests + build before trusting it
+oasbox validate  # CSS check + scope + imports + typecheck
+<pm> run ci               # biome + typecheck + tests + build before trusting it
 ```
 
 Always confirm the actual render in the browser — Arrow's footguns and CSS scoping bugs

package/template/package.json

@@ -2,9 +2,9 @@
 	"name": "obsidian-arrow-sandbox",
 	"private": true,
 	"type": "module",
+	"version": "0.1.0",
 	"description": "Client-only sandbox for prototyping Obsidian plugin UI with Arrow.js against Obsidian's real styling.",
 	"license": "MIT",
-	"packageManager": "pnpm@10.14.0",
 	"scripts": {
 		"dev": "vite",
 		"build": "vite build",
@@ -12,21 +12,20 @@
 		"typecheck": "tsc -p tsconfig.json --noEmit",
 		"pull-css": "node scripts/pull-app-css.mjs",
 		"port:css": "node scripts/port-css.mjs",
-		"create:sync": "node create-obsidian-arrow/scripts/sync-template.mjs",
-		"create:component": "node scripts/create-component.mjs",
-		"create:view": "node scripts/create-view.mjs",
+		"create:component": "oasbox generate component",
+		"create:view": "oasbox generate view",
 		"lint": "biome check .",
 		"format": "biome check --write .",
 		"test": "node --experimental-strip-types --test test/*.test.mjs",
 		"check:css": "node scripts/check-orphaned-css.mjs",
 		"check:scope": "node scripts/check-scope-classes.mjs",
 		"check:imports": "node scripts/check-view-imports.mjs",
-		"check": "biome check . && pnpm typecheck && pnpm test && pnpm check:css && pnpm check:scope && pnpm check:imports",
-		"ci": "biome ci . && pnpm typecheck && pnpm test && pnpm check:css && pnpm check:scope && pnpm check:imports && pnpm build",
+		"check": "biome check . && tsc -p tsconfig.json --noEmit && node --experimental-strip-types --test test/*.test.mjs && node scripts/check-orphaned-css.mjs && node scripts/check-scope-classes.mjs && node scripts/check-view-imports.mjs",
+		"ci": "biome ci . && tsc -p tsconfig.json --noEmit && node --experimental-strip-types --test test/*.test.mjs && node scripts/check-orphaned-css.mjs && node scripts/check-scope-classes.mjs && node scripts/check-view-imports.mjs && vite build",
+		"prepare": "husky",
 		"skills:install": "node scripts/install-skills.mjs --force",
 		"skills:update": "node scripts/install-skills.mjs --update",
-		"postinstall": "node scripts/install-skills.mjs",
-		"prepare": "husky"
+		"postinstall": "node scripts/install-skills.mjs"
 	},
 	"lint-staged": {
 		"*.{ts,mjs,js,json,jsonc}": "biome check --write --no-errors-on-unmatched"
@@ -42,14 +41,16 @@
 	"devDependencies": {
 		"@biomejs/biome": "^1.9.4",
 		"@types/node": "^22.16.5",
-		"husky": "^9.1.6",
-		"lint-staged": "^15.2.10",
+		"oasbox": "^0.1.0",
 		"postcss": "^8.5.16",
 		"typescript": "^5.9.3",
-		"vite": "^8.0.0"
+		"vite": "^8.0.0",
+		"husky": "^9.1.6",
+		"lint-staged": "^15.2.10"
 	},
 	"pnpm": {
-		"onlyBuiltDependencies": ["@biomejs/biome"]
-	},
-	"version": "0.1.0"
+		"onlyBuiltDependencies": [
+			"@biomejs/biome"
+		]
+	}
 }

package/template/src/components/DiffViewer/DiffViewer.css

@@ -0,0 +1,41 @@
+/* DiffViewer — CodeMirror 6 MergeView container. Portable. */
+.oas-diff-viewer {
+	height: 480px;
+	overflow: hidden;
+	border: 1px solid var(--background-modifier-border);
+	border-radius: var(--radius-m);
+	font-family: var(--font-monospace);
+	font-size: var(--font-ui-small);
+}
+
+.oas-diff-viewer .cm-mergeView {
+	height: 100%;
+}
+
+.oas-diff-viewer .cm-editor {
+	height: 100%;
+	background: var(--background-primary);
+	color: var(--text-normal);
+}
+
+.oas-diff-viewer .cm-scroller {
+	overflow: auto;
+	font-family: var(--font-monospace);
+}
+
+.oas-diff-viewer .cm-mergeViewEditor {
+	border-right: 1px solid var(--background-modifier-border);
+}
+
+.oas-diff-viewer .cm-mergeViewEditor:last-child {
+	border-right: none;
+}
+
+.oas-diff-viewer .cm-deletedChunk {
+	background: color-mix(in srgb, var(--color-red) 15%, transparent);
+}
+
+.oas-diff-viewer .cm-insertedChunk,
+.oas-diff-viewer .cm-changedLine {
+	background: color-mix(in srgb, var(--color-green) 12%, transparent);
+}

package/template/src/components/DiffViewer/DiffViewer.ts

@@ -0,0 +1,55 @@
+import { html } from "@arrow-js/core";
+import type { ArrowTemplate } from "@arrow-js/core";
+import { markdown } from "@codemirror/lang-markdown";
+import { MergeView } from "@codemirror/merge";
+import { EditorState } from "@codemirror/state";
+import "./DiffViewer.css";
+
+export interface DiffViewerOptions {
+	original: string;
+	modified: string;
+	/** Which side shows original (a) and which shows modified (b). Default: a-b */
+	orientation?: "a-b" | "b-a";
+}
+
+/**
+ * CodeMirror 6 MergeView — side-by-side diff using the same CM6 engine as
+ * Obsidian's editor. Obsidian's app.css styles .cm-* classes automatically,
+ * so this looks native without additional theming.
+ *
+ * Arrow.js 1.x only handles ArrowTemplate/component/array in expressions —
+ * raw Node insertion isn't supported. We render a placeholder via html`` and
+ * mount the CM6 MergeView into it after Arrow commits the DOM.
+ *
+ * requestAnimationFrame (not queueMicrotask) is required here: CSS flex layout
+ * is calculated by the rendering engine, not during microtask execution. CM6
+ * reads the container's offsetHeight at mount time — if flex hasn't painted yet
+ * it gets 0, and the editor renders at a fixed fallback height instead of
+ * filling its container.
+ */
+export function DiffViewer(options: DiffViewerOptions): ArrowTemplate {
+	// Unique attribute so we can locate the container after Arrow mounts it.
+	const key = Math.random().toString(36).slice(2, 10);
+
+	requestAnimationFrame(() => {
+		const container = document.querySelector(`[data-diff="${key}"]`);
+		if (!container) return;
+		container.removeAttribute("data-diff");
+		new MergeView({
+			a: {
+				doc: options.original,
+				extensions: [markdown(), EditorState.readOnly.of(true)],
+			},
+			b: {
+				doc: options.modified,
+				extensions: [markdown(), EditorState.readOnly.of(true)],
+			},
+			parent: container,
+			orientation: options.orientation ?? "a-b",
+			highlightChanges: true,
+			collapseUnchanged: { margin: 3, minSize: 4 },
+		});
+	});
+
+	return html`<div class="oas-diff-viewer" data-diff="${key}"></div>`;
+}