@scira/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zaid Mukaddam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# Scira CLI
+
+Terminal-native AI research and coding agent. Ask a question, get a grounded report with cited sources and verified claims — all stored locally and inspectable.
+
+## Install
+
+```bash
+npm install -g @scira/cli
+```
+
+Requires **Node.js ≥ 20**. Run the interactive setup:
+
+```bash
+scira init
+```
+
+This walks you through API keys and configuration. Keys go in `~/.scira/.env` so they work from any directory.
+
+Check your setup:
+
+```bash
+scira doctor
+```
+
+## Quickstart
+
+```bash
+# Interactive TUI (home screen with session history)
+scira
+
+# Headless run — writes a report to .scira/runs/<id>/report.md
+scira "compare browser automation tools in 2025"
+
+# Interactive TUI for a specific question
+scira new "history of the Silk Road" --tui
+
+# Classic readline shell for a specific question
+scira new "history of the Silk Road" --shell
+```
+
+## Setup
+
+Put your API keys in `~/.scira/.env` (loaded automatically from any working directory):
+
+```bash
+mkdir -p ~/.scira && cp .env.example ~/.scira/.env
+# then edit ~/.scira/.env
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `scira init` | Interactive setup for API keys and configuration |
+| `scira [question]` | Open TUI home, or run headlessly if a question is given |
+| `scira new <question>` | Start a run; add `--tui` or `--shell` to open interactive UI |
+| `scira resume <run-id>` | Resume a run; add `--tui` or `--shell` to specify UI |
+| `scira list` | List all runs |
+| `scira show <run-id>` | Print run status (sources, claims, report state) |
+| `scira run <run-id>` | Re-run the research agent on an existing run |
+| `scira verify <run-id>` | Print the claim verification report |
+| `scira export <run-id>` | Export report (md, json, or csv) with `--format` and `--output` |
+| `scira mcp list` | List configured MCP servers |
+| `scira mcp add <transport> <name> <target>` | Add an MCP server (stdio, sse, or http) |
+| `scira mcp oauth <name>` | Run OAuth PKCE flow for an MCP server |
+| `scira mcp enable <name>` | Enable an MCP server |
+| `scira mcp disable <name>` | Disable an MCP server |
+| `scira mcp remove <name>` | Remove an MCP server from config |
+| `scira watch <goal>` | Monitor a topic on a schedule with diffing |
+| `scira models [--provider <p>]` | List available AI Gateway models |
+| `scira config` | Print the resolved config |
+| `scira doctor` | Check credentials and environment |
+
+## Configuration
+
+Config merges `~/.scira/config.json` (global) with `.scira/config.json` (project). All fields are optional.
+
+```json
+{
+  "model": "deepseek/deepseek-v4-flash",
+  "approvalMode": "suggest",
+  "runDirectory": ".scira/runs",
+  "maxSources": 20,
+  "citationPolicy": "strict",
+  "search": {
+    "provider": "exa",
+    "maxResults": 8,
+    "includeDomains": [],
+    "excludeDomains": []
+  }
+}
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `model` | `deepseek/deepseek-v4-flash` | AI Gateway model ID |
+| `approvalMode` | `suggest` | `manual`, `suggest`, or `auto` tool approval |
+| `runDirectory` | `.scira/runs` | Local directory where run data is stored |
+| `maxSources` | `20` | Max sources the agent may gather per run |
+| `citationPolicy` | `strict` | `strict` (all claims cited) or `balanced` |
+| `search.provider` | `exa` | `exa`, `firecrawl`, or `parallel` |
+| `search.maxResults` | `8` | Max results per search query |
+
+## Environment Variables
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `AI_GATEWAY_API_KEY` | Yes | Vercel AI Gateway — all model calls |
+| `EXA_API_KEY` | With Exa | Web search via Exa |
+| `FIRECRAWL_API_KEY` | With Firecrawl | Web scraping via Firecrawl |
+
+## Run Directory
+
+Each run writes to `.scira/runs/<run-id>/`:
+
+```
+goal.txt          original question
+plan.md           agent's research plan
+notes.md          incremental findings
+sources.jsonl     sources gathered (id, url, title, snapshot path)
+claims.jsonl      claims extracted and verified
+report.md         final report
+convo.json        full conversation + feed (for TUI resume)
+```
+
+## License
+
+MIT

package/dist/agent/research-agent.js

@@ -0,0 +1,253 @@
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { ToolLoopAgent, isLoopFinished } from "ai";
+import ora from "ora";
+import { getLanguageModel, requireLlmKeys } from "../providers/llm/registry.js";
+import { createResearchTools, createOneShotTools, createCodingTools } from "./tools.js";
+import { SKILL_CATALOG } from "./skills.js";
+import { createMcpBridge } from "../tools/mcp-bridge.js";
+function instructions(goal, config, workspacePath) {
+    const now = new Date();
+    const temporalContext = now.toLocaleDateString("en-US", {
+        weekday: "long",
+        year: "numeric",
+        month: "long",
+        day: "numeric"
+    });
+    const citationRule = config.citationPolicy === "strict"
+        ? "Citation policy (strict): every non-trivial statement in report.md MUST cite a source ID. Do not include any uncited claims — move anything you cannot cite to an Open Questions section."
+        : "Citation policy (balanced): cite source IDs for all major claims; minor background context may be uncited but must not be overstated.";
+    const codingSection = workspacePath ? `
+
+CODING CAPABILITIES:
+You also have workspace-aware coding tools to build, modify, and debug code:
+- readWorkspaceFile: Read any file in the workspace
+- writeWorkspaceFile: Create or overwrite files (requires approval)
+- editWorkspaceFile: Make surgical edits by replacing exact strings (requires approval)
+- listWorkspaceDir: List files and directories
+- grepWorkspace: Search for patterns across the codebase
+- runWorkspaceCommand: Execute shell commands like builds, tests, installs (requires approval)
+
+Workspace: ${workspacePath}
+
+When the task involves code:
+- Use grepWorkspace and readWorkspaceFile to understand existing code structure
+- Use editWorkspaceFile for precise changes, writeWorkspaceFile for new files
+- Run tests/builds with runWorkspaceCommand to verify changes
+- Research APIs, libraries, or error messages with webSearch + readUrl when needed
+- Match existing code style and patterns
+
+You can seamlessly combine research and coding - e.g., research how to implement a feature, then implement it, or debug an issue by researching the error and fixing the code.` : "";
+    return `You are Scira AI CLI, made by Zaid Mukaddam, an autonomous research ${workspacePath ? "and coding " : ""}agent operating inside a single run directory on the user's machine.
+
+Your goal:
+${goal}
+
+Temporal context:
+Today is ${temporalContext}. Treat dates relative to this date: distinguish past, current, and future events; verify date-sensitive claims with sources instead of relying on model memory.
+
+${citationRule}
+Gather at most ${config.maxSources} high-quality sources — prefer depth and primary sources over volume.
+
+You have shell, file, search, skill${config.files ? ", and local files" : ""}${workspacePath ? ", and workspace coding" : ""} tools. Work like an engineer running a research harness:${config.files ? `\n\nLocal files directory (${config.files.dir}):\nUse listFiles / searchFiles to enumerate documents, getFile to read them, and fileExists to confirm a file is present. Prefer local files as primary sources before falling back to the web. moveFile and deleteFile require user approval.` : ""}${codingSection}
+0. Bootstrap: these built-in research skills are available — pull the relevant ones with readSkill before you begin. This is mandatory — skills contain concrete tactics for search, source quality, claim verification, and report writing.
+${SKILL_CATALOG}
+1. Plan: write a short plan.md outlining your approach (use the research-plan skill as a template).
+2. Gather: use webSearch with 3-5 parallel query variations to find real, citable sources, then readUrl to read the most relevant ones. Record findings in notes.md as you go. Never invent sources or URLs.
+3. Extract claims: after reading each source, use createClaim to record significant findings. Assign a short ID like claim_001, set confidence, and link source IDs.
+4. Verify: once all claims are recorded, use verifyClaim to update each claim's status (verified / weak / contradicted / needs_review). Be honest — flag weak or vendor-only evidence.
+5. Record sources: write all sources you actually used to sources.jsonl (include the snapshotPath reported by readUrl for each one) — STRICT JSONL rules: one compact JSON object per line, no literal newlines inside string values, no trailing commas. Use writeFile to write the entire file at once.
+6. Synthesize: write a clear, well-structured report.md grounded in verified claims (use the report-structure skill for the section layout). Cite source IDs inline. Mark vendor/marketing claims as such.
+7. Finish: when report.md is complete and accurate, stop and give the user a 2-4 sentence summary of what you found.
+
+Rules:
+- Prefer primary sources. Cross-check important claims across multiple sources.
+- Keep files inside the run directory (paths are relative to it).
+- Be terse in your narration between tool calls — say what you're doing and why in one line.
+- Do not claim something is done before you have actually written report.md.
+- Re-read a skill with readSkill any time you are uncertain how to proceed.`;
+}
+function devtoolsInstructionsBlock(toolNames) {
+    if (toolNames.length === 0)
+        return "";
+    return `
+
+Browser tools (Chrome DevTools MCP)
+You have access to a real Chromium browser via Chrome DevTools MCP. The available tool names are:
+${toolNames.map((n) => `  - ${n}`).join("\n")}
+
+DevTools is not only for debugging. Treat it as a research evidence tool for rendered, interactive, current, or runtime-dependent web sources. The built-in skill "browser-research" explains the workflow; read it with readSkill before using DevTools in a full research run.
+
+These tools drive a live browser session and roughly cover four capabilities (exact names depend on the MCP server):
+  - Navigation & input: open URLs, click, type, fill forms, scroll, wait for selectors, navigate history.
+  - DOM & content: read the rendered DOM, accessibility tree, computed styles, and text content of elements.
+  - Console & network: list console messages, errors, and network requests/responses (status, headers, timing, payloads).
+  - Performance & diagnostics: capture screenshots, run performance traces / Core Web Vitals, and inspect runtime state.
+
+When to use them (in priority order):
+  1. The research question asks what a live page currently shows: pricing, product availability, UI copy, feature lists, status pages, rankings, maps, app-store pages, dashboards, search pages, or docs portals.
+  2. The page is JS-heavy, gated, paginated, tabbed, filtered, infinite-scroll, or \`readUrl\` returns empty/garbled/incomplete text.
+  3. The claim depends on runtime behavior — redirects, loaded API payloads, console errors, network calls, client-rendered data, layout, screenshots, or performance.
+  4. You need to verify something only visible after interaction: clicking tabs, expanding accordions, selecting filters, scrolling, entering public search terms, or opening a modal.
+  5. The user explicitly asks to inspect Chrome/browser/devtools/live page/screenshot/console/network/rendered page behavior.
+
+When NOT to use them:
+  - For static articles, papers, docs, blog posts, or anything \`webSearch\` + \`readUrl\` already handles cleanly.
+  - To "browse around" without a concrete claim or hypothesis to validate — these tools are slow and expensive.
+
+Rules for browser tools:
+  - State the hypothesis or claim you are validating in one line before calling a browser tool.
+  - Prefer the smallest sequence of calls that resolves the question; close/navigate away when done.
+  - Record browser observations in notes.md with URL, access time, observed text/state, and interaction steps.
+  - Treat DOM/screenshot/console/network output as evidence for what the page showed at access time: cite the URL you observed it on, and record findings as regular claims with sourceIds pointing to that URL.
+  - Browser observations are primary evidence for page state but not independent corroboration; cross-check important factual claims with separate sources.
+  - Never paste secrets or credentials into the browser.`;
+}
+export async function createResearchAgent(runPath, goal, config, onApprovalRequired, workspacePath) {
+    requireLlmKeys(config);
+    const bridge = await createMcpBridge(config);
+    const researchTools = createResearchTools(runPath, config, onApprovalRequired);
+    const codingTools = workspacePath ? createCodingTools(workspacePath, config, onApprovalRequired) : {};
+    const tools = { ...researchTools, ...codingTools, ...bridge.tools };
+    const agent = new ToolLoopAgent({
+        model: getLanguageModel(config),
+        instructions: instructions(goal, config, workspacePath) + devtoolsInstructionsBlock(bridge.toolNames),
+        tools,
+        stopWhen: isLoopFinished()
+    });
+    return { agent, close: bridge.close };
+}
+function oneShotInstructions(goal, hasDevtools) {
+    const now = new Date();
+    const temporalContext = now.toLocaleDateString("en-US", {
+        weekday: "long",
+        year: "numeric",
+        month: "long",
+        day: "numeric"
+    });
+    const browserHint = hasDevtools
+        ? `
+
+Browser-tool routing (IMPORTANT):
+- If the user explicitly mentions "chrome", "browser", "devtools", "live page", "render", "screenshot", "console", or "network", you MUST use the devtools_* tools instead of webSearch/readUrl. Open the relevant URL with devtools_navigate_page (or devtools_new_page), then take a snapshot/screenshot or read console/network as needed.
+- Use devtools_* for research questions about what a live/current/interactive page shows: pricing pages, product pages, status pages, app-store pages, docs portals, rankings, maps, client-rendered dashboards, or pages with tabs/filters/infinite scroll.
+- Also use devtools_* when readUrl already failed or returned empty/garbled/incomplete text on a JS-heavy page.
+- Otherwise, default to webSearch + readUrl as below.`
+        : "";
+    return `You are Scira in quick one-shot mode. Your job is to either answer the user's question directly OR escalate to the full research harness.
+
+Temporal context:
+Today is ${temporalContext}. Treat dates relative to this date — don't rely on model memory for date-sensitive facts.
+
+Built-in research skills available in full research mode:
+${SKILL_CATALOG}
+
+Question:
+${goal}
+
+Step 1 — Decide the depth required:
+- If the user asks for "research," "deep dive," "analysis," "comparison," "history," or anything that would benefit from >3 sources, structured claims, and a written report → you MUST call requestFullResearch first. Do NOT try to answer it yourself.
+- If the user asks for research that depends on rendered/live/interactive web evidence and DevTools are available, prefer requestFullResearch so the full agent can read the browser-research skill, record observations, and create claims.
+- If the user asks a simple, narrow, or factual question (e.g. "what is the capital of France?", "what time is it in Tokyo?") → answer directly with 1-2 web searches.
+- When in doubt, escalate.${browserHint}
+
+Step 2 — If you decide to answer directly:
+- Default path: use webSearch (2-3 query variations) to find relevant, recent sources, then readUrl to read the best 1-2.
+- Browser path (only if the routing rules above triggered): use the devtools_* tools to drive a real Chromium session, then summarize what you observed (cite the URL you visited).
+- Synthesize a clear, direct answer in a few short paragraphs. Cite sources inline as [title](url). Never invent sources or URLs.
+- Do NOT write files, create claims, or produce a formal report — just answer in chat.`;
+}
+export async function createOneShotAgent(runPath, goal, config, onApprovalRequired, onEscalate) {
+    requireLlmKeys(config);
+    const bridge = await createMcpBridge(config);
+    const tools = { ...createOneShotTools(runPath, config, onApprovalRequired, onEscalate), ...bridge.tools };
+    const agent = new ToolLoopAgent({
+        model: getLanguageModel(config),
+        instructions: oneShotInstructions(goal, bridge.toolNames.length > 0) + devtoolsInstructionsBlock(bridge.toolNames),
+        tools,
+        stopWhen: isLoopFinished()
+    });
+    return { agent, close: bridge.close };
+}
+/**
+ * Run the research agent headlessly, streaming a compact timeline to stdout.
+ */
+export async function runResearchAgent(runPath, goal, config, workspacePath) {
+    const spinner = ora({ stream: stdout });
+    const onApprovalRequired = async (toolName, description) => {
+        spinner.stop();
+        console.error(`\n⚠  ${toolName} needs approval`);
+        console.error("-".repeat(60));
+        console.error(description.slice(0, 800));
+        console.error("-".repeat(60));
+        const rl = createInterface({ input: stdin, output: stdout });
+        const answer = await rl.question("\nApprove? [y/N] ");
+        rl.close();
+        const approved = answer.trim().toLowerCase() === "y";
+        if (approved)
+            spinner.start();
+        return approved;
+    };
+    const bundle = await createResearchAgent(runPath, goal, config, onApprovalRequired, workspacePath);
+    try {
+        const result = await bundle.agent.stream({ prompt: goal });
+        for await (const part of result.fullStream) {
+            if (part.type === "tool-call") {
+                spinner.start(`${CODING_ICONS[part.toolName] ?? TOOL_ICONS[part.toolName] ?? "•"} ${part.toolName}  ${summarize(part.input)}`);
+            }
+            else if (part.type === "tool-result") {
+                spinner.succeed(`${part.toolName}`);
+            }
+            else if (part.type === "tool-error") {
+                spinner.fail(`${part.toolName}  ${String(part.error).slice(0, 80)}`);
+            }
+            else if (part.type === "reasoning-delta") {
+                spinner.stop();
+                // dim the model's reasoning so it's visually distinct from the answer
+                process.stdout.write(`\x1b[2m${part.text}\x1b[22m`);
+            }
+            else if (part.type === "text-delta") {
+                spinner.stop();
+                process.stdout.write(part.text);
+            }
+            else if (part.type === "error") {
+                spinner.fail(String(part.error));
+            }
+        }
+        spinner.stop();
+        process.stdout.write("\n");
+    }
+    finally {
+        await bundle.close();
+    }
+}
+const TOOL_ICONS = {
+    bash: "⌘",
+    writeFile: "✎",
+    editFile: "✎",
+    readFile: "▤",
+    createClaim: "◎",
+    verifyClaim: "✓",
+    webSearch: "⌕",
+    readUrl: "↗",
+    listSkills: "★",
+    readSkill: "★",
+    listFiles: "▤",
+    searchFiles: "⌕",
+    getFile: "▤",
+    fileExists: "▤",
+    moveFile: "✎",
+    deleteFile: "✗"
+};
+function summarize(input) {
+    const obj = (input ?? {});
+    return String(obj.command ?? obj.query ?? obj.url ?? obj.path ?? obj.key ?? obj.pattern ?? obj.source ?? "").slice(0, 100);
+}
+const CODING_ICONS = {
+    readWorkspaceFile: "▤",
+    writeWorkspaceFile: "✎",
+    editWorkspaceFile: "✎",
+    listWorkspaceDir: "▤",
+    grepWorkspace: "⌕",
+    runWorkspaceCommand: "⌘"
+};

package/dist/agent/skills.js

@@ -0,0 +1,265 @@
+export const SKILLS = [
+    {
+        name: "research-plan",
+        summary: "How to structure a research session into discovery, deep-dive, and synthesis phases",
+        content: `# research-plan
+
+## Standard research phases
+
+### Phase 1 — Discovery (10-15 % of budget)
+- Write plan.md with your research questions and initial approach.
+- Run broad searches to map the landscape.
+- Identify 8-12 candidate sources across quality tiers.
+- Note key researchers, institutions, and technical terms for later queries.
+
+### Phase 2 — Deep Dive (60-70 % of budget)
+- Read the 5-8 most relevant sources.
+- Call createClaim immediately after reading each source — don't batch at the end.
+- Keep notes.md updated with key insights and emerging patterns.
+- Discover additional sources through the references sections of sources you've read.
+
+### Phase 3 — Synthesis (20-30 % of budget)
+- Call verifyClaim for every recorded claim.
+- Identify gaps: which key questions lack verified answers?
+- Write report.md following the report-structure skill.
+- Final sanity check: every statistic and specific claim in the report has a cited source ID.
+
+## plan.md starter template
+\`\`\`
+# Research Plan: <topic>
+
+## Goal
+<one sentence>
+
+## Research questions
+1.
+2.
+3.
+
+## Approach
+Phase 1: <broad searches + source identification>
+Phase 2: <deep reading + claim recording>
+Phase 3: <verification + report synthesis>
+
+## Status
+[ ] Phase 1   [ ] Phase 2   [ ] Phase 3
+\`\`\`
+`
+    },
+    {
+        name: "search-strategy",
+        summary: "How to formulate effective search queries, iterate on failures, and exploit parallel fetch",
+        content: `# search-strategy
+
+## Core principle
+Start broad, narrow by iteration. Never assume the first query is optimal.
+
+## Use parallel queries (always)
+webSearch accepts a \`queries\` array — always pass 3-5 variations for a single lookup.
+This runs them in parallel and costs the same latency as one query.
+
+Bad:  { queries: ["dolphin intelligence"] }
+Good: { queries: ["dolphin intelligence research", "cetacean cognition studies 2023 2024",
+                  "bottlenose dolphin problem solving experiments", "dolphin self-awareness evidence"] }
+
+## Retry ladder when results are poor
+1. Remove qualifiers (drop year, drop adjectives).
+2. Swap synonyms: "intelligence" → "cognition" → "learning ability" → "executive function".
+3. Add domain targeting: append "site:pubmed.ncbi.nlm.nih.gov" or "site:arxiv.org".
+4. Search for the researcher or paper title fragment directly.
+
+## Source discovery via chaining
+- Wikipedia article "References" sections are free bibliographies — mine them.
+- After finding a key paper, search for its author name to find related work.
+- Search "<topic> systematic review" or "<topic> meta-analysis" for aggregated evidence.
+
+## Know when to stop
+If 3 different query formulations on the same subtopic return no useful results, record a
+knowledge gap note in notes.md and move on rather than looping.
+`
+    },
+    {
+        name: "source-quality",
+        summary: "Tiers for source credibility; how to assign claim confidence and spot red flags",
+        content: `# source-quality
+
+## Tier 1 — High confidence (confidence: "high")
+- Peer-reviewed journals: PubMed / PMC, arXiv, Nature, Science, PLOS, Cell, PNAS
+- Government databases: NIH, NOAA, NASA, CDC, WHO (.gov, .int)
+- University research pages and institutional preprints (.edu)
+Use confidence "high" when 2+ independent Tier 1 sources agree.
+
+## Tier 2 — Medium confidence (confidence: "medium")
+- Major news organizations with science desks (Reuters, BBC, NYT, AP)
+- Wikipedia — use for orientation and bibliography mining, never as a citable source
+- Reputable non-profits, professional associations
+Use confidence "medium"; always seek corroboration for critical claims.
+
+## Tier 3 — Low / Vendor (confidence: "low", status: "weak")
+- Company blogs, product pages, PR releases, vendor whitepapers
+- Social media, Reddit, forums, user-generated wikis
+- Uncredited, undated, or anonymously authored content
+Flag these explicitly as vendor/marketing in the report.
+
+## Red flags
+- "Studies show" or "research suggests" without a named citation.
+- Statistics that only appear on a single vendor domain.
+- Press releases that describe a study — always trace back to the original paper.
+- Circular citations: A cites B which cites A — find the actual primary source.
+`
+    },
+    {
+        name: "claim-verification",
+        summary: "Protocol for verifying claims: multi-source corroboration, status rules, and common traps",
+        content: `# claim-verification
+
+## Steps for each major claim
+1. Identify the original source (journal, study name, institution, year).
+2. Search with different terminology to find independent corroboration.
+3. Actively search for contradicting evidence: "<claim topic> criticism",
+   "<claim topic> limitations", "<claim topic> contradicted".
+
+## Status decision table
+| Evidence                                        | Status          |
+|-------------------------------------------------|-----------------|
+| 2+ independent Tier 1 sources agree             | verified        |
+| Single Tier 1 source, no contradiction found    | needs_review    |
+| Multiple sources disagree substantially         | contradicted    |
+| Only vendor / marketing sources                 | weak            |
+| No primary source found after 3 search attempts | weak            |
+
+## Batching strategy
+Record claims with createClaim as you read each source.
+Run all verifyClaim calls together at the end of Phase 2, once the full evidence
+picture is assembled — this avoids premature status assignment.
+
+## Common traps
+- Circular citations: trace back to the named primary study, not a news summary.
+- Wikipedia summaries often chain to a single study — read the actual paper.
+- "Preliminary study" and "pilot study" findings warrant confidence "low" regardless of source tier.
+- Quantitative claims (percentages, effect sizes) need the exact study, not a secondary summary.
+`
+    },
+    {
+        name: "report-structure",
+        summary: "Recommended section order, inline citation style, and prose rules for report.md",
+        content: `# report-structure
+
+## Section order
+
+### Executive Summary (3-5 sentences)
+Lead with the strongest conclusions. State what is definitively known and what remains uncertain.
+Do not save the conclusion for the end.
+
+### Key Findings
+Bullet list. Each bullet has an inline source citation: [src_1] or [src_2, src_4].
+Maximum one claim per bullet.
+
+### Detailed Analysis
+One subsection per major theme (200-300 words each).
+Cite inline. Use "evidence suggests" or "appears to" for medium-confidence claims.
+Use direct declarative statements only for verified claims.
+
+### Methodology
+Which searches were run, how many sources evaluated, which were excluded and why.
+Name source tiers used.
+
+### Open Questions / Limitations
+Explicitly list what is NOT well-established.
+Flag vendor-only evidence here.
+This section adds credibility — do not omit it.
+
+### References
+One line per source:
+  - [src_1] Title — https://url
+
+## Style rules
+- Findings: present tense ("dolphins demonstrate self-recognition…")
+- Study descriptions: past tense ("Reiss & Marino (2001) found…")
+- No invented statistics. If a number can't be traced to a primary source, omit it or flag it.
+- Avoid hedge-stacking: "may possibly suggest" → "suggests"
+- Bold key terms on first use.
+- Aim for 800-1500 words for a standard run; longer only if the topic genuinely requires it.
+`
+    },
+    {
+        name: "browser-research",
+        summary: "How to use Chrome DevTools MCP for research on rendered, interactive, JS-heavy, or runtime-dependent sources",
+        content: `# browser-research
+
+Use Chrome DevTools MCP as a research instrument when normal fetch/read tools cannot capture what a real user sees.
+
+## When to use browser tools
+- JS-heavy sites where readUrl returns empty, boilerplate, paywall shells, or missing article content.
+- Product/pricing pages, dashboards, docs portals, app stores, maps, search pages, or sites with tabs/filters/infinite scroll.
+- Claims about what a page currently shows: wording, feature availability, pricing tiers, UI flows, redirects, embedded data, dates, or generated content.
+- Runtime evidence: network calls, API payloads, console errors, status codes, screenshots, layout/performance observations.
+- Verification of screenshots or visual claims that cannot be proven from plain text.
+
+## Research workflow
+1. Start with webSearch to identify candidate URLs and readUrl for static pages.
+2. Escalate a candidate URL to DevTools when the rendered page is the primary evidence or readUrl is incomplete.
+3. Navigate to the URL, wait for content to settle, then capture a snapshot/text view before interacting.
+4. If needed, click tabs, expand sections, apply filters, scroll, or inspect network calls.
+5. Record a concise note in notes.md: URL, observation, action taken, and why browser evidence was needed.
+6. Create claims from browser observations just like source text. Use the observed URL as the source and mention "browser-observed" in notes.
+
+## Evidence quality
+- Browser observations are primary evidence for "what the page showed at time of access."
+- They are not independent corroboration. Cross-check important factual claims with separate sources.
+- Prefer official pages for product/pricing/status claims, but flag vendor-only evidence as weak unless corroborated.
+- For volatile pages, include access date/time in notes.md and report.md.
+
+## Tool discipline
+- State the exact hypothesis before using DevTools.
+- Use the shortest reliable path: navigate, snapshot, maybe network/console/screenshot, then stop.
+- Do not browse aimlessly. Every browser action should resolve a research question.
+- Never enter secrets, private data, or credentials.
+`
+    },
+    {
+        name: "tool-efficiency",
+        summary: "Tool batching patterns, retry tactics, file hygiene, and common anti-patterns to avoid",
+        content: `# tool-efficiency
+
+## webSearch
+- Always pass 3-5 query variations in the queries array (parallel fetch, same latency as one).
+- Use short noun phrases, not full sentences.
+- Set retries: 2 for flaky searches.
+
+## readUrl
+- Target the specific article or paper page, not the site homepage.
+- PubMed: use the /articles/PMC… URL for full text where available.
+- If a URL 404s or times out, try: search for the title, or try an alternate domain.
+- Do not re-read a URL you already read in this session.
+
+## writeFile / bash
+- Before writing, check what exists: bash \`cat filename 2>/dev/null | head -10\`
+- Write complete files in one call; never partial appends to JSONL.
+- sources.jsonl strict rules: one compact JSON per line, no literal newlines in strings,
+  no trailing commas. Write the entire file at once using writeFile.
+
+## createClaim / verifyClaim
+- Call createClaim right after reading each source, not in a batch at the end.
+- Use a consistent ID scheme: claim_001, claim_002, … or topic-prefixed: claim_cognition_001.
+- Run all verifyClaim calls together after all claims are recorded.
+
+## Narration discipline
+- One line before each tool call: say what you're doing and why.
+- Do not repeat a tool call that already succeeded in this session.
+- Check notes.md with bash \`cat notes.md\` before re-researching a topic.
+
+## Anti-patterns
+- ✗ Searching the same query multiple times without changing terms.
+- ✗ Reading a homepage hoping it contains the article text.
+- ✗ Writing report.md before claims are verified.
+- ✗ Omitting sources.jsonl or writing it with multiline string values.
+`
+    }
+];
+export const SKILL_NAMES = SKILLS.map(s => s.name);
+/** Markdown bullet list of skill names + summaries, embedded directly in the agent system prompt. */
+export const SKILL_CATALOG = SKILLS.map(s => `- ${s.name}: ${s.summary}`).join("\n");
+export function getSkill(name) {
+    return SKILLS.find(s => s.name === name);
+}