# option-berth

> option-berth (oberth) is the runtime facts layer for Git worktrees: what a checkout should run, whether it really is running, and why not.

oberth keeps one chain — worktree → manifest → service → run → runtime facts — so a person and a coding agent read the same answer. The CLI is the only interface; every command has a `--json` shape, and JSON stdout holds exactly one value.

This guide is the long-form explanation. The authoritative contract for the CLI, JSON fields and the manifest is in the repository's docs/ directory (see Contract below).

## Guide (English)
- [The option-berth guide](https://oberth.zayju.de/guide/): What option-berth is, the chain of facts, the core loop, and how to read the rest of the book.
- [Install oberth](https://oberth.zayju.de/guide/install/): The one-line script, go install, Homebrew, release archives, and the platform boundaries.
- [Your first worktree](https://oberth.zayju.de/guide/quickstart/): The whole loop on Hello Worktree, from an empty checkout to a clean stop.
- [One chain of facts](https://oberth.zayju.de/guide/chain/): Why the order is the contract, how attribution works, and why unknown is a fact.
- [Several worktrees at once](https://oberth.zayju.de/guide/worktrees/): Run ownership, automatic ports, ${worktree} data separation, leftover checkouts, and the events stream.
- [Declare what should run](https://oberth.zayju.de/guide/declare/): init, init draft and init adopt, the smallest manifest, and the fields that change behavior.
- [up: make it run, and wait for real](https://oberth.zayju.de/guide/up/): Dependency order, prepare, automatic ports, readiness, failure reasons, and restart without losing the address.
- [status: what is really running](https://oberth.zayju.de/guide/status/): Process, listener, health and exit as four separate facts; the table, --brief, --json, and observation failures.
- [logs: the service's own output](https://oberth.zayju.de/guide/logs/): One read or a stream, the first error of the current run, and the log of a portless worker.
- [down: stop this project, not the machine](https://oberth.zayju.de/guide/down/): The normal stop, the deleted-checkout entry points, ambiguous groups, and what down never touches.
- [Facts as JSON](https://oberth.zayju.de/guide/json/): The rules, the stable error codes, a worked status read, and what an absent field does not mean.
- [Put oberth inside the agent's loop](https://oberth.zayju.de/guide/agents/): The three moments to call oberth, the reads an agent opens with, recipes, and the pitfalls that bite in hooks.
- [Leave work where the next session finds it](https://oberth.zayju.de/guide/workplace/): The workplace commands, what gets recorded automatically, how a record ends, and why it is not runtime truth.
- [When something looks wrong](https://oberth.zayju.de/guide/diagnose/): A symptom-to-command table, the evidence to keep, and what is not a fix.
- [Where the product stops](https://oberth.zayju.de/guide/boundaries/): No GUI, no machine-wide port radar, no Git writes, no model in the core; plus the contract, by topic.

## Guide (中文)
- [option-berth 指南](https://oberth.zayju.de/guide/zh/): option-berth 是什么、事实链、核心闭环，以及整本书怎么读。
- [安装 oberth](https://oberth.zayju.de/guide/zh/install/): 一行脚本、go install、Homebrew、发布包，以及平台边界。
- [你的第一个 worktree](https://oberth.zayju.de/guide/zh/quickstart/): 在 Hello Worktree 上跑完整闭环：从一个空 checkout 到一个干净的停止。
- [一条事实链](https://oberth.zayju.de/guide/zh/chain/): 为什么顺序就是契约、归属怎么确定，以及为什么未知也是一条事实。
- [同时跑多个 worktree](https://oberth.zayju.de/guide/zh/worktrees/): 运行归属、自动端口、${worktree} 的数据隔离、遗留 checkout，以及 events 流。
- [声明该跑什么](https://oberth.zayju.de/guide/zh/declare/): init、init draft、init adopt，最小清单，以及会改变行为的字段。
- [up：让它跑起来，并等到真的就绪](https://oberth.zayju.de/guide/zh/up/): 依赖顺序、prepare、自动端口、就绪、失败原因，以及不丢地址的重启。
- [status：现在到底跑着什么](https://oberth.zayju.de/guide/zh/status/): 进程、监听、健康、退出四种事实；表格、--brief、--json，以及观察失败。
- [logs：服务自己的输出](https://oberth.zayju.de/guide/zh/logs/): 一次读取或持续跟随、当前运行的第一条错误，以及无端口 worker 的日志。
- [down：停这个项目，不动整台机器](https://oberth.zayju.de/guide/zh/down/): 正常停止、checkout 已删除时的入口、同名组，以及 down 永远不碰的东西。
- [JSON 里的运行事实](https://oberth.zayju.de/guide/zh/json/): 规则、稳定错误码、一次 status 的完整读取，以及字段缺失不代表什么。
- [把 oberth 放进 agent 的循环](https://oberth.zayju.de/guide/zh/agents/): 三个调用时机、agent 开局的三次读取、接入配方，以及 hook 里最容易踩的坑。
- [把工作留在下一个会话找得到的地方](https://oberth.zayju.de/guide/zh/workplace/): workplace 命令、自动记录的内容、记录如何结束，以及为什么它不是运行事实。
- [看起来不对的时候](https://oberth.zayju.de/guide/zh/diagnose/): 症状到命令的对照表、求助时要留下的证据，以及什么不是修复。
- [产品的边界](https://oberth.zayju.de/guide/zh/boundaries/): 没有图形界面、不做整机端口表、不写 Git、内核不看模型；外加按主题分组的契约入口。

## Contract
- [CLI contract](https://github.com/SheathedSharp/option-berth/blob/main/docs/cli.md): the command surface, JSON fields, error codes and manifest references.
- [Product definition](https://github.com/SheathedSharp/option-berth/blob/main/docs/product.md): the need, the object model, write boundaries and what the product refuses to do.
- [Install and uninstall](https://github.com/SheathedSharp/option-berth/blob/main/docs/install.md): every installation channel, upgrade, removal and platform boundary.
- [Integrating orchestration tools](https://github.com/SheathedSharp/option-berth/blob/main/docs/integrations.md): recipes for Conductor, Cursor, Claude Code and Codex, plus the AGENTS.md section.
- [Work records](https://github.com/SheathedSharp/option-berth/blob/main/docs/workplace.md): the workplace commands, block fields and their boundaries.
- [Architecture](https://github.com/SheathedSharp/option-berth/blob/main/docs/agent/architecture.md): implementation boundaries and the chain of facts.

## Project
- [Source](https://github.com/SheathedSharp/option-berth): the engine, examples and site in one repository.
- [Releases](https://github.com/SheathedSharp/option-berth/releases): signed-archive checksums and platform archives.
- [macOS client](https://github.com/SheathedSharp/option-berth-macos): a separate product; it presents the same facts and grows no capability the CLI lacks.
- [Coding-agent skill](https://github.com/SheathedSharp/option-berth-skill): a separate product; it teaches an agent the same CLI and is not distributed from this repository.

## Optional
- [Full guide text](https://oberth.zayju.de/llms-full.txt): every English chapter in one plain-text file.
- [Sitemap](https://oberth.zayju.de/sitemap.xml): every page, in both languages.