One-command GIF + exhaustive consistency pass

bogdanmatasaru · claude · bogdanmatasaru · commit ab09b738b8fc · 2026-06-04T15:50:48.000+03:00
- Regenerate demo.gif to show the single `curl | bash` install (was the old
  clone + ./setup.sh flow)
- Add the one-command install to the Quickstart intro
- Clean up link text: human-readable labels instead of raw ./paths.md
- Consistency fixes from a full doc review:
  - reframe "command" as a manual-only skill (was contradicting the reference)
  - bridge "three modes" (tutorials) to "six modes" (reference)
  - add a Related nav footer to every guide (were dead-ends)
  - uniform "Source:" link format; /resume, /usage(5h), Opus-4.6 wording,
    de-duplicate Ctrl+R, move /memory out of the prefixes table
  - allowed-tools comma-separated in command assets (copy-paste correctness)
  - align setup.sh allowlist with the asset; test suite "(32 checks)" wording

Build/lint/shellcheck/tests all green; 0 render anomalies across all pages.

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/assets/commands/commit.md b/assets/commands/commit.md
@@ -1,7 +1,7 @@
 ---
 name: commit
 description: Stage changes and create a Conventional Commit from the diff. Use when the user wants to commit the current work. Does not push.
-allowed-tools: Bash(git add:*) Bash(git status:*) Bash(git diff:*) Bash(git commit:*) Bash(git log:*)
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git diff:*), Bash(git commit:*), Bash(git log:*)
 ---
 
 # Commit
diff --git a/assets/commands/review-pr.md b/assets/commands/review-pr.md
@@ -1,7 +1,7 @@
 ---
 name: review-pr
 description: Review the current diff for bugs, edge cases, and risks, then suggest concrete fixes. Use before opening or merging a PR. Read-only — makes no changes.
-allowed-tools: Bash(git diff:*) Bash(git status:*) Bash(git log:*) Bash(gh pr view:*) Bash(gh pr diff:*)
+allowed-tools: Bash(git diff:*), Bash(git status:*), Bash(git log:*), Bash(gh pr view:*), Bash(gh pr diff:*)
 ---
 
 # Review PR
diff --git a/assets/commands/write-tests.md b/assets/commands/write-tests.md
@@ -1,7 +1,7 @@
 ---
 name: write-tests
 description: Write focused tests for a given file or function and run them until they pass. Use when asked to add or improve test coverage. Pass the target as an argument, e.g. /write-tests src/auth.ts.
-allowed-tools: Bash(npm test:*) Bash(npx vitest:*) Bash(npx jest:*) Bash(pytest:*) Bash(uv run pytest:*) Bash(go test:*)
+allowed-tools: Bash(npm test:*), Bash(npx vitest:*), Bash(npx jest:*), Bash(pytest:*), Bash(uv run pytest:*), Bash(go test:*)
 ---
 
 # Write Tests
diff --git a/docs/cheatsheet.md b/docs/cheatsheet.md
@@ -15,7 +15,6 @@ the full reference.
 | `/` | Run a slash command or skill (type `/` to list) |
 | `@` | Mention a file/folder or MCP resource (`@src/auth.ts`) |
 | `!` | Run a shell command; output goes into context |
-| `/memory` | Edit persistent memory (project/user [CLAUDE.md](./reference/claude-md.md)) |
 
 ## Essential keys
 
@@ -54,6 +53,7 @@ Fine-grained: `/permissions` → allow/deny patterns like `Bash(npm run test:*)`
 | `/help` | List everything |
 | `/init` | Generate a `CLAUDE.md` from the codebase |
 | `/clear` | New conversation, keep project memory (use between tasks) |
+| `/memory` | Edit persistent memory ([CLAUDE.md](./reference/claude-md.md)) |
 | `/compact [focus]` | Compress the conversation, keep the essentials |
 | `/context` | Show context-window usage |
 | `/model` · `/effort` | Switch model · set reasoning effort |
diff --git a/docs/environment/bootstrap-setup.md b/docs/environment/bootstrap-setup.md
@@ -102,7 +102,7 @@ claude doctor         # check the Claude Code install itself
 
 ## The test suite
 
-The script ships with a **32-assertion** test suite that runs `setup.sh` in a temporary `HOME` with mocked commands — no changes to your real system:
+The script ships with a **test suite (32 checks)** that runs `setup.sh` in a temporary `HOME` with mocked commands — no changes to your real system:
 
 ```bash
 ./test/run-tests.sh
diff --git a/docs/environment/monitoring-cost-ratelimits.md b/docs/environment/monitoring-cost-ratelimits.md
@@ -13,7 +13,7 @@ Run `/usage` to see your session token use plus **plan usage bars**:
 - A **5-hour window** (the rolling session limit).
 - A **weekly window**.
 
-`/usage` also **attributes** usage to what's consuming it — skills, subagents, and MCP servers — so you can see what's expensive. Press **`d`** and **`w`** to switch between the daily and weekly views.
+`/usage` also **attributes** usage to what's consuming it — skills, subagents, and MCP servers — so you can see what's expensive. Press **`d`** and **`w`** to switch between the 5-hour and weekly views.
 
 When you're near a limit, `/usage` shows the **time until your window resets**, which is the number you actually plan around.
 
diff --git a/docs/explanation/context-window.md b/docs/explanation/context-window.md
@@ -57,6 +57,6 @@ Your main context stays clean; you get the answer without the clutter. This is o
 - `/context` to check before things feel slow.
 - **Subagents** for anything that reads a lot of files.
 
-For the full picture on keeping sessions efficient, see [../guides/cost-optimization.md](../guides/cost-optimization.md).
+For the full picture on keeping sessions efficient, see [Optimize cost & context](../guides/cost-optimization.md).
 
-**Source:** https://code.claude.com/docs/en/costs
+**Source:** [Manage cost & context](https://code.claude.com/docs/en/costs)
diff --git a/docs/explanation/how-claude-works.md b/docs/explanation/how-claude-works.md
@@ -33,7 +33,7 @@ With a verifiable target, each loop iteration moves closer to correct. Without o
 
 ## The context window
 
-Everything Claude knows in a session lives in its **context window** — its working memory. It's finite, and performance degrades as it fills. Keeping context lean (clearing between tasks, compacting mid-task) is central to good results. See [./context-window.md](./context-window.md) for the details.
+Everything Claude knows in a session lives in its **context window** — its working memory. It's finite, and performance degrades as it fills. Keeping context lean (clearing between tasks, compacting mid-task) is central to good results. See [the context window](./context-window.md) for the details.
 
 ## The customization layers
 
@@ -50,4 +50,4 @@ A simple way to remember the difference: CLAUDE.md is *always* loaded, a skill i
 
 The loop does the work; the layers shape it. Give Claude a clear goal, a lean context, and a way to verify itself, and it behaves like a capable colleague rather than a fancy autocomplete.
 
-**Source:** https://code.claude.com/docs/en/how-claude-code-works
+**Source:** [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works)
diff --git a/docs/explanation/when-to-use-what.md b/docs/explanation/when-to-use-what.md
@@ -25,12 +25,12 @@ These look similar but solve different problems:
 | Mechanism | Use when… | Trigger |
 | --- | --- | --- |
 | **Skill** | a capability is **sometimes relevant** and reusable | loads when the task matches |
-| **Command** | you want a **named shortcut** you invoke on demand | you type `/name` |
+| **Command** | you want a **named shortcut** you invoke yourself (a skill with `disable-model-invocation`) | you type `/name` |
 | **Hook** | something must happen **every time**, deterministically | fires automatically on an event |
 | **MCP** | you need to **connect an external tool** (database, API, service) | available once configured |
 
 - **Use a skill when** you have know-how that applies now and then — a testing convention, a deploy procedure — and you want Claude to pull it in automatically.
-- **Use a command when** you want to trigger something yourself by name.
+- **Use a command when** you want a skill that runs *only* when you invoke it by name — set `disable-model-invocation: true`. Commands and skills are one mechanism; a command is just a manually-triggered skill.
 - **Use a hook when** the action is non-negotiable: format on every edit, block commits to `main`, log every tool call.
 - **Use MCP when** Claude needs to reach a system it can't touch with files and shell — but keep your MCP set **lean**, since each server adds context and surface area.
 
@@ -49,7 +49,7 @@ Start on Sonnet. Step up to Opus when a task is genuinely hard; drop to Haiku wh
 - **`/clear`** between **unrelated** tasks — start each task with clean working memory.
 - **`/compact`** mid-task when context grows heavy but you still need continuity.
 
-And one more reset worth memorizing: if you've **corrected Claude two or more times** on the same point, stop fighting the thread. Run `/clear` and **rewrite the prompt** from scratch — a clean start beats a confused one. (Why context hygiene matters: [./context-window.md](./context-window.md).)
+And one more reset worth memorizing: if you've **corrected Claude two or more times** on the same point, stop fighting the thread. Run `/clear` and **rewrite the prompt** from scratch — a clean start beats a confused one. (Why context hygiene matters: [the context window](./context-window.md).)
 
 ## At a glance
 
@@ -59,4 +59,4 @@ And one more reset worth memorizing: if you've **corrected Claude two or more ti
 - Default to **Sonnet**; **Opus** for hard, **Haiku** for trivial.
 - New task → **/clear**. Long task filling up → **/compact**.
 
-**Source:** https://code.claude.com/docs/en/overview
+**Source:** [Claude Code overview](https://code.claude.com/docs/en/overview)
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -20,7 +20,7 @@ The native installer is recommended because it auto-updates in the background. P
 The native install drops a binary at `~/.local/bin/claude`. Make sure that directory is on your `PATH` if the `claude` command isn't found after installing.
 
 > [!TIP]
-> On a fresh Mac, you can skip the manual steps entirely. See [../environment/bootstrap-setup.md](../environment/bootstrap-setup.md) for a one-command setup that installs everything at once.
+> On a fresh Mac, you can skip the manual steps entirely. See [the one-command setup](../environment/bootstrap-setup.md) for a one-command setup that installs everything at once.
 
 ## Platform notes
 
@@ -57,6 +57,6 @@ claude doctor
 > [!NOTE]
 > If `claude` isn't recognized, open a new terminal so your shell picks up the updated `PATH`, then try `claude doctor` again.
 
-Next: [./quickstart.md](./quickstart.md)
+Next: [Quickstart](./quickstart.md)
 
-**Source:** https://code.claude.com/docs/en/setup
+**Source:** [Set up Claude Code](https://code.claude.com/docs/en/setup)
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
@@ -6,8 +6,14 @@ description: The fastest path to a first win with Claude Code — explore a real
 
 The goal here is a quick win: in five minutes you'll have Claude explain a real codebase and propose a change you can review before anything touches disk.
 
-> [!NOTE]
-> This assumes Claude Code is installed and you're signed in. If not, do [./installation.md](./installation.md) first (about two minutes).
+> [!TIP]
+> **Not installed yet?** Get the whole stack — Claude Code, Ghostty, and configs — in one command:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/bogdanmatasaru/claude-code-guide/main/install.sh | bash
+```
+
+Sign in when prompted, then come back here. Prefer npm or Homebrew? See the [installation guide](./installation.md).
 
 ## 1. Open a project
 
@@ -41,7 +47,7 @@ explain the folder structure
 Before asking for a change, press `Shift+Tab` until the footer shows **plan mode**. In plan mode Claude investigates and proposes an approach but makes **no edits** — perfect for your first change.
 
 > [!TIP]
-> `Shift+Tab` cycles through three modes: default → acceptEdits → plan. Stop on plan for now.
+> `Shift+Tab` cycles through three modes: default → acceptEdits → plan. Stop on plan for now. (There are [six modes](../reference/permission-modes.md) in all; these three are the everyday ones.)
 
 ## 4. Ask for a small change
 
@@ -73,6 +79,6 @@ That explore → plan → review loop scales from one-line docstrings to multi-f
 > [!IMPORTANT]
 > Run `/clear` before starting an unrelated task. It resets Claude's working memory so the next task starts clean.
 
-Next: [./your-first-session.md](./your-first-session.md)
+Next: [Your first session](./your-first-session.md)
 
-**Source:** https://code.claude.com/docs/en/quickstart
+**Source:** [Quickstart](https://code.claude.com/docs/en/quickstart)
diff --git a/docs/getting-started/your-first-session.md b/docs/getting-started/your-first-session.md
@@ -19,7 +19,7 @@ Most of the time you just type in plain English. Three prefixes give you shortcu
 
 ## Permission modes
 
-Press `Shift+Tab` to cycle through three modes. The footer shows the current one:
+Press `Shift+Tab` to cycle through the three everyday modes — there are [six in total](../reference/permission-modes.md). The footer shows the current one:
 
 - **default** — Claude asks before each edit or command. Safest; best while you're learning.
 - **acceptEdits** — auto-applies file edits and safe in-scope file commands (`mkdir`, `mv`, `cp`, `rm`); it still asks before other commands like installs or deploys. Good once you trust the task.
@@ -68,11 +68,11 @@ Each task should start with a clean slate:
 /clear
 ```
 
-Run it between unrelated tasks. A lean context keeps Claude sharp; a cluttered one makes it slower and less accurate. (More on why in [../explanation/context-window.md](../explanation/context-window.md).)
+Run it between unrelated tasks. A lean context keeps Claude sharp; a cluttered one makes it slower and less accurate. (More on why in [the context window](../explanation/context-window.md).)
 
 ## Where to go next
 
 - Task-focused walkthroughs: [Guides](../guides/onboard-a-codebase.md)
 - Commands, flags, and config: [Reference](../reference/cli.md)
 
-**Source:** https://code.claude.com/docs/en/quickstart
+**Source:** [Quickstart](https://code.claude.com/docs/en/quickstart)
diff --git a/docs/guides/cost-optimization.md b/docs/guides/cost-optimization.md
@@ -60,4 +60,6 @@ You can cap extended-thinking budget with the `MAX_THINKING_TOKENS` environment
 
 Cost in Claude Code tracks tokens, and tokens track model size and context length. Right-sizing the model and keeping the window tight attack both directly. Anthropic's guidance — be specific, keep `CLAUDE.md` lean, clear between tasks — is as much a cost strategy as a quality one.
 
+**Related:** [Cheatsheet](../cheatsheet.md) · [Best practices](../best-practices.md) · [Learning path](../learning-path.md)
+
 **Source:** [Claude Code best practices](https://code.claude.com/docs/en/best-practices); community-reported figures noted as such.
diff --git a/docs/guides/fix-a-bug.md b/docs/guides/fix-a-bug.md
@@ -68,4 +68,6 @@ Opus earns its cost on hard, cross-file bugs; Sonnet is fine for the common case
 
 Anthropic's best practices frame debugging as: reproduce, write a test that captures the failure, fix, verify. The failing test is the anchor — it forces Claude to demonstrate understanding before changing anything and gives you an objective pass/fail at the end.
 
+**Related:** [Cheatsheet](../cheatsheet.md) · [Best practices](../best-practices.md) · [Learning path](../learning-path.md)
+
 **Source:** [Claude Code best practices](https://code.claude.com/docs/en/best-practices); community practice.
diff --git a/docs/guides/headless-and-ci.md b/docs/guides/headless-and-ci.md
@@ -88,4 +88,6 @@ With this in place, mentioning `@claude` in a pull request or issue comment trig
 
 Headless mode is the same engine as interactive Claude with the human loop removed, so the same rules apply harder: tight scope, explicit verification, and minimal tool permissions. The fan-out loop scales a single good prompt across an entire codebase.
 
+**Related:** [Cheatsheet](../cheatsheet.md) · [Best practices](../best-practices.md) · [Learning path](../learning-path.md)
+
 **Source:** [Claude Code best practices](https://code.claude.com/docs/en/best-practices); community practice.
diff --git a/docs/guides/onboard-a-codebase.md b/docs/guides/onboard-a-codebase.md
@@ -66,4 +66,6 @@ Anthropic's best practices recommend exploring before acting and giving Claude r
 > [!NOTE]
 > Start a fresh session (`/clear`) before you begin actual feature work. Onboarding fills the context with exploratory detail you no longer need; the `CLAUDE.md` you generated carries the durable knowledge forward.
 
+**Related:** [Cheatsheet](../cheatsheet.md) · [Best practices](../best-practices.md) · [Learning path](../learning-path.md)
+
 **Source:** [Claude Code best practices](https://code.claude.com/docs/en/best-practices); community practice.
diff --git a/docs/guides/parallel-work-worktrees.md b/docs/guides/parallel-work-worktrees.md
@@ -59,4 +59,6 @@ You get a sandbox to think in. When you're done, delete the branch and your main
 
 The guarantee is mechanical: separate working directories mean separate files, so concurrent sessions cannot collide. That removes the main friction of running more than one Claude at once and makes it safe to let an investigative session roam without worrying about your real tree.
 
+**Related:** [Cheatsheet](../cheatsheet.md) · [Best practices](../best-practices.md) · [Learning path](../learning-path.md)
+
 **Source:** [Claude Code best practices](https://code.claude.com/docs/en/best-practices); community practice.
diff --git a/docs/guides/refactor-safely.md b/docs/guides/refactor-safely.md
@@ -75,4 +75,6 @@ Then run a structured review:
 
 Anthropic's best practices for refactoring: scope narrowly, lean on tests as the safety net, investigate before changing, and review the result. Plan mode enforces the read-before-write order; subagents keep investigation out of your main thread; the diff review is the final gate.
 
+**Related:** [Cheatsheet](../cheatsheet.md) · [Best practices](../best-practices.md) · [Learning path](../learning-path.md)
+
 **Source:** [Claude Code best practices](https://code.claude.com/docs/en/best-practices); community practice.
diff --git a/docs/guides/spec-a-feature.md b/docs/guides/spec-a-feature.md
@@ -54,4 +54,6 @@ steps, plus tests/build) so it can self-correct without you watching every edit.
 > [!NOTE]
 > Commit `SPEC.md` alongside the work. It documents *why* the feature looks the way it does — useful for review and for the next person.
 
+**Related:** [Cheatsheet](../cheatsheet.md) · [Best practices](../best-practices.md) · [Learning path](../learning-path.md)
+
 **Source:** [Claude Code best practices](https://code.claude.com/docs/en/best-practices).
diff --git a/docs/reference/claude-md.md b/docs/reference/claude-md.md
@@ -68,7 +68,7 @@ Target **under 200 lines** per file. CLAUDE.md loads in full every session and c
 - Long prose, changelogs, or generated content
 - Secrets or machine-specific paths (use `CLAUDE.local.md`)
 
-See [cost-optimization.md](../guides/cost-optimization.md) for why a lean memory file saves money. Starter templates live in [`assets/claude-md/`](https://github.com/bogdanmatasaru/claude-code-guide/tree/main/assets/claude-md).
+See [cost optimization](../guides/cost-optimization.md) for why a lean memory file saves money. Starter templates live in [`assets/claude-md/`](https://github.com/bogdanmatasaru/claude-code-guide/tree/main/assets/claude-md).
 
 ## A tiny example
 
diff --git a/docs/reference/keyboard-shortcuts.md b/docs/reference/keyboard-shortcuts.md
@@ -25,7 +25,6 @@ Claude Code's interactive REPL is driven by keyboard shortcuts. This page groups
 | Shortcut | Action |
 | --- | --- |
 | `Ctrl+G` | Edit the current prompt or plan in `$EDITOR` |
-| `Ctrl+R` | Reverse-search through history |
 
 Vim-style editing is available via `/config` → **Editor mode**.
 
diff --git a/docs/reference/permission-modes.md b/docs/reference/permission-modes.md
@@ -18,7 +18,7 @@ Permission modes control how much Claude Code can do without asking. You cycle b
 | `bypassPermissions` | Skips all permission checks entirely |
 
 > [!NOTE]
-> `auto` is a research preview (v2.1.83+) and requires Opus 4.6+ or Sonnet 4.6. State your provider when relying on model availability — Bedrock/Vertex may resolve to different versions.
+> `auto` is a research preview (v2.1.83+) and requires Opus 4.6 or newer (Opus 4.8 today) or Sonnet 4.6. State your provider when relying on model availability — Bedrock/Vertex may resolve to different versions.
 
 ## Cycling and setting the default
 
diff --git a/docs/reference/settings.md b/docs/reference/settings.md
@@ -45,12 +45,12 @@ Claude Code reads settings from five layers. Higher layers win on conflict. Perm
 | --- | --- |
 | `permissions` | `allow` / `deny` / `ask` rules, `defaultMode`, `additionalDirectories` |
 | `env` | Environment variables exported to every command and hook |
-| `hooks` | Lifecycle automation — see [hooks.md](./hooks.md) |
+| `hooks` | Lifecycle automation — see [Hooks](./hooks.md) |
 | `model` | Default model for the session |
 | `availableModels` | Models offered in the picker |
 | `effortLevel` | Reasoning effort level |
-| `outputStyle` | Active output style — see [output-styles.md](./output-styles.md) |
-| `autoMemoryEnabled` | Toggle auto memory — see [claude-md.md](./claude-md.md) |
+| `outputStyle` | Active output style — see [Output styles](./output-styles.md) |
+| `autoMemoryEnabled` | Toggle auto memory — see [CLAUDE.md & memory](./claude-md.md) |
 | `includeCoAuthoredBy` | Add the Claude co-author trailer to commits |
 | `autoUpdatesChannel` | Which release channel to auto-update from |
 
@@ -72,7 +72,7 @@ Edit(src/**)             # any file under src/
 - A bare tool name (e.g. `WebFetch`) applies to all uses of that tool.
 - `deny` always wins over `allow`; rules from all scopes are combined.
 
-For interactive permission flow control, see [permission-modes.md](./permission-modes.md).
+For interactive permission flow control, see [Permission modes](./permission-modes.md).
 
 ## `/config` and `/permissions`
 
diff --git a/docs/reference/skills.md b/docs/reference/skills.md
@@ -15,7 +15,7 @@ The directory name becomes the command name (`deploy/` → `/deploy`). Each file
 ```markdown
 ---
 description: Run our release checklist and tag a version. Use when cutting a release.
-allowed-tools: Bash(git tag *) Bash(git push *)
+allowed-tools: Bash(git tag *), Bash(git push *)
 ---
 
 # Release
@@ -80,6 +80,6 @@ Set `disable-model-invocation: true` for **manual-only** skills. Use it for side
 
 Claude Code ships several: `/code-review`, `/debug`, `/loop`, `/run`, `/verify`.
 
-See ready-to-copy examples under [`assets/skills/`](https://github.com/bogdanmatasaru/claude-code-guide/tree/main/assets/skills) and the workflow [guides](../guides/onboard-a-codebase.md).
+See ready-to-copy examples in [`assets/commands/`](https://github.com/bogdanmatasaru/claude-code-guide/tree/main/assets/commands) and [`assets/skills/`](https://github.com/bogdanmatasaru/claude-code-guide/tree/main/assets/skills), plus the workflow [guides](../guides/onboard-a-codebase.md).
 
 **Source:** [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills)
diff --git a/docs/reference/slash-commands.md b/docs/reference/slash-commands.md
diff --git a/media/demo.gif b/media/demo.gif
diff --git a/scripts/demo.tape b/scripts/demo.tape
diff --git a/setup.sh b/setup.sh
