Use this page as the map for the repository documentation. Pick the section that matches what you are trying to do; files listed as reference are most useful when changing that subsystem rather than when getting started.
| Goal | Read this |
|---|---|
| Understand the project and run a first task | Project README |
| Run the TUI with an existing LLM endpoint | English quickstart / 中文教程 |
| Learn the TUI panes, previews, approvals, and live steering | English user guide / 中文使用教程 |
| Install on any environment | Installation and deployment |
| Run FrontierAgent from a container | Docker and Compose |
| Run or configure a local NVIDIA/SGLang model | GPU and SGLang |
| Understand ReAct versus Agent Team | Workflow implementations |
| Run benchmark evaluation | Evaluation guide |
| Extend the framework | Developer guides |
Start with the installation chooser. It routes by operating model��hosted endpoint, Docker GPU host, custom cloud image, or an existing GPU container—instead of asking you to guess from the operating system alone.
| Environment | Canonical guide |
|---|---|
| macOS or Linux, fastest hosted-endpoint TUI setup | English quickstart / 中文教程 |
| macOS, hosted or remote endpoint | macOS / 中文详细版 |
| Linux, hosted or remote endpoint | Linux |
| Windows | WSL2 section in the Linux guide |
| Any host with Docker, no local Python | Docker and Compose |
| Linux NVIDIA host with Docker | Docker SGLang |
| Existing Linux GPU environment without nested Docker | Native SGLang |
| GPU cloud or custom OCI image | GPU platforms |
Read these in order when bringing up a local model:
- GPU compatibility explains supported runtime tracks and what must be recorded when certifying hardware.
- Choose the matching deployment guide from the table above.
- SGLang configuration reference documents every
.env.sglangsetting, safe tuning order, and upstream references.
The files under config/sglang/*.env.example are runnable templates; their
comments and the SGLang reference are the source of truth for those variables.
| Topic | Document |
|---|---|
| TUI panes, keyboard workflow, previews, approvals, and Agent Team intervention | English user guide / 中文使用教程 |
| CLI, TUI, themes, slash commands, approvals, and terminal internals | apodex/README.md (reference) |
| High-level architecture and sandbox boundaries | Framework architecture |
| Security policy and vulnerability reporting | Security policy |
The root README's job is the product overview, a short quick start, and results. Detailed operational behavior belongs in the focused documents above, so new instructions go there rather than into a second copy.
| Workflow | Use it for | Configuration reference |
|---|---|---|
| Stateful ReAct | One stateful agent doing sequential research and file work | Workflow README |
| Agent Team | Coordinator plus parallel sub-agents and optional reporter | Workflow README |
Those READMEs own profile selection and workflow-specific configuration. To create a new workflow plugin, use Writing a workflow instead.
- Evaluation guide: installation, judge configuration, dataset downloads, execution, filesystem contract, results, and progress.
- FrontierSearchBench evaluation: the one benchmark with an external cross-query scorer — isolation requirement, collect / export / score workflow, and scorer options.
- Benchmark registry: supported dataset keys, default pipelines, scoring implementations, repository layout, and how to add a benchmark.
docs/eval.md is the operator guide for everything the benchmarks share;
docs/eval-frontier-search.md carries only what is specific to
FrontierSearchBench. benchmarks/README.md is the registry and extension
reference; keeping those roles separate avoids duplicating setup instructions.
| Task | Document |
|---|---|
| Understand runtime flow, observers, teams, and package boundaries | Framework architecture |
| Author and register a workflow plugin | Writing a workflow |
| Develop and submit changes | Contributing |
| Understand the frozen Textual + Rich decision | TUI framework decision (design record, Chinese) |
| Compare context-offloading changes with an A/B run | Tool-result truncation A/B |
| Pick up the deferred context-offloading work | Context offloading follow-ups |
| Inspect release-facing changes | Changelog |
Subsystem READMEs live beside their code when they are primarily useful to
maintainers: apodex/,
benchmarks/,
deploy/huggingface/, and
tools/golden/. Publishing the public demo Space
has a condensed Chinese walkthrough in
README.zh-CN.md,
with that directory's English README.md as the authoritative version;
README.space.md beside them is the Space's own landing page, not repository
documentation.
When updating documentation, change the canonical page instead of copying a second set of commands:
- root
README.md: product story, capabilities, short quick start, and results; docs/install/: environment-specific installation and deployment;docs/install/docker.md: Compose, image pinning,docker run, and cloud deployment of the CPU agent container;.env.example: the runtime agent, web-tool, and document-reader variables, documented by its own comments;config/sglang/README.md: SGLang variables and tuning;- workflow READMEs: workflow behavior and profiles;
docs/eval.md: running and interpreting evaluations, including datasets and the eval-only credentials that are not in.env.example;docs/eval-frontier-search.md: FrontierSearchBench's external scorer, isolation requirement, and three-step workflow;benchmarks/README.md: benchmark registry and extension points;apodex/README.md: CLI/TUI subsystem reference;docs/framework.mdanddocs/workflows.md: framework development.
Prefer linking to a canonical section over repeating it. A small command that gets a reader started is fine; a second complete setup or troubleshooting guide usually is not.