Images & assets

Images and other binaries are committed to the same GitHub repo that hosts the document and referenced with a relative path (![alt](../assets/x.webp)), so they render on GitHub, Obsidian, Foam and any Markdown viewer — with no expiring URLs.

Why not paste base64?

A naïve “upload” tool makes the model emit the file as base64, token by token — slow, expensive, and easy to corrupt. Blenau avoids this entirely: the bytes travel straight to Blenau over HTTP and never pass through the language model.

The optimal flow (agents)

1. Call create_asset_upload(doc_path, filename). It returns a short-lived upload_url (and the size limit + compression guidance) — not a request for the file content.

2. Transfer the local file with one shell command:

   curl -F file=@./diagram.webp "<upload_url>"

3. The response carries the ready-to-paste markdown and the commit_sha.

To embed the image into the document in the same step, add form fields:

curl -F file=@./diagram.webp \
     -F alt_text="Settings screen" \
     -F insert_heading="## Setup" \
     -F insert_position=after \
     "<upload_url>"

insert_position is one of after · before · append · prepend. Blenau splices the image cleanly under the heading you choose and re-commits the doc, so GitHub stays the source of truth and the document layout stays tidy.

The optimal flow (CLI)

The CLI holds your token, so it uploads directly:

blenau assets upload ./diagram.webp \
  --doc "emboux/setup/odoo-sync.md" \
  --alt "Settings screen" \
  --insert-at "## Setup" --position after

Add --compress to auto-optimize an oversized image before upload (uses magick or cwebp if present).

Size limit & compression

Assets live in git history forever, so they must stay small. The limit is 1 MB. If your image is larger, optimize it locally before uploading — never read the file into the model’s context, just run a shell tool:

# ImageMagick (any input):
magick input.png -resize '1600x1600>' -quality 80 output.webp

# cwebp (lightweight, WebP only):
cwebp -q 80 -resize 1600 0 input.png -o output.webp

# pngquant (keep PNG):
pngquant --quality=60-80 input.png

Install ImageMagick: macOS brew install imagemagick · Windows winget install ImageMagick.ImageMagick · Debian/Ubuntu apt install imagemagick. A well-optimized WebP at 1600px wide is typically 50–200 KB — comfortably under the limit.

Good to know

• Content-addressed names. Stored assets are named assets/<sha8>-<name>, so two different images called screenshot.png never collide, and re-uploading the same bytes deduplicates automatically.
• Legacy base64 path. A base64 upload_asset tool still exists but is capped at 64 KB — use it only for tiny inline icons (e.g. a small SVG). For everything else, use create_asset_upload / blenau assets upload.