@agent-native/core 0.122.4 → 0.123.1

package/corpus/core/docs/content/template-slides.mdx

@@ -7,7 +7,7 @@ description: "Generate decks from a prompt, edit visually, and present full-scre
 
 Generate full presentation decks from a prompt, edit slides visually, and present full-screen. Ask the agent for "a 10-slide pitch deck for a coffee subscription service" and watch it stream slide-by-slide into the editor in seconds. It's an open-source replacement for Google Slides, Pitch, and PowerPoint — a deck editor you own end to end: generate, import, edit, present, and export without a subscription.
 
-<WireframeBlock id="doc-block-eqogw6">
+<WireframeBlock id="doc-block-slides1">
   <Screen
     surface="desktop"
     html={
@@ -16,9 +16,9 @@ Generate full presentation decks from a prompt, edit slides visually, and presen
   />
 </WireframeBlock>
 
-When you open a deck, the slide canvas, outline, notes, and filmstrip stay in one editor surface while the agent can still create, revise, and navigate slides through actions.
+When you open a deck, the slide canvas, outline, notes, and filmstrip stay in one editor surface while the agent can still create, revise, and navigate slides through the same actions.
 
-<Diagram id="doc-block-1u9bt95" title="Prompt to deck" summary="Ask for a deck and the agent streams slides in one at a time through the same actions you could call from the CLI.">
+<Diagram id="doc-block-slides2" title="Prompt to deck" summary="Ask for a deck and the agent streams slides in one at a time using the same tools you can also drive yourself.">
 
 ```html
 <div class="diagram-flow">
@@ -34,7 +34,7 @@ When you open a deck, the slide canvas, outline, notes, and filmstrip stay in on
   <div class="diagram-col">
     <div class="diagram-pill">create-deck</div>
     <div class="diagram-pill">add-slide &#215; n</div>
-    <small class="diagram-muted">parallel, streaming</small>
+    <small class="diagram-muted">one slide at a time</small>
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
   <div class="diagram-box" data-rough>decks (SQL)</div>
@@ -70,18 +70,17 @@ When you open a deck, the slide canvas, outline, notes, and filmstrip stay in on
 
 </Diagram>
 
+Before generating something new, the agent first checks whether an approved asset or a past deck already covers what you asked for — see [Talking to the Agent & Creative Context](/docs/template-slides-agent).
+
 ## What you can do with it
 
-- **Generate decks from a prompt.** "Generate a 10-slide pitch deck for a coffee subscription service, audience is investors."
-- **Edit slides visually** — double-click text to edit, click a block for the bubble menu, use `/` for the slash menu to insert blocks.
-- **Generate images with AI.** Hero images, product mockups, illustrations — preferably delegated to Assets, with Builder-managed image generation ready to enable once deployed and direct provider keys as today's fallback.
-- **Search stock photos and company logos.** "Find the logo for stripe.com and add it to slide 2."
-- **Present full-screen** with keyboard navigation, auto-hiding controls, and speaker notes.
-- **Comment, collaborate, and share.** Multiple people can edit the same deck in real time. Generate a public read-only URL or share with specific teammates.
-- **Import from PDF.** Turn a PDF into a starter deck — the agent parses it and lays out the content.
-- **Import from other formats.** Import PPTX, DOCX, Google Docs, GitHub repos, or any URL as a starting point. Export to PPTX, Google Slides, or HTML.
-- **Apply design systems.** Brand tokens, custom instructions, and default palettes are saved as design systems and applied to new decks.
-- **Restore earlier versions.** Each deck change is snapshotted; list or restore any prior version.
+- **Generate decks from a prompt.** "Generate a 10-slide pitch deck for a coffee subscription service, audience is investors." See [Generating & Editing Decks](/docs/template-slides-editing).
+- **Edit slides visually.** Double-click text to edit, click a block for the bubble menu, use `/` for the slash menu to insert blocks. See [Generating & Editing Decks](/docs/template-slides-editing).
+- **Present full-screen**, comment, collaborate in real time, and share a deck — publicly or with specific teammates. See [Generating & Editing Decks](/docs/template-slides-editing).
+- **Bring in existing content.** Import a PPTX, DOCX, PDF, or Google Doc as a starting point; export to PPTX, Google Slides, or a standalone HTML file. See [Design Systems & Media](/docs/template-slides-design-and-media).
+- **Apply a design system built from your brand.** Save colors, type, and logos once and reuse them on every new deck — set one up from a Figma file, a connected codebase, or a website. See [Design Systems & Media](/docs/template-slides-design-and-media).
+- **Generate images, search stock photos, and look up company logos.** See [Design Systems & Media](/docs/template-slides-design-and-media).
+- **Restore earlier versions.** Every change is snapshotted; list or restore any prior version. See [Generating & Editing Decks](/docs/template-slides-editing).
 
 ## Getting started
 
@@ -91,7 +90,7 @@ When you open the app:
 
 1. Click **New deck**.
 2. Ask the agent: "Generate a 10-slide pitch deck for a coffee subscription service, audience is investors."
-3. Watch slides stream in. Click any slide to edit, or keep asking the agent to refine.
+3. Watch slides stream in. Click any slide to edit, or keep asking the agent to refine. Select text and hit `Cmd+I` to focus the agent on exactly what you highlighted.
 
 ### Useful prompts
 
@@ -100,364 +99,23 @@ When you open the app:
 - "Make the title on this slide bigger and change the accent color to green."
 - "Generate a hero image for the current slide — dark, minimal, cinematic."
 - "Find the logo for stripe.com and add it to slide 2."
-- "Replace the word 'customers' with 'members' everywhere in this deck."
 - "Summarize this PDF as a 6-slide deck." (attach the PDF)
 
-Select text on a slide and hit Cmd+I to focus the agent with that selection — it'll act only on what you selected.
-
-## For developers
-
-The rest of this doc is for anyone forking the Slides template or extending it.
-
-### Quick start
-
-Create a new Slides app from the CLI:
+To scaffold your own copy of Slides:
 
 ```bash
 npx @agent-native/core@latest create my-slides --standalone --template slides
-cd my-slides
-pnpm install
-pnpm dev
-```
-
-### Key features {#key-features}
-
-**Prompt-to-deck generation.** Ask for a deck and the agent streams slides into the editor using the same create and edit actions you can run yourself.
-
-**Editable slide canvas.** Inline text editing, slash inserts, code editing, drag-and-drop ordering, undo/redo, comments, and presentation mode all live in the deck surface.
-
-**Import and export.** Bring in PPTX, DOCX, Google Docs, PDFs, URLs, and GitHub repos; export to PPTX, Google Slides, HTML, or a share link.
-
-**Design systems and media.** Saved brand systems, image generation, stock search, and logo lookup keep decks closer to the intended visual direction.
-
-**Collaboration and history.** Real-time Yjs editing, threaded comments, share roles, and deck version snapshots are built in.
-
-### Working with the agent
-
-The agent chat lives in the sidebar. It can create decks, edit individual slides, generate images, search logos, and navigate the UI — all using the same actions you'd run from the CLI.
-
-#### What the agent sees
-
-When a deck is open, the agent automatically sees:
-
-- The current `deckId` and `slideIndex`.
-- The full list of slides in the open deck.
-- The HTML content of the currently selected slide.
-
-This is injected into every message as a `current-screen` block, so the agent never has to guess what "this slide" means. The data comes from the `navigation` application-state key, which the UI writes on every navigation. See `templates/slides/actions/view-screen.ts`.
-
-#### Selecting text for focused edits
-
-Select text on a slide and hit Cmd+I to focus the agent with that selection pre-loaded. The agent will act only on what you selected.
-
-#### Inline slide previews in chat
-
-The agent can embed a live slide preview directly in a chat reply using the framework's embed fence. It renders a chromeless iframe via `app/routes/slide.tsx` so you can see the result without leaving the conversation.
-
-### Data model
-
-All deck data lives in SQL via Drizzle ORM. Schema: `templates/slides/server/db/schema.ts`.
-
-<DataModel
-  id="doc-block-14y7i30"
-  title="Slides data model"
-  summary={
-    "A deck owns its slides as JSON in decks.data; comments, versions, shares, and design systems hang off it."
-  }
-  entities={[
-    {
-      id: "decks",
-      name: "decks",
-      note: "Slides live as JSON in data; carries ownableColumns",
-      fields: [
-        {
-          name: "id",
-          type: "text",
-          pk: true,
-          note: "e.g. deck-1712345-abc",
-        },
-        {
-          name: "title",
-          type: "text",
-        },
-        {
-          name: "data",
-          type: "text",
-          note: "JSON: { title, slides: [{ id, content, layout }] }",
-        },
-        {
-          name: "created_at",
-          type: "text",
-        },
-        {
-          name: "updated_at",
-          type: "text",
-        },
-      ],
-    },
-    {
-      id: "slide_comments",
-      name: "slide_comments",
-      fields: [
-        {
-          name: "id",
-          type: "text",
-          pk: true,
-        },
-        {
-          name: "deck_id",
-          type: "text",
-          fk: "decks.id",
-        },
-        {
-          name: "slide_id",
-          type: "text",
-          note: "Slide the comment lives on",
-        },
-        {
-          name: "thread_id",
-          type: "text",
-          note: "Threading",
-        },
-        {
-          name: "parent_id",
-          type: "text",
-          nullable: true,
-        },
-        {
-          name: "content",
-          type: "text",
-        },
-        {
-          name: "quoted_text",
-          type: "text",
-          nullable: true,
-        },
-        {
-          name: "author_email",
-          type: "text",
-        },
-        {
-          name: "author_name",
-          type: "text",
-        },
-        {
-          name: "resolved",
-          type: "boolean",
-        },
-      ],
-    },
-    {
-      id: "deck_versions",
-      name: "deck_versions",
-      note: "Point-in-time snapshots for restore",
-      fields: [
-        {
-          name: "deck_id",
-          type: "text",
-          fk: "decks.id",
-        },
-        {
-          name: "title",
-          type: "text",
-        },
-        {
-          name: "data",
-          type: "text",
-          note: "Full deck JSON",
-        },
-        {
-          name: "change_label",
-          type: "text",
-          nullable: true,
-        },
-      ],
-    },
-    {
-      id: "design_systems",
-      name: "design_systems",
-      note: "Reusable brand tokens; ownableColumns",
-      fields: [
-        {
-          name: "data",
-          type: "text",
-          note: "colors / typography / spacing",
-        },
-        {
-          name: "assets",
-          type: "text",
-          nullable: true,
-        },
-        {
-          name: "custom_instructions",
-          type: "text",
-          nullable: true,
-        },
-        {
-          name: "is_default",
-          type: "boolean",
-        },
-      ],
-    },
-    {
-      id: "deck_share_links",
-      name: "deck_share_links",
-      note: "Persisted public share-link snapshots",
-      fields: [
-        {
-          name: "token",
-          type: "text",
-          pk: true,
-        },
-        {
-          name: "title",
-          type: "text",
-        },
-        {
-          name: "slides",
-          type: "text",
-          note: "JSON slides snapshot",
-        },
-        {
-          name: "aspect_ratio",
-          type: "text",
-          nullable: true,
-        },
-        {
-          name: "created_at",
-          type: "text",
-        },
-      ],
-    },
-  ]}
-  relations={[
-    {
-      from: "decks",
-      to: "slide_comments",
-      kind: "1-n",
-      label: "comments",
-    },
-    {
-      from: "decks",
-      to: "deck_versions",
-      kind: "1-n",
-      label: "snapshots",
-    },
-  ]}
-/>
-
-Framework shares tables (`deck_shares`, `design_system_shares`) map principals to viewer / editor / admin roles per resource.
-
-#### decks
-
-| Column       | Type | Notes                                                     |
-| ------------ | ---- | --------------------------------------------------------- |
-| `id`         | text | Primary key, e.g. `deck-1712345-abc`                      |
-| `title`      | text | Deck title                                                |
-| `data`       | text | JSON blob: `{ title, slides: [{ id, content, layout }] }` |
-| `created_at` | text | Timestamp                                                 |
-| `updated_at` | text | Timestamp                                                 |
-
-Each deck also carries the standard `ownableColumns` (owner, visibility, share token) so it slots into the framework's sharing model.
-
-#### slide_comments
-
-| Column                        | Notes                                  |
-| ----------------------------- | -------------------------------------- |
-| `id`                          | Primary key                            |
-| `deck_id`                     | Parent deck                            |
-| `slide_id`                    | Slide the comment lives on             |
-| `thread_id`, `parent_id`      | Threading                              |
-| `content`, `quoted_text`      | Comment body and optional text excerpt |
-| `author_email`, `author_name` | Author                                 |
-| `resolved`                    | Boolean flag                           |
-
-#### deck_shares
-
-Framework-provided shares table (created via `createSharesTable`) that maps principals (users or orgs) to roles (viewer, editor, admin) per deck.
-
-#### deck_versions
-
-Point-in-time snapshots of a deck — `deck_id`, `title`, `data` (full deck JSON), and an optional `change_label`. Used by `list-deck-versions` / `restore-deck-version`.
-
-#### design_systems
-
-Reusable brand tokens — `data` (colors/typography/spacing), `assets`, `custom_instructions`, and an `is_default` flag. Uses `ownableColumns` so design systems can be shared per-user or per-org.
-
-#### design_system_shares
-
-Framework shares table for design systems, mapping principals to roles (viewer, editor, admin).
-
-#### deck_share_links
-
-Persisted public share-link snapshots keyed by `token`. Each row stores a `title`, a JSON `slides` array snapshot, an optional `aspect_ratio`, and `created_at`. Persisting share links here means they survive server restarts and work across serverless instances.
-
-#### Slide structure
-
-Each slide inside `decks.data` is:
-
-```json
-{
-  "id": "slide-1",
-  "layout": "title",
-  "content": "<div class=\"fmd-slide\" style=\"...\">...</div>"
-}
 ```
 
-`content` is raw HTML — the renderer (`app/components/deck/SlideRenderer.tsx`) provides the black background and fixed aspect ratio, and the HTML provides everything inside. Rich embedding is supported too: Excalidraw diagrams via `ExcalidrawSlide.tsx` and Mermaid charts via `MermaidRenderer.tsx`.
-
-### Customizing it {#customizing}
-
-The Slides template is fully forkable. Key places to look when extending it:
-
-#### Actions — `templates/slides/actions/`
-
-Every agent-callable operation lives here as a TypeScript file. A few you'll touch often:
-
-- `create-deck.ts` — new deck from scratch or bulk replace.
-- `add-slide.ts` — append one slide; prefer this for streaming generation.
-- `update-slide.ts` — surgical find/replace or full content swap.
-- `view-screen.ts` — snapshot of what the user sees.
-- `generate-image.ts`, `edit-image.ts`, `image-search.ts`, `logo-lookup.ts` — image tooling.
-- `extract-pdf.ts` — PDF ingestion.
-
-Every action is auto-mounted at `POST /_agent-native/actions/:name` and callable from the CLI as `pnpm action <name>`. Add a new file here to give the agent a new capability.
-
-#### Routes — `templates/slides/app/routes/`
-
-- `_index.tsx` — deck list.
-- `deck.$id.tsx` — the editor.
-- `deck.$id_.present.tsx` — presentation mode.
-- `share.$token.tsx` — public read-only share page.
-- `slide.tsx` — single-slide embed used in chat previews.
-- `settings.tsx` — template settings.
-- `team.tsx` — org and team management.
-
-#### Editor components — `templates/slides/app/components/editor/`
-
-Most UI customization happens here: `SlideEditor.tsx`, `EditorToolbar.tsx`, `EditorSidebar.tsx`, bubble menus, slash menu, and the panels for image generation, search, and history.
-
-#### Skills — `templates/slides/.agents/skills/`
-
-Agent skills that explain patterns when the agent needs to modify code:
-
-- `create-deck/` — how to create a new deck with slides.
-- `slide-editing/` — how to edit individual slides.
-- `deck-management/` — how decks are stored and accessed.
-- `slide-images/` — image generation and search workflow.
-
-#### AGENTS.md
-
-`templates/slides/AGENTS.md` is the short router the agent reads on every conversation. It points at the skills under `.agents/skills/` and lays out the core rules, application-state contract, and skill index. The exact slide HTML templates for every layout live in `.agents/skills/create-deck/SKILL.md` — update that skill whenever you add or change a slide layout pattern.
-
-#### API routes
-
-For cases where actions aren't the right fit (file uploads, streaming), the template exposes a small set of REST endpoints: `GET/POST /api/decks`, `GET/PUT/DELETE /api/decks/:id`. See `templates/slides/server/routes/api/`.
+See [Getting started](/docs/getting-started) for the rest of the setup (`cd`, `pnpm install`, `pnpm dev`) and the framework fundamentals.
 
 ## What's next
 
+- [**Generating & Editing Decks**](/docs/template-slides-editing) — prompts, visual editing, presenting, comments, sharing, and version history
+- [**Design Systems & Media**](/docs/template-slides-design-and-media) — brand tokens, Figma/GitHub indexing, images, and import/export
+- [**Talking to the Agent & Creative Context**](/docs/template-slides-agent) — what the agent sees, prompts by task, and the reuse ladder
+- [**Developer Guide**](/docs/template-slides-developers) — data model, action inventory, routes, and how to extend the template
 - [**Templates**](/docs/cloneable-saas) — the clone-and-own model, and every other domain template to start from
 - [**Getting Started**](/docs/getting-started) — the framework fundamentals: actions, application state, and live sync
-- [**Assets**](/docs/template-assets) — where Slides delegates image generation and brand libraries
 - [**Real-Time Collaboration**](/docs/real-time-collaboration) — the Yjs pipeline decks share with other collaborative surfaces
 - [**Sharing**](/docs/sharing) — the share-grant model decks and design systems build on

package/corpus/core/docs/content/toolkit-capability-packages.mdx

@@ -10,6 +10,15 @@ one Toolkit discovery shelf while staying in separate npm packages, so an app
 only installs the bounded domain model, actions, skills, dependencies, and
 lifecycle metadata it needs.
 
+<WireframeBlock id="doc-block-toolkit-capability-packages">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:460px;box-sizing:border-box;padding:24px;display:flex;flex-direction:column;gap:12px'><div style='display:flex;align-items:center;gap:10px'><h2 style='margin:0'>Capability modules</h2></div><div class='wf-box' style='display:flex;align-items:center;gap:10px'><span data-icon='check'></span><div style='flex:1'><strong>Scheduling</strong><br/><small class='wf-muted'>Booking, availability, calendar/video</small></div><span class='wf-pill'>Installed</span></div><div class='wf-box' style='display:flex;align-items:center;gap:10px'><span data-icon='check'></span><div style='flex:1'><strong>Creative Context</strong><br/><small class='wf-muted'>Governed brand and asset context</small></div><span class='wf-pill'>Installed</span></div><div class='wf-box' style='display:flex;align-items:center;gap:10px'><div style='flex:1'><strong>Pinpoint</strong><br/><small class='wf-muted'>Visual feedback and annotation</small></div><button class='primary'>Add</button></div></div>"
+    }
+  />
+</WireframeBlock>
+
 ## Current package boundary
 
 | Package                          | Toolkit module                                      | Lifecycle                                                                                               |
@@ -23,30 +32,46 @@ These modules belong to the Toolkit brand without being folded into the
 where present, `docs/` bundle and `agent-native.package.json` lifecycle manifest
 as the source of truth for setup, contribution points, and ownership.
 
-Dispatch is the workspace control plane and remains a separate product.
-
 - [Scheduling package docs](https://github.com/BuilderIO/agent-native/tree/main/packages/scheduling/docs)
 - [Creative Context package docs](https://github.com/BuilderIO/agent-native/tree/main/packages/creative-context/docs)
 - [Pinpoint package README](https://github.com/BuilderIO/agent-native/tree/main/packages/pinpoint)
 
+## Package maturity and ownership {#package-maturity-and-ownership}
+
+- Scheduling, Creative Context, and Pinpoint are **Toolkit capability modules,
+  installed on demand**. They stay in separate npm packages so each domain can
+  keep an independent lifecycle manifest, dependency graph, and release
+  cadence, instead of being folded into `@agent-native/toolkit`.
+- Dispatch is the workspace control plane and remains a **separate product**,
+  not a Toolkit capability module.
+
+## Pieces {#pieces}
+
+| Package                          | Contributes                                                                                                                                                                  | Manifest                                                                          |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `@agent-native/scheduling`       | 66 actions (event types, availability, bookings, calendar/video integrations, team scheduling, workflows, routing forms), 11 packaged skills, 10 optional OAuth/API secrets. | Generic `agent-native.package.json`; supports `agent-native package add`/`eject`. |
+| `@agent-native/creative-context` | 35 actions (context packs, sources, brand DNA, canonical logo, embeddings), 1 packaged skill, 13 optional OAuth/API secrets.                                                 | Generic `agent-native.package.json`; supports `agent-native package add`/`eject`. |
+| `@agent-native/pinpoint`         | Visual feedback and annotation: element selection, structured feedback, agent handoff.                                                                                       | No generic manifest yet — install and wire up from its README.                    |
+
 ## Lifecycle manifests
 
 Each manifest describes static contributions such as actions, schema entry
-points, skills, required secret names, and peer providers. Inspect before
-writing, then use the explicit apply step:
+points, skills, required secret names, and peer providers. Inspect a package
+before installing it:
 
 ```bash
 agent-native package inspect @agent-native/scheduling
-agent-native package add @agent-native/scheduling --apply
-agent-native package eject @agent-native/scheduling --apply
 ```
 
-See [Package Lifecycle](/docs/package-lifecycle) for the safety, dry-run, and
-eject rules. See [Scheduling](/docs/template-calendar) for a product-level
-example; it is not a substitute for the package-local contract.
+See [Package Lifecycle](/docs/package-lifecycle) for the full `add`, `eject`,
+dry-run, and safety rules — the same commands apply to
+`@agent-native/creative-context`. See [Scheduling](/docs/template-calendar) for
+a product-level example; it is not a substitute for the package-local
+contract.
 
-## Related docs
+## What's next
 
-- [Toolkit overview](/docs/agent-native-toolkit) — the unified discovery shelf.
-- [Package Lifecycle](/docs/package-lifecycle) — manifest inspection, add, and eject.
-- [Recurring jobs](/docs/recurring-jobs) — runtime scheduling is different from the Scheduling package.
+- [**Package Lifecycle**](/docs/package-lifecycle) — the `inspect`, `add`, and
+  `eject` mechanics shared by every capability module.
+- [**Toolkit overview**](/docs/agent-native-toolkit) — the unified discovery shelf.
+- [**Recurring jobs**](/docs/recurring-jobs) — runtime scheduling is different from the Scheduling package.

package/corpus/core/docs/content/toolkit-context-knowledge.mdx

@@ -9,6 +9,15 @@ Context and knowledge are shared responsibilities: the runtime makes state and
 access durable, Toolkit presents reusable surfaces, and each app owns the
 domain records that make context useful.
 
+<WireframeBlock id="doc-block-toolkit-context-knowledge">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:520px;box-sizing:border-box;padding:24px;display:grid;grid-template-columns:1fr 260px;gap:16px'><main class='wf-card' style='display:flex;flex-direction:column;gap:12px'><div style='display:flex;align-items:center;gap:10px'><h2 style='margin:0'>Context X-Ray</h2><div style='flex:1'></div><span class='wf-pill'>24.6K / 128K tokens</span></div><div class='wf-box' style='display:flex;align-items:center;gap:8px'><span data-icon='lock'></span><div style='flex:1'>System &middot; ordered, not evictable</div><small class='wf-muted'>6.1K</small></div><div class='wf-box' style='display:flex;align-items:center;gap:8px;border-color:var(--wf-accent)'><span data-icon='check'></span><div style='flex:1'>Pinned &middot; roadmap.md</div><small class='wf-muted'>1.2K</small></div><div class='wf-box' style='display:flex;align-items:center;gap:8px'><div style='flex:1'>Conversation &middot; last 12 turns</div><small class='wf-muted'>14.8K</small></div><div class='wf-box' style='display:flex;align-items:center;gap:8px;opacity:.55'><span data-icon='x'></span><div style='flex:1'>Evicted &middot; old tool output</div><small class='wf-muted'>2.5K</small></div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Budget</strong><div style='height:120px;border-radius:8px;background:var(--wf-accent-soft);display:flex;align-items:center;justify-content:center'><strong>48%</strong></div><small class='wf-muted'>Share of the context window used by system, conversation, tool results, and evicted segments.</small><div style='flex:1'></div><button class='primary'>Pin selection</button></aside></div>"
+    }
+  />
+</WireframeBlock>
+
 ## Ownership boundary
 
 | Layer   | Owns                                                                                       |
@@ -21,10 +30,38 @@ The Context X-Ray engine remains Core-owned. Use Toolkit presentation to show
 that context consistently, but keep the actual app-state and access decisions
 on the Core/action surface.
 
-Import the controlled presentation views from `@agent-native/toolkit/context-ui`.
-Core's existing Context X-Ray components remain adapters that connect those
-views to runtime state and mutations. Both are documented in this Toolkit
-section because together they form one reusable product surface.
+## Pieces {#pieces}
+
+| Piece                                                        | Purpose                                                                 |
+| ------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| `<ContextXRayPanelView>`                                     | Complete panel: grouped segments, budget meter, pin/evict/restore rows. |
+| `<ContextMeterView>`                                         | Compact token-budget donut with a popover breakdown.                    |
+| `<ContextTreemapView>`                                       | Treemap of context usage by segment group and size.                     |
+| `<ContextSegmentRowView>` / `<SegmentProvenancePopoverView>` | One segment row and its provenance popover (source, tokens, status).    |
+| `formatContextTokens()`                                      | Shared token-count formatting (for example `24.6K`).                    |
+
+## Usage {#usage}
+
+Import the presentation views from `@agent-native/toolkit/context-ui` and feed
+them your own manifest data:
+
+```tsx
+import {
+  ContextMeterView,
+  ContextXRayPanelView,
+  formatContextTokens,
+} from "@agent-native/toolkit/context-ui";
+```
+
+Core wraps `ContextXRayPanelView` in its own `ContextXRayPanel`
+(`packages/core/src/client/context-xray/ContextXRayPanel.tsx`), which resolves
+the context window for the active model and wires pin/evict/restore to the
+`context-manifest-get`, `context-pin`, `context-evict`, and `context-restore`
+agent actions. That wrapper is not a published standalone import today — it
+renders only inside the built-in agent chat (`AssistantChat`). Build a custom
+context surface by composing the `context-ui` views directly against your own
+app-state reads and the same agent actions, rather than expecting a public
+Core adapter entry point.
 
 ## Build a useful context surface
 
@@ -38,9 +75,12 @@ For knowledge that comes from a provider, preserve provider credentials and
 resource access checks before exposing retrieval to the agent. Do not treat a
 presentation component as an authorization boundary.
 
-## Related docs
+## What's next
 
-- [Agent UX](/docs/toolkit-agent-ux) — composer context chips, approvals, and runs.
-- [Resources](/docs/toolkit-resources) — resource trees, search, and attachments.
-- [Context awareness](/docs/context-awareness) — application state shared with the agent.
-- [Security](/docs/security) — scoped access and credential handling.
+- [**Context Awareness**](/docs/context-awareness) — the navigation, selection,
+  and app-state contract these views present.
+- [**Agent UX**](/docs/toolkit-agent-ux) — composer context chips, approvals,
+  and the runs tray.
+- [**Resources**](/docs/toolkit-resources) — resource trees, search, and
+  attachments the agent can read.
+- [**Security**](/docs/security) — scoped access and credential handling.