Migrating to 5.0

Vocion 5.0 shipped on 2026-10-07 (v5.0.0). main is now 5.x; 4.x is maintained on the 4.x branch and keeps getting fixes. The full branch and tag policy is in Release lines and upgrades.

What changed

Area	4.x	5.0
Navigation	One long sidebar per workspace, switcher at the bottom	An app rail: Workforce first, then each app a person has in any workspace, then Add app. Each app's nav opens with a workspace picker filtered to the workspaces that have it
Apps	Plugins only	Plugins are grouped into apps. Software Factory = `software-factory` + `production-watch`; GTM = `proposals`, `data-rooms`, `growth-loop` and the GTM surfaces. Rows those plugins own move out of Workforce's nav into their app's nav
People	Members of shared workspaces	Every member also gets a personal workspace (private to them, not even admins can open it) with an assistant that asks their other workspaces
Review	Per-workspace queue	The Review queue (`/dashboard/inbox`) can show what needs you across workspaces, your own items first
Channels	Slack mentions	A shared Twilio number reaches each sender's own assistant; a reply in a Slack or SMS thread can decide the card raised in that thread

Nothing in workspace YAML had to change for 5.0: no keys were renamed, and an app is "installed" by turning on its plugins, as before. Migrations are additive.

Stay on 4.x

Find the newest 4.x release:

git ls-remote --tags https://github.com/vocion/vocion-core.git 'v4.*' | sort -t/ -k3 -V | tail -2

Use the commit on the ^{} line.

Pin it: a submodule git -C vocion-core fetch origin 4.x --tags && git -C vocion-core checkout v4.y.z, or write the 40-character commit wherever your deploy names it.
If you run the engineering runner, pin VOCION_RUNNER_IMAGE to that commit's runner (ghcr.io/vocion/vocion-runner:sha-<commit>) or to :4.x.
Point any bump automation at 4.x or latest-4. A job that follows main moves you to 5.x on its next run.

Move to 5.x

Pin a 5.x release. Pin a v5.y.z tag from main (never the branch head). On AWS with vocion-stack, set core_ref = "v5.y.z" and run the deploy document.
Pin the runner image to :sha-<commit> or :5.x. The :main runner tag is kept as a 4.x alias; an unpinned 5.x box would pull the 4.x runner.
Migrate the database. npm run db:migrate locally, or let the deploy apply migrations before it swaps the app. 5.0 migrations are additive, so returning to a 4.x pin works without a restore.
Re-apply each workspace: npm run workspace:apply -- <path> --project <slug>.
Optional: create personal workspaces up front. Sign-in creates them as people arrive. To create them all now: npm run personal-projects:backfill --workspace @vocion/core.
Consider turning on workspace access enforcement with VOCION_ENFORCE_WORKSPACE_ACCESS=1, so membership and groups decide who can open a shared workspace.

After the move

Tell people where things went: Data rooms, Proposals, Growth and the factory pages now live under their app on the rail.
Turn on apps per workspace from Add app (Marketplace → Plugins) or with plugins: in workspace.yaml. See Apps and workspaces.
To give people texting, follow Your assistant → Text and Slack.