> ## Documentation Index
> Fetch the complete documentation index at: https://docs.posy.page/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent guide

> Rules, tile types, REST examples and the CLI for agents that edit a Posy page.

Every Posy account, self-hosted or on posy.page, has an API key page (**Agents** in the dashboard), a hosted MCP server, a REST API
and a CLI. Agents edit your **draft**; nothing goes live until `publish` is called.

## Connect

1. Create a key on the **Agents** page (it's shown once).
2. Connect your agent:

```bash theme={"theme":{"light":"rose-pine-dawn","dark":"rose-pine-moon"}}
# Claude Code
claude mcp add --transport http posy https://YOUR-POSY/api/mcp --header "Authorization: Bearer posy_..."
```

Cursor, Codex and other MCP clients: add an HTTP server at `https://YOUR-POSY/api/mcp` with the header
`Authorization: Bearer posy_...`. The Agents page has copy-paste snippets for each.

`YOUR-POSY` is your own server or `posy.page`. The API, MCP server and CLI behave the same on both, so a script written for one works on the other by changing `POSY_URL`. `export` and `import` move a whole page between them.

## MCP tools

| tool | what it does |
| - | - |
| `get_page` | Draft (profile, theme, tiles with ids), public URL, version, unpublished-changes flag |
| `add_tile` | Add from a link, email, `owner/repo` or note (auto-detected), or a full tile object |
| `update_tile` / `remove_tile` / `move_tile` | Change fields, delete, reorder by id |
| `set_theme` | Look (`style`), palette (`preset`), accent, font, radius, layout (`bento`, `list`, `canvas`), alignment, background, tile style, hover effect, avatar, photos (`natural`, `mono`, `dither`, `ascii`), page colour (`background.color`), ambience on or off |
| `set_profile` | Name, bio, avatar, location |
| `publish` | Make the draft live |
| `list_options` | The looks (with notes and palettes), and allowed values for themes, fonts, backgrounds, sizes, colours and platforms |

## Prompts that work

> Add my GitHub repo `owner/name` as a wide tile under "Projects", then publish.

> Switch to the Cobalt look in the moonlit palette, with photos printed in mono.

> Make a "Writing" section with links to my three latest posts: …

## Rules for agents

1. Start with `get_page`. Tiles have stable ids.
2. Sizes: `s` (1×1), `w` (2×1), `t` (1×2), `l` (2×2). `heading` tiles start a new section.
   On the default **desk** layout every tile is an object: images are polaroids, notes are sticky notes, Spotify is a record,
   YouTube is a ticket, GitHub repos are index cards, newsletter links (Substack, Buttondown, beehiiv…) are envelopes and
   links with a preview image are postcards. Social tiles become stickers under the name.
   Other looks (`theme.style`) draw the same tiles as their own objects: `washi` (a Japanese print: paper, ink, a red seal),
   `lofi` (a desktop left open; tiles are windows you can drag), `painted` (watercolour paper, letters, wax seals), `cobalt`
   (a vintage print in two inks, under a crescent moon) and `night` (a netrunner's HUD: scanned photos, cut-corner panels,
   one signal colour). `cozy` is the Desk look. Those are the looks to offer; `list_options` returns each with a short note
   and its palettes (`theme.preset`). Pages made with the retired `press` and `gallery` looks open as `cobalt` and `painted`.
   On posy.page, Painted, Desk and Cobalt are free; Washi, Lofi and Night are Pro.
   A `text` tile with `look: "stamp"` is each look's badge (stamp, red dot, wax seal, blinking sign).
3. Colours: `auto`, `surface`, `accent` or a pastel tint (`peach`, `butter`, `mint`, `sky`, `lilac`, `rose`).
4. Keep pages calm: a few well-chosen tiles beat many. Ask before deleting things the user added.
5. Edits are version-checked, so an agent and the person in the studio can work at the same time.
6. Layouts: `bento` is the grid, `list` is one column of links, and `canvas` places every tile freely, like a design canvas.
   On `canvas` a tile can carry `pos: { x, y, w, h, r, z }` in a design space **1200 units wide** (the page scales it to fit;
   `y` grows downwards without limit). `r` is rotation in degrees (-15 to 15, default 0) and `z` is the layer (higher on top,
   default 0). Tiles without `pos` are placed automatically, flowing like the grid below any placed tiles, so switching a page
   to canvas needs no positions at all. The auto grid is 4 columns of 288 with 16 gaps: a small tile is 288×288, wide 592×288,
   tall 288×592, large 592×592, and column `n` starts at `x = n × 304`. Keep values on multiples of 8, overlap tiles only on
   purpose, and keep text tiles at least 160 wide. Example: `update_tile` with `{"pos":{"x":608,"y":0,"w":592,"h":288,"r":-3,"z":1}}`.
   On phones (under 600px) a canvas page becomes one column, ordered top to bottom, then left to right.

## Tile types

| type | required fields | notes |
| - | - | - |
| `link` | `url` | optional `title`, `description`, `image` |
| `social` | `platform`, `handle` | platforms are listed in the schema; `email` works too |
| `text` | `text` | supports `**bold**`, `*italic*` and `[links](https://…)`. On the desk layout, `look: "stamp"` turns a short note into a round badge |
| `heading` | `text` | section title, always full width |
| `image` | `src` | uploaded or external image URL |
| `video` | `url` | YouTube. Optional `image` replaces the thumbnail |
| `music` | `url` | Spotify track, album, playlist, artist or show. `title` and cover `image` are filled in automatically |
| `github` | `repo` (`owner/name`) | stars, description and language are filled in automatically |

The JSON Schema for a whole page is in `schema/page.schema.json` (`npm run schema` regenerates it).

## REST and public JSON

```bash theme={"theme":{"light":"rose-pine-dawn","dark":"rose-pine-moon"}}
curl -H "Authorization: Bearer posy_..." https://YOUR-POSY/api/v1/page
curl -X POST -H "Authorization: Bearer posy_..." -H "Content-Type: application/json" \
  -d '{"input":"https://github.com/owner/repo"}' https://YOUR-POSY/api/v1/page/tiles
curl -X PATCH -H "Authorization: Bearer posy_..." -H "Content-Type: application/json" \
  -d '{"style":"night","preset":"redline","photos":"mono"}' https://YOUR-POSY/api/v1/page/theme
curl -X POST -H "Authorization: Bearer posy_..." https://YOUR-POSY/api/v1/page/publish
curl https://YOUR-POSY/api/v1/public/USERNAME      # anyone can read a published page
```

`PATCH` (or `POST`) `/api/v1/page/theme` is `set_theme` over REST: send only the fields that should change (`style`, `preset`, `accent`, `font`, `radius`, `layout`, `align`, `photos`, `tileStyle`, `effect`, `avatar`, `motion`, `ambient`, `background`) and get the whole theme back.

Each published page also has a plain-text version at `/<username>/llms.txt`.

## The CLI

```bash theme={"theme":{"light":"rose-pine-dawn","dark":"rose-pine-moon"}}
export POSY_URL=https://YOUR-POSY POSY_API_KEY=posy_...   # your server, or https://posy.page
npm run posy -- get
npm run posy -- add https://github.com/owner/repo --size w
npm run posy -- add "Open to freelance work" --color mint
npm run posy -- theme --preset moonlit --layout list
npm run posy -- profile --bio "Designer and tinkerer"
npm run posy -- remove t-abc1234
npm run posy -- publish
npm run posy -- export my-page.json   # also: import <file>, validate <file>
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.