@deftai/directive-content 0.55.0

package/.agents/skills/deft/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: deft
+description: Apply deft framework standards for AI-assisted development. Use when starting projects, writing code, running tests, making commits, or when the user references deft, project standards, or coding guidelines.
+---
+
+Read and follow: SKILL.md

package/.agents/skills/deft-directive-article-review/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: deft-directive-article-review
+description: >-
+  Evaluate an article, paper, or post for lessons that could improve directive.
+  Analyzes two axes: how concepts improve directive's own implementation, and
+  how they improve the projects directive creates. Produces filtered
+  suggestions, iterates with the user, and optionally creates GitHub issues on
+  the directive repo.
+---
+
+Read and follow: skills/deft-directive-article-review/SKILL.md

package/.agents/skills/deft-directive-build/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: deft-directive-build
+description: >-
+  Build a project from scope vBRIEFs following Deft Directive framework standards.
+  Use after deft-directive-setup has generated the project definition, or when the
+  user has story vBRIEFs in vbrief/active/ ready to implement. Handles scaffolding,
+  implementation, testing, and quality checks phase by phase.
+---
+
+Read and follow: skills/deft-directive-build/SKILL.md

package/.agents/skills/deft-directive-cost/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: deft-directive-cost
+description: >-
+  Pre-build cost & budget transparency phase. Use after the project
+  SPECIFICATION is approved and before the build skill kicks off, to
+  produce a plain-English COST-ESTIMATE.md the user can read, react to,
+  and explicitly accept, rescope, no-build, or skip with a recorded
+  reason. Audience is non-technical users; voice is dollars and
+  whole-number bands, not spreadsheets.
+---
+
+Read and follow: skills/deft-directive-cost/SKILL.md

package/.agents/skills/deft-directive-debug/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: deft-directive-debug
+description: >-
+  Systematic, evidence-based root-cause investigation. Use when the user asks
+  "why did X break / slow down / regress?", wants to debug a failure, run a
+  forensic investigation, or find the root cause of a bug -- to enter a
+  sustained investigation MODE with a claim ledger, mandatory falsification
+  before any conclusion, a chat answer-embargo until evidence closes, and a
+  deterministic validator gate. Triggers: "debug", "root cause", "investigate",
+  "why did X break", "why is X slow", "systematic debugging", "forensic".
+---
+
+Read and follow: skills/deft-directive-debug/SKILL.md

package/.agents/skills/deft-directive-gh-arch/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: deft-directive-gh-arch
+description: >-
+  Explore a codebase for architectural improvement opportunities -- deepen
+  shallow modules, generate competing interface designs in parallel via
+  sub-agents, and file a refactor RFC as a GitHub Issue. Use when improving
+  architecture, finding refactoring opportunities, or making a codebase more
+  testable and AI-navigable. Requires the GitHub CLI (gh).
+---
+
+Read and follow: skills/deft-directive-gh-arch/SKILL.md

package/.agents/skills/deft-directive-gh-slice/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: deft-directive-gh-slice
+description: >-
+  Break a SPECIFICATION.md, PRD, or plan into independently-grabbable GitHub
+  Issues using tracer-bullet vertical slices. Use after spec generation, when
+  the user wants to create implementation tickets, or when breaking work into
+  parallel-assignable issues. Requires the GitHub CLI (gh).
+---
+
+Read and follow: skills/deft-directive-gh-slice/SKILL.md

package/.agents/skills/deft-directive-glossary/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: deft-directive-glossary
+description: >-
+  Extract a DDD-style ubiquitous language glossary from the current
+  conversation, flagging ambiguities and proposing canonical terms. Saves
+  to UBIQUITOUS_LANGUAGE.md. Use when defining domain terms, building a
+  glossary, hardening terminology, or when "domain model" or "DDD" is mentioned.
+---
+
+Read and follow: skills/deft-directive-glossary/SKILL.md

package/.agents/skills/deft-directive-interview/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: deft-directive-interview
+description: >-
+  Deterministic structured Q&A interview loop. Use when any skill needs
+  structured user input through focused questions with defaults and
+  confirmation gate. Interview output targets vBRIEF narratives.
+---
+
+Read and follow: skills/deft-directive-interview/SKILL.md

package/.agents/skills/deft-directive-pre-pr/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: deft-directive-pre-pr
+description: >-
+  Iterative pre-PR quality improvement loop. Use before pushing a branch
+  for PR creation -- after completing implementation but before task check.
+  Cycles through Read-Write-Lint-Diff until a full pass produces zero changes.
+---
+
+Read and follow: skills/deft-directive-pre-pr/SKILL.md

package/.agents/skills/deft-directive-refinement/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: deft-directive-refinement
+description: >-
+  Conversational refinement session. Ingests external work items into
+  vBRIEF proposed/ scope, deduplicates via origin references, evaluates
+  proposals with the user, reconciles stale origins, and promotes/demotes
+  scopes through the lifecycle using deterministic task commands.
+---
+
+Read and follow: skills/deft-directive-refinement/SKILL.md

package/.agents/skills/deft-directive-release/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: deft-directive-release
+description: >-
+  Cut a v0.X.Y release of the deft framework safely. Use when the user
+  says "release", "cut release", "v0.X.Y", or "publish release" -- to
+  walk an 8-phase workflow that pre-flights, runs an end-to-end
+  rehearsal against a temp repo, lands a draft on the real repo, gates
+  on user review, then publishes or rolls back. Re-uses the
+  deft-directive-swarm Phase 6 Step 5 Slack announcement template.
+---
+
+Read and follow: skills/deft-directive-release/SKILL.md

package/.agents/skills/deft-directive-review-cycle/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: deft-directive-review-cycle
+description: >-
+  Greptile bot reviewer response workflow. Use when running a review cycle
+  on a PR -- to audit process prerequisites, fetch bot findings, fix all
+  issues in a single batch commit, and exit cleanly when no P0 or P1 issues
+  remain. Enables cloud agents to run autonomous PR review cycles.
+---
+
+Read and follow: skills/deft-directive-review-cycle/SKILL.md

package/.agents/skills/deft-directive-setup/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: deft-directive-setup
+description: >-
+  Set up a new project with Deft Directive framework standards. Use when the
+  user wants to bootstrap user preferences, configure a project, or generate a
+  project specification. Walks through setup conversationally — no separate CLI
+  needed.
+---
+
+Read and follow: skills/deft-directive-setup/SKILL.md

package/.agents/skills/deft-directive-swarm/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: deft-directive-swarm
+description: >-
+  Parallel local agent orchestration. Use when running multiple agents
+  on vBRIEF stories simultaneously — to scan active/ for allocatable work,
+  set up isolated worktrees, launch agents with proven prompts, monitor
+  progress, handle stalled review cycles, and close out PRs cleanly.
+---
+
+Read and follow: skills/deft-directive-swarm/SKILL.md

package/.agents/skills/deft-directive-sync/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: deft-directive-sync
+description: >-
+  Session-start framework sync skill. Pulls latest deft submodule,
+  validates vBRIEF lifecycle structure, checks folder/status consistency,
+  detects stale origins (RFC D12), and summarizes changes.
+---
+
+Read and follow: skills/deft-directive-sync/SKILL.md

package/.agents/skills/deft-directive-triage/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: deft-directive-triage
+description: >-
+  Triage-cache hygiene and "what's next?" queue selection -- the agent-facing
+  playbook for syncing the triage cache, classifying candidates, presenting a
+  ranked queue, walking per-item decisions, and auditing the session.
+---
+
+Read and follow: skills/deft-directive-triage/SKILL.md

package/.agents/skills/deft-directive-write-skill/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: deft-directive-write-skill
+description: >-
+  Create new deft skills with proper structure, RFC2119 notation, triggers,
+  and progressive disclosure. Use when user wants to create, write, or build
+  a new deft skill.
+---
+
+Read and follow: skills/deft-directive-write-skill/SKILL.md

package/LICENSE.md

@@ -0,0 +1,22 @@
+# MIT License
+
+Copyright (c) 2025-2026 Jonathan "visionik" Taylor
+https://deft.md
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/QUICK-START.md

@@ -0,0 +1,167 @@
+# QUICK-START
+
+You are reading this because a user told you to, or because a stale `AGENTS.md` (or a `skills/deft-*/SKILL.md` redirect stub) sent you here. Follow these steps exactly, in order.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+## Installing Deft from GitHub (fetch-and-run one-liner)
+
+! If Deft is **not yet installed** and you were told to "download and install Deft from GitHub into this directory," do NOT build from a source checkout and do NOT guess a path. Run the canonical per-platform fetch-and-run one-liner below. Each downloads the correct release binary from `https://github.com/deftai/directive/releases/latest/download/<asset>`, makes it executable, then runs it headless against the current directory (`--yes --repo-root . --json`).
+
+**macOS (Intel + Apple Silicon):**
+
+```bash
+curl -fsSL -o /tmp/deft-install https://github.com/deftai/directive/releases/latest/download/install-macos-universal && chmod +x /tmp/deft-install && /tmp/deft-install --yes --repo-root . --json
+```
+
+**Linux** (amd64; use `install-linux-arm64` on Raspberry Pi / ARM):
+
+```bash
+curl -fsSL -o /tmp/deft-install https://github.com/deftai/directive/releases/latest/download/install-linux-amd64 && chmod +x /tmp/deft-install && /tmp/deft-install --yes --repo-root . --json
+```
+
+**Windows** (PowerShell; use `install-windows-arm64.exe` on Surface / Copilot+ PCs):
+
+```powershell
+Invoke-WebRequest -Uri https://github.com/deftai/directive/releases/latest/download/install-windows-amd64.exe -OutFile $env:TEMP\deft-install.exe; & $env:TEMP\deft-install.exe --yes --repo-root . --json
+```
+
+⊗ Do NOT `go build` from a source checkout or a developer-specific path (e.g. a hardcoded `/Users/<name>/...` clone) — the canonical fetch path above never assumes a local clone. Once the installer finishes, continue with Step 1 below.
+
+## Step 1 — Who are you?
+
+Ask the user: **"Are you (1) using deft in your project, or (2) working on deft itself?"**
+
+- If **(2)**: Tell the user: "Read `./AGENTS.md` in this directory instead — it has contributor instructions." **Stop here.**
+- If **(1)**: Continue to Step 2.
+
+## Step 2 — Detect project state
+
+Before touching `../AGENTS.md`, inspect the user's project root to decide whether this is a fresh install, a re-run, a stale-AGENTS.md upgrade, or a pre-cutover project that needs migration.
+
+Run these deterministic checks, in order:
+
+### 2a. Does `../AGENTS.md` exist?
+
+- **No:** treat as fresh install — jump to Case F ("No AGENTS.md") in Step 3.
+- **Yes:** continue to 2b.
+
+### 2b. Does `../AGENTS.md`'s managed section match the current template? Do referenced paths resolve?
+
+Three checks here, in this order. The first match wins; later checks only run when earlier checks pass.
+
+1. **Template-content byte comparison (Case G gate).** Locate the managed section in `../AGENTS.md` (the block bounded by the `<!-- deft:managed-section v2 -->` and `<!-- /deft:managed-section -->` markers). Compare those bytes against the current `./templates/agents-entry.md` rendered managed-section output.
+   - ! If the managed section is **byte-different** from the current template render (or the markers are absent in `../AGENTS.md`), treat as **stale content** -- jump to Case G ("Stale AGENTS.md") in Step 3. Case G is the right remediation for byte-different staleness because the refresh actually rewrites the content.
+2. **Install-path resolution (Case K gate -- #1046 PR-A).** When the managed section IS byte-current, parse the section for its install-path declaration (`Full guidelines: <root>/main.md`, e.g. `.deft/core/main.md` for the canonical install layout or `deft/main.md` for the legacy install layout). Verify that `../<root>/main.md` exists on disk.
+   - ! If the managed section is **byte-identical** to the current template render BUT the declared install path does NOT resolve, jump to **Case K ("Install location mismatch")** in Step 3. Refreshing the managed section is a documented no-op when the content already matches -- Case K is a different failure class than Case G and demands a different remediation (#1046 finding #2).
+3. **Legacy skill-path resolution (v0.19 AGENTS.md backstop).** Parse `../AGENTS.md` for any token matching `deft/skills/<name>/SKILL.md` (the legacy v0.19 path shape) and verify the file exists under `./skills/<name>/SKILL.md` (relative to this QUICK-START.md).
+   - ! If any referenced path does not exist on disk, treat `../AGENTS.md` as **stale** -- jump to Case G in Step 3.
+   - ! If the referenced path exists but its first 200 characters contain `<!-- deft:deprecated-skill-redirect -->`, also treat as stale. These stubs exist to keep v0.19 `AGENTS.md` files working until QUICK-START can refresh them. (The 200-character window matches the same budget used in 2c and is guaranteed to cover the sentinel position in every stub this repo ships -- see `tests/content/test_deprecated_skill_redirects.py::test_stub_has_sentinel`.)
+   - If all referenced paths exist and none are redirect stubs, continue to 2c.
+
+Priority ordering: Case G (byte-different content) always wins over Case K (install-path mismatch) because the refresh path is the higher-priority remediation -- when the template content has moved on, the refresh closes BOTH the content drift and any incidental install-path mismatch that the new content might re-introduce. Case K only fires when the content is byte-current AND the path is unresolved -- the exact "refresh would be a no-op" failure class issue #1046 documents.
+
+**Big-jump joint check (Case G+H gate).** Before acting on ANY Case G routing above (a byte-different managed section, or an unresolved / redirect-stub legacy skill path), first ALSO evaluate the 2c pre-cutover check below against `../`. ! If 2c ALSO holds (real pre-v0.20 `SPECIFICATION.md` / `PROJECT.md` present), the project is in the **joint big-jump state** where both the AGENTS.md refresh (Case G) and the pre-cutover migration (Case H) are due — jump to **Case G+H** (combined single-session remediation) in Step 3 instead of Case G. The combined path runs the refresh and the migration in one session and emits a single restart, avoiding the wasted Case G → restart → Case H round-trip. If 2c does not hold, route to Case G as usual.
+
+### 2c. Are there pre-v0.20 artifacts at the user's project root?
+
+Check both of these files at `../` (the user's project root), using the same
+rule implemented by `scripts/_precutover.py`:
+
+- `../SPECIFICATION.md` — exists and is neither a deprecation redirect nor a current generated spec export. A current generated spec export contains `<!-- Purpose: rendered specification -->` and `<!-- Source of truth: vbrief/specification.vbrief.json -->`, and `../vbrief/specification.vbrief.json` plus all five lifecycle folders exist.
+- `../PROJECT.md` — exists and is not a deprecation redirect (`<!-- deft:deprecated-redirect -->` or `<!-- Purpose: deprecation redirect -->`).
+
+- If **either** holds (real pre-v0.20 content present), treat as **pre-cutover** — jump to Case H ("Pre-cutover migration") in Step 3.
+- If both contain the sentinel (or neither exists), continue to 2d.
+
+### 2d. Partial migration?
+
+Check whether `../vbrief/` exists. If it does, inspect for the 5 lifecycle subfolders (`proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`). If `vbrief/` exists but any lifecycle subfolder is missing, treat as **partial migration** — jump to Case I ("Partial migration repair") in Step 3.
+
+### 2e. Everything clean
+
+If none of 2a–2d triggered, `../AGENTS.md` is current and the project is on v0.20+. Jump to Case J ("Everything clean") in Step 3.
+
+## Step 3 — Act on detected state
+
+Pick exactly one case from Step 2 and follow its instructions. Do not mix cases.
+
+### Case F — No AGENTS.md (fresh install)
+
+1. Read `./templates/agents-entry.md` (this directory).
+2. Write that content to `../AGENTS.md`.
+3. Tell the user: "✓ Created AGENTS.md at your project root."
+4. Continue to Step 4.
+
+### Case G — Stale AGENTS.md (v0.19 → v0.20 upgrade)
+
+1. Read `../AGENTS.md` and identify the **Deft-managed section** — bounded by the `deft/main.md` sentinel marker.
+2. If the `deft/main.md` sentinel is **absent**, treat the entire existing file as user-authored and do NOT rewrite it. Instead, read `./templates/agents-entry.md` and **append** its content to `../AGENTS.md` with two blank lines between the existing content and the appended block. This matches the idempotent append behavior documented in `setup.go::WriteAgentsMD` for brownfield projects with a pre-existing AGENTS.md.
+3. If the `deft/main.md` sentinel is **present**, replace only the sentinel-bounded section with the current content of `./templates/agents-entry.md`. Preserve everything outside that region verbatim.
+4. Tell the user: "✓ Refreshed Deft-managed section of AGENTS.md. Your existing additions outside that region were preserved."
+5. ! Instruct the user: **"Framework updated. Start a new agent session to pick up the changes. The current session has stale context."** Do not continue past this instruction in the current session.
+
+### Case H — Pre-cutover migration (SPECIFICATION.md / PROJECT.md without sentinel)
+
+1. Tell the user: "Your project uses the pre-v0.20 document model. I can run `task migrate:vbrief` to upgrade, which replaces SPECIFICATION.md and PROJECT.md with deprecation redirect stubs and creates the `vbrief/` lifecycle folders. First I'll run an environment preflight."
+2. ! Execute the environment preflight from `./skills/deft-directive-setup/SKILL.md` "Pre-Cutover Detection Guard" § Environment Preflight: check (a) `task migrate:vbrief` resolvability, (b) `uv` on PATH, (c) `deft/scripts/migrate_vbrief.py` present. Report each result to the user BEFORE asking for approval. If any check fails, surface the specific fix pointer and stop — do not prompt for approval until preflight passes.
+3. ! If `task migrate:vbrief` is not resolvable from the project root (the consumer `Taskfile.yml` does not yet include `deft/Taskfile.yml`), tell the user the fallback invocation `task -t ./deft/Taskfile.yml migrate:vbrief` will be used instead. See [./main.md](../main.md#publishing-deft-tasks-in-your-project-root) for the recommended include pattern that makes the primary command work from the project root.
+4. ! Only after preflight results have been reported, ask the user: "Preflight passed. Shall I run `task migrate:vbrief` (or the fallback invocation) now?" Wait for explicit user approval (`yes`, `approve`, `confirmed`). ⊗ Run migration on a broad "proceed" or "go ahead".
+5. On approval: run the resolved command (primary `task migrate:vbrief` or the fallback `task -t ./deft/Taskfile.yml migrate:vbrief`) from the project root. For preview (`--dry-run`), dirty-tree bypass (`--force`), and undo (`--rollback`) see the [Migration safety flags](./skills/deft-directive-setup/SKILL.md#migration-safety-flags) subsection.
+6. See [./main.md](../main.md#migrating-from-pre-v020) for the full migration reference (what pre-cutover looks like, what the migrator produces, safety flags) and [docs/BROWNFIELD.md](./docs/BROWNFIELD.md) for the brownfield adoption guide.
+7. After migration completes, re-run Step 2 of this QUICK-START — the project state has changed. Most likely you land in Case G (AGENTS.md still references old paths) or Case J.
+8. When AGENTS.md is refreshed, ! instruct the user: **"Framework updated. Start a new agent session to pick up the changes. The current session has stale context."**
+
+### Case G+H — Combined stale AGENTS.md + pre-cutover migration (big-jump, one session)
+
+Reached only via the **Big-jump joint check** in 2b: the managed section in `../AGENTS.md` is stale (Case G) AND pre-v0.20 artifacts are present at `../` (Case H). This is the typical shape of a multi-version "big jump" that crossed both the AGENTS.md managed-section refresh and the pre-v0.20 document-model cutover. Running Case G and Case H as two separate sessions wastes an agent-session round-trip, because `task migrate:vbrief` re-reads filesystem state directly and does NOT depend on the refreshed `AGENTS.md` being in the current agent's context. Both remediations therefore complete safely in **one session**.
+
+! Run the two remediations in this exact order — **AGENTS.md refresh first, migration second** — then emit a **single** restart instruction at the very end:
+
+1. **Refresh AGENTS.md first (Case G work).** Perform Case G steps 1-4 verbatim: identify the managed section, append when the sentinel is absent or byte-replace it when present, and preserve everything outside the managed region. ⊗ Do NOT emit the Case G step-5 restart instruction here — the combined path defers the single restart to step 3.
+2. **Run migration second (Case H work).** Perform Case H steps 1-6 verbatim: run the environment preflight, report each result, ask for explicit approval, and on approval run `task migrate:vbrief` (or the `task -t ./deft/Taskfile.yml migrate:vbrief` fallback) from the project root. ⊗ Do NOT perform Case H step 7 (re-run Step 2) or step 8 (restart): the AGENTS.md refresh is already done in step 1, and the single restart is emitted in step 3. The migration reads filesystem state directly, so refreshing AGENTS.md first does not change its inputs — the ordering is safe.
+3. **Single restart, exactly once.** Only after BOTH the refresh and the migration have completed, ! instruct the user EXACTLY ONCE: **"Framework updated and project migrated. Start a new agent session to pick up the changes. The current session has stale context."** ⊗ Do NOT emit a second restart instruction — the deferred Case G restart and the Case H restart collapse into this one.
+
+The end state is byte-identical to running Case G and Case H separately: the same managed-section refresh against `./templates/agents-entry.md` and the same `task migrate:vbrief` output (deprecation-redirect stubs plus the five `vbrief/` lifecycle folders). The only thing removed is the wasted intermediate session restart. For the version-by-version context of a big jump, see the [big-jump triage entry point](./UPGRADING.md#big-jump-triage--multi-version-upgrades-start-here) in UPGRADING.md.
+
+### Case I — Partial migration repair
+
+1. Tell the user: "Your project has a partial vBRIEF layout. Missing lifecycle folders: <list the absent ones>. Shall I complete the migration by running `task migrate:vbrief`? It is idempotent and safe to re-run."
+2. On approval, run `task migrate:vbrief` (or fall back to `task -t ./deft/Taskfile.yml migrate:vbrief` if the task is not resolvable from the project root — see [./main.md](../main.md#publishing-deft-tasks-in-your-project-root)). Re-run Step 2 afterwards.
+3. If the user declines, point them at [docs/BROWNFIELD.md](./docs/BROWNFIELD.md) §Troubleshooting and stop.
+
+### Case J — Everything clean
+
+1. Tell the user: "✓ Deft is already configured and current in your AGENTS.md."
+2. Continue to Step 4.
+
+### Case K — Install location mismatch (#1046 PR-A)
+
+The managed section in `../AGENTS.md` is byte-identical to the current `./templates/agents-entry.md` render, BUT the install path the managed section declares (e.g. `.deft/core/main.md`) does NOT resolve on disk. This is the failure class issue #1046 finding #2 documents: Case G's "refresh the managed section" prescription is a byte-for-byte no-op against the current template, so re-running just re-detects the same staleness next session.
+
+1. Tell the user (verbatim phrasing, naming the unresolved path): "AGENTS.md's managed section is byte-identical to the current template, but the install path it declares (`<declared-path>`) does NOT exist on disk. Refreshing the managed section would be a no-op -- Case G's remediation does not fix install-location mismatches."
+2. ! Direct the user to run `task framework:doctor` (forthcoming in PR-B of the #1046 cohort -- the diagnostic + remediation surface that owns Case K's fix path) OR to manually verify that the install path AGENTS.md claims actually exists on disk. Until PR-B merges, the manual check is the operator's only path: confirm the framework is deposited at the path AGENTS.md declares, OR re-run the installer / relocator to deposit at that path, OR hand-edit AGENTS.md to point at the path where the framework actually lives.
+3. ⊗ Run a Case G refresh -- it is a documented no-op for Case K. The managed section already byte-matches the current template; refreshing the bytes back to the same bytes does not change which install path is declared.
+4. ! Instruct the user: **"Stop here. Do not continue to Step 4 until the install-path mismatch is resolved -- subsequent sessions will re-enter Case K until then."**
+
+## Step 4 — Continue setup
+
+Read and follow `../AGENTS.md`. This starts the normal first-session flow (user preferences, project definition, specification). If you reached Case G or completed Case H/I and rewrote AGENTS.md, you have already told the user to start a new session — do not keep going yourself.
+
+**Brownfield pointer:** For users retrofitting Deft onto an existing project (existing code, existing docs, or pre-v0.20 Deft layout), the authoritative adoption guide is [docs/BROWNFIELD.md](./docs/BROWNFIELD.md). It covers install options, migration, post-migration checks, and troubleshooting in more depth than the Case H flow above.
+
+**Upgrade pointer:** Users moving between framework versions should also read [UPGRADING.md](./UPGRADING.md) in the repo root for the version-by-version guide. For a multi-version "big jump", start at its [big-jump triage entry point](./UPGRADING.md#big-jump-triage--multi-version-upgrades-start-here), which names which version buckets apply and in what order. An agent on a big jump that hits both a stale AGENTS.md and pre-cutover artifacts should follow [Case G+H](#case-gh--combined-stale-agentsmd--pre-cutover-migration-big-jump-one-session) above to complete both in one session.
+
+## Update notifications
+
+After a Deft project is set up, the CLI runs a periodic, read-only remote-version probe (issue #801) so you find out when the upstream framework ships a new release. The probe shells out to `git ls-remote --tags --refs <upstream>` against the deft submodule's `origin` remote at most once every 24 hours, parses the highest semver tag, and -- if your local checkout is behind -- prints a single informational warn line below the existing recorded-vs-current message:
+
+```
+⚠ Upstream directive v0.24.0 is available (you are on v0.23.0). Run `task framework:check-updates` for details; follow `skills/deft-directive-sync/SKILL.md` Phase 2 to update.
+```
+
+The banner is informational only: it never blocks CI, never prompts in non-interactive sessions, and never triggers a second `Continue anyway?` prompt on top of the existing #410 marker-drift gate. Re-notification cadence is per-tag -- once you dismiss `v0.24.0` the banner stays silent for 24 hours, but a fresh `v0.24.1` re-notifies immediately. State is persisted to `vbrief/.deft-remote-probe.json`; per-`run`-invocation dedup prevents the same banner from stacking when chained commands (e.g. `cmd_install -> cmd_project -> cmd_spec`) all hit the gate.
+
+For a synchronous interactive probe -- handy when you want to verify your update path before pushing -- run `task framework:check-updates`. Pass `-- --force` to bypass the 24-hour throttle and `-- --json` to get a machine-parseable payload (useful in CI dashboards). Exit code is `1` only when the probe positively reports BEHIND; every other status (`OK` / `NO-UPSTREAM` / `NO-TAGS` / `ERROR` / `SKIPPED`) returns `0`.
+
+Air-gapped or strict-egress environments can opt out of the probe entirely by setting `DEFT_NO_NETWORK=1` in the calling shell -- the probe short-circuits before any subprocess call, the gate emits no banner, and no `framework:remote-drift` event is recorded. The subprocess timeout (default 5 seconds) is overridable via `DEFT_REMOTE_PROBE_TIMEOUT` for slow upstream remotes.