From dcaae00d950f23675cfc41e1d973ddbe0fa9be25 Mon Sep 17 00:00:00 2001
From: jared <jaredmswanson@gmail.com>
Date: Tue, 30 Jun 2026 16:26:02 -0400
Subject: [PATCH] vault: session notes 2026-06-30

---
 _templates/convention.md                  |  43 +++++++++
 _templates/howto.md                       |  45 +++++++++
 _templates/reference.md                   | 110 ++++++++++++++++++++++
 howto/airtable-mcp-setup.md               |   4 +
 howto/design-mode-workflow.md             |  21 +----
 reference/agent-orchestration-cookbook.md |  17 ++--
 reference/agent-orchestration-patterns.md |   4 +
 7 files changed, 215 insertions(+), 29 deletions(-)
 create mode 100644 _templates/convention.md
 create mode 100644 _templates/howto.md
 create mode 100644 _templates/reference.md

diff --git a/_templates/convention.md b/_templates/convention.md
new file mode 100644
index 0000000..732147b
--- /dev/null
+++ b/_templates/convention.md
@@ -0,0 +1,43 @@
+---
+type: convention
+title: [Human-readable title]
+summary: [1-2 sentences answering "When I encounter X, what rule should I follow, and why?"]
+tags:
+  - type/convention
+  - domain/[field]
+  - tool/[tool]       # if tool-specific
+  - 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
+related:
+  - [note-slug]  # cross-links to companion notes; omit if none
+source: [project name]  # project that spawned the note
+---
+
+# [Convention Name]
+
+## Purpose
+<!-- 1–2 sentences: what recurring decision or situation this convention governs and why it matters. Do NOT restate the summary. -->
+
+## Core Principles
+<!-- 3–7 principles, each stated as a rule PLUS its rationale ("do X because Y"), not a bare directive. Number them. -->
+
+**1. [Principle stated as a rule].**
+[Rationale — why this rule exists and what following it buys you.]
+
+## Patterns
+<!-- Concrete ways the principles show up in practice — what to do, with named techniques or short examples. -->
+
+**[Pattern name].** [What to do, concretely.]
+
+## Anti-Patterns
+<!-- Concrete things this convention forbids, each with the tell that flags it. What to avoid, not the principles restated. -->
+
+- **[Smell / thing to avoid]** → [why it is wrong, or what to do instead]
+
+## Exceptions
+<!-- Known cases where the convention does NOT apply, or applies differently. Omit the section only if there are genuinely none. -->
+
+**[Case].** [Why the convention bends or does not apply here.]
diff --git a/_templates/howto.md b/_templates/howto.md
new file mode 100644
index 0000000..b04a109
--- /dev/null
+++ b/_templates/howto.md
@@ -0,0 +1,45 @@
+---
+type: howto
+title: [Human-readable title]
+summary: [1-2 sentences answering "How do I accomplish X?" — the task this note covers]
+tags:
+  - type/howto
+  - domain/[field]
+  - tool/[tool]       # if tool-specific
+  - 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 ONLY if steps involve UIs/APIs that change frequently; otherwise delete this line
+related:
+  - [note-slug]  # cross-links to companion notes; omit if none
+source: [project name]  # project that spawned the note
+---
+
+# [Task Name]
+
+## Opening
+<!-- One paragraph. Do NOT restate the summary — give the when-to-reach-for-this trigger and any framing the steps assume. No background theory. -->
+
+## Prerequisites
+<!-- Checkbox list of what must be true/installed/obtained before starting; each item independently verifiable. -->
+
+- [ ] ...
+- [ ] ...
+
+## Steps
+<!-- Numbered steps. Each step = context (why/when this step) → action (the command or change) → expected result (what success looks like). -->
+
+### Step 1: [action]
+
+## Verification
+<!-- End-to-end confirmation the whole procedure worked — concrete checks/commands and their expected output (distinct from per-step expected results). -->
+
+## Gotchas
+<!-- Known failure modes and surprises, each with how to recognize it and how to recover. Omit the section only if there are genuinely none. -->
+
+## Related
+<!-- Wikilinks to companion notes, one line each on why it is relevant. -->
+
+- [[note-slug]] — why it is relevant
diff --git a/_templates/reference.md b/_templates/reference.md
new file mode 100644
index 0000000..a8685ae
--- /dev/null
+++ b/_templates/reference.md
@@ -0,0 +1,110 @@
+---
+type: reference
+subtype: pattern/framework  # REQUIRED — set to exactly one of: pattern/framework | api-integration | role-definitions | design-rules
+title: [Human-readable title]
+summary: [1-2 sentences answering "what facts do I need to look up to make a decision / integrate / understand roles?"]
+tags:
+  - type/reference
+  - domain/[field]
+  - tool/[tool]       # if tool-specific
+  - 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
+last_reviewed: YYYY-MM-DD  # REQUIRED if subtype is api-integration (mutable facts: auth, endpoints, schema); otherwise delete this line
+related:
+  - [note-slug]  # cross-links to companion notes; omit if none
+source: [project name]  # project that spawned the note
+---
+
+# [Reference Title]
+
+## Purpose
+<!-- One or two sentences: what this reference covers and the decision / integration / role-understanding it supports. Do NOT restate the summary; do NOT add background theory. -->
+
+<!-- ============================================================
+     CHOOSE YOUR SUB-TYPE — keep ONE block below, delete the other
+     three AND this selector. Match the block to the `subtype` set in
+     frontmatter. Each block lists its body sections.
+
+       pattern/framework   → Core Principles · Decision Framework · Patterns · Anti-Patterns · Known Limitations
+       api-integration     → Setup · Authentication · Schema / Data Model · Operations · Gotchas   (REQUIRES last_reviewed)
+       role-definitions    → Roles · Inputs & Outputs · Phases · Boundaries
+       design-rules        → Rules / Standards · Examples · Exceptions
+     ============================================================ -->
+
+<!-- ===== VARIANT: pattern/framework ===== -->
+
+## Core Principles
+<!-- The 1–3 foundational ideas every pattern below rests on, each as a statement plus why it holds. Lets the reader reason about cases the patterns don't name. -->
+
+## Decision Framework
+<!-- When to choose what — a flowchart, decision tree, or table mapping situation → choice. This is the section the reader scans first to pick an approach. -->
+
+## Patterns
+<!-- Named patterns, each with: when to use it, why it works, and (optional) a short example. One sub-heading per pattern. -->
+
+### [Pattern name]
+<!-- When → why → optional short example. -->
+
+## Anti-Patterns
+<!-- What to avoid, each with the tell that flags it and the fix. Not the principles restated. -->
+
+- **[Anti-pattern / smell]** → [why it is wrong, or what to do instead]
+
+## Known Limitations
+<!-- Boundary / version-sensitive caveats: where the framework stops applying or depends on a tool's current behavior. Omit only if genuinely none. -->
+
+<!-- ===== VARIANT: api-integration ===== -->
+<!-- REQUIRES `last_reviewed` in frontmatter — these are mutable facts that drift. -->
+
+## Setup
+<!-- Prerequisites and connection steps to get the integration working: accounts, base URLs, SDK/version, env vars. Enough to go from zero to a first call. -->
+
+## Authentication
+<!-- Auth method (key / OAuth / token), where credentials live, and how tokens are obtained/refreshed. The reader configures auth from this alone. -->
+
+## Schema / Data Model
+<!-- The entities, key fields, and types the integration exposes. What the reader maps their data to. Tables work well here. -->
+
+## Operations
+<!-- The common operations / endpoints with their purpose and minimal usage shape (params in, result out). The reader picks the right call from this. -->
+
+## Gotchas
+<!-- Rate limits, quirks, breaking-change history, and version-sensitive behavior. The reader avoids the pitfall before hitting it. Omit only if genuinely none. -->
+
+<!-- ===== VARIANT: role-definitions ===== -->
+
+## Roles
+<!-- Each role/agent and its one-line responsibility. One sub-heading or list item per role. The reader assigns work from this. -->
+
+- **[Role]** — [responsibility in one line]
+
+## Inputs & Outputs
+<!-- What each role consumes and produces, so handoffs wire up correctly. A table (role · input · output) works well. -->
+
+## Phases
+<!-- The ordered phases/sequence and which role acts in each. The reader sequences the workflow from this. -->
+
+## Boundaries
+<!-- What each role does NOT do — the edges that prevent overlap or overreach. Omit only if genuinely none. -->
+
+<!-- ===== VARIANT: design-rules ===== -->
+<!-- This is LOOKUP material (established standards/values), not behavioral rules-with-rationale — that is the `convention` type. Keep entries as facts to conform to, not principles to internalize. -->
+
+## Rules / Standards
+<!-- The established standards as directives or values to conform to (e.g., the spacing scale, the naming format, the allowed set). The reader checks their work against these. -->
+
+- **[Rule / standard]** — [the value or directive]
+
+## Examples
+<!-- Concrete correct applications of the standards — what conformance looks like. The reader mirrors these. -->
+
+## Exceptions
+<!-- Where the standards do not apply or apply differently. Omit only if genuinely none. -->
+
+## Related
+<!-- Wikilinks to companion notes, one line each on why it is relevant. Keep this section in whichever variant you choose. -->
+
+- [[note-slug]] — why it is relevant
diff --git a/howto/airtable-mcp-setup.md b/howto/airtable-mcp-setup.md
index f231187..706bc17 100644
--- a/howto/airtable-mcp-setup.md
+++ b/howto/airtable-mcp-setup.md
@@ -17,6 +17,8 @@ update_note: experience-driven
 
 This guide sets up the Airtable MCP server in a Claude Code project using **project-local scope** — so MCP only loads when you're working in this project, not every session. Use it whenever you're starting a new project that reads or writes Airtable data via Claude Code.
 
+This note is flagged `update_note: experience-driven` — when a session follows these steps and finds a discrepancy (API changes, UI shifts, scope updates), update the steps rather than relying on a review date. The frontmatter contract in `vault-conventions.md` documents this pattern.
+
 ## Prerequisites
 
 - [ ] Claude Code CLI installed and working (`claude --version`)
@@ -83,6 +85,8 @@ Replace `YOUR_PROD_BASE_ID` with the actual production base ID (format: `appXXXX
 
 ### Step 3: Add project-assets reference doc
 
+**Customization Point**: Adapt the file path and structure below to match your project's conventions. This step captures project-specific Airtable configuration that may differ from project to project.
+
 Create `docs/reference/project-assets.md` to track discovered table IDs and field conventions — Airtable table IDs change if tables are recreated, so document them as you find them:
 
 ```markdown
diff --git a/howto/design-mode-workflow.md b/howto/design-mode-workflow.md
index 8266b4c..14dc921 100644
--- a/howto/design-mode-workflow.md
+++ b/howto/design-mode-workflow.md
@@ -7,7 +7,8 @@ tags:
   - tool/tailwind
   - domain/design
   - domain/dev
-scope: global
+  - project/design-mode
+scope: project
 last_updated: 2026-06-27
 ---
 
@@ -36,9 +37,7 @@ Target Design (inspiration)
      ↓
 [3] Iterate  ──→  2-3 rounds until reference matches target
      ↓
-[4] /componentize  ──→  Style base components (future capability)
-     ↓
-[5] /design  ──→  Uses config + components + style guide for creative freedom
+[4] /design  ──→  Uses config + style guide for creative freedom
 ```
 
 ## Steps
@@ -99,8 +98,6 @@ Once the foundation artifacts are stable, use `/design` for new UI work:
 
 The command uses `tailwind.config.js` (tokens) + `style-guide.md` (usage intent) as constraints, giving creative freedom within the established design language.
 
-For component work, `/componentize` (future capability) styles base components so they inherit config tokens automatically.
-
 **Expected result:** New UI output that looks consistent with the extracted design system without manually specifying colors or spacing.
 
 ## Validation Checkpoints
@@ -141,20 +138,8 @@ Replace the CDN script tags with `<link rel="stylesheet" href="dist/styles.css">
 |---------|---------|
 | `/design-to-html` | Screenshot + CSS → three foundation artifacts |
 | `/design` | Description + theme → new UI (uses config + style guide) |
-| `/componentize` | Style base components using theme tokens (future) |
 | `python tools/compress-styles.py` | Compress raw CSS before passing to design-to-html |
 
-## Project Files
-
-| File | Purpose |
-|------|---------|
-| `CLAUDE.md` | Pipeline overview for Claude Code sessions |
-| `process-guide.md` | Quick reference (source of this howto) |
-| `style-guide-template.md` | Template for style guides |
-| `tailwind-config-template.js` | Template for Tailwind config |
-| `tools/compress-styles.py` | CSS compression tool |
-| `projects/[name]/` | Per-project artifact folder |
-
 ## Tips
 
 - **Config is palette, style guide is instructor** — config says *what* values exist; style guide says *when and why* to use them
diff --git a/reference/agent-orchestration-cookbook.md b/reference/agent-orchestration-cookbook.md
index f56a59d..290e03e 100644
--- a/reference/agent-orchestration-cookbook.md
+++ b/reference/agent-orchestration-cookbook.md
@@ -1,14 +1,16 @@
 ---
 type: reference
-subtype: cookbook
+subtype: pattern/framework
 title: Agent Orchestration Cookbook
 summary: Concrete implementation examples for multi-agent orchestration — prompt templates, token budgets, error recovery, and common gotchas. Companion to the patterns hub.
 tags:
   - type/reference
   - domain/ai-agents
   - domain/orchestration
+  - tool/claude-code
 scope: global
 last_updated: 2026-06-27
+last_reviewed: 2026-06-30
 related:
   - reference/agent-orchestration-patterns
 ---
@@ -17,6 +19,8 @@ related:
 
 **Purpose**: Concrete examples, prompt templates, and gotchas for implementing the patterns in [[reference/agent-orchestration-patterns]].
 
+**Note:** Tool behavior (especially the Task tool) is version-sensitive and may change with Claude Code updates. Verify agent capabilities against current Claude Code documentation before adapting these examples to production systems.
+
 ## Phase Templates
 
 ### Phase 1 — Inventory Agent Prompt
@@ -207,16 +211,7 @@ Keep agents **flat** — peers, not hierarchies. Nested agents (agent spawns age
 
 ---
 
-## Glossary
-
-| Term | Definition |
-|---|---|
-| Tool Tax | Fixed ~20–25K token overhead per agent before any work is done |
-| Specialist | An agent that processes multiple similar items, paying tool tax once |
-| Batch | Group of agents spawned in parallel (5–8 max to respect rate limits) |
-| Manifest | JSON file tracking completed/pending/failed items for recovery |
-| Flattened | Orchestration where agents are peers at one level, not nested |
-| Idempotent | Safe to re-run — check-before-modify prevents double-processing |
+**Glossary terms** are defined in the companion patterns note: [[reference/agent-orchestration-patterns]].
 
 ---
 
diff --git a/reference/agent-orchestration-patterns.md b/reference/agent-orchestration-patterns.md
index a1217af..b7dcf0c 100644
--- a/reference/agent-orchestration-patterns.md
+++ b/reference/agent-orchestration-patterns.md
@@ -7,8 +7,10 @@ tags:
   - type/reference
   - domain/ai-agents
   - domain/orchestration
+  - tool/claude-code
 scope: global
 last_updated: 2026-06-27
+last_reviewed: 2026-06-30
 related:
   - reference/agent-orchestration-cookbook
 ---
@@ -140,6 +142,8 @@ Return: {"status": "updated|skipped|ambiguous", "changes": [...]}
 
 ## Known Limitations
 
+**Note:** Task tool behavior is version-sensitive and may change with tool updates. Verify tool capabilities in current Claude Code documentation before relying on the patterns below in production systems.
+
 - Task tool does **not** return agent IDs programmatically (visible in UI only).
 - No API to list active/completed agents.
 - `resume` parameter requires manual ID tracking — not suitable for automated orchestration.