@microsoft/rayfin-guide 1.36.0-alpha.1601 → 1.36.0-alpha.1663

package/assets/docs/app-backend/deploy.md

@@ -62,6 +62,30 @@ npx rayfin up
 
 If you are not signed in, the CLI launches an interactive login flow automatically.
 
+### Choose a unique Fabric item name
+
+By default, `rayfin up` uses the project ID from `rayfin.yml` as the Fabric item name.
+Pass `--item-name` to deploy a template under a different name without editing its configuration:
+
+```bash
+npx rayfin up --item-name my-team-todo-app
+```
+
+The override changes only the Fabric item display name.
+Runtime settings and service configuration continue to come from `rayfin.yml`.
+Rayfin records the effective item name and item ID in `rayfin/.deployments.json`, so later deployments continue targeting the same item.
+
+For an agent or CI pipeline, provide explicit workspace targeting and structured output:
+
+```bash
+npx rayfin up \
+  --item-name my-team-todo-app \
+  --workspace-id <workspace-guid> \
+  --output json
+```
+
+Do not pass `--yes` unless reusing an existing same-named item is intentional.
+
 ### What `rayfin up` does
 
 The command performs these steps in order:
@@ -91,6 +115,7 @@ For frontend frameworks, the CLI also runs `rayfin env` to emit a framework-spec
   "deployments": {
     "myworkspace": {
       "fabricItemId": "7db00cb9-f630-4ecf-8fc9-942e60af5d78",
+      "itemName": "my-team-todo-app",
       "fabricApiUrl": "https://...",
       "fabricWorkspaceId": "8b17cf64-3c12-46ac-a572-192732c32641",
       "fabricTenantId": "...",
@@ -113,13 +138,13 @@ VITE_RAYFIN_PUBLISHABLE_KEY=pk-nua-EHihY2jz71V65YB4
 VITE_FABRIC_PORTAL_URL=https://dxt.fabric.microsoft.com/
 ```
 
-| Variable | Description |
-| --- | --- |
-| `VITE_FABRIC_ITEM_ID` | The Fabric item ID for this deployment. |
-| `VITE_RAYFIN_API_URL` | Full URL to the deployed Rayfin backend API. |
-| `VITE_FABRIC_WORKSPACE_ID` | The Fabric workspace ID containing the deployment. |
+| Variable                      | Description                                                   |
+| ----------------------------- | ------------------------------------------------------------- |
+| `VITE_FABRIC_ITEM_ID`         | The Fabric item ID for this deployment.                       |
+| `VITE_RAYFIN_API_URL`         | Full URL to the deployed Rayfin backend API.                  |
+| `VITE_FABRIC_WORKSPACE_ID`    | The Fabric workspace ID containing the deployment.            |
 | `VITE_RAYFIN_PUBLISHABLE_KEY` | Publishable key used by the Rayfin client for authentication. |
-| `VITE_FABRIC_PORTAL_URL` | URL to the Fabric portal for managing the deployment. |
+| `VITE_FABRIC_PORTAL_URL`      | URL to the Fabric portal for managing the deployment.         |
 
 ### Authentication after deployment
 
@@ -203,6 +228,27 @@ Add `--json` for machine-readable output:
 npx rayfin up status --json
 ```
 
+To inspect a specific registered deployment instead of the active one, pass its name to `up`:
+
+```bash
+npx rayfin up --env-file staging status
+```
+
+If `RAYFIN_WORKSPACE_ID` is also set, the selected deployment must belong to that workspace.
+
+The management endpoint check verifies authenticated access to the deployed Fabric item and retrieves its publishable key.
+It does not verify that every application route or function is working; validate those with application-specific requests.
+
+In JSON output, `endpointHealth.scope` is `management` and `endpointHealth.url` identifies the endpoint checked.
+`endpointHealth.reachable` records whether an HTTP response arrived, while `httpStatus` and `authenticated` distinguish HTTP success from authentication or authorization failures.
+The top-level `authenticated` field indicates that the CLI acquired a token, not that the endpoint accepted it.
+`endpointHealth.errorCode` is `null` on success, or a stable code such as `http`, `redirect`, `timeout`, `connection-refused`, or `network`; `error` and `hint` provide human-readable details.
+Optional key-retrieval problems appear separately in `endpointHealth.metadata.error`, which is `null` on success or `unexpected-format` for an unsupported response body; the saved deployment key is not changed.
+
+The command exits with `0` when the management request succeeds, `1` when deployment configuration is missing or another command error occurs, or `2` when the check fails, cannot authenticate, or is cancelled.
+HTTP errors, timeouts, and connection failures return `2`, even when the server is reachable.
+An unexpected metadata format alone does not fail a successful management request.
+
 When static content is deployed, the human-readable output includes its public URL:
 
 ```text
@@ -236,11 +282,11 @@ Running `npx rayfin up` again updates the same deployment rather than creating a
 
 For targeted updates, use the subcommands:
 
-| Command | What it updates |
-| --- | --- |
-| `npx rayfin up` | Everything: settings, database, and static content. |
-| `npx rayfin up db apply` | Database schema only. |
-| `npx rayfin up staticapp deploy` | Static content only. |
+| Command                          | What it updates                                     |
+| -------------------------------- | --------------------------------------------------- |
+| `npx rayfin up`                  | Everything: settings, database, and static content. |
+| `npx rayfin up db apply`         | Database schema only.                               |
+| `npx rayfin up staticapp deploy` | Static content only.                                |
 
 ## Troubleshooting
 

package/assets/docs/auth/direct-entra-auth.md

@@ -0,0 +1,139 @@
+---
+sidebar_position: 4
+---
+
+# Direct Entra token sign-in
+
+Use `signInWithEntraToken()` when your application already has a delegated Microsoft Entra access token and wants to call a Rayfin app as that user.
+The helper exchanges it for a Rayfin session on your existing `Auth` instance, so attached SDK clients can make authenticated requests.
+It works in browsers and Node.js without a popup, iframe, handoff code, or redirect.
+
+For a portal signing in an embedded app rather than itself, use the [external embed host](./external-embed-host.md).
+For a browser app that needs Fabric to perform interactive sign-in, use the [Fabric broker flow](./fabric.md).
+
+## Prerequisites
+
+Enable external Entra exchange in the target app's `rayfin/rayfin.yml` and deploy the updated configuration:
+
+```yaml
+services:
+  auth:
+    enabled: true
+    fabric:
+      enabled: true
+      externalEntraExchange: true
+```
+
+The direct exchange must also be available in the target Fabric environment.
+Your Entra token must:
+
+- Be a delegated user token, not an app-only service principal token.
+- Target the Fabric/Power BI audience accepted by the deployment.
+- Include the delegated `Item.Execute.All` scope.
+- Be issued in the target item's owning Fabric tenant.
+
+The user must have Execute permission on that item.
+For production Power BI, request the `https://analysis.windows.net/powerbi/api/Item.Execute.All` scope through your identity library.
+Development environments may use a different resource.
+The SDK does not acquire the Entra token or handle consent.
+
+## Install
+
+For an app using `RayfinClient`:
+
+```bash
+npm install @microsoft/rayfin-client @microsoft/rayfin-auth-provider-fabric
+```
+
+## Sign in an existing client
+
+```typescript
+import { RayfinClient } from '@microsoft/rayfin-client';
+import { signInWithEntraToken } from '@microsoft/rayfin-auth-provider-fabric';
+
+const client = new RayfinClient({
+  baseUrl: rayfinEndpoint,
+  publishableKey,
+});
+
+const session = await signInWithEntraToken(client.auth, {
+  entraToken,
+});
+console.log('Authenticated', session.isAuthenticated);
+```
+
+`rayfinEndpoint` is your trusted HTTPS AppBackend workload API base URL, including the deployment's capacity/workspace/artifact path.
+Use the same backend base URL as your data client, not the app's static-hosting URL or the full token endpoint.
+The helper preserves that path and appends `/api/auth/v1/brokered/token`; there is no separate endpoint option to keep in sync.
+The base must be absolute HTTPS, including for localhost; relative proxy URLs and URLs containing credentials, query strings, or fragments are not accepted.
+`entraToken` is the raw access token string without the `Bearer` scheme prefix.
+Never accept the endpoint from an untrusted caller.
+
+The helper establishes the session on `client.auth`.
+Data and function operations on that client then use the Rayfin access token automatically.
+The returned `OpaqueSession` exposes user and session metadata without exposing tokens.
+Each call explicitly exchanges the supplied token; it does not skip the exchange just because a previous session exists.
+Concurrent direct sign-ins on the same `Auth` instance run in invocation order.
+
+## Node.js and standalone SDK clients
+
+You can construct `Auth` and `ApiClient` directly without `RayfinClient`:
+
+```bash
+npm install @microsoft/rayfin-auth @microsoft/rayfin-lib @microsoft/rayfin-auth-provider-fabric
+```
+
+```typescript
+import { Auth } from '@microsoft/rayfin-auth';
+import { ApiClient } from '@microsoft/rayfin-lib';
+import { signInWithEntraToken } from '@microsoft/rayfin-auth-provider-fabric';
+
+const apiClient = new ApiClient({
+  baseUrl: rayfinEndpoint,
+  publishableKey,
+});
+const auth = new Auth(apiClient, { storage: false });
+auth.attachToClient(apiClient);
+
+try {
+  const session = await signInWithEntraToken(auth, { entraToken });
+  console.log('Authenticated', session.isAuthenticated);
+  // Use data or other SDK clients configured with apiClient here.
+} finally {
+  auth.destroy();
+}
+```
+
+Neither the import nor this direct sign-in requires `window`, `document`, or `localStorage`.
+`storage: false` keeps the Rayfin session in memory.
+Use separate instances per user in server applications; do not share mutable user sessions across requests from different users.
+Call `auth.destroy()` when the instance is no longer needed to release its timers and listeners.
+`RayfinServerClient` uses an access-token configuration instead of exposing `auth`, so it is not passed directly to this helper.
+
+## Session lifetime
+
+Persistence follows your `Auth` configuration.
+The SDK does not persist the supplied Entra token in the Rayfin session.
+Subsequent refresh uses the Rayfin refresh token through the ordinary auth flow rather than repeating the external exchange.
+If the session can no longer refresh, obtain another Entra token and explicitly sign in again.
+
+## Errors and browser considerations
+
+The helper rejects with `AuthError` rather than returning a previous session as a successful sign-in.
+On failure, an existing unexpired session remains in memory; successful sign-in replaces it without revoking the previous server session.
+Do not publish authenticated UI or perform actions for a newly selected account until its sign-in succeeds.
+
+| Error code | Meaning |
+| --- | --- |
+| `INVALID_REQUEST` | Invalid local token or endpoint configuration. |
+| `EXCHANGE_NOT_ENABLED` | External Entra exchange is disabled for the project. |
+| `AUTH_FAILED` | The Entra token was rejected; check audience, tenant, scope, and expiry. |
+| `INSUFFICIENT_PERMISSIONS` | The user lacks Execute permission on the item. |
+| `NOT_AVAILABLE` | The endpoint is unavailable in the target environment or the URL is wrong. |
+| `TOKEN_EXCHANGE_FAILED` | A network or other HTTP failure prevented the exchange. |
+| `INVALID_TOKEN_RESPONSE` | The service returned an invalid token response. |
+
+The exchange does not follow redirects or automatically retry session issuance.
+Errors do not include the Entra token or raw server response.
+In browsers, the service must allow your origin and authorization header through its CORS policy.
+The direct helper does not require a user gesture, but your identity library may require one when obtaining the Entra token interactively.

package/assets/docs/auth/external-embed-host.md

@@ -0,0 +1,131 @@
+---
+sidebar_position: 3
+---
+
+# External embed host
+
+The external embed host lets a **third-party portal** embed a Rayfin app in an iframe and sign the user in with the portal's own Microsoft Entra identity.
+Use it when your app is hosted outside the Fabric Portal — a standalone web app, an internal tool, or any page that already holds a delegated Entra token — and you want to broker authentication for an embedded Rayfin app without a popup or redirect.
+
+This is the parent-page counterpart to [Fabric brokered auth](./fabric.md).
+Fabric auth signs a Rayfin app in when Fabric hosts it; the external embed host signs it in when *your* page hosts it.
+
+The parent page holds a delegated Entra token and answers the embedded app's handoff request.
+The embedded app never sees the token — it receives only a single-use handoff code that it exchanges for a Rayfin session.
+
+## When to use it
+
+Use `@microsoft/rayfin-embed-host` when **all** of these are true:
+
+- Your page embeds a Rayfin app in an iframe.
+- Your page is not the Fabric Portal, so the in-Fabric embed host is unavailable.
+- Your page can obtain a delegated Entra access token for the signed-in user.
+
+If your app runs inside the Fabric Portal iframe, use [Fabric brokered auth](./fabric.md) instead — you do not need this package.
+
+## How it works
+
+1. Your page calls `createEmbedHost()` and then mounts the Rayfin app in an iframe.
+2. The embedded app calls `initEmbeddedAuth()` on startup and posts a one-shot readiness signal to the parent window.
+3. The host checks the iframe's origin against `allowedOrigins` and replies with an acknowledgement, classifying the scenario as an external embed.
+4. The embedded app signs out, then sends a correlated handoff request carrying its brokered-authorize endpoint URL, its Fabric artifact id, the return origin, and a PKCE challenge.
+5. The host validates the return origin against `allowedOrigins`, calls `getAccessToken()` to obtain your delegated Entra token, and posts it to the app's `brokered/authorize/external` endpoint.
+6. The endpoint returns a single-use handoff code, which the host sends back to the iframe in the correlated response.
+7. The embedded app exchanges the handoff code for a Rayfin session — the user is signed in with no popup, redirect, or user click.
+
+The readiness signal is sent **once** with no retry.
+Register the host before you mount the iframe so the listener is live when the signal arrives.
+
+The external embed scenario is detected from this acknowledgement alone — the embedded Rayfin app needs no special query flag (such as `fabricEmbedded`) to enter external embed mode.
+The embedded app must await `initEmbeddedAuth()` before restoring a stored user or rendering authenticated content.
+Do not skip this call when `auth.getSession()` already reports an authenticated session: that session may belong to a different user than the parent portal's current user.
+
+If no host acknowledges the readiness signal, the embedded app falls back to its normal Fabric login waterfall, so a page that never calls `createEmbedHost()` is unaffected.
+
+## Install
+
+```bash
+npm install @microsoft/rayfin-embed-host
+```
+
+## Register the host before mounting the iframe
+
+Call `createEmbedHost()` before the Rayfin iframe loads.
+The embedded app emits its readiness signal once, immediately on startup, and there is no retry — if the listener is not yet registered, the handshake is missed and the app falls back to its normal login flow.
+
+```typescript
+import { createEmbedHost } from '@microsoft/rayfin-embed-host';
+
+// Register BEFORE mounting the Rayfin iframe.
+const host = createEmbedHost({
+  allowedOrigins: ['https://my-rayfin-app.example.com'],
+  getAccessToken: () => acquireDelegatedEntraToken(),
+});
+
+// Now mount the iframe pointing at the embedded Rayfin app.
+const iframe = document.createElement('iframe');
+iframe.src = 'https://my-rayfin-app.example.com';
+document.querySelector('#app-embed')?.append(iframe);
+
+// When the embed is torn down:
+host.dispose();
+```
+
+## Options
+
+`createEmbedHost()` takes an `EmbedHostOptions` object.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `allowedOrigins` | `string[]` | Origins of the embedded Rayfin app(s) this host brokers for. Set it to your app's URL origin(s), for example `https://my-rayfin-app.example.com`. The same list gates both the iframe that sends the handshake and the return origin the handoff code is bound to. |
+| `getAccessToken` | `() => string \| Promise<string>` | Yields your page's delegated Entra access token. Invoked once per handoff request; the returned token is attached only to the outbound authorization call and is never cached across requests. |
+
+## Providing the access token
+
+`getAccessToken` is your integration point with your page's identity stack.
+Return the delegated Entra access token for the currently signed-in user — for example, from MSAL's `acquireTokenSilent`, a server-side session endpoint, or whatever token cache your portal already uses.
+
+```typescript
+const host = createEmbedHost({
+  allowedOrigins: ['https://my-rayfin-app.example.com'],
+  getAccessToken: async () => {
+    const result = await msalInstance.acquireTokenSilent({
+      scopes: ['<your-api-scope>'],
+      account: msalInstance.getActiveAccount()!,
+    });
+    return result.accessToken;
+  },
+});
+```
+
+The host calls `getAccessToken()` fresh for every handoff request, so returning a short-lived token is fine — you do not need to cache one yourself.
+
+## Cleanup
+
+`createEmbedHost()` registers a `message` listener on the parent window.
+Call `dispose()` when you remove the iframe (for example, on route change or component unmount) to remove the listener and stop brokering handoffs.
+`dispose()` is idempotent.
+
+```typescript
+host.dispose();
+```
+
+## Security
+
+- **Single origin allowlist** — `allowedOrigins` gates both the browser-attested `event.origin` of the iframe that posts the handshake and handoff request, and the `returnOrigin` the handoff code is bound to.
+  Messages from any other origin are ignored, and a request naming a return origin outside the list is rejected before any network call.
+- **Token never leaves the parent** — The delegated Entra token is attached only to the outbound `brokered/authorize/external` call.
+  It is never sent over the `postMessage` bridge and never returned to the iframe.
+- **PKCE S256** — The embedded app generates the PKCE challenge; the handoff code is bound to it and is single-use.
+- **Correlated responses** — Each handoff response is matched to its request by a correlation id, so a response is only delivered to the request that asked for it.
+
+## Troubleshooting
+
+- **The app keeps its stored session without signing out or calling the external endpoint** — Check the embedded app's startup ordering.
+  Call and await `initEmbeddedAuth()` before checking for a stored user; importing the provider package alone does not start authentication.
+- **The app falls back to a popup or normal Fabric login** — The readiness signal was missed.
+  Confirm `createEmbedHost()` runs before the iframe is mounted, and that the iframe's origin is listed in `allowedOrigins`.
+- **Handoff request rejected before any network call** — The request's return origin is not in `allowedOrigins`.
+  Add the embedded app's exact origin (scheme, host, and port) to the list.
+- **Authorization call fails** — Verify `getAccessToken()` returns a valid delegated Entra token with the scope your app's `brokered/authorize/external` endpoint expects.
+- **Nothing happens after mounting the iframe** — Confirm the embedded Rayfin app is built with an external-Entra-enabled auth provider (see [Fabric brokered auth](./fabric.md) for the iframe side).

package/assets/docs/auth/fabric.md

@@ -7,12 +7,18 @@ sidebar_position: 2
 Fabric authentication lets users sign in to your Rayfin application with their existing Microsoft Entra identity through the Fabric Portal.
 No separate login form is needed — users authenticate once in Fabric and your app inherits that session automatically.
 
-The SDK supports two modes:
+The SDK supports three modes:
 
 - **Popup flow** — your app opens the Fabric Portal in a new browser tab, the user authenticates, and the tab closes automatically.
 - **Embedded flow** — your app runs inside a Fabric iframe and inherits the session via `postMessage` with no popup, redirect, or user interaction.
+- **Direct token flow** — your browser or Node.js app supplies an existing delegated Entra token and establishes a Rayfin session without a browser broker.
+  See [Direct Entra token sign-in](./direct-entra-auth.md).
 
-Both flows are secured with PKCE S256, `postMessage` origin validation, and state nonces.
+The popup and embedded flows use PKCE S256, `postMessage` origin validation, and state nonces.
+The direct flow uses an HTTPS token exchange with delegated-token validation and item-level Execute permission checks.
+
+> **Embedding outside Fabric?** If your app runs inside an iframe on your own third-party portal rather than the Fabric Portal, the portal brokers sign-in with its own Entra token via the parent-page [external embed host](./external-embed-host.md).
+> On startup the embedded app posts a one-shot readiness signal and briefly waits for the parent to acknowledge it; if no external embed host answers, the app falls back to the standard Fabric login waterfall described below with no added user-visible delay.
 
 ## How it works
 
@@ -103,7 +109,9 @@ async function handleSignIn() {
 ### Embedded flow: automatic authentication on startup
 
 Call `initEmbeddedAuth()` once at app startup (for example, in a React `useEffect` or initialization routine).
-It is safe to call on every page load — it returns `null` immediately when not in embedded mode.
+Await it before restoring a stored user or rendering authenticated content, even when a persisted session exists.
+It is safe to call on every page load: standalone pages return `null` immediately, while framed pages briefly wait for an external embed acknowledgement before choosing the login path.
+Keep session-change observers from publishing a stored user while initialization is pending.
 
 ```typescript
 import { RayfinClient } from '@microsoft/rayfin-client';
@@ -130,7 +138,7 @@ if (session) {
 
 Import `@microsoft/rayfin-auth-provider-fabric` statically in your app entry module rather than only via dynamic `import()`.
 The package captures the `?fabricEmbedded=true` URL flag into `sessionStorage` as a side effect at module load, and that must happen on the initial page load before any client-side navigation strips the query string (for example, a post-logout redirect to `/login`).
-Apps that resume from a stored refresh token never enter the embedded auth path on first load, so a dynamic-only import would miss the URL flag and fall back to the popup on the next sign-in.
+Do not condition the startup call on the absence of a stored session; that bypasses the SDK's identity check and external embed handshake.
 
 ### Detecting embedded mode
 
@@ -262,7 +270,7 @@ Most apps should use `ensureSignedInWithFabric` instead.
 
 ## Security
 
-- **PKCE S256** — Every flow generates a cryptographic code verifier and challenge to prevent authorization code interception.
+- **PKCE S256** — The popup and embedded flows generate a cryptographic code verifier and challenge to prevent authorization code interception.
 - **State nonce** — A random nonce ties the postMessage response to the originating flow, preventing CSRF.
 - **In-closure code verifier** — The PKCE `code_verifier` is held in memory (closure) and never persisted to localStorage.
 - **Origin validation** — The SDK validates `event.origin` on incoming messages against `fabricPortalUrl`.

package/assets/docs/auth/index.md

@@ -26,8 +26,14 @@ Rayfin supports multiple authentication methods that you can enable independentl
 - **Magic link** — Passwordless sign-in via email links.
 - **Fabric brokered auth** — Single sign-on through the Microsoft Fabric Portal using the user's Entra identity.
   See [Fabric Brokered Auth](./fabric.md) for setup and usage.
+- **Direct Entra token sign-in** — Exchange an existing delegated Entra token for a Rayfin session from a browser or Node.js app.
+  See [Direct Entra token sign-in](./direct-entra-auth.md).
+- **External embed host** — Broker sign-in for a Rayfin app embedded in your own third-party portal, using the portal's Entra token.
+  See [External embed host](./external-embed-host.md).
 
 ## Next steps
 
 - [How to configure auth](./overview.md)
 - [Fabric brokered auth](./fabric.md)
+- [Direct Entra token sign-in](./direct-entra-auth.md)
+- [External embed host](./external-embed-host.md)

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

@@ -8,6 +8,8 @@ sidebar_position: 2
 npx rayfin connector add --type <type> --workspace-id <ws-id> --item-id <item-id> [--name <name>] [--operations <ops>]
 ```
 
+> **`kusto` authoring is held in this release**, so `connector add --type kusto` refuses before writing anything. Kusto examples below describe the authoring path for when it ships. See [Connectors](./index.md) for what a project that already declares Kusto can still do.
+
 `connector add` declares a connector in `rayfin/rayfin.yml` and scaffolds its supporting files.
 
 The CLI verifies the Fabric item, derives a connector `name` from the item's display name (override with `--name`), writes the entry to `rayfin.yml`, and scaffolds `rayfin/connectors/<name>/schema.ts`. For Category A connectors it also runs schema discovery and writes `rayfin/connectors/<name>/metadata.json` so a subset of entities can be generated later.

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 5
 ---
 
 # Category A — GraphQL entity connectors

package/assets/docs/{experimental/cli → cli}/connectors/category-b-function-bridge.md

@@ -1,10 +1,14 @@
 ---
-sidebar_position: 7
+sidebar_position: 6
 ---
 
 # Category B — function-bridge connectors
 
-Reference for `kusto` (Fabric KQL Database) and `fabric-semanticmodel` (Power BI semantic model).
+Reference for `fabric-semanticmodel` (Power BI semantic model) and the experimental `kusto` (the **Eventhouse** connector — a Fabric Eventhouse KQL Database).
+Eventhouse is the Fabric product name; `kusto` is the type id you pass to `--type`, and KQL is its query language.
+
+> **`kusto` authoring is held in this release**, so `connector add --type kusto` refuses and search omits KQL databases. Everything below about `kusto` stays accurate for a project that **already declares** one — which still validates, deploys and invokes — and describes the authoring path for when it ships. Only `fabric-semanticmodel` can be added today. See [Connectors](./index.md).
+
 A Category B connector is a named-operation surface backed by a small, platform-owned function (UDF).
 The Builder never writes or sees the function code.
 
@@ -17,8 +21,8 @@ For the entity-generating types (`fabric-sqlanalytics`, `fabric-warehouse`, `fab
 
 | Type | Operations | Query language | Auth |
 | --- | --- | --- | --- |
-| `kusto` | `executeQuery`, `executeCommand` | KQL | `delegated` only |
 | `fabric-semanticmodel` | `executeQuery` | DAX | `delegated` only |
+| `kusto` (**experimental**) | `executeQuery`, `executeCommand` | KQL | `delegated` only |
 
 Both are pinned to an adapter version (`version: '1'` today).
 Delegated authentication runs every call as the signed-in user through the on-behalf-of flow.
@@ -78,7 +82,7 @@ export const connectorConfig = {
 } as const satisfies ConnectorConfig;
 ```
 
-### Kusto bakes cluster routing into the generated file
+### The Eventhouse scaffold bakes cluster routing into the generated file
 
 `connector add --type kusto` resolves the KQL Database's cluster query endpoint and database name from `(workspaceId, itemId)` at add time and writes both into the generated `connectorConfig`:
 
@@ -100,11 +104,11 @@ Three names appear here and nowhere else:
 - `databaseName` — the resolved KQL database name.
 - `KustoConnectorConfig` — the Kusto-specific config type these two keys satisfy, exported from `@microsoft/rayfin-connector-kusto` rather than `@microsoft/rayfin-connectors`.
 
-These keys live only in the file the Kusto scaffold writes.
+These keys live only in the file the Eventhouse scaffold writes.
 They are **not** part of the shared `rayfin.yml` schema — never write a cluster URI or database name into `rayfin.yml`, and never send either value from app code.
 If the resolved values look wrong, re-add the connector rather than editing the generated file; the values come from Fabric, not from anything you can fix by hand.
 
-The Kusto scaffold imports both its marker and `KustoConnectorConfig` from `@microsoft/rayfin-connector-kusto`, so it does not import `@microsoft/rayfin-connectors` at all.
+The Eventhouse scaffold imports both its marker and `KustoConnectorConfig` from `@microsoft/rayfin-connector-kusto`, so it does not import `@microsoft/rayfin-connectors` at all.
 
 ## Install the packages the generated file imports
 
@@ -113,7 +117,7 @@ The Kusto scaffold imports both its marker and `KustoConnectorConfig` from `@mic
 ```bash
 # Shape only. Use the version connector add printed, not this one.
 
-# kusto — marker and config type both come from this one package
+# kusto (experimental) — marker and config type both come from this one package
 npm install @microsoft/rayfin-connector-kusto@1.35.0-alpha
 
 # fabric-semanticmodel
@@ -136,7 +140,7 @@ This is not optional: the runtime is what injects the generated routing and deco
 Key the runtime map by the same connector name, and call the factory once per connector:
 
 ```ts
-import { ConnectorsRayfinClient } from '@microsoft/rayfin-client/experimental';
+import { ConnectorsRayfinClient } from '@microsoft/rayfin-client';
 import { kusto } from '@microsoft/rayfin-connector-kusto';
 import { fabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
 import {
@@ -174,11 +178,11 @@ const client = new ConnectorsRayfinClient<
 );
 ```
 
-`ConnectorsRayfinClient` is experimental — import it only from the `@microsoft/rayfin-client/experimental` subpath, never the stable `@microsoft/rayfin-client` entry.
+`ConnectorsRayfinClient` is stable — import it from the main `@microsoft/rayfin-client` entry.
 
 The connector key must be identical in four places: the `name` in `rayfin.yml`, the property in `AppConnectorsSchema`, the property in the `connectors` option, and the property in the runtime map.
 
-## Calling a Kusto connector
+## Calling an Eventhouse connector
 
 Correlation ids are not part of the response body — the connector function relays the Kusto bytes untouched — so generate the `clientRequestId` yourself and pass the same value to both `executeQuery` and `toQueryResult`:
 
@@ -208,6 +212,28 @@ Successful results contain `tables` plus the `clientRequestId` you passed in (em
 Each table contains named typed `columns` and row-major `rows`.
 Error results contain `error.message` and an optional `error.code`.
 
+### Building queries safely
+
+`executeQuery` takes its KQL in `query` and `executeCommand` takes its command in `command`; neither operation binds parameters — `ExecuteQueryInput` exposes only `query` and `clientRequestId`, and `ExecuteCommandInput` only `command` and `clientRequestId`. Every user value you place in that text runs as KQL, so treat all user input as unsafe and never interpolate it raw.
+
+- **Identifiers** (table, column, function names): map the user's choice through a fixed allow-list to a known-good constant. Never build an identifier from user text.
+- **Values**: serialize each as a typed KQL literal. Validate numbers (for example with `Number.isFinite`), parse datetimes to ISO 8601 and wrap them in `todatetime(...)`, and for strings escape `\` and `"` and reject control characters. This repo ships no KQL encoder; generic SQL or JSON escaping does not make KQL safe.
+
+```ts
+const TABLES = { events: 'Events', logs: 'Logs' } as const;
+const table = TABLES[userTable];
+if (!table) throw new Error('unknown table');
+
+// Typed KQL string literal: escape backslash and double-quote, reject control chars.
+function kqlString(value: string): string {
+  if (/[\u0000-\u001F]/.test(value)) throw new Error('control character in value');
+  return '"' + value.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+// kqlString('contoso "42"')  ->  "contoso \"42\""
+
+const query = `${table} | where DeviceId == ${kqlString(userDeviceId)} | take 200`;
+```
+
 ### Management commands
 
 `executeCommand` runs a Kusto management (control) command — the command text starts with a leading dot.
@@ -240,10 +266,10 @@ Run `rayfin docs search "resultSetRowCountLimit"` for version-locked details, si
 `rayfin connector invoke <name> <operation>` is the loop for Category B.
 See [`connector invoke`](./invoke.md) for payload input, transports, token handling, and the output contract.
 
-- `connector inspect` supports `fabric-semanticmodel` but **not** `kusto` — a `kusto` connector errors with `Unsupported connector type: kusto`.
+- `connector inspect` supports `fabric-semanticmodel` but **not** experimental `kusto` — a `kusto` connector errors with `Unsupported connector type: kusto`.
   There is no ad-hoc query path for Kusto connectors today.
 - `connector invoke` on `fabric-semanticmodel` calls Fabric/Power BI directly under the developer's identity, so it works with or without `rayfin up`.
-  Every other type, `kusto` included, POSTs to the deployed item and requires a prior `rayfin up`.
+  Every other type, including experimental `kusto`, POSTs to the deployed item and requires a prior `rayfin up`.
 - `connector invoke` on `fabric-semanticmodel` returns an already-normalized result, because that connector normalizes inside its `invoke` middleware.
   Do not apply `toQueryResult` to it again.
 - A resolved `connector invoke` call is not automatically a success.

package/assets/docs/cli/connectors/eventhouse.md

@@ -0,0 +1,21 @@
+---
+sidebar_position: 9
+---
+
+# Eventhouse (`kusto`) usage guide
+
+> **Moved.** This usage guide now ships **inside the connector package**,
+> version-locked to the `kusto` connector the Builder actually installed — so the
+> streaming model, KQL shaping, safe query construction, and result handling can
+> never drift from the CLI. It is fetched on demand with `packageVersion`
+> provenance.
+>
+> Read it from `@microsoft/rayfin-connector-kusto`:
+>
+> - MCP: `search_docs` / `discover_packages`
+> - CLI: `rayfin docs search "<term>"` (module `rayfin-connector-kusto`)
+> - Source: `@microsoft/rayfin-connector-kusto/assets/docs/`
+>
+> The shared function-bridge mechanics — `connector add`, the generated
+> `rayfin.yml` and `schema.ts`, and the `client.connectors.<name>` call — stay in
+> the [Category B guide](./category-b-function-bridge.md).

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

@@ -6,25 +6,13 @@ sidebar_position: 6
 
 Connectors let a Rayfin app read from — and, for some types, write to — Microsoft Fabric data sources: warehouses, SQL databases, Lakehouse SQL analytics endpoints, semantic models, and KQL databases.
 
-## Prerequisite — enabling the `connector` command group
+The `connector` command group is always available.
 
-Connectors are behind a feature flag, so `rayfin connector ...` is only registered when the project opts in. Prefer the declarative setting in `rayfin/rayfin.yml`:
+**Lakehouse scope:** `fabric-sqlanalytics` connects only to a Lakehouse's SQL analytics endpoint.
+It can read SQL-visible tables and views, but it cannot directly open files from the Lakehouse `Files` area, such as PDFs or images.
+This connector is read-only; the Warehouse and SQL Database connectors also support write operations.
 
-```yaml
-services:
-  connectors:
-    enabled: true
-```
-
-With that setting present the command group is available from the very first `connector add`, with nothing to configure in the shell — the path generated apps and agents should use.
-
-The flag also activates automatically once `rayfin.yml` has a `connectors:` block (written by `connector add`), and it can still be turned on for a single command with the environment variable:
-
-```bash
-RAYFIN_FEATURE_FLAGS=connectors npx rayfin connector search --help
-```
-
-Without any of the three the commands do not exist and the CLI reports an unknown command.
+> **`kusto` authoring is held in this release.** `connector types` and `connector search` omit it, and `connector add --type kusto` refuses it. A project that **already declares** a Kusto connector is unaffected: it still validates, deploys through `rayfin up`, and answers `connector invoke`. Kusto material in these docs describes that preserved runtime contract and the authoring path for when it ships.
 
 Each command has its own reference page:
 
@@ -36,7 +24,8 @@ Each command has its own reference page:
 Each category has its own contract page — read the one that matches your connector type, not both:
 
 - [Category A — GraphQL entity connectors](./category-a-entities.md) — now **package-owned**; the full reference (entity generation, `@role` policies, the aggregate schema, and the per-dialect read/write matrix) ships in `@microsoft/rayfin-connector-fabric-graphql` (`rayfin docs search` / `search_docs`).
-- [Category B — function-bridge connectors](./category-b-function-bridge.md) — the `kusto` and `fabric-semanticmodel` contract, including the Kusto cluster routing baked into the generated `schema.ts`.
+- [Category B — function-bridge connectors](./category-b-function-bridge.md) — the `fabric-semanticmodel` and experimental `kusto` contract, including the Kusto cluster routing baked into the generated `schema.ts`.
+- [Eventhouse (`kusto`) usage guide](./eventhouse.md) — the experimental `kusto` supplement, now **package-owned**; when to reach for the type, its streaming model, shaping KQL, safe query construction, and reading results all ship in `@microsoft/rayfin-connector-kusto` (`rayfin docs search` / `search_docs`).
 
 A typical loop is search → add → inspect (Category A) or search → add → invoke (Category B).
 
@@ -46,13 +35,13 @@ The commands available to a connector, and the code you write against it, depend
 
 |                                       | 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 |
+| **Types**                             | `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`, `fabric-graphql`                                                                                                | `fabric-semanticmodel`; `kusto` (**experimental**)      |
+| **App surface**                       | Generated entity files with typed CRUD through the data client                                                                                                                   | Named operations carrying raw queries                  |
 | **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 inspect`**               | Supported                                                                                                                                                                        | `fabric-semanticmodel` only — experimental `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/{experimental/cli → cli}/connectors/invoke.md

@@ -32,6 +32,10 @@ Two transports, chosen by connector type:
 - **`fabric-semanticmodel`** — the CLI calls Fabric/Power BI **directly under the developer's own identity**, so this works whether or not `npx rayfin up` has been run. It requires `workspaceId` **and** `itemId` under the connector's `config:` block; without both, it fails up front rather than falling through to the deployed transport. The Power BI scope and audience are derived from the configured Fabric API base URL, so an INT ring mints an INT-audience token.
 - **Every other type, including `kusto`** — POSTs to the deployed item at `<remote-endpoint>/__private/connectors/<name>/invoke`, so it requires a prior `npx rayfin up`.
 
+> `kusto` authoring is held in this release, but invocation is deliberately preserved: a project that already declares a Kusto connector can still invoke it. Only `connector add`, `types` and `search` withdraw the type. See [Connectors](./index.md).
+
+`--transport deployed` overrides the type-based choice and forces the deployed route. That route authenticates the **app**, not the developer, so it needs an app-session token in `RAYFIN_TOKEN`; `npx rayfin login` cannot mint one.
+
 ## Token handling (semantic model path)
 
 `npx rayfin login` only consents to the Fabric scope, not the Power BI scope this path needs. Consequences:
@@ -50,6 +54,34 @@ What `output` holds depends on the connector. `fabric-semanticmodel` normalises
 
 A resolved call is **not** automatically a success, and the failure signal depends on the same distinction. A connector that normalises reports Power BI failures — expired token, missing Build permission, throttling — as `{status: 'error', error, requestId}`, where `error` carries `category`, `message`, and optional `code` and `details`. A connector that returns the raw envelope reports failure as `status: 'Failed'` instead. The CLI reads both, converts either into a non-zero exit, and surfaces the service-supplied request id for tracing.
 
+In JSON mode, failures keep the top-level `error` as a human-readable **string**, with `recovery` and `requestId` when available.
+Connector failures additionally expose a `connectorError` object containing the available `message`, `category`, `code`, and `details` fields.
+Scalar values are stringified and structured values are JSON-encoded, so a numeric `code` or object `details` survives; empty and unavailable fields are omitted, and unrelated CLI failures do not acquire connector metadata.
+The remediation hint stays on the top-level `recovery` string only, so `connectorError` never carries a CLI-fabricated hint.
+This applies to both direct and deployed invocation, including DAX errors returned inside an HTTP 200 Arrow stream.
+The semantic-model SDK also preserves the Arrow error code and description as `error.code` and `error.details` in its normalized result.
+Existing engine-markup cleanup still applies to normalized messages and details.
+
+For example, an invalid DAX query exits with code `1` and can emit:
+
+```json
+{
+  "status": "error",
+  "error": "Connector invoke failed (DAX_ERROR): Column not found",
+  "recovery": "The service ran the operation and reported an error. Fix the query and retry.",
+  "requestId": "service-request-id",
+  "connectorError": {
+    "message": "Column not found",
+    "category": "query",
+    "code": "DAX_ERROR",
+    "details": "The column Foo does not exist"
+  }
+}
+```
+
+Read `connectorError.code` and `connectorError.details` rather than parsing the display string.
+Service diagnostics may contain query or model content; review them before sharing or recording them in logs.
+
 ## Examples
 
 ```bash

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

@@ -8,7 +8,9 @@ sidebar_position: 1
 npx rayfin connector search [query] [--workspace-id <id> --type <types> | --all-workspaces --type <types>] [--limit <n>] [--json]
 ```
 
-`connector search` finds Fabric data sources — warehouses, SQL databases, Lakehouses, semantic models, and KQL databases — that the signed-in identity can add as connectors, before you know exact workspace or item IDs.
+> **`kusto` authoring is held in this release**, so search does not return KQL databases and `--type kusto` is not accepted. Search exists to feed `connector add`, which would refuse the type — surfacing a source the Builder could not then attach. See [Connectors](./index.md).
+
+`connector search` finds Fabric data sources — warehouses, SQL databases, Lakehouses, and semantic models — that the signed-in identity can add as connectors, before you know exact workspace or item IDs.
 
 Use it to find candidates for [`connector add`](./add.md). It never touches app data itself.
 
@@ -38,7 +40,7 @@ Only one of `--workspace-id` and `--all-workspaces` may be given. Outside a Rayf
 
 Duplicate-looking entries — for example a SQL Database and its SQL-analytics-endpoint twin sharing a workspace and display name — are grouped visually next to each other in interactive and plain output only. They are never deduplicated, and `--json` always returns the canonical, ungrouped order.
 
-The SQL-endpoint-permissions note ("Schema discovery for SQL-based connectors requires SQL endpoint permissions") only prints when at least one result is a SQL-dialect connector type — never for a semantic-model-only or Kusto-only result set.
+The SQL-endpoint-permissions note ("Schema discovery for SQL-based connectors requires SQL endpoint permissions") only prints when at least one result is a SQL-dialect connector type — never for a semantic-model-only result set. (It would also not print for a Kusto-only set, once Kusto authoring ships.)
 
 ## Examples
 

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

@@ -189,7 +189,7 @@ These variables are read from the shell environment and are never written to fil
 | `RAYFIN_WORKSPACE_ID` | Fabric workspace ID for non-interactive setup. Used with `RAYFIN_TOKEN`. |
 | `RAYFIN_TENANT_ID` | Entra ID tenant used by `rayfin up` for portal URLs and the `ctid` query parameter. Equivalent to the `-t, --tenant <id>` flag (precedence: flag > env var > signed-in tenant). |
 | `RAYFIN_ENCRYPTION_FALLBACK_ENABLED` | Set to `true` to allow plaintext token cache on systems without OS credential storage. Development only. |
-| `RAYFIN_FEATURE_FLAGS` | Comma-separated list of experimental feature names to enable (case-insensitive). Recognized values include `docker-local-dev`, `functions`, and `postgresql`. |
+| `RAYFIN_FEATURE_FLAGS` | Comma-separated list of experimental feature names to enable (case-insensitive). Recognized public values include `docker-local-dev`, `postgresql`, and `storage`. |
 | `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. |
@@ -199,8 +199,8 @@ These variables are read from the shell environment and are never written to fil
 | Flag | Effect |
 | --- | --- |
 | `docker-local-dev` | Allows `rayfin dev --provider docker` and the Docker maintenance commands. Bare `rayfin dev` remains available without this flag and defaults to Fabric. |
-| `functions` | Exposes Functions service prompts during `rayfin init`. |
 | `postgresql` | Adds PostgreSQL as a selectable dialect during `rayfin init` and `rayfin init` with bundled templates. |
+| `storage` | Enables the preview Storage service when declared in `rayfin.yml` or opted in from the shell. |
 
 ## File locations
 

package/assets/docs/cli/index.md

@@ -73,6 +73,20 @@ Functions are server-side user-defined functions (UDFs) that run in the Fabric r
 | `npx rayfin dev functions apply` | Run the local function host with a live typegen watcher and debugger support. See [dev functions apply](./functions/dev-apply.md). |
 | `npx rayfin up functions deploy` | Build, package, and deploy functions to the remote Rayfin item. `rayfin up` runs this automatically. See [up functions deploy](./functions/deploy.md). |
 
+### Connectors
+
+Connectors let a Rayfin app read from — and, for some types, write to — Microsoft Fabric data sources. See [Connectors](./connectors/index.md) for the full guide.
+
+| Command | Description |
+| --- | --- |
+| `npx rayfin connector search [query]` | Discover Fabric sources the signed-in identity can add before you know exact workspace or item IDs. See [connector search](./connectors/search.md). |
+| `npx rayfin connector add --type <type> --workspace-id <ws-id> --item-id <item-id>` | Declare a connector in `rayfin.yml` and scaffold `rayfin/connectors/<name>/`. See [connector add](./connectors/add.md). |
+| `npx rayfin connector inspect` | Explore a connector's underlying source in read-only mode by listing entity names, sampling one entity, or running a `.sql` / `.dax` query file. See [connector inspect](./connectors/inspect.md). |
+| `npx rayfin connector invoke <connector-name> <operation>` | Run a single named operation against a configured connector. See [connector invoke](./connectors/invoke.md). |
+| `npx rayfin connector list` | Print the configured connectors. See [Connectors](./connectors/index.md#where-connector-state-lives). |
+| `npx rayfin connector remove <name>` | Delete both the `rayfin.yml` entry and the `rayfin/connectors/<name>/` directory. See [Connectors](./connectors/index.md#where-connector-state-lives). |
+| `npx rayfin up connector apply [--name <name>]` | Re-apply DAB config only. See [Deploying connectors](./connectors/index.md#deploying-connectors). |
+
 ### Secrets
 
 Secrets are encrypted values stored on your deployed Rayfin item and read at runtime — for example by [functions](./functions/index.md) via `ctx.getSecret`. See [Managing Secrets](./secrets.md) for the full guide.
@@ -112,3 +126,25 @@ To disable telemetry, set the following environment variable:
 ```bash
 export RAYFIN_TELEMETRY_OPTOUT=1
 ```
+
+## Diagnostic logs
+
+`npx rayfin up` and workflow-based `npx rayfin dev` record detailed diagnostics under `~/.rayfin/logs/` even when `--verbose` is absent, including when using `--json` or `--output json`.
+After a failure, open the file identified by `Diagnostic log:` to inspect the original invocation without rerunning it.
+JSON failures include the same path in the `diagnosticLog` field of the single result object.
+`dev` JSON failures also include a `hint` with recovery guidance, including provider/configuration preflight errors and unexpected failures.
+
+Adding `--verbose` also mirrors diagnostic records to stderr while `up` or `dev` runs.
+The CLI rejects combining `--verbose` with `--json` or `--output json`; detailed diagnostics are still recorded in the log file without `--verbose`.
+This capability applies to workflow-based `up` and `dev` sessions, not standalone subcommands or Docker maintenance flags such as `dev --stop`.
+
+`dev` preserves normal frontend and Functions terminal output and flushes its log after cleanup on Ctrl-C, runtime failure, or normal completion.
+Piped runtime and build output is captured with a 1 MiB limit per stream.
+Interactive runtimes that inherit the terminal keep their keyboard and TTY behavior; their console output is not captured, and the log records that limitation alongside lifecycle events.
+
+Logs stay on your machine and are independent of telemetry opt-out.
+The log directory is shared across projects on your machine, so the retention limits below apply across all projects using it.
+Known credential patterns are redacted, and build output is bounded, but review logs before sharing them because project tools can emit their own content.
+Retention is best-effort: logs older than 14 days are pruned, with targets of 20 invocation files and 100 MiB total; each file is limited to 10 MiB.
+If `RAYFIN_CONFIG_DIR` is set, logs use its `logs/` subdirectory instead.
+An unavailable or full log directory does not change the command result.

package/assets/docs/cli/templates.md

@@ -20,6 +20,12 @@ Every `npm create @microsoft/rayfin@latest` or `npx rayfin init` invocation can
 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.
 
+> **Universal App is available as the built-in `blankapp` template.**
+> The visible `blankapp` entry appears in `--list-templates` and is available in the CLI and VS Code.
+> Its canonical `universal-app` name remains hidden to avoid a duplicate listing, but plugin automation can still select it explicitly with `--template universal-app`.
+> Both names scaffold the same committed workspace template.
+> This does not change support for ordinary local directories, git repositories, or registered templates.
+
 ## List available templates
 
 Use `--list-templates` to see every template the CLI can scaffold from in your current directory:

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

@@ -24,6 +24,92 @@ your-project/
 └── README.md
 ```
 
+## Universal App workspace
+
+Universal Apps generated by the Rayfin Copilot plugin use an npm workspace while preserving the same root workflow:
+
+```text
+your-universal-app/
+├── package.json
+├── tsconfig.base.json
+├── tsconfig.json
+├── rayfin/
+│   └── rayfin.yml
+└── packages/
+    ├── frontend/
+    │   ├── src/
+    │   ├── package.json
+    │   └── vite.config.ts
+    ├── data/
+    │   ├── src/index.ts
+    │   └── package.json
+    └── shared/
+        ├── src/index.ts
+        └── package.json
+```
+
+The workspace root owns the application identity, npm workspace declaration, orchestration scripts, applied capability-pack record, TypeScript project references, and `rayfin/rayfin.yml`.
+It coordinates the packages but does not own application runtime code.
+
+| Package | Stable name | Ownership |
+| --- | --- | --- |
+| `packages/frontend` | `@rayfin-app/frontend` | React, Vite, Fabric authentication, browser UI, and static output |
+| `packages/data` | `@rayfin-app/data` | Rayfin entity registration and data schema exports |
+| `packages/shared` | `@rayfin-app/shared` | Isomorphic contracts shared across runtime boundaries |
+| `packages/functions` | `@rayfin-app/functions` | Opt-in trusted server workflows created by the functions capability pack |
+
+Only the generated root package name is personalized.
+The stable member names, cross-package dependency keys, and import specifiers are not renamed.
+
+Use root commands for the complete app workflow:
+
+```bash
+npm run build
+npm run typecheck
+npm run lint
+npm test
+npm run preview
+npm run pack:add -- <pack>
+```
+
+The root build orders shared, data, and frontend work.
+Focused package commands use npm's workspace selector, such as `npm run -w @rayfin-app/frontend test`.
+
+The base workspace does not contain `packages/functions`, and `services.functions.enabled` is `false`.
+Running `npm run pack:add -- functions` creates the stable functions package, enables its service, composes its build into root orchestration, and installs dependencies from the workspace root.
+Capability packs do not use a nested functions lockfile or nested install.
+
+### Universal App service paths
+
+Universal App service paths point to the package that owns each deployable surface:
+
+```yaml
+services:
+  data:
+    enabled: false
+    path: packages/data
+    buildCommand: npm run build
+  staticHosting:
+    enabled: true
+    path: packages/frontend
+    folder: dist
+    buildCommand: npm run build:fabric
+    assetAccess: protected
+  functions:
+    enabled: false
+```
+
+Rayfin resolves each `path` from the application root, then runs that service's `buildCommand` with the service directory as its working directory.
+The static-hosting folder is therefore `packages/frontend/dist`, not a root `dist` directory.
+After the functions pack is applied, functions uses `path: packages/functions` with its package-local `npm run build`.
+
+The Project Rayfin repository keeps this Builder-facing workspace under `samples/universal-app/template`.
+Its parent `samples/universal-app` is only a Rush validation harness that generates an ephemeral target and links that target to repository-local SDK packages.
+The Copilot plugin bundles the inner template only; the harness and generated target are not distributed.
+
+Existing flat Universal Apps remain supported by plugin validation and do not need to adopt this layout.
+This workspace template does not add automatic workspace discovery, a migration command, support for package managers other than npm, or functions by default.
+
 ## Key files
 
 ### rayfin/rayfin.yml
@@ -103,6 +189,8 @@ services:
 | --- | --- | --- | --- |
 | `enabled` | `boolean` | `false` | Enable the data service. |
 | `dialect` | `"mssql"` \| `"postgresql"` | `"mssql"` | Database dialect. Fabric deployments support MSSQL only. |
+| `path` | `string` | Project root | Data project directory relative to the application root. |
+| `buildCommand` | `string` | — | Command run from the resolved data service path before packaging. |
 
 #### `services.auth`
 
@@ -171,9 +259,10 @@ Configure an email provider for magic links, password resets, and email verifica
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
 | `enabled` | `boolean` | `false` | Enable static content hosting. |
+| `path` | `string` | — | Frontend project directory relative to the application root. |
 | `root` | `string` | — | Root directory of the frontend project (relative to the project root). |
-| `folder` | `string` | `"dist"` | Directory containing built static assets (relative to `root`). |
-| `buildCommand` | `string` | — | Shell command to run before packaging (e.g. `npm run build`). |
+| `folder` | `string` | `"dist"` | Directory containing built static assets, relative to `path` or legacy `root`. |
+| `buildCommand` | `string` | — | Shell command run from the resolved static-hosting path before packaging (for example, `npm run build`). |
 | `indexDocument` | `string` | — | Default document served for the root path (e.g. `index.html`). |
 
 > **Tip:** All string values support environment variable interpolation with `${VAR}` and `${VAR:-default}` syntax.

package/package.json

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