Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,8 @@ inference have not been tested.
[Docker quickstart](docs/local/quickstart.md) · [Codex CLI](docs/local/codex.md) ·
[Claude Code](docs/local/claude-code.md) · [OpenCode](docs/local/opencode.md) ·
[Ollama](docs/local/ollama.md) · [Integration matrix](docs/local/integrations.md) ·
[Verification and limits](docs/local/compatibility.md)
[Verification and limits](docs/local/compatibility.md) ·
[Release history](https://plompy.dev/docs/releases/)

```sh
mkdir -m 700 plompy-local
Expand Down
2 changes: 2 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Documentation

- **[Release history](https://plompy.dev/docs/releases/)**: published versions, changes, downloads and upgrade boundaries.

- **[Upgrade to Plompy 0.12](migration-plompy.md)**: retain existing sessions, private state, browser identity and Docker volumes.

plompy-engine connects a private Discord forum to persistent coding CLI sessions on
Expand Down
2 changes: 2 additions & 0 deletions docs/local/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ Plompy Local connects an agent on your computer to selected tools running behind

Plompy Local 0.13.0 ships as ready-made Docker images and a small starter kit. Download it, connect your preferred agent, and choose its tools. The Local images are separate from the Discord engine image. Check [Compatibility and verification](compatibility.md) for what has actually been tested.

See [what shipped in each release](releases.md), including the current 0.13.0 Local images.

## Pick your starting point

- [Run locally with Docker](quickstart.md): start the tools gateway, connect a client, and try a small task.
Expand Down
11 changes: 10 additions & 1 deletion docs/local/navigation.json
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,14 @@
"description": "Pull the ready-made local gateway image and connect your chosen host MCP client.",
"group": "Start here"
},
{
"slug": "releases",
"source": "releases.md",
"title": "Release history",
"description": "Every published Plompy release, with changes, downloads and historical boundaries.",
"group": "Start here",
"kind": "release-index"
},
{
"slug": "architecture",
"source": "architecture.md",
Expand Down Expand Up @@ -219,5 +227,6 @@
"description": "Keep autonomous remote browser actions outside the first research profile.",
"group": "Integrations"
}
]
],
"releaseHistory": true
}
5 changes: 5 additions & 0 deletions docs/local/releases.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Every release.<br>A little more possibility.

What shipped, when it shipped, and what changed. Follow Plompy from its first published engine to local tools for your own agent.

Published versions are listed below. Development changes on `main` are not a release, and older notes describe the capabilities and limits of their own version.
4 changes: 3 additions & 1 deletion docs/releases.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Releases and container images

Browse the [public release history](https://plompy.dev/docs/releases/) for a page per published version. This guide covers distribution, upgrades and the maintainer workflow.

A release is a versioned public source snapshot and a set of container images. It does not update an existing private deployment automatically. The [changelog](../CHANGELOG.md) records user-visible changes; the [Docker guide](docker.md) explains initial setup and private volumes.

## Choose an image
Expand Down Expand Up @@ -57,7 +59,7 @@ The [release workflow](../.github/workflows/release.yml) runs only on `v*` tag p

The workflow also builds the allowlisted Local starter kit and its SHA-256 checksum, without including source state or credentials. The original tested OCI archives and their digest reports are retained as workflow artifacts for one day. A separate publishing job receives `packages: write` after all checks succeed. It revalidates the archive hashes, labels, runtime and attestation subjects, copies every manifest with `skopeo --preserve-digests`, and combines the unchanged amd64/arm64 runtime and attestation manifests into the release index. It does not rebuild the application or reinstall its dependencies. The final index is checked against the complete tested manifest set before its digest is recorded. Publishing uses the job's short-lived GitHub token; no personal registry token is needed. If retained artifacts have expired, rerun the complete workflow so both architectures are rebuilt and retested.

After the workflow succeeds, inspect the published manifest and digest, pull the exact images without authentication to confirm public availability, and create the GitHub release with the relevant changelog entry and immutable image references. Attach the generated Local starter kit and its checksum. The workflow deliberately does not create a release announcement before the image has been verified. GitHub may initially create a GHCR package as private; check its package visibility for the first publication before documenting anonymous installation.
After the workflow succeeds, inspect the published manifest and digest, pull the exact images without authentication to confirm public availability, and create the GitHub release with the relevant changelog entry and immutable image references. Attach the generated Local starter kit and its checksum. Then refresh the [release-history catalog](releases/README.md) and rebuild the website documentation from the canonical changelog. The workflow deliberately does not create a release announcement before the image has been verified. GitHub may initially create a GHCR package as private; check its package visibility for the first publication before documenting anonymous installation.

The tag validator accepts SemVer versions with an optional prerelease, without build metadata (`+...`, which is not a Docker tag character). Release metadata and tag-selection behavior have their own offline test:

Expand Down
38 changes: 38 additions & 0 deletions docs/releases/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Maintaining the public release history

`CHANGELOG.md` is the source of release changes. `catalog.json` records which
versions actually have a published GitHub release, their publication dates,
latest-stable designation and downloadable assets. A changelog entry alone does
not make a release public.

After publishing a release and its final assets, refresh the catalog from the
public GitHub API:

```sh
node docs/releases/sync.mjs
node --test docs/releases/sync.test.mjs
```

Review and commit the catalog. The sync reads public metadata only; it does not
publish, edit releases, download artifacts or need account credentials. Drafts
and unpublished entries are excluded. Prereleases are retained and labelled.

The website builder reads `docs/local/navigation.json`, `docs/local/releases.md`,
`CHANGELOG.md` and this catalog when `releaseHistory` is enabled. It generates the
release index and individual version pages at `/docs/releases/`. Notes are not
copied into separate hand-maintained pages. Builds fail when a published version
has no matching changelog entry. Source-relative links point to the corresponding
Git tag so historical pages do not silently become current instructions.

From a sibling `plompy-site` checkout, rebuild and verify:

```sh
npm run build -- --docs-source ../plompy-engine/docs/local
npm run check
npm run test:docs
```

Normal site builds use the committed generated pages without fetching GitHub.
The generated manifest records hashes for both release sources. Development-only
changelog entries stay out of the public history until a release is published and
the catalog is refreshed.
192 changes: 192 additions & 0 deletions docs/releases/catalog.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,192 @@
{
"schema": 1,
"repository": "dalkedev/plompy-engine",
"checkedAt": "2026-11-12T16:54:05.526Z",
"latestStableTag": "v0.13.0",
"releases": [
{
"tag": "v0.13.0",
"title": "Local MCP, ready-made Docker images",
"publishedAt": "2026-11-12T16:45:24Z",
"prerelease": false,
"url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.13.0",
"assets": [
{
"name": "plompy-local-0.13.0.tar.gz",
"url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.13.0/plompy-local-0.13.0.tar.gz",
"size": 11923
},
{
"name": "plompy-local-0.13.0.tar.gz.sha256",
"url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.13.0/plompy-local-0.13.0.tar.gz.sha256",
"size": 93
}
]
},
{
"tag": "v0.12.0",
"title": "small fish, your whole machine",
"publishedAt": "2026-11-11T22:43:20Z",
"prerelease": false,
"url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.12.0",
"assets": [
{
"name": "plompy-engine-brand-kit.zip",
"url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.12.0/plompy-engine-brand-kit.zip",
"size": 3568562
}
]
},
{
"tag": "v0.11.1",
"title": "unattended Playwright",
"publishedAt": "2026-11-10T17:44:33Z",
"prerelease": false,
"url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.11.1",
"assets": []
},
{
"tag": "v0.11.0",
"title": "browser, research and analytics tools",
"publishedAt": "2026-11-10T16:08:54Z",
"prerelease": false,
"url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.11.0",
"assets": []
},
{
"tag": "v0.10.0",
"title": "Node 26 LTS",
"publishedAt": "2026-11-10T14:05:58Z",
"prerelease": false,
"url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.10.0",
"assets": [
{
"name": "image-verification.json",
"url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.10.0/image-verification.json",
"size": 1080
},
{
"name": "published-index.json",
"url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.10.0/published-index.json",
"size": 1611
}
]
},
{
"tag": "v0.9.0",
"title": "install, inspect, verify",
"publishedAt": "2026-11-10T11:24:06Z",
"prerelease": false,
"url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.9.0",
"assets": [
{
"name": "image-verification.json",
"url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.9.0/image-verification.json",
"size": 1078
},
{
"name": "published-index.json",
"url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.9.0/published-index.json",
"size": 1611
}
]
},
{
"tag": "v0.8.1",
"title": "safe goal recovery under queue pressure",
"publishedAt": "2026-11-09T21:36:45Z",
"prerelease": false,
"url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.8.1",
"assets": []
},
{
"tag": "v0.8.0",
"title": "evidence for every reviewed step",
"publishedAt": "2026-11-09T17:25:59Z",
"prerelease": false,
"url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.8.0",
"assets": []
},
{
"tag": "v0.7.0",
"title": "supervised goals",
"publishedAt": "2026-11-07T21:29:16Z",
"prerelease": false,
"url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.7.0",
"assets": []
},
{
"tag": "v0.6.1",
"title": "Release 0.6.1",
"publishedAt": "2026-11-06T19:40:59Z",
"prerelease": false,
"url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.6.1",
"assets": []
},
{
"tag": "v0.6.0",
"title": "integrations and recovery without losing the thread",
"publishedAt": "2026-11-06T16:49:02Z",
"prerelease": false,
"url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.6.0",
"assets": []
},
{
"tag": "v0.5.0",
"title": "Private Discord image input",
"publishedAt": "2026-11-05T18:37:57Z",
"prerelease": false,
"url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.5.0",
"assets": []
},
{
"tag": "v0.4.0",
"title": "Provider-bound runners and offline demos",
"publishedAt": "2026-11-05T16:14:11Z",
"prerelease": false,
"url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.4.0",
"assets": []
},
{
"tag": "v0.3.1",
"title": "Recovery and clock-safe workflows",
"publishedAt": "2026-11-05T14:37:45Z",
"prerelease": false,
"url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.3.1",
"assets": []
},
{
"tag": "v0.3.0",
"title": "Durable bounded work sessions",
"publishedAt": "2026-11-04T19:55:02Z",
"prerelease": false,
"url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.3.0",
"assets": [
{
"name": "release-manifest-0.3.0.json",
"url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.3.0/release-manifest-0.3.0.json",
"size": 1245
}
]
},
{
"tag": "v0.2.0",
"title": "Release 0.2.0",
"publishedAt": "2026-11-04T19:20:04Z",
"prerelease": false,
"url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.2.0",
"assets": [
{
"name": "release-manifest.json",
"url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.2.0/release-manifest.json",
"size": 774
},
{
"name": "szpont-engine-brand-kit.zip",
"url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.2.0/szpont-engine-brand-kit.zip",
"size": 1647770
}
]
}
]
}
60 changes: 60 additions & 0 deletions docs/releases/sync.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
import assert from 'node:assert/strict';
import { writeFile } from 'node:fs/promises';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { resolve } from 'node:path';

const repository = 'dalkedev/plompy-engine';
const tagPattern = /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;

// Publication metadata only. Changes remain authored once in CHANGELOG.md.
export function releaseCatalog(releases, latestTag, checkedAt) {
const published = releases.filter(release => !release.draft && release.published_at);
const tags = new Set();
const entries = published.map(release => {
assert(tagPattern.test(release.tag_name), 'Unsupported release tag.');
assert(!tags.has(release.tag_name), 'Duplicate release tag.');
tags.add(release.tag_name);
const url = `https://github.com/${repository}/releases/tag/${release.tag_name}`;
assert.equal(release.html_url, url, 'Unexpected release URL.');
assert(Number.isFinite(Date.parse(release.published_at)), 'Invalid publication date.');
const rawTitle = (release.name || '').replace(/^(?:Plompy|Szpont)(?: Engine)?\s+v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?\s*(?:[\u2014\u2013:-]\s*)?/i, '').trim();
return {
tag: release.tag_name,
title: (rawTitle || `Release ${release.tag_name.slice(1)}`).replaceAll('\u2014', ':'),
publishedAt: release.published_at,
prerelease: Boolean(release.prerelease),
url,
assets: release.assets.map(asset => {
const expected = `https://github.com/${repository}/releases/download/${release.tag_name}/`;
assert(asset.browser_download_url.startsWith(expected), 'Unexpected asset URL.');
assert(Number.isSafeInteger(asset.size) && asset.size >= 0, 'Invalid asset size.');
return { name: asset.name, url: asset.browser_download_url, size: asset.size };
}),
};
}).sort((a, b) => b.publishedAt.localeCompare(a.publishedAt));
assert(entries.some(entry => entry.tag === latestTag && !entry.prerelease), 'Latest stable release is not published.');
return { schema: 1, repository, checkedAt, latestStableTag: latestTag, releases: entries };
}

async function github(path) {
const response = await fetch(`https://api.github.com/repos/${repository}/${path}`, {
headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'plompy-release-docs' },
signal: AbortSignal.timeout(20_000),
});
if (!response.ok) throw new Error(`GitHub publication lookup failed: HTTP ${response.status}`);
return response.json();
}

if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
const releases = [];
for (let page = 1; page <= 20; page++) {
const batch = await github(`releases?per_page=100&page=${page}`);
releases.push(...batch);
if (batch.length < 100) break;
if (page === 20) throw new Error('Release pagination limit reached; catalog not written.');
}
const latest = await github('releases/latest');
const catalog = releaseCatalog(releases, latest.tag_name, new Date().toISOString());
await writeFile(fileURLToPath(new URL('./catalog.json', import.meta.url)), JSON.stringify(catalog, null, 2) + '\n');
console.log(`Recorded ${catalog.releases.length} published releases; latest stable ${catalog.latestStableTag}.`);
}
18 changes: 18 additions & 0 deletions docs/releases/sync.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { releaseCatalog } from './sync.mjs';

const release = (tag, extra = {}) => ({ tag_name: tag, name: `Plompy ${tag}`, html_url: `https://github.com/dalkedev/plompy-engine/releases/tag/${tag}`, published_at: '2026-11-12T12:00:00Z', prerelease: false, draft: false, assets: [], ...extra });

test('catalog includes published versions only and retains explicit stable status', () => {
const catalog = releaseCatalog([release('v0.13.0'), release('v0.14.0-rc.1', { prerelease: true }), release('v0.15.0', { draft: true }), release('v0.16.0', { published_at: null })], 'v0.13.0', '2026-11-12T13:00:00Z');
assert.equal(catalog.releases.length, 2);
assert.equal(catalog.latestStableTag, 'v0.13.0');
assert.equal(catalog.releases[1].prerelease, true);
});

test('rejects inconsistent latest release, duplicate tags and unexpected download origins', () => {
assert.throws(() => releaseCatalog([release('v0.13.0')], 'v0.14.0', ''), /not published/);
assert.throws(() => releaseCatalog([release('v0.13.0'), release('v0.13.0')], 'v0.13.0', ''), /Duplicate/);
assert.throws(() => releaseCatalog([release('v0.13.0', { assets: [{ name: 'kit.zip', size: 1, browser_download_url: 'https://example.com/kit.zip' }] })], 'v0.13.0', ''), /asset URL/);
});