waggle-os/docs/audits/2026-07-08-ux-non-main-surface-scope.md

Non-Main UX Surface Scope

Status: analysis only. No product code was changed.

Purpose: the main audit already covers the installed cockpit experience in apps/web. This note prevents "complete UX" from silently excluding the public launch funnel, Browser Companion extension, Tauri desktop wrapper, installer/update path, active local service startup path, admin web surface, CLI launchers, marketplace CLI, memory MCP utilities, AI-tool hooks, developer APIs, background jobs, substrate package verification, deployment/ops configuration, CI, benchmarks, and judging artifacts.

Scope Decision

The five-persona 9/10 judge gate should primarily score the installed product experience: apps/web rendered through the local service, because the requested personas are operating the product.

The final "complete UX" claim still needs one of these explicit decisions:

1. Fix and verify the non-main launch/desktop/utility/hook/developer/ops gates before final scoring.
2. Approve a written deferral that scopes the five-persona gate to the installed app only.

Without one of those decisions, public download, checkout, legal trust, browser capture, installer, tray, update, sidecar-startup, admin, CLI, MCP utility, hook lifecycle, SDK, server API, worker, substrate verification, deployment, CI, benchmark, and judging failures could remain outside the score while still affecting real users.

Public Launch Funnel: apps/www

User jobs:

• Understand what Waggle is.
• Download the desktop app.
• Sign in or sign up.
• Start Team checkout.
• Recover from cancelled checkout.
• Read methodology, legal, privacy, cookies, and EU AI Act trust pages.
• Reach KVARK for Enterprise.

Current strengths:

• Homepage is structured as a coherent launch narrative: hero, problem, how it works, memory, proof, features, trust, personas, open source, pricing, final CTA.
• Landing page has a skip link, semantic sections, absolute nav anchors, mobile menu semantics, and OS-aware download CTA.
• Pricing is mostly aligned to Solo, Team, Enterprise.
• Historical Lighthouse note reports 96 performance, 96 accessibility, and 100 SEO on a local prod build.
• BrandPersonasCard has useful component coverage, including keyboard activation and image-failure fallback.

Current command evidence, 2026-07-08 continuation:

Check	Result	Interpretation
npm run test -w apps/www	Pass, 1 file / 10 tests	The existing component coverage is healthy, but still narrow.
npm run build:www	Pass	Next build succeeds and reports dynamic routes for account, Clerk auth, Stripe checkout, and Stripe webhook.
npx tsc --noEmit --project apps/www/tsconfig.json	Pass	Direct TypeScript check passes for the public site.
Test-Path apps/www/dist, Test-Path apps/www/.next, Test-Path apps/www/out	False, True, False	The build output is .next, not the apps/www/dist artifact uploaded by the current GitHub Pages workflow.
Env-shape check for Clerk/Stripe keys	Mixed	apps/www/.env.local has Clerk test keys that differ from the root Clerk pair, and a live-shaped Stripe secret. Values were not printed.
next start bound to 127.0.0.1 + bounded route/API smoke	Invalid harness / fail	Next middleware attempted to proxy to localhost:<port> and returned timeouts/500s. Re-running against --hostname localhost showed the core public routes can render, so the 127.0.0.1 result is a Windows host-binding trap, not by itself product behavior.
next start bound to localhost + status/browser smoke	Mixed	/, /#pricing, /privacy, /terms, /cookies, /eu-ai-act, /sign-in, /sign-up, /docs/methodology, and unauthenticated /account redirect render; /pricing?checkout=cancelled is 404; signed-out Get Team leaves a small inline Sign in required error; browser console/server log still show Clerk development-key and session-loop warnings.
Focused T13 continuation smoke	Mixed	Fresh localhost route/API smoke confirms core pages and signed-out GET checkout redirect work; /pricing?checkout=cancelled and /methodology return 404; signed-out POST checkout returns 401 with a signInUrl the pricing UI does not use.
Live canonical-domain smoke	Fail	Current external refresh on 2026-07-08 could not resolve waggle-os.ai; nslookup waggle-os.ai returned non-existent domain from the audit environment.
GitHub Releases latest target	Fail	The public download CTA points to GitHub Releases latest, but GitHub currently reports no releases for the repo; API refresh returned an empty releases list.

Open UX risks:

ID	Risk	Evidence	Why it matters
WWW-0	The standard launch-funnel smoke is host-sensitive and Clerk-noisy.	Binding next start to 127.0.0.1 caused Next middleware proxy failures to localhost:<port> on Windows; binding to localhost rendered core routes, but the browser/server still emitted Clerk development-key and session-loop warnings.	A release gate needs a stable, documented smoke command and zero auth-loop noise before buyers or reviewers use the public site.
WWW-0A	The canonical public domain does not currently resolve.	Current external refresh could not resolve waggle-os.ai; the app metadata, sitemap, robots, and methodology page declare https://waggle-os.ai as canonical.	The acquisition, pricing, legal, auth, account, and download funnel is unreachable at the URL the app declares canonical.
WWW-1	Signed-out Team checkout can dead-end as a JSON error.	Pricing.tsx calls POST /api/stripe/checkout; the route returns 401 { message: "Sign in required", signInUrl }; the component only shows the message and ignores signInUrl.	A buyer clicking "Get Team" before signing in should be guided into sign-in/sign-up and then checkout, not shown an implementation-shaped error.
WWW-2	Stripe cancel recovery points to a likely dead route.	Checkout route uses cancel_url: ${origin}/pricing?checkout=cancelled; the site has a pricing section on /, not an app/pricing/page.tsx route.	Cancelled checkout should return to pricing with clear recovery, not a 404 or unrelated page.
WWW-3	GitHub Pages deployment workflow likely cannot publish this Next app as written.	deploy-www.yml uploads apps/www/dist; npm run build:www produced .next, not dist or out, and the app includes dynamic Clerk and Stripe API routes.	A strong local landing page still fails the launch funnel if the deploy target cannot serve it.
WWW-4	Legal trust pages are visibly unfinished and contain stale tier copy.	Terms/privacy/cookies/EU AI Act pages say "Day-0 placeholder"; privacy says "upgrade to Pro or Teams"; launch-date/address placeholders remain.	Legal/trust copy is part of UX for founders, admins, and enterprise reviewers.
WWW-5	Coverage is thin for funnel flows.	Only BrandPersonasCard.test.tsx was found under apps/www/__tests__; no route E2E, checkout recovery, account, mobile nav, or fresh Lighthouse evidence was collected in this packet.	One component test cannot justify a complete launch UX claim.
WWW-6	Public download currently leads to no installable artifact.	DownloadCTA targets GitHub Releases latest, but the repository currently has no releases; OS detection can also label iPhone/iPad as macOS and unsupported desktops as Linux while public copy says Windows and macOS.	Download is the first conversion path for Solo founders and mobile evaluators; an empty target makes the product look unavailable.

Recommended ticket: T13, Launch Funnel UX Gate. Focused supplement: docs/audits/2026-07-08-launch-funnel-t13-analysis.md.

Suggested acceptance:

• apps/www build/deploy target is valid for the actual app shape, or deployment is moved to an appropriate Next host.
• Canonical https://waggle-os.ai/ resolves and serves the selected public-site deployment.
• Download CTA leads to valid Windows/macOS artifacts or a controlled download/status page; mobile and unsupported OS labels are honest.
• Local production route smoke uses the correct host binding and serves /, /#pricing, /docs/methodology, /privacy, /terms, /cookies, /eu-ai-act, /sign-in, /sign-up, unauthenticated /account redirect, and checkout recovery without 500s, timeouts, 404s, or Clerk redirect-loop spam.
• Homepage route smoke passes on desktop and mobile with no critical console errors.
• Mobile nav, download CTA, billing toggle, signed-out Team checkout, signed-in Team checkout stub/live lane, checkout cancel recovery, account redirect, sign-in, and sign-up are exercised.
• Legal pages have no placeholder launch dates/addresses and no active Pro copy except explicit legacy billing context.
• Fresh Lighthouse or equivalent accessibility/performance/SEO evidence is attached.

Browser Companion Extension: apps/browser-ext

User jobs:

• Save selected text from any web page into Waggle memory.
• Save the current page into Waggle memory.
• See whether Waggle desktop is reachable.
• Understand which workspace or personal memory receives the save.
• Recover from CORS/sidecar disconnected states.

Current strengths:

• The folder is intentionally documented as "Waggle Companion", a Chrome MV3 extension.
• Manifest is simple and local-first: popup, background service worker, content script, context menu, active tab, storage.
• Popup has connected/disconnected status, workspace label, save-selection/save-page actions, and an Open Waggle button.
• Background script talks to the local sidecar; popup code uses textContent for workspace names rather than innerHTML.
• Server has dedicated GET /api/browser-ext/session-token and GET /api/browser-ext/health endpoints, plus CORS/config checks for extension IDs.

Current source evidence, 2026-07-08 continuation:

Check	Result	Interpretation
Get-ChildItem apps/browser-ext -Recurse -File	Pass	Extension files are present: manifest.json, popup.html, popup.js, background.js, content.js, README.md.
Source search for browser-ext and extension env vars	Pass	README, server route, CORS config, backend docs, and settings coverage card all reference the extension.
packages/server/src/local/routes/browser-ext.ts inspection	Pass	Token endpoint bootstraps allowlisted Browser Companion requests; health endpoint returns { ok, version, activeWorkspaceId, activeWorkspace } with activeWorkspace kept for legacy extension builds; save flows reuse /api/memory/frames.
Extension JS syntax, manifest parse, and server typecheck	Pass	Root extension files parse and the server side of the contract typechecks.
Playwright disconnected-state smoke	Partial	Unpacked extension loads and disconnected popup renders; screenshot at output/playwright/browser-companion-disconnected-state.png. This does not prove toolbar-popup-over-page behavior or save success.
Secure-default loaded-extension save smoke	Pass with known gaps	output/playwright/browser-companion-toolbar-3333/run-secure-default-live-smoke.mjs proves content-script extraction, MV3 service-worker no-Origin handling, token bootstrap during save, background save through chrome.runtime.sendMessage, and /api/memory/frames imported-frame confirmation. run-popup-button-click-live-smoke.mjs proves popup Tab order, visible Save selection focus, Enter-to-save selection, Save page click, frame creation through the secure sidecar path with an active-tab shim, /api/memory/search source: import, rendered /memory visibility with the imported provenance chip when WAGGLE_T19_WEB_URL is supplied, and a restricted-page popup state with non-primary disabled styling plus normal-webpage recovery copy. run-packaged-id-pairing-smoke.mjs proves stable extension-ID sidecar pairing. orchestrator-recall-hardening.test.ts proves existing chat auto_recall/catch-up imported provenance. Native toolbar-bubble exposure, native context-menu click proof, signed release-package proof if scored, and any future scored recall result shape remain open.

Open UX risks:

ID	Risk	Evidence	Why it matters
EXT-1	Browser Companion is user-facing and must stay in the judge/evidence packet.	apps/browser-ext/README.md presents it as a workflow surface for researcher/journalist/marketer/writer users. T19 now records loaded-extension and popup save evidence, but native toolbar/context proof remains open.	A complete UX claim should not omit a capture surface that feeds the memory moat.
EXT-2	Connected/disconnected/CORS-denied states are only partly visually proved.	Disconnected and connected-tab screenshots exist; focused code maps setup denial to recovery copy. Live CORS-denied screenshot is still optional evidence.	The first user experience is likely "why is this not connected?" if the sidecar or extension ID is not configured.
EXT-3	Save-to-memory success is end-to-end verified for the background path and direct popup keyboard/click path, but not the native toolbar bubble.	Secure-default smoke saves extracted selected text and confirms /api/memory/frames; popup smoke tabs through the action order, saves selection via Enter, clicks Save page, and confirms both frames. Playwright still cannot observe the native toolbar popup as a page.	The extension's core promise is a memory ingestion path, but final release evidence still needs native toolbar-bubble proof or a deliberate deferral.
EXT-4	Popup accessibility and polish are partly fixed but not fully reviewed.	Toast now has role="status"/aria-live; restricted-page and setup errors are sticky; keyboard Tab order, focus ring, Enter-to-save behavior, and restricted-page disabled styling have live evidence.	A small popup can still fail status announcement if that behavior is scored without a screen-reader proof pass.
EXT-5	Coverage Compass claimed browser extensions were covered before native toolbar/context behavior was proved.	CoverageCompassCard.tsx now marks Browser AI extensions as partial and names the popup/capture coverage plus the pending native entry points; secure save-flow smoke exists, but native toolbar-bubble and native context-menu evidence remain open.	Fixed 2026-07-10; keep the partial state until native entry-point proof or an explicit score deferral exists.
EXT-6	Disconnected/restricted-page states needed stronger copy and accessibility.	T19 now has sticky setup/restricted recovery, explicit normal-webpage copy, non-primary disabled styling, and honest memory-destination copy. Live CORS-denied screenshot remains optional if scored.	First-run extension failure should feel recoverable and accessible, not like a dead popup.

Recommended ticket: T19, Browser Companion Extension UX Gate.

Suggested acceptance:

• Load the unpacked extension in Chromium/Chrome with a fresh sidecar and extension origin allowlist.
• Verify popup connected and disconnected states.
• Verify save selected text and save whole page popup interactions show visible extension feedback and create Memory frames in Waggle; native toolbar-bubble proof can be manual if Playwright cannot expose it.
• Verify native context-menu save, or explicitly defer it. The handler itself is regression-covered.
• Verify CORS-denied recovery copy tells the user how to configure WAGGLE_BROWSER_EXT_IDS or the dev escape hatch.
• Verify status copy and screen-reader announcement behavior if scored separately; popup keyboard/focus basics now have live evidence.
• Verify CoverageCompassCard does not claim browser-extension coverage beyond current evidence.
• Add automated smoke evidence or explicitly defer the extension from the five-persona score.

Desktop Wrapper, Installer, Tray, Update: app/

User jobs:

• Install the app.
• Launch the app and see the web cockpit with the local service ready.
• Close to tray and re-open.
• Use tray actions for open, pause agents, settings, about, and quit.
• Use global shortcut behavior.
• Recover if the sidecar is unhealthy or port 3333 is occupied.
• Receive updates when the update channel is intentionally supported.

Current strengths:

• Tauri config points the desktop binary at apps/web/dist and includes bundle resources, NSIS configuration, window sizing, CSP, and tray metadata.
• Release and PR workflows stage sidecar dependencies, native dependencies, and Node runtime before Tauri build.
• Static tests cover updater config, signing helpers, installer config helpers, runtime bundling helpers, and API-level startup/chat/workspace flows.
• scripts/check-sidecar-resources.mjs fails loudly if packaged sidecar runtime artifacts are missing.

Current command evidence, 2026-07-08 continuation:

Check	Result	Interpretation
npx tsc --noEmit --project app/tsconfig.json	Pass	Desktop wrapper TypeScript scripts/config compile.
npx vitest run app/tests/auto-update.test.ts app/scripts/installer-config.test.ts app/scripts/signing-config.test.ts app/scripts/bundle-runtimes.test.ts	Pass, 4 files / 85 tests	Static updater, installer, signing, and runtime-bundling helper checks are healthy.
npx vitest run packages/server/tests/tauri-config.test.ts app/tests/auto-update.test.ts	Pass, 2 files / 30 tests	Static Tauri config and update-emitter expectations are healthy.
node scripts/check-sidecar-resources.mjs	Pass	Staged Node runtime, native deps, and sidecar node_modules are present locally.
cargo check --manifest-path app/src-tauri/Cargo.toml	Pass	Tauri Rust shell compiles in dev profile.
npm run test -- tauri-bindings.test.ts adapter.tauri-branch.test.ts --reporter=dot from apps/web	Pass, 2 files / 19 tests	Web-side Tauri command bindings and adapter Tauri branch tests pass through the correct package-local command.
npm run test -w apps/web -- src/lib/tauri-bindings.test.ts --reporter=dot	Pass, 1 file / 15 tests	Focused desktop navigation binding test covers /settings allowlist and unsupported payload filtering.
npx vitest run app/tests/e2e/startup.test.ts app/tests/e2e/chat.test.ts app/tests/e2e/workspaces.test.ts	Pass, 3 files / 11 tests	Local service startup, health, settings persistence, chat SSE, workspace/session, and memory-scope API flows work in the Vitest harness.

Native event consumer matrix:

Native event / behavior	Source	Current React consumer evidence	UX reading
Tray icon click / Open Waggle	tray.rs handles show/focus directly	Native-handled; no React consumer needed	Source-wired, but still needs packaged smoke evidence.
Close window to tray	lib.rs prevents close and hides the window	Native-handled; no React consumer needed	Source-wired, but still needs target-OS smoke evidence.
Ctrl+Shift+W global shortcut	lib.rs toggles window visibility directly	Native-handled; no React consumer needed	Source-wired, but still needs target-OS smoke evidence.
Tray Settings	tray.rs emits waggle://navigate to /settings after show/focus	App.tsx mounts TauriDesktopEventBridge; tauri-bindings.ts accepts only /settings	Source-wired, but still needs packaged smoke evidence.
Pause Agents tray action	tray.rs	Menu item and emitter removed	Hidden until pause/resume has real product behavior.
About Waggle tray action	tray.rs	Menu item and /about emitter removed	Hidden until there is a real About destination.
Tray Quit	tray.rs calls app.exit(0)	Native-handled; no React consumer needed	Source-wired to Tauri exit cleanup, but still needs packaged smoke evidence.
waggle://update-available	lib.rs emit	0 matching apps/web/src listeners; covered only as future-emitter static test	Update availability is not user-visible.
waggle://service-status	service.rs emit	0 matching apps/web/src listeners	Failed/restarting service state may not be visible.
waggle://service-restart-needed	service.rs emit	0 matching apps/web/src listeners	Restart-needed state may not guide the user.

Open UX risks:

ID	Risk	Evidence	Why it matters
DESK-1	Update/service events still have emitters but no current frontend consumers.	Tray route false affordances are narrowed: Settings has a /settings bridge, Quit is native, and Pause/About are hidden. Remaining unconsumed events are waggle://update-available, waggle://service-status, and waggle://service-restart-needed.	Update availability and service recovery may not be visible enough in the installed app.
DESK-2	Auto-update UX is intentionally disabled/unfinished for v1.	auto-update.test.ts says updater plugin config is intentionally disabled; release.yml says former update manifest published empty signatures; Rust still checks and emits waggle://update-available for future consumers.	Users need either a working update flow or no misleading update UX surface.
DESK-3	Installed-app interaction evidence is missing.	Current app tests start the Fastify service through Vitest, inspect static config, and now pass sidecar resource preflight. Open/focus, close-to-tray, and Ctrl+Shift+W are source-wired natively, but this packet did not run a packaged Tauri app, tray menu, global hotkey, installer, or close-to-tray smoke.	API tests and source inspection do not prove install, launch, tray, window, or WebView recovery UX.
DESK-4	Sidecar failure and port-conflict recovery are not proven visually.	startService() has port-availability errors and watchdog events, but no current packet evidence shows the user-facing UI for service failure/restart-needed states.	A failed local service is a first-run blocker; the app should tell the user what happened and how to recover.
DESK-5	Signing/notarization and update-channel trust are release gates, not product-screen tests.	Code-signing docs still describe pilot self-sign vs public cert procurement; release workflow builds draft assets but does not prove trusted install/update UX in this audit packet.	Installer warnings and untrusted binaries are UX for real first-time users.
DESK-6	Web-side Tauri binding tests are package-local, not root-discoverable.	Root Vitest excludes apps/**; the correct command from apps/web passes.	Final verification docs must use the right command, or root verification will look falsely missing.

Recommended ticket: T14, Desktop Wrapper and Release UX Gate.

Suggested acceptance:

• Packaged app launches on a clean data dir and reaches a healthy Home or clear service-recovery screen.
• Tray open/settings/about/quit/pause actions are verified or disabled until wired.
• Close-to-tray and global shortcut behavior are verified on the target OS lane.
• Sidecar port-conflict and sidecar-crash recovery have user-facing evidence.
• Update UX is either wired end to end with signed updater artifacts or explicitly hidden/deferred.
• Installer/signing warnings are documented for the target release channel.

Active Local Service Path

The active installed-app sidecar path is not sidecar/src/main.ts. The Tauri wrapper builds packages/server/src/local/service.ts into app/src-tauri/resources/service.js through scripts/build-sidecar.mjs, stages external dependencies with scripts/stage-sidecar-deps.mjs, and launches that service from app/src-tauri/src/service.rs.

Implication:

• Judge the packages/server/src/local/service.ts startup path for installed desktop UX.
• Treat the top-level sidecar/ JSON-RPC code as legacy or separate tooling unless a current launch path imports it.

Open service UX requirements:

• Startup progress should be visible or the first rendered app should clearly recover while the service comes up.
• Port conflict should produce a user-facing recovery path.
• Pending data erasure should surface a receipt/instruction after restart.
• Health should distinguish ok, degraded, and unavailable in user language.

Admin Web, CLI, Marketplace CLI, and MCP Utilities

User jobs:

• Use packages/admin-web to review team dashboard, analytics, members, capability policies, jobs, audit, and team settings.
• Use packages/launcher as the npx waggle entry point.
• Use packages/cli for command-line Waggle workflows.
• Use packages/marketplace CLI for package search, install, sync, scan, and audit jobs.
• Use packages/memory-mcp, packages/hive-mind-mcp-server, and packages/hive-mind-cli for memory/MCP setup, recall, harvest, maintenance, and machine-readable JSON output.

Dedicated supplement: docs/audits/2026-07-08-admin-cli-utility-t15-analysis.md.

Current command evidence, 2026-07-08 continuation:

Check	Result	Interpretation
Targeted root/package Vitest slices	Mixed	Admin-web, launcher package-local tests, @waggle/cli package-local tests, memory MCP package-local tests, hive-mind MCP, marketplace targeted tests, and hive-mind CLI package-local tests pass. Remaining mixed status is from rendered/admin and deeper state evidence, not this test command lane.
No-emit TypeScript	Pass	Admin web, Waggle CLI, marketplace, memory MCP, hive-mind MCP, and hive-mind CLI compile. packages/launcher has no local tsconfig.json and relies on tsup.
Package builds	Pass	Admin web, launcher, Waggle CLI, marketplace, memory MCP, hive-mind MCP, and hive-mind CLI build scripts completed.
Source help smokes	Pass	Launcher, Waggle CLI, hive-mind CLI, and marketplace help paths work through tsx.
Built help/runtime smokes	Mixed	Built marketplace help works with no DB side effect; built @waggle/cli help and bin-wrapper help work with no .waggle side effect; built launcher help works without a service banner or .waggle creation.
MCP protocol smoke	Improved mixed	Built hive-mind MCP server and built legacy waggle-memory-mcp both complete official MCP client handshakes and write-scope save/recall roundtrips from temp data dirs. Package-publish proof remains open.
Negative-path smokes	Improved mixed	Marketplace unknown commands now print help, exit 1, and avoid DB creation; hive-mind CLI sampled subcommand help now prints focused help and avoids personal.mind creation. Broader package/publish and every-subcommand sampling remain open.

Open utility UX risks:

ID	Risk	Evidence	Why it matters
UTIL-1	Admin web is a separate Vite UI with shallow rendered UX evidence.	packages/admin-web/src/App.tsx uses its own inline-styled sidebar, token/slug setup, and pages. Component tests pass but emit repeated act(...) warnings; no current screenshot, mobile, keyboard, or visual-guideline evidence is attached.	Team admins can hit this outside the cockpit; it needs either a judge pass or explicit deferral.
UTIL-2	Built/published-style CLI/MCP entries are locally healthier but still not publish-proved.	Built marketplace help/invalid-command paths, built launcher help, built @waggle/cli help, built legacy waggle-memory-mcp read/write handshakes, and built hive-mind MCP write roundtrip are locally fixed; clean npm tarball/npx invocation remains unproved for the locally fixed CLIs/MCP packages.	A source-mode dev smoke can pass while the command a user installs or runs via npx is unusable.
UTIL-3	Hive-mind CLI tests are present outside the root Vitest include pattern, with a package-owned test lane now added.	Root-focused commands against packages/hive-mind-cli/src/*.test.ts returned "No test files found"; npm run test --workspace @waggle/hive-mind-cli -- --reporter=dot now runs 5 files / 45 tests through the package-local config.	Root verification can still miss this package unless the documented package command is included.
UTIL-4	Launcher CLI has clean help smoke and argument tests, but no no-emit TypeScript path and no full startup/failure UX smoke in this packet.	packages/launcher has tsup.config.ts but no tsconfig.json; launcher tests copy argument parsing shape and do not start the service; built help no longer logs service data-dir information before help.	First-run npx waggle is a real acquisition path; port conflict, service failure, and browser-open behavior need evidence or deferral.
UTIL-5	Utility negative paths need broader sampling, though marketplace and sampled hive-mind CLI paths are now guarded.	Marketplace unknown commands now exit 1 without DB construction; sampled hive-mind CLI source/built subcommand help exits 0 without personal.mind creation. Other utility invalid-input, JSON, missing-env, and publish-style paths are not fully sampled.	Help and invalid-input paths should be safe, obvious, and scriptable.
UTIL-6	CLI/MCP utility UX remains incomplete beyond the successful MCP protocol smokes.	Memory MCP and hive-mind MCP read/write protocol smokes pass, but JSON output, invalid args, missing env, bad data dir, auth failure states, and clean npm tarball behavior are not fully sampled.	Engineer and admin personas may rely on these tools when desktop UI is unavailable or during setup.

Recommended ticket: T15, Admin and CLI Utility UX Gate.

Suggested acceptance:

• Admin web has screenshot/keyboard/mobile evidence or is explicitly deferred from the product UX score.
• Root test discovery includes or deliberately excludes hive-mind CLI colocated tests, with the passing package-local command kept in the verification lane.
• Launcher CLI has startup, invalid port, port conflict, --no-open, and failure copy evidence, or is deferred.
• Marketplace/memory MCP/hive-mind CLI commands have help, invalid input, JSON output, and missing-env/error-state evidence for the supported user paths.

AI-Tool Hook Lifecycle: packages/hive-mind-hooks-* and Launcher

User jobs:

• Detect a supported AI tool.
• Install memory hooks without corrupting the tool's existing configuration.
• Verify installed hooks and understand failures.
• Uninstall hooks byte-identically or remove only Waggle-managed config.
• Understand that Claude Desktop is launchable but not hook-capable.
• Trust hook events to fail open when hive-mind CLI or the sidecar is unavailable.

Current command evidence, 2026-07-08 continuation:

Check	Result	Interpretation
Shared/agent/server T16 route-contract plus package-runtime slice	Pass, original 7 files / 96 tests plus focused registry slice 5 files / 108 tests	Manifest, third-party loader, hook-capable cohort, backend hook route, launch, process, detection route contracts, packed local hook-package lifecycle, and registry-aware third-party launch agree.
Launcher/prompt/adapter slice	Pass, 3 files / 28 tests	Launcher A/B toggle, one non-Claude hook action exposure, live output pane wiring, prompt args, and adapter methods pass. Node emits punycode warnings.
Root-run hook and shim package tests	Pass, 60 files / 573 tests, 1 skipped	Hook install/verify/uninstall, config merge/unmerge, adapters, lifecycle handlers, fail-open behavior, Codex Desktop parity, hook core, and shim core are well-covered at unit/package level. Output includes expected fail-open warnings and sidecar-unreachable signal drops.
Official hook/shim package typechecks	Pass, 8/8	hive-mind-shim-core, hive-mind-hooks-core, and the six real hook packages pass their tsc --build && tsc --noEmit -p tsconfig.test.json lanes.
npm run build --workspace @waggle/hive-mind-hooks-claude-desktop	Pass	The intentional Claude Desktop no-bin stub still builds.
Compiled hook-bin help smokes	Pass, 6/6	claude-code-hooks, codex-hooks, codex-desktop-hooks, cursor-hooks, hermes-hooks, and openclaw-hooks boot locally and show usage. This does not prove published npx resolution.
Rendered Launcher Browser smoke	Pass, partial	Fresh npm run build plus in-app Browser evidence under output/playwright/launcher-t16-54147/ covers mixed installed/not-installed/hooks-active/running/Phase 4 states, prompt summary, install success, verify failure, and running output against a mock local API.
Rendered Launcher Playwright states	Pass, 1 file / 4 tests	Production-build Playwright coverage proves sidecar-offline Retry recovery, long hook stderr summarization with More output, hidden-line count, and recovery guidance, standard install output with Changed file, Install pointer, Backup, and Recovery labels, and non-built-in adapter launch-only/prompt behavior.
Package-local hook/shim npm run test --workspace ... scripts	Pass, 60 files / 574 tests	Hook core, all six hook-capable packages, and shim core now run package-local scripts against the intended root Vitest config/package paths. The shim lane also verifies the CLI ESM resolver fix for the MCP server entry.
Focused Launcher/web regressions	Pass, 5 files / 72 tests	Observed output closes after exit, covered install output shows Backup/Recovery labels without raw stdout:, Verify [FAIL] output becomes Check-failed/manual-approval rows without raw [FAIL], uninstall output labels restore/cleanup rows without implying install state, long hook output is capped behind a More output summary, hook stdout/stderr details are preserved, structured hook failures are not replaced with HTTP 400, empty-output Verify failures show retry/uninstall/reinstall recovery copy, installed Claude Desktop is explicitly launch-only with no hook actions, and a detected launchable third-party adapter gets Launch plus prompt routing.

Open hook UX risks:

ID	Risk	Evidence	Why it matters
HOOK-1	Real hook-management lifecycle is now proved for all six hook-capable route paths and rendered UI transitions; packaged-desktop evidence remains open.	The gated real-tool smoke now proves a detected OpenClaw CLI can render in Launcher and launch safely through /api/tools/launch with observed output, exit 0, and process cleanup. A broadened gated route smoke drives /api/tools/hooks through real install, verify, and uninstall for claude-code, codex, codex-desktop, cursor, hermes, and openclaw against an isolated USERPROFILE/HOME, proving config/pointer creation and cleanup without touching the user's real profile. A codified rendered Playwright spec covers all six hook-capable cards through install, verify, uninstall, and refreshed hooks-active UI transitions. No current evidence proves packaged desktop hook-status transitions.	Hook install modifies user tool config, so reversibility and status copy are trust-critical.
HOOK-2	Rendered Launcher hook-management states are codified across the all-tool matrix; screenshot breadth remains partial.	The Browser smokes cover detected, not detected, hooks active, install success, verify failure, mocked uninstall cleanup, running output, and Phase 4/unsupported states. Codified Playwright coverage now covers sidecar offline Retry, long-stderr summarization, standard install changed-file/pointer/backup/recovery labels, all six hook-capable tool cards rendering install/verify/uninstall transitions, non-built-in adapter launch-only/prompt behavior, one real detected CLI observed-launch lifecycle, and real route lifecycle for all six hook-capable tools.	Engineer and Solo founder judges need to understand what happened without reading logs.
HOOK-3	Focused fixed: Claude Desktop is a deliberate unsupported hook case.	BUILTIN_TOOL_MANIFESTS marks claude-desktop as non-hook-capable; packages/hive-mind-hooks-claude-desktop is a stub/no-bin package. The Launcher now shows installed Claude Desktop as Launch only, explains hooks are not supported yet, and hides hook actions; component coverage owns the regression and a Browser-rendered mocked state confirmed the visible layout.	Keep the copy in the rendered state matrix; no hook package/bin should be exposed for Claude Desktop until the MCP-bridge category ships.
HOOK-4	Local fixed: production-shaped npx hook package resolution is proved for the local package closure.	hook-packages-runtime.test.ts packs and installs the local hook package closure into a clean temp project, then runs npx --yes @waggle/hive-mind-hooks-<id> install/verify/uninstall for all six hook-capable tools. Registry-only proof remains a publication/release check.	A user click in Launcher depends on npx --yes @waggle/hive-mind-hooks-<id>.
HOOK-5	Rendered fixed; release residual: hook success/failure copy preserves stdout/stderr/structured-failure details, shows Backup/Recovery labels for covered install output, turns Verify [FAIL] output into Check-failed/manual-approval rows, labels uninstall restore/cleanup rows, caps long output behind More output, gives empty-output recovery copy, exposes offline retry, and has real route plus rendered lifecycle proof for all six hook-capable tools.	Component tests now prove install success shows a Backup label and backup path without raw stdout:, verify failure shows stderr even when the route returns a generic error, Verify check failure shows manual-approval detail without raw [FAIL], uninstall output shows Changed file, Restored from, Created file removed, Backup removed, and Pointer removed without Install pointer, long stderr hides later noisy lines behind a count while preserving Recovery, and empty-output Verify failure shows retry/uninstall/reinstall guidance. Adapter tests now prove a structured hook failure with no stderr/error is not replaced with HTTP 400. Browser evidence shows mocked Codex Verify manual-approval and Uninstall cleanup results plus a real /launcher smoke renders verify failed (exit 1) with recovery guidance instead of HTTP 400. Playwright rendered evidence covers standard install changed-file/pointer/backup/recovery labels, sidecar-offline Retry, long-output summarization, all six hook-capable rendered install/verify/uninstall transitions, real OpenClaw observed launch/output/exit/process cleanup, and real route install/verify/uninstall for all six hook-capable tools against an isolated profile.	Users still need packaged desktop hook-status proof and quieter release output for config-editing flows.
HOOK-11	Focused fixed: Windows hook route commands now resolve npx correctly.	The first gated route smoke reproduced /api/tools/hooks returning HTTP 400 with empty stdout/stderr because Windows execFile('npx') could not resolve the npm shim. runHookCommand() now prefers the npx.cmd beside process.execPath, and default exec capture uses the shared .cmd resolver. The broadened isolated route lifecycle now passes for all six hook-capable tools.	Keep the gated route smoke in the release lane.
HOOK-10	Focused fixed: Windows npm shims can launch, and restricted Codex WindowsApps aliases show recovery instead of a failing launch path.	Detection now prefers spawnable Windows PATH hits such as .cmd over extensionless POSIX npm shims. Standard npm .cmd shims resolve to their Node module target so prompt args stay literal; unknown .cmd/.bat files use a quoted fallback. The real smoke passed against OpenClaw. Built detection now reports this host's Codex WindowsApps codex.exe as installed but launchable: false with recovery copy, and Launcher hides the Launch button for that state.	Windows users should not see a launchable tool that crashes the sidecar. Keep the regression and require a real PATH CLI or proven desktop bridge for future direct Codex launch.
HOOK-6	Focused/rendered fixed for launchable third-party adapters.	Detection merges ~/.waggle/adapters/*.json; /api/tools/launch now validates against the runtime registry and applies adapter prompt templates, while /api/tools/hooks stays built-in-only until a safe hook policy exists. Rendered Playwright coverage proves a non-built-in adapter shows launch-only/no-hook copy, routes the prompt, and sends the expected launch payload.	Advanced adapter users can launch a detected launchable adapter; third-party hook management remains intentionally disabled until a safe hook policy exists.
HOOK-7	Standard output is noisy during successful hook tests.	Passing test output includes fail-open warnings, sidecar-unreachable signal drops, package logs, and server embedding warnings.	Noise can hide real failures and reduce confidence in release checks.
HOOK-8	Local fixed: package-local hook test commands now run their intended lanes.	Package-local hook/shim npm run test --workspace ... scripts pass for hook core, all six hook-capable packages, and shim core.	Keep these scripts in the release lane; remaining package-local command-shape gaps are tracked under DEV-1.
HOOK-9	Focused fixed: observed live output does not reconnect and replay after exit.	streamToolOutput() now closes its EventSource on a valid exit event. The focused web Launcher/adapter suite proves no reconnect/replay after exit.	Keep the regression; refresh rendered Browser evidence when the full Launcher state matrix is rerun.

Recommended ticket: T16, AI-Tool Hook Lifecycle UX Gate.

Suggested acceptance:

• Rendered Launcher screenshots or Browser/Playwright evidence cover hook install/verify/uninstall states across all six hook-capable tools, duplicate-free running output, and unsupported Claude Desktop copy.
• Command-level lifecycle evidence covers all six hook-capable tools.
• Real detected CLI launch has at least one observed safe smoke; hook install/verify/uninstall has isolated route lifecycle evidence for all six hook-capable tools.
• Packaged desktop hook-status transitions are proved or explicitly deferred.
• Production-like npx or package-pack resolution is verified for every hook package Launcher can invoke.
• Third-party adapter launch has focused route/UI proof and rendered non-built-in adapter proof; third-party hook management stays out of scope until a safe hook policy exists.
• Hook test/log output is quiet enough that real failures stand out, or expected warning noise is explicitly filtered/documented.
• Typecheck/build commands for project-reference hook packages are documented and pass in the approved verification lane.

Focused supplement: docs/audits/2026-07-08-ai-tool-hook-t16-analysis.md.

Developer APIs, Background Jobs, and Substrate Packages

Dedicated supplement: docs/audits/2026-07-08-developer-substrate-t17-analysis.md.

User jobs:

• Use @waggle/sdk to validate, install, and run skills/plugins.
• Rely on local server APIs for chat, workspaces, marketplace, billing, backup, compliance, hooks, and startup recovery.
• Trust background worker jobs for dispatch, chat handling, and job processing.
• Trust WaggleDance protocol behavior and signal handling.
• Trust memory substrate, wiki compiler, optimizer, and shared package behavior that powers the UI.
• Run documented package-local and root verification commands without false failures or hidden skipped tests.

Current command evidence, 2026-07-08 continuation:

Check	Result	Interpretation
npx tsc --noEmit --project packages/<target>/tsconfig.json for agent, core, hive-mind-core, hive-mind-shim-core, hive-mind-wiki-compiler, optimizer, sdk, server, shared, waggle-dance, weaver, wiki-compiler, and worker	Pass, 13/13 workspaces	Remaining developer/backend/substrate workspaces compile under direct no-emit TypeScript.
npm run test -w @waggle/agent	Pass, 194 files / 3079 tests	Agent runtime, connectors, tool launcher, orchestration, memory recall, personas, security, and workflow behavior are broadly covered.
npm run test -w @waggle/core -- --reporter=dot	Pass, 19 files / 295 tests	Core config, cron/file stores, compliance, vault-adjacent helpers, and quota behavior pass; output includes embedding provider probing noise.
npm run test -w @waggle/optimizer -- --reporter=dot and npm run test -w @waggle/weaver -- --reporter=dot	Pass, 4 files / 52 tests	Optimizer and Weaver unit behavior pass through package scripts.
npx vitest run packages/hive-mind-core/tests packages/hive-mind-shim-core/tests packages/wiki-compiler/tests --config vitest.config.ts --reporter=dot	Pass, 71 files / 875 tests	Memory substrate, shim core, and wiki compiler tests pass through the root runner.
npx vitest run packages/sdk/tests --config vitest.config.ts --reporter=dot	Pass, 5 files / 88 tests	SDK behavior tests pass through the root runner.
npx vitest run packages/shared/tests packages/waggle-dance/tests packages/worker/tests packages/hive-mind-wiki-compiler/src --config vitest.config.ts --reporter=dot	Pass, 12 files / 128 tests	Shared contracts, WaggleDance protocol, worker jobs, and hive-mind wiki compiler tests pass through the root runner.
npx vitest run packages/server/tests --config vitest.config.ts --reporter=dot	Pass, 184 files passed / 1 skipped; 2117 tests passed / 1 skipped	Current full server run passed, but took 98.34s and emitted very large marketplace/embedding/startup logs. Earlier packet evidence saw one performance-budget failure under full-suite load.
npx vitest run packages/server/tests/performance/benchmarks.test.ts --config vitest.config.ts --reporter=default	Pass, 13 tests	The same benchmark passes in isolation, so the risk is full-suite stability/contention and audit determinism, not a consistently broken endpoint.
npm run test -w @waggle/hive-mind-core and @waggle/wiki-compiler	Fail	Package-local Vitest tries to load vitest.setup.ts relative to the package cwd; root-run tests pass. @waggle/hive-mind-shim-core now passes package-local tests.
npm run test -w @waggle/sdk	Fail	Workspace-local Vitest resolves into packages/sdk/node_modules and cannot find convert-source-map; root-run SDK tests pass.

Open developer/substrate UX risks:

ID	Risk	Evidence	Why it matters
DEV-1	Several package-local npm test scripts fail even when the same tests pass from the root runner.	hive-mind-core and wiki-compiler fail on missing package-local vitest.setup.ts; SDK fails on missing local convert-source-map. hive-mind-shim-core is now fixed.	Engineers following package scripts hit false failures, slowing fixes and reducing trust in the verification lane.
DEV-2	The full server route suite is green in the current run but not release-clean.	Current full server run passed, but took 98.34s and emitted very large logs; earlier packet evidence saw one perf-budget failure at 841ms vs 500ms while isolated benchmark passed.	A release-quality UX gate needs deterministic, quiet command evidence with perf checks in a stable lane.
DEV-2a	Marketplace sync behavior leaks into the normal server lane.	marketplace-sync.test.ts logs many source sync attempts, add counts, and error counts during the full server run.	The default release lane should be hermetic and quiet; live/external catalog behavior belongs in a named integration lane.
DEV-3	Server and substrate verification output is very noisy.	Passing runs emit repeated embedding fallback warnings, marketplace sync logs, sidecar-unreachable-style warnings, and route startup logs.	Noise makes real failures harder to spot and weakens confidence in "all tested."
DEV-4	Developer-facing SDK/server/worker happy paths are tested, but user-facing recovery/error copy is not fully sampled.	Unit/API tests pass; no current packet evidence covers SDK docs/examples, server API consumer ergonomics, worker job failure UI copy, or bad config paths as a coherent user journey.	Engineer and admin personas depend on these APIs when integrating, debugging, or recovering from failed jobs.

Recommended ticket: T17, Developer API, Background Worker, and Substrate Verification UX Gate.

Suggested acceptance:

• Package-local scripts either pass or clearly delegate to the correct root/project-reference verification command.
• Root verification discovers all intended package tests or explicitly documents separate lanes.
• Full server route/performance gate is deterministic, with realistic budgets or isolated perf lanes.
• Noisy logs are reduced, filtered, or documented so real failures stand out.
• SDK/server/worker developer journeys have happy-path and error-path evidence, or are explicitly deferred from the five-persona score.

Ops, Deployment, CI, Benchmarks, and Judging

Dedicated supplement: docs/audits/2026-07-08-ops-deploy-ci-judging-t18-analysis.md.

User jobs:

• Release reviewers trust GitHub Actions, Docker, Render, and local Compose as honest shipping gates.
• Operators can validate deployment configuration without leaking local secrets into logs.
• Hosted deploy target is coherent: local sidecar demo versus team Postgres server is an explicit decision.
• Infra-dependent suites have a known, runnable lane.
• Benchmark and judge harnesses used for product claims compile and test through documented commands.
• Historical judging screenshots/reports are not mistaken for current five-persona score evidence.

Current command evidence, 2026-07-08 continuation:

Check	Result	Interpretation
YAML parse for docker-compose.yml, docker-compose.production.yml, render.yaml, litellm-config.yaml, and all 7 .github/workflows/*.yml	Pass	The deployment, LiteLLM, and workflow YAML files are syntactically valid.
docker --version	Pass	Docker is available in this environment for config-level checks.
docker compose ps --format json	Fail	Docker CLI is installed, but the Docker Desktop Linux engine pipe is not reachable, so live Compose services and npm run test:infra could not be run here.
docker compose -f docker-compose.yml config and docker compose -f docker-compose.production.yml config	Pass with secret-log caveat	Compose can expand both files, but raw expansion reads local env values and can print secret values. Use --no-interpolate or a sanitized env for shareable logs.
docker compose -f docker-compose*.yml config --no-interpolate targeted scan	Pass	The non-interpolated command is safer for evidence because it keeps variable references instead of local secret values.
git ls-files / git check-ignore for .env, env.local, AI API KEYS.txt, and apps/www/.env.local	Pass for tracking hygiene	Only .env.example files are tracked; local secret-bearing files checked here are ignored.
npx tsc --noEmit --project benchmarks/harness/tsconfig.json	Pass	Benchmark harness TypeScript compiles.
npm run test --prefix benchmarks/harness	Fail	Package-local Vitest tries to load benchmarks/harness/vitest.setup.ts; root-run tests pass.
npx vitest run benchmarks/harness/tests --config vitest.config.ts --reporter=dot	Pass, 29 files / 325 tests	Benchmark harness unit/smoke/stats/judge tests pass through the root runner, with noisy turn/bench logs.
judging/ inventory	Historical only	Current files are prior June 2026 rounds/screenshots, not the requested July five-persona scorecards.

Open ops/judging risks:

ID	Risk	Evidence	Why it matters
OPS-1	Shareable Compose validation can leak local secrets if run in the obvious way.	docker compose config expands local ignored .env values; ignored-file checks show those values are not tracked, but command output can still expose them.	Release/ops evidence must be secret-safe; logs are part of the UX of operating the system.
OPS-2	Render deployment target is still ambiguous.	render.yaml provisions Postgres and Redis but starts packages/server/src/local/start.ts --skip-litellm, the local SQLite sidecar path, not the team Postgres server.	A hosted deploy should either be a local-sidecar demo or a team server; mixed infra confuses operators and can hide broken team workflows.
OPS-3	CI E2E remains advisory and infra tests are not in CI; local live infra could not be run in this environment.	ci.yml marks the E2E job continue-on-error: true; no workflow starts Postgres/Redis or runs npm run test:infra; vitest.infra-suites.ts lists 19 suites that require live infra; local docker compose ps failed because the Docker Desktop engine pipe was missing.	Green CI can still miss route, browser, and Postgres/Redis regressions, and this packet only proves config-level Docker validity.
OPS-4	Production Compose uses development-style default credentials unless explicitly overridden.	docker-compose.production.yml has fallback values for Postgres and MinIO credentials.	Defaults are convenient locally, but production operators need fail-closed secret requirements or prominent warning evidence.
OPS-5	Benchmark harness package-local test script fails even though root-run tests pass.	npm run test --prefix benchmarks/harness fails on missing local setup file; root-run benchmark tests pass.	Benchmark/judge credibility depends on commands that future reviewers can run without knowing hidden root-run shape.
OPS-6	Existing judging/ artifacts are stale for the current goal.	judging/round2, round3, screenshots, and crops are June 2026 artifacts; current scorecards are not filled.	The requested 9/10 result must be generated from current source after fixes, not inherited from older screenshots.

Recommended ticket: T18, Ops, Deployment, CI, Benchmark, and Judging Evidence Gate.

Suggested acceptance:

• Secret-safe ops validation commands are documented and used for shareable evidence.
• Render target is decided and verified: hosted local-sidecar demo or team Postgres server.
• Docker/Compose production path is built or explicitly deferred, with fail-closed secret expectations.
• CI has a blocking smoke lane or the advisory E2E/infra gap is explicitly accepted before scoring.
• npm run test:infra has a documented Docker/migration lane and evidence, or is deferred.
• Benchmark harness package-local command shape is fixed or documented; root-run benchmark evidence remains green.
• Five-persona judging artifacts are generated from current post-fix source and replace historical screenshots for scoring.

Phase Placement

Phase 1 remains unchanged and should stay focused on the installed app P0s:

• T1 auth/CSP/accountless console health.
• T2 mobile Settings.
• T3 Solo/Teams/Enterprise copy in active app UI.
• T4 shortcut and Workspace Switcher route contract.
• T5 visual snapshot triage.
• T11 route evidence for thin in-app routes.

T13, T14, T15, T16, T17, T18, and T19 are not part of Phase 1 unless a Phase 1 verification command directly forces a tiny supporting fix. They are final-product gates after the in-app blockers are cleared.

Final Goal Rule

Do not claim "complete UX" until:

• T13, T14, T15, T16, T17, T18, and T19 are fixed and verified, or
• the user explicitly approves deferring launch/extension/desktop/utility/hook/developer/ops gates from the five-persona score.

The approval brief can still request Phase 1 implementation now, because Phase 1 removes known P0s in the main installed cockpit and is the fastest path to a credible judge dry run.