docs/README.md

Roark documentation

Install, configure, run, and operate Roark.

Last updated 2026-08-19T07:58:25Z

#Quick start

roark init
roark auto --repo owner/repo --limit 1 --dry-run
roark do 123 --repo owner/repo

For the full first-run path, read Quickstart.

Page	Use it for
Quickstart	Install Roark, initialize a target repository, run one issue, inspect the result, and recover.
Concepts	Learn how control checkouts, managed workspaces, attempts, gates, and artifacts fit together.
Usage	Choose the command that matches the work you want Roark to perform.
Glossary	Look up a Roark term.

Page	Use it for
Autorun	Select labeled issues and publish pull requests.
Recovery	Inspect and continue a stopped or failed attempt.
PR reviews	Inspect an existing pull request without changing it.
PR revisions	Apply existing feedback to a pull request.
Issue curation	Turn reviewer findings into approved follow-up GitHub issues.
Verification	Configure and diagnose the readiness and verification gates.

Page	Use it for
Operations runbook	Set up a host, assign permissions, monitor runs, recover work, and upgrade Roark.
Scheduling	Run Roark through cron, launchd, or GitHub Actions.
Managed workspaces	Configure clone workspaces and copy ignored local files.
Security and secrets	Protect secrets and treat GitHub content as untrusted input.
Troubleshooting	Diagnose a failed command or missing result.

Page	Use it for
CLI reference	Look up a command or option.
Configuration	Look up `.roark/config.json` keys, defaults, and precedence.
Labels and Label semantics	Look up GitHub label roles and lifecycle transitions.
Artifacts	Find a file under `.roark/runs` and understand what it records.
Lifecycle hooks	Run setup commands such as dependency installation.

Page	Use it for
Architecture	Find the module responsible for a command or workflow step.
Versioning	Apply the SemVer policy and run the release checklist.
Docs maintenance	Keep the documentation aligned with CLI behavior.