# 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 & LSP](/docs/developer-tools/vscode): Install the Crux editor extension or connect another editor to the language server.
  - [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: prompt(), prompt composition, structured output, multi-turn, and execution patterns.
    - [Prompts](/docs/guides/prompts): Define typed, composable prompts that run with any SDK adapter.
    - [Execution](/docs/guides/prompts/execution): Run the same prompt with Vercel AI SDK, OpenAI, Google GenAI, Anthropic, or agent frameworks.
    - [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.
    - [Token Management](/docs/guides/contexts/token-budget): Token-aware rendering and automatic context dropping under budget pressure.
  - 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.

  - **Context & memory**
  - Memory: Block-based memory with shared RecordStore persistence.
    - [Memory](/docs/guides/memory): Compose reusable memory blocks for recent context, 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 & RAG: The full RAG path: embeddings, ingestion, indexing, querying, recipes, grounding, and corpus sync.
    - [Retrieval & RAG](/docs/guides/retrieval): Define knowledge bases, retrieve scored evidence, compose retrieval recipes, and validate grounded citations.
    - [Embeddings](/docs/guides/retrieval/embeddings): Dense, sparse, and hybrid retrieval 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.
    - [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.
    - [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.
    - [Syncing a Corpus](/docs/guides/retrieval/corpus-sync): Keep an indexed retrieval corpus up to date without rewriting every source.
  - Compaction: Four primitives for keeping long conversations within token limits.
    - [Compaction](/docs/guides/compaction): Four primitives for keeping long conversations within token limits. Pick the one that matches your access pattern.
    - [Sliding window](/docs/guides/compaction/sliding-window): Stateful auto-rolling compression. Keep recent messages verbatim, summarize older ones.
    - [Budget manager](/docs/guides/compaction/budget): Advisory token-pressure tracker. Decide when to compact; apply your own strategy.
    - [Summarize messages](/docs/guides/compaction/summarization): One-shot stateless summarization of a message array. Pure function, no state.
    - [Extract key facts](/docs/guides/compaction/extraction): Pull typed structured data out of a conversation with a Zod schema.

  - **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.
    - [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**
  - 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.
    - [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, VectorStore, AssetStore, bundled adapters, and custom storage implementations.
    - [Storage](/docs/guides/storage): Choose the right Crux storage capability for records, vector search, and workspace files.
    - [RecordStore](/docs/guides/storage/crux-store): Store Crux JSON records for memory, cache, flows, evals, and workspace metadata.
    - [VectorStore](/docs/guides/storage/vector-store): Store dense, sparse, and hybrid vectors for retrieval and semantic lookup.
    - [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.
    - [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.
    - [Long-lived Node Runtime](/docs/guides/durable-execution/node): Use node() for local development, tests, and durable multi-worker Node processes.
    - [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.
    - [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, multimodal content, custom adapters, headless environments, extensions, and error categories.
    - [Type System](/docs/guides/advanced/type-system): Input merging, conditional return types, and generation settings.
    - [Multimodal](/docs/guides/advanced/multimodal): Use media in ordinary messages, run specialized operations, persist explicitly, and inspect the result safely.
    - [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.
  - [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, 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, persistence, observability, plugins, and experimental options.
    - [Prompts](/docs/reference/crux-core/prompts): prompt(), createPrompts(), Prompt, and prompt resolution.
    - [Contexts](/docs/reference/crux-core/contexts): context, when, match, and createContexts.
    - [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, ordered assistant output, specialized operations, and safe projection.
    - [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.
    - [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.
    - [Memory](/docs/reference/crux-core/memory): Block-based memory primitives for prompts, agents, stores, and observability.
    - [Compaction](/docs/reference/crux-core/compaction): Sliding window, budget tracking, summarization, and key facts extraction.
    - [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.
    - [Flows](/docs/reference/crux-core/flow): Suspendable, resumable flows with named steps, signals, and devtools tracing.
    - [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.
    - [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, VectorStore, 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)
      - [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.
    - [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): Postgres Runtime Engine store adapter for durable Crux work, flow snapshots, events, waiters, timers, leases, outbox rows, and setup checks.
  - 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.
    - [@use-crux/google](/docs/reference/adapters/google): Google GenAI SDK adapter, factory pattern with provider caching plus dense embedding helpers.
  - Storage: @use-crux/convex and @use-crux/upstash, persistent RecordStore, VectorStore, and AssetStore implementations.
    - [@use-crux/convex](/docs/reference/storage/convex): Convex Storage Beta adapters, Convex runtime profile, Convex Agent integration, flow helpers, and conversation compaction.
    - [@use-crux/upstash](/docs/reference/storage/upstash): Upstash VectorStore 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 recent messages, 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.
    - [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, pgvector VectorStore, 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.
    - [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 with Upstash, episodic recall over chat history.
    - [RAG](/docs/cookbook/rag): Retrieval-augmented patterns: semantic RAG with Upstash, 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 Vector, compose a retrieval recipe, and answer questions with citations.
    - [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.
    - [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 named a target absent from the runtime entry.
  - [TARGET_DUPLICATE](/docs/errors/TARGET_DUPLICATE): Two runtime targets use the same durable name.
  - [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.
  - [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.
  - [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.

# Crux Blog

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