Roark documentation

#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.

#Start Here

• Quickstart - install, initialize a target repository, run one issue, inspect results, and recover.
• Concepts - control checkout, managed workspace, attempt, readiness gate, verification gate, and artifacts.
• Usage - choose between do, auto, continue, revise-pr, workspace commands, and issue curation.
• Glossary - short definitions for common Roark terms.

#Workflows

• Autorun - label-gated one-shot automation and PR publishing.
• Recovery - inspect and continue stopped or failed attempts.
• PR revisions - respond to feedback on an existing pull request.
• Issue curation - turn reviewer findings into approved follow-up GitHub issues.
• Verification - readiness and verification gates.

#Operations

• Operations runbook - host setup, permissions, monitoring, recovery, cleanup, and upgrades.
• Scheduling - cron, launchd, and GitHub Actions examples.
• Managed workspaces - clone workspaces and workspace.copyToWorktree.
• Security and secrets - secret handling and untrusted input boundaries.
• Troubleshooting - common failure symptoms and recovery steps.

#Reference

• CLI reference - commands and options.
• Configuration - .roark/config.json, defaults, and precedence.
• Labels and Label semantics - GitHub label roles and lifecycle transitions.
• Artifacts - .roark/runs layout and phase outputs.
• Lifecycle hooks - setup commands such as dependency installation.

#Development

• Architecture - contributor-level module and workflow overview.
• Workflow skills - bundled and repo-local skill resolution.
• Versioning - SemVer policy, changelog expectations, and release checklist.
• Docs maintenance - checks to keep docs aligned with CLI behavior.

#By role

#Repository user

Read Quickstart, Concepts, Configuration, Managed workspaces, and Verification.

#Operator

Read Operations runbook, Autorun, Recovery, Scheduling, Security and secrets, and Troubleshooting.

#Contributor

Read Architecture, Artifacts, CLI reference, PR revisions, Labels, Workflow skills, Versioning, and Docs maintenance.

#Navigation Metadata

docs/docs.json contains the same top-level navigation groups for future docs-site generation or link checks.