# Research Output Schema

`scripts/live_research.py` generates a normalized `research-pack.json` that the skill can inspect before ranking and before writing the final HTML report.

## Purpose

The research pack is not the final decision. It is the evidence layer.

Use it to:

- inspect search coverage
- compare candidates consistently
- track competitor, substitute, and OSS signals
- preserve the query plan and browser strategy used

## Top-Level Shape

```json
{
  "generated_at": "2026-03-23T12:00:00Z",
  "input_file": "/abs/path/to/shortlist.json",
  "browser_strategy": {
    "x": "user_browser",
    "github": "direct_web",
    "official": "direct_web",
    "broader_web": "direct_web"
  },
  "open_request": {
    "sources": ["x"],
    "browser": "frontmost",
    "resolved_browser_app": "Arc",
    "max_open_tabs": 6,
    "opened_urls": []
  },
  "user_context": {
    "prompt": "what should I build in crypto?",
    "summary": [],
    "clarifying_answers": []
  },
  "ideas": []
}
```

## Idea Shape

Each idea should include:

```json
{
  "slug": "agent-settlement-for-vertical-saas",
  "name": "Agent Settlement for Vertical SaaS",
  "one_liner": "Let domain-specific AI agents pay each other onchain for metered actions.",
  "search_plan": {
    "x": [
      {
        "query": "\"agent settlement\" crypto",
        "url": "https://x.com/search?q=...",
        "reason": "look for launches and operator complaints"
      }
    ],
    "github": [],
    "web": [],
    "official_followups": [
      "Check official docs for any direct competitors or protocol dependencies you find."
    ]
  },
  "capture_template": {
    "direct_competitors": [],
    "adjacent_substitutes": [],
    "oss_landscape": [],
    "complaint_signals": [],
    "why_now_signals": [],
    "incumbent_risk": {
      "name": "",
      "assessment": "",
      "reason": ""
    }
  }
}
```

## Intent

- `search_plan` is deterministic and generated by the helper.
- `capture_template` is where the skill or a later pass can accumulate normalized findings.
- `official_followups` are prompts, not URLs, because the right official sources usually emerge after competitor discovery.

## Rules

- Keep the pack compact and query-focused.
- Do not stuff raw page HTML or long article text into the pack.
- Keep findings short, comparable, and source-linked.