indusagi 0.12.32 → 0.12.34

package/dist/types/shell-app/runners/registry.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The runner registry — the data-driven replacement for a mode if/else.
+ *
+ * Every concrete {@link Runner} is listed once in {@link RUNNERS}; selecting the
+ * right one for an invocation is a linear scan that returns the first whose
+ * {@link Runner.accepts | accepts} is true. Adding a new way to drive the agent
+ * means appending an entry here — no dispatch ladder to edit.
+ *
+ * Note the registry covers only the *running* modes. The `help` and `version`
+ * modes are pure, output-only concerns the boot/CLI layer renders directly from
+ * the flag table and package metadata, so no runner accepts them and they never
+ * reach {@link selectRunner}.
+ */
+import type { Invocation, Runner } from "./contract";
+/**
+ * The ordered list of runners. Order is significant only as a tie-break: the
+ * three modes are mutually exclusive, so at most one accepts any invocation, but
+ * the scan stops at the first match either way.
+ */
+export declare const RUNNERS: readonly Runner[];
+/**
+ * Thrown when no registered runner can handle an invocation. This is a launcher
+ * bug (e.g. a non-running mode reached the registry), not a user error.
+ */
+export declare class NoRunnerError extends Error {
+    constructor(mode: string);
+}
+/**
+ * Pick the runner for an invocation: the first in {@link RUNNERS} that accepts
+ * it. Throws {@link NoRunnerError} if none match — which should only happen for
+ * the `help`/`version` modes the boot layer is expected to short-circuit before
+ * ever calling here.
+ */
+export declare function selectRunner(invocation: Invocation): Runner;

package/dist/types/shell-app/runners/repl.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The REPL runner — a minimal interactive loop behind the {@link InteractiveView}
+ * seam.
+ *
+ * This is the runner behind the default interactive launch (`repl` mode): read a
+ * line, submit it to the agent, stream the answer back, repeat until the user
+ * leaves or input ends. It is deliberately *minimal* — a plain readline loop
+ * with line-oriented console output and no cursor tricks, colours, or layout.
+ *
+ * The presentation lives entirely behind the {@link InteractiveView} seam. This
+ * file ships one trivial implementation, {@link TextView}, that does plain text
+ * writes over a readline interface. THIS IS A PLACEHOLDER: a richer terminal UI
+ * is expected to implement the same `render`/`prompt`/`close` interface and be
+ * injected via {@link BootContext.view}, at which point this runner drives it
+ * unchanged. Keeping the loop UI-agnostic is the whole point — nothing here
+ * imports a UI toolkit, and nothing here will need to change when one arrives.
+ */
+import { type InteractiveView, type RunEvent, type Runner } from "./contract";
+/**
+ * The default plain-text {@link InteractiveView}.
+ *
+ * A thin wrapper over `node:readline`: {@link prompt} asks for one line and
+ * resolves it (rejecting with {@link EndOfInput} on EOF / Ctrl-D), and
+ * {@link render} writes streamed text deltas inline and a single newline once a
+ * turn settles. It owns nothing the agent needs to know about — it is the
+ * stand-in the seam exists for.
+ */
+export declare class TextView implements InteractiveView {
+    private readonly input;
+    private readonly output;
+    private readonly rl;
+    /** Set once the underlying stream signals end-of-input. */
+    private ended;
+    /** True while we are mid-assistant-turn, so settle knows to break the line. */
+    private midTurn;
+    constructor(input: NodeJS.ReadableStream, output: NodeJS.WritableStream);
+    /** Present one run event as plain text. */
+    render(event: RunEvent): void;
+    /**
+     * Ask for one line of input, rejecting with {@link EndOfInput} once the input
+     * stream has closed.
+     */
+    prompt(): Promise<string>;
+    /** Tear down the readline interface. Safe to call more than once. */
+    close(): void;
+}
+/**
+ * The interactive runner. Accepts the `repl` mode the parser derives for an
+ * attended, prompt-less launch.
+ */
+export declare const ReplRunner: Runner;

package/dist/types/shell-app/runners/wire.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The wire runner — a line-delimited JSON protocol over stdio.
+ *
+ * This is the machine-facing runner behind `--json` (a.k.a. `--rpc`/`--wire`):
+ * a host process speaks to the agent by writing one JSON request per line and
+ * reads back one JSON event per line. It is the integration seam for editors,
+ * orchestrators, and test harnesses that want structured access to the run
+ * rather than rendered prose.
+ *
+ * Protocol (every message is a single line of JSON, newline-terminated):
+ *
+ *   Requests (host → runner):
+ *     { "type": "submit", "input": "<prompt text>" }
+ *
+ *   Responses (runner → host):
+ *     { "type": "event",  "event": <RunEvent> }   — one per live run event
+ *     { "type": "result", "snapshot": <RunSnapshot> } — once per settled submit
+ *     { "type": "error",  "message": "<why>" }    — a protocol/parse failure
+ *
+ * The reader is robust to partial lines: bytes are accumulated into a buffer and
+ * only complete `\n`-delimited lines are parsed, so a request split across two
+ * chunks is handled correctly. Blank lines are ignored; a line that is not valid
+ * JSON, or not a recognised request, yields an `error` response and the loop
+ * continues rather than tearing down the connection.
+ *
+ * The runner resolves its exit code when the input stream ends (EOF): 0 in the
+ * normal case.
+ */
+import type { Runner } from "./contract";
+/**
+ * The line-delimited JSON runner. Accepts the `wire` mode the parser derives
+ * from `--json`/`--rpc`/`--wire`.
+ */
+export declare const WireRunner: Runner;

package/dist/types/shell-app/shell-app.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Behavioural tests for the assembled shell application.
+ *
+ * Five scenarios cover the seams that turn a command line into a running agent,
+ * with no network anywhere: every model turn is a scripted {@link ModelInvoker}
+ * replayed as a {@link Channel}, injected through the agent factory's deps.
+ *
+ *   1. tokenizeInvocation — flag/mode derivation for the common spellings.
+ *   2. Locator + applyUpgrades — sandboxed path math and idempotent upgrades.
+ *   3. loadSettings — a project file overriding the built-in defaults.
+ *   4. OneShotRunner — a scripted "hello" streamed to a captured output stream.
+ *   5. WireRunner — one JSON submit line in, JSON event + result lines out.
+ */
+export {};

package/dist/types/shell-app/upgrade/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shell-application startup upgrades — public surface.
+ *
+ * Exposes the idempotent upgrade vocabulary ({@link Upgrade}), the declared set
+ * ({@link UPGRADES}), and the runner ({@link applyUpgrades}) the boot layer calls
+ * once on start-up.
+ */
+export { UPGRADES, applyUpgrades } from "./upgrades";
+export type { Upgrade } from "./upgrades";

package/dist/types/shell-app/upgrade/upgrades.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Idempotent startup upgrades for the shell application.
+ *
+ * On boot the shell may need to perform one-time housekeeping: create a missing
+ * directory, move a file to a new location, rewrite a stale config shape. Each
+ * such chore is an {@link Upgrade} — a small object with a stable, human-chosen
+ * `id` and an `apply` step. The set is *keyed by id rather than by a sequential
+ * version number*: an upgrade runs at most once across the lifetime of an
+ * install, and adding, reordering, or removing entries never disturbs which
+ * other upgrades are considered "done".
+ *
+ * {@link applyUpgrades} reads a tiny marker file listing the ids that have
+ * already run, applies only the rest in declaration order, records each success,
+ * and returns the ids it applied this pass. Re-running it is a no-op once every
+ * upgrade is recorded, which is what makes startup cheap and safe to repeat.
+ *
+ * Failures are contained: if one upgrade throws, the ids that already succeeded
+ * this pass are still persisted, and the error propagates so the boot layer can
+ * decide how loud to be. The marker file itself is read forgivingly — a missing
+ * or corrupt marker is treated as "nothing has run yet".
+ */
+import type { Locator } from "../config/locator";
+/**
+ * One idempotent boot-time chore.
+ *
+ * `id` is the identity used to remember whether this upgrade has run; it must be
+ * stable forever once shipped (renaming an id re-runs the upgrade). `description`
+ * is for logs and humans only. `apply` performs the work and must itself be safe
+ * to run on an already-upgraded install, since the marker file could be lost.
+ */
+export interface Upgrade {
+    /** Stable, unique identity used to record completion. Never renamed. */
+    readonly id: string;
+    /** Human-readable summary of what the upgrade does. */
+    readonly description: string;
+    /** Perform the upgrade. Should tolerate already-applied state. */
+    apply(locator: Locator): Promise<void>;
+}
+/**
+ * The ordered set of upgrades this build knows about.
+ *
+ * Order matters only for upgrades within a single boot that have not yet run;
+ * completion is tracked per-id, so inserting a new upgrade anywhere is safe.
+ *
+ * Seeded with two trivial, self-evidently-idempotent examples:
+ *   - `ensure-profile-dir`  — guarantee the per-user profile directory exists.
+ *   - `ensure-sessions-dir` — guarantee the sessions subdirectory exists.
+ */
+export declare const UPGRADES: readonly Upgrade[];
+/**
+ * Run every upgrade that has not yet been applied, in declaration order.
+ *
+ * Reads the marker, applies each {@link UPGRADES} entry whose id is absent,
+ * records each success immediately into the in-memory set, and flushes the
+ * marker once at the end. Returns the ids applied during *this* call (empty when
+ * the install is already fully upgraded).
+ *
+ * If an upgrade throws, the marker is still flushed with whatever succeeded
+ * before the failure, then the error is re-thrown — so a retry will skip the
+ * work already done.
+ */
+export declare function applyUpgrades(locator: Locator): Promise<string[]>;

package/dist/types/smithy/config/flag-reader.d.ts

@@ -0,0 +1,128 @@
+/**
+ * `FlagReader` — a token-consuming state machine for Smithy's own CLI flags.
+ *
+ * Smithy (the agent-builder meta-tool) is launched with its own small slice of
+ * command-line options: which starter profile to seed from, where the generated
+ * agent should be written, an explicit model override, a non-interactive switch,
+ * and any number of pre-supplied interview answers. This module turns the raw
+ * `argv` slice into a {@link SmithyConfig}.
+ *
+ * Unlike the shell-app's stateless cursor-walk parser, this reader is an
+ * *explicit finite-state machine*. It walks the argv one token at a time and
+ * lives in exactly one of three states:
+ *
+ *   - `expectFlag`  — the resting state. The next token must name a flag (or be a
+ *                     glued `--flag=value`, or a bare `--` terminator). A boolean
+ *                     flag is settled here and we stay in `expectFlag`; a
+ *                     value-taking flag with no glued value advances to
+ *                     `expectValue`.
+ *   - `expectValue` — we have seen a value-taking flag and are owed its argument.
+ *                     The next token is consumed verbatim as that value and we
+ *                     fall back to `expectFlag`.
+ *   - `done`        — a bare `--` terminator was reached; every remaining token is
+ *                     ignored (Smithy takes no positionals).
+ *
+ * The set of recognised flags lives in one {@link FLAG_TABLE}, so adding a flag
+ * is a single table entry, never a new branch in the walk. The reader is pure: it
+ * reads only the array handed to it and never touches `process`, the
+ * environment, or the filesystem.
+ */
+/** The flags Smithy understands and how each one is shaped. */
+export type SmithyFlagName = "profile" | "out" | "model" | "non-interactive" | "answer";
+/** Whether a flag carries a value, and (if so) how its value is filed. */
+type FlagKind = 
+/** A bare switch: present ⇒ true. */
+"switch"
+/** A single value that overwrites (last spelling wins). */
+ | "single"
+/** A repeatable `key=value` pair folded into the answers map. */
+ | "pair";
+/** One row of the recognised-flag table. */
+interface FlagSpec {
+    /** The canonical flag name (without leading dashes). */
+    readonly name: SmithyFlagName;
+    /** Every spelling that selects this flag, e.g. `--out`, `-o`. */
+    readonly spellings: readonly string[];
+    /** Whether the flag takes a value and how it is recorded. */
+    readonly kind: FlagKind;
+}
+/**
+ * The single source of recognised flags. The walk below contains no per-flag
+ * branches — it only consults this table.
+ */
+declare const FLAG_TABLE: readonly FlagSpec[];
+/**
+ * The resolved Smithy launch configuration.
+ *
+ * Every field is optional except by intent: a launch with no flags yields an
+ * empty record, and each consumer applies its own default. `answers` collects any
+ * `--answer key=value` pairs the user pre-supplied so a non-interactive run can
+ * skip the interview.
+ */
+export interface SmithyConfig {
+    /** The starter profile to seed the blueprint from (e.g. `coder`). */
+    profile?: string;
+    /** Destination path for the generated agent file. */
+    out?: string;
+    /** An explicit model id, overriding whatever the profile would pick. */
+    model?: string;
+    /** When true, run without prompting — rely on `answers` and defaults. */
+    nonInteractive?: boolean;
+    /** Pre-supplied interview answers, keyed by question name. */
+    answers?: Record<string, string>;
+}
+/** Thrown when an argv slice cannot be read into a valid {@link SmithyConfig}. */
+export declare class FlagError extends Error {
+    constructor(message: string);
+}
+/**
+ * A token-consuming state machine that reads Smithy CLI flags.
+ *
+ * Construct one and call {@link read} with the argv slice (already stripped of
+ * the runtime and script names). The machine is single-use per `read` call —
+ * each call resets its internal state — and reports a malformed invocation by
+ * throwing {@link FlagError}.
+ */
+export declare class FlagReader {
+    /** Current position in the state machine. */
+    private state;
+    /** The flag awaiting its value while in `expectValue`. */
+    private pending;
+    /** The accumulating result, written as tokens are consumed. */
+    private config;
+    /**
+     * Read an argv slice into a {@link SmithyConfig}.
+     *
+     * Performs a single left-to-right pass, feeding each token to the active state.
+     * A trailing value-taking flag left without its argument is an error.
+     */
+    read(argv: readonly string[]): SmithyConfig;
+    /** Clear all state so the reader can be reused. */
+    private reset;
+    /**
+     * Handle a token while resting in `expectFlag`.
+     *
+     * Recognises the bare `--` terminator, a glued `--flag=value`, a value-taking
+     * flag (which arms `expectValue`), and a switch (settled immediately).
+     */
+    private onFlag;
+    /** Handle the token owed to the {@link pending} value-taking flag. */
+    private onValue;
+    /** Record a switch flag turning its slot on. */
+    private fileSwitch;
+    /** File a resolved value under the slot its spec names. */
+    private fileValue;
+    /**
+     * Fold one `key=value` interview answer into the answers map. A pair missing
+     * its `=` separator, or with an empty key, is rejected.
+     */
+    private fileAnswer;
+}
+/**
+ * Convenience entry point: read an argv slice into a {@link SmithyConfig} with a
+ * fresh {@link FlagReader}. Pass `process.argv.slice(2)` from a launcher.
+ */
+export declare function readFlags(argv: readonly string[]): SmithyConfig;
+/** Re-export the recognised-flag table for help rendering and tests. */
+export { FLAG_TABLE };
+export type { FlagSpec };

package/dist/types/smithy/config/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Smithy config layer — public surface.
+ *
+ * The flag state machine that reads Smithy's own CLI into a {@link SmithyConfig}.
+ * A launcher imports {@link FlagReader} (or the {@link readFlags} convenience) from
+ * here and nothing reaches into the module directly.
+ */
+export { FlagReader, FlagError, readFlags, FLAG_TABLE, } from "./flag-reader";
+export type { SmithyConfig, SmithyFlagName, FlagSpec } from "./flag-reader";

package/dist/types/smithy/forge.d.ts

@@ -0,0 +1,135 @@
+/**
+ * `Forge` — the build session that assembles a new agent.
+ *
+ * The other Smithy layers are each one concern in isolation: the
+ * {@link FlagReader} reads a launch into a {@link SmithyConfig}, {@link defineAgent}
+ * merges a spec over a profile into a validated {@link AgentBlueprint},
+ * {@link toAgentConfig} bridges that blueprint into a runtime `AgentConfig`, the
+ * {@link ToolLedger} accounts for what the session did, and the
+ * {@link TranscriptModel} sanitizes the dialogue for display. The Forge is the
+ * conductor that wires them into a single, drivable build session.
+ *
+ * It runs in two modes:
+ *
+ *   - {@link Forge.buildInteractive} — a short scripted *interview*. It asks the
+ *     user, through the {@link ForgeView} seam, for the agent's name, purpose,
+ *     tool needs, and model preference; folds the answers into a blueprint via
+ *     {@link defineAgent}; records each interview step on a {@link ToolLedger}; and
+ *     keeps the dialogue as a transcript a {@link TranscriptModel} can project.
+ *   - {@link Forge.buildFromConfig} — the non-interactive path. It takes a
+ *     {@link SmithyConfig} (a profile plus pre-supplied `answers`) and produces the
+ *     same kind of blueprint with no I/O at all.
+ *
+ * Finally {@link Forge.instantiate} turns a finished blueprint into a runnable
+ * {@link Agent} by way of {@link toAgentConfig} and `createAgent`.
+ *
+ * The view (and its lone `ask`) is *injected*, never constructed here, so tests
+ * can script the entire interview with canned answers and assert against the
+ * recorded ledger and transcript without ever touching a terminal or the network.
+ */
+import type { Agent } from "../runtime";
+import type { SmithyConfig } from "./config";
+import type { AgentBlueprint } from "./persona";
+import { ToolLedger } from "./runtime";
+import type { ForgeView, RenderTranscript } from "./ui";
+/**
+ * The injectable collaborators a {@link Forge} runs against.
+ *
+ * Both are optional. `view` is the full {@link ForgeView} seam; `ask` is a
+ * convenience override of just its prompt function — handy in tests that only
+ * care about scripting answers and not about captured `show` output. When neither
+ * is given, the Forge falls back to a {@link ConsoleForgeView} over stdio.
+ */
+export interface ForgeOptions {
+    /** The text view the interview reads from and writes to. */
+    readonly view?: ForgeView;
+    /** A prompt function overriding {@link ForgeView.ask} (the interview seam). */
+    readonly ask?: (question: string) => Promise<string>;
+}
+/** The answer keys the interview collects and {@link buildFromConfig} consumes. */
+export type InterviewKey = "name" | "purpose" | "tools" | "model";
+/** The collected interview answers, keyed by {@link InterviewKey}. */
+export type InterviewAnswers = Partial<Record<InterviewKey, string>>;
+/**
+ * The build session.
+ *
+ * Construct one with {@link createForge} (or directly), then call
+ * {@link buildInteractive} or {@link buildFromConfig} to obtain a validated
+ * {@link AgentBlueprint}, and {@link instantiate} to turn that blueprint into a
+ * runnable {@link Agent}. The {@link ledger} and {@link transcript} accessors
+ * expose what the most recent interactive build recorded.
+ */
+export declare class Forge {
+    /** The view the interview talks through; falls back to a console view. */
+    private readonly view;
+    /** The accountant for interview steps, one row per question asked. */
+    private readonly toolLedger;
+    /** The sanitizing projector for the recorded dialogue. */
+    private readonly transcriptModel;
+    /** The raw dialogue turns recorded during {@link buildInteractive}. */
+    private dialogue;
+    constructor(options?: ForgeOptions);
+    /**
+     * Run the scripted interview and return the resulting blueprint.
+     *
+     * Walks the {@link INTERVIEW} script: for each question it `show`s the prompt,
+     * `ask`s through the view, records the answer as a dialogue turn pair, and files
+     * one {@link ToolLedger} row noting the step. Once every answer is in, the
+     * answers are mapped through {@link defineAgent} (seeded by the profile the
+     * "tools" answer implies) into a validated {@link AgentBlueprint}.
+     *
+     * The session state — {@link ledger} and {@link transcript} — is reset at the
+     * start of each call so a reused Forge does not carry a prior interview's rows.
+     *
+     * @param seedProfile Optional starter profile name to seed defaults from.
+     */
+    buildInteractive(seedProfile?: string): Promise<AgentBlueprint>;
+    /**
+     * Build a blueprint non-interactively from a resolved {@link SmithyConfig}.
+     *
+     * No view, no prompting: the answers are read straight from `cfg.answers`, the
+     * starter profile from `cfg.profile`, and an explicit `cfg.model` (if present)
+     * overrides whatever the answers or profile would choose. The same
+     * {@link assemble} mapping is used as the interactive path, so both routes
+     * produce blueprints of identical shape.
+     *
+     * @param cfg The launch configuration (typically from a {@link FlagReader}).
+     */
+    buildFromConfig(cfg: SmithyConfig): AgentBlueprint;
+    /**
+     * Turn a finished blueprint into a runnable {@link Agent}.
+     *
+     * Projects the blueprint onto a runtime `AgentConfig` via {@link toAgentConfig}
+     * (resolving the named tool collection into a real toolbox) and hands it to
+     * `createAgent`. `cwd` roots the agent's tools at a working directory.
+     *
+     * @param blueprint A blueprint already validated by {@link defineAgent}.
+     * @param cwd       Optional working directory for the agent's tools.
+     */
+    instantiate(blueprint: AgentBlueprint, cwd?: string): Agent;
+    /** The ledger of steps recorded by the most recent interactive build. */
+    get ledger(): ToolLedger;
+    /** A sanitized, render-ready projection of the recorded dialogue. */
+    get transcript(): RenderTranscript;
+    /**
+     * Map a set of interview answers (plus an optional profile) into a validated
+     * {@link AgentBlueprint}.
+     *
+     * The "tools" answer, when it names a known tool collection, sets the
+     * blueprint's `toolCollection`; otherwise the profile/baseline default stands.
+     * The "model" answer, when non-empty, overrides the profile's model. `name` and
+     * `purpose` flow straight through to `name` and `description`. The single
+     * validation gate lives inside {@link defineAgent}.
+     */
+    private assemble;
+    /** Append one speaker turn of plain text to the recorded dialogue. */
+    private recordTurn;
+}
+/**
+ * Construct a {@link Forge} build session.
+ *
+ * The thin factory mirrors the rest of the codebase's `create*` convention and
+ * keeps the injectable {@link ForgeOptions} (a scripted view or `ask`) at the call
+ * site, which is what lets tests drive the interview with no real I/O.
+ */
+export declare function createForge(options?: ForgeOptions): Forge;

package/dist/types/smithy/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Smithy — the agent-builder meta-tool.
+ *
+ * Smithy is a leaf product surface: a tool whose job is to help a user design and
+ * generate new agents that run on the runtime. This is the package's single
+ * import site, re-exporting the layers built so far:
+ *
+ *   - `config`  — the {@link FlagReader} state machine that reads Smithy's CLI
+ *                 into a {@link SmithyConfig}.
+ *   - `persona` — the {@link AgentBlueprint} shape and validation, the starter
+ *                 {@link PROFILES} table, and the {@link defineAgent} generator
+ *                 (plus its {@link toAgentConfig} runtime bridge) that turn a
+ *                 partial spec into a validated, runnable agent description.
+ *   - `knowledge` — the externalised guide pack: a `manifest.json` plus markdown
+ *                 guides, loaded into a {@link KnowledgePack} by
+ *                 {@link loadKnowledge} for Smithy to consult while authoring.
+ *   - `runtime` — the stateful session bookkeeping, currently the
+ *                 {@link ToolLedger} that accounts for tool executions during a
+ *                 build.
+ *   - `ui`      — the render seam: the {@link TranscriptModel} visitor that
+ *                 sanitizes and projects a build transcript, and the minimal text
+ *                 {@link ForgeView} the builder loop talks to.
+ *   - `forge`   — the {@link Forge} build session that wires all of the above
+ *                 into an interactive (or config-driven) agent-builder and
+ *                 instantiates the finished blueprint into a runnable agent.
+ *
+ * The interactive view layer is kept behind {@link ForgeView}, a minimal text
+ * seam free of any terminal toolkit.
+ */
+export * from "./config";
+export * from "./persona";
+export * from "./knowledge";
+export * from "./runtime";
+export * from "./ui";
+export { Forge, createForge } from "./forge";
+export type { ForgeOptions, InterviewKey, InterviewAnswers, } from "./forge";

package/dist/types/smithy/knowledge/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Smithy knowledge layer — public surface.
+ *
+ * The externalised knowledge pack: a `manifest.json` cataloguing the guide docs
+ * and the markdown bodies under `guides/`, loaded into memory by
+ * {@link loadKnowledge}. A consumer imports the loader from here and reads guides
+ * by id without touching the filesystem layout directly.
+ */
+export { loadKnowledge, KnowledgeError, } from "./loader";
+export type { KnowledgePack, KnowledgeManifest, GuideManifestEntry, Guide, } from "./loader";

package/dist/types/smithy/knowledge/loader.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `loadKnowledge` — read Smithy's knowledge pack off disk into a {@link KnowledgePack}.
+ *
+ * The knowledge pack used to live as one big inline constant baked into the
+ * source. That made it invisible to anyone editing the prose, impossible to diff
+ * sensibly, and welded the docs to the build. Here it is *externalised*: a
+ * `manifest.json` lists the guides by id, title, file, and summary, and each
+ * guide is a plain markdown file beside it under `guides/`. This loader is the
+ * single seam that turns those files back into structured, in-memory data the
+ * rest of Smithy can consult.
+ *
+ * The manifest is the source of truth for *which* guides exist and how they are
+ * described; the markdown files are the source of truth for their *bodies*. The
+ * loader reads the manifest first, then pulls each referenced file, so a guide
+ * that is listed but missing on disk surfaces as a clear error rather than a
+ * silent gap.
+ */
+/** One guide's manifest entry: how it is catalogued, plus where its body lives. */
+export interface GuideManifestEntry {
+    /** Stable, file-safe identifier used to look the guide up. */
+    readonly id: string;
+    /** Human-readable title. */
+    readonly title: string;
+    /** Path to the guide's markdown body, relative to the manifest. */
+    readonly file: string;
+    /** One-line description of what the guide covers. */
+    readonly summary: string;
+}
+/** The parsed shape of `manifest.json` before bodies are attached. */
+export interface KnowledgeManifest {
+    /** Manifest schema/content version. */
+    readonly version: string;
+    /** The guides this pack ships, in catalogue order. */
+    readonly guides: readonly GuideManifestEntry[];
+}
+/** One fully-loaded guide: its manifest metadata plus its markdown body. */
+export interface Guide extends GuideManifestEntry {
+    /** The guide's markdown body, read from {@link GuideManifestEntry.file}. */
+    readonly body: string;
+}
+/** The whole knowledge pack: the manifest version plus every loaded guide. */
+export interface KnowledgePack {
+    /** The manifest's declared version. */
+    readonly version: string;
+    /** Every guide, with its body attached, in manifest order. */
+    readonly guides: readonly Guide[];
+    /** Look a guide up by its {@link Guide.id}; `undefined` if absent. */
+    guide(id: string): Guide | undefined;
+}
+/** Raised when the knowledge pack cannot be loaded or fails its shape check. */
+export declare class KnowledgeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Load the knowledge pack from `dir` (defaults to this module's own directory).
+ *
+ * Reads and validates `manifest.json`, then reads each guide's markdown body,
+ * resolving file paths relative to the manifest. The returned pack is frozen and
+ * carries a {@link KnowledgePack.guide} lookup. Any missing or malformed input
+ * surfaces as a {@link KnowledgeError}.
+ *
+ * @param dir Optional directory holding `manifest.json` and `guides/`.
+ */
+export declare function loadKnowledge(dir?: string): Promise<KnowledgePack>;