@nichollasf/ai-kit 1.0.1

package/dist/manifest.js

@@ -0,0 +1,223 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { normalizeSelection } from "./catalog.js";
+import { MANAGED_PATHS as V2_PATHS, LEGACY_V1_REQUIRED_PATHS, LEGACY_V1_CODEX_PATHS, } from "./legacy.js";
+export const MANIFEST_PATH = ".agents/.ai-kit-manifest.json";
+export const MANIFEST_SCHEMA_VERSION = 3;
+export const PROFILE = "personal";
+export const PACKAGE_ROOT = fileURLToPath(new URL("../", import.meta.url));
+export function sha256(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+export function resolveOwnedPath(target, relativePath) {
+    return path.join(target, ...relativePath.split("/"));
+}
+function object(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Manifest must contain objects.");
+    return value;
+}
+function keys(record, allowed) {
+    if (Object.keys(record).some((k) => !allowed.includes(k)))
+        throw new Error("Manifest has unknown fields.");
+}
+function checksum(value) {
+    if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value))
+        throw new Error("Manifest checksum is invalid.");
+    return value;
+}
+export function validateOwnedPath(value, allowedPaths) {
+    if (typeof value !== "string" ||
+        value.includes("\\") ||
+        path.posix.isAbsolute(value) ||
+        path.posix.normalize(value) !== value ||
+        value.split("/").includes("..") ||
+        !allowedPaths.has(value))
+        throw new Error(`Manifest contains an unsafe owned path: ${String(value)}`);
+    return value;
+}
+function parseFiles(value, allowed, legacy) {
+    if (!Array.isArray(value) || !value.length)
+        throw new Error("Manifest files must be non-empty.");
+    const seen = new Set();
+    return value.map((entry) => {
+        const record = object(entry);
+        keys(record, legacy ? ["path", "sha256"] : ["path", "sha256", "kind", "linkTarget"]);
+        const ownedPath = validateOwnedPath(record.path, allowed);
+        if (seen.has(ownedPath))
+            throw new Error(`Duplicate manifest path: ${ownedPath}`);
+        seen.add(ownedPath);
+        const kind = legacy ? "file" : record.kind;
+        if (kind !== "file" && kind !== "symlink")
+            throw new Error("Invalid artifact kind.");
+        const file = {
+            path: ownedPath,
+            sha256: checksum(record.sha256),
+            kind,
+        };
+        if (kind === "symlink") {
+            const link = record.linkTarget;
+            if (typeof link !== "string" ||
+                !link ||
+                link.includes(path.sep === "/" ? "\\" : "/") ||
+                path.parse(link).root !== "" ||
+                path.normalize(link) !== link ||
+                sha256(link) !== file.sha256)
+                throw new Error(`Invalid link target: ${ownedPath}`);
+            file.linkTarget = link;
+        }
+        else if (record.linkTarget !== undefined)
+            throw new Error("File must not contain linkTarget.");
+        return file;
+    });
+}
+export function parseManifest(value, allowedPaths = []) {
+    const record = object(value);
+    const version = record.schemaVersion;
+    if (![1, 2, 3].includes(version))
+        throw new Error(`Unsupported manifest schema: ${String(version)}`);
+    const legacy = version !== 3;
+    keys(record, legacy
+        ? [
+            "schemaVersion",
+            "packageVersion",
+            "profile",
+            "installedAt",
+            "files",
+            ...(version === 2 ? ["catalog", "renderedFiles"] : []),
+        ]
+        : [
+            "schemaVersion",
+            "packageVersion",
+            "profile",
+            "installedAt",
+            "files",
+            "selection",
+            "presets",
+            "catalog",
+        ]);
+    if (typeof record.packageVersion !== "string" ||
+        !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(record.packageVersion))
+        throw new Error("Invalid package version.");
+    if (typeof record.installedAt !== "string" ||
+        Number.isNaN(Date.parse(record.installedAt)))
+        throw new Error("Invalid installation timestamp.");
+    if (record.profile !== (legacy ? "openai-pro" : PROFILE))
+        throw new Error("Unsupported manifest profile.");
+    const allowed = new Set(legacy ? [...V2_PATHS, ...LEGACY_V1_REQUIRED_PATHS] : allowedPaths);
+    const files = parseFiles(record.files, allowed, legacy);
+    const common = {
+        packageVersion: record.packageVersion,
+        installedAt: record.installedAt,
+        files,
+    };
+    if (legacy) {
+        const actual = new Set(files.map((f) => f.path));
+        const candidates = version === 1
+            ? [
+                LEGACY_V1_REQUIRED_PATHS,
+                [...LEGACY_V1_REQUIRED_PATHS, ...LEGACY_V1_CODEX_PATHS],
+            ]
+            : [V2_PATHS];
+        if (!candidates.some((candidate) => candidate.length === actual.size &&
+            candidate.every((p) => actual.has(p))))
+            throw new Error(`Manifest v${version} does not contain a complete historical file set; refusing migration.`);
+        const result = {
+            schemaVersion: version,
+            profile: "openai-pro",
+            ...common,
+        };
+        if (version === 2) {
+            const catalog = object(record.catalog);
+            keys(catalog, ["baseSha256", "overlaySha256"]);
+            result.catalog = {
+                baseSha256: checksum(catalog.baseSha256),
+                overlaySha256: checksum(catalog.overlaySha256),
+            };
+            const rendered = parseFiles(record.renderedFiles, allowed, true);
+            const expected = V2_PATHS.filter((p) => p.startsWith(".codex/") || p.startsWith(".kilo/"));
+            if (rendered.length !== expected.length ||
+                rendered.some((f) => !expected.includes(f.path) ||
+                    !files.some((all) => all.path === f.path && all.sha256 === f.sha256)))
+                throw new Error("Legacy rendered inventory is inconsistent.");
+        }
+        return result;
+    }
+    const selectionRecord = object(record.selection);
+    keys(selectionRecord, ["harnesses", "archetypes", "method", "primary"]);
+    const selection = normalizeSelection(selectionRecord);
+    const presets = object(record.presets);
+    if (Object.keys(presets).length !== selection.harnesses.length ||
+        selection.harnesses.some((h) => presets[h] !==
+            (h === "opencode"
+                ? "gpt-default+claude"
+                : h === "codex"
+                    ? "gpt"
+                    : "claude")))
+        throw new Error("Manifest presets do not match selection.");
+    const catalog = object(record.catalog);
+    keys(catalog, ["baseSha256"]);
+    const byPath = new Map(files.map((f) => [f.path, f]));
+    for (const file of files) {
+        if (file.kind !== "symlink")
+            continue;
+        const destination = path.posix.join(path.posix.dirname(file.path), file.linkTarget.split(path.sep).join("/"));
+        const target = byPath.get(destination);
+        if (!destination.startsWith(".agents/") ||
+            !target ||
+            target.kind !== "file")
+            throw new Error(`Link must point directly to a known canonical file: ${file.path}`);
+    }
+    return {
+        schemaVersion: 3,
+        profile: PROFILE,
+        ...common,
+        selection,
+        presets: presets,
+        catalog: { baseSha256: checksum(catalog.baseSha256) },
+    };
+}
+export function manifestFile(asset) {
+    const file = {
+        path: asset.path,
+        sha256: asset.sha256,
+        kind: asset.kind ?? "file",
+    };
+    if (asset.linkTarget !== undefined)
+        file.linkTarget = asset.linkTarget;
+    return file;
+}
+export function createManifest(packageVersion, assets, selection, baseSha256) {
+    return {
+        schemaVersion: 3,
+        packageVersion,
+        profile: PROFILE,
+        installedAt: new Date().toISOString(),
+        selection,
+        presets: Object.fromEntries(selection.harnesses.map((h) => [
+            h,
+            h === "opencode"
+                ? "gpt-default+claude"
+                : h === "codex"
+                    ? "gpt"
+                    : "claude",
+        ])),
+        catalog: { baseSha256 },
+        files: assets
+            .map(manifestFile)
+            .sort((a, b) => a.path.localeCompare(b.path)),
+    };
+}
+export function serializeManifest(manifest) {
+    return Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`);
+}
+export async function readPackageVersion(packageRoot = PACKAGE_ROOT) {
+    const value = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8"));
+    if (typeof value.version !== "string" ||
+        !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(value.version))
+        throw new Error("Package version missing or invalid.");
+    return value.version;
+}
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"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"}

package/dist/transaction.d.ts

@@ -0,0 +1,10 @@
+import { type Asset, type ManifestFile } from "./manifest.js";
+export interface FileChange {
+    path: string;
+    asset?: Asset;
+    expected?: ManifestFile;
+}
+export declare function exists(filePath: string): Promise<boolean>;
+export declare function assertAncestors(target: string, relativePath: string): Promise<void>;
+export declare function verifyState(target: string, relativePath: string, expected?: ManifestFile): Promise<void>;
+export declare function applyTransaction(target: string, changes: readonly FileChange[], beforeStep?: (index: number) => Promise<void>): Promise<string[]>;

package/dist/transaction.js

@@ -0,0 +1,187 @@
+import { lstat, mkdir, mkdtemp, readFile, readlink, rename, rm, rmdir, symlink, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { MANIFEST_PATH, resolveOwnedPath, sha256, } from "./manifest.js";
+export async function exists(filePath) {
+    try {
+        await lstat(filePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export async function assertAncestors(target, relativePath) {
+    let current = target;
+    for (const segment of relativePath.split("/").slice(0, -1)) {
+        current = path.join(current, segment);
+        try {
+            const info = await lstat(current);
+            if (info.isSymbolicLink() || !info.isDirectory())
+                throw new Error(`Managed path traverses a symbolic link or non-directory: ${path.relative(target, current)}`);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw error;
+        }
+    }
+}
+export async function verifyState(target, relativePath, expected) {
+    await assertAncestors(target, relativePath);
+    const absolute = resolveOwnedPath(target, relativePath);
+    if (!(await exists(absolute))) {
+        if (expected)
+            throw new Error(`Owned path is missing: ${relativePath}`);
+        return;
+    }
+    if (!expected)
+        throw new Error(`Unowned collision; no changes made: ${relativePath}`);
+    const info = await lstat(absolute);
+    if (expected.kind === "symlink") {
+        if (!info.isSymbolicLink() ||
+            (await readlink(absolute)) !== expected.linkTarget)
+            throw new Error(`Owned link was modified: ${relativePath}`);
+    }
+    else if (!info.isFile() ||
+        info.isSymbolicLink() ||
+        sha256(await readFile(absolute)) !== expected.sha256)
+        throw new Error(`Owned file was modified: ${relativePath}`);
+}
+async function makeDirectories(target, relative, created) {
+    let current = target;
+    for (const segment of relative
+        .split("/")
+        .filter((x) => x !== "." && x !== "")) {
+        current = path.join(current, segment);
+        try {
+            await mkdir(current);
+            created.push(current);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const info = await lstat(current);
+            if (info.isSymbolicLink() || !info.isDirectory())
+                throw new Error(`Unsafe directory: ${current}`);
+        }
+    }
+}
+export async function applyTransaction(target, changes, beforeStep) {
+    if (changes.at(-1)?.path !== MANIFEST_PATH)
+        throw new Error("Manifest must be applied last.");
+    for (const change of changes)
+        await verifyState(target, change.path, change.expected);
+    const created = [];
+    let staging;
+    const applied = [];
+    let lock;
+    try {
+        await makeDirectories(target, ".agents", created);
+        const lockPath = resolveOwnedPath(target, ".agents/.ai-kit-lock");
+        try {
+            await mkdir(lockPath);
+            lock = lockPath;
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                throw new Error("Another ai-kit transaction or stale .agents/.ai-kit-lock exists; inspect it before retrying.");
+            throw error;
+        }
+        staging = await mkdtemp(resolveOwnedPath(target, ".agents/.ai-kit-tx-"));
+        await mkdir(path.join(staging, "staged"));
+        await mkdir(path.join(staging, "backup"));
+        for (const [index, change] of changes.entries()) {
+            if (!change.asset)
+                continue;
+            const staged = path.join(staging, "staged", String(index));
+            if (change.asset.kind === "symlink") {
+                try {
+                    await symlink(change.asset.linkTarget, staged, "file");
+                }
+                catch {
+                    throw new Error("Unable to create symlinks; retry with --method copy. No automatic fallback.");
+                }
+            }
+            else
+                await writeFile(staged, change.asset.content, {
+                    mode: 0o644,
+                    flag: "wx",
+                });
+        }
+        // Validate every expectation again after staging, before touching owned data.
+        for (const change of changes)
+            await verifyState(target, change.path, change.expected);
+        for (const [index, change] of changes.entries()) {
+            await beforeStep?.(index);
+            await verifyState(target, change.path, change.expected);
+            const destination = resolveOwnedPath(target, change.path);
+            await makeDirectories(target, path.posix.dirname(change.path), created);
+            const record = { change };
+            if (change.expected) {
+                const backup = path.join(staging, "backup", String(index));
+                await rename(destination, backup);
+                record.backup = backup;
+            }
+            applied.push(record);
+            if (change.asset)
+                await rename(path.join(staging, "staged", String(index)), destination);
+        }
+    }
+    catch (error) {
+        const failures = [];
+        for (const record of applied.reverse()) {
+            try {
+                await assertAncestors(target, record.change.path);
+                const destination = resolveOwnedPath(target, record.change.path);
+                if (await exists(destination)) {
+                    const asset = record.change.asset;
+                    if (!asset)
+                        throw new Error(`Path appeared during rollback: ${record.change.path}`);
+                    await verifyState(target, record.change.path, {
+                        path: asset.path,
+                        sha256: asset.sha256,
+                        kind: asset.kind ?? "file",
+                        ...(asset.linkTarget === undefined
+                            ? {}
+                            : { linkTarget: asset.linkTarget }),
+                    });
+                    await rm(destination);
+                }
+                if (record.backup)
+                    await rename(record.backup, destination);
+            }
+            catch (rollbackError) {
+                failures.push(rollbackError.message);
+            }
+        }
+        if (failures.length)
+            throw new Error(`Transaction failed; rollback incomplete. Backups and lock preserved at ${staging}: ${failures.join("; ")}`);
+        if (staging)
+            await rm(staging, { recursive: true, force: true });
+        if (lock)
+            await rmdir(lock);
+        for (const dir of created.reverse()) {
+            try {
+                await rmdir(dir);
+            }
+            catch {
+                /* Preserve concurrent/unrelated entries. */
+            }
+        }
+        throw error;
+    }
+    const warnings = [];
+    try {
+        if (staging)
+            await rm(staging, { recursive: true, force: true });
+        if (lock)
+            await rmdir(lock);
+    }
+    catch {
+        warnings.push(`Committed, but transaction cleanup failed: ${staging}`);
+    }
+    return warnings;
+}
+//# sourceMappingURL=transaction.js.map

package/dist/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"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"}

package/docs/architecture.md

@@ -0,0 +1,61 @@
+# Architecture decision: portable archetype catalog
+
+Status: accepted for version 1.0.0 after implementation and independent review. Date: 2026-09-12. This supersedes the initial Kilo/Codex `openai-pro` architecture. The `ai-kit` executable remains unchanged; manifest v3, removal of Kilo support and the new role/layout contracts justify the major-version transition from 0.1.0. The user explicitly authorized commit, push and publication, subject to checking that no personal credentials are exposed.
+
+Version 1.0.1 corrects the npm package name to `@nichollasf/ai-kit`, the authenticated npm account explicitly selected by the user. The GitHub repository remains `nychollas09/ai-kit`. The v1.0.0 GitHub release used the earlier scope, which was never published to npm. This metadata correction does not change installer ownership or role contracts.
+
+## Decision
+
+Keep three distinct concepts: seven model-free archetypes, a versioned JSON model/effort binding catalog, and harness-specific materialization. `.agents` is ai-kit's canonical convention; discovery uses each harness's documented paths. Support only project installs for Claude Code, Codex and OpenCode. Global installs, LSP, arbitrary wizard-selected models and silent fallback are outside scope.
+
+The selection/install interaction takes inspiration from [Matt Pocock's Skills collection](https://github.com/mattpocock/skills). Responsibility separation combines the orchestrator-worker and evaluator-optimizer patterns described by [Anthropic](https://www.anthropic.com/engineering/building-effective-agents) and [Cursor's planner/worker report](https://cursor.com/blog/scaling-agents). Planning is not recursive.
+
+Planner chooses architecture and defines tasks but cannot delegate or implement. Orchestrator dispatches an approved plan without implementing or replanning. `implementer-senior` remains the existing identifier and becomes a complex implementation worker. Implementer and Quick have bounded execution scopes. Researcher gathers evidence; Reviewer independently reviews without editing the work. Only Orchestrator delegates; every worker returns to it. Cap concurrent workers at four and require independent review for non-trivial changes.
+
+Contracts record mission, activation, inputs, deliverables, allowed actions, prohibitions, write scope, escalation and the fixed handoff. Approval digests detect changed plan bytes; they do not establish authorization. Evidence freshness, dependency checks, scope separation and approval provenance remain behavioral obligations.
+
+## Catalog and materialization
+
+`personal.json` has schemaVersion 2 and profile `personal`. `catalog-v2.schema.json` documents its exact structure. The zero-dependency runtime validator rejects unknown fields, relaxed authority, unsafe model IDs, `latest`, unsupported efforts and invalid routes. Archetype frontmatter supports only two scalar fields: JSON-quoted `description` and an explicit `mode`, with LF newlines. No generic YAML parser is shipped.
+
+Each role has GPT and Claude bindings; harness presets select one binding family. OpenCode installs both families with GPT default. Stable aliases name archetype, explicit model ID and effort; convenience aliases retain the archetype and expose `-claude` separately in OpenCode. Haiku's unsupported effort is represented in the catalog, with no emitted parameter. The GPT effort matrix is preserved, adding Orchestrator at xhigh. The user-required presets are recorded in the README and catalog.
+
+The source catalog distributes intentional model changes through package updates. Installed overlays never override the presets. Current source legacy `openai-pro.json`, schema and prompts were preserved when incorporating the initial worktree; the package excludes them. User plans/evaluations remain outside the installer inventory.
+
+Materialization emits canonical regular files under `.agents/generated/<harness>`, plus per-file discovery links or equivalent copies. Every link points directly to a known regular canonical file; there are no symlink chains, directory links or targets outside the installation. `.agents/generated/selection.json` records the chosen roles/harnesses and whether the full-team workflow is enabled. Any incomplete team disables orchestration across adapters and routing skills. Optional `selection.primary` chooses a selected standalone role; `update --primary` preserves the installed inventory while switching the main role transactionally. Full-team primary remains Orchestrator.
+
+## Adapters and enforcement
+
+| Adapter     | Discovery and configuration                                                                                                       | Relevant official contract                                                                                                                                        |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| OpenCode    | `.opencode/agents/*.md`; root `opencode.json`; primary Orchestrator, explicit task allowlist; native `.agents/skills`             | [Agents](https://opencode.ai/docs/agents/), [configuration](https://opencode.ai/docs/config/), [skills](https://opencode.ai/docs/skills/)                         |
+| Claude Code | Separate Markdown frontmatter in `.claude/agents`; `.claude/settings.json` selects main Orchestrator; `.claude/skills` file links | [Subagents](https://code.claude.com/docs/en/sub-agents), [settings](https://code.claude.com/docs/en/settings)                                                     |
+| Codex       | TOML role layers in `.codex/agents`; `.codex/config.toml` registers roles and main Orchestrator; native `.agents/skills`          | [Configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference), [subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents) |
+
+Claude's `Agent(...)` allowlist only applies when the profile is the main agent. Workers explicitly deny `Agent` and `Task`; read-only roles omit shell/write tools. Planner retains Write/Edit with a behavioral `.agents/plans` scope. The main settings set depth one and concurrency four; documented harness exceptions mean the concurrency contract also appears in instructions. [Claude model and effort documentation](https://platform.claude.com/docs/en/models/overview) establishes the requested IDs and Haiku's lack of effort control.
+
+OpenCode uses native permissions to prevent worker Task delegation and restrict Orchestrator dispatch. Planner editing is limited to planning paths; read-only roles deny edit and shell. Its four-worker cap and task-specific write scope are behavioral. The primary's configured GPT route remains available if an unselected Claude model is absent.
+
+Codex workers set `agents.enabled=false`; planner/researcher/reviewer use read-only sandboxes. The main Orchestrator uses workspace-write, because broader permissions in a worker must not be assumed to escape a read-only parent. No-product-edit and exact registered-profile dispatch remain behavioral constraints in the main context. Codex built-in roles and explicit CLI overrides are not represented as a hard allowlist. The four-worker setting uses `max_concurrent_threads_per_session`, excluding the main context. The read-only Planner returns plan text in its handoff for the user to save. Claude/OpenCode roles without hash tools require fresh trusted external hash verification plus the verified plan snapshot; they must not fabricate a cryptographic result.
+
+Runtime Codex diagnostics deliberately avoid `config/read`: an isolated synthetic-sentinel test proved that 0.154.0 returns unredacted MCP environment values. The safe `doctor --json` exposes redacted parse/model/auth status but cannot establish effective project trust or all role settings, so `check` reports that layer unverified and returns 4. Integration may use the richer API only against isolated empty/synthetic stores.
+
+Native integration verifies configuration parsing/discovery and exposed capabilities without making model calls. This is evidence about configuration, not proof that a model obeys a prompt. Account entitlement and personal configuration can change readiness independently of structural correctness. Local validated versions: Codex 0.154.0, Claude Code 2.1.265, OpenCode 1.18.30.
+
+## Ownership, transaction and migration
+
+Manifest v3 records package version, selection, presets, catalog checksum and an exact artifact list. Regular file entries record SHA-256 of bytes. Symlinks record their exact relative target with native platform separators and SHA-256 of that target string; the canonical target has a separate file checksum. Manifest artifact paths retain portable forward slashes. Alternate separator spellings and non-normalized link targets are rejected rather than accepted through equivalence checks.
+
+The parser accepts only an enumerated renderer inventory, with complete selection/method consistency and direct canonical link targets. It never infers ownership from a directory. During v3 updates, the installer first validates the checksum of the fixed regular catalog path, validates that catalog, and derives its exact old aliases. This lets reviewed source-model updates retire earlier aliases without granting ownership to arbitrary files.
+
+Legacy v1/v2 manifests require a complete known historical inventory. Every owned file must be intact. Migration removes only recorded retired artifacts, including Kilo profiles, and preserves personal Kilo configuration, unowned files, plans and evaluations. It does not enumerate or open personal Kilo settings. Existing overlays remain unmanaged: incompatible overrides stop migration before writes; empty legacy metadata may remain.
+
+Preflight validates the real project target, managed ancestors, final artifact types, checksums, link targets and all unowned collisions. Whole configuration files are owned; no automatic merge is attempted. Alternate OpenCode JSON/JSONC project configs and Claude settings.local.json are rejected by existence checks without reading their contents. Staging and backups use the target filesystem. A cooperating installer lock prevents concurrent transactions. All expectations are rechecked after staging and before each change. Backups preserve file/link types, rollback unwinds applied changes, and the manifest commits last. Only directories created during a failed transaction are candidates for rollback cleanup; existing empty directories are preserved.
+
+`--dry-run` performs preflight with no files, directories, locks or harness processes created. If symlink creation is unsupported, staging aborts and recommends explicit copy mode. Incomplete rollback preserves backups and the lock with a diagnostic path. The transaction is exception-atomic; power loss/process termination recovery is manual, and this does not claim an OS-level isolation boundary against concurrent hostile filesystem mutation.
+
+## Validation and release gate
+
+`npm run check` includes format, typecheck, catalog/CLI/installer tests and package checks. `npm run test:integration` exercises native harnesses with temporary isolated configuration stores, no credential copying and no model calls. Tests inspect effective discovery and permissions, relative links/copies, space-containing paths, collisions, tampering, rollback, v1/v2 migration, v3 model-alias updates and zero-write dry-runs. A tarball test installs through offline `npx` into a temporary project.
+
+`npm pack --dry-run --json` must match an exact allowlist. Runtime dependencies remain zero; package content excludes local overlays, credentials, plans, evaluations and third-party skills. Review contracts, adapters, ownership and migrations independently before completion. Major/layout breaks, permission broadening and a future force option require architecture and major-version review; no force flag is introduced here.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@nichollasf/ai-kit",
+  "version": "1.0.1",
+  "description": "A portable, project-scoped archetype catalog for Claude Code, Codex and OpenCode.",
+  "type": "module",
+  "bin": {
+    "ai-kit": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    ".agents/catalog/catalog-v2.schema.json",
+    ".agents/catalog/personal.json",
+    ".agents/archetypes/*.md",
+    ".agents/skills/ai-kit-model-calibration/",
+    ".agents/skills/ai-kit-task-routing/",
+    "README.md",
+    "docs/architecture.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node --input-type=module -e \"import { chmodSync } from 'node:fs'; chmodSync('dist/cli.js', 0o755)\"",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "npm run build && node --import tsx --test test/installer.test.ts test/catalog.test.ts test/cli.test.ts",
+    "test:integration": "npm run build && node --import tsx --test test/harness.integration.test.ts test/codex.integration.test.ts",
+    "package:check": "npm run build && node --import tsx --test test/package.test.ts",
+    "check": "npm run format:check && npm run typecheck && npm test && npm run package:check"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/nychollas09/ai-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nychollas09/ai-kit/issues"
+  },
+  "homepage": "https://github.com/nychollas09/ai-kit#readme",
+  "license": "MIT",
+  "author": "Nichollas",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "opencode",
+    "agents",
+    "ai",
+    "cli"
+  ],
+  "devDependencies": {
+    "@openai/codex": "0.154.0",
+    "@types/node": "24.3.1",
+    "prettier": "3.6.2",
+    "tsx": "4.20.5",
+    "typescript": "5.9.2"
+  }
+}