@aperant/framework 0.8.1 → 0.8.4

package/dist/cli/install/install-from-source.mjs

@@ -0,0 +1,271 @@
+/**
+ * install/install-from-source.mjs — Bundle D part 1.
+ *
+ * `apt-tools install-from-source <project-dir>` for the Aperant-contributor
+ * self-host case. Resolves the workspace `@aperant/framework` chain — packs
+ * the framework itself AND every `workspace:*` dependency (currently
+ * `@aperant/driver-sdk`, but the walker is general). Hands the full tarball
+ * list to a single `npm install --prefix` invocation so the same-PR
+ * unpublished-pair case stops blowing up with `EUNSUPPORTEDPROTOCOL`.
+ *
+ * Stable envelope:
+ *   { status: 'ok',     tarballs: string[], kernel_path: string }
+ *   { status: 'error',  error: string, ...optional context }
+ *
+ * Test seams: `APT_PNPM_BIN` + `APT_NPM_BIN` mirror the existing
+ * `install-kernel.mjs` + worker patterns.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { err, ok } from '../util/result.mjs';
+import { findWorkspaceFrameworkVersion } from './find-workspace-framework-version.mjs';
+import { KERNEL_BIN_REL_PATH } from './install-kernel.mjs';
+/**
+ * Locate the monorepo root given the workspace framework package.json path.
+ * `<root>/packages/framework/package.json` → `<root>`.
+ *
+ * @param {string} frameworkPkgPath
+ * @returns {string}
+ */
+function monorepoRootFrom(frameworkPkgPath) {
+    // `<root>/packages/framework/package.json` — go up THREE levels.
+    return dirname(dirname(dirname(frameworkPkgPath)));
+}
+/**
+ * Scan `<monorepoRoot>/packages/` for a directory whose `package.json:name`
+ * matches `pkgName`. Returns the directory path (containing package.json),
+ * or null if no match.
+ *
+ * @param {string} monorepoRoot
+ * @param {string} pkgName
+ * @returns {string|null}
+ */
+function findWorkspacePackage(monorepoRoot, pkgName) {
+    const packagesDir = join(monorepoRoot, 'packages');
+    if (!existsSync(packagesDir))
+        return null;
+    let entries;
+    try {
+        entries = readdirSync(packagesDir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const candidate = join(packagesDir, entry.name, 'package.json');
+        if (!existsSync(candidate))
+            continue;
+        try {
+            const pkg = JSON.parse(readFileSync(candidate, 'utf-8'));
+            if (pkg?.name === pkgName)
+                return join(packagesDir, entry.name);
+        }
+        catch {
+            // Skip unreadable package.json files.
+        }
+    }
+    return null;
+}
+/**
+ * pnpm-pack a workspace package into `tmpDir` and return the resulting
+ * tarball path. Uses `pnpm --filter <name> pack --pack-destination <tmp>`
+ * so workspace protocols resolve to concrete versions inside the tarball.
+ *
+ * `knownBefore` is the set of .tgz filenames already present in `tmpDir`
+ * before this call; the mtime fallback uses it to find only the NEW file,
+ * avoiding coarse-timestamp ambiguity when multiple packs land in the same
+ * directory.
+ *
+ * @param {string} monorepoRoot
+ * @param {string} pkgName
+ * @param {string} tmpDir
+ * @param {Set<string>} knownBefore  Filenames (not paths) present before this pack.
+ * @returns {{ tarball: string } | { error: string }}
+ */
+function packWorkspace(monorepoRoot, pkgName, tmpDir, knownBefore) {
+    const pnpmBin = process.env.APT_PNPM_BIN || 'pnpm';
+    const result = spawnSync(pnpmBin, ['--filter', pkgName, 'pack', '--pack-destination', tmpDir], {
+        cwd: monorepoRoot,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        encoding: 'utf-8',
+        timeout: 120_000,
+    });
+    if (result.error) {
+        return { error: `pnpm spawn failed for ${pkgName}: ${result.error.message}` };
+    }
+    if (result.status !== 0) {
+        const stderr = (result.stderr || '').trim().slice(-600);
+        return { error: `pnpm pack ${pkgName} exited with ${result.status}: ${stderr || 'no stderr'}` };
+    }
+    // pnpm pack prints the resulting tarball path on stdout. Take the last
+    // `.tgz` line (pnpm sometimes emits warnings above the path line).
+    const tarballLine = (result.stdout || '')
+        .split('\n')
+        .map((s) => s.trim())
+        .reverse()
+        .find((s) => s.endsWith('.tgz'));
+    if (tarballLine) {
+        // `tarballLine` may be a bare filename (older pnpm) or an absolute path.
+        // Use `isAbsolute` so Windows backslash + drive-letter paths are also
+        // recognized — `startsWith('/')` was POSIX-only.
+        const tarball = isAbsolute(tarballLine) ? tarballLine : join(tmpDir, tarballLine);
+        // SEC-001: containment check — tarball must resolve to a child of tmpDir.
+        const resolvedTmpDir = resolve(tmpDir);
+        const resolvedTarball = resolve(tarball);
+        if (!resolvedTarball.startsWith(`${resolvedTmpDir}/`) && resolvedTarball !== resolvedTmpDir) {
+            return { error: `pnpm pack ${pkgName}: tarball path escapes tmpDir: ${tarball}` };
+        }
+        return { tarball };
+    }
+    // Fall back to scanning tmpDir for the NEW tgz when stdout was
+    // uninformative (some pnpm builds print only progress to stderr).
+    // Use `knownBefore` to find only files added by this pack, avoiding
+    // mtime coarse-timestamp ambiguity on FAT32/network filesystems.
+    try {
+        for (const f of readdirSync(tmpDir)) {
+            if (!f.endsWith('.tgz'))
+                continue;
+            if (knownBefore.has(f))
+                continue;
+            return { tarball: join(tmpDir, f) };
+        }
+    }
+    catch {
+        // fall through
+    }
+    return {
+        error: `pnpm pack ${pkgName}: no .tgz produced (stdout: ${result.stdout?.slice(-200)})`,
+    };
+}
+/**
+ * `apt-tools install-from-source <project-dir>` — pack the workspace
+ * framework + every `workspace:*` dep, then npm-install the full tarball
+ * list into `<project-dir>/.aperant/deps/`.
+ *
+ * @param {string} projectDir
+ * @returns {import('../util/result.mjs').CommandResult}
+ */
+export function cmdInstallFromSource(projectDir) {
+    if (!projectDir) {
+        return err('Usage: apt-tools install-from-source <project-dir>');
+    }
+    const targetDir = resolve(projectDir);
+    const workspace = findWorkspaceFrameworkVersion(targetDir);
+    if (!workspace) {
+        return err('install-from-source: no @aperant/framework workspace found above project-dir');
+    }
+    const monorepoRoot = monorepoRootFrom(workspace.source_path);
+    // QUA-001: re-read the workspace package.json with a try/catch — the file
+    // was validated by findWorkspaceFrameworkVersion but could change between
+    // the two reads (active monorepo, contributor machine).
+    let frameworkPkg;
+    try {
+        frameworkPkg = JSON.parse(readFileSync(workspace.source_path, 'utf-8'));
+    }
+    catch (e) {
+        return err(`install-from-source: failed to read ${workspace.source_path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // Enumerate workspace:* deps from dependencies + peerDependencies.
+    const depSources = [frameworkPkg.dependencies, frameworkPkg.peerDependencies];
+    const workspaceDeps = [];
+    for (const block of depSources) {
+        if (!block || typeof block !== 'object')
+            continue;
+        for (const [name, spec] of Object.entries(block)) {
+            if (typeof spec === 'string' && spec.startsWith('workspace:')) {
+                if (!workspaceDeps.includes(name))
+                    workspaceDeps.push(name);
+            }
+        }
+    }
+    // Resolve each workspace dep to its `packages/<dir>` path. Reject hard
+    // when any dep cannot be located — we cannot pack what we cannot find.
+    const missingDeps = [];
+    const resolvedDeps = [];
+    for (const depName of workspaceDeps) {
+        const pkgDir = findWorkspacePackage(monorepoRoot, depName);
+        if (!pkgDir) {
+            missingDeps.push(depName);
+            continue;
+        }
+        resolvedDeps.push({ name: depName, dir: pkgDir });
+    }
+    if (missingDeps.length > 0) {
+        return err(`install-from-source: workspace:* dep(s) not found in packages/: ${missingDeps.join(', ')}`);
+    }
+    // PRF-001: include framework in the same pack loop — eliminates structural
+    // duplication and ensures per-pack knownBefore snapshots work uniformly.
+    const packTargets = [...resolvedDeps.map((d) => d.name), '@aperant/framework'];
+    // Pack everything into a fresh tmp dir so accumulated stale tarballs
+    // from prior runs don't sneak in.
+    const tmpDir = mkdtempSync(join(tmpdir(), 'apt-install-from-source-'));
+    const tarballs = [];
+    // QUA-002: wrap pack+install in try/finally so tmpDir is always removed.
+    try {
+        for (const pkgName of packTargets) {
+            // LOG-003: snapshot existing tgz filenames before each pack so the
+            // fallback can identify exactly the new file, even on coarse-timestamp
+            // filesystems (FAT32, some network mounts).
+            const knownBefore = new Set();
+            try {
+                for (const f of readdirSync(tmpDir)) {
+                    if (f.endsWith('.tgz'))
+                        knownBefore.add(f);
+                }
+            }
+            catch {
+                // tmpDir unreadable — proceed with empty set; fallback will still work.
+            }
+            const packResult = packWorkspace(monorepoRoot, pkgName, tmpDir, knownBefore);
+            if ('error' in packResult)
+                return err(packResult.error);
+            tarballs.push(packResult.tarball);
+        }
+        // npm install --prefix .aperant/deps <tarball1> <tarball2> ...
+        const depsDir = join(targetDir, '.aperant', 'deps');
+        mkdirSync(depsDir, { recursive: true });
+        const npmBin = process.env.APT_NPM_BIN || 'npm';
+        const args = [
+            'install',
+            '--prefix',
+            depsDir,
+            ...tarballs,
+            '--no-save',
+            '--no-package-lock',
+            '--no-audit',
+            '--no-fund',
+            '--silent',
+        ];
+        const npmResult = spawnSync(npmBin, args, {
+            cwd: targetDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            encoding: 'utf-8',
+            timeout: 180_000,
+        });
+        if (npmResult.error) {
+            return err(`install-from-source: npm spawn failed: ${npmResult.error.message}`);
+        }
+        if (npmResult.status !== 0) {
+            const stderr = (npmResult.stderr || '').trim().slice(-600);
+            return err(`install-from-source: npm install --prefix exited with ${npmResult.status}: ${stderr || 'no stderr'}`);
+        }
+        const kernelPath = join(targetDir, KERNEL_BIN_REL_PATH);
+        if (!existsSync(kernelPath)) {
+            return err(`install-from-source: npm reported success but kernel not found at ${kernelPath}`);
+        }
+        return ok({
+            status: 'ok',
+            command: 'install-from-source',
+            tarballs,
+            kernel_path: kernelPath,
+        });
+    }
+    finally {
+        rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=install-from-source.mjs.map

package/dist/cli/install/install-from-source.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-from-source.mjs","sourceRoot":"","sources":["../../../src/cli/install/install-from-source.mjs"],"names":[],"mappings":"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"}

package/dist/cli/install/install-kernel.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"install-kernel.d.mts","sourceRoot":"","sources":["../../../src/cli/install/install-kernel.mjs"],"names":[],"mappings":"AA2FA;;;;;;GAMG;AAEH;;;;;;;;;;;;GAYG;AACH,yCARW,MAAM,WACN,MAAM,SAGd;IAAsB,SAAS;IACR,MAAM;CAC7B,GAAU,mBAAmB,CAqE/B;AApJD;;;;GAIG;AACH,kCAAmC,iEAAiE,CAAA;;YAyDtF,WAAW,GAAG,SAAS,GAAG,QAAQ;;;;gBAClC,MAAM"}
+{"version":3,"file":"install-kernel.d.mts","sourceRoot":"","sources":["../../../src/cli/install/install-kernel.mjs"],"names":[],"mappings":"AA2FA;;;;;;GAMG;AAEH;;;;;;;;;;;;GAYG;AACH,yCARW,MAAM,WACN,MAAM,SAGd;IAAsB,SAAS;IACR,MAAM;CAC7B,GAAU,mBAAmB,CA6F/B;AA5KD;;;;GAIG;AACH,kCAAmC,iEAAiE,CAAA;;YAyDtF,WAAW,GAAG,SAAS,GAAG,QAAQ;;;;gBAClC,MAAM"}

package/dist/cli/install/install-kernel.mjs

@@ -115,6 +115,30 @@ export function installKernel(targetDir, version, opts = {}) {
     mkdirSync(depsDir, { recursive: true });
     const kernelPath = join(targetDir, KERNEL_BIN_REL_PATH);
     const npmBin = resolveNpmBin();
+    // Bundle B — idempotency short-circuit. When the kernel package.json
+    // already reports the requested version AND the kernel binary exists,
+    // skip the npm spawn entirely. Returns the same `status: 'installed'`
+    // envelope shape that downstream consumers branch on (init.mjs:1441,
+    // init.mjs:1735, apt-update/SKILL.md Scenario D) — no new enum value
+    // per D-02.
+    const installedPkgPath = join(depsDir, 'node_modules', '@aperant', 'framework', 'package.json');
+    if (existsSync(installedPkgPath) && existsSync(kernelPath)) {
+        try {
+            const installedPkg = JSON.parse(readFileSync(installedPkgPath, 'utf-8'));
+            if (installedPkg?.version === version) {
+                return {
+                    status: 'installed',
+                    kernelPath,
+                    reason: 'already at target version',
+                    durationMs: 0,
+                };
+            }
+        }
+        catch {
+            // Malformed package.json — fall through to the npm install path
+            // (npm will reconcile / repair).
+        }
+    }
     const t0 = Date.now();
     const args = [
         'install',

package/dist/cli/install/install-kernel.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"install-kernel.mjs","sourceRoot":"","sources":["../../../src/cli/install/install-kernel.mjs"],"names":[],"mappings":"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"}
+{"version":3,"file":"install-kernel.mjs","sourceRoot":"","sources":["../../../src/cli/install/install-kernel.mjs"],"names":[],"mappings":"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"}

package/dist/cli/install/legacy-paths.d.mts

@@ -11,28 +11,50 @@
  *     pre-manifest install still surfaces as "installed" rather than
  *     "missing-skills".
  *
- * Derivation: the codex `framework_files` list was extracted from
- * `git show 1a8dd8a8 --stat` (the original "make Codex a first-class
- * skill install surface" commit) — every `.agents/skills/…` path the
- * installer once wrote, including the `.apt-version` stamp and the
- * apt-pr-review / apt-discuss / apt-verify-proof sub-files. When the
- * codex installer was retargeted to `.codex/`, that entire tree became
- * orphaned on upgrading projects.
+ * Codex evolution: v0.7/v0.8 retargeted the codex transform to write
+ * markdown skills under `.codex/agents/` + `.codex/commands/` (with the
+ * apt-file-manifest.json next to them). Codex CLI 0.132.0 does not
+ * discover skills at either path — its documented surface is
+ * `.agents/skills/<folder>/SKILL.md` (per
+ * https://developers.openai.com/codex/skills). The v0.8.2 fix inverts
+ * this registry: the dead `.codex/` markdown tree becomes the legacy
+ * target so `runLegacyCleanup` GCs it on the next `apt-tools init`.
  *
  * Schema:
  *   { [runtimeId]: {
  *       install_root:     relative path the runtime once wrote into,
- *       version_file:     relative path of the legacy `.apt-version` stamp,
+ *       version_file:     relative path of the legacy `.apt-version` stamp
+ *                         (or a path known to never exist, when no version
+ *                         stamp was ever written for the legacy topology),
+ *       honor_manifest:   when true (default), a present apt-file-manifest.json
+ *                         at install_root signals a managed install and the
+ *                         cleanup no-ops (`reason: 'managed'`). When false,
+ *                         the legacy root is known-dead so the manifest is
+ *                         removed alongside framework files (used for surfaces
+ *                         like the v0.7/v0.8 codex misdirect that will never
+ *                         again be a managed install root).
  *       framework_files:  array of relative paths the installer once owned
  *                         (under install_root).
  *   } }
  *
  * Frozen via Object.freeze so callers cannot mutate the shared registry.
  */
-/** @type {Record<string, { install_root: string, version_file: string, framework_files: ReadonlyArray<string> }>} */
-export const LEGACY_INSTALL_PATHS: Record<string, {
+/**
+ * @typedef {Object} LegacyInstallPath
+ * @property {string} install_root
+ * @property {string} version_file
+ * @property {boolean} [honor_manifest]  default true; false for known-dead surfaces
+ * @property {ReadonlyArray<string>} framework_files
+ */
+/** @type {Record<string, LegacyInstallPath>} */
+export const LEGACY_INSTALL_PATHS: Record<string, LegacyInstallPath>;
+export type LegacyInstallPath = {
     install_root: string;
     version_file: string;
+    /**
+     * default true; false for known-dead surfaces
+     */
+    honor_manifest?: boolean | undefined;
     framework_files: ReadonlyArray<string>;
-}>;
+};
 //# sourceMappingURL=legacy-paths.d.mts.map

package/dist/cli/install/legacy-paths.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"legacy-paths.d.mts","sourceRoot":"","sources":["../../../src/cli/install/legacy-paths.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,qHAAqH;AACrH,mCADW,MAAM,CAAC,MAAM,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAoC/G"}
+{"version":3,"file":"legacy-paths.d.mts","sourceRoot":"","sources":["../../../src/cli/install/legacy-paths.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;;GAMG;AAEH,gDAAgD;AAChD,mCADW,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CA6I1C;;kBAnJY,MAAM;kBACN,MAAM;;;;;qBAEN,aAAa,CAAC,MAAM,CAAC"}

package/dist/cli/install/legacy-paths.mjs

@@ -11,58 +11,180 @@
  *     pre-manifest install still surfaces as "installed" rather than
  *     "missing-skills".
  *
- * Derivation: the codex `framework_files` list was extracted from
- * `git show 1a8dd8a8 --stat` (the original "make Codex a first-class
- * skill install surface" commit) — every `.agents/skills/…` path the
- * installer once wrote, including the `.apt-version` stamp and the
- * apt-pr-review / apt-discuss / apt-verify-proof sub-files. When the
- * codex installer was retargeted to `.codex/`, that entire tree became
- * orphaned on upgrading projects.
+ * Codex evolution: v0.7/v0.8 retargeted the codex transform to write
+ * markdown skills under `.codex/agents/` + `.codex/commands/` (with the
+ * apt-file-manifest.json next to them). Codex CLI 0.132.0 does not
+ * discover skills at either path — its documented surface is
+ * `.agents/skills/<folder>/SKILL.md` (per
+ * https://developers.openai.com/codex/skills). The v0.8.2 fix inverts
+ * this registry: the dead `.codex/` markdown tree becomes the legacy
+ * target so `runLegacyCleanup` GCs it on the next `apt-tools init`.
  *
  * Schema:
  *   { [runtimeId]: {
  *       install_root:     relative path the runtime once wrote into,
- *       version_file:     relative path of the legacy `.apt-version` stamp,
+ *       version_file:     relative path of the legacy `.apt-version` stamp
+ *                         (or a path known to never exist, when no version
+ *                         stamp was ever written for the legacy topology),
+ *       honor_manifest:   when true (default), a present apt-file-manifest.json
+ *                         at install_root signals a managed install and the
+ *                         cleanup no-ops (`reason: 'managed'`). When false,
+ *                         the legacy root is known-dead so the manifest is
+ *                         removed alongside framework files (used for surfaces
+ *                         like the v0.7/v0.8 codex misdirect that will never
+ *                         again be a managed install root).
  *       framework_files:  array of relative paths the installer once owned
  *                         (under install_root).
  *   } }
  *
  * Frozen via Object.freeze so callers cannot mutate the shared registry.
  */
-/** @type {Record<string, { install_root: string, version_file: string, framework_files: ReadonlyArray<string> }>} */
+/**
+ * @typedef {Object} LegacyInstallPath
+ * @property {string} install_root
+ * @property {string} version_file
+ * @property {boolean} [honor_manifest]  default true; false for known-dead surfaces
+ * @property {ReadonlyArray<string>} framework_files
+ */
+/** @type {Record<string, LegacyInstallPath>} */
 export const LEGACY_INSTALL_PATHS = Object.freeze({
     codex: Object.freeze({
-        install_root: '.agents/skills',
-        version_file: '.agents/skills/.apt-version',
+        // The v0.7/v0.8 misdirect lived under `.codex/agents/` + `.codex/commands/`
+        // (with the orphan apt-file-manifest.json at `.codex/apt-file-manifest.json`).
+        // Codex CLI 0.132.0 does not consume any of those paths — see header.
+        install_root: '.codex',
+        // No `.apt-version` was ever written under `.codex/`; point at a path
+        // that doesn't exist so `existsSync` returns false in
+        // skill-installs.mjs:67-68 (legacy version_file fallback). The bare
+        // apt-file-manifest.json (handled by framework_files) is enough to
+        // signal the legacy install.
+        version_file: '.codex/.apt-version',
+        // Known-dead surface: this `.codex/` topology will never again be
+        // a managed Aperant install root, so a manifest sitting here is
+        // always stale. Skip the no-op-on-manifest safety and remove the
+        // manifest alongside framework_files. Default-true elsewhere
+        // preserves the safety for legacy roots that could legitimately
+        // re-host a managed install.
+        honor_manifest: false,
+        // Enumerated from BOTH canonical sources (drift-checked at test time
+        // by legacy-cleanup-codex.test.ts):
+        //   - For each `packages/framework/skills/apt-*/` directory: the v0.7/v0.8
+        //     transform emitted BOTH `agents/<dir>.md` AND `commands/<dir>.md`.
+        //   - For each top-level `packages/framework/skills/apt-*.md` file
+        //     (fileType=agent in the pipeline): the transform emitted
+        //     `agents/<basename>.md`.
+        //   - For each `packages/framework/agents/apt-*.md` file: the transform
+        //     emitted `agents/<basename>.md` (last-write-wins de-dupe applied
+        //     by the pipeline for overlapping outputs).
+        //   - Plus the orphan apt-file-manifest.json the install pipeline
+        //     stamps at install_root.
+        // TODO: follow-up — derive this programmatically per spec ID-06 so
+        // new apt-* skills auto-extend the legacy set without an edit here.
         framework_files: Object.freeze([
-            '.apt-version',
-            'apt/SKILL.md',
-            'apt-debug/SKILL.md',
-            'apt-discuss/SKILL.md',
-            'apt-discuss/examples/rationalization-example.md',
-            'apt-docs/SKILL.md',
-            'apt-execute/SKILL.md',
-            'apt-pause/SKILL.md',
-            'apt-plan/SKILL.md',
-            'apt-pr-review/SCHEMA.md',
-            'apt-pr-review/SKILL.md',
-            'apt-pr-review/prompts/fp-gate-codex.md',
-            'apt-pr-review/templates/external-comment.md',
-            'apt-quick/SKILL.md',
-            'apt-resume/SKILL.md',
-            'apt-review/SKILL.md',
-            'apt-roadmap/SKILL.md',
-            'apt-roundtable/SKILL.md',
-            'apt-run/SKILL.md',
-            'apt-scan/SKILL.md',
-            'apt-setup/SKILL.md',
-            'apt-ship/SKILL.md',
-            'apt-stress-test/SKILL.md',
-            'apt-verify/SKILL.md',
-            'apt-verify-proof/SKILL.md',
-            'apt-verify-proof/references/multi-model-setup.md',
-            'apt-verify-proof/references/multi-model-verification.md',
-            'apt-verify-proof/references/proof-capture.md',
+            'apt-file-manifest.json',
+            // agents/<dir>.md — one per skill directory (39 dirs)
+            'agents/apt.md',
+            'agents/apt-author-skill.md',
+            'agents/apt-bootstrap.md',
+            'agents/apt-caveman.md',
+            'agents/apt-classify.md',
+            'agents/apt-close-task.md',
+            'agents/apt-create-docs.md',
+            'agents/apt-debug.md',
+            'agents/apt-design.md',
+            'agents/apt-diagram.md',
+            'agents/apt-discuss.md',
+            'agents/apt-docs.md',
+            'agents/apt-execute.md',
+            'agents/apt-fan-out.md',
+            'agents/apt-handoff.md',
+            'agents/apt-improve.md',
+            'agents/apt-mockup.md',
+            'agents/apt-pause.md',
+            'agents/apt-personas.md',
+            'agents/apt-plan.md',
+            'agents/apt-pr-review.md',
+            'agents/apt-prototype.md',
+            'agents/apt-quick.md',
+            'agents/apt-release-notes.md',
+            'agents/apt-resume.md',
+            'agents/apt-review.md',
+            'agents/apt-roadmap.md',
+            'agents/apt-roundtable.md',
+            'agents/apt-run.md',
+            'agents/apt-scan.md',
+            'agents/apt-setup.md',
+            'agents/apt-ship.md',
+            'agents/apt-spar.md',
+            'agents/apt-stress-test.md',
+            'agents/apt-terminal.md',
+            'agents/apt-triage.md',
+            'agents/apt-update.md',
+            'agents/apt-verify.md',
+            'agents/apt-verify-proof.md',
+            'agents/apt-watch-ci.md',
+            'agents/apt-zoom-out.md',
+            // commands/<dir>.md — one per skill directory (mirrors agents/)
+            'commands/apt.md',
+            'commands/apt-author-skill.md',
+            'commands/apt-bootstrap.md',
+            'commands/apt-caveman.md',
+            'commands/apt-classify.md',
+            'commands/apt-close-task.md',
+            'commands/apt-create-docs.md',
+            'commands/apt-debug.md',
+            'commands/apt-design.md',
+            'commands/apt-diagram.md',
+            'commands/apt-discuss.md',
+            'commands/apt-docs.md',
+            'commands/apt-execute.md',
+            'commands/apt-fan-out.md',
+            'commands/apt-handoff.md',
+            'commands/apt-improve.md',
+            'commands/apt-mockup.md',
+            'commands/apt-pause.md',
+            'commands/apt-personas.md',
+            'commands/apt-plan.md',
+            'commands/apt-pr-review.md',
+            'commands/apt-prototype.md',
+            'commands/apt-quick.md',
+            'commands/apt-release-notes.md',
+            'commands/apt-resume.md',
+            'commands/apt-review.md',
+            'commands/apt-roadmap.md',
+            'commands/apt-roundtable.md',
+            'commands/apt-run.md',
+            'commands/apt-scan.md',
+            'commands/apt-setup.md',
+            'commands/apt-ship.md',
+            'commands/apt-spar.md',
+            'commands/apt-stress-test.md',
+            'commands/apt-terminal.md',
+            'commands/apt-triage.md',
+            'commands/apt-update.md',
+            'commands/apt-verify.md',
+            'commands/apt-verify-proof.md',
+            'commands/apt-watch-ci.md',
+            'commands/apt-zoom-out.md',
+            // agents/<basename>.md — packages/framework/agents/apt-*.md (17 files)
+            // (overlap with skills/apt-*.md top-level — same outputPath, de-dupe)
+            'agents/apt-docs-author.md',
+            'agents/apt-executor.md',
+            'agents/apt-improver.md',
+            'agents/apt-planner.md',
+            'agents/apt-pr-review-codebase-fit.md',
+            'agents/apt-pr-review-fixer.md',
+            'agents/apt-pr-review-logic.md',
+            'agents/apt-pr-review-performance.md',
+            'agents/apt-pr-review-quality.md',
+            'agents/apt-pr-review-security.md',
+            'agents/apt-pr-review-self-reviewer.md',
+            'agents/apt-pr-review-test-integrity.md',
+            'agents/apt-pr-review-validator.md',
+            'agents/apt-researcher.md',
+            'agents/apt-reviewer.md',
+            'agents/apt-team-docs-narrator.md',
+            'agents/apt-verifier.md',
         ]),
     }),
 });

package/dist/cli/install/legacy-paths.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"legacy-paths.mjs","sourceRoot":"","sources":["../../../src/cli/install/legacy-paths.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,qHAAqH;AACrH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC;IACjD,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC;QACpB,YAAY,EAAE,gBAAgB;QAC9B,YAAY,EAAE,6BAA6B;QAC3C,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC;YAC9B,cAAc;YACd,cAAc;YACd,oBAAoB;YACpB,sBAAsB;YACtB,iDAAiD;YACjD,mBAAmB;YACnB,sBAAsB;YACtB,oBAAoB;YACpB,mBAAmB;YACnB,yBAAyB;YACzB,wBAAwB;YACxB,wCAAwC;YACxC,6CAA6C;YAC7C,oBAAoB;YACpB,qBAAqB;YACrB,qBAAqB;YACrB,sBAAsB;YACtB,yBAAyB;YACzB,kBAAkB;YAClB,mBAAmB;YACnB,oBAAoB;YACpB,mBAAmB;YACnB,0BAA0B;YAC1B,qBAAqB;YACrB,2BAA2B;YAC3B,kDAAkD;YAClD,yDAAyD;YACzD,8CAA8C;SAC9C,CAAC;KACF,CAAC;CACF,CAAC,CAAA"}
+{"version":3,"file":"legacy-paths.mjs","sourceRoot":"","sources":["../../../src/cli/install/legacy-paths.mjs"],"names":[],"mappings":"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"}