@microsoft/rayfin-guide 1.35.0-alpha.1541 → 1.36.0-alpha.1581

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

@@ -192,6 +192,7 @@ These variables are read from the shell environment and are never written to fil
 | `RAYFIN_FEATURE_FLAGS` | Comma-separated list of experimental feature names to enable (case-insensitive). Recognized values include `docker-local-dev`, `functions`, and `postgresql`. |
 | `RAYFIN_WEBSERVICE_IMAGE_NAME` | **Experimental.** Override the webservice container image used by `rayfin dev --provider docker` and Docker Compose. Defaults to `ghcr.io/microsoft/project-rayfin/webservice:cli-<version>`. |
 | `RAYFIN_APPINSIGHTS_CONNECTION_STRING` | Override the telemetry endpoint for the CLI and VS Code extension. |
+| `RAYFIN_TELEMETRY_ENV` | Override the CLI and `create-rayfin` telemetry environment label. Values are trimmed and lowercased. Known labels include `github-actions`, `azure-pipelines`, `gitlab-ci`, `jenkins`, `codespaces`, `devcontainer`, `local`, and `other`; custom labels may contain 1–64 ASCII letters, digits, hyphens, or underscores. Invalid non-empty values map to `other`, while an empty value uses automatic detection. Do not include identifying or sensitive values. |
 
 ### Recognized `RAYFIN_FEATURE_FLAGS` values
 

package/assets/docs/cli/index.md

@@ -64,20 +64,6 @@ For the full walkthrough, see the [CLI Quickstart](./quickstart.md) or the [Buil
 | `npx rayfin up secrets apply` | Read secrets from `rayfin/.env` file (prefixed with `RAYFIN_SECRET_`) and securely apply them to the remote Rayfin item workload. Validates that secrets are persisted. Use `--env-file <path>` to specify a custom .env file location. |
 | `npx rayfin up staticapp deploy` | Build, package, and deploy static content to the remote Rayfin item. Add `--skip-build` to deploy existing build output without rebuilding. |
 
-### Connectors
-
-Connectors let a Rayfin app read from existing Fabric sources. The `connector` command group is only registered when `RAYFIN_FEATURE_FLAGS` contains `connectors`. See [Connectors](./connectors/index.md) for the full guide.
-
-| Command | Description |
-| --- | --- |
-| `npx rayfin connector search [query]` | Discover Fabric sources you can connect to. See [Searching for sources](./connectors/search.md). |
-| `npx rayfin connector add` | Declare a connector in `rayfin.yml` and run schema discovery. See [Adding a connector](./connectors/add.md). |
-| `npx rayfin connector list` | List the connectors declared in the current project. |
-| `npx rayfin connector remove <name>` | Remove a connector's `rayfin.yml` entry and its `rayfin/connectors/<name>/` directory. |
-| `npx rayfin connector inspect` | Run a read-only sample query against a connector's source. See [Inspecting a source](./connectors/inspect.md). |
-| `npx rayfin connector invoke <name> <operation>` | Run one named operation against a configured connector. See [Invoking an operation](./connectors/invoke.md). |
-| `npx rayfin up connector apply` | Re-apply connector configuration to the remote Rayfin item. |
-
 ## Update the CLI
 
 To get the latest version of the Rayfin CLI and its dependencies:

package/assets/docs/data/overview.md

@@ -54,8 +54,6 @@ If you omit it, the server generates a UUID automatically.
 - Composite or non-`id` primary keys are not supported.
 
 **Scope:** the rules above apply to entities you own under `rayfin/data/`.
-Connector entities under `rayfin/connectors/` model an existing, external Fabric SQL source and follow different rules — the primary key is whatever the source actually declares, of any name and any datatype, including composite keys or no key at all.
-See [Entity generation contract](../cli/connectors/category-a-entities.md#entity-generation-contract) for the connector-path key rules.
 
 ```typescript
 @entity()

package/assets/docs/{cli → experimental/cli}/connectors/category-a-entities.md

@@ -43,8 +43,7 @@ Always narrow YAML first, then add `@role(...)` to entities.
 Example: a `fabric-warehouse` connector with `operations: [read, update]` and an `Order` entity locked to read-only:
 
 ```ts
-import { entity, int, text, decimal, Source } from '@microsoft/rayfin-core/experimental';
-import { role } from '@microsoft/rayfin-core';
+import { entity, int, text, decimal, Source, role } from '@microsoft/rayfin-core';
 
 @role('authenticated', ['read'])
 @entity()
@@ -197,7 +196,6 @@ The map also accepts entity classes, but do not use that form here: it puts the
 **Use the entity's property names, not the database column names.**
 These are the names on the generated class — the same keys that appear in the row type — not the `columnName` values in `metadata.json`.
 For `@uuid({ column: 'ProductID' }) productId!: string`, the entry is `productId`.
-The one exception is a field that declares `graphqlName`, in which case use that name.
 Include every scalar field and leave relationship fields out, since those need nested sub-selections.
 
 **Relationship selects need the class form.**
@@ -585,8 +583,8 @@ Build the import line deterministically:
 
 - Always include `entity` and `Source`.
 - Then append, in this exact order, any decorator names actually used in the file: `boolean`, `date`, `decimal`, `int`, `text`, `uuid`, `one`, `many`. Skip any not used.
-- All from `@microsoft/rayfin-core/experimental`.
-- If any column is server-generated, also add `import type { AutoGenerated } from '@microsoft/rayfin-core/experimental';`.
+- All from `@microsoft/rayfin-core`.
+- If any column is server-generated, also add `import type { AutoGenerated } from '@microsoft/rayfin-core';`.
 - For every relationship target that is a different class, add a sibling import: `import { <SiblingClass> } from './<SiblingClass>.js';`. Sibling imports are alphabetised; self-references get no sibling import.
 - In subset mode, only relationships that survived the subset skip contribute sibling imports.
 
@@ -595,8 +593,8 @@ Build the import line deterministically:
 ```ts
 // @generated — do not edit.
 
-import { entity, uuid, text, int, date, one, many, Source } from '@microsoft/rayfin-core/experimental';
-import type { AutoGenerated } from '@microsoft/rayfin-core/experimental';
+import { entity, uuid, text, int, date, one, many, Source } from '@microsoft/rayfin-core';
+import type { AutoGenerated } from '@microsoft/rayfin-core';
 import { Category } from './Category.js';
 import { OrderItem } from './OrderItem.js';
 
@@ -672,4 +670,4 @@ Absence means "unknown / not exposed", not permission to synthesize keys or rela
 | `Cannot find module '@microsoft/rayfin-connector-fabric-graphql'` | The connector packages were never installed — `connector add` does not add them | Run the pinned `npm install` command `connector add` printed, or rebuild it from `rayfin connector types --json`. |
 | Deployed page is blank with `Uncaught SyntaxError: Invalid or unexpected token`, though build, tests and deploy all passed | `schema.ts` imports or re-exports entity classes as values, so the decorated classes were bundled into the browser build | Switch every entity import and re-export in `schema.ts` to `import type` / `export type`, and give `connectorConfig.entities` column-name arrays instead of classes. |
 | A read throws `SELECTION_REQUIRED` | `connectorConfig.entities` is missing, so there is no default column list | Add the entity's property names, or pass an explicit `select([...])`. |
-| A read returns null or errors on a field that exists in the database | `entities` lists database column names instead of the entity's property names | Use the names declared on the generated class (or `graphqlName` where set), for example `productId`, not `ProductID`. |
+| A read returns null or errors on a field that exists in the database | `entities` lists database column names instead of the entity's property names | Use the names declared on the generated class, for example `productId`, not `ProductID`. |

package/assets/docs/{cli → experimental/cli}/connectors/index.md

@@ -30,7 +30,7 @@ Each command has its own reference page:
 
 - [`connector search`](./search.md) — discover Fabric sources the signed-in identity can add.
 - [`connector add`](./add.md) — declare a connector in `rayfin.yml` and scaffold its files.
-- [`connector inspect`](./inspect.md) — run a single read-only sample query against a source.
+- [`connector inspect`](./inspect.md) — list a source's entity names, or run a single read-only sample query against one.
 - [`connector invoke`](./invoke.md) — run one named operation against a configured connector.
 
 Each category has its own contract page — read the one that matches your connector type, not both:
@@ -44,16 +44,16 @@ A typical loop is search → add → inspect (Category A) or search → add →
 
 The commands available to a connector, and the code you write against it, depend on its category.
 
-|                                       | Category A — GraphQL entity connectors                          | Category B — function-bridge connectors                |
-| ------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------ |
-| **Types**                             | `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase` | `kusto`, `fabric-semanticmodel`                        |
-| **App surface**                       | Generated entity files with typed CRUD through the data client  | A single `executeQuery` operation carrying a raw query |
+|                                       | Category A — GraphQL entity connectors                                                                                                                                           | Category B — function-bridge connectors                |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| **Types**                             | `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`                                                                                                                  | `kusto`, `fabric-semanticmodel`                        |
+| **App surface**                       | Generated entity files with typed CRUD through the data client                                                                                                                   | A single `executeQuery` operation carrying a raw query |
 | **Operations**                        | `read` only for `fabric-sqlanalytics` (Lakehouse SQL endpoints are read-only); `read`, `create`, `update`, `delete` for `fabric-warehouse` and `fabric-sqldatabase` (narrowable) | `executeQuery` only                                    |
-| **Auth**                              | `delegated` or configured per project                           | Must be `delegated`                                    |
-| **Entity files and `@role` policies** | Yes                                                             | No                                                     |
-| **`metadata.json` entities**          | Yes                                                             | No                                                     |
-| **`connector inspect`**               | Supported                                                       | `fabric-semanticmodel` only — `kusto` is not supported |
-| **`connector invoke`**                | Rarely needed                                                   | The main way to exercise the connector                 |
+| **Auth**                              | `delegated` or configured per project                                                                                                                                            | Must be `delegated`                                    |
+| **Entity files and `@role` policies** | Yes                                                                                                                                                                              | No                                                     |
+| **`metadata.json` entities**          | Yes                                                                                                                                                                              | No                                                     |
+| **`connector inspect`**               | Supported                                                                                                                                                                        | `fabric-semanticmodel` only — `kusto` is not supported |
+| **`connector invoke`**                | Rarely needed                                                                                                                                                                    | The main way to exercise the connector                 |
 
 Category B connectors are pinned to an adapter version and expose no GraphQL entities, so there is nothing to generate and no row-level security to author.
 

package/assets/docs/{cli → experimental/cli}/connectors/inspect.md

@@ -5,28 +5,43 @@ sidebar_position: 3
 # connector inspect
 
 ```bash
-npx rayfin connector inspect (--name <name> | <direct-selector-flags>) (--entity <name> | --query <path>) [--rows <n>] [--verbose] [--json]
+npx rayfin connector inspect (--name <name> | <direct-selector-flags>) [--entity <name> | --query <path>] [--rows <n>] [--verbose] [--json]
 ```
 
 `connector inspect` takes no positional arguments — every selector and query mode is a flag.
 
-`connector inspect` runs a single read-only sample query against a connector's underlying source, before you have written any app code. Use it to check a table's real data and shape ahead of entity generation, or to debug a row-level-security or query issue on an already-wired connector. It is a development aid — never use it to power app functionality.
+`connector inspect` explores a connector's underlying source in read-only mode, before you have written any app code. Run it with just a selector to **list the entity/table names** the source exposes; add `--entity` to sample one of them, or `--query` to run a `.sql`/`.dax` file of your own. Use it to check a table's real data and shape ahead of entity generation, or to debug a row-level-security or query issue on an already-wired connector. It is a development aid — never use it to power app functionality.
 
 Supported types: the three Category A SQL types (`fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`) and `fabric-semanticmodel` (DAX). `kusto` is **not** supported today — the command errors with `Unsupported connector type: kusto`.
 
-## Pick exactly one selector and one query mode
+## Pick exactly one selector, and at most one query mode
 
-Two independent choices, each a mutually exclusive pair. Passing zero or both options in a pair fails validation before any network call.
+Two independent choices. The **selector** is a mutually exclusive pair — passing zero or both fails validation before any network call. The **query mode** has three options, and omitting it is a mode of its own rather than an error; only passing `--entity` and `--query` together fails.
 
-| Choice                                          | Option A                                                                                                                      | Option B                                                                                                                                                                                       |
-| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Selector** — which connector or item to query | `--name <name>` — a connector already declared in `rayfin.yml`                                                                | Direct mode — `--workspace-id`/`--workspace <name>` plus `--item-id`/`--item <name>` plus `--type <type>`, or `--url <portal-url>` for a semantic model (auto-extracts workspace and item IDs) |
-| **Query mode**                                  | `--entity <name>` — structured: builds `SELECT TOP (n) * FROM <entity>` (SQL) or `EVALUATE TOPN(n, '<entity>')` (DAX) for you | `--query <path>` — raw: runs the literal `.sql` or `.dax` file verbatim, still capped and validated                                                                                            |
+| Selector — which connector or item to query | Meaning                                                                                                                                                                           |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--name <name>`                             | A connector already declared in `rayfin.yml`.                                                                                                                                     |
+| Direct mode                                 | `--workspace-id`/`--workspace <name>` plus `--item-id`/`--item <name>` plus `--type <type>`, or `--url <portal-url>` for a semantic model (auto-extracts workspace and item IDs). |
 
-All four combinations of `{--name, direct} × {--entity, --query}` are valid.
+| Query mode                     | What it runs                                                                                                       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| _omit both_ — entity listing   | Lists the entity/table names the source exposes, so you have something to pass to `--entity`. This is the default. |
+| `--entity <name>` — structured | Builds `SELECT TOP (n) * FROM <entity>` (SQL) or `EVALUATE TOPN(n, '<entity>')` (DAX) for you.                     |
+| `--query <path>` — raw         | Runs the literal `.sql` or `.dax` file verbatim, still capped and validated.                                       |
+
+All six combinations of `{--name, direct} × {listing, --entity, --query}` are valid.
 
 `--workspace` and `--item` accept display names and are resolved to IDs the same way [`connector add`](./add.md) fuzzy matching works; `--workspace-id` and `--item-id` take literal IDs directly.
 
+## Entity listing
+
+Omitting both `--entity` and `--query` lists the entity names available on the source. This is the starting point when you don't know the names yet — the output is what you feed back into `--entity`, and the command prints a ready-to-run `--entity` suggestion carrying the same selector flags you just used.
+
+- **SQL types** — reads `INFORMATION_SCHEMA.TABLES`, returning `TABLE_SCHEMA` and `TABLE_NAME`.
+- **`fabric-semanticmodel`** — reads `INFO.TABLES()`, returning table names.
+
+Listing honours `--rows` and `--json` like any other mode, and the `--json` envelope reports `queryMode: "entities"`.
+
 ## Entity resolution
 
 Applies to `--entity` mode only.
@@ -37,22 +52,28 @@ Applies to `--entity` mode only.
 
 ## Validation
 
-Applies to both query modes.
+Applies to `--entity` and `--query` modes.
 
 - **SQL** — must start with `SELECT` or `WITH`; must be a single statement (a trailing `;` is fine, an embedded one is not); rejects `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `CREATE`, `ALTER`, `DROP`, `TRUNCATE`, `EXEC`/`EXECUTE`, and `INTO` anywhere outside a string literal.
 - **DAX** — must start with `EVALUATE`.
 - `--query <path>` must resolve to a `.sql` or `.dax` file inside the project root; paths outside it are rejected. The project root is the directory containing `rayfin/rayfin.yml` when one is found. Direct mode (no `--name`) falls back to the current working directory if no `rayfin.yml` exists, so `--query` never requires a Rayfin project.
-- `--rows <n>` caps the sample size — default 10, maximum 100. The result reports `truncated: true` when the source had more rows than the cap.
+- `--rows <n>` caps the sample size — maximum 100. The default is mode-specific: entity listing (neither `--entity` nor `--query`) defaults to **100**, while `--entity` and `--query` sampling default to **10**. The result reports `truncated: true` when the source had more rows than the cap; inspect fetches one row beyond the cap to detect that, then discards it.
 
 ## Examples
 
 ```bash
+# --name selector, no query mode: list the entity names on the source
+npx rayfin connector inspect --name inventory
+
 # --name selector + structured entity mode
 npx rayfin connector inspect --name inventory --entity Order
 
 # --name selector + raw query file
 npx rayfin connector inspect --name inventory --query rayfin/queries/order.sql
 
+# Direct selector, no query mode: list the entity names on the source
+npx rayfin connector inspect --workspace-id <ws-id> --item-id <item-id> --type fabric-warehouse
+
 # Direct selector (literal IDs) + structured entity mode
 npx rayfin connector inspect --workspace-id <ws-id> --item-id <item-id> --type fabric-warehouse --entity Order
 
@@ -63,7 +84,7 @@ npx rayfin connector inspect --workspace "Sales Analytics" --item "Inventory War
 npx rayfin connector inspect --url <fabric-portal-semantic-model-url> --query rayfin/queries/model.dax
 ```
 
-Combine `--workspace-id`, `--item-id`, and `--type` with either `--entity` or `--query` freely — none of the four combinations require `--name` or a `rayfin.yml` entry to exist.
+Combine `--workspace-id`, `--item-id`, and `--type` with entity listing, `--entity`, or `--query` freely — none of the six combinations require `--name` or a `rayfin.yml` entry to exist.
 
 ## Errors
 

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

@@ -78,6 +78,8 @@ services:
   data:
     enabled: true
     dialect: mssql
+  storage:
+    enabled: false
   staticHosting:
     enabled: true
     root: .
@@ -158,6 +160,12 @@ Configure an email provider for magic links, password resets, and email verifica
 | `useStartTls` | `boolean` | `false` | Use STARTTLS for the SMTP connection. |
 | `webPort` | `number` | `1080` | MailDev web UI port (local development only). |
 
+#### `services.storage`
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `false` | Enable the storage service. |
+
 #### `services.staticHosting`
 
 | Field | Type | Default | Description |
@@ -167,6 +175,10 @@ Configure an email provider for magic links, password resets, and email verifica
 | `folder` | `string` | `"dist"` | Directory containing built static assets (relative to `root`). |
 | `buildCommand` | `string` | — | Shell command to run before packaging (e.g. `npm run build`). |
 | `indexDocument` | `string` | — | Default document served for the root path (e.g. `index.html`). |
+| `anonymousAccess` | `boolean` | — | Whether visitors can open the app without signing in. Required when static hosting is enabled. |
+
+`anonymousAccess` has no default.
+See [Static hosting](../hosting/index.md) for the posture table.
 
 > **Tip:** All string values support environment variable interpolation with `${VAR}` and `${VAR:-default}` syntax.
 > Variables are resolved from `rayfin/.env` and the shell environment.

package/assets/docs/hosting/index.md

@@ -37,6 +37,54 @@ services:
 | `root` | No | Project root | Root directory of the frontend project, relative to the project root. |
 | `buildCommand` | No | — | Shell command to run before packaging (for example, `npm run build`). |
 | `indexDocument` | No | — | Default document to serve for directory requests (for example, `index.html`). |
+| `anonymousAccess` | Yes | — | Whether visitors can open the app without signing in. |
+
+### Access posture
+
+`anonymousAccess` selects who can open your deployed app.
+Set `anonymousAccess` explicitly — leaving it out is not the same as setting it to `false`, and once your tenant enforces static-hosting access control a deployment that omits `anonymousAccess` is rejected.
+
+| Posture | `anonymousAccess` | Who can open the app |
+| --- | --- | --- |
+| Signed-in users only | `false` | Visitors must sign in. |
+| Public | `true` | Anyone with the link, no sign-in. |
+
+```yaml
+services:
+  staticHosting:
+    enabled: true
+    folder: dist
+    anonymousAccess: false
+```
+
+`rayfin up` asks you to choose a posture the first time it deploys a project that has not recorded one, then writes your choice to `rayfin.yml` so later deploys never ask again.
+In automation — `--yes`, a non-interactive terminal, or `CI=true` — it never prompts: add `anonymousAccess` to `rayfin.yml` and re-run.
+`anonymousAccess` must be `true` or `false`; a value that is neither, such as an environment variable that did not resolve, is rejected before anything is deployed.
+
+A newly scaffolded project already has `anonymousAccess: false`, so it is private from the moment it exists and deploys without a prompt.
+The prompt exists for projects created before this property did: those apps are being served publicly today, so `rayfin up` asks once and never guesses on your behalf.
+Choosing public does not turn off Rayfin auth — it decides who may load the site, not whether the app can sign users in.
+
+`rayfin up staticapp deploy` does not set an access posture.
+It publishes content only, so the app keeps whatever posture the last full `rayfin up` recorded.
+
+### Declared package versions
+
+Every `rayfin up` records which packages produced the deployment, under `packageVersions` in the runtime settings it uploads:
+
+| Key | When it is sent |
+| --- | --- |
+| `@microsoft/rayfin-cli` | Always, set to the running CLI's version. |
+| `@microsoft/rayfin-auth` | When your frontend package has the auth SDK installed, set to the installed version. |
+
+You do not author this.
+Run `rayfin up --dry-run` to see exactly which versions a deploy would declare, without deploying.
+
+Once your tenant enforces static-hosting access control, a CLI too old to record its version cannot deploy a static-hosted app, and the deployment is rejected with instructions to upgrade:
+
+```bash
+npm install -g @microsoft/rayfin-cli@latest
+```
 
 ### Example with a separate frontend directory
 
@@ -133,7 +181,7 @@ The deploy tool updates the configuration and pushes it to the backend during de
 
 - The compressed ZIP archive must not exceed **100 MB**.
 - The CLI uses maximum compression to minimize upload size.
-- If your build output exceeds the limit, consider excluding large assets from the deployed bundle.
+- If your build output exceeds the limit, consider excluding large assets or using the storage service for binary files.
 
 ## Complete example
 
@@ -182,6 +230,7 @@ If the ZIP exceeds 100 MB:
 
 - Review your build output for unnecessary files (source maps, unoptimized images).
 - Configure your bundler to exclude development artifacts from the production build.
+- Move large binary assets to Rayfin storage instead of bundling them as static content.
 
 ### No remote endpoint configured
 

package/package.json

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