Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
docs(plugin): clarify extension taxonomy
Rahman565a88e5110f
diff --git a/claude-skills/mso/SKILL.md b/claude-skills/mso/SKILL.mdindex acf288f3..679f2872 100644--- a/claude-skills/mso/SKILL.md+++ b/claude-skills/mso/SKILL.md@@ -22,6 +22,19 @@ Choose the least-powerful capability that can finish the task:Never choose Bash merely because it is shorter for a simple operation. For repository-wide work, one scoped terminal batch is safer and faster than many disconnected discovery calls. The permission boundary remains a feature. Before destructive actions, service topology changes, credential changes, production rollback, or deleting data you did not create in the current task, require explicit human approval.+## Capability selection — reuse before adding++Treat `Skill`, `Project Plugin`, `MCP`, `Integration`, `App`, and `Managed App` as different authority domains, not synonyms. Before installing or creating anything:++1. Use an existing bounded/native MSO capability if it already completes the task.+2. For a selected project, inspect its declared functions/MCP before adding another project plugin or server.+3. For credential-dependent provider work, inspect native Integrations and reuse the exact existing user/provider/connection when it matches. Do not ask for pasted credentials or create a duplicate connection first.+4. Use a trusted skill when the missing piece is reusable procedure/routing knowledge rather than a new executable capability.+5. Install a Project Plugin only for the exact project that needs it, after inspection. Catalog presence is not installation and nothing is inherited from another project.+6. App/App Store state controls workspace UI; Managed App state controls an external runtime. Neither substitutes for MCP authorization or Integration credentials.++When a useful external capability is unavailable, continue any independent work and state the exact missing connection/capability rather than treating setup as proof of completion. Verify connection/install state before using or claiming it.+## Resolve the install — never hardcode a username/path```bashdiff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex f078548b..9fbc3188 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -79,7 +79,39 @@ Cross-slice imports go through the public slice barrels. Host-facing code is cena client slice calls its adapter/API contract, an API route calls `lib/host`, and neitherroute nor component reimplements path-jail or process guards.-## 3. AppShell+## 3. Extension taxonomy++MSO uses several extension concepts because they own different authority. They are **not** aliases for one generic plugin object. Use the narrow term that matches the lifecycle being changed:++| Term | What it owns | State / authority | Do not confuse with |+|---|---|---|---|+| **Skill** | Trusted reusable instructions and routing policy (`SKILL.md`, optional structured contract/resources). | Skill trust (`official / verified / local / untrusted`) controls whether instructions may be model-loaded. A skill does not grant credentials or tool permission. | MCP server, Integration, executable app. |+| **OpenAI/Codex plugin package** | Distribution metadata for reviewed skills plus an optional registered-app mapping (`.codex-plugin/plugin.json` + `.app.json`). | Packaging only. The package does not authorize the live MSO MCP server. | MSO Project Plugin, registered app, MCP authorization. |+| **Registered app** | External platform identity referenced by `.app.json` when an exact real app registration exists. | Platform-owned install/connection/permission state. MSO keeps the mapping empty until an exact registration exists. | Generic MSO Integration or Project Plugin. |+| **Project Plugin** | A reviewed portable capability package that can declare skills and an MCP binding for one exact project. | Catalog presence never means installed. `project_mcp_manage` installs/removes only the selected project and uses revision guards. | Global plugin install, Skill Market entry, Integration credential. |+| **MCP** | Protocol/transport boundary for structured tools. This includes MSO's own `/mcp` and project-declared MCP servers. | Tool schemas are discovered from the selected server; OAuth/project policy and call-time guards remain authoritative. | Package identity or credential storage. |+| **Integration** | Credential identity and provider routing: credential user → provider → named connection → source/backend → auth method. | Native Integrations is the credential authority; secrets stay outside ordinary model/tool arguments. | MCP itself, Project Plugin, App. |+| **App** | AppShell user-interface application or feature surfaced inside the MSO workspace. | UI install/toggle state belongs to the shell/app registry. | Managed service runtime or MCP capability. |+| **Managed App** | External runtime/service that MSO installs or operates, such as Hermes, OpenClaw or 9Router. | Host/service lifecycle, health, version, backup/update/uninstall state. | App Store entry, Integration, Project Plugin. |+| **Skill Market** | Curated source of reviewed skill bundles. | Install state is local skill state (`installed / modified / conflict / not-installed`); removal refuses unmanaged content. | General app/plugin marketplace. |+| **App Store** | MSO shell catalog for UI apps/features. | Presentation/install state in the workspace. | OpenAI plugin directory, Project Plugin catalog, Managed App registry. |++### Capability selection order++For agent routing, reuse before adding another extension:++1. Use an existing bounded/native MSO capability when it already completes the task.+2. Use an already-declared exact-project function or MCP capability when that project owns the operation.+3. For credential-dependent provider work, resolve an existing **Integration** before asking for setup or creating another connection.+4. Use an existing trusted **Skill** when the missing piece is reusable procedure/routing knowledge rather than executable capability.+5. Inspect before installing a **Project Plugin**; add one only when the selected project genuinely needs the packaged capability. Never infer global or parent-project installation.+6. Use **App** / **Managed App** lifecycle only when the request is about workspace UI or an external runtime/service.++A store/catalog is discovery metadata, not execution authority. Likewise, package metadata, a rendered widget, or the existence of a connection record never substitutes for the underlying scope, trust, revision, confirmation, provider and postcondition checks.++The cross-reference audit that informs this taxonomy lives in [`PLUGIN-REFERENCE-MATRIX.md`](./PLUGIN-REFERENCE-MATRIX.md).++## 4. AppShell`frontend/slices/appshell/` is the generic shell framework. `os-shell` is the thin MSOconsumer that supplies brand, app manifest, shell choice and capabilities.@@ -106,7 +138,7 @@ same app/window state. Phone portrait resolves to a mobile shell; phone landscapthe desktop surface according to the responsive policy. App windows themselves remain thesame feature code.-## 4. Addressable routing without page-per-app duplication+## 5. Addressable routing without page-per-app duplicationMSO uses one catch-all application route, `app/[[...slug]]/page.tsx`. The focused app ismirrored into the URL while window state remains client-side. App slugs are assigned in@@ -144,7 +176,7 @@ sandboxed. The MCP widget origin comes from `OS_MCP_UI_ORIGIN`, or is derived frorigin remains deployment-owned and retains its deny-framing headers. The split prevents convenientHTML/runtime extensibility from becoming a CSP privilege-escalation path.-## 5. Host API and filesystem model+## 6. Host API and filesystem model`/api/v1/*` is the authenticated host API. Important families include:@@ -180,7 +212,7 @@ cache-only and exposes no apply action. These are MSO roles over one Unix procesidentity directory, Linux-user switch, or tenant boundary. Appearance/Theme/Quicklinks are still asingle deployment-wide prefs document: delegated devices read it; Owner is the only writer.-## 6. Alfa versus MCP+## 7. Alfa versus MCPAlfa and MCP are two separate model-facing catalogs on purpose.@@ -198,7 +230,7 @@ The exact full transport catalog and ChatGPT model profile are generated from soSee `docs/MCP.md` for protocol/security internals, `docs/A2A.md` for peer-agent delegation, and `docs/CHATGPT-PLUGIN.md` for theChatGPT-facing setup and diagrams.-## 7. Project and skill discovery+## 8. Project and skill discoveryMSO can discover projects across configured containers instead of assuming a single`~/projects` tree. Enumeration and resolution share the same containment/ownership checks,@@ -216,7 +248,7 @@ Skills are merged from official/operator/bundled roots plus eligible per-projectTrust is derived from provenance, ownership and containment; untrusted instructions are notfed directly to the model. See `skills/README.md`.-## 8. Managed applications+## 9. Managed applicationsHermes, OpenClaw and 9Router are managed, not embedded into MSO's process model. MSO candetect, install, start/stop/restart, read logs, update, back up, restore and conservatively@@ -240,7 +272,7 @@ dashboard as one surface plus MSO's Details management surface.See `docs/MANAGED-APPS.md`, `docs/HERMES-INTEGRATION.md`,`docs/OPENCLAW-INTEGRATION.md` and `docs/9ROUTER-INTEGRATION.md`.-## 9. Camoufox Browser+## 10. Camoufox BrowserThe Browser app is a real Camoufox Firefox session on a headless X display. It is streamedthrough noVNC on a reserved split-origin host such as `camoufox.mso.example.com`. That host@@ -253,7 +285,7 @@ The logged-in Firefox profile is intentionally outside `~/.mso`, under the user'share tree. It can hold live account cookies. Browser status tools never return the VNCpassword or profile contents.-## 10. Build and release architecture+## 11. Build and release architectureProduction is a systemd deployment, not a webhook deployment. `git push` alone changes norunning bytes. The supported developer release command is:@@ -272,7 +304,7 @@ For operator updates use Settings → About or `mso update`; use `--rebuild` forsupported recovery rebuild. See `docs/INSTALL.md`, `docs/DEVELOPMENT.md` and`docs/TROUBLESHOOTING.md`.-## 11. What is authoritative+## 12. What is authoritativeWhen sources disagree, use this order:diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex 622d5e80..c13b2919 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -41,6 +41,10 @@ this is the *what*, and it is what Settings → About shows as “What's new”.- `mcp` close session terminal across shells- `mcp` close terminal after session graph check+**Docs**++- `plugin` clarify extension taxonomy+## 2026-09-15**Added**diff --git a/docs/PLUGIN-REFERENCE-MATRIX.md b/docs/PLUGIN-REFERENCE-MATRIX.mdnew file mode 100644index 00000000..ccd246dd--- /dev/null+++ b/docs/PLUGIN-REFERENCE-MATRIX.md@@ -0,0 +1,92 @@+# Plugin reference architecture matrix++> **Living reference.** This document tracks recurring architecture patterns observed while reviewing high-quality OpenAI/Codex/MCP plugin references. It is not a feature checklist and does not make a reference plugin authoritative over MSO. A pattern is promoted only when it is cross-domain or closes a concrete correctness, safety, portability, DX, or compatibility gap.++## Decision rules++- `ALREADY_STRONGER` — MSO already has the behavior with stronger or broader guarantees.+- `ALREADY_BUT_IMPROVE` — MSO has the concept, but the reference exposes a useful refinement.+- `NEW_GENERALIZABLE` — a reusable primitive is missing and evidence is strong enough to add it.+- `DOMAIN_SPECIFIC` — useful in the reference domain but not a core MSO primitive.+- `AVOID` — would reduce safety, privacy, portability, capability, or context efficiency.+- `WAIT` — promising, but one reference is not enough evidence for a new abstraction.++The matrix should be updated after each reference audit. `pending` means that plugin has not been audited yet; it does not mean the pattern is absent.++## Living matrix++| Pattern | Shopify | Plugin Management | GitHub | Gmail | Drive | Calendar | Notion | Analytics | Convex | Figma | Lovable | Sites | MSO current | Candidate primitive | Decision |+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|+| Structured skill routing/lifecycle contract | Strong reference; already adapted | Prose routing only in local snapshot | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | `contract.yaml` + `agents/openai.yaml` on official skills | Keep structured skill contract | `ALREADY_STRONGER` |+| Discover → validate → execute → verify | Strong reference; already adapted | Discovery/permission/dependency inspection is separated from mutation; connection must be verified before use | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Present across project MCP, database, workflows, integrations and action metadata | Universal lifecycle policy engine | `WAIT` — metadata must not become security authority |+| Package identity separate from live app/connection state | Partial evidence | Strong: Codex plugin package points to a required registered app; connection/permission state is managed separately | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | OpenAI package, project plugin, MCP, Integrations, App and Managed App are distinct but terminology was under-documented | Canonical extension taxonomy | `ALREADY_BUT_IMPROVE` — documented now |+| Reuse existing capability before discovering/installing a new extension | Not primary Shopify pattern | Strong: built-in → connected plugin → search new plugin | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Bounded-first and Integrations-first existed, but cross-surface ordering was implicit | Capability selection policy | `ALREADY_BUT_IMPROVE` — added to `/mso` guidance |+| Search separated from suggestion/install | Domain discovery is separate from actions | Strong: `search_plugins` is read-only discovery; `suggest_plugins` only proposes exact results and user action completes connection | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Skills, projects and project MCP have separate discovery; Project Plugin catalog is small and install is explicit | Generic extension discovery/suggestion lifecycle | `WAIT` |+| Suggestion is non-blocking | Not established | Strong: continue independent work while user handles connection | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Workflows can continue around missing integrations, but no universal suggestion state | Pending extension state | `WAIT` |+| Installed/pending duplicate prevention | State-aware mutations | Strong: do not suggest installed or already-pending plugins | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Skill Market tracks installed/modified/conflict; project MCP inspect reports exact installed bindings | Generic extension state model | `WAIT` |+| Dependency metadata resolved separately from installation | Domain dependencies exist | Strong: dependency inspection reports canonical dependencies and user-aware status without installing | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | `.app.json` maps OpenAI package→registered app; project plugin manifest declares skills/MCP, but there is no generic dependency graph | Dependency contract | `WAIT` |+| Global permission default + per-extension override/inheritance | Not established | Strong: global permission mode plus app-specific override with `inherit` | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | OAuth `read < write < exec`, live device roles and per-operation confirmation are stronger security boundaries but semantically different | Permission policy overlay | `WAIT` — do not conflate platform UX permissions with MSO authorization |+| Explicit uninstall/remove only | Mutations are explicit | Strong: uninstall requires explicit user removal intent and exact targets | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Project MCP delete is exact-project + revision guarded; Skill Market refuses unmanaged removal; App UI confirms uninstall; managed runtime uninstall is job-based | Shared removal UX vocabulary | `ALREADY_STRONGER` at enforcement level |+| Canonical identity instead of guessed identifiers | Strong target identity discipline | Strong: exact returned plugin IDs or unambiguous names; broad targets are refused | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Exact project ids, skill ids, user/provider/connection and server aliases already fail closed on ambiguity | Generic identity resolver | `ALREADY_STRONGER` |+| Public legal/support metadata for submission | Present in Shopify package | Present: website/privacy/terms in package manifest | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | MSO has real repository/website metadata but intentionally does not invent missing legal/support URLs | Submission metadata checklist | `WAIT` until real public surfaces exist |+| Target-aware capability resolver | Strong target/API legality concept | Partial: availability depends on built-ins, installed/connected state and dependency status | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Target/action metadata + dynamic project/provider discovery exist, but no universal actor+project+surface+target+environment resolver | Capability resolver | `WAIT` — strengthened candidate |+| Bulk/partial-failure result contract | Strong Shopify candidate | No evidence in current Plugin Management schemas | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | No universal result shape | `BulkResult` | `WAIT` |+| Mandatory postcondition/refetch contract | Strong Shopify candidate | Partial: skill requires verifying installation/connection before claiming state | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Verify metadata/evidence exists, but not every mutation has automatic postcondition execution | Postcondition runner | `WAIT` |+| Query/analytics DSL | ShopifyQL reference | No evidence | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | `read_pipeline` already supports select/filter/sort/unique/aggregate | Query DSL | `WAIT` for Analytics reference |++## Plugin Management audit — 0.1.0++Operator-local reference snapshot: `plugin-references/plugin-management/0.1.0` outside the portable MSO source tree.++### Architecture++The local package is deliberately thin:++```text+plugin-management/+├── .codex-remote-plugin-install.json # remote plugin identity+└── 0.1.0/+ ├── .codex-plugin/plugin.json # package/interface metadata+ ├── .app.json # required registered app dependency+ ├── assets/plugin-management.svg+ └── skills/plugin-management/SKILL.md+```++The package itself does not contain the runtime implementation of Plugin Management. Its local responsibility is packaging plus model routing. The installed app exposes the operational contracts for plugin search/suggestion, permissions, dependency inspection and uninstall.++### Behavior contract++1. Prefer an already available built-in capability.+2. Prefer an already connected plugin when it can finish the task.+3. Search the plugin directory only when an external app/account/service/data source would materially help and no available capability can access it.+4. Search with concise provider/capability terms, not the whole request.+5. Suggest only exact returned plugin identities; suggestions do not install/connect by themselves and must not block independent work.+6. Do not suggest already installed or pending plugins.+7. Treat permissions and dependencies as inspectable state, separate from plugin installation/connection.+8. Permission changes require the intended exact app and explicit or unambiguous requested mode; app-specific permissions may inherit the global default.+9. Uninstall requires explicit removal intent and exact targets.+10. Never claim installed/connected state without verification.++### Comparison with MSO++MSO is already stronger in exact target identity, trust levels, project isolation, credential isolation, CAS/revision guards, scoped OAuth authorization, dynamic MCP discovery, evidence receipts, shell escape-hatch preservation and removal safeguards. Plugin Management is clearer in one area: the model-facing mental model for choosing an existing capability versus discovering a new extension, and the separation between package identity, registered app dependency, connection state and permission policy.++MSO therefore should not collapse `Skill`, `Project Plugin`, `MCP`, `Integration`, `App`, and `Managed App` into one object. They own different authority. The immediate improvement is to make that taxonomy and routing order explicit. Generic dependency graphs, platform-style permission inheritance and suggestion state remain candidates until additional plugin references show the same pattern.++### Shopify candidate impact++- **Universal lifecycle engine:** mildly strengthened; Plugin Management also separates discovery/inspection from mutation, but does not prove a declarative universal runtime engine.+- **Knowledge/schema pack:** no supporting evidence in this snapshot.+- **Target-aware capability resolver:** strengthened; availability depends on currently available built-ins, installed/connected plugins and dependency state.+- **Bulk/partial failure result:** no supporting evidence.+- **Postcondition runner:** mildly strengthened by the explicit rule to verify install/connection before claiming state, but still not enough for an automatic generic runner.+- **Query/analytics DSL:** no supporting evidence.+- **Public submission metadata:** strengthened; Plugin Management also declares website/privacy/terms metadata.++### Decision++**Implement now:** canonical extension taxonomy and capability-selection routing guidance.++**Wait for more references:** generic plugin/extension search-and-suggest primitive, dependency graph, pending-install state, platform-style permission inheritance, universal lifecycle/postcondition engines, and public submission metadata beyond real URLs MSO already owns.++**Reject:** collapsing distinct MSO authority domains into a single generic “plugin” object, hiding existing low-level capabilities to mimic a simpler plugin product, or allowing package metadata to become an authorization/security authority.diff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex 02aca1e2..2f1eb0ab 100644--- a/docs/PROGRESS.md+++ b/docs/PROGRESS.md@@ -1,3 +1,7 @@+## 2026-09-17 — Plugin Management reference audit and extension taxonomy++Audited the local OpenAI `plugin-management` 0.1.0 package plus its installed tool contracts. The recurring improvement is model-facing capability selection and terminology, not a reason to collapse MSO authorities: Skills remain trusted instructions, Project Plugins remain exact-project capability packages, MCP remains the tool protocol, Integrations remains the credential authority, Apps remain workspace UI, and Managed Apps remain external service runtimes. Added the living `docs/PLUGIN-REFERENCE-MATRIX.md`, made that taxonomy canonical in `docs/ARCHITECTURE.md`, and updated the main `/mso` skill to reuse existing native/project/integration capabilities before adding a new plugin. No tools, scopes, credential behavior, low-level primitives, or descriptor schemas were removed or added. Generic suggestion state, dependency graphs, platform-style permission inheritance, and universal lifecycle/postcondition engines remain cross-reference candidates rather than one-plugin abstractions.+## 2026-09-17 — ChatGPT List surface and OpenAI app scaffoldAdded `render_mso_list` + `ui://mso/list-v1.html` as the lightweight collection surface between Block and Page. Data tools remain headless; the model first fetches/filters structured results, then renders at most 40 selected items as list/grid with local search, bounded metadata and user-approved follow-up actions. The widget has no network/tool-call path and cannot execute mutations. ChatGPT now exposes 113 transport tools while retaining the strict 96 KiB internal descriptor budget through scanner-only summary compaction; full MCP descriptions and runtime schemas remain unchanged. `.app.json` is now a valid empty registered-app scaffold referenced by the compatibility manifest, with skill checks rejecting malformed or placeholder mappings.diff --git a/docs/README.md b/docs/README.mdindex f4ac74b6..f2871f70 100644--- a/docs/README.md+++ b/docs/README.md@@ -44,6 +44,7 @@ evidence and review freshness. The repository quality gate runs both automatical| [`SUBAGENTS.md`](./SUBAGENTS.md) | Same-session foreground isolated worker lifecycle, context, tool authority and limits || [`MCP-FEATURE-IMPLEMENTATION.md`](./MCP-FEATURE-IMPLEMENTATION.md) | Stepwise reverse-engineering workflow for MCP tools, trusted skills and project capabilities || [`CHATGPT-PLUGIN.md`](./CHATGPT-PLUGIN.md) | ChatGPT custom MCP app setup, diagrams, scopes and file bridge |+| [`PLUGIN-REFERENCE-MATRIX.md`](./PLUGIN-REFERENCE-MATRIX.md) | Living cross-plugin architecture matrix, audit decisions and candidate generic primitives || [`MANAGED-APPS.md`](./MANAGED-APPS.md) | Hermes/OpenClaw/9Router lifecycle, jobs, backup/restore and dashboard access boundary || [`HERMES-INTEGRATION.md`](./HERMES-INTEGRATION.md) | Hermes-specific integration behaviour || [`OPENCLAW-INTEGRATION.md`](./OPENCLAW-INTEGRATION.md) | OpenClaw-specific integration behaviour |