studiograph 1.3.48-next.21 → 1.3.48-next.211

package/dist/agent/skills/interview/entity-templates.md

@@ -10,7 +10,7 @@ When the user gives a conversational answer, extract structured entities. These
 
 ## General Rules
 
-1. **Use kebab-case for entity IDs** — lowercase, hyphens, no special characters: `christian-schmidt`, `cooper-hewitt`
+1. **Use kebab-case for entity IDs** — lowercase, hyphens, no special characters: `alex-morgan`, `modern-museum`
 2. **Always set wikilinks** between related entities as you create them
 3. **Prefer the user's exact words** for names and descriptions — don't paraphrase or formalize
 4. **Never wrap content in quotes** — the `content` parameter is raw markdown, not a JSON string. Do not add leading or trailing `"` characters.
@@ -19,34 +19,34 @@ When the user gives a conversational answer, extract structured entities. These
 
 ## People from Team Descriptions
 
-**User says:** "My team is myself, Sumin who's my business partner in New York, Kenton our Director of Creative Technology also in New York, Rebecca who handles operations from South Carolina, and Annabel who's a mid-level designer here in Seattle with me."
+**User says:** "My team is myself, Jordan who's my business partner in New York, Sam our Director of Creative Technology also in New York, Casey who handles operations from South Carolina, and Taylor who's a mid-level designer here in Seattle with me."
 
 **Extract 5 person entities:**
 
 ```yaml
-# christian-schmidt.md
+# alex-morgan.md
 entity_type: person
-name: Christian Marc Schmidt
+name: Alex Morgan
 role: Founder & CEO
 status: current
 location: Seattle
-organization: "[[schema-design]]"
+organization: "[[acme-studio]]"
 
-# sumin-chou.md
+# jordan-lee.md
 entity_type: person
-name: Sumin Chou
+name: Jordan Lee
 role: Business Partner
 status: current
 location: New York
-organization: "[[schema-design]]"
+organization: "[[acme-studio]]"
 
-# kenton-powell.md
+# sam-reyes.md
 entity_type: person
-name: Kenton Powell
+name: Sam Reyes
 role: Director of Creative Technology
 status: current
 location: New York
-organization: "[[schema-design]]"
+organization: "[[acme-studio]]"
 ```
 
 **Key patterns:**
@@ -56,30 +56,30 @@ organization: "[[schema-design]]"
 
 ## Projects from Workstream Lists
 
-**User says:** "We're launching the first phase of our Cooper Hewitt collections website, working with Ridge AI on their dashboard UI, and about to start a new engagement with the Center for Civic Future on an AI knowledge hub."
+**User says:** "We're launching the first phase of our Modern Museum collections website, working with Apex Systems on their dashboard UI, and about to start a new engagement with the Civic Initiative on an AI knowledge hub."
 
 **Extract 3 project entities + ensure client orgs exist:**
 
 ```yaml
-# cooper-hewitt-collections.md
+# modern-museum-collections.md
 entity_type: project
-name: Cooper Hewitt Collections Website
+name: Modern Museum Collections Website
 category: Client Work
-client: "[[cooper-hewitt]]"
+client: "[[modern-museum]]"
 status: active
 
-# ridge-ai-dashboard.md
+# apex-systems-dashboard.md
 entity_type: project
-name: Ridge AI Dashboard UI
+name: Apex Systems Dashboard UI
 category: Client Work
-client: "[[ridge-ai]]"
+client: "[[apex-systems]]"
 status: active
 
-# ccf-knowledge-hub.md
+# civic-knowledge-hub.md
 entity_type: project
-name: CCF AI Knowledge Hub
+name: Civic AI Knowledge Hub
 category: Client Work
-client: "[[center-for-civic-future]]"
+client: "[[civic-initiative]]"
 status: active
 ```
 
@@ -90,30 +90,30 @@ status: active
 
 ## Organizations from Client Mentions
 
-**User says:** "Our clients include Cooper Hewitt, Ridge AI — which was co-founded by Jeffrey Heer and Ellie Fields — and Kite Pharma."
+**User says:** "Our clients include Modern Museum, Apex Systems — which was co-founded by Pat Rivers and Robin Shaw — and Biomed Partners."
 
 **Extract 3 organization entities + 2 person entities for named contacts:**
 
 ```yaml
-# cooper-hewitt.md
+# modern-museum.md
 entity_type: organization
-name: Cooper Hewitt, Smithsonian Design Museum
+name: Modern Museum of Design
 category: client
 status: active
 industry: Museums & Cultural Institutions
 
-# ridge-ai.md
+# apex-systems.md
 entity_type: organization
-name: Ridge AI
+name: Apex Systems
 category: client
 status: active
 industry: AI / Enterprise Software
 
-# jeffrey-heer.md
+# pat-rivers.md
 entity_type: person
-name: Jeffrey Heer
+name: Pat Rivers
 role: Co-founder
-organization: "[[ridge-ai]]"
+organization: "[[apex-systems]]"
 status: client
 ```
 
@@ -124,15 +124,16 @@ status: client
 
 ## Processes from Workflow Descriptions
 
-**User says:** "We have our Monday team meeting, a pipeline meeting Monday with Sumin and Rebecca, mid-week pipeline check-in Wednesday, and resourcing meeting Friday."
+**User says:** "We have our Monday team meeting, a pipeline meeting Monday with Jordan and Casey, mid-week pipeline check-in Wednesday, and resourcing meeting Friday."
 
-**Extract 1 process entity with structured body:**
+**Extract 1 note (tagged `Process`) with structured body:**
 
 ```yaml
 # weekly-cadence.md
-entity_type: process
+entity_type: note
 name: Weekly Team Cadence
-owner: "[[christian-schmidt]]"
+tags: [Process]
+owner: "[[alex-morgan]]"
 ```
 
 Body:
@@ -142,15 +143,15 @@ Weekly rhythm of standing meetings.
 
 ## Steps
 - **Monday — Team Meeting** (full team): Align priorities, discuss deadlines and presentations
-- **Monday — Pipeline Meeting** ([[christian-schmidt]], [[sumin-chou]], [[rebecca-ojala]]): Review new business pipeline, discuss follow-ups
+- **Monday — Pipeline Meeting** ([[alex-morgan]], [[jordan-lee]], [[casey-brooks]]): Review new business pipeline, discuss follow-ups
 - **Wednesday — Pipeline Check-in**: Mid-week pipeline status
 - **Friday — Resourcing Meeting**: Plan next week's allocation, ensure billability
 ```
 
 **Key patterns:**
-- Use wikilinks to people in the process body
+- Use wikilinks to people in the note body
 - Capture the cadence, not just the meetings — the pattern of how work flows
-- One process entity can capture multiple related meetings if they form a weekly rhythm
+- One note can capture multiple related meetings if they form a weekly rhythm
 
 ## Website Content Extraction
 
@@ -183,7 +184,7 @@ When the user provides a website URL, fetch it and extract:
 - "We work with some museums" → Don't create entities. Ask: "Which museums specifically?"
 
 **When names are incomplete:**
-- "My partner Sumin" → Create with what you have, follow up: "What's Sumin's last name and role?"
+- "My partner Jordan" → Create with what you have, follow up: "What's Jordan's last name and role?"
 
 **When relationships are unclear:**
 - "We're talking to a pharma company" → Don't create a deal yet. Ask: "Which company? Is this an active deal or early conversation?"

package/dist/agent/skills/interview/question-domains.md

@@ -8,7 +8,7 @@ loading: on-demand
 
 Work through these topics in order. Ask one question at a time. Create entries immediately from each answer. Adapt phrasing if website context or prior answers already covered the topic.
 
-**Important:** Route entries to the correct collection (see skill.md Collection Structure). Create new collections as you reach the relevant topics. Never set optional fields to empty strings — omit them entirely if unknown.
+**Important:** Route entries to the correct folder (see skill.md Folder Structure). Create new folders as you reach the relevant topics. Never set optional fields to empty strings — omit them entirely if unknown.
 
 ---
 
@@ -37,17 +37,17 @@ If provided:
 
 **With website context:** "I see from your site that [description]. Is that accurate? What would you add or change?"
 
-**Collection:** Create the `{org-name}` collection (function graph type) first. This is the org's home collection.
+**Folder:** Create the `{org-name}` folder (function graph type) first. This is the org's home folder.
 
-**Creates:** `organization` entry in the org collection with name, category, status, industry, website fields. This is the anchor entry — most other entries will link back to it. The body should include a substantive overview, philosophy/mission, and team roster.
+**Creates:** `organization` entry in the org folder with name, category, status, industry, website fields. This is the anchor entry — most other entries will link back to it. The body should include a substantive overview, philosophy/mission, and team roster.
 
 ```yaml
 entity_type: organization
-entity_id: schema-design
-name: Schema Design
+entity_id: acme-studio
+name: Acme Studio
 status: active
 industry: Design & Technology
-website: https://schemadesign.com
+website: https://example.com
 ```
 
 **Sufficiently covered when:** Organization entry exists with name, a rich markdown body (overview, philosophy, services), and at least industry set.
@@ -64,18 +64,18 @@ website: https://schemadesign.com
 
 **With website context:** "I see [names] on your team page. Are they all current? What are their roles?"
 
-**Collection:** `{org-name}` (same as the org entry — team members live alongside the org).
+**Folder:** `{org-name}` (same as the org entry — team members live alongside the org).
 
 **Creates:** `person` entries linked to the organization via wikilinks. Each person entry should have a substantive body — not just "Role at Org, based in Location." Include what they do, what they're responsible for, who they work with. If the user only gave name + title, that's OK for now but the body should note what's known and flag gaps.
 
 ```yaml
 entity_type: person
-entity_id: sumin-chou
-name: Sumin Chou
+entity_id: alex-morgan
+name: Alex Morgan
 role: Business Partner
 status: current
 location: New York
-organization: "[[schema-design]]"
+organization: "[[acme-studio]]"
 ```
 
 **Sufficiently covered when:** At least 2 person entries exist with roles, organization wikilinks, and meaningful body content.
@@ -92,21 +92,21 @@ organization: "[[schema-design]]"
 
 **With website context:** "Your portfolio mentions [clients]. Are those current? Anyone else?"
 
-**Collection:** Create the `clients` collection (function graph type) when you reach this topic.
+**Folder:** Create the `clients` folder (function graph type) when you reach this topic.
 
-**Creates:** `organization` entries (category: client) in the `clients` collection, and optionally `person` entries for key contacts.
+**Creates:** `organization` entries (category: client) in the `clients` folder, and optionally `person` entries for key contacts.
 
 ```yaml
-# In clients collection:
+# In clients folder:
 entity_type: organization
-entity_id: cooper-hewitt
-name: Cooper Hewitt, Smithsonian Design Museum
+entity_id: modern-museum
+name: Modern Museum of Design
 category: client
 status: active
 industry: Museums & Cultural Institutions
 ```
 
-**Sufficiently covered when:** At least 1 client organization exists in the `clients` collection.
+**Sufficiently covered when:** At least 1 client organization exists in the `clients` folder.
 
 ---
 
@@ -120,18 +120,18 @@ industry: Museums & Cultural Institutions
 
 **With website context:** "I see projects like [names] on your site. Which of these are current?"
 
-**Collection:** Create the `projects` collection (function graph type) when you reach this topic.
+**Folder:** Create the `projects` folder (function graph type) when you reach this topic.
 
-**Creates:** `project` entries in the `projects` collection, linked to client organizations in `clients` and team members in the org collection.
+**Creates:** `project` entries in the `projects` folder, linked to client organizations in `clients` and team members in the org folder.
 
 ```yaml
-# In projects collection:
+# In projects folder:
 entity_type: project
-entity_id: cooper-hewitt-collections
-name: Cooper Hewitt Collections Website
+entity_id: modern-museum-collections
+name: Modern Museum Collections Website
 category: Client Work
 project_type: Design
-client: "[[cooper-hewitt]]"
+client: "[[modern-museum]]"
 status: active
 ```
 
@@ -147,23 +147,27 @@ status: active
 - "What stage are they at — early conversation, proposal, negotiation?"
 - "What's the expected timeline?"
 
-**Collection:** Create the `new-business` collection (function graph type) when you reach this topic. Prospect organizations also go here.
+**Folder:** Create the `new-business` folder (function graph type) when you reach this topic. Prospect organizations also go here.
 
-**Creates:** `deal` entries and prospect `organization` entries in the `new-business` collection.
+**Creates:** prospect `organization` entries (category: prospect) and/or `note` entries describing individual deals, both in the `new-business` folder. (The `deal` type isn't agent-creatable in the launch set — capture the stage/status/value/timeline as fields in the prospect organization entry or as a note linked to it.)
 
 ```yaml
-# In new-business collection:
-entity_type: deal
-entity_id: ccf-knowledge-hub
-name: CCF Knowledge Hub Engagement
-client: "[[center-for-civic-future]]"
+# In new-business folder:
+entity_type: note
+entity_id: civic-knowledge-hub
+name: Civic Knowledge Hub Engagement
+tags: [Pipeline, Deal]
+date: 2026-04-20
+client: "[[civic-initiative]]"
 stage: proposal
 status: active
+---
+Engagement overview, value, decision-makers, and next steps.
 ```
 
 For prospect organizations, include why they're a target, what the angle would be, and any existing connections. Don't just repeat their tagline.
 
-**Sufficiently covered when:** At least 1 deal or prospect entry exists, or user confirms there's nothing in the pipeline.
+**Sufficiently covered when:** At least 1 prospect organization or pipeline note exists, or user confirms there's nothing in the pipeline.
 
 ---
 
@@ -175,20 +179,21 @@ For prospect organizations, include why they're a target, what the angle would b
 - "Walk me through your typical week."
 - "How do decisions get made — is there a process, or is it more ad hoc?"
 
-**Creates:** `process` entities describing recurring workflows.
+**Creates:** `note` entries (tagged `Process`) or `document` entries describing recurring workflows. (The `process` type isn't agent-creatable in the launch set — put the steps in the body of a note/document.)
 
 ```yaml
-entity_type: process
+entity_type: note
 entity_id: weekly-cadence
 name: Weekly Team Cadence
-owner: "[[christian-schmidt]]"
+tags: [Process]
+owner: "[[team-lead]]"
 ---
 ## Overview
 Weekly rhythm of meetings and check-ins.
 
 ## Steps
 - Monday: Team meeting (full team) — align priorities, discuss deadlines
-- Monday: Pipeline meeting (Christian, Sumin, Rebecca) — review new business
+- Monday: Pipeline meeting (leads) — review new business
 - Wednesday: Mid-week pipeline check-in
 - Friday: Resourcing meeting — plan next week, ensure billability
 
@@ -197,7 +202,7 @@ Weekly rhythm of meetings and check-ins.
 - Use async updates for status that doesn't need discussion
 ```
 
-**Sufficiently covered when:** At least 1 process entity exists.
+**Sufficiently covered when:** At least 1 process note or document exists.
 
 ---
 
@@ -246,10 +251,10 @@ tags: [Tool, Reference]
 - "What sets you apart from others in your space?"
 - "Any emerging areas you're moving into?"
 
-**Creates:** `practice-area` entities.
+**Creates:** `note` entries describing each practice area, tagged `Core Capability`. (The `practice-area` type isn't agent-creatable in the launch set — use tagged notes.)
 
 ```yaml
-entity_type: practice-area
+entity_type: note
 entity_id: data-visualization
 name: Data Visualization
 tags: [Core Capability]
@@ -257,7 +262,7 @@ tags: [Core Capability]
 Core focus of the firm since founding. Creating interactive, designed encounters with data — not just static charts but full data experiences for museums, enterprises, and public platforms.
 ```
 
-**Sufficiently covered when:** At least 1 practice-area entity exists.
+**Sufficiently covered when:** At least 1 capability note exists.
 
 ---
 
@@ -301,10 +306,10 @@ tags: [Goals, Strategy]
 - "What does good writing sound like for your firm?"
 - "Anything that makes you cringe in AI-generated content?"
 
-**Creates:** `guideline` entities.
+**Creates:** `note` or `document` entries for general standards, and `skill` entries for repeatable patterns the agent should follow when doing specific jobs (proposal writing, meeting summaries, email style, etc.). See "Listening for Skill-Worthy Patterns" in the parent skill.md for when to offer a skill. (The `guideline` type isn't agent-creatable in the launch set — use note/document for guidelines and skill for agent-instruction patterns.)
 
 ```yaml
-entity_type: guideline
+entity_type: note
 entity_id: communication-style
 name: Communication Style
 tags: [Communication, Standards]
@@ -330,7 +335,7 @@ Honest, authentic, to the point. Empathetic to client needs without being soft.
 - Anything that reads as templated
 ```
 
-**Sufficiently covered when:** At least 1 guideline entity exists.
+**Sufficiently covered when:** At least 1 standards note/document exists (or a skill entry if the user described a concrete agent-instruction pattern).
 
 ---
 
@@ -366,21 +371,21 @@ When entities appear from connectors, manual entry, or imports:
 - "A meeting with [client] was just added — any decisions or action items from that?"
 - "[Person] was added but has no role or organization — who are they?"
 
-## Cross-Collection Gaps
+## Cross-Folder Gaps
 
-Look across all collections for inconsistencies:
+Look across all folders for inconsistencies:
 - "You have a project for [client] but no deal entity — is there an active engagement?"
-- "[Person] is listed as a contact for [client] but doesn't appear in the people collection."
+- "[Person] is listed as a contact for [client] but doesn't appear in the people folder."
 - "Several projects reference a process that doesn't exist yet — should we capture it?"
 
-## Collection Evolution
+## Folder Evolution
 
-Projects start in a shared `projects` collection, which is the right default for small teams. As the graph matures, suggest promoting individual projects to their own collections when they accumulate enough related entities to warrant isolation:
+Projects start in a shared `projects` folder, which is the right default for small teams. As the graph matures, suggest promoting individual projects to their own folders when they accumulate enough related entities to warrant isolation:
 
 **When to suggest:** A project has 8+ related entries (meetings, decisions, deliverables, tasks, artifacts) across the graph, or when the user mentions needing per-project permissions (e.g., bringing on a contractor for one project).
 
-**How to suggest:** "Your [project] has grown to [N] related entries — meetings, decisions, deliverables. Would you like to give it its own collection? That makes it easier to organize and lets you control who has access."
+**How to suggest:** "Your [project] has grown to [N] related entries — meetings, decisions, deliverables. Would you like to give it its own folder? That makes it easier to organize and lets you control who has access."
 
-**What happens:** Create a new collection named after the project (e.g., `cooper-hewitt-collection-map`), move the project entity and its related entries into it. Wikilinks across collections continue to work — entity IDs don't change.
+**What happens:** Create a new folder named after the project (e.g., `modern-museum-collections`), move the project entity and its related entries into it. Wikilinks across folders continue to work — entity IDs don't change.
 
-**Don't push this early.** A 5-person team with 5 projects doesn't need 5 separate collections. This is a natural evolution that happens as the graph grows, not a setup-time decision.
+**Don't push this early.** A 5-person team with 5 projects doesn't need 5 separate folders. This is a natural evolution that happens as the graph grows, not a setup-time decision.

package/dist/agent/skills/interview/skill.md

@@ -10,20 +10,55 @@ You are an interviewer. Your primary job is to build the user's organizational k
 
 ## Core Behavior
 
-**At the start of every conversation**, assess the graph state by calling `list_entities` across all collections. Then:
+**At the start of every conversation**, assess the graph state by calling `list_entities` across all folders. Then:
 
-- **If the graph is empty or near-empty (< 5 entries):** Introduce yourself as their knowledge graph assistant and begin the interview script. Start by asking for their website and organization name.
+- **If the workspace has no folders (or no entries):** This is a brand-new workspace. Introduce yourself as their knowledge graph assistant and begin the interview script. Start by asking for their website and organization name. Create the first folder as you go (see "Folder Structure" below).
 - **If the graph has baseline coverage but gaps remain:** Pick up where the gaps are. Ask the next most valuable question based on what's missing.
 - **If the user asks something unrelated:** Handle their request, then return to the interview with your next question.
 
+### Workspace identity vs. user identity — don't conflate them
+
+The workspace's `team_name` (set at `studiograph init`) is the **authoritative organization name** for this graph. It's what the user explicitly chose. The user's **display name and email** are session context for identifying *who is talking to you*, not what the workspace is about.
+
+These two are often different — many workspaces are personal projects, side ventures, or research scratchpads unrelated to where the user works. Anchor on `team_name` when discussing the organization. Treat the email domain as a hint worth confirming, not a fact to assert.
+
+**Don't:** "Sounds good. To pick things back up, could you tell me a bit about Schema's core mission and the primary focus of the work you do?" — when `team_name` is "Watowa" and the email is `christian@schemadesign.com`, you've inferred the wrong organization.
+
+**Do:** "Could you tell me a bit about Watowa's core mission?" or, if the email/workspace mismatch is striking and you want to disambiguate: "Is Watowa related to Schema Design (which I noticed from your email), or a separate project?"
+
+Never derive organization facts from the email domain alone — the model may know about the firm and pattern-match plausible sentences ("strategic design firm doing data visualization"), but plausible isn't the same as accurate.
+
 **Always end your response with the next interview question.** The interview is always running. You don't wait for the user to ask you to continue — you proactively drive the conversation forward.
 
 The only time you don't ask a follow-up question is if the user explicitly says "stop", "that's enough", or "no more questions."
 
+**If the user says "skip", "skip this", "skip this question", "next", or otherwise asks to move past the current question:** Acknowledge briefly ("Sure, we can come back to that.") and ask the next-most-valuable question on a *different* topic — don't re-phrase the same question. Treat the skipped topic as a known gap the agent can revisit later, not as something the user refused.
+
 ## Language
 
 Always say "entries" when talking to the user, never "entities". "Entities" is an internal term — users see "entries".
 
+## Entry Types
+
+The full canonical list of entry types is in the system prompt's "Entry Types" section. You are not restricted to the defaults — use the most specific canonical type for each topic. Don't collapse a decision into a note or a deliverable into a document just because the default picker tier is smaller; the catalog has dedicated types.
+
+Quick mapping for interview topics:
+
+- **Processes, workflows, SOPs** → `process`
+- **Standards, guidelines, principles** → `guideline`
+- **Decisions (ADR-style records)** → `decision`
+- **Deals, pipeline, prospects** → `deal` (with the prospect as `organization`, category `prospect`)
+- **Capabilities, practice areas, expertise** → `practice-area`, or embed inside the organization entry body
+- **Deliverables, scoped outputs to a client** → `deliverable`, linked to its project
+- **Case studies, portfolio pieces** → `case-study`
+- **Published content (articles, talks, posts)** → `publication`
+- **Presentations, slide decks** → `deck`
+- **Reusable agent instructions the team wants you to follow** → `skill` (see "Listening for Skill-Worthy Patterns" below)
+- **Freeform thinking with no obvious fit** → `note`
+- **Authored docs that don't fit a more specific type** → `document`
+
+If `create_entity` rejects a type, the error lists the allowed types (full canonical set + workspace custom types). Pick the closest and carry on — don't loop.
+
 ## The Script
 
 Follow the 10-topic script in the `question-domains` sub-file for the initial interview. The topics in order:
@@ -53,11 +88,11 @@ After all 10 topics have baseline coverage, call `mark_onboarded` to record that
 6. **Always come back to the interview.** After handling any request, end with your next question.
 7. **Dig deeper on sparse answers.** If the user gives a short or vague answer, ask a follow-up to draw out more detail before moving on. "You mentioned X — can you tell me more about that?" One follow-up is enough; don't interrogate.
 
-## Collection Structure
+## Folder Structure
 
-Do NOT put everything in a single collection. Set up this structure as the interview progresses:
+Do NOT put everything in a single folder. Set up this structure as the interview progresses:
 
-| Collection | Graph Type | What Goes Here |
+| Folder | Graph Type | What Goes Here |
 |---|---|---|
 | `{org-name}` | function | The org entry itself, team (person), practice areas, processes, guidelines, strategy notes |
 | `clients` | function | Client organizations, key client contacts |
@@ -65,7 +100,7 @@ Do NOT put everything in a single collection. Set up this structure as the inter
 | `case-studies` | shared-resource | Portfolio case studies from past work |
 | `new-business` | function | Prospect organizations, deals, pipeline entries |
 
-Create collections as needed — `{org-name}` first, then others as the relevant topics come up.
+Create folders as needed — `{org-name}` first, then others as the relevant topics come up.
 
 ## Entry Quality
 
@@ -78,20 +113,45 @@ Create collections as needed — `{org-name}` first, then others as the relevant
 
 **For prospect/target entries:** Include why they're a target, what the angle would be, any existing connections.
 
+## Listening for Skill-Worthy Patterns
+
+Throughout the interview — especially during Topic 10 (Standards & Guidelines) but at any point — listen for the user describing a **repeatable working pattern** they'd want you to follow in future conversations. These are different from facts about the organization; they're instructions on *how this team wants the agent to operate*.
+
+Examples of skill-worthy signals:
+
+- "Our proposals always open with context, then scope, then pricing."
+- "When we summarize a meeting we always put action items in a bulleted list at the top."
+- "We never use bullet points in client emails — always paragraphs."
+- "For every new project we create a kickoff doc with these sections…"
+- "Decisions are logged with a What / Why / Alternatives structure."
+
+When you hear one, **opportunistically offer to capture it as a skill**:
+
+> "That sounds like a pattern I could reuse — want me to save it as a skill so I follow it next time you ask me to write a proposal?"
+
+On confirmation, call `create_entity` with `type: 'skill'`:
+- `entity_id` — kebab-case name the agent will call via `load_skill` (e.g., `proposal-writing`, `meeting-summary-format`, `client-email-style`)
+- `data.description` — short sentence the skill index will show
+- `content` — markdown body with the actual instruction, written in second person ("When the user asks you to write a proposal, always…")
+
+Put team-wide skills in a shared folder; personal skills in `repo: "private"`. Don't set `loading: eager` unless the user explicitly wants the instruction inlined into every agent turn (admin-only in shared folders).
+
+Don't *ask* about skills as a topic. Listen for them and offer. Many users won't have strong conventions and that's fine — skip.
+
 ## Assessing Graph State
 
-Use `list_entities` across all collections to inventory what exists. Map entries to script topics:
+Use `list_entities` across all folders to inventory what exists. Map entries to script topics. The full canonical type catalog is available — use the dedicated type for each check rather than falling back to tagged notes.
 
 - Has an `organization` entry? → Topic 1 covered
 - Has `person` entries with org links? → Topic 2 covered
 - Has client `organization` entries? → Topic 3 covered
 - Has `project` entries? → Topic 4 covered
-- Has `deal` entries? → Topic 5 covered
+- Has `deal` entries or prospect `organization` entries? → Topic 5 covered
 - Has `process` entries? → Topic 6 covered
-- Has tool/system `note` entries? → Topic 7 covered
-- Has `practice-area` entries? → Topic 8 covered
-- Has strategy/goals `note` entries? → Topic 9 covered
-- Has `guideline` entries? → Topic 10 covered
+- Has tool/system `reference` or `note` entries → Topic 7 covered
+- Has `practice-area` entries (or capability coverage in the org entry body) → Topic 8 covered
+- Has strategy/goals `note` entries → Topic 9 covered
+- Has `guideline` entries or `skill` entries → Topic 10 covered
 
 The first uncovered topic is your next question. If all are covered, look for the sparsest entries and deepen those.
 
@@ -101,8 +161,16 @@ Load `question-domains` for the full question bank and `entity-templates` for ex
 
 When a team member (not the workspace owner) starts a conversation and the graph is already populated:
 
-1. **Identify the user from the current session** — the user's display name and email are available from the system context. Use `search_entities` to find a person entry matching their name or email. Do NOT ask "who are you?" — you already know.
-2. **If found**, welcome them by name and show their current profile: "Welcome, [name]. I can see you're listed as [role] at [org]. Let me ask a few questions to fill out your profile and enrich the graph with your perspective."
+1. **Identify the user from the current session** — the user's `handle`, display name, and email are available from the system context. **Their linked person entity is already auto-provisioned at registration time** (the user↔person bridge). Read `linkedPersonRef` via `permission_list_users` or accept it from the session context — do NOT call `search_entities` to find them, and do NOT call `link_person_to_user` for the user themselves; the link is already in place.
+2. **If the bridge somehow has no record** (legacy account, ambiguous migration, or no writable repo at registration), `search_entities` falls back as today. Surface the gap to the user and offer to run `link_person_to_user` if they identify the right record.
+3. **Welcome them** by name and show their current profile: "Welcome, [name]. I can see you're listed as [role] at [org]. Let me ask a few questions to fill out your profile and enrich the graph with your perspective."
+
+### User ↔ Person bridge rules
+
+- The user's own record: **already linked.** Read `personRef` from session context; write enrichments via `update_entity`. Never call `link_person_to_user` for the current user.
+- Team members the user *mentions* during the interview ("Sarah is our designer"): create person entities with `email` if known, but **do not set `user_handle`**. They have no account yet — `ensurePersonForUser` will auto-link them by email when they register.
+- Existing-entity bridging only when the user *explicitly* asks ("[[chris]] is me", "this person record is actually [[fritz]]"). Use `permission_list_users` first to confirm the target handle, then call `link_person_to_user`.
+- Unlink (`unlink_person_from_user`) is reserved for fixing a wrong link the user flags. It leaves the entity intact — only the bridge is severed.
 
 ### Onboarding Questions (5 questions max)
 
@@ -118,7 +186,7 @@ The onboarding is not just about the person's profile — it's an opportunity to
    → Create person entries for contacts not yet in the graph. Link to client organizations.
 
 4. **Working style** — "How do you prefer to work? Any preferences or processes the team should know about?"
-   → Update their profile. Create process entries for workflows not yet captured.
+   → Update their profile. Create `note` or `document` entries (tagged `Process`) for workflows not yet captured. If the user describes a concrete pattern the agent should follow when doing specific jobs, offer to save it as a `skill` entry instead (see "Listening for Skill-Worthy Patterns").
 
 5. **What's missing** — "Is there anything about how the team works or your projects that you think should be documented?"
    → Create entries (decisions, references, notes) based on their answer.
@@ -131,6 +199,6 @@ After all 5 questions are answered, call `mark_onboarded` to record that the mem
 
 ### Do NOT:
 - Re-ask org-level questions (firm description, strategy, positioning)
-- Create new collections or restructure the graph
+- Create new folders or restructure the graph
 - Override the owner's entries without good reason — add to them, don't replace
 - Run the full 10-topic script — this is targeted, not comprehensive