dna-sdk 0.3.1 → 0.5.0

package/dist/adapters/source-url.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `sourceFromUrl` — the URL → SourcePort factory, as a PUBLIC SDK surface.
+ *
+ * 1:1 parity with python `dna/adapters/source_url.py`. Promotes URL→adapter
+ * resolution out of ad-hoc host code so `fromConfig()` and any host share ONE
+ * factory.
+ *
+ * Scheme map (TS runtime):
+ *
+ *   file:// <path>      → FilesystemSource (read/write on disk)
+ *   fs:// <path>        → alias of file://
+ *   <plain path>        → treated as file://<path>
+ *   postgresql:// …     → PostgresSource (node-postgres)
+ *   postgres:// …       → alias of postgresql://
+ *   sqlite:// <path>    → NOT SUPPORTED in the TS runtime (Python-only; the
+ *                         SqlAlchemy adapter is a Python thing) — fails loud.
+ *
+ * An unknown scheme fails loud with the supported set.
+ */
+import type { SourcePort } from "../kernel/protocols.js";
+export declare class UnsupportedSourceScheme extends Error {
+    constructor(message: string);
+}
+interface SourceFromUrlOptions {
+    /** Postgres schema namespace (postgres sources only). */
+    schema?: string;
+}
+/**
+ * Build a source from a scheme URL (see module docstring).
+ *
+ * Postgres sources run their migrations on first use; this awaits `init()` so
+ * the returned source is ready.
+ */
+export declare function sourceFromUrl(url: string, opts?: SourceFromUrlOptions): Promise<SourcePort>;
+/**
+ * The `file://` URL the SDK falls back to with no explicit config.
+ * Priority: explicit override > `DNA_BASE_DIR` env > `./.dna`.
+ */
+export declare function resolveDefaultFsUrl(baseDirOverride?: string): string;
+export {};

package/dist/adapters/source-url.js

@@ -0,0 +1,55 @@
+export class UnsupportedSourceScheme extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnsupportedSourceScheme";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+function urlToFsPath(url) {
+    // Mirror the Python rule (join netloc + path so `fs://./x` stays RELATIVE).
+    const m = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\/(.*)$/.exec(url);
+    if (!m)
+        return url; // plain path, no scheme
+    return m[2]; // everything after scheme:// (host+path joined)
+}
+function schemeOf(url) {
+    const m = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(url);
+    return (m ? m[1] : "file").toLowerCase();
+}
+/**
+ * Build a source from a scheme URL (see module docstring).
+ *
+ * Postgres sources run their migrations on first use; this awaits `init()` so
+ * the returned source is ready.
+ */
+export async function sourceFromUrl(url, opts = {}) {
+    const scheme = schemeOf(url);
+    const base = scheme.split("+", 1)[0];
+    if (scheme === "file" || scheme === "fs" || scheme === "") {
+        const { FilesystemSource } = await import("./filesystem/source.js");
+        return new FilesystemSource(urlToFsPath(url) || url);
+    }
+    if (base === "postgresql" || base === "postgres") {
+        const { PostgresSource } = await import("./postgres/source.js");
+        const src = new PostgresSource({ connectionString: url, schema: opts.schema });
+        await src.init();
+        return src;
+    }
+    if (base === "sqlite") {
+        throw new UnsupportedSourceScheme(`sqlite:// sources are Python-only — they ride the Python SqlAlchemy ` +
+            `adapter, which the TypeScript runtime does not ship. Use file:// ` +
+            `(filesystem) or postgresql:// here. Got: ${url}`);
+    }
+    throw new UnsupportedSourceScheme(`unsupported source URL scheme '${scheme}://' — the TS runtime ships ` +
+        `file:// (filesystem) and postgresql:// adapters. Got: ${url}`);
+}
+/**
+ * The `file://` URL the SDK falls back to with no explicit config.
+ * Priority: explicit override > `DNA_BASE_DIR` env > `./.dna`.
+ */
+export function resolveDefaultFsUrl(baseDirOverride) {
+    const base = baseDirOverride ?? process.env.DNA_BASE_DIR;
+    if (base)
+        return `file://${base}`;
+    return "file://.dna";
+}

package/dist/bootstrap.d.ts

@@ -43,3 +43,18 @@ export declare function createRuntimeWithBuiltins(): Runtime;
  * `ManifestInstance` for the given scope.
  */
 export declare function quickManifest(scope: string, baseDir?: string): Promise<ManifestInstance>;
+/**
+ * Boot a fully-wired Kernel from a `dna.config.yaml` (declarative port wiring —
+ * s-dx-kernel-from-config). TS twin of python `Kernel.from_config`.
+ *
+ * The config selects the `source` (`file://` / `postgresql://`) and,
+ * optionally, the `search` + `embedding` providers; every port is resolved to
+ * its adapter and wired. With NO config present (and no `path`) the behavior is
+ * unchanged — a filesystem `.dna` source, exactly like the bare default.
+ *
+ * Returns a wired Kernel; call `.instance(scope)` for the ManifestInstance.
+ * (Python exposes this as the `Kernel.from_config` static; the TS bootstrap
+ * keeps it a free function, mirroring `quickInstance` — same documented
+ * asymmetry the SDK already lives with.)
+ */
+export declare function fromConfig(path?: string): Promise<Kernel>;

package/dist/bootstrap.js

@@ -40,6 +40,8 @@ import { TestkitExtension } from "./extensions/testkit.js";
 import { ModelRegExtension } from "./extensions/modelreg.js";
 import { AutomationExtension } from "./extensions/automation.js";
 import { EvalExtension } from "./extensions/eval.js";
+import { loadConfig } from "./config.js";
+import { resolveDefaultFsUrl, sourceFromUrl } from "./adapters/source-url.js";
 /**
  * The canonical built-in extension set. Loaded into BOTH a Kernel and a
  * Runtime through this SINGLE list so the two bootstraps can never drift
@@ -132,3 +134,84 @@ export async function quickManifest(scope, baseDir = ".dna") {
     rt.resolver("github", new GitHubResolver());
     return rt.manifest(scope);
 }
+/** Minimal CachePort for non-filesystem sources (all docs self-contained).
+ *  TS twin of python `kernel_bootstrap._NoopCache`. */
+class NoopCache {
+    async loadAll() {
+        return [];
+    }
+    async loadKey() {
+        return [];
+    }
+    async store(_scope, _key, _items) {
+        // no-op
+    }
+    async has() {
+        return true; // pretend always hit → skip resolver calls
+    }
+}
+/**
+ * Boot a fully-wired Kernel from a `dna.config.yaml` (declarative port wiring —
+ * s-dx-kernel-from-config). TS twin of python `Kernel.from_config`.
+ *
+ * The config selects the `source` (`file://` / `postgresql://`) and,
+ * optionally, the `search` + `embedding` providers; every port is resolved to
+ * its adapter and wired. With NO config present (and no `path`) the behavior is
+ * unchanged — a filesystem `.dna` source, exactly like the bare default.
+ *
+ * Returns a wired Kernel; call `.instance(scope)` for the ManifestInstance.
+ * (Python exposes this as the `Kernel.from_config` static; the TS bootstrap
+ * keeps it a free function, mirroring `quickInstance` — same documented
+ * asymmetry the SDK already lives with.)
+ */
+export async function fromConfig(path) {
+    const cfg = loadConfig(path);
+    const sourceUrl = cfg ? cfg.source : resolveDefaultFsUrl();
+    const source = await sourceFromUrl(sourceUrl);
+    const k = createKernelWithBuiltins();
+    k.source(source);
+    if (source.supportsReaders) {
+        const baseDir = source.baseDir;
+        k.cache(new FilesystemCache(baseDir));
+        k.resolver("local", new LocalResolver(baseDir));
+        k.resolver("http", new HttpResolver());
+        k.resolver("https", new HttpResolver());
+        k.resolver("github", new GitHubResolver());
+    }
+    else {
+        k.cache(new NoopCache());
+    }
+    // Uniform writer/reader wiring for any KernelAttachable source.
+    const attach = source.attachKernel;
+    if (typeof attach === "function")
+        attach.call(source, k);
+    if (cfg) {
+        await wireSearch(k, cfg);
+        await wireEmbedding(k, cfg);
+    }
+    return k;
+}
+async function wireEmbedding(kernel, cfg) {
+    if (cfg.embedding === "off" || cfg.embedding === "fake")
+        return;
+    if (cfg.embedding === "onnx") {
+        // Dynamic import: the ONNX adapter (transformers.js) must never enter the
+        // default bundle (guard: tests/embedding-import-isolation.test.ts).
+        const { OnnxEmbeddingProvider } = await import("./adapters/embedding/onnx.js");
+        kernel.embeddingProvider(new OnnxEmbeddingProvider());
+    }
+}
+async function wireSearch(kernel, cfg) {
+    if (cfg.search === "off")
+        return;
+    if (cfg.search === "sqlite-vec") {
+        // Dynamic import: sqlite-vec must never enter the default bundle
+        // (guard: tests/search-import-isolation.test.ts).
+        const { SqliteVecRecordSearchProvider } = await import("./adapters/search/sqlite-vec.js");
+        kernel.recordSearchProvider(new SqliteVecRecordSearchProvider(kernel, {}));
+    }
+    else if (cfg.search === "pgvector") {
+        throw new Error("search: pgvector is Python-only in this build — the TS runtime ships " +
+            "the sqlite-vec record-search provider. Use `search: sqlite-vec` here.");
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,34 @@
+export declare const CONFIG_FILENAME = "dna.config.yaml";
+declare const VALID_SEARCH: readonly ["off", "pgvector", "sqlite-vec"];
+declare const VALID_EMBEDDING: readonly ["off", "fake", "onnx"];
+export type SearchMode = (typeof VALID_SEARCH)[number];
+export type EmbeddingMode = (typeof VALID_EMBEDDING)[number];
+/** Parsed + validated `dna.config.yaml`. */
+export interface DnaConfig {
+    /** Scheme URL: `file://` | `sqlite://` | `postgresql://`. */
+    source: string;
+    /** Record-search provider selector (default `off`). */
+    search: SearchMode;
+    /** Embedding provider selector (default `off`). */
+    embedding: EmbeddingMode;
+    /** Where it was loaded from (`null` for a synthesized default). */
+    path: string | null;
+}
+/**
+ * Path to `dna.config.yaml` in `start` (default: cwd), or `null` if absent.
+ * Deliberately NOT a walk-up — a config's meaning is tied to the boot dir.
+ */
+export declare function findConfig(start?: string): string | null;
+/**
+ * Load + validate `dna.config.yaml`.
+ *
+ * - `path` given → it MUST exist (a typo'd path is an error, not a silent
+ *   fallback); parsed and validated.
+ * - `path` omitted → look for `dna.config.yaml` in cwd. Found → parsed. Absent
+ *   → `null` (the caller keeps its default: a filesystem `.dna` source).
+ *
+ * Throws on: not-a-mapping, missing `source`, unknown keys, or an out-of-enum
+ * `search` / `embedding` value.
+ */
+export declare function loadConfig(path?: string): DnaConfig | null;
+export {};

package/dist/config.js

@@ -0,0 +1,102 @@
+/**
+ * `dna.config.yaml` — declarative port wiring (s-dx-kernel-from-config).
+ *
+ * 1:1 parity with python `dna/config.py`. The SAME file drives both SDKs — the
+ * schema is language-agnostic:
+ *
+ * ```yaml
+ * # dna.config.yaml
+ * source: postgresql://user:pass@host/db   # or sqlite:///./dev.db, file://.dna
+ * search: pgvector        # pgvector | sqlite-vec | off   (default: off)
+ * embedding: onnx         # onnx | fake | off             (default: off / fake floor)
+ * ```
+ *
+ * Only `source` is required. This module parses + VALIDATES the file (unknown
+ * keys and bad enum values fail loud); the wiring lives in `fromConfig()`.
+ *
+ * Runtime asymmetry (documented, not silent): the TS runtime ships the
+ * filesystem + postgres source adapters; `sqlite://` is Python-only (it rides
+ * the Python-only SqlAlchemy adapter). A `sqlite://` source — or a `pgvector`
+ * search — in a TS host fails loud with that explanation at wire time.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import yaml from "js-yaml";
+export const CONFIG_FILENAME = "dna.config.yaml";
+const VALID_SEARCH = ["off", "pgvector", "sqlite-vec"];
+const VALID_EMBEDDING = ["off", "fake", "onnx"];
+const KNOWN_KEYS = new Set(["source", "search", "embedding"]);
+/**
+ * Path to `dna.config.yaml` in `start` (default: cwd), or `null` if absent.
+ * Deliberately NOT a walk-up — a config's meaning is tied to the boot dir.
+ */
+export function findConfig(start) {
+    const candidate = join(start ?? process.cwd(), CONFIG_FILENAME);
+    return existsSync(candidate) ? candidate : null;
+}
+/**
+ * Load + validate `dna.config.yaml`.
+ *
+ * - `path` given → it MUST exist (a typo'd path is an error, not a silent
+ *   fallback); parsed and validated.
+ * - `path` omitted → look for `dna.config.yaml` in cwd. Found → parsed. Absent
+ *   → `null` (the caller keeps its default: a filesystem `.dna` source).
+ *
+ * Throws on: not-a-mapping, missing `source`, unknown keys, or an out-of-enum
+ * `search` / `embedding` value.
+ */
+export function loadConfig(path) {
+    let resolved;
+    if (path !== undefined) {
+        if (!existsSync(path)) {
+            throw new Error(`dna config not found at ${path} — pass a path to an existing ` +
+                `${CONFIG_FILENAME}, or omit it to auto-discover one in the ` +
+                `current directory.`);
+        }
+        resolved = path;
+    }
+    else {
+        const found = findConfig();
+        if (found === null)
+            return null;
+        resolved = found;
+    }
+    const raw = yaml.load(readFileSync(resolved, "utf-8"));
+    return parse(raw, resolved);
+}
+function parse(raw, path) {
+    if (raw === null || raw === undefined) {
+        throw new Error(`${path} is empty — it must at least declare a \`source:\` URL ` +
+            `(e.g. \`source: file://.dna\`).`);
+    }
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`${path} must be a YAML mapping (key: value).`);
+    }
+    const obj = raw;
+    const unknown = Object.keys(obj).filter((k) => !KNOWN_KEYS.has(k)).sort();
+    if (unknown.length > 0) {
+        throw new Error(`${path}: unknown key(s) ${JSON.stringify(unknown)} — supported keys ` +
+            `are ${JSON.stringify([...KNOWN_KEYS].sort())}.`);
+    }
+    const source = obj.source;
+    if (typeof source !== "string" || source.length === 0) {
+        throw new Error(`${path}: \`source:\` is required and must be a URL string ` +
+            `(file:// | sqlite:// | postgresql://).`);
+    }
+    const search = String(obj.search ?? "off").trim() || "off";
+    if (!VALID_SEARCH.includes(search)) {
+        throw new Error(`${path}: \`search: ${search}\` is not valid — choose one of ` +
+            `${JSON.stringify(VALID_SEARCH)}.`);
+    }
+    const embedding = String(obj.embedding ?? "off").trim() || "off";
+    if (!VALID_EMBEDDING.includes(embedding)) {
+        throw new Error(`${path}: \`embedding: ${embedding}\` is not valid — choose one of ` +
+            `${JSON.stringify(VALID_EMBEDDING)}.`);
+    }
+    return {
+        source,
+        search: search,
+        embedding: embedding,
+        path,
+    };
+}

package/dist/extensions/helix.js

@@ -13,6 +13,33 @@ import { readSpecString, readSpecStringArray } from "../kernel/spec-access.js";
 import { SettingKind, ThemeKind, UserProfileKind, CanvasKind } from "./helix_extras.js";
 import { registerWriteGuards } from "./helix/write-guards.js";
 const MOD_URL = import.meta.url;
+// ── Named composition layouts (s-dx-named-layouts) ─────────────────────
+//
+// An author orders persona-vs-instruction by NAME (`layout:` in the Agent
+// spec) instead of hand-writing raw Mustache with internal section names.
+// Each preset resolves to one of these embedded templates via
+// `AgentKind.layoutTemplate()`. 1:1 with Python `dna.extensions.helix`.
+//
+// The guardrails block is shared verbatim — guardrails are hard policy and
+// always land LAST, after both the instruction and the soul, regardless of
+// their relative order. (Aligns TS composition to Python, closing the
+// pre-existing i-213/i-011 divergence where TS omitted the guardrails block.)
+const GUARDRAILS_BLOCK = "{{#guardrails-guardrail}}" +
+    "## Guardrail: {{name}} ({{severity}})\n" +
+    "{{#description}}_{{description}}_\n\n{{/description}}" +
+    "{{#rules}}- {{{.}}}\n{{/rules}}\n" +
+    "{{/guardrails-guardrail}}";
+// instruction-first (a.k.a. "default") — historic order: instruction, soul,
+// guardrails. IS the kind default template.
+const LAYOUT_INSTRUCTION_FIRST = "{{{agent.instruction}}}\n\n{{{soul_content}}}\n\n" + GUARDRAILS_BLOCK;
+// persona-first — Soul leads, then instruction, then guardrails.
+const LAYOUT_PERSONA_FIRST = "{{{soul_content}}}\n\n{{{agent.instruction}}}\n\n" + GUARDRAILS_BLOCK;
+const AGENT_LAYOUTS = {
+    default: LAYOUT_INSTRUCTION_FIRST,
+    "instruction-first": LAYOUT_INSTRUCTION_FIRST,
+    "persona-first": LAYOUT_PERSONA_FIRST,
+};
+const AGENT_LAYOUT_NAMES = ["default", "instruction-first", "persona-first"];
 // GenomeKind — Phase 16 (scope segregation)
 //
 // Replaces ModuleKind as the scope-root identity Kind. Carries catalog
@@ -253,6 +280,13 @@ class AgentKind extends KindBase {
         },
         objective: { widget: "textarea", label: "Objective", order: 15 },
         model: { widget: "text", label: "Model", order: 20 },
+        layout: {
+            widget: "select",
+            label: "Layout",
+            options: ["default", "instruction-first", "persona-first"],
+            help: "Named composition order — 'persona-first' puts the Soul before the instruction. Leave empty for the default. A raw promptTemplate, if set, overrides this.",
+            order: 25,
+        },
         soul: { widget: "text", label: "Soul", help: "Name of the Soul doc to flatten into the prompt.", order: 30 },
         skills: { widget: "tags", label: "Skills", order: 40 },
         actors: { widget: "tags", label: "Actors this agent serves", order: 50 },
@@ -305,7 +339,17 @@ class AgentKind extends KindBase {
         return { skills: skills.length, soul: readSpecString(doc, "soul") ?? null };
     }
     promptTemplate() {
-        return "{{{agent.instruction}}}\n\n{{{soul_content}}}";
+        // IS the `instruction-first` / `default` named layout — the kind default
+        // template and the `default` layout are one string, so an agent with no
+        // `layout:` composes identically. (Now includes the guardrails block,
+        // matching Python — see the layout-constants comment above.)
+        return LAYOUT_INSTRUCTION_FIRST;
+    }
+    layoutTemplate(name) {
+        return AGENT_LAYOUTS[name] ?? null;
+    }
+    layoutNames() {
+        return [...AGENT_LAYOUT_NAMES];
     }
     preview(doc) {
         const spec = (doc.spec ?? {});

package/dist/extensions/sdlc.js

@@ -27,6 +27,7 @@
 import { KindBase } from "../kernel/kind_base.js";
 import { SD, TenantScope } from "../kernel/protocols.js";
 import { loadDescriptors } from "../kernel/descriptor-loader.js";
+import { HtmlArtifactSchema } from "../kernel/models.js";
 const API_VERSION = "github.com/ruinosus/dna/sdlc/v1";
 // v1.3: MILESTONE_STATUSES → EPIC_STATUSES (Jira/ADO alignment).
 const EPIC_STATUSES = ["planning", "in-progress", "done", "cancelled", "deprecated"];
@@ -1280,6 +1281,161 @@ const JOURNEY_METHODOLOGIES = [
 // the old class is frozen in sdk-py tests/test_kaizen_descriptor_equivalence.py
 // + tests/sdlc.test.ts.
 // ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// HtmlArtifact — an HTML page as a first-class work-item output (record plane)
+//
+// s-dx-html-artifact-kind. 1:1 parity with Python HtmlArtifactKind. Bundle
+// Kind: ARTIFACT.html holds the raw HTML VERBATIM (byte-faithful round-trip —
+// no frontmatter injection), plus an optional artifact.json companion with
+// structured metadata (title, description, source, created_at) — the same
+// mechanic as a Soul (SOUL.md + soul.json). Custom reader/writer (not the
+// generic marker-frontmatter path) because the marker is arbitrary HTML.
+// ---------------------------------------------------------------------------
+class HtmlArtifactKind extends KindBase {
+    apiVersion = API_VERSION;
+    kind = "HtmlArtifact";
+    // alias GENERATED = "<owner>-<kebab(kind)>" = "sdlc-html-artifact".
+    // s-alias-generated-not-typed: new Kinds must NOT type an explicit alias
+    // (EXPLICIT_ALIAS_ALLOWLIST ratchet is shrink-only). Empty here + aliasOwner
+    // triggers generation at load time (Py twin sets alias=None + alias_owner).
+    alias = "";
+    aliasOwner = "sdlc";
+    origin = "github.com/ruinosus/dna/sdlc";
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    plane = "record";
+    storage = SD.bundle("html-artifacts", "ARTIFACT.html");
+    graphStyle = { fill: "#EA580C", stroke: "#C2410C", textColor: "#fff" };
+    asciiIcon = "📄";
+    displayLabel = "HTML Artifacts";
+    uiSchema = {
+        html: {
+            widget: "code",
+            language: "html",
+            label: "ARTIFACT.html",
+            help: "The raw HTML page (stored byte-faithful).",
+            height: 520,
+            order: 10,
+        },
+        artifact_json: {
+            widget: "code",
+            language: "json",
+            label: "artifact.json",
+            help: "Structured metadata (title, description, source, created_at).",
+            height: 220,
+            order: 20,
+        },
+    };
+    docs = "An HtmlArtifact stores an HTML page as a first-class, linkable output " +
+        "of a work item (Story/Feature/Epic/Spike). Bundle: ARTIFACT.html holds " +
+        "the raw HTML verbatim (byte-faithful round-trip) plus an optional " +
+        "artifact.json companion with structured metadata (title, description, " +
+        "source, created_at) — the same shape as a Soul's SOUL.md + soul.json. " +
+        "Attach one with `dna sdlc produces add <WiKind>/<wi> HtmlArtifact/<name>`.";
+    schema() {
+        return {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                html: { type: "string", description: "The raw HTML document (byte-faithful)." },
+                artifact_json: {
+                    type: "object",
+                    additionalProperties: true,
+                    description: "Structured metadata: title, description, source, created_at.",
+                },
+            },
+        };
+    }
+    parse(raw) {
+        return HtmlArtifactSchema.parse(raw);
+    }
+    summary(doc) {
+        const spec = (doc.spec ?? {});
+        const aj = spec.artifact_json ?? {};
+        return {
+            title: aj.title ?? null,
+            source: aj.source ?? null,
+            created_at: aj.created_at ?? null,
+            html_bytes: (spec.html ?? "").length,
+        };
+    }
+    preview(doc) {
+        const spec = (doc.spec ?? {});
+        const blocks = [];
+        if (typeof spec.html === "string" && spec.html) {
+            blocks.push({ kind: "code", title: "ARTIFACT.html", body: spec.html, language: "html" });
+        }
+        if (spec.artifact_json && typeof spec.artifact_json === "object") {
+            blocks.push({
+                kind: "code",
+                title: "artifact.json",
+                body: JSON.stringify(spec.artifact_json, null, 2),
+                language: "json",
+            });
+        }
+        if (blocks.length === 0) {
+            return [{ kind: "empty", title: "HtmlArtifact (empty)" }];
+        }
+        return blocks;
+    }
+}
+class HtmlArtifactReader {
+    async detect(bundle) {
+        return bundle.exists("ARTIFACT.html");
+    }
+    async read(bundle) {
+        const spec = {};
+        const metadata = {};
+        // ARTIFACT.html — read verbatim (byte-faithful; no frontmatter parse).
+        if (await bundle.exists("ARTIFACT.html")) {
+            spec.html = await bundle.readText("ARTIFACT.html");
+        }
+        // artifact.json companion — structured metadata.
+        if (await bundle.exists("artifact.json")) {
+            const aj = JSON.parse(await bundle.readText("artifact.json"));
+            if (aj && typeof aj === "object" && !Array.isArray(aj)) {
+                spec.artifact_json = aj;
+                const desc = aj.description;
+                if (typeof desc === "string" && desc && !metadata.description) {
+                    metadata.description = desc;
+                }
+            }
+        }
+        if (metadata.name == null)
+            metadata.name = bundle.name;
+        return {
+            apiVersion: API_VERSION,
+            kind: "HtmlArtifact",
+            metadata,
+            spec,
+        };
+    }
+}
+class HtmlArtifactWriter {
+    canWrite(raw) {
+        return raw.kind === "HtmlArtifact";
+    }
+    serialize(raw) {
+        const files = [];
+        const spec = raw.spec ?? {};
+        // ARTIFACT.html — verbatim HTML (byte-faithful).
+        files.push({ relativePath: "ARTIFACT.html", content: spec.html ?? "" });
+        // artifact.json — canonical JSON companion. metadata.description is a
+        // DERIVED promotion of artifact_json.description on read, so it is NOT
+        // re-emitted separately (no phantom frontmatter — F3 market-fidelity).
+        const aj = spec.artifact_json;
+        if (aj && typeof aj === "object") {
+            files.push({ relativePath: "artifact.json", content: JSON.stringify(aj, null, 2) });
+        }
+        return files;
+    }
+    async write(bundle, raw) {
+        for (const f of this.serialize(raw)) {
+            await bundle.writeText(f.relativePath, f.content ?? "");
+        }
+    }
+}
 export class SdlcExtension {
     name = "sdlc";
     // v1.14.0 — s-consolidate-cognitive-policies: the 9 cognitive policy
@@ -1302,6 +1458,12 @@ export class SdlcExtension {
         // v1.10.0 — f-reference-citation-kind (ported from Python for
         // s-alias-generated-not-typed: Spike.depFilters → "sdlc-reference").
         kernel.kind(new ReferenceKind());
+        // s-dx-html-artifact-kind — HTML page as a first-class work-item output.
+        // Bundle Kind with a custom reader/writer for byte-faithful HTML,
+        // mirroring the Soul (SOUL.md + soul.json) mechanic.
+        kernel.kind(new HtmlArtifactKind());
+        kernel.reader(new HtmlArtifactReader());
+        kernel.writer(new HtmlArtifactWriter());
         // expr batch B: PromptTemplate is a descriptor now — registered via the
         // loadDescriptors loop below. s-consolidate-cognitive-policies: the
         // cognitive policy family is ONE descriptor (cognitive-policy.kind.yaml).

package/dist/index.d.ts

@@ -21,7 +21,12 @@ export { LockManager } from "./kernel/lock-manager.js";
 export { ReportBuilder } from "./kernel/reports.js";
 export { serializeRawToFiles } from "./kernel/serialize-to-files.js";
 export * from "./viz/index.js";
-export { createKernelWithBuiltins, quickInstance, createRuntimeWithBuiltins, quickManifest } from "./bootstrap.js";
+export { createKernelWithBuiltins, quickInstance, createRuntimeWithBuiltins, quickManifest, fromConfig } from "./bootstrap.js";
+export { AgentNotFound, UnknownLayout } from "./kernel/errors.js";
+export { PromptLibrary, loadPrompts } from "./prompts.js";
+export { loadConfig, findConfig, CONFIG_FILENAME } from "./config.js";
+export type { DnaConfig, SearchMode, EmbeddingMode } from "./config.js";
+export { sourceFromUrl, resolveDefaultFsUrl, UnsupportedSourceScheme } from "./adapters/source-url.js";
 export { HookRegistry, KNOWN_HOOK_NAMES } from "./kernel/hooks.js";
 export type { HookContext, HookName, HookNameArg, Middleware, EventHandler, PreSaveContext, VetoHandler, } from "./kernel/hooks.js";
 export type { SourcePort, CachePort, ResolverPort, ReaderPort, WriterPort, KindPort, KindPresentation, Extension, ExtensionHost, CompositionResult, CacheItem, ResolvedItem, StorageDescriptor, StoragePattern, BodyMode, SerializedFile, SerializedDocument, WritableSourcePort, QueryFilter, QueryOrder, CountResult, SourceQueryOpts, SourceCountOpts, RecordStorePort, RecordSearchProvider, EmbeddingPort, ToolPort, } from "./kernel/protocols.js";

package/dist/index.js

@@ -24,7 +24,13 @@ export { serializeRawToFiles } from "./kernel/serialize-to-files.js";
 // Viz — diagram generators, health, matrix, ASCII tree
 export * from "./viz/index.js";
 // Opinionated bootstrap — extension wiring lives here, not in kernel/
-export { createKernelWithBuiltins, quickInstance, createRuntimeWithBuiltins, quickManifest } from "./bootstrap.js";
+export { createKernelWithBuiltins, quickInstance, createRuntimeWithBuiltins, quickManifest, fromConfig } from "./bootstrap.js";
+// DX consumer surface (s-dx-*): fail-loud prompt building + the collapse-the-
+// shim helper + declarative port wiring.
+export { AgentNotFound, UnknownLayout } from "./kernel/errors.js";
+export { PromptLibrary, loadPrompts } from "./prompts.js";
+export { loadConfig, findConfig, CONFIG_FILENAME } from "./config.js";
+export { sourceFromUrl, resolveDefaultFsUrl, UnsupportedSourceScheme } from "./adapters/source-url.js";
 export { HookRegistry, KNOWN_HOOK_NAMES } from "./kernel/hooks.js";
 // i-005 — types REFERENCED by already-exported public API, previously
 // broken xrefs in TypeDoc. Each is public surface a consumer needs to name:

package/dist/kernel/errors.d.ts

@@ -13,6 +13,41 @@
  * These errors surface those problems at boot time instead of as silent
  * runtime drift.
  */
+/**
+ * `buildPrompt({ agent: X })` was asked for an agent that no prompt-target
+ * document in the loaded manifest declares (missing, renamed, or unparseable).
+ *
+ * Fail-loud contract (s-dx-build-prompt-fail-loud): the builder used to RETURN
+ * the string `"Agent 'X' not found"` instead of throwing — which sailed
+ * straight through a consumer's `if (!text)` check and became the LITERAL
+ * agent instruction. Every consumer therefore wrote the same defensive guard
+ * (`mi.findAgent(x) === null`) before every call. Throwing a typed error
+ * deletes that guard: the miss is now impossible to ignore.
+ *
+ * 1:1 parity with python `dna.AgentNotFound` (a `LookupError` subclass).
+ * Exported publicly from the package root.
+ */
+export declare class AgentNotFound extends Error {
+    readonly agent: string | null;
+    constructor(agent: string | null);
+}
+/**
+ * `buildPrompt` hit an Agent whose `layout:` names a preset the Kind does not
+ * offer (s-dx-named-layouts).
+ *
+ * Fail-loud DX: a typo'd layout (`persona_first` for `persona-first`) must not
+ * silently fall through to the Kind default and compose in the wrong order —
+ * it throws with the valid names listed.
+ *
+ * 1:1 parity with python `dna.UnknownLayout` (a `ValueError` subclass).
+ * Exported publicly from the package root.
+ */
+export declare class UnknownLayout extends Error {
+    readonly layout: string;
+    readonly available: string[];
+    readonly agent: string | null;
+    constructor(layout: string, available?: string[], agent?: string | null);
+}
 /** Base class for kernel registration validation failures. */
 export declare class KernelRegistrationError extends Error {
     constructor(message?: string);

package/dist/kernel/errors.js

@@ -13,6 +13,55 @@
  * These errors surface those problems at boot time instead of as silent
  * runtime drift.
  */
+/**
+ * `buildPrompt({ agent: X })` was asked for an agent that no prompt-target
+ * document in the loaded manifest declares (missing, renamed, or unparseable).
+ *
+ * Fail-loud contract (s-dx-build-prompt-fail-loud): the builder used to RETURN
+ * the string `"Agent 'X' not found"` instead of throwing — which sailed
+ * straight through a consumer's `if (!text)` check and became the LITERAL
+ * agent instruction. Every consumer therefore wrote the same defensive guard
+ * (`mi.findAgent(x) === null`) before every call. Throwing a typed error
+ * deletes that guard: the miss is now impossible to ignore.
+ *
+ * 1:1 parity with python `dna.AgentNotFound` (a `LookupError` subclass).
+ * Exported publicly from the package root.
+ */
+export class AgentNotFound extends Error {
+    agent;
+    constructor(agent) {
+        super(`Agent '${agent}' not found`);
+        this.name = "AgentNotFound";
+        this.agent = agent;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * `buildPrompt` hit an Agent whose `layout:` names a preset the Kind does not
+ * offer (s-dx-named-layouts).
+ *
+ * Fail-loud DX: a typo'd layout (`persona_first` for `persona-first`) must not
+ * silently fall through to the Kind default and compose in the wrong order —
+ * it throws with the valid names listed.
+ *
+ * 1:1 parity with python `dna.UnknownLayout` (a `ValueError` subclass).
+ * Exported publicly from the package root.
+ */
+export class UnknownLayout extends Error {
+    layout;
+    available;
+    agent;
+    constructor(layout, available = [], agent = null) {
+        const where = agent ? ` on agent '${agent}'` : "";
+        const hint = available.length ? ` — available: ${available.join(", ")}` : "";
+        super(`Unknown layout '${layout}'${where}${hint}`);
+        this.name = "UnknownLayout";
+        this.layout = layout;
+        this.available = available;
+        this.agent = agent;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
 /** Base class for kernel registration validation failures. */
 export class KernelRegistrationError extends Error {
     constructor(message) {

package/dist/kernel/kind_base.d.ts

@@ -94,6 +94,19 @@ export declare abstract class KindBase implements Omit<KindPort, "apiVersion" |
     describe(_doc: Document): string | null;
     summary(doc: Document): Record<string, unknown> | null;
     promptTemplate(): string | null;
+    /**
+     * Resolve a NAMED composition layout to an embedded template
+     * (s-dx-named-layouts). Prompt-target Kinds override this to expose
+     * author-friendly presets (persona-first, instruction-first) so the common
+     * case never hand-writes Mustache. Returns null for an unknown name (the
+     * prompt builder fails loud). Twin of Python ``KindBase.layout_template``.
+     */
+    layoutTemplate(_name: string): string | null;
+    /**
+     * Public layout names this Kind offers (s-dx-named-layouts) — powers
+     * discovery + fail-loud error messages. Twin of Python ``layout_names``.
+     */
+    layoutNames(): string[];
     protected canonicalSpec(spec: Record<string, unknown>): Record<string, unknown>;
     /** Stable SHA-256 of the doc's authored identity — basis for source
      *  diff/sync. Invariant to key order, formatting, volatile stamps, and

package/dist/kernel/kind_base.js

@@ -215,6 +215,23 @@ export class KindBase {
     promptTemplate() {
         return null;
     }
+    /**
+     * Resolve a NAMED composition layout to an embedded template
+     * (s-dx-named-layouts). Prompt-target Kinds override this to expose
+     * author-friendly presets (persona-first, instruction-first) so the common
+     * case never hand-writes Mustache. Returns null for an unknown name (the
+     * prompt builder fails loud). Twin of Python ``KindBase.layout_template``.
+     */
+    layoutTemplate(_name) {
+        return null;
+    }
+    /**
+     * Public layout names this Kind offers (s-dx-named-layouts) — powers
+     * discovery + fail-loud error messages. Twin of Python ``layout_names``.
+     */
+    layoutNames() {
+        return [];
+    }
     // ---- Source-sync digest (s-sync-s1; twin of Python canonical_digest) ----
     canonicalSpec(spec) {
         const out = {};

package/dist/kernel/models.d.ts

@@ -384,6 +384,7 @@ export declare const AgentSpecSchema: z.ZodObject<{
     tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     guardrails: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     promptTemplate: z.ZodOptional<z.ZodString>;
+    layout: z.ZodOptional<z.ZodString>;
     tool_groups: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     mcp_servers: z.ZodDefault<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
         ref: z.ZodString;
@@ -481,6 +482,7 @@ export declare const AgentSpecSchema: z.ZodObject<{
     reads: Record<string, Record<string, any>>;
     type?: string | undefined;
     promptTemplate?: string | undefined;
+    layout?: string | undefined;
     model?: string | undefined;
     instruction_file?: string | undefined;
     soul?: string | undefined;
@@ -517,6 +519,7 @@ export declare const AgentSpecSchema: z.ZodObject<{
     guardrails?: string[] | undefined;
     instruction?: string | undefined;
     promptTemplate?: string | undefined;
+    layout?: string | undefined;
     model?: string | undefined;
     instruction_file?: string | undefined;
     tags?: string[] | undefined;
@@ -601,6 +604,7 @@ export declare const AgentSchema: z.ZodObject<{
         tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         guardrails: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         promptTemplate: z.ZodOptional<z.ZodString>;
+        layout: z.ZodOptional<z.ZodString>;
         tool_groups: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         mcp_servers: z.ZodDefault<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
             ref: z.ZodString;
@@ -698,6 +702,7 @@ export declare const AgentSchema: z.ZodObject<{
         reads: Record<string, Record<string, any>>;
         type?: string | undefined;
         promptTemplate?: string | undefined;
+        layout?: string | undefined;
         model?: string | undefined;
         instruction_file?: string | undefined;
         soul?: string | undefined;
@@ -734,6 +739,7 @@ export declare const AgentSchema: z.ZodObject<{
         guardrails?: string[] | undefined;
         instruction?: string | undefined;
         promptTemplate?: string | undefined;
+        layout?: string | undefined;
         model?: string | undefined;
         instruction_file?: string | undefined;
         tags?: string[] | undefined;
@@ -810,6 +816,7 @@ export declare const AgentSchema: z.ZodObject<{
         reads: Record<string, Record<string, any>>;
         type?: string | undefined;
         promptTemplate?: string | undefined;
+        layout?: string | undefined;
         model?: string | undefined;
         instruction_file?: string | undefined;
         soul?: string | undefined;
@@ -860,6 +867,7 @@ export declare const AgentSchema: z.ZodObject<{
         guardrails?: string[] | undefined;
         instruction?: string | undefined;
         promptTemplate?: string | undefined;
+        layout?: string | undefined;
         model?: string | undefined;
         instruction_file?: string | undefined;
         tags?: string[] | undefined;
@@ -1551,6 +1559,83 @@ export declare const SoulSchema: z.ZodObject<{
     } | undefined;
 }>;
 export type TypedSoul = z.output<typeof SoulSchema>;
+export declare const HtmlArtifactSpecSchema: z.ZodObject<{
+    html: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    artifact_json: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    html: string;
+    artifact_json?: Record<string, unknown> | undefined;
+}, {
+    html?: string | undefined;
+    artifact_json?: Record<string, unknown> | undefined;
+}>;
+export declare const HtmlArtifactSchema: z.ZodObject<{
+    apiVersion: z.ZodLiteral<"github.com/ruinosus/dna/sdlc/v1">;
+    kind: z.ZodLiteral<"HtmlArtifact">;
+    metadata: z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        icon: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        group: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        labels: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description: string;
+        version: string;
+        icon: string;
+        group: string;
+        labels: Record<string, string>;
+    }, {
+        name: string;
+        description?: string | undefined;
+        version?: string | undefined;
+        icon?: string | undefined;
+        group?: string | undefined;
+        labels?: Record<string, string> | undefined;
+    }>;
+    spec: z.ZodDefault<z.ZodObject<{
+        html: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        artifact_json: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        html: string;
+        artifact_json?: Record<string, unknown> | undefined;
+    }, {
+        html?: string | undefined;
+        artifact_json?: Record<string, unknown> | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    metadata: {
+        name: string;
+        description: string;
+        version: string;
+        icon: string;
+        group: string;
+        labels: Record<string, string>;
+    };
+    spec: {
+        html: string;
+        artifact_json?: Record<string, unknown> | undefined;
+    };
+    apiVersion: "github.com/ruinosus/dna/sdlc/v1";
+    kind: "HtmlArtifact";
+}, {
+    metadata: {
+        name: string;
+        description?: string | undefined;
+        version?: string | undefined;
+        icon?: string | undefined;
+        group?: string | undefined;
+        labels?: Record<string, string> | undefined;
+    };
+    apiVersion: "github.com/ruinosus/dna/sdlc/v1";
+    kind: "HtmlArtifact";
+    spec?: {
+        html?: string | undefined;
+        artifact_json?: Record<string, unknown> | undefined;
+    } | undefined;
+}>;
+export type TypedHtmlArtifact = z.output<typeof HtmlArtifactSchema>;
 export declare const AgentDefinitionSpecSchema: z.ZodObject<{
     content: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {

package/dist/kernel/models.js

@@ -128,6 +128,12 @@ export const AgentSpecSchema = z.object({
     tags: z.array(z.string()).default([]),
     guardrails: z.array(z.string()).default([]),
     promptTemplate: z.string().optional(),
+    // s-dx-named-layouts — pick the composition ORDER by name instead of
+    // hand-writing raw Mustache. "persona-first" puts the Soul before the
+    // instruction; "instruction-first" (a.k.a. "default") keeps the historic
+    // order. Resolved by the Kind's layoutTemplate() into an embedded preset.
+    // A raw promptTemplate still wins over layout when both are set.
+    layout: z.string().optional(),
     // Phase 14x — tool-group specialization (TS parity with Python).
     tool_groups: z.array(z.string()).default([]),
     // s-mcp-servers-on-agent (2026-07-07, spec
@@ -393,6 +399,19 @@ export const SoulSchema = z.object({
     spec: SoulSpecSchema.default({}),
 });
 // ---------------------------------------------------------------------------
+// HtmlArtifact (github.com/ruinosus/dna/sdlc/v1)
+// ---------------------------------------------------------------------------
+export const HtmlArtifactSpecSchema = z.object({
+    html: z.string().optional().default(""),
+    artifact_json: z.record(z.unknown()).optional(),
+});
+export const HtmlArtifactSchema = z.object({
+    apiVersion: z.literal("github.com/ruinosus/dna/sdlc/v1"),
+    kind: z.literal("HtmlArtifact"),
+    metadata: MetadataSchema,
+    spec: HtmlArtifactSpecSchema.default({}),
+});
+// ---------------------------------------------------------------------------
 // AgentDefinition (agents.md/v1)
 // ---------------------------------------------------------------------------
 export const AgentDefinitionSpecSchema = z.object({

package/dist/kernel/prompt-builder.js

@@ -10,6 +10,7 @@
  */
 import Mustache from "mustache";
 import { stripPromptBlock } from "./_text.js";
+import { AgentNotFound, UnknownLayout } from "./errors.js";
 // ---------------------------------------------------------------------------
 // PromptBuilder
 // ---------------------------------------------------------------------------
@@ -38,7 +39,10 @@ export class PromptBuilder {
         }
         const agentDoc = agentName ? this._findAgent(agentName) : null;
         if (!agentDoc) {
-            return `Agent '${agentName}' not found`;
+            // Fail loud (s-dx-build-prompt-fail-loud): throw a typed error instead
+            // of returning a placeholder string that would become the literal
+            // instruction.
+            throw new AgentNotFound(agentName);
         }
         // Build context — merge backwards-compat params into enabledSlots
         const enabledSlots = { ...(opts?.enabledSlots ?? {}) };
@@ -69,7 +73,10 @@ export class PromptBuilder {
                 data: {},
             });
         }
-        return prompt;
+        // Clean output (s-dx-clean-composition-output): template sections can pad
+        // the composed prompt with trailing newlines; consumers used to strip them
+        // themselves. Return it already clean.
+        return prompt.replace(/\n+$/, "");
     }
     // -------------------------------------------------------------------------
     // Private helpers
@@ -199,22 +206,33 @@ export class PromptBuilder {
     async _renderPrompt(ctx, agentDoc) {
         const agentSpec = agentDoc.spec;
         const kinds = this.host._kinds;
-        // 1. Agent-level template override
+        // 1. Agent-level raw template override (poweruser escape hatch).
         const agentTemplate = agentSpec.promptTemplate ??
             agentSpec.prompt_template ??
             null;
         if (agentTemplate) {
             return await this._mustacheRender(agentTemplate, ctx);
         }
-        // 2. Kind default template
         const agentKp = kinds.get(`${agentDoc.apiVersion}\0${agentDoc.kind}`);
+        // 2. Named layout preset (s-dx-named-layouts) — author picks the
+        // composition order by NAME; the kernel resolves it to an embedded
+        // template so the common case never hand-writes Mustache.
+        const layout = agentSpec.layout;
+        if (layout && agentKp) {
+            const layoutTmpl = agentKp.layoutTemplate(layout);
+            if (layoutTmpl == null) {
+                throw new UnknownLayout(layout, agentKp.layoutNames(), agentDoc.name);
+            }
+            return await this._mustacheRender(layoutTmpl, ctx);
+        }
+        // 3. Kind default template
         if (agentKp) {
             const kindTemplate = agentKp.promptTemplate();
             if (kindTemplate) {
                 return await this._mustacheRender(kindTemplate, ctx);
             }
         }
-        // 3. Fallback: agent instruction as plain text
+        // 4. Fallback: agent instruction as plain text
         const agent = ctx.agent;
         return agent?.instruction ?? "";
     }

package/dist/prompts.d.ts

@@ -0,0 +1,27 @@
+import type { ManifestInstance } from "./kernel/instance.js";
+/** Lazy, cached view `agent name -> composed prompt` over one scope. */
+export declare class PromptLibrary {
+    /** The underlying ManifestInstance (drop down for the full surface). */
+    readonly mi: ManifestInstance;
+    private readonly cache;
+    constructor(
+    /** The underlying ManifestInstance (drop down for the full surface). */
+    mi: ManifestInstance);
+    /**
+     * Compose `name`'s prompt (cached). Throws {@link AgentNotFound} on a miss;
+     * the returned text is clean (no trailing newlines).
+     */
+    get(name: string): Promise<string>;
+    /** True when `name` is a prompt-target document in the scope (no compose). */
+    has(name: string): boolean;
+    /** Names of every prompt-target document in the scope, sorted. */
+    names(): string[];
+}
+/**
+ * Compose the prompts of `scope` behind a {@link PromptLibrary}.
+ *
+ * `baseDir` follows the {@link quickInstance} convention — the directory that
+ * holds `<scope>/` (the `.dna` scopes root). Omitted → the `DNA_BASE_DIR` env
+ * var, then `.dna` in the cwd.
+ */
+export declare function loadPrompts(scope: string, baseDir?: string): Promise<PromptLibrary>;

package/dist/prompts.js

@@ -0,0 +1,76 @@
+/**
+ * `loadPrompts` — the one call that collapses the prompt shim (TS twin of
+ * python `dna.load_prompts`).
+ *
+ * With the fail-loud builder (s-dx-build-prompt-fail-loud) and clean output
+ * (s-dx-clean-composition-output) in place, a hand-rolled prompt module
+ * becomes:
+ *
+ * ```ts
+ * import { loadPrompts } from "@ruinosus/dna";
+ *
+ * const prompts = await loadPrompts("helpdesk");
+ * export const TRIAGE = await prompts.get("triage"); // composed, clean, or throws
+ * ```
+ *
+ * `loadPrompts` boots a filesystem kernel for `scope` and returns a
+ * {@link PromptLibrary} — a lazy, cached, read-only view from agent name to
+ * composed system prompt. A missing agent throws {@link AgentNotFound} (never a
+ * placeholder string); the returned text is already stripped of trailing
+ * newlines.
+ *
+ * TS/Py asymmetry: composition is async in TS, so `get(name)` returns a
+ * `Promise<string>` (python's `lib[name]` is sync — same reason `buildPrompt`
+ * is `await`ed in TS but not in Python).
+ */
+import { quickInstance } from "./bootstrap.js";
+/** Lazy, cached view `agent name -> composed prompt` over one scope. */
+export class PromptLibrary {
+    mi;
+    cache = new Map();
+    constructor(
+    /** The underlying ManifestInstance (drop down for the full surface). */
+    mi) {
+        this.mi = mi;
+    }
+    /**
+     * Compose `name`'s prompt (cached). Throws {@link AgentNotFound} on a miss;
+     * the returned text is clean (no trailing newlines).
+     */
+    async get(name) {
+        const cached = this.cache.get(name);
+        if (cached !== undefined)
+            return cached;
+        // buildPrompt throws AgentNotFound on a miss and returns clean text.
+        const text = await this.mi.buildPrompt({ agent: name });
+        this.cache.set(name, text);
+        return text;
+    }
+    /** True when `name` is a prompt-target document in the scope (no compose). */
+    has(name) {
+        return this.names().includes(name);
+    }
+    /** Names of every prompt-target document in the scope, sorted. */
+    names() {
+        const kinds = this.mi._kinds;
+        const seen = new Set();
+        for (const doc of this.mi.documents) {
+            const kp = kinds.get(`${doc.apiVersion}\0${doc.kind}`);
+            if (kp?.isPromptTarget)
+                seen.add(doc.name);
+        }
+        return [...seen].sort();
+    }
+}
+/**
+ * Compose the prompts of `scope` behind a {@link PromptLibrary}.
+ *
+ * `baseDir` follows the {@link quickInstance} convention — the directory that
+ * holds `<scope>/` (the `.dna` scopes root). Omitted → the `DNA_BASE_DIR` env
+ * var, then `.dna` in the cwd.
+ */
+export async function loadPrompts(scope, baseDir) {
+    const resolved = baseDir ?? process.env.DNA_BASE_DIR ?? ".dna";
+    const mi = await quickInstance(scope, resolved);
+    return new PromptLibrary(mi);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dna-sdk",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "DNA — Domain Notation of Anything (TypeScript SDK)",
   "type": "module",
   "license": "MIT",