@synsci/thesis 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Synthetic Sciences
+
+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,46 @@
+# @synsci/thesis
+
+**Thesis by Synthetic Sciences** — graph-based research management.
+Structure your research. Let agents do the rest.
+
+## Quick Setup
+
+```bash
+npx --yes @synsci/thesis setup
+```
+
+This will:
+1. Detect your installed AI hosts (Claude Code, Codex, Cursor, OpenCode, etc.)
+2. Open your browser to authenticate
+3. Configure MCP connections for all detected hosts
+
+### Remote Setup (SSH)
+
+```bash
+npx --yes @synsci/thesis setup \
+  --auth-mode device \
+  --base-url https://thesis.syntheticsciences.ai
+```
+
+### Uninstall
+
+```bash
+npx --yes @synsci/thesis uninstall
+```
+
+### Web Connector Hosts (Claude.ai, ChatGPT.com)
+
+For web-based MCP hosts, use the URL when prompted:
+```
+https://thesis.syntheticsciences.ai/mcp-server
+```
+
+## What is Thesis?
+
+Thesis is "git for research" — a graph-based system for tracking research work, decisions, and evidence. Agents and researchers collaborate through a DAG of nodes, where each node represents an observation or experiment.
+
+- **MCP-first**: Works with any MCP host (Claude Code, Codex, Cursor, OpenCode, etc.)
+- **63 tools**: Full node lifecycle, artifact management, compute provisioning, collaboration
+- **Graph structure**: Branch, merge, and iterate on ideas like code
+
+[thesis.syntheticsciences.ai](https://thesis.syntheticsciences.ai)

package/bin/thesis.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.mjs';
+run().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@synsci/thesis",
+  "version": "0.1.0",
+  "description": "Thesis by Synthetic Sciences — graph-based research management. One-command MCP setup.",
+  "type": "module",
+  "bin": {
+    "thesis": "./bin/thesis.mjs"
+  },
+  "main": "src/cli.mjs",
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "thesis",
+    "mcp",
+    "research",
+    "experiment-tracking",
+    "dag",
+    "ai-agents",
+    "synthetic-sciences"
+  ],
+  "author": "Synthetic Sciences",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/synthetic-sciences/thesis"
+  },
+  "homepage": "https://thesis.syntheticsciences.ai",
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "inquirer": "^12.0.0",
+    "ora": "^8.0.0",
+    "picocolors": "^1.0.0",
+    "open": "^10.0.0",
+    "js-yaml": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/thesis/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: thesis
+description: Use for Thesis experiment design, turning source material into Thesis graphs, staged frontier planning with `/lookahead`, budgeted autonomous research with `/fsd`, MCP-assisted execution, and platform setup/troubleshooting across supported hosts.
+---
+
+# Thesis Skill
+
+Use this skill to structure research work and to route setup/support questions to the smallest relevant Thesis docs.
+
+## When To Use
+
+Use this skill when the conversation is about any of the following:
+
+- planning experiments, hypotheses, comparisons, or next-branch decisions
+- turning source material into a Thesis graph
+- using command-like Thesis workflows such as `/to-graph`, `/reproduce`,
+  `/lookahead`, or `/fsd`
+- running or interpreting empirical work in Thesis
+- choosing between `insight` and `empirical` nodes
+- setting up, updating, authenticating, or troubleshooting Thesis MCP
+- managed compute, local hardware, campaigns, or Thesis Web UI navigation
+
+If the request is ambiguous, default to experiment-design guidance before platform mechanics.
+
+## Workflow
+
+1. Classify the request as research guidance, platform support, or mixed.
+2. Load only the minimum files needed for the current task.
+3. If the user is using command-like language such as `/to-graph`,
+   `/reproduce`, `/lookahead`, or `/fsd`, load
+   `reference/command-presets.md` first.
+4. For research requests, run a short design pass before execution:
+   ask 1-2 questions to clarify objective, assumptions, and decision criteria.
+5. If design is solid and the user wants to proceed, shift to execution support.
+6. Use Thesis MCP tools for live behavior/contract checks when available.
+7. Summarize evidence and propose the most likely next branch.
+
+## Routing Map
+
+Choose one primary file first, then add at most one supporting file only if needed:
+
+- `reference/experiment-design-protocol.md` for structured experiment design and readiness checks
+- `reference/command-presets.md` for `/to-graph`, `/reproduce`, `/lookahead`,
+  and `/fsd`
+- `reference/thesis-mcp-tool-map.md` for exact tool surface and contract behavior
+- `getting-started/tutorial-overview.md` for orientation and learning path
+- `getting-started/quickstart.md` for fastest first-use setup and auth recovery
+
+## Guardrails
+
+- Keep guidance harness-agnostic unless the user explicitly asks for a specific host.
+- Prefer concrete steps and decision points over long narrative explanations.
+- Do not run broad document reads; load only what is required by the current request.
+- Do not start compute-heavy execution before design intent is clear.
+- Keep `/reproduce` narrow: validate existing knowledge claims rather than
+  expanding an open-ended research frontier.
+- Treat `/lookahead` as planning only and `/fsd` as budgeted autonomous
+  frontier advancement.

package/skills/thesis/getting-started/quickstart.md

@@ -0,0 +1,209 @@
+# Thesis Quickstart
+
+Get from zero to a working Thesis graph in minutes.
+
+## Prerequisites
+
+- An active Thesis account with valid credentials
+- A supported AI agent harness (Claude Code, Cursor, or any MCP-compatible host)
+- Thesis MCP server configured and connected
+
+## Step 1: Verify Authentication
+
+Before doing anything else, confirm that your MCP connection is live and
+authenticated.
+
+```
+mcp__thesis__thesis_auth_status
+```
+
+If authentication fails:
+
+1. Check that the Thesis MCP server is running
+2. Verify your credentials are current
+3. Re-authenticate through your harness's MCP configuration
+4. Run `mcp__thesis__thesis_auth_status` again to confirm
+
+## Step 2: Review the Contract
+
+Read the runtime contract to understand the current rules for node commits,
+artifact uploads, and budget policies.
+
+```
+mcp__thesis__thesis_get_contract
+```
+
+You can also read a specific section:
+
+```
+mcp__thesis__thesis_get_contract_section(section_id="node_commit")
+```
+
+This step is optional for experienced users but strongly recommended when
+starting out or after a platform update.
+
+## Step 3: Create Your First Node
+
+Create a root node to anchor your research graph. A root node is a staged
+(draft) node with no parent.
+
+```
+mcp__thesis__thesis_stage_node_create(
+  title="My First Research Topic",
+  content="Initial exploration of [your topic here].",
+  summary="Root node for [topic] research."
+)
+```
+
+This returns a node ID and revision number. Save the node ID -- you will need
+it for subsequent operations.
+
+## Step 4: Update the Staged Node
+
+Add more detail to your staged node before committing.
+
+```
+mcp__thesis__thesis_stage_node_update(
+  node_id="<your-node-id>",
+  expected_revision=<current-revision>,
+  content="Detailed description of the research direction...",
+  summary="Root node exploring [specific question]."
+)
+```
+
+Always pass `expected_revision` to avoid lost updates from concurrent edits.
+
+## Step 5: Commit the Node
+
+Commit the node to make it permanent in the graph. You must specify `kind`,
+`outcome`, and `summary`.
+
+For an insight node (synthesis, rationale, design decisions):
+
+```
+mcp__thesis__thesis_commit_node(
+  node_id="<your-node-id>",
+  expected_revision=<current-revision>,
+  kind="insight",
+  outcome="committed",
+  summary="Established root direction for [topic] research.",
+  insights="Key insight: [what you learned or decided]."
+)
+```
+
+For an empirical node (experiment results, evidence):
+
+```
+mcp__thesis__thesis_commit_node(
+  node_id="<your-node-id>",
+  expected_revision=<current-revision>,
+  kind="empirical",
+  outcome="committed",
+  summary="Baseline measurement of [metric].",
+  hypothesis="[Your falsifiable hypothesis]."
+)
+```
+
+Remember:
+
+- `insight` commits require non-empty `insights`
+- `empirical` commits require non-empty `hypothesis` and either artifacts or `no_artifacts_reason`
+
+## Step 6: Branch From Your Root
+
+Create child nodes to explore different directions from your root.
+
+```
+mcp__thesis__thesis_branch_node(
+  parent_node_id="<root-node-id>",
+  title="Branch A: [direction]",
+  content="Exploring [specific sub-question]..."
+)
+```
+
+Repeat for each research direction. This builds the DAG (directed acyclic graph)
+that represents your research tree.
+
+## Step 7: Attach Artifacts
+
+When you have results, figures, data, or other files to attach:
+
+```
+mcp__thesis__thesis_prepare_artifact_uploads(
+  node_id="<your-node-id>",
+  artifacts=[
+    {
+      "filename": "results.json",
+      "artifact_type": "json",
+      "size_bytes": 2048
+    }
+  ]
+)
+```
+
+This returns signed upload URLs. Upload your file bytes to those URLs via HTTP
+PUT, then finalize:
+
+```
+mcp__thesis__thesis_finalize_artifact_uploads(
+  node_id="<your-node-id>",
+  upload_batch_id="<batch-id-from-prepare>"
+)
+```
+
+## Example: Complete First-Use Workflow
+
+Here is a complete workflow from start to finish:
+
+1. **Authenticate**: `thesis_auth_status` -- confirm connection
+2. **Create root**: `thesis_stage_node_create` -- "Evaluating LLM summarization quality"
+3. **Update root**: `thesis_stage_node_update` -- add detailed research context
+4. **Commit root**: `thesis_commit_node` -- kind=insight, capture initial direction
+5. **Branch**: `thesis_branch_node` -- "Baseline: GPT-4 ROUGE scores on CNN/DailyMail"
+6. **Update branch**: `thesis_stage_node_update` -- set hypothesis, metric, budget
+7. **Run experiment**: acquire compute, run evaluation, collect scores
+8. **Upload artifacts**: prepare + upload + finalize -- results table, score distribution plot
+9. **Commit branch**: `thesis_commit_node` -- kind=empirical, outcome, hypothesis, summary
+10. **Next branch**: `thesis_branch_node` -- "Comparison: Claude vs GPT-4 on same benchmark"
+
+## Common Patterns
+
+### Check your credit balance
+
+```
+mcp__thesis__thesis_get_credits_balance
+```
+
+### List your nodes
+
+```
+mcp__thesis__thesis_list_nodes
+```
+
+### View a subtree
+
+```
+mcp__thesis__thesis_get_node_tree(node_id="<root-node-id>")
+```
+
+### Get a condensed summary
+
+```
+mcp__thesis__thesis_summarize_node_tree(node_id="<root-node-id>")
+```
+
+### Share with collaborators
+
+```
+mcp__thesis__thesis_set_sharing_for_node(
+  node_id="<node-id>",
+  sharing_policy={...}
+)
+```
+
+## What Next
+
+- Read `tutorial-overview.md` for a deeper understanding of Thesis concepts
+- Read `reference/experiment-design-protocol.md` to learn the 5-phase design process
+- Read `reference/command-presets.md` to use `/to-graph`, `/reproduce`, `/lookahead`, and `/fsd`
+- Read `reference/thesis-mcp-tool-map.md` for the complete tool reference

package/skills/thesis/getting-started/tutorial-overview.md

@@ -0,0 +1,220 @@
+# Thesis Tutorial Overview
+
+Thesis by Synthetic Sciences is a graph-based system for tracking research work,
+decisions, and evidence over time. This document covers the core concepts that
+agents and users need to understand before working with Thesis.
+
+## What Thesis Is
+
+Thesis is a structured research graph. It replaces flat notes, scattered
+documents, and unlinked experiment logs with a directed acyclic graph (DAG)
+where every piece of research has a clear place, clear provenance, and clear
+relationships to the work around it.
+
+Thesis is designed to be operated by AI agents through MCP (Model Context
+Protocol) tools. Agents read and write the graph, plan experiments, execute
+compute, and record evidence -- all within a structured framework that
+preserves context across sessions and collaborators.
+
+## Key Concepts
+
+### Nodes
+
+A node is the fundamental unit of Thesis. Every piece of research -- a question,
+a hypothesis, a result, a design decision, a synthesis -- lives in a node.
+
+Each node has:
+
+- **title**: short human-readable name
+- **content**: the primary narrative, reasoning, or description (markdown)
+- **summary**: a brief synopsis for tree views and quick scanning
+- **kind**: either `insight` or `empirical` (set at commit time)
+- **outcome**: the resolution status (set at commit time)
+- **artifacts**: attached files, figures, tables, data
+
+### The DAG (Directed Acyclic Graph)
+
+Nodes are connected by parent-child edges forming a DAG. This is not a flat
+list or a simple tree -- nodes can have multiple parents (via `add_parent`)
+and the graph can represent convergent research paths, not just divergent
+branching.
+
+Key properties:
+
+- **Root nodes** have no parents and anchor a research topic
+- **Branch nodes** are children created via `branch_node` to explore sub-questions
+- **Merge nodes** combine insights from multiple parent branches
+- **The graph is acyclic**: no node can be its own ancestor
+
+### Kinds: Insight vs Empirical
+
+Every committed node has a `kind` that determines its contract requirements:
+
+**Insight nodes** capture synthesis, rationale, design decisions, literature
+review, or any non-empirical knowledge. They require:
+
+- Non-empty `insights` field at commit time
+- No artifact requirement (though artifacts are welcome)
+
+Use insight nodes for:
+
+- Research direction decisions
+- Literature synthesis
+- Experiment design rationale
+- Open questions and decomposition
+- Planning and strategy
+
+**Empirical nodes** capture work that produces evidence -- experiment runs,
+benchmark results, data analysis, measurements. They require:
+
+- Non-empty `hypothesis` field at commit time
+- Artifacts attached, or a `no_artifacts_reason` explaining their absence
+
+Use empirical nodes for:
+
+- Experiment results
+- Benchmark comparisons
+- Data analysis outputs
+- Measurement and observation records
+
+### Node Lifecycle
+
+Every node follows a staged-then-committed lifecycle:
+
+1. **Staged (draft)**: Created via `thesis_stage_node_create`. The node exists
+   in the graph but is mutable. You can update it freely with
+   `thesis_stage_node_update`.
+
+2. **Committed**: Finalized via `thesis_commit_node`. The node's kind, outcome,
+   and summary are locked. Committed nodes represent completed units of work.
+
+Important: staged nodes should not be left indefinitely. They represent
+in-progress work. Commit them when the work they represent is resolved, or
+delete them if the direction is abandoned.
+
+### Optimistic Locking
+
+All mutation operations use `expected_revision` for optimistic locking. When
+you read a node, you get its current revision number. When you update or commit
+it, you pass that revision number back. If someone else has modified the node
+in the meantime, the operation fails with a revision conflict, preventing lost
+updates.
+
+Always:
+
+1. Read the node to get the current revision
+2. Pass that revision to your mutation call
+3. Handle revision conflicts by re-reading and retrying
+
+### Artifacts
+
+Artifacts are files attached to nodes: results tables, plots, figures, code,
+datasets, checkpoints, notebooks, and more.
+
+Supported artifact types include:
+`text`, `table`, `json`, `image`, `banner`, `html`, `plotly_html`, `vega`,
+`checkpoint`, and `diff_carousel`.
+
+Artifact upload is a two-step process:
+
+1. **Prepare**: Call `thesis_prepare_artifact_uploads` with filenames, types, and
+   sizes. This returns signed upload URLs and a batch ID.
+2. **Upload**: HTTP PUT the raw file bytes to each signed URL.
+3. **Finalize**: Call `thesis_finalize_artifact_uploads` with the batch ID to
+   complete the upload.
+
+Never skip the finalize step -- artifacts are not visible until finalized.
+
+### Tags
+
+Tags are lightweight annotations you can attach to nodes for filtering,
+grouping, and organizing. Create tag definitions with `thesis_create_node_tag`,
+then assign them to nodes with `thesis_set_node_tag_assignments`.
+
+Tags are useful for:
+
+- Marking experiment status (e.g., "needs-review", "baseline", "promising")
+- Categorizing research areas
+- Filtering node lists in large graphs
+
+### Sharing and Collaboration
+
+Thesis graphs can be shared with collaborators through access policies.
+Use `thesis_get_node_sharing` to check current policies and
+`thesis_set_sharing_for_node` to grant or revoke access.
+
+For handoff, use `thesis_export_summary` or `thesis_export_subgraph` to create
+portable representations of your work.
+
+### Managed Compute
+
+Thesis provides managed compute for running experiments. The flow is:
+
+1. Maintain an approval session (`thesis_approval_session_heartbeat`)
+2. Request budget approval (`thesis_request_compute_grant_approval`)
+3. Acquire a compute instance (`thesis_compute_acquire`)
+4. Use the instance (check status, get connection details)
+5. Release when done (`thesis_compute_release`)
+
+Compute costs credits. Always check your balance with
+`thesis_get_credits_balance` and set explicit budget caps before acquiring
+compute.
+
+### Campaigns
+
+Campaigns are organized research efforts with shared budgets. Organizers
+create campaign budgets (`thesis_create_campaign_budget`) that participants
+can draw from. Use `thesis_get_campaign_snapshot` to see the current state
+of a campaign.
+
+## How Agents Use Thesis
+
+AI agents interact with Thesis through MCP tools. The typical agent workflow is:
+
+1. **Orient**: Read the existing graph (`thesis_list_nodes`,
+   `thesis_get_node_tree`, `thesis_summarize_node_tree`) to understand what
+   work exists.
+
+2. **Design**: Use the experiment design protocol to clarify what the user
+   wants to learn. Capture the design in an `insight` node.
+
+3. **Execute**: Create `empirical` branches, acquire compute if needed, run
+   experiments, and upload artifacts.
+
+4. **Synthesize**: Commit nodes with clear summaries and outcomes. Branch
+   again for follow-up questions.
+
+5. **Repeat**: The graph grows as a persistent record of research decisions
+   and evidence, usable across sessions and agents.
+
+### Agent Best Practices
+
+- Always read before writing. Check the existing graph state before creating
+  new nodes.
+- Use the design protocol before spending compute. Clarify the question first.
+- Keep `content` readable. The node content should tell the story; artifacts
+  provide supporting evidence.
+- Commit nodes promptly. Do not leave large numbers of staged nodes lingering.
+- Use `insight` nodes for planning and `empirical` nodes for evidence. Do not
+  conflate them.
+- Respect budget caps. Never acquire compute without an explicit budget ceiling.
+- Name uncertainty. If results are ambiguous, say so in the summary rather than
+  overstating confidence.
+
+## Workflow Commands
+
+Thesis supports four command presets that encode common research workflows:
+
+- `/to-graph` -- Convert source material into a structured Thesis graph
+- `/reproduce` -- Structure source material and run budgeted empirical validation
+- `/lookahead` -- Plan the next frontier of work without executing
+- `/fsd` -- Autonomous frontier advancement under a hard budget
+
+See `reference/command-presets.md` for full details on each command.
+
+## Further Reading
+
+- `getting-started/quickstart.md` -- Hands-on first steps
+- `reference/experiment-design-protocol.md` -- The 5-phase design protocol
+- `reference/command-presets.md` -- Command preset details
+- `reference/thesis-mcp-tool-map.md` -- Complete MCP tool reference