@uchibeke/gallivant 0.2.0 → 0.3.0

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**. Check npm's current release with
+`npm view @uchibeke/gallivant version`. Source changes on `main` reach this
+command through a [versioned release](releasing.md); setup itself does not publish
+a package.
+
+`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.
 
-## 2. Sign in and create config
+### Install from source
+
+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,10 +299,10 @@ 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;
+spending limits. The default `max_iterations` is 60 automatic fix rounds;
 `max_budget_usd` defaults to 5 and gives Claude a native per-run dollar cap.
 Other local harnesses do not enforce an equivalent dollar cap. Use your provider's
 spend controls and review [budget semantics](config.md) before unattended work.
@@ -271,9 +331,9 @@ gallivant task start TASK_ID --revision REVISION --run
 gallivant start
 ```
 
-Alternatively, add `--run` to the original `task` request to authorize
-implementation as soon as preparation and any clarifications succeed. The task
-service starts the daemon; `gallivant start` with no path also opens the dashboard.
+Preparation always returns for review, including when the original request
+contains `--run`. Approve the visible ready revision with the separate start
+command above. The task service starts the daemon; `gallivant start` with no path also opens the dashboard.
 Read [task operations](tasks.md) for selected context, revisions, recovery and costs.
 
 ### From a written brief
@@ -336,3 +396,13 @@ Watch `gallivant status` after the start run ends: the entry moves from `impleme
 | `<worktrees>/<repo>/<prd>` | one partial clone per PRD; durable until you delete it |
 
 Override the home directory with `GALLIVANT_HOME` to run a second instance.
+
+## Bitbucket-only first run
+
+Bitbucket setup uses Node, Git, a selected local harness, an account API token,
+and explicit reviewer or no-reviewer policy. It does not require `gh` sign-in.
+Follow the [first-run commands](bitbucket-review.md#first-setup-including-a-checkout-with-no-existing-configuration),
+including separate SSH and API credentials when using SSH Git. Setup checks
+transport access; a live public repository run has reached ready with explicit
+no-reviewer policy. Independent review and a clean Linux installation have not
+been qualified. Check `gallivant doctor` before starting your own repository.

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/network-recovery.md

@@ -1,5 +1,14 @@
 # Network failures and recovery
 
+The coordinator normally retains a successful local provider health check for
+five minutes, so a long coordinator cycle does not immediately expire it. A due,
+pending, failed or timed-out check still fences dispatch. An explicit
+`execution.progressMs` setting controls this interval and remains authoritative.
+Provider readiness refreshes on its own timer while a long coordinator cycle
+is still processing. A pending or failed refresh continues to block dispatch.
+Messages and resume requests remain queued while a readiness check is pending;
+an actual failed check still reports failure for the operator to repair.
+
 `ENOTFOUND` means a hostname lookup failed. `EAI_AGAIN` indicates a temporary
 resolver failure. Neither proves that a provider is down, credentials expired,
 or APort denied a tool call. DNS can affect one hostname while other sites work.

package/docs/openai-agents.md

@@ -85,7 +85,8 @@ entry, prepare and inspect a brief first, then follow the returned next action:
 ```sh
 gallivant task "Document the existing test commands in CONTRIBUTING.md. Change documentation only." \
   --harness openai-agents --verify 'git diff --check'
-# Add --run to authorize implementation once the brief passes readiness.
+# Review the ready draft, then substitute its returned task ID and revision:
+gallivant task start TASK_ID --revision REVISION --run
 ```
 
 Natural-language intake uses the selected provider's versioned preparation
@@ -414,7 +415,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/prd.md

@@ -76,6 +76,27 @@ These keys beyond `status` and `harness` are read if present:
   editing a document it was handed, and the list is part of the contract: adding or removing a file stops the entry
   the way an edited criterion does. See [config.md](config.md#files-a-brief-carries-sources) for how it differs from
   `context_paths`.
+- `publish_files` is an optional list of **exact output files** that would otherwise match the task-artifact policy:
+
+  ```yaml
+  publish_files:
+    - docs/audit/requested-security-report.md
+    - docs/evidence/export-dialog.png
+  ```
+
+  Use it only for reports, evidence or carried documents the operator explicitly wants in the PR. It does not list
+  ordinary implementation files or tests. No globs, directories, absolute paths or more than 100 entries are accepted.
+  The saved, approved brief supplies these exceptions; editing the session's copy cannot grant permission. Changing
+  the list changes the contract and uses the normal `prd-changed` repair/approval flow.
+
+  Task work logs, session transcripts, scratch files, audit chronology and review/handoff notes belong outside Git.
+  Create scratch space with `mktemp -d`; put concise verification results in the PR receipt. Keep lasting project
+  documentation and release/rollback instructions concise. The commit hook and final remote PR-diff check reject
+  conventional work-artifact paths (including `docs/audit/`, `docs/evidence/`, `docs/verification/`, `WORK_LOG.md`,
+  `NOTES.md`, and carried `sources`) unless listed here. Deletions remain allowed so an existing PR can be cleaned.
+  Required image evidence must remain committed at its explicitly approved paths; deleting it would invalidate review.
+  This is a path hygiene check, not a semantic content scanner: do not rename work logs to evade it.
+
 - `context_paths` gives this one brief read access to directories outside its checkout, added to whatever
   `config.json` already lists rather than replacing it. Comma-separated, or a `[a, b]` list:
 
@@ -128,7 +149,7 @@ file in your checkout are two files, and until this existed nothing compared the
 the run finished against criteria nobody was asking for and the PR arrived satisfying a document that had changed.
 
 So the two are compared, and what happens depends on what you changed. The comparison is in the contract's own terms:
-the acceptance criteria, Verify commands, `harness`, `context_paths`, `sources`,
+the acceptance criteria, Verify commands, `harness`, `context_paths`, `sources`, `publish_files`,
 and the **Coordinator delivery contract** when present. The ownership section
 keeps a natural-language publication instruction separate from provider work.
 It is validated and fingerprinted too; malformed edits cannot be silently ignored.
@@ -138,7 +159,7 @@ request bytes remain exact.
 | What you changed | What happens |
 |---|---|
 | Anything outside those contract fields: the Problem prose, a reworded story, a new Out of scope bullet | Nothing stops. The snapshot follows your edit so later prompts carry your current wording, the log says it happened, and you are not told. Stopping a run to ask about a typo fix would be worse than useless. |
-| A criterion, a Verify command, the harness, `context_paths`, `sources` or coordinator delivery ownership | The entry stops with `prd-changed` before the gate runs, and `gallivant why` names each difference. |
+| A criterion, a Verify command, the harness, `context_paths`, `sources`, `publish_files` or coordinator delivery ownership | The entry stops with `prd-changed` before the gate runs, and `gallivant why` names each difference. |
 | The ORDER of two criteria, without changing a word of either | Also `prd-changed`. Criteria are numbered by position, and the receipt on the open PR attests `ac-1` and `ac-2` by those numbers, so swapping two of them leaves the receipt attesting each criterion with the other's evidence. |
 | The file no longer passes the contract | `prd-illegal`. Fix the file and `gallivant ready` it again; it cannot become the brief the gate judges as it stands. |
 | The file is gone from your checkout | `prd-gone`. Restore it, or `gallivant remove` the entry. |

package/docs/preparation.md

@@ -16,7 +16,7 @@ Preparation and implementation are separate capabilities:
 | Claude Code | Tools disabled | Local checkout |
 | Codex | Isolated native profile, Codex 0.160.0+ | Local checkout |
 | OpenAI Agents API | Text only, no tools or environment | Hosted sandbox |
-| Gemini CLI, OpenCode, Goose | Unavailable; use `new` → `ready` → `start` | Local checkout |
+| Gemini CLI, OpenCode, Goose | Unavailable through the harness; the configured [model route](task-profiles.md#planner-routes) can draft, or use `new` → `ready` → `start` | Local checkout |
 | Codex Cloud | Unavailable | New dispatch blocked on environment/repository verification |
 
 An adapter's presence does not prove the configured account can use its selected
@@ -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/release-qualification.md

@@ -16,7 +16,7 @@ the accessible actual demo recording URL. Do not substitute generated images.
 
 ```sh
 npm run release:preflight -- --config "$PACKAGE_CONFIG" --setup "$SETUP_EVIDENCE"
-npm run release:package -- --config "$PACKAGE_CONFIG" --out "$RELEASE_DIR" --core-version 0.2.0 --source-commit "$SOURCE_COMMIT" --deployment "$DEPLOYMENT_RECORD" --evidence "$LIVE_EVIDENCE"
+npm run release:package -- --config "$PACKAGE_CONFIG" --out "$RELEASE_DIR" --core-version 0.3.0 --source-commit "$SOURCE_COMMIT" --deployment "$DEPLOYMENT_RECORD" --evidence "$LIVE_EVIDENCE"
 npm run release:validate -- --out "$RELEASE_DIR"
 ```
 

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
 
@@ -75,10 +81,25 @@ GitHub release. Until then, use the documented CI bootstrap credential route.
 
 ## Release a version
 
+Merging a PR to `main` does not bump the version, create a tag or publish a
+package. There is no scheduled release or automatic version-bump PR. Prepare a
+version-bump PR, wait for its checks, merge it, then trigger the workflow and
+approve the protected `npm` environment. A newer source checkout with an already
+published version cannot refresh that npm version: the tag and tarball guards
+deliberately require the original commit and bytes.
+
 Update the version with `npm version patch --no-git-tag-version` (or `minor`),
 which updates `package.json` and `npm-shrinkwrap.json`. Include release notes in
 the PR and merge it after CI passes. Do not bump the version for a retry.
 
+Update `CORE_VERSION` in `lib/task_delivery_contract.mjs` to the same version.
+For a minor release, review and update its pre-1.0 compatibility window, the
+handshake tests and the packaging examples in [task delivery](task-delivery.md)
+and [release qualification](release-qualification.md). Other minor versions
+require explicit migration; keep the exact artifact pin and wire-schema guards.
+Run the full portability suite, including plugin packaging and release assembly,
+before publishing: the npm install smoke alone does not exercise those builders.
+
 The workflow follows the guardrails repository's pattern: validate the release
 ref, test before publishing, and permit recovery without replacing published
 versions. This single-package project does not need its multi-registry dispatcher.
@@ -87,8 +108,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.3.0 -m 'Release 0.3.0'
+git push origin v0.3.0
 
 # Or dispatch against main; the workflow uses main's package version.
 gh workflow run release.yml --repo uchibeke/gallivant --ref main
@@ -113,7 +134,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 +146,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 +157,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,14 +12,14 @@ 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.
 
 ## Installed exports
 
-Core `0.2.0`, task schema `1`, execution schema `1`, operation schema `1`.
+Core `0.3.0`, task schema `1`, execution schema `1`, operation schema `1`.
 The candidate digest comes from the emitted `runtime.json`/`manifest.json`;
 pin the artifact produced from the eventual human-merged commit, not this branch.
 
@@ -218,7 +218,7 @@ Before wake-up, migrate/pin the exact runtime artifact. Supply the emitted
 The coordinator refuses a different active-job digest. Compatible patches keep
 task/provider/brief identities; drain jobs before staging a different artifact.
 No running code is silently upgraded. The public API's pre-1.0 compatibility
-window is `0.2.x`, with operation/task/execution wire schemas all `1`; other
+window is `0.3.x`, with operation/task/execution wire schemas all `1`; other
 versions need migration.
 
 The portable contracts/views/wake envelope have no Node dependencies. The complete
@@ -267,9 +267,9 @@ changes and remain development fixtures:
 npm ci --ignore-scripts
 node bin/package-plugin.mjs --config /private/aport-package.json --validate-public
 npm run package:plugin -- --config /private/aport-package.json --out /private/candidate \
-  --core-version 0.2.0 --source-commit <40-character-merged-commit>
+  --core-version 0.3.0 --source-commit <40-character-merged-commit>
 # For development only, add --internal; keep fixture:true in the config.
-npm install --ignore-scripts --prefix /private/candidate-runtime /private/candidate/uchibeke-gallivant-0.2.0.tgz
+npm install --ignore-scripts --prefix /private/candidate-runtime /private/candidate/uchibeke-gallivant-0.3.0.tgz
 node /private/candidate-runtime/node_modules/@uchibeke/gallivant/bin/task-delivery-state.mjs check \
   --home /durable/preview --manifest /private/candidate/runtime.json
 node /private/previous-runtime/node_modules/@uchibeke/gallivant/bin/task-delivery-state.mjs backup \