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

package/dist/agent/skills/artifact-canvas/skill.md

@@ -0,0 +1,257 @@
+---
+name: artifact-canvas
+description: Create sandboxed canvas artifacts as an ordered list of frames (HTML/CSS/JS) — for DESIGNED, laid-out, visual output (decks, graphics, prototypes, and documents the user wants designed on letterhead / as a formatted PDF). A plain prose draft of a proposal/contract/memo is a `document` entry, not an artifact. The platform arranges, steps, and paginates frames — a deck is one `slides` frame per slide, a designed letterhead document is ONE fixed-page-box `pages` frame flowed across pages — so never hand-roll a deck/stepper/page-grid.
+loading: on-demand
+---
+
+# Artifact Canvas
+
+Use this skill when the user asks for a visual or interactive output that should appear in the Studiograph canvas: slide decks, designed letterhead/print documents, social graphics, diagrams, prototypes, whiteboards, calculators, one-off tools, or any other artifact you can express as HTML/CSS/JS.
+
+> **Entry or artifact? Decide before you build.** A canvas artifact is for a **designed, laid-out, visual** output. If the user just wants to *draft / write / put together* a proposal, contract, memo, report, or brief as **prose**, that is a **`document` entry** (editable markdown in the graph) — NOT an artifact. Build a document *artifact* only when they signal a designed / print output: "on letterhead", "as a formatted/branded PDF", "design a proposal", a specific visual treatment. *"Draft a proposal for Acme"* → a `document` entry; *"draft a proposal for Acme on our letterhead"* / *"design a proposal"* → an artifact. When it's ambiguous, prefer the document entry (cheaper, editable) or ask: *"Want this as an editable document, or designed on letterhead?"* Decks, graphics, prototypes, and whiteboards are always artifacts — this gate is really about **prose documents**. The rest of this skill assumes you've decided it IS an artifact.
+
+An artifact is an **ordered list of frames** (the Figma/Paper artboard sense). Each frame owns its own content and geometry; the **platform** owns the arrangement (a tidy row-major grid), the present/export sequence, the stepper, scaling, and all canvas chrome. You author **content per frame** — you never write deck/stepper/grid machinery yourself.
+
+## Choose the artifact type FIRST (route the prompt)
+
+Before you build anything, decide which kind of artifact the prompt is asking for. This one decision drives the frame count, the layout, and the whole bundle — getting it wrong (a document built as one `app` frame, a deck built as a single frame, a one-page flyer paying the pagination cost) is the most common failure. Match the user's intent:
+
+| The user is asking for… | Build | Layout & frame count | Notes |
+|---|---|---|---|
+| a presentation, slide deck, pitch | a **deck** | one `slides` frame **per slide** (N → N frames) | stepped in present; never one frame for the whole deck |
+| a **flowing** document — letter, contract, report, proposal, agreement of continuous / variable-length text | a **paginated document** | **ONE** `pages` frame holding the whole body | the platform auto-flows + paginates it (Paged.js). Never one frame per page. **Load `paged-documents`.** |
+| a **fixed single page** — flyer, poster, invoice, certificate, cover, menu, one-page letter | an **artboard** | one `artboard` frame at the page size | you compose it to fit; no Paged.js |
+| a **composed multi-page** document — brochure, multi-page form, designed report where each page is its own layout | **artboards** | one `artboard` frame **per page** (N → N frames) | each page composed by hand; exports an N-page PDF; no Paged.js |
+| a social graphic, banner, ad, diagram, chart, infographic | an **artboard** | one `artboard` frame at its fixed size | the canvas size IS the design |
+| an app screen, prototype, UI mockup, tool, calculator, dashboard, landing page | an **app** | one `app` frame (`fill`, or fixed width + `fill` height) | single frame; reflows/interacts |
+| a brainstorm, mind-map, moodboard, concept map, freeform layout | a **whiteboard** | one large `whiteboard` frame | absolute placement, pannable |
+
+### Documents — FLOW vs COMPOSE (this picks `pages` vs `artboard`)
+
+For anything document-shaped, the decision that matters is: does the platform need to **flow** a continuous text stream, or are you **composing** the pages yourself?
+
+- **FLOW → `pages` (Paged.js).** ONE continuous content stream that the platform fragments across as many pages as the text needs — used precisely *because* you don't want to decide where the breaks fall (a long contract, a report of unknown length). Paged.js also repeats the letterhead on every page for free. **This is the only case that loads Paged.js** (~500KB + processing).
+- **COMPOSE → `artboard` (no Paged.js).** Each page is a fixed surface you lay out yourself — **one** frame for a single page, **N** frames for a multi-page doc whose pages are each their own composition. Faster, exports one PDF page per frame; you place content per page and repeat any header per frame (a shared CSS class).
+
+Deciding question: **"Do I want the platform to break a text stream into pages for me?"** Yes → `pages`. No (it's one page, or I'm composing each page) → `artboard`. The moment you'd be manually splitting flowing text into page-frames, switch to `pages`; the moment a "document" is really one fixed page, use `artboard` and skip the pagination cost.
+
+Caveat: an `artboard` **crops** overflow (no pagination net) — use it for content you control to fit; if the length is uncertain, `pages` is safer. The verify loop catches a cropped artboard (`framesOverflowing`).
+
+### Other tie-breakers
+- **Deck vs document:** a deck is *presented* (stepped, landscape, sparse slides); a document is *read or printed* (portrait pages, dense text, page numbers).
+- **Artboard vs app:** an artboard is a fixed static surface; an app reflows and can be interactive.
+
+A single artifact is almost always ONE type. Only mix layouts when the user genuinely asks for distinct things together; otherwise commit to one type and build it well.
+
+## Workflow
+
+1. Gather the source material from the user's prompt and any relevant entries.
+2. Build an `ArtifactBundle` (shape below) with `frames` ordered the way they should present.
+3. Call `create_artifact` with the bundle. Its result reports the resolved frame structure (`manifest`) and any `warnings` — check the frame count and per-frame layouts against what the user asked for (a deck is N `slides` frames, not one `app` frame; a document is ONE `pages` frame the platform flows across pages, not an `app`/`artboard` frame with a hand-built page grid), and resolve any warning (e.g. `packed-slides`, `packed-pages`), before you respond. This structural check is free; do it every time.
+4. Call `inspect_artifact` when you need a visual (pixel) check after meaningful work — the create/patch manifest already covers frame count and per-frame layout/geometry, but it counts characters and CANNOT measure rendered height, so it cannot see CROPPED content. For a large or content-driven artifact, inspect it: the render reports `framesOverflowing` (frames whose content is taller than their declared height and is clipped from view). A `pages` document frame is NOT in this list — it paginates instead of cropping. For an `app`/`artboard` frame that overflows, set its `geometry.height` to `"auto"` (or split the content) and re-inspect until `framesOverflowing` is empty.
+5. Keep your chat response short; the canvas carries the artifact itself.
+6. If the chat is scoped to an open artifact entry, `create_artifact` updates that canvas. If the user references a different EXISTING artifact entry, pass `target.entityId` and `target.repo` when known. To create a SEPARATE new artifact while scoped to one, pass `createNew: true` (optionally with `target.repo` to pick the destination folder) — the scoped canvas is left untouched. Otherwise it creates a new `artifact` graph entry.
+
+## Storage — always use the artifact tools
+
+An `artifact` entry stores the ArtifactBundle as **JSON** in its body — never markdown or prose. Always create and edit artifacts through the artifact tools, never `create_entity` / `update_entity` / `patch_entity`:
+
+- Create or fill: `create_artifact` with the full bundle.
+- Edit an existing one: `read_artifact` (returns the current bundle + a `hash`), modify the full bundle, then `create_artifact` passing that `hash` as `baseHash` so a concurrent change is detected instead of silently overwritten.
+
+`create_artifact` assembles and validates the bundle for you; the generic entry tools reject a hand-written artifact body. If you only have raw markdown/prose you haven't laid out yet, create a `document` entry instead — not an `artifact`.
+
+Make a revision as ONE `create_artifact` that rewrites the whole bundle — don't fan out several edits to the same artifact in parallel. Each write replaces the entire bundle, so concurrent writes race; a sibling write that lands first makes yours fail the `baseHash` precondition (re-read and retry rather than retrying blindly).
+
+## Large artifacts — build a skeleton, then grow it incrementally
+
+A whole bundle is emitted as ONE streamed `create_artifact` argument. A very large bundle (long decks, multi-section documents) can blow past the model's per-response output-token limit **mid-content**: the response is cut off, but a partial bundle can still close validly and SAVE — so you get a silently truncated artifact (missing frames, content ending mid-sentence) that reports success. This is NOT the 512KB storage cap; it's the model's output limit, and it fires long before 512KB.
+
+Do not try to one-shot a large artifact. Author it in steps:
+
+1. **Skeleton first.** `create_artifact` with every frame present but each holding only its heading/placeholder (a few lines). This establishes the structure cheaply, well under the output limit.
+2. **Fill incrementally with `patch_artifact`** — one frame (or one section) per call. Use `set_frame_content` to populate a skeleton frame, or `add_frame` to append a new frame. Each patch is its own response with its own output budget, so the total content can far exceed what a single `create_artifact` could emit. (Pass the `base_hash` from the previous read/write; re-read if it drifts.)
+3. **Heed the truncation warning.** If a `create_artifact` / `patch_artifact` result says output was TRUNCATED (it hit the model limit), do NOT assume the write finished — `inspect_artifact` to see what landed, then append the rest with `patch_artifact`.
+
+Rule of thumb: more than ~8–10 content-heavy frames, or any single frame with a lot of prose? Go skeleton-first + patch. It is the reliable path, not a fallback.
+
+## Bundle shape
+
+A valid bundle is a JSON object:
+
+```jsonc
+{
+  "artifactId": "client-overview",   // stable id, starts alphanumeric
+  "title": "Client Overview",
+  "frames": [ /* ordered, at least one */ ],
+  "tokens": { "brand": "#e8482b" },   // optional CSS design variables → :root custom props
+  "shared": {                          // optional code shared across ALL frames
+    "files": { "deck.css": "…", "deck.js": "…" },
+    "head": "<link rel=\"preconnect\" …>"
+  },
+  "libraries": ["motion"],            // optional curated runtimes: three | d3 | motion
+  "display": { "background": "#0b0b10" }   // optional default frame bg: neutral | transparent | a CSS color/gradient
+}
+```
+
+### Frames
+
+Each frame:
+
+```jsonc
+{
+  "id": "cover",                 // stable, unique within the artifact
+  "title": "Cover",              // optional human label shown above the frame
+  "layout": "slides",            // slides | pages | artboard | app | whiteboard
+  "geometry": { "width": 1280, "height": 720 },
+  "content": "<section>…</section>",  // the frame's HTML FRAGMENT (no <html>/<body>)
+  "background": "#0b0b10"        // optional per-frame bg: neutral | transparent | a CSS color/gradient
+}
+```
+
+**Letterhead, running headers & footers — use general CSS Paged Media.** A `pages` document is plain HTML/CSS — design it as richly as you like (full-bleed colored bands, logos, zebra-striped tables, multi-column footers). To make content **repeat on every page** (a letterhead, running header, footer, page numbers), use **standard CSS Paged Media** in a `shared` CSS file — the open, fully-flexible mechanism (Paged.js renders it). This is the PRIMARY way; aim for a real designed letterhead, not a plain text line.
+
+> **Building a multi-page document, load the `paged-documents` skill first.** It is the deep, effective-use reference for the pagination layer — `@page` rules, named/cover pages, the page-margin-box **width** mechanics that decide whether a running header clips, running elements for real letterhead, page counters, break control, and the mandatory render-and-inspect verify loop. The summary below gets you started; that skill is how you do it *well*.
+
+- Mark an element as *running* and pull it into a page-margin box. Put the element once at the top of the frame `content`; it renders in the margin of EVERY page:
+  ```css
+  .letterhead { position: running(lh); }
+  @page {
+    margin: 132px 64px 90px;                /* room for the running header/footer */
+    @top-center    { content: element(lh); }
+    @bottom-center { content: element(ft); }
+    @bottom-right  { content: "Page " counter(page) " of " counter(pages); }
+  }
+  ```
+  You get the full surface: any of the 16 margin boxes (`@top-left`/`@bottom-right`/…), `:first`/`:left`/`:right` page selectors, named pages, counters.
+- **Full-bleed branded band** (a colored letterhead that runs edge-to-edge): set the side page margins to `0`, give the running element a background + fixed height, and position its left/right parts with **`position:absolute`**. Do NOT use flex/table to spread them: that layout does NOT survive Paged.js's clone into the margin box (the parts collapse stacked + centered) — absolute children anchor to the band's edges and DO render correctly. (Verified by render.) **Footer/header TEXT needs its own inset when side margins are `0`:** the band is meant to bleed, but `@bottom-left`/`@bottom-right`/`@top-*` text in a 0-margin page sits flush against the paper edge. Margin boxes accept `padding`, so pad each text slot to your body gutter (`padding-left`/`padding-right: 64px`) — only the band bleeds; the furniture aligns to the column.
+  ```css
+  @page  {
+    margin: 104px 0 64px;                              /* side margins 0 → the band bleeds */
+    @top-center  { content: element(band); }
+    @bottom-left { content: "Confidential"; padding-left: 64px; }   /* inset the text to the column */
+    @bottom-right{ content: counter(page);  padding-right: 64px; }  /* (margins are 0, so pad each box) */
+  }
+  .band  { position: running(band); height:104px; background:#16315c; color:#fff; }
+  .brand { position:absolute; left:64px;  top:50%; transform:translateY(-50%); }
+  .addr  { position:absolute; right:64px; top:50%; transform:translateY(-50%); text-align:right; }
+  .doc   { padding: 0 64px; }                /* the body supplies its own side gutters */
+  ```
+- Anything you author this way **overrides the platform defaults** (the default margins + the auto page number) — you are in full control.
+
+The platform also offers two **optional shortcuts** for the simple case; any author CSS Paged Media above overrides them, and for a full-bleed band or any non-trivial layout you should use CSS Paged Media, not these:
+
+- **`furniture`** (a `pages` frame field) — a plain inset running header/footer: `{ header?, footer? }`, each with `first` (page 1) / `middle` (the rest + fallback) / `last` (final page) HTML. The platform tucks the header into the top margin and the footer into the bottom and never lets them overlap the body. Inset to the content column (not full-bleed). Use only when you want a plain running line and don't want to write `@page` CSS. `furniture` positions itself from `pageMargins` (or the defaults) — so if you set your own `@page { margin }` in CSS, don't also use `furniture`; put your header/footer in `@page` margin boxes instead.
+- **`pageMargins`** (a `pages` frame field, px per side; absent sides default to top 96 / sides 72 / bottom 84) — a shortcut for `@page { margin: … }`.
+
+- **`content` is a fragment**, not a full document. The platform assembles ONE sandboxed document: it injects `tokens` as `:root` custom properties, the `shared.head`, every `shared.files` stylesheet/script, then each frame's `content`. So a class defined in a `shared` CSS file is available to every frame — you do not write `<link>`/`<style>`/`<head>` yourself (put shared CSS/JS in `shared.files`, not inline `<style>` repeated per frame).
+- **Order is the meaning**: it is the present/export/pagination sequence. Reordering is a list move.
+- Use stable `data-sg-name` / `data-sg-role` attributes on important elements (e.g. `data-sg-name="Pricing table"`) so the user can click to select them and ask for scoped edits in natural language.
+
+### Layouts
+
+- **`slides`** — a fixed-size deck frame (e.g. `1280×720` or `1920×1080`), stepped one at a time in present. One frame = one slide.
+- **`pages`** — a **flowing** print/document frame, the only layout that loads Paged.js. Use it when the platform should auto-flow a continuous text stream across pages. Give it a **fixed page-box width AND height** — any size @96dpi, portrait/landscape/arbitrary (common presets: US-Letter `816×1056`, Legal `816×1344`, Tabloid `1056×1632`, A4 `794×1123`, A3 `1123×1587`, A5 `559×794`) — and put the **whole document body** in ONE `pages` frame's `content`. The platform flows the text across as many pages as needed, numbers them, and exports a real multi-page PDF. A fixed `pages` box does NOT crop — overflow flows onto the next page. Use `break-before: page` to force a new page and `break-inside: avoid` to keep a block together; for repeating letterhead, **load the `paged-documents` skill**. The model for letters, contracts, proposals, agreements, and variable-length reports. (A `pages` frame with `height: "auto"` is NOT paginated and does not load Paged.js — one tall continuous page; use it for a deliberately single scroll.) **If the document is one fixed page, or pages you compose by hand, use `artboard` instead** (no Paged.js) — see the router.
+- **`artboard`** — a **fixed-size composed surface**: a banner, social graphic, diagram, or poster, AND the non-paginated document surface — a single fixed page (flyer, invoice, certificate, one-pager) as ONE `artboard` frame, or a multi-page document you compose page-by-page as N `artboard` frames (one per page, exported as an N-page PDF). No Paged.js. A fixed `artboard` CROPS overflow, so design it to fit (or use `pages` if the length is uncertain).
+- **`app`** — a full-bleed responsive prototype / app screen. Use `geometry: { "width": "fill", "height": "fill" }` to span the whole viewport (content reflows). For a fixed-width app (a phone / tablet / sidebar mock), set a numeric `width` with `"height": "fill"` — the platform centers and letterboxes it at that width and fills height, rather than stretching edge-to-edge. An `app` artifact is single-frame.
+- **`whiteboard`** — one large pannable freeform surface (e.g. `2400×1600`). Opens at 100% centered and pans; no stepper. The platform draws a dot-grid surface; you place content (notes, diagrams, images) absolutely.
+
+### Geometry
+
+`width` is a number (px) or `"fill"`. `height` is a number, `"auto"` (content-driven), or `"fill"`. `"fill"` = span the available viewport (single-frame `app`).
+
+**On a `pages` frame, a fixed page-box height does NOT crop — it paginates.** A *flowing* multi-page document (a letter/contract/report whose text runs to an unknown length) is a `pages` frame with a fixed page-box width AND height (e.g. `816×1056`); the platform flows the overflow onto more pages and prints letterhead + page numbers. Reach for `pages` when you want that auto-flow; for a single fixed page or hand-composed pages, use `artboard` frames (no Paged.js) — see the router. `height: "auto"` on a `pages` frame turns pagination OFF (one tall continuous page, no Paged.js) — for a deliberately single non-paginated scroll.
+
+**On a non-`pages` frame, a fixed numeric height CROPS content taller than it** — the frame is a hard box with `overflow:hidden`, so anything past the declared height is clipped from view. For a content-driven `app`/`artboard` surface whose length you can't predict, declare `height: "auto"` so it grows to fit; do NOT guess a tall fixed number (e.g. `4000`) "to be safe". Use a fixed numeric height for genuinely fixed surfaces (a `slides` deck, a poster/banner `artboard`) where the canvas size IS the design.
+
+## Background — paint the design's real surface
+
+A frame defaults to a solid white surface (`pages`/`app`) or transparent (`slides`/`artboard`). **When the design has a non-white background — a dark deck, a colored cover, a brand gradient — set the frame's `background` to that actual color or gradient**, or it renders white. Set it per-frame, or set `display.background` for the artifact-wide default. It accepts:
+
+- a keyword — `"neutral"` (white) or `"transparent"`;
+- a **color** — `"#0b0b10"`, `"rgb(11,11,16)"`, `"hsl(240 30% 8%)"`;
+- a **gradient** — `"linear-gradient(135deg, #0b0b10, #1a1a2e)"`, `"radial-gradient(circle, #1a1a2e, #000)"`.
+
+`background` is the BACKDROP behind the frame's content, restricted to a plain color or gradient — the standard color functions (`rgb`/`hsl`/`hwb`/`lab`/`lch`/`oklab`/`oklch`/`color-mix`) and gradient functions (`linear`/`radial`/`conic`, incl. `repeating-`). It rejects `url()`, images, and anything else (`var()`, `calc()`, `env()`, …); for an image backdrop or a value built from variables, put it in the frame's own HTML/CSS instead. Style per-element colors in the content's HTML/CSS as usual. (Exception: a `whiteboard` ignores `background` — its themed paper surface is platform-owned; see "Whiteboard theming".)
+
+## Sizing — author at natural 1:1
+
+Frames render at their **declared pixel size**, and the host opens them at **100% (1:1)** by default. Size content the way you would for a real 1:1 screen — do NOT inflate fonts/elements for a large surface:
+
+- **slides**: the geometry (e.g. 1920×1080) IS the design size; size type to read on a projected slide.
+- **artboard / pages**: the declared geometry is the 1:1 design surface; don't inflate beyond what reads at that size.
+- **whiteboard**: body text ~14–18px, section titles ~28–32px, post-its ~200px — not 60px+ titles. If a single element is wider than ~⅓ of the canvas or its body text is over ~20px, it is probably over-scaled. Cluster primary content near the centre (visible on open), secondary material spread out to pan to.
+
+## Whiteboard theming — use the ink tokens
+
+The whiteboard is the **one** surface the platform themes: its paper + dot-grid follow the user's light/dark setting. `slides`/`pages`/`artboard`/`app` are author-designed end to end and are **not** themed. So whiteboard content drawn directly on the bare surface must adapt, or "default ink" authored for light paper goes invisible on the dark surface. Opt into the platform tokens for ink on the bare surface:
+
+- `var(--sg-ink)` — primary foreground: connector lines, outlines, line-art, monochrome icons, body text, the title.
+- `var(--sg-ink-muted)` — secondary: eyebrows, labels, hairlines, captions.
+- `var(--sg-surface)` — the paper color, for a panel/shape that should match the board.
+
+For SVG line-art, set `color: var(--sg-ink)` on the `<svg>` and use `currentColor` for `stroke`/`fill` (presentation attributes can't take `var()`). **Do NOT theme intentional content**: anything with its OWN background — a colored post-it, a photo, a filled callout — keeps its own colors and pins its own (usually dark) text; don't let it inherit `--sg-ink` or it turns light-on-light in dark mode.
+
+## JavaScript & libraries
+
+JS runs only inside a sandboxed iframe. Write self-contained JS in `shared.files` (e.g. `deck.js`); it runs after any requested libraries are ready. Do not rely on network access, external packages, cookies, localStorage, parent-window access, downloads, forms, or navigation. For 3D/data-viz/animation, request a curated local runtime instead of a CDN:
+
+- `"three"` exposes `window.THREE`; `"d3"` exposes `window.d3`; `"motion"` exposes `window.Motion`.
+
+Do not request framework/component kits (shadcn, Bits UI, React, Tailwind runtime). Build components as semantic HTML + self-contained CSS.
+
+## Constraints
+
+- Keep the whole bundle under 512KB.
+- Do not reference external URLs for scripts, styles, fonts, images, APIs, or tracking.
+- Custom fonts may be referenced only from uploaded Studiograph asset URLs (`/api/assets/…`) or `data:` URLs (declare `@font-face` in a `shared` CSS file or `shared.head`).
+- Use embedded SVG, CSS shapes, data URIs, or uploaded asset URLs for imagery.
+
+## Example — a slide deck
+
+```json
+{
+  "artifactId": "client-overview",
+  "title": "Client Overview",
+  "tokens": { "brand": "#e8482b", "ink": "#16110f" },
+  "shared": {
+    "files": {
+      "deck.css": "*{box-sizing:border-box;margin:0}.slide{width:100%;height:100%;padding:80px;font-family:Inter,system-ui;color:var(--ink);display:flex;flex-direction:column;justify-content:center;gap:24px}.tag{color:var(--brand);font-weight:600;text-transform:uppercase;letter-spacing:.08em;font-size:24px}h1{font-size:84px;line-height:1.02}h2{font-size:54px}p{font-size:30px;color:#5a514d;max-width:62ch}"
+    }
+  },
+  "frames": [
+    { "id": "cover", "title": "Cover", "layout": "slides", "geometry": { "width": 1280, "height": 720 },
+      "content": "<div class=\"slide\"><div class=\"tag\">Overview</div><h1 data-sg-name=\"Cover title\">Client Overview</h1><p>Q3 engagement summary.</p></div>" },
+    { "id": "approach", "title": "Approach", "layout": "slides", "geometry": { "width": 1280, "height": 720 },
+      "content": "<div class=\"slide\"><div class=\"tag\">Approach</div><h2>How we work</h2></div>" }
+  ]
+}
+```
+
+Each slide is one `slides` frame; the shared `deck.css` styles every frame; the platform steps and exports them — there is no hand-rolled navigation or grid.
+
+## Example — a flowing letterhead document (full-bleed band via CSS Paged Media)
+
+A *flowing* letter, contract, or proposal is ONE `pages` frame at a fixed page size; the `content` is the whole body and the platform flows it across pages. (A single fixed page or a multi-page document you compose by hand is an `artboard` instead — see the router; this example is the auto-flow case.) The letterhead is a **running element** in a `@page` margin box, so it repeats on every page; side margins are `0` so the band runs edge-to-edge, and the band's logo/address are placed with **`position:absolute`** (flex/table collapse inside a Paged.js margin box — verified). The footer is `@bottom-left`/`@bottom-right` margin boxes **padded to the body gutter** (side margins are `0`, so without the `padding` the footer would sit on the paper edge); the page size comes from `geometry`, so there is **no `@page { size }`**.
+
+```json
+{
+  "artifactId": "offer-letter",
+  "title": "Offer of Employment",
+  "shared": {
+    "files": {
+      "doc.css": "*{box-sizing:border-box}body{margin:0;font:14px/1.6 -apple-system,Segoe UI,Roboto,sans-serif;color:#1f2937}.doc{padding:28px 64px}h2{color:#16315c;font-size:13px;letter-spacing:.06em;text-transform:uppercase;border-bottom:1px solid #e5e7eb;padding-bottom:6px;margin:22px 0 12px}p{margin:0 0 12px}table{width:100%;border-collapse:collapse;font-size:13px}td{padding:9px 12px;border-bottom:1px solid #eef2f7}tr:nth-child(odd) td{background:#f7f9fc}.band{position:running(band);height:104px;background:#16315c;color:#fff}.brand{position:absolute;left:64px;top:34px}.logo{display:inline-block;width:40px;height:40px;border-radius:8px;background:#e8492b;color:#fff;text-align:center;line-height:40px;font-weight:800;font-size:22px;vertical-align:middle;margin-right:14px}.btxt{display:inline-block;vertical-align:middle}.btxt b{font-size:20px}.btxt small{display:block;color:#9fb3d1;font-size:10px;letter-spacing:.12em}.addr{position:absolute;right:64px;top:38px;text-align:right;font-size:11px;color:#cdd9ea;line-height:1.5}.exhibit{break-before:page}@page{margin:104px 0 70px;@top-center{content:element(band)}@bottom-left{content:\"Confidential\";padding-left:64px;font-size:10px;color:#9ca3af}@bottom-right{content:\"Page \" counter(page) \" of \" counter(pages);padding-right:64px;font-size:10px;color:#9ca3af}}"
+    }
+  },
+  "frames": [
+    {
+      "id": "letter",
+      "layout": "pages",
+      "geometry": { "width": 816, "height": 1056 },
+      "content": "<div class=\"band\"><div class=\"brand\"><span class=\"logo\">A</span><span class=\"btxt\"><b>Acme Inc.</b><small>PEOPLE &amp; TALENT</small></span></div><div class=\"addr\">1 Acme Plaza, Suite 800<br>San Francisco, CA 94105<br>hr@acmeinc.com</div></div><div class=\"doc\"><p style=\"color:#6b7280\">June 17, 2026</p><p><b>Jordan Lee</b><br>742 Evergreen Terrace<br>Portland, OR 97201</p><p>Dear Jordan,</p><p>On behalf of the entire team at Acme Inc., it is our great pleasure to extend this offer…</p><h2>Position Details</h2><table><tr><td>Job Title</td><td>Senior Product Manager</td></tr><tr><td>Start Date</td><td>July 14, 2026</td></tr></table><section class=\"exhibit\"><h2>Conditions of Employment</h2><p>…</p></section></div>"
+    }
+  ]
+}
+```
+
+ONE `pages` frame, fixed `816×1056`; the platform paginates the body into as many pages as the content needs and the running band + footer repeat on every page. For a different size set `geometry` to a preset (A4 `794×1123`, Tabloid `1056×1632`, …). Never make one frame per page, and never simulate pages with a CSS grid. (For just a plain inset header/footer with no `@page` CSS, the `furniture` shortcut is the lighter option.)

package/dist/agent/skills/create-skill.md

@@ -0,0 +1,39 @@
+---
+name: create-skill
+description: Capture a repeatable task or a just-produced output (a document/deck house style, a report format, a workflow) as a reusable skill the agent can load and reuse later. Use when the user asks to "create/save a skill", "make this reusable", or "remember how to do this" — and proactively offer it after producing polished, reusable, style-bearing work.
+loading: on-demand
+---
+
+# Create Skill
+
+A **skill** is reusable agent instructions saved as a `skill` entry in the workspace. Once saved it appears in the skill index and is loaded on demand, so the next time a similar task comes up the house style / recipe / steps are applied consistently. This is how a workspace teaches itself: capture a good output once, reuse it forever.
+
+## When to create a skill
+
+- **Explicit** — the user says "create a skill", "save this as a skill", "make this reusable", "remember how to do this", "do it like this from now on".
+- **Proactive** — you just produced something polished and reusable that has a repeatable RECIPE (a branded document or deck style, a standard report format, a multi-step workflow). Offer ONCE, in one short line: *"Want me to save this as a reusable '<name>' skill so I can produce it consistently next time?"*
+  - Only offer for genuinely reusable, style-bearing work — NOT for one-off answers, edits, searches, or trivial outputs.
+  - Offer at most once for a given piece of work; if the user declines or ignores it, drop it and don't re-offer.
+
+## Author a good skill
+
+1. **Distill the RECIPE, not the instance.** If you just made an artifact, extract the reusable pattern — the structure, the CSS / house style, the steps — and drop the one-off content. Generalize "Acme's offer letter to Jordan Lee" into "an offer letter on the company's letterhead". Parameterize what varies (company, names, figures); keep what's stable (layout, tone, sections, format).
+2. **Write a sharp `description` — this is the most important field.** It is what ROUTES the skill: the agent reads skill descriptions to decide when to load one. State exactly WHEN to use it, in the user's words, in one or two sentences. A vague description means the skill is never loaded.
+3. **Write the body as concrete, runnable instructions** — the steps, the key patterns, and a **worked example** (the actual CSS / structure / template). Concrete examples beat abstract prose. Keep it tight: instructions, not an essay.
+4. **Don't over-fit and don't bloat.** One skill = one coherent capability. If it's trying to do five unrelated things, it's five skills.
+
+## Save it
+
+**Always ask the user which folder to save the skill in** before creating it — don't assume. A personal folder makes it the user's own skill; a shared/team folder makes it available to the whole team. Confirm the destination.
+
+Then create it with `create_entity`:
+- `entity_type: 'skill'`
+- `entity_id`: a kebab-case skill name (e.g. `offer-letter`) — the id IS the skill name.
+- `data`: `{ name: '<Display Name>', description: '<the sharp when-to-use line>', loading: 'on-demand' }`
+- `content`: the markdown instructions body (recipe + worked example). Do NOT open the body with an `#` H1.
+
+`loading: 'on-demand'` is almost always right — the skill loads only when its description matches the task. Reserve `'eager'` for guidance that must shape every response.
+
+## After saving
+
+Confirm to the user and link the new skill with a wikilink — e.g. *"Saved the **Offer Letter** skill ([[offer-letter]]) — next time you ask for an offer letter I'll use this format."* The skill is loadable immediately via `load_skill`; no restart needed.

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

@@ -1,182 +1,100 @@
 ---
 name: entity-schema
-description: Complete field reference for the 9 launch-visible entity types — required/optional fields, status enums, file layout, frontmatter
+description: Field reference for canonical entity types — file layout, base fields, wikilinks. Enum values come from get_entity_schema.
 loading: on-demand
 ---
 
 # Entry Schema Reference
 
-Use this reference when creating, validating, or mapping entries. All entries are Markdown files with YAML frontmatter stored in `{collection}/{entity_id}/main.md` (entity-folder layout).
+Use this reference when creating, validating, or mapping entries. All entries are Markdown files with YAML frontmatter stored in `{folder}/{entity_id}/main.md` (entity-folder layout).
+
+Studiograph has 16 canonical entity types (15 user-facing + 1 system). The full per-type field list — including enum values, defaults, and descriptions — lives in `src/core/validation.ts` (`ENTITY_SCHEMAS`). **Do not memorize field shapes from this document.** Call `get_entity_schema(entityType)` to fetch the authoritative schema before writing. Workspaces may also define custom types via `schema_extensions` in their workspace config; those types are returned by `get_entity_schema` too.
+
+## When to call `get_entity_schema`
+
+- Before the first create/update of a given entity type in a conversation.
+- After any error mentioning an unknown enum value, a missing field, or a type mismatch.
+- Whenever you're about to write a field name that hints at an enum (`stage`, `status`, `category`, `priority`, `audience`, `source`, `type`) and you don't have the current list in this turn.
+
+The response shape:
+
+```json
+{
+  "success": true,
+  "entityType": "deal",
+  "fields": {
+    "name": { "type": "string", "optional": false, "description": "Deal name is required" },
+    "stage": {
+      "type": "enum",
+      "optional": true,
+      "description": "Pipeline stage (lead = pre-pipeline; dormant = parked, not lost)",
+      "enum": ["lead", "qualification", "scoping", "proposal", "negotiation", "pending-signature", "won", "lost", "dormant"]
+    },
+    "deal_value": { "type": "number", "optional": true, "description": "Estimated deal value" },
+    "services": {
+      "type": "string[]",
+      "optional": true,
+      "description": "Service entities this project includes (wikilinks)",
+      "itemType": "string"
+    }
+  },
+  "bodyTemplate": "## Opportunity\n\n## Scope\n\n## Next Actions\n\n## Notes\n\n"
+}
+```
+
+Use `enum` to know what's allowed, `default` to know what you'll get if you omit the field, and `description` to disambiguate similar field names.
 
-The agent can create the 9 entry types documented here. Additional canonical types (`role`, `practice-area`, `decision`, `deliverable`, `publication`, `process`, `guideline`, `case-study`, `dataset`) exist in storage for backward compatibility but are not available for new creation at launch. Workspaces may also define custom types via `schema_extensions` in their workspace config.
+`bodyTemplate` (present for types that have one — omitted for `note`, `dataset`, etc.) is the **suggested** markdown section scaffold for the entry body, the same one a human gets from the New Entry picker. Treat it as a **guideline, not a rule**: use it as-is when it fits, adapt it (rename/reorder sections), add or drop sections, or write a different structure entirely when the specific entry calls for it. The goal is a body that serves the entry — not dogmatic adherence to the scaffold.
 
 ## Base Fields (all entries)
 
-Every entry inherits these fields. Most are auto-populated by the system on create/update.
+Every entry inherits these fields. Most are auto-populated by the system on create/update — do not pass them yourself.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `entity_type` | string | Yes | The entry type identifier |
-| `entity_id` | string (kebab-case) | Yes | Unique ID: lowercase, numbers, hyphens, underscores |
+| `entity_type` | string | Yes | The entry type identifier (passed as the `entityType` parameter, not in `data`) |
+| `entity_id` | string (kebab-case) | Yes | Unique ID: lowercase letters, numbers, hyphens, underscores |
 | `created_at` | datetime | Yes | ISO 8601 (auto) |
 | `updated_at` | datetime | Yes | ISO 8601 (auto) |
 | `created_by` | string | Yes | Username (auto) |
 | `updated_by` | string | Yes | Username (auto) |
-| `date` | string | No | Human-friendly date |
+| `date` | string | No | Human-friendly date (event date, project start, etc.) |
 | `tags` | string[] | No | Categorization tags (Title Case, except acronyms which stay uppercase: "AI", "UI Design", "B2B") |
 
-Schemas use `.passthrough()` — custom fields beyond the schema are preserved.
-
-## Wikilinks
-
-Cross-entry references use `[[entity-id]]` wikilink syntax in string or string[] fields. Fields named `related_*`, `attendees`, `team`, `assignee`, `organization`, `project` typically hold wikilinks.
-
----
-
-## note
-
-Freeform thinking, research, scratch notes, brainstorms, drafts.
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `title` | string | No | Optional title (first line of body used otherwise) |
-| `type` | enum | No | `research` \| `scratch` \| `daily` \| `brainstorm` \| `draft` |
-| `related_projects` | string[] | No | Project wikilinks |
-| `related_people` | string[] | No | Person wikilinks |
-
-Prefer `note` for freeform thinking. Prefer `document` for structured authored content.
-
-## meeting
+Schemas use `.passthrough()` — custom fields beyond the schema are preserved on disk.
 
-Meetings, calls, workshops — with attendees, agenda, notes, action items.
+## Canonical Entity Types
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | Yes | Meeting name/subject |
-| `date` | string | No | Meeting date (ISO or human-readable) |
-| `attendees` | string[] | No | Person wikilinks |
-| `related_projects` | string[] | No | Project wikilinks |
-| `related_organizations` | string[] | No | Organization wikilinks |
-| `agenda` | string | No | Agenda (markdown) |
-| `notes` | string | No | Notes (markdown) |
-| `action_items` | string[] | No | Action items |
-| `summary` | string | No | Meeting summary |
-
-The `date` field must reflect when the meeting actually occurred, not when the entry was captured.
-
-## task
-
-Action items and to-dos.
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | Yes | Task name |
-| `assignee` | string | No | Person wikilink |
-| `due_date` | string | No | Due date |
-| `status` | enum | No | `open` (default) \| `in-progress` \| `done` \| `cancelled` |
-| `priority` | enum | No | `low` \| `medium` \| `high` \| `urgent` |
-| `project` | string | No | Project wikilink |
-| `related_meeting` | string | No | Meeting wikilink (if task came from a meeting) |
-| `description` | string | No | Detailed description |
-
-Use `assignee` (schema field). Never invent `assigned_to`.
+The 16 canonical types are grouped into five categories. For each, call `get_entity_schema` to see required fields, enums, and defaults.
 
-## document
+**CRM:** `person`, `organization`, `position`, `deal`
+**PM:** `project`, `event`, `task`, `deliverable`
+**KM (authored):** `document`, `deck`, `publication`, `case-study`, `service`, `skill`
+**Capture:** `note`, `reference`
+**System:** `comment` (virtual, SQLite-backed)
 
-Any authored document — reports, proposals, briefs, memos, templates, financial plans.
+Quick notes on common types:
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | Yes | Document name |
-| `type` | string | No | Free-form descriptor: `report`, `proposal`, `contract`, `brief`, `memo`, `financial-plan`, `template`, etc. |
-| `client` | string | No | Client organization wikilink |
-| `project` | string | No | Project wikilink |
-| `status` | enum | No | `draft` (default) \| `sent` \| `signed` \| `completed` |
-| `date` | string | No | Document date |
-| `team` | string[] | No | Person wikilinks |
-| `related_deals` | string[] | No | Deal wikilinks |
+- **person** — `name` is required; `role` is free-text (distinct from the `position` entity type, which is a job spec).
+- **organization** — clients/vendors/partners/prospects.
+- **deal** — pre-project pipeline opportunity. `stage` is OPTIONAL with no default (a lead in the new-business inbox legitimately has no stage); the enum runs `lead` (pre-pipeline) → `qualification` … `won`/`lost` → `dormant` (parked, not lost). Pipedrive-mirrored fields: `deal_type`, `deal_score` (hot/warm/cold), `pipedrive_deal_id`, `pipedrive_lead_id`, `expected_close_date`, `currency`, `owner`, `organization` — all optional.
+- **event** — any scheduled gathering (meeting, call, workshop, review, presentation, conference). Body holds Summary / Notes / Action Items.
+- **task** — `assignee` (not `assigned_to`), free-text `phase`.
+- **note** — freeform capture. Decisions land here as plain notes.
+- **deck** — slide decks. Has a dedicated renderer; pattern-matches on `entity_type === 'deck'`.
 
-Prefer `document` for structured authored content (reports, assessments, summaries, email drafts, analyses). Use a specific `type` to categorize.
+For anything more specific (which enum values are valid, what's required, what defaults apply), call `get_entity_schema`.
 
-## dataset
-
-Structured tabular data with typed columns. The markdown body holds CSV rows; the frontmatter `schema` defines column types.
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | Yes | Dataset name |
-| `schema` | ColumnDefinition[] | Yes | Column definitions (min 1) |
-| `description` | string | No | What the data represents |
-
-Each column in `schema` is `{ name, type: "string"|"number"|"boolean"|"date", required?, description? }`.
-
-Datasets are created from CSV uploads (schema inferred automatically) or manually. Use `query_dataset` to filter rows and `append_rows` to add data.
-
-## person
-
-Team members, client contacts, any individual.
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | Yes | Full name |
-| `role` | string | No | Role or title |
-| `status` | enum | No | `current` \| `former` \| `contractor` \| `client` \| `partner` |
-| `email` | string | No | Email address |
-| `location` | string | No | Location |
-| `organization` | string | No | Organization wikilink |
-
-The `name` must be the full human name as it appears in the source. If only a first name is given, use "First (Organization)" (e.g., "Andrew (Simpson Thacher)") rather than truncating.
-
-## organization
-
-Clients, vendors, partners, prospects, industry bodies.
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | Yes | Organization name |
-| `category` | enum | No | `client` \| `vendor` \| `partner` \| `prospect` \| `industry-body` \| `other` |
-| `status` | enum | No | `active` (default) \| `inactive` \| `former` |
-| `industry` | string | No | Industry sector |
-| `website` | url | No | Website URL |
-
-## project
-
-Client engagements and internal initiatives.
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | Yes | Project name |
-| `client` | string | No | Client organization wikilink |
-| `website_url` | url | No | Project website |
-| `start_date` | string | No | ISO 8601 |
-| `end_date` | string | No | End date |
-| `status` | enum | No | `planning` \| `scoping` \| `active` \| `on-hold` \| `completed` \| `archived` |
-| `team` | string[] | No | Person wikilinks |
-| `related_projects` | string[] | No | Related project wikilinks |
-
-## reference
-
-External resources and inspiration.
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | Yes | Reference name |
-| `type` | enum | No | `article` \| `video` \| `tool` \| `technique` \| `framework` \| `website` |
-| `date` | string | No | Publication date |
-| `source` | string | No | Source/author |
-| `link` | string | No | URL |
-| `related_projects` | string[] | No | Project wikilinks |
-| `related_people` | string[] | No | Person wikilinks |
-| `description` | string | No | Description |
+## Wikilinks
 
----
+Cross-entry references use `[[entity-id]]` wikilink syntax in string or string[] fields. Fields named `attendees`, `team`, `assignee`, `organization`, `client`, `services`, `depends_on`, `enables`, `project` typically hold wikilinks. The schema returns `string` / `string[]` for these — the wikilink convention is semantic, not enforced at the type level.
 
 ## File Layout
 
 Entries use the **entity-folder** layout:
 
 ```
-{collection}/
+{folder}/
   {entity_id}/
     main.md          # Sentinel file (frontmatter + body)
     notes/           # Optional sub-content
@@ -196,11 +114,8 @@ entity_id: acme-website-redesign
 name: Acme Website Redesign
 client: "[[acme-corp]]"
 start_date: "2026-01-15"
-end_date: "2026-06-30"
-status: active
-team:
-  - "[[alice-smith]]"
-  - "[[jamie-torres]]"
+date: "2026-06-30"        # a project's `date` is its end date
+status: in-progress
 tags:
   - Website
   - Redesign
@@ -214,3 +129,5 @@ updated_by: alice-smith
 
 Project content goes here. Use [[wikilinks]] to reference other entries.
 ```
+
+The `status` value above is illustrative — call `get_entity_schema('project')` to see the current allowed values before writing.