From ec828217ea264f3aa044b005f26da70f236b2ac6 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Wed, 22 Jul 2026 05:30:56 +0000
Subject: [PATCH] docs(plugins): standardize on pnpx and unify plugin docs
 structure

- Replace every npx / bare-bin CLI instruction across docs/plugins/*.md,
  plugins/*/README.md, and cli.ts doc-comments with
  `pnpx @devframes/plugin-xxxx`.
- Give every docs/plugins/*.md page the same shape: What it does,
  Standalone, Mount into a Vite host, Programmatic, RPC surface, Source.
- Fill in the gaps this surfaced: a fixed package name in a11y.md, and
  new Standalone / Mount / Programmatic / RPC surface / Source sections
  for og.md, a11y.md, data-inspector.md, and terminals.md.

Docs only; generated with the help of an agent.
---
 docs/plugins/a11y.md             | 50 +++++++++++++++++++++++++++-----
 docs/plugins/code-server.md      |  2 +-
 docs/plugins/data-inspector.md   | 34 ++++++++++++++++------
 docs/plugins/git.md              |  6 ++--
 docs/plugins/index.md            |  8 ++---
 docs/plugins/inspect.md          |  2 +-
 docs/plugins/og.md               | 44 ++++++++++++++++++++++++----
 docs/plugins/terminals.md        | 21 +++++++++++++-
 plugins/a11y/README.md           |  3 +-
 plugins/a11y/src/cli.ts          |  2 +-
 plugins/code-server/README.md    |  2 +-
 plugins/data-inspector/README.md |  8 ++---
 plugins/git/README.md            |  8 ++---
 plugins/inspect/README.md        |  2 +-
 plugins/inspect/src/cli.ts       |  2 +-
 plugins/messages/README.md       |  2 +-
 plugins/messages/src/cli.ts      |  2 +-
 plugins/og/README.md             |  2 +-
 18 files changed, 152 insertions(+), 48 deletions(-)

diff --git a/docs/plugins/a11y.md b/docs/plugins/a11y.md
index 8ef086b9..aebf290e 100644
--- a/docs/plugins/a11y.md
+++ b/docs/plugins/a11y.md
@@ -6,7 +6,7 @@ outline: deep
 
 An accessibility inspector that runs [axe-core](https://github.com/dequelabs/axe-core) against a host application, lists the WCAG A/AA violations in a **Solid** panel, and highlights the offending element in the page when you hover a warning.
 
-Package: `@devframes/a11y` · framework: **Solid + Vite**
+Package: `@devframes/plugin-a11y` · framework: **Solid + Vite**
 
 ## What it does
 
@@ -34,6 +34,48 @@ await mountDevframe(ctx, a11yDevframe, {
 
 Outside a hub, one `<script type="module">` for the same bundle boots the agent standalone — the scan loop is identical, with the feed mirror simply absent.
 
+## Standalone
+
+```sh
+pnpx @devframes/plugin-a11y
+```
+
+Runs the panel alone, without a host page to scan — serves at `/__devframes_plugin_a11y/` even standalone, so the mount path matches the hosted case. Useful for a quick look at the panel UI; pair it with a manually-loaded agent script to drive it against a real page.
+
+## Mount into a Vite host
+
+```ts
+// vite.config.ts
+import { a11yVitePlugin } from '@devframes/plugin-a11y/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [
+    a11yVitePlugin(),
+  ],
+})
+```
+
+## Programmatic
+
+`createA11yDevframe(options)` returns a definition you can deploy through any adapter:
+
+```ts
+import { createA11yDevframe } from '@devframes/plugin-a11y'
+
+export default createA11yDevframe({
+  port: 9899,
+})
+```
+
+## RPC surface
+
+All functions are namespaced `devframes:plugin:a11y:*`:
+
+| Function | Type | Returns |
+|----------|------|---------|
+| `get-config` | `static` | The impact taxonomy (with developer-facing copy) and the `BroadcastChannel` coordinates the panel uses to find its injected agent. |
+
 ## Run the demo
 
 The Accessibility Inspector lives in the repository as a reference plugin. Its demo serves an intentionally-broken host page and the panel from one origin so they share the channel:
@@ -47,12 +89,6 @@ pnpm -C plugins/a11y demo:build  # static: baked RPC dump, no server
 
 Open the printed URL, then hover any row in the panel — the matching element in the page gets a focus ring and scrolls into view if it is off-screen. Both demo modes behave identically; the panel's `websocket` / `static` tag is the only tell.
 
-Run the panel on its own, without a host app:
-
-```sh
-pnpm -C plugins/a11y dev
-```
-
 ## Source
 
 [`plugins/a11y`](https://github.com/devframes/devframe/tree/main/plugins/a11y)
diff --git a/docs/plugins/code-server.md b/docs/plugins/code-server.md
index b2366f4c..b9e2f915 100644
--- a/docs/plugins/code-server.md
+++ b/docs/plugins/code-server.md
@@ -32,7 +32,7 @@ The editor iframe points at the server's own origin, so its WebSocket traffic fl
 ## Standalone
 
 ```sh
-npx @devframes/plugin-code-server
+pnpx @devframes/plugin-code-server
 ```
 
 ## Mount into a Vite host
diff --git a/docs/plugins/data-inspector.md b/docs/plugins/data-inspector.md
index c911d596..8041a616 100644
--- a/docs/plugins/data-inspector.md
+++ b/docs/plugins/data-inspector.md
@@ -70,6 +70,17 @@ ctx.services.whenAvailable('devframes:plugin:data-inspector:sources', (sources)
 > [!WARNING]
 > Queries are eval-grade access to registered objects: jora can invoke any function reachable as an own property and fires own getters. Register live objects with that in mind, and keep inspector endpoints on loopback.
 
+## Standalone
+
+```sh
+pnpx @devframes/plugin-data-inspector                      # the example source
+pnpx @devframes/plugin-data-inspector stats.json log.jsonl # one static source per data file
+pnpx @devframes/plugin-data-inspector build stats.json     # self-contained static export
+pnpx @devframes/plugin-data-inspector attach               # attach to a process running the agent
+```
+
+`.json` files parse whole; `.jsonl` / `.ndjson` parse as an array of records. `build` writes a static site embedding the dataset — the same query engine runs client-side there, so saved recipes keep working.
+
 ## Mount into a Vite host
 
 ```ts
@@ -98,16 +109,17 @@ export default defineConfig({
 
 Hub hosts mount the default export like any devframe definition.
 
-## Standalone CLI
+## Programmatic
 
-```sh
-devframe-data-inspector                      # the example source
-devframe-data-inspector stats.json log.jsonl # one static source per data file
-devframe-data-inspector build stats.json     # self-contained static export
-devframe-data-inspector attach               # attach to a process running the agent
-```
+`createDataInspectorDevframe(options)` returns a definition you can deploy through any adapter:
 
-`.json` files parse whole; `.jsonl` / `.ndjson` parse as an array of records. `build` writes a static site embedding the dataset — the same query engine runs client-side there, so saved recipes keep working.
+```ts
+import { createDataInspectorDevframe } from '@devframes/plugin-data-inspector'
+
+export default createDataInspectorDevframe({
+  exampleSource: false,
+})
+```
 
 ## Attach to another Node process
 
@@ -139,7 +151,7 @@ globalThis.cache = cache
 
 Then query `store`, `cache`, or `keys($)` to see what's there. The source reads `globalThis` at query time, so assignments made after the agent started show up on the next run. Opt out with `DEVFRAME_DATA_INSPECTOR_GLOBAL=0`.
 
-The agent binds `127.0.0.1`, requires devframe's trust handshake with a per-run pre-shared token, and advertises its endpoint in `node_modules/.data-inspector/agent.json` — `devframe-data-inspector attach` consumes it automatically (or pass `ws://…` and `--token` explicitly). Queries execute inside the target process, where the live objects are. Treat the endpoint like a debugger port.
+The agent binds `127.0.0.1`, requires devframe's trust handshake with a per-run pre-shared token, and advertises its endpoint in `node_modules/.data-inspector/agent.json` — `pnpx @devframes/plugin-data-inspector attach` consumes it automatically (or pass `ws://…` and `--token` explicitly). Queries execute inside the target process, where the live objects are. Treat the endpoint like a debugger port.
 
 ## RPC surface
 
@@ -153,3 +165,7 @@ All functions are namespaced `devframes:plugin:data-inspector:*`:
 | `skeleton` | `query` | The type skeleton of a source, honoring the filter options. |
 | `suggest` | `query` | Autocomplete candidates from jora's stat mode at a cursor position. |
 | `saved:list` / `saved:save` / `saved:delete` | `query` / `action` | Saved-query recipes in the `workspace` and `project` scopes. |
+
+## Source
+
+[`plugins/data-inspector`](https://github.com/devframes/devframe/tree/main/plugins/data-inspector)
diff --git a/docs/plugins/git.md b/docs/plugins/git.md
index 66a5c6b4..ae95740f 100644
--- a/docs/plugins/git.md
+++ b/docs/plugins/git.md
@@ -15,9 +15,9 @@ Status, a SourceTree-style commit graph, branches, and diffs are read-only. Stag
 ## Standalone
 
 ```sh
-npx @devframes/plugin-git              # dev server (live RPC over WebSocket)
-npx @devframes/plugin-git --write      # also enable staging / committing from the UI
-npx @devframes/plugin-git build        # static deploy → dist-static/
+pnpx @devframes/plugin-git         # dev server (live RPC over WebSocket)
+pnpx @devframes/plugin-git --write # also enable staging / committing from the UI
+pnpx @devframes/plugin-git build   # static deploy → dist-static/
 ```
 
 ## Programmatic
diff --git a/docs/plugins/index.md b/docs/plugins/index.md
index 3bbebb51..afccdc2c 100644
--- a/docs/plugins/index.md
+++ b/docs/plugins/index.md
@@ -26,12 +26,12 @@ This is the framework-agnostic promise in practice. The browser bundle is the au
 
 ## Running a plugin
 
-Most plugins publish a `bin`, so the quickest path is `npx`:
+Most plugins publish a `bin`, so the quickest path is `pnpx`:
 
 ```sh
-npx @devframes/plugin-inspect      # the Devframe Inspector, standalone
-npx @devframes/plugin-og           # inspect Open Graph metadata and social cards
-npx @devframes/plugin-git          # the Git dashboard against the current repo
+pnpx @devframes/plugin-inspect      # the Devframe Inspector, standalone
+pnpx @devframes/plugin-og           # inspect Open Graph metadata and social cards
+pnpx @devframes/plugin-git          # the Git dashboard against the current repo
 ```
 
 Each also exports a `create…Devframe` factory (or, for the Accessibility Inspector, a ready-made definition) you can drive through any adapter — see the individual pages for the factory name, options, and host-mount snippets.
diff --git a/docs/plugins/inspect.md b/docs/plugins/inspect.md
index c561bd2c..80dabf20 100644
--- a/docs/plugins/inspect.md
+++ b/docs/plugins/inspect.md
@@ -20,7 +20,7 @@ The three introspection `query` functions are agent-exposed and bake into the st
 ## Standalone
 
 ```sh
-npx @devframes/plugin-inspect
+pnpx @devframes/plugin-inspect
 ```
 
 Opens the inspector against a fresh standalone devframe connection — handy as a reference and for poking at the introspection RPCs themselves. The CLI prints the URL it serves on.
diff --git a/docs/plugins/og.md b/docs/plugins/og.md
index 63f42059..ae8ab651 100644
--- a/docs/plugins/og.md
+++ b/docs/plugins/og.md
@@ -4,17 +4,39 @@ outline: deep
 
 # Open Graph Viewer
 
-Inspect a page's resolved Open Graph and Twitter metadata and compare its social cards across common platforms.
+Inspect a page's resolved Open Graph and Twitter metadata and compare its social cards across common platforms, built as a **Vue** SPA.
 
-## Run Standalone
+Package: `@devframes/plugin-og` · framework: **Vue + Vite**
+
+## What it does
+
+Enter any HTTP or HTTPS page reachable from the devframe process. The viewer resolves relative image and icon URLs against the fetched document, renders the resulting social cards for Twitter, Facebook, LinkedIn, and Telegram, and identifies missing metadata with a ready-to-use Nuxt `useSeoMeta()` snippet.
+
+The standalone server requires devframe's trust handshake by default because it can request developer-supplied URLs. Set `auth: false` only for an isolated local environment.
+
+## Standalone
 
 ```sh
-npx @devframes/plugin-og
+pnpx @devframes/plugin-og
 ```
 
-Enter any HTTP or HTTPS page reachable from the devframe process. The viewer resolves relative image and icon URLs against the fetched document and identifies missing metadata with a ready-to-use Nuxt `useSeoMeta()` snippet.
+## Mount into a Vite host
 
-## Create A Definition
+```ts
+// vite.config.ts
+import { ogVitePlugin } from '@devframes/plugin-og/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [
+    ogVitePlugin(),
+  ],
+})
+```
+
+## Programmatic
+
+`createOgDevframe(options)` returns a definition you can deploy through any adapter:
 
 ```ts
 import { createOgDevframe } from '@devframes/plugin-og'
@@ -26,4 +48,14 @@ export default createOgDevframe({
 
 `defaultUrl` supplies the initial target and makes `devframe build` bake that page into the static RPC dump. The resulting report keeps its assets relative and runs from any deployment path.
 
-The standalone server requires devframe's trust handshake by default because it can request developer-supplied URLs. Set `auth: false` only for an isolated local environment.
+## RPC surface
+
+All functions are namespaced `devframes:plugin:og:*`:
+
+| Function | Type | Returns |
+|----------|------|---------|
+| `resolve-metadata` | `query` | Fetches an HTTP or HTTPS page and returns its normalized title, language, Open Graph, Twitter, and link metadata. |
+
+## Source
+
+[`plugins/og`](https://github.com/devframes/devframe/tree/main/plugins/og)
diff --git a/docs/plugins/terminals.md b/docs/plugins/terminals.md
index a066babf..3522abc1 100644
--- a/docs/plugins/terminals.md
+++ b/docs/plugins/terminals.md
@@ -19,7 +19,7 @@ Interactive shells run on a real pseudo-terminal via [`zigpty`](https://github.c
 ## Standalone
 
 ```sh
-npx @devframes/plugin-terminals
+pnpx @devframes/plugin-terminals
 ```
 
 ## Mount into a Vite host
@@ -72,6 +72,25 @@ await rpc.call('hub:docks:activate', {
 
 It works whether the panel is already open (it reacts to the `devframe:docks:active` shared-state slot) or mounts in response to the switch (it reads the slot on start and converges). Focus is one-shot: an unknown or not-yet-arrived session id waits for that session to appear, and the user's own tab clicks are always honored afterward. A session id that never appears is a no-op — the default selection (most-recent session) stands.
 
+## RPC surface
+
+All functions are namespaced `devframes:plugin:terminals:*`:
+
+| Function | Type | Purpose |
+|----------|------|---------|
+| `list` | `query` (snapshot) | The current sessions with their status, mode, and command. |
+| `presets` | `query` (snapshot) | The declared launcher presets. |
+| `spawn` | `action` | Start a new session from a preset id, or a command + mode. Interactive sessions accept input; readonly sessions only stream output. |
+| `write` | `action` | Send input to an interactive session. |
+| `resize` | `action` | Resize a session's PTY to the given columns and rows. |
+| `restart` | `action` | Restart a session's process, keeping its id and scrollback. |
+| `rename` | `action` | Rename a session. |
+| `terminate` | `action` | End a session's running process; keeps the session and its scrollback. |
+| `remove` | `action` | Kill a session and discard it (process, stream, and scrollback). |
+| `clear-exited` | `action` | Discard every stopped session at once; running sessions are left untouched. |
+
+Status (and every mutation above) is mirrored into shared state, so every connected panel stays in sync.
+
 ## Source
 
 [`plugins/terminals`](https://github.com/devframes/devframe/tree/main/plugins/terminals)
diff --git a/plugins/a11y/README.md b/plugins/a11y/README.md
index 46ce0cc7..aae2f179 100644
--- a/plugins/a11y/README.md
+++ b/plugins/a11y/README.md
@@ -65,7 +65,8 @@ behave identically; the panel's `websocket` / `static` tag is the only tell.
 Standalone, without a host app:
 
 ```sh
-pnpm -C plugins/a11y dev         # panel only, at /__devframes_plugin_a11y/
+pnpx @devframes/plugin-a11y      # the published package, panel only, at /__devframes_plugin_a11y/
+pnpm -C plugins/a11y dev         # from source: same, at /__devframes_plugin_a11y/
 ```
 
 ## File map
diff --git a/plugins/a11y/src/cli.ts b/plugins/a11y/src/cli.ts
index 426715ef..50b0c9ba 100644
--- a/plugins/a11y/src/cli.ts
+++ b/plugins/a11y/src/cli.ts
@@ -4,7 +4,7 @@ import a11yDevframe from './index.ts'
 
 /**
  * Build the standalone CLI for the a11y inspector — backs the package `bin`
- * (`devframes_plugin_a11y`) and `npx @devframes/plugin-a11y`. Wraps the
+ * (`devframes_plugin_a11y`) and `pnpx @devframes/plugin-a11y`. Wraps the
  * default {@link createA11yDevframe} definition with devframe's
  * `dev` / `build` / `spa` command shell.
  */
diff --git a/plugins/code-server/README.md b/plugins/code-server/README.md
index 02be9c29..70e5826f 100644
--- a/plugins/code-server/README.md
+++ b/plugins/code-server/README.md
@@ -41,7 +41,7 @@ launcher; `vscode.dev` handles authentication.
 ### Standalone CLI
 
 ```sh
-npx @devframes/plugin-code-server        # dev server + launcher
+pnpx @devframes/plugin-code-server        # dev server + launcher
 ```
 
 ### Programmatic
diff --git a/plugins/data-inspector/README.md b/plugins/data-inspector/README.md
index dc2f8217..2a0defcb 100644
--- a/plugins/data-inspector/README.md
+++ b/plugins/data-inspector/README.md
@@ -38,9 +38,9 @@ import { dataInspectorVitePlugin } from '@devframes/plugin-data-inspector/vite'
 ## Standalone CLI
 
 ```sh
-devframe-data-inspector stats.json trace.jsonl   # inspect local data files
-devframe-data-inspector build stats.json         # self-contained static export
-devframe-data-inspector attach                   # attach to a process running the agent
+pnpx @devframes/plugin-data-inspector stats.json trace.jsonl # inspect local data files
+pnpx @devframes/plugin-data-inspector build stats.json       # self-contained static export
+pnpx @devframes/plugin-data-inspector attach                 # attach to a process running the agent
 ```
 
 Static exports embed the dataset and run the same query engine client-side, so saved recipes stay portable.
@@ -64,7 +64,7 @@ DEVFRAME_DATA_INSPECTOR=1 node --import @devframes/plugin-data-inspector/inject
 
 On the zero-code path there's nowhere to call `registerDataSource`, so the agent auto-registers a **`globalThis`** source: assign what you want to inspect onto the global object (`globalThis.store = store`) and query it live. Opt out with `DEVFRAME_DATA_INSPECTOR_GLOBAL=0`.
 
-The agent binds `127.0.0.1`, requires devframe's trust handshake with a per-run token by default, and advertises its endpoint in `node_modules/.data-inspector/agent.json`, which `devframe-data-inspector attach` picks up automatically.
+The agent binds `127.0.0.1`, requires devframe's trust handshake with a per-run token by default, and advertises its endpoint in `node_modules/.data-inspector/agent.json`, which `pnpx @devframes/plugin-data-inspector attach` picks up automatically.
 
 > [!WARNING]
 > A connected inspector runs eval-grade jora queries against live objects: queries can invoke functions reachable as own properties and fire getters. Treat the agent endpoint like a debugger port — keep it on loopback and keep auth on.
diff --git a/plugins/git/README.md b/plugins/git/README.md
index 8b485054..546c4ebf 100644
--- a/plugins/git/README.md
+++ b/plugins/git/README.md
@@ -24,10 +24,10 @@ npm i -D @devframes/plugin-git
 Run the dashboard against the current repository:
 
 ```sh
-npx devframe-git              # dev server (live RPC over WebSocket)
-npx devframe-git --write      # also enable staging / committing from the UI
-npx devframe-git build        # static deploy → dist-static/
-npx devframe-git --port 4000
+pnpx @devframes/plugin-git         # dev server (live RPC over WebSocket)
+pnpx @devframes/plugin-git --write # also enable staging / committing from the UI
+pnpx @devframes/plugin-git build   # static deploy → dist-static/
+pnpx @devframes/plugin-git --port 4000
 ```
 
 ## Programmatic
diff --git a/plugins/inspect/README.md b/plugins/inspect/README.md
index cc2ffcef..0942baf8 100644
--- a/plugins/inspect/README.md
+++ b/plugins/inspect/README.md
@@ -16,7 +16,7 @@ framework-neutral client (`connectDevframe`, `rpc.sharedState`) with a Vue + Vit
 ## Use it standalone
 
 ```bash
-npx @devframes/plugin-inspect
+pnpx @devframes/plugin-inspect
 ```
 
 Opens the inspector against a fresh standalone devframe connection — useful as a
diff --git a/plugins/inspect/src/cli.ts b/plugins/inspect/src/cli.ts
index 4718a781..6f072582 100644
--- a/plugins/inspect/src/cli.ts
+++ b/plugins/inspect/src/cli.ts
@@ -4,7 +4,7 @@ import inspectDevframe from './index'
 
 /**
  * Build the standalone CLI for the inspector — backs the package `bin`
- * (`devframe-inspect`) and `npx @devframes/plugin-inspect`. Wraps the
+ * (`devframe-inspect`) and `pnpx @devframes/plugin-inspect`. Wraps the
  * default {@link createInspectDevframe} definition with devframe's
  * `dev` / `build` / `spa` / `mcp` command shell.
  */
diff --git a/plugins/messages/README.md b/plugins/messages/README.md
index 6a6dcb8b..658d3f59 100644
--- a/plugins/messages/README.md
+++ b/plugins/messages/README.md
@@ -42,7 +42,7 @@ const handle = await mountMessages(document.querySelector('#panel')!, {
 ## Standalone
 
 ```bash
-npx @devframes/plugin-messages
+pnpx @devframes/plugin-messages
 ```
 
 `pnpm dev` in this package self-hosts the SPA against a demo-seeded messages
diff --git a/plugins/messages/src/cli.ts b/plugins/messages/src/cli.ts
index 1021023d..6cee4f1e 100644
--- a/plugins/messages/src/cli.ts
+++ b/plugins/messages/src/cli.ts
@@ -4,7 +4,7 @@ import messagesDevframe from './index'
 
 /**
  * Build the standalone CLI for the messages panel — backs the package `bin`
- * (`devframe-messages`) and `npx @devframes/plugin-messages`. Wraps the
+ * (`devframe-messages`) and `pnpx @devframes/plugin-messages`. Wraps the
  * default {@link createMessagesDevframe} definition with devframe's
  * `dev` / `build` / `spa` / `mcp` command shell.
  */
diff --git a/plugins/og/README.md b/plugins/og/README.md
index ccee16fc..83b3d96f 100644
--- a/plugins/og/README.md
+++ b/plugins/og/README.md
@@ -3,7 +3,7 @@
 Inspect Open Graph and Twitter metadata for any reachable page, then compare its social preview across Twitter, Facebook, LinkedIn, and Telegram.
 
 ```sh
-npx @devframes/plugin-og
+pnpx @devframes/plugin-og
 ```
 
 The package exports `createOgDevframe()` for custom definitions and `ogVitePlugin()` from `@devframes/plugin-og/vite` for Vite hosts. Pass `defaultUrl` to bake a shareable report with the devframe build adapter.