Docs Overview

This directory is the maintainer-facing landing page for repository docs. Use it to find the right guide quickly and keep public documentation aligned when the repo changes.

Start Here

• Repository overview
• Canonical concept model
• Copy-paste examples
• Change history

Using The Packages

• Python package guide
• TypeScript package guide
• Demo data notes

Public examples use the canonical nested CLI paths: autoctx scenario create for scenario authoring and autoctx serve mcp for MCP clients.

Integrating External Agents

• External agent integration guide
• Running the loop on your own hardware
• Hermes Curator + autocontext positioning
• Python and TypeScript extension hooks
• Sandbox and executor notes
• Capability-scoped research workspaces
• Provider-neutral remote execution sessions
• Persistent host worker
• Correctness-first external kernel evolution
• MLX host training notes
• Case study: recursive loop closed on local MLX

Contributing And Support

• Contributing guide
• Agent guide
• Support
• Security policy

Architecture And Parity

• Cross-runtime CLI contract guide, machine-readable contract, wire-output schemas, and shared fixtures
• Interactive WebSocket protocol contract

The contract pins the TypeScript-only agent_progress_notes_v1 extension, including its exact Autowork-compatible fixture, safe-copy and size limits, earlier same-run evidence rules, exact durable replay, and finite retention. Python intentionally does not advertise it until equivalent durable transcript metadata is available.

• Core/control package split
• Runtime component lifecycle
• Runtime effect policy
• Runtime component graph
• Transactional runtime activation
• Runtime composition confluence harness
• Strategy package import side-effect contract
• Generic edge runtime compatibility spike
• Fetch adapter API reference
• Fetch host capability manifest examples
• Generated Fetch packaging guide
• Fetch conformance guide
• Fetch adapter troubleshooting guide
• Flue-inspired runtime decisions
• Scenario parity matrix — Python & TypeScript
• Scenario environment contract
• Role routing contract
• Typed rubric contract
• Run progress report
• Run utilization report
• Negative result ledger
• Campaign mode report
• Optional campaign scheduler
• Read-only campaign auditor
• Goal run report
• Playbook approval gate
• Immutable context bundles and outcome-gated promotion
• Campaign false-promotion calibration
• Derived lesson curation
• Soft structural hints
• Span-level credit attribution
• Ablation-backed context attribution
• Trainer-local statistical confirmation
• OPD/GKD + GRPO mixture experiment protocol
• Exploration collapse guard
• Browser exploration contract
• OpenTelemetry bridge
• Background session domain and parity contract
• Background execution trust boundaries and credential model

Execution Surfaces

• simulate — modeled-world exploration with sweeps, replay, compare, export
• investigate — evidence-driven diagnosis in synthetic harness or iterative LLM modes
• analyze — interpret and compare outputs from all surfaces
• context-selection — inspect persisted prompt context telemetry for run budget/cache tuning
• mission — real-world goal execution with adaptive planning and campaigns
• agent — TypeScript local runner/dev server and self-hosted Node build target for experimental .autoctx/agents handlers
• tui — Node 22.19+ pi-tui operator client for local runs or remote TypeScript server attachment, with durable transcript replay and cockpit reads
• train — distill curated datasets into scenario-local models
• hermes — read-only Hermes v0.12 skill/Curator inspection plus Hermes skill export

Trace Pipeline

• Public trace schema v1.0.0 for cross-harness interchange
• Privacy-aware export with sensitive-data redaction (21 patterns)
• Publishing to local JSONL, GitHub Gist, Hugging Face (ShareGPT format)
• Dataset curation with gate filtering, top-quartile selection, held-out splits
• Model selection strategy (from-scratch / LoRA / full fine-tune)
• Training backends (MLX / CUDA) with promotion lifecycle

Maintainer Docs

• Analytics and adoption guide
• Release checklist

Keep These In Sync

If a change affects commands, package names, published versions, environment variables, agent integration flows, or support expectations, review these docs in the same PR:

• README.md
• autocontext/README.md
• ts/README.md
• examples/README.md
• autocontext/docs/agent-integration.md
• CHANGELOG.md
• SUPPORT.md