@uchibeke/gallivant 0.2.0 → 0.2.1

package/docs/install.md

@@ -1,14 +1,34 @@
 # Install
 
-Get one repository task from a brief to a reviewed pull request. Install the CLI,
-sign in to GitHub and one harness, finish the checks, then start a small task.
-Gallivant keeps the implementation and review loop moving; you review and merge.
+Get one repository task from a brief to a reviewed pull request. One command sets
+up a repository; `doctor` tells you what still needs your decision or login; then
+you start a small task. Gallivant keeps the implementation and review loop moving
+and you review and merge.
 
 **Using a coding agent to set this up?** Give it the [agent setup guide](agent-setup.md).
-It includes a copy/paste prompt, setup checks and the point where a real run starts.
+It includes a copy/paste prompt, the setup checks and the point where a real run starts.
 
-For DNS errors or stalled provider calls, see [network diagnosis and recovery](network-recovery.md).
-The diagnostic command works before configuration or login, on Linux and macOS.
+## 1. Prerequisites
+
+Requirements shared by the coordinator: macOS or Linux, Node 22 or newer, Git,
+`gh` signed in, and `jq`. For the recommended local path, use signed-in Codex CLI
+0.160.0+ or Claude Code 2.1.263+ (Codex implementation accepts 0.158.0+, but
+plain-language preparation needs 0.160.0+). Hosted OpenAI Agents execution has a
+separate setup below and needs no local Codex or Claude binary. See the
+[capability matrix](../README.md#harness-support) before choosing another harness.
+
+| Prerequisite | Check | If it fails |
+| --- | --- | --- |
+| Node 22+ | `node --version` | install Node from your package manager or a version manager |
+| Git and jq | `git --version`, `jq --version` | `brew install git jq`, `apt install git jq` or `dnf install git jq` |
+| GitHub CLI signed in | `gh auth status` | `gh auth login` |
+| Codex CLI signed in | `codex login status` | `codex login` |
+| Claude Code signed in | `claude auth status` | `claude auth login` |
+| Git identity | `git config --get user.name`, `git config --get user.email` | `git config --global user.name "..."` and `user.email` |
+
+Each login belongs to that tool's own flow. Nothing in Gallivant asks for a
+password, token or browser cookie, and `init` stops before writing anything when
+`gh` or the selected harness is signed out.
 
 Linux installations need process inspection through `ps` with `lstart`, `command`,
 PID and process-group fields (normally the `procps`/`procps-ng` package). Minimal
@@ -17,72 +37,103 @@ blocks safe restart rather than allowing overlapping agents. The CI baseline is
 Ubuntu with Node 22/24; other distributions must also satisfy their harness and
 sandbox prerequisites.
 
-Start with one harness and one repository. `gallivant init` creates your local
-config; `gallivant doctor` checks the prerequisites and prints a fix for each
-missing item. Setup time depends on whether your harness and GitHub are already
-configured. No model call is needed to install the CLI or validate a hand-written PRD.
+For DNS errors or stalled provider calls, see [network diagnosis and recovery](network-recovery.md).
+The diagnostic command works before configuration or login, on Linux and macOS.
 
-Requirements shared by the coordinator: macOS or Linux, Node 22 or newer, Git,
-`gh` signed in, and `jq`. For the recommended local path, use signed-in Claude
-Code 2.1.263+ or Codex CLI 0.160.0+ (Codex implementation accepts 0.158.0+, but
-plain-language preparation needs 0.160.0+). Hosted OpenAI Agents execution has a
-separate setup below and needs no local Codex or Claude binary. See the
-[capability matrix](../README.md#harness-support) before choosing another harness.
+## 2. The command
 
-## 1. The command
+Inside the Git checkout you want Gallivant to work in:
 
-Check the [registry version](https://www.npmjs.com/package/@uchibeke/gallivant). If one
-is available, install the CLI with `npm install -g @uchibeke/gallivant` and check
-`gallivant --version`. If the package has not been published yet, use the source
-checkout:
+```bash
+cd /path/to/your/repository
+npx --yes @uchibeke/gallivant init --harness codex    # or: --harness claude
+```
+
+This setup flow requires **0.2.1 or newer**. On 2026-10-20, npm's `latest` was
+still 0.2.0: its `init` creates the config only, so repository registration and
+`doctor` must be done separately. A maintainer must [publish 0.2.1](releasing.md)
+before the command above provides the flow below; setup does not publish it.
+
+`npx` downloads the published `@uchibeke/gallivant` package into npm's cache and
+runs its `gallivant` command. Nothing is installed globally, no `gallivant`
+command is added to your PATH, and this repository is not cloned. The command
+ends by saying so and printing both the next `npx` command and the optional
+persistent install:
 
 ```bash
-git clone https://github.com/uchibeke/gallivant && cd gallivant
-npm ci --ignore-scripts
-npm link
+npm install -g @uchibeke/gallivant     # optional; then use plain `gallivant`
 gallivant --version
-gallivant --help          # from any directory, to confirm it is on your PATH
 ```
 
-The package has locked runtime dependencies; `npm ci` installs them for a source
-checkout. `npm i -g .` copies instead of linking.
-If the shell cannot find the command afterwards,
-the `bin` directory under `npm prefix -g` is not on your PATH.
+If the shell cannot find `gallivant` after a global install, the `bin` directory
+under `npm prefix -g` is not on your PATH. Avoid `sudo npm install`; use a
+user-owned Node installation or prefix. The rest of this guide writes
+`gallivant`; with `npx`, read that as `npx --yes @uchibeke/gallivant`.
+
+### What `init` does
+
+1. Refuses to continue, writing nothing, when the directory is not a Git
+   checkout, its `origin` remote is not a github.com repository, `gh` is signed
+   out, the selected harness is missing, too old or signed out, or the resolved
+   run credential cannot see or push to the repository. Each refusal names the
+   command that fixes it. Classic credentials also need `public_repo` or `repo`
+   scope; a failed scope lookup stops setup before writing and asks you to retry.
+2. Creates `~/.gallivant/config.json` (mode 600) with your authenticated GitHub
+   login in `trusted_authors`, the selected installed harness, notifications
+   disabled and a separate `~/.gallivant-worktrees` directory for task checkouts.
+   Use `--worktrees /absolute/path` to put checkouts elsewhere, outside the
+   config home.
+3. Records the repository in `repos` once, by its lowercased `owner/name`.
+4. Prints the `doctor` report and exits with its status: `0` when every check
+   passes, `1` while something still needs you.
+
+Running it again is safe. An existing config keeps every key as written,
+including custom harness binaries, `github_token_file`, `repos` entries with
+their base branches, `notify` and `worktrees`; the only change is the one `repos`
+entry for the current repository, and a repository already listed is not
+duplicated. `--worktrees` is refused when it differs from the configured
+directory, so edit the config to move checkouts. `--harness` adds the named
+harness when it is not configured yet and leaves the others alone.
+If both Codex and Claude are configured, pass `--harness codex` or
+`--harness claude` explicitly. Setup rechecks settings changed by another command
+before writing, so concurrent repository registrations preserve each other's entries.
+
+### What `init` leaves to you
+
+`doctor` reports these with the exact fix. `init` does not perform them:
+
+- **Reviewer.** The default reviewer is the Codex GitHub integration. Enable it
+  on the repository, configure another supported bot, or set `"reviewer": null`
+  to rely on CI and trusted human feedback. Without one of these, the default
+  loop waits for a review that cannot arrive. See [the reviewer key](config.md#the-reviewer-object).
+- **Branch protection.** Section 5 below. `doctor` prints the `gh api` call; you
+  run it.
+- **Harness guardrails.** Sections 7 and 8 below. APort's installer writes the
+  hook, and Codex asks you to trust it interactively.
+- **Credentials and notifications.** Sections 4 and 6 below are optional and
+  need your own token or ntfy topic.
+- **Starting work.** Setup never prepares or starts a task, so it spends nothing
+  on inference. Section 9 covers the first task and what `--run` authorizes.
 
 Global configuration lives in `~/.gallivant/config.json` (or
-`$GALLIVANT_HOME/config.json` when explicitly set). Task commands still
-need a target checkout: run inside it, pass `--dir` for natural-language tasks, or
-pass the PRD path for a written brief.
+`$GALLIVANT_HOME/config.json` when explicitly set). See [config.md](config.md)
+for every key. Task commands still need a target checkout: run inside it, pass
+`--dir` for natural-language tasks, or pass the PRD path for a written brief.
+
+### Install from source
 
-## 2. Sign in and create config
+Contributors who want to run the checkout they are editing:
 
 ```bash
-gh auth login             # skip if gh auth status already passes
-codex login               # or sign in with claude, if that is your selected harness
-git config --get user.name
-git config --get user.email
-gallivant init --harness codex    # or --harness claude
-gallivant doctor
+git clone https://github.com/uchibeke/gallivant && cd gallivant
+npm ci --ignore-scripts
+npm link
+gallivant --version
 ```
 
-`init` writes `~/.gallivant/config.json` with mode 600, trusts your authenticated
-GitHub login, records only the selected installed harness, and creates
-`~/.gallivant-worktrees` for separate task checkouts. Use `--worktrees /absolute/path`
-to choose another location outside the config home. Notifications start disabled.
-Existing configs are never overwritten. If `init` reports an existing config,
-continue with `doctor`; preserve the config and repair only the relevant keys.
-Set your Git name/email if the checks
-above are empty; commits use your configured identity.
-
-`doctor` can also print a suggested config when none exists. It reports missing
-guardrails, credentials and repository protections; `init` does not configure
-those for you. Add the target repository to `repos` so `doctor` checks its
-permissions, base branch and protections. See [config.md](config.md) for every key.
-The default reviewer is
-the Codex GitHub integration: enable it on your target repository, configure
-another supported bot, or explicitly set `"reviewer": null` to use CI and trusted
-human feedback. Without a configured review bot, the default loop waits for a
-review that cannot arrive.
+The package has locked runtime dependencies; `npm ci` installs them for a source
+checkout. `npm i -g .` copies instead of linking. This is not the path for using
+Gallivant; the published package is.
 
 ### Hosted Agents API instead of a local CLI
 
@@ -134,7 +185,16 @@ currently disabled because repository ownership of the selected environment
 cannot be verified. See [the Cloud gate](codex-cloud.md); local Codex and Claude
 remain available.
 
-## 3. GitHub auth
+## 3. Read the report
+
+`init` ends with the `doctor` report; `gallivant doctor` prints it again at any
+time. Every failing line carries the command or file that fixes it. Work through
+them in order, then rerun `doctor`. `doctor` without flags checks configuration,
+credentials and repository access without launching a model run; `doctor --probe`
+runs a real Claude sandbox test and `doctor --send` sends a real notification,
+so use those only when you mean to.
+
+## 4. GitHub auth
 
 By default Gallivant uses the login you already have, however you set it up. Nothing to configure beyond `gh auth status` passing. There is no file to copy for this: every git setting a run needs, the credential helper included, is passed in the run's environment.
 
@@ -178,11 +238,11 @@ recognizes enterprise hosts on an existing checkout, but new-task repository
 resolution and clone URLs currently use github.com. An enterprise login or token
 alone does not establish supported end-to-end operation.
 
-## 4. A ruleset on each repo
+## 5. A ruleset on each repo
 
 The one control that stops a push to the default branch is GitHub's. `doctor` prints the exact `gh api` call for every repo in `repos`; it creates a ruleset that blocks deletion and force pushes on the default branch and requires a pull request, with no bypass actors. Gallivant never merges, so the ruleset costs nothing in the loop.
 
-## 5. Notifications
+## 6. Notifications
 
 Optional: create a topic on [ntfy.sh](https://ntfy.sh) or your own server, install the ntfy app, and set
 `"notify": { "ntfy": "https://ntfy.sh/<unguessable-topic>", "email": null }`.
@@ -195,7 +255,7 @@ gallivant doctor --send      # sends one test message
 
 Three kinds of message exist: `ready for a human`, `needs you: <reason>`, and a throttled `gallivant: <error>` when the daemon itself cannot work (gh not authenticated, a harness signed out). Nothing on merge. Nothing per round.
 
-## 6. APort on Claude Code
+## 7. APort on Claude Code
 
 APort's installer writes a PreToolUse hook with matcher `*` into whichever settings file it is pointed at, and the hook enforces one passport. Gallivant's passport is strict on purpose: writes only under the worktrees directory, control-plane directories blocked. Installed into `~/.claude/settings.json`, that policy would apply to every interactive Claude session you run and block your normal work. So the installer goes into a Gallivant-owned directory, and every run loads it with `--settings` plus `APORT_CLAUDE_CODE_CONFIG_DIR`. Nothing about the sandbox requires this; it is only about keeping Gallivant's policy separate from yours.
 
@@ -224,7 +284,7 @@ gallivant doctor --probe     # a real run: a write inside the checkout succeeds,
 
 The probe reads the APort audit log to tell apart a hook that never ran from a passport that allowed the write, and prints the fix for each.
 
-## 7. APort on Codex
+## 8. APort on Codex
 
 ```bash
 npx @aporthq/aport-agent-guardrails codex --global --enforcement=warn
@@ -239,7 +299,7 @@ Git metadata writes and escalations, the scoped token and the ruleset. Gallivant
 sets the approval mode on start and resume. A denial must be diagnosed, not
 bypassed. See [guardrails.md](guardrails.md#codex-git-writes-need-automatic-approval).
 
-## 8. First task
+## 9. First task
 
 Before dispatch, confirm the repository, target branch, permitted changes and
 spending limits. The default `max_iterations` is 30 automatic fix rounds;

package/docs/launch.md

@@ -1,10 +1,13 @@
 # Announcement drafts
 
 Publish these only after [the release checks](releasing.md#verify-before-announcing)
-pass and the repository is public. Use the install command that actually works
-for the released version; do not advertise npm installation before publication.
-Add a genuine dashboard screenshot or recording of a task reaching a reviewed
-PR. Fixture tests are not live provider evidence.
+pass for the version being announced. The package is published as
+`@uchibeke/gallivant`; the setup command to advertise is
+`npx --yes @uchibeke/gallivant init --harness codex` (or `--harness claude`),
+run inside the target checkout. Check that the behavior the README describes is
+in the released version before quoting it. Add a genuine dashboard screenshot or
+recording of a task reaching a reviewed PR. Fixture tests are not live provider
+evidence.
 
 ## X
 

package/docs/openai-agents.md

@@ -414,7 +414,7 @@ publication and review correction. Use the exact prerequisites above to record
 those phases; fixture passes alone are not end-to-end qualification.
 
 The original M5/M6 integration handoff points to
-[`aporthq/agent-passport#417`](https://github.com/aporthq/agent-passport/pull/417),
+[`aporthq/agent-passport#417`](https://github.com/aporthq/agent-passport/pull/417) (not publicly readable),
 merged on 2026-10-09. Its canonical brief is
 `docs/prds/aport-task-delivery-workflow-integration.md` in that repository, with
 job identity `aporthq/agent-passport/aport-task-delivery-workflow-integration`.

package/docs/preparation.md

@@ -102,7 +102,7 @@ Official configuration references:
 Re-run native qualification when upgrading the CLI or adding tool capabilities.
 
 The recorded cross-repository integration handoff names
-[`aporthq/agent-passport#417`](https://github.com/aporthq/agent-passport/pull/417),
+[`aporthq/agent-passport#417`](https://github.com/aporthq/agent-passport/pull/417) (not publicly readable),
 with job identity `aporthq/agent-passport/aport-task-delivery-workflow-integration`.
 The handoff calls for reusing that continuation after the actual portable package
 is available. This document qualifies the preparation boundary; it does not

package/docs/releasing.md

@@ -1,9 +1,16 @@
 # Releasing
 
 The package name is `@uchibeke/gallivant`; the executable is `gallivant`. The repository is
-`uchibeke/gallivant`. Before announcing a version, confirm npm publication and a
-passing consumer smoke check. A public GitHub repository alone does not make the
-npm command work.
+`uchibeke/gallivant`. The first public release, 0.2.0, was published on
+2026-10-19; `npm view @uchibeke/gallivant version` reports the current one.
+Before announcing a version, confirm its npm publication and a passing consumer
+smoke check. A public GitHub repository alone does not make the npm command work.
+
+The README and installation guide lead with
+`npx --yes @uchibeke/gallivant init --harness codex`, which runs whatever
+version npm serves as `latest`. When `init` or another documented command changes
+behavior, release the version that carries it before, or together with, the
+documentation that describes it.
 
 ## One-time launch setup
 
@@ -21,14 +28,13 @@ npm command work.
    Enable the `main` ruleset with pull requests, the four portability checks,
    and protection against deletion and force pushes. Read back both settings:
    merely referencing `environment: npm` in YAML does not create protection.
-3. For a package that does not exist yet, arrange the initial npm publication
-   credential with the npm owner. If needed, set a short-lived granular
-   `NPM_TOKEN` in the protected `npm` environment, scoped as narrowly as npm
-   permits. Never put it in the repository or a PR.
-   A local `npm login` is not authentication for GitHub Actions. Do not publish
-   the release locally to bypass this setup: the release's provenance is
-   generated in supported CI, not by the developer's terminal.
-4. Once the package exists, configure its npm trusted publisher for GitHub owner
+3. The initial publication used a short-lived granular `NPM_TOKEN` in the
+   protected `npm` environment, scoped as narrowly as npm permits. Never put a
+   token in the repository or a PR. A local `npm login` is not authentication
+   for GitHub Actions. Do not publish a release locally to bypass this setup:
+   the release's provenance is generated in supported CI, not by the
+   developer's terminal.
+4. With the package published, configure its npm trusted publisher for GitHub owner
    `uchibeke`, repository `gallivant`, workflow `release.yml`, environment `npm`.
    Permit direct `npm publish`, which is what this workflow runs. Validate a new
    trusted publisher within two days or recreate it after expiry; configure it
@@ -56,8 +62,8 @@ npm whoami --registry=https://registry.npmjs.org
 npm view @uchibeke/gallivant version --registry=https://registry.npmjs.org
 ```
 
-An absent package is expected before the first publication. An absent `npm`
-environment or disabled branch protection is unfinished release setup.
+`npm view` should report the published version. An absent `npm` environment or
+disabled branch protection is unfinished release setup.
 
 ### Staged publishing is a different workflow
 
@@ -87,8 +93,8 @@ Choose one trigger:
 
 ```sh
 # From an up-to-date main checkout; replace the example with package.json's version.
-git tag -a v0.2.0 -m 'Release 0.2.0'
-git push origin v0.2.0
+git tag -a v0.2.1 -m 'Release 0.2.1'
+git push origin v0.2.1
 
 # Or dispatch against main; the workflow uses main's package version.
 gh workflow run release.yml --repo uchibeke/gallivant --ref main
@@ -113,7 +119,8 @@ original workflow rather than dispatching newer `main` with the old version.
 
 ```sh
 npm view @uchibeke/gallivant version dist.integrity dist.attestations
-npm install -g @uchibeke/gallivant
+npx --yes @uchibeke/gallivant --version     # the command the README leads with
+npm install -g @uchibeke/gallivant          # the documented persistent option
 gallivant --version
 gallivant --help
 ```
@@ -124,9 +131,9 @@ in a clean project that installed the released version to verify registry
 signatures and available provenance. Metadata presence alone is not signature
 verification; see [npm provenance verification](https://docs.npmjs.com/generating-provenance-statements/#verifying-provenance-attestations).
 
-After publication is verified, update the README and installation guide to put
-the tested npm install command first and remove the first-release-pending notes
-(including this page). Keep the source-install alternative.
+After publication is verified, check that the README's `npx` command and the
+installation guide match the behavior of the released version, and keep the
+source-install alternative for contributors.
 
 Use a clean test account/home and the [getting-started guide](install.md) for one
 small real PR. Confirm implementation, feedback-driven continuation, CI and the
@@ -135,6 +142,8 @@ paid-provider access. Recheck anonymous GitHub access and all README links.
 Announcement drafts are in [launch.md](launch.md).
 
 For local validation without publishing: `npm run lint`, `npm test`, and
-`npm run test:install`. The last command packs and installs under a disposable
-directory, exercises setup and PRD commands outside the source tree, and imports
-every declared module export. It makes registry requests but no model calls.
+`npm run test:install`. The last command packs the tarball under a disposable
+directory, runs the README's `npx` setup command against it from a fixture
+repository with a throwaway home, installs it as a dependency, exercises PRD
+commands outside the source tree, and imports every declared module export. It
+makes registry requests but no model calls.

package/docs/task-delivery.md

@@ -12,7 +12,7 @@ must enforce the same authorization, ownership, persistence and recovery
 contracts. In the APort integration, APort owns publication and the host
 responsibilities above. Its existing
 `aporthq/agent-passport/aport-task-delivery-mcp` job produced merged
-[PR #414](https://github.com/aporthq/agent-passport/pull/414); reuse that integration.
+[PR #414](https://github.com/aporthq/agent-passport/pull/414) (not publicly readable); reuse that integration.
 The M5/M6 notes below preserve that integration's milestone evidence and gates;
 they do not certify another host or supply a public UI, database or competing
 runner.

package/lib/commands/doctor.mjs

@@ -39,6 +39,18 @@ export const CONTROL_PLANE = ["~/.claude", "~/.codex", "~/.config/opencode", "~/
 // are checked separately. Public-only OAuth must not require private repo access.
 export const hasRepositoryWriteScope = scopes => scopes === null || String(scopes).split(/[\s,]+/).some(scope => scope === "repo" || scope === "public_repo");
 
+/** A missing OAuth header is valid for fine-grained tokens; a failed lookup is not evidence of that absence. */
+export async function repositoryWriteScopeCheck(gh, credential) {
+  let scopes;
+  try { scopes = await gh.tokenScopes(); }
+  catch (error) {
+    const detail = scrubbed(String(error?.message || error), credential?.token).split("\n")[0];
+    return fail(`could not verify ${describeCredential(credential)} repository write scope: ${detail}`, "retry after restoring GitHub API access; run gallivant doctor before starting a task");
+  }
+  if (!hasRepositoryWriteScope(scopes)) return fail(`${describeCredential(credential)} has no repository write scope (${scopes})`, "for public repositories use public_repo, or put a selected-repository fine-grained PAT with Contents: write in github_token_file");
+  return ok(scopes === null ? "fine-grained" : `classic (${scopes})`);
+}
+
 /**
  * What a local passport is missing, as a list of sentences, empty when it is sound. Exported because it is the only
  * thing in `doctor` that speaks for the guardrail the docs promise, so it is worth testing on its own.
@@ -160,12 +172,9 @@ export async function doctor({ home = gallivantHome(), send = false, probe = fal
     if (!r.ok) return r.fix
       ? fail(`could not verify ${describeCredential(runCredential)} with GitHub: ${r.detail}`, r.fix)
       : fail(`${describeCredential(runCredential)} is rejected by GitHub: ${r.detail}`, runCredential.source === SOURCES.file ? `the token in ${contract(p)} is expired or revoked; paste a new one` : "gh auth login, or export a valid GH_TOKEN");
-    const scopes = await gh.tokenScopes().catch(() => null);
-    const kind = scopes === null ? "fine-grained" : `classic (${scopes})`;
-    // `repo` or public-only `public_repo` permits writes. A fine-grained PAT carries no scopes at all,
-    // so the absence of the header is not a finding; per-repo permissions are what the next check asks GitHub about.
-    if (!hasRepositoryWriteScope(scopes)) return fail(`${describeCredential(runCredential)} has no repository write scope (${scopes})`, "for public repositories use public_repo, or put a selected-repository fine-grained PAT with Contents: write in github_token_file");
-    return ok(`${describeCredential(runCredential)}, ${kind}, acts as ${r.detail}`);
+    const scope = await repositoryWriteScopeCheck(gh, runCredential);
+    if (!scope.ok) return scope;
+    return ok(`${describeCredential(runCredential)}, ${scope.detail}, acts as ${r.detail}`);
   });
   // Push rights per repo, asked of GitHub. Scopes say what a token is allowed to attempt; `permissions.push` says
   // whether this identity may write to this repository, which is the thing a run actually needs and the thing an