@agent-native/core 0.122.4 → 0.123.0

package/docs/content/template-assets-developers.mdx

@@ -0,0 +1,456 @@
+---
+title: "Assets — architecture and data model"
+description: "The SQL schema, access-control model, and action reference for developers forking or extending the Assets template."
+---
+
+# Assets — architecture and data model
+
+This page is for anyone forking the [Assets](/docs/template-assets) template or extending it: the action inventory, data model, access-control rules, and the places to start when you want to change how Assets works.
+
+## Quick start
+
+Create a new workspace with the Assets template:
+
+```bash
+npx @agent-native/core@latest create my-assets --standalone --template assets
+```
+
+See [Getting Started](/docs/getting-started) for the rest of the local setup (`cd`, `pnpm install`, `pnpm dev`).
+
+## Action reference
+
+Every operation is a TypeScript file in `templates/assets/actions/`, auto-mounted at `POST /_agent-native/actions/:name`.
+
+**Libraries & organization**
+
+- `list-libraries` / `match-library` — find or disambiguate a brand kit
+- `create-library` / `update-library` / `archive-library` / `unarchive-library` / `delete-library` — kit lifecycle
+- `duplicate-library` — a private, current-user-owned copy with contents remapped; shares, visibility, generation runs, and handoff sessions are not copied
+- `list-library-presets` / `create-library-from-preset` — start from a default look instead of a blank kit
+- `create-collection` / `update-collection` — optional style/category groupings inside a kit
+- `create-folder` / `update-folder` / `delete-folder` — nestable folders
+
+**Assets**
+
+- `list-assets` / `search-assets` — browse or search by title, description, alt text, prompt, model, media type, status, role, folder, or collection
+- `get-asset` / `describe-asset` / `update-asset` — read and edit one asset record
+- `delete-asset` / `delete-assets` — single or bulk delete
+- `import-asset-from-url` — ingest an external HTTPS image as a reference asset with `sourceUrl` provenance
+- `set-canonical-logo` — pin the kit's pixel-perfect logo (flips the asset's `role` to `logo_reference` and `status` to `reference`)
+- `export-asset` / `export-image` — return a download URL or artifact for another app
+
+**Generation presets**
+
+- `list-generation-presets` — list a kit's saved recipes before generating
+- `create-generation-preset` / `update-generation-preset` / `delete-generation-preset` — author format, model, aspect ratio, text/reference policy, `includeLogo`, and `skeletonSpec`
+- `analyze-collection-style` — vision-based brand analysis (palette, composition, lighting) when a collection is underspecified
+- `extract-palette-from-references` — derive a color palette from reference assets
+
+**Generating & iterating**
+
+- `generate-image` / `generate-image-batch` — synchronous image generation: one asset, or several stable-`slotId` candidates in one call
+- `generate-video` — asynchronous video generation; poll `refresh-generation-run`
+- `refine-image` / `edit-image` / `restyle-image` — iterate on an existing asset by feedback, a targeted edit, or a subject-preserving restyle
+- `generate-asset` — human-in-the-loop generation that returns the inline picker
+- `rerun-generation-run` — rerun an older run's prompt and settings against the current library style
+- `get-generation-run` / `refresh-generation-run` — poll a run (video only; image calls are synchronous)
+- `variant-slots` / `dismiss-variant-slots` — back the shared live generation tray (`asset-variants` app state)
+
+**Sessions & handoff**
+
+- `create-generation-session` / `update-generation-session` / `get-generation-session` / `list-generation-sessions` — designer handoff carrying the brief, preset, active asset, feedback, and run lineage
+- `prepare-generation-session-continuation` — preload a fresh chat with a session's handoff context
+
+**Picker & navigation**
+
+- `open-asset-picker` — browse, search, or pick in the embedded picker, or drive its own generation
+- `navigate` / `view-screen` — move the UI to a picker, library, generation, or preset surface, or read current navigation and selection
+
+**Audit (org-admin)**
+
+- `is-audit-admin` — cheap check the UI polls to show or hide the Audit Log nav link
+- `list-audit-runs` / `get-audit-run` — paginated feed and full run detail, scoped to the caller's org (or their own runs in single-user mode)
+- `export-audit-csv` — bulk CSV export of filtered runs to a presigned download URL
+
+**Creative Context** (shared `@agent-native/creative-context` package, mounted into Assets — see [Cross-app Creative Context reuse](/docs/template-assets-integrations#cross-app-creative-context-reuse))
+
+- `search-creative-context` / `get-context-item` / `record-context-feedback` — retrieval and feedback verbs shared across every app that mounts `setupCreativeContext`
+- `manage-context-membership` — submit an Assets asset into a governed Context, pinning immutable bytes and metadata
+- `clone-creative-context-asset` — Assets-specific: copy approved governed media into an editable library without exposing the private blob handle
+
+## Data model
+
+All data lives in SQL via Drizzle ORM (binary media lives in object storage, or the local file-upload fallback during development). Schema: `templates/assets/server/db/schema.ts`. Libraries carry the standard `ownableColumns` and a matching framework shares table, so they slot into the per-user / per-org sharing model.
+
+Note: the SQL table names keep the legacy `image_*` prefix from when the app was called Images. They cover videos and other media too.
+
+| Table                            | What it holds                                                                                                                                                                            |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `image_libraries`                | A library — the top-level container grouped by brand, campaign, product, or category. Holds `custom_instructions`, `style_brief`, canonical logo and cover asset refs, and archive state |
+| `image_library_shares`           | Framework shares table mapping principals (users or orgs) to roles (viewer, editor, admin) per library                                                                                   |
+| `image_collections`              | Style/category groupings inside a library — `style_brief`, `prompt_template`, default aspect ratio and image size                                                                        |
+| `asset_folders`                  | Nestable folders inside a library (`parent_id` for hierarchy)                                                                                                                            |
+| `image_generation_presets`       | Saved generation recipes — media type, prompt template, aspect ratio, model, and text/reference policy                                                                                   |
+| `image_generation_sessions`      | An iterative generate-and-choose session with a brief, status, active asset, and feedback summary                                                                                        |
+| `image_generation_session_items` | Candidate assets within a session, each with a role and note                                                                                                                             |
+| `image_assets`                   | The asset record — media type, role, status, title/description/alt text, prompt, model, dimensions, MIME type, object/thumbnail keys, and lineage                                        |
+| `image_generation_runs`          | The generation audit log — prompt, compiled prompt, model, references, status, errors, and the `source` (`chat` / `ui` / `a2a`) that triggered it                                        |
+
+<DataModel
+  id="doc-block-assets10"
+  title="Assets data model"
+  summary={
+    "Libraries are the ownable container; collections, folders, and presets organize them. Sessions drive generate-and-choose; assets and runs hold output and the audit log. Table names keep the legacy image_* prefix but cover all media."
+  }
+  entities={[
+    {
+      id: "library",
+      name: "image_libraries",
+      note: "Top-level ownable container",
+      fields: [
+        {
+          name: "id",
+          type: "id",
+          pk: true,
+        },
+        {
+          name: "custom_instructions",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "style_brief",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "logo_asset_id",
+          type: "id",
+          fk: "image_assets.id",
+          nullable: true,
+        },
+        {
+          name: "archived",
+          type: "boolean",
+        },
+      ],
+    },
+    {
+      id: "library_shares",
+      name: "image_library_shares",
+      note: "Framework shares table",
+      fields: [
+        {
+          name: "library_id",
+          type: "id",
+          fk: "image_libraries.id",
+        },
+        {
+          name: "role",
+          type: "text",
+          note: "viewer / editor / admin",
+        },
+      ],
+    },
+    {
+      id: "collections",
+      name: "image_collections",
+      note: "Style/category groupings",
+      fields: [
+        {
+          name: "library_id",
+          type: "id",
+          fk: "image_libraries.id",
+        },
+        {
+          name: "style_brief",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "prompt_template",
+          type: "text",
+          nullable: true,
+        },
+      ],
+    },
+    {
+      id: "folders",
+      name: "asset_folders",
+      note: "Nestable folders",
+      fields: [
+        {
+          name: "library_id",
+          type: "id",
+          fk: "image_libraries.id",
+        },
+        {
+          name: "parent_id",
+          type: "id",
+          fk: "asset_folders.id",
+          nullable: true,
+        },
+      ],
+    },
+    {
+      id: "presets",
+      name: "image_generation_presets",
+      note: "Saved generation recipes",
+      fields: [
+        {
+          name: "media_type",
+          type: "text",
+        },
+        {
+          name: "prompt_template",
+          type: "text",
+        },
+        {
+          name: "model",
+          type: "text",
+        },
+      ],
+    },
+    {
+      id: "sessions",
+      name: "image_generation_sessions",
+      note: "Iterative generate-and-choose",
+      fields: [
+        {
+          name: "id",
+          type: "id",
+          pk: true,
+        },
+        {
+          name: "status",
+          type: "text",
+        },
+        {
+          name: "active_asset_id",
+          type: "id",
+          fk: "image_assets.id",
+          nullable: true,
+        },
+      ],
+    },
+    {
+      id: "session_items",
+      name: "image_generation_session_items",
+      note: "Candidate assets in a session",
+      fields: [
+        {
+          name: "session_id",
+          type: "id",
+          fk: "image_generation_sessions.id",
+        },
+        {
+          name: "asset_id",
+          type: "id",
+          fk: "image_assets.id",
+        },
+        {
+          name: "role",
+          type: "text",
+        },
+      ],
+    },
+    {
+      id: "assets",
+      name: "image_assets",
+      note: "The asset record",
+      fields: [
+        {
+          name: "id",
+          type: "id",
+          pk: true,
+        },
+        {
+          name: "media_type",
+          type: "text",
+          note: "image / video",
+        },
+        {
+          name: "status",
+          type: "text",
+        },
+        {
+          name: "prompt",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "object_key",
+          type: "text",
+          nullable: true,
+        },
+      ],
+    },
+    {
+      id: "runs",
+      name: "image_generation_runs",
+      note: "Generation audit log",
+      fields: [
+        {
+          name: "model",
+          type: "text",
+        },
+        {
+          name: "status",
+          type: "text",
+        },
+        {
+          name: "source",
+          type: "text",
+          note: "chat / ui / a2a",
+        },
+      ],
+    },
+  ]}
+  relations={[
+    {
+      from: "library",
+      to: "collections",
+      kind: "1-n",
+    },
+    {
+      from: "library",
+      to: "folders",
+      kind: "1-n",
+    },
+    {
+      from: "library",
+      to: "assets",
+      kind: "1-n",
+    },
+    {
+      from: "sessions",
+      to: "session_items",
+      kind: "1-n",
+    },
+    {
+      from: "library",
+      to: "library_shares",
+      kind: "1-n",
+    },
+  ]}
+/>
+
+## Access control
+
+`image_libraries` carries `ownableColumns()` plus its own shares table
+(`image_library_shares`), so it slots into the standard visibility model
+(`private` / `org` / `public`) and the framework `share-resource`,
+`unshare-resource`, and `set-resource-visibility` actions with
+`resourceType: "asset-library"` (the legacy `image-library` alias remains
+registered for existing grants).
+
+`image_assets`, `image_collections`, and `image_generation_runs` do **not**
+carry `ownableColumns` themselves — they inherit access from their parent
+`library_id`:
+
+- **List queries** filter by `accessFilter(schema.assetLibraries, schema.assetLibraryShares)` to resolve the caller's accessible library ids first, then query children by those ids.
+- **Read by id** calls `resolveAccess("asset-library", libraryId)` — wrapped by the `requireLibrary(id)` helper in `actions/_helpers.ts`.
+- **Write** calls `assertAccess("asset-library", libraryId, "editor")` for updates and inserts, `"admin"` for deletes.
+
+Every action that touches an ownable resource resolves `libraryId` first, then
+asserts against the parent library — never query `image_assets` without also
+pinning `library_id` to a value the caller has access to.
+
+`delete-library` cascades through generation sessions, session items, presets,
+assets, runs, collections, and folders before removing the library and its
+shares. The underlying storage objects are not reaped (a v2 background job);
+this is tolerable today because every asset URL still checks access through
+its row, not the object key.
+
+The schema is strictly additive — hosted templates share their production
+database across every deploy context, so add columns via
+`ALTER TABLE ... ADD COLUMN IF NOT EXISTS ...` in a new migration version in
+`server/plugins/db.ts`; never rename or drop a column, and never run
+`drizzle-kit push` against production. See [Database](/docs/database#migrations)
+for the full migration pattern.
+
+## Customizing it
+
+Assets is a complete, cloneable template. Some practical extension ideas:
+
+- "Add a product catalog connector so product reference shots can be selected by SKU."
+- "Add a strict approval queue before generated assets are marked usable for marketing."
+- "Add a brand review dashboard that filters failed or low-rated generations by model."
+- "Create a workspace-wide default asset library and route Slides image generation through it."
+- "Add a new provider behind the image generation interface after checking the latest provider docs."
+
+The agent edits routes, components, actions, skills, and SQL-backed models as
+needed:
+
+<FileTree
+  id="doc-block-assets11"
+  title="Where to look when forking Assets"
+  entries={[
+    {
+      path: "templates/assets/server/db/schema.ts",
+      note: "Drizzle schema — image_libraries, image_assets, image_generation_runs, and the rest",
+    },
+    {
+      path: "templates/assets/actions/create-library.ts",
+      note: "Library CRUD — the pattern every ownable-resource action follows",
+    },
+    {
+      path: "templates/assets/actions/generate-image.ts",
+      note: "The core single-asset generation entry point",
+    },
+    {
+      path: "templates/assets/actions/generate-image-batch.ts",
+      note: "Multi-slot generation used by the UI tray and A2A callers",
+    },
+    {
+      path: "templates/assets/actions/_helpers.ts",
+      note: "Shared access-check helpers — requireLibrary, requireLibraryAccess",
+    },
+    {
+      path: "templates/assets/actions/list-audit-runs.ts",
+      note: "Org-scoped audit feed — the pattern for any org-admin-only action",
+    },
+    {
+      path: "templates/assets/.agents/skills/library-management/SKILL.md",
+      note: "Schema, CRUD, sharing, and cascade-delete rules",
+    },
+    {
+      path: "templates/assets/.agents/skills/logo-composite/SKILL.md",
+      note: "The generate-then-composite pipeline and preset skeletons",
+    },
+    {
+      path: "templates/assets/.agents/skills/creative-context/SKILL.md",
+      note: "The cross-app reuse ladder and context opt-out contract",
+    },
+    {
+      path: "templates/assets/agent-native.app-skill.json",
+      note: "Distribution manifest — hosted URL, MCP server name, exported skills, host adapters",
+    },
+  ]}
+/>
+
+See [Templates](/docs/cloneable-saas) for the full clone, customize, deploy flow, and [A2A Protocol](/docs/a2a-protocol) for cross-app generation.
+
+## Distributing the app skill
+
+`agent-native.app-skill.json` at the template root is the distribution
+manifest: it declares the app id (`assets`), the hosted app and MCP URLs, the
+MCP server name, which `.agents/skills/*` directories export (and under what
+name — `asset-generation` exports as `assets`, while `creative-context`,
+`image-generation`, and `a2a-assets` stay internal-only), the `/picker` MCP App
+surface, and the list of `hostAdapters` (`codex-plugin`, `claude-marketplace`,
+`vercel-skills`, `plain-skill`, `claude-skill`, `chatgpt-mcp`, `generic-mcp`)
+to generate packages for.
+
+For the install commands, the packed bundle's folder layout, and how an
+external host actually calls the picker or generation actions, see
+[Installing the Assets skill in a coding agent](/docs/template-assets-integrations#installing-the-assets-skill-in-a-coding-agent)
+on the integrations page.
+
+## What's next
+
+- [**Using Assets from other apps and agents**](/docs/template-assets-integrations) — embedding, A2A, Creative Context, and the packaged skill bundle
+- [**Sharing & Privacy**](/docs/sharing#building) — `ownableColumns()` and the visibility model this template relies on
+- [**Database**](/docs/database) — migrations, dialects, and `getDb`/`schema`
+- [**Actions**](/docs/actions#access-control) — the action system powering every entry above
+- [**Assets**](/docs/template-assets) — back to the overview

package/docs/content/template-assets-generation.mdx

@@ -0,0 +1,147 @@
+---
+title: "Generating, refining, and reviewing assets"
+description: "How to generate image and video candidates from chat or a library, iterate on a candidate with feedback, hand work off to a designer, and review every run in the admin audit log."
+---
+
+# Generating, refining, and reviewing assets
+
+This page is for anyone using [Assets](/docs/template-assets) day to day: asking for media, picking and refining a candidate, and — for admins — reviewing what was generated and by whom.
+
+## Generate through chat or a library
+
+Ask for what you want in plain language, from the home composer or from inside
+a library's Generate controls: "three homepage hero options," "a square social
+image in the launch-campaign style," "a video storyboard for the onboarding
+flow." The message goes to the agent, which chooses references, a model, and
+(when one matches) a preset, then returns candidates you can inspect, give
+feedback on, and iterate on before anything is kept.
+
+If you want the same brief across several destinations at once — three social
+sizes, four slide backgrounds — ask for that directly ("give me a version for
+each of these four slides") and Assets generates one candidate per destination
+in a single pass instead of one request at a time.
+
+## Iterate on a candidate
+
+Once you have a candidate, keep going in the same conversation:
+
+- **Give feedback** on a saved image and ask for a revision — "make it darker,"
+  "move the subject to the right." Assets keeps the prior image as a reference
+  and links the new candidate back to the source, so lineage is never lost.
+- **Ask for a small, targeted edit** rather than a full regeneration — "remove
+  the text in the corner," "fix the hand." This preserves everything else in
+  the image.
+- **Restyle while keeping the exact subject** — "put this product photo in our
+  brand style" — when you want the library's look applied without changing
+  what's actually in the shot.
+
+## Logo accuracy in plain language
+
+Image models are good at scenes and bad at logos — they smear gradients, drop
+letters, and rearrange elements. Assets sidesteps this: when logo compositing
+is on, the agent leaves a clean, empty area in the image instead of asking the
+model to draw the logo, and the server stamps your library's actual uploaded
+logo into that space afterward, pixel-perfect. The model never touches the
+logo itself. This is a setting on the preset (or a one-off override for a
+single generation) — see [Presets: design once, run everywhere](/docs/template-assets-presets#designers-build-one-preset-per-use-case) for how it's configured.
+
+The same idea extends to a locked layout: a preset can carry a fixed brand
+plate — a background image with an open region — so a webinar template's
+header, framing, and logo survive every run untouched while only the open
+region changes.
+
+## Hand off to a designer
+
+When someone else should keep working on a piece, ask the agent to hand it
+off: "have a designer continue this." Assets creates a handoff session that
+carries the brief, the chosen preset, the active candidate, your feedback so
+far, and every run that led up to it. The designer can pick the work back up
+in a fresh chat preloaded with that context, instead of replaying the whole
+conversation or guessing at what was tried already.
+
+<Diagram id="doc-block-assets5" title="Candidate generation loop" summary={"A brief produces several candidates; feedback and iteration narrow to a chosen asset that lands in the library. Every run — kept or not — is written to the audit log."}>
+
+```html
+<div class="diagram-genloop">
+  <div class="diagram-node">
+    Brief<br /><small class="diagram-muted">chat or Generate controls</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    <span class="diagram-pill accent">N candidates</span
+    ><small class="diagram-muted">refine · edit · restyle</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-col">
+    <div class="diagram-node">
+      Feedback<br /><small class="diagram-muted"
+        >"make it darker", "try square"</small
+      >
+    </div>
+    <div class="diagram-node">
+      Chosen asset<br /><small class="diagram-muted">saved to library</small>
+    </div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    <span class="diagram-pill">Audit Log</span
+    ><small class="diagram-muted">every run, always recorded</small>
+  </div>
+</div>
+```
+
+```css
+.diagram-genloop {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-genloop .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-genloop .diagram-box {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+.diagram-genloop .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## The generation audit log
+
+Every generation — kept, discarded, or failed — is recorded automatically:
+the prompt, the compiled prompt actually sent to the model, the model and
+aspect ratio used, the references it drew on, who ran it and from where (chat,
+the UI, or another app over A2A), and every asset it produced.
+
+Org admins (or, in single-user local mode, anyone reviewing their own runs) see
+an **Audit Log** link in the sidebar. It opens a filterable list — by date
+range, owner, library, model, status, source, or a prompt search — with a
+detail view per run showing its full references, generated children, and
+(for a refinement) the parent run it came from. An **Export CSV** button
+bulk-exports the filtered runs to a downloadable file, useful for a design
+team reviewing quality by model, app, or prompt pattern across everything
+generated.
+
+<WireframeBlock id="doc-block-assets6">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='display:flex;flex-direction:column;gap:14px;padding:18px;min-height:520px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>Audit Log</h1><span class='wf-pill accent'>Org admin</span><div style='flex:1'></div><button>Export CSV</button></div><div class='wf-card' style='display:flex;gap:8px;flex-wrap:wrap'><span class='wf-pill'>Date range</span><span class='wf-pill'>Owner</span><span class='wf-pill'>Model</span><span class='wf-pill'>Status</span><span class='wf-pill'>Source</span><span class='wf-pill'>Prompt search</span></div><div class='wf-card' style='display:flex;flex-direction:column;gap:8px;flex:1'><div style='display:grid;grid-template-columns:2fr 1fr 1fr 1fr 1fr;gap:8px;border-bottom:1px solid var(--wf-line);padding-bottom:6px'><span class='wf-muted'>Prompt</span><span class='wf-muted'>Library</span><span class='wf-muted'>Model</span><span class='wf-muted'>Source</span><span class='wf-muted'>Status</span></div><div style='display:grid;grid-template-columns:2fr 1fr 1fr 1fr 1fr;gap:8px'><span>Three blog hero options</span><span>Acme Brand</span><span>gpt-image-2</span><span class='wf-pill'>chat</span><span class='wf-pill accent'>completed</span></div><div style='display:grid;grid-template-columns:2fr 1fr 1fr 1fr 1fr;gap:8px'><span>Webinar LinkedIn ad</span><span>Acme Brand</span><span>gpt-image-2</span><span class='wf-pill'>a2a · slides</span><span class='wf-pill accent'>completed</span></div><div style='display:grid;grid-template-columns:2fr 1fr 1fr 1fr 1fr;gap:8px'><span>Product cutout render</span><span>Launch Campaign</span><span>gpt-image-1</span><span class='wf-pill'>ui</span><span class='wf-pill warn'>failed</span></div></div></div>"
+    }
+  />
+</WireframeBlock>
+
+## What's next
+
+- [**Presets: design once, run everywhere**](/docs/template-assets-presets) — build the recipe once so this workflow needs no settings
+- [**Using Assets from other apps and agents**](/docs/template-assets-integrations) — the embedded picker, A2A, and Creative Context reuse
+- [**Assets**](/docs/template-assets) — back to the overview