diff --git a/docs/athens/index.md b/docs/athens/index.md index 48d16669..2e4b80af 100644 --- a/docs/athens/index.md +++ b/docs/athens/index.md @@ -22,6 +22,8 @@ Requirements: - Podman - `just` - Mkosi meeting the minimum in `mkosi.conf` +- OpenSSL (`just genkey` runs `openssl` on the host) +- `sudo` access (`just build-image` and `just clean` run Mkosi as root) - `zstd` - `systemd` @@ -36,6 +38,12 @@ The Mkosi image and partition artifacts are written to `mkosi.output/`. This path remains the existing disk-image build; it does not produce an OCI image. It does not produce a qualified installer ISO or production release. +The committed configuration sets no root password. For a root login on a local +test build, write a password to `mkosi.images/os/mkosi.rootpw` (mode `0600`, +git-ignored) before building; Mkosi reads it in place of `RootPassword=`. Mkosi +stores that password inside the image's `/usr`, so do not hand such an image to +anyone else. + Build the separate Athens bootc OCI image with BuildStream, then export its OCI layout to `buildstream-oci/`: @@ -49,7 +57,9 @@ just lint-oci `just export-oci` checks out the already-built `oci/athens.bst` artifact and requires the `buildstream-oci/` destination not to exist. `just load-oci` imports that local OCI layout into Podman without a registry operation; -`just lint-oci` runs `bootc container lint` on the imported image. +`just lint-oci` runs `bootc container lint` on the imported image, then +`scripts/check-image-access.sh`, which fails if the image has an account with an +empty password, a stored root password, a `NOPASSWD` sudo rule or an autologin. The target layers only Athens's Pantheon/codecs content over the GNOME OS OCI base runtime and sets the `containers.bootc` image label. It does not produce a disk image or push to a registry. @@ -67,6 +77,28 @@ image or prove boot/install/deployment behavior. The OCI bootc path is experimental and local-only; the local lint recipe has not been run, nor has the image been tested through bootc installation/update flows. +Pull requests and pushes to `bst` also run `actions-security.yml`, which checks +the workflows themselves: + +- The `lockfile` job runs `gh actions-lock --verify` (the + [`github/gh-actions-lock`](https://github.com/github/gh-actions-lock) + extension, version pinned in the job). It fails when + `.github/workflows/actions.lock` no longer matches the `uses:` lines in the + workflows, or when a locked pin no longer verifies upstream. +- The `zizmor` job runs the zizmor workflow security linter and fails on any + finding. + +The contract tests include `tests/test_access_invariants.py`. It fails when a +file either image build reads sets a root password, blanks a password, adds a +`NOPASSWD` sudo rule or turns on an autologin. Access for a test build belongs +in git-ignored local configuration, as under "Build locally". + +`actions.lock` is generated; do not edit it by hand. After adding a workflow +or changing any `uses:` line (including a Dependabot action bump), install the +extension once with `gh extension install github/gh-actions-lock`, run +`gh actions-lock` from the repository root, and commit the updated lockfile in +the same pull request. + The GNOME OS junction's secure-boot key sources use its checked-in key-generation template in the default `snakeoil` mode. No signing key is committed or used for production signing; this does not establish a distributable secure-boot trust diff --git a/docs/bluefin-cli/development.md b/docs/bluefin-cli/development.md new file mode 100644 index 00000000..71ecac09 --- /dev/null +++ b/docs/bluefin-cli/development.md @@ -0,0 +1,146 @@ +--- +sidebar_position: 9 +title: "development" +--- + +This guide maps the repository so you can find where a change belongs. For +build, test, and lint commands, see [`CONTRIBUTING.md`](https://github.com/tuna-os/bluefin-cli/blob/main/CONTRIBUTING.md). For +the test layers, see [`testing.md`](https://github.com/tuna-os/bluefin-cli/blob/main/docs/testing.md). For architecture rules that +reviewers enforce, see [AGENTS.md](https://github.com/tuna-os/bluefin-cli/blob/main/AGENTS.md). + +## Top-level layout + +| Path | What it holds | +|---|---| +| `main.go` | Entry point. Hands control to the `cmd` package. | +| `cmd/` | Cobra commands and the TUI destinations they open. | +| `internal/` | Reusable behavior, grouped by package. | +| `docs/` | User and developer docs. `docs/commands/` is generated. | +| `docs/adr/` | Architecture decision records. | +| `scripts/` | Shell suites for TUI smoke tests, state tests, and shell experience. | +| `test/` | Go integration tests. | +| `src/bluefin-cli/` | Dev container feature files. | +| `tools/release/` | Release tooling. | +| `justfile` | Task recipes. Run `just --list`. | + +The repository builds two binaries from one source tree: `bluefin-cli` +(standard) and `bluefin-cli-plus` (`-tags extra`). See +[vanilla-vs-extra.md](https://github.com/tuna-os/bluefin-cli/blob/main/docs/vanilla-vs-extra.md). + +## `cmd/`: command wiring + +Each file registers a Cobra command on the root command in `cmd/root.go` +(for example `doctor.go`, `install.go`, `shell.go`, `profile.go`, `update.go`). +Keep argument parse and wiring code here. Put reusable behavior in `internal/`. + +The `menu*.go`, `shell_menu.go`, and `install_menu.go` files assemble the +interactive menu: + +- `menu.go` defines the `menu` command, starts the TUI with `app.Run`, and + runs the background update check. +- `menu_model.go` describes the main menu as data (items, icons, descriptions). +- `menu_router.go` maps a selected menu value to a handler. +- `menu_native.go` holds in-shell flows: forms, text views, and runner screens + that capture command output. +- `menu_vanilla.go`, `menu_extra.go`, and `menu_extra_actions.go` hold the + parts that differ between builds. + +### Build-tag split + +Features that only ship in the plus build (wallpapers, fonts, sunset) sit +behind the `extra` build tag. Files marked `//go:build extra` hold the real +code. `cmd/extra_stubs.go` (`//go:build !extra`) supplies no-op stand-ins so +the standard build compiles. After you change a conditional feature, check both +builds. `cmd/variant_contract_test.go` and the `*_extra_test.go` files cover +this split. + +## `internal/`: packages + +| Package | Owns | +|---|---| +| `tui/app` | The persistent Bubble Tea program: screen stack, header and footer, command palette, and runners. See below. | +| `tui` and `tui/theme` | Shared styles and theme definitions for the TUI. | +| `shell` | Shell experience for Bash, Zsh, Fish, ash, Nushell, and PowerShell: enabling and disabling, rendering the init script, status, and uninstall. | +| `install` | Packages, bundles, Brewfiles, and wallpaper collections. Embeds Brewfiles and wallpaper metadata from `install/resources/`. | +| `pkgmanager` | Package manager selection on Alpine-family hosts (coldbrew, then apk). | +| `config` | Persisted configuration file. | +| `env` | Config directory lookup and terminal environment detection. | +| `profile` | Portable profiles: export, import, diff, and gist sync. | +| `update` | Checksum-verified self-update. | +| `doctor` | Diagnostic probes, `--fix` remediation, shell startup benchmark, and report rendering (`doctor/render`). | +| `status` | The status report. | +| `motd` | Message-of-the-day handling. | +| `starship` | Starship install and preset themes. | +| `terminal` | Terminal emulator and font setup. | +| `wallpaper` | Native per-platform wallpaper setting. | +| `sunset` | Sunset and sunrise theme and wallpaper switching. | +| `countme` | The Fedora countme protocol implementation. | + +### The TUI (`internal/tui/app`) + +- A `Screen` (`app.go`) is one level of the navigation stack: `Title`, `Init`, + `Update`, `View`, and `KeyHints`. +- Screen types: `MenuScreen` (`menu.go`), `FormScreen` (`form.go`), + `TextScreen` (`text.go`), and `RunnerScreen` (`runner.go`) for captured + task output. `wallpaper_picker.go`, `game.go`, and `dino.go` hold special + screens and art. +- An `Action` (`action.go`) is a registered capability. Menus and the + `ctrl+p` command palette read the same registry, so each action is + reachable from both. Modules call `app.Register` for their own actions. +- `exec.go` releases the terminal for an external interactive program. Use it + only when a command must own the terminal. + +### Shell integration (`internal/shell`) + +- `shells.go` is the registry of managed shells: rc path, init line, and + syntax flavor. Add a shell there. +- `resources/` holds the init scripts (`shell.sh`, `shell.fish`, `shell.nu`, + `shell.ps1`). `nu_aliases.go` generates the Nushell aliases. +- Installation backends are separate from the shell init code: `installers.go` + (shared entry points and Homebrew), `windows_tools.go` (winget), + `install_alpine.go` (coldbrew/apk). `shell.go` keeps enablement, the init + output, and status. + +### Embedded resources (`internal/install/resources`) + +Brewfiles and wallpaper metadata ship inside the binary. Update them with +`just update-resources`, which also rewrites `PROVENANCE.json`. Do not edit +them by hand. + +## How a command reaches `internal/` + +1. `main.go` calls into `cmd`, which runs the root Cobra command. +2. The subcommand's `RunE` in `cmd/.go` parses flags and calls a + function in the matching `internal/` package. +3. For the TUI, `bluefin-cli menu` calls `app.Run` with the main menu screen. + Menu selections go through the router to screens or actions, which call + the same `internal/` functions the CLI commands use. + +## Where to start + +- **Add a command.** Create `cmd/.go`, register it with + `rootCmd.AddCommand` in `init`, put the logic in `internal/`, then run + `just gen-docs` to regenerate `docs/commands/`. CI fails on a stale diff. +- **Add a TUI destination.** Make a type that satisfies `app.Screen`, or + register an `app.Action`. Reuse `RunnerScreen` for tasks that show command + output. +- **Fix or extend shell integration.** Start in `internal/shell` + (`shells.go`, `resources/`), and see the scope rules in + [AGENTS.md](https://github.com/tuna-os/bluefin-cli/blob/main/AGENTS.md). +- **Add a package or bundle.** Update the embedded resources with + `just update-resources`. See [brewfile-guide.md](https://github.com/tuna-os/bluefin-cli/blob/main/docs/brewfile-guide.md). +- **Change config or profile behavior.** Use `internal/config` and + `internal/profile`. See [configuration.md](https://github.com/tuna-os/bluefin-cli/blob/main/docs/configuration.md) and + [profiles.md](https://github.com/tuna-os/bluefin-cli/blob/main/docs/profiles.md). + +## Test layout + +- Unit tests sit beside the code as `*_test.go` in each package. +- `cmd/*_test.go` covers command and menu wiring, including build-variant + contracts. +- `test/` holds Go integration tests that the containerized suite + (`just test`) runs. +- `scripts/` holds the shell suites: `tui-smoke.sh`, `tui-state.sh`, and + `shell-experience.sh`. + +See [`testing.md`](https://github.com/tuna-os/bluefin-cli/blob/main/docs/testing.md) for how to run each layer and add tests. diff --git a/docs/bluefin-cli/getting-started.md b/docs/bluefin-cli/getting-started.md index 8cc15754..5d493a9a 100644 --- a/docs/bluefin-cli/getting-started.md +++ b/docs/bluefin-cli/getting-started.md @@ -1,5 +1,5 @@ --- -sidebar_position: 9 +sidebar_position: 10 title: "getting started" --- diff --git a/docs/bluefin-cli/gnome.md b/docs/bluefin-cli/gnome.md index 3d5602d6..ec098423 100644 --- a/docs/bluefin-cli/gnome.md +++ b/docs/bluefin-cli/gnome.md @@ -1,5 +1,5 @@ --- -sidebar_position: 10 +sidebar_position: 11 title: "gnome" --- diff --git a/docs/bluefin-cli/index.md b/docs/bluefin-cli/index.md index 74439d58..f2533876 100644 --- a/docs/bluefin-cli/index.md +++ b/docs/bluefin-cli/index.md @@ -40,10 +40,14 @@ Never post account credentials or API keys in issues or pull requests. ## 🚀 Installation -> **Status (2026-10-07):** each release ships prebuilt binary assets: -> tarballs for Linux, macOS and Windows, plus native deb and rpm packages. -> The one-liner scripts and direct downloads below work today. A note -> marks each package-manager path that does not work yet. +> **Status (2026-11-19):** each release ships prebuilt binary assets: +> archives for Linux, macOS and Windows, plus native deb and rpm packages +> (see `.goreleaser.yaml`). The latest tag in the repository is v0.11.23; the +> [releases page](https://github.com/tuna-os/bluefin-cli/releases/latest) is +> authoritative for the current version. Package-manager channels depend on +> external registries that this repository cannot check. Their states come +> from [`docs/release-publishing.md`](https://github.com/tuna-os/bluefin-cli/blob/main/docs/release-publishing.md), last +> recorded 2026-10-17, and a note marks each path that is not available. ### One-liner (Linux / macOS) @@ -53,8 +57,8 @@ For more Linux and macOS steps, see the [Linux Setup Guide](https://github.com/t curl -fsSL https://raw.githubusercontent.com/tuna-os/bluefin-cli/main/install.sh | sh ``` -> **Status (2026-10-07):** the script downloads the binary from GitHub release -> assets, published on every release since v0.10.6. +> **Status (2026-11-19):** the script downloads the binary from GitHub release +> assets. Releases have published these assets since v0.10.6. ### One-liner (Windows PowerShell) @@ -70,42 +74,47 @@ Then enable shell integration: bluefin-cli shell powershell on ``` -> **Status (2026-10-07):** same as the Linux/macOS one-liner — the script -> downloads from GitHub release assets, published on every release since -> v0.10.6. +> **Status (2026-11-19):** same as the Linux/macOS one-liner — the script +> downloads from GitHub release assets. Releases have published these assets +> since v0.10.6. ### Homebrew (Linux / macOS) -The preview formula is available from `ublue-os/homebrew-experimental-tap`, -synced from the source-build formula in -[`contrib/homebrew/bluefin-cli.rb`](https://github.com/tuna-os/bluefin-cli/blob/main/contrib/homebrew/bluefin-cli.rb): +```bash +brew tap tuna-os/tap +brew install tuna-os/tap/bluefin-cli +``` + +> **Status (2026-11-19):** GoReleaser publishes the binary formula to +> [`tuna-os/homebrew-tap`](https://github.com/tuna-os/homebrew-tap) on each +> release, with the `HOMEBREW_TAP_SSH_KEY` deploy key. The tap has received +> each release since v0.11.17, and its `Formula/bluefin-cli.rb` is at v0.11.23. +> The [release policy](https://github.com/tuna-os/bluefin-cli/blob/main/docs/release-publishing.md) keeps this channel at +> **preview** until a maintainer records a `brew install` check. + +A source-build preview formula is also available from +`ublue-os/homebrew-experimental-tap`. A maintainer syncs it by hand from +[`contrib/homebrew/bluefin-cli.rb`](https://github.com/tuna-os/bluefin-cli/blob/main/contrib/homebrew/bluefin-cli.rb), so it +can lag behind the current release: ```bash brew tap ublue-os/homebrew-experimental-tap brew install bluefin-cli ``` -> **Status (2026-10-17):** use `ublue-os/homebrew-experimental-tap` above. -> The primary tap [`tuna-os/homebrew-tap`](https://github.com/tuna-os/homebrew-tap) -> is not available yet. The GoReleaser configuration includes the Homebrew -> publisher. It pushes to the tap with the `HOMEBREW_TAP_SSH_KEY` deploy key, -> but the team has not verified a publication yet -> ([#295](https://github.com/tuna-os/bluefin-cli/issues/295)). For maintainer -> key and setup details, see -> [`docs/release-publishing.md`](https://github.com/tuna-os/bluefin-cli/blob/main/docs/release-publishing.md). Once published, -> `brew tap tuna-os/tap && brew install bluefin-cli` will be the primary path. - ### Winget (Windows) ```powershell winget install --id Hanthor.BluefinCLI --exact ``` -> **Status (2026-10-07):** the winget repository has `Hanthor.BluefinCLI` -> **v0.8.1** (microsoft/winget-pkgs#407090). That version predates the -> current v0.11.x release line — **installable, though not current**. A -> newer manifest awaits review; `.github/workflows/winget.yml` is the manual -> fallback to resubmit one. +> **Status (last recorded 2026-10-17; not re-verified):** the winget +> repository had `Hanthor.BluefinCLI` **v0.8.1** (microsoft/winget-pkgs#407090). +> That version predates the current v0.11.x release line — **installable, +> though not current**. Check the +> [winget-pkgs listing](https://github.com/microsoft/winget-pkgs/tree/master/manifests/h/Hanthor/BluefinCLI) +> for the live version. `.github/workflows/winget.yml` is the manual fallback +> to resubmit one. ### Chocolatey (Windows) @@ -113,8 +122,9 @@ winget install --id Hanthor.BluefinCLI --exact choco install bluefin-cli ``` -> **Status (2026-10-07):** the Chocolatey community repository has no -> `bluefin-cli` package yet — **not available**. +> **Status (last recorded 2026-10-17; not re-verified):** no `bluefin-cli` +> package was in the Chocolatey community repository — **not available**. +> The release invocation skips this publisher. ### Scoop (Windows) @@ -123,7 +133,7 @@ scoop bucket add tuna-os https://github.com/tuna-os/scoop-bucket scoop install bluefin-cli ``` -> **Status (2026-10-07):** still not published — `tuna-os/scoop-bucket` +> **Status (last recorded 2026-10-17; not re-verified):** not published — `tuna-os/scoop-bucket` > ships no manifests at all. Like the Homebrew tap above, GoReleaser skips > the Scoop publisher because no one has set the `SCOOP_BUCKET_TOKEN` > repository secret; see @@ -147,8 +157,8 @@ sudo rpm -i bluefin-cli__linux_amd64.rpm yay -S bluefin-cli-bin ``` -> **Status (2026-10-07):** no `bluefin-cli-bin` package exists in the AUR yet -> — **not available**. +> **Status (last recorded 2026-10-17; not re-verified):** no +> `bluefin-cli-bin` package existed in the AUR — **not available**. ### Go Install @@ -424,6 +434,8 @@ grep # ugrep (if installed) output, and fixes for common setup problems. - [`docs/testing.md`](https://github.com/tuna-os/bluefin-cli/blob/main/docs/testing.md): how to run the TUI tests, the test layers, and how to add a test. +- [`docs/development.md`](https://github.com/tuna-os/bluefin-cli/blob/main/docs/development.md): where each part of the code + lives and where to start a change. Maintainers can find package-channel credentials and release checks in [release details](https://github.com/tuna-os/bluefin-cli/blob/main/docs/release-publishing.md). The diff --git a/docs/bluefin-cli/menus.md b/docs/bluefin-cli/menus.md index df81a62e..b304fc6e 100644 --- a/docs/bluefin-cli/menus.md +++ b/docs/bluefin-cli/menus.md @@ -1,5 +1,5 @@ --- -sidebar_position: 11 +sidebar_position: 12 title: "menus" --- diff --git a/docs/bluefin-cli/profiles.md b/docs/bluefin-cli/profiles.md index 457961d2..a27abd51 100644 --- a/docs/bluefin-cli/profiles.md +++ b/docs/bluefin-cli/profiles.md @@ -1,5 +1,5 @@ --- -sidebar_position: 12 +sidebar_position: 13 title: "profiles" --- diff --git a/docs/bluefin-cli/release-publishing.md b/docs/bluefin-cli/release-publishing.md index 3df0d398..d9584e55 100644 --- a/docs/bluefin-cli/release-publishing.md +++ b/docs/bluefin-cli/release-publishing.md @@ -1,5 +1,5 @@ --- -sidebar_position: 13 +sidebar_position: 14 title: "release publishing" --- @@ -63,14 +63,14 @@ Channel states mean: - **Unavailable**: not an advertised installation path, even when publisher configuration exists in the repository. -Status as of 2026-10-17: +Status as of 2026-10-17, with the `tuna-os/homebrew-tap` row updated 2026-11-19: | Channel | State | Contract | |---|---|---| | GitHub archives and one-line installers | Supported | Every stable release; archives are covered by `checksums.txt`. | | GitHub deb and rpm assets | Supported | Every stable release; direct packages only, not a distro repository. | | `ublue-os/homebrew-experimental-tap` | Preview | Source formula is synchronized manually and may lag. | -| `tuna-os/homebrew-tap` | Unavailable | Publisher is configured with the `HOMEBREW_TAP_SSH_KEY` deploy key; publication is not verified yet. | +| `tuna-os/homebrew-tap` | Preview | GoReleaser publishes the binary formula with the `HOMEBREW_TAP_SSH_KEY` deploy key on each release (each release since v0.11.17); no install check is recorded yet. | | Winget (`Hanthor.BluefinCLI`) | Preview | Installable v0.8.1 is stale; normal publication is disabled pending token repair, with a manual resubmission workflow available. | | `tuna-os/scoop-bucket` | Unavailable | Publisher is configured but skipped until `SCOOP_BUCKET_TOKEN` is installed and publication is verified. | | Chocolatey | Unavailable | No package is published; the release invocation explicitly skips this publisher. | diff --git a/docs/bluefin-cli/setup-linux.md b/docs/bluefin-cli/setup-linux.md index 3b9bc1a7..870fbbe9 100644 --- a/docs/bluefin-cli/setup-linux.md +++ b/docs/bluefin-cli/setup-linux.md @@ -1,5 +1,5 @@ --- -sidebar_position: 14 +sidebar_position: 15 title: "setup linux" --- diff --git a/docs/bluefin-cli/setup-macos.md b/docs/bluefin-cli/setup-macos.md index a42d44ac..5c37f191 100644 --- a/docs/bluefin-cli/setup-macos.md +++ b/docs/bluefin-cli/setup-macos.md @@ -1,5 +1,5 @@ --- -sidebar_position: 15 +sidebar_position: 16 title: "setup macos" --- diff --git a/docs/bluefin-cli/setup-windows.md b/docs/bluefin-cli/setup-windows.md index 9d98e3df..c4709448 100644 --- a/docs/bluefin-cli/setup-windows.md +++ b/docs/bluefin-cli/setup-windows.md @@ -1,5 +1,5 @@ --- -sidebar_position: 16 +sidebar_position: 17 title: "setup windows" --- diff --git a/docs/bluefin-cli/testing.md b/docs/bluefin-cli/testing.md index 86ee88a9..339a9b13 100644 --- a/docs/bluefin-cli/testing.md +++ b/docs/bluefin-cli/testing.md @@ -1,5 +1,5 @@ --- -sidebar_position: 17 +sidebar_position: 18 title: "testing" --- diff --git a/docs/bluefin-cli/tools.md b/docs/bluefin-cli/tools.md index d9cd4192..7edc3abb 100644 --- a/docs/bluefin-cli/tools.md +++ b/docs/bluefin-cli/tools.md @@ -1,5 +1,5 @@ --- -sidebar_position: 18 +sidebar_position: 19 title: "tools" --- diff --git a/docs/bluefin-cli/troubleshooting.md b/docs/bluefin-cli/troubleshooting.md index 43809690..b8c5c7b4 100644 --- a/docs/bluefin-cli/troubleshooting.md +++ b/docs/bluefin-cli/troubleshooting.md @@ -1,5 +1,5 @@ --- -sidebar_position: 19 +sidebar_position: 20 title: "troubleshooting" --- diff --git a/docs/bluefin-cli/vanilla-vs-extra.md b/docs/bluefin-cli/vanilla-vs-extra.md index f01ecb01..956f0b4c 100644 --- a/docs/bluefin-cli/vanilla-vs-extra.md +++ b/docs/bluefin-cli/vanilla-vs-extra.md @@ -1,5 +1,5 @@ --- -sidebar_position: 20 +sidebar_position: 21 title: "vanilla vs extra" --- diff --git a/docs/bootc-migrate/ROADMAP.md b/docs/bootc-migrate/ROADMAP.md index f9474165..34b0aff8 100644 --- a/docs/bootc-migrate/ROADMAP.md +++ b/docs/bootc-migrate/ROADMAP.md @@ -116,7 +116,7 @@ validation named in that issue's own scope never shipped. | Cross-base remap + `/etc` conflict policy | implemented in `OstreeDeploy` | #191 covers the gate; same-family E2E remains; #259 covers the cross-family path | #67, #187, #259 | | DE stash/restore (`--de-migrate`) | implemented, detection table-tested | the non-gating Bluefin→Aurora cell passes `--de-migrate` and asserts the stash; evidence depends on the exploratory cell and target registry scan succeeding | #68, #188 | | Identity-DB merge across families | implemented in `cross_family` for conversion, `OstreeDeploy` and `ImageSwap` | composefs and OstreeDeploy cells cover identity preservation; the same-family/native gap remains | #80, #256, #259 | -| composefs → ostree (`ostree_install`, `Strategy::OstreeInstall`) | implemented: alongside install through the target's bootc, ESP snapshot/restore, `/etc` merge, `/var` copy, NVRAM order; the argv builder, ESP path classifier, deployment picker, karg carry-over and the snapshot/restore round trip are table-tested | two non-gating cells (dakota composefs-native → fedora-bootc 44, and → utah testing, #302) assert the route, the fixtures, GRUB first in BootOrder and the preserved rollback entry; never executed on a real host before that cell | #260 | +| composefs → ostree (`ostree_install`, `Strategy::OstreeInstall`) | implemented: alongside install through the target's bootc, atomically journaled boot transaction, hash-verified ESP snapshot/restore, `/etc` merge, `/var` copy, rollback-first `BootOrder`, one-shot target `BootNext`, and target promotion only after an observed boot; the classifier and snapshot/journal round trip are table-tested | two route cells plus two non-gating fault cells assert resume before arming and rollback after the destructive ESP wipe; real-hardware validation remains advisable | #260, #387 | | Package-host rollback artifacts (`package_rollback`, `bootc-rebase undo`) | implemented as a reusable snapshot/stage/undo core; rollback wiring into `Strategy::PackageInstall` remains separate | no E2E cell exercises package-host installation, reboot into `Previous system`, or retention after `bootc upgrade`; wire through #373 and cover in the package-based matrix #380 | #374, #373, #380 | | package → ostree (`Strategy::PackageInstall`) | implemented on the shared alongside-install engine: `/` is bound at `/target` with `rslave`, root-mount kargs are retained, and the old kernel/initramfs/BLS/GRUB paths are snapshotted before bootc empties `/boot`; argv, karg and snapshot selection are table-tested | package-host E2E cells are tracked by #380; the old-system boot entry, package-aware `/etc`, selective data carry and commit remain separate #374–#378 slices | #373, #380 | | composefs → ostree with `/boot` on an encrypted root (`ostree_install::esp_resident`) | implemented: the route detects `/boot` without its own partition on a dm-crypt or `rd.luks.` root, copies the new kernel and initrd to the ESP with a BLS entry that keeps the `ostree=` argument, makes that entry the systemd-boot default and puts systemd-boot first in `BootOrder`; detection, entry parsing, the ESP plan and the staging are table-tested | no E2E cell installs a composefs host with `/boot` on LUKS; the hand-made equivalent was staged on a real host, but its boot is not yet recorded; after `bootc upgrade`, the ESP copy does not follow the new kernel | #305 | @@ -127,6 +127,7 @@ validation named in that issue's own scope never shipped. | `NativeStore` (`composefs-native`) | behind a feature flag, off by default | default path still pins a legacy-CLI builder | #13 | | TUI composefs-host route step (#312) | implemented: background scan, dual-capable route choice, honest notes, bootc-rebase execution | covered by state-machine tests only; tui-migrate cell runs on an ostree host and does not exercise the composefs-host screens or launch bootc-rebase | #312 | | Package-managed source → OSTree (`Strategy::PackageInstall`) | harness support is implemented: checksum-pinned Fedora Cloud, synthesized Workstation, and Ubuntu Cloud disks, cloud-init SSH, package fixtures and Previous system assertions | the three #380 cells are exploratory until the package route and its readiness/report/bootloader pieces (#373–#379) land; the Fedora Cloud cell must be promoted to gating after its first green run on `main` | #373–#380 | +| postmarketOS-family ARM64 laptops (apk, LUKS root, ESP at /boot, devicetree) | implemented: apk host detection, LUKS root preflight, whole-ESP snapshot and restore, bind plan for ESP at /boot, devicetree & arm64 kargs policy, per-board DTB match against the host's `compatible`, and a Previous system rollback entry that also restores the pre-install `BootOrder` | no arm64 E2E cell exists, and none can run in the lanes this repo has: the whole matrix needs `/dev/kvm`, GitHub's arm64 hosted fleet does not surface nested virtualization ([actions/runner-images#14062](https://github.com/actions/runner-images/issues/14062)), and `.github/runs-on.yml` defines x86_64 families only. The cell (LUKS2 argon2id ext4, ESP at /boot, systemd-boot with a `devicetree` entry) therefore needs an arm64 KVM host — a self-hosted arm64 runner or an EC2 Graviton bare-metal RunsOn profile — before it can be written; X13s hardware qualification remains open behind it | #461 | Everything not in this table — the OSTree→ComposeFS migrator itself, including rollback and commit — is covered by the seven-cell E2E matrix. @@ -384,18 +385,21 @@ RFC](https://github.com/tuna-os/bootc-migrate/issues/30) but never got a milestone or an issue. Recorded here so they aren't lost, not because either is imminent: -- **`composefs→ostree` (reverse backend switch)** — now implemented as +- **`composefs→ostree` (reverse backend switch)** — implemented as `Strategy::OstreeInstall` (#260, `crates/bootc-migrate-core/src/ostree_install.rs`): the target image's own `bootc install to-existing-root` runs in a privileged container against the physical root (`/sysroot`), building an - OSTree deployment beside the composefs one with nothing to restore from; - the composefs ESP artifacts are snapshotted before bootc's alongside mode - empties the ESP and restored beside the new shim/GRUB, `/etc` is 3-way - merged (cross-family policy included) and `/var` copied into the - stateroot, and the GRUB firmware entry goes first with "Linux Boot - Manager" kept as rollback. `undo` remains the narrow path for a migration - this tool itself performed. Exploratory: one non-gating cell (dakota → - bluefin) and no rollback subcommand for this direction yet. + OSTree deployment beside the composefs one. The composefs ESP artifacts + are hash-snapshotted before bootc's alongside mode empties the ESP, then + restored and verified immediately after that destructive operation; + `/etc` is 3-way merged (cross-family policy included) and `/var` copied + into the stateroot. The cutover is an atomic journaled transaction (#387): + "Linux Boot Manager" remains first as rollback, the target is armed once + with `BootNext`, restart classifies observed ESP/NVRAM state and either + resumes or repairs, and `commit --apply` makes the observed-good target + persistent. Non-gating route and fault-injection cells exercise both + interruption boundaries. `undo` remains the narrow path for a migration + this tool itself performed. - **Cross-family re-base (Fedora ↔ Ubuntu ↔ Arch) via `bootc switch`** — `cross_family.rs` covers conversion and both switch routes. Target defaults win; source vendor-only files drop; machine state, user files and identity diff --git a/docs/bootc-migrate/index.md b/docs/bootc-migrate/index.md index 6e3aa9f8..61e036be 100644 --- a/docs/bootc-migrate/index.md +++ b/docs/bootc-migrate/index.md @@ -153,9 +153,11 @@ tool does not support a return from ComposeFS to OSTree. The wizard starts in dry-run mode. Press Enter to accept each screen, use ↑/↓ to choose an image, and press Space on the options page to change a setting. -For a live run, turn off dry-run there. The final review needs `CONFIRM` and -Enter before anything changes. You need root for a migration, but you can -browse the catalog without it. +For a live run, turn off dry-run there, or press Enter after a successful +dry-run to review and apply in the same session. The wizard then clears the +old confirmation and does the readiness checks again. The final review needs +`CONFIRM` and Enter before anything changes. You need root for a migration, +but you can browse the catalog without it. ## Coming from a regular (non-bootc) install @@ -305,6 +307,30 @@ ghcr.io/projectbluefin/dakota:stable # default target For other OSTree systems (Aurora, Silverblue), set `--target-image` to the composefs equivalent. +**Utah on OSTree → Utah on composefs.** Utah ships systemd-boot and the +composefs initramfs module of bootc. Thus a Utah install that boots OSTree can +change to the composefs backend with the image that it runs now. The OS stays the +same; only the backend and the bootloader (GRUB → systemd-boot) change: + +```bash +sudo bootc-migrate --target-image ghcr.io/projectbluefin/utah:testing --dry-run +sudo bootc-migrate --target-image ghcr.io/projectbluefin/utah:testing +``` + +On such a host, `sudo bootc-migrate tui` offers this conversion as the +first choice. Utah is pre-alpha, and its `utah -> utah` cell (btrfs on +LUKS) is non-gating. + +> ⚠️ **Not on btrfs until the target's kernel has the btrfs fs-verity fix.** +> +> On btrfs, kernels from 7.2 on can reject data that is correct +> (`fs-verity ... FILE CORRUPTED!` in `dmesg`). The composefs +> store is fs-verity data. The first local run of the cell stopped at the integrity +> check before it staged anything. A host that gets past the check can still +> read `EIO` from its root later. The fix is linux-next `dcf8811f63af`; Utah +> plans to ship Fedora's kernel rebuilt with it. Details and measurements are +> in [docs/support-matrix.md](https://github.com/tuna-os/bootc-migrate/blob/main/docs/support-matrix.md#utah-ostree--utah-composefs). + The target must share a base lineage with the source: its `ID_LIKE` must overlap yours, or both images must ship the same package manager. Bluefin, Silverblue and CentOS-based images are all one dnf family. The tool @@ -650,8 +676,9 @@ Overridable via env: `BASE_IMAGE`, `TARGET_IMAGE`, `DISK_SIZE`, `E2E_PACKAGE_CROSS_FAMILY`. The full matrix is authoritative in `.github/e2e-scenarios.yml`. The nightly -schedule runs it. Each PR and push to `main` runs a round-robin slice of the -gating cells (see the [test guide](https://github.com/tuna-os/bootc-migrate/blob/main/docs/testing.md)): +schedule runs alternate cells, so each cell runs every other night. Each PR +and push to `main` runs a round-robin slice of the gating cells (see the +[test guide](https://github.com/tuna-os/bootc-migrate/blob/main/docs/testing.md)): | Cell | Base → target | Filesystem | Disk | |---|---|---|---| @@ -669,8 +696,11 @@ gating cells (see the [test guide](https://github.com/tuna-os/bootc-migrate/blob | cross-family migration (non-gating) | bluefin:stable → bootcrew/ubuntu-bootc:latest | btrfs | 60G | | cross-family migration (non-gating) | bluefin:stable → bootcrew/arch-bootc:latest | btrfs | 60G | | composefs → ostree (non-gating) | dakota:stable → fedora-bootc:44 | btrfs | 40G | +| composefs → ostree, fault after ESP wipe (non-gating) | dakota:stable → fedora-bootc:44 | btrfs | 40G | +| composefs → ostree, fault before BootNext (non-gating) | dakota:stable → fedora-bootc:44 | btrfs | 40G | | composefs → ostree, Dakota → Utah (non-gating) | dakota:stable → utah:testing | btrfs | 80G | | composefs image swap (non-gating) | dakota:stable → utah:testing | btrfs | 40G | +| ostree → composefs, Utah → Utah (non-gating) | utah:testing → utah:testing | btrfs on LUKS | 60G | | cross-family image swap (non-gating) | tunaOS marlin:gnome → utah:testing | btrfs | 60G | | composefs → ostree, Marlin → Utah (non-gating) | tunaOS marlin:gnome → utah:testing | btrfs | 80G | | tunaOS desktop ring, ostree re-base with `--de-migrate` (4 cells, non-gating) | albacore gnome → niri → cosmic → xfce → gnome | btrfs | 40G | @@ -712,12 +742,12 @@ cargo build --release -p bootc-rebase | Subcommand | What it does | Status | |---|---|---| -| `scan ` | Registry-streamed capability probe of a target image — composefs/ostree readiness, fs-verity requirement, transient root/etc, bootloader payload, desktops, base OS identity, sysusers, initramfs flavor, filesystem expectation, and a `Compatible: YES/NO` verdict with reasons. On a package host it also compares installed software with the target image. `--json` includes the software report for machine consumers. | Done | -| `rebase --target-image ` | Re-base the running system, routing on `--source-backend`/`--target-backend` through the strategy table below. `--plan` prints the route, selected phases, and bootloader policy, then exits without touching the system. | Implemented for ostree→composefs (the MVP pipeline), composefs→composefs (image swap), ostree→ostree (native `bootc switch`, with cross-base UID/GID remap when host and target disagree on distro family — pass `--accept-cross-base` to proceed past the report), and composefs→ostree (`OstreeInstall`, #260: the target's own `bootc install to-existing-root` builds an OSTree deployment beside the composefs root; `/etc` merged, `/var` copied, composefs ESP artifacts restored and its firmware entry kept as rollback; exploratory, one non-gating cell). `--accept-cross-base` also accepts a cross-family target on all three migration routes and selects the cross-family `/etc` policy (#256/#259) | +| `scan ` | Registry-streamed capability probe of a target image — composefs/ostree readiness, fs-verity requirement, transient root/etc, bootloader payload, desktops, base OS identity, sysusers, initramfs flavor, filesystem expectation, and a `Compatible: YES/NO` verdict with reasons. On a package host it also prints a host overview (distribution and family, package manager and count, filesystem layout, boot mode, Secure Boot and SELinux — #371) and compares installed software with the target image. `--json` includes the host overview and software report for machine consumers. | Done | +| `rebase --target-image ` | Re-base the running system, routing on `--source-backend`/`--target-backend` through the strategy table below. `--plan` prints the route, selected phases, and bootloader policy, then exits without touching the system. | Implemented for ostree→composefs (the MVP pipeline), composefs→composefs (image swap), ostree→ostree (native `bootc switch`, with cross-base UID/GID remap when host and target disagree on distro family — pass `--accept-cross-base` to proceed past the report), and composefs→ostree (`OstreeInstall`, #260: the target's own `bootc install to-existing-root` builds an OSTree deployment beside the composefs root; `/etc` merged, `/var` copied, composefs ESP artifacts restored and its firmware entry kept first as rollback; a durable transaction journal verifies ESP/NVRAM state and uses one-shot `BootNext` for the target until commit; exploratory, non-gating cells). `--accept-cross-base` also accepts a cross-family target on all three migration routes and selects the cross-family `/etc` policy (#256/#259) | | `rollback [--reboot]` | Re-order UEFI `BootOrder` back to the previous deployment. | Done | | `undo [--reboot]` | Make the staged package-host `Previous system` entry the bootloader default without removing the new bootc deployment. `--dry-run` prints the exact action. | Core rollback support is implemented for the snapshot produced by PackageInstall; engine wiring is tracked separately in #373 | | `boot-entries [--json] [--interactive] [--rename-branding] [--apply] [--undo]` | Enumerate and classify UEFI boot entries: dead (loader path missing), generic-label, duplicate, firmware-managed, plus which are protected and why. **Dry-run by default** — a bare invocation is the read-only audit. `--interactive` opens a checklist (protected entries are unselectable), `--rename-branding` proposes renaming the booted entry to `PRETTY_NAME`, `--apply` writes the result to NVRAM after a typed confirmation and a restorable snapshot, and `--undo` replays that snapshot. | Audit and the cleanup **planner** are unit-tested (protections, the last-bootable-entry guard, and the "every entry looks dead ⇒ the ESP is wrong" refusal). The gating OSTree re-base E2E cell also renames a live OVMF NVRAM entry, applies the plan, undoes it, and asserts byte-identical `efibootmgr -v` output. This covers the executor and snapshot restore; it does **not** cover the separate, unimplemented GRUB2→systemd-boot flip ([#31](https://github.com/tuna-os/bootc-migrate/issues/31), [#189](https://github.com/tuna-os/bootc-migrate/issues/189)) | -| `commit [--apply] [--yes] [--force]` | After a composefs → ostree re-base has booted, remove the composefs state it kept as rollback (#315). **Dry run by default**: checks that the system booted the OSTree deployment the install report names, that the ESP snapshot and a shim/GRUB firmware entry exist, and that every path of the old `/var` is present in the live `/var`. It then lists every path it would delete, with sizes. `--apply` deletes after a typed confirmation. First it copies the install report and ESP snapshot into the live `/var/lib/bootc-rebase`. Then it removes the old `/var`, the composefs store and the composefs deployments. It never touches the OSTree repo, `/boot`, the ESP or NVRAM. `--force` accepts failed checks. It never accepts a composefs boot or a filesystem mounted inside a path to delete. | Unit-tested against a fixture physical root. The non-gating composefs → ostree cell runs the dry run, then `--apply`, then reboots and checks system health | +| `commit [--apply] [--yes] [--force]` | After a composefs → ostree re-base has booted, remove the composefs state it kept as rollback (#315). **Dry run by default**: checks that the system booted the OSTree deployment the install report names, that the ESP snapshot and a shim/GRUB firmware entry exist, and that every path of the old `/var` is present in the live `/var`. It then lists every path it would delete, with sizes. `--apply` deletes after a typed confirmation. It first requires the boot transaction to classify as complete, promotes the observed-good target entry in UEFI `BootOrder`, and records that promotion. Then it copies the install report and ESP snapshot into the live `/var/lib/bootc-rebase` and removes the old `/var`, the composefs store and the composefs deployments. It never modifies the OSTree repo, `/boot` or the ESP. `--force` accepts failed cleanup checks, but never an unobserved boot transaction, a composefs boot, or a filesystem mounted inside a path to delete. | Unit-tested against a fixture physical root. The non-gating composefs → ostree cell runs the dry run, then `--apply`, observes target-first `BootOrder`, then reboots and checks system health | | `de-migrate stash\|restore` | Move a user's desktop-environment config (GNOME dconf/gnome-shell, KDE kdeglobals/plasma, COSMIC, niri, XFCE) into or out of a stash directory around a cross-DE re-base — union of paths per issue [#68](https://github.com/tuna-os/bootc-migrate/issues/68), never deletes. `--run-hooks` executes `pre-switch.d`/`post-switch.d` scripts with `REBASE_FROM_DE`/`REBASE_TO_DE`/`REBASE_STASH_DIR`/`REBASE_HOME` set. `--dry-run` previews without touching anything. | Done. Also runs automatically inside `rebase --de-migrate`; this subcommand remains the manual escape hatch for images shipping several desktops (which detection refuses to guess between) | | `rebase --de-migrate` | Detects the desktop environment the target image ships (registry-streamed session files, session binaries, and display-manager default session — no `podman pull`) and the one this host runs. When they differ, stashes every human account's outgoing DE config before staging and re-exposes any stash a previous re-base in the other direction left behind, running the `pre-switch.d`/`post-switch.d` hooks around each. | Done, unit-tested; **off by default** — a re-base never touches per-user desktop state unless asked to. The non-gating Bluefin→Aurora E2E cell passes `--de-migrate`, seeds GNOME config, and asserts that the cross-DE plan and stash are created. Because target desktop detection uses the registry scan, this evidence depends on that exploratory cell completing successfully ([#68](https://github.com/tuna-os/bootc-migrate/issues/68), [#188](https://github.com/tuna-os/bootc-migrate/issues/188)) | | `migrate-bootloader --to systemd-boot [--promote\|--undo] [--from-image ]` | GRUB2 → systemd-boot conversion, standalone of a backend re-base. | **Implemented** — stages every existing deployment on the ESP, installs systemd-boot, creates a one-boot `BootNext` trial without changing `BootOrder`, and installs a `kernel-install` resync hook. If the host does not ship `systemd-bootx64.efi`, `--from-image ` supplies a registry-reachable image to extract it from. `--promote` requires that the running system booted from the trial before making it persistent; `--undo` restores the prior firmware order and removes only the migration-owned files. The `bootloader-trial` QEMU cell covers the OVMF BootOrder swap, reboot, resync, promotion, and undo path. | @@ -780,6 +810,13 @@ The report shows third-party package repositories and enabled services that the target lacks. If the registry pass is incomplete, the report does not make absence claims. It does not treat missing evidence as an empty image. +On a package host, `scan` also prints a host overview (#371). The overview +shows the facts that the migration sees on this machine, apart from the +target image. These facts are the distribution, the package manager, and +the package count. They also include the layout of `/`, `/home`, `/boot` +and `/var` with LUKS/LVM, the boot mode, Secure Boot, and SELinux. +`--json` puts the overview under `host`. + A non-dry package-host invocation writes the machine-readable report and its Markdown twin to `/var/lib/bootc-rebase/software-report.json` and `/var/lib/bootc-rebase/software-report.md`. Dry runs and `scan` print the report diff --git a/docs/bootc-migrate/support-matrix.md b/docs/bootc-migrate/support-matrix.md index 418af14b..0965c8eb 100644 --- a/docs/bootc-migrate/support-matrix.md +++ b/docs/bootc-migrate/support-matrix.md @@ -69,10 +69,10 @@ Route availability by frontend (mechanism fact, not a support claim): ## Package-based source hosts These rows are separate from the general route table. -Detection of rpm, dpkg, or pacman plus the readiness checks does not prove +Detection of rpm, dpkg, pacman or apk plus the readiness checks does not prove that a package host can migrate or boot. A row stays **UNPROVEN** until its cell turns green on `main`. Issue #380 owns these cells. -A green Fedora row does not promote Ubuntu, Debian, or Arch. +A green Fedora row does not promote Ubuntu, Debian, Arch, or postmarketOS. A green UEFI/ext4 row does not promote btrfs, XFS, or BIOS. | Source | Package database | Root filesystem | Boot mode | Storage stack | Status | Proof needed | @@ -83,6 +83,7 @@ A green UEFI/ext4 row does not promote btrfs, XFS, or BIOS. | Ubuntu | dpkg | ext4 | UEFI | plain | **UNPROVEN** | Ubuntu cross-family cell green on `main` | | Debian | dpkg | ext4 | UEFI | plain | **UNPROVEN** | Debian cross-family cell green on `main` | | Arch Linux | pacman | ext4 | UEFI | plain | **UNPROVEN** | Arch cross-family cell green on `main` | +| postmarketOS / Alpine | apk | ext4 | UEFI | LUKS root with unencrypted ESP at /boot | **UNPROVEN** | arm64 VM cell with pmOS layout green on `main` (#461) | | Fedora, Ubuntu, Debian or Arch | matching database above | btrfs, XFS or ext4 | BIOS/CSM | plain | **UNPROVEN; preflight refuses** | per-distribution BIOS cell plus implementation that passes preflight | | Fedora, Ubuntu, Debian or Arch | matching database above | btrfs, XFS or ext4 | UEFI | LUKS and/or LVM | **UNPROVEN; preflight refuses** | per-layout cell plus implementation that passes preflight | @@ -100,7 +101,7 @@ first-boot verification (#379) are not ready. | CoreMigration → GRUB2 (`--bootloader grub2`) | **UNPROVEN** | no cell sets it (`grub.rs` is a placeholder; the logic lives in `phase5_setup_bootloader` with no E2E) | | KeepSource on OstreeDeploy (GRUB stays GRUB) | **PROVEN** | gating `bluefin ostree re-base` green on main 33891928677 | | KeepSource on ImageSwap (systemd-boot stays) | **UNPROVEN** | route is RED; nothing separable is proven | -| OstreeInstall GRUB-first + "Linux Boot Manager" rollback entry | **UNPROVEN** | cell is RED; bootloader vs route failure not separated | +| OstreeInstall journaled rollback-first `BootOrder` + one-shot target `BootNext` | **UNPROVEN** | route cell and both fault-boundary cells are non-gating and have not supplied green evidence | | Standalone `migrate-bootloader` (#65/#382) | **IMPLEMENTED; E2E cell added** | `bootloader-trial` stages GRUB2 → systemd-boot with a one-boot trial, kernel-install resync, guarded promotion, and undo; the cell is the pending live proof, while real-hardware firmware behavior remains outside OVMF | | BIOS/CSM (non-UEFI) hosts, any route | **UNPROVEN** | harness boots OVMF/UEFI only; no BIOS cell | | GRUB2-BLS as an endpoint (openSUSE default) | **UNPROVEN** | reference note in `docs/references.md` only | @@ -113,11 +114,12 @@ first-boot verification (#379) are not ready. | CoreMigration, LUKS root (`xfs+crypt`, TPM2 unlock) | **PROVEN** | gating cell green on main 33891928677 | | CoreMigration, LVM-on-LUKS + separate `/var` | **RED** (`main`); green on a PR branch | red on main 33891928677, green on PR 36215098705 — flaky, unproven | | CoreMigration, encrypted `/boot` | **UNPROVEN** | E2E layout assumes unencrypted `/boot`; no code, no cell | -| CoreMigration, btrfs-on-LUKS | **UNPROVEN** | no code path, no cell | +| CoreMigration, btrfs-on-LUKS | **UNPROVEN** | `utah -> utah` cell (`btrfs+crypt`) added, no `main` run yet; see "Utah OSTree → Utah composefs" below | | CoreMigration, detached LUKS headers | **UNPROVEN** | no code path, no cell | -| CoreMigration, passphrase (non-TPM2) unlock | **UNPROVEN** | harness unlocks via swtpm only; no sendkey/passphrase cell | +| CoreMigration, passphrase (non-TPM2) unlock | **UNPROVEN** | the `btrfs+crypt` harness layout injects the passphrase over serial; its only cell has no `main` run yet | | LUKS of any kind on ImageSwap / OstreeDeploy | **UNPROVEN** | no cells; both rely on `bootc switch` native behavior, which no cell exercises under encryption | | LUKS of any kind on OstreeInstall | **UNPROVEN** | `carry_over_kargs` keeps `rd.luks.*`/`rd.lvm.lv` in code, but the route's only cell is RED on unencrypted disk — encryption adds an unproven axis to a red route | +| PackageInstall, LUKS root with unencrypted ESP at /boot (ARM64 postmarketOS) | **UNPROVEN** | core LUKS preflight, whole-ESP snapshot, bind plan, DTB gating, and kargs derivation implemented (#461); arm64 E2E cell pending | ## UKI (boot artifact format) @@ -129,9 +131,11 @@ first-boot verification (#379) are not ready. Consequence for the Utah question: "composefs-capable" in scan output means `prepare-root.conf` enables composefs. It does not tell if the initramfs -has the composefs module (the scan shows that Utah's does not). It also -tells nothing about UKI. The RED/flaky image-swap cell must show if Utah -boots as a composefs deployment. Refer to the backend table, not the scan. +has the composefs module. Images up to the 2026-09 scan had none; the +`testing-20261106` image ships `bootc-root-setup.service` and +`/usr/lib/bootc/initramfs-setup` in its initramfs, and systemd-boot. It +also tells nothing about UKI. Only a cell that boots shows if Utah boots as +a composefs deployment. Refer to the backend table, not the scan. ## Package manager (lineage input) @@ -163,8 +167,8 @@ no package manager, GNOME) → Utah (ostree, GRUB via bootupd, GNOME). | Axis | Status for this pair | |---|---| -| Backend (composefs → ostree) | **RED** with `fedora-bootc:44`; **no cell** with Utah — unproven for this pair | -| Bootloader (systemd-boot → GRUB-first + rollback entry) | **UNPROVEN** (only exercised inside the RED cell) | +| Backend (composefs → ostree) | **RED** with `fedora-bootc:44`; Utah has an active non-gating cell but no green evidence | +| Bootloader (systemd-boot fallback first → one-shot GRUB `BootNext` → promote after observed boot) | **UNPROVEN** (route and fault-boundary cells have not supplied green evidence) | | LUKS (btrfs-on-LUKS source) | **UNPROVEN** (no btrfs-on-LUKS cell on any route) | | UKI | N/A — ostree target boots BLS/GRUB, not a UKI question | | Package manager (none → ?) | **UNPROVEN** (Unknown-lineage path, no green E2E) | @@ -195,6 +199,38 @@ a supported migration. What would promote it, in order: 4. LUKS coverage for the route last — it is the hardest axis to add (swtpm + fisherman recipe per `docs/luks-testing.md`). +## Utah OSTree → Utah composefs + +The same image, converted in place by CoreMigration. The TUI offers it first +on an OSTree Utah host. Status: **UNPROVEN** — the `utah -> utah` cell has no +`main` run. + +A local run of that cell stopped after Phase 3. It staged no deployment. +The object-store integrity check read one composefs object with `EIO`. The +guest kernel logged `fs-verity ... FILE CORRUPTED!`. The object read back +intact afterwards. On the same kernel, outside the guest: + +| Store | Files read per pass | `FILE CORRUPTED` reports per pass (3 passes) | Failed reads | +|---|---|---|---| +| btrfs on LUKS (the cell's disk) | 87384 | 15, 12, 12 | 0 | +| btrfs, no LUKS | 6791 | 0, 1, 1 | 0 | +| ext4 `-O verity`, same files | 6418 | 0, 0, 0 | 0 | + +Most rejected 4 KiB blocks hash to all zeros. The kernel retries a failed +readahead, so reads usually succeed; the guest's one failed read shows that +they do not always succeed. A host with this kernel can pass the integrity +check and still read `EIO` from its composefs root later. + +The cause is in the kernel, not in this tool. Since 7.2, btrfs uses large data +folios. `btrfs_verify_folio()` verifies the whole folio when a read fills only +part of it. Every kernel from 7.2 on has it (7.3.x and 7.4-rc1 included). + +The fix is linux-next `dcf8811f63af`. +Fedora's `7.2.15-200.fc44` rebuilt with only that patch logged no reports. The +stock build logged 18 reports. Utah plans to ship that rebuild from its kernel +cache image. Do not convert a btrfs Utah host until the target's kernel +carries the fix. + ## Maintenance - This file follows `main` E2E runs, not PR runs. After a green `main` run, diff --git a/docs/bootc-migrate/testing.md b/docs/bootc-migrate/testing.md index e63bbd09..c617f715 100644 --- a/docs/bootc-migrate/testing.md +++ b/docs/bootc-migrate/testing.md @@ -14,7 +14,7 @@ automates validation. This text complements `ROADMAP.md` and | Unit | Pure logic: parsers, planners, mergetc tables, routing, digest handling, probe classification | `just test` / CI `validate`, every push | seconds | | Feature-matrix | Same, with every cargo feature on (`composefs-native` is invisible to the default build) | `just test-all-features` (part of `just check`) | seconds | | Integration (host) | Real repositories on loopback filesystems, real podman probes of real images — no VM | developer machines + scheduled canary | minutes | -| E2E (VM) | Full migrations in QEMU: partition → install → migrate → reboot → assert | e2e-tests.yml, called from ci.yml's `e2e` job: a round-robin slice of the gating cells per PR/push, the full matrix nightly | ~30 min/cell | +| E2E (VM) | Full migrations in QEMU: partition → install → migrate → reboot → assert | e2e-tests.yml, called from ci.yml's `e2e` job: a round-robin slice of the gating cells per PR/push, alternate cells each night (every cell every other night) | ~30 min/cell | Rules of thumb: @@ -44,9 +44,12 @@ Current (the four **MVP gates for regressions, which must stay**, plus the M1 ad | bluefin stable → bluefin gts (ostree-rebase mode) | OstreeDeploy strategy + rollback presence | PR #69/#70 | | bluefin stable → aurora (ostree-rebase mode) | cross-DE native `/etc` merge probe (#80) | active, non-gating | | bluefin stable → dakota (tui-migrate mode) | TUI wizard + Config Drift Review event loops on a pty (`tests/tui-e2e-driver.py`), then the full composefs pipeline + all default-mode assertions | active, gating | -| dakota stable (composefs-native) → fedora-bootc 44 (`composefs-to-ostree` mode) | the reverse backend switch (#260): `--plan` resolves `OstreeInstall`, the target's `bootc install to-existing-root` runs alongside, `/etc` + `/var` + `/var/home` fixtures survive, the reboot lands in the OSTree deployment, and the composefs "Linux Boot Manager" entry and ESP kernel remain as rollback. Then `bootc-rebase commit` (#315) runs as a dry run that deletes nothing, and with `--apply` it removes `/sysroot/state` and `/sysroot/composefs` but keeps the OSTree repo, the deployment and the forensics; a reboot follows, then the health check | active, non-gating | -| dakota stable (composefs-native) → utah testing (`composefs-to-ostree` mode) | the Dakota → Utah migration through `OstreeInstall` (#302): the same assertions as the fedora-bootc cell, plus the shim/GRUB entry first in `BootOrder`, the booted os-release `ID=hummingbird` and GDM running | active, non-gating | +| dakota stable (composefs-native) → fedora-bootc 44 (`composefs-to-ostree` mode) | the reverse backend switch (#260): `--plan` resolves `OstreeInstall`; a journal records the hash-verified ESP rollback and observed NVRAM state; the target is armed through `BootNext` while "Linux Boot Manager" stays first; `/etc` + `/var` + `/var/home` fixtures survive; a real new `boot_id` proves the reboot; `commit --apply` promotes GRUB, removes composefs state, and another new `boot_id` proves the persistent target boot | active, non-gating | +| dakota stable → fedora-bootc 44 (`composefs-to-ostree`, `E2E_BOOT_TXN_FAULT=after-esp-wipe`) | interruption after bootc wipes the ESP is classified `needs-repair`; restart restores both snapshot and ESP to journaled hashes, clears `BootNext`, observes rollback-first `BootOrder`, and a real reboot returns to composefs | active, non-gating | +| dakota stable → fedora-bootc 44 (`composefs-to-ostree`, `E2E_BOOT_TXN_FAULT=before-arm`) | interruption after durable preparation is classified `resumable`; restart re-observes both entries and ESP hashes, arms `BootNext`, and completes the ordinary route | active, non-gating | +| dakota stable (composefs-native) → utah testing (`composefs-to-ostree` mode) | the Dakota → Utah migration through `OstreeInstall` (#302): the same transaction assertions as the fedora-bootc cell, plus the booted os-release `ID=hummingbird` and GDM running | active, non-gating | | dakota stable (composefs-native) → utah testing (`image-swap` mode) | a composefs image swap across distributions: `--plan` resolves `ImageSwap`, the host's `bootc switch` stages Utah (Bluefin on Fedora Hummingbird), `/etc` + `/var` + `/var/home` fixtures survive, the reboot lands in Utah and the Dakota deployment stays as rollback | active, non-gating | +| utah testing (OSTree, `btrfs+crypt`) → utah testing | the full conversion with the same image: ESP + ext4 `/boot` + btrfs in a passphrase-unlocked LUKS2 root, the reboot lands in Utah booted from composefs through systemd-boot, and the composefs-migrate fixtures survive | active, non-gating | | tunaOS marlin gnome (composefs-native, Arch) → utah testing (`image-swap` mode, `E2E_CROSS_FAMILY=1`) | a cross-family image swap: the swap is refused without `--accept-cross-base`, then the host's `bootc switch` stages Utah, and the same fixture, reboot and rollback checks as the Dakota cell run | active, non-gating | | tunaOS marlin gnome (composefs-native, Arch) → utah testing (`composefs-to-ostree` mode) | the OstreeInstall route from a host with no `efibootmgr` and no SELinux: NVRAM through the target's `efibootmgr`, `/boot` labelled with Utah's policy, the apps Marlin preinstalled still installed after Utah's first-boot `flatpak preinstall`, and the commit dry run's `/var` check | active, non-gating | | bluefin stable → bootcrew/opensuse-bootc (`composefs-migrate`, `E2E_CROSS_FAMILY=1`) | cross-family gate and `/etc` policy: target defaults, sidecars, machine state and identity merge | active, non-gating | @@ -248,7 +251,8 @@ python3 tests/tui-e2e-driver.py --mode wizard-expect-failure \ ## KVM runner options The E2E matrix needs `/dev/kvm`. GitHub-hosted Linux runners provide KVM access. -`ubuntu-latest` is the default runner. +`ubuntu-24.04` is the default runner. +The workflows do not use `ubuntu-latest`. On `ubuntu-26.04`, the fixture for bluefin LTS fails. Both workflows set up podman storage. The runner image defaults to `Native Overlay Diff: "false"`, which causes slow layer builds. The step @@ -259,7 +263,7 @@ Runner precedence: 1. **`E2E_RUNSON_SPEC` set**: RunsOn EC2 runners with nested virtualization. 2. **`E2E_SELF_HOSTED=true`**: self-hosted runner with KVM. -3. **Default**: `ubuntu-latest`. +3. **Default**: `ubuntu-24.04`. Use `KVM_E2E_ENABLED='false'` to disable the E2E matrix. @@ -272,7 +276,7 @@ Keep these constraints: - Use `spot=false`, or `retry=when-interrupted`, because spot interruption is risky for a 30–90-minute cell. 1. **`E2E_SELF_HOSTED=true`** → the `kvm`-labelled self-hosted host (kanpur), the original setup. -2. **Neither** → `ubuntu-latest`. +2. **Neither** → `ubuntu-24.04`. Set `KVM_E2E_ENABLED='false'` to stop the matrix. The `required-checks` job treats a skipped `e2e` job as a pass. @@ -292,7 +296,8 @@ also need the existing `tui-migrate` cell. The path list is in PRs compare the merge base with the head. Pushes compare `before` with `after`. A failed diff stops the plan. Tests run with `just test-ci-selection`. -The nightly schedule and `workflow_dispatch` run every cell. +The nightly schedule runs alternate cells, so each cell runs every other night. +`workflow_dispatch` runs every cell. ### Timeouts, and why they are what they are diff --git a/docs/bootsahi/CONTRIBUTING.md b/docs/bootsahi/CONTRIBUTING.md index ce28e57d..57dc300d 100644 --- a/docs/bootsahi/CONTRIBUTING.md +++ b/docs/bootsahi/CONTRIBUTING.md @@ -3,7 +3,7 @@ sidebar_position: 2 title: "Contributing" --- -This repo (`tuna-os/bootc-installer-asahi`) is the Apple Silicon (Asahi Linux) +This repo (`tuna-os/bootsahi`) is the Apple Silicon (Asahi Linux) install path for TunaOS-family bootc images: a macOS app (Bootsahi) plus a bootstrap image whose first boot runs [fisherman](https://github.com/tuna-os/fisherman) to `bootc install` @@ -96,5 +96,5 @@ number in the PR description when one exists. ## Reporting issues -Use [GitHub Issues](https://github.com/tuna-os/bootc-installer-asahi/issues) +Use [GitHub Issues](https://github.com/tuna-os/bootsahi/issues) on this repository. diff --git a/docs/bootsahi/E2E-RUNNERS.md b/docs/bootsahi/E2E-RUNNERS.md index e9796e43..1ed57a40 100644 --- a/docs/bootsahi/E2E-RUNNERS.md +++ b/docs/bootsahi/E2E-RUNNERS.md @@ -72,7 +72,7 @@ shows which mode it used. Before the RunsOn path can work, a maintainer must do these steps: -1. Install the RunsOn app on `tuna-os/bootc-installer-asahi`. It +1. Install the RunsOn app on `tuna-os/bootsahi`. It has access to other tuna-os repositories now. 2. Make sure that the RunsOn stack can start Graviton `.metal` instances in its AWS region and account limits. diff --git a/docs/bootsahi/ROADMAP.md b/docs/bootsahi/ROADMAP.md index 44f33c58..54d34022 100644 --- a/docs/bootsahi/ROADMAP.md +++ b/docs/bootsahi/ROADMAP.md @@ -48,9 +48,11 @@ have durable evidence linked from the release notes: - [ ] Confirm the installer refuses unsupported Macs and unverified catalog entries before making disk changes. - [ ] Replace the hand-maintained catalog trust bit with CI-generated harness - evidence ([#70](https://github.com/tuna-os/bootc-installer-asahi/issues/70)), - and have the same job establish currency alongside provenance under the - catalog currency contract below. + evidence, and have the same job establish currency alongside provenance + under the catalog currency contract below. #70 closed when #104 added + only an interim guard: `scripts/validate-catalog.sh` checks each + `verified: true` entry against the hand-written + `docs/harness-results.json`. CI generation is still to do. - [ ] State that Alpha ships GNOME only, so single-desktop coverage is a recorded scope decision rather than an unexamined default. - [ ] Publish a signed and notarized DMG, checksums, supported-host statement, diff --git a/docs/bootsahi/index.md b/docs/bootsahi/index.md index bebc9747..4037fd5f 100644 --- a/docs/bootsahi/index.md +++ b/docs/bootsahi/index.md @@ -8,7 +8,7 @@ status: unknown Bootsahi is the Apple Silicon (Asahi Linux) installer path for TunaOS-family bootc images — and anyone else's (Dakota, Bluefin, Bazzite). It is a macOS-driven install flow for M1/M2 Macs. The repository is -`tuna-os/bootc-installer-asahi`. +`tuna-os/bootsahi`.

Advisories -> New draft security advisory**). Name `tuna-os/ccleft` -as the affected repository and include the affected component, a minimal -reproduction, the impact, and a suggested fix if you have one. +Report privately with GitHub private vulnerability reporting on this +repository: open a +[new draft security advisory](https://github.com/tuna-os/ccleft/security/advisories/new) +(**Security -> Report a vulnerability**). Include the affected component, a +minimal reproduction, the impact, and a suggested fix if you have one. Never include real credentials, tokens, or account identifiers in a report. Redact captures first. diff --git a/docs/compass/crates.md b/docs/compass/crates.md index 7827791e..395048f3 100644 --- a/docs/compass/crates.md +++ b/docs/compass/crates.md @@ -21,7 +21,7 @@ has the full rules. | Crate | What it is | |---|---| -| `compass` | The `compass` command: the CLI, the engine (`compass serve`, the IPC server and the services it runs), and the wiring of every other crate. Linux-bound. | +| `compass` | The `compass` command: the CLI, the engine (`compass serve`, the IPC server and the services it runs), on-demand startup from `toggle`/`show`/`query`, and the wiring of every other crate. Linux-bound. | | `compass-ui` | The Iced launcher window: every view, the settings, the onboarding flow. | ## Application logic diff --git a/docs/compass/getting-started.md b/docs/compass/getting-started.md index 7f4fa114..e0b73cd7 100644 --- a/docs/compass/getting-started.md +++ b/docs/compass/getting-started.md @@ -33,18 +33,22 @@ The examples on this page use the `compass` command. From the Flatpak, run it as ## Start Compass when you log in -Opening Compass from the application grid starts it for the rest of the session. To start it at -every login, turn on **Start at login**, in the first-run setup's "Make it your own" step or in -Settings, General. It is off until you turn it on. Compass asks your desktop's Background portal, -which shows you what it allows, to run `compass start --hidden` when you log in. Where there is no +You do not need a service or a login-start entry to use Compass. Pressing the launcher shortcut +starts the engine and window on demand, and they keep running for the rest of the session. + +Opening Compass from the application grid also starts it for the rest of the session. To have it +waiting from the moment you log in, turn on **Start at login**, in the first-run setup's "Make it +your own" step or in Settings, General. It is off until you turn it on. Compass asks your desktop's +Background portal, which shows you what it allows, to run `compass start --hidden` when you log in. Where there is no Background portal (some wlroots sessions) and Compass is not in the Flatpak, it writes `~/.config/autostart/compass.desktop` itself, and turning the switch off removes only that file. If your desktop declines, the switch stays off and says so. From a terminal, `compass login-start status` shows the same state, and `compass login-start enable` and `compass login-start disable` change it as the switch does. -Packages also install a systemd user unit, which Compass never turns on or off. Settings says when -it is installed and whether it is enabled. To use the unit instead of the switch: +Packages may also install a systemd user unit as an optional fallback. Compass never turns it on +or off, and nothing needs it for the launcher to work; Settings only reports when it is installed +and whether it is enabled. To use the unit as well: ```sh systemctl --user enable --now compass @@ -77,9 +81,10 @@ compositor's autostart instead, for example `exec compass start --hidden` in Swa ## Set a keyboard shortcut -The launcher opens with `compass toggle`, which shows it or hides it. Compass has to be running -for this to work: open it once from the application grid, or run `compass start --hidden` when you -log in. +The launcher opens with `compass toggle`, which shows it or hides it. If Compass is not running, +this command starts it for you, so the shortcut works from the first press without a service or a +login-start entry. `compass query` likewise starts the engine it needs; headless, it starts only +the engine and no window. Compass asks for Super+Space by default. To change it, run **Open Settings** and set **Launcher hotkey** under General, or set `launcher.hotkey` in the configuration file. diff --git a/docs/corral/ci-boot-gate.md b/docs/corral/ci-boot-gate.md index e1f27837..36286e00 100644 --- a/docs/corral/ci-boot-gate.md +++ b/docs/corral/ci-boot-gate.md @@ -310,13 +310,31 @@ export CORRAL_VMTEST_HEADLESS_ID=fedora CORRAL_VMTEST_HEADLESS_VERSION=41 export CORRAL_VMTEST_DESKTOP_IMAGE=your-desktop-bootc-image export CORRAL_VMTEST_DESKTOP_ID=your-os-id export CORRAL_VMTEST_DESKTOP_COMMAND=gnome-shell CORRAL_VMTEST_DESKTOP_UNIT=gdm.service -sudo -E go test -tags e2evmtest -timeout 90m -count=1 -v ./pkg/vmtest/ -run 'TestE2E_GuestAssertion' +export CORRAL_REQUIRE_TOOLS=bootc-local-build,kvm,guest-images +export CORRAL_VMTEST_ARTIFACTS="$PWD/vmtest-guest-out" +sudo -E "$(command -v go)" test -tags e2evmtest -timeout 90m -count=1 -v ./pkg/vmtest/ -run 'TestE2E_GuestAssertion' ``` This also boots the headless image with a deliberately incorrect identity and asserts an `ExitCheck` failure with check output, serial log and result file. -A test skips a case when you do not configure its image or when the host does not -have a VM prerequisite. Read the test output: a skipped case is not boot evidence. +The desktop case uses a 32 GiB disk and builds the existing test layer to enable +SSH. Its desktop configuration does not change. When a case passes, it also +checks for nonempty serial and result evidence. `CORRAL_VMTEST_ARTIFACTS` preserves each case's artifacts under +its VM name; without it, Go removes them with its temporary test directories. + +`CORRAL_REQUIRE_TOOLS` makes missing images/identities (`guest-images`), local +build tools or KVM fail these acceptance cases. Without this setting, missing +prerequisites skip the case for local development. A skipped case is not boot +evidence. + +The existing **VM test harness** Actions workflow exposes the same cases on +manual dispatch. To use them, enable `guest_assertions` and configure `image`, +`headless_id` and `headless_version`. Then supply `desktop_image`, `desktop_id`, +and the desktop command/unit (plus an optional desktop version). The workflow runs all three +cases with required prerequisites and uploads `vmtest-guest-out/` alongside its +usual evidence, even on failure. Guest acceptance is opt-in; scheduled and PR +runs keep their existing scope. A successful job for the container layer does not +satisfy guest acceptance. ### GitHub Actions diff --git a/docs/dualcut/CONTRIBUTING.md b/docs/dualcut/CONTRIBUTING.md index 6a85199f..dcafd9cb 100644 --- a/docs/dualcut/CONTRIBUTING.md +++ b/docs/dualcut/CONTRIBUTING.md @@ -46,7 +46,8 @@ Read these — they are short and will save you (and reviewers) time: | Path | What lives here | |---|---| -| `engine/` | The Rust engine: document model (`engine/src/document.rs`), rendering (GStreamer Editing Services), the HTTP server, the GTK4/libadwaita UI | +| `engine/` | The Rust engine: document model (`engine/src/document/mod.rs`), rendering (GStreamer Editing Services), the HTTP server, the GTK4/libadwaita UI | +| `engine/src/document/` | Document schema and timeline boundaries: `model.rs`, `validation.rs`, `ops.rs`, `rate_ramp.rs`, and `traversal.rs` | | `engine/schema/` | The canonical document schema: `dualcut.d.ts` (TS types) + `dualcut.schema.json` (JSON Schema) | | `skills/dualcut/references/` | Bundled copies of the schema used by the agent skill — **must stay byte-identical** to `engine/schema/` (CI enforces this) | | `docs/` | `USER_GUIDE.md` (user documentation), `guide/` (screenshots), `recipes/`, `adr/` | @@ -251,13 +252,16 @@ next section before you submit changes. GPU backend that works (or a compatible software driver). For smoke tests of the Linux UI, use the CI Xvfb recipe. Do not force a Wayland session. +More symptoms and fixes are in [docs/TROUBLESHOOTING.md](https://github.com/tuna-os/dualcut/blob/main/docs/TROUBLESHOOTING.md). + ## Making a change 1. **Branch from `main`** — use a descriptive name, e.g. `git checkout -b fix/crossfade-offset` or `feat/export-webm`. 2. **Keep commits focused** and sign them with DCO: `git commit -s` (your commit must carry a `Signed-off-by` trailer). -3. **Run the checks CI will run** before pushing: +3. **Run the checks CI will run** before pushing. [docs/TESTING.md](https://github.com/tuna-os/dualcut/blob/main/docs/TESTING.md) + describes each layer and how CI runs it: ```sh # 1. Schema copies must be byte-identical to the agent skill bundle diff --git a/docs/dualcut/TESTING.md b/docs/dualcut/TESTING.md new file mode 100644 index 00000000..93305e5b --- /dev/null +++ b/docs/dualcut/TESTING.md @@ -0,0 +1,85 @@ +--- +sidebar_position: 4 +title: "TESTING" +--- + +This page lists the test layers in dualcut, the commands that run each one, +and how the `test` job in CI runs them. The CI workflow +([`.github/workflows/ci.yml`](https://github.com/tuna-os/dualcut/blob/main/.github/workflows/ci.yml)) is the +authoritative reference. If this page and that file differ, follow the file. + +## Test layers + +| Layer | Where it lives | Command | +|---|---|---| +| Schema sync | `engine/schema/` and `skills/dualcut/references/` | `diff engine/schema/dualcut.d.ts skills/dualcut/references/dualcut.d.ts` (and the same for `dualcut.schema.json`) | +| Lint | Whole engine crate | `cd engine && cargo clippy --all-features -- -D warnings` | +| Unit tests | `#[cfg(test)]` modules in `engine/src/` | `cd engine && cargo test --all-features` | +| Release render build | `engine/` | `cd engine && cargo build --release --features vector` | +| Render smoke suite | `tests/smoke.sh` | `tests/smoke.sh engine/target/release/render` | +| App start smoke | `engine/src/bin/preview/` | Xvfb run of `preview` with `DUALCUT_WALKTHROUGH=1` (see CI) | + +Run commands from the repository root unless a line says otherwise. + +## Unit tests + +Unit tests sit next to the code they test, in `#[cfg(test)]` modules. The +document model is in `engine/src/document/`, and the HTTP API tests are in +`engine/src/api.rs`. To add a unit test, add a `#[test]` function to the +module that owns the code. Run one module with a name filter: + +```sh +cd engine && cargo test --all-features document +``` + +## Render smoke suite + +`tests/smoke.sh` renders real projects with the release `render` binary and +checks the output with GStreamer and Pillow. It needs `gst-discoverer-1.0`, +`gst-launch-1.0`, and `python3` with Pillow. It checks: + +- the built-in demo renders and has a video stream; +- a volume fade attenuates audio over time; +- chroma key removes the keyed green; +- a freeform mask shows the background outside the shape, and `invert` + flips which side is visible; +- each export profile (`webm`, `vp9`, `ogg`, `flac`, `wav`, `mkv`, `m4a`) + writes a non-empty file; +- a round-tripped project still renders. + +The script prints `ok` or `FAIL` per check and exits non-zero on any failure. + +To add a case, copy one of the existing blocks. Write a project JSON into +`$WORK`, render it with `"$BIN"`, then assert on the output. Keep the +assertion loose enough to survive encoder changes. + +## Application start smoke + +CI builds `preview` with `--features preview,scripting,vector` and starts it +under Xvfb with `DUALCUT_WALKTHROUGH=1`. The job passes only when the log +contains `WALKTHROUGH-SHOT about`. This check needs a display, so run it in +CI or on a desktop session. CI starts Xvfb for it. + +## Which CI steps block a PR + +The `test` job in `ci.yml` runs the steps in the table above, in order. A +failing step fails the job. The schema sync check, clippy, unit tests, the +render smoke suite, and the app start smoke all count. Branch protection rules +are set in repository settings, not in this tree. + +The nightly `coverage` workflow runs on a schedule, not on PRs. + +## Coverage + +[`codecov.yml`](https://github.com/tuna-os/dualcut/blob/main/codecov.yml) sets the project target to 45%, with a 2% +threshold. The patch target is 70%, and it is informational only. + +## Debugging a CI failure locally + +1. Find the failing step in the `test` job log. +2. Run the same command from the table above in a Fedora 45 environment. + [CONTRIBUTING.md](https://github.com/tuna-os/dualcut/blob/main/CONTRIBUTING.md) has a Podman command for one. +3. For the render smoke suite, pass the same binary path that CI uses. Build + it first with `cargo build --release --features vector`. + +This repository does not document a flaky-test policy. diff --git a/docs/dualcut/TROUBLESHOOTING.md b/docs/dualcut/TROUBLESHOOTING.md new file mode 100644 index 00000000..e4b2d5df --- /dev/null +++ b/docs/dualcut/TROUBLESHOOTING.md @@ -0,0 +1,120 @@ +--- +sidebar_position: 5 +title: "TROUBLESHOOTING" +--- + +Common problems, with the commands to diagnose them. For build and install +errors, see the Troubleshooting section in +[CONTRIBUTING.md](https://github.com/tuna-os/dualcut/blob/main/CONTRIBUTING.md#troubleshooting). + +## Export and GStreamer + +**Export fails with "Couldn't create encoder for format audio/mpeg".** +The AAC encoder is missing. MP4 and M4A export need `avenc_aac`. + +```sh +gst-inspect-1.0 avenc_aac +gst-inspect-1.0 x264enc +``` + +If either is missing, install the GStreamer libav and ugly plugin sets for +your distribution. Then run `gst-inspect-1.0` again. + +**Export or preview fails on a codec or discovery error.** Raise the +GStreamer log level for that one command: + +```sh +GST_DEBUG=2 cargo run --bin render -- project.json out.mp4 +``` + +Check for stale `GST_PLUGIN_PATH` or `GST_PLUGIN_SYSTEM_PATH` values that +point at another installation. `pkg-config` success does not prove that the +runtime plugins are present. + +**Preview shows black video, no position, or a play button that does +nothing.** Look for `Failed to link sink element` in the terminal output. +That message comes from a sink-setup problem in the app, not from your +project. Report it with your GStreamer version. Include the output of +`gst-inspect-1.0 --version`. + +**Export rejects the output name.** The profile comes from the file extension +or the profile name. Supported names include `mp4` (or `h264`), `webm` (or +`vp8`), `vp9`, `av1`, `h265`, `prores` (or `mov`), `ffv1` (or `mkv`), `m4a`, +`ogg`, `flac`, `mp3`, and `wav`. Any other name is an error. + +**Captions fail with "No whisper model found".** Set `DUALCUT_WHISPER_MODEL` +to the path of a ggml Whisper model file, then start the app again. + +## HTTP API + +The API listens on `127.0.0.1:7357` by default. Check that it responds: + +```sh +curl -s http://127.0.0.1:7357/status +``` + +**"agent API not available: binding 127.0.0.1:7357" in the terminal.** Another +process uses the port. Choose a different port with `DUALCUT_API_PORT`, or set +it to `0` to turn the API off: + +```sh +DUALCUT_API_PORT=7358 preview project.json +``` + +For `serve`, pass the port as the second argument: +`cargo run --bin serve -- project.json 7358`. + +**Connection refused.** The app or `serve` is not running, or it uses another +port. Check the port you set, then run the `curl` command above again. + +**403 Forbidden.** The request has an `Origin` header, or its `Host` is not +`localhost` or an IP address. Browser pages cannot use the API. Use `curl` or +a script instead. + +**400 with an error message.** The body was rejected and the project file was +not changed. Read the `error` field. For `/op`, check the op name and its +required fields. For `/project`, check the document against +[`engine/schema/dualcut.schema.json`](https://github.com/tuna-os/dualcut/blob/main/engine/schema/dualcut.schema.json). + +**501 on `/script`.** The `serve` binary was built without the `scripting` +feature. Rebuild it with `--features scripting`. + +## Project files + +**The project does not open, or the app reports validation errors.** Check the +JSON syntax first, then the fields listed in the schema. Ids must be unique, +and scenes must have `duration > 0`. + +```sh +curl -s http://127.0.0.1:7357/project +``` + +A `500` from `GET /project` means the file cannot be read or parsed. + +## Performance and display + +**`preview` will not start.** It needs a graphical session and libadwaita 1.8 +or newer. Check the version: + +```sh +pkg-config --atleast-version=1.8 libadwaita-1 && echo ok +``` + +`render` and `serve` run without a desktop session. Use them to check +whether a problem is in the UI or in the engine. + +**Preview is slow with a large project.** No tuning guide exists for this in +the repository yet. Test with a smaller project to narrow the cause, and +include the project size and GPU details in a bug report. + +## When to file a bug + +Check this page and the setup steps in CONTRIBUTING first. File a bug if the +problem reproduces with a fresh checkout and a supported toolchain. Include: + +- the command you ran and its full output; +- `gst-inspect-1.0 --version` and `rustc -vV`; +- the project file, or a minimal project that shows the problem. + +A missing package or a wrong path is a configuration issue. Fix it locally +and do not file a bug. diff --git a/docs/dualcut/USER_GUIDE.md b/docs/dualcut/USER_GUIDE.md index d56bc8c7..9b81470e 100644 --- a/docs/dualcut/USER_GUIDE.md +++ b/docs/dualcut/USER_GUIDE.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 6 title: "USER GUIDE" --- diff --git a/docs/dualcut/index.md b/docs/dualcut/index.md index 7d7647b4..5ca4ea60 100644 --- a/docs/dualcut/index.md +++ b/docs/dualcut/index.md @@ -16,7 +16,7 @@ HTTP API for agents) — every surface stays in sync while the app runs. ![dualcut editor](https://raw.githubusercontent.com/tuna-os/dualcut/main/docs/screenshot.png) -**[📘 User Guide](https://github.com/tuna-os/dualcut/blob/main/docs/USER_GUIDE.md)** — screenshots captured from the real app. +**[📘 User Guide](https://github.com/tuna-os/dualcut/blob/main/docs/USER_GUIDE.md)** — screenshots captured from the real app. Problems? See [Troubleshooting](https://github.com/tuna-os/dualcut/blob/main/docs/TROUBLESHOOTING.md). **Install (Flatpak, via the TunaOS remote):** diff --git a/docs/dualcut/observability.md b/docs/dualcut/observability.md index 285d81bb..acafe4e6 100644 --- a/docs/dualcut/observability.md +++ b/docs/dualcut/observability.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 7 title: "observability" --- @@ -65,6 +65,7 @@ Common `GST_DEBUG` levels: 0=none, 1=error, 2=warning, 3=fixme, 4=info, 5=debug, ### HTTP Agent API Diagnostics While the API server runs (default port 7357): + - Access logs and errors print to standard error - Health check endpoint: `GET /status` verifies server responsiveness - Project API: `GET /project` validates document structure @@ -96,6 +97,7 @@ gst-inspect-1.0 | grep -E 'h264|vp8|aac|vorbis' ### Proxy Media Cache Proxy media is cached in `.dualcut-cache/` within the project directory: + - Safe to delete; will be regenerated on next preview - Reduces timeline scrubbing latency for large videos - Disable with *Preferences → Use proxy media* diff --git a/docs/flatpak-index/APP-LIFECYCLE.md b/docs/flatpak-index/APP-LIFECYCLE.md index 393868ea..bd3b1d2b 100644 --- a/docs/flatpak-index/APP-LIFECYCLE.md +++ b/docs/flatpak-index/APP-LIFECYCLE.md @@ -96,6 +96,56 @@ Retirement therefore needs a coordinated, reviewed production change. 4. Run the served-index audit and verify the retired app is absent from the served index. Keep the retirement decision and date in the change record. +## Respond to a bad publication + +A publication is bad when the served remote no longer matches the registry or +the documented catalog. Find it three ways: a drift check fails, +`enrich-index.py --check` reports missing or wrong metadata, or a user reports +`Nothing matches` for an app the remote should serve. Roll back to the last +known-good served index. + +The `tunaos-org` Cloudflare Worker serves the production remote from `tuna-os/docs`, so a +rollback is a change to that repository, not this one. This checkout holds no +local `index/static`, so the recovery source is the prior commit to +`tuna-os/docs/static/flatpak/index/static`. + +1. Confirm the publication is bad against the registry, not only against the + docs: + + ```sh + curl -sSfL -o served-index.json \ + https://tunaos.org/flatpak/index/static + ./scripts/enrich-index.py served-index.json --check + ``` + + A `--check` result that prints "missing labels present in the registry" + shows the registry has labels the served index lacks. That is a bad + index. Roll back the served index. + + A result that prints "could not read labels" or "image has no AppStream + metadata" is a registry fault. A rollback changes only the served index, so + it cannot fix data in the registry. A result that flags only documentation + is a drift check, not a rollback. + +2. Find the last good publication as the prior commit to + `tuna-os/docs/static/flatpak/index/static`. + +3. Restore it in `tuna-os/docs` — revert the bad commit, or re-publish the + previous good index. The Worker re-serves the static asset on push. Keep + `FLATPAK_INDEX_TOKEN` scoped to `tuna-os/docs`; never put its value in a + command, commit, or this document. + +4. Re-verify from the served URL (step 1) and confirm the catalog, digest, + architecture, and AppStream labels now match the registry. + +5. Record the incident in the change record: the bad commit SHA, what you + restored, the date, and the owner. + +The incident owner is the production-source owner named by the governance +decision in ROADMAP.md. Until then, any `tuna-os/docs` maintainer with +`FLATPAK_INDEX_TOKEN` may do the rollback. Run this procedure as a live +exercise at least once. A rollback nobody has exercised is not one. + ## Checks From this repository, run the test suite, which uses the standard library, diff --git a/docs/flatpak-index/index.md b/docs/flatpak-index/index.md index 0db5092d..4d893bcc 100644 --- a/docs/flatpak-index/index.md +++ b/docs/flatpak-index/index.md @@ -309,6 +309,50 @@ as a bare application ID with an "Unknown" licence and no screenshots. describes the proposed gate and its current limits. The production publisher does not enforce it yet. +## Publish, validate, enrich + +Every entry in the index runs through the same three stages, across two scripts +that share one job and are deliberately separate: + +``` +flatpak build-bundle --oci + │ + ▼ +update-index.py publish: writes the entry, keeps org.flatpak.* + appstream labels + │ + ▼ +tuna-os/docs ──► tunaos.org/flatpak served by the Cloudflare Worker + │ + ▼ +enrich-index.py --check audit: re-reads each image's labels from the registry, flags gaps +``` + +- **Publish** — `scripts/update-index.py` reads the `flatpak build-bundle --oci` + image and writes one entry into the index. It keeps the `org.flatpak.*` labels, + which Flatpak needs to resolve and install the ref. It also keeps the + `org.freedesktop.appstream.*` labels, which Bazaar, GNOME Software and Discover + render as the app page. Without AppStream metadata an app shows as a bare ID + with an "Unknown" licence and no screenshots. Run it with `--require-appstream` + to fail instead of warn when the image has no metainfo. Then an incomplete build + never reaches the index in the first place. +- **Serve** — the `tunaos-org` Cloudflare Worker publishes the index at + `tunaos.org/flatpak/`. It serves the copy in `tuna-os/docs`. This repo keeps + no copy of the index. +- **Validate** — `scripts/enrich-index.py --check` re-reads every published + image's labels from the registry and reports any that are missing or incomplete. + It runs daily against the live remote + ([`check-metadata.yml`](https://github.com/tuna-os/flatpak-index/blob/main/.github/workflows/check-metadata.yml)). A failure there + can also mean a deploy has not propagated, so read it as a monitor result. + +The two scripts apply the *same* label rule, but each script has its own copy. +`update-index.py` must stay a single vendored file and cannot import `oci.py`, so +the rule lives in both. [`tests/test_label_policy.py`](https://github.com/tuna-os/flatpak-index/blob/main/tests/test_label_policy.py) +pins the two copies to each other. [`tests/test_publish_enrich_contract.py`](https://github.com/tuna-os/flatpak-index/blob/main/tests/test_publish_enrich_contract.py) +runs a published entry through the auditor end to end. A divergence between the +two copies fails in CI, but an incomplete entry does not. `update-index.py` omits +the entry only with `--require-appstream`, and the enrich auditor repairs it +when the registry has the metadata and reports it as a problem otherwise. + ## Architecture ``` diff --git a/docs/gnome-hive-monitor/CONTRIBUTING.md b/docs/gnome-hive-monitor/CONTRIBUTING.md index 6fb46eb0..4f434e0b 100644 --- a/docs/gnome-hive-monitor/CONTRIBUTING.md +++ b/docs/gnome-hive-monitor/CONTRIBUTING.md @@ -81,7 +81,7 @@ Use Node.js 24 and Python 3. You do not need npm packages: ```bash python3 -m unittest discover -s tests -v -node --test tests/test_widget.cjs +node --experimental-vm-modules --test tests/test_widget.cjs node --experimental-vm-modules --test tests/behavior.cjs ``` @@ -117,7 +117,8 @@ Verify that `gnome-extensions pack` can pack the extension: ```bash gnome-extensions pack --force --extra-source=schemas/ \ - --extra-source=hiveClient.js --extra-source=githubClient.js + --extra-source=hiveClient.js --extra-source=githubClient.js \ + --extra-source=ideaValidation.js ``` ## Pull Request Guidelines diff --git a/docs/hive-operator/CONTRIBUTING.md b/docs/hive-operator/CONTRIBUTING.md new file mode 100644 index 00000000..169c0dca --- /dev/null +++ b/docs/hive-operator/CONTRIBUTING.md @@ -0,0 +1,166 @@ +--- +sidebar_position: 2 +title: "Contributing" +--- + +hive-operator is a Go Kubernetes operator. It reconciles Hive custom resources, publishes metrics, and moves selected Hive operations from shell CronJobs into controllers. Read [README.md](https://github.com/tuna-os/hive-operator/blob/main/README.md) for current controller status and [DESIGN.md](https://github.com/tuna-os/hive-operator/blob/main/DESIGN.md) before changing reconciliation or shadow-diff behaviour. + +## Prerequisites + +Install or provide these before running commands: + +- Git. +- Go 1.27.2 or newer. The module declares Go 1.26.0; CI and both container build files use Go 1.27.2/1.27. +- GNU Make for the repository targets in `Makefile`. +- `kubectl` and a kubeconfig for `make deploy`, `make run`, sample resources, and shadow-diff checks. Unit tests and local builds do not need a cluster. +- Docker for `make docker-build` and `make docker-build-usage`. +- Network access to download Go modules. Manifest generation runs `controller-gen` through `go run`; no global controller-tools install is required. + +Confirm the Go toolchain before starting: + +```sh +go version +``` + +Do not point sample or promotion commands at a production cluster. The sample resources include `Enforce` modes and are intended for a disposable or explicitly authorized Hive environment. + +## Checkout and repository layout + +```sh +git clone https://github.com/tuna-os/hive-operator.git +cd hive-operator +``` + +Important paths: + +- `api/v1alpha1/` — custom-resource types and generated deepcopy code. +- `internal/controller/` — reconcilers and Kubernetes integration. +- `internal/rotation/`, `internal/liveness/`, and `internal/usage/` — controller policy and usage logic. +- `cmd/` — manager, shadow-diff, and usage-sidecar entry points. +- `config/crd/`, `config/rbac/`, and `config/manager/` — generated and deployment manifests. +- `config/samples/` and `config/usage/` — example resources. +- `docs/` — promotion and operational runbooks. + +## Build, format, generate, and test + +The Makefile keeps generated artifacts reproducible and invokes `controller-gen` through a pinned `go run` version. + +```sh +make generate # update api/v1alpha1 generated deepcopy code +make manifests # update config/crd and config/rbac +make fmt # format Go sources +make vet # run go vet ./... +make test # run go test ./... -count=1 +make build # fmt, vet, and build bin/manager +make all # generate, manifests, and build +``` + +Run `make generate` and `make manifests` after API or RBAC changes. Review generated diffs with the source change; do not hand-edit generated files. `make build` writes `bin/manager`, which is ignored by Git. + +For a focused package test, use the Go tool directly, for example: + +```sh +go test ./internal/rotation -count=1 +``` + +The image workflow runs `go build ./...`, `go vet ./...`, and `go test ./... -count=1` before publishing images for `main` and version tags. + +## Run locally against Kubernetes + +`make deploy` generates manifests and applies CRDs, RBAC, and the manager Deployment in `hive-system`: + +```sh +make deploy +kubectl -n hive-system get deployment hive-operator +``` + +To run the manager from the checkout instead of the Deployment, use a dedicated cluster and do not run both managers against the same resources: + +```sh +make run +``` + +`make run` disables leader election and binds the local dashboard to port `8082`. Stop it with Ctrl+C. Remove the installed resources when finished: + +```sh +make undeploy +``` + +The local process needs the Kubernetes permissions installed by `make deploy` and access to any Hive API endpoints referenced by the resources it reconciles. `make deploy` does not apply sample resources. + +## Apply sample resources + +Review each manifest and cluster context first. Apply only to an authorized test environment: + +```sh +kubectl apply -f config/samples/fleet.yaml +kubectl apply -f config/samples/release.yaml +kubectl apply -f config/samples/housekeeping.yaml +kubectl apply -f config/usage/usagepools.yaml +``` + +The samples intentionally exercise different controllers: + +- `fleet.yaml` creates `SharedAuth`, `HiveSpoke`, and `ModelLadder` resources. +- `release.yaml` creates a `HiveRelease` rollout plan. +- `housekeeping.yaml` creates `HiveHousekeeping` desired state for the remaining hive-ops CronJobs. +- `usagepools.yaml` creates provider-account usage pools; the `hive-usage` sidecar is optional. + +Promotion is not a routine development step. Read [docs/rotation-promotion.md](https://github.com/tuna-os/hive-operator/blob/main/docs/rotation-promotion.md), [docs/liveness-promotion.md](https://github.com/tuna-os/hive-operator/blob/main/docs/liveness-promotion.md), [docs/release.md](https://github.com/tuna-os/hive-operator/blob/main/docs/release.md), and [docs/housekeeping.md](https://github.com/tuna-os/hive-operator/blob/main/docs/housekeeping.md) before changing any resource from `Shadow` to `Enforce` or retiring a CronJob. + +## Shadow-diff development + +Shadow-diff compares controller output with captured or live shell-job output. It is read-only, but live mode still requires authorized cluster access. + +Against a live cluster: + +```sh +go run ./cmd/hive-shadow-diff --live +``` + +Against captured inputs: + +```sh +go run ./cmd/hive-shadow-diff --bash bash.log --spoke spoke.json +``` + +For liveness comparisons, use the corresponding flags documented in [docs/liveness-promotion.md](https://github.com/tuna-os/hive-operator/blob/main/docs/liveness-promotion.md). Classify every difference using the categories in [DESIGN.md](https://github.com/tuna-os/hive-operator/blob/main/DESIGN.md) before changing logic: snapshot skew, ladder data, journal state, or an actual parity defect. + +## Container images and usage sidecar + +The default image names are defined in `Makefile`: + +```sh +make docker-build +make docker-build-usage +``` + +Override tags without editing files: + +```sh +make docker-build IMG=ghcr.io/tuna-os/hive-operator:dev +make docker-build-usage USAGE_IMG=ghcr.io/tuna-os/hive-operator/hive-usage:dev +``` + +The sidecar image pins the Linux x64 `@ccusage/ccusage-linux-x64` package in `Dockerfile.usage`. Keep its version and npm integrity value aligned when updating it. To inspect copied logs without changing a Hive pod, run the sidecar once against a local copy: + +```sh +go run ./cmd/hive-usage --once --home /path/to/copy/of/data/home --ccusage "$(which ccusage)" --state "" +``` + +Replace `/path/to/copy/of/data/home` with a read-only copy and provide a compatible `ccusage` binary. Do not point this command at a live shared store unless the access and impact are explicitly authorized. + +## Pull requests + +1. Keep changes focused. Update generated CRDs, RBAC, or deepcopy output when their source changes. +2. Add or update tests for controller transitions, policy boundaries, and parity rules. Preserve golden fixtures when they document live shell output. +3. Run the relevant `make` targets locally and inspect `git diff` before committing. +4. Sign commits with the Developer Certificate of Origin: + + ```sh + git commit -s -m "docs: describe the change" + ``` + +5. Open a pull request against `main` with a summary, verification commands, cluster-impact notes, and any required rollout or rollback procedure. Never include credentials, kubeconfigs, API keys, or copied production state. + +Changes that alter promotion order, controller authority, image rollout, credentials, or production manifests need explicit maintainer review. Keep operational decisions in the relevant `docs/` runbook and update the README or sample comments when behaviour changes. diff --git a/docs/hive-operator/housekeeping.md b/docs/hive-operator/housekeeping.md index c287cbd4..0f9a5092 100644 --- a/docs/hive-operator/housekeeping.md +++ b/docs/hive-operator/housekeeping.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 title: "housekeeping" --- diff --git a/docs/hive-operator/liveness-promotion.md b/docs/hive-operator/liveness-promotion.md index 8c76dbd6..e04b1637 100644 --- a/docs/hive-operator/liveness-promotion.md +++ b/docs/hive-operator/liveness-promotion.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 title: "liveness promotion" --- @@ -21,7 +21,7 @@ the nudge backstop (`hive-nudge.sh nudge`: the `hive-nudge` CronJob, :13 and - `.watchdogPlan` — the actions (`restart`, `rotate-off`, `repair`, `effort`, `hygiene`, `wake`, `needs-human`) with reasons; - `.nudgePlanText` / `.nudgePlan` — this spoke's share of the nudge output - (check-mode suffix ` — would nudge`), capped at 4 as an apply would be; + (check-mode suffix `— would nudge`), capped at 4 as an apply would be; - `.journal` — heal backoff per agent, stall clocks, pending provider resets, last hygiene. Kept **as if every action succeeded**, so the backoff ladder is warm and comparable with bash's at promotion. diff --git a/docs/hive-operator/release.md b/docs/hive-operator/release.md index 9c401dea..b81beb6a 100644 --- a/docs/hive-operator/release.md +++ b/docs/hive-operator/release.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 title: "release" --- diff --git a/docs/hive-operator/rotation-promotion.md b/docs/hive-operator/rotation-promotion.md index 217854c2..a4d04078 100644 --- a/docs/hive-operator/rotation-promotion.md +++ b/docs/hive-operator/rotation-promotion.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 6 title: "rotation promotion" --- diff --git a/docs/hive-operator/upstream-ccusage.md b/docs/hive-operator/upstream-ccusage.md index 448e9160..ff3291fc 100644 --- a/docs/hive-operator/upstream-ccusage.md +++ b/docs/hive-operator/upstream-ccusage.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 7 title: "upstream ccusage" --- @@ -45,17 +45,21 @@ Suggested filing order: 1 and 2 are small and unblock us the most. 3 is the one In `ccusage-adapter-common` (`collect_usage_files`, `common/src/lib.rs:24-30`), the walker uses `DirEntry::file_type()`, which does not follow symlinks. As a result, a session file or project directory that is a symlink is never read. Only the root passed in through an env var is resolved. Why it matters: + - Multi-user and containerised setups rely on symlinks. Our hive runs each agent with `HOME=/data/home/agents/`, where `.claude`, `.codex` and `.gemini` are symlinks to a shared store. - A filtered view (for example, symlinking only recently modified files to speed up a scan) reads as empty. Reproduction on v20.0.24: + ``` mkdir -p v/claude/projects/x && ln -s ~/.claude/projects/

/.jsonl v/claude/projects/x/ CLAUDE_CONFIG_DIR=$PWD/v/claude ccusage claude session --json # → 0 sessions ``` + The same thing happens with `ANTIGRAVITY_DATA_DIR` pointing at a directory of symlinked `.db` files: 0 sessions in 0.16 s, against 34 sessions from the same files copied. Proposal: + - Use `fs::metadata` (which follows links) for entries that are symlinks. - Guard against cycles with a visited set of (dev, ino). @@ -70,6 +74,7 @@ I'm happy to implement this. Watch out when extracting it: the path sits inside protobuf blobs, so a naive regex picks up neighbouring length/tag bytes (`guid`, `guidej` next to 131× `guide`). It needs to come from the decoded trajectory metadata field, not a string search. **Performance.** On a real store of 500 conversation DBs (206 MB), `ccusage antigravity session --json --offline` takes about **185 s of single-core CPU** (~0.5 s per DB; 40 DBs / 16 MB took 20 s). Claude (120 MB) takes 1 s and codex (10 homes) takes 6 s. The loader (`loader.rs:19-40`) parses databases sequentially. Two possible fixes: + - Use the same size-balanced parallel reads the JSONL adapters already use. - Cache parsed events per (path, size, mtime), since most conversation DBs never change again. @@ -82,6 +87,7 @@ Either would make a 5-minute refresh cadence viable. I can share timings and pro Provider limits are windows whose start the provider decides: Anthropic's 5-hour session (for example 12:40→17:40Z), the weekly cap, and Codex's primary/secondary windows. `--since` accepts `YYYYMMDD` only. `blocks` is Claude-only and anchors on the hour of the first message, so it doesn't line up with the provider's reset (`blocks --active` reported 15:00–20:00 while Anthropic's own window was 12:40–17:40). Either of these would help: + - **(a)** Accept RFC 3339 timestamps in `--since/--until` for every report. `session` totals would then be bounded to the instant (related: #1609, #1791). - **(b)** Add `ccusage events --json`: one row per priced request with `timestamp`, `sessionId`, `projectPath`, `model` and the token/cost fields. This is the most general option, and callers can window it however they like. @@ -92,6 +98,7 @@ Today we work around it by differencing cumulative `session` totals between coll **Title:** `codex session` rows can't be attributed when `CODEX_HOME` lists several homes With `CODEX_HOME=a,b,c`, session rows carry `directory: "2026/09/20"` and a `sessionId` that is a date path, but nothing that says which home the row came from. Rollouts do record `cwd` in `session_meta`, though. Please add one of: + - `projectPath` from `session_meta.cwd`, consistent with claude and pi, or - a `codexHome` field. @@ -102,6 +109,7 @@ Until then we run ccusage once per `CODEX_HOME` (10 runs, ~0.6 s each). **Title:** current Copilot CLI writes usage to `~/.copilot/session-store.db`, which isn't read On our hosts, current Copilot CLI builds no longer write `session-state/*/events.jsonl`. Usage instead goes to the SQLite table `assistant_usage_events`, with these columns: + - `model` - `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `reasoning_tokens` - `request_multiplier`, `total_nano_aiu` diff --git a/docs/homebrew-tap/CONTRIBUTING.md b/docs/homebrew-tap/CONTRIBUTING.md index 36fb0e22..3d6e2a98 100644 --- a/docs/homebrew-tap/CONTRIBUTING.md +++ b/docs/homebrew-tap/CONTRIBUTING.md @@ -68,6 +68,12 @@ and `Casks/`. It also makes sure that each download URL is under `sha256` digest. It does not download artifacts or compare a digest with the downloaded file. +The script also checks each formula that GoReleaser generates. The header of +such a file says `DO NOT EDIT`. Renovate must not change such a formula, so +`renovate.json` must have a `packageRules` entry for the file, with +`"enabled": false`. If you add a generated formula, add this entry in the +same pull request. + CI (`.github/workflows/ci.yml`) runs the regression suite and the validation script. It also runs `brew audit` and installs `corral-vm` and the `tavern` cask on Linux. CI does not install `bluefin-cli`, and it does not install on diff --git a/docs/homebrew-tap/ROADMAP.md b/docs/homebrew-tap/ROADMAP.md index 224aa03c..ac1821ef 100644 --- a/docs/homebrew-tap/ROADMAP.md +++ b/docs/homebrew-tap/ROADMAP.md @@ -65,10 +65,13 @@ ownership and freshness are tracked in - [ ] Once that credential exists, authorize Tavern's `Update Homebrew Tap` for the current published release, then confirm the cask and install/parity evidence. -- [ ] Decide corral-vm's publisher: add a GoReleaser Homebrew block in corral, - or keep manual bumps with a named owner. v0.7.0 - ([corral#339](https://github.com/tuna-os/corral/issues/339)) is the next - release that will need one. +- [ ] Let corral-vm's publisher open its own pull request. corral publishes + through its `release-brew.yml` (see AGENTS.md), not GoReleaser. For v0.7.0 + it pushed the bump branch, but its `COMMITTER_TOKEN` got HTTP 403 when it + tried to open the pull request, so a person opened + [#80](https://github.com/tuna-os/homebrew-tap/pull/80). v0.7.1 arrived as a + Renovate pull request + ([#91](https://github.com/tuna-os/homebrew-tap/pull/91)). - [ ] Set a release-currency objective: update a supported formula or cask, or publish a visible exception, within 48 hours of an eligible upstream release. diff --git a/docs/proton-unofficial-sdk/index.md b/docs/proton-unofficial-sdk/index.md index 0196de46..7f3f6802 100644 --- a/docs/proton-unofficial-sdk/index.md +++ b/docs/proton-unofficial-sdk/index.md @@ -568,12 +568,15 @@ for encryption. A card that pins keys for the address decides which key is the recipient's. When the API offers keys for that address and none of them is pinned, the send is refused with `send_failed` rather than encrypted to the API's key: -a key the key server swapped is what a pin guards against. This is where -the table leaves Bridge, which would use the API's key; Proton's web client -refuses as well. To send again, the user trusts the new key (or removes -the old one) in the contact. One exception: a card that says not to encrypt -to keys it does not pin gets cleartext, as it asked, and `secure` delivery -refuses that as usual. +a key the key server swapped is what a pin guards against. A pinned key +the API still lists but no longer marks active counts as not offered while +another key is active: its owner retired it, as obsolete or compromised, +and the key that replaced it is not pinned. This is where the table leaves +Bridge, which would use the API's key, or the retired pinned one; Proton's +web client refuses as well. To send again, the user trusts the new key (or +removes the old one) in the contact. One exception: a card that says not to +encrypt to keys it does not pin gets cleartext, as it asked, and `secure` +delivery refuses that as usual. Then a draft is created (body encrypted to the sender's key, Reply-To and the Message-ID set), attachments are uploaded encrypted, and the packages @@ -777,6 +780,20 @@ go test -mod=vendor ./... go build -mod=vendor -trimpath -o proton-helper ./cmd/proton-helper ``` +CI also gates every pull request on `govulncheck` +(`.github/workflows/govulncheck.yml`). It fails when a known advisory has a +call path from `protonsdk/` or `cmd/`, which is most likely after a +dependency bump. Unlike the checks above, it needs the network to fetch +the vulnerability database. Its standard-library findings depend on the +Go that runs it, so use the version in `go.mod`, as CI does; a newer local +Go can report advisories that CI does not: + +```sh +go install golang.org/x/vuln/cmd/govulncheck@v1.9.0 +GOTOOLCHAIN="go$(go list -m -f '{{.GoVersion}}')" GOFLAGS=-mod=vendor \ + "$(go env GOPATH)/bin/govulncheck" ./protonsdk/... ./cmd/... +``` + The tests run go-proton-api's own in-process API server (`github.com/ProtonMail/go-proton-api/server`) behind a reverse proxy the tests control, and drive the library through its real framing: login → diff --git a/docs/spindle/mls.md b/docs/spindle/mls.md index 1472ad7a..1f21d6ef 100644 --- a/docs/spindle/mls.md +++ b/docs/spindle/mls.md @@ -3,23 +3,25 @@ sidebar_position: 21 title: "mls" --- -**Decision on 2026-10-02: no-go.** Spindle does not start MLS work yet. -This page records the evidence, what the proposals ask of a server, and -the events that reopen the question. It is the design review that -[#23](https://github.com/tuna-os/spindle/issues/23) asks for. When a -trigger at the end of this page fires, update this page before you write -code. +**Decision refreshed on 2026-10-22: no-go.** The specification and client +gates remain closed. A feature- and runtime-gated hub implementation has +landed, but [#22](https://github.com/tuna-os/spindle/issues/22) has not met +its exit criteria. This page records the evidence, what the proposals ask +of a server, and the events that reopen the question. It is the design +review that [#23](https://github.com/tuna-os/spindle/issues/23) asks for. +When a trigger at the end of this page fires, update this page before you +write code. ## The gates The exit criteria of #23 name four conditions. Only one passes today. -| Gate | Result | Evidence on 2026-10-02 | +| Gate | Result | Evidence on 2026-10-22 | |---|---|---| | Megolm compatibility is complete | Pass | The M2 row of [docs/dashboard.md](https://github.com/tuna-os/spindle/blob/main/docs/dashboard.md) is **Done**: E2EE transport, fallback keys, device lists, key backup and cross-signing. | | A stable specification | Fail | No MLS proposal has left review. The next table has the details. | | A maintained client | Fail | No client that people use speaks any of the proposals. The second table has the details. | -| Hub mode is available | Fail | [#22](https://github.com/tuna-os/spindle/issues/22) (MSC3995) is open, and the M6 row of the dashboard says "Not started". | +| Hub mode is complete | Fail | [#628](https://github.com/tuna-os/spindle/pull/628) put the opt-in implementation on `main`, but #22 remains open for room-class transitions and the real-Synapse failover scenario. | ### The proposals @@ -54,10 +56,12 @@ MSC4244 that server is the DS. In MSC4256 it is the first entry of and a commit from a server outside the list travels as an `m.mls.pending_commit`. -Spindle already gives each room a total order: the linear index (`li`) of -SPEC §5. On one server, `li` order is commit order and the DS check is one -state lookup. Across servers, `li` is a total order only under hub mode, -so this requirement waits for #22. +Spindle gives each room a total order: the linear index (`li`) of SPEC §5. +On one server, `li` order is commit order and the DS check is one state +lookup. Across servers, #628's opt-in hub path now provides a +compare-and-append order, signed epochs and failover. That baseline is +on `main`, but #22 has not met its exit criteria, so an MLS prototype still +waits for that gate. **Epoch.** Neither proposal defines a state event that holds the epoch. In MSC4256 the `m.mls.commit` state event is the current commit, and every @@ -129,7 +133,7 @@ update the tables above with the new dates. draft and fills its `TODO` sections. - A client that people use ships an MLS mode, with commits in the last six months. A test client does not count. -- #22 hub mode reaches `main`. +- #22 hub mode meets its exit criteria and closes. When all three gates pass, the work follows #23 in order. First, put a prototype behind the `unstable-msc4244` or `unstable-msc4256` Cargo diff --git a/docs/tavern/ARCHITECTURE.md b/docs/tavern/ARCHITECTURE.md index a87369d6..d492d679 100644 --- a/docs/tavern/ARCHITECTURE.md +++ b/docs/tavern/ARCHITECTURE.md @@ -70,9 +70,10 @@ UI modules do not run `brew` themselves. to the desktop. The desktop opens a URI with the application that owns its scheme. Thus each function in this module examines its argument before it opens the URI. A web link must be `http`, `https`, or `mailto`. A software -center link must contain a Flatpak application ID. Other modules call these -functions and do not use `Gtk.UriLauncher`, `Gtk.LinkButton`, -`Gio.AppInfo.launch_default_for_uri`, or `xdg-open`. +center link must contain a Flatpak application ID. + +Other modules call these functions and do not use `Gtk.UriLauncher`, +`Gtk.LinkButton`, `Gio.AppInfo.launch_default_for_uri`, or `xdg-open`. `tests/test_dependency_boundaries.py` makes sure of this. **Backend lifecycle.** `BackendLifecycle` (`backend_lifecycle.py`) controls diff --git a/docs/tromso/SPEC.md b/docs/tromso/SPEC.md index fd08a925..2bfa3d0f 100644 --- a/docs/tromso/SPEC.md +++ b/docs/tromso/SPEC.md @@ -110,8 +110,12 @@ freedesktop-sdk (base SDK, via elements/freedesktop-sdk.bst junction) ``` The build is fully reproducible: all sources are pinned by git ref or tarball SHA256. -BuildGrid is used for distributed compilation — build jobs run on the home cluster -over Tailscale and results are cached as content-addressable artifacts. +CI has no remote executor. Builds run on GitHub-hosted runners, split into +plan, core, chunk and final jobs that hand their CAS to each other as tarballs +on GHCR. BuildStream pulls artifacts and sources from +`cache.freedesktop-sdk.io` (`project.conf`). Remote execution through +`cache.projectbluefin.io` stays off until a CASD client certificate exists. +See [docs/ci-and-iso-pipeline.md](https://github.com/tuna-os/tromso/blob/main/docs/ci-and-iso-pipeline.md). --- @@ -125,7 +129,7 @@ over Tailscale and results are cached as content-addressable artifacts. | Bootloader | systemd-boot | Via bootc install | | Image format | OCI/bootc | Enables atomic upgrades via `bootc upgrade` | | Build system | BuildStream 2 | Same as GNOME OS and dakota; hermetic builds | -| Artifact cache | BuildGrid (gRPC) | Home cluster via Tailscale; survives runner restarts | +| Artifact cache | freedesktop-sdk CAS + per-chunk CAS tarballs on GHCR | Free runners cannot hold the whole KDE build; chunks restore their own previous CAS | --- diff --git a/docs/tuna-desktop/api-stability.md b/docs/tuna-desktop/api-stability.md index b82f5137..468b0a44 100644 --- a/docs/tuna-desktop/api-stability.md +++ b/docs/tuna-desktop/api-stability.md @@ -33,7 +33,8 @@ release. | Crate | Kind | In-repo dependents | Tier | |---|---|---|---| -| `tuna-shell-control` (`crates/shell-control-schema`) | library | compositor, shell-host, shell-gtk, backlight | internal; its wire format is a cross-process contract | +| `tuna-shell-control` (`crates/shell-control-schema`) | library | compositor, shell-host, shell-gtk, wallpaper | internal; its wire format is a cross-process contract | +| `tuna-output` (`crates/output`) | library | shell-control, backlight, compositor, shell-host, shell-gtk | internal; its field order is part of the shell-control wire format | | `tuna-wallpaper` | library | compositor | internal | | `tuna-backlight` | library | shell-gtk | internal | | `tuna-magnifier` | library | compositor, shell-gtk | internal; its session JSON file is a cross-process contract | diff --git a/docs/tuna-desktop/capture-security.md b/docs/tuna-desktop/capture-security.md index 35663821..619e976f 100644 --- a/docs/tuna-desktop/capture-security.md +++ b/docs/tuna-desktop/capture-security.md @@ -7,7 +7,7 @@ ScreenCast session creation and Screenshot requests require the supervised shell The portal is the trusted consent broker; this check authenticates the broker, rather than implementing its picker. Applications must use the external desktop portal. The supervised shell's screenshot UI supplies explicit local selection and Capture actions. The shell's public recorder D-Bus methods deny external calls, so an arbitrary caller cannot borrow the shell's trusted compositor connection. -Each ScreenCast session belongs to its unique creator. Only that creator may add streams, start or stop it. Start is single-use, streams cannot be added after Start, and revocation is permanent. Registries admit at most 256 sessions and 64 streams per session. The compositor denies queued starts when locked or already revoked; lock closes all active PipeWire streams in its next tick, and existing offscreen capture paths also refuse locked frames. Idle dimming or blanking before lock does not itself revoke a grant. +Each ScreenCast session belongs to its unique creator. Only that creator may add streams, start or stop it. Start is single-use for the session and for each stream; as in Mutter, a stream added after Start waits for its own `Stream.Start`. Revocation is permanent. Registries admit at most 256 sessions and 64 streams per session. The compositor denies queued starts when locked or already revoked; lock closes all active PipeWire streams in its next tick, and existing offscreen capture paths also refuse locked frames. Idle dimming or blanking before lock does not itself revoke a grant. The D-Bus service scans grants every 100 ms. Losing the creator connection, the trusted portal name, the supervised shell PID or unlocked state revokes the grant and queues stream teardown. The normal disconnect teardown latency is the scan interval plus one compositor tick; this is not a hard real-time guarantee under CPU starvation. Explicit Stop revokes immediately before queuing teardown. Closed session/stream objects are removed from the bus and registry. diff --git a/docs/tuna-desktop/ci-runners.md b/docs/tuna-desktop/ci-runners.md index 5331510d..2a0afdca 100644 --- a/docs/tuna-desktop/ci-runners.md +++ b/docs/tuna-desktop/ci-runners.md @@ -38,7 +38,7 @@ schedule, dispatch or a pull request whose head repository is | Runner | Lanes | | --- | --- | -| `tuna-ci-24.04` | select-lanes, check, fprint-phase-proof, app-content, scroll-proof, grid-cancel-comparison, gtk-shell, native-reference-context, parity-ledger, docs-shots, ci-gate | +| `tuna-ci-24.04` | select-lanes, check, app-content, scroll-proof, grid-cancel-comparison, gtk-shell, native-reference-context, parity-ledger, docs-shots, ci-gate | | `tuna-ci-26.04` | journey, orca-speech, portal-security, remote-security, niri-parity | | GitHub-hosted, always | arch-package, drm-smoke, marlin-vm (pull requests: the primary lifecycle leg only; push, schedule and dispatch add the Orca 51 leg and both paired reference members), marlin-image (push, schedule and dispatch only), gdm51-native-package | @@ -120,7 +120,7 @@ but the explicit older head checkout lacked it, so `check` stopped with `[Errno 2] No such file or directory`. Checking out the merge ref preserves the real predicate suite instead of adding a placeholder or making it optional. The check job exports its actual checked commit as `tested_sha`; -the authentication, fingerprint and grid comparison proofs check out that +the authentication and grid comparison proofs check out that exact output. Their admission receipts bind it to the checkout and commit tree separately from the API's triggering `head_sha` (the PR head, not its merge tree). Lane selection remains head-only because it computes the PR diff --git a/docs/tuna-desktop/development.md b/docs/tuna-desktop/development.md index 88f72298..8ce92776 100644 --- a/docs/tuna-desktop/development.md +++ b/docs/tuna-desktop/development.md @@ -77,7 +77,7 @@ spektacular version check ## Project Structure -The project is a Cargo workspace with eight crates. The crate manifests and +The project is a Cargo workspace with nine crates. The crate manifests and existing crate `README.md` files describe their purpose and dependencies. ``` @@ -85,6 +85,7 @@ tuna-desktop/ ├── crates/ │ ├── backlight/ # tuna-backlight: bounded backlight/owned-connector reads │ ├── compositor/ # tuna-compositor and tuna-session binaries (Smithay) +│ ├── output/ # tuna-output: compositor-owned native DRM output identity │ ├── shell-control-schema/ # tuna-shell-control: compositor/shell IPC protocol │ ├── shell-host/ # tuna-shell-host: original shell binary and shared shell logic │ ├── shell-gtk/ # tuna-shell-gtk: GTK4/libadwaita shell (ADR 0006) diff --git a/docs/tuna-desktop/environment.md b/docs/tuna-desktop/environment.md index 5f5aa600..595538a2 100644 --- a/docs/tuna-desktop/environment.md +++ b/docs/tuna-desktop/environment.md @@ -33,8 +33,9 @@ environment `tuna-session` or `tuna-compositor` starts from. | `TUNA_IBUS` | compositor | `0` does not start the IBus bridge. By default the bridge starts whenever `ibus-daemon` is on `PATH` and a bridge binary can be found. | `crates/compositor/src/ime.rs:47-62` | | `TUNA_IBUS_BRIDGE_BIN` | compositor | Path of the `tuna-ibus-bridge` binary. Without it the compositor looks beside its own executable, then on `PATH`. | `crates/compositor/src/ime.rs:62-69` | | `TUNA_BELL` | compositor | `0` silences the audible bell. The visual bell still follows its setting. | `crates/compositor/src/bell.rs:80-85` | -| `TUNA_PAM_SERVICE` | compositor | PAM service the lock screen authenticates against, instead of `tuna-lock`. An empty value uses the default. | `crates/compositor/src/pam.rs:20-23`, `crates/compositor/src/pam.rs:247-251` | -| `TUNA_FPRINTD_OFF` | compositor | When set, fingerprint unlock is off: the lock screen behaves as if there is no reader and asks for the password. | `crates/compositor/src/fprintd.rs:73-76`, `crates/compositor/src/fprintd.rs:976-978` | +| `TUNA_PAM_SERVICE` | compositor | PAM service the lock screen authenticates against, instead of `tuna-lock`. An empty value uses the default. | `crates/compositor/src/pam.rs:23-26`, `crates/compositor/src/pam.rs:254-270` | +| `TUNA_PAM_FINGERPRINT_SERVICE` | compositor | PAM service the lock screen's fingerprint conversation runs, instead of `tuna-lock-fingerprint`. An empty value uses the default. | `crates/compositor/src/pam.rs:27-30`, `crates/compositor/src/pam.rs:259-270` | +| `TUNA_FPRINTD_OFF` | compositor | When set, fingerprint unlock is off: the lock screen behaves as if there is no reader and asks for the password. | `crates/compositor/src/fprintd.rs:41-44`, `crates/compositor/src/fprintd.rs:338-341` | | `TUNA_IDLE_TIMEOUT_MS` | compositor | Idle time in milliseconds before the session locks, for scripted lock tests. Zero, non-numbers and unset use the five-minute default. | `crates/compositor/src/runtime.rs:44-53`, `crates/compositor/src/lock.rs:15-16` | ## Set by Tuna Desktop for its own processes @@ -96,7 +97,7 @@ these emitters (all paths below are under `crates/`): | `tuna-compositor: drm: output`, session paused/activated | `compositor/src/drm.rs` | | Compositor workspace, switcher, modifier, session mode, media diagnostics | `compositor/src/windows.rs` | | Compositor lock conversation and authentication retirement | `compositor/src/runtime/auth.rs`, `compositor/src/runtime.rs` | -| `screen reader retired`, `FPRINT-PHASE` receipts | `compositor/src/orca.rs`, `compositor/src/fprintd.rs` | +| `screen reader retired` | `compositor/src/orca.rs` | | Shell grid, transient, unlock-dialog, switcher fade | `shell-gtk/src/grid_animation.rs`, `transient.rs`, `lock_curtain.rs`, `switcher.rs` | | Shell lock/auth, command results, password-submission **markers** (not passwords) | `shell-gtk/src/lock.rs`, `lock_auth.rs` | | Shell keybindings, media-key setup, policy refusals, screenshot-clipboard marker | `shell-gtk/src/main.rs`, `power.rs`, `run_dialog.rs` | @@ -105,9 +106,8 @@ these emitters (all paths below are under `crates/`): | Shell media diagnostics and `FOLDER-CREATE` observations | `shell-gtk/src/media_keys.rs`, `folders.rs` | | Bridge ready/context, key/cursor/focus, property and method diagnostics | `shell-host/src/bin/tuna-ibus-bridge.rs`, `shell-host/src/ibus.rs` | -Preformatted switcher and fingerprint receipts also use their crate's helper, -without allocating another buffer; the fingerprint proof still fails on a -receipt write error. Python proof fixtures (IBus test engine, fprintd mock, +Preformatted switcher receipts also use their crate's helper, without +allocating another buffer. Python proof fixtures (IBus test engine, fprintd mock, service stubs) use separate artifact logs, not this shared session stream. Wallpaper/SVG helper diagnostics are not proof receipts, but are buffered too because they can otherwise fragment another process's receipt. @@ -120,7 +120,7 @@ be driven through them by accident. | Variable | Read by | Effect | Source | |---|---|---|---| -| `TUNA_COMPOSITOR_STATE` | compositor, `tuna-shell-gtk` | Absolute path for coherent JSON snapshots: windows, focus, overview, lock, keyboard, frame cost and more. One owned writer atomically replaces the file off the compositor thread, retaining only the latest waiting snapshot. Successful writes alone deduplicate; failed bodies can retry on the next submission. Graceful shutdown drains the latest body. Publication is not presentation; existing real-frame evidence rules remain unchanged. | `crates/compositor/src/state_snapshot.rs`, `crates/compositor/src/runtime.rs:2520` | +| `TUNA_COMPOSITOR_STATE` | compositor, `tuna-shell-gtk` | Absolute path for coherent JSON snapshots: windows, focus, overview, lock, keyboard, frame cost and more. One owned writer atomically replaces the file off the compositor thread, retaining only the latest waiting snapshot. Successful writes alone deduplicate; failed bodies can retry on the next submission. Graceful shutdown drains the latest body. Publication is not presentation; existing real-frame evidence rules remain unchanged. Proofs keep a copy with `snapshot_state` from `scripts/lib/tuna-state-snapshot.sh`: plain `cp` refuses a file renamed over mid-copy. | `crates/compositor/src/state_snapshot.rs`, `crates/compositor/src/runtime.rs:2520` | | `TUNA_ANIMATION_CLOCK` | compositor, `tuna-shell-gtk` | Absolute path of a file that freezes or steps animation time; needs `TUNA_COMPOSITOR_STATE`. See [animation clock](https://github.com/tuna-os/tuna-desktop/blob/main/docs/testing.md#animation-clock-and-motion-policy). | `crates/compositor/src/animation_clock.rs:20-21`, `crates/shell-gtk/src/anim_clock.rs:55-65` | | `TUNA_PROOF_SWIPE_INPUT` | compositor | Absolute path of a JSON file of synthetic touchpad swipe phases, each read once; needs `TUNA_COMPOSITOR_STATE`. | `crates/compositor/src/runtime.rs:1488-1491`, `crates/compositor/src/runtime.rs:3001-3012` | | `TUNA_INTROSPECT_FILE` | `tuna-shell-host` | Absolute path where the legacy shell writes a snapshot of its panel and overview. | `crates/shell-host/src/introspect.rs:20-44`, `crates/shell-host/src/panel.rs:4290` | @@ -165,7 +165,6 @@ start. They have no effect on an installed session. | `TUNA_NATIVE_NODE`, `TUNA_NATIVE_SERIAL`, `TUNA_NATIVE_COOKIE`, `TUNA_NATIVE_MUTED`, `TUNA_NATIVE_EXPECTED` | Inputs to the PipeWire privacy test's child process. | `crates/shell-gtk/src/privacy.rs:1725-1730` | | `TUNA_A11Y_TEST_SCHEMA_DIR`, `TUNA_A11Y_RECEIPT` | Schema fixture and receipt file for `scripts/tuna-gtk-accessibility-proof`. | `crates/shell-gtk/src/accessibility.rs:381`, `crates/shell-gtk/src/accessibility.rs:439` | | `TUNA_SCREENSHOT_LIFECYCLE_RECEIPT` | Receipt file the screenshot UI test writes when it passes. | `crates/shell-gtk/src/screenshot_ui.rs:1141-1146` | -| `TUNA_FPRINT_PHASE_NONCE` | A 32-hex-digit nonce that makes the fingerprint tests record phase timings for `scripts/tuna-fprint-phase-proof`. | `crates/compositor/src/fprintd.rs:4238-4247` | | `TUNA_XIM_PROBE_OWNER_FIXTURE`, `TUNA_XIM_PROBE_PID_FILE` | IBus XIM ownership test fixture. | `crates/compositor/src/ime.rs:391-402` | | `GSETTINGS_BACKEND` | Two shell tests check for `memory`. | `crates/shell-gtk/src/accessibility.rs:286`, `crates/shell-gtk/src/lockdown.rs:499` | | `DBUS_SESSION_BUS_ADDRESS`, `WAYLAND_DISPLAY`, `WAYLAND_SOCKET` | The admitted GTK tests check that they run on a private session bus and X display, with no Wayland connection. | `crates/shell-gtk/src/notify.rs:1892-1895`, `crates/shell-gtk/src/osd.rs:400-405` | @@ -277,8 +276,8 @@ processes and are not options: the `TUNA_*_PRIVATE_BUS` and under `dbus-run-session`, the `TUNA_STUB_*_LOG` call logs, the `TUNA_TEST_*` controls for `scripts/lib/tuna-test-window.py`, `TUNA_FLASH_PROOF_ARTIFACTS` and `TUNA_PROOF_SOURCE_SHA` for proof helper -scripts, and the ownership markers `TUNA_GRID_COMPARISON_OWNER` and -`TUNA_FPRINT_PHASE_OWNER`. `scripts/ci-select-lanes` and the proof identity +scripts, and the ownership marker `TUNA_GRID_COMPARISON_OWNER`. +`scripts/ci-select-lanes` and the proof identity helpers in `scripts/lib/` read the `GITHUB_*` and `RUNNER_*` variables GitHub Actions provides. diff --git a/docs/tuna-desktop/index.md b/docs/tuna-desktop/index.md index 5f614440..4c398f4d 100644 --- a/docs/tuna-desktop/index.md +++ b/docs/tuna-desktop/index.md @@ -5,7 +5,7 @@ sidebar_label: "tuna-desktop" status: unknown --- -Formerly **Roost**. Binaries, packages, crates and environment variables were renamed in [#505](https://github.com/tuna-os/tuna-desktop/issues/505); the old `roost-*` names keep working for one release (see [packaging/README.md](https://github.com/tuna-os/tuna-desktop/blob/main/packaging/README.md)). +Formerly **Roost**. Binaries, packages, crates and environment variables were renamed in [#505](https://github.com/tuna-os/tuna-desktop/issues/505); the one-release compatibility layer (`roost-*` binary symlinks and `ROOST_*` environment variables) was removed in [#775](https://github.com/tuna-os/tuna-desktop/pull/775). [packaging/README.md](https://github.com/tuna-os/tuna-desktop/blob/main/packaging/README.md#upgrading-from-the-former-name) covers upgrading from the old package. A new, independent Wayland desktop session with a GNOME-inspired everyday workflow. This project is not a GNOME Shell rewrite and does not promise compatibility with GNOME Shell extensions or private Mutter APIs. diff --git a/docs/tuna-desktop/install.md b/docs/tuna-desktop/install.md index 7d52045c..6c0cd38b 100644 --- a/docs/tuna-desktop/install.md +++ b/docs/tuna-desktop/install.md @@ -48,7 +48,11 @@ sudo apt install ./tuna-desktop_X.Y.Z_amd64.deb ``` Dependencies resolve automatically on a target with the declared runtime -packages available. After installing, the Tuna Desktop session is +packages available: GTK at least 4.14, libadwaita, gtk4-layer-shell, +libgweather 4.4 and `python3` for the shipped GeoClue agent-policy helper. Location services +need `geoclue-2.0`, which the package recommends rather than requires; +without it the session runs and hides the location indicator. After +installing, the Tuna Desktop session is selectable from the login screen. Upgrading installs the newer package over the older one; the [legacy-upgrade guide](https://github.com/tuna-os/tuna-desktop/blob/main/docs/legacy-upgrade.md) explains the temporary two-file bridge, explicit session reselection, preserved settings @@ -66,10 +70,9 @@ Install the complete package list in matching the CI `check` job). The compositor builds its DRM and PipeWire features by default, so it needs the libseat, libinput, libudev, GBM, libdrm, PipeWire, libclang and xkbcommon development packages -(`crates/compositor/Cargo.toml`); the GTK shell and greeter need GTK 4, -libadwaita and gtk4-layer-shell, and the shell also libgweather 4 for the -date menu's world clocks and weather (`crates/shell-gtk/Cargo.toml`, -`crates/greeter/Cargo.toml`). Where the distribution has no gtk4-layer-shell +(`crates/compositor/Cargo.toml`); the GTK shell needs GTK 4, libadwaita, +gtk4-layer-shell and, for the date menu's world clocks and weather, +libgweather 4 (`crates/shell-gtk/Cargo.toml`). Where the distribution has no gtk4-layer-shell package, `scripts/ci-install-gtk4-layer-shell` builds it. At run time the nested backend additionally dlopens the EGL/Mesa display libraries (`libegl1`, `libgl1-mesa-dri`, `libgbm1` on Ubuntu). @@ -109,15 +112,21 @@ on the login screen. The entry's `Exec=` line is `tuna-session`, never the compositor directly, so shell supervision stays in the loop, and `X-GDM-SessionRegisters=true` tells GDM the session registers itself. -The lock screen authenticates through the `tuna-lock` PAM service. The -packages install it; a source install needs it too, or PAM falls back to the -`other` service (deny on most distributions) and a locked session cannot be -unlocked: +The lock screen authenticates through the `tuna-lock` PAM service, and +fingerprint unlock through `tuna-lock-fingerprint` (`pam_fprintd` plus your +`login` account stack, like GDM's `gdm-fingerprint`). The packages install +both; a source install needs them too. Without `tuna-lock`, PAM falls back to +the `other` service (deny on most distributions) and a locked session cannot +be unlocked; without `tuna-lock-fingerprint`, only fingerprint unlock fails: ```sh install -Dm0644 share/pam.d/tuna-lock /etc/pam.d/tuna-lock +install -Dm0644 share/pam.d/tuna-lock-fingerprint /etc/pam.d/tuna-lock-fingerprint ``` +Fingerprint unlock also needs `pam_fprintd.so`: the `libpam-fprintd` +package on Debian and Ubuntu, `fprintd` on Arch. + ## When something goes wrong [Troubleshooting](https://github.com/tuna-os/tuna-desktop/blob/main/docs/troubleshooting.md) covers package, build and login diff --git a/docs/tuna-desktop/parity-ledger.md b/docs/tuna-desktop/parity-ledger.md index a9a07bf0..63a57751 100644 --- a/docs/tuna-desktop/parity-ledger.md +++ b/docs/tuna-desktop/parity-ledger.md @@ -37,7 +37,7 @@ rationale and owner), `untested`. | P-SY-01 | Session starts from the display manager on hardware | partial | proof:D-OUTPUT, proof:D-IDLE, proof:D-FRAMES, cargo:recycled_buffer_repaints_damage_from_intervening_frames, cargo:timing_only_frame_and_removed_elements_keep_correct_damage, cargo:global_drawing_pass_order_and_opacity_changes_reset_buffer_history, proof:D-SHELL, proof:V-DRM, proof:V-SHELL, proof:V-PANEL, cargo:pam_unlock_accepts_the_right_password_and_nothing_else, proof:D-ENDURANCE, proof:D-NOPANIC, proof:V-DISPLAY-MANAGER, proof:V-GREETER-LIST, proof:V-GDM-FALLBACK, proof:V-GDM-LOGIN, proof:V-NOPANIC, proof:V-LIFECYCLE-OWNER, proof:V-VT, proof:V-SUSPEND, proof:V-SUSPEND-GPU-PM, proof:V-SUSPEND-GPU-UPLOAD, proof:V-SHELL-FAIL-CLOSED, proof:V-LOGOUT, proof:V-LIFECYCLE | DRM/KMS on vkms in CI (`scripts/tuna-drm-smoke`), with retained idle before/after frame-counter snapshots (at most one new submission in three seconds), bounded initial submissions over the longer idle window, 240 real changing-client presentations at both default and 200% scale carrying ordered vsync/hardware-completion feedback, and a 16-second endurance run without a panic; the `marlin-vm` and `marlin-vm-orca51` jobs build the Marlin image from source, give it tunaOS's tuna-flavor GDM login path (greeter theme overlay, `FallbackSession=tuna`, every other session hidden; `packaging/marlin/vm-lane/tunaos/`), install it with bootc and boot it five times in QEMU/KVM, where the lane types the fixture password into stock GDM's user list and GDM starts the Tuna Desktop DRM/KMS session as a non-root `gdm-password` logind session with the GTK shell and black panel (V-GREETER-LIST, V-GDM-FALLBACK, V-GDM-LOGIN on all five boots of CI run 40977772289, PR #858; `scripts/tuna-vm-lane`, `docs/vm-lifecycle.md`); in that run the session also survives a VT switch, real S3 suspend/resume and a supervised shell replacement, and the product's Log Out returns to the GDM greeter; the published-image nightly runs the same GDM login code against `marlin:tuna` (`docs/marlin-tuna-nightly.md`) and passed with tuna-desktop 1.0.0beta.1-1 after tunaOS#4055 (runs 40967204592 on marlin@sha256:6b9b3413, 40977772364 on marlin@sha256:ae6363c1); its sixth pristine boot now runs a bounded 3000 s soak with the native frame workload and publishes a memory and frame-pacing report (nightly-only V-SOAK, `docs/soak.md`; run 41080213387 on marlin@sha256:ae6363c1: 51 samples, session PSS 548.6 MiB after warmup and 549.4 MiB at the end, fds and processes flat, 224951 frames at a 13.33 ms p99 interval), which is not the 24-hour soak (#203) | VM only (virtio-gpu). No physical hardware yet (#68) | | P-SY-02 | Multi-monitor with per-output panel and hotplug | pass (nested) | cargo:hotplug_remove_and_readd_returns_windows_to_their_output, cargo:moved_output_carries_its_windows, cargo:rearranged_and_scaled_outputs_carry_their_windows_past_the_next_tick, cargo:unplug_racing_a_wl_output_bind_keeps_the_client, cargo:hotplug_prefers_stored_then_complete_existing_then_linear, proof:V-INTROSPECT-SCREEN | `tests/outputs.rs`, `tests/migration.rs`; real DRM connector hotplug runs nightly in the `nested stress` workflow's `hotplug` job (vkms configfs, H-* gates, `docs/testing.md`), not yet a ledger proof input; virtio-gpu hotplug, rotation and unplug in the Marlin VM (V-INTROSPECT-SCREEN) | real panels/EDIDs and colord registration on hotplug untested | | P-SY-03 | Fractional scaling and mixed DPI | partial | proof:S-LOGICAL, proof:S-PANEL, proof:S-WINDOW, proof:S-INPUT, proof:S-X11-WINDOW, proof:S-X11-INPUT, proof:D-SCALE, cargo:picks_the_arrangement_for_the_lit_connectors, cargo:windows_take_the_scale_of_the_output_they_overlap_most, cargo:new_windows_start_at_the_scale_of_the_output_under_the_pointer | per-output scale and layout from GNOME's monitors.xml on hardware; `TUNA_SCALE` for nested sessions; the nested proof runs 100/125/150/200 percent with native and genuine X11 painted clients and physical-pointer input; logical layout, fractional-scale clients, scaled input and cursor; on mixed DPI each window and layer surface gets the preferred buffer and fractional scale of the output it overlaps most, re-sent every frame | mixed DPI not yet run on hardware (#68) | -| P-SY-04 | XWayland apps run by default | pass (nested) | proof:G-X11-APP, proof:G-X11-DEMAND, proof:G-X11-RESTART, proof:G-X11-CLEANUP, proof:G-X11-INPUT-FOCUS, cargo:on_by_default_when_xwayland_is_installed, cargo:running_disconnect_keeps_backoff_and_total_restart_budget | default builds reserve compositor-owned sockets and advertise DISPLAY; first X11 connection consumes that exact owner to start the pinned Smithay 0.7.0 server; bounded restart preserves native windows; the X server's input focus follows the focused X11 window (Mutter's meta_x11_display_set_input_focus), not the X pointer | green main CI run 38878636595 (e67f6a8b) passed first-client mapping, on-demand start, actual server restart with native-ID preservation and socket/lock cleanup in the nested session; no installed-image X11 gate exists, and physical GPU/VT qualification remains separate | +| P-SY-04 | XWayland apps run by default | pass (nested) | proof:G-X11-APP, proof:G-X11-DEMAND, proof:G-X11-RESTART, proof:G-X11-CLEANUP, proof:G-X11-INPUT-FOCUS, proof:G-X11-ICONIC, cargo:on_by_default_when_xwayland_is_installed, cargo:running_disconnect_keeps_backoff_and_total_restart_budget | default builds reserve compositor-owned sockets and advertise DISPLAY; first X11 connection consumes that exact owner to start the pinned Smithay 0.7.0 server; bounded restart preserves native windows; the X server's input focus follows the focused X11 window (Mutter's meta_x11_display_set_input_focus), not the X pointer; a minimized X11 window (Super+H, the window menu, or its own WM_CHANGE_STATE IconicState) is WM_STATE IconicState with _NET_WM_STATE_HIDDEN and NormalState without once restored (Mutter's meta_window_x11_set_wm_state and set_net_wm_state, #1078) | green main CI run 38878636595 (e67f6a8b) passed first-client mapping, on-demand start, actual server restart with native-ID preservation and socket/lock cleanup in the nested session; no installed-image X11 gate exists, and physical GPU/VT qualification remains separate | | P-SY-06 | Clients find the protocols Mutter offers (dmabuf, activation, viewporter, fractional scale, cursor shape, idle inhibit, presentation time, fifo, shortcuts inhibit, xdg-foreign, dialogs) | partial | cargo:advertised_globals_match_the_golden_list, cargo:dmabuf_is_advertised_only_with_renderer_formats, cargo:focused_client_can_hand_focus_with_a_token, cargo:background_clients_and_serial_less_tokens_cannot_steal_focus, cargo:presentation_feedback_reports_the_frame_that_drew_the_window, cargo:a_hidden_window_keeps_its_feedback_until_drawn, cargo:fifo_holds_a_waiting_commit_until_the_next_refresh, cargo:fifo_keeps_advancing_behind_the_lock_screen, cargo:a_timed_update_waits_for_the_refresh_whose_presentation_reaches_it, cargo:timed_updates_apply_in_commit_order_not_timestamp_order, cargo:a_timestamp_with_a_whole_second_of_nanoseconds_is_invalid, cargo:nested_presentation_is_timed_on_the_monotonic_clock_without_hardware_claims, cargo:an_inhibiting_window_gets_the_shortcuts_until_super_escape, cargo:denied_shortcut_inhibition_stays_denied_after_refocus, cargo:shortcut_consent_cannot_survive_a_lock_or_focus_change, cargo:modal_dialogs_keep_focus_from_their_parent, cargo:exported_windows_parent_another_clients_dialog, cargo:provider_exit_returns_focus_to_the_pickers_foreign_parent, cargo:provider_exit_after_focus_moved_does_not_steal_focus, cargo:caller_exit_then_provider_exit_never_focuses_the_dead_caller, cargo:the_system_bell_rings, cargo:windows_keep_their_toplevel_tag, proof:G-GL-WINDOW, proof:G-WAYLAND-INFO, proof:G-SHORTCUT-CONSENT, proof:V-PICKER | `docs/protocols.md` lists what is advertised and each gap. G-WAYLAND-INFO runs `wayland-info` on the nested session and compares it with a real GNOME 51 capture (`tests/protocols/gnome51-wayland-info.txt`: gnome-shell/mutter 51.0, Fedora 45 headless, fedora:45@sha256:dbb22055c0c1...). The headless capture's 40 globals plus 3 source-derived floors remain in `tests/protocols/gnome51-globals.tsv`. Native Marlin GNOME 51 capture [37196669447](https://github.com/tuna-os/tuna-desktop/actions/runs/37196669447) records the same 40 versions plus DRM lease v1; `tests/protocols/marlin-gnome51-globals.tsv` represents all 41 captured globals plus two remaining source-only floors, with raw candidate/reference captures and digest/image/package/observer manifest retained. G-WAYLAND-INFO compares both lists; 27 of the 43 are offered at GNOME's version. Added for parity with Mutter (#89): wl_compositor v6; presentation-time v2 with feedback from the frame path (kernel vblank time and sequence on hardware), fifo and commit-timing released per refresh cycle, commit-timing tv_nsec validated as Mutter does (`crates/compositor/src/frame_timing.rs`); xdg-dialog (modal dialogs attached to their parent), xdg-foreign v2 (portal dialogs parented to the app; a provider that exits or restarts while its focused picker is open hands focus back to the caller, as Mutter's `focus_ancestor_or_top_window` does, never to a dead caller and never away from an app the user moved to, #432/#404), keyboard-shortcuts-inhibit with Super+Escape restoring, pointer-warp, xdg-system-bell (GNOME's bell sound), xdg-toplevel-tag Portal file choosers from real Wayland and X11 GTK callers are parented, centred and modal on a Marlin VM (V-PICKER). | 13 GNOME 51 globals missing, each with its reason in `docs/protocols.md`: gtk_shell1 by choice; not in Smithay 0.7 (toplevel drag, session management, color management and representation, background blur, wl_fixes, xdg-foreign v1); tablet (Smithay manager v1 only, tablet input not routed); hardware only (DRM lease, syncobj; #68); Xwayland keyboard grab (rootful Xwayland only). 3 at older versions because Smithay 0.7 implements no newer (xdg_wm_base 6/7, wl_seat 9/10, text-input 1/2). Shortcut inhibition uses the GTK shell's consent dialog and GNOME PermissionStore (G-SHORTCUT-CONSENT); configurable Xwayland exemption rules remain absent. Native reference uses the derived Marlin GNOME 51 baseline, four-vCPU/6-GiB/1280×800 KVM; Bochs still advertises dmabuf v3, so GPU-capable native-backend feedback remains unqualified | | P-SY-07 | End session: Suspend, Restart…, Power Off…, Log Out with GNOME's 60 s confirmation dialog | partial | proof:G-POWER-MENU, proof:G-POWER-DIALOG, proof:G-POWER-OFF, cargo:nested_sessions_only_offer_log_out, proof:G-POWER-ESCAPE, proof:G-SUSPEND-LOCK, cargo:countdown_text_matches_gnome, proof:V-SUSPEND, proof:V-LOGOUT, proof:V-RESTART-DIALOG, proof:V-POWER-OFF-DIALOG, proof:V-POWER-BUTTON, cargo:end_session_dialog_types_and_signals_match_gnome_51, cargo:end_of_session_routes_like_gnome_session_51, cargo:end_session_errors_carry_gnome_session_names, cargo:gsd_power_key_shutdown_opens_the_shells_dialog_and_follows_its_answer, proof:G-END-SESSION-RESTART, proof:G-END-SESSION-POWEROFF, proof:G-END-SESSION-LOGOUT, cargo:power_menu_requests_end_the_session_only_as_the_dialog_confirms, cargo:menu_rows_ask_the_session_manager_like_system_actions, cargo:countdown_steps_by_ten_until_the_last_ten_seconds_like_gnome, proof:G-END-SESSION-USERS, proof:G-END-SESSION-REALNAME, proof:G-END-SESSION-BATTERY, proof:G-END-SESSION-BOOT-OPTIONS, proof:G-END-SESSION-ASYNC, cargo:other_sessions_are_filtered_and_titled_like_gnome_51, cargo:log_out_names_the_user_by_real_name_like_gnome_51, cargo:low_battery_warning_follows_gnome_51, cargo:offline_updates_shape_the_dialog_like_gnome_51, cargo:boot_options_need_logind_yes_or_challenge | quick-settings power menu (`crates/shell-gtk/src/power.rs`) that, as GNOME Shell 51's `systemActions.js`, asks `org.gnome.SessionManager` (the compositor's `crates/compositor/src/session_manager.rs`, or gnome-session where it runs) for `Suspend`, `Reboot`, `Shutdown` and `Logout(0)`; the manager suspends through logind's `SuspendWithFlags(SD_LOGIND_SKIP_INHIBITORS)` and routes the rest as gnome-session 51 does (`disable-log-out` → `LockedDown`, `logout-prompt`, logout inhibitors, logout modes) into the shell's `org.gnome.SessionManager.EndSessionDialog` (Open types 0/1/2, `Close`, `Confirmed*`/`Canceled`/`Closed`): GNOME's 60 s countdown shown in its ten-second steps, the applications holding logout inhibitors listed under "Some applications are busy or have unsaved work" (services and non-logout inhibitors left out), Cancel and Escape; for Restart and Power Off the other users' logind sessions under "Other users are logged in" (greeter, closing and this session left out, at most five, graphical ones by user name and console/remote ones by AccountsService real name, as GNOME 51 titles them); Log Out's title and countdown name the user by AccountsService's real name (an empty `RealName` falls back to the user name, and without AccountsService the plain "Log Out" strings stay); with gnome-software's `org.gnome.Software.OfflineUpdates` reporting an update prepared or scheduled, Restart and Power Off offer "Install pending software updates" (checked unless the battery is low; confirming sets gnome-software's post-update action, a Power Off it accepts reboots to install, and unchecking cancels the update), a scheduled one turns a Restart into GNOME's type-3 "Restart & Install Updates", and UPower's DisplayDevice discharging below 30 % shows "Low battery power: please plug in before installing updates" while updates are to install, live as the battery changes; where logind's `CanRebootToBootLoaderMenu` answers `yes`/`challenge`, holding Alt swaps Restart for "Boot Options", which sets `SetRebootToBootLoaderMenu(60 s)` before confirming the reboot. The manager, never the shell, carries the confirmation out (logind `PowerOff(true)`/`Reboot(true)`, a shutdown the shell promoted to a reboot reboots, Log Out ends the compositor, the session leader, through its orderly shutdown as gnome-session's exit ends a GNOME session); Shutdown/Reboot answer with the dialog's outcome, Logout once it opens, and a newer request supersedes an older one still waiting (private-bus tests). The GTK proof drives the hardware menu against the compositor's manager and a logind stub on a private system bus that records the calling process: G-END-SESSION-RESTART/-POWEROFF/-LOGOUT see each row reach the manager (dbus-monitor), `Open(type, 0, 60, [inhibitor])`, the listed inhibiting app, the countdown stepping 60 → 50, Cancel leaving the session and logind untouched with the request failed as cancelled, Restart and Power Off reaching logind from the manager's process, and Log Out (last) ending the compositor gracefully; with the stub's sessions, AccountsService and UPower and a gnome-software stub, G-END-SESSION-USERS, -REALNAME, -BATTERY and -BOOT-OPTIONS see the sessions section, the real name and its fallback, the update box, warning and Restart & Install Updates (hiding once charging, none without updates), and Alt's Boot Options reaching logind from the shell before the manager's Reboot; Suspend reaches logind from the manager and locks on PrepareForSleep (G-SUSPEND-LOCK). The nested preview offers Log Out only, through its own compositor's manager or, inside a host desktop, a local dialog that ends only this compositor. Recorded against GNOME 51 in `docs/gnome-parity.md` (Log Out dialog 0.4% off); on the Marlin image built in CI run 38878636595 (and the published image, nightly 38844351544) logind suspends to a real QEMU S3 state and resumes locked (V-SUSPEND), and Log Out returns to the display manager's greeter (V-LOGOUT; GDM in the current-build lanes since CI run 40977772289; the current-build lane logs out from the shell's power menu by physical keys: Log Out… reaches the compositor's manager as `Logout(0)`, its dialog opens counting down from 60 with Cancel focused, and the session ends only once the countdown confirms); in the same lane Restart… and Power Off… from the menu open `Open(2, 0, 60, …)` and `Open(1, 0, 60, …)`, step to 50 with the VM, session and logind untouched, and Return on the focused Cancel fails the request as cancelled (V-RESTART-DIALOG, V-POWER-OFF-DIALOG). Log Out ends the compositor instead of calling logind's `Session.Terminate`: Terminate also signalled GDM's session worker, whose switch back to the login VT logind's VT restore could cancel, leaving no greeter (published nightly runs 40883859027, 40940329310); gsd-media-keys' power key under `power-button-action` interactive reaches the dialog in the Marlin VM (V-POWER-BUTTON) | V-SUSPEND calls logind rather than pressing the menu; a confirmed restart or power off reaches only the logind stub (the installed image cancels both dialogs); no physical hardware (#68). Offline updates, sessions, AccountsService, the battery and the boot loader menu run only against stubs (Marlin ships no gnome-software offline updates); session avatars show AccountsService's `IconFile` or the default avatar, without GNOME's per-user live updates; the Log Out real name is read per dialog rather than followed live. The session manager has no client registration, so no `QueryEndSession` client is asked before the dialog | | P-SY-05 | Screen capture and sharing through portals with consent | partial | proof:G-SCREENSHOT-DENY, proof:G-CAPTURE-DENY, proof:G-CAPTURE-LOCKED, proof:G-CAPTURE-REVOKE, proof:G-CAPTURE-LOCK-REVOKE, proof:G-PORTAL-CONSENT, proof:G-PORTAL-LOCKED, proof:G-SCREENSHOT-BUTTON, proof:G-SCREENSHOT-UI, proof:G-SCREENSHOT-KEYS, cargo:exclusive_overlay_receives_navigation_and_retains_popup_system_accelerators, cargo:exclusive_overview_keeps_overview_accelerators, proof:G-SCREENSHOT-UI-WINDOW, proof:G-SCREENCAST-UI, proof:G-SCREENCAST-DBUS, cargo:lock_admission_fails_closed_and_updates, cargo:sessions_are_owned_by_the_unique_creator_and_revoke_permanently, cargo:arbitrary_process_cannot_be_the_installed_portal, cargo:paths_follow_gnome, cargo:window_properties_follow_gnome_shell, cargo:the_window_selector_leaves_room_for_the_panel, cargo:the_window_selector_reads_the_compositors_answer, cargo:record_areas_land_on_their_monitor, cargo:areas_crop_out_of_frames, cargo:the_pipeline_is_gnomes_software_vp8, cargo:an_admitted_caller_reads_sandboxed_apps_and_windows_through_org_gnome_shell, cargo:an_unadmitted_caller_is_denied_through_org_gnome_shell, cargo:a_locked_session_denies_the_list_through_org_gnome_shell, cargo:compositor_change_signals_reach_subscribers_on_org_gnome_shell, proof:V-PORTAL, proof:V-PORTAL-GNOME, proof:V-PORTAL-SCREENSHOT, proof:V-PORTAL-SCREENCAST, proof:G-INTROSPECT-SIZE, proof:G-INTROSPECT-TYPES, cargo:a_wedged_bus_never_blocks_the_emitting_thread, cargo:emissions_arrive_in_submission_order, cargo:owner_checks_are_bounded_and_fail_closed_on_a_wedged_bus, cargo:publishing_never_waits_on_a_wedged_bus, cargo:queued_publication_arrives_in_order | screenshots of the screen or the focused window (org.gnome.Shell.Screenshot), monitor, area and window screen casts (org.gnome.Mutter.ScreenCast with RecordArea and DisplayConfig, PipeWire), and the portal's window list (org.gnome.Shell.Introspect, portal callers only) — what xdg-desktop-portal-gnome calls, niri's shape; as in GNOME 51 the Introspect object also answers under `org.gnome.Shell`, where the portal's Background implementation reads running apps and `sandboxed-app-id` (the GTK shell relays it; the compositor admits the original caller with the same rule, #410); the screenshot UI's window selector (the active workspace's windows spread as in the overview, the chosen one ringed in the accent color, saved alone at full size); screen recording from the UI's video switch through org.gnome.Shell.Screencast (GNOME's software VP8/WebM pipeline into Videos/Screencasts) with the red panel indicator that stops it; on the Marlin image built in CI run 38878636595 (and the published image, nightly 38844351544) the portal frontend, the GNOME backend and the Screenshot/ScreenCast interfaces routed by `tuna-portals.conf` answer on the user bus on 5/5 boots (V-PORTAL*; availability only, not a consent flow), and that run's portal-security and remote-security jobs repeat the genuine GNOME 51 Screenshot/ScreenCast/RemoteDesktop consent, lock and revoke flows; ScreenCast stream/close signals and Introspect change signals leave the event loop through an ordered queue, as GDBus emission does, so a bus that stops reading cannot stall frames or input, and a bus that stops answering revokes capture owners within 5 s (fail closed) instead of stalling the revocation scan (#657) | [Qualified packaged evidence](https://github.com/tuna-os/tuna-desktop/blob/main/docs/capture-evidence.json) records all sixteen current-head gates and genuine GNOME 51 Screenshot Deny/Allow/locked completion, ScreenCast consent/frame/Close/disconnect/lock and independent libei Remote keyboard/pointer delivery; #61 acceptance is complete, while Remote touch/keysym/text/clipboard, EIS snapshot refresh and interactive portal screenshot area/color remain unsupported; the installed GNOME backend native-display bootstrap and its retained pre-picker failure are documented in [portal-service-channel.md](https://github.com/tuna-os/tuna-desktop/blob/main/docs/portal-service-channel.md); [Screenshot consent and locked completion](https://github.com/tuna-os/tuna-desktop/blob/main/docs/portal-screenshot-consent.md) use GNOME capture with GTK Access UI; admission now requires the supervised shell or root-owned installed GNOME portal executable plus its unique bus identity, sessions belong to their creator, and disconnect/lock revoke streaming; the Background portal's `org.gnome.Shell` path is covered on a private bus with the real relay and service, while its installed-portal VM qualification (Background.GetAppState) is pending (#410); dmabuf zero-copy and cursor metadata are missing, so neither casts nor recordings show the pointer (nor does the UI's Show Pointer); recordings run GStreamer through gst-launch-1.0 rather than in-process, without GNOME's hardware-encoder pipelines; the window selector shows every window on the primary monitor rather than one selector per monitor (#61) | @@ -77,7 +77,7 @@ rationale and owner), `untested`. | P-ST-09 | Apps panel: permissions, background apps, global shortcuts, default handlers and removable-media autorun | partial | proof:G-SHORTCUT-CONSENT, cargo:shortcut_consent_cannot_survive_a_lock_or_focus_change, cargo:buttons_escape_and_close_map_to_gnome_responses, cargo:missing_or_malformed_store_data_asks_and_never_grants, cargo:each_request_is_answered_once_and_superseded_ones_never, cargo:only_remembered_answers_for_known_apps_are_saved, cargo:automount_mounts_a_hotplugged_volume_with_the_mount_operation, cargo:automount_refuses_inactive_inhibited_mounted_and_locked, cargo:unlock_mounts_waiting_volumes_without_autorun, cargo:autorun_follows_the_first_content_types_setting, cargo:autorun_never_and_unallowed_mounts_do_nothing, cargo:wrong_passphrases_ask_again_other_failures_do_not, cargo:sniffer_counts_a_real_directory_tree, proof:V-INTROSPECT-SANDBOX | Shortcut-inhibit requests need consent and the decision persists per app in PermissionStore (G-SHORTCUT-CONSENT). The Background portal reads a sandboxed Flatpak app's state through Introspect on a Marlin VM (V-INTROSPECT-SANDBOX). The GTK shell now carries GNOME Shell 51's automount/autorun components (`media-handling` consumer, passphrase prompt, in-process hotplug sniffer; unit-tested with fake volumes). Corral VM on the published Marlin image (2026-10-30): shipped build leaves a hotplugged volume unmounted (no consumer, no org.gnome.SessionManager in that build); the Background portal honours PermissionStore yes/no; GlobalShortcuts CreateSession/BindShortcuts/ListShortcuts work through GNOME Settings' provider; the shipped (2026-10-15) build missed the chord's Activated, while this candidate sideloaded on the same image delivers Activated and Deactivated to a sandboxed client through xdg-desktop-portal-gnome's GrabAccelerators path. The candidate sideloaded on the published image (`bootc usroverlay`) mounts a hotplugged removable volume and posts the "connected" notification whose Open with Files action opens it, mounts silently under `autorun-never`, leaves the volume unmounted while an automount inhibitor is held, defers a lock-time plug to unlock without autorun, and re-asks a wrong LUKS2 passphrase in the same dialog; Settings > Default Apps switching changes `xdg-mime` and the shell's open path follows it. GNOME Settings' per-app list is empty on the image (libmalcontent without the malcontent package, a tunaOS image packaging gap), so per-app permission toggles are unqualified. Remaining: per-app permissions through Settings, `org.gtk.MountOperationHandler`, the candidate in a published image, and physical USB/optical media ([#361](https://github.com/tuna-os/tuna-desktop/issues/361)) | — | | P-ST-10 | Service-backed Settings panels (network, Bluetooth, online accounts, printers, sharing, users, region, updates) on the shipped image | partial | proof:G-QS-PRINTERS, proof:G-QS-PRINTERS-ABSENT, cargo:client_lists_printers_over_http, cargo:client_lists_jobs_and_cancels, cargo:tile_subtitle_names_queue_printer_or_absence, cargo:row_label_names_printer_status_and_jobs, proof:G-QS-WWAN, proof:G-QS-WWAN-ABSENT, proof:G-QS-LOCATION, proof:G-QS-LOCATION-ABSENT | Printers: the quick-settings Printers tile and menu list the live CUPS queue over IPP, and the queue window shows GNOME's printer rows, jobs and actions, with Cancel and Test Page reaching the print server; with no print server the tile and menu say No Print Service (`crates/shell-gtk/src/printers.rs`, nested proof against a CUPS stub). Mobile broadband and location services run against live service shapes in the nested proof: the Mobile Network menu reads modems through NetworkManager `Udi` and ModemManager `Modem3gpp` (operator, signal, APN) and its tile flips `WwanEnabled`; the shell's GeoClue2 agent registers, `InUse` drives the panel indicator, and `AuthorizeApp` answers from the permission store under the Settings-owned switch and `max-accuracy-level` ceiling with first-use consent; without ModemManager or GeoClue the tile and indicator hide and grants stay gated (`crates/shell-gtk/src/wwan.rs`, `location.rs`). Network, Bluetooth, online accounts, sharing, users, region and updates panels on Marlin, printer discovery/add through cups-pk-helper, physical modem proof and GeoClue agent whitelisting/packaging on TunaOS remain unqualified ([#362](https://github.com/tuna-os/tuna-desktop/issues/362)) | — | | P-ST-11 | Legacy and app-owned GNOME settings are classified without false parity claims | partial | | Every one of the 428 desktop keys names its GNOME 51 enforcing owner in the [inventory](https://github.com/tuna-os/tuna-desktop/blob/main/docs/settings-desktop-inventory.md): 253 implemented (each citing a gate or cargo test that exists), 26 toolkit, 38 app-owned, 51 deprecated, 60 unimplemented (each linking an issue); `scripts/tuna-settings-inventory-check` and `scripts/lib/settings-inventory-check-tests.py` enforce categories, citations, id existence and that keys gnome-control-center 51.0 writes carry an observable gate or an open issue. Stale `Ignored` rows corrected (locate-pointer, switch-panels, bells, per-app notifications, tablets, background gradients, document/monospace/font-rendering). Key-count coverage is not behaviour coverage: 32 GNOME-Settings-exposed implemented keys still have only consumer tests (listed as `observable proof pending`), and 60 keys are unimplemented ([#365](https://github.com/tuna-os/tuna-desktop/issues/365)) | — | -| P-LK-02 | Authentication beyond one password: fingerprint, smartcard/PIN, multi-step and web login on the lock screen | partial | cargo:actual_main_runtime_pam_conversation_relay, cargo:three_failed_scans_end_failed_like_pam_fprintd_max_tries, cargo:a_retry_then_match_reports_pam_fprintd_messages, cargo:timeouts_and_daemon_failures_end_unavailable_never_matched, cargo:interactive_attempt_reports_armed_and_retry_then_matches, cargo:interactive_cancel_ends_the_attempt_and_frees_the_claim, cargo:auth_conversation_is_appended_and_round_trips, cargo:answer_frames_match_the_generic_encoding_and_never_debug_the_answer, proof:G-LOCK-AUTH-MULTISTEP, proof:G-LOCK-AUTH-WRONG-CODE, proof:G-LOCK-AUTH-CANCEL, proof:G-LOCK-AUTH-FPRINT, proof:G-LOCK-AUTH-FPRINT-MAXTRIES, proof:G-LOCK-AUTH-NO-PRINTS | The lock screen runs GNOME 51's AuthPrompt flow (`crates/shell-gtk/src/lock.rs`, `lock_auth.rs`) over shell protocol 0.44 against a GDM-UserVerifier-shaped compositor consumer (`crates/compositor/src/runtime/auth.rs`, [lock-conversations.md](https://github.com/tuna-os/tuna-desktop/blob/main/docs/security/lock-conversations.md)): every PAM prompt of the `tuna-lock` stack is relayed one question at a time (password, then a code or PIN, with Info/Error messages shown and announced, Back from step 2 soft-resets), and fingerprint runs beside it as pam_fprintd does for `gdm-fingerprint` (fprintd D-Bus, 3 scans, GNOME's hint and messages). Nested-only and emulated (ADR 0008): the controlled multi-prompt PAM module in the actual runtime, and the GTK proof `scripts/tuna-lock-auth-proof` with pam_wrapper (pam_matrix + one-time code) and a mock fprintd; no reader hardware, no installed published-image stack. Smartcard/PIN-pad (pam_pkcs11/pam_sss, GNOME's smartcard mechanism and auth menu) and web login (GDM `eidp`) have no code; greetd sessions keep the single-password `Unlock` ([#366](https://github.com/tuna-os/tuna-desktop/issues/366)) | — | +| P-LK-02 | Authentication beyond one password: fingerprint, smartcard/PIN, multi-step and web login on the lock screen | partial | cargo:actual_main_runtime_pam_conversation_relay, cargo:actual_main_runtime_fingerprint_through_pam, cargo:actual_main_runtime_fingerprint_setting_enforced, cargo:private_pam_helper_actual_binary_conversation_and_retirement, cargo:capability_reports_enrollment_and_scan_type, cargo:auth_conversation_is_appended_and_round_trips, cargo:answer_frames_match_the_generic_encoding_and_never_debug_the_answer, proof:G-LOCK-AUTH-MULTISTEP, proof:G-LOCK-AUTH-WRONG-CODE, proof:G-LOCK-AUTH-CANCEL, proof:G-LOCK-AUTH-FPRINT, proof:G-LOCK-AUTH-FPRINT-EXPIRED, proof:G-LOCK-AUTH-FPRINT-MAXTRIES, proof:G-LOCK-AUTH-NO-PRINTS | The lock screen runs GNOME 51's AuthPrompt flow (`crates/shell-gtk/src/lock.rs`, `lock_auth.rs`) over shell protocol 0.44 against a GDM-UserVerifier-shaped compositor consumer (`crates/compositor/src/runtime/auth.rs`, [lock-conversations.md](https://github.com/tuna-os/tuna-desktop/blob/main/docs/security/lock-conversations.md)): every PAM prompt of the `tuna-lock` stack is relayed one question at a time (password, then a code or PIN, with Info/Error messages shown and announced, Back from step 2 soft-resets), and fingerprint runs beside it as its own PAM service, `tuna-lock-fingerprint` (`share/pam.d/tuna-lock-fingerprint`: pam_fprintd plus login's account stack, as GDM runs `gdm-fingerprint`; 3 scans, GNOME's hint and messages, GDM's max-tries and expired-account messages). The compositor enforces `org.gnome.login-screen enable-fingerprint-authentication` and admits three failed fingerprint conversations per lock (#1162 F5). Nested-only and emulated (ADR 0008): controlled PAM modules (multi-prompt; pam_fprintd-like with an expirable account) in the actual runtime, and the GTK proof `scripts/tuna-lock-auth-proof` with pam_wrapper (pam_matrix + one-time code; a pam_fprintd stand-in) and a mock fprintd; no reader hardware, no installed pam_fprintd or published-image stack. Smartcard/PIN-pad (pam_pkcs11/pam_sss, GNOME's smartcard mechanism and auth menu) and web login (GDM `eidp`) have no code ([#366](https://github.com/tuna-os/tuna-desktop/issues/366)) | — | | P-LK-03 | The login screen is Tuna Desktop's own greeter on GDM's daemon, matching GDM 51's login screen: user list, password, fingerprint, smartcard and multi-step auth, accessibility and input sources before login, user switching and GDM policy keys | missing | | Added to v1 by the owner on 2026-11-16 ([ADR 0008](https://github.com/tuna-os/tuna-desktop/blob/main/docs/adr/0008-v1-beta-track-and-release-scope.md) item 6, epic [#1164](https://github.com/tuna-os/tuna-desktop/issues/1164)). GNOME 51: gdm's greeter is `gnome-shell --mode=gdm` (`js/gdm/loginDialog.js`, `authPrompt.js`, `util.js` over libgdm's `GdmClient`/`UserVerifier`/`Greeter`), started as `org.gnome.Shell@gdm.service` in `gnome-session@gnome-login.target`. Every image still logs in through that GNOME Shell greeter (V-GREETER-LIST, V-GDM-LOGIN). The lock screen's AuthPrompt flow (P-LK-02) is the starting point for the greeter's authentication UI | — | | P-AN-01 | Motion preferences: animations off is instant, reduced motion keeps fades only, slow-down factor scales durations | partial | proof:G-ANIMATIONS-OFF, proof:G-INTROSPECT-MOTION, proof:G-ANIMATION-CLOCK, proof:G-TRANSIENT-OFF, cargo:transient::tests::the_motion_policy_gates_fades_and_motion, cargo:transient::tests::reduced_motion_keeps_only_the_fade | A shared full / fade-only / off policy with the slow-down factor drives shell and compositor animations, shell transients included (G-TRANSIENT-OFF), and a deterministic animation clock samples them at fixed delays (#523); paired GNOME 51 captures at the same delays are still missing ([#493](https://github.com/tuna-os/tuna-desktop/issues/493), epic [#492](https://github.com/tuna-os/tuna-desktop/issues/492)) | — | | P-AN-02 | Window open and close animations (150 ms map/destroy, 100 ms attached dialogs) | partial | cargo:gnome51_normal_map_pivot_and_exponential_curve, cargo:destroy_and_attached_dialog_follow_quad, cargo:reduced_motion_and_slowdown, cargo:animations_off_land_without_scale_or_fade, cargo:keyboard_workspace_slide_suppresses_lifecycle_and_resume_does_not_replay_map, cargo:interrupted_map_and_size_change_close_skip_raw_snapshot, cargo:expired_ghosts_release_budget_before_new_close | Wired native map/destroy rendering and bounded retained textures; slides and interrupted map/resize close suppress effects. Paired GNOME/native GPU, X11 runtime, shadow/popup geometry and snapshot-budget overflow remain unqualified ([#494](https://github.com/tuna-os/tuna-desktop/issues/494)); see [implementation scope](https://github.com/tuna-os/tuna-desktop/blob/main/docs/window-lifecycle.md). | — | @@ -88,7 +88,7 @@ rationale and owner), `untested`. | P-AN-07 | Overview transitions: open/close easing, gesture momentum, picker and app grid, hover, thumbnails, drag, search, dash and panel | partial | proof:G-OVERVIEW-EASING, proof:G-OV-APPGRID, proof:G-DASH-MOTION, cargo:swipe_release_projects_velocity_like_gnome, cargo:the_app_grid_swap_morphs_out_sine_over_250_ms, cargo:hover_grows_over_200_ms_out_quad, cargo:drags_shrink_then_snap_back_or_revert_like_gnome, cargo:search_fades_the_workspaces_over_250_ms, cargo:dash_motion::tests::gnome_51_dash_durations, cargo:dash_motion::tests::items_zoom_and_fade_in_and_out_over_200_ms_ease_out_quad, cargo:dash_motion::tests::an_item_removed_while_zooming_in_shrinks_back_from_where_it_stands, cargo:dash_motion::tests::reduced_motion_keeps_the_fade_at_full_size_and_off_lands_at_once, cargo:dash_motion::tests::labels_fade_in_over_150_ms_and_out_over_100_ms_from_where_they_stand, cargo:dash_motion::tests::the_slow_down_factor_stretches_dash_motion | Overview opening uses out-sine and closing out-quad; swipe release carries momentum; picker/app-grid morph, workspace scroll, thumbnail growth, hover, drag and search transitions are implemented (`crates/compositor/src/overview.rs`). Nested proof samples open/close easing and Show Apps; unit tests cover the remaining curves. The dash follows gnome-shell 51 dash.js (`crates/shell-gtk/src/dash_motion.rs`, `overview.rs`): items persist across redisplays; an app joining zooms and fades in and one leaving zooms and fades out over `DASH_ANIMATION_TIME` 200 ms ease-out-quad with its size following its scale (`DashItemContainer.show`/`animateOutAndDestroy`, :154-185, :82-98), not on the overview's initial fill (:784-798); the hovered item's label (GNOME's `dash-label` pill, 8 px above it) fades in over 150 ms after `DASH_ITEM_HOVER_TIMEOUT` 300 ms (at once while labels are showing) and out over 100 ms, hidden on click and when the overview hides (:100-141, :483-571); like GNOME's chrome St.Label it is a plain label to assistive technology while the item's button keeps the accessible name; the separator shows only between favorites and other apps (`nFavorites > 0`, :809-835). G-DASH-MOTION samples item add/remove, a removal mid-add, the label fade in and out, Reduced Motion and animations off on the frozen proof clock. Deviations under the shared motion policy and interruption rule: Reduced Motion keeps items at full size while they fade (GNOME 51's dash.js does not consult reduced-motion); a label shown again while fading out fades in from its drawn opacity where `showLabel` restarts from 0; an app re-added while animating out zooms back in where GNOME's `_redisplay` lets it finish leaving; a redisplay during the overview's own open/close animation still animates (GNOME checks `animationInProgress`). Not implemented: `_adjustIconSize` (the dash keeps 64 px icons, so no icon-size animation), drag-and-drop placeholders and the window-drag dash fade. Paired GNOME 51 intermediate-frame/gesture captures and panel transition qualification remain missing ([#499](https://github.com/tuna-os/tuna-desktop/issues/499)) | — | | P-AN-08 | App grid animations: folder zoom, launch zoom, page switch curve, swipe settle, page dots and page arrows (GNOME 51 defines AppIcon.scaleIn() but never calls it, so new icons do not scale in) | partial | proof:G-GRID-PAGE-ANIM, proof:G-FOLDER-ZOOM, proof:G-LAUNCH-ZOOM, proof:G-GRID-ACTIVATE-RUNNING, proof:G-GRID-FADE, proof:G-GRID-PAGE-PEEK, cargo:grid_animation::tests::curves_match_clutter_easing_modes, cargo:grid_animation::tests::gnome_51_durations, cargo:grid_animation::tests::reduced_motion_keeps_fades_and_off_keeps_nothing, cargo:grid_animation::tests::slow_down_factor_stretches_durations_and_delays, cargo:grid_animation::tests::folder_dialog_zooms_from_its_icon, cargo:grid_animation::tests::launch_zoom_triples_and_stays_on_the_monitor, cargo:grid_animation::tests::page_switch_eases_out_cubic_over_300_ms, cargo:grid_animation::tests::page_dots_follow_the_drawn_position, cargo:grid_animation::tests::swipe_history_keeps_150_ms_of_moves, cargo:grid_animation::tests::a_swipe_goes_at_most_a_page_past_where_it_began, cargo:grid_animation::tests::released_swipes_settle_as_gnome_swipe_tracker, cargo:the_plan_follows_app_icon_activate, cargo:a_stopped_app_launches_with_the_zoom_even_with_ctrl, cargo:exact_running_app_activates_before_close_without_spawning_or_zooming, cargo:ctrl_or_middle_on_a_running_app_opens_a_new_window_with_the_zoom, cargo:ctrl_on_a_running_single_main_window_app_raises_it, cargo:failed_spawn_keeps_overview_open_without_the_zoom, cargo:can_open_new_window_reads_the_desktop_file_like_shell_app, cargo:the_new_window_action_is_parsed_like_exec, cargo:open_new_window_runs_the_action_else_launches_again | Matched to gnome-shell 51.0 appDisplay.js, iconGrid.js, pageIndicators.js and swipeTracker.js (`crates/shell-gtk/src/grid_animation.rs`, `grid_pager.rs`, `folder_dialog.rs`, `overview.rs`). The folder dialog zooms 200 ms ease-out-expo out of its icon and back with the shade and icon fades (G-FOLDER-ZOOM, incl. animations-off and Reduced Motion). Grid, folder, dash and search result tiles share GNOME's `AppIcon.activate` (appDisplay.js:3053-3071; primary and middle button, :1854): a stopped app launches and its tile's last drawn icon (and label, in the grid) grows 3× while fading over 250 ms ease-out-quad, kept on the monitor (G-LAUNCH-ZOOM, from a folder); a running app's window is raised with no launch and no zoom (G-GRID-ACTIVATE-RUNNING clicks a running app's grid tile: its window takes focus, no new window, no relaunch, no zoom surface); Ctrl+click or a middle click on a running app opens a new window with the zoom when `shell_app_can_open_new_window` (src/shell-app.c:631-700) allows it from the desktop file (`SingleMainWindow`, then `X-GNOME-SingleWindow`, then a `new-window` desktop action, else yes), through the `new-window` desktop action or a relaunch (`shell_app_open_new_window`, :574-623; G-GRID-ACTIVATE-RUNNING Ctrl+clicks for the relaunch and its zoom). The dash zoom has no CI gate because the proof's dash favorites are fixed at shell start. goToPage eases 300 ms out-cubic from wherever the pages are drawn; G-GRID-PAGE-ANIM checks every animated frame's GDK frame-clock sample against GNOME's curve and every page-dot update against pageIndicators.js, and that animations off jump. Arrows fade 200 ms; swipes settle on SwipeTracker's projected page and duration (unit-tested only, no CI swipe gate). Not frozen-clock: GTK shell animations run on the GDK frame clock, not `TUNA_ANIMATION_CLOCK`. Reduced Motion keeps only fades per Tuna's shared motion policy (GNOME 51's appDisplay.js does not consult reduced-motion). Not matched in activation, for want of what ShellApp tracks: a running app's exported `app.new-window` D-Bus action and the unique-GtkApplication test are not asked (such apps count as able to open a window), and bus activation of `app.new-window` and of DBusActivatable apps is not used (Tuna runs the `Exec` lines); `shell_app_activate_window` raises the app's most recently used window (and its other windows on that workspace) where Tuna raises its lowest-id window; GNOME's STARTING state (a click on a launched app with no window yet does nothing) is not tracked, so it launches again; a failed launch keeps the overview open where GNOME hides it and notifies. Paired GNOME 51 clips are missing ([#500](https://github.com/tuna-os/tuna-desktop/issues/500)) | — | | P-AN-09 | Menus, quick-settings submenus, OSD, notification banners and list, Alt+Tab, modal dialogs and lightbox | partial | proof:G-SWITCHER-FADE, proof:G-TRANSIENT-SETTLE, proof:G-TRANSIENT-OFF, cargo:transient::tests::gnome_51_durations, cargo:transient::tests::banners_drop_in_scaled_and_slide_back_up, cargo:transient::tests::list_items_zoom_in_and_out, cargo:transient::tests::submenus_grow_then_fade_and_fade_then_shrink, cargo:transient::tests::fades_ease_out_quad_from_where_they_stand, cargo:transient::tests::easing_curves_match_clutter, cargo:transient::tests::progress_is_linear_and_instant_when_animations_are_off, cargo:transient::tests::panel_menus_fade_rise_and_grow_open, cargo:transient::tests::a_menu_taking_over_from_another_opens_fade_only, cargo:menu_close::tests::closes_with_gnome_51_boxpointer_curve, cargo:menu_close::tests::fade_only_and_reduced_motion_drop_the_rise, cargo:menu_close::tests::shrinks_about_the_top_centre_and_rises, proof:G-TRANSIENT-CLOSE-CLOCK, proof:G-NM-WIRED, cargo:transient::tests::ease_out_expo_matches_clutter, cargo:transient::tests::popup_submenus_grow_and_turn_their_arrow_over_250_ms_out_expo, cargo:transient::tests::a_reversed_popup_submenu_starts_from_its_drawn_frame, cargo:transient::tests::popup_submenus_skip_the_animation_when_the_menu_scrolls, cargo:transient::tests::popup_submenus_keep_their_motion_under_reduced_motion, cargo:transient::tests::menus_close_as_boxpointer_from_where_they_stand, cargo:transient::tests::a_hidden_buttons_menu_closes_unanimated, cargo:transient::gtk_menu_tests::actual_gtk_popup_submenus_ease_open_and_closed, cargo:transient::gtk_menu_tests::actual_gtk_menus_close_at_once_and_switch_fade_only, cargo:menu_close::tests::a_hidden_buttons_close_pairs_whichever_arrives_first, cargo:menu_close::tests::an_unanimated_request_waits_for_its_popup_and_is_recorded, cargo:runtime::tests::switcher_thumbnails_draw_their_window_at_the_frames_opacity, cargo:switcher::tests::window_images_take_their_frames_opacity_as_clutter_does, cargo:switcher_fade_and_menu_close_wire_tests::switcher_thumbnail_opacity_rides_last_and_round_trips, cargo:switcher_fade_and_menu_close_wire_tests::close_menu_unanimated_follows_pad_osd_closed, cargo:control::switcher_thumbnail_tests::a_departed_shell_takes_its_switcher_thumbnails_with_it | Notification groups animate expansion; the Alt+Tab popup fades out, thumbnails fade in/out, and the focused thumbnail strip scrolls over 100 ms ease-out-quad (`crates/shell-gtk/src/switcher.rs`, G-SWITCHER-FADE), and the compositor draws the thumbnails' window images at their frame's opacity (wire `SwitcherThumbnail.opacity`), so they fade in with the strip and out with the popup instead of popping (G-SWITCHER-FADE samples the published alphas at 0/50/100 ms in and 50 ms out on the proof clock); a shell that disconnects, crashes or is replaced while they are drawn takes them with it, and none draw under the lock. The OSD and its level fade over 100 ms, and a show during its fade-out lets the fade-out finish and hide it as `osdWindow.js` does (actual-GTK X11 test in CI), banners drop in and slide out over 200 ms, list items zoom over 100 ms, polkit, end-session and network-secret modals fade with their lightbox over 100 ms, panel menus (date, quick settings, accessibility, tray, input method, dwell) open as GNOME's BoxPointer (fade in, rise 6px and grow from 96% about the top centre over 150 ms ease-out quad; fade-only when taking over from another menu) and close as `BoxPointer.close` drawn by the compositor from the menu's last frame (fade out, rise 6px, shrink to 96%; fade-only on a takeover) while GTK closes them logically, for the accessible tree and input, at once (`crates/compositor/src/menu_close.rs`, G-TRANSIENT-CLOSE-CLOCK samples 0/75/150 ms on the proof clock); a panel button hidden under its open menu closes it unanimated as `PanelMenu.Button.vfunc_hide` does (`panelMenu.js:149-154`; `CloseMenuUnanimated`, G-TRANSIENT-CLOSE-CLOCK hides the Accessibility button) and the menu stays closed when the button returns. The window menu opens with BoxPointer's fade alone and closes with its full close over 150 ms (`windowMenu.js:239`, `crates/shell-gtk/src/window_menu.rs`, G-TRANSIENT-SETTLE). Popup submenus (wired adapters' `NMSectionItem`, IBus property menus) open and close as `PopupSubMenu` (`popupMenu.js:1265-1342`): height and arrow (0→90°, −90° right to left) ease out expo over 250 ms from where they stand, no animation when the menu must scroll, Left closes back to the item, the item carries the expanded state and a labelled group holds item and rows; GNOME animates the height under Reduced Motion too, so only animations off lands it (`crates/shell-gtk/src/transient.rs` `PopupSubmenu`, actual-GTK X11 test in CI; G-NM-WIRED opens a second adapter's submenu but checks its rows, not its frames). Quick-settings submenus grow then fade over 400 ms; Reduced Motion keeps only the fades and animations off lands them at once (`crates/shell-gtk/src/transient.rs`, G-TRANSIENT-SETTLE, G-TRANSIENT-OFF). The menu close is sampled as compositor state rather than pixels, the OSD's fade, level ease and the menu rise are proven by trace timings and unit frames rather than pixel captures, popup submenu frames are proven under X11 GTK only and no proof drives an IBus property submenu, the on-screen keyboard's extended-key and language popups (`keyboard.js:289,1462`, FULL BoxPointer) are still unanimated, the lightbox is the modal window's own background, message-list and lightbox timing are covered by unit tests only, and paired GNOME 51 intermediate-frame captures remain missing ([#501](https://github.com/tuna-os/tuna-desktop/issues/501)) | — | -| P-AN-10 | Lock curtain slide, wallpaper crossfade, screenshot flash, hot-corner ripples, startup and monitor-change transitions | partial | cargo:screenshot_flash::tests::white_then_quarter_opacity_at_half_time_and_absent_at_end, cargo:screenshot_flash::tests::concurrent_feedback_is_bounded_and_lock_clear_is_immediate, cargo:screenshot_flash::tests::disabled_motion_and_invalid_areas_create_no_feedback, proof:G-LOCK-SLIDE, proof:G-STARTUP-REVEAL, proof:G-WALLPAPER-CROSSFADE, proof:G-HOT-CORNER-RIPPLES, proof:G-MONITOR-TRANSITION, cargo:startup_and_monitor_change_fade_on_gnome_timing, cargo:startup_holds_until_the_shell_is_ready_or_the_cap, proof:G-LOCK-CURTAIN-CLOCK, proof:G-LOCK-CURTAIN-POLICY, proof:G-LOCK-CURTAIN-DRAG, proof:G-LOCK-CURTAIN-HINT, proof:G-LOCK-CURTAIN-TOUCHPAD, proof:G-LOCK-SWIPE-SECURITY, cargo:lock_curtain::tests::pages_trade_places_like_unlock_dialog_51, cargo:lock_curtain::tests::reduced_motion_keeps_only_the_fade, cargo:lock_curtain::tests::crossfade_is_300_ms_ease_out_quad_from_the_current_value, cargo:lock_curtain::tests::a_drag_moves_nothing_until_16_px_then_follows_each_event, cargo:lock_curtain::tests::pan_velocity_is_clutters_last_150_ms, cargo:lock_curtain::tests::slow_releases_settle_on_the_nearer_page, cargo:lock_curtain::tests::a_flick_reaches_the_other_page_from_a_short_drag, cargo:lock_curtain::tests::a_cancelled_swipe_returns_to_where_it_began, cargo:lock_curtain::tests::touchpad_releases_use_the_touchpad_thresholds, cargo:lock_curtain::tests::touchpad_history_is_gnomes_event_history, cargo:lock_curtain::tests::touchpad_swipe_follows_gnomes_three_finger_gesture, cargo:lock_curtain::tests::touchpad_scroll_follows_and_the_stop_ends_it, cargo:lock_curtain::tests::the_hint_follows_touch_mode, cargo:lock_curtain::tests::the_hint_fades_in_on_clutters_default_ease_and_hides_at_once, cargo:lock_curtain::gtk_curtain_tests::actual_gtk_curtain_pages_follow_progress_and_policy, cargo:anim_clock::tests::a_file_freezes_steps_and_releases_the_clock, cargo:a_finished_finger_scroll_sends_axis_stop, cargo:lock_surface_alone_hears_touchpad_swipes_and_the_scroll_stop, cargo:hub_broadcasts_seat_touch_mode_changes_and_hands_newcomers_the_value | Idle shield fade and unlock crossfade animate (`crates/compositor/src/lock.rs`); the compositor's curtain lowers on lock and lifts after PAM (`crates/compositor/src/transitions.rs`, G-LOCK-SLIDE). The unlock dialog moves between its clock curtain and prompt on unlockDialog.js 51's single progress (`crates/shell-gtk/src/lock_curtain.rs`): the clock fades, rises 200 px and shrinks toward 30% while the prompt fades in from 200 px below; a key (a printable one becoming the first password character), click, wheel step or Escape eases it over 300 ms ease-out quad, and a vertical pointer drag (touch arrives as the primary button) follows past Clutter's 16 px and settles on swipeTracker.js's velocity projection in 100-400 ms ease-out cubic; Reduced Motion keeps the fade only, animations off switch at once, and the leaving prompt drops focus and is cleared once the clock is back. Touchpad: while locked the compositor hands the lock surface (and nothing else) touchpad swipes as pointer gestures, and every finger scroll's end as `wl_pointer.axis_stop` (mutter meta-seat-impl.c:2254-2277, meta-wayland-pointer.c:927-967; unlocked clients get the stop too); a three-finger swipe under way at lock ends cancelled, so no gesture opens the overview or switches workspace while locked (G-LOCK-SWIPE-SECURITY asserts it from the state document). The dialog follows swipeTracker.js's `TouchpadSwipeGesture` (3+ fingers, 16 px orientation lock, natural-scroll) and `ScrollGesture` (ended by the stop) over `TOUCHPAD_BASE_HEIGHT` with `EventHistory` velocity and the touchpad thresholds; G-LOCK-CURTAIN-TOUCHPAD injects both through the nested swipe-input file and checks each release against GNOME's formulas. The hint is hidden until the IdleMonitor's 4 s `HINT_TIMEOUT` watch fires, then fades in over 300 ms on Clutter's default ease-out cubic; a `PowerSaveMode` change hides it at once; its text follows the seat's touch-mode ("Swipe up" / "Click or press a key", new wire `SeatTouchMode`); G-LOCK-CURTAIN-HINT samples 0/150/300 ms on the frozen clock under full motion and Reduced Motion and checks animations off. The shell samples the compositor's proof clock, so G-LOCK-CURTAIN-CLOCK/-POLICY check frames at exact delays and G-LOCK-CURTAIN-DRAG drives real xdotool drags, a flick and a PAM unlock. Screenshot methods pass their flash request to an output-only white fade (`crates/compositor/src/screenshot_flash.rs`). Wallpaper replacement crossfades over 1000 ms ease-out quad (background.js:119,897-900; `crates/compositor/src/wallpaper.rs`), the hot corner draws ripples.js's three rings, and the startup cover and monitor-change transition (layout.js:21-28 timings, `ScreenTransition`) run in `transitions.rs`; their gates pass on main CI. Not matched: touchpad gestures are proven with nested synthetic input only, never a hardware touchpad; the swipe reaches the lock surface with accelerated deltas (GNOME reads unaccelerated ones); the touch-mode text is unit-tested only (nested sessions have no touchscreen); no auth-mechanism hint, notifications box, auth-method indicator or other-user button; Tuna starts in the overview like GNOME, but its startup is the compositor's black cover fade (GNOME's `!hasOverview` path) instead of overviewControls.js:798-860 `runStartupAnimation` (controls fade in, search falls, dash rises after 500 ms), and the uiGroup 0.75 scale is not drawn; the screenshot-flash pixel proof is not run in CI; paired GNOME frames for every transition are missing ([#502](https://github.com/tuna-os/tuna-desktop/issues/502)) | — | +| P-AN-10 | Lock curtain slide, wallpaper crossfade, screenshot flash, hot-corner ripples, startup and monitor-change transitions | partial | cargo:screenshot_flash::tests::white_then_quarter_opacity_at_half_time_and_absent_at_end, cargo:screenshot_flash::tests::concurrent_feedback_is_bounded_and_lock_clear_is_immediate, cargo:screenshot_flash::tests::disabled_motion_and_invalid_areas_create_no_feedback, proof:G-LOCK-SLIDE, proof:G-STARTUP-REVEAL, proof:G-WALLPAPER-CROSSFADE, proof:G-HOT-CORNER-RIPPLES, proof:G-MONITOR-TRANSITION, cargo:startup_and_monitor_change_fade_on_gnome_timing, cargo:startup_holds_until_the_shell_is_ready_or_the_cap, proof:G-LOCK-CURTAIN-CLOCK, proof:G-LOCK-CURTAIN-POLICY, proof:G-LOCK-CURTAIN-DRAG, proof:G-LOCK-CURTAIN-HINT, proof:G-LOCK-CURTAIN-TOUCHPAD, proof:G-LOCK-SWIPE-SECURITY, cargo:lock_curtain::tests::pages_trade_places_like_unlock_dialog_51, cargo:lock_curtain::tests::reduced_motion_keeps_only_the_fade, cargo:lock_curtain::tests::crossfade_is_300_ms_ease_out_quad_from_the_current_value, cargo:lock_curtain::tests::a_drag_moves_nothing_until_16_px_then_follows_each_event, cargo:lock_curtain::tests::pan_velocity_is_clutters_last_150_ms, cargo:lock_curtain::tests::slow_releases_settle_on_the_nearer_page, cargo:lock_curtain::tests::a_flick_reaches_the_other_page_from_a_short_drag, cargo:lock_curtain::tests::a_cancelled_swipe_returns_to_where_it_began, cargo:lock_curtain::tests::touchpad_releases_use_the_touchpad_thresholds, cargo:lock_curtain::tests::touchpad_history_is_gnomes_event_history, cargo:lock_curtain::tests::touchpad_swipe_follows_gnomes_three_finger_gesture, cargo:lock_curtain::tests::touchpad_scroll_follows_and_the_stop_ends_it, cargo:lock_curtain::tests::the_hint_follows_touch_mode, cargo:lock_curtain::tests::the_hint_fades_in_on_clutters_default_ease_and_hides_at_once, cargo:lock_curtain::gtk_curtain_tests::actual_gtk_curtain_pages_follow_progress_and_policy, cargo:anim_clock::tests::a_file_freezes_steps_and_releases_the_clock, cargo:a_finished_finger_scroll_sends_axis_stop, cargo:lock_surface_alone_hears_touchpad_swipes_and_the_scroll_stop, cargo:hub_broadcasts_seat_touch_mode_changes_and_hands_newcomers_the_value, cargo:transitions::tests::the_lock_screen_is_shown_only_once_the_curtain_lands, cargo:hub_broadcasts_lock_screen_shown_and_hands_newcomers_the_value, cargo:control::tests::lock_screen_shown_needs_the_lock_and_its_own_landing, cargo:screensaver::tests::active_follows_the_shown_lock_screen, cargo:screensaver::tests::every_confirmed_unlock_wakes_the_screen_first | Idle shield fade and unlock crossfade animate (`crates/compositor/src/lock.rs`); the compositor's curtain lowers on lock and lifts after PAM (`crates/compositor/src/transitions.rs`, G-LOCK-SLIDE). As in screenShield.js `_lockScreenShown`, `org.gnome.ScreenSaver` goes active (GetActive, `ActiveChanged(true)`, `Lock` returning) only once the curtain has landed (new wire `LockScreenShown`), because gnome-settings-daemon blanks the screen on `ActiveChanged(true)`: blanking mid-slide froze the curtain's first frame (clock off screen) on guppy; G-LOCK-SLIDE checks GetActive is false half way down. gnome-settings-daemon unblanks only on input or `WakeUpScreen`, so, as `_continueDeactivate` does, every confirmed unlock emits `WakeUpScreen` before `ActiveChanged(false)`: without it `loginctl unlock-session` after a Super+L blank left the unlocked session dark until the next input (marlin-vm V-ORCA-ACTIVATION froze); G-LOCK-KEY checks the order. The unlock dialog moves between its clock curtain and prompt on unlockDialog.js 51's single progress (`crates/shell-gtk/src/lock_curtain.rs`): the clock fades, rises 200 px and shrinks toward 30% while the prompt fades in from 200 px below; a key (a printable one becoming the first password character), click, wheel step or Escape eases it over 300 ms ease-out quad, and a vertical pointer drag (touch arrives as the primary button) follows past Clutter's 16 px and settles on swipeTracker.js's velocity projection in 100-400 ms ease-out cubic; Reduced Motion keeps the fade only, animations off switch at once, and the leaving prompt drops focus and is cleared once the clock is back. Touchpad: while locked the compositor hands the lock surface (and nothing else) touchpad swipes as pointer gestures, and every finger scroll's end as `wl_pointer.axis_stop` (mutter meta-seat-impl.c:2254-2277, meta-wayland-pointer.c:927-967; unlocked clients get the stop too); a three-finger swipe under way at lock ends cancelled, so no gesture opens the overview or switches workspace while locked (G-LOCK-SWIPE-SECURITY asserts it from the state document). The dialog follows swipeTracker.js's `TouchpadSwipeGesture` (3+ fingers, 16 px orientation lock, natural-scroll) and `ScrollGesture` (ended by the stop) over `TOUCHPAD_BASE_HEIGHT` with `EventHistory` velocity and the touchpad thresholds; G-LOCK-CURTAIN-TOUCHPAD injects both through the nested swipe-input file and checks each release against GNOME's formulas. The hint is hidden until the IdleMonitor's 4 s `HINT_TIMEOUT` watch fires, then fades in over 300 ms on Clutter's default ease-out cubic; a `PowerSaveMode` change hides it at once; its text follows the seat's touch-mode ("Swipe up" / "Click or press a key", new wire `SeatTouchMode`); G-LOCK-CURTAIN-HINT samples 0/150/300 ms on the frozen clock under full motion and Reduced Motion and checks animations off. The shell samples the compositor's proof clock, so G-LOCK-CURTAIN-CLOCK/-POLICY check frames at exact delays and G-LOCK-CURTAIN-DRAG drives real xdotool drags, a flick and a PAM unlock. Screenshot methods pass their flash request to an output-only white fade (`crates/compositor/src/screenshot_flash.rs`). Wallpaper replacement crossfades over 1000 ms ease-out quad (background.js:119,897-900; `crates/compositor/src/wallpaper.rs`), the hot corner draws ripples.js's three rings, and the startup cover and monitor-change transition (layout.js:21-28 timings, `ScreenTransition`) run in `transitions.rs`; their gates pass on main CI. Not matched: touchpad gestures are proven with nested synthetic input only, never a hardware touchpad; the swipe reaches the lock surface with accelerated deltas (GNOME reads unaccelerated ones); the touch-mode text is unit-tested only (nested sessions have no touchscreen); a manual lock goes active as the curtain lands, without GNOME's 300 ms beat and 300 ms short-lightbox fade to black (`MANUAL_FADE_TIME`) before it; no auth-mechanism hint, notifications box, auth-method indicator or other-user button; Tuna starts in the overview like GNOME, but its startup is the compositor's black cover fade (GNOME's `!hasOverview` path) instead of overviewControls.js:798-860 `runStartupAnimation` (controls fade in, search falls, dash rises after 500 ms), and the uiGroup 0.75 scale is not drawn; the screenshot-flash pixel proof is not run in CI; paired GNOME frames for every transition are missing ([#502](https://github.com/tuna-os/tuna-desktop/issues/502)) | — | | P-SY-11 | Clipboard contents stay pasteable after the copying app closes | partial | cargo:clipboard_survives_owner_disconnect, cargo:clipboard_survives_owner_null_selection, cargo:retained_clipboard_keeps_the_most_preferred_type, cargo:new_client_selection_replaces_retained_copy, cargo:unsupported_clipboard_type_is_not_retained | Implemented in #1056 (`crates/compositor/src/clipboard_manager.rs`) following mutter 51 `meta-clipboard-manager.c`: the most preferred supported type is copied (text 4 MiB, images 200 MiB) and served after the owner clears, destroys its source or quits. Proven with real socketpair Wayland clients only; no nested or installed proof with real applications. A RemoteDesktop session's selection is not copied (recorded divergence). ([#1033](https://github.com/tuna-os/tuna-desktop/issues/1033)) | — | | P-WM-10 | X11 windows without their own decorations get a server-side frame | missing | | Untracked until the 2026-11-10 audit (main `8cd7dd75`). GNOME 51: mutter `src/frames/` (mutter-x11-frames). No frame code exists in `crates/compositor/src`; X11 windows are mapped bare (for example `docs/walkthrough/x11.png`). ([#1034](https://github.com/tuna-os/tuna-desktop/issues/1034)) | — | | P-WM-11 | An app that stops responding gets the "not responding" dialog with Force Quit and Wait | partial | cargo:unanswered_ping_shows_the_close_dialog_until_a_late_pong, cargo:answering_window_is_never_reported, cargo:force_quit_disconnects_the_unresponsive_client, cargo:zero_check_alive_timeout_disables_the_check, cargo:lock_hides_the_close_dialog_and_stops_pinging, cargo:strings_match_gnome_shell_51 | Implemented in #1060 (`crates/compositor/src/unresponsive.rs`, `windows/alive.rs`, `crates/shell-gtk/src/close_dialog.rs`, wire 0.50) following mutter 51 ping/`check-alive-timeout` and gnome-shell `closeDialog.js`. X11 windows are not pinged (Smithay 0.7 does not report `_NET_WM_PING` replies); no nested or installed proof with a hung application and no paired GNOME frame. ([#1035](https://github.com/tuna-os/tuna-desktop/issues/1035)) | — | diff --git a/docs/tuna-desktop/performance-profiling.md b/docs/tuna-desktop/performance-profiling.md index 3353409b..5c026195 100644 --- a/docs/tuna-desktop/performance-profiling.md +++ b/docs/tuna-desktop/performance-profiling.md @@ -142,6 +142,7 @@ drawn frame (`FrameCost` in `crates/compositor/src/occlusion.rs`): | `rendered` | Scene elements repainted in that frame | | `culled` | Elements skipped because they are wholly under opaque elements | | `damage_rects`, `damage_area` | Number and total area (physical pixels) of damaged rectangles | +| `damage_bounds` | `[x, y, w, h]` box around the damaged rectangles (output pixels, before rotation), or `null` | | `output_area` | The output's area, for the damage ratio | | `drawn_windows` | Window ids with any element showing on the output, repainted or not | | `culled_windows` | Window ids entirely hidden behind opaque surfaces | diff --git a/docs/tuna-desktop/security-model.md b/docs/tuna-desktop/security-model.md index 8a8ea18c..dcbade20 100644 --- a/docs/tuna-desktop/security-model.md +++ b/docs/tuna-desktop/security-model.md @@ -13,9 +13,11 @@ delivery tier (nested developer preview) is explicitly "not a secure daily-driver session" ([architecture](https://github.com/tuna-os/tuna-desktop/blob/main/docs/architecture.md#delivery-tiers)). The [ADR register](https://github.com/tuna-os/tuna-desktop/blob/main/docs/adr/README.md#decision-register) still lists the same-UID threat model, trusted lock/portal identity and the production lock/auth and -portal/capture grant lifecycle as open 1.0 release blockers. Everything -below describes what the code on `main` does today. Planned behaviour is -labelled **target**. +portal/capture grant lifecycle as 1.0 release blockers. +[ADR 0010](https://github.com/tuna-os/tuna-desktop/blob/main/docs/adr/0010-same-uid-trusted-identity.md) and +[ADR 0011](https://github.com/tuna-os/tuna-desktop/blob/main/docs/adr/0011-lock-auth-and-capture-grant-lifecycle.md) propose them; +the owner has not decided. Everything below describes what the code on +`main` does today. Planned behaviour is labelled **target**. ## What is protected @@ -37,12 +39,18 @@ labelled **target**. 1. **Ordinary Wayland clients**, sandboxed or not. They may send arbitrary protocol requests, claim any app ID or title, and connect and disconnect - at will. They must not capture the screen, type into other clients, see - other windows' contents, place shell layers or get past the lock. -2. **Session-bus callers.** Any same-user process on the session bus may - call the compositor's and shell's D-Bus interfaces, and may claim - well-known names that nobody owns yet. Capture, remote input and window - introspection must not be granted on the strength of a claimed name. + at will. Through Wayland they must not capture the screen, type into + other clients, see other windows' contents, place shell layers or get + past the lock. What a native client can do outside Wayland is covered + under [Out of scope](#out-of-scope). +2. **Sandboxed and non-native session-bus callers.** Flatpak and other + sandboxed applications reach the session bus through a filtering proxy, + and other callers may not be native processes of the session user. They + may call the compositor's and shell's D-Bus interfaces they can reach, + and may claim well-known names that nobody owns yet. Capture, remote + input and window introspection must not be granted on the strength of a + claimed name. Native same-user processes are out of scope + ([ADR 0010](https://github.com/tuna-os/tuna-desktop/blob/main/docs/adr/0010-same-uid-trusted-identity.md)). 3. **Processes of other users.** They must not reach the control socket or any per-session state. 4. **A person at a locked screen.** They can type and click on the lock @@ -56,12 +64,20 @@ labelled **target**. ## Out of scope -- **Same-UID processes that can debug or rewrite the shell or compositor.** - ADR 0005 records that a process able to `ptrace` the shell "still wins; - that is the platform's same-uid boundary, not something a socket can fix" +- **Native same-UID processes.** A native process running as the session + user can kill the portal or gnome-remote-desktop and start the genuine, + root-owned binary with `LD_PRELOAD`. That needs no `ptrace`, and Yama + does not stop it. Every identity check then passes, and the process gets + screen capture and remote input with no consent. No check of process + attributes can prevent this under one UID; GNOME 51 makes the same choice + with weaker checks + ([ADR 0010](https://github.com/tuna-os/tuna-desktop/blob/main/docs/adr/0010-same-uid-trusted-identity.md#residual-risks), R1). + ADR 0005 likewise records that a process able to `ptrace` the shell + "still wins; that is the platform's same-uid boundary, not something a + socket can fix" ([ADR 0005](https://github.com/tuna-os/tuna-desktop/blob/main/docs/adr/0005-control-socket-peer-authentication.md#consequences)). - The same applies to a same-user process that edits the user's - configuration, autostart entries or extension directory. + The same applies to a same-user process that edits the user's login + environment, configuration, autostart entries or extension directory. - **root, the kernel, GPU drivers and firmware.** Executable-identity checks trust root-owned, non-writable installed binaries (see below), so a root compromise defeats them by design. @@ -125,7 +141,10 @@ locked state to the capture authority and closes the overview (`runtime.rs:1661-1687`). Unlock runs the session user's own PAM transaction against the `tuna-lock` service (`share/pam.d/tuna-lock`) in a private helper. Attempts are bound to the control connection, request, -attempt serial and lock epoch. See: +attempt serial and lock epoch. Fingerprint unlock does not run through PAM +yet: a fprintd match unlocks without the account stack (a fix is in +progress; [ADR 0011](https://github.com/tuna-os/tuna-desktop/blob/main/docs/adr/0011-lock-auth-and-capture-grant-lifecycle.md), F5). +See: - [Lock-screen authentication conversations](https://github.com/tuna-os/tuna-desktop/blob/main/docs/security/lock-conversations.md) - [Password result ownership](https://github.com/tuna-os/tuna-desktop/blob/main/docs/security/password-owner-epoch.md) @@ -221,7 +240,10 @@ refuse locked frames. Full detail and the qualification evidence: listener 250 ms and is retried, instead of ending the event loop and the session (#1071, `security_listener.rs`; `crates/compositor/tests/security_context_accept.rs`). -- Input-method v2 is open to any client, as on GNOME (`protocols.rs:165-166`). +- Input-method v2 is visible and bindable only to the compositor's IBus + bridge, like the virtual keyboard (`protocols.rs`, `_input_method`). + Evidence: `crates/compositor/tests/input_protocols.rs` + (`ordinary_and_spoofed_clients_cannot_discover_or_force_bind_privileged_input_managers`). ### Session-bus interfaces @@ -300,9 +322,14 @@ UI classification remain required for both legs. ## Known limitations -- **Same-UID boundary.** PID-based shell identity and executable-identity - checks stop name spoofing. They do not stop a same-user process that can - `ptrace` or inject into the shell or portal. +- **Same-UID boundary.** Shell identity and executable-identity + checks stop processes that only claim an identity. They do not stop a + native same-user process, and it needs no `ptrace`: `LD_PRELOAD` into the + genuine portal or grd binary is enough. Mitigations: a GNOME-style + screen-sharing and remote-access indicator with Stop and + gnome-remote-desktop sessions only while Remote Desktop is enabled in + gsettings are being built; pidfd-pinned shell identity is #1171 + ([ADR 0010](https://github.com/tuna-os/tuna-desktop/blob/main/docs/adr/0010-same-uid-trusted-identity.md#review-findings-and-dispositions)). - **Name-based allowlists.** The `org.gnome.Shell` allowlist trusts whoever owns an allowlisted well-known name, as GNOME does. A same-user process that claims `org.gnome.Settings` first passes it. Those methods @@ -340,8 +367,12 @@ quality: - Requirements R6 (session/lock), R11 (extension boundary) and R14 (capture/privileged surfaces) with their security cases ([requirements](https://github.com/tuna-os/tuna-desktop/blob/main/docs/requirements.md)). -- The open ADR register rows for same-UID identity and the production - lock/auth and portal/capture lifecycle +- The ADR register rows for same-UID identity and the production + lock/auth and portal/capture lifecycle, proposed in + [ADR 0010](https://github.com/tuna-os/tuna-desktop/blob/main/docs/adr/0010-same-uid-trusted-identity.md) and + [ADR 0011](https://github.com/tuna-os/tuna-desktop/blob/main/docs/adr/0011-lock-auth-and-capture-grant-lifecycle.md) (#1162) and + awaiting the owner's decision. Their residual risks, including the gaps + they record, are part of the gate 4 review ([ADR register](https://github.com/tuna-os/tuna-desktop/blob/main/docs/adr/README.md#decision-register)). The `portal-security` and `remote-security` CI lanes run the packaged diff --git a/docs/tuna-desktop/session-operations.md b/docs/tuna-desktop/session-operations.md index 9284870e..b83fd04d 100644 --- a/docs/tuna-desktop/session-operations.md +++ b/docs/tuna-desktop/session-operations.md @@ -229,7 +229,9 @@ The session locks after five minutes without input, on Super+L, on password with the PAM service `tuna-lock`, installed as `/etc/pam.d/tuna-lock` (`share/pam.d/tuna-lock`), which includes your distribution's `login` stack. Fingerprint unlock goes through fprintd when a reader and an enrolled finger -are present. +are present, with its own PAM service `tuna-lock-fingerprint`, installed as +`/etc/pam.d/tuna-lock-fingerprint`: `pam_fprintd` plus the `login` account +stack, like GDM's `gdm-fingerprint`. ### When the password is not accepted @@ -245,7 +247,7 @@ are present. 2. The lock screen authenticates `$LOGNAME` (else `$USER`) from the compositor's environment (`crates/compositor/src/unlock.rs:70-77`). 3. Each attempt has 10 seconds; a PAM stack that hangs longer is treated as a - failure (`crates/compositor/src/pam.rs:24-25`). + failure (`crates/compositor/src/pam.rs:31-32`). 4. For more detail, reproduce with `TUNA_LOCK_TRACE=1` in the compositor's environment. It logs each authentication attempt's lifecycle, never the password. @@ -253,6 +255,15 @@ are present. To test a different PAM stack without touching `tuna-lock`, set `TUNA_PAM_SERVICE` to another service name. +### When the fingerprint is not accepted + +Check `/etc/pam.d/tuna-lock-fingerprint` exists (a source install copies it +from `share/pam.d/tuna-lock-fingerprint`) and that `pam_fprintd.so` is +installed (`libpam-fprintd` on Debian and Ubuntu, `fprintd` on Arch). Without +either, the finger is refused and the password still unlocks. +`TUNA_PAM_FINGERPRINT_SERVICE` names a different service for fingerprint +unlock. + ### Getting out of a stuck lock screen In a hardware session the compositor follows logind like GNOME Shell does diff --git a/docs/tuna-desktop/testing.md b/docs/tuna-desktop/testing.md index 0afae714..eef06e2e 100644 --- a/docs/tuna-desktop/testing.md +++ b/docs/tuna-desktop/testing.md @@ -50,10 +50,10 @@ base, and picks the proof lanes the change can affect: `test_notify_callback_contract.py`); a test only `check` runs selects none. `WorkflowSync.test_lane_run_tests_select_their_lane` fails when a lane job runs a test the selector does not map. -- a packaged conffile (`share/pam.d/`, installed as `/etc/pam.d/tuna-lock`): - `journey`, whose disposable Debian lifecycle fails when its bytes drift - from the released package's, plus the core lanes and every package - consumer. +- a packaged conffile (`share/pam.d/`, installed as `/etc/pam.d/tuna-lock` + and `/etc/pam.d/tuna-lock-fingerprint`): `journey`, whose disposable Debian + lifecycle fails when `tuna-lock`'s bytes drift from the released package's, + plus the core lanes and every package consumer. - anything else (crates, `share/`, other scripts): `gtk-shell` plus a round-robin slice of the other end-to-end lanes, rotated by run number. The slice size is the repository variable `CI_ROUND_ROBIN_SIZE` @@ -62,7 +62,7 @@ base, and picks the proof lanes the change can affect: The step summary of `select-lanes` names the chosen lanes and why. Independent lanes start after selection, without waiting for workspace -tests. GTK, grid comparison and fingerprint admission still require the +tests. GTK and grid comparison admission still require the successful current-run `check`; the ledger also consumes its test list, and image publication waits for it. Package and screenshot consumers still wait for their producing proof jobs. @@ -120,7 +120,7 @@ action invokes its paired installer through `GITHUB_ACTION_PATH` and hashes those actual workflow-owned files, not similarly named candidate files. Older PR heads need not contain the cache action or staged installer. The required `check` job tests the PR merge ref and exports its actual -`tested_sha`; GTK authentication, fingerprint and grid comparison proofs +`tested_sha`; GTK authentication and grid comparison proofs check out that exact revision. Admission separately validates the workflow event commit, checked output, clean checkout/tree and API triggering head, so a green job's `head_sha` is never mistaken for its tested merge tree. @@ -140,10 +140,10 @@ Ubuntu keys include the native distro ID/version in addition to the pinned cache action's compiler, architecture, environment and dependency identity. `check` includes the standalone `third-party/reis` and `third-party/smithay` targets. Grid comparison has separate cached -old/fixed targets under `target/ci-grid`, keyed to its reviewed old source; -fingerprint uses `target/ci-fprint`. Setting `CARGO_TARGET_DIR` opts these -two proof scripts into persistent build targets; without it, local runs -keep isolated targets inside their fresh artifact directory. Receipts, +old/fixed targets under `target/ci-grid`, keyed to its reviewed old source. +Setting `CARGO_TARGET_DIR` opts its proof script into persistent build +targets; without it, local runs keep isolated targets inside their fresh +artifact directory. Receipts, admissions and verdicts are always freshly produced outside the cache. The Arch job shares an explicit Cargo home between cache restoration and @@ -195,6 +195,14 @@ This matches Mutter 51's initial-focus path: [attaching the drag handler immediately invalidates focus](https://github.com/GNOME/mutter/blob/51.0/src/wayland/meta-wayland-input.c#L288-L325), and [drag focus sends the destination its offer while restricting source-less drags to the origin client](https://github.com/GNOME/mutter/blob/51.0/src/wayland/meta-wayland-data-device.c#L337-L397). +The GTK proof's focused slices (`--*-only`) run one at a time. A new slice +adds its usage line above `# end of --help` in the script's header (`--help` +prints up to that line) and one case arm that calls `only_mode` with its flag +and the traits it needs: `source-build` refuses `--installed-package`, and +`no-media-source`, `no-examples` and `no-camera-policy` skip the full run's +media-source receipt, example-client build and camera policy. No other +slice's checks change. + `scripts/tuna-gtk-shell-proof --window-leak-only --artifacts DIR` runs G-WINDOW-LEAK (#1088): after five warm-up windows, 100 libadwaita windows (`TUNA_WINDOW_LEAK_WINDOWS` sets the count) are opened and closed, odd ones @@ -936,6 +944,7 @@ budget. The owner observation is null while locked. The compositor state (`TUNA_COMPOSITOR_STATE`) carries `frame_cost`, one entry per output describing its last drawn frame: `rendered` and `culled` element counts, `damage_rects` and `damage_area` against `output_area`, +the box around the damage (`damage_bounds`, `[x, y, w, h]`), and the window ids the frame shows (`drawn_windows`) or wholly hides behind opaque surfaces (`culled_windows`). Both cover the whole output, so a frame that repaints only the panel or the cursor still lists the windows @@ -948,6 +957,11 @@ told so gets no frame callbacks until it shows again. Proof `G-OCCLUSION-CULL` fullscreens an opaque window over another and requires the lower one to be culled and throttled, then drawn at full rate again once the upper window's translucent shadow returns. +Proof `G-CLOCK-DAMAGE` (#1154) turns on clock-show-seconds and requires +a frame whose damage lies inside the panel bar and covers under 2% of the +output: the clock's rectangle. Before #1154 the nested output's buffer +age read as 0 after every client commit, so each one repainted the whole +output. ## Settings writes in proofs diff --git a/docs/tuna-desktop/troubleshooting.md b/docs/tuna-desktop/troubleshooting.md index ac02300b..d85ff7bd 100644 --- a/docs/tuna-desktop/troubleshooting.md +++ b/docs/tuna-desktop/troubleshooting.md @@ -97,9 +97,10 @@ qualified yet. dependency resolution fails because the package needs gtk4-layer-shell 1.1 or later ([install guide](https://github.com/tuna-os/tuna-desktop/blob/main/docs/install.md#from-the-debian-format-package)). Build from source there instead. -- `/etc/pam.d/tuna-lock` is a configuration file. If you changed or deleted - it, dpkg can stop and ask what to do during an upgrade; an unattended - upgrade then leaves the package unconfigured. Answer the prompt, then run +- `/etc/pam.d/tuna-lock` and `/etc/pam.d/tuna-lock-fingerprint` (fingerprint + unlock) are configuration files. If you changed or deleted one, dpkg can + stop and ask what to do during an upgrade; an unattended upgrade then leaves + the package unconfigured. Answer the prompt, then run `sudo dpkg --configure -a`. - Upgrading from a package with the project's former name is covered in the [upgrade and recovery guide](https://github.com/tuna-os/tuna-desktop/blob/main/docs/legacy-upgrade.md). @@ -118,7 +119,7 @@ Build it from a checkout with: TUNA_LOCAL_SRC="$PWD" makepkg -f --dir packaging/arch ``` -Both PAM files are in the package's `backup` array, so pacman keeps a file you +Every PAM file is in the package's `backup` array, so pacman keeps a file you changed and writes the new one as `.pacnew` beside it. Compare the two and merge by hand ([legacy upgrade](https://github.com/tuna-os/tuna-desktop/blob/main/docs/legacy-upgrade.md#arch-replacement)). @@ -129,7 +130,8 @@ merge by hand ([legacy upgrade](https://github.com/tuna-os/tuna-desktop/blob/mai binaries into the same directory ([install guide](https://github.com/tuna-os/tuna-desktop/blob/main/docs/install.md#installing)). - Install `share/pam.d/tuna-lock` as `/etc/pam.d/tuna-lock`, or the lock - screen cannot be unlocked. + screen cannot be unlocked, and `share/pam.d/tuna-lock-fingerprint` as + `/etc/pam.d/tuna-lock-fingerprint`, or fingerprint unlock fails. ### TunaOS Marlin diff --git a/docs/tuna-desktop/visual-capture-matrix.md b/docs/tuna-desktop/visual-capture-matrix.md index 124043de..a58d4922 100644 --- a/docs/tuna-desktop/visual-capture-matrix.md +++ b/docs/tuna-desktop/visual-capture-matrix.md @@ -142,6 +142,7 @@ state records its state observation next to its stills and clips. | P-ST-10 | Service-backed Settings panels on image | `unsupported-in-nested` | No adequate capture | network/BT/accounts/printers/sharing/users/region/updates need installed-image Corral item-by-item | | P-ST-11 | Legacy/app-owned settings classified | `nonvisual` | No adequate capture | inventory disposition, checked by scripts/tuna-settings-inventory-check | | P-LK-02 | Fingerprint, smartcard, multi-step login | `missing-product` | No adequate capture | one password entry only; distinct challenges need product work plus Corral hardware | +| P-LK-03 | Tuna Desktop's own greeter on GDM's daemon | `missing-product` | No adequate capture | the greeter is not shipped yet ([#1164](https://github.com/tuna-os/tuna-desktop/issues/1164)); its screens need product work plus a Corral boot to GDM | | P-AN-01 | Motion preferences | stage:transitions `partial` | Transition clip required | full-speed clips captured; animations-off/reduced-motion/slowdown variants unproven | | P-AN-02 | Window open/close animations | stage:transitions `partial` | Transition clip required | overview/size clips captured; map/destroy/dialog intermediate frames unproven | | P-AN-03 | Minimize toward dash icon | `missing-product` | Transition clip required | hide/restore is instant; no transition exists to film | @@ -235,6 +236,7 @@ their ledger rows above: - netloc: P-ST-10 (`unsupported-in-nested`, network locations and sharing panels on image). - fprint: P-LK-02 (`missing-product`). +- greeter: P-LK-03 (`missing-product`, #1164). ## Walkthrough freshness diff --git a/docs/tuna-desktop/vm-lifecycle.md b/docs/tuna-desktop/vm-lifecycle.md index 0817a085..34a49484 100644 --- a/docs/tuna-desktop/vm-lifecycle.md +++ b/docs/tuna-desktop/vm-lifecycle.md @@ -52,6 +52,20 @@ and 120-second phase deadlines remain unchanged. No updater service, notification policy or failure log is disabled; acknowledging a banner does not qualify the update operation that produced it. +Banners queue, as in GNOME's message tray: the shell shows one at a time and +never times out a critical one, so closing it drops the next into the same +layer. The probe closes each in turn, as a user would. The observer reports +each Close control's accessible object path, which names that widget +instance and not its content; the shell builds a new card for every banner +it shows. A Close instance receives Return at most once. When the banner +layer is still there 0.6 s after Return, the probe observes it again. A new +Close instance gets the same Super+N, Tab and focused-Return sequence. The +one it already activated is never activated again, and the capture deadline +then fails the case. In marlin-vm run 44442598008, uupd failed three times +and queued three critical "Some System Updates Failed" banners. The probe +closed only the first, and the next one covered the frame until +`V-STRIP-INSTALLED` timed out. + The column-height capture also submits a real critical notification through the session's public notification service. It cannot pass until the original shell shows the fixed public fixture title, its sensitive Close button receives @@ -690,7 +704,9 @@ That control must belong to the original shell process and its AT-SPI bus. It must report `FOCUSED`. A layer namespace alone is not proof of that owner. -After the normal Close action, the banner must be absent and all keys released. +After the normal Close action, the banner must be absent and all keys released; +a queued banner that drops in instead gets its own focused Close (see +"Installed strip captures"). Original windows, focus, workspace and session mode must remain unchanged. Both PNG and PPM still need all original 25 color checks. No pointer coordinates or empirical offsets select the control. diff --git a/docs/tuna-mail/CONTRIBUTING.md b/docs/tuna-mail/CONTRIBUTING.md index c853b2d4..3c267f54 100644 --- a/docs/tuna-mail/CONTRIBUTING.md +++ b/docs/tuna-mail/CONTRIBUTING.md @@ -1,97 +1,6 @@ --- -sidebar_position: 3 -title: "CONTRIBUTING" +sidebar_position: 2 +title: "Contributing" --- -Welcome to the Thunderbird for Android project! We're excited to have you here and welcome your contributions. - -## 🌱 New Contributor Essentials - -Before you start contributing, please take a moment to familiarize yourself with the following: - -- [About Thunderbird for Android](https://github.com/tuna-os/tuna-mail/blob/main/docs/about.md). -- [Thunderbird Developer Portal](https://developer.thunderbird.net/) -- [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/) -- [Matrix (developer chat)](https://matrix.to/#/#tb-mobile-dev:mozilla.org) -- [Frequently Asked Questions (historical K-9 forum)](https://forum.k9mail.app/c/faq) -- [Support Forum (historical K-9 forum)](https://forum.k9mail.app/) - -Note: Some support resources currently point to the K-9 Mail forum due to the project’s history and ongoing migration. -Where appropriate, we’ll update links to Thunderbird-specific channels. - -### 📋 Recommended knowledge - -Helpful background (not strictly required): - -- **[Kotlin](https://kotlinlang.org/docs/home.html)** - Primary programming language for the project -- **[Jetpack Compose](https://developer.android.com/jetpack/compose)** - UI toolkit used for Android -- **[Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html)** - Shared code across modules where applicable -- **[Android Development](https://developer.android.com/guide)** - Basic understanding of Android app development -- **[GitHub](https://docs.github.com/en)** - For managing contributions and pull requests - -## 🐛 Bug Reports and Feature Ideas - -When you encounter a bug or have a feature request or idea, please do the following: - -**Bugs**: - -- Search for [existing issues](https://github.com/thunderbird/thunderbird-android/issues?q=is%3Aissue) before filing a new one. -- If you can't find an existing issue, please [open a new GitHub issue](https://github.com/thunderbird/thunderbird-android/issues/new/choose) using the appropriate template. - -**Feature Requests / Ideas:** - -We don’t track new ideas or feature requests in GitHub Issues. - -- Start a discussion in [Mozilla Connect – Ideas](https://connect.mozilla.org/t5/ideas/idb-p/ideas/label-name/thunderbird%20android) -- Once a feature is accepted and work is planned, maintainers will create the corresponding GitHub issue(s). - -**GitHub Work:** - -GitHub Bug Issues track confirmed defects. GitHub Feature Issues and GitHub Task Issues track work that maintainers have -accepted and planned. New feature proposals still start in Mozilla Connect; maintainers create GitHub issues after a -proposal is accepted and scheduled. - -- External contributors should start from an existing GitHub Bug Issue, GitHub Feature Issue, or GitHub Task Issue. -- Bug issues labeled `unconfirmed` are not ready for contributions. -- Issues labeled `tb-team` are reserved for maintainers. -- If you are unsure whether an existing issue is ready for your contribution, follow - [Working From GitHub Issues](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/contribution-workflow.md#working-from-github-issues). - -## 🌐 Translations - -If you'd like to help to translate Thunderbird for Android, please visit: - -- **[Translations](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/translations.md)** – How to help localize Thunderbird for Android via Weblate. -- **[Weblate - Thunderbird for Android project](https://hosted.weblate.org/projects/thunderbird/thunderbird-android/)** - Translation platform where all localization happens. - -## 🤝 Contributing Code - -This should give you a detailed overview on how to contribute code to the project. Use it as a reference for setup, -development, testing, and review. - -### 🚀 Getting Started - -- **[Contribution Workflow](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/contribution-workflow.md)** – Step-by-step process: find an issue, fork, branch, commit, PR. -- **[Development Environment](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/development-environment.md)** – How to set up Android Studio, build, run, and debug the project. - -### 🏗️ Development Practices - -- **[Engineering](https://github.com/tuna-os/tuna-mail/blob/main/docs/engineering/README.md)** – Process and artifacts for proposing, deciding, and delivering technical changes (RFCs, Technical Designs, ADRs). -- **[Architecture](https://github.com/tuna-os/tuna-mail/blob/main/docs/architecture/README.md)** – System design: module types, UI/Domain/Data layers, offline-first. -- **[Development Guidelines](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/development-guide.md)** – Project-specific conventions and quick “do’s & don’ts.” -- **[Code Quality Guide](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/code-quality-guide.md)** – Style rules, static analysis tools, and security practices. -- **[Testing Guide](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/testing-guide.md)** – Test layers, frameworks, and best practices. - -### 🔍 Reviews & Collaboration - -- **[Git Commit Guide](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/git-commit-guide.md)** – How to write clear, Conventional Commit-style messages. -- **[Code Review Guide](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/code-review-guide.md)** – Expectations for PR authors and reviewers, review etiquette. - -### 🌐 Translations - -- **[Translations](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/translations.md)** – How to help localize Thunderbird for Android via Weblate. -- **[Managing Strings](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/managing-strings.md)** – Developer guide for adding/changing/removing strings, languages, and handling Weblate sync. - -## Thank You - -Thank you for taking the time to contribute to Thunderbird for Android! We appreciate your help in making the project better and more useful for everyone. +We welcome contributions! See our [Contributing Guide](https://github.com/tuna-os/tuna-mail/blob/main/docs/CONTRIBUTING.md) for how to report bugs, find an issue, set up your environment, and submit a pull request. diff --git a/docs/tuna-mail/HOW-TO-DOCUMENT.md b/docs/tuna-mail/HOW-TO-DOCUMENT.md index d08759d7..d9004a70 100644 --- a/docs/tuna-mail/HOW-TO-DOCUMENT.md +++ b/docs/tuna-mail/HOW-TO-DOCUMENT.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 title: "HOW TO DOCUMENT" --- diff --git a/docs/tuna-mail/SECURITY.md b/docs/tuna-mail/SECURITY.md index e56ffe37..e172e35b 100644 --- a/docs/tuna-mail/SECURITY.md +++ b/docs/tuna-mail/SECURITY.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 title: "Security" --- diff --git a/docs/tuna-mail/about.md b/docs/tuna-mail/about.md index f8e5018e..d246fa17 100644 --- a/docs/tuna-mail/about.md +++ b/docs/tuna-mail/about.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 7 title: "about" --- diff --git a/docs/tuna-mail/docs-CONTRIBUTING.md b/docs/tuna-mail/docs-CONTRIBUTING.md new file mode 100644 index 00000000..66a8c0b2 --- /dev/null +++ b/docs/tuna-mail/docs-CONTRIBUTING.md @@ -0,0 +1,97 @@ +--- +sidebar_position: 4 +title: "CONTRIBUTING" +--- + +Welcome to the Thunderbird for Android project! We're excited to have you here and welcome your contributions. + +## 🌱 New Contributor Essentials + +Before you start contributing, please take a moment to familiarize yourself with the following: + +- [About Thunderbird for Android](https://github.com/tuna-os/tuna-mail/blob/main/docs/about.md). +- [Thunderbird Developer Portal](https://developer.thunderbird.net/) +- [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/) +- [Matrix (developer chat)](https://matrix.to/#/#tb-mobile-dev:mozilla.org) +- [Frequently Asked Questions (historical K-9 forum)](https://forum.k9mail.app/c/faq) +- [Support Forum (historical K-9 forum)](https://forum.k9mail.app/) + +Note: Some support resources currently point to the K-9 Mail forum due to the project’s history and ongoing migration. +Where appropriate, we’ll update links to Thunderbird-specific channels. + +### 📋 Recommended knowledge + +Helpful background (not strictly required): + +- **[Kotlin](https://kotlinlang.org/docs/home.html)** - Primary programming language for the project +- **[Jetpack Compose](https://developer.android.com/jetpack/compose)** - UI toolkit used for Android +- **[Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html)** - Shared code across modules where applicable +- **[Android Development](https://developer.android.com/guide)** - Basic understanding of Android app development +- **[GitHub](https://docs.github.com/en)** - For managing contributions and pull requests + +## 🐛 Bug Reports and Feature Ideas + +When you encounter a bug or have a feature request or idea, please do the following: + +**Bugs**: + +- Search for [existing issues](https://github.com/thunderbird/thunderbird-android/issues?q=is%3Aissue) before filing a new one. +- If you can't find an existing issue, please [open a new GitHub issue](https://github.com/thunderbird/thunderbird-android/issues/new/choose) using the appropriate template. + +**Feature Requests / Ideas:** + +We don’t track new ideas or feature requests in GitHub Issues. + +- Start a discussion in [Mozilla Connect – Ideas](https://connect.mozilla.org/t5/ideas/idb-p/ideas/label-name/thunderbird%20android) +- Once a feature is accepted and work is planned, maintainers will create the corresponding GitHub issue(s). + +**GitHub Work:** + +GitHub Bug Issues track confirmed defects. GitHub Feature Issues and GitHub Task Issues track work that maintainers have +accepted and planned. New feature proposals still start in Mozilla Connect; maintainers create GitHub issues after a +proposal is accepted and scheduled. + +- External contributors should start from an existing GitHub Bug Issue, GitHub Feature Issue, or GitHub Task Issue. +- Bug issues labeled `unconfirmed` are not ready for contributions. +- Issues labeled `tb-team` are reserved for maintainers. +- If you are unsure whether an existing issue is ready for your contribution, follow + [Working From GitHub Issues](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/contribution-workflow.md#working-from-github-issues). + +## 🌐 Translations + +If you'd like to help to translate Thunderbird for Android, please visit: + +- **[Translations](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/translations.md)** – How to help localize Thunderbird for Android via Weblate. +- **[Weblate - Thunderbird for Android project](https://hosted.weblate.org/projects/thunderbird/thunderbird-android/)** - Translation platform where all localization happens. + +## 🤝 Contributing Code + +This should give you a detailed overview on how to contribute code to the project. Use it as a reference for setup, +development, testing, and review. + +### 🚀 Getting Started + +- **[Contribution Workflow](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/contribution-workflow.md)** – Step-by-step process: find an issue, fork, branch, commit, PR. +- **[Development Environment](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/development-environment.md)** – How to set up Android Studio, build, run, and debug the project. + +### 🏗️ Development Practices + +- **[Engineering](https://github.com/tuna-os/tuna-mail/blob/main/docs/engineering/README.md)** – Process and artifacts for proposing, deciding, and delivering technical changes (RFCs, Technical Designs, ADRs). +- **[Architecture](https://github.com/tuna-os/tuna-mail/blob/main/docs/architecture/README.md)** – System design: module types, UI/Domain/Data layers, offline-first. +- **[Development Guidelines](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/development-guide.md)** – Project-specific conventions and quick “do’s & don’ts.” +- **[Code Quality Guide](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/code-quality-guide.md)** – Style rules, static analysis tools, and security practices. +- **[Testing Guide](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/testing-guide.md)** – Test layers, frameworks, and best practices. + +### 🔍 Reviews & Collaboration + +- **[Git Commit Guide](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/git-commit-guide.md)** – How to write clear, Conventional Commit-style messages. +- **[Code Review Guide](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/code-review-guide.md)** – Expectations for PR authors and reviewers, review etiquette. + +### 🌐 Translations + +- **[Translations](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/translations.md)** – How to help localize Thunderbird for Android via Weblate. +- **[Managing Strings](https://github.com/tuna-os/tuna-mail/blob/main/docs/contributing/managing-strings.md)** – Developer guide for adding/changing/removing strings, languages, and handling Weblate sync. + +## Thank You + +Thank you for taking the time to contribute to Thunderbird for Android! We appreciate your help in making the project better and more useful for everyone. diff --git a/docs/tuna-mail/docs-README.md b/docs/tuna-mail/docs-README.md index c8b32ce6..146100f6 100644 --- a/docs/tuna-mail/docs-README.md +++ b/docs/tuna-mail/docs-README.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 6 title: "README" --- diff --git a/docs/tunaos-packages/CONTRIBUTING.md b/docs/tunaos-packages/CONTRIBUTING.md index c3e079a2..4a94aee8 100644 --- a/docs/tunaos-packages/CONTRIBUTING.md +++ b/docs/tunaos-packages/CONTRIBUTING.md @@ -107,6 +107,24 @@ manifest, and the Bats suite. If your change touches shell workflows, install Ba the relevant file under `tests/bats/`; see [`tests/bats/README.md`](https://github.com/tuna-os/tunaos-packages/blob/main/tests/bats/README.md) for setup and examples. +Two other CI checks can fail a pull request: + +- The `actions-security` workflow verifies `.github/workflows/actions.lock` + and scans the workflows with zizmor. If you change a `uses:` line in a + workflow, update `actions.lock` in the same pull request. +- The `Prose` workflow (`ste.yml`) checks `README.md`, `CONTRIBUTING.md`, + `SECURITY.md` and the files in `docs/` against Simplified Technical English. + `.ste-budget` holds the current number of problems. One new STE problem in + these files makes the check fail. To run the same linter, you + need Node.js and a clone of [tuna-os/.github](https://github.com/tuna-os/.github). + From the root of this repository, run: + + ```bash + node ../.github/.github/actions/ste-lint/ste-lint.mjs --max "$(cat .ste-budget)" + ``` + + Change `../.github` if you cloned tuna-os/.github to a different directory. + For a local RPM build, use the target declared by the owning pipeline: ```bash diff --git a/docs/tunaos-packages/FACTORY-STATUS.md b/docs/tunaos-packages/FACTORY-STATUS.md index 27b54fd5..5cff0d8b 100644 --- a/docs/tunaos-packages/FACTORY-STATUS.md +++ b/docs/tunaos-packages/FACTORY-STATUS.md @@ -5,9 +5,8 @@ title: "FACTORY STATUS" -# Factory status — built vs needed, per target -Measured 2026-10-16T10:19:18+00:00 from the live published indexes; +Measured 2026-11-18T14:24:09+00:00 from the live published indexes; provenance (repomd revision, primary.xml sha256) is in `docs/factory-status.json`, which also carries the full built and needed lists this page truncates. @@ -19,35 +18,48 @@ needs catalog version pins, which most entries do not carry yet. ## Progress since the last measurement -Compared against 2026-10-15T10:09:50+00:00, the last measurement +Compared against 2026-10-16T10:19:18+00:00, the last measurement that actually MERGED — so a large gap here means the daily refresh is not landing, which is its own defect: +> **⚠ the previous measurement is 33 days old.** The refresh PR is not merging; every delta +> below spans that whole window, and nothing in between +> was recorded. + | target/arch | built Δ | needed Δ | no movement for | newly built | |---|---|---|---|---| -| debian/amd64 | +1 | +0 | — | tuna-desktop | -| debian/arm64 | +1 | +0 | — | tuna-desktop | -| el10/aarch64 | +2 | -1 | — | gtk4-layer-shell, tuna-desktop | -| el10/x86_64 | +2 | -1 | — | gtk4-layer-shell, tuna-desktop | -| fedora/x86_64 | +1 | +0 | — | tuna-desktop | -| hummingbird/aarch64 | -5 | +19 | — | — | -| hummingbird/x86_64 | -4 | +18 | — | libao | -| opensuse-tumbleweed/aarch64 | +1 | +0 | — | tuna-desktop | -| opensuse-tumbleweed/x86_64 | +1 | +0 | — | tuna-desktop | -| ubuntu/amd64 | +1 | +0 | — | tuna-desktop | -| ubuntu/arm64 | +1 | +0 | — | tuna-desktop | +| debian/amd64 | +0 | +0 | 33 days | — | +| debian/arm64 | +0 | +0 | 33 days | — | +| el10/aarch64 | +0 | -1 | 33 days | — | +| el10/x86_64 | +2 | -3 | — | colord-gtk, gsound | +| eln/aarch64 | +2 | +36 | newly measured | gtkgreet, tuna-desktop | +| eln/x86_64 | +2 | +36 | newly measured | gtkgreet, tuna-desktop | +| fedora/x86_64 | +0 | +0 | 33 days | — | +| gentoo/amd64 | +1 | +0 | newly measured | tuna-desktop | +| hummingbird/aarch64 | -3 | +1 | — | tuna-desktop | +| hummingbird/x86_64 | -1 | -1 | — | ghc-pandoc, pandoc-cli, tuna-desktop | +| noble/amd64 | +2 | +0 | newly measured | gtk4-layer-shell, tuna-desktop | +| noble/arm64 | +2 | +0 | newly measured | gtk4-layer-shell, tuna-desktop | +| opensuse-tumbleweed/aarch64 | +0 | +0 | 33 days | — | +| opensuse-tumbleweed/x86_64 | +0 | +0 | 33 days | — | +| rawhide/aarch64 | +1 | +0 | newly measured | tuna-desktop | +| rawhide/x86_64 | +1 | +0 | newly measured | tuna-desktop | +| trixie/amd64 | +1 | +0 | newly measured | tuna-desktop | +| trixie/arm64 | +1 | +0 | newly measured | tuna-desktop | +| ubuntu/amd64 | +0 | +1 | 33 days | — | +| ubuntu/arm64 | +0 | +1 | 33 days | — | **Retired — built by the previous measurement, no longer in the catalog.** The target adopted them, so the factory stopped owing them; this is work REMOVED (RFC 011 criterion 2), and it is why `built` can fall without anything being lost: -- hummingbird/aarch64: NetworkManager-vpnc, libuser, python-six, usermode, vpnc -- hummingbird/x86_64: NetworkManager-vpnc, libuser, python-six, usermode, vpnc +- hummingbird/aarch64: cairo, jasper, lcms2, openjpeg +- hummingbird/x86_64: cairo, jasper, lcms2, openjpeg ## debian | arch | catalog entries | built | needed | index packages | |---|---|---|---|---| -| amd64 | 57 | 6 | 51 | 20 | -| arm64 | 57 | 6 | 51 | 20 | +| amd64 | 57 | 6 | 51 | 30 | +| arm64 | 57 | 6 | 51 | 30 | Needed on amd64 (51; first 40, full list in the JSON): @@ -143,16 +155,17 @@ libxfce4ui | arch | catalog entries | built | needed | index packages | |---|---|---|---|---| -| aarch64 | 145 | 44 | 101 | 64 | -| x86_64 | 145 | 115 | 30 | 439 | +| aarch64 | 144 | 44 | 100 | 64 | +| x86_64 | 144 | 117 | 27 | 439 | -Needed on aarch64 (101; first 40, full list in the JSON): +Needed on aarch64 (100; first 40, full list in the JSON): ``` autoconf avahi cairo cli11-devel +colord-gtk dms dms-cli dms-greeter @@ -174,12 +187,11 @@ gnome-settings-daemon gnome-shell gnome50-el10-compat gobject-introspection -graphviz gsettings-desktop-schemas +gsound gtk4 gtkgreet harfbuzz -highway iio-niri input-remapper krunner-bazaar @@ -188,10 +200,10 @@ libadwaita libei libfprint libgda -libgee +libgexiv2 ``` -Needed on x86_64 (30): +Needed on x86_64 (27): ``` cli11-devel @@ -202,16 +214,13 @@ fprintd gdk-pixbuf2 gnome-desktop3 gnome-initial-setup -graphviz harfbuzz -highway iio-niri input-remapper krunner-bazaar labwc libfprint libgda -libgee libglib-testing libsoup libzip @@ -220,10 +229,99 @@ ptyxis quickshell simdutf sqlcipher -vala vte291 xdg-desktop-portal xdg-desktop-portal-gnome +yq +``` + +## eln + +| arch | catalog entries | built | needed | index packages | +|---|---|---|---|---| +| aarch64 | 38 | 2 | 36 | 4 | +| x86_64 | 38 | 2 | 36 | 4 | + +Needed on aarch64 (36): + +``` +exo +garcon +gtk-layer-shell +libxfce4ui +libxfce4util +libxfce4windowing +mousepad +ristretto +thunar +tumbler +uupd +wayland-protocols +wlr-protocols +xfce4-appfinder +xfce4-clipman-plugin +xfce4-cpugraph-plugin +xfce4-datetime-plugin +xfce4-dev-tools +xfce4-genmon-plugin +xfce4-netload-plugin +xfce4-notifyd +xfce4-panel +xfce4-power-manager +xfce4-pulseaudio-plugin +xfce4-screenshooter +xfce4-sensors-plugin +xfce4-session +xfce4-settings +xfce4-taskmanager +xfce4-terminal +xfce4-wayland +xfce4-weather-plugin +xfce4-whiskermenu-plugin +xfconf +xfdesktop +xfwl4 +``` + +Needed on x86_64 (36): + +``` +exo +garcon +gtk-layer-shell +libxfce4ui +libxfce4util +libxfce4windowing +mousepad +ristretto +thunar +tumbler +uupd +wayland-protocols +wlr-protocols +xfce4-appfinder +xfce4-clipman-plugin +xfce4-cpugraph-plugin +xfce4-datetime-plugin +xfce4-dev-tools +xfce4-genmon-plugin +xfce4-netload-plugin +xfce4-notifyd +xfce4-panel +xfce4-power-manager +xfce4-pulseaudio-plugin +xfce4-screenshooter +xfce4-sensors-plugin +xfce4-session +xfce4-settings +xfce4-taskmanager +xfce4-terminal +xfce4-wayland +xfce4-weather-plugin +xfce4-whiskermenu-plugin +xfconf +xfdesktop +xfwl4 ``` ## fedora @@ -232,14 +330,20 @@ xdg-desktop-portal-gnome |---|---|---|---|---| | x86_64 | 4 | 4 | 0 | 11 | +## gentoo + +| arch | catalog entries | built | needed | index packages | +|---|---|---|---|---| +| amd64 | 1 | 1 | 0 | 1 | + ## hummingbird | arch | catalog entries | built | needed | index packages | |---|---|---|---|---| -| aarch64 | 679 | 620 | 59 | 3915 | -| x86_64 | 679 | 640 | 39 | 8821 | +| aarch64 | 677 | 617 | 60 | 3916 | +| x86_64 | 677 | 639 | 38 | 8791 | -Needed on aarch64 (59; first 40, full list in the JSON): +Needed on aarch64 (60; first 40, full list in the JSON): ``` brltty @@ -253,6 +357,7 @@ evolution-ews firefox fprintd fwupd +ghc-pandoc glycin gnome-initial-setup gnome-user-share @@ -272,7 +377,6 @@ kf6-kxmlgui libao libayatana-ido libcanberra -liberation-fonts liblouis libphonenumber librist @@ -284,7 +388,7 @@ libxml2_2.13 nautilus ``` -Needed on x86_64 (39): +Needed on x86_64 (38): ``` brltty @@ -303,7 +407,6 @@ grub2 gstreamer1-plugins-bad-free iw libcanberra -liberation-fonts liblouis libphonenumber librist @@ -317,17 +420,24 @@ plasma-union plymouth pyatspi qt6-qtwebengine +rpm-ostree rust-pathrs samba speech-dispatcher stoken -tuna-desktop vdirsyncer webkitgtk xfce4-settings xfdesktop ``` +## noble + +| arch | catalog entries | built | needed | index packages | +|---|---|---|---|---| +| amd64 | 2 | 2 | 0 | 6 | +| arm64 | 2 | 2 | 0 | 6 | + ## opensuse-tumbleweed | arch | catalog entries | built | needed | index packages | @@ -363,14 +473,28 @@ uupd wayland-protocols ``` +## rawhide + +| arch | catalog entries | built | needed | index packages | +|---|---|---|---|---| +| aarch64 | 1 | 1 | 0 | 1 | +| x86_64 | 1 | 1 | 0 | 1 | + +## trixie + +| arch | catalog entries | built | needed | index packages | +|---|---|---|---|---| +| amd64 | 1 | 1 | 0 | 14 | +| arm64 | 1 | 1 | 0 | 14 | + ## ubuntu | arch | catalog entries | built | needed | index packages | |---|---|---|---|---| -| amd64 | 56 | 6 | 50 | 12 | -| arm64 | 56 | 6 | 50 | 12 | +| amd64 | 57 | 6 | 51 | 17 | +| arm64 | 57 | 6 | 51 | 17 | -Needed on amd64 (50; first 40, full list in the JSON): +Needed on amd64 (51; first 40, full list in the JSON): ``` bazaar @@ -415,7 +539,7 @@ libunwind-devel mutter ``` -Needed on arm64 (50; first 40, full list in the JSON): +Needed on arm64 (51; first 40, full list in the JSON): ``` bazaar @@ -483,7 +607,7 @@ desktops tunaOS can wire (tunaOS#1755). | gnome | 1/10 | gdm, gnome-control-center, gnome-initial-setup, gnome-session, gnome-settings-daemon, gnome-shell, … (9 total) | | kde | 3/5 | plasma-desktop, plasma-workspace | | niri | 3/6 | dms, dms-cli, dms-greeter | -| tuna | 0/1 | tuna-desktop | +| tuna | 1/3 | libcanberra, rpm-ostree | | xfce | 5/6 | xfwl4 | ## hummingbird desktop coverage (x86_64) @@ -494,12 +618,12 @@ desktops tunaOS can wire (tunaOS#1755). | desktop | roots present | missing | |---|---|---| -| bluefin | 59/77 | anaconda-live, bootc, bootupd, dracut-live, evolution-ews-core, firefox, … (18 total) | +| bluefin | 58/77 | anaconda-live, bootc, bootupd, dracut-live, evolution-ews-core, firefox, … (19 total) | | cosmic | 5/5 | — | | gnome | 10/10 | — | | kde | 5/5 | — | | niri | 3/6 | dms, dms-cli, dms-greeter | -| tuna | 0/1 | tuna-desktop | +| tuna | 1/3 | libcanberra, rpm-ostree | | xfce | 5/6 | xfwl4 | ## Not yet measured @@ -509,7 +633,7 @@ absence of a gap: | target | format | catalog entries | why | |---|---|---|---| -| arch | pkg.tar.zst | 28 | no published_index declared in package-factory.yaml | -| eln | rpm | 4 | no published_index declared in package-factory.yaml | -| rawhide | rpm | 1 | no published_index declared in package-factory.yaml | -| trixie | deb | 1 | no published_index declared in package-factory.yaml | +| alma10 | rpm | 142 | no published_index declared in package-factory.yaml | +| alma10-kitten | rpm | 142 | no published_index declared in package-factory.yaml | +| arch | pkg.tar.zst | 30 | no published_index declared in package-factory.yaml | +| ubuntu-rolling | deb | 1 | no published_index declared in package-factory.yaml | diff --git a/docs/wootc/CONTRIBUTING.md b/docs/wootc/CONTRIBUTING.md index 6eb4ba54..a4e1ba14 100644 --- a/docs/wootc/CONTRIBUTING.md +++ b/docs/wootc/CONTRIBUTING.md @@ -26,10 +26,75 @@ Never post account credentials or API keys in issues or pull requests. 3. Check the build/test matrix in `docs/status.md` for known-good and known-red cells. Do this before you blame a symptom on your change. +## Prerequisites + +Clone with submodules, or initialize them after you clone: + +```bash +git submodule update --init --recursive +``` + +The fast tier runs in Bash without a container or VM. Install all four lanes +below; the runner skips a lane when its executable is missing. + +| Tool | Installation and version source | Fast-tier lane | +|---|---|---| +| [just](https://just.systems/man/en/packages.html) | Follow the package instructions for your platform, or use `cargo install --locked just` with Rust installed. The repository does not pin a just version. | Recipe launcher; optional when invoking `bash tests/run.sh fast` directly | +| [Bats](https://bats-core.readthedocs.io/en/stable/installation.html) | Debian/Ubuntu: `sudo apt-get install bats`; Fedora: `sudo dnf install bats`; macOS: `brew install bats-core`. No Bats minimum is pinned. | `bats tests/unit/*.bats` | +| [Python 3](https://www.python.org/downloads/) | Debian/Ubuntu: `sudo apt-get install python3`; Fedora: `sudo dnf install python3`; macOS: `brew install python`. Use Python **3.11 or later** for the package consumer controls, as required by `ci.yml`; there is no single repository-wide Python pin. | Each `tests/unit/test_*.py`, directly, without pytest | +| [Go](https://go.dev/doc/install) | Use the official installer/archive or your platform package manager. `app/go.mod` declares **1.26.0**; the fast CI job selects **1.27**. Use that CI toolchain to match CI, and honor each submodule's own `go.mod`. | `go test ./...` in `app`, `fisherman/tui`, and `fisherman/fisherman` | +| [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell) | Follow the Linux, macOS, or Windows instructions and make **`pwsh`** available in Bash's `PATH`. Windows PowerShell's `powershell.exe` is not the runner's executable. No PowerShell version is pinned for this tier. | `tests/lint-ps1.ps1` and each `tests/unit/test-*.ps1` | + +The fixtures also use standard Unix tools such as `rsync`, `jq`, QEMU's +common/GUI utilities and `binutils`; individual suites may need additional +tools. For Debian/Ubuntu, this set is useful: + +```bash +sudo apt-get update +sudo apt-get install bats python3 rsync jq qemu-system-common qemu-system-gui binutils +``` + +Install Go, PowerShell and `just` through the linked instructions; this command +does not install them. macOS can run suitable portable lanes, but some fixtures +use utilities from Linux. On Windows, use a Linux development environment +(for example WSL) for the Bash fast tier; Windows-specific engine and WinUI +tests still need Windows. Native shell development has separate .NET and +Windows SDK requirements in [the shell guide](https://github.com/tuna-os/wootc/blob/main/docs/winui-shell.md). + +### Containers and Linux/KVM E2E are separate + +- Install [Podman](https://podman.io/docs/installation) for `just test-slow`. + On macOS/Windows, follow its `podman machine init` / `podman machine start` + setup. A Podman machine does not prove host support for privileged integration + tests on Linux or nested Windows/KVM E2E. +- For a Linux VM host, install QEMU utilities (`sudo apt-get install qemu-utils` + on Debian/Ubuntu, `sudo dnf install qemu-img` on Fedora). Confirm with + `qemu-img --version`. See [QEMU downloads](https://www.qemu.org/download/). +- `/dev/kvm` is a **Linux kernel capability**, not a downloadable tool. Enable + CPU virtualization in firmware, then check: + + ```bash + test -c /dev/kvm && test -r /dev/kvm && test -w /dev/kvm + ``` + + If the device is absent, load the appropriate module (`sudo modprobe kvm_intel` + or `sudo modprobe kvm_amd`). If you cannot access it, follow your distribution's + KVM group policy (commonly `sudo usermod -aG kvm "$USER"`, then log out and + back in). A VM host also needs nested virtualization exposed by its provider. + See [KVM setup](https://www.linux-kvm.org/page/RunningKVM). +- macOS and Windows do not expose Linux `/dev/kvm` directly. Full hosted E2E + uses the project's dedicated remote hosts and credentials; these + packages do not grant access. Read [agent lessons](https://github.com/tuna-os/wootc/blob/main/docs/agent-lessons.md) + and [E2E architecture](https://github.com/tuna-os/wootc/blob/main/docs/e2e-architecture.md) before you use that lane. + +There are no repository-pinned Podman or QEMU minimum versions. +Record the versions you used and their evidence. +Do not invent compatibility guarantees. + ## Building and testing -`just --list` shows all targets (needs `just`; the E2E targets also need -`podman`, `qemu-img`, and `/dev/kvm`). +`just --list` shows all targets. The prerequisites above distinguish the local +fast tier from container and VM work. The fast, no-container red-green loop for day-to-day changes: @@ -37,10 +102,11 @@ The fast, no-container red-green loop for day-to-day changes: just test # or: tests/run.sh fast ``` -This runs the bats unit suites (payload gates/transforms) plus `go test` for -the cross-platform Go packages. Windows-tagged Go (`app/*_windows.go`) only -builds on Windows by design, so this tier covers the platform-independent -code. +This runs the Bats, Python, PowerShell and Go lanes listed above. **A `PASSED` +summary with `!! ... skipping ...` warnings does not prove every suite ran.** +Retain the lane headers and skip warnings when reporting results. Windows-tagged +Go (`app/*_windows.go`) only runs on Windows; a Linux fast-tier pass does not +prove the Windows engine or the WinUI interface. Containerized integration tests (User Data Bridge, WSL, go-native gates) run in a privileged Fedora container and need `podman`: @@ -103,3 +169,7 @@ wootc is dual-licensed under GPL-2.0 and MIT (see `LICENSE-GPL-2.0` and Questions or stuck? Open an issue, or ask on [Matrix #tunaos](https://matrix.to/#/%23tunaos:reilly.asia). + +Use the [documentation index](https://github.com/tuna-os/wootc/blob/main/docs/README.md) to find role-specific references. +For deployment evaluation rather than source development, start with the +[IT-admin quick start](https://github.com/tuna-os/wootc/blob/main/docs/it-admin-quick-start.md). diff --git a/docs/wootc/RELEASING.md b/docs/wootc/RELEASING.md index f947bd7c..dd03e9b8 100644 --- a/docs/wootc/RELEASING.md +++ b/docs/wootc/RELEASING.md @@ -54,13 +54,14 @@ Windows is a good outcome; a walked-into-red user with a broken boot is not. Each item opens a gate when its matrix row passes: -- [x] yellowfin / bonito / marlin / flounder full three-phase → `status: green` -- [x] composefs-native (dakota) Phase-2/3 -- [x] Windows 10 + Home/Enterprise/LTSC editions -- [x] BitLocker FDE path (#34) → `BitLockerSupported: true` -- [ ] tpm2-luks root (#33) → offer encryption -- [ ] btrfs sealed Phase-2 (#35) → offer btrfs -- [x] custom OCI refs (once the deploy path is family-agnostic green) → `CustomImageAllowed: true` +- [ ] Current-candidate full matrix for all green catalog images (#222). +- [ ] Current-candidate BitLocker installation, editable Documents, save and persistence proof (#427); a refusal-path pass does not satisfy this. +- [ ] Offline VM acceptance before generic pre-download becomes default-on (#217). +- [ ] Verify Windows editions and native setups for brands on the same candidate (#240). +- [ ] Verify encryption/filesystem axes before you offer them; implementation or a historical closed issue is not new evidence. + +Several policy flags and paths for deployment exist on `main`. These +checkboxes track the evidence for acceptance, not code merges. When the **whole matrix** passes, `beta` becomes the default channel. The catalog then offers all images and lets users select custom references. @@ -69,11 +70,12 @@ The gates for each axis open as their issues close. ## Native shell release gates The [roadmap](https://github.com/tuna-os/wootc/blob/main/ROADMAP.md#native-shell-sequence-and-evidence-357) puts the -WinUI default change before 1.0. Phase B packages remain preview assets. -Phase C proved the native consumer journey, the VM journey, and full cycles. -Phase D now makes the native setup the primary release path and keeps the Wails -build once as `wootc-legacy.exe`. Phase E follows a clean native release and -the docs audit. +WinUI default change before 1.0. Phases B and C contain native packaging, +consumer and VM implementation, but their open trackers still require actual +acceptance evidence. Phase D's packaging cutover merged on 2026-10-31 and +prepares native setups plus one `wootc-legacy.exe` fallback. It has not changed +the assets of the latest full release, `v0.1.0-alpha.1`. Phase E follows a clean +native release and the docs audit; do not remove the fallback before that gate. A release cannot use old Wails passes as native UI or setup proof. Carry only component evidence whose engine code and contract did not change. Re-run the @@ -87,9 +89,36 @@ A shell or transport change needs fresh proof; its earlier streak cannot carry. Use the [run ledger](https://github.com/tuna-os/wootc/blob/main/docs/soak.md) for #235. Do not claim the #239 streak from a release list alone or from dates before these gates pass. +### Manual tests at a frozen ref + +Freeze a candidate branch at its full commit SHA. Keep that branch fixed until +all tests end. These workflows check out the selected ref. They have no +`source_sha` input. + +Use this test-only route before a release. It does not publish or waive release +or E2E gates. Keep `release_tag` empty for `winui-preview.yml`. + +```bash +repo=tuna-os/wootc +ref='' +sha='' +test "$(gh api "repos/$repo/commits/$ref" --jq .sha)" = "$sha" || exit 1 + +for workflow in ci.yml native-configuration.yml ste.yml \ + native-original-user.yml readonly-cli-status.yml offline-image-bundle.yml \ + vm-qmp-controls.yml vm-guest-observer-controls.yml; do + gh workflow run "$workflow" --repo "$repo" --ref "$ref" || exit 1 +done +gh workflow run winui-preview.yml --repo "$repo" --ref "$ref" -f release_tag= +``` + +Record each run ID. Accept the run only if its `head_sha` matches `$sha`. +Reject runs at any other SHA, even if they pass. A skipped gate does not count as proof. +These tests do not change the unsigned preview or GA policy. + ## Cutting a release -Releases are **E2E-gated**. The tagged gate uses Windows 11, Bluefin LTS, +Releases are **E2E-gated**. The tagged gate uses Windows 11, Bluefin `:stable`, BitLocker off, the native GUI install, and `phase3: true` on a hosted runner. It ends in graduated Linux and checks this run's file from Windows Documents. That final boot does not prove a Windows return after graduation. @@ -99,19 +128,49 @@ source SHA. Their proof covers the stages selected by that run. The `skip_e2e` input can waive the gate for an emergency dispatch. The release notes disclose that waiver. +### Named full release + ``` git tag v0.1.0-alpha.1 && git push origin v0.1.0-alpha.1 # → tests → native E2E gate (real Windows VM, bluefin:stable) → build + publish ``` -Every release ships the **full artifact set** from `release.yml` and the -workflow for native packages. The primary GUI downloads are one Inno setup per eligible +### Current-source prerelease + +A preview does not need to wait for the full GA matrix, winget submission or +30-day soak. Freeze a candidate branch and retain a fresh E2E gate for native code: + +```bash +gh workflow run release.yml --repo tuna-os/wootc \ + --ref -f release_tag= -f skip_e2e=false +``` + +The empty `release_tag` creates a `manual-vYYYYMMDD-` GitHub prerelease. +A nonempty tag is a full-release switch in this workflow, even if its name +contains `-alpha`. Do not use that switch for this preview route. + +This path tests the default alpha scenario, not every matrix axis. Configured +repository/environment policies still apply. An explicitly unsigned preview is +supported; do not claim Authenticode, SmartScreen, or fresh-machine acceptance. + +Native setup attachment is asynchronous. Wait for `winui-preview.yml`, +dispatched at the new tag, to finish its `publish-preview` job. +Check the expected setup assets and `native-SHA256SUMS`. +A green parent Release run with only boot/legacy assets is not a complete native download. +Count setup installation only when the E2E route reports `inno`. +Its file-copy fallback does not prove setup installation. + +### Artifact set + +The current workflows prepare the following **native artifact set**. This +describes a future release that passes its gates, not the published `v0.1.0-alpha.1`. +Its primary GUI downloads are one Inno setup per eligible brand: `wootc-Installer-Setup.exe`, `TunaOS-Installer-Setup.exe`, `Bluefin-Installer-Setup.exe`, `Bazzite-Installer-Setup.exe`, and `Aurora-Installer-Setup.exe`. Each setup installs the WinUI shell beside its protected Go engine and carries the release's public verification key. -This cut-over release publishes the Wails build once as `wootc-legacy.exe`. +The cut-over release is configured to publish the Wails build once as `wootc-legacy.exe`. It is a compatibility fallback, not a branded primary installer. It needs WebView2. @@ -202,12 +261,16 @@ A person must attach three screenshots, because a script cannot make them: ### Signatures and file identity -**No release has a signature yet.** [#229] is the choice and purchase of a -signature method. This is a spend decision for the maintainer. Until a -credential exists, each signature box is ✘. SmartScreen shows the wall for -unknown apps, and UAC shows "unknown publisher". +**Azure Trusted Signing is the selected signing path** ([#229]). The maintainer +must create the account and certificate profile, complete organization identity +validation, configure the Entra federated credential, and set the repository +variables listed below. Agents must not create those resources or handle the +credentials. Until that setup and fresh-machine verification pass, signatures +and SmartScreen acceptance remain unproven; a signing decision is not a signed +release. -The pipeline side ([#230]) is ready for any credential that #229 selects. +The pipeline side ([#230]) supports the selected service through jsign and +GitHub OIDC. See [the owner setup](#setting-up-azure-trusted-signing). The release step `Authenticode-sign the installers` runs `packaging/sign-exes.sh` after the build of the exes and before the step that writes `SHA256SUMS`. Authenticode changes the bytes of the file, so the diff --git a/docs/wootc/ROADMAP.md b/docs/wootc/ROADMAP.md index 6dffb756..be117fea 100644 --- a/docs/wootc/ROADMAP.md +++ b/docs/wootc/ROADMAP.md @@ -3,7 +3,7 @@ sidebar_position: 3 title: "Roadmap" --- -**Last updated**: 2026-10-15 | **Maintainer**: tuna-os (hanthor) +**Last updated**: 2026-11-02 | **Maintainer**: tuna-os (hanthor) --- @@ -45,18 +45,35 @@ for the work to restore the intended first experience. - **v0.3.0-beta milestone work (not released)**: The milestone issue #211 closed on 2026-09-02, but no `v0.3.0-beta` tag or release exists. Earlier work enabled the BitLocker policy and captured numerical keys for recovery. It resolved UAC identity to the interactive user and checked ownership of `wootc-data`. It added migrator plugins, JSON manifest schemas, and a runbook to take back a bad release (#211, #358, #354, #362). - **Later dependencies and tools**: Wails reached v2.16.0 (#384), and Vite reached v8.3.0 (#382). `golang.org/x/crypto` reached v0.57.0 (#381), and `golang.org/x/sys` reached v0.48.0 (#379). Direct tests cover the DTO generator (#378). The repository adopted the shared English check and Renovate preset (#374, #375). - Historical runs used the GUI and passed native deployment, Linux boot, and graduation on `bluefin:lts`. Those runs did not launch Linux inside Windows. -- **Release automation, three channels**: Tagged releases need an E2E gate. Dispatch inputs can select a tag without tag-push rights. Every green nightly can produce an automatic pre-release. Manual pre-releases also exist. Every release ships setup assets for the five eligible brands and deployer boot artifacts. The cut-over release also ships one Wails fallback, `wootc-legacy.exe`. It includes signed `SHA256SUMS`. +- **Release automation, three channels**: Tagged releases need an E2E gate. Dispatch inputs can select a tag without tag-push rights. Green nightlies can produce automatic pre-releases; manual pre-releases also exist. The native cutover code on `main` prepares setup assets, deployer artifacts, one `wootc-legacy.exe` fallback, and signed checksum manifests. This is a build contract, not the asset list of the published `v0.1.0-alpha.1`, which still ships Wails executables. - **First tagged release shipped**: [`v0.1.0-alpha.1`](https://github.com/tuna-os/wootc/releases/tag/v0.1.0-alpha.1) passed its E2E gate. The release workflow published it on 2026-08-22. - **Brand assets**: Marks, typefaces, and themes come from each project's published assets. Automatic screenshots show each brand (`docs/branded-walkthroughs.md`). `just` brand arguments support local and manual tests. - **Offline-first core**: Windows can pre-download OCI data and verify its digest. The deployer ingests that bundle. Its settled hook starts with a bounded wait for the network. Branded builds / `WOOTC_PRELOAD=1` support installation without a network during deployment on Wi-Fi-only laptops. - **Earlier user experience**: Windows appears on the boot menu, and users can re-arm a one-shot boot. Product boots have calm text. First login offers a welcome and a bookmark to the Windows drive. Add/Remove has an entry. Uninstall tries cleanup; complete restoration still needs proof. Guides exist in `docs/getting-started.md` and `docs/manual-testing.md`. - The winget package (`TunaOS.wootc`) supports automatic submission on full releases. It still needs the one-time `WINGET_TOKEN` secret. -**In flight**: RC validation and the pipeline for signed releases remain incomplete. Phase A of the WinUI 3 migration (#340) has merged: the Go engine supports `wootc.exe serve` JSON-RPC. Phase B (#343) delivered the native preview and hosted component proof. Phase C (#344) delivered the native consumer and VM journey. +**In flight**: RC acceptance and setup for signatures remain incomplete. Phase A of the WinUI migration (#340) added `wootc.exe serve` JSON-RPC. Phases B (#343) and C (#344) contain substantial native implementation and component checks. Their open acceptance trackers do not establish a complete VM journey on Windows. -Phase D (#345) switches release artifacts to branded Inno setup packages. It keeps one Wails release as `wootc-legacy.exe` and moves winget to `InstallerType: inno`. Phase E (#346) still covers the clean native release and legacy removal. +Phase D (#345) closed on 2026-10-31 after the merge of the native package cutover. The latest full release is still `v0.1.0-alpha.1`; it does not contain native setup assets. The post-cutover Secure Boot authority and publisher-policy defects in #688 block release acceptance. Phase E (#346) must retain the legacy fallback until a clean native release and its audit exist. -**Open defects and verification**: dakota hangs during its first Phase-2 boot (#209). Session token rewrap still needs verification after beta (#1). Console flash repair (#179) is historical; maintainers closed the issue. +**Open verification**: #596 retains the VM-first requirement for RC, which the maintainer reaffirmed on 2026-10-30. Closure of #178 does not supply desktop, persistence, or same-system promotion evidence. Dakota's historical hang tracker #209 and the earlier epic for GUI reliability #399 have closed. Their red rows in the old matrix remain historical, not proof of a new pass. Session migration remains open under #1 and its target-side import issues. + +### Working-tree follow-up — 2026-11-02 + +The source work groups the 58 open issues into these workstreams. This is a source-work +record, not issue closure, a released artifact, or an upgrade of the matrix. + +| Workstream / issues | Source work and remaining acceptance boundary | +|---|---| +| Native release: #688, #346, #344, #343, #340, #304 | Release-bound shim authorities/publisher metadata, editable profile mappings and native boot-summary/proof controls. Signed Windows setup/UIA/full-cycle proof and upstream decisions remain required; legacy removal waits. | +| Installation safety: #427, #285, #279, #197 | Canonical fail-closed BitLocker staging/scrubbing, profile collision handling, ordinary-user Documents copying, retained recovery authority and owned uninstall/power state. Real encrypted editing/restart and Windows interruption/restore proof remain required. | +| Sessions: #1, #252, #253, #254, #255, #256, #257, #258, #259, #293, #294, #295, #296, #420 | Consented encrypted-envelope import, bounded Chromium stores, explicit Linux keyring backends, preservation/recovery rules and shared detection. Unsupported formats refuse; Spotify and real authenticated application journeys remain open. ADR 0005 remains proposed. | +| VM-first: #596 | Read-only installed-target boot-input export with identity/hash checks and durable state, plus startup-state repairs. Windows-hosted desktop/persistence acceptance, host promotion preflight and transactional native handoff remain open; export does not arm boot. | +| Hardware/catalog: #576, #574 | Pinned upstream catalog plus explicit consumer policy; target-module/firmware compatibility checks before Windows mutation. Unknown observations warn rather than imply support; real hardware acceptance remains required. | +| Architecture: #588, #587, #545, #518, #380, #297 | Install-policy seams, shared progress catalogue, credential-safe diagnostics, sourceable deployer modules and layer-specific evidence. Broad extraction and full product-layer acceptance are not implied by these boundaries. | +| Documentation: #544, #541, #539, #233 | Contributor/toolchain guidance, categorized index, protocol/consent/grant contracts and current-release truth corrections. Candidate walkthrough and docs-vs-release verification still need the candidate artifact. | +| Release gates: #367, #241, #240, #239, #237, #234, #229, #222, #221, #217, #213, #212, #24 | Native proof producer/strict soak verifier, audit follow-up and release prerequisites. Azure provisioning, winget moderation/token, complete matrix/offline/hardware proof and an actual 30-day soak cannot be replaced by component tests. | +| Adoption: #598, #595, #594, #592, #591, #590, #586, #302 | Approval-gated cohort/outreach, WSL and administrator material. No recruitment, publication, partnership, upstream approval or participant success is claimed. | --- @@ -74,7 +91,7 @@ The VM has been the world so far; this milestone makes real laptops the evidence - Maintainer + early-tester manual runs per `docs/manual-testing.md`, with a field-report issue template; every report triaged to green/fixed/filed. - Offline proof: `offline=on` matrix axis (`-nic none`), then `preloadImage` default-on for the generic build. -- Find the cause of the dakota hang in Phase 2 (#209). Demote catalog status when evidence does not support it. +- Re-verify Dakota on the candidate build after closure of the historical tracker for the Phase-2 hang (#209). Catalog status still needs current evidence for acceptance. - No console flash on launch (#179) — the first second must look intentional. - Harness reliability: QGA-channel loss classified and retried, WU neutralization proven across editions. - Upstream must accept the first winget submission. @@ -95,7 +112,7 @@ Beta means the support policy stops saying "alpha" because the evidence exists. - **Signed binaries**: The maintainer chose `Azure Trusted Signing` (#229). The release workflow can sign with it after the Azure setup in `docs/RELEASING.md`. Verify publisher identity and fresh-machine SmartScreen behavior (#230). A valid signature alone does not guarantee that SmartScreen lets a launch proceed without a prompt. - **WinUI 3 shell replaces Wails (#340)**: phases B–D must pass their native gates before the RC default changes. Phase E follows a clean native release. The [sequence for the native shell](#native-shell-sequence-and-evidence-357) defines which earlier evidence can carry forward. -- **VM-first (#178)**: Required first experience. Prepare and run the persistent Linux image inside Windows before native boot. [ADR 0004](https://github.com/tuna-os/wootc/blob/main/docs/adr/0004-restore-vm-first-product.md) replaces the #318 deferral; current releases do not yet meet this gate. +- **VM-first (#596, formerly #178)**: Required first experience, reaffirmed by the maintainer on 2026-10-30. Prepare and run the persistent Linux image inside Windows before native boot. [ADR 0004](https://github.com/tuna-os/wootc/blob/main/docs/adr/0004-restore-vm-first-product.md) replaces the #318 deferral; the full Windows-hosted desktop, persistence, and native-promotion gate remains unproved. - **Migration adapters (#203)**: Discovery and manifests exist. The [extension plan](https://github.com/tuna-os/wootc/blob/main/docs/specs/migration-extensions.md) adds truthful results, transactions, compatibility, and scoped execution before broad support. - **Boot-chain work from Libertix (#308)**: [Libertix](https://github.com/ekimiateam/libertix) also installs Linux from Windows. It uses real partitions; wootc uses `root.disk`. Its geometry code does not apply, but its reboot designs help. `docs/borrowed-from-libertix.md` defines six items. They cover Secure Boot CA preflight (#322) and recovery guard (#331). They cover evidence of first boot, checked from Windows (#332), and ESP signed-chain refresh (#333). They also need one catalogue of steps with a CI diff (#334) and pinned, signed artifacts (#335). - Complete the docs and verify their claims end-to-end. Regenerate walkthrough images from the release build. @@ -155,9 +172,8 @@ Verify all four criteria at the top of this file. All 30 days of nightlies must | Item | Issue | Priority | |------|-------|----------| | Session token rewrap verification | #1 | P2 (v0.9.0-rc validation; beta gate resolved via staged re-link #347) | -| Program migrator plugin architecture | #203 | P2 (rc decision — delivered in #354) | -| E2E runs as systemd user units instead of nohup jobs | #57 | P2 | -| VM-first persistent Linux inside Windows | #178 | Product priority; incomplete, required before the VM-first claim | +| Migration adapters | #258, #296 | Finish target-side orchestration and truthful import outcomes; the plugin architecture itself was delivered in #354 | +| VM-first persistent Linux inside Windows | #596 | Product priority; acceptance remains required despite #178 closing | ## How to contribute diff --git a/docs/wootc/adoption-outreach.md b/docs/wootc/adoption-outreach.md new file mode 100644 index 00000000..948dcfdb --- /dev/null +++ b/docs/wootc/adoption-outreach.md @@ -0,0 +1,185 @@ +--- +sidebar_position: 7 +title: "adoption outreach" +--- + +This file combines requests in #586, #590, #591, #592, +# 594, #595 and #598 under [the external cohort gate](https://github.com/tuna-os/wootc/blob/main/docs/alpha-adopter-program.md) +and [the upstream review process](https://github.com/tuna-os/wootc/blob/main/docs/upstream-blessings.md). These drafts +and rules are **not** evidence of recruitment, partnerships, publication +or a successful migration. This file does not authorize outreach. + +Do not repeat issue-body claims that a tag or closed milestone proves a complete +user journey. Check [current status](https://github.com/tuna-os/wootc/blob/main/docs/status.md) and retained evidence for the +exact release. Do not advertise “zero data loss”, “fully undoable”, identical +accounts, universal game compatibility, enterprise support or a completed +VM-first experience without the corresponding acceptance evidence. + +## Channel strategy + +The first five-person cohort uses the existing tunaOS Matrix community after +a maintainer names the room, intake owner and dates. Other channels below are +**candidates for a later, expressly approved campaign**, not places already +contacted or permission to broaden the cohort. Use existing warm relationships +and current community rules; moderators may decline. Do not send unsolicited +DMs, scrape membership, or cross-post the same advertisement. Do not use help +threads to promote the project. + +| Candidate audience/channel | Value-first material | Permission and stop condition | +| --- | --- | --- | +| Existing tunaOS Matrix community | One small-cohort invitation with trust/recovery limits and reporting instructions | Maintainer approves launch and room/rules; pause at five accepted testers or any recovery/data-loss concern. | +| GitHub Discussions | A pointer to the approved invitation and a place for migration questions | Repository admin enables/chooses a category and assigns moderation first; do not advertise an unstaffed support SLA. | +| WSL community (for example r/bashonubuntu) | The WSL guide, explaining exactly what is and is not imported | Confirm subreddit spelling/current rules and moderator permission where required; answer a relevant question only when useful, with project affiliation disclosed. | +| Windows administrators/homelab (for example r/sysadmin or r/homelab) | A supervised pilot checklist and honest recovery boundaries | Obtain any required moderator approval; never present the consumer app as a fleet tool or cold-promote in unrelated questions. | +| Gaming, hardware-reuse or educational communities with an existing relationship | Workload compatibility checklist and a recoverable spare-PC trial | Community owner approves; no claim that old hardware, anti-cheat games or school devices are supported without evidence and device-owner permission. | + +A campaign owner records the approved venue, date, exact published text/link and +aggregate responses in the cohort tracker. Do not retain contacts or handles in +public artifacts. WSL background is optional and self-described. Count +responses, tries and completions without pixels that track people, private +demographics or installation telemetry. + +The owner may report aggregate downloads of branded assets. +These counts do not establish people, tries or successful journeys. + +## Cohort invitation + +**Draft, not sent.** The intake owner fills all factual details from the approved +tracker before publication; if anything below is unavailable, do not post. + +> We seek five volunteers from outside the wootc contributor team. +> All must be adults. They will try a supported Windows-to-Linux journey on a +> spare/recoverable PC. We especially welcome people who describe themselves +> as non-technical users of Linux. Participation is optional. +> You can stop or decline without explanation. + +> This is early boot software, not a promise of a safe production migration. +> The Windows binary has no signature; SmartScreen or policy may block it. +> Installation changes boot settings/files, and some storage plans change +> partitions. Windows return and uninstall can fail. Keep an independent, +> verified backup and recovery arrangements; never bypass organizational policy. + +> The named intake owner will supply the exact approved tag, asset and checksum +> manifest from the cohort tracker. The owner will also supply the supported +> image/storage path, matching instructions, dates and contact. +> The journey is download → launch → Linux login → Windows return → Linux +> re-entry → uninstall/restoration → report. +> Stop if the documented steps do not match the screen or data/recovery looks wrong. + +> Public GitHub reports expose your account; public participation is not +> anonymous. You may instead ask the intake owner to post a sanitized +> summary with your consent. Never share keys, account details or raw logs. +> The owner publishes only aggregate cohort counts and removes temporary +> participant records at the gate decision. + +> You can withdraw before publication. The owner cannot promise that others +> will erase copies they have already made public. +> See the approved tracker for build links, dates and the intake owner, and the +> [program](https://github.com/tuna-os/wootc/blob/main/docs/alpha-adopter-program.md) +> for eligibility, evidence and privacy boundaries. + +## WSL graduation article + +**Publication draft for the tunaOS site, not a published blog post.** A site +editor must approve the final copy. The editor must replace links that change +with the campaign's reviewed instructions. The title does not promise that all +data or accounts travel automatically. + +### From WSL to native Linux: keep your starting point + +If you already use Linux tools in WSL, a native Linux desktop may be a useful +next experiment. It is a separate system, not the same WSL installation booted +on bare metal. wootc installs a bootc Linux system beside Windows on supported +configurations. You can test the workflow and keep the original system. + +Start with a recoverable PC and independent backups. Export each needed WSL +distribution, keep Windows/WSL installed, and check the release's current limits. +The helper can copy selected dotfiles and propose some development packages; it +does not import your entire distribution, projects, databases or sign-in state. +Review configuration for secrets and rebuild one real work task. +Then decide whether the new setup fits. + +The practical checklist is [Coming from WSL](https://github.com/tuna-os/wootc/blob/main/docs/wsl-migration.md). For the current +release's actual evidence, read [status](https://github.com/tuna-os/wootc/blob/main/docs/status.md). For an approved alpha +cohort, your report matters even when you stop at a trust prompt. +Report a mismatch in the documentation, too. A verified Windows return and +uninstall are part of the experiment, not an afterthought. This is a trial of +real usability, not a claim that every WSL user can already graduate safely. + +## Windows workflow and branded-distro pathways + +We propose these choices, not endorsements or approved partner campaigns. +Every third-party brand remains subject to its +[recorded permission and compatibility review](https://github.com/tuna-os/wootc/blob/main/docs/upstream-blessings.md). +Use the project's own hardware/application guidance as well as wootc's matrix. +A branded executable does not grant support for all its images. + +| Audience | Possible pathway | Questions to resolve before migration | +| --- | --- | --- | +| Developer considering Bluefin | Follow the WSL export → supported image → selected config import → rebuild one project procedure in [the WSL guide](https://github.com/tuna-os/wootc/blob/main/docs/wsl-migration.md). | Is this exact Bluefin/Bluefin LTS/Dakota image admitted for the release and hardware? Are runtimes, container workflows, VPN and required credentials re-established? No whole-WSL/account transfer claim. | +| Gamer considering Bazzite | Check the exact hardware/image, back up saves, retain Windows and test one required game on Linux before relying on a library bridge. | Does that game's current anti-cheat/launcher/DRM permit Linux/Proton? Is the original library readable and supported by the bridge? Confirm saves and Windows return. No promise that every game works or that in-place reuse never requires downloading. | +| Productivity user considering Aurora | Choose a supported desktop/image, test real documents and peripherals, then compare the work task in both systems. | Do fonts, document formatting, macros, meetings, printers and accessibility work? The Office settings helper is not a Microsoft Office runtime, license transfer or complete conversion. | + +**Office FAQ:** LibreOffice or OnlyOffice may suit a workflow. +Check compatibility on copies of the user's actual documents. Keep originals and +Windows available; do not promise macro fidelity or automatic app-license transfer. + +**Gaming FAQ:** Wine/Proton and access to library files do not make every Windows +game playable. Use current game/upstream guidance and report real outcomes. + +**DevOps FAQ:** Reinstall tools through the destination distribution's supported +methods. A generated Brewfile is only a partial proposal, not environment parity. +Re-enroll secrets through approved processes; do not publish configurations or +customer code as evidence. + +## Three case-study and walkthrough briefs + +These are **scenario briefs that need real volunteers**, not fabricated +case studies. They cover the developer, gamer and power-user asks in #586 and +the specialist story in #591. A real study/video needs consent, a named editor, +an exact tested build and actual results. Images, quotes or details that identify +people need separate approval for publication. An unsuccessful trial needs +consent and an accurate description before publication. + +Never stage a pass, invent a quote or promise a walkthrough video before you +record it. + +1. **Developer beyond WSL.** Record the initial distribution/workload privately + and verify an export. Install a supported image and show the limits of + selected dotfiles. Rebuild a non-sensitive project and compare outputs. + Show Windows/WSL return, Linux re-entry and uninstall/restoration. + Report assistance and absent packages or files, not only a successful shell prompt. +2. **Gamer with Bazzite.** Check image/hardware and game compatibility. + Back up saves and show actual library discovery or its absence. + Test a game that lets you play on Linux and verify saves on both systems. + Record any downloads the game still needs. Finish Windows return and + uninstall; do not characterize library visibility as playability. +3. **Power user or migration specialist with Aurora.** Use the + [administrator pilot](https://github.com/tuna-os/wootc/blob/main/docs/it-admin-quick-start.md) on a spare machine with permission. + Open copies of representative documents and exercise one peripheral/network task. + Compare the data retained on Windows, and record return and uninstall checks. + Do not generalize that result into a fleet or enterprise success story. + +For each video, capture the actual build identity and download verification, +trust/UAC prompts, proposed storage plan, Linux task, Windows return, re-entry +and uninstall proof. Redact keys, names, notifications and customer data **before** +publication; do not run a camera over an unreviewed recovery-key screen. Link the +sanitized field report and actual outcome so edits to footage cannot hide a +failure. Retain the original evidence only through an approved process for +storage/consent, not in git. + +## Human decisions and ownership gaps + +| Issues | Repository material | Required human action before acceptance | +| --- | --- | --- | +| #302, #598 | Cohort eligibility, intake, privacy, aggregate tracker and gate | Maintainer assigns intake/deputy, approves tag/channel and new dates, opens/links tracker, provides actual recruitment counts and qualifies the exact journey. The October #302 comment's dates were proposed, not approved. | +| #590 | Invitation and five-person/three-independent-completion rules | Authorized owner posts the approved invitation in Matrix and any enabled Discussion, recruits five consenting non-contributors (including two non-technical Linux users), triages actual reports within two working days, and records proceed/repeat/stop at #210. | +| #595 | WSL guide, article draft and optional aggregate WSL funnel | Documentation/site editors review and publish; community owner authorizes any warm-channel sharing. Real consenting WSL volunteers and evidence are required for success stories. | +| #591 | Administrator guide and supervised pilot/case-study brief | Repository admin chooses/enables a migration Discussion category and moderation; community owner approves any forum response/content; a real pilot with consent is required for a case study. | +| #594, #592 | Per-brand review packet and explicit approval procedure | Maintainer appoints liaison; authorized Bluefin/Bazzite/Aurora owners review branding and images and provide durable decisions; release owner enforces approval gating, signing/provenance and support ownership; upstream chooses whether to link or co-promote. | +| #586 | Channel plan, three workflow briefs, FAQs and partner process | Campaign editor obtains participant/publication consent and records real videos/results; upstream approves any branded messaging; maintainer supplies winget credentials and completes actual generic-package submission/review. Branded namespaces require separate permission, not merely a token. | + +Drafts, a tracker or a label are not external evidence. +These repository artifacts do not send invitations, post to forums, request +upstream approval or change a Discussion category. They do not publish to a +site, supply secrets or submit packages to winget. diff --git a/docs/wootc/agent-lessons.md b/docs/wootc/agent-lessons.md index 935a3207..77eceb84 100644 --- a/docs/wootc/agent-lessons.md +++ b/docs/wootc/agent-lessons.md @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 title: "agent lessons" --- @@ -863,3 +863,70 @@ threshold of 23,502,050,623 bytes. The experiment's former 8 GiB node guard was The [recorded result](https://github.com/tuna-os/wootc/blob/main/docs/experiments/evidence/2026-09-26-vm-first/windows-helper-storage-stop.json) retains the empty helper receipt and the harness termination reason. No claim of an installed desktop or a complete installation follows from this run. + +## 36. Ordinary unit tests must not control their Windows host + +The full test gate for the Windows app module exposed a safety defect in source. +Untagged tests for non-Windows dev stubs called production code on Windows. +That code could restart the host, change partitions, power and boot/ESP state, +uninstall the product, and collect credentials. +An RPC smoke test for method inventory also invoked real reboot, +defragmentation, uninstall, and boot actions. + +An assertion that expects a platform error does not isolate the host. +A successful `shutdown /r /t 5 /f` schedules the restart before the assertion can fail. + +- Delete obsolete stub/no-op checks and checks that invoke every method. + Do not substitute test-mode no-ops in production or record mock echoes. +- Preserve refusal by the protocol, replay, cancellation, ownership, and behavior for corrupt state. + Use owned temporary paths and existing dependency boundaries. + Never remove or overwrite `C:\wootc` files merely to clear a test fixture. +- A cancelled install-engine test still enters preparation before its first + step. Supply an isolated platform fixture, not the real preparation adapter. +- Transport tests must not run unrelated startup discovery. + The uninstall probe on Windows validates existing installation trees and reapplies their root ACL. + Construct the transport's App directly instead. +- Keep the full Windows `go test ./...` gate. + Narrow selectors for methods can hide cross-platform hazards; they do not repair them. + +The runner lost communication during a full-suite try. +Its final test log and Windows restart events were unavailable. +These call paths establish a real risk of host actions. +They do not establish the cause of that particular runner loss. + +## 37. Platform contracts need platform evidence + +The full Windows module on 2026-11-02 exposed defects in file access and fixtures. +Linux checks and Windows cross-builds did not detect them. + +- Use `internal/privatefile` for private JSON and Ed25519 seeds. + Windows needs a protected ACL before the first byte. + Elevated state keeps BA ownership and BA/SYSTEM access. + An ordinary generator keeps access for its effective user. + Refuse unsafe existing files before truncation; do not repair their ACL. +- Preserve the exact catalog bytes on checkout. + A targeted `.gitattributes` rule keeps the snapshot at LF. + Do not normalize bytes before their hash check or change the reviewed digest to fit CRLF. +- Manifest readers on Windows need `FILE_SHARE_DELETE`. + Use the scoped content reader for ownership snapshots. + State identity pins must still block replacement. + A held destination handle can still block replacement. + Refused publication must preserve old claims and stop payload changes. + + Join each test writer before the test returns; report errors in the owner goroutine. + This does not guarantee atomic writes on every FAT32 implementation. +- Create an owned HKCU parent for a registry fixture. + Leave guarded creation of the leaf to production code. + Keep refusal controls for foreign and unmarked keys. +- Resolve aliases in each Windows path for a fixture before you bind identity. + Create a private proof directory for a local test. + Retain the driver's explicit destination when it supplies one. +- Open a secret observer with the required share flags on Windows. + Close it before final path checks. +- Compare paths with the same separator after platform cleanup. + Keep the boundary checks for sibling directories and foreign drives. +- Test consumer outcomes, not producer source or generated copies. + Do not rewrite the checkout to compare source bytes. + +Run the actual program on Windows before a release. +A successful Linux smoke or cross-build does not supply that evidence. diff --git a/docs/wootc/alpha-adopter-program.md b/docs/wootc/alpha-adopter-program.md index 78bb8a35..5be7d2d2 100644 --- a/docs/wootc/alpha-adopter-program.md +++ b/docs/wootc/alpha-adopter-program.md @@ -1,11 +1,21 @@ --- -sidebar_position: 8 +sidebar_position: 9 title: "alpha adopter program" --- -**Status:** proposed for `v0.2.0-alpha` -**Owner:** maintainer to assign -**Tracking:** [#302](https://github.com/tuna-os/wootc/issues/302) +**Status:** no evidence of recruitment; maintainer must decide whether to launch +**Owner:** maintainer to assign before invitations +**Issues:** [#302](https://github.com/tuna-os/wootc/issues/302), +[#590](https://github.com/tuna-os/wootc/issues/590), +[#598](https://github.com/tuna-os/wootc/issues/598) + +As of 2026-11-02, the field-report template is present at +[manual-test-report.yml](https://github.com/tuna-os/wootc/blob/main/.github/ISSUE_TEMPLATE/manual-test-report.yml). +The assigned recruitment issues contain no participant counts or completed +external reports. That means **unknown**, not zero participants or a passed +gate. The October 11 comment on #302 proposed October 15–November 1 recruitment +and a November 15 decision; those were proposals, not approved dates. +Release tags, closed milestones and first-party runs do not satisfy this gate. ## Purpose @@ -31,6 +41,12 @@ Recruitment starts only after all of the following are true: - the manual-testing protocol includes Windows return and uninstall checks; - one named maintainer owns intake and acknowledges new reports within two working days. +- the selected build's [status](https://github.com/tuna-os/wootc/blob/main/docs/status.md) and manual protocol match the UI and supported image/storage path. + A legacy protocol does not qualify a native WinUI or VM-first journey; +- the owner opens an [aggregate cohort tracker](https://github.com/tuna-os/wootc/blob/main/.github/ISSUE_TEMPLATE/alpha-cohort.yml) + and links it from #302 and #210. + The owner enters the release, channel, dates for recruitment/reports, and owners for intake and deputy duties. + The owner must explicitly approve the launch. ## Cohort and recruitment @@ -39,10 +55,50 @@ of Windows 10 and 11, hardware vendors, Secure Boot states, and comfort levels. At least two participants should describe themselves as non-technical Linux users, matching the project's stated audience. -Use one declared recruitment channel first (for example the tunaOS Matrix -room). Record only the channel and invitation count; do not publish participant -identities. Do not broaden recruitment until the first five reports have been -triaged. +The first channel is the existing tunaOS Matrix community, after a maintainer +confirms the room and its rules. A GitHub Discussions notice may point to the +same invitation after approval; it is not a second uncontrolled cohort. +Do not send unsolicited direct messages or scrape members. Do not broaden +recruitment until the owner has triaged reports from the first five accepted testers. + +### Eligibility and stopping rules + +- Adults who explicitly volunteer and are not wootc contributors. + A school or organization must give permission before its users take part. +- A spare or recoverable physical PC with Windows 10/11, x86-64 and UEFI. + The participant must have permission to install software and change boot settings. +- A verified independent backup and a way to recover Windows. + Access to any required recovery key, plus power and time for return/uninstall checks. +- Only the image, Secure Boot, encryption and storage combinations admitted + by the chosen release's policy. Do not change encryption or company policy + to qualify. Include different **supported** Secure Boot states when possible. +- Exclude a sole PC for important work/school use, managed devices without permission, and PCs without recovery arrangements. + Exclude unsupported configurations for storage/encryption. + +Participation is optional and may stop at any stage. A decline or withdrawal +needs no explanation. Stop for a documentation mismatch, unexpected partition +plan, missing data, blocked Windows return or uncertain recovery. + +Preserve evidence, report it, and wait for the intake owner. Do not try commands +from chat. Suspected data loss or a recovery failure pauses new runs and +recruitment until the maintainer records a safe resolution. + +### Common participant brief + +In the approved invitation, the owner supplies the exact tag, asset URL, +checksum manifest and status link. The owner also supplies the +matching [user guide](https://github.com/tuna-os/wootc/blob/main/docs/user-guide.md), [manual protocol](https://github.com/tuna-os/wootc/blob/main/docs/manual-testing.md), +report-form link, report due date and intake contact. +Use the draft in [adoption outreach](https://github.com/tuna-os/wootc/blob/main/docs/adoption-outreach.md#cohort-invitation). +Never substitute a moving `latest` link for a pinned test build. + +Explain before download: this is early Windows software without a signature. +SmartScreen or organizational policy can block it. Checksums do not identify a +publisher. Installation changes startup files and settings; some paths can +change partitions. Recovery and uninstall can fail. + +There is no zero-data-loss guarantee. No one needs to weaken a security policy +or continue past a warning. ## Participant journey @@ -61,32 +117,77 @@ longer matches the screen. That mismatch is an adoption finding. ## Evidence ledger -Maintain an issue comment or milestone table with one anonymous row per -participant: +The intake owner keeps one row locally for each participant who consents. +These temporary rows use random aliases, not account names or related identifiers. +Do not put those rows, contacts or maps from aliases to accounts in git or public issue comments. +Keep only the data needed to count each independent journey once: | Field | Allowed values | | --- | --- | -| Invitation | accepted / declined / no response | -| Download | reached / blocked | -| Launch | reached / trust-blocked / other-blocked | -| Linux first login | reached / not reached | +| Invitation channel | declared Matrix channel / approved referral | +| Invitation | accepted / declined / no response / withdrawn | +| Background, voluntary | WSL / new to Linux / other / not stated | +| Attempted journey | not started / download / launch / native install / VM-first (if qualified) | +| Download | reached / blocked / not attempted | +| Launch | reached / trust-blocked / other-blocked / not attempted | +| Linux first login | reached / not reached / not attempted | | Windows return | verified / failed / not attempted | +| Linux re-entry | verified / failed / not attempted | | Uninstall restoration | verified / failed / not attempted | +| Blocker | none / trust / preflight / storage / firmware-boot / network / migration-data / docs-usability / recovery-uninstall / other | | Outcome | passed / product defect / docs defect / environment / abandoned | -| Follow-up | linked issue or none | - -Publish aggregate counts only. Do not collect names, email addresses, recovery -keys, machine serial numbers, logs containing account names, or telemetry from -the installed system. Participants choose what to attach to their report after -reviewing it. +| Follow-up | sanitized issue link or none | + +An unattempted checkpoint is not a pass. A retry counts as one person, not a +second independent journey. If a maintainer intervenes, record the journey as +assisted. Do not present it as an independent completion. + +Publish **aggregate counts only** in the tracker. +Count invitations, acceptance, declines, no response, withdrawals, tries, +downloads, launches and first logins. Also count Windows returns, Linux +re-entries, verified uninstalls, independent completions, assisted completions +and blockers by category. + +Add separate links to sanitized reports. Do not link an individual report to +its private cohort alias. For #595, optionally count responses, tries and +completions by WSL background. Do not use pixels to track people or installer +telemetry. Omit small breakdowns by background/hardware that would identify a +participant. + +Never request names, email addresses, serial numbers, passwords, recovery keys, +private keys or raw logs with account names. Public reports on GitHub are not +anonymous: explain this before the participant opts in. They may decline to +file a public report. With consent, the owner can file a sanitized summary instead. + +Participants review every attachment. At the gate decision, delete temporary +participant rows and contact maps. Retain only aggregate counts and sanitized +reports with consent. For a withdrawal, remove unpublished rows and update +aggregates. Explain that the owner cannot promise that others will erase copies +of public GitHub data. + +## Feedback ownership + +The named intake owner (or named deputy) acknowledges reports within two +business days of submission. This is a launch prerequisite, not a service that +an unstaffed program already offers. For each report, record: + +1. Checkpoint and blocker category, exact tested build, and whether the participant + needed assistance or a retry. +2. Triage as green, fixed, or filed. For fixed, link the change and a real rerun. + For filed, link the issue and name the responsible owner and next action. + Do not mark filed as fixed. +3. For any data-loss/recovery concern, pause and escalate to the maintainer. +4. Link product/doc fixes back to the aggregate tracker. + Get a new report before a failed journey can count as complete. ## Exit criteria The external-adoption portion of the real-hardware gate is satisfied when: -- five external testers have accepted an invitation; -- at least three independently complete first login, Windows return, and - uninstall restoration; +- five external non-contributors have accepted an invitation. + At least two describe themselves as non-technical users of Linux; +- at least three independently complete first login, Windows return, Linux + re-entry, and uninstall restoration on the pinned supported journey; - every unsuccessful journey has a blocker category and a linked issue when the cause is in wootc or its documentation; - no unresolved data-loss or recovery blocker remains; and diff --git a/docs/wootc/architecture-boundary.md b/docs/wootc/architecture-boundary.md index 473170fc..80f1255a 100644 --- a/docs/wootc/architecture-boundary.md +++ b/docs/wootc/architecture-boundary.md @@ -1,5 +1,5 @@ --- -sidebar_position: 9 +sidebar_position: 10 title: "architecture boundary" --- @@ -15,15 +15,16 @@ that turns an attached empty block device into a bootable Linux root. | Component | Notes | |---|---| -| Windows installer GUI + headless CLI (`app/`) | Catalog entries are opaque references handed to the deployer; the pipeline (root disk, ESP chain, BCD, vault, state.json) never inspects them. | +| Windows installer adapters (`app/`) | Wails, headless and RPC adapt into the shared install policy and engine. Image policy/hardware assessment is separate from the provisioner that installs the target. | | Boot chain | BCD one-shot → signed shim+grub → kernel on ESP. Wubi-style; nothing bootc about it. | -| Root-disk hosting | NTFS-hosted VHDX/raw file + dracut attach hook (`platform/dracut/99wootc-boot`). Zero bootc references. | -| User Data Bridge (`payload/migration/`) | Passthrough binds, Steam bridge, browser import, folder conversion, polkit policy. Zero bootc references (3 grep hits are comments). | +| Root-disk hosting | NTFS-hosted raw disk and dracut attach hook (`platform/dracut/99wootc-boot`); managed VM and native paths have distinct readiness gates. | +| User Data Bridge (`payload/migration/`) | Windows-folder links, copies, Steam bridge, browser import, conversion and policy; preserve existing target content independently of deployment backend. | | Migration dashboard | Reads bridge state files; distro-agnostic. | | `state.json` lifecycle contract | Deliberately generic vocabulary (staged/armed/deploying/deployed/healthy/failed). | | E2E harness (`tests/e2e/`) | Drives Windows, QGA, serial; image ref is a passthrough string. | -**bootc-specific (currently ~50 references, all inside `payload/deployer/deploy.sh` + fisherman):** +**bootc-specific:** current deployment and verification in +`payload/deployer/deploy.sh`, the VM builder, and fisherman include: - fisherman itself (recipe → `bootc install to-filesystem`). - Post-install verification: ostree deploy-root discovery @@ -38,7 +39,7 @@ that turns an attached empty block device into a bootable Linux root. ## The provisioner contract (adaptation seam) Someone porting wootc to another deployment method replaces one stage. -Contract, as deploy.sh already implicitly defines it: +Contract, as `payload/deployer/deploy.sh` defines it: **Input:** an attached, empty block device; a recipe `{image/source, hostname, filesystem, user{name, password_hash}, flatpaks?, luks?}`. @@ -59,6 +60,98 @@ Everything else in deploy.sh — disk discovery, NTFS mount, scratch, telemetry/heartbeat, vault ingest/shred, User Data Bridge install, ESP sync mechanics, state.json, reboot — is orchestration and stays. +## Shared policy, engine and diagnostics + +`app/install_policy.go` checks admission with explicit dependencies for the +system, catalogue, platform, space and profile, not `App`/frontend state. +`app/install_engine.go` owns the execution sequence. Wails, CLI and RPC must not +grow a second copy of policy or privileged install operations. Preparation +stages the image and checks hardware before Fast Startup changes or +creation of `root.disk`. A hardware warning or partial inventory is not a +compatibility pass; see [the user guide](https://github.com/tuna-os/wootc/blob/main/docs/user-guide.md#hardware-warnings-are-not-compatibility-certificates). + +### E2E layer attribution + +`tests/e2e/lib/layer-evidence.sh` and `layer-evidence.py` separate infrastructure +evidence from Windows-installer/deployer attribution. They are sourceable +adapters, not a second result ledger: all assertions/failures delegate to the +existing `results.sh` / `results.py` authority. A fresh QGA +`guest-info` response within the size limit proves only that infrastructure responds. + +Deployer attribution also needs the current run's reset result. +It then needs the exact OEM `RunId` receipt or an existing authenticated `gui-install` +assertion, plus the selected image and fresh, ordered deployer-started/lifecycle metadata. +An old receipt, a mismatch in image identity or a guest that responds cannot supply +that attribution. Even valid attribution never satisfies deployed-system, +Linux-boot, root-disk or user-data assertions; those retain their independent +observations. `tests/unit/test_layer_evidence.py` covers the adapter behavior, +but this documentation update does not claim that suite or a VM run passed. + +### Engine and deployer diagnostics + +`app/migration_diagnostics.go` will emit records locally as JSON to **stderr**, never RPC +stdout. Records carry `timestamp`, `attemptId`, stable `phase`, `event`, +`duration_ms` and optional `error_code`. Phases include `prepare`, phase IDs from +the generated installer, `commit` and the outer `install`; events are +`phase_start`, `phase_complete`, `phase_error` or `phase_cancelled`. +The only failure codes are `operation_failed` and `cancelled`. This channel +excludes configuration in raw form, passwords, paths, subprocess errors and session +material; the protected journal/lifecycle records remain the recovery authority. +A diagnostic sink failure must not change the privileged operation's outcome. + +The deployer packages sourceable `/usr/libexec/wootc-initramfs-lib.sh` +(`find_ldso`, `dso_closure`) and `/usr/libexec/wootc-lifecycle.sh` +(`write_ntfs_state`, `write_deployer_started`, with explicit image identity). +Container and initramfs packages must carry these modules. +A source test on the host alone does not prove they exist in the boot image. + +`/usr/libexec/wootc-migration-diagnostics.sh` supplies deployer phase timing +with the same JSON field names. It uses the boot UUID to identify each try and +`/proc/uptime` for elapsed milliseconds. It writes to stderr and the append-only +deployer log alongside existing text diagnostics. + +Stable phases are +`ntfs-mounted`, `scratch-setup`, `bundle-ingest`, `network-wait`, +`registry-preflight`, `fisherman`, `verification` and `reboot`. Each transition +starts the next phase and completes the prior one; cleanup records final +completion/error from the exit status. It uses only `operation_failed` for an +error, never raw errors or credentials. Packages must also carry this module. + +Encrypted session envelopes stay on the NTFS source under +`wootc/install/slurp/session`. Do not copy them into installed `/usr/share` +or conflate them with the separate vault/Wi-Fi ingest path. For each target import, +the installed user must explicitly unlock them; see the +[session contract](https://github.com/tuna-os/wootc/blob/main/docs/session-migration.md). + +## Catalogue provenance is not support evidence + +`app/data/catalog-sources.json` holds the public snapshot of upstream source. +`app/data/catalog-provenance.json` records the reviewed bootc-migrate commit for that snapshot. +`app/data/catalog-policy.json` retains +wootc-owned display, support status, bootloader, family and MOK policy. +Go combines source and policy; `app/data/images.json` is the generated +artifact for packages/E2E, not an independent hand-maintained catalogue. + +From the repository root: + +```bash +python3 app/catalog_sync.py --check +python3 app/catalog_sync.py +python3 app/catalog_sync.py --revision +``` + +The first checks offline. The second regenerates from the retained snapshot +and reviewed policy. The last downloads an immutable revision of reviewed source, +validates it, then writes it. Replace the angle-bracket argument +with the reviewed full commit. + +Upstream publication does not automatically add +a product or promote its wootc status. Its v1 identity/backend/family rules do +not supply bootloader, MOK, firmware compatibility or wootc runtime acceptance. +An upstream backend change must pass wootc's explicit check for consistent boot policy. +It must not silently change the installed boot chain. Private brand +and enterprise overrides keep the public `Image` contract. + ## Working rules - New features must not import bootc concepts outside the provisioner diff --git a/docs/wootc/artifact-authentication.md b/docs/wootc/artifact-authentication.md index 77d9a119..2906e226 100644 --- a/docs/wootc/artifact-authentication.md +++ b/docs/wootc/artifact-authentication.md @@ -1,5 +1,5 @@ --- -sidebar_position: 10 +sidebar_position: 11 title: "artifact authentication" --- diff --git a/docs/wootc/backend-contract.md b/docs/wootc/backend-contract.md index 99e75a69..de03e36a 100644 --- a/docs/wootc/backend-contract.md +++ b/docs/wootc/backend-contract.md @@ -1,5 +1,5 @@ --- -sidebar_position: 11 +sidebar_position: 12 title: "backend contract" --- diff --git a/docs/wootc/borrowed-from-libertix.md b/docs/wootc/borrowed-from-libertix.md index 3e5568b4..47c62040 100644 --- a/docs/wootc/borrowed-from-libertix.md +++ b/docs/wootc/borrowed-from-libertix.md @@ -1,5 +1,5 @@ --- -sidebar_position: 12 +sidebar_position: 13 title: "borrowed from libertix" --- diff --git a/docs/wootc/branded-walkthroughs.md b/docs/wootc/branded-walkthroughs.md index 3f01c34f..8e06808d 100644 --- a/docs/wootc/branded-walkthroughs.md +++ b/docs/wootc/branded-walkthroughs.md @@ -1,5 +1,5 @@ --- -sidebar_position: 13 +sidebar_position: 14 title: "branded walkthroughs" --- @@ -10,18 +10,17 @@ brand's real embedded assets from `app/branding//`. These are the same brand.json, logo, typeface and theme that a `-X main.brandID=` binary compiles in. -The test drives the real frontend bundle through the four -journey screens. On each screen, it asserts that the build shows its own -name, mark and look. A branded build must never show the word "wootc". -When you run the Playwright suite again, it refreshes each image below. +The test drives the Wails frontend bundle with a mock backend through four +journey screens. It checks the embedded identity and presentation of each brand, +not native setup or real installation. New Playwright images are not native/RC evidence. +Fresh native images need provenance for the matching build and fixture. -**Live video walkthroughs:** each distribution that passed a full -GUI-driven E2E has its own timelapse in the gallery at -**https://tuna-os.github.io/wootc/e2e/** . In each timelapse, a real Windows -VM installs that image through the real GUI. It then moves the user data and -goes back to Windows. The most recent green run of each image is always at -[/e2e/latest/](https://tuna-os.github.io/wootc/e2e/latest/). Cuts publish -automatically on green (`e2e-gui.yml`), one directory per distribution. +**Recorded video walkthroughs:** the gallery links to retained runs at +**https://tuna-os.github.io/wootc/e2e/** and +[/e2e/latest/](https://tuna-os.github.io/wootc/e2e/latest/). Inspect each run's +SHA, frontend and terminal observations; some historical runs lack a user-data +check. A gallery path or green component job does not itself prove a current +native install, Windows return or same-image VM journey. Each brand has the same journey: @@ -39,10 +38,13 @@ Each brand has the same journey: ### Bazzite brand test record -This record is for the native `-X main.brandID=bazzite` setup package -(`Bazzite-Installer-Setup.exe`). Each row has one check, the result, and the evidence. -A unit test or a mock GUI test is not proof that the product works on a computer. -Only the hosted E2E rows show that. +This **historical ledger has mixed types of evidence**. It does not certify the +current native `Bazzite-Installer-Setup.exe`. The Wails brand flag +`-X main.brandID=bazzite`, mock screenshots and older exe resources do not +prove acceptance of native setup. Check the linked run/commit and exact artifact for each claim. + +The documentation audit on 2026-11-02 kept these records; it did not rerun the tests. +Only real runs with the appropriate scope can prove runtime behavior. | Check | Status | Evidence | |---|:--:|---| @@ -61,9 +63,9 @@ Only the hosted E2E rows show that. | Windows-side errors (BitLocker busy, legacy BIOS, VM viewer, ESP guards, boot repair, uninstall check, unsafe-state dialog) never say "wootc" | ✅ | `TestUserFacingStringsNeverHardcodeWootc` (source scan: every string literal in `app/` that says "wootc" is an identifier or marker on an explicit list) | | Launchpad, progress, done, manage, uninstall dialogs, interrupted, recovery and failed-run screens never say "wootc" | ✅ | `tests/gui/branded-walkthrough.spec.js`. Windows paths such as `C:\wootc\disks` are the on-disk contract, so the test ignores them | | The done screen shows the MokManager step and its password | ✅ | walkthrough test "done celebrates the brand" | -| Exe version resource: product "Bazzite Installer", file `Bazzite-Installer-Setup.exe`, company "TunaOS", no copyright | ✅ | local native packaging build, read with `pefile` (2026-10-15). The company is the distributor, not Universal Blue, while `blessing.json` is pending: `TestUnblessedBrandsNeverClaimTheOwnerAsPublisher`, `tests/unit/test_windows_resources.py` | +| Exe product/file/company resource identity | Historical; current native setup unproven here | The old record cites a local `pefile` inspection (2026-10-15), not retained evidence for today's native setup bytes. Current native packaging must independently show its actual product/file name and distributor Publisher while `blessing.json` is pending; see `tests/unit/test_windows_resources.py` and the native package checks | | Add/Remove publisher and winget draft publisher are "TunaOS" while unblessed | ✅ | `TestBazziteBuild_PublisherIsTheDistributorWhileUnblessed`; `tests/unit/test_winget_brand.py`; `tests/unit/brand-blessings.bats` | -| The release builds the exe, and the log names it as unblessed | ✅ | `tests/unit/brand-blessings.bats`; `packaging/brands.sh explain` | +| Release build selection respects unblessed identity | Source/component record, not publication proof | `tests/unit/brand-blessings.bats`; `packaging/brands.sh explain`. Actual native release assets and package Publisher observation remain separate | | winget manifests render into `Bazzite.Installer` and are not submitted | ✅ | `tests/unit/brand-blessings.bats`; `packaging/winget/render-brand.sh bazzite` | | Hosted GUI E2E, `bazzite:stable`: install, MOK under Secure Boot, Phase 2, user data, Windows return | ✅ 2026-08-24 | [run 32679831098](https://github.com/tuna-os/wootc/actions/runs/32679831098) on `4fd4bc8` | | Hosted GUI E2E, `bazzite:stable`, launch fix and MOK fix | ✅ 2026-10-15 | [run 38792319332](https://github.com/tuna-os/wootc/actions/runs/38792319332) on `b102db9` (PR #609, which contains PR #516). Install, MokManager under Secure Boot, Phase 2, the Documents file in Linux, and the return to Windows passed. The earlier run [38731850924](https://github.com/tuna-os/wootc/actions/runs/38731850924) on `13afd74` stopped at the launch deadlock that PR #516 fixes | @@ -102,8 +104,8 @@ Gaps that this page does not close: ## wootc (generic) -The un-branded engine, as shipped today — also covered by the main -[GUI walkthrough](https://github.com/tuna-os/wootc/blob/main/docs/gui-walkthrough.md). +The generic Wails frontend in the retained mock illustrations — also covered +by the [GUI walkthrough](https://github.com/tuna-os/wootc/blob/main/docs/gui-walkthrough.md), not today's native setup. | | | |---|---| diff --git a/docs/wootc/branding-and-distribution.md b/docs/wootc/branding-and-distribution.md index ea50160b..bc69d0c9 100644 --- a/docs/wootc/branding-and-distribution.md +++ b/docs/wootc/branding-and-distribution.md @@ -1,34 +1,35 @@ --- -sidebar_position: 14 +sidebar_position: 15 title: "branding and distribution" --- -Status: SPEC + phase-1 implementation (2026-08-22). Owner intent (maintainer, -verbatim requirements): automated GitHub releases; an un-branded **wootc** -build plus branded builds for **TunaOS**, the **Bluefin family** -(bluefin / dakota), **Aurora**, and **Bazzite**; branding via a -per-brand config + assets override; branded installers do not use the wootc -name (wootc is the generic project name only); branded distributions -pre-bundle or pre-download the bootc image **on Windows**, because the -deployer stage must never rely on the internet — laptops on Wi-Fi have no -networking in the initramfs, and the E2E VM's virtio ethernet has been -masking that. +Scope updated 2026-11-02: package source and design requirements. This scope +does not prove that a publisher released or qualified a native package. +The observed latest non-prerelease remains `v0.1.0-alpha.1` with Wails executables; +see the [start guide](https://github.com/tuna-os/wootc/blob/main/docs/getting-started.md). + +The owner's original intent was to automate GitHub releases with an un-branded +**wootc** build and branded builds. Brands include **TunaOS**, the **Bluefin +family** (bluefin / dakota), **Aurora**, and **Bazzite**. +Each brand uses its own config and asset overrides. +Branded installers do not use the wootc name; wootc is only the generic project name. + +Branded distributions pre-bundle or pre-download the bootc image **on Windows**. +The deployer stage must never rely on the internet. +Laptops on Wi-Fi have no network in the initramfs. +The E2E VM's virtio ethernet has hidden that limitation. --- ## 1. Automated releases -**Trigger.** Two channels, one pipeline (`release.yml`): +**Triggers and gates.** Main defines tagged and automatic release paths in +`release.yml`. Consult [release instructions](https://github.com/tuna-os/wootc/blob/main/docs/RELEASING.md) for the exact +stages selected for E2E, how they bind the SHA, and any documented emergency waiver. +A workflow's existence is not a passed run or a published release. -- **Tagged** (`v*`): unchanged — the human-blessed channel, E2E-gated. -- **Auto** (`workflow_run` after a green E2E nightly on `main`, or - `workflow_dispatch`): tags `auto-vYYYYMMDD-` and publishes a - **pre-release**. The E2E gate is satisfied by the run that triggered it — - the release is cut from the exact SHA the nightly proved. No green nightly, - no auto release. - -**Assets.** Every release ships the native setup packages for each eligible -brand (see §2), plus the shared boot set: +**Native assets on main.** The first native cutover plans to publish +setup packages for each eligible brand (see §2), plus the shared boot set: | Asset | Source | |---|---| @@ -40,13 +41,15 @@ brand (see §2), plus the shared boot set: | `SHA256SUMS` | sha256sum over the boot and legacy assets | | `native-SHA256SUMS` | sha256sum over the attached setup assets | -The setup package embeds the native shell, its protected Go engine, and the -public key for release verification. This cut-over release keeps the Wails -executable only as a compatibility fallback, not a second branded installer. +The setup package in source embeds the native shell, protected Go engine and +public key for artifact verification. The first native cutover will also retain a +single compatibility executable for Wails. Older `v0.1.0-alpha.1` instead provides +`wootc.exe`, branded `*-Installer.exe` files and `SHA256SUMS`, not this native +asset set. Download only an asset listed on the selected tag. -`deployerBaseURL()` previously pointed at release assets that did not exist -(documented on #196). The first automated release closes that gap. A plain -online install then works without advance setup. +A release URL alone does not establish a plain online or offline install. +Boot artifacts, signed metadata, image inputs, Windows runtime and frontend +must match the tested build. See [native release gates](https://github.com/tuna-os/wootc/blob/main/docs/winui-shell.md#packaging-and-offline-proof). **Branded downloads.** Each branded setup has its own layout expectation for `deployerBaseURL`. All brands share the boot artifacts because the deployer is @@ -141,13 +144,16 @@ falls out of the answers: any `no` → `declined`, all four `yes` → `blessed`, anything else → `pending`. A mark this project does not own cannot be marked `blessed` without a link to the yes. -**Release matrix.** The publish job asks `packaging/brands.sh` which brands -may ship, builds each surviving exe with its ldflag, names it `exeName`.exe, -and adds all to the release + SHA256SUMS. The decision is load-bearing -there: a **declined** project's exe drops out of the matrix, a brand with no -record at all is a hard error rather than a default yes, and a **pending** -one still builds (shipping predates the ask) but is named as unblessed in -the release log. `WOOTC_REQUIRE_BLESSING=1` drops pending brands too. +**Release matrix.** `packaging/brands.sh` decides which brands may build. +For native packages, the process maps each selected brand to its setup name and checksums. +Names of older Wails assets do not prove publication of native setup. + +A **declined** project's build drops out of the matrix; an absent permission +record is an error, not an implicit yes. A project without a final decision +can still build but must retain unblessed/distributor identity. +`WOOTC_REQUIRE_BLESSING=1` also excludes brands without a final decision. +These source rules do not establish upstream +approval, namespace ownership, installation success or a published download. ## 3. Offline-first deploys diff --git a/docs/wootc/branding.md b/docs/wootc/branding.md index 345760c6..e12040ec 100644 --- a/docs/wootc/branding.md +++ b/docs/wootc/branding.md @@ -1,5 +1,5 @@ --- -sidebar_position: 15 +sidebar_position: 16 title: "branding" --- @@ -17,6 +17,11 @@ Drop a `brand.json` next to the installer (or push it via MDM to `C:\wootc\brand.json`). Any field you omit falls back to the wootc default; you only specify what you want to change. +Brand JSON and the brand table from `packaging/brand.py` use **UTF-8**, +independent of the host's ANSI locale. Save names, taglines and emoji as UTF-8. +The shared loader/generator needs no change to Windows' system code page +and no UTF-8 environment override. + ```json { "name": "Acme Switch", @@ -51,6 +56,16 @@ The palette is applied as CSS custom properties at startup, so a single accent change re-skins every button, chip, and highlight consistently. See the branded screenshot in [gui-walkthrough.md](https://github.com/tuna-os/wootc/blob/main/docs/gui-walkthrough.md). +In the legacy Wails frontend, `applyBranding` derives input/hover surfaces +from an explicit `brand.card`. It derives muted/dim text from an explicit +`brand.text` when a complete theme does not supply those tokens. +This prevents light input backgrounds with light text in a partial palette. + +The frontend applies full `brand-theme` CSS last. +That CSS will override the derived defaults, even after repeated brand changes. +This describes source behavior, not native WinUI styles. +It does not prove every theme's contrast/accessibility. + ## `brand.css` — deep restyle A `C:\wootc\brand.css` is injected after the app stylesheet (and after any @@ -127,11 +142,13 @@ provisioner stage differs. ## What is NOT themeable (on purpose) -The honesty rules are not configurable: the "nothing is deleted from -Windows" reassurance, the per-app truthful session outcomes, and the -BitLocker/data-safety warnings are part of the product's trust contract, -not the skin. A branded migrator can look like anything; it cannot lie -about what happens to the user's data. +The honesty rules are not configurable. The trust contract includes truthful +session outcomes, BitLocker/data-safety warnings, changes before reboot, and +limits of cleanup/recovery. A theme cannot change these rules. + +A brand must not turn a data-preservation goal into a guarantee. +It cannot promise that no operation deletes data or that failed cleanup restores every setting. +It must not hide a partial result or lie about what happens to the person's data. ## Testing a brand diff --git a/docs/wootc/dakota-return-boot-rca.md b/docs/wootc/dakota-return-boot-rca.md index dc25a012..3471ec92 100644 --- a/docs/wootc/dakota-return-boot-rca.md +++ b/docs/wootc/dakota-return-boot-rca.md @@ -1,5 +1,5 @@ --- -sidebar_position: 16 +sidebar_position: 17 title: "dakota return boot rca" --- diff --git a/docs/wootc/deployer-experience.md b/docs/wootc/deployer-experience.md index 55376fdf..f49b3d2d 100644 --- a/docs/wootc/deployer-experience.md +++ b/docs/wootc/deployer-experience.md @@ -1,5 +1,5 @@ --- -sidebar_position: 17 +sidebar_position: 18 title: "deployer experience" --- diff --git a/docs/wootc/destructive-paths.md b/docs/wootc/destructive-paths.md index c4f7991b..a2a1714e 100644 --- a/docs/wootc/destructive-paths.md +++ b/docs/wootc/destructive-paths.md @@ -1,5 +1,5 @@ --- -sidebar_position: 18 +sidebar_position: 19 title: "destructive paths" --- @@ -9,6 +9,11 @@ It records source gates, failure behavior, tests, and evidence limits. It is not the execution review for [#237](https://github.com/tuna-os/wootc/issues/237). That issue still needs an RC SHA and a full-tier run. +**Source follow-up, 2026-11-02:** the source updates below are not an RC +clearance or a published release. Component checks and observations from isolated +runtime trials must retain their stated boundaries. +Real Windows mutation, firmware, BitLocker changes and same-system promotion remain separate gates. + ## Review method and status The review walked `app/` and `payload/`, enumerated the relevant mutation @@ -39,31 +44,32 @@ it can destroy user work even when no external path changes. | Native install confirmation: `app/native_install_session.go`, `app/native_install_authorization_windows.go` | Typed immutable install plan; image/storage validation; captured-user revalidation; session/brand/one-shot intent binding; fresh observation immediately before starting the existing install pipeline | A failed or mismatched confirmation consumes the intent; the existing install pipeline owns rollback and disarm behavior | `app/native_install_session_test.go`, `app/native_install_session_windows_test.go`, and the authorization path cover protocol and replay refusal. The native shell has no full destructive hardware run yet (#237). | | Change hibernation/Fast Startup: `app/installer_windows.go`, `app/power_state.go` | Prior-state marker; install/recovery/uninstall paths | Restoration attempts recorded prior settings | Parser tests in `app/power_state_test.go` and `tests/unit/uninstall-restoration.bats` do not prove actual Windows restoration on real hardware. RC verification remains #237/#238. | | Create/arm firmware BCD entry: `app/installer_esp.go:configureBCD`, `armBootChain`, `app/boot_txn.go` | Export prior BCD; hash check of the staged ESP chain before entry creation and again before the arm; journal `install/boot-txn.json` records each step; the one-shot is the last change before reboot | Each step compares `bcdedit /enum firmware` with the intended chain. A failure or cancel removes the entry and reads the store again. Residue keeps the journal in `rollback-unconfirmed`, and the startup task tries again | #286: tests in `app/boot_txn_test.go` cut power at each boundary and fail each step against a simulated store. **Open #234**: a Windows VM run with real interruptions is still necessary. | -| Cancel/recover/uninstall BCD cleanup: `app/installer_esp.go:disarmOneShot`, `deleteWootcBCDEntries`, `app/recovery_windows.go` | Journal GUID or saved GUID (full GUID check), or entry description; the sweep removes only the wootc elements of the one-shot | Removes wootc entries, then reads the store. Cleanup that it cannot see keeps the journal, `armed.json` and the recovery tasks for a retry | #286 tests cover a foreign one-shot, an entry that does not delete, and a store that does not read. **Open #234**: failed BCD enumeration still becomes false absence in `hasWootcBCDEntry`. Actual cleanup on Windows still needs counterexamples. | +| Cancel/recover/uninstall BCD cleanup: `app/installer_esp.go:disarmOneShot`, `deleteWootcBCDEntries`, `app/recovery_windows.go` | Journal/saved full GUID or owned entry description; strict firmware-store observation | Failed enumeration refuses instead of becoming false absence. Rollback must be observed before recovery tasks, EFI files or state can be removed; failure retains retry authority | Working-tree failure controls cover unreadable stores and retained state. **Open #234**: actual Windows cleanup and interruption counterexamples remain required. | | Initial ESP kernel/loader/config staging: `app/installer_esp.go`, `payload/deployer/deploy.sh` | Product ownership manifest and selected boot chain | Existing boot backup/cleanup paths; multiple files change | **Open #286/#234**: immutable whole-chain rollback and process-cut firmware acceptance required. Cross-vendor transition cannot use the upgrade's mixed-trio assumption. | | Uninstall ESP files: `app/esp_cleanup.go` | Raw relative-path validation; modern manifest authority; regular-file/no-symlink checks; complete preflight | Removes exact claims; observes whole-plan absence; keeps manifest on partial failure for retry; preserves foreign neighbors | #442 merged. Actual temporary filesystem tests reject traversal, ambiguous case, directory claims and lying removers. Nine Windows tests pass, one case-ambiguity test skips on NTFS and passes on Linux. No real ESP mutation in that proof. | -| Delete installed disk/staged data: `app/installer_windows.go:uninstallWith` | DeleteRootDisk/RemovePartition options; default keeps existing disk | Recursive cleanup removes installer subtrees; verification follows | **Open #234**: namespace-based recursive removal and discarded removal errors need ownership/error review; partition receipt must be validated before deleting its metadata. Default preservation is distinct from explicit root-disk deletion consent. | +| Delete installed disk/staged data: `app/installer_windows.go:uninstallWith` | Explicit DeleteRootDisk/RemovePartition choices; partition receipt validated before metadata removal; secret scrubbing must succeed | Removal errors propagate. Default preservation retains unfamiliar saved data even when `root.disk` is absent; failed scrub retains the secret and its retry authority | Working-tree component controls cover preservation and failure propagation. **Open #234**: explicit deletion namespace, partition mutation and actual Windows interruption acceptance remain required. | | Discard an unfinished attempt's `root.disk` before a resume: `app/install_recovery.go:prepareResumeAt` | Re-observes and re-classifies on every call. The journal starts only after the gate that refuses an existing `root.disk`. The attempt must have reached "Making room for Linux" and stopped before the boot steps. `armed.json` and `deployer-started.json` must be absent, and the file must not be older than the attempt | Verified download pieces are kept. Any doubt refuses the resume and offers removal instead | `app/install_recovery_test.go` refuses an older file, a touched boot chain, and a started deployer, and confirms that a refused resume keeps the file. Uses temporary files only. No interrupted Windows VM run proves it yet (#287). | | Read host volumes and mount selected host NTFS read-write: `payload/deployer/deploy.sh:scan_for_root_disk` | Read-only scan, root image discovery; selected volume then mounted read-write | Unmount/retry/diagnostic paths | `tests/unit/scan-root-disk.bats`, NTFS state-writer and clean-unmount checks cover components. **Open #234/#370**: bind actual host identity at writes and prove dirty/hibernated/failed-observation behavior; source scan alone is not data-loss clearance. | | Advance VDL, attach loop and provision image: `payload/deployer/deploy.sh` | Selected root image; loop layout and deployment verification | Writes inside raw image; failure diagnostics and Windows return | Existing successful native-cycle runs prove their exact cells. **Open #234/#285/#286**: interruption/retry must preserve an existing installed image; a boot-ready size is not installation consent. | -| Format helper target/scratch: `payload/builder/wootc-builder.sh:blank_disk`, `prepare_storage` | Both block devices, dedicated serials, whole-disk type, minimum sizes, no partitions/signatures/mount before first format | Disposable dedicated disks; installation failure reported | Helper storage preflight evidence exists; it does not prove target desktop or restart. #178 remains open. Identity changes between preflight and mutation still need final audit. | +| Format helper target/scratch: `payload/builder/wootc-builder.sh:blank_disk`, `prepare_storage` | Install operation only: both block devices, dedicated serials, whole-disk type, minimum sizes, no partitions/signatures/mount before first format | Disposable dedicated disks; installation failure reported; export is a separate read-only operation | Helper storage preflight does not prove target desktop or restart. Historical #178 is closed; current VM-first acceptance is #596. Identity changes between preflight and mutation still need final audit. | +| Export managed-VM boot inputs: `app/vm_promotion.go`, `payload/builder/wootc-export.sh` | Clean stopped VM, disk lease/GPT/install identity, signed export-capable helper; original target read-only, ephemeral overlay for target-native initramfs generation; exact kernel/closure and archive hashes | Durable export/failure journal and cancellation; separate retained export directory. No ESP/BCD mutation or claim that native boot is armed | Real installed-target helper export, cancellation and byte-identity proof remain required. **Open #596**: host storage/trust/BitLocker/Fast Startup/recovery preflight and transactional native handoff remain unimplemented. | | Installed ESP kernel/initramfs/config refresh: `payload/migration/wootc-esp-sync` | Resolves the host ESP from the recorded UUID; requires the owned `EFI/wootc` namespace; the direct route writes `.new` then renames; the controller route observes boot identity and ownership before each write | Direct kernel/config replacement is per-file, not a whole-set transaction; the controller retains journal state for recovery and refuses an unprepared boot | `tests/unit/esp-chain-refresh.bats`, `tests/unit/test_wootc_esp_control.py`, and `tests/unit/test_wootc_esp_transaction.py` cover the split paths. **Open #237/#333**: direct pair interruption and real firmware acceptance remain unproved. | | Signed shim/GRUB/MokManager refresh: `payload/migration/wootc-esp-sync:sync_signed_chain` | `wootc-esp-control:prepare` binds current boot identity, ownership, source package, firmware trust, and signatures; publication accepts only receipt-listed destinations and the prepared boot ID | The transaction archives and recovers the signed trio; an ambiguous source or changed boot refuses before publication | `tests/unit/test_wootc_esp_control.py`, `tests/unit/test_wootc_esp_transaction.py`, and `tests/unit/test_esp_chain_refresh.py` cover the controller. **Open #237/#333**: production integration, process-cut recovery, and firmware-upgrade boot acceptance remain unproved. | | Native graduation to blank whole disk: `payload/migration/wootc-go-native:graduate_to_disk_execute` | `--to-disk` requires a block device different from the host disk; execution requires `--execute` plus `WOOTC_GN_ALLOW_DESTRUCTIVE=1`; fisherman owns target partition/format checks; the image is already local | Source Windows/root image remains untouched; only the explicitly selected target changes; failure leaves the source available for retry | `tests/unit/go-native.bats` covers the dry-run and destructive flag boundary. Historical GUI run 36265248670 proves a blank-disk cell, not the native shell. User-work persistence and native boot remain open (#237). | | Same-disk shrink/reclaim plan: `payload/migration/wootc-go-native:graduate_plan`, `cmd_migrate` | `ntfsresize --info` is read-only; `--reclaim` requires native boot and at least one converted folder; in-place execution without `--to-disk` refuses after printing the plan | Current main performs no same-disk shrink, partition delete, or Windows-entry removal; the plan is not rollback evidence | `tests/unit/go-native.bats` proves the dry-run and refusal boundary. The printed `ntfsresize`/`sfdisk`/`efibootmgr` commands are not implemented acceptance; do not claim same-disk safety. | -| Write/move imported user files: `payload/migration/wootc-mount-user-dirs`, `wootc-convert-dir`, plugin imports | Profile map, category operation and bridge paths | Category-specific rollback and ledger; contracts differ per importer | Migration component suite proves seeded cases only. #427 actual BitLocker editor save/reopen/second-boot proof is running on draft434; no result yet. Audit all importer overwrite/collision paths before #234 closure. | -| Import from an external Windows or WSL volume: `payload/migration/wootc-import`, `wootc-wsl-bridge`, `wootc-detect-apps`, `wootc-steam-bridge` | Running-disk exclusion; BitLocker unlock via stdin; read-only source mount; explicit category selection; `--update`/no-clobber checks for standard files | Eject unmounts the bind and source and closes the BitLocker mapper; partial destination files remain for inspection and retry | `tests/unit/import.bats` and `tests/unit/test_plugin_import_results.py` cover the orchestration and result shape. **Open #234**: bridge failures are tolerated, Steam rewrites its VDF, Firefox/Thunderbird write profile metadata, and no common per-file receipt or rollback proves every existing native file survives an interrupted import. | -| Shred staged vault, Wi-Fi exports and recovery key: `payload/deployer/deploy.sh`, `payload/migration/wootc-wifi-bridge`, `wootc-convert-dir` | Product staging paths and import/convert flow. The deployer moves the recovery key to `/etc/wootc/bitlocker-key` and shreds the NTFS copy only after it verifies the move. The bridge seals it to `bitlocker-key.cred` with `systemd-creds --with-key=auto` and shreds the plaintext only after the sealed copy decrypts to the same bytes. `wootc-convert-dir` shreds both when no folder is bridged from C: | Credentials deliberately removed; `rm` fallback does not promise physical erasure. Shutdown keeps the key, because the bridge unlocks C: on each boot | `tests/unit/bitlocker-key-lifecycle.bats` covers the move, the fallback, shutdown and conversion. The BitLocker E2E cell reads Documents on a second Phase-2 boot. The sealed path is not yet observed in a VM. #281 staged session envelope lifecycle remains open. Never retain secret values as audit evidence. | +| Write/move imported user files: `payload/migration/wootc-mount-user-dirs`, `wootc-convert-dir`, plugin imports | Profile map, category operation and bridge paths; Documents copying writes as the receiving ordinary user | Failed Documents copy preserves existing Linux work instead of hiding it under a read-only Windows bind; unsafe empty-mountpoint removal refuses; importer collision rules remain category-specific | Component controls cover seeded failures. **Open #427/#234**: actual BitLocker editor save/reopen/second-boot and importer interruption acceptance remain required; no old draft run is current proof. | +| Import from an external Windows or WSL volume: `payload/migration/wootc-import`, `wootc-wsl-bridge`, `wootc-detect-apps`, `wootc-steam-bridge` | 2026-11-02 source update: running-disk exclusion; BitLocker unlock via stdin; read-only source; explicit categories; standard-file copies publish complete files exclusively, preserve existing destination bytes and refuse source/destination symlinks or special files | Per-category copied/preserved/failed results; failed or unverified categories return nonzero even if others completed. Eject unmounts bind/source and closes mapper. Existing Steam VDF is preserved byte-for-byte; missing entries require manual Add Library. WSL dotfiles, `.ssh` and Brewfile preserve existing different content and use exact new-file ownership rather than recursive chown; per-item outcomes are copied/alreadyPresent/preserved/failed | `tests/unit/import.bats` and `tests/unit/test_plugin_import_results.py` are existing orchestration/result suites; no new execution result is asserted by this source update. **Open #234**: real read-only volume, interrupted publication/eject and complete mixed-category preservation still require runtime evidence. A copied file or preserved VDF does not prove service/account migration. | +| Scrub staged vault/Wi-Fi/recovery secrets: `payload/deployer/deploy.sh`, migration bridges, `app/secret_scrub_windows.go` | Canonical recovery password; checked staging ACLs; verified and durably published sealed copy before removing plaintext; encrypted session envelopes retained on NTFS for explicit consented import, not copied into target `/usr/share` | Failed overwrite/flush retains plaintext and blocks unlink/uninstall for retry. Shutdown retains the bridge credential. Host-only fallback does not protect a copied disk, and overwriting does not promise physical erasure | Component failure controls cover scrub/seal ordering. **Open #279/#427/#234**: actual TPM reset, BitLocker editing and second-boot proof remain required. Never retain secret values as audit evidence. | -| Add/Remove Programs registry and prior-power mirror: `app/installer_windows.go:registerUninstallEntry`, `unregisterUninstallEntry`, `app/sysprobe_windows.go` | Fixed HKLM product key; escaped branding values | Registry deletion attempted after power restoration | **Open #234/#238**: writes/removal discard errors, no ownership receipt for a pre-existing key, and key removal can destroy the last power-state mirror after unsuccessful restoration. Need actual failure/foreign-key controls and observed retained retry data. | +| Add/Remove Programs registry and prior-power mirror: `app/installer_windows.go`, `app/sysprobe_windows.go` | Prior power state durably recorded before mutation; `WootcOwner=wootc-install-v1` receipt required for product-key reuse/removal; foreign or unmarked keys refused | Registry errors propagate. Power restoration must be observed before removing its final retry mirror | Working-tree controls cover ownership and failure propagation. **Open #234**: actual Windows foreign-key, failed-write/restoration and retained-retry observations remain required. | | Boot repair and Windows-only restore (#290): `app/boot_repair.go`, `app/recovery_windows.go:repairBootFromArmed` | Reads `bcdedit /enum firmware` first. Acts only on entries with the `wootc` description. Refuses when the recorded GUID has a different description, when `armed.json` and `bcd-guid.txt` disagree, when the next boot goes to a foreign entry, or when the ESP manifest is unreadable | Restore clears the one-shot and removes wootc entries from the permanent order. It keeps the entry, the ESP files and `armed.json`. Repair passes only when a new observation shows the recorded entry as the next boot and the recorded ESP hashes. If that check fails, repair takes wootc out of the boot order again | Decision-table and command-list tests in `app/boot_repair_test.go` use `bcdedit` dumps, not a real BCD store. A Windows VM run of each action is still necessary. | | Recovery scheduled tasks: `app/recovery_windows.go:registerRecoveryTasks`, `unregisterRecoveryTasks` | Fixed task names; SYSTEM startup and elevated logon principals; the existing task's executable, arguments, principal, run level, trigger and action/trigger counts must match before reuse or removal | Registration refuses a foreign same-name task before the first BCD write. Cleanup is idempotent for absent tasks, verifies removal, and returns command or observation errors | The task identity is bound to the staged executable and its recorded hash is checked before startup recovery. The broader privileged-state and TOCTOU audit remains open under #234/#370. | | Trusted state directory ACL: `app/state_trust_windows.go:prepareTrustedStateTree` | Trusted parent volume; restricted creation descriptor; recursive owner/DACL/no-reparse inspection before root ACL update; rejects unsafe existing trees instead of repairing them | Fails before trusting planted artifacts; does not restore earlier ACLs | Component native trust tests exist. #370 remains open for the full reader/writer/transition surface and TOCTOU review; this source gate does not prove every elevated artifact consumer. Dedicated-volume root ACL and OEM equivalent need separate ownership proof. | -| BitLocker recovery-password capture/write: `app/bitlocker_windows.go` | Selected volume; existing recovery protector; state directory and file ACL attempt | Plaintext recovery password written to install staging; ACL failure emits warning and returns success | **Open #279/#370/#427**: current main strips separators, incompatible with Linux password parsing. Canonical-format repair is in frozen draft431/434 awaiting runtime acceptance; never describe it as shipped. Machine-bound key storage and failure-closed secret lifecycle remain required. | +| BitLocker recovery-password capture/write: `app/bitlocker_windows.go` | Selected volume and recovery protector; canonical length/digit/checksum/hyphen validation; checked directory/file ACLs | Staging/ACL failure returns error; scrubbing failure preserves retry authority instead of silently deleting the secret | The canonical-format and fail-closed repairs are working-tree changes, not a published release. **Open #279/#370/#427**: actual Windows capture, TPM lifecycle and editor/restart evidence remain required. | | OEM carve/decrypt/key/BCD equivalents: `tests/e2e/setup-wootc.ps1` | Measured C: shrink; freshly formatted storage; conversion wait; positive BCD path/entry/sequence checks | Per-step cleanup attempts and one-shot rollback | **Open #234/#286**: `UseMaximumSize` still needs exact extent proof; two absent BitLocker objects count as plaintext; BCD rollback drops errors. Harness success cannot clear Go product variants. Frozen draft434 adds a separate complete-C:-encryption readiness gate; its run is not terminal. | | Native folder conversion swap/marker: `payload/migration/wootc-convert-dir` | Allowed folder, nonempty source, second successful rsync; native destination must be empty; actual empty-directory removal after unmount; final move forbids nesting | Failed swap preserves native files and staging; no new marker; retry preserves Linux edits | #447 merged after all applicable hosted checks. Five actual-script/private-file controls prove successful final placement, repeat-edit preservation, hidden native files, move-time race refusal and the faulty-move mutant. Mount/identity/ownership calls are mocked. **Open #234/#285**: full staging ownership, locking and crash recovery remain unproved. | -| Browser profile import: `payload/migration/wootc-import-browser` | Selection flags and source profile; Chromium files copied only if missing | Firefox uses fixed `windows-import.wootc` destination and updates profile list; Windows originals remain | **Open #234**: repeat Firefox rsync/cp can overwrite edits in a prior import, and raw profiles.ini relative path needs traversal/no-reparse validation. The Chromium existence check/copy is not exclusive creation. Seeded happy-path import does not prove collision safety. | -| Office dictionary/templates/fonts import: `payload/migration/wootc-office-bridge` | Existing source; dictionary words deduplicated; templates/fonts use no-clobber copy | Appends dictionary; recursive ownership changes and outcome record | **Open #234**: no-clobber command success is not proof a file arrived; symlink destinations, partial write recovery and actual ownership before recursive chown still need refusal controls. | +| Browser profile import: `payload/migration/wootc-import-browser` | 2026-11-02 source update: FD-pinned no-follow traversal; absolute/traversal/reparse/symlink profiles refuse; Firefox stages a complete profile and publishes with atomic no-replace; Chromium uses exclusive hardlink publication, never overwrite | Existing Firefox import directory refuses and preserves edits. Existing `profiles.ini` is never rewritten/appended; a copied but unregistered profile reports failure/manual-registration advice. Failed/partial copies retain private `.wootc-*.partial` staging and return nonzero; source originals remain unchanged. Browser state is native only for nonempty imports without errors, failed on any error, unchanged for no work, always unverified | Source controls address the prior check-then-copy and repeat-overwrite defects; this edit does not claim tests ran. **Open #234**: validate interrupted publication, real source filesystem semantics and browser metadata registration in runtime fixtures. Neither copied profile nor native category state is authentication proof. | +| Office dictionary/templates/fonts import: `payload/migration/wootc-office-bridge` | 2026-11-02 source update: existing different native templates/fonts/autocorrect/defaults preserved, not counted as migrated; unsafe paths refuse; exact new-file ownership only, no recursive chown | Dictionary append has a recovery journal and refuses changed pending state; per-file outcomes distinguish copied/already-present/preserved/failed. Failure does not authorize replacing native work; inspect journal before retry | Source controls replace no-clobber exit-status/recursive-chown assumptions; this edit does not claim tests ran. **Open #234**: real ownership, interrupted dictionary append, collision and retry acceptance still need retained runtime results; category presence or a successful skipped copy is not evidence a file arrived. | ## Dependency review: selected Windows data before partitioning diff --git a/docs/wootc/distro-adoption.md b/docs/wootc/distro-adoption.md index c87c1b50..633d70b9 100644 --- a/docs/wootc/distro-adoption.md +++ b/docs/wootc/distro-adoption.md @@ -1,5 +1,5 @@ --- -sidebar_position: 19 +sidebar_position: 20 title: "distro adoption" --- diff --git a/docs/wootc/docs-README.md b/docs/wootc/docs-README.md index cd4113ff..fe945cad 100644 --- a/docs/wootc/docs-README.md +++ b/docs/wootc/docs-README.md @@ -3,11 +3,12 @@ sidebar_position: 4 title: "README" --- -This directory contains current user guidance, engineering references, release -material, and historical investigations. Start with the first section, then -use topic sections for deeper detail. Documents marked **historical** record a -completed investigation or an earlier plan; they are not current operating -instructions. +The [repository README](https://github.com/tuna-os/wootc/blob/main/README.md) explains the product and where to get it; +this index helps you find operating instructions, contracts, acceptance +evidence, and design history. A design or release-note filename is not proof +that its behavior ships. Use [verification status](https://github.com/tuna-os/wootc/blob/main/docs/status.md) and +[release instructions](https://github.com/tuna-os/wootc/blob/main/docs/RELEASING.md) for current decisions; dated experiments +and plans are context, not current operating instructions. ## Start here @@ -17,6 +18,16 @@ instructions. - [Verification status](https://github.com/tuna-os/wootc/blob/main/docs/status.md) — proven matrix cells and their evidence. - [Philosophy](https://github.com/tuna-os/wootc/blob/main/docs/philosophy.md) — product goals and decision rules. +### Choose an entry point + +| Reader | Read first | Then | +|---|---|---| +| End user | [Getting started](https://github.com/tuna-os/wootc/blob/main/docs/getting-started.md) | [User guide](https://github.com/tuna-os/wootc/blob/main/docs/user-guide.md), or [Coming from WSL](https://github.com/tuna-os/wootc/blob/main/docs/wsl-migration.md) | +| Contributor | [Contributing](https://github.com/tuna-os/wootc/blob/main/CONTRIBUTING.md), then [AGENTS.md](https://github.com/tuna-os/wootc/blob/main/AGENTS.md) | [Agent lessons](https://github.com/tuna-os/wootc/blob/main/docs/agent-lessons.md) before harness/deployer changes; [native shell contract](https://github.com/tuna-os/wootc/blob/main/docs/winui-shell.md#current-stdio-protocol-reference) for Go/WinUI integration | +| Maintainer/reviewer | [Verification status](https://github.com/tuna-os/wootc/blob/main/docs/status.md) | [Release instructions](https://github.com/tuna-os/wootc/blob/main/docs/RELEASING.md), [truth-pass record](https://github.com/tuna-os/wootc/blob/main/docs/docs-truth-pass.md), [roadmap](https://github.com/tuna-os/wootc/blob/main/ROADMAP.md) | +| Distro packager | [Distro adoption](https://github.com/tuna-os/wootc/blob/main/docs/distro-adoption.md) | [Brand distribution](https://github.com/tuna-os/wootc/blob/main/docs/branding-and-distribution.md), [upstream blessings](https://github.com/tuna-os/wootc/blob/main/docs/upstream-blessings.md), [backend contract](https://github.com/tuna-os/wootc/blob/main/docs/backend-contract.md) | +| IT evaluator | [IT-admin quick start](https://github.com/tuna-os/wootc/blob/main/docs/it-admin-quick-start.md) | [Manual testing](https://github.com/tuna-os/wootc/blob/main/docs/manual-testing.md), [destructive paths](https://github.com/tuna-os/wootc/blob/main/docs/destructive-paths.md); this is not a fleet-management product | + ## Product and architecture - [Specification](https://github.com/tuna-os/wootc/blob/main/docs/SPEC.md) — complete product and protocol requirements. @@ -53,6 +64,10 @@ instructions. - [Release instructions](https://github.com/tuna-os/wootc/blob/main/docs/RELEASING.md) — green-gated release process. - [Alpha adopter program](https://github.com/tuna-os/wootc/blob/main/docs/alpha-adopter-program.md) — structured early-adopter tests. - [Pre-filled profiles](https://github.com/tuna-os/wootc/blob/main/docs/prefilled-profile-testing.md) — migration tests with an existing Windows profile. +- [First-boot evidence](https://github.com/tuna-os/wootc/blob/main/docs/firstboot-evidence.md) — observed guest identity and completion records. +- [WSL migration](https://github.com/tuna-os/wootc/blob/main/docs/wsl-migration.md) — manual transfer boundaries; no automatic WSL distro or account import. +- [IT-admin quick start](https://github.com/tuna-os/wootc/blob/main/docs/it-admin-quick-start.md) — bounded single-machine evaluation, not fleet rollout. +- [Adoption outreach](https://github.com/tuna-os/wootc/blob/main/docs/adoption-outreach.md) — approval-gated invitations and scenario briefs, not claimed success stories. - [Native GUI soak](https://github.com/tuna-os/wootc/blob/main/docs/soak.md) — shell stability ledger for long runs. - [Agent lessons](https://github.com/tuna-os/wootc/blob/main/docs/agent-lessons.md) — operational traps from E2E work. - [Docs truth pass](https://github.com/tuna-os/wootc/blob/main/docs/docs-truth-pass.md) — dated documentation-versus-build checks. @@ -65,16 +80,23 @@ instructions. - [dakota return-boot RCA](https://github.com/tuna-os/wootc/blob/main/docs/dakota-return-boot-rca.md) — **historical** Phase-2 hang investigation. - [Phase-2 attach postmortem](https://github.com/tuna-os/wootc/blob/main/docs/phase2-attach-postmortem.md) — **historical** debugging record. - [Phase-2 debug plan](https://github.com/tuna-os/wootc/blob/main/docs/phase2-debug-plan.md) — **historical** hypotheses and resolution path. -- [v0.3.0-beta release notes](https://github.com/tuna-os/wootc/blob/main/docs/release-notes-v0.3.0-beta.md) — release record and evidence status. -- [v1.0.0 release notes](https://github.com/tuna-os/wootc/blob/main/docs/release-notes-v1.0.0.md) — release goals and evidence checklist. +- [v0.3.0-beta release notes](https://github.com/tuna-os/wootc/blob/main/docs/release-notes-v0.3.0-beta.md) — draft release material; consult tags and release evidence before you call it shipped. +- [v1.0.0 release notes](https://github.com/tuna-os/wootc/blob/main/docs/release-notes-v1.0.0.md) — release goals and evidence checklist, not a shipped-version claim. ## Document collections - [`adr/`](https://github.com/tuna-os/wootc/blob/main/docs/adr) — architecture decision records. + Includes [phase-1 architecture](https://github.com/tuna-os/wootc/blob/main/docs/adr/0001-phase1-first-architecture.md), + [hardware matching](https://github.com/tuna-os/wootc/blob/main/docs/adr/0002-hardware-preflight-bootc-matching.md), + [OneDrive placeholders](https://github.com/tuna-os/wootc/blob/main/docs/adr/0003-onedrive-files-on-demand-migration.md), + [composefs/kernel matching](https://github.com/tuna-os/wootc/blob/main/docs/adr/0004-composefs-kernel-module-matching.md), + the [VM-first correction](https://github.com/tuna-os/wootc/blob/main/docs/adr/0004-restore-vm-first-product.md), and + [session-envelope unlock](https://github.com/tuna-os/wootc/blob/main/docs/adr/0005-session-envelope-unlock.md) (approval pending). - [`specs/`](https://github.com/tuna-os/wootc/blob/main/docs/specs) — detailed migration proposals. + Read [enterprise migration](https://github.com/tuna-os/wootc/blob/main/docs/specs/enterprise-migration.md) and + [migration extensions](https://github.com/tuna-os/wootc/blob/main/docs/specs/migration-extensions.md) as proposals unless an + implementation and its acceptance evidence are explicitly named. - [`experiments/`](https://github.com/tuna-os/wootc/blob/main/docs/experiments) — dated research notes and implementation experiments. - [`evidence/`](https://github.com/tuna-os/wootc/blob/main/docs/evidence) — checked-in evidence summaries. - [`experiments/evidence/`](https://github.com/tuna-os/wootc/blob/main/docs/experiments/evidence) — experiment artifacts and provenance. - [`screenshots/`](https://github.com/tuna-os/wootc/blob/main/docs/screenshots) — UI walkthrough images. - -- Use [status.md](https://github.com/tuna-os/wootc/blob/main/docs/status.md) and [release instructions](https://github.com/tuna-os/wootc/blob/main/docs/RELEASING.md) for current verification and release decisions. Use dated plans and investigations for context, not as substitutes for those sources. diff --git a/docs/wootc/docs-truth-pass.md b/docs/wootc/docs-truth-pass.md index 9be07c4e..cbffcb39 100644 --- a/docs/wootc/docs-truth-pass.md +++ b/docs/wootc/docs-truth-pass.md @@ -1,13 +1,14 @@ --- -sidebar_position: 20 +sidebar_position: 21 title: "docs truth pass" --- -Every checkable claim in the user-facing docs, walked against the build and -marked ✔ or ✘ (#233). This file is a **dated record of a pass**, not a live -status page: it says what was true on a given commit and what was done about -what wasn't. The live enforcement is `tests/unit/docs-truth.bats`, which turns -each ✘ found here into a test so the same drift fails CI instead of a reader. +This is a **dated record**, not a live status page or a certification. +Each entry states what the reviewer inspected and what remained unobserved. +Static source review does not substitute for a walk through the matching release build. +Earlier entries refer to `tests/unit/docs-truth.bats`. +The 2026-11-02 pass below removed that suite of prose checks. +Those historical references describe the old process, not current enforcement. --- @@ -266,3 +267,66 @@ releases holds `v0.1.0-alpha.1` only. | ✘ | `ROADMAP.md`: v0.3.0-beta *"shipped 2026-09-03"* | The milestone issue #211 closed on 2026-09-02, but nobody cut the release. The roadmap now says that the release is planned and its notes are a draft. | | ✘ | `docs/release-notes-v0.3.0-beta.md`: *"Status: Shipped"* | The notes now carry the draft marker, so `check-notes.sh` refuses to publish them before a person checks them again. | | ✘ | `README.md` and `ROADMAP.md`: an existing beta release | The earlier releases are `v0.1.0-alpha.1` and the automatic pre-releases. | + +## Source and published-artifact audit — 2026-11-02 + +**Baseline:** `167b83ff55a51599666dc75b9be28bfa892c24c7`, with the current +implementation work explicitly separated from previously published artifacts. +**Method:** source/manifests and GitHub issue/release metadata, not an RC VM +walk. No test, screenshot, signing, installation, timing or hardware result is +claimed by this pass. + +GitHub's observed latest non-prerelease was +[`v0.1.0-alpha.1`](https://github.com/tuna-os/wootc/releases/tag/v0.1.0-alpha.1), +published 2026-08-22. Its assets include `wootc.exe`, +`Bazzite-Installer.exe`, `Bluefin-Installer.exe`, `Aurora-Installer.exe`, +`TunaOS-Installer.exe` and `SHA256SUMS`. They do **not** include the native +`*-Installer-Setup.exe`, `native-SHA256SUMS` or `wootc-legacy.exe` names. +The latest ten entries returned by `gh release list` were automatic +prereleases, dated 2026-08-31 and earlier. A closed implementation issue and a +workflow on main do not make a release asset exist. + +| Finding | Evidence and correction | +|---|---| +| Main's native setup was advertised as the latest available download | `gh release view --json tagName,publishedAt,assets`; getting-started and user-guide now distinguish the observed published Wails release from main's native setup packaging | +| The shell page still said phase D had not started and advertised old build pins | Current `shell/Wootc.Shell/Wootc.Shell.csproj` pins Windows App SDK 2.6.4; `shell/global.json` pins SDK 10.0.403. Phase D source packaging exists; #345 closed 2026-10-31. #346 still needs a clean native release before Wails removal | +| Stdio reference conflated legacy and native session capabilities | `app/serve.go` and native authorization/dispatch modules; shell guide now documents launch, framing, errors, every method, session capability, params, schema locations, events, grants and cleanup | +| Contributor tools had no installation path and fast-tier skips were hidden | `tests/run.sh`, `app/go.mod`, CI workflow pins; contributor guide now lists the four lanes and official setup links, separates Linux/KVM, and warns that a PASSED summary with missing lanes is incomplete | +| Literal source/doc strings were treated as regression evidence | Removed `tests/unit/docs-truth.bats` and `app/serve_test.go`'s `TestProtocolMatchesWinuiShellSpec`; source wording tests are not behavioral proof. Existing runtime protocol, golden DTO, fixture and integration suites remain. No new grep-based replacement was added | +| Historical screenshots could be read as current native UI | User-guide captions, GUI walkthrough and branded-ledger framing identify retained Wails/mock illustrations and historical evidence, not RC/native acceptance screenshots | + +### Decisions that remain gates + +- [#544's latest bounded acceptance](https://github.com/tuna-os/wootc/issues/544#issuecomment-6356243044) + requests a fast-tier invocation with executed/skipped lanes and checked + installation links. All eight prerequisite installation references were + fetched successfully with the web reader on 2026-11-02 (PowerShell redirects + to Microsoft's current installation page; Python supplies its release feed). + Integration verification must retain fast-tier output; this documentation + edit does not claim it ran the tier. +- [#233's latest checklist](https://github.com/tuna-os/wootc/issues/233#issuecomment-6247924342) + explicitly leaves RC VM/native hardware, measured timings, signed SmartScreen, + Settings rendering, and RC-SHA screenshots/timelapses open. +- [#596's Option A decision](https://github.com/tuna-os/wootc/issues/596#issuecomment-6514382140) + makes VM-first an RC requirement. Helper receipts, a process, gallery fixtures, + and a closed older ticket do not prove a working named-account desktop or + same-image promotion. + +### RC/manual acceptance ledger — not yet observed by this pass + +| Required observation | Prerequisite / retained evidence | +|---|---| +| Walk README, startup/user/manual/brand/release guides against one immutable RC | Published RC tag/SHA and exact artifacts; record each claim, screen label, log and registry path, pass/fail, tester and fixture identity | +| Minimum native OS and real UAC | Isolated Windows build 17763, plus normal consumer Windows; interactive consent/No and alternate-admin behavior, not only policy-driven refusal | +| Native setup and removal, online and offline | Matching brand setup plus signed artifact metadata; clean machine without development tools/WebView2; retained Apps display and ownership/removal evidence | +| Windows prompts and publisher identity | Final signed RC on a fresh machine; separately record signature validity and observed SmartScreen/policy behavior; neither guarantees the other | +| Timings and constrained hardware | Measured wall time on named CPU/RAM/storage/network; no timing promise from source, helper output or CI duration | +| BitLocker editable Documents and rollback | Disposable encrypted fixture with recovery material; verify visible original and Linux-created files and behavior after failed copy, interruption, return, retry and uninstall | +| VM-first and later promotion | Isolated WHPX-capable Windows host, signed matching runtime, image/account and adequate capacity; real graphical login, nonce/preferences surviving stop/start, unchanged host boot identity, then separately same-image native promotion and return | +| Fresh visual material | Regenerate GUI and branded screenshots and nightly timelapse from that RC; retain SHA, frontend, fixture and provenance. Existing images are not newly dated evidence | +| Real-hardware safety/recovery | Authorized backed-up hardware cohort with pre/post boot, partition, power and filesystem observations; VM results cannot fill this row | + +Keep #233 open until the RC walk has no unexplained failed claim. +The image sets must also pin that RC. The authoritative live matrix and release decision +remain [status](https://github.com/tuna-os/wootc/blob/main/docs/status.md), [roadmap](https://github.com/tuna-os/wootc/blob/main/ROADMAP.md) and +[release instructions](https://github.com/tuna-os/wootc/blob/main/docs/RELEASING.md). diff --git a/docs/wootc/e2e-architecture.md b/docs/wootc/e2e-architecture.md index 2dd43db1..e2a17bac 100644 --- a/docs/wootc/e2e-architecture.md +++ b/docs/wootc/e2e-architecture.md @@ -1,5 +1,5 @@ --- -sidebar_position: 21 +sidebar_position: 22 title: "e2e architecture" --- diff --git a/docs/wootc/finish-plan.md b/docs/wootc/finish-plan.md index 5c46eb08..815f0be3 100644 --- a/docs/wootc/finish-plan.md +++ b/docs/wootc/finish-plan.md @@ -1,5 +1,5 @@ --- -sidebar_position: 22 +sidebar_position: 23 title: "finish plan" --- diff --git a/docs/wootc/firstboot-evidence.md b/docs/wootc/firstboot-evidence.md index 0fe842a4..47652ac5 100644 --- a/docs/wootc/firstboot-evidence.md +++ b/docs/wootc/firstboot-evidence.md @@ -1,5 +1,5 @@ --- -sidebar_position: 23 +sidebar_position: 24 title: "firstboot evidence" --- diff --git a/docs/wootc/getting-started.md b/docs/wootc/getting-started.md index 035a96bb..6ba6b5c6 100644 --- a/docs/wootc/getting-started.md +++ b/docs/wootc/getting-started.md @@ -1,5 +1,5 @@ --- -sidebar_position: 24 +sidebar_position: 25 title: "getting started" --- @@ -20,25 +20,37 @@ anywhere — Downloads is fine. Run the Inno setup as Administrator; it installs the native WinUI shell and protected engine. The native shell does not need WebView2. -Prefer a specific distribution? The same release page carries branded -setup packages of the identical engine — -`Bazzite-Installer-Setup.exe`, `Bluefin-Installer-Setup.exe`, -`Aurora-Installer-Setup.exe`, `TunaOS-Installer-Setup.exe`. -They pre-select their own images and download the whole OS while still on -Windows, which is the right choice on a Wi-Fi-only laptop. - -This release keeps the Wails compatibility build for one release. -The `wootc-legacy.exe` file is the only release download that needs WebView2. - -Command-line folks can use winget once the package clears Microsoft's -one-time review: `winget install TunaOS.wootc`. - -To check your download, compare the release's `native-SHA256SUMS` entry with -PowerShell's `Get-FileHash .\wootc-Installer-Setup.exe` result. -A matching checksum confirms the file matches that manifest. It does not identify the publisher. -The app checks hashes and a signed manifest for its boot artifacts. - -Your browser may say something like *"wootc-Installer-Setup.exe isn't commonly +Main's release workflow now prepares native +`wootc-Installer-Setup.exe`, `Bazzite-Installer-Setup.exe`, +`Bluefin-Installer-Setup.exe`, `Aurora-Installer-Setup.exe` and +`TunaOS-Installer-Setup.exe`, with `native-SHA256SUMS` and a one-release +`wootc-legacy.exe` compatibility artifact. +**Do not assume those files are available in an older tag.** +A matching native package installs the WinUI shell and protected engine. +That shell does not need WebView2. See the +[native shell status](https://github.com/tuna-os/wootc/blob/main/docs/winui-shell.md) and [verification matrix](https://github.com/tuna-os/wootc/blob/main/docs/status.md) +before you test a preview or source build. + +Save the chosen executable anywhere — Downloads is fine. Verify it before +you run it, then use only the instructions for that tag and frontend. +Distribution-specific builds select their own image. Check offline/preloaded +behavior for the particular package; do not assume it from the brand name. +The planned winget command is `winget install TunaOS.wootc`. +It is not an installation route until Microsoft's package review is complete. + +To check an older published download, compare its `SHA256SUMS` entry with +PowerShell's output: + +```powershell +Get-FileHash .\wootc.exe -Algorithm SHA256 +``` + +For a native setup, use that package's actual filename and its release's +`native-SHA256SUMS`. A checksum match does not identify the publisher. +Current engine source also authenticates a signed manifest for boot artifacts; +that is separate from a Windows executable's publisher signature. + +Your browser may say something like *"wootc.exe isn't commonly downloaded"* and hide the file behind a menu. SmartScreen checks file and publisher reputation. A warning can reflect an unknown or negative reputation. If you trust the source and want to continue, choose **Keep** in Edge: `…` → @@ -46,8 +58,9 @@ If you trust the source and want to continue, choose **Keep** in Edge: `…` → ## 2. The blue "Windows protected your PC" screen -When you run `wootc-Installer-Setup.exe`, SmartScreen can show **Windows protected your PC**. -The current release pipeline does not sign the Windows executable. +When you run the selected executable, SmartScreen can show **Windows protected +your PC**. Check the actual artifact's signature. Main's package definition +does not prove that a publisher signed a published Windows binary. A signature identifies a publisher; it does not guarantee that SmartScreen will accept a new file. [Microsoft describes the checks for file and publisher reputation](https://learn.microsoft.com/en-us/windows/apps/package-and-deploy/smartscreen-reputation). @@ -56,28 +69,50 @@ Windows policy can prevent continuation. If you want to verify the download first (a good habit): the Releases page lists a SHA-256 checksum for each file. In PowerShell, -`Get-FileHash .\wootc-Installer-Setup.exe` prints yours to compare. +`Get-FileHash .\wootc.exe -Algorithm SHA256` prints the older generic download's +hash; substitute your actual filename. ## 3. The administrator prompt -Next, Windows asks: *"Do you want to allow this app from an unknown -publisher to make changes to your device?"* +Windows can ask: *"Do you want to allow this app to make changes to your device?"* +The publisher text depends on the artifact's signature. wootc needs administrator rights to create the Linux disk file and change the boot setup. It also reads the system information that it shows you. -The current unsigned executable has no verified publisher identity. Choose **Yes** if you want to allow those changes. +An unsigned executable has no verified publisher identity. Choose **Yes** only +if you trust this exact download and intend to allow those changes. The native +shell normally remains unelevated and requests elevation for its protected +engine; the older Wails app uses a different launch path. ## 4. You're in -From here, the app itself takes over — and the first screen tells you the -most important thing before asking you for anything: +From here, the matching installer takes over. Current source uses the tagline: > Bring Windows to Linux — keep everything. +This is a product goal, not a guarantee of qualification for every app, login +or recovery path. Older published builds and branded packages can show different +screens. See the [user guide](https://github.com/tuna-os/wootc/blob/main/docs/user-guide.md) for behavior in current source +and its evidence boundaries. + The **Install** button starts changes before you restart. The app creates the Linux disk file, copies boot files to the EFI system partition, and changes Windows startup settings. The installer describes each step as it happens. -To uninstall, use **Settings → Apps → TunaOS (wootc) → Uninstall**. -Cleanup can fail and leave files or boot state behind. Linux data removal is a separate choice in Manage. -See the [user guide](https://github.com/tuna-os/wootc/blob/main/docs/user-guide.md#9-uninstall--put-everything-back) for the cleanup actions and data choices. +To uninstall, find the matching product under **Settings → Apps**. The older +generic build registers **TunaOS (wootc)**; native setup uses its brand/package +identity, so the entry can differ. Cleanup can fail and leave files or boot +state behind. Linux data removal is a separate choice in Manage. +See the [user guide](https://github.com/tuna-os/wootc/blob/main/docs/user-guide.md#9-uninstall--put-everything-back) for the +cleanup actions and data choices. + +## Coming from WSL? + +Read the [WSL migration guide](https://github.com/tuna-os/wootc/blob/main/docs/wsl-migration.md) before you change your setup. +Keep a separate export/backup of each WSL distribution and verify any manual +file transfer on Linux. wootc does not automatically import a WSL distribution, +accounts, passwords or active services. It does not promise protection against +all data loss. + +For a work PC, read the [IT-admin quick start](https://github.com/tuna-os/wootc/blob/main/docs/it-admin-quick-start.md). +It describes the single-machine evaluation boundary, not fleet rollout. diff --git a/docs/wootc/gui-phase1-architecture.md b/docs/wootc/gui-phase1-architecture.md index 3084fd44..94c2b840 100644 --- a/docs/wootc/gui-phase1-architecture.md +++ b/docs/wootc/gui-phase1-architecture.md @@ -1,5 +1,5 @@ --- -sidebar_position: 25 +sidebar_position: 26 title: "gui phase1 architecture" --- diff --git a/docs/wootc/gui-walkthrough.md b/docs/wootc/gui-walkthrough.md index a9ff5565..c200ea64 100644 --- a/docs/wootc/gui-walkthrough.md +++ b/docs/wootc/gui-walkthrough.md @@ -1,12 +1,13 @@ --- -sidebar_position: 26 +sidebar_position: 27 title: "gui walkthrough" --- -Screenshots are generated by the Playwright suite (`tests/gui/`), which -drives the real frontend bundle with a mocked backend — so this -walkthrough stays in sync with the shipping UI. Regenerate with -`cd tests/gui && npx playwright test`. +These are **Wails/frontend mock illustrations**, generated by Playwright +(`tests/gui/`) with the frontend bundle and a mocked backend. They do not prove +an installed native shell, a real migration or the RC screenshot gate. +Regenerate with `cd tests/gui && npx playwright test`; retain the SHA and +frontend identity. See the separate [evidence for the native shell](https://github.com/tuna-os/wootc/blob/main/docs/winui-shell.md). ## 1. Launchpad — choose a variant @@ -129,22 +130,23 @@ and a `passwordSet` boolean — never the secret itself. ![Move to Linux](https://raw.githubusercontent.com/tuna-os/wootc/main/docs/screenshots/14-move-to-linux.png) -`wootc-go-native-gui`. While Linux is still running from `root.disk` on -the Windows volume, this offers to graduate onto a real disk. The safety -gates are surfaced directly in the UI — where root currently lives, -whether the Windows layout was recorded, whether a rollback snapshot -exists, and which folders are already native. Graduating keeps Windows -and `root.disk` in place, so it stays reversible. +`wootc-go-native-gui` presents the intended move and observed safety inputs. +Current execution supports a harness path for a blank target disk, with separate gates. +It does not support a general in-place consumer move. It keeps the Windows source and +`root.disk`, but that does not guarantee rollback or preservation of later +native work. Managed-VM boot-input export is also not native arming; see +[managed VM](https://github.com/tuna-os/wootc/blob/main/docs/managed-vm.md#same-image-native-boot-input-export-is-not-promotion). ## 10. Reclaim the Windows space ![Reclaim Windows](https://raw.githubusercontent.com/tuna-os/wootc/main/docs/screenshots/15-reclaim-windows.png) -The same app once you're running natively. Reclaim is **only offered -after your data is native** — the identical hard gate the CLI enforces -(`wootc-go-native` refuses `--reclaim` otherwise). Before anything runs -you get the exact command plan to review; nothing destructive happens -without that explicit confirmation. +The UI can show a reclaim **plan** once native-data prerequisites are met. +Normal-use code does not remove Windows from the same disk because +someone marks a folder native or prints a plan. +Confirmation of this screen does not prove implementation or qualification +of destructive execution, rollback or full data migration. +Keep Windows and a separate backup. ## 11. Bring your Windows over (another disk / BitLocker) diff --git a/docs/wootc/index.md b/docs/wootc/index.md index 131981a3..9117f936 100644 --- a/docs/wootc/index.md +++ b/docs/wootc/index.md @@ -29,8 +29,10 @@ status: unknown --- wootc installs a real Linux desktop from a [bootc](https://github.com/containers/bootc) -image into `root.disk`, a file beside your Windows files. The native WinUI shell is the primary Windows release surface. -[Verification status](https://github.com/tuna-os/wootc/blob/main/docs/status.md) describes the evidence and limits. +image into `root.disk`, a file beside your Windows files. The latest full release, +`v0.1.0-alpha.1`, uses Wails. Native WinUI packaging is implemented on `main`, +but a released native setup and its acceptance evidence remain outstanding. +[Verification status](https://github.com/tuna-os/wootc/blob/main/docs/status.md) distinguishes these builds and their limits. The setup form asks for **a password**. The app suggests your username and computer name from your PC. It sizes the disk from available space and selects TPM encryption by default. @@ -57,24 +59,23 @@ Never post account credentials or API keys in issues or pull requests. > `*-Installer.exe` files and `SHA256SUMS`. **[⬇ Download the latest release](https://github.com/tuna-os/wootc/releases/latest)** -— run `wootc-Installer-Setup.exe` as Administrator. The Inno setup installs -the native WinUI shell and protected engine, fetches boot artifacts, checks hashes, and verifies a signed manifest. -The native shell does not require WebView2. +— the latest full release is `v0.1.0-alpha.1`. Download `wootc.exe`, keep it +beside its downloaded boot artifacts, and run it as Administrator. This +release uses the Wails UI and requires WebView2. -This release keeps the Wails compatibility build as `wootc-legacy.exe`. -Use it only when you need the legacy Wails UI. +Its branded executables are `Bazzite-Installer.exe`, `Bluefin-Installer.exe`, +`Aurora-Installer.exe`, and `TunaOS-Installer.exe`. A branded build is not +evidence of upstream endorsement; see [the approval record](https://github.com/tuna-os/wootc/blob/main/docs/upstream-blessings.md). -``` -winget install TunaOS.wootc -``` - -*(winget follows the generic setup for the native app.)* +The code on `main` prepares the native WinUI shell and protected engine as +`wootc-Installer-Setup.exe` and branded `*-Installer-Setup.exe` assets, with one +`wootc-legacy.exe` fallback. Those assets are not in the latest full release. +Use the asset list of the release you downloaded, not a filename +from a newer build's instructions. -Every release also ships **branded installers** — -`Bazzite-Installer-Setup.exe`, `Bluefin-Installer-Setup.exe`, -`Aurora-Installer-Setup.exe`, `TunaOS-Installer-Setup.exe` — the same engine -with each distribution's identity and preselected images. They can -pre-download the OS on Windows for deployment without a network after reboot. +`winget install TunaOS.wootc` is the intended package command. The first +submission and clean-machine installation remain gated by +[#221](https://github.com/tuna-os/wootc/issues/221); do not assume availability. > The binaries are not yet code-signed. Windows may show SmartScreen or an > "unknown publisher" prompt. Policy can prevent continuation. @@ -86,7 +87,7 @@ pre-download the OS on Windows for deployment without a network after reboot. ## How it works ``` -Windows 11 → wootc-Installer-Setup.exe → native WinUI shell → reboot +Windows 11 → installer GUI → reboot → signed shim → GRUB → deployer initramfs → fisherman: bootc install into root.disk → reboot → Windows → Manage: choose Linux boot diff --git a/docs/wootc/it-admin-quick-start.md b/docs/wootc/it-admin-quick-start.md new file mode 100644 index 00000000..09564599 --- /dev/null +++ b/docs/wootc/it-admin-quick-start.md @@ -0,0 +1,141 @@ +--- +sidebar_position: 28 +title: "it admin quick start" +--- + +wootc is a consumer Windows-to-Linux installer, **not** a fleet deployment or +endpoint-management system. This guide organizes a supervised pilot on one +authorized, recoverable PC at a time. There is no implied unattended rollout, +domain migration, enterprise support agreement or zero-data-loss guarantee. +The [enterprise migration specification](https://github.com/tuna-os/wootc/blob/main/docs/specs/enterprise-migration.md) is a +proposal, not shipped fleet functionality. + +Use [current status](https://github.com/tuna-os/wootc/blob/main/docs/status.md) to select the release and supported journey. +The [manual test guide](https://github.com/tuna-os/wootc/blob/main/docs/manual-testing.md) is for the legacy native path. +Its checklist does not prove a native WinUI or VM-first release. +If the selected build lacks matching instructions and evidence, stop the pilot. +Do not extend a mismatched procedure to multiple PCs. + +## Before authorizing a pilot + +- Name a change approver, operator, data owner and recovery contact. Get + permission to change boot configuration, the ESP and any proposed partition + layout. A local administrator password is not organizational approval. +- Use a spare/test PC before anyone's primary workstation. Record model, + firmware, Windows edition/version, architecture, storage layout and the exact + build/image. **Keep serial numbers and personal identifiers out of public logs.** +- Check UEFI, free space, power and Secure Boot requirements against the release. + Do not generalize one vendor's successful boot to other firmware or images. +- Back up Windows, user data and WSL/application data to independent storage. + Verify a restore. Prepare recovery media for Windows and an escalation route + for boot repair. That route must not depend on the installed Linux system. +- Check BitLocker/device encryption and recovery-key escrow with the security + owner. Confirm an authorized operator can retrieve the key if Windows requests + it. Never put a key in a ticket, screenshot, script argument or public report. + An alpha that refuses encrypted Windows is not permission to decrypt it. + Experimental beta code for keys is not a release qualification; follow + [the encryption policy](https://github.com/tuna-os/wootc/blob/main/docs/user-guide.md#7-encryption--bitlocker) and status gate. +- Confirm support for the user's hardware and required work in the Linux image. + Check Office document fidelity/macros, accessibility, VPN, printers, smart cards, + graphics, meetings, security tools and required applications. Neither a + Linux alternative nor Wine/Proton implies compatibility with every workload. +- Save and close work. Arrange a maintenance window for more than the initial + download. Include install, first login, Windows return, uninstall and recovery. + +## Corporate networks and trust + +Download only the pinned release asset and matching checksum manifest through +approved channels. Compare SHA-256 locally; a checksum does not authenticate a +publisher. The Windows binary may lack a signature; SmartScreen or application +control can refuse it. Do not disable Defender, SmartScreen, WDAC or company +policy to continue. Get a security decision first. + +A blocked launch is valid pilot evidence. + +Check outbound access from Windows to the selected release/artifact and image +registries. Separately check the network needed by the chosen deploy path. +A Wi-Fi-only deployment needs a build that supports preloaded payloads. +A preloaded OS image does not promise an entirely offline installation or updates. + +Captive portals, TLS interception, authenticated proxies and custom CA requirements +need their own pilot. The privileged client for artifacts does **not** inherit +proxy settings from its environment. Do not bypass signature or TLS verification. +Stop and file the exact sanitized error if approved connectivity cannot work. +Never embed proxy passwords in an invitation or public log. + +Saved home Wi-Fi is not proof of enterprise 802.1X enrollment. Expect to enroll +certificates and sign in through the organization's supported Linux procedure. +The migration does not automatically transfer Domain/Entra join, device compliance +or enterprise SSO to a new Linux account. + +## Execute one complete journey + +1. Pin the tag, Windows asset name/hash, image and approved storage plan in the + local change record. Use the [download guide](https://github.com/tuna-os/wootc/blob/main/docs/getting-started.md) and the + build's matching [user guide](https://github.com/tuna-os/wootc/blob/main/docs/user-guide.md). Do not invent silent-install + flags or deploy to a group policy collection. +2. Capture a pre-change baseline for your change record: boot entries, owned + ESP files, partition layout, encryption and power settings. Keep sensitive + machine/account information in your own approved storage. +3. Review the app's proposed changes with the data owner. Installation can + change boot files/settings; an alternate storage plan can change partitions. + Stop on a different disk/partition or an unclear ownership warning. +4. Install, reach a real Linux desktop and test the required work task. Verify + the contents of files, not only folder names. Cloud placeholders do not + contain downloaded data. Migrate one category at a time; keep the source and + backup. For developers, use [the WSL guide](https://github.com/tuna-os/wootc/blob/main/docs/wsl-migration.md). +5. Reboot into the Windows desktop. Check that original files and important + applications still work. Re-enter Linux through the documented Manage path. +6. Follow the [uninstall verification protocol](https://github.com/tuna-os/wootc/blob/main/docs/manual-testing.md#proving-the-uninstall-put-everything-back). + Capture its baseline **after installation and before uninstall**. + Save it outside `C:\wootc`. Uninstall, boot Windows twice and run the verification. + It supplements, not replaces, the pre-change baseline and recovery plan. + + From a reviewed checkout matching the test build, in Administrator PowerShell: + + ```powershell + .\tests\field\verify-uninstall.ps1 capture -Out C:\uninstall-proof + # Uninstall through Settings > Apps; boot Windows twice, then: + .\tests\field\verify-uninstall.ps1 verify -Baseline C:\uninstall-proof -RootDisk keep + ``` + + The example preserves the Linux disk. Data deletion is a separate explicit + choice. Export/verify Linux work before you request deletion. Keep the baseline + and checklist in your change record, and sanitize any public attachment. +7. Record checkpoint outcomes, assistance, symptoms and sanitized evidence in a + [field report](https://github.com/tuna-os/wootc/issues/new?template=manual-test-report.yml). + Only expand after the approver reviews real recovery/uninstall evidence for + each target hardware/image/storage cohort. One successful machine is not a + fleet qualification. + +## Rollback and escalation + +- If Linux fails but firmware offers Windows Boot Manager, select it and verify + the Windows desktop. A reboot request alone is not a successful return. +- If Windows runs, use the app's recovery/Manage controls described in + [problems and recovery](https://github.com/tuna-os/wootc/blob/main/docs/user-guide.md#10-problems-and-recovery). An inspect + operation is not a repair. Do not hand-edit BCD, delete ESP directories or + remove another operating system's entries to force a green report. +- Uninstall tries to remove owned boot entries/files and restore the power + settings it recorded; it can fail. It retains Linux data by default and does + not undo migration onto a graduated native disk. Read every cleanup result. + Verify Windows boot plus retained data before you declare rollback complete. +- If Windows will not start or recovery ownership is uncertain, stop. Use your + organization's prepared process for Windows recovery and its recovery contact. + Do not try an improvised partition resize or irreversible cleanup from chat. +- Stop rollout for suspected data loss, violations of security policy or failures + of recovery. Preserve evidence and backups, and file a sanitized issue. + Get a decision from the responsible maintainer/security owner. + Complete a real rerun before you continue. + +## Evidence and support boundaries + +Internal operational records may contain sensitive details; public wootc reports +must not. Publish only sanitized results with consent. For an external alpha +cohort, use the [cohort aggregate gate](https://github.com/tuna-os/wootc/blob/main/docs/alpha-adopter-program.md), not a list of +employees or machines. + +Do not advertise a migration Discussions category, response SLA or support channel +until a maintainer enables it and assigns moderation. Case studies from consultants +need actual outcomes and customer consent for publication. +This procedure is not a customer endorsement. diff --git a/docs/wootc/managed-vm.md b/docs/wootc/managed-vm.md index cc89db1f..3ec847b0 100644 --- a/docs/wootc/managed-vm.md +++ b/docs/wootc/managed-vm.md @@ -1,5 +1,5 @@ --- -sidebar_position: 27 +sidebar_position: 29 title: "managed vm" --- @@ -7,6 +7,12 @@ The VM uses one Linux system in `:\wootc\disks\root.disk`. A restart reuses that image and `vm\firmware-vars.fd`. It does not redeploy Linux. Native promotion needs more proof (ADR 0004). +The [2026-10-30 decision on #596](https://github.com/tuna-os/wootc/issues/596#issuecomment-6514382140) +chose **Option A: VM-first remains required for RC**. A closed VM +issue does not prove the desktop or same-image native-promotion gate. +The source contracts below do not claim that the latest published tag +contains a complete, usable product with a VM-first workflow. + Standard releases still need to publish the signed runtime package. The GUI offers explicit setup through `InstallVMRuntime`. An executable alone is insufficient. The engine checks the complete runtime @@ -86,6 +92,12 @@ The GUI reuses the Linux username and password fields. It derives the username from Windows when possible. `PrepareVM` accepts these choices. Without an account, `TryInVMFresh` refuses preparation. +Both host and helper accept the same account syntax: 1–32 characters, +`[a-z_][a-z0-9_-]{0,31}`. Host and helper reserve the names `root`, `nobody`, `daemon`, `bin` and `sys`. +They refuse these names before disk preparation. Passwords must be nonempty, +at most 1024 bytes, without NUL or line breaks. These choices create the Linux +account; they do not migrate Windows authentication. + This evidence proves the installed disk and the helper's account result. A usable login and desktop still need independent guest evidence. @@ -121,6 +133,8 @@ It never trusts a reused process ID. | Restart | Only from `ready` or `stopped`, with the same GPT identity | | Stale active state | Recovery required; no automatic restart | | `desktopReady` | Always false until independent guest evidence exists | +| Launch refused before a VM process can run | Preserve the prior verified `ready`/`stopped` phase and disk; record the error so a corrected retry remains possible | +| Failure after a writer could start | Do not infer a clean stop; require observed shutdown or mark recovery | The bounded wait allows the engine to exit. A forced stop never becomes a clean stop. Follow-up work includes filesystem recovery, account/login proof, @@ -129,6 +143,59 @@ a desktop probe, and promotion of the same system to native boot. The shutdown evidence follows the [QEMU QMP reference](https://www.qemu.org/docs/master/interop/qemu-qmp-ref.html#event-SHUTDOWN). A guest request to power off does not prove that each application saved its documents. +### Same-image native boot-input export is not promotion + +Current source can try an export that does not arm boot from a VM with verified stopped state. +It uses the signed builder's advertised `export-boot` operation. +This needs a matching helper/runtime, rebuilt and re-signed; an older runtime without that operation +refuses. It attaches the existing target read-only, with no scratch disk, +network or account credentials. + +The installed kernel must match its module tree and BLS entry. +A tmpfs overlay provides workspace for the installed `dracut`. +It creates a separate native initramfs with the required attach/storage closure. +It does not borrow a different kernel ABI as a fallback. + +The bounded export contains fixed boot files and validated digests, bound to +the current run, installation and GPT disk identity. Artifacts stay under +`vm/native-boot-`; `vm/promotion.json` records `exporting`, +`export-failed` or `boot-inputs-verified`, while VM state remains stopped. +The separate entry for native boot preserves the installed root/ostree options. A successful +export still returns **not armed**: it does not write the ESP/BCD, prove Secure +Boot/hardware readiness, or establish a native login. VM execution, filesystem +immutability and same-image native boot still need real runtime acceptance. + +## Required runtime acceptance (not supplied by the helper receipt) + +Use an isolated Windows 11/WHPX fixture with at least 8 GiB of host RAM. +Keep 88 GiB free on the target volume. +Use a matching signed runtime and a pinned supported image. +Keep the account and disk disposable, not a user's live PC. + +1. Record Windows `LastBootUpTime`, `bcdedit /enum all`, BitLocker and Fast + Startup before preparation. Use the actual app account/`PrepareVM` route. +2. Retain the helper receipt and matching installation/GPT disk identity. + Log in to the real graphical desktop using the chosen account; capture it. + In a graphical editor, save a random nonce to + `~/Documents/wootc-vm-first.txt`, change an application preference, and reopen + both in the guest. A shell command or receipt is not graphical-login proof. +3. Request `StopVM`. Check for guest QMP `SHUTDOWN` evidence **and** actual + process exit before you accept `stopped` with no writer. +4. `BootInVM` must reuse the same disk path/GPT identity and firmware variables. + Reopen the nonce/preference graphically. Confirm Windows boot identity and + boot configuration did not change: this must not need a host native reboot. +5. Current native promotion may export boot inputs, but must report **not armed**. + It must leave BCD/ESP and bytes on the target disk unchanged. + A future positive gate for promotion needs native login into the **same installed system**. + Read the VM nonce/preference, then create a second native nonce. + Return cleanly to Windows, launch the VM again, and read both markers. + Do not mark that gate passed from export or a redeployed image. + +`desktopReady` deliberately remains false; the draft guest observer is not a +substitute for a desktop observer that independent checks verify, with installation and connections complete. +Keep receipts, guest screenshots, process/shutdown evidence, host boot +observations and exact build/image/runtime identities together. + ## Probe source The embedded boot sector is 512 bytes. Its source is in diff --git a/docs/wootc/manual-testing.md b/docs/wootc/manual-testing.md index fe4d77d3..e1f42d2b 100644 --- a/docs/wootc/manual-testing.md +++ b/docs/wootc/manual-testing.md @@ -1,5 +1,5 @@ --- -sidebar_position: 28 +sidebar_position: 30 title: "manual testing" --- diff --git a/docs/wootc/milestones.md b/docs/wootc/milestones.md index 81521751..91424f26 100644 --- a/docs/wootc/milestones.md +++ b/docs/wootc/milestones.md @@ -1,5 +1,5 @@ --- -sidebar_position: 29 +sidebar_position: 31 title: "milestones" --- diff --git a/docs/wootc/non-bootc-adoption.md b/docs/wootc/non-bootc-adoption.md index 9e36d658..65b710a1 100644 --- a/docs/wootc/non-bootc-adoption.md +++ b/docs/wootc/non-bootc-adoption.md @@ -1,5 +1,5 @@ --- -sidebar_position: 30 +sidebar_position: 32 title: "non bootc adoption" --- diff --git a/docs/wootc/ntfs-on-linux.md b/docs/wootc/ntfs-on-linux.md index 807d8562..53e276e9 100644 --- a/docs/wootc/ntfs-on-linux.md +++ b/docs/wootc/ntfs-on-linux.md @@ -1,5 +1,5 @@ --- -sidebar_position: 31 +sidebar_position: 33 title: "ntfs on linux" --- diff --git a/docs/wootc/phase2-attach-postmortem.md b/docs/wootc/phase2-attach-postmortem.md index 0a6f3dce..1dc434ff 100644 --- a/docs/wootc/phase2-attach-postmortem.md +++ b/docs/wootc/phase2-attach-postmortem.md @@ -1,5 +1,5 @@ --- -sidebar_position: 32 +sidebar_position: 34 title: "phase2 attach postmortem" --- diff --git a/docs/wootc/phase2-debug-plan.md b/docs/wootc/phase2-debug-plan.md index cab507fb..c3b0d7e5 100644 --- a/docs/wootc/phase2-debug-plan.md +++ b/docs/wootc/phase2-debug-plan.md @@ -1,5 +1,5 @@ --- -sidebar_position: 33 +sidebar_position: 35 title: "phase2 debug plan" --- diff --git a/docs/wootc/philosophy.md b/docs/wootc/philosophy.md index a23090e1..d98fe421 100644 --- a/docs/wootc/philosophy.md +++ b/docs/wootc/philosophy.md @@ -1,5 +1,5 @@ --- -sidebar_position: 34 +sidebar_position: 36 title: "philosophy" --- diff --git a/docs/wootc/plan.md b/docs/wootc/plan.md index b8d17188..8d683eca 100644 --- a/docs/wootc/plan.md +++ b/docs/wootc/plan.md @@ -1,5 +1,5 @@ --- -sidebar_position: 35 +sidebar_position: 37 title: "plan" --- diff --git a/docs/wootc/plugin-architecture.md b/docs/wootc/plugin-architecture.md index 8984f150..5197e2f3 100644 --- a/docs/wootc/plugin-architecture.md +++ b/docs/wootc/plugin-architecture.md @@ -1,5 +1,5 @@ --- -sidebar_position: 36 +sidebar_position: 38 title: "plugin architecture" --- diff --git a/docs/wootc/prefilled-profile-testing.md b/docs/wootc/prefilled-profile-testing.md index aa12a298..22cc4902 100644 --- a/docs/wootc/prefilled-profile-testing.md +++ b/docs/wootc/prefilled-profile-testing.md @@ -1,5 +1,5 @@ --- -sidebar_position: 37 +sidebar_position: 39 title: "prefilled profile testing" --- diff --git a/docs/wootc/project-review-2026-09-26.md b/docs/wootc/project-review-2026-09-26.md index 535c678d..c7bd742a 100644 --- a/docs/wootc/project-review-2026-09-26.md +++ b/docs/wootc/project-review-2026-09-26.md @@ -1,5 +1,5 @@ --- -sidebar_position: 38 +sidebar_position: 40 title: "project review 2026 09 26" --- diff --git a/docs/wootc/release-notes-v0.3.0-beta.md b/docs/wootc/release-notes-v0.3.0-beta.md index 73fc4914..c718fae7 100644 --- a/docs/wootc/release-notes-v0.3.0-beta.md +++ b/docs/wootc/release-notes-v0.3.0-beta.md @@ -1,5 +1,5 @@ --- -sidebar_position: 39 +sidebar_position: 41 title: "release notes v0.3.0 beta" --- diff --git a/docs/wootc/release-notes-v1.0.0.md b/docs/wootc/release-notes-v1.0.0.md index 63fffa5b..b4b755ff 100644 --- a/docs/wootc/release-notes-v1.0.0.md +++ b/docs/wootc/release-notes-v1.0.0.md @@ -1,5 +1,5 @@ --- -sidebar_position: 40 +sidebar_position: 42 title: "release notes v1.0.0" --- diff --git a/docs/wootc/session-migration.md b/docs/wootc/session-migration.md index 8f19c9a3..8bde3f5e 100644 --- a/docs/wootc/session-migration.md +++ b/docs/wootc/session-migration.md @@ -1,109 +1,242 @@ --- -sidebar_position: 41 +sidebar_position: 43 title: "session migration" --- -North Star: the user should not have to re-set-up their digital life. So -we try, in this order, to carry each app's *logged-in session* across — -and when we can't do it safely, we make re-authenticating one tap, not a -scavenger hunt. +## Scope and evidence, 2026-11-02 -## The key realization: decrypt in Windows, not in the deployer +The goal is to preserve a person's digital setup where safe. Otherwise, help +the person sign in or re-link. -Most "you can't migrate the session" folklore assumes offline access from -Linux. But the **wootc installer GUI runs inside the user's live Windows -session**, where the DPAPI master key is unlocked. That is exactly where -Chromium/Electron `safeStorage` and cookie databases *can* be decrypted. +**A copied profile, unlocked key, rewritten database, +or synthetic crypto fixture is not proof of a logged-in service.** -So session handling splits by *where* it must happen: +The source can rewrite supported stores from Chrome/Edge within strict bounds. +It targets profiles that Chrome has initialized on Linux. -| Where | What it can do | Owns | +The real disposable-account Chrome/Edge/Spotify launch-and-restart matrix remains +a separate gate (#296). Spotify's actual session format and Linux safeStorage +identity remain unsupported: sign in again. + +This describes source behavior, not a promise that the older published +`v0.1.0-alpha.1` contains the target-side importer. See the [start guide](https://github.com/tuna-os/wootc/blob/main/docs/getting-started.md) +and [verification status](https://github.com/tuna-os/wootc/blob/main/docs/status.md). The +[unlock ADR](https://github.com/tuna-os/wootc/blob/main/docs/adr/0005-session-envelope-unlock.md) records the explicit-password +contract; a maintainer must still approve it for #252 acceptance. + +## Ownership and consent + +| Stage | Responsibility | What it does not prove | |---|---|---| -| **Windows GUI (online, DPAPI available)** | decrypt cookies/tokens, re-encrypt for transport | `slurp_windows.go` session collectors | -| **Deployer (offline)** | copy plain-file state only | `wootc-detect-apps`, `wootc-import-browser` | -| **Target first-login** | re-import, or present a one-tap re-link | dashboard + `wootc-apply-look` | - -## Per-class strategy - -**Plain-file sessions → copy verbatim (already implemented).** -Firefox/Thunderbird whole profile, Telegram `tdata`, VS Code, OBS. These -carry the login with no decryption. Done in the deployer. - -**Chromium/Electron `safeStorage` (Discord, Slack, Spotify, Chrome, Edge) -→ decrypt-and-rewrap in Windows.** At slurp time the GUI: - -1. reads the app's `Local State`, DPAPI-decrypts the `os_crypt.encrypted_key`; -2. uses it to decrypt the Cookies/Local Storage LevelDB entries; -3. re-encrypts the payload under a key derived from the wootc vault - secret (never written in clear to disk), stored in - `install\slurp\session\.enc`. -On the Linux side, once the app's equivalent store is written back, -re-encrypted under the Linux `safeStorage` (libsecret/kwallet), and verified -against real service invalidation, the app opens signed in. **Gated behind -explicit user consent per app** — this is moving auth tokens, so the dashboard -asks first and defaults off. Until the target consumer and test matrix prove -a migration, the key remains staged and the UI honestly says so. - -### Online rewrap contract - -The Windows installer now has the first complete, testable half of that -contract. `collectSessions` writes only decryptability findings. The install -configuration's `sessionConsent` map is opt-in per app; missing and false -entries do nothing. For a consented Chrome, Edge, or Spotify entry, the -installer decrypts the DPAPI-protected Chromium master key while the user is -online and writes `install/slurp/session/.enc`. It also writes an -`exports.json` ledger whose state is `staged`, never `imported`. - -That file is a versioned, authenticated AES-256-GCM envelope with the binary -layout `[version | 32-byte salt | nonce | ciphertext+tag]`. Its key is -derived with HKDF-SHA256 from the Linux vault secret, app name, and the fresh -per-envelope salt; the app name is also authenticated as associated data. -The DPAPI key is never written in clear. Files are created with mode `0600` -and the export is best-effort: a failed export does not fail installation or -claim that the session moved. - -The target-side consumer still must decrypt the envelope, enumerate the -app's SQLite/LevelDB values, and re-encrypt them with the Linux keyring. That -work is deliberately separate because Chrome, Edge, and Spotify differ in -database layout and token invalidation behavior. Discord and Slack remain -re-link-only even when DPAPI can read their key. - -`decryptChromiumValue` (`app/session_chromium_value.go`) implements the one -sub-step of that whose correctness doesn't depend on a live browser: given -the os_crypt key recovered from the envelope, it decrypts a single Cookies -`encrypted_value` (or Local Storage value) in Chromium's documented `v10` -wire format — `"v10" | 12-byte nonce | ciphertext | GCM tag`, AES-256-GCM. -Tested against synthetically-sealed fixtures, not a real browser. Still -unclaimed: enumerating a real Cookies SQLite/Local Storage LevelDB file, -`v11`-prefixed values (which add platform-specific associated data on some -Chrome versions — not documented consistently enough to implement blind), -and the actual libsecret/kwallet write on the target. Those need a real -Chrome/Edge install and a Linux D-Bus session to verify against, neither -of which this change had access to. - -Until that consumer completes and records `imported`, the dashboard must show -staged guidance ("staged — you'll sign in once on Linux") or re-link/sign-in -guidance rather than a signed-in result. A staged key is an implementation -artifact, not evidence that a token transplant succeeded. - -**Phone-linked apps → guided re-link, not token theft.** Signal, WhatsApp, -and (when token copy is declined) any messenger: the safest, most durable -path is the app's own "link a device" flow. The dashboard shows the exact -steps and, where possible, deep-links the Linux app straight to its -QR/scan screen. This is *better* than copying a fragile token that the -service may invalidate on a new device fingerprint. - -**Cloud-account apps → one-tap sign-in.** Spotify library, Discord -servers, Zoom — the content is server-side; a single sign-in restores -everything. The dashboard frames it that way ("your playlists are waiting -— just sign in") instead of implying data was lost. - -## Honesty rules (non-negotiable, North Star) - -- Never claim a session moved when only bookmarks did. -- Never silently copy auth tokens — always consent, always per-app. -- Prefer re-link over token copy when the service is known to invalidate - transplanted sessions (avoids a broken-looking app on first launch). -- Every app row in the dashboard states its real outcome: *signed in*, - *staged — sign in once*, *re-link needed (2 steps)*, or *sign in once*. -- No UI surface implies a migration that wasn't measured. +| Windows online collector | Identify the original interactive user, assess DPAPI decryptability, export a consented per-app os_crypt key | Linux compatibility or accepted login | +| Deployer | Retain encrypted session envelopes on the Windows volume; do not install copies under `/usr/share` | Unlock or authentication | +| Linux dashboard | Ask for per-app consent and the original installation password for this attempt; invoke the target import action | Successful service login | +| Linux importer | Validate source/envelope/schema/keyring, prepare replacements, preserve existing identities and backups, record outcome | Live authentication, token validity, account/service acceptance | +| User/runtime acceptance | Open the actual app with a disposable account and check behavior after restart | A generic guarantee for other app versions or services | + +Consent defaults off. Windows `InstallConfig.sessionConsent` opts in per app; +missing/false entries stage nothing. Import on Linux needs separate, explicit +consent for each app. Do not silently infer one from the other. + +The native RPC for installation now refuses `sessionConsent`: its strict +plan is not a session-export API. The legacy path on Windows refuses if it +cannot establish the original interactive user. It also refuses if elevation +changes that identity. Environment variables do not grant authority to access another user's encrypted data. + +## Windows envelope and discovery + +The exporter stages only the DPAPI-recovered **32-byte os_crypt key**, not a +complete cookie database or token payload, at +`:\wootc\install\slurp\session\.enc`. Its `exports.json` ledger +uses `staged`, `skipped` or `failed`, never authenticated/imported success. +Export is best-effort; the UI must not report a failed export as a transferred session. + +The envelope uses versioned, authenticated AES-256-GCM: +`[version | 32-byte salt | nonce | ciphertext + tag]`. HKDF-SHA256 derives the +key from the original password for Linux installation, app name and fresh salt. +The app name is also associated data. +The installer persists a password hash, not recoverable plaintext. +A later Linux login/password change does not change which password opens an already staged envelope. + +Target discovery is **only**: + +```text +/run/wootc/host/wootc/install/slurp/session/ + exports.json + chrome.enc + edge.enc + spotify.enc +``` + +The importer only reads the Windows source. It does not fall back to `/usr/share`, +accept an arbitrary envelope path from a caller, or scan recursively. +It consumes only supported app names with a `staged` ledger entry. +It ignores a source ledger that claims `imported`; that claim is not evidence. +The importer limits the ledger to 64 KiB and each regular, non-symlink envelope to 4096 bytes. + +It refuses duplicate entries for supported apps, changed/unsafe files, unsupported +versions, failed GCM authentication and non-32-byte payloads. + +## Unlock, retry, cancellation and cleanup + +- Enter the **original installation password** explicitly for each try. + It is not a Windows password or a request to unlock all Linux secret stores. + The dashboard must not prefill it from durable state. +- The password travels only in the in-process request. + The app does not retain it in `App` state, a ledger, logs, command-line arguments, environment, or a file. + The code will clear mutable buffers after use. + Go/JavaScript strings and garbage collection provide no guarantee of complete erasure from memory. +- Wrong password, damaged envelope and unsupported version share a safe unlock + refusal; do not reveal or log secret material. The source stays `staged` + and unchanged. The person may retry with a new password; there is no durable + lockout counter or retry secret cache. +- Cancel before submission closes the form without import. + After submission, the modal disables Cancel/Escape; it offers no in-flight cancel control. + Process shutdown/context cancellation and time limits on secret-store work still apply. + Do not report a partial operation as success. + A closed form does not prove that the worker stopped. Keep rollback errors. +- Unlock alone never deletes the envelope or changes its source ledger. + This importer leaves originals on NTFS for retry; it does not automatically wipe them after a rewrite. + They remain sensitive encrypted material. + Do not attach them, browser databases or secrets from credential stores to a public issue. + +## Target action and supported formats + +`App.ImportAppSession` takes this JSON-shaped Wails request (this is **not** a +new `wootc.exe serve` method and there is no shell unlock CLI): + +```json +{"app":"chrome","consent":true,"password":"","backend":"secret-service","packaging":"flatpak","sourceProfile":"Default","targetProfile":"Default"} +``` + +Treat this as an input schema, not a command to paste with a real password. +`app` is `chrome` or `edge` for supported rewrites. +For `spotify`, the action returns re-link advice and does not change a profile. +`packaging` is explicitly `flatpak` or `native` for the initialized **Google Chrome** target: + +- Flatpak: `~/.var/app/com.google.Chrome/config/google-chrome` +- Native: `~/.config/google-chrome` + +Source and target profile names are `Default` or numbered `Profile N` names. +An Edge source on Windows maps to the Chrome target on Linux. +This does not establish support for arbitrary native/Flatpak Edge destinations or package identities. +Open the target once, then close all Chrome/Chromium processes. +Import as the installed user in their desktop session. + +The importer will refuse unsafe paths, active browsers, singleton locks, missing/uninitialized +profiles, concurrent imports and unsupported package types. +Do not delete browser locks to bypass this. +The target must already contain a compatible Cookies database (schema 23/24). +If the source has Local Storage, the target also needs its own `Local Storage/leveldb` `VERSION=1` store. +An otherwise empty profile does not suffice without those stores, even after you open it. +The importer never invents a destination schema or automatically initializes a new database. + +### Cookies SQLite + +- The importer supports validated schemas **23 and 24** for Chromium. + It supports `v10` AES-GCM values from Windows and domain binding for schema 24. + It refuses Windows app-bound `v20`, unknown schema/crypto prefixes and incompatible rows; it does not guess a decryption scheme. +- The importer will re-encrypt imported values with the Linux secret store that the person explicitly selects. + Cookie identities that already exist in the target win. + Import does not authorize changes to native cookies or removal of a signed-in target account. +- Stage into a complete replacement, retain the adjacent + `.wootc-session-backup-*` original, and use atomic exchange. + The importer never changes the source database on Windows. + +### Local Storage LevelDB + +The supported Chromium `VERSION=1` store contains script-controlled bytes, +not a universal format for encrypted safeStorage values. +The importer merges records for supported origins **byte-for-byte** and preserves origins that already exist in the target. +It does not blindly decrypt every value that resembles `v10`. +It refuses unknown metadata/layout, corruption or locks. +Generic Chromium fixtures do not establish Spotify/Electron record layout or invalidation behavior. + +An error in a later store or the outcome ledger will request rollback of replacements +that the importer has already published during normal operation. +Before publication or rollback, the importer checks again for an active browser. +It also rechecks file identity/inode, content digest and database sidecars, with the same checks for the backup to restore. +If the browser becomes active or either store changes, rollback **refuses** to overwrite newer data. +It reports both paths for manual recovery. + +This is **not a browser lease or a crash-atomic multi-store transaction**. +A browser can race an observation. +A process/power failure between stores can leave a partial format rewrite. +The importer retains all stores that it published or displaced, even after an otherwise clean rollback. +Late writes through open file descriptors can still reach those stores. + +Do not automatically erase these recovery copies or assume that one path contains every latest write. +Keep them private and stop the browser. +Inspect reported paths/errors before manual recovery or retry. +The operation does not produce a signed-in state. + +## Linux safeStorage prerequisites and limitations + +Select `backend` explicitly: `secret-service`, `kwallet5` or `kwallet6`. +The importer does not guess a backend, fall back automatically, generate a new secret, +or use Chromium `basic_text`/plaintext fallback. +It uses the target Chrome identity, even when the Windows source is Edge: + +| Backend | Existing identity required | +|---|---| +| Secret Service | `application=chrome`, Chrome Safe Storage secret, in the existing unlocked default collection | +| KWallet 5/6 | Existing network wallet, folder `Chrome Keys`, key `Chrome Safe Storage`, application `Google Chrome` | + +Run as the installed desktop user with a valid, explicit `DBUS_SESSION_BUS_ADDRESS`. +Use an active, permitted service and the existing unlocked collection/wallet. +The adapter does not activate a service or invoke Secret Service Unlock/Prompt. +Secret Service uses its standard `plain` transport session on that user's D-Bus. +This does not store the browser secret as plaintext. + +KWallet checks whether the wallet has an unlocked state before the native call to acquire a handle. +If the wallet locks between those calls, the unavoidable race can still cause a daemon prompt. +Do not promise a no-prompt guarantee. + +The target Flatpak must use that exact key identity and have the required D-Bus access. +Do not assume compatibility with portal-only or isolated access. +Output uses Linux Chromium `v11` safeStorage with AES-128-CBC and its documented PBKDF2 parameters. +That byte-format conversion is not proof of browser or service acceptance. +Spotify support needs real, versioned, sanitized Linux/Windows records and a verified safeStorage identity. + +## Detection, ledgers and presentation + +`wootc-detect-apps --detect-browsers [username]` detects browsers and only reads their data. +It honors the standard `WOOTC_HOST`, `WOOTC_WIN_USER` and `WOOTC_WIN_USER_DIR` source-selection contract. +Browser plugins, the manifest fallback and the legacy detector for apps consume those records. +Detection itself does not copy browser data or change mount/user-directory setup. + +Browser detection will retain discovery and source fields for Firefox `profiles.ini` and Chrome/Edge `User Data`. +UI outcomes remain `portable`, `staged` or `signin`, with details. +A source export's `staged` entry is eligibility, not proof of authentication. +The UI must not show signed-in status from even an untrusted source `imported` marker. + +The importer will record outcomes for the target separately in +`~/.config/wootc/session-imports.json`: `rewritten` or `failed`, with +`verified:false`; Spotify is re-link-only. The action result includes `app`, +`state`, `verified`, `reason`, `cookiesWritten`, `localRecordsWritten`, +`recordsPreserved` and optional backup paths. The source export ledger stays `staged`. +Use text such as **“Supported records rewritten; sign in if requested”**. +Never report **“Session moved”** or **“Signed in”** from that result. + +Firefox whole-profile copies can include saved passwords, but still do not +prove every service accepts the new profile. Phone-linked apps should use +their own link-a-device flow. Discord/Slack remain sign-in/re-link routes; +a DPAPI key alone is not permission to transplant their credentials. + +## Remaining runtime acceptance + +Use a disposable source account on real Windows and a graphical session on Linux. +Use real, initialized Chrome/Edge stores and supported versions of SQLite. +Test each required combination of secret store, backend and package type. +Verify source and target preservation, explicit consent, wrong-password retry and cancellation. +Verify refusal of locked secret stores, preservation of duplicate identities/origins, and multi-store rollback. +Verify that the outcome persists after a dashboard restart. + +For authentication acceptance, get consent to use a disposable account for the service. +Open the real destination app and observe the expected account/content. +Quit and restart it. +Retain sanitized evidence that identifies the app version, backend, package type and build SHA. +Record invalidated sessions as sign-in/re-link, not migration success. + +Spotify remains blocked on real fixtures for its format and secret store. +Synthetic cookie, LevelDB or D-Bus tests cannot replace this matrix. diff --git a/docs/wootc/soak.md b/docs/wootc/soak.md index 1b0aca03..9e3be42f 100644 --- a/docs/wootc/soak.md +++ b/docs/wootc/soak.md @@ -1,5 +1,5 @@ --- -sidebar_position: 42 +sidebar_position: 44 title: "soak" --- @@ -57,30 +57,37 @@ diagnosis issue on the same day. Automatic pre-releases continue each day. ## Native proof contract -Wails cannot qualify. A future native runner must supply a job named -`native-shell GUI acceptance`. These steps must pass: +Wails cannot qualify. `tests/e2e/native-proof*` and the dedicated workflow job +for the full cycle will produce native proof. GitHub must +report its qualified job name as `native-proof / native-shell GUI acceptance`. +These steps must pass: - `Verify native process identity` - `Assert native UIA journeys` - `Capture native framebuffer` -It must upload both artifacts in the same run and try. The ledger does not -supply that runner. +The producer must upload both artifacts in the same run and try. Its +implementation is not proof that a real Windows/Linux/Windows cycle passed. - `native-shell-build--`: the tested `Wootc.Shell.exe` at the archive root. - `native-gui-soak-proof--`: the native receipt, raw UIA captures, - PNG framebuffers, and an independent Linux boot observation at the archive root. + PNG framebuffers, an independent Linux boot observation, and + `windows-current-observation.json` at the archive root. The collector checks the IDs and digests of artifacts from GitHub. It checks the source SHA and try number. The hash of the native process must match the bytes of the packaged executable. The receipt must name WinUI 3 and Windows UI Automation. The collector rejects browser receipts. -Each required control must be visible and enabled. Its observed value must -match the required value. A screenshot alone fails. The Linux summary must match -a separate observation from Linux in that try. Its capture time must fall inside -the try and before the UI summary. The record must match the live Linux boot ID. Missing or stale evidence fails. -Ambiguous or incorrect evidence also fails. +Each required control must be visible and enabled, with the required observed +value. A screenshot alone fails. The Linux summary, including `InstalledBootId`, +must match independent live Linux facts from that try. + +The current-Windows observation comes from Windows CIM, not a UI claim. The +collector needs this chronology within the same run and try: +confirmation → live Linux facts → actual Windows boot → UI summary → +Windows capture → completed return. Missing, stale, ambiguous or contradictory +evidence fails. An earlier Windows boot cannot prove a Linux-to-Windows return. [The verifier](https://github.com/tuna-os/wootc/blob/main/tools/soak/ledger.py) defines the receipt fields and control IDs. It hashes sorted `(path, Git blob SHA)` arrays as compact JSON with SHA-256. @@ -88,6 +95,6 @@ It hashes sorted `(path, Git blob SHA)` arrays as compact JSON with SHA-256. the conservative transport identity. The collector compares them with the GitHub tree at the tested commit. The ledger records the source SHA, executable hash, IDs of artifacts, and hashes -of archives. Artifact expiry cannot remove a retained observation. The native -producer and real VM proof remain necessary before any row can qualify. +of archives. Artifact expiry cannot remove a retained observation. Real VM proof +of the producer remains necessary before any row can qualify. This ledger schedules no VM run and starts no soak. diff --git a/docs/wootc/status.md b/docs/wootc/status.md index 6d78eb32..62eb5bc5 100644 --- a/docs/wootc/status.md +++ b/docs/wootc/status.md @@ -1,5 +1,5 @@ --- -sidebar_position: 43 +sidebar_position: 45 title: "status" --- @@ -9,11 +9,52 @@ The [ROADMAP](https://github.com/tuna-os/wootc/blob/main/ROADMAP.md) says where what the evidence supports today. The verification ladder itself is defined in [milestones.md](https://github.com/tuna-os/wootc/blob/main/docs/milestones.md). +## Current release and acceptance boundary — 2026-11-02 + +The latest full release is +[`v0.1.0-alpha.1`](https://github.com/tuna-os/wootc/releases/tag/v0.1.0-alpha.1), +published on 2026-08-22. Its assets are the Wails `wootc.exe` and branded +`*-Installer.exe` executables; it has no native `*-Installer-Setup.exe`, +`wootc-legacy.exe`, or `native-SHA256SUMS`. + +The native package cutover (#345) merged and closed on 2026-10-31. That +implementation does not prove a released native artifact or its GUI, setup, +accessibility, hardware, and full-cycle gates. Issue #688 tracks the post-cutover +defects in authority and publisher policy. + +The maintainer reaffirmed VM-first as an RC requirement on 2026-10-30 in +[#596](https://github.com/tuna-os/wootc/issues/596#issuecomment-6514382140). +Closure of #178 does not establish complete acceptance here. +That still needs a desktop on Windows, persistent work, and native promotion of the same system. +The soak has no recorded start; earlier native/Wails passes cannot count. + +The following dated records remain historical evidence. References below to +# 209 or #399 as open describe their old run context; both issues are now +closed. Neither closure upgrades an old matrix row to a candidate pass. + The native-cycle matrix below records Windows seed → deploy → native Linux boot → seeded file readable from Linux. It does not prove Phase 1 inside Windows. [ADR 0004](https://github.com/tuna-os/wootc/blob/main/docs/adr/0004-restore-vm-first-product.md) needs a usable Linux VM, with persistent user work, before native promotion. That gate remains open. +## Development-worktree checks — 2026-11-02 + +These checks exercise the current source work. They are not a released artifact, +hosted matrix acceptance, or permission to open a support-policy gate. + +| Check | Observed result and boundary | +|---|---| +| Full fast tier | Passed Bats, Python and Go modules, including catalog synchronization, recovery, import and session controls. | +| PowerShell | Repository syntax lint, the new native observer parser, and all 136 PowerShell unit checks passed on Linux; not Windows mutation proof. | +| Native shell components | All 195 portable shell tests passed. Native/UI test projects cross-built; actual WinUI execution/setup remains unproven. | +| Legacy frontend | All 65 mock-backed GUI cases passed. Browser interaction also exercised editable secondary profiles, duplicate refusal and corrected input contrast; not native Windows proof. | +| Mounted migration scripts | Isolated Corral Ubuntu VM running privileged Fedora containers: main suite 90/90, auxiliary folder/profile suites 6/6, 6/6 and 12/12. Actual ordinary-user Documents editing/reopen, preserved Windows originals, collisions and refusal paths were exercised on seeded files, not real BitLocker. | +| Linux credential backend | Actual isolated Secret Service creation/reopen and locked, missing-keyring and unavailable-service states exercised. This does not prove a real authenticated browser/application session. | + +The fixture for nested Windows reached a Windows lock screen, but lacked a +usable control channel for QGA. This record claims no pass for a native Windows full-cycle, +real BitLocker/TPM, signed setup, firmware mutation or VM promotion of the same system. + ## Phase 1: Linux inside Windows | Gate | Status | Evidence as of 2026-09-26 | @@ -101,7 +142,7 @@ Each package passed the startup check for its brand. These are component checks with the same elevated user. Interactive UAC, original-user collection, the minimum OS, and the full native journey remain open. [The source record](https://github.com/tuna-os/wootc/blob/main/docs/experiments/evidence/2026-09-27-native-serving-readiness/hosted-7a/provenance.json) retains the exact source, jobs, and artifact hashes. -Wails remains the default. #343 and #344 remain open. +This September component run used Wails as the default. The later native cutover is described above; #343 and #344 still require their own acceptance evidence. ## Build/test matrix diff --git a/docs/wootc/systemd-boot.md b/docs/wootc/systemd-boot.md index 4529721e..289b954c 100644 --- a/docs/wootc/systemd-boot.md +++ b/docs/wootc/systemd-boot.md @@ -1,5 +1,5 @@ --- -sidebar_position: 44 +sidebar_position: 46 title: "systemd boot" --- diff --git a/docs/wootc/upstream-blessings.md b/docs/wootc/upstream-blessings.md index a8c4e157..6b21ef76 100644 --- a/docs/wootc/upstream-blessings.md +++ b/docs/wootc/upstream-blessings.md @@ -1,5 +1,5 @@ --- -sidebar_position: 45 +sidebar_position: 47 title: "upstream blessings" --- @@ -15,9 +15,75 @@ brand, summarised in the table in documentation: `packaging/brands.sh` reads them, and a **declined** brand's exe drops out of the release matrix. -**Current state: nothing has been asked yet.** Bluefin, Bazzite and Aurora -are all `pending` with `ask.filed: false`. This document exists so that -filing the ask is a copy-paste rather than a blank page. +**Recorded state as of 2026-11-02:** Bluefin, Bazzite and Aurora are all +`pending`, all four decisions are `pending`, `ask.filed` is `false`, and +`winget.identifierAgreed` is `false`. The records contain no third-party approval. +The self-owned `wootc` and `tunaos` records are `blessed`; that is not an +upstream endorsement of any image or migration path. + +| Project | Authoritative permission record | Ask / branded distribution / winget | +| --- | --- | --- | +| Bluefin | [blessing.json](https://github.com/tuna-os/wootc/blob/main/app/branding/bluefin/blessing.json) | not filed / pending / not agreed | +| Bazzite | [blessing.json](https://github.com/tuna-os/wootc/blob/main/app/branding/bazzite/blessing.json) | not filed / pending / not agreed | +| Aurora | [blessing.json](https://github.com/tuna-os/wootc/blob/main/app/branding/aurora/blessing.json) | not filed / pending / not agreed | + +The records determine the scope of approval, not assumptions in outreach issues. +Asset provenance, shared organization membership, a successful build, previous +downloads or an unanswered invitation are not consent. + +## Partner-ready release prerequisites + +Issues [#594](https://github.com/tuna-os/wootc/issues/594), +[#592](https://github.com/tuna-os/wootc/issues/592) and +[#586](https://github.com/tuna-os/wootc/issues/586) use the same process for review. +A maintainer must own each request. A draft in this document does not authorize +or send a request. + +Before you claim approval for a branded download or arrange co-promotion: + +1. Name a wootc liaison. Ask the project's authorized brand/release owner whether + they want a review, through an existing permitted channel. + Verify the current venue with the project. + Historical URLs in `ask.venue` do not prove permission to post there. +2. Supply a packet for review tied to an exact release/commit. + Include the asset URL, checksums, actual filename and Windows signature/publisher status. + Include asset licenses, provenance and UI screenshots from that build. + Add image references/digests and the supported matrix for hardware/storage/channel. + Include real retained evidence of install → Linux login → Windows return → uninstall. + State known migration/recovery gaps; a link to a latest run that changes is not enough. +3. Ask the four questions about the brand separately. + Ask the image maintainer to review catalog defaults, hardware fit and preload/update assumptions. + Ask them to review the claimed behavior for file/Wi-Fi/profile migration. + Logo permission does not imply a review of compatibility. +4. Agree a review window with the reviewer. Two weeks is a proposal, not an + imposed deadline or automatic approval. Without a reply, the record stays undecided. +5. Record the authorized decision and durable public evidence for its exact + scope. A private answer is not permission to publish its contents. + Get confirmation that you may publish before you add public evidence. + Record winget namespace/publisher agreement separately from permission to ship an exe. +6. Name the distributor, the owner for signatures/releases, and the owner for support/escalation. + Get credentials to publish to winget through the repository's secret settings, never in an issue or this document. + A token is not brand permission. +7. Only then agree on optional PRs for upstream docs, download-page links, + announcement copy, dates and aggregate metrics. + Do not promise an upstream link or support commitment. + Use real reports with consent for case studies. + Download counts alone do not establish tries or successful migrations. + +**Enforcement gap:** `packaging/brands.sh` still includes brands that need approval +by default and warns in the log. Its existing `WOOTC_REQUIRE_BLESSING=1` mode +drops those brands. Release owners must use that mode for public distribution +that needs prior approval. The default workflow for releases does not enforce +prior approval. Both modes will exclude brands that have a refusal in their record. + +For each later release, the liaison and release owner must compare the approved +identity, catalog and claims against the new build. They must retain new +evidence of compatibility. Ask again when scope or upstream requirements +change; a previous yes is not perpetual permission for new claims. + +In the release evidence, the release owner records the tag, image digest, +evidence and unresolved issues from the review. Keep permission for the brand, +qualification of compatibility and approval for joint promotion distinct. ## What each project is asked @@ -48,8 +114,10 @@ Not a description — the actual thing: published branding: [`app/branding/README.md`](https://github.com/tuna-os/wootc/blob/main/app/branding/README.md) § Asset provenance. This answers "where did you get our logo" before it is asked. -3. **A live E2E video** of that image actually installing, migrating and - returning to Windows: [https://tuna-os.github.io/wootc/e2e/latest/](https://tuna-os.github.io/wootc/e2e/latest/). +3. **Retained E2E evidence** for the exact candidate build/image: installation, + migration, return to Windows and uninstall. The + [E2E index](https://tuna-os.github.io/wootc/e2e/latest/) is a discovery + link, not by itself proof for the candidate. 4. **The rendered winget manifests** for their namespace (below) — an offer, not a submission. @@ -65,10 +133,11 @@ they want: `winget.identifierAgreed`, and they can take it over at any time; - **no winget package** — the exe stays a direct download. -Only `TunaOS.wootc` is submitted automatically today -(`.github/workflows/winget-publish.yml`); no branded package is submitted -anywhere without a recorded yes. See -[`packaging/winget/README.md`](https://github.com/tuna-os/wootc/blob/main/packaging/winget/README.md). +The automatic submission workflow (`.github/workflows/winget-publish.yml`) uses +only the generic `TunaOS.wootc` identifier. Publication still needs the +maintainer's credentials, first-submission review and a successful workflow. +Do not submit a branded package without a separate agreement for its namespace +in the records. See [`packaging/winget/README.md`](https://github.com/tuna-os/wootc/blob/main/packaging/winget/README.md). Render a brand's manifests to show them exactly what would be published: @@ -83,37 +152,46 @@ the shape of the package. ## The request -Adapt per project; keep it short and make the "no" genuinely free. +**Draft, not sent.** Adapt per project; keep it short and make the "no" genuinely free. > **Subject:** May we ship a Bazzite-branded Windows installer? -> -> We build [wootc](https://github.com/tuna-os/wootc), an installer that puts -> a bootc image on a Windows machine from inside Windows — no USB, no -> repartitioning, and fully undoable. It already installs Bazzite, and we -> build a variant whose window says "Bazzite Installer" and wears your mark, -> type and colours, so users never see our project's name. -> -> We have not shipped that variant on your say-so and we are asking before -> it goes further. Four separate questions, and a no to any of them is + +> We build [wootc](https://github.com/tuna-os/wootc), early software to +> install a bootc Linux system beside Windows. It changes boot files and +> startup settings; some storage paths also change partitions. Windows return, +> migration and uninstall have limits documented in the attached evidence. +> We have built a variant whose window says "Bazzite Installer" and uses your +> mark, type and colours. Existing builds do not establish your approval. + +> We would like your review before any further approved distribution or +> co-promotion. Four separate questions, and a no to any of them is > completely fine: -> + > 1. May we use the Bazzite mark, colours and typeface in the installer? > 2. May we call it "Bazzite Installer"? > 3. May we use the tagline "``"? > 4. May we distribute an exe branded as Bazzite at all? -> -> Here is exactly what it looks like today: ``. -> Every asset and where we took it from: ``. A real install, -> start to finish, on video: ``. -> -> On winget: `Bazzite.Installer` belongs in your namespace, not ours. We -> have the manifests rendered and would rather hand them to you than publish -> under a name that isn't ours — attached/below. We are not submitting -> anything until you say so. -> -> If the answer is no to any of it, tell us and we will drop it — the -> branded exe comes out of our release matrix, which is a one-line change on -> our side. + +> Here is the exact candidate and its checksums: ``. +> Screenshots from that build: ``. +> Asset provenance and licenses: ``. +> Supported image references/digests, retained journey evidence and known +> limitations: ``. + +> Please also review image defaults and the migration claims. +> We will not treat permission to use your mark as a compatibility certification. + +> On winget: `Bazzite.Installer` belongs in your namespace, not ours. +> We have rendered the manifests — attached/below. We prefer to hand them to you, +> not publish under a name that isn't ours. We will not submit anything +> until you say so. + +> Would you like to review this? Would two weeks for feedback be useful? +> No response means no approval; we will leave the decision open. +> Please identify the authorized reviewer and a public decision location we may cite. + +> If the answer is no to any of it, tell us and we will drop it. +> We will remove the branded exe from our release matrix. ## Recording the answer diff --git a/docs/wootc/user-guide.md b/docs/wootc/user-guide.md index d43e65ab..0ee7fe65 100644 --- a/docs/wootc/user-guide.md +++ b/docs/wootc/user-guide.md @@ -1,5 +1,5 @@ --- -sidebar_position: 46 +sidebar_position: 48 title: "user guide" --- @@ -12,7 +12,11 @@ Windows remains the default boot choice during the native install path. The installer changes boot entries, boot files, and Windows power settings. Some storage choices also change partitions. Read the proposed plan before you continue. -This guide describes the current installer. See [current status](https://github.com/tuna-os/wootc/blob/main/docs/status.md) for the evidence and limits. +This guide describes **current source**, not a guarantee that the latest +published tag contains every feature. On 2026-11-02 the observed latest +non-prerelease remained `v0.1.0-alpha.1`; main has newer native setup packages. +Follow the [download guide](https://github.com/tuna-os/wootc/blob/main/docs/getting-started.md) for actual download names and +[current status](https://github.com/tuna-os/wootc/blob/main/docs/status.md) for evidence and limits. ## Contents @@ -32,9 +36,14 @@ This guide describes the current installer. See [current status](https://github. The app checks your PC at startup. Its current requirements include: - **Windows 10 or 11**, 64-bit, with UEFI firmware. -- **At least 35 GB of free space** on `C:` for the minimum plan. - Linux needs 20 GB. The app reserves another 15 GB for Windows. - You can choose a larger Linux disk if enough space is available. +- **Enough free space on an admitted storage volume.** The native plan needs a + Linux disk of at least 20 GB. It also needs image-dependent scratch space, + space for any offline image copy, and a safety reserve. The app reads the + reserve for the selected image and lowers the offered disk size to fit. + A blanket "35 GB is enough" is not valid for every current image or frontend. + + VM preparation has a separate conservative gate: 88 GiB of free space on the + host. See [managed VM](https://github.com/tuna-os/wootc/blob/main/docs/managed-vm.md). - **Secure Boot can remain on.** The installer checks whether your firmware trusts its Microsoft-signed loader before it changes boot configuration. It stops if it cannot confirm that trust. - **BitLocker off for the alpha install path.** The released alpha refuses an encrypted Windows drive. @@ -43,31 +52,59 @@ The app checks your PC at startup. Its current requirements include: You do not need a bootable USB for this path. +### Hardware warnings are not compatibility certificates + +Current source will check aliases for Linux PCI modules in a staged image before +disk or boot changes. A proven lack of an important PCI driver can stop the plan. +This refusal needs complete inventories from Windows and from one target kernel. +Nouveau-only graphics or firmware-framebuffer support gives a warning, not a +promise of an accelerated desktop. + +Missing declared firmware also warns: Windows cannot establish which Linux +firmware variant the device uses. USB PnP identifiers do not supply a complete +Linux modalias. Partial or unknown inventory gives a warning, not a fabricated +match. Without a local/preloaded image the assessment may be unknown. +Neither unknown nor warning means green. + +The installer shows each warning in its progress view; include them with a +compatibility report. + ## 2. Install Linux -Download the generic native setup `wootc-Installer-Setup.exe`, or the -distribution-specific setup package, and run it as Administrator. The setup -installs the WinUI shell and protected engine. `wootc-legacy.exe` is the -one-release Wails compatibility build; it needs WebView2 and is not the -primary installer. +Use an artifact present in the chosen release. The older published executable +for the generic build is `wootc.exe`. Current source uses native setup packages: +`wootc-Installer-Setup.exe` (or a distribution-specific setup). These install +the WinUI shell and protected engine. A native release may retain +`wootc-legacy.exe` for one release. + +The older Wails interface needs WebView2; the native shell does not. +These artifact generations are not interchangeable. ![Launchpad](https://raw.githubusercontent.com/tuna-os/wootc/main/docs/screenshots/01-launchpad.png) +*Historical Wails/mock illustration, not a screenshot of the RC/native package. +This guide asserts no RC SHA for the retained image.* + 1. **Pick a desktop.** The catalog has GNOME, KDE Plasma, Niri, and XFCE entries across several Linux bases. - The alpha offers only its supported subset, with Bluefin LTS as the default. - See the [release policy](https://github.com/tuna-os/wootc/blob/main/docs/RELEASING.md#alpha-now). + The selected brand and release channel determine the offered subset and + default; a branded build need not default to Bluefin. See the + [release policy](https://github.com/tuna-os/wootc/blob/main/docs/RELEASING.md#alpha-now). 2. **Set a password.** The app proposes your username, computer name, disk size, and encryption choice. Review them under **Advanced**. You can also change the Windows look option there. -3. **“Make it feel like Windows” defaults to on.** Review this option. - On supported Wayland desktops, the helpers transfer your wallpaper, accent, keyboard layout, and shortcuts. +3. **Review “Make it feel like Windows.”** Defaults differ between frontends; + do not assume the frontend selects this box. On supported Wayland desktops, the + helpers transfer your selected wallpaper, accent, keyboard layout, and shortcuts. Saved Wi-Fi networks use a separate path. 4. Click **Install**. The app creates the Linux disk file and stages boot files. It also configures a one-time boot into the deployer and disables Fast Startup and hibernation. ![Install progress](https://raw.githubusercontent.com/tuna-os/wootc/main/docs/screenshots/03-progress.png) +*Historical Wails/mock progress illustration; current native controls and RC +screenshots need their own retained evidence.* + Restart when you are ready. The one-time boot starts the deployer. Windows remains the default after that entry expires. A failed install can need recovery or cleanup. A one-time entry does not guarantee every failure returns safely. @@ -98,11 +135,16 @@ The helpers cover these categories: - **Files:** Documents, Desktop, Pictures, Downloads, Music, and Videos. A folder can initially share its Windows contents. Conversion makes a separate Linux copy. - **Browsers:** Firefox imports a complete profile, which can include saved passwords. - Chrome and Edge import bookmarks and history. Their Windows password stores need a separate sign-in path. + Chrome and Edge can import bookmarks and history. Their encrypted Windows + stores and login tokens have separate consent, keyring and service-specific + limits; see [session migration](https://github.com/tuna-os/wootc/blob/main/docs/session-migration.md). A copied or rewritten + database is not proof that the browser opens signed in. - **Steam:** a library bridge can use games in place, without another download. - **Office:** the helper copies your selected styles, dictionaries, and preferences for LibreOffice. - **Apps:** the dashboard lists apps from Windows and suggests alternatives for Linux. -- **WSL:** selected dotfiles and package lists can help rebuild your Linux tools. +- **WSL:** selected dotfiles and package lists can help rebuild tools, not clone + an entire WSL system or transfer its accounts. Follow the + [WSL migration guide](https://github.com/tuna-os/wootc/blob/main/docs/wsl-migration.md) and keep a separate export/backup. - **Wi-Fi:** the helper creates NetworkManager connections from saved networks. Enterprise networks can need a fresh sign-in. - **Windows look:** the helpers transfer your selected preferences and shortcuts on supported desktops. @@ -111,16 +153,73 @@ A category's presence does not prove every account or application will transfer. Check your files and application state on Linux before you remove any source data. Keep your own backup. Do not assume a repeat import will preserve your later edits. +### Existing Linux files and repeat imports + +Import is not permission to replace work already made on Linux. For standard +copies of external files, the helper will publish complete new files. +It will not overwrite an existing destination and will refuse unsafe +symlinks/special files. For Office templates, fonts, autocorrect and defaults, +the helper will preserve native content that differs. It will not count that +content as migrated. + +Dictionary append uses a recovery journal. It refuses if the state of an +unfinished append changes. Read each category's result. A selected category that fails, +partly completes or lacks verification makes external import return nonzero, +even if others completed. The GUI must show the item's error and the action +needed, not “All set.” + +A plan for desktop-look changes counts as partial until the helper applies it, +not as a completed preference import. + +Browser import uses safe source traversal and exclusive publication. +If the directory for Firefox import exists, the helper refuses a repeat copy to +preserve Linux edits. The helper does not rewrite existing Firefox `profiles.ini`. +A copied profile may need manual registration. That case reports failure/advice, +not a false complete result. + +Failed copies can retain private `.wootc-*.partial` directories for inspection. +Do not delete source data or assume a retry will overwrite/repair the target +automatically. + +The Steam bridge keeps an existing library VDF byte-for-byte. If Steam has not +registered the Windows library, use Steam's **Add Library** UI. The bridge does not +silently rewrite the configuration of native libraries. WSL dotfiles, `.ssh` +and Brewfile imports will also preserve bytes that differ from those at the source. +Manually merge the configuration/formulae you want; do not assume a retry +replaces them. + +Per-item `copied`, `alreadyPresent`, `preserved` and `failed` outcomes describe +what happened. None proves a live account has signed in. + +VS Code, Telegram, Signal, Thunderbird and OBS file/profile imports also +preserve existing destinations. They publish new files or complete new profiles +exclusively as the target user. The helper does not recursively take ownership +of unrelated native content. The helper creates metadata for Thunderbird only +inside its new bundle. + +Read per-app copied, preserved and failed outcomes in `bridge-apps.json`; +failed imports return nonzero. A copy of a messenger profile or a synthetic +fixture is not a verified login. It does not replace the app's own re-link +procedure. + ## 5. Try it first, commit later -The intended Phase 1 runs Linux inside Windows before native boot. -Current standard releases do not yet provide that complete journey. -The existing VM option needs a prepared Linux disk, QEMU, firmware, and an accelerator. -The main install path still uses the deployer after a reboot. +The RC needs Linux-inside-Windows first, as +[#596's Option A decision](https://github.com/tuna-os/wootc/issues/596#issuecomment-6514382140) +states. Current source can prepare a persistent VM disk with a selected Linux +account, then stop/start that disk through the managed QEMU/WHPX runtime. +It does not yet establish the complete desktop journey for consumers: +`desktopReady` remains false without independent guest evidence. -Do not treat “Boot in VM” as proof that no earlier reboot is necessary. -[ADR 0004](https://github.com/tuna-os/wootc/blob/main/docs/adr/0004-restore-vm-first-product.md) tracks the required VM-first path. -It must preserve your installed system and work when you later choose native boot. +Use only a matching signed runtime and an explicitly admitted image. +See [managed VM requirements and lifecycle](https://github.com/tuna-os/wootc/blob/main/docs/managed-vm.md) before you try it. +A helper receipt or QEMU process is not proof of graphical login, persistence, +or native promotion. Current promotion of a managed disk can try to export +verified boot inputs through read-only access. It still reports **not armed**. + +It does not silently redeploy, discard the existing system or write BCD/ESP. +[ADR 0004](https://github.com/tuna-os/wootc/blob/main/docs/adr/0004-restore-vm-first-product.md) needs the same installed +system and data to survive eventual native boot; that positive gate remains open. ## 6. Import from another disk or a backup @@ -153,11 +252,16 @@ It needs the key to show your Windows folders until you convert them to Linux fo The installer writes a copy to the installer folder, which only administrators can read. The Linux installer moves that copy into the Linux disk and erases the copy on the Windows side. -At the first Linux start, Linux seals the copy to this PC with its TPM. -A PC with no TPM uses a key that it keeps on the PC. -A copy of the Linux disk cannot open your Windows drive on a different PC. -When you convert the last Windows folder, Linux erases the key. -If you delete your Linux data when you uninstall, the uninstaller erases the key too. +The TPM path tries to seal the copy to this PC. On a TPM machine, it refuses +a downgrade to default PCRs. It keeps root-only plaintext for a retry and does +not claim that the weaker seal met the requirement. + +Only without a usable TPM can the host-only fallback keep a local key for the +seal beside the encrypted recovery key. That fallback does **not** protect +against an attacker who can read the entire Linux disk without encryption. +The helpers try to erase the retained key after conversion of the last linked +Windows folder or deletion of the Linux disk. Deletion does not prove that no +storage remnants or backups remain. If the sealed copy fails, for example after a TPM clear, Linux writes a message to the system log. Your Windows folders stay on the Windows drive. @@ -165,8 +269,11 @@ To show them again, save your recovery key as `/etc/wootc/bitlocker-key`, readab Linux disk encryption is a separate choice: -- **TPM auto-unlock:** LUKS uses your PC's TPM to unlock the Linux disk at boot. -- **Passphrase:** you enter a password at boot. +- **TPM auto-unlock:** a planned LUKS/TPM path; current install admission refuses + `tpm2-luks` until it meets all safety gates. A UI default or option does not + prove that encryption works. +- **Passphrase:** Linux disk encryption that needs a password at boot; + verify qualification of the selected image/path. - **None:** anyone with access to the disk can read its contents. **One-time MOK enrollment.** Some distributions sign their kernel or drivers with their own key. @@ -196,8 +303,10 @@ Keep both systems until you have verified your work and a separate backup. ## 9. Uninstall -Open **Settings → Apps → Installed apps** and choose **TunaOS (wootc)**. -You can also open the installed **TunaOS (wootc)** app as Administrator and choose **Uninstall** on the Manage screen. +Open **Settings → Apps → Installed apps** and find the matching product. +The older generic build registers **TunaOS (wootc)**; branded/native setup +names follow their package identity. Check their appearance in the real Settings UI. +Open that app and choose **Uninstall** on Manage for the engine's data choices. The uninstaller tries to: @@ -205,11 +314,30 @@ The uninstaller tries to: - Remove installer files. - Restore the recorded Fast Startup and hibernation settings. -It keeps `root.disk` by default. -Select **Also delete my Linux data** only if you want to remove that disk file and its contents. +It keeps `root.disk` by default. Default cleanup removes known installer +subtrees and only empty disk/root directories. Unfamiliar saved data and VM +metadata remain even when a known root-disk filename is absent. + +Select **Also delete my Linux data** only to delete the product tree recursively, +including retained product data. This is more than app removal. A dedicated volume needs additional ownership and content checks before the app offers to return its space to Windows. If ownership or contents remain uncertain, the app preserves the partition and gives a reason. +Current-source cleanup must confirm BCD rollback before it removes recovery +tasks, EFI files or state. Boot cleanup, file removal, secret sanitization or +restoration of power settings can fail. Cleanup then reports the error and +retains recovery/retry authority where possible. A request for deletion does +not mean complete cleanup. + +A corrupt/unreadable journal or orphaned armed/deployer marker means +**needs repair**, not “no installation.” Removal keeps the Linux disk unless +you explicitly choose otherwise. + +The Add/Remove registry entry must carry the engine's ownership marker before +reuse or removal. The engine refuses an unmarked or foreign same-name entry; +it does not adopt that entry automatically. Do not delete its marker or state +to bypass refusal. + An incomplete cleanup can leave files or boot state behind. Read any reported errors before you retry. Uninstall does not undo work that you made on a graduated native disk. @@ -236,12 +364,44 @@ Uninstall does not undo work that you made on a graduated native disk. - **Setup stopped before it finished:** open wootc again. It shows how the last install ended (cancelled, closed, or failed) and the last step that finished. **Continue setup** keeps the checked part of the download and asks for your password again. - If setup stopped during a change to the startup files, wootc offers **Remove** only. - Remove the installation, then install again. + + If setup stopped during startup-file changes, it offers repair/removal guidance. + It also offers that guidance for a damaged or ambiguous journal/marker. + It does not assume there is no installation. + Removal will retain Linux data by default. + Inspect reported errors before you try another install. To see the same result in a terminal, run `wootc.exe recover --classify`. - **Windows asks to scan a drive:** a power cut or forced shutdown can leave it unclean. Complete the Windows check and inspect its result. Do not assume every file survived a failed shutdown. +For support, retain the exact release/build SHA, frontend, selected image, +`C:\wootc\state.json` (or the selected drive's install root) and relevant +`logs\` / `install\` evidence. Review it before you share it: logs and profile paths +can contain personal data. Never attach passwords, recovery keys, cookies, +session envelopes or a complete browser profile to a public issue. + +Current-source engine diagnostics include JSON lines on **stderr** with +`timestamp`, `attemptId`, stable `phase`, `event`, `duration_ms` and optional +`error_code`. Events are `phase_start`, `phase_complete`, `phase_error` and +`phase_cancelled`; error codes are coarse `operation_failed` / `cancelled`, +not raw failure text. The protected journal will retain errors for diagnosis. +Do not mix stderr diagnostics into stdout for stdio JSON-RPC. + +For a Windows profile mapping, review the complete account plan and edit it +before you continue. Secondary generated names use `user1`, `user2`, and so on. +A collision with your selected primary name is not permission to drop a profile. +The engine refuses duplicate, invalid or reserved Linux names. +The reviewed set of Windows profiles must still match what the engine discovers. + +The legacy installer refuses if it cannot establish the original interactive user. +It also refuses if alternate-admin elevation changes that identity. +Environment hints are not authority to collect another user's secrets. + +If a copy of Documents from encrypted Windows fails, the bridge preserves an +existing Documents directory on Linux. It does not hide native files behind a +read-only Windows bind. Inspect the logged source path and use it for manual +recovery; a fallback is not proof that the copy succeeded. Keep the Windows source. + wootc remains early software. The tests cover some scenarios for native installation in VMs. It does not establish complete VM-first use or real-hardware acceptance. See the [status](https://github.com/tuna-os/wootc/blob/main/docs/status.md), [verification ladder](https://github.com/tuna-os/wootc/blob/main/docs/milestones.md), and [roadmap](https://github.com/tuna-os/wootc/blob/main/ROADMAP.md). diff --git a/docs/wootc/vhdx-exploration.md b/docs/wootc/vhdx-exploration.md index 776964fb..8826e431 100644 --- a/docs/wootc/vhdx-exploration.md +++ b/docs/wootc/vhdx-exploration.md @@ -1,5 +1,5 @@ --- -sidebar_position: 47 +sidebar_position: 49 title: "vhdx exploration" --- diff --git a/docs/wootc/windows-state-trust.md b/docs/wootc/windows-state-trust.md index a20003b2..0f3ba8f5 100644 --- a/docs/wootc/windows-state-trust.md +++ b/docs/wootc/windows-state-trust.md @@ -1,5 +1,5 @@ --- -sidebar_position: 48 +sidebar_position: 50 title: "windows state trust" --- @@ -43,6 +43,39 @@ the app executable are also not evidence. Discovery uses generated lifecycle, power, root-disk, boot and recovery records. ESP files and dedicated volumes can also show that installation began. +## Recovery and ownership authority — current-source update, 2026-11-02 + +Unreadable/corrupt install journals and orphaned armed/deployer markers fail +closed as **needs repair**. They are not evidence that no installation exists. + +Removal keeps the Linux disk by default. Current uninstall must observe BCD +rollback before it removes recovery tasks, EFI files and installer state. +It captures errors from recursive removal; an issued command does not prove cleanup. +If secret overwrite/sync fails, uninstall refuses to unlink the unsanitized secret. +It retains a visible failure and does not claim sanitization passed. + +The installer durably writes prior Fast Startup/hibernation state to the power-state +file and a registry mirror that it owns **before** it disables those settings. +Restore must observe its result and retain retry authority if it fails. +Only `WootcOwner=wootc-install-v1` establishes ownership of the Add/Remove key. +The installer refuses to change or remove an unmarked or foreign key with the same name. +There is no ownership-adoption shim. + +Recovery-password preparation validates all eight groups/checksums and retains +canonical hyphens, without the secret in errors. +Linux must make the sealed file and directory durable before it destroys plaintext. +A host-only seal keeps a local key on the disk. +It therefore does **not** protect against an attacker who can read the entire unencrypted image of the disk. +On a TPM machine, the seal path refuses a default-PCR downgrade and retains root-only plaintext for retry. + +Host-only fallback applies only without a usable TPM. +Default uninstall removes known installer subtrees and only empty disk/root directories. +It will preserve the unfamiliar saved data and the VM metadata, even when a known root disk is absent. +Explicit Linux-data deletion keeps its recursive product-tree scope; partition removal still needs its receipt. +These are source contracts, not newly observed BCD, firmware, sanitization or +power-restoration acceptance. The hardware/RC failure and retry matrix remains +required. + ## Native tests Run these commands from an elevated Windows checkout: diff --git a/docs/wootc/winui-shell.md b/docs/wootc/winui-shell.md index a099a71d..71dc6c28 100644 --- a/docs/wootc/winui-shell.md +++ b/docs/wootc/winui-shell.md @@ -1,21 +1,23 @@ --- -sidebar_position: 49 +sidebar_position: 51 title: "winui shell" --- WinUI 3 remains the chosen Windows UI. Linux keeps GTK4/libadwaita. -The existing consumer installer stays the default until native proof passes. -This revision corrects the transport and identity assumptions in the earlier design. +Main now contains native setup packaging; that does not prove a native release +has shipped or passed its release gates. The latest non-prerelease inspected +on 2026-11-02 was `v0.1.0-alpha.1`, with the older Wails executables. +See [getting started](https://github.com/tuna-os/wootc/blob/main/docs/getting-started.md) for the download distinction. -## Current source, 2026-09-27 +## Source and evidence boundaries, 2026-11-02 | Phase | Actual state | Remaining work | |---|---|---| -| A: engine protocol | Go stdio RPC and DTO generator exist; legacy disconnect and console controls pass | Native operation authorization and the full consumer journey remain open | +| A: engine protocol | Go stdio RPC, generated DTOs, authenticated native sessions and one-shot operation grants exist | Full native acceptance is separate from protocol/component tests | | B: scaffold (#343) | Native projects, authenticated assessment RPC, startup UI tests, and five branded preview packages pass hosted component checks. Each installed package shows its palette and logo and refuses Windows builds before 17763. Windows policy refuses elevation for a standard user, and the shell keeps the branded assessment and the retry ([run 38776425860](https://github.com/tuna-os/wootc/actions/runs/38776425860)) | Interactive UAC consent on the secure desktop, proof on build 17763, and preview release assets (#608). The native E2E now installs the real preview installer in the guest ([run 38888315334](https://github.com/tuna-os/wootc/actions/runs/38888315334)) | | C: experience (#344) | A read-only startup view, a configuration form, a route for an interrupted install, an install route that needs an engine grant and a confirmation, progress and done views fed by that install session, manage and recovery views whose uninstall and boot repair need their own engine grant in an install session, Linux window views whose VM actions each need an engine grant, UI Automation controls, a screen gallery, and an E2E drive mode (`WOOTC_E2E_DRIVE=1`) that operates these views exist. The GUI E2E can install the native shell in the guest and drive it (`WOOTC_E2E_GUI_FRONTEND=native`, see [Native shell E2E](#native-shell-e2e)). [Run 38857241312](https://github.com/tuna-os/wootc/actions/runs/38857241312) drove a full Windows, deployer, Linux and Windows cycle through it | Consumer screens, VM and migration flows, interactive UAC consent, accessibility, persistence, and the full journey. An unelevated shell with an elevated install engine, installed by the real preview installer, drove a full cycle ([run 38923119161](https://github.com/tuna-os/wootc/actions/runs/38923119161)) | -| D: release (#345) | Not started | Native default only after C; retain a legacy artifact for one release | -| E: removal (#346) | Not started | Remove Wails/web frontend only after a clean native release and docs audit | +| D: release (#345) | Issue closed 2026-10-31; source builds branded Inno native setup as the primary artifact and retains one legacy artifact | A workflow/package definition is not a clean published native release; inspect retained build, install and removal evidence | +| E: removal (#346) | Wails remains in the source | Remove it only after a clean native release; closing D alone is not that proof | This preview candidate retains [run 36328543336](https://github.com/tuna-os/wootc/actions/runs/36328543336). It tested merge `68e6f452` from head `7aee354`. @@ -27,7 +29,8 @@ The tests used the same elevated user. They do not prove interactive UAC or inst The UAC refusal test uses `ConsentPromptBehaviorUser=0` for a disposable standard user. Windows then returns `ERROR_ACCESS_DISABLED_BY_POLICY`, not the `ERROR_CANCELLED` of a No click. The shell shows both as a refusal. A No click on the secure desktop has no hosted test. -The current Wails installer and release assets remain the default. +The older Wails assets remain the observed latest non-prerelease download; +main's native release packaging is a separate source fact. The future preview and results follow the [migration extension plan](https://github.com/tuna-os/wootc/blob/main/docs/specs/migration-extensions.md). Those APIs do not exist in `serve` yet. Phase 1 must run Linux inside Windows before native promotion. @@ -43,10 +46,11 @@ Existing method names and DTO shapes remain stable unless a versioned change rep Generate C# DTOs from Go and retain protocol goldens. Keep `wootc.exe install`, `status`, `uninstall`, `recover`, and stdio `serve` -for headless tools and tests. The native GUI needs a separate transport adapter. -A transport adapter must not add a second implementation of install logic. +for headless tools and tests. The native GUI uses the authenticated named-pipe +transport and session-scoped authorization described below, not an elevated +stdio child. Transport adapters must not duplicate install logic. -Proposed layout: +Source layout: ```text shell/ @@ -58,22 +62,26 @@ shell/ Drive/ E2E directives through view-model actions Wootc.Shell.Core/ testable state and protocol logic without WinUI Wootc.Shell.Tests/ unit/contract tests, including Linux CI - Wootc.Shell.UiTest/ Windows UI Automation and screenshot evidence + Wootc.Shell.UiTests/ Windows UI Automation and screenshot evidence ``` ## Build dependency and OS evidence -On 2026-09-27, Microsoft identifies **2.5.1** as the stable version of -Windows App SDK. The [download page](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/downloads) -and [package page](https://www.nuget.org/packages/Microsoft.WindowsAppSDK/2.5.1) -show that version. The preview pins that package and .NET SDK 8.0.425. -The hosted run above restored, built, and tested that combination. -It does not prove the minimum OS in the manifest. +The source pins the Windows App SDK in the `Microsoft.WindowsAppSDK` +package reference of +[`Wootc.Shell.csproj`](https://github.com/tuna-os/wootc/blob/main/shell/Wootc.Shell/Wootc.Shell.csproj), and the +.NET SDK in `sdk.version` of [`global.json`](https://github.com/tuna-os/wootc/blob/main/shell/global.json), with +roll-forward disabled. Renovate updates both pins, so this page does not copy +the numbers. Install the exact .NET SDK that `global.json` names to reproduce +the build; another SDK version fails. The application still +targets `net8.0-windows10.0.19041.0`; SDK and target framework are different. +Older hosted runs on this page used earlier pins and do not certify the new +combination or the minimum OS. The [SDK support contract](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/support) includes backward compatibility to Windows 10 1809, build 17763. That does not prove wootc works on that OS. -The requested `net8.0-windows10.0.19041` compile target and the minimum runtime +The `net8.0-windows10.0.19041.0` compile target and the minimum runtime OS are separate settings. Review `TargetPlatformMinVersion` and `SupportedOSPlatformVersion`, then test the actual native package on the claimed minimum OS before the user guide adopts that floor. @@ -90,7 +98,7 @@ redirection needs `UseShellExecute=false`. See [Microsoft's process contract](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.processstartinfo.useshellexecute) and [shell launch verbs](https://learn.microsoft.com/en-us/windows/win32/shell/launch). -Proposed native transport: +The native transport follows this contract: 1. Start the shell without elevation. Show local brand assets and read-only assessment. 2. Request UAC only for an operation that needs it. Launch the engine from its trusted absolute path with `runas`. @@ -116,10 +124,11 @@ These checks need native Windows tests before the transport becomes a release pa ## Preserve the original person's identity -The old design claimed a fix for alternate-admin UAC through explicit profile fields. -The current `InstallConfig` has no verified source-user contract. -Several collectors still read `HKCU` or `USERPROFILE` in the elevated process. -A supplied path or username is not proof of ownership. +The native transport captures and revalidates the original user's token. +Profile collection must use that authority, not a caller's path or username. +The legacy installer now refuses when interactive +identity is unavailable or differs after elevation. `USERPROFILE` or +`WOOTC_*` hints are not an alternate-admin fallback. Keep user-specific collection in the original unelevated session where possible. Bind exports to the source SID, profile identity, session, plan, and consent. @@ -189,11 +198,11 @@ Target 1366×768 and low-memory machines as explicit test cohorts. ## Packaging and offline proof -Phase D makes the native shell setup the primary release artifact. The workflow -publishes each eligible brand as `-Installer-Setup.exe` through the -Inno wrapper. The generic package is `wootc-Installer-Setup.exe`. -For this release only, `release.yml` keeps one Wails download: -`wootc-legacy.exe`. +Phase D's **source workflow** makes native shell setup the primary artifact: +each eligible brand builds `-Installer-Setup.exe` through the Inno +wrapper; the generic name is `wootc-Installer-Setup.exe`. The first native +release also retains `wootc-legacy.exe` as a Wails download. These names +describe packages on main, not assets present in `v0.1.0-alpha.1`. Keep the Go engine beside the shell and retain the standalone headless asset. The native package embeds the public key for release verification. The package @@ -224,9 +233,34 @@ Do not infer it only from the minimum for Windows App SDK. Test Windows 10 and 11 before a change to the product requirements. MSIX still needs a proven distribution path. Code signatures need one too. -winget now consumes the Inno setup manifest. +The checked-in winget manifest targets Inno setup; package review/publication +is a separate prerequisite, not proof that `winget install` works today. A native UI does not remove SmartScreen or code-signature requirements. +In production, the native engine will use the exact shim bytes from the release for Secure Boot provenance. +It also uses the key that signed them and the matching source commit. +It uses `shell/packaging/release-metadata.py`, not an empty/handwritten authority list. +The package Publisher uses `packaging/brand.py`'s effective identity (including +unapproved-brand distributor identity); installed-package checks retain +`publisher-observations.json`. Component fixtures and package assertions still +do not prove firmware trust or how Apps appears on a fresh machine. + +The native plan displays the complete Windows-directory → editable Linux-user +map and warnings. An edit discards an earlier grant and needs a new check. +Final confirmation repeats the map that the engine granted. +The UI no longer offers unsupported TPM encryption for root; the native default is `none`. +Hardware warnings remain visible during progress and on Done. + +The dedicated `native-proof / native-shell GUI acceptance` E2E job will record +observations from UI Automation/CopyFromScreen before the confirmation button. +It independently compares displayed boot evidence with Linux QGA and the +current Windows boot identity. It retains +`native-gui-soak-proof--` and +`native-shell-build--` artifacts. + +This source verification path does **not** prove a new native cycle passed. +It does not qualify an RC or start or complete a thirty-day soak. + ## Screen gallery The gallery is a separate build of the shell (`-p:NativeGallery=true`). @@ -374,6 +408,94 @@ Retain the legacy build until a native release passes its gates, before phase E ## Current stdio protocol reference +### Purpose, launch and connection + +`wootc.exe serve` is a headless adapter to the same Go engine used by the +installer. It is a child-process **stdin/stdout** protocol, not an HTTP server: +there is no TCP port, URL, REST endpoint, or listener option. It does not open +the GUI. `serve` defines no command-specific flags; additional arguments are +not a supported configuration API. Use a trusted matching engine build. + +For a read-only protocol probe in PowerShell: + +```powershell +$requests = @( + '{"jsonrpc":"2.0","id":1,"method":"GetStatus"}' + '{"jsonrpc":"2.0","id":2,"method":"Shutdown"}' +) +$requests | & .\wootc.exe serve 2> .\serve-stderr.log +``` + +Use the engine executable's actual path/name if your package calls it +`wootc-engine.exe`. The child must inherit or have explicitly redirected +stdin/stdout; drain stdout and stderr independently. Do not use `runas` +with redirected standard streams. The consumer native shell uses the +authenticated named-pipe launcher, identity handshake, and configuration or +install sessions instead. A random pipe name, a supplied username, or a +successful stdio probe does not authorize a native session. + +**Safety:** stdio is a trusted automation interface, not an untrusted local +service. `StartInstall`, reboot, uninstall, defrag and VM actions can change the +machine. Elevation, protected state and all engine preconditions still apply. +Do not use examples that change the machine on a development workstation. + +### Framing, responses and lifetime + +- Write one JSON object per line as UTF-8. End each line with LF; the reader also accepts CRLF. + The reader will ignore blank lines. It does not support batches for JSON-RPC or `Content-Length`. + The current reader limit is 10 MiB per line; use small requests. +- Request envelope: + `{"jsonrpc":"2.0","id":1,"method":"GetStatus","params":null}`. + Method names are case-sensitive. Use a unique string or integer `id`. + Omit `params` for parameterless methods. Native read methods reject any + non-null params, even `{}`. +- Success: `{"jsonrpc":"2.0","id":1,"result":...}`. + Void methods return `result:null`. Errors have `error` instead of `result`: + `{"jsonrpc":"2.0","id":1,"error":{"code":-32601,"message":"..."}}`. + `error.data` is optional; configuration errors can carry diagnostic data. +- This adapter responds with `id:null` when the request has no `id`; do not + rely on JSON-RPC client-notification silence. Malformed JSON uses `id:null`. + Legacy calls will generally accept a property that they do not recognize in a JSON object. + Native plan and confirmation decoders are deliberately stricter. +- `-32700`: JSON decode failed. +- `-32600`: missing/wrong `"2.0"` or empty method. +- `-32601`: unknown method or unavailable in this session. +- `-32602`: malformed params. +- `-32603`: engine failure, policy refusal, changed observations, or unavailable capability. + Treat messages as display text, not stable machine-readable codes. + An error is not a success receipt. +- Dispatch is sequential, but workers for installs and VMs can emit events asynchronously. + Responses and events can alternate. Route responses by `id` and events + by `method`, never by line position. +- `StartInstall`/`PrepareVM` acceptance does not mean work finished. Read + `GetStatus` or VM state and events. `CancelInstall` requests cancellation; + `null` does not prove cleanup has completed. +- `Shutdown` responds with `null` and ends the loop; EOF also ends it. + When the transport closes, the engine shuts down VMs and cancels/cleans up installs. + The engine waits for safe cleanup; its 30-second install warning is **not** a + deadline after which it kills the worker. Drain stderr until process exit. + + Exit 0 means the loop in the server ended normally. It does not mean an install succeeded. + A reader error returns exit 1. + +### Session availability + +The method list below is a union, not a promise that every transport accepts +every method: + +| Session | Allowed surface | +|---|---| +| Legacy stdio `serve` | Legacy methods below; native configuration, grants, maintenance, `InspectBoot` and native VM methods are unavailable | +| Native assessment | `GetStatus`, `GetLastRun`, `GetRecoveryVerdict`, `GetInstallRecovery`; a configuration-capable session additionally permits `GetNativeConfiguration`, `GetNativeInstallSpace` and the three E2E drive methods | +| Native install-purpose | `GetStatus`, `CancelInstall`, `Shutdown`, grants/confirmations for install, maintenance and VM, plus `GetUninstallInfo`, `InspectBoot`, `GetNativeVMStatus`; `Reboot` only after this session's own successful completed install | + +The trusted transport selects these capabilities. A field in JSON cannot +upgrade an assessment session. E2E drive calls remain inert unless the **engine's** +environment enables `WOOTC_E2E_DRIVE=1`; this is a test facility, not a +consumer automation API. + +### Methods + | Method | Params | Result | |---|---|---| | `GetSupportPolicy` | — | `SupportPolicy` | @@ -384,7 +506,7 @@ Retain the legacy build until a native release passes its gates, before phase E | `GetInstallSteps` | — | `[]StepDefinition` | | `GetNativeConfiguration` | — | `NativeConfigurationSnapshot` | | `GetNativeInstallSpace` | image and drive of the last configuration read | `InstallSpace` (configuration session only; the space the image needs beside its disk) | -| `GetSessionCandidates` | — | as today | +| `GetSessionCandidates` | — | `[]SessionCandidate` (detection/consent choices, no token material) | | `StartInstall` | `InstallConfig` | `null` or error | | `PrepareNativeInstall` | `InstallConfig` | `NativeInstallGrant` (install session only; one plan for each session) | | `ConfirmNativeInstall` | intent confirmation | `null` or error (install session only; the first attempt uses the intent) | @@ -408,18 +530,134 @@ Retain the legacy build until a native release passes its gates, before phase E | `E2EDriveDirective` | — | `string` (empty unless the engine runs with `WOOTC_E2E_DRIVE=1`; native shell: configuration session only) | | `E2EDriveReport` | `string` | `null` (written only when bound to the current directive; native shell: configuration session only) | | `E2EDriveReady` | `string` | `null` (first-render marker, bound to no directive; native shell: configuration session only) | -| `GetVMCapability` | — | `VMCapability` | Signed runtime and persistent disk availability. | -| `GetFreshVMCapability` | — | `VMCapability` | Signed runtime and helper availability. | -| `GetVMState` | — | `VMState` | Durable disk lifecycle; desktop readiness requires independent evidence. | -| `TryInVMFresh` | image string | — | Legacy call refuses preparation without account details. | -| `InstallVMRuntime` | — | — | Acquire the signed runtime for this release; no native fallback or existing-runtime replacement. | -| `PrepareVM` | `VMInstallConfig` | — | Prepare a persistent system with its Linux account, then launch its VM. | -| `BootInVM` | — | — | Restart the same verified, stopped VM disk. | -| `StopVM` | — | — | Request guest shutdown; preserve ownership until actual exit. | -| `ForceStopVM` | — | — | Explicit forced stop; disk requires recovery before reuse. | -| `Shutdown` | — | `null` (engine exits 0) | +| `GetVMCapability` | — | `VMCapability` (signed runtime and persistent disk availability) | +| `GetFreshVMCapability` | — | `VMCapability` (signed runtime and helper availability) | +| `GetVMState` | — | `VMState` (disk lifecycle, not desktop proof) | +| `TryInVMFresh` | image string | `null` or error; refuses preparation without account details | +| `InstallVMRuntime` | — | `null` or error; acquire this release's signed runtime, no replacement of an existing runtime | +| `PrepareVM` | `VMInstallConfig` | `null` or error; prepare the persistent account/disk, then launch | +| `BootInVM` | — | `null` or error; restart the verified stopped disk | +| `StopVM` | — | `null` or error; request guest shutdown, retain ownership until actual exit | +| `ForceStopVM` | — | `null` or error; forced stop requires recovery before reuse | +| `Shutdown` | — | `null`; stop the loop, then complete cleanup | Notifications use `install:progress` and `vm:progress`. The native shell uses the versioned VM contract (`NativeVMStatus`, `NativeVMPlan` and `NativeVMGrant`) in an install session. Each VM action that changes state needs its own engine grant, and each grant is used once. The legacy VM methods stay for the legacy app. + +### Parameter schemas + +Use JSON field names, not Go/C# property names. Integers must be JSON numbers, +booleans JSON booleans, and passwords strings. Never log request payloads. + +| Type/call | JSON object fields and constraints | +|---|---| +| `InstallConfig` / `StartInstall` | `imageRef:string`, `diskSizeGB:integer`, `username:string`, `password:string`, `hostname:string`, `bootloader:string` (`auto`, `grub2`, `systemd-boot`), `composeFs:boolean`, `storageDrive:string` (letter without colon; legacy empty means C), `encryption:string` (`none`, `luks-passphrase`, or currently refused `tpm2-luks`), `luksPassphrase:string`, `windowsLook:boolean`; optional `sessionConsent:object` is per-app opt-in, optional `profileAccounts:array` is the reviewed complete mapping, optional `faultInject:string` is a test-only boundary | +| `PrepareNativeInstall` | Same install object **except** `sessionConsent` and `faultInject` are forbidden. Object only, at most 16 KiB; unknown/duplicate/null fields refused. Nonempty image, username, password and storage drive and positive disk size required. Admission further checks policy, image and physical storage observations | +| `ProfileAccount` | `{"windowsDir":"","linuxUser":""}`; only Linux account names are editable, all discovered profiles must remain represented, and duplicates/invalid/reserved names refuse | +| `GetNativeInstallSpace` | `{"imageRef":"","storageDrive":"C"}`; must name one admitted image/drive from the last configuration read | +| `UninstallOptions` | `{"deleteRootDisk":false,"removePartition":false}`; destructive choices remain subject to engine ownership and safety checks | +| `NativeMaintenancePlan` | `action:string`: `uninstall`, `repair-boot`, `restore-windows-boot`, `try-again`, or `boot-linux`; `deleteRootDisk:boolean`, `removePartition:boolean` apply only to uninstall | +| `VMInstallConfig` / `PrepareVM` | `{"imageRef":"","username":"","password":""}`; no implied encryption, Windows-look or session-migration options | +| `NativeVMPlan` | `action:string`: `install-runtime`, `prepare`, `boot`, `stop`, `force-stop`; only `prepare` includes `imageRef:string`, `username:string`, `password:string` | +| `TryInVMFresh`, `E2EDriveReport`, `E2EDriveReady` | String params; report/ready accept serialized report text, not an arbitrary JSON report object | + +Legacy object parameters also accept `[object]`, using only the first element. +Legacy string params accept a string, `[string]`, or `{"state":"..."}` / +`{"report":"..."}`. New clients should send the direct object or string; +native plan/confirmation contracts do **not** accept positional arrays. + +The native install grant returns `schemaVersion`, `session`, `brandId`, +`intentId`, admitted `imageRef`, `storageDrive`, `diskSizeGB`, `encryption`, +`bitLockerOn`, `bitLockerRecoveryKeyWarning`, `fastStartupOn`, and +`secureBootChainWarning`, `profileAccounts` and `profileWarnings`. Display the +engine's grant and mapping before confirmation; do not manufacture a grant +from the form. Confirmation is: + +```json +{"jsonrpc":"2.0","id":12,"method":"ConfirmNativeInstall","params":{"kind":"confirm-install","protocolVersion":1,"session":"","brandId":"","intentId":""}} +``` + +Maintenance/VM confirmations have the same fields that bind the grant, plus the granted +`action`. They use `kind:"confirm-maintenance"` / `"confirm-vm"` and their +respective method names. The engine issues session and intent IDs as lowercase +hex strings of 32 characters. The decoder needs every confirmation field. +It refuses unknown/duplicate fields and limits confirmations to 4096 bytes. +The first try consumes its intent even if the engine refuses it. + +Install/maintenance preparation is one-shot per session, including a failed +prepare; a changed plan needs a new session. Each VM action needs a fresh +grant; a new VM prepare replaces an unconfirmed grant. +The engine checks its observations and the original user's identity again before mutation. + +### Results, schemas and event payloads + +The complete wire schema is the Go structs' **`json` tags**, with corresponding +`JsonPropertyName` attributes in the generated +[`Dto.cs`](https://github.com/tuna-os/wootc/blob/main/shell/Wootc.Shell/Engine/Dto.cs). `omitempty` fields may be absent; +do not interpret omission as proof of success. Go pointers can be `null`; +nil slices not explicitly normalized by a method can also be `null`. +`GetImages` and `GetSessionCandidates` explicitly normalize to `[]`. + +This map covers every result and nested schema used by the methods above: + +| Contract | Canonical definition / example | +|---|---| +| `SupportPolicy`, `SystemInfo`, `DataPartition`, `Branding`, `UninstallInfo`, `UninstallOptions` | [`app.go`](https://github.com/tuna-os/wootc/blob/main/app/app.go), [golden DTO JSON](https://github.com/tuna-os/wootc/blob/main/app/testdata/dto) | +| `ReleaseNotice` (`version:string`, `url:string`; no notice has both strings empty) | [`release_notice.go`](https://github.com/tuna-os/wootc/blob/main/app/release_notice.go) | +| `Image`, `InstallConfig`, `InstallStatus`, `ProgressEvent`, `ProfileAccount` | [`install_contract.go`](https://github.com/tuna-os/wootc/blob/main/app/install_contract.go), [`profiles.go`](https://github.com/tuna-os/wootc/blob/main/app/profiles.go), [golden DTO JSON](https://github.com/tuna-os/wootc/blob/main/app/testdata/dto) | +| `StepDefinition` (`id`, `owner`, `label`, all strings) | [`steps_gen.go`](https://github.com/tuna-os/wootc/blob/main/app/steps_gen.go); generated phase vocabulary, not prose matching | +| `SessionCandidate` (`app`, `kind`, `portable`, `recommend`, `note`, `consentRequired`) | [`session.go`](https://github.com/tuna-os/wootc/blob/main/app/session.go), [candidate example](https://github.com/tuna-os/wootc/blob/main/app/testdata/dto/session_candidate.json) | +| `NativeConfigurationSnapshot`, image/default/bundle/storage records | [`native_configuration.go`](https://github.com/tuna-os/wootc/blob/main/app/native_configuration.go), [configuration fixture](https://github.com/tuna-os/wootc/blob/main/tests/unit/fixtures/native-gallery/configuration.json) | +| `InstallSpace` (`imageRef`, `compressedBytes`, `sizeSource`, `scratchGiB`, `bundleGiB`, `reserveGiB`) | [`install_space.go`](https://github.com/tuna-os/wootc/blob/main/app/install_space.go); reserve is space **beside** the Linux disk | +| `NativeInstallGrant` | [`native_install_session.go`](https://github.com/tuna-os/wootc/blob/main/app/native_install_session.go) | +| `NativeMaintenancePlan`, `NativeMaintenanceGrant` | [`native_maintenance.go`](https://github.com/tuna-os/wootc/blob/main/app/native_maintenance.go), [maintenance exchanges](https://github.com/tuna-os/wootc/blob/main/tests/unit/fixtures/native-maintenance/responses.ndjson) | +| `BootRepairReport` | [`boot_repair.go`](https://github.com/tuna-os/wootc/blob/main/app/boot_repair.go); observation includes saved evidence, not repair success | +| `NativeVMCapability`, `NativeVMStatus`, `NativeVMPlan`, `NativeVMGrant` | [`native_vm.go`](https://github.com/tuna-os/wootc/blob/main/app/native_vm.go), [VM exchanges](https://github.com/tuna-os/wootc/blob/main/tests/unit/fixtures/native-vm/responses.ndjson) | +| `LifecycleState` | [`state.go`](https://github.com/tuna-os/wootc/blob/main/app/state.go), [lifecycle example](https://github.com/tuna-os/wootc/blob/main/app/testdata/dto/lifecycle_state.json) | +| `RecoveryVerdict` | [`recovery.go`](https://github.com/tuna-os/wootc/blob/main/app/recovery.go) | +| `InstallRecoverySummary`, `InstallRecoveryActions` | [`status_install_recovery.go`](https://github.com/tuna-os/wootc/blob/main/app/status_install_recovery.go); native response is a safe summary, not raw journal evidence | +| `VMInstallConfig` | [`vm_account.go`](https://github.com/tuna-os/wootc/blob/main/app/vm_account.go) | +| `VMCapability` | [`vm_windows.go`](https://github.com/tuna-os/wootc/blob/main/app/vm_windows.go), [non-Windows definition](https://github.com/tuna-os/wootc/blob/main/app/vm_other.go) | +| `VMState`, `VMEvent` | [`vm_lifecycle.go`](https://github.com/tuna-os/wootc/blob/main/app/vm_lifecycle.go), [`app.go`](https://github.com/tuna-os/wootc/blob/main/app/app.go), [event example](https://github.com/tuna-os/wootc/blob/main/app/testdata/dto/vm_event.json) | + +An illustrative status exchange (values vary with the engine's observation): + +```json +{"jsonrpc":"2.0","id":1,"method":"GetStatus"} +{"jsonrpc":"2.0","id":1,"result":{"running":false,"done":false,"existing":false}} +``` + +Notifications omit `id`. Install progress carries `ProgressEvent`: + +```json +{"jsonrpc":"2.0","method":"install:progress","params":{"phaseId":"image-pull","step":"Downloading Linux","message":"Downloading Linux…","percent":50,"done":false}} +``` + +`phaseId` and `error` may be absent. The example is a shape illustration, not +an observed run. `vm:progress` carries `VMEvent` (`stage:string`, +`percent:number`, `message:string`). A progress +percentage, helper exit or active QEMU process does not establish login, +desktop readiness or successful migration. Read the durable lifecycle and +independent evidence before you report completion. + +### Contributor testing patterns + +- Protocol behavior: from `app`, run `go test ./...`. + `serve_test.go`, `serve_assessment_test.go`, `serve_shutdown_test.go` and + tests for native sessions will exercise JSON decode, dispatch, refusal, and cleanup. + Add behavioral requests/responses, not source-text assertions. +- After an intentional Go DTO change, run `go generate ./...` from `app` and + review the generated DTO changes. Validate compatibility through actual RPC + requests and consumers, not raw JSON copies. +- Cross-platform shell logic: `dotnet test shell/Wootc.Shell.Tests/Wootc.Shell.Tests.csproj` + and `dotnet test shell/Wootc.Shell.NativeTests/Wootc.Shell.NativeTests.csproj`. + Recorded exchanges and the gallery are suitable for screen/blocked-state + development, but do not prove Windows transport, elevation or installation. +- On an isolated Windows fixture, use the installed engine and native shell from the same build. + Run the native E2E lane above. Include malformed + and replayed grants, cancel/EOF during an armed operation, and restart/recovery. + Observe cleanup and Windows return; a successful `Shutdown` response + does not prove either result. Interactive UAC, minimum OS, offline setup, accessibility, + consumer hardware and RC screenshots retain their own acceptance gates. diff --git a/docs/wootc/wsl-migration.md b/docs/wootc/wsl-migration.md new file mode 100644 index 00000000..fae62562 --- /dev/null +++ b/docs/wootc/wsl-migration.md @@ -0,0 +1,126 @@ +--- +sidebar_position: 52 +title: "wsl migration" +--- + +WSL runs Linux inside Windows. wootc's native path installs a separate Linux +system beside Windows; it does not turn your WSL installation into a bootable +system. Your Windows account, WSL account and new Linux account are different. +With Windows, you can compare your work and return to the original tools. +This does not guarantee protection against data loss. + +Read the [current status](https://github.com/tuna-os/wootc/blob/main/docs/status.md), [download guide and trust prompts](https://github.com/tuna-os/wootc/blob/main/docs/getting-started.md) +and [user guide](https://github.com/tuna-os/wootc/blob/main/docs/user-guide.md) before you choose a build. +A release tag does not prove readiness for VM-first use, a particular image +or your hardware. The complete VM-first experience has its own acceptance gate. + +## 1. Inventory and back up in Windows + +1. Run `wsl --list --verbose` in PowerShell. Record the distributions you use + privately; do not paste account details into a public report. +2. In each WSL distribution, save open work. Commit projects or back them up + independently. Record required runtimes, packages, databases and services. + Projects under `/home` live inside WSL, not in Windows Documents. +3. Stop database/services cleanly, exit applications and run `wsl --shutdown` + from PowerShell. Do this before you export or install. + Do not treat a copy of a live `ext4.vhdx` as an application-consistent backup. +4. Export **each** needed distribution to independent backup storage. For + example, if `wsl --list --verbose` lists `Ubuntu` and `E:` is your backup: + + ```powershell + wsl --export Ubuntu E:\Backups\Ubuntu-before-wootc.tar + ``` + + Use your actual distribution name and an existing backup destination. A + WSL export can contain passwords, keys and work data: encrypt/protect it, + and never attach it to an issue. Follow + [Microsoft's WSL export/import guidance](https://learn.microsoft.com/en-us/windows/wsl/basic-commands#export-a-distribution) + to verify restoration on a separate test instance. An export is not proof + of recovery until you have checked its contents and restore procedure. +5. Back up Windows files separately, including cloud data downloaded for + offline use. Keep recovery media for Windows accessible without this PC. + Also keep any BitLocker key you need accessible without this PC. + Do not decrypt or bypass organizational policy to satisfy the installer. + +Keep these backups and WSL installed throughout the trial. Do **not** run +`wsl --unregister`: it deletes the registered distribution's data. + +## 2. Install through the supported journey + +Follow the selected build's [user guide](https://github.com/tuna-os/wootc/blob/main/docs/user-guide.md). +If you volunteer, also follow the [manual test protocol](https://github.com/tuna-os/wootc/blob/main/docs/manual-testing.md). +Use an admitted image and storage plan. Keep Windows as your recovery path. +Do not remove Windows or reclaim its partition during a first migration. +Review the proposed disk and boot changes; do not assume every plan only creates a file. + +On first Linux login, inspect **Bring Over From Windows** and the WSL category +when available. Availability in code or a dashboard is not proof that the +selected image and hardware have passed migration acceptance. + +## 3. Understand what the WSL helper actually does + +The implementation is +[`wootc-wsl-bridge`](https://github.com/tuna-os/wootc/blob/main/payload/migration/wootc-wsl-bridge): + +| Source | Behavior and limit | +| --- | --- | +| WSL1 files under the Windows profile | Searches legacy `lxss/rootfs` and Store `Packages/*/LocalState/rootfs` locations. | +| WSL2 `ext4.vhdx` | Searches Store `Packages/*/LocalState` and `wsl/*` under the Windows profile; needs `qemu-nbd`, an available NBD device and readable Windows storage. Attaches the source read-only. Imported/custom-location distros may not be found. | +| Multiple distros or Linux homes | Uses the first discovered rootfs and first home directory (or `/root`); it is **not** a distro/account picker. If this is not your intended source, leave the WSL category off and restore selected files manually from your backup. | +| Shell/editor config | Copies an allowlist including `.bashrc`, `.zshrc`, `.gitconfig`, `.vimrc`, `.tmux.conf` and selected other dotfiles; skips destination files already present. It does not merge them. | +| SSH | Copies public keys, `config` and `known_hosts` if absent at the destination; does not copy SSH private keys or GPG private-key stores. | +| Packages | Maps a subset of installed Debian/Ubuntu `dpkg` packages to a proposed `~/.config/wootc/Brewfile`. This is neither the complete package set nor a version lock; other package managers are not reconstructed. | +| Projects, databases, containers, services and credentials | No complete WSL filesystem, application state, account or service import. Move these deliberately from verified backups using the application's own procedure. | + +**Review configuration for secrets before you select migration.** An allowlisted +`.gitconfig`, `.curlrc`, `.zshenv` or SSH config can itself contain a token, +private host name or command. An allowlist is not a secret scanner. Also review +commands in shell startup files before you open the destination shell. +The exclusion of private-key files does not make every copied configuration non-sensitive. + +## 4. Rebuild and verify the development environment + +1. Compare copied dotfiles with your backup and review import results for each + item. A preserved collision or partial result is not a completed migration. + Deliberately merge files that the helper skipped. Adapt WSL paths such as + `/mnt/c`, `wsl.exe` calls and Windows executables. + + Keep native edits and back up the destination config before you edit it. + Do not replace a destination symlink or delete an existing file to force the importer to run. +2. Inspect `~/.config/wootc/Brewfile` before you install anything. Preserve any + native edits. Manually merge a proposal that conflicts with native content. + Do not assume silent regeneration or that a retry refreshed the file. + Where Homebrew is available and the reviewed tools are appropriate, run as + your normal user: + + ```sh + brew bundle --file="$HOME/.config/wootc/Brewfile" + ``` + + This optional step will download software; it does not automatically restore + the full toolchain. Use your distribution's supported tools for other packages. +3. Restore a non-sensitive project to a new Linux directory. Compare important + files with the backup, and run its normal build/tests. Re-establish language + runtimes, databases and containers with their supported migration methods. +4. Sign into services again or enroll new keys through your organization's + approved procedure. Do not copy credential stores to avoid sign-in. +5. Verify the contents of files, editor settings, network access and a work task. + A populated dashboard or generated Brewfile alone is not success. +6. Reboot to the Windows desktop, confirm the original WSL environment still + works, and re-enter Linux using the documented management path. For an alpha + cohort run, complete uninstall and the restoration checklist too. + +## If it does not work + +A missing WSL category, wrong source, empty folder, unexpected prompt or broken +return to Windows is a problem to report. Do not force-mount disks or delete +the original. Stop and submit a sanitized +[field report](https://github.com/tuna-os/wootc/issues/new?template=manual-test-report.yml). +Include the build, WSL1/WSL2, checkpoint and whether you needed help. + +Never attach an export, `.vhdx`, recovery key, raw home directory or configuration +with credentials. See [recovery and uninstall](https://github.com/tuna-os/wootc/blob/main/docs/user-guide.md#10-problems-and-recovery). + +Real user stories and public videos need an actual completed journey and the +participant's separate consent for publication. This guide is a procedure, not +a claim of a successful case study for a WSL graduation. diff --git a/src/data/synced-docs.json b/src/data/synced-docs.json index 8259c5c5..5f1a3380 100644 --- a/src/data/synced-docs.json +++ b/src/data/synced-docs.json @@ -1,15 +1,15 @@ { "rust-atomicwrites": { "revision": "7e18cf3045168c9e57368470d9d9dfb582d67d8a", - "lastSuccessfulFetch": "2026-11-18T14:42:20.564Z", + "lastSuccessfulFetch": "2026-11-19T14:49:27.862Z", "status": "ok", "pages": { "rust-atomicwrites/index": "README.md" } }, "tunaOS": { - "revision": "aaf0926717058e6be1d69825116455be00a6a095", - "lastSuccessfulFetch": "2026-11-18T14:41:56.888Z", + "revision": "893d80e447ef3cbe4084aad02508e77a7d578875", + "lastSuccessfulFetch": "2026-11-19T14:48:58.383Z", "status": "ok", "pages": { "tunaos/index": "README.md", @@ -19,8 +19,8 @@ } }, "bluefin-cli": { - "revision": "21835a4374e6f137f4b6a1ba9736340e1f0ac568", - "lastSuccessfulFetch": "2026-11-18T14:41:57.919Z", + "revision": "504b6f80f94e47cb511faa33ce1159b10b45a17c", + "lastSuccessfulFetch": "2026-11-19T14:48:59.011Z", "status": "ok", "pages": { "bluefin-cli/index": "README.md", @@ -31,6 +31,7 @@ "bluefin-cli/brewfile-guide": "docs/brewfile-guide.md", "bluefin-cli/cncf": "docs/cncf.md", "bluefin-cli/configuration": "docs/configuration.md", + "bluefin-cli/development": "docs/development.md", "bluefin-cli/getting-started": "docs/getting-started.md", "bluefin-cli/gnome": "docs/gnome.md", "bluefin-cli/menus": "docs/menus.md", @@ -46,8 +47,8 @@ } }, "tunaos-packages": { - "revision": "d75a51d242b43c56b074822c61a6b6623a54f948", - "lastSuccessfulFetch": "2026-11-18T14:41:59.099Z", + "revision": "590f3128735c55e0f5ca43098f11dd1b530dc303", + "lastSuccessfulFetch": "2026-11-19T14:49:00.326Z", "status": "ok", "pages": { "tunaos-packages/index": "README.md", @@ -84,8 +85,8 @@ } }, "tromso": { - "revision": "c0871d3da40cb8f7509e92a9d6f09e9c7fe15c16", - "lastSuccessfulFetch": "2026-11-18T14:42:00.663Z", + "revision": "35cc88eec27ec2492a27a06e4c9d8088064455c9", + "lastSuccessfulFetch": "2026-11-19T14:49:01.330Z", "status": "ok", "pages": { "tromso/index": "README.md", @@ -102,8 +103,8 @@ } }, "brussels": { - "revision": "26a08ac7c342d249468d054eb7ed246a9a955911", - "lastSuccessfulFetch": "2026-11-18T14:42:01.221Z", + "revision": "68db47be091b5a50de83ca73bb51b7e0769cfe29", + "lastSuccessfulFetch": "2026-11-19T14:49:01.966Z", "status": "ok", "pages": { "brussels/index": "README.md", @@ -117,8 +118,8 @@ } }, "tacklebox": { - "revision": "bf3d813816671f5abd00c9962e2e07964b062615", - "lastSuccessfulFetch": "2026-11-18T14:42:01.814Z", + "revision": "834a6d1e5e7ec6cb90051f7b5f0f7d70278c0575", + "lastSuccessfulFetch": "2026-11-19T14:49:02.624Z", "status": "ok", "pages": { "tacklebox/index": "README.md", @@ -142,8 +143,8 @@ } }, "Tavern": { - "revision": "52e4a8a13bda0e41ea2dc8af3ae64369a4e77087", - "lastSuccessfulFetch": "2026-11-18T14:42:02.467Z", + "revision": "5e77e0c40239d6bcb3be8b3d1167658390835a05", + "lastSuccessfulFetch": "2026-11-19T14:49:03.400Z", "status": "ok", "pages": { "tavern/index": "README.md", @@ -161,8 +162,8 @@ } }, "corral": { - "revision": "e3688e0938f4f68a8fe0a94993838f3388139366", - "lastSuccessfulFetch": "2026-11-18T14:42:03.342Z", + "revision": "0f956dffdda7c682804a804fb2c81fadfb5abe51", + "lastSuccessfulFetch": "2026-11-19T14:49:04.431Z", "status": "ok", "pages": { "corral/index": "README.md", @@ -195,8 +196,8 @@ } }, "bootc-migrate": { - "revision": "cb0b64aae4c5ce6bebce3c9bd6ad8fa461c2012e", - "lastSuccessfulFetch": "2026-11-18T14:42:03.987Z", + "revision": "934905f50ffbc61ecbccebdb2466161f8b3a005f", + "lastSuccessfulFetch": "2026-11-19T14:49:05.251Z", "status": "ok", "pages": { "bootc-migrate/index": "README.md", @@ -215,8 +216,8 @@ } }, "flatpak-index": { - "revision": "afc043748d826466dddec2915dec4fdfec02391f", - "lastSuccessfulFetch": "2026-11-18T14:42:04.350Z", + "revision": "56f5cfd316f9832d389dcc0343bf8298b7031b87", + "lastSuccessfulFetch": "2026-11-19T14:49:05.789Z", "status": "ok", "pages": { "flatpak-index/index": "README.md", @@ -233,7 +234,7 @@ }, "changelog-action": { "revision": "68295f376aef8f3d789ff18da86463bbb937796b", - "lastSuccessfulFetch": "2026-11-18T14:42:04.645Z", + "lastSuccessfulFetch": "2026-11-19T14:49:06.262Z", "status": "ok", "pages": { "changelog-action/index": "README.md", @@ -242,8 +243,8 @@ } }, "branding": { - "revision": "5153d171a2066fea91a3f3454327b96a9cb0ff52", - "lastSuccessfulFetch": "2026-11-18T14:42:05.033Z", + "revision": "5b470a9ddae49eb34b1ad5de41a195e989058bc5", + "lastSuccessfulFetch": "2026-11-19T14:49:06.713Z", "status": "ok", "pages": { "branding/index": "README.md", @@ -252,8 +253,8 @@ } }, "wootc": { - "revision": "2f720b317fece702b8b65bee6d28c090ceabfa1f", - "lastSuccessfulFetch": "2026-11-18T14:42:06.004Z", + "revision": "569e55e755373340aa5d78e9a913675b5502f73c", + "lastSuccessfulFetch": "2026-11-19T14:49:08.032Z", "status": "ok", "pages": { "wootc/index": "README.md", @@ -262,6 +263,7 @@ "wootc/docs-README": "docs/README.md", "wootc/RELEASING": "docs/RELEASING.md", "wootc/SPEC": "docs/SPEC.md", + "wootc/adoption-outreach": "docs/adoption-outreach.md", "wootc/agent-lessons": "docs/agent-lessons.md", "wootc/alpha-adopter-program": "docs/alpha-adopter-program.md", "wootc/architecture-boundary": "docs/architecture-boundary.md", @@ -282,6 +284,7 @@ "wootc/getting-started": "docs/getting-started.md", "wootc/gui-phase1-architecture": "docs/gui-phase1-architecture.md", "wootc/gui-walkthrough": "docs/gui-walkthrough.md", + "wootc/it-admin-quick-start": "docs/it-admin-quick-start.md", "wootc/managed-vm": "docs/managed-vm.md", "wootc/manual-testing": "docs/manual-testing.md", "wootc/milestones": "docs/milestones.md", @@ -304,12 +307,13 @@ "wootc/user-guide": "docs/user-guide.md", "wootc/vhdx-exploration": "docs/vhdx-exploration.md", "wootc/windows-state-trust": "docs/windows-state-trust.md", - "wootc/winui-shell": "docs/winui-shell.md" + "wootc/winui-shell": "docs/winui-shell.md", + "wootc/wsl-migration": "docs/wsl-migration.md" } }, "bootc-installer": { - "revision": "6ec0fd9d2b0c29b4b1cc84db6a42cdac3ff2c59c", - "lastSuccessfulFetch": "2026-11-18T14:42:07.629Z", + "revision": "8de6a37d787f3f9f20664ce2adf9f0e555c00345", + "lastSuccessfulFetch": "2026-11-19T14:49:11.038Z", "status": "ok", "pages": { "bootc-installer/index": "README.md", @@ -324,20 +328,22 @@ } }, "dualcut": { - "revision": "8f3def7ff88f2f1a67b6a9b1cf595c5585f99289", - "lastSuccessfulFetch": "2026-11-18T14:42:08.117Z", + "revision": "f39694dead18c14fa8320354eaf760420faf5ec1", + "lastSuccessfulFetch": "2026-11-19T14:49:11.656Z", "status": "ok", "pages": { "dualcut/index": "README.md", "dualcut/CONTRIBUTING": "CONTRIBUTING.md", "dualcut/ROADMAP": "ROADMAP.md", + "dualcut/TESTING": "docs/TESTING.md", + "dualcut/TROUBLESHOOTING": "docs/TROUBLESHOOTING.md", "dualcut/USER_GUIDE": "docs/USER_GUIDE.md", "dualcut/observability": "docs/observability.md" } }, "iso-builder": { - "revision": "70d17f2d9b5da9c0f1038857e601a5d97aafce03", - "lastSuccessfulFetch": "2026-11-18T14:42:08.719Z", + "revision": "c33e586e3d08d4f4b2f84afd9c5bcb9cf8b68ae8", + "lastSuccessfulFetch": "2026-11-19T14:49:12.275Z", "status": "ok", "pages": { "iso-builder/index": "README.md", @@ -354,8 +360,8 @@ } }, "homebrew-tap": { - "revision": "0ba2cbfa27b9574ba4eb5656e255b4def157e940", - "lastSuccessfulFetch": "2026-11-18T14:42:09.030Z", + "revision": "dfc2a75965e7dd1ff439bc9902f3776621041c40", + "lastSuccessfulFetch": "2026-11-19T14:49:12.788Z", "status": "ok", "pages": { "homebrew-tap/index": "README.md", @@ -364,8 +370,8 @@ } }, "scoop-bucket": { - "revision": "389dbe5082d48b380293eb0ebed54e65fbb9aaa8", - "lastSuccessfulFetch": "2026-11-18T14:42:09.347Z", + "revision": "cfcf43fd83e5ce99c0b43a9914dfaa5dd8848c64", + "lastSuccessfulFetch": "2026-11-19T14:49:13.268Z", "status": "ok", "pages": { "scoop-bucket/index": "README.md", @@ -374,8 +380,8 @@ } }, "bootsahi": { - "revision": "072140c5ecba20f9da6b070a378644cd8c327246", - "lastSuccessfulFetch": "2026-11-18T14:42:09.753Z", + "revision": "114a8831b6176cb396415b7d143f182a024ee2ce", + "lastSuccessfulFetch": "2026-11-19T14:49:13.841Z", "status": "ok", "pages": { "bootsahi/index": "README.md", @@ -391,7 +397,7 @@ }, "bst-ci": { "revision": "bad002079d5fab339c43b774a51a7dd30a79b294", - "lastSuccessfulFetch": "2026-11-18T14:42:10.128Z", + "lastSuccessfulFetch": "2026-11-19T14:49:14.516Z", "status": "ok", "pages": { "bst-ci/index": "README.md", @@ -400,8 +406,8 @@ } }, "protota": { - "revision": "aa615b113efc587ef8ff99fc5a36d0e2e888b2e7", - "lastSuccessfulFetch": "2026-11-18T14:42:11.141Z", + "revision": "115401dc27511ca59ce3b4c3ba5fb11901706e32", + "lastSuccessfulFetch": "2026-11-19T14:49:15.935Z", "status": "ok", "pages": { "protota/index": "README.md", @@ -425,8 +431,8 @@ } }, "hive": { - "revision": "e838cc613f21367df06a0f493d701eea5ee77432", - "lastSuccessfulFetch": "2026-11-18T14:42:13.305Z", + "revision": "469f7f7c235f00a3008f26a42b9762c5472aea57", + "lastSuccessfulFetch": "2026-11-19T14:49:17.994Z", "status": "ok", "pages": { "hive/index": "README.md", @@ -452,8 +458,8 @@ } }, "spindle": { - "revision": "34f53d9d68da3c8decfc551878463fae514ba77a", - "lastSuccessfulFetch": "2026-11-18T14:42:14.897Z", + "revision": "883bb6d0c0d808bfb06b13415bea909e374f1fff", + "lastSuccessfulFetch": "2026-11-19T14:49:20.022Z", "status": "ok", "pages": { "spindle/index": "README.md", @@ -496,8 +502,8 @@ } }, "gnome-hive-monitor": { - "revision": "32620db937c893565774da0846ce3919b227a4cf", - "lastSuccessfulFetch": "2026-11-18T14:42:15.345Z", + "revision": "a658a259fe711ede2c9f62396367042c49743a4b", + "lastSuccessfulFetch": "2026-11-19T14:49:20.537Z", "status": "ok", "pages": { "gnome-hive-monitor/index": "README.md", @@ -507,11 +513,12 @@ } }, "hive-operator": { - "revision": "5c4a7262827b98a7b4a2e3541dd5a613d4b91e5d", - "lastSuccessfulFetch": "2026-11-18T14:42:15.870Z", + "revision": "482b2a98c414fcef9ac65120952c89c933229cfd", + "lastSuccessfulFetch": "2026-11-19T14:49:21.107Z", "status": "ok", "pages": { "hive-operator/index": "README.md", + "hive-operator/CONTRIBUTING": "CONTRIBUTING.md", "hive-operator/housekeeping": "docs/housekeeping.md", "hive-operator/liveness-promotion": "docs/liveness-promotion.md", "hive-operator/release": "docs/release.md", @@ -521,15 +528,15 @@ }, "rdocx": { "revision": "9e9cbd5e8447d7a7f50e19dd9193e8b3ac5960b5", - "lastSuccessfulFetch": "2026-11-18T14:42:17.533Z", + "lastSuccessfulFetch": "2026-11-19T14:49:23.578Z", "status": "ok", "pages": { "rdocx/index": "README.md" } }, "compass": { - "revision": "6ad02542991a465bb1df161258ced5c51a7b4bbd", - "lastSuccessfulFetch": "2026-11-18T14:42:19.123Z", + "revision": "7fb743b75f0c6d4439c7d63c2118ddb83b9a6546", + "lastSuccessfulFetch": "2026-11-19T14:49:25.661Z", "status": "ok", "pages": { "compass/index": "README.md", @@ -544,7 +551,7 @@ }, "quickcast": { "revision": "12227fbf2eb6573328dea66a68d7fbbb8ebfee65", - "lastSuccessfulFetch": "2026-11-18T14:42:19.660Z", + "lastSuccessfulFetch": "2026-11-19T14:49:26.376Z", "status": "ok", "pages": { "quickcast/index": "README.md", @@ -556,15 +563,15 @@ }, "libcosmic": { "revision": "ed6bffbd8cff8233f9dee5915a474b5599bd402c", - "lastSuccessfulFetch": "2026-11-18T14:42:20.261Z", + "lastSuccessfulFetch": "2026-11-19T14:49:27.347Z", "status": "ok", "pages": { "libcosmic/index": "README.md" } }, "iced": { - "revision": "881f1004c84350fda3cd90d662e53e7e8fd67033", - "lastSuccessfulFetch": "2026-11-18T14:42:21.428Z", + "revision": "a34895c8bc57810c30beceac2ecda08be1c20846", + "lastSuccessfulFetch": "2026-11-19T14:49:29.649Z", "status": "ok", "pages": { "iced/index": "README.md", @@ -574,7 +581,7 @@ }, "PaperWM": { "revision": "b72c9beba8c6482d988383dd37ff85093c632b63", - "lastSuccessfulFetch": "2026-11-18T14:42:21.904Z", + "lastSuccessfulFetch": "2026-11-19T14:49:30.238Z", "status": "ok", "pages": { "paperwm/index": "README.md", @@ -582,8 +589,8 @@ } }, "ccleft": { - "revision": "d108f9158538e9ff5095f53d95411805a3a39e88", - "lastSuccessfulFetch": "2026-11-18T14:42:22.241Z", + "revision": "989a7e822a2f996aacac0d555d428ea337252b5b", + "lastSuccessfulFetch": "2026-11-19T14:49:30.744Z", "status": "ok", "pages": { "ccleft/index": "README.md", @@ -592,8 +599,8 @@ } }, "tuna-desktop": { - "revision": "aa414f39195a225037f2cfa8e1f83e6adfe67348", - "lastSuccessfulFetch": "2026-11-18T14:42:27.751Z", + "revision": "9dacb1e1d73bfa2a2720d30a69bab11c0d712dea", + "lastSuccessfulFetch": "2026-11-19T14:49:43.437Z", "status": "ok", "pages": { "tuna-desktop/index": "README.md", @@ -666,16 +673,16 @@ } }, "athens": { - "revision": "39013ae72b045a2102f3e09dccdb5386bc905e88", - "lastSuccessfulFetch": "2026-11-18T14:42:28.279Z", + "revision": "bcf2c5afed681c6d552b3d44770bad4e00983e3a", + "lastSuccessfulFetch": "2026-11-19T14:49:44.150Z", "status": "ok", "pages": { "athens/index": "README.md" } }, "lifafa": { - "revision": "5d4c5c6f0c9a4bc25629e7eb7c242646864f0fdc", - "lastSuccessfulFetch": "2026-11-18T14:42:29.838Z", + "revision": "8e0fb0dfd7aa3c8d4c503fff2ae197ba3caec89c", + "lastSuccessfulFetch": "2026-11-19T14:49:45.768Z", "status": "ok", "pages": { "lifafa/index": "README.md", @@ -695,8 +702,8 @@ } }, "tuta-unofficial-sdk": { - "revision": "e7c70b0f838976ba62d805d54da31b4c59118a23", - "lastSuccessfulFetch": "2026-11-18T14:42:30.577Z", + "revision": "69e62f0967c7ef3df8a5f76abe06076bb3970623", + "lastSuccessfulFetch": "2026-11-19T14:49:46.387Z", "status": "ok", "pages": { "tuta-unofficial-sdk/index": "README.md" @@ -704,7 +711,7 @@ }, "flatpark": { "revision": "97dda79a7ab404ca885d761e7f3051a98a7c99f9", - "lastSuccessfulFetch": "2026-11-18T14:42:31.480Z", + "lastSuccessfulFetch": "2026-11-19T14:49:47.577Z", "status": "ok", "pages": { "flatpark/index": "README.md", @@ -714,21 +721,22 @@ } }, "tuna-mail": { - "revision": "4fcd73498dee93a9e1140838991e720ae622c8df", - "lastSuccessfulFetch": "2026-11-18T14:42:34.868Z", + "revision": "28e9804a58534f144442be7b04845df028b48457", + "lastSuccessfulFetch": "2026-11-19T14:49:51.392Z", "status": "ok", "pages": { "tuna-mail/index": "README.md", + "tuna-mail/CONTRIBUTING": "CONTRIBUTING.md", "tuna-mail/SECURITY": "SECURITY.md", - "tuna-mail/CONTRIBUTING": "docs/CONTRIBUTING.md", + "tuna-mail/docs-CONTRIBUTING": "docs/CONTRIBUTING.md", "tuna-mail/HOW-TO-DOCUMENT": "docs/HOW-TO-DOCUMENT.md", "tuna-mail/docs-README": "docs/README.md", "tuna-mail/about": "docs/about.md" } }, "proton-unofficial-sdk": { - "revision": "2a20b8d2eab47c3f0a1f2813a072593fc305aa0e", - "lastSuccessfulFetch": "2026-11-18T14:42:36.178Z", + "revision": "4bdd7cc6226e868e278b85918889f3c179f149bd", + "lastSuccessfulFetch": "2026-11-19T14:49:53.005Z", "status": "ok", "pages": { "proton-unofficial-sdk/index": "README.md"