forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/docs/guides/MIGRATION.md

@@ -1,6 +1,6 @@
 # Migration Guide
 
-Use this guide when moving older Forge docs, habits, or installed scaffolding toward the v0.0.11 public framing.
+Use this guide when moving older Forge docs, habits, or installed scaffolding toward the v0.1.0-beta.6 public framing.
 
 ## What Changed
 
@@ -26,7 +26,7 @@ Use both entry points correctly:
 
 - `forge init` creates the `.forge/` adoption skeleton.
 - `forge setup` installs agent instructions, skills, harness files, local Beads compatibility, and optional setup material.
-- `forge setup --sync` is deprecated and retained only to remove old generated Beads/GitHub sync scaffolding when present.
+- `forge setup` also removes old generated Beads/GitHub sync scaffolding when present, with no flag needed.
 
 ## From Singular Agent Flags
 
@@ -39,8 +39,8 @@ forge setup --agents claude,cursor
 
 ## Version Labels
 
-- `0.0.11` is the package version for this public docs/readiness release.
-- `0.0.10` is the previous published package version.
+- `0.1.0-beta.6` is the current prerelease package version.
+- `0.1.0-beta.5` is the previous prerelease package version.
 - Internal labels such as `0.0.19` or `v3` describe roadmap slices or historical codenames. Do not present them as current package versions.
 
 ## Safe Upgrade Path

package/docs/guides/SETUP.md

@@ -59,10 +59,16 @@ bunx forge setup --agents claude cursor
 bunx forge setup --all --quick
 bunx forge setup --path ./my-project --agents codex --dry-run
 bunx forge setup --merge smart --agents claude,cursor
+bunx forge setup --agents claude --skills-only
 ```
 
 Use `--agents`, not `--agent`.
 
+Use `--skills-only` (or its `--no-hooks` alias) when you want the Forge skill
+suite without installing Git hooks, Forge-native hook scripts, or Claude/Cursor
+native hook enforcement. The default `forge setup` behavior is unchanged, and
+the option is safe to re-run.
+
 ## Agent Notes
 
 Forge currently supports Claude Code, Codex, and Cursor. Hermes support is planned.
@@ -75,31 +81,25 @@ Exact generated files depend on selected agents and existing repository files. U
 
 ## Issue Backend
 
-Forge issue commands (`forge ready`, `forge show`, `forge claim`, `forge create`, `forge close`) use the built-in **kernel** backend by default. No install or initialization is required — a fresh clone can track issues immediately.
+Forge issue commands (`forge ready`, `forge show`, `forge claim`, `forge create`, `forge close`) use the built-in **kernel** backend. No install or initialization is required — a fresh clone can track issues immediately.
 
-## Beads (Opt-Out Backend)
+## Migrating From Beads
 
-Beads (`bd`) is an optional opt-out backend for teams that prefer Dolt-backed sync internals. Select it (precedence, highest first) with `--issue-backend beads`, `FORGE_ISSUE_BACKEND=beads`, or `issueBackend: beads` in `.forge/config.yaml`; only then is `bd` required. Prefer the current Beads installer documented by Beads itself and this repo's toolchain docs. On Windows, avoid stale global install examples if they hit EPERM or shim issues; use the PowerShell installer path described in [Toolchain](../reference/TOOLCHAIN.md).
+Beads is no longer a selectable backend: `--issue-backend beads`, `FORGE_ISSUE_BACKEND=beads`, and `issueBackend: beads` are rejected, and `bd` is never required. An existing `.beads` directory is import-only state.
 
-When Beads is selected, health checks:
+Import it once, then use the kernel issue commands:
 
 ```bash
-bd doctor
-bd dolt status
-forge sync
+forge migrate --from beads
 ```
 
-If a feature worktree reports `database "forge" not found on Dolt server`, diagnose in the root checkout before changing issue state. This applies only to the Beads backend.
-
 ## Deprecated GitHub Sync Cleanup
 
-To remove old generated GitHub/Beads sync files from an existing install:
-
-```bash
-bunx forge setup --sync
-```
-
-`forge setup --sync` is deprecated. It now removes old generated Beads/GitHub sync files instead of creating new sync workflows. Future GitHub issue sync belongs to Forge Kernel/server authority, not Beads runtime files or metadata commits.
+`forge setup` removes old generated GitHub/Beads sync files from an existing
+install automatically — there is no flag for it. Only files whose content
+matches a known generated template are removed, so files you have edited
+yourself are left alone. Future GitHub issue sync belongs to Forge Kernel/server
+authority, not Beads runtime files or metadata commits.
 
 ## Validate Setup
 

package/docs/reference/COMMANDS.md

@@ -53,22 +53,25 @@ forge plan "<feature description>"
 forge dev [--issue-id <id>] [--phase red|green|refactor]
 forge validate
 forge ship <feature-slug> [<title>] [--dry-run]
-forge status [--full] [--json]
-forge prime [--budget N] [--json]
+forge status [-v|--verbose] [--full] [--json]
+forge prime [--budget N] [--json]   # deprecated alias for `forge status -v`
 forge orient [--budget N] [--json]
 forge recap <issue> [--budget N] [--json]
 forge recall [query] [--limit N] [--all] [--json]
 forge remember <note> [--tag <label>]... [--json]
 forge skill for "<situation>" [--json]
+forge skill eval <skill> --full --tier <30|100|300> [--json]
 ```
 
 - `forge plan` creates the implementation plan, kernel issue, and feature branch/worktree from a researched feature description; it prints the created issue id, branch name, and the suggested next command.
 - `forge dev` runs the TDD development stage with RED/GREEN/REFACTOR phase guidance; `--issue-id` scopes it to a specific kernel issue and `--phase` overrides auto-detection.
 - `forge validate` runs the validation orchestration pipeline (conflict markers, type check, lint, security, tests) with no arguments — see also `bun run check` under Validation And Packaging.
 - `forge ship` creates the pull request from validated feature work (wraps `gh pr create`); `--dry-run` previews without creating a PR.
-- `forge status` is the one-glance orientation command: where you are, what to run next, and your active work; `--full` also shows blocked/stale/recently-completed issues.
-- `forge prime` emits the bounded session-entry orientation envelope agents read at the start of a session; it now leads with a bounded (<=20-line) **live-state** block — current stage, claimed issue(s), ready-work count, enabled gates/rails, and one progressive-adoption nudge — collected best-effort (never blocks, honest fallbacks) before the deterministic orientation.
-- `forge skill for "<situation>"` is the deterministic intent-to-skill router: it reads the canonical skill catalog and prints the best-fit Forge skill(s) plus why, as the reasoning fallback for harnesses without a SessionStart hook that auto-injects the `using-forge` dispatch skill. `--json` emits the machine-readable routing result. The `forge skill` noun is structured so later waves can add `forge skill eval` / `forge skill scores`.
+- `forge status` is the one-glance orientation command: where you are, what to run next, and your active work; `--full` also shows blocked/stale/recently-completed issues. `-v`/`--verbose` prints the full session-entry briefing instead of the short pulse (git-status-v semantics).
+- `forge status -v` emits the bounded session-entry orientation envelope agents read at the start of a session; it leads with a bounded (<=20-line) **live-state** block — current stage, claimed issue(s), ready-work count, enabled gates/rails, and one progressive-adoption nudge — collected best-effort (never blocks, honest fallbacks) before the deterministic orientation.
+- `forge prime` is a **deprecated** alias for `forge status -v`. It still works and its stdout is byte-identical (session-start hooks consume it as context), but it prints a one-line deprecation notice on stderr.
+- `forge skill for "<situation>"` is the deterministic intent-to-skill router: it reads the canonical skill catalog and prints the best-fit Forge skill(s) plus why, as the reasoning fallback for harnesses without a SessionStart hook that auto-injects the `using-forge` dispatch skill. `--json` emits the machine-readable routing result.
+- `forge skill eval <skill> --full --tier <30|100|300>` runs the controlled four-arm behavioral protocol against the current PR head. It requires a live Kernel issue, an open PR at the exact local HEAD, and an isolated supported runtime. Tier 30 is instrumentation-only, tier 100 is the decision gate, and tier 300 is confirmation. Missing attribution, controls, usage, or reconstructable evidence returns `INCOMPLETE`; the command never authorizes merge.
 - `forge orient` emits bounded project orientation from deterministic source files (broader than `prime`, still token-budgeted via `--budget`).
 - `forge recap <issue>` is the issue-scoped counterpart to `forge orient`/`forge prime` — it summarizes a single issue from the same deterministic file assembly instead of the whole project. Requires an issue id; running it with no id (or `--help`) prints usage only.
 - `forge recall` retrieves project-memory notes from the kernel-backed memory store; omit `query` to list recent notes.

package/docs/reference/FORGE_KERNEL_STORAGE_MODEL.md

@@ -79,6 +79,10 @@ Forge Kernel local mode uses a builtin SQLite runtime driver. Driver selection m
 
 The selected driver must pass conformance checks for WAL mode, `busy_timeout`, transactions, WAL checkpointing, backup creation, and FTS5 before Forge claims real local SQLite authority behavior.
 
+Legacy claim contradictions are handled only by the explicit, human-gated
+[legacy claim repair](./LEGACY_CLAIM_REPAIR.md). The broker never starts or applies
+that repair automatically.
+
 ## Team Mode
 
 Team mode requires server authority.

package/docs/reference/INSIGHTS_RECAP.md

@@ -1,6 +1,6 @@
 # Insights And Recap
 
-`forge insights` and `forge recap` summarize recurring local workflow evidence from existing Forge and Beads state.
+`forge insights` summarizes recurring local workflow evidence from Kernel and Forge state. `forge recap <issue>` renders a bounded, issue-scoped orientation envelope from the same Kernel issue record.
 
 ## Commands
 
@@ -11,24 +11,24 @@ forge insights --min-count 2 --limit 5
 forge insights --json
 forge insights accept <candidate-id> --note "why this is useful"
 forge insights reject <candidate-id> --note "why this is noise"
-forge recap
-forge recap --json
+forge recap <issue>
+forge recap <issue> --json
 ```
 
-`--review-feedback` is a compatibility alias. In this MVP it reads Beads interactions and issue evidence; it does not infer external review-provider comments.
+`--review-feedback` is a compatibility alias. It reads kernel events and issue evidence; it does not infer external review-provider comments.
 
 ## Evidence Sources
 
-- `.beads/interactions.jsonl`: field changes and review/close outcome reasons.
-- `.beads/issues.jsonl`: tokenized issue titles and descriptions for themes, plus statuses and timestamps for recap context.
+- Kernel events (`kernel_events`, newest first): field changes and review/close outcome reasons. Interactions imported from a legacy Beads store are read here too, as `beads.interaction.<kind>` events.
+- Kernel issues (`forge issue list`): tokenized issue titles and descriptions for themes, plus statuses and timestamps.
 - `.forge/log.jsonl` and `.forge/audit.log`: optional audit event counts when present.
-- Beads-backed typed memory: accept/reject decisions are recorded through `lib/memory/typed-api.js`.
+- Typed memory: accept/reject decisions are recorded through `lib/memory/typed-api.js`.
 
 ## What It Can Infer
 
 - Repeated local workflow patterns.
 - Candidate follow-ups based on frequency, source diversity, and evidence count.
-- Recent issue activity and review outcome counts.
+- Recent issue activity counts.
 - Whether history is too sparse for a useful suggestion.
 
 ## What It Cannot Infer
@@ -48,16 +48,5 @@ Ranked candidates:
   Next: Review interaction evidence and consider a local workflow skill only if the pattern is still useful.
 Limitations:
 - Insights are local workflow signals, not proof of correctness.
-```
-
-```text
-Forge recap
-Issues: 260 total, 94 open, 166 closed
-Review outcomes found: 4
-Recent work:
-- forge-besw.12: forge insights --review-feedback PoC (Week 1 deliverable) [open]
-Insight candidates:
-- insight-interaction-status-closed-merged-and-verified: status changed to closed (merged-and-verified)
-Limitations:
-- Sparse Beads interactions or missing Forge audit logs reduce confidence.
+- Sparse kernel events or missing Forge audit logs reduce confidence.
 ```

package/docs/reference/INSTALL.md

@@ -155,6 +155,10 @@ installed and on your `PATH`:
 These are runtime prerequisites checked by `forge`'s own health checks; the
 installer does not install them for you.
 
+Using personal and work GitHub accounts together? See the optional
+[per-clone GitHub account guide](github-accounts.md). Ordinary single-account
+setup is unchanged.
+
 ---
 
 ## Uninstall

package/docs/reference/LEGACY_CLAIM_REPAIR.md

@@ -0,0 +1,112 @@
+# Legacy Claim Repair
+
+This is an explicit operator tool for the one-time pre-0.1.0 reconciliation of
+legacy Kernel claim rows. It is not called by setup, startup, broker migrations,
+claim acquisition, or any background process.
+
+## Safety contract
+
+- Always use an explicit, file-backed database path and a different backup path.
+- The observation time is mandatory and must be one canonical UTC instant. Reuse
+  that literal time for approval and apply.
+- Dry-run does not mutate Kernel authority. It creates a separate SQLite backup,
+  restores that backup into an isolated temporary database, and requires the
+  restored snapshot digest to equal the source preflight digest. On POSIX
+  systems, both the temporary and final backup are forced to owner-only `0600`
+  permissions before the backup is accepted. On Windows, inherited access is
+  removed and a private DACL for the current operator is applied and verified.
+- The digest covers the complete Kernel database schema and every row in every
+  authority table, while the report exposes only the digest and aggregate claim
+  counts. Any intervening Kernel write invalidates approval.
+- Preflight fails closed on integrity, foreign-key, schema/index, duplicate-row,
+  state, timestamp, read faults, or active claims attached to unclaimable issue
+  types.
+- Apply requires the human-approved exact digest and the verified backup. It
+  acquires `BEGIN IMMEDIATE`, re-reads the complete repair snapshot, rejects any
+  digest drift, and compare-and-swaps every exact row before committing one
+  privacy-safe receipt.
+- Terminal issue state wins over expiry: its active claim becomes `released`.
+  An expired active claim on nonterminal work becomes `reclaimable`. Valid
+  unexpired leases and historical null-expiry leases remain active.
+- Replaying the same approved digest returns the original receipt without another
+  mutation. Any interruption before receipt commit rolls back the whole repair.
+
+## Dry-run and approval
+
+Choose the observation time once; do not substitute a moving clock between steps.
+
+```powershell
+bun scripts/legacy-claim-repair.js --dry-run `
+  --database <absolute-kernel.sqlite> `
+  --backup <absolute-separate-backup.sqlite> `
+  --at <YYYY-MM-DDTHH:mm:ss.sssZ>
+```
+
+```bash
+bun scripts/legacy-claim-repair.js --dry-run \
+  --database <absolute-kernel.sqlite> \
+  --backup <absolute-separate-backup.sqlite> \
+  --at <YYYY-MM-DDTHH:mm:ss.sssZ>
+```
+
+Every dry-run requires a new, unused `--backup` path. Repeating a dry-run with
+the same path fails closed instead of overwriting the immutable backup.
+
+Review the privacy-safe counts, `preflight.digest`, `preflight.after_digest`, and
+backup proof. Approval must name the exact `preflight.digest`.
+
+## Apply (human-gated)
+
+Do not run this command until the exact dry-run digest is explicitly approved.
+
+```powershell
+bun scripts/legacy-claim-repair.js --apply `
+  --database <absolute-kernel.sqlite> `
+  --backup <absolute-separate-backup.sqlite> `
+  --at <same-literal-observation-time> `
+  --approved-digest <approved-preflight-digest> `
+  --actor <operator-id>
+```
+
+```bash
+bun scripts/legacy-claim-repair.js --apply \
+  --database <absolute-kernel.sqlite> \
+  --backup <absolute-separate-backup.sqlite> \
+  --at <same-literal-observation-time> \
+  --approved-digest <approved-preflight-digest> \
+  --actor <operator-id>
+```
+
+If an apply process is forcibly terminated, it may leave empty blocker
+directories named `<backup>-wal`, `<backup>-shm`, and `<backup>-journal`. After
+confirming that no repair process is still running, remove those stale
+directories before verifying or reusing that backup. An already committed
+receipt can still be replayed without this cleanup.
+
+`CLAIM_REPAIR_BACKUP_POSTCOMMIT_DRIFT` means the repair and receipt committed,
+but the named backup changed during commit. Do not discard the
+`details.recovery_path` copy: it is the independently retained verified backup.
+Fence writers and investigate the named path before any restore. Repeating the
+same approved apply returns the committed receipt without mutating rows again.
+
+A successful first apply also reports `receipt.recovery_path`, and its durable
+receipt stores a privacy-safe `recovery_ref` suffix so a retry with the same
+`--backup` path reconstructs the retained artifact after response loss. The
+tool never automatically unlinks this owner-only independent copy after commit
+because no final check can make a later unlink race-free. Keep it until the
+named backup and receipt have been independently verified. A human may then
+remove that exact reported recovery path after confirming that no repair
+process is running.
+
+On POSIX the recovery file and its parent directory entry are synced before the
+authority transaction commits. Every receipt replay reopens the retained copy,
+reapplies owner-only permissions, and verifies its exact digest and identity
+before reporting success.
+
+## Restore boundary
+
+Restore is deliberately not automated. Fence every Kernel writer, stop Forge
+processes, and close all database handles first. Preserve the failed database and
+its `-wal`/`-shm` sidecars for diagnosis, then restore the separately verified
+backup to a new path and run the same fixed-time dry-run there before replacing
+authority. Never overwrite a live or open SQLite database.

package/docs/reference/RELEASE.md

@@ -2,9 +2,9 @@
 
 This page documents release readiness. Package publishing still requires the explicit publish step after merge.
 
-## v0.0.11 Boundary
+## v0.1.0-beta.6 Boundary
 
-v0.0.11 is the public documentation and positioning package release. The release branch bumps package metadata to `0.0.11`; publish only after the release PR is merged, tagged, and validated.
+v0.1.0-beta.6 is the current prerelease boundary. The release branch declares `0.1.0-beta.6`; publish only after the release PR is merged, tagged, and validated on that exact SHA.
 
 Keep these release steps explicit:
 
@@ -23,6 +23,8 @@ bun run check
 npm pack --dry-run
 ```
 
+The trusted npm workflow is generated through `forge release generate-npm-workflow --expect-head "$(git rev-parse HEAD)"`; the full expected SHA must match the current checkout, and direct workflow edits remain blocked. The generated authorization is bound to that SHA, actor, worktree, path, and exact content, so moving HEAD before staging also fails closed. On a release event, the workflow resolves the tag once, runs the complete supported repository suite on that immutable commit, and allows publication only when the attributable suite receipt, verification checkout, and publish checkout all name the same SHA.
+
 For docs-heavy changes, also run a Markdown link check if available. If no docs checker exists and adding one would broaden the PR, create a follow-up issue instead.
 
 ## Packaging Check
@@ -41,7 +43,7 @@ Release notes should include:
 - adapter compatibility
 - DeepWiki refresh checklist
 
-The v0.0.11 release notes live in [CHANGELOG.md](../../CHANGELOG.md).
+The v0.1.0-beta.6 release notes live in [CHANGELOG.md](../../CHANGELOG.md).
 
 ## Rollback
 

package/docs/reference/TOOLCHAIN.md

@@ -140,6 +140,14 @@ Forge project memory is a **kernel-backed** read model. `lib/project-memory.js`
 
 `forge remember` / `forge recall` route through this same `kernel_memories` table (via `lib/memory/router.js`), indexed by **FTS5** for token-AND BM25 recall: a `recall` query does full-text matching, and a no-query `recall` returns the newest notes plus a total count (never a full dump). Because the insights engine also writes `kernel_memories`, what it learns is recallable. Any legacy `.forge/memory/notes.jsonl` is imported once on first use, then retired. The opt-in **`graphiti`** backend is **experimental** — its config/doctor checks ship but the runtime write-through emitter is a fast-follow, so selecting it today still writes the local kernel floor. See [docs/guides/memory-backends.md](../guides/memory-backends.md).
 
+Claude Code setup and upgrade repair the existing Forge-owned `SessionStart` and `UserPromptSubmit` hook groups without replacing user hooks. `SessionStart` supplies a bounded project-memory digest; each submitted prompt can receive relevant FTS5-ranked memory as `additionalContext`. Other harnesses keep their documented CLI/rule/`AGENTS.md` fallback surfaces—Forge does not claim a native dynamic prompt hook where none is verified.
+
+Automatic recall is project-local. Forge derives scope from Git's canonical common directory so linked worktrees share one repository identity without crossing into another repository. Eligibility is applied before ranking: foreign scope, already-seen records, stale suggested records, and validly superseded records are excluded. Confirmed memories are authoritative project context; fresh suggested memories appear only under **Suggested memory — verify before relying**. Suggested memories outside the seven-day freshness window remain available to manual recall but are not injected automatically. User-global `.remember` data is not read because it has no authority-safe canonical project identity.
+
+Recall is bounded and fail-open: automatic prompt and session memory each have a 400-token budget, while default manual `forge recall` has a 1,200-token budget. Prompt recall has an internal 4.5-second deadline and SessionStart has a 9-second deadline, keeping them inside the 5-second and 10-second hook limits; an unavailable or slow store injects nothing rather than blocking the agent. Local 1,000-record holdouts enforce an FTS5 p95 of at most 250 ms. Linux CI timing acceptance is not claimed yet.
+
+The capped prompt shadow log stores aggregate candidate/injection counts and scores only—never prompt terms, session ids, selected memory ids, or memory bodies. The separate `memory.recall.observed` Kernel event likewise stores bounded outcomes, counts, selected ids, source/trust mixes, token estimates, elapsed time, and harness, with no prompt/query text, memory body/snippet, or correlation fingerprint.
+
 Typed memory helpers in `lib/memory/typed-api.js` add category and provenance conventions on top of the same kernel store; they do not create a new datastore. The supported categories are:
 
 | Category | Key prefix | Durable backend |

package/docs/reference/github-accounts.md

@@ -0,0 +1,134 @@
+# Optional GitHub accounts per clone
+
+Use this when you keep personal and work GitHub accounts signed in at the same
+time. It is off by default. Installing Forge or running `forge setup` does not
+select an account. Unbound projects keep native account selection.
+
+## Sign in once, select per clone
+
+From a normal terminal outside any previously launched account session, run:
+
+```sh
+gh auth login --hostname github.com --web --skip-ssh-key
+```
+
+Complete the browser flow for one account, then repeat for the other account.
+Choose the intended browser account each time. Keep your existing Git transport
+choice and decline Git credential-helper changes unless you deliberately want
+them. GitHub CLI owns login and credential storage; Forge does not create another
+credential store. Native `gh` normally uses the system credential store, but can
+fall back to a plaintext file when that store is unavailable. See
+[GitHub CLI login](https://cli.github.com/manual/gh_auth_login).
+
+Do not paste tokens into chat, commands, project files, shell profiles, or `.env`
+files. You do not need to export or persist `GH_TOKEN` for this workflow. If your
+normal terminal already supplies GitHub token variables, remove those overrides
+from that session before interactive login; do not print their values.
+
+Inside the work clone:
+
+```sh
+forge github use WORK_LOGIN
+forge github status
+forge github run -- codex
+```
+
+Inside the personal clone, in another terminal:
+
+```sh
+forge github use PERSONAL_LOGIN
+forge github status
+forge github run -- t3
+```
+
+Replace the uppercase labels with your GitHub logins. Both sessions can remain
+open together. Substitute any installed, trusted CLI harness or shell for `codex`
+or `t3`, such as `claude`, `pwsh`, or `bash`.
+
+`use` verifies the named stored account and repository access, then writes only
+`git config --local github.account`. It does not log in, switch the globally
+active account, or modify another clone. Linked Git worktrees normally share this
+clone-local configuration; use separate clones when you need separate bindings.
+
+Supported GitHub-dependent Forge commands use the binding automatically. To give
+the same identity to a harness's own `gh` calls, start that harness with
+`forge github run --`. Already-running terminals and harnesses are not changed.
+
+The launcher deliberately gives its child GitHub authority through transient
+environment variables. Only launch programs you trust with that account. Forge
+does not persist the token, but the launched program can access it. Harnesses or
+tools using their own credentials instead of the inherited `gh` environment are
+outside this guarantee.
+
+## Check or undo
+
+```sh
+forge github status --json
+forge github unset
+```
+
+Status reports the selected and verified login, clone-local binding source,
+effective Git author, origin transport, helper classification, and repository
+access. It does not print tokens, raw remote URLs, or raw credential-helper
+commands. Treat author and account labels as personal information when sharing
+diagnostics.
+
+`unset` is safe to repeat. It removes only the clone binding, not either stored
+login. It does not revoke authority from a running child: close that session and
+start a new one after changing or removing a binding.
+
+## Three separate identities
+
+| Identity | Controlled by |
+| --- | --- |
+| GitHub API account used by supported Forge routes | Clone-local `github.account` |
+| Commit author | Git `user.name` and `user.email` |
+| Fetch/push authentication | SSH configuration or the HTTPS credential helper |
+
+Forge does not change your author, origin, SSH keys, or credential helper.
+Existing SSH keys and host aliases remain valid; custom aliases must resolve to
+`github.com` for Forge's repository-access check. HTTPS and SSH GitHub.com origins
+are supported; insecure HTTP/Git transports and Enterprise hosts are not V1 targets.
+
+HTTPS has one important coupling: if Git uses `gh auth git-credential` as its
+helper, Git commands inside the explicitly launched session may use that session's
+selected token too. Other HTTPS helpers and SSH key selection remain independent.
+For native multi-account transport, keep separate SSH keys/aliases or configure
+your HTTPS credential manager to distinguish repository URLs (`useHttpPath`).
+These are optional Git choices, not Forge setup steps; see
+[GitHub's multi-account transport guide](https://docs.github.com/en/account-and-profile/how-tos/account-management/managing-multiple-accounts).
+
+## Platforms and recovery
+
+The command syntax is the same on Windows, macOS, and Linux. Windows executable
+and `.cmd` launchers are supported; quote paths or arguments containing spaces.
+Everything after `run --` belongs to the child, including `--help`, `--version`,
+and `--path`. Git Bash is still required for Forge's existing Windows Bash helpers.
+
+- **Account missing or expired:** run the browser login again from a normal
+  terminal, then retry `use` or `status`. Forge never starts login automatically.
+- **Account mismatch:** stop and check the clone with `forge github status`.
+  Reauthenticate the intended account, or explicitly bind the correct login.
+  A failed `use` leaves the prior binding intact.
+- **Repository access denied:** check organization membership, SSO authorization,
+  and the intended repository with its administrator. Account identity alone does
+  not grant repository access.
+- **Git push still uses the wrong account:** check the separate transport and
+  commit-author configuration above; changing the Forge API binding does not
+  replace SSH or credential-manager setup.
+- **Unsupported GitHub CLI:** upgrade `gh` to a version supporting named-account
+  token retrieval. Unbound projects do not need that capability.
+- **Program not found:** install the harness and check its executable name/PATH.
+
+The supported workflow entrypoints are `forge`, `forge-workflow`, and the compiled
+Forge executable. Direct developer invocation of `node bin/forge-cmd.js` is an
+internal legacy utility, not an account-isolated V1 entrypoint.
+
+## CuraPod adoption
+
+Only after this Forge feature is merged, the merged build is installed, and its
+acceptance checks pass: open each intended CuraPod clone, run
+`forge github use WORK_LOGIN`, verify `forge github status`, then launch the
+chosen harness with `forge github run --`. Keep personal clones separately bound
+to `PERSONAL_LOGIN`. This example does not discover or modify existing CuraPod
+repositories, remotes, keys, or accounts automatically.

package/docs/reference/protected-state-surfaces.md

@@ -8,7 +8,7 @@ The committed manifest is `.forge/protected-paths.yaml`. Runtime enforcement is
 
 | Surface | Examples | Required write surface |
 | --- | --- | --- |
-| `beads_state` | `.beads/issues.jsonl`, `.beads/config.yaml` | `bd` or Forge issue commands |
+| `beads_state` | `.beads/issues.jsonl`, `.beads/config.yaml` | `forge migrate --from beads`, then Forge issue commands |
 | `forge_config` | `.forge/config.yaml`, `.forge/protected-paths.yaml` | Forge config/setup API |
 | `generated_harness` | `AGENTS.md`, `.claude/skills/`, `.codex/skills/`, `.cursor/rules/` | `forge setup` or harness generator |
 | `memory_projection` | `docs/sessions/`, `docs/memory/`, `.forge/memory/` | Forge memory projection writer |
@@ -23,13 +23,13 @@ The committed manifest is `.forge/protected-paths.yaml`. Runtime enforcement is
 
 - Direct edits, additions, modifications, renames, and deletions of protected files are blocked by `scripts/protected-state-check.js`.
 - Allowed Forge API writes must declare the matching required surface. For example, a Forge config writer must call the protected writer with `surface: "forge_config"` and `viaForgeApi: true`.
-- Forge-owned commands that intentionally stage generated protected changes can set `FORGE_PROTECTED_STATE_ALLOWED_SURFACES` to the comma-separated surfaces they own for that command invocation.
+- Surface-only environment declarations do not authorize protected changes. Forge-owned workflow commands must issue a content-bound Kernel capability for the exact actor, worktree, surface, path, and bytes.
 - Blocked decisions include actor, path, decision, required surface, reason, and repair hint.
-- Audit-ready events use kind `protected_state_write` and are recorded through Beads audit when available.
+- Audit-ready events use kind `protected_state_write` and are appended as JSON lines to `.forge/protected-state-audit.jsonl` (git-ignored, capped at the newest 500 records). This log is visibility-only and never authorizes a protected edit. Forge-owned workflow authorization uses one-time, content-bound Kernel events that the protected-state checker consumes; hand-written JSON cannot grant authority. The audit write remains best-effort for ordinary blocked checks, while the workflow generator rolls back its file transaction if its required audit or Kernel authorization write fails.
 
 ## Repair Hint
 
-Every blocked path prints a repair hint. A repair hint is specific guidance such as using `bd update` for `beads_state`, `forge setup` for generated harness files, or the package manager for `lockfiles`.
+Every blocked path prints a repair hint. A repair hint is specific guidance such as importing a legacy store with `forge migrate --from beads` for `beads_state`, `forge setup` for generated harness files, or the package manager for `lockfiles`.
 
 Example blocked output shape: