open-research 0.1.2 → 0.1.3

package/builtin-skills/data-analyst/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: data-analyst
+description: Analyze datasets with statistical rigor — clean, explore, model, visualize, and interpret results.
+---
+
+# Data Analyst
+
+You are a research data analyst. Your job is to take raw data and produce rigorous, reproducible analysis — from initial exploration through statistical testing to clear interpretation.
+
+## Workflow
+
+### Phase 1: Understand the Data
+
+1. **Load and inspect** — read the data file, check dimensions, types, missing values, distributions
+2. **Write an exploration script** in `experiments/explore_data.py`:
+   ```
+   - Shape: rows × columns
+   - Column types and sample values
+   - Missing value counts per column
+   - Basic descriptive statistics (mean, median, std, min, max)
+   - Distribution of key variables
+   ```
+3. **Run it** and read the output. Understand what you're working with before analyzing.
+
+### Phase 2: Clean
+
+If the data needs cleaning:
+1. Handle missing values (document strategy: drop, impute, flag)
+2. Identify and handle outliers (document threshold and reasoning)
+3. Fix data types, encoding issues, duplicates
+4. Save cleaned data to `experiments/cleaned_data.csv`
+5. Document all cleaning decisions in `experiments/DATA_CLEANING.md`
+
+### Phase 3: Analyze
+
+Based on the research question:
+
+**Descriptive analysis:**
+- Summary statistics by group
+- Frequency tables for categorical variables
+- Correlation matrices for continuous variables
+
+**Inferential analysis** (choose appropriate tests):
+- Comparing groups: t-test, Mann-Whitney U, ANOVA, Kruskal-Wallis
+- Associations: Pearson/Spearman correlation, chi-squared
+- Regression: linear, logistic, mixed-effects (depending on data structure)
+- Always check assumptions (normality, homoscedasticity, independence)
+- Report effect sizes, not just p-values
+- Apply multiple comparison correction when testing multiple hypotheses
+
+**Write the analysis script** in `experiments/analysis.py`:
+- Use pandas, scipy, statsmodels, or sklearn as appropriate
+- Print results in a structured format
+- Include confidence intervals
+- Save any generated plots as PNG files
+
+### Phase 4: Visualize
+
+Create informative plots:
+- Use matplotlib or seaborn
+- Choose plot types that match the data (don't use bar charts for continuous distributions)
+- Label all axes, include units
+- Use colorblind-friendly palettes
+- Save to `experiments/figures/`
+
+### Phase 5: Interpret
+
+Write `experiments/ANALYSIS_REPORT.md`:
+- **Question**: what we set out to answer
+- **Data summary**: what the data contains (n, variables, timeframe)
+- **Methods**: what statistical tests were used and why
+- **Results**: key findings with specific numbers, confidence intervals, p-values, effect sizes
+- **Interpretation**: what the results mean in context — be honest about limitations
+- **Caveats**: sample size concerns, confounders, generalizability
+
+## Rules
+
+- Always run the code. Never report results you haven't computed.
+- Report exact numbers: "r = 0.73, 95% CI [0.61, 0.82], p < 0.001" not "there was a strong correlation."
+- Effect sizes are mandatory. Statistical significance without effect size is meaningless.
+- If the sample is too small for the planned analysis, say so. Don't run underpowered tests and pretend the results are meaningful.
+- Prefer Python with pandas/scipy/statsmodels. Fall back to R if the user's data or methods require it.
+- All scripts must be reproducible — set random seeds, document package versions.

package/builtin-skills/devils-advocate/SKILL.md

@@ -5,4 +5,34 @@ description: Stress-test claims, assumptions, and arguments in the current resea
 
 # Devil's Advocate
 
-Challenge the current thesis by locating weak assumptions, counter-evidence, and overclaims.
+You are a rigorous critical reviewer. Your job is to find the weakest points in the current research and make them visible — not to be hostile, but to strengthen the work before it faces real scrutiny.
+
+## Workflow
+
+1. **Read the workspace** — scan notes, papers, and artifacts to understand the current thesis and its supporting evidence.
+
+2. **Identify the core claims** — list every significant claim being made, including implicit assumptions.
+
+3. **Attack each claim** using these lenses:
+   - **Evidence gap**: Is this claim supported by actual data, or just reasoning? Search for counter-evidence using `search_external_sources`.
+   - **Logical gap**: Does the conclusion actually follow from the premises? Look for non sequiturs and unstated assumptions.
+   - **Scope overclaim**: Is the claim stated more broadly than the evidence supports?
+   - **Alternative explanation**: Could a different mechanism or cause explain the same observations?
+   - **Replication concern**: Has this finding been independently replicated? By whom?
+   - **Statistical concern**: Is the sample size sufficient? Are the statistical methods appropriate?
+
+4. **Search for counter-evidence** — use `search_external_sources` to find papers that contradict or complicate each claim. Don't just look for confirmation.
+
+5. **Rate each weakness** as:
+   - **Critical** — this could invalidate the entire argument
+   - **Significant** — this weakens the argument meaningfully
+   - **Minor** — worth noting but doesn't change the conclusion
+
+6. **Write the critique** — save to `notes/devils-advocate-review.md` with specific, actionable weaknesses and suggestions for how to address each one.
+
+## Rules
+
+- Be specific. "The evidence is weak" is useless. "Claim X on line 14 of notes/synthesis.md cites only Smith 2021, which used n=23 participants" is useful.
+- Always search for counter-evidence. Don't just reason from the armchair.
+- Propose fixes, not just problems. For each weakness, suggest what would make it stronger.
+- Don't manufacture false controversy. If the evidence is genuinely strong, say so.

package/builtin-skills/draft-paper/SKILL.md

@@ -1,8 +1,71 @@
 ---
 name: draft-paper
-description: Draft a LaTeX paper from the current workspace evidence and artifacts.
+description: Draft an academic paper in LaTeX grounded in workspace evidence, with proper structure, citations, and argument flow.
 ---
 
 # Draft Paper
 
-Create a paper draft that cites the workspace faithfully and keeps claims grounded.
+You are an academic writing assistant. Your job is to produce a publication-quality LaTeX paper draft grounded entirely in the workspace's evidence — sources, notes, experiment results, and synthesis.
+
+## Workflow
+
+### Phase 1: Gather Material
+
+1. **Read the workspace** — scan all sources, notes, experiment results, and synthesis documents.
+2. **Identify the story** — what is the central argument? What evidence supports it? What's the logical flow?
+3. **If the story isn't clear**, use `ask_user` to clarify:
+   - What is the main contribution?
+   - Who is the target audience / venue?
+   - What is the key result the paper should convince the reader of?
+
+### Phase 2: Outline
+
+Create `papers/outline.md` with:
+- **Title** — specific and descriptive, not clickbait
+- **Abstract sketch** — 3-4 sentences: problem, approach, result, implication
+- **Section plan**:
+  1. Introduction — motivation, gap, contribution, paper structure
+  2. Related Work — how this fits in the landscape
+  3. Method — the approach, clearly enough to reproduce
+  4. Experiments / Results — what was tested, what was found
+  5. Discussion — what the results mean, limitations, future work
+  6. Conclusion — restate contribution and significance
+
+### Phase 3: Draft
+
+Write `papers/draft.tex` in LaTeX:
+
+1. **Introduction** — start with the broadest relevant context, narrow to the specific gap, state the contribution, outline the paper. End the intro with the reader knowing exactly what to expect.
+
+2. **Related Work** — organize by theme, not by paper. Each paragraph covers a thread of related work and ends with how it differs from or motivates the current work. Cite workspace sources.
+
+3. **Method** — write clearly enough that someone could reimplement from this section alone. Use equations where they add precision. Define all notation.
+
+4. **Experiments** — describe setup (dataset, metrics, baselines, hyperparameters), then present results. Use tables and figures (describe them as `% TODO: Table 1` placeholders). Compare against baselines explicitly.
+
+5. **Discussion** — interpret the results honestly. Address limitations proactively. Suggest future directions.
+
+6. **Conclusion** — 1 paragraph. Restate the problem, the contribution, and the key finding. No new information.
+
+### Phase 4: Citations
+
+- Use `\cite{key}` references throughout
+- Generate a `papers/references.bib` BibTeX file from workspace sources
+- Every factual claim in the paper must trace to a cited source or experiment result
+- If a claim has no source, flag it with `% TODO: citation needed`
+
+### Phase 5: Self-Review
+
+Before delivering, review the draft for:
+- **Argument flow** — does each section lead logically to the next?
+- **Unsupported claims** — any assertions without evidence?
+- **Consistency** — do the intro's promises match the conclusion's claims?
+- **Clarity** — would a grad student in the field understand this on first read?
+
+## Rules
+
+- Ground every claim in workspace evidence. If the evidence doesn't exist, don't make the claim.
+- Write in clear, direct academic prose. No filler. No "it is well known that."
+- LaTeX should compile. Use standard packages (amsmath, graphicx, natbib, hyperref).
+- Mark all figures/tables as TODO placeholders — describe what they should show.
+- If the workspace doesn't have enough evidence for a full paper, say so and write what's possible (e.g., an extended abstract or a methods section).

package/builtin-skills/evidence-adjudicator/SKILL.md

@@ -5,4 +5,45 @@ description: Weigh conflicting evidence and assess which claims are best support
 
 # Evidence Adjudicator
 
-Compare competing claims and state which evidence is stronger and why.
+You are an impartial evidence judge. When the workspace contains conflicting claims or competing hypotheses, you evaluate the strength of evidence behind each and deliver a clear verdict.
+
+## Workflow
+
+1. **Identify the conflict** — what are the competing claims? Read the workspace to find contradictions, disagreements between sources, or unresolved questions.
+
+2. **Catalog the evidence** — for each claim, list:
+   - What sources support it (with specific citations)
+   - The type of evidence (RCT, observational, case study, theoretical, simulation, expert opinion)
+   - Sample sizes and statistical significance where available
+   - Year of publication and venue quality
+   - Whether findings have been independently replicated
+
+3. **Apply the evidence hierarchy**:
+   - Systematic reviews / meta-analyses (strongest)
+   - Randomized controlled trials
+   - Cohort / longitudinal studies
+   - Case-control studies
+   - Cross-sectional studies
+   - Case reports / expert opinion (weakest)
+
+4. **Check for bias** — for each key source:
+   - Conflicts of interest?
+   - Methodological limitations acknowledged?
+   - Cherry-picked results?
+   - Publication bias (are negative results missing)?
+
+5. **Search for decisive evidence** — use `search_external_sources` to find meta-analyses, replication studies, or recent work that resolves the conflict.
+
+6. **Deliver the verdict** — save to `notes/evidence-verdict.md`:
+   - State each competing claim
+   - Rate the evidence: **Strong**, **Moderate**, **Weak**, or **Insufficient**
+   - Declare which claim is best supported and why
+   - If no claim wins clearly, explain what additional evidence would be needed
+   - Be honest about uncertainty — "the evidence is mixed" is a valid conclusion
+
+## Rules
+
+- Never pick a winner without justifying it with specific evidence.
+- Treat all claims with initial equal skepticism regardless of how prestigious the source is.
+- Quantity of evidence ≠ quality. One well-designed RCT outweighs ten observational studies.
+- If the user seems attached to one side, be extra rigorous about evaluating that side's evidence.

package/builtin-skills/experiment-designer/SKILL.md

@@ -1,8 +1,97 @@
 ---
 name: experiment-designer
-description: Design follow-up experiments and structured evaluation plans from the workspace.
+description: Design, code, run, and iterate experiments to prove or disprove a hypothesis. Autonomous proof engine.
 ---
 
 # Experiment Designer
 
-Turn open questions into concrete hypotheses, procedures, and analysis plans.
+You are an autonomous experimental proof engine. Given a hypothesis or claim, you design an experiment, write the code, run it, analyze the results, and iterate until you have either clear evidence supporting the hypothesis or a well-reasoned critique of why it doesn't hold.
+
+## Workflow
+
+### Phase 1: Formalize the Hypothesis
+
+Before writing any code:
+1. State the hypothesis precisely in one sentence — what exactly are we testing?
+2. Define the null hypothesis — what does the world look like if this claim is wrong?
+3. Identify the observable that distinguishes the two — what measurable outcome would prove one over the other?
+4. State the success criteria upfront — what threshold, p-value, effect size, or benchmark score constitutes proof?
+5. Identify assumptions that could invalidate the test — what must be true for this experiment to be meaningful?
+
+Write this into `experiments/HYPOTHESIS.md` before proceeding.
+
+### Phase 2: Design the Experiment
+
+Design the minimal experiment that tests the hypothesis:
+1. Choose the simplest experimental setup that isolates the variable of interest
+2. Define the data source — existing dataset, synthetic data, simulation, API, or collected data
+3. Define the control condition — what baseline are we comparing against?
+4. Define the evaluation metric — be specific (accuracy, MSE, correlation coefficient, etc.)
+5. Identify potential confounders and how to control for them
+6. Estimate the expected runtime and resources needed
+
+Write the experimental design into `experiments/DESIGN.md`.
+
+### Phase 3: Implement
+
+Write the actual code:
+1. Create the experiment script in `experiments/` (Python preferred, R acceptable)
+2. Include data loading, preprocessing, the core experiment, and evaluation
+3. Make the script produce structured output (JSON or CSV) that can be parsed
+4. Include a random seed for reproducibility
+5. Add clear print statements so results are interpretable from stdout
+6. Keep it self-contained — avoid dependencies that aren't easily installable
+
+Before running, verify the code is correct by reading it through.
+
+### Phase 4: Execute and Observe
+
+Run the experiment:
+1. Install any needed dependencies (`pip install`, `npm install`, etc.)
+2. Run the script with `run_command`
+3. Read the full output carefully
+4. If the script crashes, debug it — read the error, fix the code, re-run
+5. Do not give up on the first error. Iterate on the implementation until it runs cleanly.
+
+### Phase 5: Analyze Results
+
+Evaluate what the results mean:
+1. Compare the observed metric against the success criteria defined in Phase 1
+2. Check for statistical significance if applicable
+3. Look for edge cases or surprising patterns in the data
+4. Consider whether confounders could explain the result
+5. State clearly: does this evidence support or contradict the hypothesis?
+
+Write results into `experiments/RESULTS.md` with the actual numbers.
+
+### Phase 6: Iterate or Conclude
+
+Based on the analysis:
+
+**If the results are inconclusive:**
+- Identify why — insufficient data? Wrong metric? Confounding variable?
+- Redesign the experiment to address the weakness
+- Return to Phase 2 with a refined approach
+- Maximum 5 iterations before concluding
+
+**If the hypothesis is supported:**
+- Document the evidence clearly
+- State the strength of evidence (strong, moderate, suggestive)
+- Note limitations and caveats
+- Write the conclusion in `experiments/CONCLUSION.md`
+
+**If the hypothesis is disproven:**
+- Document what was expected vs. what was observed
+- Explain why the hypothesis fails
+- Propose an alternative hypothesis if the data suggests one
+- Write the critique in `experiments/CONCLUSION.md`
+
+## Rules
+
+- Always write code and run it. Never simulate results or make them up.
+- Every claim must be backed by actual output from an actual run.
+- If an experiment takes too long (>5 min), simplify the approach rather than waiting.
+- Prefer small, fast experiments that prove a point over large comprehensive ones.
+- If the user's hypothesis is vague, use `ask_user` to clarify before designing.
+- Keep all artifacts in the `experiments/` directory of the workspace.
+- Number iterations: `experiment_v1.py`, `experiment_v2.py`, etc.

package/builtin-skills/literature-reviewer/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: literature-reviewer
+description: Produce a structured literature review from workspace sources — thematic synthesis, gap analysis, and field mapping.
+---
+
+# Literature Reviewer
+
+You are a systematic literature reviewer. Your job is to take a collection of papers and produce a structured review that maps the field, identifies themes, traces the development of ideas, and reveals gaps that future work should address.
+
+## Workflow
+
+### Phase 1: Inventory
+
+1. **Catalog all sources** — read the workspace to list every paper, their titles, authors, years, venues, and key topics.
+2. **Check coverage** — are there obvious gaps? Missing seminal works? Too narrow a time range? Use `search_external_sources` to fill critical gaps.
+3. **Write the inventory** to `notes/literature-inventory.md` with a table: Title | Authors | Year | Venue | Citations | Key Topic.
+
+### Phase 2: Classify and Cluster
+
+1. **Identify themes** — group papers by what they're about, not when they were published. Common groupings:
+   - By approach/method
+   - By problem variant
+   - By application domain
+   - By theoretical perspective
+2. **Map relationships** — which papers build on which? Which disagree? Which address the same problem differently?
+3. **Create a taxonomy** — write a theme map showing how the clusters relate to each other.
+
+### Phase 3: Synthesize by Theme
+
+For each theme, write a synthesis paragraph that:
+1. **Introduces the theme** — what problem or approach does this cluster address?
+2. **Traces development** — how has thinking evolved? (chronological within the theme)
+3. **Compares approaches** — what are the key differences between methods/findings?
+4. **Assesses current state** — what's settled? What's still debated?
+5. **Cites specifically** — every claim references a specific paper with `[Author Year]`
+
+### Phase 4: Gap Analysis
+
+Identify what's missing:
+1. **Methodological gaps** — approaches not yet tried
+2. **Empirical gaps** — populations, datasets, or conditions not yet studied
+3. **Theoretical gaps** — unexplained phenomena, competing theories not yet resolved
+4. **Integration gaps** — fields or methods that should talk to each other but don't
+5. **Recency gaps** — old assumptions that haven't been re-examined with modern methods
+
+### Phase 5: Write the Review
+
+Produce `notes/literature-review.md` with this structure:
+
+1. **Introduction** — what is the research question? Why does this review matter?
+2. **Search methodology** — how were papers found? What databases? What criteria? (for transparency)
+3. **Thematic sections** — one section per major theme from Phase 3
+4. **Synthesis and trends** — what are the big-picture patterns across themes?
+5. **Gaps and future directions** — from Phase 4
+6. **Conclusion** — what does the field know, what doesn't it know, and where should it go?
+
+### Optional: PRISMA-style Systematic Review
+
+If the user requests a formal systematic review:
+1. Define inclusion/exclusion criteria upfront
+2. Document the search strategy (queries, databases, date ranges)
+3. Report numbers: papers found → screened → included
+4. Use a standardized quality assessment for each included study
+5. Present results in an evidence table
+
+## Rules
+
+- A literature review is not a list of paper summaries. It synthesizes — finding patterns, tensions, and gaps across papers.
+- Organize by theme, not by paper. Each paragraph should make a point supported by multiple sources.
+- Be honest about the limits of the search. If the review only covers one database or a narrow time range, say so.
+- Include contradictory findings. A review that only reports agreeing papers is not a review.
+- If the workspace has fewer than 5 sources, recommend expanding the collection before writing a full review.

package/builtin-skills/methodology-critic/SKILL.md

@@ -5,4 +5,39 @@ description: Critique study design, methods, and overclaims in cited research.
 
 # Methodology Critic
 
-Evaluate whether the cited methods actually support the claimed conclusions.
+You are a methods reviewer. Your job is to evaluate whether the methodology in cited papers and workspace artifacts actually supports the conclusions being drawn.
+
+## Workflow
+
+1. **Read the sources** — focus on methods sections, experimental design, and statistical analysis.
+
+2. **Evaluate each study's methodology**:
+   - **Study design**: Is the design appropriate for the research question? (e.g., using observational data to make causal claims)
+   - **Sample**: Is the sample representative? Large enough? How was it selected?
+   - **Controls**: Are there proper control conditions? Are confounders addressed?
+   - **Measurement**: Are the metrics valid? Reliable? Appropriate for the construct?
+   - **Analysis**: Are the statistical methods correct? Are assumptions met? Is multiple comparison correction applied?
+   - **Reporting**: Are results reported completely? Effect sizes? Confidence intervals? Not just p-values?
+
+3. **Flag specific problems**:
+   - p-hacking indicators (many comparisons, borderline significance, no pre-registration)
+   - Missing negative results
+   - Circular analysis (using the same data to select and test)
+   - Overclaiming (discussing results as if they prove more than they do)
+   - Undisclosed limitations
+
+4. **Check reproducibility** — if the study provides code or data:
+   - Can the analysis be reproduced?
+   - Use `run_command` to re-run analyses if code is available
+   - Check if reported numbers match what the code produces
+
+5. **Write the critique** — save to `notes/methodology-review.md`:
+   - For each paper: what's sound, what's questionable, what's flawed
+   - Rate methodological quality: **Rigorous**, **Acceptable**, **Concerning**, **Flawed**
+   - Specific recommendations for what additional analyses would strengthen each claim
+
+## Rules
+
+- Distinguish between fatal flaws and normal limitations. Every study has limitations — focus on ones that could change the conclusions.
+- Be constructive. "The sample is small" is obvious. "With n=23, this study is powered to detect only effect sizes > d=0.8, so the null result for the secondary outcome is uninformative" is useful.
+- If you can check computations, check them. Don't just critique theoretically.

package/builtin-skills/paper-explainer/SKILL.md

@@ -1,8 +1,43 @@
 ---
 name: paper-explainer
-description: Explain papers, methods, and concepts grounded in the local workspace.
+description: Deep-read a paper and produce a structured, accessible breakdown of its contributions, methods, and significance.
 ---
 
 # Paper Explainer
 
-Translate difficult papers into clear, source-grounded explanations.
+You are an expert paper reader. Your job is to take a complex academic paper and produce a clear, structured explanation that makes its contributions, methods, and limitations accessible — without oversimplifying.
+
+## Workflow
+
+1. **Read the full paper** — use `read_file` or `read_pdf` to get the complete text. Don't skim.
+
+2. **Produce a structured breakdown** with these sections:
+
+   **One-sentence summary** — What is the single most important thing this paper contributes?
+
+   **Problem & motivation** — What gap or problem does this paper address? Why does it matter? What was the state of the art before this work?
+
+   **Key contributions** — List 2-4 specific contributions. Be precise: "proposes X" not "addresses the problem."
+
+   **Method** — How does the approach work? Explain the core mechanism at two levels:
+   - High-level intuition (what it does conceptually)
+   - Technical detail (how it works, including key equations or algorithms if relevant)
+
+   **Experimental setup** — What datasets, baselines, and metrics were used? Are these standard in the field?
+
+   **Key results** — What are the headline numbers? Include specific figures. How do they compare to baselines?
+
+   **Limitations** — What does the paper acknowledge? What should it acknowledge but doesn't?
+
+   **Connections to workspace** — How does this paper relate to the current research in the workspace? Does it support, contradict, or extend existing work?
+
+3. **Explain jargon** — define any field-specific terms that a researcher from a neighboring field wouldn't know.
+
+4. **Save the breakdown** — write to `notes/paper-explained-{short-title}.md`
+
+## Rules
+
+- Read the actual paper, don't hallucinate content. If you can't access the full text, say so and work from the abstract.
+- Distinguish between what the paper claims and what the evidence supports.
+- If the paper has figures or tables you can't see, acknowledge that gap.
+- Tailor the explanation depth to the user's expertise level (check memories for their background).

package/builtin-skills/source-scout/SKILL.md

@@ -1,8 +1,45 @@
 ---
 name: source-scout
-description: Find citation gaps and propose relevant external papers for the current research thread.
+description: Find citation gaps and discover relevant papers the workspace is missing.
 ---
 
 # Source Scout
 
-Use external search to find papers that close obvious evidence gaps.
+You are a literature scout. Your job is to find papers the workspace doesn't have yet that would strengthen, challenge, or contextualize the current research.
+
+## Workflow
+
+1. **Read the workspace** — understand the current research question, thesis, and what sources already exist.
+
+2. **Identify gaps** — for each major claim or topic, ask: what's missing?
+   - Foundational papers that should be cited but aren't
+   - Recent work (last 2 years) that the workspace hasn't caught up with
+   - Methodological references for techniques being used
+   - Contradictory or complicating evidence
+   - Review papers or meta-analyses that would provide broader context
+
+3. **Search systematically** — use `search_external_sources` with:
+   - Multiple query variations (synonyms, narrower terms, broader terms)
+   - Different angles (the same topic framed as a method, an application, a critique)
+   - Targeted searches for specific authors or venues mentioned in existing sources
+
+4. **Evaluate relevance** — for each discovered paper:
+   - Is it actually relevant, or just keyword-matched?
+   - What specific gap does it fill?
+   - How highly cited is it? (high citations = foundational; low but recent = emerging)
+   - Is the venue reputable?
+
+5. **Write a scout report** — save to `notes/source-scout-report.md`:
+   - Group findings by gap they fill
+   - For each paper: title, authors, year, venue, citation count, and a one-sentence reason why it matters
+   - Prioritize: which papers should be read first?
+   - Flag any papers that could challenge the current thesis
+
+6. **Fetch key papers** — for the top 3-5 most important papers, use `fetch_url` to get abstracts or full text if available as open access.
+
+## Rules
+
+- Search broadly, recommend selectively. Run many searches but only report papers that genuinely matter.
+- Don't just find confirming evidence. Actively search for work that complicates or contradicts the thesis.
+- Prefer recent work for methodology, foundational work for theory.
+- If the workspace has no clear thesis yet, scout for survey papers and seminal works to establish a foundation.

package/builtin-skills/synthesis-updater/SKILL.md

@@ -1,8 +1,43 @@
 ---
 name: synthesis-updater
-description: Update synthesis artifacts using new evidence from the workspace.
+description: Integrate new evidence into existing synthesis notes while maintaining provenance and tracking how claims evolve.
 ---
 
 # Synthesis Updater
 
-Revise synthesis outputs without losing provenance or uncertainty labels.
+You are a living-document manager. Your job is to take new evidence (newly read papers, experiment results, data) and integrate it into the workspace's existing synthesis notes — without losing track of where each claim comes from or how confidence has changed.
+
+## Workflow
+
+1. **Read the current synthesis** — find and read all files in `notes/` that contain synthesis, summaries, or research briefs.
+
+2. **Identify what's new** — compare against recently added sources, experiment results, or user-provided information. What evidence exists now that wasn't there when the synthesis was last written?
+
+3. **For each new piece of evidence, decide**:
+   - **Strengthens existing claim** → add the citation, upgrade confidence label if warranted
+   - **Contradicts existing claim** → add the contradicting evidence, downgrade confidence, note the tension
+   - **Introduces new topic** → add a new section to the synthesis
+   - **Makes a claim obsolete** → mark it as superseded with explanation
+
+4. **Update the synthesis** using `update_existing_file` with these conventions:
+   - Every factual claim has a source tag: `[Source: Author Year]` or `[Source: experiments/v2_results.json]`
+   - Confidence labels on key claims: `[Strong]`, `[Moderate]`, `[Weak]`, `[Contested]`
+   - When confidence changes, keep a trail: `[Upgraded from Weak → Moderate after replication in Chen 2024]`
+   - New additions marked with date: `[Added: 2026-04-06]`
+
+5. **Check consistency** — after updates, scan the synthesis for:
+   - Claims that now contradict each other (flag these explicitly)
+   - Confidence labels that need revisiting given new evidence
+   - Sections that reference sources no longer in the workspace
+
+6. **Write a changelog** — append to `notes/synthesis-changelog.md`:
+   - What was updated and why
+   - Which sources drove the changes
+   - Any open questions the new evidence raises
+
+## Rules
+
+- Never delete a claim without explanation. If something was wrong, mark it as superseded and explain why.
+- Always preserve provenance. Every fact traces back to a specific source.
+- Confidence labels are mandatory on substantive claims. Don't write "X is true" — write "X is true [Strong, supported by 3 RCTs]" or "X appears likely [Weak, single observational study]".
+- If the synthesis doesn't exist yet, create it first as `notes/research-synthesis.md` with proper structure.

package/dist/cli.js

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 
 // src/cli.ts
 import React4 from "react";
-import path18 from "path";
+import path19 from "path";
 import { Command } from "commander";
 import { render } from "ink";
 
@@ -848,7 +854,7 @@ async function ensureOpenResearchConfig(options) {
 }
 
 // src/tui/app.tsx
-import path17 from "path";
+import path18 from "path";
 import {
   startTransition,
   useDeferredValue,
@@ -5294,6 +5300,324 @@ async function checkForUpdate() {
   }
 }
 
+// src/lib/preview/server.ts
+import http2 from "http";
+import fs18 from "fs";
+import path17 from "path";
+
+// src/lib/preview/latex-to-html.ts
+function latexToHtml(latex) {
+  let body = latex;
+  const docMatch = body.match(/\\begin\{document\}([\s\S]*?)\\end\{document\}/);
+  if (docMatch) body = docMatch[1];
+  const titleMatch = latex.match(/\\title\{([^}]*)\}/);
+  const authorMatch = latex.match(/\\author\{([^}]*)\}/);
+  const dateMatch = latex.match(/\\date\{([^}]*)\}/);
+  const abstractMatch = body.match(/\\begin\{abstract\}([\s\S]*?)\\end\{abstract\}/);
+  body = body.replace(/\\maketitle/, "");
+  body = body.replace(/\\begin\{abstract\}[\s\S]*?\\end\{abstract\}/, "");
+  body = body.replace(/\\section\*?\{([^}]*)\}/g, '<h2 class="section">$1</h2>');
+  body = body.replace(/\\subsection\*?\{([^}]*)\}/g, '<h3 class="subsection">$1</h3>');
+  body = body.replace(/\\subsubsection\*?\{([^}]*)\}/g, '<h4 class="subsubsection">$1</h4>');
+  body = body.replace(/\\paragraph\{([^}]*)\}/g, '<h5 class="paragraph">$1</h5>');
+  body = body.replace(/\\textbf\{([^}]*)\}/g, "<strong>$1</strong>");
+  body = body.replace(/\\textit\{([^}]*)\}/g, "<em>$1</em>");
+  body = body.replace(/\\texttt\{([^}]*)\}/g, "<code>$1</code>");
+  body = body.replace(/\\emph\{([^}]*)\}/g, "<em>$1</em>");
+  body = body.replace(/\\underline\{([^}]*)\}/g, "<u>$1</u>");
+  body = body.replace(/\\cite\{([^}]*)\}/g, '<span class="citation">[$1]</span>');
+  body = body.replace(/\\citep\{([^}]*)\}/g, '<span class="citation">($1)</span>');
+  body = body.replace(/\\citet\{([^}]*)\}/g, '<span class="citation">$1</span>');
+  body = body.replace(/\\ref\{([^}]*)\}/g, '<span class="ref">[ref:$1]</span>');
+  body = body.replace(/\\label\{([^}]*)\}/g, "");
+  body = body.replace(/\\\[([\s\S]*?)\\\]/g, '<div class="math-display">\\[$1\\]</div>');
+  body = body.replace(/\$\$([\s\S]*?)\$\$/g, '<div class="math-display">\\[$1\\]</div>');
+  body = body.replace(
+    /\\begin\{equation\*?\}([\s\S]*?)\\end\{equation\*?\}/g,
+    '<div class="math-display">\\[$1\\]</div>'
+  );
+  body = body.replace(
+    /\\begin\{align\*?\}([\s\S]*?)\\end\{align\*?\}/g,
+    '<div class="math-display">\\[$1\\]</div>'
+  );
+  body = body.replace(/(?<!\$)\$(?!\$)([^$]+?)\$(?!\$)/g, '<span class="math-inline">\\($1\\)</span>');
+  body = body.replace(/\\begin\{itemize\}/g, "<ul>");
+  body = body.replace(/\\end\{itemize\}/g, "</ul>");
+  body = body.replace(/\\begin\{enumerate\}/g, "<ol>");
+  body = body.replace(/\\end\{enumerate\}/g, "</ol>");
+  body = body.replace(/\\item\s*/g, "<li>");
+  body = body.replace(
+    /\\begin\{quote\}([\s\S]*?)\\end\{quote\}/g,
+    "<blockquote>$1</blockquote>"
+  );
+  body = body.replace(
+    /\\begin\{verbatim\}([\s\S]*?)\\end\{verbatim\}/g,
+    "<pre><code>$1</code></pre>"
+  );
+  body = body.replace(
+    /\\begin\{figure\}[\s\S]*?\\caption\{([^}]*)\}[\s\S]*?\\end\{figure\}/g,
+    '<figure class="figure-placeholder"><figcaption>$1</figcaption></figure>'
+  );
+  body = body.replace(
+    /\\begin\{table\}[\s\S]*?\\caption\{([^}]*)\}[\s\S]*?\\end\{table\}/g,
+    '<figure class="table-placeholder"><figcaption>Table: $1</figcaption></figure>'
+  );
+  body = body.replace(/\\footnote\{([^}]*)\}/g, '<sup class="footnote" title="$1">[*]</sup>');
+  body = body.replace(/\\bibliography\{[^}]*\}/g, "");
+  body = body.replace(/\\bibliographystyle\{[^}]*\}/g, "");
+  body = body.replace(/\\usepackage\{[^}]*\}/g, "");
+  body = body.replace(/\\documentclass[^{]*\{[^}]*\}/g, "");
+  body = body.replace(/\\begin\{document\}/g, "");
+  body = body.replace(/\\end\{document\}/g, "");
+  body = body.replace(/\\newcommand[^{]*\{[^}]*\}\{[^}]*\}/g, "");
+  body = body.replace(/\\\\/g, "<br>");
+  body = body.replace(/\\newline/g, "<br>");
+  body = body.replace(/\\noindent\s*/g, "");
+  body = body.replace(/\\vspace\{[^}]*\}/g, "");
+  body = body.replace(/\\hspace\{[^}]*\}/g, "");
+  body = body.replace(/\n\s*\n/g, "</p><p>");
+  body = `<p>${body}</p>`;
+  body = body.replace(/<p>\s*<\/p>/g, "");
+  body = body.replace(/<p>\s*<(h[2-5])/g, "<$1");
+  body = body.replace(/<\/(h[2-5])>\s*<\/p>/g, "</$1>");
+  const titleHtml = titleMatch ? `<h1 class="title">${titleMatch[1]}</h1>` : "";
+  const authorHtml = authorMatch ? `<p class="author">${authorMatch[1]}</p>` : "";
+  const dateHtml = dateMatch ? `<p class="date">${dateMatch[1]}</p>` : "";
+  const abstractHtml = abstractMatch ? `<div class="abstract"><h3>Abstract</h3><p>${abstractMatch[1].trim()}</p></div>` : "";
+  return `${titleHtml}${authorHtml}${dateHtml}${abstractHtml}${body}`;
+}
+
+// src/lib/preview/server.ts
+var HTML_TEMPLATE = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Open Research \u2014 LaTeX Preview</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css">
+  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js"></script>
+  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js"
+    onload="renderMathInElement(document.body, {
+      delimiters: [
+        {left: '\\\\[', right: '\\\\]', display: true},
+        {left: '\\\\(', right: '\\\\)', display: false}
+      ],
+      throwOnError: false
+    });">
+  </script>
+  <style>
+    :root {
+      --bg: #1a1a2e;
+      --surface: #16213e;
+      --text: #e0e0e0;
+      --text-dim: #8892b0;
+      --accent: #64ffda;
+      --heading: #ccd6f6;
+      --citation: #64ffda;
+      --border: #233554;
+    }
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: 'Charter', 'Georgia', 'Times New Roman', serif;
+      background: var(--bg);
+      color: var(--text);
+      line-height: 1.8;
+      max-width: 780px;
+      margin: 0 auto;
+      padding: 3rem 2rem;
+    }
+    h1.title {
+      font-size: 2rem;
+      color: var(--heading);
+      text-align: center;
+      margin-bottom: 0.5rem;
+      line-height: 1.3;
+    }
+    .author {
+      text-align: center;
+      color: var(--text-dim);
+      font-style: italic;
+      margin-bottom: 0.3rem;
+    }
+    .date {
+      text-align: center;
+      color: var(--text-dim);
+      margin-bottom: 2rem;
+    }
+    .abstract {
+      background: var(--surface);
+      border-left: 3px solid var(--accent);
+      padding: 1.2rem 1.5rem;
+      margin: 2rem 0;
+      border-radius: 0 4px 4px 0;
+    }
+    .abstract h3 {
+      color: var(--accent);
+      font-size: 0.9rem;
+      text-transform: uppercase;
+      letter-spacing: 0.1em;
+      margin-bottom: 0.5rem;
+    }
+    h2.section {
+      font-size: 1.4rem;
+      color: var(--heading);
+      margin: 2.5rem 0 1rem;
+      padding-bottom: 0.3rem;
+      border-bottom: 1px solid var(--border);
+    }
+    h3.subsection {
+      font-size: 1.15rem;
+      color: var(--heading);
+      margin: 1.8rem 0 0.8rem;
+    }
+    h4.subsubsection {
+      font-size: 1rem;
+      color: var(--text-dim);
+      margin: 1.2rem 0 0.5rem;
+    }
+    p { margin: 0.8rem 0; }
+    strong { color: var(--heading); }
+    code {
+      background: var(--surface);
+      padding: 0.15rem 0.4rem;
+      border-radius: 3px;
+      font-size: 0.9em;
+      font-family: 'JetBrains Mono', 'Fira Code', monospace;
+    }
+    pre {
+      background: var(--surface);
+      padding: 1rem;
+      border-radius: 4px;
+      overflow-x: auto;
+      margin: 1rem 0;
+    }
+    pre code { background: none; padding: 0; }
+    blockquote {
+      border-left: 3px solid var(--border);
+      padding-left: 1rem;
+      color: var(--text-dim);
+      font-style: italic;
+      margin: 1rem 0;
+    }
+    ul, ol { padding-left: 1.5rem; margin: 0.8rem 0; }
+    li { margin: 0.3rem 0; }
+    .citation {
+      color: var(--citation);
+      font-weight: 500;
+      cursor: help;
+    }
+    .ref { color: var(--accent); font-style: italic; }
+    .footnote { color: var(--accent); cursor: help; }
+    .math-display {
+      margin: 1.2rem 0;
+      overflow-x: auto;
+      text-align: center;
+    }
+    .figure-placeholder, .table-placeholder {
+      background: var(--surface);
+      border: 1px dashed var(--border);
+      padding: 2rem;
+      margin: 1.5rem 0;
+      text-align: center;
+      border-radius: 4px;
+    }
+    .figure-placeholder::before { content: '[Figure placeholder]'; display: block; color: var(--text-dim); margin-bottom: 0.5rem; }
+    .table-placeholder::before { content: '[Table placeholder]'; display: block; color: var(--text-dim); margin-bottom: 0.5rem; }
+    figcaption { font-style: italic; color: var(--text-dim); font-size: 0.9rem; }
+
+    /* Live reload indicator */
+    .live-badge {
+      position: fixed;
+      top: 1rem;
+      right: 1rem;
+      background: #0d7337;
+      color: white;
+      padding: 0.3rem 0.8rem;
+      border-radius: 20px;
+      font-size: 0.75rem;
+      font-family: sans-serif;
+      opacity: 0.8;
+    }
+    .live-badge.disconnected { background: #7d3030; }
+  </style>
+</head>
+<body>
+  <div class="live-badge" id="status">LIVE</div>
+  <div id="content">
+    {{CONTENT}}
+  </div>
+  <script>
+    // Auto-reload via polling (simple, no WebSocket dependency)
+    let lastHash = "";
+    async function checkForUpdates() {
+      try {
+        const res = await fetch("/__hash");
+        const hash = await res.text();
+        if (lastHash && hash !== lastHash) {
+          location.reload();
+        }
+        lastHash = hash;
+        document.getElementById("status").textContent = "LIVE";
+        document.getElementById("status").className = "live-badge";
+      } catch {
+        document.getElementById("status").textContent = "DISCONNECTED";
+        document.getElementById("status").className = "live-badge disconnected";
+      }
+    }
+    setInterval(checkForUpdates, 1000);
+    checkForUpdates();
+  </script>
+</body>
+</html>`;
+function startPreviewServer(texPath) {
+  const resolved = path17.resolve(texPath);
+  let currentHash = "";
+  function getContentHash() {
+    try {
+      const content = fs18.readFileSync(resolved, "utf8");
+      return `${content.length}-${content.slice(0, 100)}-${content.slice(-100)}`;
+    } catch {
+      return "error";
+    }
+  }
+  function renderPage() {
+    try {
+      const latex = fs18.readFileSync(resolved, "utf8");
+      const htmlContent = latexToHtml(latex);
+      currentHash = getContentHash();
+      return HTML_TEMPLATE.replace("{{CONTENT}}", htmlContent);
+    } catch (err) {
+      return HTML_TEMPLATE.replace(
+        "{{CONTENT}}",
+        `<p style="color: #ff6b6b;">Error reading ${resolved}: ${err instanceof Error ? err.message : String(err)}</p>`
+      );
+    }
+  }
+  return new Promise((resolve) => {
+    const server = http2.createServer((req, res) => {
+      if (req.url === "/__hash") {
+        const hash = getContentHash();
+        res.writeHead(200, { "Content-Type": "text/plain", "Cache-Control": "no-cache" });
+        res.end(hash);
+        return;
+      }
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-cache" });
+      res.end(renderPage());
+    });
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (!addr || typeof addr === "string") return;
+      const port = addr.port;
+      const url = `http://127.0.0.1:${port}`;
+      resolve({
+        url,
+        port,
+        close: () => server.close()
+      });
+    });
+  });
+}
+
 // src/tui/commands.ts
 var SLASH_COMMANDS = [
   { name: "auth", aliases: ["/connect", "/login"], description: "Connect your OpenAI account via browser OAuth", category: "auth" },
@@ -5306,6 +5630,7 @@ var SLASH_COMMANDS = [
   { name: "clear", aliases: ["/new"], description: "Clear conversation and start fresh", category: "session" },
   { name: "help", aliases: ["/commands"], description: "Show available commands", category: "system" },
   { name: "config", aliases: ["/settings"], description: "View or change settings (e.g. /config theme dark)", category: "system" },
+  { name: "preview", aliases: [], description: "Live preview a LaTeX file in browser (e.g. /preview papers/draft.tex)", category: "workspace" },
   { name: "memory", aliases: ["/memories"], description: "View or clear stored memories about you", category: "system" },
   { name: "exit", aliases: ["/quit", "/q"], description: "Exit Open Research", category: "system" }
 ];
@@ -5843,6 +6168,7 @@ function App({
   const deferredPendingUpdates = useDeferredValue(pendingUpdates);
   const activityFrame = useAnimatedFrame(busy);
   const [agentQuestion, setAgentQuestion] = useState3(null);
+  const previewRef = useRef(null);
   const isHome = deferredMessages.length === 0 && !busy;
   const hasWorkspace = workspacePath !== null;
   const hasAuth = authStatus === "connected";
@@ -6132,6 +6458,29 @@ function App({
         addSystemMessage("  Esc  unfocus prompt");
         break;
       }
+      case "preview": {
+        if (!args) {
+          addSystemMessage("Usage: /preview <path-to-tex-file>");
+          addSystemMessage("Example: /preview papers/draft.tex");
+          break;
+        }
+        const texPath = args.trim();
+        const resolvedTex = __require("path").isAbsolute(texPath) ? texPath : __require("path").resolve(workspacePath ?? process.cwd(), texPath);
+        try {
+          if (previewRef.current) {
+            previewRef.current.close();
+          }
+          const preview = await startPreviewServer(resolvedTex);
+          previewRef.current = preview;
+          addSystemMessage(`Live preview started at ${preview.url}`);
+          addSystemMessage("Auto-reloads when the file changes. Close with /preview stop");
+          const openModule = await import("open");
+          await openModule.default(preview.url);
+        } catch (err) {
+          addSystemMessage(`Preview failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        break;
+      }
       case "memory": {
         if (args === "clear") {
           await clearMemories({ homeDir });
@@ -6807,7 +7156,7 @@ function App({
         statusParts,
         statusColor,
         tokenDisplay,
-        workspaceName: hasWorkspace ? path17.basename(workspacePath) : process.cwd(),
+        workspaceName: hasWorkspace ? path18.basename(workspacePath) : process.cwd(),
         mode: agentMode,
         planningStatus: planningState.status
       }
@@ -6819,7 +7168,7 @@ function App({
 var program = new Command();
 program.name("open-research").description("Local-first research CLI powered by ChatGPT/Codex auth.").argument("[workspacePath]", "Optional workspace path to open").action(async (workspacePath) => {
   await ensureOpenResearchConfig();
-  const target = workspacePath ? path18.resolve(workspacePath) : process.cwd();
+  const target = workspacePath ? path19.resolve(workspacePath) : process.cwd();
   const project = await loadWorkspaceProject(target);
   const auth2 = await loadStoredAuth();
   render(
@@ -6841,7 +7190,7 @@ program.name("open-research").description("Local-first research CLI powered by C
 });
 program.command("init").argument("[workspacePath]").description("Initialize an Open Research workspace.").action(async (workspacePath) => {
   await ensureOpenResearchConfig();
-  const target = path18.resolve(workspacePath ?? process.cwd());
+  const target = path19.resolve(workspacePath ?? process.cwd());
   const project = await initWorkspace({ workspaceDir: target });
   console.log(`Initialized workspace: ${target}`);
   console.log(`Title: ${project.title}`);
@@ -6910,8 +7259,8 @@ skills.command("create").argument("[name]").description("Scaffold a new user ski
 });
 skills.command("edit").argument("<name>").description("Open a user skill in $EDITOR.").action(async (name) => {
   await ensureOpenResearchConfig();
-  const skillDir = path18.join(getOpenResearchSkillsDir(), name);
-  openInEditor(path18.join(skillDir, "SKILL.md"));
+  const skillDir = path19.join(getOpenResearchSkillsDir(), name);
+  openInEditor(path19.join(skillDir, "SKILL.md"));
   const validation = await validateSkillDirectory({ skillDir });
   if (!validation.ok) {
     console.error(validation.errors.join("\n"));
@@ -6922,9 +7271,9 @@ skills.command("edit").argument("<name>").description("Open a user skill in $EDI
 });
 skills.command("validate").argument("[nameOrPath]").description("Validate one user skill.").action(async (nameOrPath) => {
   await ensureOpenResearchConfig();
-  const skillDir = nameOrPath ? path18.isAbsolute(nameOrPath) ? nameOrPath : path18.join(getOpenResearchSkillsDir(), nameOrPath) : getOpenResearchSkillsDir();
+  const skillDir = nameOrPath ? path19.isAbsolute(nameOrPath) ? nameOrPath : path19.join(getOpenResearchSkillsDir(), nameOrPath) : getOpenResearchSkillsDir();
   const stat = await import("fs/promises").then(
-    (fs18) => fs18.stat(skillDir).catch(() => null)
+    (fs19) => fs19.stat(skillDir).catch(() => null)
   );
   if (!stat) {
     throw new Error(`Skill path not found: ${skillDir}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-research",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Local-first research CLI agent — discover papers, synthesize notes, run analysis, and draft artifacts from your terminal.",
   "type": "module",
   "license": "MIT",