---
title: A changelog with pictures and docs that keep up with the app
description: CHANGELOG.md and the guides in your docs folder show screens from accepted runs. When a screen changes, Kaloko says which section to rewrite.
seo_title: Visual changelog and living docs from accepted runs
seo_description: A changelog with before and after screenshots and guides whose pictures never go stale, drafted by your agent from accepted Kaloko runs.
query: visual changelog and living documentation with screenshots
kind: use-case
order: 14
updated: 2026-10-04
demo: false
---
Support asks what changed in the release. The answer is a list of pull request titles nobody outside the team can read, and the help centre still shows the checkout from two versions ago. Your accepted runs already hold every screen of the release, so the changelog and the docs can show them.

## The problem

Screenshots in documentation are taken by hand, once, and go stale with the next release. Release notes are written from commit messages. Nobody notices that a guide describes a button that moved until a customer writes in.

## What changes with Kaloko

A picture in Markdown names a step instead of a file: `![Payment](kaloko:checkout/payment)` shows the newest accepted screenshot of that step, `?version=2.4.0` the one of that release. The changelog and the guides stay in your repository; Kaloko turns the references into pictures and shows them as pages you can share with clients, support or marketing.

## How it works

1. **Set it up once**: `npx kaloko init --docs=changelog` adds `CHANGELOG.md` and the config block; `--docs=full` also creates `docs/` folders for tutorials, how-to guides, reference and explanation, each with a template.
2. **Draft the entry**: `kaloko changelog draft` writes the Unreleased entry from the merged pull requests since the last release and adds before and after pictures of the screens accepted runs show differently. `--apply` writes it into `CHANGELOG.md`; the agent then rewrites the lines for people.
3. **Record the release**: `kaloko release 2.4.0` turns Unreleased into the version, records its pictures and prints the changelog page. With release-please, changesets or semantic-release, `kaloko ci github --release` adds a workflow that does it on every published release.
4. **Keep the guides current**: `kaloko docs publish` sends the docs folder to Kaloko. When an accepted run later shows a different screen, the section says "the screen changed in 2.4 — check the text", and `kaloko docs check` lists it, with broken references and missing translations, and exits 1 in CI.
5. **Export where you need it**: `kaloko export --format md|docusaurus|vitepress|mkdocs|html|pdf|json` writes the docs and the changelog with the pictures as files for your own docs site.

## Skills and prompts

```
Draft the changelog entry for this release with Kaloko, rewrite the lines for our customers and keep the before and after pictures.
```

Expected outcome: an Unreleased entry grouped Added, Changed, Fixed, Removed, one change per line, with step references under the lines they show. Nothing is recorded until you say so.

```
Run kaloko docs check and fix every section whose screen changed since it was written; translate the changes into Czech too.
```

Expected outcome: the stale sections rewritten against the new screens, `guide.cs.md` files updated next to the originals, and a clean `kaloko docs check`.

## What you get

- A changelog page with a slider between before and after, in the reader's language and screen size, each picture linked to its flow on the canvas.
- Guides that play as a walkthrough, one step at a time, with a version selector, search and language switch.
- On every plan: the changelog, the latest docs and Markdown or JSON exports. From Business: docs per version with stale sections, the static-site, HTML and PDF exports, a "What's new" e-mail with each release, readers from your company's domain and a public changelog with a feed.

## See it on Kaloko itself

We keep Kaloko's own changelog and help this way, and both are public. [Kaloko's changelog](https://kaloko.app/p/sinfin/kaloko/changelog?lang=en) shows our releases with before and after pictures from the runs we accepted before shipping them. [Kaloko's help](https://kaloko.app/p/sinfin/kaloko/docs?lang=en) is a docs folder in our repository with step references; switch the language or the screen size and the pictures follow.

## FAQ

### Do we have to move our docs to Kaloko?

No. The Markdown stays in your repository and your docs site keeps its own build; export into its folder or run the export in its CI.

### What if a release tool already writes CHANGELOG.md?

Kaloko reads the entry the tool wrote and never rewrites the file. Put your draft into the pull request or the release notes instead.

### Can clients read the changelog without an account?

On Business and Enterprise an admin can open it to readers from your verified domains or publish it at a public address with an Atom feed. Guests of a project always read the changelog of their product.
