create-obsidian-arrow 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-obsidian-arrow",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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.

package/template/README.md

@@ -42,8 +42,9 @@ 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. 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
 

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/src/router/routeToPage.ts

@@ -1,7 +1,7 @@
 import { html } from "@arrow-js/core";
 import type { ArrowExpression } from "@arrow-js/core";
-import { ExamplesIndex } from "../examples/ExamplesIndex";
-import { examples, findExample } from "../examples/registry";
+import { findExample } from "../examples/registry";
+import { Home } from "../sandbox/home";
 
 /**
  * Single route resolver, shared by every entry point. Returns the page status,
@@ -24,8 +24,8 @@ export function routeToPage(url: string): Page {
 	if (pathname === "/" || pathname === "") {
 		return {
 			status: 200,
-			title: `Examples · ${APP_NAME}`,
-			view: ExamplesIndex(examples),
+			title: APP_NAME,
+			view: Home(),
 		};
 	}
 

package/template/src/sandbox/home.ts

@@ -0,0 +1,106 @@
+import { component, html, reactive } from "@arrow-js/core";
+import type { ArrowTemplate } from "@arrow-js/core";
+import { ExamplesIndex } from "../examples/ExamplesIndex";
+import { examples } from "../examples/registry";
+import { layoutState } from "./layout";
+import { themeState } from "./theme";
+
+/**
+ * Sandbox landing page at "/": a readiness check + getting-started commands +
+ * the examples list. Sandbox chrome — does not port to a plugin.
+ *
+ * The readiness probe catches the #1 fresh-machine gotcha: running `pnpm dev`
+ * before `pnpm pull-css` leaves app.css unloaded, so every `var(--…)` token is
+ * empty. We detect that by reading the computed value of a known token.
+ */
+const probe = reactive({ tick: 0 });
+
+function stylingLoaded(): boolean {
+	const generation = probe.tick; // reactive dependency; Re-check bumps it
+	const style = getComputedStyle(document.body);
+	return (
+		generation >= 0 &&
+		style.getPropertyValue("--background-primary").trim() !== "" &&
+		style.getPropertyValue("--text-accent").trim() !== ""
+	);
+}
+
+function recheck(): void {
+	probe.tick++;
+}
+
+const GETTING_STARTED = [
+	{ cmd: "pnpm pull-css", note: "extract Obsidian's app.css — run once (macOS auto-detect)" },
+	{ cmd: "pnpm dev", note: "this dev server (Vite + HMR)" },
+	{ cmd: "pnpm skills:install --yes", note: "install the agent skills from the published repo" },
+	{ cmd: "pnpm run ci", note: "biome + typecheck + tests + build" },
+];
+
+export const Home = component((): ArrowTemplate => {
+	// Re-probe shortly after mount, in case app.css finished loading after the
+	// first paint (stylesheets load async).
+	setTimeout(recheck, 250);
+
+	return html`
+		<div class="oas-settings">
+			<div class="setting-item setting-item-heading">
+				<div class="setting-item-info">
+					<div class="setting-item-name">Obsidian Arrow Sandbox</div>
+					<div class="setting-item-description">
+						Prototype Obsidian plugin UI with Arrow.js against Obsidian's real styling.
+					</div>
+				</div>
+			</div>
+
+			<div class="setting-item">
+				<div class="setting-item-info">
+					<div class="setting-item-name">Obsidian styling</div>
+					<div class="setting-item-description">
+						${() =>
+							stylingLoaded()
+								? "app.css loaded — tokens resolve."
+								: "Not loaded — run `pnpm pull-css`, then Re-check."}
+					</div>
+				</div>
+				<div class="setting-item-control">
+					<span
+						style="${() =>
+							`color: ${stylingLoaded() ? "var(--text-success)" : "var(--text-error)"}; font-weight: var(--font-semibold);`}"
+					>${() => (stylingLoaded() ? "READY" : "MISSING")}</span>
+					<button class="oas-recheck" @click="${recheck}">Re-check</button>
+				</div>
+			</div>
+
+			<div class="setting-item">
+				<div class="setting-item-info">
+					<div class="setting-item-name">Theme / panel</div>
+					<div class="setting-item-description">
+						${() => `${themeState.theme} · ${layoutState.width}px`}
+					</div>
+				</div>
+			</div>
+
+			<div class="setting-item setting-item-heading">
+				<div class="setting-item-info">
+					<div class="setting-item-name">Getting started</div>
+					<div class="setting-item-description">
+						See AGENTS.md + docs/ for the full flow; agent prompts in docs/prompts/.
+					</div>
+				</div>
+			</div>
+			${GETTING_STARTED.map((step) =>
+				html`
+						<div class="setting-item">
+							<div class="setting-item-info">
+								<div class="setting-item-name" style="font-family: var(--font-monospace);">
+									${step.cmd}
+								</div>
+								<div class="setting-item-description">${step.note}</div>
+							</div>
+						</div>
+					`.key(step.cmd)
+			)}
+		</div>
+		${ExamplesIndex(examples)}
+	`;
+});

package/template/src/sandbox/sandbox.css

@@ -109,6 +109,11 @@ body {
 	align-items: center;
 }
 
+.oas-frame .setting-item-control button.oas-recheck {
+	margin-left: var(--size-4-2);
+	font-size: var(--font-ui-smaller);
+}
+
 /* Drag-to-resize handle on the pane's right edge (Obsidian-like). */
 .oas-frame .oas-resize-handle {
 	position: absolute;