feat: add GUI onboarding walkthrough + README single-session docs

Add a 6-slide first-run onboarding overlay to the GUI (Welcome, How It
Works, Safety Net, One Project at a Time, Token Usage, Ready to Go).
Uses localStorage to show once, dismissible via Skip/Get Started/Escape/
click-outside. Follows existing modal overlay pattern.

Add "One Session at a Time" section to README explaining the
single-session enforcement design (singleton guard + lock file).

Also includes pre-existing fixes: stdin-only prompt delivery in
claude.js (removes -p flag Windows mangling), gui/server.js tweaks.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: VibeWriter User

.claude/memory/claude-integration.md

@@ -9,12 +9,9 @@ Assumes CLAUDE.md loaded. Subprocess wrapper in `src/claude.js`.
 | `DEFAULT_TIMEOUT` | 45 min (2,700,000 ms) — overridable via `--timeout` |
 | `DEFAULT_RETRIES` | 3 (total attempts = 4) |
 | `RETRY_DELAY` | 10,000 ms between retries |
-| `STDIN_THRESHOLD` | 8,000 chars → switches to stdin pipe mode |
+## Prompt Delivery
 
-## Spawn Modes
-
-- **Short** (< 8000 chars): `-p "prompt"` flag, stdin `'ignore'`
-- **Long** (≥ 8000 chars): stdin `'pipe'`, write prompt + end
+All prompts delivered via **stdin pipe** (never `-p` flag). On Windows, `shell: true` causes `cmd.exe` to silently mangle special characters in `-p` arguments. Stdin is binary-safe on all platforms.
 
 ## Platform Rules
 

CLAUDE.md

@@ -106,7 +106,7 @@ test/
 gui/
   server.js                  # Node.js HTTP server + Chrome app-mode launcher
   resources/
-    index.html               # Single-page app with 5 screen sections
+    index.html               # Single-page app with 5 screen sections + first-run onboarding overlay
     styles.css               # Dark theme CSS (extracted from dashboard-html.js)
     logic.js                 # Pure functions (buildCommand, parseCliOutput, formatMs, etc.)
     app.js                   # State machine + fetch API calls to server.js endpoints
@@ -265,7 +265,7 @@ NightyTidy creates these files/artifacts in the project it runs against:
 - **Usage-limit resume**: When a rate limit is detected during an interactive CLI run, state is saved to `nightytidy-run-state.json` (same format as orchestrator mode). The user can close the terminal and resume later with `--resume`. The backoff schedule covers ~9.9 hours total (2min → 5min → 15min → 30min → 1hr → 2hr × 4). GUI's pause overlay includes a "Save & Close" button that exits cleanly for later resume.
 - **Prompt integrity check**: `executor.js` computes SHA-256 of all step prompts and compares against `STEPS_HASH`. After editing any markdown file in `src/prompts/steps/` or `src/prompts/specials/`, recompute and update the hash in `executor.js`. Warns but does not block (user may have legitimate prompt changes).
 - **`--dangerously-skip-permissions`**: Required for non-interactive Claude Code subprocess calls. NightyTidy is the permission layer — it controls what prompts are sent and operates on a safety branch.
-- **Prompt delivery threshold**: Prompts longer than 8000 chars (`STDIN_THRESHOLD` in `claude.js`) are piped via stdin instead of passed as a `-p` argument. This avoids OS command-line length limits. If prompts fail with argument-too-long errors, check this threshold.
+- **Prompt delivery via stdin**: All prompts are piped to Claude Code via stdin (never the `-p` flag). On Windows, `shell: true` causes Node.js to embed `-p` arguments directly in the `cmd.exe` command string, where special characters (`|`, `&`, `(`, `)`, `<`, `>`) get silently mangled. Stdin is binary-safe and immune to shell escaping on all platforms.
 - **Env var allowlist**: `cleanEnv()` in `env.js` uses an explicit allowlist (system paths, locale, Anthropic/Claude/Git prefixes) instead of a blocklist. Unknown env vars are filtered out and logged via `debug()`. `CLAUDECODE` is explicitly blocked. Tests in `env.test.js`.
 - **Branch guard**: `ensureOnBranch()` in `git.js` is called before and after every step execution in `runStep()`. If Claude Code switched to a different branch during a step, it commits any uncommitted work, checks out the run branch, and merges the stray branch back. On merge conflict, the merge is aborted (step work preserved on the stray branch). This prevents the "branch drift" problem where Claude Code creates its own branches, scattering commits across multiple branches.
 - **Gitleaks CI scan**: `.github/workflows/ci.yml` runs `gitleaks/gitleaks-action@v2` on every push/PR to detect committed secrets.

README.md

@@ -50,6 +50,15 @@ A full 33-step run is a serious workload — expect **6 to 8 hours** with Claude
 
 Running fewer steps per session is a perfectly valid workflow — you'll get the same results, just spread over multiple nights.
 
+## One Session at a Time
+
+NightyTidy enforces single-session execution — only one improvement run can be active at a time, whether through the GUI or CLI. This is by design: running multiple concurrent AI sessions against the same codebase would create conflicting changes, broken merges, and unreliable results.
+
+- **GUI**: A singleton guard ensures only one NightyTidy window can be open. Launching again focuses the existing window.
+- **CLI**: An atomic lock file (`nightytidy.lock`) prevents concurrent runs. If a previous run was interrupted, you'll be prompted to override or resume.
+
+If you need to run against multiple projects, use separate terminal sessions — the lock is per-project, not global.
+
 ## Desktop GUI
 
 The GUI is the primary way to use NightyTidy. It wraps the CLI orchestrator in a five-screen visual workflow.

gui/resources/app.js

@@ -86,6 +86,76 @@ let lastRenderedOutput = '';
 let lastOutputChangeTime = 0;
 const WORKING_INDICATOR_DELAY_MS = 8000; // Show after 8s of no output change
 
+// ── Onboarding (first-run walkthrough) ──────────────────────────────
+
+const ONBOARDING_STORAGE_KEY = 'nightytidy-onboarding-seen';
+const ONBOARDING_SLIDE_COUNT = 6;
+let onboardingSlide = 0;
+let onboardingFocusTrapCleanup = null;
+
+function shouldShowOnboarding() {
+  try {
+    return !localStorage.getItem(ONBOARDING_STORAGE_KEY);
+  } catch {
+    return false; // localStorage unavailable — skip onboarding
+  }
+}
+
+function markOnboardingSeen() {
+  try {
+    localStorage.setItem(ONBOARDING_STORAGE_KEY, '1');
+  } catch { /* ignore */ }
+}
+
+function showOnboarding() {
+  onboardingSlide = 0;
+  renderOnboardingSlide();
+  const overlay = document.getElementById('onboarding-overlay');
+  overlay.classList.remove('hidden');
+  onboardingFocusTrapCleanup = trapFocus(overlay.querySelector('.modal'));
+  document.getElementById('btn-onboarding-next').focus();
+}
+
+function dismissOnboarding() {
+  markOnboardingSeen();
+  const overlay = document.getElementById('onboarding-overlay');
+  overlay.classList.add('hidden');
+  if (onboardingFocusTrapCleanup) {
+    onboardingFocusTrapCleanup();
+    onboardingFocusTrapCleanup = null;
+  }
+  document.getElementById('btn-select-folder').focus();
+}
+
+function nextOnboardingSlide() {
+  if (onboardingSlide >= ONBOARDING_SLIDE_COUNT - 1) {
+    dismissOnboarding();
+    return;
+  }
+  onboardingSlide++;
+  renderOnboardingSlide();
+}
+
+function goToOnboardingSlide(index) {
+  if (index < 0 || index >= ONBOARDING_SLIDE_COUNT) return;
+  onboardingSlide = index;
+  renderOnboardingSlide();
+}
+
+function renderOnboardingSlide() {
+  const slides = document.querySelectorAll('.onboarding-slide');
+  slides.forEach((s, i) => {
+    s.classList.toggle('active', i === onboardingSlide);
+  });
+  const dots = document.querySelectorAll('.onboarding-dot');
+  dots.forEach((d, i) => {
+    d.classList.toggle('active', i === onboardingSlide);
+    d.setAttribute('aria-selected', i === onboardingSlide ? 'true' : 'false');
+  });
+  const nextBtn = document.getElementById('btn-onboarding-next');
+  nextBtn.textContent = onboardingSlide === ONBOARDING_SLIDE_COUNT - 1 ? 'Get Started' : 'Next';
+}
+
 // ── State ──────────────────────────────────────────────────────────
 
 const SCREENS = {
@@ -2141,9 +2211,24 @@ function bindEvents() {
     window.close();
   });
 
+  // Onboarding
+  document.getElementById('btn-onboarding-skip').addEventListener('click', dismissOnboarding);
+  document.getElementById('btn-onboarding-next').addEventListener('click', nextOnboardingSlide);
+  document.querySelectorAll('.onboarding-dot').forEach(dot => {
+    dot.addEventListener('click', () => {
+      goToOnboardingSlide(parseInt(dot.dataset.dot, 10));
+    });
+  });
+
   // Keyboard accessibility — Escape key to close drawer and modals
   document.addEventListener('keydown', (e) => {
     if (e.key === 'Escape') {
+      // Onboarding overlay — Escape dismisses
+      const onboardingOverlay = document.getElementById('onboarding-overlay');
+      if (!onboardingOverlay.classList.contains('hidden')) {
+        dismissOnboarding();
+        return;
+      }
       const confirmOverlay = document.getElementById('confirm-stop-overlay');
       if (!confirmOverlay.classList.contains('hidden')) {
         cancelStopRun();
@@ -2157,7 +2242,12 @@ function bindEvents() {
     }
   });
 
-  // Click outside modal to close (confirm dialog only)
+  // Click outside modal to close
+  document.getElementById('onboarding-overlay').addEventListener('click', (e) => {
+    if (e.target.id === 'onboarding-overlay') {
+      dismissOnboarding();
+    }
+  });
   document.getElementById('confirm-stop-overlay').addEventListener('click', (e) => {
     if (e.target.id === 'confirm-stop-overlay') {
       cancelStopRun();
@@ -2357,6 +2447,11 @@ document.addEventListener('DOMContentLoaded', () => {
   bindEvents();
   showScreen(SCREENS.SETUP);
 
+  // Show first-run onboarding (before user can interact with setup)
+  if (shouldShowOnboarding()) {
+    showOnboarding();
+  }
+
   // Start heartbeat systems immediately (fire-and-forget)
   initHeartbeat();
 

gui/resources/index.html

@@ -218,6 +218,60 @@ <h2 id="pause-title">Rate Limit Reached</h2>
     </div>
   </div>
 
+  <!-- ═══ Onboarding Overlay (first-run only) ═══ -->
+  <div class="modal-overlay hidden" id="onboarding-overlay" role="dialog" aria-modal="true" aria-labelledby="onboarding-title">
+    <div class="modal modal-onboarding">
+      <div class="onboarding-slide active" data-slide="0">
+        <div class="onboarding-icon" aria-hidden="true">&#9790;</div>
+        <h2 id="onboarding-title">Welcome to NightyTidy</h2>
+        <p>AI-powered overnight codebase improvement. Pick what to improve, let Claude Code do the work, wake up to cleaner code.</p>
+      </div>
+
+      <div class="onboarding-slide" data-slide="1">
+        <div class="onboarding-icon" aria-hidden="true">&#9881;</div>
+        <h2>How It Works</h2>
+        <p>Choose from 33 improvement steps &mdash; documentation, testing, security, performance, and more. NightyTidy runs each one through Claude Code and generates a detailed report of everything that changed.</p>
+      </div>
+
+      <div class="onboarding-slide" data-slide="2">
+        <div class="onboarding-icon" aria-hidden="true">&#128274;</div>
+        <h2>Built-In Safety Net</h2>
+        <p>Every run creates a git branch and a safety tag before touching your code. If you don't like the changes, one command undoes everything. Your main branch stays untouched until you're ready to merge.</p>
+      </div>
+
+      <div class="onboarding-slide" data-slide="3">
+        <div class="onboarding-icon" aria-hidden="true">&#128736;</div>
+        <h2>One Project at a Time</h2>
+        <p>NightyTidy runs one session at a time &mdash; don't open multiple windows for different repos. Finish one run before starting the next. This prevents conflicts and keeps everything clean.</p>
+      </div>
+
+      <div class="onboarding-slide" data-slide="4">
+        <div class="onboarding-icon" aria-hidden="true">&#9889;</div>
+        <h2>Token Usage</h2>
+        <p>A full 33-step run is very token-heavy. You'll almost certainly need the <strong>Max plan</strong> with plenty of usage left. If you're not on Max, run 8&ndash;10 steps at a time and wait for your limits to reset between batches.</p>
+      </div>
+
+      <div class="onboarding-slide" data-slide="5">
+        <div class="onboarding-icon" aria-hidden="true">&#127769;</div>
+        <h2>Ready to Go</h2>
+        <p>Select a project folder, pick your steps, and let NightyTidy work overnight. If you hit a rate limit mid-run, it pauses automatically &mdash; you can resume later right where you left off.</p>
+      </div>
+
+      <div class="onboarding-nav">
+        <button class="link-btn" id="btn-onboarding-skip" type="button">Skip</button>
+        <div class="onboarding-dots" id="onboarding-dots" role="tablist" aria-label="Onboarding slides">
+          <button class="onboarding-dot active" data-dot="0" role="tab" aria-selected="true" aria-label="Slide 1" type="button"></button>
+          <button class="onboarding-dot" data-dot="1" role="tab" aria-selected="false" aria-label="Slide 2" type="button"></button>
+          <button class="onboarding-dot" data-dot="2" role="tab" aria-selected="false" aria-label="Slide 3" type="button"></button>
+          <button class="onboarding-dot" data-dot="3" role="tab" aria-selected="false" aria-label="Slide 4" type="button"></button>
+          <button class="onboarding-dot" data-dot="4" role="tab" aria-selected="false" aria-label="Slide 5" type="button"></button>
+          <button class="onboarding-dot" data-dot="5" role="tab" aria-selected="false" aria-label="Slide 6" type="button"></button>
+        </div>
+        <button class="btn btn-primary btn-sm" id="btn-onboarding-next" type="button">Next</button>
+      </div>
+    </div>
+  </div>
+
   <script src="/marked.umd.js"></script>
   <script src="/logic.js"></script>
   <script src="/app.js"></script>

gui/resources/styles.css

@@ -878,6 +878,69 @@ body {
   50% { opacity: 0.6; }
 }
 
+/* ── Onboarding (first-run walkthrough) ── */
+.modal-onboarding {
+  max-width: 480px;
+  text-align: center;
+  padding: 36px 32px 24px;
+}
+.onboarding-icon {
+  font-size: 2.8rem;
+  margin-bottom: 16px;
+  line-height: 1;
+}
+.onboarding-slide {
+  display: none;
+}
+.onboarding-slide.active {
+  display: block;
+  animation: onboarding-fade 0.25s ease-out;
+}
+@keyframes onboarding-fade {
+  from { opacity: 0; transform: translateY(8px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+.onboarding-slide h2 {
+  font-size: 1.15rem;
+  color: var(--text);
+  margin-bottom: 12px;
+}
+.onboarding-slide p {
+  color: var(--text-dim);
+  font-size: 0.9rem;
+  line-height: 1.6;
+  margin: 0;
+}
+.onboarding-nav {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-top: 28px;
+  gap: 12px;
+}
+.onboarding-dots {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+.onboarding-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--border);
+  border: none;
+  padding: 0;
+  cursor: pointer;
+  transition: background 0.2s, transform 0.15s;
+}
+.onboarding-dot:hover {
+  background: var(--text-dim);
+}
+.onboarding-dot.active {
+  background: var(--cyan);
+  transform: scale(1.25);
+}
+
 /* ── Side Drawer (step output / report viewer) ── */
 .step-drawer {
   position: fixed;

gui/server.js

@@ -785,8 +785,18 @@ function cleanup() {
   // Singleton check — exit early if another GUI is already running
   const existingUrl = await checkExistingInstance();
   if (existingUrl) {
-    console.log(`NightyTidy GUI is already running at ${existingUrl}`);
-    console.log('Opening existing window...');
+    console.log('');
+    console.log('  ⚠  NightyTidy GUI is already running!');
+    console.log('');
+    console.log('  NightyTidy is designed to work on one project at a time.');
+    console.log('  Running multiple instances can cause conflicts and broken runs.');
+    console.log('');
+    console.log('  If you need to work on a different project, close the existing');
+    console.log('  window first, then start the GUI again.');
+    console.log('');
+    console.log(`  Existing instance: ${existingUrl}`);
+    console.log('  Focusing existing window...');
+    console.log('');
     launchChrome(existingUrl);
     process.exit(0);
   }

src/claude.js

@@ -52,7 +52,6 @@ import { cleanEnv } from './env.js';
 const DEFAULT_TIMEOUT = 45 * 60 * 1000; // 45 minutes
 const DEFAULT_RETRIES = 3;
 const RETRY_DELAY = 10000; // 10 seconds
-const STDIN_THRESHOLD = 8000; // chars
 const SIGKILL_DELAY = 5000; // grace period before SIGKILL after initial kill
 export const INACTIVITY_TIMEOUT_MS = 3 * 60 * 1000; // 3 minutes — no stdout or stderr data
 
@@ -186,35 +185,25 @@ export function sleep(ms, signal) {
  * @returns {import('child_process').ChildProcess} The spawned child process
  */
 function spawnClaude(prompt, cwd, useShell = false, continueSession = false) {
-  const useStdin = prompt.length > STDIN_THRESHOLD;
-
-  // --dangerously-skip-permissions: required for non-interactive mode.
-  // Without it, Claude Code blocks on tool permission prompts (Bash, Edit, etc.)
-  // that cannot be approved without a TTY. NightyTidy is the permission layer —
-  // it controls what prompts are sent and operates on a safety branch.
-  // --output-format stream-json: streams NDJSON events in real-time as the
-  // conversation progresses. Each line is a JSON object (assistant message,
-  // tool use, etc.). The final line is a `result` event with total_cost_usd,
-  // num_turns, duration_api_ms, and the response text in the `result` field.
-  const args = useStdin
-    ? ['--output-format', 'stream-json', '--verbose', '--dangerously-skip-permissions']
-    : ['-p', prompt, '--output-format', 'stream-json', '--verbose', '--dangerously-skip-permissions'];
+  // Always deliver prompts via stdin pipe. The previous approach used the -p flag
+  // for short prompts, but on Windows (shell: true), cmd.exe silently mangles
+  // special characters (|, &, (, ), <, >) in the command string, causing Claude
+  // Code to receive a garbled or empty prompt and fall back to a generic greeting.
+  // Stdin is binary-safe and immune to shell escaping issues on all platforms.
+  const args = ['--output-format', 'stream-json', '--verbose', '--dangerously-skip-permissions'];
   if (continueSession) args.push('--continue');
-  const stdinMode = useStdin ? 'pipe' : 'ignore';
 
-  debug(`Spawn mode: ${useStdin ? 'stdin' : '-p flag'}, prompt length: ${prompt.length} chars`);
+  debug(`Spawn: stdin pipe, prompt length: ${prompt.length} chars`);
 
   const child = spawn('claude', args, {
     cwd,
-    stdio: [stdinMode, 'pipe', 'pipe'],
+    stdio: ['pipe', 'pipe', 'pipe'],
     shell: useShell,
     env: cleanEnv(),
   });
 
-  if (useStdin) {
-    child.stdin.write(prompt);
-    child.stdin.end();
-  }
+  child.stdin.write(prompt);
+  child.stdin.end();
 
   return child;
 }