Docs map

Read top down

Do not start from every subsystem at once. Start with the smallest mental model, watch one real run, then move into the operating surface that matches your job.

light entryoperatedecidecontrolbuildreference

Read 5-minute storyRead run anatomy

small model firstreal run nextcontracts last

Depth axisLight entry -> operation -> decision lenses -> control -> builder -> contracts.Domain axisRun control, profiles, evidence, workspaces, cross-project, prompts, MCP.Reading ruleMove deeper only when the current layer raises a concrete question.

docs routedepth + domain

01  what is the run shape?
  -> 5-minute story, quickstart

02  how do I operate delivery?
  -> lifecycle, gates, evidence, recovery

03  which responsibility lens applies?
  -> technical leadership, economics, adoption

04  how do I control it from tools?
  -> MCP, CI autopilot, handoffs

05  how do I adapt it to my project?
  -> workspaces, plugins, skills, prompts

06  what is the exact contract?
  -> config, profiles, artifacts, events

Read by depth first. Use domain slices when you already know the problem surface you need.

01Light entryUnderstand Orcho, run one mono task, watch live output, and read the result.02Advanced operationOperate real delivery: lifecycle, gates, evidence, rejects, recovery.03Decision lensesEvaluate Orcho by responsibility: leadership, economics, adoption.04Control surfacesStart, observe, and guide runs through MCP or tuned CI automation.05Expert builderTune workspaces, plugins, skills, prompts, profiles, and runtimes.06ReferenceUse raw config, profile, CLI, artifact, and event contracts.

Light entry

Use this layer when you are still deciding whether Orcho makes sense.

Question	Read
What is Orcho?	What is Orcho?
Can I see the whole idea in one run story?	Orcho in 5 minutes
Can my AI client run Orcho for me?	Let your agent drive it
How do I run one task?	Quickstart
What should I watch while it runs?	Watch the run
What did the run leave behind?	Read the result
Why do profiles matter, deeper?	Profile semantics
Can Orcho recommend the profile?	Profile advisor

This layer should stay compact. It explains the promise: Orcho turns agent work into accountable delivery runs.

Advanced operator

Use this layer when you are running real work and need to make decisions.

Operating need	Read
Understand the lifecycle	Run lifecycle
Control delivery decisions	Delivery control
Run tuned projects without prompts	CI autopilot
Read a deeper feature-shaped run	Run anatomy
Understand plan contracts and subtask DAGs	Plan contract and DAG
Understand pauses and handoff advice	Handoffs and advisors
Understand run economics	Cost accounting
Recover after rejection	Correction follow-ups
Choose resume vs follow-up	Recovery and resume
Start through MCP	Start with MCP
Understand MCP ROI	LLM captain mode
Operate through MCP	MCP control surface
Observe a run from a client	Observe a run
Build an expert MCP captain loop	Expert MCP control loop
Understand workspace boundaries	Workspace model
Coordinate across project boundaries	Cross-project mode

This layer is where Orcho becomes an operator tool, not only a CLI command.

Decision lenses

Use this layer when the question is not “how do I operate a run?”, but “what does Orcho change for the person accountable for delivery?”

Decision question	Read
How should a technical leader evaluate Orcho?	For technical leaders
How do we judge workflow economics?	Cost accounting
What crosses the security boundary?	Security and privacy
When is MCP worth the overhead?	LLM captain mode
What proof exists after the run?	Evidence bundle
Where does cross-project work matter?	Cross-project mode

This is not a separate developer path. Developers and operators should read Light entry and Advanced operation first. Decision lenses are for tech leads, CTOs, VPs of Delivery, and anyone judging accountability, adoption, economics, and organizational risk.

Expert builder

Use this layer when you are shaping Orcho for a repository, team, or extension.

Builder need	Read
Teach Orcho a repository	Project tuning and plugins
Understand participant topology	From mono-run to participant sets
Coordinate one feature across repositories	Cross-project mode
Route subtasks to domain capabilities	Skill registry
Understand prompt composition	Prompt engine
Tune workflow depth and gates	Profiles and gates
Inspect every profile mode and schema key	Profile reference
Connect worker CLIs	Runtime adapters
Understand every config surface	Configuration reference
Inspect proof artifacts	Evidence bundle
Prove verification ran	Verification receipts
Work from raw contracts	Configuration, Profiles, CLI, Artifacts, Events

This layer should be dense. It is for people who already understand the run shape and now need contracts.

Domain slices

The same docs can also be read by product subsystem.

Run controlLifecycle, delivery decisions, plan/DAG, handoffs, follow-ups, resume.Profiles and gatesThe semantic plane, verification boundary, readiness policy, receipts.Evidence and trustRecorded result, artifacts, events, cost, proof that gates actually ran.WorkspacesRun state, project boundaries, participant sets, isolation choices.Cross-project deliveryOne feature intent split across repo boundaries and returned to one gate.Decision lensesLeadership, economics, adoption risk, MCP ROI, and accountability.Prompt enginePrompt parts, protected contracts, project context, utility-lab primitives.Project knowledgePlugins, project policy, prompt overrides, routed skills.Worker runtimesWorker CLIs, phase routing, adapter boundaries, cost accounting.MCP controlTyped client control for start, observe, diagnose, and decide.Reference contractsConfiguration, profiles, CLI, artifacts, events.

Run control

Run control is the lifecycle plus the decisions that move it forward.

• Run lifecycle
• Delivery control
• CI autopilot
• Run anatomy
• Plan contract and DAG
• Handoffs and advisors
• Correction follow-ups
• Recovery and resume

Decision lenses

Decision lenses are not a separate developer tutorial. They help accountable people evaluate Orcho from the responsibility they carry: quality, adoption, economics, policy, and cross-system risk.

• For technical leaders
• Security and privacy
• Cost accounting
• LLM captain mode
• Evidence bundle
• Cross-project mode

Profiles and gates

Profiles choose the shape of work. Gates decide whether work can continue or deliver. Isolation policy decides whether that work happens in a retained run-owned checkout or directly in the project checkout.

• Profile semantics
• Profile advisor
• CI autopilot
• Profiles and gates
• Profile reference
• False-ready delivery
• Verification receipts

Evidence and trust

Evidence is the durable proof surface behind a run.

• Read the result
• Cost accounting
• Evidence bundle
• Verification receipts
• Artifacts
• Events

Workspaces and participant sets

Workspaces separate project code from run state. Participant sets explain how Orcho grows beyond one repository. Cross-project mode is the delivery shape for one feature intent that must move across project boundaries and return to one system release decision.

• Workspace model
• Project tuning and plugins
• Mono and participant sets
• Cross-project mode

Cross-project delivery

Cross-project delivery is the advanced surface for API/web, backend/mobile, runtime/MCP, analytics, docs, or infra work that fails at the boundary between systems.

• Cross-project mode
• Run anatomy
• Plan contract and DAG
• Handoffs and advisors
• Evidence bundle

Prompt engine

The prompt engine composes role, task, format, protected contracts, project context, and turn payload before a worker runtime is invoked.

• Prompt engine
• Skill registry
• Project tuning and plugins
• Profiles and gates

Project knowledge and skills

Project tuning, prompt overrides, and skills are different customization surfaces. Use plugins for project facts and policy. Use the skill registry for portable specialist procedures that can be routed to subtasks.

• Project tuning and plugins
• Skill registry
• Prompt engine
• Configuration reference
• Plan contract and DAG
• Workspace model

Worker runtimes

Worker runtimes are agent CLIs. Orcho routes phases to them, but does not let them own the delivery protocol.

• Quickstart
• Runtime adapters
• Cost accounting
• CI autopilot
• Watch the run

MCP control

MCP is the typed control surface for clients that start, observe, diagnose, and decide runs.

• Start with MCP
• LLM captain mode
• MCP control surface
• Observe a run
• Expert MCP control loop
• Events

Reference contracts

Use reference pages after the operating model is clear.

• Configuration
• Profiles
• CLI
• Artifacts
• Events

Rule for going deeper

Move to the next layer only when the current layer raises a concrete question:

• “What is this?” -> light entry.
• “What do I do now?” -> advanced operator.
• “How do I configure or extend it?” -> expert builder.
• “What exactly is the contract?” -> reference.

That keeps the docs from becoming a wall, while still giving deep readers a clear path down.