Reading Paths

Reading Paths

Audience-based tours through the wiki. Each path is short on purpose — pick the one that matches why you are reading, walk it in order, and you end the walk with a complete mental model for your role.

If you are editing the wiki and add a page that belongs in one of these tours, update this file.

---

Path 1 — Newcomer

You have heard of stud-cli and want to know what it is.

1. First Run flow — what the very first invocation looks like (provider setup + project-trust prompt). Grounds the rest of the path in a concrete experience.
2. Vision — problem, philosophy, non-goals.
3. Glossary — the vocabulary used everywhere else. Skim; come back as needed.
4. High-Level Architecture — one diagram of the whole system.
5. Extensibility Boundary — what is extensible vs. core.
6. Default Chat flow — an end-to-end turn with no SM attached. Concretizes the diagram.

After this you should be able to answer: What does stud-cli do that existing tools do not? What is core vs. extension? How does one turn actually flow?

---

Path 2 — Extension author

You want to write a provider, tool, hook, UI, logger, command, Session Store, or Context Provider.

1. Vision and Extensibility Boundary — make sure your idea is an extension and not a core change.
2. Glossary — especially attached, loaded, active, bundled, default, immutable.
3. Contract Pattern — the meta-shape every extension implements.
4. Extension Lifecycle — init / activate / deactivate / dispose and reload safety.
5. Host API — what your extension can request from core.
6. Validation Pipeline — load-time checks and severity.
7. Configuration Scopes — which layer your extension ships in and how overrides work.
8. The contract for your category:
   • Providers — and Provider Params for the defaultParams shape and per-adapter native fields.
   • Tools
   • Hooks
   • UI
   • Loggers
   • State Machines
   • Commands
   • Session Stores
   • Context Providers
9. Subagent Sessions — read if your tool, hook, or UI may interact with delegated child sessions, or if your provider should expect concurrent requests from the same parent session's subagents. The bundled delegate tool is the reference example.
10. Versioning and Compatibility — how your contract version interacts with core versions.
11. Conformance and Testing — what contract tests you should run.
12. A matching reference extension, when available, under reference-extensions/.
13. Prompt Caching — required reading if you write a Provider or Protocol Adapter; optional but useful for Context Provider authors who shape the system layer.

Before shipping, also read anything under security/ that applies to your category — especially Secrets Hygiene if you touch env or config, and LLM Context Isolation if you contribute to context.

---

Path 3 — State machine designer

You want to drive a deterministic workflow where the LLM is an executor, not the orchestrator.

1. Vision — the deterministic-workflow philosophy.
2. Glossary — especially stage, stage definition, stage execution, orchestrator session, turn stage, attached, completionTool, turnCap.
3. State Machines contract — the Stage pipeline; SM authority; cardinality (one attached).
4. SM Stage Lifecycle — the six steps per stage (Setup → Init → CheckGate → Act → Assert → Exit).
5. Stage Definitions — the markdown + frontmatter format you write.
6. Stage Executions — how a stage runs inside the orchestrator session; grantStageTool; fan-out and joins; strict cancel.
7. Execution Model and Message Loop — the turn stages that compose inside each stage execution.
8. Hook Taxonomy — per-call guard hooks are orthogonal to your SM; the SM owns workflow, guards own argument-sensitive policy.
9. Command Model — commands are orthogonal to SM; the user can always run /save, /resume, etc.
10. Extension State — how your SM's state rides the session.
11. Security Modes and Tool Approvals — stage-level precedence over mode.
12. Determinism and Ordering — what is deterministic and what is not (compaction, sampling, retries, user approvals, clock).
13. Context Providers contract — sanctioned way to feed facts into the LLM's view.
14. Concurrency and Cancellation — stage cancellation scope and the strict-cancel rule for parallel fan-out.
15. State Machine Workflow flow and Ralph case study — concrete walkthroughs.
16. LLM vs SM Orchestration — side-by-side comparison.

After this you should be able to answer: What does my SM own? What does a stage look like on disk? What does Act see? What happens when a stage fails or a sibling is cancelled? How does state survive a resume?

---

Path 4 — Reviewer (security / trust / compliance)

You are reviewing stud-cli for deployment, audit, or threat-model purposes.

1. Vision and Extensibility Boundary — know the attack surface.
2. Trust Model — the overall posture.
3. Project Trust — the first-run prompt; trust list.
4. Extension Isolation — v1 is in-process, no sandbox. Read this explicitly.
5. Extension Integrity — signing, checksums, pinning — what is and is not available in v1.
6. LLM Context Isolation — env / settings never enter the LLM by default.
7. Secrets Hygiene — env provider; settings.json permissions; project-env commit footgun; session-manifest secret ban.
8. Security Modes — mode is session-fixed.
9. Tool Approvals — SM precedence + mode gate + interactor; subagent envelope and child-session approvals.
10. Subagent Sessions — the user-approved spawn envelope; what an orchestrator LLM can and cannot launder through delegate. Read in tandem with the Subagent Delegation flow.
11. MCP Trust — server startup inherits project trust.
12. Sandboxing — container guidance for yolo; what core does not enforce in v1.
13. Audit Trail — durable record of authoritative actions; subagent attribution chain (parentSessionId / subagentId / depth).
14. Project First-Run Trust flow — trust prompt in context.
15. Headless Run flow — headless + SM / headless + yolo / headless + ask (error). Subagent IP requests follow the same uniform emit-and-halt rule.

After this you should be able to answer: What is trusted by default? What is the blast radius of a malicious extension in v1? Where can secrets leak? What is audited?

---

Path 5 — Operator / deployer

You run stud-cli somewhere, possibly headless, and you want the mental model to operate it.

1. Vision — non-goals especially.
2. Project Root — cwd only, no walk-up.
3. Configuration Scopes — bundled / global / project.
4. Extension Discovery — how layers combine at startup.
5. Extension Reloading — what can and cannot hot reload.
6. Headless and Interactor — SM-attached vs. interactor-required cases.
7. Session Lifecycle, Session Manifest, Persistence and Recovery.
8. Determinism and Ordering — what is reproducible and what is not.
9. Prompt Caching — what stud-cli caches across turns, where the cache invalidates, what observability fields land on the usage bag. Material for cost and latency budgeting.
10. Observability and Audit Trail — where signal comes from.
11. Health and Diagnostics — startup diagnostics, extension health.
12. Session Resume flow — crash → resume with manifest validation; drift.
13. Scope Layering flow — override and extend across bundled, global, project.

---

Path 6 — Deeply curious

You want to understand the whole thing, in order.

Read in directory order, depth-first, following the plan's writing sequence:

1. overview/ — Vision, Glossary, High-Level Architecture, Extensibility Boundary.
2. core/ — the kernel.
3. contracts/ — the normative surfaces.
4. context/, security/, operations/, runtime/ — cross-cutting.
5. providers/, integrations/ — backends.
6. reference-extensions/ — examples.
7. flows/, case-studies/ — end-to-end stories that tie everything together.

---

Updating this page

When you add a new page:

• If it belongs in Path 1–5, add it at the right step.
• If it belongs only to Path 6, add it to its directory group there.
• If it does not belong to any path, ask whether the page should exist at all.