# OLCP documentation

## Product

The product specification is **one specification in two files**. Neither may be
implemented from alone; their own section 0 mandates a fusion into a single
`IMPLEMENTATION_PLAN.md` before the first product code, and card 017 executes
that fusion.

- [plan.md](plan.md) - the foundational plan: identity, OAuth, privacy,
  evaluation, idempotency, Voice, the practice loop and the four core tools.
  Governs those areas on any conflict.
- [teaching-intelligence.md](teaching-intelligence.md) - the complementary
  Teaching Intelligence specification: lessons, knowledge atoms, the Curriculum
  Track Compiler, the Session Compiler, pedagogical RAG, editorial ingestion,
  CEFR classification and the Model Gateway. Governs those areas on any
  conflict.
- [context.md](context.md) - company stage and risk tolerance: what this
  project cannot afford to break.
- [identity/README.md](identity/README.md) - identity design for the remote MCP
  server: WorkOS AuthKit as authorization server, OLCP as resource server,
  provider comparison, minors and GDPR, endpoints, EU data residency.

## Operations

- [execution/s0-readiness.md](execution/s0-readiness.md) - what runs today,
  what is blocked, and the human setup checklist that unblocks the identity
  spikes. Read before starting the first code card.

## Operating contracts

- [agents/SOURCE.md](agents/SOURCE.md) - where the copied agent contracts come
  from and why they are never edited in place.
- [agents/workflows/](agents/workflows/) - review, risk tiers, decision log,
  closing commit, landing.
- [agents/HOSTS.md](agents/HOSTS.md) - capability to model, per host.

## Research

Primary-source reports, kept because the decisions they support are still live.

- [research/mcp-spec-2026-07-28-remote.md](research/mcp-spec-2026-07-28-remote.md) -
  the MCP 2026-07-28 specification as fetched: OAuth, Streamable HTTP, dual-era
  negotiation, SDKs, and what it means for ChatGPT.
- [research/openai-chatgpt-mcp-voice-research-2026-08-23.md](research/openai-chatgpt-mcp-voice-research-2026-08-23.md) -
  official MCP, Voice and OAuth documentation as of 23 August 2026. ChatGPT does
  not declare `2026-07-28`, and Voice-in-Chat does not document MCP apps.

## The proof of concept

`poc/` in the repository root is a **retained experiment**, not a migration
target. It accepts a `learner_id` and keeps state in JSON - both of which the
product forbids. It is kept because its findings are what justified the product
design, and it must not be extended.

- [poc/overview.md](poc/overview.md) - hypothesis, scope, expected result
- [poc/plan.md](poc/plan.md) - the plan the experiment actually followed
- [poc/architecture.md](poc/architecture.md) - files, MCP tools, data flow
- [poc/pedagogy.md](poc/pedagogy.md) - the deterministic selection rules
- [poc/running.md](poc/running.md) - running the tests, the demo and Inspector
- [poc/assumptions.md](poc/assumptions.md) - deliberate deviations
- [poc/cursor.md](poc/cursor.md) - connecting the server to Cursor
- [poc/catalog-a1.md](poc/catalog-a1.md) - the five A1 vocabulary items
- [poc/speaking.md](poc/speaking.md) - the pronunciation server (Streamable HTTP)
- [poc/chatgpt-voice.md](poc/chatgpt-voice.md) - the ChatGPT Voice tunnel and the
  twelve-attempt protocol
- [poc/evaluation.md](poc/evaluation.md) - the critical assessment of the result