# @nhtio/adk documentation

> TypeScript Agent Development Kit documentation for deterministic turn execution, context threading, tools, artifacts, event streaming, and opt-in batteries.

LLM-friendly entry points for this documentation site. This file is a curated orientation index, not an exhaustive sitemap.

## Primary Documents

- [Complete hand-written documentation](/llms-full.txt): Full prose documentation concatenated for large-context ingestion.
- [Machine-readable documentation manifest](/llms.json): Structured manifest of documentation pages and metadata.
- [API reference index](/api/index.md): Generated TypeDoc reference entry point.
- [Sitemap](/sitemap.xml): Exhaustive crawler sitemap for every published page.

## Hand-written Documentation

- [@nhtio/adk documentation](/index.md): TypeScript Agent Development Kit documentation for deterministic turn execution, context threading, tools, artifacts, event streaming, and opt-in batteries.
- [What ADK is, and what it isn't](/what-adk-is.md): The library's ethos — what ADK owns, what it deliberately doesn't, and the design choices that follow from that line.
- [How agents work](/how-agents-work.md): A plain-English orientation to agents, turns, tools, and the request lifecycle — for engineers who haven't built one before.
- [Quickstart](/quickstart.md): Installing @nhtio/adk and the smallest legal three-file assembly with the executor seam in full view — no API key, no remote model, mock executor inline.
- [Playground](/playground.md): An in-browser REPL for the ADK TurnRunner with scripted examples and a live lifecycle trace. Runtime explorer, not the onboarding path.
- [Minimal Assembly](/assembly/minimal-assembly.md): The smallest complete ADK assembly: wire model execution, state, tools, and turn running before adding optional batteries.
- [The Loop](/the-loop/index.md): Mental model for one ADK turn — what the ADK owns, where your code plugs in, and the order things happen in.
- [Turn Runner](/the-loop/turn-runner.md): The TurnRunner entry point: eager config validation, the TurnContext, callback boundaries, and the two event buses around one turn.
- [Inside one turn](/the-loop/turn-runner/inside-one-turn.md): The pipeline diagram, the four invariants, and the two event buses around one turn.
- [LLM Dispatch](/the-loop/llm-dispatch.md): LLMExecutionRunner, the executor seam, the iteration loop, and the ack / nack lifecycle that bounds one dispatch.
- [Tools](/the-loop/tools.md): Schema-owned tooling: Tool, ToolRegistry, merge collision policy, and the per-turn registry lifecycle.
- [Artifacts](/the-loop/artifacts.md): SpooledArtifact, the handle pattern, and the ctx-scoped forgeTools lifecycle that lets the model query large tool outputs.
- [Primitives](/the-loop/primitives.md): The validated data primitives ADK threads through every turn: Tokenizable, Identity, Message, Media, Memory, Retrievable, Thought, ToolCall.
- [Trust Tiers](/the-loop/trust-tiers.md): Envelope shapes, multi-identity rendering, RAG tiering, and reasoning fences — how ADK communicates authority to the model.
- [Gates](/the-loop/gates.md): ctx.waitFor and TurnGate — the cooperative suspension primitive that human-in-the-loop, RBAC, and external-approval flows are built on.
- [Events](/the-loop/events.md): Functional vs observability buses, payload shapes, and the rule that separates them.
- [Failure](/the-loop/failure.md): Exception codes, validation errors, gate failures, abort semantics, and what ack / nack actually mean.
- [Assembly](/assembly/index.md): Where you plug your stack into the ADK — your LLM, your storage, your tools, your retrieval, your memory.
- [Bring your own LLM](/assembly/byo-llm.md): Write an LLMExecutorFn for your provider; use the OpenAI Chat Completions battery as the reference implementation.
- [Bring your own tools](/assembly/byo-tools.md): Forging Tool and ArtifactTool instances, plus the canonical forgeTools + bindContext + ack pattern for ephemeral artifact tools.
- [Bring your own storage](/assembly/byo-storage.md): Wire fetch / store / mutate / delete callbacks for every primitive, using the storage backend your product already operates.
- [Recipes](/assembly/recipes/index.md): Task-oriented walkthroughs that show one finished pattern from start to end.
- [Glossary](/glossary.md): Glossary of @nhtio/adk terms for agents, turns, tools, artifacts, batteries, and bring-your-own infrastructure.

## API Reference

Generated API reference pages are intentionally not listed here. Use [API reference index](/api/index.md), [Machine-readable documentation manifest](/llms.json), or [Sitemap](/sitemap.xml) for exhaustive API discovery.