@b0tts/template-dev-installer 1.0.0

package/files/.agents/skills/docs-mcp/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: docs-mcp
+description: Search and index up-to-date library documentation via Docs MCP (self-hosted Context7 alternative). Use when user asks a library-specific question, needs API reference with exact signatures, wants version-pinned docs, or says "check the docs", "look up the API", "what's the latest on X", "how do I use Y". Prefer over web_search when the library is (or can be) indexed — this gives structured, version-aware results without ads or SEO spam. Also use when the model suspects its training data may be stale.
+---
+
+# Docs MCP — Versioned Documentation Search
+
+## Tool Inventory
+
+| Tool | Purpose | Destructive |
+|------|---------|-------------|
+| `mcp_docs_list_libraries` | See all indexed libraries + versions | No |
+| `mcp_docs_find_version` | Resolve best matching version | No |
+| `mcp_docs_search_docs` | Semantic search within indexed docs | No |
+| `mcp_docs_fetch_url` | Fetch single page as Markdown (no indexing) | No |
+| `mcp_docs_scrape_docs` | Index a new library/version from URL | Yes (writes) |
+| `mcp_docs_refresh_version` | Re-scrape, updating only changed pages | Yes |
+| `mcp_docs_remove_docs` | Delete a library/version from index | Yes |
+| `mcp_docs_list_jobs` | List scraping jobs (filter by status) | No |
+| `mcp_docs_get_job_info` | Get job progress/detail | No |
+| `mcp_docs_cancel_job` | Cancel a running/queued job | Yes |
+
+## Core Workflow
+
+### 1. Check what's indexed
+
+Always start with `mcp_docs_list_libraries`. Currently only `prettier` is indexed — most queries will require scraping first.
+
+### 2. Find the right version
+
+Use `mcp_docs_find_version` to discover available versions. Supports X-Range patterns:
+- `"18.x"` → highest 18.x.x
+- `"18.2.x"` → highest 18.2.x
+- `"18.2.0"` → exact match
+- omit → latest available
+
+### 3. Search or scrape
+
+**If the library IS indexed**: use `mcp_docs_search_docs` with a specific query. Good queries name concrete APIs or concepts: `"hooks lifecycle"`, `"ReturnType example"`, `"form validation"`. Avoid broad queries like `"react"`.
+
+**If the library is NOT indexed**: ask the user if they want to scrape it, then use `mcp_docs_scrape_docs`:
+```
+library: "react"
+version: "18.2.0"      // or "18.x" for latest 18.x
+url: "https://react.dev/reference/react"
+maxPages: 500
+maxDepth: 3
+scope: "subpages"       // or "hostname" for whole site
+```
+
+Scraping is async — returns a `jobId`. Use `mcp_docs_get_job_info` to monitor progress. Once COMPLETED, search results are available.
+
+### 4. Fetch single pages (no indexing)
+
+Use `mcp_docs_fetch_url` for one-off lookups — converts any URL to Markdown without storing it. Good for: testing URLs before scraping, reading private docs (with `headers`), converting local files (`file://`).
+
+## Version Targeting Strategy
+
+| User says | Use version |
+|-----------|-------------|
+| "how do I use React hooks" | omit (latest) |
+| "React 18 hooks" | `"18.x"` |
+| "React 18.2 hooks" | `"18.2.x"` |
+| "useState in React 18.2.0" | `"18.2.0"` |
+
+## When NOT to use Docs MCP
+
+- **General web research** → use `web_search`
+- **Code examples / Stack Overflow** → use `code_search`
+- **Library is obscure / no docs site** → `web_search` or `code_search`
+- **Conceptual questions** ("what is a monad") → `web_search`
+- **Comparing libraries** → `web_search` (multiple angles via `queries`)
+
+## Anti-Patterns
+
+- Searching before checking if library is indexed
+- Using version `"latest"` string — omit the version parameter instead
+- Waiting synchronously for scraping — use `get_job_info` to poll
+- Scraping huge sites at `maxDepth: 10` — start shallow, add depth if needed
+- Using `search_docs` for queries better suited to `code_search` (how-to patterns with code snippets)
+
+## Job Management
+
+Scraping jobs flow: `queued → running → completed` (or `failed`/`cancelled`).
+
+After starting a scrape with `waitForCompletion: false` (default for MCP), check progress:
+1. `mcp_docs_list_jobs` (optionally filter `status: "running"`)
+2. `mcp_docs_get_job_info` with the `jobId`
+3. If stuck or too slow, `mcp_docs_cancel_job`
+
+Failed jobs leave the version in `FAILED` state. Re-scrape by calling `scrape_docs` again with `clean: true`.

package/files/.agents/skills/explain-it-v2/REFERENCE.md

@@ -0,0 +1,213 @@
+# Learning Science Reference
+
+## The Evidence Base
+
+### Retrieval Practice (Strongest Evidence)
+
+**What:** Actively recalling information from memory rather than passively rereading.
+
+**Evidence:** Systematic review of 50 classroom experiments found retrieval practice reliably benefits learning across materials, ages, abilities, and test types (Agarwal et al., Annual Reviews; Yang et al., Educational Psychology Review).
+
+**Why it works:** Retrieval strengthens memory traces and slows forgetting. The act of trying to remember is itself a learning event.
+
+**Application in this skill:**
+- Ask "What do you think this does?" before explaining
+- "Explain this back to me in your own words" after explaining
+- "How would you modify this to do X?" (application-level retrieval)
+
+### Generation Effect (Strong Evidence)
+
+**What:** Producing information (writing, typing, saying) leads to better retention than reading it.
+
+**Evidence:** Meta-analysis found moderate benefit (Hedges' g = .41) for generating text over reading, not due to extra time spent (Springer Nature, 2023).
+
+**Why it works:** Generation requires deeper processing and creates stronger memory traces.
+
+**Application in this skill:**
+- Always ask user to attempt an answer before showing the correct one
+- Even wrong guesses improve retention of the correct answer
+- "What would happen if we removed this line?" forces generation
+
+### Socratic Questioning (Good Evidence)
+
+**What:** Asking questions that guide thinking rather than providing direct answers. Oxford tutorial system uses this extensively.
+
+**Evidence:** Studies show Socratic-style AI questioning improves learning and engagement. One study reported 45% knowledge gain and 13% confidence boost in code comprehension (ACM, 2020).
+
+**Why it works:** Forces active thinking, reveals misconceptions, builds intellectual curiosity.
+
+**Application in this skill:**
+- "What do you think [concept] means?" before explaining
+- "Why do you think they chose to do it this way?"
+- "What would be a different approach and what are the tradeoffs?"
+
+### Bloom's Taxonomy (Widely Used Framework)
+
+**Levels (lowest to highest cognitive demand):**
+1. **Remember** — Recall facts ("What is a foreign key?")
+2. **Understand** — Explain ideas ("Why do we need foreign keys?")
+3. **Apply** — Use information in new situations ("Add a foreign key to this new table")
+4. **Analyze** — Draw connections ("How does this trigger relate to the scores table?")
+5. **Evaluate** — Justify decisions ("Is this schema design good? What would you change?")
+6. **Create** — Produce new work ("Design a schema for a similar system")
+
+**Application in this skill:**
+- Start with Remember/Understand for basic concepts
+- Progress to Apply/Analyze for retrieval checks
+- End with Evaluate/Create in application challenges
+
+### Desirable Difficulties (Bjork)
+
+**What:** Conditions that make learning harder in specific ways improve long-term retention.
+
+**Key strategies:**
+- **Spacing** — Distribute practice over time
+- **Interleaving** — Mix different topics within a session
+- **Generation** — Produce answers rather than read them
+
+**Why it works:** Difficulty during learning creates stronger memory traces. Easy learning = weak retention.
+
+**Application in this skill:**
+- Interleaving: Circle back to earlier concepts later (spaced retrieval)
+- Generation: Always ask before telling
+- Productive struggle: Let user think before giving answers
+
+### Productive Struggle
+
+**What:** Engaging with challenging tasks promotes deeper learning, even if the user gets it wrong initially.
+
+**Evidence:** "Productive Failure" research shows solving problems before receiving instruction prepares learners to notice and encode critical features (Review of Educational Research, 2021).
+
+**Why it works:** Struggle activates relevant prior knowledge and creates "hooks" for new information.
+
+**Application in this skill:**
+- Present code before explaining it
+- Ask "What do you think this does?" even if user might be wrong
+- Celebrate attempts — wrong answers are valuable learning events
+
+### Feynman Technique
+
+**What:** Explain a concept in simple language (like to a child), identify gaps, review and simplify.
+
+**Evidence:** Effectiveness derives from combining self-explanation and retrieval practice (both have strong independent research support).
+
+**Application in this skill:**
+- "Explain this back to me in your own words" is a Feynman-style retrieval
+- "How would you explain this to someone who's never seen SQL?"
+- If user struggles, that reveals a gap to address
+
+### Metacognition and Calibration
+
+**What:** "Thinking about thinking" — the ability to monitor and control your own learning. A key component is **metacognitive calibration**: how accurately you assess what you know.
+
+**Challenge:** Students are often overconfident and overestimate their understanding.
+
+**Application in this skill:**
+- Calibration phase helps user (and agent) accurately assess current knowledge
+- Retrieval checks reveal actual understanding vs perceived understanding
+- "Explain this back to me" exposes gaps the user didn't know they had
+
+## When to Use Each Technique
+
+### Generation Effect (Ask Before Telling)
+**Use when:** Introducing any new section or concept
+**Don't use when:** User clearly knows it already (from calibration)
+
+### Retrieval Practice (Explain Back)
+**Use when:** After explaining a concept, to solidify understanding
+**Don't use when:** User is struggling and needs more support first
+
+### Socratic Questioning (Guiding Questions)
+**Use when:** User gives a partial answer or you want to probe deeper
+**Don't use when:** User is clearly confused and needs direct explanation
+
+### Interleaving (Mix Concepts)
+**Use when:** Spaced retrieval phase, to strengthen connections
+**Don't use when:** User needs to master one concept before moving on
+
+### Productive Struggle (Present Challenge First)
+**Use when:** User has some baseline knowledge (from calibration)
+**Don't use when:** User is a complete beginner on this topic (just explain)
+
+## Adapting to User Level
+
+### For ✅ "Knows It" Concepts
+- Minimal generation prompts ("Quick sanity check — what does this do?")
+- Jump to higher Bloom's levels (Analyze, Evaluate)
+- Focus on project-specific usage, not general explanation
+- Retrieval checks can be application-level ("How would you change this?")
+
+### For 🟡 "Sort of Knows It" Concepts
+- Brief generation prompt ("What do you remember about this?")
+- Quick refresher explanation
+- Standard retrieval checks
+- Connect to what they already know
+
+### For ❌ "No Idea" Concepts
+- Skip generation prompt (would be frustrating, not productive)
+- Go straight to explanation with analogies and tables
+- Simple retrieval checks ("Explain this back in your own words")
+- Celebrate any attempt, even partial
+
+## Example Dialogue Flow
+
+### User says: "Explain this SQL file"
+
+**Agent (Phase 2: Calibrate):**
+> "Before we dive in, quick calibration — have you worked with SQL before, or is this new?"
+
+**User:** "I know the basics — SELECT, INSERT, that kind of thing."
+
+**Agent:** "Got it. And what about triggers and materialized views — familiar, or new territory?"
+
+**User:** "No idea what those are."
+
+**Agent (Phase 3: Active Explanation):**
+
+*Shows first section (table definitions)*
+
+> "Alright, let's start here. You know SQL basics, so — what do you think these CREATE TABLE statements are setting up? What's the relationship between these tables?"
+
+**User:** "Looks like clans, events, and scores. Events probably reference clans?"
+
+**Agent (Socratic feedback):**
+> "Spot on! Events do reference clans. Quick follow-up — what do you think happens to events if we delete a clan? Look for a clue in the SQL."
+
+**User:** "Oh, ON DELETE CASCADE — so the events get deleted too?"
+
+**Agent:**
+> "Exactly! Now here's the full breakdown..."
+
+*[Gives detailed explanation with tables and analogies]*
+
+**Agent (Retrieval check):**
+> "OK, so if I insert a new event for clan 'SIG' in season 1 worth 100 points, what happens to the clan_season_scores table?"
+
+**User:** "The trigger fires and adds 100 to SIG's season 1 total?"
+
+**Agent:**
+> "Perfect! Now let's tackle triggers and materialized views — these are new for you, so I'll explain first..."
+
+*[Goes straight to explanation without generation prompt, since user said they don't know these]*
+
+## Common Pitfalls
+
+### Over-Questioning
+**Wrong:** Asking 5 Socratic questions per section
+**Right:** 1 generation prompt + 1 retrieval check per section (max)
+
+### Ignoring Calibration
+**Wrong:** Asking "What's a SELECT statement?" when user said they know SQL
+**Right:** Skip basics, focus on project-specific usage
+
+### No Retrieval
+**Wrong:** Explaining everything without checking understanding
+**Right:** "Explain this back to me" after key concepts
+
+### Too Much Struggle
+**Wrong:** Letting user flounder on completely new concepts
+**Right:** If calibration shows "no idea", explain first, then retrieve
+
+### Passive Consumption
+**Wrong:** Long explanations without interaction
+**Right:** One section at a time, always pause for retrieval

package/files/.agents/skills/explain-it-v2/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: explain-it-v2
+description: Evidence-based interactive walkthrough using retrieval practice, Socratic questioning, and productive struggle. Calibrated to user's level. Use when user says "explain this", "walk me through", "teach me this", "break this down", or pastes an error and asks "what happened".
+---
+
+# Explain It V2
+
+Interactive, evidence-based walkthrough that challenges the user to think actively rather than passively consuming explanations.
+
+## Core Learning Principles
+
+Every interaction incorporates these evidence-based strategies:
+
+1. **Retrieval Practice** — Force recall from memory, not passive rereading
+2. **Generation Effect** — Ask user to produce an answer before showing the correct one
+3. **Socratic Questioning** — Guide through questions, don't just give answers
+4. **Productive Struggle** — Present challenges before solutions
+5. **Bloom's Taxonomy** — Progress: Remember → Understand → Apply → Analyze → Evaluate → Create
+
+See [REFERENCE.md](REFERENCE.md) for detailed learning science.
+
+## Phase 1: Gather
+
+Determine what's being explained:
+- **File in project** → read it in full
+- **Code in chat** → work from conversation directly
+- **Error message** → work from pasted text
+
+If the file references other short, directly relevant files, read those too.
+
+## Phase 2: Calibrate
+
+### Quick check (always)
+
+Ask 2-3 rapid-fire questions to gauge skill level. One at a time.
+
+**Style:** casual, "help me calibrate" not "let me test you."
+
+If a question can be answered from codebase/conversation history, figure it out yourself.
+
+### Grill session (optional)
+
+After quick check, offer to do a quick grill session based on the grill me skill.
+
+If yes: activate the grill-me skill and utilize its architecture to calibrate the user's skill level.
+
+### Build level map
+
+Tag each concept:
+- ✅ **Knows it** → correct terminology, skip basics
+- 🟡 **Sort of knows it** → brief refresh
+- ❌ **No idea** → plain English, analogies, build from scratch
+
+If user says "just explain it" → default to beginner and go.
+
+## Phase 3: Active Explanation
+
+For each section, follow this cycle:
+
+### 3a. Present (Generation Effect)
+
+Show the code WITHOUT explanation. Ask:
+
+> "Before I break this down, what do you think this section does? Even a wrong guess helps."
+
+Wait for user's attempt.
+
+### 3b. Socratic Feedback
+
+Assess their answer:
+- If correct: acknowledge, ask a follow-up to probe deeper
+- If partially correct: acknowledge what's right, ask guiding question about what's missing
+- If wrong or "no idea": that's fine, move to explanation
+
+Don't spend more than 1-2 exchanges here. The goal is activation, not interrogation.
+
+### 3c. Explain
+
+Now give the full breakdown using:
+- **Tables** for structured comparisons
+- **Analogies** for abstract concepts
+- **Plain English translations** of technical syntax
+- **Why it matters** in one line
+
+Match depth to the level map from Phase 2.
+
+### 3d. Retrieval Check
+
+After explanation, ask a retrieval question:
+- "Explain this back to me in your own words"
+- "How would you modify this to do X?"
+- "What would happen if we removed this line?"
+
+Wait for answer, give brief feedback, then move on.
+
+### For Error Messages
+
+1. **Present** — show the error, ask "What do you think went wrong?"
+2. **Socratic probe** — based on their answer, ask a follow-up
+3. **Explain** — TL;DR, fix, why it happened, prevention
+4. **Retrieval** — "If you saw this error again, what would you check first?"
+
+## Phase 4: Reinforcement
+
+After all sections:
+
+### 4a. Connection Diagram
+
+ASCII art showing how pieces relate.
+
+### 4b. Spaced Retrieval
+
+Circle back to 2-3 earlier concepts:
+- "Quick check — can you remind me what [earlier concept] does?"
+- Mix concepts from different sections (interleaving)
+
+### 4c. Application Challenge
+
+Present a new scenario requiring application:
+- "Given this schema, how would you add [new feature]?"
+- "If you wanted to change [behavior], what would you modify?"
+
+Target Apply/Analyze level of Bloom's, not just Remember.
+
+## Rules
+
+- **Never explain before asking** — always give user a chance to generate first
+- **One section at a time** for large files (>50 lines)
+- **Match the level map** — don't over-explain what they know
+- **Use their context** — reference their actual project, not generic examples
+- **Celebrate attempts** — wrong answers are valuable, acknowledge the thinking
+- **No setup overhead** — conversational only, don't create files unless asked
+- **Pause after retrieval** — wait for answer before moving on

package/files/.agents/skills/grill-me/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.

package/files/.agents/skills/grill-with-docs/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily — only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
+- **Considered Options** — only when the rejected alternatives are worth remembering
+- **Consequences** — only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.

package/files/.agents/skills/grill-with-docs/CONTEXT-FORMAT.md

@@ -0,0 +1,63 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
+- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Show relationships.** Use bold term names and express cardinality where obvious.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+- **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/files/.agents/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: grill-with-docs
+description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.
+---
+
+<what-to-do>
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time, waiting for feedback on each question before continuing.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+</what-to-do>
+
+<supporting-info>
+
+## Domain awareness
+
+During codebase exploration, also look for existing documentation:
+
+### File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).
+
+</supporting-info>