dna-sdk 0.4.0 → 0.6.0

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

@@ -10,6 +10,9 @@
  *   file:// <path>      → FilesystemSource (read/write on disk)
  *   fs:// <path>        → alias of file://
  *   <plain path>        → treated as file://<path>
+ *   pkg://<pkg>[/sub]   → FilesystemSource (READ-ONLY) over a scope embedded
+ *                         as PACKAGE DATA of <pkg> (sub defaults to .dna);
+ *                         travels with the app (tarball / Docker)
  *   postgresql:// …     → PostgresSource (node-postgres)
  *   postgres:// …       → alias of postgresql://
  *   sqlite:// <path>    → NOT SUPPORTED in the TS runtime (Python-only; the

package/dist/adapters/source-url.js

@@ -16,6 +16,22 @@ function schemeOf(url) {
     const m = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(url);
     return (m ? m[1] : "file").toLowerCase();
 }
+/**
+ * Split `pkg://<package>[/<subpath>]` into `{ pkg, subpath }`. Parity with the
+ * python `_parse_pkg_url`: `pkg://app` → `{pkg:"app", subpath:""}`;
+ * `pkg://app/.dna` → `{pkg:"app", subpath:".dna"}`. The package is the netloc
+ * (a dotted `pkg://my.app` stays `my.app`).
+ */
+function parsePkgUrl(url) {
+    const m = /^pkg:\/\/([^/]*)(?:\/(.*))?$/.exec(url);
+    const pkg = m?.[1] ?? "";
+    if (!pkg) {
+        throw new UnsupportedSourceScheme(`pkg:// source URL is missing a package name — use ` +
+            `pkg://<package>[/<subpath>] (e.g. pkg://app or pkg://app/.dna). ` +
+            `Got: ${url}`);
+    }
+    return { pkg, subpath: m?.[2] ?? "" };
+}
 /**
  * Build a source from a scheme URL (see module docstring).
  *
@@ -29,6 +45,16 @@ export async function sourceFromUrl(url, opts = {}) {
         const { FilesystemSource } = await import("./filesystem/source.js");
         return new FilesystemSource(urlToFsPath(url) || url);
     }
+    if (scheme === "pkg") {
+        // A scope embedded as PACKAGE DATA — resolve it from inside the installed
+        // package so it travels with the app (tarball / Docker), no path
+        // navigation and no manual copy. READ-ONLY: FilesystemSource has no write
+        // surface here (to write, use file:// or postgresql://).
+        const { FilesystemSource } = await import("./filesystem/source.js");
+        const { anchorScopesRoot, DEFAULT_SUBPATH } = await import("../package-scope.js");
+        const { pkg, subpath } = parsePkgUrl(url);
+        return new FilesystemSource(anchorScopesRoot(pkg, subpath || DEFAULT_SUBPATH));
+    }
     if (base === "postgresql" || base === "postgres") {
         const { PostgresSource } = await import("./postgres/source.js");
         const src = new PostgresSource({ connectionString: url, schema: opts.schema });
@@ -41,7 +67,8 @@ export async function sourceFromUrl(url, opts = {}) {
             `(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}`);
+        `file:// (filesystem), pkg:// (read-only package-data scope) and ` +
+        `postgresql:// adapters. Got: ${url}`);
 }
 /**
  * The `file://` URL the SDK falls back to with no explicit config.

package/dist/extensions/helix/kinds/tool.kind.yaml

@@ -0,0 +1,240 @@
+# Tool — a declarative, invocable capability an agent can call (record plane).
+#
+# "Tools as data" (f-dna-tools-as-data). The DNA already governs persona,
+# instruction and guardrails declaratively; a Tool moves the AGENT-FACING
+# surface of a tool into the same declarative plane — the ``description`` the
+# model reads to decide whether to call it (``metadata.description``) and the
+# ``parameters`` JSON Schema of its arguments (``spec.input_schema``). One
+# source of truth, versioned, testable, and overridable per tenant, served
+# identically to a Python backend (`@tool`) and a TypeScript frontend
+# (CopilotKit `useCopilotAction`) via ``dna.load_tools`` / ``loadTools``.
+#
+# F3 migration (s-tool-kind-descriptor): this WAS a hand-written ``ToolKind``
+# class (helix/__init__.py + helix.ts) with a ``TypedTool``/``ToolSpec``
+# model. It is now a ``kinds/tool.kind.yaml`` descriptor — a record Kind
+# expressed as data, per the repo's own ratchet (record Kinds are
+# descriptors, never classes). The invocation surface (type/endpoint/mcp/
+# python/shell + input/output schema + auth + read_only/requires_confirmation)
+# is preserved verbatim; only the IMPLEMENTATION moved class → descriptor and
+# the plane moved composition → record (a Tool is not a prompt target and
+# never composes into an agent prompt, so it carries no composition signal —
+# writing a Tool no longer invalidates the composition schema cache).
+#
+# Agents reference Tools by name via ``dep_filters.tools`` (unchanged — the
+# alias ``helix-tool`` is stable). Stored as ``tools/<name>.yaml`` —
+# marketplace-shareable as standalone bundles.
+#
+# tenant_scope intentionally NOT declared — permissive (base Tool + optional
+# per-tenant overlay). A tenant may legitimately override a tool's
+# description/parameters (the SaaS value hook); the base stays intact and the
+# máxima "inheritable ⇒ never tenanted" holds.
+#
+# PARITY-CRITICAL package data: byte-identical mirror under both runtimes'
+# helix/kinds/ (tests/test_descriptor_hash_parity.py enforces).
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: tool
+spec:
+  target_api_version: github.com/ruinosus/dna/v1
+  target_kind: Tool
+  alias: helix-tool
+  origin: github.com/ruinosus/dna/tool
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  storage:
+    type: yaml
+    container: tools
+  schema:
+    type: object
+    properties:
+      type:
+        type: string
+        enum:
+        - http
+        - mcp
+        - python
+        - shell
+        - builtin
+        description: How the tool is executed. builtin | http | mcp | python
+          | shell.
+      endpoint:
+        type: string
+        description: URL called when type=http. Supports {placeholder}
+          templating.
+      method:
+        type: string
+        description: HTTP method when type=http (default POST).
+      mcp_server:
+        type: string
+        description: MCP server name when type=mcp.
+      mcp_tool:
+        type: string
+        description: Tool name on the MCP server when type=mcp.
+      python_module:
+        type: string
+        description: Dotted import path when type=python.
+      python_callable:
+        type: string
+        description: Attribute on the module (function or class) when
+          type=python.
+      shell_command:
+        type: string
+        description: Command template when type=shell. Never executed without
+          confirmation.
+      input_schema:
+        type: object
+        description: JSON Schema of the arguments the agent passes when
+          invoking the tool — the "parameters" the model fills in. Surfaced
+          as ``parameters`` by ``dna.load_tools`` / ``loadTools``.
+      output_schema:
+        type: object
+        description: JSON Schema describing the shape of the tool's response.
+      auth_type:
+        type: string
+        enum:
+        - none
+        - api_key
+        - bearer
+        - oauth2
+        description: Credential strategy for the invocation.
+      auth_env_var:
+        type: string
+        description: Environment variable holding the credential (e.g.
+          GITHUB_TOKEN).
+      read_only:
+        type: boolean
+        description: False = the tool may mutate state (DB writes, file
+          changes, external side effects).
+      requires_confirmation:
+        type: boolean
+        description: Force user approval before each invocation.
+      tags:
+        type: array
+        items:
+          type: string
+        description: Free-form labels for filtering and search.
+      examples:
+        type: array
+        items:
+          type: object
+        description: Usage examples ([{input, output}]).
+  ui:
+    mode: build
+    label:
+      en: Tools
+      pt-BR: Ferramentas
+    description:
+      en: '@tool functions available to agents.'
+      pt-BR: Ferramentas (@tool) disponíveis aos agentes.
+    routes:
+      list: docs/Tool
+      detail: docs/Tool/:name
+    permissions:
+      list: any
+      detail: any
+    in_sidebar: true
+    display_order: 53
+  ui_schema:
+    type:
+      widget: select
+      label: Invocation type
+      help: 'How the tool is executed: http | mcp | python | shell | builtin.'
+      order: 10
+    endpoint:
+      widget: text
+      label: HTTP endpoint
+      help: URL called when type=http. Supports {placeholder} templating.
+      order: 20
+    method:
+      widget: select
+      label: HTTP method
+      order: 25
+    mcp_server:
+      widget: text
+      label: MCP server
+      help: Server name when type=mcp.
+      order: 30
+    mcp_tool:
+      widget: text
+      label: MCP tool name
+      order: 35
+    python_module:
+      widget: text
+      label: Python module
+      help: Dotted import path when type=python.
+      order: 40
+    python_callable:
+      widget: text
+      label: Python callable
+      help: Attribute on the module (function or class).
+      order: 45
+    shell_command:
+      widget: textarea
+      label: Shell command
+      help: Command template when type=shell. Never executed without
+        confirmation.
+      order: 50
+    input_schema:
+      widget: code
+      language: yaml
+      label: Input schema (JSON Schema)
+      help: Validates the arguments the agent passes when invoking the tool.
+      height: 260
+      order: 60
+    output_schema:
+      widget: code
+      language: yaml
+      label: Output schema (JSON Schema)
+      help: Describes the shape of the tool's response.
+      height: 220
+      order: 70
+    auth_type:
+      widget: select
+      label: Auth type
+      help: none | api_key | bearer | oauth2.
+      order: 80
+    auth_env_var:
+      widget: text
+      label: Auth env var
+      help: Environment variable holding the credential.
+      order: 85
+    read_only:
+      widget: checkbox
+      label: Read-only
+      help: Uncheck if the tool mutates state (database writes, file changes,
+        external side effects).
+      order: 90
+    requires_confirmation:
+      widget: checkbox
+      label: Requires confirmation
+      help: Force user approval before each invocation.
+      order: 95
+    tags:
+      widget: tags
+      label: Tags
+      order: 100
+    examples:
+      widget: readonly
+      label: Examples
+      help: Usage examples. Nested list — edit via YAML for now.
+      order: 110
+  graph_style:
+    fill: '#14B8A6'
+    stroke: '#0D9488'
+    text_color: '#fff'
+  ascii_icon: 🔧
+  display_label: Tools
+  docs: A Tool is a declarative, invocable capability an agent can call — an
+    HTTP endpoint, an MCP server tool, a Python callable, a shell command, or
+    a builtin. It bridges DNA with OpenAI/Anthropic tool-calling conventions.
+    The agent-facing surface is its ``metadata.description`` (the text the
+    model reads to decide to call it) and its ``spec.input_schema`` (the
+    "parameters" JSON Schema of the arguments); ``dna.load_tools`` /
+    ``loadTools`` serve exactly that surface, identically to Python and
+    TypeScript consumers from this one source. It also declares an auth
+    strategy and read_only / requires_confirmation flags the host honors at
+    runtime. Agents reference Tools via ``dep_filters.tools``. Stored as
+    ``tools/<name>.yaml`` — marketplace-shareable as standalone bundles.

package/dist/extensions/helix.js

@@ -7,12 +7,40 @@ import yaml from "js-yaml";
 import { join as pathJoin } from "node:path";
 import { nodeFS, readTextSafe, collectDir } from "../kernel/fs.js";
 import { KindBase } from "../kernel/kind_base.js";
-import { AgentSchema, ActorSchema, UseCaseSchema, ToolSchema, AgentSpecSchema, ActorSpecSchema, UseCaseSpecSchema, ToolSpecSchema, GenomeSchema, GenomeSpecSchema, LayerPolicySchema, LayerPolicySpecSchema, zodSpecToJsonSchema } from "../kernel/models.js";
+import { AgentSchema, ActorSchema, UseCaseSchema, AgentSpecSchema, ActorSpecSchema, UseCaseSpecSchema, GenomeSchema, GenomeSpecSchema, LayerPolicySchema, LayerPolicySpecSchema, zodSpecToJsonSchema } from "../kernel/models.js";
+import { loadDescriptors } from "../kernel/descriptor-loader.js";
 import { SD } from "../kernel/protocols.js";
 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 +281,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 +340,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 ?? {});
@@ -485,102 +530,6 @@ class UseCaseKind extends KindBase {
     }
 }
 // ---------------------------------------------------------------------------
-// ToolKind
-// ---------------------------------------------------------------------------
-class ToolKind extends KindBase {
-    apiVersion = "github.com/ruinosus/dna/v1";
-    kind = "Tool";
-    alias = "helix-tool";
-    isSchemaAffecting = true;
-    origin = "github.com/ruinosus/dna/tool";
-    isPromptTarget = false;
-    promptTargetPriority = 0;
-    flattenInContext = false;
-    storage = SD.yaml("tools");
-    graphStyle = { fill: "#14B8A6", stroke: "#0D9488", textColor: "#fff" };
-    asciiIcon = "🔧";
-    displayLabel = "Tools";
-    _sourceUrl = MOD_URL;
-    docs = "A Tool is a declarative, invocable capability an agent can call: an " +
-        "HTTP endpoint, an MCP server tool, a Python callable, a shell command, " +
-        "or a builtin. Bridges helix with OpenAI/Anthropic tool-calling " +
-        "conventions. Each Tool declares an input/output JSON Schema, an auth " +
-        "strategy, and read_only / requires_confirmation flags that the harness " +
-        "honors at runtime. Agents reference Tools via dep_filters.tools. " +
-        "Stored as tools/<name>.yaml — marketplace-shareable as standalone bundles.";
-    uiSchema = {
-        type: { widget: "select", label: "Invocation type", help: "How the tool is executed: http | mcp | python | shell | builtin.", order: 10 },
-        endpoint: { widget: "text", label: "HTTP endpoint", help: "URL called when type=http. Supports {placeholder} templating.", order: 20 },
-        method: { widget: "select", label: "HTTP method", order: 25 },
-        mcp_server: { widget: "text", label: "MCP server", help: "Server name when type=mcp.", order: 30 },
-        mcp_tool: { widget: "text", label: "MCP tool name", order: 35 },
-        python_module: { widget: "text", label: "Python module", help: "Dotted import path when type=python.", order: 40 },
-        python_callable: { widget: "text", label: "Python callable", help: "Attribute on the module (function or class).", order: 45 },
-        shell_command: { widget: "textarea", label: "Shell command", help: "Command template when type=shell. Never executed without confirmation.", order: 50 },
-        input_schema: {
-            widget: "code",
-            language: "yaml",
-            label: "Input schema (JSON Schema)",
-            help: "Validates the arguments the agent passes when invoking the tool.",
-            height: 260,
-            order: 60,
-        },
-        output_schema: {
-            widget: "code",
-            language: "yaml",
-            label: "Output schema (JSON Schema)",
-            help: "Describes the shape of the tool's response.",
-            height: 220,
-            order: 70,
-        },
-        auth_type: { widget: "select", label: "Auth type", help: "none | api_key | bearer | oauth2.", order: 80 },
-        auth_env_var: { widget: "text", label: "Auth env var", help: "Environment variable holding the credential.", order: 85 },
-        read_only: { widget: "checkbox", label: "Read-only", help: "Uncheck if the tool mutates state.", order: 90 },
-        requires_confirmation: { widget: "checkbox", label: "Requires confirmation", help: "Force user approval before each invocation.", order: 95 },
-        tags: { widget: "tags", label: "Tags", order: 100 },
-        examples: { widget: "readonly", label: "Examples", help: "Usage examples. Edit via YAML for now.", order: 110 },
-    };
-    schema() { return zodSpecToJsonSchema(ToolSpecSchema); }
-    parse(raw) {
-        return ToolSchema.parse(raw);
-    }
-    summary() { return null; }
-    preview(doc) {
-        const spec = (doc.spec ?? {});
-        const fields = [];
-        if (typeof spec.type === "string")
-            fields.push({ label: "type", value: spec.type });
-        if (typeof spec.endpoint === "string")
-            fields.push({ label: "endpoint", value: spec.endpoint });
-        if (typeof spec.method === "string")
-            fields.push({ label: "method", value: spec.method });
-        if (typeof spec.mcp_server === "string")
-            fields.push({ label: "mcp_server", value: spec.mcp_server });
-        if (typeof spec.mcp_tool === "string")
-            fields.push({ label: "mcp_tool", value: spec.mcp_tool });
-        if (typeof spec.python_module === "string")
-            fields.push({ label: "python_module", value: spec.python_module });
-        if (typeof spec.python_callable === "string")
-            fields.push({ label: "python_callable", value: spec.python_callable });
-        if (typeof spec.shell_command === "string")
-            fields.push({ label: "shell_command", value: spec.shell_command });
-        if (spec.input_schema)
-            fields.push({ label: "input_schema", value: JSON.stringify(spec.input_schema, null, 2) });
-        if (spec.output_schema)
-            fields.push({ label: "output_schema", value: JSON.stringify(spec.output_schema, null, 2) });
-        if (typeof spec.auth_type === "string")
-            fields.push({ label: "auth", value: spec.auth_type });
-        if (spec.read_only != null)
-            fields.push({ label: "read_only", value: String(spec.read_only) });
-        if (spec.requires_confirmation != null)
-            fields.push({ label: "requires_confirmation", value: String(spec.requires_confirmation) });
-        if (fields.length === 0) {
-            return [{ kind: "empty", title: `Tool ${doc.name}` }];
-        }
-        return [{ kind: "fields", title: `Tool ${doc.name}`, fields }];
-    }
-}
-// ---------------------------------------------------------------------------
 // AgentReader / AgentWriter
 // ---------------------------------------------------------------------------
 const KNOWN_DIRS = new Set(["scripts", "references", "assets"]);
@@ -941,9 +890,15 @@ export class HelixExtension {
         kernel.kind(new GenomeKind());
         kernel.kind(new LayerPolicyKind());
         kernel.kind(new AgentKind());
-        kernel.kind(new ToolKind());
         kernel.kind(new ActorKind());
         kernel.kind(new UseCaseKind());
+        // Tool (helix-tool) ships as a descriptor — helix/kinds/tool.kind.yaml
+        // (f-dna-tools-as-data / s-tool-kind-descriptor). It WAS a hand-written
+        // ToolKind class; migrated to a record-plane descriptor per the repo's
+        // own ratchet (record Kinds are data, not classes).
+        for (const raw of loadDescriptors(import.meta.url, "helix/kinds")) {
+            kernel.kindFromDescriptor(raw);
+        }
         // 2026-05-26 — absorbed from claude-code-templates catalog (MIT).
         // Setting rounds out the Claude-Code-customization primitives that
         // live alongside Skill / UA / Soul / Tool.

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).