Short answers. Deep dives link to other docs.
Setting up for the first time? See the onboarding hub — checklists, GUI vs CLI, and plain-language status help.
onboarding/README.md — pick quickstart (desktop) or first-run-cli (terminal).
No for desktop-first setup. Use quickstart and the in-app Getting Started hub. CLI is optional: choose-your-path.
Healthy / Degraded / Blocked on Getting Started — same idea as Docker Desktop engine status. Details: status-indicators.md.
First diet-hermes install downloads Python packages (3–8 min). Later launches are seconds. installation.md
Usually missing LLM API keys on profile joyzoning. api-keys-and-models.md
Yes — Project → Open Workspace when ready. first-run-desktop.md
desktop-menu-guide.md — menu bar and sidebar map.
troubleshooting-setup.md — decision trees for app, checklist, chips, and jz.
Yes. Use jz task start-external <task-id> --agent cursor. JoyZoning creates the card branch and a JSDP prompt; you edit in Cursor; you run mark-ready, verify, and complete --yes. No Hermes lease is created. external-agent-jsdp.md
No. Each role can be external: jz delivery-chain next <chain-id> --external --agent cursor. Role 2 stays blocked until Role 1 is Complete after your merge — same gate as managed roles.
External tasks do not have leases by design. Use jz task status <id> or GET /api/tasks/{id}/external/status.
No. Same rule as managed work: only the operator runs jz task complete <id> --yes after review and verification.
execution-paths.md — decision table, cheat sheet, prerequisites.
A governed execution runtime for AI-assisted software work on your machine — review, boundaries, verification, and human merge before changes count as done. Plain language: what-is-joyzoning.md. Technical spine: concepts.md.
No. It is a supervision layer: kanban, leases, approvals, diffs, timeline. You keep editing in your IDE; JoyZoning tracks agent work and sign-off.
One kanban card → one inspection context in your canonical workspace. After dispatch, work is on branch joyzoning/card-<id>; before dispatch, you see the session workspace on your default branch. Workspace, Timeline, and git all agree. workspace-state.md · philosophy.md.
Session workspace = the project you opened (Project → Open Workspace). Card branch = joyzoning/card-<id> after Dispatch — same folder, different branch. Always check the header before merge — like confirming the right PR branch.
Workspace for files on disk; Manager Chat for plans and reasoning. Same split as GitHub issue comments vs the PR Files changed tab.
The name reflects zoning agent authority: each task gets a bounded lease (worktree + rules), like zoning land for a specific use.
No. One diet-hermes checkout; manager and executor are different sessions on the same gateway. hermes-integration.md
Merge is the human accountability gate. Agents stop at ready_for_review after verification. lease-lifecycle.md
risk: 3. Dispatch and retry require humanApprovedCritical / --approve-critical. Only one critical active lease globally by default.
The lease stays in verifying (or blocked); failed reports are stored as evidence. Re-run verify; use supersede when replacing a passing report. execution-orchestration-api.md
No. Worktree paths are preserved; evidence and verification JSON remain on the lease record.
| Port | Service |
|---|---|
| 9470 | JoyZoning control plane |
| 8642 | Hermes API |
| 9119 | Hermes dashboard |
macOS: ~/Library/Application Support/JoyZoning/joyzoning.db. Override with JOYZONING_DB_PATH. configuration.md
Yes. Same REST API and lease orchestration. jz agent is the constrained worker subset.
Yes. Run the control plane and use jz only. cli.md
diet-hermes / Hermes Agent. JoyZoning installs via scripts/install-diet-hermes.sh or your own checkout.
Usually missing dashboard token. Connect dashboard from Hermes → Connection…. [troubleshooting.md#hermes-and-connectivity)
Default profile name: joyzoning (API enabled on 8642). Configurable per session.
whitepaper.md (v1.6) — implementation-independent; JoyZoning is one embodiment (Annex A). Start with whitepaper-summary.md for invariants C1–C7 and boundaries B1–B4. Theory hardening: theory-hardening-audit.md. Narrative: research-companion.md.
Framework shorthand: narrative advises; inspectable repository state grounds acceptance; merge authority is the operator accountability gate (invariant C2). Product mapping: philosophy.md, execution-paths.md.
No. Constraint persistence (§1.3): acceptance disciplines (coordinates, merge authority, gates) have outlasted recent mutation-engine churn in observed environments—contingent mechanisms, persistent requirement. Managed and external JSDP paths are embodiments, not definitions.
MIT — LICENSE.
GitHub Issues with OS, .NET version, and health report if connectivity-related. CONTRIBUTING.md