@bridge_gpt/mcp-server 0.2.68 → 0.2.70

package/docs/EPIC-IMPLEMENTER-INSTALL.md

@@ -1,867 +1,12 @@
-# Epic Implementer install guide (for agents)
-
-This guide is for a coding agent (Claude Code, Cursor, or similar) working in a
-customer repository. Your human said "set up the Epic Implementer" and does not
-know how. Follow the steps below in order. Each step says why it matters, the
-exact command, how to check it worked, what to do if it fails, and whether you
-must ask the human first.
-
-Bridge copies this file into every installed project at
-`docs/install/epic-implementer-install.md`. The same text ships in the npm
-package as `docs/EPIC-IMPLEMENTER-INSTALL.md`. For the full reference, read
-`docs/EPIC-IMPLEMENTER.md` inside the `@bridge_gpt/mcp-server` package.
-
-In this guide, `<launcher>` means `npx -y @bridge_gpt/mcp-server`. Always keep
-the `-y`. Without it, `npx` stops to ask whether to install the package.
-
----
-
-## 0. Rules for you, the agent
-
-1. **Read first, write later.** Run every read-only check in a step before any
-   step that writes.
-2. **Ask before any write or push.** Ask the human before you install a GitHub
-   App, open a pull request, create a secret, change an admin setting, or push a
-   branch. Say what will change and why.
-3. **Replace every placeholder before you run a printed remedy.** The tools now
-   print complete commands, with the `npx -y @bridge_gpt/mcp-server` prefix and
-   every required flag. Some carry a placeholder that only a real value can fill:
-   `<@org/team|@user>` (the one reviewer of the workflow file; Bridge cannot infer
-   it) and `<check-name>` (the exact name of a CI check this repository requires;
-   repeat `--required-check` for more than one). Older tool versions printed
-   shorthand; the table in [§12](#12-troubleshooting-and-known-wrong-remedies)
-   maps it to the full command.
-4. **Stop at human-only access.** Some steps need a browser, a GitHub admin, or
-   the Bridge admin panel. Stop, say exactly what the human must do, and wait.
-5. **Interactive commands go to the human.** `install`, `connect-github`, and
-   both `install conductor` forms ask questions on a terminal. A shell you run
-   has no terminal (no TTY), so the answer is always "no":
-   - `install conductor` prints `Aborted` and **exits `0`**. The exit code does
-     not tell you it failed.
-   - `install conductor --merge-workflow` prints `consent_declined` and exits `1`.
-
-   Ask the human to run these commands in their own terminal, from the
-   repository root. Then read what they paste back.
-6. **Never write a secret into the repository.** No token, API key, or merge
-   credential goes into a tracked file, a command argument you print, or a
-   commit.
-7. **Keep notes.** Record which step you finished. Step 5 asks the human to
-   restart the MCP client, which may end this session.
-
-## 1. What you are setting up
-
-The Epic Implementer drives a multi-ticket epic from an approved plan to merged
-pull requests. It cuts an `epic/<EPIC-KEY>` branch, hands each child ticket to
-an agent on this machine, waits for CI and code review on each child PR, and
-merges each child PR into the epic branch. A person merges the final
-integration PR into the default branch.
-
-By default a run with two or more tickets is **unattended**: it merges child
-PRs on its own. `--attended` is the opt-out: the run then has no permission to
-merge by itself.
-
-Both kinds of run still need CI and code review to actually run on child PRs
-into `epic/<EPIC-KEY>`, or every ticket waits forever. Unattended runs also need
-the server to confirm the setup (steps 6 to 9). Attended runs skip that
-confirmation, but have their own launch path ([§11c](#11c-attended-runs)).
-
-## 2. Preflight checklist (read-only)
-
-**Why:** the executor that runs the jobs lives on this machine. It refuses to
-start without certain tools, and several later steps need `gh` and push rights.
-
-**Ask first?** No. Everything here only reads.
-
-| Check | Command | Pass when |
-|---|---|---|
-| Node.js 18 or newer | `node --version` | `v18` or later. The optional git hooks want an even LTS line, `v20` or later. |
-| Operating system | `uname -s` | `Darwin` or `Linux`. The executor does not run on Windows. |
-| git | `git --version` | Prints a version. |
-| GitHub CLI, logged in | `gh auth status` | Logged in to github.com. |
-| Claude Code CLI | `claude --version` | Prints a version. The human must also be logged in to `claude`. |
-| Worktrunk | `wt --version` | Prints a version. The executor refuses to start without it. |
-| Push rights | `gh repo view --json viewerPermission -q .viewerPermission` | `WRITE`, `MAINTAIN`, or `ADMIN`. Setup pushes an `epic/<EPIC-KEY>` branch with the human's own git. |
-| No retired variables | The command below | Prints nothing. |
-
-Retired-variable check (prints names only, never values):
-
-```bash
-env | grep -E '^(BAPI_CONDUCTOR_|CONDUCTOR_(NODE_PATH|DEAD_MAN_ONLY|DEADMAN_CHANNEL_TYPE|DEADMAN_DESTINATION_REF)=)' | cut -d= -f1
-```
-
-These are old Epic Implementer variable names. If any is set, every
-`<launcher>` command exits `1` and lists each old name with its new one. Show
-the names to the human and ask them to rename or remove them in their shell
-profile, then open a fresh shell.
-
-If a tool is missing, stop and tell the human which one. Do not install tools
-yourself without asking.
-
-Then run the three Bridge diagnostics. All three only read:
-
-```bash
-npx -y @bridge_gpt/mcp-server doctor
-npx -y @bridge_gpt/mcp-server epic-implementer doctor
-npx -y @bridge_gpt/mcp-server epic-implementer readiness --json
-```
-
-- `doctor` checks the base install: repository identity, credentials, server
-  connection, and whether the repository is indexed.
-- `epic-implementer doctor` checks this machine: the local ledger, git hooks,
-  and the merge credential. It briefly starts a headless `claude` probe to check
-  that permission denials are enforced.
-- `epic-implementer readiness --json` combines all of these with the server's
-  view. It is the one report you will re-run after every step. It always exits
-  `0`, even when things fail, so read the JSON.
-
-**How to read `readiness --json`:** look at the `checks` array. Each entry has an
-`id` (for example `server.github-credentials`), a `status`, a `label`, and
-sometimes a `detail` and a `remediation`.
-
-- `pass` — fine.
-- `warn` — works but degraded. Note it.
-- `fail` — not met, **or could not be checked**. Read the `detail` to tell which.
-- `skip` — does not apply here.
-
-Rows whose `id` starts with `plane.` only matter when the human runs their own
-Bridge API server. Against the hosted service you can ignore them. The
-`server.executor-readiness` row may fail before the first run. That is fine:
-`drive-epic` starts an executor for each run by itself.
-
-Map each failing row to a step below. Do not run the `remediation` text as a
-command; see rule 3.
-
-## 3. Base install (only if Bridge is not installed yet)
-
-**Why:** every Epic Implementer command needs the repository's Bridge identity
-and API key.
-
-**Check first:** if `.bridge/config` exists and `doctor` reports the credential
-and server connection as fine, skip this step.
-
-**Ask first?** Yes. It is interactive and writes files.
-
-Ask the human to run this in their own terminal, from the repository root:
-
-```bash
-npx -y @bridge_gpt/mcp-server install
-```
-
-It asks for an email (new account) or a key or invite (existing account). It
-writes `.bridge/config`, the editor's MCP config, and the slash commands. It
-stores the API key outside the repository.
-
-**How credentials are found.** Every command looks for the API key in this
-order: the `BAPI_API_KEY` environment variable, then the file
-`~/.config/bridge/credentials.json` under the key `bapi:<repo_name>`. A key
-that lives only in the editor's MCP config is **not** visible to a shell you
-start, so rely on the credentials file.
-
-**The `repo_name` rule.** `repo_name` must match byte for byte everywhere:
-`.bridge/config`, the `BAPI_REPO_NAME` in the MCP config, the `bapi:<repo_name>`
-key, and any `--repo` flag. Never derive it from the folder or GitHub name. A
-hyphen where Bridge has an underscore gives a **403** that looks like a
-permissions problem. Read it:
-
-```bash
-grep '^repo_name' .bridge/config
-```
-
-**Check it worked:** re-run `npx -y @bridge_gpt/mcp-server doctor`. The identity,
-credential, and connectivity rows should pass.
-
-**If it fails:** a 403 almost always means a `repo_name` mismatch. A 401 means
-the key was rejected or rotated. Ask the human for a fresh key.
-
-## 4. Connect GitHub
-
-**Why:** the server watches CI and review through the Bridge GitHub App. Without
-App credentials, `drive-epic` refuses to start any run (`github_credentials`).
-
-**Check first:** in `readiness --json`, find `server.github-credentials`. If it
-passes, skip to the permission check below.
-
-**Ask first?** Yes. It opens a browser and installs a GitHub App.
-
-Ask the human to run, in their own terminal:
-
-```bash
-npx -y @bridge_gpt/mcp-server connect-github --repo <repo_name>
-```
-
-It opens the GitHub App install page. The human installs the App there, comes
-back to the terminal, and confirms the repository. No GitHub token is ever
-typed. If someone else administers the GitHub organization, use
-`connect-github --handoff --repo <repo_name>` instead. It prints a link to send
-to that admin. After they finish, run `connect-github --resume --repo <repo_name>`.
-
-**Permission check.** Find `server.github-actions-permission` in
-`readiness --json`. It should read `actions: write`. Without it, the Epic
-Implementer cannot re-run a flaky workflow (the rerun fails with a 403). This is
-a warning, not a blocker. If it shows a lower level, ask the human to check the
-Bridge GitHub App's installation in their GitHub settings and accept any
-pending permission request. If `detail` says the permission could not be
-checked, re-run readiness after credentials resolve.
-
-**Check it worked:** `server.github-credentials` passes.
-
-## 5. Bootstrap the repository: `install conductor`
-
-**Why:** this writes the repository's default Epic Implementer settings on the
-server: the required CI check each ticket must pass, merge approval, and the
-review policy. `drive-epic` refuses a repository without them
-(`supervisor_setup`, `supervisor_config`). With extra flags it also writes the
-`claude-review` workflow when you opt in to AI review, and it adds the Epic Implementer MCP
-tools to your editor config.
-
-The subcommand is still named `install conductor` (the Epic Implementer's old
-name). `install-bridge conductor` is the same command.
-
-**Ask first?** Yes. It asks several yes/no questions and writes to the server
-and to local files. It needs a real terminal.
-
-### 5a. Choose the required check
-
-The installer needs a **confirmed repository gate**: provider checks, local
-commands the executor runs, both, or none. Without gate flags it uses a gate
-already stored (an older `--required-check` setup counts), or it proposes one
-from the working tree and the provider's real check history and asks the human
-to confirm it. You may explain the proposal; you never confirm, clear, or write
-a gate. Read `docs/install/install-bridge-conductor-gate.md` first.
-
-`--required-check` is the common scripted form: it stores a confirmed provider
-gate. It must be the exact name of a CI check run that GitHub reports on child
-PRs into `epic/<EPIC-KEY>`. A name that never reports leaves every ticket
-waiting forever.
-
-- **Unattended runs (the default):** the name must be a job `name:` written
-  literally in `.github/workflows/epic-implementer-ci.yml` or
-  `.github/workflows/claude-review.yml` on the default branch. At approval the
-  server checks each required check against those two files. Any other name,
-  including a real check from another workflow, is refused as
-  `admission_evidence_unverifiable`. Use **`epic-implementer-ci / gate`**, the
-  gate job in the step 6 template.
-- **Attended runs only:** any real check name works, as long as that check runs
-  on pull requests into `epic/**`. List the names on a recent pull request:
-
-  ```bash
-  gh pr view <pr-number> --json statusCheckRollup \
-    | jq -r '.statusCheckRollup[] | .name // .context'
-  ```
-
-**Never use `claude-review` as a required check.** It is the review signal, not
-a test run. The review gate reads it separately.
-
-### 5b. Choose the review workflow values
-
-`.github/workflows/claude-review.yml` produces the review verdict the review
-gate waits for **when you choose AI review** (`verdict_protocol`). For unattended
-runs it must also emit two markers (`run-id:` and `Reviewed-SHA:`). This command
-writes a correct file when you choose AI review and pass **all three** of these
-flags. If one is missing, phase 3 prints a `skipped — …` line and writes nothing.
-Without AI review you can skip this section.
-
-| Flag | Value |
-|---|---|
-| `--allowed-bot` | The GitHub App bot whose PRs get reviewed. Child PRs are opened by the Bridge GitHub App. For hosted Bridge, use `bridge-gpt-ai-tools-for-sfcc[bot]`. A self-hosted Bridge uses its own App's `<app-slug>[bot]`. |
-| `--secret-name` | The **name** (not the value) of a GitHub Actions secret that holds a Claude Code OAuth token, for example `CLAUDE_CODE_OAUTH_TOKEN`. Upper-case letters, digits, and underscores only. |
-| `--branches` | The pull-request base branches to review: the default branch plus `epic/**`, for example `main,epic/**`. Child PRs target `epic/<EPIC-KEY>`, so without `epic/**` they are never reviewed. |
-
-Installation no longer defaults to `verdict_protocol`. If you omit
-`--review-policy`, the command assumes `repository_policy`: it scaffolds **no**
-Claude-review workflow and stores **no** repository review default. A new
-feature-branch run then gets `repository_policy` from the server at its first
-approval, when neither the run nor the repository sets a policy.
-
-AI review is an explicit opt-in. Pass `--review-policy verdict_protocol` to
-scaffold the workflow and store `verdict_protocol` as the repository choice.
-Passing any value explicitly stores it as the repository default. A run that was
-already approved without a stored policy is not changed: it still resolves to
-`verdict_protocol` and still needs the workflow.
-
-If the repository already has a `claude-review.yml`, the command asks before
-overwriting it. An older or hand-written file may lack the markers. Readiness
-tells you which marker is missing.
-
-### 5c. Run it
-
-Find the default branch:
-
-```bash
-gh repo view --json defaultBranchRef -q .defaultBranchRef.name
-```
-
-First ask the human to preview with `--dry-run`. The preview still asks one
-question (whether to use the shown Bridge API URL) because it reads from the
-server. It writes nothing:
-
-```bash
-npx -y @bridge_gpt/mcp-server install conductor \
-  --required-check "epic-implementer-ci / gate" \
-  --allowed-bot "bridge-gpt-ai-tools-for-sfcc[bot]" \
-  --secret-name CLAUDE_CODE_OAUTH_TOKEN \
-  --branches "main,epic/**" \
-  --dry-run
-```
-
-Replace `main` with the real default branch and adjust the other values. Then
-ask the human to run the same command **without** `--dry-run`, in their own
-terminal, from the repository root. It runs eight phases:
-
-1. A read-only doctor. It stops before any write if something fatal is missing.
-2. A preview of the server settings, then "Write the safe project-default
-   supervisor posture now?". If the change would remove an existing
-   requirement, it asks a second, separate question.
-3. The `claude-review` workflow (only with `--review-policy verdict_protocol` and the
-   three flags from 5b).
-4. **Tool visibility:** adds `epic_implementer` to `BRIDGE_MCP_PROFILE` in the
-   Bridge entry of `.mcp.json`, `.vscode/mcp.json`, and `.cursor/mcp.json`. It
-   only edits files that already have a Bridge entry. It never creates a file
-   and never touches Codex or Copilot config.
-5. Local observability: the optional local git hooks. Safe to decline.
-6. A plan check, only with `--epic-key` and `--plan-file`. Skip it for now.
-7. An executor service, only with `--executor-id`. Skip it: `drive-epic` starts
-   one for each run.
-8. A capability report and a final doctor.
-
-The last line is `complete` or `complete-with-manual-steps`. Before the first
-run, `complete-with-manual-steps` is normal, because no executor has been seen
-yet. Read the "Manual actions" list it prints.
-
-**After it finishes:**
-
-- The workflow file (phase 3) was only written locally. It lands in step 6.
-- **Restart the MCP client** (the editor or `claude` session). The server reads
-  its tool groups at startup, so `get_epic_snapshot` and `explain_run` appear
-  only after a restart. Save your notes first. After the restart, confirm those
-  two tools are listed. If they are not, check that the Bridge entry's
-  `BRIDGE_MCP_PROFILE` contains `epic_implementer`, for example
-  `core,epic_implementer`.
-
-**Check it worked:** in `readiness --json`, `server.supervisor-setup`,
-`server.supervisor-config`, and `server.supervisor-required-checks` pass.
-
-**If it fails:** if the output says `Aborted` right after the URL question, it
-had no terminal or the human answered no. Ask them to run it again in their own
-terminal. If phase 1 lists a fatal row, fix that row first (usually step 3 or 4).
-
-## 6. The two workflows, on the default branch
-
-**Why:** child PRs need CI and review that really run. For unattended runs, the
-server also reads two files from the **default branch**, at fixed paths, before
-it creates or approves a run. If either is wrong, it refuses with
-`repository_readiness_unconfirmed`. **No install command fixes this.** The files
-must be merged into the default branch.
-
-| File | Requirement |
-|---|---|
-| `.github/workflows/claude-review.yml` | Must emit the `run-id:` and `Reviewed-SHA:` markers. Written by step 5 with the three flags from 5b. |
-| `.github/workflows/epic-implementer-ci.yml` | Must exist and parse as a workflow. Nothing in the package writes it. Use the template below. |
-
-A different file name does not count, even if it runs the same tests.
-
-**Ask first?** Yes. You will create a branch and open a pull request.
-
-### 6a. The `epic-implementer-ci.yml` template
-
-This is a minimal, generic starting point. It runs the repository's tests on the
-Epic Implementer's pull requests and reports one check,
-`epic-implementer-ci / gate`. That name is the required check from step 5.
-`gh pr view --json statusCheckRollup` shows it as `epic-implementer-ci / gate`.
-The GitHub web page may show it as `epic-implementer-ci / epic-implementer-ci / gate`
-(workflow name, then job name). The required check is still
-`epic-implementer-ci / gate`.
-
-The Epic Implementer names each child branch `feature/<TICKET-KEY>` and the
-epic branch `epic/<EPIC-KEY>`. Child PRs go from `feature/…` into `epic/…`. The
-final integration PR goes from `epic/…` into the default branch. The template
-tests every same-repository PR from a `feature/` or `epic/` branch. To test only
-the Epic Implementer's tickets, you may narrow `feature/` to
-`feature/<PREFIX>-`, where `<PREFIX>` is the ticket prefix of the **child**
-tickets. Get that wrong and every child PR counts as out of scope, so the gate
-passes **without running any tests**.
-
-```yaml
-name: epic-implementer-ci
-
-on:
-  pull_request:
-    # The default branch (change main if yours differs) and the epic branches
-    # that child pull requests target.
-    branches: [main, "epic/**"]
-
-permissions:
-  contents: read
-
-# A new push cancels the run for the older head of the same pull request.
-concurrency:
-  group: epic-implementer-ci-${{ github.event.pull_request.number }}
-  cancel-in-progress: true
-
-jobs:
-  tests:
-    name: tests
-    # Same-repository feature/ and epic/ branches only.
-    if: >-
-      ${{ github.event.pull_request.head.repo.full_name == github.repository &&
-      (startsWith(github.event.pull_request.head.ref, 'feature/') ||
-      startsWith(github.event.pull_request.head.ref, 'epic/')) }}
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          # Test the exact head commit of the pull request.
-          ref: ${{ github.event.pull_request.head.sha }}
-          persist-credentials: false
-      # Add the repository's real setup steps here (language runtime,
-      # dependency install), then its real test command.
-      - name: Run tests
-        run: |
-          echo "Replace this step with the repository's test command."
-          exit 1
-
-  gate:
-    # This name IS the check-run name the done gate waits for. Keep it literal.
-    name: epic-implementer-ci / gate
-    needs: [tests]
-    if: ${{ always() }}
-    runs-on: ubuntu-latest
-    steps:
-      - name: Aggregate the result
-        env:
-          # Keep this identical to the tests job's condition.
-          IN_SCOPE: ${{ github.event.pull_request.head.repo.full_name == github.repository && (startsWith(github.event.pull_request.head.ref, 'feature/') || startsWith(github.event.pull_request.head.ref, 'epic/')) }}
-          TESTS_RESULT: ${{ needs.tests.result }}
-        run: |
-          if [ "$IN_SCOPE" != "true" ]; then
-            echo "Out-of-scope pull request: the gate passes without running tests."
-            exit 0
-          fi
-          if [ "$TESTS_RESULT" = "success" ]; then
-            echo "Tests passed."
-            exit 0
-          fi
-          echo "Tests concluded '$TESTS_RESULT', so the gate fails."
-          exit 1
-```
-
-Fill in the `tests` job with the repository's real test command. Find it in the
-existing CI workflows, `package.json` scripts, a `Makefile`, or the README. Ask
-the human if it is unclear. Do not leave the placeholder step: it fails on
-purpose.
-
-**Things to keep**, in this file and in `claude-review.yml`:
-
-- `if: ${{ always() }}` on the gate. Without it, a failed or skipped test job
-  would leave the gate check missing instead of red.
-- The gate is green only when the tests job concluded `success`. A skipped or
-  cancelled test job is never treated as a pass.
-- `persist-credentials: false` and the checkout of the pull request's head SHA.
-- **Static job names.** For unattended runs the server must read every job's
-  check name straight from both files. If either file has any of the following,
-  the server cannot read the names, and approval refuses every required check:
-  - a `strategy.matrix` on any job;
-  - a job-level `uses:` (a reusable workflow call). A `uses:` inside a step is
-    fine;
-  - a `${{ … }}` expression in any job id or job `name:`.
-
-  Put matrix or reusable-workflow jobs in a different workflow file if you need
-  them.
-
-### 6b. The `migration-guard` job (only for Alembic repositories)
-
-Check whether the repository has `alembic.ini` at its **root** on the default
-branch:
-
-```bash
-git fetch origin
-git ls-tree --name-only origin/<default-branch> alembic.ini
-```
-
-If that prints nothing, skip this part. If it prints `alembic.ini`, the server
-also requires a job whose id is exactly `migration-guard`, with a step that runs
-exactly `python scripts/check_alembic_migration_graph.py`. The repository must
-contain that script. It should fail when the Alembic revision graph has more
-than one head, a duplicate revision id, a missing parent, or a cycle. Add the
-job to `needs:` in the gate and fail the gate unless it concluded `success`. If
-the human does not want this, they can run attended instead.
-
-### 6c. Land both files
-
-1. Ask the human before you branch and push.
-2. Create a branch, for example `chore/epic-implementer-workflows`.
-3. Commit `.github/workflows/epic-implementer-ci.yml` and the
-   `.github/workflows/claude-review.yml` that step 5 wrote.
-4. Open a pull request into the default branch with `gh pr create`.
-5. Ask the human to review and merge it. Do not merge it yourself.
-
-**Secret the human must add** (repository Settings, then Secrets and variables,
-then Actions): a secret with the exact name you passed to `--secret-name`,
-holding a Claude Code OAuth token. The human can create one with
-`claude setup-token`. Never ask them to paste the token to you.
-
-**Check it worked:** after the merge, re-run `readiness --json`.
-`server.review-workflow`, `server.conductor-ci-workflow`, and
-`server.repository-workflow-readiness` should pass.
-
-**If it fails:** readiness names the missing item, for example "does not emit
-the Reviewed-SHA: marker". A detail saying Bridge "could not read" a file means
-the read failed, not that the file is wrong. Re-run readiness. If it keeps
-failing, contact Bridge support.
-
-## 7. Index the repository, after the workflows merge
-
-**Why:** `setup-epic` cuts `epic/<EPIC-KEY>` at the exact commit the code index
-was built from, not at the tip of the default branch. If that commit is older
-than the merge from step 6, the epic branch has no workflows. Then child PRs into
-it get no CI and no review, and every ticket waits forever. Each child ticket's
-plan also uses the index to find code.
-
-**Ask first?** No. Indexing runs on the server and changes nothing in the
-repository. It can take a while on a large repository.
-
-After the step 6 pull request has merged, run the `/parse-repository` slash
-command, even if the repository was indexed before. Then poll the
-`parse_repository` MCP tool with `action: "status"` until it reports completed.
-`doctor` also shows the indexing state.
-
-You will confirm the cut commit in [§11a](#11a-plan-the-epic), once a plan
-exists.
-
-**If it fails:** report the status message to the human. Do not start a real
-run until indexing has completed after the merge.
-
-## 8. Unattended prerequisites
-
-**Why:** an unattended run merges on its own, so three things are checked
-before a run is created. `--attended` skips them. `setup-epic` (which `/plan-epic`
-runs) and the `drive-epic` preview name each one differently.
-
-**Repository consent**
-- `setup-epic` refusal: `target_not_allowed`. `drive-epic` preview:
-  `unattended_consent`. Readiness row: `server.unattended-consent`.
-- It is **on by default**. The repository owner switches "Allow unattended Epic
-  Implementer runs" on the repository's Setup page in the Bridge admin panel.
-  Only a human can change it. If it is already on, contact Bridge support.
-
-**An escalation channel** (where alerts go when the run needs a person)
-- `setup-epic` refusal: `webhook_unverified`. `drive-epic` preview:
-  `unattended_notify_default`. Readiness row: `server.unattended-notify-default`.
-- The simplest channel is the email address on the Bridge account. It needs no
-  extra step when the account has one.
-- A webhook also works, but only through a `--policy-file` that sets
-  `notify.webhook_url`. `/plan-epic` and `/drive-epic-run` never pass a policy
-  file, so the webhook route needs the shell `drive-epic` ([§11c](#11c-attended-runs)
-  shows the command form). `notify.local_sink` does not count.
-
-  ```json
-  { "notify": { "webhook_url": "https://example.com/your-webhook" } }
-  ```
-
-  A policy file is the **complete** run policy, so keep it minimal. The server
-  tests the webhook when the run activates, so it must be reachable from the
-  internet.
-
-**The two workflows**
-- `setup-epic` refusal: `repository_readiness_unconfirmed`. `drive-epic`
-  preview: `repository_readiness`. Readiness row:
-  `server.repository-workflow-readiness`.
-- Finish step 6. The message names the missing file, marker, or job.
-
-**Readiness could not be read**
-- `setup-epic` refusal: `readiness_unreadable`.
-- The server did not report these facts. Retry. If it persists, contact Bridge
-  support.
-
-**Ask first?** Yes for anything that changes an account or admin setting. Only
-the human can change these.
-
-## 9. Merge credential and merge modes
-
-**Why:** in an unattended run, the executor on this machine merges each child PR
-into the epic branch with `gh pr merge`. In the default local mode it uses
-**only** the token in `BAPI_LOCAL_MERGE_TOKEN`. (A run in machine-user mode uses
-only `BAPI_MACHINE_MERGE_TOKEN` instead.) It never falls back to the human's `gh`
-login, `GH_TOKEN`, or `GITHUB_TOKEN`. Without the token, merges are refused. The
-diagnostics show this only as a warning (`conductor.merge-credential`), so it is
-easy to miss.
-
-**Ask first?** Yes. This concerns the human's GitHub credential.
-
-The executor inherits its environment from the process that runs `drive-epic`.
-So the variable must be set in the shell that launches `drive-epic`. If you use
-`/drive-epic-run`, that is **your own session's** environment, so the human must
-set it before starting the editor or `claude`.
-
-The simplest source is the human's own GitHub CLI token:
-
-```bash
-export BAPI_LOCAL_MERGE_TOKEN="$(gh auth token)"
-```
-
-To make it last, suggest the human add that exact line (the command, not the
-token value) to their shell profile, for example `~/.zshrc`, then open a new
-terminal and restart the editor. Never write the token value into any file, and
-never add it to the repository.
-
-If an executor is already running for a run, it will not see a newly exported
-value. It must be restarted from a shell that has it.
-
-**Check it worked:** `npx -y @bridge_gpt/mcp-server epic-implementer doctor`
-no longer warns about the merge credential. Run it from the same shell.
-
-### Optional: GitHub Actions merge mode
-
-Use this only if the human wants merges done by a GitHub Actions workflow
-instead of this machine. It applies only to a run whose policy file declares
-`"merge_execution_mode": "github_actions"`. Otherwise skip it.
-
-Ask the human to run, in their own terminal (it asks before writing):
-
-```bash
-npx -y @bridge_gpt/mcp-server install conductor --merge-workflow --codeowner <@org/team|@user>
-```
-
-`--codeowner` is required: the one GitHub user or team who must review changes
-to the merge workflow. Add `--dry-run` first to preview. The command writes
-`.github/workflows/epic-implementer-merge.yml` and two helper files, pushes a
-branch with the human's own git, and opens a pull request with their own `gh`.
-It never merges it.
-
-After the human merges that pull request, three manual steps remain. The human
-does all three:
-
-1. Create a repository Actions secret named `BAPI_API_KEY` holding the
-   repository's Bridge API key.
-2. Merge the rule from `.bridge/merge-workflow/CODEOWNERS.fragment` into the
-   active CODEOWNERS file. The fragment does nothing on its own.
-3. Add a default-branch rule that requires a pull request and code-owner review.
-   Until it exists, the workflow file is not protected.
-
-## 10. Verify
-
-**Before a plan exists**, use readiness only:
-
-```bash
-npx -y @bridge_gpt/mcp-server epic-implementer readiness --json
-```
-
-The `drive-epic` preview is not useful yet. Without a plan it only says
-`decision: stop`, with no reason, or a generic "not ready" refusal.
-
-**Done means:**
-
-- These rows pass: `server.supervisor-setup`, `server.supervisor-config`,
-  `server.supervisor-required-checks`, and `server.github-credentials`.
-- For unattended runs, these pass too: `server.unattended-consent`,
-  `server.unattended-notify-default`, and `server.repository-workflow-readiness`.
-  If a `server.admission-required-checks` row is present, it passes too.
-- `server.worker-present` and `server.single-transition-authority` pass. These
-  are the server's own health. If they fail, contact Bridge support.
-- `conductor.merge-credential` passes in the shell that will launch runs.
-- The `get_epic_snapshot` and `explain_run` tools are available.
-- Every other `fail` is explained, and the human accepted it.
-
-**After `/plan-epic` has written a plan**, preview the launch:
-
-```bash
-npx -y @bridge_gpt/mcp-server drive-epic <EPIC> --plan-file <path to epic-plan.dag.json> --dry-run --json
-```
-
-It changes nothing. Its `decision` is `create`, `attach`, `refuse`, or `stop`. A
-`refuse` carries `refusal.reason_id` and `refusal.remedy`. Map the `reason_id`:
-
-- `supervisor_setup`, `supervisor_config` — step 5.
-- `github_credentials` — step 4.
-- `unattended_consent`, `unattended_notify_default`, `repository_readiness` — step 8.
-- `remote-reconciler-not-live` — the Bridge server side. Contact Bridge support.
-- Anything else — read its `remedy`, then check the table in step 12 before you
-  run anything.
-
-Report to the human what passed, what failed, and what they still need to do.
-
-## 11. First run
-
-### 11a. Plan the epic
-
-`/plan-epic` needs an **existing epic ticket**. Run `/plan-epic <EPIC>` with its
-key, for example `SHOP-100`. Free text instead of a key gives no epic key, and
-no run can be created from it.
-
-It explores the code, splits the epic into child tickets, and asks the human to
-approve the split. It writes its files to `<docs_dir>/epic-plans/<slug>/`, where
-`<docs_dir>` is the docs folder the `ping` MCP tool reports (often `docs/tmp`).
-The plan file is `epic-plan.dag.json`.
-
-**Before the plan is approved, check every `ticket_key` in
-`epic-plan.dag.json`.** Each one must be a real ticket key. A placeholder such as
-`TBD-1` must not reach approval. If you see one, stop and create or link the
-real tickets first.
-
-**The last step of `/plan-epic` creates and approves an unattended run** (it
-runs `setup-epic` without `--attended`). For an attended run, see §11c before
-you reach that step.
-
-Before that step runs `setup-epic` for real, run its dry run and check the cut
-commit (plain output, not `--json`):
-
-```bash
-npx -y @bridge_gpt/mcp-server setup-epic --epic-key <EPIC> \
-  --plan-file <path to epic-plan.dag.json> --dry-run
-git fetch origin
-git ls-tree --name-only <sha from the "Cut:" line> .github/workflows/
-```
-
-The listing must include `claude-review.yml` and `epic-implementer-ci.yml`. If
-it does not, the index is older than the step 6 merge. Go back to step 7 and
-re-index first.
-
-**If `setup-epic` fails, what happened depends on where it failed:**
-
-- **`setup-epic REFUSED (<reason>)`** — a check before creation failed.
-  `target_not_allowed`, `webhook_unverified`, `repository_readiness_unconfirmed`,
-  and `readiness_unreadable` are all this kind. **Nothing was created.** Fix the
-  named item (step 8) and run it again.
-- **`The plan was NOT approved: …`** — the server refused at approval. By then
-  the run **was** created, the epic branch **was** cut, and the plan **was**
-  stored. The run waits in `planning`. The message always talks about unattended
-  consent, whatever the real cause. Ignore that wording and read the `Detail:`
-  line for `predicate` and `reason_code`:
-  - `admission_evidence_unverifiable` or `admission_evidence_denied` with
-    predicate `required_checks` — the required check is not a static job name in
-    the two workflow files (step 5a, and "Things to keep" in 6a).
-  - predicate `repository_readiness` — step 6.
-  - predicate `webhook` or `notify_webhook` — step 8, escalation channel.
-  - predicate `target_allowed` or `unattended_consent` — step 8, consent.
-  - any other predicate — report the `predicate` and `reason_code` to the human.
-
-  Fix the cause, then run the same `setup-epic` command again. It reuses the
-  existing run instead of creating a second one.
-
-### 11b. Drive an unattended run
-
-In Claude Code or Cursor:
-
-```text
-/drive-epic-run <EPIC> <path to epic-plan.dag.json>
-```
-
-It previews the launch, asks the human once, creates the run (or attaches to the
-one `/plan-epic` created), starts an executor, and watches the run to the end. It
-accepts no flags, so it cannot pass `--attended` or `--policy-file`. When it
-creates a run, the run must be unattended.
-
-From a shell, the same launch is:
-
-```bash
-npx -y @bridge_gpt/mcp-server drive-epic <EPIC> --plan-file <path to epic-plan.dag.json>
-```
-
-Add `--policy-file <policy.json>` for a webhook (step 8). Run it from the
-repository root, in a shell that has `BAPI_LOCAL_MERGE_TOKEN`. Always pass
-`--plan-file`. Without it, `drive-epic` searches only `docs/tmp/epic-plans/` (or
-`BAPI_DOCS_DIR`), which may not be where `/plan-epic` wrote. `drive-epic` starts
-a run-scoped executor in the background. Its log is
-`.bridge/executors/<run>.log`. The executor exits by itself when the run is done
-or abandoned.
-
-### 11c. Attended runs
-
-An attended run never merges by itself. It still needs a required check that
-really runs on child PRs into `epic/<EPIC-KEY>` (step 5a, attended branch), and a
-review verdict on those PRs (step 5b, `--branches` including `epic/**`).
-
-1. Plan with `/plan-epic <EPIC>`, but **do not let its last step run
-   `setup-epic`**. That step would create an unattended run whenever the
-   unattended prerequisites hold. Tell the human, and skip that step with their
-   agreement. If it has already run and refused with `setup-epic REFUSED`,
-   nothing was created and you can continue.
-2. Check every `ticket_key` in `epic-plan.dag.json`, as in §11a.
-3. Launch from a shell, from the repository root:
-
-   ```bash
-   npx -y @bridge_gpt/mcp-server drive-epic <EPIC> \
-     --plan-file <path to epic-plan.dag.json> --attended
-   ```
-
-`/drive-epic-run` cannot create an attended run.
-
-### 11d. Monitor
-
-- MCP tools: `get_epic_snapshot` (the full run state) and `explain_run` (why a
-  run or ticket is stuck). Both need the `epic_implementer` profile from step 5.
-- Notifications: `npx -y @bridge_gpt/mcp-server notifications --repo <repo_name> --run <EPIC> --follow`.
-- Quick health: `npx -y @bridge_gpt/mcp-server epic-implementer epic-status --epic-key <EPIC>`.
-
-### 11e. Stop and recover
-
-Always diagnose with the `explain_run` MCP tool first. Then apply one verb. Ask
-the human before any of them. Each runs as:
-
-```bash
-npx -y @bridge_gpt/mcp-server epic-implementer <verb> --epic-run-id <EPIC>
-```
-
-`--epic-run-id` takes the run id, or the epic key when the epic has exactly one
-active run.
-
-The two you will use most:
-
-| Verb | Use it to |
-|---|---|
-| `unpark --ticket-key <key>` | Send a parked (`needs_human`) ticket back into its gates once the cause is fixed. |
-| `stop-run` | Stop the run now: no new work, queued work cancelled. The record stays. |
-
-Advanced verbs. Use them only when `explain_run` points at them:
-
-| Verb | Use it to |
-|---|---|
-| `abandon-run` | End the run for good. **Terminal and irreversible.** |
-| `resume-run [--clear-quarantine]` | Resume a paused run. |
-| `adopt-current-head-and-unpark --ticket-key <key>` | Recover a ticket parked because someone pushed to its PR. |
-| `continue-child --ticket-key <key>` | Let a parked child carry on without resetting its attempt. |
-| `continuation-receipt --ticket-key <key>` | Check whether a `continue-child` request took effect (read-only). |
-| `resume-ci --ticket-key <key>` | Resume a child parked on a CI stop once CI is green. |
-| `dispatch-remediation --ticket-key <key> --context-file <path>` | Queue a repair job with your notes. |
-| `merge-child --pr <number>` | Merge the run's child PR through the shared merge service. |
-| `scope-reparse --scope-id <scope>` | Re-index the run's own index scope. |
-| `scope-catch-up --scope-id <scope>` | Replay merges the run's scope missed. |
-| `patch-policy --patch-file <path>` | Change part of the run's policy. |
-
-In Claude Code or Cursor, `/drive-epic-run` applies these for you within limits,
-and asks when it must.
-
-## 12. Troubleshooting and known-wrong remedies
-
-Current tools print complete commands. Replace any placeholder in them with a
-real value before you run them. Older tool versions printed the shorthand in the
-left-hand column below, which does not work as typed. Use the right-hand column
-instead.
-
-| Printed remedy | Problem | Run this instead |
-|---|---|---|
-| `install-bridge connect-github` | `install` accepts no such argument, and there is no `npx` prefix. | `npx -y @bridge_gpt/mcp-server connect-github --repo <repo_name>` (step 4) |
-| `install-bridge conductor` or `install conductor` with no flags | Missing the `npx` prefix and the required `--required-check`. | The full command in step 5c |
-| `install-bridge conductor --merge-workflow` (older tools) | Missing the `npx` prefix and the required `--codeowner`. | `npx -y @bridge_gpt/mcp-server install conductor --merge-workflow --codeowner <@org/team\|@user>`; replace the placeholder with the one reviewer (step 9) |
-| `npx @bridge_gpt/mcp-server install` | Missing `-y`, so `npx` stops to ask. | `npx -y @bridge_gpt/mcp-server install` (step 3) |
-| Any remedy for `repository_readiness_unconfirmed` that names an install command | No install command creates the workflows. | Step 6, then step 7 |
-| `The plan was NOT approved: this repository is no longer authorized for unattended runs` | Printed for every approval refusal, whatever the cause. | Read `Detail:` (§11a) |
-| `install conductor --executor-id <id> --repo-wide` for executor readiness | Not needed to launch. | Nothing. `drive-epic` starts an executor per run. |
-
-Other common problems:
-
-| Symptom | Cause | Fix |
-|---|---|---|
-| Every `<launcher>` command exits `1` with a list of variable names | Old Epic Implementer variable names are set. | Step 2, retired-variable check. |
-| `install conductor` prints `Aborted` and exits `0` | No terminal, or the human answered no. | Rule 5: the human runs it in their own terminal. |
-| `--merge-workflow` prints `consent_declined` | No terminal, or the human answered no. | Rule 5. |
-| 403 on any command | `repo_name` does not match byte for byte. | Step 3. |
-| `get_epic_snapshot` is not available | The MCP client was not restarted, or the profile lacks `epic_implementer`. | Step 5, "After it finishes". |
-| Child PRs get no CI or no review at all | The epic branch was cut before the workflows merged, or `--branches` / the CI trigger lacks `epic/**`. | Steps 5b, 6a, and 7. |
-| Tickets wait forever at CI | The required check name does not match a check that runs on child PRs. | Step 5a. Compare with `gh pr view <n> --json statusCheckRollup`. |
-| Tickets pass CI but no tests ran | A narrowed `feature/<PREFIX>-` does not match the child branches. | Step 6a. |
-| Approval refused: `admission_evidence_unverifiable` on `required_checks` | The required check is not a static job name in the two workflow files. | Steps 5a and 6a. |
-| Child PRs are never merged | `BAPI_LOCAL_MERGE_TOKEN` was not set for the executor. | Step 9. |
-| `merge_execution_ineligible` | The policy declares `github_actions` merge mode, but the merge workflow is missing or not ready. | Step 9, optional part. Or remove that line from the policy. |
-| `drive-epic` cannot find the plan | It searched `docs/tmp/epic-plans/` only. | Pass `--plan-file`. |
-| The reconciler or worker rows fail | The Bridge server side is not healthy. | Nothing to fix locally. Contact Bridge support. |
+# Epic Implementer install guide
+
+This file is now a short pointer. The one first-run guide is
+[epic-implementer/getting-started.md](./epic-implementer/getting-started.md).
+`npx -y @bridge_gpt/mcp-server install` writes that guide into your project at
+`docs/install/epic-implementer-install.md`. Run it again at any time to refresh
+the file.
+
+The first run has four steps: install, set up (`npx -y @bridge_gpt/mcp-server
+install conductor`), define the epic (`/define-tickets`), and launch it
+(`/drive-epic-run <EPIC>`). For every option and command, read
+[EPIC-IMPLEMENTER.md](./EPIC-IMPLEMENTER.md).