npm - @pyric/cli - Versions diffs - 0.1.0-alpha.9 - Mend

@pyric/cli 0.1.0-alpha.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1169) hide show

package/dist/serve/docs-ui/docs/pyric-cli-tutorials-wire-claude-code/index.html ADDED Viewed

@@ -0,0 +1,136 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Wire Claude Code to your pyric sandbox (manual MCP wiring) · Pyric Studio</title><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.CQYSemvw.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/" aria-current="true"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/" aria-current="true"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="/__pyric/ui/docs/pyric-cli/">@pyric/cli</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Tutorials</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Wire Claude Code</span> </li> </ol> </nav>  <article class="prose">  <h1 id="wire-claude-code-to-your-pyric-sandbox-manual-mcp-wiring">Wire Claude Code to your pyric sandbox (manual MCP wiring)</h1>
+<blockquote>
+<p><strong>Most users want the plugin instead.</strong> <code>claude plugin install</code> +
+<code>/pyric:pyric-start</code> does everything below automatically, see
+<a href="../start-building/">getting-started.md</a>. This tutorial is the
+manual path: wiring Claude Code to a bridge yourself, e.g. for a
+sandbox embedded in your own dev server, a custom port layout, or an
+MCP client other than Claude Code.</p>
+</blockquote>
+<p>By the end of this tutorial you will have:</p>
+<ul>
+<li>A running pyric bridge on <code>127.0.0.1:5174</code>.</li>
+<li>Your existing Firebase app’s in-browser pyric sandbox connected to the bridge.</li>
+<li>Claude Code configured to talk to the bridge via MCP-over-HTTP.</li>
+<li>A successful end-to-end tool call from Claude Code into your browser-resident Firestore sandbox.</li>
+</ul>
+<p>Should take ~10 minutes.</p>
+<h2 id="prerequisites">Prerequisites</h2>
+<ul>
+<li>An existing Firebase app already retrofitted to use pyric, i.e. you’ve replaced the relevant <code>firebase/*</code> imports with <code>@pyric/*</code> adapter SDKs and your app boots against <code>initializeSandbox()</code> in dev. (If you haven’t done the retrofit yet, do that first: see the per-package READMEs under <code>packages/*/README.md</code>.)</li>
+<li>Claude Code installed and working. Verify with <code>claude --version</code>.</li>
+<li>Node 22+ and <code>npm</code> / <code>bun</code>. This tutorial uses <code>npm</code> in commands; <code>bun</code> works equivalently.</li>
+</ul>
+<h2 id="step-1-install-pyric">Step 1: Install pyric</h2>
+<p>In your app’s repo:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#61AFEF">npm</span><span style="color:#98C379"> install</span><span style="color:#D19A66"> --save-dev</span><span style="color:#98C379"> pyric</span></span></code></pre>
+<p>This pulls in the bridge implementation (<code>@pyric/cli/bridge</code>) as part of <code>@pyric/cli</code>.</p>
+<p>Verify:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#61AFEF">npx</span><span style="color:#98C379"> pyric</span><span style="color:#D19A66"> --version</span></span></code></pre>
+<p>Expected output: a version string (e.g. <code>0.0.0</code>).</p>
+<h2 id="step-2-connect-your-app-to-the-bridge">Step 2: Connect your app to the bridge</h2>
+<p>The bridge waits for a browser tab to register a sandbox over WebSocket. Your app needs to call <code>connectBridge()</code> from <code>@pyric/cli/bridge</code> (browser entry) in dev mode.</p>
+<p><strong>Vite users</strong>: the simplest path. Use the <code>pyricSandbox</code> plugin with <code>bridge: true</code>. One plugin does the <code>firebase/*</code> → sandbox swap <strong>and</strong> the bridge, so you don’t even add the <code>connectBridge</code> snippet below:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">defineConfig</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'vite'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">pyricSandbox</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/cli/vite'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">export</span><span style="color:#C678DD"> default</span><span style="color:#61AFEF"> defineConfig</span><span style="color:#ABB2BF">({</span></span>
+<span class="line"><span style="color:#E06C75">  plugins</span><span style="color:#ABB2BF">: [</span><span style="color:#61AFEF">pyricSandbox</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">bridge</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF"> })],</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span></code></pre>
+<p>The plugin attaches the bridge to Vite’s own dev server (so it shares Vite’s port instead of running as a sidecar) AND wires the browser side automatically via the served init payload. You can skip Step 3 and 4: your app is already wired. <code>bridge: true</code> routes the agent’s tool-calls through the <strong>SharedWorker</strong>, so the agent, your app, and Pyric Studio all share one sandbox (keep a tab open while the agent works); see <a href="../pyric-cli-how-to-use-the-vite-plugin/#drive-the-sandbox-from-an-agent-bridge">Use the Vite plugin</a>.</p>
+<p><strong>Non-Vite users</strong>: add a small dev-mode snippet wherever your app initializes the sandbox:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#7F848E;font-style:italic">// e.g. src/main.ts or wherever you call initializeSandbox()</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">initializeSandbox</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/sandbox'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">connectBridge</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/cli/bridge'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> sandbox</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> initializeSandbox</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">if</span><span style="color:#ABB2BF"> (</span><span style="color:#C678DD">import</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">meta</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">env</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">DEV</span><span style="color:#7F848E;font-style:italic"> /* or NODE_ENV === 'development' */</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#61AFEF">  connectBridge</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">sandbox</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>The conditional gate is important: <code>connectBridge</code> opens a WebSocket to <code>127.0.0.1:5174</code>, which doesn’t exist in production. Without the gate, your production build would attempt a failed WebSocket handshake on page load.</p>
+<h2 id="step-3-start-the-bridge-non-vite-users-only">Step 3: Start the bridge (non-Vite users only)</h2>
+<p>Open a new terminal in your app’s directory and run:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#61AFEF">npx</span><span style="color:#98C379"> pyric</span><span style="color:#98C379"> bridge</span></span></code></pre>
+<p>Expected output:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="plaintext"><code><span class="line"><span>pyric bridge 0.0.0 — mode: sandbox, project: sandbox</span></span>
+<span class="line"><span>  listening on http://127.0.0.1:5174</span></span>
+<span class="line"><span>  health:  http://127.0.0.1:5174/health</span></span>
+<span class="line"><span>  mcp:     http://127.0.0.1:5174/mcp</span></span>
+<span class="line"><span>  sandbox: ws://127.0.0.1:5174/sandbox</span></span>
+<span class="line"><span>  audit:   /Users/you/.pyric/projects/sandbox/events.ndjson</span></span>
+<span class="line"><span></span></span>
+<span class="line"><span>Waiting for browser tab to connect. Ctrl-C to stop.</span></span></code></pre>
+<p>Leave this terminal running.</p>
+<blockquote>
+<p>Vite users: skip this step, the bridge already runs as part of <code>npm run dev</code>.</p>
+</blockquote>
+<h2 id="step-4-verify-the-bridge-is-reachable">Step 4: Verify the bridge is reachable</h2>
+<p>In a third terminal:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#61AFEF">curl</span><span style="color:#98C379"> http://127.0.0.1:5174/health</span></span></code></pre>
+<p>Expected:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="json"><code><span class="line"><span style="color:#ABB2BF">{</span></span>
+<span class="line"><span style="color:#E06C75">  "status"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"ok"</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  "mode"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"sandbox"</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  "project"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"sandbox"</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  "sandboxConnected"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">false</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  "version"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"0.0.0"</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  "startedAt"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"2026-05-24T..."</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>The <code>sandboxConnected: false</code> is correct: no browser tab has registered yet. Vite users with the plugin: the URL is your Vite dev server’s, with <code>/__pyric/health</code> as the path (e.g. <code>http://localhost:5173/__pyric/health</code>).</p>
+<h2 id="step-5-open-your-app-in-a-browser">Step 5: Open your app in a browser</h2>
+<p>Run your usual dev command (<code>npm run dev</code>, <code>bun run dev</code>, …) and open the app in a browser. Your <code>connectBridge(sandbox)</code> call (Step 2) will run and open the WebSocket.</p>
+<p>Verify with another curl:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#61AFEF">curl</span><span style="color:#98C379"> http://127.0.0.1:5174/health</span></span></code></pre>
+<p>Expected: <code>"sandboxConnected": true</code>.</p>
+<p>If it’s still <code>false</code>, check the browser devtools console for WebSocket errors. The most common cause is the dev-mode gate (Step 2 conditional) being false. Add a <code>console.log('pyric: connecting')</code> line above <code>connectBridge(...)</code> to confirm it runs.</p>
+<h2 id="step-6-register-the-bridge-with-claude-code">Step 6: Register the bridge with Claude Code</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#61AFEF">claude</span><span style="color:#98C379"> mcp</span><span style="color:#98C379"> add</span><span style="color:#98C379"> pyric</span><span style="color:#D19A66"> --transport</span><span style="color:#98C379"> http</span><span style="color:#56B6C2"> \</span></span>
+<span class="line"><span style="color:#D19A66">  --url</span><span style="color:#98C379"> http://127.0.0.1:5174/mcp</span><span style="color:#56B6C2"> \</span></span>
+<span class="line"><span style="color:#D19A66">  --scope</span><span style="color:#98C379"> project</span></span></code></pre>
+<p><code>--scope project</code> writes the MCP config to <code>.mcp.json</code> in the current directory (checked into git, shared with your team). Other scopes:</p>
+<ul>
+<li><code>--scope user</code>: <code>~/.claude.json</code>, personal only.</li>
+<li><code>--scope local</code>: this machine, this project, not checked in.</li>
+</ul>
+<p>Verify the registration:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#61AFEF">claude</span><span style="color:#98C379"> mcp</span><span style="color:#98C379"> list</span></span></code></pre>
+<p>Expected: <code>pyric</code> shows in the list with <code>transport: http</code> and the URL.</p>
+<h2 id="step-7-confirm-claude-code-sees-the-bridge">Step 7: Confirm Claude Code sees the bridge</h2>
+<p>Inside Claude Code (in your terminal or IDE), run:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="plaintext"><code><span class="line"><span>/mcp</span></span></code></pre>
+<p>Expected: <code>pyric</code> appears as a configured MCP server, status <code>connected</code>. If status shows <code>disconnected</code>, check the bridge process is still running (Step 3 terminal) and the URL matches.</p>
+<p>If Claude Code was already running when you ran <code>claude mcp add</code>, you may need to restart it to pick up new project-scoped MCP config.</p>
+<h2 id="step-8-make-an-end-to-end-tool-call">Step 8: Make an end-to-end tool call</h2>
+<p>Ask Claude Code:</p>
+<blockquote>
+<p>“Use the pyric MCP to seed my Firestore sandbox with a <code>users/u1</code> document containing <code>{ name: 'Alice' }</code>, then read it back.”</p>
+</blockquote>
+<p>Expected behavior:</p>
+<ol>
+<li>Claude Code calls <code>pyric__firestore_simulator_create</code> and <code>pyric__firestore_simulator_execute</code> (the tools are namespaced by the MCP server name <code>pyric</code>).</li>
+<li>The bridge forwards both calls over WebSocket to your browser tab.</li>
+<li>Your browser’s <code>connectBridge()</code> dispatches them into <code>LocalEnvironment</code>.</li>
+<li>Results flow back to Claude Code.</li>
+<li>Claude Code reports success with the seeded + read document.</li>
+</ol>
+<p>Open the browser devtools and check the sandbox’s state: <code>users/u1</code> should be present.</p>
+<p>You can also verify via the audit log (sandbox events flow through the bridge’s <code>onToolEvent</code> hook):</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#61AFEF">tail</span><span style="color:#D19A66"> -n</span><span style="color:#D19A66"> 5</span><span style="color:#98C379"> ~/.pyric/projects/sandbox/events.ndjson</span></span></code></pre>
+<p>Each line is a JSON object with <code>tool</code>, <code>args</code>, <code>result</code>, <code>mode</code>, <code>timestamp</code>.</p>
+<h2 id="step-9-try-a-sandbox-management-tool">Step 9: Try a sandbox-management tool</h2>
+<p>Ask Claude Code:</p>
+<blockquote>
+<p>“Undo the last write, then redo it.”</p>
+</blockquote>
+<p>Expected: two tool calls (<code>firestore_simulator_undo</code>, <code>firestore_simulator_redo</code>) round-trip through the bridge. The undo restores prior state; redo re-applies.</p>
+<h2 id="troubleshooting">Troubleshooting</h2>
+<p><strong><code>sandboxConnected: false</code> even after opening the page.</strong> Either <code>connectBridge()</code> isn’t being called (dev-mode gate or path issue), or the WebSocket can’t reach the bridge (firewall, browser security policy on a non-localhost domain, port mismatch). Browser devtools Network tab → WS filter shows the handshake attempt and failure mode.</p>
+<p><strong>Tool call returns <code>"sandbox not connected"</code>.</strong> The browser tab disconnected (page closed, crashed, navigated away). Reopen the page; the bridge auto-accepts new connections (last-wins).</p>
+<p><strong>Multiple tabs open against the same app.</strong> Last-wins. The most recently connected tab is the active sandbox; previous tabs are inactive (their <code>connectBridge</code> keeps reconnecting and replaces). For v1 this is acceptable; multi-tab is a v1.1 question.</p>
+<p><strong>Port 5174 already in use.</strong> Another <code>pyric bridge</code> instance is running, OR another tool. Either kill the other process (<code>lsof -ti:5174 | xargs kill</code>) or run with <code>--port 5180</code> (and update your Claude Code MCP config to match).</p>
+<h2 id="next-steps">Next steps</h2>
+<ul>
+<li>Read <a href="../pyric-cli-bridge/">the bridge README</a> for the bridge architecture.</li>
+<li>The bridge audit log at <code>~/.pyric/projects/&#x3C;project>/events.ndjson</code> is the durable record of every tool call: review it after agent sessions.</li>
+</ul>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#prerequisites">Prerequisites</a> </li><li data-depth="2"> <a href="#step-1-install-pyric">Step 1: Install pyric</a> </li><li data-depth="2"> <a href="#step-2-connect-your-app-to-the-bridge">Step 2: Connect your app to the bridge</a> </li><li data-depth="2"> <a href="#step-3-start-the-bridge-non-vite-users-only">Step 3: Start the bridge (non-Vite users only)</a> </li><li data-depth="2"> <a href="#step-4-verify-the-bridge-is-reachable">Step 4: Verify the bridge is reachable</a> </li><li data-depth="2"> <a href="#step-5-open-your-app-in-a-browser">Step 5: Open your app in a browser</a> </li><li data-depth="2"> <a href="#step-6-register-the-bridge-with-claude-code">Step 6: Register the bridge with Claude Code</a> </li><li data-depth="2"> <a href="#step-7-confirm-claude-code-sees-the-bridge">Step 7: Confirm Claude Code sees the bridge</a> </li><li data-depth="2"> <a href="#step-8-make-an-end-to-end-tool-call">Step 8: Make an end-to-end tool call</a> </li><li data-depth="2"> <a href="#step-9-try-a-sandbox-management-tool">Step 9: Try a sandbox-management tool</a> </li><li data-depth="2"> <a href="#troubleshooting">Troubleshooting</a> </li><li data-depth="2"> <a href="#next-steps">Next steps</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>

package/dist/serve/docs-ui/docs/pyric-cli-tutorials-wire-claude-code.md ADDED Viewed

@@ -0,0 +1,217 @@
+# Wire Claude Code to your pyric sandbox (manual MCP wiring)
+> **Most users want the plugin instead.** `claude plugin install` +
+> `/pyric:pyric-start` does everything below automatically, see
+> [getting-started.md](../start-building/). This tutorial is the
+> manual path: wiring Claude Code to a bridge yourself, e.g. for a
+> sandbox embedded in your own dev server, a custom port layout, or an
+> MCP client other than Claude Code.
+By the end of this tutorial you will have:
+- A running pyric bridge on `127.0.0.1:5174`.
+- Your existing Firebase app's in-browser pyric sandbox connected to the bridge.
+- Claude Code configured to talk to the bridge via MCP-over-HTTP.
+- A successful end-to-end tool call from Claude Code into your browser-resident Firestore sandbox.
+Should take ~10 minutes.
+## Prerequisites
+- An existing Firebase app already retrofitted to use pyric, i.e. you've replaced the relevant `firebase/*` imports with `@pyric/*` adapter SDKs and your app boots against `initializeSandbox()` in dev. (If you haven't done the retrofit yet, do that first: see the per-package READMEs under `packages/*/README.md`.)
+- Claude Code installed and working. Verify with `claude --version`.
+- Node 22+ and `npm` / `bun`. This tutorial uses `npm` in commands; `bun` works equivalently.
+## Step 1: Install pyric
+In your app's repo:
+```bash
+npm install --save-dev pyric
+```
+This pulls in the bridge implementation (`@pyric/cli/bridge`) as part of `@pyric/cli`.
+Verify:
+```bash
+npx pyric --version
+```
+Expected output: a version string (e.g. `0.0.0`).
+## Step 2: Connect your app to the bridge
+The bridge waits for a browser tab to register a sandbox over WebSocket. Your app needs to call `connectBridge()` from `@pyric/cli/bridge` (browser entry) in dev mode.
+**Vite users**: the simplest path. Use the `pyricSandbox` plugin with `bridge: true`. One plugin does the `firebase/*` → sandbox swap **and** the bridge, so you don't even add the `connectBridge` snippet below:
+```ts
+import { defineConfig } from 'vite';
+import { pyricSandbox } from '@pyric/cli/vite';
+export default defineConfig({
+  plugins: [pyricSandbox({ bridge: true })],
+});
+```
+The plugin attaches the bridge to Vite's own dev server (so it shares Vite's port instead of running as a sidecar) AND wires the browser side automatically via the served init payload. You can skip Step 3 and 4: your app is already wired. `bridge: true` routes the agent's tool-calls through the **SharedWorker**, so the agent, your app, and Pyric Studio all share one sandbox (keep a tab open while the agent works); see [Use the Vite plugin](../pyric-cli-how-to-use-the-vite-plugin/#drive-the-sandbox-from-an-agent-bridge).
+**Non-Vite users**: add a small dev-mode snippet wherever your app initializes the sandbox:
+```ts
+// e.g. src/main.ts or wherever you call initializeSandbox()
+import { initializeSandbox } from 'pyric/sandbox';
+import { connectBridge } from '@pyric/cli/bridge';
+const sandbox = initializeSandbox();
+if (import.meta.env.DEV /* or NODE_ENV === 'development' */) {
+  connectBridge(sandbox);
+}
+```
+The conditional gate is important: `connectBridge` opens a WebSocket to `127.0.0.1:5174`, which doesn't exist in production. Without the gate, your production build would attempt a failed WebSocket handshake on page load.
+## Step 3: Start the bridge (non-Vite users only)
+Open a new terminal in your app's directory and run:
+```bash
+npx pyric bridge
+```
+Expected output:
+```
+pyric bridge 0.0.0 — mode: sandbox, project: sandbox
+  listening on http://127.0.0.1:5174
+  health:  http://127.0.0.1:5174/health
+  mcp:     http://127.0.0.1:5174/mcp
+  sandbox: ws://127.0.0.1:5174/sandbox
+  audit:   /Users/you/.pyric/projects/sandbox/events.ndjson
+Waiting for browser tab to connect. Ctrl-C to stop.
+```
+Leave this terminal running.
+> Vite users: skip this step, the bridge already runs as part of `npm run dev`.
+## Step 4: Verify the bridge is reachable
+In a third terminal:
+```bash
+curl http://127.0.0.1:5174/health
+```
+Expected:
+```json
+{
+  "status": "ok",
+  "mode": "sandbox",
+  "project": "sandbox",
+  "sandboxConnected": false,
+  "version": "0.0.0",
+  "startedAt": "2026-05-24T..."
+}
+```
+The `sandboxConnected: false` is correct: no browser tab has registered yet. Vite users with the plugin: the URL is your Vite dev server's, with `/__pyric/health` as the path (e.g. `http://localhost:5173/__pyric/health`).
+## Step 5: Open your app in a browser
+Run your usual dev command (`npm run dev`, `bun run dev`, …) and open the app in a browser. Your `connectBridge(sandbox)` call (Step 2) will run and open the WebSocket.
+Verify with another curl:
+```bash
+curl http://127.0.0.1:5174/health
+```
+Expected: `"sandboxConnected": true`.
+If it's still `false`, check the browser devtools console for WebSocket errors. The most common cause is the dev-mode gate (Step 2 conditional) being false. Add a `console.log('pyric: connecting')` line above `connectBridge(...)` to confirm it runs.
+## Step 6: Register the bridge with Claude Code
+```bash
+claude mcp add pyric --transport http \
+  --url http://127.0.0.1:5174/mcp \
+  --scope project
+```
+`--scope project` writes the MCP config to `.mcp.json` in the current directory (checked into git, shared with your team). Other scopes:
+- `--scope user`: `~/.claude.json`, personal only.
+- `--scope local`: this machine, this project, not checked in.
+Verify the registration:
+```bash
+claude mcp list
+```
+Expected: `pyric` shows in the list with `transport: http` and the URL.
+## Step 7: Confirm Claude Code sees the bridge
+Inside Claude Code (in your terminal or IDE), run:
+```
+/mcp
+```
+Expected: `pyric` appears as a configured MCP server, status `connected`. If status shows `disconnected`, check the bridge process is still running (Step 3 terminal) and the URL matches.
+If Claude Code was already running when you ran `claude mcp add`, you may need to restart it to pick up new project-scoped MCP config.
+## Step 8: Make an end-to-end tool call
+Ask Claude Code:
+> "Use the pyric MCP to seed my Firestore sandbox with a `users/u1` document containing `{ name: 'Alice' }`, then read it back."
+Expected behavior:
+1. Claude Code calls `pyric__firestore_simulator_create` and `pyric__firestore_simulator_execute` (the tools are namespaced by the MCP server name `pyric`).
+2. The bridge forwards both calls over WebSocket to your browser tab.
+3. Your browser's `connectBridge()` dispatches them into `LocalEnvironment`.
+4. Results flow back to Claude Code.
+5. Claude Code reports success with the seeded + read document.
+Open the browser devtools and check the sandbox's state: `users/u1` should be present.
+You can also verify via the audit log (sandbox events flow through the bridge's `onToolEvent` hook):
+```bash
+tail -n 5 ~/.pyric/projects/sandbox/events.ndjson
+```
+Each line is a JSON object with `tool`, `args`, `result`, `mode`, `timestamp`.
+## Step 9: Try a sandbox-management tool
+Ask Claude Code:
+> "Undo the last write, then redo it."
+Expected: two tool calls (`firestore_simulator_undo`, `firestore_simulator_redo`) round-trip through the bridge. The undo restores prior state; redo re-applies.
+## Troubleshooting
+**`sandboxConnected: false` even after opening the page.** Either `connectBridge()` isn't being called (dev-mode gate or path issue), or the WebSocket can't reach the bridge (firewall, browser security policy on a non-localhost domain, port mismatch). Browser devtools Network tab → WS filter shows the handshake attempt and failure mode.
+**Tool call returns `"sandbox not connected"`.** The browser tab disconnected (page closed, crashed, navigated away). Reopen the page; the bridge auto-accepts new connections (last-wins).
+**Multiple tabs open against the same app.** Last-wins. The most recently connected tab is the active sandbox; previous tabs are inactive (their `connectBridge` keeps reconnecting and replaces). For v1 this is acceptable; multi-tab is a v1.1 question.
+**Port 5174 already in use.** Another `pyric bridge` instance is running, OR another tool. Either kill the other process (`lsof -ti:5174 | xargs kill`) or run with `--port 5180` (and update your Claude Code MCP config to match).
+## Next steps
+- Read [the bridge README](../pyric-cli-bridge/) for the bridge architecture.
+- The bridge audit log at `~/.pyric/projects/<project>/events.ndjson` is the durable record of every tool call: review it after agent sessions.