create-bridgething 0.10.0 → 0.12.0

package/README.md

@@ -1,22 +1,26 @@
 # create-bridgething
 
-Scaffold a new [bridgething](https://github.com/JoeyEamigh/bridgething) webapp, a
-single-page app that runs on the kiosk chromium of a Spotify Car Thing and talks
-to the on-device daemon. The template ships React + Vite + Tailwind v4 with
-[`@bridgething/client`](https://www.npmjs.com/package/@bridgething/client)
-preinstalled.
+Scaffold a [bridgething](https://github.com/JoeyEamigh/bridgething) webapp for
+the Spotify Car Thing: React, Vite, Tailwind v4, and
+[`@bridgething/client`](https://www.npmjs.com/package/@bridgething/client).
 
 ```sh
 bun create bridgething my-app
 ```
 
-```sh
-npm create bridgething@latest my-app
-```
+| flag           | what you get                                  |
+| -------------- | --------------------------------------------- |
+| `--launcher`   | A replacement home screen                     |
+| `--overlay`    | System UI drawn over every webapp             |
+| `--extension`  | A desktop-side Deno process beside the webapp |
+| `--no-install` | Skip `bun install`                            |
+| `--no-git`     | Skip `git init`                               |
+
+`--extension` combines with `--launcher`, `--overlay`, or a plain webapp.
 
-The generated project includes `bun run push` to deploy the built webapp to a
-connected Car Thing, `bun run share` to share it with the community, and
-`bun run update` to bring the connected device to the latest bridgething release.
+The project ships `bun run dev`, `build`, `push` (install on a connected Car
+Thing), `share` (zip for the store), and `update` (bring the device to the
+latest release).
 
-- Full docs: <https://bridgething.com/docs>
+- Docs: <https://bridgething.com/docs>
 - Source: <https://github.com/JoeyEamigh/bridgething>

package/dist/index.mjs

@@ -7,6 +7,29 @@ import { v7 } from "uuid";
 //#region src/index.ts
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATE_DIR = resolve(__dirname, "..", "template");
+const EXTENSION = {
+	dir: "template-extension",
+	manifest: {
+		extension: {
+			entry: "extension/desktop.mjs",
+			permissions: ["all"],
+			api: 1
+		},
+		config: [{
+			type: "string",
+			data: {
+				key: "greeting",
+				label: "Greeting the extension sends on connect"
+			}
+		}]
+	},
+	dependencies: { "@bridgething/extension": `^${JSON.parse(readFileSync(resolve(__dirname, "..", "package.json"), "utf8")).version}` },
+	devDependencies: {
+		deno: "2.9.6",
+		esbuild: "^0.28.2"
+	},
+	summary: "native extension (a desktop-side Deno process)"
+};
 const VARIANTS = {
 	app: { summary: "webapp" },
 	launcher: {
@@ -32,10 +55,12 @@ function parseArgs(argv) {
 	let install = true;
 	let git = true;
 	let variant = "app";
+	let extension = false;
 	for (const arg of argv) if (arg === "--no-install") install = false;
 	else if (arg === "--no-git") git = false;
 	else if (arg === "--launcher") variant = "launcher";
 	else if (arg === "--overlay") variant = "overlay";
+	else if (arg === "--extension") extension = true;
 	else if (arg === "--help" || arg === "-h") {
 		printHelp();
 		process.exit(0);
@@ -52,11 +77,12 @@ function parseArgs(argv) {
 		target: positional[0],
 		install,
 		git,
-		variant
+		variant,
+		extension
 	};
 }
 function printHelp() {
-	console.log(`Usage: create-bridgething <target-dir> [--launcher | --overlay] [--no-install] [--no-git]
+	console.log(`Usage: create-bridgething <target-dir> [--launcher | --overlay] [--extension] [--no-install] [--no-git]
 
 Scaffold a new bridgething webapp at <target-dir>.
 
@@ -67,6 +93,10 @@ Variants:
   --overlay     A system overlay. Ships an 'overlay.js' the daemon injects
                 into every webapp, replacing the built-in one.
 
+Add-ons (combine with any variant):
+  --extension   A native extension: a Deno process the desktop app runs
+                alongside the webapp, with host access the manifest declares.
+
 Options:
   --no-install  Skip 'bun install' after copying.
   --no-git      Skip 'git init' after copying.
@@ -79,23 +109,48 @@ function patchJson(path, patch) {
 		...patch
 	}, null, 2)}\n`);
 }
+function patchPackage(target, patch) {
+	const path = join(target, "package.json");
+	const pkg = JSON.parse(readFileSync(path, "utf8"));
+	patchJson(path, {
+		scripts: {
+			...pkg.scripts,
+			...patch.scripts
+		},
+		dependencies: sortKeys({
+			...pkg.dependencies,
+			...patch.dependencies
+		}),
+		devDependencies: sortKeys({
+			...pkg.devDependencies,
+			...patch.devDependencies
+		})
+	});
+}
+function sortKeys(record) {
+	return Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
+}
+function overlayTemplate(target, dir, subs) {
+	copyTemplate(resolve(__dirname, "..", dir), target, subs);
+	const appendPath = join(target, "_claude_append.md");
+	if (!existsSync(appendPath)) return;
+	const claudePath = join(target, "CLAUDE.md");
+	writeFileSync(claudePath, `${readFileSync(claudePath, "utf8").trimEnd()}\n\n${readFileSync(appendPath, "utf8")}`);
+	rmSync(appendPath);
+}
 function applyVariant(target, variant, subs) {
 	const spec = VARIANTS[variant];
-	if (spec.dir) copyTemplate(resolve(__dirname, "..", spec.dir), target, subs);
-	const appendPath = join(target, "_claude_append.md");
-	if (existsSync(appendPath)) {
-		const claudePath = join(target, "CLAUDE.md");
-		writeFileSync(claudePath, readFileSync(claudePath, "utf8") + readFileSync(appendPath, "utf8"));
-		rmSync(appendPath);
-	}
+	if (spec.dir) overlayTemplate(target, spec.dir, subs);
 	if (spec.manifest) patchJson(join(target, "public", "manifest.json"), spec.manifest);
-	if (spec.scripts) {
-		const pkgPath = join(target, "package.json");
-		patchJson(pkgPath, { scripts: {
-			...JSON.parse(readFileSync(pkgPath, "utf8")).scripts,
-			...spec.scripts
-		} });
-	}
+	if (spec.scripts) patchPackage(target, { scripts: spec.scripts });
+}
+function applyExtension(target, subs) {
+	overlayTemplate(target, EXTENSION.dir, subs);
+	patchJson(join(target, "public", "manifest.json"), EXTENSION.manifest);
+	patchPackage(target, {
+		dependencies: EXTENSION.dependencies,
+		devDependencies: EXTENSION.devDependencies
+	});
 }
 const BINARY_EXT = new Set([
 	".ttf",
@@ -168,7 +223,9 @@ function main() {
 	console.log(`scaffolding ${projectName} (${webappUuid}) in ${target}`);
 	copyTemplate(TEMPLATE_DIR, target, subs);
 	applyVariant(target, args.variant, subs);
-	console.log(`  ✓ template copied (${VARIANTS[args.variant].summary})`);
+	if (args.extension) applyExtension(target, subs);
+	const shape = args.extension ? `${VARIANTS[args.variant].summary} + ${EXTENSION.summary}` : VARIANTS[args.variant].summary;
+	console.log(`  ✓ template copied (${shape})`);
 	linkAgentAliases(target);
 	console.log("  ✓ agent guides linked (CLAUDE.md, AGENTS.md, /bridgething skill)");
 	if (args.git) if (run("git", ["init", "--quiet"], target)) console.log("  ✓ git initialized");
@@ -182,7 +239,8 @@ function main() {
 Done! Next steps:
 
   cd ${args.target}
-${args.install ? "" : "  bun install\n"}  bun run dev          # local dev server (http://localhost:5173/)
+${args.install ? "" : "  bun install\n"}  bun run dev          # local dev server (http://localhost:5173/) against the connected Car Thing
+  bun run dev:device   # the same server on the Car Thing's own screen, hot reload included
 
 Open this folder with your coding agent (Claude Code, Codex, opencode, ...).
 It reads CLAUDE.md / AGENTS.md and the /bridgething skill in .claude/skills
@@ -193,14 +251,21 @@ driving the app, and installing and sharing it.
   bun run push <addr>  # build + install onto a connected Car Thing (default bridgething.local)
   bun run share        # build first, then zip dist/ to hand to friends
   bun run update       # bring the connected Car Thing to the latest bridgething release
-${args.variant === "app" ? "" : `
+${args.extension ? `
+'extension/main.ts' is the desktop-side half: a Deno process the bridgething
+desktop app runs alongside this webapp, with the host access 'manifest.json'
+declares. 'bun run dev' and 'bun run dev:device' also run it, rebuilt on every
+save and wired to the connected Car Thing, so both halves iterate together.
+'bun run build' bundles it to dist/extension/desktop.mjs.
+` : ""}${args.variant === "app" ? "" : `
 'bun run push' also claims the device's ${args.variant} slot, so this is live the
 moment it lands. 'bun run push --release' hands the slot back to the built-in
 ${args.variant === "launcher" ? "hub" : "overlay"}, which is how you recover if a build of this wedges the screen.
 The companion phone app can do the same thing.
 `}
-The starter App connects to ws://127.0.0.1:8891/ on the device, and to
-ws://<device-ip>:8891/ in dev when you set VITE_BRIDGETHING_URL.
+The starter App connects to the daemon through daemonUrl() in src/daemon.ts: the
+local daemon on the device, and the dev server's proxy to the Car Thing over USB
+under bun run dev (SUPERBIRD_HOST picks another device).
 `);
 }
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bridgething",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "Scaffold a new bridgething webapp (React + Vite + Tailwind v4)",
   "license": "MIT",
@@ -25,18 +25,24 @@
   "files": [
     "dist",
     "template",
+    "template-extension",
     "template-launcher",
     "template-overlay"
   ],
   "scripts": {
-    "prebuild": "bun scripts/sync-push.ts",
+    "prebuild": "bun scripts/sync-shared.ts",
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
   },
   "devDependencies": {
+    "@bridgething/extension": "0.12.0",
+    "@msgpack/msgpack": "^3.1.3",
+    "@types/bun": "^1.4.0",
     "@types/node": "^26.1.1",
     "@types/uuid": "^11.0.0",
+    "esbuild": "^0.28.2",
     "tsdown": "^0.21.10"
   },
   "peerDependencies": {

package/template/CLAUDE.md

@@ -1,95 +1,71 @@
 # Building this bridgething webapp
 
-You are helping build a **bridgething webapp**: a single-page web UI for the
-Spotify Car Thing. It runs full-screen in a chromium kiosk on the device and
-talks to the on-device daemon over a local WebSocket using `@bridgething/client`.
-This file is always loaded; it holds the constraints. The `/bridgething` skill
-goes deep on the how-to: the client API, running and driving the app, and
-shipping it.
-
-## The device you are targeting
-
-- **Screen: 800x480, landscape.** Fixed. Design for exactly this. The window
-  never resizes; there is no responsive breakpoint to chase.
-- **One page.** The kiosk shows exactly one webapp at a time. In-app views are
-  fine, but there are no browser tabs, popups, or second windows.
-- **Physical controls arrive as ordinary browser events.** Listen with a
-  `keydown` handler and a `wheel` handler on `window`.
-  - Preset buttons **1 2 3 4** -> `keydown` key `"1"` `"2"` `"3"` `"4"`.
-  - **Mode** button -> `keydown` key `"m"`. (Pressing it 5 times fast is a
-    system gesture that jumps back to the launcher, so do not build anything
-    that depends on rapid repeated `m`.)
-  - **Back** button -> `keydown` key `"Escape"`.
-  - **Rotary wheel** -> horizontal scroll: `wheel` events with `deltaX`. This is
-    the primary way users move through lists; make horizontal wheel scroll work.
-  - **Touch** works normally (pointer/touch events).
-- **No keyboard, no mouse.** Those five controls plus touch are the whole input
-  surface. There is no text entry unless you build an on-screen one.
-
-## The SDK: `@bridgething/client`
+A bridgething webapp is one page running full-screen in the chromium kiosk on a
+Spotify Car Thing. It reaches the on-device daemon through `@bridgething/client`.
+
+## The device
+
+The screen is 800x480, landscape, and never resizes. The kiosk shows one webapp,
+so build in-app views rather than tabs or windows. Add an on-screen keyboard if
+the app needs text entry.
+
+Listen with a `keydown` handler and a `wheel` handler on `window`.
+
+| Control      | Event                                 |
+| ------------ | ------------------------------------- |
+| Preset 1-4   | `keydown` key `"1"` `"2"` `"3"` `"4"` |
+| Mode         | `keydown` key `"m"`                   |
+| Back         | `keydown` key `"Escape"`              |
+| Rotary wheel | `wheel` with horizontal `deltaX`      |
+| Touch        | pointer and touch events              |
+
+Make horizontal wheel scroll move through the main list. Five fast presses of
+Mode returns to the launcher.
+
+## The client
 
 ```ts
 import { BridgethingClient } from '@bridgething/client';
-const client = new BridgethingClient(); // auto-connects to the daemon, auto-reconnects
+import { useMemo } from 'react';
+
+import { daemonUrl } from './daemon';
+
+const client = useMemo(() => new BridgethingClient({ url: daemonUrl() }), []);
 ```
 
-Construct it once and reuse it. It defaults to the on-device daemon; in dev you
-point it at your device with `VITE_BRIDGETHING_URL` (the starter `App.tsx`
-already does this). Do not hardcode a WebSocket URL.
-
-It is fully typed with a doc comment on every surface, method, and field. Read
-those declarations directly - you have no editor to hover in:
-
-- `node_modules/@bridgething/client/dist/dispatch.generated.d.ts` - every
-  `client.<surface>.<method>` and event, with docs.
-- `node_modules/@bridgething/lib/dist/bindings/*.d.ts` - the payload and reply
-  types (`PlayerState`, `MediaItem`, ...), with per-field docs.
-
-18 surfaces: `player asset config store capabilities library audio notifications
-phone geo net hardware bluetooth system time voice webapp forward`. Each method
-is one of three shapes:
-
-- **events**: `client.<s>.onXxx(handler)` returns an unsubscribe fn; or
-  `client.<s>.subscribe({ onXxx, ... })`.
-- **requests**: `await client.<s>.xxx(req)` returns `{ ok: true, response }` or
-  `{ ok: false, kind, error }` - always check `.ok`.
-- **commands**: `await client.<s>.xxx(payload)` returns `void` (fire-and-forget).
-
-Now-playing and library data come from the **connected phone's** Spotify. Assume
-a phone may not be connected: handle the empty/disconnected state gracefully (the
-starter shows a "connect a phone" placeholder). Fetch artwork by opaque asset id
-via `client.asset.get`; never build image URLs by hand.
-
-Run `/bridgething` for the cookbook, the dev loop, and shipping; grep the `.d.ts`
-files for a specific method or type.
-
-## `manifest.json` (in `public/`)
-
-- `id` - baked in at scaffold, unique to this project. **Never change it.**
-- `name`, `version`, `description`, `icon` - cosmetic / store metadata.
-- `config` - user-tunable settings (each becomes a `client.config` value).
-- `permissions` - capabilities you need (e.g. `net.fetch`, `net.proxy`, `geo`).
-- `art: { heroPx, thumbPx }` - the pixel sizes you want artwork delivered at.
-- `settings` - one self-contained HTML file (built from `settings/`) the
-  companion phone app renders as this webapp's settings page. It talks to the
-  companion over `@bridgething/client/settings`, not the on-device SDK. Capped
-  at 1 MiB at install. It loads from a `file://` origin: websocket APIs work
-  from it, but plain HTTP fetch is CORS-gated (`Origin: null`) - see the
-  network caveat in the `/bridgething` skill's sdk reference.
+Construct it once and reuse it. It connects and reconnects on its own. Call
+`daemonUrl()` instead of a literal `ws://` address.
 
-## Workflow
+Now-playing and library data come from the phone's Spotify, so render a
+placeholder when no phone is connected. Fetch artwork with `client.asset.get`
+using the opaque id on the track.
+
+Every surface: `player asset config store doc capabilities library audio
+notifications phone peer geo net hardware bluetooth system time voice lyrics
+webapp forward`. Each method is an event, a request, or a command.
+
+Methods, types, and examples: `.claude/skills/bridgething/reference/sdk.md`.
 
-- `bun run dev` - vite dev server. Iterate here. Use `/bridgething` for the loop
-  of seeing the screen and pressing the buttons.
-- `bun run build` - production bundle into `dist/`.
-- `bun run push` - build + install onto a connected Car Thing (see `/bridgething`).
-- `bun run update` - update the connected device to the latest bridgething release
-  (device firmware, not your webapp; see `/bridgething`).
+## `public/manifest.json`
+
+- `id` identifies this webapp on the device. Keep it.
+- `version` tells builds apart. Raise it before sharing an update.
+- `config` declares the settings the companion app edits and `client.config`
+  reads.
+- `permissions` grants `geo` and `net.proxy`.
+- `art.heroPx` and `art.thumbPx` are the sizes artwork arrives at.
+- `settings` names the page built from `settings/`, capped at 1 MiB. It talks to
+  the companion app through `@bridgething/client/settings`.
+
+## Workflow
 
-## Do not
+- `bun run dev` serves at `http://localhost:5173/` against the connected Car
+  Thing.
+- `bun run dev:device` shows that server on the device's own screen.
+- `bun run build` writes `dist/`.
+- `bun run push` builds and installs onto the connected device.
+- `bun run share` zips `dist/`.
+- `bun run update` brings the device to the latest bridgething release.
 
-- Fight the 800x480 viewport or assume any other size.
-- Hardcode `ws://...`; use the SDK default + `VITE_BRIDGETHING_URL`.
-- Assume a phone is always connected.
-- Build image URLs by hand; fetch by opaque asset id.
-- Rely on rapid repeated `m` (system launcher gesture).
+Running and driving the app: `.claude/skills/bridgething/reference/develop.md`.
+Push, zip, update: `.claude/skills/bridgething/reference/ship.md`.

package/template/README.md

@@ -1,14 +1,13 @@
 # **PROJECT_NAME**
 
-A bridgething webapp scaffolded with `create-bridgething`.
+A bridgething webapp scaffolded with `create-bridgething`. It runs full-screen in
+the chromium kiosk on a Spotify Car Thing and talks to the on-device daemon
+through [`@bridgething/client`](https://github.com/JoeyEamigh/bridgething).
 
-Stack: React 19 + Vite + Tailwind v4 + TypeScript strict, with
-[`@bridgething/client`](https://github.com/JoeyEamigh/bridgething) preinstalled.
+Stack: React 19, Vite, Tailwind v4, TypeScript strict.
 
-## Building with an agent
-
-Open this folder with your coding agent (Claude Code, Codex, opencode, ...). It
-reads `CLAUDE.md` / `AGENTS.md` and the `/bridgething` skill.
+Open this folder with your coding agent. It reads `CLAUDE.md` or `AGENTS.md` and
+the `/bridgething` skill.
 
 ## Develop
 
@@ -17,54 +16,42 @@ bun install
 bun run dev
 ```
 
-Opens at http://localhost:5173/. The starter `App.tsx` connects to
-`ws://<host>/` (the daemon's local WebSocket on port 8891 of the device
-itself). To dev against a remote device, set:
+Vite serves at http://localhost:5173/ with hot reload, against the daemon on the
+Car Thing plugged in over USB. Set `SUPERBIRD_HOST` to target another device, or
+`BRIDGETHING_DAEMON_URL` to reach a daemon elsewhere.
 
 ```bash
-VITE_BRIDGETHING_URL=ws://<device-ip>:8891/ bun run dev
+bun run dev:device
 ```
 
-## Push to a device
+The same server, shown on the Car Thing's own screen, hot reload included.
+Ctrl-C hands the screen back to the installed build.
 
-```bash
-bun run push
-```
+When the project ships an extension (`extension/main.ts`), both commands bundle
+it on every save and run it under Deno with the permissions the manifest
+declares.
 
-`push` builds `dist/`, rsyncs it into `/var/bridgething/webapps/<manifest-id>/`
-on the Car Thing, and switches the kiosk to your app. Pass an IP address to target
-something other than `bridgething.local` over USB.
-
-## Share
+## Push, share, update
 
 ```bash
+bun run push     # build, copy to the Car Thing, switch the kiosk to it
 bun run build
-bun run share
-```
-
-`share` writes `<name>-<version>.zip` from `dist/`. Anyone with a bridgething Car
-Thing installs it from the app.
-
-## Update the device
-
-```bash
-bun run update
+bun run share    # write <name>-<version>.zip from dist/
+bun run update   # bring the device to the latest bridgething release
 ```
 
-`update` runs [`@bridgething/updater`](https://www.npmjs.com/package/@bridgething/updater)
-to bring the connected Car Thing to the latest bridgething release. Multiple devices: `bun run update -- --host ws://bridgething-<serial>.local:8892/`.
+`push` targets `bridgething.local` over USB; pass a host or IP address for
+another device. Anyone with a bridgething Car Thing installs the zip from the
+companion app. For one device out of several,
+`bun run update -- --host ws://bridgething-<serial>.local:8892/`.
 
 ## Layout
 
-- `src/App.tsx` - starter UI: subscribes to `client.player.onSnapshot`,
-  fetches artwork via `client.asset.get`, exposes transport controls.
-- `src/index.css` - `@import "tailwindcss";`.
-- `vite.config.ts` - vite + tailwind plugin, `es2022` target.
-- `index.html` - 800x480 viewport, no overscroll, no tap highlight.
-- `settings/` - the companion-side settings page (preact), built by
-  `vite.settings.config.ts` into a single self-contained `dist/settings.html`.
-  It reads and writes settings over `@bridgething/client/settings`.
-
-`bun run build` runs both configs: the main app into `dist/`, then the settings
-page as `dist/settings.html`. `manifest.json`'s `settings` field points the
-companion at it.
+- `src/App.tsx` subscribes to `client.player.onSnapshot`, fetches artwork through
+  `client.asset.get`, and draws transport controls.
+- `src/daemon.ts` returns the daemon URL.
+- `public/manifest.json` carries the webapp id, version, config schema, and
+  permissions.
+- `settings/` is the settings page the companion app renders, built to
+  `dist/settings.html`.
+- `index.html` and `vite.config.ts` fix the 800x480 viewport and the build target.

package/template/_claude/skills/bridgething/SKILL.md

@@ -1,25 +1,20 @@
 ---
 name: bridgething
-description: Build, run, and ship a bridgething webapp for the Spotify Car Thing. Covers @bridgething/client (the SDK a webapp uses to reach the on-device daemon - now-playing, artwork, storage, settings, networking, all 18 surfaces), the loop for running the app and driving its 800x480 screen and physical controls from a browser you control, and installing the built app onto a device or packaging it as a shareable zip. Use whenever calling the daemon, running or previewing the app, pressing its controls, or pushing it to hardware.
+description: Build, run, and ship a bridgething webapp for the Spotify Car Thing. Use for @bridgething/client calls (now-playing, transport, artwork, storage, user settings, networking, every surface), running the dev server and driving the 800x480 screen and its physical controls, pushing the built app to a device or packaging a shareable zip, and writing the desktop-side Deno extension a webapp can ship.
 ---
 
 # Building a bridgething webapp
 
-A bridgething webapp is a single-page React UI that runs full-screen in the
-device's chromium kiosk and reaches the on-device daemon through one typed
-client. You build it against a browser on your own machine and push it to real
-hardware only for final checks.
-
-Three jobs. Read the reference file for the one in front of you:
-
-- **Call the daemon** - now-playing, transport, artwork, storage, settings,
-  networking, and the full 18-surface index: [reference/sdk.md](reference/sdk.md)
-- **Run and drive the app** - dev server, screenshot the 800x480 screen, press
-  the physical controls (locally, then over CDP on the device):
+- Calling the daemon, from now-playing to networking, plus every surface the SDK
+  ships: [reference/sdk.md](reference/sdk.md)
+- Running the app, screenshotting the 800x480 screen, and pressing the physical
+  controls locally and over CDP on the device:
   [reference/develop.md](reference/develop.md)
-- **Install and share** - build, push onto a connected Car Thing, package a zip
-  anyone can install, and keep the device on the latest bridgething release:
-  [reference/ship.md](reference/ship.md)
+- Installing onto a connected Car Thing, packaging a zip, and updating the
+  device: [reference/ship.md](reference/ship.md)
+- The desktop-side Deno extension, its `ctx` contract, and its permission model,
+  when the project has an `extension/` directory:
+  [reference/extension.md](reference/extension.md)
 
-The device shape, the control-to-event mapping, and the hard constraints live in
-CLAUDE.md, which is always loaded. This skill is the how-to on top of it.
+CLAUDE.md holds the device shape, the control-to-event mapping, and the manifest
+fields.