@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/ui-traffic-trafficstats.md

@@ -0,0 +1,46 @@
+# `<TrafficStats>`
+
+The aggregation panel — totals, deny rate, and count breakdowns by method /
+origin / path. Pairs with `useTrafficStats`.
+
+```ts
+import { TrafficStats, useTrafficStats } from '@pyric/ui/traffic';
+```
+
+## Example
+
+```tsx
+const stats = useTrafficStats({ events: filtered, topPaths: 10 });
+
+<TrafficStats stats={stats} />
+```
+
+Feed it the filtered or full event list depending on what the panel should
+reflect — it's pure derivation either way.
+
+## Props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `stats` | `TrafficStatsSummary` | yes | From `useTrafficStats`. |
+| `className` | `string` | no | Forwarded to the root. |
+
+## Styling hooks
+
+```
+[data-pyric-ui="traffic-stats"]          /* root; carries --pyric-deny-rate */
+[data-pyric-stat-totals]
+[data-pyric-stat]                        /* + data-pyric-stat-key="total|allows|denies|deny-rate" */
+[data-pyric-stat-label] / [data-pyric-stat-value]
+[data-pyric-stat-group]                  /* + data-pyric-stat-group-label="method|origin|path" */
+[data-pyric-stat-group-heading]
+[data-pyric-stat-bucket]                 /* + data-pyric-stat-key */
+[data-pyric-stat-bucket-label] / [data-pyric-stat-bucket-count]
+```
+
+## Notes
+
+- The deny rate is exposed twice — as a `%` text value and as the
+  `--pyric-deny-rate` custom property on the root, for a proportional meter.
+- `byPath` is capped at `topPaths` (default 10); `byMethod` and `byOrigin` are
+  uncapped (bounded domains).

package/dist/serve/docs-ui/docs/ui-traffic.md

@@ -0,0 +1,102 @@
+# `@pyric/ui/traffic`
+
+Headless components + hooks for observing rule-eval traffic — a Chrome
+DevTools Network-panel-style **log** and a per-rule **heatmap**, plus stats
+and grouping. Decoupled from `pyric/sandbox`: the data hook takes a `source`
+function, so the same components work against the sandbox or a production
+log feed.
+
+```ts
+import {
+  useTrafficMonitor,
+  useTrafficFilter,
+  useRuleHeatmap,
+  useTrafficStats,
+  useTrafficGroups,
+  TrafficLog,
+  TrafficRow,
+  TrafficGroupRow,
+  TrafficDetail,
+  RuleHeatmap,
+  TrafficStats,
+  type TrafficEvent,
+  type TrafficSource,
+} from '@pyric/ui/traffic';
+```
+
+## The decoupling contract
+
+```ts
+type TrafficSource = (cb: (event: TrafficEvent) => void) => () => void;
+```
+
+`pyric/sandbox`'s `Sandbox.onRequest` matches this signature exactly —
+`useTrafficMonitor({ source: sandbox.onRequest })` wires with zero adapter
+code. `TrafficEvent` is structurally identical to the sandbox's `RequestEvent`
+but the library owns its own copy so it never imports `pyric/sandbox`.
+
+## Components
+
+- [TrafficLog](../ui-traffic-trafficlog/) — the event stream; virtualized flat list,
+  or singles + collapsible groups in grouped mode.
+- [TrafficDetail](../ui-traffic-trafficdetail/) — drill-in panel for one event.
+- [RuleHeatmap](../ui-traffic-ruleheatmap/) — per-rule fire / deny rollup.
+- [TrafficStats](../ui-traffic-trafficstats/) — totals + breakdowns.
+
+## Hooks
+
+Hook docs live in the source JSDoc — every hook has an options interface and a
+return-shape interface commented per field. Summary:
+
+- **`useTrafficMonitor({ source, bufferSize?, paused?, transform? })`** — the
+  core. A capped ring buffer (default 5000) with `pause` / `resume` / `clear`
+  and derived `counts`. `transform` runs per event before buffering, for
+  consumer-side payload shrinking.
+- **`useTrafficFilter({ events })`** — filters along origin / result / path.
+  Defaults to **user-origin, allow+deny visible, listener hidden** — the probe
+  found listener traffic is 94–99.6% of events.
+- **`useRuleHeatmap({ events })`** — rolls events up by
+  `matchedRule.ruleIndex`: per-rule total / allow / deny counts + deny ratio.
+- **`useTrafficStats({ events, topPaths? })`** — totals, deny rate, and count
+  breakdowns by method / origin / path.
+- **`useTrafficGroups({ events })`** — folds the buffer into singles +
+  collapsible groups: `groupId` batches/transactions, and consecutive
+  listener-run aggregation.
+
+## Minimal wiring
+
+```tsx
+function TrafficPanel({ sandbox }) {
+  const monitor = useTrafficMonitor({ source: sandbox.onRequest });
+  const { filtered, filter, setOrigin, setResult, setPathQuery } =
+    useTrafficFilter({ events: monitor.events });
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const selected = monitor.events.find((e) => e.id === selectedId);
+
+  return selected ? (
+    <TrafficDetail event={selected} onBack={() => setSelectedId(null)} />
+  ) : (
+    <TrafficLog
+      events={[...filtered].reverse()}
+      selectedId={selectedId ?? undefined}
+      onSelect={(e) => setSelectedId(e.id)}
+    />
+  );
+}
+```
+
+## Notes
+
+- **Latency is de-featured.** `evalMs` stays on `TrafficEvent` and shows in
+  `TrafficDetail`, but it is not a log column — this is a local simulator.
+- **Classification is the consumer's.** `expected` / `ambiguous` /
+  `unexpected` verdicts are app-source analysis, not sandbox data. Components
+  expose a `renderClassification` render-prop slot for it.
+
+## See also
+
+- design rationale — the milestone roadmap.
+- design rationale — the sandbox
+  `onRequest` API and the empirical probe findings this builds on.
+- Live showcase — the "Traffic
+  Monitor" route.

package/dist/serve/docs-ui/docs/ui.md

@@ -0,0 +1,90 @@
+# `@pyric/ui` docs
+
+Per-component reference. Each page is one-screen — import, minimal example, props table, common gotchas.
+
+## Primitives
+
+`@pyric/ui/primitives`
+
+- [CopyButton](../ui-primitives-copybutton/) — clipboard button exposing `data-copied`.
+- [Badge](../ui-primitives-badge/) — headless pill exposing `data-pyric-badge-kind`.
+- [JsonView](../ui-primitives-jsonview/) — collapsible JSON tree.
+- [SegmentedControl](../ui-primitives-segmentedcontrol/) — single-select chip group (ARIA radiogroup).
+- [ConfirmDialog](../ui-primitives-confirmdialog/) — headless dialog + imperative `useConfirm` provider.
+- [Toast](../ui-primitives-toast/) — toast queue + `useToast` hook.
+- [VirtualList](../ui-primitives-virtuallist/) — TanStack-Virtual wrapper for long lists.
+
+## Firestore
+
+`@pyric/ui/firestore`
+
+- [DocumentPreview](../ui-firestore-documentpreview/) — read-only field renderer.
+- [DocumentEditor](../ui-firestore-documenteditor/) — reducer-backed editor + compound component.
+- [CollectionList](../ui-firestore-collectionlist/) — headless list renderer for collections.
+- [DocumentList](../ui-firestore-documentlist/) — paginated + optionally virtualized doc list.
+- [ReferencePicker](../ui-firestore-referencepicker/) — path text input + browseable panel.
+- [QueryBuilder](../ui-firestore-querybuilder/) — single-level where/orderBy/limit form.
+- [DeleteWithConfirm](../ui-firestore-deletewithconfirm/) — composes useConfirm + useRecursiveDelete.
+
+## Auth
+
+`@pyric/ui/auth` — emulator-style sign-in for sandbox auth.
+
+- [AuthSignInHelper](../ui-auth-authsigninhelper/) — account picker + add-account
+  form behind `useAuthFlowHelper` (the `AuthFlowResolver` host for
+  `signInWithPopup` / `signInWithRedirect`), with emulator-grade
+  custom-claims validation.
+- [Auth users admin](../ui-auth-authusers/) — `useAuthUsers` +
+  `useAuthUserEditor`, the `AuthUserList` table, `AuthUserForm`,
+  `ClaimsField`, and confirm-gated delete/clear actions.
+
+## Storage
+
+`@pyric/ui/storage` — browse Firebase Storage (sandbox or prod) via one
+`FirebaseStorage` handle. See the [subpath overview](../ui-storage/)
+for the wiring + hooks.
+
+- [ObjectBrowser](../ui-storage-objectbrowser/) — folders-first row list; folder rows navigate, object rows select; virtualized above 100 rows.
+- [PathBreadcrumb](../ui-storage-pathbreadcrumb/) — clickable ancestor trail.
+
+## Traffic
+
+`@pyric/ui/traffic` — observe rule-eval traffic. See the
+[subpath overview](../ui-traffic/) for the decoupling contract + hooks.
+
+- [TrafficLog](../ui-traffic-trafficlog/) — the DevTools-style event stream (+ `TrafficRow`, `TrafficGroupRow`).
+- [TrafficDetail](../ui-traffic-trafficdetail/) — drill-in panel for one event.
+- [RuleHeatmap](../ui-traffic-ruleheatmap/) — per-rule fire / deny rollup.
+- [TrafficStats](../ui-traffic-trafficstats/) — totals + breakdowns.
+
+## Hooks
+
+All hooks are exported from the corresponding subpath (`/firestore/hooks` or `/primitives`). The hook documentation lives in the source JSDoc — every exported hook has a description, an options interface, and a return-shape interface with comments per field. Open the source or your editor's hover-help to read them.
+
+Highlights:
+
+- `useFirestoreDoc(ref)`, `useFirestoreCollection(query)` — `onSnapshot` subscriptions returning `{ data, error, isLoading }`.
+- `useDocumentEditor({ initial })` — owns the editor reducer; returns `{ tree, errorCount, isDirty, isValid, setValue, …, toData }`.
+- `useReferencePicker({ firestore, listCollections })` — browse + parse state machine.
+- `useQueryBuilder({ initial })` — composes a Firestore `Query` from a where/orderBy/limit form.
+- `useCollectionList`, `useDocumentList`, `useRecursiveDelete`, `useConfirm`, `useToast`, `useContainerSize`.
+- `useStorageList(storage, path)` — `listAll` + prefix→folder synthesis; `{ status, items, prefixes, entries, error, refresh }` + the optimistic insert/remove seam.
+- `usePathState({ path?, onPathChange?, defaultPath? })` — controlled/uncontrolled storage-path navigation.
+- `useTrafficMonitor({ source })` — capped ring buffer over a `TrafficSource`; `pause`/`resume`/`clear` + `counts`.
+- `useTrafficFilter`, `useRuleHeatmap`, `useTrafficStats`, `useTrafficGroups` — pure derivations over a traffic buffer.
+
+## See also
+
+- Live showcase — one Astro page per component with copy-pasteable Tailwind styling for the `[data-pyric-*]` selectors.
+
+## Styling pattern (all components)
+
+The library ships **no CSS**. Components emit structural `data-pyric-*` attributes that consumers target with attribute selectors:
+
+```css
+[data-pyric-ui='document-preview'] { /* root */ }
+[data-pyric-field-type='reference'][data-pyric-clickable] { /* clickable refs */ }
+[data-pyric-toast][data-pyric-toast-kind='error'] { /* error toast */ }
+```
+
+See `examples/admin-playground/src/styles/global.css` for a complete set of Tailwind-based rules covering every component the library ships.

package/dist/serve/docs-ui/docs/watch-and-review/index.html

@@ -0,0 +1,25 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Watch the agent work, then check it · Pyric Studio</title><meta name="description" content="See every operation your agent performs, live, with the verdict that decided it."><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" open> <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/" aria-current="page"> 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"> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> 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" open> <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/" aria-current="page"> 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"> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> 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="#nav-group-inspect-and-correct">Inspect and correct</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <a href="#nav-section-inspect-and-correct-inspect-the-sandbox">Inspect the sandbox</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Review agent activity</span> </li> </ol> </nav>  <article class="prose">  <h1 id="watch-the-agent-work-then-check-it">Watch the agent work, then check it</h1>
+<p>An agent you cannot see is an agent you cannot trust. Pyric makes the agent’s work visible two ways: live, in Studio, while it happens, and after the fact, in the event stream, where every operation carries its own receipt.</p>
+<h2 id="watch-it-live-in-studio">Watch it live in Studio</h2>
+<p>Start the sandbox with Studio on:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#61AFEF">pyric</span><span style="color:#98C379"> dev</span><span style="color:#D19A66"> --ui</span></span></code></pre>
+<p>Studio opens at <code>/__pyric/ui/</code> against the same sandbox your app tab and MCP client use.</p>
+<p>Ask your connected agent for a feature and watch documents appear in the Firestore tab as it writes them, because there is one backend and everyone is looking at it. When the agent claims it seeded ten users, the Auth tab either shows ten users or it does not.</p>
+<h2 id="review-activity-through-the-event-stream">Review activity through the event stream</h2>
+<p>Every operation the backend performs is a typed event, and agent operations land in the same stream as your app’s. Each event carries:</p>
+<ul>
+<li>the operation and who performed it</li>
+<li>its provenance</li>
+<li>the rules verdict that allowed or denied it, and for a denial, the rule that said no and the data it saw</li>
+</ul>
+<p>Reviewing an agent session is reading the stream, not reconstructing it. That turns “the agent says it worked” into something you can check line by line. The Traffic tab shows the stream live, and <a href="../see-whats-happening/">see what’s happening</a> covers reading it yourself, including from code.</p>
+<h2 id="understand-the-access-boundary">Understand the access boundary</h2>
+<p>The trust posture is short:</p>
+<ul>
+<li>The sandbox is local state, in your dev server and your browser tab. Every tool call against it stays on your machine, and there is no cloud project behind it to damage.</li>
+<li>The agent reaches production only through the deploy tools, and those work only with credentials you deliberately provide, a login or a service account, as a separate step.</li>
+<li>Until you take that step, the blast radius of any agent session is a sandbox you can reset in one command.</li>
+</ul>
+<p>When you do take it, <a href="../ship-to-production/">ship to production</a> covers what deploying involves and how to verify a ruleset before it goes live.</p>
+<h2 id="where-to-go-next">Where to go next</h2>
+<p>If the agent is not connected yet, start at <a href="../set-up-your-agent/">set up your agent</a>. To go deeper on the stream itself, read <a href="../see-whats-happening/">see what’s happening</a>.</p>  </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="#watch-it-live-in-studio">Watch it live in Studio</a> </li><li data-depth="2"> <a href="#review-activity-through-the-event-stream">Review activity through the event stream</a> </li><li data-depth="2"> <a href="#understand-the-access-boundary">Understand the access boundary</a> </li><li data-depth="2"> <a href="#where-to-go-next">Where to go 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/watch-and-review.md

@@ -0,0 +1,40 @@
+
+# Watch the agent work, then check it
+
+An agent you cannot see is an agent you cannot trust. Pyric makes the agent's work visible two ways: live, in Studio, while it happens, and after the fact, in the event stream, where every operation carries its own receipt.
+
+## Watch it live in Studio
+
+Start the sandbox with Studio on:
+
+```bash
+pyric dev --ui
+```
+
+Studio opens at `/__pyric/ui/` against the same sandbox your app tab and MCP client use.
+
+Ask your connected agent for a feature and watch documents appear in the Firestore tab as it writes them, because there is one backend and everyone is looking at it. When the agent claims it seeded ten users, the Auth tab either shows ten users or it does not.
+
+## Review activity through the event stream
+
+Every operation the backend performs is a typed event, and agent operations land in the same stream as your app's. Each event carries:
+
+- the operation and who performed it
+- its provenance
+- the rules verdict that allowed or denied it, and for a denial, the rule that said no and the data it saw
+
+Reviewing an agent session is reading the stream, not reconstructing it. That turns "the agent says it worked" into something you can check line by line. The Traffic tab shows the stream live, and [see what's happening](../see-whats-happening/) covers reading it yourself, including from code.
+
+## Understand the access boundary
+
+The trust posture is short:
+
+- The sandbox is local state, in your dev server and your browser tab. Every tool call against it stays on your machine, and there is no cloud project behind it to damage.
+- The agent reaches production only through the deploy tools, and those work only with credentials you deliberately provide, a login or a service account, as a separate step.
+- Until you take that step, the blast radius of any agent session is a sandbox you can reset in one command.
+
+When you do take it, [ship to production](../ship-to-production/) covers what deploying involves and how to verify a ruleset before it goes live.
+
+## Where to go next
+
+If the agent is not connected yet, start at [set up your agent](../set-up-your-agent/). To go deeper on the stream itself, read [see what's happening](../see-whats-happening/).

package/dist/serve/docs-ui/docs/what-your-agent-can-do/index.html

@@ -0,0 +1,81 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Work with the sandbox through an agent · Pyric Studio</title><meta name="description" content="Every backend capability, callable as a tool: inspect, query, simulate, shape, ship, verify."><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" open> <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/" aria-current="page"> 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"> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> 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" open> <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/" aria-current="page"> 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"> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> 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="#nav-group-inspect-and-correct">Inspect and correct</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <a href="#nav-section-inspect-and-correct-work-with-an-agent">Work with an agent</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Work through an agent</span> </li> </ol> </nav>  <article class="prose">  <h1 id="work-with-the-sandbox-through-an-agent">Work with the sandbox through an agent</h1>
+<p>Once connected, your agent works on the backend the way you do, except every capability is a tool call it can make and check. This page walks the surface by what the agent can accomplish, not by tool name. The names appear where they matter.</p>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>The agent can</th><th>Through</th></tr></thead><tbody><tr><td>Read, write, and query as any user</td><td>the Firestore and RTDB data tools</td></tr><tr><td>See what exists before guessing</td><td><code>sandbox_inspect</code> and the discovery crawls</td></tr><tr><td>Prove a rule before writing it</td><td><code>firestore_simulate_rules</code> and simulator sessions</td></tr><tr><td>Shape the state it tests against</td><td>seed, reset, and snapshot</td></tr><tr><td>Operate the real project</td><td>the deploy and auth-config tools, with credentials you provide</td></tr><tr><td>Check its own work</td><td>session replay against candidate rules</td></tr></tbody></table></div>
+<h2 id="read-write-and-query-with-application-identity">Read, write, and query with application identity</h2>
+<p>The data plane is the app’s own surface, and the agent uses it as a specific identity, so a read that should be denied is denied for the agent too.</p>
+<ul>
+<li><strong>Firestore</strong>: create, read, update, and delete documents, and run queries with filters and ordering.</li>
+<li><strong>Realtime Database</strong>: get, set, update, and push.</li>
+<li><strong>RTDB inspection</strong>: crawls the active sandbox snapshot and reports its local structure without production access.</li>
+</ul>
+<h2 id="inspect-state-before-changing-it">Inspect state before changing it</h2>
+<p>The single most-used move is one call. <code>sandbox_inspect</code> returns:</p>
+<ul>
+<li>the current rules with a lint summary</li>
+<li>a document census by collection</li>
+<li>the recent denials and requests from the event log</li>
+</ul>
+<p>The tool’s own source records why it exists. In a recorded debug session, diagnosing “why aren’t my rules working” took fifty-one tool calls and seventy-two thousand tokens of grepping through packages. The same diagnosis is now one round-trip, and it is the first thing a well-set-up agent does.</p>
+<p>Discovery works on real projects too. Firestore has no schema, so Pyric infers one: the agent can crawl a live database by sampling, cost-bounded and cost-reported, and come back with the shape of what is actually there. The same goes for a Realtime Database tree.</p>
+<h2 id="simulate-a-rule-before-writing-it">Simulate a rule before writing it</h2>
+<p>The agent can ask whether a specific request, by a specific identity, would be allowed under a ruleset, and get the verdict with the rule and data that decided it. No deploy, no waiting.</p>
+<p>For longer work it can open a stateful simulator session:</p>
+<ul>
+<li>seed documents and execute writes</li>
+<li>run batches and transactions</li>
+<li>read the event log</li>
+<li>undo or redo any step</li>
+</ul>
+<p>A scratchpad for rules and data with a real undo stack, which means the agent can try something wrong and back out cleanly.</p>
+<h2 id="shape-the-state-under-test">Shape the state under test</h2>
+<p>Backend state is a tool input. The agent can seed a scenario, reset to clean, and snapshot what it built so the state survives as a fixture. Between test runs, between hypotheses, between conversations.</p>
+<p>The same seed, reset, and snapshot moves you make yourself, callable.</p>
+<h2 id="understand-the-credential-boundary">Understand the credential boundary</h2>
+<p>Given credentials you choose to hand it, the agent can run the control plane over REST, with no extra CLI:</p>
+<ul>
+<li>deploy rules, indexes, hosting, and functions</li>
+<li>enable auth providers and manage authorized domains</li>
+<li>provision databases and storage</li>
+</ul>
+<p>This is the same path you walk in <a href="../set-up-the-project/">set up the project</a> and <a href="../ship-to-production/">ship to production</a>. Without those credentials, none of it is reachable.</p>
+<h2 id="check-the-result">Check the result</h2>
+<p>Verification is a tool, not a ritual. The agent can replay a captured session of real operations against a candidate ruleset and learn which operations change verdict, before anything deploys.</p>
+<p>It writes a rule, replays, reads the diff, and fixes what flipped. That loop is the difference between an agent that asserts its rules work and one that has evidence.</p>
+<h2 id="understand-the-supported-boundary">Understand the supported boundary</h2>
+<p>The surface is wide because Firebase’s is: data, rules, identity, deployment, and two database models.</p>
+<p>The exact tool count drifts as consolidation continues, and consolidation is ongoing on purpose. Fewer, stronger calls beat a long menu. What holds steady is the capability list above.</p>
+<h2 id="where-to-go-next">Where to go next</h2>
+<p>The tools carry the moves. The procedures for the hard problems live in <a href="../skills/">skills</a>. And everything the agent does lands in a stream you can read, in <a href="../watch-and-review/">watch and review</a>.</p>  </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="#read-write-and-query-with-application-identity">Read, write, and query with application identity</a> </li><li data-depth="2"> <a href="#inspect-state-before-changing-it">Inspect state before changing it</a> </li><li data-depth="2"> <a href="#simulate-a-rule-before-writing-it">Simulate a rule before writing it</a> </li><li data-depth="2"> <a href="#shape-the-state-under-test">Shape the state under test</a> </li><li data-depth="2"> <a href="#understand-the-credential-boundary">Understand the credential boundary</a> </li><li data-depth="2"> <a href="#check-the-result">Check the result</a> </li><li data-depth="2"> <a href="#understand-the-supported-boundary">Understand the supported boundary</a> </li><li data-depth="2"> <a href="#where-to-go-next">Where to go 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/what-your-agent-can-do.md

@@ -0,0 +1,78 @@
+
+# Work with the sandbox through an agent
+
+Once connected, your agent works on the backend the way you do, except every capability is a tool call it can make and check. This page walks the surface by what the agent can accomplish, not by tool name. The names appear where they matter.
+
+| The agent can | Through |
+|---|---|
+| Read, write, and query as any user | the Firestore and RTDB data tools |
+| See what exists before guessing | `sandbox_inspect` and the discovery crawls |
+| Prove a rule before writing it | `firestore_simulate_rules` and simulator sessions |
+| Shape the state it tests against | seed, reset, and snapshot |
+| Operate the real project | the deploy and auth-config tools, with credentials you provide |
+| Check its own work | session replay against candidate rules |
+
+## Read, write, and query with application identity
+
+The data plane is the app's own surface, and the agent uses it as a specific identity, so a read that should be denied is denied for the agent too.
+
+- **Firestore**: create, read, update, and delete documents, and run queries with filters and ordering.
+- **Realtime Database**: get, set, update, and push.
+- **RTDB inspection**: crawls the active sandbox snapshot and reports its local structure without production access.
+
+## Inspect state before changing it
+
+The single most-used move is one call. `sandbox_inspect` returns:
+
+- the current rules with a lint summary
+- a document census by collection
+- the recent denials and requests from the event log
+
+The tool's own source records why it exists. In a recorded debug session, diagnosing "why aren't my rules working" took fifty-one tool calls and seventy-two thousand tokens of grepping through packages. The same diagnosis is now one round-trip, and it is the first thing a well-set-up agent does.
+
+Discovery works on real projects too. Firestore has no schema, so Pyric infers one: the agent can crawl a live database by sampling, cost-bounded and cost-reported, and come back with the shape of what is actually there. The same goes for a Realtime Database tree.
+
+## Simulate a rule before writing it
+
+The agent can ask whether a specific request, by a specific identity, would be allowed under a ruleset, and get the verdict with the rule and data that decided it. No deploy, no waiting.
+
+For longer work it can open a stateful simulator session:
+
+- seed documents and execute writes
+- run batches and transactions
+- read the event log
+- undo or redo any step
+
+A scratchpad for rules and data with a real undo stack, which means the agent can try something wrong and back out cleanly.
+
+## Shape the state under test
+
+Backend state is a tool input. The agent can seed a scenario, reset to clean, and snapshot what it built so the state survives as a fixture. Between test runs, between hypotheses, between conversations.
+
+The same seed, reset, and snapshot moves you make yourself, callable.
+
+## Understand the credential boundary
+
+Given credentials you choose to hand it, the agent can run the control plane over REST, with no extra CLI:
+
+- deploy rules, indexes, hosting, and functions
+- enable auth providers and manage authorized domains
+- provision databases and storage
+
+This is the same path you walk in [set up the project](../set-up-the-project/) and [ship to production](../ship-to-production/). Without those credentials, none of it is reachable.
+
+## Check the result
+
+Verification is a tool, not a ritual. The agent can replay a captured session of real operations against a candidate ruleset and learn which operations change verdict, before anything deploys.
+
+It writes a rule, replays, reads the diff, and fixes what flipped. That loop is the difference between an agent that asserts its rules work and one that has evidence.
+
+## Understand the supported boundary
+
+The surface is wide because Firebase's is: data, rules, identity, deployment, and two database models.
+
+The exact tool count drifts as consolidation continues, and consolidation is ongoing on purpose. Fewer, stronger calls beat a long menu. What holds steady is the capability list above.
+
+## Where to go next
+
+The tools carry the moves. The procedures for the hard problems live in [skills](../skills/). And everything the agent does lands in a stream you can read, in [watch and review](../watch-and-review/).