primr

Route Primr research without making the user learn its internal commands. Primr Zero combines deterministic Primr collection with the current agent host's research and reasoning. The provider-backed pipeline adds Primr-managed model synthesis, cross-validation, strategy generation, and rendering after an estimate and explicit spend approval. Both aim for useful strategic artifacts; the host-powered path is not a renamed scrape mode or a deliberately worse application.

The declared tool surface covers both routes: narrowly scoped Primr shell commands for collection and provider-backed operation, plus host-native web research and artifact editing for the no-launcher Zero fallback. Normal host permissions and workspace boundaries still apply.

Agent-host default

When a request is addressed to an agent host, keep the public invocation simple:

primr "Company" https://company.example

Treat that bare company-and-URL request, "run Primr," and "build a full dossier" as Primr Zero by default. Use the primr-zero skill and run primr prep internally when a shell is available. Do not make the user choose between prep, scrape, and full, and do not ask for spend approval for the zero-model-call collection. Disclose its public network activity, then continue.

Route to the provider-backed pipeline only when the user explicitly asks for paid, metered, provider-backed, or premium Primr; supplies a dollar budget; asks to use provider API keys; or provides provider-only CLI modifiers such as --premium, --mode, --platform, --strategy-type, or --no-ai-strategy. Configured API keys are capability, not consent to spend.

This is an agent-routing rule, not a CLI compatibility change. When a human runs primr "Company" https://company.example directly in a terminal, the existing provider-backed CLI behavior remains unchanged and requires the normal estimate and approval discipline.

When this is the right tool

Use Primr Zero when the user wants substantial Primr research without explicit provider-spend intent:

• "Run Primr on ExampleCo" / "primr ExampleCo https://example.co"
• "Build me the full strategic dossier for ExampleCo"
• "Use this repository to research ExampleCo"
• "Build the fullest dossier you can for $0 using my existing agent plan"

Use the provider-backed pipeline when paid intent is explicit:

• "Run the paid Primr pipeline on ExampleCo"
• "Use my provider API keys after showing me the estimate"
• "Run premium Primr with a budget of $5"
• "Generate the paid AI strategy module for the ExampleCo report"
• "Refresh ExampleCo with the provider-backed pipeline"

Do not use primr for:

• A quick pre-call brief with no API budget - use the host's built-in web search and reasoning. primr is wrong for "give me two paragraphs on Acme."
• DNS / tenant / email-security only - use primr recon company.com, which is

keyless and standalone. A host-native passive lookup is also fine when Primr is not installed.

• Reviewing an existing primr report's quality - still primr (run_qa MCP tool or primr --qa <company> CLI), but invoke that path directly without estimating a new run.

If the user is ambiguous ("research ExampleCo"), use the host's normal quick research path. If the user names Primr or points the agent at this repository, use the Agent-host default above. A vague research request must never trigger billable Primr.

Before first invocation

Resolve a working Primr launcher before the first call in a session. For Primr Zero, provider configuration is irrelevant:

primr --version

If the current workspace is a Primr source checkout and primr is not on PATH, try uv run --no-sync primr --version. When that succeeds, use uv run --no-sync primr anywhere these instructions show primr. If neither launcher works during Primr Zero, continue with the host-native research fallback when the host can search the web. You may offer installation, but do not block useful work on it and do not install or sync an environment without approval. A provider-backed request does require a working Primr installation.

Before a provider-backed run, also check its configuration:

primr doctor

For an explicitly provider-backed request where Primr is not installed:

"Primr isn't installed. It's a Python CLI from github.com/blisspixel/primr. For this provider-backed run, use pipx install primr on Python 3.12+, then run primr init. Want me to walk through it?"

Wait for explicit approval before running pip install. For Primr Zero, if installation is declined or unavailable, proceed with the host-native fallback and disclose the unavailable Primr collectors. If primr doctor reports missing keys, do not attempt to set them yourself. Missing keys block provider-backed research, but they do not block primr prep or primr recon.

Detecting MCP vs CLI

Choose Primr Zero versus provider-backed execution before choosing transport. Primr Zero collection uses primr prep; never call a billable MCP research tool as a substitute. For an explicitly provider-backed request, look at your available-tools list:

• If you see mcp__primr__* tools (mcp__primr__estimate_run, mcp__primr__research_company, etc.) → prefer MCP. It returns structured objects, exposes job state via resources, and the cost gate is enforced server-side.
• Otherwise → fall back to the primr CLI. Same workflow, file-based artifacts.

Do not call an MCP tool speculatively to test connectivity. To get from CLI-only to MCP, the user adds primr to their host's MCP config (the snippet is { "command": "primr", "args": ["mcp"] }; see the clients/ directory in the primr repo for per-host paths).

In an Agent Plugins v1 client, skills may still load when the MCP component is unsupported or cannot start. Primr's portable mcp.json uses the bare primr executable token, so that component requires Primr to be installed and discoverable through the client's executable search rules. Treat an unavailable server as skill-only operation, not as approval to substitute another billable tool.

Zero-cost host handoff (precedes billable modes)

Treat a bare Primr company-and-URL request in an agent host, any request for a free version, zero cost, no API key or API spend, or use of an existing Claude, Codex, Copilot, Gemini, Cowork, or other agent plan as a request for Primr Zero. This routing decision takes precedence over the billable cost gate and applies even after a paid estimate was shown, declined, or cancelled. Stop the paid workflow before continuing. Never answer "there is no free tier": the provider-backed Primr pipeline has no free mode, but Primr Zero is a supported workflow.

Tell the user that Primr Zero uses keyless primr prep collection with zero Primr model calls, followed by research and synthesis in the current agent host. Only describe the complete workflow as zero incremental spend after verifying that the host is plan-backed and will not bill API usage or overages.

If the dedicated primr-zero skill is available, use it. If it is unavailable, stale, or cannot be loaded from the current skill, do not deny the free path or stall. With shell access, follow this inline fallback:

primr --version
primr prep "Company" https://company.example --dry-run
primr prep "Company" https://company.example

The dry run must report $0.00 and zero model calls. The real command performs public network requests, emits a bounded evidence bundle and portable skill, and fails closed against model egress even when keys are configured. Disclose the network activity, but do not require spend approval for this zero-dollar collection. Read the emitted prep_manifest.json, source_index.json, research_packet.md, and HOST_WORKFLOW.md in that order, then follow the emitted primr-zero/SKILL.md for host research, writing, and QA. Never pass host OAuth tokens or cookies into Primr, and never switch to a paid run silently.

Without shell access, or when the Primr launcher is unavailable and installation is declined or cannot proceed, use the host's supported web research and file tools to follow the same Primr Zero report contract. Do not stall on the missing launcher. Disclose that Primr DNS, browser-backed collection, ATS adapters, scrape traces, and local artifact QA were unavailable. If the host cannot research the web, ask for a prep bundle or source files instead of writing from model memory.

--mode scrape is still a billable provider-backed mode, typically around $0.10. It is not Primr Zero and must not be presented as the free or cheapest available path when the user asked for $0.

The billable cost gate (non-negotiable)

primr runs cost real money and real time. Never launch a run without:

1. Estimating first. MCP integrated research: estimate_run(company_url=..., mode=..., platforms=[one_platform], strategy_type="ai"). Additional platforms and non-AI modules use estimate_strategy plus generate_strategy after the base report. CLI: append --dry-run to the exact command you intend to run. For an existing report, use primr --ai-strategy-only REPORT --dry-run; execution repeats the quote and still requires explicit approval.
2. Reporting the estimate verbatim - quoted dollars and minutes, plus what mode and what strategy.
3. Getting explicit user approval in the conversation. "Want me to launch it?" → wait for "yes" / "go" / equivalent. A user asking "how much would it cost" is not approval.

If the user pushes back on cost or asks whether a free version exists, offer the Primr Zero route above first. Only if they explicitly prefer a cheaper provider-backed run should you suggest scrape (~$0.10) or --no-ai-strategy (around ~$0.76-$0.79 on the measured xAI plus Gemini recipe), then re-estimate. If they want premium depth, surface --premium and report its live estimate instead of a static price.

MCP enforces this gate with estimate-bound tokens and caps. The CLI prompts by default; an agent must still report the estimate and obtain approval before it passes --skip-confirm for noninteractive execution.

The presence of a configured provider API key never satisfies approval. Paid intent chooses this path; the estimate and explicit approval authorize the specific run.

Provider-backed workflow

1. Estimate. estimate_run (MCP) or primr "Name" url --dry-run [flags] (CLI). Capture the cost, time, page count, planned strategy.
2. Approve. Quote the estimate, ask for go-ahead. Stop. Do not proceed without an explicit "yes."
3. Launch. MCP: research_company(company_name=..., company_url=..., mode=..., platform=..., destination=...) returns job_id. CLI: after approval, replace --dry-run with --skip-confirm in the exact quoted command. Use a prompt only for a foreground human terminal run. Note the job_id or output directory.
4. Don't block. Runs take 35-120 minutes. Tell the user the job is running and what file path will hold the report. Do not poll synchronously in a loop.
5. Resume on next turn. When the user comes back ("is the Acme report done?"), check primr://research/status or check_jobs (MCP), or look for the markdown file at output/<company>/<Company>_Strategic_Overview_<MM-DD-YYYY>.md (CLI). If still running, report the stage and stage_progress_percent.
6. Confirm completion, then hand off. If using MCP, read primr://output/artifacts/by_job/{job_id} first to list the owned job's artifacts without loading report body content. If QA ran, read primr://output/qa_summary/by_job/{job_id} for compact score/status/count metadata. Read primr://output/usage_summary/by_job/{job_id} when you need cost, timing, approval, or artifact-count metadata without loading the full manifest. Its actual_cost_usd can be null until the actual-cost audit closes; never present an estimate or approved ceiling as actual spend. Read primr://output/source_summary/by_job/{job_id} when you need citation/source appendix counts, domains, missing citations, or duplicate URL metadata without loading report body content. Read primr://output/trace_summary/by_job/{job_id} when you need scrape trace health, tier attempts, latency, block, HTTP status, or validation metadata without loading URLs, raw trace entries, or page content. Read primr://output/verification_summary/by_job/{job_id} when you need claim verification trust score, claim counts, status counts, first-party downgrade counts, or source-reference counts without loading raw claims, source URLs, search queries, explanations, or report body content. Read primr://output/calibration_summary/by_job/{job_id} when you need label-calibration counts, evidence-review count buckets, judge provenance, or judge-agreement metadata without loading raw claims, source URLs, evidence reviews, rationales, or report body content. MCP resource reads and A2A skill calls are audit-logged without raw URI query values, raw resource bodies, raw message text, raw results, or caller ids. Then read the report path or preview needed for the handoff. Do NOT dump the full report into the conversation - it's ~21k words. Summarize the executive summary, list the section count, and offer downstream actions (see references/downstream-handoff.md).

Mode, tier, platform, strategy

primr exposes four orthogonal levers. Default is full mode, recon-driven platform selection, default --grok-tier, and the built-in AI Strategy module unless --no-ai-strategy is passed.

For the full decision matrix - when to pick each, cost and time per combination, multi-platform behavior - see references/modes-and-strategies.md. One-liner heuristics:

• Mode: full for almost everything. scrape if external research isn't needed. deep if the site is blocked. premium only when the user asks for board-grade depth.
• Platform: omit unless the user requests an ecosystem emphasis. Use --platform azure, --platform aws, --platform gcp, or --platform private for one strategy. --platform ms is the explicit azure private shorthand and produces two artifacts, so re-estimate it accordingly. The flag affects the AI strategy module, not the core report.
• Strategy type: omit for the default Strategic Overview plus AI Strategy. Pass --no-ai-strategy for the base report only. Use an active type reported by primr --list-strategies or primr://strategies/available, such as customer_experience, modern_security_compliance, or data_fabric_strategy. Use primr skills, not --ai-strategy-only, for the Skills pack workflow.

Custom strategies

primr discovers any YAML file dropped into <install>/prompts/strategies/ (or the user's override path). Author one when the user wants a recurring deliverable that doesn't fit the built-ins (e.g., "FinOps assessment for retail clients", "M&A integration playbook").

For the schema and a worked example, see references/custom-strategy-yaml.md. Keep custom strategies in version control; do not edit a built-in YAML in place.

Async monitoring

Long runs are the common case. Pick the lightest async pattern your host supports - never poll synchronously in a tight loop.

Preferred, in rough order:

1. Background launch with completion notification. If your host can run a command in the background and notify you when it exits, use that to launch primr. For an approved standard provider-backed CLI run, the background command must include --skip-confirm; never rely on an interactive prompt or pipe y into it. The experimental primr orchestrate command instead requires an approved --max-cost <usd> ceiling. You get one event ~45 min later when the run finishes. This is the cleanest pattern.
2. Stream phase markers from the log. If your host can tail a file and emit one event per matching line, watch the run log for the phase boundaries (PHASE, Complete, Error) - about 6-8 events across a full run. Right density for "is it making progress?" without polling noise.
3. Schedule a single early sanity check at ~5 minutes. Most failures (rejected key, scrape pilot fails, no external sources) surface in the first phase. A one-shot check at +5min catches those before the user wastes 45 minutes.
4. Fallback (no async primitives at all). Tell the user "I'll check back in about an hour" and stop. When the next turn arrives, read state first (check_jobs / primr://research/status / the report file at output/<company>/<Company>_Strategic_Overview_<MM-DD-YYYY>.md), then summarize.

On every follow-up turn, regardless of how you got there: read state first. Never claim done until the report file exists and check_jobs reports status: completed. On failure, read primr://output/manifest/latest if available - it contains the audit trail (estimate, approval, execution, error). Surface the failure cause; do not silently re-launch.

What not to do:

• Don't poll in a tight loop or with sub-minute sleeps. primr stages take minutes; sub-minute polling burns context for no information.
• Don't promise a heartbeat cadence the host can't actually deliver. If you can't schedule wake-ups, "check back in an hour" is honest; "I'll update you every 10 minutes" is not.
• Don't treat the absence of completion as failure. A run that's been going 60 minutes is probably fine; check the log for the most recent phase marker before assuming the worst.

Output handling

Reports land in output/<company_slug>/:

• <Company>_Strategic_Overview_<date>.md - primary deliverable
• <Company>_AI_Strategy_<date>.md - only if --strategy-type ai (or another module) was selected
• scraped_content.txt, insights.json, dossier.json - pipeline intermediates
• run_manifest.json - audit trail

When the user asks "what did we get": for MCP, prefer primr://output/artifacts/by_job/{job_id} as the first inventory read; it returns file names, paths, sizes, hashes, timestamps, classifications, and missing-file state without report body content. If QA artifacts are attached, use primr://output/qa_summary/by_job/{job_id} for compact QA score/status/count metadata without detailed QA body text. Use primr://output/usage_summary/by_job/{job_id} for compact cost, timing, approval, and artifact-count metadata without full manifest content. Its actual_cost_usd can be null until the actual-cost audit closes; never present an estimate or approved ceiling as actual spend. Use primr://output/source_summary/by_job/{job_id} for compact citation/source appendix counts, domains, missing citations, duplicate URLs, and source URLs without report body content. Use primr://output/trace_summary/by_job/{job_id} for compact scrape trace counts, tier health, latency, block, HTTP status, and validation metadata without URLs, raw trace entries, or page content. Use primr://output/verification_summary/by_job/{job_id} for compact claim verification trust score, claim counts, status counts, first-party downgrade counts, and source-reference counts without raw claims, source URLs, search queries, explanations, or report body content. Use primr://output/calibration_summary/by_job/{job_id} for compact label-calibration counts, evidence-review count buckets, judge provenance, and judge-agreement metadata without raw claims, source URLs, evidence reviews, rationales, or report body content. MCP resource reads and A2A skill calls are audit-logged with hashed payload values, without raw URI query values, resource bodies, message text, raw results, or caller ids. Then list the artifacts, quote the executive summary, and note section count. Do not dump the full markdown unless they ask for the full text. Offer to convert to DOCX (primr writes both by default in full mode) or to feed it to a downstream consumer.

Downstream handoff

primr's outputs are inputs to the rest of the user's toolchain. Do not let a report sit unused. When a run completes, proactively offer the next step the user is likely to need.

For the mapping (Strategic Overview → which next action, AI Strategy module → which next action, hypotheses → which next action), see references/downstream-handoff.md.

Hypothesis memory

primr persists durable research memory per company. Before launching a new run on a company you've researched before:

• MCP: call get_hypotheses(company=...) and read primr://memory/<company> to see what's already known.
• After the run completes, the pipeline saves new hypotheses automatically. If the user asks you to record a finding from a customer conversation, use save_hypothesis(company=..., hypothesis_id=..., claim=..., confidence=..., evidence=...).

Display confidence levels honestly (untested, validated, invalidated, confirmed). Do not promote hypotheses without new evidence.

How to talk about primr's output

primr's voice is hedged strategic analysis with cited sources. Mirror that:

• Surface confidence annotations the report already carries - don't strip them.
• Quote sources from the citation appendix when the user pushes on a specific claim.
• Say "primr's analysis suggests…" rather than asserting findings as facts; the report is one input, not ground truth.
• If the user asks a question the report doesn't cover, say so - do not extrapolate beyond what's written.

Gotchas

See references/gotchas.md for the living list of real observed failure modes (cost gate, async, thin evidence, etc.) and how to avoid them. This file is the primary place for updates.

Key highlights:

• Always estimate first and get explicit approval.
• Long runs are async; check state on next turn.
• primr is for full pipeline, not quick briefs or DNS-only.

Update references/gotchas.md from real failures when using the skill. Load it only when needed (progressive disclosure).

Hard rules

• Cost gate. Never launch a billable run without a fresh estimate and explicit approval in the same conversation turn.
• No synchronous waits. Long runs are async; check state on the next turn.
• No silent retries. A failed run gets reported back to the user with the manifest's error context - they decide whether to re-run.
• No re-estimating against an active job. If check_jobs shows the company already running, surface that and ask if they want to monitor it instead of starting a parallel run.
• Defer behaviorally, not by skill name. For vague "research X" requests with no budget, use the host's web search and reasoning. For DNS-only work, use primr recon when Primr is installed and a host-native passive lookup otherwise. For quality checks on an existing report, use run_qa directly without a new estimate.
• Never edit built-in strategy YAMLs. Custom strategies live in the user's override path; built-ins ship with the package.