Assets

Asset fields store a reference, not the bytes:

image: field.asset({ optional: true }),
// → { key: string, alt?: string }

Keys are lowercase paths. .. segments are invalid.

Upload

CLI

graft asset put ./hero.svg pages/home/hero.svg

The command prints a frontmatter snippet. Content type is inferred from the file.

MCP

put_asset accepts:

Input	When
path	File on the machine running stdio MCP
base64 + key	Remote agents

Existing keys refuse without overwrite: true. The store keeps no history.

Frontmatter

---
title: Home
image:
  key: pages/home/hero.svg
  alt: Branch grafted onto a trunk
---

Resolve URLs in the app

@usegraft/assets exposes url(key) / presignGet. Prefer a public base (S3_PUBLIC_URL) when you have one; otherwise use a short-lived signed GET.

Compile indexes populated asset fields on each projected document so agents and search can see which keys a page uses.

Env

See Configuration for S3_BUCKET, S3_ENDPOINT, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, and S3_PUBLIC_URL.