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-sandbox-tutorials-01-your-first-sandbox-session/index.html ADDED Viewed

@@ -0,0 +1,115 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Your first sandbox session · 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/"> @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/" aria-current="true"> 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/"> @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/" aria-current="true"> 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-sandbox/">pyric / sandbox</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">Your first sandbox session</span> </li> </ol> </nav>  <article class="prose">  <h1 id="your-first-sandbox-session">Your first sandbox session</h1>
+<p>Create a sandbox, deploy a tiny set of rules, write a document as one user, deny a read as another, and inspect the result. By the end you’ll have seen the three core ideas (<code>Sandbox</code>, <code>SandboxContext</code>, <code>SandboxError</code>) work together in one short script.</p>
+<p>No Firebase project, no network, no setup beyond an <code>npm install</code>.</p>
+<h2 id="what-you-will-build">What you will build</h2>
+<p>A standalone script that creates a sandbox, runs three operations against it, and prints what happened.</p>
+<h2 id="step-1-set-up">Step 1: Set up</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">mkdir</span><span style="color:#98C379"> sandbox-tutorial</span><span style="color:#ABB2BF"> &#x26;&#x26; </span><span style="color:#56B6C2">cd</span><span style="color:#98C379"> sandbox-tutorial</span></span>
+<span class="line"><span style="color:#61AFEF">bun</span><span style="color:#98C379"> init</span><span style="color:#D19A66"> -y</span></span>
+<span class="line"><span style="color:#61AFEF">bun</span><span style="color:#98C379"> add</span><span style="color:#98C379"> pyric/sandbox</span><span style="color:#98C379"> pyric-admin</span></span></code></pre>
+<p><code>pyric-admin</code> gives us the Admin-SDK-shaped data plane that sits on top of the sandbox. (You could use <code>pyric/firestore</code> for the modular Web shape instead; the choice doesn’t matter for this tutorial.)</p>
+<h2 id="step-2-create-the-sandbox-and-deploy-rules">Step 2: Create the sandbox and deploy rules</h2>
+<p>Create <code>session.ts</code>:</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">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">getFirestore</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric-admin'</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">const</span><span style="color:#E5C07B"> adminCtx</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">withAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'admin'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">token</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">admin</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF"> } });</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> adminDb</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getFirestore</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">adminCtx</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#E5C07B">adminDb</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">setRules</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`rules_version = '2';</span></span>
+<span class="line"><span style="color:#98C379">service cloud.firestore {</span></span>
+<span class="line"><span style="color:#98C379">  match /databases/{db}/documents {</span></span>
+<span class="line"><span style="color:#98C379">    match /notes/{noteId} {</span></span>
+<span class="line"><span style="color:#98C379">      allow read: if request.auth != null;</span></span>
+<span class="line"><span style="color:#98C379">      allow write: if request.auth.uid == request.resource.data.ownerId;</span></span>
+<span class="line"><span style="color:#98C379">    }</span></span>
+<span class="line"><span style="color:#98C379">  }</span></span>
+<span class="line"><span style="color:#98C379">}`</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'Sandbox ready, rules deployed.'</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<p>Notice three things:</p>
+<ul>
+<li><code>initializeSandbox()</code> takes no arguments. Identity comes later, via <code>withAuth</code>.</li>
+<li>The admin context uses a custom <code>token.admin</code> claim. The rule doesn’t check for it here; we’ll use it shortly when we want to bypass user-shape rules.</li>
+<li><code>setRules</code> is part of <code>pyric-admin</code>’s handle, not the sandbox itself. The sandbox is identity-agnostic; deploying rules is conceptually identity-agnostic too, but the surface lives on the data-plane adapter for ergonomics.</li>
+</ul>
+<p>Run it:</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">bun</span><span style="color:#98C379"> run</span><span style="color:#98C379"> session.ts</span></span></code></pre>
+<p>You should see <code>Sandbox ready, rules deployed.</code> and nothing else.</p>
+<h2 id="step-3-write-as-one-user-read-as-another">Step 3: Write as one user, read as another</h2>
+<p>Add to <code>session.ts</code>:</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">const</span><span style="color:#E5C07B"> alice</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getFirestore</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">withAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> }));</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> bob</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> getFirestore</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">withAuth</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'bob'</span><span style="color:#ABB2BF"> }));</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#E5C07B"> alice</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'n1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">({</span></span>
+<span class="line"><span style="color:#E06C75">  ownerId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  title</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'My first note'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> aliceRead</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#E5C07B"> alice</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'n1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">get</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'Alice sees:'</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">aliceRead</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">data</span><span style="color:#ABB2BF">());</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> bobRead</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#E5C07B"> bob</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'n1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">get</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'Bob sees:'</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">bobRead</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">data</span><span style="color:#ABB2BF">());</span></span></code></pre>
+<p>Run it again. You will see:</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>Sandbox ready, rules deployed.</span></span>
+<span class="line"><span>Alice sees: { ownerId: "alice", title: "My first note" }</span></span>
+<span class="line"><span>Bob sees: { ownerId: "alice", title: "My first note" }</span></span></code></pre>
+<p>Both reads succeed because the rule says <code>allow read: if request.auth != null</code>. Any signed-in user can read any note. The two contexts share data; they differ only in the identity rules evaluate under.</p>
+<h2 id="step-4-watch-a-denial">Step 4: Watch a denial</h2>
+<p>Add:</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">SandboxError</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>
+<span class="line"><span style="color:#C678DD">try</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  await</span><span style="color:#E5C07B"> bob</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">collection</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">doc</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'n1'</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">set</span><span style="color:#ABB2BF">({</span></span>
+<span class="line"><span style="color:#E06C75">    ownerId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF">,  </span><span style="color:#7F848E;font-style:italic">// Bob lies about who owns it</span></span>
+<span class="line"><span style="color:#E06C75">    title</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'Bob tampers'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">  });</span></span>
+<span class="line"><span style="color:#ABB2BF">} </span><span style="color:#C678DD">catch</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75">e</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#C678DD">  if</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75">e</span><span style="color:#C678DD"> instanceof</span><span style="color:#E5C07B"> SandboxError</span><span style="color:#56B6C2"> &#x26;&#x26;</span><span style="color:#E5C07B"> e</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">code</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'permission-denied'</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#E5C07B">    console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'Bob was denied.'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#E5C07B">    console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'  Reasons:'</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">e</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">denialContext</span><span style="color:#ABB2BF">?.</span><span style="color:#E06C75">reasons</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#E5C07B">    console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'  Request method:'</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">e</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">denialContext</span><span style="color:#ABB2BF">?.</span><span style="color:#E5C07B">request</span><span style="color:#ABB2BF">?.</span><span style="color:#E06C75">method</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#ABB2BF">  } </span><span style="color:#C678DD">else</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">    throw</span><span style="color:#E06C75"> e</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">  }</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>Run. You will see:</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>Bob was denied.</span></span>
+<span class="line"><span>  Reasons: [ "Rule #1 (write) → deny", "Simulated: DENY" ]</span></span>
+<span class="line"><span>  Request method: update</span></span></code></pre>
+<p>The write rule is <code>request.auth.uid == request.resource.data.ownerId</code>. Bob’s <code>auth.uid</code> is <code>'bob'</code>; the proposed payload’s <code>ownerId</code> is <code>'alice'</code>. They don’t match, the rule denies, the SDK throws <code>SandboxError</code> with <code>code: 'permission-denied'</code>.</p>
+<p><code>denialContext</code> carries the full eval-time payload: what the rule saw, why it said no. Production Firebase strips this server-side for security; the sandbox can show it because it’s a development tool.</p>
+<h2 id="step-5-use-admin-reads-to-confirm-state">Step 5: Use admin reads to confirm state</h2>
+<p>Add:</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:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'Actual data:'</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">admin</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">getDocument</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes/n1'</span><span style="color:#ABB2BF">));</span></span></code></pre>
+<p>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>Actual data: { ownerId: "alice", title: "My first note" }</span></span></code></pre>
+<p><code>sandbox.admin.getDocument</code> bypasses rules entirely. It tells you what the data is, regardless of whether any specific user can read it. Bob’s attempted overwrite never happened (the rule denied it), so the document still has Alice’s original payload.</p>
+<p>This is how you assert state in tests without worrying about whether your test fixture’s identity can read what you want to verify.</p>
+<h2 id="step-6-watch-a-reset">Step 6: Watch a reset</h2>
+<p>Add at the end:</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:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">reset</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'After reset:'</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">sandbox</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">admin</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">getDocument</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'notes/n1'</span><span style="color:#ABB2BF">));</span></span>
+<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'Alice context still works:'</span><span style="color:#ABB2BF">, </span><span style="color:#56B6C2">!!</span><span style="color:#E06C75">alice</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<p>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>After reset: null</span></span>
+<span class="line"><span>Alice context still works: true</span></span></code></pre>
+<p><code>reset</code> wipes data, rules, and listeners, but the <code>alice</code> and <code>bob</code> contexts still work. Their sandbox reference is stable; the underlying environment was replaced. The next operation through <code>alice</code> would evaluate against the fresh environment (and would fail because rules are gone, so default-deny applies).</p>
+<h2 id="what-you-have-learned">What you have learned</h2>
+<ul>
+<li><code>initializeSandbox()</code> produces an identity-agnostic sandbox.</li>
+<li><code>sandbox.withAuth(...)</code> derives a <code>SandboxContext</code> for a specific identity.</li>
+<li>Data-plane adapters (<code>pyric-admin</code>) accept a context and provide the Firestore API.</li>
+<li>Denied operations throw <code>SandboxError('permission-denied')</code> carrying a structured <code>denialContext</code>.</li>
+<li><code>sandbox.admin</code> bypasses rules for state assertions.</li>
+<li><code>sandbox.reset()</code> swaps the underlying environment but keeps context references alive.</li>
+</ul>
+<h2 id="what-to-do-next">What to do next</h2>
+<ul>
+<li>Run the same pattern across a test suite: <a href="../test-in-node/">Use the sandbox in a test harness</a>.</li>
+<li>Render denials in a UI without try/catch: <a href="../pyric-sandbox-how-to-observe-events/">Observe sandbox events</a>.</li>
+<li>Pick between the two adapter shapes: <a href="../pyric-sandbox-how-to-pick-an-adapter/">Pick between <code>pyric-admin</code> and <code>pyric/firestore</code></a>.</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="#what-you-will-build">What you will build</a> </li><li data-depth="2"> <a href="#step-1-set-up">Step 1: Set up</a> </li><li data-depth="2"> <a href="#step-2-create-the-sandbox-and-deploy-rules">Step 2: Create the sandbox and deploy rules</a> </li><li data-depth="2"> <a href="#step-3-write-as-one-user-read-as-another">Step 3: Write as one user, read as another</a> </li><li data-depth="2"> <a href="#step-4-watch-a-denial">Step 4: Watch a denial</a> </li><li data-depth="2"> <a href="#step-5-use-admin-reads-to-confirm-state">Step 5: Use admin reads to confirm state</a> </li><li data-depth="2"> <a href="#step-6-watch-a-reset">Step 6: Watch a reset</a> </li><li data-depth="2"> <a href="#what-you-have-learned">What you have learned</a> </li><li data-depth="2"> <a href="#what-to-do-next">What to do next</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-sandbox-tutorials-01-your-first-sandbox-session.md ADDED Viewed

@@ -0,0 +1,176 @@
+# Your first sandbox session
+Create a sandbox, deploy a tiny set of rules, write a document as one user, deny a read as another, and inspect the result. By the end you'll have seen the three core ideas (`Sandbox`, `SandboxContext`, `SandboxError`) work together in one short script.
+No Firebase project, no network, no setup beyond an `npm install`.
+## What you will build
+A standalone script that creates a sandbox, runs three operations against it, and prints what happened.
+## Step 1: Set up
+```bash
+mkdir sandbox-tutorial && cd sandbox-tutorial
+bun init -y
+bun add pyric/sandbox pyric-admin
+```
+`pyric-admin` gives us the Admin-SDK-shaped data plane that sits on top of the sandbox. (You could use `pyric/firestore` for the modular Web shape instead; the choice doesn't matter for this tutorial.)
+## Step 2: Create the sandbox and deploy rules
+Create `session.ts`:
+```ts
+import { initializeSandbox } from 'pyric/sandbox';
+import { getFirestore } from 'pyric-admin';
+const sandbox = initializeSandbox();
+const adminCtx = sandbox.withAuth({ uid: 'admin', token: { admin: true } });
+const adminDb = getFirestore(adminCtx);
+adminDb.setRules(`rules_version = '2';
+service cloud.firestore {
+  match /databases/{db}/documents {
+    match /notes/{noteId} {
+      allow read: if request.auth != null;
+      allow write: if request.auth.uid == request.resource.data.ownerId;
+    }
+  }
+}`);
+console.log('Sandbox ready, rules deployed.');
+```
+Notice three things:
+- `initializeSandbox()` takes no arguments. Identity comes later, via `withAuth`.
+- The admin context uses a custom `token.admin` claim. The rule doesn't check for it here; we'll use it shortly when we want to bypass user-shape rules.
+- `setRules` is part of `pyric-admin`'s handle, not the sandbox itself. The sandbox is identity-agnostic; deploying rules is conceptually identity-agnostic too, but the surface lives on the data-plane adapter for ergonomics.
+Run it:
+```bash
+bun run session.ts
+```
+You should see `Sandbox ready, rules deployed.` and nothing else.
+## Step 3: Write as one user, read as another
+Add to `session.ts`:
+```ts
+const alice = getFirestore(sandbox.withAuth({ uid: 'alice' }));
+const bob = getFirestore(sandbox.withAuth({ uid: 'bob' }));
+await alice.collection('notes').doc('n1').set({
+  ownerId: 'alice',
+  title: 'My first note',
+});
+const aliceRead = await alice.collection('notes').doc('n1').get();
+console.log('Alice sees:', aliceRead.data());
+const bobRead = await bob.collection('notes').doc('n1').get();
+console.log('Bob sees:', bobRead.data());
+```
+Run it again. You will see:
+```
+Sandbox ready, rules deployed.
+Alice sees: { ownerId: "alice", title: "My first note" }
+Bob sees: { ownerId: "alice", title: "My first note" }
+```
+Both reads succeed because the rule says `allow read: if request.auth != null`. Any signed-in user can read any note. The two contexts share data; they differ only in the identity rules evaluate under.
+## Step 4: Watch a denial
+Add:
+```ts
+import { SandboxError } from 'pyric/sandbox';
+try {
+  await bob.collection('notes').doc('n1').set({
+    ownerId: 'alice',  // Bob lies about who owns it
+    title: 'Bob tampers',
+  });
+} catch (e) {
+  if (e instanceof SandboxError && e.code === 'permission-denied') {
+    console.log('Bob was denied.');
+    console.log('  Reasons:', e.denialContext?.reasons);
+    console.log('  Request method:', e.denialContext?.request?.method);
+  } else {
+    throw e;
+  }
+}
+```
+Run. You will see:
+```
+Bob was denied.
+  Reasons: [ "Rule #1 (write) → deny", "Simulated: DENY" ]
+  Request method: update
+```
+The write rule is `request.auth.uid == request.resource.data.ownerId`. Bob's `auth.uid` is `'bob'`; the proposed payload's `ownerId` is `'alice'`. They don't match, the rule denies, the SDK throws `SandboxError` with `code: 'permission-denied'`.
+`denialContext` carries the full eval-time payload: what the rule saw, why it said no. Production Firebase strips this server-side for security; the sandbox can show it because it's a development tool.
+## Step 5: Use admin reads to confirm state
+Add:
+```ts
+console.log('Actual data:', sandbox.admin.getDocument('notes/n1'));
+```
+Output:
+```
+Actual data: { ownerId: "alice", title: "My first note" }
+```
+`sandbox.admin.getDocument` bypasses rules entirely. It tells you what the data is, regardless of whether any specific user can read it. Bob's attempted overwrite never happened (the rule denied it), so the document still has Alice's original payload.
+This is how you assert state in tests without worrying about whether your test fixture's identity can read what you want to verify.
+## Step 6: Watch a reset
+Add at the end:
+```ts
+sandbox.reset();
+console.log('After reset:', sandbox.admin.getDocument('notes/n1'));
+console.log('Alice context still works:', !!alice);
+```
+Output:
+```
+After reset: null
+Alice context still works: true
+```
+`reset` wipes data, rules, and listeners, but the `alice` and `bob` contexts still work. Their sandbox reference is stable; the underlying environment was replaced. The next operation through `alice` would evaluate against the fresh environment (and would fail because rules are gone, so default-deny applies).
+## What you have learned
+- `initializeSandbox()` produces an identity-agnostic sandbox.
+- `sandbox.withAuth(...)` derives a `SandboxContext` for a specific identity.
+- Data-plane adapters (`pyric-admin`) accept a context and provide the Firestore API.
+- Denied operations throw `SandboxError('permission-denied')` carrying a structured `denialContext`.
+- `sandbox.admin` bypasses rules for state assertions.
+- `sandbox.reset()` swaps the underlying environment but keeps context references alive.
+## What to do next
+- Run the same pattern across a test suite: [Use the sandbox in a test harness](../test-in-node/).
+- Render denials in a UI without try/catch: [Observe sandbox events](../pyric-sandbox-how-to-observe-events/).
+- Pick between the two adapter shapes: [Pick between `pyric-admin` and `pyric/firestore`](../pyric-sandbox-how-to-pick-an-adapter/).

package/dist/serve/docs-ui/docs/pyric-sandbox.md ADDED Viewed

@@ -0,0 +1,69 @@
+# `pyric/sandbox`
+An in-process Firebase sandbox, the foundation every other `@pyric/*` data-plane package plugs into. It holds documents, rules, and listener state for a single isolated environment. It is identity-agnostic by design: every operation flows through a `SandboxContext` that names the auth identity it should evaluate under.
+Three concepts:
+- **`Sandbox`**: the data + rules + lifecycle handle. One per isolated environment. Also the observability surface: `onDenial`, `onSnapshotError`, and `onRequest` emit traffic events, while `reset`, `dispose`, and `snapshot` manage lifecycle.
+- **`SandboxContext`**: an immutable `(sandbox, auth)` pair. Service handles (`pyric-admin`, `pyric/firestore`) accept this.
+- **`SandboxError`**: a typed error family covering both Firebase-aligned codes (`permission-denied`, `not-found`) and sandbox-specific ones (`unimplemented`, `not-seeded`).
+The sandbox does *not* ship the data-plane API itself. The Admin-SDK-shaped surface lives in `pyric-admin`; the modular Web-SDK surface lives in `pyric/firestore`. This package is the substrate they share.
+## Install
+```bash
+bun add pyric/sandbox
+# or
+npm install pyric/sandbox
+```
+You will usually install one of the service-adapter packages alongside it:
+```bash
+bun add pyric/sandbox pyric-admin       # admin-SDK-shaped
+bun add pyric/sandbox pyric/firestore   # modular Web-SDK-shaped
+```
+## A 30-second example
+```ts
+import { initializeSandbox } from 'pyric/sandbox';
+import { getFirestore } from 'pyric-admin';
+const sandbox = initializeSandbox();
+const aliceDb = getFirestore(sandbox.withAuth({ uid: 'alice' }));
+await aliceDb.collection('notes').doc('n1').set({ title: 'hello' });
+const anonDb = getFirestore(sandbox.withAuth(null));
+const snap = await anonDb.collection('notes').doc('n1').get();
+console.log(snap.exists, snap.data());
+```
+Two contexts, one sandbox, shared data. The rules engine evaluates `aliceDb`'s write under `request.auth.uid == 'alice'`; the same writes are visible to `anonDb`'s read with `request.auth == null`.
+## Where to go next
+Documentation is organised under [`docs/`](../pyric-sandbox/) following the [Diataxis](https://diataxis.fr/) framework:
+| If you want to | Read |
+|---|---|
+| Follow a complete lesson | Tutorials |
+| Accomplish a specific task | How-to guides |
+| Look up a method signature or error code | Reference |
+| Understand the design | Explanation |
+### Starting points by role
+- **First time here?** Run [Your first sandbox session](../pyric-sandbox-tutorials-01-your-first-sandbox-session/).
+- **Writing tests?** Read [Use the sandbox in a test harness](../test-in-node/).
+- **Building an adapter?** See [The `/internal` adapter protocol](../pyric-sandbox-explanation-internal-adapter-protocol/).
+## Position in the Pyric stack
+`pyric/sandbox` is the **runtime substrate**. It does not depend on `pyric-admin`, `pyric/firestore`, or any other adapter. They depend on it. Rules tooling lives in `pyric/rules` (imported by the sandbox for the engine-internal `SimulateFirestoreRulesHandler`, on `pyric/rules/internal`). Production shipping stays with `firebase-tools` / Console. See [Why this package exists](../pyric-sandbox-explanation-why-this-package-exists/).
+## Licence
+Same as the parent workspace.