@llm4ts/runner 0.17.0 → 0.18.0

package/dist/Kits.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A kit is a directory bundling everything stack-specific the engine flows
+ * consume: `packs/<name>/pack.md` manifests, the `scaffolds/` they point at,
+ * a `patterns/` deck of translation cards, optional `flows/` of its own, and
+ * a `README.md` whose first paragraph is the kit's description (ADR 0014).
+ * Kits are discovered in the same three tiers as flows — the project's
+ * `.llm4ts/kits/`, the global `~/.config/llm4ts/kits/`, and the built-in
+ * kits shipped beside the engine flows — with project > global > builtin
+ * precedence by kit name.
+ */
+export type KitTier = "project" | "global" | "builtin";
+export interface KitTierPaths {
+    readonly project?: string;
+    readonly global?: string;
+    readonly builtin?: string;
+}
+export interface DiscoveredKit {
+    readonly name: string;
+    /** Absolute kit directory. */
+    readonly root: string;
+    readonly tier: KitTier;
+    readonly description?: string;
+    /** Pack names: every `packs/<name>/pack.md`. */
+    readonly packs: ReadonlyArray<string>;
+    /** Flow names: every `flows/<name>.ts|js` (not `lib/` or `test/`). */
+    readonly flows: ReadonlyArray<string>;
+    readonly shadows: ReadonlyArray<KitTier>;
+}
+export declare const kitTierPaths: (options: {
+    readonly cwd: string;
+    readonly homeDir: string;
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+    readonly builtinDir?: string;
+}) => KitTierPaths;
+/**
+ * The built-in kits directory for a flow script: the `kits/` directory that
+ * sits beside the engine `flows/` — in a checkout `<repo>/kits`, in the
+ * published shell `<shell>/kits` — found by walking up from the flow's own
+ * directory. A kit's own flows live two levels deeper and resolve the same
+ * way. `undefined` when no `kits/` directory is within reach.
+ */
+export declare const builtinKitsDir: (flowDir: string) => string | undefined;
+/** The first non-empty line after the README's `# ` title, without markup. */
+export declare const parseKitDescription: (readme: string) => string | undefined;
+/**
+ * Discovers kits across the tiers. A directory is a kit when it holds at
+ * least one pack or one flow; missing tier directories contribute nothing.
+ */
+export declare const discoverKits: (paths: KitTierPaths) => ReadonlyArray<DiscoveredKit>;
+export type PackLookup = {
+    readonly _tag: "Found";
+    readonly kit: DiscoveredKit;
+    readonly pack: string;
+} | {
+    readonly _tag: "Ambiguous";
+    readonly candidates: ReadonlyArray<string>;
+} | {
+    readonly _tag: "Absent";
+};
+/**
+ * Resolves a pack name across discovered kits. `kit/pack` names one kit;
+ * a bare name is searched tier by tier (project, then global, then builtin)
+ * and is ambiguous only when two kits of the SAME tier both ship it — a
+ * project kit shadows a built-in one, exactly as flows do.
+ */
+export declare const findPack: (reference: string, kits: ReadonlyArray<DiscoveredKit>) => PackLookup;
+//# sourceMappingURL=Kits.d.ts.map

package/dist/Kits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Kits.d.ts","sourceRoot":"","sources":["../src/Kits.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAA;AAEtD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACrC,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;CACzC;AAID,eAAO,MAAM,YAAY,GAAI,SAAS;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;IACnE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B,KAAG,YAWH,CAAA;AAUD;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,KAAG,MAAM,GAAG,SAczD,CAAA;AAED,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,GAAI,QAAQ,MAAM,KAAG,MAAM,GAAG,SAU7D,CAAA;AAyCD;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,YAAY,KAAG,aAAa,CAAC,aAAa,CAuB7E,CAAA;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9E;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAAE,GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAA;AAE/B;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,MAAM,aAAa,CAAC,aAAa,CAAC,KAAG,UAoBhF,CAAA"}

package/dist/Kits.js

@@ -0,0 +1,143 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+const tierOrder = ["project", "global", "builtin"];
+export const kitTierPaths = (options) => {
+    const environment = options.environment ?? process.env;
+    const configHome = environment.XDG_CONFIG_HOME !== undefined && environment.XDG_CONFIG_HOME.length > 0
+        ? environment.XDG_CONFIG_HOME
+        : join(options.homeDir, ".config");
+    return {
+        project: join(options.cwd, ".llm4ts", "kits"),
+        global: join(configHome, "llm4ts", "kits"),
+        ...(options.builtinDir === undefined ? {} : { builtin: options.builtinDir })
+    };
+};
+const isDirectory = (path) => {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * The built-in kits directory for a flow script: the `kits/` directory that
+ * sits beside the engine `flows/` — in a checkout `<repo>/kits`, in the
+ * published shell `<shell>/kits` — found by walking up from the flow's own
+ * directory. A kit's own flows live two levels deeper and resolve the same
+ * way. `undefined` when no `kits/` directory is within reach.
+ */
+export const builtinKitsDir = (flowDir) => {
+    let directory = resolve(flowDir);
+    for (let depth = 0; depth < 4; depth += 1) {
+        const candidate = join(directory, "kits");
+        if (isDirectory(candidate)) {
+            return candidate;
+        }
+        const parent = dirname(directory);
+        if (parent === directory) {
+            break;
+        }
+        directory = parent;
+    }
+    return undefined;
+};
+/** The first non-empty line after the README's `# ` title, without markup. */
+export const parseKitDescription = (readme) => {
+    const lines = readme.split(/\r?\n/);
+    const start = lines.findIndex((line) => line.startsWith("# "));
+    for (const line of lines.slice(start + 1)) {
+        const trimmed = line.trim();
+        if (trimmed.length > 0 && !trimmed.startsWith("#")) {
+            return trimmed;
+        }
+    }
+    return undefined;
+};
+const listDirectories = (path) => isDirectory(path)
+    ? readdirSync(path)
+        .filter((entry) => isDirectory(join(path, entry)))
+        .sort()
+    : [];
+const readKit = (name, root, tier) => {
+    const packs = listDirectories(join(root, "packs")).filter((pack) => existsSync(join(root, "packs", pack, "pack.md")));
+    const flowsDir = join(root, "flows");
+    const flows = isDirectory(flowsDir)
+        ? readdirSync(flowsDir)
+            .filter((entry) => entry.endsWith(".ts") || entry.endsWith(".js"))
+            .map((entry) => entry.replace(/\.(ts|js)$/, ""))
+            .sort()
+        : [];
+    if (packs.length === 0 && flows.length === 0) {
+        return undefined;
+    }
+    const readme = join(root, "README.md");
+    const description = existsSync(readme)
+        ? parseKitDescription(readFileSync(readme, "utf8"))
+        : undefined;
+    return {
+        name,
+        root,
+        tier,
+        ...(description === undefined ? {} : { description }),
+        packs,
+        flows
+    };
+};
+/**
+ * Discovers kits across the tiers. A directory is a kit when it holds at
+ * least one pack or one flow; missing tier directories contribute nothing.
+ */
+export const discoverKits = (paths) => {
+    const byName = new Map();
+    for (const tier of tierOrder) {
+        const directory = paths[tier];
+        if (directory === undefined) {
+            continue;
+        }
+        for (const name of listDirectories(directory)) {
+            const kit = readKit(name, join(resolve(directory), name), tier);
+            if (kit === undefined) {
+                continue;
+            }
+            const existing = byName.get(name);
+            if (existing === undefined) {
+                byName.set(name, { kit, shadows: [] });
+            }
+            else {
+                existing.shadows.push(tier);
+            }
+        }
+    }
+    return [...byName.values()]
+        .map(({ kit, shadows }) => ({ ...kit, shadows }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+};
+/**
+ * Resolves a pack name across discovered kits. `kit/pack` names one kit;
+ * a bare name is searched tier by tier (project, then global, then builtin)
+ * and is ambiguous only when two kits of the SAME tier both ship it — a
+ * project kit shadows a built-in one, exactly as flows do.
+ */
+export const findPack = (reference, kits) => {
+    const slash = reference.indexOf("/");
+    if (slash > 0 && reference.indexOf("/", slash + 1) < 0) {
+        const kitName = reference.slice(0, slash);
+        const pack = reference.slice(slash + 1);
+        const kit = kits.find((candidate) => candidate.name === kitName);
+        return kit !== undefined && kit.packs.includes(pack)
+            ? { _tag: "Found", kit, pack }
+            : { _tag: "Absent" };
+    }
+    for (const tier of tierOrder) {
+        const holders = kits.filter((kit) => kit.tier === tier && kit.packs.includes(reference));
+        if (holders.length === 1) {
+            return { _tag: "Found", kit: holders[0], pack: reference };
+        }
+        if (holders.length > 1) {
+            return { _tag: "Ambiguous", candidates: holders.map((kit) => `${kit.name}/${reference}`) };
+        }
+    }
+    return { _tag: "Absent" };
+};
+//# sourceMappingURL=Kits.js.map

package/dist/Kits.js.map

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

package/dist/Packs.d.ts

@@ -4,51 +4,76 @@ import type { PlanParseError } from "@llm4ts/flow/FlowError";
 import { type Pack } from "@llm4ts/flow/Pack";
 import { type PatternCard } from "@llm4ts/flow/Patterns";
 import type { WorkspaceError, WorkspaceShape } from "@llm4ts/flow/Workspace";
+import { type DiscoveredKit, type KitTierPaths } from "./Kits.ts";
 declare const PackNotFound_base: Schema.Class<PackNotFound, Schema.TaggedStruct<"PackNotFound", {
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /**
  * Pack location for the modernization flows. `LLM4TS_PACK` names the pack
- * (default `packs/cobol-springboot`) and is resolved against the launch
- * directory first — a pack the user keeps next to their work wins — then
- * against the flow script's own directory, where the published shell ships
- * the built-in packs. An absolute `LLM4TS_PACK` is used as-is. The fallback
- * is what lets `llm4ts run modernize-survey --repo <estate>` work from any
- * directory instead of only from a checkout with `packs/` at its cwd.
+ * (default `cobol-springboot`) in one of three forms:
+ *
+ * - a bare name (`cobol-springboot`) or `kit/pack` (`mainframe-java/cobol-springboot`),
+ *   resolved across the kits discovered in the project, global, and built-in
+ *   tiers (ADR 0014);
+ * - a path relative to the launch directory whose directory holds `pack.md`
+ *   (`packs/my-pack`) — a pack still being written, not yet in a kit;
+ * - an absolute path to such a directory.
+ *
+ * The built-in tier is what lets `llm4ts run modernize-survey --repo <estate>`
+ * work from any directory instead of only from a checkout.
  */
 export declare class PackNotFound extends PackNotFound_base {
 }
 export interface LocatedPack {
-    /** Directory the pack workspace is rooted at. */
+    /** Directory the pack workspace is rooted at: the kit, or the pack itself. */
     readonly root: string;
-    /** Pack directory relative to `root` (`"."` when the pack path is absolute). */
+    /** Pack directory relative to `root` (`"."` for a path-form pack). */
     readonly dir: string;
+    /** The kit the pack came from; absent for a path-form pack. */
+    readonly kit?: DiscoveredKit;
 }
-/** The first candidate root whose `packDir` holds a `pack.md` manifest. */
-export declare const locatePack: (packDir: string, roots: ReadonlyArray<string>) => LocatedPack | undefined;
+export type PackLocation = ({
+    readonly _tag: "Located";
+} & LocatedPack) | {
+    readonly _tag: "Ambiguous";
+    readonly candidates: ReadonlyArray<string>;
+} | {
+    readonly _tag: "Absent";
+};
+/** Resolves a pack reference: absolute path, launch-relative path, then kits. */
+export declare const locatePack: (reference: string, options: {
+    readonly launchDir: string;
+    readonly kits: ReadonlyArray<DiscoveredKit>;
+}) => PackLocation;
 export interface OpenedPack {
     readonly pack: Pack;
     /**
-     * Workspace rooted where the pack was found. Pack-relative paths — prompts,
-     * `<pack>/patterns`, `lessons.md`, the scaffold — must resolve through this
-     * workspace, not the launch directory's.
+     * Workspace rooted where the pack was found — the kit for a kit pack, the
+     * pack directory itself otherwise. Pack-relative paths — prompts,
+     * `<pack>/patterns`, `lessons.md`, the scaffold — must resolve through
+     * this workspace, not the launch directory's.
      */
     readonly workspace: WorkspaceShape;
     /** Pack directory within `workspace`. */
     readonly dir: string;
+    /** The kit the pack belongs to, when it came from one. */
+    readonly kit?: DiscoveredKit;
 }
+export declare const defaultPackName = "cobol-springboot";
 export declare const openPack: (options: {
     readonly environment: Readonly<Record<string, string | undefined>>;
     /** The directory the flow was launched from (`resolveFlowInput().workspace`). */
     readonly launchDir: string;
     /** The directory holding the flow script (`import.meta.dirname`). */
     readonly flowDir: string;
+    /** Kit tiers to search; defaults to the standard tiers around `launchDir` and `flowDir`. */
+    readonly kits?: KitTierPaths;
 }) => Effect.Effect<OpenedPack, PlanParseError | WorkspaceError | PackNotFound, never>;
 /**
- * The universal pattern cards: the first candidate root with a `patterns/`
- * directory contributes them, and no root having one is an empty set —
- * patterns are optional everywhere.
+ * The pattern cards of the kit the opened pack belongs to (`<kit>/patterns`);
+ * a path-form pack, or a kit without a deck, contributes none. Pack-local
+ * cards (`<pack>/patterns`) are loaded separately by the flows.
  */
-export declare const loadUniversalPatternCards: (roots: readonly string[]) => Effect.Effect<readonly PatternCard[], WorkspaceError, never>;
+export declare const loadKitPatternCards: (opened: OpenedPack) => Effect.Effect<readonly PatternCard[], WorkspaceError, never>;
 export {};
 //# sourceMappingURL=Packs.d.ts.map

package/dist/Packs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Packs.d.ts","sourceRoot":"","sources":["../src/Packs.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC5D,OAAO,EAAY,KAAK,IAAI,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;;;;AAG5E;;;;;;;;GAQG;AAEH,qBAAa,YAAa,SAAQ,iBAEhC;CAAG;AAEL,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,gFAAgF;IAChF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED,2EAA2E;AAC3E,eAAO,MAAM,UAAU,GACrB,SAAS,MAAM,EACf,OAAO,aAAa,CAAC,MAAM,CAAC,KAC3B,WAAW,GAAG,SAWhB,CAAA;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC,yCAAyC;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED,eAAO,MAAM,QAAQ;0BACG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAClE,iFAAiF;wBAC7D,MAAM;IAC1B,qEAAqE;sBACnD,MAAM;sFAexB,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,4FAapC,CAAA"}
+{"version":3,"file":"Packs.d.ts","sourceRoot":"","sources":["../src/Packs.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC5D,OAAO,EAAY,KAAK,IAAI,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC5E,OAAO,EAKL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,WAAW,CAAA;;;;AAGlB;;;;;;;;;;;;;GAaG;AAEH,qBAAa,YAAa,SAAQ,iBAEhC;CAAG;AAEL,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,CAAA;CAC7B;AAED,MAAM,MAAM,YAAY,GACpB,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG,WAAW,CAAC,GAC5C;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAAE,GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAA;AAI/B,iFAAiF;AACjF,eAAO,MAAM,UAAU,GACrB,WAAW,MAAM,EACjB,SAAS;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;CAAE,KACnF,YAwBF,CAAA;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC,yCAAyC;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,CAAA;CAC7B;AAED,eAAO,MAAM,eAAe,qBAAqB,CAAA;AAEjD,eAAO,MAAM,QAAQ;0BACG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAClE,iFAAiF;wBAC7D,MAAM;IAC1B,qEAAqE;sBACnD,MAAM;IACxB,4FAA4F;oBAC5E,YAAY;sFAuC5B,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,sFAO9B,CAAA"}

package/dist/Packs.js

@@ -1,63 +1,103 @@
 import { existsSync } from "node:fs";
+import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import { loadPack } from "@llm4ts/flow/Pack";
 import { loadPatternCards } from "@llm4ts/flow/Patterns";
+import { builtinKitsDir, discoverKits, findPack, kitTierPaths } from "./Kits.js";
 import { makeNodeWorkspace } from "./NodeWorkspace.js";
 /**
  * Pack location for the modernization flows. `LLM4TS_PACK` names the pack
- * (default `packs/cobol-springboot`) and is resolved against the launch
- * directory first — a pack the user keeps next to their work wins — then
- * against the flow script's own directory, where the published shell ships
- * the built-in packs. An absolute `LLM4TS_PACK` is used as-is. The fallback
- * is what lets `llm4ts run modernize-survey --repo <estate>` work from any
- * directory instead of only from a checkout with `packs/` at its cwd.
+ * (default `cobol-springboot`) in one of three forms:
+ *
+ * - a bare name (`cobol-springboot`) or `kit/pack` (`mainframe-java/cobol-springboot`),
+ *   resolved across the kits discovered in the project, global, and built-in
+ *   tiers (ADR 0014);
+ * - a path relative to the launch directory whose directory holds `pack.md`
+ *   (`packs/my-pack`) — a pack still being written, not yet in a kit;
+ * - an absolute path to such a directory.
+ *
+ * The built-in tier is what lets `llm4ts run modernize-survey --repo <estate>`
+ * work from any directory instead of only from a checkout.
  */
 export class PackNotFound extends Schema.TaggedErrorClass()("PackNotFound", {
     message: Schema.String
 }) {
 }
-/** The first candidate root whose `packDir` holds a `pack.md` manifest. */
-export const locatePack = (packDir, roots) => {
-    if (isAbsolute(packDir)) {
-        return existsSync(join(packDir, "pack.md")) ? { root: packDir, dir: "." } : undefined;
+const hasManifest = (directory) => existsSync(join(directory, "pack.md"));
+/** Resolves a pack reference: absolute path, launch-relative path, then kits. */
+export const locatePack = (reference, options) => {
+    if (isAbsolute(reference)) {
+        return hasManifest(reference)
+            ? { _tag: "Located", root: reference, dir: "." }
+            : { _tag: "Absent" };
     }
-    for (const root of roots) {
-        const resolved = resolve(root);
-        if (existsSync(join(resolved, packDir, "pack.md"))) {
-            return { root: resolved, dir: packDir };
-        }
+    const launchDir = resolve(options.launchDir);
+    if (reference.includes("/") && hasManifest(join(launchDir, reference))) {
+        return { _tag: "Located", root: launchDir, dir: reference };
+    }
+    const lookup = findPack(reference, options.kits);
+    switch (lookup._tag) {
+        case "Found":
+            return {
+                _tag: "Located",
+                root: lookup.kit.root,
+                dir: join("packs", lookup.pack),
+                kit: lookup.kit
+            };
+        case "Ambiguous":
+            return lookup;
+        case "Absent":
+            return lookup;
     }
-    return undefined;
 };
+export const defaultPackName = "cobol-springboot";
 export const openPack = Effect.fn("@llm4ts/runner/Packs.openPack")(function* (options) {
-    const packDir = options.environment.LLM4TS_PACK ?? "packs/cobol-springboot";
-    const located = locatePack(packDir, [options.launchDir, options.flowDir]);
-    if (located === undefined) {
+    const reference = options.environment.LLM4TS_PACK?.trim() || defaultPackName;
+    const builtinDir = builtinKitsDir(options.flowDir);
+    const tiers = options.kits ??
+        kitTierPaths({
+            cwd: options.launchDir,
+            homeDir: homedir(),
+            environment: options.environment,
+            ...(builtinDir === undefined ? {} : { builtinDir })
+        });
+    const kits = discoverKits(tiers);
+    const location = locatePack(reference, { launchDir: options.launchDir, kits });
+    if (location._tag === "Ambiguous") {
+        return yield* PackNotFound.make({
+            message: `pack '${reference}' is shipped by more than one kit — ` +
+                `name one of: ${location.candidates.join(", ")}`
+        });
+    }
+    if (location._tag === "Absent") {
+        const known = kits.flatMap((kit) => kit.packs.map((pack) => `${kit.name}/${pack}`));
         return yield* PackNotFound.make({
-            message: `pack '${packDir}' not found: no ${join(packDir, "pack.md")} under ` +
-                `${resolve(options.launchDir)} or ${resolve(options.flowDir)} — ` +
-                "set LLM4TS_PACK or launch from a directory containing the pack"
+            message: `pack '${reference}' not found: no kit ships it` +
+                (known.length === 0 ? "" : ` (known packs: ${known.join(", ")})`) +
+                ` and no ${join(reference, "pack.md")} exists under ${resolve(options.launchDir)} — ` +
+                "set LLM4TS_PACK to a kit pack name, a kit/pack name, or a directory holding pack.md"
         });
     }
-    const workspace = yield* makeNodeWorkspace(located.root);
-    const pack = yield* loadPack(workspace, located.dir);
-    return { pack, workspace, dir: located.dir };
+    const workspace = yield* makeNodeWorkspace(location.root);
+    const pack = yield* loadPack(workspace, location.dir);
+    return {
+        pack,
+        workspace,
+        dir: location.dir,
+        ...(location.kit === undefined ? {} : { kit: location.kit })
+    };
 });
 /**
- * The universal pattern cards: the first candidate root with a `patterns/`
- * directory contributes them, and no root having one is an empty set —
- * patterns are optional everywhere.
+ * The pattern cards of the kit the opened pack belongs to (`<kit>/patterns`);
+ * a path-form pack, or a kit without a deck, contributes none. Pack-local
+ * cards (`<pack>/patterns`) are loaded separately by the flows.
  */
-export const loadUniversalPatternCards = Effect.fn("@llm4ts/runner/Packs.loadUniversalPatternCards")(function* (roots) {
-    const root = roots
-        .map((candidate) => resolve(candidate))
-        .find((candidate) => existsSync(join(candidate, "patterns")));
-    if (root === undefined) {
+export const loadKitPatternCards = Effect.fn("@llm4ts/runner/Packs.loadKitPatternCards")(function* (opened) {
+    if (opened.kit === undefined || !existsSync(join(opened.kit.root, "patterns"))) {
         return [];
     }
-    const workspace = yield* makeNodeWorkspace(root);
-    return yield* loadPatternCards(workspace, "patterns");
+    return yield* loadPatternCards(opened.workspace, "patterns");
 });
 //# sourceMappingURL=Packs.js.map

package/dist/Packs.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The flow author's entry point: everything a flow script under
+ * `.llm4ts/flows/` reaches for, re-exported from the runner and flow
+ * subpaths so a script needs one import line. Nothing here is new API — the
+ * subpath exports stay the contract for everything else, and the list is
+ * exactly what the shipped flows use.
+ */
+export { runEmbedded, runFlowMain, runNode } from "./FlowRunner.ts";
+export type { FlowRunnerOptions } from "./FlowRunner.ts";
+export { resolveFlowInput, ScriptUsage } from "./FlowArgs.ts";
+export type { FlowInput } from "./FlowArgs.ts";
+export { apiConnectorFromEnvironment, asReadOnly, coderFor, coderFromEnv, mock, withModel, withTurnLimit } from "./Connectors.ts";
+export { loadKitPatternCards, openPack, PackNotFound } from "./Packs.ts";
+export type { OpenedPack } from "./Packs.ts";
+export { nodePlainFileStore } from "./NodePlainFileStore.ts";
+export { makeNodeWorkspace } from "./NodeWorkspace.ts";
+export { nodeProcessExecutor } from "./NodeProcessExecutor.ts";
+export { reviewFingerprint } from "./ReviewFingerprint.ts";
+export { completeAndPublish, implementPlanFlow } from "@llm4ts/flow/Flow";
+export type { ImplementPlanOptions } from "@llm4ts/flow/Flow";
+export type { FlowContextShape } from "@llm4ts/flow/FlowContext";
+export { implementTaskLoop, stage } from "@llm4ts/flow/PlanExecution";
+export { lintCommand, mergeReviewResults, minimalReviewers, reviewAndFixLoop, ReviewResult } from "@llm4ts/flow/Review";
+export { Reviewer } from "@llm4ts/flow/Reviewer";
+export { makeChat } from "@llm4ts/flow/Chat";
+export { makePlanStore } from "@llm4ts/flow/Persistence";
+export { defaultPlanInstructions, planFrom, writeBrief } from "@llm4ts/flow/Planner";
+export { defaultPlanPath, parsePlan, Plan } from "@llm4ts/flow/Plan";
+export { AssistantMessage, Info } from "@llm4ts/flow/FlowEvents";
+export { FlowAborted, FlowLlmError } from "@llm4ts/flow/FlowError";
+export { loadPack } from "@llm4ts/flow/Pack";
+//# 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;;;;;;GAMG;AACH,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AACnE,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AACxD,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC7D,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,EACL,2BAA2B,EAC3B,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,IAAI,EACJ,SAAS,EACT,aAAa,EACd,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACxE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAE1D,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACzE,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAC7D,YAAY,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAChE,OAAO,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAA;AACrE,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACb,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAE,uBAAuB,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACpF,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAA;AACpE,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAA;AAChE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/index.js

@@ -0,0 +1,27 @@
+/**
+ * The flow author's entry point: everything a flow script under
+ * `.llm4ts/flows/` reaches for, re-exported from the runner and flow
+ * subpaths so a script needs one import line. Nothing here is new API — the
+ * subpath exports stay the contract for everything else, and the list is
+ * exactly what the shipped flows use.
+ */
+export { runEmbedded, runFlowMain, runNode } from "./FlowRunner.js";
+export { resolveFlowInput, ScriptUsage } from "./FlowArgs.js";
+export { apiConnectorFromEnvironment, asReadOnly, coderFor, coderFromEnv, mock, withModel, withTurnLimit } from "./Connectors.js";
+export { loadKitPatternCards, openPack, PackNotFound } from "./Packs.js";
+export { nodePlainFileStore } from "./NodePlainFileStore.js";
+export { makeNodeWorkspace } from "./NodeWorkspace.js";
+export { nodeProcessExecutor } from "./NodeProcessExecutor.js";
+export { reviewFingerprint } from "./ReviewFingerprint.js";
+export { completeAndPublish, implementPlanFlow } from "@llm4ts/flow/Flow";
+export { implementTaskLoop, stage } from "@llm4ts/flow/PlanExecution";
+export { lintCommand, mergeReviewResults, minimalReviewers, reviewAndFixLoop, ReviewResult } from "@llm4ts/flow/Review";
+export { Reviewer } from "@llm4ts/flow/Reviewer";
+export { makeChat } from "@llm4ts/flow/Chat";
+export { makePlanStore } from "@llm4ts/flow/Persistence";
+export { defaultPlanInstructions, planFrom, writeBrief } from "@llm4ts/flow/Planner";
+export { defaultPlanPath, parsePlan, Plan } from "@llm4ts/flow/Plan";
+export { AssistantMessage, Info } from "@llm4ts/flow/FlowEvents";
+export { FlowAborted, FlowLlmError } from "@llm4ts/flow/FlowError";
+export { loadPack } from "@llm4ts/flow/Pack";
+//# 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;;;;;;GAMG;AACH,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAEnE,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE7D,OAAO,EACL,2BAA2B,EAC3B,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,IAAI,EACJ,SAAS,EACT,aAAa,EACd,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAExE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAE1D,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAGzE,OAAO,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAA;AACrE,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACb,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAE,uBAAuB,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACpF,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAA;AACpE,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAA;AAChE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/runner",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Node runner, CLI, terminal, and MCP composition for llm4ts",
   "license": "MIT",
   "type": "module",
@@ -13,12 +13,14 @@
     "src"
   ],
   "exports": {
+    ".": "./dist/index.js",
     "./Cli": "./dist/Cli.js",
     "./CoderPolicy": "./dist/CoderPolicy.js",
     "./Connectors": "./dist/Connectors.js",
     "./Doctor": "./dist/Doctor.js",
     "./FlowArgs": "./dist/FlowArgs.js",
     "./FlowRunner": "./dist/FlowRunner.js",
+    "./Kits": "./dist/Kits.js",
     "./McpStdio": "./dist/McpStdio.js",
     "./NodeHttpClient": "./dist/NodeHttpClient.js",
     "./NodeGeminiCliExecutor": "./dist/NodeGeminiCliExecutor.js",
@@ -57,8 +59,8 @@
     "typescript"
   ],
   "dependencies": {
-    "@llm4ts/flow": "0.17.0",
-    "@llm4ts/core": "0.17.0"
+    "@llm4ts/core": "0.18.0",
+    "@llm4ts/flow": "0.18.0"
   },
   "peerDependencies": {
     "effect": "4.0.0-beta.102"

package/src/Kits.ts

@@ -0,0 +1,198 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+
+/**
+ * A kit is a directory bundling everything stack-specific the engine flows
+ * consume: `packs/<name>/pack.md` manifests, the `scaffolds/` they point at,
+ * a `patterns/` deck of translation cards, optional `flows/` of its own, and
+ * a `README.md` whose first paragraph is the kit's description (ADR 0014).
+ * Kits are discovered in the same three tiers as flows — the project's
+ * `.llm4ts/kits/`, the global `~/.config/llm4ts/kits/`, and the built-in
+ * kits shipped beside the engine flows — with project > global > builtin
+ * precedence by kit name.
+ */
+export type KitTier = "project" | "global" | "builtin"
+
+export interface KitTierPaths {
+  readonly project?: string
+  readonly global?: string
+  readonly builtin?: string
+}
+
+export interface DiscoveredKit {
+  readonly name: string
+  /** Absolute kit directory. */
+  readonly root: string
+  readonly tier: KitTier
+  readonly description?: string
+  /** Pack names: every `packs/<name>/pack.md`. */
+  readonly packs: ReadonlyArray<string>
+  /** Flow names: every `flows/<name>.ts|js` (not `lib/` or `test/`). */
+  readonly flows: ReadonlyArray<string>
+  readonly shadows: ReadonlyArray<KitTier>
+}
+
+const tierOrder: ReadonlyArray<KitTier> = ["project", "global", "builtin"]
+
+export const kitTierPaths = (options: {
+  readonly cwd: string
+  readonly homeDir: string
+  readonly environment?: Readonly<Record<string, string | undefined>>
+  readonly builtinDir?: string
+}): KitTierPaths => {
+  const environment = options.environment ?? process.env
+  const configHome =
+    environment.XDG_CONFIG_HOME !== undefined && environment.XDG_CONFIG_HOME.length > 0
+      ? environment.XDG_CONFIG_HOME
+      : join(options.homeDir, ".config")
+  return {
+    project: join(options.cwd, ".llm4ts", "kits"),
+    global: join(configHome, "llm4ts", "kits"),
+    ...(options.builtinDir === undefined ? {} : { builtin: options.builtinDir })
+  }
+}
+
+const isDirectory = (path: string): boolean => {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The built-in kits directory for a flow script: the `kits/` directory that
+ * sits beside the engine `flows/` — in a checkout `<repo>/kits`, in the
+ * published shell `<shell>/kits` — found by walking up from the flow's own
+ * directory. A kit's own flows live two levels deeper and resolve the same
+ * way. `undefined` when no `kits/` directory is within reach.
+ */
+export const builtinKitsDir = (flowDir: string): string | undefined => {
+  let directory = resolve(flowDir)
+  for (let depth = 0; depth < 4; depth += 1) {
+    const candidate = join(directory, "kits")
+    if (isDirectory(candidate)) {
+      return candidate
+    }
+    const parent = dirname(directory)
+    if (parent === directory) {
+      break
+    }
+    directory = parent
+  }
+  return undefined
+}
+
+/** The first non-empty line after the README's `# ` title, without markup. */
+export const parseKitDescription = (readme: string): string | undefined => {
+  const lines = readme.split(/\r?\n/)
+  const start = lines.findIndex((line) => line.startsWith("# "))
+  for (const line of lines.slice(start + 1)) {
+    const trimmed = line.trim()
+    if (trimmed.length > 0 && !trimmed.startsWith("#")) {
+      return trimmed
+    }
+  }
+  return undefined
+}
+
+const listDirectories = (path: string): ReadonlyArray<string> =>
+  isDirectory(path)
+    ? readdirSync(path)
+        .filter((entry) => isDirectory(join(path, entry)))
+        .sort()
+    : []
+
+const readKit = (
+  name: string,
+  root: string,
+  tier: KitTier
+): Omit<DiscoveredKit, "shadows"> | undefined => {
+  const packs = listDirectories(join(root, "packs")).filter((pack) =>
+    existsSync(join(root, "packs", pack, "pack.md"))
+  )
+  const flowsDir = join(root, "flows")
+  const flows = isDirectory(flowsDir)
+    ? readdirSync(flowsDir)
+        .filter((entry) => entry.endsWith(".ts") || entry.endsWith(".js"))
+        .map((entry) => entry.replace(/\.(ts|js)$/, ""))
+        .sort()
+    : []
+  if (packs.length === 0 && flows.length === 0) {
+    return undefined
+  }
+  const readme = join(root, "README.md")
+  const description = existsSync(readme)
+    ? parseKitDescription(readFileSync(readme, "utf8"))
+    : undefined
+  return {
+    name,
+    root,
+    tier,
+    ...(description === undefined ? {} : { description }),
+    packs,
+    flows
+  }
+}
+
+/**
+ * Discovers kits across the tiers. A directory is a kit when it holds at
+ * least one pack or one flow; missing tier directories contribute nothing.
+ */
+export const discoverKits = (paths: KitTierPaths): ReadonlyArray<DiscoveredKit> => {
+  const byName = new Map<string, { kit: Omit<DiscoveredKit, "shadows">; shadows: Array<KitTier> }>()
+  for (const tier of tierOrder) {
+    const directory = paths[tier]
+    if (directory === undefined) {
+      continue
+    }
+    for (const name of listDirectories(directory)) {
+      const kit = readKit(name, join(resolve(directory), name), tier)
+      if (kit === undefined) {
+        continue
+      }
+      const existing = byName.get(name)
+      if (existing === undefined) {
+        byName.set(name, { kit, shadows: [] })
+      } else {
+        existing.shadows.push(tier)
+      }
+    }
+  }
+  return [...byName.values()]
+    .map(({ kit, shadows }): DiscoveredKit => ({ ...kit, shadows }))
+    .sort((left, right) => left.name.localeCompare(right.name))
+}
+
+export type PackLookup =
+  | { readonly _tag: "Found"; readonly kit: DiscoveredKit; readonly pack: string }
+  | { readonly _tag: "Ambiguous"; readonly candidates: ReadonlyArray<string> }
+  | { readonly _tag: "Absent" }
+
+/**
+ * Resolves a pack name across discovered kits. `kit/pack` names one kit;
+ * a bare name is searched tier by tier (project, then global, then builtin)
+ * and is ambiguous only when two kits of the SAME tier both ship it — a
+ * project kit shadows a built-in one, exactly as flows do.
+ */
+export const findPack = (reference: string, kits: ReadonlyArray<DiscoveredKit>): PackLookup => {
+  const slash = reference.indexOf("/")
+  if (slash > 0 && reference.indexOf("/", slash + 1) < 0) {
+    const kitName = reference.slice(0, slash)
+    const pack = reference.slice(slash + 1)
+    const kit = kits.find((candidate) => candidate.name === kitName)
+    return kit !== undefined && kit.packs.includes(pack)
+      ? { _tag: "Found", kit, pack }
+      : { _tag: "Absent" }
+  }
+  for (const tier of tierOrder) {
+    const holders = kits.filter((kit) => kit.tier === tier && kit.packs.includes(reference))
+    if (holders.length === 1) {
+      return { _tag: "Found", kit: holders[0]!, pack: reference }
+    }
+    if (holders.length > 1) {
+      return { _tag: "Ambiguous", candidates: holders.map((kit) => `${kit.name}/${reference}`) }
+    }
+  }
+  return { _tag: "Absent" }
+}

package/src/Packs.ts

@@ -1,4 +1,5 @@
 import { existsSync } from "node:fs"
+import { homedir } from "node:os"
 import { isAbsolute, join, resolve } from "node:path"
 import * as Effect from "effect/Effect"
 import * as Schema from "effect/Schema"
@@ -6,16 +7,29 @@ import type { PlanParseError } from "@llm4ts/flow/FlowError"
 import { loadPack, type Pack } from "@llm4ts/flow/Pack"
 import { loadPatternCards, type PatternCard } from "@llm4ts/flow/Patterns"
 import type { WorkspaceError, WorkspaceShape } from "@llm4ts/flow/Workspace"
+import {
+  builtinKitsDir,
+  discoverKits,
+  findPack,
+  kitTierPaths,
+  type DiscoveredKit,
+  type KitTierPaths
+} from "./Kits.ts"
 import { makeNodeWorkspace } from "./NodeWorkspace.ts"
 
 /**
  * Pack location for the modernization flows. `LLM4TS_PACK` names the pack
- * (default `packs/cobol-springboot`) and is resolved against the launch
- * directory first — a pack the user keeps next to their work wins — then
- * against the flow script's own directory, where the published shell ships
- * the built-in packs. An absolute `LLM4TS_PACK` is used as-is. The fallback
- * is what lets `llm4ts run modernize-survey --repo <estate>` work from any
- * directory instead of only from a checkout with `packs/` at its cwd.
+ * (default `cobol-springboot`) in one of three forms:
+ *
+ * - a bare name (`cobol-springboot`) or `kit/pack` (`mainframe-java/cobol-springboot`),
+ *   resolved across the kits discovered in the project, global, and built-in
+ *   tiers (ADR 0014);
+ * - a path relative to the launch directory whose directory holds `pack.md`
+ *   (`packs/my-pack`) — a pack still being written, not yet in a kit;
+ * - an absolute path to such a directory.
+ *
+ * The built-in tier is what lets `llm4ts run modernize-survey --repo <estate>`
+ * work from any directory instead of only from a checkout.
  */
 
 export class PackNotFound extends Schema.TaggedErrorClass<PackNotFound>()("PackNotFound", {
@@ -23,79 +37,126 @@ export class PackNotFound extends Schema.TaggedErrorClass<PackNotFound>()("PackN
 }) {}
 
 export interface LocatedPack {
-  /** Directory the pack workspace is rooted at. */
+  /** Directory the pack workspace is rooted at: the kit, or the pack itself. */
   readonly root: string
-  /** Pack directory relative to `root` (`"."` when the pack path is absolute). */
+  /** Pack directory relative to `root` (`"."` for a path-form pack). */
   readonly dir: string
+  /** The kit the pack came from; absent for a path-form pack. */
+  readonly kit?: DiscoveredKit
 }
 
-/** The first candidate root whose `packDir` holds a `pack.md` manifest. */
+export type PackLocation =
+  | ({ readonly _tag: "Located" } & LocatedPack)
+  | { readonly _tag: "Ambiguous"; readonly candidates: ReadonlyArray<string> }
+  | { readonly _tag: "Absent" }
+
+const hasManifest = (directory: string): boolean => existsSync(join(directory, "pack.md"))
+
+/** Resolves a pack reference: absolute path, launch-relative path, then kits. */
 export const locatePack = (
-  packDir: string,
-  roots: ReadonlyArray<string>
-): LocatedPack | undefined => {
-  if (isAbsolute(packDir)) {
-    return existsSync(join(packDir, "pack.md")) ? { root: packDir, dir: "." } : undefined
+  reference: string,
+  options: { readonly launchDir: string; readonly kits: ReadonlyArray<DiscoveredKit> }
+): PackLocation => {
+  if (isAbsolute(reference)) {
+    return hasManifest(reference)
+      ? { _tag: "Located", root: reference, dir: "." }
+      : { _tag: "Absent" }
+  }
+  const launchDir = resolve(options.launchDir)
+  if (reference.includes("/") && hasManifest(join(launchDir, reference))) {
+    return { _tag: "Located", root: launchDir, dir: reference }
   }
-  for (const root of roots) {
-    const resolved = resolve(root)
-    if (existsSync(join(resolved, packDir, "pack.md"))) {
-      return { root: resolved, dir: packDir }
-    }
+  const lookup = findPack(reference, options.kits)
+  switch (lookup._tag) {
+    case "Found":
+      return {
+        _tag: "Located",
+        root: lookup.kit.root,
+        dir: join("packs", lookup.pack),
+        kit: lookup.kit
+      }
+    case "Ambiguous":
+      return lookup
+    case "Absent":
+      return lookup
   }
-  return undefined
 }
 
 export interface OpenedPack {
   readonly pack: Pack
   /**
-   * Workspace rooted where the pack was found. Pack-relative paths — prompts,
-   * `<pack>/patterns`, `lessons.md`, the scaffold — must resolve through this
-   * workspace, not the launch directory's.
+   * Workspace rooted where the pack was found — the kit for a kit pack, the
+   * pack directory itself otherwise. Pack-relative paths — prompts,
+   * `<pack>/patterns`, `lessons.md`, the scaffold — must resolve through
+   * this workspace, not the launch directory's.
    */
   readonly workspace: WorkspaceShape
   /** Pack directory within `workspace`. */
   readonly dir: string
+  /** The kit the pack belongs to, when it came from one. */
+  readonly kit?: DiscoveredKit
 }
 
+export const defaultPackName = "cobol-springboot"
+
 export const openPack = Effect.fn("@llm4ts/runner/Packs.openPack")(function* (options: {
   readonly environment: Readonly<Record<string, string | undefined>>
   /** The directory the flow was launched from (`resolveFlowInput().workspace`). */
   readonly launchDir: string
   /** The directory holding the flow script (`import.meta.dirname`). */
   readonly flowDir: string
+  /** Kit tiers to search; defaults to the standard tiers around `launchDir` and `flowDir`. */
+  readonly kits?: KitTierPaths
 }): Effect.fn.Return<OpenedPack, PackNotFound | WorkspaceError | PlanParseError> {
-  const packDir = options.environment.LLM4TS_PACK ?? "packs/cobol-springboot"
-  const located = locatePack(packDir, [options.launchDir, options.flowDir])
-  if (located === undefined) {
+  const reference = options.environment.LLM4TS_PACK?.trim() || defaultPackName
+  const builtinDir = builtinKitsDir(options.flowDir)
+  const tiers =
+    options.kits ??
+    kitTierPaths({
+      cwd: options.launchDir,
+      homeDir: homedir(),
+      environment: options.environment,
+      ...(builtinDir === undefined ? {} : { builtinDir })
+    })
+  const kits = discoverKits(tiers)
+  const location = locatePack(reference, { launchDir: options.launchDir, kits })
+  if (location._tag === "Ambiguous") {
     return yield* PackNotFound.make({
       message:
-        `pack '${packDir}' not found: no ${join(packDir, "pack.md")} under ` +
-        `${resolve(options.launchDir)} or ${resolve(options.flowDir)} — ` +
-        "set LLM4TS_PACK or launch from a directory containing the pack"
+        `pack '${reference}' is shipped by more than one kit — ` +
+        `name one of: ${location.candidates.join(", ")}`
     })
   }
-  const workspace = yield* makeNodeWorkspace(located.root)
-  const pack = yield* loadPack(workspace, located.dir)
-  return { pack, workspace, dir: located.dir }
+  if (location._tag === "Absent") {
+    const known = kits.flatMap((kit) => kit.packs.map((pack) => `${kit.name}/${pack}`))
+    return yield* PackNotFound.make({
+      message:
+        `pack '${reference}' not found: no kit ships it` +
+        (known.length === 0 ? "" : ` (known packs: ${known.join(", ")})`) +
+        ` and no ${join(reference, "pack.md")} exists under ${resolve(options.launchDir)} — ` +
+        "set LLM4TS_PACK to a kit pack name, a kit/pack name, or a directory holding pack.md"
+    })
+  }
+  const workspace = yield* makeNodeWorkspace(location.root)
+  const pack = yield* loadPack(workspace, location.dir)
+  return {
+    pack,
+    workspace,
+    dir: location.dir,
+    ...(location.kit === undefined ? {} : { kit: location.kit })
+  }
 })
 
 /**
- * The universal pattern cards: the first candidate root with a `patterns/`
- * directory contributes them, and no root having one is an empty set —
- * patterns are optional everywhere.
+ * The pattern cards of the kit the opened pack belongs to (`<kit>/patterns`);
+ * a path-form pack, or a kit without a deck, contributes none. Pack-local
+ * cards (`<pack>/patterns`) are loaded separately by the flows.
  */
-export const loadUniversalPatternCards = Effect.fn(
-  "@llm4ts/runner/Packs.loadUniversalPatternCards"
-)(function* (
-  roots: ReadonlyArray<string>
+export const loadKitPatternCards = Effect.fn("@llm4ts/runner/Packs.loadKitPatternCards")(function* (
+  opened: OpenedPack
 ): Effect.fn.Return<ReadonlyArray<PatternCard>, WorkspaceError> {
-  const root = roots
-    .map((candidate) => resolve(candidate))
-    .find((candidate) => existsSync(join(candidate, "patterns")))
-  if (root === undefined) {
+  if (opened.kit === undefined || !existsSync(join(opened.kit.root, "patterns"))) {
     return []
   }
-  const workspace = yield* makeNodeWorkspace(root)
-  return yield* loadPatternCards(workspace, "patterns")
+  return yield* loadPatternCards(opened.workspace, "patterns")
 })

package/src/index.ts

@@ -0,0 +1,46 @@
+/**
+ * The flow author's entry point: everything a flow script under
+ * `.llm4ts/flows/` reaches for, re-exported from the runner and flow
+ * subpaths so a script needs one import line. Nothing here is new API — the
+ * subpath exports stay the contract for everything else, and the list is
+ * exactly what the shipped flows use.
+ */
+export { runEmbedded, runFlowMain, runNode } from "./FlowRunner.ts"
+export type { FlowRunnerOptions } from "./FlowRunner.ts"
+export { resolveFlowInput, ScriptUsage } from "./FlowArgs.ts"
+export type { FlowInput } from "./FlowArgs.ts"
+export {
+  apiConnectorFromEnvironment,
+  asReadOnly,
+  coderFor,
+  coderFromEnv,
+  mock,
+  withModel,
+  withTurnLimit
+} from "./Connectors.ts"
+export { loadKitPatternCards, openPack, PackNotFound } from "./Packs.ts"
+export type { OpenedPack } from "./Packs.ts"
+export { nodePlainFileStore } from "./NodePlainFileStore.ts"
+export { makeNodeWorkspace } from "./NodeWorkspace.ts"
+export { nodeProcessExecutor } from "./NodeProcessExecutor.ts"
+export { reviewFingerprint } from "./ReviewFingerprint.ts"
+
+export { completeAndPublish, implementPlanFlow } from "@llm4ts/flow/Flow"
+export type { ImplementPlanOptions } from "@llm4ts/flow/Flow"
+export type { FlowContextShape } from "@llm4ts/flow/FlowContext"
+export { implementTaskLoop, stage } from "@llm4ts/flow/PlanExecution"
+export {
+  lintCommand,
+  mergeReviewResults,
+  minimalReviewers,
+  reviewAndFixLoop,
+  ReviewResult
+} from "@llm4ts/flow/Review"
+export { Reviewer } from "@llm4ts/flow/Reviewer"
+export { makeChat } from "@llm4ts/flow/Chat"
+export { makePlanStore } from "@llm4ts/flow/Persistence"
+export { defaultPlanInstructions, planFrom, writeBrief } from "@llm4ts/flow/Planner"
+export { defaultPlanPath, parsePlan, Plan } from "@llm4ts/flow/Plan"
+export { AssistantMessage, Info } from "@llm4ts/flow/FlowEvents"
+export { FlowAborted, FlowLlmError } from "@llm4ts/flow/FlowError"
+export { loadPack } from "@llm4ts/flow/Pack"