Docs Overview

ContextOS is the decision runtime for AI-native enterprises. It compiles per-request Context Packs that bound model behavior, runs governed decision loops, and produces typed decisions with evidence and approvals — not free-form text.

Explore the five planes

Hover or click each plane to see its primitives and the typed contracts it owns.

The five planes

┌───────────────────────────────────────────────────────────────┐
│  TRUST PLANE                                                  │
│  policy · approval-mode tiers · identity · evaluators · OTEL  │
├───────────────────────────────────────────────────────────────┤
│  ACTION PLANE                                                 │
│  Tool Gateway · MCP · A2A · OpenAPI · idempotency             │
├───────────────────────────────────────────────────────────────┤
│  DECISION PLANE                                               │
│  cognitive loop · Planner / Executor / Critic · subagent lanes│
├───────────────────────────────────────────────────────────────┤
│  CONTEXT PLANE                                                │
│  Context Pack Compiler · token budgets · runtime controls     │
├───────────────────────────────────────────────────────────────┤
│  INTELLIGENCE PLANE                                           │
│  ontology · knowledge graph · memory · embeddings · identity  │
└───────────────────────────────────────────────────────────────┘

Improvement surfaces by plane

ContextOS treats the harness as a versioned artifact that can improve from traces, scorecards, corrections, and replay. The Improvement Loop may propose changes across all five planes, but each plane owns both a tunable surface and an invariant that the optimizer cannot relax.

This is the practical reading of “autotune” in ContextOS: search may discover better harness configurations, but every candidate remains a typed proposal that passes replay, review, and staged rollout before release.

Cross-cutting primitives

Every contract carries:

• RunContext — run_id, trace_id, session_id, tenant_id, user (delegation), agent (workload identity), safety_mode, run_budget.
• ApprovalMode (5-tier) — read_only / local_write / network / delegated / destructive.
• ContextPack — versioned, signed, immutable.
• CompiledContext — compiled_prompt, manifests, runtime_controls, budget_report.
• DecisionRecord — typed outcome with evidence_refs, approvals, controls_active, trace_id.
• ToolEnvelope — ToolCallEnvelope / ToolResultEnvelope with policy_decision_id, approval mode, idempotency, evidence refs, and W3C trace context.

The canonical execution contract

invokeAgent(request_envelope, run_context)
  → compile(packs, request, run_context) → CompiledContext
  → loop {
       planner(CompiledContext)         → Plan
       critic.verify(Plan)              → ok | replan | reject
       executor(Plan, ToolGateway)      → step_results, evidence
       critic.score(step_results)       → accept | retry | replan | escalate
       consolidate(effects, evidence)   → memory_proposals
     }
  → DecisionRecord(evidence_refs, approvals, controls_active, trace_id)

Every doc references back to this contract. Schemas are authoritative; prose snippets are blueprints unless explicitly marked production.

What is authoritative vs. blueprint

New patterns are validated against working systems before they land in the spec — this repo lags implementation, not the other way around.

Reading paths

Platform engineers building the runtime → How It Works → Reference Architecture → all foundations → API Contracts → Context Pack.

Product engineers building agents on top of the runtime → How It Works → Quickstart → Intent-Task Catalog → Decision Catalog → Decision Record → Workflow Examples.

Applied AI / ML integrating models and retrieval → Cognitive Core → Agentic Context Engineering → Knowledge Graph → Identity Layer → Evaluation and Observability.

Security / governance assessing the runtime → Governance → Security and Compliance → High-Risk Workflow → Evaluation and Observability.

Executives evaluating the investment case → Invest Early in ContextOS → Reference Architecture executive summary → Use Cases.

Document status

Every doc declares a status in its frontmatter:

Quick links

• Soul, operating philosophy → The SOUL of ContextOS
• Overview, end-to-end → How It Works
• Run something → Quickstart
• Architecture → Reference Architecture
• Glossary → Glossary
• Status, source of truth → schemas linked from each implementation doc