Add custom agent system with orchestration, templates, and broadened legal coverage (#21)

* Add standardized template for custom agent creation

New file: references/agent-template.md

This is a reference document that the Architect reads when generating
custom agents. It defines the exact structure every agent must follow:
YAML frontmatter format, required sections (Language, User Profile,
Inter-Agent Coordination, Core Responsibilities, Operational Rules),
placeholder tokens, and inline conventions (naming rules, tool
permissions, multilingual triggers).

The template is not an agent itself. It is a structural guide that
ensures custom agents are generated with the same quality and
consistency as the core 8.

* Add custom agent support to orchestration references

agents-registry.md:
- Added "Custom Agents" section with rules for how custom agents
  are added to the registry (naming, priority, creation flow)
- Custom agents always have lower priority than core 8
- Names must be lowercase with hyphens, no conflicts with core names

agents.md:
- Added "Custom Agents" section explaining what they are, how they
  coordinate with core agents, and how to create/edit/remove them

agent-orchestration.md:
- Added "Suggested new agent" signal format so agents can flag when
  the user needs functionality that no existing agent provides
- Added step in Dispatcher Decision Logic to check for this signal
- Added "Custom Agent Lifecycle" section covering creation, discovery,
  routing, chaining, maintenance, and deletion

* Add "Suggested new agent" capability to all 7 non-architect agents

Each agent now has a "When to suggest a new agent" subsection inside
its Inter-Agent Coordination block. When an agent detects that the
user needs functionality that no existing agent can handle, it
outputs a "Suggested new agent" section with:
- Need: what capability is missing
- Reason: why no existing agent covers it
- Suggested role: what the new agent would do

The dispatcher reads this and asks the user if they want the
Architect to create a custom agent for the detected need.

Agents are also told when NOT to suggest a new agent (existing
agent can handle it, one-off task, outside vault scope).

* Add full custom agent creation flow to the Architect

The Architect can now create, edit, and remove custom agents through
an extended conversational flow with the user.

Changes to the frontmatter:
- Added trigger phrases for custom agent creation in 6 languages
  ("create a new agent", "custom agent", "crea un nuovo agente", etc.)

New section "Custom Agent Creation" with:
- 5-phase conversation flow (Understanding, Capabilities, Output,
  Advanced, Confirmation) where the Architect asks one question at
  a time and adapts follow-ups based on user answers
- Agent file generation following references/agent-template.md
- Automatic updates to agents-registry.md and agents.md
- Management commands: edit, remove, list custom agents
- Validation rules: no name conflicts with core 8, minimal tool
  permissions by default, mandatory coordination sections
- Quality standards: Core Responsibilities must be detailed enough
  to produce a production-quality agent

Also added the "Suggested new agent" subsection (same as other agents).

* Update dispatcher routing to support custom agents

- Changed "The ONLY agents you may use are these 8" to acknowledge
  that custom agents created by the Architect are also valid
- Added row 9+ to the routing priority table for custom agents
  (always lower priority than core 8)
- Added section 9 "CUSTOM AGENTS" with routing logic: when no core
  agent matches, check agents-registry.md for custom agents
- Added check for "Suggested new agent" signals in the multi-agent
  routing decision flow (step 6)

* Add custom agents to README, CONTRIBUTING, and TERMS_OF_USE

README.md:
- Badge changed from "8 Agents" to "8+ Agents"
- Added custom agents as point 4 of "What makes this different",
  positioned right after the main pitch for maximum visibility
- Includes a table of real-life scenarios (budget tracking, journaling,
  paper reading, project monitoring, client deadline management)
- Links to Terms of Use for the responsibility disclaimer

CONTRIBUTING.md:
- Renamed "Propose a new crew member" to "Propose a new core crew
  member" with a note that users can create custom agents via Architect
- Added "Custom agents vs. core agents" section explaining the
  distinction between personal custom agents and project-shipped
  core agents

TERMS_OF_USE.md:
- Added new Section 9 "Custom Agents" with full disclaimer: custom
  agents are entirely the user's creation and responsibility, no
  warranty on their behavior, author accepts no liability
- Updated Section 7 (Limitation of Liability) to reference custom
  agents explicitly
- Renumbered sections 9-11 to 10-12

* Force the Architect to always run the full conversation before creating a custom agent

The Architect was generating custom agents immediately from a single
user message instead of going through the 5-phase conversation flow.

Added explicit blocking instructions at three points:
- Section intro: "NEVER create an agent in one shot"
- Before the conversation phases: "Do NOT generate the agent
  immediately, even if the request seems clear"
- Explicit rule: "You are NOT allowed to create the agent file
  until Phase 5"
- Reinforced one-question-per-message rule

* Force custom agent descriptions to use only the user's language

The Architect was copying the multilingual pattern from core agents
and adding translations in 6+ languages to custom agent descriptions.

Custom agents should have their description and trigger phrases
written exclusively in the language the user speaks. Reinforced
this rule in both the generation instructions and the validation
rules section.

* Force custom agent body to always be written in English

The frontmatter description uses the user's language (for trigger
matching), but the agent body (system prompt) must always be in
English for better LLM instruction-following performance. The agent
still responds in the user's language at runtime thanks to the
language matching rule.

* Add confirmation prompt before overwriting existing installation

launchme.sh:
- Detects if .claude/ or CLAUDE.md already exist in the vault
- Shows the user what will be overwritten
- Asks for explicit confirmation before proceeding
- Clarifies that custom agents and vault notes are never touched

updateme.sh:
- Asks for confirmation before overwriting core files
- Same clarification about custom agents being preserved

* Deprecate removed files instead of leaving orphans in the vault

When a file is removed from the repo (agents, references, or skills),
the updater now renames it with a "-DEPRECATED" suffix and prepends
a "DEPRECATED DO NOT USE" header instead of silently leaving it.

updateme.sh:
- Core agents in .claude/agents/ that no longer exist in the repo
  get renamed to {name}-DEPRECATED.md with deprecation header
  (custom agents are never touched)
- References in .claude/references/ that no longer exist in the repo
  get the same treatment
- The entire .claude/skills/ directory (removed from the project)
  gets renamed to .claude/skills-DEPRECATED/ with deprecation headers
  on each SKILL.md
- Summary now reports deprecated file count

launchme.sh:
- Added confirmation prompt before overwriting existing installation
- Skills generation and copying kept intact (generate-skills.py runs
  first, then copies to .claude/skills/)

* Add first-run setup section to custom agent template and creation flow

Custom agents now have a "First Run Setup" section that defines what
the agent must do the very first time it is invoked: what questions
to ask the user, what config files or folders to create, and how to
detect that it has already been set up.

agent-template.md:
- New "First Run Setup" section between Core Responsibilities and
  Operational Rules, with subsections for detection, questions to
  ask, what to create, and post-setup behavior

architect.md:
- New Phase 4 "First Run Setup" in the conversational flow where
  the Architect asks the user what the agent should do on first run
- Previous Phase 4 (Advanced) becomes Phase 5
- Previous Phase 5 (Confirmation) becomes Phase 6
- Updated blocking rules to reference Phase 6

* Redesign README header and broaden legal disclaimers for custom agents

Improve README header visual hierarchy: centered title, prominent Discord
CTA, metadata badges moved to secondary row. Replace two custom agent
examples with funnier, gender-neutral ones. Rewrite TERMS_OF_USE Section 3
from "Health and Wellness Agents" to "Custom Agents and Advice-Generating
Output" covering health, legal, financial, and all regulated domains.

* Fix reference paths in architect to use .claude/references/ prefix

The agent runs inside the vault where references live under
.claude/references/, not under references/ (which is the repo layout).

* Fix reference paths in agent-template to use .claude/references/ prefix

* Add core-manifest to protect custom agents from deprecation

launchme.sh and updateme.sh now write .core-manifest listing which agent
files were installed as core. The deprecation loop checks this manifest
before touching any file, so custom agents are never deprecated.

* Skip agent deprecation if target DEPRECATED file already exists

* Include skill count in updateme.sh summary condition and message

* Fix agents-registry.md paths in CLAUDE.md to use .claude/references/ prefix

* Add edit/remove/list trigger phrases to custom agent routing

* Deprecate stale core agents on reinstall before copying new ones

On reinstall (EXISTING=1), read the old .core-manifest and deprecate
any agent that is no longer shipped in the repo, before writing the
new manifest. Prevents stale core agents from lingering in the vault.

* Fix custom agent description: triggers are in user's language, not multilingual

* Fix updateme.sh: deprecate stale agents before rewriting manifest

The manifest was being truncated and rewritten before the deprecation
loop ran, so removed core agents were no longer in the manifest and
got skipped as "custom". Now: read old manifest -> deprecate -> copy
new agents -> rewrite manifest.

* Fix grep exit code handling when removing last entry from manifest

* Fix nested fenced code blocks in agent-template using tildes

* Add core-manifest for references to protect user-created reference docs

Same pattern as agents: launchme/updateme write a .core-manifest in
.claude/references/ listing installed core files. The deprecation loop
only touches files in the manifest, leaving user-created references
untouched.

* Move deprecated files to .claude/deprecated/ to prevent auto-discovery

Deprecated agents kept in .claude/agents/ could still be auto-discovered
by Claude Code via their frontmatter. Moving them to .claude/deprecated/
ensures they are completely invisible to the dispatcher while still
preserved for user reference.

* Harden updateme.sh from Copilot review feedback

Address multiple issues raised during PR code review:

- Skip deprecation entirely when .core-manifest is missing, preventing
  accidental deprecation of custom agents/references on first update
- Preserve user's "## Custom Agents" sections in agents-registry.md and
  agents.md during reference updates (merge strategy instead of overwrite)
- Update confirmation message to accurately reflect what is preserved

* Preserve custom agent content during install and update

- launchme.sh: skip overwriting agents-registry.md and agents.md on
  reinstall to preserve custom agent entries
- updateme.sh: extract and re-insert custom table rows from the
  registry table plus custom sections, preventing data loss when
  updating from upstream
- Require manifest before deprecating to avoid false positives

* Update wardrobe-coach example phrase in README

* Use robust string matching and printf for user-mutable refs

- Replace grep -qw with bash substring match for filename detection
- Replace echo with printf '%s\n' to prevent content mangling

* Enforce step-by-step conversation in Architect and fix registry row reinsertion

- Add HARD CONSTRAINT blocks to both onboarding and custom agent creation
  flows, forcing the use of AskUserQuestion for each question to prevent
  the Architect from skipping phases or bundling questions
- Replace hard-coded "| postman |" match in updateme.sh with generic
  last-table-row detection to avoid breaking custom row reinsertion if
  core agents are renamed or reordered

* Improve input handling in launchme.sh and updateme.sh for non-interactive shells

* Extract 13 skills from agents and update full documentation

Architecture change: complex multi-step flows (onboarding, email triage,
transcription, etc.) are now skills that run in the main conversation
context instead of agent subprocesses. This fixes the state/context loss
that caused agents to skip phases during multi-turn conversations.

Skills created (13):
- Architect: /onboarding, /create-agent, /manage-agent, /defrag
- Postman: /email-triage, /meeting-prep, /weekly-agenda, /deadline-radar
- Transcriber: /transcribe
- Librarian: /vault-audit, /deep-clean, /tag-garden
- Sorter: /inbox-triage

Agent changes:
- architect.md: -70% (1554 → 473 lines)
- transcriber.md: -72% (530 → 147 lines)
- postman.md: -42%, librarian.md: -37%, sorter.md: -11%
- All agents: explicit post-it create-if-not-exists

Scripts:
- launchme.sh/updateme.sh: copy skills/ directly, remove generate-skills.py

Docs updated:
- README.md: new Skills section, mermaid diagrams, routing
- getting-started.md, examples.md: skill references
- docs/agents/*.md: capability tables with skill vs agent routing
- references/agents.md, agent-orchestration.md, agents-registry.md,
  agent-template.md: skill registry, skill-first routing protocol

docs/agents/architect.md

@@ -12,8 +12,17 @@ Think of it as the urban planner of your knowledge city. It decides where things
 
 ## Capabilities
 
-- **Full vault onboarding**: a guided, conversational setup that creates your entire vault from scratch based on your answers
-- **User profile creation**: saves your preferences, language, goals, and context so every agent can serve you better
+The Architect agent handles reactive, single-shot structural operations. Several of its more complex, multi-step flows have been promoted to dedicated skills that run as guided conversations:
+
+| Capability | Now handled by |
+|---|---|
+| Full vault onboarding | `/onboarding` skill |
+| Vault defragmentation | `/defrag` skill |
+| Custom agent creation | `/create-agent` skill |
+| Custom agent management | `/manage-agent` skill |
+
+What the Architect agent still does directly:
+
 - **Folder management**: creates, restructures, and archives folders as your life evolves
 - **Template management**: builds and maintains Templater-compatible templates for meetings, ideas, tasks, projects, people, daily notes, and more
 - **Tag taxonomy**: maintains the official tag list, enforces naming rules, and prevents tag sprawl
@@ -26,16 +35,19 @@ Think of it as the urban planner of your knowledge city. It decides where things
 
 ## How to use it
 
-Start a conversation with any of these phrases (in any language):
+Start a conversation with any of these phrases (in any language). Some phrases invoke a dedicated skill instead of the agent directly:
 
-- "Initialize my vault" / "Set up the vault" / "Onboarding"
-- "Create a new project folder for [name]"
-- "I need a new area for [topic]"
-- "Add a template for [type]"
-- "Update the tag taxonomy"
-- "Restructure my vault"
-- "I changed jobs, update my profile"
-- "Create a MOC for [topic]"
+- "Initialize my vault" / "Set up the vault" / "Onboarding" --> invokes the `/onboarding` skill
+- "Create a new agent" / "I need a new agent" --> invokes the `/create-agent` skill
+- "Edit my agent" / "Remove agent" / "List agents" --> invokes the `/manage-agent` skill
+- "Defragment the vault" / "Weekly defrag" --> invokes the `/defrag` skill
+- "Create a new area for [topic]" --> invokes the Architect agent directly
+- "Create a new project folder for [name]" --> Architect agent
+- "Add a template for [type]" --> Architect agent
+- "Update the tag taxonomy" --> Architect agent
+- "Restructure my vault" --> Architect agent
+- "I changed jobs, update my profile" --> Architect agent
+- "Create a MOC for [topic]" --> Architect agent
 
 In Italian: "Inizializza il vault", "Nuovo progetto", "Configura il vault"
 In French: "Initialiser le vault", "Nouveau projet"
@@ -107,3 +119,7 @@ Want me to apply these changes?
 - **Ask for restructuring when things feel messy.** If you notice notes piling up in the wrong places or tags multiplying, ask the Architect to audit and evolve the structure.
 - **Update your profile when your life changes.** New job? New language? New goal? Tell the Architect so every agent stays in sync.
 - **Start small.** You do not need all 10 agents on day one. Start with the core (Architect, Scribe, Sorter, Seeker) and add more as your vault grows.
+
+## What it remembers
+
+The Architect keeps a post-it in `Meta/states/architect.md` that tracks its progress across conversations. This is especially important during onboarding and custom agent creation: if the conversation is interrupted, the Architect picks up exactly where it left off. After a completed operation, it remembers what it did (folders created, structural issues detected) so it has context for next time.

docs/agents/connector.md

@@ -120,3 +120,7 @@ Want me to create any of these connections?
 - **Watch the orphan rate.** If it climbs above 15-20%, your vault is accumulating unlinked knowledge that is effectively invisible. Run a graph audit.
 - **Do not over-link.** The Connector follows a quality-over-quantity principle. A few meaningful links are worth more than dozens of superficial ones. Trust its judgment.
 - **Check the people network.** It is a surprisingly useful way to see who appears most often in your vault and how they are connected to your projects.
+
+## What it remembers
+
+The Connector keeps a post-it in `Meta/states/connector.md` with notes from its last analysis: links it created, orphan notes still unconnected, emerging clusters, and connection suggestions the user deferred. This gives it a head start on the next graph analysis.

docs/agents/librarian.md

@@ -12,33 +12,39 @@ The Librarian is conservative by design. It never deletes anything, only archive
 
 ## Capabilities
 
-- **6-phase full audit**: structural scan, duplicate detection, link integrity, frontmatter audit, MOC review, and health report generation
+Several of the Librarian's more complex, multi-step flows have been promoted to dedicated skills that run as guided conversations:
+
+| Capability | Now handled by |
+|---|---|
+| Full 7-phase vault audit | `/vault-audit` skill |
+| Deep clean (extended cleanup) | `/deep-clean` skill |
+| Tag garden (tag analysis and cleanup) | `/tag-garden` skill |
+
+What the Librarian agent still does directly:
+
 - **Quick health check**: a lighter version focusing on the most common issues (broken links, inbox stragglers, recent duplicates)
-- **Deep clean**: aggressive audit that catches everything, including near-duplicate content with 70%+ overlap
+- **Consistency report**: shows exactly what is wrong and what was fixed, with counts and percentages
+- **Growth analytics**: tracks your vault's growth over time (notes per week, links per note, health score trends)
+- **Stale content detector**: identifies notes not touched in 30, 60, or 90 days across active areas
 - **Duplicate detection**: finds exact filename matches, "(copy)" variants, sync conflicts, and content-similar notes
 - **Broken link repair**: identifies wikilinks pointing to non-existent notes and fixes or flags them
 - **Orphan note rescue**: finds notes with zero incoming links and suggests where they should be connected
 - **Frontmatter consistency**: checks that every note has required fields (type, date, tags, status) and fixes format issues automatically
-- **Tag audit**: validates all tags against the official taxonomy and flags unknown or duplicate-meaning tags
-- **Consistency report**: shows exactly what is wrong and what was fixed, with counts and percentages
-- **Growth analytics**: tracks your vault's growth over time (notes per week, links per note, health score trends)
-- **Stale content detector**: identifies notes not touched in 30, 60, or 90 days across active areas
-- **Tag garden**: cleans up tag sprawl by finding redundant, misspelled, or orphaned tags
 - **Message archive cleanup**: archives resolved agent messages older than 7 days
 
 ## How to use it
 
-Run the Librarian periodically to maintain vault quality:
+Run the Librarian periodically to maintain vault quality. Some phrases invoke a dedicated skill instead of the agent:
 
-- "Weekly review" / "Run the weekly audit"
-- "Check vault health" / "Quick health check"
-- "Are there any duplicates?"
-- "Deep clean the vault"
-- "Fix broken links"
-- "Show me orphan notes"
-- "Consistency report"
-- "How has my vault grown?"
-- "Clean up the tags"
+- "Weekly review" / "Run the weekly audit" / "Vault audit" --> invokes the `/vault-audit` skill
+- "Deep clean the vault" --> invokes the `/deep-clean` skill
+- "Clean up the tags" / "Tag garden" --> invokes the `/tag-garden` skill
+- "Check vault health" / "Quick health check" --> Librarian agent
+- "Are there any duplicates?" --> Librarian agent
+- "Fix broken links" --> Librarian agent
+- "Show me orphan notes" --> Librarian agent
+- "Consistency report" --> Librarian agent
+- "How has my vault grown?" --> Librarian agent
 
 In Italian: "Review settimanale", "Controlla il vault", "Ci sono duplicati?", "Pulizia"
 In French: "Revision hebdomadaire", "Verifier le vault"
@@ -130,3 +136,7 @@ Your vault is growing healthily. The link density improvement is a good sign. Th
 - **Pay attention to the health score.** It is a single number that tells you how well-maintained your vault is. Aim for 85%+.
 - **Use growth analytics for motivation.** Seeing your vault grow in notes, links, and quality is surprisingly satisfying and helps you stay consistent.
 - **Act on archive suggestions.** Stale content in active areas adds noise. Archiving old notes keeps your working areas focused.
+
+## What it remembers
+
+The Librarian keeps a post-it in `Meta/states/librarian.md` with notes from its last audit: issues found, problems fixed, and recurring problems across audits. This lets it track whether vault health is improving or degrading over time.

docs/agents/postman.md

@@ -12,31 +12,39 @@ It works in four modes: email triage (scan and save important emails), calendar
 
 ## Capabilities
 
-- **Email triage**: scans unread Gmail messages, filters out noise (newsletters, notifications, receipts), and saves relevant emails as structured notes with action items and deadlines
-- **VIP filter**: prioritizes emails from important contacts (colleagues, clients, key people)
+Several of the Postman's more complex, multi-step flows have been promoted to dedicated skills that run as guided conversations:
+
+| Capability | Now handled by |
+|---|---|
+| Email triage (scan and process unread emails) | `/email-triage` skill |
+| Meeting prep (comprehensive meeting brief) | `/meeting-prep` skill |
+| Weekly agenda (day-by-day week overview) | `/weekly-agenda` skill |
+| Deadline radar (unified deadline timeline) | `/deadline-radar` skill |
+
+What the Postman agent still does directly:
+
 - **Calendar import**: pulls upcoming Google Calendar events into the vault as meeting prep notes with participant lists and agenda
 - **Event creation**: creates Google Calendar events from your requests or from deadlines found in vault notes
 - **Targeted search**: searches Gmail or Calendar for specific topics, people, or date ranges
-- **Deadline radar**: extracts all upcoming deadlines from recent emails and presents them in one view
-- **Meeting prep**: creates pre-meeting notes from calendar events with participant context from your People folder
-- **Weekly agenda**: generates a week-at-a-glance view combining calendar events and email-sourced deadlines
+- **VIP filter**: prioritizes emails from important contacts (colleagues, clients, key people)
+- **Email drafting**: drafts reply emails based on vault context
 - **Travel mode**: when it detects travel-related events (flights, hotels, conferences), creates a consolidated travel itinerary note
 - **Thread intelligence**: reads entire email threads and synthesizes key points and latest developments
 - **Attachment awareness**: flags emails with attachments (cannot process them, but notes their existence)
 
 ## How to use it
 
-Trigger the Postman for email and calendar tasks:
+Trigger the Postman for calendar and targeted email tasks. Some phrases invoke a dedicated skill instead of the agent:
 
-- "Check my email" / "Triage my inbox"
-- "What's on my calendar this week?"
-- "Create an event for Friday at 3pm"
-- "Are there any urgent emails?"
-- "Import this week's meetings"
-- "Find emails about [topic]"
-- "What deadlines are coming up?"
-- "Prepare me for tomorrow's meetings"
-- "Weekly agenda"
+- "Check my email" / "Triage my inbox" --> invokes the `/email-triage` skill
+- "Prepare me for tomorrow's meetings" --> invokes the `/meeting-prep` skill
+- "Weekly agenda" / "Plan my week" --> invokes the `/weekly-agenda` skill
+- "What deadlines are coming up?" --> invokes the `/deadline-radar` skill
+- "What's on my calendar this week?" --> Postman agent
+- "Create an event for Friday at 3pm" --> Postman agent
+- "Import this week's meetings" --> Postman agent
+- "Find emails about [topic]" --> Postman agent
+- "Draft a reply to [person]" --> Postman agent
 
 In Italian: "Controlla la mail", "Cosa ho in inbox", "Crea evento", "Cosa ho in calendario"
 In French: "Verifie mes emails", "Qu'est-ce que j'ai au calendrier"
@@ -124,3 +132,7 @@ Shall I proceed?
 - **Trust the noise filter.** The Postman is aggressive about filtering newsletters, notifications, and receipts. If it ever filters something important, tell it. It learns from your corrections.
 - **Check "needs your input" items.** The Postman flags ambiguous emails rather than guessing. These are usually worth a quick look.
 - **Make sure Gmail and Google Calendar are connected.** The Postman needs API access to your accounts. Check `Meta/user-profile.md` to verify integrations are enabled, or ask the Architect during onboarding.
+
+## What it remembers
+
+The Postman keeps a post-it in `Meta/states/postman.md` with notes from its last run: when it last scanned the inbox, emails it saved to the vault, pending follow-ups, and upcoming deadlines it detected. This prevents re-processing the same emails and keeps deadline tracking continuous.

docs/agents/scribe.md

@@ -107,3 +107,7 @@ Filed as `2026-03-21 - Idea - Tiered Pricing Model.md` with `source: voice-note`
 - **Say "brainstorm" when you want zero filtering.** The Scribe will capture every idea without judging, then gently highlight the best ones.
 - **Check the suggested connections.** The Scribe adds a Connections section at the end of each note. These are quick wins for building your knowledge graph.
 - **Trust the assumptions.** The Scribe makes judgment calls when your input is ambiguous. It always tells you what it assumed, so you can correct it if needed.
+
+## What it remembers
+
+The Scribe keeps a post-it in `Meta/states/scribe.md` with notes from its last run: which notes it created, brainstorm topics in progress, and assumptions it made. This means if you come back to continue a brainstorm or refine a note, the Scribe already has context.

docs/agents/seeker.md

@@ -111,3 +111,7 @@ Would you like to create notes for any of these gaps, or search for related cont
 - **Ask about gaps.** "What am I missing about [topic]?" triggers the missing knowledge detector, which is surprisingly useful for learning and project planning.
 - **Combine criteria.** "Find all notes tagged #urgent that mention Marco from the last two weeks." The Seeker handles compound queries.
 - **Use it to update notes.** Instead of finding a note and editing it yourself, tell the Seeker: "Update the note about X with this new info."
+
+## What it remembers
+
+The Seeker keeps a post-it in `Meta/states/seeker.md` with notes from its last search: what you searched for, what was found (or not), and recurring topics. This helps it refine future searches and flag vault gaps it has noticed over time.

docs/agents/sorter.md

@@ -12,7 +12,14 @@ Run the Sorter daily (or whenever your Inbox feels cluttered) and your vault sta
 
 ## Capabilities
 
-- **Standard triage**: processes inbox notes one by one, classifying and filing each to its proper location
+Standard inbox triage has been promoted to a dedicated skill:
+
+| Capability | Now handled by |
+|---|---|
+| Standard inbox triage (classify, route, update MOCs, extract actions) | `/inbox-triage` skill |
+
+What the Sorter agent still does directly:
+
 - **Smart batch mode**: groups related notes by project, topic, or date before filing, so related notes end up cross-linked
 - **Priority triage**: scans the inbox and ranks notes by urgency (critical, high, normal, low), filing the most important ones first
 - **Project pulse**: generates an activity report showing which projects received the most new notes and which have gone quiet
@@ -25,14 +32,13 @@ Run the Sorter daily (or whenever your Inbox feels cluttered) and your vault sta
 
 ## How to use it
 
-Trigger the Sorter when your Inbox has accumulated notes:
+Trigger the Sorter when your Inbox has accumulated notes. Some phrases invoke a dedicated skill instead of the agent:
 
-- "Triage my inbox" / "Process inbox" / "File my notes"
-- "Batch sort" / "Smart batch" (for 10+ notes)
-- "Priority triage" / "Urgent first" / "What needs attention?"
-- "Project pulse" / "Which projects are active?"
-- "What's piling up?"
-- "Evening triage" / "Daily digest"
+- "Triage my inbox" / "Process inbox" / "File my notes" --> invokes the `/inbox-triage` skill
+- "Batch sort" / "Smart batch" (for 10+ notes) --> Sorter agent
+- "Priority triage" / "Urgent first" / "What needs attention?" --> Sorter agent
+- "Project pulse" / "Which projects are active?" --> Sorter agent
+- "Evening triage" / "Daily digest" --> Sorter agent
 
 In Italian: "Smista la inbox", "Pulisci la inbox", "Svuota inbox"
 In French: "Trie la boite de reception", "Range mes notes"
@@ -127,3 +133,7 @@ Emerging Topics (not yet a project/area):
 - **Check the archive suggestions.** At the end of every triage, the Sorter flags stale notes. Archiving keeps your active areas lean.
 - **Use project pulse weekly.** It is a quick way to see where your energy is actually going versus where you think it is going.
 - **Never delete notes.** The Sorter follows a strict no-deletion policy. Notes are moved, archived, or merged, never destroyed.
+
+## What it remembers
+
+The Sorter keeps a post-it in `Meta/states/sorter.md` with notes from its last triage: files still in the inbox, ambiguous notes it deferred, and filing patterns it noticed. This helps it pick up where it left off and avoid re-processing notes it already handled.

docs/agents/transcriber.md

@@ -4,14 +4,18 @@
 
 ## What it does
 
-The Transcriber takes raw audio transcripts (meetings, lectures, podcasts, interviews, voice memos) and transforms them into richly structured Obsidian notes. It does not just clean up text. It extracts the intelligence: decisions made, action items with owners and deadlines, key insights, emotional dynamics, and follow-up needs.
+All transcription processing is now handled by the `/transcribe` skill, which runs as a guided, multi-turn conversation. The skill takes raw audio transcripts (meetings, lectures, podcasts, interviews, voice memos) and transforms them into richly structured Obsidian notes. It does not just clean up text. It extracts the intelligence: decisions made, action items with owners and deadlines, key insights, emotional dynamics, and follow-up needs.
 
-Paste a messy Zoom transcript full of filler words and speaker labels, and the Transcriber will produce a polished meeting note with an executive summary, a decisions log, an action items table with confidence scores, and even a draft follow-up email you can send to attendees. Paste lecture notes, and it creates study-ready material with key concepts, definitions, and exam-relevant highlights.
+Paste a messy Zoom transcript full of filler words and speaker labels, and the `/transcribe` skill will produce a polished meeting note with an executive summary, a decisions log, an action items table with confidence scores, and even a draft follow-up email you can send to attendees. Paste lecture notes, and it creates study-ready material with key concepts, definitions, and exam-relevant highlights.
 
-The Transcriber works with whatever you give it, whether that is output from Whisper, Otter.ai, Google Meet auto-transcription, or your own handwritten notes from a call. It adapts its parsing to the source format and asks just enough context questions to produce the best possible output.
+The `/transcribe` skill works with whatever you give it, whether that is output from Whisper, Otter.ai, Google Meet auto-transcription, or your own handwritten notes from a call. It adapts its parsing to the source format and asks just enough context questions to produce the best possible output.
+
+The Transcriber agent itself is kept for edge cases and direct follow-ups not covered by the skill.
 
 ## Capabilities
 
+All of the following capabilities are delivered through the `/transcribe` skill:
+
 - **Meeting notes**: full meeting processing with executive summary, key points, decisions log, action items table (with confidence scores), detailed notes by topic, open questions, next steps, and a follow-up email draft
 - **Lecture notes**: structured academic notes with key concepts, definitions, exam-relevant points, and connections to previous material
 - **Podcast summaries**: TL;DR, numbered key insights, notable quotes, detailed breakdown by topic, and resources mentioned
@@ -26,7 +30,7 @@ The Transcriber works with whatever you give it, whether that is output from Whi
 
 ## How to use it
 
-Paste a transcript or describe what you want to process:
+Paste a transcript or describe what you want to process. All of these phrases invoke the `/transcribe` skill:
 
 - "Transcribe this meeting: [paste transcript]"
 - "Process these meeting notes"
@@ -130,3 +134,7 @@ Saved as `2026-03-21 - Voice Journal - New Project Tensions.md`. Want to review
 - **Check the confidence scores on action items.** "High" means someone explicitly said it. "Low" means the Transcriber inferred it from context, so verify these.
 - **Use voice journal mode for personal reflections.** It preserves your authentic voice instead of making everything sound corporate.
 - **Paste raw transcripts without cleanup.** The Transcriber handles filler words, broken sentences, and transcription artifacts. Do not waste time pre-editing.
+
+## What it remembers
+
+The Transcriber keeps a post-it in `Meta/states/transcriber.md` with notes from its last transcription: speaker names and roles it learned, meeting series context, and domain terminology it discovered. This means it gets better at identifying speakers and jargon over time.

docs/examples.md

@@ -31,7 +31,7 @@ Practical scenarios showing how the Crew works in daily life. Each example shows
 > "Triage my inbox"
 
 **What happens:**
-1. **Sorter** scans all 12 notes in `00-Inbox/`
+1. The `/inbox-triage` skill scans all 12 notes in `00-Inbox/`
 2. Reads each note's content and frontmatter
 3. Files them:
    - 3 meeting notes go to `06-Meetings/2026/03/`
@@ -55,7 +55,7 @@ Practical scenarios showing how the Crew works in daily life. Each example shows
 *[pastes raw transcript]*
 
 **What happens:**
-1. **Transcriber** processes the raw text
+1. The `/transcribe` skill processes the raw text
 2. Identifies speakers from context
 3. Generates:
    - Executive summary (4 sentences)
@@ -78,7 +78,7 @@ Practical scenarios showing how the Crew works in daily life. Each example shows
 > "Check my email for anything urgent"
 
 **What happens:**
-1. **Postman** scans your Gmail inbox (last 48 hours)
+1. The `/email-triage` skill scans your Gmail inbox (last 48 hours)
 2. Reads 34 emails
 3. Filters:
    - 22 newsletters/promos/notifications are ignored
@@ -121,7 +121,7 @@ Practical scenarios showing how the Crew works in daily life. Each example shows
 > "Run the weekly review"
 
 **What happens:**
-1. **Librarian** runs a 6-phase audit:
+1. The `/vault-audit` skill runs a multi-phase audit:
    - Structure scan: all folders intact
    - Duplicate detection: found 1 near-duplicate
    - Link integrity: 3 broken links fixed automatically, 2 orphan notes flagged
@@ -157,16 +157,16 @@ Practical scenarios showing how the Crew works in daily life. Each example shows
 
 ## Daily Workflow Cheat Sheet
 
-| Time | What to say | Agent |
-|------|------------|-------|
-| Morning | "What's on my calendar today?" | Postman |
-| Morning | "Check my email" | Postman |
-| Any time | "Save this: [thought]" | Scribe |
-| After meeting | "Transcribe this meeting: [paste]" | Transcriber |
-| Evening | "Triage my inbox" | Sorter |
-| Weekly | "Weekly review" | Librarian |
-| When lost | "Find [topic]" | Seeker |
-| When stuck | "Find connections for [note]" | Connector |
+| Time | What to say | Skill/Agent |
+|------|------------|-------------|
+| Morning | "What's on my calendar today?" | Postman agent |
+| Morning | "Check my email" | `/email-triage` skill |
+| Any time | "Save this: [thought]" | Scribe agent |
+| After meeting | "Transcribe this meeting: [paste]" | `/transcribe` skill |
+| Evening | "Triage my inbox" | `/inbox-triage` skill |
+| Weekly | "Weekly review" | `/vault-audit` skill |
+| When lost | "Find [topic]" | Seeker agent |
+| When stuck | "Find connections for [note]" | Connector agent |
 
 ---
 

docs/getting-started.md

@@ -96,8 +96,8 @@ When it's done, your vault will look like this:
 ```
 your-vault/
 ├── .claude/
-│   ├── agents/          ← 8 crew agents (Claude Code CLI)
-│   ├── skills/          ← 8 crew skills (Claude Code Desktop / Cowork)
+│   ├── agents/          ← 8 lightweight crew agents
+│   ├── skills/          ← 13 specialized skills for complex flows
 │   └── references/      ← shared docs the agents read
 ├── CLAUDE.md            ← project instructions
 ├── .mcp.json            ← Gmail + Calendar (only if you said yes)
@@ -130,7 +130,7 @@ This is the fun part. Just type:
 
 > **"Initialize my vault"**
 
-The **Architect** agent will wake up and start a friendly conversation with you. It will ask:
+The `/onboarding` skill will kick in and the **Architect** will start a friendly conversation with you. It will ask:
 
 ### About you
 - What should I call you?
@@ -149,6 +149,12 @@ The **Architect** agent will wake up and start a friendly conversation with you.
 
 After the conversation, the Architect creates your entire vault structure, saves your profile, and leaves you a personalized welcome note.
 
+### Agent memory (Post-it)
+
+Every agent has a small "post-it" file in `Meta/states/` where it jots down notes for its next run. This means agents remember what they did last time: the Sorter knows which files it already triaged, the Scribe remembers what you were brainstorming about, the Architect knows which onboarding step you were on if the conversation was interrupted.
+
+You don't need to manage these files — agents handle them automatically. Each post-it is limited to 30 lines, so they never grow out of control.
+
 ---
 
 ## Step 6: Start using it
@@ -168,12 +174,12 @@ The **Scribe** detects multiple items and creates separate notes for each.
 ### Check your email
 > "Check my email for anything important"
 
-The **Postman** scans your Gmail, saves actionable emails, and gives you a summary.
+The `/email-triage` skill scans your Gmail, saves actionable emails, and gives you a summary.
 
 ### File everything
 > "Triage my inbox"
 
-The **Sorter** processes all notes in your inbox and files them to the right places.
+The `/inbox-triage` skill processes all notes in your inbox and files them to the right places.
 
 ### Search your brain
 > "What do I know about the Henderson project?"
@@ -197,14 +203,14 @@ The Crew works best with simple daily routines:
 > "Triage my inbox" to let the Sorter file everything
 
 ### Weekly (10 minutes)
-> "Weekly review" for a full vault health check from the Librarian
+> "Weekly review" to run the `/vault-audit` skill for a full vault health check
 
 ---
 
 ## Troubleshooting
 
 ### "The agent doesn't seem to activate"
-Make sure Claude Code is open inside your vault folder (not a different directory). Verify the agent files exist at `.claude/agents/` in your vault. If you're using Cowork/Desktop, check that `.claude/skills/` was also created by the installer. Try saying the trigger phrase differently. Agents understand natural language in multiple languages.
+Make sure Claude Code is open inside your vault folder (not a different directory). Verify agent files exist at `.claude/agents/` and skill files at `.claude/skills/` in your vault. Try saying the trigger phrase differently. Agents and skills understand natural language in multiple languages.
 
 ### "Gmail/Calendar isn't working"
 The Postman needs Gmail and Google Calendar MCP connectors. Run the installer again (`bash scripts/launchme.sh`) and answer **yes** to the Gmail/Calendar question, or manually copy `.mcp.json` from the repo to your vault root. Then authorize the connection when Claude Code prompts you.