feat(phases 2-7): MCP tools, resources, transport, agent skills, EventBus SSE

.claude/skills/literature-review/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: literature-review
+description: This skill should be used when the user asks to "do a literature review",
+  "survey papers on a topic", "search and summarize research on X", "find papers about
+  attention mechanisms", "systematic review of the literature", "what papers exist on Y",
+  or wants a multi-step workflow to search, filter by relevance, score quality, and
+  summarize academic papers using PaperBot MCP tools.
+tools:
+  - paper_search
+  - relevance_assess
+  - paper_judge
+  - paper_summarize
+  - export_to_obsidian
+  - save_to_memory
+---
+
+# Literature Review Workflow
+
+Conduct a systematic literature review: search, filter by relevance, judge quality,
+summarize top papers, and save findings to memory.
+
+## Workflow
+
+### Step 1: Search for papers
+
+Call `paper_search` with the research question or topic.
+
+- Parameters: `query` (required), `max_results` (default 10; use 20–50 for broad surveys),
+  `sources` (optional; omit for all sources, or specify `["arxiv", "semantic_scholar"]`)
+- Returns: list of paper dicts with `title`, `abstract`, `authors`, `year`, `venue`,
+  `arxiv_id`, `doi`
+
+### Step 2: Filter by relevance
+
+For each paper, call `relevance_assess` with `title`, `abstract`, and the same `query`.
+
+- Parameters: `title`, `abstract`, `query`, `keywords` (optional comma-separated terms)
+- Returns: dict with `score` (0–100) and `reason`
+- Suggested threshold: discard papers with `score` below 40
+- If `degraded=True`, token-overlap scoring is used (less accurate but functional)
+
+### Step 3: Judge quality of relevant papers
+
+For papers above the relevance threshold, call `paper_judge`.
+
+- Parameters: `title`, `abstract`, `full_text` (optional), `rubric` (default `"default"`;
+  pass the research question for context-aware judging)
+- Returns: dimension scores (1–5), `overall_score`, `recommendation`
+  (`must_read` / `worth_reading` / `skim` / `skip`)
+- Prioritize papers with `must_read` and `worth_reading` recommendations
+
+### Step 4: Summarize top papers
+
+Call `paper_summarize` for papers recommended as `must_read` or `worth_reading`.
+
+- Parameters: `title`, `abstract`
+- Returns: dict with `summary` key (concise string)
+- If `degraded=True`, generate a manual summary from the abstract text
+
+### Step 5: Export to Obsidian (optional)
+
+Call `export_to_obsidian` for papers to save as permanent Obsidian notes.
+
+- Parameters: `title`, `abstract`, `authors` (list), `year`, `venue`, `arxiv_id`, `doi`
+  (provide whichever identifiers are available)
+- Returns: dict with `markdown` key — YAML-frontmattered note ready to write to vault
+
+### Step 6: Save synthesis to memory
+
+Call `save_to_memory` with a synthesis of findings across all reviewed papers.
+
+- Parameters: `content` (synthesis text), `kind` (`"note"` for general observations,
+  `"hypothesis"` for research directions), `user_id` (default `"default"`),
+  `scope_type` (`"global"` unless scoping to a specific research track),
+  `scope_id` (required if `scope_type="track"`), `confidence` (0.0–1.0)
+- Returns: dict with `created` or `skipped` status
+
+## Degraded Mode
+
+`paper_judge`, `paper_summarize`, and `relevance_assess` require a configured LLM API key.
+`paper_search` works without LLM and returns raw search results in all cases.
+
+When any LLM-backed tool returns `degraded=True`:
+- The response also contains an `error` key describing the issue
+- Set `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` and restart the MCP server
+- In degraded mode, proceed with `paper_search` results only; skip Steps 2–4
+
+## Notes
+
+- For broad surveys (>30 papers), consider running `relevance_assess` in bulk before
+  `paper_judge` to reduce LLM calls
+- Use `rubric="reproducibility"` in `paper_judge` if the review goal is identifying
+  reproducible papers for implementation
+- The `export_to_obsidian` step is optional — skip it if the user has not set up an
+  Obsidian vault or does not need persistent notes

.claude/skills/paper-reproduction/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: paper-reproduction
+description: This skill should be used when the user asks to "reproduce a paper",
+  "implement paper code", "paper2code", "replicate research results", "run experiment
+  from paper", "implement the algorithm from this paper", or wants to locate, understand,
+  and plan implementation of a specific academic paper using PaperBot MCP tools.
+tools:
+  - paper_search
+  - paper_judge
+  - paper_summarize
+  - export_to_obsidian
+  - save_to_memory
+---
+
+# Paper Reproduction Workflow
+
+Reproduce or implement a paper: locate it, assess reproducibility, understand its
+contributions, save an implementation plan, and export a paper note.
+
+## Workflow
+
+### Step 1: Find the paper
+
+Call `paper_search` with the paper title, topic, or known identifier.
+
+- Parameters: `query` (required; include ArXiv ID or DOI if known for direct lookup),
+  `max_results` (default 10; use 3–5 for a known paper to minimize noise)
+- Returns: list of paper dicts with `title`, `abstract`, `authors`, `year`, `venue`,
+  `arxiv_id`, `doi`
+- Select the most specific match if multiple results are returned
+
+### Step 2: Judge reproducibility
+
+Call `paper_judge` with `rubric="reproducibility"` to assess implementation feasibility.
+
+- Parameters: `title`, `abstract`, `full_text` (optional; include if available for
+  richer analysis), `rubric="reproducibility"`
+- Returns: dimension scores (1–5) including `rigor`, `clarity`, `novelty`, `reproducibility`,
+  `overall_score`, and `recommendation`
+- Favorable signals: high `rigor` and `clarity` scores
+- Unfavorable signals: low `clarity` score may indicate reproduction difficulty; low
+  `reproducibility` score indicates missing implementation details (pseudocode, datasets)
+
+### Step 3: Summarize paper contributions
+
+Call `paper_summarize` to extract key contributions, methods, and findings.
+
+- Parameters: `title`, `abstract`
+- Returns: dict with `summary` key (concise string covering contributions and approach)
+- Use the summary to inform the implementation plan in Step 4
+
+### Step 4: Save reproduction plan to memory
+
+Call `save_to_memory` with an outline of the planned implementation steps.
+
+- Parameters: `content` (implementation plan text), `kind` (`"project"` for structured
+  plans or `"decision"` for approach decisions), `user_id` (default `"default"`),
+  `scope_type` (`"global"` or `"track"` if this paper belongs to a research track),
+  `scope_id` (track ID if `scope_type="track"`), `confidence` (0.0–1.0)
+- Include: key algorithms to implement, datasets needed, evaluation metrics, dependencies
+
+### Step 5: Export paper note
+
+Call `export_to_obsidian` to create a structured Obsidian note for the paper.
+
+- Parameters: `title`, `abstract`, `authors` (list), `year`, `venue`, `arxiv_id`, `doi`
+  (provide all available identifiers)
+- Returns: dict with `markdown` key — YAML-frontmattered note ready for Obsidian vault
+- The note provides a permanent reference alongside the implementation
+
+## Implementation Guidance
+
+After completing the above workflow, proceed with code implementation using available
+tools (Bash, Write, etc.). The Paper2Code pipeline in PaperBot
+(`src/paperbot/repro/`) provides deeper multi-stage analysis (Planning → Blueprint →
+Environment → Generation → Verification) for complex reproductions requiring the full
+PaperBot backend.
+
+For simpler reproductions:
+1. Use the summary from Step 3 and the plan from Step 4 as starting context
+2. Implement iteratively, checking against paper details in the Obsidian note
+3. Store implementation decisions in memory with `kind="decision"` as the work progresses
+
+## Degraded Mode
+
+`paper_judge` and `paper_summarize` require a configured LLM API key.
+`paper_search` works without LLM.
+
+When LLM-backed tools return `degraded=True`:
+- The response also contains an `error` key describing the issue
+- Set `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` and restart the MCP server
+- In degraded mode, use `paper_search` to locate the paper and proceed to implementation
+  using the raw abstract and metadata; skip Steps 2 and 3

.claude/skills/scholar-monitoring/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: scholar-monitoring
+description: This skill should be used when the user asks to "monitor a scholar",
+  "check researcher activity", "track publications from author X", "follow author Y",
+  "scholar update for Z", "what has researcher X published recently", or wants to
+  retrieve and synthesize a researcher's recent publication activity using PaperBot
+  MCP tools.
+tools:
+  - check_scholar
+  - analyze_trends
+  - save_to_memory
+---
+
+# Scholar Monitoring Workflow
+
+Monitor a researcher's recent publication activity: fetch their profile and papers,
+optionally analyze output trends, and save a monitoring note.
+
+## Workflow
+
+### Step 1: Check scholar activity
+
+Call `check_scholar` with the researcher's name.
+
+- Parameters: `scholar_name` (required; use the researcher's full name as commonly
+  published), `max_papers` (default 10; increase to 20–30 for career-wide coverage)
+- Returns: dict with:
+  - `scholar`: profile dict with `name`, `hIndex`, `citationCount`, `affiliations`,
+    `paperCount`, `url`
+  - `recent_papers`: list of paper dicts (title, abstract, year, venue, citation count)
+  - `candidates`: list of top-3 candidate matches (inspect if the top result is wrong)
+- If `degraded=True`, the scholar was not found on Semantic Scholar or the API is
+  unavailable
+
+### Step 2: Analyze paper trends (optional)
+
+If `recent_papers` is non-empty and the user wants thematic analysis, call `analyze_trends`.
+
+- Parameters: `topic` (use the scholar's name or primary research area as the topic),
+  `papers` (the `recent_papers` list from Step 1)
+- Returns: dict with `trend_analysis` (natural language narrative of the scholar's
+  research focus and evolution)
+- Skip this step if the user only needs raw paper metadata (no LLM API key required
+  for Step 1 alone)
+
+### Step 3: Save monitoring note
+
+Call `save_to_memory` with a summary of the scholar's recent activity.
+
+- Parameters: `content` (monitoring summary — include scholar name, hIndex,
+  recent paper titles, and trend analysis if available), `kind="note"`,
+  `user_id` (default `"default"`), `scope_type="global"`,
+  `confidence` (0.0–1.0; suggest 0.9 for factual publication data)
+- Returns: dict with `created` or `skipped` status
+
+## Note on Scholar Lookup
+
+`check_scholar` searches Semantic Scholar by name. Common issues:
+
+- **Name diacritics:** Names with accents (e.g., "Müller", "Bengio") may need the
+  ASCII variant ("Muller", "Yoshua Bengio") if exact-match fails
+- **New researchers:** Very new researchers may have limited or no Semantic Scholar
+  records — check `paperCount` in the returned profile
+- **Name ambiguity:** The `candidates` field in the response lists the top 3 matches;
+  inspect these if the top result appears to be the wrong person (wrong affiliation,
+  wrong research area)
+- **Name format:** Use "First Last" format; middle names are generally not needed but
+  can help disambiguate common names
+
+## Degraded Mode
+
+`analyze_trends` (Step 2) requires a configured LLM API key. `check_scholar` (Step 1)
+and `save_to_memory` (Step 3) do not require LLM.
+
+When `analyze_trends` returns `degraded=True`:
+- Set `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` and restart the MCP server
+- Skip Step 2 and proceed directly to Step 3 with a summary based on raw paper metadata
+
+When `check_scholar` itself returns `degraded=True`:
+- This indicates the scholar was not found or the Semantic Scholar API is unavailable
+- Try an alternate name spelling or abbreviation
+- Check `candidates` in the response for close matches

.claude/skills/trend-analysis/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: trend-analysis
+description: This skill should be used when the user asks to "analyze trends in a
+  research area", "what is trending in X", "research landscape for topic Y", "topic
+  trend analysis", "emerging themes in machine learning", "what are researchers working
+  on in Z", or wants to survey a field and identify emerging patterns across multiple
+  papers using PaperBot MCP tools.
+tools:
+  - paper_search
+  - analyze_trends
+  - get_research_context
+  - save_to_memory
+---
+
+# Trend Analysis Workflow
+
+Identify research trends across a topic by collecting papers, analyzing patterns, and
+saving a synthesis of emerging themes.
+
+## Workflow
+
+### Step 1: Load research context (optional)
+
+If a research track exists for the topic, call `get_research_context` to retrieve
+existing memories and previously found papers.
+
+- Parameters: `query` (the research topic), `user_id` (default `"default"`),
+  `track_id` (optional; pass if a specific track ID is known)
+- Returns: dict with `papers` (list), `memories` (list), `stage` (workflow stage string)
+- Use the existing memories as context when synthesizing results in Step 4
+- Skip this step if no prior research context exists for the topic
+
+### Step 2: Search for papers
+
+Call `paper_search` with the topic. Use a broader corpus for trend analysis.
+
+- Parameters: `query` (required), `max_results` (use 20–50 for trend analysis — a
+  larger corpus improves trend signal quality), `sources` (optional)
+- Returns: list of paper dicts with `title`, `abstract`, `authors`, `year`, `venue`
+- If `track_id` context was loaded in Step 1, merge the existing papers with new results
+  (deduplicate by `arxiv_id` or `doi`)
+
+### Step 3: Analyze trends
+
+Call `analyze_trends` with the topic and the list of papers from Step 2.
+
+- Parameters: `topic` (the research area string), `papers` (list of paper dicts from
+  `paper_search`; pass the full list for best results)
+- Returns: dict with `trend_analysis` (natural language narrative), `topic`, `paper_count`
+- Check for `degraded=True` — `analyze_trends` requires a configured LLM API key
+
+### Step 4: Save synthesis
+
+Call `save_to_memory` with the trend analysis narrative and any additional observations.
+
+- Parameters: `content` (the `trend_analysis` text from Step 3, optionally enhanced with
+  your own observations), `kind` (`"note"` for factual observations, `"hypothesis"` for
+  directional predictions), `user_id` (default `"default"`),
+  `scope_type` (`"global"` for broad field trends, `"track"` if scoping to a research area),
+  `scope_id` (track ID if `scope_type="track"`), `confidence` (0.0–1.0)
+- Returns: dict with `created` or `skipped` status
+
+## Degraded Mode
+
+`analyze_trends` requires a configured LLM API key. `paper_search` and `get_research_context`
+work without LLM.
+
+When `analyze_trends` returns `degraded=True`:
+- The response also contains an `error` key describing the issue
+- Set `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` and restart the MCP server
+- In degraded mode, present the raw search results grouped by year or venue as a
+  manual trend signal; skip Step 3 or surface the paper list to the user directly
+
+## Notes
+
+- For fast trend snapshots, use `max_results=20` and skip Step 1
+- For deep research landscape maps, use `max_results=50` and integrate prior context
+  from `get_research_context`
+- When analyzing sub-field trends (e.g., "sparse attention mechanisms"), narrow the
+  query rather than broadening `max_results`
+- Multiple calls with different `topic` variants (e.g., "mixture of experts" vs.
+  "sparse expert models") can be combined for a richer landscape view