# Crux documentation for coding agents

> Start with the smallest relevant page, then use the complete index below to find exact APIs and guides.

## Start here

- [Foundations](https://cruxjs.dev/docs/foundations): What Crux is and how its primitives fit together.
- [Getting Started](https://cruxjs.dev/docs/getting-started): Install Crux and ship a first prompt.
- [Developer Tools](https://cruxjs.dev/docs/developer-tools): Devtools, CLI and TUI, VS Code and LSP, and coding-agent access.
- [Guides](https://cruxjs.dev/docs/guides): Task-focused explanations and workflows.
- [API Reference](https://cruxjs.dev/docs/reference): Exact APIs, commands, settings, and contracts.

Fetch one documentation page as source Markdown by replacing `/docs/` with `/llms.mdx/` in its URL.

# Docs

- Foundations: Concept-first introduction to Crux: what problem it solves, how to think about it, how it works, and when to use each primitive.
  - [What is Crux?](/docs/foundations): Crux helps TypeScript teams make AI features easier to change, inspect, and test without giving up their existing SDK.
  - [Thinking in Crux](/docs/foundations/thinking-in-crux): The principles behind Crux and the way it approaches reliable AI systems.
  - [Mental Model](/docs/foundations/mental-model): How Crux turns authored definitions into assembled, observed, and testable model turns.
  - [Primitives](/docs/foundations/primitives): A tour of every primitive Crux gives you, with one-line examples and links into the deep guides.
  - [Best Practices](/docs/foundations/best-practices): Patterns and guidelines for building robust prompt systems with Crux.
  - [Packages](/docs/foundations/packages): What each Crux package does and when to install it.
  - [Comparison](/docs/foundations/comparison): How Crux compares to SDKs, prompt strings, frameworks, tracing tools, and eval tools.
- Getting Started: Per-framework walkthroughs to install Crux and ship your first prompt: Next.js, Node, Convex, Expo.
  - [Getting Started](/docs/getting-started): Pick the smallest useful way to add Crux around your existing model calls.
  - [Next.js](/docs/getting-started/nextjs): Wire Crux into a Next.js 16 App Router project, covering Server Actions, streaming Route Handlers, and the recommended file layout.
  - [Node.js](/docs/getting-started/node): Use Crux in any Node.js script, CLI tool, or backend service. No framework required.
  - [Convex](/docs/getting-started/convex): Run Crux prompts inside Convex actions and persist memory in the crux component.
  - [Expo / React Native](/docs/getting-started/expo): Use Crux from an Expo or React Native app via a Node.js or Convex backend.
- Developer Tools: Choose the Crux interface that fits your workflow: browser Devtools, CLI and TUI, VS Code and LSP, or machine-readable docs for coding agents.
  - [Developer Tools](/docs/developer-tools): Choose the Crux interface that fits how you build, inspect, and maintain an AI system.
  - [Devtools](/docs/developer-tools/devtools): Inspect Crux runs, authored definitions, Evals, and project health in the browser.
  - [CLI & TUI](/docs/developer-tools/cli): Run Crux locally, inspect projects in the terminal, and automate checks with machine-readable output.
  - [VS Code & Cursor](/docs/developer-tools/vscode): Author Markdown-aware PromptText in TypeScript and connect your editor to Crux Project Index and runtime evidence.
  - [AI coding assistants](/docs/developer-tools/ai-assistants): Give coding agents a machine-readable map of Crux and fetch individual docs pages as Markdown.
- Guides: Task-focused how-to guides for every Crux capability, grouped from the everyday building blocks up to durable runtime and operations.
  - [Guides](/docs/guides): Task-focused how-to guides for every Crux capability, from the everyday building blocks up to durable runtime and operations.

  - **Building blocks**
  - Prompts: Typed prompt contracts, PromptText, structured output, execution, and response caching.
    - [Prompts](/docs/guides/prompts): Define typed, composable prompts that run with any SDK adapter.
    - [PromptText](/docs/guides/prompts/prompt-text): Compose readable Markdown-oriented prompt text and inspect it from source to captured Run.
    - [Structured Output](/docs/guides/prompts/structured-output): Return provider-compatible, Zod-validated objects from a Prompt.
    - [Execution](/docs/guides/prompts/execution): Run the same prompt with Vercel AI SDK, OpenAI, Google GenAI, Anthropic, or agent frameworks.
    - [SDK Bridges](/docs/guides/prompts/sdk-bridges): Convert messages and supply lightweight generation functions to framework-neutral Core APIs.
    - [Semantic Response Cache](/docs/guides/prompts/semantic-cache): Skip repeated model calls when a new request is semantically equivalent to a previous prompt result.
  - Contexts: context(): reusable system text, conditional inclusion, priority, caching, token budget.
    - [Contexts](/docs/guides/contexts): Reusable fragments that contribute system text, input fields, and tools to any prompt.
    - [Context Caching](/docs/guides/contexts/caching): Cache expensive context resolvers and leverage LLM provider token caching for cost savings.
    - [Request budgets](/docs/guides/contexts/token-budget): Measure complete provider requests and authorize explicit representation ladders.
  - Context planning: Plan complete provider requests, adapt authorized representations, and inspect request evidence.
    - [Context planning](/docs/guides/context-planning): Fit complete provider requests without silently changing canonical context.
    - [Representation ladders](/docs/guides/context-planning/representations): Authorize exact alternatives, summaries, references, and omission in a fixed fidelity order.
    - [History planning](/docs/guides/context-planning/history): Choose exact, recent, or managed projections without mutating canonical messages.
    - [Input budgets](/docs/guides/context-planning/budgets): Set soft and strict limits for each complete provider request.
    - [Adaptive preparation hooks](/docs/guides/context-planning/hooks): Amend provider calls and composition children at explicit execution boundaries.
    - [Receipts and preview](/docs/guides/context-planning/receipts-preview): Compare prospective fit with redacted evidence from executed requests.
  - Tools: Declare LLM-callable tools on prompts and contexts.
    - [Tools](/docs/guides/tools): Declare tools on contexts and prompts, merged automatically by adapters.
    - [Connect an MCP server](/docs/guides/tools/mcp): Add portable Streamable HTTP or stdio tools with safe credentials, policy, approval, and evaluations.
    - [Tool middleware](/docs/guides/tools/middleware): Audit, time, validate, and gate tool execution without rewriting every tool.
    - [Tool approvals](/docs/guides/tools/approvals): Add human approval to dangerous tool calls in serverless-safe apps.
  - Media: Use media in model messages, generate images and speech, transcribe audio, stream output, apply Safety, and persist assets.
    - [Media and multimodal](/docs/guides/media): Choose the right Crux operation for media input, image generation, transcription, speech, streaming, Safety, and storage.
    - [Media inputs](/docs/guides/media/inputs): Send images, audio, video, PDFs, and files through ordinary Crux messages without giving up type safety or ownership.
    - [Image generation](/docs/guides/media/image-generation): Generate and edit images with portable Crux options, provider-native controls, Safety, routing, and explicit storage.
    - [Speech generation](/docs/guides/media/speech-generation): Turn text into usable audio with portable controls, provider-native voices, streaming, Safety, and correct format handling.
    - [Transcription](/docs/guides/media/transcription): Convert audio into honest text, timing, speaker, language, and translation facts without inventing unsupported measurements.
    - [Streaming generated media](/docs/guides/media/streaming): Stream genuine image and speech output with replay, cancellation, routing commitment, Safety, and final-result ownership.
    - [Media safety](/docs/guides/media/safety): Guard media inputs, generated previews, incomplete deltas, final assets, and transcripts without leaking payloads.
    - [Storage and delivery](/docs/guides/media/storage-and-delivery): Persist, serve, render, and observe generated media without accidental regeneration, retention, or payload exposure.

  - **Context & memory**
  - Threads: Canonical conversation history, managed turns, alternatives, and erasure.
    - [Threads](/docs/guides/threads): Persist exact canonical conversation history with stable identities, atomic turns, and durable alternatives.
    - [Managed Conversations](/docs/guides/threads/conversations): Read one exact Thread revision, plan the request, invoke the provider, and commit only the accepted turn.
    - [Branching And Alternatives](/docs/guides/threads/branching): Preserve concurrent appends, edit without mutation, navigate remembered continuations, and render branch pickers.
    - [Removal, Redaction, And Deletion](/docs/guides/threads/erasure): Choose reversible visibility state, irreversible message provenance erasure, or permanent whole-Thread deletion.
  - Memory: Block-based memory with shared RecordStore persistence.
    - [Memory](/docs/guides/memory): Compose reusable working state, episodes, facts, procedures, and custom agent memory.
    - [Working state](/docs/guides/memory/working): Typed scratchpad memory for the current task.
    - [Episodes](/docs/guides/memory/episodic): Append-only event memory with optional dense recall.
    - [Facts and procedures](/docs/guides/memory/facts-procedures): Long-term extracted knowledge and operating memory.
    - [Memory Stores](/docs/guides/memory/stores): How memory blocks use RecordStore for persistence, recall, and production storage.
  - Retrieval & Knowledge: One progressive system: index and retrieve scored evidence, then add typed views, relations, assertions, communities, and global search as the corpus demands.
    - [Retrieval & Knowledge](/docs/guides/retrieval): One progressive system from plain RAG to typed views, evidence-backed relations, communities, and global search.

    - **Fundamentals**
    - [Knowledge Bases](/docs/guides/retrieval/knowledge-bases): Index, reindex, remove, retrieve, ground, scope, and inspect a Connected Knowledge base.
    - [Querying](/docs/guides/retrieval/querying): Query knowledge bases, store-backed retrievers, and custom retrieval backends.
    - [Retrieval Recipes](/docs/guides/retrieval/recipes): Compose named, traceable retrieval work with fanout, federation, reranking, parent expansion, and compression.
    - [Grounding And Citations](/docs/guides/retrieval/grounding): Inject retrieved evidence, expose search tools, and validate that answers cite allowed sources.

    - **Indexing**
    - [Ingesting Text, Files, and URLs](/docs/guides/retrieval/ingestion): Use @use-crux/ingest to produce documents for indexing.
    - [Indexing Documents](/docs/guides/retrieval/indexing): Turn documents into chunked, embedded retrieval records.
    - [Chunkers](/docs/guides/retrieval/chunkers): Choose how documents are split before embedding: structured, plain text, parent-child, semantic, or custom.
    - [Embeddings](/docs/guides/retrieval/embeddings): Dense and sparse embeddings in Crux without mixing vector generation and search orchestration.
    - [Multimodal Search](/docs/guides/retrieval/multimodal-search): Index media and text into one embedding space, then query it with text or media.
    - [Syncing a Corpus](/docs/guides/retrieval/corpus-sync): Keep an indexed retrieval corpus up to date without rewriting every source.

    - **Connected knowledge**
    - [Connected Knowledge](/docs/guides/retrieval/connected-knowledge): Add typed views, evidence-backed relations, assertions, communities, and global search to a knowledge base.
    - [Views](/docs/guides/retrieval/views): Create typed, live, and pinned read surfaces from knowledge-base metadata.
    - [Relations](/docs/guides/retrieval/relations): Derive typed graph edges from indexed sources and expand retrieval through the published graph.
    - [Assertions](/docs/guides/retrieval/assertions): Publish typed evidence-backed propositions and resolve conflicts without mutating source records.
    - [Communities](/docs/guides/retrieval/communities): Build and read report hierarchies over a knowledge base or view.
    - [Global Search](/docs/guides/retrieval/global-search): Search Connected Knowledge community reports and return cited finding hits.
    - [Planning](/docs/guides/retrieval/planning): Use Connected Knowledge with request planning, representation ladders, tools, artifacts, and receipts.

  - **Agents & workflows**
  - Agents: agent(), blackboards, handoffs, and delegates: building blocks for multi-agent systems.
    - [Overview](/docs/guides/agents): Composition patterns and coordination primitives for multi-agent AI applications.
    - [Agent](/docs/guides/agents/agent): Bundle a prompt with optional model and tools into a reusable agent primitive for composition utilities.
    - [Background Agent Work](/docs/guides/agents/background-agent-work): Let a coordinator model start, inspect, and rejoin process-local child Agent Work.
    - [Conversation Threads](/docs/guides/agents/threads): Bind an agent to durable conversation history, then use the full Threads guides for lifecycle and branch behavior.
    - [Handoff](/docs/guides/agents/handoff): Structured context transfer between agents with validation, compression, and optional persistence.
    - [Blackboard](/docs/guides/agents/blackboard): Shared typed scratchpad for multi-agent coordination.
    - [Delegate](/docs/guides/agents/delegate): Call a subagent as a tool from an orchestrator, with the result validated and transformed through a handoff.
  - Skills: Markdown-based instruction sets agents can load on demand. Compatible with skills.sh.
    - [Skills](/docs/guides/skills): Markdown instruction sets that agents load on demand. The index stays in the system prompt; full content is loaded only when the LLM asks for it.
    - [Writing skills](/docs/guides/skills/writing): SKILL.md format, frontmatter fields, references directories, and tips for instructions an LLM will actually follow.
    - [Registries](/docs/guides/skills/registries): Load skills from skills.sh, from disk, or from your own private registry using the .well-known/agent-skills protocol.
    - [Agent framework integration](/docs/guides/skills/agent-frameworks): Use createAgentSkillKit() to wire skills into Convex Agent, Mastra, or any framework that controls its own tool loop.
  - Compositions: Pipeline, parallel, consensus, and swarm composition patterns.
    - [Compositions](/docs/guides/compositions): Combine multiple agents into pipelines, parallel groups, voting consensus, or peer-to-peer swarms.
    - [Pipeline](/docs/guides/compositions/pipeline): Chain agents sequentially with typed data flow between immediate steps.
    - [Parallel](/docs/guides/compositions/parallel): Run multiple agents concurrently and get typed results as a named record.
    - [Consensus](/docs/guides/compositions/consensus): Run multiple agents and determine a winner via voting with configurable quorum.
    - [Swarm](/docs/guides/compositions/swarm): Dynamic peer-to-peer agent routing where the LLM decides which agent handles the next turn.
  - Flows: Compose generate() calls into structured pipelines with named steps, retries, suspend/resume, and full observability.
    - [Flows](/docs/guides/flows): Compose generate() calls into structured pipelines with named steps, automatic retries, fallbacks, and full observability.
    - [Suspend and resume](/docs/guides/flows/suspend-and-resume): Pause flows for human approval or external events, persist state, and resume execution, possibly in a different process.
    - [Typed input and step composition](/docs/guides/flows/typed-input): Type the flow's input, share it with steps via flow.input, extract steps into reusable functions, and compose flows by nesting.
    - [Agent primitives in flows](/docs/guides/flows/agent-primitives): Compose flows with handoff, delegate, and blackboard, the building blocks that plug into steps for validation, sub-pipelines, and shared state.
  - Background Work: Run follow-up work after the response is sent, without making the user wait.
    - [Background Work](/docs/guides/background-work): Start follow-up work at the nearest Crux boundary and retain it for the life of the host invocation.
    - [Host support](/docs/guides/background-work/hosts): Configure retention once, and add a strict lifecycle wrapper only when the handler boundary needs it.
    - [Troubleshooting](/docs/guides/background-work/troubleshooting): Diagnose defer scope, retention, capability, and durable-acceptance failures.
    - [Author a host adapter](/docs/guides/background-work/host-adapters): Implement a provider-neutral retention binding and strict invocation boundary for another platform.
  - Plans & Tasks: Persistent plans and task lists with reactive UI hooks and worker primitives.
    - [Plans & Tasks](/docs/guides/plans-and-tasks): Give agents persistent intent documents and structured work ledgers.
    - [Plans](/docs/guides/plans-and-tasks/plans): Store versioned intent documents and expose them as context or focused tools.
    - [Tasks](/docs/guides/plans-and-tasks/tasks): Track structured work with dynamic or typed task ledgers.
    - [Workers](/docs/guides/plans-and-tasks/workers): Bind an agent to one task with scoped context and lifecycle tools.
    - [Orchestration](/docs/guides/plans-and-tasks/orchestration): Compose plans, task ledgers, workers, flow, and external runners without turning tasks into a queue.
    - [Reactive UI](/docs/guides/plans-and-tasks/reactive-ui): Subscribe to plans and task ledgers from React with canonical hooks.
    - [Server Usage](/docs/guides/plans-and-tasks/server): Use plan and task handles from server functions, route handlers, and durable workers.
    - [Recipes](/docs/guides/plans-and-tasks/recipes): Common Plans & Tasks patterns using the canonical beta API.
    - [Best Practices](/docs/guides/plans-and-tasks/best-practices): Keep Plans & Tasks simple, visible, and easy to compose.

  - **Reliability**
  - Effects and rollback: Make external state changes explicit, recoverable, and observable with receipts and rollback boundaries.
    - [Effects and rollback](/docs/guides/effects): Make external state changes explicit, recoverable, and observable with receipts and rollback boundaries.
    - [Recovery patterns](/docs/guides/effects/recovery-patterns): Choose a recovery form, use idempotency keys, prevent double recovery, and handle conflicts and contract versions.
    - [Rollback boundaries](/docs/guides/effects/rollback-boundaries): Group related effects, choose strict or best-effort recovery, and respond to rollback results without hiding partial work.
    - [Ambiguity and reconciliation](/docs/guides/effects/ambiguity-and-reconciliation): Classify unknown external outcomes, confirm them out of band, and reconcile both executions and recovery attempts safely.
    - [Durability and restarts](/docs/guides/effects/durability-and-restarts): Configure a Runtime store for durable Effect receipts, understand crash windows, and recover honestly after process loss.
  - Routing & Fallback: Choose, escalate, and fail over between models without scattering provider logic through your app.
    - [Routing](/docs/guides/routing): Choose, retry, split, escalate, and fail over between models with one receipt.
    - [Router](/docs/guides/routing/router): Classify input and select a model route before generation starts.
    - [Split](/docs/guides/routing/split): Deterministically divide traffic across weighted model routes.
    - [Retry](/docs/guides/routing/retry): Retry one model before another routing primitive handles failure.
    - [Fallback](/docs/guides/routing/fallback): Try backup models when an attempt fails or produces unusable output.
    - [Cascade](/docs/guides/routing/cascade): Generate with cheaper tiers first and escalate when evaluators reject the result.
    - [Routing Receipts](/docs/guides/routing/receipts): Inspect the concrete model and every routing decision for a call.
    - [Routing And Streaming](/docs/guides/routing/streaming): Understand which routing primitives can stream and when fallback can retry.
    - [Patterns](/docs/guides/routing/patterns): Compose router, split, retry, fallback, and cascade into production model policies.
  - Safety: Guardrails, constraints, validation retry, and injection-resistant prompt patterns.
    - [Safety](/docs/guides/safety): Boundary-targeted guardrails, constraints, tool policies, validation retry, and prompt-injection-resistant patterns.
    - [Guardrails](/docs/guides/safety/guardrails): Boundary-targeted policies that allow, block, warn, or rewrite content before unsafe data crosses a runtime boundary.
    - [Media classifier guardrails](/docs/guides/safety/media-classifier): Classify canonical image, audio, video, and file parts with any structured-generation provider.
    - [Constraints](/docs/guides/safety/constraints): Retryable semantic assertions for generated output.
    - [Validation Retry](/docs/guides/safety/validation-retry): Automatically retry structured output that fails Zod validation, feeding errors back to the model for self-correction.
    - [Security](/docs/guides/safety/security): Input sanitization and prompt injection defense.
  - Evals: Typed Cases, Variants, checks, Eval runs, Baselines, and production Review.
    - [Evals](/docs/guides/evals): Test production AI tasks with typed Cases, Variants, automatic evidence reuse, and explicit Baselines.
    - [Checks](/docs/guides/evals/assertions): Write typed output checks and opt into fresh timing evidence explicitly.
    - [Scorers and Gates](/docs/guides/evals/scorers-and-gates): Measure Eval output, reuse exact judge evidence, and define explicit blocking policy.
    - [Variants and Baselines](/docs/guides/evals/variants-and-baselines): Compare named candidate changes with Current and accept complete evidence explicitly.
    - [Runtime host setup](/docs/guides/evals/runtime-hosts): Connect Evals to the project's selected Crux Runtime without exposing credentials.
    - [Feedback and Review](/docs/guides/evals/feedback-and-review): Submit durable run-linked feedback and deliberately turn reviewed incidents into Cases.
    - [Errors and remedies](/docs/guides/evals/errors): Exact preflight and task-contract diagnostics for Evals.
    - [Recipes](/docs/guides/evals/recipes): Practical workflows for CI, Case files, cost planning, feedback, and Review.

  - **State & storage**
  - Workspaces: Durable agent work areas for scratch files, generated outputs, uploads, and asset-backed files.
    - [Workspaces](/docs/guides/workspaces): Give agents durable scratch space and generated output files without writing custom file tools.
    - [Files and Artifacts](/docs/guides/workspaces/files-and-artifacts): Read, write, list, copy, finalize, and publish generated workspace files.
    - [Tools and Safety](/docs/guides/workspaces/tools-and-safety): Configure workspace tool names, prefixes, approvals, and write guardrails.
    - [Sources and Mounts](/docs/guides/workspaces/sources-and-mounts): Mount retrievers, MCP resources, app documents, uploads, and provider-owned files into a workspace.
    - [Versions, Snapshots, and Transactions](/docs/guides/workspaces/versions-and-transactions): Choose file history, explicit subtree snapshots, or staged multi-file writes.
    - [Watching Changes](/docs/guides/workspaces/watching): Subscribe to workspace changes with durable cursors and update app views outside the model loop.
    - [Storage and Limits](/docs/guides/workspaces/storage-and-limits): Choose workspace records and assets, configure namespaces, TTL, quotas, and inline thresholds.
  - Storage: RecordStore, SearchStore, AssetStore, bundled adapters, and custom storage implementations.
    - [Storage](/docs/guides/storage): Choose the right Crux storage capability for records, retrieval search, and workspace files.
    - [RecordStore](/docs/guides/storage/crux-store): Store Crux JSON records for memory, cache, flows, evals, and workspace metadata.
    - [SearchStore](/docs/guides/storage/search-store): Store dense, sparse, and lexical search records for retrieval.
    - [AssetStore](/docs/guides/storage/asset-storage): Store binary and oversized workspace files with asset storage.

  - **Runtime & operations**
  - Durable Execution: The optional engine that makes flows and background work survive restarts, retries, and time.
    - [Durable Execution](/docs/guides/durable-execution): The optional engine that makes flows and background work survive restarts, retries, and time.
    - [Application Work](/docs/guides/durable-execution/work): Durably accept an exported Flow in one request and reconnect it in another.
    - Durable Sessions: Keyed Agent or Flow ownership, Signal ingress, streams, lifecycle, recovery, and production setup.
      - [Durable Sessions](/docs/guides/durable-execution/sessions): Own a long-lived Agent or Flow conversation with ordered durable turns, Signal ingress, streams, and lifecycle controls.
      - [Activation, Signals, and lifecycle](/docs/guides/durable-execution/sessions/activation-and-lifecycle): Signal ingress, safe boundaries, streams, close/kill/delete, fork, statistics, and durability for durable Sessions.
      - [Durable Session recipes](/docs/guides/durable-execution/sessions/recipes): Process-local start, Flow Sessions, Signal subscriptions, PostgreSQL and Convex durability, reconnect, recovery, testing, and Devtools.
    - Signals: Typed process-local events, durable Flow waits, and Signal providers.
      - [Signals](/docs/guides/durable-execution/signals): Start with typed process-local events, then add durable Flow waits when the deployment can support them.
      - [Publish and subscribe](/docs/guides/durable-execution/signals/publish-and-subscribe): Define a Signal, normalize payloads, publish at acceptance, and observe future occurrences in one process.
      - [Filters and idempotency](/docs/guides/durable-execution/signals/filters-and-idempotency): Build inert match or predicate views and make publication retries safe.
      - [Durable Flow waits](/docs/guides/durable-execution/signals/durable-flow-waits): Declare a static Signal source and suspend a Flow without an acceptance-to-registration race.
      - [Signal providers](/docs/guides/durable-execution/signals/providers): Accept authenticated provider webhooks, poll provider pages, or supervise managed streams, acknowledge only after durable acceptance, and fan out through ordinary Signals.
      - [Provider recipes](/docs/guides/durable-execution/signals/provider-recipes): Authentication, idempotency, retries, dead letters, replay, and operator deployment for Signal providers.
      - [Retries, Effects, storage, and Evals](/docs/guides/durable-execution/signals/retries-effects-and-evals): Know what durable Signal delivery preserves, retries, and deliberately refuses to claim.
      - [Operations and errors](/docs/guides/durable-execution/signals/operations-and-errors): Diagnose Signal failures and deploy durable waits without overstating what acceptance proves.
      - [Signal recipes](/docs/guides/durable-execution/signals/recipes): Copy current-API patterns for ingestion, local callbacks, normalization, filtering, and acceptance handling.
    - [Next and Vercel Runtime](/docs/guides/durable-execution/next-vercel): Run the Crux Runtime Engine on serverless deployments with Postgres state and QStash wake delivery.
    - [Node execution worker](/docs/guides/durable-execution/node): Run one generated Runtime program in a durable, separately supervised Node process.
    - [Convex Runtime](/docs/guides/durable-execution/convex): Declare Convex as a host-bound Runtime Engine and run durable work inside Convex functions.
    - [Testing Runtime Flows](/docs/guides/durable-execution/testing): Test Runtime Engine flows, timers, and durable tasks with createTestRuntime().
    - [Runtime Adapter Authoring](/docs/guides/durable-execution/custom-adapters): Build Runtime Engine store, wake, or full host adapters with the shared contracts and conformance tests.
  - Observability: Devtools, OpenTelemetry telemetry, plugins, and middleware.
    - [Observability](/docs/guides/observability): Devtools, OpenTelemetry, plugins, and middleware: see what your prompts are actually doing.
    - [Devtools](/docs/guides/observability/devtools): Inspect production runs, Evals, Eval runs, Baselines, Review work, and source definitions locally.
    - [Execution evidence](/docs/guides/observability/execution-evidence): Inspect automatic evidence, retain it in Crux Local, and add qualified custom claims when a native producer is not available.
    - [Catalog runtime evidence](/docs/guides/observability/catalog-runtime-evidence): Open a prompt in Catalog and see which runs actually used it, with honest empty states when identity cannot be proven.
    - [Runs and delivery health](/docs/guides/observability/runs-and-delivery): What incomplete, suspended, and degraded mean in the Runs list, and what to do about each.
    - [Adapter outcomes](/docs/guides/observability/adapter-outcomes): Handle a rate limit, timeout, or refusal the same way on every provider.
    - [Runtime setup](/docs/guides/observability/runtime-setup): Bind observability drain correctly on Node, serverless, Cloudflare Workers, and Convex.
    - [Privacy and redaction](/docs/guides/observability/privacy): What Crux telemetry keeps, redacts, or omits, including DefinitionRef.source and provider errors.
    - [Troubleshooting observability](/docs/guides/observability/troubleshooting): Why deliveryHealth is unknown, runs are incomplete or conflicted, and definitions show no runs: truthful states, not silent bugs.
    - [Debug why a model turn behaved badly](/docs/guides/observability/debug-model-turns): Use Run Detail Explain to inspect what shaped one model turn, find the source to change, and protect the behavior with Eval assertions.
    - [Cloud & Tunnel Setup](/docs/guides/observability/devtools-cloud): Connect cloud backends like Convex, Vercel, or Lambda to your local devtools server.
    - [Observability context propagation](/docs/guides/observability/observability-context): How observability context and parentSpanId flow through your agents, flows, and across serverless action boundaries.
    - [Cost tracking](/docs/guides/observability/cost-tracking): Attribute model spend to prompts, models, sessions, flows, and steps.
    - [Production Telemetry](/docs/guides/observability/telemetry): Send Crux traces to Datadog, Honeycomb, Grafana, and other observability platforms via OpenTelemetry.
    - [Plugins](/docs/guides/observability/plugins): Extend Crux with composable plugins for telemetry, logging, and custom instrumentation.
    - [Middleware & Hooks](/docs/guides/observability/middleware): Global middleware and per-prompt lifecycle hooks for logging, timing, and error handling.
  - Project Health: Devtools health, Index Lint, diagnostics, and source-aware AI system feedback.
    - [Project Health](/docs/guides/project-health): Use Devtools health and Index Lint to understand whether Crux can see, connect, and check your authored AI system.
    - [Index Lint](/docs/guides/project-health/lint): Configure, fix, and suppress Crux's authored-graph lint findings.
  - [Project setup](/docs/guides/setup): Check and safely apply setup contributed by Crux subsystems.

  - **Platforms**
  - Convex: Run Crux inside Convex actions, Agent threads, storage, memory, flows, swarms, and devtools.
    - [Convex](/docs/guides/convex): Recommended architecture for running Crux inside Convex actions, Agent threads, storage, flows, swarms, and devtools.
    - [Setup](/docs/guides/convex/setup): Install @use-crux/convex, register the component, and create shared Crux storage helpers.
    - [Function Boundaries](/docs/guides/convex/function-boundaries): Preserve Crux run/span context across Convex actions, queries, mutations, and scheduled work.
    - [Storage, Memory, Workspaces](/docs/guides/convex/storage-memory-workspaces): Use Convex Storage Beta adapters, memory blocks, blackboards, and Convex file storage from Convex functions.
    - [Agent, Tools, Skills](/docs/guides/convex/agent-tools-skills): Integrate Crux prompts, tools, blackboards, and skills with the Convex Agent component.
    - [Flows](/docs/guides/convex/flows): Build durable Convex-aware flows with start, suspend, signal, and resume support.
    - [Swarms](/docs/guides/convex/swarms): Experimental cross-action swarm routing for Convex.
    - [Observability](/docs/guides/convex/observability): Connect Convex to Crux devtools and preserve trace continuity across serverless workers.
    - [Recipes](/docs/guides/convex/recipes): Recommended Convex patterns and anti-patterns for Crux applications.

  - **More**
  - Advanced: Type system, custom adapters, headless environments, extensions, error categories, and removed APIs.
    - [Advanced](/docs/guides/advanced): Extend Crux, work at framework boundaries, and understand advanced type and runtime behavior.
    - [Type System](/docs/guides/advanced/type-system): Input merging, conditional return types, and generation settings.
    - [Building Custom Adapters](/docs/guides/advanced/building-adapters): Use Crux's shared orchestration layer to build adapters for any AI SDK with minimal boilerplate.
    - [Headless Calls](/docs/guides/advanced/headless): Use adapter codecs, prepare/step/finish handles, or transport callbacks when you want to own the provider wire call.
    - [Writing an Indexer Extension](/docs/guides/advanced/writing-indexer-extension): Build an experimental Crux Indexer extension that contributes Project Index definitions and relation specs.
    - [Error Reference](/docs/guides/advanced/errors): Every error Crux can throw, what causes it, and how to fix it.
    - [Removed APIs](/docs/guides/advanced/migrations): Removed pre-launch APIs, their replacements, and the semantic changes to account for.
  - [FAQ](/docs/guides/faq): Common questions and troubleshooting for Crux.
- API Reference: Hand-written API reference organized by package - @use-crux/core, @use-crux/react, @use-crux/indexer, adapters, storage, plugins, ingest, and the local runtime.
  - [API Reference](/docs/reference): Hand-written API reference for every Crux package, organized by package.
  - @use-crux/core: The base Crux package, prompts, contexts, memory, agents, flows, effects, plans, tasks, skills, scoring, Evals, safety, index, lint, runtime bridge, and observability.
    - [@use-crux/core](/docs/reference/crux-core): The base Crux package, package overview, config, registry API, and shared utilities.
    - [Config](/docs/reference/crux-core/config): Full crux.config.ts reference for project policy, local tooling, runtime hooks, storage, observability, plugins, and experimental options.
    - [Prompts](/docs/reference/crux-core/prompts): prompt(), createPrompts(), Prompt resolution, and request preview.
    - [Prompt Resolution](/docs/reference/crux-core/prompt-resolution): use composition, input inference, message modes, output modes, and provider adaptation.
    - [PromptText](/docs/reference/crux-core/prompt-text): md composition, interpolation, inspection, Project Index evidence, and runtime preview.
    - [Contexts](/docs/reference/crux-core/contexts): context, when, match, and createContexts.
    - [Thread](/docs/reference/crux-core/thread): Durable provider-neutral conversation history with atomic turns, branches, edits, redaction, and deletion.
    - [Tools](/docs/reference/crux-core/tools): SDK-agnostic Crux tool definitions for prompts, contexts, adapters, and runtime profiles.
    - [Tool Middleware](/docs/reference/crux-core/tool-middleware): toolMiddleware(), approvalMiddleware(), resumable tool approvals, and the per-call ToolLifecycle session.
    - [Multimodal content](/docs/reference/crux-core/multimodal): Canonical message media, source types, ordered assistant output, text projection, and related media-operation references.
    - [Media operations](/docs/reference/crux-core/media-operations): Exact portable options and result contracts for image generation, transcription, and speech generation.
    - [Media streaming](/docs/reference/crux-core/media-streaming): Exact bounded image and speech stream result, event, replay, cancellation, routing, Safety, and terminal contracts.
    - [Workspaces](/docs/reference/crux-core/workspace): API reference for durable, path-addressed agent workspaces.
    - [Workspace Snapshots](/docs/reference/crux-core/workspace-snapshots): Materialize, list, restore, and delete reusable Workspace subtree checkpoints.
    - [Retrieval](/docs/reference/crux-core/retrieval): Retrieval & RAG beta APIs for knowledge bases, retrievers, recipes, tools, grounding, and traceable evidence.
    - [Connected Knowledge](/docs/reference/crux-core/connected-knowledge): knowledgeBase(), KnowledgeBase handles, scoped handles, and KnowledgeView handles.
    - [Connected Knowledge Relations](/docs/reference/crux-core/connected-knowledge-relations): relate(), relateReferences(), relateEntities(), relation stages, emit API, and KnowledgeLocator.
    - [Connected Knowledge Assertions](/docs/reference/crux-core/connected-knowledge-assertions): assertions(), AssertionSet, resolution handles, assertion refs, and assertion relations.
    - [Connected Knowledge Communities](/docs/reference/crux-core/connected-knowledge-communities): communities(), KnowledgeCommunitiesSurface, community reports, lifecycle, and report records.
    - [Connected Knowledge Recipe Steps](/docs/reference/crux-core/connected-knowledge-recipes): expandRelations(), globalSearch(), connected hit shapes, defaults, ceilings, and request receipts.
    - [Connected Knowledge Model And Refs](/docs/reference/crux-core/connected-knowledge-model-and-refs): knowledgeModel(), KnowledgeModel, KnowledgeRef, KnowledgeRefKind, and reference codecs.
    - [Connected Knowledge Conformance](/docs/reference/crux-core/connected-knowledge-conformance): runConnectedKnowledgeConformance() for storage adapter authors.
    - [Connected Knowledge Inspection](/docs/reference/crux-core/connected-knowledge-inspection): Knowledge handle inspection and RequestKnowledgeInspection on inspectRequest().
    - [Citations](/docs/reference/crux-core/citations): Grounded citation and provenance primitives for retrieval-backed prompts.
    - [Indexing](/docs/reference/crux-core/indexing): Chunking and indexing primitives for turning documents into stored retrieval chunks.
    - [Cost](/docs/reference/crux-core/cost): Cost tracking plugin and pricing helpers.
    - [Request planning](/docs/reference/crux-core/request-planning): Input budgets, representation ladders, and adapter capacity contracts.
    - [Request evidence](/docs/reference/crux-core/request-evidence): Preview prospective fit and inspect redacted evidence from executed requests.
    - [Request history](/docs/reference/crux-core/request-history): Exact, recent, and managed history projections with summary strategy contracts.
    - [Request preparation](/docs/reference/crux-core/request-preparation): prepareStep, prepareInvocation, constrained amendments, resources, statistics, and composition receipt trees.
    - [Invocation preparation](/docs/reference/crux-core/request-invocation): Prepare composition children and inspect their causal request receipt trees.
    - [Memory](/docs/reference/crux-core/memory): Block-based memory primitives for prompts, agents, stores, and observability.
    - [Semantic Cache](/docs/reference/crux-core/cache): createSemanticCache and semantic response cache policy helpers.
    - [Agents](/docs/reference/crux-core/agent): Agent definitions, composition utilities, blackboard, handoff, and delegate for multi-agent coordination.
    - [Backgroundable Agent Work](/docs/reference/crux-core/backgroundable-agent-work): Exact process-local backgroundable(), Work reference, automatic work Tool, and safe status contracts.
    - [Durable Sessions](/docs/reference/crux-core/session): Exact session, getSession, handle, subscriptions, streams, lifecycle, inspection, stats, and Runtime read model contracts.
    - [GenerationModel](/docs/reference/crux-core/generation-model): Provider-neutral adapter-bound models for Agents, durable Agent Sessions, and Runtime programs.
    - [Flows](/docs/reference/crux-core/flow): Suspendable, resumable flows with named steps, signals, and devtools tracing.
    - Signals: Signal definitions, publication, filtering, Flow waits, providers, and errors.
      - [Signals API](/docs/reference/crux-core/signal): Exact public API for typed Signal definitions, publication, filtering, and durable Flow waits.
      - [Definitions and publication](/docs/reference/crux-core/signal/definitions-and-publication): Exact signatures for Signal definitions, schema inference, occurrences, receipts, and subscriptions.
      - [Filters and helper types](/docs/reference/crux-core/signal/filters-and-types): Exact signatures for Signal match data, predicates, filtered views, and static-source occurrence inference.
      - [Flow Signal integration](/docs/reference/crux-core/signal/flow-integration): Exact signatures for static Signal waits and existing local Flow signal delivery.
      - [Providers and transports](/docs/reference/crux-core/signal/providers-and-transports): Exact public API for Signal providers, webhook, polling, managed stream, SSE, and WebSocket transports, managed bindings, accept/normalize lifecycle, statistics, and projections.
      - [Signal errors](/docs/reference/crux-core/signal/errors): Exact public Signal error classes, stable codes, and Runtime errors around durable delivery.
    - [Effects](/docs/reference/crux-core/effect): Custom effects, receipts, recovery, rollback boundaries, reconciliation, and durable Runtime store records.
    - [defer()](/docs/reference/crux-core/defer): Register inline or durable work on the nearest Crux execution scope.
    - [Runtime Engine](/docs/reference/crux-core/runtime-engine): API reference for @use-crux/core/runtime durable execution contracts, composers, handlers, diagnostics, and conformance helpers.
    - [Runtime program and worker](/docs/reference/crux-core/runtime-worker): API reference for immutable Runtime programs and the self-hosted execution worker lifecycle.
    - [Runtime work records](/docs/reference/crux-core/runtime-work-records): Exact RuntimeWorkItem and RuntimeWorkState contracts for Runtime Engine adapter authors.
    - [Runtime Signal adapter surface](/docs/reference/crux-core/runtime-adapter): Exact @use-crux/core/runtime contracts for durable Signal storage, records, codecs, atomic composites, and conformance.
    - [Plan](/docs/reference/crux-core/plan): Reference for the canonical plan primitive.
    - [Tasks](/docs/reference/crux-core/tasks): Reference for task ledgers, task specs, lifecycle methods, workers, statuses, and errors.
    - [Skills](/docs/reference/crux-core/skill): Markdown-based skill loading for Crux agents. Compatible with skills.sh.
    - [Safety](/docs/reference/crux-core/safety): Boundary-targeted guardrails, constraints, tool policies, and the per-call Safety session.
    - [Safety for content primitives](/docs/reference/crux-core/safety-content-primitives): Exact Safety boundaries and guarantees for language, image, speech, and transcription operations.
    - [Scoring](/docs/reference/crux-core/scoring): LLM-as-a-judge scoring and pre-built quality metrics.
    - [Eval](/docs/reference/crux-core/eval): Reference for @use-crux/core/eval, Node coordination, Cases, checks, Eval runs, and Baselines.
    - [Storage Interfaces](/docs/reference/crux-core/storage): RecordStore, SearchStore, AssetStore, storage(), and in-memory Storage Beta implementations.
    - [RecordStore](/docs/reference/crux-core/store): JSON record storage methods, capabilities, TTL, filters, and bundled adapters.
    - [Index](/docs/reference/crux-core/project-index): Design-plane contract for discovered Crux definitions, relations, source locations, diagnostics, and lint findings.
    - [Index Lint](/docs/reference/crux-core/lint): API reference for @use-crux/core/lint rule metadata, findings, profiles, and suppressions.
    - Index Lints
      - [definition.missing_eval_coverage](/docs/reference/crux-core/index-lints/definition-missing-eval-coverage)
      - [agent.unobservable_handoff](/docs/reference/crux-core/index-lints/agent-unobservable-handoff)
      - [prompt.missing_input_schema](/docs/reference/crux-core/index-lints/prompt-missing-input-schema)
      - [prompt.missing_output_schema](/docs/reference/crux-core/index-lints/prompt-missing-output-schema)
      - [prompt.hidden_required_input](/docs/reference/crux-core/index-lints/prompt-hidden-required-input)
      - [prompt.conflicting_injected_input](/docs/reference/crux-core/index-lints/prompt-conflicting-injected-input)
      - [prompt.conditional_required_input](/docs/reference/crux-core/index-lints/prompt-conditional-required-input)
      - [context.missing_input_schema](/docs/reference/crux-core/index-lints/context-missing-input-schema)
      - [injection.dynamic_dependency](/docs/reference/crux-core/index-lints/injection-dynamic-dependency)
      - [injection.dynamic_tools](/docs/reference/crux-core/index-lints/injection-dynamic-tools)
      - [prompt.indirect_tool_surface](/docs/reference/crux-core/index-lints/prompt-indirect-tool-surface)
      - [injectable.unused](/docs/reference/crux-core/index-lints/injectable-unused)
      - [context.unused](/docs/reference/crux-core/index-lints/context-unused)
      - [injection.unresolved_target](/docs/reference/crux-core/index-lints/injection-unresolved-target)
      - [injection.deep_schema_chain](/docs/reference/crux-core/index-lints/injection-deep-schema-chain)
      - [flow.untyped_args](/docs/reference/crux-core/index-lints/flow-untyped-args)
      - [tool.missing_input_schema](/docs/reference/crux-core/index-lints/tool-missing-input-schema)
      - [tool.output_not_inspectable](/docs/reference/crux-core/index-lints/tool-output-not-inspectable)
      - [flow.suspension_without_coverage](/docs/reference/crux-core/index-lints/flow-suspension-without-coverage)
      - [flow.duplicate_step_label](/docs/reference/crux-core/index-lints/flow-duplicate-step-label)
      - [flow.duplicate_suspend_name](/docs/reference/crux-core/index-lints/flow-duplicate-suspend-name)
      - [flow.undeclared_suspend_signal](/docs/reference/crux-core/index-lints/flow-undeclared-suspend-signal)
      - [workspace.write_without_guardrail](/docs/reference/crux-core/index-lints/workspace-write-without-guardrail)
      - [safety.duplicate_policy_id](/docs/reference/crux-core/index-lints/safety-duplicate-policy-id)
      - [thread.conflicting_binding](/docs/reference/crux-core/index-lints/thread-conflicting-binding)
      - [thread.duplicate_active](/docs/reference/crux-core/index-lints/thread-duplicate-active)
      - [memory.long_lived_without_retention](/docs/reference/crux-core/index-lints/memory-long-lived-without-retention)
      - [resource.write_without_read](/docs/reference/crux-core/index-lints/resource-write-without-read)
      - [consensus.missing_judge](/docs/reference/crux-core/index-lints/consensus-missing-judge)
      - [shared_blackboard_without_policy](/docs/reference/crux-core/index-lints/shared-blackboard-without-policy)
      - [routing.missing_stable_id](/docs/reference/crux-core/index-lints/routing-missing-stable-id)
      - [routing.router_missing_default](/docs/reference/crux-core/index-lints/routing-router-missing-default)
      - [routing.unresolved_target](/docs/reference/crux-core/index-lints/routing-unresolved-target)
      - [routing.cascade_unreachable_tier](/docs/reference/crux-core/index-lints/routing-cascade-unreachable-tier)
      - [rag.recipe_step_unresolved_target](/docs/reference/crux-core/index-lints/rag-recipe-step-unresolved-target)
      - [embedding.unsupported-modality](/docs/reference/crux-core/index-lints/embedding-unsupported-modality)
      - [embedding.namespace-identity-mismatch](/docs/reference/crux-core/index-lints/embedding-namespace-identity-mismatch)
      - [embedding.sparse-media](/docs/reference/crux-core/index-lints/embedding-sparse-media)
      - [runtime.duplicate_target_name](/docs/reference/crux-core/index-lints/runtime-duplicate-target-name)
      - [runtime.non_literal_target_name](/docs/reference/crux-core/index-lints/runtime-non-literal-target-name)
      - [runtime.target_not_exported](/docs/reference/crux-core/index-lints/runtime-target-not-exported)
      - [runtime.closure_defer](/docs/reference/crux-core/index-lints/runtime-closure-defer)
      - [runtime.missing_runtime_config](/docs/reference/crux-core/index-lints/runtime-missing-runtime-config)
      - [defer.replay_unsafe](/docs/reference/crux-core/index-lints/defer-replay-unsafe)
      - [defer.floating_named_promise](/docs/reference/crux-core/index-lints/defer-floating-named-promise)
      - [flow.nondeterministic_code](/docs/reference/crux-core/index-lints/flow-nondeterministic-code)
      - [runtime.non_serializable_payload](/docs/reference/crux-core/index-lints/runtime-non-serializable-payload)
    - [Runtime Bridge](/docs/reference/crux-core/runtime-bridge): API reference for @use-crux/core/runtime-bridge schemas and command-plane helpers.
    - [Operation Result Correlation](/docs/reference/crux-core/operation-results): Exact logical-run, trace, span, and provider identity on successful Crux results.
    - [Execution evidence](/docs/reference/crux-core/evidence): Author and inspect qualified evidence relationships for Crux executions and artifacts.
    - [Observability](/docs/reference/crux-core/observability): Canonical graph record contract shared by Crux runtimes, devtools, TUI, and the Go backend.
    - [Devtools Plugin](/docs/reference/crux-core/devtools): API reference for connecting @use-crux/core observability to the local devtools runtime.
  - [@use-crux/react](/docs/reference/react): Reactive hooks and transports for plans, task lists, blackboards, and working memory.
  - [@use-crux/react/server](/docs/reference/react-server): Server-side SSE handler for streaming RecordStore changes to the browser.
  - [@use-crux/indexer](/docs/reference/indexer): Crux-owned Catalog compiler contracts and experimental extension tooling.
  - [@use-crux/indexer/extensions](/docs/reference/indexer-extensions): Experimental Crux Indexer extension authoring surface.
  - [@use-crux/local](/docs/reference/local): Local Crux runtime for the Go devtools server, TUI, traces, Evals, Review, index, and lint.
  - [crux lsp](/docs/reference/lsp): Language Server Protocol diagnostics, completion, navigation, hover, hints, and code actions for Crux projects.
  - [Semantic completion](/docs/reference/lsp-completion): Project Index-aware completion for first-party Crux dependency slots.
  - [MCP](/docs/reference/mcp): API reference for portable Model Context Protocol tool sources.
  - [@use-crux/postgres](/docs/reference/postgres): PostgreSQL JSON records, pgvector and lexical SearchStore retrieval, composed storage, and durable Runtime Engine storage.
  - Adapters: @use-crux/ai, @use-crux/anthropic, @use-crux/openai, @use-crux/google plus the custom adapter interface.
    - [Adapter Interface](/docs/reference/adapters): Provider adapter abstraction for building AI provider integrations.
    - [@use-crux/ai](/docs/reference/adapters/ai): Vercel AI SDK adapter, generate, stream, dense embedding helpers, and the SdkGateway test seam.
    - [@use-crux/anthropic](/docs/reference/adapters/anthropic): Anthropic SDK adapter, factory pattern with native options.
    - [@use-crux/openai](/docs/reference/adapters/openai): OpenAI SDK adapter, factory pattern with native generation options plus dense embedding helpers.
    - [OpenAI media operations](/docs/reference/adapters/openai-media): OpenAI media input, image generation, transcription, speech generation, native options, results, and finite streams.
    - [@use-crux/google](/docs/reference/adapters/google): Google GenAI SDK adapter, factory pattern with provider caching plus dense embedding helpers.
    - [Google media operations](/docs/reference/adapters/google-media): Google media input, Imagen and Gemini images, composed transcription, speech generation, native options, and finite streams.
  - Storage: @use-crux/convex, @use-crux/postgres, and @use-crux/upstash persistent RecordStore, SearchStore, and AssetStore implementations.
    - [@use-crux/convex](/docs/reference/storage/convex): Convex Storage Beta adapters, Convex runtime profile, Convex Agent integration, and flow helpers.
    - [@use-crux/upstash](/docs/reference/storage/upstash): Upstash SearchStore and Redis RecordStore adapters for Crux.
  - Plugins: @use-crux/otel: OpenTelemetry plugin for production observability.
    - [@use-crux/otel](/docs/reference/plugins/otel): OpenTelemetry integration, spans for every instrumented Crux event.
  - @use-crux/ingest: @use-crux/ingest, source loaders for text, files, and URLs.
    - [@use-crux/ingest](/docs/reference/ingest): Source loaders for inline text, files, and URLs, produce IngestDocument streams for corpus sync.
    - [File Loaders](/docs/reference/ingest/files): fileSource, filesSource, load IngestDocuments from individual files, globs, or directories.
    - [URL Loaders](/docs/reference/ingest/urls): urlSource, urlsSource, fetch HTTP(S) URLs and load them as IngestDocuments with HTML extraction.
- Cookbook: End-to-end working recipes: chat, extraction, multi-agent compositions, workflows with approval, RAG pipelines, production patterns.
  - [Cookbook](/docs/cookbook): End-to-end working examples: full code, real scenarios, multiple Crux primitives composed together.
  - Basics: Everyday recipes: chat with memory, structured extraction, streaming with tools.
    - [Basics](/docs/cookbook/basics): Everyday Crux recipes: chat with memory, structured extraction, streaming with tools.
    - [Chat with memory](/docs/cookbook/basics/chat-with-memory): Compose planned history, working state, episodes, and proposed facts for a practical chat agent.
    - [Structured extraction](/docs/cookbook/basics/structured-extraction): Pull a typed object out of unstructured text, with auto-retry on schema failure.
    - [Streaming with tools](/docs/cookbook/basics/streaming-with-tools): Stream a response while the model calls tools mid-stream, updating the UI as data arrives.
    - [Safe image generation](/docs/cookbook/basics/safe-image-generation): Generate, guard, persist, and deliver an image while keeping model, Safety, and storage failures separate.
    - [Transcribe and narrate](/docs/cookbook/basics/transcribe-and-narrate): Build an audio-to-text-to-audio pipeline with honest transcript detail, separate Safety boundaries, and explicit persistence.
    - [Workspace files](/docs/cookbook/basics/workspace-files): Give an agent durable scratch files, final outputs, and approval-gated writes.
    - [Federated workspace sources](/docs/cookbook/basics/workspace-source-mounts): Mount retrievers, MCP resources, project indexes, or app documents as workspace files.
    - [Editable workspace sources](/docs/cookbook/basics/workspace-editable-source-mounts): Let a custom source-backed mount write changes back to its provider.
    - [Postgres Storage](/docs/cookbook/basics/postgres-data-store): Implement durable Crux RecordStore, SearchStore, and bytea AssetStore adapters on Postgres.
    - [Node request-scoped defer](/docs/cookbook/basics/request-scoped-defer-node): Use primitive-local work directly, or add a Node HTTP boundary for response-scoped work.
    - [React tool approvals](/docs/cookbook/basics/tool-approval-react): Add human approval to a Next.js chat route without holding a server request open.
    - [CLI tool approvals](/docs/cookbook/basics/tool-approval-cli): Use the same approval middleware in a terminal app.
    - [Expo tool approvals](/docs/cookbook/basics/tool-approval-expo): Handle tool approval requests in React Native with a normal app screen.
  - Agents: Multi-agent compositions in action: pipelines, debates, peer-to-peer swarms.
    - [Agents](/docs/cookbook/agents): Multi-agent compositions in action: pipelines, debates, peer-to-peer swarms.
    - [Background research coordinator](/docs/cookbook/agents/background-research): Let a coordinator draft in parallel, then retrieve a process-local research Agent result.
    - [Research pipeline](/docs/cookbook/agents/research-pipeline): A planner → searcher → writer pipeline with typed handoffs. Each agent's output becomes the next agent's input.
    - [Multi-agent debate](/docs/cookbook/agents/multi-agent-debate): Three agents take positions, a quorum decides. Built on consensus + a shared blackboard.
    - [Swarm routing](/docs/cookbook/agents/swarm-routing): A triage agent routes to specialists. The model itself decides who handles each turn.
  - Workflows: Plan-with-approval gates, long-running flows, task worker pools.
    - [Workflows](/docs/cookbook/workflows): Orchestration recipes: plan-with-approval gates, long-running flows, task worker pools.
    - [Plan with approval](/docs/cookbook/workflows/plan-with-approval): Generate a plan, pause for human review, execute on approval. Plan + flow + signal.
    - [Long-running flow](/docs/cookbook/workflows/long-running-flow): A flow that suspends and resumes across action boundaries, hours or days. Bounded by timeout, signaled to resume.
    - [Task Worker Pool](/docs/cookbook/workflows/task-worker-pool): Run one worker handle per pending task and show progress from a task ledger.
  - RAG: Semantic RAG, Connected Knowledge compliance, episodic recall over chat history.
    - [RAG](/docs/cookbook/rag): Retrieval-augmented patterns: semantic RAG, Connected Knowledge compliance, episodic recall.
    - [Local Files RAG](/docs/cookbook/rag/local-files-rag): Index a local docs directory, compose a retrieval recipe, and answer questions with citations.
    - [Semantic RAG with Upstash](/docs/cookbook/rag/semantic-rag): Index a doc corpus into Upstash SearchStore, compose a retrieval recipe, and answer questions with citations.
    - [Compliance corpus with Connected Knowledge](/docs/cookbook/rag/connected-knowledge-compliance): Build a multi-document policy corpus with typed metadata, views, relations, assertions, and global themes.
    - [Episodic recall](/docs/cookbook/rag/episodic-recall): Recall relevant past chat events with the episodes memory block.
    - [Crawler-Style Custom Loader](/docs/cookbook/rag/crawler-loader): Crawl a small site in userland and feed the pages into Crux indexing without making crawling built-in.
  - Runtime Recipes: Runtime Engine adapter mappings and queue recipes.
    - [Runtime Recipes](/docs/cookbook/runtime): Adapter mappings for queues and durable execution systems.
    - [Execution worker recipes](/docs/cookbook/runtime/execution-worker): Develop, deploy, diagnose, recover, and safely replace the Node/PostgreSQL Runtime worker.
    - [Named defer on serverless and Convex](/docs/cookbook/runtime/named-defer-serverless): Await durable acceptance with config-only ambient mode or a strict host boundary.
    - [Generic Queue and BullMQ](/docs/cookbook/runtime/generic-queue-bullmq): Use genericQueue() to adapt a user-owned queue to Runtime Engine wake delivery.
    - [Cloudflare Runtime Mapping](/docs/cookbook/runtime/cloudflare): Recipe-only code sketch for mapping Cloudflare Queues, Durable Objects, D1, and alarms to Runtime Engine concepts.
    - [Inngest Runtime Mapping](/docs/cookbook/runtime/inngest): Recipe-only code sketch for mapping Crux runtime targets onto Inngest functions and events.
    - [Temporal Runtime Mapping](/docs/cookbook/runtime/temporal): Recipe-only code sketch for mapping Crux flows and tasks onto Temporal workflows and activities.
  - Production: Eval gates in CI and the full observability stack.
    - [Production](/docs/cookbook/production): Recipes for running Crux in production: quality gates and observability stack.
    - [Observability stack](/docs/cookbook/production/observability-stack): withDevtools for dev + withTelemetry for OTel + a custom CruxPlugin for app-specific metrics.
- Errors: Stable Crux runtime diagnostic codes and fixes.
  - [Runtime Errors](/docs/errors): Stable Runtime Engine diagnostic codes, causes, and fixes.
  - [RUNTIME_REQUIRED](/docs/errors/RUNTIME_REQUIRED): A runtime-bound API was called without a configured Runtime Engine.
  - [CAPABILITY_MISSING](/docs/errors/CAPABILITY_MISSING): The configured runtime stack cannot support a used feature.
  - [TARGET_NOT_FOUND](/docs/errors/TARGET_NOT_FOUND): A wake envelope or Effect recovery declaration named a target the runtime program cannot address.
  - [TARGET_DUPLICATE](/docs/errors/TARGET_DUPLICATE): Two runtime targets or Effect recovery targets use the same durable identity.
  - [TARGET_NOT_EXPORTED](/docs/errors/TARGET_NOT_EXPORTED): A discovered runtime target cannot be imported as a named export.
  - [REPLAY_DIVERGED](/docs/errors/REPLAY_DIVERGED): A suspended flow replay no longer matches its recorded fingerprint.
  - [ARTIFACTS_STALE](/docs/errors/ARTIFACTS_STALE): Generated runtime artifacts do not match current source.
  - [WAKE_UNVERIFIED](/docs/errors/WAKE_UNVERIFIED): HTTP wake verification failed.
  - [PUBLIC_URL_UNRESOLVED](/docs/errors/PUBLIC_URL_UNRESOLVED): Production serverless wake has no stable public URL.
  - [SETUP_REQUIRED](/docs/errors/SETUP_REQUIRED): Runtime adapter resources are missing or mismatched.
  - [PAYLOAD_NOT_JSON](/docs/errors/PAYLOAD_NOT_JSON): A durable runtime payload is not JSON-compatible.
  - [WORK_DEAD_LETTERED](/docs/errors/WORK_DEAD_LETTERED): Runtime work exhausted its retry budget.
  - [WORK_IDEMPOTENCY_CONFLICT](/docs/errors/WORK_IDEMPOTENCY_CONFLICT): A Work idempotency tuple was reused with different normalized input.
  - [WORK_TARGET_MISMATCH](/docs/errors/WORK_TARGET_MISMATCH): getWork() received a different exported Flow than the accepted Work.
  - [SESSION_IDENTITY_CONFLICT](/docs/errors/SESSION_IDENTITY_CONFLICT): A durable Agent Session key is already bound to a different Agent target.
  - [SESSION_NOT_FOUND](/docs/errors/SESSION_NOT_FOUND): No durable Agent Session exists for the key in the active Runtime namespace.
  - [SESSION_INPUT_INVALID](/docs/errors/SESSION_INPUT_INVALID): An input could not be durably accepted by a durable Agent Session.
  - [SESSION_UNSUPPORTED](/docs/errors/SESSION_UNSUPPORTED): The configured Runtime store cannot persist durable Agent Sessions.
  - [GENERATION_MODEL_BINDING_MISSING](/docs/errors/GENERATION_MODEL_BINDING_MISSING): A durable Agent Session could not select an executable generation model.
  - [GENERATION_MODEL_NOT_STATIC](/docs/errors/GENERATION_MODEL_NOT_STATIC): The selected GenerationModel is not declared by the active Runtime program.
  - [GENERATION_CAPABILITY_MISSING](/docs/errors/GENERATION_CAPABILITY_MISSING): The selected GenerationModel cannot execute the Agent contract.
  - [SESSION_TURN_RESULT_ARTIFACT_UNAVAILABLE](/docs/errors/SESSION_TURN_RESULT_ARTIFACT_UNAVAILABLE): Prepared result evidence for a recovering durable Agent Session turn is missing or mismatched.
  - [LEASE_LOST](/docs/errors/LEASE_LOST): A stale worker tried to commit after losing its lease.
  - [NAMESPACE_AMBIGUOUS](/docs/errors/NAMESPACE_AMBIGUOUS): serverless() could not resolve a safe production Runtime Engine namespace.
  - [RUNTIME_HOST_ONLY](/docs/errors/RUNTIME_HOST_ONLY): A host-bound runtime was used outside its required host boundary.
  - [EVAL_REACTIVE_DISPATCH_FORBIDDEN](/docs/errors/EVAL_REACTIVE_DISPATCH_FORBIDDEN): Eval execution attempted to dispatch a Signal to durable reactive work.
  - [DEFER_SCOPE_REQUIRED](/docs/errors/DEFER_SCOPE_REQUIRED): defer() was called without a Crux execution scope or ambient host binding.
  - [DEFER_CAPABILITY_MISSING](/docs/errors/DEFER_CAPABILITY_MISSING): The active scope or host cannot honor this defer() operation.
  - [DEFER_SCOPE_SEALED](/docs/errors/DEFER_SCOPE_SEALED): defer() registration happened after the invocation was sealed.
  - [DEFER_LIMIT_EXCEEDED](/docs/errors/DEFER_LIMIT_EXCEEDED): defer() exceeded host callback count, nesting, or related bounds.
  - [DEFER_REPLAY_UNSAFE](/docs/errors/DEFER_REPLAY_UNSAFE): Public defer() cannot run inside replayable flow execution.
  - [DEFER_TARGET_INPUT_REQUIRED](/docs/errors/DEFER_TARGET_INPUT_REQUIRED): Named defer(target, input) was called without the required JSON input.
  - [DEFER_COMMIT_FAILED](/docs/errors/DEFER_COMMIT_FAILED): Named deferred work could not be committed before the host response boundary.
  - [EFFECT_DUPLICATE_ID](/docs/errors/EFFECT_DUPLICATE_ID): Two custom effect definitions use the same id and version.
  - [EFFECT_RESOURCE_FAILED](/docs/errors/EFFECT_RESOURCE_FAILED): An effect resource projection threw before execution.
  - [EFFECT_CAPTURE_FAILED](/docs/errors/EFFECT_CAPTURE_FAILED): A captured-recovery effect could not record its pre-state.
  - [EFFECT_RECOVERY_REQUIRED](/docs/errors/EFFECT_RECOVERY_REQUIRED): An irreversible effect was blocked by a required-recovery boundary.
  - [EFFECT_SCOPE_NOT_FOUND](/docs/errors/EFFECT_SCOPE_NOT_FOUND): An effect rollback scope reference is missing, malformed, or unavailable.
  - [EFFECT_RECEIPT_NOT_FOUND](/docs/errors/EFFECT_RECEIPT_NOT_FOUND): An effect receipt reference is missing, malformed, or belongs to another definition.
  - [EFFECT_SCOPE_TERMINAL](/docs/errors/EFFECT_SCOPE_TERMINAL): New effect work was attempted after a rollback boundary became terminal.
  - [EFFECT_OUTCOME_AMBIGUOUS](/docs/errors/EFFECT_OUTCOME_AMBIGUOUS): An effect outcome is unknown or cannot be reconciled safely.
  - [EFFECT_ROLLBACK_PARTIAL](/docs/errors/EFFECT_ROLLBACK_PARTIAL): A required effect rollback did not complete.
  - [EVIDENCE_INPUT_INVALID](/docs/errors/EVIDENCE_INPUT_INVALID): Evidence input or a destination response failed strict validation.
  - [EVIDENCE_SUBJECT_REQUIRED](/docs/errors/EVIDENCE_SUBJECT_REQUIRED): Evidence authoring had no explicit or active execution subject.
  - [EVIDENCE_SUBJECT_NOT_FOUND](/docs/errors/EVIDENCE_SUBJECT_NOT_FOUND): The readable destination cannot resolve the requested evidence subject.
  - [EVIDENCE_KIND_INVALID](/docs/errors/EVIDENCE_KIND_INVALID): An evidence kind is malformed, reserved, or cannot be resolved.
  - [EVIDENCE_CONCLUSION_INVALID](/docs/errors/EVIDENCE_CONCLUSION_INVALID): The evidence conclusion does not belong to its selected role.
  - [EVIDENCE_REFERENCE_INVALID](/docs/errors/EVIDENCE_REFERENCE_INVALID): An evidence subject or source is not a canonical graph reference.
  - [EVIDENCE_SUPERSESSION_INVALID](/docs/errors/EVIDENCE_SUPERSESSION_INVALID): Evidence supersession is duplicated, cyclic, or identity-incompatible.
  - [EVIDENCE_IDEMPOTENCY_CONFLICT](/docs/errors/EVIDENCE_IDEMPOTENCY_CONFLICT): Content diverges from the first accepted evidence identity.
  - [EVIDENCE_WRITE_QUARANTINED](/docs/errors/EVIDENCE_WRITE_QUARANTINED): A closed Eval cell rejected a late evidence authoring call.
  - [EVIDENCE_QUERY_UNAVAILABLE](/docs/errors/EVIDENCE_QUERY_UNAVAILABLE): No active or configured readable evidence source can answer.
  - [EVIDENCE_CURSOR_INVALID](/docs/errors/EVIDENCE_CURSOR_INVALID): An evidence cursor is stale, malformed, or bound to another query.
  - [EVIDENCE_ACCESS_DENIED](/docs/errors/EVIDENCE_ACCESS_DENIED): The readable destination denied evidence inspection.
  - [EVIDENCE_INPUT_TOO_LARGE](/docs/errors/EVIDENCE_INPUT_TOO_LARGE): A bounded evidence inspection request exceeded its HTTP size limit.
  - [EVIDENCE_QUERY_FAILED](/docs/errors/EVIDENCE_QUERY_FAILED): Crux Local could not complete a canonical evidence read.
  - [EVIDENCE_STAGING_CAPACITY](/docs/errors/EVIDENCE_STAGING_CAPACITY): Durable Local evidence staging is temporarily at capacity.
  - [EVIDENCE_STAGING_CANDIDATE_TOO_LARGE](/docs/errors/EVIDENCE_STAGING_CANDIDATE_TOO_LARGE): One canonical evidence candidate exceeds the fixed Local size bound.
  - [EVIDENCE_PRIVACY_DELETED](/docs/errors/EVIDENCE_PRIVACY_DELETED): Evidence delivery references explicitly deleted private state.

# Crux Blog

- [Crux 0.7](https://cruxjs.dev/blog/crux-0-7): stream() becomes one Crux-owned logical stream, Safety moves onto the boundary so nothing can publish unchecked output, structured output is always validated, and md brings Markdown-aware prompt authoring to your editor.
- [Crux 0.6](https://cruxjs.dev/blog/crux-0-6): Evals V1 replaces the pre-release Quality model, MCP servers become portable tool sources, media gets real Safety boundaries, and memory capture modes finally do what they say.
- [Where a harness layer fits: AI SDK, LangChain, Mastra, and Crux](https://cruxjs.dev/blog/where-a-harness-layer-fits): The TypeScript AI stack is usually framed as a framework choice. A harness layer is a different axis: it composes over the SDK you already picked. An honest map of what each tool owns, and when you'd add (or skip) Crux.
- [Guardrails that compose: practical LLM safety boundaries in TypeScript](https://cruxjs.dev/blog/guardrails-that-compose): Prompt injection can't be solved with a wrapper function and a regex. Model safety as typed boundaries (input, output, tool calls, memory writes) with declared actions, streaming semantics, and evidence for every decision.
- [Cut your AI bill with a routing policy you can prove](https://cruxjs.dev/blog/routing-policy-you-can-prove): Vendors promise 40–85% savings from model routing. The claims are plausible, and unverifiable without two things most routing setups lack: a declared policy and a receipt per request.
- [The RAG freshness problem is a harness problem](https://cruxjs.dev/blog/rag-freshness-is-a-harness-problem): Vector similarity has no concept of time: a stale chunk at 0.92 outranks the current one at 0.87, every time. Why freshness can't be fixed inside the index, and what it looks like as a first-class, testable property of the turn.
- [Shipping a model migration without breaking production](https://cruxjs.dev/blog/model-migration-without-regressions): Every model deprecation email starts the same fire drill. A migration playbook built on baselines, side-by-side variants, provider adaptations, and canary splits, so 'upgrade the model' becomes a reviewable change.
- [Silent truncation: the context your model never saw](https://cruxjs.dev/blog/silent-truncation): When a prompt outgrows its budget, something gets cut, and most stacks cut silently. What actually gets dropped, why 'lost instructions' bugs are so hard to diagnose, and how to make dropping a declared policy.
- [Test the harness, not just the output](https://cruxjs.dev/blog/test-the-harness-not-just-the-output): Output evals tell you that something regressed. They can't tell you what. Assert what your harness did (context decisions, routing, freshness) and CI starts failing with causes instead of symptoms.
- [Context engineering is missing correctness](https://cruxjs.dev/blog/context-engineering-missing-correctness): The discipline taught us to curate what the model sees. It never gave us a way to verify the curation. That second half is where production reliability actually lives.
- [Adding memory to the Vercel AI SDK](https://cruxjs.dev/blog/vercel-ai-sdk-memory): The AI SDK deliberately leaves memory open. How to add typed, budgeted, observable memory to an AI SDK app: recent messages, working state, and long-term facts, without switching frameworks.
- [What did the model actually see? Anatomy of a bad AI answer](https://cruxjs.dev/blog/what-did-the-model-see): A debugging walkthrough of one bad model turn: from wrong answer, to the context that never made it into the prompt, to a regression test that keeps it fixed.
- [It was never the prompt. It was the harness.](https://cruxjs.dev/blog/it-was-never-the-prompt): Most production AI failures are not model failures. They are failures in the layer around the model call, and that layer is engineerable.