@deftai/directive-content 0.68.0 → 0.69.0

package/SKILL.md

@@ -1,7 +1,7 @@
 <!-- DEFT-PREAMBLE-V1 -->
 <!--
 ! Cold-start check: deft runs from the npm-installed engine (`npm i -g @deftai/directive`). If neither `deft` nor `directive` will run on this machine, do not proceed with the instructions below -- recover first (#1933 Option 1, deprecate-by-disuse).
-! To recover: read `.deft/core/UPGRADING.md`, find the section whose "Applies when" clause matches your symptom, and follow that section verbatim before any other instruction in this file or in the consumer AGENTS.md.
+! To recover: read the **Cold-start bootstrap** block at the top of the project's `README.md` and follow the global-first npm ladder there before any other instruction in this file or in the consumer AGENTS.md. `README.md` is always committed (never gitignored) and does not depend on the `.deft/core/` payload, so the recovery ladder is reachable on a fresh clone even when the vendored payload is absent (#2273).
 ! Respect any "Restart required" directive -- if present, stop and tell the user to start a fresh session after cleanup commands complete. Otherwise continue.
 -->
 ---

package/UPGRADING.md

@@ -12,6 +12,18 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
 ---
 
+## Which command do I run? (three-command model)
+
+Directive is driven by three commands, and upgrading is one of them. Route by situation to exactly one:
+
+- **Ordinary upgrade of an existing Directive project** → `directive update` (after `npm i -g @deftai/directive@latest`). This is the one command most upgrades need; the [Canonical upgrade — npm](#canonical-upgrade--npm-v0551) section below is the full walkthrough.
+- **Not sure what state you are in, or something looks broken** → `directive doctor`. It is read-only and prints exactly one recommended next step (including "run `directive update`" when the deposit is stale).
+- **First-time adoption, or a legacy / pre-v0.20 layout** → `directive init`. It classifies the directory and either scaffolds Directive or routes you to the specific migration path.
+
+Everything below preserves the **advanced and big-jump** detail — multi-version jumps, the frozen pre-v0.20 bridge, legacy Go-installer migration, and the per-version transitions. Ordinary upgraders only need `directive update`; reach into the detailed sections when `directive doctor` or the [big-jump triage](#big-jump-triage--multi-version-upgrades-start-here) points you there.
+
+---
+
 ## Canonical upgrade — npm (v0.55.1+)
 
 From v0.55.1 onwards `@deftai/directive` is published on npm. The canonical consumer upgrade path is:
@@ -22,6 +34,14 @@ From v0.55.1 onwards `@deftai/directive` is published on npm. The canonical cons
    npm i -g @deftai/directive@latest
    ```
 
+   **Using pnpm?** pnpm installs the same package from the same npm registry — no extra registry or config:
+
+   ```bash
+   pnpm add -g @deftai/directive@latest
+   ```
+
+   Ensure pnpm's global bin directory is on your `PATH` (`pnpm setup` configures `PNPM_HOME`). A project-local `pnpm add -D @deftai/directive@latest` (run via `pnpm exec directive …`) is equivalent for pnpm-managed repos that avoid global installs. `deft update` / `deft migrate` / `deft doctor` all work identically regardless of which package manager installed the engine.
+
 2. **Refresh the project deposit** from your project root:
 
    ```bash

package/docs/BROWNFIELD.md

@@ -12,9 +12,28 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
 ## 1. Install Deft in Your Project
 
-You have three ways to add the `deft/` framework to an existing project. Pick the one that fits your workflow:
+### Start here: `directive init`
 
-### Option A: Git submodule (recommended)
+For a project that already has code, the canonical adoption path is the **same universal entrypoint** greenfield users run — `directive init`:
+
+```bash
+npm i -g @deftai/directive     # Node >= 20
+cd your-existing-project
+directive init                 # detects app code, installs Directive beside it
+directive doctor               # confirms the install + prints your one next step
+```
+
+**pnpm-managed project?** Swap the first line for `pnpm add -g @deftai/directive` (same package, same npm registry — no extra registry needed) and make sure `PNPM_HOME` is on your `PATH` (`pnpm setup`). Everything after installs and runs identically.
+
+`directive init` classifies the directory you run it in. Because it finds existing app code (or a git repo) but no Directive deposit, it takes the **brownfield-install** path: it installs Directive support *beside* your source without disturbing it, scaffolds the `xbrief/` layout, and points you toward brownfield spec extraction. It never overwrites your files, and it ignores only Directive's local-only artifacts (`.deft/core/`, `.deft/.cli/`, `.deft/ritual-state.json`, and the `.deft-cache/` cache) while leaving your committed `package.json` pin tracked in git. If the directory turns out to hold a legacy / pre-v0.20 layout, init routes you to the specific migration path (§2) instead of scaffolding over it — and `directive doctor` is the read-only probe that tells you exactly what to run next if anything looks off.
+
+An already-initialized Directive project does not need `init` at all — run `directive update` to refresh it.
+
+### Legacy install paths (submodule / installer / clone)
+
+Before the npm-first channel, Deft was added to an existing project with one of the options below. They remain available for **offline / air-gapped** deposits or for migrating an old on-disk layout, but `directive init` above is the canonical path for new adopters — reach for these only when npm is not an option:
+
+### Option A: Git submodule (legacy)
 
 ```bash
 git submodule add https://github.com/deftai/directive.git deft

package/main.md

@@ -1,6 +1,6 @@
 <!-- DEFT-PREAMBLE-V1 -->
 ! Cold-start check: deft runs from the npm-installed engine (`npm i -g @deftai/directive`). If neither `deft` nor `directive` will run on this machine, do not proceed with the instructions below -- recover first (#1933 Option 1, deprecate-by-disuse).
-! To recover: read `.deft/core/UPGRADING.md`, find the section whose "Applies when" clause matches your symptom, and follow that section verbatim before any other instruction in this file or in the consumer AGENTS.md.
+! To recover: read the **Cold-start bootstrap** block at the top of the project's `README.md` and follow the global-first npm ladder there before any other instruction in this file or in the consumer AGENTS.md. `README.md` is always committed (never gitignored) and does not depend on the `.deft/core/` payload, so the recovery ladder is reachable on a fresh clone even when the vendored payload is absent (#2273).
 ! Respect any "Restart required" directive -- if present, stop and tell the user to start a fresh session after cleanup commands complete. Otherwise continue.
 
 # Warp AI Guidelines

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "Shippable Directive framework content in the consumer .deft/core/ layout (C1 flatten), plus the engine surfaces (.githooks/, Taskfile.yml, tasks/) the deposit wires. Python-free per #2022 Phase 3. Refs #11, #1669, #1967.",
   "type": "module",
   "files": [

package/templates/agents-entry.md

@@ -5,6 +5,14 @@ Deft is installed in .deft/core/. Full guidelines: .deft/core/main.md
 
 ! If any .deft/core/.agents/skills/ path referenced in this file cannot be read (missing file, stale path from a previous framework version, or a deprecation redirect stub), read .deft/core/QUICK-START.md instead and follow it. QUICK-START refreshes this section idempotently for the current framework version.
 
+## Cold-start bootstrap (#2273)
+
+! If `deft` / `directive` will not run on this machine, recover BEFORE following any instruction below. Directive runs from an npm-installed engine; the recovery ladder is payload-independent and always lives in the **Cold-start bootstrap** block at the top of the project's committed `README.md` (never gitignored, present on a fresh clone even when `.deft/core/` is absent). Read it there and follow the global-first ladder.
+
+! Global-first ladder (prose; no committed shell shim — you are the interpreter). Work top-down; stop at the first rung that yields a working `directive`, keyed off the `package.json` pin: (1) try `directive doctor`; (2) else if `.deft/.cli/<platform>` holds an intact engine at/above the pin, use it; (3) else `npm i -g @deftai/directive` (Node ≥ 20); (4) else, when the global npm prefix is not writable (sandbox), `npm install --prefix .deft/.cli/<platform> @deftai/directive@<pinned>`; (5) else install from a staged tarball / vendored payload.
+
+⊗ Point cold-start recovery at a path inside `.deft/core/` — that is the exact payload absent when recovery is needed. The reachable-on-a-fresh-clone recovery surface is `README.md`, never the vendored payload.
+
 ## Pre-Cutover Check (run before First Session / Returning Sessions)
 
 ! Before the First Session / Returning Sessions checks below, detect whether this project pre-dates the v0.20 xBRIEF-centric model. If it does, migration MUST happen before any Phase 1, Phase 2, or Returning-Sessions routing fires.
@@ -194,5 +202,5 @@ Directive product commands use the `/deft:directive:*` namespace (#418 / #1670).
 
 **CLI compatibility:**
 
-The legacy Python `.deft/core/run` CLI is deprecated and is no longer a load-bearing operator path (#1933 Option 1, deprecate-by-disuse). Use the agent-driven setup skill for first-time setup and project/spec generation; if `deft` or `directive` will not run, read `.deft/core/UPGRADING.md`.
+The legacy Python `.deft/core/run` CLI is deprecated and is no longer a load-bearing operator path (#1933 Option 1, deprecate-by-disuse). Use the agent-driven setup skill for first-time setup and project/spec generation; if `deft` or `directive` will not run, follow the payload-independent recovery ladder in the `## Cold-start bootstrap (#2273)` section above (top of the project's `README.md`), not a path inside `.deft/core/`.
 <!-- /deft:managed-section -->