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

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.