docs: harden agent release guidance

Author: tw93

.agents/skills/code-review/SKILL.md

@@ -20,11 +20,15 @@ Use Waza `/check` for the generic review method. This adapter adds Pake-specific
 - [ ] Changes to package metadata embedded by Rollup (`package.json` name/version/repository/bin/scripts/exports) rebuild and commit `dist/cli.js`.
 - [ ] Release version bumps keep `package.json`, `src-tauri/Cargo.toml`, `src-tauri/Cargo.lock`, and `src-tauri/tauri.conf.json` in sync.
 - [ ] npm release workflow changes preserve Trusted Publishing: `.github/workflows/npm-publish.yml`, `id-token: write`, canonical `git+https://github.com/tw93/Pake.git`, and `scripts/check-release-version.mjs`.
+- [ ] Release/status changes keep npm registry, GitHub Release/assets, workflow run state, and issue closeout as separate truth surfaces.
+- [ ] `workflow_dispatch` release logic does not infer the release tag from `headBranch`, run title, or compare UI; use an explicit tag/ref and verify the package `gitHead`.
 - [ ] No new `tauriConf: any` or other untyped config objects; use `PakeTauriConfig`.
 - [ ] No user-reachable `panic!` or `.unwrap()` on config, CLI, or event paths.
 - [ ] Silent `catch {}` blocks surface the real error through `logger.warn`.
 - [ ] New helper in `bin/utils/` or `bin/helpers/` has a matching `tests/unit/<basename>.test.ts`.
 - [ ] Binary parsers have a round-trip test, not only builder assertions.
+- [ ] Linux WebKit/AppImage runtime flag changes keep the default conservative, add or update tests for the decision logic, and update `docs/faq*.md` when users need a fallback command.
+- [ ] macOS `--new-window` or auth URL changes include targeted tests for popup/auth routing in `src-tauri/src/inject/event.js`.
 
 ## Quick Review Commands
 

.agents/skills/release/SKILL.md

@@ -28,13 +28,14 @@ Four files must be updated in sync — never update one without the others:
 ### Pre-Release
 
 1. [ ] Confirm the new version number (check current: `cat package.json | jq .version`)
-2. [ ] Update all four version files above
-3. [ ] Run `pnpm run format` — must pass cleanly
-4. [ ] Run `pnpm test` — must pass cleanly. If the release workflow step fails with `pnpm install ... exit code 1` against the CN mirror, re-run once; a single transient flake is acceptable, two consecutive failures is not.
-5. [ ] Run `pnpm run cli:build` — Rollup + TS must pass (catches type errors that `format` misses).
-6. [ ] Run `pnpm run release:check` — verifies version sync, package contents, and npm dry-run
-7. [ ] No uncommitted changes: `git status`
-8. [ ] Commit version bump with message: `chore: bump version to VX.X.X`
+2. [ ] Confirm the version is not already on npm: `npm view pake-cli@X.Y.Z version` should return 404 before publishing
+3. [ ] Update all four version files above
+4. [ ] Run `pnpm run format` — must pass cleanly
+5. [ ] Run `pnpm test` — must pass cleanly. If the release workflow step fails with `pnpm install ... exit code 1` against the CN mirror, re-run once; a single transient flake is acceptable, two consecutive failures is not.
+6. [ ] Run `pnpm run cli:build` — Rollup + TS must pass (catches type errors that `format` misses).
+7. [ ] Run `pnpm run release:check` — verifies version sync, package contents, and npm dry-run
+8. [ ] No uncommitted changes: `git status`
+9. [ ] Commit version bump with message: `chore: bump version to VX.X.X`
 
 ### Tagging (triggers CI)
 
@@ -49,19 +50,32 @@ Tag format: uppercase `V` prefix (e.g. `V3.11.0`), not `v3.11.0`.
 
 1. [ ] Confirm CI triggered: `gh run list --workflow=release.yml`
 2. [ ] Watch CI status: `gh run watch`
-3. [ ] Verify GitHub Release was created: `gh release view VX.X.X`
+3. [ ] Verify GitHub Release was created: `gh release view VX.X.X --json tagName,url,assets`
 4. [ ] Confirm npm workflow exists and is active: `gh workflow list --all | grep "Publish npm Package"`
 5. [ ] Confirm npm Trusted Publishing triggered: `gh run list --workflow=npm-publish.yml`
-6. [ ] Verify npm published the package: `npm view pake-cli version` and `npm view pake-cli@X.Y.Z dist.tarball`
+6. [ ] Verify npm published the exact package: `npm view pake-cli@X.Y.Z version gitHead dist.tarball --json`
+7. [ ] Verify latest now resolves to the release: `npm view pake-cli version`
+8. [ ] Record Quality & Testing status separately: `gh run list --workflow=quality-and-test.yml --limit 3`
 
 npm publishes through Trusted Publishing from `.github/workflows/npm-publish.yml`. Configure npm package settings with GitHub Actions, `tw93/Pake`, workflow file `npm-publish.yml`, and no environment. Local `npm publish` is only a fallback if CI or registry state blocks the trusted path.
 
+Keep release surfaces separate in the final status:
+
+- npm registry: the authority for `pake-cli` installability and CLI/npm issue closeout.
+- GitHub Release/assets: the authority for app installers and popular-app artifact availability.
+- Quality workflow: the authority for post-push CI health, but it can continue after npm has already shipped.
+- Source/tag: the authority for what code was intended to ship.
+
+Do not collapse these into "released" without naming which surface was verified. If GitHub Release assets are visible while `gh run list` still reports the release workflow as queued or in progress, trust `gh release view` for asset state and report the workflow state separately.
+
 ## Trusted Publishing Notes
 
 - The first real Trusted Publishing test must use a new version and a new `V*` tag; do not retry an already-published version.
 - npm package settings should use the strict publishing option: require two-factor authentication and disallow tokens. Trusted Publishing still works with this setting.
 - If local fallback is unavoidable, prefer `npm exec --yes --package=pnpm@10.26.2 -- npm publish --registry=https://registry.npmjs.org` so `prepublishOnly` can find the pinned pnpm version.
-- Do not reply to GitHub issues or close them as released until `npm view pake-cli@X.Y.Z version` returns the expected version.
+- Do not reply to GitHub issues or close them as released until `npm view pake-cli@X.Y.Z version` returns the expected version. `npm view pake-cli version` alone is not enough because `latest` can point at a different commit than the fix under review.
+- A `workflow_dispatch` run may execute on `main`; do not treat `headBranch`, run title, or compare UI as the release tag. Check the pushed tag and published package `gitHead`.
+- If CI creates `chore: update contributors [skip ci]` after the tag is pushed, fast-forward local `main` after the release. Do not retag just to include generated contributor art.
 
 ## Build Commands (local only)
 

.agents/skills/use-pake/SKILL.md

@@ -136,6 +136,22 @@ After build, confirm:
 
 Not supported. Pake uses system WebView (WKWebView on macOS, WebView2 on Windows, WebKitGTK on Linux), not a full Chrome browser. Use `--inject` to add custom JS/CSS as an alternative.
 
+### Linux Wayland Input Issues
+
+If an AppImage opens but buttons cannot be clicked or keyboard input does not reach the page on a pure Wayland compositor, especially niri, first rebuild with the latest `pake-cli`. Then try the native WebKit path:
+
+```bash
+PAKE_LINUX_WEBKIT_SAFE_MODE=0 ./YourApp.AppImage
+```
+
+If that produces a blank window on the same system, re-enable the conservative WebKit workaround:
+
+```bash
+PAKE_LINUX_WEBKIT_SAFE_MODE=1 ./YourApp.AppImage
+```
+
+Do not diagnose this from GTK, appindicator, or GStreamer warnings alone; those can be optional runtime warnings unrelated to the input failure.
+
 ## Common Patterns
 
 ### Website behind proxy (icon also needs proxy)

.claude/rules/rust.md

@@ -34,5 +34,7 @@
 ### Platform sensitivity
 
 - WebKit compositing on Linux/Wayland is platform-sensitive. Don't change defaults without testing on the affected platform or documenting the risk.
+- Linux WebKit runtime flags live in `src-tauri/src/lib.rs`. Keep the default conservative; compositor-specific exceptions need unit tests for the decision function and FAQ guidance for users.
+- AppImage logs often contain optional GTK, appindicator, or GStreamer warnings. Do not treat those warnings as the root cause unless the user-visible symptom and target path confirm it.
 - `--incognito` trades persistence for clean private sessions; be deliberate around login / cookies / local storage / embedded-WebView detection.
 - Google OAuth and other embedded-WebView restrictions may still apply even with `--new-window` / `--multi-window`.

.claude/skills/release/SKILL.md

@@ -28,13 +28,14 @@ Four files must be updated in sync — never update one without the others:
 ### Pre-Release
 
 1. [ ] Confirm the new version number (check current: `cat package.json | jq .version`)
-2. [ ] Update all four version files above
-3. [ ] Run `pnpm run format` — must pass cleanly
-4. [ ] Run `pnpm test` — must pass cleanly. If the release workflow step fails with `pnpm install ... exit code 1` against the CN mirror, re-run once; a single transient flake is acceptable, two consecutive failures is not.
-5. [ ] Run `pnpm run cli:build` — Rollup + TS must pass (catches type errors that `format` misses).
-6. [ ] Run `pnpm run release:check` — verifies version sync, package contents, and npm dry-run
-7. [ ] No uncommitted changes: `git status`
-8. [ ] Commit version bump with message: `chore: bump version to VX.X.X`
+2. [ ] Confirm the version is not already on npm: `npm view pake-cli@X.Y.Z version` should return 404 before publishing
+3. [ ] Update all four version files above
+4. [ ] Run `pnpm run format` — must pass cleanly
+5. [ ] Run `pnpm test` — must pass cleanly. If the release workflow step fails with `pnpm install ... exit code 1` against the CN mirror, re-run once; a single transient flake is acceptable, two consecutive failures is not.
+6. [ ] Run `pnpm run cli:build` — Rollup + TS must pass (catches type errors that `format` misses).
+7. [ ] Run `pnpm run release:check` — verifies version sync, package contents, and npm dry-run
+8. [ ] No uncommitted changes: `git status`
+9. [ ] Commit version bump with message: `chore: bump version to VX.X.X`
 
 ### Tagging (triggers CI)
 
@@ -49,19 +50,32 @@ Tag format: uppercase `V` prefix (e.g. `V3.11.0`), not `v3.11.0`.
 
 1. [ ] Confirm CI triggered: `gh run list --workflow=release.yml`
 2. [ ] Watch CI status: `gh run watch`
-3. [ ] Verify GitHub Release was created: `gh release view VX.X.X`
+3. [ ] Verify GitHub Release was created: `gh release view VX.X.X --json tagName,url,assets`
 4. [ ] Confirm npm workflow exists and is active: `gh workflow list --all | grep "Publish npm Package"`
 5. [ ] Confirm npm Trusted Publishing triggered: `gh run list --workflow=npm-publish.yml`
-6. [ ] Verify npm published the package: `npm view pake-cli version` and `npm view pake-cli@X.Y.Z dist.tarball`
+6. [ ] Verify npm published the exact package: `npm view pake-cli@X.Y.Z version gitHead dist.tarball --json`
+7. [ ] Verify latest now resolves to the release: `npm view pake-cli version`
+8. [ ] Record Quality & Testing status separately: `gh run list --workflow=quality-and-test.yml --limit 3`
 
 npm publishes through Trusted Publishing from `.github/workflows/npm-publish.yml`. Configure npm package settings with GitHub Actions, `tw93/Pake`, workflow file `npm-publish.yml`, and no environment. Local `npm publish` is only a fallback if CI or registry state blocks the trusted path.
 
+Keep release surfaces separate in the final status:
+
+- npm registry: the authority for `pake-cli` installability and CLI/npm issue closeout.
+- GitHub Release/assets: the authority for app installers and popular-app artifact availability.
+- Quality workflow: the authority for post-push CI health, but it can continue after npm has already shipped.
+- Source/tag: the authority for what code was intended to ship.
+
+Do not collapse these into "released" without naming which surface was verified. If GitHub Release assets are visible while `gh run list` still reports the release workflow as queued or in progress, trust `gh release view` for asset state and report the workflow state separately.
+
 ## Trusted Publishing Notes
 
 - The first real Trusted Publishing test must use a new version and a new `V*` tag; do not retry an already-published version.
 - npm package settings should use the strict publishing option: require two-factor authentication and disallow tokens. Trusted Publishing still works with this setting.
 - If local fallback is unavoidable, prefer `npm exec --yes --package=pnpm@10.26.2 -- npm publish --registry=https://registry.npmjs.org` so `prepublishOnly` can find the pinned pnpm version.
-- Do not reply to GitHub issues or close them as released until `npm view pake-cli@X.Y.Z version` returns the expected version.
+- Do not reply to GitHub issues or close them as released until `npm view pake-cli@X.Y.Z version` returns the expected version. `npm view pake-cli version` alone is not enough because `latest` can point at a different commit than the fix under review.
+- A `workflow_dispatch` run may execute on `main`; do not treat `headBranch`, run title, or compare UI as the release tag. Check the pushed tag and published package `gitHead`.
+- If CI creates `chore: update contributors [skip ci]` after the tag is pushed, fast-forward local `main` after the release. Do not retag just to include generated contributor art.
 
 ## Build Commands (local only)
 

AGENTS.md

@@ -85,6 +85,7 @@ Execution rules:
 - Start with the smallest plausible file set
 - Prefer targeted search (`rg <symbol|string> <paths>`) over repository-wide scans
 - Ignore generated or output-heavy areas unless the task directly targets them, especially `dist/`, `node_modules/`, `src-tauri/target/`, `.app/`, `src-tauri/icons/`, and `src-tauri/png/`. Exception: `dist/cli.js` is the shipped CLI build artifact (see `package.json` `files`); when you change anything under `bin/`, rebuild it via `pnpm run cli:build` and commit the regenerated `dist/cli.js` alongside the source change
+- If a task touches release status, issue closeout, npm delivery, or GitHub assets, verify live surfaces separately: source commit/tag, workflow run, npm registry, GitHub Release/assets, and issue state. Do not let one passing surface imply another
 - Keep changes local to one subsystem when possible
 - Run the narrowest relevant verification first, expand only if needed
 - If key context is missing, make one reasonable assumption and proceed
@@ -95,8 +96,11 @@ Execution rules:
 - Recent window/runtime options include `--incognito`, `--new-window`, `--min-width`, `--min-height`, `--maximize`, multi-window behavior, notification click handling, and Linux/Wayland WebKit compositing defaults.
 - `--incognito` intentionally trades persistence for clean private sessions; be careful around login, cookies, local storage, and WeChat-style WebView detection.
 - `--new-window` and `--multi-window` do not bypass every provider policy. Google OAuth and similar embedded-WebView restrictions may still require a normal browser or native client.
+- macOS auth-popup behavior is fragile. Auth/sign-in URLs that trigger WebKit `SOAuthorization` popup creation should stay in the current window when that path can abort the app; changes in `src-tauri/src/inject/event.js` need targeted tests.
 - Notification flows cross injected JS, Tauri invokes, capabilities, and native notification plugins. Verify the Rust capability and JS caller together.
-- WebKit compositing behavior is platform-sensitive on Linux/Wayland. Do not change defaults without testing the affected platform path or documenting the risk.
+- WebKit compositing behavior is platform-sensitive on Linux/Wayland. Runtime flag decisions live in `src-tauri/src/lib.rs`; keep the default conservative, cover compositor exceptions with unit tests, and document user-facing fallbacks in `docs/faq*.md`.
+- Linux AppImage reports often include harmless GTK, appindicator, or GStreamer warnings. Separate optional runtime warnings from the actual symptom before changing code; input/click failures on pure Wayland compositors are not the same class as blank-window failures.
+- Release state can be split. npm Trusted Publishing can succeed before the popular-app release workflow finishes, and GitHub Release assets can exist while a workflow run still shows queued or in progress. Report each surface explicitly.
 
 ## Platform-Specific Development
 
@@ -150,7 +154,14 @@ The workflow can also be triggered manually via `workflow_dispatch` with options
 
 Pushing the same `V*` tag also triggers `.github/workflows/npm-publish.yml`, which publishes `pake-cli` to npm through Trusted Publishing. Configure the npm package's Trusted Publisher as GitHub Actions, `tw93/Pake`, workflow file `npm-publish.yml`, with no environment. Local `npm publish` is only a fallback when CI or npm registry state blocks the trusted path.
 
-Before treating an npm release as shipped, verify both `gh workflow list --all | grep "Publish npm Package"` and `npm view pake-cli@X.Y.Z version`. Do not reply to or close GitHub issues as released until the public registry returns the expected version.
+Before treating an npm release as shipped, verify both `gh workflow list --all | grep "Publish npm Package"` and `npm view pake-cli@X.Y.Z version`. Prefer `npm view pake-cli@X.Y.Z version gitHead dist.tarball --json` so the published package can be tied back to the intended commit. Do not reply to or close GitHub issues as released until the public registry returns the expected version.
+
+For release follow-through, keep these boundaries explicit:
+
+- `workflow_dispatch` runs on a branch unless a tag ref or input is supplied. Do not infer a release tag from the branch name, run title, or compare UI.
+- For CLI/npm issue closeout, the npm registry is the decisive public surface. GitHub app release assets and quality workflows should still be reported, but they are separate surfaces.
+- For app-release claims, inspect the GitHub Release directly with `gh release view <tag> --json assets` and check asset count/state instead of trusting source state or workflow names alone.
+- If CI pushes an automatic `chore: update contributors [skip ci]` commit after release, fast-forward local `main`; do not move an already pushed release tag to include it.
 
 `.github/workflows/quality-and-test.yml` runs auto-format on push, Rust quality checks, and CLI/build validation across Linux, Windows, and macOS.