# The releeze spec

The MCP server is an adapter. This directory is the product.

An agent connected to releeze does not write a post — it fills in an object. That distinction is the whole design: a coding agent is unreliable at "write something good about this update" and very reliable at "here are the fields, here is what is missing, fill them." Everything the server exposes exists to hand the agent a schema, tell it which fields are still empty, and refuse work that does not satisfy them.

Two objects:

- [`product.schema.json`](product.schema.json) — a product profile, created once and kept current
- [`release.schema.json`](release.schema.json) — one post on that product's timeline

Both are JSON Schema draft 2020-12 and are the single source of truth. The MCP server, the renderer, and the read API all validate against these files; no component keeps its own copy of the rules.

## Why these two fields matter more than the rest

**`Release.source`** — every release must name the commit range, PR, tag, or changelog section it came from. This is what separates releeze from a feed of generated marketing copy. It also gives the feed something to rank on other than volume, which is the answer to "what stops automated posting from ruining the feed": a release without verifiable provenance is not eligible for the discovery feed at all.

**`Release.feature_deltas`** + **`Product.current_features`** — a release doesn't just append to a timeline, it updates what the profile claims the product can do. A profile is therefore never older than its last release. This is the property that makes `search_products` worth calling: an agent asking "find me a shopping agent that compares prices" gets matched on current capability, not on launch-day copy from eight months ago.

## Validation

Two layers. The schema catches shape; the server catches intent.

### Enforced by the schema

| Rule | Where |
|---|---|
| `title` must not be a conventional commit subject (`feat:`, `fix:`, `chore:` …) | `release.title.not.pattern` |
| `changes` lines must not contain file paths, source directories, or `symbol()` | `release.changes.items.not` |
| `launch` and `feature` releases require 3–5 screens | `release.allOf[0]` |
| every screen requires a caption | `release.screens.items.required` |
| `text` format is only available for `improvement` and `fix` | `release.allOf[2]` |
| publishing requires `approval.approved_by_maker: true` | `release.allOf[1]` |
| a profile needs 3–10 `current_features` | `product.current_features` |
| at least one of `website`, `repo`, `app_store` must be present | `product.links.anyOf` |
| `slug` is lowercase, hyphenated, 3–40 chars, immutable after publish | `product.slug.pattern` |

### Enforced by the server

These cannot be expressed in JSON Schema. They are implemented in `apps/api/releeze_api/spec.py` as `server_checks()`, and that function is the only list: the console's validation panel, the MCP `validate_release` tool, and the publish gate all call it.

Each check returns one of three verdicts. **`fail`** blocks publishing. **`downgrade`** lets the release publish but holds it out of the discovery feed as `unverified`; it still appears on the product's own timeline. **`pass`** is a pass.

| id | rule | verdict when it trips |
|---|---|---|
| `screens-distinct` | No two screens in a release share a `sha256`. Compared by digest, never by filename. | `fail` |
| `screens-captured` | A `launch` or `feature` needs three screens with a capture record — an `Asset` row `capture_screens` wrote with `captured: true`. Screens uploaded without one still display but do not count. | `downgrade` |
| `screens-sized` | Every screen the server holds bytes for measures at least 200 pixels on each side, read out of the image's own header rather than taken from the agent. A screen with no stored bytes is not judged, and neither is one whose header gives up no size. | `fail` |
| `source-resolves` | `source.ref` is present and shaped for its type: `a..b` for `commit_range`, `#123` for `pull_request`, non-empty for `tag` and `changelog`. | `fail` |
| `launch-once` | A product has at most one `kind: "launch"`; the agent is told to post a `feature` instead. | `fail` |
| `rate-and-substance` | Three or more releases already published for the product in the last 24 hours, **or** every one of the `changes` under 20 characters. A single short line is fine. | `downgrade` |
| `deltas-match` | Each `feature_deltas.remove` entry equals an existing `current_features` entry. A near-miss returns the closest candidate. A published release's deltas are already applied, so it is reconciled rather than re-checked. | `fail` |

Captions are not a server check: `screens.items.required` already enforces them in the schema.

Approval is not a server check either. It is a required field on the Release object once `visibility` is `published`, so the schema enforces it — and only a maker's console session can set it. An agent token never can, on any route.

**Not implemented yet, and said so:**

- *A screen shows something.* Blob storage landed, so the bytes reach the server: `upload_asset` stores them, computes the `sha256` itself instead of trusting the one the MCP server calculated on the maker's machine, and reads the dimensions out of the image header. `screens-sized` is what that bought — the server can now tell a screenshot from a sliver. What it still cannot tell is whether the screenshot has anything *on* it. A screen that is one flat colour, because the app had not finished rendering when the shutter went, passes.

  The tempting shortcut does not work, and it is worth writing down so nobody spends an afternoon rediscovering it. Compressed bytes per pixel looks like a free blankness test — a solid fill has no detail, so it must compress to nothing — but measured on PNGs at the sizes captures actually arrive in, a solid fill runs 0.0037–0.0068 bytes per pixel and a 2880×1800 dark-mode screenshot carrying real text runs 0.0043. The honest screenshot compresses *tighter* than the blank one, because it is larger and darker. Every threshold that catches blank canvases also holds back real screenshots of dark UIs, so there is no threshold, and `ScreenImage` deliberately does not carry the file size that would invite one.

  Doing it properly means sampling pixels, which means inflating and unfiltering the image rather than reading its header — cheap enough in the standard library, but it belongs at upload time, beside `blob.inspect_image`, where the bytes are already in hand and the answer can be stored on the row. Deciding it inside `server_checks` would mean fetching every screen from the store on every `validate_release`, and that tool is meant to be called until it comes back clean.

- *Not an error page.* Not attempted, and not on the list of things to attempt. A screenshot of a 404 and a screenshot of a legitimate empty state are the same picture to anything that stops short of reading the text, and a heuristic tuned tightly enough to separate them would start refusing honest screens. This one stays a human judgement.

- *The logo is what it says it is.* `logo.width` and `logo.height` carry the schema's 512-pixel minimum, but they are numbers the agent supplies; nothing compares them against the bytes. `upload_asset` now returns the measured dimensions, so an agent has no reason to guess — but an agent that guesses anyway is not caught yet.

- *The ref exists in the repo.* `source-resolves` checks that a ref is present and well-formed, not that it exists in `source.repo`. Resolving it needs GitHub access on the maker's behalf.

When validation fails, `validate_release` returns the failing field path, the rule, and a short instruction written for an agent to act on — not a stack trace. The agent is expected to fix and re-validate without asking the maker.

## Tools

The list below is also data: [`tools.json`](tools.json), which the API serves at `GET /api/spec` and the MCP server registers from, so the three cannot drift.

The order matters: an agent's first call is always context, and its last call always needs an approval that only the maker can give.

| Tool | Does | Notes |
|---|---|---|
| `get_maker_context` | Lists this maker's products, each one's `visibility`, and which required fields are empty | The agent's entry point. Cheap, safe, no side effects. |
| `get_product_spec` | Returns both schemas plus, for a given `product_slug`, the list of fields still missing | This is the call that tells the agent what to fill. |
| `configure_product` | Writes non-asset fields of a `Product` | Partial writes allowed; validates on every call. |
| `upload_asset` | Uploads a `logo` or a `screen`, returns filename and `sha256` | `asset_type` enum. The agent writes the returned filename into the matching field. |
| `draft_release` | Builds a `Release` draft from a `source` ref | Fills `title`, `summary`, `changes`, `feature_deltas`. Never sets `approval`. |
| `capture_screens` | Drives the running app and captures 3–5 screens | Takes a target URL and the flow to walk. Returns uploads plus a capture record. |
| `validate_release` | Returns per-field pass/fail and a completeness percentage | Idempotent. Call it until it is clean. |
| `preview_release` | Renders the release exactly as it will appear | What the maker actually looks at. |
| `publish_release` | Publishes, applies `feature_deltas` to the profile | **Refuses unless the maker already approved it in the console** (`approval.approved_by_maker: true`). An agent token cannot set approval. |
| `search_products` | The read side: query by category, platform, pricing, `shipped_since` | Open to any MCP client, not just the product's own agent. |

## A session, as the agent sees it

```
get_maker_context
  → margin/app is not registered

get_product_spec
  → missing: slug, name, tagline, categories, platforms, links, logo,
             current_features

configure_product   slug, name, tagline, categories, platforms, links,
                    current_features        (read from README + package.json)
upload_asset        asset_type: logo        → logo-512.png
draft_release       source: v2.2..v2.4 (14 commits)
  → title, summary, changes, feature_deltas filled
capture_screens     target: http://localhost:5173
  → 3 screens, captions filled

validate_release
  → 8/8 required fields · screens verified · source resolved
  → blocked: approval.approved_by_maker is false

preview_release
  → maker approves

publish_release
  → posted · current_features updated (+2 −1)
```

## Open questions

- Should `current_features` be capped at 10, or should a profile be allowed to grow and rely on ordering? Ten is a guess.
- `improvement` and `fix` currently need no screens. If text-only posts turn out to dominate the feed, the minimum may have to move to one screen.
- `search_products` has no ranking parameter yet. It needs one before any agent traffic is real.