studiograph 1.3.48-next.26 → 1.3.48-next.261

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

@@ -12,45 +12,52 @@ You are an interviewer. Your primary job is to build the user's organizational k
 
 **At the start of every conversation**, assess the graph state by calling `list_entities` across all folders. Then:
 
-- **If the only folder is `meridian-rebrand` (or the graph contains *only* the starter scaffold below):** Treat the workspace as empty. The scaffold is template data, not real user content. Introduce yourself, explain that the workspace currently has example data you'll help replace, and begin the interview by asking for their website and organization name. Offer to delete the `meridian-rebrand` folder once they've added real entries.
-- **If the graph is otherwise 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.
 
-### Recognizing the starter scaffold
+### Workspace identity vs. user identity — don't conflate them
 
-A freshly-initialized workspace ships with one folder named `meridian-rebrand` containing exactly these 8 example entries:
+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.
 
-- `meridian-health` (organization, client)
-- `sarah-chen`, `alex-rivera` (people)
-- `meridian-rebrand` (project)
-- `2026-02-10-kickoff` (meeting)
-- `dec-2026-001` (decision)
-- `discovery-workshop` (process)
-- `brand-deliverables-checklist` (guideline)
+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.
 
-If you see this exact set, do **not** treat it as the user's real graph. It's a template demonstrating how entries connect. Acknowledge it briefly when relevant ("your workspace has a sample folder showing how things connect — we'll build your real one alongside it") and focus the interview on the user's actual organization. Never ask them to elaborate on Meridian Health, Sarah Chen, or the rebrand project — those aren't theirs.
+**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 Type Mapping
+## Entry Types
 
-The canonical list of entry types you can create is in the system prompt's "Entry Types" section. When the interview script mentions topics that hint at other types, map them to the allowed set:
+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.
 
-- **Processes, workflows, SOPs** → create as `note` (with `type: research`) or `document` (with `type: process`). Put the steps in the body.
-- **Standards, guidelines, principles** → create as `note` or `document`. Put the guidelines in the body.
-- **Deals, pipeline, prospects** → create the organization as `organization` (category: prospect). Log any pipeline notes in a `note` linked to that organization.
-- **Capabilities, practice areas, expertise** → capture as `note` entries in a shared folder, or mention inside the organization entry body.
-- **Deliverables, artifacts** → capture as `document` entries linked to the relevant project.
-- **Case studies, portfolio pieces** → capture as `document` entries (with `type: case-study`) linked to their originating project.
+Quick mapping for interview topics:
 
-If `create_entity` rejects a type, the error message lists the allowed types. Pick the closest allowed type and carry on — don't loop.
+- **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
 
@@ -133,18 +140,18 @@ Don't *ask* about skills as a topic. Listen for them and offer. Many users won't
 
 ## Assessing Graph State
 
-Use `list_entities` across all folders to inventory what exists. Map entries to script topics. The checks below use only launch-visible entry types — the agent can't create types like `deal`, `process`, `practice-area`, or `guideline` in the current set, so their intent is captured as tagged notes/documents (see the Entry Type Mapping section above).
+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 prospect `organization` or pipeline `note` entries? → Topic 5 covered
-- Has `note`/`document` entries tagged `Process` → Topic 6 covered
-- Has tool/system `note` entries → Topic 7 covered
-- Has `note` entries tagged `Core Capability` → Topic 8 covered
+- Has `deal` entries or prospect `organization` entries? → Topic 5 covered
+- Has `process` entries? → Topic 6 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 standards `note`/`document` entries or `skill` entries → Topic 10 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.
 
@@ -154,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)
 

package/dist/agent/skills/paged-documents/skill.md

@@ -0,0 +1,147 @@
+---
+name: paged-documents
+description: How to author multi-page print documents (letters, contracts, proposals, reports, briefs) WELL with CSS Paged Media — the platform paginates a `pages` frame with Paged.js. Deep technical know-how for @page rules, named/cover pages, page-margin boxes, running letterhead/headers/footers, page counters, and break control, plus the mandatory render-and-inspect verify loop. Load this whenever you build or edit a paginated document (a `pages` frame); it is the layer beneath any house-style skill.
+loading: on-demand
+---
+
+# Paged documents — using CSS Paged Media (Paged.js) well
+
+Load this when you build or edit a **flowing** document: a single `pages` frame whose continuous text the platform fragments across pages with Paged.js (letters, contracts, proposals, agreements, reports, briefs, memos of variable / unknown length). The `artifact-canvas` skill covers the frame model; this skill is the deep, effective-use reference for the pagination layer. A workspace **house-style** skill (if one exists) sits ON TOP of this — that one carries the org's specific letterhead, type scale, and conventions; this one is the universal craft of making Paged Media render correctly.
+
+**First check you actually need pagination.** `pages` + Paged.js is for AUTO-FLOWING a continuous stream across pages. If the document is a **single fixed page** (flyer, poster, invoice, certificate, one-pager) or a **multi-page document you compose page by page** (brochure, multi-page form, designed report), build it as `artboard` frame(s) instead — one frame per page — which skips Paged.js entirely (it's heavier and slower to load). See the router in `artifact-canvas`. Use this skill only when you want the platform to break a text stream into pages for you.
+
+The single most important habit: **a document is print-bound — you cannot eyeball it like a deck. You MUST render and inspect it, then fix what the render shows, before you say it's done.** See "The verify loop" at the end. Most document defects (a clipped running header, a heading stranded at a page bottom, an orphaned rule) are invisible in the source and obvious in the render.
+
+## Mental model
+
+You author **one ordinary HTML document body** plus **CSS Paged Media rules**. Paged.js fragments that one flowing body into as many fixed-size pages as the content needs, and repeats your letterhead/headers/footers on every page. You do NOT build pages by hand — no per-page frames, no page-height spacer divs, no manual page grid. Write the body once; write `@page` rules for the furniture; let the platform paginate.
+
+```
+ONE <pages> frame  ──Paged.js──▶  page 1 │ page 2 │ page 3 │ …  (real multi-page PDF)
+   whole body                     each carries your @page margins + running header/footer + page number
+```
+
+## The platform contract (what we give you, what is fixed)
+
+Your CSS reaches Paged.js from **shared `.css` files AND inline `<style>` in the frame `content`** — both are honored for `@page` / break / named-page / running-element rules. Relative `url()` (fonts, images) is fine; the platform handles it. Then:
+
+- **Page SIZE is the frame `geometry` — ANY width × height, and the platform LOCKS it.** The page can be any size in px @96dpi, **portrait, landscape, or arbitrary** — there is no canonical "default." Common print presets (portrait; swap width↔height for landscape): US-Letter `816×1056`, Legal `816×1344`, Tabloid `1056×1632`, A4 `794×1123`, A3 `1123×1587`, A5 `559×794`. But a custom size is equally valid — a landscape report `1056×816`, a square `1000×1000`, a wide spread `1632×816`, a tall menu `612×1584`. Pick the geometry the document calls for. **Do NOT write `@page { size: … }`** (or `size: letter`) — the platform appends the authoritative `@page { size }` (your chosen geometry) LAST, so yours is ignored. Sizing the page is the geometry's job; everything else below is relative to it.
+- **The platform gives you sensible defaults that your CSS overrides:** a default `@page { margin }` (from the frame's `pageMargins`, else top 96 / sides 72 / bottom 84) and a default **"Page N of M"** counter in `@bottom-right`. Write your own `@page { margin }` or your own margin-box content and yours wins.
+- **Cascade order:** platform defaults → **your CSS** → page-size lock. So your `@page`/margin/break/running rules win over the defaults; only the page size is beyond your reach.
+- **Fixed height is required to paginate.** A `pages` frame with a fixed height (e.g. `1056`) flows overflow onto more pages. A `pages` frame with `height: "auto"` does NOT paginate — it renders as one tall continuous page. Use `auto` only for a deliberately single, non-paginated scroll.
+
+## `@page` rules and named pages
+
+The base page:
+
+```css
+@page {
+  margin: 96px 72px 84px;     /* top  sides  bottom — illustrative, NOT canonical */
+}
+```
+
+**Margins are a design choice relative to the page, not fixed numbers.** Scale them to the geometry and the document: a big page (Tabloid/A3) wants larger margins than an A5; a landscape page often wants more side margin than top/bottom; a bound document wants an asymmetric inner/outer margin (`@page :left` / `:right`). The top/bottom margins must also leave room for your running header/footer (a tall letterhead needs a taller top margin). The platform's fallback when you set none is top 96 / sides 72 / bottom 84 px — fine for a Letter-ish portrait, but choose your own for any other size. Everywhere below, **the content width is `page-width − left-margin − right-margin`** and any element you size to the column should be derived from the geometry you picked, never a copied constant.
+
+**Named pages** give a specific page its own rules — the classic use is a **cover page with no running header/footer**, then a forced break into the body:
+
+```css
+@page cover { margin: 0; }                         /* full-bleed cover */
+@page cover { @top-left { content: none } @top-right { content: none } @bottom-right { content: none } }
+.cover { page: cover; break-after: page; }         /* this element is the cover; body starts on the next page */
+```
+
+`@page :first`, `@page :left`, `@page :right`, and `@page :blank` also work (e.g. mirrored margins for a bound document, or suppressing furniture on the first page).
+
+## Page-margin boxes — left/right header text, and the width trap
+
+A running header/footer of **short text** lives directly in margin-box slots. The top edge has these (the bottom mirrors them); each slot positions itself, so left + right text needs no layout work:
+
+```
+@top-left-corner │ @top-left │ @top-center │ @top-right │ @top-right-corner
+```
+
+**The reliable two-part header — separate slots, no width:**
+
+```css
+@page {
+  @top-left     { content: "Acme Inc." }       /* sits at the left of the top margin */
+  @top-right    { content: "Project Brief" }    /* sits at the right                  */
+  @bottom-right { content: counter(page) }
+}
+```
+
+**The width trap (this is the #1 document bug).** The top row's width is the page width minus the corners, **shared** among `@top-left` / `@top-center` / `@top-right`, and each box sizes to its own content. **Never put `width: 100%` (or a wide fixed width) on one margin box** — it steals the whole row and crushes the others, so their text wraps into a sliver and **clips** (a header that should read "Cooper Hewitt Brand Refresh" renders as "Hewitt / Brand / Refresh", cut off — the exact bug). Margin boxes also do NOT grow or wrap gracefully; they clip. So: keep each slot's `content` **short** (a few words), and to get a full-width underline under the header, do NOT reach for `width: 100%` — use a running element for the rule (below).
+
+## Running elements — for ONE repeated block (band, logo, rule), not for spreading parts
+
+`position: running(name)` pulls an element out of the body flow and `content: element(name)` drops it into a margin box, repeated on every page. Use it for a **single content block**: a full-bleed colored band, a logo lockup, a centered title, or a full-width rule. It is real HTML/CSS — backgrounds, borders, a fixed height.
+
+**Verified Paged.js limitation — do not lay out multiple parts with flex inside a running element.** When the element is cloned into the margin box, its **`display:flex` / `justify-content:space-between` does NOT spread** — the children collapse to their intrinsic size, centered (`<span>Acme</span><span>Brief</span>` renders as "AcmeBrief" in the middle, not left+right). So:
+
+- **Left vs right text with NO shared background → use the two margin boxes above** (`@top-left` + `@top-right`), never a flex running element.
+- **A band WITH a shared background that needs left + right content (logo left, address right) → one running element, lay the parts out with `position:absolute`.** Flex and `display:table` both collapse in the clone; **absolute** children anchor to the band's box and DO render correctly. Use **fixed px offsets**, not percentages — the band's height is not definite in the clone, so `top:50%` escapes to the page; `top:34px` stays in the band. (Verified by render.)
+
+```css
+.band  { position: running(band); height: 104px; background: #16315c; color: #fff; }
+.brand { position: absolute; left: 64px;  top: 34px; }   /* logo + name lockup (inline-block inside is fine) */
+.addr  { position: absolute; right: 64px; top: 38px; text-align: right; }
+@page  {
+  margin: 110px 0 84px;                                  /* side margins 0 → the band spans full width */
+  @top-center  { content: element(band) }
+  @bottom-left { content: "Confidential"; padding-left: 64px }   /* inset the footer text to the column */
+  @bottom-right{ content: counter(page);  padding-right: 64px }  /* (margins are 0, so pad each box) */
+}
+.doc   { padding: 0 64px; }                                              /* body supplies its own gutters */
+```
+
+**The full-bleed-band footer trap.** Side margins `0` let the band bleed — but they also drop any `@bottom-left`/`@bottom-right`/`@top-*` TEXT onto the very paper edge (a page number jammed against the corner). Margin boxes accept `padding`, so **inset every text slot to your body column** with `padding-left`/`padding-right` matching the body gutter (`64px` above). Only the band is meant to bleed; the page number, confidential line, and any header text align to the column. (Verified by render — without the padding the footer sits at x≈0.)
+
+For a **first-page-only / last-page-only** variant, attach the element on a named page (`@page :first { @top-center { content: element(coverhead) } }`). Put the running element **once**, near the top of `content`; it does not appear inline.
+
+Whatever you build here, **confirm it in the render** (verify loop below) — margin-box and running-element layout has non-obvious behavior (the flex caveat above is exactly why), so looking at the pixels is the only way to know it landed.
+
+## Page counters
+
+`counter(page)` is the current page, `counter(pages)` the total. The platform defaults to "Page N of M" bottom-right; override it with your own:
+
+```css
+@page { @bottom-right { content: counter(page); font: 7.5pt 'Brand'; color: #666 } }
+```
+
+`target-counter(attr(href url), page)` resolves the page of a target — use it for a table of contents or cross-references ("see p. 4").
+
+## Break control (the craft that separates clean from sloppy)
+
+- `break-before: page` / `break-after: page` — start a section/exhibit on a fresh page.
+- `break-inside: avoid` — keep a block together (a figure + caption, a table row, a signature block, a heading + its first lines).
+- `break-after: avoid` on headings — so a heading is never stranded alone at the bottom of a page with its content on the next.
+- `orphans` / `widows` (e.g. `p { orphans: 2; widows: 2 }`) — no single dangling line of a paragraph across a page break.
+- **Do NOT emit a divider (`<hr>`, a `border-top` separator) immediately before a forced `break-before` section.** The page break already IS the separator; the divider lands orphaned at the bottom of the prior page. Put separators BETWEEN in-flow sections only, not where a page break does the dividing.
+
+## Vertical rhythm and spacing
+
+Give headings real breathing room and keep spacing consistent (a single scale: e.g. space below a section heading ≥ the space between paragraphs, so headers don't read as glued to their body). A label-column layout (section label left, body right) needs the label and the body's first line to share a baseline. The EXACT scale (sizes, leading, margins) is **house style** — defer to the workspace house-style skill if one exists; absent that, pick one scale and apply it everywhere rather than ad-hoc values per section.
+
+## The verify loop (mandatory — not optional for documents)
+
+After `create_artifact` / `patch_artifact`, **`inspect_artifact` the document and READ the rendered pages**, then fix and re-inspect until clean. A `pages` frame paginates rather than cropping, so it never appears in `framesOverflowing` — that is exactly why you must look at the pixels. Check, on the render:
+
+- **Running header/footer fully visible** on every page — not clipped or wrapped (clipping ⇒ a margin box is too narrow, usually a `width` hack; switch to a running element or shorten the text).
+- **No stranded headings** at page bottoms and **no orphaned rules/dividers** at page edges.
+- **Tables and blocks break sanely** (no row split mid-cell, no header row alone at a page bottom).
+- **Cover/first page** furniture is suppressed if intended; page numbers run 1…N.
+- **Margins and the letterhead** look right on page 2+ (page 1 often differs).
+
+Do not describe the structure and stop. Render it, look at it, fix what you see. The most common real defects (clipped headers, orphaned dividers, stranded headings) are invisible in the markup and obvious in the render — one inspect pass catches them.
+
+## Quick checklist
+
+- [ ] ONE `pages` frame, fixed width AND height — the size the document needs (portrait, landscape, or arbitrary; via geometry, no `@page { size }`).
+- [ ] Margins scaled to that page size (not copied Letter numbers); top/bottom leave room for the letterhead.
+- [ ] Letterhead / multi-part header / full-width rule → a **running element**, not margin-box `width` hacks.
+- [ ] Margin-box text is short and fits.
+- [ ] Full-bleed band (side margins `0`)? Footer/header text slots `padding`-inset to the body column, not on the page edge.
+- [ ] Cover/first page handled with a named page if it differs.
+- [ ] `break-inside: avoid` on blocks that must stay together; `break-after: avoid` on headings; no divider right before a `break-before`.
+- [ ] Consistent spacing scale (defer the exact scale to the house-style skill).
+- [ ] **Rendered and inspected; the pages actually look right.**

package/dist/agent/skills/schema-rules.md

@@ -1,6 +1,6 @@
 ---
 name: schema-rules
-description: Critical rules for creating and updating entities — valid enums, field types, common pitfalls
+description: Critical rules for creating and updating entities — enum discovery, field types, common pitfalls
 loading: eager
 ---
 
@@ -14,41 +14,41 @@ These rules apply whenever you create or update entries. For the full field refe
 
 **Never wrap the `content` parameter in quotes.** The `content` field is raw markdown, not a JSON string. Do not add leading or trailing `"` characters. Pass the markdown directly.
 
-## Field Types
+## Enum Fields — Always Check the Schema
 
-- **website** / **url** fields: must be a valid URL with protocol (e.g., `https://example.com`) or omitted entirely
-- **email** fields: must be a valid email address or omitted
-- **date** fields (start_date, end_date, due_date, expected_close): must be ISO format `YYYY-MM-DD` or omitted
-- **number** fields (deal_value, probability, year): must be actual numbers, not strings
+Many entity fields are enums (a closed set of allowed values). Field names that signal an enum include `stage`, `status`, `category`, `priority`, `audience`, `source`, `type`. **Do not guess enum values from memory.** Allowed values change as the product evolves, and a guessed value that "sounds right" (e.g. `negotiating` vs the actual `negotiation`) will fail validation.
 
-## Valid Enum Values
+**Before writing any enum-shaped field on create or update:**
 
-### Organization
-- **category**: `client`, `vendor`, `partner`, `prospect`, `industry-body`, `other`
-- **status**: `active`, `inactive`, `former`
+1. Call `get_entity_schema(entityType)` to fetch the authoritative schema for the entity type.
+2. Inspect the returned `fields` object. For each enum field, the descriptor includes:
+   - `type: "enum"` (or `"enum[]"` for arrays of enums)
+   - `enum: [...]` — the full list of allowed values
+   - `default: ...` — the value applied when the field is omitted (when present)
+3. Use only values from the `enum` array. If you want the default, omit the field entirely.
 
-For prospect organizations, use `category: "prospect"` with `status: "active"`.
+You may cache the schema response within a single conversation turn, but re-fetch when starting work on a different entity type or after a schema change is mentioned.
 
-### Person
-- **status**: `current`, `former`, `contractor`, `client`, `partner`
+## Field Types (from `get_entity_schema`)
 
-### Project
-- **status**: `planning`, `scoping`, `active`, `on-hold`, `completed`, `archived`
+- `string` — free text
+- `string` with format `url` — must be a valid URL with protocol (e.g., `https://example.com`)
+- `string` with format `email` — must be a valid email
+- `datetime` — ISO 8601 datetime (auto-stamped on `created_at` / `updated_at` — do not pass these)
+- `number` — actual number, not a quoted string
+- `boolean` — `true` / `false`
+- `enum` — one of the values listed under the field's `enum` array
+- `string[]` — array of strings; for wikilink arrays (`attendees`, `services`, etc.) each entry is a wikilink id like `[[acme-corp]]`
+- `enum[]` — array of enum values; each entry must be one of `itemEnum`
 
-### Deal
-- **stage**: `scoping`, `proposal`, `negotiating`, `won`, `lost`
-- **source**: `referral`, `inbound`, `outbound`, `repeat`, `partner`, `other`
+Dates use exactly two fields. `date` (type `date`) is every entity's salient date — its meaning is type-specific and shown in the field's `label` (a task's "Due date", a deal's "Close date", a project's "End date"). `start_date` (type `date`, only on project/event/task/deliverable/deal) is the optional earlier bound of a range `[start_date, date]`. Both must be `YYYY-MM-DD` (date-only — not a datetime) or omitted; anything else is rejected.
 
-### Task
-- **status**: `open`, `in-progress`, `done`, `cancelled`
-- **priority**: `low`, `medium`, `high`, `urgent`
-
-### Decision
-- **status**: `proposed`, `accepted`, `rejected`, `deprecated`, `superseded`
+## Error Recovery
 
-### Case Study
-- No status enum — uses base fields only
+When an entry creation or update fails with a validation error, read the message carefully:
 
-## Error Recovery
+- If it names an enum field (e.g. `stage: Invalid enum value`), call `get_entity_schema` for that entity type, pick a valid value from the `enum` list, and retry.
+- If it complains about a URL or email format, drop the field rather than substituting a placeholder.
+- If it complains about a missing required field, ask the user or omit the entry and explain.
 
-When an entry creation fails, read the error message, fix the offending field, and retry immediately. Do not skip the entry or tell the user it failed without retrying.
+Do not skip the entry silently — either retry with corrected data or tell the user what went wrong.

package/dist/agent/tools/artifact-tools.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Artifact tools let the agent hand a renderable bundle to the web canvas.
+ * The active transport decides whether that bundle updates the currently
+ * scoped artifact entry or creates a new persisted artifact entry.
+ */
+import { Type as T } from 'typebox';
+import { type ArtifactBundle } from '../../core/artifact-frame-model.js';
+import { type ArtifactInspectOptions, type ArtifactInspectionResult } from '../../services/artifact-render-export.js';
+export interface ArtifactCallbackResult {
+    repo: string;
+    entityType: 'artifact';
+    entityId: string;
+    action: 'created' | 'updated';
+    /** True when the write was a no-op (idempotent identical retry). The caller
+     *  shows the artifact chip regardless but skips the cross-client change
+     *  broadcast, mirroring the MCP surface. */
+    noop?: boolean;
+    /** The VALIDATED/normalized bundle the store actually persisted — so the tool
+     *  builds its return-rich manifest (P4.3) from what was written (geometry
+     *  rounded, fields normalized), matching the MCP surface. Absent only for
+     *  callbacks that don't go through ArtifactStore (e.g. test stubs); the tool
+     *  then falls back to the bundle it submitted. */
+    bundle?: ArtifactBundle;
+}
+export interface ArtifactToolTarget {
+    repo?: string;
+    entityId?: string;
+}
+/** Optional concurrency/safety controls threaded from `create_artifact` to the
+ *  write callback. `baseHash` is the hash the agent received from `read_artifact`;
+ *  the writer rejects the update if the current artifact's hash differs (someone
+ *  else changed it since the read). `replace` opts out of the destructive-shrink
+ *  guard for intentional blank/rewrite. `createNew` forces a fresh artifact
+ *  entry even when the chat is scoped to one — without it a scoped chat has no
+ *  path to a SECOND artifact (omitting target updates the scoped canvas, and a
+ *  target must already exist). */
+export interface ArtifactWriteOptions {
+    baseHash?: string;
+    replace?: boolean;
+    createNew?: boolean;
+}
+export type ArtifactCallback = (bundle: ArtifactBundle, target?: ArtifactToolTarget, options?: ArtifactWriteOptions) => void | ArtifactCallbackResult | Promise<void | ArtifactCallbackResult>;
+/** What `read_artifact` hands back: the parsed bundle plus the hash + timestamp
+ *  the agent passes to `create_artifact` as `baseHash` for stale-write detection. */
+export interface ArtifactReadResult {
+    bundle: ArtifactBundle;
+    hash: string;
+    updatedAt?: string;
+}
+export type ArtifactReadCallback = (target?: ArtifactToolTarget) => ArtifactReadResult | Promise<ArtifactReadResult>;
+/** Stable content hash of an artifact's stored body STRING (not the parsed
+ *  bundle), so `read_artifact` and the write-time guard hash the exact same
+ *  serialization — no canonicalization, no false mismatches from key reordering. */
+export declare function hashArtifactBody(body: string): string;
+/** Tool names whose results carry a truncation warning when the assistant turn
+ *  that emitted them stopped on the model's output-token cap. A whole bundle is
+ *  one streamed tool-call argument, so a capped turn cuts the JSON mid-content —
+ *  yet a partial bundle can still close validly and pass validation, so the
+ *  write "succeeds" silently. The agent must be told to verify + append. */
+export declare const ARTIFACT_WRITE_TOOL_NAMES: Set<string>;
+/** The note appended to an artifact write's tool result when its turn was
+ *  output-capped. Exported for the orchestrator's afterToolCall wiring + tests. */
+export declare function artifactOutputTruncationNote(toolName: string): string;
+type ToolResultBlock = {
+    type: string;
+    text?: string;
+};
+/** Pure adapter for the afterToolCall hook: given the just-finished assistant
+ *  turn's stopReason, the tool name, and the tool result's content blocks, return
+ *  a replacement `{ content }` carrying the truncation note — or undefined when
+ *  the turn was not an output-capped artifact write (the common case, a no-op).
+ *  The note is folded into the last existing text block so the result stays a
+ *  single well-formed block; if there is none, it is added as a new block. */
+export declare function artifactTruncationToolResult(args: {
+    stopReason?: string;
+    toolName?: string;
+    content?: unknown;
+}): {
+    content: ToolResultBlock[];
+} | undefined;
+export interface ArtifactToolOptions {
+    readArtifact?: ArtifactReadCallback | null;
+    inspectArtifact?: (bundle: ArtifactBundle, options?: ArtifactInspectOptions) => Promise<ArtifactInspectionResult>;
+    /**
+     * Resolve headless-render asset access for inspect_artifact: the server origin
+     * (where `/api/assets` is served) + a signed, short-lived token scoped to the
+     * bundle. Without it the headless render uses `assets:{mode:'none'}`, so every
+     * workspace `/api/assets/...` image is aborted and shows the broken-image
+     * placeholder — the false "original asset is no longer available" that misleads
+     * the agent into thinking assets were deleted. Returns null when unavailable
+     * (e.g. an unsaved bundle with no repo/entity), degrading to the prior no-asset
+     * behavior. Injected by the server layer (the agent layer cannot import the
+     * server-side token mint or resolve a base URL request-free).
+     */
+    resolveInspectAssets?: ((target: ArtifactToolTarget | undefined, bundle: ArtifactBundle) => {
+        baseUrl: string;
+        assetToken: string;
+    } | null) | null;
+}
+export declare function createArtifactTools(onArtifact?: ArtifactCallback | null, options?: ArtifactToolOptions): ({
+    name: string;
+    label: string;
+    description: string;
+    parameters: T.TObject<{
+        bundle: T.TObject<{}>;
+        target: T.TOptional<T.TObject<{
+            repo: T.TOptional<T.TString>;
+            entityId: T.TOptional<T.TString>;
+        }>>;
+        baseHash: T.TOptional<T.TString>;
+        replace: T.TOptional<T.TBoolean>;
+        createNew: T.TOptional<T.TBoolean>;
+    }>;
+    execute: (_toolCallId: string, params: {
+        bundle?: unknown;
+        target?: ArtifactToolTarget;
+        baseHash?: string;
+        replace?: boolean;
+        createNew?: boolean;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: any;
+    }>;
+} | {
+    name: string;
+    label: string;
+    description: string;
+    parameters: T.TObject<{
+        bundle: T.TOptional<T.TObject<{}>>;
+        target: T.TOptional<T.TObject<{
+            repo: T.TOptional<T.TString>;
+            entityId: T.TOptional<T.TString>;
+        }>>;
+        context: T.TOptional<T.TUnion<[T.TLiteral<"editor">, T.TLiteral<"present">]>>;
+        frameIndexes: T.TOptional<T.TArray<T.TNumber>>;
+        maxFrames: T.TOptional<T.TNumber>;
+        includePageScreenshot: T.TOptional<T.TBoolean>;
+        includeFrameScreenshots: T.TOptional<T.TBoolean>;
+        screenshotFormat: T.TOptional<T.TUnion<[T.TLiteral<"jpeg">, T.TLiteral<"png">]>>;
+    }>;
+    execute: (_toolCallId: string, params: {
+        bundle?: unknown;
+        target?: ArtifactToolTarget;
+        context?: "editor" | "present";
+        frameIndexes?: number[];
+        maxFrames?: number;
+        includePageScreenshot?: boolean;
+        includeFrameScreenshots?: boolean;
+        screenshotFormat?: "png" | "jpeg";
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: any;
+    } | {
+        content: ({
+            type: "image";
+            data: string;
+            mimeType: "image/jpeg" | "image/png";
+        } | {
+            type: "text";
+            text: string;
+        })[];
+        details: {
+            success: true;
+            inspection: Record<string, unknown>;
+        };
+    }>;
+} | {
+    name: string;
+    label: string;
+    description: string;
+    parameters: T.TObject<{
+        target: T.TOptional<T.TObject<{
+            repo: T.TOptional<T.TString>;
+            entityId: T.TOptional<T.TString>;
+        }>>;
+    }>;
+    execute: (_toolCallId: string, params: {
+        target?: ArtifactToolTarget;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: any;
+    }>;
+} | {
+    name: string;
+    label: string;
+    description: string;
+    parameters: T.TObject<{
+        target: T.TOptional<T.TObject<{
+            repo: T.TOptional<T.TString>;
+            entityId: T.TOptional<T.TString>;
+        }>>;
+        baseHash: T.TString;
+        ops: T.TArray<T.TObject<{}>>;
+    }>;
+    execute: (_toolCallId: string, params: {
+        target?: ArtifactToolTarget;
+        baseHash?: string;
+        ops?: unknown;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: any;
+    }>;
+} | {
+    name: string;
+    label: string;
+    description: string;
+    parameters: T.TObject<{
+        target: T.TOptional<T.TObject<{
+            repo: T.TOptional<T.TString>;
+            entityId: T.TOptional<T.TString>;
+        }>>;
+        frameId: T.TOptional<T.TString>;
+    }>;
+    execute: (_toolCallId: string, params: {
+        target?: ArtifactToolTarget;
+        frameId?: string;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: any;
+    }>;
+})[];
+export {};