@remixhq/claude-plugin 0.1.20 → 0.1.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixhq/claude-plugin",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Claude Code plugin for Remix collaboration workflows",
   "homepage": "https://github.com/RemixDotOne/remix-claude-plugin",
   "license": "MIT",
@@ -34,12 +34,12 @@
     "postbuild": "node -e \"const fs=require('node:fs'); for (const p of ['dist/mcp-server.cjs','dist/hook-pre-git.cjs','dist/hook-user-prompt.cjs','dist/hook-post-collab.cjs','dist/hook-stop-collab.cjs']) fs.chmodSync(p, 0o755);\"",
     "dev": "tsx src/mcp-server.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "node --import tsx --test src/**/*.test.ts",
+    "test": "node --import tsx --test 'src/**/*.test.ts'",
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@remixhq/core": "^0.1.15",
-    "@remixhq/mcp": "^0.1.15"
+    "@remixhq/core": "^0.1.17",
+    "@remixhq/mcp": "^0.1.17"
   },
   "devDependencies": {
     "@types/node": "^25.4.0",

package/skills/init-or-remix/SKILL.md

@@ -5,11 +5,13 @@ description: Use when deciding whether to bind the current repo to Remix or crea
 
 # Init, Remix, Or Checkout
 
-## Silent-init rule
+## Mid-turn unbound branch is hook-owned
 
-If during any turn you find yourself on an unbound branch in a Remix-bound repo — whether the user mentioned Remix or not, whether the prompt is trivial or not — **silently run `remix_collab_init` on the current branch without asking**. This is not a decision point. Do not present init as one option among several. Do not switch to a bound branch to avoid init. Init the branch you are on.
+When the current branch is unbound in a Remix-bound repo — whether the user mentioned Remix or not, whether the prompt is trivial or not — **the Remix `UserPromptSubmit` hook detects this and spawns `remix collab init` for you, detached, in the background**. You do not need to call `remix_collab_init` yourself for that case, and you should not present init as a decision point. The prompt context will include a Remix note when init is in flight; treat it as informational.
 
-The user-facing decision tree below (init vs. remix vs. checkout) only applies when the user is explicitly choosing how to bring a repo into Remix for the first time. Mid-turn unbound-branch recovery is always silent init.
+If the user explicitly asks you to initialize the current branch, you may call `remix_collab_init` to give them an immediate synchronous result instead of waiting for the hook. Otherwise, leave it to the hook.
+
+The user-facing decision tree below (init vs. remix vs. checkout) applies when the user is explicitly choosing how to bring a repo into Remix for the first time, or when the repo has no Remix binding at all (no `.remix/config.json`). The hook's auto-init path only fires when the repo already has a binding for some other branch.
 
 Use this skill when onboarding a repository into Remix, starting from an existing Remix app lineage, or checking out an exact existing Remix app.
 

package/skills/review-merge-request/SKILL.md

@@ -31,7 +31,7 @@ Important rules:
 - In a bound repo, use Remix review tools as the default path for MR handling.
 - Choose an explicit queue instead of treating merge requests as one broad inbox.
 - Do not treat raw `git merge` as the way Remix merge requests are approved or applied.
-- Do not assume a successful `remix_collab_finalize_turn` already created a remote change step; drain and re-check when status reports `await_finalize`.
+- Do not assume queued hook recording already created a remote change step; drain and re-check when status reports `await_finalize`.
 - If approval would mutate the local target repo, explain that before applying it.
 - If the repo context is unclear, stay in remote-only review mode until the target repo is confirmed.
-- Before the final response, use `remix_collab_finalize_turn` to record the completed review turn.
+- Rely on automatic hook recording to capture the completed review turn.

package/skills/safe-collab-workflow/SKILL.md

@@ -9,30 +9,35 @@ In a Remix-bound repo, treat Remix MCP tools as the authoritative workflow layer
 
 ## Runtime override (read this first)
 
-When this turn's context contains a Remix runtime status note (recognizable by the literal `[Remix runtime status]` prefix from the Remix `UserPromptSubmit` hook), recording and queue draining for **this** turn are handled automatically by the runtime's `Stop` hook. In that case:
+In a Remix-bound repo, the Remix plugin hooks own all "plumbing" for recording: turn finalize, branch init when the current branch is unbound, baseline repair when the local anchor diverged, and safe sync recovery when the server moved ahead. These run automatically, detached, in the background. You are not the recovery layer.
 
-- Do **not** call `remix_collab_finalize_turn` for this turn — the runtime is recording it. Calling it would create a duplicate record.
+Concretely:
+
+- Do **not** call `remix_collab_init` to "fix" an unbound branch. The `UserPromptSubmit` hook detects an unbound current branch and spawns `remix collab init` itself; the prompt context will tell you when this is in progress. Only call `remix_collab_init` when the user explicitly asks you to initialize a repo or when the runtime surfaces an unrecoverable error pointing at it.
+- Do **not** call any MCP tool to "re-anchor" or "repair the baseline". The `Stop` hook auto-dispatches `remix collab re-anchor` when the server returns `re_anchor_required`; the next prompt will surface progress or failure.
+- Do **not** call `remix_collab_sync_apply` purely as a precondition for recording. The `Stop` hook auto-dispatches `remix collab sync` when the server returns `pull_required`. Sync remains the right tool when the **user** asks to pull or when status shows divergence the user wants to act on.
+- Do **not** call a finalize MCP tool for the current turn. The MCP surface does not expose one; the `Stop` hook is recording it.
 - Do **not** call `remix_collab_drain_finalize_queue` as a precondition for anything. The runtime drains the queue automatically in the background; mutation tools (`remix_collab_request_merge`, `remix_collab_reconcile_apply`) also drain internally before they run.
 
-The runtime status note is authoritative for the override. The rest of this skill — including the "before the final response, you must record" rule — still applies for **tool errors**, **explicit recovery flows**, and **turns where no runtime status note is present**.
+When the prompt context includes a `[Remix recovery]` note from a previous turn, treat it as informational. The runtime is already retrying or has already failed and surfaced the log path; do not race it with another MCP call unless the user asks you to.
+
+The runtime status note is authoritative for automatic recording. Use queue drain only for **explicit recovery flows**, such as status reporting `await_finalize` before a merge-related operation.
 
 Canonical rules:
 
 - In a bound repo, Remix tools are the required workflow layer for collaboration work.
 - In a bound repo, branch switches are collaboration-state transitions because each branch can resolve to its own Remix lane and app lineage.
 - Never switch git branches on your own. Branch switches are user-initiated only. If a Remix tool points at a different branch, do not "fix" it by switching — run `remix_collab_status` and follow its recommendation for the current branch.
-- An unbound branch is always a silent-init situation. Run `remix_collab_init` without asking. The user's intent when working on a branch is that the branch be bound.
+- An unbound current branch is handled automatically by the `UserPromptSubmit` hook. Do not call `remix_collab_init` for the current branch unless the user explicitly asks; the hook spawns it detached and surfaces progress on the next prompt.
 - Historical intent questions go to Remix memory before raw git history.
-- Remix is source-blind: any local content change since the last recorded turn — whether you typed it, the user typed it, a merge produced it, `git pull` brought it in, or an IDE saved it — is captured by exactly one `remix_collab_finalize_turn`. Do not pick a different command based on what produced the change. `re-anchor` is for the narrow missing-baseline case only (status reports `re_anchor`).
-- Raw git mutation is allowed in a bound repo, but it never substitutes for `remix_collab_finalize_turn`. After raw git mutations, run `remix_collab_status` and record with `finalize-turn`.
-- Before the final response, you must record exactly one completed turn with `remix_collab_finalize_turn` — **unless the runtime override at the top of this skill applies** (a `[Remix runtime status]` note from the Remix hook stating that the Stop hook will record this turn).
-- `remix_collab_finalize_turn` is queued only. It captures the local boundary first; a remote change step does not exist yet until the finalize queue drains.
-- The recording call must include the exact user prompt and your final assistant response.
-- Do not finish the response before recording the completed turn (subject to the runtime override).
+- Remix is source-blind: any local content change since the last recorded turn — whether you typed it, the user typed it, a merge produced it, `git pull` brought it in, or an IDE saved it — is captured by exactly one completed-turn hook recording. Do not pick a different command based on what produced the change. Baseline repair (`re-anchor`) is hook-owned: when the runtime needs it, the `Stop` hook spawns it and the next prompt explains it in plain language.
+- Raw git mutation is allowed in a bound repo, but it never substitutes for automatic hook recording. After raw git mutations, run `remix_collab_status` if you need to inspect state; `recommendedAction: record` means the completed-turn hook will capture the boundary.
+- The runtime records the exact user prompt and final assistant response automatically at turn completion.
+- Hook recording is queued. A remote change step does not exist yet until the finalize queue drains.
 - Prefer preview tools before apply tools whenever both exist.
 - Treat reconcile as high risk and use it only when sync is unavailable and clearly required.
 
-Raw git mutation commands are not the normal collaboration path, but they are allowed. When they are used, treat the result the same as any other local content change: run `remix_collab_status` and follow its `recommendedAction` (almost always `record` → `remix_collab_finalize_turn`). Raw git reads are reserved for exact repository facts, not for normal collaboration-state or historical-reasoning flows.
+Raw git mutation commands are not the normal collaboration path, but they are allowed. When they are used, treat the result the same as any other local content change: run `remix_collab_status` if you need to inspect state; `recommendedAction: record` means the completed-turn hook will capture the boundary. Raw git reads are reserved for exact repository facts, not for normal collaboration-state or historical-reasoning flows.
 
 Follow this order:
 
@@ -49,13 +54,13 @@ Follow this order:
    - `remix_collab_memory_timeline`
 7. Only call `remix_collab_memory_change_step_diff` after you already have a specific `changeStepId`.
 8. Use raw git history only after Remix memory has narrowed the relevant change, or when the user explicitly asks for exact commit, blame, ancestry, or patch-level detail.
-9. Before the final response, call `remix_collab_finalize_turn`, **unless** the runtime override at the top of this skill applies for this turn — in which case the runtime records it on your behalf and a manual call would be a duplicate.
+9. Before merge-related or recovery flows, drain and re-check only if status reports `await_finalize`; routine completed-turn recording is automatic.
 
 After switching branches:
 
 1. Run `remix_collab_status`.
 2. If the branch is healthy and bound, continue with the requested workflow.
-3. If the branch is unbound, silently run `remix_collab_init` on that branch before mutation commands. Do not ask, do not offer to switch back to another branch — init the branch you are on.
+3. If the branch is unbound, do not call `remix_collab_init` yourself. The next `UserPromptSubmit` will trigger the hook-owned init for that branch automatically. Continue with read-only work; mutations land in the deferred-turn queue and replay once the branch binds.
 4. If status reports a branch mismatch, stop and recover the correct branch binding before recording, syncing, reconciling, or opening a merge request.
 5. Do not assume another branch's binding is safe to reuse on the current checkout.
 
@@ -74,16 +79,16 @@ Branch state can change between turns by means you did not initiate — external
 
 **NEVER end your response with an unhandled Remix error.** If a Remix tool fails and you cannot resolve it this turn, at minimum: run `remix_collab_status`, report the real state to the user, and explicitly ask how to proceed. Silently giving up is not an option in a bound repo.
 
-**NEVER switch branches to "recover" from an unexpected binding state.** If status shows the current branch is unbound or mismatched, the recovery is `remix_collab_init` (silent) or a user-facing question — never `git checkout` another branch. Branch switches belong to the user.
+**NEVER switch branches to "recover" from an unexpected binding state.** If status shows the current branch is unbound or mismatched, the recovery is hook-owned (the next `UserPromptSubmit` spawns init automatically) or a user-facing question — never `git checkout` another branch. Branch switches belong to the user.
 
 Important rules:
 
-- If the repo is unbound, use `remix_collab_init` for the current repo, `remix_collab_remix` for a new fork from an existing app lineage, or `remix_collab_checkout` to materialize an existing app as-is.
-- In a bound repo, raw git mutations (`commit`, `pull`, `merge`, `rebase`, `reset`) are allowed but never replace `remix_collab_finalize_turn`. After any raw git mutation, run `remix_collab_status` and record with `finalize-turn`. Do not assume `re-anchor` is the recovery — that command is only for missing-baseline cases (`recommendedAction: re_anchor`).
+- If the repo has no Remix binding at all (no `.remix/config.json`), use `remix_collab_init` for the current repo, `remix_collab_remix` for a new fork from an existing app lineage, or `remix_collab_checkout` to materialize an existing app as-is. The `UserPromptSubmit` hook only auto-spawns init when a binding exists for some other branch on the same repo; it does not initialize a brand-new repo for you.
+- In a bound repo, raw git mutations (`commit`, `pull`, `merge`, `rebase`, `reset`) are allowed but never replace automatic hook recording. After any raw git mutation, run `remix_collab_status` if you need to inspect state; `recommendedAction: record` means the completed-turn hook will capture the boundary. Do not call `remix_collab_re_anchor`, `remix_collab_init`, or `remix_collab_sync_apply` purely to "satisfy" recording — the `Stop` hook auto-dispatches each of those when finalize reports the matching preflight code.
 - In a bound repo, do not start why/history/failed-attempt questions with raw git `log`, `show`, `blame`, or `diff`; start with Remix memory reads instead.
-- In a bound repo, do not finish the response before recording the completed turn yourself.
-- Do not treat a successful `remix_collab_finalize_turn` call as proof that the turn is already available for merge-request or remote-history workflows. Drain and re-check when status reports `await_finalize`.
-- After the final recording call, avoid further repo mutations unless you intend to record another final turn.
+- In a bound repo, rely on automatic hook recording for the completed turn.
+- Do not treat queued hook recording as proof that the turn is already available for merge-request or remote-history workflows. Drain and re-check when status reports `await_finalize`.
+- After the final response, avoid further repo mutations unless you intend to capture them in a later turn.
 - Use raw git reads only when the task is clearly about exact repository facts or a separate GitHub-only branch workflow rather than Remix state.
 - When viewing merge requests, request bounded diff output first and only ask for more detail if needed.
 - For merge-request listing, choose the explicit queue that matches the intent: `remix_collab_review_queue`, `remix_collab_my_merge_requests`, or `remix_collab_list_app_merge_requests` with required `queue` set to `app_reviewable`, `app_outgoing`, or `app_related_visible`.

package/skills/submit-change-step/SKILL.md

@@ -1,91 +1,63 @@
 ---
-name: finalize-turn-workflow
-description: Use when code edits or review work are complete in a Remix-bound repo and the turn should be recorded with `remix_collab_finalize_turn`.
+name: turn-recording-workflow
+description: Use when code edits or review work are complete in a Remix-bound repo and the completed turn should be captured by automatic hook recording.
 ---
 
-# Finalize A Remix Turn
+# Record A Remix Turn
 
 Use this skill after edits or review work are complete and the task should be captured as the final recorded turn in a Remix-bound repo.
 
-This skill is specifically about the queued-finalize model behind `remix_collab_finalize_turn`.
+This skill is specifically about the automatic hook recording model. The MCP surface does not expose a manual finalize tool.
 
 ## Source-blind recording rule
 
-Remix records turns source-blind. Any local content change since the last recorded turn — whether you typed it, the user typed it, a `git pull` brought it in, a `git merge` or `git rebase` produced it, or an IDE saved it — is captured by exactly one `remix_collab_finalize_turn`. `finalize-turn` automatically attaches `preTurnEvents` metadata describing any commits, merges, or uncommitted state captured at the boundary; you do not need to summarize that yourself.
+Remix records turns source-blind. Any local content change since the last recorded turn — whether you typed it, the user typed it, a `git pull` brought it in, a `git merge` or `git rebase` produced it, or an IDE saved it — is captured by exactly one completed-turn hook recording. The recording automatically attaches `preTurnEvents` metadata describing any commits, merges, or uncommitted state captured at the boundary; you do not need to summarize that yourself.
 
-Do **not** pick a different command (`re-anchor`, `sync`, `reconcile`) based on what produced the local change. Those commands are only correct when `remix_collab_status.recommendedAction` explicitly names them:
+Do **not** call `remix_collab_re_anchor_*`, `remix_collab_init`, or `remix_collab_sync_apply` purely as preconditions for recording. The runtime's `Stop` hook auto-dispatches each of those when finalize reports the matching preflight code:
 
-- `record` (or `repoState: local_only_changed`) → `remix_collab_finalize_turn`. This is the catch-all and the most common case.
-- `re_anchor` → `remix_collab_re_anchor_*`. Only when no local Remix baseline exists for this lane (fresh clone, deleted `.remix/`, or first init didn't seed). Re-anchor seeds the baseline; it is not a recovery for "the local content changed."
-- `pull` → `remix_collab_sync_*`. Only when the server lane advanced and local did not.
-- `reconcile` → `remix_collab_reconcile_*`. Only when both sides changed since the agreed baseline.
+- `branch_binding_missing` → hook spawns `remix collab init`.
+- `re_anchor_required` → hook spawns `remix collab re-anchor`.
+- `pull_required` → hook spawns `remix collab sync`.
 
-## Runtime override (read this first)
+Each fix runs detached, logs to `.remix/<command>.log`, and writes a marker the next prompt surfaces. If you see a `[Remix recovery]` note in the next prompt's context, it is the runtime telling you what already happened — not a request for you to retry.
 
-When a Remix runtime status note appears in this turn's context — recognizable by the literal `[Remix runtime status]` prefix and originating from the Remix `UserPromptSubmit` hook — recording and queue draining for **this** turn are handled automatically by the runtime's `Stop` hook. In that case:
+The recommended-action codes from `remix_collab_status` (`record`, `re_anchor`, `pull`, `reconcile`) remain meaningful when the **user** is reasoning about state or explicitly asks for a sync, a re-anchor, or a reconcile. Don't pre-emptively invoke them just to "satisfy" recording.
 
-- Do **not** call `remix_collab_finalize_turn` for this turn. The runtime is recording it. A redundant call would create a duplicate record.
+## Runtime recording
+
+In a Remix-bound repo, the `Stop` hook is the authoritative recorder for every completed turn:
+
+- Do **not** call a finalize MCP tool. The MCP surface does not expose one.
 - Do **not** call `remix_collab_drain_finalize_queue` for this turn. The runtime drains the queue automatically in the background. Mutation tools (`remix_collab_request_merge`, `remix_collab_reconcile_apply`) drain internally before they run, so manual draining is never required as a precondition.
 
-The runtime status note is authoritative for the override. Everything else in this skill — the mandates, the "NEVER" rules, the recovery sequences — still applies for **error recovery**, **tool failures**, and **turns where no runtime status note is present**. Treat the override as covering only the routine "I just finished a healthy turn, time to record it" case.
+Use `remix_collab_drain_finalize_queue` only for explicit recovery flows, such as status reporting `await_finalize` before a merge-related operation.
 
 Workflow:
 
 1. Run `remix_collab_status` first to confirm the repo is bound and inspect current warnings.
-2. If status recommends `await_finalize`, do not record again and do not request a merge yet. Use `remix_collab_drain_finalize_queue`, then re-check `remix_collab_status`.
-3. When the repo is ready, use `remix_collab_finalize_turn` before the final response, with the exact user prompt and your final assistant response — **unless the runtime override above applies**.
-4. Treat `remix_collab_finalize_turn` as capturing the local workspace boundary and queueing remote processing, not as immediate proof that a remote change step already exists.
+2. If status recommends `await_finalize`, do not request a merge yet. Use `remix_collab_drain_finalize_queue`, then re-check `remix_collab_status`.
+3. When status recommends `record`, continue the turn normally. The completed-turn hook captures the exact user prompt, final assistant response, and local workspace boundary.
+4. Treat hook recording as local capture plus queued remote processing, not as immediate proof that a remote change step already exists.
 
 Important behavior:
 
-- `remix_collab_finalize_turn` is the authoritative recording path for completed work instead of raw git commit or push.
-- `remix_collab_finalize_turn` is queued only. A remote change step does not exist yet until the finalize queue drains successfully.
-- A successful finalize call means local capture and queueing succeeded. It does not mean merge-request or remote-history workflows can assume the turn is already materialized remotely.
+- Automatic hook recording is the authoritative path for completed work instead of raw git commit or push.
+- Hook recording is queued. A remote change step does not exist yet until the finalize queue drains successfully.
 - If `remix_collab_status` reports `await_finalize`, use `remix_collab_drain_finalize_queue` and re-check status before merge-related or recovery flows.
-- If the user wants to understand current repo state before recording, re-run `remix_collab_status`.
-- Do not make further repo mutations after the final recording call unless you intend to record another completed turn.
-- Do not retry finalize immediately just because a remote record is not visible yet; queue drain is the next step, not a second finalize.
-- If finalize or drain returns `recommendedNextActions` or an `error.hint`, those fields are **authoritative and mandatory**. Do not ignore them. Do not improvise around them. Call `remix_collab_status` first and use its result plus the hint together to choose the next tool. Skipping this step is the single most common way agents fail in this skill.
+- If the user wants to understand current repo state before the turn ends, re-run `remix_collab_status`.
+- Do not make further repo mutations after the final response unless you intend them to be captured by a later completed turn.
+- Do not retry recording just because a remote record is not visible yet; queue drain is the next step, not another recording attempt.
+- If drain returns `recommendedNextActions` or an `error.hint`, those fields are **authoritative and mandatory**. Do not ignore them. Do not improvise around them. Call `remix_collab_status` first and use its result plus the hint together to choose the next tool.
 - If the tool surfaces a preserved local recovery artifact, mention it explicitly and keep it available while you repair repo state.
 
-Use the live worktree as the source of truth for finalized work. If the repo is not ready, fix the preflight state first rather than trying to bypass it.
-
-## Finalize errors — non-negotiable rules
-
-When `remix_collab_finalize_turn` returns an error, you are in a state-recovery situation. You do not have permission to end your turn until it is resolved.
-
-**NEVER, UNDER ANY CIRCUMSTANCES, END A TURN WITH AN UNHANDLED FINALIZE ERROR.**
-
-This means:
-
-- Do not decide "finalize isn't applicable here" because the user's prompt was trivial (e.g. "hello world"). The recording rule fires on any turn that touches the bound repo — including the very finalize call that just failed. The call touched the repo. You must record.
-- Do not skip finalize because the error seems like a state problem outside your control. State problems are exactly what the error's `hint` and `recommendedNextActions` fields are there to resolve. Read them. Follow them.
-- Do not run a random bash command to "check what happened" and then give up. That is the failure pattern. `remix_collab_status` is the correct first tool, every time, without exception.
-
-**Mandatory recovery sequence when finalize errors:**
-
-1. Read the error's `message`, `hint`, and `recommendedNextActions` fields in full. They are authoritative. If the hint names a tool, that tool is almost certainly the next correct call.
-2. Call `remix_collab_status` immediately. The hint from status supersedes anything you inferred from the error alone — status sees the actual current binding, branch, worktree, alignment, and queue state.
-3. Based on status, pick the correct recovery tool:
-   - `local_only_changed` (or `recommendedAction: record`) → `remix_collab_finalize_turn`. This is the catch-all for any local mutation, including raw `git commit`, `git pull`, `git merge`, `git rebase`, or `git reset`. The source of the change does not matter.
-   - `baseline_missing` or `external_local_base_changed` (or `recommendedAction: re_anchor`) → commit any pending edits, then `remix_collab_re_anchor_preview` → `remix_collab_re_anchor_apply`. This applies only when no local Remix baseline exists for this lane yet, not whenever local content moved.
-   - `await_finalize` → `remix_collab_drain_finalize_queue`, then re-check status.
-   - Unbound or mismatched branch → follow the branch-recovery rules below.
-   - `delta_ready` for sync (or `recommendedAction: pull`) → `remix_collab_sync_preview` → `remix_collab_sync_apply`.
-   - `both_changed` (or `recommendedAction: reconcile`) → `remix_collab_reconcile_preview` → `remix_collab_reconcile_apply`.
-4. Retry `remix_collab_finalize_turn` only after status confirms the blocker is cleared.
-5. Only then produce your final user-facing response.
-
-**If finalize fails because the current branch is unbound:**
+Use the live worktree as the source of truth for recorded work. If the repo is not ready, fix the preflight state first rather than trying to bypass it.
 
-The error hint will explicitly name the branch (e.g., `"Run remix collab init on branch X"`). That hint is the answer. Sequence:
+## Branch recovery
 
-1. Call `remix_collab_status` to confirm the current branch is unbound (not mismatched, not in another recoverable state).
-2. **Silently run `remix_collab_init` on the current branch.** Do not ask the user first. Do not offer alternatives. Do not switch branches. An unbound branch in a Remix-bound repo is always a silent-init situation — that is the entire point of the init-on-demand contract.
-3. Retry `remix_collab_finalize_turn`. Only after it succeeds, respond.
+If status shows the current branch is unbound, **the next `UserPromptSubmit` hook will spawn `remix collab init` for you, detached, in the background.** Continue the requested work. The current turn lands in the deferred-turn queue and replays automatically once init completes; if init fails, the next prompt's context will explain it in plain language and point at `.remix/collab-init.log`.
 
-**NEVER switch git branches to resolve a finalize error.** Branch switching is a user-initiated action and requires explicit user instruction. If status shows the current branch is unbound, init it — do not switch to some other bound branch to avoid the init. Silently initing the current branch is always correct; silently switching branches is always wrong.
+You should not call `remix_collab_init` yourself for this case unless the user explicitly asks for an immediate, synchronous result. Calling it eagerly races the hook and produces no observable benefit.
 
-**Cross-branch finalize** (`allowBranchMismatch: true`) applies only when the user has explicitly asked for it. Do not infer it from status.
+**NEVER switch git branches to resolve a recording issue.** Branch switching is a user-initiated action and requires explicit user instruction. If status shows the current branch is unbound, leave it for the hook — do not switch to some other bound branch to avoid the init.
 
-**The triviality of the user's current prompt is irrelevant.** "Say hello world" does not exempt you from the protocol. Neither does "what time is it", "thanks", or any other small talk. If the bound repo was touched — including by a failing Remix tool call — you finalize. No exceptions, **except** the explicit runtime override at the top of this skill (a `[Remix runtime status]` note from the runtime hook stating that the Stop hook will record this turn automatically). The runtime override is the **only** sanctioned way to skip a finalize call; nothing else exempts you.
+The triviality of the user's current prompt is irrelevant. "Say hello world" does not exempt the turn from recording if the bound repo was touched. The hooks handle routine recording automatically.

package/skills/sync-and-reconcile/SKILL.md

@@ -14,8 +14,8 @@ Mental model:
 - `remix_collab_sync_*` is for pulling Remix-known app state into the local repo when fast-forward sync is possible (i.e. `recommendedAction: pull`, `repoState: server_only_changed`).
 - `remix_collab_reconcile_*` is for the rare case where both the local workspace and the server lane changed since the last agreed baseline (i.e. `recommendedAction: reconcile`, `repoState: both_changed`).
 - `remix_collab_sync_upstream` is for bringing new upstream app changes into a remix.
-- `remix_collab_finalize_turn` is not a sync tool. It records the completed turn, but it does not replace sync, reconcile, or upstream-sync workflows.
-- `re-anchor` is **not** a sync or recovery tool for diverged history. It only seeds a missing local Remix baseline (`recommendedAction: re_anchor`). See the finalize-turn-workflow skill for full handling. If status reports `local_only_changed` (or `recommendedAction: record`), the answer is `finalize-turn`, never reconcile.
+- Automatic hook recording is not a sync tool. It records the completed turn, but it does not replace sync, reconcile, or upstream-sync workflows.
+- `re-anchor` is **not** a sync or recovery tool for diverged history. It only seeds a missing local Remix baseline (`recommendedAction: re_anchor`). If status reports `local_only_changed` (or `recommendedAction: record`), routine completed-turn hook recording is the answer, never reconcile.
 
 Workflow: