---
type: user-guide
title: [Human-readable title]
summary: [1-2 sentences answering "what mental model + gotchas does using [tool] well require?" — NOT what the tool does or a feature list]
tags:
  - type/user-guide
  - tool/[tool]
  - domain/[field]     # if applicable
  - client/[client]    # if client-specific
  - project/[project]  # if project-specific
scope: [global|project|client]
last_updated: YYYY-MM-DD
date: YYYY-MM-DD          # creation date — set once, never updated
update_note: experience-driven  # keep — user guides update when a session finds a new gotcha or a discrepancy
related:
  - [note-slug]  # cross-links to companion notes; omit if none
source: [project name]  # project that spawned the note
---

# [Tool Name] — User Guide

<!-- REMINDER before you fill this: this is NOT a how-to. No numbered steps. Command
     syntax gets the compact table in "Command Reference" at most — everything else
     is nuance: semantics, distinctions, gotchas, judgment calls a competent user has
     internalized. If a section would just restate --help output, cut it. -->

## What it is
<!-- One paragraph. What the tool does and the one-sentence mental model of its purpose —
     enough for the reader to recognize "this is/isn't the tool for my situation." Do NOT
     restate the summary; do NOT give a feature list. -->

## Mental model
<!-- The key concepts and distinctions the reader must hold to reason about the tool
     correctly — the vocabulary and the boundaries between modes/concepts that command
     syntax alone does not convey (e.g. "X vs Y look similar but differ in Z"). This is
     what makes the rest of the guide (and the tool's own docs) parseable. -->

## Nuances & gotchas
<!-- The meat of the guide — the heaviest section. Each item: the surprising behavior,
     why it exists (if known), and how to recognize/avoid/recover from it. Prioritize
     things that look safe but aren't, defaults that surprise, or state that silently
     changes behavior. One sub-heading or bullet per nuance; don't pad with obvious facts. -->

## When NOT to use it / limits
<!-- The boundary: situations where this tool is the wrong choice, or where it stops
     working as expected. Prevents the reader from forcing a bad fit. Omit only if the
     tool genuinely has no such boundary (rare — justify the omission to yourself first). -->

## Command reference
<!-- Compact table ONLY — command/flag → one-line effect. No walkthroughs, no examples
     of full sessions. If there's nothing beyond what --help already says clearly, cut
     this section entirely rather than restate --help. -->

| Command | Effect |
|---|---|
| `[command]` | [one-line effect] |

## Pointers
<!-- Where to go deeper: repo paths, ADRs, specs, upstream docs. One line each — what
     the reader finds there, not a restatement of its content. -->

- [path/to/repo] — [what's there]

## Related
<!-- Wikilinks to companion notes, one line each on why it is relevant. -->

- [[note-slug]] — why it is relevant