scriptoriumadmin/veritas-kanban
1
0
Fork 0
mirror of https://github.com/BradGroux/veritas-kanban.git synced 2026-08-28 02:44:59 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Add v5 release readiness docs (#546)

Browse source
This commit is contained in:
Brad Groux 2026-06-03 07:49:26 -07:00 • committed by GitHub
parent ea352fcac9
commit 72715f229f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
11 changed files with 502 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
CHANGELOG.md
View file

@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
- Added v5 release readiness docs covering upgrade/install/admin paths,
compatibility matrix, release channels, rollback limits, release notes, and
deferred post-GA platform backlog.
### Changed
- Expanded release validation to cover the desktop package version and required
v5 release documentation.
## [4.3.2] - 2026-05-16
### Added

3
README.md
View file

@ -81,6 +81,9 @@ When the board is working, use [Setup Paths](docs/SETUP-PATHS.md) to choose the
- [v5 Identity and RBAC Model](docs/IDENTITY-RBAC.md) — users, workspaces, memberships, roles, agent tokens, permission matrix, migration, and UX flows.
- [v5 Mantine Migration Plan](docs/UI-MANTINE-MIGRATION.md) — component inventory, migration order, retained custom surfaces, rollback strategy, and cleanup gates.
- [v5 GA Checklist](docs/V5-GA-CHECKLIST.md) — final release gates, Mantine visual/accessibility cleanup evidence, bundle checks, and holdout tracking.
- [v5 Upgrade, Install, Remote, And Admin Guide](docs/V5-UPGRADE-INSTALL-ADMIN-GUIDE.md) — fresh install, v4-to-v5 upgrade, desktop setup, remote/server, mobile/PWA, admin, backup, and diagnostics paths.
- [v5 Compatibility And Release Policy](docs/V5-COMPATIBILITY-AND-RELEASE-POLICY.md) — supported version combinations, update channels, stale-client behavior, rollback limits, and release validation.
- [v5 Release Notes Draft](docs/V5-RELEASE-NOTES.md) — breaking changes, migration warnings, release artifact checklist, and deferred post-GA backlog.
- [v5 Desktop Architecture ADR](docs/architecture/ADR-0001-v5-desktop-architecture.md) — shell decision, native/server boundaries, connection modes, lifecycle, packaging, and security model.
- [Self-Hosting Guide](docs/guides/SELF_HOST.md) — production deployment, reverse proxy, auth hardening, Docker, and backups.
- [Agent Task Workflow SOP](docs/SOP-agent-task-workflow.md) — lifecycle, API/CLI snippets, prompts.

10
docs/DEPLOYMENT.md
View file

@ -717,7 +717,15 @@ sudo journalctl -u veritas-kanban --since "1 min ago"
### Migration Notes
Veritas Kanban runs startup migrations automatically (`runStartupMigrations()` in `server/src/index.ts`). These are idempotent and safe to run on every startup — no manual migration steps are needed during upgrades.
Veritas Kanban runs startup migrations automatically (`runStartupMigrations()`
in `server/src/index.ts`). These are idempotent and safe to run on every
startup.
For v5 file-to-SQLite upgrades, run the dry-run migration, preserve the
pre-migration backup and journal, and follow
[v5 SQLite Migration Recovery](MIGRATION-RECOVERY.md). App rollback after a
SQLite migration is limited by schema compatibility; restore the pre-migration
file-backed backup when an older app cannot open a newer database.
---

6
docs/DESKTOP-RELEASE.md
View file

@ -65,6 +65,10 @@ available, downloading, ready, failed, and unsupported states. The menu enables
download only when an update is available and install only when an update has
downloaded.
The full v5 channel, staged rollout, version-skew, stale-client, and rollback
policy is tracked in
[v5 Compatibility And Release Policy](V5-COMPATIBILITY-AND-RELEASE-POLICY.md).
## Release Checklist
- Bump all workspace package versions together.
@ -79,6 +83,8 @@ downloaded.
- Confirm a first run creates the profile/workspace app data directories.
- Confirm update check, download, install, failed-download, and rollback paths
on the selected channel.
- Confirm `pnpm validate:release` passes and verifies root/shared/server/web,
CLI, MCP, and desktop package versions plus required v5 release docs.
## Smoke Tests

2
docs/FEATURES.md
View file

@ -1871,7 +1871,7 @@ Production-ready deployment and development tooling.
- **Concurrency control** — In-progress runs cancelled when new commits push
- **Pipeline jobs** — Lint and warning budget, type check, workspace unit tests, production build, and security audit
- **Scheduled QA** — Weekly and manually triggered Playwright and k6 gates run outside the fast PR path
- **Release validation** — `pnpm validate:release` checks versions, release docs, built artifacts, and optional GitHub tag/release state
- **Release validation** — `pnpm validate:release` checks root/shared/server/web/CLI/MCP/desktop versions, required v5 release docs, built artifacts, and optional GitHub tag/release state
- **pnpm caching** — Dependency cache for faster CI runs
### Development

88
docs/V5-COMPATIBILITY-AND-RELEASE-POLICY.md Normal file
View file

@ -0,0 +1,88 @@
# v5 Compatibility And Release Policy
This document defines the v5 release compatibility contract across the desktop
app, bundled server, SQLite schema, CLI, MCP, mobile/PWA clients, workflow
engine, WebSocket sync, migration tooling, and updater metadata.
## Compatibility Matrix
| Surface | Supported v5 combination | Version signal | Stale or unsupported behavior | Release validation |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| macOS desktop app | Desktop package, bundled server, web build, shared package, CLI, MCP, and updater metadata must ship from the same workspace version. | `desktop/package.json`, root `package.json`, app bridge `appInfo.version`, updater metadata. | Show desktop update status as failed or unsupported. Do not silently start with a mismatched bundled server. | `pnpm validate:release`, `pnpm desktop:package:mac:unsigned`, `Desktop Artifacts`, and signed `Desktop Release`. |
| Server/API | Current v5 clients target API `v1`. Server responses include `X-API-Version: v1`. | `X-API-Version`, `GET /api/health.version`, package version. | Requests with unsupported `X-API-Version` return `400` with requested, supported, and current versions. | `pnpm validate:release`, CI, API smoke checks. |
| SQLite schema | A v5 app may open supported v5 schema versions only. File-backed v4 data upgrades through the migration service. | SQLite migrations, migration journal, recovery state. | Older apps must refuse newer SQLite databases and direct the admin to a compatible app or pre-migration backup restore. | Dual-storage parity tests, migration fixture tests, `docs/MIGRATION-RECOVERY.md`. |
| CLI | CLI package version should match the target server version for release support. Minor patch skew may read, but write support is not guaranteed. | `vk --version`, `vk setup`, `/api/health.version`, `X-API-Version`. | `vk setup` must show the reachable server version and fail clearly on auth or API incompatibility. | `pnpm validate:release`, CLI build, CLI read/write smoke from setup docs. |
| MCP server/tools | MCP package version should match the target server version when write tools are enabled. | MCP server package version, MCP tool list, `/api/health.version`. | Read tools may work with compatible API `v1`; write tools must fail closed on auth or unsupported API responses. | `pnpm validate:release`, MCP build, MCP read/write smoke from setup docs. |
| Mobile/PWA | Browser/PWA clients must be served from the same trusted origin and build version as the target server. | Web asset hash, service worker scope, `/api/health.version`, WebSocket connection state. | Offline shell may render cached static assets, but API data is not cached and writes are not queued. Stale clients must refresh before writing. | PWA install docs, mobile smoke tests, service worker static-cache checks. |
| Workflow definitions | Workflow definition versions are durable per workflow. Runs store the workflow version they executed. | `workflow.version`, `workflowRun.workflowVersion`. | Existing runs remain readable. New runs should dry-run before execution and block unsupported skill, client-mode, or output-target combinations. | Workflow authoring dry-run tests, skill audit gates, run-service tests. |
| WebSocket protocol | v5 clients use same-origin `/ws` with authenticated human, device, service, or agent context. | Same-origin URL, auth principal, event names, run/task sequence metadata. | Unsupported auth or stale permissions close the socket and require reconnect with a valid session/token. | Realtime sync hardening tests and remote smoke checks. |
| Migration tooling | v4 file-backed projects migrate through dry-run, backup, journaled run, recovery-state, and restore-backup endpoints. | Migration report, migration journal, backup manifest. | Failed migrations keep file storage as the recovery source. Destructive down migrations are not a GA rollback path. | Migration recovery drills, backup/restore tests, release checklist. |
| Updater metadata | Stable, beta, and dev channels publish channel-specific metadata and artifacts. | `latest*.yml`, DMG/ZIP/blockmap artifacts, update status bridge. | Bad metadata must be removed or superseded. App rollback does not roll back a migrated SQLite schema. | `Desktop Artifacts`, signed `Desktop Release`, manual updater smoke. |
## Version Negotiation Rules
1. API clients may send `X-API-Version: v1`; unsupported values fail before the
route handler runs.
2. CLI and MCP setup smoke checks must compare their local package version to
`/api/health.version` and report skew in release verification notes.
3. Desktop local mode uses a bundled server and web build from the same
workspace version. A packaged app must not mix release artifacts from
different commits.
4. Remote and mobile clients must validate `/api/health`, `/health/ready`,
`/api/auth/status`, and `/ws` from the same public origin before the setup
path is marked healthy.
5. A client that cannot prove compatible auth, API version, and same-origin
WebSocket behavior may read cached shell UI only. It must not queue writes.
## Release Channels
| Channel | Purpose | Opt in/out | Promotion gate |
| -------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `dev` | Local packaged testing and controlled development metadata. | `VERITAS_UPDATE_CHANNEL=dev` plus explicit dev updater config. | Local smoke only. Never promoted to users. |
| `beta` | Prerelease testers and release candidates. | `VERITAS_UPDATE_CHANNEL=beta` or prerelease version metadata. | CI, unsigned artifact smoke, migration dry-run, remote/mobile smoke, no open critical/high release blockers. |
| `stable` | Default Mac GA channel. | Default packaged release channel. Users leave prerelease channels by installing stable. | Signed/notarized DMG, updater metadata, migration recovery drill, security/load evidence, docs published. |
Promotion between channels is blocked by failed CI, failed desktop packaging,
failed migration recovery, failed backup/restore, failed remote/mobile smoke,
security blockers, unsigned artifacts in a stable release, or stale docs links
from the GA checklist.
## Rollback Policy
| Asset | Supported rollback | Limit |
| ----------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| App binary | Install the previous signed DMG or supersede the bad update metadata with a corrected release. | Only safe when the existing data schema is compatible with the older app. |
| Bundled server/web runtime | Roll back with the app binary because the server and renderer are packaged together. | Do not mix server/runtime files between releases. |
| Updater metadata | Remove, replace, or supersede bad GitHub release assets and channel metadata. | Existing downloaded updates may still need user cleanup or reinstall guidance. |
| SQLite schema after migration | Restore the pre-migration file-backed backup using the recovery drill. | GA does not promise indefinite destructive down migrations from future SQLite schema versions. |
| Remote/self-hosted server | Admin installs the prior release and restores backup if schema is incompatible. | Auto-updating self-hosted servers is out of v5 GA scope. |
## Unsupported Combination Copy
Use this pattern in UI, CLI, MCP, and support docs:
```text
This Veritas client is not compatible with the connected server or data schema.
Client: <client version>. Server: <server version>. API: <api version>.
Action: update the older side, refresh the PWA tab, or restore the
pre-migration backup with docs/MIGRATION-RECOVERY.md.
```
Do not include tokens, cookies, private keys, local private paths, raw chat
content, or task body text in compatibility errors or debug bundles.
## GA Validation Checklist
Before publishing stable:
1. Run `pnpm validate:release` after `pnpm build`.
2. Run `pnpm validate:release -- --github --repo BradGroux/veritas-kanban`
after the tag and GitHub release exist.
3. Run `pnpm desktop:package:mac:unsigned` and inspect artifact names and
update metadata.
4. Run the `Desktop Artifacts` workflow for unsigned PR artifacts.
5. Run the signed `Desktop Release` workflow only with Apple credentials set.
6. Verify `/api/health.version`, `X-API-Version`, `vk --version`, MCP package
version, desktop app version, and updater metadata all match the release.
7. Verify migration dry-run, migration run, recovery-state, and restore-backup
against the release fixture.

46
docs/V5-GA-CHECKLIST.md
View file

@ -52,6 +52,26 @@ operator checklist for final release verification.
- [ ] Docs cover upgrade, desktop install, remote access, admin operations,
backup/restore, diagnostics, and known platform limits, with ADR 0002 as
the remote/server-mode security baseline.
- [ ] Compatibility and release policy covers desktop/server/API/SQLite/CLI/MCP,
PWA/mobile, workflow, WebSocket, migration, updater channel, staged
rollout, stale-client, and rollback behavior. Track the contract in
[v5 Compatibility And Release Policy](V5-COMPATIBILITY-AND-RELEASE-POLICY.md).
- [ ] Upgrade, install, remote, mobile/PWA, admin, backup/restore, diagnostics,
and first-run setup docs are linked from
[v5 Upgrade, Install, Remote, And Admin Guide](V5-UPGRADE-INSTALL-ADMIN-GUIDE.md).
- [ ] Release notes include breaking changes, migration warnings, artifact
requirements, documentation links, and deferred post-GA backlog. Track the
draft in [Draft v5.0 Release Notes](V5-RELEASE-NOTES.md).
- [ ] `pnpm validate:release` passes after `pnpm build`, including root/shared,
server, web, CLI, MCP, and desktop package version alignment plus required
release documentation checks.
- [ ] Post-GA backlog exists for deferred Linux, Windows, native mobile, cloud
sync/SaaS, and deeper desktop agent workbench scope:
[#541](https://github.com/BradGroux/veritas-kanban/issues/541),
[#542](https://github.com/BradGroux/veritas-kanban/issues/542),
[#543](https://github.com/BradGroux/veritas-kanban/issues/543),
[#544](https://github.com/BradGroux/veritas-kanban/issues/544), and
[#545](https://github.com/BradGroux/veritas-kanban/issues/545).
## Mantine component-system cleanup gate
@ -79,6 +99,32 @@ Run this gate before closing #418, #417, or the v5 release checklist issue.
- [ ] Confirm bundle budgets remain within the `pnpm qa:mantine` thresholds or
record an explicit release-risk acceptance.
## Final Release Validation Commands
Run these before publishing stable:
```bash
pnpm install --frozen-lockfile
pnpm typecheck
pnpm lint:budget
pnpm test:unit
pnpm build
pnpm validate:release
pnpm desktop:package:mac:unsigned
pnpm test:load:smoke
```
After the tag and GitHub release exist:
```bash
pnpm validate:release -- --github --repo BradGroux/veritas-kanban
```
Signed stable publishing requires the `Desktop Release` workflow with the Apple
signing/notarization secrets from [Desktop Release](DESKTOP-RELEASE.md). Record
the workflow run URL, artifact URLs, and updater metadata URLs in the release
notes before marking GA complete.
## Final Sign-Off Notes
Each GA release candidate should link the PRs or workflow runs that satisfy the

94
docs/V5-RELEASE-NOTES.md Normal file
View file

@ -0,0 +1,94 @@
# Draft v5.0 Release Notes
These notes are the source draft for the v5.0 GitHub release. Replace the
package version and artifact links when the signed stable release is published.
## Highlights
- Native macOS desktop app with bundled local server lifecycle, app data paths,
safe-storage backed secrets, menus, notifications, deep links, setup
diagnostics, updater status, and signed/notarized release workflow.
- SQLite-backed v5 storage with file-to-database migration, dry-run reports,
migration journals, backup/export/import, rollback recovery, and dual-storage
parity coverage.
- Multi-user workspaces with roles, memberships, invitations, scoped API
tokens, device sessions, actor attribution, optimistic concurrency, and RBAC
coverage across REST, WebSocket, CLI, MCP, and workflow paths.
- Remote/mobile access for trusted same-origin hosts, secure pairing, hardened
realtime sync, responsive mobile surfaces, and PWA install support with
static-shell-only offline behavior.
- Cohesive v5 work surfaces: Work View, action queue, readiness gates, durable
work products, completion packets, universal search, workflow authoring,
policy decision traces, maintenance center, product modes, skill capability
profiles, skill security scanning, and orchestrator/subagent pipelines.
## Breaking Changes And Migration Warnings
- v5 promotes SQLite as the primary GA storage backend. Run the migration dry
run and preserve the pre-migration backup before accepting the SQLite
database.
- Rolling back the app binary after a SQLite migration is only safe when the
older app supports the current schema. Otherwise restore the pre-migration
file-backed backup.
- Remote/server mode must not rely on localhost bypass. Enable auth, use HTTPS
or a trusted VPN/tunnel, and validate `/api`, `/ws`, manifest, service worker,
and static assets from the same origin.
- PWA/mobile offline support caches only the static shell. It does not cache API
data, WebSocket events, tokens, task contents, comments, work products, or
mutation responses.
- Owner/admin credentials are not for routine agents. Use scoped agent or
service tokens and revoke lost devices or tokens from Settings.
## Fresh Install
1. Install the signed Mac DMG from the stable release.
2. Launch Veritas Kanban and choose Board Only unless you already need agent or
remote setup.
3. Save the recovery key.
4. Verify Settings -> Maintenance health, storage, backup, and debug-bundle
previews.
## Upgrade
1. Back up the existing v4 file-backed project or desktop data directory.
2. Run migration dry-run.
3. Resolve warnings or record accepted risks.
4. Run migration and preserve the journal/report.
5. Verify board, task detail, search, workflows, chat, settings, work products,
Maintenance Center, and audit history.
6. Run backup/export and restore verification before deleting old artifacts.
## Release Artifacts
Stable release must include:
- signed/notarized macOS DMG
- signed/notarized macOS ZIP
- blockmap files
- channel update metadata
- source archive
- changelog entry
- links to upgrade, desktop install, remote/mobile, admin, compatibility, and
GA checklist docs
## Documentation
- [v5 Upgrade, Install, Remote, And Admin Guide](V5-UPGRADE-INSTALL-ADMIN-GUIDE.md)
- [v5 Compatibility And Release Policy](V5-COMPATIBILITY-AND-RELEASE-POLICY.md)
- [v5 GA Checklist](V5-GA-CHECKLIST.md)
- [Desktop Release](DESKTOP-RELEASE.md)
- [Migration Recovery](MIGRATION-RECOVERY.md)
- [Self-Hosting Guide](guides/SELF_HOST.md)
- [PWA Install](guides/PWA_INSTALL.md)
- [Identity, Workspace, And RBAC](IDENTITY-RBAC.md)
- [Maintenance Center](MAINTENANCE-CENTER.md)
- [v5 Security Review](security/v5-security-review.md)
- [v5 Performance And Load Test Notes](testing/v5-performance-load.md)
## Deferred Post-GA Work
- Linux desktop packaging: #541
- Windows desktop packaging: #542
- Native mobile apps with offline execution: #543
- Cloud sync and hosted SaaS model: #544
- Deeper desktop agent workbench features: #545

187
docs/V5-UPGRADE-INSTALL-ADMIN-GUIDE.md Normal file
View file

@ -0,0 +1,187 @@
# v5 Upgrade, Install, Remote, And Admin Guide
This guide is the release-facing entry point for v5 operators. It links the
existing detailed docs and keeps the happy path separate from optional
automation layers.
## Choose The Right Path
| Path | Use when | Start here | Do not configure on day one |
| ----------------------- | ----------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------- |
| Local board from source | You want a personal board and dev server. | `docs/SETUP-PATHS.md` and `docs/GETTING-STARTED.md`. | OpenClaw, MCP writes, Squad Chat webhooks, workflow gates, notifications. |
| Mac desktop local | You want the packaged desktop app and bundled local server. | This guide plus `docs/DESKTOP-RELEASE.md`. | Remote exposure, tunnels, multi-user invitations, external webhooks. |
| v4 to v5 upgrade | You have file-backed v4 data and need SQLite. | Migration steps below plus `docs/MIGRATION-RECOVERY.md`. | Deleting old files before the SQLite migration is accepted. |
| Remote/server | You want trusted LAN, VPN, reverse proxy, or tunnel access. | `docs/guides/SELF_HOST.md` and ADR 0002. | Public exposure without auth, HTTPS, backup, and WebSocket validation. |
| Mobile/PWA | You want phone/tablet access to a trusted host. | `docs/guides/PWA_INSTALL.md`. | Native offline execution or queued writes. |
| Multi-user admin | You manage workspaces, roles, invites, devices, and tokens. | `docs/IDENTITY-RBAC.md` and the admin section below. | Sharing owner/admin tokens with agents. |
## Fresh Mac Desktop Install
1. Download the signed/notarized DMG from the stable GitHub release.
2. Mount the DMG and drag Veritas Kanban into `/Applications`.
3. Launch normally. A stable release should not show a Gatekeeper warning.
4. Pick the first-run path:
- Board Only for a local board with no agents.
- Agent Ready for local agent tooling.
- Remote Server to pair with a trusted host.
- Restore to import a backup.
5. Create the admin password and save the recovery key.
6. Open Settings -> Maintenance and verify health checks, storage, logs, backup,
and debug-bundle previews.
Desktop data lives under:
```text
~/Library/Application Support/@veritas-kanban/desktop/profiles/default/workspaces/local/
```
Desktop secrets use the native safe-storage/keychain path documented in the
desktop architecture and release docs. Do not copy raw keychain payloads between
machines.
## v4 To v5 Upgrade
1. Stop the app and preserve the current repo or app data directory.
2. Run a dry-run migration:
```text
POST /api/v1/sqlite/migration/dry-run
```
3. Review warnings for malformed tasks, duplicate IDs, missing attachments, and
backup copy issues.
4. Run the migration only after the dry run is clean enough to accept:
```text
POST /api/v1/sqlite/migration/run
```
5. Preserve the migration journal, backup directory, and report.
6. Boot v5 with SQLite storage and verify board, task detail, search, workflow,
chat, settings, work products, Maintenance Center, and audit history.
7. Accept the migration only after backup/export and restore drills pass.
Rollback means restoring the pre-migration file-backed backup. Do not rely on
destructive SQLite down migrations for GA users. Follow
`docs/MIGRATION-RECOVERY.md` if the migration fails or an older app sees a
newer database.
## Remote And Server Mode
Remote access is a trusted-host setup, not localhost mode. The supported happy
path serves the web app, `/api`, `/ws`, manifest, service worker, health routes,
and static assets from one HTTPS origin.
Minimum remote checks:
```bash
curl https://kanban.example.com/api/health
curl https://kanban.example.com/health/ready
curl https://kanban.example.com/api/auth/status
```
Then verify a WebSocket upgrade to `wss://kanban.example.com/ws` from the same
origin. Keep `VERITAS_AUTH_ENABLED=true` and
`VERITAS_AUTH_LOCALHOST_BYPASS=false` for remote/server mode.
Use safe LAN, VPN, Tailscale, or reverse-proxy examples from
`docs/guides/SELF_HOST.md`. Split-origin deployments require exact CORS,
WebSocket, service-worker, cookie, and token handling as described in ADR 0002.
## Mobile And PWA
Use mobile/PWA only from a trusted HTTPS host. Pair or sign in first, then
install from Safari or Chrome using `docs/guides/PWA_INSTALL.md`.
Mobile-safe behavior:
- Read board, notifications, work products, workflow runs, approvals, and
settings-lite surfaces allowed by role.
- Status changes are disabled while offline.
- API responses and WebSocket data are not cached for offline replay.
- Writes are not queued for later sync.
Desktop-only behavior remains desktop-only: local app data paths, keychain
management, desktop update checks, local backup/import filesystem actions, and
native menu/deep-link commands.
## Multi-User Admin
Use Settings to manage:
- users and memberships
- roles: owner, admin, member, reviewer, read-only, agent
- invitations and revocation
- trusted devices and paired sessions
- scoped API tokens
- workspaces and workspace switching
Rules:
1. Keep at least one owner.
2. Use admin/member/reviewer/read-only for humans.
3. Use agent or service tokens for automation.
4. Rotate and revoke scoped tokens from the UI when a client is lost.
5. Keep owner/admin credentials out of task descriptions, prompts, logs, and
support bundles.
## Backup, Restore, Diagnostics, And Maintenance
Use Settings -> Maintenance for:
- health checks
- storage summaries
- redacted log tails
- redacted debug bundles
- SQLite export/import reporting
- cleanup previews
- skill security scans
For backup/import API details, see the SQLite portability and Maintenance
Center sections in `docs/API-REFERENCE.md`.
## Assistant-Safe Setup Prompts
Local board:
```text
Set up Veritas Kanban locally using the board-only path first. Verify
localhost:3000 and localhost:3001/api/health. Do not configure OpenClaw, MCP,
Squad Chat webhooks, workflow gates, notifications, or remote access unless I
ask for that layer.
```
Mac desktop:
```text
Install the signed Veritas Kanban Mac app, choose Board Only first-run setup,
save the recovery key, and verify Settings -> Maintenance health. Do not expose
the app to the network or configure integrations yet.
```
Remote/server:
```text
Configure Veritas Kanban as a trusted same-origin HTTPS host. Keep auth enabled,
disable localhost bypass, verify /api/health, /health/ready, /api/auth/status,
and /ws from the public origin, then document the reverse proxy and backup path.
```
MCP/CLI:
```text
Build the CLI or MCP server from this checkout, set VK_API_URL and a scoped
VK_API_KEY, run the documented read/write smoke checks, and do not use owner or
admin credentials for routine agent writes.
```
## Known v5 GA Limits
- Mac is the only desktop GA target. Linux and Windows are tracked in #541 and
#542.
- Mobile GA is responsive web plus PWA, not native offline apps. Native mobile
planning is tracked in #543.
- Hosted cloud sync/SaaS is out of v5 GA scope and tracked in #544.
- Deeper desktop agent workbench features are tracked in #545.
- App rollback after SQLite migration is limited by schema compatibility. Use
the pre-migration backup when an older app cannot open a newer schema.

6
docs/security.md
View file

@ -124,6 +124,12 @@ The v5.0 hardening review is recorded in
including fixed high/critical findings, accepted hardening risks, and the
remaining browser-session GA blocker.
Release compatibility, stale-client behavior, update channels, and rollback
limits are tracked in
[`docs/V5-COMPATIBILITY-AND-RELEASE-POLICY.md`](V5-COMPATIBILITY-AND-RELEASE-POLICY.md).
Compatibility errors and debug bundles must redact tokens, cookies, private
keys, local private paths, raw chat content, and task body text.
## Configuration Reference
### Environment Variables

51
scripts/validate-release.mjs
View file

@ -14,6 +14,7 @@ const packageFiles = [
{ label: 'web', file: 'web/package.json' },
{ label: 'cli', file: 'cli/package.json' },
{ label: 'mcp', file: 'mcp/package.json' },
{ label: 'desktop', file: 'desktop/package.json' },
];
const requiredFiles = [
@ -44,6 +45,30 @@ const buildOutputs = [
{ label: 'web build output', file: 'web/dist/index.html' },
{ label: 'CLI build output', file: 'cli/dist/index.js' },
{ label: 'MCP build output', file: 'mcp/dist/index.js' },
{ label: 'desktop build output', file: 'desktop/out/main/index.js' },
];
const requiredReleaseDocs = [
{
label: 'v5 compatibility and release policy',
file: 'docs/V5-COMPATIBILITY-AND-RELEASE-POLICY.md',
terms: ['Compatibility Matrix', 'Release Channels', 'Rollback Policy'],
},
{
label: 'v5 upgrade install admin guide',
file: 'docs/V5-UPGRADE-INSTALL-ADMIN-GUIDE.md',
terms: ['Fresh Mac Desktop Install', 'v4 To v5 Upgrade', 'Multi-User Admin'],
},
{
label: 'v5 release notes',
file: 'docs/V5-RELEASE-NOTES.md',
terms: ['Breaking Changes And Migration Warnings', 'Release Artifacts'],
},
{
label: 'v5 GA checklist',
file: 'docs/V5-GA-CHECKLIST.md',
terms: ['Final Release Validation Commands', 'Post-GA backlog'],
},
];
const checks = [];
@ -241,6 +266,17 @@ async function main() {
);
}
const desktopPackage = packages.find((pkg) => pkg.label === 'desktop')?.json;
if (desktopPackage) {
for (const scriptName of ['package:mac:unsigned', 'release:mac']) {
check(
`Desktop release script exists: ${scriptName}`,
typeof desktopPackage.scripts?.[scriptName] === 'string',
desktopPackage.scripts?.[scriptName] ?? 'missing'
);
}
}
check(
'packageManager pins pnpm',
/^pnpm@\d+\.\d+\.\d+$/.test(rootPackage.packageManager ?? ''),
@ -278,6 +314,21 @@ async function main() {
`expected ## [${expectedVersion}]`
);
for (const doc of requiredReleaseDocs) {
const docExists = await exists(doc.file);
check(`Required release doc exists: ${doc.label}`, docExists, doc.file);
if (!docExists) continue;
const content = await readText(doc.file);
for (const term of doc.terms) {
check(
`Required release doc section exists: ${doc.label} -> ${term}`,
content.includes(term),
doc.file
);
}
}
if (options.skipBuildOutput) {
skip('Local build output validation', 'skipped by --skip-build-output');
} else {