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-rules-how-to-register-tools-with-an-agent/index.html ADDED Viewed

@@ -0,0 +1,61 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>How to register rules tools with an agent · 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/" aria-current="true"> 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/"> @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/" aria-current="true"> 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-rules/">pyric / rules</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>How-to</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Register rules tools</span> </li> </ol> </nav>  <article class="prose">  <h1 id="how-to-register-rules-tools-with-an-agent">How to register rules tools with an agent</h1>
+<p>Expose the rules surface as tool handlers for an <code>@inbrowser/agent</code> registry, so an LLM-driven agent can lint, simulate, and test rules through structured tool calls.</p>
+<p>The tool factories (<code>createFirestoreRulesTools</code>, <code>createFirestoreSimulatorTools</code>) are engine-internal, imported from <code>pyric/rules/internal/node</code>. They’re not part of the public <code>pyric/rules</code> contract and may change without notice, but they’re the supported way to wire rules tooling into an agent registry.</p>
+<h2 id="without-project-credentials-lint--resolve--simulate">Without project credentials: lint / resolve / simulate</h2>
+<p><code>createFirestoreRulesTools()</code> returns three handlers:</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">createFirestoreRulesTools</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal/node'</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">createToolRegistry</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@inbrowser/agent'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> registry</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> createToolRegistry</span><span style="color:#ABB2BF">();</span></span>
+<span class="line"><span style="color:#C678DD">for</span><span style="color:#ABB2BF"> (</span><span style="color:#C678DD">const</span><span style="color:#E5C07B"> handler</span><span style="color:#C678DD"> of</span><span style="color:#61AFEF"> createFirestoreRulesTools</span><span style="color:#ABB2BF">()) {</span></span>
+<span class="line"><span style="color:#E5C07B">  registry</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">register</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">handler</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:#E5C07B">registry</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">list</span><span style="color:#ABB2BF">().</span><span style="color:#61AFEF">map</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">h</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> h</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">name</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// → ['firestore_lint_rules', 'firestore_resolve_modules', 'firestore_simulate_rules']</span></span></code></pre>
+<p>These are pure-local: no network, no credentials, safe to expose anywhere.</p>
+<h2 id="with-a-projectscope-also-expose-live-testing">With a <code>ProjectScope</code>: also expose live testing</h2>
+<p>Pass a <code>ProjectScope</code> and a fourth handler appears: <code>firestore_test_rules</code>, which calls Google’s Rules Test API.</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">fromServiceAccount</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@pyric/cli/credentials/node'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> scope</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#61AFEF"> fromServiceAccount</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'./service-account.json'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">for</span><span style="color:#ABB2BF"> (</span><span style="color:#C678DD">const</span><span style="color:#E5C07B"> handler</span><span style="color:#C678DD"> of</span><span style="color:#61AFEF"> createFirestoreRulesTools</span><span style="color:#ABB2BF">({ </span><span style="color:#E06C75">scope</span><span style="color:#ABB2BF"> })) {</span></span>
+<span class="line"><span style="color:#E5C07B">  registry</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">register</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">handler</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:#E5C07B">registry</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">list</span><span style="color:#ABB2BF">().</span><span style="color:#61AFEF">map</span><span style="color:#ABB2BF">((</span><span style="color:#E06C75;font-style:italic">h</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> h</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">name</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// → ['firestore_lint_rules', 'firestore_resolve_modules',</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">//    'firestore_simulate_rules', 'firestore_test_rules']</span></span></code></pre>
+<p>Only attach <code>scope</code> when the host actually has credentials. The factory drops <code>firestore_test_rules</code> cleanly when <code>scope</code> is omitted, so an unsuspecting agent can’t try to call it.</p>
+<h2 id="dispatch-a-tool-call">Dispatch a tool call</h2>
+<p><code>@inbrowser/agent</code> does the dispatch:</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">createDispatch</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@inbrowser/agent'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> dispatch</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> createDispatch</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">registry</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> result</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#E5C07B"> dispatch</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">execute</span><span style="color:#ABB2BF">(</span></span>
+<span class="line"><span style="color:#ABB2BF">  {</span></span>
+<span class="line"><span style="color:#E06C75">    id</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'1'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    name</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'firestore_lint_rules'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    args</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">source</span><span style="color:#ABB2BF">: </span><span style="color:#E06C75">yourRulesSource</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:#E06C75">signal</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">new</span><span style="color:#61AFEF"> AbortController</span><span style="color:#ABB2BF">().</span><span style="color:#E06C75">signal</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:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">result</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">summary</span><span style="color:#ABB2BF">); </span><span style="color:#7F848E;font-style:italic">// 'Linted rules source'</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:#E5C07B">result</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">data</span><span style="color:#ABB2BF">);    </span><span style="color:#7F848E;font-style:italic">// the full internal LintResult</span></span></code></pre>
+<p>The <code>ToolResult</code> shape is uniform across handlers: <code>{ ok, summary, data }</code>. Look at <code>summary</code> for a one-line agent-facing message; <code>data</code> is the structured payload.</p>
+<h2 id="stateful-simulator-tools-slice-8-scaffold">Stateful simulator tools (Slice 8 scaffold)</h2>
+<p><code>createFirestoreSimulatorTools({ resolveSandbox })</code> is the entry point for the seven-tool simulator family that operates against a session-scoped <code>LocalEnvironment</code> from <code>pyric/sandbox</code>. It currently returns an empty array. The full implementation lands as consumers ask for it. The factory shape and dependency contract are stable; only the handlers are pending.</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">createFirestoreSimulatorTools</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal/node'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// Today: returns [] — placeholder</span></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> tools</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> createFirestoreSimulatorTools</span><span style="color:#ABB2BF">({</span></span>
+<span class="line"><span style="color:#61AFEF">  resolveSandbox</span><span style="color:#ABB2BF">: () </span><span style="color:#C678DD">=></span><span style="color:#E5C07B"> sessionContext</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">localEnv</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span></code></pre>
+<p>The <code>resolveSandbox</code> resolver fires per dispatch, so hosts that reset or swap the sandbox transparently get a fresh environment without re-registering tools.</p>
+<h2 id="where-to-look-next">Where to look next</h2>
+<ul>
+<li>For <code>ToolHandler</code>, <code>createToolRegistry</code>, and <code>createDispatch</code>, see the <code>@inbrowser/agent</code> package.</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="#without-project-credentials-lint--resolve--simulate">Without project credentials: lint / resolve / simulate</a> </li><li data-depth="2"> <a href="#with-a-projectscope-also-expose-live-testing">With a ProjectScope: also expose live testing</a> </li><li data-depth="2"> <a href="#dispatch-a-tool-call">Dispatch a tool call</a> </li><li data-depth="2"> <a href="#stateful-simulator-tools-slice-8-scaffold">Stateful simulator tools (Slice 8 scaffold)</a> </li><li data-depth="2"> <a href="#where-to-look-next">Where to look 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-rules-how-to-register-tools-with-an-agent.md ADDED Viewed

@@ -0,0 +1,87 @@
+# How to register rules tools with an agent
+Expose the rules surface as tool handlers for an `@inbrowser/agent` registry, so an LLM-driven agent can lint, simulate, and test rules through structured tool calls.
+The tool factories (`createFirestoreRulesTools`, `createFirestoreSimulatorTools`) are engine-internal, imported from `pyric/rules/internal/node`. They're not part of the public `pyric/rules` contract and may change without notice, but they're the supported way to wire rules tooling into an agent registry.
+## Without project credentials: lint / resolve / simulate
+`createFirestoreRulesTools()` returns three handlers:
+```ts
+import { createFirestoreRulesTools } from 'pyric/rules/internal/node';
+import { createToolRegistry } from '@inbrowser/agent';
+const registry = createToolRegistry();
+for (const handler of createFirestoreRulesTools()) {
+  registry.register(handler);
+}
+registry.list().map((h) => h.name);
+// → ['firestore_lint_rules', 'firestore_resolve_modules', 'firestore_simulate_rules']
+```
+These are pure-local: no network, no credentials, safe to expose anywhere.
+## With a `ProjectScope`: also expose live testing
+Pass a `ProjectScope` and a fourth handler appears: `firestore_test_rules`, which calls Google's Rules Test API.
+```ts
+import { fromServiceAccount } from '@pyric/cli/credentials/node';
+const scope = await fromServiceAccount('./service-account.json');
+for (const handler of createFirestoreRulesTools({ scope })) {
+  registry.register(handler);
+}
+registry.list().map((h) => h.name);
+// → ['firestore_lint_rules', 'firestore_resolve_modules',
+//    'firestore_simulate_rules', 'firestore_test_rules']
+```
+Only attach `scope` when the host actually has credentials. The factory drops `firestore_test_rules` cleanly when `scope` is omitted, so an unsuspecting agent can't try to call it.
+## Dispatch a tool call
+`@inbrowser/agent` does the dispatch:
+```ts
+import { createDispatch } from '@inbrowser/agent';
+const dispatch = createDispatch(registry);
+const result = await dispatch.execute(
+  {
+    id: '1',
+    name: 'firestore_lint_rules',
+    args: { source: yourRulesSource },
+  },
+  { signal: new AbortController().signal },
+);
+console.log(result.summary); // 'Linted rules source'
+console.log(result.data);    // the full internal LintResult
+```
+The `ToolResult` shape is uniform across handlers: `{ ok, summary, data }`. Look at `summary` for a one-line agent-facing message; `data` is the structured payload.
+## Stateful simulator tools (Slice 8 scaffold)
+`createFirestoreSimulatorTools({ resolveSandbox })` is the entry point for the seven-tool simulator family that operates against a session-scoped `LocalEnvironment` from `pyric/sandbox`. It currently returns an empty array. The full implementation lands as consumers ask for it. The factory shape and dependency contract are stable; only the handlers are pending.
+```ts
+import { createFirestoreSimulatorTools } from 'pyric/rules/internal/node';
+// Today: returns [] — placeholder
+const tools = createFirestoreSimulatorTools({
+  resolveSandbox: () => sessionContext.localEnv,
+});
+```
+The `resolveSandbox` resolver fires per dispatch, so hosts that reset or swap the sandbox transparently get a fresh environment without re-registering tools.
+## Where to look next
+- For `ToolHandler`, `createToolRegistry`, and `createDispatch`, see the `@inbrowser/agent` package.

package/dist/serve/docs-ui/docs/pyric-rules-how-to-resolve-module-imports/index.html ADDED Viewed

@@ -0,0 +1,93 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>How to resolve 2+modules imports · 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/" aria-current="true"> 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/"> @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/" aria-current="true"> 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-rules/">pyric / rules</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>How-to</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Resolve 2+modules imports</span> </li> </ol> </nav>  <article class="prose">  <h1 id="how-to-resolve-2modules-imports">How to resolve <code>2+modules</code> imports</h1>
+<p>Write rules that import reusable helper functions, then resolve them into a standard Firestore rules source.</p>
+<p><code>2+modules</code> is a Pyric extension. The Firestore rules engine itself only understands <code>rules_version = '2'</code>. The resolver inlines all imported functions and rewrites the version, so the output is something Firebase will accept.</p>
+<p><code>resolveModules</code> is an engine-internal, Node-only seam, imported from <code>pyric/rules/internal/node</code>. It’s not part of the public <code>pyric/rules</code> contract and may change without notice, but it’s the supported way to resolve <code>2+modules</code> imports today.</p>
+<h2 id="author-rules-with-imports">Author rules with imports</h2>
+<p>Set the version to <code>'2+modules'</code> and add <code>import</code> statements at the top of the file:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="rules"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { isAuthenticated, isOwner } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'auth'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { hasRequired, hasOnly } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'validation'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">rules_version</span><span style="color:#ABB2BF"> = </span><span style="color:#98C379">'2+modules'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">service</span><span style="color:#ABB2BF"> cloud.firestore {</span></span>
+<span class="line"><span style="color:#C678DD">  match</span><span style="color:#ABB2BF"> /databases/</span><span style="color:#E06C75;font-style:italic">{db}</span><span style="color:#ABB2BF">/documents {</span></span>
+<span class="line"><span style="color:#C678DD">    match</span><span style="color:#ABB2BF"> /notes/</span><span style="color:#E06C75;font-style:italic">{id}</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">      allow</span><span style="color:#61AFEF"> read</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">if</span><span style="color:#ABB2BF"> isAuthenticated();</span></span>
+<span class="line"><span style="color:#C678DD">      allow</span><span style="color:#61AFEF"> create</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">if</span><span style="color:#ABB2BF"> isOwner(</span><span style="color:#E5C07B">request</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">resource</span><span style="color:#ABB2BF">.data.ownerId)</span></span>
+<span class="line"><span style="color:#ABB2BF">                    &#x26;&#x26; hasOnly([</span><span style="color:#98C379">'ownerId'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'title'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'body'</span><span style="color:#ABB2BF">]);</span></span>
+<span class="line"><span style="color:#C678DD">      allow</span><span style="color:#61AFEF"> update</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">if</span><span style="color:#ABB2BF"> isOwner(</span><span style="color:#E5C07B">resource</span><span style="color:#ABB2BF">.data.ownerId)</span></span>
+<span class="line"><span style="color:#ABB2BF">                    &#x26;&#x26; hasRequired([</span><span style="color:#98C379">'ownerId'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'title'</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>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<h2 id="resolve-to-standard-rules">Resolve to standard rules</h2>
+<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">resolveModules</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal/node'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> result</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> resolveModules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">source</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#C678DD">if</span><span style="color:#ABB2BF"> (</span><span style="color:#56B6C2">!</span><span style="color:#E5C07B">result</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">success</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">error</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">`[</span><span style="color:#C678DD">${</span><span style="color:#E5C07B">result</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">error</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">code</span><span style="color:#C678DD">}</span><span style="color:#98C379">] </span><span style="color:#C678DD">${</span><span style="color:#E5C07B">result</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">error</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">message</span><span style="color:#C678DD">}</span><span style="color:#98C379">`</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#E5C07B">  process</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">exit</span><span style="color:#ABB2BF">(</span><span style="color:#D19A66">1</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:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">result</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">data</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">resolved</span><span style="color:#ABB2BF">);   </span><span style="color:#7F848E;font-style:italic">// standard '2' rules, ready to deploy</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:#E5C07B">result</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">data</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">modules</span><span style="color:#ABB2BF">);    </span><span style="color:#7F848E;font-style:italic">// ['auth', 'validation']</span></span></code></pre>
+<p>The output uses <code>rules_version = '2'</code> and has the imported functions inlined at the root scope of the match block.</p>
+<h2 id="use-the-stdlib">Use the stdlib</h2>
+<p>Fifteen modules ship with the package: <code>auth</code>, <code>validation</code>, <code>lobby</code>, <code>turns</code>, <code>state</code>, <code>membership</code>, <code>lifecycle</code>, <code>transitions</code>, <code>geometry</code>, <code>counters</code>, <code>timing</code>, <code>content</code>, <code>spaces</code>, <code>joining</code>, <code>atomic</code>. They resolve automatically; you don’t need to configure anything.</p>
+<p>For the full list of exports, see <a href="../pyric-rules-reference-stdlib-modules/">Standard library modules</a>.</p>
+<h2 id="use-your-own-rules-files">Use your own <code>.rules</code> files</h2>
+<p>For project-specific helpers, write a <code>.rules</code> file and use a relative import:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="rules"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { hasModeratorClaim } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> './lib/moderation'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>Then point the resolver at the base directory:</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"> result</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> resolveModules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">source</span><span style="color:#ABB2BF">, { </span><span style="color:#E06C75">basePath</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'./src'</span><span style="color:#ABB2BF"> });</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// Loads './src/lib/moderation.rules'</span></span></code></pre>
+<p>The resolved path is <code>${basePath}/${importPath}.rules</code>. Functions in your module file can be marked <code>export</code> (visible to importers) or left bare (private, renamed with a module prefix so they don’t collide).</p>
+<h2 id="inject-modules-from-memory">Inject modules from memory</h2>
+<p>For tests, ephemeral environments, or any case where the source isn’t on disk, pass <code>modules</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"> result</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> resolveModules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">source</span><span style="color:#ABB2BF">, {</span></span>
+<span class="line"><span style="color:#E06C75">  modules</span><span style="color:#ABB2BF">: {</span></span>
+<span class="line"><span style="color:#98C379">    './moderation'</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">`</span></span>
+<span class="line"><span style="color:#98C379">      export function hasModeratorClaim() {</span></span>
+<span class="line"><span style="color:#98C379">        return request.auth.token.role == 'moderator';</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 style="color:#ABB2BF">  },</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span></code></pre>
+<p>The <code>modules</code> map takes priority over both <code>basePath</code> lookups and the stdlib, so you can override a stdlib module by name if you need to.</p>
+<h2 id="handle-resolve-failures">Handle resolve failures</h2>
+<p><code>result.error.code</code> discriminates the failure mode:</p>
+<div class="table-scroll">
+<table><thead><tr><th>Code</th><th>Meaning</th></tr></thead><tbody><tr><td><code>PARSE_FAILED</code></td><td>The input source did not parse. Fix syntax first.</td></tr><tr><td><code>NOT_MODULE_SOURCE</code></td><td>The source has <code>rules_version = '2'</code>, not <code>'2+modules'</code>. No resolution needed; deploy as-is.</td></tr><tr><td><code>UNKNOWN_MODULE</code></td><td>An imported module name isn’t in stdlib, the <code>modules</code> map, or <code>basePath</code>.</td></tr><tr><td><code>UNKNOWN_FUNCTION</code></td><td>The module exists but doesn’t export the named function. The error message tells you if it exists but is private.</td></tr><tr><td><code>DUPLICATE_FUNCTION</code></td><td>Two modules export the same function name, or an imported function collides with one defined in the source.</td></tr></tbody></table></div>
+<h2 id="where-to-look-next">Where to look next</h2>
+<ul>
+<li>For all stdlib modules and their exports, see <a href="../pyric-rules-reference-stdlib-modules/">Standard library modules</a>.</li>
+<li>For the design rationale, see <a href="../pyric-rules-explanation-the-2-plus-modules-extension/">The <code>2+modules</code> extension</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="#author-rules-with-imports">Author rules with imports</a> </li><li data-depth="2"> <a href="#resolve-to-standard-rules">Resolve to standard rules</a> </li><li data-depth="2"> <a href="#use-the-stdlib">Use the stdlib</a> </li><li data-depth="2"> <a href="#use-your-own-rules-files">Use your own .rules files</a> </li><li data-depth="2"> <a href="#inject-modules-from-memory">Inject modules from memory</a> </li><li data-depth="2"> <a href="#handle-resolve-failures">Handle resolve failures</a> </li><li data-depth="2"> <a href="#where-to-look-next">Where to look 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-rules-how-to-resolve-module-imports.md ADDED Viewed

@@ -0,0 +1,105 @@
+# How to resolve `2+modules` imports
+Write rules that import reusable helper functions, then resolve them into a standard Firestore rules source.
+`2+modules` is a Pyric extension. The Firestore rules engine itself only understands `rules_version = '2'`. The resolver inlines all imported functions and rewrites the version, so the output is something Firebase will accept.
+`resolveModules` is an engine-internal, Node-only seam, imported from `pyric/rules/internal/node`. It's not part of the public `pyric/rules` contract and may change without notice, but it's the supported way to resolve `2+modules` imports today.
+## Author rules with imports
+Set the version to `'2+modules'` and add `import` statements at the top of the file:
+```rules
+import { isAuthenticated, isOwner } from 'auth';
+import { hasRequired, hasOnly } from 'validation';
+rules_version = '2+modules';
+service cloud.firestore {
+  match /databases/{db}/documents {
+    match /notes/{id} {
+      allow read: if isAuthenticated();
+      allow create: if isOwner(request.resource.data.ownerId)
+                    && hasOnly(['ownerId', 'title', 'body']);
+      allow update: if isOwner(resource.data.ownerId)
+                    && hasRequired(['ownerId', 'title']);
+    }
+  }
+}
+```
+## Resolve to standard rules
+```ts
+import { resolveModules } from 'pyric/rules/internal/node';
+const result = resolveModules(source);
+if (!result.success) {
+  console.error(`[${result.error.code}] ${result.error.message}`);
+  process.exit(1);
+}
+console.log(result.data.resolved);   // standard '2' rules, ready to deploy
+console.log(result.data.modules);    // ['auth', 'validation']
+```
+The output uses `rules_version = '2'` and has the imported functions inlined at the root scope of the match block.
+## Use the stdlib
+Fifteen modules ship with the package: `auth`, `validation`, `lobby`, `turns`, `state`, `membership`, `lifecycle`, `transitions`, `geometry`, `counters`, `timing`, `content`, `spaces`, `joining`, `atomic`. They resolve automatically; you don't need to configure anything.
+For the full list of exports, see [Standard library modules](../pyric-rules-reference-stdlib-modules/).
+## Use your own `.rules` files
+For project-specific helpers, write a `.rules` file and use a relative import:
+```rules
+import { hasModeratorClaim } from './lib/moderation';
+```
+Then point the resolver at the base directory:
+```ts
+const result = resolveModules(source, { basePath: './src' });
+// Loads './src/lib/moderation.rules'
+```
+The resolved path is `${basePath}/${importPath}.rules`. Functions in your module file can be marked `export` (visible to importers) or left bare (private, renamed with a module prefix so they don't collide).
+## Inject modules from memory
+For tests, ephemeral environments, or any case where the source isn't on disk, pass `modules`:
+```ts
+const result = resolveModules(source, {
+  modules: {
+    './moderation': `
+      export function hasModeratorClaim() {
+        return request.auth.token.role == 'moderator';
+      }
+    `,
+  },
+});
+```
+The `modules` map takes priority over both `basePath` lookups and the stdlib, so you can override a stdlib module by name if you need to.
+## Handle resolve failures
+`result.error.code` discriminates the failure mode:
+| Code | Meaning |
+|---|---|
+| `PARSE_FAILED` | The input source did not parse. Fix syntax first. |
+| `NOT_MODULE_SOURCE` | The source has `rules_version = '2'`, not `'2+modules'`. No resolution needed; deploy as-is. |
+| `UNKNOWN_MODULE` | An imported module name isn't in stdlib, the `modules` map, or `basePath`. |
+| `UNKNOWN_FUNCTION` | The module exists but doesn't export the named function. The error message tells you if it exists but is private. |
+| `DUPLICATE_FUNCTION` | Two modules export the same function name, or an imported function collides with one defined in the source. |
+## Where to look next
+- For all stdlib modules and their exports, see [Standard library modules](../pyric-rules-reference-stdlib-modules/).
+- For the design rationale, see [The `2+modules` extension](../pyric-rules-explanation-the-2-plus-modules-extension/).