chore(release): 0.2.0 by thecodacus · Pull Request #303 · thecodacus/pithagoras

thecodacus · 2026-10-23T17:50:02Z

This PR prepares 0.2.0. It raises the portal and @pithagoras/extension-api to 0.2.0, and it rewrites docs/guide/upgrading.md so the guide is correct for a portal that goes straight from v0.1.0 to 0.2.0. It adds tests for the #221 checklist items that had none. It also fixes one thing the upgrade lost: the name a person gave v0.1.0's tool set for pictures. The branch is cut from main at 2286642, so #294, #295, #296 and #298 are in it, and the guide and the release notes cover them.

Version bump

package.json and packages/extension-api/package.json go from 0.1.0 to 0.2.0.
package-lock.json changes in three lines only: the top-level version, and the "" and packages/extension-api entries. These are the files and entries that the release steps in extension-ui.md name. tests/extension-api-package.test.mts passes.
The docs package (docs/package.json) stays at 0.1.0. Nothing reads its version, and neither the release steps nor the lockstep test name it.
The shipped extensions keep their own versions. All are 0.1.0 except Docker for extensions, which is 1.2.0 (fix(voice): its container comes back after the host restarts #298).

What changed besides the docs

fix(upgrade): v0.1.0 filed its picture tools as the set <portal:images>. Add a Media area for pictures and videos: one settings tab, one sidebar tab, one tool group (#79) #164 renamed the set <portal:media> but did not carry over a name the person had given it, and the schema 7 hand-off moved only <portal:media>. handOffMedia now moves both, the newer one first. This is one line in core/server/src/db.ts.
New tests:
- schema-fingerprint.test.mjs: a v0.1.0 data folder that uses every part goes from schema 3 to 11 in one start. The folder holds a canvas, a picture on the Images page with its file, the image endpoint, voice mode connected to the service with the person's own addresses remembered, a designed voice and a clone, the GPU, Understory's settings and MCP entry, the browser's settings and a local profile, the allowlist, a heartbeat rule for routine_update, tools_seen and the sets' names. The test checks for one backup, portal-v3-….db, the five hand-offs at their schemas, the settings that are left, and the rules.
- deploy-files.test.mts: runs scripts/old-entries.mjs into its own folder and checks four things. Each server/dist forwarder runs the matching file in core/server/dist with its arguments. The build runs the script. The Dockerfile copies server/dist.
- extensions/git/test/drafts.test.mts: the extension's gitDrafts reads and writes v0.1.0's pithagoras.git-draft.<key> entries.
- mcp-edited-outside.test.mjs: a tool left over from before fix(mcp): notice a server taken out of mcp.json outside the portal #295's first look goes away once its server is added again and then removed in Settings → MCP.
- extension-packages.test.mts: pins extensions/defaults.json to the six packages the guide lists.
Docs outside the upgrading guide:
- settings.md lists Sandbox and Guard.
- deploying.md names all six default extensions.
- configuration.md gains PORTAL_DEFAULT_EXTENSIONS and BROWSER_BIND.
- mcp.md tells you to add the server and remove it again, instead of editing tools_seen.

The upgrading guide

New: "From 0.1.0 to 0.2.0". It has:
- schemas 3 to 11 in one start, in order, each linked to its section;
- what you do: take PORTAL_PASSWORD out, install the extensions you used, reload open tabs, change scripts and bookmarks, rename Azure's provider, use Node 22.19 from a checkout, and drop docker-compose.voice.yml from the start command;
- a table of the pages, settings and routes that moved, under the names 0.1.0 used. It includes the renamed Voice routes (GET install → /state, presets → voices, POST connect → PUT …/chosen) and the renamed Understory routes (PUT /api/features/understory → …/use, GET /api/features → …/state);
- the new environment variables, and what each one does when unset: the waits are 30 minutes where 0.1.0 had Node's five, and a checkout looks for new commits every six hours;
- what does not carry over.
New sections:
- agents and routines have tools of their own (schema 4);
- code mode is off by default;
- the extensions a portal starts with, and the ones it does not install;
- the terminal and Git as extensions (routes, T, panel places);
- a tool's files (schema 6);
- the guard (taint, MCP output, heartbeat rules, a routine's exemptions);
- MCP servers taken out by hand (fix(mcp): notice a server taken out of mcp.json outside the portal #295's mcp_configured first look, and fix(mcp): tell a server's tools by the prefix the adapter really gives them #296's dotted names);
- pi is 1.1.
Changed sections:
- Canvases gains its routes, D and the panel place.
- Media gains 0.1.0's /settings/images and its Images group.
- Browser gains the allowlist's old place and route.
- Voice: when Voice starts, it gives the existing container the unless-stopped policy in place. This needs Docker for extensions 1.2.0 (fix(voice): its container comes back after the host restarts #298). The container comes back after a restart only with Docker 29 or later. Older Docker can leave it stopped, and the page then shows failed with Retry setup. Nothing remakes the container before Voice is installed.
Renamed: "Upgrading from the first release" is now "Upgrading to 0.1.0 from an earlier build", and it keeps only 0.1.0's own items. The password, pi 1.1 and the voice container moved to 0.2.0's sections. The heartbeat line now says that 0.2.0 also removes a heartbeat's rules.
New: "Going back to 0.1.0". It is one procedure, in order:
1. remove the extensions 0.1.0 does not have;
2. stop the portal;
3. put back portal-v3-….db;
4. run one script that moves the Images page's pictures and the local profile back, and moves extension-data/ and handoff/ aside. The script is written out in full twice, once for the host and once for a container (--volumes-from);
5. set PORTAL_PASSWORD again;
6. start 0.1.0;
7. remake Understory's container.
It also covers what stays behind: each canvas exists twice, pi is back at 0.82, the voice container keeps its policy, and modes and exemptions are lost.

The #221 checklist

Item	Status	Tested	Documented
Schema 3 → 4 (#100)	Done	`schema-fingerprint` "a database of v0.1.0 …", and the new whole-folder test	"Agents and routines have tools of their own" (new)
Schema 4 → 5 (#223), canvases written out	Done	`schema-fingerprint` "the canvases a portal stored …" (from `portal-v3.db`), and the whole-folder test	"Canvases are an extension", now with routes, D and the panel
The password moves into the database (#168)	Done	`core/server/test/auth-environment.test.mjs` (4 tests; not `auth.test.mjs`)	"The password moves into the database"
People rules for `subagent` and the routine tools	Done. Since #253 a heartbeat's rules are removed too	`schema-fingerprint` v2 test (r1 to r4), and the whole-folder test (a heartbeat's `routine_update`)	"The guard"; the line in the pre-0.1.0 section is fixed
Backup, and no start on a newer database	Done	`db-upgrade.test.mjs` (the port-taken test fails on macOS only, #43)	"What happens on the first start", "When it cannot upgrade", "Going back"
Code moved to `core/`, forwarders (#198)	Done	New `deploy-files` test that runs the forwarders and checks the Dockerfile	"The server and the web app moved to core/"
`WORKSPACES_DIR`, Portainer `PORTAL_DATA_DIR`	Not a change from 0.1.0 (the same in `66a35a4`)	`deploy-files`	"Upgrading to 0.1.0 from an earlier build"
Extensions installed once on the first start (#197)	Done	`default-extensions*.test.mjs`, `retired-extensions-wait.test.mjs`, and the new pin of `defaults.json` to the guide	"The extensions a portal starts with" (new)
Routes moved: terminal, Git, Canvases	Done	The extensions' own route tests	The "From 0.1.0" table, "The terminal is an extension", "Git is an extension", Canvases
T and D shortcuts	Decided: not carried over. The guide says they go back to their defaults, and the panels go back to their default places, once	Nothing to test	"What does not carry over", the terminal and Canvases sections
Git drafts keep their key	Done	New `extensions/git/test/drafts.test.mts`	"Git is an extension"
Notes no longer in `extensions/` (#200)	No effect on 0.1.0. Decided: a note. The guide says to remove a leftover entry under Settings → Extensions	Nothing to test	"The extensions a portal starts with"
Browser UI kept off the network (#173)	Done	`extensions/browser/test/bind.test.mts`	Browser section, and the variables table
A voice add-on's container	Done. This is Voice's job: the container is remade once where its network is gone, and otherwise given `unless-stopped` in place (#298)	`extensions/voice/test/network.test.mts`, `restart.test.mts`, `server-half.test.mts`	Voice section
pi 0.82 → 1.1 (#112)	Done	`deploy-files` "the image takes what the lock says …", `lockfile.test.mts`	"pi is 1.1", "Going back to 0.1.0"
Tool settings carried over	Done. Gateway and lazy marks: 0.1.0 had none. Code mode is seeded off. Media group: now includes v0.1.0's `<portal:images>` name (the fix above). Agents and routines: done	`schema-fingerprint` v0.1.0 test and whole-folder test	"Code mode is a tool, off by default", Media, schema 4 sections
New, nothing to move	In the release notes	—	Release notes
The whole upgrade, once (a real v0.1.0 data folder)	Mostly done. The whole-folder test automates it at the database level, and it was run by hand on friday-lab twice (see below). Left: a channel answering, a routine run, a heartbeat, and a running voice add-on on a Docker host. These were not exercised because they need a model, a channel and Docker	—	—
Going back: the backup restores and starts on v0.1.0	Done. The procedure is written and was run once on friday-lab without Docker, and its container form was run in alpine	Manual (below)	"Going back to 0.1.0" (new)
`upgrading.md` covers every item	Done	—	This PR

Every item is done except the part of "The whole upgrade, once" listed above, so this PR says Refs #221. If what was run is enough, change it to Closes #221.

Upgrade test

From the workflow, at bb87b8c, on friday-lab. Two data folders went to schema 11 and every check passed. One was made by v0.1.0 through its API, and the other was fixtures/portal-v3.db. Both showed the Upgrading page and made the backup, and quick_check and integrity_check returned ok. Each hand-off was taken up once its extension ran. The six defaults were installed, the chats and the routine were kept, and the password moved. No log line reported an error.
Two notes, now known issues in the release notes:
- after the Upgrading page closes, the port refuses connections for about 0.4 s;
- Browser, Voice and Understory installed through POST /api/packages without Docker wait without showing any message.
The going-back check, at cdb3df2, on friday-lab. The steps:
1. v0.1.0 made a data folder with 2 chats, a picture on the Images page and a local profile.
2. This branch upgraded it, and a chat was added.
3. The six default extensions were removed.
4. The guide's remaining steps were followed, with its host script run verbatim with sh.
v0.1.0 then started with its 2 chats (the added chat was gone) and the picture, with its file served. The profile was back in browser-profile/, and pi was live in a chat.
Without step 1, 0.1.0 still started. It listed the six leftover entries and could remove them, and the guide says so.
The container form of step 4, at bcbd40f. The form was copied from the guide unchanged, except that --volumes-from pithagoras became a bind mount of a test folder. It passed bash -n, sh -n and zsh -n, and it ran in a throwaway alpine:3.20 container on friday-lab. The pictures from Media's folder, from handoff/media and from a .media.partial folder ended up in images/. The profile ended up in browser-profile/, a cut-off .copy was left behind, and extension-data/ and handoff/ were moved to backups/0.2.0-<stamp>/. All 17 shell blocks in the guide pass the three syntax checks, including the inner scripts of the six sh -c '…' forms.

Tests

friday-lab (node:22, as the node user, at cdb3df2; the later commits change only docs and the docs package version):
- server: 1552 tests, 1524 pass, 20 skipped, 8 fail (the update-routes self-update tests);
- root and extensions: 1918 tests, 1907 pass, 7 skipped, 3 fail and 1 cancelled (docker host-paths mountinfo, the terminal shutdown pair, and the docs store file timing out);
- every failure is on the known list.
Mac (node 22):
- npm run build, check:boundaries and docs:build, with every anchor link in the changed pages checked: 138 anchor links, none broken;
- the root tests touched: 41/41 with the Git drafts test, and after the docs version change extension-api-package, license, lockfile, deploy-files and extension-packages again, 31/31;
- server upgrade tests: 71/72; the one failure is the known macOS port test (Server tests fail as root and under full-suite load #43).

Release notes

The docs have no place for release notes, so the GitHub release body is written separately, in the style of v0.1.0's. It starts with what 0.2.0 is and the counts: from 7 October 2026 up to #302 on 23 October, together with this pull request, 137 commits and 132 merged pull requests, 74 by @thecodacus and 58 by @Piggidragon. These counts assume this PR is squash-merged and nothing else merges before the tag. Then come the upgrade notes, the known issues, what is new in each area with PR numbers (#294 to #302 included, and #198's move to core/), and the thanks to contributors.

Since the review, main was merged in again with #300 (Files: Refresh reads the open file again, part of #292), #301 (the Settings rail's groups fold, #268) and #302 (voice conversations can be switched off while dictation stays, #287). None of them changes an upgrade: #302's switch is on by default.

After this merges

Merge this PR.
If anything else merged first, recount with git rev-list --count v0.1.0..v0.2.0 and the merged-PR list, and update the counts in the release notes.
Tag v0.2.0 on main. docker.yml builds ghcr.io/thecodacus/pithagoras:0.2.0, and publish-extension-api.yml runs.
The workflow is expected to fail at npm publish the first time. Publish 0.2.0 by hand from a clean checkout of v0.2.0 (npm publish --provenance=false -w packages/extension-api) using the token in ~/.npmrc, before it expires around 2026-10-29.
Publish the GitHub release with the notes.
Deploy to friday when the owner says to.

🤖 Generated with Claude Code

The portal, @pithagoras/extension-api and the docs site move from 0.1.0 to 0.2.0, in package.json and in the lock's entries for them, as tests/extension-api-package.test.mts requires for the tag v0.2.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…a whole v0.1.0 data folder in one start v0.1.0 filed its picture tools as the set "<portal:images>". #164 renamed the set "<portal:media>" without carrying a name given to it, and the Media hand-off (schema 7) moved only "<portal:media>" to pithagoras-media, so a name a person gave the set in v0.1.0 was lost. The hand-off now moves both, the newer one first. The new test starts from fixtures/portal-v3.db with something of every part an extension holds now, kept as v0.1.0 kept it: a canvas, a Media page picture and its file, the image endpoint, voice mode connected to the voice service with the person's own addresses remembered, a designed voice and a clone, the GPU, Understory's settings and MCP entry, the browser's settings and a local profile, the allowlist, a heartbeat rule for routine_update, the tools seen and the sets' names. One start takes it to schema 11 with one backup, portal-v3-….db, and leaves media, browser, voice-service, voice-addresses and understory for their extensions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…nstall has Two items of the v0.1.0 checklist (#221) were ticked without a test that would fail: - server/dist/index.js, reset-password.js and sso-only-off.js: scripts/old-entries.mjs is run into a folder of its own, and each file it writes runs the file of the same name in core/server/dist with the arguments it was given. The build runs the script, and the Dockerfile copies server/dist. - Git drafts: a commit message or a pull request's text that v0.1.0's own Git panel kept in the tab's session storage, under pithagoras.git-draft.<key>, is read and written by the extension's gitDrafts under the same name. tests/drafts.test.mts only used the prefix as a string. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…r is added and removed again #295 judges nothing the first time the portal looks at mcp.json, so a tool of a server taken out by hand before then stays listed. The MCP guide sent the person to tools_seen in the database. Adding the server again under its name in Settings → MCP and removing it there forgets its tools as any removal does; the new test checks that, and the guide says it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…he configuration reference lacked - settings.md: the Agent group lists Sandbox and Guard, as the rail has them. - deploying.md: PORTAL_DEFAULT_EXTENSIONS names the six extensions a portal starts with, not two. - configuration.md: rows for PORTAL_DEFAULT_EXTENSIONS and BROWSER_BIND, which .env.example and both Compose files have. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The guide had a section for each move made on main, written for a portal that followed main, and a section called "Upgrading from the first release" that was mostly 0.1.0's own notes for builds before it. It now reads true for a portal at 0.1.0: - From 0.1.0 to 0.2.0: schemas 3 to 11 in one start with one backup (portal-v3-….db), in order, each linked to its section; what the person does; the pages, settings and routes that moved, as 0.1.0 named them (Settings → Agent → Images, Settings → Add-ons, the allowlist on the Browser page); the new environment variables; what does not carry over. - New sections for steps that had none: agents' and routines' tools (schema 4), code mode off by default, the six extensions a portal starts with and the ones it does not install, the terminal and Git as extensions (routes, T, panel places), a tool's files on old picture calls (schema 6), the guard (taint only on a suspected injection, MCP output, heartbeat rules, a routine's exemptions), MCP servers taken out by hand (#295's first look, dotted names from #296), and pi 1.1. - Canvases: the routes, D and the panel's place. Media: 0.1.0's /settings/images and its Images group. Browser: the allowlist's old place and route. Voice: the container is given unless-stopped in place (#298), which needs Docker for extensions 1.2.0, and nothing remakes it before Voice is installed. - The section for builds before 0.1.0 is renamed "Upgrading to 0.1.0 from an earlier build" and keeps only 0.1.0's own items; the password, pi 1.1 and the voice container moved to 0.2.0's sections, and the heartbeat line says 0.2.0 removes a heartbeat's rules too. - Going back to 0.1.0: one procedure, from removing the extensions 0.1.0 does not have to remaking Understory's container. tests/deploy-files.test.mts follows the renamed section. tests/extension-packages.test.mts pins extensions/defaults.json to the six packages the guide lists. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Going back was run once on friday-lab: a v0.1.0 data folder with two chats, a picture of the Images page and a local Chrome profile, upgraded by this branch, a chat added, then put back with the steps of "Going back to 0.1.0" and started on v0.1.0 (66a35a4). It answered with its two chats and the picture, its file served, the profile in browser-profile/, and pi started in a chat. Left in pi's settings.json, the six extensions a portal starts with did not stop 0.1.0 or its pi; it lists them under Settings → Extensions, where they can be removed. Step 1 now says so. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Notes came with builds of main between #169 and #200 and is a test fixture now; the portal retires only theme-dusk and theme-warm, so a portal that installed Notes from extensions/notes keeps an entry whose folder is gone. The guide says to remove it under Settings → Extensions. 0.1.0 never had it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…hat 0.1.0's defaults were Going back to 0.1.0, step 4: the container form is written out, as Media's and Browser's are. Its comments no longer have apostrophes, which closed the single quote of `sh -c '…'`, so that only `cd /data` ran in the container and the rest on the host. Checked with bash -n, sh -n and zsh -n, and run in an alpine container on a copy of a data folder. The new environment variables: unset, the fetch and Understory waits are 30 minutes where 0.1.0 had Node's five, and a checkout looks for new commits at the start and every six hours. What you do gains Node 22.19 for a checkout and dropping docker-compose.voice.yml from the start command. The moved-routes table names the Voice and Understory routes that were renamed. The voice container comes back after a restart with Docker 29 or later. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Nothing reads the docs package's version, and the release steps in extension-ui.md and tests/extension-api-package.test.mts name only the portal's package.json, packages/extension-api/package.json and those entries of the lock. The release now changes only those. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…estart with Docker 29 or later Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

coderabbitai · 2026-10-23T17:50:13Z

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 4 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 2 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Source mode: Auto
Repository: Unavailable
Branch: Unavailable
File: No configuration file from this repository applied
Commit: Unavailable
Layers: defaults
Review profile: CHILL
Plan: Advanced
Run ID: b4dbcd68-d839-43bb-90ad-c9c186ef52d1

📥 Commits

Reviewing files that changed from the base of the PR and between bb0bf66 and b6cd2db.

⛔ Files ignored due to path filters: 1

package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing: 13

core/server/src/db.ts
core/server/test/mcp-edited-outside.test.mjs
core/server/test/schema-fingerprint.test.mjs
docs/guide/deploying.md
docs/guide/mcp.md
docs/guide/settings.md
docs/guide/upgrading.md
docs/reference/configuration.md
extensions/git/test/drafts.test.mts
package.json
packages/extension-api/package.json
tests/deploy-files.test.mts
tests/extension-packages.test.mts

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

thecodacus and others added 12 commits October 23, 2026 21:43

chore(release): 0.2.0

a1db1b2

The portal, @pithagoras/extension-api and the docs site move from 0.1.0 to 0.2.0, in package.json and in the lock's entries for them, as tests/extension-api-package.test.mts requires for the tag v0.2.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Merge remote-tracking branch 'origin/main' into chore/release-0.2.0

1821330

docs(upgrading): going back, the voice container comes back after a r…

b6cd2db

…estart with Docker 29 or later Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

thecodacus merged commit fbcbf31 into main Oct 23, 2026
5 checks passed

thecodacus mentioned this pull request Oct 23, 2026

Server tests fail as root and under full-suite load #43

Open

Navigation Menu

Repository navigation

chore(release): 0.2.0 - #303

chore(release): 0.2.0#303
thecodacus merged 12 commits into
mainfrom
chore/release-0.2.0

thecodacus commented Oct 23, 2026

Uh oh!

coderabbitai Bot commented Oct 23, 2026

Review limit reached

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

thecodacus commented Oct 23, 2026

Version bump

What changed besides the docs

The upgrading guide

The #221 checklist

Upgrade test

Tests

Release notes

After this merges

Uh oh!

coderabbitai Bot commented Oct 23, 2026

Review limit reached

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant