feat(v1.2.0): add start-here callout and refine risk guidance

.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node scripts/validate.mjs)"
+    ]
+  }
+}

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

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.
 

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>

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>

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",

src/styles.css

@@ -117,6 +117,10 @@
   box-sizing: border-box;
 }
 
+html {
+  scroll-behavior: smooth;
+}
+
 body {
   margin: 0;
   min-height: 100vh;
@@ -187,6 +191,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;

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();
   }
 })();