chore(root): align repo-native dev commands

Author: Oba-One

.dev-surfaces/skills/dev-surface/SKILL.md

@@ -1,35 +1,46 @@
 ---
-name: dev-surface
-description: Use when working in Coop and needing to start, reuse, open, inspect, validate, or clean up this repo's local development surfaces through the shared dev-surfaces workbench.
+name: coop-dev-surface
+description: Use when working in Coop and needing the local app, receiver PWA, docs, API/signaling server, or extension watcher.
 ---
 
 # Coop Dev Surface
 
-Use the global workbench CLI instead of starting duplicate servers manually:
+Inside this repo, use the repo-native command:
 
 ```sh
-dev-surfaces status
-dev-surfaces up coop
-dev-surfaces open coop
-dev-surfaces logs coop:<surface>
-dev-surfaces down coop
+bun install
+# configure repo env if needed
+bun run dev
 ```
 
-Stable fallback path: `/Users/afo/Code/dev-surfaces/bin/dev-surfaces.js`.
+`bun run dev` runs `scripts/dev.ts`. It starts the app, API/signaling server, docs, extension watcher, optional Cloudflare tunnel, and a dev browser profile when available. It writes runtime state to `packages/app/public/__coop_dev__/state.json`, streams logs, and cleans up child processes on Ctrl-C.
 
-## Surfaces
+Expected ports:
 
-- `app`: app / receiver PWA on `3101`
-- `docs`: docs on `3102`
-- `api`: API / signaling on `3103`
-- `extension`: extension dev server, if bound on `3104`
+- `3101`: app / receiver PWA
+- `3102`: docs
+- `3103`: API / signaling
+- `3104`: extension dev server, when bound
 
-## Validation Notes
+Useful native commands:
 
-- Default real-browser proof should use Brave or another Chromium-family browser on this machine.
-- Keep receiver PWA and signaling URLs aligned when launching the extension surface.
-- `app` depends on `api`, and `extension` depends on both, so the workbench brings signaling up before UI review surfaces that need it.
-- Docs require Node 20+; the repo scripts prepend `mise where node@22` before running Docusaurus so agent shells do not fall back to system Node 18.
-- After changing local port docs or dev scripts, run `dev-surfaces doctor`.
+```sh
+bun run dev
+bun run dev:stop
+bun run dev:app
+bun run dev:api
+bun run dev:docs
+bun run dev:extension
+```
+
+For cross-repo orchestration from anywhere, use the global workbench:
+
+```sh
+dev launch coop
+dev launch coop:app
+dev status coop
+dev health coop
+dev stop coop
+```
 
-Never kill unknown port occupants. If a port is busy and not owned by dev-surfaces, report the PID/command and ask for direction.
+Do not call `.dev-surfaces/run.mjs`; this repo should not have that wrapper.

AGENTS.md

@@ -8,10 +8,11 @@ For full details, see [`CLAUDE.md`](./CLAUDE.md).
 
 ```bash
 bun install                  # Install dependencies
-bun dev                      # Start app + extension (concurrent)
-bun dev:app                  # Start app only
-bun dev:extension            # Start extension only (WXT dev + Chromium)
-bun dev:api                  # Start API server (signaling + routes)
+bun run dev                  # Start full repo-native local environment
+bun run dev:stop             # Stop repo-tracked local targets
+bun run dev:app              # Start app only
+bun run dev:extension        # Start extension only (WXT dev + Chromium)
+bun run dev:api              # Start API server (signaling + routes)
 cd packages/app && bun run build        # Build app only
 cd packages/extension && bun run build  # Build extension only
 bun format && bun lint       # Format (Biome) and lint workspace

CLAUDE.md

@@ -6,10 +6,11 @@ This file provides guidance to Claude Code when working with this repository.
 
 ```bash
 bun install                  # Install dependencies
-bun dev                      # Start app + extension (concurrent)
-bun dev:app                  # Start app only
-bun dev:extension            # Start extension only (WXT dev + Chromium)
-bun dev:api                  # Start API server (signaling + routes)
+bun run dev                  # Start full repo-native local environment
+bun run dev:stop             # Stop repo-tracked local targets
+bun run dev:app              # Start app only
+bun run dev:extension        # Start extension only (WXT dev + Chromium)
+bun run dev:api              # Start API server (signaling + routes)
 cd packages/app && bun run build        # Build app only
 cd packages/extension && bun run build  # Build extension only
 bun format && bun lint       # Format (Biome) and lint workspace
@@ -180,8 +181,8 @@ Do not duplicate these. Import or apply existing classes.
 | `wss://api.coop.town/yws` | Fly.io Yjs document sync | WebSocket fallback for peer sync |
 | `https://coop.town` | Vercel PWA (landing + receiver) | Proxied through Cloudflare |
 | `https://docs.coop.town` | Vercel docs | Proxied through Cloudflare |
-| `wss://dev-api.coop.town` | Cloudflare tunnel -> localhost:3103 | Only up during `bun dev` |
-| `https://local.coop.town` | Cloudflare tunnel → localhost:3001 | Only up during `bun dev` |
+| `wss://dev-api.coop.town` | Cloudflare tunnel -> localhost:3103 | Only up during `bun run dev` or the coordinator fallback |
+| `https://local.coop.town` | Cloudflare tunnel -> localhost:3101 | Only up during `bun run dev` or the coordinator fallback |
 
 ## Environment
 
@@ -197,7 +198,7 @@ Single `.env.local` at root (never create package-specific .env). Env vars are b
 
 Full reference: `docs/builder/environment.md` (30+ vars covering TURN, Pimlico, FVM, Green Goods, trusted-node archive, tunnels)
 
-`bun dev` automatically sets `VITE_COOP_SIGNALING_URLS` and `VITE_COOP_RECEIVER_APP_URL` for the extension build. The extension gets both local and production signaling URLs for fallback.
+The lower-level dev scripts started by `bun run dev` set `VITE_COOP_SIGNALING_URLS` and `VITE_COOP_RECEIVER_APP_URL` for the extension build. The extension gets both local and production signaling URLs for fallback.
 
 ## Validation Suites
 

README.md

@@ -116,10 +116,11 @@ Essential commands:
 
 ```bash
 bun install                    # Install dependencies
-bun dev                        # Start app + extension concurrently
-bun dev:app                    # Start app only
-bun dev:extension              # Start extension only
-bun dev:api                    # Start API server
+bun run dev                    # Start full repo-native local environment
+bun run dev:stop               # Stop repo-tracked local targets
+bun run dev:app                # Start app only
+bun run dev:extension          # Start extension only
+bun run dev:api                # Start API server
 bun run test                   # Run unit tests with Vitest
 bun run build                  # Build shared -> app -> extension
 bun run validate smoke         # Fast confidence pass

docs/builder/environment.md

@@ -36,7 +36,7 @@ prefixed variables are baked into bundles at build time by Vite -- rebuild after
 
 Notes:
 
-- `bun dev` injects `VITE_COOP_RECEIVER_APP_URL` and `VITE_COOP_SIGNALING_URLS` for the extension
+- `bun run dev` starts the workbench targets whose lower-level scripts inject `VITE_COOP_RECEIVER_APP_URL` and `VITE_COOP_SIGNALING_URLS` for the extension
   watcher so local dev can point at the active app and API processes.
 - `VITE_COOP_RECEIVER_APP_URL` is also used to derive the receiver bridge content-script matches in
   the extension manifest.

docs/builder/getting-started.md

@@ -78,15 +78,15 @@ Run these commands from the repository root:
 
 ```bash
 bun install
-bun dev
+bun run dev
 ```
 
 Useful split commands:
 
 ```bash
-bun dev:app
-bun dev:extension
-bun dev:api
+bun run dev:app
+bun run dev:extension
+bun run dev:api
 ```
 
 ## Keep One Root Environment File

docs/reference/demo-and-deploy-runbook.md

@@ -90,10 +90,10 @@ coordination patterns, and hardening live/operator rails.
   - `live`: bounded Smart Session execution for phase-1 Green Goods actions
 - Production passkeys must be created on the final production PWA domain.
 
-## Environment 1: Local Development (with `bun dev`)
+## Environment 1: Local Development (with `bun run dev`)
 
-Use `bun dev` to start all services concurrently. The dev script automatically configures the
-extension with the correct signaling and receiver URLs.
+Use `bun run dev` to start all local repo services through the repo-native dev coordinator. The lower-level
+dev scripts automatically configure the extension with the correct signaling and receiver URLs.
 
 ### Root `.env.local` (minimal)
 
@@ -125,7 +125,7 @@ run `bun run docs:dev` or `bun run docs:build`.
 
 ```bash
 bun install
-bun dev
+bun run dev
 ```
 
 To stop the full local dev environment and clean up orphan listeners:
@@ -141,7 +141,7 @@ Expected surfaces:
 - Production fallback signaling: `wss://api.coop.town`
 - Extension bundle: `packages/extension/dist/chrome-mv3`
 
-To run services individually instead of `bun dev`:
+To run services individually instead of `bun run dev`:
 
 ```bash
 bun run dev:app

docs/reference/extension-install-and-distribution.md

@@ -70,12 +70,12 @@ For development with live-reload and all local services:
 
 ```bash
 bun install
-bun dev
+bun run dev
 ```
 
-This starts the extension, the receiver PWA, and the signaling server concurrently. The dev script
-automatically sets `VITE_COOP_SIGNALING_URLS` and `VITE_COOP_RECEIVER_APP_URL` for the extension
-build.
+This starts the extension, receiver PWA, docs, and signaling server through the repo-native dev coordinator.
+The lower-level scripts automatically set `VITE_COOP_SIGNALING_URLS` and
+`VITE_COOP_RECEIVER_APP_URL` for the extension build.
 
 If you only need the extension:
 

docs/reference/original-introduction.md

@@ -73,8 +73,8 @@ ERC-4337, ERC-1271, EIP-712, ERC-7579, ERC-5564, ERC-8004, Semaphore, Storacha/F
 
 ```bash
 bun install            # Install dependencies
-bun dev                # Start app + extension concurrently
-bun dev:api            # Start API server
+bun run dev            # Start the full repo-native local environment
+bun run dev:api        # Start API server
 bun run test           # Run tests
 bun run build          # Build everything
 bun run validate:production-readiness  # Staged-launch validation

package.json

@@ -171,8 +171,5 @@
     "vite": "^6.2.0",
     "vitest": "^3.2.4"
   },
-  "overrides": {
-    "protobufjs": "7.5.9"
-  },
   "trustedDependencies": ["@biomejs/biome"]
 }