docs(plugins): standardize on pnpx and unify plugin docs structure (#123)

Author: antfubot

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)

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

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)

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

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.

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.

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)

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)

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

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.
  */