From 043f5e8616f54208b0e590d787f5a1f1f24d4d29 Mon Sep 17 00:00:00 2001
From: Magaav <magaav@colmeio.com>
Date: Wed, 29 Apr 2026 13:38:58 +0000
Subject: [PATCH 1/2] feature(customware): add customware bundle interface

---
 AGENTS.md                                     |   3 +-
 README.md                                     |   8 +
 app/AGENTS.md                                 |   9 +-
 app/L0/_all/mod/_core/documentation/AGENTS.md |   2 +-
 .../docs/app/customware-bundles.md            | 124 ++++++++++
 .../docs/app/modules-and-extensions.md        |  27 ++-
 .../docs/app/runtime-and-layers.md            |   1 +
 .../docs/server/api/modules-and-runtime.md    |   5 +
 .../server/customware-layers-and-paths.md     |  14 ++
 .../ext/skills/documentation/SKILL.md         |   2 +
 app/L0/_all/mod/_core/framework/AGENTS.md     |  17 +-
 .../_all/mod/_core/framework/js/api-client.js | 112 +++++++++
 app/L0/_all/mod/_core/framework/js/bundles.js | 150 ++++++++++++
 .../_all/mod/_core/framework/js/extensions.js |  18 +-
 app/L0/_all/mod/_core/framework/js/runtime.js |   4 +
 .../skillset/ext/skills/development/AGENTS.md |   4 +-
 .../skillset/ext/skills/development/SKILL.md  |   4 +
 .../development/app-files-apis/SKILL.md       |   1 +
 .../development/backend-reference/SKILL.md    |   3 +-
 .../extensions-components/SKILL.md            |  12 +-
 .../development/frontend-runtime/SKILL.md     |   7 +-
 .../development/layers-ownership/SKILL.md     |   1 +
 app/space-runtime.d.ts                        |  76 ++++++
 server/AGENTS.md                              |   5 +-
 server/api/AGENTS.md                          |   3 +
 server/api/bundle_info.js                     |  67 ++++++
 server/api/bundle_list.js                     |  35 +++
 server/lib/customware/AGENTS.md               |   9 +
 server/lib/customware/bundles.js              | 146 ++++++++++++
 server/lib/customware/module_manage.js        | 151 ++++++++----
 tests/AGENTS.md                               |   4 +
 tests/customware_bundle_test.mjs              | 219 ++++++++++++++++++
 tests/fixtures/AGENTS.md                      |  24 ++
 .../customware_bundle_example/AGENTS.md       |  25 ++
 .../customware_bundle_example/README.md       |  10 +
 .../space.bundle.yaml                         |  18 ++
 36 files changed, 1250 insertions(+), 70 deletions(-)
 create mode 100644 app/L0/_all/mod/_core/documentation/docs/app/customware-bundles.md
 create mode 100644 app/L0/_all/mod/_core/framework/js/bundles.js
 create mode 100644 server/api/bundle_info.js
 create mode 100644 server/api/bundle_list.js
 create mode 100644 server/lib/customware/bundles.js
 create mode 100644 tests/customware_bundle_test.mjs
 create mode 100644 tests/fixtures/AGENTS.md
 create mode 100644 tests/fixtures/customware_bundle_example/AGENTS.md
 create mode 100644 tests/fixtures/customware_bundle_example/README.md
 create mode 100644 tests/fixtures/customware_bundle_example/space.bundle.yaml

diff --git a/AGENTS.md b/AGENTS.md
index 9f334057..fb7a9e26 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -178,7 +178,7 @@ Top-level structure:
 - `commands/`: CLI command modules such as `serve`, `help`, `get`, `set`, `version`, and `update`
 - `app/`: browser runtime, layered customware model, shared frontend modules, and browser test surfaces
 - `server/`: thin local infrastructure runtime, with page shells, request routing, API hosting, fetch proxying, file-watch indexes, auth/session infrastructure, and Git support code
-- `tests/`: repo-level verification harnesses, prepared evaluation fixtures, and saved result artifacts
+- `tests/`: repo-level verification harnesses, prepared evaluation fixtures such as `tests/fixtures/`, and saved result artifacts
 - `packaging/`: optional Electron host and packaging scripts; native hosts should stay thin
 
 Project concepts:
@@ -188,6 +188,7 @@ Project concepts:
 - browser modules are namespaced as `mod/<author>/<repo>/...`
 - frontend extensibility is a core runtime primitive; the framework installs `space.extend` first and the browser runtime grows by loading modules and extension points deterministically
 - the layered browser model is `app/L0` firmware, `app/L1` group customware, and `app/L2` user customware
+- customware bundles are ordinary installed `L1` or `L2` modules that include a `space.bundle.yaml` manifest; the server discovers them through the same module index and permission model, and the browser uses `space.bundles` for metadata reads, removable action handlers, and external bridge-state sync points
 - `app/L1` and `app/L2` are the logical writable layers; on disk they default to `app/L1` and `app/L2`, but when `CUSTOMWARE_PATH` is set the backend stores them under `CUSTOMWARE_PATH/L1` and `CUSTOMWARE_PATH/L2`
 - writable layer content is transient runtime state and is gitignored when it lives under the repo; do not treat it as durable repo-owned sample content
 - `L2/<username>/user.yaml` stores user metadata such as `full_name`; auth state lives under `L2/<username>/meta/`
diff --git a/README.md b/README.md
index ec541b69..a3490653 100644
--- a/README.md
+++ b/README.md
@@ -134,6 +134,14 @@ node space supervise HOST=0.0.0.0 PORT=3000 # zero downtime auto-update
 
 Run `node space help` to see the full command surface and built-in help for each from [`commands/params.yaml`](./commands/params.yaml).
 
+## Customware bundles
+
+Reusable customizations can ship as customware bundles: ordinary `L1` or `L2` modules with a root `space.bundle.yaml` manifest.
+
+Bundles stay inside Space Agent's existing browser-first model. They add UI through `ext/html`, behavior through `ext/js` and `space.extend(...)`, skills through `ext/skills`, theme or landing-background CSS through `_core/framework/theme/end`, and removable browser actions through `space.bundles.actions`. The manifest exposes metadata such as id, version, capabilities, config defaults, compatibility, extension points, and action descriptions.
+
+Install, update, or remove a bundle the same way you manage any customware module under `L1/<group>/mod/<author>/<repo>/` or `L2/<user>/mod/<author>/<repo>/`. Direct runtime injection is discouraged because it depends on private implementation details; when a customization needs a new stable seam, add or propose that seam instead.
+
 ## AI-driven development and documentation
 
 Space Agent is developed by AI agents, including its documentation.
diff --git a/app/AGENTS.md b/app/AGENTS.md
index 2930cdfe..971db6cb 100644
--- a/app/AGENTS.md
+++ b/app/AGENTS.md
@@ -115,7 +115,7 @@ Current browser entry surfaces are served from `server/pages/`:
 
 Current major first-party modules under `app/L0/_all/mod/_core/`:
 
-- `framework/`: frontend bootstrap, runtime primitives, component loader, extension system, shared utilities
+- `framework/`: frontend bootstrap, runtime primitives, component loader, extension system, customware-bundle runtime helpers, shared utilities
 - `agent-chat/`: headless shared chat helpers that belong to first-party agent features rather than the platform layer, currently including repeated-assistant-message evaluation helpers and hook implementations reused by overlay and admin chat
 - `login_hooks/`: headless authenticated-bootstrap lifecycle hooks for first-login and same-origin `/login` arrival events, with a client-owned `~/meta/login_hooks.json` marker and feature-owned onboarding hooks such as the spaces module's first-login `Big Bang` onboarding-space bootstrap
 - `visual/`: shared visual language, canvas, chrome, buttons, dialog helpers, conversation rendering primitives, and reusable authenticated-app imagery under `visual/res/`; pre-auth `/login` and `/enter` keep their mirrored astronaut asset under `server/pages/res/`
@@ -175,7 +175,7 @@ Current boot flow:
 
 1. A page shell in `server/pages/` loads shared framework CSS and `/mod/_core/framework/js/initFw.js`.
 2. The shell exposes one top-level HTML anchor in the body.
-3. `initFw.js` installs the runtime, injects the framework-owned `_core/framework/head/end` HTML seam into `document.head`, runs the extensible framework bootstrap step in `_core/framework/js/initializer.js`, including framework-wide navigation interception for same-origin `_blank` app opens and best-effort current-tab cross-origin escape blocking, then installs Alpine helpers and shared bootstrap behavior.
+3. `initFw.js` installs the runtime, injects the framework-owned `_core/framework/theme/end` and `_core/framework/head/end` HTML seams into `document.head`, runs the extensible framework bootstrap step in `_core/framework/js/initializer.js`, including framework-wide navigation interception for same-origin `_blank` app opens and best-effort current-tab cross-origin escape blocking, then installs Alpine helpers and shared bootstrap behavior.
 4. The first mounted module owns the next seam and exposes more anchors or wrapped functions.
 5. Other modules compose into those explicit seams instead of patching private internals.
 
@@ -203,7 +203,7 @@ HTML extension anchors:
 - HTML callers name only the seam; the runtime loads `<x-extension>` tags from the module's `ext/html/` tree automatically
 - thin extension files should usually mount the real component from the module root instead of containing the entire feature directly
 - root page anchors such as `body/start` and `page/admin/body/start` are fixed shell contracts; module-owned anchors should be named after the owning module path, for example `_core/router/shell_start`
-- `_core/framework` also creates `_core/framework/head/end` in `document.head` during bootstrap so layers can add declarative head-side tags or inline bootstraps without editing page shells or adding a JS hook
+- `_core/framework` also creates `_core/framework/theme/end` and `_core/framework/head/end` in `document.head` during bootstrap so layers can add declarative theme CSS, head-side tags, or inline bootstraps without editing page shells or adding a JS hook
 - runtime discovery watches the whole document tree, so `x-extension` and `x-component` insertions under `head` are supported the same way as body-mounted seams
 - `_core/onscreen_menu` owns a reserved centered header bar from `_core/router/shell_start`; it keeps `_core/onscreen_menu/bar_start` on the left and `_core/onscreen_menu/bar_end` on the right for shell-level controls, allows route-owned `x-inject` content to target the existing left-side `[id="_core/onscreen_menu/bar_start"]` container when a feature wants ephemeral controls that disappear with the route but the shell seam may mount later, keeps a persistent Home button that routes to the empty route `#/` so the router default decides the home screen, and exposes `_core/onscreen_menu/items` as the dropdown action seam for non-Home feature buttons, whose modules contribute thin button adapters with numeric `data-order` values while `_core/onscreen_menu` sorts them automatically and keeps only the auth exit action local after the seam; `_core/dashboard` is the current first-party example of a route-owned wrapper that injects into `bar_start` and then exposes ordered dashboard-local seams for dashboard-only topbar actions
 - `_core/web_browsing` is the current first-party example of a module that uses both `_core/onscreen_menu/items` and `page/router/overlay/end`: it contributes a Browser menu action at `data-order="250"`, opens a new floating browser window each time the action is used, keeps each browser surface on a unique internal `browser-N` id while the public `space.browser` runtime surface exposes numeric ids such as `1`, lets widgets or other screen DOM create registered surfaces with plain `<x-browser src="...">` markup, keeps that public runtime surface top-level and id-based only instead of exposing per-window handles, auto-settles open or state or navigation or inspection helpers internally so they can return fresh browser state snapshots without a separate `sync(...)` step while ref-targeted actions return `{ action, state }` with visible-effect flags such as `reacted`, `noObservedEffect`, `validationTextAdded`, or `domChanged`, requires navigation-capable helpers to wait for an observed browser-side navigation or loading transition before they accept a new snapshot, blocks stale old-guest bridge reads during that handoff, exposes `space.browser.setLogLevel(...)` as the runtime-side override for browser diagnostics while leaving the default app browser log level at `error`, persists each open browser window's URL, geometry, minimized state, and stacking data in browser-local storage so reloads can reopen the same window set, reuses the same viewport-fit pass for both live resize and restore so reopened windows clamp back onto the current screen when the viewport changed, and raises a focused browser window to the top of the browser stack even when the click lands inside the iframe or desktop webview page content. It spawns new windows below the fixed shell bar near the left edge of the centered router-stage column at approximately that column width while still allowing later drag movement all the way to the viewport top edge, renders popup windows through `<x-browser controls="true">` with Back, Forward, Reload, and address controls while inline surfaces may omit controls or opt in with the same attribute, keeps its page-side browsing bridge self-contained through `/mod/_core/web_browsing/browser-frame-inject.js` plus matching host helpers, and may also extend the onscreen-agent transient sections seam with a brief `currently open web browsers` status block plus prompt-time `last interacted web browser` content when the remembered interacted browser surface is still open; browser sessions render an iframe fallback inside that element, packaged desktop runs now prefer a DOM `<webview>` inside that same element so modal, widget, and other renderer-owned placement clipping stays aligned with the shell, the desktop host installs a tiny document-start browser guest kernel into the top page and all iframe descendants so shadow roots and nested documents stay crawlable later, the renderer then injects the bridge bootstrap plus an extensible guest runtime script list built through `space.extend(...)`, desktop `_blank` and `window.open(...)` requests are routed back into new in-app browser modals instead of separate OS windows, and the injected runtime must stay transport-agnostic so later browser-extension injection can reuse the same page-side request handlers while readable `content(...)` output stays in the lean typed-ref form like `[disabled muted button 18] Continue`, `[checked checkbox 7] Email updates`, `[error button 9] Delete`, or `[input text 30] Search placeholder=Hledat value=Ethereum` and omits obviously non-visible DOM or CSS-hidden content such as `hidden`, `aria-hidden`, `display:none`, `visibility:hidden|collapse`, `content-visibility:hidden`, or `opacity:0` subtrees
@@ -215,7 +215,7 @@ JS extension hooks:
 - wrapped functions become async and should be awaited by callers
 - JS hook files live at `mod/<author>/<repo>/ext/js/<extension-point>/*.js` or `*.mjs`
 - JS callers name only the seam; the runtime loads hooks from the module's `ext/js/` tree automatically
-- framework-backed pages expose `_core/framework/initializer.js/initialize`; use `_core/framework/head/end` when the work can stay as declarative head HTML or inline bootstrap code, and prefer the initializer `/end` hook when the setup must stay imperative instead of editing page shells
+- framework-backed pages expose `_core/framework/initializer.js/initialize`; use `_core/framework/theme/end` for declarative theme or background CSS, use `_core/framework/head/end` when the work can stay as other declarative head HTML or inline bootstrap code, and prefer the initializer `/end` hook when the setup must stay imperative instead of editing page shells
 - framework-backed pages centrally grant `/enter` tab access to same-origin `/` and `/admin` windows opened through normal `target="_blank"` link clicks or `window.open(..., "_blank")`, and they also intercept same-tab cross-origin `http(s)` escapes through the Navigation API `navigate` event when available plus fallback anchor or `window.open(..., "_self")` and `location`-based hooks so web runtime can move those requests into a new tab while packaged desktop runtime blocks them before the Electron main-window origin guard needs to recover; location-bar navigations and manual browser opens such as context-menu, middle-click, or modifier-key opens are not intercepted and still route through `/enter` or the host guard
 - use `callJsExtensions("name", data)` only when the seam is an explicit event rather than a function lifecycle
 - `_core/login_hooks` is a first-party example of an explicit event seam: it runs from `_core/framework/initializer.js/initialize/end`, checks `~/meta/login_hooks.json`, then dispatches `_core/login_hooks/first_login` once per user and `_core/login_hooks/any_login` when the authenticated shell was reached from `/login`; `_core/spaces` currently uses that first-login seam to copy or reuse the module-owned `Big Bang` onboarding space and rewrite the main-shell default route before the router falls back to `#/dashboard`
@@ -278,6 +278,7 @@ Runtime guidance:
 - framework-backed pages that boot through `/mod/_core/framework/js/initFw.js` already initialize the runtime before feature modules mount
 - `globalThis.space` is scoped to the current window or iframe only; do not publish it into other browsing contexts
 - use `space.api` for authenticated backend calls
+- use `space.bundles` for installed customware-bundle metadata, removable browser-side action handlers, and bridge-state sync points owned by external integrations instead of patching framework or feature internals
 - prefer the shared `space.api` helpers over feature-local request batching; same-tick `fileRead(...)` calls coalesce automatically, preserve per-call missing-file behavior by retrying individually when a combined batch fails, and identical in-flight file, identity, and extension-load requests are deduped by the runtime
 - use `space.api.folderDownloadUrl(...)` when a folder download should stay as a browser attachment instead of fetching the archive blob into frontend memory
 - first-party framework, shell, skill-helper, and bundled demo assets required for normal app use must be local `/mod/...` files, server page assets, or inline code; do not load required scripts, styles, fonts, images, or other framework assets from CDNs
diff --git a/app/L0/_all/mod/_core/documentation/AGENTS.md b/app/L0/_all/mod/_core/documentation/AGENTS.md
index d8bbbdf6..db70b435 100644
--- a/app/L0/_all/mod/_core/documentation/AGENTS.md
+++ b/app/L0/_all/mod/_core/documentation/AGENTS.md
@@ -16,7 +16,7 @@ Current structure:
 
 - `ext/skills/documentation/SKILL.md`: the required entry skill that lists every documentation page by relative path, name, and short description and tells the agent how to read focused docs
 - `docs/architecture/`: repo-wide runtime, desktop-host packaging, and documentation-system orientation
-- `docs/app/`: frontend runtime, admin-agent, browser-side WebLLM and Hugging Face runtime docs, extension, and spaces documentation
+- `docs/app/`: frontend runtime, customware bundle, admin-agent, browser-side WebLLM and Hugging Face runtime docs, extension, and spaces documentation
 - `docs/agent/`: onscreen-agent runtime, prompt, execution, and skill-system documentation
 - `docs/server/`: router, page, API, auth, layered-filesystem, and writable-layer history documentation, including auth-preserving rollback rules
 - `docs/cli/`: CLI command and runtime-parameter documentation
diff --git a/app/L0/_all/mod/_core/documentation/docs/app/customware-bundles.md b/app/L0/_all/mod/_core/documentation/docs/app/customware-bundles.md
new file mode 100644
index 00000000..38f1849c
--- /dev/null
+++ b/app/L0/_all/mod/_core/documentation/docs/app/customware-bundles.md
@@ -0,0 +1,124 @@
+# Customware Bundles
+
+This doc covers the Customware Bundle Interface for reusable downstream modules.
+
+## Primary Sources
+
+- `AGENTS.md`
+- `app/AGENTS.md`
+- `app/L0/_all/mod/_core/framework/AGENTS.md`
+- `server/lib/customware/AGENTS.md`
+- `server/api/AGENTS.md`
+
+## What A Bundle Is
+
+A customware bundle is an ordinary installed module with one extra manifest:
+
+```txt
+L1/<group>/mod/<author>/<repo>/space.bundle.yaml
+L2/<user>/mod/<author>/<repo>/space.bundle.yaml
+```
+
+The bundle still uses the normal Space Agent composition model:
+
+- UI through `ext/html/...`
+- behavior through `ext/js/...` and `space.extend(...)`
+- skills through `ext/skills/*/SKILL.md`
+- browser guest behavior through documented web-browsing guest-runtime seams
+- visual/theme changes through `_core/framework/theme/end`
+- head-side setup through `_core/framework/head/end`
+
+The manifest advertises the package. It does not grant permission to monkey patch private runtime internals.
+
+## Manifest Shape
+
+The root file is `space.bundle.yaml`.
+
+The checked-in minimal reference fixture lives at `tests/fixtures/customware_bundle_example/`.
+
+Example:
+
+```yaml
+id: acme/fleet
+name: Fleet Control
+version: 1.0.0
+description: Team-owned fleet controls for Space Agent
+capabilities: [theme, actions, browser-runtime]
+extension_points:
+  - _core/framework/theme/end
+  - _core/web_browsing/browser-guest-runtime.js/buildBrowserGuestRuntimeScriptPaths/end
+compatibility:
+  space_agent: ">=0.65"
+config_defaults:
+  accent: teal
+actions:
+  - id: fleet.open
+    title: Open fleet
+    capability: actions
+    description: Open the fleet dashboard
+```
+
+Stable fields:
+
+- `id`: lowercase bundle id, usually `<author>/<repo>`
+- `name`, `version`, and `description`: display metadata
+- `capabilities`: high-level advertised capabilities
+- `extension_points`: documented seams the bundle expects to use
+- `compatibility`: version or runtime compatibility notes
+- `config_defaults`: optional structured defaults owned by the bundle
+- `actions`: declarative action metadata
+
+## Runtime Surface
+
+Installed bundle metadata is available through:
+
+- `space.api.bundleList(options)`
+- `space.api.bundleInfo(pathOrOptions)`
+- `space.bundles.list(options)`
+- `space.bundles.info(pathOrOptions)`
+
+Executable browser actions are registered at runtime:
+
+```js
+const dispose = space.bundles.actions.register({
+  bundleId: "acme/fleet",
+  id: "fleet.open",
+  title: "Open fleet",
+  async run(payload) {
+    return payload;
+  }
+});
+```
+
+When the module unmounts or disables the feature, call `dispose()` or `space.bundles.actions.unregister("fleet.open")`.
+
+External integrations can publish bridge state through:
+
+```js
+space.bundles.bridge.registerSync("acme/fleet", async (payload) => payload);
+await space.bundles.bridge.syncState("acme/fleet", { online: true });
+```
+
+## Install, Update, Remove
+
+Bundles are installed, updated, and removed as modules.
+
+Use the normal module locations:
+
+- `L1/<group>/mod/<author>/<repo>/` for group-level customware
+- `L2/<user>/mod/<author>/<repo>/` for user-level customware
+
+The existing module APIs and admin module views still own installation and removal. Removing the module removes its bundle metadata, extension files, skills, and action handlers once the owning page reloads or unregisters them.
+
+## Why Not Runtime Injection
+
+Direct runtime injection is fragile because it depends on private file names, timing, or implementation details. Bundles should instead turn desired changes into stable extension contracts:
+
+- add a missing HTML seam
+- add a missing JS hook through `space.extend(...)`
+- add metadata under `ext/...`
+- add a browser-side action through `space.bundles.actions`
+- add a bridge sync handler through `space.bundles.bridge`
+- propose the missing seam upstream when no stable contract exists
+
+That keeps downstream customizations rebase-friendly while preserving Space Agent's browser-first customware model.
diff --git a/app/L0/_all/mod/_core/documentation/docs/app/modules-and-extensions.md b/app/L0/_all/mod/_core/documentation/docs/app/modules-and-extensions.md
index 80202aaa..f202f195 100644
--- a/app/L0/_all/mod/_core/documentation/docs/app/modules-and-extensions.md
+++ b/app/L0/_all/mod/_core/documentation/docs/app/modules-and-extensions.md
@@ -75,7 +75,7 @@ Resolution rules:
 - the caller names only the seam
 - matching files live under `mod/<author>/<repo>/ext/html/some/path/*.html`
 - extension files should stay thin and normally mount the real component or view
-- `_core/framework` also injects `_core/framework/head/end` into `document.head` during bootstrap so layers can add declarative head-side tags or inline bootstraps without editing page shells
+- `_core/framework` also injects `_core/framework/theme/end` and `_core/framework/head/end` into `document.head` during bootstrap so layers can add declarative theme CSS, head-side tags, or inline bootstraps without editing page shells
 - `_core/framework` also registers `x-inject="selector"` during bootstrap; it mirrors Alpine `x-teleport` for `<template>` roots, waits for the selector when the target seam is not mounted yet, and tears down that wait when the source template unmounts
 - dynamic extension and component discovery watches the whole document tree, so seams and components inserted under `head` are hydrated the same way as body-mounted ones
 
@@ -120,7 +120,7 @@ Rules:
 - the wrapped function becomes async
 - hooks resolve under `mod/<author>/<repo>/ext/js/<extension-point>/*.js` or `*.mjs`
 - wrapped functions expose `/start` and `/end` hook points
-- framework-backed page boot also creates the `_core/framework/head/end` HTML seam in `document.head`; use that seam when the integration can stay declarative, and use `_core/framework/initializer.js/initialize/end` when the setup must stay imperative
+- framework-backed page boot also creates the `_core/framework/theme/end` and `_core/framework/head/end` HTML seams in `document.head`; use the theme seam for declarative CSS/background customization, use the head seam for other declarative setup, and use `_core/framework/initializer.js/initialize/end` when the setup must stay imperative
 - feature-specific prompt or execution behavior for the onscreen agent should be supplied from the owning module through `_core/onscreen_agent/...` extension seams, not hardcoded into `_core/onscreen_agent`
 - `_core/agent_prompt` is a headless shared helper module: it owns the reusable prepared-prompt runtime used by first-party agent surfaces, while surface-specific prompt sections, examples, and transient builders still live in the owning agent modules
 - headless helper modules are valid first-party modules too: `_core/promptinclude` has no route or UI, but it extends `_core/onscreen_agent/llm.js/buildOnscreenAgentSystemPromptSections` and `_core/onscreen_agent/llm.js/buildOnscreenAgentTransientSections` to auto-inject readable `**/*.system.include.md` files into the overlay system prompt and readable `**/*.transient.include.md` files into the overlay transient context
@@ -140,6 +140,29 @@ JS hook lookups do not use that frame wait window. Hook callers await them direc
 
 The framework fetch wrapper also carries the highest observed `Space-State-Version` on follow-up same-origin requests, keeps that floor in per-tab `sessionStorage`, mirrors it into a short-lived same-origin `space_state_version` cookie for immediate redirect handoffs, and automatically retries the router's bounded retryable sync `503` responses a few times, so startup-time worker catch-up races do not usually surface as broken extension bootstrap.
 
+## Customware Bundles
+
+A customware bundle is a normal installed `L1` or `L2` module with a root `space.bundle.yaml` manifest. The manifest advertises the package id, name, version, capabilities, config defaults, compatibility notes, extension points, and declarative action metadata; it does not grant permission to replace private framework or feature internals.
+
+Bundle files live under the same module roots as any other customware:
+
+```txt
+L1/<group>/mod/<author>/<repo>/space.bundle.yaml
+L2/<user>/mod/<author>/<repo>/space.bundle.yaml
+```
+
+Bundles compose through the existing Space Agent seams:
+
+- UI adapters in `ext/html/...`
+- behavior hooks in `ext/js/...` through `space.extend(...)`
+- skills in `ext/skills/*/SKILL.md`
+- theme or landing-background CSS in `_core/framework/theme/end`
+- other head-side setup in `_core/framework/head/end`
+- browser-side executable actions registered from module code through `space.bundles.actions`
+- external bridge state synchronized through `space.bundles.bridge`
+
+Installed bundle metadata is exposed through `space.api.bundleList(...)`, `space.api.bundleInfo(...)`, `space.bundles.list(...)`, and `space.bundles.info(...)`. Actions registered through `space.bundles.actions.register(...)` are runtime handlers owned by the loaded module; they should be unregistered on unmount or disappear naturally when the module is removed and the page reloads.
+
 ## Extension Metadata Manifests
 
 Not every extension-resolved file is an HTML adapter or JS hook.
diff --git a/app/L0/_all/mod/_core/documentation/docs/app/runtime-and-layers.md b/app/L0/_all/mod/_core/documentation/docs/app/runtime-and-layers.md
index f5df40e1..c3d8e15f 100644
--- a/app/L0/_all/mod/_core/documentation/docs/app/runtime-and-layers.md
+++ b/app/L0/_all/mod/_core/documentation/docs/app/runtime-and-layers.md
@@ -76,6 +76,7 @@ Important namespaces:
 
 - `space.api`: authenticated backend API client helpers
 - `space.api.gitHistoryList(...)`, `gitHistoryDiff(...)`, `gitHistoryPreview(...)`, `gitHistoryRollback(...)`, and `gitHistoryRevert(...)`: optional writable-layer local-history helpers backed by server-owned Git APIs
+- `space.bundles`: installed customware-bundle metadata helpers plus removable browser action and external bridge-state registries for bundle-owned integrations
 - `space.config`: frontend-exposed runtime params
 - `space.fw.createStore`: Alpine store helper
 - `space.utils.markdown.render(...)` and `parseDocument(...)`
diff --git a/app/L0/_all/mod/_core/documentation/docs/server/api/modules-and-runtime.md b/app/L0/_all/mod/_core/documentation/docs/server/api/modules-and-runtime.md
index d5a5d71f..b59b9e64 100644
--- a/app/L0/_all/mod/_core/documentation/docs/server/api/modules-and-runtime.md
+++ b/app/L0/_all/mod/_core/documentation/docs/server/api/modules-and-runtime.md
@@ -53,6 +53,8 @@ Important behaviors:
 ## Module Endpoints
 Current module endpoints:
 
+- `bundle_list`
+- `bundle_info`
 - `module_list`
 - `module_info`
 - `module_install`
@@ -62,6 +64,9 @@ These delegate to `server/lib/customware/module_manage.js`.
 
 Important behaviors:
 
+- `bundle_list` and `bundle_info` expose root `space.bundle.yaml` metadata for installed modules without adding a separate plugin loader
+- bundle reads use the same module indexes, owner filters, permissions, `CUSTOMWARE_PATH` roots, and L1/L2 visibility rules as module reads
+- bundle manifests can describe capabilities, extension points, compatibility, config defaults, and declarative actions, but executable behavior must still enter through documented module seams or the browser-side bundle action registry
 - module writes must reuse shared permission rules
 - module writes should publish changed logical paths through the shared mutation commit flow so every worker sees the new module state before the response finishes
 - request-time module list and info reads consume replicated shared-state shards, usually only the readable `L1` roots plus the caller's own `L2`, instead of scanning the full app index
diff --git a/app/L0/_all/mod/_core/documentation/docs/server/customware-layers-and-paths.md b/app/L0/_all/mod/_core/documentation/docs/server/customware-layers-and-paths.md
index 6e03e4d9..3cc52a32 100644
--- a/app/L0/_all/mod/_core/documentation/docs/server/customware-layers-and-paths.md
+++ b/app/L0/_all/mod/_core/documentation/docs/server/customware-layers-and-paths.md
@@ -12,6 +12,7 @@ This doc covers the layered filesystem model behind `/mod/...` and the app-file
 - `server/lib/customware/git_history.js`
 - `server/lib/customware/module_inheritance.js`
 - `server/lib/customware/extension_overrides.js`
+- `server/lib/customware/bundles.js`
 - `server/lib/customware/layer_limit.js`
 
 ## Logical Versus Disk Paths
@@ -123,6 +124,19 @@ Resolution rules:
 - `extension_overrides.js` owns extension lookup resolution
 - request-time module and extension lookup reads replicated shared-state shards for the relevant readable owners instead of scanning the full watchdog path index
 
+## Customware Bundles
+
+Customware bundles are installed modules with a root `space.bundle.yaml` manifest:
+
+```txt
+L1/<group>/mod/<author>/<repo>/space.bundle.yaml
+L2/<user>/mod/<author>/<repo>/space.bundle.yaml
+```
+
+The server parses those manifests through `server/lib/customware/bundles.js` and exposes them through `bundle_list`, `bundle_info`, and the existing module list or info payloads. Discovery is intentionally tied to module management, so bundles keep the same readable-owner filtering, admin-only cross-user rules, and configured `CUSTOMWARE_PATH` storage behavior as other modules.
+
+The manifest is metadata, not executable permission. Bundle code still enters through module-owned files such as `ext/html`, `ext/js`, `ext/skills`, documented `space.extend(...)` seams, and browser-side `space.bundles.actions` registrations.
+
 ## `maxLayer`
 
 `maxLayer` limits module and extension lookup, not normal app-file APIs. The narrow first-party exception is explicit module-oriented `file_paths` discovery when a caller passes `maxLayer` intentionally, such as the dashboard panel index resolving readable `mod/*/*/ext/panels/*.yaml` files before batch-reading them through `file_read`.
diff --git a/app/L0/_all/mod/_core/documentation/ext/skills/documentation/SKILL.md b/app/L0/_all/mod/_core/documentation/ext/skills/documentation/SKILL.md
index 52ac768d..076b7ddc 100644
--- a/app/L0/_all/mod/_core/documentation/ext/skills/documentation/SKILL.md
+++ b/app/L0/_all/mod/_core/documentation/ext/skills/documentation/SKILL.md
@@ -29,6 +29,7 @@ recommended starting points
 - frontend runtime and layers: `app/runtime-and-layers.md`
 - admin agent runtime: `app/admin-agent-runtime.md`
 - modules, routing, extensions, or dashboard panels: `app/modules-and-extensions.md`
+- customware bundle manifests and runtime actions: `app/customware-bundles.md`
 - browser-side Hugging Face testing: `app/huggingface-browser-runtime.md`
 - browser-side WebLLM testing: `app/webllm-browser-runtime.md`
 - spaces and widgets: `app/spaces-and-widgets.md`
@@ -49,6 +50,7 @@ architecture/overview.md|Runtime Overview|Browser-first architecture, major entr
 architecture/desktop-host-and-packaging.md|Desktop Host And Packaging|Electron host startup, free-port binding, packaged single-user behavior, and desktop build outputs.
 architecture/documentation-system.md|Documentation System|How `AGENTS.md`, the documentation module, and code fit together, plus update rules.
 app/runtime-and-layers.md|App Runtime And Layers|Frontend boot flow, `space` runtime namespaces, entry shells, and `L0/L1/L2` rules.
+app/customware-bundles.md|Customware Bundles|Bundle manifests, installed module discovery, bundle actions, bridge sync, and no-injection guidance.
 app/admin-agent-runtime.md|Admin Agent Runtime|Admin chat ownership, config persistence, shared execution loop, and API-versus-local-Hugging-Face transport switching.
 app/modules-and-extensions.md|Modules And Extensions|`/mod/...` delivery, router path resolution, dashboard panel manifests, `ext/html`, `ext/js`, and `<x-component>` behavior.
 app/huggingface-browser-runtime.md|Hugging Face Browser Runtime|The routed Transformers.js test surface, its worker split, direct Hub model loading contract, and throughput metrics.
diff --git a/app/L0/_all/mod/_core/framework/AGENTS.md b/app/L0/_all/mod/_core/framework/AGENTS.md
index 54ee3452..aa6c7b1c 100644
--- a/app/L0/_all/mod/_core/framework/AGENTS.md
+++ b/app/L0/_all/mod/_core/framework/AGENTS.md
@@ -21,7 +21,8 @@ This module owns:
 - `js/yaml-lite.js`: project-owned lightweight YAML parser and serializer shared directly by browser runtime helpers, server modules, and agent-surface param parsers
 - `js/execution-format.js`: shared YAML-first execution transcript formatting helpers used by first-party agent runtimes for console-log and returned-value serialization
 - `js/server-config.js`: injected page-meta parsing for frontend-exposed backend runtime parameters
-- `js/extensions.js`: `space.extend`, HTML extension loading, the framework-managed `_core/framework/head/end` head seam, JS hook loading, lookup caching, and batching
+- `js/bundles.js`: browser-side customware-bundle runtime helper for metadata reads through `space.api`, removable bundle action handlers, and external bridge-state sync handlers
+- `js/extensions.js`: `space.extend`, HTML extension loading, the framework-managed `_core/framework/theme/end` and `_core/framework/head/end` head seams, JS hook loading, lookup caching, and batching
 - `js/moduleResolution.js`: propagation of `maxLayer` into framework-managed module and extension requests
 - `js/components.js`: `<x-component>` loading, recursive component imports, and `xAttrs(...)`
 - `js/modals.js`: the generic framework modal wrapper used for separately loaded modal documents that are not mounted as feature-owned native dialogs
@@ -39,7 +40,7 @@ Framework-backed page shells load `/mod/_core/framework/js/initFw.js` once.
 
 Current boot order:
 
-1. `initFw.js` imports `extensions.js` first so `space.extend` exists before other framework modules expose seams and so the framework-managed head HTML seam is present before the initial extension scan.
+1. `initFw.js` imports `extensions.js` first so `space.extend` exists before other framework modules expose seams and so the framework-managed head HTML seams are present before the initial extension scan.
 2. `initializeRuntime(...)` publishes the shared runtime onto `globalThis.space`.
 3. `initializer.initialize()` runs the first extensible framework bootstrap step, installs the framework navigation guard, and injects the framework-owned runtime context tag.
 4. Alpine and framework support modules are loaded.
@@ -48,6 +49,7 @@ Current boot order:
 `initializeRuntime(...)` currently publishes:
 
 - `space.api`
+- `space.bundles`, which exposes installed customware-bundle metadata reads, a removable action registry at `space.bundles.actions`, and external bridge-state sync hooks at `space.bundles.bridge`
 - `space.config`
 - `space.chat` when an agent surface publishes the active thread messages plus attachment handles
 - `space.fw.createStore`
@@ -62,6 +64,7 @@ Current boot order:
 Current API helper contract:
 
 - `space.api.userSelfInfo()` is the canonical frontend identity snapshot; it now also returns the backend `sessionId` plus `userCryptoKeyId` and `userCryptoState`, and frontend agents should still use `username`, `managedGroups`, and `_admin` membership in `groups` to infer writable app roots before choosing where to store files or modules
+- `space.api.bundleList(...)` and `space.api.bundleInfo(...)` expose installed customware-bundle manifests from `space.bundle.yaml` files discovered through the server module-management path
 - `space.api.fileRead(...)` accepts one logical path, one `{ path, encoding? }` entry, or a `files` batch, and `js/api-client.js` now coalesces same-tick file reads into one `/api/file_read` request before re-slicing the returned files back to each caller; when a combined batch fails, it retries the queued reads individually so shorthand paths like `~/...` and optional missing-file callers keep their original per-call behavior
 - `space.api.fileList(pathOrOptions, recursive?)` accepts normal path strings and an options object with `access: "write"`, `writableOnly: true`, or `gitRepositories: true` for server-confirmed writable discovery without exposing reserved `.git` metadata
 - `space.api.folderDownloadUrl(pathOrOptions)` builds the same-origin attachment URL for a permission-checked folder ZIP download without fetching the archive into browser memory
@@ -73,6 +76,12 @@ Current API helper contract:
 - same-origin `fetch(...)` calls made after the fetch proxy is installed automatically carry the highest observed `Space-State-Version`; `js/state-version.js` keeps that floor in per-tab `sessionStorage` and mirrors it into a short-lived same-origin cookie so immediate top-level redirects can reuse the same minimum version without query params, and when the router returns its bounded retryable sync `503` with `Retry-After: 0`, `fetch-proxy.js` retries the request a few times before surfacing the failure to callers
 - frontend modules and widgets must not hardcode third-party CORS proxy services; use direct `fetch(...)` or `space.fetchExternal(...)` for remote reads and reserve `space.proxy.buildUrl(...)` for cases that need a same-origin proxied URL string
 
+Current customware-bundle runtime contract:
+
+- `space.bundles.list(...)` and `space.bundles.info(...)` are thin browser helpers over the authenticated bundle APIs
+- bundle manifests may declare action metadata, but executable browser behavior must register through `space.bundles.actions.register({ id, title, run })` from normal module code and unregister when the owning module unmounts
+- external bridges should publish state through named `space.bundles.bridge` sync handlers instead of patching private feature stores or framework globals
+
 Current context helper contract:
 
 - `js/context.js` owns generic `<x-context>` discovery for the frontend, not just skill filtering
@@ -87,7 +96,7 @@ Rules:
 - framework bootstrap registers `x-inject="selector"` for `<template>` roots; it mirrors Alpine `x-teleport`, waits for a matching selector with a `MutationObserver`, and disconnects that wait when the source template cleans up, so route-owned markup can safely target shell seams that may mount later
 - `css/index.css` installs the app-wide border-box sizing baseline; modules may rely on `width: 100%` including padding and borders unless they explicitly opt an element back into content-box sizing
 - if bootstrap order changes, update this doc and `/app/AGENTS.md`
-- shell-level one-time setup that can stay declarative, such as inline analytics bootstrap or static `document.head` tags, should prefer the framework-managed `_core/framework/head/end` HTML seam instead of page-shell edits
+- shell-level theme customization that can stay declarative should prefer the framework-managed `_core/framework/theme/end` HTML seam, while other one-time declarative setup such as inline analytics bootstrap or static `document.head` tags should prefer `_core/framework/head/end` instead of page-shell edits
 - shell-level one-time setup that must stay imperative should prefer the shared `_core/framework/initializer.js/initialize/end` JS hook instead of page-shell edits
 - ordinary authenticated feature dialogs must not route through `js/modals.js`; they should stay feature-owned native `<dialog class="chat-dialog">` surfaces using `_core/visual/forms/dialog.css` plus `forms/dialog.js`, while `js/modals.js` stays reserved for generic separately loaded modal documents or platform utilities that truly need it
 - framework-backed pages centralize navigation interception in `js/new-window.js`: same-origin `/` and `/admin` URLs opened with `_blank` through normal left-clicks or `window.open(..., "_blank")` receive the current tab's `/enter` access in the child window before navigation, while same-tab cross-origin `http(s)` navigations are first blocked through the Navigation API `navigate` event when that event exists and is cancelable, and otherwise fall back to interception of anchor clicks, `window.open(..., "_self")`, and best-effort `Location.assign(...)`, `Location.replace(...)`, or `Location.href = ...` writes; web runtime tries to move those cross-origin requests into a new browser tab, while packaged desktop runtime blocks them in-place and relies on the Electron host as the hard guarantee; location-bar navigations, manual browser opens such as context-menu or middle-click or modifier-key opens, non-cancelable navigation events, and any browser engines that refuse the location patches still fall back to the page-shell or host guard
@@ -101,7 +110,7 @@ Important contracts:
 - `<x-extension id="some/path">` resolves HTML adapters from `mod/<author>/<repo>/ext/html/some/path/*.html`
 - `space.extend(import.meta, ...)` requires a valid module ref and wraps standalone functions only
 - `space.extend(...)` and `callJsExtensions("some/path", ...)` resolve JS hook files from `mod/<author>/<repo>/ext/js/<extension-point>/*.js` or `*.mjs`
-- `extensions.js` injects `_core/framework/head/end` into `document.head` on framework-backed pages before the initial HTML extension scan, so layers can contribute head-side HTML without page-shell edits
+- `extensions.js` injects `_core/framework/theme/end` and `_core/framework/head/end` into `document.head` on framework-backed pages before the initial HTML extension scan, so layers can contribute theme CSS and other head-side HTML without page-shell edits
 - dynamic `<x-extension>` discovery watches the whole `document.documentElement`, not only `body`, so head-side extension seams keep working after bootstrap
 - `_core/framework/initializer.js/initialize` is the shared once-per-page bootstrap seam for framework-backed shells, and its `/end` hook is the imperative fallback when a head-side integration cannot stay declarative
 - extension callers should name only the seam; the runtime chooses the `html/` or `js/` subfolder implicitly
diff --git a/app/L0/_all/mod/_core/framework/js/api-client.js b/app/L0/_all/mod/_core/framework/js/api-client.js
index f3d4a066..08fbd53d 100644
--- a/app/L0/_all/mod/_core/framework/js/api-client.js
+++ b/app/L0/_all/mod/_core/framework/js/api-client.js
@@ -185,6 +185,61 @@
  * @typedef {{ paths: FileDeleteInput[] }} FileDeleteBatchOptions
  */
 
+/**
+ * @typedef {{
+ *   area?: string,
+ *   ownerId?: string,
+ *   search?: string
+ * }} BundleListOptions
+ */
+
+/**
+ * @typedef {{
+ *   maxLayer?: number,
+ *   ownerId?: string,
+ *   path?: string
+ * }} BundleInfoOptions
+ */
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   title: string,
+ *   bundleId?: string,
+ *   capability?: string,
+ *   description?: string,
+ *   inputSchema?: Record<string, unknown>,
+ *   outputSchema?: Record<string, unknown>
+ * }} BundleActionInfo
+ */
+
+/**
+ * @typedef {{
+ *   actions: BundleActionInfo[],
+ *   capabilities: string[],
+ *   compatibility: Record<string, unknown>,
+ *   configDefaults: Record<string, unknown>,
+ *   description: string,
+ *   errors: string[],
+ *   extensionPoints: string[],
+ *   id: string,
+ *   manifestPath: string,
+ *   module?: Record<string, unknown>,
+ *   name: string,
+ *   source: Record<string, unknown>,
+ *   valid: boolean,
+ *   version: string
+ * }} BundleInfo
+ */
+
+/**
+ * @typedef {{
+ *   bundle: BundleInfo | null,
+ *   installed: boolean,
+ *   module: Record<string, unknown>
+ * }} BundleInfoResult
+ */
+
 /**
  * @typedef {{
  *   fullName: string,
@@ -665,12 +720,44 @@ function createGitHistoryPreviewRequest(pathOrOptions, commitHash, operation = "
   };
 }
 
+function createBundleListRequest(options = {}) {
+  const input = isPlainObject(options) ? options : {};
+
+  return {
+    area: input.area,
+    ownerId: input.ownerId ?? input.owner_id ?? input.username,
+    search: input.search
+  };
+}
+
+function createBundleInfoRequest(pathOrOptions) {
+  if (isPlainObject(pathOrOptions)) {
+    return {
+      method: "GET",
+      query: {
+        maxLayer: pathOrOptions.maxLayer,
+        ownerId: pathOrOptions.ownerId ?? pathOrOptions.owner_id ?? pathOrOptions.username,
+        path: pathOrOptions.path ?? pathOrOptions.modulePath ?? pathOrOptions.module_path
+      }
+    };
+  }
+
+  return {
+    method: "GET",
+    query: {
+      path: pathOrOptions
+    }
+  };
+}
+
 export function createApiClient(options = {}) {
   const basePath = options.basePath || "/api";
   const inFlightRequestPromises = new Map();
   const queuedFileReadRequests = [];
   const pendingFileReadPromises = new Map();
   const DEDUPED_ENDPOINTS = new Set([
+    "bundle_info",
+    "bundle_list",
     "extensions_load",
     "file_read",
     "file_info",
@@ -994,6 +1081,29 @@ export function createApiClient(options = {}) {
     return call("health");
   }
 
+  /**
+   * List installed customware bundles visible to the current user.
+   *
+   * @param {BundleListOptions} [options]
+   * @returns {Promise<BundleInfo[]>}
+   */
+  async function bundleList(options = {}) {
+    return call("bundle_list", {
+      method: "GET",
+      query: createBundleListRequest(options)
+    });
+  }
+
+  /**
+   * Read bundle metadata for one module path such as `/mod/acme/demo`.
+   *
+   * @param {string | BundleInfoOptions} pathOrOptions
+   * @returns {Promise<BundleInfoResult>}
+   */
+  async function bundleInfo(pathOrOptions) {
+    return call("bundle_info", createBundleInfoRequest(pathOrOptions));
+  }
+
   /**
    * Read an authenticated app file.
    * `fileRead()` accepts app-rooted paths such as `L2/alice/note.txt` and the
@@ -1184,6 +1294,8 @@ export function createApiClient(options = {}) {
   }
 
   return {
+    bundleInfo,
+    bundleList,
     call,
     fileCopy,
     fileDelete,
diff --git a/app/L0/_all/mod/_core/framework/js/bundles.js b/app/L0/_all/mod/_core/framework/js/bundles.js
new file mode 100644
index 00000000..31af70f1
--- /dev/null
+++ b/app/L0/_all/mod/_core/framework/js/bundles.js
@@ -0,0 +1,150 @@
+function normalizeId(value) {
+  return String(value || "").trim();
+}
+
+function cloneAction(action) {
+  return {
+    bundleId: normalizeId(action.bundleId),
+    capability: normalizeId(action.capability),
+    description: normalizeId(action.description),
+    id: normalizeId(action.id),
+    title: normalizeId(action.title || action.name || action.id)
+  };
+}
+
+function dispatchBundleEvent(type, detail) {
+  if (typeof globalThis.CustomEvent !== "function" || !globalThis.window) {
+    return;
+  }
+
+  globalThis.window.dispatchEvent(new globalThis.CustomEvent(type, { detail }));
+}
+
+export function createBundleRuntime(options = {}) {
+  const api = options.api;
+  const actions = new Map();
+  const bridgeSyncHandlers = new Map();
+
+  function requireApi() {
+    if (!api || typeof api.bundleList !== "function" || typeof api.bundleInfo !== "function") {
+      throw new Error("space.bundles requires the framework API client.");
+    }
+
+    return api;
+  }
+
+  async function list(listOptions = {}) {
+    return requireApi().bundleList(listOptions);
+  }
+
+  async function info(pathOrOptions) {
+    return requireApi().bundleInfo(pathOrOptions);
+  }
+
+  function registerAction(action) {
+    const source = action && typeof action === "object" ? action : {};
+    const id = normalizeId(source.id);
+    const title = normalizeId(source.title || source.name || id);
+
+    if (!id || !title || typeof source.run !== "function") {
+      throw new TypeError("Bundle actions require id, title, and run(payload, context).");
+    }
+
+    const entry = {
+      ...cloneAction({ ...source, id, title }),
+      run: source.run
+    };
+
+    actions.set(id, entry);
+    dispatchBundleEvent("space:bundle-action-registered", cloneAction(entry));
+    return () => unregisterAction(id);
+  }
+
+  function unregisterAction(id) {
+    const normalizedId = normalizeId(id);
+    const existing = actions.get(normalizedId);
+
+    if (!existing) {
+      return false;
+    }
+
+    actions.delete(normalizedId);
+    dispatchBundleEvent("space:bundle-action-unregistered", cloneAction(existing));
+    return true;
+  }
+
+  function listActions() {
+    return [...actions.values()].map(cloneAction);
+  }
+
+  function getAction(id) {
+    const entry = actions.get(normalizeId(id));
+    return entry ? cloneAction(entry) : null;
+  }
+
+  async function runAction(id, payload = undefined, context = {}) {
+    const entry = actions.get(normalizeId(id));
+
+    if (!entry) {
+      throw new Error(`Bundle action is not registered: ${String(id || "")}`);
+    }
+
+    return entry.run(payload, {
+      action: cloneAction(entry),
+      payload,
+      ...context
+    });
+  }
+
+  function registerBridgeSync(id, handler) {
+    const normalizedId = normalizeId(id);
+
+    if (!normalizedId || typeof handler !== "function") {
+      throw new TypeError("Bridge sync handlers require id and handler(payload, context).");
+    }
+
+    bridgeSyncHandlers.set(normalizedId, handler);
+    return () => unregisterBridgeSync(normalizedId);
+  }
+
+  function unregisterBridgeSync(id) {
+    return bridgeSyncHandlers.delete(normalizeId(id));
+  }
+
+  async function syncBridgeState(id, payload = undefined, context = {}) {
+    const normalizedId = normalizeId(id);
+    const handler = bridgeSyncHandlers.get(normalizedId);
+
+    dispatchBundleEvent("space:bundle-bridge-sync", {
+      id: normalizedId,
+      payload
+    });
+
+    if (!handler) {
+      return null;
+    }
+
+    return handler(payload, {
+      id: normalizedId,
+      payload,
+      ...context
+    });
+  }
+
+  return {
+    info,
+    list,
+    actions: {
+      get: getAction,
+      list: listActions,
+      register: registerAction,
+      run: runAction,
+      unregister: unregisterAction
+    },
+    bridge: {
+      registerSync: registerBridgeSync,
+      syncState: syncBridgeState,
+      unregisterSync: unregisterBridgeSync
+    }
+  };
+}
diff --git a/app/L0/_all/mod/_core/framework/js/extensions.js b/app/L0/_all/mod/_core/framework/js/extensions.js
index acbf0e96..3e26ae37 100644
--- a/app/L0/_all/mod/_core/framework/js/extensions.js
+++ b/app/L0/_all/mod/_core/framework/js/extensions.js
@@ -67,6 +67,7 @@ const EXTENSION_BATCH_FALLBACK_MS = 32;
 const HTML_EXTENSIONS_LOAD_BATCH_WAIT_MS = 0;
 const HTML_EXTENSION_SCOPE = "html";
 const JS_EXTENSION_SCOPE = "js";
+const FRAMEWORK_THEME_EXTENSION_POINT = "_core/framework/theme/end";
 const FRAMEWORK_HEAD_EXTENSION_POINT = "_core/framework/head/end";
 export const HTML_EXTENSION_READY_ATTRIBUTE = "data-space-extension-ready";
 
@@ -87,7 +88,7 @@ function readCachedValue(area, key) {
   return cache.get(area, key);
 }
 
-function ensureFrameworkHeadExtensionAnchor() {
+function ensureFrameworkHeadExtensionAnchor(id) {
   const head = document.head;
   if (!head) {
     return null;
@@ -96,18 +97,23 @@ function ensureFrameworkHeadExtensionAnchor() {
   const existing = Array.from(head.children).find(
     (child) =>
       child.tagName === "X-EXTENSION" &&
-      child.getAttribute("id") === FRAMEWORK_HEAD_EXTENSION_POINT
+      child.getAttribute("id") === id
   );
   if (existing instanceof HTMLElement) {
     return existing;
   }
 
   const extension = document.createElement("x-extension");
-  extension.setAttribute("id", FRAMEWORK_HEAD_EXTENSION_POINT);
+  extension.setAttribute("id", id);
   head.appendChild(extension);
   return extension;
 }
 
+function ensureFrameworkHeadExtensionAnchors() {
+  ensureFrameworkHeadExtensionAnchor(FRAMEWORK_THEME_EXTENSION_POINT);
+  ensureFrameworkHeadExtensionAnchor(FRAMEWORK_HEAD_EXTENSION_POINT);
+}
+
 function ensureSpaceRuntime() {
   const runtime =
     globalThis.space && typeof globalThis.space === "object"
@@ -760,9 +766,9 @@ const extensionObserverCallback = (mutations) => {
 const extensionObserver = new MutationObserver(extensionObserverCallback);
 extensionObserver.observe(document.documentElement, { childList: true, subtree: true });
 
-// Framework-backed pages always get one head-side HTML seam for declarative
-// tags or inline bootstraps that should not require page-shell edits.
-ensureFrameworkHeadExtensionAnchor();
+// Framework-backed pages always get head-side HTML seams for declarative theme
+// and bootstrap tags that should not require page-shell edits.
+ensureFrameworkHeadExtensionAnchors();
 
 // Do an initial scan for static x-extension tags
 // that already exist in the DOM (index.html), then rely on
diff --git a/app/L0/_all/mod/_core/framework/js/runtime.js b/app/L0/_all/mod/_core/framework/js/runtime.js
index b43edb98..4a5505ec 100644
--- a/app/L0/_all/mod/_core/framework/js/runtime.js
+++ b/app/L0/_all/mod/_core/framework/js/runtime.js
@@ -1,5 +1,6 @@
 import { createApiClient } from "./api-client.js";
 import { createStore } from "./AlpineStore.js";
+import { createBundleRuntime } from "./bundles.js";
 import { downloadProxiedFile } from "./download.js";
 import { installFetchProxy } from "./fetch-proxy.js";
 import * as markdown from "./markdown-frontmatter.js";
@@ -19,6 +20,8 @@ export function initializeRuntime(options = {}) {
     previousRuntime.config && typeof previousRuntime.config === "object" ? previousRuntime.config : {};
   const previousFw =
     previousRuntime.fw && typeof previousRuntime.fw === "object" ? previousRuntime.fw : {};
+  const previousBundles =
+    previousRuntime.bundles && typeof previousRuntime.bundles === "object" ? previousRuntime.bundles : null;
   const previousUtils =
     previousRuntime.utils && typeof previousRuntime.utils === "object" ? previousRuntime.utils : {};
   const previousMarkdownUtils =
@@ -55,6 +58,7 @@ export function initializeRuntime(options = {}) {
       createStore
     },
     chat: previousChat || legacyCurrentChat || undefined,
+    bundles: previousBundles || createBundleRuntime({ api }),
     proxyPath,
     utils: {
       ...previousUtils,
diff --git a/app/L0/_all/mod/_core/skillset/ext/skills/development/AGENTS.md b/app/L0/_all/mod/_core/skillset/ext/skills/development/AGENTS.md
index bedebb81..3778c4f0 100644
--- a/app/L0/_all/mod/_core/skillset/ext/skills/development/AGENTS.md
+++ b/app/L0/_all/mod/_core/skillset/ext/skills/development/AGENTS.md
@@ -62,10 +62,12 @@ Source-doc mirror map:
 - the router skill should tell the agent to use the top-level `documentation` skill's built-in docs map for broad orientation when relevant, while still treating `AGENTS.md` files as the binding contract layer
 - nested skills should stay focused on one area rather than repeating the whole architecture
 - `frontend-runtime/SKILL.md` must keep the shared runtime helper list current, including browser utilities such as `space.utils.markdown.render(...)`
+- `frontend-runtime/SKILL.md` must keep `space.bundles` guidance current when customware-bundle metadata, action, or bridge-sync contracts change
 - `frontend-runtime/SKILL.md` must keep embedded browser-surface guidance current, including direct `<x-browser>` authoring, the `controls` attribute, and automatic `space.browser` registration
 - `frontend-runtime/SKILL.md` must keep the external-fetch guidance current: frontend code should use runtime-managed `fetch(...)` or `space.fetchExternal(...)` and must not hardcode third-party CORS proxy services because the runtime already falls back to `/api/proxy`
+- `extensions-components/SKILL.md` must keep customware-bundle composition guidance current: bundles use normal `ext/html`, `ext/js`, `ext/skills`, theme/head seams, and `space.bundles.actions` instead of runtime injection
 - `extensions-components/SKILL.md` must keep extension lookup batching guidance current, including the HTML-only frontend constant `HTML_EXTENSIONS_LOAD_BATCH_WAIT_MS`, and must keep delayed-target `x-inject` guidance current for route-owned markup that targets shell seams
-- `frontend-runtime/SKILL.md` and `extensions-components/SKILL.md` must keep the framework-managed `_core/framework/head/end` seam aligned with the imperative `_core/framework/initializer.js/initialize/end` fallback guidance
+- `frontend-runtime/SKILL.md` and `extensions-components/SKILL.md` must keep the framework-managed `_core/framework/theme/end` and `_core/framework/head/end` seams aligned with the imperative `_core/framework/initializer.js/initialize/end` fallback guidance
 - `skills/SKILL.md` should tell authors to prefer small skill-local helper imports inside the owning skill folder over long inlined browser scripts when that keeps skill text shorter and more stable
 - `skills/SKILL.md` must keep the shared skill metadata rules current, including `metadata.when`, `metadata.loaded`, `metadata.placement`, and the live `<x-context>` tag contract
 - `skills/SKILL.md` must keep the first-party tag examples current: framework bootstrap emits exactly one runtime context with `data-runtime="browser"` or `data-runtime="app"` and the derived tags `runtime-browser` or `runtime-app`, the overlay emits `onscreen`, the admin shell emits `admin`, and feature modules may add route or state tags such as `route:<current-path>` or `space:open`
diff --git a/app/L0/_all/mod/_core/skillset/ext/skills/development/SKILL.md b/app/L0/_all/mod/_core/skillset/ext/skills/development/SKILL.md
index f066da6c..490c04ab 100644
--- a/app/L0/_all/mod/_core/skillset/ext/skills/development/SKILL.md
+++ b/app/L0/_all/mod/_core/skillset/ext/skills/development/SKILL.md
@@ -10,6 +10,8 @@ Use this skill first for any development task. This is a routing skill: it tells
 
 When the user wants to extend the system with a reusable interface rather than a space widget, prefer a custom routed page module plus an optional `ext/panels/*.yaml` dashboard entry instead of pushing everything into spaces.
 
+When the user wants to package reusable downstream customizations for install, update, or removal as one unit, use the customware-bundle convention: a normal `L1` or `L2` module with `space.bundle.yaml`, normal `ext/html`, `ext/js`, and `ext/skills` seams, and browser commands registered through `space.bundles.actions`.
+
 ## Hard Boundary
 
 - This skill set only authorizes development in `app/`.
@@ -39,6 +41,8 @@ Load for framework-backed pages, Alpine stores, `space.*` runtime usage, shared
 
 Load for `ext/html/`, `ext/js/`, `x-extension`, `x-component`, `x-context`, and layered override behavior.
 
+Also load it for customware bundles that need to turn runtime patches into documented seams.
+
 ### `development/app-files-apis`
 
 Load for `space.api`, app-file storage paths, `file_paths`, `userSelfInfo`, and permission-aware frontend reads or writes.
diff --git a/app/L0/_all/mod/_core/skillset/ext/skills/development/app-files-apis/SKILL.md b/app/L0/_all/mod/_core/skillset/ext/skills/development/app-files-apis/SKILL.md
index 9d5ba63a..9bc99b3c 100644
--- a/app/L0/_all/mod/_core/skillset/ext/skills/development/app-files-apis/SKILL.md
+++ b/app/L0/_all/mod/_core/skillset/ext/skills/development/app-files-apis/SKILL.md
@@ -52,6 +52,7 @@ When a UI needs user-visible download failure feedback without fetching the arch
 - Use permission-aware APIs, not ad hoc browser path guesses.
 - Use `space.api.call("file_paths", { method: "POST", body: { patterns: [...] } })` for indexed glob discovery; add `access: "write"` for writable-only results.
 - Use `space.api.call("module_list", ...)` only when you need module inventory metadata rather than raw file paths.
+- Use `space.api.bundleList(...)`, `space.api.bundleInfo(...)`, or the matching `space.bundles` helpers when you need installed customware-bundle metadata from `space.bundle.yaml`.
 - Use `space.api.call("extensions_load", ...)` when the browser needs module-owned `ext/...` assets resolved with layered override behavior, such as HTML adapters or JS hooks. Keep `maxLayer` at the top level of the call, and when batching grouped lookups send ordered `patterns` entries and read grouped results back in that same order.
 - Use `file_paths` plus `fileRead(...)` for readable module metadata files such as `ext/panels/*.yaml` when you only need logical file discovery and file contents rather than the `extensions_load` response shape.
 
diff --git a/app/L0/_all/mod/_core/skillset/ext/skills/development/backend-reference/SKILL.md b/app/L0/_all/mod/_core/skillset/ext/skills/development/backend-reference/SKILL.md
index 51ae5ec8..f59e642d 100644
--- a/app/L0/_all/mod/_core/skillset/ext/skills/development/backend-reference/SKILL.md
+++ b/app/L0/_all/mod/_core/skillset/ext/skills/development/backend-reference/SKILL.md
@@ -31,7 +31,7 @@ Important frontend-facing endpoint families are:
 
 - app files: `file_list`, `file_paths`, `file_read`, `file_write`, `file_delete`, `file_copy`, `file_move`, `file_info`, `folder_download`
 - local history: `git_history_list`, `git_history_diff`, `git_history_preview`, `git_history_rollback`, `git_history_revert`
-- modules: `module_list`, `module_info`, `module_install`, `module_remove`
+- modules: `bundle_list`, `bundle_info`, `module_list`, `module_info`, `module_install`, `module_remove`
 - runtime and identity: `extensions_load`, `password_generate`, `password_change`, `user_crypto_session_key`, `user_self_info`
 
 These endpoints are thin wrappers over shared helpers in `server/lib/customware/` and `server/lib/auth/`.
@@ -57,6 +57,7 @@ These endpoints are thin wrappers over shared helpers in `server/lib/customware/
 - `/admin` effectively clamps module and extension resolution to `L0`.
 - Frontend HTML extensions resolve through `ext/html/...`.
 - Frontend JS hooks resolve through `ext/js/...`.
+- Customware bundles are normal installed `L1` or `L2` modules with root `space.bundle.yaml` manifests; `bundle_list` and `bundle_info` expose that metadata through the same module-management visibility and owner rules instead of a separate plugin loader.
 - Frontend modules may also enumerate other extension-owned assets such as `ext/panels/*.yaml` through `file_paths` plus `file_read` when they only need readable logical file discovery and contents. `extensions_load` remains the backend contract for HTML and JS extension resolution, keeping `maxLayer` at the top level, ordered `patterns` groups in the request, and ordered grouped results with matching `patterns` plus resolved `extensions`.
 
 ## Auth And User Storage
diff --git a/app/L0/_all/mod/_core/skillset/ext/skills/development/extensions-components/SKILL.md b/app/L0/_all/mod/_core/skillset/ext/skills/development/extensions-components/SKILL.md
index 05f9971f..ecb830d6 100644
--- a/app/L0/_all/mod/_core/skillset/ext/skills/development/extensions-components/SKILL.md
+++ b/app/L0/_all/mod/_core/skillset/ext/skills/development/extensions-components/SKILL.md
@@ -11,7 +11,7 @@ Use this skill when the task needs `ext/html/`, `ext/js/`, `x-extension`, `x-com
 - Matching HTML files live at `mod/<author>/<repo>/ext/html/some/path/*.html`.
 - HTML callers name only the seam; the runtime resolves `ext/html/` automatically.
 - Keep extension files thin. They should usually mount a real component with `<x-component path="/mod/...">`.
-- `_core/framework` also creates `_core/framework/head/end` in `document.head` during bootstrap when a layer needs head-side HTML or inline bootstrap code without editing page shells.
+- `_core/framework` also creates `_core/framework/theme/end` and `_core/framework/head/end` in `document.head` during bootstrap when a layer needs declarative theme CSS, landing or background customization, head-side HTML, or inline bootstrap code without editing page shells.
 - Use framework `x-inject="selector"` instead of raw Alpine `x-teleport` when route-owned markup targets a shell seam that may mount later; it mirrors teleport semantics for `<template>` roots, waits for the selector, and disconnects its observer when the source template unmounts.
 - Dynamic discovery watches the whole document tree, so `head` seams and the `x-component` nodes they insert are loaded the same way as body content.
 - The routed shell header owns Home itself and points it at the empty route `#/`; `_core/onscreen_menu/bar_start` and `_core/onscreen_menu/bar_end` are the left and right shell-control seams, and feature modules add non-Home dropdown menu-action buttons under `_core/onscreen_menu/items` with numeric `data-order` values such as `100`, `200`, `300`, and `400`; `_core/onscreen_menu` sorts contributed controls or items automatically and keeps only the auth exit action after the dropdown seam.
@@ -32,9 +32,17 @@ Example:
 - JS hook files live at `mod/<author>/<repo>/ext/js/<extension-point>/*.js` or `*.mjs`.
 - The runtime resolves `/start` and `/end` hooks around the wrapped function automatically.
 - `space.extend()` requires a valid module ref and a standalone named function or explicit extension point name.
-- Framework-backed pages expose `_core/framework/initializer.js/initialize`; use `_core/framework/head/end` when the work can stay declarative, and keep the initializer `/end` hook for once-per-page shell setup that must stay imperative.
+- Framework-backed pages expose `_core/framework/initializer.js/initialize`; use `_core/framework/theme/end` for declarative theme or background changes, `_core/framework/head/end` when other head-side work can stay declarative, and keep the initializer `/end` hook for once-per-page shell setup that must stay imperative.
 - If a feature needs onscreen-agent-specific prompt shaping or execution validation for its own helpers, add an `ext/js/_core/onscreen_agent/...` hook from that feature instead of editing `_core/onscreen_agent` directly.
 
+## Customware Bundle Rules
+
+- A customware bundle is a normal installed `L1` or `L2` module with a root `space.bundle.yaml`.
+- Bundle manifests describe capabilities, compatibility, config defaults, extension points, and declarative actions; they do not authorize private runtime patching.
+- Bundle UI should use normal `ext/html` seams, bundle behavior should use `ext/js` plus `space.extend(...)`, and bundle skills should live under `ext/skills/*/SKILL.md`.
+- Browser commands should register executable handlers through `space.bundles.actions.register(...)` from loaded module code and unregister when the owning component unmounts.
+- When a bundle needs an integration point that does not exist yet, add a documented seam in the owning module instead of injecting into private DOM, stores, or framework internals.
+
 ## Extension Metadata Rules
 
 - Modules may also store lightweight metadata assets under other `ext/` folders when those files should follow the same readable-layer permissions and same-path override rules as HTML and JS extensions.
diff --git a/app/L0/_all/mod/_core/skillset/ext/skills/development/frontend-runtime/SKILL.md b/app/L0/_all/mod/_core/skillset/ext/skills/development/frontend-runtime/SKILL.md
index dfabb591..249b04a6 100644
--- a/app/L0/_all/mod/_core/skillset/ext/skills/development/frontend-runtime/SKILL.md
+++ b/app/L0/_all/mod/_core/skillset/ext/skills/development/frontend-runtime/SKILL.md
@@ -23,11 +23,12 @@ Use this skill when the task changes browser runtime behavior, framework-backed
 - Framework-backed pages boot through `/mod/_core/framework/js/initFw.js`.
 - The runtime installs onto `globalThis.space`.
 - `initFw.js` runs the extensible framework bootstrap step at `_core/framework/initializer.js/initialize` before Alpine startup.
-- Framework bootstrap also creates `_core/framework/head/end` in `document.head` for declarative head-side tags or inline bootstraps.
-- Use `_core/framework/head/end` when the setup can stay declarative, and use `_core/framework/initializer.js/initialize/end` when the setup must stay imperative instead of editing page shells.
+- Framework bootstrap also creates `_core/framework/theme/end` and `_core/framework/head/end` in `document.head` for declarative theme CSS, landing or background customization, head-side tags, or inline bootstraps.
+- Use `_core/framework/theme/end` for declarative theme or background changes, `_core/framework/head/end` for other declarative head setup, and `_core/framework/initializer.js/initialize/end` when setup must stay imperative instead of editing page shells.
 - Framework-backed pages centrally handle same-origin `/` and `/admin` opens through normal `target="_blank"` link clicks and `window.open(..., "_blank")` by granting the child window the current tab's `/enter` access marker before navigation; context-menu, middle-click, and modifier-key browser opens stay unmodified and still route through `/enter`.
 - Current shared runtime surface includes:
   - `space.api`
+  - `space.bundles` for installed customware-bundle metadata, removable browser-side actions, and external bridge sync handlers
   - `space.config`
   - `space.chat` when the current agent surface publishes the active thread snapshot
   - `space.fw.createStore`
@@ -39,6 +40,8 @@ Use this skill when the task changes browser runtime behavior, framework-backed
   - `space.fetchExternal(...)`
   - `space.browser` for registered browser-surface control; load the top-level `browser-control` skill for the detailed method list and browser-frame bridge usage
 
+Use `space.bundles.actions.register({ id, title, run })` when a loaded customware bundle needs to expose an executable browser command. Unregister the action when the owning component unmounts, and keep action ids stable enough that other bundle UI can call `space.bundles.actions.run(id, payload)`.
+
 Use `<x-browser src="https://example.com"></x-browser>` when frontend UI, pages, or widgets need to embed a live browser surface directly in their DOM. Add `controls="true"` when that surface should render its own address bar and navigation controls; omit it or set `controls="false"` for a frameless embedded browser. Authored `<x-browser>` elements register with `space.browser` automatically, so agents can discover, inspect, navigate, and interact with them the same way they use stand-alone browser windows.
 
 External browser fetches under the framework should try direct `fetch(...)` first and only fall back to `/api/proxy` after a failed cross-origin attempt; when that fallback succeeds, the runtime keeps an in-memory origin cache so later requests to the same origin go through the backend immediately for the rest of the page lifetime.
diff --git a/app/L0/_all/mod/_core/skillset/ext/skills/development/layers-ownership/SKILL.md b/app/L0/_all/mod/_core/skillset/ext/skills/development/layers-ownership/SKILL.md
index 1dc5681f..08b2d057 100644
--- a/app/L0/_all/mod/_core/skillset/ext/skills/development/layers-ownership/SKILL.md
+++ b/app/L0/_all/mod/_core/skillset/ext/skills/development/layers-ownership/SKILL.md
@@ -18,6 +18,7 @@ Use this skill before deciding where new files belong or how readable and writab
 - `L2/<username>/user.yaml` stores user metadata such as `full_name`.
 - `L2/<username>/meta/` holds auth state such as password and login session records.
 - `L2/<username>/mod/` is that user's customware module root.
+- Installed customware bundles live in normal module roots such as `L1/<group>/mod/<author>/<repo>/` or `L2/<username>/mod/<author>/<repo>/` and add a root `space.bundle.yaml` manifest.
 - `L1/<group>/group.yaml` is the canonical group membership and management file.
 - When `CUSTOMWARE_GIT_HISTORY` is enabled, each writable `L1/<group>/` and `L2/<username>/` root may have a server-managed local Git history repository.
 - L2 history ignores `meta/password.json` and `meta/logins.json`; rollback preserves those current auth files and keeps previous heads listable for forward travel when possible, while revert creates a new inverse commit.
diff --git a/app/space-runtime.d.ts b/app/space-runtime.d.ts
index 3a56d8cc..a581a4ee 100644
--- a/app/space-runtime.d.ts
+++ b/app/space-runtime.d.ts
@@ -113,6 +113,54 @@ type SpaceUserSelfInfo = {
   username: string;
 };
 
+type SpaceBundleActionInfo = {
+  bundleId?: string;
+  capability?: string;
+  description?: string;
+  id: string;
+  inputSchema?: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+  title: string;
+};
+
+type SpaceBundleInfo = {
+  actions: SpaceBundleActionInfo[];
+  capabilities: string[];
+  compatibility: Record<string, unknown>;
+  configDefaults: Record<string, unknown>;
+  description: string;
+  errors: string[];
+  extensionPoints: string[];
+  id: string;
+  manifestPath: string;
+  module?: Record<string, unknown>;
+  name: string;
+  source: Record<string, unknown>;
+  valid: boolean;
+  version: string;
+};
+
+type SpaceBundleListOptions = {
+  area?: string;
+  ownerId?: string;
+  search?: string;
+  username?: string;
+};
+
+type SpaceBundleInfoOptions = {
+  maxLayer?: number;
+  modulePath?: string;
+  ownerId?: string;
+  path?: string;
+  username?: string;
+};
+
+type SpaceBundleInfoResult = {
+  bundle: SpaceBundleInfo | null;
+  installed: boolean;
+  module: Record<string, unknown>;
+};
+
 type SpaceGitHistoryFile = {
   action?: "added" | "modified" | "deleted" | string;
   oldPath?: string;
@@ -197,6 +245,8 @@ type SpaceGitHistoryPreviewResult = {
 };
 
 type SpaceApi = {
+  bundleInfo(pathOrOptions: string | SpaceBundleInfoOptions): Promise<SpaceBundleInfoResult>;
+  bundleList(options?: SpaceBundleListOptions): Promise<SpaceBundleInfo[]>;
   call<T = unknown>(endpointName: string, callOptions?: SpaceApiCallOptions): Promise<T>;
   fileCopy(path: string, toPath: string): Promise<SpaceFileApiResult>;
   fileCopy(entry: SpaceFileTransferInput): Promise<SpaceFileApiResult>;
@@ -352,6 +402,31 @@ type SpaceChat = {
   transient: SpaceChatTransient;
 };
 
+type SpaceBundleActionRegistration = SpaceBundleActionInfo & {
+  name?: string;
+  run(payload?: unknown, context?: Record<string, unknown>): unknown | Promise<unknown>;
+};
+
+type SpaceBundlesNamespace = {
+  actions: {
+    get(id: string): SpaceBundleActionInfo | null;
+    list(): SpaceBundleActionInfo[];
+    register(action: SpaceBundleActionRegistration): () => boolean;
+    run(id: string, payload?: unknown, context?: Record<string, unknown>): Promise<unknown>;
+    unregister(id: string): boolean;
+  };
+  bridge: {
+    registerSync(
+      id: string,
+      handler: (payload?: unknown, context?: Record<string, unknown>) => unknown | Promise<unknown>
+    ): () => boolean;
+    syncState(id: string, payload?: unknown, context?: Record<string, unknown>): Promise<unknown>;
+    unregisterSync(id: string): boolean;
+  };
+  info(pathOrOptions: string | SpaceBundleInfoOptions): Promise<SpaceBundleInfoResult>;
+  list(options?: SpaceBundleListOptions): Promise<SpaceBundleInfo[]>;
+};
+
 type SpaceUtils = {
   markdown?: SpaceMarkdownUtils;
   yaml?: SpaceYamlUtils;
@@ -785,6 +860,7 @@ type SpaceBrowserNamespace = {
 type SpaceRuntime = {
   api?: SpaceApi;
   browser?: SpaceBrowserNamespace;
+  bundles?: SpaceBundlesNamespace;
   chat?: SpaceChat;
   current?: SpaceCurrentNamespace | null;
   extend: SpaceExtend;
diff --git a/server/AGENTS.md b/server/AGENTS.md
index 9828c8ff..0f36ac46 100644
--- a/server/AGENTS.md
+++ b/server/AGENTS.md
@@ -113,7 +113,7 @@ Current server layout:
 - `server/router/`: top-level request routing, page handling, `/mod/...` serving, direct app-file fetches, request context, response helpers, proxy transport, and CORS handling
 - `server/lib/utils/process_title.js`: canonical OS process-title helper for direct serve, clustered primary, clustered workers, and supervisor-owned runtime naming
 - `server/lib/utils/project_version.js`: shared project-version resolver for Git-tag source checkouts and package-version fallback display in page shells
-- `server/lib/customware/`: logical app-path normalization, customware-root resolution, group and inheritance logic, extension override resolution, app-file access, and module management
+- `server/lib/customware/`: logical app-path normalization, customware-root resolution, group and inheritance logic, extension override resolution, customware-bundle manifest discovery, app-file access, and module management
 - `server/lib/customware/git_history.js`: optional writable-layer local Git history scheduling, repository discovery, paginated commit listing, file-diff reads, operation previews, rollback, revert, and commit-loop suppression
 - `server/lib/customware/user_quota.js`: optional per-user `L2` folder size accounting and cached quota projection helpers for app-file mutations
 - `server/lib/auth/`: password verification, session service, user file helpers, user indexing, and user-management helpers
@@ -179,7 +179,8 @@ The server relies on a small set of shared infrastructure contracts. Do not re-i
 - `server/lib/share/service.js` is the canonical hosted-share helper for backend-owned ZIP storage under `CUSTOMWARE_PATH/share/spaces/`, archive validation, authenticated imports, and guest-clone session issuance; endpoints and page shells must not duplicate that logic
 - `server/lib/tmp/` owns the canonical `server/tmp/` janitor and disk-backed archive creation for streamed folder downloads
 - `server/lib/customware/module_inheritance.js` and `server/lib/customware/extension_overrides.js` are the canonical module and extension resolution helpers
-- `server/lib/customware/module_manage.js` is the canonical module list, info, install, and remove helper
+- `server/lib/customware/module_manage.js` is the canonical module list, info, install, remove, and customware-bundle listing helper
+- `server/lib/customware/bundles.js` is the canonical `space.bundle.yaml` parser for installed customware module manifests
 - `server/lib/auth/service.js` is the canonical session and login service
 - `server/lib/auth/keys_manage.js` is the canonical backend auth-key loader, with shared-env override support and local `server/data/` or `SPACE_AUTH_DATA_DIR` fallback
 - `server/lib/utils/runtime_params.js` is the canonical parameter-resolution layer for startup env overrides, defaults, and frontend exposure
diff --git a/server/api/AGENTS.md b/server/api/AGENTS.md
index 0475d294..477b0f5e 100644
--- a/server/api/AGENTS.md
+++ b/server/api/AGENTS.md
@@ -102,6 +102,8 @@ Current rules:
 - both `cloud_share_clone` and `space_import` must reuse `server/lib/share/service.js` for archive validation, extracted-folder checks, destination naming, and install logic instead of adding endpoint-local ZIP handling
 
 Module endpoints:
+- `bundle_list`
+- `bundle_info`
 - `module_list`
 - `module_info`
 - `module_install`
@@ -110,6 +112,7 @@ Module endpoints:
 Current rules:
 
 - these endpoints delegate to `server/lib/customware/module_manage.js`
+- `bundle_list` and `bundle_info` expose `space.bundle.yaml` metadata for installed modules while preserving the same module visibility, owner, and admin-access rules as module listing
 - request-time reads should consume replicated shared-state shards instead of calling watchdog scan helpers directly
 - writable operations must reuse the shared permission model and publish concrete changed logical paths through the shared mutation flow so the primary refreshes replicated module state
 - when `USER_FOLDER_SIZE_LIMIT_BYTES` is positive, new `module_install` writes into `L2/<user>/` are measured in a system temp directory and quota-checked before the module tree is moved into the user folder
diff --git a/server/api/bundle_info.js b/server/api/bundle_info.js
new file mode 100644
index 00000000..9eb52173
--- /dev/null
+++ b/server/api/bundle_info.js
@@ -0,0 +1,67 @@
+import { createHttpError } from "../lib/customware/file_access.js";
+import { normalizeMaxLayer } from "../lib/customware/layer_limit.js";
+import { readBundleInfo } from "../lib/customware/module_manage.js";
+
+function readPayload(context) {
+  return context.body && typeof context.body === "object" && !Buffer.isBuffer(context.body)
+    ? context.body
+    : {};
+}
+
+function readInfoPath(context) {
+  const payload = readPayload(context);
+
+  return String(
+    context.params.path ||
+      context.params.modulePath ||
+      context.params.module_path ||
+      payload.path ||
+      payload.modulePath ||
+      payload.module_path ||
+      ""
+  );
+}
+
+function readMaxLayer(context) {
+  const payload = readPayload(context);
+
+  return normalizeMaxLayer(payload.maxLayer ?? context.params.maxLayer);
+}
+
+function readOwnerId(context) {
+  const payload = readPayload(context);
+
+  return String(
+    payload.ownerId ||
+      payload.owner_id ||
+      payload.username ||
+      context.params.ownerId ||
+      context.params.owner_id ||
+      context.params.username ||
+      ""
+  ).trim();
+}
+
+async function read(context) {
+  try {
+    return await readBundleInfo({
+      maxLayer: readMaxLayer(context),
+      ownerId: readOwnerId(context),
+      path: readInfoPath(context),
+      projectRoot: context.projectRoot,
+      runtimeParams: context.runtimeParams,
+      stateSystem: context.stateSystem,
+      username: context.user?.username,
+    });
+  } catch (error) {
+    throw createHttpError(error.message || "Bundle info lookup failed.", Number(error.statusCode) || 500);
+  }
+}
+
+export async function get(context) {
+  return read(context);
+}
+
+export async function post(context) {
+  return read(context);
+}
diff --git a/server/api/bundle_list.js b/server/api/bundle_list.js
new file mode 100644
index 00000000..0ce7b2d8
--- /dev/null
+++ b/server/api/bundle_list.js
@@ -0,0 +1,35 @@
+import { createHttpError } from "../lib/customware/file_access.js";
+import { listInstalledBundles } from "../lib/customware/module_manage.js";
+
+function readListArea(context) {
+  return String(context.params.area || "").trim();
+}
+
+function readListOwnerId(context) {
+  return String(
+    context.params.ownerId ||
+      context.params.owner_id ||
+      context.params.username ||
+      ""
+  ).trim();
+}
+
+function readListSearch(context) {
+  return String(context.params.search || "").trim();
+}
+
+export async function get(context) {
+  try {
+    return await listInstalledBundles({
+      area: readListArea(context),
+      ownerId: readListOwnerId(context),
+      projectRoot: context.projectRoot,
+      runtimeParams: context.runtimeParams,
+      search: readListSearch(context),
+      stateSystem: context.stateSystem,
+      username: context.user?.username,
+    });
+  } catch (error) {
+    throw createHttpError(error.message || "Bundle list failed.", Number(error.statusCode) || 500);
+  }
+}
diff --git a/server/lib/customware/AGENTS.md b/server/lib/customware/AGENTS.md
index e7a02d31..200bf93f 100644
--- a/server/lib/customware/AGENTS.md
+++ b/server/lib/customware/AGENTS.md
@@ -20,6 +20,7 @@ Current files:
 - `group_files.js`: normalized `L1/<group>/group.yaml` read and write helpers used by CLI-managed group editing; membership adds ensure the target writable group directory exists first
 - `group_index.js`: derived group membership and management graph from `group.yaml`
 - `overrides.js`: inheritance ranking, accessible module collection, and override selection
+- `bundles.js`: `space.bundle.yaml` manifest parsing and normalization for customware bundles installed as normal modules
 - `module_inheritance.js`: `/mod/...` file resolution through layered overrides
 - `extension_overrides.js`: extension request-path resolution and ordered grouped extension lookup results keyed by requested pattern groups rather than synthetic ids
 - `file_access.js`: canonical app-file permission model, file operations, and readable-folder download resolution
@@ -118,6 +119,14 @@ Rules:
 - module metadata lookup
 - Git-backed installs and updates
 - module removal
+- customware bundle listing and bundle info lookup through installed module manifests
+
+Customware bundle rules:
+
+- a bundle is a normal readable `L1` or `L2` module with a root `space.bundle.yaml`
+- bundle discovery must use the same module indexes, group permissions, owner filtering, and `CUSTOMWARE_PATH` resolution as module discovery
+- bundle manifests may declare id, name, version, description, compatibility, capabilities, config defaults, extension points, and declarative action metadata
+- bundle manifests do not grant arbitrary runtime patching privileges; executable behavior still enters through documented module seams such as `ext/html`, `ext/js`, `ext/skills`, `space.extend(...)`, and browser-side `space.bundles.actions`
 
 Module Git rules:
 
diff --git a/server/lib/customware/bundles.js b/server/lib/customware/bundles.js
new file mode 100644
index 00000000..8fb40283
--- /dev/null
+++ b/server/lib/customware/bundles.js
@@ -0,0 +1,146 @@
+import { promises as fsPromises } from "node:fs";
+import path from "node:path";
+
+import { parseSimpleYaml } from "../../../app/L0/_all/mod/_core/framework/js/yaml-lite.js";
+
+const BUNDLE_MANIFEST_FILENAME = "space.bundle.yaml";
+const BUNDLE_ID_PATTERN = /^[a-z0-9][a-z0-9._/-]{0,127}$/u;
+
+function normalizeString(value) {
+  return String(value ?? "").trim();
+}
+
+function normalizeObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function normalizeStringList(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeString(item)).filter(Boolean);
+  }
+
+  if (value && typeof value === "object") {
+    return Object.entries(value)
+      .filter(([, enabled]) => enabled !== false && enabled !== null)
+      .map(([key]) => normalizeString(key))
+      .filter(Boolean);
+  }
+
+  const normalized = normalizeString(value);
+  return normalized ? [normalized] : [];
+}
+
+function normalizeAction(action, bundleId) {
+  const source = normalizeObject(action);
+  const id = normalizeString(source.id);
+  const title = normalizeString(source.title || source.name || id);
+
+  if (!id || !title) {
+    return null;
+  }
+
+  return {
+    bundleId,
+    capability: normalizeString(source.capability),
+    description: normalizeString(source.description),
+    id,
+    inputSchema: normalizeObject(source.input_schema || source.inputSchema),
+    outputSchema: normalizeObject(source.output_schema || source.outputSchema),
+    title
+  };
+}
+
+function normalizeActions(actions, bundleId) {
+  return Array.isArray(actions)
+    ? actions.map((action) => normalizeAction(action, bundleId)).filter(Boolean)
+    : [];
+}
+
+function createInvalidManifest(error, moduleEntry = {}) {
+  return {
+    actions: [],
+    capabilities: [],
+    compatibility: {},
+    configDefaults: {},
+    description: "",
+    errors: [error.message || "Bundle manifest could not be parsed."],
+    extensionPoints: [],
+    id: `${moduleEntry.authorId || "unknown"}/${moduleEntry.repositoryId || "unknown"}`,
+    manifestPath: BUNDLE_MANIFEST_FILENAME,
+    name: "",
+    source: createBundleSource(moduleEntry),
+    valid: false,
+    version: ""
+  };
+}
+
+function createBundleSource(moduleEntry = {}) {
+  return {
+    authorId: normalizeString(moduleEntry.authorId),
+    layer: normalizeString(moduleEntry.layer),
+    ownerId: normalizeString(moduleEntry.ownerId),
+    ownerType: normalizeString(moduleEntry.ownerType),
+    path: normalizeString(moduleEntry.path),
+    repositoryId: normalizeString(moduleEntry.repositoryId),
+    requestPath: normalizeString(moduleEntry.requestPath)
+  };
+}
+
+function normalizeManifest(rawManifest, moduleEntry = {}) {
+  const source = normalizeObject(rawManifest);
+  const id = normalizeString(source.id || `${moduleEntry.authorId}/${moduleEntry.repositoryId}`);
+  const errors = [];
+
+  if (!BUNDLE_ID_PATTERN.test(id)) {
+    errors.push(
+      "Bundle id must start with a lowercase letter or number and may contain lowercase letters, numbers, '.', '_', '-', or '/'."
+    );
+  }
+
+  const actions = normalizeActions(source.actions, id);
+  const manifest = {
+    actions,
+    capabilities: normalizeStringList(source.capabilities),
+    compatibility: normalizeObject(source.compatibility),
+    configDefaults: normalizeObject(source.config_defaults || source.configDefaults),
+    description: normalizeString(source.description),
+    errors,
+    extensionPoints: normalizeStringList(source.extension_points || source.extensionPoints),
+    id,
+    manifestPath: BUNDLE_MANIFEST_FILENAME,
+    name: normalizeString(source.name || id),
+    source: createBundleSource(moduleEntry),
+    valid: errors.length === 0,
+    version: normalizeString(source.version)
+  };
+
+  return manifest;
+}
+
+async function readBundleManifestAtModulePath(absolutePath, moduleEntry = {}) {
+  const modulePath = normalizeString(absolutePath);
+
+  if (!modulePath) {
+    return null;
+  }
+
+  try {
+    const manifestText = await fsPromises.readFile(
+      path.join(modulePath, BUNDLE_MANIFEST_FILENAME),
+      "utf8"
+    );
+    return normalizeManifest(parseSimpleYaml(manifestText), moduleEntry);
+  } catch (error) {
+    if (error?.code === "ENOENT" || error?.code === "ENOTDIR") {
+      return null;
+    }
+
+    return createInvalidManifest(error, moduleEntry);
+  }
+}
+
+export {
+  BUNDLE_MANIFEST_FILENAME,
+  normalizeManifest,
+  readBundleManifestAtModulePath
+};
diff --git a/server/lib/customware/module_manage.js b/server/lib/customware/module_manage.js
index bf8cbb15..348a3d3c 100644
--- a/server/lib/customware/module_manage.js
+++ b/server/lib/customware/module_manage.js
@@ -6,6 +6,7 @@ import path from "node:path";
 import { FILE_INDEX_AREA } from "../../runtime/state_areas.js";
 import { cloneGitRepository, createGitClient } from "../git/client_create.js";
 import { sanitizeRemoteUrl } from "../git/shared.js";
+import { readBundleManifestAtModulePath } from "./bundles.js";
 import { createAppAccessController, createHttpError, toAppRelativePath } from "./file_access.js";
 import { recordAppPathMutations } from "./git_history.js";
 import { getLayerOrder, normalizeMaxLayer } from "./layer_limit.js";
@@ -639,24 +640,32 @@ async function resolveInstalledLocations(options = {}) {
   const locations = await mapWithConcurrencyLimit(
     visibleEntries,
     GIT_INFO_CONCURRENCY,
-    async (entry) => ({
-      authorId: entry.authorId,
-      canRead: entry.canRead,
-      canWrite: entry.canWrite,
-      effective: selectedEntryMap.has(entry.projectPath),
-      git: await readModuleGitInfo({
-        absolutePath: createAbsolutePath(options.projectRoot, entry.projectPath, options.runtimeParams),
-        runtimeParams: options.runtimeParams
-      }),
-      layer: entry.layer,
-      ownerId: entry.ownerId,
-      ownerType: entry.ownerType,
-      path: toAppRelativePath(entry.projectPath),
-      rank: selectedEntryMap.get(entry.projectPath)?.rank ?? null,
-      requestPath: entry.requestPath,
-      repositoryId: entry.repositoryId,
-      selected: selectedEntryMap.get(entry.projectPath)?.selected === true
-    })
+    async (entry) => {
+      const absolutePath = createAbsolutePath(options.projectRoot, entry.projectPath, options.runtimeParams);
+      const location = {
+        authorId: entry.authorId,
+        canRead: entry.canRead,
+        canWrite: entry.canWrite,
+        effective: selectedEntryMap.has(entry.projectPath),
+        git: await readModuleGitInfo({
+          absolutePath,
+          runtimeParams: options.runtimeParams
+        }),
+        layer: entry.layer,
+        ownerId: entry.ownerId,
+        ownerType: entry.ownerType,
+        path: toAppRelativePath(entry.projectPath),
+        rank: selectedEntryMap.get(entry.projectPath)?.rank ?? null,
+        requestPath: entry.requestPath,
+        repositoryId: entry.repositoryId,
+        selected: selectedEntryMap.get(entry.projectPath)?.selected === true
+      };
+
+      return {
+        ...location,
+        bundle: await readBundleManifestAtModulePath(absolutePath, location)
+      };
+    }
   );
 
   return locations.sort(compareResolvedModuleLocations);
@@ -682,10 +691,12 @@ async function readModuleInfo(options = {}) {
   const selectedLocation = locations.find((location) => location.selected) || null;
 
   return {
+    bundle: selectedLocation ? selectedLocation.bundle : null,
     installed: locations.length > 0,
     locations,
     modulePath: moduleReference.requestPath.slice(1),
     requestPath: moduleReference.requestPath,
+    selectedLocation,
     selectedPath: selectedLocation ? selectedLocation.path : ""
   };
 }
@@ -788,19 +799,20 @@ async function listInstalledModules(options = {}) {
       GIT_INFO_CONCURRENCY,
       async (groupedEntry) => {
         const representativeEntry = groupedEntry.entries[0];
+        const absolutePath = createAbsolutePath(
+          options.projectRoot,
+          representativeEntry.projectPath,
+          options.runtimeParams
+        );
         const ownerPreview = [...groupedEntry.ownerIds].sort((left, right) => left.localeCompare(right)).slice(0, 3);
 
-        return {
+        const listEntry = {
           aggregated: true,
           authorId: groupedEntry.authorId,
           canRead: groupedEntry.canRead,
           canWrite: false,
           git: await readModuleGitInfo({
-            absolutePath: createAbsolutePath(
-              options.projectRoot,
-              representativeEntry.projectPath,
-              options.runtimeParams
-            ),
+            absolutePath,
             runtimeParams: options.runtimeParams
           }),
           id: createModuleListItemId(groupedEntry, {
@@ -816,6 +828,11 @@ async function listInstalledModules(options = {}) {
           requestPath: groupedEntry.requestPath,
           repositoryId: groupedEntry.repositoryId
         };
+
+        return {
+          ...listEntry,
+          bundle: await readBundleManifestAtModulePath(absolutePath, listEntry)
+        };
       }
     );
   }
@@ -823,32 +840,78 @@ async function listInstalledModules(options = {}) {
   return mapWithConcurrencyLimit(
     entries,
     GIT_INFO_CONCURRENCY,
-    async (entry) => ({
-      aggregated: false,
-      authorId: entry.authorId,
-      canRead: entry.canRead,
-      canWrite: entry.canWrite,
-      git: await readModuleGitInfo({
-        absolutePath: createAbsolutePath(options.projectRoot, entry.projectPath, options.runtimeParams),
-        runtimeParams: options.runtimeParams
-      }),
-      id: createModuleListItemId(entry, {
-        area
-      }),
-      layer: entry.layer,
-      ownerId: entry.ownerId,
-      ownerType: entry.ownerType,
-      ownerCount: 1,
-      path: toAppRelativePath(entry.projectPath),
-      requestPath: entry.requestPath,
-      repositoryId: entry.repositoryId
-    })
+    async (entry) => {
+      const absolutePath = createAbsolutePath(options.projectRoot, entry.projectPath, options.runtimeParams);
+      const listEntry = {
+        aggregated: false,
+        authorId: entry.authorId,
+        canRead: entry.canRead,
+        canWrite: entry.canWrite,
+        git: await readModuleGitInfo({
+          absolutePath,
+          runtimeParams: options.runtimeParams
+        }),
+        id: createModuleListItemId(entry, {
+          area
+        }),
+        layer: entry.layer,
+        ownerId: entry.ownerId,
+        ownerType: entry.ownerType,
+        ownerCount: 1,
+        path: toAppRelativePath(entry.projectPath),
+        requestPath: entry.requestPath,
+        repositoryId: entry.repositoryId
+      };
+
+      return {
+        ...listEntry,
+        bundle: await readBundleManifestAtModulePath(absolutePath, listEntry)
+      };
+    }
   );
 }
 
+async function listInstalledBundles(options = {}) {
+  const modules = await listInstalledModules(options);
+
+  return modules
+    .filter((entry) => entry.bundle)
+    .map((entry) => ({
+      ...entry.bundle,
+      module: {
+        aggregated: entry.aggregated === true,
+        authorId: entry.authorId,
+        canRead: entry.canRead,
+        canWrite: entry.canWrite,
+        id: entry.id,
+        layer: entry.layer,
+        ownerCount: entry.ownerCount,
+        ownerId: entry.ownerId,
+        ownerPreview: entry.ownerPreview || [],
+        ownerType: entry.ownerType,
+        path: entry.path,
+        requestPath: entry.requestPath,
+        repositoryId: entry.repositoryId
+      }
+    }));
+}
+
+async function readBundleInfo(options = {}) {
+  const moduleInfo = await readModuleInfo(options);
+  const bundle = moduleInfo.bundle || moduleInfo.locations.find((location) => location.bundle)?.bundle || null;
+
+  return {
+    bundle,
+    installed: Boolean(bundle),
+    module: moduleInfo
+  };
+}
+
 export {
   installModule,
+  listInstalledBundles,
   listInstalledModules,
   normalizeModuleTargetPath,
+  readBundleInfo,
   readModuleInfo
 };
diff --git a/tests/AGENTS.md b/tests/AGENTS.md
index 072e67ad..f7a5db95 100644
--- a/tests/AGENTS.md
+++ b/tests/AGENTS.md
@@ -12,6 +12,7 @@ Keep test workflows explicit scriptable and isolated from app runtime behavior u
 
 Current deeper docs:
 
+- `tests/fixtures/AGENTS.md`
 - `tests/agent_llm_performance/AGENTS.md`
 - `tests/browser_component_harness/AGENTS.md`
 - `tests/agent_llm_performance_structured/AGENTS.md`
@@ -20,6 +21,7 @@ Current deeper docs:
 Parent vs child split:
 
 - this file owns the top-level test layout and shared test-workflow boundaries
+- `fixtures/AGENTS.md` owns durable hand-authored fixture folders such as the customware-bundle reference manifest
 - `agent_llm_performance/AGENTS.md` owns the LLM prompt-performance harness, its config, cases, prompts, and scoring rules
 - `browser_component_harness/AGENTS.md` owns the standalone Electron browser-component harness under `tests/browser_component_harness/`
 - `agent_llm_performance_structured/AGENTS.md` owns the structured-output LLM prompt-performance harness, its schema contract, cases, prompts, and scoring rules
@@ -48,6 +50,8 @@ This scope owns:
 - `browser_desktop_harness_test.mjs`: regression coverage for the standalone browser-component harness against the Novinky consent flow
 - `browser_skill_contract_test.mjs`: focused frontend-skill coverage for the onscreen `browser-manager` auto-load metadata, the `browser-control` `browser:open` auto-load gate, and the browser overlay `x-context` export that makes that gate work
 - `customware_git_history_test.mjs`: focused server-side harness for optional writable-layer Git history, adaptive debounce rules, primary-owned scheduling, per-repo queue serialization, repository discovery, pagination, nested filename filters with full file metadata, diff reads, operation previews, revert, ignore rules, rollback or forward-travel preservation, filtered-list `total: null` behavior, explicit `409` revert-conflict coverage, successful non-overlapping isomorphic revert coverage, and runtime-param-selected isomorphic-backend coverage for Time Travel diff, preview, rollback, and revert flows
+- `customware_bundle_test.mjs`: focused coverage for `space.bundle.yaml` manifest discovery through installed modules, bundle metadata exposure on module list/info helpers, invalid-manifest reporting, and the browser-side `space.bundles` action and bridge sync registries
+- `fixtures/customware_bundle_example/`: minimal reference customware-bundle manifest copied by bundle tests into temporary `L1` or `L2` module roots; it is fixture content, not product behavior
 - `desktop_packaging_test.mjs`: focused packaging-runtime coverage for the packaged desktop host storage overrides so bundled desktop builds keep transient temp artifacts under a writable OS temp root, preserve the rebrand-stable packaged `userData` tree, keep backend-only auth fallback data under that user-data root instead of the installed app tree, keep the packaged updater log rooted at `<userData>/logs/desktop-updater.log`, keep Windows on the stock direct updater handoff while hardening the NSIS installer-side running-app shutdown path, detect malformed Windows updater metadata that omits the current arch installer and preserve the canonical fallback asset naming used to recover from it, stage same-version or downgrade debug reinstalls against canonical GitHub Release metadata, and clean stale updater `pending/` payloads after a marked install handoff without deleting reusable cache metadata
 - `extensions_load_request_shape_test.mjs`: focused frontend-loader request-shape coverage for top-level `maxLayer`, ordered grouped `patterns`, and grouped `extensions_load` responses without synthetic transport keys
 - `assistant_message_evaluation_test.mjs`: focused frontend agent-runtime coverage for repeated-assistant-message loop detection, severity escalation, normalization of exact-message matches, and safe prepending of synthetic transcript logs ahead of real execution console output
diff --git a/tests/customware_bundle_test.mjs b/tests/customware_bundle_test.mjs
new file mode 100644
index 00000000..50352510
--- /dev/null
+++ b/tests/customware_bundle_test.mjs
@@ -0,0 +1,219 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+import { createBundleRuntime } from "../app/L0/_all/mod/_core/framework/js/bundles.js";
+import { listInstalledBundles, listInstalledModules, readBundleInfo } from "../server/lib/customware/module_manage.js";
+import { createStateSystem } from "../server/runtime/state_system.js";
+import {
+  FILE_INDEX_AREA,
+  GROUP_INDEX_AREA,
+  GROUP_META_AREA,
+  GROUP_USER_INDEX_AREA
+} from "../server/runtime/state_areas.js";
+
+const CUSTOMWARE_BUNDLE_FIXTURE_PATH = fileURLToPath(
+  new URL("./fixtures/customware_bundle_example/", import.meta.url)
+);
+
+function createRuntimeParams(values = {}) {
+  return {
+    get(name, fallbackValue = undefined) {
+      return Object.prototype.hasOwnProperty.call(values, name) ? values[name] : fallbackValue;
+    }
+  };
+}
+
+function copyDirectory(projectRoot, appPath, sourcePath) {
+  const absolutePath = path.join(projectRoot, "app", ...appPath.split("/"));
+  fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+  fs.cpSync(sourcePath, absolutePath, { recursive: true });
+}
+
+function writeFile(projectRoot, appPath, content) {
+  const absolutePath = path.join(projectRoot, "app", ...appPath.split("/"));
+  fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+  fs.writeFileSync(absolutePath, content, "utf8");
+}
+
+function seedBundleState() {
+  const stateSystem = createStateSystem();
+
+  stateSystem.setEntry(GROUP_INDEX_AREA, "team", {
+    groupId: "team",
+    includesAllUsers: false,
+    memberUsers: ["alice"]
+  });
+  stateSystem.setEntry(GROUP_META_AREA, "errors", []);
+  stateSystem.setEntry(GROUP_META_AREA, "inclusion_cycles", []);
+  stateSystem.setEntry(GROUP_USER_INDEX_AREA, "alice", {
+    username: "alice",
+    groups: ["team"],
+    managedGroups: []
+  });
+  stateSystem.setEntry(FILE_INDEX_AREA, "L1/team", {
+    "/app/L1/team/mod/example/customware_bundle_example/": {
+      isDirectory: true,
+      mtimeMs: 1,
+      sizeBytes: 0
+    },
+    "/app/L1/team/mod/example/customware_bundle_example/space.bundle.yaml": {
+      isDirectory: false,
+      mtimeMs: 1,
+      sizeBytes: 300
+    }
+  });
+  stateSystem.setEntry(FILE_INDEX_AREA, "L2/alice", {
+    "/app/L2/alice/mod/acme/invalid/": {
+      isDirectory: true,
+      mtimeMs: 1,
+      sizeBytes: 0
+    },
+    "/app/L2/alice/mod/acme/invalid/space.bundle.yaml": {
+      isDirectory: false,
+      mtimeMs: 1,
+      sizeBytes: 20
+    }
+  });
+
+  return stateSystem;
+}
+
+test("customware bundles are discovered from installed module manifests", async (t) => {
+  const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "space-bundle-test-"));
+  t.after(() => fs.rmSync(projectRoot, { force: true, recursive: true }));
+
+  copyDirectory(
+    projectRoot,
+    "L1/team/mod/example/customware_bundle_example",
+    CUSTOMWARE_BUNDLE_FIXTURE_PATH
+  );
+  writeFile(projectRoot, "L2/alice/mod/acme/invalid/space.bundle.yaml", "id: Bad Bundle\n");
+
+  const runtimeParams = createRuntimeParams();
+  const stateSystem = seedBundleState();
+
+  const bundles = await listInstalledBundles({
+    area: "l1",
+    projectRoot,
+    runtimeParams,
+    stateSystem,
+    username: "alice"
+  });
+
+  assert.equal(bundles.length, 1);
+  assert.equal(bundles[0].id, "example/customware-bundle");
+  assert.equal(bundles[0].valid, true);
+  assert.deepEqual(bundles[0].capabilities, ["theme", "actions"]);
+  assert.deepEqual(
+    bundles[0].actions.map((action) => [action.id, action.title, action.bundleId]),
+    [["example.bundle.ping", "Example bundle ping", "example/customware-bundle"]]
+  );
+  assert.equal(bundles[0].module.path, "L1/team/mod/example/customware_bundle_example/");
+
+  const moduleEntries = await listInstalledModules({
+    area: "l1",
+    projectRoot,
+    runtimeParams,
+    stateSystem,
+    username: "alice"
+  });
+  assert.equal(moduleEntries[0].bundle.id, "example/customware-bundle");
+});
+
+test("customware bundle info returns selected module metadata and invalid manifest errors", async (t) => {
+  const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "space-bundle-test-"));
+  t.after(() => fs.rmSync(projectRoot, { force: true, recursive: true }));
+
+  copyDirectory(
+    projectRoot,
+    "L1/team/mod/example/customware_bundle_example",
+    CUSTOMWARE_BUNDLE_FIXTURE_PATH
+  );
+  writeFile(projectRoot, "L2/alice/mod/acme/invalid/space.bundle.yaml", "id: Bad Bundle\n");
+
+  const runtimeParams = createRuntimeParams();
+  const stateSystem = seedBundleState();
+
+  const info = await readBundleInfo({
+    maxLayer: 1,
+    path: "/mod/example/customware_bundle_example",
+    projectRoot,
+    runtimeParams,
+    stateSystem,
+    username: "alice"
+  });
+  assert.equal(info.installed, true);
+  assert.equal(info.bundle.id, "example/customware-bundle");
+  assert.equal(info.module.selectedPath, "L1/team/mod/example/customware_bundle_example/");
+
+  const invalidBundles = await listInstalledBundles({
+    area: "l2_self",
+    projectRoot,
+    runtimeParams,
+    stateSystem,
+    username: "alice"
+  });
+  assert.equal(invalidBundles.length, 1);
+  assert.equal(invalidBundles[0].valid, false);
+  assert.match(invalidBundles[0].errors.join("\n"), /Bundle id must start/u);
+});
+
+test("browser bundle runtime registers removable actions and bridge sync handlers", async () => {
+  const apiCalls = [];
+  const runtime = createBundleRuntime({
+    api: {
+      bundleInfo(pathOrOptions) {
+        apiCalls.push(["info", pathOrOptions]);
+        return Promise.resolve({ bundle: null, installed: false, module: {} });
+      },
+      bundleList(options) {
+        apiCalls.push(["list", options]);
+        return Promise.resolve([]);
+      }
+    }
+  });
+
+  assert.deepEqual(await runtime.list({ area: "l1" }), []);
+  assert.deepEqual(apiCalls[0], ["list", { area: "l1" }]);
+
+  const unregisterAction = runtime.actions.register({
+    bundleId: "acme/fleet",
+    id: "fleet.open",
+    title: "Open fleet",
+    async run(payload, context) {
+      return {
+        actionId: context.action.id,
+        payload
+      };
+    }
+  });
+
+  assert.deepEqual(runtime.actions.list(), [
+    {
+      bundleId: "acme/fleet",
+      capability: "",
+      description: "",
+      id: "fleet.open",
+      title: "Open fleet"
+    }
+  ]);
+  assert.deepEqual(await runtime.actions.run("fleet.open", { node: "orchestrator" }), {
+    actionId: "fleet.open",
+    payload: { node: "orchestrator" }
+  });
+  assert.equal(unregisterAction(), true);
+  assert.equal(runtime.actions.get("fleet.open"), null);
+
+  const unregisterSync = runtime.bridge.registerSync("hermes", (payload) => ({
+    received: payload
+  }));
+  assert.deepEqual(await runtime.bridge.syncState("hermes", { online: true }), {
+    received: { online: true }
+  });
+  assert.equal(unregisterSync(), true);
+  assert.equal(await runtime.bridge.syncState("hermes", { online: false }), null);
+});
diff --git a/tests/fixtures/AGENTS.md b/tests/fixtures/AGENTS.md
new file mode 100644
index 00000000..2c010b27
--- /dev/null
+++ b/tests/fixtures/AGENTS.md
@@ -0,0 +1,24 @@
+# AGENTS
+
+## Purpose
+
+`tests/fixtures/` owns small, hand-authored files that test harnesses copy into temporary project roots.
+
+Fixtures in this folder are durable reference inputs, not runtime state. Keep them readable, deterministic, and independent from the real `app/L1` or `app/L2` writable layers.
+
+## Ownership
+
+Current fixture folders:
+
+- `customware_bundle_example/`: minimal reference customware-bundle module used by bundle discovery tests and documentation.
+
+## Local Contracts
+
+- Do not store generated output or local verification artifacts here.
+- Fixtures must be safe to copy into a temporary project root during tests.
+- Prefer explicit README or AGENTS notes for each fixture folder so future agents know whether it is a runtime example, parser fixture, or regression case.
+
+## Development Guidance
+
+- Keep fixture contents small and hand-authored.
+- Update `tests/AGENTS.md` when adding or repurposing a fixture family.
diff --git a/tests/fixtures/customware_bundle_example/AGENTS.md b/tests/fixtures/customware_bundle_example/AGENTS.md
new file mode 100644
index 00000000..ecc53493
--- /dev/null
+++ b/tests/fixtures/customware_bundle_example/AGENTS.md
@@ -0,0 +1,25 @@
+# AGENTS
+
+## Purpose
+
+`customware_bundle_example/` is a minimal reference implementation of a Customware Bundle Interface manifest.
+
+It is intentionally a fixture, not a bundled product feature. Tests copy this folder into temporary `L1/<group>/mod/...` roots to verify manifest discovery without checking sample writable-layer content into `app/L1` or `app/L2`.
+
+## Ownership
+
+This folder owns:
+
+- `space.bundle.yaml`: the reference bundle manifest.
+- `README.md`: installation and extension notes for humans and agents reading the fixture.
+
+## Local Contracts
+
+- Keep the manifest valid and small.
+- Do not add behavior here that silently changes the running app.
+- If the example grows real `ext/html`, `ext/js`, or `ext/skills` files, document those folders here and keep them clearly marked as reference behavior.
+
+## Development Guidance
+
+- Use this fixture to demonstrate manifest shape and discovery only.
+- Runtime action handlers still belong in normal module code and must register through `space.bundles.actions`.
diff --git a/tests/fixtures/customware_bundle_example/README.md b/tests/fixtures/customware_bundle_example/README.md
new file mode 100644
index 00000000..1c217b0a
--- /dev/null
+++ b/tests/fixtures/customware_bundle_example/README.md
@@ -0,0 +1,10 @@
+# Customware Bundle Example
+
+This is a tiny reference bundle fixture. Copy it into a normal customware module root to test discovery:
+
+```txt
+L1/team/mod/example/customware_bundle_example/
+L2/alice/mod/example/customware_bundle_example/
+```
+
+The manifest advertises the seams a bundle may use. Executable behavior still enters through normal module files such as `ext/html`, `ext/js`, `ext/skills`, and runtime registration through `space.bundles.actions`.
diff --git a/tests/fixtures/customware_bundle_example/space.bundle.yaml b/tests/fixtures/customware_bundle_example/space.bundle.yaml
new file mode 100644
index 00000000..fe4819f2
--- /dev/null
+++ b/tests/fixtures/customware_bundle_example/space.bundle.yaml
@@ -0,0 +1,18 @@
+id: example/customware-bundle
+name: Example Customware Bundle
+version: 0.1.0
+description: Minimal reference manifest for the Customware Bundle Interface.
+capabilities:
+  - theme
+  - actions
+extension_points:
+  - _core/framework/theme/end
+compatibility:
+  space_agent: ">=0.65"
+config_defaults:
+  accent: mint
+actions:
+  - id: example.bundle.ping
+    title: Example bundle ping
+    capability: actions
+    description: Demonstrates declarative action metadata; runtime code registers the handler through space.bundles.actions.

From a08a909d64edd03bad299a70bcfdb20f26111687 Mon Sep 17 00:00:00 2001
From: Magaav <magaav@colmeio.com>
Date: Wed, 29 Apr 2026 14:12:11 +0000
Subject: [PATCH 2/2] feature(customware): add component context menu bundle

---
 AGENTS.md                                     |   3 +
 .../docs/app/customware-bundles.md            |  32 +-
 tests/AGENTS.md                               |   1 +
 tests/customware_bundle_test.mjs              |  77 +++
 tests/fixtures/AGENTS.md                      |   2 +
 .../component_context_menu_bundle/AGENTS.md   |  31 ++
 .../component_context_menu_bundle/README.md   |  55 ++
 .../component-menu.css                        | 100 ++++
 .../component-menu.js                         | 516 ++++++++++++++++++
 .../initialize/end/component-context-menu.js  |   5 +
 .../space.bundle.yaml                         |  17 +
 11 files changed, 838 insertions(+), 1 deletion(-)
 create mode 100644 tests/fixtures/component_context_menu_bundle/AGENTS.md
 create mode 100644 tests/fixtures/component_context_menu_bundle/README.md
 create mode 100644 tests/fixtures/component_context_menu_bundle/component-menu.css
 create mode 100644 tests/fixtures/component_context_menu_bundle/component-menu.js
 create mode 100644 tests/fixtures/component_context_menu_bundle/ext/js/_core/framework/initializer.js/initialize/end/component-context-menu.js
 create mode 100644 tests/fixtures/component_context_menu_bundle/space.bundle.yaml

diff --git a/AGENTS.md b/AGENTS.md
index fb7a9e26..3cb25051 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -133,6 +133,9 @@ Test docs:
 - `/tests/AGENTS.md`
 - `/tests/agent_llm_performance/AGENTS.md`
 - `/tests/browser_component_harness/AGENTS.md`
+- `/tests/fixtures/AGENTS.md`
+- `/tests/fixtures/component_context_menu_bundle/AGENTS.md`
+- `/tests/fixtures/customware_bundle_example/AGENTS.md`
 
 ## Programming Guide
 
diff --git a/app/L0/_all/mod/_core/documentation/docs/app/customware-bundles.md b/app/L0/_all/mod/_core/documentation/docs/app/customware-bundles.md
index 38f1849c..81b629f3 100644
--- a/app/L0/_all/mod/_core/documentation/docs/app/customware-bundles.md
+++ b/app/L0/_all/mod/_core/documentation/docs/app/customware-bundles.md
@@ -34,7 +34,9 @@ The manifest advertises the package. It does not grant permission to monkey patc
 
 The root file is `space.bundle.yaml`.
 
-The checked-in minimal reference fixture lives at `tests/fixtures/customware_bundle_example/`.
+The checked-in minimal manifest fixture lives at `tests/fixtures/customware_bundle_example/`.
+
+The checked-in browser-runtime reference plugin lives at `tests/fixtures/component_context_menu_bundle/`.
 
 Example:
 
@@ -99,6 +101,34 @@ space.bundles.bridge.registerSync("acme/fleet", async (payload) => payload);
 await space.bundles.bridge.syncState("acme/fleet", { online: true });
 ```
 
+## Reference Component Menu Plugin
+
+`tests/fixtures/component_context_menu_bundle/` is an installable reference plugin for component-level browser behavior.
+
+Install it at:
+
+```txt
+L1/<group>/mod/space/component-context-menu/
+L2/<user>/mod/space/component-context-menu/
+```
+
+It loads through `_core/framework/initializer.js/initialize/end`, right-clicks Space widget cards by their `data-widget-id`, and exposes:
+
+```js
+const unregister = space.componentMenu.registerAction({
+  id: "example.inspect",
+  label: "Inspect component",
+  when(context) {
+    return context.type === "space-widget";
+  },
+  run(context) {
+    console.log(context.id);
+  }
+});
+```
+
+The menu footer always includes `Copy ID`. That copied id can be pasted into Agent Space when the user wants an agent to modify a precise UI entity.
+
 ## Install, Update, Remove
 
 Bundles are installed, updated, and removed as modules.
diff --git a/tests/AGENTS.md b/tests/AGENTS.md
index f7a5db95..0d77399a 100644
--- a/tests/AGENTS.md
+++ b/tests/AGENTS.md
@@ -51,6 +51,7 @@ This scope owns:
 - `browser_skill_contract_test.mjs`: focused frontend-skill coverage for the onscreen `browser-manager` auto-load metadata, the `browser-control` `browser:open` auto-load gate, and the browser overlay `x-context` export that makes that gate work
 - `customware_git_history_test.mjs`: focused server-side harness for optional writable-layer Git history, adaptive debounce rules, primary-owned scheduling, per-repo queue serialization, repository discovery, pagination, nested filename filters with full file metadata, diff reads, operation previews, revert, ignore rules, rollback or forward-travel preservation, filtered-list `total: null` behavior, explicit `409` revert-conflict coverage, successful non-overlapping isomorphic revert coverage, and runtime-param-selected isomorphic-backend coverage for Time Travel diff, preview, rollback, and revert flows
 - `customware_bundle_test.mjs`: focused coverage for `space.bundle.yaml` manifest discovery through installed modules, bundle metadata exposure on module list/info helpers, invalid-manifest reporting, and the browser-side `space.bundles` action and bridge sync registries
+- `fixtures/component_context_menu_bundle/`: installable reference customware bundle that adds a right-click Space widget component menu through `_core/framework/initializer.js/initialize/end`, exposes `space.componentMenu.registerAction(...)`, and keeps `Copy ID` as the footer action for agent-targeted UI edits
 - `fixtures/customware_bundle_example/`: minimal reference customware-bundle manifest copied by bundle tests into temporary `L1` or `L2` module roots; it is fixture content, not product behavior
 - `desktop_packaging_test.mjs`: focused packaging-runtime coverage for the packaged desktop host storage overrides so bundled desktop builds keep transient temp artifacts under a writable OS temp root, preserve the rebrand-stable packaged `userData` tree, keep backend-only auth fallback data under that user-data root instead of the installed app tree, keep the packaged updater log rooted at `<userData>/logs/desktop-updater.log`, keep Windows on the stock direct updater handoff while hardening the NSIS installer-side running-app shutdown path, detect malformed Windows updater metadata that omits the current arch installer and preserve the canonical fallback asset naming used to recover from it, stage same-version or downgrade debug reinstalls against canonical GitHub Release metadata, and clean stale updater `pending/` payloads after a marked install handoff without deleting reusable cache metadata
 - `extensions_load_request_shape_test.mjs`: focused frontend-loader request-shape coverage for top-level `maxLayer`, ordered grouped `patterns`, and grouped `extensions_load` responses without synthetic transport keys
diff --git a/tests/customware_bundle_test.mjs b/tests/customware_bundle_test.mjs
index 50352510..16d36601 100644
--- a/tests/customware_bundle_test.mjs
+++ b/tests/customware_bundle_test.mjs
@@ -18,6 +18,9 @@ import {
 const CUSTOMWARE_BUNDLE_FIXTURE_PATH = fileURLToPath(
   new URL("./fixtures/customware_bundle_example/", import.meta.url)
 );
+const COMPONENT_CONTEXT_MENU_FIXTURE_PATH = fileURLToPath(
+  new URL("./fixtures/component_context_menu_bundle/", import.meta.url)
+);
 
 function createRuntimeParams(values = {}) {
   return {
@@ -82,6 +85,37 @@ function seedBundleState() {
   return stateSystem;
 }
 
+function seedComponentContextMenuBundleState() {
+  const stateSystem = createStateSystem();
+
+  stateSystem.setEntry(GROUP_INDEX_AREA, "team", {
+    groupId: "team",
+    includesAllUsers: false,
+    memberUsers: ["alice"]
+  });
+  stateSystem.setEntry(GROUP_META_AREA, "errors", []);
+  stateSystem.setEntry(GROUP_META_AREA, "inclusion_cycles", []);
+  stateSystem.setEntry(GROUP_USER_INDEX_AREA, "alice", {
+    username: "alice",
+    groups: ["team"],
+    managedGroups: []
+  });
+  stateSystem.setEntry(FILE_INDEX_AREA, "L1/team", {
+    "/app/L1/team/mod/space/component-context-menu/": {
+      isDirectory: true,
+      mtimeMs: 1,
+      sizeBytes: 0
+    },
+    "/app/L1/team/mod/space/component-context-menu/space.bundle.yaml": {
+      isDirectory: false,
+      mtimeMs: 1,
+      sizeBytes: 460
+    }
+  });
+
+  return stateSystem;
+}
+
 test("customware bundles are discovered from installed module manifests", async (t) => {
   const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "space-bundle-test-"));
   t.after(() => fs.rmSync(projectRoot, { force: true, recursive: true }));
@@ -124,6 +158,49 @@ test("customware bundles are discovered from installed module manifests", async
   assert.equal(moduleEntries[0].bundle.id, "example/customware-bundle");
 });
 
+test("component context menu bundle fixture advertises the initializer plugin seam", async (t) => {
+  const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "space-component-menu-test-"));
+  t.after(() => fs.rmSync(projectRoot, { force: true, recursive: true }));
+
+  copyDirectory(
+    projectRoot,
+    "L1/team/mod/space/component-context-menu",
+    COMPONENT_CONTEXT_MENU_FIXTURE_PATH
+  );
+
+  const runtimeParams = createRuntimeParams();
+  const stateSystem = seedComponentContextMenuBundleState();
+
+  const bundles = await listInstalledBundles({
+    area: "l1",
+    projectRoot,
+    runtimeParams,
+    stateSystem,
+    username: "alice"
+  });
+
+  assert.equal(bundles.length, 1);
+  assert.equal(bundles[0].id, "space/component-context-menu");
+  assert.deepEqual(bundles[0].capabilities, ["component-menu", "actions", "browser-runtime"]);
+  assert.deepEqual(bundles[0].extensionPoints, ["_core/framework/initializer.js/initialize/end"]);
+  assert.deepEqual(
+    bundles[0].actions.map((action) => [action.id, action.title, action.capability]),
+    [["space.component_menu.copy_id", "Copy component ID", "component-menu"]]
+  );
+  assert.equal(bundles[0].module.path, "L1/team/mod/space/component-context-menu/");
+
+  const info = await readBundleInfo({
+    maxLayer: 1,
+    path: "/mod/space/component-context-menu",
+    projectRoot,
+    runtimeParams,
+    stateSystem,
+    username: "alice"
+  });
+  assert.equal(info.installed, true);
+  assert.equal(info.bundle.id, "space/component-context-menu");
+});
+
 test("customware bundle info returns selected module metadata and invalid manifest errors", async (t) => {
   const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "space-bundle-test-"));
   t.after(() => fs.rmSync(projectRoot, { force: true, recursive: true }));
diff --git a/tests/fixtures/AGENTS.md b/tests/fixtures/AGENTS.md
index 2c010b27..03458b9c 100644
--- a/tests/fixtures/AGENTS.md
+++ b/tests/fixtures/AGENTS.md
@@ -10,6 +10,7 @@ Fixtures in this folder are durable reference inputs, not runtime state. Keep th
 
 Current fixture folders:
 
+- `component_context_menu_bundle/`: installable reference customware bundle that demonstrates a browser-side component context menu through the framework initializer hook.
 - `customware_bundle_example/`: minimal reference customware-bundle module used by bundle discovery tests and documentation.
 
 ## Local Contracts
@@ -17,6 +18,7 @@ Current fixture folders:
 - Do not store generated output or local verification artifacts here.
 - Fixtures must be safe to copy into a temporary project root during tests.
 - Prefer explicit README or AGENTS notes for each fixture folder so future agents know whether it is a runtime example, parser fixture, or regression case.
+- Runtime reference bundles must still enter through documented module seams; do not add fixture-only monkey patches that would not be acceptable as installable customware.
 
 ## Development Guidance
 
diff --git a/tests/fixtures/component_context_menu_bundle/AGENTS.md b/tests/fixtures/component_context_menu_bundle/AGENTS.md
new file mode 100644
index 00000000..f2178be4
--- /dev/null
+++ b/tests/fixtures/component_context_menu_bundle/AGENTS.md
@@ -0,0 +1,31 @@
+# AGENTS
+
+## Purpose
+
+`component_context_menu_bundle/` is a reference Customware Bundle Interface plugin for component-level context menus.
+
+It demonstrates how an installable bundle can add browser behavior through documented `ext/js` hooks without patching Space Agent core runtime files.
+
+## Ownership
+
+This folder owns:
+
+- `space.bundle.yaml`: bundle manifest metadata for discovery tests and module listings.
+- `component-menu.js`: browser runtime that installs `space.componentMenu`.
+- `component-menu.css`: bundle-owned menu presentation.
+- `ext/js/_core/framework/initializer.js/initialize/end/component-context-menu.js`: the documented framework initializer hook that starts the bundle.
+- `README.md`: install, update, removal, and action-registration guidance.
+
+## Local Contracts
+
+- Keep this fixture installable at `L1/<group>/mod/space/component-context-menu/` or `L2/<user>/mod/space/component-context-menu/`.
+- Runtime behavior must enter through `_core/framework/initializer.js/initialize/end`.
+- Do not patch `_core/spaces/store.js`, private widget functions, or other core runtime files.
+- Treat widget DOM signals such as `.spaces-widget-card` and `data-widget-id` as the stable v1 component target contract.
+- Keep `Copy ID` available in the menu footer because it is the agent-targeting workflow this bundle exists to support.
+
+## Development Guidance
+
+- Add new menu integrations through `space.componentMenu.registerAction(...)`.
+- If a future component type needs stronger metadata than DOM discovery can provide, document the missing upstream seam before adding a workaround.
+- Keep the example generic and not Hermes-branded; downstream mirrors can layer product-specific actions on top.
diff --git a/tests/fixtures/component_context_menu_bundle/README.md b/tests/fixtures/component_context_menu_bundle/README.md
new file mode 100644
index 00000000..ff0be638
--- /dev/null
+++ b/tests/fixtures/component_context_menu_bundle/README.md
@@ -0,0 +1,55 @@
+# Component Context Menu Bundle
+
+This reference Customware Bundle Interface plugin adds a right-click context menu for Space widget cards.
+
+Install it as a normal customware module:
+
+```txt
+L1/team/mod/space/component-context-menu/
+L2/alice/mod/space/component-context-menu/
+```
+
+The bundle uses the documented `_core/framework/initializer.js/initialize/end` browser hook. It does not edit Space Agent core files or monkey patch private widget runtime functions.
+
+## What It Does
+
+- Right-click a Space widget card to open a component menu.
+- Use the footer `Copy ID` button to copy the clicked UI entity id.
+- Paste that id into Agent Space when you want the agent to modify a precise widget or component.
+- Register custom actions that appear above the footer and receive the clicked component context.
+
+## Action Registration
+
+Other bundles can add menu actions from browser code:
+
+```js
+const unregister = space.componentMenu.registerAction({
+  id: "example.inspect",
+  label: "Inspect component",
+  order: 100,
+  when(context) {
+    return context.type === "space-widget";
+  },
+  async run(context) {
+    console.log(context.id, context.widgetId, context.path);
+  }
+});
+```
+
+Call `unregister()` when the action should disappear.
+
+The v1 context contains:
+
+- `type`
+- `id`
+- `widgetId`
+- `spaceId`
+- `path`
+- `element`
+- `event`
+
+## Update And Remove
+
+Update or remove this bundle the same way as any other installed module. Removing the module removes its manifest and hook files; the context menu runtime disappears after the page reloads.
+
+Direct runtime injection is discouraged because it binds customware to private implementation details. This bundle keeps the customization attached to Space Agent through documented module, manifest, and `ext/js` seams.
diff --git a/tests/fixtures/component_context_menu_bundle/component-menu.css b/tests/fixtures/component_context_menu_bundle/component-menu.css
new file mode 100644
index 00000000..fa269c4b
--- /dev/null
+++ b/tests/fixtures/component_context_menu_bundle/component-menu.css
@@ -0,0 +1,100 @@
+.space-component-menu-layer {
+  position: fixed;
+  inset: 0;
+  z-index: 10000;
+  pointer-events: none;
+}
+
+.space-component-menu-panel {
+  position: fixed;
+  width: min(260px, calc(100vw - 24px));
+  max-height: min(420px, calc(100vh - 24px));
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  color: var(--space-text-primary, #f8fafc);
+  background: var(--space-surface-strong, #111827);
+  border: 1px solid var(--space-border-subtle, rgba(148, 163, 184, 0.28));
+  border-radius: 8px;
+  box-shadow: 0 18px 40px rgba(15, 23, 42, 0.32);
+  pointer-events: auto;
+}
+
+.space-component-menu-header {
+  padding: 10px 12px 8px;
+  border-bottom: 1px solid var(--space-border-subtle, rgba(148, 163, 184, 0.18));
+}
+
+.space-component-menu-title {
+  margin: 0;
+  overflow: hidden;
+  color: var(--space-text-primary, #f8fafc);
+  font-size: 13px;
+  font-weight: 700;
+  line-height: 1.25;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.space-component-menu-subtitle {
+  margin: 4px 0 0;
+  overflow: hidden;
+  color: var(--space-text-muted, #94a3b8);
+  font-size: 11px;
+  line-height: 1.35;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.space-component-menu-actions {
+  overflow: auto;
+  padding: 6px;
+}
+
+.space-component-menu-action,
+.space-component-menu-footer-button {
+  width: 100%;
+  min-height: 34px;
+  display: flex;
+  align-items: center;
+  justify-content: flex-start;
+  gap: 8px;
+  padding: 7px 9px;
+  color: inherit;
+  background: transparent;
+  border: 0;
+  border-radius: 6px;
+  cursor: pointer;
+  font: inherit;
+  font-size: 13px;
+  line-height: 1.25;
+  text-align: left;
+}
+
+.space-component-menu-action:hover,
+.space-component-menu-action:focus-visible,
+.space-component-menu-footer-button:hover,
+.space-component-menu-footer-button:focus-visible {
+  background: var(--space-control-hover, rgba(148, 163, 184, 0.14));
+  outline: none;
+}
+
+.space-component-menu-empty {
+  margin: 0;
+  padding: 8px 9px;
+  color: var(--space-text-muted, #94a3b8);
+  font-size: 12px;
+  line-height: 1.35;
+}
+
+.space-component-menu-footer {
+  padding: 6px;
+  border-top: 1px solid var(--space-border-subtle, rgba(148, 163, 184, 0.18));
+  background: var(--space-surface-muted, rgba(15, 23, 42, 0.24));
+}
+
+.space-component-menu-footer-button {
+  justify-content: center;
+  color: var(--space-accent-text, #c7d2fe);
+  font-weight: 700;
+}
diff --git a/tests/fixtures/component_context_menu_bundle/component-menu.js b/tests/fixtures/component_context_menu_bundle/component-menu.js
new file mode 100644
index 00000000..c0a5b5b9
--- /dev/null
+++ b/tests/fixtures/component_context_menu_bundle/component-menu.js
@@ -0,0 +1,516 @@
+import { showToast } from "/mod/_core/visual/chrome/toast.js";
+
+const BUNDLE_ID = "space/component-context-menu";
+const MENU_LAYER_ID = "space-component-context-menu-layer";
+const STYLESHEET_ID = "space-component-context-menu-style";
+const STYLESHEET_HREF = "/mod/space/component-context-menu/component-menu.css";
+const RUNTIME_KEY = "__spaceComponentMenuRuntime";
+const EDITABLE_SELECTOR = "input, textarea, select, [contenteditable=''], [contenteditable='true']";
+
+function normalizeText(value) {
+  return String(value || "").trim();
+}
+
+function normalizeOrder(value) {
+  const order = Number(value);
+  return Number.isFinite(order) ? order : 100;
+}
+
+function getSpaceRuntime() {
+  if (!globalThis.space || typeof globalThis.space !== "object") {
+    globalThis.space = {};
+  }
+
+  return globalThis.space;
+}
+
+function getSpacesStore() {
+  try {
+    return globalThis.Alpine?.store?.("spacesPage") || null;
+  } catch {
+    return null;
+  }
+}
+
+function ensureStylesheet() {
+  if (document.getElementById(STYLESHEET_ID)) {
+    return;
+  }
+
+  const link = document.createElement("link");
+  link.id = STYLESHEET_ID;
+  link.rel = "stylesheet";
+  link.href = STYLESHEET_HREF;
+  document.head.append(link);
+}
+
+function isElement(value) {
+  return typeof Element !== "undefined" && value instanceof Element;
+}
+
+function findElementTarget(target) {
+  if (isElement(target)) {
+    return target;
+  }
+
+  return isElement(target?.parentElement) ? target.parentElement : null;
+}
+
+function isEditableTarget(target) {
+  const element = findElementTarget(target);
+  return Boolean(element?.closest?.(EDITABLE_SELECTOR));
+}
+
+function findComponentElement(target) {
+  const element = findElementTarget(target);
+
+  if (!element) {
+    return null;
+  }
+
+  return element.closest("[data-space-component-id], .spaces-widget-card[data-widget-id], .spaces-widget-card, [data-widget-id]");
+}
+
+function buildWidgetPath(spaceId, widgetId) {
+  const normalizedSpaceId = normalizeText(spaceId);
+  const normalizedWidgetId = normalizeText(widgetId);
+
+  if (!normalizedSpaceId || !normalizedWidgetId) {
+    return "";
+  }
+
+  return `~/spaces/${normalizedSpaceId}/widgets/${normalizedWidgetId}.yaml`;
+}
+
+function getContextFromEvent(event) {
+  if (!event || isEditableTarget(event.target)) {
+    return null;
+  }
+
+  const element = findComponentElement(event.target);
+
+  if (!element) {
+    return null;
+  }
+
+  const widgetCard = element.closest?.(".spaces-widget-card[data-widget-id], .spaces-widget-card, [data-widget-id]") || element;
+  const widgetId = normalizeText(widgetCard?.dataset?.widgetId || element.dataset?.widgetId);
+  const componentId = normalizeText(element.dataset?.spaceComponentId || widgetId || element.id);
+
+  if (!componentId) {
+    return null;
+  }
+
+  const spacesStore = getSpacesStore();
+  const spaceId = normalizeText(
+    element.dataset?.spaceId ||
+      widgetCard?.dataset?.spaceId ||
+      spacesStore?.currentSpaceId ||
+      spacesStore?.currentSpace?.id
+  );
+  const type = widgetId ? "space-widget" : "component";
+
+  return {
+    type,
+    id: componentId,
+    widgetId,
+    spaceId,
+    path: buildWidgetPath(spaceId, widgetId),
+    element,
+    event
+  };
+}
+
+function clonePublicContext(context) {
+  return {
+    type: context.type,
+    id: context.id,
+    widgetId: context.widgetId,
+    spaceId: context.spaceId,
+    path: context.path,
+    element: context.element,
+    event: context.event
+  };
+}
+
+async function copyTextToClipboard(text) {
+  const value = normalizeText(text);
+
+  if (!value) {
+    return false;
+  }
+
+  if (navigator.clipboard?.writeText) {
+    await navigator.clipboard.writeText(value);
+    return true;
+  }
+
+  const input = document.createElement("textarea");
+  input.value = value;
+  input.setAttribute("readonly", "");
+  input.style.position = "fixed";
+  input.style.left = "-9999px";
+  input.style.top = "0";
+  document.body.append(input);
+  input.select();
+
+  try {
+    return document.execCommand("copy");
+  } finally {
+    input.remove();
+  }
+}
+
+function notify(message, tone = "success") {
+  showToast(message, {
+    durationMs: 1800,
+    tone
+  });
+}
+
+function dispatchRuntimeEvent(type, detail) {
+  if (typeof CustomEvent !== "function" || !globalThis.window) {
+    return;
+  }
+
+  window.dispatchEvent(new CustomEvent(type, { detail }));
+}
+
+function normalizeAction(action) {
+  const source = action && typeof action === "object" ? action : {};
+  const id = normalizeText(source.id);
+  const label = normalizeText(source.label || source.title || source.name || id);
+
+  if (!id || !label || typeof source.run !== "function") {
+    throw new TypeError("Component menu actions require id, label/title, and run(context).");
+  }
+
+  return {
+    bundleId: normalizeText(source.bundleId || BUNDLE_ID),
+    id,
+    label,
+    order: normalizeOrder(source.order),
+    when: typeof source.when === "function" ? source.when : null,
+    run: source.run
+  };
+}
+
+function createRuntime() {
+  const actions = new Map();
+  let layer = null;
+  let activeContext = null;
+
+  function unregisterAction(id) {
+    const normalizedId = normalizeText(id);
+    const existing = actions.get(normalizedId);
+
+    if (!existing) {
+      return false;
+    }
+
+    actions.delete(normalizedId);
+    dispatchRuntimeEvent("space:component-menu-action-unregistered", {
+      id: normalizedId,
+      bundleId: existing.bundleId
+    });
+    return true;
+  }
+
+  function registerAction(action) {
+    const entry = normalizeAction(action);
+    actions.set(entry.id, entry);
+    dispatchRuntimeEvent("space:component-menu-action-registered", {
+      id: entry.id,
+      bundleId: entry.bundleId,
+      label: entry.label
+    });
+    return () => unregisterAction(entry.id);
+  }
+
+  function getVisibleActions(context) {
+    const publicContext = clonePublicContext(context);
+
+    return [...actions.values()]
+      .filter((action) => {
+        if (!action.when) {
+          return true;
+        }
+
+        try {
+          return Boolean(action.when(publicContext));
+        } catch (error) {
+          console.warn("[component-context-menu] action predicate failed", action.id, error);
+          return false;
+        }
+      })
+      .sort((left, right) => left.order - right.order || left.label.localeCompare(right.label));
+  }
+
+  function listActions(context = null) {
+    const candidateActions = context ? getVisibleActions(context) : [...actions.values()];
+    return candidateActions.map((action) => ({
+      bundleId: action.bundleId,
+      id: action.id,
+      label: action.label,
+      order: action.order
+    }));
+  }
+
+  function close() {
+    if (!layer) {
+      return;
+    }
+
+    layer.remove();
+    layer = null;
+    activeContext = null;
+  }
+
+  async function runMenuAction(action, context) {
+    try {
+      await action.run(clonePublicContext(context));
+      close();
+    } catch (error) {
+      console.error("[component-context-menu] action failed", action.id, error);
+      notify(String(error?.message || "Component menu action failed."), "error");
+    }
+  }
+
+  async function copyContextId(context) {
+    try {
+      await copyTextToClipboard(context.id);
+      notify("Component ID copied.");
+      close();
+    } catch (error) {
+      console.error("[component-context-menu] copy id failed", error);
+      notify("Unable to copy component ID.", "error");
+    }
+  }
+
+  function createMenuButton(action, context) {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = "space-component-menu-action";
+    button.setAttribute("role", "menuitem");
+    button.textContent = action.label;
+    button.addEventListener("click", () => {
+      void runMenuAction(action, context);
+    });
+    return button;
+  }
+
+  function buildLayer(context) {
+    const nextLayer = document.createElement("div");
+    nextLayer.id = MENU_LAYER_ID;
+    nextLayer.className = "space-component-menu-layer";
+
+    const panel = document.createElement("section");
+    panel.className = "space-component-menu-panel";
+    panel.setAttribute("role", "menu");
+    panel.setAttribute("aria-label", "Component actions");
+
+    const header = document.createElement("header");
+    header.className = "space-component-menu-header";
+
+    const title = document.createElement("p");
+    title.className = "space-component-menu-title";
+    title.textContent = context.type === "space-widget" ? "Space widget" : "Component";
+
+    const subtitle = document.createElement("p");
+    subtitle.className = "space-component-menu-subtitle";
+    subtitle.textContent = context.id;
+    header.append(title, subtitle);
+
+    const actionsElement = document.createElement("div");
+    actionsElement.className = "space-component-menu-actions";
+    const visibleActions = getVisibleActions(context);
+
+    if (visibleActions.length) {
+      visibleActions.forEach((action) => {
+        actionsElement.append(createMenuButton(action, context));
+      });
+    } else {
+      const empty = document.createElement("p");
+      empty.className = "space-component-menu-empty";
+      empty.textContent = "No custom actions";
+      actionsElement.append(empty);
+    }
+
+    const footer = document.createElement("footer");
+    footer.className = "space-component-menu-footer";
+
+    const copyButton = document.createElement("button");
+    copyButton.type = "button";
+    copyButton.className = "space-component-menu-footer-button";
+    copyButton.setAttribute("role", "menuitem");
+    copyButton.textContent = "Copy ID";
+    copyButton.addEventListener("click", () => {
+      void copyContextId(context);
+    });
+    footer.append(copyButton);
+
+    panel.append(header, actionsElement, footer);
+    nextLayer.append(panel);
+    return {
+      layer: nextLayer,
+      panel
+    };
+  }
+
+  function placePanel(panel, clientX, clientY) {
+    const margin = 8;
+    const rect = panel.getBoundingClientRect();
+    const left = Math.max(margin, Math.min(clientX, window.innerWidth - rect.width - margin));
+    const top = Math.max(margin, Math.min(clientY, window.innerHeight - rect.height - margin));
+
+    panel.style.left = `${left}px`;
+    panel.style.top = `${top}px`;
+  }
+
+  function open(context, position = {}) {
+    close();
+    activeContext = context;
+    const menu = buildLayer(context);
+    layer = menu.layer;
+    document.body.append(layer);
+    placePanel(menu.panel, Number(position.clientX) || 0, Number(position.clientY) || 0);
+    menu.panel.querySelector("button")?.focus?.({ preventScroll: true });
+    dispatchRuntimeEvent("space:component-menu-opened", {
+      id: context.id,
+      type: context.type,
+      widgetId: context.widgetId,
+      spaceId: context.spaceId
+    });
+  }
+
+  function handleContextMenu(event) {
+    if (layer?.contains(event.target)) {
+      event.preventDefault();
+      return;
+    }
+
+    const context = getContextFromEvent(event);
+
+    if (!context) {
+      return;
+    }
+
+    event.preventDefault();
+    open(context, {
+      clientX: event.clientX,
+      clientY: event.clientY
+    });
+  }
+
+  function handlePointerDown(event) {
+    if (layer && !layer.contains(event.target)) {
+      close();
+    }
+  }
+
+  function handleKeyDown(event) {
+    if (event.key === "Escape") {
+      close();
+    }
+  }
+
+  function destroy() {
+    close();
+    document.removeEventListener("contextmenu", handleContextMenu, true);
+    document.removeEventListener("pointerdown", handlePointerDown, true);
+    window.removeEventListener("keydown", handleKeyDown, true);
+    window.removeEventListener("scroll", close, true);
+    window.removeEventListener("resize", close, true);
+    actions.clear();
+  }
+
+  document.addEventListener("contextmenu", handleContextMenu, true);
+  document.addEventListener("pointerdown", handlePointerDown, true);
+  window.addEventListener("keydown", handleKeyDown, true);
+  window.addEventListener("scroll", close, true);
+  window.addEventListener("resize", close, true);
+
+  return {
+    close,
+    destroy,
+    get activeContext() {
+      return activeContext ? clonePublicContext(activeContext) : null;
+    },
+    getContextFromEvent,
+    listActions,
+    open,
+    registerAction,
+    unregisterAction
+  };
+}
+
+function registerBuiltInActions(runtime) {
+  runtime.registerAction({
+    id: "space.component_menu.copy_widget_path",
+    label: "Copy Widget Path",
+    order: 20,
+    when(context) {
+      return context.type === "space-widget" && Boolean(context.path);
+    },
+    async run(context) {
+      await copyTextToClipboard(context.path);
+      notify("Widget path copied.");
+    }
+  });
+}
+
+function registerBundleAction(runtime) {
+  const bundles = getSpaceRuntime().bundles;
+
+  if (!bundles?.actions?.register) {
+    return null;
+  }
+
+  return bundles.actions.register({
+    bundleId: BUNDLE_ID,
+    capability: "component-menu",
+    id: "space.component_menu.copy_id",
+    title: "Copy component ID",
+    async run(payload = {}) {
+      const id = normalizeText(payload.id || runtime.activeContext?.id);
+
+      if (!id) {
+        throw new Error("A component id is required.");
+      }
+
+      await copyTextToClipboard(id);
+      notify("Component ID copied.");
+      return {
+        id
+      };
+    }
+  });
+}
+
+export function installComponentContextMenu() {
+  if (globalThis[RUNTIME_KEY]) {
+    return globalThis[RUNTIME_KEY].api;
+  }
+
+  ensureStylesheet();
+
+  const api = createRuntime();
+  const unregisterBundleAction = registerBundleAction(api);
+  registerBuiltInActions(api);
+
+  const runtime = {
+    api,
+    destroy() {
+      unregisterBundleAction?.();
+      api.destroy();
+      delete globalThis[RUNTIME_KEY];
+    }
+  };
+
+  globalThis[RUNTIME_KEY] = runtime;
+
+  const space = getSpaceRuntime();
+  space.componentMenu = api;
+
+  return api;
+}
diff --git a/tests/fixtures/component_context_menu_bundle/ext/js/_core/framework/initializer.js/initialize/end/component-context-menu.js b/tests/fixtures/component_context_menu_bundle/ext/js/_core/framework/initializer.js/initialize/end/component-context-menu.js
new file mode 100644
index 00000000..b05449e7
--- /dev/null
+++ b/tests/fixtures/component_context_menu_bundle/ext/js/_core/framework/initializer.js/initialize/end/component-context-menu.js
@@ -0,0 +1,5 @@
+import { installComponentContextMenu } from "/mod/space/component-context-menu/component-menu.js";
+
+export default async function componentContextMenuInitializerEnd() {
+  installComponentContextMenu();
+}
diff --git a/tests/fixtures/component_context_menu_bundle/space.bundle.yaml b/tests/fixtures/component_context_menu_bundle/space.bundle.yaml
new file mode 100644
index 00000000..fc22cf8f
--- /dev/null
+++ b/tests/fixtures/component_context_menu_bundle/space.bundle.yaml
@@ -0,0 +1,17 @@
+id: space/component-context-menu
+name: Component Context Menu
+version: 0.1.0
+description: Reference customware bundle that adds right-click component actions and Copy ID for Space widgets.
+capabilities:
+  - component-menu
+  - actions
+  - browser-runtime
+extension_points:
+  - _core/framework/initializer.js/initialize/end
+compatibility:
+  space_agent: ">=0.65"
+actions:
+  - id: space.component_menu.copy_id
+    title: Copy component ID
+    capability: component-menu
+    description: Copy the clicked UI entity id so Agent Space can target exact component changes.