@aperant/framework 0.8.1 → 0.8.6

package/src/cli/install/find-workspace-framework-version.mjs

@@ -0,0 +1,88 @@
+/**
+ * install/find-workspace-framework-version.mjs — Bundle A.
+ *
+ * Locates the workspace `packages/framework/package.json` above `targetDir`
+ * so the SessionStart worker and `apt-tools check-version` can detect the
+ * "self-host contributor's workspace is ahead of the installed kernel" case
+ * WITHOUT requiring the user to remember the `--from-source` flag.
+ *
+ * Mirrors the bounded-walk + semver-validation contract of the route-side
+ * `detectSourceWorkspaceDrift` (route/drift-detect.mjs:32-107), but returns
+ * just the source workspace metadata — the caller decides whether to flip
+ * `update_available` (worker / check-version branch on the comparison).
+ *
+ * Safe for hot paths: synchronous, file-existence + JSON parse only,
+ * bounded walk (6 segments max), no network, no spawn.
+ *
+ * Security: workspace `package.json:version` is validated against the same
+ * `SEMVER_RE` as `update-chips.mjs` so a poisoned `package.json` cannot
+ * propagate a non-semver value into downstream envelopes.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { SEMVER_RE } from '../util/semver.mjs'
+
+/** Max directory frames to walk before giving up. Mirrors route/drift-detect.mjs:32. */
+const MAX_WALK_DEPTH = 6
+
+/**
+ * Walk up from `start`, returning every directory frame including `start`
+ * itself. Stops at the filesystem root or at depth `MAX_WALK_DEPTH`
+ * (whichever comes first).
+ *
+ * @param {string} start
+ * @returns {string[]}
+ */
+function walkUp(start) {
+	const frames = []
+	let cur = start
+	for (let i = 0; i < MAX_WALK_DEPTH; i++) {
+		frames.push(cur)
+		const parent = dirname(cur)
+		if (parent === cur) break
+		cur = parent
+	}
+	return frames
+}
+
+/**
+ * Find the workspace `@aperant/framework` package above `targetDir`.
+ *
+ * @param {string} targetDir  Absolute path to start the walk from.
+ * @returns {null | { source_path: string, source_version: string }}
+ *   `source_path` is the absolute path to `packages/framework/package.json`.
+ *   `source_version` is the semver-validated `version` field. Returns null
+ *   when no workspace package is found, when the workspace package name is
+ *   not `@aperant/framework`, or when the workspace version fails the
+ *   semver-shape check.
+ */
+export function findWorkspaceFrameworkVersion(targetDir) {
+	if (!targetDir || typeof targetDir !== 'string') return null
+
+	for (const dir of walkUp(targetDir)) {
+		const candidate = join(dir, 'packages', 'framework', 'package.json')
+		if (!existsSync(candidate)) continue
+
+		let pkg
+		try {
+			pkg = JSON.parse(readFileSync(candidate, 'utf-8'))
+		} catch {
+			continue
+		}
+
+		// Guard against false matches on unrelated monorepos that happen to
+		// have a `packages/framework/` directory.
+		if (pkg?.name !== '@aperant/framework') continue
+
+		const sourceVersion = pkg?.version
+		if (typeof sourceVersion !== 'string' || !SEMVER_RE.test(sourceVersion)) continue
+
+		return {
+			source_path: candidate,
+			source_version: sourceVersion,
+		}
+	}
+
+	return null
+}

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

@@ -0,0 +1,276 @@
+/**
+ * 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 (none today after
+ * the 0.8.5 driver-sdk inline, but the walker is general). Hands the full
+ * tarball list to a single `npm install --prefix` invocation so any future
+ * 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 })
+	}
+}

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

@@ -120,6 +120,30 @@ export function installKernel(targetDir, version, opts = {}) {
 	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/src/cli/install/legacy-paths.mjs

@@ -11,18 +11,28 @@
  *     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).
  *   } }
@@ -30,40 +40,155 @@
  * 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-research.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-research.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/src/cli/install/runtime-detect.mjs

@@ -50,7 +50,7 @@ export const RUNTIMES = Object.freeze([
 	{
 		id: 'codex',
 		flag: '--codex',
-		installRoot: '.codex',
+		installRoot: '.agents',
 		markers: ['.codex/config.toml'],
 		cliId: 'codex',
 	},