@pyric/cli 0.1.0-alpha.10 → 0.1.0-alpha.12

package/dist/serve/docs-ui/docs/pyric-admin-firestore-reference-api.md

@@ -1,30 +1,2241 @@
+<!-- Generated from published package declarations via TypeDoc. Rendered by the api-reference content loader. -->
 
-<!-- Generated from published package declarations via TypeDoc. Do not edit by hand; run bun run docs:api:generate. -->
+## Interfaces
+
+<a id="admindocumentsnapshot"></a>
+
+### AdminDocumentSnapshot
+
+#### Extended by
+
+- [`AdminQueryDocumentSnapshot`](#adminquerydocumentsnapshot)
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="exists"></a> `exists` | `readonly` | `boolean` |
+| <a id="id"></a> `id` | `readonly` | `string` |
+| <a id="ref"></a> `ref` | `readonly` | [`DocumentReference`](#documentreference) |
+
+#### Methods
+
+<a id="data"></a>
+
+##### data()
+
+```ts
+data(): DocumentData;
+```
+
+###### Returns
+
+[`DocumentData`](pyric-firestore-reference-api.md#documentdata)
+
+***
+
+<a id="adminquerydocumentsnapshot"></a>
+
+### AdminQueryDocumentSnapshot
+
+#### Extends
+
+- [`AdminDocumentSnapshot`](#admindocumentsnapshot)
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="exists-1"></a> `exists` | `readonly` | `boolean` |
+| <a id="id-1"></a> `id` | `readonly` | `string` |
+| <a id="ref-1"></a> `ref` | `readonly` | [`DocumentReference`](#documentreference) |
+
+#### Methods
+
+<a id="data-2"></a>
+
+##### data()
+
+```ts
+data(): DocumentData;
+```
+
+###### Returns
+
+[`DocumentData`](pyric-firestore-reference-api.md#documentdata)
+
+###### Overrides
+
+[`AdminDocumentSnapshot`](#admindocumentsnapshot).[`data`](#data)
+
+***
+
+<a id="adminquerysnapshot"></a>
+
+### AdminQuerySnapshot
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="docs"></a> `docs` | `readonly` | [`AdminQueryDocumentSnapshot`](#adminquerydocumentsnapshot)[] |
+| <a id="empty"></a> `empty` | `readonly` | `boolean` |
+| <a id="size"></a> `size` | `readonly` | `number` |
+
+#### Methods
+
+<a id="foreach"></a>
+
+##### forEach()
+
+```ts
+forEach(callback: (snap: AdminQueryDocumentSnapshot) => void): void;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `callback` | (`snap`: [`AdminQueryDocumentSnapshot`](#adminquerydocumentsnapshot)) => `void` |
+
+###### Returns
+
+`void`
+
+***
+
+<a id="aggregatequerysnapshot"></a>
+
+### AggregateQuerySnapshot
+
+Result of `Query.aggregate(spec).get()`. `.data()` returns the
+computed numbers under the spec's aliases. Empty-input averages
+resolve to `null` to mirror Firestore production behavior
+(averaging over zero documents has no meaningful number).
+
+#### Methods
+
+<a id="data-4"></a>
+
+##### data()
+
+```ts
+data(): Record<string, number | null>;
+```
+
+###### Returns
+
+`Record`\<`string`, `number` \| `null`\>
+
+***
+
+<a id="collectionreference"></a>
+
+### CollectionReference
+
+#### Extends
+
+- [`Query`](#query)
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="id-2"></a> `id` | `readonly` | `string` |
+| <a id="path"></a> `path` | `readonly` | `string` |
+
+#### Methods
+
+<a id="add"></a>
+
+##### add()
+
+```ts
+add(data: DocumentData, opts?: OperationOptions): Promise<DocumentReference>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `data` | [`DocumentData`](pyric-firestore-reference-api.md#documentdata) |
+| `opts?` | `OperationOptions` |
+
+###### Returns
+
+`Promise`\<[`DocumentReference`](#documentreference)\>
+
+<a id="aggregate"></a>
+
+##### aggregate()
+
+```ts
+aggregate(spec: AggregateSpec): Promise<AggregateQuerySnapshot>;
+```
+
+Compute one or more aggregates over the documents matching this
+query. Mirrors the Admin SDK's `query.aggregate({ … }).get()`
+pattern, collapsed into one call for the simulator (no need to
+build an `AggregateQuery` reference type when there's no remote
+dispatch).
+
+Each entry in `spec` is keyed by a caller-chosen alias and
+resolves to an `AggregateField`. The returned snapshot exposes
+the computed numbers under the same aliases via `.data()`.
+
+Where / orderBy clauses ARE applied before aggregation (they
+narrow the candidate doc set). `limit` is honored — the aggregate
+computes against the limited set, matching production semantics.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `spec` | [`AggregateSpec`](#aggregatespec) |
+
+###### Returns
+
+`Promise`\<[`AggregateQuerySnapshot`](#aggregatequerysnapshot)\>
+
+###### Inherited from
+
+[`Query`](#query).[`aggregate`](#aggregate-2)
+
+<a id="applyfilter"></a>
+
+##### applyFilter()
+
+```ts
+applyFilter(filter: Filter): Query;
+```
+
+Add a composite filter (leaf, AND, or OR) to the query's filter
+stack. Each `applyFilter` call AND-s with whatever filters are
+already on the query — same implicit-AND semantics as multiple
+`where()` calls. To OR multiple predicates, wrap them with
+`{ kind: 'or', filters: [...] }` before calling. Backs the
+modular `or()` / `and()` constraints in `pyric/firestore`.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `filter` | [`Filter`](#filter) |
+
+###### Returns
+
+[`Query`](#query)
+
+###### Inherited from
+
+[`Query`](#query).[`applyFilter`](#applyfilter-2)
+
+<a id="doc"></a>
+
+##### doc()
+
+```ts
+doc(id?: string): DocumentReference;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `id?` | `string` |
+
+###### Returns
+
+[`DocumentReference`](#documentreference)
+
+<a id="endcursor"></a>
+
+##### endCursor()
+
+```ts
+endCursor(values: unknown[], inclusive: boolean): Query;
+```
+
+Set the end position of the query relative to the orderBy fields.
+`inclusive` controls `endAt` (true) vs `endBefore` (false).
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `values` | `unknown`[] |
+| `inclusive` | `boolean` |
+
+###### Returns
+
+[`Query`](#query)
+
+###### Inherited from
+
+[`Query`](#query).[`endCursor`](#endcursor-2)
+
+<a id="endcursorfromsnapshot"></a>
+
+##### endCursorFromSnapshot()
+
+```ts
+endCursorFromSnapshot(snapshot: AdminDocumentSnapshot, inclusive: boolean): Query;
+```
+
+Snapshot-based variant of [endCursor](#endcursor-2).
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `snapshot` | [`AdminDocumentSnapshot`](#admindocumentsnapshot) |
+| `inclusive` | `boolean` |
+
+###### Returns
+
+[`Query`](#query)
+
+###### Inherited from
+
+[`Query`](#query).[`endCursorFromSnapshot`](#endcursorfromsnapshot-2)
+
+<a id="get"></a>
+
+##### get()
+
+```ts
+get(opts?: OperationOptions): Promise<AdminQuerySnapshot>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `opts?` | `OperationOptions` |
+
+###### Returns
+
+`Promise`\<[`AdminQuerySnapshot`](#adminquerysnapshot)\>
+
+###### Inherited from
+
+[`Query`](#query).[`get`](#get-6)
+
+<a id="limit"></a>
+
+##### limit()
+
+```ts
+limit(n: number): Query;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `n` | `number` |
+
+###### Returns
+
+[`Query`](#query)
+
+###### Inherited from
+
+[`Query`](#query).[`limit`](#limit-2)
+
+<a id="limittolast"></a>
+
+##### limitToLast()
+
+```ts
+limitToLast(n: number): Query;
+```
+
+Limit from the END of the ordered result. Equivalent to reversing
+the orderBy, taking `n`, then re-reversing — the simulator
+implements it that way. Requires at least one `orderBy` clause on
+the query (matches the JS SDK's runtime contract).
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `n` | `number` |
+
+###### Returns
+
+[`Query`](#query)
+
+###### Inherited from
+
+[`Query`](#query).[`limitToLast`](#limittolast-2)
+
+<a id="orderby"></a>
+
+##### orderBy()
+
+```ts
+orderBy(field: string, direction?: OrderDirection): Query;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `field` | `string` |
+| `direction?` | [`OrderDirection`](pyric-firestore-reference-api.md#orderdirection) |
+
+###### Returns
+
+[`Query`](#query)
+
+###### Inherited from
+
+[`Query`](#query).[`orderBy`](#orderby-2)
+
+<a id="startcursor"></a>
+
+##### startCursor()
+
+```ts
+startCursor(values: unknown[], inclusive: boolean): Query;
+```
+
+Set the start position of the query relative to the orderBy
+fields. `values` corresponds 1:1 with the orderBy clauses on the
+query (one value per clause); `inclusive` controls `startAt` (true)
+vs `startAfter` (false). Repeated calls replace the previous
+cursor — matches production.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `values` | `unknown`[] |
+| `inclusive` | `boolean` |
+
+###### Returns
+
+[`Query`](#query)
+
+###### Inherited from
+
+[`Query`](#query).[`startCursor`](#startcursor-2)
+
+<a id="startcursorfromsnapshot"></a>
+
+##### startCursorFromSnapshot()
+
+```ts
+startCursorFromSnapshot(snapshot: AdminDocumentSnapshot, inclusive: boolean): Query;
+```
+
+Variant of [startCursor](#startcursor-2) that takes a `DocumentSnapshot`
+and extracts the cursor values from the snapshot's data at each
+orderBy field. Mirrors the JS SDK's `startAt(snapshot)` overload
+and shines for cursor-based pagination ("hand me the next page
+after this one"). Requires at least one `orderBy` clause —
+thrown at call time, not at get-time, so the failure surfaces
+close to the bug.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `snapshot` | [`AdminDocumentSnapshot`](#admindocumentsnapshot) |
+| `inclusive` | `boolean` |
+
+###### Returns
+
+[`Query`](#query)
+
+###### Inherited from
+
+[`Query`](#query).[`startCursorFromSnapshot`](#startcursorfromsnapshot-2)
+
+<a id="where"></a>
+
+##### where()
+
+```ts
+where(
+   field: string,
+   op: WhereFilterOp,
+   value: unknown): Query;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `field` | `string` |
+| `op` | [`WhereFilterOp`](pyric-firestore-reference-api.md#wherefilterop) |
+| `value` | `unknown` |
+
+###### Returns
+
+[`Query`](#query)
+
+###### Inherited from
+
+[`Query`](#query).[`where`](#where-2)
+
+***
+
+<a id="docchangesoptions"></a>
+
+### DocChangesOptions
+
+Options for `QuerySnapshot.docChanges`. Mirrors Web SDK shape.
+
+#### Properties
+
+| Property | Type |
+| :------ | :------ |
+| <a id="includemetadatachanges"></a> `includeMetadataChanges?` | `boolean` |
+
+***
+
+<a id="documentchange"></a>
+
+### DocumentChange
+
+#### Properties
+
+| Property | Modifier | Type | Description |
+| :------ | :------ | :------ | :------ |
+| <a id="doc-2"></a> `doc` | `readonly` | [`QueryDocumentSnapshot`](#querydocumentsnapshot) | - |
+| <a id="newindex"></a> `newIndex` | `readonly` | `number` | -1 for `removed`. |
+| <a id="oldindex"></a> `oldIndex` | `readonly` | `number` | -1 for `added`. |
+| <a id="type"></a> `type` | `readonly` | [`DocumentChangeType`](#documentchangetype-1) | - |
+
+***
+
+<a id="documentreference"></a>
+
+### DocumentReference
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="id-3"></a> `id` | `readonly` | `string` |
+| <a id="parent"></a> `parent` | `readonly` | [`CollectionReference`](#collectionreference) |
+| <a id="path-1"></a> `path` | `readonly` | `string` |
+
+#### Methods
+
+<a id="collection"></a>
+
+##### collection()
+
+```ts
+collection(name: string): CollectionReference;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `name` | `string` |
+
+###### Returns
+
+[`CollectionReference`](#collectionreference)
+
+<a id="delete"></a>
+
+##### delete()
+
+```ts
+delete(opts?: OperationOptions): Promise<void>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `opts?` | `OperationOptions` |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+<a id="get-2"></a>
+
+##### get()
+
+```ts
+get(opts?: OperationOptions): Promise<AdminDocumentSnapshot>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `opts?` | `OperationOptions` |
+
+###### Returns
+
+`Promise`\<[`AdminDocumentSnapshot`](#admindocumentsnapshot)\>
+
+<a id="set"></a>
+
+##### set()
+
+```ts
+set(data: DocumentData, options?: SetOptions): Promise<void>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `data` | [`DocumentData`](pyric-firestore-reference-api.md#documentdata) |
+| `options?` | [`SetOptions`](#setoptions) |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+<a id="update"></a>
+
+##### update()
+
+```ts
+update(data: DocumentData, opts?: OperationOptions): Promise<void>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `data` | [`DocumentData`](pyric-firestore-reference-api.md#documentdata) |
+| `opts?` | `OperationOptions` |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+***
+
+<a id="documentsnapshot"></a>
+
+### DocumentSnapshot
+
+#### Extended by
+
+- [`QueryDocumentSnapshot`](#querydocumentsnapshot)
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="id-4"></a> `id` | `readonly` | `string` |
+| <a id="metadata"></a> `metadata` | `readonly` | [`SnapshotMetadata`](#snapshotmetadata) |
+| <a id="ref-2"></a> `ref` | `readonly` | `SnapshotDocRef` |
+
+#### Methods
+
+<a id="data-6"></a>
+
+##### data()
+
+```ts
+data(): DocumentData;
+```
+
+###### Returns
+
+`DocumentData`
+
+<a id="exists-2"></a>
+
+##### exists()
+
+```ts
+exists(): boolean;
+```
+
+###### Returns
+
+`boolean`
+
+<a id="get-4"></a>
+
+##### get()
+
+```ts
+get(fieldPath: string): unknown;
+```
+
+Field accessor mirroring `firebase/firestore`'s `DocumentSnapshot.get(fieldPath)`.
+Dotted paths supported. Missing intermediate keys yield `undefined`
+— production behavior; agents commonly chain optional reads.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `fieldPath` | `string` |
+
+###### Returns
+
+`unknown`
+
+***
+
+<a id="firestore"></a>
+
+### Firestore
+
+#### Extended by
+
+- [`SandboxFirestore`](#sandboxfirestore)
+
+#### Methods
+
+<a id="batch"></a>
+
+##### batch()
+
+```ts
+batch(): WriteBatch;
+```
+
+###### Returns
+
+[`WriteBatch`](#writebatch)
+
+<a id="collection-2"></a>
+
+##### collection()
+
+```ts
+collection(path: string): CollectionReference;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `path` | `string` |
+
+###### Returns
+
+[`CollectionReference`](#collectionreference)
+
+<a id="collectiongroup"></a>
+
+##### collectionGroup()
+
+```ts
+collectionGroup(collectionId: string): Query;
+```
+
+Cross-collection query — returns a `Query` that scans every
+document under every collection whose final segment matches
+`collectionId`, regardless of position in the path. Matches the
+Admin SDK's `Firestore.collectionGroup(id)` shape.
+
+The returned `Query` accepts `where` / `orderBy` / `limit` like
+any other; the simulator gathers all candidate docs first, then
+applies the constraints in-memory.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `collectionId` | `string` |
+
+###### Returns
+
+[`Query`](#query)
+
+<a id="doc-3"></a>
+
+##### doc()
+
+```ts
+doc(path: string): DocumentReference;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `path` | `string` |
+
+###### Returns
+
+[`DocumentReference`](#documentreference)
+
+<a id="runtransaction"></a>
+
+##### runTransaction()
+
+```ts
+runTransaction<R>(fn: (tx: Transaction) => R | Promise<R>, opts?: OperationOptions): Promise<R>;
+```
+
+###### Type Parameters
+
+| Type Parameter |
+| :------ |
+| `R` |
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `fn` | (`tx`: [`Transaction`](#transaction)) => `R` \| `Promise`\<`R`\> |
+| `opts?` | `OperationOptions` |
+
+###### Returns
+
+`Promise`\<`R`\>
+
+***
+
+<a id="lintwarning"></a>
+
+### LintWarning
+
+#### Properties
+
+| Property | Type | Description |
+| :------ | :------ | :------ |
+| <a id="fix"></a> `fix?` | `string` | - |
+| <a id="location"></a> `location?` | \{ `functionName?`: `string`; `matchPath?`: `string`; `ruleIndex?`: `number`; `testCaseDescription?`: `string`; \} | - |
+| `location.functionName?` | `string` | - |
+| `location.matchPath?` | `string` | - |
+| `location.ruleIndex?` | `number` | - |
+| `location.testCaseDescription?` | `string` | Test-case description from `TestCase.description`. Set only by rules that operate on the optional test suite (e.g. REQUEST_TIME_NOT_PINNED). |
+| <a id="message"></a> `message` | `string` | - |
+| <a id="rule"></a> `rule` | `string` | - |
+| <a id="severity"></a> `severity` | `"error"` \| `"warning"` | - |
+
+***
+
+<a id="query"></a>
+
+### Query
+
+#### Extended by
+
+- [`CollectionReference`](#collectionreference)
+
+#### Methods
+
+<a id="aggregate-2"></a>
+
+##### aggregate()
+
+```ts
+aggregate(spec: AggregateSpec): Promise<AggregateQuerySnapshot>;
+```
+
+Compute one or more aggregates over the documents matching this
+query. Mirrors the Admin SDK's `query.aggregate({ … }).get()`
+pattern, collapsed into one call for the simulator (no need to
+build an `AggregateQuery` reference type when there's no remote
+dispatch).
+
+Each entry in `spec` is keyed by a caller-chosen alias and
+resolves to an `AggregateField`. The returned snapshot exposes
+the computed numbers under the same aliases via `.data()`.
+
+Where / orderBy clauses ARE applied before aggregation (they
+narrow the candidate doc set). `limit` is honored — the aggregate
+computes against the limited set, matching production semantics.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `spec` | [`AggregateSpec`](#aggregatespec) |
+
+###### Returns
+
+`Promise`\<[`AggregateQuerySnapshot`](#aggregatequerysnapshot)\>
+
+<a id="applyfilter-2"></a>
+
+##### applyFilter()
+
+```ts
+applyFilter(filter: Filter): Query;
+```
+
+Add a composite filter (leaf, AND, or OR) to the query's filter
+stack. Each `applyFilter` call AND-s with whatever filters are
+already on the query — same implicit-AND semantics as multiple
+`where()` calls. To OR multiple predicates, wrap them with
+`{ kind: 'or', filters: [...] }` before calling. Backs the
+modular `or()` / `and()` constraints in `pyric/firestore`.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `filter` | [`Filter`](#filter) |
+
+###### Returns
+
+[`Query`](#query)
+
+<a id="endcursor-2"></a>
+
+##### endCursor()
+
+```ts
+endCursor(values: unknown[], inclusive: boolean): Query;
+```
+
+Set the end position of the query relative to the orderBy fields.
+`inclusive` controls `endAt` (true) vs `endBefore` (false).
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `values` | `unknown`[] |
+| `inclusive` | `boolean` |
+
+###### Returns
+
+[`Query`](#query)
+
+<a id="endcursorfromsnapshot-2"></a>
+
+##### endCursorFromSnapshot()
+
+```ts
+endCursorFromSnapshot(snapshot: AdminDocumentSnapshot, inclusive: boolean): Query;
+```
+
+Snapshot-based variant of [endCursor](#endcursor-2).
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `snapshot` | [`AdminDocumentSnapshot`](#admindocumentsnapshot) |
+| `inclusive` | `boolean` |
+
+###### Returns
+
+[`Query`](#query)
+
+<a id="get-6"></a>
+
+##### get()
+
+```ts
+get(opts?: OperationOptions): Promise<AdminQuerySnapshot>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `opts?` | `OperationOptions` |
+
+###### Returns
+
+`Promise`\<[`AdminQuerySnapshot`](#adminquerysnapshot)\>
+
+<a id="limit-2"></a>
+
+##### limit()
+
+```ts
+limit(n: number): Query;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `n` | `number` |
+
+###### Returns
+
+[`Query`](#query)
+
+<a id="limittolast-2"></a>
+
+##### limitToLast()
+
+```ts
+limitToLast(n: number): Query;
+```
+
+Limit from the END of the ordered result. Equivalent to reversing
+the orderBy, taking `n`, then re-reversing — the simulator
+implements it that way. Requires at least one `orderBy` clause on
+the query (matches the JS SDK's runtime contract).
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `n` | `number` |
+
+###### Returns
+
+[`Query`](#query)
+
+<a id="orderby-2"></a>
+
+##### orderBy()
+
+```ts
+orderBy(field: string, direction?: OrderDirection): Query;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `field` | `string` |
+| `direction?` | [`OrderDirection`](pyric-firestore-reference-api.md#orderdirection) |
+
+###### Returns
+
+[`Query`](#query)
+
+<a id="startcursor-2"></a>
+
+##### startCursor()
+
+```ts
+startCursor(values: unknown[], inclusive: boolean): Query;
+```
+
+Set the start position of the query relative to the orderBy
+fields. `values` corresponds 1:1 with the orderBy clauses on the
+query (one value per clause); `inclusive` controls `startAt` (true)
+vs `startAfter` (false). Repeated calls replace the previous
+cursor — matches production.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `values` | `unknown`[] |
+| `inclusive` | `boolean` |
+
+###### Returns
+
+[`Query`](#query)
+
+<a id="startcursorfromsnapshot-2"></a>
+
+##### startCursorFromSnapshot()
+
+```ts
+startCursorFromSnapshot(snapshot: AdminDocumentSnapshot, inclusive: boolean): Query;
+```
+
+Variant of [startCursor](#startcursor-2) that takes a `DocumentSnapshot`
+and extracts the cursor values from the snapshot's data at each
+orderBy field. Mirrors the JS SDK's `startAt(snapshot)` overload
+and shines for cursor-based pagination ("hand me the next page
+after this one"). Requires at least one `orderBy` clause —
+thrown at call time, not at get-time, so the failure surfaces
+close to the bug.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `snapshot` | [`AdminDocumentSnapshot`](#admindocumentsnapshot) |
+| `inclusive` | `boolean` |
+
+###### Returns
+
+[`Query`](#query)
+
+<a id="where-2"></a>
+
+##### where()
+
+```ts
+where(
+   field: string,
+   op: WhereFilterOp,
+   value: unknown): Query;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `field` | `string` |
+| `op` | [`WhereFilterOp`](pyric-firestore-reference-api.md#wherefilterop) |
+| `value` | `unknown` |
+
+###### Returns
+
+[`Query`](#query)
+
+***
+
+<a id="querydocumentsnapshot"></a>
+
+### QueryDocumentSnapshot
+
+Production narrows `data()` to non-undefined here. We follow suit so
+that agent code calling `snap.data().foo` doesn't need a guard for
+the items inside a `QuerySnapshot.docs` array.
+
+#### Extends
+
+- [`DocumentSnapshot`](#documentsnapshot)
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="id-5"></a> `id` | `readonly` | `string` |
+| <a id="metadata-1"></a> `metadata` | `readonly` | [`SnapshotMetadata`](#snapshotmetadata) |
+| <a id="ref-3"></a> `ref` | `readonly` | `SnapshotDocRef` |
+
+#### Methods
+
+<a id="data-8"></a>
+
+##### data()
+
+```ts
+data(): DocumentData;
+```
+
+###### Returns
+
+`DocumentData`
+
+###### Overrides
+
+[`DocumentSnapshot`](#documentsnapshot).[`data`](#data-6)
+
+<a id="exists-4"></a>
+
+##### exists()
+
+```ts
+exists(): boolean;
+```
+
+###### Returns
+
+`boolean`
+
+###### Inherited from
+
+[`DocumentSnapshot`](#documentsnapshot).[`exists`](#exists-2)
+
+<a id="get-8"></a>
+
+##### get()
+
+```ts
+get(fieldPath: string): unknown;
+```
+
+Field accessor mirroring `firebase/firestore`'s `DocumentSnapshot.get(fieldPath)`.
+Dotted paths supported. Missing intermediate keys yield `undefined`
+— production behavior; agents commonly chain optional reads.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `fieldPath` | `string` |
+
+###### Returns
+
+`unknown`
+
+###### Inherited from
+
+[`DocumentSnapshot`](#documentsnapshot).[`get`](#get-4)
+
+***
+
+<a id="querysnapshot"></a>
+
+### QuerySnapshot
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="docs-1"></a> `docs` | `readonly` | [`QueryDocumentSnapshot`](#querydocumentsnapshot)[] |
+| <a id="empty-1"></a> `empty` | `readonly` | `boolean` |
+| <a id="metadata-2"></a> `metadata` | `readonly` | [`SnapshotMetadata`](#snapshotmetadata) |
+| <a id="query-1"></a> `query` | `readonly` | `SnapshotQueryRef` |
+| <a id="size-1"></a> `size` | `readonly` | `number` |
+
+#### Methods
+
+<a id="docchanges"></a>
+
+##### docChanges()
+
+```ts
+docChanges(options?: DocChangesOptions): DocumentChange[];
+```
+
+Per findings section 4: cached by `includeMetadataChanges` value; throws if
+called with `true` when the listener did not subscribe with
+`includeMetadataChanges: true`. The Slice 2 implementation produces
+"all docs added" on the first fire — Slice 3 supplies real diffs.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `options?` | [`DocChangesOptions`](#docchangesoptions) |
+
+###### Returns
+
+[`DocumentChange`](#documentchange)[]
+
+<a id="foreach-2"></a>
+
+##### forEach()
+
+```ts
+forEach(callback: (snap: QueryDocumentSnapshot) => void): void;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `callback` | (`snap`: [`QueryDocumentSnapshot`](#querydocumentsnapshot)) => `void` |
+
+###### Returns
+
+`void`
+
+***
+
+<a id="rulesmetrics"></a>
+
+### RulesMetrics
+
+#### Properties
+
+| Property | Type |
+| :------ | :------ |
+| <a id="allowrulecount"></a> `allowRuleCount` | `number` |
+| <a id="functioncount"></a> `functionCount` | `number` |
+| <a id="getcallcount"></a> `getCallCount` | `number` |
+| <a id="maxcalldepth"></a> `maxCallDepth` | `number` |
+| <a id="maxchaindepth"></a> `maxChainDepth` | `number` |
+| <a id="maxchainop"></a> `maxChainOp` | `string` |
+| <a id="maxestimatedexpressions"></a> `maxEstimatedExpressions` | `number` |
+| <a id="maxletbindings"></a> `maxLetBindings` | `number` |
+| <a id="maxletbindingsfunction"></a> `maxLetBindingsFunction` | `string` |
+| <a id="sourcesize"></a> `sourceSize` | `number` |
+
+***
+
+<a id="sandboxfirestore"></a>
+
+### SandboxFirestore
+
+Sandbox-extended Firestore handle. Adds three sandbox-only methods
+on top of the production-shaped [Firestore](#firestore) surface:
+
+  - [SandboxFirestore.setRules](#setrules) — replace the active ruleset
+    for subsequent operations.
+  - [SandboxFirestore.seed](#seed) — replace stored documents with a
+    fresh seed map (rules are preserved).
+  - [SandboxFirestore.snapshot](#snapshot) — capture all stored documents
+    as a path-keyed map.
+
+These have no production analog. They use sandbox vocabulary
+(`setRules`, `seed`, `snapshot`) deliberately so a reader can't
+confuse them with Firebase deployment semantics.
+
+#### Extends
+
+- [`Firestore`](#firestore)
+
+#### Methods
+
+<a id="batch-2"></a>
+
+##### batch()
+
+```ts
+batch(): WriteBatch;
+```
+
+###### Returns
+
+[`WriteBatch`](#writebatch)
+
+###### Inherited from
+
+[`Firestore`](#firestore).[`batch`](#batch)
+
+<a id="collection-4"></a>
+
+##### collection()
+
+```ts
+collection(path: string): CollectionReference;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `path` | `string` |
+
+###### Returns
+
+[`CollectionReference`](#collectionreference)
+
+###### Inherited from
+
+[`Firestore`](#firestore).[`collection`](#collection-2)
+
+<a id="collectiongroup-2"></a>
+
+##### collectionGroup()
+
+```ts
+collectionGroup(collectionId: string): Query;
+```
+
+Cross-collection query — returns a `Query` that scans every
+document under every collection whose final segment matches
+`collectionId`, regardless of position in the path. Matches the
+Admin SDK's `Firestore.collectionGroup(id)` shape.
+
+The returned `Query` accepts `where` / `orderBy` / `limit` like
+any other; the simulator gathers all candidate docs first, then
+applies the constraints in-memory.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `collectionId` | `string` |
+
+###### Returns
+
+[`Query`](#query)
+
+###### Inherited from
+
+[`Firestore`](#firestore).[`collectionGroup`](#collectiongroup)
+
+<a id="doc-5"></a>
+
+##### doc()
+
+```ts
+doc(path: string): DocumentReference;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `path` | `string` |
+
+###### Returns
+
+[`DocumentReference`](#documentreference)
+
+###### Inherited from
+
+[`Firestore`](#firestore).[`doc`](#doc-3)
+
+<a id="runtransaction-2"></a>
+
+##### runTransaction()
+
+```ts
+runTransaction<R>(fn: (tx: Transaction) => R | Promise<R>, opts?: OperationOptions): Promise<R>;
+```
+
+###### Type Parameters
+
+| Type Parameter |
+| :------ |
+| `R` |
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `fn` | (`tx`: [`Transaction`](#transaction)) => `R` \| `Promise`\<`R`\> |
+| `opts?` | `OperationOptions` |
+
+###### Returns
+
+`Promise`\<`R`\>
+
+###### Inherited from
+
+[`Firestore`](#firestore).[`runTransaction`](#runtransaction)
+
+<a id="seed"></a>
+
+##### seed()
+
+```ts
+seed(options?: {
+  documents?: Record<string, DocumentData>;
+}): LintResult;
+```
+
+Replace stored documents with a new seed map. Active rules are
+preserved. Pass an empty `documents` map (or omit it) to clear
+state without touching rules.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `options?` | \{ `documents?`: `Record`\<`string`, [`DocumentData`](pyric-firestore-reference-api.md#documentdata)\>; \} |
+| `options.documents?` | `Record`\<`string`, [`DocumentData`](pyric-firestore-reference-api.md#documentdata)\> |
+
+###### Returns
+
+[`LintResult`](pyric-firestore-reference-api.md#lintresult)
+
+<a id="setrules"></a>
+
+##### setRules()
+
+```ts
+setRules(rules: string): LintResult;
+```
+
+Replace the active ruleset. Returns the lint result so callers can
+surface warnings; if the source has parse-level errors, the rules
+are not swapped (consistent with `LocalEnvironment.deployRules`).
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `rules` | `string` |
+
+###### Returns
+
+[`LintResult`](pyric-firestore-reference-api.md#lintresult)
+
+<a id="snapshot"></a>
+
+##### snapshot()
+
+```ts
+snapshot(): Record<string, DocumentData>;
+```
+
+Capture every stored document as a `{ [path]: data }` map. Reads
+from the live state and is independent of rules.
+
+###### Returns
+
+`Record`\<`string`, [`DocumentData`](pyric-firestore-reference-api.md#documentdata)\>
+
+***
+
+<a id="setoptions"></a>
+
+### SetOptions
+
+Options for `DocumentReference.set`. Mirrors the modular Web-SDK's
+`SetOptions` shape with pyric's `auth` per-op override layered on.
+
+  - default (neither flag set) → REPLACE the existing document
+    entirely. Firestore default for `set()`.
+  - `{ merge: true }` → shallow-merge every top-level field in
+    `data` into the existing document. Fields not in `data` are
+    preserved. Rule eval still runs the `update` clause when the
+    doc exists.
+  - `{ mergeFields: [...] }` → project `data` down to just the
+    listed top-level fields, then merge. Other fields in `data` are
+    ignored; other fields in the existing doc are preserved.
+
+`merge` and `mergeFields` are mutually exclusive at the JS-SDK
+level. We don't currently enforce the constraint — if both are
+provided, `mergeFields` wins (matches the JS SDK's effective
+behavior).
+
+#### Extends
+
+- `OperationOptions`
+
+#### Properties
+
+| Property | Type |
+| :------ | :------ |
+| <a id="auth"></a> `auth?` | \{ `token?`: `Record`\<`string`, `unknown`\>; `uid`: `string`; \} |
+| `auth.token?` | `Record`\<`string`, `unknown`\> |
+| `auth.uid` | `string` |
+| <a id="merge"></a> `merge?` | `boolean` |
+| <a id="mergefields"></a> `mergeFields?` | readonly `string`[] |
+
+***
+
+<a id="snapshotmetadata"></a>
+
+### SnapshotMetadata
+
+Mirrors `firebase/firestore`'s `SnapshotMetadata`. `fromCache` is always
+`false` (the sandbox has no offline cache). `hasPendingWrites` transitions
+(item 3): a local write's optimistic echo carries `true`, and the server
+ack carries `false` — so `includeMetadataChanges` has an observable effect
+matching prod (COMPAT firestore#85).
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="fromcache"></a> `fromCache` | `readonly` | `false` |
+| <a id="haspendingwrites"></a> `hasPendingWrites` | `readonly` | `boolean` |
+
+***
+
+<a id="snapshotobserver"></a>
+
+### SnapshotObserver
+
+Observer form accepted by `onSnapshot`. Mirrors `firebase/firestore`'s
+`PartialObserver<T>` shape — any subset of the three handlers. `complete`
+is accepted for shape parity but never fires in the sandbox: the local
+listener stream has no terminal state.
+
+#### Type Parameters
+
+| Type Parameter |
+| :------ |
+| `T` |
+
+#### Properties
+
+| Property | Type |
+| :------ | :------ |
+| <a id="complete"></a> `complete?` | () => `void` |
+| <a id="error"></a> `error?` | (`error`: `unknown`) => `void` |
+| <a id="next"></a> `next?` | (`snapshot`: `T`) => `void` |
+
+***
+
+<a id="transaction"></a>
+
+### Transaction
+
+#### Methods
+
+<a id="delete-2"></a>
+
+##### delete()
+
+```ts
+delete(ref: DocumentReference): Transaction;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `ref` | [`DocumentReference`](#documentreference) |
+
+###### Returns
+
+[`Transaction`](#transaction)
+
+<a id="get-10"></a>
+
+##### get()
+
+###### Call Signature
+
+```ts
+get(ref: DocumentReference): Promise<AdminDocumentSnapshot>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `ref` | [`DocumentReference`](#documentreference) |
+
+###### Returns
+
+`Promise`\<[`AdminDocumentSnapshot`](#admindocumentsnapshot)\>
+
+###### Call Signature
+
+```ts
+get(query: Query): Promise<AdminQuerySnapshot>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `query` | [`Query`](#query) |
+
+###### Returns
+
+`Promise`\<[`AdminQuerySnapshot`](#adminquerysnapshot)\>
+
+<a id="set-2"></a>
+
+##### set()
+
+```ts
+set(ref: DocumentReference, data: DocumentData): Transaction;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `ref` | [`DocumentReference`](#documentreference) |
+| `data` | [`DocumentData`](pyric-firestore-reference-api.md#documentdata) |
+
+###### Returns
+
+[`Transaction`](#transaction)
+
+<a id="update-2"></a>
+
+##### update()
+
+```ts
+update(ref: DocumentReference, data: DocumentData): Transaction;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `ref` | [`DocumentReference`](#documentreference) |
+| `data` | [`DocumentData`](pyric-firestore-reference-api.md#documentdata) |
+
+###### Returns
+
+[`Transaction`](#transaction)
+
+***
+
+<a id="writebatch"></a>
+
+### WriteBatch
+
+#### Methods
+
+<a id="commit"></a>
+
+##### commit()
+
+```ts
+commit(opts?: OperationOptions): Promise<void>;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `opts?` | `OperationOptions` |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+<a id="delete-4"></a>
+
+##### delete()
+
+```ts
+delete(ref: DocumentReference): WriteBatch;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `ref` | [`DocumentReference`](#documentreference) |
+
+###### Returns
+
+[`WriteBatch`](#writebatch)
+
+<a id="set-4"></a>
+
+##### set()
+
+```ts
+set(ref: DocumentReference, data: DocumentData): WriteBatch;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `ref` | [`DocumentReference`](#documentreference) |
+| `data` | [`DocumentData`](pyric-firestore-reference-api.md#documentdata) |
+
+###### Returns
+
+[`WriteBatch`](#writebatch)
+
+<a id="update-4"></a>
+
+##### update()
+
+```ts
+update(ref: DocumentReference, data: DocumentData): WriteBatch;
+```
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `ref` | [`DocumentReference`](#documentreference) |
+| `data` | [`DocumentData`](pyric-firestore-reference-api.md#documentdata) |
+
+###### Returns
+
+[`WriteBatch`](#writebatch)
+
+## Type Aliases
+
+<a id="aggregatefield"></a>
+
+### AggregateField
+
+```ts
+type AggregateField =
+  | {
+  kind: "count";
+}
+  | {
+  field: string;
+  kind: "sum";
+}
+  | {
+  field: string;
+  kind: "average";
+};
+```
+
+Single aggregate definition. Field is required for sum / average,
+forbidden for count (no field has any meaning when you're
+counting rows). Encoded as discriminated union so type errors
+surface at the call site, not at runtime.
+
+***
+
+<a id="aggregatespec"></a>
+
+### AggregateSpec
+
+```ts
+type AggregateSpec = Record<string, AggregateField>;
+```
+
+Spec passed to `Query.aggregate(...)`. Aliases become the keys in
+ the returned snapshot's `.data()` object.
+
+***
+
+<a id="documentchangetype-1"></a>
+
+### DocumentChangeType
+
+```ts
+type DocumentChangeType = "added" | "modified" | "removed";
+```
+
+***
+
+<a id="filter"></a>
+
+### Filter
+
+```ts
+type Filter =
+  | {
+  field: string;
+  kind: "where";
+  op: WhereFilterOp;
+  value: unknown;
+}
+  | {
+  filters: Filter[];
+  kind: "and";
+}
+  | {
+  filters: Filter[];
+  kind: "or";
+};
+```
+
+Composite filter tree for `Query.applyFilter`. Recursive — `and` /
+`or` carry their own `filters` array of nested `Filter`s; the
+leaves are field/op/value triples (`kind: 'where'`).
+
+Mirrors `firebase/firestore`'s `QueryFilterConstraint` shape, just
+as a tagged-union value type (the SDK's classes carry an `_op`
+field; ours is the `kind` discriminant).
+
+***
+
+<a id="snapshotlistenoptions"></a>
+
+### SnapshotListenOptions
+
+```ts
+type SnapshotListenOptions = SnapshotListenerOptions;
+```
+
+Mirrors `firebase/firestore`'s `SnapshotListenOptions`. The
+`includeMetadataChanges` flag is accepted for API parity but has no
+observable effect in the sandbox: there's no offline cache and no
+pending-writes window, so `metadata.fromCache` and
+`metadata.hasPendingWrites` are always `false` (snapshot-listeners.ts section 6).
+
+***
+
+<a id="unsubscribe"></a>
+
+### Unsubscribe()
+
+```ts
+type Unsubscribe = () => void;
+```
+
+Returned from `onSnapshot`. Calling it deregisters the listener and
+stops further callback invocations. Idempotent.
+
+#### Returns
+
+`void`
 
 ## Functions
 
+<a id="getadminfirestore"></a>
+
+### getAdminFirestore()
+
+#### Call Signature
+
+```ts
+function getAdminFirestore(ctx: SandboxContext): SandboxFirestore;
+```
+
+Resolve a **rules-bypassing** Firestore handle for a context — the
+Pyric Studio admin lens (Gap #2). Same chainable `SandboxFirestore`
+surface as `getFirestore`, but every operation it issues (reads,
+writes, queries, batches, transactions) SKIPS security-rule evaluation
+and is treated as ALLOW. This is the modular/chainable-shaped sibling of
+the path-string `sandbox.admin.*` bypass — it reuses the exact same
+`LocalEnvironment` bypass execution path (`bypassRules` on the op),
+rather than reimplementing it.
+
+Storage preconditions still apply (a `create` on an existing doc still
+fails `already-exists`, matching real Firestore admin), and the same
+`request`/`write` events fire + listeners wake, so the change shows up
+live and on the traffic log (stamped as an admin-bypass read/write).
+
+Use for "edit anything as admin" surfaces (Studio F2). For rules-applied
+impersonation ("act as this user"), use `getFirestore(sandbox.withAuth({
+uid }))` instead — that path is unchanged.
+
+##### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `ctx` | [`SandboxContext`](pyric-firestore-reference-api.md#sandboxcontext) |
+
+##### Returns
+
+[`SandboxFirestore`](#sandboxfirestore)
+
+##### Example
+
+```ts
+import { initializeSandbox } from 'pyric/sandbox';
+import { getFirestore, getAdminFirestore } from 'pyric-admin/firestore';
+
+const sandbox = initializeSandbox();
+getFirestore(sandbox.withAuth(null)).setRules('...deny everything...');
+
+// Denied under rules:
+await getFirestore(sandbox.withAuth({ uid: 'alice' }))
+  .doc('locked/x').set({ a: 1 }); // throws permission-denied
+
+// Bypasses rules:
+await getAdminFirestore(sandbox).doc('locked/x').set({ a: 1 }); // ok
+```
+
+#### Call Signature
+
+```ts
+function getAdminFirestore(sandbox: Sandbox): SandboxFirestore;
+```
+
+Resolve a **rules-bypassing** Firestore handle for a context — the
+Pyric Studio admin lens (Gap #2). Same chainable `SandboxFirestore`
+surface as `getFirestore`, but every operation it issues (reads,
+writes, queries, batches, transactions) SKIPS security-rule evaluation
+and is treated as ALLOW. This is the modular/chainable-shaped sibling of
+the path-string `sandbox.admin.*` bypass — it reuses the exact same
+`LocalEnvironment` bypass execution path (`bypassRules` on the op),
+rather than reimplementing it.
+
+Storage preconditions still apply (a `create` on an existing doc still
+fails `already-exists`, matching real Firestore admin), and the same
+`request`/`write` events fire + listeners wake, so the change shows up
+live and on the traffic log (stamped as an admin-bypass read/write).
+
+Use for "edit anything as admin" surfaces (Studio F2). For rules-applied
+impersonation ("act as this user"), use `getFirestore(sandbox.withAuth({
+uid }))` instead — that path is unchanged.
+
+##### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `sandbox` | [`Sandbox`](pyric-firestore-reference-api.md#sandbox) |
+
+##### Returns
+
+[`SandboxFirestore`](#sandboxfirestore)
+
+##### Example
+
+```ts
+import { initializeSandbox } from 'pyric/sandbox';
+import { getFirestore, getAdminFirestore } from 'pyric-admin/firestore';
+
+const sandbox = initializeSandbox();
+getFirestore(sandbox.withAuth(null)).setRules('...deny everything...');
+
+// Denied under rules:
+await getFirestore(sandbox.withAuth({ uid: 'alice' }))
+  .doc('locked/x').set({ a: 1 }); // throws permission-denied
+
+// Bypasses rules:
+await getAdminFirestore(sandbox).doc('locked/x').set({ a: 1 }); // ok
+```
+
+***
+
 <a id="getfirestore"></a>
 
 ### getFirestore()
 
 ```ts
-function getFirestore(target?: any): SandboxFirestore;
+function getFirestore(target?:
+  | SandboxAdminApp
+  | SandboxContext): SandboxFirestore;
 ```
 
 Return the admin Firestore handle.
 
-  - `getFirestore(ctx)` — the original context form (rules-applied for the
+  - `getFirestore(ctx)` — the original context form (rules-APPLIED for the
     ctx's captured identity). Unchanged; idempotent per `SandboxContext`.
-  - `getFirestore(app)` — resolves a PyricAdminApp's sandbox.
-  - `getFirestore()` — resolves the default app; throws `app/no-app` when
-    nothing is initialized.
+    This is the pyric-internal rules-simulation shape, not a firebase-admin
+    shape, so it keeps rule evaluation.
+  - `getFirestore(app)` — resolves a [PyricAdminApp](pyric-admin-app-reference-api.md#pyricadminapp)'s sandbox to the
+    rules-BYPASS admin lens (firebase-admin parity, #394).
+  - `getFirestore()` — resolves the default app to the rules-BYPASS admin
+    lens; throws `app/no-app` when nothing is initialized.
+
+The app forms mirror `firebase-admin/firestore`'s `getFirestore(app?)`,
+which bypasses security rules — so a Cloud Function's admin write lands the
+same way it does in production, instead of being denied as `request.auth ==
+null` by the sandbox's anon lens (the #394 deny-direction divergence).
 
 #### Parameters
 
 | Parameter | Type |
 | :------ | :------ |
-| `target?` | `any` |
+| `target?` | \| [`SandboxAdminApp`](pyric-admin-app-reference-api.md#sandboxadminapp) \| [`SandboxContext`](pyric-firestore-reference-api.md#sandboxcontext) |
 
 #### Returns
 
-`SandboxFirestore`
+[`SandboxFirestore`](#sandboxfirestore)
+
+***
+
+<a id="onsnapshot"></a>
+
+### onSnapshot()
+
+#### Call Signature
+
+```ts
+function onSnapshot(reference: DocumentReference, observer: SnapshotObserver<DocumentSnapshot>): Unsubscribe;
+```
+
+##### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `reference` | [`DocumentReference`](#documentreference) |
+| `observer` | [`SnapshotObserver`](#snapshotobserver)\<[`DocumentSnapshot`](#documentsnapshot)\> |
+
+##### Returns
+
+[`Unsubscribe`](#unsubscribe)
+
+#### Call Signature
+
+```ts
+function onSnapshot(
+   reference: DocumentReference,
+   options: SnapshotListenerOptions,
+   observer: SnapshotObserver<DocumentSnapshot>): Unsubscribe;
+```
+
+##### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `reference` | [`DocumentReference`](#documentreference) |
+| `options` | `SnapshotListenerOptions` |
+| `observer` | [`SnapshotObserver`](#snapshotobserver)\<[`DocumentSnapshot`](#documentsnapshot)\> |
+
+##### Returns
+
+[`Unsubscribe`](#unsubscribe)
+
+#### Call Signature
+
+```ts
+function onSnapshot(
+   reference: DocumentReference,
+   onNext: (snapshot: DocumentSnapshot) => void,
+   onError?: (error: unknown) => void,
+   onCompletion?: () => void): Unsubscribe;
+```
+
+##### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `reference` | [`DocumentReference`](#documentreference) |
+| `onNext` | (`snapshot`: [`DocumentSnapshot`](#documentsnapshot)) => `void` |
+| `onError?` | (`error`: `unknown`) => `void` |
+| `onCompletion?` | () => `void` |
+
+##### Returns
+
+[`Unsubscribe`](#unsubscribe)
+
+#### Call Signature
+
+```ts
+function onSnapshot(
+   reference: DocumentReference,
+   options: SnapshotListenerOptions,
+   onNext: (snapshot: DocumentSnapshot) => void,
+   onError?: (error: unknown) => void,
+   onCompletion?: () => void): Unsubscribe;
+```
+
+##### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `reference` | [`DocumentReference`](#documentreference) |
+| `options` | `SnapshotListenerOptions` |
+| `onNext` | (`snapshot`: [`DocumentSnapshot`](#documentsnapshot)) => `void` |
+| `onError?` | (`error`: `unknown`) => `void` |
+| `onCompletion?` | () => `void` |
+
+##### Returns
+
+[`Unsubscribe`](#unsubscribe)
+
+#### Call Signature
+
+```ts
+function onSnapshot(reference: Query | CollectionReference, observer: SnapshotObserver<QuerySnapshot>): Unsubscribe;
+```
+
+##### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `reference` | [`Query`](#query) \| [`CollectionReference`](#collectionreference) |
+| `observer` | [`SnapshotObserver`](#snapshotobserver)\<[`QuerySnapshot`](#querysnapshot)\> |
+
+##### Returns
+
+[`Unsubscribe`](#unsubscribe)
+
+#### Call Signature
+
+```ts
+function onSnapshot(
+   reference: Query | CollectionReference,
+   options: SnapshotListenerOptions,
+   observer: SnapshotObserver<QuerySnapshot>): Unsubscribe;
+```
+
+##### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `reference` | [`Query`](#query) \| [`CollectionReference`](#collectionreference) |
+| `options` | `SnapshotListenerOptions` |
+| `observer` | [`SnapshotObserver`](#snapshotobserver)\<[`QuerySnapshot`](#querysnapshot)\> |
+
+##### Returns
+
+[`Unsubscribe`](#unsubscribe)
+
+#### Call Signature
+
+```ts
+function onSnapshot(
+   reference: Query | CollectionReference,
+   onNext: (snapshot: QuerySnapshot) => void,
+   onError?: (error: unknown) => void,
+   onCompletion?: () => void): Unsubscribe;
+```
+
+##### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `reference` | [`Query`](#query) \| [`CollectionReference`](#collectionreference) |
+| `onNext` | (`snapshot`: [`QuerySnapshot`](#querysnapshot)) => `void` |
+| `onError?` | (`error`: `unknown`) => `void` |
+| `onCompletion?` | () => `void` |
+
+##### Returns
+
+[`Unsubscribe`](#unsubscribe)
+
+#### Call Signature
+
+```ts
+function onSnapshot(
+   reference: Query | CollectionReference,
+   options: SnapshotListenerOptions,
+   onNext: (snapshot: QuerySnapshot) => void,
+   onError?: (error: unknown) => void,
+   onCompletion?: () => void): Unsubscribe;
+```
+
+##### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `reference` | [`Query`](#query) \| [`CollectionReference`](#collectionreference) |
+| `options` | `SnapshotListenerOptions` |
+| `onNext` | (`snapshot`: [`QuerySnapshot`](#querysnapshot)) => `void` |
+| `onError?` | (`error`: `unknown`) => `void` |
+| `onCompletion?` | () => `void` |
+
+##### Returns
+
+[`Unsubscribe`](#unsubscribe)
+
+## References
+
+<a id="authstate"></a>
+
+### AuthState
+
+Re-exports [AuthState](pyric-firestore-reference-api.md#authstate)
+
+***
+
+<a id="documentdata"></a>
+
+### DocumentData
+
+Re-exports [DocumentData](pyric-firestore-reference-api.md#documentdata)
+
+***
+
+<a id="fieldvalue"></a>
+
+### FieldValue
+
+Re-exports [FieldValue](pyric-firestore-reference-api.md#fieldvalue)
+
+***
+
+<a id="fieldvaluesentinel"></a>
+
+### FieldValueSentinel
+
+Re-exports [FieldValueSentinel](pyric-firestore-reference-api.md#fieldvaluesentinel)
+
+***
+
+<a id="lintresult"></a>
+
+### LintResult
+
+Re-exports [LintResult](pyric-firestore-reference-api.md#lintresult)
+
+***
+
+<a id="orderdirection"></a>
+
+### OrderDirection
+
+Re-exports [OrderDirection](pyric-firestore-reference-api.md#orderdirection)
+
+***
+
+<a id="sandbox"></a>
+
+### Sandbox
+
+Re-exports [Sandbox](pyric-firestore-reference-api.md#sandbox)
+
+***
+
+<a id="sandboxcontext"></a>
+
+### SandboxContext
+
+Re-exports [SandboxContext](pyric-firestore-reference-api.md#sandboxcontext)
+
+***
+
+<a id="sandboxerror"></a>
+
+### SandboxError
+
+Re-exports [SandboxError](pyric-firestore-reference-api.md#sandboxerror)
+
+***
+
+<a id="timestamp"></a>
+
+### Timestamp
+
+Re-exports [Timestamp](pyric-firestore-reference-api.md#timestamp)
+
+***
+
+<a id="wherefilterop"></a>
+
+### WhereFilterOp
+
+Re-exports [WhereFilterOp](pyric-firestore-reference-api.md#wherefilterop)