From 6acf08f80d802fb37dadc7a24a2d59f6a074cfcf Mon Sep 17 00:00:00 2001
From: Ryan Malloy <ryan@supported.systems>
Date: Fri, 20 Feb 2026 16:15:37 -0700
Subject: [PATCH] Add SpiceBook docs -- reference page, tutorial, and updated
 indexes

New pages:
- reference/spicebook: all 5 SpiceBook tools with params, returns, examples
- tutorials/publish-to-spicebook: end-to-end workflow guide

Updated pages:
- reference/index: add SpiceBook LinkCard, bump tool/resource/prompt counts
- reference/resources: add spicebook://status resource
- reference/prompts: add publish_to_spicebook prompt
- tutorials/index: add Publish to SpiceBook LinkCard
- sidebar: SpiceBook entry with "New" badge
---
 docs/astro.config.mjs                         |   2 +
 docs/src/content/docs/reference/index.mdx     |  16 +-
 docs/src/content/docs/reference/prompts.mdx   |  31 ++-
 docs/src/content/docs/reference/resources.mdx |  15 +-
 docs/src/content/docs/reference/spicebook.mdx | 194 ++++++++++++++++++
 docs/src/content/docs/tutorials/index.mdx     |   1 +
 .../docs/tutorials/publish-to-spicebook.mdx   | 115 +++++++++++
 7 files changed, 367 insertions(+), 7 deletions(-)
 create mode 100644 docs/src/content/docs/reference/spicebook.mdx
 create mode 100644 docs/src/content/docs/tutorials/publish-to-spicebook.mdx

diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index b7ba5ae..bf70f0a 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -40,6 +40,7 @@ export default defineConfig({
             { label: 'Overview', slug: 'tutorials' },
             { label: 'Design a Filter', slug: 'tutorials/design-a-filter' },
             { label: 'Monte Carlo Yield', slug: 'tutorials/monte-carlo-yield' },
+            { label: 'Publish to SpiceBook', slug: 'tutorials/publish-to-spicebook' },
           ],
         },
         {
@@ -54,6 +55,7 @@ export default defineConfig({
             { label: 'Stability & Power', slug: 'reference/stability-power' },
             { label: 'Schematic & Netlist', slug: 'reference/schematic-netlist' },
             { label: 'Library & Templates', slug: 'reference/library-templates' },
+            { label: 'SpiceBook', slug: 'reference/spicebook', badge: { text: 'New', variant: 'note' } },
             { label: 'Resources', slug: 'reference/resources' },
             { label: 'Prompts', slug: 'reference/prompts' },
           ],
diff --git a/docs/src/content/docs/reference/index.mdx b/docs/src/content/docs/reference/index.mdx
index 33ddf48..4ce1119 100644
--- a/docs/src/content/docs/reference/index.mdx
+++ b/docs/src/content/docs/reference/index.mdx
@@ -5,7 +5,7 @@ description: Complete reference for all mcltspice tools, resources, and prompts.
 
 import { LinkCard } from '@astrojs/starlight/components';
 
-mcltspice exposes 37 tools, 5 resources, and 7 prompts. This section documents every one of them with parameter types, defaults, return values, and usage notes.
+mcltspice exposes 42 tools, 6 resources, and 8 prompts. This section documents every one of them with parameter types, defaults, return values, and usage notes.
 
 ## Tools by category
 
@@ -51,16 +51,22 @@ mcltspice exposes 37 tools, 5 resources, and 7 prompts. This section documents e
   href="/reference/library-templates/"
 />
 
+<LinkCard
+  title="SpiceBook (5 tools)"
+  description="Publish circuits as interactive notebooks on SpiceBook, run remote ngspice simulations, list and manage published notebooks."
+  href="/reference/spicebook/"
+/>
+
 ## Resources and prompts
 
 <LinkCard
-  title="Resources (5 URIs)"
-  description="Read-only data sources exposed via MCP resource URIs --- symbols, examples, status, templates, and template detail."
+  title="Resources (6 URIs)"
+  description="Read-only data sources exposed via MCP resource URIs --- symbols, examples, status, templates, template detail, and SpiceBook status."
   href="/reference/resources/"
 />
 
 <LinkCard
-  title="Prompts (7 prompts)"
-  description="Guided workflows for filter design, power supply analysis, debugging, optimization, Monte Carlo, circuit creation, and troubleshooting."
+  title="Prompts (8 prompts)"
+  description="Guided workflows for filter design, power supply analysis, debugging, optimization, Monte Carlo, circuit creation, troubleshooting, and SpiceBook publishing."
   href="/reference/prompts/"
 />
diff --git a/docs/src/content/docs/reference/prompts.mdx b/docs/src/content/docs/reference/prompts.mdx
index cb99c13..e7e50a6 100644
--- a/docs/src/content/docs/reference/prompts.mdx
+++ b/docs/src/content/docs/reference/prompts.mdx
@@ -7,7 +7,7 @@ import { Aside, Code } from '@astrojs/starlight/components';
 
 MCP prompts are conversation starters. Each prompt generates an initial message that guides the LLM through a multi-step workflow, telling it which tools to call and in what order. Think of them as runbooks --- they encode best practices so the LLM does not have to figure out the workflow from scratch.
 
-mcltspice provides 7 prompts covering filter design, power supply analysis, debugging, optimization, Monte Carlo yield analysis, building circuits from descriptions, and troubleshooting simulation failures.
+mcltspice provides 8 prompts covering filter design, power supply analysis, debugging, optimization, Monte Carlo yield analysis, building circuits from descriptions, troubleshooting simulation failures, and publishing to SpiceBook.
 
 <Aside type="note">
   Prompt support varies by client. In Claude Code, prompts appear as suggested workflows. In other MCP clients, they may be listed in a prompt library or triggered from a menu.
@@ -225,3 +225,32 @@ A diagnostic checklist for simulation failures and convergence issues. Works thr
 - Unexpected clipping: check supply voltages and headroom
 - Oscillation in DC circuits: add small feedback capacitors
 - Model not found: verify `.lib` / `.include` paths
+
+---
+
+## publish_to_spicebook
+
+Guides through publishing a circuit as an interactive notebook on [SpiceBook](https://spicebook.warehack.ing): verify locally in LTspice, test ngspice compatibility, publish with metadata, and verify the result.
+
+<table class="param-table">
+  <thead>
+    <tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>circuit_description</td><td><code>str</code></td><td><code>""</code></td><td>Description of the circuit to publish. If empty, the prompt asks the LLM to describe it.</td></tr>
+    <tr><td>netlist_path</td><td><code>str</code></td><td><code>""</code></td><td>Path to the netlist or schematic. If empty, the prompt asks the LLM to identify or create one first.</td></tr>
+  </tbody>
+</table>
+
+**Workflow steps:**
+
+1. **Verify locally** --- simulate with `simulate` or `simulate_netlist`, check results with `get_waveform` and `analyze_waveform`
+2. **Test ngspice compatibility** --- run `spicebook_simulate` to dry-run the converted netlist on SpiceBook's engine; review any conversion warnings
+3. **Publish** --- use `spicebook_publish` with title, description, and tags; optionally set `run=True` for immediate simulation
+4. **Verify** --- use `spicebook_get` to confirm the notebook was created; share the URL
+
+**Tips included in the prompt:**
+- Add tags like `"filter"`, `"amplifier"`, `"power"` for discoverability
+- The converter handles `.backanno`, `Rser=`, and Windows paths automatically
+- Use `spicebook_list` to see all published notebooks
+- Use `spicebook_delete` to clean up test notebooks
diff --git a/docs/src/content/docs/reference/resources.mdx b/docs/src/content/docs/reference/resources.mdx
index 3b7765d..402859d 100644
--- a/docs/src/content/docs/reference/resources.mdx
+++ b/docs/src/content/docs/reference/resources.mdx
@@ -7,7 +7,7 @@ import { Aside } from '@astrojs/starlight/components';
 
 MCP resources are read-only data sources that clients can attach to conversations for context. Unlike tools, resources are not invoked with parameters --- they are referenced by URI and return structured data. A client might attach `ltspice://status` at the start of a session so the LLM knows what is available without making a tool call.
 
-mcltspice exposes 5 resources.
+mcltspice exposes 6 resources.
 
 <Aside type="note">
   Resource support varies by MCP client. Claude Code currently reads resources when they are referenced in conversation context. Other clients may list available resources in a sidebar or attach them automatically.
@@ -151,3 +151,16 @@ If the template exists in only one format (netlist or schematic), only that key
 <Aside type="tip">
   Use `ltspice://templates` to discover all available template names, then query `ltspice://template/{name}` for the one you need.
 </Aside>
+
+---
+
+## spicebook://status
+
+Current SpiceBook service status --- URL and reachability. Attaching this resource lets the LLM know whether SpiceBook is available for publishing without making a tool call.
+
+```
+SpiceBook URL: https://spicebook.warehack.ing
+Status: reachable
+```
+
+If SpiceBook is unreachable (network issue, service down), the status will show `unreachable`. The URL can be changed via the `SPICEBOOK_URL` environment variable.
diff --git a/docs/src/content/docs/reference/spicebook.mdx b/docs/src/content/docs/reference/spicebook.mdx
new file mode 100644
index 0000000..76b13cc
--- /dev/null
+++ b/docs/src/content/docs/reference/spicebook.mdx
@@ -0,0 +1,194 @@
+---
+title: SpiceBook Integration
+description: Publish circuits as interactive notebooks, run remote ngspice simulations, and manage notebooks on SpiceBook.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+These tools bridge mcltspice with [SpiceBook](https://spicebook.warehack.ing), a web notebook service for SPICE circuits. You can publish LTspice designs as interactive, runnable notebooks --- shareable via URL --- and test ngspice compatibility without leaving your MCP session.
+
+<Aside type="tip">
+  The `publish_to_spicebook` prompt walks through the full workflow: verify locally, test ngspice compatibility, then publish. See [Prompts](/reference/prompts/#publish_to_spicebook).
+</Aside>
+
+---
+
+### spicebook_publish
+
+Publish an LTspice netlist as an interactive SpiceBook notebook. Reads the netlist from a string or file, converts it from LTspice dialect to ngspice (stripping `.backanno`, `Rser=`, Windows paths), builds notebook cells with an intro and the netlist, and creates the notebook via SpiceBook's compose endpoint.
+
+<table class="param-table">
+<thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>netlist_text</td><td>`str | None`</td><td>`None`</td><td>Netlist as a string. Mutually exclusive with `netlist_path`.</td></tr>
+<tr><td>netlist_path</td><td>`str | None`</td><td>`None`</td><td>Path to a `.cir`, `.net`, `.sp`, `.spice`, or `.asc` file on disk.</td></tr>
+<tr><td>title</td><td>`str`</td><td>`"Untitled Circuit"`</td><td>Notebook title, shown in the listing and intro cell.</td></tr>
+<tr><td>description</td><td>`str | None`</td><td>`None`</td><td>Circuit description, rendered in the intro markdown cell.</td></tr>
+<tr><td>tags</td><td>`list[str] | None`</td><td>`None`</td><td>Tags for categorization and search (e.g. `["filter", "audio"]`).</td></tr>
+<tr><td>run</td><td>`bool`</td><td>`False`</td><td>If `True`, SpiceBook runs the simulation immediately on publish.</td></tr>
+</tbody>
+</table>
+
+**Returns:** A dict with `notebook_id`, `url` (direct link to the notebook), `cell_count`, and `conversion_warnings` (list of strings describing any LTspice-to-ngspice changes).
+
+<details>
+<summary>Example</summary>
+
+```json
+{
+  "notebook_id": "rc-lowpass-filter-a3b2c1d4",
+  "url": "https://spicebook.warehack.ing/notebooks/rc-lowpass-filter-a3b2c1d4",
+  "cell_count": 2,
+  "conversion_warnings": [
+    "Stripped Rser= from: C1 out 0 100n Rser=0.1"
+  ]
+}
+```
+
+</details>
+
+<Aside type="note">
+  The converter handles four LTspice-to-ngspice incompatibilities automatically: `.backanno` directives, `.options plotwinsize=0`, `.lib`/`.include` with Windows paths, and `Rser=` parasitic ESR on capacitors and inductors. Standard SPICE passes through untouched. Any changes are reported in `conversion_warnings`.
+</Aside>
+
+---
+
+### spicebook_simulate
+
+Run a netlist via SpiceBook's ngspice engine without creating a notebook. Useful for testing whether a netlist is ngspice-compatible before publishing. The netlist is converted from LTspice dialect first.
+
+<table class="param-table">
+<thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>netlist_text</td><td>`str | None`</td><td>`None`</td><td>Netlist as a string. Mutually exclusive with `netlist_path`.</td></tr>
+<tr><td>netlist_path</td><td>`str | None`</td><td>`None`</td><td>Path to a netlist file on disk.</td></tr>
+</tbody>
+</table>
+
+**Returns:** The simulation result from SpiceBook's ngspice engine, plus `conversion_warnings` if any LTspice constructs were modified.
+
+<details>
+<summary>Example</summary>
+
+```json
+{
+  "stdout": "...",
+  "stderr": "",
+  "returncode": 0,
+  "conversion_warnings": []
+}
+```
+
+</details>
+
+---
+
+### spicebook_list
+
+List all notebooks on SpiceBook. No parameters.
+
+**Returns:** A dict with `notebooks` (array of notebook summaries) and `count`.
+
+<details>
+<summary>Example</summary>
+
+```json
+{
+  "notebooks": [
+    {
+      "id": "rc-lowpass-filter-a3b2c1d4",
+      "metadata": {
+        "title": "RC Lowpass Filter",
+        "tags": ["filter", "analog"],
+        "modified": "2026-02-15T21:45:24Z"
+      }
+    }
+  ],
+  "count": 1
+}
+```
+
+</details>
+
+---
+
+### spicebook_get
+
+Retrieve a full SpiceBook notebook with all cells and outputs.
+
+<table class="param-table">
+<thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>notebook_id</td><td>`str`</td><td>---</td><td>The notebook ID to retrieve.</td></tr>
+</tbody>
+</table>
+
+**Returns:** The complete notebook object including `metadata` (title, tags, engine, timestamps), `cells` (array of cell objects with type, source, and outputs), and `spicebook_version`.
+
+<details>
+<summary>Example</summary>
+
+```json
+{
+  "spicebook_version": "2026-02-13",
+  "metadata": {
+    "title": "RC Lowpass Filter",
+    "engine": "ngspice",
+    "tags": ["filter"],
+    "created": "2026-02-15T21:45:24Z",
+    "modified": "2026-02-15T21:45:24Z"
+  },
+  "cells": [
+    {
+      "id": "cell-abc123",
+      "type": "markdown",
+      "source": "# RC Lowpass Filter\n\nFirst-order filter with fc = 1.59 kHz",
+      "outputs": []
+    },
+    {
+      "id": "cell-def456",
+      "type": "spice",
+      "source": "V1 in 0 AC 1\nR1 in out 1k\nC1 out 0 100n\n.ac dec 100 1 1meg\n.end",
+      "outputs": []
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### spicebook_delete
+
+Delete a SpiceBook notebook.
+
+<table class="param-table">
+<thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>notebook_id</td><td>`str`</td><td>---</td><td>The notebook ID to delete.</td></tr>
+</tbody>
+</table>
+
+**Returns:** `{"deleted": true, "notebook_id": "..."}` on success.
+
+---
+
+## Configuration
+
+SpiceBook tools read two environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SPICEBOOK_URL` | `https://spicebook.warehack.ing` | Base URL of the SpiceBook instance. |
+| `SPICEBOOK_TIMEOUT` | `30` | HTTP request timeout in seconds. |
+
+No authentication is required.
+
+## Error handling
+
+All SpiceBook tools return structured error dicts on failure:
+
+- **Unreachable:** `{"error": "SpiceBook not reachable at <url>", "hint": "Check connectivity or set SPICEBOOK_URL env var"}`
+- **Timeout:** `{"error": "SpiceBook request timed out"}`
+- **HTTP error:** `{"error": "HTTP <status>", "detail": "<response body>"}`
diff --git a/docs/src/content/docs/tutorials/index.mdx b/docs/src/content/docs/tutorials/index.mdx
index ae37d05..a9e678b 100644
--- a/docs/src/content/docs/tutorials/index.mdx
+++ b/docs/src/content/docs/tutorials/index.mdx
@@ -10,4 +10,5 @@ Tutorials walk you through complete workflows from start to finish. Each one bui
 <CardGrid>
   <LinkCard title="Design a Filter" href="/tutorials/design-a-filter/" description="Build an RC lowpass filter, measure its bandwidth, and iterate toward a target cutoff frequency." />
   <LinkCard title="Monte Carlo Yield" href="/tutorials/monte-carlo-yield/" description="Run statistical analysis on component tolerances to estimate manufacturing yield." />
+  <LinkCard title="Publish to SpiceBook" href="/tutorials/publish-to-spicebook/" description="Convert an LTspice circuit to ngspice and publish it as an interactive notebook on SpiceBook." />
 </CardGrid>
diff --git a/docs/src/content/docs/tutorials/publish-to-spicebook.mdx b/docs/src/content/docs/tutorials/publish-to-spicebook.mdx
new file mode 100644
index 0000000..bc658d2
--- /dev/null
+++ b/docs/src/content/docs/tutorials/publish-to-spicebook.mdx
@@ -0,0 +1,115 @@
+---
+title: Publish to SpiceBook
+description: Design a circuit in LTspice, verify it works, and publish it as an interactive notebook on SpiceBook.
+---
+
+import { Steps, Aside, Code } from '@astrojs/starlight/components';
+
+## Goal
+
+Take an LTspice circuit, convert it to ngspice format, and publish it as an interactive notebook on [SpiceBook](https://spicebook.warehack.ing) --- shareable via URL and runnable in the browser.
+
+## Workflow
+
+<Steps>
+
+1. **Create and simulate the circuit locally**
+
+   Start by building the circuit with mcltspice and verifying it works in LTspice. Here we use the built-in RC lowpass template:
+
+   ```json
+   // create_from_template
+   {
+     "template": "rc_lowpass",
+     "params": { "r": "10k", "c": "1n" }
+   }
+   ```
+
+   Then simulate:
+
+   ```json
+   // simulate_netlist
+   {
+     "netlist_path": "/tmp/rc_lowpass.cir"
+   }
+   ```
+
+   Confirm the simulation succeeds and check the frequency response with `measure_bandwidth` to verify the cutoff is around 15.9 kHz (1 / (2 * pi * 10k * 1n)).
+
+2. **Test ngspice compatibility**
+
+   LTspice and ngspice have dialect differences. Before publishing, do a dry run on SpiceBook's ngspice engine:
+
+   ```json
+   // spicebook_simulate
+   {
+     "netlist_path": "/tmp/rc_lowpass.cir"
+   }
+   ```
+
+   Check the result for errors. If `conversion_warnings` appears, the converter handled known LTspice-isms automatically (`.backanno`, `Rser=`, Windows paths). If the simulation fails, adjust the netlist to remove any unsupported constructs.
+
+3. **Publish the notebook**
+
+   Once ngspice compatibility is confirmed, publish with a descriptive title and tags:
+
+   ```json
+   // spicebook_publish
+   {
+     "netlist_path": "/tmp/rc_lowpass.cir",
+     "title": "RC Lowpass Filter - 15.9 kHz Cutoff",
+     "description": "First-order RC lowpass with R=10k, C=1n. AC analysis from 1 Hz to 1 MHz.",
+     "tags": ["filter", "lowpass", "analog", "first-order"]
+   }
+   ```
+
+   The response includes a direct URL to the notebook:
+
+   ```json
+   {
+     "notebook_id": "rc-lowpass-filter-15-9-khz-cutoff-a1b2c3d4",
+     "url": "https://spicebook.warehack.ing/notebooks/rc-lowpass-filter-15-9-khz-cutoff-a1b2c3d4",
+     "cell_count": 2,
+     "conversion_warnings": []
+   }
+   ```
+
+4. **Verify the published notebook**
+
+   Retrieve the notebook to confirm it was created correctly:
+
+   ```json
+   // spicebook_get
+   {
+     "notebook_id": "rc-lowpass-filter-15-9-khz-cutoff-a1b2c3d4"
+   }
+   ```
+
+   The notebook is now live at the URL and can be shared with anyone. Visitors can view the netlist, modify it, and run simulations directly in the browser.
+
+</Steps>
+
+<Aside type="tip">
+  Set `run: true` in `spicebook_publish` to have SpiceBook execute the simulation immediately on publish. The notebook will already have simulation results when visitors open it.
+</Aside>
+
+## Managing notebooks
+
+Use `spicebook_list` to see all published notebooks, and `spicebook_delete` to remove any that are no longer needed --- useful for cleaning up test notebooks.
+
+## What gets converted
+
+The publish tool automatically converts four LTspice-specific constructs to ngspice-compatible equivalents:
+
+| LTspice construct | What happens |
+|---|---|
+| `.backanno` | Stripped (LTspice annotation directive) |
+| `.options plotwinsize=0` | Stripped (LTspice buffer setting) |
+| `.lib` / `.include` with Windows paths | Commented out with a warning |
+| `Rser=` on capacitors or inductors | Stripped with a warning |
+
+All changes are reported in `conversion_warnings` so you know exactly what was modified. Standard SPICE passes through untouched.
+
+## Key takeaway
+
+The full workflow --- design, simulate, verify, publish --- can happen in a single MCP session. SpiceBook notebooks are interactive: anyone with the URL can view, edit, and re-run the circuit without installing LTspice.