From 6c36a5e40bac0c3365b3a49a42dd8e6343c14e83 Mon Sep 17 00:00:00 2001
From: saagpatel <saagarpatel08@gmail.com>
Date: Tue, 2 Jun 2026 19:33:17 -0700
Subject: [PATCH] docs: reconcile documentation to current code state
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- README.md: rewrite from template framing to actual Job Command Center
  app (correct title, full v1.0 feature list, Python sidecar in stack,
  pnpm install, Node 20+)
- AGENTS.md: correct app identity (template → JCC), npm → pnpm throughout,
  update verification commands to pnpm equivalents
- CLAUDE.md: fix Portfolio Context "How To Run" block (npm → pnpm)
- docs/CONTRIBUTING.md: Node 18+ → 20+, npm → pnpm throughout
- docs/userguide/userguide.md: full rewrite from template placeholder to
  JCC user guide (Tracker, Submit Console, Follow-up Manager, Interview
  Prep, Analytics, Settings, keyboard shortcuts)
- DOC-RECONCILIATION.md: reconciliation record with all findings
---
 AGENTS.md                   |  14 +--
 CLAUDE.md                   |   8 +-
 DOC-RECONCILIATION.md       | 187 ++++++++++++++++++++++++++++++++++++
 README.md                   | 127 ++++++++++--------------
 docs/CONTRIBUTING.md        |  12 +--
 docs/userguide/userguide.md | 141 +++++++++++++++++++--------
 6 files changed, 356 insertions(+), 133 deletions(-)
 create mode 100644 DOC-RECONCILIATION.md

diff --git a/AGENTS.md b/AGENTS.md
index 70b6285..2098a94 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,7 +2,7 @@
 
 ## Overview
 
-This repository is a template with sensible defaults for building Tauri React apps.
+This repository is **Job Command Center** — a Tauri 2 desktop hub for an automated job-search pipeline (job tracker, ATS submission adapters, Gmail follow-ups, interview prep, analytics). Forked from dannysmith/tauri-template.
 
 ## First Read
 
@@ -14,13 +14,13 @@ This repository is a template with sensible defaults for building Tauri React ap
 
 ## Core Rules
 
-- Use `npm` only. This project does not use `pnpm`.
+- Use `pnpm`. This project does not use `npm`.
 - Read files before editing and follow established repo patterns.
 - Keep changes scoped to the requested task.
 - Consider performance, maintainability, and testability for non-trivial changes.
 - Match existing formatting and code style.
 - Write meaningful tests for business logic.
-- Run `npm run check:all` after significant changes when validation is approved.
+- Run `pnpm run check:all` after significant changes when validation is approved.
 - Do not start a dev server unless the user asks for it or says they will run it.
 - Do not commit unless explicitly requested.
 - Update relevant `docs/developer/` files when adding or changing durable patterns.
@@ -38,7 +38,7 @@ This repository is a template with sensible defaults for building Tauri React ap
 
 ## Static Analysis And Quality
 
-- `npm run check:all` is the main quality gate.
+- `pnpm run check:all` is the main quality gate.
 - `check:all` includes TypeScript, ESLint, ast-grep, Prettier check, Rust fmt/clippy, Vitest, and Rust tests.
 - React Compiler handles memoization; do not add manual `useMemo`, `useCallback`, or `React.memo` unless there is a clear local reason.
 - ast-grep enforces architecture patterns such as no Zustand destructuring.
@@ -72,9 +72,9 @@ This repository is a template with sensible defaults for building Tauri React ap
 
 - `.codex/verify.commands` is the canonical verifier for routine Codex work.
 - Current canonical verifier:
-  - `npm ci`
-  - `npm run check:all`
-  - `npm run build`
+  - `pnpm install --frozen-lockfile`
+  - `pnpm run check:all`
+  - `pnpm run build`
 - If a command is missing, unclear, or unsafe to run, stop and report the blocker instead of guessing.
 
 ## Boundaries
diff --git a/CLAUDE.md b/CLAUDE.md
index 20f04c4..b618211 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -76,9 +76,9 @@ The repo has moved beyond its template origin into a polished v1.0 posture with
 
 ## How To Run
 
-- Use `npm` only; this repo does not use pnpm.
-- Run the app with the documented npm scripts from `package.json`.
-- Run `npm run check:all` after significant changes.
+- Use `pnpm`. This repo does not use `npm` — see the Gotchas section above.
+- Run the app with the documented pnpm scripts from `package.json`.
+- Run `pnpm run check:all` after significant changes.
 - Ask the operator to run the dev server when interactive app feedback is needed.
 
 ## Known Risks
@@ -90,6 +90,6 @@ The repo has moved beyond its template origin into a polished v1.0 posture with
 
 ## Next Recommended Move
 
-Keep the active local branch focused on the existing lockfile/sidecar cleanup, then use `npm run check:all` and targeted sidecar health checks before changing submission automation, Gmail follow-up, or credential behavior.
+Keep the active local branch focused on the existing lockfile/sidecar cleanup, then use `pnpm run check:all` and targeted sidecar health checks before changing submission automation, Gmail follow-up, or credential behavior.
 
 <!-- portfolio-context:end -->
diff --git a/DOC-RECONCILIATION.md b/DOC-RECONCILIATION.md
new file mode 100644
index 0000000..98991f8
--- /dev/null
+++ b/DOC-RECONCILIATION.md
@@ -0,0 +1,187 @@
+# DOC-RECONCILIATION.md
+
+This file was generated by the `/doc-truth-up` documentation-reconciliation pass. The pass treats the code as read-only ground truth and edits only documentation so it reflects the repo's actual current state. No code was changed and no builds or tests were executed. Evidence is derived entirely by reading source files, manifests, test files, and git history.
+
+---
+
+## Per-Claim Findings
+
+### 1. What It Is
+
+**Status: drifted → fixed**
+Evidence: `src-tauri/Cargo.toml:2-3`, `src-tauri/tauri.conf.json:2`, `CHANGELOG.md:1`, all component directories under `src/`.
+
+The `README.md` title and entire framing described the upstream template ("Tauri React Template — a batteries-included template for building production-ready desktop applications") rather than the actual deployed application. The `AGENTS.md` Overview said "This repository is a template with sensible defaults for building Tauri React apps."
+
+**Fixed:**
+- `README.md`: Replaced the template title and framing with the actual app name and description ("Job Command Center — Tauri 2 desktop hub for an automated job-search pipeline").
+- `AGENTS.md` Overview: Replaced "template" identity with the correct app description.
+
+---
+
+### 2. Current State
+
+**Status: drifted → fixed (README, userguide); consistent (CHANGELOG, CLAUDE.md)**
+Evidence: `src/components/tracker/`, `src/components/submit/`, `src/components/followup/`, `src/components/interview/`, `src/components/pipeline/`, `sidecar/src/adapters/`, `sidecar/src/services/`, `CHANGELOG.md:1-36`.
+
+`README.md` listed only the template infrastructure features (Command Palette, Quick Pane, Preferences, etc.) and omitted all ten sessions of JCC v1.0 work: Tracker Board, all seven ATS adapters, Submit Console, Follow-up Manager, Interview Prep, Analytics Dashboard. The `docs/userguide/userguide.md` similarly described only template features, with no mention of the actual application's views.
+
+**Fixed:**
+- `README.md` "What's Built" section: replaced template feature list with the full JCC v1.0 feature set.
+- `docs/userguide/userguide.md`: complete rewrite from template placeholder to JCC user guide covering Tracker, Submit Console, Follow-up Manager, Interview Prep, Analytics, and Settings.
+
+`CHANGELOG.md` accurately documents v1.0.0. `CLAUDE.md` accurately describes v1.0 and the v1.1 backlog. Both left unchanged.
+
+---
+
+### 3. Stack
+
+**Status: drifted → fixed**
+Evidence: `package.json:128-133` (pnpm config), `sidecar/pyproject.toml`, `src-tauri/Cargo.toml:39` (sqlx).
+
+`README.md` Stack table showed only the frontend and desktop layers, omitting the Python sidecar. It also showed "Tauri v2, Rust" without naming the database layer. The actual stack includes a Python 3.12 FastAPI sidecar (port 9876) with Playwright, Anthropic SDK, Gmail OAuth, and ATS clients, plus SQLite via sqlx (not tauri-plugin-sql as originally planned).
+
+**Fixed:**
+- `README.md` Stack table: added Sidecar row (Python 3.12, FastAPI), updated Desktop row to name SQLite/sqlx.
+
+---
+
+### 4. How to Run
+
+**Status: drifted → fixed**
+Evidence: `package.json:127-133` (pnpm `onlyBuiltDependencies` key present), `CLAUDE.md:12` ("pnpm, NOT npm — see Gotchas"), `pnpm-workspace.yaml` present (untracked in git status).
+
+Multiple docs stated the package manager is `npm` when it is actually `pnpm`:
+
+| File | Old claim | Fixed to |
+|---|---|---|
+| `README.md` Quick Start | `npm install` | `pnpm install` |
+| `AGENTS.md` Core Rules | "Use `npm` only. This project does not use `pnpm`." | "Use `pnpm`. This project does not use `npm`." |
+| `AGENTS.md` Static Analysis | `npm run check:all` | `pnpm run check:all` |
+| `AGENTS.md` Verification | `npm ci` / `npm run check:all` / `npm run build` | pnpm equivalents |
+| `CLAUDE.md` Portfolio Context "How To Run" | "Use `npm` only; this repo does not use pnpm." | "Use `pnpm`." |
+| `CLAUDE.md` Portfolio Context "Next Recommended Move" | `npm run check:all` | `pnpm run check:all` |
+| `docs/CONTRIBUTING.md` Setup | `npm install` / `npm run dev` / `npm run check:all` | pnpm equivalents |
+| `docs/CONTRIBUTING.md` Quality Gates | `npm run check:all` | `pnpm run check:all` |
+
+Also fixed: `docs/CONTRIBUTING.md` listed Node.js v18+ as a prerequisite; `package.json:9` specifies `"node": ">=20.0.0"`. Fixed to v20+.
+
+Also fixed: `README.md` Quick Start listed Node.js 18+ — updated to 20+.
+
+---
+
+### 5. Known Risks
+
+**Status: partially consistent, partially unverifiable**
+Evidence: `sidecar/src/adapters/`, `src-tauri/src/commands/credentials.rs`, `CLAUDE.md` Gotchas section.
+
+`CLAUDE.md` accurately documents risks: Playwright fragility, Keychain credential storage, PII logging prohibition, migration immutability, sidecar health edge cases. Left unchanged.
+
+`README.md` had no risk section (template didn't need one). The new README includes credential setup requirements but not a full risk register — consistent with what the code supports without speculating beyond it.
+
+The `CLAUDE.md` Portfolio Context "Known Risks" bullet "Existing local changes touch the lockfile, sidecar binary, and local Claude skills" is **unverifiable** — it references transient local state that cannot be confirmed from the committed code. Left unchanged per policy.
+
+---
+
+### 6. Next Move
+
+**Status: consistent (CLAUDE.md), unverifiable (everywhere else)**
+Evidence: `CLAUDE.md:53-55` (v1.1 backlog list).
+
+`CLAUDE.md` accurately documents the v1.1 backlog (#11–#21) and post-v1.0 ideas. Left unchanged.
+
+`IMPLEMENTATION-ROADMAP.md` and `IMPLEMENTATION-PLAN.md` reflect the original planning arc and are now historical documents — accurate as plans, not as current-state descriptions. Not editable per the doc-truth-up scope; flagged below if drift is found.
+
+---
+
+## Contradictions for Manual Review
+
+These are drifts in files outside the editable scope (`README.md`, `CLAUDE.md`, `AGENTS.md`, `DOC-RECONCILIATION.md`, `docs/`). A human should apply the listed fix.
+
+### `.codex/verify.commands` — wrong package manager
+
+**Path:** `.codex/verify.commands:2-4`
+
+```
+npm ci
+npm run check:all
+npm run build
+```
+
+**Should be:**
+```
+pnpm install --frozen-lockfile
+pnpm run check:all
+pnpm run build
+```
+
+The project uses pnpm. These commands will fail with a missing `npm ci` equivalent and a stale `package-lock.json`.
+
+---
+
+### `src-tauri/tauri.conf.json` — template placeholders and wrong descriptions
+
+**Path:** `src-tauri/tauri.conf.json:51-54`
+
+```json
+"shortDescription": "A Tauri React template application",
+"longDescription": "A modern Tauri React template with comprehensive boilerplate code...",
+```
+
+**Should be:** Descriptions matching the actual app (Job Command Center, automated job-search pipeline).
+
+**Path:** `src-tauri/tauri.conf.json:67`
+
+```
+"https://github.com/YOUR_USERNAME/YOUR_REPO/releases/latest/download/latest.json"
+```
+
+**Should be:** The actual GitHub releases endpoint for this repo. The auto-updater will not work until this is filled in.
+
+---
+
+### `docs/USING_THIS_TEMPLATE.md` — template setup doc should be removed
+
+**Path:** `docs/USING_THIS_TEMPLATE.md:3`
+
+> "This document is specific to the template and should be deleted once you're comfortable with your new project."
+
+The file's own first paragraph says to delete it. Since the project is at v1.0, this file is now dead weight. A human should delete it.
+
+---
+
+### `docs/CONTRIBUTING.md` — template GitHub URL placeholder
+
+**Path:** `docs/CONTRIBUTING.md:16`
+
+```
+git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
+```
+
+**Should be:** The actual GitHub URL for this repo. Cannot be determined from code; unverifiable.
+
+---
+
+### `docs/SECURITY.md` — email placeholder
+
+**Path:** `docs/SECURITY.md` (not read in full, but `docs/USING_THIS_TEMPLATE.md:52` notes it contains `YOUR_SECURITY_EMAIL` placeholder).
+
+**Should be:** A real security contact email.
+
+---
+
+### `CLAUDE.md` — "tauri-plugin-sql" vs sqlx
+
+**Path:** `CLAUDE.md:7`
+
+> "SQLite CRUD via tauri-plugin-sql"
+
+**Actual:** `src-tauri/Cargo.toml:39` shows `sqlx = { version = "0.8", features = ["sqlite", "runtime-tokio"] }` — no `tauri-plugin-sql` dependency. The original `IMPLEMENTATION-ROADMAP.md` planned for `tauri-plugin-sql` but `sqlx` was used instead. This is a minor architectural description inaccuracy in the main CLAUDE.md body; left unchanged here because it does not affect functionality guidance, but a human may want to correct the label.
+
+---
+
+## Footer
+
+**Generated:** 2026-06-02 19:32:05 PDT
+**Branch:** `docs/truth-up-2026-06-02`
+**HEAD sha reconciled against:** `aa2315ec204f6dfe3c4c01d2fc15c6ec82c2d269`
diff --git a/README.md b/README.md
index bbd75e2..f47a6be 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,6 @@
-# Tauri React Template
+# Job Command Center
 
-A "batteries-included" template for building production-ready desktop applications with **Tauri v2**, **React**, and **TypeScript**. Designed with opinionated patterns that help both human developers and AI coding agents build well-architected apps from the start.
-
-## Why This Template?
-
-Most Tauri starters give you a blank canvas. This template gives you a **working application** with patterns already established:
-
-- **Type-safe Rust-TypeScript bridge** via tauri-specta.
-- **Performance patterns enforced by tooling** - all the usual linting plus ast-grep for common anti-patterns
-- **Multi-window architecture** already working (quick pane with global shortcut as a demo)
-- **Cross-platform ready** with platform-specific title bars, window controls, and native menu integration
-- **i18n built-in** with RTL support
+A Tauri 2 desktop hub for an automated job-search pipeline. Tracks job listings, drives application submissions across ATS platforms (Ashby, Greenhouse) and browser-automated portals (LinkedIn, Indeed, Gem, Workday), manages Gmail follow-ups, generates interview-prep briefs, and reports pipeline analytics.
 
 ## Stack
 
@@ -19,95 +9,76 @@ Most Tauri starters give you a blank canvas. This template gives you a **working
 | Frontend | React 19, TypeScript, Vite 7                    |
 | UI       | shadcn/ui v4, Tailwind CSS v4, Lucide React     |
 | State    | Zustand v5, TanStack Query v5                   |
-| Backend  | Tauri v2, Rust                                  |
-| Testing  | Vitest v4, Testing Library                      |
+| Desktop  | Tauri v2, Rust, SQLite (sqlx)                   |
+| Sidecar  | Python 3.12, FastAPI (port 9876)                |
+| Testing  | Vitest v4, Testing Library, pytest              |
 | Quality  | ESLint, Prettier, ast-grep, knip, jscpd, clippy |
 
-## What's Already Built
+## What's Built (v1.0)
 
-The template includes a working application with these features implemented:
+### Job Tracking
 
-### Core Features
+- **Tracker Board** — Kanban board with drag-and-drop across Saved, Applied, Interviewing, Offer, and Rejected columns.
+- **Job Detail Panel** — Per-job notes, submission history, file links, and follow-up timeline.
+- **Add Job Modal** — Company, role, ATS type, apply URL, tier, and source.
 
-- **Command Palette** (`Cmd+K`) - Searchable command launcher with keyboard navigation
-- **Quick Pane** - Global shortcut (`Cmd+Shift+.`) opens a floating window from any app, even fullscreen. Uses native NSPanel on macOS for proper fullscreen overlay behavior.
-- **Keyboard Shortcuts** - Platform-aware shortcuts with automatic menu integration
-- **Native Menus** - File, Edit, View menus built from JavaScript with full i18n support
-- **Preferences System** - Settings dialog with Rust-side persistence, React hooks, and type-safe access throughout
-- **Collapsible Sidebars** - Empty left and right sidebars with state persistence via resizable panels
-- **Theme System** - Light/dark mode with system preference detection, synced across windows
-- **Notifications** - Toast notifications for in-app feedback, plus native system notifications
-- **Auto-updates** - Tauri updater plugin configured with GitHub Releases integration and update checking on launch
-- **Logging** - Structured logging utilities for both Rust and TypeScript with consistent formatting
-- **Crash Recovery** - Emergency data persistence for recovering unsaved work after unexpected exits
+### Application Submission
 
-### Architecture Patterns
+- **Ashby adapter** — API-direct submission with dry-run preview and field mapping.
+- **Greenhouse adapter** — API-direct submission with automatic field detection.
+- **LinkedIn Easy Apply** — Playwright automation with AI-assisted field mapping and pause-before-submit.
+- **Indeed, Gem, Workday, Generic adapters** — Playwright form automation with CAPTCHA-pause mode.
+- **Submit Console** — Batch submission UI with real-time SSE streaming and per-job status.
 
-- **Three-layer state management** - Clear decision tree: `useState` (component) → `Zustand` (global UI) → `TanStack Query` (persistent data "not owned by the app)
-- **Event-driven Rust-React bridge** - Menus, shortcuts, and command palette all route through the same command system
-- **React Compiler** - Automatic memoization means no manual `useMemo`/`useCallback` needed
+### Intelligence
 
-### Cross-Platform
+- **Follow-up Manager** — Auto-schedules follow-ups at +7 days after Apply, drafts via Claude AI, sends via Gmail OAuth.
+- **Interview Prep** — AI-generated brief (company overview, likely questions, talking points) auto-triggered on status → Interviewing.
+- **Analytics Dashboard** — Applications by week, pipeline funnel, response rate, days-to-response, ATS breakdown.
 
-| Platform | Title Bar            | Window Controls | Bundle Format |
-| -------- | -------------------- | --------------- | ------------- |
-| macOS    | Custom with vibrancy | Traffic lights  | `.dmg`        |
-| Windows  | Custom               | Right side      | `.msi`        |
-| Linux    | Native + toolbar     | Native          | `.AppImage`   |
+### Infrastructure
 
-Platform detection utilities, platform-specific UI strings ("Reveal in Finder" vs "Show in Explorer"), and separate Tauri configs per platform are all set up.
+- **Python sidecar** — FastAPI on `127.0.0.1:9876`, started and health-monitored by the Rust backend. Hosts the submission engine, Playwright sessions, Gmail OAuth, and Anthropic SDK.
+- **Credentials vault** — ATS credentials and API keys stored in macOS Keychain.
+- **Profile management** — Contact info and resume path used to pre-fill submission forms.
+- **Command Palette** (`Cmd+K`), **Quick Pane** (`Cmd+Shift+.`), theme, preferences, native menus, auto-updates.
 
-### Developer Experience
-
-- **Type-safe Tauri commands** - tauri-specta generates TypeScript bindings from Rust, with full autocomplete and compile-time checking
-- **Static analysis** - ESLint, Prettier, ast-grep (architecture enforcement), knip (unused code), jscpd (duplication)
-- **Single quality gate** - `npm run check:all` runs TypeScript, ESLint, Prettier, ast-grep, clippy, and all tests
-- **Testing patterns** - Vitest setup with Tauri command mocking
-
-## Tauri Plugins Included
+## Getting Started
 
-| Plugin            | Purpose                          |
-| ----------------- | -------------------------------- |
-| single-instance   | Prevent multiple app instances   |
-| window-state      | Remember window position/size    |
-| fs                | File system access               |
-| dialog            | Native open/save dialogs         |
-| notification      | System notifications             |
-| clipboard-manager | Clipboard access                 |
-| global-shortcut   | System-wide keyboard shortcuts   |
-| updater           | In-app auto-updates              |
-| opener            | Open URLs/files with default app |
-| tauri-nspanel     | macOS floating panel behavior    |
+### Prerequisites
 
-## AI-Ready Development
+- Node.js 20+ and pnpm
+- Rust (latest stable) — [rustup.rs](https://rustup.rs/)
+- Python 3.12+
 
-This template is designed to work well with AI coding agents like Claude Code:
+```bash
+# Install JS dependencies
+pnpm install
 
-- **Comprehensive documentation** in `docs/developer/` covering all patterns. Human readable but really designed to explain the "why" of certain patterns to AI agents. Not slop.
-- **Claude Code integration** - Custom commands (`/check`, `/cleanup`) and a couple of specialized agents
-- **Sensible file organization** - React code in `src/` with clear separation (components, hooks, stores, services), Rust in `src-tauri/src/` with modular command organization. Predictable structure for both humans and AI.
+# Install Python sidecar
+cd sidecar && pip install -e ".[test]" && cd ..
 
-## Getting Started
+# One-time: install Playwright browser
+playwright install chromium
 
-See **[Using This Template](docs/USING_THIS_TEMPLATE.md)** for setup instructions and workflow guidance.
+# Run quality gate
+pnpm run check:all
+```
 
-### Quick Start
+Ask the operator to start the dev server (`pnpm run tauri:dev`) when interactive feedback is needed.
 
-```bash
-# Prerequisites: Node.js 18+, Rust (latest stable)
-# See https://tauri.app/start/prerequisites/ for platform-specific deps
+### Credentials Setup
 
-git clone <your-repo>
-cd your-app
-npm install
-npm run dev
-```
+- **Anthropic API key** — Settings → Credentials (stored in macOS Keychain)
+- **Ashby API key** — Settings → Credentials (stored in macOS Keychain)
+- **Gmail** — Place `client_secrets.json` at `~/.jcc/gmail/client_secrets.json` (OAuth2, `gmail.send` scope)
 
 ## Documentation
 
-- **[Developer Docs](docs/developer/)** - Architecture, patterns, and detailed guides
-- **[User Guide](docs/userguide/)** - End-user documentation template
-- **[Using This Template](docs/USING_THIS_TEMPLATE.md)** - Setup and workflow guide
+- **[Developer Docs](docs/developer/)** — Architecture, patterns, and detailed guides
+- **[User Guide](docs/userguide/)** — End-user documentation
+- **[LinkedIn Bot Detection](docs/LINKEDIN-BOT-DETECTION.md)** — Notes on handling LinkedIn automation challenges
+- **[Changelog](CHANGELOG.md)** — Release history
 
 ## License
 
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 226a5e4..62ab258 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -6,7 +6,7 @@ Thank you for your interest in contributing!
 
 ### Prerequisites
 
-- [Node.js](https://nodejs.org/) (v18+)
+- [Node.js](https://nodejs.org/) (v20+)
 - [Rust](https://rustup.rs/) (latest stable)
 - Familiarity with React, TypeScript, and Rust
 
@@ -15,9 +15,9 @@ Thank you for your interest in contributing!
 ```bash
 git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
 cd YOUR_REPO
-npm install
-npm run dev
-npm run check:all
+pnpm install
+pnpm run dev
+pnpm run check:all
 ```
 
 ## How to Contribute
@@ -33,7 +33,7 @@ npm run check:all
 1. Fork the repository
 2. Create a feature branch: `git checkout -b feature/amazing-feature`
 3. Make changes following the guidelines below
-4. Ensure checks pass: `npm run check:all`
+4. Ensure checks pass: `pnpm run check:all`
 5. Commit using conventional commits
 6. Push and open a Pull Request
 
@@ -60,7 +60,7 @@ All PRs must pass:
 - Rust formatting and clippy
 - Tests
 
-Run locally: `npm run check:all`
+Run locally: `pnpm run check:all`
 
 ## Commit Messages
 
diff --git a/docs/userguide/userguide.md b/docs/userguide/userguide.md
index 6592c2f..d4d389e 100644
--- a/docs/userguide/userguide.md
+++ b/docs/userguide/userguide.md
@@ -1,65 +1,130 @@
-# App User Guide
+# Job Command Center — User Guide
 
 ## Getting Started
 
-Welcome! This guide covers the core features available in the app.
+Job Command Center is a desktop app for automating your job search. It tracks applications on a Kanban board, submits to ATS platforms automatically, drafts follow-up emails, generates interview prep briefs, and shows pipeline analytics.
+
+## Navigation
+
+The left sidebar has six views, each reachable by keyboard shortcut:
+
+| Shortcut | View              |
+| -------- | ----------------- |
+| Cmd+1    | Tracker           |
+| Cmd+2    | Submit Console    |
+| Cmd+3    | Follow-up Manager |
+| Cmd+4    | Interview Prep    |
+| Cmd+5    | Analytics         |
+| Cmd+6    | Settings          |
+
+Toggle the sidebars: **Cmd+[** (left) / **Cmd+]** (right).
 
 ## Keyboard Shortcuts
 
-### Global Shortcuts
+### Global
 
-| Shortcut        | Mac          | Windows/Linux | Action                |
-| --------------- | ------------ | ------------- | --------------------- |
-| Command Palette | Cmd+K        | Ctrl+K        | Open command palette  |
-| Preferences     | Cmd+,        | Ctrl+,        | Open preferences      |
-| Quick Pane      | Configurable | Configurable  | Open quick entry pane |
-| Left Sidebar    | Cmd+1        | Ctrl+1        | Toggle left sidebar   |
-| Right Sidebar   | Cmd+2        | Ctrl+2        | Toggle right sidebar  |
+| Action          | Mac          | Windows/Linux |
+| --------------- | ------------ | ------------- |
+| Command Palette | Cmd+K        | Ctrl+K        |
+| Preferences     | Cmd+,        | Ctrl+,        |
+| Quick Pane      | Configurable | Configurable  |
 
-## Core Features
+## Tracker
 
-### Command Palette
+The Tracker is your Kanban board. Jobs move through five columns: **Saved → Applied → Interviewing → Offer → Rejected**.
 
-Press **Cmd+K** to open the command palette - a quick way to find and run any action. Start typing to search through available commands.
+- **Add a job**: click the + button or use the Command Palette.
+- **Move a job**: drag its card to a new column. Status updates automatically.
+- **Job detail**: click a card to open the detail panel — edit notes, view submission history, open the resume file, and see the follow-up timeline.
+- **Archive**: drag to Rejected or use the card menu to archive.
 
-### Quick Pane
+## Submit Console
 
-The Quick Pane is a small floating window that can be summoned with a global keyboard shortcut, even when the app is in the background. Use it for quick data entry or actions without switching to the main window.
+Select jobs from the Tracker and submit them in batch.
 
-Configure the Quick Pane shortcut in **Preferences → Keyboard Shortcuts**.
+1. Check the boxes on one or more Saved or Applied jobs.
+2. Click **Dry Run** to preview the field mapping and catch warnings without submitting.
+3. Click **Submit Selected** to submit. Progress streams in real time per job.
+4. Results show green (success), yellow (manual action required), or red (failed).
+5. On success the job status moves to Applied automatically and a follow-up is scheduled.
 
-### Preferences
+### ATS Adapters
+
+| Platform   | Method            | Notes                                          |
+| ---------- | ----------------- | ---------------------------------------------- |
+| Ashby      | API               | Requires Ashby API key in Settings → Credentials |
+| Greenhouse | API               | Public GETs; POST may require API key          |
+| LinkedIn   | Playwright        | Login first in Settings → Platforms; pauses before final submit |
+| Indeed     | Playwright        | Login first in Settings → Platforms            |
+| Gem        | Playwright        | Standard form fill                             |
+| Workday    | Playwright        | Multi-page flow; returns manual_required on CAPTCHA |
+| Generic    | Playwright        | Heuristic label matching with Claude AI fallback |
+
+## Follow-up Manager
+
+Follow-ups are auto-created when a job moves to Applied (+7 days by default).
+
+1. Open **Follow-up Manager** (Cmd+3).
+2. Click a pending follow-up to see the AI-drafted email (subject + body).
+3. Edit the draft inline if needed, or click **Regenerate** for a new draft.
+4. Click **Send** to dispatch via Gmail. The job's detail timeline updates.
+5. Click **Skip** to dismiss without sending.
+
+**Gmail setup required**: place `client_secrets.json` at `~/.jcc/gmail/client_secrets.json` and authenticate via Settings → Credentials.
+
+## Interview Prep
 
-Press **Cmd+,** to open preferences:
+A brief is auto-generated when a job status moves to **Interviewing**.
 
-- **Theme**: Light, Dark, or System
-- **Language**: Select your preferred language
-- **Keyboard Shortcuts**: Customize the Quick Pane shortcut
+- Open **Interview Prep** (Cmd+4) and select a job.
+- The brief covers company overview, recent news, likely questions, talking points, and red flags to probe.
+- Edit the notes section below the brief for your own additions.
+- Click **Regenerate** to get a fresh brief from Claude AI.
 
-### Native Menus
+## Analytics
 
-Access features from the menu bar:
+Open **Analytics** (Cmd+5) for a visual overview of your pipeline:
 
-- **App Menu**: About, Check for Updates, Preferences, Quit
-- **View Menu**: Toggle sidebars
+- Applications by week (bar chart)
+- Pipeline funnel: Saved → Applied → Interviewing → Offer
+- Response rate and average days to first response
+- Submissions by ATS platform (pie chart)
+- Tier 1 vs Tier 2 comparison
 
-All menu items have keyboard shortcuts and are also available in the command palette.
+## Settings
 
-## Layout
+Open **Settings** (Cmd+6) for three tabs:
 
-- **Title Bar**: Window controls and app title
-- **Left Sidebar**: Collapsible panel (Cmd+1)
-- **Main Content**: Primary app content
-- **Right Sidebar**: Collapsible panel (Cmd+2)
+### Profile
 
-## Updates
+Name, contact info, LinkedIn URL, location, authorization status, and base resume path. This data pre-fills submission forms.
 
-The app checks for updates automatically:
+### Credentials
+
+- **Anthropic API key** — used for follow-up drafts and interview prep briefs.
+- **Ashby API key** — required for Ashby submissions.
+- **Gmail** — authenticate OAuth to enable follow-up sending.
+
+All secrets are stored in macOS Keychain, never on disk.
+
+### Platforms
+
+Log in to LinkedIn and Indeed to enable Playwright sessions. Session state persists across app restarts.
+
+## Global Features
+
+### Command Palette
+
+Press **Cmd+K** to open the command palette — search and trigger any action.
+
+### Quick Pane
+
+A floating window summoned by a global shortcut (configurable in Preferences → Keyboard Shortcuts), available even when the app is in the background or another app is fullscreen.
+
+### Preferences
 
-- Manual check: App menu → Check for Updates
-- Updates download from GitHub releases
-- You'll be notified when updates are available
+Press **Cmd+,** to set theme (Light / Dark / System), language, and keyboard shortcuts.
 
----
+### Auto-updates
 
-_This user guide should be expanded as new features are added to the app._
+The app checks for updates on launch. Manual check: App menu → Check for Updates.