model-orchestrator 0.1.35 → 1.0.0

package/src/install.js

@@ -1,15 +1,40 @@
-import { readFileSync, existsSync, mkdirSync, writeFileSync, chmodSync, readdirSync, statSync, lstatSync, unlinkSync, realpathSync } from 'node:fs';
-import { join, dirname, relative, resolve, sep, parse as parsePath, posix } from 'node:path';
+import { readFileSync, existsSync, mkdirSync, writeFileSync, chmodSync, readdirSync, statSync, lstatSync, unlinkSync, realpathSync, openSync, closeSync, fstatSync, constants } from 'node:fs';
+import { join, dirname, isAbsolute, relative, resolve, sep, parse as parsePath, posix } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
 import { render } from './render.js';
+import { validateActivationOwnership } from './activation-ownership.js';
 import { createHash } from 'node:crypto';
-import { AIS, LEVELS, TOOLS, PROVIDERS, IMAGES, byId, toolById, providerById, npmSpec } from './catalog.js';
+import { ROLE_SPECS, assignRoles, roleTable, roleRoute, manifestRoles, inferPrimary } from './roles.js';
+import { LANE_FLAGS } from '../bin/cli-run.mjs';
+import { AIS, LEVELS, TOOLS, PROVIDERS, IMAGES, byId, toolById, providerById, npmSpec, summaryWithEvidence } from './catalog.js';
+import { companionRegistrationSteps } from './apply-companions.js';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const GENERATOR_VERSION = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8')).version;
 const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
 export const TEMPLATES = join(HERE, '..', 'templates');
 export const CLI_RUN_SRC = join(HERE, '..', 'bin', 'cli-run.mjs');
+// Compatibility with the 0.1.x filename; current docs use the public brief name.
+const LEGACY_BRIEF = ['TASK', 'BUN' + 'DLE.md'].join('_');
+// R1: a pre-existing settings or MCP JSON file larger than this is refused
+// before it is read or parsed, the same way invalid JSON is refused today.
+// Generous on purpose: real settings/MCP files are kilobytes, not megabytes.
+export const ACTIVATION_JSON_BYTE_CAP = 10 * 1024 * 1024; // 10 MB
+
+function readLegacyBrief(path, dir) {
+  const problems = preflight([{ rel: LEGACY_BRIEF }], dir);
+  if (problems.length) throw Object.assign(new Error(problems.join('; ')), { code: 'PREFLIGHT' });
+  const expected = lstatSync(path);
+  const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+  try {
+    const actual = fstatSync(fd);
+    if (!actual.isFile() || actual.dev !== expected.dev || actual.ino !== expected.ino) {
+      throw Object.assign(new Error('legacy brief changed during inspection; re-run the installer'), { code: 'PREFLIGHT' });
+    }
+    return { content: readFileSync(fd), stat: actual };
+  } finally { closeSync(fd); }
+}
 
 function walk(dir, base = dir) {
   const out = [];
@@ -37,23 +62,25 @@ function table(rows, header) {
   return [line(header), line(header.map(() => '---')), ...rows.map(line)].join('\n');
 }
 
-export function lanesTable(selected, plans = {}) {
-  const rows = selected.map((a) => [
+export function lanesTable(selected, plans = {}, primary = inferPrimary(selected)) {
+  const { roles } = assignRoles({ selected, primary, plans });
+  const rows = selected.map(a => [
     a.name,
-    a.lane === 'A' ? 'A (subscription, $0 per call)' : a.lane === 'B' ? 'B (metered)' : a.lane === 'local' ? 'local' : 'chat',
-    a.role,
-    a.cliRun ? '`cli-run ' + a.id + '`' : a.bin ? '`' + a.bin + '`' : 'the app',
+    a.facts.billing,
+    summaryWithEvidence(a),
+    Object.entries(roles).filter(([, role]) => role.ai === a.id).map(([id]) => id).join(', ') || 'none',
+    a.facts.cliRun ? '`cli-run ' + a.id + '`' : a.bin ? '`' + a.bin + '`' : 'the app',
     plans[a.id] ? `${plans[a.id].name} (${plans[a.id].headroom} headroom)` : 'not stated'
   ]);
-  return table(rows, ['AI', 'Lane', 'Wins at', 'Call it with', 'Plan']);
+  return table(rows, ['AI', 'Lane', 'What it is', 'Assigned roles', 'Call it with', 'Plan']);
 }
 
 function planGuidance(selected, plans = {}) {
   const lines = selected.filter((a) => plans[a.id]).map((a) => {
     const p = plans[a.id];
     const volume = p.headroom === 'base'
-      ? 'Keep this base-headroom lane for short second opinions. If it is primary, delegate volume to high or max headroom lanes.'
-      : 'Use this high or max headroom lane for volume: scoped well-specified builds, pre-ship second-family checks through cli-run, and first-pass research.';
+      ? 'Keep this base-headroom lane for short second opinions. If it is your main agent, delegate volume to high or max headroom lanes.'
+      : 'Use this high or max headroom lane for volume: scoped well-specified builds, first-pass research, and pre-ship reviews through cli-run when its configured model family differs from the author\'s.';
     return `- **${a.name}: ${p.name} (${p.headroom} headroom).** ${volume} Capability and independent-review rules are unchanged. Checked ${p.checked}.`;
   });
   return lines.length ? lines.join('\n') : 'State subscription plans with `--plans` to receive volume-allocation guidance. Capability and independent-review rules stay unchanged.';
@@ -77,7 +104,7 @@ export function installTable(selected) {
 export function gatewayModels(selected, apis = []) {
   const lines = [];
   if (selected.some((a) => a.id === 'ollama')) {
-    lines.push('  - model_name: local-small', '    litellm_params:', '      model: ollama/llama3.2:3b', '      api_base: http://ollama:11434');
+    lines.push('  - model_name: local-small', '    litellm_params:', `      model: ${byId.ollama.gatewayModel}`, '      api_base: http://ollama:11434');
   }
   for (const prov of apis) {
     for (const [alias, model] of prov.lanes) {
@@ -98,7 +125,7 @@ export function scriptInstallers(selected) {
   const lines = [];
   for (const a of selected) {
     if (a.install.script) lines.push(`say "  ${a.name}:  curl -fsSL ${a.install.script} -o /tmp/${a.id}-install.sh && less /tmp/${a.id}-install.sh && bash /tmp/${a.id}-install.sh"`);
-    else if (a.install.url && a.kind !== 'chat') lines.push(`say "  ${a.name}:  ${a.install.url}"`);
+    else if (a.install.url && a.facts.kind !== 'chat') lines.push(`say "  ${a.name}:  ${a.install.url}"`);
   }
   return lines.length ? lines.join('\n') : 'say "  none"';
 }
@@ -147,94 +174,134 @@ export function dirProblems(dir) {
   return problems;
 }
 
-// The lane the generated weekly audit calls: the first ENABLED cli-run lane
-// in this preference order. None enabled means the job refuses at run time
-// (exit 13) instead of calling a lane the installer disabled.
-export const AUDIT_LANE_ORDER = ['hermes', 'qwen', 'codex', 'agy', 'grok'];
-export function auditLane(selected) {
-  const enabled = new Set(selected.filter((a) => a.cliRun).map((a) => a.id));
-  return AUDIT_LANE_ORDER.find((l) => enabled.has(l)) || null;
+// The weekly job uses the independent review assignment, then an eligible
+// bulk runner. A main-agent fallback without a runner keeps the exit-13 guard.
+export function auditLane(selected, primary = selected[0]) {
+  const { roles } = assignRoles({ selected, primary });
+  const id = roles.review.ai ?? roles.bulk.ai ?? null;
+  return selected.some(a => a.id === id && a.facts.cliRun) ? id : null;
+}
+
+function stackContext(selected, primary, detected = new Set()) {
+  const installed = new Set(agentIds(primary));
+  const names = { plan: 'deep-planner', build: 'builder', review: 'code-reviewer', verify: 'finding-verifier', research: 'live-researcher', bulk: 'bulk-worker', read: 'reader' };
+  const agents = Object.fromEntries(Object.entries(names).filter(([, name]) => installed.has(name)));
+  return { selected, primary, detected, agents };
+}
+
+function rolePick(id, assignment, ctx) {
+  const entry = roleRoute(id, assignment, ctx);
+  if (!entry || !entry.ai) return `none selected: ${entry?.reason || entry?.why || 'no eligible lane'}`;
+  const ai = ctx.selected.find(a => a.id === entry.ai);
+  if (entry.command) return '`' + entry.command + '`';
+  if (entry.via === 'local') return `${ai.name} on your machine`;
+  if (entry.via === 'main-agent') {
+    if (ai.facts.kind === 'chat') return `paste the work into your main agent, ${entry.tier} tier`;
+    return `${entry.agent ? '`' + entry.agent + '` on ' : ''}your main agent, ${entry.tier} tier`;
+  }
+  return `${ai.name}, ${entry.tier} tier`;
 }
 
-// Everything ROUTING.md and RESEARCH_TRIAGE.md say about lanes is rendered
-// from the lanes the user actually has. A generated manual must never
-// recommend a command its own lanes.json disables.
-export function laneVars(selected) {
-  const has = (id) => selected.some((a) => a.id === id);
-  const categories = new Set(selected.flatMap((a) => a.laneCategories || []));
-  const supplies = (category) => categories.has(category);
-  const picks = [
-    ['cheapest-metered', 'Bulk classify / extract / summarize, data may leave the machine', 'the cheapest metered lane, then the fast tier', 'use the selected bulk lane and verify its output'],
-    ['local', 'Bulk work on data that must stay local', 'the local lane', 'a privacy lane; route here for confinement'],
-    ['fan-out', 'Many independent items each needing its own agent turn', 'a concurrent fan-out lane', 'one call, N children, on a subscription'],
-    ['live-data', 'Live web or social reads', 'the live-data CLI', 'subscription-covered; the same search on the API bills per call'],
-    ['second-coder', 'Code review, no changes', 'standard tier, or the second-coder CLI', 'a different model family catches what one misses'],
-    ['second-coder', 'Second-opinion audit of a security-shaped diff', 'the second-coder CLI in read-only audit mode', 'a second family challenges, the orchestrator reproduces'],
-    [null, 'Deep architecture / planning', 'deep tier', 'expensive to get wrong'],
-    [null, 'Well-specified execution', 'the orchestrator', 'execution does not need the top tier'],
-    ['largest-context', 'Long-document analysis', 'the largest-context lane, or caching on the primary', 'window size vs re-query cost'],
-    [null, 'Routing decisions themselves', 'the cheapest lane you have, or none', 'spend only the tokens the routing decision needs'],
-    ['free', 'Rough drafts, divergent reads, first-pass summaries', 'the free tier', '$0, and disagreement with the primary is information'],
-    ['cheapest-metered', 'Anything citing a line, a number, or a source', 'the cheapest metered lane with a full verification pass', 'verify every supporting number and citation']
-  ].filter(([category]) => !category || supplies(category)).map(([, ...row]) => row);
+// Routing advice uses the same assignments as the stack table and manifest.
+// Capability facts determine eligibility; selection order resolves equal fits.
+export function laneVars(selected, primary = selected[0]) {
+  const assignment = assignRoles({ selected, primary });
+  const ctx = stackContext(selected, primary);
+  const { roles } = assignment;
+  const rolesForPrimary = routingRoles(primary);
+  const pick = id => rolePick(id, assignment, ctx);
+  // The installed subagent labels describe only main-agent assignments.
+  // An external winner must reach the action instructions as well as the table.
+  const assignedLabel = (id, local) => roles[id]?.ai && roles[id].ai !== primary?.id ? pick(id) : local;
+  const assignedRoles = {
+    PLANNER_ROLE: assignedLabel('plan', rolesForPrimary.PLANNER_ROLE),
+    BUILDER_ROLE: assignedLabel('build', rolesForPrimary.BUILDER_ROLE),
+    REVIEW_ROLE: assignedLabel('review', rolesForPrimary.REVIEW_ROLE),
+    FINDING_ROLE: assignedLabel('verify', rolesForPrimary.FINDING_ROLE),
+    DONE_ROLE: assignedLabel('verify', rolesForPrimary.DONE_ROLE),
+    LIVE_ROLE: assignedLabel('research', rolesForPrimary.LIVE_ROLE),
+    BULK_ROLE: assignedLabel('bulk', rolesForPrimary.BULK_ROLE),
+    READER_ROLE: assignedLabel('read', rolesForPrimary.READER_ROLE)
+  };
+  // TIERS.md's "Role" column is the one place several rows can carry the
+  // SAME bare command (two different rows can both land on `cli-run grok`,
+  // and FINDING_ROLE/DONE_ROLE are literally the same 'verify' assignment
+  // shown twice): a bare command alone does not say which row it is (C2).
+  // ROUTING.md and ORCHESTRATOR.md keep the assignedRoles values above
+  // (their decision-tree and activation text are pinned to that bare
+  // shape), so this labels a separate set of vars for TIERS.md only.
+  const externalWinner = (id) => Boolean(roles[id]?.ai && roles[id].ai !== primary?.id);
+  const tierRole = (value, id, label) => externalWinner(id) ? `${label} (${value})` : value;
+  const tierRoles = {
+    TIER_PLANNER_ROLE: tierRole(assignedRoles.PLANNER_ROLE, 'plan', 'planning'),
+    TIER_REVIEW_ROLE: tierRole(assignedRoles.REVIEW_ROLE, 'review', 'code review'),
+    TIER_FINDING_ROLE: tierRole(assignedRoles.FINDING_ROLE, 'verify', 'reproduce a finding'),
+    TIER_BUILDER_ROLE: tierRole(assignedRoles.BUILDER_ROLE, 'build', 'build'),
+    TIER_LIVE_ROLE: tierRole(assignedRoles.LIVE_ROLE, 'research', 'live research'),
+    TIER_BULK_ROLE: tierRole(assignedRoles.BULK_ROLE, 'bulk', 'bulk work'),
+    TIER_DONE_ROLE: tierRole(assignedRoles.DONE_ROLE, 'verify', 'check definition of done'),
+    TIER_READER_ROLE: tierRole(assignedRoles.READER_ROLE, 'read', 'read many files')
+  };
+  const reviewer = selected.find(a => a.id === roles.review.ai);
+  // No reviewer: state the self-check once (dropping roles.review.why here,
+  // which restates the same point) and end without a period, so
+  // ROUTING.md's fixed "... with appropriate effort." tail reads as one
+  // sentence instead of a second, dangling one glued after a full stop
+  // (C3). "review" still ends every "Why" column via roles.review.why
+  // directly, so that reasoning is not lost, only not duplicated here.
+  const review = reviewer
+    ? `${pick('review')} (different model family from the main agent by default; verify the current models before dispatch${reviewer.facts.readOnlyMode ? '; read-only filesystem sandbox' : '; request review only and check the CLI permissions'})`
+    : `${rolesForPrimary.REVIEW_ROLE} in a fresh context. No different-family reviewer is selected: treat this as a self-check`;
+  const picks = ROLE_SPECS.filter(spec => roles[spec.id]).map(spec => [spec.job, spec.id === 'review' ? review : pick(spec.id), roles[spec.id].why]);
+  const metered = selected.some(a => a.facts.billing === 'pay-per-token');
+  const free = selected.some(a => a.facts.billing === 'free');
   const cost = [
-    'Prompt caching everywhere it fits: frozen prefix first, volatile text last.',
-    'Cascade: cheapest capable tier first, escalate on signal.',
-    ...(supplies('cheapest-metered') ? ['Batch APIs where the selected provider supports them, for work that can wait.'] : []),
-    ...(supplies('free') ? ['A free model for routing decisions.'] : []),
-    'Effort and reasoning knobs before model swaps; often the bigger lever.',
-    'Alias-based config so a vendor rename is a one-line repoint.'
+    'Prompt caching where it fits: frozen prefix first, volatile text last.',
+    `Use the assigned bulk route for bounded volume: ${pick('bulk')}. ${roles.bulk.why}.`,
+    ...(metered ? ["Batch APIs where the selected provider supports them, for work that can wait. When a rate is unverified, check your provider's rate."] : []),
+    ...(free ? ['A free model can carry routing decisions when its tools and context fit.'] : []),
+    'Select effort and scoped context before changing model tiers.',
+    'Read the current model roster before choosing an explicit model.'
   ];
-  const enabled = selected.filter((a) => a.cliRun).map((a) => a.id);
-  const cr = (id) => '`cli-run ' + id + '`';
-  const step0 = [];
-  if (has('hermes')) step0.push(`${cr('hermes')} (the free tier) for rough drafts and divergent reads`);
-  if (has('qwen')) step0.push(`${cr('qwen')} (the cheapest metered lane) for structured bulk, never for anything citing a line, number or source`);
-  if (has('grok')) step0.push(`${cr('grok')} for X and live web reads at $0`);
-  if (has('codex')) step0.push(`${cr('codex --audit')} for a second-opinion read by a second model family`);
-  if (has('agy')) step0.push(`${cr('agy')} for research sweeps and concurrent fan-out`);
-  const stage1 = [];
-  if (has('codex')) stage1.push(`${cr('codex')} for a second-opinion critique of the map`);
-  if (has('grok')) stage1.push(`${cr('grok')} to verify current API behaviour instead of trusting recall`);
-  if (has('hermes')) stage1.push(`${cr('hermes')} for a divergent read`);
-  if (has('agy')) stage1.push(`${cr('agy')} for a wide sweep of prior art`);
-  const examples = [];
-  examples.push(has('grok') ? `| "What is trending on X today" | ${cr('grok')} |` : '| "What is trending on X today" | live-researcher (standard tier with web tools) |');
-  examples.push(has('codex') ? `| "Audit this auth diff" | ${cr('codex --audit')} |` : '| "Audit this auth diff" | code-reviewer at deep tier, in a fresh context told to challenge |');
-  examples.push(has('qwen') ? `| "Classify these 200 items" | bulk-worker, or ${cr('qwen')} if the items may leave the machine |` : '| "Classify these 200 items" | bulk-worker |');
-  examples.push(enabled.length >= 2 ? '| "Research this topic properly" | several engines in parallel, see `RESEARCH_TRIAGE.md` |' : '| "Research this topic properly" | deep tier plans, standard tier sweeps, a fresh context challenges; see `RESEARCH_TRIAGE.md` |');
-  const roles = [];
-  if (has('agy')) roles.push('| Web sweep | `cli-run agy` | widest landscape pass |');
-  if (has('codex')) roles.push('| Second-opinion read | `cli-run codex --audit` | question the premise, hunt for what the others would get wrong |');
-  if (has('grok')) roles.push('| Live data | `cli-run grok` | dated primary sources, real-time reads |');
-  if (has('hermes')) roles.push('| Cheap divergent read | `cli-run hermes` | another opinion at $0 |');
-  if (has('qwen')) roles.push('| Structured extraction | `cli-run qwen` | pull the facts into a table; never trust its citations without a check |');
-  roles.push('| Triage + the durable record | the orchestrator | opens primary sources, marks every claim, writes the artifact |');
-  const run = [];
-  if (has('agy')) run.push('node bin/cli-run.mjs agy   --brief "$BRIEF" --timeout 900 > research/out-agy.md');
-  if (has('codex')) run.push('node bin/cli-run.mjs codex --audit --brief "$BRIEF" --timeout 900 > research/out-codex.md');
-  if (has('grok')) run.push('node bin/cli-run.mjs grok  --brief "$BRIEF" --timeout 900 > research/out-grok.md');
-  if (has('hermes')) run.push('node bin/cli-run.mjs hermes --brief "$BRIEF" --timeout 900 > research/out-hermes.md');
-  if (has('qwen')) run.push('node bin/cli-run.mjs qwen  --brief "$BRIEF" --timeout 900 > research/out-qwen.md');
+  const enabled = selected.filter(a => a.facts.cliRun);
+  const step0 = ROLE_SPECS.filter(spec => roles[spec.id]?.ai && roles[spec.id].ai !== primary?.id)
+    .map(spec => `${pick(spec.id)} for ${spec.job.toLowerCase()}; ${roles[spec.id].why}`);
+  const stage1 = ['research', 'review', 'fan-out'].filter(id => roles[id]?.ai)
+    .map(id => `${id === 'review' ? review : pick(id)} for ${id === 'research' ? 'current primary sources' : id === 'review' ? 'a critique of the context file' : 'independent research units'}`);
+  const examples = [
+    `| "What is current on this topic" | ${pick('research')}; ${roles.research.why} |`,
+    `| "Audit this auth diff" | ${review} |`,
+    `| "Classify these 200 items" | ${pick('bulk')} |`,
+    '| "Research this topic properly" | plan the question, collect primary sources and verify claims; see `RESEARCH_TRIAGE.md` |'
+  ];
+  const researchRoles = ['research', 'review', 'bulk', 'fan-out'].filter(id => roles[id]?.ai)
+    .map(id => `| ${ROLE_SPECS.find(spec => spec.id === id).job} | ${id === 'review' ? review : pick(id)} | ${roles[id].why} |`);
+  researchRoles.push('| Triage + the durable record | the main agent | opens primary sources, marks every claim, writes the artifact |');
+  const runLanes = new Map();
+  for (const id of ['review', 'research', 'bulk', 'fan-out']) {
+    const entry = roleRoute(id, assignment, ctx);
+    if (entry?.command && !runLanes.has(entry.ai)) runLanes.set(entry.ai, entry.command);
+  }
+  const run = [...runLanes].map(([id, command]) => `node bin/cli-run.mjs ${command.replace(/^cli-run /, '')} --brief "$BRIEF" --timeout 900 > research/out-${id}.md`);
   return {
+    ...assignedRoles,
+    ...tierRoles,
     TASK_LANES_TABLE: table(picks, ['Task type', 'Pick', 'Why']),
     COST_PLAYBOOK: cost.map((line, i) => `${i + 1}. ${line}`).join('\n'),
-    FAN_OUT_ADVICE: supplies('fan-out') ? ' Many independent items each needing its own agent turn → the selected concurrent fan-out lane.' : '',
-    METERED_CITATION_NOTE: supplies('cheapest-metered') ? " A lane's figure is re-derived before it is repeated: verify every supporting number and citation from the cheapest metered lane." : '',
-    RESEARCH_SELECTION_ADVICE: enabled.length >= 2
-      ? 'Send the same PLAN to your selected CLI lanes, preferring different model families. Run each through `cli-run` so a run that produced nothing exits 10 and is treated as a missing engine.'
-      : 'Use the primary agent for the sweep, then a fresh-context second-opinion turn. Add CLI lanes from different model families for independent research passes.',
-    GAP_ANALYSIS_LANE: supplies('second-coder')
-      ? 'a **different model family** reading the same artifact. Use the selected second-opinion coder lane in read-only mode; verify each finding before acting.'
-      : 'a fresh-context second pass reading the same artifact. Use a different model family when one is available; verify each finding before acting.',
-    LANE_STEP0: step0.length ? step0.map((l) => '   - ' + l).join('\n') : '   - none selected yet: every task stays on your primary agent\'s tiers until you add a lane (re-run the installer with more AIs)',
-    STAGE1_LANES: stage1.length ? '; ' + stage1.join(', ') : '',
-    ATTACK_LANE: has('codex') ? '`cli-run codex --audit` (a second model family in a read-only sandbox)' : 'code-reviewer at deep tier, in a fresh context told to challenge and allowed to answer CLEAN',
-    LIVE_LANE: has('grok') ? '`cli-run grok` first ($0), then' : '',
-    BULK_LANE: has('qwen') ? ', or `cli-run qwen` if the data may leave your machine' : has('hermes') ? ', or `cli-run hermes` for a free rough pass' : '',
+    FAN_OUT_ADVICE: roles['fan-out'] ? ` Many independent items each needing their own agent turn → ${pick('fan-out')}.` : '',
+    METERED_CITATION_NOTE: metered ? ' Verify every supporting number and citation returned by a pay-per-token lane.' : '',
+    RESEARCH_SELECTION_ADVICE: `Use ${pick('research')} for current primary sources. ${roles.research.why}. ` + (enabled.length >= 2
+      ? 'Send a shared task brief to selected lanes with complementary capabilities; prefer different model families for independent perspectives.'
+      : 'Use a fresh context to challenge the sweep; add a different model family for independent research.') + ` For review, use ${review}.`,
+    GAP_ANALYSIS_LANE: `${review}. Give it the same artifact and verify each finding before acting.`,
+    LANE_STEP0: step0.length ? step0.map(line => '   - ' + line).join('\n') : '   - no separate lane selected yet: use your main agent\'s tiers; keep local-only work off cloud lanes and arrange independent review separately',
+    STAGE1_LANES: stage1.length ? '; ' + stage1.join('; ') : '',
+    ATTACK_LANE: review,
+    LIVE_LANE: `${pick('research')} for current sources, then`,
+    BULK_LANE: `; assigned bulk route: ${pick('bulk')}`,
     LANE_EXAMPLES: examples.join('\n'),
-    RESEARCH_ROLES: roles.join('\n'),
-    RESEARCH_RUN: run.length ? run.join('\n') : '# no cli-run lane selected: run the sweep on your primary agent, then a fresh second-opinion turn (protocols/deep-research.md, level 1 shape)',
+    RESEARCH_ROLES: researchRoles.join('\n'),
+    RESEARCH_RUN: run.length ? run.flatMap(command => ['# Or: ' + command.replace('node bin/cli-run.mjs', 'aunx cli-run'), command]).join('\n') : '# no separate cli-run assignment: run the sweep on your main agent, then a fresh-context self-check',
     RESEARCH_ENGINES: String(run.length)
   };
 }
@@ -246,7 +313,7 @@ export function laneVars(selected) {
 // note) is gated on this so a primary with no verified premise keeps the
 // original, more conservative wording.
 export function subagentsLoadRules(primary) {
-  return !!(primary && primary.subagentsLoadRules);
+  return !!(primary && primary.facts.loadsProjectRules);
 }
 
 // Canonical agent order, tier-first. Used to render a stable, non-hardcoded
@@ -254,8 +321,9 @@ export function subagentsLoadRules(primary) {
 // shipped, so a future agent addition or removal cannot leave the sentence
 // stale the way the finding-verifier omission did.
 const AGENT_ORDER = ['deep-planner', 'builder', 'code-reviewer', 'finding-verifier', 'live-researcher', 'bulk-worker', 'done-verifier', 'reader'];
-export function claudeAgentIds() {
-  const dir = join(TEMPLATES, 'agents', 'claude-code');
+function agentIds(primary) {
+  if (!primary?.facts.agentDefinitions) return [];
+  const dir = join(TEMPLATES, 'agents', primary.id);
   if (!existsSync(dir)) return [];
   const files = readdirSync(dir).filter((f) => f.endsWith('.md') && f !== 'README.md').map((f) => f.replace(/\.md$/, ''));
   const set = new Set(files);
@@ -263,40 +331,51 @@ export function claudeAgentIds() {
   const extra = files.filter((id) => !AGENT_ORDER.includes(id)).sort();
   return [...ordered, ...extra];
 }
+export function claudeAgentIds() {
+  return agentIds(byId['claude-code']);
+}
 
-// The compact "pick the lane before acting" table, rendered from the AIs the
+function routingRoles(primary) {
+  const installed = new Set(agentIds(primary));
+  const role = (id, label) => installed.has(id) ? id : `${label} role on the main agent`;
+  return {
+    BULK_ROLE: role('bulk-worker', 'bulk processing'),
+    BUILDER_ROLE: role('builder', 'build'),
+    READER_ROLE: role('reader', 'reading'),
+    REVIEW_ROLE: role('code-reviewer', 'code review'),
+    FINDING_ROLE: role('finding-verifier', 'finding verification'),
+    DONE_ROLE: role('done-verifier', 'completion verification'),
+    PLANNER_ROLE: role('deep-planner', 'planning'),
+    LIVE_ROLE: role('live-researcher', 'live research')
+  };
+}
+
+// The compact "choose a route before acting" table, rendered from the AIs the
 // user actually selected and the agents actually installed, never a second
 // hand-typed copy of ROUTING.md's decision tree.
-export function routeGateTable(selected) {
-  const rows = [
-    ['Bulk or mechanical, many similar items', 'bulk-worker'],
-    ['Needs live data', 'live-researcher'],
-    ['Review without changing', 'code-reviewer'],
-    ['Findings from a review or a scanner', 'finding-verifier, before any repair'],
-    ['Reading or digesting many files or notes', 'reader'],
-    ['Checking a tracker item against its stated done-signal', 'done-verifier'],
-    ['Ambiguous, architectural, expensive to get wrong', 'deep-planner'],
-    ['Everything else that changes files', 'builder, by default']
-  ];
-  for (const a of selected.filter((x) => x.cliRun)) rows.push([a.role, '`cli-run ' + a.id + '`']);
+export function routeGateTable(selected, primary = inferPrimary(selected)) {
+  const assignment = assignRoles({ selected, primary });
+  const ctx = stackContext(selected, primary);
+  const rows = ROLE_SPECS.filter(spec => assignment.roles[spec.id])
+    .map(spec => [spec.job, rolePick(spec.id, assignment, ctx)]);
   return table(rows, ['Task', 'Lane']);
 }
 
 // The marked block route-gate.mjs extracts at runtime. Installed only for
 // claude-code so the hook always finds a block to read; other primaries get
 // no hook and so get no block.
-export function routeGateSection(selected) {
+export function routeGateSection(selected, primary = inferPrimary(selected)) {
   return [
     '<!-- route-gate:start -->',
-    '## Route gate: pick the lane before acting',
+    '## Route gate: choose a route before acting',
     '',
     'Injected on every turn by the `route-gate` hook, so this table is read at runtime rather than recalled from memory.',
     '',
-    routeGateTable(selected),
+    routeGateTable(selected, primary),
     '',
     "Stay inline only when: (a) the brief would cost as much as the work itself, (b) the task needs this conversation's own context, (c) it is the human's decision or the final verification of delegated work (a delegate never verifies itself).",
     '',
-    'Never: the built-in Explore or Plan agents for rule-bound work (they skip CLAUDE.md). general-purpose taking work a named agent already owns.',
+    'When work depends on project rules, use a named agent that loads those rules. The built-in Explore and Plan agents skip CLAUDE.md; give their rule-bound work to the matching named agent.',
     '',
     'End every reply with a hidden marker: `<!-- route: <lane> | <why, a few words> -->`. The route-metrics hook reads only the lane out of it, so routing coverage can be measured instead of assumed.',
     '<!-- route-gate:end -->'
@@ -305,45 +384,39 @@ export function routeGateSection(selected) {
 
 // ROUTING.md / ORCHESTRATOR.md decision-tree rule 5 and the "Who builds"
 // section read differently for claude-code, because only claude-code has the
-// verified premise that its subagents load CLAUDE.md. Every other primary
-// keeps the original wording: the orchestrator builds the main line directly
-// and a subagent or second CLI is assumed to hold none of these rules.
+// verified premise that its subagents load CLAUDE.md. Other agents verify
+// rules and tool reach during Assign before handing off a section.
 export function decisionRule5(primary) {
   return subagentsLoadRules(primary)
-    ? `5. **Everything else that changes files** → builder executes by default. The orchestrator plans, briefs, verifies and talks to the human; it stays inline only when (a) the brief would cost as much as the work, (b) the task needs this conversation's own context, or (c) it is the human's decision, or the final verification of delegated work (a delegate never verifies itself). Never route rule-bound work to the built-in Explore or Plan agents: both skip CLAUDE.md. general-purpose should not take work a named agent already owns.`
-    : `5. **Everything else that changes files** → the orchestrator builds it directly. Bounded sub-parts go to cheaper tiers; the main build is never handed off whole.`;
+    ? `5. **When the task changes files**, builder executes by default after Assign confirms its tools, rules and context fit. The main agent briefs, combines sections, verifies and talks to the human. Keep conversation-dependent decisions and final verification with the main agent. When rules matter, use the matching named agent; the built-in Explore and Plan agents skip CLAUDE.md.`
+    : `5. **When the task changes files**, the main agent builds it directly until Assign verifies another lane can carry the required tools, context and rules. Give a suitable delegate the whole scope and its bounded section in a task brief.`;
 }
+// ORCHESTRATOR.md's own decision tree already lists items 1-7 (see the
+// template); this rule lands after all of them, so it continues that
+// sequence as 8, not the "5" that fits ROUTING.md's shorter, differently
+// ordered tree above (C4).
 export function decisionRule5Beginner(primary) {
   return subagentsLoadRules(primary)
-    ? `5. **Everything else that changes files or executes a known plan** → builder executes by default, at standard tier. The orchestrator plans, briefs, verifies and talks to you; it stays inline only when (a) the brief would cost as much as the work, (b) the task needs this conversation's own context, or (c) it is your decision, or the final verification of delegated work. Never route rule-bound work to the built-in Explore or Plan agents: both skip CLAUDE.md.`
-    : `5. **Everything else that changes files or executes a known plan** → you build it directly, at standard tier. The main build is never handed off whole; bounded sub-parts (a bulk pass, a wide search, a long audit loop) can go to cheaper tiers.`;
+    ? `8. **When the task changes files or executes a known plan**, builder executes by default after checking its tools and rules. Use the working model tier for well-specified work and a planning model for architecture. Keep conversation-dependent decisions and final verification with the main agent.`
+    : `8. **When the task changes files or executes a known plan**, use the main agent's working model tier. If another lane has the required tools and rules, give it a bounded section and a task brief.`;
 }
 export function whoBuildsSection(primary) {
-  if (subagentsLoadRules(primary)) {
-    return [
-      '## Who builds',
-      '',
-      `**Builder executes by default.** A Claude Code subagent loads this project's CLAUDE.md hierarchy at start (verified: code.claude.com/docs/en/sub-agents), so it already carries the standing rules; the orchestrator's job is to plan, brief, verify and talk to the human, not to hold work a delegate can do. Stay inline only when: (a) the brief would cost as much as the work itself, (b) the task needs this conversation's own context, or (c) it is the human's decision to make, or the final verification of delegated work (a delegate never verifies its own output as final). Never route rule-bound work to the built-in Explore or Plan agents: both skip CLAUDE.md and the git status the router depends on. general-purpose should not take work a named agent already owns.`,
-      '',
-      `Delegate: the main build, background and long-running tasks, small tasks, scoping, verification, research, bounded sub-parts. Never delegate: the human's own decision, or the final sign-off on a delegate's work.`,
-      '',
-      `Every delegation carries \`TASK_BUNDLE.md\`. Its brief must restate this task's scope: a Claude Code subagent already has the standing rules, just not that.`
-    ].join('\n');
-  }
   return [
     '## Who builds',
     '',
-    '**The orchestrator owns the main build.** It is the only surface that holds these rules: a subagent or a second CLI starts with none of them and cannot route. Handing the main build to one hands it to something the router cannot reach.',
+    subagentsLoadRules(primary)
+      ? '**Builder executes by default when its capabilities fit.** A Claude Code subagent loads the project CLAUDE.md hierarchy. Give it the context file, acceptance checks and whole scope in `TASK_BRIEF.md`. When the task depends on conversation context, keep that section with the main agent.'
+      : '**Assign each section by tools, context and rules.** The main agent already holds the session context. When another lane can carry the required context and permissions, give it the whole scope and its section in `TASK_BRIEF.md`; otherwise build that section in the main agent.',
     '',
-    'Delegate: background and long-running tasks, small tasks, scoping, verification, research, bounded sub-parts. Never delegate: the main build, or any step that must carry a house rule (secrets handling, the loud-negative verification, the durable record).',
+    'When a decision belongs to the human, return it to them. When a section finishes, the main agent combines it with the other sections and gives the final artifact to the independent reviewer.',
     '',
-    'Every delegation carries `TASK_BUNDLE.md`. Its brief must restate every convention the delegate needs.'
+    'When delegation costs as much as the bounded work itself, keep that work in the current session and record the reason.'
   ].join('\n');
 }
 export function addEndpointRow(primary) {
   return subagentsLoadRules(primary)
-    ? '| "Add an endpoint" | builder, briefed and verified by the orchestrator |'
-    : '| "Add an endpoint" | the orchestrator builds it |';
+    ? '| "Add an endpoint" | builder after Assign confirms its capabilities, with a task brief |'
+    : '| "Add an endpoint" | the main agent or another capable build lane chosen during Assign |';
 }
 export function inlineThresholdNote(primary) {
   return subagentsLoadRules(primary)
@@ -356,29 +429,24 @@ export function delegateRulesNote(primary) {
     : 'Subagents, a fresh chat, a second window: each one holds none of these rules.';
 }
 
-// Pre-release audit finding 3: the delegate-by-default gate reached the
-// decision tree and "Who builds" but missed three other generated surfaces
-// stating the same old premise (the orchestrator writes the main build
-// itself; a delegate inherits none of the session's rules). These three
-// close that gap the same way: gated on subagentsLoadRules(primary), every
-// other primary keeps the original wording unchanged.
+// Keep assignment guidance consistent across the routing and build protocols.
 export function planBigExecuteSmallLine(primary) {
   return subagentsLoadRules(primary)
-    ? `- **Plan big, execute small**, within a build: deep tier plans at Checkpoint 1, builder executes from the orchestrator's brief, bulk and wide searches go down.`
-    : '- **Plan big, execute small**, within a build: deep tier plans at Checkpoint 1, the orchestrator executes, bulk and wide searches go down.';
+    ? '- **Assign by job fit.** Use a planning model for architecture, assign scoped execution to builder, and use a cheap model for mechanical work.'
+    : '- **Assign by job fit.** Match reach, context window and headroom to each section. When delegation cannot carry its required rules, the main agent executes that section.';
 }
 export function rolesBuilderRow(primary) {
   return subagentsLoadRules(primary)
     ? [
-        '| Orchestrator | Routes, maps, briefs, verifies, records. Stages 0, 1, 2, 4, 5b, 6, 7 | Write the build |',
-        "| Builder | Executes Stage 3 from the orchestrator's brief | Route further, or verify its own work as final |"
+        '| Main agent | Frames, maps, assigns, combines sections, verifies, records | Keeps the whole scope and names merge conflicts |',
+        '| Builder | Executes the assigned section from the task brief | Hands verification to an independent reviewer |'
       ].join('\n')
-    : '| Builder / orchestrator | Routes, maps, writes, verifies, records. Stages 0, 1, 3, 6, 7 | Hand off the main build |';
+    : '| Main agent / assigned builder | Executes each section whose tools and rules it holds | Gives the reviewer the combined result and acceptance checks |';
 }
 export function builderHandoffNote(primary) {
   return subagentsLoadRules(primary)
-    ? `**Why Stage 3 goes to builder by default:** a Claude Code subagent loads this project's CLAUDE.md hierarchy at start, so it already carries the standing rules; the orchestrator's brief only has to restate this task's scope (see \`TASK_BUNDLE.md\`). The orchestrator keeps Stage 3 for itself only when the brief would cost as much as the work, the task needs this conversation's own context, or it is the human's decision or the final verification of delegated work.`
-    : `**Why the builder does not hand off the main build:** a delegated agent does not inherit the session's standing rules and usually cannot delegate further. Any brief must restate every convention it needs (see \`TASK_BUNDLE.md\`), and that cost is itself a reason to build directly when the work fits.`;
+    ? '**Assign the build:** when a Claude Code subagent has the needed tools and rules, send it the scoped task brief from `TASK_BRIEF.md`. Keep conversation-dependent decisions and the final verification with the main agent.'
+    : '**Assign the build:** when another lane can hold the required context, tools and rules, give it the whole scope and its section in `TASK_BRIEF.md`. When that transfer is impractical, build that section in the main agent.';
 }
 
 // Which activation file this primary gets. ONE decision, read by three
@@ -390,6 +458,29 @@ export function snippetFor(primary) {
   return primary.rulesFile ? primary.rulesFile.replace(/\.md$/, '.snippet.md') : 'PASTE-INTO-YOUR-AGENT.md';
 }
 
+// The one primary-instruction step: copy into a known rules file, paste into a
+// chat app's surface, or (Q3/Q5) load the block by hand for a CLI main agent
+// the catalog has no project rules file for (Grok, Hermes today). Read by the
+// terminal summary line, the activation list and the generated README's
+// "where things went" section, so the three surfaces cannot describe three
+// different things (#20).
+export function primaryActivationStep({ primary, dir, project }) {
+  const snippet = snippetFor(primary);
+  if (!primary || !snippet) return null;
+  const dirAbs = resolve(dir || 'ai-orchestrator');
+  const projectAbs = resolve(project || process.cwd());
+  if (primary.rulesFile) return `copy the block in ${join(dirAbs, snippet)} into ${join(projectAbs, primary.rulesFile)} (create it if missing)`;
+  // A chat app has no possessive that survives its catalog note: "Claude app or
+  // claude.ai (chat only, no CLI)'s custom instructions" was the sentence this
+  // replaces (#22).
+  if (primary.facts.kind === 'chat') return `open ${primary.chatName || primary.name} and paste the block in ${join(dirAbs, snippet)} into its ${primary.chatSurface || 'custom instructions'}`;
+  // A CLI with no cataloged project rules file: say plainly there is nothing
+  // to write automatically, and name the accurate fallback (Q3). No verified
+  // per-CLI loading convention is cataloged for Grok or Hermes, so this states
+  // the honest generic fallback rather than guessing a mechanism.
+  return `${primary.name} has no cataloged project rules file, so the installer has nothing to write for it; load the block in ${join(dirAbs, snippet)} at the start of a session with ${primary.name}`;
+}
+
 // The activation list, in order. The terminal prints this array at the end of a
 // run and the generated README renders the same array, so the page cannot
 // describe a different first step from the one the user just read (#20).
@@ -398,25 +489,33 @@ export function activationSteps(opts) {
   const tools = opts.tools || [];
   const dirAbs = resolve(opts.dir || 'ai-orchestrator');
   const projectAbs = resolve(opts.project || process.cwd());
-  const snippet = snippetFor(primary);
   const steps = [];
-  if (opts.applySnippets) steps.push(`applied ${join(dirAbs, snippet)} to the model-orchestrator marked block in ${join(projectAbs, 'CLAUDE.md')}`);
-  else if (snippet && primary.rulesFile) steps.push(`copy the block in ${join(dirAbs, snippet)} into ${join(projectAbs, primary.rulesFile)} (create it if missing)`);
-  // A chat app has no possessive that survives its catalog note: "Claude app or
-  // claude.ai (chat only, no CLI)'s custom instructions" was the sentence this
-  // replaces (#22).
-  else if (snippet) steps.push(`open ${primary.chatName || primary.name} and paste the block in ${join(dirAbs, snippet)} into its ${primary.chatSurface || 'custom instructions'}`);
-  if (primary && primary.agentsDir) steps.push(`subagents are in ${join(projectAbs, primary.agentsDir)}; run ${primary.bin} from ${projectAbs} to pick them up`);
+  // Automatic application only ever covers a primary with a rulesFile; every
+  // other case (no rulesFile, or applySnippets off) keeps the manual step.
+  if (primary && !(primary.rulesFile && opts.applySnippets)) {
+    const step = primaryActivationStep({ primary, dir: opts.dir, project: opts.project });
+    if (step) steps.push(step);
+  }
   // Only claude-code ships hooks (route-gate, subagent-context): the wiring
   // lives in a snippet, applied only when the user opts in.
-  if (opts.applySnippets) steps.push(`applied hooks to ${join(projectAbs, '.claude', 'settings.json')}, preserving existing settings and hooks`);
-  else if (subagentsLoadRules(primary)) steps.push(`merge the hooks in ${join(dirAbs, 'settings.hooks.snippet.json')} into ${join(projectAbs, '.claude', 'settings.json')} (create it if missing) to wire the route-gate, subagent-context and route-metrics hooks`);
-  for (const a of selected.filter((a) => a.bin && a.kind === 'agent-cli')) steps.push(`sign in to ${a.name}: ${a.auth}`);
+  if (!opts.applySnippets && subagentsLoadRules(primary)) steps.push(`merge the hooks in ${join(dirAbs, 'settings.hooks.snippet.json')} into ${join(projectAbs, '.claude', 'settings.json')} (create it if missing) to wire the route-gate, subagent-context and route-metrics hooks`);
+  for (const a of selected.filter((a) => a.bin && a.facts.kind === 'agent-cli')) {
+    if (opts.authStatuses?.[a.id] === true) continue;
+    steps.push(opts.authStatuses?.[a.id] === false
+      ? `sign in to ${a.name}: ${a.auth}`
+      : `${a.name}, if you have not signed in yet: ${a.auth}`);
+  }
   // A local runtime has a bin but no sign-in, so the agent-cli loop above skips it
   // and before this it appeared in no ordered list at any level (#26).
-  for (const a of selected.filter((a) => a.bin && a.kind === 'local')) steps.push(`install ${a.name}: ${a.install.url}, then \`${a.bin} pull <model>\` before the local lane can answer`);
-  for (const t of tools) steps.push(`${t.id}: ${t.install}`);
-  if (level >= 2) steps.push(`smoke test: node ${join(dirAbs, 'bin', 'cli-run.mjs')} --doctor   (add --run to send each lane one tiny prompt)`);
+  for (const a of selected.filter((a) => a.bin && a.facts.kind === 'local-runtime')) {
+    // Q2/Q6: only print the install step when the runtime is not already on
+    // PATH, and name the configured model instead of a placeholder.
+    if (level < 3 && opts.detected?.has(a.id)) continue;
+    steps.push(level >= 3
+      ? `${a.name}: follow vm/README.md, then run \`bash setup-vm.sh --start-services\` in vm/ to pull the configured model into its Compose service and verify local-small`
+      : `install ${a.name}: ${a.install.url}, then \`${a.bin} pull ${a.gatewayModel.replace(/^ollama\//, '')}\` before the local lane can answer`);
+  }
+  steps.push(...companionRegistrationSteps({ ...opts, tools, dir: dirAbs, project: projectAbs }));
   if (level >= 3) steps.push(`box: read ${join(dirAbs, 'vm', 'README.md')}; keys named in vm/ENVIRONMENT.md go in your secrets manager, never a file`);
   return steps;
 }
@@ -425,15 +524,19 @@ export function activationSteps(opts) {
 // activationSteps is: level 1 writes no bin/, so a step naming cli-run.mjs or
 // lanes.json there described an install that did not happen (#27).
 export function proofSteps(opts) {
-  const { level, primary } = opts;
+  const { level, primary, selected = primary ? [primary] : [] } = opts;
   const steps = [
     'Start a fresh agent session and ask: "Read the orchestrator instructions. Quote the routing rule you will use, then sort pear, apple, banana alphabetically. Name the tier and whether you delegated."',
-    'Expect the fast tier and `apple, banana, pear`. If the agent cannot quote the routing rule, check the snippet location or chat instructions before continuing. This is a manual activation check, not proof that every future task follows the rules.'
+    'Expect the cheap model tier and `apple, banana, pear`. If the agent cannot quote the routing rule, check the snippet location or chat instructions before continuing. This is a manual activation check, not proof that every future task follows the rules.'
   ];
   if (level >= 2) {
-    steps.push('Run `node bin/cli-run.mjs --doctor` from this folder. It checks binary presence, not authentication or loaded instructions, and prints the model and effort each lane is pinned to. `--doctor --run` additionally uses a little quota to test live responses. No enabled lanes means delegation is inactive.');
+    steps.push('Run `node bin/cli-run.mjs --doctor` from this folder, or `aunx cli-run --doctor` from your project root. It checks binary presence, not authentication or loaded instructions, and prints the model and effort each lane is pinned to. `--doctor --run` additionally uses a little quota to test live responses. No enabled lanes means delegation is inactive.');
     steps.push('Decide whether the route matters to you. Every lane starts unpinned, which means it runs on whatever its own config file says: a CLI configured months ago at a low reasoning effort will keep auditing at that effort while your docs describe something stronger. Pin it in `bin/lanes.json` under `defaults`, or per call with `--model` and `--effort`. Either way the run is recorded in the log with the value requested and where it came from.');
-    steps.push('To test a real output contract, choose an enabled lane from `bin/lanes.json` and run `node bin/cli-run.mjs <lane> \'Return only {"sorted":["apple","banana","pear"]}\' --expect-json`. This uses quota. Expect JSON and exit 0; inspect the array yourself. A non-JSON response exits 10, a missing binary exits 13, and an authentication failure reports the vendor error. The explicit lane tests execution; your primary agent still makes delegation decisions.');
+    if (selected.some(a => a.facts.cliRun)) {
+      steps.push('To test a real output contract, choose an enabled lane from `bin/lanes.json` and run `node bin/cli-run.mjs <lane> \'Return only {"sorted":["apple","banana","pear"]}\' --expect-json`. The same command is available as `aunx cli-run <lane>` with those arguments. This uses quota. Expect JSON and exit 0; inspect the array yourself. A non-JSON response exits 10, a missing binary exits 13, and an authentication failure reports the vendor error. The explicit lane tests execution; your main agent still makes delegation decisions.');
+    } else {
+      steps.push('Delegation is inactive: no supported CLI lane is selected, so `--doctor` will exit 13. Defer the output-contract test until you select a supported CLI lane: re-run the installer with that lane in `--ais` and `--update-docs`, then install it and sign in using the printed instructions.');
+    }
   }
   // Only claude-code ships the route-gate hook, so only claude-code gets a
   // proof step that checks it fired: the table must come from the hook's
@@ -450,7 +553,15 @@ function vars(opts) {
   const tools = opts.tools || [];
   const apis = opts.apis || [];
   const lvl = LEVELS.find((l) => l.id === level);
-  const lane = auditLane(selected);
+  const lane = auditLane(selected, primary);
+  const assignment = assignRoles({ selected, primary, detected: opts.detected, plans });
+  const stack = stackContext(selected, primary, opts.detected);
+  const enabled = selected.filter(a => a.facts.cliRun);
+  const exampleLane = enabled[0]?.id || '<lane>';
+  const exampleDefaults = { model: '<model-id>', ...(LANE_FLAGS[exampleLane]?.effort ? { effort: 'high' } : {}) };
+  const auditExample = enabled.find(a => a.facts.readOnlyMode);
+  const fallbackNote = 'When no separate lane qualifies, your main agent carries the job at its stated tier. Independent review and local-only work require an eligible lane.';
+  const gaps = assignment.unassigned.map(id => `${id}: ${assignment.roles[id].why}`).join(' ');
   const codecalc = tools.some((t) => t.id === 'codecalc');
   const dirAbs = resolve(opts.dir || 'ai-orchestrator');
   const projectAbs = resolve(opts.project || process.cwd());
@@ -483,46 +594,66 @@ function vars(opts) {
     : '';
   const pinOf = (id) => (toolById[id] && toolById[id].pin) || 'latest';
   const snippet = snippetFor(primary);
-  const steps = activationSteps({ level, selected, primary, tools, dir: opts.dir, project: opts.project, applySnippets: opts.applySnippets });
-  const proofs = proofSteps({ level, primary });
+  const steps = activationSteps({ level, selected, primary, tools, dir: opts.dir, project: opts.project, applySnippets: opts.applySnippets, authStatuses: opts.authStatuses, registrations: opts.registrations, detected: opts.detected });
+  const proofs = proofSteps({ level, primary, selected });
   const routingFile = level >= 2 ? 'ROUTING.md' : 'ORCHESTRATOR.md';
   // The path route-gate.mjs and subagent-context.mjs resolve at runtime,
   // relative to CLAUDE_PROJECT_DIR. Mirrors the RULES_PATH fallback below:
   // outside the project, the honest path is absolute, never a hardcoded one.
   const relJoin = (name) => (rulesPath === dirPosix ? posix.join(dirPosix, name) : rulesPath === '.' ? name : rulesPath + '/' + name);
   const rulesFileRel = relJoin(routingFile);
-  const taskBundleRel = relJoin('TASK_BUNDLE.md');
+  const taskBriefRel = relJoin('TASK_BRIEF.md');
   // Only claude-code and agy put files under the project root. A chat primary
   // puts nothing there, so naming a project root would name a folder this run
   // never created (#21).
-  const writesProject = !!(primary && primary.agentsDir);
+  const writesProject = !!(primary && primary.facts.agentDefinitions);
   const readsProjectRules = !!(primary && primary.rulesFile);
   const whereThingsWent = [`- This folder: \`${dirAbs}\``];
-  if (writesProject) whereThingsWent.push(`- Project root (where your agent reads rules and subagents): \`${projectAbs}\``, `- Subagent definitions: \`${join(projectAbs, primary.agentsDir)}\``);
-  else if (readsProjectRules) whereThingsWent.push(`- Project root (where ${primary.name} reads \`${primary.rulesFile}\`): \`${projectAbs}\`` + (existsSync(projectAbs) ? '' : ' (this run wrote nothing there; create the folder before you copy the snippet in)'), '- Subagent definitions: none, this agent has no subagent folder');
+  if (writesProject) whereThingsWent.push(`- Project root (where your agent reads rules and subagents): \`${projectAbs}\``, `- Subagent definitions: \`${join(projectAbs, primary.facts.agentDefinitions)}\``);
+  else if (readsProjectRules) whereThingsWent.push(`- Project root (where ${primary.name} reads \`${primary.rulesFile}\`): \`${projectAbs}\`` + (opts.applySnippets || existsSync(projectAbs) ? '' : ' (this run wrote nothing there; create the folder before you copy the snippet in)'), '- Subagent definitions: none, this agent has no subagent folder');
+  // Q5: a CLI with no cataloged project rules file (Grok, Hermes) is not a
+  // chat app, so it gets its own accurate sentence instead of borrowing theirs.
+  else if (primary && primary.facts.kind !== 'chat') whereThingsWent.push(`- Project root: none. ${primary.name} has no cataloged project rules file, so this install wrote nothing to a project folder; load the block by hand each session.`, '- Subagent definitions: none');
   else whereThingsWent.push('- Project root: none. A chat app reads pasted instructions, not files, so this install wrote nothing to a project folder.', '- Subagent definitions: none');
   whereThingsWent.push(`- The rules path your snippets use: \`${rulesPath}\``);
   whereThingsWent.push(rulesPathNote
     ? '- Rules location: absolute, because this folder is outside the project. ' + rulesPathNote
     : '- Rules location: project-relative, so moving the project and its rules folder together preserves the paths.');
   return {
-    ...laneVars(selected),
-    ACTIVATION_STEPS: steps.map((st, i) => `${i + 1}. ${st}`).join('\n'),
+    ...laneVars(selected, primary),
+    STACK_TABLE: roleTable(assignment, stack),
+    STACK_FALLBACK_NOTE: fallbackNote,
+    STACK_GAPS: gaps,
+    // The "Full assignments" pointer is its own paragraph, not a clause
+    // glued onto the end of the gaps sentence (C5): when gaps is non-empty
+    // it already ends its own sentence ("...off every lane here."), and
+    // running the pointer straight on read as a continuation of it.
+    STACK_SUMMARY: ['## Your stack: who does what', fallbackNote, gaps].filter(Boolean).join('\n')
+      + '\n\nFull assignments: [README.md](README.md#your-stack-who-does-what).',
+    EXAMPLE_LANE: exampleLane,
+    EXAMPLE_EFFORT_FLAGS: LANE_FLAGS[exampleLane]?.effort ? ' --effort high' : '',
+    EXAMPLE_AUDIT_LANE: auditExample?.id || '',
+    EXAMPLE_AUDIT_BLOCK: auditExample ? `When reviewing with an available read-only mode, select its audit shape:\n\n\x60\x60\x60bash\naunx cli-run ${auditExample.id} --audit --brief REVIEW.md\nnode bin/cli-run.mjs ${auditExample.id} --audit --brief REVIEW.md\n\x60\x60\x60` : 'When reviewing, verify the chosen lane permissions and request review-only work.',
+    EXAMPLE_LANES_JSON: JSON.stringify({ enabled: enabled.map(a => a.id), defaults: { [exampleLane]: exampleDefaults } }, null, 2),
+    // Renders only when Qwen is actually selected: the sentence names a flag
+    // that is a usage error on every other lane (C1).
+    QWEN_SAFE_MODE_NOTE: selected.some(a => a.id === 'qwen') ? "When Qwen's safe mode is required, pass `--safe-mode` to that lane. " : '',
+    ACTIVATION_STEPS: steps.length ? steps.map((st, i) => `${i + 1}. ${st}`).join('\n') : 'Nothing left to do.',
     PROOF_STEPS: proofs.map((st, i) => `${i + 1}. ${st}`).join('\n'),
-    LOAD_IT: opts.applySnippets
-      ? 'The installer applied the generated rules to the model-orchestrator marked block in `CLAUDE.md` and merged the hooks into `.claude/settings.json`. Existing files changed by this run have timestamped backups beside them; their paths were printed in the terminal.'
+    LOAD_IT: opts.applySnippets && readsProjectRules
+      ? `The installer applied the generated rules to the model-orchestrator marked block in \`${primary.rulesFile}\`${subagentsLoadRules(primary) ? ' and merged the hooks into `.claude/settings.json`' : ''}. Existing files changed by this run have timestamped backups beside them; their paths were printed in the terminal.`
       : readsProjectRules
-      ? `${primary.name} reads its rules from \`${primary.rulesFile}\` in the project root. The installer wrote \`${snippet}\` next to this README; copy its contents into \`${join(projectAbs, primary.rulesFile)}\`, creating that file if it does not exist. Nothing was appended to a file you already had.`
+      ? `${primary.name} reads its rules from \`${primary.rulesFile}\` in the project root. The installer wrote \`${snippet}\` next to this README; copy its contents into \`${join(projectAbs, primary.rulesFile)}\`, creating that file if it does not exist. Nothing was appended to a file you already had.${subagentsLoadRules(primary) ? ` Also merge \`settings.hooks.snippet.json\`, written next to this README, into \`.claude/settings.json\` (create it if missing) to wire the route-gate, subagent-context and route-metrics hooks.` : ''}`
       : snippet
-        ? `${primary.name} has no project rules file, so the rules travel by paste. The installer wrote \`${snippet}\` next to this README; open ${primary.chatName || primary.name} and paste its contents into ${primary.chatSurface || 'custom instructions'}. Nothing was appended to a file you already had.`
-        : 'No primary agent was selected, so no activation file was written. Re-run the installer and pick one.',
+        ? `${primary.name} has no cataloged project rules file. Follow the load step under "What's left for you" using \`${snippet}\` next to this README.`
+        : 'No main agent was selected, so no activation file was written. Re-run the installer and pick one.',
     CLAUDE_SNIPPET_INTRO: opts.applySnippets
       ? '# Model orchestrator activation\n\nThe installer applied these rules to the marked block in `CLAUDE.md` at your project root.'
       : "# Add this to your project's CLAUDE.md\n\nCopy the block below into `CLAUDE.md` at your project root (create the file if it does not exist). The installer did not modify any file you already had.",
     CLAUDE_HOOKS_ACTIVATION: opts.applySnippets
       ? 'The installer merged the hook entries into `.claude/settings.json` to wire all three in.'
       : 'Merge `settings.hooks.snippet.json`, written next to this file, into `.claude/settings.json` to wire all three in.',
-    CHAT_UPLOAD_NOTE: primary && primary.kind === 'chat' ? ' A chat app cannot open a local path: upload or paste any protocol file you want it to read.' : '',
+    CHAT_UPLOAD_NOTE: primary && primary.facts.kind === 'chat' ? ' A chat app cannot open a local path: upload or paste any protocol file you want it to read.' : '',
     WHERE_THINGS_WENT: whereThingsWent.join('\n'),
     RULES_PATH: rulesPath,
     RULES_PATH_NOTE: rulesPathNote,
@@ -530,7 +661,7 @@ function vars(opts) {
     RULES_DIR_OVERRIDE_JS: 'process.env.MODEL_ORCHESTRATOR_RULES_DIR',
     ROUTING_FILE: level >= 2 ? 'ROUTING.md' : 'ORCHESTRATOR.md',
     PROJECT_DIR: projectAbs,
-    AGENTS_DIR: primary && primary.agentsDir ? join(projectAbs, primary.agentsDir) : 'none (your primary agent has no subagent folder)',
+    AGENTS_DIR: primary && primary.facts.agentDefinitions ? join(projectAbs, primary.facts.agentDefinitions) : 'none (your main agent has no subagent folder)',
     LITELLM_IMAGE: IMAGES.litellm,
     OLLAMA_IMAGE: IMAGES.ollama,
     CODECALC_PIN: pinOf('codecalc'),
@@ -542,16 +673,21 @@ function vars(opts) {
     INSTALL_DIR_SYSTEMD: systemdEscape(dirPosix),
     // vm/README.md step 3 named `grok login` and `agy` whatever you picked (#26).
     VM_SIGNIN: (() => {
-      const lines = selected.filter((a) => a.bin && a.kind === 'agent-cli').map((a) => `   - ${a.name}: ${a.auth}`);
-      for (const a of selected.filter((a) => a.bin && a.kind === 'local')) lines.push(`   - ${a.name}: no sign-in. Install it from ${a.install.url}, then \`${a.bin} pull <model>\`.`);
+      const lines = selected.filter((a) => a.bin && a.facts.kind === 'agent-cli').map((a) => `   - ${a.name}: ${a.auth}`);
+      for (const a of selected.filter((a) => a.bin && a.facts.kind === 'local-runtime')) lines.push(`   - ${a.name}: no sign-in. Step 5 initializes the model in its Compose service.`);
       return lines.length ? lines.join('\n') : '   - none: no CLI you selected needs a sign-in on the box.';
     })(),
+    VM_LOCAL_MODEL_SH: shellQuote(selected.some((a) => a.id === 'ollama') ? byId.ollama.gatewayModel.replace(/^ollama\//, '') : ''),
+    VM_SCRIPT_INSTALLERS: scriptInstallers(selected.filter((a) => a.facts.kind !== 'local-runtime')),
+    VM_LOCAL_SETUP: selected.some((a) => a.id === 'ollama')
+      ? `The command waits for Ollama, pulls \`${byId.ollama.gatewayModel.replace(/^ollama\//, '')}\` inside its Compose service, then requires a nonempty chat completion through the gateway alias \`local-small\`. The container uses its own volume; a host Ollama installation is separate. This check sends one short prompt to the local model.`
+      : 'No local runtime was selected. The command starts the configured services; verify any configured provider lanes separately.',
     AUDIT_LANE: lane || 'none',
     // Enforced boundary per lane: codex has a read-only sandbox flag; the others
     // run with whatever their own config allows, and the script says so.
-    AUDIT_LANE_FLAGS: lane === 'codex' ? '--audit' : '',
-    AUDIT_LANE_BOUNDARY_NOTE: lane === 'codex'
-      ? 'codex --audit, a read-only filesystem sandbox; commands and network follow the codex config'
+    AUDIT_LANE_FLAGS: selected.find(a => a.id === lane)?.facts.readOnlyMode ? '--audit' : '',
+    AUDIT_LANE_BOUNDARY_NOTE: selected.find(a => a.id === lane)?.facts.readOnlyMode
+      ? `${lane} --audit, a read-only filesystem sandbox; commands and network follow the ${lane} config`
       : lane
         ? `${lane} offers no sandbox flag cli-run can pass, so the denied-actions list is instruction-level only and enforcement is whatever ${lane}'s own permission config allows`
         : 'no lane selected',
@@ -559,9 +695,9 @@ function vars(opts) {
       ? ''
       : 'echo "weekly-audit: no cli-run lane was enabled at install time; enable one in bin/lanes.json and edit AUDIT_LANE" >&2; exit 13',
     TOOLS_LIST: tools.length ? tools.map((t) => '- ' + t.name + ': ' + t.role).join('\n') : '- none selected (re-run the installer with --tools codecalc to add the calculator and code runner)',
-    CODECALC_STATUS: codecalc ? 'installed alongside this folder (see `CODECALC.md`)' : 'not selected; the rule below still binds, do the arithmetic with any tool that computes rather than guesses',
-    OBSIDIAN_TC_STATUS: tools.some((t) => t.id === 'obsidian-tc') ? 'selected (see `OBSIDIAN-TC.md`); the tool names below are live calls' : 'not selected; the rule below still binds against whatever store you keep (a notes folder, a wiki, a repo of markdown), the tool names are what obsidian-tc would give you',
-    CONTEXT7_STATUS: tools.some((t) => t.id === 'context7') ? 'selected (see `CONTEXT7.md`); the tool names below are live calls' : 'not selected; the rule below still binds, read the vendor docs or source by hand before trusting them',
+    CODECALC_STATUS: codecalc ? 'setup instructions selected (see `CODECALC.md`); verify your own installation before calling it' : 'use a calculator or the project runtime to compute and verify arithmetic',
+    OBSIDIAN_TC_STATUS: tools.some((t) => t.id === 'obsidian-tc') ? 'setup instructions selected (see `OBSIDIAN-TC.md`); verify server access before calling these tools' : 'not selected; the rule below still binds against whatever store you keep (a notes folder, a wiki, a repo of markdown), the tool names are what obsidian-tc would give you',
+    CONTEXT7_STATUS: tools.some((t) => t.id === 'context7') ? 'setup instructions selected (see `CONTEXT7.md`); verify server access before calling these tools' : 'not selected; the rule below still binds, read the vendor docs or source by hand before trusting them',
     DATE: new Date().toISOString().slice(0, 10),
     LEVEL_ID: String(level),
     LEVEL_NAME: lvl.name,
@@ -569,15 +705,15 @@ function vars(opts) {
     PRIMARY_ID: primary ? primary.id : 'none',
     PRIMARY_NAME: primary ? primary.name : 'your agent',
     PRIMARY_RULES_FILE: primary && primary.rulesFile ? primary.rulesFile : 'your agent\'s instructions file',
-    PRIMARY_DEEP: primary && primary.models ? primary.models.deep : 'your strongest model',
-    PRIMARY_STANDARD: primary && primary.models ? primary.models.standard : 'your everyday model',
-    PRIMARY_FAST: primary && primary.models ? primary.models.fast : 'your cheapest model',
-    AIS_LIST: selected.map((a) => '- ' + a.name + ': ' + a.role).join('\n'),
+    PRIMARY_DEEP: 'the planning model available in your configuration',
+    PRIMARY_STANDARD: 'the working model available in your configuration',
+    PRIMARY_FAST: 'the cheap model available in your configuration',
+    AIS_LIST: selected.map((a) => '- ' + a.name + ': ' + summaryWithEvidence(a)).join('\n'),
     AI_IDS: selected.map((a) => a.id).join(','),
-    LANES_TABLE: lanesTable(selected, plans),
+    LANES_TABLE: lanesTable(selected, plans, primary),
     PLAN_GUIDANCE: planGuidance(selected, plans),
     INSTALL_TABLE: installTable(selected),
-    CLI_RUN_LANES: selected.filter((a) => a.cliRun).map((a) => a.id).join(', ') || 'none selected',
+    CLI_RUN_LANES: selected.filter((a) => a.facts.cliRun).map((a) => a.id).join(', ') || 'none selected',
     GATEWAY_MODELS: gatewayModels(selected, apis),
     ENV_NAMES: envNames(selected, apis).map((n) => '- `' + n + '`').join('\n'),
     ENV_EXPORTS: envNames(selected, apis).map((n) => n + '=').join('\n'),
@@ -585,9 +721,8 @@ function vars(opts) {
     SCRIPT_INSTALLERS: scriptInstallers(selected),
     COMPOSE_ENV: composeEnv(selected, apis),
     COMPOSE_OLLAMA: composeOllama(selected),
-    // Delegate by default (0.1.15): gated on subagentsLoadRules(primary), currently
-    // claude-code only. Every other primary keeps the original, more
-    // conservative wording these replace.
+    // Delegate-by-default wording uses the verified subagent loading surface.
+    // Every other agent confirms tool and rule reach during Assign.
     DECISION_RULE5: decisionRule5(primary),
     DECISION_RULE5_L1: decisionRule5Beginner(primary),
     WHO_BUILDS: whoBuildsSection(primary),
@@ -597,11 +732,11 @@ function vars(opts) {
     PLAN_BIG_LINE: planBigExecuteSmallLine(primary),
     ROLES_BUILDER_ROW: rolesBuilderRow(primary),
     BUILDER_HANDOFF_NOTE: builderHandoffNote(primary),
-    ROUTE_GATE_SECTION: subagentsLoadRules(primary) ? '\n' + routeGateSection(selected) + '\n' : '',
+    ROUTE_GATE_SECTION: subagentsLoadRules(primary) ? '\n' + routeGateSection(selected, primary) + '\n' : '',
     AGENTS_LIST_LINE: claudeAgentIds().map((id) => '`' + id + '`').join(', '),
     RULES_FILE_REL: rulesFileRel,
     RULES_FILE_REL_JSON: JSON.stringify(rulesFileRel),
-    TASK_BUNDLE_REL_JSON: JSON.stringify(taskBundleRel),
+    TASK_BRIEF_REL_JSON: JSON.stringify(taskBriefRel),
     // route-gate.mjs takes a candidate list so the plugin bundle (src/plugin.js)
     // can render the installer's default locations from the same template. An
     // install knows its one rules file, and wrote it, so it needs no hint.
@@ -620,6 +755,18 @@ export function planFiles(opts) {
   const files = [];
   // root: 'dir' (the docs folder) or 'project' (where the agent actually looks for subagents)
   const add = (rel, content, mode, root = 'dir') => files.push({ rel, content, mode: mode || 0o644, root });
+  const renderAgent = (raw) => {
+    let content = render(raw, v);
+    const tier = raw.match(/^Tier: ((?:planning|working|cheap) model)\./m)?.[1];
+    const model = opts.plans?.[primary?.id]?.tierModels?.[tier];
+    // Mappings belong to a dated, verified plan entry. Every shipped mapping
+    // is null; an unstated plan leaves vendor resolution entirely intact.
+    if (model != null) {
+      if (typeof model !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_.:/-]*$/.test(model)) throw new Error('invalid tierModels model identifier');
+      content = content.replace(/^---\n/, `---\nmodel: ${model}\n`);
+    }
+    return content;
+  };
   const addTemplates = (sub) => {
     for (const f of walk(join(TEMPLATES, sub))) {
       if (!installable(sub, f.rel)) continue;
@@ -631,11 +778,11 @@ export function planFiles(opts) {
   addTemplates('common');
   addTemplates('beginner');
 
-  // The primary agent's own loading surface.
+  // The main agent's own loading surface.
   if (primary && primary.id === 'claude-code') {
     for (const f of walk(join(TEMPLATES, 'agents', 'claude-code'))) {
       if (!installable('agents', f.rel)) continue;
-      add(join('.claude', 'agents', f.rel), render(readFileSync(f.abs, 'utf8'), v), 0o644, 'project');
+      add(join('.claude', 'agents', f.rel), renderAgent(readFileSync(f.abs, 'utf8')), 0o644, 'project');
     }
     add('CLAUDE.snippet.md', render(readFileSync(join(TEMPLATES, 'agents', 'snippets', 'claude-code.md'), 'utf8'), v));
     // Delegate-by-default hooks (0.1.15), claude-code only: route-gate.mjs (UserPromptSubmit)
@@ -652,7 +799,7 @@ export function planFiles(opts) {
   } else if (primary && primary.id === 'agy') {
     for (const f of walk(join(TEMPLATES, 'agents', 'agy'))) {
       if (!installable('agents', f.rel)) continue;
-      add(join('.agents', 'agents', f.rel), render(readFileSync(f.abs, 'utf8'), v), 0o644, 'project');
+      add(join('.agents', 'agents', f.rel), renderAgent(readFileSync(f.abs, 'utf8')), 0o644, 'project');
     }
     add('GEMINI.snippet.md', render(readFileSync(join(TEMPLATES, 'agents', 'snippets', 'generic.md'), 'utf8'), v));
   } else if (primary && primary.rulesFile) {
@@ -672,10 +819,10 @@ export function planFiles(opts) {
       join('bin', 'lanes.json'),
       JSON.stringify(
         {
-          enabled: selected.filter((a) => a.cliRun).map((a) => a.id),
+          enabled: selected.filter((a) => a.facts.cliRun).map((a) => a.id),
           defaults: Object.fromEntries((opts.effortAuto || []).map((lane) => [lane, { effort: 'auto' }])),
           note: 'Lanes cli-run may call. Edit to enable or disable a lane. A lane not listed here exits 13 (unavailable).',
-          defaultsNote: 'Pin what a lane runs with, so the route in your docs is the route that runs: "defaults": {"codex": {"model": "gpt-6-astra", "effort": "high"}}. Left empty, a lane inherits its own config file, which cli-run cannot see and does not guess. `--model` and `--effort` override this per call, and `--doctor` prints what each lane is pinned to. Every lane takes a model; every lane except qwen takes an effort.'
+          defaultsNote: 'Pin what a lane runs with, so the route in your docs is the route that runs: "defaults": {"' + (selected.find(a => a.facts.cliRun)?.id || '<lane>') + '": ' + JSON.stringify({ model: '<model-id>', ...(LANE_FLAGS[selected.find(a => a.facts.cliRun)?.id]?.effort ? { effort: 'high' } : {}) }) + '}. Left empty, a lane inherits its own config file, which cli-run cannot see and does not guess. `--model` and `--effort` override this per call, and `--doctor` prints what each lane is pinned to. Every enabled lane takes a model; the runner reports which lanes support an effort flag.'
         },
         null,
         2
@@ -706,6 +853,8 @@ export function planFiles(opts) {
           level,
           ais: selected.map((a) => a.id),
           primary: primary ? primary.id : null,
+          detected: selected.filter(a => opts.detected?.has(a.id)).map(a => a.id),
+          roles: manifestRoles(assignRoles({ selected, primary, detected: opts.detected, plans: opts.plans }), stackContext(selected, primary, opts.detected)),
           tools: (opts.tools || []).map((t) => t.id),
           apis: (opts.apis || []).map((p) => p.id),
           ...(Object.keys(opts.plans || {}).length ? { plans: Object.fromEntries(Object.entries(opts.plans).sort(([a], [b]) => a.localeCompare(b)).map(([id, p]) => [id, p.id])) } : {}),
@@ -750,6 +899,28 @@ export function realRoot(dir) {
   return { root: missing.length ? join(real, ...missing) : real, exists: missing.length === 0 };
 }
 
+// Project activation must never become a machine-wide agent configuration.
+// Resolve the user's home as well as the requested root to cover system aliases.
+export function globalConfigProblem(path) {
+  const home = realRoot(homedir()).root;
+  const globalFolders = new Set(['.claude', '.codex', '.grok', '.qwen', '.gemini', '.agents', '.antigravity', '.hermes']);
+  for (const ai of AIS) {
+    if (ai.facts?.agentDefinitions) globalFolders.add(ai.facts.agentDefinitions.split('/')[0]);
+  }
+  const rules = new Set(AIS.map((ai) => ai.rulesFile).filter(Boolean));
+  rules.add('.mcp.json');
+  const relativePath = relative(home, path);
+  const globalFolder = [...globalFolders].some((folder) => {
+    const target = realRoot(join(home, folder)).root;
+    const rel = relative(target, path);
+    return rel === '' || rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel);
+  });
+  if (rules.has(relativePath) || globalFolder) {
+    return `${path}: global agent configuration is outside the installer scope; choose a project folder below your home directory`;
+  }
+  return null;
+}
+
 export function preflight(files, dir) {
   const problems = dirProblems(dir);
   if (problems.length) return problems;
@@ -761,6 +932,11 @@ export function preflight(files, dir) {
       problems.push(`${f.rel}: resolves outside the target directory`);
       continue;
     }
+    const globalProblem = globalConfigProblem(abs);
+    if (globalProblem) {
+      problems.push(globalProblem);
+      continue;
+    }
     const parts = relative(root, abs).split(sep);
     let cur = root;
     for (let i = 0; i < parts.length; i++) {
@@ -838,6 +1014,24 @@ export function readManifest(dir) {
   }
 }
 
+// Path-safety-only preflight: global agent config, path escape, a non-directory
+// target. Read-only, no side effects, and independent of any previous
+// manifest. writeFiles() below runs the same check again before it writes
+// anything; bin/cli.js calls this copy earlier, so a doomed install (global
+// config, path escape) never reaches a step that can run a real vendor status
+// command as a side effect (Q1 safety: signInStatus can execute
+// `claude auth status` etc. before writeFiles is ever called).
+export function writePreflightProblems(files, { dir, project }) {
+  const roots = { dir, project: project || dir };
+  const groups = { dir: files.filter((f) => (f.root || 'dir') === 'dir'), project: files.filter((f) => f.root === 'project') };
+  const problems = [];
+  for (const k of ['dir', 'project']) {
+    if (!groups[k].length) continue;
+    problems.push(...preflight(groups[k], roots[k]).map((p) => (k === 'project' ? `[project] ${p}` : p)));
+  }
+  return problems;
+}
+
 // Files carry a root: 'dir' for the docs folder, 'project' for the agent
 // definitions the user's CLI reads from the project root. Each root gets its
 // own preflight; one failure anywhere rolls back everything this run touched.
@@ -856,12 +1050,52 @@ export function writeFiles(files, opts) {
   const belongsHere = (key) => typeof key === 'string' && sameRoots[key.startsWith('[project] ') ? 'project' : 'dir'];
   // A hash or directory from another project cannot establish ownership here.
   const prevHashes = previous?.files ? Object.fromEntries(Object.entries(previous.files).filter(([key]) => belongsHere(key))) : null;
+  if (sameRoots.project && previous?.activation !== undefined) {
+    if (!previous.activation || typeof previous.activation !== 'object' || Array.isArray(previous.activation)) {
+      throw Object.assign(new Error('invalid activation ownership in previous manifest'), { code: 'PREFLIGHT' });
+    }
+    for (const [key, ownership] of Object.entries(previous.activation)) {
+      const problem = validateActivationOwnership(key, ownership);
+      if (problem) throw Object.assign(new Error(problem), { code: 'PREFLIGHT' });
+    }
+  }
+  const activation = previous?.activation && typeof previous.activation === 'object' && !Array.isArray(previous.activation)
+    ? Object.fromEntries(Object.entries(previous.activation).filter(([key]) => belongsHere(key))) : {};
+  for (const file of files.filter((item) => item.activation)) {
+    const key = '[project] ' + toPosixRel(file.rel);
+    const prior = activation[key];
+    const next = { ...file.activation, created: file.original === null };
+    if (prior?.kind === next.kind) {
+      next.created = prior.created;
+      if (next.kind === 'rules') {
+        next.addedPrefix = prior.addedPrefix;
+        next.addedSuffix = prior.addedSuffix;
+      } else if (next.kind === 'hooks') {
+        next.hadHooks = prior.hadHooks;
+        next.originalEvents = prior.originalEvents;
+        next.hooks = [...new Map([...(prior.hooks || []), ...next.hooks].map((hook) => [JSON.stringify(hook), hook])).values()];
+      } else if (next.kind === 'mcp') {
+        next.servers = { ...prior.servers, ...next.servers };
+        next.hadKey = prior.hadKey;
+      }
+    }
+    activation[key] = next;
+  }
   const groups = { dir: files.filter((f) => (f.root || 'dir') === 'dir'), project: files.filter((f) => f.root === 'project') };
   const problems = [];
   for (const k of ['dir', 'project']) {
     if (!groups[k].length) continue;
     problems.push(...preflight(groups[k], roots[k]).map((p) => (k === 'project' ? `[project] ${p}` : p)));
   }
+  // A legacy brief is a read and possible deletion target, so validate it with
+  // the same containment, regular-file and symlink checks as every write.
+  const currentBrief = groups.dir.find((f) => f.rel === 'TASK_BRIEF.md');
+  const legacyPath = resolve(realRoot(dir).root, LEGACY_BRIEF);
+  let hasLegacy = false;
+  if (currentBrief) {
+    try { lstatSync(legacyPath); hasLegacy = true; } catch { /* absent */ }
+    if (hasLegacy) problems.push(...preflight([{ rel: LEGACY_BRIEF }], dir));
+  }
   if (!problems.length) {
     for (const f of files.filter((file) => file.applySnippet)) {
       const abs = resolve(roots[f.root], f.rel);
@@ -884,6 +1118,7 @@ export function writeFiles(files, opts) {
   const docsUpdated = [];   // --update-docs: documents regenerated because the installed copy was an untouched generated one
   const docsConflict = [];  // --update-docs: documents kept because you edited them
   const docsUnverifiable = []; // --update-docs: documents kept because there is no manifest to compare against
+  const docsRenamed = [];
   const backups = [];
   const created = [];
   // Only directories actually created by this install are owned. Preserve the
@@ -895,6 +1130,7 @@ export function writeFiles(files, opts) {
   // never the hash of content this run planned but did not write. Otherwise the next
   // --update-docs or upgrade sees every kept file as "edited".
   const keptKeys = new Set();
+  const removedKeys = new Set();
   try {
     // project first so MANIFEST.json (last in the dir group) is the final write and can
     // describe every decision made above it
@@ -969,7 +1205,40 @@ export function writeFiles(files, opts) {
         }
         let content = f.content;
         if (f.rel === 'MANIFEST.json') {
+          if (hasLegacy) {
+            const previousHash = prevHashes?.[LEGACY_BRIEF];
+            const original = readLegacyBrief(legacyPath, dir);
+            const unchanged = previousHash && sha256(original.content) === previousHash;
+            if ((updateDocs || force) && unchanged) {
+              // The replacement has already been written (or preserved) by this
+              // point. Keep deletion in this transaction and restore on failure.
+              const current = readLegacyBrief(legacyPath, dir);
+              const last = lstatSync(legacyPath);
+              if (!current.content.equals(original.content) || current.stat.ino !== original.stat.ino || current.stat.dev !== original.stat.dev
+                  || last.ino !== current.stat.ino || last.dev !== current.stat.dev || !last.isFile()) {
+                const e = new Error('legacy brief changed during upgrade; re-run the installer');
+                e.code = 'PREFLIGHT';
+                throw e;
+              }
+              if (!dry) {
+                originals.set(legacyPath, { content: original.content, mode: original.stat.mode });
+                unlinkSync(legacyPath);
+              }
+              removedKeys.add(LEGACY_BRIEF);
+              docsRenamed.push(`${LEGACY_BRIEF} -> TASK_BRIEF.md`);
+            } else if ((updateDocs || force) && !previousHash) {
+              docsUnverifiable.push(LEGACY_BRIEF);
+            } else if ((updateDocs || force) && !unchanged) {
+              docsConflict.push(LEGACY_BRIEF);
+            } else skipped.push(LEGACY_BRIEF);
+          }
           const m = JSON.parse(content);
+          // Preserve ownership of retained 0.1.x companion files and other
+          // formerly selected files, so uninstall still checks their original
+          // installed hashes. New defaults do not erase a previous selection.
+          m.files = { ...prevHashes, ...m.files };
+          if (Object.keys(activation).length) m.activation = activation;
+          for (const removed of removedKeys) delete m.files[removed];
           for (const kk of Object.keys(m.files || {})) {
             if (!keptKeys.has(kk)) continue;
             if (prevHashes && prevHashes[kk]) m.files[kk] = prevHashes[kk];
@@ -977,7 +1246,7 @@ export function writeFiles(files, opts) {
           }
           content = JSON.stringify(m, null, 2) + '\n';
         }
-        if (exists && opts.backupExisting) {
+        if (exists && (opts.backupExisting || k === 'project')) {
           let stamp = Date.now();
           let backup;
           do {
@@ -1033,7 +1302,7 @@ export function writeFiles(files, opts) {
     }
     throw e;
   }
-  return { written, skipped, upgraded, conflicts, unverifiable, docsUpdated, docsConflict, docsUnverifiable, backups };
+  return { written, skipped, upgraded, conflicts, unverifiable, docsUpdated, docsConflict, docsUnverifiable, docsRenamed, backups };
 }
 
 export function resolveSelection(ids) {