Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mux-extensions-main.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

A reproducible sign-off pass for the Mux Extension Platform. Every step listed below MUST be executed manually against a release build before a v1 release ships, with the evidence below attached to the release PR.
  • Screenshot = a still image of the relevant UI state.
  • Video = a short screen recording covering the full interaction (start to stable end state).
The kill-switch toggle and the Consent Shortcut flow always require video because they exercise multi-step state transitions; everything else is screenshot-only unless noted.

​
Before you start

  • Build the release artifact you intend to ship (Electron + dev-server).
  • Use a clean macOS, Windows, and Linux profile each — the user-global root sits at ~/.mux/extensions/ and prior dogfood runs leak state across runs unless deleted.
  • Have one third-party Extension package available locally for the install / update / drift steps. The bundled Demo Extension is fine as a copy-paste base.

​
Checklist

The order below matches the natural cold-start → install → drift → recovery progression, so a single pass produces a coherent narrative for the release PR.

​
1. Cold start with no user-global root

Goal. Section renders the initialize affordance with no errors.
  • Delete ~/.mux/extensions/.
  • Launch Mux. Open Settings → Extensions.
  • Confirm: header shows zero error and zero warning counts; the user-global subsection shows the Initialize User Extensions Root affordance plus a 2-sentence explanation.
Evidence. Screenshot of the section in this state.

​
2. Cold start with a malformed user-global package.json

Goal. Section surfaces the failure card; the app starts normally.
  • With Mux closed, write malformed JSON to ~/.mux/extensions/package.json (e.g., { "name":).
  • Launch Mux. Open Settings → Extensions.
  • Confirm: user-global subsection header shows a Failed pill plus a Retry button; the rest of the app remains usable.
Evidence. Screenshot of the failed user-global subsection.

​
3. Initialize, install, reload

Goal. Newly-installed Extensions become visible without restart.
  • Click Initialize User Extensions Root in the action row.
  • In a terminal: cd ~/.mux/extensions && bun add <publisher>/<package>.
  • Run Reload Extensions from the command palette.
  • Confirm: the new Extension appears as a card in the user-global subsection.
Evidence. Screenshot before reload (no card) and after reload (card visible).

​
4. Project-local trust ladder

Goal. Pre-trust shows the prerequisite card; granting trust unlocks inspection-only mode.
  • Open a project that contains a .mux/extensions/ directory, with project trust ungranted.
  • Confirm: the project-local subsection shows the project-trust prerequisite card and renders no Extension cards.
  • Grant project trust (the existing Mux project-trust flow).
  • Confirm: Safe Manifest Inspection runs and Extension cards appear in inspection-only mode (no Enable / Grant actions yet).
Evidence. Screenshot of each state (untrusted, trusted + inspection-only). Goal. The one-click Consent Shortcut applies trust + enable + grant in one transaction; Review individually falls through to the granular ladder.
  • Click Quick Setup on a project-local Extension card.
  • In the Consent Shortcut Modal, verify the summary lists: identity, distribution (<package>@<version>), description, and the requested permissions.
  • Confirm Quick Setup. Verify the card reaches Enabled.
  • Repeat the install on a second Extension and click Review individually instead. Verify the granular Trust → Enable → Grant controls become visible on the card and that each step succeeds independently.
Evidence. Video capturing both the shortcut and granular paths end-to-end.

​
6. Drift surfacing on permission update

Goal. Adding a new requested permission shows Pending re-grant without a modal; previously available contributions remain available.
  • Update an installed Extension to add a new entry to requestedPermissions (e.g., bump the package version and add a new operational permission).
  • Run Reload Extensions.
  • Confirm: the card shows a Pending re-grant pill and the Review Pending Extension Permissions action appears in the action row. No modal is shown. Previously available contributions are still marked Available.
Evidence. Screenshot of the card with the Pending re-grant pill.

​
7. Drift surfacing on new contribution type

Goal. Adding a new contribution type triggers Inferred Registration Permission drift; the new contribution stays Unavailable until re-grant.
  • Update the same Extension to add a contribution of a type it did not previously declare (e.g., add a themes entry to a previously skill-only Extension).
  • Run Reload Extensions.
  • Confirm: the card surfaces drift; the new contribution row shows Unavailable until re-grant.
  • Re-grant. Confirm: the new contribution becomes Available.
Evidence. Screenshot of the Unavailable state pre-grant and the Available state post-grant.

​
8. Kill-switch toggle (video)

Goal. Toggling EXTENSION_PLATFORM off cleanly hides the section and stops discovery; toggling back on restores all prior state without re-prompting.
  • In Settings → Experiments, toggle EXTENSION_PLATFORM off.
  • Confirm: the Extensions section disappears from the Settings sidebar; discovery does not run on the next reload (verify via bun run debug extensions returning the previous snapshot, not a fresh one).
  • Toggle EXTENSION_PLATFORM back on.
  • Confirm: the section reappears; all previously trusted roots, enabled Extensions, and granted permissions are intact; no consent shortcut fires.
Evidence. Video covering the off → on round trip.

​
9. Reserved-prefix rejection

Goal. A non-bundled Extension claiming a mux.* identity is rejected with extension.identity.reserved and contributes nothing.
  • Install (user-global or project-local) a third-party Extension whose manifest declares id: "mux.foo".
  • Run Reload Extensions.
  • Confirm: the card surfaces the extension.identity.reserved diagnostic; the contributions table is empty (or every row marked Unavailable); the Extension does not register any capability.
Evidence. Screenshot of the card with the diagnostic visible.

​
10. Debug snapshot capture

Goal. bun run debug extensions produces structured JSON in cold, post-install, and post-failure states; no third-party identifiers leak into telemetry.
  • Run bun run debug extensions (cold), bun run debug extensions (post-install), and bun run debug extensions (post-failure: induce a malformed manifest and re-run).
  • Optionally narrow with --root <rootId>.
  • Spot-check telemetry events captured during the same session (PostHog console, dev tools, or whichever sink is configured): no event payload contains a third-party Extension identifier. The catalog this should be checked against lives at Extension Telemetry.
Evidence. Output capture (text) of each run; brief note confirming the telemetry spot-check.

​
11. Stale Record handling

Goal. Removing an installed Extension from disk leaves its Grant Record visible with explicit Forget and Keep actions.
  • Uninstall an Extension you previously granted (delete from ~/.mux/extensions/node_modules/<package> and remove from ~/.mux/extensions/package.json#dependencies).
  • Run Reload Extensions.
  • Confirm: the section’s Stale Records group shows the prior Extension as Stale (extension not currently installed) with both Forget and Keep actions wired.
Evidence. Screenshot of the Stale Record card.

​
Sign-off

  • All 11 steps above produce the expected evidence with no unexpected diagnostics.
  • The release PR description links to each piece of evidence and notes the OS / build profile each step was captured on.
  • A migration release does not alter this checklist — the EXTENSION*PLATFORM kill switch and MIGRATION*<feature> switches are exercised separately in the migration release’s own checklist.