@gxp-dev/tools 2.0.71 → 2.0.73

package/template/AGENTS.md

@@ -2,6 +2,96 @@
 
 This is a GxP plugin project for the GxP kiosk platform. Follow these guidelines when working with this codebase.
 
+## Development Workflow
+
+Every task starts with understanding and ends with a validated, linted build. Do not skip steps.
+
+### 1. Understand what the client is building
+
+Before touching code, get specific about the feature:
+
+- What is the user-facing outcome? Who uses it (attendee, staff, admin)?
+- Which real-world data does it read or write?
+- What events does it react to in real time?
+- What needs to be configurable by an admin (text, assets, colors, thresholds, feature flags)?
+
+Ask clarifying questions instead of guessing. A 30-second question beats a 30-minute rewrite.
+
+### 2. Discover the right data sources via MCP
+
+Use the `gxp-api` MCP server to ground the implementation in the real platform — never invent endpoints or event names.
+
+- **Find endpoints** — `api_list_tags`, `api_list_operation_ids` (optionally scoped by tag), `search_api_endpoints` (keyword).
+- **Inspect a specific endpoint** — `api_get_operation_parameters`, `get_endpoint_details`.
+- **Find endpoints by payload shape** — `api_find_endpoints_by_schema` (search by request/response field names).
+- **Find WebSocket events** — `api_find_events_for_operation` (given an operationId, returns events via `x-triggered-by`), `api_list_events`, `search_websocket_events`, `get_asyncapi_spec`. Run `api_find_events_for_operation` for every operationId you plan to call so you subscribe instead of polling.
+- **Generate dependency JSON** — `api_generate_dependency` produces the canonical entry for `app-manifest.json` → `dependencies`.
+- **Read the docs** — `docs_list_pages`, `docs_search`, `docs_get_page` (full-text search across docs.gxp.dev).
+
+Output of this step: a short list of the operationIds, WebSocket events, and dependencies the plugin will use.
+
+### 3. Plan with the client, including the admin config form
+
+Before writing code, produce a plan and confirm it with the client. The plan must include:
+
+- **Screens/components** — what's rendered and in which layout (Public/Private/System).
+- **Data flow** — which store getters read which sections, which API calls populate them, which socket events mutate state.
+- **Admin configuration form** — every piece of customizable content belongs in `configuration.json` as a card/field so admins can edit it without a code change. Cover text (strings), images (assets), colors/thresholds (settings), and feature toggles.
+- **Strings and assets inventory** — the exact keys that will appear in `app-manifest.json`.
+
+Do not proceed to implementation until the client has reviewed the plan.
+
+### 4. Implement
+
+Build against the plan:
+
+- Use the GxP store for **all** data access — `store.callApi(operationId, identifier, data)` for platform API calls, plus sockets, strings, assets, settings, state. Never use `axios` or `fetch` directly.
+- Declare every permission identifier used by `callApi` in `app-manifest.json` → `dependencies` + `permissions`. Use `"project"` for project-wide / top-level operations and pass any required IDs in `data`.
+- Wire every piece of user-facing text with `gxp-string` and every image with `gxp-src` so the admin form controls them.
+- Keep components under `src/`. The runtime container (layouts, routing, dev tools) is not yours to edit.
+
+### 5. Sync the manifest and build the admin form
+
+As soon as you've added a new `store.callApi`, `store.listen`, `gxp-string`, or `gxp-src` — and before you move on to testing — close the loop on the admin-editable surface:
+
+1. **Extract the configurable surface into `app-manifest.json`.** Run the MCP tool `config_extract_strings` with `writeTo: "app-manifest.json"`. It scans `src/` for every `gxp-string`, `gxp-src`, `store.getString/getSetting/getAsset/getState`, and `store.callApi` identifier and merges the new keys into the manifest (linter-guarded; falls back to `gxdev extract-config` on the CLI if you need it). Do this every time you touch the plugin's public surface so the manifest never drifts from the code.
+
+2. **Build `configuration.json` from what's in the manifest.** For every entry in the manifest, add a matching field in the admin form using the MCP `config_*` tools — they validate each write against the schema. Default mappings:
+
+   | Manifest entry                                   | `configuration.json` field type                                                                  |
+   | ------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+   | `strings.default.*`                              | `text` (or `textarea` for long copy)                                                             |
+   | `assets.*` (driven by `gxp-src`)                 | `selectAsset`                                                                                    |
+   | `dependencies[]` — each identifier               | `asyncSelect` wired to the matching resource list endpoint (so the admin binds to a real record) |
+   | `settings.*` that represent colors               | `colorPicker`                                                                                    |
+   | `settings.*` that represent thresholds / numbers | `number`                                                                                         |
+   | `settings.*` that represent feature toggles      | `boolean`                                                                                        |
+   | Anything else discussed with the client          | Pick with `config_list_field_types` / `config_get_field_schema`                                  |
+
+   Group related fields into `fields_list` cards (`config_add_card` + `config_add_field`). If you're unsure what field types exist, call `config_list_field_types` / `config_list_card_types` first. If a mutation is refused, read the validation error and fix the input — do not set `force: true`.
+
+3. **Lint.** Run `gxdev lint --all` and fix every error before moving on.
+
+### 6. Test with real broadcasts
+
+Before declaring done, exercise the plugin against real event shapes:
+
+- List available events — `gxdev socket list`.
+- Send one — `gxdev socket send --event <EventName>` (edit or add payloads under `socket-events/`).
+- Hit endpoints against the local mock API via the `test_api_route` MCP tool.
+- Scaffold unit tests with `test_scaffold_component_test` for any non-trivial component.
+
+### 7. Final lint
+
+Step 5 already runs `gxdev lint --all`, but run it one more time after Step 6's test pass — test changes (adding mock payloads, tweaking identifiers) can re-introduce schema drift.
+
+```bash
+gxdev lint           # validate default targets
+gxdev lint --all     # validate everything
+```
+
+Fix every error. Do not mark work complete with a failing lint.
+
 ## Project Architecture
 
 This plugin runs inside a container environment provided by the `gxdev` development server. You should ONLY modify files in the `src/` directory. The runtime container (PortalContainer.vue) handles layouts, dev tools, routing, and store initialization.
@@ -17,30 +107,102 @@ src/
 
 ## Core Principle: Use the GxP Store for Everything
 
-The `gxpPortalConfigStore` is the central hub. Import it in any component:
+The `gxpPortalConfigStore` is the central hub for every piece of data — API, sockets, strings, assets, settings, state. Import it in any component:
 
 ```javascript
 import { useGxpStore } from "@gx-runtime/stores/gxpPortalConfigStore"
 const store = useGxpStore()
 ```
 
-## API Calls - ALWAYS Use Store Methods
+## API Calls — Use `store.callApi` with an Operation ID + Permission Identifier
+
+**Every call to the GxP platform goes through `store.callApi`.** It handles authorization, URL resolution, team/project scoping, and path-parameter substitution. You only provide three things:
 
-NEVER use axios or fetch directly. The store handles authentication, base URLs, and CORS:
+```javascript
+await store.callApi(operationId, identifier, data)
+```
+
+| Argument      | Purpose                                                                                                                                                                                                                           |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `operationId` | The OpenAPI operationId for the call. Look it up with `api_list_operation_ids` or `search_api_endpoints` (MCP). Never invent one.                                                                                                 |
+| `identifier`  | A **permission identifier** declared in `app-manifest.json` → `dependencies` / `permissions`. Determines which resource's permissions the call runs under, and supplies the parent object ID that gets substituted into the path. |
+| `data`        | Additional params — body fields, query params, or path params not covered by the identifier. Pass `"pluginVars.someKey"` as a value to pull from settings at call time.                                                           |
+
+NEVER use axios/fetch directly. `apiGet`/`apiPost`/`apiPut`/`apiPatch`/`apiDelete` still exist as low-level escape hatches, but `callApi` is the default — only it participates in the permission model.
+
+### Permission identifiers
+
+Each identifier is declared in `app-manifest.json` and later bound by an admin to a specific resource + permission scope (read, create, update, delete). Pick identifiers that describe the **role the resource plays in the plugin**, not its name.
+
+Example — a plugin that reads posts from one social stream and creates posts on another:
+
+```json
+// app-manifest.json
+{
+	"dependencies": [
+		{ "identifier": "social_stream_one", "model": "SocialStream" },
+		{ "identifier": "social_stream_two", "model": "SocialStream" }
+	],
+	"permissions": [
+		{
+			"identifier": "social_stream_one",
+			"description": "Source stream — read posts"
+		},
+		{
+			"identifier": "social_stream_two",
+			"description": "Destination stream — create posts"
+		}
+	]
+}
+```
 
 ```javascript
-// Correct - use store methods
-const data = await store.apiGet("/api/v1/endpoint", { param: "value" })
+// Read posts from the source stream
+const posts = await store.callApi("posts.index", "social_stream_one")
+
+// Create a post on the destination stream
+await store.callApi("posts.store", "social_stream_two", {
+	body: "Hello world",
+	image_url: imageUrl,
+})
+```
+
+The admin assigns `social_stream_one` read-only access to stream A and `social_stream_two` create access to stream B. The plugin code never hard-codes IDs.
+
+### The `project` identifier — project-wide, top-level operations
+
+When you need to create the parent resource itself (e.g. the social stream), or hit any endpoint scoped at the project level rather than to a specific dependency, use the reserved identifier `"project"`. `callApi` will run with project-wide permissions — but you must pass any path params the endpoint needs in `data`.
+
+```javascript
+// Create a new social stream under the project
+const stream = await store.callApi("social_streams.store", "project", {
+	name: "New Stream",
+})
+
+// Create a post directly against a known socialStreamId (no dependency binding)
+await store.callApi("posts.store", "project", {
+	socialStreamId: stream.id,
+	body: "First post",
+})
+```
+
+Rule of thumb:
+
+- Operating on a resource the admin will bind later → declare a dependency identifier and pass it.
+- Creating the parent resource itself, or acting across the whole project → use `"project"` and pass the relevant IDs in `data`.
+
+### Low-level methods (avoid unless necessary)
+
+```javascript
+await store.apiGet("/api/v1/endpoint", { param: "value" })
 await store.apiPost("/api/v1/endpoint", { data: "value" })
 await store.apiPut("/api/v1/endpoint/123", { data: "value" })
 await store.apiPatch("/api/v1/endpoint/123", { data: "value" })
 await store.apiDelete("/api/v1/endpoint/123")
-
-// WRONG - never do this
-// const response = await axios.get(...);  // NO!
-// const response = await fetch(...);      // NO!
 ```
 
+These bypass the permission model. Prefer `callApi`.
+
 ## Store Data Access
 
 ```javascript
@@ -58,26 +220,59 @@ store.updateAsset("key", "url")
 store.updateState("key", "value")
 ```
 
-## WebSocket Events
+## Real-Time Events
+
+Every plugin has two streams of real-time events, both surfaced through the store:
+
+1. **The `primary` channel** — a peer channel scoped to users of this plugin right now. Use it for in-app pub/sub (cursor positions, "someone just did X", remote controls).
+2. **Platform API events** — defined in AsyncAPI at `${apiDocsBaseUrl}/api-specs/asyncapi.json` under `components.messages`. Each message can declare `x-triggered-by` pointing at an OpenAPI operationId. When the server handles that operation, the event fires — you subscribe instead of polling.
 
-Listen for real-time events through the store:
+### The `primary` channel
 
 ```javascript
-// Listen on primary socket
-store.listenSocket("primary", "EventName", (data) => {
-	console.log("Received:", data)
+// Listen for a custom event from other users of this plugin
+store.listen("primary", "cursor_moved", (data) => {
+	console.log("Peer moved:", data)
 })
 
-// Emit events
-store.emitSocket("primary", "client-event", { data: "value" })
+// Broadcast to everyone else on the primary channel
+store.broadcast("primary", "cursor_moved", { x: 42, y: 100 })
+```
+
+### Platform API events
+
+Use the AsyncAPI form of `listen` — event name first, permission identifier second, callback third:
 
-// For dependency-based sockets
-store.useSocketListener("dependency_id", "updated", callback)
+```javascript
+store.listen("SocialStreamPostCreated", "social_stream_two", (post) => {
+	console.log("New post on the destination stream:", post)
+})
 ```
 
+The permission identifier (`"social_stream_two"` above, or `"project"` for project-wide events) is the same identifier you pass to `callApi`. It scopes the subscription to the resource the admin bound for that identifier.
+
+### Rule: whenever you add a `callApi`, check for a matching event
+
+Before wiring polling or manual refresh after a mutation, ask: does this operation fire a socket event? Use the MCP:
+
+- `api_find_events_for_operation` — given an operationId, returns every AsyncAPI message whose `x-triggered-by` matches. If it returns one, subscribe to it instead of polling.
+- `api_list_events` — list every event, optionally filtered by `triggeredBy`.
+- `search_websocket_events` — keyword search across events + channels.
+
+Example: you just added `store.callApi("posts.store", "social_stream_two", {...})`. Run `api_find_events_for_operation({ operationId: "posts.store" })`, see `SocialStreamPostCreated`, subscribe with `store.listen("SocialStreamPostCreated", "social_stream_two", cb)`. No polling.
+
+### Testing broadcasts locally
+
+```bash
+gxdev socket list                      # list available events
+gxdev socket send --event EventName    # fire a test broadcast
+```
+
+Payloads live under `socket-events/` — add or edit a JSON file to define a new one.
+
 ## Vue Directives for Dynamic Content
 
-Use these directives instead of hardcoding text and images:
+Every piece of admin-editable content goes through a directive — that's what makes the configuration form meaningful.
 
 ```html
 <!-- Text from strings -->
@@ -90,6 +285,40 @@ Use these directives instead of hardcoding text and images:
 <img gxp-src="hero_image" src="/placeholder.jpg" alt="Hero" />
 ```
 
+## Admin Configuration Form (`configuration.json`)
+
+`configuration.json` defines the form admins use to customize the plugin after it ships. Every string, asset, dependency, color, and setting your plugin exposes must have a matching field here.
+
+The full workflow — run it whenever you've added/changed a `callApi`, `listen`, `gxp-string`, or `gxp-src`:
+
+1. **Extract the configurable surface into `app-manifest.json`** — `config_extract_strings` with `writeTo: "app-manifest.json"` (same logic as `gxdev extract-config` on the CLI). It scans `src/` for directives and store usage and merges the new keys into the manifest, linter-guarded.
+2. **Add a form field in `configuration.json` for every manifest entry**, using the mapping below.
+3. **Validate** — `config_validate` on demand, or `gxdev lint --all` at the end.
+
+### Default field mapping
+
+| Manifest source                                  | `configuration.json` field                                                                  |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| `strings.default.<key>`                          | `text` (short) or `textarea` (long)                                                         |
+| `assets.<key>` (driven by `gxp-src`)             | `selectAsset`                                                                               |
+| `dependencies[]` — each declared identifier      | `asyncSelect` bound to the matching resource list endpoint so the admin picks a real record |
+| `settings.<key>` representing a color            | `colorPicker`                                                                               |
+| `settings.<key>` representing a threshold/number | `number`                                                                                    |
+| `settings.<key>` representing a feature toggle   | `boolean`                                                                                   |
+| Any other setting discussed with the client      | Pick via `config_list_field_types` / `config_get_field_schema`                              |
+
+Group related fields into `fields_list` cards (`config_add_card` then `config_add_field`). Use the `name` of each field to exactly match the manifest key it controls — that's the contract the directives and store getters rely on.
+
+### Relevant tools
+
+- `config_list_card_types`, `config_list_field_types` — enumerate what's available.
+- `config_get_field_schema` — get the shape (required props, conditional rules) of a specific field type.
+- `config_add_card`, `config_add_field`, `config_move_field`, `config_remove_field`, `config_move_card`, `config_remove_card` — mutate the form. Linter-guarded; invalid writes are refused.
+- `config_extract_strings` — the manifest-sync entry point described above.
+- `config_validate` — validate a file on demand.
+
+If a mutation is refused, read the validation error and fix the input — do not reach for `force: true`.
+
 ## Component Kit
 
 Import UI components from `@gramercytech/gx-componentkit`:
@@ -106,13 +335,26 @@ import {
 
 Available: GxButton, GxCard, GxInput, GxModal, GxSpinner, GxAlert, GxBadge, GxAvatar, GxProgress, GxTabs, GxAccordion
 
-## Configuration
+## Configuration Files
 
-Edit `app-manifest.json` for strings, assets, and settings. Changes hot-reload during development.
+- `app-manifest.json` — strings, assets, settings, dependencies, permissions. Hot-reloaded in dev.
+- `configuration.json` — admin-facing form definition (cards + fields).
+
+## Linting
+
+Run before declaring any change complete:
+
+```bash
+gxdev lint           # default targets
+gxdev lint --all     # everything
+gxdev lint --json    # machine-readable output
+```
 
 ## Testing
 
 - Socket events: `gxdev socket send --event EventName`
+- API calls against local mock: `test_api_route` MCP tool
+- Component tests: `test_scaffold_component_test` MCP tool
 - Dev Tools: Press Ctrl+Shift+D
 - Console: `window.gxDevTools.store()` to inspect store
 
@@ -127,6 +369,8 @@ Set `VITE_API_ENV` in `.env`:
 
 ## API Documentation
 
+Prefer the MCP tools (`get_openapi_spec`, `search_api_endpoints`, `docs_search`, etc.) over fetching these URLs directly:
+
 - OpenAPI Spec: https://api.zenith-develop.env.eventfinity.app/api-specs/openapi.json
 - AsyncAPI Spec: https://api.zenith-develop.env.eventfinity.app/api-specs/asyncapi.json
 - Webhooks: https://api.zenith-develop.env.eventfinity.app/api-specs/webhooks.json

package/template/GEMINI.md

@@ -2,6 +2,73 @@
 
 This is a GxP plugin project for the GxP kiosk platform built with Vue 3.
 
+## Development Workflow
+
+Work through these steps in order. Do not skip.
+
+### 1. Understand the feature
+
+Before writing anything, clarify with the client:
+
+- Who uses it and what's the user-facing outcome?
+- Which real data is read/written? Which real-time events matter?
+- What must an admin be able to customize after ship (text, images, colors, thresholds)?
+
+### 2. Discover data sources via the `gxp-api` MCP server
+
+Ground the implementation in real platform endpoints and events. Do not invent API paths or event names.
+
+- Endpoints — `api_list_tags`, `api_list_operation_ids`, `search_api_endpoints`, `api_get_operation_parameters`, `get_endpoint_details`.
+- Find by payload shape — `api_find_endpoints_by_schema`.
+- WebSocket events — `api_find_events_for_operation` (maps operationId → events via `x-triggered-by`), `api_list_events`, `search_websocket_events`, `get_asyncapi_spec`. Run for every planned operationId so you subscribe instead of polling.
+- Canonical dependency JSON — `api_generate_dependency`.
+- Documentation — `docs_list_pages`, `docs_search`, `docs_get_page`.
+
+### 3. Plan with the client
+
+Confirm a plan before implementing. It must include:
+
+- Screens/components and which layout (Public/Private/System).
+- Which store getters, API calls, and socket events power each piece of data.
+- The **admin configuration form** (`configuration.json`) — every admin-editable string, asset, color, and setting listed as cards/fields.
+- The exact keys you'll add to `app-manifest.json`.
+
+### 4. Implement
+
+- All data goes through the GxP store — `store.callApi(operationId, identifier, data)` for platform APIs, plus sockets, strings, assets, settings, state. No direct `axios`/`fetch`.
+- Every permission identifier used by `callApi` must be declared in `app-manifest.json` → `dependencies` + `permissions`. Use `"project"` for project-wide / top-level operations.
+- Wire every user-facing text with `gxp-string` and every image with `gxp-src`.
+- Only edit files under `src/`; the runtime container is off-limits.
+
+### 5. Sync the manifest and build the admin form
+
+Whenever you add or change a `store.callApi`, `store.listen`, `gxp-string`, or `gxp-src`, close the loop on the admin-editable surface before you move on:
+
+1. **Extract into `app-manifest.json`** — call the MCP tool `config_extract_strings` with `writeTo: "app-manifest.json"` (same logic as `gxdev extract-config` on the CLI). It scans `src/` for directives and store usage and merges new keys into the manifest, linter-guarded.
+2. **Add a form field in `configuration.json` for every manifest entry**, using the MCP `config_*` tools. Default mapping:
+   - `strings.default.*` → `text` (or `textarea` for long copy)
+   - `assets.*` (driven by `gxp-src`) → `selectAsset`
+   - Each declared dependency identifier → `asyncSelect` bound to the matching resource list endpoint so the admin picks a real record
+   - Color settings → `colorPicker`; numeric thresholds → `number`; feature toggles → `boolean`
+   - Anything else → enumerate with `config_list_field_types` / `config_get_field_schema`
+     Each field's `name` must exactly match the manifest key it controls.
+3. **Lint** — `gxdev lint --all`. Fix every error before moving on.
+
+### 6. Test broadcasts
+
+- `gxdev socket list` — see available events.
+- `gxdev socket send --event <EventName>` — fire a test broadcast.
+- `test_api_route` MCP tool — hit endpoints against the local mock.
+- `test_scaffold_component_test` MCP tool — generate Vitest files.
+
+### 7. Final lint
+
+```bash
+gxdev lint --all
+```
+
+Run again after testing and fix every error before declaring done.
+
 ## Architecture
 
 The plugin runs inside a container provided by the `gxdev` server. Only edit files in `src/`:
@@ -9,24 +76,71 @@ The plugin runs inside a container provided by the `gxdev` server. Only edit fil
 - `src/Plugin.vue` - Main entry point
 - `src/components/` - Reusable components
 - `src/views/` - Page components
-- `app-manifest.json` - Configuration (strings, assets, settings)
+- `app-manifest.json` - Strings, assets, settings, dependencies (hot-reloaded)
+- `configuration.json` - Admin-facing configuration form (cards + fields)
 
-## Critical Rule: Use GxP Store for API Calls
+## Critical Rule: Use `store.callApi` for All Platform Calls
 
-NEVER use axios or fetch directly. Always use the store's API methods:
+Every call to the GxP platform goes through `store.callApi(operationId, identifier, data)`. It handles auth, URL resolution, team/project scoping, and path-parameter substitution.
 
 ```javascript
 import { useGxpStore } from "@gx-runtime/stores/gxpPortalConfigStore"
 const store = useGxpStore()
 
-// API methods (handles auth, CORS, base URL automatically)
-await store.apiGet("/api/v1/endpoint", { params })
-await store.apiPost("/api/v1/endpoint", data)
-await store.apiPut("/api/v1/endpoint/id", data)
-await store.apiPatch("/api/v1/endpoint/id", data)
-await store.apiDelete("/api/v1/endpoint/id")
+await store.callApi(operationId, identifier, data)
+```
+
+- **`operationId`** — OpenAPI operationId. Look it up with `api_list_operation_ids` or `search_api_endpoints` (MCP). Do not invent one.
+- **`identifier`** — a permission identifier declared in `app-manifest.json` → `dependencies` / `permissions`. It scopes the call to the resource the admin has bound to that identifier, and supplies the parent ID for path substitution.
+- **`data`** — body fields, query params, or path params not supplied by the identifier. `"pluginVars.someKey"` pulls a value from settings at call time.
+
+### Permission identifier pattern
+
+Declare identifiers by the **role** a resource plays, not its name. Example — a plugin that reads posts from one social stream and creates posts on another:
+
+```json
+// app-manifest.json
+{
+	"dependencies": [
+		{ "identifier": "social_stream_one", "model": "SocialStream" },
+		{ "identifier": "social_stream_two", "model": "SocialStream" }
+	],
+	"permissions": [
+		{ "identifier": "social_stream_one", "description": "Source — read posts" },
+		{
+			"identifier": "social_stream_two",
+			"description": "Destination — create posts"
+		}
+	]
+}
 ```
 
+```javascript
+const posts = await store.callApi("posts.index", "social_stream_one")
+await store.callApi("posts.store", "social_stream_two", {
+	body: "Hello world",
+})
+```
+
+### The `"project"` identifier
+
+For project-wide operations (creating the parent resource itself, or any top-level call not scoped to a dependency) use the reserved identifier `"project"`. You must pass any required IDs in `data`:
+
+```javascript
+const stream = await store.callApi("social_streams.store", "project", {
+	name: "New Stream",
+})
+
+await store.callApi("posts.store", "project", {
+	socialStreamId: stream.id,
+	body: "First post",
+})
+```
+
+### Low-level methods
+
+`store.apiGet` / `apiPost` / `apiPut` / `apiPatch` / `apiDelete` bypass the permission model. Avoid unless you have a specific reason. Never use axios or fetch directly.
+
 ## Store Data Access
 
 ```javascript
@@ -43,20 +157,54 @@ store.updateAsset("key", "url")
 store.updateState("key", "value")
 ```
 
-## WebSocket Events
+## Real-Time Events
+
+Two streams, both through the store:
+
+1. **`primary` channel** — peer pub/sub between users of this plugin.
+2. **Platform API events** — AsyncAPI events from `${apiDocsBaseUrl}/api-specs/asyncapi.json` (`components.messages`). Each message may declare `x-triggered-by` pointing at an OpenAPI operationId.
+
+### `primary` channel
+
+```javascript
+store.listen("primary", "custom_event", (data) => {
+	/* ... */
+})
+store.broadcast("primary", "custom_event", { hello: "world" })
+```
+
+### Platform API events
 
 ```javascript
-// Listen for events
-store.listenSocket("primary", "EventName", (data) => {
-	console.log("Event received:", data)
+// Event name first, permission identifier second, callback third
+store.listen("SocialStreamPostCreated", "social_stream_two", (post) => {
+	// fires whenever the admin-bound social_stream_two receives a new post
 })
+```
+
+The permission identifier is the same one you use in `callApi` — it scopes the subscription to the admin-bound resource. Use `"project"` for project-wide events.
+
+### Replace polling with events
+
+Whenever you add a `callApi` call, check whether its operationId triggers a socket event using MCP tools:
 
-// Emit events
-store.emitSocket("primary", "event-name", data)
+- `api_find_events_for_operation { operationId: "posts.store" }` — returns events whose `x-triggered-by` matches.
+- `api_list_events` — list all events; optional `triggeredBy` filter.
+- `search_websocket_events` — keyword search.
+
+If a match exists, subscribe instead of polling.
+
+### Testing broadcasts
+
+```bash
+gxdev socket list
+gxdev socket send --event EventName
 ```
 
 ## Vue Directives
 
+Every admin-editable piece of content goes through a directive — that's the bridge between the component and the admin form.
+
 ```html
 <!-- Dynamic text from strings -->
 <h1 gxp-string="welcome_title">Default</h1>
@@ -65,16 +213,30 @@ store.emitSocket("primary", "event-name", data)
 <img gxp-src="hero_image" src="/placeholder.jpg" />
 ```
 
+## Admin Configuration Form
+
+`configuration.json` defines the form admins use to customize the plugin. The workflow — run it whenever you touch a `callApi`, `listen`, `gxp-string`, or `gxp-src`:
+
+1. **Sync the manifest** — `config_extract_strings` with `writeTo: "app-manifest.json"` (same as `gxdev extract-config`). Scans `src/` and merges directives, store getters, and dependency identifiers into the manifest, linter-guarded.
+2. **Add a form field for every manifest entry** via the MCP `config_*` tools. Default mapping:
+   - `strings.default.*` → `text` / `textarea`
+   - `assets.*` → `selectAsset`
+   - Each `dependencies[]` identifier → `asyncSelect` bound to the resource's list endpoint
+   - Colors → `colorPicker`; numbers/thresholds → `number`; toggles → `boolean`
+   - Anything else → `config_list_field_types` / `config_get_field_schema`
+     Field `name` must match the manifest key it controls.
+3. **Validate** — `config_validate`, then `gxdev lint --all`.
+
+Tools: `config_list_card_types`, `config_list_field_types`, `config_get_field_schema`, `config_add_card`, `config_add_field`, `config_move_field`, `config_remove_field`, `config_validate`, `config_extract_strings`. Every mutation is linter-guarded against schemas in `bin/lib/lint/schemas/`.
+
 ## Component Kit
 
 Use `@gramercytech/gx-componentkit` for UI:
 GxButton, GxCard, GxInput, GxModal, GxSpinner, GxAlert, GxBadge, GxProgress, GxTabs
 
-## Configuration
-
-Edit `app-manifest.json` for strings, assets, settings. Hot-reloads in dev.
-
 ## API Specs
 
+Prefer the MCP tools over direct fetches:
+
 - OpenAPI: https://api.zenith-develop.env.eventfinity.app/api-specs/openapi.json
 - AsyncAPI: https://api.zenith-develop.env.eventfinity.app/api-specs/asyncapi.json