---
name: plungeai-platform
description: "THE PlungeAI (Ocean) platform capability map: a growing live registry of agents and structured tools, CNL multi-agent workflows, bounded harness missions, injectable skills/plugins/experts/personas, model routing with an OpenAI-compatible inference API, cron scheduling, per-user long-term memory, and full run observability — how the five layers fit together and which capability skill covers which job. Use when the user asks \"what can PlungeAI do\", \"which PlungeAI capability/agent/tool for X\", wants an end-to-end mental model of the platform, hits a trust fence (`403 refused` / `needs_approval` / `409`) and needs the doctrine, or is planning multi-step work and needs to pick between a single agent call, a CNL workflow, and a harness mission. For which door (MCP/REST/CLI/Studio) to use, load `choose-your-plungeai-door` first; each capability's own deep-dive skill (named below) covers its exact tools/params."
---

# PlungeAI Platform

PlungeAI (internally "Ocean") is a Cloudflare-native agent runtime: every agent, tool,
and workflow runs as a deployed edge service, connected by RPC. You do not install or
host anything — you operate the live platform through one of four doors (MCP, One API,
Ocean CLI, Ocean Studio — see `choose-your-plungeai-door`) and compose its capabilities.
There is no local mode: everything you execute runs on the deployed platform, and
everything you read (catalogs, contracts, results) is live.

The platform is **discovery-first by design**: the agent catalog, tool contracts,
model list, and workflow inventory change without notice. Never assert what exists
from memory — look it up (see "Discovery first" below). "90+ agents and growing" is
flavor; the live catalog is the fact.

## Connect

MCP (Claude Code shown; other clients use the equivalent `mcpServers` JSON —
install page: `https://mcp.plungeai.com/install`; full setup: `plungeai-mcp-setup`):

```bash
claude mcp add --transport http plungeai https://mcp.plungeai.com/v1 \
  --header "Authorization: Bearer ozk_YOUR_KEY"
```

One API (same `ozk_` key, `Authorization: Bearer` or `X-API-Key`; full setup:
`plungeai-api-setup`):

```bash
curl -s https://api.plungeai.com/v1/agents?limit=3 \
  -H "Authorization: Bearer ozk_YOUR_KEY"
```

Keys are self-service `ozk_` keys from **Dashboard → One API → Keys**
(`https://dashboard.plungeai.com`). `ozk_` keys authenticate the execution
planes; the model-inference money plane (`/v1/chat/completions`,
`/v1/embeddings`, `/v1/models`) uses `sk-ocean-` keys instead — see
`plungeai-models`. Rate limits by tier: free 30/min, pro 100/min (default),
enterprise 300/min (as of last sync — the tier table at
`GET https://api.plungeai.com/docs` is authoritative; `plungeai_whoami` shows your
live window). A plain-text platform summary for any LLM lives at
`https://mcp.plungeai.com/llms.txt`.

## Verify

Before doing real work, prove the connection and identity once:

- **MCP:** call `plungeai_whoami` — returns the identity card: user id, tier, key
  label, rate-limit window. If it fails, the key or transport is wrong; fix that
  before anything else.
- **One API:** `curl -s https://api.plungeai.com/health` (no auth) proves the router
  is up; an authenticated `GET /v1/agents?limit=1` proves the key.

## How the platform fits together

Five layers, bottom to top — useful when deciding where a problem lives:

| Layer | What it does | You touch it via |
|---|---|---|
| **Runtime** | Agents execute; providers serve models; memory stores state. Every agent is a deployed edge service with one uniform task interface | `plungeai-agents`, `plungeai-tools-connectors`, `plungeai-models`, `plungeai-memory` |
| **Orchestration** | The CNL engine runs workflows as DAGs of agent calls (parallel/sequential/…); the scheduler fires them on cron | `plungeai-workflows`, `plungeai-scheduling` |
| **Harness** | Mission-bounded autonomous runs: tool fence, iteration cap, recursion guard, memory recall | `plungeai-missions` |
| **Capability injection** | Skills, plugins, experts, personas, backgrounds, MCP servers injected per run into one loop agent | `plungeai-skills-plugins` |
| **Product** | Ocean Studio (build), dashboards (operate), branded runner apps (use) | Studio, for humans |

Two properties fall out of this architecture and explain most behavior you will
observe: internal calls are RPC between deployed Workers (which is why parallel
fan-out is essentially free — see `plungeai-workflows`), and every result is stored under
`(workflow_id, task_id)` (which is why every execution returns redeemable pointers —
see `plungeai-memory`).

## Capability map

One skill per capability. This table is the router — load the skill before
working in that area.

| Capability | What it gives you | Skill |
|---|---|---|
| **Discovery** | Find agents/tools/models/skills/connectors/templates on the live registry — never from memory | `plungeai-discovery` |
| **Agents** | Registry of building-block agents (search, LLM, documents, finance, social, …) — discover and execute one | `plungeai-agents` |
| **Tools & connectors** | Structured tool-agents with typed contracts (JSON Schema params, operations, approval gates, connected accounts) | `plungeai-tools-connectors` |
| **Workflows** | CNL YAML multi-agent orchestration: parallel/sequential/batch/debate/… pipelines | `plungeai-workflows` |
| **Models** | Provider factory inside runs + OpenAI-compatible inference API with routing/fallback | `plungeai-models` |
| **Skills / Plugins / Experts / Personas** | Injectable instruction packs, Claude-Code-format plugin bundles, voice/domain expertise, standing context | `plungeai-skills-plugins` |
| **Missions** | Bounded autonomous agent runs: goal, tool fence, iteration cap, success criteria | `plungeai-missions` |
| **Scheduling** | Cron jobs that run workflows/agents/missions unattended | `plungeai-scheduling` |
| **Campaigns** | Ledgered, claim-based batch work across many rows (the data-table campaign primitive) | `plungeai-campaigns` |
| **Memory** | Run-data exchange (SharedMemory) + per-user long-term memory | `plungeai-memory` |
| **Results & traces** | Live SSE events, execution history, persisted traces, cost | `plungeai-results-traces` |
| **Chat** | Persistent platform chat with sessions (`plungeai_chat` — send/new/list_sessions/history); conversations appear in Studio and the CLI | `plungeai-mcp-setup` |

## Which capability for which job

- **One-shot capability call** ("search the web", "convert this PDF"): a single
  agent. Prompt-driven → `plungeai_execute_agent`; structured (has a
  parameters table) → `plungeai_get_tool_contract` then `plungeai_execute_tool`.
  → `plungeai-agents`, `plungeai-tools-connectors`
- **Multi-step pipeline with known steps** ("research A, B, C in parallel, then
  synthesize"): a CNL workflow. → `plungeai-workflows`
- **Open-ended goal needing judgment** ("investigate X and produce a memo, use
  whatever tools you need"): ONE harness mission, not many small tasks. → `plungeai-missions`
- **Behavior/knowledge an agent should carry into a run** (style guide, domain
  method, company context): skills, plugins, experts, personas, backgrounds. →
  `plungeai-skills-plugins`
- **Raw LLM inference in your own code** (chat/embeddings, model fallback):
  the One API money plane. → `plungeai-models`
- **"Every morning / every hour" anything**: schedule it. → `plungeai-scheduling`
- **Batch work over many rows with claims/leases** (a "campaign"): →
  `plungeai-campaigns`
- **"Remember this" / "what did we learn last run"**: long-term memory. → `plungeai-memory`
- **"Why did that run fail / how long / what did it cost"**: observability. →
  `plungeai-results-traces`

## Discovery first (non-negotiable)

Catalogs are live and execution refuses stale ids. Always:

1. **Agents:** `plungeai_list_agents {search: "<capability in plain words>"}` — a
   hybrid semantic + keyword search; describe the job, trust the ranking. REST:
   `GET /v1/agents`, `GET /v1/discovery/search?q=…`. Take ids verbatim (kebab-case,
   e.g. `brave-agent`, `exa-agent`) from results only.
2. **Injectable capability ids** (skills, experts, personas, models, workflows,
   connectors): the same tool with a `kind` filter —
   `plungeai_list_agents {kind: "skills" | "experts" | "personas" | "models" |
   "workflows" | "connectors", search: "…"}`. REST: `GET /v1/discovery/search?kind=…`.
   A typo'd injectable id silently degrades to a warning
   (`plungeai-skills-plugins`) — look ids up before declaring them.
3. **Tool shapes:** `plungeai_get_tool_contract {agent_id}` or `GET /v1/tools/{id}`
   before the first call to an unfamiliar structured agent — the contract IS the docs.
4. **Routes:** `GET /v1/openapi.json` — never invent One API paths.
5. **Models:** `GET /v1/models` — the priced catalog routing draws from (this one
   endpoint takes an `sk-ocean-` key, not `ozk_` — see `plungeai-models`).
6. **The user's own inventory:** `plungeai_list_workflows` (in user parlance,
   "my agents" means their saved workflows — not the registry).

Full discovery mechanics (search params, cards, contracts, templates) — `plungeai-discovery`.

## Trust fences and structured outcomes

The platform answers with structured outcomes, never raw errors. Respect them:

- **Over MCP the outcome is an envelope, not an HTTP error**: every tool answers
  HTTP 200 with a status of `ok`, `needs_input`, `needs_connection`,
  `needs_api_key`, `needs_approval`, `unavailable`, or `error` (there is no
  `refused` MCP status — fences spell as HTTP codes only on the One API).
- **`403 refused`** (One API): a fence blocked the call — gated or money operation
  attempted unattended. Surface it to the user. **Never retry**; a fence is a
  policy, not a flake.
- **`409 approval_required`** / **`needs_approval` outcome + a paused run
  (`⏸ AWAITING USER APPROVAL`)**: a human must decide. Relay the approval block
  verbatim, wait for the user's explicit answer, then `plungeai_continue`
  (`approve: true` ONLY after they said yes; their refusal or change of course goes
  in `message`). Never approve on your own.
- **`needs_input`** (or `422 invalid_params`): the response names the missing/invalid
  fields and carries the schema — fix exactly those, then retry once.
- **`needs_connection` / `needs_api_key`**: the acting user must connect a credential
  in the platform apps (Studio). Tell them exactly what to connect; retry after.
- **`unavailable`**: the outcome lists live alternatives — pick one or re-discover.

Same doctrine everywhere: follow the remediation in the outcome; never blind-retry
the identical call.

## A complete first session (MCP)

The canonical shape of operating the platform, end to end — adapt the middle to the
job:

```
1. plungeai_whoami
   → identity card (proves key, tier, rate window)

2. plungeai_list_agents {search: "web search",
     user_request: "research solid-state battery commercialization for me"}
   → ranked cards; pick e.g. brave-agent, exa-agent (ids verbatim)

3. plungeai_execute_workflow {
     user_request: "research solid-state battery commercialization for me",
     workflow_yaml: "
     name: quick research
     tasks:
       - type: parallel
         id: research
         subtasks:
           - { type: task, id: a, agent: brave-agent, query: \"{input}\" }
           - { type: task, id: b, agent: exa-agent,   query: \"{input}\" }
       - type: task
         id: brief
         agent: llm-agent
         prompt: \"Write a sourced brief on: {input}\"
   ", input: "solid-state battery commercialization"}
   → result (final markdown — relay verbatim)
   For >3 min jobs: mode: "async" → plungeai_get_workflow_status → plungeai_get_result

4. Output is right → plungeai_workflow {action: "create", name, yaml, description}
   → saved, synced live to Studio and peer apps

5. plungeai_schedule {action: "create", job_type: "workflow",
     target: "<saved id>", schedule: "0 7 * * *"}
   → runs every morning; verify once with {action: "run_now"}
```

Steps 2-3 change per job (single agent call, tool contract + typed execution, or a
harness mission via `plungeai_run_mission`) — the frame (verify → discover → test →
save → schedule) does not.

## Operating rules

- **Every `plungeai_*` call also takes `user_request`** — pass the user's ask
  verbatim, in their own words (the platform uses it for routing and support
  diagnostics; arguments alone lose the intent).
- **Agent ids only from a live search.** Unknown or inactive ids are refused at
  execution time.
- **Async for long runs.** Anything over ~3 minutes: `mode: "async"` (on
  `plungeai_execute_workflow` / `plungeai_execute_tool` / `plungeai_run_mission` —
  `plungeai_execute_agent` has none; wrap it in a one-task workflow) → poll
  `plungeai_get_workflow_status` → fetch with `plungeai_get_result` when completed.
- **Results are final, user-ready markdown.** Present them verbatim and in full —
  do not re-format, shorten, or re-type them as your own prose.
- **Test before saving.** Run ad-hoc (`plungeai_execute_workflow {workflow_yaml}`)
  and read the actual output before `plungeai_workflow {action: "create"}`.
- **Idempotency:** payment-, messaging-, and automation-class agents may duplicate
  side effects on re-runs. Do not re-fire a call that may already have acted;
  check execution status first.

## Common pitfalls

| Pitfall | Reality |
|---|---|
| Using an agent id from memory or an old example | Catalog is live, active-only; execution refuses stale ids. Search first, always |
| "Show me my agents" answered with the registry | Users mean their saved workflows → `plungeai_list_workflows` |
| Prose prompt sent to a structured tool-agent | Cards with a Parameters table take typed `params` via the contract door (`plungeai-tools-connectors`) |
| Retrying a `403`/`refused` or self-approving a `409`/`⏸` | Fences are policy. Surface, get the human decision, `plungeai_continue` |
| Decomposing an open-ended goal into many guessed tasks | One `type: harness` mission with a fence beats a brittle guessed pipeline (`plungeai-missions`) |
| Summarizing platform output "helpfully" | Outputs are final user-ready markdown — relay verbatim and in full |
| Blocking on a long sync call | `mode: "async"` + status polling exists for exactly this |
| Baking dates into scheduled workflows | Date tokens (`{week_start}`, …) roll automatically (`plungeai-scheduling`) |
| Storing context as long-term memory that belongs in a background/skill | Memory is learned per-user state; authored shared context goes in backgrounds/skills (`plungeai-memory`) |
| Inventing One API routes or model names in generated code | `GET /v1/openapi.json` and `GET /v1/models` are the only authorities |

## Related skills

- `choose-your-plungeai-door` — which door (MCP/REST/CLI/Studio) for which job.
- `plungeai-mcp-setup` / `plungeai-api-setup` / `plungeai-cli-setup` — connect and verify a client.
- Every capability in the map above has its own deep-dive skill by the same name.
- `plungeai-in-<tool>` — wiring a specific coding tool's agent to PlungeAI over MCP.