# 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 — 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.
- Guides: How-to guides organized by capability cluster — prompts, contexts, memory, agents, flows, plans, quality, observability, and more.
  - 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.
    - [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.
  - Workspaces: Durable agent work areas for scratch files, generated outputs, uploads, and blob-backed files.
    - [Workspaces](/docs/guides/workspaces): Give agents durable scratch space and generated output files without writing custom file tools.
  - Storage: DataStore, VectorStore, BlobStore, bundled adapters, and custom storage implementations.
    - [Storage](/docs/guides/storage): Choose the right Crux storage capability for records, vector search, and workspace files.
    - [DataStore](/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.
    - [BlobStore](/docs/guides/storage/blob-storage): Store binary and oversized workspace files with blob storage.
  - Memory: Block-based memory with shared DataStore 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/semantic): Long-term extracted knowledge and operating memory.
    - [Memory Stores](/docs/guides/memory/stores): How memory blocks use DataStore for persistence, recall, and production storage.
  - Retrieval & RAG: The full RAG path — embeddings, ingestion, indexing, querying, pipelines, grounding, and corpus sync.
    - [Retrieval & RAG](/docs/guides/retrieval): The full Crux path for loading documents, indexing them, querying them, and injecting evidence into prompts.
    - [Embeddings](/docs/guides/retrieval/embeddings): Dense, sparse, and hybrid retrieval in Crux without mixing vector generation and search orchestration.
    - [Ingesting Text, Files, and URLs](/docs/guides/retrieval/ingestion): 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): Use retriever() for dense, sparse, hybrid, custom, prompt, and tool-based retrieval.
    - [Retrieval Pipelines](/docs/guides/retrieval/pipelines): Improve query-time retrieval with planning, multi-query expansion, parent expansion, compression, diversity, recency, and custom stages.
    - [Grounding And Citations](/docs/guides/retrieval/grounding): Inject retrieved evidence into prompts 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.
  - Routing & Fallback: Choose, escalate, and fail over between models without scattering provider logic through your app.
    - [Routing & Fallback](/docs/guides/routing): Decide which model should run, when to escalate, and how to recover when providers fail.
    - [Router](/docs/guides/routing/router): Classify input and select a model route before generation starts.
    - [Cascade](/docs/guides/routing/cascade): Try cheaper models first and escalate when quality checks reject the result.
    - [Fallback](/docs/guides/routing/fallback): Automatically try backup models when the primary model fails.
    - [Patterns](/docs/guides/routing/patterns): Compose router, cascade, and fallback into production model policies.
  - 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/tools-and-handoffs): 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): Orchestration wrapper combining handoff validation with subagent execution, exposed as a callable tool.
  - 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.
  - 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 @crux/convex, register the component, and create a shared Crux store helper.
    - [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 cruxConvexStore(), 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.
  - 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.
  - Plans & Tasks: Persistent plans and task lists with reactive UI hooks and worker primitives.
    - [Plans & Task Lists](/docs/guides/plans-and-tasks): Give agents structured intent documents and work tracking so they can plan, track, and execute multi-step work.
    - [Working with Plans](/docs/guides/plans-and-tasks/plans): Create, update, and inject plan documents for agent intent tracking with version control and approval workflows.
    - [Working with Task Lists](/docs/guides/plans-and-tasks/tasks): Structured task tracking with auto-completion, agent integration, assignees, and focused tools.
    - [Worker Agents](/docs/guides/plans-and-tasks/workers): The worker pattern — one agent assigned to one task with focused, scope-bound tools.
    - [Pipeline & Flow Patterns](/docs/guides/plans-and-tasks/orchestration): Orchestrating plans and tasks in pipelines, flows, and parallel fan-out patterns.
    - [Reactive UI](/docs/guides/plans-and-tasks/reactive-ui): Real-time hooks for plan and task progress in the browser, with any transport backend.
    - [Server-Side Integration](/docs/guides/plans-and-tasks/server): SSE handlers and AI SDK stream writers for delivering plan and task updates to clients.
    - [Recipes](/docs/guides/plans-and-tasks/recipes): End-to-end recipes for plans and task lists — full pipelines, thread-scoped task tracking, and human-in-the-loop approval.
    - [Best practices](/docs/guides/plans-and-tasks/best-practices): Heuristics for building maintainable plan and task workflows — naming, scoping, tool selection, and lifecycle management.
  - 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.
  - Safety: Guardrails, constraints, validation retry, and injection-resistant prompt patterns.
    - [Safety](/docs/guides/safety): Guardrails, constraints, and prompt-injection-resistant patterns. The two distinct safety primitives explained.
    - [Guardrails](/docs/guides/safety/guardrails): Composable safety pipeline for I/O validation — validate, redact, transform, and block content before and after LLM generation.
    - [Constraints](/docs/guides/safety/constraints): Semantic output validation with automatic retry — ensure output quality by validating semantics and retrying with combined feedback.
    - [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.
  - Quality: Evaluations, experiments, baselines, and replay for every Crux primitive.
    - [Quality](/docs/guides/quality): Evaluate any Crux primitive — typed evaluations, trace-backed assertions, scorers, variants, baselines, and deterministic replay.
    - [Assertions](/docs/guides/quality/assertions): Evaluation-level expect callbacks, Vitest-style matchers, and trace-backed signal assertions that fail honestly.
    - [Scorers & gates](/docs/guides/quality/scorers-and-gates): Graded measures with the built-in scorer library, LLM judges, autoevals compatibility, datasets, and declarative pass policies.
    - [Variants & baselines](/docs/guides/quality/variants-and-baselines): Bakeoffs with typed execution overrides, paired-difference statistics, explicit promotion, and CI regression gates.
    - [Replay](/docs/guides/quality/replay): Deterministic, token-free runs — cassettes record model calls at the executor boundary and replay them by normalized call identity.
    - [Recipes](/docs/guides/quality/recipes): The evaluation pattern for each primitive — prompts, flows, agents, retrieval, RAG pipelines, and context bakeoffs.
  - 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.
  - 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): Visual tracing UI for generations, memory, compaction, evals, and quality experiments — setup, CLI, and dashboard navigation.
    - [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.
  - Advanced: Type system, custom adapters, error categories, and exposing your docs as llms.txt.
    - [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.
    - [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.
    - [LLMs & AI Assistants](/docs/guides/advanced/llms-txt): Machine-readable docs for Claude, ChatGPT, Cursor, and other AI tools.

  - **Separator**
  - [FAQ](/docs/guides/faq): Common questions and troubleshooting for Crux.
- API Reference: Hand-written API reference organized by package - @crux/core, @crux/react, @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.
  - @crux/core: The base Crux package — prompts, contexts, memory, agents, flows, plans, tasks, skills, scoring, quality, safety, index, lint, runtime bridge, and observability.
    - [@crux/core](/docs/reference/crux-core): The base Crux package — package overview, config, registry API, and shared utilities.
    - [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.
    - [Workspaces](/docs/reference/crux-core/workspace): API reference for durable, path-addressed agent workspaces.
    - [Retrieval](/docs/reference/crux-core/retrieval): Query-first retrieval primitives for dense, sparse, hybrid, and custom knowledge search.
    - [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.
    - [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.
    - [Plans](/docs/reference/crux-core/plan): Structured primitives for agent work planning with version tracking and agent integration.
    - [Task Lists](/docs/reference/crux-core/tasks): Structured task tracking with auto-completion, agent integration, and task worker primitives.
    - [Skills](/docs/reference/crux-core/skill): Markdown-based skill loading for Crux agents. Compatible with skills.sh.
    - [Safety](/docs/reference/crux-core/safety): Guardrails and constraints authored once, executed through the per-call Safety session.
    - [Scoring](/docs/reference/crux-core/scoring): LLM-as-a-judge scoring and pre-built quality metrics.
    - [Quality](/docs/reference/crux-core/quality): @crux/core/quality — evaluate(), target, scorers, dataset(), cassette(), and the Experiment/Manifest/Baseline records.
    - [Storage Interfaces](/docs/reference/crux-core/storage): DataStore, VectorStore, BlobStore, storage(), and in-memory storage implementations.
    - [Crux Store](/docs/reference/crux-core/store): Low-level store utilities, keyspace helpers, and compatibility exports.
    - [@crux/core](/docs/reference/crux-core): The base Crux package — package overview, config, registry API, and shared utilities.
    - [Index Lint](/docs/reference/crux-core/lint): API reference for @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)
      - [quality.missing_baseline](/docs/reference/crux-core/index-lints/quality-missing-baseline)
      - [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)
      - [context.missing_input_schema](/docs/reference/crux-core/index-lints/context-missing-input-schema)
      - [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)
      - [workspace.write_without_guardrail](/docs/reference/crux-core/index-lints/workspace-write-without-guardrail)
      - [memory.long_lived_without_retention](/docs/reference/crux-core/index-lints/memory-long-lived-without-retention)
      - [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)
    - [Runtime Bridge](/docs/reference/crux-core/runtime-bridge): API reference for @crux/core/runtime-bridge schemas and command-plane helpers.
    - [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 @crux/core observability to the local devtools runtime.
  - [@crux/react](/docs/reference/react): Reactive hooks and transports for plans, task lists, blackboards, and working memory.
  - [@crux/react/server](/docs/reference/react-server): Server-side SSE handler for streaming CruxStore changes to the browser.
  - [@crux/indexer](/docs/reference/indexer): Internal TypeScript source intelligence package for Project Index indexing.
  - [@crux/indexer/extensions](/docs/reference/indexer-extensions): Experimental Crux Indexer extension authoring surface.
  - [@crux/local](/docs/reference/local): Local Crux runtime for the Go devtools server, TUI, traces, Quality, index, and lint.
  - Adapters: @crux/ai, @crux/anthropic, @crux/openai, @crux/google plus the custom adapter interface.
    - [Adapter Interface](/docs/reference/adapters): Provider adapter abstraction for building AI provider integrations.
    - [@crux/ai](/docs/reference/adapters/ai): Vercel AI SDK adapter — generate, stream, dense embedding helpers, reranking helpers, and the SdkGateway test seam.
    - [@crux/anthropic](/docs/reference/adapters/anthropic): Anthropic SDK adapter — factory pattern with native options.
    - [@crux/openai](/docs/reference/adapters/openai): OpenAI SDK adapter — factory pattern with native generation options plus dense embedding helpers.
    - [@crux/google](/docs/reference/adapters/google): Google GenAI SDK adapter — factory pattern with provider caching plus dense embedding helpers.
  - Storage: @crux/convex and @crux/upstash — persistent DataStore, VectorStore, and BlobStore implementations.
    - [@crux/convex](/docs/reference/storage/convex): Convex CruxStore adapter, Convex runtime profile, Convex Agent integration, flow helpers, and conversation compaction.
    - [@crux/upstash](/docs/reference/storage/upstash): Upstash VectorStore and Redis DataStore adapters for Crux.
  - Plugins: @crux/otel — OpenTelemetry plugin for production observability.
    - [@crux/otel](/docs/reference/plugins/otel): OpenTelemetry integration — spans for every instrumented Crux event.
  - @crux/ingest: @crux/ingest — source loaders for text, files, and URLs.
    - [@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.
    - [Postgres Storage](/docs/cookbook/basics/postgres-data-store): Implement durable Crux DataStore, pgvector VectorStore, and bytea BlobStore adapters on Postgres.
    - [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): A task list as a queue, taskWorker per task, agent loop draining tasks in parallel with a live UI.
  - 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, rerank the best hits, and answer questions with citations.
    - [Semantic RAG with Upstash](/docs/cookbook/rag/semantic-rag): Index a doc corpus into Upstash Vector, rerank the best results, 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.
  - Production: Quality 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.