Skip to content

Reference

Information-oriented, exhaustive descriptions of the machinery. Reference is consulted, not read start-to-finish.

Everything here is generated from source — docstrings (Python), TSDoc (TypeScript), the dna command definitions (CLI), and the registered Kinds' own schemas (Kinds). It therefore cannot drift from the code: a regeneration runs in CI on every change (scripts/gen_cli_docs.py, scripts/gen_kinds_docs.py, bun run docs:api, and mkdocstrings inline).

Pick your surface

  • Python API

    The dna package — Kernel, the five ports, Document, ManifestInstance, the extensions and the dna.testing conformance kit. Rendered inline from the docstrings by mkdocstrings.

  • TypeScript API

    The @dna/sdk package — the exact same surface with 1:1 behavioural parity, documented against its TypeScript names and types. Generated by TypeDoc from the TSDoc of src/index.ts.

  • CLI

    The dna binary — one page per command group (sdlc, research, doc, scope, kind, docs, source). Introspected from the Click command tree, so --help and the docs can never disagree.

  • Kinds

    The registered Kinds and their spec schemas, plus the KindDefinition descriptor format. Introspected from Kernel.auto().

  • Parity matrix

    The member × language grid — published proof of what each SDK implements — generated from the byte-parity fixtures CI enforces, in the spirit of the OpenTelemetry spec-compliance matrix.

Python and TypeScript are sibling trees, never fused

DNA ships two SDKs with byte-for-byte behavioural parity, but their reference is kept per-language: the same concept is documented against the exact names, types and defaults of each runtime, rather than merged into one lossy page. The parity matrix is the cross-language proof — a member × language grid generated from the byte-parity conformance fixtures.

The stable read surface

The blessed, documented read/query API (all, one, root, default_agent, build_prompt, resolve) is walked through narratively in How to read document data; the Python and TypeScript trees above are its exhaustive, machine-generated counterpart. What every source adapter must implement is in How to write a source adapter.