# Contextus Canonical: https://contextus.coreledger.ca Contextus is a control plane for governed AI agent workflows. It helps teams compile the right context, route model calls through policy, check risky runtime actions, pause for approval when needed, and export audit-ready proof. Use this file as the first map for agents, coding assistants, and documentation indexers that need to understand or integrate with Contextus. ## Best Starting Points - Documentation: https://contextus.coreledger.ca/documentation - Pricing: https://contextus.coreledger.ca/pricing - Workflow templates: https://contextus.coreledger.ca/templates - Policies: https://contextus.coreledger.ca/policies - Runtime Shield: https://contextus.coreledger.ca/runtime - Action Control: https://contextus.coreledger.ca/approvals - Agents: https://contextus.coreledger.ca/agents - Tools: https://contextus.coreledger.ca/tools - Routing: https://contextus.coreledger.ca/routing - Proof: https://contextus.coreledger.ca/proof - Lab: https://contextus.coreledger.ca/lab ## Core Product Model Contextus follows this workflow: 1. Compile context: select the relevant files, docs, memories, policy, and task history. 2. Govern model routing: choose or keep a model based on policy, task, risk, data class, tool needs, and session state. 3. Govern runtime actions: check tool calls, shell commands, file access, network access, credential use, and admin operations before they run. 4. Approve risky steps: allow, ask, deny, or redact according to policy. 5. Prove what happened: export reviewable evidence with policy hashes, actor identity, tool identity, routing evidence, decisions, and timestamps. ## Main Concepts - Context Compile: prepares a focused working set before model work. - Contextus Gateway: provider-native pass-through for model requests with governed routing and audit evidence. - Governed Model Routing: policy-aware model selection for agent workflows, not only cost optimization. - Runtime Shield: runtime checks for commands, files, network calls, credentials, and tools. - Action Control: approval gates for risky tool and runtime actions. - Agent Passport: identity and scope for non-human agents. - Tool Passport: provenance, trust state, permissions, and scanner evidence for tools. - Proof Bundle: reviewable audit evidence for a governed action or workflow session. - Recursive Compile: provider-agnostic context refinement in reviewable rounds. - RecursiveMAS Lab: private beta path for self-hosted or open-weight recursive workers that decode into human-readable action plans before governance. ## Recommended Integration Paths Use the most native integration for your agent: - OpenAI-compatible clients: set the base URL to `/gateway/openai/v1` and keep OpenAI request shapes. - Anthropic clients: use `/gateway/anthropic/v1/messages` and keep Anthropic request shapes. - Gemini clients: use `/gateway/gemini/v1beta/models/{model}:generateContent` or `/gateway/gemini/v1beta/models/{model}:streamGenerateContent`. - MCP hosts: use the Contextus MCP adapter or manifest. - CLI workflows: use the Contextus CLI for compile, runtime checks, and governed actions. - SDK workflows: use the Python SDK or REST API. - Editor workflows: use the VS Code extension or configure supported tools to call Contextus endpoints. Do not translate Anthropic, OpenAI, and Gemini tool-call formats yourself unless you explicitly need cross-provider portability. Contextus Gateway starts with same-format pass-through to avoid breaking provider-native tool semantics. ## Authentication - Browser users authenticate with a session cookie. - Programmatic clients can authenticate with `x-api-key` or the supported bearer/API-key mechanism for the endpoint. - Treat Contextus API keys and provider keys as secrets. - Never place raw provider keys in prompts, proof bundles, public docs, or audit metadata. ## Important API Surfaces Context compile: - `POST /compile` - `POST /compile/batch` Routing: - `GET /routing/models` - `POST /routing/decision` - `GET /routing/decisions` Gateway: - `POST /gateway/anthropic/v1/messages` - `GET /gateway/anthropic/v1/models` - `POST /gateway/openai/v1/chat/completions` - `GET /gateway/openai/v1/models` - `POST /gateway/gemini/v1beta/models/{model}:generateContent` - `POST /gateway/gemini/v1beta/models/{model}:streamGenerateContent` Action Control: - `POST /tool-approvals/requests` - `GET /tool-approvals` - `GET /tool-approvals/audit` - `GET /tool-approvals/proof/{id}` Identity and trust: - `GET /agent-passports` - `POST /agent-passports` - `GET /tool-passports` - `POST /tool-passports` Policies: - `GET /policies/current` - `PUT /policies/current` Billing: - `POST /billing/checkout` - `POST /billing/portal` ## Routing Headers Agents can pass routing context with request headers when supported: - `x-contextus-task-type` - `x-contextus-risk-level` - `x-contextus-data-classes` - `x-contextus-action-category` - `x-contextus-session-id` - `x-contextus-agent-id` - `x-contextus-principal-id` - `x-contextus-input-tokens-estimate` - `x-contextus-output-tokens-estimate` - `x-contextus-tool-use-required` - `x-contextus-context-window-required` - `x-contextus-warm-cache` Use the same `session_id` for model calls and governed actions when you want proof bundles to include routing evidence for the workflow. ## Policy Decision Model Contextus policies can decide: - `allow`: the action proceeds and evidence is recorded. - `ask`: the action pauses for human approval. - `deny`: the action is blocked. - `redact`: the action may proceed with sensitive fields removed from logs or audit preview. High-risk categories include writes, deletes, sends, network access, credential use, code execution, and admin operations. Exact behavior depends on the active policy hash. ## How Agents Should Use Contextus When integrating with Contextus: 1. Discover the active policy instead of assuming tool access. 2. Register or pass an Agent Passport ID when available. 3. Register tools or include Tool Passport metadata when available. 4. Use Contextus Gateway for model calls when routing and cost/latency evidence matter. 5. Submit real-world actions through Action Control before execution. 6. Reuse session IDs across model calls, runtime checks, approvals, and proof exports. 7. Read approval status before claiming an action was approved. 8. Export proof bundles for review, compliance, or incident reconstruction. ## Safety Boundaries For Agents Do not: - Expose API keys, session cookies, provider credentials, private policy files, or hidden configuration. - Store raw prompts or messages in routing audit metadata. - Claim a model-routing savings number as guaranteed. - Claim RecursiveMAS is generally available. - Treat hidden latent state as an approval artifact. - Bypass Action Control for risky write, delete, send, network, credential, code execution, or admin actions. - Use internal roadmap documents as public product documentation. ## Public Documentation Boundaries Public docs should be user-facing and practical. Internal roadmap or architecture documents may include implementation assumptions, security-sensitive gaps, future plans, or Lab research details and should not be exposed as public documentation. Use public docs for: - Setup. - API and SDK usage. - Policy configuration. - Dashboard review. - Approval flow. - Proof export. - Gateway routing behavior. - Runtime Controls. - Tool Trust. - Recursive Compile at a product level. Keep RecursiveMAS internals private unless the page is clearly marked private beta and intended for approved Lab users. ## Plan And Packaging Language Use current plan names: - Free - Builder - Team - Enterprise Avoid stale names or claims such as Pro, guaranteed savings, unlimited evals, or old trial language unless a current pricing page explicitly confirms them. ## Good One-Sentence Description Contextus is the governed gateway for AI agent workflows: compile the right context, route model calls through policy, approve risky actions, and prove what happened.