@prowl-ai/prowl-skill 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## v0.5.0 — 2026-08-15
+
+Package `@prowl-ai/prowl-skill` 0.5.0 · plugins `prowl` 0.4.0, `prowl-cli` 0.2.0.
+
+Both skills were audited against the running server rather than against each
+other, and both were wrong in ways an agent acts on.
+
+### Fixed
+
+- **`prowl_analyze` takes `execution_mode`, not `tier`.** The `prowl` skill said
+  `tier`, and had said it for two releases. An unknown key is ignored, so an
+  agent following the skill sent `tier: "deep"`, got a **basic** run, was billed
+  as basic, and reported back as if it had run deep. The tiers table now names
+  the real parameter, for `prowl_start_session` and `prowl_schedule_create` too.
+
+- **The subscription gate was documented nowhere.** `deep` requires an Exploit+
+  subscription and `max` a Blackops+ one, and a key without it is **not
+  refused** — the run silently resolves to `basic` and bills as basic
+  (`mcp_server/models.effective_tier`). Both skills now state it where the tier
+  is chosen, and point at `prowl_get_wallet` / `prowl wallet` for checking
+  before the spend rather than inferring it from a thin report afterwards.
+
+- **`prowl_list_tools` no longer returns names by default.** The verify step
+  promised "448 tools grouped by category"; the server returns category counts
+  and gives names only for `names=true` or a single `category`. The step now
+  describes what actually comes back.
+
+### Added
+
+- **`prowl_get_wallet`** in the tool table, the billing section and the verify
+  steps. It is the only surface that can read a balance for a `prowl_` key:
+  `GET /api/v1/wallet` returns the same figures but decodes a JWT, and no REST
+  route on the server accepts an API key. The registered MCP tool count moves
+  22 → 23 with it.
+
+- **The `prowl-cli` skill was rewritten for the CLI it now documents.**
+  `@prowl-ai/cli` 0.2.0 covers all 21 logical MCP tools rather than six —
+  sessions, playbooks, schedules, artifacts, export, stats and the error feed —
+  so the command list, the long-run guidance (`session start --watch` for CI)
+  and the exit-code advice all changed. The old page documented `prowl wallet`
+  as working; it could not.
+
 ## v0.4.0 — 2026-08-13
 
 Package `@prowl-ai/prowl-skill` 0.4.0 · plugins `prowl` 0.3.0, `prowl-cli` 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prowl-ai/prowl-skill",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The Prowl plugin: install/usage skills, the hosted MCP config, and the live status widget that makes a running Prowl call, its progress and its cost visible in the terminal. This package is the installer CLI.",
   "keywords": [
     "prowl",

package/plugins/prowl/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "prowl",
   "description": "Prowl market-intelligence skill backed by the hosted Prowl MCP server (448 tools), with a status widget that makes a running call, its progress and its cost visible in the terminal.",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "author": {
     "name": "Prowl",
     "email": "support@prowl.chat",

package/plugins/prowl/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "prowl",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Prowl market-intelligence skill backed by the hosted Prowl MCP server (448 tools), with a status widget that makes a running call, its progress and its cost visible in the terminal.",
   "author": {
     "name": "Prowl",

package/plugins/prowl/skills/prowl/SKILL.md

@@ -5,13 +5,15 @@ license: MIT
 compatibility: Requires network access to prowl.chat and a Prowl API token; the bundled MCP config runs `npx mcp-remote` (needs Node.js 18+).
 metadata:
   author: prowl.chat
-  version: "0.3.0"
+  version: "0.4.0"
 ---
 
 # Prowl — market intelligence for your agent
 
 Prowl is a single MCP endpoint that exposes **448 market-intelligence API tools** across 15 providers (DataForSEO, SearchAPI, SerpApi, SpyFu, Majestic, Foreplay, Firecrawl, Exa, Perplexity, Gemini, …) plus the full Prowl pipeline — `prowl_analyze`, async research sessions, recurring schedules, artifacts and exports. Call real data instead of guessing.
 
+Prefer the sibling `prowl-cli` skill when the work belongs in a shell script or a CI job; use this one when the agent should call Prowl as MCP tools inside its own tool loop.
+
 - MCP URL: `https://prowl.chat/mcp`
 - Transport: Streamable HTTP
 - Auth header: `Authorization: Bearer prowl_<your_key>`
@@ -30,39 +32,54 @@ For manual per-client setup (Cursor `.cursor/mcp.json`, Claude Code `claude mcp
 
 ## Core tools
 
-22 MCP tools front the catalog. The ones that matter day to day:
+23 MCP tools front the catalog. The ones that matter day to day:
 
 | Tool | Purpose | Cost |
 |------|---------|------|
-| `prowl_list_tools` | Browse the 448 tools by category | free |
+| `prowl_list_tools` | Category **counts**; pass `category` or `names=true` for names | free |
 | `prowl_search_tools` | Semantic search over the catalog | free |
 | `prowl_tool_info` | JSON input schema + estimated cost for one tool | free |
 | `prowl_call_tool` | Invoke any single tool | metered |
-| `prowl_analyze` | Full multi-agent research report in one shot | metered, tier-capped |
+| `prowl_analyze` | Full multi-agent research report in one shot | metered, capped by `execution_mode` |
+| `prowl_get_wallet` | Balance + which `execution_mode`s this key can run | free |
 | `prowl_list_playbooks` | The 8 fixed, persona-tuned report shapes | free |
-| `prowl_start_session` / `prowl_session_status` / `prowl_get_session` | Async deep research: kick off, poll, read back | metered |
-| `prowl_generate_artifact` / `prowl_export_report` | Visuals, infographics, audio; Markdown/PDF/PPTX export | metered |
+| `prowl_start_session` / `prowl_session_status` / `prowl_get_session` / `prowl_list_sessions` | Async deep research: kick off, poll, read back | metered |
+| `prowl_generate_artifact` / `prowl_export_report` | Infographic, PDF, PPTX, audio, video; Markdown/HTML export | metered |
 | `prowl_schedule_create` / `_list` / `_pause` / `_resume` / `_cancel` | Recurring hunts | metered per run |
 | `prowl_get_stats` / `prowl_get_error_feed` / `prowl_reset_session` | Run accounting, failures, state reset | free |
 
 MCP tool args are **flat**, not nested.
 
-Recommended flow: `prowl_search_tools` → `prowl_tool_info` → `prowl_call_tool` for one fact; `prowl_analyze` for a complete strategy report. Pass a stable `session_id` across calls to keep the report cache and conversation memory scoped to one conversation.
+`prowl_list_tools` answers with category counts by default — the full name list
+costs about 4k tokens and is returned only for `names=true` or a single
+`category`. Reach for `prowl_search_tools` to find a tool by intent; it is the
+cheap path and ranks by relevance.
+
+Recommended flow: `prowl_search_tools` → `prowl_tool_info` → `prowl_call_tool` for one fact; `prowl_analyze` for a complete strategy report. Pass a stable `session_id` across calls to keep the report cache and conversation memory scoped to one conversation — `prowl_generate_artifact` and `prowl_export_report` read the report cached against that session, so they need a prior `prowl_analyze` on the same id.
 
 Full reference: [https://prowl.chat/mcp/skill.md](https://prowl.chat/mcp/skill.md)
 
 ## Tiers
 
-`prowl_analyze` and `prowl_start_session` take a `tier`, which sets the tool budget and the hard provider-cost cap for the run:
+`prowl_analyze`, `prowl_start_session` and `prowl_schedule_create` take
+**`execution_mode`** — not `tier`. The parameter sets the tool budget and the
+hard provider-cost cap for the run. An unknown key is ignored, so a call that
+sends `tier` runs at the default and reports back as if it had not.
 
-| Tier | Use for | Provider cost cap |
-|------|---------|------------------:|
-| `basic` | One question, fast turnaround | $2.50 |
-| `deep` | Full competitive report | $8.00 |
-| `max` | Exhaustive, research-grade | $18.00 |
+| `execution_mode` | Use for | Provider cost cap | Requires |
+|------|---------|------------------:|----------|
+| `basic` | One question, fast turnaround | $2.50 | — |
+| `deep` | Full competitive report | $8.00 | Exploit+ subscription |
+| `max` | Exhaustive, research-grade | $18.00 | Blackops+ subscription |
 
 You are never billed more than the reserved hold.
 
+**A key without the subscription is not refused — it is downgraded.** `deep` and
+`max` resolve to `basic`, and the run executes and bills as `basic` with a notice
+on the stream. Call `prowl_get_wallet` (free) before spending: it returns
+`entitlement.available_execution_modes` for the current key, and
+`downgraded_modes` for the ones that would silently change.
+
 ## Playbooks
 
 Pass `playbook_id` to `prowl_analyze` to force a fixed report shape instead of a dynamically composed one:
@@ -74,14 +91,21 @@ Call `prowl_list_playbooks` (free) for what each one covers.
 ## Verify
 
 1. List MCP tools; confirm `prowl_list_tools`, `prowl_tool_info`, `prowl_call_tool`, `prowl_analyze`.
-2. Run `prowl_list_tools` (free) → 448 tools grouped by category.
-3. Connectivity check (no auth): `curl https://prowl.chat/mcp/health`.
+2. Run `prowl_list_tools` (free) → category counts summing to `total_tools: 448`. (It returns counts, not names — pass `names=true` for the full list.)
+3. Run `prowl_get_wallet` (free) → the key is valid, and the balance and available modes come back.
+4. Connectivity check (no auth): `curl https://prowl.chat/mcp/health`.
 
 ## Billing
 
 - **Subscription pool** (plan renewal, burns at period end) + **extra pool** (top-ups, never expires).
 - Each `prowl_call_tool` response carries a `billing` object (`estimated_cost_usd`, `actual_cost_usd`, `debited`).
 - Insufficient balance blocks the call before it runs — top up at MCP Home.
+- Read the balance with **`prowl_get_wallet`** (free). The REST route
+  `GET /api/v1/wallet` returns the same figures but decodes a **JWT**, and a
+  `prowl_` API key is not one — no REST endpoint accepts an API key, so MCP is
+  the only surface that can answer this key.
+- A scoped key can be capped below the wallet (`key_limits` in the same
+  response); a batch planned against the balance alone can still be refused.
 
 ## The status widget
 

package/plugins/prowl-cli/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "prowl-cli",
   "description": "Prowl CLI skill: drive the 448-tool Prowl market-intelligence catalog from the shell with @prowl-ai/cli — no MCP server required.",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "author": {
     "name": "Prowl",
     "email": "support@prowl.chat",

package/plugins/prowl-cli/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "prowl-cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Prowl CLI skill: drive the 448-tool Prowl market-intelligence catalog from the shell with @prowl-ai/cli — no MCP server required.",
   "author": {
     "name": "Prowl",

package/plugins/prowl-cli/skills/prowl-cli/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: Requires Node.js 18+, the `@prowl-ai/cli` npm package (installed globally or run via npx) and a Prowl API key; makes network calls to prowl.chat.
 metadata:
   author: prowl.chat
-  version: "0.1.1"
+  version: "0.2.0"
 ---
 
 # Prowl CLI — market intelligence from the shell
@@ -32,57 +32,100 @@ mkdir -p ~/.prowl && printf %s 'prowl_...' > ~/.prowl/prowl_mcp_token && chmod 6
 
 Never print the key back to the user, never pass it in a command you echo into a log, and never write it into a repo file.
 
-Requires Node.js >= 18.
+Requires Node.js >= 18. Verify with `prowl auth status`, which proves the key by making an authenticated call rather than assuming it works.
 
 ## Commands
 
+Each command maps to one MCP tool; the CLI covers all 21 the server registers.
+
 ```
-prowl auth status | login | logout
-prowl tools list                            # 448 tools by category (free)
-prowl tools search "<query>"                # semantic catalog search (free)
-prowl tools info <tool_name>                # input schema + estimated cost (free)
-prowl call <tool_name> --params '<json>'    # invoke one tool (wallet debit)
-prowl analyze "<query>" [--tier basic|deep|max] [--playbook <id>] [--session <id>]
-prowl wallet                                # balance
-prowl version
+CATALOGUE (free)
+  prowl tools list [--category <c>] [--names] [--limit n] [--offset n]
+  prowl tools search "<query>" [--category <c>] [--provider <p>] [--limit n] [--offset n]
+  prowl tools info <tool_name>
+  prowl playbooks
+
+RESEARCH (debits the wallet)
+  prowl call <tool_name> --params '<json>' [--session <id>]
+  prowl analyze "<query>" [--tier basic|deep|max] [--playbook <id>] [--session <id>]
+  prowl session start "<query>" [--tier <t>] [--title <s>] [--watch] [--interval <s>]
+  prowl session status <id> | get <id> [--messages] | list | reset [<id>]
+
+SCHEDULES (each run debits the wallet)
+  prowl schedule create "<query>" [--cadence <c>] [--tier <t>] [--playbook <id>]
+  prowl schedule list | pause <job_id> | resume <job_id> | cancel <job_id>
+
+OUTPUT (debits the wallet; needs a report on the same --session)
+  prowl artifact <infographic|pdf|pptx|audio|video> [--theme <t>] [--session <id>]
+  prowl export [--format markdown|html] [--session <id>]
+
+ACCOUNT (free)
+  prowl auth status | login | logout
+  prowl wallet
+  prowl stats [--session <id>]
+  prowl errors [--hours n] [--tool <name>] [--severity <s>] [--limit n]
+  prowl version
 ```
 
-Global flags: `--json` (one machine-readable JSON document on stdout — always use this when parsing), `--key <k>`, `-h`.
+Global flags: `--json` (one machine-readable JSON document on stdout — always use this when parsing), `--key <k>`, `--quiet`, `-h`.
+Environment: `PROWL_API_KEY`, `PROWL_BASE_URL`, `PROWL_MCP_URL`, `PROWL_TIMEOUT_MS`.
+
+Recommended flow: `tools search` → `tools info` (check the cost) → `call`. Reach for `analyze` when the goal is a full report rather than one data point. Pass a stable `--session <id>` across consecutive calls to keep the report cache, history and spend scoped to one investigation; `artifact` and `export` read the report cached against that session, so they need a prior `analyze` on the same id.
 
-Recommended flow: `tools search` → `tools info` (check the cost) → `call`. Reach for `analyze` when the goal is a full report rather than one data point. Pass a stable `--session <id>` across consecutive `analyze` calls to keep the report cache and conversation history scoped to one investigation.
+`tools list` returns category **counts**, not names — pass `--names` or `--category <c>` for names, or prefer `tools search`, which is cheaper and ranks by relevance.
 
-## Tiers and cost control
+## Tiers, and the downgrade that is not a refusal
 
 `analyze` defaults to `--tier basic`. Each tier holds a hard provider-cost cap for the run — billing never exceeds the reserved hold.
 
-| Tier | Use for | Cap |
-|------|---------|----:|
-| `basic` | one question, fast turnaround | $2.50 |
-| `deep` | full competitive report | $8.00 |
-| `max` | exhaustive, research-grade | $18.00 |
+| Tier | Use for | Cap | Requires |
+|------|---------|----:|----------|
+| `basic` | one question, fast turnaround | $2.50 | — |
+| `deep` | full competitive report | $8.00 | Exploit+ subscription |
+| `max` | exhaustive, research-grade | $18.00 | Blackops+ subscription |
+
+**A key without the subscription is not refused — it is downgraded to `basic`, and the run executes and bills as `basic`.** Nothing in the output announces this loudly, so check before spending:
+
+```bash
+prowl wallet     # balance, plus the modes this key can actually run
+```
 
 Check `prowl tools info <tool>` before a `call` in a loop, and `prowl wallet` before a batch. Confirm with the human before running `--tier max` or a batch that could exceed a few dollars.
 
+## Long runs
+
+`analyze` blocks for 30 seconds to 5 minutes (`max`: up to 10); the CLI waits up to 15 minutes, overridable with `PROWL_TIMEOUT_MS`. In a script, prefer the async form — the run is detached server-side from the first call, so a dropped connection costs nothing:
+
+```bash
+prowl session start "competitors of stripe.com" --tier deep --watch
+```
+
+Without `--watch` it returns a `session_id` immediately; poll with `prowl session status <id>` and read the report with `prowl session get <id>`.
+
 ## Playbooks
 
 `--playbook <id>` forces a fixed, persona-tuned report shape:
 
 `geo-visibility-audit` · `competitor-teardown` · `content-engine` · `local-and-reputation` · `mobile-aso` · `amazon-marketplace` · `idea-validation` · `channel-economics-audit`
 
+`prowl playbooks` (free) prints what each one covers.
+
 ## Exit codes
 
 `0` ok · `1` runtime/tool error · `2` usage · `3` auth (missing or invalid key) · `4` insufficient balance · `5` network/timeout.
 
-Handle them: `3` means ask the human for a key, `4` means stop and report the balance rather than retrying, `5` is the only one worth a retry.
+Handle them: `3` means ask the human for a key, `4` means stop and report the balance rather than retrying, `5` is the only one worth a retry. A tool that reports failure as text is mapped onto the same codes, so branching on the exit code is safe.
 
 ## Examples
 
 ```bash
-prowl tools search "backlinks"
+prowl tools search "backlinks" --limit 5
 prowl tools info majestic_get_back_link_data
 prowl call extract_domain_from_url --params '{"url":"https://stripe.com/pricing"}'
 prowl analyze "competitors of stripe.com" --tier basic --json
 prowl analyze "is there demand for an AI receipt scanner" --playbook idea-validation --tier deep
+prowl session start "teardown of vercel.com" --tier deep --watch
+prowl wallet --json
 ```
 
 ## When to use