@microsoft/rayfin-guide 1.33.2 → 1.34.0-alpha.1148

package/assets/docs/cli/environment-variables.md

@@ -17,6 +17,7 @@ The `rayfin env` command (or the auto-emit built into `rayfin up`) maps them to
 | `RAYFIN_PUBLIC_TENANT_ID` | Entra ID tenant for workspace disambiguation. | `rayfin up` |
 | `RAYFIN_PUBLIC_PORTAL_URL` | Fabric Portal base URL (for example, `https://app.fabric.microsoft.com/`). | `rayfin up` |
 | `RAYFIN_PUBLIC_SERVICE_MODE` | `rayfin` (real backend) or `mock` (local testing). | User-set in `rayfin/.env` |
+| `RAYFIN_PUBLIC_FRONTEND_PORT` | Stable per-project frontend dev-server port. Assigned once and reused so the dev server pins a deterministic origin the deployed backend can allow-list. | `rayfin dev` / `rayfin up` |
 
 ### Framework mapping
 
@@ -31,9 +32,14 @@ The `rayfin env` command (or the auto-emit built into `rayfin up`) maps them to
 | `RAYFIN_PUBLIC_TENANT_ID` | `VITE_FABRIC_TENANT_ID` | `NEXT_PUBLIC_FABRIC_TENANT_ID` | `TENANT_ID` |
 | `RAYFIN_PUBLIC_PORTAL_URL` | `VITE_FABRIC_PORTAL_URL` | `NEXT_PUBLIC_FABRIC_PORTAL_URL` | `PORTAL_URL` |
 | `RAYFIN_PUBLIC_SERVICE_MODE` | `VITE_SERVICE_MODE` | `NEXT_PUBLIC_SERVICE_MODE` | `SERVICE_MODE` |
+| `RAYFIN_PUBLIC_FRONTEND_PORT` | `VITE_PORT` | `PORT` | `FRONTEND_PORT` |
 
 Custom `RAYFIN_PUBLIC_*` variables you add follow a generic pattern: `RAYFIN_PUBLIC_FOO` becomes `VITE_RAYFIN_FOO` (Vite), `NEXT_PUBLIC_RAYFIN_FOO` (Next.js), or `FOO` (plain).
 
+`RAYFIN_PUBLIC_FRONTEND_PORT` maps to the port variable each dev server reads (`VITE_PORT` for Vite, `PORT` for Next.js).
+The sample `vite.config.ts` files pin the server to it with `strictPort`, so if the assigned port is already taken the dev server fails fast instead of silently drifting to another port.
+To run on a different port, set `RAYFIN_PUBLIC_FRONTEND_PORT` in `rayfin/.env` (then re-run `rayfin env`); `rayfin up` registers whatever value is assigned in the deployed redirect allow-list.
+
 ## Tooling overrides
 
 These variables configure CLI and extension behavior.

package/assets/docs/cli/index.md

@@ -32,7 +32,7 @@ For the full walkthrough, see the [CLI Quickstart](./quickstart.md) or the [Buil
 | Command | Description |
 | --- | --- |
 | `npm install --save-dev @microsoft/rayfin-cli` | Install the Rayfin CLI as a dev dependency. Not needed if you scaffolded with `npm create @microsoft/rayfin@latest`. |
-| `npm create @microsoft/rayfin <name>` | Scaffold a new project from a template. Use `-t, --template <name>` to skip the interactive prompt or `--list-templates` to see available templates. |
+| `npm create @microsoft/rayfin <name>` | Scaffold a new project from a template. See [Project templates](./templates.md) for choosing a built-in template, scaffolding from a git URL, registering your own template sources, and authoring templates. |
 | `npx rayfin init [directory]` | Initialize a new Rayfin project interactively. Prompts for project name, services (Auth, Data), and auth methods. Creates the `rayfin/` directory with starter files. |
 | `npx rayfin init ai-files install` | Install or refresh the [agent context files](./ai-files.md) (`AGENTS.md`, `.mcp.json`, `.agents/skills/rayfin/SKILL.md`) so coding agents know how to work with your project. Idempotent; auto-runs as part of the scaffold pipeline. |
 | `npx rayfin init ai-files status` | Print the current state of each agent file. Add `--json` for machine-readable output. |

package/assets/docs/cli/quickstart.md

@@ -20,7 +20,7 @@ The project name is a **positional argument** — not a flag.
 Provide a valid directory name like `my-app`, or use `.` to scaffold into the current directory.
 
 - The CLI prompts for a template and database dialect interactively.
-- Use `-t, --template <name>` to skip the template prompt (run `--list-templates` to see options).
+- See [Project templates](./templates.md) for skipping the prompt with `-t, --template`, scaffolding from a git URL, or authoring your own templates.
 - Expected result: `✔ Project created`.
 
 ## Add Rayfin to an existing project

package/assets/docs/cli/templates.md

@@ -0,0 +1,391 @@
+---
+sidebar_position: 3
+---
+
+# Project templates
+
+Templates let Rayfin builders scaffold a project from a known starting point: a built-in starter, a local directory, a git repository your team maintains, or a registered third-party source.
+
+This page covers using templates and authoring your own.
+
+## Where templates come from
+
+Every `npm create @microsoft/rayfin@latest` or `npx rayfin init` invocation can pull from any of these sources:
+
+- **Built-in templates** ship inside `@microsoft/rayfin-cli` and work offline.
+- **Local template directories** let you test or reuse a template on disk.
+- **External git repositories** are cloned on demand from any HTTPS, SSH, or `git@` URL.
+- **Template registries** are YAML files that name git URLs you (or your team) want to surface alongside the built-ins.
+
+External and local template sources are discovered through `rayfin-template.yml` manifests inside the selected source directory.
+Built-in templates are packaged with the CLI and appear in `--list-templates` automatically.
+
+## List available templates
+
+Use `--list-templates` to see every template the CLI can scaffold from in your current directory:
+
+```bash
+npx rayfin init --list-templates
+```
+
+The output is a JSON document on stdout, suitable for piping to a script or AI agent.
+The shape is versioned by `schemaVersion`:
+
+```json
+{
+  "schemaVersion": 1,
+  "bundled": [
+    {
+      "name": "todoapp",
+      "displayName": "Basic Todo App",
+      "description": "End-to-end Fabric-authenticated todo CRUD with a Rayfin data model and per-user row-level security",
+      "source": "built-in"
+    }
+  ],
+  "registry": [
+    {
+      "name": "team-templates",
+      "displayName": "Team Templates",
+      "description": "Our team's starter collection",
+      "url": "https://github.com/example-org/rayfin-templates.git",
+      "ref": "v1.2.0",
+      "path": "catalogs/official",
+      "source": "C:\\Users\\you\\.rayfin\\template-registries.yml"
+    }
+  ]
+}
+```
+
+If any registry file fails to load or contains conflicts, a `warnings` array is appended to the output.
+The list does **not** include arbitrary git URLs — it shows only built-ins plus what is registered through `template-registries.yml` files.
+Template names in examples can change over time; run `--list-templates` for the current copy/paste-ready names.
+
+## Scaffold from a built-in template
+
+The default flow prompts you to pick a template interactively:
+
+```bash
+npm create @microsoft/rayfin@latest my-app
+```
+
+To skip the prompt, pass `-t`/`--template <name>` using one of the names from `--list-templates`:
+
+```bash
+npm create @microsoft/rayfin@latest my-app -- --template todoapp
+```
+
+## Scaffold from an external git repository
+
+Pass any git URL to `-t`/`--template`:
+
+```bash
+npx rayfin init my-app -t https://github.com/example-org/my-template.git
+```
+
+Supported URL formats are HTTPS, SSH, `git@host:org/repo.git`, and `file://`.
+The CLI does a shallow clone into a temp directory, scaffolds, then deletes the clone.
+
+To pin to a specific branch, tag, or commit, append `#<ref>` to the URL:
+
+```bash
+npx rayfin init my-app -t https://github.com/example-org/my-template.git#v1.2.0
+npx rayfin init my-app -t https://github.com/example-org/my-template.git#main
+```
+
+Use a branch name, tag name, or **full** 40-character commit SHA.
+Abbreviated SHAs are rejected because `git clone --branch` would treat them ambiguously.
+For repeated use, register the repo in a `template-registries.yml` so the `ref` is kept in configuration (see [Add a template registry](#add-a-template-registry)) — then `-t <registry-name>` clones the pinned ref automatically.
+
+## Scaffold from a local template directory
+
+Pass a relative or absolute path to `-t`/`--template` when the template is already on disk:
+
+```bash
+npx rayfin init my-app -t ./my-template
+```
+
+Local templates use the same `rayfin-template.yml` file format as git-backed templates for top-level entries.
+
+> **Bare names resolve as template names, not paths.**
+> Use `./`, `../`, or an absolute path when pointing at a local directory:
+>
+> POSIX shells:
+>
+> ```bash
+> npx rayfin init my-app -t ./my-templates       # local relative path
+> npx rayfin init my-app -t ../shared/templates  # parent directory
+> npx rayfin init my-app -t /opt/templates/web   # POSIX absolute
+> ```
+>
+> PowerShell:
+>
+> ```powershell
+> npx rayfin init my-app -t C:\templates\web     # Windows absolute
+> ```
+>
+> A bare value like `-t my-templates` is treated as a template name and looked up against the built-ins and registries.
+
+### Authentication for private repositories
+
+The CLI uses your existing git credentials — SSH keys, Git Credential Manager, GitHub CLI auth, or whatever your environment already provides.
+No credentials are stored or managed by Rayfin.
+
+Interactive credential prompts are disabled, so a misconfigured environment fails fast instead of hanging.
+For GitHub repos, run `gh auth setup-git` to wire credentials through Git Credential Manager.
+
+### Multi-template repositories
+
+A single repository can publish multiple templates via the `entries` array in its `rayfin-template.yml` manifest (see [Author a template](#author-a-template)).
+
+When you scaffold from a multi-template source interactively, the CLI shows a picker.
+For non-interactive flows, pass `--template-name` with the entry's `name` or `path`:
+
+```bash
+npx rayfin init my-app \
+  -t https://github.com/example-org/templates.git \
+  --template-name api-service \
+  --yes
+```
+
+`--template-name` requires `--template`/`-t` pointing at a multi-template source — passing it on its own is an error.
+The value must match one of the source's entry `name` or `path` values; against a built-in template name it has no effect.
+
+## Add a template registry
+
+A registry is a YAML file that lists template repositories you want to surface in `--list-templates` and the interactive picker.
+Edit a `template-registries.yml` file at one of these locations:
+
+| Tier | Path | When to use |
+| --- | --- | --- |
+| **User-global** | `~/.rayfin/template-registries.yml` | Templates you use across many projects on this machine |
+| **Project-local** | `<projectDir>/.rayfin/template-registries.yml` | Templates pinned to a specific project (commit alongside the repo) |
+
+Both files are optional — the CLI also loads a bundled registry that ships with `@microsoft/rayfin-cli` itself.
+The bundled registry that ships with current CLI releases may be empty.
+Some templates the CLI ships with are protected and can't be overridden by a user or project entry that reuses their `name`; the rest can (see [Conflict handling](#conflict-handling) below).
+
+> **Manage registries by hand-editing the YAML files.** There is no CLI command to add or remove registry entries.
+
+### Registry file format
+
+```yaml
+registries:
+  - name: team-templates
+    displayName: Team Templates
+    description: Our team's reusable starters
+    url: https://github.com/example-org/rayfin-templates.git
+    ref: v1.2.0
+    path: catalogs/official
+```
+
+Each entry supports the following fields:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `name` | Yes | Unique identifier for this entry |
+| `url` | Yes | Git URL of the template repository (HTTPS, SSH, `git@`, or `file://`) |
+| `displayName` | No | Human-readable label (defaults to `name`) |
+| `description` | No | Short description shown in pickers and `--list-templates` |
+| `ref` | No | Git tag, branch, or full commit SHA to pin to (defaults to the repository's default branch) |
+| `path` | No | Subdirectory inside the repo where the manifest lives |
+| `templateName` | No | For a multi-template repo, the entry `name` or `path` to pre-select so consumers skip the picker |
+
+### Conflict handling
+
+The CLI loads registries in tier order (bundled → user-global → project-local).
+The first occurrence of any `name` wins; later tiers with the same name are skipped and listed under `warnings` in `--list-templates` output.
+A few templates the CLI ships with are protected: a user or project entry that reuses their `name` is ignored and gets a dedicated warning.
+Other name conflicts still resolve by tier order; rename one of the conflicting entries to resolve.
+
+## Author a template
+
+A template is a directory with a `rayfin-template.yml` manifest at its root.
+Template files are copied into the target directory, then Rayfin applies a small fixed set of scaffold transforms.
+If your template includes `package.json`, Rayfin rewrites its `name` field to the generated project slug.
+If `package.json` is not valid JSON, Rayfin leaves it as-is.
+If your template includes `README.md`, Rayfin replaces the supported placeholders listed below.
+Other file contents are not templated.
+`__projectName__` placeholders in **filenames** are replaced with the user's project name.
+
+The user's project name comes from the `[directory]` positional (`npm create @microsoft/rayfin@latest my-app` → `my-app`) unless they pass `--project-name` to override.
+
+### Minimal template
+
+```text
+my-template/
+├── rayfin-template.yml
+└── template/
+    ├── package.json
+    ├── README.md
+    └── src/
+        └── __projectName__.config.ts
+```
+
+`rayfin-template.yml`:
+
+```yaml
+apiVersion: v1
+metadata:
+  name: my-starter
+  displayName: My Starter
+  description: A starter template for Rayfin projects
+entries:
+  - name: my-starter
+    path: ./template
+```
+
+When scaffolded into `my-app/`, the file `src/__projectName__.config.ts` is written as `src/my-app.config.ts`.
+
+### Publish and share an external template repository
+
+Once your template is working, share it as a git repository so your team (or anyone else) can scaffold from it.
+
+#### 1. Initialize a git repo for the template
+
+From your template directory:
+
+```bash
+git init
+git add .
+git commit -m "Initial template"
+git remote add origin https://github.com/example-org/my-template.git
+git push -u origin main
+```
+
+#### 2. Tag a release
+
+Don't ask consumers to scaffold from the moving `main` branch — pin to a tag so their scaffolds are reproducible:
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+Bump the tag whenever you ship a meaningful change to the template.
+
+#### 3. Share the URL
+
+The simplest path is to hand consumers the git URL. They scaffold with:
+
+```bash
+npx rayfin init my-app -t https://github.com/example-org/my-template.git#v1.0.0
+```
+
+#### 4. (Optional) Surface it through a registry
+
+If you want the template to appear in `rayfin init --list-templates` and the interactive picker — without consumers having to remember the URL — add it to a `template-registries.yml` file (see [Add a template registry](#add-a-template-registry)).
+
+A team-shared `.rayfin/template-registries.yml` committed to the project root, or a personal `~/.rayfin/template-registries.yml`, both work:
+
+```yaml
+registries:
+  - name: my-starter
+    displayName: My Starter
+    description: Our team's Rayfin starter
+    url: https://github.com/example-org/my-template.git
+    ref: v1.0.0
+```
+
+After that, consumers scaffold by name:
+
+```bash
+npx rayfin init my-app -t my-starter
+```
+
+When you ship a new tag, update the `ref` and (ideally) commit the registry change so everyone on the team picks it up.
+
+### Try it locally before publishing
+
+Test your template against a local path before pushing or tagging:
+
+```bash
+npx rayfin init test-output -t ./my-template --yes
+```
+
+### Manifest reference
+
+```yaml
+apiVersion: v1            # required, must be 'v1'
+metadata:
+  name: my-collection     # required, identifier for the manifest
+  displayName: My Collection
+  description: Optional description
+  version: 1.2.0           # accepted, currently informational only
+  tags: [todo, auth]       # accepted, currently informational only
+entries:                   # required, at least one entry
+  - name: api-service     # template entry: scaffolds files from path
+    path: ./api-service
+    description: REST API with Rayfin data layer
+```
+
+`metadata.displayName` and `metadata.description` are shown when scaffolding from this template.
+`metadata.version` and `metadata.tags` are accepted by the manifest schema but are not surfaced in the CLI today.
+Entry-level `description` is shown in the local multi-template picker.
+For git-backed nested navigation, group descriptions are shown; template entry descriptions are not.
+
+### Single-entry vs multi-entry manifests
+
+A single-entry manifest auto-selects with no picker:
+
+```yaml
+entries:
+  - name: my-starter
+    path: .
+```
+
+A multi-entry manifest shows an interactive picker (or requires `--template-name` for non-interactive flows):
+
+```yaml
+entries:
+  - name: api-service
+    path: ./templates/api-service
+  - name: fullstack
+    path: ./templates/fullstack
+```
+
+For local template directories, keep entries at the top level of `entries`.
+Grouped nested navigation is available for git-backed template sources.
+
+### Group entries for nested navigation
+
+Use `group` entries to organize larger collections.
+Groups can nest, and the picker walks users through the hierarchy:
+
+```yaml
+entries:
+  - group:
+      name: starters
+      displayName: Starter Apps
+      entries:
+        - name: hello-world
+          path: ./starters/hello-world
+        - name: todo-app
+          path: ./starters/todo-app
+  - name: standalone-app
+    path: ./standalone-app
+```
+
+### What's currently supported
+
+Templates are intentionally minimal:
+
+- Most file contents are copied as-is.
+- `README.md` supports `{{PROJECT_NAME}}`, `{{PROJECT_NAME_KEBAB}}`, and `{{PROJECT_NAME_PASCAL}}` placeholders.
+- `package.json` `name` is set to the generated project slug.
+- The only filename placeholder is `__projectName__`, replaced with the user's project name and with path separators sanitized.
+- Files matching `rayfin-template.yml`, `.git`, `node_modules`, `.DS_Store`, and `Thumbs.db` are skipped during scaffolding.
+- Symlinks are not followed.
+- After scaffolding, the CLI installs its own agent files (`mcpServers.rayfin` inside `.mcp.json`, `.agents/skills/rayfin/`) into the project. You can ship `.mcp.json` with your own MCP servers, but do not include a `mcpServers.rayfin` key because the CLI manages that key. You can also ship an `AGENTS.md`; it's a one-time install and the CLI won't overwrite a template-provided one.
+
+## Gotchas
+
+- `--list-templates` lists built-in and registered templates only — arbitrary git URLs you pass with `-t` are not in the list.
+- The CLI clones a single ref shallowly. Tools that depend on git history or other branches won't have them at scaffold time.
+- Private repositories rely on ambient git credentials. Interactive prompts are disabled, so missing credentials produce an immediate auth error.
+- Non-interactive scaffolding from a multi-entry source fails unless `--template-name` is provided. The error message lists the available names.
+- Bare values passed to `-t` resolve as template names. Use `./`, `../`, or an absolute path for local directories.
+
+## Related
+
+- [CLI Quickstart](./quickstart.md) — common scaffolding workflows
+- [Environment variables](./environment-variables.md) — runtime configuration after scaffolding

package/assets/docs/data/graphql.md

@@ -36,7 +36,7 @@ Some older examples may show `client.data.gql.<Entity>`.
 
 ### Read multiple records
 
-Here is an example to read all the records and order by a column.
+Here is an example to read records and order by a column.
 
 ```typescript
 const notes = await this.rayfinClient.data.Note.select([
@@ -61,6 +61,11 @@ const notes = await this.rayfinClient.data.Note.select([
 return this.sortWithPinnedFirst(notes);
 ```
 
+> **`.execute()` returns a single page (100 records by default).**
+> The Data API caps a single response at its default page size (100 records).
+> `.first(n)` raises the page size, but `.execute()` still returns only that one page and does **not** signal whether more records exist - so a list longer than the page is silently truncated.
+> If your entity can grow beyond a single page (or you need a guaranteed-complete result set), use [pagination](#paginate-large-lists) instead of `.execute()`.
+
 ### Filter records
 
 Use `where` to filter results.
@@ -78,7 +83,16 @@ const pinnedNotes = await this.rayfinClient.data.Note.select([
 
 ### Paginate Large Lists
 
-Use cursor pagination for large lists.
+Because `.execute()` returns only a single page (100 records by default) and gives no indication that more exist, use cursor pagination whenever a query can return more than one page.
+Pagination uses `.first(n)` to set the page size and `.executePaginated()` to return one page plus the cursor metadata needed to fetch the next one.
+
+**When to paginate vs. when `.execute()` is fine:**
+
+- Use `.execute()` only for queries you know are bounded under one page (for example a `.where(...)` filter that can match at most a handful of rows, or a small lookup table).
+- Use pagination for any unbounded or growing list - a user's notes, an order history, a product catalog. When in doubt, paginate.
+- If you are building a UI list and aren't sure how large it will get, ask the user whether they want infinite scroll / a "load more" button (page-at-a-time) or the complete set up front (loop until `hasNextPage` is `false`, shown below).
+
+**Fetch a single page:**
 
 ```typescript
 const page = await this.rayfinClient.data.Note.select([
@@ -90,11 +104,29 @@ const page = await this.rayfinClient.data.Note.select([
   .first(25)
   .executePaginated();
 
-const items = page.items;
-const cursor = page.endCursor;
-const hasNextPage = page.hasNextPage;
+const items = page.items; // up to 25 records
+const cursor = page.endCursor; // pass to .after(cursor) for the next page
+const hasNextPage = page.hasNextPage; // true if more records remain
 ```
 
+**Fetch the next page** by passing the previous `endCursor` to `.after()`:
+
+```typescript
+const nextPage = await this.rayfinClient.data.Note.select(['id', 'title', 'createdAt'])
+  .orderBy({ createdAt: 'desc' })
+  .first(25)
+  .after(cursor)
+  .executePaginated();
+```
+
+**Fetch every record** by repeating the call in a loop, passing each page's `endCursor` to `.after()`, until `hasNextPage` is `false`.
+Keep the `.select()`, `.where()`, and `.orderBy()` clauses identical across pages - a stable sort order is required for the cursor to advance correctly.
+
+> **`.first(n)` is bounded by DAB's maximum page size (100,000).**
+> Rayfin returns a single default page of 100 records when a query omits `.first(n)`.
+> For large result sets, the recommended pattern is to page through results with `.after()` rather than requesting everything in one large `.first(n)`.
+> `.first(-1)` requests an unbounded page (all matching records), which DAB still caps at the maximum - so it works only when the full result set fits under that limit.
+
 ### Fetch a Single Record
 
 Here is an example to fetch a single record.
@@ -198,6 +230,8 @@ await this.rayfinClient.data.Note.delete({ id });
 
 ## Limitations and Workarounds
 
+- `.execute()` returns only a single page (100 records by default) and does not signal whether more records exist, so lists longer than one page are silently truncated.
+Use `.first(n)` with `.executePaginated()` and `.after(endCursor)` to page through the full result set.
 - `count()` is not implemented today; select the identifiers you need and use `results.length` or a custom aggregate.
 - `totalCount` appears on the `PagedResult` type but DAB does not populate it in paginated queries.
 

package/assets/docs/data/validation.md

@@ -7,6 +7,10 @@ sidebar_position: 4
 Rayfin can generate a [Standard Schema](https://standardschema.dev) validator directly from your decorated entity classes.
 This lets you validate form input on the client without adding a separate validation library like Zod or Yup.
 
+> **Note:** Rayfin entities use TC39 Stage 3 decorators, so any build tooling that compiles your client code must target **ES2022** (or later).
+> If you see `Expression expected` errors on `@entity()` (or other decorators) when calling `toStandardSchema` or `getFieldConstraints`, your bundler is compiling to an older target.
+> For Vite, set `target: 'es2022'` in your `vite.config.ts` — see [Vite configuration](../getting-started/project-structure.md#vite-configuration) — and use the default `@vitejs/plugin-react` (esbuild) plugin, since `@vitejs/plugin-react-swc` does not support these decorators regardless of the `target` setting.
+
 ## Build a validator from an entity
 
 Use `toStandardSchema` to create a validator from any `@entity()` class.

package/assets/docs/deprecations.md

@@ -0,0 +1,41 @@
+---
+sidebar_position: 75
+---
+
+# Deprecation Warnings
+
+Rayfin may emit deprecation warnings when your application uses an API or option that will change in a future release.
+Warnings are printed with `console.warn` and include a stable code such as `[RAYFIN_DEP_USE_PROXY]` so you can search for the affected usage.
+
+## Silence warnings in application code
+
+Use `setDeprecationsSilenced(true)` when you have reviewed the warnings and want to hide them for a specific environment.
+Import the setting from `@microsoft/rayfin-client` and call it early in application startup before creating Rayfin clients or using deprecated APIs.
+
+```ts
+import { setDeprecationsSilenced } from '@microsoft/rayfin-client';
+
+setDeprecationsSilenced(true);
+```
+
+You can call `setDeprecationsSilenced(false)` to enable warnings again.
+Use `isDeprecationSilenced()` when you need to check the current setting.
+
+```ts
+import { isDeprecationSilenced } from '@microsoft/rayfin-client';
+
+console.log(isDeprecationSilenced());
+```
+
+## Silence warnings in Node.js
+
+For Node.js scripts, tests, or server-side tools, set `RAYFIN_NO_DEPRECATION` to `1` or `true`.
+
+```bash
+RAYFIN_NO_DEPRECATION=1 npm run dev
+```
+
+## Browser apps
+
+Browser environments do not provide the Node.js environment variable that Rayfin checks.
+Use the programmatic toggle in browser apps, and call it during startup before code paths that could emit deprecation warnings.

package/assets/docs/getting-started/project-structure.md

@@ -273,6 +273,9 @@ export default defineConfig({
 
 > **Tip:** Templates created with `npm create @microsoft/rayfin@latest` already include these settings.
 > If you are integrating Rayfin into an existing Vite project, add the three `target` entries shown above.
+>
+> **Note:** Use the default `@vitejs/plugin-react` plugin (esbuild-based).
+> `@vitejs/plugin-react-swc` only supports legacy/experimental decorators and fails to parse Rayfin's TC39 decorators with an `Expression expected` error — regardless of the `target` setting.
 
 ### Environment variables
 

package/assets/docs/index.md

@@ -96,4 +96,5 @@ It can scaffold new projects, launch local infrastructure, sync schema changes,
 - Configure authentication with [Rayfin Auth](./auth/overview.md).
 - Deploy frontends with [Static Content Hosting](./hosting/index.md).
 - Explore CLI capabilities in [CLI Guide](./cli/index.md).
+- Learn how to manage [Deprecation Warnings](./deprecations.md).
 - Review [Known Limitations](./known-limitations.md) for current behaviors and workarounds.

package/assets/docs/known-limitations.md

@@ -18,6 +18,10 @@ Use an explicit join entity with two `@one()` navigations instead.
 Some query limitations are imposed by Data API Builder.
 See [Data known limitations](./data/index.md#known-limitations).
 
+- Collection queries return only one page unless the client pages through them.
+The default page size is 100 records and the maximum page size is 100,000 records.
+Use `.first(n)` with `.executePaginated()` and `.after(endCursor)` for lists that can exceed one page.
+
 ## Relationships
 
 - Rayfin auto-generates foreign key columns when you define `@one()` or `@many()` navigation decorators.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rayfin-guide",
-  "version": "1.33.2",
+  "version": "1.34.0-alpha.1148",
   "description": "Cross-cutting Builder guides for the Rayfin platform — discovered by `@microsoft/rayfin-docs` via the `rayfinDocs` package.json field convention.",
   "type": "module",
   "files": [