devlyn-cli 4.3.25 → 4.3.27

package/README.md

@@ -29,13 +29,13 @@ npx devlyn-cli
 
 That's it. The installer asks:
 
-1. **What** — `AGENTS.md — Codex · omp · Pi · Grok` (checked) and `CLAUDE.md — Claude Code` (checked when this project already has a devlyn Claude install). Space toggles, Enter confirms.
+1. **What** — `Codex · omp · Pi · Grok` (checked) and `Claude Code` (checked when this project already has a devlyn Claude install). Space toggles, Enter confirms.
 2. **Where** — `This project` (default) or `Global — every project on this machine`.
-3. **Optional skills & packs** — none checked; see [Optional Add-ons](#optional-add-ons) below. MCP servers are offered only with CLAUDE.md.
+3. **Optional skills & packs** — none checked; see [Optional Add-ons](#optional-add-ons) below. MCP servers are offered only with Claude Code.
 
-In a project, AGENTS.md readers load the skills from `.agents/skills/`; Claude Code loads only `.claude/skills/` and reads AGENTS.md when the project has no CLAUDE.md; a CLAUDE.md the installer creates imports an existing AGENTS.md (`@AGENTS.md`). Global installs skills only: `~/.agents/skills/` (omp, Pi, Grok) and `~/.codex/skills/` (Codex), plus `~/.claude/skills/` for Claude Code. Every target gets the `devlyn-ideate` skill and the `devlyn-engines` utility. In Codex / omp / Pi, invoke them as skills (`$devlyn-ideate`); in Claude Code and Grok they're slash commands (`/devlyn-ideate`). Rerunning refreshes skills and the managed instruction block while preserving project rules outside it. See [Migration from earlier versions](#migration-from-earlier-versions) for legacy migration and merge recovery.
+In a project, Codex, omp, Pi and Grok load the skills from `.agents/skills/`; Claude Code loads only `.claude/skills/`. The installer never writes `CLAUDE.md` or `AGENTS.md`: those files stay yours. Global installs skills only: `~/.agents/skills/` (omp, Pi, Grok) and `~/.codex/skills/` (Codex), plus `~/.claude/skills/` for Claude Code. Every target gets the `devlyn-ideate` skill and the `devlyn-engines` utility. In Codex / omp / Pi, invoke them as skills (`$devlyn-ideate`); in Claude Code and Grok they're slash commands (`/devlyn-ideate`). Rerunning refreshes skills. See [Migration from earlier versions](#migration-from-earlier-versions) for projects that carry an earlier copy of the principles.
 
-Without prompts, `npx devlyn-cli -y` installs AGENTS.md + `.agents/skills/` plus every target this project already has; add `--claude` for Claude Code. With `--global` it installs for every project on this machine, plus `~/.claude/skills/` with `--claude` or when it already has a devlyn install. The installer leaves Git to you: it prints no commit guidance after a project install or update. When Git ignores some, but not all, files of an installed skill folder, it prints one line with their count and an example ignore rule.
+Without prompts, `npx devlyn-cli -y` installs `.agents/skills/` plus every target this project already has; add `--claude` for Claude Code. With `--global` it installs for every project on this machine, plus `~/.claude/skills/` with `--claude` or when it already has a devlyn install. The installer leaves Git to you: it prints no commit guidance after a project install or update. When Git ignores some, but not all, files of an installed skill folder, it prints one line with their count and an example ignore rule.
 
 `npx devlyn-cli update` — Update every devlyn install already here (this project and your global skill folders) to this version; installs nothing new.
 
@@ -43,13 +43,17 @@ Without prompts, `npx devlyn-cli -y` installs AGENTS.md + `.agents/skills/` plus
 
 ## How It Works — Principles and Loops
 
-The managed `CLAUDE.md` / `AGENTS.md` block carries the North Star, seven principles (no workaround, no overengineering, no guesswork, worldclass, best practice, optimized, production ready) and three discipline rules, plus short pointers to the skills. Agents do the work directly under it; for work that splits into tasks, ideate designs a loop and drains it:
+The Devlyn defaults carry the North Star, seven principles (no workaround, no overengineering, no guesswork, worldclass, best practice, optimized, production ready) and three discipline rules, plus short pointers to the skills. Each session gets them from the release, through the Devlyn app or `devlyn run`, so projects hold no copy and a new release reaches every project at once. A clone without either gets no Devlyn defaults. Agents do the work directly under them; for work that splits into tasks, ideate designs a loop and drains it:
 
 ```
 intent  →  direct work under the installed principles, or an ideate loop  →  ship
 ```
 
-Non-Claude agents (Codex / omp / Pi / Grok): the AGENTS.md choice installs the skills for them. In Codex / omp / Pi, use `$devlyn-ideate`; in Grok, use `/devlyn-ideate`, the same slash-command form as Claude Code. A drain from Pi or Grok needs [a pinned executor](#executor--devlyn-engines).
+Non-Claude agents (Codex / omp / Pi / Grok): the default choice installs the skills for them. In Codex / omp / Pi, use `$devlyn-ideate`; in Grok, use `/devlyn-ideate`, the same slash-command form as Claude Code. A drain from Pi or Grok needs [a pinned executor](#executor--devlyn-engines).
+
+### Terminal sessions — `devlyn run`
+
+`devlyn run claude`, `devlyn run codex` or `devlyn run omp` starts the engine in this terminal with the same principles and skills the Devlyn app delivers, from the selected release. Arguments after the engine name go to the engine. See [docs/harness-run.md](docs/harness-run.md).
 
 ### Plan and drain loops — `/devlyn-ideate`
 
@@ -62,7 +66,7 @@ Give ideate an intent or a document. It writes a loop package — a meta-prompt
 | `/devlyn-ideate status` | Pending, active, accepted and failed counts; the next runnable task; delivery and recovery blockers. |
 | `/devlyn-ideate drain` | Runs the queue serially and hands-free. |
 
-A bare intent is planned and, when your request authorizes the work, added and drained without another confirmation; no arguments shows status. Questions come only when the answer changes behavior, scope, data semantics, acceptance or delivery, each with a recommended answer; `--autonomous` plans without questions, recording ordinary low-consequence, reversible defaults within the request, including user-visible details; material ambiguity in intended outcomes, persistent data or state semantics, or public surface beyond the request stops planning with a concrete question. Each task runs in its own worktree with the executor pinned by `/devlyn-engines` (default: the CLI you opened; Pi and Grok need a pin) under your installed CLAUDE.md/AGENTS.md instructions. Tasks start from committed state, the branch you added the loop on or the remote base for `auto`/`pr`, so a task's worktree holds only what is committed there. A task would run without installed CLAUDE.md/AGENTS.md that exist only in this checkout, so add stops while they differ from HEAD, and drain waits while they differ from the task's start commit. It is marked `[x]` only when its declared checks pass on its committed source and its required reviews cover it: the checks run through the drain's runner (a wholly clean run the executor lists for that source is reused; the drain runs any other check itself), and review coverage is attested by records the executor submits; a failed task becomes `[F]` with its reason and blocks only its dependents. An interrupted drain resumes without repeating accepted work. `--local-only` (or `--no-push`) keeps delivery local: each accepted task stays on its `devlyn/<loop-id>/<task-id>` branch in a retained worktree, nothing is merged or pushed, and the drain report's `Bring into` command brings the result into your branch, stopping if your files cannot be preserved.
+A bare intent is planned and, when your request authorizes the work, added and drained without another confirmation; no arguments shows status. Questions come only when the answer changes behavior, scope, data semantics, acceptance or delivery, each with a recommended answer; `--autonomous` plans without questions, recording ordinary low-consequence, reversible defaults within the request, including user-visible details; material ambiguity in intended outcomes, persistent data or state semantics, or public surface beyond the request stops planning with a concrete question. Each task runs in its own worktree with the executor pinned by `/devlyn-engines` (default: the CLI you opened; Pi and Grok need a pin) under the Devlyn defaults and your project's CLAUDE.md/AGENTS.md. Tasks start from committed state, the branch you added the loop on or the remote base for `auto`/`pr`, so a task's worktree holds only what is committed there. A task would run without installed CLAUDE.md/AGENTS.md that exist only in this checkout, so add stops while they differ from HEAD, and drain waits while they differ from the task's start commit. It is marked `[x]` only when its declared checks pass on its committed source and its required reviews cover it: the checks run through the drain's runner (a wholly clean run the executor lists for that source is reused; the drain runs any other check itself), and review coverage is attested by records the executor submits; a failed task becomes `[F]` with its reason and blocks only its dependents. An interrupted drain resumes without repeating accepted work. `--local-only` (or `--no-push`) keeps delivery local: each accepted task stays on its `devlyn/<loop-id>/<task-id>` branch in a retained worktree, nothing is merged or pushed, and the drain report's `Bring into` command brings the result into your branch, stopping if your files cannot be preserved.
 
 ### Delivery
 
@@ -107,29 +111,25 @@ An account server you never list remains available.
 
 ### Migration from earlier versions
 
-Reinstall with the new version to refresh instructions and skills for the selected
-targets. Claude uses `CLAUDE.md`; Codex, Grok, omp and Pi share `AGENTS.md`.
-Devlyn updates its checksum-marked instruction block and preserves project-specific
-rules outside it. Keep custom rules outside the block; they take precedence over
-its defaults. Exact pre-update backups are saved in `.devlyn/instructions/`.
-When recovery is needed, pre-existing symlinks or non-directory entries at `.devlyn/` or
-`.devlyn/instructions/` stop installation without replacing the instruction file.
-
-Older and mixed-version templates migrate automatically. Within recognizable
-Devlyn sections, exact historical paragraphs and list items are replaced;
-modified or unknown text and its headings are preserved outside the new block.
-Edits inside an existing managed block are preserved outside it too. Plain custom
-files and rules outside managed blocks retain their contents. Unknown old text
-is kept conservatively, even when it may contain obsolete defaults.
-Malformed or duplicate managed markers still stop with an exact `.backup`, new
-defaults in `.incoming`, and a `.merge.md` guide; the original remains unchanged.
+Reinstall with the new version to refresh skills for the selected targets. Install and
+update leave `CLAUDE.md` and `AGENTS.md` byte-identical.
+
+Earlier installs put the principles in those files, inside a checksum-marked block or as
+a whole template. [Cleanup](docs/harness-cleanup.md) removes an intact copy, keeps the text
+around it byte-for-byte and deletes a file that held only the copy; a `@AGENTS.md` import
+left without its file is harmless. Exact pre-removal backups are saved in
+`.devlyn/instructions/`; pre-existing symlinks or non-directory entries at `.devlyn/` or
+`.devlyn/instructions/` stop the removal without touching the file.
+
+A copy someone edited stays exactly as it is, as does any text Devlyn cannot prove it wrote:
+a quoted example, or malformed or duplicate markers. Devlyn's defaults replace a remaining
+block for each session.
 Portability refreshes the offline fingerprints from Git history using
 `node scripts/update-instruction-templates.js` before testing; publish ships that tested tarball.
 Installation needs no Git or network.
-Use 3.1.3 or newer consistently: older installers still overwrite `CLAUDE.md`.
 
 Upgrading to 4.1.0: `npx devlyn-cli -y` in a 4.x project keeps its Claude Code install
-current and adds `AGENTS.md` + `.agents/skills/`. Earlier releases put the Codex, omp, Pi
+current and adds `.agents/skills/`. Earlier releases put the Codex, omp, Pi
 and Grok skills in `~/.codex/skills`, `~/.agents/skills` and `~/.grok/skills`; a project
 install no longer refreshes them and names each one it finds. Refresh them with `--global`
 or delete them; global installs and `update` clean Devlyn’s retired `~/.grok/skills` entries automatically.
@@ -224,7 +224,7 @@ Selected during install. Run `npx devlyn-cli` again to add more.
 </details>
 
 <details>
-<summary><strong>MCP Servers</strong> — installed via <code>claude mcp add</code>, offered with the CLAUDE.md choice</summary>
+<summary><strong>MCP Servers</strong> — installed via <code>claude mcp add</code>, offered with the Claude Code choice</summary>
 
 | Server | Description |
 |---|---|
@@ -246,7 +246,7 @@ Only `__pycache__` directories containing exclusively regular `*.pyc` files coun
 
 - **Node.js 20 (20.17+), 22 (22.13+) or 23.5+** and npm
 - **Python 3.11+** available as `python3` for the harness, and **Git** for safe installation and the harness
-- **An agent CLI** installed and configured: Codex, omp, Pi or Grok (AGENTS.md), or [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (CLAUDE.md)
+- **An agent CLI** installed and configured: Codex, omp, Pi or Grok, or [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
 - **For `auto`/`pr` delivery**, an `origin` remote naming one GitHub repository and an authenticated [`gh`](https://cli.github.com/)
 
 On native Windows, use native Node/npm and Python plus Git for Windows Bash for the shipped shell wrapper. Run `npx devlyn-cli -y` in the project (add `--claude` for Claude Code). Skill folders follow the Agent Skills naming standard (for example `devlyn-ideate`), so a project that commits them checks out on Windows. Harness text is UTF-8 without requiring `PYTHONUTF8`.

package/bin/devlyn.js

@@ -10,7 +10,7 @@ const { parseTree, findNodeAtLocation, applyEdits } = require('jsonc-parser');
 const CONFIG_SOURCE = path.join(__dirname, '..', 'config');
 const OPTIONAL_SKILLS_SOURCE = path.join(__dirname, '..', 'optional-skills');
 const PKG = require('../package.json');
-const { updateInstructions, InstructionError, holdsDevlynDefaults, importsAgentsMd } = require('./instructions');
+const { removeInstructions, InstructionError, holdsDevlynDefaults } = require('./instructions');
 const { contentHash, fingerprint, gitEnvironment, isIgnoredEntry, trackedPaths } = require('./skill-ownership');
 const SKILL_HISTORY = require('./skill-history.json');
 const CLEANUP_HISTORY = require('./cleanup-history.json');
@@ -105,18 +105,13 @@ function hasDevlynInstall(root) {
 }
 
 // A devlyn Claude install in this scope. Globally only the marker a `--global --claude` run
-// writes counts; in a project also a devlyn skill (0.6.0 and later), command (0.2-0.5) or
-// CLAUDE.md with devlyn defaults, held or imported from AGENTS.md, which a team may commit
-// while ignoring .claude/. An optional devlyn skill is not one: 4.0.1 put those into
-// .claude/skills without the Claude target. A CLAUDE.md link (often to AGENTS.md) is not the
-// Claude target's file: updateInstructions refuses links.
+// writes counts; in a project also a devlyn skill (0.6.0 and later) or command (0.2-0.5). An
+// optional devlyn skill is not one: 4.0.1 put those into .claude/skills without the Claude target.
 function hasDevlynClaude(global) {
   const claudeDir = path.dirname(skillRoots('claude', global)[0]);
   if (global) return fs.existsSync(path.join(claudeDir, 'skills', DEVLYN_INSTALL_MARKER));
   const names = (dir) => (fs.existsSync(dir) ? fs.readdirSync(dir) : []);
   const optional = new Set(OPTIONAL_ADDONS.map((addon) => addon.name));
-  const instructions = path.join(path.dirname(claudeDir), 'CLAUDE.md');
-  const claude = fs.lstatSync(instructions, { throwIfNoEntry: false })?.isFile() ? fs.readFileSync(instructions, 'utf8') : '';
   const root = path.join(claudeDir, 'skills');
   const deprecated = new Set([...deprecatedSkillPaths(root)].map((full) => path.basename(full).toLowerCase()));
   return names(root).some((name) => {
@@ -124,8 +119,7 @@ function hasDevlynClaude(global) {
     return name === DEVLYN_INSTALL_MARKER
       || (name.startsWith('devlyn') && !optional.has(name.replace(/[:\uF03A]/g, '-')));
   })
-    || names(path.join(claudeDir, 'commands')).some((name) => name.startsWith('devlyn.'))
-    || holdsDevlynDefaults('CLAUDE.md', claude) || importsAgentsDefaults(claude);
+    || names(path.join(claudeDir, 'commands')).some((name) => name.startsWith('devlyn.'));
 }
 
 // Exact Devlyn command names removed by previous versions, in either scope.
@@ -764,67 +758,19 @@ function updateProjectGitignore(markerEntry) {
 
 // With the Claude target in the same run, an AGENTS.md that links to this project's CLAUDE.md (a
 // common Claude-first setup) gets its devlyn block through CLAUDE.md. Any other link is refused.
-// AGENTS.md that is this project's CLAUDE.md under another name: a symlink to it, or the plain
-// file Git for Windows checks out in a symlink's place when core.symlinks is off (its whole
-// content is the link target). Compared by real path: a link to another hard link of CLAUDE.md
-// would go stale once CLAUDE.md is replaced.
-function agentsMdIsClaudeMd() {
-  const agents = path.join(projectDir(), 'AGENTS.md');
-  const claude = path.join(projectDir(), 'CLAUDE.md');
-  const stat = fs.lstatSync(agents, { throwIfNoEntry: false });
-  if (!stat || !fs.lstatSync(claude, { throwIfNoEntry: false })?.isFile()) return false;
-  const target = stat.isSymbolicLink() ? agents
-    : stat.isFile() && stat.size < 256 ? path.resolve(projectDir(), fs.readFileSync(agents, 'utf8'))
-      : null;
-  return target !== null && fs.existsSync(target) && fs.realpathSync.native(target) === fs.realpathSync.native(claude);
-}
-
-function installAgentsProject(withClaude, installedSkills = new Map()) {
-  if (!agentsMdIsClaudeMd()) {
-    updateInstructions('AGENTS.md');
-  } else if (withClaude) {
-    log('  → AGENTS.md is CLAUDE.md here, so it gets the devlyn block written there', 'dim');
-  } else {
-    throw new InstructionError('AGENTS.md is CLAUDE.md under another name here. Choose CLAUDE.md as well '
-      + '(npx devlyn-cli -y --claude) so the devlyn block is written once, into CLAUDE.md.');
-  }
+function installAgentsProject(installedSkills = new Map()) {
   installCoreSkills(skillRoots('agents', false)[0], installedSkills);
   updateProjectGitignore('.agents/skills/.devlyn-install.json');
 }
 
-// Whether Claude Code reads the devlyn defaults of AGENTS.md through an `@AGENTS.md` import in this CLAUDE.md text.
-// An AGENTS.md that is CLAUDE.md under another name holds CLAUDE.md's own defaults.
-function importsAgentsDefaults(claude) {
-  const agents = path.join(projectDir(), 'AGENTS.md');
-  return importsAgentsMd(claude) && !agentsMdIsClaudeMd() && fs.statSync(agents, { throwIfNoEntry: false })?.isFile() === true
-    && holdsDevlynDefaults('AGENTS.md', fs.readFileSync(agents, 'utf8'));
-}
-
-// Claude Code reads AGENTS.md only where no CLAUDE.md exists, or through a CLAUDE.md that imports it. So a new
-// CLAUDE.md imports an existing AGENTS.md, and a CLAUDE.md importing an AGENTS.md that holds devlyn defaults holds no
-// copy of its own, not even one it got while AGENTS.md lacked the block. Only the AGENTS.md target updates those defaults,
-// together with .agents/skills, so the Claude target stops while they need an update.
-function installClaudeInstructions() {
-  const file = path.join(projectDir(), 'CLAUDE.md');
-  const stat = fs.lstatSync(file, { throwIfNoEntry: false });
-  const initial = !stat && fs.statSync(path.join(projectDir(), 'AGENTS.md'), { throwIfNoEntry: false })?.isFile() ? '@AGENTS.md\n' : '';
-  const imported = importsAgentsDefaults(stat?.isFile() ? fs.readFileSync(file, 'utf8') : initial);
-  if (imported && updateInstructions('AGENTS.md', '', true, false)) {
-    throw new InstructionError('Claude Code reads AGENTS.md here, and its devlyn defaults need an update. Codex, omp, Pi and Grok '
-      + 'read them too, with .agents/skills, so choose AGENTS.md as well (npx devlyn-cli -y --claude) to update both together.');
-  }
-  updateInstructions('CLAUDE.md', initial, !imported);
-  if (imported) log('  → CLAUDE.md imports AGENTS.md, which holds the devlyn block', 'dim');
-}
-
-// Project CLAUDE.md and .claude/: skills and settings.
+// Project .claude/: skills and settings.
 function installClaudeCore(installedSkills = new Map()) {
   const skillsDir = skillRoots('claude', false)[0];
   const targetDir = path.dirname(skillsDir);
   // Read before any write, so settings this install cannot merge leave the Claude target as it was.
   const settingsPath = path.join(targetDir, 'settings.json');
   const unmergeable = (reason) => new InstructionError(`Cannot merge .claude/settings.json: ${reason}. `
-    + 'CLAUDE.md and .claude/ are unchanged; fix the file and rerun the same install command.');
+    + '.claude/ is unchanged; fix the file and rerun the same install command.');
   const settingsStat = fs.lstatSync(settingsPath, { throwIfNoEntry: false });
   if (settingsStat && !settingsStat.isFile()) throw unmergeable('not a regular file');
   let settings = {};
@@ -843,7 +789,6 @@ function installClaudeCore(installedSkills = new Map()) {
       && (!settings.env || typeof settings.env !== 'object' || Array.isArray(settings.env))) {
     throw unmergeable('env must be a JSON object');
   }
-  installClaudeInstructions();
   installCoreSkills(skillsDir, installedSkills);
   updateProjectGitignore('.claude/skills/.devlyn-install.json');
 
@@ -1073,34 +1018,32 @@ function install(targets, global, optionalNames = [], plan, afterInstall = () =>
   const home = fs.statSync(os.homedir(), { bigint: true, throwIfNoEntry: false });
   const here = fs.statSync(projectDir(), { bigint: true });
   if (!global && home?.dev === here.dev && home?.ino === here.ino) {
-    throw new InstructionError('This project is your home folder, so its CLAUDE.md, AGENTS.md and .claude/settings.json '
-      + 'would apply to every project. Run from a project folder, or use --global for skills only.');
+    throw new InstructionError('This project is your home folder, so its .claude/settings.json would apply to every project. '
+      + 'Run from a project folder, or use --global for skills only.');
   }
   const roots = targets.flatMap((target) => skillRoots(target, global));
   return withUserSkillLocks(global ? roots : [], () => {
     const installedSkills = new Map();
     if (!global) readProjectGitignore();
     plan ??= preflightSkills(roots, optionalNames);
-    // AGENTS.md first, whatever order the menu gave: a new CLAUDE.md holds the block only when AGENTS.md does not.
     for (const target of ['agents', 'claude'].filter((name) => targets.includes(name))) {
       if (global) skillRoots(target, true).forEach((root) => installCoreSkills(root, installedSkills));
-      else if (target === 'agents') installAgentsProject(targets.includes('claude'), installedSkills);
+      else if (target === 'agents') installAgentsProject(installedSkills);
       else installClaudeCore(installedSkills);
     }
     for (const name of optionalNames) installLocalSkill(name, roots, installedSkills);
     afterInstall();
     log(`\n✅ devlyn ${PKG.version} installed`, 'green');
-    if (global) log('The principles block installs per project: run npx devlyn-cli in the project without --global.');
+    log('The Devlyn app gives every session the principles; in a terminal, start with: npx devlyn-cli run <claude|codex|omp>');
     noticeGlobalDrift(roots);
-    cleanupScope(global ? os.homedir() : projectDir(), global,
-      global ? [] : targets.map((target) => target === 'agents' ? 'AGENTS.md' : 'CLAUDE.md'));
+    cleanupScope(global ? os.homedir() : projectDir(), global);
     if (!global) noticeIgnoredInstallFiles(installedSkills);
     return roots;
   });
 }
 
 // Cleanup visits existing paths in the command's scope; it never creates an install.
-function cleanupScope(base, global, activeInstructions = []) {
+function cleanupScope(base, global) {
   const warned = new Set();
   let found = false;
   const warning = (file, error) => {
@@ -1206,15 +1149,15 @@ function cleanupScope(base, global, activeInstructions = []) {
       log('  ✕ .claude/settings.json retired entries (removed)', 'dim');
     }
   });
-  const instructions = global ? [] : ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md', '.cursorrules', '.windsurfrules', '.github/copilot-instructions.md'];
-  for (const name of instructions.filter((name) => !activeInstructions.includes(name))) {
+  // CLAUDE.md and AGENTS.md stay as they are here: only a reviewed cleanup changes them.
+  const instructions = global ? [] : ['GEMINI.md', '.cursorrules', '.windsurfrules', '.github/copilot-instructions.md'];
+  for (const name of instructions) {
     const file = path.join(base, name);
     attempt(file, () => {
       if (!realParents(file) || !fs.lstatSync(file, { throwIfNoEntry: false })?.isFile()) return;
-      const evaluatorOnly = ['CLAUDE.md', 'AGENTS.md'].includes(name);
-      if (!updateInstructions(name, '', false, false, base, evaluatorOnly)) return;
+      if (!removeInstructions(name, false, base)) return;
       found = true;
-      updateInstructions(name, '', false, true, base, evaluatorOnly);
+      removeInstructions(name, true, base);
     });
   }
   return found;
@@ -1360,7 +1303,7 @@ async function init({ yes, claude, global }) {
     install(targets, global);
     log('\n💡 Add optional addons later: run `npx devlyn-cli` without -y', 'dim');
     const hints = [
-      ...(targets.includes('claude') ? [] : [`${global ? '~/.claude/skills' : 'CLAUDE.md + .claude/'} for Claude Code: add --claude`]),
+      ...(targets.includes('claude') ? [] : [`${global ? '~/.claude/skills' : '.claude/'} for Claude Code: add --claude`]),
       ...(global ? [] : ['every project on this machine: add --global']),
     ];
     if (hints.length > 0) log(`   ${hints.join(' · ')}`, 'dim');
@@ -1370,8 +1313,8 @@ async function init({ yes, claude, global }) {
   }
 
   const targetOptions = [
-    { key: 'agents', name: 'AGENTS.md — Codex · omp · Pi · Grok', desc: 'AGENTS.md + .agents/skills' },
-    { key: 'claude', name: 'CLAUDE.md — Claude Code', desc: 'CLAUDE.md + .claude/ (skills, settings)' },
+    { key: 'agents', name: 'Codex · omp · Pi · Grok', desc: '.agents/skills' },
+    { key: 'claude', name: 'Claude Code', desc: '.claude/ (skills, settings)' },
   ];
   const preselected = claude || hasDevlynClaude(false) || (global && hasDevlynClaude(true)) ? [0, 1] : [0];
   const targets = (await multiSelect('What to install', targetOptions, preselected)).map((option) => option.key);
@@ -1405,12 +1348,13 @@ async function init({ yes, claude, global }) {
 function showHelp() {
   showLogo();
   log('Usage:', 'green');
-  log('  npx devlyn-cli               Install/update devlyn: choose what (AGENTS.md, CLAUDE.md) and where (this project or global)');
+  log('  npx devlyn-cli               Install/update devlyn skills: choose which agents and where (this project or global)');
   log('  npx devlyn-cli update        Update every devlyn install already here (this project and your global skill folders) to this version; installs nothing new');
-  log('  npx devlyn-cli -y            Without prompts: AGENTS.md + .agents/skills, plus CLAUDE.md + .claude/ if this project has them');
-  log('  npx devlyn-cli -y --claude   Also install CLAUDE.md + .claude/ for Claude Code');
+  log('  npx devlyn-cli -y            Without prompts: .agents/skills, plus .claude/ if this project has it');
+  log('  npx devlyn-cli -y --claude   Also install .claude/ for Claude Code');
   log('  npx devlyn-cli -y --global   Skills only, for every project on this machine (~/.agents/skills, ~/.codex/skills; ~/.claude/skills with --claude, or when it already has a devlyn install)');
   log('  npx devlyn-cli list          List available skills');
+  log('  npx devlyn-cli run <engine>  Start claude, codex or omp in this terminal with the devlyn principles and skills');
   log('  npx devlyn-cli --help        Show this help\n');
   log('Optional skills (select during install):', 'green');
   OPTIONAL_ADDONS.filter((a) => a.type === 'local').forEach((skill) => {
@@ -1704,10 +1648,10 @@ function cleanupProjectFiles(base, includedHooks = new Set(), callerBase = base)
   return items;
 }
 
-// An intact managed block from an earlier release is brought up to date; owner text around it stays
-// byte-for-byte (updateInstructions). A current block is the team's principles and stays.
+// The release gives each session the principles (docs/harness-run.md), so an intact copy in a project
+// file is removed, owner text around it kept byte-for-byte (removeInstructions). A copy someone
+// edited stays exactly as it is: only recognized content is ever removed.
 function cleanupInstructions(base) {
-  const { inspectInstruction } = require('./harness-status');
   const items = [];
   for (const name of ['CLAUDE.md', 'AGENTS.md']) {
     const file = path.join(base, name);
@@ -1716,10 +1660,10 @@ function cleanupInstructions(base) {
     let text;
     try { text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(file)); }
     catch { continue; }
-    if (!/<!-- devlyn:instructions:begin sha256=/.test(text)) continue;
-    const template = fs.readFileSync(path.join(CONFIG_SOURCE, '..', name), 'utf8');
-    if (inspectInstruction(text, template, name).ownership === 'outdated') {
-      items.push({ kind: 'instructions', path: file, base, action: 'edit', reasons: [] });
+    if (removeInstructions(name, false, base)) {
+      items.push({ kind: 'instructions', path: file, base, action: 'remove', reasons: [] });
+    } else if (holdsDevlynDefaults(name, text)) {
+      items.push({ kind: 'instructions', path: file, base, action: 'skip', reasons: [cleanupReason('modified-copy')] });
     }
   }
   return items;
@@ -2071,6 +2015,11 @@ function cleanupValidateItem(item) {
 function cleanupApplyItem(item) {
   const invalid = cleanupValidateItem(item);
   if (invalid) return invalid;
+  // Before the generic removal: only the proven copy goes, never the owner's file.
+  if (item.kind === 'instructions') {
+    removeInstructions(path.basename(item.path), true, path.dirname(item.path));
+    return null;
+  }
   if (cleanupAction(item) === 'remove') {
     if (item.kind === 'legacy-hook') {
       const { safe, settings } = cleanupReadSettings(item.base);
@@ -2087,10 +2036,6 @@ function cleanupApplyItem(item) {
     else if (after !== text) replaceFile(item.path, after);
     return null;
   }
-  if (item.kind === 'instructions') {
-    updateInstructions(path.basename(item.path), '', true, true, path.dirname(item.path));
-    return null;
-  }
   return cleanupReason('unknown-item');
 }
 
@@ -2169,7 +2114,7 @@ function cleanupSupport(item) {
 }
 
 function cleanupCanInclude(item) {
-  return !cleanupSupport(item) && item.action === 'skip'
+  return !cleanupSupport(item) && item.kind !== 'instructions' && item.action === 'skip'
     && item.reasons.length === 1 && item.reasons[0].code === 'modified-copy';
 }
 
@@ -2391,7 +2336,7 @@ function cleanupDeliveryCommit(worktree, items, current, release, scope, base) {
   }
   const add = cleanupGit(worktree, ['add', '-u', '--', ...applied]);
   const commit = add.status === 0 && cleanupGit(worktree, ['-c', 'user.useConfigOnly=true', 'commit', '-q', '-m',
-    `chore(devlyn): remove legacy devlyn-cli copies\n\nDevlyn now delivers devlyn-cli ${PKG.version} to each session it starts, so the copies earlier\ninstalls committed here are no longer used. The managed principles block stays for teammates.`]);
+    `chore(devlyn): remove legacy devlyn-cli copies\n\nDevlyn now delivers devlyn-cli ${PKG.version} to each session it starts, so the copies earlier\ninstalls committed here, the principles block included, are no longer used.`]);
   if (!commit || commit.status !== 0) return release(cleanupReason('delivery-failed', { detail: (commit || add).stderr.trim() }));
   // This check must observe the committed delivery worktree, not project the still-unclean remote.
   const inputs = { machine: false, projects: [worktree], accountHomes: [] };
@@ -2527,6 +2472,9 @@ async function main() {
 const command = args[0];
 
 switch (command) {
+  case 'run':
+    await require('./harness-run').runMain(args.slice(1));
+    break;
   case 'cleanup':
     require('./release').runJson(() => cleanupCommand(args.slice(1)));
     break;