@microsoft/rayfin-guide 1.36.0-alpha.1620 → 1.36.0-alpha.1675

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/cli/connectors/index.md

@@ -8,6 +8,10 @@ Connectors let a Rayfin app read from — and, for some types, write to — Micr
 
 The `connector` command group is always available.
 
+**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.
+
 > **`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:

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

@@ -54,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/cli/index.md

@@ -126,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,11 +20,10 @@ 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 distributed by the Rayfin Copilot plugin.**
-> It is a hidden built-in template: it does not appear in `--list-templates`,
-> but it can be selected explicitly with `--template universal-app`.
-> The plugin selects that bundled template and distributes its committed workspace
-> template directly.
+> **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

package/package.json

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