@bvdm/delano 0.2.1 → 0.2.2

package/LICENSE

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

package/README.md

@@ -15,9 +15,19 @@ The npm package is intentionally thin. It distributes the approved runtime paylo
 ## Delano CLI
 
 - Package: `@bvdm/delano`
+- Current package version: `0.2.2`
 - Binary: `delano`
 - Commands: `onboarding`, `install`, `viewer`, `init`, `validate`, `status`, `next`
-- Primary v1.1 goal: bootstrap a repo safely, then stay out of the way
+- Primary goal: bootstrap a repo safely, expose local delivery state clearly, and keep runtime gates verifiable
+
+## Recent main changes
+
+The latest main merges moved Delano beyond a thin install wrapper:
+
+- PR #4, `feat/delano-vnext-runtime-upgrade`, merged on 2026-05-04. This added the v0.2 runtime layer: schema-backed `.project` artifact validation, operating-mode and status-transition checks, evidence mapping, strict validation fixtures, privacy-safe logging defaults, package/payload drift checks, dry-run sync inspection, apply-gated repair planning, lease-based multi-agent coordination, worktree health checks, delivery metrics, context audits, skill-output eval fixtures, and compact root/adapter agent instructions.
+- PR #3, `delano-viewer-design-overhaul`, merged on 2026-04-29. This added the packaged read-only Delano viewer under `.delano/viewer`, including the local Node server, static UI, `.project` indexing APIs, project outlines, workstream/task navigation, rendered markdown, context-aware filters, guarded open actions, and visual/browser smoke evidence.
+
+The current runtime still treats `HANDBOOK.md` and `.project/` as the source of truth. The new pieces make that model easier to inspect and harder to bypass accidentally.
 
 ## One-command bootstrap
 
@@ -123,11 +133,11 @@ bash .agents/scripts/pm/status.sh
 bash .agents/scripts/pm/next.sh --all
 ```
 
-The viewer is packaged with `@bvdm/delano` and serves the selected repository's `.project` files read-only. It defaults to `http://127.0.0.1:3977`; set `DELANO_VIEWER_PORT` or `PORT` to use another port.
+The viewer is packaged with `@bvdm/delano` and serves the selected repository's `.project` files read-only. It defaults to `http://127.0.0.1:3977`; set `DELANO_VIEWER_PORT` or `PORT` to use another port. It indexes `.project/context`, `.project/templates`, and `.project/projects`, then derives artifact roles, statuses, project outlines, task/workstream relationships, snippets, and rendered markdown for local inspection.
 
 ## Required dependencies
 
-Delano v1.1 assumes these tools are available:
+Delano assumes these tools are available:
 
 - `node` 18 or newer
 - `bash`
@@ -144,6 +154,7 @@ The CLI does not bundle its own shell or Python runtime.
 - it aborts if an approved target path already exists
 - it reports each conflict as file, directory, or symlink
 - it only overwrites approved allowlist paths when `--force` is used
+- it can narrow updates with `--only`, `--exclude`, `--no-project-context`, and `--no-project-state`
 - it does not touch unrelated files outside the allowlist
 - it does not install or overwrite repo-root Git config files such as `.gitignore` or `.gitattributes`
 
@@ -152,6 +163,19 @@ The base install payload includes `.delano/`, including the read-only viewer UI.
 The installable `.project/context/` pack is seeded from generic templates during packaging; it does not ship Delano's own repo-specific context files into consumer repositories.
 After install, the recommended first step is `delano onboarding`, which requires explicit approval before it reviews `AGENTS.md`.
 
+For an update-safe refresh that avoids repo-owned project state, narrow the plan before forcing overwrites:
+
+```bash
+delano install --interactive
+delano install --only skills,project-templates --force --yes
+delano install --exclude project-context,project-projects,project-registry --force --yes
+delano install --no-project-state --force --yes
+```
+
+The interactive installer presents presets for updating the runtime while preserving project state, updating only skills and project templates, full install or repair, and custom category selection.
+
+Install categories are `agent-runtime`, `skills`, `viewer`, `project-context`, `project-templates`, `project-registry`, `project-projects`, `handbook`, and `legacy-installer`. The `--no-project-state` shortcut excludes `.project/context`, `.project/projects`, and `.project/registry`.
+
 ## Optional AGENTS.md / CLAUDE.md snippet
 
 If you want explicit Delano instructions in a repo-root `AGENTS.md` or `CLAUDE.md`, copy and paste this yourself:
@@ -174,16 +198,38 @@ When working in this repository:
 - use `delano viewer` to inspect `.project/` through the read-only local UI
 ```
 
-## v1.1 boundaries
+## Runtime boundaries
 
 This package is deliberately narrow:
 
 - npm is the distribution surface
 - `.project` remains repo-owned after install
 - `.project/context/` installs as generic starter context that the target repo must replace with its own reality
+- `.project/projects/` and `.project/registry/` are repo-owned state and should normally be excluded from forced refreshes
 - `.agents` remains the runtime surface
-- wrapper commands stay thin in v1.1
+- wrapper commands stay thin
 - `install-delano.sh` remains available as the legacy bridge installer
+- remote GitHub/Linear writes remain outside the default flow; current sync tooling is dry-run and repair-plan oriented unless an operator explicitly approves an apply-capable workflow
+
+## Runtime validation
+
+The v0.2 runtime upgrade expanded `delano validate` and `bash .agents/scripts/pm/validate.sh` with local gates for:
+
+- artifact schemas, artifact scope, operating modes, status transitions, dependencies, blockers, and acceptance/evidence mapping
+- privacy-safe prompt/log defaults and path-output safety
+- package manifest and install payload drift
+- local/GitHub/Linear sync inspection, drift reporting, and apply-gated repair planning
+- lease contracts, conflict zones, stream-aware next-task selection, handoff summaries, and worktree health
+- delivery metrics, project metrics summaries, context audit scoring, skill-output eval fixtures, and closeout learning proposals
+
+For release readiness, run:
+
+```bash
+npm run build:assets
+npm run check:package-manifest
+bash .agents/scripts/pm/validate.sh
+npm test
+```
 
 ## Local development
 
@@ -208,7 +254,7 @@ Before the first Actions publish, configure npm trusted publishing for `@bvdm/de
 
 The package metadata must keep `repository.url` set to `https://github.com/MajesteitBart/delano`; npm validates that value against the GitHub Actions provenance bundle.
 
-After trusted publishing is configured, publish by pushing a matching version tag such as `v0.2.0`, or run the `Publish package to npm` workflow manually from `main`. The workflow rebuilds the package payload, checks manifest drift, runs tests, dry-runs the package contents, verifies the version is not already published, and then runs `npm publish --access public` from GitHub Actions using OIDC. A manual `dry_run` input is available to run the same checks without publishing.
+After trusted publishing is configured, publish by pushing a matching version tag such as `v0.2.2`, or run the `Publish package to npm` workflow manually from `main`. The workflow rebuilds the package payload, checks manifest drift, runs tests, dry-runs the package contents, verifies the version is not already published, and then runs `npm publish --access public` from GitHub Actions using OIDC. A manual `dry_run` input is available to run the same checks without publishing.
 
 If npm publish fails after the package checks pass, verify that the npm trusted publisher settings match the repository and workflow filename exactly, and that the workflow has `id-token: write`.
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@bvdm/delano",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "CLI for the Delano delivery runtime.",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/MajesteitBart/delano"

package/src/cli/commands/install.js

@@ -2,6 +2,7 @@ const {
   applyInstallPlan,
   buildInstallPlan,
   collectConflicts,
+  configureInteractiveInstall,
   confirmInstall,
   parseInstallArgs,
   printConflicts,
@@ -17,24 +18,43 @@ function getInstallHelp() {
     "Options:",
     "  --target <dir>     Install into the given directory. Defaults to the current working directory.",
     "  --agents <list>    Comma-separated agent list for future opt-in adapter docs: claude,codex,opencode,pi.",
+    "  --only <list>      Install only selected categories.",
+    "  --exclude <list>   Omit selected categories from the install plan.",
+    "  --no-project-state Omit .project/context, .project/projects, and .project/registry.",
+    "  --no-project-context",
+    "                    Omit .project/context starter templates.",
+    "  --interactive     Choose an install preset and target in the terminal.",
+    "  --tui             Alias for --interactive.",
     "  --force            Overwrite existing allowlisted target paths. Does not override parent-path blockers.",
     "  --yes              Skip the final confirmation prompt.",
     "  -h, --help         Show command help.",
     "",
+    "Categories:",
+    "  agent-runtime, skills, viewer, project-context, project-templates,",
+    "  project-registry, project-projects, handbook, legacy-installer",
+    "",
     "Behavior:",
     "  - Computes the full install plan before writing files.",
     "  - Aborts on conflicts by default.",
+    "  - Filters the plan before conflict detection when --only or --exclude is used.",
+    "  - Treats .project/context, .project/projects, and .project/registry as repo-owned state after install.",
     "  - Only installs the approved base payload; top-level adapter entry docs remain opt-in and are not installed in v1.",
     "",
     "Examples:",
+    "  delano install --interactive",
     "  delano install --target ../repo --yes",
+    "  delano install --only skills,project-templates --force --yes",
+    "  delano install --exclude project-context,project-projects,project-registry --force --yes",
     "  delano --yes",
     "  npx -y @bvdm/delano@latest --yes"
   ].join("\n");
 }
 
 async function runInstall(args) {
-  const options = parseInstallArgs(args);
+  let options = parseInstallArgs(args);
+  if (options.interactive) {
+    options = await configureInteractiveInstall(options);
+  }
   const plan = buildInstallPlan(options);
   const conflicts = collectConflicts(plan);
   const unforceableConflicts = conflicts.filter((conflict) => !conflict.forceable);

package/src/cli/lib/install.js

@@ -8,13 +8,110 @@ const {
   statSync,
 } = require("node:fs");
 const path = require("node:path");
-const readline = require("node:readline/promises");
+const readline = require("node:readline");
 const { stdin, stdout } = require("node:process");
 
 const { CliError } = require("./errors");
 const { getPackageRoot, getPathType } = require("./runtime");
 
 const SUPPORTED_AGENTS = ["claude", "codex", "opencode", "pi"];
+const INSTALL_CATEGORIES = [
+  {
+    name: "agent-runtime",
+    description: ".agents runtime except skills",
+    matches: (target) => target.startsWith(".agents/") && !target.startsWith(".agents/skills/")
+  },
+  {
+    name: "skills",
+    description: ".agents/skills",
+    matches: (target) => target.startsWith(".agents/skills/")
+  },
+  {
+    name: "viewer",
+    description: ".delano viewer files",
+    matches: (target) => target.startsWith(".delano/")
+  },
+  {
+    name: "project-context",
+    description: ".project/context starter templates",
+    matches: (target) => target.startsWith(".project/context/")
+  },
+  {
+    name: "project-templates",
+    description: ".project/templates",
+    matches: (target) => target.startsWith(".project/templates/")
+  },
+  {
+    name: "project-registry",
+    description: ".project/registry",
+    matches: (target) => target.startsWith(".project/registry/")
+  },
+  {
+    name: "project-projects",
+    description: ".project/projects seed files",
+    matches: (target) => target.startsWith(".project/projects/")
+  },
+  {
+    name: "handbook",
+    description: "HANDBOOK.md",
+    matches: (target) => target === "HANDBOOK.md"
+  },
+  {
+    name: "legacy-installer",
+    description: "install-delano.sh",
+    matches: (target) => target === "install-delano.sh"
+  }
+];
+
+const INSTALL_CATEGORY_ALIASES = new Map([
+  ["agent-skills", "skills"],
+  ["agents", "agent-runtime"],
+  ["runtime", "agent-runtime"],
+  ["context", "project-context"],
+  ["templates", "project-templates"],
+  ["project-state", "project-projects"],
+  ["projects", "project-projects"],
+  ["registry", "project-registry"],
+  ["delano", "viewer"],
+  ["installer", "legacy-installer"]
+]);
+
+const INSTALL_CATEGORY_NAMES = INSTALL_CATEGORIES.map((category) => category.name);
+const PROJECT_STATE_CATEGORIES = ["project-context", "project-projects", "project-registry"];
+const INSTALL_PRESETS = [
+  {
+    id: "update-safe",
+    label: "Update Delano runtime, preserve project state",
+    description: "Refresh runtime files while excluding .project/context, .project/projects, and .project/registry.",
+    only: null,
+    exclude: PROJECT_STATE_CATEGORIES,
+    force: true
+  },
+  {
+    id: "skills-templates",
+    label: "Update skills and project templates",
+    description: "Refresh .agents/skills and .project/templates only.",
+    only: ["skills", "project-templates"],
+    exclude: [],
+    force: true
+  },
+  {
+    id: "full",
+    label: "Full install or repair",
+    description: "Install every allowlisted category. This includes project starter state.",
+    only: null,
+    exclude: [],
+    force: false
+  },
+  {
+    id: "custom",
+    label: "Choose categories",
+    description: "Pick exact categories and force behavior.",
+    only: null,
+    exclude: [],
+    force: false
+  }
+];
 
 function getMissingPackagedAssetMessage(relativePath) {
   return [
@@ -64,12 +161,47 @@ function parseAgentList(rawValue) {
   return selected;
 }
 
+function parseCategoryList(rawValue, optionName) {
+  if (!rawValue) {
+    throw new CliError(`Missing value for ${optionName}.`, 1);
+  }
+
+  const selected = [];
+  for (const chunk of rawValue.split(",")) {
+    const value = chunk.trim().toLowerCase();
+    if (!value) {
+      continue;
+    }
+
+    const categoryName = INSTALL_CATEGORY_ALIASES.get(value) || value;
+    if (!INSTALL_CATEGORY_NAMES.includes(categoryName)) {
+      throw new CliError(
+        `Unknown install category '${value}'. Supported values: ${INSTALL_CATEGORY_NAMES.join(", ")}.`,
+        1
+      );
+    }
+
+    if (!selected.includes(categoryName)) {
+      selected.push(categoryName);
+    }
+  }
+
+  if (selected.length === 0) {
+    throw new CliError(`No install categories selected for ${optionName}.`, 1);
+  }
+
+  return selected;
+}
+
 function parseInstallArgs(args) {
   const options = {
     target: process.cwd(),
     force: false,
     yes: false,
-    agents: [...SUPPORTED_AGENTS]
+    interactive: false,
+    agents: [...SUPPORTED_AGENTS],
+    only: null,
+    exclude: []
   };
 
   for (let index = 0; index < args.length; index += 1) {
@@ -103,6 +235,42 @@ function parseInstallArgs(args) {
       continue;
     }
 
+    if (arg === "--only") {
+      index += 1;
+      options.only = parseCategoryList(args[index], "--only");
+      continue;
+    }
+
+    if (arg.startsWith("--only=")) {
+      options.only = parseCategoryList(arg.slice("--only=".length), "--only");
+      continue;
+    }
+
+    if (arg === "--exclude") {
+      index += 1;
+      options.exclude = parseCategoryList(args[index], "--exclude");
+      continue;
+    }
+
+    if (arg.startsWith("--exclude=")) {
+      options.exclude = parseCategoryList(arg.slice("--exclude=".length), "--exclude");
+      continue;
+    }
+
+    if (arg === "--no-project-context") {
+      options.exclude = mergeCategoryLists(options.exclude, ["project-context"]);
+      continue;
+    }
+
+    if (arg === "--no-project-state") {
+      options.exclude = mergeCategoryLists(options.exclude, [
+        "project-context",
+        "project-projects",
+        "project-registry"
+      ]);
+      continue;
+    }
+
     if (arg === "--force") {
       options.force = true;
       continue;
@@ -113,6 +281,11 @@ function parseInstallArgs(args) {
       continue;
     }
 
+    if (arg === "--interactive" || arg === "--tui") {
+      options.interactive = true;
+      continue;
+    }
+
     throw new CliError(`Unknown install option: ${arg}`, 1);
   }
 
@@ -120,9 +293,170 @@ function parseInstallArgs(args) {
   return options;
 }
 
+function applyInstallPreset(options, presetId) {
+  const preset = INSTALL_PRESETS.find((candidate) => candidate.id === presetId);
+  if (!preset) {
+    throw new CliError(`Unknown install preset: ${presetId}`, 1);
+  }
+
+  return {
+    ...options,
+    only: preset.only ? [...preset.only] : null,
+    exclude: [...preset.exclude],
+    force: preset.force
+  };
+}
+
+async function configureInteractiveInstall(options) {
+  const prompt = createPrompter(stdin, stdout);
+  try {
+    console.log("Delano install");
+    console.log("==============");
+    console.log("");
+    console.log("Choose what to install:");
+    INSTALL_PRESETS.forEach((preset, index) => {
+      console.log(`  ${index + 1}. ${preset.label}`);
+      console.log(`     ${preset.description}`);
+    });
+    console.log("");
+
+    const presetAnswer = await prompt.ask("Selection [1]: ");
+    const presetIndex = parseSelectionNumber(presetAnswer, 1, INSTALL_PRESETS.length, 1) - 1;
+    const preset = INSTALL_PRESETS[presetIndex];
+    let configured = applyInstallPreset(options, preset.id);
+
+    const targetAnswer = await prompt.ask(`Target [${configured.target}]: `);
+    if (targetAnswer.trim()) {
+      configured.target = path.resolve(targetAnswer.trim());
+    }
+
+    if (preset.id === "custom") {
+      configured = await configureCustomInstallSelection(configured, prompt);
+    } else {
+      const forceDefault = configured.force ? "Y/n" : "y/N";
+      const forceAnswer = await prompt.ask(`Overwrite selected existing files with --force? [${forceDefault}] `);
+      configured.force = parseYesNo(forceAnswer, configured.force);
+    }
+
+    return configured;
+  } finally {
+    prompt.close();
+  }
+}
+
+async function configureCustomInstallSelection(options, prompt) {
+  console.log("");
+  console.log("Categories:");
+  INSTALL_CATEGORIES.forEach((category, index) => {
+    console.log(`  ${index + 1}. ${category.name} - ${category.description}`);
+  });
+  console.log("");
+  console.log("Enter category numbers or names separated by commas.");
+  console.log("Use 'all' for every category.");
+
+  const categoryAnswer = await prompt.ask("Categories [all]: ");
+  const only = parseInteractiveCategorySelection(categoryAnswer);
+  const forceAnswer = await prompt.ask("Overwrite selected existing files with --force? [y/N] ");
+
+  return {
+    ...options,
+    only,
+    exclude: [],
+    force: parseYesNo(forceAnswer, false)
+  };
+}
+
+function createPrompter(input, output) {
+  const rl = readline.createInterface({ input, crlfDelay: Infinity });
+  const iterator = rl[Symbol.asyncIterator]();
+
+  return {
+    async ask(promptText) {
+      output.write(promptText);
+      const next = await iterator.next();
+      const answer = next.done ? "" : next.value;
+      output.write("\n");
+      return answer;
+    },
+    close() {
+      rl.close();
+    }
+  };
+}
+
+
+function parseSelectionNumber(rawValue, min, max, defaultValue) {
+  const value = rawValue.trim();
+  if (!value) {
+    return defaultValue;
+  }
+
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+    throw new CliError(`Selection must be a number from ${min} to ${max}.`, 1);
+  }
+  return parsed;
+}
+
+function parseYesNo(rawValue, defaultValue) {
+  const value = rawValue.trim().toLowerCase();
+  if (!value) {
+    return defaultValue;
+  }
+  if (value === "y" || value === "yes") {
+    return true;
+  }
+  if (value === "n" || value === "no") {
+    return false;
+  }
+  throw new CliError("Answer must be yes or no.", 1);
+}
+
+function parseInteractiveCategorySelection(rawValue) {
+  const value = rawValue.trim();
+  if (!value || value.toLowerCase() === "all") {
+    return null;
+  }
+
+  const selected = [];
+  for (const chunk of value.split(",")) {
+    const token = chunk.trim();
+    if (!token) {
+      continue;
+    }
+
+    const numeric = Number(token);
+    const categoryName = Number.isInteger(numeric)
+      ? INSTALL_CATEGORIES[numeric - 1]?.name
+      : (INSTALL_CATEGORY_ALIASES.get(token.toLowerCase()) || token.toLowerCase());
+
+    if (!categoryName || !INSTALL_CATEGORY_NAMES.includes(categoryName)) {
+      throw new CliError(
+        `Unknown install category '${token}'. Supported values: ${INSTALL_CATEGORY_NAMES.join(", ")}.`,
+        1
+      );
+    }
+
+    if (!selected.includes(categoryName)) {
+      selected.push(categoryName);
+    }
+  }
+
+  if (selected.length === 0) {
+    throw new CliError("No install categories selected.", 1);
+  }
+
+  return selected;
+}
+
 function buildInstallPlan(options) {
   const { manifest, entries, payloadRoot } = readInstallManifest();
-  const items = entries.map((entry) => {
+  const selectedEntries = filterManifestEntries(entries, options);
+  if (selectedEntries.length === 0) {
+    throw new CliError("Install selection matched no files.", 1);
+  }
+
+  const items = selectedEntries.map((entry) => {
     const sourcePath = path.join(payloadRoot, entry.target);
     if (!existsSync(sourcePath)) {
       throw new CliError(getMissingPackagedAssetMessage(entry.target), 1);
@@ -137,11 +471,41 @@ function buildInstallPlan(options) {
 
   return {
     manifest,
+    selectedEntries,
+    skippedCount: entries.length - selectedEntries.length,
     items,
     targetRoot: options.target
   };
 }
 
+function mergeCategoryLists(left, right) {
+  const merged = [...left];
+  for (const item of right) {
+    if (!merged.includes(item)) {
+      merged.push(item);
+    }
+  }
+  return merged;
+}
+
+function getInstallCategory(target) {
+  const normalizedTarget = target.replace(/\\/g, "/");
+  return INSTALL_CATEGORIES.find((category) => category.matches(normalizedTarget))?.name || "uncategorized";
+}
+
+function filterManifestEntries(entries, options) {
+  const only = options.only ? new Set(options.only) : null;
+  const exclude = new Set(options.exclude || []);
+
+  return entries.filter((entry) => {
+    const category = getInstallCategory(entry.target);
+    if (only && !only.has(category)) {
+      return false;
+    }
+    return !exclude.has(category);
+  });
+}
+
 function collectConflicts(plan) {
   const conflicts = [];
 
@@ -191,10 +555,18 @@ function printPlanSummary(plan, options) {
   console.log("------------");
   console.log(`Target: ${options.target}`);
   console.log(`Files: ${plan.items.length}`);
+  if (plan.skippedCount > 0) {
+    console.log(`Skipped by selection: ${plan.skippedCount}`);
+  }
   console.log(`Agents: ${options.agents.join(", ")}`);
+  console.log(`Only: ${options.only ? options.only.join(", ") : "all categories"}`);
+  if (options.exclude.length > 0) {
+    console.log(`Exclude: ${options.exclude.join(", ")}`);
+  }
   console.log(`Force: ${options.force ? "yes" : "no"}`);
   console.log("");
   console.log("Note: --agents is accepted now for forward compatibility, but v1 base install still excludes top-level adapter entry docs by default.");
+  console.log("Note: .project/context, .project/projects, and .project/registry are repo-owned after install; use --no-project-state or --only for update-safe refreshes.");
 }
 
 function printConflicts(conflicts, options) {
@@ -211,7 +583,7 @@ function printConflicts(conflicts, options) {
   if (options.force) {
     console.error("Install cannot continue because at least one conflict is not forceable.");
   } else {
-    console.error("Install aborted before writing files. Re-run with --force to overwrite only allowlisted target paths.");
+    console.error("Install aborted before writing files. Re-run with --force to overwrite only selected allowlisted target paths, or narrow the plan with --only/--exclude.");
   }
 }
 
@@ -220,15 +592,15 @@ async function confirmInstall(plan, options) {
     return true;
   }
 
-  const rl = readline.createInterface({ input: stdin, output: stdout });
+  const prompt = createPrompter(stdin, stdout);
   try {
-    const prompt = options.force
+    const promptText = options.force
       ? `Proceed with force-installing ${plan.items.length} files into ${options.target}? [y/N] `
       : `Proceed with installing ${plan.items.length} files into ${options.target}? [y/N] `;
-    const answer = await rl.question(prompt);
+    const answer = await prompt.ask(promptText);
     return /^[Yy](es)?$/.test(answer.trim());
   } finally {
-    rl.close();
+    prompt.close();
   }
 }
 
@@ -294,12 +666,21 @@ function validateManifestPath(relativePath, fieldName) {
 }
 
 module.exports = {
+  INSTALL_CATEGORIES,
+  INSTALL_PRESETS,
   SUPPORTED_AGENTS,
   applyInstallPlan,
+  applyInstallPreset,
   buildInstallPlan,
   collectConflicts,
   confirmInstall,
+  configureInteractiveInstall,
+  createPrompter,
+  filterManifestEntries,
+  getInstallCategory,
   normalizeManifestEntries,
+  parseInteractiveCategorySelection,
+  parseCategoryList,
   parseAgentList,
   parseInstallArgs,
   printConflicts,