@danieljvdm/dev-kit 0.9.0 → 0.11.0

package/README.md

@@ -20,6 +20,9 @@ Install the published Dev Kit package:
 bun add -d @danieljvdm/dev-kit
 ```
 
+Dev Kit requires Bun 1.3 or newer. Its published executable runs TypeScript
+natively with Bun and rejects direct Node.js execution.
+
 Initialize the project, browse available built-in, approved Git, and installed
 package skills, then add the ones you want:
 
@@ -94,12 +97,14 @@ before running locked mode:
 
 ```bash
 bun install --ignore-scripts
-bun x dev-kit apply --locked
+bun ./node_modules/@danieljvdm/dev-kit/bin/dev-kit.mjs apply --locked
 ```
 
 Or allow the normal postinstall and fail CI when it leaves tracked changes.
 Do not run an unlocked apply before a locked verification because that would
 regenerate the drift being checked.
+The package-qualified path cannot be shadowed by a consumer script named
+`dev-kit`.
 
 This repository dogfoods the same flow with its committed `dev-kit.jsonc` and
 `dev-kit.lock.json`. From this source checkout, invoke the local CLI with:
@@ -211,7 +216,7 @@ The patch is idempotent, preserves existing lines, and refuses symlinked
 
 ## Agent instructions
 
-Enable a managed project-root instruction wrapper and a portable Claude Code
+Enable managed project-root instruction sections and a portable Claude Code
 bridge in the manifest:
 
 ```jsonc
@@ -224,18 +229,37 @@ bridge in the manifest:
 }
 ```
 
-`setup.agentInstructions` manages `AGENTS.md` as a generated wrapper with a
-short description of dev-kit and a pointer to the installed `dev-kit` skill.
-When the root `package.json` declares `vite-plus` directly, the wrapper also
-includes Vite+'s installed `node_modules/vite-plus/AGENTS.md` instructions.
-Transitive installations do not opt a project in.
+`setup.agentInstructions` manages marked sections in the project-root
+`AGENTS.md`, preserving handwritten project guidance around them. The Dev Kit
+section contains a short description and a pointer to the installed `dev-kit`
+skill. When the root `package.json` declares `vite-plus` directly, Dev Kit
+renders its own repository-specific Vite+ guidance, including the unified
+toolchain overview, help and documentation entry points, and `vp env doctor`
+troubleshooting. It does not import Vite+'s generic `AGENTS.md`, which can
+conflict with the repository's exact commands; transitive installations do not
+opt a project in. Previously managed Vite+ sections are removed during a safe
+owned update. Ambiguous or malformed managed markers fail closed.
+
+The Dev Kit section also renders an opinionated project command policy. A
+direct Vite+ dependency makes `vp` the only supported front door: built-in
+format, lint, and test commands use `vp`, while repository tasks and package
+scripts use `vp run`. When Dev Kit manages the quality config, the canonical
+full validation and typecheck commands are `vp run check` and
+`vp run typecheck`; `vp check` alone is only the Vite+ static-check command.
+Without Vite+, Bun is the required package-script runner and Dev Kit lists only
+quality scripts the root package actually declares. The package manager named
+by `package.json#packageManager`, or inferred from a single recognized root
+lockfile, is used only for dependency-install guidance. The policy forbids
+switching script runners or bypassing project entry points with raw `tsc`,
+test-runner, linter, or formatter commands.
 
 `setup.claudeInstructions` manages `CLAUDE.md` as the relative symlink
-`CLAUDE.md → AGENTS.md`. It can link to the generated wrapper in the same apply,
+`CLAUDE.md → AGENTS.md`. It can link to the section-managed file in the same apply,
 or retain the older behavior of linking to an existing regular `AGENTS.md` when
-the wrapper task is disabled. Both outputs are recorded independently in the
-lockfile and local ownership state. Dev Kit refuses to replace unowned files
-and removes only unchanged owned outputs.
+the section task is disabled. Both outputs are recorded independently in the
+lockfile and local ownership state. Disabling agent instructions removes only
+unchanged managed sections and deletes `AGENTS.md` only when no handwritten
+content remains.
 
 ## Vite+ Git hooks
 
@@ -351,10 +375,11 @@ scripts, or TypeScript topology. It performs one frozen, script-suppressed
 install, runs `dev-kit apply --locked`, and only then runs custom preparation,
 formatting, linting, tests, and typechecking. Its default typecheck command is
 `vp run typecheck`; `workflow.typecheck` replaces it. Vite+ maps install flags
-to the detected package manager. The template pins an exact `setup-vp` release
-commit because its `v1` tag is frozen; keep it current with Renovate or
-Dependabot. Existing workflows remain user-owned until their rendered content
-matches exactly—Dev Kit never merges YAML. See the primary
+to the detected package manager. The template installs the consumer's declared
+Bun version and pins exact `setup-bun` and `setup-vp` releases; the latter's
+`v1` tag is frozen. Keep both current with Renovate or Dependabot. Existing
+workflows remain user-owned until their rendered content matches exactly—Dev
+Kit never merges YAML. See the primary
 [`setup-vp` versioning guidance](https://github.com/voidzero-dev/setup-vp#versioning),
 [Vite+ install guide](https://viteplus.dev/guide/install), and
 [Vite Task run guide](https://viteplus.dev/guide/run) when maintaining the

package/bin/dev-kit.mjs

@@ -1,3 +1,17 @@
-#!/usr/bin/env -S node --import tsx
+#!/usr/bin/env bun
 
-import "../src/bin/dev-kit.ts";
+import semver from "semver";
+
+const MINIMUM_BUN_VERSION = "1.3.0";
+const bunVersion = globalThis.Bun?.version;
+
+if (bunVersion === undefined) {
+  throw new Error(
+    `Dev Kit requires the Bun runtime, version ${MINIMUM_BUN_VERSION} or newer. Install Bun and run \`dev-kit\` again.`,
+  );
+}
+if (!semver.satisfies(bunVersion, `>=${MINIMUM_BUN_VERSION}`)) {
+  throw new Error(`Dev Kit requires Bun ${MINIMUM_BUN_VERSION} or newer; found ${bunVersion}.`);
+}
+
+await import("../src/bin/dev-kit.ts");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danieljvdm/dev-kit",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "private": false,
   "description": "Declarative project development toolkit with portable agent skills.",
   "license": "MIT",
@@ -65,15 +65,15 @@
     "catalog:check": "./bin/dev-kit.mjs catalog verify"
   },
   "dependencies": {
-    "@effect/platform-node": "4.0.0-beta.102",
+    "@effect/platform-bun": "4.0.0-beta.102",
     "@stylistic/eslint-plugin": "5.10.0",
     "effect": "4.0.0-beta.102",
     "jsonc-parser": "3.3.1",
-    "semver": "7.8.5",
-    "tsx": "4.22.4"
+    "semver": "7.8.5"
   },
   "devDependencies": {
     "@changesets/cli": "3.0.0-next.10",
+    "@effect/platform-node": "4.0.0-beta.102",
     "@effect/tsgo": "0.24.3",
     "@effect/vitest": "4.0.0-beta.102",
     "@types/node": "25.9.1",
@@ -101,7 +101,7 @@
     }
   },
   "engines": {
-    "node": ">=22.12.0"
+    "bun": ">=1.3.0"
   },
   "packageManager": "bun@1.3.14"
 }

package/schema/dev-kit.schema.json

@@ -68,7 +68,7 @@
   "required": ["include"],
   "$defs": {
     "agentInstructionsSetup": {
-      "description": "Manage a project-root AGENTS.md wrapper with dev-kit guidance and conditional tool instructions.",
+      "description": "Manage marked sections in project-root AGENTS.md with dev-kit guidance and conditional tool instructions while preserving handwritten content.",
       "type": "object",
       "additionalProperties": false,
       "properties": {

package/skill-sources.jsonc

@@ -55,5 +55,35 @@
       "include": ["tdd", "improve-codebase-architecture"],
       "licensePath": "LICENSE",
     },
+    {
+      "id": "expo-skills",
+      "repository": "https://github.com/expo/skills.git",
+      "ref": "main",
+      "skillsPath": "plugins/expo/skills",
+      "include": [
+        "eas-app-stores",
+        "eas-hosting",
+        "eas-observe",
+        "eas-simulator",
+        "eas-update-insights",
+        "eas-workflows",
+        "expo-app-clip",
+        "expo-brownfield",
+        "expo-data-fetching",
+        "expo-dev-client",
+        "expo-dom",
+        "expo-examples",
+        "expo-module",
+        "expo-native-ui",
+        "expo-project-structure",
+        "expo-router",
+        "expo-skill-feedback",
+        "expo-tailwind-setup",
+        "expo-ui",
+        "expo-upgrade",
+        "expo-web-to-native",
+      ],
+      "licensePath": "LICENSE",
+    },
   ],
 }

package/skill-sources.lock.json

@@ -143,6 +143,106 @@
         "tdd": "sha256:ea2d26eda005b10a2de4bdb7de44d33072f2a8e82dbf670952ce30a9c2d7c475"
       },
       "licensePath": "LICENSE"
+    },
+    {
+      "id": "expo-skills",
+      "repository": "https://github.com/expo/skills.git",
+      "ref": "main",
+      "resolved": "994342f0e343f05b9b8cdd38a0e91356ceef00f6",
+      "skillsPath": "plugins/expo/skills",
+      "include": [
+        "eas-app-stores",
+        "eas-hosting",
+        "eas-observe",
+        "eas-simulator",
+        "eas-update-insights",
+        "eas-workflows",
+        "expo-app-clip",
+        "expo-brownfield",
+        "expo-data-fetching",
+        "expo-dev-client",
+        "expo-dom",
+        "expo-examples",
+        "expo-module",
+        "expo-native-ui",
+        "expo-project-structure",
+        "expo-router",
+        "expo-skill-feedback",
+        "expo-tailwind-setup",
+        "expo-ui",
+        "expo-upgrade",
+        "expo-web-to-native"
+      ],
+      "skills": [
+        "eas-app-stores",
+        "eas-hosting",
+        "eas-observe",
+        "eas-simulator",
+        "eas-update-insights",
+        "eas-workflows",
+        "expo-app-clip",
+        "expo-brownfield",
+        "expo-data-fetching",
+        "expo-dev-client",
+        "expo-dom",
+        "expo-examples",
+        "expo-module",
+        "expo-native-ui",
+        "expo-project-structure",
+        "expo-router",
+        "expo-skill-feedback",
+        "expo-tailwind-setup",
+        "expo-ui",
+        "expo-upgrade",
+        "expo-web-to-native"
+      ],
+      "descriptions": {
+        "eas-app-stores": "EAS service (paid). Deploy Expo apps to the app stores with EAS - build and submit to the iOS App Store, Google Play Store, and TestFlight, configure eas.json build and submit profiles, manage app versions and build numbers, and publish App Store metadata and ASO. Use whenever the user wants to deploy, release, or ship an app to production or the app stores, is preparing a production build, running eas build or eas submit, shipping to TestFlight, bumping version or build numbers, or setting up store listing metadata. For deploying an Expo website or API routes, use the eas-hosting skill.",
+        "eas-hosting": "EAS service (paid). Deploy Expo websites and Expo Router API routes to EAS Hosting - export the web bundle, run eas deploy for production and PR preview URLs, manage environment secrets and custom domains, and work within the Cloudflare Workers runtime. Also covers authoring API routes (+api.ts handlers, HTTP methods, request handling, CORS). Use when deploying an Expo web app or API routes, setting up EAS Hosting, or configuring hosting environments and domains. Not for native builds or store releases - use the eas-app-stores skill for those.",
+        "eas-observe": "EAS service (paid). Use for anything related to EAS Observe - adding `expo-observe` to an Expo project (AppMetricsRoot/ObserveRoot HOC, markInteractive, the useObserve hook, the Expo Router / React Navigation integrations for per-route metrics, and user-defined events via `Observe.logEvent`), querying via the EAS CLI (`eas observe:metrics-summary`, `observe:metrics`, `observe:routes`, `observe:events`, `observe:versions`), or interpreting the resulting metrics (cold/warm launch, TTR, TTI, navigation cold/warm TTR, update download, and the TTI frameRate params for triaging slow startups).",
+        "eas-simulator": "EAS service (paid). Run and control a user's app on a remote iOS/Android simulator hosted on EAS cloud. Read before running any `eas simulator:*` commands - it has the current syntax for this experimental API. Use whenever the user needs a simulator they can't run locally - 'run my app on a cloud simulator', 'use eas simulator to run/install/screenshot my app', 'I'm on Linux/Cursor and need an iOS device', 'no sim on this box / headless CI', 'let an agent click through my app and screenshot it', 'test my dev build on a remote sim with live reload', 'stream a sim to my browser' - even when they don't say 'EAS Simulator' or 'cloud'. On a host WITHOUT a local simulator (Linux, CI, cloud sandbox) it's the default; on macOS, do NOT auto-trigger for a plain 'run on the simulator' - use it only for a cloud/remote/shareable sim, an iOS version they lack, or an agent-driven session. NOT for local sims (expo run:ios, Xcode, Android Studio), EAS Build/Update, web preview, or physical devices.",
+        "eas-update-insights": "EAS service (paid). Check the health of published EAS Update: crash rates, install/launch counts, unique users, payload size, and the split between embedded and OTA users per channel. Use when the user asks how an update is performing, whether a rollout is healthy, how many users are on the embedded build vs OTA, or wants to gate CI on update health.",
+        "eas-workflows": "EAS service (paid). Helps understand and write EAS workflow YAML files for Expo projects. Use this skill when the user asks about CI/CD or workflows in an Expo or EAS context, mentions .eas/workflows/, or wants help with EAS build pipelines or deployment automation.",
+        "expo-app-clip": "Framework (OSS). Add an iOS App Clip target to an Expo app. Use when the user mentions App Clip, AASA, apple-app-site-association, appclips, smart app banner, or wants to ship a lightweight iOS Clip invoked from a URL alongside their parent app.",
+        "expo-brownfield": "Framework (OSS). Integrate Expo and React Native into an existing native iOS or Android app. Use when the user mentions brownfield, embedding React Native in a native app, AAR/XCFramework, or adding Expo to an existing Kotlin/Swift project. Covers both the isolated approach and the integrated approach.",
+        "expo-data-fetching": "Framework (OSS). Use when implementing or debugging ANY network request, API call, or data fetching. Covers fetch API, React Query, SWR, error handling, caching, offline support, and Expo Router data loaders (`useLoaderData`).",
+        "expo-dev-client": "Framework (OSS). Build and distribute Expo development clients locally or via TestFlight for internal testing. For production TestFlight releases and store submission, use the eas-app-stores skill.",
+        "expo-dom": "Framework (OSS). Use Expo DOM components to run web code in a webview on native and as-is on web. Migrate web code to native incrementally. For the end-to-end migration of a whole web app, use the expo-web-to-native skill.",
+        "expo-examples": "Framework (OSS). Expo's official example projects - the expo/examples repo of ~70 `with-*` integrations (Stripe, Clerk, Supabase, OpenAI, maps, Reanimated, SQLite, Skia, NativeWind, and more). Use when integrating a third-party library or service into an existing Expo app and you want the canonical, version-matched pattern to adapt, or when scaffolding a new project from one with `npx create-expo --example`.",
+        "expo-module": "Framework (OSS). Guide for creating and writing Expo native modules and views using the Expo Modules API (Swift, Kotlin, TypeScript). Covers module definition DSL, native views, shared objects, config plugins, lifecycle hooks, autolinking, and type system. Use when building or modifying native modules for Expo. Not for migrating an existing Swift module from the definition DSL to the Expo Modules API 2.0 macros; use expo-migrate-module (from the expo-experiments plugin) for that.",
+        "expo-native-ui": "Framework (OSS). Build beautiful, native-feeling Expo screens. Covers Apple HIG styling, semantic colors, native controls, SF Symbols, media, animations, visual effects, gradients, storage, and responsive layout. For routing and navigation, use the expo-router skill.",
+        "expo-project-structure": "Framework (OSS). Folder structure for a new Expo app. Use when scaffolding or laying out a new Expo project with Expo Router, or deciding where a file should live in one. For new projects only — never restructure an existing app to match.",
+        "expo-router": "Framework (OSS). Navigation and routing for Expo Router. Covers file-based routes, groups and dynamic routes, folder organization, Link with previews and context menus, native Stack, page titles, modals and form sheets, NativeTabs, headers and toolbars, and header search bars.",
+        "expo-skill-feedback": "Submit feedback on an Expo skill—or Expo itself—and control bundled anonymous usage telemetry (off by default / opt-in). Submit feedback with: npx --yes submit-expo-feedback@latest \"ACTIONABLE_FEEDBACK\". Optionally add either or both: --category \"CATEGORY\" and --subject \"SUBJECT\". Replace the uppercase placeholders before running. Use when a skill was useful, confusing, broken, missing context, or worth improving; when Expo, Expo CLI, EAS CLI, docs, or MCP worked well or fell short; when an AI agent repeatedly failed, got stuck, or needed the user to take over an Expo task (report it as an eval candidate); or when the user explicitly asks to enable or disable telemetry (tracking), check its status, or understand what it collects.",
+        "expo-tailwind-setup": "Framework (OSS). Set up Tailwind CSS v4 in Expo with react-native-css and NativeWind v5 for universal styling",
+        "expo-ui": "Framework (OSS). Build native UI with the @expo/ui package: real SwiftUI on iOS and Jetpack Compose on Android rendered from React in an Expo or React Native app. Covers universal cross-platform components (Host, Column, Row, Button, Text, List, and more imported from @expo/ui), drop-in replacements for popular React Native community libraries (BottomSheet, DateTimePicker, Slider, Menu, etc.), and platform-specific SwiftUI (@expo/ui/swift-ui, iOS only) and Jetpack Compose (@expo/ui/jetpack-compose, Android only) trees and modifiers. Use when adding or reviewing @expo/ui Host/RNHostView trees, building native-feeling UI where standard React Native components fall short (grouped settings forms with toggles, sections, menus, sheets, pickers, sliders), choosing between universal and platform-specific components, or replacing an RN community UI library with a native @expo/ui equivalent. Not for custom native modules, Expo Router navigation, Reanimated, or data fetching.",
+        "expo-upgrade": "Framework (OSS). Guidelines for upgrading Expo SDK versions and fixing dependency issues",
+        "expo-web-to-native": "Framework (OSS). Migrate an existing web React app to a native iOS/Android app with Expo. Use when the user wants to turn a website into a mobile app, port a Next.js/Vite/CRA React codebase to React Native, reuse web code on native incrementally, or asks how web idioms (the DOM, CSS, React Router, localStorage, window) map to native. This is the end-to-end migration guide; use the `expo-dom` skill for the DOM-component mechanism itself."
+      },
+      "digests": {
+        "eas-app-stores": "sha256:830332227adfe1421667abe0e3e90c554c85661c5646de4e05a976b276bd2c74",
+        "eas-hosting": "sha256:9d2df9eb3045016b45c69d8578b4d1bdfea5d520b22136145a4593a2ebc57586",
+        "eas-observe": "sha256:da1785de84561773ab17d36a80d82a0a2e764ed2585a6234a491b6296fb58e86",
+        "eas-simulator": "sha256:461021e81e3a6abf8ed4cd119208e62e420d3779a41edec94f84b5d7ce8cd0f6",
+        "eas-update-insights": "sha256:5a98762401a49571a68e8d7824c510bf6b54bd3d2e4d097c846964ee4ff25687",
+        "eas-workflows": "sha256:27bee5b70ef49ff91cc3fc3473257444af07733248926acd0115752223045eee",
+        "expo-app-clip": "sha256:9129826172144ec4e625ae768e79f2acaebb5cf53a8af51fbc32fb45d82c260a",
+        "expo-brownfield": "sha256:0fd07f633c868759a062fd0732b3702826bc3ca3f3a6c094cb7ea7a213ad1dfd",
+        "expo-data-fetching": "sha256:a556bea72824a147744fc5b784128207cbeb3425082fa741070ce47799631a27",
+        "expo-dev-client": "sha256:dd1a5364386a171d367108519a78cf743ecbac6f9f66f030910e0048e5650788",
+        "expo-dom": "sha256:46af40ce11aaa7e94b82fc2c3c38198241b87dbc31c925152da53bbd2a063d4e",
+        "expo-examples": "sha256:608f12b9e6c52c6968ae6d655f51d83384194f6a221ea02a0bf812ed23438a2f",
+        "expo-module": "sha256:8133a3f27a7b99d60961dc31dd27b9f0ea39b0bbac753be8a17ba8f554f7ef98",
+        "expo-native-ui": "sha256:87516edae70305f9e7231599533b2ae27c12a55bb5f0b7205b0d64ababa0c967",
+        "expo-project-structure": "sha256:28fafa0754bcd9686ead5dcbc6a8abf8e00325ee756b794989bfb8e11f6ae941",
+        "expo-router": "sha256:3d07d7c13c906665725fc235b6fa2cb28bbd8ad7184ec9eba3d2e2ae87baa3c2",
+        "expo-skill-feedback": "sha256:6c636f8bcec43c2ad1ed1bf11c90fc32d75b6b15dfe79f23d44387fa45e20307",
+        "expo-tailwind-setup": "sha256:de3cc17cc9e11f1989659a61a8fddb98a62b356c58d77c7ec5318b03789e896a",
+        "expo-ui": "sha256:b6773a56b0f9bf4cc3dc9cb1858ab50bdfcc3dc9b2d4e500990ab5d24e28d1ca",
+        "expo-upgrade": "sha256:6c65f94c60f8127a36ca2d9402b610756314388de42200a2a120bbbea77f131b",
+        "expo-web-to-native": "sha256:360359742d72d0a8ed9926d53f19bae7603fb788f6e897a14208bbb35c2ed618"
+      },
+      "licensePath": "LICENSE"
     }
   ]
 }

package/skills/dev-kit/SKILL.md

@@ -95,14 +95,30 @@ use symlinks for additional harness discovery paths. Keep every target path
 project-relative and separate from the manifest, lock, state, and process-lock
 paths.
 
-Enable `setup.agentInstructions` to manage a project-root `AGENTS.md` wrapper
-that points agents back to this skill. When `vite-plus` is a declared direct
-dependency, dev-kit includes its installed agent instructions in the wrapper.
+Enable `setup.agentInstructions` to manage marked sections in a project-root
+`AGENTS.md` while preserving handwritten project guidance. The Dev Kit section
+points agents back to this skill. When `vite-plus` is a declared direct
+dependency, dev-kit synthesizes repository-specific Vite+ guidance inside its
+own section instead of importing Vite+'s generic `AGENTS.md`. Preserve the
+useful unified-toolchain overview, help and documentation entry points, and
+`vp env doctor` troubleshooting without duplicating generic commands that can
+contradict the repository policy. Treat duplicate, overlapping, reversed, or
+unmatched managed markers as a conflict rather than guessing which content Dev
+Kit owns; remove a legacy owned Vite+ section during migration.
+The managed section also publishes the repository's command authority. Direct
+Vite+ projects must use `vp` built-ins and `vp run <task>`; managed quality
+projects use `vp run check` for the complete format/lint/test/typecheck suite
+and `vp run typecheck` for the Effect-patched compiler. Non-Vite+ projects run
+existing root quality scripts through `bun run`; package-manager metadata and
+lockfiles affect dependency-install guidance only. Never substitute another
+script runner or call raw `tsc`, test, lint, or format binaries when a project
+command exists.
 Enable `setup.claudeInstructions` when Claude Code should consume the same
 project-root instructions; it manages `CLAUDE.md` as a relative symlink to the
-wrapper or to an existing regular `AGENTS.md`. Preserve conflicting paths;
-when disabled, dev-kit removes only unchanged outputs recorded in local
-ownership state.
+section-managed file or to an existing regular `AGENTS.md`. Preserve
+conflicting paths; when disabled, dev-kit removes only unchanged marked
+sections recorded in local ownership state and leaves handwritten content in
+place.
 
 Enable `setup.vitePlus.hooks` when an installed direct `vite-plus` dependency
 should manage Git hooks. Each apply checks the local `.vite-hooks/_` dispatcher,
@@ -129,9 +145,11 @@ builds custom. Workflow-only consumers may configure `workflow.beforeChecks`
 and `workflow.typecheck`; treat these commands as trusted manifest input.
 
 The workflow must use one frozen, script-suppressed install, then locked Dev Kit
-convergence before preparation or checks. Keep `setup-vp` pinned to a reviewed
-release commit—the `v1` tag is frozen—and let Vite+ resolve the consumer's
-compatible locked version.
+convergence before preparation or checks. Set up Bun from the consumer's
+`packageManager` or `engines.bun` declaration before Vite+ setup. Keep both
+`setup-bun` and `setup-vp` pinned to reviewed release commits—the `setup-vp`
+`v1` tag is frozen—and let Vite+ resolve the consumer's compatible locked
+version.
 
 ## Ownership and conflicts
 
@@ -157,6 +175,10 @@ Run `dev-kit gitignore` to add `.repos/` and `.dev-kit/` additively. Preview wit
 `dev-kit gitignore --dry-run`. Treat `.repos/<source-id>` as the reserved source
 checkout root.
 
+Require Bun 1.3 or newer wherever Dev Kit runs. The published `dev-kit`
+executable uses Bun directly and rejects Node execution; keep Bun available to
+package lifecycle scripts and locked CI verification.
+
 For one lifecycle entry point, configure:
 
 ```jsonc
@@ -171,7 +193,10 @@ This intentionally refreshes the committed lock and owned outputs when the
 package manager installs a new Dev Kit or selected package-skill version.
 Review and commit those changes with the dependency update. Keep
 `dev-kit apply --locked` as a verification command, not the normal local
-lifecycle; in CI, run it only before any unlocked apply.
+lifecycle; in CI, run it only before any unlocked apply. Invoke locked consumer
+verification as
+`bun ./node_modules/@danieljvdm/dev-kit/bin/dev-kit.mjs apply --locked` so a
+package script named `dev-kit` cannot shadow the executable.
 
 ## Effect source checkout
 
@@ -263,7 +288,7 @@ in the consuming project.
 
 ## Current boundary
 
-Manage skill outputs, the `setup.agentInstructions` wrapper, the
+Manage skill outputs, the `setup.agentInstructions` marked sections, the
 `setup.claudeInstructions` link, the `setup.vitePlus.hooks` dispatcher, the
 independently opt-in `setup.vitePlus.quality` config and GitHub workflow, the
 `setup.effectSource` checkout, and the explicit `setup.effectTsgo` task.

package/src/bin/dev-kit.ts

@@ -1,4 +1,4 @@
-import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { BunRuntime, BunServices } from "@effect/platform-bun";
 import { Effect, Result } from "effect";
 import { Argument, CliError, Command as CliCommand, Flag } from "effect/unstable/cli";
 
@@ -399,7 +399,7 @@ const program = CliCommand.run(command, { version: DEV_KIT_VERSION }).pipe(
       ),
   ),
   Effect.scoped,
-  Effect.provide(NodeServices.layer),
+  Effect.provide(BunServices.layer),
 );
 
-NodeRuntime.runMain(program, { disableErrorReporting: true });
+BunRuntime.runMain(program, { disableErrorReporting: true });

package/src/project-package.ts

@@ -8,6 +8,7 @@ export class ProjectPackageError extends Schema.TaggedErrorClass<ProjectPackageE
 const ProjectPackageSchema = Schema.fromJsonString(
   Schema.Struct({
     name: Schema.optional(Schema.String),
+    packageManager: Schema.optional(Schema.String),
     scripts: Schema.optional(Schema.Record(Schema.String, Schema.String)),
     dependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
     devDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),

package/src/sync.ts

@@ -26,7 +26,7 @@ import {
   observePathWithRawModes,
   type ObservedPath,
 } from "./path-digest.ts";
-import { readDirectDependencyNames } from "./project-package.ts";
+import { readDirectDependencyNames, readProjectPackage } from "./project-package.ts";
 import { acquireProjectProcessLock, PROJECT_PROCESS_LOCK_PATH } from "./project-process-lock.ts";
 import {
   AppliedStateSchema,
@@ -115,12 +115,14 @@ type SkillPlanAction =
       readonly action: "create" | "update";
       readonly desired: DesiredOutput;
       readonly observed: ObservedPath;
+      readonly stagedContent?: string;
     }
   | {
       readonly action: "remove";
       readonly previous: OwnershipReceipt;
       readonly destination: string;
       readonly observed: ObservedPath;
+      readonly stagedContent?: string;
     }
   | {
       readonly action: "unchanged";
@@ -234,6 +236,255 @@ const DEFAULT_LOCKFILE = "dev-kit.lock.json";
 const DEFAULT_STATE = ".dev-kit/state.json";
 const AGENT_INSTRUCTIONS_TEMPLATE = "templates/AGENTS.md";
 const DEV_KIT_SKILL_PATH_PLACEHOLDER = "{{DEV_KIT_SKILL_PATH}}";
+const PROJECT_COMMAND_POLICY_PLACEHOLDER = "{{PROJECT_COMMAND_POLICY}}";
+const AGENT_INSTRUCTION_MARKERS = [
+  { start: "<!-- DEV KIT START -->", end: "<!-- DEV KIT END -->" },
+  // Legacy Dev Kit releases copied this upstream section into AGENTS.md. Keep
+  // recognizing it so an owned section can be removed during migration.
+  { start: "<!--VITE PLUS START-->", end: "<!--VITE PLUS END-->" },
+] as const;
+
+type ManagedInstructionRange = {
+  readonly start: number;
+  readonly end: number;
+  readonly content: string;
+};
+
+type ManagedInstructionInspection =
+  | {
+      readonly kind: "valid";
+      readonly ranges: ReadonlyArray<ManagedInstructionRange>;
+      readonly content?: string;
+    }
+  | { readonly kind: "invalid"; readonly reason: string };
+
+const findOccurrences = (content: string, marker: string): ReadonlyArray<number> => {
+  const positions: Array<number> = [];
+  let offset = 0;
+
+  while (offset < content.length) {
+    const position = content.indexOf(marker, offset);
+
+    if (position === -1) break;
+    positions.push(position);
+    offset = position + marker.length;
+  }
+
+  return positions;
+};
+
+const inspectManagedInstructionSections = (content: string): ManagedInstructionInspection => {
+  const ranges: Array<ManagedInstructionRange> = [];
+
+  for (const markers of AGENT_INSTRUCTION_MARKERS) {
+    const starts = findOccurrences(content, markers.start);
+    const ends = findOccurrences(content, markers.end);
+
+    if (starts.length === 0 && ends.length === 0) continue;
+    if (
+      starts.length !== 1 ||
+      ends.length !== 1 ||
+      starts[0] === undefined ||
+      ends[0] === undefined
+    ) {
+      return {
+        kind: "invalid",
+        reason: `expected exactly one ${markers.start}/${markers.end} marker pair`,
+      };
+    }
+    if (starts[0] >= ends[0]) {
+      return { kind: "invalid", reason: `${markers.end} appears before ${markers.start}` };
+    }
+    const end = ends[0] + markers.end.length;
+
+    ranges.push({ start: starts[0], end, content: content.slice(starts[0], end) });
+  }
+  ranges.sort((left, right) => left.start - right.start);
+  for (let index = 1; index < ranges.length; index += 1) {
+    const previous = ranges[index - 1];
+    const current = ranges[index];
+
+    if (previous !== undefined && current !== undefined && current.start < previous.end) {
+      return { kind: "invalid", reason: "managed instruction marker pairs overlap" };
+    }
+  }
+
+  return {
+    kind: "valid",
+    ranges,
+    ...(ranges.length === 0
+      ? {}
+      : { content: `${ranges.map((range) => range.content.trim()).join("\n\n")}\n` }),
+  };
+};
+
+const removeManagedInstructionSections = (
+  content: string,
+  ranges: ReadonlyArray<ManagedInstructionRange>,
+): string => {
+  const first = ranges[0];
+  const last = ranges.at(-1);
+  const hasOnlyManagedSeparators = ranges.every((range, index) => {
+    const next = ranges[index + 1];
+
+    return next === undefined || /^\s*$/.test(content.slice(range.end, next.start));
+  });
+
+  if (first?.start === 0 && last !== undefined && hasOnlyManagedSeparators) {
+    let end = last.end;
+
+    if (content.startsWith("\r\n", end)) end += 2;
+    else if (content.startsWith("\n", end)) end += 1;
+
+    return content.slice(end);
+  }
+  let result = content;
+
+  for (const range of [...ranges].reverse()) {
+    result = result.slice(0, range.start) + result.slice(range.end);
+  }
+
+  return result;
+};
+
+const prependManagedInstructionSections = (content: string, managed: string): string => {
+  if (content.trim().length === 0) return managed;
+
+  return `${managed}${content}`;
+};
+
+const reconcileManagedInstructionSections = (
+  content: string,
+  inspection: Extract<ManagedInstructionInspection, { readonly kind: "valid" }>,
+  managed: string,
+): string =>
+  prependManagedInstructionSections(
+    removeManagedInstructionSections(content, inspection.ranges),
+    managed,
+  );
+
+const renderVitePlusCommandPolicy = (
+  scripts: Readonly<Record<string, string>>,
+  managesQualityConfig: boolean,
+): string => {
+  const hasCheck = managesQualityConfig || scripts.check !== undefined;
+  const hasTypecheck = managesQualityConfig || scripts.typecheck !== undefined;
+
+  return [
+    "## Project command policy",
+    "",
+    "Vite+ is the unified toolchain and command authority for this repository. It wraps Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task behind the `vp` CLI; Vite+ is distinct from Vite.",
+    "",
+    "Run `vp help` for available commands and `vp <command> --help` for command-specific options. Documentation is available locally in `node_modules/vite-plus/docs` and online at https://viteplus.dev/guide/.",
+    "",
+    "Use these repository commands:",
+    "",
+    "- Install dependencies: `vp install`.",
+    ...(hasCheck ? ["- Full validation: `vp run check`."] : []),
+    "- Static checks: `vp check`.",
+    "- Format check: `vp fmt --check`; format fixes: `vp fmt`.",
+    "- Lint only: `vp lint`; lint fixes: `vp lint --fix`.",
+    "- Tests only: `vp test`.",
+    ...(hasTypecheck ? ["- Typecheck only: `vp run typecheck`."] : []),
+    "- Other repository tasks and package scripts: `vp run <task>`.",
+    "- Toolchain or runtime troubleshooting: run `vp env doctor` and include its output when asking for help.",
+    "",
+    "Do not use `bun run`, `npm run`, `pnpm run`, or `yarn run` in this repository. Do not invoke underlying tools such as `tsc`, `vitest`, `oxlint`, or `oxfmt` directly; use the Vite+ entry points above.",
+  ].join("\n");
+};
+
+const PACKAGE_MANAGER_COMMANDS = {
+  bun: { install: "bun install", label: "Bun" },
+  npm: { install: "npm install", label: "npm" },
+  pnpm: { install: "pnpm install", label: "pnpm" },
+  yarn: { install: "yarn install", label: "Yarn" },
+} as const;
+
+type PackageManagerName = keyof typeof PACKAGE_MANAGER_COMMANDS;
+
+const packageManagerName = (declaration: string | undefined): PackageManagerName | undefined => {
+  const name = declaration?.split("@", 1)[0];
+
+  return name !== undefined && name in PACKAGE_MANAGER_COMMANDS
+    ? (name as PackageManagerName)
+    : undefined;
+};
+
+const detectPackageManager = Effect.fn("detectPackageManager")(function* (
+  projectDir: string,
+  declaration: string | undefined,
+) {
+  const declared = packageManagerName(declaration);
+
+  if (declared !== undefined || declaration !== undefined) return declared;
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const lockfiles: ReadonlyArray<readonly [PackageManagerName, ReadonlyArray<string>]> = [
+    ["bun", ["bun.lock", "bun.lockb"]],
+    ["npm", ["package-lock.json", "npm-shrinkwrap.json"]],
+    ["pnpm", ["pnpm-lock.yaml"]],
+    ["yarn", ["yarn.lock"]],
+  ];
+  const detected: Array<PackageManagerName> = [];
+
+  for (const [manager, files] of lockfiles) {
+    let found = false;
+
+    for (const file of files) {
+      if (yield* fs.exists(path.join(projectDir, file))) {
+        found = true;
+        break;
+      }
+    }
+    if (found) {
+      detected.push(manager);
+    }
+  }
+
+  return detected.length === 1 ? detected[0] : undefined;
+});
+
+const renderPackageScriptCommandPolicy = (
+  manager: PackageManagerName | undefined,
+  scripts: Readonly<Record<string, string>>,
+): string => {
+  const installer = manager === undefined ? undefined : PACKAGE_MANAGER_COMMANDS[manager];
+  const entries = [
+    ["check", "Full validation"],
+    ["format:check", "Format check"],
+    ["format", "Format"],
+    ["lint", "Lint"],
+    ["test", "Tests"],
+    ["typecheck", "Typecheck"],
+  ] as const;
+  const commands = entries.flatMap(([script, label]) =>
+    scripts[script] === undefined ? [] : [`- ${label}: \`bun run ${script}\`.`],
+  );
+  const knownScripts = new Set(entries.map(([script]) => script));
+  const additionalCommands = Object.keys(scripts)
+    .filter(
+      (script) =>
+        !knownScripts.has(script as (typeof entries)[number][0]) &&
+        /^(?:check|validate|fmt|format|lint|test|type-?check)(?::|$)/.test(script),
+    )
+    .sort()
+    .map((script) => `- Script \`${script}\`: \`bun run ${script}\`.`);
+  const qualityCommands = [...commands, ...additionalCommands];
+
+  return [
+    "## Project command policy",
+    "",
+    "Bun is the package-script runner for this repository:",
+    "",
+    ...(installer === undefined
+      ? []
+      : [`- Install dependencies with ${installer.label}: \`${installer.install}\`.`]),
+    ...qualityCommands,
+    ...(qualityCommands.length === 0 ? ["- No root quality scripts are currently declared."] : []),
+    "",
+    "Run only declared scripts through `bun run <script>`. Do not use `npm run`, `pnpm run`, or `yarn run`, invent missing scripts, or invoke underlying tools such as `tsc`, `vitest`, `eslint`, or `prettier` directly. The Bun script-runner requirement does not choose the package manager used to install dependencies.",
+  ].join("\n");
+};
 
 const resolvePackageRoot = Effect.fn("resolvePackageRoot")(function* () {
   const path = yield* Path.Path;
@@ -521,6 +772,7 @@ const renderAgentInstructions = Effect.fn("renderAgentInstructions")(function* (
   packageRoot: string,
   projectDir: string,
   sourceBySkill: ReadonlyMap<string, ResolvedSkillSource>,
+  managesVitePlusQuality: boolean,
 ) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
@@ -538,6 +790,11 @@ const renderAgentInstructions = Effect.fn("renderAgentInstructions")(function* (
       message: `dev-kit agent instructions template is missing ${DEV_KIT_SKILL_PATH_PLACEHOLDER}`,
     });
   }
+  if (!template.includes(PROJECT_COMMAND_POLICY_PLACEHOLDER)) {
+    return yield* new InvalidProjectStateError({
+      message: `dev-kit agent instructions template is missing ${PROJECT_COMMAND_POLICY_PLACEHOLDER}`,
+    });
+  }
 
   const devKitSkill = sourceBySkill.get("dev-kit");
   const devKitSkillPath =
@@ -550,21 +807,22 @@ const renderAgentInstructions = Effect.fn("renderAgentInstructions")(function* (
             path.join(devKitSkill.linkPath ?? devKitSkill.path, "SKILL.md"),
           ),
         );
-  const sections = [template.replaceAll(DEV_KIT_SKILL_PATH_PLACEHOLDER, devKitSkillPath).trimEnd()];
-
-  if ((yield* readDirectDependencyNames(projectDir)).includes("vite-plus")) {
-    const vitePlusTemplate = path.join(projectDir, "node_modules", "vite-plus", "AGENTS.md");
-
-    if ((yield* observePath(vitePlusTemplate)).kind !== "file") {
-      return yield* new InvalidProjectStateError({
-        message:
-          "Vite+ is a direct dependency but its agent instructions are not a regular file: node_modules/vite-plus/AGENTS.md",
-      });
-    }
-    sections.push((yield* fs.readFileString(vitePlusTemplate)).trim());
-  }
-
-  return `${sections.join("\n\n")}\n`;
+  const usesVitePlus = (yield* readDirectDependencyNames(projectDir)).includes("vite-plus");
+  const projectPackage = yield* readProjectPackage(projectDir).pipe(
+    Effect.catchTag("ProjectPackageError", (error) =>
+      error.message.startsWith("package.json not found:") ? Effect.void : Effect.fail(error),
+    ),
+  );
+  const manager = yield* detectPackageManager(projectDir, projectPackage?.packageManager);
+  const commandPolicy = usesVitePlus
+    ? renderVitePlusCommandPolicy(projectPackage?.scripts ?? {}, managesVitePlusQuality)
+    : renderPackageScriptCommandPolicy(manager, projectPackage?.scripts ?? {});
+  const devKitInstructions = template
+    .replaceAll(DEV_KIT_SKILL_PATH_PLACEHOLDER, devKitSkillPath)
+    .replaceAll(PROJECT_COMMAND_POLICY_PLACEHOLDER, commandPolicy)
+    .trimEnd();
+
+  return `${devKitInstructions}\n`;
 });
 
 const readGeneratedFileTemplate = Effect.fn("readGeneratedFileTemplate")(function* (
@@ -597,7 +855,12 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
 
   if (setup.agentInstructions.enabled) {
     const managed = yield* resolveManagedPath(projectDir, "AGENTS.md");
-    const content = yield* renderAgentInstructions(packageRoot, projectDir, sourceBySkill);
+    const content = yield* renderAgentInstructions(
+      packageRoot,
+      projectDir,
+      sourceBySkill,
+      setup.vitePlus.quality.config.enabled,
+    );
 
     outputs.push({
       resourceId: "setup:agent-instructions",
@@ -662,7 +925,7 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
       devKitCommand:
         projectDir === packageRoot
           ? "./bin/dev-kit.mjs apply --locked"
-          : "vp exec dev-kit apply --locked",
+          : "bun ./node_modules/@danieljvdm/dev-kit/bin/dev-kit.mjs apply --locked",
       workflow: setup.vitePlus.quality.workflow,
     });
 
@@ -803,6 +1066,89 @@ const planDesiredOutputs = Effect.fn("planDesiredSkillOutputs")(function* (
         (rawModeObservation?.kind === matchingLockedOutput.kind &&
           rawModeObservation.digest === matchingLockedOutput.digest));
 
+    if (output.resourceId === "setup:agent-instructions" && "content" in output) {
+      if (observed.kind === "missing") {
+        actions.push({
+          action: "create",
+          desired: output,
+          observed,
+          stagedContent: output.content,
+        });
+        continue;
+      }
+      if (observed.kind !== "file") {
+        actions.push({
+          action: "conflict",
+          path: output.path,
+          reason: "destination is not a regular file",
+        });
+        continue;
+      }
+      const existingContent = yield* FileSystem.FileSystem.pipe(
+        Effect.flatMap((fs) => fs.readFileString(output.destination)),
+      );
+      const inspection = inspectManagedInstructionSections(existingContent);
+
+      if (inspection.kind === "invalid") {
+        actions.push({ action: "conflict", path: output.path, reason: inspection.reason });
+        continue;
+      }
+      const managedDigest =
+        inspection.content === undefined ? undefined : yield* digestFileContent(inspection.content);
+      const receiptOwnsManaged =
+        sameReceipt !== undefined &&
+        (managedDigest === sameReceipt.digest || observed.digest === sameReceipt.digest);
+      const lockOwnsManaged =
+        matchingLockedOutput !== undefined &&
+        (managedDigest === matchingLockedOutput.digest ||
+          observed.digest === matchingLockedOutput.digest);
+      const legacyOwnsWholeFile =
+        (sameReceipt !== undefined &&
+          observed.digest === sameReceipt.digest &&
+          managedDigest !== sameReceipt.digest) ||
+        (matchingLockedOutput !== undefined &&
+          lockedOwnsObserved &&
+          managedDigest !== matchingLockedOutput.digest);
+
+      if (managedDigest === output.digest && !legacyOwnsWholeFile) {
+        if (sameReceipt !== undefined || lockOwnsManaged || lockedOwnsObserved) {
+          actions.push({
+            action: "unchanged",
+            desired: output,
+            observed,
+            adopted: sameReceipt === undefined,
+          });
+        } else {
+          actions.push({
+            action: "conflict",
+            path: output.path,
+            reason: "managed instruction sections exist but are not owned",
+          });
+        }
+      } else if (
+        managedDigest === undefined ||
+        receiptOwnsManaged ||
+        lockOwnsManaged ||
+        lockedOwnsObserved
+      ) {
+        actions.push({
+          action: "update",
+          desired: output,
+          observed,
+          stagedContent: legacyOwnsWholeFile
+            ? output.content
+            : reconcileManagedInstructionSections(existingContent, inspection, output.content),
+        });
+      } else {
+        actions.push({
+          action: "conflict",
+          path: output.path,
+          reason: "managed instruction sections exist but are not owned",
+        });
+      }
+      continue;
+    }
+
     if (observed.kind === "missing") {
       actions.push({ action: "create", desired: output, observed });
     } else if (observed.kind === output.kind && observed.digest === output.digest) {
@@ -839,6 +1185,46 @@ const planDesiredOutputs = Effect.fn("planDesiredSkillOutputs")(function* (
     const observed = yield* observePath(managed.absolute);
 
     if (observed.kind === "missing") continue;
+    if (receipt.resourceId === "setup:agent-instructions") {
+      if (observed.kind !== "file") {
+        actions.push({
+          action: "conflict",
+          path: receipt.path,
+          reason: "stale owned destination is not a regular file",
+        });
+        continue;
+      }
+      const existingContent = yield* FileSystem.FileSystem.pipe(
+        Effect.flatMap((fs) => fs.readFileString(managed.absolute)),
+      );
+      const inspection = inspectManagedInstructionSections(existingContent);
+
+      if (inspection.kind === "invalid") {
+        actions.push({ action: "conflict", path: receipt.path, reason: inspection.reason });
+        continue;
+      }
+      if (inspection.content === undefined) continue;
+      const managedDigest = yield* digestFileContent(inspection.content);
+
+      if (managedDigest === receipt.digest || observed.digest === receipt.digest) {
+        const remaining = removeManagedInstructionSections(existingContent, inspection.ranges);
+
+        actions.push({
+          action: "remove",
+          previous: receipt,
+          destination: managed.absolute,
+          observed,
+          ...(remaining.trim().length === 0 ? {} : { stagedContent: remaining }),
+        });
+      } else {
+        actions.push({
+          action: "conflict",
+          path: receipt.path,
+          reason: "stale owned managed instruction sections were modified",
+        });
+      }
+      continue;
+    }
     if (observed.kind === receipt.kind && observed.digest === receipt.digest) {
       actions.push({
         action: "remove",
@@ -1110,16 +1496,6 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
   const currentLock = yield* readOptionalStructuredFile(lockManaged.absolute, DevKitLockSchema);
   const currentState = yield* readOptionalStructuredFile(stateManaged.absolute, AppliedStateSchema);
 
-  if (
-    manifest.setup.claudeInstructions.enabled &&
-    !manifest.setup.agentInstructions.enabled &&
-    currentState?.outputs.some((output) => output.resourceId === "setup:agent-instructions")
-  ) {
-    return yield* new InvalidProjectStateError({
-      message:
-        "cannot disable agentInstructions while claudeInstructions still links to its AGENTS.md wrapper",
-    });
-  }
   yield* validateReservedPaths(projectDir, reservedPaths, [
     ...(currentLock?.outputs ?? []),
     ...(currentState?.outputs ?? []),
@@ -1143,6 +1519,19 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
     currentState,
     nextLock,
   );
+  const removesClaudeInstructionsSource = planned.actions.some(
+    (action) =>
+      action.action === "remove" &&
+      action.previous.resourceId === "setup:agent-instructions" &&
+      action.stagedContent === undefined,
+  );
+
+  if (manifest.setup.claudeInstructions.enabled && removesClaudeInstructionsSource) {
+    return yield* new InvalidProjectStateError({
+      message:
+        "cannot disable agentInstructions while claudeInstructions still links to an AGENTS.md that would be removed",
+    });
+  }
 
   return {
     projectDir,
@@ -1310,13 +1699,28 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
   let stageIndex = 0;
 
   for (const action of mutating) {
-    if (action.action === "remove") continue;
+    if (action.action === "remove" && action.stagedContent === undefined) continue;
     const staged = path.join(stageDir, String(stageIndex++));
 
     yield* fs.makeDirectory(path.dirname(staged), { recursive: true });
-    if (action.desired.mode === "copy") {
+    if (action.stagedContent !== undefined && action.observed.kind === "file") {
+      const destination =
+        action.action === "remove" ? action.destination : action.desired.destination;
+
+      yield* fs.copy(destination, staged, { overwrite: true });
+      yield* fs.writeFileString(staged, action.stagedContent);
+    } else if (action.action === "remove") {
+      if (action.stagedContent === undefined) {
+        return yield* new InvalidProjectStateError({
+          message: `missing staged content for ${action.previous.resourceId}`,
+        });
+      }
+      yield* fs.writeFileString(staged, action.stagedContent, { mode: 0o644 });
+    } else if (action.desired.mode === "copy") {
       if (action.desired.kind === "file") {
-        yield* fs.writeFileString(staged, action.desired.content, { mode: 0o644 });
+        yield* fs.writeFileString(staged, action.stagedContent ?? action.desired.content, {
+          mode: 0o644,
+        });
       } else {
         yield* fs.copy(action.desired.source, staged, { overwrite: true });
         const symbolicLink = yield* findNestedSymbolicLink(staged);
@@ -1330,14 +1734,35 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
     } else {
       yield* fs.symlink(action.desired.linkTarget, staged);
     }
-    const observation = yield* observePath(staged);
-
-    if (observation.kind !== action.desired.kind || observation.digest !== action.desired.digest) {
-      return yield* new InvalidProjectStateError({
-        message: `staged output digest mismatch for ${action.desired.path}`,
-      });
+    if (action.action !== "remove") {
+      const observation = yield* observePath(staged);
+
+      if (action.desired.resourceId === "setup:agent-instructions") {
+        const content = yield* fs.readFileString(staged);
+        const inspection = inspectManagedInstructionSections(content);
+        const digest =
+          inspection.kind === "valid" && inspection.content !== undefined
+            ? yield* digestFileContent(inspection.content)
+            : undefined;
+
+        if (observation.kind !== "file" || digest !== action.desired.digest) {
+          return yield* new InvalidProjectStateError({
+            message: `staged output digest mismatch for ${action.desired.path}`,
+          });
+        }
+      } else if (
+        observation.kind !== action.desired.kind ||
+        observation.digest !== action.desired.digest
+      ) {
+        return yield* new InvalidProjectStateError({
+          message: `staged output digest mismatch for ${action.desired.path}`,
+        });
+      }
     }
-    stagedByResource.set(action.desired.resourceId, staged);
+    stagedByResource.set(
+      action.action === "remove" ? action.previous.resourceId : action.desired.resourceId,
+      staged,
+    );
   }
 
   yield* verifyPackageSkillSources(plan);
@@ -1360,11 +1785,18 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
 
   for (const action of mutating) {
     const staged =
-      action.action === "remove" ? undefined : stagedByResource.get(action.desired.resourceId);
+      action.action === "remove"
+        ? stagedByResource.get(action.previous.resourceId)
+        : stagedByResource.get(action.desired.resourceId);
 
-    if (action.action !== "remove" && staged === undefined) {
+    if (
+      (action.action !== "remove" || action.stagedContent !== undefined) &&
+      staged === undefined
+    ) {
       return yield* new InvalidProjectStateError({
-        message: `missing staged output for ${action.desired.resourceId}`,
+        message: `missing staged output for ${
+          action.action === "remove" ? action.previous.resourceId : action.desired.resourceId
+        }`,
       });
     }
     replacements.push({

package/src/vite-plus-quality.ts

@@ -32,7 +32,8 @@ export type VitePlusQualitySelection = {
 };
 
 const SINGLE_PROJECT_TYPECHECK_TASK = '      typecheck: "tsc --noEmit",';
-const LOCKED_DEV_KIT_COMMAND = "vp exec dev-kit apply --locked";
+const LOCKED_DEV_KIT_COMMAND =
+  "bun ./node_modules/@danieljvdm/dev-kit/bin/dev-kit.mjs apply --locked";
 const BEFORE_CHECKS_MARKER =
   "      # Dev Kit inserts configured quality.workflow.beforeChecks steps here.\n\n";
 const DEFAULT_WORKFLOW_TYPECHECK = `      - name: Type check with Effect TypeScript-Go

package/templates/AGENTS.md

@@ -6,4 +6,6 @@ This project uses `@danieljvdm/dev-kit` to manage portable agent skills and repr
 
 For dev-kit operations, use the `dev-kit` skill and read `{{DEV_KIT_SKILL_PATH}}` before changing managed outputs.
 
+{{PROJECT_COMMAND_POLICY}}
+
 <!-- DEV KIT END -->

package/templates/vite-plus/github-actions-check.yml

@@ -22,6 +22,10 @@ jobs:
         with:
           persist-credentials: false
 
+      # setup-bun resolves the consumer's packageManager or engines.bun version.
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # setup-bun action v2.2.0
+
       # setup-vp's v1 tag is frozen. Keep this v1.16.1 commit current with
       # Renovate or Dependabot so fixes arrive through reviewed pull requests.
       - name: Set up Vite+ and install dependencies
@@ -34,7 +38,7 @@ jobs:
             args: ["--frozen-lockfile", "--ignore-scripts"]
 
       - name: Verify locked Dev Kit setup
-        run: vp exec dev-kit apply --locked
+        run: bun ./node_modules/@danieljvdm/dev-kit/bin/dev-kit.mjs apply --locked
 
       # Dev Kit inserts configured quality.workflow.beforeChecks steps here.