@danieljvdm/dev-kit 0.18.0 → 1.0.0

package/README.md

@@ -1,737 +1,226 @@
 # Dev Kit
 
-Portable agent skills and reproducible project setup, managed from one manifest.
+Agent-led TypeScript repository setup and a curated catalog of portable coding
+skills.
 
-Dev Kit gives every project the same development conventions without requiring a
-collection of unrelated postinstall scripts. It can:
+Dev Kit is a transient toolbox. It copies guidance into a repository, helps an
+agent build the requested setup against the repository's real constraints, and
+then gets out of the way. Generated source, configuration, workflows, scripts,
+and skills belong to the repository that receives them.
 
-- install selected skills for Codex, Claude, and OpenCode;
-- run explicit setup tasks such as version-matched Effect source checkout and
-  Effect TypeScript-Go patching;
-- preview changes before writing them;
-- lock resolved outputs for reproducible installs; and
-- detect ownership conflicts without overwriting user files.
+The finished repository has no Dev Kit dependency, manifest, lock, ownership
+state, postinstall manager, or CI reconciliation step.
 
-## Quick start
+The package intentionally exposes no importable JavaScript API. Its public
+surface is the transient executable and the guidance or skills it copies.
 
-Install the published Dev Kit package:
+## Set up a repository
 
-```bash
-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:
+From a new or existing repository, copy the Dev Kit setup skill:
 
 ```bash
-bun x dev-kit init
-bun x dev-kit list --all
-bun x dev-kit add dev-kit effect
+bunx @danieljvdm/dev-kit@latest setup
 ```
 
-Before adding external skills, have the agent inspect repository instructions,
-workspace dependencies, framework and tool configuration, representative
-source boundaries, and CI workflows. It should compare that concrete capability
-inventory with catalog descriptions and select the narrowest useful set. Broad
-umbrella skills and source families belong only when their full breadth is
-intentional; explicit creative or advisory requests remain valid even without a
-mechanical dependency signal. Treat lazy reference folders inside one skill as
-progressive-disclosure content, not as separately triggered skills; a repository
-using several covered products may reasonably select that umbrella while still
-excluding unrelated top-level skills.
+This writes `.agents/skills/dev-kit` and a small origin receipt inside that skill.
+It does not edit `package.json` or create project-wide Dev Kit metadata.
 
-Search and inspect candidates, then add the matching skills individually:
+Then ask the coding agent for the outcome:
 
-```bash
-bun x dev-kit search cloudflare
-bun x dev-kit info workers-best-practices
-bun x dev-kit add workers-best-practices wrangler
-```
+> Use $dev-kit to set up this repository as a Vite+ TypeScript monorepo with an
+> Effect-based Cloudflare Worker API and a web application.
 
-`add` updates `dev-kit.jsonc` and applies the selection immediately. The
-resulting manifest is ordinary JSONC:
-
-In an interactive terminal, `dev-kit add` and `dev-kit remove` with no names
-open a multi-select picker. Pass several names to change them in one command,
-or use `--no-apply` to edit the manifest without syncing yet.
-
-```jsonc
-{
-  "$schema": "./node_modules/@danieljvdm/dev-kit/schema/dev-kit.schema.json",
-  "include": ["dev-kit", "effect"],
-  "targets": {
-    "agents": { "enabled": true, "mode": "copy" },
-    "claude": { "enabled": true, "mode": "symlink" },
-  },
-}
-```
+The skill inventories the repository, loads only the applicable setup references,
+resolves material product decisions, implements ordinary repo-owned files, and
+validates through the resulting repository's own commands.
 
-For review-first workflows, edit the manifest or pass `--no-apply`, then:
+For an empty directory, the agent establishes the package and toolchain foundation
+before consulting documentation shipped by the installed dependencies. For an
+existing repository, it integrates with established package boundaries, scripts,
+configuration, and CI instead of replacing them with a fixed template.
 
-```bash
-bun x dev-kit plan
-bun x dev-kit apply
-```
+## The ownership contract
 
-Commit the generated `dev-kit.lock.json`, then let the package lifecycle
-converge owned outputs automatically when installed packages change:
+Dev Kit commands are transactions, not reconciliation:
 
-```jsonc
-{
-  "scripts": {
-    "postinstall": "dev-kit apply",
-  },
-}
-```
+- `setup` copies the agent-led setup skill once.
+- `skills add` copies selected skills once.
+- `skills update` refreshes an unchanged tracked skill when requested.
+- `eject` releases projects created by the legacy managed model.
+- toolbox commands perform an explicit diagnostic or mechanical operation.
 
-That single postinstall applies every task enabled in `dev-kit.jsonc` and
-regenerates `dev-kit.lock.json` when an intentional package upgrade changes a
-bundled or package-provided skill. Ownership and conflict checks still prevent
-unreviewed overwrites.
+Git records the resulting project state. Dev Kit does not remember the desired
+shape of the repository and does not silently rewrite configuration after setup.
 
-Keep strict verification in CI. Either install with lifecycle scripts disabled
-before running locked mode:
+## Commands
 
-```bash
-bun install --ignore-scripts
-bun ./node_modules/@danieljvdm/dev-kit/bin/dev-kit.mjs apply --locked
-```
+| Command                                        | Purpose                                                            |
+| ---------------------------------------------- | ------------------------------------------------------------------ |
+| `dev-kit setup`                                | Copy the agent-led Dev Kit skill into `.agents/skills`.            |
+| `dev-kit skills list --all`                    | Browse built-in, approved Git, and installed-package skills.       |
+| `dev-kit skills search <words...>`             | Search skill names, descriptions, and sources.                     |
+| `dev-kit skills info <skill>`                  | Show one skill's description and provenance.                       |
+| `dev-kit skills add <skill...>`                | Copy repo-owned skills without a manifest.                         |
+| `dev-kit skills status`                        | Compare tracked copies with their approved upstream content.       |
+| `dev-kit skills update [skill...]`             | Fast-forward tracked skills that have no local edits.              |
+| `dev-kit skills diff <skill>`                  | Diff a repository copy against the latest approved upstream.       |
+| `dev-kit skills update <skill> --accept-local` | Keep an agent-merged copy and advance its upstream base.           |
+| `dev-kit skills detach <skill...>`             | Remove origin receipts while preserving local content.             |
+| `dev-kit eject [--dry-run]`                    | Release a legacy managed project into repo ownership.              |
+| `dev-kit effect sync`                          | Explicitly sync an Effect source checkout to an installed version. |
+| `dev-kit tsgo patch`                           | Explicitly patch the installed Effect TypeScript-Go compiler.      |
+| `dev-kit cache prune`                          | Remove stale machine-global catalog checkouts.                     |
 
-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`.
+Commands that write project skills accept `--project-dir`, `--target`, and
+`--dry-run`. The default target is `.agents/skills`.
 
-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:
+Run any command with `--help` for its complete flags.
 
-```bash
-bun run dev-kit plan
-bun run dev-kit apply --locked
-```
+## Skills
 
-`bun x dev-kit` is for consuming projects where installation has created the
-`node_modules/.bin/dev-kit` link; package managers do not create that link for
-the root package itself.
+Dev Kit combines three sources:
 
-## Commands
+- skills bundled with this package;
+- exact commits from an approved external Git catalog; and
+- skills discovered in direct project dependencies that expose compatible
+  package metadata.
 
-| Command                                    | Purpose                                                   |
-| ------------------------------------------ | --------------------------------------------------------- |
-| `dev-kit`                                  | Show selected skills and the four common next actions.    |
-| `dev-kit init`                             | Create a minimal `dev-kit.jsonc`.                         |
-| `dev-kit add <skill...>`                   | Select and immediately install skills.                    |
-| `dev-kit remove <skill...>`                | Deselect and uninstall skills safely.                     |
-| `dev-kit list [--all]`                     | List selected skills or browse the catalog.               |
-| `dev-kit search <words...>`                | Search names and descriptions.                            |
-| `dev-kit info <skill>`                     | Show description and Git or installed-package provenance. |
-| `dev-kit status`                           | Check whether the project matches its selection.          |
-| `dev-kit sync`                             | Apply the current manifest.                               |
-| `dev-kit plan`                             | Preview project changes without writing files.            |
-| `dev-kit apply`                            | Apply the manifest and update `dev-kit.lock.json`.        |
-| `dev-kit apply --locked`                   | Reproduce the committed lock or fail on drift.            |
-| `dev-kit gitignore`                        | Add `.repos/` and `.dev-kit/` to `.gitignore`.            |
-| `dev-kit effect sync`                      | Sync `.repos/effect` to the installed Effect version.     |
-| `dev-kit tsgo patch`                       | Validate and patch Effect TypeScript-Go directly.         |
-| `dev-kit cache prune`                      | Evict stale machine-global cache content (`--all` wipes). |
-| `dev-kit catalog refresh`                  | Maintainer command to approve current upstream refs.      |
-| `dev-kit catalog add <repository>`         | Inspect a repository and approve selected skills.         |
-| `dev-kit catalog remove <source-or-skill>` | Revoke an approval (`--yes` outside a terminal).          |
-| `dev-kit catalog list`                     | List approved upstream repositories.                      |
-| `dev-kit catalog info <source>`            | Show a source, commit, and approved skills.               |
-| `dev-kit catalog verify`                   | Verify the committed snapshot without advancing refs.     |
-
-Options vary by command and include `--dry-run`, `--manifest`, `--lockfile`,
-and `--project-dir`. Run any command with `--help` for its complete usage.
-
-## How it works
-
-Dev Kit uses three project-local files:
-
-| Path                  | Role                                                    | Commit it? |
-| --------------------- | ------------------------------------------------------- | ---------- |
-| `dev-kit.jsonc`       | Desired skills, targets, and setup tasks.               | Yes        |
-| `dev-kit.lock.json`   | Resolved content digests and setup-tool versions.       | Yes        |
-| `.dev-kit/state.json` | Local ownership receipts used during apply and cleanup. | No         |
-
-Skills are copied into `.agents/skills` by default. Other harness targets can
-copy or symlink those project-local skills.
-
-Dev Kit only changes paths represented by the manifest. Existing unknown files,
-modified managed files, and unsafe symlink paths are reported as conflicts and
-left untouched. Cleanup removes only unchanged outputs with a matching local
-ownership receipt.
-
-Locked mode rejects changes to the manifest, packaged skill content, or setup
-tool versions. A project-local process lock also prevents concurrent applies.
-
-## Manifest
-
-`include` accepts static skill names, skill families, and explicit
-`<package>#<skill>` selectors:
-
-```jsonc
-{
-  "$schema": "./node_modules/@danieljvdm/dev-kit/schema/dev-kit.schema.json",
-  "include": [
-    "dev-kit",
-    "effect",
-    "open-pull-request",
-    "workers-best-practices",
-    "wrangler",
-    "serve-sim",
-    "@tanstack/ai#ai-core",
-  ],
-  "exclude": ["animation-vocabulary"],
-  "setup": {
-    "agentInstructions": { "enabled": true },
-    "claudeInstructions": { "enabled": true },
-  },
-  "targets": {
-    "agents": { "enabled": true, "mode": "copy" },
-    "claude": { "enabled": true, "mode": "symlink" },
-    "opencode": { "enabled": false, "mode": "symlink" },
-  },
-}
-```
+Search the catalog before copying:
 
-- `dev-kit` installs guidance for operating the toolkit itself.
-- `effect` is a built-in family: the `effect-ts` bootstrap,
-  `effect-architecture-audit`, `build-effect-apis`, `effect-atom-state`, and
-  `build-effect-clis`.
-- External Git skills (`workers-best-practices`, `serve-sim`, …) are selected
-  individually after scanning the project for relevant technologies. An
-  approved source ID selects every skill from that source; use it only when
-  the scan confirms that every member applies.
-- `@tanstack/ai#ai-core` explicitly selects a skill discovered in that direct
-  project dependency; discovery alone never selects it.
-
-Dev Kit reserves `.repos/<source-id>` for project-local source checkouts. Run
-`dev-kit gitignore` to add `.repos/` and `.dev-kit/` to the project ignore file.
-The patch is idempotent, preserves existing lines, and refuses symlinked
-`.gitignore` files.
-
-## Agent instructions
-
-Enable managed project-root instruction sections and a portable Claude Code
-bridge in the manifest:
-
-```jsonc
-{
-  "include": ["dev-kit"],
-  "setup": {
-    "agentInstructions": { "enabled": true },
-    "claudeInstructions": { "enabled": true },
-  },
-}
+```bash
+bunx @danieljvdm/dev-kit@latest skills search cloudflare
+bunx @danieljvdm/dev-kit@latest skills info workers-best-practices
+bunx @danieljvdm/dev-kit@latest skills add workers-best-practices wrangler
 ```
 
-`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 — toolchain overview, help
-and documentation entry points, `vp env doctor` troubleshooting — rather than
-importing Vite+'s generic `AGENTS.md`, which can contradict the repository's
-exact commands; transitive installations do not opt a project in. 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 the manifest enables the Vite+ workflow scaffold,
-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 section-managed file in the same apply,
-or retain the older behavior of linking to an existing regular `AGENTS.md` when
-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
-
-Enable Vite+'s project-local Git hook dispatcher in the manifest:
-
-```jsonc
-{
-  "include": ["dev-kit"],
-  "setup": {
-    "vitePlus": { "hooks": { "enabled": true } },
-  },
-}
-```
+Source families select every approved skill from one source and are intentionally
+broad. Prefer individual skills unless every family member applies.
 
-`dev-kit apply` requires `vite-plus` as an installed direct dependency and runs
-its project-local `vp config --no-agent` command when hook setup is missing. The
-generated `.vite-hooks/_` dispatcher is ignored by Git, so every linked
-worktree converges its own copy during install while the project-owned
-`.vite-hooks/pre-commit` hook remains portable. Dev Kit preserves an unrelated
-`core.hooksPath` instead of replacing another hook manager. Set
-`VITE_GIT_HOOKS=0` (or `HUSKY=0`) to skip the task for that invocation.
-
-## Vite+ quality setup
-
-The repository always owns `vite.config.ts`. Compose Dev Kit's quality defaults
-from that project-owned config, then opt into the scaffolded GitHub Actions
-workflow independently:
-
-```ts
-import { createRecommendedVitePlusConfig } from "@danieljvdm/dev-kit/vite-plus";
-import { defineConfig } from "vite-plus";
-
-const recommended = createRecommendedVitePlusConfig({
-  ignorePatterns: ["apps/api/worker-configuration.d.ts", "apps/web/src/routeTree.gen.ts"],
-});
-
-export default defineConfig({
-  ...recommended,
-  // Project-owned Vite, test, build, and framework options stay local.
-  server: { port: 5173 },
-});
-```
+Package skills use the exact `<package>#<skill>` selector:
 
-Spread the returned top-level config before local options. When overriding a
-`fmt`, `lint`, `run`, or `staged` block, spread that returned block as well so
-its defaults remain composed. Merge nested collections too; for example, a
-local lint rule block starts with `...recommended.lint.rules` before adding
-repository-specific rules.
-
-The factory configures `vp staged`, matching Oxlint/Oxfmt ignores for Dev Kit's
-tool-owned paths, and separate `vp run check` and pure `vp run typecheck` tasks.
-Project and framework-generated paths belong in `ignorePatterns` as shown;
-custom harness target paths belong there too. Dev Kit does not grow a global
-framework ignore list.
-
-```jsonc
-{
-  "include": ["dev-kit", "effect"],
-  "setup": {
-    "effectTsgo": { "enabled": true },
-    "vitePlus": {
-      "hooks": { "enabled": true },
-      "workflow": { "enabled": true },
-    },
-  },
-}
+```bash
+bunx @danieljvdm/dev-kit@latest skills add @tanstack/ai#ai-core
 ```
 
-`setup.vitePlus.workflow` scaffolds `.github/workflows/check.yml` and never
-reads, rewrites, adopts, or removes `vite.config.ts`. Scaffolds are
-create-only: the file is written only when missing, never recorded in
-`dev-kit.lock.json`, and never touched again — the repository owns it from
-creation, and disabling the task leaves it in place. Edit the YAML directly
-for repository-specific preparation steps or a custom typecheck command; when
-the shipped template improves, compare against the installed copy under
-`node_modules/@danieljvdm/dev-kit/templates/` and merge what fits.
-Scaffolding requires direct `@danieljvdm/dev-kit`, `vite-plus`, `effect`,
-`@effect/tsgo`, and native TypeScript dependencies with
-`setup.effectTsgo.enabled`, and the installed Vite+ must satisfy Dev Kit's
-peer range.
-
-Workspaces select bounded, dependency-ordered typechecking in their config:
-
-```ts
-export default defineConfig(
-  createRecommendedVitePlusConfig({
-    typecheck: {
-      strategy: "workspace",
-      concurrency: 4,
-      packages: ["apps/web", "packages/core"],
-    },
-  }),
-);
-```
+The package must already be a direct, installed dependency. Dev Kit never
+downloads a missing package or executes package-provided discovery code.
 
-Each listed package must expose a pure `typecheck` script.
-
-The scaffolded workflow performs one frozen, script-suppressed install, runs
-`dev-kit apply --locked`, and only then runs formatting, linting, tests, and
-`vp run typecheck`. 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
-templates.
-
-### Absolute (path-alias) imports
-
-Opt into enforcing path-alias imports for selected app sources. The factory
-appends an Oxlint override that errors on `../` imports inside the given
-globs, so those files import through tsconfig path aliases such as `@/*`:
-
-```ts
-export default defineConfig(
-  createRecommendedVitePlusConfig({
-    absoluteImports: {
-      files: ["apps/app/src/**/*.{ts,tsx}", "apps/mobile/src/**/*.{ts,tsx}"],
-    },
-  }),
-);
-```
+### Origin receipts
 
-The lint rule only forbids relative parent imports; each covered app must map
-the alias itself. Add the `paths` entry to the app's `tsconfig.json`:
+Each copied skill contains `.dev-kit-origin.json`:
 
-```jsonc
-{
-  "compilerOptions": {
-    "paths": { "@/*": ["./src/*"] },
-  },
-}
+```text
+.agents/skills/workers-best-practices/
+├── SKILL.md
+├── references/
+└── .dev-kit-origin.json
 ```
 
-Vite-built apps also resolve the alias from the same tsconfig by setting
-`resolve: { tsconfigPaths: true }` in the app's Vite config. Expo apps need no
-Metro configuration: Expo SDK 49+ resolves tsconfig `paths` by default.
-
-Standalone Oxlint projects compose the same override directly:
+The receipt identifies that artifact's selector, approved source, and base
+digest. It does not enumerate other skills, express desired project state, or
+run automatically.
 
-```ts
-// oxlint.config.ts
-import {
-  createAbsoluteImportsOxlintOverride,
-  recommendedOxlintConfig,
-} from "@danieljvdm/dev-kit/oxlint";
-import { defineConfig } from "oxlint";
+An unmodified tracked skill can fast-forward safely:
 
-export default defineConfig({
-  extends: [recommendedOxlintConfig],
-  overrides: [createAbsoluteImportsOxlintOverride({ files: ["src/**/*.{ts,tsx}"] })],
-});
+```bash
+bunx @danieljvdm/dev-kit@latest skills status
+bunx @danieljvdm/dev-kit@latest skills update
 ```
 
-## Worktrunk project config
+When both the repository and upstream changed, Dev Kit preserves the local copy:
 
-Enable a scaffolded default [Worktrunk](https://worktrunk.dev) project config
-in the manifest:
-
-```jsonc
-{
-  "include": ["dev-kit"],
-  "setup": {
-    "worktrunk": { "config": { "enabled": true } },
-  },
-}
+```bash
+bunx @danieljvdm/dev-kit@latest skills diff workers-best-practices
 ```
 
-`setup.worktrunk.config` scaffolds `.config/wt.toml` with the portable hooks an
-app repository wants in every worktree: a `pre-start` pipeline that copies
-gitignored files matched by `.worktreeinclude` (a no-op without that file) and
-then installs dependencies, plus a `pre-merge` full-validation hook. Hook
-commands render for the repository's command runner: a direct `vite-plus`
-dependency selects `vp install` and `vp run check`; otherwise Dev Kit requires
-a declared root `check` package script, runs it through `bun run check`, and
-takes the install command from the detected package manager. Repositories with
-neither fail the plan instead of shipping a broken hook.
-
-The config follows the same create-only scaffold semantics as the check
-workflow above: created once, never locked or touched again, owned by the
-repository. Edit hooks freely after creation.
-
-The config intentionally carries no worktree-path template or other user
-preferences—those belong in each user's `~/.config/worktrunk/config.toml`. A
-commented `post-start` block shows how to run a per-worktree dev server on a
-stable branch-derived port (`{{ branch | hash_port }}`) under `wt step tether`;
-point it at the repository's dev entrypoint and uncomment to opt in. Worktrunk
-never runs project hooks until each user approves them with
-`wt config approvals add`.
-
-## Effect source checkout
-
-Enable a local checkout of the exact installed Effect release in the manifest:
-
-```jsonc
-{
-  "include": ["effect"],
-  "setup": {
-    "effectSource": { "enabled": true },
-  },
-}
-```
+Ask the agent to merge applicable upstream intent. After reviewing the merged
+skill, advance its recorded base without overwriting it:
 
-`dev-kit apply` reads `node_modules/effect/package.json`, then shallow-clones or
-updates `.repos/effect` to the detached `effect@<version>` tag. Tag fetches go
-through a shared clone in the machine-global cache, so a new worktree or
-project reuses tags already cached on the machine and only contacts the
-network for a tag the cache has never seen. It skips the checkout in CI,
-leaves the repository in place when the task is disabled, and refuses to
-switch a checkout with local changes or an unexpected origin.
-
-The path, package name, and repository URL may be overridden for compatible
-Effect package layouts. Use `dev-kit effect sync --dry-run` to inspect this
-task directly.
-
-## Effect TypeScript-Go
-
-Enable Effect TypeScript-Go in the same manifest:
-
-```jsonc
-{
-  "include": ["effect"],
-  "setup": {
-    "effectSource": { "enabled": true },
-    "effectTsgo": { "enabled": true },
-  },
-}
+```bash
+bunx @danieljvdm/dev-kit@latest skills update workers-best-practices --accept-local
 ```
 
-Pin the compatible packages in the consuming project:
+To sever the upstream relationship entirely:
 
-```jsonc
-{
-  "devDependencies": {
-    "@danieljvdm/dev-kit": "^0.2.0",
-    "@effect/tsgo": "0.36.4",
-    "typescript": "7.0.2",
-  },
-}
-```
-
-```jsonc
-{
-  "$schema": "./node_modules/@effect/tsgo/schema.json",
-  "compilerOptions": {
-    "plugins": [
-      {
-        "name": "@effect/language-service",
-        "diagnosticSeverity": {
-          "anyUnknownInErrorContext": "warning",
-          "instanceOfSchema": "suggestion",
-          "nestedEffectGenYield": "suggestion",
-          "newSchemaClass": "suggestion",
-          "preferSchemaTypeProperty": "suggestion",
-          "unsafeEffectTypeAssertion": "warning",
-        },
-        "overrides": [
-          {
-            "include": ["src/**/*.ts"],
-            "options": {
-              "diagnosticSeverity": {
-                "nodeBuiltinImport": "warning",
-                "preferSchemaOverJson": "suggestion",
-              },
-            },
-          },
-        ],
-      },
-    ],
-  },
-}
+```bash
+bunx @danieljvdm/dev-kit@latest skills detach workers-best-practices
 ```
 
-`dev-kit apply` validates both exact version pins and patches the project-local
-native TypeScript compiler. It does not download dependencies and skips an
-installation that is already patched. Use `dev-kit tsgo patch --dry-run` when
-troubleshooting the task directly.
+Only the receipt is removed. The skill remains ordinary repository content.
 
-The same typed object is exported as `recommendedEffectTsgoPlugin` for
-programmatic configuration tooling. Dependency and `tsconfig.json` edits remain
-explicit. In a monorepo, put the plugin in the shared root config and ensure
-every workspace extends it without redeclaring `compilerOptions.plugins`:
-TypeScript replaces that array in child configs rather than merging it. Adjust
-the `src/**/*.ts` override to the source layout seen from each config file.
+## Eject a legacy managed project
 
-## Installed package skills
+Projects from the previous Dev Kit model may contain:
 
-Dev Kit generically discovers agent skills bundled by the project's installed
-JavaScript packages. It reads the project's direct dependencies, checks the
-package's Intent v1 discovery metadata (or Intent's repository-metadata
-fallback), then looks for the layout
-`node_modules/<package>/skills/<skill>/SKILL.md`.
-TanStack is one publisher of this layout; no TanStack package names or skill
-paths are hard-coded into Dev Kit.
+- `dev-kit.jsonc`;
+- `dev-kit.lock.json`;
+- `.dev-kit/state.json`;
+- managed sections in `AGENTS.md`;
+- `dev-kit apply` lifecycle or CI commands; and
+- runtime imports such as `@danieljvdm/dev-kit/vite-plus`.
 
-Discovery is browse-only. These commands show an installed package skill but do
-not select, copy, symlink, lock, or otherwise install it:
+Preview the migration directly:
 
 ```bash
-bun x dev-kit list --all
-bun x dev-kit search tanstack
-bun x dev-kit info @tanstack/ai#ai-core
+bunx @danieljvdm/dev-kit@latest eject --dry-run
 ```
 
-Selection is explicit and package-qualified:
+Dry-run reports recurring behaviors that still need repo-owned replacements.
+Typical examples are local Vite+/Oxlint/Oxfmt configuration, Effect compiler
+patching, source checkouts, and Git hook generation.
 
-```bash
-bun x dev-kit add @tanstack/ai#ai-core
-```
-
-That writes `@tanstack/ai#ai-core` to `dev-kit.jsonc` and, unless
-`--no-apply` is passed, installs it through the normal ownership-safe sync
-path. The qualifier prevents ambiguity when two dependencies publish the same
-skill name, and the installed output carries it: the copied directory flattens
-the package name and appends the skill name (`@tanstack/ai#ai-core` →
-`tanstack-ai-ai-core`), and the copied `SKILL.md` frontmatter `name:` is
-rewritten to match because harnesses identify a skill by its directory name.
-Symlink-mode targets link straight into `node_modules`, so only the link
-carries the qualified name. Two selections that would write the same
-destination are rejected before any output changes.
-
-The compatibility boundary is intentionally small and deterministic: only the
-root project's direct dependencies are scanned, package code is never imported
-or executed, npm-style and pnpm/workspace symlinks are supported (Yarn
-Plug'n'Play and transitive traversal are not), and only immediate
-`skills/<name>/SKILL.md` roots are listed — nested topic skills and references
-are copied as part of their root.
-
-The project `dev-kit.lock.json` records the selected package name, installed
-version, original bare skill name, and the `node_modules` content digest.
-`apply --locked` therefore rejects package-version or skill-content drift.
-Dev Kit never downloads a missing package or substitutes a registry version.
-
-See TanStack's
-[Agent Skills documentation](https://tanstack.com/ai/latest/docs/getting-started/agent-skills)
-for a real package suite that uses this convention.
-
-## Approved external Git skills
-
-This repository remains an opinionated catalog for Git-hosted skills.
-`skill-sources.jsonc` contains only reviewed Git sources:
-
-```jsonc
-{
-  "$schema": "./schema/skill-sources.schema.json",
-  "sources": [
-    {
-      "id": "emilkowalski-skills",
-      "repository": "https://github.com/emilkowalski/skills.git",
-      "ref": "main",
-      "skillsPath": "skills",
-      "include": ["*"],
-      "licensePath": "LICENSE",
-    },
-  ],
-}
-```
-
-Maintainers approve a new upstream snapshot with:
+After the agent materializes those behaviors, run:
 
 ```bash
-bun run catalog:refresh
-bun run catalog:check
+bunx @danieljvdm/dev-kit@latest eject
 ```
 
-Adding a Git source does not require editing JSONC:
+The command:
 
-```bash
-dev-kit catalog add https://github.com/owner/repository
-dev-kit catalog add https://github.com/owner/repository \
-  --skill one --skill two
-dev-kit catalog add https://github.com/owner/repository --all
-```
-
-GitHub tree URLs are accepted. `--all` expands to the skills found at that
-exact snapshot; it never writes a wildcard that could silently approve a future
-upstream addition. Catalog refresh resolves refs to exact commits, validates
-names and paths, rejects symlinks and collisions, extracts descriptions, and
-updates `skill-sources.lock.json`.
-
-When a project selects one of these Git-backed skills, Dev Kit fetches the
-approved commit into a machine-global cache and installs it through the same
-ownership-safe sync path. Cache entries are keyed by resolved commit SHA, so
-every project and git worktree on the machine shares one download; a warm
-`dev-kit plan` or `dev-kit apply` performs no network operations. The cache
-lives in `$XDG_CACHE_HOME/dev-kit` (falling back to `~/Library/Caches/dev-kit`
-on macOS and `~/.cache/dev-kit` elsewhere) and may be overridden with
-`DEV_KIT_CACHE_DIR`; it is safe to delete at any time. Populating this
-immutable commit-keyed cache is not project state, so planning and `--locked`
-verification use it too. Only a reviewed catalog refresh changes the approved
-Git content.
-
-The cache does not grow without bounds: every use refreshes a recency stamp,
-and `dev-kit apply` sweeps content unused for 30 days at most once a day.
-Shared Effect repositories drop unused tags individually and are removed whole
-once empty. Run `dev-kit cache prune` to sweep on demand (`--max-age-days` to
-tune the threshold, `--all` to clear the cache entirely); an evicted entry is
-simply fetched again the next time a project needs it.
-
-## Oxlint and Oxfmt configurations
-
-Dev Kit exports typed Oxlint/Oxfmt presets for standalone Oxc projects. The
-Vite+ factory composes both presets and keeps their tool-path ignores aligned:
-
-```ts
-import { createRecommendedVitePlusConfig } from "@danieljvdm/dev-kit/vite-plus";
-import { defineConfig } from "vite-plus";
-
-export default defineConfig(createRecommendedVitePlusConfig());
-```
-
-The shared lint preset enables `typeAware` for semantic lint rules but leaves
-`typeCheck` disabled. Effect TypeScript-Go projects run:
-
-```sh
-vp fmt --check
-vp lint
-vp test
-vp run typecheck
-```
+- preserves and releases managed agent instructions;
+- converts safe legacy skill outputs into repo-owned copies with origin receipts;
+- removes the Dev Kit dependency and pure apply scripts;
+- removes the known legacy CI verification step; and
+- deletes the manifest, lock, and local ownership receipt.
 
-Standalone projects import the same objects from their native config files:
+It stops before writing when a managed setup task, runtime import, ambiguous
+script, modified destination, unsafe path, or malformed marker still needs human
+or agent judgment. Regenerate the package-manager lockfile and run the full
+repository validation after ejection.
 
-```ts
-// oxlint.config.ts
-import { recommendedOxlintConfig } from "@danieljvdm/dev-kit/oxlint";
-import { defineConfig } from "oxlint";
+## Approved catalog maintenance
 
-export default defineConfig({
-  extends: [recommendedOxlintConfig],
-});
-```
-
-```ts
-// oxfmt.config.ts
-import { recommendedOxfmtConfig } from "@danieljvdm/dev-kit/oxfmt";
-import { defineConfig } from "oxfmt";
+External skill sources are authored in `skill-sources.jsonc` and approved as
+exact commits in `skill-sources.lock.json`. These are package-maintainer files,
+not consumer project state.
 
-export default defineConfig({
-  ...recommendedOxfmtConfig,
-});
-```
+| Command                                    | Purpose                                               |
+| ------------------------------------------ | ----------------------------------------------------- |
+| `dev-kit catalog add <repository>`         | Inspect a repository and approve selected skills.     |
+| `dev-kit catalog remove <source-or-skill>` | Revoke an approval.                                   |
+| `dev-kit catalog list`                     | List approved sources.                                |
+| `dev-kit catalog info <source>`            | Show one source's commit and skills.                  |
+| `dev-kit catalog refresh`                  | Advance approved refs and regenerate the snapshot.    |
+| `dev-kit catalog verify`                   | Verify the committed snapshot without advancing refs. |
 
-The Oxlint preset vendors and enables every rule from
-[dmmulroy/anti-slop](https://github.com/dmmulroy/anti-slop) at upstream commit
-`9b80d9a5c317d3af94d88a577bdbde4d9a45f7be`. These opinionated rules reject
-low-evidence patterns such as broad `unknown` contracts, runtime `typeof`
-narrowing, module mocking, chained assertions, and assertions without a
-nearby `SAFETY:` justification. The package also exports the plugin from
-`@danieljvdm/dev-kit/oxlint-plugin-anti-slop`. Its vendored MIT license is
-retained beside the source.
-
-The TypeScript files under `src/oxlint-plugin-anti-slop/` are canonical. After
-updating them, run `vp run anti-slop:bundle` to regenerate the package-loadable
-JavaScript entry point without cleaning canonical source.
-
-The preset also enables `stylistic/padding-line-between-statements`: adjacent
-variable declarations remain grouped, while the next logical statement and
-all `return` statements require a separating blank line. The rule is fixable,
-so `vp lint --fix` repairs missing spacing automatically. With the matching
-Oxlint 1.78 peer installed, Vite+ 0.2.6 executes the preset's JavaScript-plugin
-rules through the normal `vp lint` command.
-
-The preset also registers the shared `effect` JavaScript plugin. Effect
-projects opt into its rules in path-specific overrides, for example
-`effect/no-effect-run`, `effect/no-unsafe-promise`, and
-`effect/no-untyped-throw`. The package exports the plugin directly from
-`@danieljvdm/dev-kit/oxlint-plugin-effect` for configurations that do not
-extend the recommended preset. Strict workflow, Atom, and boundary rules remain
-consumer-scoped because application and host boundaries differ by repository.
+Resolved external content is cached machine-wide by immutable commit. Project
+skill copies remain independent of that cache.
 
 ## Development
 
+This repository uses Vite+ as its command authority:
+
 ```bash
 vp install
 vp run check
 ```
+
+The package's own `prepare` script explicitly syncs its Effect source checkout,
+patches Effect TypeScript-Go, and configures Vite+ Git hooks. Those are local
+development operations for Dev Kit itself, not a consumer management model.
+
+The v1 decoder exists only behind `eject`. Repository-setup behavior belongs in
+`skills/dev-kit` as concise agent instructions and progressively disclosed
+references. Deterministic CLI code is reserved for catalog, provenance,
+migration, validation, and other mechanics where a free-form agent edit would
+be unsafe.