From 84e40da3383949a8bb0b452734793aecd6d0d496 Mon Sep 17 00:00:00 2001
From: Iwan Kelaiah <iwan.kelaiah@gmail.com>
Date: Fri, 15 May 2026 20:53:52 +1000
Subject: [PATCH 1/2] feat(v1.2.0): add start-here callout and refine risk
 guidance

- Add dismissible "Start here" callout on both pages, persisted in
  localStorage; overview links to the Beginner Daily Path, branch map
  points at the create-from-commit flow.
- Soften `git reset --soft HEAD~1` from danger to caution since it
  keeps edits staged; expand the note to warn against using it on
  shared commits.
- Pair the diverged-scenario `git merge origin/<branch>` suggestion
  with a preceding `git fetch` so the two-step recovery is explicit;
  update the summary to match.
- Move shared callout setup into src/version.js so both HTML pages
  reuse the same behaviour without duplicating code.
- Bump version to 1.2.0 and update README and CHANGELOG.
---
 .claude/settings.local.json |  7 +++++
 CHANGELOG.md                | 14 ++++++++++
 README.md                   |  6 +++--
 branch-map.html             |  5 ++++
 index.html                  |  7 ++++-
 src/data.js                 |  8 +++---
 src/styles.css              | 53 +++++++++++++++++++++++++++++++++++++
 src/version.js              | 47 +++++++++++++++++++++++++++++---
 8 files changed, 137 insertions(+), 10 deletions(-)
 create mode 100644 .claude/settings.local.json

diff --git a/.claude/settings.local.json b/.claude/settings.local.json
new file mode 100644
index 0000000..c2a7791
--- /dev/null
+++ b/.claude/settings.local.json
@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node scripts/validate.mjs)"
+    ]
+  }
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 789f071..608efc9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.2.0] - 2026-05-15
+
+### Added
+
+- Added a dismissible "Start here" callout under the page intro on `index.html` and `branch-map.html`, with the dismissed state stored in `localStorage` under `git-map-start-here-dismissed`.
+- Added an `id="daily-path"` anchor on the Beginner Daily Path block so the overview callout can jump to it.
+- Added `git fetch` to the diverged scenario `next` steps so the standalone `git merge origin/<branch>` recommendation is paired with the preceding fetch.
+
+### Changed
+
+- Softened `git reset --soft HEAD~1` from `danger` to `caution` because the command keeps your edits staged; the note now also reminds users to avoid it on shared commits.
+- Updated the diverged scenario summary to describe the fetch-then-merge option alongside rebase and merge.
+- Moved the start-here setup into `src/version.js` so both HTML pages share the same callout behaviour without duplicating code.
+
 ## [1.1.0] - 2026-05-15
 
 ### Added
diff --git a/README.md b/README.md
index 66bc547..d539305 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
 [🌐 Live Demo](https://ikelaiah.github.io/git-map/)
 [GitHub Repository](https://github.com/ikelaiah/git-map)
 
-[![Version](https://img.shields.io/badge/Version-1.1.0-2f6fed?style=for-the-badge)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-1.2.0-2f6fed?style=for-the-badge)](CHANGELOG.md)
 [![HTML5](https://img.shields.io/badge/Made%20with-HTML5-e34f26?style=for-the-badge&logo=html5&logoColor=white)](index.html)
 [![CSS](https://img.shields.io/badge/CSS-theme--tokens-2f6fed?style=for-the-badge&logo=css&logoColor=white)](src/styles.css)
 [![Vanilla JavaScript](https://img.shields.io/badge/Vanilla-JavaScript-f7df1e?style=for-the-badge&logo=javascript&logoColor=111111)](src/app.js)
@@ -26,7 +26,9 @@ Git Map is a dependency-free Git visualisation and situation solver for beginner
 - 🗂️ Local Repo
 - 🌐 Remote Repo
 
-Version 1.1 updates the command guidance for current Git behavior. The Git Branch Map now creates branches from any selected commit, generated histories include the realistic edit, stage, and commit flow, diverged pull guidance shows explicit fast-forward, rebase, and merge choices, and both HTML pages link back to the GitHub repository.
+Version 1.2 sharpens onboarding and refines the risk and recovery guidance. A dismissible "Start here" callout points beginners at the Beginner Daily Path on the overview page and at the create-from-commit flow on the Git Branch Map. The diverged pull scenario now suggests `git fetch` followed by `git merge origin/<branch>` as a clear two-step pair, and `git reset --soft HEAD~1` is presented as a caution rather than a danger because it keeps your edits staged.
+
+Version 1.1 updated the command guidance for current Git behavior. The Git Branch Map creates branches from any selected commit, generated histories include the realistic edit, stage, and commit flow, diverged pull guidance shows explicit fast-forward, rebase, and merge choices, and both HTML pages link back to the GitHub repository.
 
 Commands in the app are examples. Replace placeholders such as `<file>`, `<branch>`, `<commit>`, and visual IDs like `c2` with real paths, branch names, commit SHAs, tags, or refs from your repository.
 
diff --git a/branch-map.html b/branch-map.html
index d8d766b..4fccf6d 100644
--- a/branch-map.html
+++ b/branch-map.html
@@ -12,6 +12,11 @@
       <div>
         <h1 id="page-title">Git Branch Map</h1>
         <p class="intro">Create branches from commits, add commits, switch, and merge visually. Every action writes the Git commands that would produce the graph.</p>
+        <aside class="start-here" id="start-here" role="note" hidden>
+          <span class="start-here-icon" aria-hidden="true">👉</span>
+          <p class="start-here-text">New here? Click a commit in the graph, then <strong>Create from selected commit</strong> to make your first branch.</p>
+          <button class="start-here-dismiss" type="button" id="start-here-dismiss" aria-label="Dismiss start here callout">×</button>
+        </aside>
         <nav class="page-tabs" aria-label="Git map pages">
           <a href="index.html">Git Map</a>
           <a href="branch-map.html" aria-current="page">Git Branch Map</a>
diff --git a/index.html b/index.html
index 5a3b151..df703a5 100644
--- a/index.html
+++ b/index.html
@@ -12,6 +12,11 @@
       <div>
         <h1 id="page-title">Git Map</h1>
         <p class="intro">Explore how Git commands move work between stash, workspace, staging, local history, and remote repositories.</p>
+        <aside class="start-here" id="start-here" role="note" hidden>
+          <span class="start-here-icon" aria-hidden="true">👉</span>
+          <p class="start-here-text">New here? Follow the <a href="#daily-path">Beginner Daily Path</a> — pull, edit, add, commit, push.</p>
+          <button class="start-here-dismiss" type="button" id="start-here-dismiss" aria-label="Dismiss start here callout">×</button>
+        </aside>
         <nav class="page-tabs" aria-label="Git map pages">
           <a href="index.html" aria-current="page">Git Map</a>
           <a href="branch-map.html">Git Branch Map</a>
@@ -115,7 +120,7 @@ <h2>How To Read It</h2>
           <div class="legend-item"><span class="legend-dot" style="--dot: var(--violet)"></span><span>Violet flows temporarily store work without committing it.</span></div>
           <div class="legend-item"><span class="legend-pill"><b>D</b> Daily</span><span>The daily marker highlights the common pull, add, commit, and push flow.</span></div>
         </div>
-        <div class="learn-section">
+        <div class="learn-section" id="daily-path">
           <h3>Beginner Daily Path</h3>
           <ol class="path-steps">
             <li><b>1</b><span>Sync first with <code>git pull</code>.</span></li>
diff --git a/src/data.js b/src/data.js
index 64c9bc3..ca59ca2 100644
--- a/src/data.js
+++ b/src/data.js
@@ -198,9 +198,9 @@ const commands = [
     color: "var(--green)",
     marker: "arrow-green",
     zones: ["local", "staging"],
-    risk: "danger",
+    risk: "caution",
     caution: "Rewrites last local commit",
-    note: "Moves the last commit back to staging so you can adjust and recommit."
+    note: "Moves the last commit back to staging so you can adjust and recommit. Soft reset keeps your edits staged, but avoid it on commits you have already shared."
   },
   {
     id: "reset-hard",
@@ -614,9 +614,9 @@ const statusScenarios = [
     label: "Diverged",
     zone: "remote",
     commandId: "fetch",
-    summary: "Both local and remote have commits the other side does not have. Plain git pull may stop under the fast-forward-only default, so choose rebase or merge.",
+    summary: "Both local and remote have commits the other side does not have. Plain git pull may stop under the fast-forward-only default, so choose rebase, merge, or run git fetch first and then merge origin/<branch>.",
     checks: ["git status", "git fetch", "git log --oneline --graph --decorate --all"],
-    next: ["git pull --rebase", "git pull --no-rebase", "git merge origin/<branch>"]
+    next: ["git pull --rebase", "git pull --no-rebase", "git fetch", "git merge origin/<branch>"]
   },
   {
     id: "conflict",
diff --git a/src/styles.css b/src/styles.css
index b6dc05c..8aa5f44 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -187,6 +187,59 @@ h1 {
   line-height: 1.55;
 }
 
+.start-here {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  max-width: 720px;
+  margin: 14px 0 0;
+  padding: 10px 12px;
+  border: 1px solid var(--line);
+  border-left: 4px solid var(--blue, #2f6fed);
+  border-radius: 10px;
+  background: var(--switch-bg);
+  color: var(--ink);
+  font-size: 0.92rem;
+  line-height: 1.45;
+}
+
+.start-here[hidden] {
+  display: none;
+}
+
+.start-here-icon {
+  font-size: 1.05rem;
+  line-height: 1;
+}
+
+.start-here-text {
+  margin: 0;
+  flex: 1;
+}
+
+.start-here-text a {
+  color: var(--blue, #2f6fed);
+  font-weight: 800;
+  text-decoration: underline;
+}
+
+.start-here-dismiss {
+  background: transparent;
+  border: 1px solid transparent;
+  color: var(--muted);
+  font-size: 1.15rem;
+  line-height: 1;
+  padding: 2px 8px;
+  border-radius: 6px;
+  cursor: pointer;
+}
+
+.start-here-dismiss:hover,
+.start-here-dismiss:focus-visible {
+  border-color: var(--line);
+  color: var(--ink);
+}
+
 .page-tabs {
   display: flex;
   flex-wrap: wrap;
diff --git a/src/version.js b/src/version.js
index 082c5ca..e3a2dc0 100644
--- a/src/version.js
+++ b/src/version.js
@@ -1,5 +1,6 @@
 (() => {
-  const version = "1.1.0";
+  const version = "1.2.0";
+  const startHereStorageKey = "git-map-start-here-dismissed";
 
   window.gitMapVersion = version;
 
@@ -10,9 +11,49 @@
     });
   }
 
+  function readDismissed() {
+    try {
+      return window.localStorage.getItem(startHereStorageKey) === "1";
+    } catch {
+      return false;
+    }
+  }
+
+  function writeDismissed() {
+    try {
+      window.localStorage.setItem(startHereStorageKey, "1");
+    } catch {
+      // Ignore storage failures; the callout will reappear next visit.
+    }
+  }
+
+  function setupStartHere(root = document) {
+    const callout = root.querySelector("#start-here");
+    if (!callout) {
+      return;
+    }
+    if (readDismissed()) {
+      callout.hidden = true;
+      return;
+    }
+    callout.hidden = false;
+    const dismiss = root.querySelector("#start-here-dismiss");
+    if (dismiss) {
+      dismiss.addEventListener("click", () => {
+        callout.hidden = true;
+        writeDismissed();
+      });
+    }
+  }
+
+  function init() {
+    applyVersionLabels();
+    setupStartHere();
+  }
+
   if (document.readyState === "loading") {
-    document.addEventListener("DOMContentLoaded", () => applyVersionLabels());
+    document.addEventListener("DOMContentLoaded", init);
   } else {
-    applyVersionLabels();
+    init();
   }
 })();

From 23e0b8993079e2c704dc3b6f9642e9bded89b120 Mon Sep 17 00:00:00 2001
From: Iwan Kelaiah <iwan.kelaiah@gmail.com>
Date: Fri, 15 May 2026 21:38:26 +1000
Subject: [PATCH 2/2] feat(ui): add a smooth animation when the Beginner Daily
 Path banner is clicked

---
 src/styles.css | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/styles.css b/src/styles.css
index 8aa5f44..a1ea5f3 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -117,6 +117,10 @@
   box-sizing: border-box;
 }
 
+html {
+  scroll-behavior: smooth;
+}
+
 body {
   margin: 0;
   min-height: 100vh;