# Changelog

Source: https://docs.colophon.404human.dev/changelog/

## November 2026

### Saves commit together again: live-list hints are sent after the commit

18 Nov 2026 · Improvement · Performance, API · https://docs.colophon.404human.dev/changelog/#2026-11-18-change-hints-leave-the-commit

Every save, publish or membership change used to send its live-list hint from inside its own database transaction. PostgreSQL lets only one transaction that sends a notification commit at a time, so concurrent writes lost group commit: in load tests on a slower machine, changes to members, schedules and tokens queued 100–380 ms for that one lock.

Now a write only records its hint, and each Colophon process sends the committed hints every 100 ms, each distinct hint once, in a short transaction of its own. Concurrent saves commit in groups again. A statement that changes 1,000 rows queues one hint, not 1,000.

What you notice: a Studio list or an open event stream may hear about a change up to 100 ms later than before. Nothing else changes for clients. The `change` frames on `GET /api/v1/projects/{project}/environments/{environment}/events` keep their shape, commits close together may fold into one frame, and the last commit is always reported. A client should still refetch on each frame rather than count frames, and treat `resync` as "reload what you show".

```text
event: change
data: {"k":"entries","c":"posts","e":"<environment id>"}
```

Read more: [Live events](https://docs.colophon.404human.dev/api/live-events/)

### Preview helpers for your site in the SDK, and a colophon preview command

18 Nov 2026 · Feature · SDK, CLI · https://docs.colophon.404human.dev/changelog/#2026-11-18-preview-helpers-and-cli

Connecting your site to draft preview is now a few lines. `@colophon-cms/sdk` adds helpers built on the standard `Request` and `Response` types, so they work in SvelteKit, Astro, Next.js or any other framework:

- `createPreviewHandler` exchanges the one-time code for a preview token, keeps it in your own `HttpOnly` cookie and redirects to the page;
- `previewTokenFromRequest` and `previewClient` read drafts from `/preview/v1` with that token;
- `previewHeaders` sends `private, no-store`, `noindex` and a `frame-ancestors` rule so only your Studio can frame the page;
- `listenForDraftUpdates` reloads the page after each save in the Studio; `exitPreviewHandler` ends preview.

```ts
import { createPreviewHandler } from '@colophon-cms/sdk';
const enter = createPreviewHandler({ baseUrl: 'http://localhost:8080', project: PROJECT_ID });
```

A static site can read previews straight from the browser: `/preview/v1` answers CORS for the environment's preview origin, never with credentials.

From the terminal, `colophon preview` prints a one-time address for an entry's saved draft, or for a publish request with `--changeset`:

```sh
colophon preview <entry id> --project <project> --minutes 30
```

The address works once, within a minute. The SDK is prepared for its first npm release.

Read more: [TypeScript SDK](https://docs.colophon.404human.dev/sdk/) · [The colophon CLI](https://docs.colophon.404human.dev/cli/) · [Preview](https://docs.colophon.404human.dev/studio/preview/)

### Preview the saved draft on your own site, beside the editor or in a new tab

18 Nov 2026 · Feature · Studio · https://docs.colophon.404human.dev/changelog/#2026-11-18-preview-in-the-studio

Editors can now see a draft as their website will show it, before it is published.

An owner sets the site's preview address once, in **Settings → Website connections → Preview on your site**. The address must contain `{code}`, and may also use `{collection}`, `{id}`, `{slug}` and `{locale}`, so it can open the right page directly.

In the entry editor, the **Preview** menu offers **Side by side** (your site beside the fields; on a narrow screen, switch between Edit and Preview) and **Open on my site** (a new tab). The pane shows your last *saved* version, never unsaved keystrokes, and refreshes after each save the server accepted. It keeps the preview open while you work and ends it when you close the pane.

A publish request's page has **Preview on your site** too, showing exactly what that request will publish, bound to its current content.

Every state is spelled out: not set up yet, opening, the site didn't confirm, unsaved changes, a save that failed, or a browser that blocks the site's cookie inside the pane. In that last case, open the preview in a new tab instead, which always works.

Your site needs a preview route; the SDK's preview helpers provide one.

Read more: [Preview](https://docs.colophon.404human.dev/studio/preview/)

### A production path without containers: a hardened systemd unit and a Caddyfile

18 Nov 2026 · Feature · Self-hosting · https://docs.colophon.404human.dev/changelog/#2026-11-18-production-without-containers

If you would rather not run Docker, or your database is managed elsewhere, Colophon now ships a path for one Linux host: `colophon-server` under systemd, Caddy in front for HTTPS, and PostgreSQL and object storage wherever you keep them.

The systemd unit keeps secrets out of files and the environment: the database URL, cache URL and storage key are systemd credentials, read through the `COLOPHON_*_FILE` settings. The service runs as a dynamic user with no privileges, a read-only file system and a narrow system-call filter, and shuts down gracefully so in-flight requests finish. The Caddyfile proxies your domain to the server on loopback and passes live events through as they are written.

```ini
LoadCredential=database_url:/etc/colophon/credentials/database_url
Environment=COLOPHON_DATABASE_URL_FILE=%d/database_url
```

The non-secret settings live in an environment file; set `COLOPHON_PUBLIC_URL` to your `https://` address and `COLOPHON_TRUSTED_PROXIES=127.0.0.1/32` so rate limits count each visitor rather than the proxy. The steps start from a release's static binaries; until the first release is published, build them from source.

These files are checked in CI by `systemd-analyze verify` and `caddy validate`. They have not yet been followed end to end on a real host.

Read more: [Installation](https://docs.colophon.404human.dev/installation/) · [Security](https://docs.colophon.404human.dev/self-hosting/security/)

### Creating API tokens no longer starves reads, and schedule and release lists read only what they show

18 Nov 2026 · Improvement · Performance, API · https://docs.colophon.404human.dev/changelog/#2026-11-18-token-creation-and-list-reads

Two load fixes for busy projects.

**Token creation.** A project may hold at most 100 active API tokens, so each `POST /api/v1/projects/{project}/tokens` takes the project's creation lock, counts, then writes. That lock used to be held across eight round trips to the database, about 100 ms each on a small server, while queued creators each held a pooled connection and other reads waited. It is now held for two statements: the lock, then one statement that counts and writes the token and its permissions. The count stays exact: twenty creators racing for the last slot still make exactly one token, and the rest get `422 too_many_tokens`. The answer to a creation is now exactly what reading the token back returns.

**Schedule and release lists.** `GET …/schedules` and `GET …/releases`, and the check that finds which publish requests stop an entry's deletion, now choose their rows first and look up titles and names afterwards. Before, once a project had grown past the database's statistics, a 120-row schedule list could read 16,203 publish-request rows and take three seconds, and a 100-release page read 10,150. Each list now reads about as many rows as it returns.

Nothing to change on your side.

Read more: [Authentication & API tokens](https://docs.colophon.404human.dev/api/authentication/) · [Scheduling](https://docs.colophon.404human.dev/studio/scheduling/)

### Sign-in tokens and device codes in a URL never reach the logs

17 Nov 2026 · Security · Self-hosting · https://docs.colophon.404human.dev/changelog/#2026-11-17-credentials-kept-out-of-logs

Every log line written while handling a request carries the request's path. Two routes carry a secret in that path: spending a magic link (`POST /audience/v1/{project}/magic-link/{token}`) and the CLI's device approval page (`GET /auth/device/{code}`). With debug logging on, or whenever a warning was logged during such a request, the live token or code was written to the log store.

Now the logged path writes those segments as their names, so the line reads `POST /audience/v1/<project id>/magic-link/{token}` at every log level. Every other segment is kept as sent, so ids stay searchable. A path that matches no route but looks like one of these, such as one with a trailing slash, is redacted the same way.

Nothing changes for clients; the routes keep their shape. If you kept debug logs from before this change, treat magic-link tokens and device codes in them as exposed. They expire on their own within minutes, so the risk is to old logs that were shared, not to accounts today.

Read more: [Monitoring](https://docs.colophon.404human.dev/self-hosting/monitoring/) · [Security](https://docs.colophon.404human.dev/self-hosting/security/)

### Database guards trust roles, not session settings, and deleting a project is an operator's job

17 Nov 2026 · Security · Self-hosting · https://docs.colophon.404human.dev/changelog/#2026-11-17-database-hardening

Colophon's PostgreSQL schema protects a project's owner role, its last owner and the audit log with triggers. Some of those guards stood aside when a session setting was present, and any session can set one, including the server's own database login. Now the guards stand aside only for the dedicated database roles that do sanctioned work: the retention sweep and project deletion.

Also fixed in the database:

- The guard functions pin their `search_path`, and the check that a project exists answers only inside its trigger.
- Sign-in throttle rows are row-level secured by realm, so staff keys and each project's site-user keys are visible only in their own context.
- The retention sweep keeps pace with the two tables unauthenticated requests grow (magic links and sign-in throttle keys).
- Deleting a project now removes its audience roles, site users and their sessions, magic links, listed origins and upload versions. It runs from the database owner's login, as an operator task; the server's login can no longer call it.

**Rollback floor:** these changes are additive, so an older build would still start on the newer schema and simply ignore them. Once you run a build with these fixes, never roll back to one without them; fix forward instead.

Read more: [Security](https://docs.colophon.404human.dev/self-hosting/security/) · [Backups and restore](https://docs.colophon.404human.dev/self-hosting/backups/)

### Preview drafts on your own site through a short-lived, read-only preview API

17 Nov 2026 · Feature · API · https://docs.colophon.404human.dev/changelog/#2026-11-17-draft-preview-api

Your site can now show unpublished drafts to the people who are working on them. First tell Colophon where previews open, as a signed-in person (here with the personal token `colophon login` keeps):

```sh
curl -X PUT http://localhost:8080/api/v1/projects/{project}/environments/{environment}/preview-target \
  -H "Authorization: Bearer $COLOPHON_TOKEN" -H 'Content-Type: application/json' \
  -d '{"url_template":"https://example.com/api/preview?code={code}"}'
```

A person then opens a preview of an entry (with its translations) or of a publish request with `POST …/previews`; project API tokens can't. The answer holds a site address carrying a one-time code that works once, within 60 seconds. Your site exchanges it at `POST /preview/v1/{project}/{environment}/exchange` for a bearer token that lasts 15 minutes by default.

With that token, `/preview/v1` answers exactly like `/content/v1` (list, get, query and a `session` route for a preview banner), with the drafts laid over the latest release and a `preview` object on each row. A publish request's preview is bound to the exact content under review: if it changes, reads answer `409 preview_stale`.

Preview answers are `private, no-store`, never indexed and never cached, and every read re-checks that the person who opened it may still read this content. They can renew the preview, ask for a fresh code or end it now.

Read more: [Preview](https://docs.colophon.404human.dev/studio/preview/) · [Delivery API](https://docs.colophon.404human.dev/api/delivery/)

### GraphQL refuses documents that are too deep or too large before running them

17 Nov 2026 · Security · API · https://docs.colophon.404human.dev/changelog/#2026-11-17-graphql-document-limits

A GraphQL document's cost used to be measured only as it ran. A short document full of nested fragments could keep a server busy for minutes, and a value nested deeply enough could exhaust the server's stack while parsing.

Now every document sent to `POST /api/v1/projects/{project}/environments/{environment}/collections/{collection}/graphql` is measured before it runs, with its fragments expanded:

- deeper than 16 levels: `too_deep`
- more than 512 fields: `too_complex`
- fragments that spread one another in a cycle: `fragment_cycle`
- brackets nested more than 64 deep, checked before parsing: `too_deep`

Each refusal is a `422` in the usual error envelope, pointing at the query, and nothing runs:

```json
{"error": {"code": "validation_failed",
  "message": "…",
  "details": {"reason": "too_deep", "pointer": "/query"},
  "request_id": "…"}}
```

The limits leave room for every read the schema allows (a two-level reference read is 6 deep) and for a full introspection query.

Read more: [GraphQL](https://docs.colophon.404human.dev/api/graphql/) · [Errors](https://docs.colophon.404human.dev/api/errors/)

### Magic links land only on sites the project lists, and link requests are bounded

17 Nov 2026 · Breaking · API · https://docs.colophon.404human.dev/changelog/#2026-11-17-magic-links-need-listed-origins

**Old behaviour:** a magic-link request could name any absolute http(s) address as `return_to`, and the sign-in token was added to it, so the token could travel to a site the project never chose. Asking for a new link also cancelled the previous one.

**New behaviour:** `return_to` must be on an origin the project lists, or the request answers `422 return_to_not_allowed` before any link exists. A project that lists nothing sends no links. Asking again no longer cancels a link; spending any link retires the others for that address. The token is placed before any `#fragment` in `return_to`.

Requests are now bounded: 5 links per client address per project in ten minutes (`COLOPHON_MAGIC_LINKS_PER_ADDRESS`), a recipient wait that starts at one minute and doubles up to an hour, and 300 links per project a minute (`COLOPHON_MAGIC_LINKS_PER_PROJECT`). Each answers `429 rate_limited` with `Retry-After` and sends nothing.

**What to do:** as a member with `audience.manage`, list every site that receives links (at most 32, each `scheme://host[:port]`):

```sh
curl -X PUT http://localhost:8080/api/v1/projects/{project}/audience/origins \
  -H "Authorization: Bearer $COLOPHON_TOKEN" -H "Content-Type: application/json" \
  -d '{"origins": ["https://www.example.com"]}'
```

Read more: [Authentication & API tokens](https://docs.colophon.404human.dev/api/authentication/)

### A replaced or deleted image no longer stays cached for a year at its plain address

17 Nov 2026 · Security · API · https://docs.colophon.404human.dev/changelog/#2026-11-17-media-cache-headers

An upload's plain address, `/media/v1/{project}/{environment}/{asset}`, always serves the upload's current version, and a replace or a delete changes what that is. It was nevertheless marked immutable for a year, so a browser or CDN that had seen the old bytes could keep showing a replaced image, or one you had deleted, long after the change.

Now caching follows what the address names:

- a version's own address, `…/{asset}/{sha}` and its renditions, stays `public` and `immutable` with a one-year `max-age`: those bytes never change;
- the plain addresses, `…/{asset}` and `…/{asset}/{name}`, answer `public, max-age=60, must-revalidate` with the version's `ETag`, and a matching `If-None-Match` gets a `304` with no body.

```http
GET /media/v1/{project}/production/{asset}
If-None-Match: "…"

HTTP/1.1 304 Not Modified
Cache-Control: public, max-age=60, must-revalidate
```

A change at the plain address now reaches caches within a minute. For pages that must show exactly what was published, use the versioned `url` that delivery rows carry in `media`.

Read more: [Media library](https://docs.colophon.404human.dev/studio/media-library/) · [Delivery API](https://docs.colophon.404human.dev/api/delivery/)

### The media library pages, searches, filters and keeps alt text, titles, credits and tags

17 Nov 2026 · Improvement · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-11-17-media-library-search-and-details

The upload list used to stop at the newest 100, so the 101st upload was invisible in the Media page and in every image picker. Now `GET /api/v1/projects/{project}/environments/{environment}/assets` pages with `limit` (1–100) and `cursor`, answering `next_cursor`. It also searches file names, titles and alt text with `q`, and filters by `state` and `tag`.

Each upload keeps its own words. `PATCH …/assets/{asset}` changes `alt` (up to 300 characters), `title`, `credit` and `tags` (up to 10, lowercase with dashes), under `If-Match`; a stale `ETag` answers `409 stale_version`. Tags take the place of folders.

```sh
curl -X PATCH http://localhost:8080/api/v1/projects/{project}/environments/production/assets/{asset} \
  -H "Authorization: Bearer $COLOPHON_TOKEN" -H 'If-Match: "v3"' \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{"alt": "Harbour at dawn", "tags": ["harbour", "cover"]}'
```

In the Studio, the Media page shows the whole library with search and filters, uploads many files at once through a queue, and opens each upload's details: alt text, title, credit and tags (with a conflict state if someone else changed them), its versions, where it's used, replace (with a reminder to republish), both addresses to copy, and delete.

Read more: [Media library](https://docs.colophon.404human.dev/studio/media-library/)

### The static Linux server runs allocation-heavy requests five times faster

17 Nov 2026 · Improvement · Performance, Self-hosting · https://docs.colophon.404human.dev/changelog/#2026-11-17-mimalloc-for-the-static-server

The Linux build of `colophon-server` is a static binary linked against musl, so one file runs on any Linux and the container image needs no C library. musl's own memory allocator takes a single lock for every thread, and it showed: on the same CI runner, validating a realistic rich-text post ran at 4,589 requests a second (p99 29.1 ms) against 23,340 (p99 10.3 ms) for a glibc build of the same code.

The static Linux server now allocates through mimalloc. Measured the same way, it matched glibc: 24,367 requests a second against 23,891, p99 9.6 ms against 10.0 ms. Memory after the run was 38.2 MB resident against glibc's 32.5 MB. These are observations on one CI runner type, not capacity figures.

Nothing to configure. Only the static Linux server and the container image change; macOS, Windows and glibc builds keep their system allocator, and the `colophon` CLI, a short-lived client, keeps musl's.

Read more: [Installation](https://docs.colophon.404human.dev/installation/)

### Colophon is released under the MIT licence

17 Nov 2026 · Improvement · Self-hosting · https://docs.colophon.404human.dev/changelog/#2026-11-17-mit-licence

Colophon now has a licence: MIT. The repository's `LICENSE` file holds the standard MIT text, every Rust component of the server, worker and `colophon` CLI declares `license = "MIT"`, and the npm packages prepared for the first release (`@colophon-cms/sdk`, `@colophon-cms/rich-text` and `@colophon-cms/cli`) say `"license": "MIT"`.

Why it matters: until a licence is settled, nobody can safely run, change or build on the code. MIT lets you self-host Colophon, modify it and ship it inside your own products, commercial or not. The only condition is that copies keep the copyright and licence notice. There is no warranty.

What to do: nothing, if you are running Colophon. If you redistribute it, for example in a container image or as part of a larger product, include the `LICENSE` file. Colophon's own dependencies keep their own licences; the build only admits licences on its allowlist, MIT among them.

```json
{
  "name": "@colophon-cms/sdk",
  "license": "MIT"
}
```

Read more: [Introduction](https://docs.colophon.404human.dev/)

### Run Colophon with one Docker Compose command, with secrets kept in files

17 Nov 2026 · Feature · Self-hosting, CLI · https://docs.colophon.404human.dev/changelog/#2026-11-17-one-command-docker-install

Docker is now all you need. The quick start's compose file starts Colophon with PostgreSQL, Valkey and Garage, generates every password and key on first start, and publishes only `127.0.0.1:8080`. One image carries the server, the `colophon` CLI and the Studio, on a distroless base, running as a non-root user. The image is prepared for the first release; until it is published, build it from a clone of the repository and name it in `COLOPHON_IMAGE`.

```sh
docker compose up -d --wait
docker compose logs colophon | grep "Setup code"
```

Then open `http://localhost:8080/studio/`, create the first account and enter the setup code; the Studio's first-run screen shows that command too.

Two pieces help any install, container or not:

- Every secret setting also takes `<KEY>_FILE`, a path to a mounted secret, for example `COLOPHON_DATABASE_URL_FILE` or `COLOPHON_S3_SECRET_KEY_FILE`. Setting both a value and its file stops the server at start-up, and no error ever prints a secret's contents.
- `colophon admin init-roles --app-password-file FILE` creates the database roles the server needs, sending passwords as SCRAM verifiers. It refuses the development password and anything under 16 characters, and is safe to rerun.

Read more: [Quick start](https://docs.colophon.404human.dev/quick-start/) · [Installation](https://docs.colophon.404human.dev/installation/) · [Configuration](https://docs.colophon.404human.dev/self-hosting/configuration/)

### Website connections reach only public https addresses unless you opt in

17 Nov 2026 · Security · Self-hosting, API · https://docs.colophon.404human.dev/changelog/#2026-11-17-private-destinations-and-development-shortcuts

A server listening on a loopback address used to be treated as a development machine, so its webhooks, CDN purges and probes could reach private and loopback addresses. A production server behind a reverse proxy listens on loopback too, which meant a project member could aim a destination at services on the private network.

Now a destination must be https and resolve to a public address, checked when it is saved and again before every attempt, whatever address the server listens on. The worker also ignores proxy settings from its environment, so a delivery can't go around the check through a proxy.

For local development only, opt in explicitly; the server says so in its start-up log:

```sh
COLOPHON_ALLOW_PRIVATE_DESTINATIONS=1
```

The other development shortcuts got the same treatment. `COLOPHON_DEV_MAIL=1`, which hands sign-in links back in responses, and the development identity provider's public client secret are refused at start-up unless the server listens on loopback **and** `COLOPHON_PUBLIC_URL` names `localhost`, a `*.localhost` name or a loopback address.

Read more: [Website connections](https://docs.colophon.404human.dev/api/website-connections/) · [Configuration](https://docs.colophon.404human.dev/self-hosting/configuration/)

### Anonymous live streams have their own budget and can't crowd out editors

17 Nov 2026 · Security · API, Self-hosting · https://docs.colophon.404human.dev/changelog/#2026-11-17-public-live-stream-budget

The public live stream, `GET /content/v1/{project}/{environment}/events`, needs no credential. Its streams used to count against the same per-project and per-server limits as the Studio's own live updates, so enough anonymous streams could stop editors from getting live updates, and one client could take the whole budget.

Now anonymous streams are counted on their own, and each client address has a cap (IPv6 counted by its /64). Editors' streams never compete with them. Hints still travel the same way, so a published change costs the same to announce.

| Setting | Default | Over it |
|---|---|---|
| `COLOPHON_EVENTS_PUBLIC_PER_ADDRESS` | 8 | `429 rate_limited` with `Retry-After` |
| `COLOPHON_EVENTS_PUBLIC_PER_PROJECT` | 256 | `503 unavailable` |
| `COLOPHON_EVENTS_PUBLIC_MAX_STREAMS` | 2048 per server | `503 unavailable` |

A site that fans one upstream stream out to its own visitors holds one stream per site server, well inside the per-address cap. Behind a reverse proxy, set `COLOPHON_TRUSTED_PROXIES` so each visitor is counted by their own address rather than the proxy's.

Read more: [Live events](https://docs.colophon.404human.dev/api/live-events/) · [Configuration](https://docs.colophon.404human.dev/self-hosting/configuration/)

### Delivery rows name the exact image versions a release published

17 Nov 2026 · Breaking · API, SDK · https://docs.colophon.404human.dev/changelog/#2026-11-17-released-media-versions-in-delivery

**Old behaviour:** sites built image addresses that always served an upload's newest version, with no size. Replacing an image changed published pages at once, without anyone publishing.

**New behaviour:** a release records the version of every upload its entries name, in asset fields and rich text. Each `/content/v1` row now carries `media`, keyed by asset id: `url` (that version's immutable address, cacheable for a year), `current_url` (follows replacements), `type`, `width`, `height` and `renditions` (`w320`, `w1280` when the original is wider). A replaced image reaches `url` at the entry's next publish; pinned reads with `?generation=` and rollbacks show that release's images. Absolute addresses use `COLOPHON_MEDIA_URL`, which defaults to `COLOPHON_PUBLIC_URL`. Cached delivery answers are refetched once.

**What to do:** use `url` for "what was published" or `current_url` for "always the newest", and republish entries whose images you replaced. With the SDK, `mediaFor(row)` gives the renderer each image's `width`, `height`, `srcset` and `sizes`:

```ts
import { mediaFor } from '@colophon-cms/sdk';
import { renderToHtml } from '@colophon-cms/rich-text';

const html = renderToHtml(row.content.body, { assetUrl, media: mediaFor(row) });
```

Read more: [Delivery API](https://docs.colophon.404human.dev/api/delivery/) · [Media library](https://docs.colophon.404human.dev/studio/media-library/) · [TypeScript SDK](https://docs.colophon.404human.dev/sdk/)

### The releases list pages past the newest 100, and the OpenAPI document matches the routes

17 Nov 2026 · Fix · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-11-17-releases-list-pages-and-openapi-fixes

`GET /api/v1/projects/{project}/environments/{environment}/releases` used to stop at the newest 100 releases with `next_cursor` always `null`, although the OpenAPI document described a cursor. It now pages for real: `?limit=` takes 1–100 (default 100, what it answered before, so callers that never page see no change) and `?cursor=` takes the `next_cursor` of the previous page. A release published while you walk the pages lands above the first page, so a walk never skips or repeats one.

```sh
curl "http://localhost:8080/api/v1/projects/{project}/environments/{environment}/releases?limit=50&cursor=<next_cursor>" \
  -H "Authorization: Bearer $COLOPHON_TOKEN"
```

The MCP server's `list_releases` tool takes the cursor too, and the Studio's Releases page has **Show older releases**.

The OpenAPI document now says only what each route does. A list that pages names the parameter its `next_cursor` goes back in; a list that always answers in one page says what that page holds and types `next_cursor` as always `null`. A release's receipt lists every release field directly, with the release, delivery and observation fields marked required. The SDK's generated types follow the corrected document.

Read more: [Management API](https://docs.colophon.404human.dev/api/management/) · [API reference](https://docs.colophon.404human.dev/api/reference/)

### Images inside rich text must name real uploads from the media library

17 Nov 2026 · Breaking · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-11-17-rich-text-images-are-real-uploads

**Old behaviour:** the server checked only a rich-text image's shape. Any `assetId` was saved, so an image could name nothing at all, publishing never checked it, and its upload could be deleted while a page still showed it. The Studio's old image dialog inserted a random placeholder id.

**New behaviour:** each image is tracked like an asset field: checked at publish, kept from deletion while used, and listed under "Where it's used". A save naming an id that isn't an upload of the environment is refused at that image:

```json
{"error": {"code": "validation_failed", "message": "…",
  "details": {"reason": "asset_not_found",
              "pointer": "/body/doc/content/3/attrs/assetId"},
  "request_id": "…"}}
```

A document may name at most 200 distinct images (`too_many_images`). In the Studio, images come from the media library: pick, search or upload one, then give alt text, which is required. A pasted or dropped image is uploaded and inserted.

**What to do:** drafts holding placeholder images are refused at their next save. Open each one: the Studio marks the image in place with **Replace** and **Remove**. Revisions saved before this change pin their images only once saved again.

Read more: [Rich text and images](https://docs.colophon.404human.dev/studio/rich-text-and-images/) · [Media library](https://docs.colophon.404human.dev/studio/media-library/)

### The SDK checks it fits the server, and the rich-text renderer becomes its own package

17 Nov 2026 · Feature · SDK · https://docs.colophon.404human.dev/changelog/#2026-11-17-sdk-compatibility-and-rich-text-package

`@colophon-cms/sdk` now says plainly when the server it talks to is too old or too new. Before its first call it reads `GET /version` once and judges it by the same rule as the `colophon` CLI: the server must serve API `v1`, share the SDK's minor version before 1.0, and be at least the oldest server the SDK supports. The new `compat` option decides what happens: `'warn'` (the default) logs the reason and never delays a call, `'throw'` fails every call with an `incompatible_server` error, `'off'` never asks.

```ts
import { Client } from '@colophon-cms/sdk';

const client = new Client({ baseUrl: 'http://localhost:8080', compat: 'throw' });
const fit = await client.compatibility();
if (!fit.compatible) console.error(fit.reason); // which side to upgrade, and to what
```

The renderer the Studio uses is now `@colophon-cms/rich-text`, a package with no dependencies whose `renderToHtml` turns stored rich text into escaped HTML, so your site renders exactly what editors previewed.

Both packages are prepared for their first npm release, not yet published: every push checks the files they would ship, their size (the browser client is about 4.5 KB compressed), their type declarations, and a scratch project that installs and compiles them.

Read more: [TypeScript SDK](https://docs.colophon.404human.dev/sdk/) · [Rich text and images](https://docs.colophon.404human.dev/studio/rich-text-and-images/)

### A database on another machine needs sslmode=verify-full, and on/off settings are strict

17 Nov 2026 · Breaking · Self-hosting · https://docs.colophon.404human.dev/changelog/#2026-11-17-settings-checked-at-start-up

**Old behaviour:** the server had no TLS for PostgreSQL: a remote URL without `sslmode` connected in plain text, and one asking for TLS could not connect. On/off settings with values such as `yes` or `on` were quietly read as "off".

**New behaviour:** the server and the `colophon admin` commands refuse to start when `COLOPHON_DATABASE_URL` or `COLOPHON_MIGRATION_DATABASE_URL` names another machine with anything but `sslmode=verify-full`. `require` accepts any certificate, so anyone on the network path could answer as your database; `verify-ca` here accepts any publicly trusted certificate, for any name. `channel_binding=require` is refused on any host, because the driver would silently ignore it. The error names the problem and the fix, never the URL. A loopback host or a Unix socket needs no certificate, as before.

On/off settings now take only `1`, `true`, `0` or `false`; anything else stops the server at start-up with a message naming the setting.

**What to do:** change a remote database URL to `verify-full`, adding `sslrootcert` if your database uses a private certificate authority:

```sh
COLOPHON_DATABASE_URL="postgres://colophon_app@db.internal:5432/colophon?sslmode=verify-full&sslrootcert=/etc/colophon/db-ca.pem"
```

If you copied a hosted provider's URL with `sslmode=require&channel_binding=require`, replace both parameters with `sslmode=verify-full`.

Read more: [Database TLS](https://docs.colophon.404human.dev/self-hosting/database-tls/) · [Configuration](https://docs.colophon.404human.dev/self-hosting/configuration/)

### Sign-in pauses the guesser, not the account, and password work has a ceiling

17 Nov 2026 · Security · API, Self-hosting · https://docs.colophon.404human.dev/changelog/#2026-11-17-sign-in-hardening

Several fixes to staff and site-user sign-in, all on `main`:

- **Guessing no longer locks out the owner.** Eight misses used to pause the account itself, and a pause answered differently from a wrong password. Now misses pause the (account, client address) pair for fifteen minutes; IPv6 clients count by their /64. Fifty misses in an hour from addresses the account never signed in from pause those addresses only; the owner's own addresses keep working.
- **A pause looks like a miss.** `409 too_many_attempts` is gone: a paused attempt answers `400 sign_in_failed`, as a wrong password or a missing account does. A site user's `403 account_disabled` now comes only with the right password.
- **Password hashing is bounded.** At most `COLOPHON_PASSWORD_CONCURRENCY` hashes run at once (one per core by default); a short queue waits, the rest answer `503 unavailable` with `Retry-After`, and no hash holds a database connection, so a sign-in flood can't starve delivery.
- **Small bodies before sign-in.** Sign-up, sign-in, the device flow and magic-link requests read at most 16 KiB; more answers `413 payload_too_large`.

If clients branch on `too_many_attempts`, treat `sign_in_failed` as the only refusal. Behind a reverse proxy, set `COLOPHON_TRUSTED_PROXIES`, or every client looks like the proxy.

Read more: [Authentication & API tokens](https://docs.colophon.404human.dev/api/authentication/) · [Errors](https://docs.colophon.404human.dev/api/errors/) · [Security](https://docs.colophon.404human.dev/self-hosting/security/)

### The Studio no longer shows stale lists after a live update, or closes an entry when a refresh fails

17 Nov 2026 · Fix · Studio · https://docs.colophon.404human.dev/changelog/#2026-11-17-studio-keeps-up-with-live-updates

Two Studio bugs that showed up on slow connections and under load are fixed.

**Lists could stay stale until a reload.** When a live change arrived while a page was still loading a list for the first time, the Studio joined the read already in flight instead of sending a new one. If that read had left before the change committed, its old answer stood: a release's deliveries, for example, kept saying "pending" after the job had finished. Now every live change, resync and catch-up cancels matching reads in flight and reads again, so the list always reflects the change that triggered it.

**An open entry could vanish.** After a save, the Studio refreshes the entry. If that refresh failed, for example because a burst of requests hit the rate limit, the editor was replaced by the error screen, heading and all. Now the error screen appears only when there is nothing to show yet; a failed refresh leaves the editor, and your work, where they are.

Nothing to configure: both fixes are in the Studio served by the server.

Read more: [Live events](https://docs.colophon.404human.dev/api/live-events/) · [Writing in the Studio](https://docs.colophon.404human.dev/studio/writing/)

### Opening an entry no longer slows down as a project fills up with entries

17 Nov 2026 · Improvement · Performance · https://docs.colophon.404human.dev/changelog/#2026-11-17-translations-read-by-key

Every read of a draft also lists its translations (the `localizations` on `GET /api/v1/projects/{project}/environments/{environment}/collections/{collection}/entries/{entry}`). In a project that had just been filled with entries, PostgreSQL could plan that lookup as a comparison of every entry with every other one. In load tests a single entry read then took 0.5–0.7 seconds, and the entries load test failed with 2–4 second latencies.

The lookup is now two direct reads: the entry by its key, then, only if it belongs to a group of translations, that group by its key. An entry without translations, the usual case, costs one key lookup, and a translated entry's read grows with the size of its own group, never with the size of the project.

What you notice: entry pages in the Studio, and draft reads over the API, stay as quick in a project of thousands of entries as in a small one, including right after a large import, before the database has refreshed its statistics. A test now fills a project with 1,500 entries and reads translations twenty times each within 250 ms; it took 1.1 seconds before the fix.

Nothing to change on your side.

Read more: [Languages](https://docs.colophon.404human.dev/studio/languages/)

### Collections with a hyphen in their name get a cache tag, so CDN purges reach their lists

16 Nov 2026 · Fix · API · https://docs.colophon.404human.dev/changelog/#2026-11-16-cache-tags-for-hyphenated-collections

Delivery answers carry a `Cache-Tag` header so a CDN connection can purge exactly what a release changed. A list page's tags include one for its collection, but that tag was only made for names of lowercase letters, digits and underscores. Collection names may also contain hyphens, so a collection such as `release-notes` got no collection tag. After a release, the purge missed its list pages, and a CDN kept serving the old list until it expired (up to 30 seconds).

The rule for a collection tag is now exactly the rule for a collection's name, hyphens included. A name no collection could have still gets no tag, so text from a URL never reaches the header.

```http
GET /content/v1/{project}/{environment}/release-notes HTTP/1.1
Host: localhost:8080

HTTP/1.1 200 OK
Cache-Tag: …, colophon:p:<project id>:e:<environment id>:c:release-notes
```

Nothing to change on your side: the next release purges these lists along with everything else, and the tags do not depend on the generation, so purges cover answers cached from earlier releases too.

Read more: [Website connections](https://docs.colophon.404human.dev/api/website-connections/) · [Delivery API](https://docs.colophon.404human.dev/api/delivery/)

### A new installation greets you as new, and the server prints a link that fills in the setup code

16 Nov 2026 · Improvement · API, Studio, Self-hosting · https://docs.colophon.404human.dev/changelog/#2026-11-16-installation-status-and-setup-link

The first run used to be the hardest part: the installer copied a setup code out of a scrolling server log, and the signed-out Studio told them to ask someone for an invitation. Now the server's banner prints a link next to the code, and the Studio knows when nobody runs this Colophon yet.

```text
Setup code: <code>
...the link fills the code in for you:
    http://localhost:8080/studio/#setup=<code>
```

The code travels in the `#` fragment, which browsers never send, so it reaches no server or proxy log. Opened from the link, the Studio leads with **Create an account** and fills the code into **Finish setting up**. The code works once, for an hour.

Without the link, the Studio asks `GET /api/v1/installation`, a route anyone may call before signing in. It answers only yes or no, never who, with `Cache-Control: no-store`:

```json
{"data": {"has_administrator": false}}
```

Smaller Studio changes landed alongside: no text is smaller than 14px, the search box says "Search", and the getting-started checklist says "Write first" until there is something to publish.

Read more: [Installation](https://docs.colophon.404human.dev/installation/) · [Quick start](https://docs.colophon.404human.dev/quick-start/)

### Sign in with email and password; an identity provider is now optional

6 Nov 2026 · Feature · API, Studio, Self-hosting · https://docs.colophon.404human.dev/changelog/#2026-11-06-sign-in-without-an-identity-provider

Colophon no longer needs an OpenID Connect provider. Built-in email-and-password accounts are the default way to sign in to the Studio, and OIDC is an adapter you add only if you want single sign-on.

`POST /auth/signup` makes an account (password at least 8 characters) and starts its session; an existing email answers `409 email_taken`. `POST /auth/signin` answers `204` with the session cookies. A wrong password and a missing account get the same `400 sign_in_failed`, so the form never reveals who has an account. `GET /auth/providers` answers `{"data": {"sso": false}}` when no provider is configured, and the Studio hides the single sign-on button accordingly.

Operators can make accounts from the terminal. `colophon admin account` creates or resets one, and `--admin` makes it an administrator; `colophon admin bootstrap --issuer password --subject <email>` makes the first administrator without a provider.

```sh
export COLOPHON_MIGRATION_DATABASE_URL=postgres://…
COLOPHON_ACCOUNT_PASSWORD='…' colophon admin account \
  --email editor@example.com --admin
```

Re-running the command replaces the password, so it doubles as a recovery tool.

Read more: [Authentication & API tokens](https://docs.colophon.404human.dev/api/authentication/) · [Installation](https://docs.colophon.404human.dev/installation/)

### Queued work is bounded per project and per installation, and dead rows are swept hourly

5 Nov 2026 · Improvement · Self-hosting · https://docs.colophon.404human.dev/changelog/#2026-11-05-bounded-work-and-table-retention

Two bounds now stop queued work growing without end. A project holds at most 10,000 unfinished jobs across delivery, uploads, bulk edits and schema migrations, and an installation holds at most 1 GiB of pending job data such as keys, manifests and migration plans. A request that would pass either bound is refused before anything is stored: `503 unavailable` with `Retry-After` and `details.reason` `work_full` or `payload_full`. Work drains as workers finish it, so retrying after the delay is the fix.

The worker also sweeps dead state every hour (`COLOPHON_TABLE_SWEEP_MS`), at most 500 rows a table per pass, oldest first: finished jobs, schedules, probe observations and idempotency records after 30 days; the audit log, settled budget records, and sessions, personal tokens, invitations and setup codes 90 days after they lapse.

Why it matters: a stuck destination or a runaway script can't fill the database, and a long-running installation stays the size of its content. History is never swept: revisions, publications, tombstones, comments, tasks and the deletion ledger stay, and open or uncertain budget records are kept.

```json
{"error": {"code": "unavailable", "message": "…", "request_id": "…",
  "details": {"reason": "work_full"}}}
```

Read more: [Errors](https://docs.colophon.404human.dev/api/errors/) · [Configuration](https://docs.colophon.404human.dev/self-hosting/configuration/)

### Site users can sign in with a magic link sent by email

5 Nov 2026 · Feature · API, Self-hosting · https://docs.colophon.404human.dev/changelog/#2026-11-05-magic-links

Visitors to your site can now sign in, or sign up, without a password. Your site asks Colophon for a link, Colophon emails it, and the visitor lands back on your site with a single-use token that lasts 15 minutes.

`POST /audience/v1/{project}/magic-link` answers the same `202` whether or not the address has an account, so it reveals nothing about who is registered. The link is your `return_to` page with `token=` added. Your site spends it with `POST /audience/v1/{project}/magic-link/{token}`: an existing account gets its session, an unknown address becomes a new site user in the project's open sign-up role, and a used, expired or unknown token answers `403 magic_link_invalid`. Only the token's hash is stored.

```sh
curl -X POST http://localhost:8080/audience/v1/{project}/magic-link \
  -H 'Content-Type: application/json' \
  -d '{"email":"reader@example.com","return_to":"https://example.com/signed-in"}'
```

To send real mail, set `COLOPHON_MAIL_PROVIDER=resend`, `COLOPHON_MAIL_FROM` and `COLOPHON_RESEND_API_KEY` together; a partial set stops the server at start-up. Since 2026-11-17 a link lands only on an origin the project lists.

Read more: [Authentication & API tokens](https://docs.colophon.404human.dev/api/authentication/) · [Configuration](https://docs.colophon.404human.dev/self-hosting/configuration/)

### Published content has a public live stream, so open pages refresh without a rebuild

5 Nov 2026 · Feature · API · https://docs.colophon.404human.dev/changelog/#2026-11-05-public-live-updates

A site can now hear when something is published. `GET /content/v1/{project}/{environment}/events` is an anonymous server-sent-events stream: it sends `hello` once, then a `change` frame each time a release lands in that environment. Draft saves never reach it, and a burst of release activity folds into one frame.

The frame carries nothing but its own existence: no ids, no collections, no content. A reader only learns to re-read the delivery API with whatever credentials it already has, so gated entries cannot leak through the stream. The answer is `Cache-Control: no-store`, and the stream ends after its lifetime so clients reconnect.

The intended shape is one stream per site server, not per visitor: your server listens once and tells its open browser tabs to refresh, which keeps the CMS's stream count proportional to sites, not readers.

```sh
curl -N http://localhost:8080/content/v1/{project}/{environment}/events
```

```text
event: hello
data: {}

event: change
data: {}
```

On each `change`, fetch the page's data again from `/content/v1`; the new answer names the new generation.

Read more: [Live events](https://docs.colophon.404human.dev/api/live-events/)

### Replace an upload with new bytes, and every earlier version stays addressable

5 Nov 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-11-05-replace-an-upload

An upload can now be replaced. `POST /api/v1/projects/{project}/environments/{environment}/assets/{asset}/replace` takes the new file with the same headers as an upload and answers `202`. The worker checks the new bytes like any upload, and only if they pass does the asset's current version move to them; a refused file leaves the current version serving. Only a usable asset takes a replacement.

Why it matters: each verified version is stored under its own SHA-256 and never overwritten, so bytes a release published can't be silently replaced or deleted while anything pins them. `GET …/assets/{asset}` lists every verified version, oldest first, and the media origin serves both kinds of address: `/media/v1/{project}/{environment}/{asset}` for the current version, and `…/{asset}/{sha}` for one exact version, with its renditions under `…/{sha}/{name}`.

The same day, the Studio gained a Media page in the project sidebar: every upload with its thumbnail, state, dimensions and size, uploading, and a confirmed delete that names the entries still using a file.

```sh
curl -X POST http://localhost:8080/api/v1/projects/{project}/environments/production/assets/{asset}/replace \
  -H "Authorization: Bearer $COLOPHON_TOKEN" -H "Content-Type: image/webp" \
  -H "X-Colophon-File-Name: hero.webp" -H "Idempotency-Key: $(uuidgen)" \
  --data-binary @hero.webp
```

Read more: [Media library](https://docs.colophon.404human.dev/studio/media-library/)

### Site users and gated content: visitors sign up, and each entry says who may read it

5 Nov 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-11-05-site-users-and-gated-content

A project can now have an audience: site visitors with accounts of their own, separate from staff. They sign up and sign in with email and password at `/audience/v1/{project}/signup` and `/signin`, getting a session as a cookie or as the `session` token for a bearer header; `/me` and `/signout` complete the set. Staff manage audience roles, users and their sessions under `/api/v1/projects/{project}/audience/…` with the `audience.manage` permission. Signup may choose only a role marked `self_assign`.

Every entry now carries a `visibility`, set with `?visibility=` on a create or save: `public` (the default), `authenticated`, or `role:<name>`. A release publishes the gate its revision carried, and PostgreSQL row-level security enforces it in delivery. Anonymous readers see public rows only; a gated row answers `404`, like one never published. A visitor's read bypasses the shared cache (`Colophon-Cache: bypass`, `Cache-Control: private`), so gated content never enters it.

In the Studio, the sidebar's People group now holds Members and a new Audience page (visitors, roles, disabling, sign-in activity), and visitor sign-ups and sign-ins are recorded in the audit log.

```sh
curl http://localhost:8080/content/v1/{project}/production/posts \
  -H "Authorization: Bearer $SITE_SESSION"
```

Read more: [Delivery API](https://docs.colophon.404human.dev/api/delivery/) · [Authentication & API tokens](https://docs.colophon.404human.dev/api/authentication/) · [Members and roles](https://docs.colophon.404human.dev/studio/members-and-roles/)

### An API token can never approve a publish request that a token submitted

4 Nov 2026 · Security · API · https://docs.colophon.404human.dev/changelog/#2026-11-04-agents-cannot-approve-their-own-work

A project API token can no longer approve a publish request (`changesets` in the API) that any API token submitted. An approval sent to `POST /api/v1/projects/{project}/environments/{environment}/changesets/{changeset}/reviews` answers `403` with `details.reason` `agent_self_review`, at the single review and at every named review stage alike.

Why it matters: a token holding both review and publish permissions could otherwise submit, approve and publish its own work with no person involved. Checking only for the same token would not help, because a second token costs nothing to make, so the rule looks at the kind of credential on both sides. It runs on the server, inside the review's own transaction, so it holds for MCP clients, scripts and any other HTTP client alike.

What a token may still do: ask for changes on any publish request (`"decision": "request_changes"`), approve a person's publish request when its permissions include `content.review`, and publish a request a person approved when it holds `content.publish`. People reviewing their own requests are not affected.

```json
{"error": {"code": "forbidden", "request_id": "…",
  "message": "an API token can't approve a changeset an API token submitted; it needs a person's approval",
  "details": {"reason": "agent_self_review"}}}
```

Read more: [MCP server](https://docs.colophon.404human.dev/mcp/) · [Authentication & API tokens](https://docs.colophon.404human.dev/api/authentication/)

### API tokens can carry limits: requests a minute, and writes and jobs a day

4 Nov 2026 · Feature · API · https://docs.colophon.404human.dev/changelog/#2026-11-04-api-token-limits-and-budgets

A project API token can now carry `limits`, set when it is created or later with `PATCH /api/v1/projects/{project}/tokens/{token}`. Every ceiling is optional:

- `requests_per_minute` (1–100,000): past it, the token's requests answer `429 rate_limited` with `Retry-After`.
- `documents_per_day` (1–1,000,000) counts entry creates, saves, translations and imported items over a rolling day; `max_concurrent_jobs` (1–64) caps the delivery jobs its publishes hold at once. Past either, the write is refused with `403` and `details.reason` `budget_exceeded` before it commits.
- `tokens_per_day` and `cost_per_day_micros` are ceilings for model-provider usage; they are stored and reported, and no Colophon feature consumes them today.

Why it matters: a looping script or agent can't flood the API or rewrite a project overnight. Budgets are counted in PostgreSQL inside the transaction that accepts the work, so parallel requests can't overspend them. People are never limited this way.

`GET …/tokens/{token}` shows the limits and current `usage`; `{"limits": null}` removes them. Token management takes a person's credential:

```sh
curl -X PATCH http://localhost:8080/api/v1/projects/{project}/tokens/{token} \
  -H "Authorization: Bearer $PERSONAL_TOKEN" -H "Content-Type: application/json" \
  -d '{"limits": {"requests_per_minute": 60, "documents_per_day": 500}}'
```

Read more: [Rate limits](https://docs.colophon.404human.dev/api/rate-limits/) · [Authentication & API tokens](https://docs.colophon.404human.dev/api/authentication/)

### Bulk edits as a manifest of exact entries, applied one item at a time

4 Nov 2026 · Feature · API · https://docs.colophon.404human.dev/changelog/#2026-11-04-bulk-jobs

`POST /api/v1/projects/{project}/environments/{environment}/bulk` takes a manifest for one collection: up to 100 items and 1 MiB a chunk, up to 10,000 items a job. Each item names a stable `key`, the `entry`, the `expected_revision` the change is based on, and an `op`: `update` with new content, `set` one field, `move` a value, or `delete`. Later chunks go to `…/bulk/{job}/items` under `If-Match`, and `seal` starts the run.

Why it matters: a worker applies each item in its own transaction, as the person or token that submitted it, rechecking permissions and the base revision. An entry edited since gets `conflict`, never an overwrite. Outcomes are `applied`, `conflict`, `refused` or `skipped`, and a retried chunk adds nothing twice. Revoking the submitting token, or removing the member, stops the run. An interrupted client reads `GET …/bulk/{job}/items` in key order and carries on from there; `POST …/bulk/{job}/cancel` skips what is still pending.

Bulk jobs change drafts only; publishing stays a publish request.

```json
{"collection": "posts", "seal": true, "items": [
  {"key": "retag-1", "entry": "<entry id>", "expected_revision": "<revision id>",
   "op": {"op": "set", "path": "section", "value": "News"}}
]}
```

Read more: [Management API](https://docs.colophon.404human.dev/api/management/)

### Every CLI command's JSON output is one versioned envelope, and lists stream line by line

4 Nov 2026 · Feature · CLI · https://docs.colophon.404human.dev/changelog/#2026-11-04-cli-json-envelope-and-new-commands

Every `colophon` command's `--json` now prints one object of a fixed shape: `{"version": 2, "command": "content list", "data": …}` on success, and the same object with `error` in place of `data` on failure. An API refusal is carried whole (`code`, `message`, `details`, `request_id`), so a script reads exactly what the server said, and the exit code still names the class of failure: 2 usage, 3 denied, 4 conflict, 5 unavailable, 6 internal.

List commands take `--jsonl` and print one envelope per item, following `next_cursor` page by page without holding more than a page in memory: `content list`, `content query`, `release list`, `migration list`, `migration items`, `comment list` and `task list`.

New the same day: `colophon content query` runs a query document against a collection; `colophon release list` and `colophon release show GENERATION` read releases and their receipts; and `colophon mcp` serves the MCP server on standard input and output, configured by `COLOPHON_SERVER`, `COLOPHON_TOKEN` and `COLOPHON_PROJECT`.

```sh
colophon content list posts --project my-site --jsonl | jq -r '.data.id'
colophon release show 12 --project my-site --json
```

Read more: [The colophon CLI](https://docs.colophon.404human.dev/cli/)

### Comments pinned to the version you read, and tasks for the editorial team

4 Nov 2026 · Feature · API, Studio, CLI · https://docs.colophon.404human.dev/changelog/#2026-11-04-comments-and-tasks

Editors can now discuss an entry and hand work to each other inside Colophon.

A comment is anchored to one saved version (revision) of an entry, and optionally to a field such as `author` or `sections/2/byline`. Revisions never change, so a comment always refers to exactly what its author was reading, even after the draft moves on. Comments are kept word for word: they can be resolved and reopened, never edited or deleted. A task names an entry (and optionally a revision or a publish request), has a title, an assignee and a status of `open`, `done` or `cancelled`, and is changed under `If-Match`, so two people can't overwrite each other's update (`409 task_moved`).

Both follow the entry's own permissions, including "only their own" roles, and stay readable after the entry is deleted.

In the Studio, the entry editor has a **Comments** tab for the version on screen, and the project has a **Tasks** page. From the terminal:

```bash
colophon comment create posts {entry} --project my-site --revision {revision} --field title --body "Shorter, please?"
colophon task create --project my-site --entry {entry} --title "Check the quotes" --assignee {identity}
colophon task list --project my-site --assignee me --status open
```

The API routes are `…/entries/{entry}/comments` (with `/resolve` and `/reopen`) and `…/tasks`.

Read more: [Comments and tasks](https://docs.colophon.404human.dev/studio/comments-and-tasks/)

### Encrypted backups with continuous WAL archiving, and a staged restore that holds unsent work

4 Nov 2026 · Feature · Self-hosting · https://docs.colophon.404human.dev/changelog/#2026-11-04-encrypted-backups-and-restore

The backup tooling shipped with Colophon now captures encrypted base backups of the whole PostgreSQL cluster, with continuous WAL archiving (a segment at least every minute) aimed at a 15-minute recovery point. Backups run as a replication-only database role, are encrypted from a passphrase file, and are checked with `pg_verifybackup` at capture and again after decryption. The daily run creates and verifies a backup, copies the deletion ledger beside it, keeps the newest verified backup of each of the last 7 days and 4 weeks, and writes an audit line. A backup that fails verification is never pruned.

A restore runs on clean, separate infrastructure in six stages, each gated on the last: decrypt, verify the schema against the binary, start a new recovery epoch so old cache generations and worker leases can't act, replay deletions made after the backup, hold every unfinished delivery job, then serve.

Why it matters: a restore can't fire a webhook twice or bring a deleted entry back. The database steps are CLI commands:

```sh
colophon admin migrate-status   # current, behind, or exit 4: the schema is newer than this binary
colophon admin restore jobs     # what was held, for you to reconcile
colophon admin restore resume   # only after reconciling
```

Read more: [Backups and restore](https://docs.colophon.404human.dev/self-hosting/backups/)

### Read drafts with GraphQL, through the same query engine as REST

4 Nov 2026 · Feature · API · https://docs.colophon.404human.dev/changelog/#2026-11-04-graphql

Each collection now answers GraphQL at `POST /api/v1/projects/{project}/environments/{environment}/collections/{collection}/graphql`, with a body of `{"query", "operationName"?, "variables"?}` and a query of at most 8 KiB. The schema is built for each request from your content types and your role: `entries(where, orderBy, first, after)` returns `nodes`, `pageInfo { endCursor hasNextPage }` and `applied { query queryHash }`, and `entry(id)` returns one draft or `null`. Collections the role can't read are not in the schema.

Why it matters: this is not a second read path. Every call compiles to the same bounded query document that `POST …/entries/query` runs, through the same permission checks, so both answer the same rows with the same `queryHash`. `where` and `orderBy` take only fields the content type marks as indexed, and a refusal arrives as a GraphQL error whose `extensions.code` and `extensions.pointer` are the codes REST uses.

GraphQL is read-only: writes stay on REST with `If-Match` and `Idempotency-Key`, and public reads stay on `/content/v1`.

```graphql
{
  entries(where: { section: { eq: "News" } }, orderBy: [{ field: rating, dir: DESC }], first: 10) {
    nodes { id title author { title } }
    pageInfo { endCursor hasNextPage }
  }
}
```

Read more: [GraphQL](https://docs.colophon.404human.dev/api/graphql/)

### Export a collection as JSON Lines and import it back, or bring entries from Strapi and Sanity

4 Nov 2026 · Feature · API, CLI · https://docs.colophon.404human.dev/changelog/#2026-11-04-import-and-export-with-strapi-and-sanity

`GET /api/v1/projects/{project}/environments/{environment}/collections/{collection}/export` streams every draft of a collection as JSON Lines (`application/jsonlines`), one content document per line. `POST …/import` takes that file back, or a JSON array, a Strapi v4 or v5 export, or Sanity's NDJSON, mapping each document onto your content type's fields. Up to 512 items land in one transaction, or none do. An item carrying the id of a live entry updates that entry's draft; the rest are created.

Why it matters: moving content between projects, or in from another CMS, no longer needs a script per source. `?dry_run=true` runs the whole import and rolls it back, answering a plan per item (`would_create`, `would_update`, `skipped`, or `invalid` with its refusal) plus any `unmapped` fields, and needs no `Idempotency-Key`. A real import requires one, so a retry can't import twice. `?type=` takes one Sanity `_type` from a mixed file. An export needs a role that reads every field.

From the terminal:

```sh
colophon content export posts --project my-site > posts.jsonl
colophon content import posts --project my-site --file posts.jsonl --dry-run
colophon content import posts --project other-site --file sanity.ndjson --type post
```

Read more: [Management API](https://docs.colophon.404human.dev/api/management/) · [The colophon CLI](https://docs.colophon.404human.dev/cli/)

### The Studio's lists update live as other people work, over a server-sent events stream

4 Nov 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-11-04-live-lists

When a colleague saves an entry, opens a publish request or publishes a release, your Studio now shows it without a reload or a poll: entry lists, publish requests, receipts, tasks and the rest refresh themselves within moments of the change committing. A save on an entry you have open is still a conflict for you to resolve, never a silent overwrite.

The same stream is open to your own tools. Any member or project API token can subscribe:

```bash
curl -N http://localhost:8080/api/v1/projects/{project}/environments/{environment}/events \
  -H "Authorization: Bearer $COLOPHON_TOKEN"
```

It sends `hello`, then a `change` frame naming only what kind of thing changed, such as `{"k":"entries","c":"posts"}`, never an id or any content. Refetch through the API you already use, so what you see is what your role may read. If hints may have been missed, the stream sends `resync`: reload what you show. It never replays.

Streams are bounded: past 8 for one credential the answer is `429 rate_limited` with `Retry-After`, and past the project's or server's limit, `503`. A stream ends cleanly after 30 minutes so clients reconnect, and a member removed from the project, or a revoked token, loses the stream within minutes.

Read more: [Live events](https://docs.colophon.404human.dev/api/live-events/)

### An OpenAPI 3.1 document describes every route, served at /openapi.json

4 Nov 2026 · Feature · API · https://docs.colophon.404human.dev/changelog/#2026-11-04-openapi-document

Colophon now serves an OpenAPI 3.1 document for its whole HTTP surface: the management API under `/api/v1`, sign-in under `/auth`, `/me`, public delivery under `/content/v1`, media under `/media/v1`, the health checks, `/version` and the document itself. It is emitted from the same route table the server's router is built from, so a route can't exist without being described, and a described route can't be missing. A copy is kept in the repository, and a test fails when the two differ.

Why it matters: you can generate a typed client, browse the API in any OpenAPI viewer, and check a request's shape before writing code. Every failure points at the one error envelope, and each kind of credential has its own security scheme.

How to use it: `GET /openapi.json` needs no sign-in. It answers with `Cache-Control: public, max-age=300` and an `ETag`; send that back in `If-None-Match` and an unchanged document answers `304 Not Modified`.

```sh
curl -s -D - -o openapi.json http://localhost:8080/openapi.json | grep -i etag
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/openapi.json \
  -H 'If-None-Match: "<etag from above>"'   # 304
```

Read more: [API reference](https://docs.colophon.404human.dev/api/reference/)

### Filter, sort and select fields with one query document, on drafts and published content

4 Nov 2026 · Feature · API · https://docs.colophon.404human.dev/changelog/#2026-11-04-query-language-and-depth

Collections can now be queried with a small JSON document posted to `…/query`: `filters` (`eq`, `in`, `lt`, `lte`, `gt`, `gte`, `contains`), `sort`, `fields`, `limit` and `depth`. The same document runs on published content at `/content/v1` (pinned to a release with `?generation=`) and, for signed-in callers, on current drafts at `POST /api/v1/projects/{project}/environments/{environment}/collections/{collection}/entries/query`.

```bash
curl -X POST "http://localhost:8080/content/v1/{project}/{environment}/posts/query" \
  -H "Content-Type: application/json" \
  -d '{"filters": [{"field": "category", "op": "eq", "value": "travel"}],
       "sort": [{"field": "published_on", "dir": "desc"}],
       "fields": ["title", "author"], "limit": 10, "depth": 1}'
```

Queries stay fast and predictable because they are bounded: you can only filter or sort on fields the content type marks `"index": true` (`field_not_indexed` otherwise), with at most 8 filters and 4 sort keys. `depth` (0–2) replaces each top-level single reference with the linked entry's `id`, `title` and `content`. Every answer echoes the canonical query and its `query_hash` in `applied`, and `next_cursor` only works for that same query (`foreign_cursor`).

On drafts, results respect field-level permissions: filtering or sorting on a field your role can't read is `422 field_not_readable`, and `hidden_fields` names what a row left out.

Read more: [Delivery API](https://docs.colophon.404human.dev/api/delivery/) · [Management API](https://docs.colophon.404human.dev/api/management/)

### Agents can reach the MCP server over HTTP, signed in with a project API token

4 Nov 2026 · Feature · API · https://docs.colophon.404human.dev/changelog/#2026-11-04-remote-mcp

The API itself now serves Colophon's MCP server at `POST /api/v1/projects/{project}/environments/{environment}/mcp`, over MCP's Streamable HTTP transport (protocol `2025-11-25`). An agent host that supports remote servers points at that URL with a project API token; nothing else needs installing.

Why it matters: it is the same server as the local `colophon mcp` process, not a second one. Tools, answers and refusals are identical on both, and every tool call runs through the API's own routes under the same token, so the boundary holds: agents read, query and write drafts, comments and tasks, and open publish requests, but never approve, publish or drive a migration.

How it works: the first `initialize` answers with an `Mcp-Session-Id` header, which later requests send back with `MCP-Protocol-Version: 2025-11-25`; `DELETE` on the same URL ends the session. Only project API tokens may connect: a browser session or personal token answers `403` with reason `api_token_required`. Sessions are capped per token (`429`) and per project and server (`503`), expire when idle, and stop working when the token is revoked.

```sh
curl -X POST http://localhost:8080/api/v1/projects/{project}/environments/production/mcp \
  -H "Authorization: Bearer $COLOPHON_TOKEN" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"demo","version":"1"}}}'
```

Read more: [MCP server](https://docs.colophon.404human.dev/mcp/)

### Review stages: several named approvals before a publish request can go live

4 Nov 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-11-04-review-stages

An environment can now name an ordered list of review stages, such as Editor, Legal and Fact-check. A publish request (`changesets` in the API) publishes only once every stage has an approval on its current content, in any order. A request for changes at any stage blocks it until a newer approval clears it, and any edit to the content makes earlier approvals stale, as before. A stage marked `different_reviewer` can't be approved by the person who made the request. An environment with no stages keeps the single review it always had.

In the Studio, **Settings → Review stages** edits the list, and a publish request's page shows each stage in order with its state (`pending`, `changes_requested`, `approved` or `approval_expired`) and who decided it. Every review names the stage it decides.

Through the API, replace the whole list under its `ETag` (you need permission to change the schema):

```bash
curl -X PUT http://localhost:8080/api/v1/projects/{project}/environments/{environment}/review-stages \
  -H "Authorization: Bearer $COLOPHON_TOKEN" -H 'If-Match: "sha256:…"' \
  -H "Idempotency-Key: stages-2026-11-0001" -H "Content-Type: application/json" \
  -d '{"stages": [{"key": "editor", "name": "Editor"},
                  {"key": "legal", "name": "Legal", "different_reviewer": true}]}'
```

A review then sends `{"decision": "approve", "stage": "legal"}`; leaving out `stage` where stages exist is `422 stage_required`.

Read more: [Publishing](https://docs.colophon.404human.dev/studio/publishing/)

### Change a content type that existing entries don't fit: plan, dry run, approve, apply

4 Nov 2026 · Feature · API, Studio, CLI · https://docs.colophon.404human.dev/changelog/#2026-11-04-schema-migrations

A content-type change that stored entries wouldn't pass (`422 needs_migration`) no longer has to stop at a refusal. You can plan a migration: Colophon dry-runs the new definition against every draft and open publication of the collection and lists each entry as `ok` or `needs_input`, with the problem it would hit. Nothing is written until the plan is approved and applied.

Approve and apply bind to the plan's hash (its `ETag`), so you apply exactly what you looked at; if the plan has moved, the answer is `409 plan_moved`. Applying answers `202` and a worker converts the entries one at a time, resuming after a crash without doing any twice. The plan ends `done`, or `blocked` with its reason, and `republish_required` lists the published entries to publish again. While it runs, the type can't be changed elsewhere (`migration_in_progress`). For an entry the target can't derive, give it a replacement with `PUT …/migrations/{migration}/items/{entry}`.

In the Studio, the type builder's refusal offers **Plan a migration for this change**, and a **Migrations** section shows each plan's counts, items and a resolve dialog. From the terminal:

```bash
colophon migration plan posts --project my-site --file posts-v4.json
colophon migration show {migration} --project my-site
colophon migration approve {migration} --project my-site --if-match <plan hash>
colophon migration apply {migration} --project my-site --if-match <plan hash>
```

Read more: [Management API](https://docs.colophon.404human.dev/api/management/) · [The colophon CLI](https://docs.colophon.404human.dev/cli/)

### A TypeScript SDK whose types come from the OpenAPI document

4 Nov 2026 · Feature · SDK · https://docs.colophon.404human.dev/changelog/#2026-11-04-typescript-sdk

`@colophon-cms/sdk` is a TypeScript client for Colophon. Its types are generated from the committed OpenAPI document, with a check that fails when they drift; the client on top is small and hand-written. It covers what a site, tool or agent calls most: entries and revisions, content types, publish requests, releases and receipts, comments, tasks, and public delivery.

Why it matters: the types know which writes need a precondition, so `saveEntry` won't compile without `ifMatch` and `idempotencyKey`, and a retried save can neither overwrite someone's edit nor apply twice. Every failure is an `ApiError` with the error envelope's `code`, `requestId` and `details`. The client attaches the credential you give it and never signs in by itself.

How to use it: the package is prepared for the first npm release; until then, build it from a checkout of the repository with `npm run build -w @colophon-cms/sdk`.

```ts
import { Client, newIdempotencyKey } from '@colophon-cms/sdk';

const client = new Client({ baseUrl: 'http://localhost:8080', token });
const env = client.environment(projectId); // production by default
const { data: draft, response } = await env.getEntry('posts', entryId);
await env.saveEntry('posts', entryId, { ...draft.content, title: 'New title' },
  { ifMatch: response.etag!, idempotencyKey: newIdempotencyKey() });

const site = client.delivery(projectId).atGeneration(42); // every read from one release
```

Read more: [TypeScript SDK](https://docs.colophon.404human.dev/sdk/)

### Upload images: verified before anyone sees them, served from a public media address

3 Nov 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-11-03-image-uploads-and-media-origin

Colophon now stores images. An upload (PNG, JPEG or WebP, up to 20 MiB) lands in quarantine and answers `202` with state `quarantined`. A worker then checks the real file signature, decodes it within size limits, strips its metadata and promotes it to `usable`, or marks it `rejected` with a reason. A verified image also gets `w320` and `w1280` renditions when it is wider than those.

```bash
curl -X POST http://localhost:8080/api/v1/projects/{project}/environments/{environment}/assets \
  -H "Authorization: Bearer $COLOPHON_TOKEN" -H "Idempotency-Key: upload-harbour-0001" \
  -H "Content-Type: image/jpeg" -H "X-Colophon-File-Name: harbour.jpg" \
  --data-binary @harbour.jpg
```

Content types gain an `asset` field: one upload's id, or a bounded list with `"many": true`. A draft may name an image that is still being checked, but a release refuses one that isn't usable (`409 asset_not_usable`), so readers only ever get verified bytes. Those are served without sign-in at `GET /media/v1/{project}/{environment}/{asset}` and `…/{asset}/w320`.

In the Studio, an image field is a picker: **Choose an image** opens the project's uploads, shows each one's state, and uploads a new file in place.

Deleting is staged: `DELETE …/assets/{asset}` answers `202` (requested, not gone), and is refused `409 still_referenced` while a draft or any release names the image.

Read more: [Media library](https://docs.colophon.404human.dev/studio/media-library/)

### Roll back to an earlier release, reviewed like any other publish

3 Nov 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-11-03-rollback-as-a-new-release

You can now restore what an earlier release published. A rollback is not a jump back in time: it opens an ordinary publish request (`changesets` in the API) that republishes every entry that release had live, and takes down entries that are live now but weren't then. It is submitted, approved on its exact content and published like any other, and publishing it makes a new release with the next generation number. Your history stays whole, and the review rule still applies.

In the Studio, a release's receipt has **Roll back to this release** for anyone who may update content, on any release before the current one. It opens the restore, and its page says which release it restores.

Through the API:

```bash
curl -X POST http://localhost:8080/api/v1/projects/{project}/environments/{environment}/releases/{generation}/rollback \
  -H "Authorization: Bearer $COLOPHON_TOKEN" -H "Idempotency-Key: rollback-to-12-0001" \
  -H "Content-Type: application/json" -d '{"title": "Rollback to release 12"}'
```

The answer is `201` with the publish request, whose `rollback_generation` names the release it restores. A generation outside the earlier releases is `422 invalid_generation`; if nothing would change, `422 already_at`. Content taken down since that release is not brought back.

Read more: [Rollback](https://docs.colophon.404human.dev/studio/rollback/) · [Publishing](https://docs.colophon.404human.dev/studio/publishing/)

### A website starter: pages built from sections, a menu and a theme, with a Look tab

3 Nov 2026 · Feature · Studio · https://docs.colophon.404human.dev/changelog/#2026-11-03-website-pages-menu-and-theme

The Studio can now add a ready-made website structure to a project. On **Content types**, choose **A website**: a dialog lists what it will add and what is already there, then **Add to this project** creates a `pages` collection, a `navigation` single type, a `theme` single type and a seeded Home page.

Nothing here is new machinery. A page's `sections` field is an ordinary page-sections field with six layouts (hero, rich text, features, testimonial, call to action, and questions and answers), the menu links to pages through reference fields that can't dangle, and the theme's colours, corner radii, shadows and fonts are an entry like any other. So pages and the theme get drafts, history, publish requests and releases, and republishing the theme changes the whole site's look in one release. Running the starter again only adds what is missing.

Pages and the theme entry gain a **Look** tab beside Content and History. It shows the page exactly as the shared site renderer builds it, from the draft on screen (saved or not), the menu and the theme, and redraws as you type. Click a section to jump to its form. On the theme, the Look tab checks each colour pair's contrast against WCAG AA.

Read more: [Concepts](https://docs.colophon.404human.dev/concepts/) · [Preview](https://docs.colophon.404human.dev/studio/preview/)

### Delete a collection you no longer need, once nothing of it remains

2 Nov 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-11-02-delete-an-empty-collection

A collection can now be deleted for good, together with every version of its definition, and its name is free to use again. In the Studio, the content type's page has a two-step **Delete collection…** button.

Deletion is only allowed while nothing of the collection remains, so no revision, publish request or release ever points at a type that has gone. The answer is `409` with a reason you can act on:

- `still_referenced`: another content type has a reference field that links here; the message names it.
- `collection_not_empty`: the collection still has entries; the message counts them.
- `collection_has_history`: deleted entries left revisions that use its definition. Revisions are never rewritten, so a collection that has ever held an entry stays.

The request needs `If-Match` with the type's `ETag` and an `Idempotency-Key`, so a retry after a lost answer replays the deletion instead of answering 404.

```bash
curl -X DELETE http://localhost:8080/api/v1/projects/{project}/environments/{environment}/content-types/drafts-old \
  -H 'If-Match: "v3"' -H 'Idempotency-Key: delete-drafts-old-0001' \
  -H "Authorization: Bearer $COLOPHON_TOKEN"
```

The answer is `200` with `{"data": {"slug": "drafts-old", "removed": true}}`.

Read more: [Management API](https://docs.colophon.404human.dev/api/management/)

### Two-way links: a reference field can be mirrored on the entries it points to

2 Nov 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-11-02-inverse-references

A reference field can now name an `inverse`: a reference field on the target collection that points back. When you link a post to a writer, the writer's `posts` field gains the post in the same save; unlink it and the writer loses it; delete the post and it leaves every mirror.

This is the link editors reach for first (posts and writers, products and categories), and you no longer keep both sides by hand. Both sides commit together or not at all. The forward link stays the truth: if a mirror can't be written, for example because the far field no longer points back, the forward save still succeeds and the link is simply one-way.

In the Studio, open the reference field's settings and pick the field under **Mirrored on … by**. To offer one, first add a link back to this type on the other collection. In a definition:

```json
{ "id": "writers", "label": "Writers", "type": "reference",
  "to": "writers", "many": true, "inverse": "posts" }
```

Only top-level reference fields may mirror. The named field must exist on the target, be a reference, and point back at this collection; otherwise the definition is refused `422 invalid_inverse` at `/fields/{n}/inverse`.

Read more: [Linked entries](https://docs.colophon.404human.dev/studio/linked-entries/)

### Write an entry in several languages, one linked version per locale

2 Nov 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-11-02-locales-and-translations

An entry can now carry a locale tag such as `en` or `pt-BR`, and its translations are grouped together, one live entry per tag. Each translation is a full entry with its own draft, slug, history and publish requests, so the French version can be published while the German one is still being written.

In the Studio's entry editor, **Locale** sets the entry's own tag (empty means the project's default), and the **Versions** card lists the group and adds one: type `fr`, choose **Add version**, and a copy of the current draft opens as its own entry, with a slug such as `my-post-fr`.

Through the API, `?locale=` rides create, save and list, and a new translation is one request:

```bash
curl -X POST "http://localhost:8080/api/v1/projects/{project}/environments/{environment}/collections/posts/entries/{entry}/localizations?locale=fr" \
  -H "Authorization: Bearer $COLOPHON_TOKEN" -H "Idempotency-Key: translate-post-fr-0001"
```

Drafts answer with `locale` and `localizations` (each sibling's id and tag). The source needs a tag of its own before it can start a group (`locale_required`). A tag already in the group is `409 locale_taken`, naming the entry that holds it; a malformed tag is `422 invalid_locale`. Published rows don't carry the tag: a site reads each translation as its own entry.

Read more: [Languages](https://docs.colophon.404human.dev/studio/languages/)

## October 2026

### Project API tokens with an exact kill switch, and an append-only audit log

28 Oct 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-10-28-api-tokens-and-audit-log

Scripts and integrations can now use a project API token instead of a person's sign-in. A token is `read-only`, `full-access` or `custom` (its own permission list, like a role), expires in 1 to 366 days, and acts as an identity of its own, so what it writes is attributed to it. The secret, prefixed `colophon_api_`, is shown once in the create answer and stored only as a hash. No token can manage members, roles or tokens, or read the audit log.

```http
POST /api/v1/projects/{project}/tokens
{"name": "Site build", "kind": "read-only", "expires_in_days": 90}
```

Send it as `Authorization: Bearer colophon_api_…`. It works on its own project's `/environments/…` routes; elsewhere it gets 403 `api_token_not_allowed`, another project answers 404, and a revoked or expired token 401. `DELETE /api/v1/projects/{project}/tokens/{token}` revokes it exactly: requests already running finish, and nothing starts after.

Every change to roles, memberships, invitations and tokens is written to the audit log in the same transaction; the API can only add to it and read it. Owners read it newest first at `GET /api/v1/projects/{project}/audit`, filtered by `action` (such as `token.revoked`) and `actor`, with `limit` and `cursor`. In the Studio, both live in Settings: *API tokens* and *Activity*.

Read more: [Authentication & API tokens](https://docs.colophon.404human.dev/api/authentication/) · [Studio settings](https://docs.colophon.404human.dev/studio/settings/)

### Custom roles, down to single fields and a member's own entries

28 Oct 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-10-28-custom-roles-and-field-permissions

Roles are now data you can shape. Every project starts with four built-in roles, `owner`, `developer`, `editor` and `publisher`, with the powers they always had, and owners can add their own in Settings → Roles. A role is a list of permissions: an action such as `content.update` or `content.publish`, a subject (one collection, or `*` for all), an optional field list, and an optional `own` condition that limits it to entries the member created.

A field list works both ways. A save that changes any other field is refused with 422 `field_not_permitted` at that field's pointer; a read leaves the other fields out and names them in `hidden_fields`. One evaluator decides for the API, the CLI and the Studio, and the Studio hides controls a role can't use while the server still decides.

```http
POST /api/v1/projects/{project}/roles
{"key": "copy-desk", "name": "Copy desk", "permissions": [
  {"action": "content.read", "subject": "*"},
  {"action": "content.update", "subject": "articles", "fields": ["title", "summary"]},
  {"action": "content.update", "subject": "notes", "condition": "own"}]}
```

Roles change under `If-Match` (`"v<version>"`). Any caller can ask what it may do with `GET /api/v1/projects/{project}/environments/{environment}/permissions`. The Studio's role editor is a grid of collections and actions, with a section for field lists and "only their own entries".

Read more: [Members and roles](https://docs.colophon.404human.dev/studio/members-and-roles/)

### Delete an entry, refused while anything still depends on it

28 Oct 2026 · Feature · API · https://docs.colophon.404human.dev/changelog/#2026-10-28-delete-an-entry

Entries can now be deleted through the API. A deletion leaves a tombstone: the entry disappears from every read, list and history, its URL name and any unique values become free, and its earlier versions and past releases are kept untouched. It needs `content.delete` on the entry (or the `own` condition and an entry you created), the draft's `ETag` as `If-Match`, and an `Idempotency-Key`, so a retry after a lost answer replays the same result.

```bash
curl -X DELETE \
  http://localhost:8080/api/v1/projects/{project}/environments/{environment}/collections/posts/entries/{entry} \
  -H "Authorization: Bearer $COLOPHON_TOKEN" \
  -H 'If-Match: <the draft ETag>' \
  -H "Idempotency-Key: $(uuidgen)"
```

The database refuses a deletion that would leave something dangling, and it decides every race. The answer is 409 with a reason:

- `entry_published`: readers still get it, so take it down in a publish request first;
- `still_referenced`: another entry links to it, listed in `details.referenced_by` (only collections you can read);
- `entry_in_changeset`: an unpublished publish request holds it, scheduled or not, listed in `details.changesets`.

A successful deletion answers 200 with `id`, `collection`, `revision_id`, `deleted_at` and `deleted_by`, and is recorded in the audit log.

Read more: [Management API](https://docs.colophon.404human.dev/api/management/)

### Set up a new installation from the Studio with a one-time setup code

28 Oct 2026 · Feature · Studio, Self-hosting · https://docs.colophon.404human.dev/changelog/#2026-10-28-first-run-setup-code

A new Colophon no longer needs someone with database access to make its first administrator. While nobody is an administrator, the server prints a one-time setup code to its terminal when it starts, never to the structured log or to any response. A signed-in person enters it on the Studio's home page, which sends it to `POST /api/v1/setup`, and becomes the administrator.

```http
POST /api/v1/setup
{"code": "XXXXX-XXXXX-XXXXX-XXXXX"}
```

The code lasts an hour, works once and is stored only as a hash. Attempts are limited (429 `rate_limited` with `Retry-After`), and wrong, used and expired codes all get the same 422 `setup_code_invalid`. Once anyone is an administrator the route answers 409 `already_set_up`, and later starts print nothing.

Alongside it, the Studio was reworked for editors who aren't developers. Its words come from one glossary: a changeset is a *publish request*, a revision a *version*, a slug a *URL name*, destinations are *website connections*. A project's first page is a short checklist (write, invite, connect the website, publish). Publishing one entry is one button: it publishes at once where the project lets you review your own work, and asks for review otherwise.

Read more: [Quick start](https://docs.colophon.404human.dev/quick-start/) · [Installation](https://docs.colophon.404human.dev/installation/)

### Groups, lists, page sections and shared components in content types

28 Oct 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-10-28-groups-lists-page-sections-and-components

Content types can now hold structure, not only flat fields:

- `object` groups nested `fields`, such as an address;
- `list` holds up to 100 values of one kind (`of`), never a list or page sections;
- `blocks` is a page builder: up to 100 items, each one of up to 20 named kinds of block with its own fields, marked by `_block`.

Structures nest at most three deep. A reference inside one is stored and checked like any other, with its path, such as `sections/1/author`.

```json
{"id": "tags", "label": "Tags", "type": "list", "of": {"type": "text", "max_chars": 30}, "max": 3}
```

A shared component is a named group of fields that many content types reuse, such as an SEO block. Create one with `POST …/components`, then use `{"type": "component", "component": "seo"}` wherever an object can go; the server copies the component's fields in, so every content type version stays a complete description of its content. Changing a component with `PUT …/components/{slug}` writes a new version of every content type that uses it, in one transaction and each checked against stored content. If one can't take the change, nothing changes, and the refusal names that type.

The Studio's builder makes groups, lists, page sections and components, and the editor fills them in.

Read more: [Concepts](https://docs.colophon.404human.dev/concepts/)

### An MCP server lets AI agents draft content, but never approve or publish it

28 Oct 2026 · Feature · API · https://docs.colophon.404human.dev/changelog/#2026-10-28-mcp-server-for-agents

Colophon now has a Model Context Protocol server, so an agent host can give an AI agent typed tools over your content. It speaks MCP over standard input and output, and it is a plain client of the same `/api/v1` the Studio and the CLI use, with a project API token as its only credential: an agent can do exactly what a script with that token can, and what it writes is attributed to the token.

```bash
COLOPHON_SERVER=http://localhost:8080
COLOPHON_TOKEN=colophon_api_…
COLOPHON_PROJECT={project}
```

Its tools read content types and entries, create and update drafts (sending the revision it read as `If-Match`), make a publish request and ask for its review. Writes carry an `Idempotency-Key`, and a refusal keeps the API's reason and field pointer.

Agents stop at proposals. No tool approves, publishes, unpublishes or schedules, or manages roles, members or tokens, whatever the token itself may do. The tool list follows the token's permissions, read from the new `GET /api/v1/projects/{project}/environments/{environment}/permissions`, which answers any caller's own permissions. Listing a tool grants nothing: the API still decides every call.

Read more: [MCP server](https://docs.colophon.404human.dev/mcp/)

### Seven new field types: email, URL, date, time, JSON, Markdown and colour

28 Oct 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-10-28-new-field-types

Content types can now use `email`, `url`, `date`, `time`, `json`, `markdown` and `color` fields, beside text, rich text, number, yes-or-no, choice and date-time. Any field may carry a `description` (help text, up to 500 characters), and text fields a `min_chars`.

Each type keeps one stored form that a browser can reproduce, so what you send round-trips byte for byte:

- `url`: `http` or `https` only, no credentials, stored as a browser's `new URL(text).href` writes it;
- `email`: checked for its shape, never for delivery;
- `date` is `YYYY-MM-DD`; `time` is `HH:MM` or `HH:MM:SS`;
- `json`: any value up to 64 KiB and 32 levels deep, keys sorted the way JavaScript sorts them;
- `markdown`: multi-line text with `max_chars`, rendered by your site;
- `color`: lowercase `#rrggbb`; an uppercase value is refused, not rewritten.

```json
{"id": "contact", "label": "Contact", "type": "email",
 "description": "Shown under the article"}
```

Changing a field's type is checked against stored content: a text field can become an email field when every stored value is an address. The Studio's builder offers every type, and the editor has a control for each.

Read more: [Concepts](https://docs.colophon.404human.dev/concepts/) · [Writing in the Studio](https://docs.colophon.404human.dev/studio/writing/)

### Entry requests stop re-reading their content type's definition from scratch

28 Oct 2026 · Improvement · Performance · https://docs.colophon.404human.dev/changelog/#2026-10-28-parsed-content-types-cached

Every entry read, save, list and history request checks content against its collection's content type, and each one used to parse that definition again. Benchmarks showed the parse costing more than the entry's own validation: 1.9 µs for a small type, 20.4 µs for a typical page type and 281 µs for a 100-field type, about half of it compiling text patterns.

Each server now keeps parsed content types in memory, keyed by the SHA-256 of the definition text it has just read from the database. A cache hit costs only that hash: 0.12 µs, 0.59 µs and 6.5 µs for the same three types. The definition itself is still read from the database on every request, so a cached parse can never be out of date: a changed content type is new text with a new key, and nothing needs to be invalidated.

The cache holds at most 1,024 types and 32 MiB of definition text, dropping the least recently used first; a definition larger than that is parsed every time and never kept.

Nothing changes in the API. Projects with large content types, many fields or text patterns see the biggest drop in time per request.

Read more: [Management API](https://docs.colophon.404human.dev/api/management/)

### Rate limits counted once across every server, and safe to run several servers

28 Oct 2026 · Feature · API, Self-hosting · https://docs.colophon.404human.dev/changelog/#2026-10-28-rate-limits-shared-across-servers

Every request to the management API (`/api/`, `/auth/`) now counts against its client address and its credential, and every public delivery request (`/content/`) against its address at a higher rate. Health checks, `/version` and the Studio's files never count. Over a limit, the answer is 429 `rate_limited` with `Retry-After` in seconds, before any work is done.

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 2

{"error": {"code": "rate_limited", "message": "…", "request_id": "…"}}
```

The counts live in Valkey, so several Colophon servers behind one load balancer share them. If Valkey is down or slow, each server applies the same limits on its own until it is back. Sessions, idempotency keys and caches were already shared, so any server can answer any request, and `/readyz` checks the database on a connection of its own, so a busy server isn't marked unready by mistake.

Defaults are 300 requests a second (burst 600) per address, 150 (300) per credential and 1,000 (2,000) for delivery; change them with `COLOPHON_RATE_LIMIT_PER_ADDRESS`, `COLOPHON_RATE_LIMIT_PER_CREDENTIAL` and `COLOPHON_RATE_LIMIT_DELIVERY` (for example `300/600`, or `off`). Behind a reverse proxy, list it in `COLOPHON_TRUSTED_PROXIES` so `X-Forwarded-For` names the real client; otherwise every visitor shares the proxy's count.

Read more: [Rate limits](https://docs.colophon.404human.dev/api/rate-limits/) · [Configuration](https://docs.colophon.404human.dev/self-hosting/configuration/)

### Link entries with reference fields that can never point at nothing

28 Oct 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-10-28-references-that-never-dangle

A `reference` field links an entry to entries of one collection: one, or up to 100 with `many`. Each version stores its links and the database checks them, so an id that names no entry of that collection is refused with 422 `reference_not_found` at the field's pointer.

```json
{"id": "author", "label": "Author", "type": "reference", "to": "authors"}
{"id": "related", "label": "Related", "type": "reference", "to": "articles", "many": true, "max": 5}
```

Releases keep links whole too. Publishing an entry that links to one nobody has published is refused with 409 `references_unpublished`, and taking down an entry that a published entry still links to is refused with 409 `still_referenced`. Doing both in one release works.

An entry's read now carries `referenced_by`, the entries that link to it, limited to collections your role can read, so nobody learns of entries they can't open. Pointing an existing field at a different collection is refused.

In the Studio, a link field is filled by searching titles, an entry shows what it is *Linked from*, a refused link names the entries in the way and says what to do, and the Studio warns before a take-down that would be refused.

Read more: [Linked entries](https://docs.colophon.404human.dev/studio/linked-entries/)

### Schedule a publish request for a local time in any time zone

28 Oct 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-10-28-scheduled-publishing

An approved publish request can now go live later. You choose the date and time as a wall clock shows it and an IANA time zone; Colophon keeps both, with the instant they resolve to. A time the clocks show twice or skip at a daylight-saving change is refused with 422 `ambiguous_local_time` or `skipped_local_time`, with both possible instants in `details.candidates`; send `"choice": "earlier"` or `"later"` to pick one.

```http
POST /api/v1/projects/{project}/environments/{environment}/changesets/{changeset}/schedule
If-Match: <the publish request's ETag>

{"local_time": "2026-12-01T09:00:00", "time_zone": "Europe/London"}
```

When it falls due, the worker publishes as the person who scheduled it, with every check a publish makes at that moment. An edit since approval, an expired approval, a role that can no longer publish or a URL name another entry holds blocks the schedule with the reason, and nothing is published. A run that starts more than a minute late is marked `delayed`, never reported as on time. API tokens can't schedule.

`GET …/schedules` lists pending and recently finished schedules; `DELETE …/schedules/{schedule}` cancels one (409 `schedule_ran` if it already ran). In the Studio, a publish request has a Schedule panel and the Releases page lists what is scheduled.

Read more: [Scheduling](https://docs.colophon.404human.dev/studio/scheduling/)

### Single types for one-of-a-kind content like site settings or a home page

28 Oct 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-10-28-single-types

A content type marked `"single": true` holds at most one entry per environment: a site's settings, its home page, its footer. The database is what enforces it, so however two creations race, the second is refused with 409 `single_exists`.

```http
POST /api/v1/projects/{project}/environments/{environment}/content-types
Idempotency-Key: 6f1c…

{"slug": "settings", "definition": {
  "name": "Settings", "title_field": "site_name", "single": true,
  "fields": [{"id": "site_name", "label": "Site name", "type": "text", "required": true}]}}
```

You can make an existing collection single while it holds at most one entry; with more, the change is refused with 422 `too_many_entries` at `/single`. Making it plural again just clears the flag. Older definitions keep their hashes, because the flag is written only when it is true.

In the Studio, a single type opens straight to its one entry instead of a list.

Read more: [Concepts](https://docs.colophon.404human.dev/concepts/)

### URL names for entries, and a content-type builder that checks your content first

28 Oct 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-10-28-slugs-and-content-type-builder

A content type can now have one `slug` field, which the Studio calls a *URL name*. A slug is 1 to 120 lowercase letters and digits in groups joined by single hyphens; anything else is refused with `invalid_slug`, never quietly rewritten. The Studio suggests one from the text field you name as its `source`. A slug belongs to one entry among drafts and one among what is published, and the database enforces it: a save gets 409 `slug_taken`, and a release that would publish a taken slug is refused whole.

```json
{"id": "slug", "label": "URL name", "type": "slug", "source": "title"}
```

Changing a content type is now checked against what you have stored, not only against the old definition. Removing a field, making one required or narrowing a limit goes through when every draft and published version still fits; otherwise `PUT …/content-types/{slug}` answers 422 `needs_migration` and names the first 20 entries in the way.

In the Studio, *Content types* has a place of its own in the navigation, shown to roles that may change them. A type is one row per field; *Add a field* opens a picker grouped as Basics, Links, Structure and Advanced; each field's settings open in a dialog, and changes wait behind one save bar.

Read more: [Concepts](https://docs.colophon.404human.dev/concepts/) · [Studio settings](https://docs.colophon.404human.dev/studio/settings/)

### The Studio starts from your work, and publishes several entries at once

28 Oct 2026 · Improvement · Studio · https://docs.colophon.404human.dev/changelog/#2026-10-28-studio-built-around-your-work

The Studio's home page is now *Your work*: for a project, the entries you started that aren't live, publish requests waiting for review, what is scheduled (and why a blocked schedule stopped), and the latest releases. Inside a collection, *Only mine* narrows the list to the entries you started.

From a collection's list you can pick several entries and publish them together as one release, or send them as one publish request for review if your role can't publish. An entry can be duplicated, an earlier version restored with *Restore this version* (it becomes the newest version, nothing is lost), and a live entry taken down.

What changed for every screen:

- refusals come from the API's reasons and are said in plain words, with what to do next;
- controls follow your role's permissions, and navigation shows only what you can read;
- a release's receipt says what needs attention and the safe next step;
- reviewing and publishing work on a phone;
- Settings has a left panel of pages (General, Roles, Website connections, API tokens, Activity), and making something opens a dialog;
- the entry page says where the entry stands once, in one line naming its release;
- *About Colophon* in the account menu shows which server and version you are using, for a problem report.

Read more: [Writing in the Studio](https://docs.colophon.404human.dev/studio/writing/) · [Publishing](https://docs.colophon.404human.dev/studio/publishing/) · [History](https://docs.colophon.404human.dev/studio/history/)

### Field rules: unique values, text patterns, defaults and conditional fields

28 Oct 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-10-28-unique-fields-patterns-defaults-and-conditions

Four rules for fields, checked by the server for the Studio, the CLI, scripts and agents alike:

- **Unique.** `"unique": true` on a top-level text, email, URL, number, date, time or date-time field. A value belongs to one entry among drafts and one among what is published, compared exactly as stored. The database enforces it: a save gets 409 `value_taken`, and so does a release that would publish a taken value.
- **Pattern.** A text field's `pattern` must match the whole value, in Rust `regex` syntax, which runs in time linear in the value, so no pattern can stall writes. A bad pattern is 422 `invalid_pattern`; a value that doesn't match, 422 `pattern_mismatch`.
- **Default.** `default` fills a field a new entry leaves out, on the server and only on creation, so a required field with a default may be left out.
- **Conditional.** `"when": {"field": "kind", "is": "video"}` makes a field apply only while a yes-or-no or choice field holds those values; otherwise content must leave it out (422 `not_applicable`).

```json
{"id": "duration", "label": "Duration", "type": "number",
 "when": {"field": "kind", "is": ["video"]}}
```

Adding any of these is checked against stored content. The Studio's builder sets them, its editor shows the allowed form, fills defaults into new entries and shows a conditional field only while it applies.

Read more: [Concepts](https://docs.colophon.404human.dev/concepts/)

### Every server and CLI reports its version, and the CLI says when it doesn't fit

28 Oct 2026 · Feature · API, CLI · https://docs.colophon.404human.dev/changelog/#2026-10-28-versions-and-compatibility

Colophon now has one version for the server, the CLI and the packages: `0.1.0-alpha.1`, not yet released. `GET /version` reports the release, its git commit, its build date and the API versions it serves, needs no sign-in and is never rate-limited. Fields may be added to it, never removed or renamed.

```bash
curl http://localhost:8080/version
{"version":"0.1.0-alpha.1","commit":"…","build_date":"2026-10-28","api":["v1"]}
```

`colophon --version` and `colophon-server --version` print the same facts on one line.

Before any command that talks to a server, the CLI reads `/version` and stops with a plain explanation when the two don't fit: the server must serve the API version the CLI speaks, and before 1.0 both must be on the same minor line, because a minor release may change the API. The message names both versions and says which one to install. `colophon logout` skips the check, so signing out always works.

Packaging is prepared for the first release but nothing is published yet: an npm launcher package with one binary package per platform, a Homebrew formula template and an install script.

Read more: [API reference](https://docs.colophon.404human.dev/api/reference/) · [The colophon CLI](https://docs.colophon.404human.dev/cli/)

### A redesigned Studio with entry states, title search, and comparisons for history and review

27 Oct 2026 · Improvement · Studio · https://docs.colophon.404human.dev/changelog/#2026-10-27-studio-design-history-and-compare

The Studio is rebuilt on a design system of its own: warm paper, black ink and one accent colour, Inter throughout, and light, dark and high-contrast schemes. State colours always come with a word, and motion switches off when your system asks for reduced motion. The sign-in page has the same look.

Every project page now sits in one shell: a sidebar with each collection and its entry count, publish requests waiting for review, and the live release with its label; breadcrumbs; and a command palette (⌘K) that finds entries by title across collections.

- **Entry states.** A collection is a table with **Draft**, **Changed** and **Live** filters, worked out by comparing each draft with its published revision.
- **Title search** runs on the server (`q` on the entries list), so it finds entries beyond the first page.
- **History.** The editor compares any earlier revision with the draft (`GET …/entries/{entry}/revisions/{revision}` reads one).
- **Review.** A publish request shows, for each entry, a word-level comparison of what readers have now and what they will get; for a take-down, what goes.

Why it matters: an editor can see what state each entry is in, and what a review is about to approve, without opening raw JSON.

Read more: [Writing in the Studio](https://docs.colophon.404human.dev/studio/writing/) · [History](https://docs.colophon.404human.dev/studio/history/)

### Sign the colophon CLI in from your browser, then create and list entries

26 Oct 2026 · Feature · CLI · https://docs.colophon.404human.dev/changelog/#2026-10-26-cli-device-sign-in

`colophon login` starts a device sign-in. It prints a short code and a link to the Studio's `/studio/device` page, where you, already signed in, see what is asking and approve it. The terminal then receives a personal token that acts with your own memberships for 30 days. The server stores only its hash; the CLI keeps it in `credentials.json` under `COLOPHON_CONFIG_DIR`, else `$XDG_CONFIG_HOME/colophon`, else `~/.config/colophon`.

Why it matters: a terminal can't hold a browser session, and the approval happens where you can see it. Codes last 10 minutes and the token is handed out exactly once.

```sh
colophon login --server http://localhost:8080
colophon whoami
colophon content create posts --project my-site --data '{"headline":"Hello"}'
colophon content list posts --project my-site --limit 20
```

`content create` writes the same validated draft the Studio would, with an idempotency key so a retry can't create twice; it exits 2 when the content doesn't fit its content type and 3 when you aren't allowed. `--profile` keeps sign-ins for several servers apart, and `colophon logout` revokes the token and forgets it.

Read more: [The colophon CLI](https://docs.colophon.404human.dev/cli/)

### Define your own content types, versioned and checked against the content they hold

26 Oct 2026 · Feature · API · https://docs.colophon.404human.dev/changelog/#2026-10-26-content-types-you-define

A project now defines its own content types. A definition has a name, the field that serves as each entry's title, and 1 to 100 fields, each with an id, a label, whether it is required, and a type with its limits: `text`, `rich_text`, `number`, `boolean`, `enum` or `datetime`. The server validates every entry save against its collection's definition.

Definitions are versioned and insert-only, and each revision records the version it was checked against. `GET …/content-types/{slug}` answers with `ETag: "v<version>"`; a change is a `PUT` with that value in `If-Match`, so two people editing one type can't overwrite each other (409 `stale_version`). A change that would leave stored entries invalid is refused with 422 `needs_migration`, so every stored revision stays valid.

```sh
curl -X POST "http://localhost:8080/api/v1/projects/{project}/environments/{environment}/content-types" \
  -H 'Authorization: Bearer …' -H 'Idempotency-Key: create-posts-type-01' \
  -H 'Content-Type: application/json' \
  -d '{"slug":"posts","definition":{"name":"Posts","title_field":"headline",
       "fields":[{"id":"headline","label":"Headline","type":"text","required":true}]}}'
```

Entries then live under `…/collections/posts/entries`.

Read more: [Concepts](https://docs.colophon.404human.dev/concepts/) · [Management API](https://docs.colophon.404human.dev/api/management/)

### Delivery answers are cached by release, with ETags and a header that says where they came from

26 Oct 2026 · Feature · API, Performance · https://docs.colophon.404human.dev/changelog/#2026-10-26-delivery-cache-and-etags

`/content/v1` answers are now cached in Valkey under keys that name their release generation. The generation itself is always read from PostgreSQL first, so a cached answer can't come from the wrong release: a new release simply uses new keys. When many readers miss the same key at once, one request fills it and the others share its answer.

Every answer carries:

- a strong `ETag`; send it back in `If-None-Match` to get `304 Not Modified`;
- `Cache-Control` for shared caches: 30 seconds for the latest release, 300 for a read pinned with `?generation=`, and browsers always revalidate;
- `Cache-Tag` with the entry's and collection's tags, which CDN purges use;
- `Colophon-Cache`: `hit`, `miss`, `coalesced` (waited for another request's fill) or `bypass` (read from PostgreSQL).

```http
HTTP/1.1 200 OK
Colophon-Generation: 12
Colophon-Cache: hit
ETag: "…"
Cache-Control: public, max-age=0, must-revalidate, s-maxage=30
```

The cache is disposable. When Valkey is down or slower than 100 ms, reads go straight to PostgreSQL, bounded by its connection pool (503 with `Retry-After` when it's full), and `/readyz` reports `degraded` rather than unready. Nothing is lost.

Read more: [Delivery API](https://docs.colophon.404human.dev/api/delivery/)

### Drafts that can't be lost: every save is a revision, guarded by If-Match and Idempotency-Key

26 Oct 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-10-26-drafts-that-cannot-be-lost

Entries are drafts, and every save writes a new revision; revisions are insert-only, so nothing is overwritten. An entry's `ETag` names its current revision, and a save sends it back in `If-Match`. If someone saved in between, the answer is 409 with `details.reason` `stale_revision` and the current `ETag`; a save without `If-Match` is 428.

Creates and saves also need an `Idempotency-Key` (16 to 128 letters, digits, `-` or `_`). A retry after a lost answer replays the recorded result with `Idempotent-Replayed: true` instead of saving twice; the same key with a different body is 409 `idempotency_key_reused`.

```sh
curl -X PUT "http://localhost:8080/api/v1/projects/{project}/environments/{environment}/collections/{collection}/entries/{entry}" \
  -H 'Authorization: Bearer …' -H 'If-Match: "{revision}"' \
  -H 'Idempotency-Key: save-hello-world-0001' \
  -H 'Content-Type: application/json' -d '{"title":"Hello"}'
```

`GET …/entries/{entry}/revisions` lists every revision kept.

The Studio's editor keeps your edits in this browser first, saves a second after you stop typing, and holds on to them through a closed tab, a dropped network or an expired session. On a conflict it shows both versions and lets you choose: **Keep my version** saves yours on top (theirs stays in the history), **Use their version** discards your unsaved changes.

Read more: [Writing in the Studio](https://docs.colophon.404human.dev/studio/writing/) · [Management API](https://docs.colophon.404human.dev/api/management/) · [History](https://docs.colophon.404human.dev/studio/history/)

### Members and single-use invitations, and a first administrator made from the terminal

26 Oct 2026 · Feature · API, Studio, Self-hosting · https://docs.colophon.404human.dev/changelog/#2026-10-26-members-invitations-and-first-administrator

Signing in grants nothing by itself: people reach a project by invitation. Each member has a role (the built-in ones are owner, developer, editor and publisher). Owners change roles and remove people, anyone may leave, and the last owner can't go (409 `last_owner`).

An invitation is a single-use link that expires after 72 hours by default. The answer that creates it is the only place the link appears; its token travels after `#`, so it never reaches a server, and only its hash is stored. Before joining, the invitee sees the project, the role and who invited them.

```sh
curl -X POST http://localhost:8080/api/v1/projects/{project}/invitations \
  -H 'Authorization: Bearer …' -H 'Content-Type: application/json' \
  -d '{"role":"editor","label":"Copy desk"}'
```

Only an installation's administrators create projects; anyone else gets 403 `administrators_only`. The first administrator is made once, from the operator's terminal, bound to a sign-in identity's subject (`colophon whoami` prints yours):

```sh
colophon admin bootstrap --subject "{subject}"
```

Run again for the same person it changes nothing; after that first run, bootstrap is disabled for good.

Read more: [Members and roles](https://docs.colophon.404human.dev/studio/members-and-roles/) · [Installation](https://docs.colophon.404human.dev/installation/)

### Publish requests pin exact revisions, and an approval covers only what was reviewed

26 Oct 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-10-26-publish-requests-bound-to-exact-content

A publish request (`changesets` in the API) names 1 to 100 entries and pins each at its current revision. Its hash is computed from those exact revisions, and an approval counts only while the request keeps the hash it was given on. Edit an entry afterwards and the request turns `stale`: refreshing it pins the new revision, changes the hash and needs a fresh review. Approvals also expire after seven days.

Why it matters: "approved" means these exact bytes were looked at, not that someone once said yes to an entry.

```http
POST /api/v1/projects/{project}/environments/{environment}/changesets
Idempotency-Key: …
{"title":"Spring launch","entries":["{entry}"]}

POST …/changesets/{changeset}/submit
If-Match: "sha256:…"

POST …/changesets/{changeset}/reviews
If-Match: "sha256:…"
{"decision":"approve","comment":"Checked the prices"}
```

`submit`, `refresh` and `reviews` each send the hash the caller looked at; if it moved, the answer is 409 `stale_changeset` with the current hash in `ETag`. A review's `decision` is `approve` or `request_changes`, and only the latest decision on the current hash counts. A request moves through `open`, `awaiting_review`, `changes_requested`, `approved` and `approval_expired`, and publishes once.

Read more: [Publishing](https://docs.colophon.404human.dev/studio/publishing/)

### One release, one generation number, and a public delivery API that reads any of them

26 Oct 2026 · Feature · API · https://docs.colophon.404human.dev/changelog/#2026-10-26-releases-and-the-delivery-api

Publishing an approved publish request commits one release in one transaction. The environment's generation goes up by exactly one, and only from the base the publisher saw: if another release committed first, the answer is 409 `generation_moved` with the current number in `Colophon-Generation`. Two releases on one base can never both win.

```http
POST /api/v1/projects/{project}/environments/{environment}/changesets/{changeset}/publish
If-Match: "sha256:…"
Idempotency-Key: …
{"base_generation": 11}
```

Published content is served at `/content/v1` with no sign-in, from a published copy read by a database role that can't see drafts at all. `{project}` is the project's id:

```sh
curl http://localhost:8080/content/v1/{project}/{environment}/posts
curl "http://localhost:8080/content/v1/{project}/{environment}/posts/{entry}?generation=12"
```

Without `generation` you read the latest release; with it you read that release exactly as it was, so a site build can take every collection from one release. Every answer names its generation in `Colophon-Generation`, a list's `next_cursor` keeps its first page's generation so paging never mixes two releases, and a generation not yet published is 422 `invalid_generation`.

Read more: [Delivery API](https://docs.colophon.404human.dev/api/delivery/) · [Concepts](https://docs.colophon.404human.dev/concepts/)

### Sign in to the Studio, and every project is walled off from the others

26 Oct 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-10-26-sign-in-and-project-isolation

People can sign in to the Studio through an OpenID Connect provider: `GET /auth/login` sends the browser to the provider, and `GET /auth/callback` brings it back signed in. The server keeps each session as a database row and gives the browser only a random token in the `colophon_session` cookie (`HttpOnly`, `Secure`, `SameSite=Lax`). A session ends 12 hours after sign-in or after 2 hours unused, and `POST /auth/logout` ends it from the very next request, because nothing caches sessions.

Writes made with that cookie need two more things: an `X-CSRF-Token` header echoing the readable `colophon_csrf` cookie, and an `Origin` that is the server's public origin or one listed in `COLOPHON_TRUSTED_ORIGINS`, compared exactly. Anything else is 403 with `details.reason` `csrf_token_invalid` or `origin_not_allowed`.

Projects are isolated. `GET /me` and `GET /api/v1/projects` list only the projects you belong to, and a route naming a project you aren't in answers exactly as one that doesn't exist, so ids and slugs can't be probed:

```http
GET /api/v1/projects/{project} HTTP/1.1
Cookie: colophon_session=…

HTTP/1.1 404 Not Found
{"error":{"code":"not_found","message":"…","request_id":"…"}}
```

Read more: [Authentication & API tokens](https://docs.colophon.404human.dev/api/authentication/)

### Take an entry down through a publish request, and it answers 410 at every generation

26 Oct 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-10-26-take-downs-answer-410

Taking an entry down changes what readers see, so it goes through review like any other change. A publish request (`changesets` in the API) lists the entry under `unpublish`, pinning the revision that is live now, so the reviewer approves taking down exactly what readers get:

```http
POST /api/v1/projects/{project}/environments/{environment}/changesets
Idempotency-Key: …
{"title":"Withdraw the old pricing page","unpublish":["{entry}"]}
```

When its release commits, the entry's publication closes, a tombstone is recorded and every earlier publication of it is revoked. From then on `/content/v1` leaves it out of lists and answers a read of it with 410 `gone` and `Cache-Control: no-store`, including reads pinned to an older release with `?generation=`: history never gets round a take-down. Answers cached before it are never served again, because cache keys name the environment's latest take-down.

With a CDN connection, the release reports its purge as `pending`, `accepted` or `failed`, and the Studio says *Removal pending at the CDN* until it is accepted. Copies a browser already downloaded can't be recalled. Publishing the entry again makes it readable from that new release on.

Read more: [Publishing](https://docs.colophon.404human.dev/studio/publishing/) · [Delivery API](https://docs.colophon.404human.dev/api/delivery/)

### Website connections announce each release once, purge CDNs and check your site

26 Oct 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-10-26-website-connections-and-receipts

An environment can have destinations, the Studio's website connections, of three kinds (`POST …/destinations`):

- `webhook`: each release is announced with a `release.committed` POST carrying `Idempotency-Key` and `Colophon-Generation`. The job is written in the release's own transaction and sent by a background worker, retried with backoff on 408, 425, 429, 500, 502, 503 and 504, and dropped when a newer release supersedes it, so an older release never lands after a newer one.
- `cdn`: each release sends `{"tags": [...]}`, a purge by tag covering every release since that CDN's last successful purge.
- `probe`: the worker fetches a URL and reads which release it serves, from the `Colophon-Generation` header or a `<meta name="colophon-generation" content="N">` tag.

```json
{"kind":"probe","name":"Home page","url":"https://example.com/"}
```

Addresses must be https on the public internet. `GET …/releases/{generation}` is the release's receipt: one `label` (`published`, `pending`, `verified` with its count of `locations`, or `needs_attention`), the CDN `purge` state, each destination's deliveries and every probe observation. "Verified" always says at how many locations, because one probe's view isn't the whole internet. The Studio shows it as a receipt timeline.

Read more: [Website connections](https://docs.colophon.404human.dev/api/website-connections/) · [Publishing](https://docs.colophon.404human.dev/studio/publishing/)

### Every error has one shape and a request ID, and health checks say what is wrong

25 Oct 2026 · Feature · API, Self-hosting, CLI · https://docs.colophon.404human.dev/changelog/#2026-10-25-errors-request-ids-and-health-checks

Every failed request now answers in one JSON envelope, whether a handler or the server's own middleware refused it: a stable `code` to branch on, a `message` that is safe to show a person, and the `request_id`. When there is more to say, `details` carries a stable `reason` and, for a refused body, a JSON Pointer to the value at fault.

```json
{"error":{"code":"validation_failed","message":"…","details":{"reason":"unknown_node","pointer":"/doc/content/0/type"},"request_id":"…"}}
```

The same ID comes back in the `x-request-id` header on every answer and appears in the server's log lines for that request, so a bug report can quote it. Send your own (up to 64 letters, digits, `.`, `_` or `-`) and the server keeps it; otherwise it makes one.

Two health endpoints need no sign-in. `/livez` says the process responds. `/readyz` reports `ready`, or `degraded` when the cache is down (slower, still safe), with a 200; `starting`, `not_ready` or `draining` answer 503, so a load balancer stops sending traffic. `colophon doctor` reads it for you:

```sh
colophon doctor --server http://localhost:8080
```

It exits 0 when the server is ready and 5 when it is degraded, not ready or unreachable.

Read more: [Errors](https://docs.colophon.404human.dev/api/errors/) · [Monitoring](https://docs.colophon.404human.dev/self-hosting/monitoring/)

### Rich text is stored in one strict, versioned format that the server checks

25 Oct 2026 · Feature · API, Studio · https://docs.colophon.404human.dev/changelog/#2026-10-25-rich-text-format

Rich-text fields are stored as `colophon/rich-text` version 1: editor JSON limited to an allowlist and wrapped in a versioned envelope. It holds paragraphs, headings (levels 2 to 4), bulleted and numbered lists, quotes, code blocks, horizontal rules, callouts and images, with bold, italic, strike, code and link marks. Nothing executable is ever stored (no HTML, scripts, styles or embeds), and a link may only be `https:`, `http:`, `mailto:`, a site path or a `#` fragment.

Why it matters: the server has the last word, not the editor. A document deeper than 16 levels, larger than 256 KiB or with more than 10,000 nodes is refused, and every refusal names a code and a JSON Pointer to the value at fault. The Studio's editor opens a document only if it can write it back byte for byte, and one renderer turns documents into escaped HTML.

Check a document before saving it; the endpoint stores nothing:

```sh
curl -X POST http://localhost:8080/api/v1/rich-text/validate \
  -H 'Content-Type: application/json' \
  -d '{"schema":"colophon/rich-text","version":1,"doc":{"type":"doc","content":[{"type":"paragraph"}]}}'
```

A valid document comes back in canonical form with its `nodes`, `depth` and `bytes`; an invalid one is 422 `validation_failed`.

Read more: [Rich text and images](https://docs.colophon.404human.dev/studio/rich-text-and-images/) · [Management API](https://docs.colophon.404human.dev/api/management/)

