diff --git a/.claude/commands/create-adr.md b/.claude/commands/create-adr.md
new file mode 100644
index 00000000..e4043a47
--- /dev/null
+++ b/.claude/commands/create-adr.md
@@ -0,0 +1,95 @@
+# Create Architecture Decision Record
+
+Use this command when you need to document an architectural decision made during a task.
+
+## When to use this
+
+Create an ADR when your work involves any of these:
+- Choosing a storage strategy (vault vs app settings vs database)
+- Adding or removing a major dependency
+- Supporting a new platform or target
+- Introducing or removing a core abstraction
+- Making a cross-cutting decision that affects how future code should be written
+
+Do NOT create ADRs for: bug fixes, UI styling, refactors that preserve behavior, or test additions.
+
+## Steps
+
+### 1. Find the next available ID
+
+```bash
+ls docs/adr/*.md | grep -oP '\d{4}' | sort | tail -1
+```
+
+Increment by 1. If no files exist, start at `0001`.
+
+### 2. Create the file
+
+Filename: `docs/adr/NNNN-short-kebab-title.md`
+
+Use this template exactly:
+
+```markdown
+---
+type: ADR
+id: "NNNN"
+title: "Short decision title"
+status: active
+date: YYYY-MM-DD
+---
+
+## Context
+What situation led to this decision? What forces and constraints are at play?
+
+## Decision
+**What was decided.** State it clearly in one or two sentences — bold so it stands out.
+
+## Options considered
+- **Option A** (chosen): brief description — pros / cons
+- **Option B**: brief description — pros / cons
+- **Option C**: brief description — pros / cons
+
+## Consequences
+What becomes easier or harder as a result?
+What are the positive and negative ramifications?
+What would trigger re-evaluation of this decision?
+
+## Advice
+*(optional)* Input received before making this decision.
+Omit this section if the decision was made without external input.
+```
+
+### 3. Update the index
+
+Add a row to the table in `docs/adr/README.md`:
+
+```markdown
+| [NNNN](NNNN-short-kebab-title.md) | Title | active |
+```
+
+### 4. Commit in the same commit as the feature
+
+Include the ADR in the same commit as the code it documents:
+
+```bash
+git add docs/adr/NNNN-short-kebab-title.md docs/adr/README.md
+# include in the feature commit, not a separate one
+```
+
+## Superseding an existing ADR
+
+If your decision replaces an existing one:
+
+1. Edit the existing ADR — add `superseded_by: "NNNN"` to frontmatter and change `status: superseded`
+2. Create the new ADR with the updated decision
+3. Update the README index (change old status to `superseded`, add new row)
+
+**Never edit the content of an active ADR** — only its status metadata.
+
+## Best practices
+
+- Write the **Decision** section first — if you can't state it in 1-2 sentences, the decision is too vague
+- Be honest about **Options considered** — document the alternatives you actually thought about, not hypothetical ones
+- **Consequences** should include both positive and negative — a one-sided ADR is a red flag
+- Date = today's date in `YYYY-MM-DD` format
+- If you're unsure whether something warrants an ADR, err on the side of creating one — it's cheaper to have an unnecessary ADR than to lose context
diff --git a/CLAUDE.md b/CLAUDE.md
index 833e00af..ff9bc75b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -86,15 +86,13 @@ After adding a Tauri command, new component/hook, data model change, or new inte
 
 ## Architecture Decision Records (ADRs)
 
-ADRs live in `docs/adr/`. Read `docs/adr/README.md` for the format.
+ADRs live in `docs/adr/`. Before making an architectural choice, check existing ADRs there first.
 
-**Before making any architectural choice** (storage strategy, new dependency, platform approach, data model change): check `docs/adr/` for an existing decision that covers it. If one exists and your work aligns with it — proceed. If your work **supersedes** an existing ADR, **do not modify the existing file** — instead:
-1. Update the existing ADR: set `status: superseded` and `superseded_by: "NNNN"`
-2. Create a new ADR with the updated decision
+**When to create one**: storage strategy, new dependency, platform support, core abstraction change, cross-cutting concern. Use `/create-adr` for the full template and instructions.
 
-**After completing a task**: if you made a significant architectural decision that isn't already documented in `docs/adr/`, create a new ADR in the same commit. A decision is "significant" if it affects: data storage, platform support, major dependencies, core abstractions, or cross-cutting concerns.
+**When your work supersedes an existing ADR**: do not edit the existing file — use `/create-adr` which covers the superseding flow.
 
-**Do not create ADRs for**: implementation details, UI styling choices, refactoring decisions, or anything that doesn't affect how future code should be written.
+**Do not create ADRs for**: bug fixes, UI styling, refactors, or test additions.
 
 ## Design File (UI tasks)