researcher-now (researcher.now)

Article and video analysis, not scraping: any URL becomes a cleanly formatted article — any YouTube video, X/Twitter video post, or Spotify / Apple Podcasts episode a full transcript with speaker-aware quotes — plus finished structured analysis (claims, facts, quantitative data, stakeholder positions, quotes with attribution), so you don't spend your own context window parsing raw pages. Articles answer inline; media analysis lands on the run within minutes. Deep multi-source research via one explicit `deep_research` call returns a synthesized, cited Research Report.

Base URL: https://researcher.now
Install page: https://researcher.now/install/
Agent contract: https://researcher.now/agent.txt
Machine contract: https://researcher.now/agent.json
API docs: https://researcher.now/api/
MCP endpoint: https://researcher.now/mcp
Hermes plugin install: pip install researcher-now && hermes plugins enable researcher-now (or add researcher-now to plugins.enabled in ~/.hermes/config.yaml if the CLI says not installed)
  (the `hermes plugins enable` step is REQUIRED — pip plugins are opt-in in Hermes)
Installable skill: npx skills add researcher-now/skill

Use researcher-now when a customer needs article or video analysis (`POST /v1/analyze`, seconds to first result, then a full synthesized report on the same run), durable cited Research Reports, reusable source records, a live watch URL, stored artifacts, usage audit data, run-scoped chat, or research-memory recall (`GET /v1/library/search`). Always surface the `viewerUrl` from analyze and the `watchUrl`/`viewerUrl` from deep research back to the end user in your reply. This is a durable, shareable research artifact — the user expects to be able to open it, share it, and revisit it. Do not swallow these links. Relay links exactly as returned by the API — never construct researcher.now URLs yourself; the share slug is random and cannot be derived from the runId. Keys are customer rk_ keys from https://researcher.now/account/.

Critical rules:
1. Use a customer key: `Authorization: Bearer $RESEARCHER_TOKEN`.
2. If no key is available, send the customer to https://researcher.now/account/?setup=agent.
3. Use `GET /v1/me` before spending if token role is uncertain.
4. Use `POST /v1/runs` for all new work and include `Idempotency-Key`. Send it on paid `POST /v1/runs/:id/iterate` calls too.
5. Use `preflightPlan:true` for vague or high-stakes requests.
6. Use `source.type:"topic"` for research, `"url"` for direct ingestion, `"feed"` for RSS/Atom/JSON Feed, and `"video"` for transcript-first video work.
7. Share `watchUrl` and `viewerUrl` immediately after create succeeds. Also share any returned `watchUrl` or `viewerUrl` from `research_status`.
8. Do not use admin tokens, payment bypasses, local key searches, or generic scraping fallbacks while researcher-now is processing.
9. Prefer `limits.maxCostUsd` for budgets. `limits.max_cost_usd`, top-level `maxCostUsd`, `max_cost_usd`, `budgetUsd`, and `budget_usd` are accepted aliases. If `depth` is omitted, Researcher derives the planning tier from the budget; explicit `depth` wins. Research runs are budget-bounded; do not describe source counts, query counts, loop counts, `maxSources`, or other internal safety controls as customer-facing caps.
10. For unattended or multi-run agents, register a terminal webhook with `POST /v1/webhooks` before starting work. Otherwise stream or poll until `succeeded`, `failed`, or `cancelled`; never leave terminal runs in a queued/in-flight list.

MCP:
- Remote endpoint: `https://researcher.now/mcp`
- Transport: Streamable HTTP JSON-RPC.
- Auth: customer bearer keys only; admin/operator tokens are rejected.
- Tools: `analyze_article`, `analyze_video`, `deep_research`, `research_status`, `research_inbox`, `recall_research`, `list_personas`, `ask_persona`, `ask_corpus`, `list_persona_sessions`, `list_topics`, `topic_brief`, `get_source_package`.
- `list_personas` / `ask_persona` / `ask_corpus`: consult durable expert personas (Paul Graham, Warren Buffett, Elon Musk, Patrick Collison, Jeff Bezos, Stanley Druckenmiller, and more) — each a research-grounded corpus of that person's own writing, talks, and posts; `ask_persona` answers in their voice with citations (small per-question fee), and `ask_corpus` is the alias when you already know the corpus slug. `list_topics` / `topic_brief`: read your standing research topics and their living briefs (free). `get_source_package`: download one source's full delivery package from a persona's corpus (cleaned text, timestamped transcript, graded `evidence.json`, `summary.md`, citation handles); pass `persona` plus `sourceId`, add `file` to fetch any one file in full (free).
- `deep_research` accepts a `topic` argument only in this production version. Use REST for source objects, preflight/chat fields, and URL/feed/video run ingestion until the MCP URL-safety gate ships; use `analyze_article`/`analyze_video` for single-URL work.
- MCP exposes persona/corpus consultation and topic reads; it intentionally excludes Run Analyst chat, source add/prune/redo, delete/stop, account-key creation, webhooks, deposits, collections, entity/topic management, Discord, admin/operator paths, and arbitrary REST passthrough.

Codex setup:
```bash
export RESEARCHER_TOKEN="rk_..."
codex mcp add researcher-now --url https://researcher.now/mcp --bearer-token-env-var RESEARCHER_TOKEN
```

Create a topic run:
```bash
curl -sS -X POST "$RESEARCHER_BASE_URL/v1/runs" \
  -H "Authorization: Bearer $RESEARCHER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: run-$(date +%s)" \
  -d '{
    "requestedBy": "customer-agent",
    "source": {"type": "topic", "topic": "recent advances in battery recycling"},
    "instructions": "Include citations, confidence, gaps, and next actions.",
    "limits": {"maxResearchLoops": 3, "maxCostUsd": 25}
  }'
```

Direct URL, feed, and video sources use the same endpoint:
```json
{"source":{"type":"url","url":"https://example.com/","scope":"domain"}}
{"source":{"type":"feed","url":"https://example.com/feed.xml","limit":50}}
{"source":{"type":"video","url":"https://www.youtube.com/watch?v=...","transcriptMode":"native"}}
```

Read and inspect:
- `GET /v1/runs/:id/job`
- `GET /v1/runs/:id/stream`
- `GET /v1/runs/:id/results`
- `GET /v1/runs/:id/markdown`
- `GET /v1/runs/:id/sources`
- `GET /v1/runs/:id/extractions`
- `GET /v1/runs/:id/transcript`
- `GET /v1/runs/:id/usage`
- `GET /v1/runs/:id/diff`
- `GET /v1/runs/:id/tags`

Check run-state warnings before presenting a completed report. `report_contract_residual_issues` means writing or output-shape defects remain; `report_evidence_gaps` means more evidence would be needed for some requested requirements; `report_unavailable_evidence` means some requested data appears paid, private, blocked, registry-only, or otherwise unavailable to an automated public run.

Completion webhooks:
- `POST /v1/webhooks` with `{"event":"run.complete","url":"https://example.com/researcher","secret":"at-least-8-chars"}` registers an account-scoped terminal-run webhook.
- `GET /v1/webhooks` lists active webhooks; `DELETE /v1/webhooks/:id` disables one.
- `run.complete` subscriptions receive succeeded, failed, and cancelled terminal deliveries. The `x-researcher-event` header and payload event name the actual terminal event, such as `run.succeeded` or `run.failed`.
- When a secret is set, verify `x-researcher-signature`: `sha256=` plus the HMAC-SHA256 of the raw JSON body.
- Per-run `webhookUrl` fields on `POST /v1/runs` are not supported; register an account webhook once.

Agent inbox (default run delivery):
- Every terminal run on the account lands in the agent inbox as a pending export, regardless of which surface started it — no registration required.
- `GET /v1/exports/pending` lists unseen terminal runs (`limit` default 20, max 100); entries carry `id`, `runId`, `event`, `title`, `topic`, and `urls` (watch, markdown, api).
- `POST /v1/exports/ack` with `{"ids":["..."]}` marks them seen; acknowledging is per-account.
- Check the inbox at session start and before commissioning new research; surface each run's watch URL to the user.

Iterate:
- `POST /v1/runs/:id/iterate` with action `start`, `pause`, `continue`, `deepen`, `focus`, `steer`, `report`, `fork`, `evaluate`, `cancel`, or `stop`.
- `POST /v1/runs/:id/sources` to add sources.
- `DELETE /v1/runs/:id/sources` to prune sourceIds[].
- `POST /v1/runs/:id/sources/:sourceId/redo` to re-analyze one weak source.

Run chat:
- `POST /v1/runs/:id/chat`
- `GET/POST /v1/runs/:id/chat/sessions`
- `POST /v1/runs/:id/chat/sessions/:sessionId/messages`
- `GET /v1/runs/:id/chat/turns/:turnId/stream`
- `DELETE /v1/runs/:id/chat/turns/:turnId`
- `GET /v1/runs/:id/chat/index`
- `POST /v1/runs/:id/chat/index/rebuild`

Account and library:
- `GET /v1/runs`
- `GET /v1/account/chats`
- `GET /v1/account/balance`
- `GET/POST/PATCH/DELETE /v1/account/keys`
- `GET/POST /v1/account/deposit-addresses`
- `GET/POST /v1/webhooks`
- `DELETE /v1/webhooks/:id`
- `GET /v1/exports/pending`
- `POST /v1/exports/ack`
- `GET /v1/library/search`
- `GET /v1/library/evidence`
- `GET /v1/library/claims`
- `GET/PATCH /v1/library/contradictions/:id`
- `POST /v1/library/contradictions/:id/verify`

Billing:
If create returns 402, surface `account_funding_url` when present; otherwise send the customer to https://researcher.now/account/. `limits.maxCostUsd` is a ceiling, not a target. `priceUsd` is the planner estimate; `budgetUsd` and `budgetPolicy` are the authorized ceiling. When setting a budget from an agent, prefer `{"limits":{"maxCostUsd":25}}`.