@zedtech/zedkit-ai 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zedtech-fr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,176 @@
-# Temporary Holding Version
+# @zedtech/zedkit-ai
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An agent-agnostic AI setup for a code repo: an `AGENTS.md` template, skills,
+subagents, and a small installer and validator. Works with Claude Code,
+Cursor, Codex, Muse and any tool that reads `AGENTS.md` or Agent Skills.
+Original work by the same author, plus vendored MIT skills (see
+[kit/THIRD_PARTY_NOTICES.md](kit/THIRD_PARTY_NOTICES.md)).
+
+## Use it
+
+Not published to npm yet. From a zedkit checkout, pack the tarballs;
+then in your own repo, install and run with `npx`:
+
+```sh
+for p in ai core; do (cd packages/$p && pnpm pack --pack-destination /tmp/zedkit-pack); done
+npm install --no-save /tmp/zedkit-pack/*.tgz   # in your own repo
+npx zedkit-ai init .               # copy the core kit into this repo
+# then ask your agent: "run the setup-ai skill"
+npx zedkit-ai validate             # check skills and subagents
+```
+
+With pnpm instead of npm, pin the unpacked core tarball first (pnpm
+resolves each tarball's dependencies independently — this goes away once
+the packages publish):
+
+```sh
+mkdir -p /tmp/zedkit-core && tar -xzf /tmp/zedkit-pack/zedkit-core-*.tgz -C /tmp/zedkit-core
+# package.json: { "pnpm": { "overrides": { "@zedtech/zedkit-core": "file:/tmp/zedkit-core/package" } } }
+pnpm add /tmp/zedkit-pack/zedtech-zedkit-ai-0.1.0.tgz
+./node_modules/.bin/zedkit-ai init . --provider cursor
+./node_modules/.bin/zedkit-ai validate   # must print: ok
+```
+
+`init` installs generic instructions. The `setup-ai` skill makes them specific:
+it explores the repo (code, docs, CI, history), runs the commands it finds,
+then fills `AGENTS.md` with verified facts and proposes repo-specific nested
+rules, skills and subagents. If a setup already exists (`AGENTS.md`,
+`.cursor/rules`, `CLAUDE.md`, ...), it audits it first (stale, contradictory,
+duplicated, too long) and improves it in place instead of replacing it.
+`setup-ai` also fills the template's `Role and style` section (role, tone,
+reply language) from repo evidence — docs language, commit style — asking a
+single question when the evidence cannot tell. At a multi-repo workspace
+root (several child checkouts) it switches to workspace mode: it inventories
+each repo, maps cross-repo dependencies, and writes a root `AGENTS.md`
+without touching the children unasked.
+
+Developing the kit itself? From a zedkit checkout, build once and call
+the binary directly: `pnpm --filter @zedtech/zedkit-ai build`, then
+`node packages/ai/dist/bin.js init <dir>`.
+
+`init` options: `--preset core|full`, `--provider cursor,claude,codex,muse,all`
+(`--target` is an alias), `--dry-run`. It copies files (you own them
+afterwards) and never overwrites an existing one; the one exception is an
+existing `AGENTS.md` without the ladder, which gets the ladder section
+appended (reported as `append`). It also skips
+`.cursor/rules/project.mdc` (with a skip line naming the rule) when another
+rule in `.cursor/rules/` is already always on (`alwaysApply: true`), instead
+of adding a second one. Run `zedkit-ai list` to see presets, subagents and
+commands.
+
+## Providers
+
+One shared source (`.agents/`), then a thin layer per provider:
+
+| Provider | Layer | Reads |
+|---|---|---|
+| `cursor` | `.cursor/rules/project.mdc`, `.cursor/skills` link, agents and commands as real-file copies | its `.cursor/` layer |
+| `claude` | `CLAUDE.md` link, `.claude/{skills,agents,commands}` links | its `.claude/` layer |
+| `codex` | none | `AGENTS.md` and `.agents/skills` directly |
+| `muse` | none | `.agents/` directly |
+
+Cursor gets copies because a symlinked folder shows up empty there. Copies
+can drift when `.agents/` changes: `zedkit-ai validate` reports each missing
+or drifted copy — fix it by copying the file over (init never overwrites).
+`setup-ai` takes provider names (`setup-ai cursor claude`) and asks once
+which providers to wire when it cannot tell.
+
+## What you get
+
+```
+AGENTS.md                  instructions every tool reads
+CLAUDE.md -> AGENTS.md
+.agents/skills/            workflows (the Agent Skills layout)
+.agents/agents/            subagents
+.agents/commands/          one-keystroke commands (thin: each runs a skill)
+.claude/{skills,agents,commands}  symlinks to .agents/
+.cursor/skills             symlink to .agents/skills
+.cursor/{agents,commands}  real-file copies (a link shows up empty)
+.cursor/rules/project.mdc  one always-on rule pointing at AGENTS.md
+```
+
+One source (`.agents/`), thin per-tool links. Nested `AGENTS.md` files hold
+per-folder rules.
+
+Commands (`review`, `plan`, `challenge`, `implement`, `setup-ai`, `pr`,
+`handoff`) are 3-6 line files: each runs its skill on the command arguments
+(or the current context). Both tools also list skills as `/` commands
+nowadays; the files stay as the explicit one-keystroke path and as fallback
+when the skills link is not followed.
+
+## The kit
+
+**Principles it enforces**
+
+- *Verify, do not guess* (`ground-truth`): read the source before relying on a
+  name, shape, flag or version; cite `file:line`; say what was not checked.
+- *Smallest complete change* (`ponytail`, MIT, vendored): reuse before adding.
+- *Parallel and context-aware* (`parallel-work`): fan out independent work to
+  subagents with self-contained briefs; contract first, disjoint files.
+- *Proven done* (`definition-of-done`, agent `verifier`): gates on the final
+  state, no weakened tests, refactor parity by reading bodies, cold second
+  review.
+
+**Skills first-party:** `ground-truth`, `parallel-work`, `definition-of-done`,
+`adversarial-tests`, `rules-upkeep`, `persona-review`, `setup-ai`, `use-zedkit`.
+
+**Entry points (one command per phase):** `review` (pins the diff, fans out
+`code-review` + `persona-review` + `adversarial-tests`/`security-reviewer`
+when relevant, one verdict), `plan` (`to-spec`/`to-tickets`/`wayfinder`, then
+`challenge`), `challenge` (`plan-challenger` + domain/design checks),
+`implement` (extended: challenged plan in, `definition-of-done`, `review`).
+All four live in the `core` preset; the detailed skills stay reusable and are
+never copied into them.
+
+**Skills vendored (MIT):** `ponytail` (+ review, audit, debt, gain, help) and
+the Matt Pocock engineering skills (`tdd`, `code-review`, `diagnosing-bugs`,
+`handoff`, `pr`, `to-spec`, `triage`, ...).
+
+**Subagents:** `explorer` (read-only lookup), `architect` (plan, never code),
+`plan-challenger` (pre-mortem and ranked objections), `verifier` (gate),
+`improver` (apply review findings, smallest diff), `security-reviewer`.
+
+**Presets:** `core` (the skills most projects benefit from; `zedkit-ai list`
+shows them) and `full` (all). Keep the skill count low: every skill's name and
+description is loaded into context up front (Codex caps that list at about 2%
+of the context window and shortens descriptions past it). Subagents are always
+installed; their files are only read when one is used.
+
+## Choices worth knowing
+
+- Subagent `model` is left unset (inherits). An unknown model id silently
+  falls back in some tools, so pin one in your project only after listing what
+  your tool accepts. The validator rejects any other value in the kit.
+- Subagent `description` is one line: a block (`>`) can be shown literally and
+  the agent is then never chosen. The validator checks it.
+- Read-only subagents say so in their prompt body and set
+  `disallowedTools: Write, Edit` (Claude Code honors it; other tools tolerate
+  the key). There is deliberately no `readonly:` key: at least one tool
+  silently drops a subagent file with an unknown field, so the validator
+  rejects it.
+- Cursor reads `.cursor/agents`, `.claude/agents` and `.codex/agents`
+  ([docs](https://cursor.com/docs/subagents), checked 2026-10-24); the installer
+  links `.cursor/agents` anyway so a Cursor-only repo needs nothing else.
+- Codex reads `.agents/skills` (it follows symlinks) and `AGENTS.md`
+  ([docs](https://developers.openai.com/codex/skills), checked 2026-10-24), so
+  it needs no adapter. The subagent files are not wired for Codex.
+- Muse reads `AGENTS.md`, `.agents/skills` and `.agents/agents` directly
+  (verified empirically 2026-10-24 with `muse skills list` and a headless
+  `muse exec` run: every core skill and all 6 subagents load), so it needs
+  no adapter either. It ignores the `.claude/` and `.cursor/` links. This is
+  how the `readonly:` ban above was found: files setting it never appear in
+  its agent list.
+- Symlinks need a filesystem that supports them (Windows: developer mode or
+  WSL).
+
+## API
+
+`installKit(options)` and `validateKit(dir)`: see [CATALOG.md](CATALOG.md).
+
+## Verify
+
+```sh
+pnpm --filter @zedtech/zedkit-ai typecheck && pnpm --filter @zedtech/zedkit-ai lint && pnpm --filter @zedtech/zedkit-ai build && pnpm --filter @zedtech/zedkit-ai test
+```
+
+The tests also validate the whole bundled kit.

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Original work by the same author.
+import { main } from "./cli.js";
+process.exitCode = main(process.argv.slice(2), {
+    out: (line) => console.log(line),
+    err: (line) => console.error(line),
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,oCAAoC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhC,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IAC7C,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;IAChC,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;CACnC,CAAC,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+/** Where the CLI writes: normal lines and error lines. */
+export type Sinks = {
+    out: (line: string) => void;
+    err: (line: string) => void;
+};
+/** Run the CLI. Returns the process exit code (0 ok, 1 validation problems, 2 usage or runtime error). */
+export declare function main(argv: string[], sinks: Sinks): number;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAyBA,0DAA0D;AAC1D,MAAM,MAAM,KAAK,GAAG;IAAE,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,CAAC;AAqFjF,0GAA0G;AAC1G,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,CAQzD"}

package/dist/cli.js

@@ -0,0 +1,123 @@
+// Original work by the same author.
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { err, ok, tryCatch } from "@zedtech/zedkit-core";
+import { installKit } from "./install.js";
+import { readManifest } from "./kit.js";
+import { checkDrift, validateKit } from "./validate.js";
+const USAGE = `zedkit-ai <command>
+
+  init [dir] [--preset core|full] [--provider ...] [--dry-run]
+      Copy skills, subagents, commands and an AGENTS.md template into dir
+      (default .), then wire the providers (default all). Never overwrites
+      existing files (an existing AGENTS.md without the ladder gets the
+      ladder section appended). --provider takes cursor,claude,codex,muse,all;
+      --target is an alias of --provider.
+  validate [dir]
+      Check skills, subagents and commands, plus provider-copy drift
+      (default dir: .agents; a project root is accepted too). Exit 1
+      on problems.
+  list
+      Show presets, subagents and commands.
+`;
+const OPTIONS = {
+    preset: { type: "string" },
+    provider: { type: "string" },
+    target: { type: "string" },
+    "dry-run": { type: "boolean" },
+};
+function parse(args, options, maxPositionals) {
+    const parsed = tryCatch(() => parseArgs({ args, allowPositionals: true, options }));
+    if (!parsed.ok)
+        return err(parsed.error);
+    if (parsed.value.positionals.length > maxPositionals) {
+        return err(new Error(`unexpected argument "${parsed.value.positionals[maxPositionals]}"`));
+    }
+    return ok(parsed.value);
+}
+function parseProviders(value) {
+    if (value === undefined)
+        return ok(undefined);
+    const names = String(value).split(",").map((s) => s.trim());
+    if (names.includes("all"))
+        return ok(undefined);
+    const bad = names.find((n) => n !== "claude" && n !== "cursor" && n !== "codex" && n !== "muse");
+    if (bad !== undefined)
+        return err(new Error(`unknown provider "${bad}" (cursor, claude, codex, muse, all)`));
+    return ok(names);
+}
+function fail(message, sinks) {
+    sinks.err(`error: ${message}`);
+    return 2;
+}
+function runInit(args, sinks) {
+    const parsed = parse(args, OPTIONS, 1);
+    if (!parsed.ok)
+        return fail(parsed.error.message, sinks);
+    const { values, positionals } = parsed.value;
+    const providers = parseProviders(values.provider ?? values.target);
+    if (!providers.ok)
+        return fail(providers.error.message, sinks);
+    const dryRun = values["dry-run"] === true;
+    const preset = typeof values.preset === "string" ? values.preset : undefined;
+    const result = installKit({
+        dest: resolve(positionals[0] ?? "."),
+        ...(preset !== undefined && { preset }),
+        ...(providers.value !== undefined && { providers: providers.value }),
+        dryRun,
+    });
+    if (!result.ok)
+        return fail(result.error.message, sinks);
+    for (const action of result.value) {
+        sinks.out(`${action.kind.padEnd(5)} ${action.path}${action.note ? `  (${action.note})` : ""}`);
+    }
+    sinks.out(dryRun ? "dry run: nothing written" : "next: ask your agent to run the `setup-ai` skill, then `zedkit-ai validate`");
+    return 0;
+}
+function runValidate(args, sinks) {
+    const parsed = parse(args, {}, 1);
+    if (!parsed.ok)
+        return fail(parsed.error.message, sinks);
+    const dir = resolve(parsed.value.positionals[0] ?? ".agents");
+    if (!existsSync(dir))
+        return fail(`no such directory: ${dir}`, sinks);
+    // A project root points at its .agents/; an .agents/ dir drifts against
+    // its own parent. Any other dir just has nothing to drift against.
+    const nested = join(dir, ".agents");
+    const agentsDir = existsSync(nested) ? nested : dir;
+    const projectRoot = agentsDir === dir ? dirname(dir) : dir;
+    const issues = [...validateKit(agentsDir), ...checkDrift(projectRoot, agentsDir)];
+    for (const issue of issues)
+        sinks.out(`${issue.path}: ${issue.message}`);
+    sinks.out(issues.length === 0 ? "ok" : `${issues.length} problem(s)`);
+    return issues.length === 0 ? 0 : 1;
+}
+function runList(args, sinks) {
+    const parsed = parse(args, {}, 0);
+    if (!parsed.ok)
+        return fail(parsed.error.message, sinks);
+    const manifest = readManifest();
+    if (!manifest.ok)
+        return fail(manifest.error.message, sinks);
+    for (const [name, skills] of Object.entries(manifest.value.presets)) {
+        sinks.out(`preset ${name}: ${skills === "*" ? "every skill" : skills.join(", ")}`);
+    }
+    sinks.out(`agents: ${manifest.value.agents.join(", ")}`);
+    sinks.out(`commands: ${(manifest.value.commands ?? []).join(", ") || "(none)"}`);
+    return 0;
+}
+/** Run the CLI. Returns the process exit code (0 ok, 1 validation problems, 2 usage or runtime error). */
+export function main(argv, sinks) {
+    const [command, ...rest] = argv;
+    if (command === "init")
+        return runInit(rest, sinks);
+    if (command === "validate")
+        return runValidate(rest, sinks);
+    if (command === "list")
+        return runList(rest, sinks);
+    const help = command === undefined || command === "--help" || command === "-h";
+    (help ? sinks.out : sinks.err)(USAGE.trimEnd());
+    return help ? 0 : 2;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/frontmatter.d.ts

@@ -0,0 +1,9 @@
+import { type Result } from "@zedtech/zedkit-core";
+export type Frontmatter = {
+    /** Parsed YAML mapping. */
+    data: Record<string, unknown>;
+    /** Frontmatter source text, without the `---` fences. */
+    raw: string;
+};
+export declare function parseFrontmatter(text: string): Result<Frontmatter>;
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAGtE,MAAM,MAAM,WAAW,GAAG;IACxB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAKF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,CAelE"}

package/dist/frontmatter.js

@@ -0,0 +1,22 @@
+// Original work by the same author.
+import { err, ok, tryCatch } from "@zedtech/zedkit-core";
+import { parse } from "yaml";
+// Optional BOM, opening fence, body (may be empty), closing fence.
+const FENCE = /^\uFEFF?---[ \t]*\n(?:([\s\S]*?)\n)?---[ \t]*(?:\n|$)/;
+export function parseFrontmatter(text) {
+    const match = FENCE.exec(text.replace(/\r\n/g, "\n"));
+    if (!match) {
+        return err(new Error("missing frontmatter (file must start with a --- block)"));
+    }
+    const raw = match[1] ?? "";
+    const parsed = tryCatch(() => parse(raw));
+    if (!parsed.ok) {
+        return err(new Error(`invalid YAML frontmatter: ${parsed.error.message}`));
+    }
+    const value = parsed.value ?? {};
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return err(new Error("frontmatter must be a YAML mapping"));
+    }
+    return ok({ data: value, raw });
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,QAAQ,EAAe,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAS7B,mEAAmE;AACnE,MAAM,KAAK,GAAG,uDAAuD,CAAC;AAEtE,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;IACtD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,GAAG,CAAC,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC,CAAC;IAClF,CAAC;IACD,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3B,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC,CAAC;IACrD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO,GAAG,CAAC,IAAI,KAAK,CAAC,6BAA6B,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAC7E,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;IACjC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACtD,OAAO,GAAG,CAAC,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,KAAgC,EAAE,GAAG,EAAE,CAAC,CAAC;AAC7D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { type Action, type InstallOptions, type Provider, type Target, installKit } from "./install.js";
+export { type Issue, checkDrift, validateKit } from "./validate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACxG,OAAO,EAAE,KAAK,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { installKit } from "./install.js";
+export { checkDrift, validateKit } from "./validate.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgE,UAAU,EAAE,MAAM,cAAc,CAAC;AACxG,OAAO,EAAc,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/install.d.ts

@@ -0,0 +1,36 @@
+import { type Result } from "@zedtech/zedkit-core";
+export type Provider = "claude" | "cursor" | "codex" | "muse";
+/** @deprecated Use {@link Provider}. Kept so `--target` and old callers keep working. */
+export type Target = Provider;
+export type InstallOptions = {
+    /** Project directory to install into. */
+    dest: string;
+    /** Preset name from kit.json. Default `core`. */
+    preset?: string;
+    /** Providers to wire. Default: all. */
+    providers?: Provider[];
+    /** @deprecated Use `providers`. */
+    targets?: Target[];
+    /** Report what would happen without touching the disk. */
+    dryRun?: boolean;
+    /** Custom kit directory (default: the bundled kit). */
+    kit?: string;
+};
+export type Action = {
+    kind: "copy" | "link" | "write" | "append" | "skip";
+    path: string;
+    /** Why it was skipped, what was appended, or what a link points to. */
+    note?: string;
+};
+/**
+ * Install the kit into a project. The shared source (skills, subagents,
+ * commands, AGENTS.md) is copied into `.agents/` (the project owns it from
+ * then on); each chosen provider then gets its thin layer, links where the
+ * provider follows them, real files where it does not. Existing files are
+ * never overwritten: they are reported as skipped, except an existing
+ * AGENTS.md missing the ladder, which gets the ladder section appended
+ * (reported as `append`). A bad preset or kit fails before anything is
+ * written.
+ */
+export declare function installKit(options: InstallOptions): Result<Action[]>;
+//# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAeA,OAAO,EAAqB,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAItE,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9D,yFAAyF;AACzF,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAC;AAE9B,MAAM,MAAM,cAAc,GAAG;IAC3B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG;IACnB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAsNF;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAapE"}