# Markloom Agent Guide

Markloom is a static visual review board for AI-assisted UI feedback.

The landing page is for humans. Agents should use the current entrypoint at:

```text
https://markloom.satoapps.com/start.md
```

Primary use case: open one app screenshot, mark exact fixes on it, then copy the board image back to an LLM or review thread. Side-by-side reference images are supported, but optional.

Always re-read this guide before using Markloom. The board and skill may change without breaking the URL, and this page is the current source of truth.

## Quick Start

Open:

```text
https://markloom.satoapps.com/board/
```

For a first-time user, start with the agent entrypoint:

```text
https://markloom.satoapps.com/start.md
```

The intended onboarding flow is:

1. The user pastes a tiny prompt into their AI agent or the agent finds the entrypoint link on the LP.
2. The agent reads `/start.md`, then this guide if detailed board rules are needed.
3. The agent captures, requests, or prepares one app screenshot.
4. The agent opens or prepares a Markloom board with that screenshot.
5. The user marks visual feedback and copies the board image back.
6. The agent summarizes the concrete UI changes before implementing.
7. The agent tells the user that next time they can say: `Review this screen with Markloom.`
8. The agent asks whether to install or update the Markloom skill.

To preload images, pass a base64url JSON payload in the hash:

```text
https://markloom.satoapps.com/board/#data=<base64url(JSON)>
```

Minimal one-screenshot payload:

```json
{
  "title": "App Screen Review",
  "storageKey": "app-screen-review-20260605",
  "pairs": [
    {
      "id": "home",
      "image": "https://example.com/home-screen.png"
    }
  ]
}
```

With an optional reference image:

```json
{
  "title": "App Screen Review",
  "storageKey": "app-screen-review-20260605",
  "pairs": [
    {
      "id": "home",
      "title": "Home Screen",
      "image": "https://example.com/current.png",
      "reference": "https://example.com/reference.png",
      "imageLabel": "Screenshot",
      "referenceLabel": "Reference"
    }
  ]
}
```

If only one image is provided, the board shows it centered. Image labels and section titles are optional.

Supported pair fields:

- `id`: stable board id
- `title`: optional section title
- `image`, `src`, or `url`: primary screenshot URL or data URL
- `reference`, `right`, `golden`, `actual`, or `compare`: optional secondary image URL or data URL
- `imageLabel`, `leftLabel`, or `label`: optional primary image label
- `referenceLabel`, `rightLabel`, `goldenLabel`, or `compareLabel`: optional secondary image label
- `imageAlt`, `leftAlt`, `alt`: optional primary image alt text
- `referenceAlt`, `rightAlt`, or `goldenAlt`: optional secondary image alt text

Legacy `left`/`mock` and `right`/`golden` payloads still work, but new agents should prefer `image` and optional `reference`.

Do not inject red or blue review comments, handwritten annotations, arrows, or boxes through the import payload. The import payload should only define page title, section title, image URLs, and optional image labels. The user or agent should add visual annotations on the board after import.

## Tools

The board exposes:

- Select
- Pen
- Arrow
- Box
- Text
- Eraser
- Add image
- Color swatches
- Board-level Undo, Redo, Reset, and Copy

There is no circle tool.

## Clipboard

Use the board-level `Copy` button to copy the rendered board image to the clipboard. This is the preferred handoff back to an LLM or another review thread.

## Updating Images

To update the primary screenshot, decode the current `#data` payload, replace the target pair's `image`, then re-encode and update the hash.

To add or update a secondary image, set the target pair's `reference`. Keep the same `storageKey` and `id` if existing annotations should stay associated with the same review. Use a new `storageKey` if the board should open clean.

## Large Images

Small HTTPS URLs and small data URLs are fine in hash payloads. For large images, prefer opening the board and pasting or dragging images into it.

## Downloadable Skill

The current skill is available at:

```text
https://markloom.satoapps.com/skill/SKILL.md
```

If an agent has a local copy, it should refresh it after Markloom updates. If an agent is unsure how the board works, it should read this guide and the skill URL again instead of relying on stale instructions.