# Design AI Assistant Admin

> Manage AI assistant configurations and peer-to-peer mesh network connections in the NV oOS Pro Toolkit. Covers assistant creation, model configuration, provider setup, peer discovery, mesh networking, cross-assistant communication, and detecting from a coding-agent session (Zed) which NV oOS assistants / MCP servers are enabled. Use when creating or editing AI assistants, configuring model providers, setting up peer connections, managing mesh network topology, debugging assistant behavior, or answering "is agent X available" / "what tools does this MCP have".

- Skill: `nvdigitalsolutions/design-ai-assistant-admin` (Agent Skill)
- Install (CLI): `npx get-skill add nvdigitalsolutions/design-ai-assistant-admin`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nvdigitalsolutions/design-ai-assistant-admin/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: Proprietary. See LICENSE.txt
- Author: nvdigitalsolutions (https://skillmd.com/u/nvdigitalsolutions)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/nvdigitalsolutions/design-ai-assistant-admin

---


# NV oOS AI Assistant Administration

> **Accuracy note (2026-09-15):** this skill was rewritten after a live
> verification pass against plugin v1.1.79 (`includes/assistants/`,
> `includes/cli/`, `includes/rest/`) and the Design Stack deployment. Every
> meta key, command, and route below is code-verified. The previous version
> of this skill documented `_assistant_*` / `_peer_*` meta keys that the
> plugin has never stored — do not use them.

## When to use this skill

Trigger when ANY of the following is true:

- Creating, editing, or deleting AI assistant configurations.
- Changing an assistant's model provider (OpenAI, Gemini, Anthropic, Ollama, etc.).
- Configuring an assistant's system prompt, temperature, or tool access.
- Setting up or removing peer-to-peer federation records between WordPress sites.
- Listing all assistants with their current model, provider, and status.
- Querying which tools are enabled for a specific assistant.
- Debugging assistant behavior — checking configuration, tool access, or peer routing.
- Checking whether a specific NV oOS assistant / MCP server ("kate agent", "ECA agent", …) is enabled in the current editor session.
- Answering "is agent X available?" / "what tools does this MCP expose?" from inside a coding-agent session.
- Managing assistant-specific vector store or memory settings.
- Cloning an assistant configuration for testing or staging environments.

## Mental model

Two CPT-backed entity types, plus a small set of verified interfaces:

```
AI ASSISTANT  (CPT: mcp_ai_assistant)         AI PEER  (CPT: ai_peer)
├── title / post_status                        ├── title
├── _wp_mcp_ai_provider                        ├── _wp_mcp_ai_peer_mcp_url
├── _wp_mcp_ai_model                           ├── _wp_mcp_ai_peer_capabilities
├── _wp_mcp_ai_system_prompt                   ├── _wp_mcp_ai_peer_health_status
├── _wp_mcp_ai_tools (serialized slug array)   ├── _wp_mcp_ai_peer_last_verified
├── _wp_mcp_ai_credentials (hashed tokens)     ├── _wp_mcp_ai_peer_site_url
└── mcp_ai_required_capability                 └── … (see peer meta table)

INTERFACES (in order of reliability):
1. WP-CLI   wp mcp-ai assistant|credential|tool|provider|chat|health|log …
2. REST     https://<site>/wp-json/mcp-ai/v1/chat  +  /mcp (JSON-RPC)  +  /tools
3. Admin UI assistant CPT editor + federation pages
4. toolkit_cpt MCP tool — Pro-only, not guaranteed to be exposed
```

**Relationships:**

- An **AI Assistant** (`mcp_ai_assistant`) is one row per assistant persona.
  Model, provider, prompt, temperature, and the assigned tool-slug array all
  live in `_wp_mcp_ai_*` post meta (plus `mcp_ai_required_capability`).
- An **AI Peer** (`ai_peer`) is a federation-directory record pointing at a
  remote MCP server: MCP/OpenAPI URLs, JWKS URI, capabilities, quotas, and a
  health status that is refreshed by verification runs. Peers only render in
  the admin federation page when `enable_federation_directory` is on.
- **`toolkit_cpt`** (`WP_MCP_AI_Pro_Tool_CPT`,
  `addons/pro/includes/tools/infrastructure/class-wp-mcp-ai-pro-tool-cpt.php`)
  is the generic CPT CRUD MCP tool (group `wordpress-core`, `pro` capability
  flag). It is NOT the single interface: it may be absent from a given
  deployment's `tools/list`. Always verify it exists before scripting against
  it; WP-CLI and the REST routes are the always-available paths.

## WP-CLI command surface (verified against includes/cli/)

| Command | Purpose |
|---|---|
| `wp mcp-ai assistant list [--status=any\|publish\|draft\|trash] [--format]` | List assistants (title, status, legacy model column — see quirk below) |
| `wp mcp-ai assistant get <id> [--format=json]` | Post-level details; only shows `mcp_ai_*`-prefixed meta (quirk below) |
| `wp mcp-ai assistant create --title=<t> [--status=publish] [--model] [--system-prompt] [--porcelain]` | Create assistant; `--porcelain` prints the new ID |
| `wp mcp-ai assistant update <id> [--title] [--status] [--model] [--system-prompt]` | Update assistant |
| `wp mcp-ai assistant delete <id> [--force] [--yes]` | Trash or permanently delete |
| `wp mcp-ai assistant export <id> [--file=<name.json>]` | Export config JSON (stdout or uploads/mcp-ai/exports/) |
| `wp mcp-ai assistant import [--file=<name.json> \| --stdin] [--porcelain]` | Import from exports dir or stdin |
| `wp mcp-ai credential list [<assistant-id>] [--format]` | List issued credentials |
| `wp mcp-ai credential issue <assistant-id> [--user=<id>] [--porcelain]` | Issue token; `--porcelain` prints `cred_xxxxx.SECRET` once |
| `wp mcp-ai credential revoke <assistant-id> <credential-id> [--yes]` | Revoke a token |
| `wp mcp-ai tool list [--status=enabled\|disabled] [--format=ids]` | **Discover assignable tool slugs** (registry + enabled state) |
| `wp mcp-ai tool enable <slug>` / `wp mcp-ai tool disable <slug> [--yes]` | Toggle global tool availability |
| `wp mcp-ai provider list` / `provider test <slug>` / `provider models <slug>` | Provider config status, connectivity test, model list |
| `wp mcp-ai chat "<message>" [--assistant=<id>] [--model] [--provider] [--stream] [--format=json]` | One-shot chat via the model router |
| `wp mcp-ai health` / `wp mcp-ai log` / `wp mcp-ai cache clear` / `wp mcp-ai version` | Diagnostics |
| `wp mcp-ai toolkit list \| enable <key> \| disable <key>` (Pro) | Pro toolkit settings keys (`enable_crm_toolkit`, …) — **not** assistant CRUD |

There is **no** `wp mcp-ai peer` command — peer records are edited via post
meta or the admin UI. (Older versions of this skill claimed `peer list` /
`peer test`; those commands do not exist in v1.1.79.)

### CLI quirks you will hit (code-verified)

- `assistant create|update --model=…` and `--system-prompt=…` write legacy
  `mcp_ai_model` / `mcp_ai_system_prompt` meta keys. The chat runtime reads
  `_wp_mcp_ai_model` / `_wp_mcp_ai_system_prompt`, so those flags currently
  have **no runtime effect** — set the `_wp_mcp_ai_*` keys explicitly.
- `assistant list` reads `mcp_ai_model` (usually empty) and `assistant get`
  only collects meta keys starting with `mcp_ai_`, which misses every
  `_wp_mcp_ai_*` key. Inspect real config with `wp post meta get` instead.
- `wp mcp-ai provider list` and `wp mcp-ai chat` fatal on builds before the
  CLI fix in #6625 (see Known Issues).

## Verified meta keys

### `mcp_ai_assistant`

Constants in `includes/assistants/class-wp-mcp-ai-assistant-cpt.php`:

| Key | Type | Purpose |
|---|---|---|
| `_wp_mcp_ai_provider` | string | Provider slug (`openai`, `gemini`, `anthropic`, `deepseek`, `ollama`, …) |
| `_wp_mcp_ai_model` | string | Model identifier (`gpt-4o-mini`, `gemini-2.5-flash`, …) |
| `_wp_mcp_ai_temperature` | float | Sampling temperature |
| `_wp_mcp_ai_system_prompt` | string | Persona / system prompt |
| `_wp_mcp_ai_tools` | array (serialized) | Assigned tool slugs — must be a real PHP array |
| `_wp_mcp_ai_credentials` | array | Issued credentials (hashed). Never hand-edit |
| `_wp_mcp_ai_classification` | string | Information label; defaults to `internal` |
| `mcp_ai_required_capability` | string | Capability gate for tool calls — **no `_wp_` prefix** (`manage_options`, `edit_posts`) |
| `_wp_mcp_ai_vector_store_id` | string | OpenAI vector store for RAG |
| `_wp_mcp_ai_memory_files` | array | Memory file attachment IDs |
| `_wp_mcp_ai_corpus_name` | string | Corpus name for knowledge routing |
| `_wp_mcp_ai_tool_shortcuts` | array | Tool shortcut definitions |
| `_wp_mcp_ai_harness_profile` | array (JSON) | Agent-harness profile (memory summary etc.) |

### `ai_peer`

Constants in `includes/class-wp-mcp-ai-ai-peer-cpt.php`:

| Key | Type | Purpose |
|---|---|---|
| `_wp_mcp_ai_peer_mcp_url` | string | Remote MCP endpoint URL |
| `_wp_mcp_ai_peer_openapi_url` | string | Remote OpenAPI spec URL |
| `_wp_mcp_ai_peer_jwks_uri` | string | JWKS URI for token verification |
| `_wp_mcp_ai_peer_capabilities` | mixed | Advertised capabilities |
| `_wp_mcp_ai_peer_regions` | mixed | Serving regions |
| `_wp_mcp_ai_peer_data_tags` / `_wp_mcp_ai_peer_policy_tags` | mixed | Data / policy tags |
| `_wp_mcp_ai_peer_quotas` / `_wp_mcp_ai_peer_price_hints` | mixed | Quota and pricing metadata |
| `_wp_mcp_ai_peer_health_status` | string | Health state (`healthy`, …) |
| `_wp_mcp_ai_peer_latency_p50` | mixed | p50 latency |
| `_wp_mcp_ai_peer_last_verified` | string | Last verification timestamp |
| `_wp_mcp_ai_peer_last_error` | string | Last verification error |
| `_wp_mcp_ai_peer_site_name` / `_wp_mcp_ai_peer_site_url` | string | Remote site identity |
| `_wp_mcp_ai_peer_wellknown_url` | string | `/.well-known/` discovery URL |
| `_wp_mcp_ai_peer_verification_data` | mixed | Verification payload |

## Verified provisioning recipe (Design Stack)

This is the end-to-end path that actually works on the Design Stack deployment:

```bash
# 0. In the Design Stack WP container, wp requires --allow-root.
#    (In this repo's own compose: docker compose run --rm wp-cli …)

# 1. Discover assignable slugs before assigning.
wp mcp-ai tool list                  # base registry: slug + enabled + capability
wp mcp-ai toolkit list               # Pro toolkit settings keys

# 2. Create the record.
wp mcp-ai assistant create --title="Brand Assistant" --status=publish --porcelain
# → prints the new assistant ID (call it <id>)

# 3. Set runtime meta. The CLI's --model/--system-prompt write legacy keys the
#    runtime ignores — set the _wp_mcp_ai_* keys explicitly:
wp post meta update <id> _wp_mcp_ai_provider openai
wp post meta update <id> _wp_mcp_ai_model gpt-4o-mini
wp post meta update <id> _wp_mcp_ai_temperature 0.7
wp post meta update <id> _wp_mcp_ai_system_prompt "$(cat assistant-system-prompt.md)"
wp post meta update <id> _wp_mcp_ai_classification internal
wp post meta update <id> mcp_ai_required_capability manage_options

# Tools is a serialized PHP array. wp post meta update would store a string,
# which breaks tool resolution — use wp eval for that one key:
wp eval 'update_post_meta(<id>, "_wp_mcp_ai_tools", array("web_search", "deep_research", "create_post"));'

# 4. Issue the credential (prints cred_xxxxx.SECRET exactly once).
wp mcp-ai credential issue <id> --porcelain
```

## Verification checklist (what actually works)

1. **MCP JSON-RPC handshake** — `POST /wp-json/mcp-ai/v1/mcp` with
   `Authorization: Bearer <TOKEN>`:

   ```json
   {"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"zed","version":"1"}},"id":1}
   ```

   Then `tools/list` — expect exactly the slugs you assigned (empty list ⇒
   `_wp_mcp_ai_tools` was never set as an array).

2. **REST chat smoke test** (the reliable fallback when `wp mcp-ai chat` fatals):

   ```bash
   curl -s -X POST http://localhost:8092/wp-json/mcp-ai/v1/chat \
     -H "Authorization: Bearer <TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"assistant_id": <id>, "messages": [{"role":"user","content":"Reply with exactly: OK"}]}'
   ```

   `messages` is required; `assistant_id` is optional (int or string);
   optional `options` object accepts `provider`, `model`, `temperature`,
   `stream`, `response_format`.

3. **Inspect persisted config** — `wp post meta get <id> _wp_mcp_ai_provider`
   etc. Do not trust `wp mcp-ai assistant get` for meta (legacy-key caveat).

## Detecting NV oOS agent enablement from a coding-agent session (Zed)

> Added after a live Zed-session probe (2026-10). When a user asks "is agent
> X available?" or "what tools does this MCP have?", NV oOS assistants never
> appear under their server/assistant name — detect them by tool surface.

### The two registries (do not conflate them)

1. **Zed agent registry** — `list_agents_and_models`. Lists only native Zed
   sub-agents (e.g. `Zed Agent`) and their models. NV oOS assistants / MCP
   servers are **never** listed here, even when fully connected. Absence here
   proves nothing about the bridge.
2. **MCP tool servers** — appear only as *functions in your tool list*, under
   their tool names (e.g. `web_search_validated`, `list_ecas`), never under
   the server name (`nv-oos-kate-agent`, "ECA agent"). Map a name to its
   tools via the group signatures below.

"Agent" in user speech almost always means "MCP server / assistant bridge",
not a registry agent. Translate the question to "which tool group is live?"
before answering.

### Known tool-group signatures to look for

| Group | Signature tools | Notes |
|---|---|---|
| Research / web bridge | `web_search_validated`, `brave_web_search`, `brave_local_search`, `deep_research`, `semantic_content_search`, `verify_information`, `aggregate_research_data`, `extract_structured_data`, `generate_research_report`, `create_post_from_research` | 16 tools observed in one session; `web_search_validated` is the cheapest probe |
| Image bridge | `generate_gemini_image_validated`, `generate_openai_image_validated`, `edit_gemini_image_validated`, `edit_openai_image`, `create_image_variation`, `product_actualization` | Usually exposed alongside the research bridge |
| ECA (school extra-curriculars) | `list_ecas`, `get_eca`, `create_eca`, `update_eca`, `enroll_student_eca`, `withdraw_student_eca`, `mark_eca_attendance`, `manage_eca_waitlist`, `get_eca_timetable`, `send_eca_notification`, `generate_eca_analytics`, `list_students`, `get_student` | 26 tools observed; `list_ecas` is the cheapest probe |
| Design stack (may be absent) | `schedule_social_post`, `paper_store_*`, `remote_wp_connection`, `resize_image`, `remove_background` | Absence of one group does NOT mean the bridge is down — groups are exposed per assistant/session |

### Detection procedure (in order)

1. **Inventory your tool list** (the session function list) against the
   signatures above. Presence of any signature tool ⇒ that assistant's MCP
   is wired in.
2. **Probe with the cheapest read-only tool** of the suspected group — e.g.
   `web_search_validated` (`max_results: 2`) or `list_ecas` (defaults). A
   live bridge returns real structured data: records, `task_id`, `provider`,
   timestamps. An error or empty envelope means exposed-but-not-live.
3. **Re-probe, don't trust earlier checks.** MCP connections refresh
   mid-session. Observed: `list_available_toolsets` worked on one call and
   returned "No tool named … exists" minutes later while the underlying
   tools stayed live. `get_write_tools` (where present) enumerates a
   connected MCP's full mutating surface and doubles as a capability
   snapshot (Cloudways: 188 write tools).
4. **Report precisely.** Say "MCP server connected, verified live via
   `<tool>` (`<evidence>`)" — never claim an assistant is absent just
   because it is missing from `list_agents_and_models`.

### Verified example (2026-10, single session)

- `list_agents_and_models` ⇒ only `Zed Agent` (no `nv-oos-*` agents).
- `web_search_validated("…", 2)` ⇒ real Brave results + `task_id` ⇒ NV oOS
  research bridge (`nv-oos-kate-agent`) live.
- `list_ecas` ⇒ 75 live ECA records from `eca.directory` ⇒ ECA MCP live.
- Cloudways: `get_write_tools` ⇒ 188 write tools even after toolset-discovery
  tools disappeared ⇒ connection still live.

## Known issues (observed on Design Stack, 2026-09)

- **`wp mcp-ai provider list` and `wp mcp-ai chat` fatal** (PHP 8) on builds
  before the CLI fix: `format_output()` passed an inline array literal to
  `WP_CLI\Formatter`'s by-reference constructor, and `chat` constructed the
  model router with zero args. Fixed in #6625 (merged to alpha-working;
  ships after v1.1.79). Workarounds on older builds: provider config status
  → NV oOS settings page; provider connectivity →
  `wp mcp-ai provider test <slug>`; chat → the REST smoke test above.
- **`assistant create|update --model/--system-prompt`** write legacy keys the
  runtime does not read (see CLI quirks). Always set `_wp_mcp_ai_*` explicitly.
- **`--allow-root`** is required for `wp` inside the Design Stack WP container.
- **`toolkit_cpt` may be missing** from `tools/list` on a given deployment
  (Pro tool with a `pro` capability flag). Check availability before
  scripting against it; WP-CLI + REST are the fallback.

## Critical Rules

- `_wp_mcp_ai_tools` must be a **real PHP array** (serialized). Set it with
  `wp eval` / `update_post_meta()`, never `wp post meta update` (string).
- `mcp_ai_required_capability` has **no `_wp_` prefix** — unlike every other
  assistant key. Getting this wrong silently falls back to default gates.
- Credential tokens print **once** (`credential issue --porcelain`); never log
  them or commit them. Hashes live in `_wp_mcp_ai_credentials` — never edit.
- Provider/model slugs must match `wp mcp-ai provider list` and the model
  catalog; a mismatched pair fails at runtime, not at assignment time.
- Peer records are only meaningful when `enable_federation_directory` is on;
  health is maintained by verification runs, not by editing the post.
- Verify with the checklist above after every change — `assistant get` does
  not show you the runtime configuration.

## Common Mistakes

```
WRONG — assigning tools via wp post meta update
wp post meta update 42 _wp_mcp_ai_tools '["web_search", "deep_research"]'
// Stores a STRING. is_array() checks in tool resolution fail → tools/list [].
RIGHT — wp eval 'update_post_meta(42, "_wp_mcp_ai_tools", array("web_search", "deep_research"));'

WRONG — relying on assistant create --model to configure the runtime
wp mcp-ai assistant create --title="Bot" --model=gpt-4o
// Writes mcp_ai_model. The runtime reads _wp_mcp_ai_model → default model used.
RIGHT — create with --title/--status, then set _wp_mcp_ai_model via wp post meta update.

WRONG — trusting assistant get for configuration audits
wp mcp-ai assistant get 42
// Collects only mcp_ai_*-prefixed meta; misses _wp_mcp_ai_* keys entirely.
RIGHT — wp post meta get 42 _wp_mcp_ai_provider (one key at a time, or wp eval get_post_meta).

WRONG — exposing a credential in a Zed config file or chat log
// Tokens are bearer credentials; treat like API keys. Store via design-vault.
```

## Cross-References

- Run `mcp-ai-wpoos-plugin` for MCP bridge setup, JSON-RPC examples, and the
  WP-CLI provisioning recipe with the chat REST smoke test.
- Run `design-pro-workflow-builder` to create workflows that chain assistants.
- Run `design-pro-schedule-manager` to schedule recurring assistant health checks.
- Run `design-vault` to securely store credential tokens.
- Run `design-team-management` to assign assistants to teams or roles.
- Run `design-crm` if the assistant is used for CRM automation.
- Run `design-project-management` if the assistant manages projects or tasks.
- Run `wp-security-audit` on any assistant-facing endpoint — exposed
  assistants are attack surfaces.
- Run `wp-security-secrets` to audit credential handling.
- Run `design-elementor-mcp-connection` to connect Elementor MCP servers to
  an assistant via the MCP Apps metabox/slash-command (per-assistant remote
  MCP tool bridging) — this skill covers assistant config, not MCP app
  connections.

## What This Skill Does NOT Cover

- MCP bridge tool calling mechanics — use `mcp-ai-wpoos-plugin` for JSON-RPC.
- Chat UI configuration (shortcodes, Elementor widgets) — see the plugin's
  chat UI documentation.
- Provider API key management — NV oOS Settings page or `design-vault`.
- Vector store file upload and management — Files API tools.
- Agent memory system internals — `retrieve_agent_memory` / `store_agent_context`.
- Workflow builder orchestration — `design-pro-workflow-builder`.
- Peer wire protocol (SSE, message format) — this skill covers peer
  *configuration*, not the transport.
- Multi-site WordPress network administration — `remote_wp_connection`.
- MCP App connections to remote MCP servers (e.g. Elementor MCP) —
  `design-elementor-mcp-connection`.

## References

- Assistant CPT + meta constants: `includes/assistants/class-wp-mcp-ai-assistant-cpt.php`
- Peer CPT + meta constants: `includes/class-wp-mcp-ai-ai-peer-cpt.php`
- CLI commands: `includes/cli/class-wp-mcp-ai-cli-assistant-command.php`,
  `…-credential-command.php`, `…-tool-command.php`, `…-provider-command.php`,
  `…-chat-command.php`, `addons/pro/includes/cli/class-wp-mcp-ai-pro-cli-toolkit-command.php`
- `toolkit_cpt` MCP tool: `addons/pro/includes/tools/infrastructure/class-wp-mcp-ai-pro-tool-cpt.php`
- REST chat endpoint: `includes/rest/class-wp-mcp-ai-rest-chat-controller.php`
- REST namespace (`mcp-ai/v1`): `includes/class-wp-mcp-ai-rest.php`
- Credential store: `includes/class-wp-mcp-ai-credentials.php`

