hafez 1.4.0 → 2.1.0

package/dist/cli/onboard.js

@@ -1,94 +1,277 @@
 // src/cli/onboard.ts
 //
-// `hafez onboard` — agent-directed first-run guide. Same pattern as
-// `hafez help --agent`: plain text printed for the agent operating on the
-// user's behalf. Covers the two things a fresh install leaves open — seeding
-// the empty vault and choosing how deeply the agent integrates.
+// `hafez onboard` — the user side of the Agent Contract (onboard decision
+// #58). Bare, it prints where things stand, then the script the agent follows
+// for its user: ask the Mode, install, allow the command, offer the hook and
+// any other Harness found, seed an empty vault, hand over with the teaching
+// lines. The files are the state: re-running walks only what is not current.
 //
-// Static by design, and deliberately NOT part of the skill: the skill loads
-// into every session forever, this is read once. Living in the CLI also means
-// it works before the skill is installed.
-export const INTEGRATION_SNIPPET = `## Hafez — Session Memory
-
-- Session start: if the first message names a project or topic, load context
-  with \`hafez read <slug>\` (or \`hafez search "<topic>"\`). Don't load
-  speculatively.
-- Mid-session: new workstream -> create an entity. Durable insight -> create
-  or update a knowledge note (search first). User mentions a project by
-  name -> check if it's a Hafez entity. Use \`hafez batch\` for 2+ mutations.
-- Session end: record a digest (\`hafez digest | hafez batch\`; on shells
-  that can't pipe, e.g. PowerShell 5.1: \`--file\` on both) with the
-  entities touched, decisions made, and a short narrative.
-- Knowledge boundary: useful beyond this repo/session -> vault knowledge
-  note. Specific to one repo's code -> that repo's own docs, not the vault.`;
-export function renderOnboard() {
-    return `# Hafez — First Run
-
-You are an agent reading this on behalf of your user. Walk them through the
-steps below conversationally — do not dump this document on them.
-
-Prerequisites: \`hafez init\` resolves a vault, and you have read
-\`hafez help --agent\` (do that now if not). The CLI is the whole interface —
-no other pieces are required. If your harness is Claude Code, also install
-the bundled skill — see the README Setup (github.com/shrvn-r/hafez).
-
-Re-running onboard is normal and intended: on a vault that is already set
-up and integrated, skip Step 2 and use Step 1 as a seeding interview for
-whatever is new since last time. Seed current, active work — seeding never
-means documenting the past; using the vault as you go stays primary.
-
-## Step 1 — Seed the vault
-
-An empty vault gives the agent nothing to trigger on, so the memory loop
-never starts. The goal here is a small set of high-quality entries — not a
-bulk import.
-
-1. Interview the user: "What are you actively working on right now?" Aim for
-   3-7 projects or areas. For each one, draw out:
-   - a one-line description (\`description\`)
-   - current state / handoff context, 2-4 sentences (\`brief\`)
-   - 1-2 concrete next actions (\`add_action\`)
-2. Offer to mine sources they already have — a repo's README, existing notes,
-   a TODO list. Read what they point you at, propose entries, and let them
-   approve before writing anything.
-3. Anything vague, aspirational, or someday-maybe becomes a capture, not a
-   project. Captures are the inbox; promotion comes later. When in doubt,
-   capture.
-4. Write everything in ONE \`hafez batch\` call (see
-   \`hafez schema create-entity --examples\`), then show the user
-   \`hafez stats\`.
-
-Quality bar: every project entry should let a future agent with zero context
-pick the work up from the brief alone. If a brief would not do that, ask one
-more question.
-
-## Step 2 — Choose the integration level
-
-Ask the user how they want Hafez wired into their sessions. Recommend the
-first option.
-
-RECOMMENDED — always active. Add the block below to the user's global agent
-instructions file — Claude Code: \`~/.claude/CLAUDE.md\`; any harness that
-follows the AGENTS.md standard (Codex, Cursor, Copilot, ...): its global
-AGENTS.md, e.g. \`~/.codex/AGENTS.md\` for Codex CLI. This makes memory
-automatic: context loads at session start, the vault is updated as work
-happens, and a digest records each session. Show them the block, get a yes,
-then append it verbatim:
-
-${INTEGRATION_SNIPPET}
-
-FALLBACK — invoke only. If the user prefers to stay in control, add nothing.
-Explain how invocation works: the agent touches the vault only when they
-mention Hafez or name a project ("what am I working on?", "read <slug>").
-Nothing is loaded or written unless asked. They can upgrade later
-by re-running \`hafez onboard\`.
-
-## Step 3 — Hand over
-
-Finish with three example asks tailored to what was just seeded, e.g.:
-
-- "What am I working on?"
-- "Read <their-project-slug> and pick up where we left off."
-- "Capture: <idea> — I'll triage it later."
-`;
+// `--install` and `--remove` write the files Hafez owns outside the vault
+// (install.ts). The binary has no interactive prompts: the agent asks, then
+// passes the answer as a flag. `--block` is the SessionStart hook's render
+// (block-hook.ts) and writes nothing.
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { UsageError, parseArgs, str } from './args.js';
+import { HARNESSES, ONBOARD_HARNESSES, detectAgent, isHarness, isOnboardHarness } from '../harness.js';
+import { MODES, SKILL_DIRS, fixBrokenMarkers, install, installState, instructionsFile, isMode, legacyLine, remove, removeLegacy } from './install.js';
+import { noVaultMessage, resolveVaultPath } from './resolve-vault.js';
+import { HafezError } from '../types.js';
+import { kindDir, scanVaultDir } from '../vault.js';
+import { ITEMS } from '../surfaces/items.js';
+import { renderBlock } from '../surfaces/surfaces.js';
+import { blockHook } from './block-hook.js';
+const HARNESS_IDS = Object.keys(HARNESSES).join('|');
+const MODE_IDS = MODES.join('|');
+const ONBOARD_USAGE = `Usage:
+  hafez onboard
+  hafez onboard --install --mode <${MODE_IDS}> [--harness <${HARNESS_IDS}>] [--confirm]
+  hafez onboard --remove [--confirm]
+  hafez onboard --block [--harness <${HARNESS_IDS}>]`;
+/** `ctx` is the temp-home seam: tests pass a temporary home and environment;
+ * the install functions are given the home, never read it. `vaultFlag` is the
+ * global `--vault`; without it the bare form reports on the registered vault.
+ * `--block` returns a promise of its render, or of null when it must print nothing. */
+export function cmdOnboard(args, ctx = {}) {
+    const { home = homedir(), env = process.env, cwd, vaultFlag } = ctx;
+    const { flags, positionals } = parseArgs(args, { install: 'boolean', remove: 'boolean', block: 'boolean', mode: 'string', harness: 'string', confirm: 'boolean' }, ONBOARD_USAGE);
+    const fail = (why) => {
+        throw new UsageError(`${why}\n${ONBOARD_USAGE}`);
+    };
+    if (positionals.length)
+        fail(`Unexpected argument: ${positionals[0]}`);
+    const mode = str(flags.mode);
+    const harnessFlag = str(flags.harness);
+    const confirm = flags.confirm === true;
+    if (flags.install && flags.remove)
+        fail('--install and --remove are separate commands');
+    if (flags.block) {
+        if (flags.install || flags.remove || mode !== undefined || confirm)
+            fail('--block takes only --harness: it prints the Block and writes nothing');
+        if (harnessFlag !== undefined && !isHarness(harnessFlag))
+            fail(`Unknown harness: ${harnessFlag}`);
+        return blockHook({ home, env, cwd, vaultFlag });
+    }
+    if (flags.remove) {
+        if (mode !== undefined || harnessFlag !== undefined)
+            fail('--remove takes no --mode or --harness: it removes everything Hafez wrote');
+        return remove({ home, confirm });
+    }
+    if (flags.install) {
+        if (mode === undefined)
+            return fail(`--install needs --mode <${MODE_IDS}>`);
+        if (!isMode(mode))
+            return fail(`Unknown mode: ${mode}`);
+        const harness = harnessFlag ?? detectAgent(env);
+        if (!isHarness(harness)) {
+            return fail(harnessFlag === undefined ? `No harness detected: pass --harness <${HARNESS_IDS}>` : `Unknown harness: ${harnessFlag}`);
+        }
+        return install({ home, harness, mode, confirm });
+    }
+    if (mode !== undefined || harnessFlag !== undefined || confirm)
+        fail('--mode, --harness and --confirm go with --install, --remove or --block');
+    const harness = detectAgent(env);
+    if (!isOnboardHarness(harness)) {
+        return fail('No harness detected: run `hafez onboard` from inside Claude Code or Codex. Another harness: `hafez onboard --install --harness <h>`');
+    }
+    return renderOnboard({ home, harness, vault: resolvedVault(vaultFlag) });
+}
+function resolvedVault(flag) {
+    const resolution = resolveVaultPath(flag);
+    if (resolution === null)
+        throw new HafezError('NOT_FOUND', noVaultMessage());
+    if (typeof resolution === 'object')
+        throw new HafezError('NOT_FOUND', resolution.error);
+    return resolution;
+}
+// --- Bare onboard: status, then the script ---
+const read = (home, rel) => {
+    try {
+        return readFileSync(join(home, rel), 'utf-8');
+    }
+    catch {
+        return null;
+    }
+};
+/** Whether the SessionStart hook and the permission entries are already in
+ * the Harness's config: present when found, absent otherwise (an unreadable
+ * file included). Claude Code's settings are JSON; Codex's rule and TOML are
+ * matched as text. */
+function harnessConfig(home, harness, vault) {
+    const isHook = (command) => typeof command === 'string' && command.includes('hafez onboard --block');
+    if (harness === 'claude-code') {
+        const { hooks, allowEntry } = ONBOARD_HARNESSES[harness];
+        let settings = null;
+        try {
+            settings = JSON.parse(read(home, hooks) ?? 'null');
+        }
+        catch {
+            settings = null;
+        }
+        const groups = Array.isArray(settings?.hooks?.SessionStart) ? settings.hooks.SessionStart : [];
+        const allow = Array.isArray(settings?.permissions?.allow) ? settings.permissions.allow : [];
+        return {
+            hook: groups.some((group) => Array.isArray(group?.hooks) && group.hooks.some((h) => isHook(h?.command))),
+            allowlist: allow.includes(allowEntry),
+        };
+    }
+    const { hooks, rules, config } = ONBOARD_HARNESSES[harness];
+    const toml = read(home, config) ?? '';
+    return {
+        hook: isHook(read(home, hooks)) || isHook(toml),
+        allowlist: /prefix_rule\(\s*pattern\s*=\s*\[\s*"hafez"\s*\]/.test(read(home, rules) ?? '') && toml.includes(JSON.stringify(vault)),
+    };
+}
+const hookEntry = (harness) => `{"matcher": "startup|compact", "hooks": [{"type": "command", "command": "hafez onboard --block --harness ${harness}"}]}`;
+/** Mode is never stored: a Block present means always-on, skills `onboard`
+ * installed without one mean invoke-only. Neither is a first run, a setup from
+ * before `onboard` (a hand-pasted section, a skill with no hash) included. */
+const modeOf = ({ block, onboarded }) => block !== null && block !== 'absent' ? 'always-on' : onboarded ? 'invoke-only' : null;
+/** Current in its Mode: the skills current, and the Block too where there is
+ * one. A Harness with no Block file (Cursor) is current on its skills. */
+const isCurrent = (state) => state.skills === 'current' && (state.block === null || state.block === 'current' || modeOf(state) === 'invoke-only');
+const statusLine = (label, { block, skills }, extra = []) => `${label}: ${[...(block === null ? [] : [`Block ${block === 'broken' ? 'broken markers' : block}`]), `skills ${skills}`, ...extra].join(' | ')}`;
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+const listed = (names) => (names.length === 1 ? names[0] : `${names.slice(0, -1).join(', ')} and ${names.at(-1)}`);
+export function renderOnboard({ home, harness, vault }) {
+    const { label, instructions } = HARNESSES[harness];
+    const state = installState(home, harness);
+    const config = harnessConfig(home, harness, vault);
+    const others = Object.keys(HARNESSES)
+        .filter(id => id !== harness && existsSync(join(home, HARNESSES[id].dir)))
+        .map(id => ({ id, ...HARNESSES[id], state: installState(home, id) }));
+    const entities = scanVaultDir(join(vault, kindDir('entity'))).length;
+    const knowledge = scanVaultDir(join(vault, kindDir('knowledge'))).length;
+    const mode = modeOf(state);
+    const otherMode = mode === 'always-on' ? 'invoke-only' : 'always-on';
+    const installCurrent = isCurrent(state);
+    const teaching = (m) => ITEMS.teachingLines.render({ harness, mode: m });
+    const line2 = (m) => ITEMS.teachingLines.render({ harness, mode: m, line2Only: true });
+    const instructionsRel = `~/${instructionsFile(home, instructions)}`;
+    const block = `\`\`\`\`\n${renderBlock()}\`\`\`\``;
+    const showBlock = `show the user the Block below word for word, not a summary, say it goes into ${instructionsRel} between two marker lines and nothing else in that file changes, and get a yes. Then run:`;
+    const status = [
+        `Vault: ${vault} (${plural(entities, 'entity', 'entities')}, ${plural(knowledge, 'knowledge note', 'knowledge notes')})`,
+        statusLine(`${label} (this harness)`, state, [`hook ${config.hook ? 'present' : 'absent'}`, `allowlist ${config.allowlist ? 'present' : 'absent'}`]),
+        ...others.map(o => statusLine(`${o.label} (found at ~/${o.dir})`, o.state)),
+        // `--install` and `--remove` refuse broken markers: only a hand fix walks on.
+        ...[{ ...HARNESSES[harness], state }, ...others]
+            .filter(h => h.state.block === 'broken')
+            .map(h => fixBrokenMarkers(`~/${instructionsFile(home, h.instructions)}`, 'hafez onboard')),
+        ...[{ ...HARNESSES[harness], state }, ...others]
+            .filter(h => h.state.legacy !== null)
+            .map(h => `${legacyLine(`~/${instructionsFile(home, h.instructions)}`, h.state.legacy)}, from Hafez 1.x, with no markers.`),
+    ];
+    // With the install current there is no install step: switching the Mode is
+    // walked here, and re-running `onboard` afterwards walks what it changed.
+    const switchMode = !installCurrent || mode === null
+        ? []
+        : otherMode === 'always-on'
+            ? [`To switch to always-on, ${showBlock}`, '', 'hafez onboard --install --mode always-on', '', 'then `hafez onboard` again for the session-start hook.', '', block]
+            : [
+                'To switch to invoke-only, run:',
+                '',
+                'hafez onboard --install --mode invoke-only',
+                ...(config.hook ? ['', `and remove the hafez entry from hooks.SessionStart in ~/${ONBOARD_HARNESSES[harness].hooks}.`] : []),
+            ];
+    const steps = [];
+    steps.push({
+        title: 'Ask how Hafez should run',
+        body: [
+            'Ask one question and recommend the first answer.',
+            '',
+            '- Always-on: you load the vault at the start of a session and write to it as work lands.',
+            '- Invoke-only: nothing happens unless the user asks. No load at start, no writes during the session.',
+            ...(mode === null ? [] : ['', `It runs ${mode} now.${switchMode.length ? ` ${switchMode[0]}` : ''}`, ...switchMode.slice(1)]),
+        ].join('\n'),
+    });
+    if (!installCurrent && state.block !== 'broken') {
+        steps.push({
+            title: 'Install',
+            body: [
+                // Either install leaves the 1.x section in place, beside the Block or alone.
+                ...(state.legacy === null ? [] : [`${removeLegacy(instructionsRel, state.legacy)} Do this before either install below.`, '']),
+                `Always-on: ${showBlock}`,
+                '',
+                'hafez onboard --install --mode always-on',
+                '',
+                'Invoke-only: no file of theirs is edited. Run:',
+                '',
+                'hafez onboard --install --mode invoke-only',
+                '',
+                `Both install two skills, \`hafez\` and \`hafez-save\`, into ${SKILL_DIRS.map(d => `~/${d}`).join(' and ')}.`,
+                '',
+                block,
+            ].join('\n'),
+        });
+    }
+    if (installCurrent && state.legacy !== null) {
+        steps.push({ title: 'Remove the Hafez 1.x section', body: removeLegacy(instructionsRel, state.legacy) });
+    }
+    if (!config.allowlist) {
+        steps.push({ title: 'Allow the command', body: ITEMS.harnessPermissions.render({ harness, vault }) });
+    }
+    if (!config.hook && mode !== 'invoke-only') {
+        steps.push({
+            title: 'Offer the session-start hook (always-on only)',
+            body: 'Ask: should the Block be delivered again at the start of every session and after the context is compacted? '
+                + `If yes, show this entry, then add it to ~/${ONBOARD_HARNESSES[harness].hooks} under hooks.SessionStart:\n\n${hookEntry(harness)}`
+                // Live run (#101): Codex asks once whether to trust a new hook.
+                + (harness === 'codex' ? '\n\nTell the user Codex will ask once, at the next session start, whether to trust this hook: the answer is yes.' : ''),
+        });
+    }
+    const offered = others.filter(o => !isCurrent(o.state) && o.state.block !== 'broken');
+    if (offered.length > 0) {
+        const one = offered.length === 1;
+        steps.push({
+            title: 'Offer the other harness',
+            body: [
+                `${listed(offered.map(o => o.label))} ${one ? 'is' : 'are'} installed too. Ask once whether to set ${one ? 'it' : 'them'} up the same way. If yes:`,
+                '',
+                // A first run cannot know the answer to step 1 yet; the agent carries it.
+                ...offered.map(o => `hafez onboard --install --harness ${o.id} --mode ${mode ?? 'always-on'}`),
+            ].join('\n'),
+        });
+    }
+    steps.push(entities + knowledge === 0
+        ? {
+            title: 'Seed the vault',
+            body: [
+                'An empty vault gives you nothing to load. Ask: "What are you working on right now?" Aim for three to seven pieces of work. For each, draw out one sentence of description, where things stand, and the next step, then write it:',
+                '',
+                ITEMS.createLines.render('<name>'),
+                '',
+                'Anything vague or someday: `hafez capture "<name>"`. Read a README or notes only if the user points you at them. Do not ask for approval before writing. When done, show them `hafez stats`.',
+            ].join('\n'),
+        }
+        : { title: 'Seed the vault (skipped: the vault is not empty)' });
+    // On a re-run only line 2's subject can have changed: the Mode, if the
+    // user switches it in step 1.
+    steps.push({
+        title: 'Hand over',
+        body: mode === null
+            ? [
+                'Say these to the user in your own words, then give three example asks drawn from their vault, each naming an entity or note in it.',
+                '',
+                'Always-on:',
+                '',
+                teaching('always-on'),
+                '',
+                'Invoke-only, line 2:',
+                '',
+                line2('invoke-only'),
+            ].join('\n')
+            : `The user has heard the teaching lines before. Only if they switched to ${otherMode} in step 1, tell them in your own words:\n\n${line2(otherMode)}`,
+    });
+    return [
+        '# Hafez setup',
+        '',
+        'You are an agent reading this for your user. Talk them through it; do not paste this to them.',
+        '',
+        '## Where things stand',
+        '',
+        ...status,
+        ...steps.flatMap(({ title, body }, i) => ['', `## ${i + 1}. ${title}`, ...(body === undefined ? [] : ['', body])]),
+    ].join('\n');
 }

package/dist/cli/resolve-vault.d.ts

@@ -1,12 +1,19 @@
-export declare function getConfigDir(): string;
-export declare function getConfigPath(): string;
-export declare function readVaultConfig(): string | null;
+/** Where the config is looked for. The environment and home are inputs so the
+ * `onboard --block` hook runs against a temporary home in tests. */
+export interface ConfigHome {
+    env: Record<string, string | undefined>;
+    home: string;
+}
+export declare function getConfigDir({ env, home }?: ConfigHome): string;
+export declare function getConfigPath(at?: ConfigHome): string;
+export declare function readVaultConfig(at?: ConfigHome): string | null;
 export declare function saveVaultConfig(vaultPath: string): void;
+export declare function isVault(dirPath: string): boolean;
 /**
  * Resolve vault path. Returns string or null.
  * If config exists but points to a bad path, returns an error object instead.
  */
-export declare function resolveVaultPath(flagValue?: string): string | null | {
+export declare function resolveVaultPath(flagValue?: string, at?: ConfigHome): string | null | {
     error: string;
 };
 export declare function noVaultMessage(): string;

package/dist/cli/resolve-vault.js

@@ -4,15 +4,16 @@ import { join, resolve } from 'path';
 import { homedir } from 'os';
 import { execSync } from 'child_process';
 import { kindDir } from '../vault.js';
-export function getConfigDir() {
-    const xdg = process.env.XDG_CONFIG_HOME;
-    return join(xdg || join(homedir(), '.config'), 'hafez');
+import { helpIfAsked } from './args.js';
+const processHome = () => ({ env: process.env, home: homedir() });
+export function getConfigDir({ env, home } = processHome()) {
+    return join(env.XDG_CONFIG_HOME || join(home, '.config'), 'hafez');
 }
-export function getConfigPath() {
-    return join(getConfigDir(), 'vault');
+export function getConfigPath(at = processHome()) {
+    return join(getConfigDir(at), 'vault');
 }
-export function readVaultConfig() {
-    const configPath = getConfigPath();
+export function readVaultConfig(at = processHome()) {
+    const configPath = getConfigPath(at);
     if (!existsSync(configPath))
         return null;
     try {
@@ -28,25 +29,25 @@ export function saveVaultConfig(vaultPath) {
     mkdirSync(dir, { recursive: true });
     writeFileSync(join(dir, 'vault'), resolve(vaultPath) + '\n');
 }
-function isVault(dirPath) {
+export function isVault(dirPath) {
     return existsSync(dirPath) && statSync(dirPath).isDirectory() && existsSync(join(dirPath, kindDir('entity')));
 }
 /**
  * Resolve vault path. Returns string or null.
  * If config exists but points to a bad path, returns an error object instead.
  */
-export function resolveVaultPath(flagValue) {
+export function resolveVaultPath(flagValue, at = processHome()) {
     // 1. Explicit flag
     if (flagValue)
         return flagValue;
     // 2. Config file
-    const configValue = readVaultConfig();
+    const configValue = readVaultConfig(at);
     if (configValue) {
         if (isVault(configValue))
             return configValue;
         // Config exists but points to bad path — loud failure
         return {
-            error: `Config (${getConfigPath()}) points to ${configValue} but it doesn't look like a vault.\nRun 'hafez init --register /correct/path' to fix.`,
+            error: `Config (${getConfigPath(at)}) points to ${configValue} but it doesn't look like a vault.\nRun 'hafez init --register /correct/path' to fix.`,
         };
     }
     return null;
@@ -65,6 +66,7 @@ Get started:
 `;
 }
 export function cmdInit(args, flagValue) {
+    helpIfAsked(args, 'Usage: hafez init [--register <path>]');
     const registerIdx = args.indexOf('--register');
     if (registerIdx !== -1) {
         // hafez init --register <path>

package/dist/cli/schema-introspect.js

@@ -47,8 +47,10 @@ function walk(node) {
         return inner;
     }
     if (type === 'pipe' || type === 'effects' || type === 'transform' || type === 'readonly') {
-        // Zod effects / transforms / pipes — descend to the inner schema.
-        const inner = def.in ?? def.schema ?? def.innerType;
+        // Zod effects / transforms / pipes — descend to the inner schema. A
+        // z.preprocess is a pipe whose input is the bare transform: its shape is
+        // the output side.
+        const inner = def.in?._def?.type === 'transform' ? def.out : def.in ?? def.schema ?? def.innerType;
         if (inner)
             return walk(inner);
     }
@@ -153,7 +155,6 @@ export const DIGEST_EXAMPLE = {
     decisions: ['Decision made'],
     narrative: 'One to three sentence cross-cutting summary.',
     session_date: '2026-01-15',
-    agent: 'claude',
 };
 // Descriptions live in the Op Spec table (src/batch-ops.ts) — one row per op.
 const OP_DESCRIPTIONS = Object.fromEntries(OP_SPECS.map(s => [s.name, s.description]));

package/dist/cli/upgrade.d.ts

@@ -1,3 +1,4 @@
+import { type BlockCheck, type LegacyCheck, type SkillCheck } from './install.js';
 export type Comparison = 'behind' | 'equal' | 'ahead' | 'unknown';
 /** `command` entries are directly executable (after user approval); `action`
  * entries are prose, so an agent that shells out every entry does not try to
@@ -13,19 +14,29 @@ export interface UpgradeState {
     registryReachable: boolean;
     npmMajor: number | null;
     install: 'registry' | 'dev-checkout';
-    skill: 'present' | 'absent';
-    skillSource: string;
-    skillTarget: string;
+    /** Null when the installed files could not be read. */
+    integration: Integration | null;
     /** Mutually exclusive with the registry install in `steps` — exposed
      * separately so an agent iterating `steps` cannot run both. */
     alternativeInstall: string | null;
     steps: UpgradeStep[];
 }
+/** Mode is not stored: a Block present means always-on, and so does a 1.x
+ * section with no markers (`legacy`). */
+export interface Integration {
+    mode: 'always-on' | 'invoke-only';
+    blocks: BlockCheck[];
+    skills: SkillCheck[];
+    legacy: LegacyCheck[];
+}
 export interface UpgradeDeps {
     fetch: typeof globalThis.fetch;
     registryUrl: string;
     packageRoot: string;
-    installedSkillPath: string;
+    /** The temp-home seam, as onboard's. */
+    home: string;
+    /** Names the Harness for an invoke-only `onboard --install`. */
+    env: Record<string, string | undefined>;
     npmVersion: () => string;
 }
 /** Three-way compare on the numeric segments. Hand-rolled string compare is