create-agent-rig 0.3.1 → 0.4.0

package/packages/cli/dist/commands/upgrade.js

@@ -0,0 +1,300 @@
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { initInstallSet, projectNameFor } from './init.js';
+import { loadHashHistory, presentInEveryRelease } from '../lib/history.js';
+import { agentOsInstallSet, agentOsLayerDirs } from '../lib/install-set.js';
+import { listTree } from '../lib/copy-tree.js';
+import { readManifest, sha256, writeManifest } from '../lib/manifest.js';
+import { resolveInside } from '../lib/safe-path.js';
+import { detokenizeContent, substituteFileName } from '../lib/substitute.js';
+import { TARGETS } from '../lib/targets.js';
+import { packageVersion } from '../lib/version.js';
+/** A user-facing failure: message is printed as-is, no stack trace. */
+export class UpgradeError extends Error {
+}
+const SETTINGS = '.claude/settings.json';
+/** The universal layer's architecture group — installed by `create`, never by `init`. */
+const ARCHITECTURE_ONLY = [
+    '.claude/rules/architecture.md',
+    '.claude/hooks/guard-core-purity.mjs',
+    '.claude/hooks/guard-web-boundary.mjs',
+];
+async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where `rel` lives inside the rig — refused outright if it lands anywhere
+ * else. Nothing should be able to produce such a path once the manifest is
+ * validated, which is exactly why this stays: the whole command is writes into
+ * somebody's repository, and a containment check is cheap next to the cost of
+ * being wrong about that.
+ */
+function onDisk(repoDir, rel) {
+    const dest = resolveInside(repoDir, rel);
+    if (dest === null) {
+        throw new UpgradeError(`Refusing to touch "${rel}" — it resolves outside ${repoDir}.`);
+    }
+    return dest;
+}
+/**
+ * The file's bytes, or `null` when it is genuinely **absent**.
+ *
+ * Only "not there" is absence. Any other failure — a permission, a directory
+ * where a file should be, a path this command refuses to touch — is rethrown,
+ * because "I could not read your file" must never become "so I wrote mine over
+ * it": every caller of this treats `null` as grounds to install.
+ */
+async function readIfPresent(repoDir, rel) {
+    try {
+        return await readFile(onDisk(repoDir, rel), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+/** Every stack overlay any target composes — the candidates a rig can carry. */
+function knownStacks() {
+    return [...new Set(Object.values(TARGETS).flatMap((t) => t.stacks))];
+}
+/**
+ * What a rig with no manifest looks like it is, from the files it has.
+ *
+ * Two signals, because one file is too thin a thread to hang a project's map
+ * on: the architecture rules and hooks, which `create` installs and `init`
+ * deliberately does not, **and** any stack-overlay file at all — `init`
+ * composes no overlays, so one of those is proof on its own. The region comes
+ * from the target whose stack set matches; it is the only value substitution
+ * needs that the directory name cannot give.
+ *
+ * 🔴 Limit: a `create` rig that deleted every architecture file *and* every
+ * stack file reads as an `init` rig. It is then offered the `init` flavour of
+ * `CLAUDE.md` — a map of a different project shape. Nothing but a manifest
+ * distinguishes those two rigs, which is why 0.4.0 writes one.
+ */
+async function detectInstall(repoDir) {
+    const ctx = { projectName: '', projectScope: '', region: '' };
+    const stacks = [];
+    for (const stack of knownStacks()) {
+        const [layer] = agentOsLayerDirs([stack]).slice(1);
+        if (layer === undefined)
+            continue;
+        const rels = await listTree(layer.dir, {
+            transformName: (name) => substituteFileName(name, ctx),
+        });
+        for (const rel of rels) {
+            if (await exists(onDisk(repoDir, rel))) {
+                stacks.push(stack);
+                break;
+            }
+        }
+    }
+    let architectural = stacks.length > 0;
+    for (const rel of ARCHITECTURE_ONLY) {
+        if (architectural)
+            break;
+        architectural = await exists(onDisk(repoDir, rel));
+    }
+    if (!architectural)
+        return { kind: 'init', stacks: [], region: '' };
+    const target = Object.values(TARGETS).find((t) => t.stacks.length === stacks.length && t.stacks.every((s) => stacks.includes(s)));
+    return { kind: 'create', stacks, region: target?.defaultRegion ?? '' };
+}
+async function installSetFor(repoDir, kind, project, stacks) {
+    if (kind === 'init')
+        return initInstallSet(repoDir, project);
+    return agentOsInstallSet(stacks, {
+        projectName: project.name,
+        projectScope: project.scope,
+        region: project.region,
+    });
+}
+/**
+ * Whether these bytes are a released version of this file.
+ *
+ * Two candidates are offered to the table: the bytes as they sit, and the
+ * bytes with the project's own values turned back into tokens — released
+ * template bytes carry `__PROJECT_NAME__`, installed bytes never do.
+ */
+function isReleasedVersion(history, rel, content, ctx) {
+    const known = history.files[rel];
+    if (known === undefined || known.hashes.length === 0)
+        return false;
+    const candidates = new Set([sha256(content), sha256(detokenizeContent(content, ctx))]);
+    return known.hashes.some((hash) => candidates.has(hash));
+}
+/**
+ * What an upgrade would do, decided per file, writing nothing.
+ *
+ * The rule is the whole design: **replace what the rig installed and the user
+ * did not touch; report everything else.** There is no three-way merge and no
+ * patching — silently merging someone's edits into a file the agent loop obeys
+ * is how a rig stops meaning what its owner thinks it means.
+ */
+export async function planUpgrade(repoDir, options = {}) {
+    const manifest = await readManifest(repoDir);
+    // Detection is a whole-tree probe, and it answers a question the manifest
+    // has already answered when there is one.
+    const detected = manifest === null
+        ? await detectInstall(repoDir)
+        : { kind: manifest.kind, stacks: manifest.stacks, region: manifest.project.region };
+    const kind = manifest?.kind ?? detected.kind;
+    const name = path.basename(path.resolve(repoDir));
+    // `init` slugs the directory name into something an operator can type (it
+    // ends up in the kill-switch filename); `create` validated it as an npm name
+    // at generation time, so there the basename is already the project name.
+    const bootstrapName = kind === 'init' ? projectNameFor(repoDir) : name;
+    const project = manifest?.project ?? {
+        name: bootstrapName,
+        scope: bootstrapName,
+        region: detected.region,
+    };
+    // Only overlays this version actually ships. An unknown name is not input
+    // being dropped — there is no layer behind it to install from — and reading
+    // a directory a manifest names would be reading a directory a manifest names.
+    const shipped = new Set(knownStacks());
+    const stacks = (manifest?.stacks ?? detected.stacks).filter((stack) => shipped.has(stack));
+    const history = options.history ?? (await loadHashHistory());
+    const files = await installSetFor(repoDir, kind, project, stacks);
+    const ctx = {
+        projectName: project.name,
+        projectScope: project.scope,
+        region: project.region,
+    };
+    const actions = [];
+    const contents = new Map();
+    const nextFiles = {};
+    let wiring = null;
+    for (const file of files) {
+        const current = await readIfPresent(repoDir, file.rel);
+        const recorded = manifest?.files[file.rel];
+        contents.set(file.rel, file.content);
+        if (current === null) {
+            // Evidence, not a command. The manifest is the direct evidence; without
+            // one, a path that shipped in *every* release the table covers was there
+            // to be removed, so its absence is a decision. A path added later is
+            // simply missing from an older rig, and that one is delivered.
+            if (recorded !== undefined) {
+                actions.push({
+                    rel: file.rel,
+                    verdict: 'deleted',
+                    reason: 'installed by the rig, removed since — not restored',
+                });
+                nextFiles[file.rel] = recorded;
+            }
+            else if (presentInEveryRelease(history, file.rel)) {
+                actions.push({
+                    rel: file.rel,
+                    verdict: 'deleted',
+                    reason: `shipped in every release since ${history.versions[0]}, and is gone — not restored`,
+                });
+            }
+            else {
+                actions.push({ rel: file.rel, verdict: 'new', templatePath: file.source });
+                nextFiles[file.rel] = sha256(file.content);
+            }
+            continue;
+        }
+        if (file.rel === SETTINGS) {
+            if (current === file.content) {
+                actions.push({ rel: file.rel, verdict: 'unchanged' });
+                nextFiles[file.rel] = sha256(file.content);
+            }
+            else {
+                // Same special case `init` makes: this file is a merge target, not a
+                // payload — replacing it can unwire hooks the user added themselves.
+                wiring = file.content;
+                actions.push({
+                    rel: file.rel,
+                    verdict: 'wiring',
+                    reason: 'never replaced — merge the entries below by hand',
+                });
+                if (recorded !== undefined)
+                    nextFiles[file.rel] = recorded;
+            }
+            continue;
+        }
+        if (current === file.content) {
+            actions.push({ rel: file.rel, verdict: 'unchanged' });
+            nextFiles[file.rel] = sha256(file.content);
+        }
+        else if (recorded !== undefined && sha256(current) === recorded) {
+            actions.push({ rel: file.rel, verdict: 'update', templatePath: file.source });
+            nextFiles[file.rel] = sha256(file.content);
+        }
+        else if (isReleasedVersion(history, file.rel, current, ctx)) {
+            actions.push({ rel: file.rel, verdict: 'update', templatePath: file.source });
+            nextFiles[file.rel] = sha256(file.content);
+        }
+        else {
+            actions.push({
+                rel: file.rel,
+                verdict: 'conflict',
+                reason: recorded === undefined
+                    ? 'not a version this rig ever released — treated as yours'
+                    : 'edited since it was installed',
+                templatePath: file.source,
+            });
+            // deliberately NOT recorded: the rig does not own these bytes
+        }
+    }
+    // With no manifest, "there is a rig here" has to be *recognised*, not
+    // assumed from a file existing: `CLAUDE.md` and `.claude/settings.json` are
+    // in the install set and in nearly every repository ever opened by an agent.
+    // Recognition means bytes we know — a file already current, or one that
+    // matches a released version. Without that this command would silently
+    // perform an `init` nobody asked for.
+    if (manifest === null &&
+        !actions.some((a) => a.verdict === 'unchanged' || a.verdict === 'update'))
+        throw new UpgradeError(`No rig found in ${repoDir}. Nothing here is recognisable as a create-agent-rig ` +
+            'install — run `create-agent-rig init` to install the process layer, or upgrade ' +
+            'from the directory that holds the rig.');
+    return {
+        kind,
+        fromVersion: manifest?.version ?? null,
+        toVersion: await packageVersion(),
+        bootstrapped: manifest === null,
+        actions,
+        wiring,
+        contents,
+        manifest: {
+            version: await packageVersion(),
+            kind,
+            project,
+            stacks: [...stacks],
+            files: nextFiles,
+        },
+    };
+}
+/**
+ * Write the plan: the `update` and `new` files, then the manifest. Everything
+ * else in the plan is a sentence for a human, not an edit.
+ */
+export async function applyUpgrade(repoDir, plan, options = {}) {
+    const written = [];
+    if (options.dryRun === true)
+        return { written };
+    for (const action of plan.actions) {
+        if (action.verdict !== 'update' && action.verdict !== 'new')
+            continue;
+        const content = plan.contents.get(action.rel);
+        // Never a silent empty file: a missing entry is a defect in the plan, and
+        // truncating somebody's rule file is the worst way to report one.
+        if (content === undefined) {
+            throw new UpgradeError(`Internal: no content planned for "${action.rel}" — nothing written.`);
+        }
+        const dest = onDisk(repoDir, action.rel);
+        await mkdir(path.dirname(dest), { recursive: true });
+        await writeFile(dest, content);
+        written.push(action.rel);
+    }
+    await writeManifest(repoDir, plan.manifest);
+    return { written };
+}

package/packages/cli/dist/index.js

@@ -1,14 +1,13 @@
 #!/usr/bin/env node
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { CreateError, createProject } from './commands/create.js';
 import { InitError, initFileContents, initProject, planInit } from './commands/init.js';
+import { UpgradeError, applyUpgrade, planUpgrade } from './commands/upgrade.js';
 import { makePalette } from './lib/colors.js';
-import { promptTarget } from './lib/prompts.js';
+import { promptConfirm, promptTarget } from './lib/prompts.js';
 import { collectGovernance, renderSummary } from './lib/summary.js';
 import { DEFAULT_TARGET, TARGET_NAMES } from './lib/targets.js';
+import { packageVersion } from './lib/version.js';
 const USAGE = `Usage: create-agent-rig <dir> [options]
 
 Scaffolds a new project into <dir>: agent operating system (.claude/, CLAUDE.md)
@@ -25,14 +24,11 @@ Options
 
 Also: create-agent-rig init [--dry-run] [--force]
   Install the process layer (rules, gates, stop rules — no architecture
-  assumptions) into the CURRENT existing repo. Refuses to clobber CLAUDE.md.`;
-async function packageVersion() {
-    // dist/index.js lives three levels under the package root — same walk as
-    // the templates resolver, valid in the repo and in the published package.
-    const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'package.json');
-    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
-    return pkg.version;
-}
+  assumptions) into the CURRENT existing repo. Refuses to clobber CLAUDE.md.
+
+Also: create-agent-rig upgrade [--dry-run] [--yes]
+  Bring the rig in the CURRENT repo up to this version. Replaces the files it
+  installed and you did not touch; everything else is reported, never merged.`;
 async function runInit(rawArgs) {
     let values;
     try {
@@ -77,10 +73,99 @@ async function runInit(rawArgs) {
     }
     return 0;
 }
+const MARK = {
+    update: '~',
+    new: '+',
+    conflict: '!',
+    deleted: '-',
+    wiring: '!',
+    unchanged: '·',
+};
+function renderUpgradePlan(repoDir, plan) {
+    const of = (verdict) => plan.actions.filter((a) => a.verdict === verdict);
+    const lines = [
+        `agent-rig upgrade — ${plan.kind} rig in ${repoDir}`,
+        plan.bootstrapped
+            ? `  no manifest here (a pre-0.4.0 rig) — matching files against released versions`
+            : `  installed by ${plan.fromVersion}`,
+        `  upgrading to ${plan.toVersion}`,
+        '',
+    ];
+    for (const verdict of ['update', 'new', 'deleted', 'conflict', 'wiring']) {
+        for (const action of of(verdict)) {
+            lines.push(`  ${MARK[verdict]} ${action.rel}` + (action.reason ? `  — ${action.reason}` : ''));
+            // A conflict is only useful if the new version can be diffed by hand.
+            if (verdict === 'conflict' && action.templatePath) {
+                lines.push(`      new version: ${action.templatePath}`);
+            }
+        }
+    }
+    const unchanged = of('unchanged').length;
+    lines.push('', `  ${of('update').length} to replace, ${of('new').length} new, ` +
+        `${of('conflict').length} yours (kept), ${unchanged} already current`);
+    return `${lines.join('\n')}\n`;
+}
+async function runUpgrade(rawArgs) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: rawArgs,
+            options: { 'dry-run': { type: 'boolean' }, yes: { type: 'boolean' } },
+            allowPositionals: false,
+        }));
+    }
+    catch (error) {
+        process.stderr.write(`${error.message}\n\n${USAGE}\n`);
+        return 1;
+    }
+    const cwd = process.cwd();
+    const plan = await planUpgrade(cwd);
+    process.stdout.write(renderUpgradePlan(cwd, plan));
+    // The one thing this command will not do for you — printed with the plan,
+    // because the dry run is where a reader decides whether there is work here,
+    // and a report that mentions entries it never shows is not a plan.
+    if (plan.wiring !== null) {
+        process.stdout.write(`\n!  .claude/settings.json is never replaced — it is where your own hooks live.\n` +
+            `   This version wires them like this; merge in what is missing:\n\n` +
+            plan.wiring.replace(/^/gm, '   ') +
+            '\n');
+    }
+    if (values['dry-run'] === true) {
+        process.stdout.write('\nDry run — nothing written.\n');
+        return 0;
+    }
+    // The plan above is the review step, so it has to be answered before
+    // anything is written. On a terminal that is a question; off one it is the
+    // same refusal `create` makes without --target — never guess for a run that
+    // cannot be asked, least of all when the answer rewrites its repository.
+    const isInteractive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    if (values.yes !== true) {
+        if (!isInteractive) {
+            process.stderr.write('Refusing to rewrite files in a non-interactive run. ' +
+                'Re-run with --yes once the plan above is what you want (or --dry-run to keep looking).\n');
+            return 1;
+        }
+        const confirmed = await promptConfirm('\nApply this plan?', {
+            input: process.stdin,
+            output: process.stderr,
+            isInteractive,
+        });
+        if (!confirmed) {
+            process.stdout.write('Nothing written.\n');
+            return 0;
+        }
+    }
+    const result = await applyUpgrade(cwd, plan);
+    process.stdout.write(`\nWrote ${result.written.length} files.\n`);
+    return 0;
+}
 async function main() {
     if (process.argv[2] === 'init') {
         return runInit(process.argv.slice(3));
     }
+    if (process.argv[2] === 'upgrade') {
+        return runUpgrade(process.argv.slice(3));
+    }
     let positionals;
     let values;
     try {
@@ -144,7 +229,9 @@ main()
     process.exitCode = code;
 })
     .catch((error) => {
-    if (error instanceof CreateError || error instanceof InitError) {
+    if (error instanceof CreateError ||
+        error instanceof InitError ||
+        error instanceof UpgradeError) {
         process.stderr.write(`${error.message}\n`);
     }
     else {

package/packages/cli/dist/lib/copy-tree.js

@@ -34,6 +34,14 @@ export async function copyTree(srcDir, destDir, options = {}) {
  * composition for collisions before anything is copied.
  */
 export async function listTree(srcDir, options = {}) {
+    return (await listTreeEntries(srcDir, options)).map((entry) => entry.rel);
+}
+/**
+ * {@link listTree} with the source path kept alongside each destination — what
+ * an upgrade needs to read the new version of a file, and to name where it
+ * lives when it must not write it.
+ */
+export async function listTreeEntries(srcDir, options = {}) {
     const ignore = new Set(options.ignore ?? DEFAULT_IGNORE);
     const files = [];
     const walk = async (dir, relDir) => {
@@ -47,7 +55,7 @@ export async function listTree(srcDir, options = {}) {
                 await walk(path.join(dir, entry.name), relPath);
             }
             else if (entry.isFile()) {
-                files.push(relPath);
+                files.push({ rel: relPath, source: path.join(dir, entry.name) });
             }
         }
     };

package/packages/cli/dist/lib/git-env.js

@@ -0,0 +1,48 @@
+/**
+ * Variables that point git at a repository other than the one at `cwd`.
+ *
+ * Inherited, they silently redirect a git command into the CALLER's repository:
+ * `git init` re-initialises it, `add -A` stages the caller's tree, and a commit
+ * lands on whatever branch the caller has checked out — while the directory the
+ * command was aimed at ends up with no `.git` at all.
+ *
+ * This is not hypothetical. Git sets `GIT_DIR` and `GIT_INDEX_FILE` — absolute —
+ * for the hooks it runs, so a `git commit` from a linked worktree whose
+ * pre-commit runs a suite that shells out to git writes one junk commit per
+ * invocation onto the branch being committed. Observed twice in this repo, from
+ * two different call sites, which is why this lives in one module: a second copy
+ * of this list is a second chance to fix one and forget the other.
+ *
+ * The list is explicit rather than a `GIT_*` sweep on purpose — `GIT_SSH_COMMAND`
+ * or `GIT_TERMINAL_PROMPT` are the caller's environment and none of our business.
+ * Only repository *location* is stripped.
+ *
+ * 🔴 Limit, stated: this strips repository *location*, not every way git can be
+ * redirected. The config-injection family (`GIT_CONFIG_COUNT`/`_KEY_n`/`_VALUE_n`,
+ * `GIT_CONFIG_PARAMETERS`, `GIT_CONFIG_GLOBAL`/`_SYSTEM`) can carry `core.worktree`
+ * or `core.bare` and is deliberately out of scope: git never sets those for the
+ * hooks that cause this problem, and stripping a caller's deliberate config
+ * overrides would be its own surprise.
+ *
+ * 🔴 And it protects exactly the call sites that use it. It does not make git
+ * safe to call from a hook-invoked process in general, and a spawn that forgets
+ * `gitEnv()` is unprotected — nothing in this module can detect that. The sweep
+ * in `test/template/git-env.test.ts` is what watches for it.
+ */
+export const GIT_LOCATION_VARS = [
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_INDEX_FILE',
+    'GIT_COMMON_DIR',
+    'GIT_OBJECT_DIRECTORY',
+    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+    'GIT_NAMESPACE',
+    'GIT_PREFIX',
+];
+/** The caller's environment minus anything that re-points git at another repo. */
+export function gitEnv(env = process.env) {
+    const sanitised = { ...env };
+    for (const key of GIT_LOCATION_VARS)
+        delete sanitised[key];
+    return sanitised;
+}

package/packages/cli/dist/lib/history.js

@@ -0,0 +1,49 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { templatesRoot } from '../templates.js';
+export const EMPTY_HISTORY = { versions: [], files: {} };
+/**
+ * Whether every release this table knows about carried this path.
+ *
+ * It is the one question that lets a manifest-less rig keep a **deletion**: if
+ * the file shipped in every version the rig could possibly be, then it is gone
+ * because somebody removed it — not because the rig predates it. A path added
+ * later is genuinely new to an older rig and must still be delivered.
+ */
+export function presentInEveryRelease(history, rel) {
+    const oldest = history.versions[0];
+    const entry = history.files[rel];
+    return oldest !== undefined && entry !== undefined && entry.since === oldest;
+}
+export function historyPath() {
+    return path.join(templatesRoot(), 'hash-history.json');
+}
+/**
+ * Fails open to an empty table: a missing or corrupt history means "nothing is
+ * recognised", which downgrades files to conflicts. That is the safe
+ * direction — the unsafe one is claiming a file is untouched when it is not.
+ */
+export async function loadHashHistory() {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(historyPath(), 'utf8'));
+    }
+    catch {
+        return EMPTY_HISTORY;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return EMPTY_HISTORY;
+    const { versions, files } = parsed;
+    if (!Array.isArray(versions) || typeof files !== 'object' || files === null)
+        return EMPTY_HISTORY;
+    const clean = {};
+    for (const [rel, entry] of Object.entries(files)) {
+        const { since, hashes } = (entry ?? {});
+        if (typeof since !== 'string')
+            continue;
+        if (!Array.isArray(hashes) || hashes.some((h) => typeof h !== 'string'))
+            continue;
+        clean[rel] = { since, hashes };
+    }
+    return { versions: versions.filter((v) => typeof v === 'string'), files: clean };
+}

package/packages/cli/dist/lib/install-set.js

@@ -0,0 +1,46 @@
+import { readFile } from 'node:fs/promises';
+import { listTreeEntries } from './copy-tree.js';
+import { substituteContent, substituteFileName } from './substitute.js';
+import { agentOsStackDir, agentOsUniversalDir } from '../templates.js';
+/**
+ * The agent-os layers of a target, in composition order. One definition, read
+ * by `create` when it copies them and by `upgrade` when it refreshes them —
+ * two lists would drift, and the one nobody looks at would be the wrong one.
+ */
+export function agentOsLayerDirs(stacks) {
+    return [
+        { name: 'agent-os/universal', dir: agentOsUniversalDir() },
+        ...stacks.map((stack) => ({ name: `agent-os/stack/${stack}`, dir: agentOsStackDir(stack) })),
+    ];
+}
+/**
+ * Exactly the agent-os bytes `create` writes, for a given target and project.
+ *
+ * The skeleton is deliberately absent: after generation the code is the user's
+ * project, not the rig's — `upgrade` refreshes the process layer and nothing
+ * else. Layers claim disjoint paths (`composition.ts` refuses otherwise), so
+ * this is a plain concatenation.
+ *
+ * 🔴 Two assumptions, both load-bearing and both true today: the layer is all
+ * **text** (this reads every file as UTF-8; a template test pins it for the
+ * process half) and none of it is **executable** (`upgrade` writes with a bare
+ * `writeFile` and does not carry the mode across the way `copyTree` does —
+ * nothing in `templates/agent-os` currently has a mode to carry). Adding the
+ * first binary asset or executable script here means teaching both.
+ */
+export async function agentOsInstallSet(stacks, ctx) {
+    const files = [];
+    for (const layer of agentOsLayerDirs(stacks)) {
+        const entries = await listTreeEntries(layer.dir, {
+            transformName: (name) => substituteFileName(name, ctx),
+        });
+        for (const entry of entries) {
+            files.push({
+                rel: entry.rel,
+                source: entry.source,
+                content: substituteContent(await readFile(entry.source, 'utf8'), ctx),
+            });
+        }
+    }
+    return files;
+}