From 0e2f3197eb536bc89f1bd5fb01734545337c6cfd Mon Sep 17 00:00:00 2001 From: "shumeiko.it" Date: Sun, 1 Nov 2026 02:21:20 +0100 Subject: [PATCH] docs: describe the release workflow now that it is merged The architecture guide, AGENTS.md and the threat model said releases were built by hand or Windows-first; ADR-0009 still listed the release workflow as future work. The Windows build guide named the missing Settings > API Keys tab. --- .gitignore | 3 +-- AGENTS.md | 5 +++-- THREAT_MODEL.md | 8 ++++---- docs/ARCHITECTURE.md | 10 ++++++---- docs/install.md | 3 ++- docs/oss/adr/0009-installer-server-archive.md | 3 ++- docs/oss/adr/README.md | 2 +- docs/oss/build-windows.md | 2 +- 8 files changed, 20 insertions(+), 16 deletions(-) diff --git a/.gitignore b/.gitignore index 4e17c05..68888b0 100644 --- a/.gitignore +++ b/.gitignore @@ -33,8 +33,7 @@ node-compile-cache/ marketplace.db !packages/marketplace/marketplace.db -# Code signing (LAUNCH-06 pilot self-sign artifacts — never commit private -# cert material or operator-local thumbprints into the repo) +# Code signing material: never commit private certificates or local thumbprints *.pfx app/src-tauri/.thumbprint.txt diff --git a/AGENTS.md b/AGENTS.md index 012e364..00c56e0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -149,8 +149,9 @@ npm run dev:server # sidecar on http://localhost:3333, serves the UI from tsx, Vitest, Vite and the sidecar bundle resolve (P2.1). No `build:packages` is needed before running or testing; it builds the `dist/` entries for publishing. - The desktop app (`app/`) has its own dependencies outside the npm workspaces: run - `npm ci` in `app/` once, then `npm run tauri:build:mac:arm64` (or the script for your - platform). It needs a current Rust toolchain. Set `CI=true` when the build runs without + `npm ci` in `app/` once, then `npm run tauri:build:mac:arm64` (or `tauri:build:mac:x64`, + `tauri:build:win`, `tauri:build:linux`). It needs a current Rust toolchain. Releases are + built and smoke-tested on all targets by `.github/workflows/release.yml`. Set `CI=true` when the build runs without access to Finder, or the DMG step fails while styling the disk image window. The Windows installer must be built on Windows: see [docs/oss/build-windows.md](docs/oss/build-windows.md). - The sidecar registers routes for the files in `dist/` when it starts (`@fastify/static` diff --git a/THREAT_MODEL.md b/THREAT_MODEL.md index 1fcde5e..afc3ea6 100644 --- a/THREAT_MODEL.md +++ b/THREAT_MODEL.md @@ -1,9 +1,9 @@ # Waggle OS — Threat Model -Waggle OS is a **workspace-native AI agent platform with persistent memory**. The current -launch scope is a Windows-first Tauri desktop binary with a bundled Node.js sidecar; -macOS packaging and certification remain roadmap work. This document states the trust -boundary and the controls that enforce it. +Waggle OS is a **workspace-native AI agent platform with persistent memory**. The community +edition ships a Tauri desktop app for Windows, macOS and Linux and a headless server +installer, both running the same Node.js sidecar on a bundled Node runtime. This document +states the trust boundary and the controls that enforce it. > Status: living document. The controls below are implemented and cited to source. > Known gaps are open and honestly listed. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 5a9c83e..0c42cd1 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -185,14 +185,16 @@ payload and `apps/web/dist` into the server archive for that target, with a `.sh ```bash npm ci (cd app && npm ci) -(cd app && npm run tauri:build:mac:arm64) # or tauri:build:mac:x64, tauri:build:win, tauri:build +(cd app && npm run tauri:build:mac:arm64) # or tauri:build:mac:x64, tauri:build:win, tauri:build:linux npm run build:server-archive # set TARGET_ARCH=x64 after an x64 macOS build ``` The Windows build must run on Windows; see [docs/oss/build-windows.md](oss/build-windows.md). -The first community release is unsigned ([docs/oss/signing.md](oss/signing.md)). The release -workflow for the community edition is not set up yet, so releases are built by hand on each -system. +Releases are built by `.github/workflows/release.yml`. On each target (Windows x64, macOS +arm64 and x64, Linux x64) it stages the sidecar, packs the server archive, builds the Tauri +bundles and smoke-tests both the server installer and the installed desktop app. A `v*` tag +creates a draft GitHub release with a `SHA256SUMS` file. The first community release is +unsigned, apart from an ad-hoc signature on macOS ([docs/oss/signing.md](oss/signing.md)). Shipped dependencies are checked for licenses that allow MIT distribution (`npm run check:licenses`, and `cargo deny` for the Rust crates), and their notices are in diff --git a/docs/install.md b/docs/install.md index 9bd97f8..4af2d83 100644 --- a/docs/install.md +++ b/docs/install.md @@ -40,7 +40,8 @@ Waggle uses the WebView2 runtime, which ships with current Windows 10 and 11. 1. Download the `.dmg` for your Mac: `Waggle__aarch64.dmg` for Apple silicon, `Waggle__x64.dmg` for Intel. (Apple menu → **About This Mac** shows the chip.) 2. Open the `.dmg` and drag **Waggle** to **Applications**. -3. Open Waggle. Because the app is not signed, macOS blocks the first launch: +3. Open Waggle. Because the app is not signed with an Apple Developer ID, macOS blocks the + first launch: - macOS 15 and later: after the warning, open **System Settings** → **Privacy & Security**, scroll to the message about Waggle and choose **Open Anyway**. - Earlier versions: Control-click (or right-click) Waggle in Applications, choose **Open**, diff --git a/docs/oss/adr/0009-installer-server-archive.md b/docs/oss/adr/0009-installer-server-archive.md index 0ed4650..7390709 100644 --- a/docs/oss/adr/0009-installer-server-archive.md +++ b/docs/oss/adr/0009-installer-server-archive.md @@ -44,6 +44,7 @@ The project owner chose this over publishing the server to npm on 2026-11-01. tests. - An archive is about 130 MB (macOS arm64); it is downloaded once per version. - `install.sh`, `scripts/waggle-server.sh` and their CI job are removed. -- The release workflow must build the archive on each target system (P1.3d). +- The release workflow (`release.yml`) builds the archive on each target system and + smoke-tests the installer against it. - Windows cannot replace a running program: `update` and `uninstall` there run through `npx`, and the server must be stopped first. diff --git a/docs/oss/adr/README.md b/docs/oss/adr/README.md index edf0f6e..a0f2292 100644 --- a/docs/oss/adr/README.md +++ b/docs/oss/adr/README.md @@ -25,7 +25,7 @@ work packages wait for the answer. |---|---|---| | Licensing review (includes code copied from the Apache-2.0 `hive-mind-core` into MIT `core`, ADR-0007) | Technical license checks continue | P2.3, P2.6 | | Product name and system identifiers | Temporary names | P1.3d, P2.6 | -| Location of the public repository | Manual builds on each OS | P1.3d, P2.6 | +| Location of the public repository | `release.yml` is ready but has not run; the installer has no default download location (`--from`) | P2.6, P2.7 | | Supported platforms for v1 | Windows x64, macOS arm64 and x64, Linux x64 (glibc) | P1.3b, P1.3d | | Installer signing | First release may ship unsigned with launch instructions | P2.5 | | Separate data directory from the commercial edition | Not separated yet | P1.3c | diff --git a/docs/oss/build-windows.md b/docs/oss/build-windows.md index f74a25c..2c5c43d 100644 --- a/docs/oss/build-windows.md +++ b/docs/oss/build-windows.md @@ -114,7 +114,7 @@ node scripts/release-smoke.mjs desktop --app "$env:LOCALAPPDATA\Waggle\waggle.ex Home screen. 3. If it stays on "Starting Waggle…", close it and take the log from `%USERPROFILE%\.waggle\logs\service.log`. -4. Chat needs a model: an API key in Settings → API Keys, or a running Ollama. +4. Chat needs a model: an API key in Settings → Models (Provider Keys), or a running Ollama. Waggle keeps its data in `%USERPROFILE%\.waggle`.