dna-sdk 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -22,8 +22,12 @@ export { ReportBuilder } from "./kernel/reports.js";
 export { serializeRawToFiles } from "./kernel/serialize-to-files.js";
 export * from "./viz/index.js";
 export { createKernelWithBuiltins, quickInstance, createRuntimeWithBuiltins, quickManifest, fromConfig } from "./bootstrap.js";
-export { AgentNotFound } from "./kernel/errors.js";
+export { AgentNotFound, ToolNotFound, UnknownLayout } from "./kernel/errors.js";
 export { PromptLibrary, loadPrompts } from "./prompts.js";
+export { ToolLibrary, loadTools } from "./tools.js";
+export type { ToolSurface } from "./tools.js";
+export type { LoadPromptsOptions } from "./prompts.js";
+export { anchorScopesRoot, PackageScopeNotFound, DEFAULT_SUBPATH } from "./package-scope.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";

package/dist/index.js

@@ -27,8 +27,10 @@ export * from "./viz/index.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 } from "./kernel/errors.js";
+export { AgentNotFound, ToolNotFound, UnknownLayout } from "./kernel/errors.js";
 export { PromptLibrary, loadPrompts } from "./prompts.js";
+export { ToolLibrary, loadTools } from "./tools.js";
+export { anchorScopesRoot, PackageScopeNotFound, DEFAULT_SUBPATH } from "./package-scope.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";

package/dist/kernel/errors.d.ts

@@ -31,6 +31,41 @@ export declare class AgentNotFound extends Error {
     readonly agent: string | null;
     constructor(agent: string | null);
 }
+/**
+ * `loadTools(scope).get(name)` was asked for a Tool that no `Tool` document in
+ * the scope declares (missing, renamed, or in another scope).
+ *
+ * Fail-loud contract (s-load-tools-helper), the twin of `AgentNotFound`: the
+ * agent-facing tool surface is data, so a miss must throw a typed error —
+ * never return an empty surface that would silently reach a model as a tool
+ * with no description.
+ *
+ * 1:1 parity with python `dna.ToolNotFound` (a `LookupError` subclass).
+ * Exported publicly from the package root.
+ */
+export declare class ToolNotFound extends Error {
+    readonly toolName: string | null;
+    readonly scope: string | null;
+    readonly available: string[];
+    constructor(name: string | null, scope?: string | null, available?: string[]);
+}
+/**
+ * `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

@@ -36,6 +36,59 @@ export class AgentNotFound extends Error {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
+/**
+ * `loadTools(scope).get(name)` was asked for a Tool that no `Tool` document in
+ * the scope declares (missing, renamed, or in another scope).
+ *
+ * Fail-loud contract (s-load-tools-helper), the twin of `AgentNotFound`: the
+ * agent-facing tool surface is data, so a miss must throw a typed error —
+ * never return an empty surface that would silently reach a model as a tool
+ * with no description.
+ *
+ * 1:1 parity with python `dna.ToolNotFound` (a `LookupError` subclass).
+ * Exported publicly from the package root.
+ */
+export class ToolNotFound extends Error {
+    toolName;
+    scope;
+    available;
+    constructor(name, scope = null, available = []) {
+        const where = scope ? ` in scope '${scope}'` : "";
+        const hint = available.length ? ` — available: ${available.join(", ")}` : "";
+        super(`Tool '${name}' not found${where}${hint}`);
+        this.name = "ToolNotFound";
+        this.toolName = name;
+        this.scope = scope;
+        this.available = available;
+        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-registry.js

@@ -115,7 +115,9 @@ export function generateAlias(owner, kind) {
 export const EXPLICIT_ALIAS_ALLOWLIST = new Set([
     // helix
     "helix-genome", "helix-agent", "helix-actor",
-    "helix-usecase", "helix-tool", "policy-layer-policy",
+    // helix-tool migrated to a descriptor (s-tool-kind-descriptor): its alias
+    // lives in helix/kinds/tool.kind.yaml (parity-critical) — shrink-only.
+    "helix-usecase", "policy-layer-policy",
     "helix-canvas",
     "helix-setting", "helix-theme", "helix-user-profile",
     // sdlc (classes; descriptors are outside the ratchet)

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;
@@ -1158,197 +1166,6 @@ export declare const UseCaseSchema: z.ZodObject<{
     } | undefined;
 }>;
 export type TypedUseCase = z.output<typeof UseCaseSchema>;
-export declare const ToolTypeEnum: z.ZodEnum<["http", "mcp", "python", "shell", "builtin"]>;
-export declare const ToolAuthTypeEnum: z.ZodEnum<["none", "api_key", "bearer", "oauth2"]>;
-export declare const ToolSpecSchema: z.ZodObject<{
-    type: z.ZodDefault<z.ZodEnum<["http", "mcp", "python", "shell", "builtin"]>>;
-    endpoint: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    method: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    mcp_server: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    mcp_tool: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    python_module: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    python_callable: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    shell_command: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    input_schema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    output_schema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    auth_type: z.ZodDefault<z.ZodEnum<["none", "api_key", "bearer", "oauth2"]>>;
-    auth_env_var: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    read_only: z.ZodDefault<z.ZodBoolean>;
-    requires_confirmation: z.ZodDefault<z.ZodBoolean>;
-    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    examples: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">>;
-}, "strip", z.ZodTypeAny, {
-    type: "http" | "mcp" | "python" | "shell" | "builtin";
-    tags: string[];
-    input_schema: Record<string, unknown>;
-    endpoint: string;
-    method: string;
-    mcp_server: string;
-    mcp_tool: string;
-    python_module: string;
-    python_callable: string;
-    shell_command: string;
-    output_schema: Record<string, unknown>;
-    auth_type: "none" | "api_key" | "bearer" | "oauth2";
-    auth_env_var: string;
-    read_only: boolean;
-    requires_confirmation: boolean;
-    examples: Record<string, unknown>[];
-}, {
-    type?: "http" | "mcp" | "python" | "shell" | "builtin" | undefined;
-    tags?: string[] | undefined;
-    input_schema?: Record<string, unknown> | undefined;
-    endpoint?: string | undefined;
-    method?: string | undefined;
-    mcp_server?: string | undefined;
-    mcp_tool?: string | undefined;
-    python_module?: string | undefined;
-    python_callable?: string | undefined;
-    shell_command?: string | undefined;
-    output_schema?: Record<string, unknown> | undefined;
-    auth_type?: "none" | "api_key" | "bearer" | "oauth2" | undefined;
-    auth_env_var?: string | undefined;
-    read_only?: boolean | undefined;
-    requires_confirmation?: boolean | undefined;
-    examples?: Record<string, unknown>[] | undefined;
-}>;
-export declare const ToolSchema: z.ZodObject<{
-    apiVersion: z.ZodLiteral<"github.com/ruinosus/dna/v1">;
-    kind: z.ZodLiteral<"Tool">;
-    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<{
-        type: z.ZodDefault<z.ZodEnum<["http", "mcp", "python", "shell", "builtin"]>>;
-        endpoint: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        method: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        mcp_server: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        mcp_tool: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        python_module: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        python_callable: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        shell_command: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        input_schema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        output_schema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        auth_type: z.ZodDefault<z.ZodEnum<["none", "api_key", "bearer", "oauth2"]>>;
-        auth_env_var: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        read_only: z.ZodDefault<z.ZodBoolean>;
-        requires_confirmation: z.ZodDefault<z.ZodBoolean>;
-        tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-        examples: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">>;
-    }, "strip", z.ZodTypeAny, {
-        type: "http" | "mcp" | "python" | "shell" | "builtin";
-        tags: string[];
-        input_schema: Record<string, unknown>;
-        endpoint: string;
-        method: string;
-        mcp_server: string;
-        mcp_tool: string;
-        python_module: string;
-        python_callable: string;
-        shell_command: string;
-        output_schema: Record<string, unknown>;
-        auth_type: "none" | "api_key" | "bearer" | "oauth2";
-        auth_env_var: string;
-        read_only: boolean;
-        requires_confirmation: boolean;
-        examples: Record<string, unknown>[];
-    }, {
-        type?: "http" | "mcp" | "python" | "shell" | "builtin" | undefined;
-        tags?: string[] | undefined;
-        input_schema?: Record<string, unknown> | undefined;
-        endpoint?: string | undefined;
-        method?: string | undefined;
-        mcp_server?: string | undefined;
-        mcp_tool?: string | undefined;
-        python_module?: string | undefined;
-        python_callable?: string | undefined;
-        shell_command?: string | undefined;
-        output_schema?: Record<string, unknown> | undefined;
-        auth_type?: "none" | "api_key" | "bearer" | "oauth2" | undefined;
-        auth_env_var?: string | undefined;
-        read_only?: boolean | undefined;
-        requires_confirmation?: boolean | undefined;
-        examples?: Record<string, unknown>[] | undefined;
-    }>>;
-}, "strip", z.ZodTypeAny, {
-    metadata: {
-        name: string;
-        description: string;
-        version: string;
-        icon: string;
-        group: string;
-        labels: Record<string, string>;
-    };
-    spec: {
-        type: "http" | "mcp" | "python" | "shell" | "builtin";
-        tags: string[];
-        input_schema: Record<string, unknown>;
-        endpoint: string;
-        method: string;
-        mcp_server: string;
-        mcp_tool: string;
-        python_module: string;
-        python_callable: string;
-        shell_command: string;
-        output_schema: Record<string, unknown>;
-        auth_type: "none" | "api_key" | "bearer" | "oauth2";
-        auth_env_var: string;
-        read_only: boolean;
-        requires_confirmation: boolean;
-        examples: Record<string, unknown>[];
-    };
-    apiVersion: "github.com/ruinosus/dna/v1";
-    kind: "Tool";
-}, {
-    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/v1";
-    kind: "Tool";
-    spec?: {
-        type?: "http" | "mcp" | "python" | "shell" | "builtin" | undefined;
-        tags?: string[] | undefined;
-        input_schema?: Record<string, unknown> | undefined;
-        endpoint?: string | undefined;
-        method?: string | undefined;
-        mcp_server?: string | undefined;
-        mcp_tool?: string | undefined;
-        python_module?: string | undefined;
-        python_callable?: string | undefined;
-        shell_command?: string | undefined;
-        output_schema?: Record<string, unknown> | undefined;
-        auth_type?: "none" | "api_key" | "bearer" | "oauth2" | undefined;
-        auth_env_var?: string | undefined;
-        read_only?: boolean | undefined;
-        requires_confirmation?: boolean | undefined;
-        examples?: Record<string, unknown>[] | undefined;
-    } | undefined;
-}>;
-export type TypedTool = z.output<typeof ToolSchema>;
 export declare const SkillSpecSchema: z.ZodObject<{
     instruction: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     scripts: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -1551,6 +1368,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
@@ -329,38 +335,6 @@ export const UseCaseSchema = z.object({
     spec: UseCaseSpecSchema.default({}),
 });
 // ---------------------------------------------------------------------------
-// Tool (github.com/ruinosus/dna/v1)
-//
-// Declarative, invocable capability an agent can call. Bridges helix with
-// OpenAI/Anthropic tool-calling conventions.
-// ---------------------------------------------------------------------------
-export const ToolTypeEnum = z.enum(["http", "mcp", "python", "shell", "builtin"]);
-export const ToolAuthTypeEnum = z.enum(["none", "api_key", "bearer", "oauth2"]);
-export const ToolSpecSchema = z.object({
-    type: ToolTypeEnum.default("builtin"),
-    endpoint: z.string().optional().default(""),
-    method: z.string().optional().default("POST"),
-    mcp_server: z.string().optional().default(""),
-    mcp_tool: z.string().optional().default(""),
-    python_module: z.string().optional().default(""),
-    python_callable: z.string().optional().default(""),
-    shell_command: z.string().optional().default(""),
-    input_schema: z.record(z.unknown()).default({}),
-    output_schema: z.record(z.unknown()).default({}),
-    auth_type: ToolAuthTypeEnum.default("none"),
-    auth_env_var: z.string().optional().default(""),
-    read_only: z.boolean().default(true),
-    requires_confirmation: z.boolean().default(false),
-    tags: z.array(z.string()).default([]),
-    examples: z.array(z.record(z.unknown())).default([]),
-});
-export const ToolSchema = z.object({
-    apiVersion: z.literal("github.com/ruinosus/dna/v1"),
-    kind: z.literal("Tool"),
-    metadata: MetadataSchema,
-    spec: ToolSpecSchema.default({}),
-});
-// ---------------------------------------------------------------------------
 // Skill (agentskills.io/v1)
 // ---------------------------------------------------------------------------
 export const SkillSpecSchema = z.object({
@@ -393,6 +367,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,7 +10,7 @@
  */
 import Mustache from "mustache";
 import { stripPromptBlock } from "./_text.js";
-import { AgentNotFound } from "./errors.js";
+import { AgentNotFound, UnknownLayout } from "./errors.js";
 // ---------------------------------------------------------------------------
 // PromptBuilder
 // ---------------------------------------------------------------------------
@@ -206,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/package-scope.d.ts

@@ -0,0 +1,18 @@
+/** The conventional scopes-root sub-directory inside a package (matches the
+ * repo's own `.dna/<scope>/` layout). */
+export declare const DEFAULT_SUBPATH = ".dna";
+/** Raised when an `anchor` package / subpath can't be resolved to a real
+ * on-disk scopes-root directory. */
+export declare class PackageScopeNotFound extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve the `.dna` scopes-root embedded in package `anchor`.
+ *
+ * `anchor` is a resolvable package specifier (e.g. `"app"`); `subpath` is the
+ * scopes-root dir inside it (default `.dna`). Returns the concrete filesystem
+ * path of `<anchor-package>/<subpath>` — the `baseDir` a FilesystemSource
+ * consumes. Fails loud (`PackageScopeNotFound`) when the package cannot be
+ * resolved or the subpath does not exist in the installed package.
+ */
+export declare function anchorScopesRoot(anchor: string, subpath?: string): string;