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

docs: finalize v5 stable release documentation

Browse source
This commit is contained in:
Brad Groux 2026-06-06 00:00:51 -05:00
parent ae7fd15049
commit 5536b51a45
10 changed files with 94 additions and 73 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
README.md
View file

@ -91,11 +91,11 @@ When the board is working, use [Setup Paths](docs/SETUP-PATHS.md) to choose the
- [API Reference](docs/API-REFERENCE.md) — Auth, endpoints, request/response examples, WebSocket, common workflows.
- [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 Visual Tour](docs/V5-VISUAL-TOUR.md) — current dummy-data screenshots and GIFs for the v5 board, task work view, Maintenance Center, and mobile/PWA shell.
- [v5 GA Checklist](docs/V5-GA-CHECKLIST.md) — release-gate reference, follow-up evidence tracking, Mantine visual/accessibility cleanup evidence, and bundle checks.
- [v5 Visual Tour](docs/V5-VISUAL-TOUR.md) — release-safe dummy screenshots and GIFs for the v5 board, task work view, Maintenance Center, and mobile/PWA shell.
- [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 Release Notes](docs/V5-RELEASE-NOTES.md) — breaking changes, migration warnings, published v5.0.0 artifacts, 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.
- [Post-GA Desktop Agent Workbench Spec](docs/DESKTOP-AGENT-WORKBENCH.md) — desktop workbench UX, run controls, approvals, evidence, native affordances, and safety coverage.
- [Post-GA Native Mobile Offline ADR](docs/architecture/ADR-0003-post-ga-native-mobile-offline.md) — native mobile authority model, offline queue semantics, conflict handling, and security review.
@ -767,7 +767,7 @@ pnpm validate:release # Release readiness checks
| Document | Description |
| ---------------------------------------------- | -------------------------------------------- |
| [Features](docs/FEATURES.md) | Complete feature reference |
| [v5 Visual Tour](docs/V5-VISUAL-TOUR.md) | Current dummy-data screenshots and GIFs |
| [v5 Visual Tour](docs/V5-VISUAL-TOUR.md) | Release-safe dummy screenshots and GIFs |
| [API Reference](docs/API-REFERENCE.md) | Auth, endpoints, WebSocket docs |
| [CLI Guide](docs/CLI-GUIDE.md) | Comprehensive CLI usage guide |
| [Self-Hosting Guide](docs/guides/SELF_HOST.md) | Production deployment, reverse proxy, Docker |
@ -786,7 +786,7 @@ pnpm validate:release # Release readiness checks
<details>
<summary><strong>Click to expand v5 screenshots and GIFs</strong></summary>
These captures use dummy release-candidate content against the current v5 app surfaces. See the [v5 Visual Tour](docs/V5-VISUAL-TOUR.md) for the full set and capture notes.
These captures use release-safe dummy content against the current v5 app surfaces. See the [v5 Visual Tour](docs/V5-VISUAL-TOUR.md) for the full set and capture notes.
### Desktop

1
docs/DOC-FRESHNESS.md
View file

@ -58,6 +58,7 @@ When a doc is older than the current version, it may need review.
| Date | Scope | Agent |
| ---------- | ------------------------------------------------------------------- | ------- |
| 2026-06-05 | v5.0.0 stable release docs, install paths, release assets, RC notes | Codex |
| 2026-03-25 | Full v3→v4 version references, governance docs, CHANGELOG, examples | VERITAS |
| 2026-03-21 | v4.0 release documentation | TARS |

2
docs/SOP-squad-chat.md
View file

@ -195,5 +195,5 @@ curl -s -X POST http://localhost:3001/api/chat/squad \
- [docs/features/squad-chat.md](features/squad-chat.md) — Feature deep-dive
- [docs/SQUAD-CHAT-PROTOCOL.md](SQUAD-CHAT-PROTOCOL.md) — Detailed narration rules and examples
- [AGENTS.md — Squad Chat section](../AGENTS.md#squad-chat-narrate-your-own-work-mandatory) — Workspace-level narration rules
- [CLAUDE.md — Agent Guidelines](../CLAUDE.md) — Repository-level agent guidelines
- [SOP-agent-task-workflow.md](SOP-agent-task-workflow.md) — How squad chat fits into the full task workflow

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

@ -1,13 +1,14 @@
# Veritas Kanban v5 GA Checklist
This checklist tracks the release evidence that must be true before v5.0 GA.
The GitHub epic remains the source of scheduling truth; this document is the
operator checklist for final release verification.
v5.0.0 stable is published. This checklist remains the operator reference for
release-gate review, follow-up evidence debt, and future v5 patch candidates.
The GitHub release and release issues remain the source of scheduling truth.
Use [v5 Release Candidate Evidence Packet](V5-RC-EVIDENCE-PACKET.md) as the
single evidence target for each release candidate. The packet is the place to
link command output, workflow runs, signed artifact URLs, checksums,
notarization proof, load results, mobile/PWA smoke proof, and accepted limits.
For future candidates, use
[v5 Release Candidate Evidence Packet](V5-RC-EVIDENCE-PACKET.md) as the single
evidence target. The packet is the place to link command output, workflow runs,
signed artifact URLs, checksums, notarization proof, load results, mobile/PWA
smoke proof, and accepted limits.
## Required Release Gates
@ -60,8 +61,8 @@ notarization proof, load results, mobile/PWA smoke proof, and accepted limits.
backup/restore, diagnostics, visual walkthroughs, and known platform
limits, with ADR 0002 as the remote/server-mode security baseline. The
dummy-data documentation media set lives in
[v5 Visual Tour](V5-VISUAL-TOUR.md); real RC proof still belongs in the
evidence packet.
[v5 Visual Tour](V5-VISUAL-TOUR.md); candidate proof belongs in the
reusable evidence packet or the linked GitHub release issue.
- [ ] 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
@ -71,7 +72,7 @@ notarization proof, load results, mobile/PWA smoke proof, and accepted limits.
[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).
stable notes in [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.
@ -112,7 +113,7 @@ Run this gate before closing #418, #417, or the v5 release checklist issue.
## Final Release Validation Commands
Run these before publishing stable:
Run these before any future stable publication or v5 patch promotion:
```bash
pnpm install --frozen-lockfile
@ -132,15 +133,15 @@ After the tag and GitHub release exist:
pnpm validate:release -- --github --repo BradGroux/veritas-kanban
```
Signed stable publishing requires the `Desktop Release` workflow with the Apple
Signed 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 and the [v5 Release Candidate Evidence Packet](V5-RC-EVIDENCE-PACKET.md)
before marking GA complete.
for each candidate that needs retained evidence.
## Final Sign-Off Notes
Each GA release candidate should link the PRs or workflow runs that satisfy the
gates above from [v5 Release Candidate Evidence Packet](V5-RC-EVIDENCE-PACKET.md).
If a gate is intentionally deferred, link the follow-up issue and state the
user-visible risk in release notes.
Each release candidate should link the PRs or workflow runs that satisfy the
gates above from [v5 Release Candidate Evidence Packet](V5-RC-EVIDENCE-PACKET.md)
or the linked GitHub issue. If a gate is intentionally deferred, link the
follow-up issue and state the user-visible risk in release notes.

34
docs/V5-RC-EVIDENCE-PACKET.md
View file

@ -1,16 +1,17 @@
# v5 Release Candidate Evidence Packet
Use this packet for each v5 release candidate before marking GA complete. Keep
links to GitHub workflow runs, release assets, screenshots, logs, and command
output artifacts here or in the linked GitHub issue. Do not paste secrets,
tokens, private keys, raw chat/task content, or unredacted local private paths.
The filled packet is the evidence target for #644.
Use this packet for future v5 release candidates and for retained follow-up
evidence tied to v5.0.0 release issues. Keep links to GitHub workflow runs,
release assets, screenshots, logs, and command output artifacts here or in the
linked GitHub issue. Do not paste secrets, tokens, private keys, raw chat/task
content, or unredacted local private paths. The reusable packet remains the
evidence target for #644.
## Candidate Identity
| Field | Value |
| --------------------- | ----- |
| RC label | |
| Candidate label | |
| Release version | |
| Git tag | |
| Commit SHA | |
@ -175,16 +176,17 @@ Security release notes:
The checked-in dummy-data docs media lives in
[v5 Visual Tour](V5-VISUAL-TOUR.md). Use this section to confirm the docs assets
still match the RC UI and to attach real RC screenshots or recordings.
still match the candidate UI and to attach real screenshots or recordings when
release evidence is required.
| Surface | Docs asset | RC proof |
| ------------------------- | ------------------------------------------ | -------- |
| Desktop board | `docs/assets/v5/v5-board-overview.png` | |
| Board/workflow/audit GIF | `docs/assets/v5/v5-board-to-workflow.gif` | |
| Task work view | `docs/assets/v5/v5-task-work-view.png` | |
| Maintenance Center | `docs/assets/v5/v5-maintenance-center.png` | |
| Mobile/PWA board | `docs/assets/v5/v5-mobile-pwa-board.png` | |
| Mobile/PWA navigation GIF | `docs/assets/v5/v5-mobile-pwa-flow.gif` | |
| Surface | Docs asset | Candidate proof |
| ------------------------- | ------------------------------------------ | --------------- |
| Desktop board | `docs/assets/v5/v5-board-overview.png` | |
| Board/workflow/audit GIF | `docs/assets/v5/v5-board-to-workflow.gif` | |
| Task work view | `docs/assets/v5/v5-task-work-view.png` | |
| Maintenance Center | `docs/assets/v5/v5-maintenance-center.png` | |
| Mobile/PWA board | `docs/assets/v5/v5-mobile-pwa-board.png` | |
| Mobile/PWA navigation GIF | `docs/assets/v5/v5-mobile-pwa-flow.gif` | |
Visual docs notes:
@ -199,7 +201,7 @@ Visual docs notes:
| Are all critical/high v5 release blockers closed? | |
| Are all deferred items linked as post-GA issues? | |
| Are user-visible limits documented in release notes? | |
| Is this RC approved for stable publication? | |
| Is this candidate approved for publication? | |
Decision notes:

37
docs/V5-RELEASE-NOTES.md
View file

@ -1,7 +1,13 @@
# Draft v5.0 Release Notes
# 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.
These notes describe the published Veritas Kanban v5.0.0 stable release.
- GitHub release:
[Veritas Kanban v5.0.0](https://github.com/BradGroux/veritas-kanban/releases/tag/v5.0.0)
- Supported packaged install:
`brew tap BradGroux/tap && brew install --cask veritas-kanban`
- Manual macOS install:
[Veritas-Kanban-5.0.0-mac-arm64.zip](https://github.com/BradGroux/veritas-kanban/releases/download/v5.0.0/Veritas-Kanban-5.0.0-mac-arm64.zip)
## Highlights
@ -68,16 +74,23 @@ package version and artifact links when the signed stable release is published.
## Release Artifacts
Stable release must include:
The v5.0.0 stable release includes:
- 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
| Artifact | SHA-256 |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| [Veritas-Kanban-5.0.0-mac-arm64.dmg](https://github.com/BradGroux/veritas-kanban/releases/download/v5.0.0/Veritas-Kanban-5.0.0-mac-arm64.dmg) | `ea0c98d5e8a57cf9352602a198d840678aeae427d4a5d51c8418f2219cf0c35d` |
| [Veritas-Kanban-5.0.0-mac-arm64.zip](https://github.com/BradGroux/veritas-kanban/releases/download/v5.0.0/Veritas-Kanban-5.0.0-mac-arm64.zip) | `ea492c71c3276de8c44c15e1ccb51fc7d713b5b4f8b8c9f302c0f5dd54e14c32` |
| [Veritas-Kanban-5.0.0-mac-arm64.dmg.blockmap](https://github.com/BradGroux/veritas-kanban/releases/download/v5.0.0/Veritas-Kanban-5.0.0-mac-arm64.dmg.blockmap) | `8a24eeed35f09313488e4fd6feecefada5f4218a97c03879c9d81e7fc43869a7` |
| [Veritas-Kanban-5.0.0-mac-arm64.zip.blockmap](https://github.com/BradGroux/veritas-kanban/releases/download/v5.0.0/Veritas-Kanban-5.0.0-mac-arm64.zip.blockmap) | `0ba0660ff9e82c32c120bf3ec828a5b363db5946df6117cc2073a03cc275981e` |
| [latest-mac.yml](https://github.com/BradGroux/veritas-kanban/releases/download/v5.0.0/latest-mac.yml) | `60baa09d4eb3b93c419178536e639aff74ecd8e5ee72e628f461cd027f945501` |
Checksum sidecars are published as
[`Veritas-Kanban-5.0.0-mac-arm64.dmg.sha256`](https://github.com/BradGroux/veritas-kanban/releases/download/v5.0.0/Veritas-Kanban-5.0.0-mac-arm64.dmg.sha256)
and
[`Veritas-Kanban-5.0.0-mac-arm64.zip.sha256`](https://github.com/BradGroux/veritas-kanban/releases/download/v5.0.0/Veritas-Kanban-5.0.0-mac-arm64.zip.sha256).
The GitHub release also includes the source archive and links to the upgrade,
desktop install, remote/mobile, admin, compatibility, and GA checklist docs.
## Documentation

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

@ -4,10 +4,11 @@ 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.
For current dummy-data screenshots and GIFs of the v5 board, task work view,
Maintenance Center, and mobile/PWA shell, see
[v5 Visual Tour](V5-VISUAL-TOUR.md). Use real RC screenshots in the evidence
packet before publishing stable.
For current release-safe dummy screenshots and GIFs of the v5 board, task work
view, Maintenance Center, and mobile/PWA shell, see
[v5 Visual Tour](V5-VISUAL-TOUR.md). Release evidence, when needed for a future
candidate, belongs in the reusable
[v5 Release Candidate Evidence Packet](V5-RC-EVIDENCE-PACKET.md).
## Choose The Right Path
@ -29,9 +30,10 @@ packet before publishing stable.
brew install --cask veritas-kanban
```
Manual install is also supported from the stable GitHub release by
downloading `Veritas-Kanban-5.0.0-mac-arm64.zip`, unzipping it, and moving
`Veritas Kanban.app` into `/Applications`.
Manual install is also supported from the
[stable GitHub release](https://github.com/BradGroux/veritas-kanban/releases/tag/v5.0.0)
by downloading `Veritas-Kanban-5.0.0-mac-arm64.zip`, unzipping it, and
moving `Veritas Kanban.app` into `/Applications`.
2. Launch normally. A stable release should not show a Gatekeeper warning.
3. Pick the first-run path:

20
docs/V5-VISUAL-TOUR.md
View file

@ -1,16 +1,16 @@
# Veritas Kanban v5 Visual Tour
This page is the v5 documentation media index. The screenshots and GIFs use
dummy release-candidate content captured from the current app surfaces so the
docs can show realistic workflows without exposing real tasks, prompts, logs,
paths, tokens, or customer data.
release-safe dummy content captured from the current app surfaces so the docs
can show realistic workflows without exposing real tasks, prompts, logs, paths,
tokens, or customer data.
## Capture Set
| Asset | Path | Notes |
| ---------------------- | ------------------------------------------ | ------------------------------------------------------------------------------- |
| Board to workflow tour | `docs/assets/v5/v5-board-to-workflow.gif` | Desktop board, task detail, Workflows, and Decision Audit Trail flow. |
| Board overview | `docs/assets/v5/v5-board-overview.png` | Current dark-mode board with v5 release-candidate dummy tasks. |
| Board overview | `docs/assets/v5/v5-board-overview.png` | Current dark-mode board with v5 dummy tasks. |
| Task work view | `docs/assets/v5/v5-task-work-view.png` | Task detail drawer with dummy v5 release smoke content. |
| Maintenance Center | `docs/assets/v5/v5-maintenance-center.png` | Operator diagnostics, storage, cleanup preview, and redacted evidence surfaces. |
| Mobile/PWA board | `docs/assets/v5/v5-mobile-pwa-board.png` | Phone-width board shell with mobile navigation. |
@ -53,15 +53,15 @@ mobile/PWA access. They do not claim native offline execution; v5 PWA offline
behavior remains static-shell-only as documented in the release notes and admin
guide.
## Release Evidence Use
## Documentation Use
Use this page when completing:
- [v5 GA Checklist](V5-GA-CHECKLIST.md)
- [v5 Release Candidate Evidence Packet](V5-RC-EVIDENCE-PACKET.md)
- [v5 Upgrade, Install, Remote, And Admin Guide](V5-UPGRADE-INSTALL-ADMIN-GUIDE.md)
- [Draft v5.0 Release Notes](V5-RELEASE-NOTES.md)
- [v5.0 Release Notes](V5-RELEASE-NOTES.md)
For an actual release candidate, attach real installer, browser, and mobile
smoke evidence to the RC packet. These dummy captures are documentation assets,
not final release-candidate proof.
These dummy captures are documentation assets, not release proof. Future
release-candidate evidence belongs in the reusable
[v5 Release Candidate Evidence Packet](V5-RC-EVIDENCE-PACKET.md) or the linked
GitHub release issue for that candidate.

2
docs/WORKFLOW_ENGINE_ARCHITECTURE.md
View file

@ -1355,7 +1355,7 @@ steps:
- Angle 1: ...
## Sources
1. [Source Title](URL)
1. [Source Title](https://example.com/source)
2. ...
```

10
docs/testing/v5-performance-load.md
View file

@ -3,8 +3,9 @@
Review date: 2026-06-03
This note records the v5.0 performance/load evidence for SQLite-backed local
mode and trusted-host remote/mobile access. Release-candidate evidence belongs
in [v5 Release Candidate Evidence Packet](../V5-RC-EVIDENCE-PACKET.md).
mode and trusted-host remote/mobile access. Future candidate or retained
follow-up evidence belongs in
[v5 Release Candidate Evidence Packet](../V5-RC-EVIDENCE-PACKET.md).
## Target Dataset
@ -114,8 +115,9 @@ HTTP errors below 1 percent plus WebSocket connection errors below 5 percent.
- `v5-remote-mix` validates API, dashboard, search, workflow, chat, and
WebSocket server behavior. It does not measure native mobile browser rendering
performance.
- Scheduled k6 runs use generated seed data. Before GA, attach the workflow
artifacts from a `load_profile=full` run against the release candidate to
- Scheduled k6 runs use generated seed data. For future candidates or retained
release evidence, attach the workflow artifacts from a `load_profile=full`
run against the candidate to
[v5 Release Candidate Evidence Packet](../V5-RC-EVIDENCE-PACKET.md).
- Large-team or SaaS-style deployments need follow-up load profiles with higher
seed counts and longer soak windows.