@atollhq/skill-claude 0.4.36 → 0.4.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-claude",
-  "version": "0.4.36",
+  "version": "0.4.37",
   "description": "Install the Atoll project management skill for Claude Code",
   "bin": {
     "skill-claude": "bin/install.mjs"

package/skill/references/local-runner.md

@@ -2,6 +2,105 @@
 
 Read this reference before installing, diagnosing, configuring, or operating `atoll-runner`, its repository bindings, loopback UI, leases, or recovery behavior.
 
+## End-to-end setup
+
+The released runner does not require an Atoll source checkout. It is the
+`atoll-runner` binary in `@atollhq/cli`; the machine needs Node.js, Git, a local
+checkout of each repository that will receive work, and an authenticated Codex
+runtime. On macOS, first confirm that `git --version` succeeds. Apple Git can be
+blocked until the operator reviews and accepts the Xcode Command Line Tools
+license; do not accept legal terms or enter an administrator password for them.
+
+Install or update the released CLI, then verify that both binaries exist:
+
+```bash
+npm install -g @atollhq/cli@latest
+atoll --version
+atoll-runner --help
+```
+
+Create one named Atoll profile per agent identity and organization. Obtain the
+agent key from the human operator; never print it, put it in shell history on
+their behalf, or copy it into runner configuration. The interactive flow is
+preferred when a terminal is available:
+
+```bash
+atoll auth setup
+atoll auth profiles --json
+```
+
+For each profile, discover the project's verified repository mapping and keep
+its opaque `repo_ref`. Do not invent a reference or treat a local path as
+authorization:
+
+```bash
+atoll --profile agent-a repository list --project project-slug --json
+atoll-runner --profile agent-a repositories bind repo-ref /absolute/path/to/checkout --issue issue-uuid
+atoll-runner --profile agent-a repositories validate repo-ref
+```
+
+The issue is authorization evidence for its project; binding does not execute
+that issue. The checkout must be a non-bare Git repository whose credential-free
+`origin` matches the authorized GitHub repository. The runner uses the checkout
+as a verified source and creates isolated worktrees under its private local
+state. It does not work directly in the primary checkout, and the released CLI
+does not accept a custom worktree root or per-issue working directory.
+
+Before the first start, the authenticated agent has no hosted runner row to
+pause. The operator must first remove every eligible assignment from that agent,
+or use a dedicated setup agent with no assignments. Do not infer safety from a
+quick issue read when another process can assign work concurrently. With this
+no-work precondition established, run one bounded real cycle to initialize local
+state and register the hosted row:
+
+```bash
+atoll-runner --profile agent-a run --once
+```
+
+This is not a model test. It is safe only because the agent has no eligible
+assigned work. A binding command creates local identity but not runner state or
+server presence; `doctor` will not fully pass yet, and `--dry-run` intentionally
+does not perform registration. As soon as the runner appears, pause it in
+**Workspace Settings → Runners → Manage → Pause new work** and verify that the
+fleet row shows **Paused**. Keep it paused while running the read-only checks and
+installing the optional macOS service:
+
+```bash
+atoll-runner --profile agent-a doctor
+atoll-runner --profile agent-a run --once --dry-run
+atoll-runner --profile agent-a service install --ui --ui-port 4735
+atoll-runner --profile agent-a service status
+atoll-runner --profile agent-a status
+```
+
+Expected readiness evidence is: `doctor` succeeds, every required repository
+binding validates, Codex is authenticated, the service is installed and loaded,
+the loopback UI returns HTTP 200 when enabled, and runner status reports Atoll
+reachable with no unexpected current or retained job. A dry run is read-only;
+after the hosted row is paused it should return no candidate with
+`blocked_reason: intake_paused`.
+
+Only after those checks pass should the operator resume **Workspace Settings →
+Runners → Manage → Resume new work**. Read back both the hosted fleet row and
+`atoll-runner --profile agent-a status`; the final state is `connected` with
+active/accepting intake. Resuming can immediately claim eligible assigned work,
+so do not use it as a setup probe.
+
+One machine can store and run multiple named profiles, including profiles for
+different organizations. Each runner process and macOS service is fixed to one
+profile, and that profile supplies one agent identity and organization. Install
+one service per profile and give every enabled loopback UI a different port:
+
+```bash
+atoll-runner --profile agent-a service install --ui --ui-port 4735
+atoll-runner --profile agent-b service install --ui --ui-port 4736
+```
+
+Do not run competing profiles for the same Atoll agent identity: the server
+allows one current local runner installation per authenticated agent. A single
+profile can bind several authorized repositories, each to its own absolute local
+checkout. Work remains serialized to one current job per runner installation.
+
 ### Local runner presence
 
 Authenticated agents can register and refresh one local runner installation with