feat(FN-5473): add smart pull guide and merge advance notice banner to dash

- feat(FN-5473): complete Step 5 — fix typecheck verification regressions
- feat(FN-5473): complete Step 4 — add AGENTS doc cross references
- feat(FN-5473): complete Step 3 — document merge advance notice banner
- feat(FN-5473): complete Step 2 — add smart pull guide section

Fusion-Task-Id: FN-5473

Co-authored-by: Fusion (runfusion.ai) <noreply@runfusion.ai>
Fusion-Task-Id: FN-5473

AGENTS.md

@@ -152,7 +152,7 @@ When `settings.autoMerge: false`, `in-review` is terminal-until-merged by a huma
 
 ### Reliability Mechanism Coverage
 
-- FN-5432 backstop: `packages/engine/src/__tests__/reliability-interactions/dependency-cycle-reconcile.test.ts` extends FN-5256 coverage with long-cycle ambiguous sweep, write-boundary/sweep race, self-defeating+cycle non-contradiction across one maintenance flow, and audit-event shape regression; core regression cases (long cycle, self-loop via update, incremental-update closes a loop, moveTask seam invariant, DependencyCycleError shape) live in `packages/core/src/__tests__/store-dependency-cycle.test.ts`.
+- FN-5432 backstop: `packages/engine/src/__tests__/reliability-interactions/dependency-cycle-reconcile.test.ts` extends FN-5256 coverage with long-cycle ambiguous sweep, write-boundary/sweep race, self-defeating+cycle non-contradiction across one maintenance flow, and audit-event shape regression; core regression cases (long cycle, self-loop via update, incremental-update closes a loop, moveTask seam invariant, DependencyCycleError shape) live in `packages/core/src/__tests__/store-dependency-cycle.test.ts`. User-facing pull/stash audit event behavior (`pull:fast-forward`, `stash:pop-conflict`) is documented in `docs/dashboard-guide.md` under Merge Advance Notice / Smart Pull.
 - FN-5403 backstop: `packages/engine/src/__tests__/reliability-interactions/engine-stop-aborts-execution.test.ts` locks stop-ordering behavior so engine shutdown aborts executor AI sessions before drain wait and preserves task-row lifecycle semantics.
 
 ---
@@ -161,7 +161,7 @@ When `settings.autoMerge: false`, `in-review` is terminal-until-merged by a huma
 
 - `./docs/architecture.md` — lifecycle invariants, self-healing rules, reliability interaction backstops, run-audit internals.
 - `./docs/testing.md` — full testing lanes, worker fanout guidance, test taxonomy, and file organization.
-- `./docs/dashboard-guide.md` — dashboard behavior and **Styling Guide** details.
+- `./docs/dashboard-guide.md` — dashboard behavior and **Styling Guide** details. User-facing docs for Merge Advance Notice and Smart Pull live here.
 - `./docs/agents.md` — pi extension scope, coordination tools, checkout leasing, runtime config.
 - `./docs/settings-reference.md` — model-selection hierarchy, mock provider mode, token budget precedence, presets.
 - `./docs/storage.md` — hybrid storage model details.

docs/dashboard-guide.md

@@ -209,6 +209,61 @@ Features:
 
 ![Git manager](./screenshots/git-manager.png)
 
+## Merge Advance Notice
+
+Merge Advance Notice is a global banner (`MergeAdvanceNotice`) mounted in the main app chrome that appears when the integration branch advances.
+
+When it appears:
+- Reacts to `task:merged` SSE events
+- Hydrates from `GET /api/tasks/merge-advance-events`
+- Shows the latest merge-advance event for the current project
+
+What it shows:
+- Integration branch name and the new tip short SHA
+- Advancing task ID and advance metadata from the event payload (`advanceMode`, `refName`, SHA details)
+- Checkout-state warnings when your current worktree is dirty or has untracked files
+
+How to react:
+- Click **Pull** to run Smart Pull (`POST /api/git/smart-pull`), including the stash-conflict flow in `StashConflictModal` when needed
+- Use the dismiss close button to hide the notice
+- Treat dirty/untracked warnings as a hint that local changes may be auto-stashed during pull
+
+Push follow-up (when shown):
+- If the integration branch is ahead of `origin`, the banner can show push controls with ahead count
+- Use **Push to origin** (or force-with-lease via **Advanced**) to publish the advanced branch tip
+- If push is rejected (`rejected-non-ff` / `sha-mismatch`), the banner offers a Smart Pull retry path
+
+Branch names are dynamic from merge/audit payloads; the banner is not hardcoded to `main`.
+
+## Smart Pull
+
+Smart Pull is a one-shot pull workflow that keeps local work safe while advancing your checked-out integration branch.
+
+What it does:
+- Calls `POST /api/git/smart-pull`
+- If your worktree is clean, runs a fast-forward pull and returns `kind: "clean-pull"`
+- If local changes exist, auto-stashes (including untracked files), runs `git pull --ff-only`, then restores the stash
+- Returns `kind: "stash-pull-pop"` when stash → pull → pop succeeds cleanly
+- Returns `kind: "stash-pop-conflict"` when stash restore conflicts, then opens `StashConflictModal`
+
+Where it is triggered:
+- From the merge-advance banner pull action (`MergeAdvanceNotice`)
+- From any dashboard surface that invokes `POST /api/git/smart-pull`
+
+When `stash-pop-conflict` occurs, `StashConflictModal` shows:
+- Stash short SHA + stash label
+- Per-file conflict list
+- Per-file resolution actions (**Keep mine** / **Keep incoming**, backed by `/api/git/stash-resolve` choices `ours`/`theirs`)
+- Stash actions: **Drop stash** (`POST /api/git/stash-drop`) and **Restore from stash ref** (`POST /api/git/stash-restore`)
+- A stash-SHA copy button for sharing the conflict list/reference
+
+After resolution:
+- As each file is resolved, `remainingConflicts` shrinks; when empty, the modal can be closed and the branch stays at the advanced integration tip with resolved stash content applied
+- Dropping the stash discards the saved local edits after conflicts are resolved
+- Restoring from stash ref re-applies the stash and may reintroduce conflicts for manual handling
+
+You may also see matching run-audit events in logs, including `pull:fast-forward` and `stash:pop-conflict`.
+
 ## Documents View
 
 Documents view aggregates task documents and project markdown files.