@iseoane/agent-depot 0.4.0 → 0.5.0

package/dist/src/tui/sources-view.js

@@ -6,6 +6,14 @@ import { rowStyle, theme } from "./theme.js";
 import { computeWindow, pageStep, useListHeight } from "./window.js";
 import { useKeys } from "./keys.js";
 import { useSourcesRecipes } from "./sources-recipes.js";
+/** Footer keys for the selected row; App seeds the footer before the view reports a selection. */
+export function sourceRowHints(row) {
+    if (row === undefined)
+        return "n add · q quit";
+    return row.kind === "app"
+        ? "j/k move · Enter preview/approve · n add · r refresh · d remove · q quit"
+        : "j/k move · space mark · a all · Enter catalog · n add · r refresh · d remove · q quit";
+}
 /** The highlighted index: by stable id while that source exists, otherwise the bounded fallback index. */
 function resolveIndex(sources, selection) {
     const found = sources.findIndex((source) => source.id === selection.id);
@@ -29,7 +37,7 @@ async function refreshEach(operations, targets) {
 function errorText(error) {
     return error instanceof Error ? error.message : String(error);
 }
-export function SourcesView({ operations, onCapturingChange, onOpenCatalog, listHeight, environment }) {
+export function SourcesView({ operations, onCapturingChange, onOpenCatalog, listHeight, environment, onHintsChange }) {
     const height = useListHeight(listHeight, 9);
     const [state, setState] = useState({ status: "loading" });
     // The highlight follows the source id; the index is only the fallback once that source is gone.
@@ -95,12 +103,28 @@ export function SourcesView({ operations, onCapturingChange, onOpenCatalog, list
     const sources = allSources.filter((source) => source.kind === "git");
     const sourcesRef = useRef(sources);
     sourcesRef.current = sources;
-    const selected = resolveIndex(sources, selection);
+    const rowsRef = useRef([]);
     const recipes = useSourcesRecipes({
-        operations, environment, onCapturingChange, height, gitCount: sources.length,
+        operations, environment, onCapturingChange,
+        highlightedFile: () => {
+            const rows = rowsRef.current;
+            const row = rows[resolveIndex(rows, selectionRef.current)];
+            return row?.kind === "app" ? row.recipe.entry.file : undefined;
+        },
     });
+    const rows = [
+        ...sources.map((source) => ({ id: source.id, kind: "skills", source })),
+        ...recipes.rows.map((recipe) => ({ id: `recipe:${recipe.entry.file}`, kind: "app", recipe })),
+    ];
+    rowsRef.current = rows;
+    const selected = resolveIndex(rows, selection);
+    const selectedRow = rows[selected];
+    const hints = sourceRowHints(selectedRow);
+    useEffect(() => { onHintsChange?.(hints); }, [hints, onHintsChange]);
     const select = (index) => {
-        const listed = sourcesRef.current;
+        setMessage(undefined);
+        recipes.clearMessage();
+        const listed = rowsRef.current;
         const bounded = Math.min(Math.max(index, 0), Math.max(listed.length - 1, 0));
         setSelection({ id: listed[bounded]?.id, index: bounded });
     };
@@ -164,6 +188,19 @@ export function SourcesView({ operations, onCapturingChange, onOpenCatalog, list
         const mode = modeRef.current;
         if (mode.kind === "busy")
             return;
+        if (mode.kind === "add-kind") {
+            if (key.escape || input === "n")
+                dispatch({ type: "done" });
+            else if (input === "1") {
+                typed.current = "";
+                dispatch({ type: "input" });
+            }
+            else if (input === "2") {
+                dispatch({ type: "done" });
+                recipes.startAdd();
+            }
+            return;
+        }
         if (mode.kind === "input") {
             if (key.escape)
                 dispatch({ type: "done" });
@@ -205,14 +242,13 @@ export function SourcesView({ operations, onCapturingChange, onOpenCatalog, list
                 dispatch({ type: "done" });
             return;
         }
-        if (recipes.handleKey(input, key)) {
-            if (key.tab)
-                setMessage(undefined);
+        if (recipes.handleKey(input, key))
             return;
-        }
+        const rows = rowsRef.current;
+        const at = resolveIndex(rows, selectionRef.current);
+        const row = rows[at];
         const listed = sourcesRef.current;
-        const at = resolveIndex(listed, selectionRef.current);
-        const highlighted = listed[at];
+        const highlighted = row?.kind === "skills" ? row.source : undefined;
         if (key.downArrow || input === "j") {
             select(at + 1);
         }
@@ -220,24 +256,23 @@ export function SourcesView({ operations, onCapturingChange, onOpenCatalog, list
             select(at - 1);
         }
         else if (key.pageDown) {
-            select(at + pageStep(recipes.gitHeight));
+            select(at + pageStep(height));
         }
         else if (key.pageUp) {
-            select(at - pageStep(recipes.gitHeight));
+            select(at - pageStep(height));
         }
         else if (key.return && highlighted) {
             onOpenCatalog?.(highlighted);
         }
         else if (input === "n") {
             setMessage(undefined);
-            typed.current = "";
-            dispatch({ type: "input" });
+            dispatch({ type: "add-kind" });
         }
         else if (input === " " && highlighted) {
             setMessage(undefined);
             toggle([highlighted.id]);
         }
-        else if (input === "a") {
+        else if (input === "a" && row?.kind !== "app") {
             if (listed.length === 0)
                 stop("There are no Git sources to select");
             else {
@@ -245,7 +280,7 @@ export function SourcesView({ operations, onCapturingChange, onOpenCatalog, list
                 toggle(listed.map((source) => source.id));
             }
         }
-        else if (input === "r") {
+        else if (input === "r" && row?.kind !== "app") {
             const targets = markedRef.current.size > 0
                 ? listed.filter((source) => markedRef.current.has(source.id))
                 : highlighted ? [highlighted] : [];
@@ -264,13 +299,16 @@ export function SourcesView({ operations, onCapturingChange, onOpenCatalog, list
         return _jsx(Text, { children: "Loading sources..." });
     if (state.status === "error")
         return _jsxs(Text, { color: theme.error, children: ["Error: ", state.message] });
-    const window = computeWindow(sources.length, selected, recipes.gitHeight);
-    return (_jsxs(Box, { flexDirection: "column", children: [builtin ? _jsxs(Text, { color: theme.muted, children: ["    ", builtin.id, " \u00B7 included"] }) : null, sources.length === 0 ? _jsx(Text, { children: "No Git sources \u00B7 n to add" }) : null, sources.length > 0 ? _jsxs(Text, { color: theme.muted, children: ["      ", "ID  KIND  URL"] }) : null, sources.slice(window.start, window.end).map((source, offset) => {
+    const window = computeWindow(rows.length, selected, height);
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { color: theme.muted, children: ["      ", "ID  KIND  LOCATION / STATUS"] }), builtin ? _jsxs(Text, { color: theme.muted, children: ["    ", builtin.id, "  skills  included"] }) : null, rows.length === 0 ? _jsx(Text, { children: "No sources or App recipes \u00B7 n to add" }) : null, rows.slice(window.start, window.end).map((row, offset) => {
                 const index = window.start + offset;
-                return (_jsxs(Text, { ...rowStyle(!recipes.focused && index === selected), children: [!recipes.focused && index === selected ? "> " : "  ", marked.has(source.id) ? "[x] " : "[ ] ", source.id, "  ", source.kind, "  ", source.url] }, source.id));
+                const id = row.kind === "skills" ? row.source.id : row.recipe.entry.recipe?.name ?? row.recipe.entry.file.split(/[\\/]/u).pop();
+                return (_jsxs(Text, { ...rowStyle(index === selected), children: [index === selected ? "> " : "  ", row.kind === "skills" ? (marked.has(row.id) ? "[x] " : "[ ] ") : "    ", id, "  ", row.kind, "  ", row.kind === "skills" ? row.source.url : `${row.recipe.entry.file} · ${row.recipe.status}`] }, row.id));
             }), window.indicator ? _jsx(Text, { color: theme.muted, children: window.indicator }) : null, selectedCount > 0 ? _jsxs(Text, { children: [selectedCount, " selected"] }) : null, recipes.panel, _jsx(Prompt, { mode: mode }), message ? _jsx(Text, { color: message.kind === "error" ? theme.error : theme.success, children: message.text }) : null] }));
 }
 function Prompt({ mode }) {
+    if (mode.kind === "add-kind")
+        return _jsx(Text, { children: "Add: 1 Git Source (skills + Packages) \u00B7 2 App recipe (Esc cancel)" });
     if (mode.kind === "input")
         return _jsxs(Text, { children: ["URL: ", mode.value] });
     if (mode.kind === "busy")

package/dist/src/tui/tree.js

@@ -1,7 +1,6 @@
-/** Initially only the first group with children is open; every other group starts collapsed. */
-export function defaultExpanded(roots) {
-    const first = roots.find((root) => (root.children?.length ?? 0) > 0);
-    return new Set(first ? [first.id] : []);
+/** Every group starts collapsed until the user expands it. */
+export function defaultExpanded() {
+    return new Set();
 }
 /** The visible nodes in display order: children appear only under expanded parents. */
 export function flattenVisible(roots, expanded) {

package/dist/src/tui/updates-flow.js

@@ -81,9 +81,12 @@ export function useUpdatesFlow(inputs) {
         }
         if (!mounted.current)
             return;
-        setMessage(result);
         // The sources were fetched for the check that was just applied; only the installations changed.
+        // The summary lands with the refreshed list, so no check is still writing when the view reports done.
         await load(false);
+        if (!mounted.current)
+            return;
+        setMessage(result);
     };
     return { state, load, startPreview, apply };
 }

package/dist/src/tui/updates-panel.js

@@ -7,7 +7,7 @@ import { PreviewLines } from "./panel-parts.js";
 /** What the last check found out: its age, how the sources were refreshed, and what failed. */
 export function CheckStatus({ data, now }) {
     const errors = data.results.filter((result) => result.error !== undefined);
-    return (_jsxs(_Fragment, { children: [_jsxs(Text, { color: theme.muted, children: ["checked ", formatAgo(now - data.checkedAt), " \u00B7 ", describeRefresh(data)] }), data.refresh.failed.map((failure) => (_jsxs(Text, { color: theme.warning, children: ["refresh failed for ", failure.source, ": ", failure.reason] }, failure.source))), data.appError ? _jsxs(Text, { color: theme.error, children: ["Error (Apps): ", data.appError] }) : null, errors.map((result) => _jsxs(Text, { color: theme.error, children: ["Error (", result.scope, "): ", result.error] }, result.scope))] }));
+    return (_jsxs(_Fragment, { children: [_jsxs(Text, { color: theme.muted, children: ["checked ", formatAgo(now - data.checkedAt), " \u00B7 ", describeRefresh(data)] }), data.refresh.failed.map((failure) => (_jsxs(Text, { color: theme.warning, children: ["refresh failed for ", failure.source, ": ", failure.reason] }, failure.source))), data.appError ? _jsxs(Text, { color: theme.error, children: ["Error (Apps): ", data.appError] }) : null, data.packageError ? _jsxs(Text, { color: theme.error, children: ["Error (Packages): ", data.packageError] }) : null, errors.map((result) => _jsxs(Text, { color: theme.error, children: ["Error (", result.scope, "): ", result.error] }, result.scope))] }));
 }
 /** One line of the list: an update, the fold of unassessable items, or one of those when unfolded. */
 export function EntryLine({ entry, selected, checked, view, showUnknown }) {
@@ -35,7 +35,7 @@ export function ModePanel({ mode }) {
         case "busy":
             return mode.label === REFRESHING || mode.label === CHECKING ? null : _jsx(Text, { children: mode.label });
         case "preview":
-            return (_jsxs(Box, { flexDirection: "column", children: [_jsx(PreviewLines, { lines: mode.prepared.lines }), _jsx(PreviewLines, { lines: mode.prepared.appFailures }), mode.prepared.failures.map(({ item, message }) => (_jsxs(Text, { color: theme.error, children: ["Preview failed for ", JSON.stringify(item.id), ": ", message] }, item.id))), mode.prepared.applicable.length === 0
+            return (_jsxs(Box, { flexDirection: "column", children: [_jsx(PreviewLines, { lines: mode.prepared.lines }), _jsx(PreviewLines, { lines: mode.prepared.appFailures }), _jsx(PreviewLines, { lines: mode.prepared.packageFailures }), mode.prepared.failures.map(({ item, message }) => (_jsxs(Text, { color: theme.error, children: ["Preview failed for ", JSON.stringify(item.id), ": ", message] }, item.id))), mode.prepared.applicable.length === 0
                         ? _jsx(Text, { children: "Nothing can be applied. Enter/Esc to go back" })
                         : _jsxs(Text, { children: ["Apply ", mode.prepared.applicable.length, " ", mode.prepared.applicable.length === 1 ? "update" : "updates", "? y/n"] })] }));
         case "confirm-paths":

package/dist/src/tui/updates.js

@@ -1,7 +1,10 @@
 import { checkAppUpdates, createAppOperations } from "../app-flow.js";
+import { describeCoordinates, selectionKey } from "../package-model.js";
 import { formatVersionPolicy } from "../skill-install.js";
 import { applyConfirmedUpdates, describeUpdatePreview, loadUpdates, previewUpdateCandidates, readScopeInstallations, } from "../update-flow.js";
+import { packageOperationsOf } from "./environment.js";
 import { formatVersionEvidence } from "./installations.js";
+import { installedEvidenceLabel, packagePlanLines, packageStatusLabel, packageVersionLabel, recordedVersionLabel } from "./package-rows.js";
 /** Every scope the view can assess, in display order. */
 export const UPDATE_SCOPES = ["project", "user-global"];
 const APP_STATUS_LABEL = {
@@ -68,6 +71,7 @@ async function refreshSources(operations, selections) {
  */
 export async function loadUpdateRows(operations, environment, options) {
     const apps = createAppOperations({ homeDirectory: environment.homeDirectory, ...environment.appEnvironment });
+    const packages = packageOperationsOf(environment);
     let refresh = { attempted: false, refreshed: [], failed: [], unreadable: [] };
     if (options.refresh) {
         options.onPhase?.("refreshing");
@@ -121,7 +125,29 @@ export async function loadUpdateRows(operations, environment, options) {
             reason: check.reason ?? check.inspection.reason ?? check.inspection.status,
         });
     }
-    return { results, rows, refresh, apps, appError, checkedAt: (options.now ?? Date.now)() };
+    let packageChecks = [];
+    let packageError;
+    try {
+        packageChecks = await packages.checkUpdates();
+    }
+    catch (error) {
+        packageError = errorText(error);
+    }
+    for (const check of packageChecks) {
+        rows.push({
+            kind: "package",
+            key: `package:${selectionKey(check.installed.selection)}`,
+            scope: "user-global",
+            check,
+            path: `Package: ${describeCoordinates(check.installed.selection)}`,
+            policy: formatVersionPolicy(check.installed.selection.version),
+            installed: recordedVersionLabel(check.installed),
+            available: check.available === undefined ? "?" : packageVersionLabel(check.available),
+            status: packageStatusLabel(check.status),
+            reason: check.reason ?? "the host reports no usable version evidence",
+        });
+    }
+    return { results, rows, refresh, apps, packages, appError, packageError, checkedAt: (options.now ?? Date.now)() };
 }
 /** `just now`, `42s ago`, `5 min ago`, `2 h ago`. */
 export function formatAgo(elapsedMs) {
@@ -140,10 +166,12 @@ export async function prepareUpdates(data, selected) {
     const groups = [];
     const appPlans = [];
     const appFailures = [];
+    const packagePlans = [];
+    const packageFailures = [];
     const lines = [];
     const failures = [];
     for (const { scope, loaded } of data.results) {
-        const items = selected.filter((row) => row.kind !== "app" && row.scope === scope).map((row) => row.item);
+        const items = selected.filter((row) => row.kind !== "app" && row.kind !== "package" && row.scope === scope).map((row) => row.item);
         if (!loaded || items.length === 0)
             continue;
         const { context } = loaded;
@@ -164,16 +192,32 @@ export async function prepareUpdates(data, selected) {
         try {
             const plan = await data.apps.planLifecycle(row.check.entry, "update", undefined, row.check);
             appPlans.push(plan);
-            lines.push(`Environment: ${plan.environment}`, row.path, `Version: ${plan.previousVersion} -> ${plan.latestVersion ?? "unknown"}`, ...(plan.argv ? [`argv: ${JSON.stringify(plan.argv)}`, `Executable: ${plan.executable ?? "unavailable"}`] : []), ...(plan.manual ? [`Manual: ${plan.manual}`] : []), `Working directory: ${plan.cwd}`, ...(plan.warning ? [plan.warning] : []));
+            lines.push(`Environment: ${plan.environment}`, row.path, `Version: ${plan.previousVersion} -> ${plan.latestVersion ?? "unknown"}`, ...(plan.argv ? [`argv: ${JSON.stringify(plan.argv)}`, `Executable: ${plan.executable ?? `${JSON.stringify(plan.argv[0])} not found in PATH`}`] : []), ...(plan.manual ? [`Manual: ${plan.manual}`] : []), `Working directory: ${plan.cwd}`, ...(plan.warning ? [plan.warning] : []));
         }
         catch (error) {
             appFailures.push(`Failed ${row.path}: preview failed: ${errorText(error)}`);
         }
     }
+    for (const row of selected) {
+        if (row.kind !== "package" || !data.packages)
+            continue;
+        try {
+            const plan = await data.packages.planLifecycle(row.check.installed.selection, "update");
+            const approval = await data.packages.approvalStatus(row.check.installed.selection, "update");
+            packagePlans.push({ plan, approval });
+            lines.push(...packagePlanLines(plan, approval));
+            if (approval === "needs approval")
+                lines.push("This apply approves the declaration above.");
+        }
+        catch (error) {
+            packageFailures.push(`Failed ${row.path}: preview failed: ${errorText(error)}`);
+        }
+    }
     return {
         groups, apps: data.apps, appPlans, appFailures,
+        packages: data.packages, packagePlans, packageFailures,
         lines,
-        applicable: [...groups.flatMap((group) => group.applicable), ...appPlans],
+        applicable: [...groups.flatMap((group) => group.applicable), ...appPlans, ...packagePlans.map(({ plan }) => plan)],
         failures,
         nonCanonicalPaths: groups.flatMap((group) => group.nonCanonicalPaths.map((location) => ({ scope: group.scope, path: location }))),
     };
@@ -220,7 +264,31 @@ export async function runUpdates(prepared, confirmedPaths, confirmManual) {
             failedLines.push(`Failed ${name}: ${errorText(error)}`);
         }
     }
+    for (const { plan, approval } of prepared.packagePlans ?? []) {
+        const name = `Package: ${plan.descriptor.name} (${plan.selection.host})`;
+        try {
+            const packages = prepared.packages;
+            if (!packages)
+                throw new Error("Package operations unavailable; check again");
+            if (approval === "needs approval")
+                await packages.approve(plan.selection, plan.action);
+            const result = await packages.executeLifecycle(plan, true);
+            if (result.status === "updated") {
+                updated.push(`Updated ${name}: ${installedEvidenceLabel(result.previous)} -> ${installedEvidenceLabel(result.verified)}`);
+            }
+            else if (result.status === "failed" || result.status === "stale plan" || result.status === "manual required") {
+                failedLines.push(`Failed ${name}: ${result.reason}`);
+            }
+            else {
+                failedLines.push(`Failed ${name}: unexpected result ${JSON.stringify(result.status)}`);
+            }
+        }
+        catch (error) {
+            failedLines.push(`Failed ${name}: ${errorText(error)}`);
+        }
+    }
     failedLines.push(...prepared.appFailures);
+    failedLines.push(...prepared.packageFailures);
     const previewFailed = prepared.failures.map(({ item, message }) => `Failed ${item.selection.path}: preview failed: ${message}`);
     const failed = failedLines.length + previewFailed.length;
     return {

package/dist/src/user-global-skill-inventory.js

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import path from "node:path";
 import { assertSkillNotAppOwned, loadAppOwnedSkillFilter } from "./app-owned-skills.js";
+import { assertSkillNotPackageOwned, loadPackageOwnedSkillFilter, } from "./package-owned-skills.js";
 import { pathsOverlap } from "./path-safety.js";
 import { readExistingSkillTree } from "./skill-adoption.js";
 import { parseSkillFrontmatter, skillTreeBaseline } from "./skill-discovery.js";
@@ -51,7 +52,9 @@ export async function scanUserGlobalSkillInventory(options = {}) {
     const exposures = [];
     const symlinks = [];
     const isAppOwned = await loadAppOwnedSkillFilter({ ...options, homeDirectory });
-    const state = { isAppOwned, managedPaths, managedCanonicalPaths, entries, skipped, exposures, symlinks };
+    const owned = await loadPackageOwnedSkillFilter({ ...options, homeDirectory });
+    const isPackageOwned = (name) => owned(name) !== undefined;
+    const state = { isAppOwned, isPackageOwned, managedPaths, managedCanonicalPaths, entries, skipped, exposures, symlinks };
     for (const root of GLOBAL_SKILL_ROOTS) {
         const rootPath = path.join(homeDirectory, ...root.relativePath);
         await scanRoot(root, rootPath, homeDirectory, state);
@@ -108,7 +111,7 @@ async function listScannableRoot(root, rootPath, homeDirectory, skipped) {
 }
 async function scanRootEntry(root, name, candidatePath, homeDirectory, state) {
     const { managedPaths, entries, skipped } = state;
-    if (!managedPaths.has(pathKey(candidatePath)) && state.isAppOwned(name))
+    if (!managedPaths.has(pathKey(candidatePath)) && (state.isAppOwned(name) || state.isPackageOwned(name)))
         return;
     if (isTransientName(name)) {
         skipped.push({ name, path: candidatePath, root: root.kind, reason: "excluded-transient" });
@@ -293,6 +296,7 @@ export async function inspectUserGlobalSkillRemoval(candidatePath, options) {
     const homeDirectory = path.resolve(options.homeDirectory);
     const targetPath = validateExplicitGlobalPath(candidatePath, homeDirectory);
     await assertSkillNotAppOwned(path.basename(candidatePath), options);
+    assertSkillNotPackageOwned(path.basename(candidatePath), await loadPackageOwnedSkillFilter({ ...options, homeDirectory }));
     const fileSystem = options.fileSystem ?? nodeFileSystem;
     await assertRealGlobalAncestors(homeDirectory, path.dirname(targetPath), fileSystem);
     const managedPaths = managedProtectionPaths(homeDirectory, options.managedInstallations);
@@ -388,6 +392,7 @@ export async function inspectUserGlobalSymlinkRemoval(candidatePath, options) {
     const homeDirectory = path.resolve(options.homeDirectory);
     const linkPath = validateExplicitGlobalPath(candidatePath, homeDirectory);
     await assertSkillNotAppOwned(path.basename(candidatePath), options);
+    assertSkillNotPackageOwned(path.basename(candidatePath), await loadPackageOwnedSkillFilter({ ...options, homeDirectory }));
     const fileSystem = options.fileSystem ?? nodeFileSystem;
     await assertRealGlobalAncestors(homeDirectory, path.dirname(linkPath), fileSystem);
     const managedPath = managedProtectionPaths(homeDirectory, options.managedInstallations)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iseoane/agent-depot",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A cross-platform catalog for reusable coding-agent skills.",
   "license": "MIT",
   "author": "iseoane",
@@ -30,6 +30,7 @@
     "!skills/**/test_*.py",
     "!skills/**/testdata",
     "README.md",
+    "README.es.md",
     "LICENSE",
     "CHANGELOG.md"
   ],

package/skills/agent-depot-apprecipe/SKILL.md

@@ -4,7 +4,7 @@ description: "Trigger: App recipe creation or repair. Research an App's actual i
 license: MIT
 metadata:
   author: "iseoane"
-  version: "1.0"
+  version: "1.2"
 ---
 
 ## Activation Contract
@@ -17,7 +17,8 @@ Use for creating or repairing user-global App recipes, not portable Skills.
 - Write user-owned JSON in the environment-local `apps/` beside `sources.json`. Preserve existing files unless the user authorizes replacement. Keep Apps out of Sources and project manifests.
 - Never approve a recipe on the user's behalf. Approval belongs to the user via `agent-depot app approve <name> --yes`; changed bytes need renewed approval. Validation is not approval.
 - Use bare executable-plus-arguments arrays, without shells, shell syntax, credentials or environment assignments. Script-only routes (`curl | sh`, PowerShell scripts, `.cmd`) belong in `manual` text, never pipe-to-shell argv. Agent Depot displays manual text without executing it.
-- Steps run from the user's home with stdin EOF and no timeout. Use non-interactive flags; terminal-dependent installers belong in manual steps.
+- Steps run from the user's home with stdin EOF and no timeout. Verify non-interactive behavior against the installed installer's help/version, not just an upstream quickstart. Use supported non-interactive flags; terminal-dependent installers belong in manual steps.
+- Preflight the chosen channel before writing lifecycle steps. Missing prerequisites must be declared, never silently installed, configured or trusted. Recipe approval does not authorize separate prerequisite installation.
 
 ## Decision Gates
 
@@ -30,15 +31,38 @@ Use for creating or repairing user-global App recipes, not portable Skills.
 | brew / npm / pipx | Derive update and uninstall from that channel: upgrade/uninstall, global install/uninstall, or upgrade/uninstall respectively. |
 | Go install / release binary | Use the documented update route and a manual binary-removal step. |
 | App has its own uninstall | Prefer it after verifying scope and non-interactive flags; explain remaining channel cleanup. |
+| Missing manager, runtime, PATH entry, repository/tap, permissions or hook dependency | Explain the blocker and preparation before approval. Use a complete manual route or ask whether the user wants an explicitly prerequisite-dependent recipe; never call it ready to install. |
+| Installer needs several commands | Use schema-supported ordered steps only if present. Otherwise put the complete sequence in `manual` or obtain the user's explicit choice of the prerequisite-dependent route below; never invent dependency fields, concatenate commands in argv, or hide preparation in a fallback. |
+
+## Installer Preflight
+
+Check installation **and** update, uninstall, version/latest and each Host setup/teardown. Record evidence as satisfied, missing or unverified:
+
+- **Executable and environment:** inspect all manager/runtime PATH matches, resolved paths and versions in the environment Agent Depot actually inherits. A shell alias/function is not a spawnable executable. A terminal's PATH change does not reach an already-running TUI; tell the user to relaunch it from the prepared environment. Prefer read-only checks; do not create shims or edit shell configuration merely to make validation pass.
+- **Channel registration and trust:** inspect required taps, repositories, registries and plugin marketplaces, their identities and current package metadata. Verify whether this installer version auto-registers them or requires explicit preparation; do not assume historical behavior. Report missing registration before writing argv. Registration can clone repositories and execute package definitions: do not run it as a supposedly read-only probe or without user authorization.
+- **Runtime/build and hook requirements:** verify documented engine ranges, compiler/toolchain minimums, architecture/libc support and utilities such as `git`, `curl`, `jq` or extraction tools. Check write access to the actual global prefix and required elevation; never assume sudo or request credentials in chat. Inspect prerequisites for Host plugins separately from the App binary.
+- **Unattended behavior:** use installed manager `--help`/documented help and upstream installer source to establish confirmation defaults and supported flags. Verify explicit formula/cask or package disambiguation where necessary. Do not invent `--yes` flags or rely on stdin EOF to count as consent. Run dry-run/read-only probes only after checking they do not install, register, authenticate or rewrite configuration; never test a lifecycle command just to see whether it prompts.
+- **Version and update signals:** verify a release-meaningful version (not an unchanged `dev`) and a latest signal for the chosen channel. A GitHub release can be ahead of a package-manager formula. Use channel metadata when available and disclose freshness limits; do not run `brew update` or another mutating refresh as a read-only latest probe.
+- **Preserved state:** identify existing binary copies, data directories and Host wiring without reading private memory content. Explain migrations, backups and teardown scope outside executable argv where appropriate; never delete user data or remove a shared tap/marketplace implicitly.
+
+### Homebrew checklist
+
+Inspect `brew --version`, `brew help install`, `brew help upgrade`, `brew help uninstall`, `brew tap` and `brew list --versions`. Resolve `brew` from Agent Depot's PATH. Check the actual tap formula/cask and its release rather than trusting a possibly stale README. Homebrew auto-updates taps only for `install`, `outdated`, `upgrade`, `bundle`, `release` and `tap <name>`, never `info`, so `brew info --json=v2 <tap>/<formula>` reports the local clone's last refresh and lags a published release. When the tap mirrors a GitHub release, declare `latest` as `{"github": "owner/repo"}`; install and upgrade refresh the tap themselves. Use supported non-interactive flags for install/update and `--formula` or `--cask` when names conflict. Do not assume `brew install owner/tap/name` registers a missing tap automatically.
+
+For example, Homebrew 7.0.8 encountered during recipe research required an explicit `brew tap gentleman-programming/tap`; its install help documented ask-by-default and `--yes`. This is version-specific evidence, not a universal flag or a claim about when the behavior changed. Recheck the user's installed version.
+
+### Representing preparation
+
+Read the current schema; do not assume it has dependency or multi-command fields. When a required tap is missing and a lifecycle step accepts only one argv, `install.manual` can describe both registration and installation. Alternatively, with the user's explicit choice, retain automated install as prerequisite-dependent and provide the preparation commands and blocked status clearly in the handoff. An `argv` plus `manual` step falls back **only on spawn failure**: it cannot perform preparation before argv and does not handle a non-zero exit. Keep manual text concise; put research and caveats in the handoff. Never approve either route on the user's behalf. Execute preparation only with separate user authorization; execute recipe commands only after user approval and an explicit execution request.
 
 ## Execution Steps
 
 1. Record upstream evidence and platform support. Inspect all PATH matches (`which -a`/`whence -a`, or Windows `Get-Command -All`), resolved paths, and channel inventories such as `brew list`, `npm ls -g` or `pipx list`. List Windows shims seen from WSL separately: `/mnt/<drive>/` executables cannot serve a Linux recipe. Finish only when the actual channel is established or the user has chosen one.
-2. Write required `name`, `install`, `update`, `uninstall`, and `version`. Each lifecycle step uses `argv`, `manual`, or both; manual fallback applies only to spawn failure, never non-zero exit. `version` needs read-only argv and a JavaScript regex with exactly one capture group. Choose optional `latest` as `github: owner/repo`, `npm: package`, or read-only `argv` plus `pattern`; omit it when unknown. Consult [the illustrative example](assets/example.md), not as upstream command evidence.
+2. Complete the Installer Preflight and resolve the prerequisite decision gate before writing required `name`, `install`, `update`, `uninstall`, and `version`. Each lifecycle step uses `argv`, `manual`, or both; manual fallback applies only to spawn failure, never non-zero exit. `version` needs read-only argv and a JavaScript regex with exactly one capture group. Choose optional `latest` as `github: owner/repo`, `npm: package`, or read-only `argv` plus `pattern`; omit it when unknown. Consult [the illustrative example](assets/example.md), not as upstream command evidence.
 3. Put user-global Host wiring in optional `setup`/`teardown` maps keyed by `pi`, `claude`, `codex`, or `opencode`. Keep install separate; uninstall never implicitly runs teardown. Delegate wiring to App commands or manual user instructions, not direct agent edits of Host configuration. Exclude project initialization.
 4. Declare optional `skills` only for documented App-owned directory/link names. Match whole names case-sensitively; only `*` is special, while `?` and brackets are literal. Reject empty/whitespace-only, path separators, NUL and star-only patterns. These declarations filter unmanaged adoption/removal even before approval/install; they verify no artifacts or provenance.
-5. Run `agent-depot app validate <file>...` for current-platform recipes. Fix structural errors; report unapproved recipes as needs approval, not runtime-verified. Version commands run only for approved applicable content. Mark other platforms unverified. After user approval, the user can inspect `app list` and separately preview `app install|update|uninstall <name>` or `app setup|teardown <name> --host <host>`.
+5. Run `agent-depot app validate <file>...` for current-platform recipes. Fix structural errors; report unapproved recipes as needs approval, not runtime-verified. Distinguish structural validity, recipe approval, prerequisite readiness, installed version and Host wiring; none proves the others. A known missing prerequisite remains a blocker even when validation succeeds. Version commands run only for approved applicable content. Mark other platforms unverified. After user approval, the user can inspect `app list` and separately preview `app install|update|uninstall <name>` or `app setup|teardown <name> --host <host>`.
 
 ## Output Contract
 
-Return file paths, platform/channel evidence, validation results and runtime-verification limits; unsupported platforms; omitted optional fields and why; license, telemetry/update-check behavior (or unknown); and conflicting duplicate install routes, including plugin-marketplace versus setup routes. Explain that version alone determines installed state, updates require a changed version, and unknown latest is not an available update. End with the user's approval command, without running it.
+Return file paths, platform/channel evidence, a concise prerequisite status (satisfied/missing/unverified) with preparation commands and whether the recipe is ready or blocked, validation results and runtime-verification limits; unsupported platforms; omitted optional fields and why; license, telemetry/update-check behavior (or unknown); and conflicting duplicate install routes, including plugin-marketplace versus setup routes. Explain that version alone determines installed state, updates require a changed version, and unknown latest is not an available update. End with the user's approval command, without running it.