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

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,9 @@ 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`:
-
-```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 +20,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 +31,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:

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.

package/assets/docs/cli/templates.md

@@ -20,6 +20,13 @@ 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.
+> 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.1620",
   "description": "Cross-cutting Builder guides for the Rayfin platform — discovered by `@microsoft/rayfin-docs` via the `rayfinDocs` package.json field convention.",
   "type": "module",
   "files": [