@synsci/thesis 0.1.0

package/skills/thesis/reference/command-presets.md

@@ -0,0 +1,273 @@
+# Command Presets
+
+Use this guide when the user frames the request as `/to-graph`,
+`/reproduce`, `/lookahead`, `/fsd`, or equivalent command-like language.
+
+These are workflow presets inside the Thesis skill. They are not separate
+product surfaces.
+
+## `/to-graph`
+
+Use `/to-graph` when the user's main goal is to convert unstructured source
+material into a Thesis graph.
+
+Typical inputs:
+
+- paper
+- blogpost
+- README
+- markdown wiki
+- research notes
+
+Output contract:
+
+- create or update a root node or subtree
+- put the primary narrative in node `content`
+- attach supporting files as artifacts
+- add only durable graph edges
+
+Execution policy:
+
+- do not acquire compute by default
+- do not spend budget implicitly
+- execution only happens if the user explicitly asks to run branches
+
+Default mapping:
+
+- stable page or concept -> one node
+- main markdown/text -> `content`
+- short synopsis -> `summary`
+- figures, PDFs, datasets, notebooks, code, tables -> artifacts
+- durable semantic relationships -> edges
+- ordinary hyperlinks or citations -> remain in markdown unless they deserve an
+  actual graph relationship
+
+Typical tool sequence:
+
+1. `mcp__thesis__thesis_stage_node_create` -- create root or subtree nodes
+2. `mcp__thesis__thesis_stage_node_update` -- populate content, summary
+3. `mcp__thesis__thesis_prepare_artifact_uploads` -- if artifacts exist
+4. Upload artifact bytes to signed URLs
+5. `mcp__thesis__thesis_finalize_artifact_uploads` -- finalize uploads
+6. `mcp__thesis__thesis_add_parent` -- wire edges between nodes
+7. `mcp__thesis__thesis_commit_node` -- commit each node
+
+## `/reproduce`
+
+Use `/reproduce` when the source is claim-bearing and the user wants Thesis
+to both structure the source and run empirical validation.
+
+`/reproduce` is conceptually:
+
+```text
+/to-graph --mode reproduce --execute
+```
+
+That means:
+
+1. graphify the source first
+2. split it into explicit validation branches
+3. execute those branches within a hard maximum budget
+
+Typical sources:
+
+- research papers
+- benchmark claims
+- blogposts with strong empirical claims
+- replication requests on an existing Thesis graph
+
+Budget semantics:
+
+- a max budget is a hard ceiling, not a soft preference
+- if no max budget is given, ask for one before any compute acquisition
+- until the budget is explicit, planning and graph construction may proceed, but
+  empirical execution should not start
+- prefer the highest-information, lowest-cost branches first
+- stop when the claim is resolved or the budget limit is reached
+
+Default branch types:
+
+- baseline sanity check
+- mechanism or intermediate-signal check
+- ablation
+- efficiency or overhead check
+- robustness or failure-mode check
+- follow-up analysis branch after results land
+
+Typical tool sequence:
+
+1. `/to-graph` sequence to structure the source
+2. `mcp__thesis__thesis_branch_node` -- create validation branches
+3. `mcp__thesis__thesis_stage_node_update` -- set hypothesis for each branch
+4. `mcp__thesis__thesis_request_compute_grant_approval` -- request budget
+5. `mcp__thesis__thesis_compute_acquire` -- acquire compute
+6. Run experiments, collect results
+7. `mcp__thesis__thesis_prepare_artifact_uploads` -- upload evidence
+8. Upload artifact bytes to signed URLs
+9. `mcp__thesis__thesis_finalize_artifact_uploads` -- finalize
+10. `mcp__thesis__thesis_commit_node` -- commit with outcome
+
+## `/lookahead`
+
+Use `/lookahead` when the user wants Thesis to plan the next frontier of work
+from an existing set of nodes without executing it yet.
+
+`/lookahead` is conceptually:
+
+```text
+/plan-frontier --execute=false
+```
+
+That means:
+
+1. resolve a starting set of Thesis nodes
+2. resolve a measurable objective for those nodes
+3. expand the frontier into staged next-step nodes
+
+Starting-node policy:
+
+- prefer explicit node ids, slugs, or directly named nodes
+- otherwise use the focused or recently referenced graph context
+- if no stable starting set can be recovered, ask
+
+Objective policy:
+
+- if the objective is missing, ask for one
+- if the user insists on not specifying it, infer the objective from the graph
+  context and state it explicitly before planning
+- the objective must be measurable enough to rank frontier branches
+
+Lookahead policy:
+
+- depth `n` means plan `n` hops ahead from the currently resolved frontier
+- default `n=1`
+- width `k` means expand up to `k` non-redundant frontier directions
+- avoid redundant siblings that only restate the same branch with different
+  wording
+
+Node-typing policy:
+
+- if a planned node is expected to produce evidence or artifacts, type it
+  `empirical`
+- otherwise type it `insight`
+- leave planned nodes staged until the underlying work has a resolution
+
+Output contract:
+
+- create or update a graph-local planning contract
+- write the objective, depth `n`, width `k`, and terminal condition into the
+  graph
+- stage the next frontier of nodes without hidden execution
+
+Typical tool sequence:
+
+1. `mcp__thesis__thesis_get_node` or `mcp__thesis__thesis_get_node_tree` -- resolve starting nodes
+2. `mcp__thesis__thesis_summarize_node_tree` -- understand current state
+3. `mcp__thesis__thesis_branch_node` -- create frontier branches (staged)
+4. `mcp__thesis__thesis_stage_node_update` -- populate each branch with plan details
+5. Do NOT commit or execute -- leave nodes staged for review
+
+## `/fsd`
+
+Use `/fsd` ("full self-driving") when the user wants Thesis to keep
+advancing a research frontier autonomously under a specified budget.
+
+`/fsd` is conceptually:
+
+```text
+/lookahead --execute --replan-after-each-resolution
+```
+
+That means:
+
+1. resolve starting nodes
+2. resolve a measurable objective
+3. resolve a hard budget
+4. expand the frontier up to depth `n` and width `k`
+5. execute up to `k` frontier branches in parallel
+6. refresh the lookahead after each resolved node so the graph stays `n` hops
+   ahead
+
+Budget semantics:
+
+- credits are the default budget unit unless the user specifies another
+  measurable budget semantic
+- the budget is a hard ceiling, not a soft preference
+- if no budget is given, ask before execution starts
+- if the user supplies a non-credit budget unit, persist that exact unit in the
+  graph-local control contract
+
+Objective policy:
+
+- if the objective is missing, ask for one
+- if the user refuses to specify it, infer it from the existing graph context
+  and state it explicitly before execution
+- the objective must be precise enough that the model can decide whether a
+  branch is advancing or stalling it
+
+Width and worker policy:
+
+- `k` always means maximum distinct frontier directions
+- in `/fsd`, that same `k` also caps concurrent workers
+- if more than `k` worthwhile branches exist, route the extra branches in
+  sequence via the parent model
+
+Termination policy:
+
+- do not rely on new user feedback to decide whether to continue
+- before execution, persist a graph-local terminal condition that later steps
+  can read directly from node state
+- stop when the persisted condition is met, for example:
+  - objective reached
+  - hard budget exhausted
+  - no non-redundant frontier branch with positive expected value remains
+
+Graph-maintenance policy:
+
+- keep unresolved planned nodes staged
+- commit nodes only when their work has a resolution
+- empirical nodes should accumulate the expected evidence or artifact before
+  completion
+- insight nodes should only be committed once the synthesis is actually known
+
+Typical tool sequence (per cycle):
+
+1. `mcp__thesis__thesis_get_node_tree` -- read current frontier
+2. `mcp__thesis__thesis_branch_node` -- expand frontier
+3. `mcp__thesis__thesis_stage_node_update` -- populate branch plans
+4. `mcp__thesis__thesis_request_compute_grant_approval` -- request budget
+5. `mcp__thesis__thesis_compute_acquire` -- acquire compute
+6. Run experiment, collect results
+7. `mcp__thesis__thesis_prepare_artifact_uploads` + finalize -- upload evidence
+8. `mcp__thesis__thesis_commit_node` -- commit resolved branch
+9. Loop: re-expand frontier from new state, repeat until termination
+
+## Choosing Between Them
+
+Use `/to-graph` when the user wants structure from source material.
+
+Use `/reproduce` when the user wants structure plus budgeted validation of
+existing knowledge.
+
+Use `/lookahead` when the user wants staged next-step planning from existing
+nodes.
+
+Use `/fsd` when the user wants budgeted autonomous frontier advancement.
+
+If a graph starts as `/lookahead`, `/fsd` should resume from the same graph and
+keep it `n` steps ahead rather than planning from scratch each time.
+
+## Guardrails
+
+- Do not hide spend behind `/to-graph`.
+- Do not treat `/reproduce` as a magical bulk importer.
+- Do not blur `/reproduce` and `/fsd`.
+- `/reproduce` validates existing knowledge claims.
+- `/fsd` expands the frontier to create new knowledge under budget.
+- Build the graph explicitly with nodes, artifacts, and selected edges.
+- Keep the source material legible in `content`; do not dump everything into
+  artifacts.
+- Keep `/reproduce` scoped by cost and decision value, not by exhaustively
+  trying every possible branch.
+- Keep `/fsd` graph-local: future continuation and stopping decisions should be
+  derivable from the persisted node state rather than from fresh chat context.

package/skills/thesis/reference/experiment-design-protocol.md

@@ -0,0 +1,200 @@
+# Experiment Design Protocol
+
+Use this when the user needs help turning research intent into a well-formed experiment or exploration before spending compute.
+
+## Goal
+
+Help the user clarify what they are trying to learn, shape the work around that question, and avoid wasting compute before the design is solid.
+
+## Operating rules
+
+- Treat design and execution as separate phases.
+- Optimize for clarity of experimental purpose, not speed to a first run.
+- Adapt depth to the user's experience and the clarity already present in the conversation.
+- Apply epistemic discipline: separate what is known from what is assumed, and name uncertainty instead of smoothing it over.
+- Support both hypothesis-driven and exploratory work.
+- Support simple runs and complex shapes such as multi-stage pipelines, sweep-then-deep-dive, multi-arm comparisons, and custom structures.
+- Keep all 10 brief fields, but allow exploratory fields to be marked `exploratory` or `TBD` rather than fabricated.
+- Use quick Socratic questioning to surface assumptions, confidence, and what would change the user's mind. Keep it to 1-2 short questions per turn.
+- Propose defaults for structural choices such as experiment shape, stop condition, or artifact plan. Use questions rather than defaults for epistemic choices such as beliefs, assumptions, and what evidence would matter.
+- When a reasoning or design gap is visible, raise it as a question rather than an assertion.
+- If the core gate is satisfied and the user wants to proceed, stop asking more design questions.
+- Use Thesis `insight` nodes to preserve design context when it will help across turns or sessions.
+
+## Phase 1: Clarify what the user is trying to learn
+
+Start with:
+
+1. What are you trying to learn or decide?
+2. Is this mainly hypothesis-driven or exploratory right now?
+
+Keep this phase quick. Ask 1-2 short questions per turn, and use light Socratic questioning as an epistemic check after the user states the learning goal: briefly surface what seems known versus assumed before moving on.
+
+If the work is hypothesis-driven, ask:
+
+- What is the hypothesis?
+- Compared to what baseline or alternative?
+- What result would matter?
+
+If the work is exploratory, ask:
+
+- What is the big question?
+- What would you need to learn first before tackling it?
+- What is the cheapest or cleanest way to learn that first piece?
+- What signal or pattern are you looking for?
+
+If the user is still fuzzy after this phase, stay in planning mode. If needed, create or update an `insight` node rather than an `empirical` node.
+
+## Phase 2: Shape the work
+
+Choose or define the experiment shape through quick Socratic questioning:
+
+- single focused run
+- multi-stage pipeline
+- sweep then deep-dive
+- multi-arm comparison
+- custom shape
+
+If the user is unsure about structure, propose a default shape, stop condition, or artifact plan instead of extending the question loop.
+
+Then fill the experiment brief:
+
+- `question`: the decision or learning goal
+- `hypothesis`: the claim being tested
+- `comparator`: the baseline or alternative
+- `unit_of_work`: what one run, branch, or stage actually changes
+- `primary_metric`: the main number or observable to inspect
+- `artifact_plan`: which artifact will help interpret the result
+- `budget_cap`: max spend or runtime for the current stage
+- `stop_condition`: when to stop rather than letting the run expand
+- `interpretation`: what would count as signal, no signal, or ambiguity
+- `next_branch_if_inconclusive`: the follow-up branch if the result is unclear
+
+For exploratory work, `hypothesis` or `comparator` may be marked `exploratory` or `TBD`, but the learning goal still needs to be explicit.
+
+## Phase 3: Run the adaptive design gate
+
+Frame the gate as preventing waste, not enforcing bureaucracy.
+
+Always check:
+
+- the question or goal is explicit
+- at least one metric or observable is defined
+- a budget cap or stop condition exists
+
+For hypothesis-driven work, also check:
+
+- there is a falsifiable hypothesis
+- there is a comparator or baseline
+
+For exploratory work, instead check:
+
+- the user can say what they are looking for
+- the first learning step is scoped well enough to run
+
+Additional checks when relevant:
+
+- an artifact plan or `no_artifacts_reason` exists
+- the run shape matches the question and is not changing too many important things without purpose
+- an interpretation rule or next branch is defined
+
+If the core gate passes and the user wants to proceed, let them run even if some non-core details are still `TBD`.
+
+When blocked, ask only the next necessary question instead of reopening the whole brief.
+
+## Phase 4: Confirm the plan
+
+Before any compute request or training launch, restate:
+
+- what we are trying to learn
+- the experiment shape
+- the metric or observable
+- the artifact plan
+- the budget or stop condition
+- what result would change the next step
+
+If the run is expensive or high-risk, ask for explicit confirmation.
+
+## Phase 5: Drive Thesis
+
+Use Thesis in layers when possible.
+
+### Design layer
+
+Use an `insight` node to capture rationale, open questions, experiment shape, and any decomposition needed for exploratory or multi-stage work.
+
+Typical flow:
+
+1. `mcp__thesis__thesis_stage_node_create`
+2. `mcp__thesis__thesis_stage_node_update`
+3. `mcp__thesis__thesis_commit_node`
+
+### Execution layer
+
+Only after the design gate passes, create or branch the `empirical` node for the runnable part of the work.
+
+Typical flow:
+
+1. `mcp__thesis__thesis_branch_node` or `mcp__thesis__thesis_stage_node_create`
+2. `mcp__thesis__thesis_stage_node_update` with the explicit run summary and the local question or hypothesis for that branch
+3. `mcp__thesis__thesis_request_compute_grant_approval` only after the user accepts the design
+4. `mcp__thesis__thesis_compute_acquire` and related compute tools only when execution is actually needed
+5. `mcp__thesis__thesis_prepare_artifact_uploads`
+6. Do a brief epistemic check before commit: verify what the evidence actually shows, whether it matches the interpretation rule from the brief, and whether any gap between the data and the hoped-for story needs to be named explicitly in the node summary.
+7. `mcp__thesis__thesis_commit_node`
+
+Important notes:
+
+- Exploratory work can stay in `insight` nodes until a specific empirical probe is ready.
+- Because `empirical` commits require a non-empty `hypothesis`, turn each runnable exploratory probe into a concrete local question or hypothesis for that branch.
+- For multi-stage or multi-arm work, use branches to represent stages or arms and keep summaries clear about how each branch feeds the next.
+- Completed empirical work needs artifacts or a `no_artifacts_reason`.
+
+## Adaptive question flow
+
+Ask in short batches of 1-2 questions per turn. Keep the flow light, Socratic, and epistemic rather than exhaustive.
+
+1. What are you trying to learn or decide?
+2. Is this hypothesis-driven or exploratory?
+3. Briefly separate what the user seems to know from what they seem to be assuming before locking the design.
+4. If hypothesis-driven: what is the hypothesis and compared to what?
+5. If exploratory: what is the first thing you need to learn and what is the cheapest way to learn it?
+6. What experiment shape fits this work?
+7. What metric or observable and artifact will you inspect?
+8. What budget or stop condition keeps this from wasting compute?
+9. What interpretation rule will distinguish evidence from expectation?
+10. If the result is ambiguous, what is the next branch?
+
+## Output template
+
+Use this shape when turning a vague request into an executable plan:
+
+```md
+Experiment brief
+
+- Question:
+- Hypothesis:
+- Comparator:
+- Unit of work:
+- Primary metric or observable:
+- Artifact plan:
+- Budget/time cap:
+- Stop condition:
+- Interpretation rule:
+- Next branch if inconclusive:
+
+Experiment type: hypothesis-driven | exploratory
+Design gate: ready | blocked
+Remaining gap:
+Recommended next action:
+```
+
+## Generalization rule
+
+Reuse the same protocol across domains by changing the unit of work and artifact type:
+
+- model training -> metrics tables, loss curves, checkpoints
+- benchmark comparisons -> score tables, latency plots, error slices
+- prompt evaluations -> rubric tables, failure examples, sampled outputs
+- product experiments -> funnels, event tables, user-segment slices
+- scientific workflows -> figures, logs, result tables, notebooks

package/skills/thesis/reference/thesis-mcp-tool-map.md

@@ -0,0 +1,201 @@
+# Thesis MCP Tool Map
+
+This reference describes the Thesis MCP tool families and the common runtime
+contract expected by the public Thesis skill.
+
+Use it as a routing guide, not as a session snapshot. Always verify the exact
+tool surface exposed by your current MCP host before executing critical flows.
+
+## Core Contract Expectations
+
+- Node lifecycle and graph-mutation flows use optimistic locking
+  (`expected_revision`).
+- Node commits require `kind`, `outcome`, and `summary`.
+- `kind` is typically `insight` or `empirical`.
+- `insight` commits require non-empty `insights`.
+- `empirical` commits require a non-empty `hypothesis`; completed empirical
+  commits also require artifacts or a `no_artifacts_reason`.
+- Artifact publish is a two-step flow:
+  prepare upload, upload raw bytes to returned signed URLs, then finalize
+  the upload batch.
+
+## Tool Families
+
+### Session, Auth, and Contract
+
+| # | Tool | Purpose |
+|---|------|---------|
+| 1 | `mcp__thesis__thesis_auth_status` | Check current authentication state |
+| 2 | `mcp__thesis__thesis_get_contract` | Retrieve the full runtime contract |
+| 3 | `mcp__thesis__thesis_get_contract_section` | Retrieve a specific contract section by ID |
+| 4 | `mcp__thesis__thesis_get_credits_balance` | Check remaining credits balance |
+
+### Node Discovery and Read
+
+| # | Tool | Purpose |
+|---|------|---------|
+| 5 | `mcp__thesis__thesis_list_nodes` | List nodes with optional filters |
+| 6 | `mcp__thesis__thesis_get_node` | Get a single node by ID |
+| 7 | `mcp__thesis__thesis_get_node_tree` | Get the subtree rooted at a node |
+| 8 | `mcp__thesis__thesis_get_node_ancestry` | Get the ancestor chain of a node |
+| 9 | `mcp__thesis__thesis_summarize_node_tree` | Get a condensed summary of a subtree |
+| 10 | `mcp__thesis__thesis_get_campaign_snapshot` | Get the current campaign snapshot |
+| 11 | `mcp__thesis__thesis_list_audit` | List audit log entries |
+| 12 | `mcp__thesis__thesis_resolve_node_slug` | Resolve a human-readable slug to a node ID |
+
+### Node Mutation, Branching, and Commit
+
+| # | Tool | Purpose |
+|---|------|---------|
+| 13 | `mcp__thesis__thesis_stage_node_create` | Create a new node in staged (draft) state |
+| 14 | `mcp__thesis__thesis_stage_node_update` | Update fields on a staged node |
+| 15 | `mcp__thesis__thesis_commit_node` | Commit a staged node with kind, outcome, summary |
+| 16 | `mcp__thesis__thesis_branch_node` | Create a child branch from an existing node |
+| 17 | `mcp__thesis__thesis_merge_nodes` | Merge two or more nodes |
+| 18 | `mcp__thesis__thesis_add_parent` | Add an additional parent edge to a node |
+| 19 | `mcp__thesis__thesis_remove_parent` | Remove a parent edge from a node |
+| 20 | `mcp__thesis__thesis_delete_node` | Delete a single node |
+| 21 | `mcp__thesis__thesis_bulk_delete_nodes` | Delete multiple nodes in one call |
+
+### Access Policy and Collaboration
+
+| # | Tool | Purpose |
+|---|------|---------|
+| 22 | `mcp__thesis__thesis_get_node_sharing` | Get sharing/access policy for a node |
+| 23 | `mcp__thesis__thesis_set_sharing_for_node` | Set sharing policy on a single node |
+| 24 | `mcp__thesis__thesis_set_sharing_for_nodes` | Set sharing policy on multiple nodes |
+
+### Tags and Graph Annotation
+
+| # | Tool | Purpose |
+|---|------|---------|
+| 25 | `mcp__thesis__thesis_create_node_tag` | Create a new tag definition |
+| 26 | `mcp__thesis__thesis_update_node_tag` | Update an existing tag |
+| 27 | `mcp__thesis__thesis_delete_node_tag` | Delete a tag definition |
+| 28 | `mcp__thesis__thesis_set_node_tag_assignments` | Assign or remove tags on nodes |
+
+### Artifacts
+
+| # | Tool | Purpose |
+|---|------|---------|
+| 29 | `mcp__thesis__thesis_list_artifacts` | List artifacts attached to a node |
+| 30 | `mcp__thesis__thesis_get_artifact` | Get metadata for a single artifact |
+| 31 | `mcp__thesis__thesis_get_artifact_preview` | Get a preview/thumbnail of an artifact |
+| 32 | `mcp__thesis__thesis_prepare_artifact_uploads` | Prepare signed URLs for artifact upload |
+| 33 | `mcp__thesis__thesis_finalize_artifact_uploads` | Finalize an artifact upload batch |
+| 34 | `mcp__thesis__thesis_set_artifact_note` | Set or update the note on an artifact |
+| 35 | `mcp__thesis__thesis_delete_artifact` | Delete an artifact |
+
+Common artifact types include:
+`text`, `table`, `json`, `image`, `banner`, `html`, `plotly_html`, `vega`,
+`checkpoint`, and `diff_carousel`.
+
+### Export and Import
+
+| # | Tool | Purpose |
+|---|------|---------|
+| 36 | `mcp__thesis__thesis_export_subgraph` | Export a subgraph as a portable bundle |
+| 37 | `mcp__thesis__thesis_import_subgraph` | Import a previously exported subgraph |
+| 38 | `mcp__thesis__thesis_export_summary` | Export a text summary of a subtree |
+| 39 | `mcp__thesis__thesis_export_summary_stream` | Stream a text summary of a subtree |
+| 40 | `mcp__thesis__thesis_export_summary_pdf` | Export a summary as PDF |
+| 41 | `mcp__thesis__thesis_export_summary_render_pdf` | Render and export a summary as PDF |
+
+### Executions
+
+| # | Tool | Purpose |
+|---|------|---------|
+| 42 | `mcp__thesis__thesis_launch_execution` | Launch a compute execution on a node |
+| 43 | `mcp__thesis__thesis_list_executions` | List executions with optional filters |
+| 44 | `mcp__thesis__thesis_terminate_execution` | Terminate a running execution |
+
+### Managed Compute
+
+| # | Tool | Purpose |
+|---|------|---------|
+| 45 | `mcp__thesis__thesis_approval_session_heartbeat` | Keep an approval session alive |
+| 46 | `mcp__thesis__thesis_list_approval_sessions` | List active approval sessions |
+| 47 | `mcp__thesis__thesis_expire_approval_session` | Expire an approval session |
+| 48 | `mcp__thesis__thesis_request_compute_grant_approval` | Request compute grant approval from budget holder |
+| 49 | `mcp__thesis__thesis_list_compute_grants` | List compute grants available to you |
+| 50 | `mcp__thesis__thesis_compute_list_options` | List available compute options (GPU types, regions) |
+| 51 | `mcp__thesis__thesis_compute_acquire` | Acquire a compute instance |
+| 52 | `mcp__thesis__thesis_compute_status` | Check status of an acquired compute instance |
+| 53 | `mcp__thesis__thesis_compute_connection` | Get connection details for an acquired instance |
+| 54 | `mcp__thesis__thesis_compute_release` | Release a single compute instance |
+| 55 | `mcp__thesis__thesis_compute_release_all` | Release all acquired compute instances |
+
+### Campaign Budgets (Organizer Flows)
+
+| # | Tool | Purpose |
+|---|------|---------|
+| 56 | `mcp__thesis__thesis_list_campaign_budgets` | List campaign budgets |
+| 57 | `mcp__thesis__thesis_create_campaign_budget` | Create a new campaign budget |
+| 58 | `mcp__thesis__thesis_update_campaign_budget` | Update an existing campaign budget |
+| 59 | `mcp__thesis__thesis_revoke_campaign_budget` | Revoke a campaign budget |
+
+### Updates and Notifications
+
+| # | Tool | Purpose |
+|---|------|---------|
+| 60 | `mcp__thesis__thesis_updates_list` | List pending updates/notifications |
+| 61 | `mcp__thesis__thesis_updates_hide` | Hide a specific update |
+| 62 | `mcp__thesis__thesis_updates_hide_all_active` | Hide all active updates |
+| 63 | `mcp__thesis__thesis_updates_unhide` | Unhide a previously hidden update |
+
+### Migration Helpers
+
+Some installations may expose migration-only helper tools with hashed names.
+Treat these as specialized one-off tools, not part of day-to-day research
+workflows.
+
+## Practical Tool Sequences
+
+### Insight Node Flow
+
+Use this flow to capture rationale, synthesis, design decisions, or any
+non-empirical knowledge.
+
+1. `mcp__thesis__thesis_stage_node_create` -- create a staged insight node
+2. `mcp__thesis__thesis_stage_node_update` -- populate content, summary, insights
+3. `mcp__thesis__thesis_commit_node` -- commit with `kind: insight`, non-empty `insights`
+
+### Empirical Node With Artifacts
+
+Use this flow when the node represents work that produces evidence: experiment
+runs, benchmark results, data analysis.
+
+1. `mcp__thesis__thesis_stage_node_create` -- create a staged empirical node
+2. `mcp__thesis__thesis_stage_node_update` -- populate hypothesis, content, summary
+3. Run experiment or compute steps
+4. `mcp__thesis__thesis_prepare_artifact_uploads` -- get signed URLs
+5. Upload artifact bytes to signed URLs (HTTP PUT)
+6. `mcp__thesis__thesis_finalize_artifact_uploads` -- finalize the batch
+7. `mcp__thesis__thesis_commit_node` -- commit with `kind: empirical`, non-empty `hypothesis`, artifacts present
+
+### Managed Compute Flow
+
+Use this flow to acquire GPU or other managed compute for empirical work.
+
+1. `mcp__thesis__thesis_approval_session_heartbeat` -- start/maintain approval session
+2. `mcp__thesis__thesis_request_compute_grant_approval` -- request budget approval
+3. `mcp__thesis__thesis_list_compute_grants` -- (if needed) verify grant exists
+4. `mcp__thesis__thesis_compute_acquire` -- acquire the instance
+5. `mcp__thesis__thesis_compute_status` -- poll until ready
+6. `mcp__thesis__thesis_compute_connection` -- get SSH/connection details
+7. `mcp__thesis__thesis_compute_release` -- release when done (or `..._release_all`)
+
+### Share a Graph With Collaborators
+
+1. `mcp__thesis__thesis_get_node_sharing` -- check current sharing state
+2. `mcp__thesis__thesis_set_sharing_for_node` -- (or `..._for_nodes`) set access
+3. `mcp__thesis__thesis_export_summary` or `..._export_subgraph` -- for handoff
+
+## Safety Notes
+
+- Prefer `get_contract` before implementing strict assumptions in automation.
+- Avoid call-order assumptions not mandated by contract.
+- Keep checks bounded: list/read first, then mutate only the intended nodes.
+- Always verify `expected_revision` before mutation to avoid lost updates.
+- Never skip the two-step artifact upload flow (prepare then finalize).
+- Release compute instances when work is complete to avoid unnecessary charges.