README.md

Design Documents

Current design notes for OpenProgram, grouped by subsystem to mirror the code layout under openprogram/. Read this index first, then the doc you need.

Each subdirectory collects the designs for one area. Within a group, the doc that defines the current implementation is listed first; the rest are supporting notes / investigations that should not override it.

context/ — context engine, commits, tool aging

Doc	Topic
context/overview.md	Context layer: pipeline + DAG storage + ContextCommit + compaction/render + attach/merge + cross-turn tool + gaps
context/composition.md	Target state: per-call layering (L0/L1/L2) + situational context
context/comparison.md	Context approaches compared against reference projects
context/context-compaction.html	Context compaction (rendered)

memory/ — memory system (entity + abstract)

Doc	Topic
memory/README.md	Memory system overview: architecture, design principles, implementation status
memory/overview.md	Memory subsystem: entity/virtual two-tier + provenance-navigated recall, and the chain running today (visualization)
memory/entity-memory.md	Entity memory: Session-Git + Project-Git, organized by lifecycle
memory/git-as-entity-memory.md	Entity memory on Git: Session-Git + Project-Git
memory/virtual-memory.md	Abstract memory: Timeline + Graph + Core, organized by type × lifecycle

proactive/ — event layer + proactivity (event-driven)

Two parts: the event base (one unified event stream for the whole framework) and proactivity applications (rules subscribe to the stream and act). They are decoupled, so the base is usable alone. Read event-layer first for the overall picture.

Event base:

Doc	Topic
proactive/event-layer.md	Unified Event model, framework placement, diagram, event boundaries (landed: class A/B events all emitted, gate can block, visualization)
proactive/framework-evolution.md	Framework evolution: current → target → five migration steps (steps 1·2·3 done, visualization)

Proactivity applications (built on the base):

Doc	Topic
proactive/overview.md	One scenario end to end (blocking rm -rf), introducing rules / actions / state in place
proactive/events-and-state.md	How state folds out of events — why a rule can remember the past
proactive/execution-model.md	How to write a Policy; blocking vs observing rules
proactive/policies-mvp.md	Three sample rules to copy when writing new ones
proactive/invariants.md	Invariants the framework itself must hold (chiefly: no feedback loops)

Paper/production-grade material (offline replay validation, adversarial safety, evaluation skeleton) is archived under proactive/_research_archive/.

runtime/ — agent execution, DAG, async, revert, controllability

Doc	Topic
runtime/overview.md	Runtime API behaviour (see also ../api/runtime.md)
runtime/operations/user-input-requests.md	User input via runtime.ask/confirm
runtime/controllability-and-three-surface-sync.md	Attended/unattended toggle, mid-run intervention, graceful stop, three-surface sync
runtime/p3-three-surface-sync.md	P3 three-surface sync implementation detail
runtime/unified-session-context.md	Unified session context
runtime/agent-configuration-ui.html	Agent configuration framework: identity, model, instructions, Programs, Skills, MCP, and Sessions (core settings, capabilities, Programs picker)
runtime/execution/agent-worktree.md	Agent worktree behaviour
runtime/execution/async-job-lifecycle.md	Async task lifecycle
runtime/agent-resource-governance.html	Agent runtime quotas and task lifecycle governance: current implementation audit, reference comparison, admission, budgets, recovery, visibility, and implementation gates
runtime/operations/streaming-resume.md	Streaming + resume
runtime/operations/file-management.md	Revert layers (commit / worktree)
runtime/operations/multi-agent-revert-todo.md	Multi-agent revert TODO
runtime/dag/overview.md	authoritative Session DAG data model (one graph / 3 node roles user·llm·code / caller+predecessor edges / spawn / rendering / assembly / compaction)
runtime/dag/rendering.md	authoritative rendering spec: layout / edges / legend / default visibility, 12 scenarios
runtime/dag/branch-collaboration.md	Branch collaboration (communication / dispatch / merge) design and implementation steps
runtime/execution/dispatcher-split.md	Dispatcher split design
runtime/execution/next-step-decision.md	Next-step decision (how the model picks what runs next)
runtime/execution/agentic-self-recursion.md	Agentic self-recursion (rendered)
runtime/operations/rewind.md	Rewind
runtime/operations/branch-naming.md	Branch naming (rendered)
runtime/session/README.md	Session subsystem: data model, storage, naming, listing, lifecycle
runtime/self-update.md	Source-checkout upgrades: gated Git flow, channel semantics, verification, and manual recovery
runtime/permission-model.md	Permission system design
runtime/sandbox.md	Sandbox: the boundary on both platforms, where the switch is lost, coverage, how eight reference harnesses compare, repair order (rendered)
runtime/ssrf-protection.html	Outbound URL and SSRF design: current gaps, Hermes/OpenClaw/OWASP comparison, scoped trust policy, transport requirements, and full acceptance gates
runtime/agent-collaboration.md	Agent collaboration: cross-branch communication primitives (tool surface, eight reference implementations compared)
runtime/agent-resource-governance.html	Agent resource governance: current implementation, framework comparison, durable scheduling and enforceable budget plan
runtime/tool-toggle-management.md	Tool toggles / toolset management design
runtime/additional-working-directories.md	Multiple working directories per session

providers/ — LLM providers, credentials, model catalog, thinking/effort

Doc	Topic
providers/request-build.md	Request build pipeline
providers/models/overview.md	Model catalog, final design
providers/models/thinking-effort.md	Thinking / effort subsystem (level definitions, data flow, per-provider wire formats, UI picker)
providers/models/fast-tier.md	The Fast tier: two-tier detection, storage, wires
providers/auth/claude-code-direct-oauth.md	claude-code direct subscription auth (Meridian dropped)
providers/auth/credential-validation-unification.md	Unified credential validation
providers/auth/unified-auth-storage.md	Unified auth storage
providers/auth/unified-account-management.md	Unified account management + rotation
providers/auth/credential-file-hardening.html	File credential persistence hardening: current inventory, user-flow risks, atomic private-write contract, backup/restore boundary, and implementation gates
providers/auth/credential-status-redesign.md	Credential status
providers/auth/api-key-resolution-unification.md	API key resolution unification
providers/reliability/error-retry.md	Error + retry handling
providers/reliability/error-taxonomy-propagation.md	Error taxonomy + propagation
providers/reliability/llm-fault-tolerance.md	LLM fault tolerance (investigation)
providers/reliability/error-and-timeout-mechanism.html	Error + timeout mechanism (rendered)
providers/network-proxy.md	Outbound network proxy
providers/auth/credential-connection-unification.md	Credential/connection unification
providers/PROBLEM-models-and-bailian.md	Model list and the Bailian provider

function/ — function & tool calling

Doc	Topic
function/calling-unification.md	Tool/function calling framework (current)

Authoring-facing docs (@agentic_function usage, function metadata, tool-calling loop, next-step decision, pure-python helpers) moved to the user guide at ../agentic-programming/README.md.

cli/ — CLI / TUI, slash commands, ports

Doc	Topic
cli/redesign.md	CLI / TUI redesign (schema-driven settings, config panel) — current
cli/ports.md	Web UI port (config surface, conflict handling)
cli/slash-commands.md	Slash commands
cli/slash-commands-references.md	Slash-command reference snapshot
cli/drop-run-command.md	Function execution path from the Web UI
cli/naming.md	CLI naming
cli/single-port.md	Single-port architecture
cli/config-write-safety.md	Config write safety — atomic update_config
cli/tui-upgrade.md	TUI upgrade

channels/ — messaging channels

Doc	Topic
channels/design.md	Channel design (current)
channels/audit.md	Channel audit / reference snapshot

ui/ — surfaces, indicators, attachments, GUI agent

Doc	Topic
ui/invariants.md	Cross-module UI invariants
ui/chat-turn-visual-spec.html	Chat-turn visual spec (execution timeline + manual runs + message minimap)
ui/interaction-feedback.md	The 0ms interaction-feedback rule
ui/surface-system.md	Surface system
ui/theme-system.html	Theme entry, complete token contract, component consumption, and desktop-overlay propagation
ui/app-icon.html	macOS app icon source layers, Apple-managed enclosure, packaging, and legacy fallback boundary
ui/settings-collapsible-columns.html	Collapsible app, Settings, and Provider navigation columns
ui/indicator-dots.md	Indicator dots
ui/attachment-handling.md	Attachment handling (rendered)
ui/composer-interaction-modes.md	Composer interaction modes
ui/gui-agent-context.md	GUI agent context flow
ui/state-layer.md	Web state layer: per-session vs global stores, session-scope container plan
ui/center-tabs-and-split-layout.html	Authoritative single-tab and composite split-tab lifecycle, rendering, persistence, and transfer design
ui/project-workspace.md	Project workspace — files, tabs, multi-session (prototype)

integrations/ — MCP, skills/plugins, harness standard

Doc	Topic
integrations/harness-standard.md	Harness standard (plug-in + auto-detect); install: ../installing-harnesses.md
integrations/mcp-integration.md	MCP integration
integrations/skills-and-plugins.md	Skills and plugins

extension-gating/

Extension gating design + reference comparison — see extension-gating/README.md.

Cross-cutting

Doc	Topic
usage-metering.md	Usage subsystem (token/cost accounting, ledger, collection point, subprocesses, consumers)
framework-overview.md	Framework overview: one conversation from input to output
framework-comparison.html	Whole-framework comparison against twelve reference implementations by design axis: where we lead, where we lag, and what they have that we never considered (rendered)
feature-matrix.html	The same twelve implementations scanned by feature list instead of design axis: 160 user-facing features in one grid, what only they have, what only we have (rendered)
docs-site.md	The documentation site itself (build, nav, bilingual routing)
repository-structure.html	Repository boundaries, long-file split policy, and documentation information architecture
repository-structure-implementation.md	Implementation ledger for the repository structure design

research/ — investigations

Doc	Topic
research/execution-trace-model-selection.md	Choosing the data model for agent execution traces (span concept, what's novel)

distribution/ — installation, packaging, and updates

Doc	Topic
distribution/installation-packaging.html	Complete-product installation, packaging, platform support, and release artifacts
distribution/automatic-updates.html	Stable Release discovery, Desktop verified DMG handoff, managed CLI atomic activation, trust boundaries, UI states, and implementation evidence
distribution/implementation-plan.md	Historical distribution implementation evidence not duplicated by the current designs

plans/ — dated implementation plans

Doc	Topic
plans/proactive-implementation.md	Proactive layer implementation plan
plans/cache-control-passthrough.md	Per-block passthrough of Anthropic cache_control (landed)
plans/2026-07-08-credential-connection-unification.md	Credential/connection unification migration

Removed docs

There is no archive/ directory: superseded docs were deleted outright rather than moved aside. Recover them from git history if needed.

Previously removed:

• model-catalog-dynamic.md / model-catalog-per-provider.md — iteration drafts, superseded by models.md
• claude-code-meridian-profile.md — the Meridian proxy was dropped; purely historical
• *-references.md — investigation snapshots / raw research notes (slash-commands / tui-upgrade / user-input-requests)

TODO-doc-code-gaps.md

TODO-doc-code-gaps.md — Places where the docs and the code disagree, ordered by priority. Delete an entry once it is fixed.

Conventions

• One subdirectory per subsystem, mirroring openprogram/. New design docs go into the matching group, not the flat root. Add a group when a topic grows past a couple of files.
• Each group lists the current source first; supporting notes follow.
• API reference belongs under docs/api/; design rationale belongs here.
• For function-authoring rules, ../agentic-programming/writing-functions/function-metadata.md is the source of truth — shorter files link to it rather than repeating it.
• The decorator field is render_range={"callers": N, "subcalls": M} — callers caps pre-frame nodes by seq, subcalls caps in-frame nodes by seq. Both code and docs use these names exclusively.