@techierathore/techieflow 1.0.1 → 1.0.3

package/docs/TechieFlow-Installation.md

@@ -17,7 +17,7 @@ You need four things on the machine.
 |---|---|---|
 | Node.js 20 or newer | Runs the installer. Nothing is added to your project. | `node --version` |
 | bash | The framework's guard hooks and helper scripts run under bash. macOS and Linux have it. On Windows, work inside WSL or Git Bash. | `bash --version` |
-| Python 3.10 or newer | Powers the HTML renderer, the telemetry writer and the guard hooks. An older Python 3 works but skips the Codex files. | `python3 --version` |
+| Python 3 | Powers the HTML renderer, the telemetry writer and the guard hooks. | `python3 --version` |
 | Claude Code or OpenCode | The harness that runs the agents. Either one. Both work from the same install. | `claude --version` or `opencode --version` |
 
 For a .NET project you also need the .NET SDK. Run `dotnet --version` to check.
@@ -30,6 +30,8 @@ You do not need rsync, git on the command line, or a clone of this repository.
 
 The installer copies the framework into hidden folders inside your project. It never adds the framework as a dependency of your application. After it runs there is no `node_modules`, no `package.json` and no lock file that was not there before.
 
+The npm package itself holds the framework folders, this document and a `scripts/` folder with the installer's own three files. Nothing from `scripts/` is ever copied into your project, so it cannot clash with a `scripts/` folder of your own. Claude Code and OpenCode never read the package. They read the copies the installer places in your project, listed below.
+
 | Path | What it is | On update |
 |---|---|---|
 | `.tfcore/` | The framework: personas, tasks, templates, hooks, helper scripts. | Refreshed. Two files inside are yours and are kept: `core-config.yaml` and `routing.yaml`. |
@@ -40,8 +42,6 @@ The installer copies the framework into hidden folders inside your project. It n
 | `.opencode/opencode.jsonc` | The framework's OpenCode configuration. OpenCode reads the personas and tasks straight from `.tfcore/` through it. | Refreshed. |
 | `.opencode/command/generate-html.md` | The short `/generate-html` command for OpenCode. | Added on update only. |
 | `opencode.jsonc` | The root OpenCode configuration, for your own additions. | Refreshed only when it holds nothing of yours, with the old file kept as `opencode.jsonc.bak`. |
-| `.codex/` and `.agents/skills/` | The Codex adapter, generated from the same personas and tasks. | Refreshed. `config.toml` is yours and is kept. |
-| `WORKFLOW.html` | The human workflow guide. Open it in a browser. | Refreshed. |
 | `.tf-scaffold-note.txt` | A note with your next command. Delete it when read. | Left alone. |
 | `docs/metrics/` | Five empty telemetry files and a README. This is your project's history: commit it. | Left alone. |
 | `.gitignore` | Lines that keep the copies above out of your commits. Appended, never rewritten. | Appended. |
@@ -240,7 +240,6 @@ The installer and the updater never write to:
 - `.tfcore/core-config.yaml` and `.tfcore/routing.yaml` after the first install
 - `.claude/settings.local.json`
 - `.claude/commands/trblazeui.md`, `.claude/commands/techierag.md` and the same names under `.opencode/command/`. These come from the NuGet packages.
-- `.codex/config.toml` after the first install
 - `opencode.jsonc` at the root when it holds a key of your own
 
 Existing lines in `.gitignore` and `.gitattributes` are never rewritten. The managed lines are appended once and recognised on every later run.
@@ -282,17 +281,38 @@ git clone https://github.com/techierathore/TechieFlow.git
 
 The installer and the scripts produce the same files. A test in the repository, `scripts/test-install.mjs`, runs both on the same folders and fails on any difference. Choose the route you like. The package route needs no clone and always gives you the released version. The clone route gives you whatever is on the branch you checked out.
 
-Do not run `npm install @techierathore/techieflow`. That would add the package to your application. Use `npx`, which runs the installer once and keeps nothing.
+---
+
+## 9. If you ran `npm install` instead of `npx`
+
+The documented command is `npx ... install`. It downloads the package to npm's cache, runs the installer once, and leaves nothing behind.
+
+`npm install @techierathore/techieflow` is the wrong command for a framework. It treats the package as a dependency of your application: it puts the whole package under `node_modules/@techierathore/techieflow/`, and writes it into `package.json` and `package-lock.json`. Claude Code and OpenCode do not look there.
+
+What happens next depends on your npm version. Check with `npm --version`.
+
+| npm version | What happens |
+|---|---|
+| 10 or 11 | The package's install hook runs the installer for you, then removes the package from `node_modules/`, `package.json` and `package-lock.json`. If npm created those files only for this install, they are removed too. A JavaScript project keeps its own `package.json`, lock file and `node_modules/`, minus the framework entry. The end result is the same as the `npx` command. npm hides the installer's output, so read `.tf-scaffold-note.txt` for the next step. |
+| 12 or newer | npm no longer runs install hooks unless the project allows them. Nothing is installed. The package just sits under `node_modules/`. |
+
+Either way, the fix is the same. Run the real command in the project folder:
+
+```bash
+npx @techierathore/techieflow@latest install
+```
+
+It installs the framework if it is not there yet, then removes the leftover package from `node_modules/`, `package.json` and `package-lock.json`. `update` does the same tidy-up.
 
 ---
 
-## 9. If something goes wrong
+## 10. If something goes wrong
 
 | What you see | What to do |
 |---|---|
+| The framework is under `node_modules/@techierathore/techieflow/` and nowhere else | You ran `npm install`. See section 9. Run `npx @techierathore/techieflow@latest install`. |
 | `bash was not found` | On Windows, run the command inside WSL or Git Bash. |
 | `python3 was not found` | Install Python 3 and run the command again. On macOS: `brew install python3`. On Ubuntu or WSL: `sudo apt-get install -y python3`. |
-| `Codex bindings could not be generated` | Your Python is older than 3.10. Everything except the Codex files is installed. Upgrade Python and run `update` to add them. |
 | `Refusing to install into the framework itself` | You ran the command inside a clone of this repository. Pass `--target=<your project>`. |
 | `does not look installed` on update | The folder has no `.tfcore/`. Run `install` first. |
 | Claude Code does not show the `/TechieFlow:agents:analyst` command | Restart Claude Code in the project folder. Check that `.claude/commands/TechieFlow/agents/analyst.md` exists. |

package/opencode.jsonc

@@ -253,7 +253,7 @@
           "sudo *": "ask"
         }
       },
-      "description": "Madhav — the single super-agent. Orchestrates the full pipeline (*run-workflow, *phase) with parallel subagents, runs the unified build (*build-phase — calls /trblazeui + /techierag as sub-agents), fixes bugs from screenshots (*fix-issues), analyzes + logs human-found bugs without fixing (*triage-issues), records a single missed requirement in seconds (*log-miss), reports development telemetry (*metrics), and handles doc/status utilities (*render-workflow-docs, *generate-html, *handoff-phase, *refresh-status, *devguide) plus any one-off task."
+      "description": "Madhav — the TechieFlow master: build (*build-phase), fix (*fix-issues), triage (*triage-issues), log a miss (*log-miss), amend documents (*amend-docs), DevGuide and ProductGuide, handoff, refresh-status, metrics, HTML rendering, YOLO. The analyst owns day-1; the verifier owns *verify.",
     },
     "flow-architect": {
       "prompt": "{file:./.tfcore/agents/architect.md}",
@@ -839,19 +839,23 @@
     },
     "techieflow:tasks:fix-issues": {
       "template": "{file:./.tfcore/tasks/fix-issues.md}",
-      "description": "Bug-fix front door: given a folder of screenshots (+ optional description), reproduce with Playwright, triage (layout/data/logic/RAG), fan fixes to the right builder, re-smoke (data+visual) + re-verify, update docs. Driven by /flow-master."
+      "description": "Fixes the bugs in a folder of screenshots: triages and logs them, builds the fix through the builders in FIX mode, smokes, re-verifies the touched rows, closes the misses with the fix cost (tf-fix-close.sh). Driven by /flow-master."
     },
     "techieflow:tasks:log-miss": {
       "template": "{file:./.tfcore/tasks/log-miss.md}",
-      "description": "The 20-second front door for 'you missed this': turns one sentence about something an agent got wrong into a misses.jsonl record (what was missed, which phase/agent/model let it through, who found it) plus the checklist line — demotion with a dated miss Remark, or a new Planned row when nothing owns it. Never boots the app, never reproduces, never edits code. Driven by /flow-master."
+      "description": "The twenty-second record: one sentence from the owner becomes one miss record and one checklist line through tf-log-miss.sh. Never boots, never fixes. Driven by /flow-master."
     },
     "techieflow:tasks:triage-issues": {
       "template": "{file:./.tfcore/tasks/triage-issues.md}",
-      "description": "ANALYZE-ONLY bug front door for human-found (UAT/production) bugs: reproduce with Playwright, triage to the owning REQ, log in the checklist (demote to Needs re-verify / new Planned rows), optional scoped regression re-verify, update PROJECT-STATUS with the *fix-issues pointer. NEVER edits code. Driven by /flow-master."
+      "description": "Analyse-only front door for bugs a person found: reproduces each on its screen, logs it in the checklist and the telemetry through tf-triage.sh (demote, new, note, close), never edits code. Driven by /flow-master."
+    },
+    "techieflow:tasks:triage-and-fix": {
+      "template": "{file:./.tfcore/tasks/triage-and-fix.md}",
+      "description": "The owner's whole bug sequence in YOLO: compare every screen to its mockup, triage the reported bugs, log every root cause with its cost, fix, log every fix with its cost, refresh the metrics, one summary per step. Driven by /flow-master."
     },
     "techieflow:tasks:verify-phase": {
       "template": "{file:./.tfcore/tasks/verify-phase.md}",
-      "description": "Autonomous verification of a scope (ui | functional | all | REQ list | legacy phase-N) — filters the one Checklist by REQ prefix; applies the data-render + visual-truth gates; verdicts land in the Checklist Requirements Status table."
+      "description": "Verifies every checklist row in a scope (ui | functional | all | REQ list) against the running app: boots it, runs the seven checks in order through the tf-verify-* scripts, writes the verdicts into the checklist and the telemetry. YOLO by default. Driven by /verifier."
     },
     "techieflow:tasks:handoff-phase": {
       "template": "{file:./.tfcore/tasks/handoff-phase.md}",
@@ -873,14 +877,14 @@
       "template": "{file:./.tfcore/tasks/generate-html.md}",
       "description": "Render any markdown file(s) or a non-recursive directory to self-contained HTML using the shared shell."
     },
-    "techieflow:tasks:author-brd": {
-      "template": "{file:./.tfcore/tasks/author-brd.md}",
-      "description": "Interactively extend docs/{AppName}-BRD.md with confirmed BRD-N requirements (per-item elicitation)."
-    },
     "techieflow:tasks:amend-docs": {
       "template": "{file:./.tfcore/tasks/amend-docs.md}",
       "description": "Fold an evolving concept / changed requirements into the EXISTING day-1 docs IN PLACE: surgically amends BRD + Architecture (append-only IDs), ripples to PROJECT-STATUS / BRD §4 / checklists, re-renders HTML. Incremental alternative to re-running day1-*."
     },
+    "techieflow:tasks:deploy-checklist": {
+      "template": "{file:./.tfcore/tasks/deploy-checklist.md}",
+      "description": "Deployment Checklist: the steps to put the application on its host, one document per hosting target, written after UAT from the owner's pipeline guidance document and the Stack answers Q9 and Q10 (docs/TechieFlow-Document-Schemas.md §3.10). Never deploys. Driven by /flow-master."
+    },
     "techieflow:tasks:productguide": {
       "template": "{file:./.tfcore/tasks/productguide.md}",
       "description": "End-user Product Guide: screenshot-illustrated, task-oriented how-to manual for external users (what each screen is for + how to do things) — the user-facing sibling of the DevGuide, reusing its captured screenshots. Always MD + HTML. On-demand. Driven by /flow-master."
@@ -889,10 +893,6 @@
       "template": "{file:./.tfcore/tasks/devguide.md}",
       "description": "Generate/refresh the screen-by-screen Developer Guide: traces every screen/control from Razor page → service → data-access → stored proc/query, per user role, documenting the code AS BUILT. Single doc for small apps, split per role for large ones; --update refreshes only changed screens."
     },
-    "techieflow:tasks:document-project": {
-      "template": "{file:./.tfcore/tasks/document-project.md}",
-      "description": "Generate comprehensive documentation for existing projects optimized for AI development agents."
-    },
     "techieflow:tasks:create-doc": {
       "template": "{file:./.tfcore/tasks/create-doc.md}",
       "description": "Create a document from a YAML-driven TechieFlow template (interactive, section by section)."
@@ -904,26 +904,6 @@
     "techieflow:tasks:facilitate-brainstorming-session": {
       "template": "{file:./.tfcore/tasks/facilitate-brainstorming-session.md}",
       "description": "Run a structured brainstorming session; results land in docs/brainstorming-session-results.md."
-    },
-    "techieflow:tasks:advanced-elicitation": {
-      "template": "{file:./.tfcore/tasks/advanced-elicitation.md}",
-      "description": "Reflective/brainstorming actions for deeper exploration and iterative refinement of drafted content."
-    },
-    "techieflow:tasks:execute-checklist": {
-      "template": "{file:./.tfcore/tasks/execute-checklist.md}",
-      "description": "Validate a document or work product against one of the TechieFlow checklists."
-    },
-    "techieflow:tasks:index-docs": {
-      "template": "{file:./.tfcore/tasks/index-docs.md}",
-      "description": "Maintain docs/index.md by scanning all documentation files and indexing them with descriptions."
-    },
-    "techieflow:tasks:kb-mode-interaction": {
-      "template": "{file:./.tfcore/tasks/kb-mode-interaction.md}",
-      "description": "User-friendly interface to the TechieFlow knowledge base."
-    },
-    "techieflow:tasks:shard-doc": {
-      "template": "{file:./.tfcore/tasks/shard-doc.md}",
-      "description": "Split a large document into smaller documents by level-2 sections, preserving content integrity."
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techierathore/techieflow",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "TechieFlow: a spec-driven development framework for AI coding agents, for Claude Code and OpenCode. One command installs it into any project.",
   "license": "Apache-2.0",
   "repository": {
@@ -33,19 +33,16 @@
     ".opencode/command",
     "!.opencode/command/trblazeui.md",
     "!.opencode/command/techierag.md",
-    ".codex/config.toml",
-    ".codex/hooks.json",
-    ".codex/rules",
     "opencode.jsonc",
-    "WORKFLOW.html",
     "scripts/install.mjs",
-    "scripts/test-install.mjs",
-    "scripts/validate.mjs",
+    "scripts/npm-postinstall.mjs",
+    "scripts/npm-cleanup.mjs",
     "docs/TechieFlow-Installation.md",
     "LICENSE",
     "README.md"
   ],
   "scripts": {
+    "postinstall": "node scripts/npm-postinstall.mjs",
     "validate": "node scripts/validate.mjs",
     "test:install": "node scripts/test-install.mjs",
     "pack:check": "npm pack --dry-run",

package/scripts/install.mjs

@@ -20,7 +20,7 @@
 // scripts/test-install.mjs proves that by running both routes and comparing the results.
 //
 // Needs: node, bash and python3. The framework's own helper scripts (telemetry setup,
-// build-output ignore audit, Codex bindings) are run exactly as the shell scripts run them.
+// build-output ignore audit) are run exactly as the shell scripts run them.
 
 import { spawnSync } from "node:child_process";
 import {
@@ -31,6 +31,7 @@ import { homedir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
+import { hasDependencyFootprint, removeDependencyFootprint } from "./npm-cleanup.mjs";
 
 // ---------------------------------------------------------------- arguments
 
@@ -200,7 +201,7 @@ function checkTools() {
   }
   pythonCommand = findPython();
   if (!pythonCommand) {
-    throw new Error("python3 was not found. It powers the HTML renderer, the telemetry writer, the Codex bindings and every guard hook.\n"
+    throw new Error("python3 was not found. It powers the HTML renderer, the telemetry writer and every guard hook.\n"
       + "  Install it and run this command again:\n"
       + "    macOS:          brew install python3\n"
       + "    Ubuntu / WSL:   sudo apt-get install -y python3\n"
@@ -209,6 +210,22 @@ function checkTools() {
   }
 }
 
+// Someone ran `npm install @techierathore/techieflow` instead of the npx command. On npm 10
+// and 11 the package's install hook deploys the framework and removes its own npm files.
+// npm 12 and newer skip install hooks, so the package just sits under node_modules/ and in
+// package.json. Whichever way it happened, once the framework is in place those npm files
+// have no purpose: remove them. Skipped while the install hook itself is running (the
+// package folder is still in use by npm then; the hook's own cleanup handles that case).
+function tidyDependencyInstall() {
+  const packageDir = join(target, "node_modules", "@techierathore", "techieflow");
+  if (sourceRoot === packageDir || sourceRoot.startsWith(`${packageDir}${sep}`)) return;
+  if (!hasDependencyFootprint(target)) return;
+  say("");
+  say("  The package was found under node_modules/ (someone ran `npm install` on it). The framework is not an application dependency.");
+  if (dryRun) { say("  WOULD remove it from node_modules/, package.json and package-lock.json."); return; }
+  for (const item of removeDependencyFootprint(target)) say(`  removed ${item}`);
+}
+
 function ensureSafeTarget() {
   if (target === sourceRoot || target.startsWith(`${sourceRoot}${sep}`)) throw new Error("Refusing to install into the framework itself. Pass --target=<your project folder>.");
   if (target === resolve("/") || target === resolve(homedir())) throw new Error("Refusing to install into the filesystem root or your home folder.");
@@ -220,8 +237,8 @@ function ensureSafeTarget() {
 // Same lines, same patterns and same header text as the shell scripts. Append-only: an
 // entry already present in any anchored or slash variant is respected, nothing is rewritten.
 const frameworkIgnore = {
-  lines: [".tfcore/", ".claude/", ".opencode/", ".codex/", ".agents/skills/", "/CLAUDE.md", "/WORKFLOW.html", "/opencode.jsonc", "/.tf-scaffold-note.txt"],
-  patterns: [/^\/?\.tfcore\/?$/, /^\/?\.claude\/?$/, /^\/?\.opencode\/?$/, /^\/?\.codex\/?$/, /^\/?\.agents\/skills\/?$/, /^\/?CLAUDE\.md$/, /^\/?WORKFLOW\.html$/, /^\/?opencode\.jsonc$/, /^\/?\.tf-scaffold-note\.txt$/],
+  lines: [".tfcore/", ".claude/", ".opencode/", "/CLAUDE.md", "/opencode.jsonc", "/.tf-scaffold-note.txt"],
+  patterns: [/^\/?\.tfcore\/?$/, /^\/?\.claude\/?$/, /^\/?\.opencode\/?$/, /^\/?CLAUDE\.md$/, /^\/?opencode\.jsonc$/, /^\/?\.tf-scaffold-note\.txt$/],
   header: ["# TechieFlow framework — deployed copies, never commit (managed by scaffold/update-framework.sh)"],
   label: "framework entries",
 };
@@ -336,6 +353,22 @@ const canonicalSettings = String.raw`{
           {
             "type": "command",
             "command": "bash \"$CLAUDE_PROJECT_DIR/.tfcore/hooks/guard-artifacts.sh\""
+          },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.tfcore/hooks/guard-status.sh\""
+          },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.tfcore/hooks/guard-metrics.sh\""
+          },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.tfcore/hooks/guard-db.sh\""
+          },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.tfcore/hooks/guard-build.sh\""
           }
         ]
       },
@@ -346,6 +379,10 @@ const canonicalSettings = String.raw`{
             "type": "command",
             "command": "bash \"$CLAUDE_PROJECT_DIR/.tfcore/hooks/guard-status.sh\""
           },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.tfcore/hooks/guard-metrics.sh\""
+          },
           {
             "type": "command",
             "command": "bash \"$CLAUDE_PROJECT_DIR/.tfcore/hooks/guard-verify.sh\""
@@ -409,7 +446,6 @@ Added (only missing files filled — re-runs are safe):
   .tfcore/                  ← TechieFlow v4 customized (agents, tasks, templates)
   .claude/commands/            ← Claude Code slash commands (TechieFlow agents)
   .claude/settings.json        ← yolo-except-git-writes permissions
-  WORKFLOW.html                ← the human workflow guide (open in a browser; §17 = macOS / Windows / Linux)
   opencode.jsonc               ← OpenCode config (loads agents/tasks from .tfcore/ via {file:...} refs)
   .gitignore                   ← framework entries appended (deployed copies stay uncommitted)
 
@@ -451,7 +487,6 @@ Folders/files created (only missing files filled — re-runs are safe):
   .tfcore/                  ← TechieFlow v4 customized (agents, tasks, templates)
   .claude/commands/            ← Claude Code slash commands (TechieFlow agents)
   .claude/settings.json        ← yolo-except-git-writes permissions
-  WORKFLOW.html                ← the human workflow guide (open in a browser; §17 = macOS / Windows / Linux)
   opencode.jsonc               ← OpenCode config (loads agents/tasks from .tfcore/ via {file:...} refs)
   .gitignore                   ← framework entries appended (deployed copies stay uncommitted)
   tests/playwright/  tests/unit/  src/
@@ -498,15 +533,20 @@ function deployOpenCodeBridge() {
   writeText(join(target, ".opencode", "opencode.jsonc"), openCodeConfigCopy());
 }
 
-function deployCodexAdapter() {
-  say("  .codex/ + .agents/skills/ — Codex adapter");
-  if (dryRun) { say("  WOULD preserve/create .codex/config.toml; refresh hooks/rules; regenerate agents/skills"); return; }
-  for (const folder of [".codex/agents", ".codex/rules", ".agents/skills"]) mkdirSync(join(target, folder), { recursive: true });
-  copyFile(join(sourceRoot, ".codex", "config.toml"), join(target, ".codex", "config.toml"), { onlyIfMissing: true });
-  copyFile(join(sourceRoot, ".codex", "hooks.json"), join(target, ".codex", "hooks.json"));
-  copyFile(join(sourceRoot, ".codex", "rules", "techieflow.rules"), join(target, ".codex", "rules", "techieflow.rules"));
-  const result = runPython([join(target, ".tfcore", "utils", "tf-codex-bind.py"), target]);
-  if (result.status !== 0) say("  ⚠ Codex bindings could not be generated (python3 required)");
+// The Codex adapter was removed on 2026-09-07 (D-14, FR-42) and WORKFLOW.html was dropped the
+// same day: it was a second full description of the process, last revised before the reset, and
+// it still taught commands that no longer exist. Both are taken out of a project that has them.
+// Nothing here is project content: .codex/ held a config file plus generated bindings,
+// .agents/skills/ was generated in full from .tfcore/tasks/, and WORKFLOW.html was a copy.
+function removeRetiredFiles() {
+  for (const path of [".codex", ".agents/skills", "WORKFLOW.html"]) {
+    const full = join(target, path);
+    if (!existsSync(full)) continue;
+    if (dryRun) { say(`  ${would}remove ${path} — no longer part of the framework`); continue; }
+    rmSync(full, { recursive: true, force: true });
+    say(`  removed ${path} — no longer part of the framework`);
+  }
+  if (!dryRun) { try { rmdirSync(join(target, ".agents")); say("  removed the emptied .agents/"); } catch {} }
 }
 
 function deployHousekeeping() {
@@ -602,13 +642,11 @@ async function install() {
   say("  syncing agent files from .tfcore/agents/ → .claude/commands/TechieFlow/agents/");
   copyTree(dryRun ? join(sourceRoot, ".tfcore", "agents") : join(target, ".tfcore", "agents"), join(target, ".claude", "commands", "TechieFlow", "agents"));
   // 4. reference files at the root, only if missing
-  copyFile(join(sourceRoot, "WORKFLOW.html"), join(target, "WORKFLOW.html"), { onlyIfMissing: true });
   copyFile(join(sourceRoot, "opencode.jsonc"), join(target, "opencode.jsonc"), { onlyIfMissing: true });
   // 4b. OpenCode bridge, always refreshed
   deployOpenCodeBridge();
-  // 4c. Codex adapter
-  deployCodexAdapter();
-  if (!dryRun) say("  Codex adapter installed — trust this repository and review /hooks before relying on guards");
+  // 4c. files earlier versions deployed and the framework no longer ships
+  removeRetiredFiles();
   // 5. Claude Code permissions, only if missing
   if (writeText(join(target, ".claude", "settings.json"), `${canonicalSettings}\n`, { onlyIfMissing: true })) { if (!dryRun) say("  created .claude/settings.json"); }
   else say("  .claude/settings.json already exists — preserved");
@@ -624,6 +662,8 @@ async function install() {
   shimLegacyPersonas({ gapOnly: false });
   // 9. .gitignore, build-output audit, telemetry, .gitattributes
   deployHousekeeping();
+  // 10. leftovers of a plain `npm install` of this package, if any
+  tidyDependencyInstall();
 
   say("");
   if (dryRun) { say("✔ Dry run complete — no files changed."); return; }
@@ -631,13 +671,15 @@ async function install() {
   say("");
   say(`Next: cd "${target}"`);
   if (greenfield) say("      dotnet new sln + blazor + add TrBlazeUI/TechieRag NuGets + dotnet build");
-  say("      open WORKFLOW.html in a browser");
   say(`      start Claude Code or OpenCode and run the ${greenfield ? "greenfield" : "brownfield"} day-1 command from .tf-scaffold-note.txt`);
 }
 
 // ---------------------------------------------------------------- update (update-framework.sh)
 
-const frameworkSubdirs = ["agents", "tasks", "telemetry", "templates", "checklists", "data", "utils", "hooks", "workflows", "agent-teams"];
+// Keep this in step with FRAMEWORK_SUBDIRS in update-framework.sh. `standards` arrived with the
+// document schemas and was missing here, so a project migrated from the old layout came out
+// without its coding standards (found by scripts/test-install.mjs, 2026-09-07).
+const frameworkSubdirs = ["agents", "tasks", "telemetry", "templates", "checklists", "data", "utils", "hooks", "standards", "workflows", "agent-teams"];
 const frameworkTopFiles = ["enhanced-ide-development-workflow.md", "user-guide.md", "working-in-the-brownfield.md", "install-manifest.yaml", "TOKEN-GUIDE.md"];
 const legacyConfigPattern = /\.bmad-core|bmad-(master|orchestrator|analyst|architect|verifier)|BMad:/;
 
@@ -847,22 +889,18 @@ function update() {
   deployOpenCodeBridge();
   refreshRootOpenCodeConfig();
 
-  // 4b. Codex adapter
-  deployCodexAdapter();
-  if (!dryRun) say("  Codex hooks changed or installed — trust this repository and review /hooks");
+  // 4b. files earlier versions deployed and the framework no longer ships
+  removeRetiredFiles();
   for (const file of libraryPersonas) if (existsSync(join(target, ".opencode", "command", file))) say(`  .opencode/command/${file} — preserved (NuGet-deployed)`);
 
-  // 4. WORKFLOW.html, always refreshed
-  if (existsSync(join(sourceRoot, "WORKFLOW.html"))) {
-    copyFile(join(sourceRoot, "WORKFLOW.html"), join(target, "WORKFLOW.html"));
-    say("  WORKFLOW.html");
-  }
   // 5. NuGet persona shims: gap-fill only, never an overwrite
   shimLegacyPersonas({ gapOnly: true });
   // 6, 7. messages about stale references in files the owner owns
   reportStaleReferences();
   // 8. .gitignore, build-output audit, telemetry, .gitattributes
   deployHousekeeping();
+  // 9. leftovers of a plain `npm install` of this package, if any
+  tidyDependencyInstall();
 
   say("");
   if (dryRun) {
@@ -903,29 +941,18 @@ function uninstall() {
   plan(".opencode/opencode.jsonc");
   plan(".opencode/opencode.json", "(generated by routing)");
   for (const file of shippedFiles(".opencode/command", ".md")) if (!libraryPersonas.has(file)) plan(`.opencode/command/${file}`);
-  plan(".codex/hooks.json");
-  plan(".codex/rules/techieflow.rules");
-  if (existsSync(join(target, ".codex", "config.toml"))) {
-    if (sameAsShipped(".codex/config.toml", ".codex/config.toml")) plan(".codex/config.toml");
-    else keep(".codex/config.toml", "you changed it");
-  }
-  const codexAgents = join(target, ".codex", "agents");
-  if (existsSync(codexAgents)) for (const f of readdirSync(codexAgents)) {
-    if (f.endsWith(".toml") && /description = "TechieFlow [a-z-]+ (specialist|role)\."/.test(read(join(codexAgents, f)))) plan(`.codex/agents/${f}`);
-    else keep(`.codex/agents/${f}`, "not written by the framework");
-  }
-  const skills = join(target, ".agents", "skills");
-  if (existsSync(skills)) for (const f of readdirSync(skills)) if (f.startsWith("techieflow-")) plan(`.agents/skills/${f}`);
+  // Retired on 2026-09-07 but still present in a project set up by an older version.
+  for (const path of [".codex", ".agents/skills"]) if (existsSync(join(target, path))) plan(path, "(retired Codex adapter)");
   for (const lib of [".trblazeui", ".techierag"]) {
     if (!existsSync(join(target, lib))) continue;
     const rest = readdirSync(join(target, lib)).filter((f) => f !== ".codex-agent-package-owned" && f !== ".gitignore");
     plan(`${lib}/.codex-agent-package-owned`);
     if (rest.length === 0) plan(`${lib}/.gitignore`);
   }
-  for (const [path, shipped] of [["WORKFLOW.html", "WORKFLOW.html"], ["opencode.jsonc", "opencode.jsonc"]]) {
-    if (!existsSync(join(target, path))) continue;
-    if (sameAsShipped(path, shipped)) plan(path);
-    else keep(path, "you changed it");
+  if (existsSync(join(target, "WORKFLOW.html"))) plan("WORKFLOW.html", "(retired human workflow guide)");
+  if (existsSync(join(target, "opencode.jsonc"))) {
+    if (sameAsShipped("opencode.jsonc", "opencode.jsonc")) plan("opencode.jsonc");
+    else keep("opencode.jsonc", "you changed it");
   }
   plan(".tf-scaffold-note.txt");
   const hook = join(target, ".git", "hooks", "pre-commit");

package/scripts/npm-cleanup.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// scripts/npm-cleanup.mjs — removes the package's own footprint after a plain `npm install`.
+//
+// The framework is not an application dependency. `npm install @techierathore/techieflow`
+// still puts the package under node_modules/ and writes it into package.json and
+// package-lock.json. Once the framework files are in place, this removes that footprint:
+//
+//   node_modules/@techierathore/techieflow   the package folder
+//   node_modules/@techierathore              when nothing else is in it
+//   node_modules/.bin/techieflow*            the command shims
+//   the package's entry in package.json, package-lock.json and node_modules/.package-lock.json
+//
+// If npm created package.json, package-lock.json or node_modules only for this install
+// (an empty folder, or a .NET project), they are removed as well. A project's own
+// package.json, lock file and node_modules are kept, minus the entry for this package.
+//
+// Used two ways:
+//   - by npm-postinstall.mjs, detached, after the install hook has deployed the framework.
+//     npm writes package.json, package-lock.json and node_modules/.package-lock.json AFTER
+//     the hook has run, so the detached process waits for that last write before it starts.
+//   - by install.mjs, straight away, when the package is found under node_modules/ of the
+//     project it just installed into. That happens when the owner ran `npm install` on an
+//     npm that skips install hooks (npm 12 and newer) and then ran the real command.
+
+import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+export const packageName = "@techierathore/techieflow";
+const dependencyKeys = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
+const lockKey = `node_modules/${packageName}`;
+
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; }
+}
+
+const writeJson = (path, value) => writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+
+// True for a package.json that npm created for this install alone: nothing in it except
+// empty dependency tables once this package's entry is gone.
+function isEmptyManifest(manifest) {
+  return Object.entries(manifest).every(([key, value]) =>
+    dependencyKeys.includes(key) && value && typeof value === "object" && Object.keys(value).length === 0);
+}
+
+// Drops this package from a package.json object. Returns true when something was removed.
+function dropFromManifest(manifest) {
+  let changed = false;
+  for (const key of dependencyKeys) {
+    if (manifest?.[key] && packageName in manifest[key]) { delete manifest[key][packageName]; changed = true; }
+  }
+  return changed;
+}
+
+// Drops this package from a package-lock.json object (root file or the hidden one in node_modules).
+function dropFromLock(lock) {
+  let changed = false;
+  if (lock?.packages) {
+    if (lockKey in lock.packages) { delete lock.packages[lockKey]; changed = true; }
+    if (lock.packages[""] && dropFromManifest(lock.packages[""])) changed = true;
+  }
+  if (lock?.dependencies && packageName in lock.dependencies) { delete lock.dependencies[packageName]; changed = true; }
+  return changed;
+}
+
+// Does this project folder hold the package as an npm dependency artifact?
+export function hasDependencyFootprint(target) {
+  const manifest = readJson(join(target, "package.json"));
+  return existsSync(join(target, "node_modules", "@techierathore", "techieflow"))
+    || dependencyKeys.some((key) => manifest?.[key] && packageName in manifest[key]);
+}
+
+// Removes the footprint. Returns the list of things removed, in plain words, for the caller to print.
+export function removeDependencyFootprint(target) {
+  const removed = [];
+  const nm = join(target, "node_modules");
+  const scopeDir = join(nm, "@techierathore");
+  const packageDir = join(scopeDir, "techieflow");
+  const bin = join(nm, ".bin");
+
+  if (existsSync(packageDir)) { rmSync(packageDir, { recursive: true, force: true }); removed.push("node_modules/@techierathore/techieflow/"); }
+  if (existsSync(scopeDir) && readdirSync(scopeDir).every((e) => e === ".DS_Store")) rmSync(scopeDir, { recursive: true, force: true });
+  if (existsSync(bin)) {
+    for (const shim of readdirSync(bin)) {
+      if (shim === "techieflow" || shim.startsWith("techieflow.")) { rmSync(join(bin, shim), { force: true }); removed.push(`node_modules/.bin/${shim}`); }
+    }
+  }
+
+  const manifestPath = join(target, "package.json");
+  const manifest = readJson(manifestPath);
+  let manifestRemoved = false;
+  if (manifest && dropFromManifest(manifest)) {
+    if (isEmptyManifest(manifest)) { rmSync(manifestPath, { force: true }); manifestRemoved = true; removed.push("package.json (npm created it for this install)"); }
+    else { writeJson(manifestPath, manifest); removed.push(`the ${packageName} entry in package.json`); }
+  }
+
+  const lockPath = join(target, "package-lock.json");
+  if (manifestRemoved) {
+    if (existsSync(lockPath)) { rmSync(lockPath, { force: true }); removed.push("package-lock.json (npm created it for this install)"); }
+  } else {
+    const lock = readJson(lockPath);
+    if (lock && dropFromLock(lock)) { writeJson(lockPath, lock); removed.push(`the ${packageName} entry in package-lock.json`); }
+  }
+
+  if (existsSync(nm)) {
+    const bookkeeping = (entry) => entry === ".package-lock.json" || entry === ".DS_Store"
+      || (entry === ".bin" && readdirSync(bin).every((e) => e === ".DS_Store"));
+    if (readdirSync(nm).every(bookkeeping)) { rmSync(nm, { recursive: true, force: true }); removed.push("node_modules/ (npm created it for this install)"); }
+    else {
+      const hiddenPath = join(nm, ".package-lock.json");
+      const hidden = readJson(hiddenPath);
+      if (hidden && dropFromLock(hidden)) writeJson(hiddenPath, hidden);
+    }
+  }
+  return removed;
+}
+
+// ---- standalone use: node npm-cleanup.mjs <project folder>, started detached by the install hook.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const target = process.argv[2];
+  if (!target || !existsSync(target)) process.exit(0);
+  const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+  const hiddenLock = join(target, "node_modules", ".package-lock.json");
+  // npm's last write is node_modules/.package-lock.json. Wait for it to name this package,
+  // then a moment longer for npm to close it. Give up waiting after 60 seconds (for example
+  // when npm was told not to write a lock file) and clean up anyway.
+  for (let waited = 0; waited < 60_000; waited += 200) {
+    const hidden = readJson(hiddenLock);
+    if (hidden?.packages && lockKey in hidden.packages) break;
+    await sleep(200);
+  }
+  await sleep(500);
+  // On Windows npm may still hold a handle for a moment; retry briefly.
+  for (let attempt = 0; attempt < 50; attempt++) {
+    try { removeDependencyFootprint(target); break; } catch { await sleep(200); }
+  }
+}