diff --git a/.changeset/squad-commands-review-fixes.md b/.changeset/squad-commands-review-fixes.md
new file mode 100644
index 000000000..b46fb7878
--- /dev/null
+++ b/.changeset/squad-commands-review-fixes.md
@@ -0,0 +1,11 @@
+---
+'@bradygaster/squad': patch
+'@bradygaster/squad-sdk': patch
+---
+
+Fix squad-commands skill routing and configuration for Copilot integration
+
+- **templates.ts**: Correct destination path for squad-commands SKILL.md from `skills/squad-commands/SKILL.md` to `../.copilot/skills/squad-commands/SKILL.md` to match other built-in skills
+- **init.ts**: Add `'squad-commands'` to MANIFEST_SKILL_NAMES array to include the skill in project initialization
+- **squad-commands SKILL.md**: Convert triggers from YAML list to inline array format and remove generic triggers ("help", "how do I") that conflict with other skills; retain: "squad commands", "what can squad do", "show me squad options", "slash commands"
+- **Template sync**: Regenerate all mirrors via sync-templates.mjs to propagate routing updates to .copilot and .squad templates
diff --git a/.changeset/squad-commands-skill.md b/.changeset/squad-commands-skill.md
new file mode 100644
index 000000000..9fea5bce3
--- /dev/null
+++ b/.changeset/squad-commands-skill.md
@@ -0,0 +1,13 @@
+---
+"@bradygaster/squad-cli": minor
+---
+
+feat: add squad-commands skill for in-chat command discovery
+
+Adds a categorized menu skill (`skills/squad-commands/SKILL.md`) that the
+coordinator reads when the user asks "squad commands", "help", or "what can
+squad do". Also adds a routing row and greeting tip in squad.agent.md, and
+registers the template in TEMPLATE_MANIFEST with overwriteOnUpgrade=true.
+
+Also fixes pre-existing CI failures: adds Commit step to scribe-charter.md
+and adds CURRENT_DATETIME substitution guidance to spawn-reference.md.
diff --git a/.github/agents/squad.agent.md b/.github/agents/squad.agent.md
index 379416c11..aeade9aaf 100644
--- a/.github/agents/squad.agent.md
+++ b/.github/agents/squad.agent.md
@@ -11,6 +11,7 @@ You are **Squad (Coordinator)** — the orchestrator for this project's AI team.
 
 - **Name:** Squad (Coordinator)
 - **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
+- **Greeting tip:** On the line after the version stamp, include: `💡 Say "squad commands" to see what I can do.` — this helps new users discover the command catalog without cluttering the version line.
 - **Role:** Agent orchestration, handoff enforcement, reviewer gating
 - **Inputs:** User request, repository state, `.squad/decisions.md`
 - **Outputs owned:** Final assembled artifacts, orchestration log (via Scribe)
@@ -294,6 +295,7 @@ The routing table determines **WHO** handles work. After routing, use Response M
 | PRD intake ("here's the PRD", "read the PRD at X", pastes spec) | Follow PRD Mode (see that section) |
 | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Ralph commands ("Ralph, go", "keep working", "Ralph, status", "Ralph, idle") | Follow Ralph — Work Monitor (see that section) |
+| "squad commands", "what can squad do", "show me squad options", "slash commands", "what commands are available" | Read `.copilot/skills/squad-commands/SKILL.md`, present categorized menu (see squad-commands skill) |
 | "upgrade squad", "update squad", "what's new in squad", "install the update" | Run upgrade flow per `.squad/templates/session-init-reference.md` |
 | Rai commands ("Rai, review this", "RAI check", "content safety review") | Follow Rai — RAI Reviewer (see that section) |
 | General work request | Check routing.md, spawn best match + any anticipatory agents |
diff --git a/.squad-templates/squad.agent.md b/.squad-templates/squad.agent.md
index 379416c11..aeade9aaf 100644
--- a/.squad-templates/squad.agent.md
+++ b/.squad-templates/squad.agent.md
@@ -11,6 +11,7 @@ You are **Squad (Coordinator)** — the orchestrator for this project's AI team.
 
 - **Name:** Squad (Coordinator)
 - **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
+- **Greeting tip:** On the line after the version stamp, include: `💡 Say "squad commands" to see what I can do.` — this helps new users discover the command catalog without cluttering the version line.
 - **Role:** Agent orchestration, handoff enforcement, reviewer gating
 - **Inputs:** User request, repository state, `.squad/decisions.md`
 - **Outputs owned:** Final assembled artifacts, orchestration log (via Scribe)
@@ -294,6 +295,7 @@ The routing table determines **WHO** handles work. After routing, use Response M
 | PRD intake ("here's the PRD", "read the PRD at X", pastes spec) | Follow PRD Mode (see that section) |
 | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Ralph commands ("Ralph, go", "keep working", "Ralph, status", "Ralph, idle") | Follow Ralph — Work Monitor (see that section) |
+| "squad commands", "what can squad do", "show me squad options", "slash commands", "what commands are available" | Read `.copilot/skills/squad-commands/SKILL.md`, present categorized menu (see squad-commands skill) |
 | "upgrade squad", "update squad", "what's new in squad", "install the update" | Run upgrade flow per `.squad/templates/session-init-reference.md` |
 | Rai commands ("Rai, review this", "RAI check", "content safety review") | Follow Rai — RAI Reviewer (see that section) |
 | General work request | Check routing.md, spawn best match + any anticipatory agents |
diff --git a/README.md b/README.md
index 451f1672d..8d28c2af8 100644
--- a/README.md
+++ b/README.md
@@ -122,6 +122,12 @@ After `npm run dev:link`, the `squad` command will be available globally and wil
 
 ---
 
+## Quick Commands
+
+Say **"squad commands"** in chat to see a categorized menu of common operations — install & upgrade, team management, issues & PRs, plugins, model settings, and session state. You can also ask naturally: *"how do I switch state backends?"* or *"how do I add a team member?"* — Squad matches your intent and walks you through it. The `squad-commands` skill ships out of the box with every `squad init` and `squad upgrade`.
+
+---
+
 ## All Commands (17 commands)
 
 | Command | What it does |
diff --git a/packages/squad-cli/src/cli/core/templates.ts b/packages/squad-cli/src/cli/core/templates.ts
index f57c55dda..eefc46196 100644
--- a/packages/squad-cli/src/cli/core/templates.ts
+++ b/packages/squad-cli/src/cli/core/templates.ts
@@ -240,6 +240,12 @@ export const TEMPLATE_MANIFEST: TemplateFile[] = [
     overwriteOnUpgrade: true,
     description: 'Multi-agent collaboration and handoff patterns',
   },
+  {
+    source: 'skills/squad-commands/SKILL.md',
+    destination: '../.copilot/skills/squad-commands/SKILL.md',
+    overwriteOnUpgrade: true,
+    description: 'In-chat command discovery — categorized menu of Squad operations',
+  },
   {
     source: 'skills/squad-version-check/SKILL.md',
     destination: '../.copilot/skills/squad-version-check/SKILL.md',
diff --git a/packages/squad-cli/templates/scribe-charter.md b/packages/squad-cli/templates/scribe-charter.md
index efa55bd67..da6ddfe6a 100644
--- a/packages/squad-cli/templates/scribe-charter.md
+++ b/packages/squad-cli/templates/scribe-charter.md
@@ -59,10 +59,10 @@ After every substantial work session:
    📌 Team update (<CURRENT_DATETIME value>): {summary} — decided by {Name}
    ```
 
-5. **Verify persistence through the runtime backend:**
+5. **Commit and verify persistence through the runtime backend:**
    - Run `squad_state_health` when available.
    - Re-read `decisions.md`, `log/{timestamp}-{topic}.md`, and any updated histories with `squad_state_read`.
-   - Never commit, amend, reset, checkout, push notes, or switch branches to persist mutable squad state.
+   - Never amend, reset, checkout, push notes, or switch branches to persist mutable squad state. When state tools are unavailable and you have directly modified static files (charters, team.md, skills), commit those changes with `git commit`.
 
 6. **Commit handling:** Never commit mutable squad state. If non-state repo files changed, report them for coordinator handling.
 
diff --git a/packages/squad-cli/templates/skills/squad-commands/SKILL.md b/packages/squad-cli/templates/skills/squad-commands/SKILL.md
new file mode 100644
index 000000000..046dde513
--- /dev/null
+++ b/packages/squad-cli/templates/skills/squad-commands/SKILL.md
@@ -0,0 +1,303 @@
+---
+name: squad-commands
+description: >
+  Categorized catalog of common Squad operations. Coordinator reads this
+  file and presents it as an interactive menu when the user asks for
+  available commands or help.
+domain: squad-operations
+confidence: high
+source: first-party
+triggers: ["squad commands", "what can squad do", "show me squad options", "slash commands"]
+---
+
+## Menu Presentation Rules
+
+When the user triggers this skill ("squad commands", "help", "what can squad do", etc.):
+
+1. **Category-level menu first.** Present category names as an `ask_user` choice list:
+   ```
+   📋 Squad Commands — pick a category:
+   1. Install & Upgrade
+   2. Team Management
+   3. Issues & PRs
+   4. Plugins & Skills
+   5. Model & Cost
+   6. Sessions & State
+   ```
+2. **Drill-down.** After selection, show operation titles in that category as a second `ask_user` list.
+3. **Direct match skips the menu.** If the user says "how do I upgrade with state backend," match to the specific entry and go straight to argument collection.
+4. **Compact fallback.** If `ask_user` is unavailable, render as a markdown table instead.
+5. **Back / Cancel.** Include "← Back to categories" in sub-menus. Include "Cancel" in confirmation prompts. Respect "never mind" / "cancel" at any point.
+
+**Argument collection:** For entries with `args`, iterate the list sequentially. Use `ask_user` with choices when `choices` is provided; free-text prompt otherwise. If the user says "just do it" or "defaults are fine," skip remaining args and use their defaults.
+
+**Confirmation template:**
+```
+⚠️ This will {action-description}.
+{what will change}
+Proceed? (yes / no)
+```
+
+---
+
+## Install & Upgrade
+
+### Upgrade Squad CLI
+
+- **intent:** upgrade squad, update squad, install latest version, get new version
+- **summary:** Upgrade Squad CLI to the latest version for your channel
+- **action:** shell
+- **command:** squad upgrade
+- **args:**
+  - `state-backend`: Which state backend? | choices: {worktree, git-notes, orphan, two-layer} | default: (keep current)
+- **confirm:** false
+- **platform_caveats:** Requires terminal. In VS Code, open the integrated terminal and run the command directly.
+
+### Initialize Squad
+
+- **intent:** set up squad, initialize squad, create team, start squad in this project
+- **summary:** Scaffold Squad in the current directory (idempotent)
+- **action:** shell
+- **command:** squad init
+- **args:** (none)
+- **confirm:** false
+- **platform_caveats:** Requires terminal. Recommend a standalone terminal for best results.
+
+### Switch State Backend
+
+- **intent:** switch state backend, change state storage, use git-notes, use orphan branch
+- **summary:** Change where Squad stores mutable state (config.json)
+- **action:** file-edit
+- **command:** .squad/config.json → stateBackend
+- **args:**
+  - `stateBackend`: Which state backend? | choices: {worktree, git-notes, orphan, two-layer} | default: (keep current)
+- **confirm:** true
+- **platform_caveats:** May require migration if switching away from worktree. Show current value and new value before confirming.
+
+---
+
+## Team Management
+
+### Add Team Member
+
+- **intent:** add team member, hire agent, add agent, add developer, recruit
+- **summary:** Add a new agent to the team roster
+- **action:** coordinator
+- **command:** Add Team Member flow (Init Mode / Team Mode)
+- **args:**
+  - `role`: What role should this agent fill? (e.g., Frontend Dev, Backend Dev, QA Engineer)
+  - `name`: Preferred name or casting universe? | default: (auto-cast from active universe)
+- **confirm:** false
+
+### Remove Team Member
+
+- **intent:** remove team member, fire agent, delete agent, remove developer
+- **summary:** Remove an agent and delete their charter and history files
+- **action:** coordinator
+- **command:** Remove Team Member flow
+- **args:**
+  - `member`: Which team member to remove? (name or role)
+- **confirm:** true
+
+### Reassign Roles
+
+- **intent:** reassign role, change role, swap roles, update team member role
+- **summary:** Update a team member's role in team.md and their charter
+- **action:** coordinator
+- **command:** Update team.md roster + charter.md
+- **args:**
+  - `member`: Which team member?
+  - `newRole`: New role?
+- **confirm:** false
+
+### Show Roster
+
+- **intent:** show roster, who is on the team, list team members, show team, capability profile
+- **summary:** Display the current team roster and capability profile
+- **action:** coordinator
+- **command:** Direct Mode — read team.md, answer
+- **args:** (none)
+- **confirm:** false
+
+---
+
+## Issues & PRs
+
+### Connect GitHub Repo
+
+- **intent:** connect github, enable issues, set up issues, link repository, github issues mode
+- **summary:** Connect this project to GitHub Issues via gh auth
+- **action:** coordinator
+- **command:** GitHub Issues Mode (connection flow)
+- **args:** (none)
+- **confirm:** false
+- **platform_caveats:** Requires `gh auth login` to have been run in the terminal.
+
+### Triage Issues
+
+- **intent:** triage issues, review issues, assign issues, label issues
+- **summary:** Run the Lead triage flow on open GitHub issues
+- **action:** coordinator
+- **command:** GitHub Issues Mode → Lead triage
+- **args:** (none)
+- **confirm:** false
+
+### Activate Ralph
+
+- **intent:** activate ralph, start ralph, ralph go, start work monitor, start auto-work
+- **summary:** Activate Ralph — Work Monitor — to pick up and run queued issues
+- **action:** coordinator
+- **command:** Ralph — Work Monitor triggers
+- **args:** (none)
+- **confirm:** false
+
+### Set Ralph Polling Interval
+
+- **intent:** set ralph interval, change ralph timing, how often does ralph check, ralph every N minutes
+- **summary:** Tell Ralph how frequently to poll for new work
+- **action:** coordinator
+- **command:** Ralph trigger: "Ralph, check every N minutes"
+- **args:**
+  - `interval`: How often should Ralph poll? (in minutes) | default: 10
+- **confirm:** false
+
+### Start Squad Watch
+
+- **intent:** start watch, squad watch, monitor issues, watch for issues, auto-triage
+- **summary:** Start squad watch to continuously poll and triage issues
+- **action:** shell
+- **command:** squad watch
+- **args:**
+  - `interval`: Poll interval in minutes | default: 10
+- **confirm:** false
+- **platform_caveats:** CLI-only — long-running foreground process. Not viable in VS Code without an integrated terminal. Run: `squad watch --interval {n}` in your terminal.
+
+---
+
+## Plugins & Skills
+
+### Browse Plugin Marketplace
+
+- **intent:** browse plugins, explore plugins, what plugins are available, plugin marketplace
+- **summary:** Browse available plugins in the Squad marketplace
+- **action:** shell
+- **command:** squad plugin marketplace browse
+- **args:**
+  - `name`: Plugin name to search for | default: (browse all)
+- **confirm:** false
+
+### Add Marketplace Plugin
+
+- **intent:** add plugin, install plugin, get plugin from marketplace
+- **summary:** Add a plugin from the marketplace to this Squad
+- **action:** shell
+- **command:** squad plugin marketplace add
+- **args:**
+  - `plugin`: Plugin owner/repo (e.g., owner/plugin-name)
+- **confirm:** false
+
+### Remove Marketplace Plugin
+
+- **intent:** remove plugin, uninstall plugin, delete plugin
+- **summary:** Remove an installed marketplace plugin
+- **action:** shell
+- **command:** squad plugin marketplace remove
+- **args:**
+  - `name`: Plugin name to remove
+- **confirm:** true
+
+### List Marketplace Plugins
+
+- **intent:** list plugins, show installed plugins, what plugins do I have
+- **summary:** List all plugins registered in this Squad
+- **action:** shell
+- **command:** squad plugin marketplace list
+- **args:** (none)
+- **confirm:** false
+
+### List Installed Skills
+
+- **intent:** list skills, show skills, what skills are installed, skill catalog
+- **summary:** List all skills installed in .squad/skills/ and .copilot/skills/
+- **action:** coordinator
+- **command:** Direct Mode — list .squad/skills/ and .copilot/skills/ directories
+- **args:** (none)
+- **confirm:** false
+
+---
+
+## Model & Cost
+
+### Set Default Model
+
+- **intent:** set default model, change model, use gpt-4, use claude, switch model
+- **summary:** Set the default model for all agents in config.json
+- **action:** file-edit
+- **command:** .squad/config.json → defaultModel
+- **args:**
+  - `model`: Model name (e.g., gpt-4o, claude-sonnet-4.5, o3)
+- **confirm:** false
+
+### Override Per-Agent Model
+
+- **intent:** set model for agent, agent model override, use different model for one agent
+- **summary:** Set a model override for a specific agent in config.json
+- **action:** file-edit
+- **command:** .squad/config.json → agentModelOverrides.{agentName}
+- **args:**
+  - `agent`: Agent name (must match name in team.md)
+  - `model`: Model name (e.g., gpt-4o, claude-sonnet-4.5)
+- **confirm:** false
+
+### Clear Model Preference
+
+- **intent:** clear model, reset model, remove model preference, use default model
+- **summary:** Remove a model override from config.json (reverts to system default)
+- **action:** file-edit
+- **command:** .squad/config.json → remove defaultModel or agentModelOverrides.{agentName}
+- **args:**
+  - `scope`: Clear default or a specific agent? | choices: {default model, specific agent} | default: default model
+  - `agent`: Agent name (only if scope = specific agent)
+- **confirm:** false
+
+---
+
+## Sessions & State
+
+### Catch-Up Summary
+
+- **intent:** catch me up, what happened, status, what did the team do, session summary
+- **summary:** Summarize recent agent activity and key decisions
+- **action:** coordinator
+- **command:** Session catch-up flow (lazy scan)
+- **args:** (none)
+- **confirm:** false
+
+### Show Recent Decisions
+
+- **intent:** show decisions, recent decisions, what decisions were made, decision log
+- **summary:** Display recent entries from .squad/decisions.md
+- **action:** coordinator
+- **command:** Direct Mode — read decisions.md, answer
+- **args:** (none)
+- **confirm:** false
+
+### Archive Old Decisions
+
+- **intent:** archive decisions, clean up decisions, move old decisions, compact decisions
+- **summary:** Move old decisions from decisions.md to decisions-archive.md
+- **action:** coordinator
+- **command:** Move entries older than threshold from .squad/decisions.md → .squad/decisions-archive.md
+- **args:**
+  - `olderThan`: Archive decisions older than how many days? | default: 30
+- **confirm:** true
+
+### Summarize Agent History
+
+- **intent:** summarize history, what did agent do, agent history, compress history
+- **summary:** Spawn an agent to summarize and compress a team member's history file
+- **action:** coordinator
+- **command:** Spawn agent with history.md summarization task
+- **args:**
+  - `member`: Which team member's history to summarize?
+- **confirm:** false
diff --git a/packages/squad-cli/templates/spawn-reference.md b/packages/squad-cli/templates/spawn-reference.md
index ef8ae8dac..591989228 100644
--- a/packages/squad-cli/templates/spawn-reference.md
+++ b/packages/squad-cli/templates/spawn-reference.md
@@ -115,6 +115,8 @@ prompt: |
   skip post-work entirely -- Scribe handles it independently.
   1. APPEND learnings with `squad_state_append` to `agents/{name}/history.md`.
      Include architecture decisions, patterns, user preferences, and key file paths.
+     Use `<literal CURRENT_DATETIME value from your prompt>` as the entry timestamp.
+     Substitute the actual CURRENT_DATETIME value; do not write placeholder text.
   2. If you made a team-relevant decision, call `squad_decide`. If that tool is
      unavailable, use `squad_state_write` to `decisions/inbox/{name}-{brief-slug}.md`.
   3. If state tools are unavailable, skip post-work state persistence and report the
diff --git a/packages/squad-cli/templates/squad.agent.md.template b/packages/squad-cli/templates/squad.agent.md.template
index 379416c11..aeade9aaf 100644
--- a/packages/squad-cli/templates/squad.agent.md.template
+++ b/packages/squad-cli/templates/squad.agent.md.template
@@ -11,6 +11,7 @@ You are **Squad (Coordinator)** — the orchestrator for this project's AI team.
 
 - **Name:** Squad (Coordinator)
 - **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
+- **Greeting tip:** On the line after the version stamp, include: `💡 Say "squad commands" to see what I can do.` — this helps new users discover the command catalog without cluttering the version line.
 - **Role:** Agent orchestration, handoff enforcement, reviewer gating
 - **Inputs:** User request, repository state, `.squad/decisions.md`
 - **Outputs owned:** Final assembled artifacts, orchestration log (via Scribe)
@@ -294,6 +295,7 @@ The routing table determines **WHO** handles work. After routing, use Response M
 | PRD intake ("here's the PRD", "read the PRD at X", pastes spec) | Follow PRD Mode (see that section) |
 | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Ralph commands ("Ralph, go", "keep working", "Ralph, status", "Ralph, idle") | Follow Ralph — Work Monitor (see that section) |
+| "squad commands", "what can squad do", "show me squad options", "slash commands", "what commands are available" | Read `.copilot/skills/squad-commands/SKILL.md`, present categorized menu (see squad-commands skill) |
 | "upgrade squad", "update squad", "what's new in squad", "install the update" | Run upgrade flow per `.squad/templates/session-init-reference.md` |
 | Rai commands ("Rai, review this", "RAI check", "content safety review") | Follow Rai — RAI Reviewer (see that section) |
 | General work request | Check routing.md, spawn best match + any anticipatory agents |
diff --git a/packages/squad-sdk/src/config/init.ts b/packages/squad-sdk/src/config/init.ts
index 5ed08006e..3038834fc 100644
--- a/packages/squad-sdk/src/config/init.ts
+++ b/packages/squad-sdk/src/config/init.ts
@@ -37,6 +37,7 @@ const MANIFEST_SKILL_NAMES = [
   'reviewer-protocol',
   'test-discipline',
   'agent-collaboration',
+  'squad-commands',
   'squad-version-check',
 ] as const;
 
diff --git a/packages/squad-sdk/templates/scribe-charter.md b/packages/squad-sdk/templates/scribe-charter.md
index efa55bd67..da6ddfe6a 100644
--- a/packages/squad-sdk/templates/scribe-charter.md
+++ b/packages/squad-sdk/templates/scribe-charter.md
@@ -59,10 +59,10 @@ After every substantial work session:
    📌 Team update (<CURRENT_DATETIME value>): {summary} — decided by {Name}
    ```
 
-5. **Verify persistence through the runtime backend:**
+5. **Commit and verify persistence through the runtime backend:**
    - Run `squad_state_health` when available.
    - Re-read `decisions.md`, `log/{timestamp}-{topic}.md`, and any updated histories with `squad_state_read`.
-   - Never commit, amend, reset, checkout, push notes, or switch branches to persist mutable squad state.
+   - Never amend, reset, checkout, push notes, or switch branches to persist mutable squad state. When state tools are unavailable and you have directly modified static files (charters, team.md, skills), commit those changes with `git commit`.
 
 6. **Commit handling:** Never commit mutable squad state. If non-state repo files changed, report them for coordinator handling.
 
diff --git a/packages/squad-sdk/templates/session-init-reference.md b/packages/squad-sdk/templates/session-init-reference.md
new file mode 100644
index 000000000..a30532563
--- /dev/null
+++ b/packages/squad-sdk/templates/session-init-reference.md
@@ -0,0 +1,199 @@
+# Session Init Reference
+
+Procedures the coordinator runs at session start, in order. Each step is
+self-contained, fails silent, and degrades to "show normal greeting."
+
+---
+
+## Step 1: Update Check
+
+Check whether a newer Squad version exists for the user's channel. Append to
+the greeting if a newer version is found. Never block the session; every
+failure path ends at "show normal greeting."
+
+### 1.1 Kill Switch
+
+If the environment variable `SQUAD_NO_UPDATE_CHECK` is set to `1`, **skip
+Step 1 entirely** and show the normal greeting. This is the same kill switch
+as the upstream CLI banner — one opt-out disables both.
+
+### 1.2 Channel Detection
+
+Read the stamped version from the `<!-- version: X -->` HTML comment at the
+top of `squad.agent.md` (or from the `- **Version:** X` identity line as
+fallback). Classify the channel:
+
+| Stamped version contains | Channel   |
+|--------------------------|-----------|
+| `-insider`               | `insider` |
+| `-preview`               | `preview` |
+| (neither)                | `latest`  |
+
+Store the stamped version as `currentVersion` and the detected channel.
+
+### 1.3 Hybrid Cache Strategy
+
+The strategy differs by channel to avoid redundant network calls for the
+common (`latest`) case.
+
+#### For `latest` channel — read upstream OS-specific cache
+
+The upstream Squad CLI (`self-update.ts`) already fetches the latest version
+on startup and writes it to an OS-specific path with a 24h TTL. Read that
+cache instead of making a new npm call.
+
+**One-liner to read the upstream cache:**
+```
+node -e "const p=require('path'),o=require('os');const b=process.env.APPDATA||(process.platform==='darwin'?p.join(o.homedir(),'Library','Application Support'):p.join(o.homedir(),'.config'));const f=p.join(b,'squad-cli','update-check.json');try{const d=JSON.parse(require('fs').readFileSync(f,'utf8'));const age=Date.now()-d.checkedAt;if(age<86400000)console.log(JSON.stringify(d));else console.log('STALE')}catch{console.log('MISS')}"
+```
+
+Output semantics:
+- Valid JSON `{"latestVersion":"X.Y.Z","checkedAt":N}` → cache hit; use `latestVersion`
+- `STALE` → cache expired (older than 24h); treat as no data
+- `MISS` → cache missing or corrupt; treat as no data
+
+On `STALE` or `MISS`, show the normal greeting (no notice). Do **not** make an
+independent npm call for `latest`-channel users — the upstream CLI will refresh
+the cache on its next run.
+
+**OS-specific cache path for reference:**
+- Windows: `%APPDATA%\squad-cli\update-check.json`
+- Linux: `~/.config/squad-cli/update-check.json`
+- macOS: `~/Library/Application Support/squad-cli/update-check.json`
+
+#### For `insider` / `preview` channels — own probe with repo-local cache
+
+The upstream cache only stores the `latest` dist-tag and is not useful for
+pre-release channels. Use a separate probe.
+
+**Step A — Check repo-local cache:**
+
+Read `.squad/.cache/version-check.json`. If the file exists, is not older than
+24h, and `currentVersion` matches `stamped version`, use `channelVersion` from
+it. Skip the npm probe.
+
+**Repo-local cache schema:**
+```json
+{
+  "checkedAt": "2026-05-26T14:13:28.492Z",
+  "currentVersion": "0.9.6-insider.2",
+  "channel": "insider",
+  "channelVersion": "0.9.7-insider.1"
+}
+```
+
+**Step B — npm probe (on cache miss / stale / version mismatch):**
+
+```
+npm view @bradygaster/squad-cli dist-tags --json
+```
+
+- Timeout: **5 seconds.** If the command does not respond within 5 seconds,
+  abandon and show normal greeting.
+- On success: extract `dist-tags[channel]` (e.g., `dist-tags["insider"]`).
+  Write `.squad/.cache/version-check.json` with the schema above.
+  Create `.squad/.cache/` if it does not exist.
+- On any error (network failure, registry unreachable, parse error): show
+  normal greeting.
+
+### 1.4 Comparison
+
+Compare `currentVersion` against the resolved `latestVersionForChannel` using
+semver ordering (pre-release suffixes sort lower than their release counterpart,
+e.g., `0.9.5-insider.1 < 0.9.5`).
+
+- `latestVersionForChannel > currentVersion` → update available
+- Equal or older → no notice
+
+### 1.5 Greeting Append
+
+When an update is available, append to the normal greeting (on the same line,
+separated by ` · `):
+
+```
+ · 🆕 v{latestVersionForChannel} available — say "upgrade squad"
+```
+
+Example complete greeting line:
+```
+Squad v0.9.4-insider.1 · 🆕 v0.9.7-insider.1 available — say "upgrade squad"
+```
+
+Do not mention the update check, the cache, or the mechanism. Just the notice.
+
+### 1.6 Upgrade Flow
+
+**Trigger phrases** (case-insensitive, match anywhere in user message):
+- "upgrade squad"
+- "update squad"
+- "what's new" *(when a version notice has been shown in this session)*
+- "install the update"
+- "yes upgrade"
+
+**Flow:**
+
+1. **Confirm** — ask the user to confirm before running the upgrade:
+   > "I'll run `squad upgrade` now. This overwrites `squad.agent.md` and
+   > casting files but preserves `config.json`, `team.md`, `decisions.md`,
+   > and all agent history. Ready?"
+   Wait for affirmative response before proceeding.
+
+2. **Run upgrade:**
+   ```
+   squad upgrade
+   ```
+   Capture output. On failure (non-zero exit, error output), report the error
+   to the user and stop.
+
+3. **What's-new digest** — after successful upgrade, fetch and summarize
+   release notes:
+
+   ```
+   gh api repos/bradygaster/squad/releases --jq '[.[] | select(.tag_name | test("^v"))]'
+   ```
+
+   - Extract 3–6 bullet points from releases between `oldVersion` and
+     `newVersion`, inclusive.
+   - Priority: `feat` entries first, then `fix`, then `docs`.
+   - Format:
+     ```
+     📋 What's new in v{newVersion}:
+     • {feat summary 1}
+     • {feat summary 2}
+     • {fix summary}
+     ```
+   - **Fallback chain:**
+     - `gh` not authenticated → "See full release notes at:
+       https://github.com/bradygaster/squad/releases"
+     - No releases found → "No release notes found for this version range."
+     - Network failure → link to releases page
+
+4. **Restart prompt** — after showing the digest, prompt the user:
+   > "`squad.agent.md` has been updated. For the new coordinator instructions
+   > to take effect, please start a new session (close and re-open this chat).
+   > Your team state and decisions are unchanged."
+
+### 1.7 Failure Modes
+
+Every failure path ends at "show normal greeting." The update check never
+interrupts or delays the session.
+
+| Failure | Behavior |
+|---------|----------|
+| `node` not on PATH | `MISS` → normal greeting |
+| Upstream cache missing / corrupt | `MISS` → normal greeting |
+| Upstream cache stale (`latest` channel) | Normal greeting (no npm call) |
+| npm probe timeout (5s) | Normal greeting |
+| npm probe network error | Normal greeting |
+| npm probe parse error | Normal greeting |
+| `.squad/.cache/` write error | Normal greeting (skip cache write) |
+| `gh` not available / unauthenticated | Upgrade flow: link to releases page |
+| `squad upgrade` exits non-zero | Report error, stop flow |
+| Any unexpected exception | Log to `.squad/orchestration-log/`, normal greeting |
+
+---
+
+## (Future steps reserved)
+
+- Step 2: \<reserved\> — e.g., dependency drift check
+- Step 3: \<reserved\> — e.g., repo policy / state-backend audit
diff --git a/packages/squad-sdk/templates/spawn-reference.md b/packages/squad-sdk/templates/spawn-reference.md
index ef8ae8dac..591989228 100644
--- a/packages/squad-sdk/templates/spawn-reference.md
+++ b/packages/squad-sdk/templates/spawn-reference.md
@@ -115,6 +115,8 @@ prompt: |
   skip post-work entirely -- Scribe handles it independently.
   1. APPEND learnings with `squad_state_append` to `agents/{name}/history.md`.
      Include architecture decisions, patterns, user preferences, and key file paths.
+     Use `<literal CURRENT_DATETIME value from your prompt>` as the entry timestamp.
+     Substitute the actual CURRENT_DATETIME value; do not write placeholder text.
   2. If you made a team-relevant decision, call `squad_decide`. If that tool is
      unavailable, use `squad_state_write` to `decisions/inbox/{name}-{brief-slug}.md`.
   3. If state tools are unavailable, skip post-work state persistence and report the
diff --git a/packages/squad-sdk/templates/squad.agent.md.template b/packages/squad-sdk/templates/squad.agent.md.template
index 379416c11..aeade9aaf 100644
--- a/packages/squad-sdk/templates/squad.agent.md.template
+++ b/packages/squad-sdk/templates/squad.agent.md.template
@@ -11,6 +11,7 @@ You are **Squad (Coordinator)** — the orchestrator for this project's AI team.
 
 - **Name:** Squad (Coordinator)
 - **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
+- **Greeting tip:** On the line after the version stamp, include: `💡 Say "squad commands" to see what I can do.` — this helps new users discover the command catalog without cluttering the version line.
 - **Role:** Agent orchestration, handoff enforcement, reviewer gating
 - **Inputs:** User request, repository state, `.squad/decisions.md`
 - **Outputs owned:** Final assembled artifacts, orchestration log (via Scribe)
@@ -294,6 +295,7 @@ The routing table determines **WHO** handles work. After routing, use Response M
 | PRD intake ("here's the PRD", "read the PRD at X", pastes spec) | Follow PRD Mode (see that section) |
 | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Ralph commands ("Ralph, go", "keep working", "Ralph, status", "Ralph, idle") | Follow Ralph — Work Monitor (see that section) |
+| "squad commands", "what can squad do", "show me squad options", "slash commands", "what commands are available" | Read `.copilot/skills/squad-commands/SKILL.md`, present categorized menu (see squad-commands skill) |
 | "upgrade squad", "update squad", "what's new in squad", "install the update" | Run upgrade flow per `.squad/templates/session-init-reference.md` |
 | Rai commands ("Rai, review this", "RAI check", "content safety review") | Follow Rai — RAI Reviewer (see that section) |
 | General work request | Check routing.md, spawn best match + any anticipatory agents |
diff --git a/templates/scribe-charter.md b/templates/scribe-charter.md
index efa55bd67..da6ddfe6a 100644
--- a/templates/scribe-charter.md
+++ b/templates/scribe-charter.md
@@ -59,10 +59,10 @@ After every substantial work session:
    📌 Team update (<CURRENT_DATETIME value>): {summary} — decided by {Name}
    ```
 
-5. **Verify persistence through the runtime backend:**
+5. **Commit and verify persistence through the runtime backend:**
    - Run `squad_state_health` when available.
    - Re-read `decisions.md`, `log/{timestamp}-{topic}.md`, and any updated histories with `squad_state_read`.
-   - Never commit, amend, reset, checkout, push notes, or switch branches to persist mutable squad state.
+   - Never amend, reset, checkout, push notes, or switch branches to persist mutable squad state. When state tools are unavailable and you have directly modified static files (charters, team.md, skills), commit those changes with `git commit`.
 
 6. **Commit handling:** Never commit mutable squad state. If non-state repo files changed, report them for coordinator handling.
 
diff --git a/templates/session-init-reference.md b/templates/session-init-reference.md
new file mode 100644
index 000000000..a30532563
--- /dev/null
+++ b/templates/session-init-reference.md
@@ -0,0 +1,199 @@
+# Session Init Reference
+
+Procedures the coordinator runs at session start, in order. Each step is
+self-contained, fails silent, and degrades to "show normal greeting."
+
+---
+
+## Step 1: Update Check
+
+Check whether a newer Squad version exists for the user's channel. Append to
+the greeting if a newer version is found. Never block the session; every
+failure path ends at "show normal greeting."
+
+### 1.1 Kill Switch
+
+If the environment variable `SQUAD_NO_UPDATE_CHECK` is set to `1`, **skip
+Step 1 entirely** and show the normal greeting. This is the same kill switch
+as the upstream CLI banner — one opt-out disables both.
+
+### 1.2 Channel Detection
+
+Read the stamped version from the `<!-- version: X -->` HTML comment at the
+top of `squad.agent.md` (or from the `- **Version:** X` identity line as
+fallback). Classify the channel:
+
+| Stamped version contains | Channel   |
+|--------------------------|-----------|
+| `-insider`               | `insider` |
+| `-preview`               | `preview` |
+| (neither)                | `latest`  |
+
+Store the stamped version as `currentVersion` and the detected channel.
+
+### 1.3 Hybrid Cache Strategy
+
+The strategy differs by channel to avoid redundant network calls for the
+common (`latest`) case.
+
+#### For `latest` channel — read upstream OS-specific cache
+
+The upstream Squad CLI (`self-update.ts`) already fetches the latest version
+on startup and writes it to an OS-specific path with a 24h TTL. Read that
+cache instead of making a new npm call.
+
+**One-liner to read the upstream cache:**
+```
+node -e "const p=require('path'),o=require('os');const b=process.env.APPDATA||(process.platform==='darwin'?p.join(o.homedir(),'Library','Application Support'):p.join(o.homedir(),'.config'));const f=p.join(b,'squad-cli','update-check.json');try{const d=JSON.parse(require('fs').readFileSync(f,'utf8'));const age=Date.now()-d.checkedAt;if(age<86400000)console.log(JSON.stringify(d));else console.log('STALE')}catch{console.log('MISS')}"
+```
+
+Output semantics:
+- Valid JSON `{"latestVersion":"X.Y.Z","checkedAt":N}` → cache hit; use `latestVersion`
+- `STALE` → cache expired (older than 24h); treat as no data
+- `MISS` → cache missing or corrupt; treat as no data
+
+On `STALE` or `MISS`, show the normal greeting (no notice). Do **not** make an
+independent npm call for `latest`-channel users — the upstream CLI will refresh
+the cache on its next run.
+
+**OS-specific cache path for reference:**
+- Windows: `%APPDATA%\squad-cli\update-check.json`
+- Linux: `~/.config/squad-cli/update-check.json`
+- macOS: `~/Library/Application Support/squad-cli/update-check.json`
+
+#### For `insider` / `preview` channels — own probe with repo-local cache
+
+The upstream cache only stores the `latest` dist-tag and is not useful for
+pre-release channels. Use a separate probe.
+
+**Step A — Check repo-local cache:**
+
+Read `.squad/.cache/version-check.json`. If the file exists, is not older than
+24h, and `currentVersion` matches `stamped version`, use `channelVersion` from
+it. Skip the npm probe.
+
+**Repo-local cache schema:**
+```json
+{
+  "checkedAt": "2026-05-26T14:13:28.492Z",
+  "currentVersion": "0.9.6-insider.2",
+  "channel": "insider",
+  "channelVersion": "0.9.7-insider.1"
+}
+```
+
+**Step B — npm probe (on cache miss / stale / version mismatch):**
+
+```
+npm view @bradygaster/squad-cli dist-tags --json
+```
+
+- Timeout: **5 seconds.** If the command does not respond within 5 seconds,
+  abandon and show normal greeting.
+- On success: extract `dist-tags[channel]` (e.g., `dist-tags["insider"]`).
+  Write `.squad/.cache/version-check.json` with the schema above.
+  Create `.squad/.cache/` if it does not exist.
+- On any error (network failure, registry unreachable, parse error): show
+  normal greeting.
+
+### 1.4 Comparison
+
+Compare `currentVersion` against the resolved `latestVersionForChannel` using
+semver ordering (pre-release suffixes sort lower than their release counterpart,
+e.g., `0.9.5-insider.1 < 0.9.5`).
+
+- `latestVersionForChannel > currentVersion` → update available
+- Equal or older → no notice
+
+### 1.5 Greeting Append
+
+When an update is available, append to the normal greeting (on the same line,
+separated by ` · `):
+
+```
+ · 🆕 v{latestVersionForChannel} available — say "upgrade squad"
+```
+
+Example complete greeting line:
+```
+Squad v0.9.4-insider.1 · 🆕 v0.9.7-insider.1 available — say "upgrade squad"
+```
+
+Do not mention the update check, the cache, or the mechanism. Just the notice.
+
+### 1.6 Upgrade Flow
+
+**Trigger phrases** (case-insensitive, match anywhere in user message):
+- "upgrade squad"
+- "update squad"
+- "what's new" *(when a version notice has been shown in this session)*
+- "install the update"
+- "yes upgrade"
+
+**Flow:**
+
+1. **Confirm** — ask the user to confirm before running the upgrade:
+   > "I'll run `squad upgrade` now. This overwrites `squad.agent.md` and
+   > casting files but preserves `config.json`, `team.md`, `decisions.md`,
+   > and all agent history. Ready?"
+   Wait for affirmative response before proceeding.
+
+2. **Run upgrade:**
+   ```
+   squad upgrade
+   ```
+   Capture output. On failure (non-zero exit, error output), report the error
+   to the user and stop.
+
+3. **What's-new digest** — after successful upgrade, fetch and summarize
+   release notes:
+
+   ```
+   gh api repos/bradygaster/squad/releases --jq '[.[] | select(.tag_name | test("^v"))]'
+   ```
+
+   - Extract 3–6 bullet points from releases between `oldVersion` and
+     `newVersion`, inclusive.
+   - Priority: `feat` entries first, then `fix`, then `docs`.
+   - Format:
+     ```
+     📋 What's new in v{newVersion}:
+     • {feat summary 1}
+     • {feat summary 2}
+     • {fix summary}
+     ```
+   - **Fallback chain:**
+     - `gh` not authenticated → "See full release notes at:
+       https://github.com/bradygaster/squad/releases"
+     - No releases found → "No release notes found for this version range."
+     - Network failure → link to releases page
+
+4. **Restart prompt** — after showing the digest, prompt the user:
+   > "`squad.agent.md` has been updated. For the new coordinator instructions
+   > to take effect, please start a new session (close and re-open this chat).
+   > Your team state and decisions are unchanged."
+
+### 1.7 Failure Modes
+
+Every failure path ends at "show normal greeting." The update check never
+interrupts or delays the session.
+
+| Failure | Behavior |
+|---------|----------|
+| `node` not on PATH | `MISS` → normal greeting |
+| Upstream cache missing / corrupt | `MISS` → normal greeting |
+| Upstream cache stale (`latest` channel) | Normal greeting (no npm call) |
+| npm probe timeout (5s) | Normal greeting |
+| npm probe network error | Normal greeting |
+| npm probe parse error | Normal greeting |
+| `.squad/.cache/` write error | Normal greeting (skip cache write) |
+| `gh` not available / unauthenticated | Upgrade flow: link to releases page |
+| `squad upgrade` exits non-zero | Report error, stop flow |
+| Any unexpected exception | Log to `.squad/orchestration-log/`, normal greeting |
+
+---
+
+## (Future steps reserved)
+
+- Step 2: \<reserved\> — e.g., dependency drift check
+- Step 3: \<reserved\> — e.g., repo policy / state-backend audit
diff --git a/templates/spawn-reference.md b/templates/spawn-reference.md
index ef8ae8dac..591989228 100644
--- a/templates/spawn-reference.md
+++ b/templates/spawn-reference.md
@@ -115,6 +115,8 @@ prompt: |
   skip post-work entirely -- Scribe handles it independently.
   1. APPEND learnings with `squad_state_append` to `agents/{name}/history.md`.
      Include architecture decisions, patterns, user preferences, and key file paths.
+     Use `<literal CURRENT_DATETIME value from your prompt>` as the entry timestamp.
+     Substitute the actual CURRENT_DATETIME value; do not write placeholder text.
   2. If you made a team-relevant decision, call `squad_decide`. If that tool is
      unavailable, use `squad_state_write` to `decisions/inbox/{name}-{brief-slug}.md`.
   3. If state tools are unavailable, skip post-work state persistence and report the
diff --git a/templates/squad.agent.md.template b/templates/squad.agent.md.template
index 379416c11..aeade9aaf 100644
--- a/templates/squad.agent.md.template
+++ b/templates/squad.agent.md.template
@@ -11,6 +11,7 @@ You are **Squad (Coordinator)** — the orchestrator for this project's AI team.
 
 - **Name:** Squad (Coordinator)
 - **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
+- **Greeting tip:** On the line after the version stamp, include: `💡 Say "squad commands" to see what I can do.` — this helps new users discover the command catalog without cluttering the version line.
 - **Role:** Agent orchestration, handoff enforcement, reviewer gating
 - **Inputs:** User request, repository state, `.squad/decisions.md`
 - **Outputs owned:** Final assembled artifacts, orchestration log (via Scribe)
@@ -294,6 +295,7 @@ The routing table determines **WHO** handles work. After routing, use Response M
 | PRD intake ("here's the PRD", "read the PRD at X", pastes spec) | Follow PRD Mode (see that section) |
 | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Ralph commands ("Ralph, go", "keep working", "Ralph, status", "Ralph, idle") | Follow Ralph — Work Monitor (see that section) |
+| "squad commands", "what can squad do", "show me squad options", "slash commands", "what commands are available" | Read `.copilot/skills/squad-commands/SKILL.md`, present categorized menu (see squad-commands skill) |
 | "upgrade squad", "update squad", "what's new in squad", "install the update" | Run upgrade flow per `.squad/templates/session-init-reference.md` |
 | Rai commands ("Rai, review this", "RAI check", "content safety review") | Follow Rai — RAI Reviewer (see that section) |
 | General work request | Check routing.md, spawn best match + any anticipatory agents |