@pyric/cli 0.1.0-alpha.9

package/LICENSE

@@ -0,0 +1,216 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   Copyright 2026 David East
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,156 @@
+<p align="center">
+  <img src="https://pyric.dev/pyric-logo.svg" alt="Pyric" width="180" />
+</p>
+
+<h1 align="center">Build with Firebase without touching production</h1>
+
+<p align="center">Keep the same <code>firebase/*</code> code. Pyric runs it against a local backend during development, then gets out of the way when the app ships to Firebase.</p>
+
+<p align="center"><a href="https://pyric.dev">pyric.dev</a></p>
+
+<br />
+
+Pyric adds a development-only resolution layer to a Firebase application. Run the Vite development server and supported Firebase imports resolve to a browser-local backend. Run a normal production build and those imports resolve to Firebase again. The application source does not branch between the two.
+
+The mirrored data services do not connect to a production Firebase project. Local writes cannot delete production data or create Firebase usage charges, and local rules changes do not deploy. Pyric owns the development sandbox and verification workflow. Firebase owns production, with `firebase-tools` or the Firebase Console handling deployment.
+
+## Start a new Firebase application locally
+
+Create a Vite application with canonical Firebase imports, Firestore rules, and the Pyric development plugin already configured:
+
+```bash
+npx create-pyric my-app
+cd my-app
+npm install
+npm run dev
+```
+
+`npm create pyric my-app` runs the same scaffold.
+
+## Run an existing Firebase application locally
+
+Install the development plugin:
+
+```bash
+npm install --save-dev @pyric/cli
+```
+
+Add it to the existing Vite configuration:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { pyricSandbox } from '@pyric/cli/vite';
+
+export default defineConfig({
+  plugins: [pyricSandbox()],
+});
+```
+
+Start the normal development server:
+
+```bash
+npm run dev
+```
+
+During `vite dev`, the plugin swaps supported `firebase/*` modules at resolution time. The backend runs in a SharedWorker, so tabs on the same development origin use one local backend. Browser-local persistence uses IndexedDB.
+
+Pyric Studio is available on the Vite origin at `/__pyric/ui/`. It opens the same backend used by the application.
+
+For a static application or a Node process, `pyric dev` provides the same development-only package swap without the Vite plugin. The [CLI reference](packages/cli/docs/reference/cli.md) documents those paths and every command.
+
+## Keep writing Firebase code
+
+Application code continues to import Firebase:
+
+```ts
+// src/firebase.ts
+import { initializeApp } from 'firebase/app';
+import { getAuth } from 'firebase/auth';
+import { getFirestore } from 'firebase/firestore';
+
+const app = initializeApp({
+  apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
+  authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
+  projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
+});
+
+export const auth = getAuth(app);
+export const db = getFirestore(app);
+```
+
+The Firebase configuration is accepted by the local mirror during development. The production build passes that same configuration to Firebase. Normal Auth, Firestore, Realtime Database, Storage, Messaging, and Firebase AI Logic usage still belongs in the [Firebase documentation](https://firebase.google.com/docs).
+
+Pyric documents the parts that differ locally, including supported behavior, Security Rules, persistence, inspection, verification, and known gaps. See [use the Vite plugin](packages/cli/docs/how-to/use-the-vite-plugin.md) for the complete plugin contract.
+
+## Inspect and correct a failed operation
+
+Pyric Studio shows local data, requests, authentication state, Security Rules verdicts, and denied operations. Open `/__pyric/ui/` on the development server and reproduce the failure. A denied request includes the path and verdict needed to correct the rule or the application code.
+
+The Vite plugin discovers the Firestore rules path from `firebase.json`, or falls back to `firestore.rules`. Saving that file replaces the active local ruleset without a production deploy. A parse failure leaves the last valid ruleset active and reports the error in the development server.
+
+State and test identities stay browser-local by default. Add `persist: true` to write a committable `.pyric/state/state.json`, or use `seed` to start from a known scenario:
+
+```ts
+pyricSandbox({
+  persist: true,
+  seed: 'seed.json',
+});
+```
+
+See [persistence and multi-tab behavior](packages/cli/docs/how-to/serve-persistence-and-multi-tab.md) for reset and seed precedence.
+
+## Give coding agents the same local Firebase target
+
+An agent can keep writing the same Firebase code while inspecting and changing the backend that the application is already using. Agent access is opt-in. Enable the MCP bridge in the Vite plugin:
+
+```ts
+pyricSandbox({ bridge: true });
+```
+
+The bridge mounts on the Vite development origin and routes agent operations to the same SharedWorker backend used by the application and Studio. The included [Claude Code plugin](pyric-plugin/README.md) discovers that bridge, while other MCP clients can connect to its HTTP endpoint.
+
+This protects the local workflow, not an independently credentialed process. A coding agent with production Firebase credentials or deployment access can still affect production outside Pyric.
+
+## Verify the rules boundary
+
+Development sessions capture Firestore and Realtime Database operations in `.pyric/last-session.json` by default. Replay those requests against candidate rules before deployment:
+
+```bash
+npx pyric verify
+```
+
+The default engine runs locally. The optional Firestore Rules Test API engine sends derived rule cases to Google's hosted evaluator when production-authority verification is needed. It verifies rules and does not deploy them. See [verify against a captured session](packages/cli/docs/how-to/verify-against-a-captured-session.md).
+
+## Ship the same application code
+
+A standard Vite production build leaves the development swap inactive:
+
+```bash
+npm run build
+```
+
+The built application contains the real Firebase SDK and uses the Firebase configuration already present in the source. Deploy the build, rules, and indexes with `firebase-tools` or the Firebase Console. Pyric has no production deployment path.
+
+## Check what Pyric mirrors
+
+Pyric is an independent implementation of observable Firebase behavior. Conformance evidence records what has been compared with Firebase and keeps five outcomes distinct: conforms, documented divergence, bug, unsupported, and unverified. The evidence is a floor, not a claim that every Firebase behavior has been measured.
+
+Read the generated matrices for [App](packages/pyric/docs/app/COMPAT.md), [Auth](packages/pyric/docs/auth/COMPAT.md), [Firestore](packages/pyric/docs/firestore/COMPAT.md), [Realtime Database](packages/pyric/docs/database/COMPAT.md), [Storage](packages/pyric/docs/storage/COMPAT.md), [Messaging](packages/pyric/docs/messaging/COMPAT.md), [AI Logic](packages/pyric/docs/ai/COMPAT.md), [Security Rules](packages/pyric/docs/rules/COMPAT.md), and [Functions with Realtime Database](packages/cli/docs/functions-rtdb/COMPAT.md). The [versioning and compatibility policy](packages/pyric/docs/explanation/versioning-and-compatibility.md) explains the release boundary.
+
+## Stability
+
+Pyric is alpha software, currently `0.1.0-alpha.8`. Firebase-shaped surfaces are tracked through the compatibility matrices. Pyric-specific development APIs may change between alpha releases. All packages are ESM-only and require Node 22.15 or later.
+
+## Develop Pyric
+
+The repository is a Bun workspace:
+
+```bash
+bun install
+bun run build
+bun run test
+bun run compat:check
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [CONTEXT.md](CONTEXT.md), and [AGENTS.md](AGENTS.md) before changing the codebase.

package/README.md.orig

@@ -0,0 +1,138 @@
+# `@pyric/cli`
+
+The Pyric CLI and programmatic helpers for local sandbox development,
+verification, artifact generation, and agent bridges.
+
+> **Alpha.** This package is an early alpha. Non-mirrored exports (e.g.
+> `@pyric/cli/serve/worker`, `@pyric/cli/verify`, `@pyric/cli/credentials/node`)
+> are experimental public-alpha surfaces that may change without notice. The
+> MCP tool surface (tool names and shapes) will consolidate during early
+> alpha — do not treat tool names as stable.
+
+Production project administration (deploy, Identity Toolkit configuration,
+hosted discovery) is **not** part of this package. Use
+[`firebase-tools`](https://firebase.google.com/docs/cli) or the Firebase
+Console to ship rules, indexes, hosting, and functions to a real project.
+
+## CLI subcommands
+
+| Command | What it does |
+|---|---|
+| `pyric init [dir]` | Scaffold a pyric project — never prompts, idempotent, safe to rerun. `--template web` (default) creates a Vite app with canonical `firebase/*` imports; `--template static` creates a no-bundler app; `--template node` creates a script-style project. Run any template through `pyric dev` for sandbox resolution; inactive production tooling loads Firebase directly. Also `--name`, `--force` (overwrite scaffold-owned files), and `--json` (machine result on stdout). |
+| `pyric bridge` | Stand up an HTTP+WebSocket bridge an MCP client (Claude Code, Cursor) connects to (sandbox mode only) |
+| `pyric dev` | Local dev server with the pyric sandbox standing in for Firebase: serves `hosting.public`, resolves unmodified `firebase/*` imports to a pyric sandbox via a served import map, deploys + hot-reloads `firestore.rules` (SSE), opens an emulator-style sign-in helper for `signInWithPopup`/`signInWithRedirect`. The sandbox runs in a **SharedWorker by default** — one backend shared by every tab of the origin (live cross-tab sync), kept in the browser's IndexedDB so **your sandbox data — Firestore docs, auth users, RTDB, storage objects, and the traffic history — survives a refresh/restart by default** (see the persistence guide's coverage matrix for the exact tiers); a per-tab in-page sandbox is the fallback when SharedWorker is unavailable. Flags + exit codes: [CLI reference](docs/reference/cli.md#pyric-dev); persistence, ephemeral runs, clearing data, and SharedWorker tips: [persistence & multi-tab](docs/how-to/serve-persistence-and-multi-tab.md) |
+| `pyric snapshot` | Promote lived sandbox state (live `dev --persist`, else `.pyric/state/state.json`) to a committable fixture; `pyric dev --seed <fixture>` re-serves it (docs + users). `--out`, `--port`, `--force`, `--json` |
+| `pyric verify` | Replay a captured sandbox session against candidate rules (`--engine sandbox\|rules-test-api\|both`). Hosted Rules Test API needs SA/ADC via `FIREBASE_SA_BASE64` / `GOOGLE_APPLICATION_CREDENTIALS` |
+| `pyric mcp` | Start the stdio MCP server; attach to `pyric dev --bridge` when available or host a headless sandbox |
+| `pyric firestore rules lint <path>` | Lint a Firestore rules file |
+| `pyric firestore rules validate <path>` | Validate Firestore rules structure |
+| `pyric firestore rules simulate` | Run the local Firestore rules simulator |
+| `pyric firestore rules resolve <path>` | Resolve `2+modules` imports into a Firebase rules artifact |
+| `pyric firestore indexes generate <path...>` | Derive composite-index definitions from application source |
+| `pyric storage rules lint <path>` / `simulate` | Run local Storage rules lint or simulation |
+| `pyric database rules lint <path>` | Lint a Realtime Database rules JSON file |
+| `pyric database rules validate <path>` | Validate Realtime Database rules expressions |
+| `pyric database rules simulate` | Run the local Realtime Database rules simulator |
+| `pyric database rules generate` | Compile a constraints module to local `database.rules.json` without contacting production |
+
+Every command's full flags, defaults, exit codes, and environment variables are
+in the **[CLI reference](docs/reference/cli.md)**. Task guides and the rest of
+the docs are indexed in **[docs/](docs/README.md)**.
+
+### Persistence caveats (documented limits)
+
+- **Anonymous users don't persist** (no round-trip key) — but their *documents
+  do*. An app that calls `signInAnonymously` on load mints a new uid every
+  reload under `--persist`, so docs owned by prior anonymous uids accumulate
+  unreachably. Use the sign-in helper (or seeded users) for owner-based data
+  you want durable.
+- **The state file is not a point-in-time snapshot** — firestore and auth
+  sections flush on independent debounces; a crash between them can persist
+  docs whose owner user hasn't flushed yet (or vice versa).
+- **One writer tab at a time (in-page fallback only)** — when several per-tab
+  in-page sandboxes share one `.pyric/state` file, the first tab to flush holds
+  the writer lock; others run read-only (console warning + `persistReadOnly`
+  diagnostic) so they can't erase the writer's data. On the default SharedWorker
+  path this can't happen — the single worker is the sole writer.
+- **Loss window** — the final unsaved change can be lost if the tab CLOSES
+  within the flush debounce while the state exceeds ~60KB (keepalive cap);
+  smaller states flush on unload, and reloads are always safe. A reset (or
+  any delete-all) that empties a non-empty state first preserves the prior
+  file at `.pyric/state/state.json.bak`.
+
+### Agent onboarding (init → dev → MCP)
+
+Three parseable steps, no flags to discover:
+
+```bash
+pyric init myapp --json        # → {..., "nextSteps": [...]}
+cd myapp && bun install
+bun run dev:agent              # pyric dev --bridge --seed seed.json
+```
+
+Readiness probe: `GET <url>/__pyric/init.json` → 200 once serving (body
+carries the live rules hash). MCP endpoint: `<url>/__pyric/mcp`. With
+`pyric dev --json`, stdout's single line carries `{url, port, mcpUrl,
+rulesHash}`.
+
+## Programmatic subpaths
+
+| Subpath | Surface |
+|---|---|
+| `@pyric/cli/credentials/node` | `fromServiceAccount`, `fromAdc` — build a `ProjectScope` for the Rules Test API (`pyric verify --engine rules-test-api\|both`) |
+| `@pyric/cli/verify` | Captured-session replay for Firestore and RTDB rules |
+| `@pyric/cli/assurance` | Assurance campaign types and tools |
+| `@pyric/cli/assurance/browser` | Browser attachment for assurance campaigns |
+| `@pyric/cli/bridge` | `createBridge`, `startServer` (Node) / `connectBridge` (browser via conditional export). Vite integration is `pyricSandbox({ bridge })` in `@pyric/cli/vite`. |
+| `@pyric/cli/bridge/client` | Browser bridge client helpers |
+| `@pyric/cli/vite` | `pyricSandbox(opts)`, the dev-only firebase→sandbox swap plugin. Opts: `rules`, `persist`/`fresh`, `seed`, `capture`, `bridge` (MCP), `ui` (Pyric Studio at `/__pyric/ui/`, parity with `dev --ui`). |
+| `@pyric/cli/discover` | Credential-free crawl helpers for sandbox discovery (`crawl`, `findCollectionGroup`, `createFirestoreDiscoverTools`). Not registered on the default MCP bridge. |
+| `@pyric/cli/serve/worker` | SharedWorker serve runtime |
+| `@pyric/cli/remote` | Remote / headless helpers |
+| `@pyric/cli/register` | Registration helpers |
+
+## MCP tool surface (`pyric bridge`)
+
+The bridge composes its toolsets from the same factories used by its browser
+dispatcher so advertised and executable tools cannot drift. The canonical,
+always-current list is the
+[agent tool inventory](../../docs/agent-tools.md).
+
+**Sandbox-routed** — dispatched against the connected browser sandbox
+(`createFirestoreDataTools` + `createFirestoreSimulatorTools` +
+`createFirestoreInspectTools` + local RTDB inspection):
+
+- data: `firestore_get_document` / `_list_documents` / `_create_document` / `_add_document` / `_update_document` / `_delete_document` / `_batch_write` / `_query_where` / `firestore_create_with_auto_id`
+- stateful simulator session: `firestore_simulator_create` / `_execute` / `_read` / `_batch` / `_undo` / `_redo` / `_events` / `_transaction`
+- diagnostics: `sandbox_inspect` — single-call sandbox state/rules snapshot
+- RTDB authorization: `rtdb_simulate_access` — evaluates one operation against
+  the rules and data currently installed in the connected sandbox
+- RTDB structure: `rtdb_crawl_structure` — returns a bounded structural view of
+  current sandbox data without leaf values
+
+Assurance campaign tools remain available programmatically from
+`@pyric/cli/assurance`, but are not registered on the default MCP bridge.
+
+**In-process** — run on the bridge process itself (`createFirestoreRulesTools`
+without a live `ProjectScope`, so no Rules Test API tool):
+
+- `firestore_simulate_rules`
+- `firestore_rules_stdlib_list` / `_get`
+- `firestore_lint_rules`
+- `firestore_resolve_modules`
+
+### Gaps from the playground tool surface
+
+The `packages/playground/` app ships richer diagnostic tools that
+the `pyric bridge` does NOT register out of the box today. They're
+playground-specific orchestrators built on top of `useRuntimeStore`
+and other browser-only state:
+
+- `inspect_firestore_traffic` — structured dump of the sandbox traffic log
+- `seed_firestore_data_as_admin` — admin-bypass bulk writes for fixture setup
+- `generate_fixture_from_session` — snapshot `sandbox.history()` as a replay fixture
+- `try_rules_edit` — replay events under a proposed rules edit
+- `debug_firestore_rules` — orchestrator over simulate + lint + history + state
+
+The underlying primitives (`sandbox.history()`, `pyric/sandbox/replay`, and the
+rules simulator) remain available for custom compositions.

package/dist/assurance/attachment.d.ts

@@ -0,0 +1,24 @@
+import type { Sandbox } from "pyric/sandbox";
+import { type AssuranceAttachmentInventory, type AssuranceAttachmentSource, type AssuranceCoverageGap, type LocalFirebaseTarget } from "./types.js";
+export interface AssuranceAttachmentInput {
+    url: string;
+}
+export interface AssuranceAttachment {
+    target: LocalFirebaseTarget;
+    source: AssuranceAttachmentSource;
+    inventory: AssuranceAttachmentInventory;
+    coverageGaps: AssuranceCoverageGap[];
+}
+export type AssuranceAttachmentProvider = (input: AssuranceAttachmentInput) => Promise<AssuranceAttachment>;
+export interface SandboxAttachmentProviderOptions {
+    origin?: string;
+    fetchImpl?: typeof fetch;
+}
+export type { AssuranceAttachmentInventory, AssuranceAttachmentSource, AssuranceCoverageGap, } from "./types.js";
+/**
+ * Clone the sandbox currently hosting the connected bridge peer. The URL is an
+ * origin assertion and source for explicit rules metadata; no arbitrary host is
+ * contacted and the returned campaign target itself keeps networking forbidden.
+ */
+export declare function createSandboxAttachmentProvider(sandbox: Sandbox, options?: SandboxAttachmentProviderOptions): AssuranceAttachmentProvider;
+//# sourceMappingURL=attachment.d.ts.map

package/dist/assurance/attachment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment.d.ts","sourceRoot":"","sources":["../../src/assurance/attachment.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAGL,KAAK,4BAA4B,EACjC,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,MAAM,EAAE,yBAAyB,CAAC;IAClC,SAAS,EAAE,4BAA4B,CAAC;IACxC,YAAY,EAAE,oBAAoB,EAAE,CAAC;CACtC;AAED,MAAM,MAAM,2BAA2B,GAAG,CACxC,KAAK,EAAE,wBAAwB,KAC5B,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElC,MAAM,WAAW,gCAAgC;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,YAAY,EACV,4BAA4B,EAC5B,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AA2DpB;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,gCAAqC,GAC7C,2BAA2B,CAwG7B"}