@microsoft/rayfin-guide 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) Microsoft Corporation.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @microsoft/rayfin-guide
+
+Cross-cutting Builder guides for the Rayfin platform.
+
+This package ships markdown only — no code.
+The `@microsoft/rayfin-docs` indexing library discovers it via the `rayfinDocs` field in this package's `package.json` and exposes its content through the same `rayfin docs` CLI commands and MCP tools that surface SDK package docs.
+
+## Usage
+
+Builders can query these guides from a Rayfin project:
+
+```bash
+npx -y @microsoft/rayfin-cli docs list --module guide
+npx -y @microsoft/rayfin-cli docs search 'quickstart' --module guide
+npx -y @microsoft/rayfin-cli docs get --id rayfin-guide:index.md
+```
+
+## Contents
+
+- `assets/docs/index.md` — top-level introduction to the Rayfin platform
+- `assets/docs/quickstart.md` — the canonical Builder quickstart
+
+Additional guide pages can be added under `assets/docs/`.
+
+## Discovery
+
+```typescript
+import { DocsService } from '@microsoft/rayfin-docs';
+
+const docs = new DocsService({
+  discover: { from: process.cwd() },
+});
+const guides = docs.listDocs('guide');
+```

package/assets/docs/index.md

@@ -0,0 +1,52 @@
+---
+symbols: []
+---
+
+# Rayfin platform overview
+
+Rayfin is Microsoft's platform for building data-driven applications
+on Microsoft Fabric. It combines:
+
+- **Code-first data modeling** via TypeScript decorators (the
+  `@microsoft/rayfin-core` package's `@entity()`, `@text()`, `@uuid()`,
+  `@one()`, `@many()`, `@anonymous()`, `@authenticated()`).
+- **DAB-compliant data access** via `@microsoft/rayfin-data` exposing
+  GraphQL clients generated from your decorated entity classes.
+- **Authentication** via `@microsoft/rayfin-auth` with magic-link and
+  Fabric-token flows.
+- **A high-level client entrypoint** (`@microsoft/rayfin-client`) that
+  composes auth + data behind a single configured client.
+- **A scaffolding CLI** (`@microsoft/rayfin-cli`) that generates DAB
+  configuration from your entity classes and bootstraps new projects.
+- **An MCP server** (`@microsoft/rayfin-mcp`) that exposes the docs
+  corpus as `list_docs`, `search_docs`, and `get_doc` tools for AI
+  agents working in Builder projects.
+
+## Where to start
+
+For Builders new to Rayfin, follow the [quickstart](./quickstart.md).
+The quickstart walks through:
+
+1. Scaffolding a new Rayfin project with `npm create rayfin@latest`.
+2. Defining your first entity with the core decorators.
+3. Running the project locally with `rayfin up`.
+4. Querying via the generated GraphQL endpoint.
+
+## Per-package reference
+
+Each Rayfin SDK package ships its own docs at
+`<package>/assets/docs/`. Discoverable via:
+
+```bash
+rayfin docs list --module ts-sdk
+rayfin docs search 'magic link'
+rayfin docs get --id rayfin-auth:index.md
+```
+
+Or, in MCP-host environments, via the `list_docs`, `search_docs`, and
+`get_doc` tools.
+
+## Package discovery
+
+If a package is not installed yet, use `rayfin docs discover '<topic>'`
+to find matching Rayfin packages and install commands.

package/assets/docs/quickstart.md

@@ -0,0 +1,81 @@
+---
+symbols: []
+---
+
+# Quickstart
+
+This quickstart walks you through scaffolding a new Rayfin project,
+defining your first entity, running the project locally, and querying
+via GraphQL.
+
+## Prerequisites
+
+- Node.js 20+
+- A modern terminal (PowerShell, bash, zsh)
+
+## 1. Scaffold a new project
+
+```bash
+npm create rayfin@latest my-app
+cd my-app
+npm install
+```
+
+The scaffold creates a Rayfin project with:
+
+- `rayfin/data/` — your entity classes
+- `rayfin.config.json` — project configuration
+- `package.json` with `rayfin-cli`, `rayfin-core`, `rayfin-data`, and
+  `rayfin-auth` already wired
+
+## 2. Define your first entity
+
+Edit `rayfin/data/Todo.ts`:
+
+```typescript
+import { entity, uuid, text, int, anonymous, authenticated } from '@microsoft/rayfin-core';
+
+@entity()
+@anonymous('read')
+@authenticated('*')
+export class Todo {
+  @uuid() id!: string;
+  @text() title!: string;
+  @int() priority!: number;
+  @text({ optional: true }) notes?: string;
+}
+```
+
+## 3. Run locally
+
+```bash
+rayfin up
+```
+
+This generates a DAB-compliant configuration from your entity classes
+and starts the Data API Builder server on
+[http://localhost:5000](http://localhost:5000).
+
+## 4. Query via GraphQL
+
+Open [http://localhost:5000/graphql](http://localhost:5000/graphql) and try:
+
+```graphql
+query {
+  todos {
+    items {
+      id
+      title
+      priority
+    }
+  }
+}
+```
+
+## Next steps
+
+- [Auth overview](./index.md) — for sign-in flows beyond the
+  built-in `anonymous` role.
+- Per-package reference via `rayfin docs list --module ts-sdk`.
+- Deploy to Fabric: see the `rayfin up staticapp deploy` subcommand
+  (interactive scaffolding through Fabric workspace selection).

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@microsoft/rayfin-guide",
+  "version": "1.1.0",
+  "description": "Cross-cutting Builder guides for the Rayfin platform — discovered by `@microsoft/rayfin-docs` via the `rayfinDocs` package.json field convention.",
+  "type": "module",
+  "files": [
+    "assets/docs",
+    "LICENSE",
+    "README.md"
+  ],
+  "rayfinDocs": {
+    "version": 1,
+    "dir": "assets/docs",
+    "module": "rayfin-guide",
+    "kind": "guide"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com",
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/project-rayfin.git",
+    "directory": "packages/guide"
+  },
+  "license": "MIT"
+}