From 3325b293832b1059f2475a719fdf613fc5c02061 Mon Sep 17 00:00:00 2001 From: sinedied Date: Tue, 30 Jun 2026 16:57:43 +0200 Subject: [PATCH 01/16] feat: add start.md prompt --- content/start.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 content/start.md diff --git a/content/start.md b/content/start.md new file mode 100644 index 0000000..b2c1aff --- /dev/null +++ b/content/start.md @@ -0,0 +1,100 @@ +# Rayfin — New Project Setup + +You're helping a developer create a new Rayfin project. Rayfin is a TypeScript +Backend-as-a-Service: decorate data models to get auto-generated APIs (REST + +GraphQL), typed clients, auth, storage, and a local dev stack. + +**Core rule:** Rayfin's specifics are version-locked per project, so once a project +exists, never answer schema/API/auth/storage/deployment questions from memory: +remembered Rayfin APIs are routinely wrong. Defer to the project's installed skill, +`rayfin docs`, and `rayfin` MCP (Step 4). Keep this bootstrap light on Rayfin +internals. + +**One question at a time:** whenever you need input from the user, ask a single +question and wait for the answer before asking the next. + +## Step 1 — Detect context and ask what they want to build + +First, check the current directory: context signals are enough, even if you can't +open the files. It's already a Rayfin project if it has `rayfin/rayfin.yml` or a +`package.json` with `@microsoft/rayfin-*` deps. Never create a project nested inside +or beside an existing app. + +Then ask what they want to build. Infer whether it targets Microsoft Fabric or should +be self-contained, only clarifying if it's unclear. This guides the template and +later customization. + +## Step 2 — Check prerequisites + +Before running any `npx` command: `node --version` (need 20+) and `git --version`. +Install anything missing first: + +- macOS: `brew install node git` +- Windows: `winget install -e --id OpenJS.NodeJS.LTS Git.Git` +- Linux (Debian/Ubuntu): Node from [nodejs.org/en/download](https://nodejs.org/en/download), then `sudo apt install -y git` + +Don't proceed until `node --version` reports v20+. + +## Step 3 — Get into a project + +Act on the context from Step 1. You're not a TTY, so always pass `-y` to `npx` (bare +`npm create` can mishandle piped stdin and strip flags). + +- **Already in a Rayfin project:** don't scaffold; they may have run this by mistake. + Confirm they mean to work here (else ask for an empty target dir for a new project), + then go to Step 4. +- **Existing non-Rayfin app here:** confirm, then add Rayfin in place with + `npx -y rayfin init` (no template). Then Step 4. +- **Empty directory:** scaffold a new child project. Map the Step 1 answer to a + template, then list the live set and pick the closest fit: + + ```bash + npx -y @microsoft/create-rayfin@latest --list-templates # JSON of gallery templates + ``` + + If unavailable, fall back to these built-in slugs (default `dataapp` for Fabric, or + `todoapp` if self-contained / no Fabric workspace): + + - **`dataapp`** _(default)_: Microsoft Fabric data analytics app. + - **`todoapp`**: full app (auth, entities, frontend); best to learn Rayfin end-to-end. + - **`gettingstartedauth`**: minimal app with auth wired up; add your own data model. + - **`blankapp`**: bare scaffolding (auth + data services, no entities/UI). + + For more options, including user-contributed ones, see the community gallery linked + at the end. + + Prefer a template matching their domain over a blank one. Propose a kebab-case + project name, confirm it, then: + + ```bash + npx -y @microsoft/create-rayfin@latest --project-name --template + ``` + +The scaffolder (or `init`) creates the project, installs dependencies, and writes +agent rules + an MCP config, so don't redo that work. `cd` into the new `/` +child dir (`rayfin init` works in place, so you're already there). If `npx` errors, +Node may be missing; see Step 2. + +## Step 4 — Load the in-project skill, then plan & customize + +Before writing any Rayfin-specific code, hand off to the project's authoritative, +version-locked sources: + +1. Load `.agents/skills/rayfin/SKILL.md` and follow it; if your tooling supports it, + reload tools to bring the `rayfin` MCP online. +2. Look up version-matched APIs via `rayfin docs` and the `rayfin` MCP instead of + guessing. The skill file and `rayfin docs` work as soon as the project exists, so + don't block waiting on the MCP reload. + +Then enter plan mode and outline the first changes for what they described in Step 1: +entities under `rayfin/data/`, views under `src/`, and packages to install. Confirm +with the user before writing code. + +Don't start the backend or frontend; the user runs the app themselves when ready (see +the project's `README.md`). + +## Useful links + +- Docs: +- Scaffolder: +- Community template gallery: From 53b7a378cdc183e153f7b2b3ab358e49bb7939a2 Mon Sep 17 00:00:00 2001 From: sinedied Date: Tue, 30 Jun 2026 16:57:57 +0200 Subject: [PATCH 02/16] docs: add guided setup prompt for coding agents --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index c5cd6b7..427606b 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,16 @@ npm create @microsoft/rayfin@latest This CLI scaffolds a new Rayfin project with everything you need: data models, authentication, APIs, and a ready-to-deploy app. +> [!TIP] +> **Prefer to build with a coding agent?** Hand it the guided setup prompt and +> describe what you want to build: +> +> ```bash +> copilot -i "$(curl -sSfL https://aka.ms/rayfin/start.md)" +> ``` +> +> This loads the [Rayfin starter prompt](docs/START.md): it checks your environment, picks a template, scaffolds the project, and helps you customize. + ### Agent plugin Install the Rayfin getting-started skill through your agent's native marketplace or extension manager: From ca6ac47925f6f2f8c7dae549cf5977e80d5dc272 Mon Sep 17 00:00:00 2001 From: sinedied Date: Tue, 30 Jun 2026 17:11:10 +0200 Subject: [PATCH 03/16] docs: fix starter prompt link to content/start.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 427606b..06bcd29 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ This CLI scaffolds a new Rayfin project with everything you need: data models, a > copilot -i "$(curl -sSfL https://aka.ms/rayfin/start.md)" > ``` > -> This loads the [Rayfin starter prompt](docs/START.md): it checks your environment, picks a template, scaffolds the project, and helps you customize. +> This loads the [Rayfin starter prompt](content/start.md): it checks your environment, picks a template, scaffolds the project, and helps you customize. ### Agent plugin From a0794ed8260e7f4eda49678770597dcea01be7b8 Mon Sep 17 00:00:00 2001 From: sinedied Date: Tue, 30 Jun 2026 19:52:39 +0200 Subject: [PATCH 04/16] docs: use colons instead of em-dashes in start.md headings Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- content/start.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/start.md b/content/start.md index b2c1aff..6b6c3ba 100644 --- a/content/start.md +++ b/content/start.md @@ -1,4 +1,4 @@ -# Rayfin — New Project Setup +# Rayfin: New Project Setup You're helping a developer create a new Rayfin project. Rayfin is a TypeScript Backend-as-a-Service: decorate data models to get auto-generated APIs (REST + @@ -13,7 +13,7 @@ internals. **One question at a time:** whenever you need input from the user, ask a single question and wait for the answer before asking the next. -## Step 1 — Detect context and ask what they want to build +## Step 1: Detect context and ask what they want to build First, check the current directory: context signals are enough, even if you can't open the files. It's already a Rayfin project if it has `rayfin/rayfin.yml` or a @@ -24,7 +24,7 @@ Then ask what they want to build. Infer whether it targets Microsoft Fabric or s be self-contained, only clarifying if it's unclear. This guides the template and later customization. -## Step 2 — Check prerequisites +## Step 2: Check prerequisites Before running any `npx` command: `node --version` (need 20+) and `git --version`. Install anything missing first: @@ -35,7 +35,7 @@ Install anything missing first: Don't proceed until `node --version` reports v20+. -## Step 3 — Get into a project +## Step 3: Get into a project Act on the context from Step 1. You're not a TTY, so always pass `-y` to `npx` (bare `npm create` can mishandle piped stdin and strip flags). @@ -75,7 +75,7 @@ agent rules + an MCP config, so don't redo that work. `cd` into the new `/ child dir (`rayfin init` works in place, so you're already there). If `npx` errors, Node may be missing; see Step 2. -## Step 4 — Load the in-project skill, then plan & customize +## Step 4: Load the in-project skill, then plan & customize Before writing any Rayfin-specific code, hand off to the project's authoritative, version-locked sources: From 939c5ac64aff7d8ef6df9e27fb1267cbbabde4a3 Mon Sep 17 00:00:00 2001 From: sinedied Date: Fri, 4 Sep 2026 10:20:08 +0200 Subject: [PATCH 05/16] fix: address PR review on start.md Delegate scaffolding to the getting-started skill instead of duplicating it. Step 3 now fetches skills/rayfin-getting-started/SKILL.md and follows it, so the default template, detection signals and CLI commands have a single source of truth and can no longer drift between the two entry points. Fix the stale init command in the skill. There is no public 'rayfin' package (404), and 'npx @microsoft/rayfin-cli' resolves a 'rayfin-cli' command that does not exist, exiting 1 with no output. The bin is 'rayfin', so npx needs the explicit -p form. Add a PowerShell equivalent for the README one-liner, and drop the 'plan mode' wording since 'copilot -i' does not enter that mode. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .claude-plugin/marketplace.json | 4 +- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- .cursor-plugin/plugin.json | 2 +- .github/plugin/marketplace.json | 4 +- .grok-plugin/plugin.json | 2 +- .kimi-plugin/plugin.json | 2 +- README.md | 7 +++ content/start.md | 71 ++++++++++---------------- gemini-extension.json | 2 +- kimi-marketplace.json | 2 +- plugin.json | 2 +- skills/rayfin-getting-started/SKILL.md | 15 ++++-- 13 files changed, 56 insertions(+), 61 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 1cfd640..60188d5 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,13 +6,13 @@ }, "metadata": { "description": "Official Rayfin agent skills for AI coding assistants", - "version": "0.4.0" + "version": "0.4.1" }, "plugins": [ { "name": "rayfin", "description": "Getting-started router for Rayfin - gets an agent from zero into a working Rayfin project via the Rayfin CLI (scaffold/init), then hands off to the version-locked in-project skill the scaffold installs.", - "version": "0.4.0", + "version": "0.4.1", "source": "./" } ] diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 66285ef..acd0e52 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "rayfin", - "version": "0.4.0", + "version": "0.4.1", "description": "Getting-started router skill for Rayfin - scaffold a new app with the Rayfin CLI, then use the version-locked skill installed in the project.", "author": { "name": "Microsoft", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index cc1c9aa..fd74555 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "rayfin", - "version": "0.4.0", + "version": "0.4.1", "description": "Getting-started router skill for Rayfin - scaffold a new app with the Rayfin CLI, then use the version-locked skill installed in the project.", "author": { "name": "Microsoft", diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 66285ef..acd0e52 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "rayfin", - "version": "0.4.0", + "version": "0.4.1", "description": "Getting-started router skill for Rayfin - scaffold a new app with the Rayfin CLI, then use the version-locked skill installed in the project.", "author": { "name": "Microsoft", diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index ef7e1cf..ccf8fe9 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -6,13 +6,13 @@ }, "metadata": { "description": "Official Rayfin agent skills for AI coding assistants", - "version": "0.4.0" + "version": "0.4.1" }, "plugins": [ { "name": "rayfin", "description": "Getting-started router for Rayfin — gets an agent from zero into a working Rayfin project via the Rayfin CLI (scaffold/init), then hands off to the version-locked in-project skill the scaffold installs.", - "version": "0.4.0", + "version": "0.4.1", "source": "./" } ] diff --git a/.grok-plugin/plugin.json b/.grok-plugin/plugin.json index 66285ef..acd0e52 100644 --- a/.grok-plugin/plugin.json +++ b/.grok-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "rayfin", - "version": "0.4.0", + "version": "0.4.1", "description": "Getting-started router skill for Rayfin - scaffold a new app with the Rayfin CLI, then use the version-locked skill installed in the project.", "author": { "name": "Microsoft", diff --git a/.kimi-plugin/plugin.json b/.kimi-plugin/plugin.json index b96eaff..12b0fa9 100644 --- a/.kimi-plugin/plugin.json +++ b/.kimi-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "rayfin", - "version": "0.4.0", + "version": "0.4.1", "description": "Getting-started router skill for Rayfin - scaffold a new app with the Rayfin CLI, then use the version-locked skill installed in the project.", "author": { "name": "Microsoft", diff --git a/README.md b/README.md index 06bcd29..07c604b 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,13 @@ This CLI scaffolds a new Rayfin project with everything you need: data models, a > copilot -i "$(curl -sSfL https://aka.ms/rayfin/start.md)" > ``` > +> On Windows (PowerShell): +> +> ```powershell +> $prompt = Invoke-RestMethod 'https://aka.ms/rayfin/start.md' +> copilot -i $prompt +> ``` +> > This loads the [Rayfin starter prompt](content/start.md): it checks your environment, picks a template, scaffolds the project, and helps you customize. ### Agent plugin diff --git a/content/start.md b/content/start.md index 6b6c3ba..ee45b2b 100644 --- a/content/start.md +++ b/content/start.md @@ -13,16 +13,15 @@ internals. **One question at a time:** whenever you need input from the user, ask a single question and wait for the answer before asking the next. -## Step 1: Detect context and ask what they want to build +## Step 1: Ask what they want to build -First, check the current directory: context signals are enough, even if you can't -open the files. It's already a Rayfin project if it has `rayfin/rayfin.yml` or a -`package.json` with `@microsoft/rayfin-*` deps. Never create a project nested inside -or beside an existing app. +Ask what they want to build, and confirm a kebab-case project name. Infer whether it +targets Microsoft Fabric or should be self-contained, only clarifying if it's unclear. +This guides the template choice in Step 3 and the customization in Step 4. -Then ask what they want to build. Infer whether it targets Microsoft Fabric or should -be self-contained, only clarifying if it's unclear. This guides the template and -later customization. +Keep it short if the working directory already looks like an existing app: Step 3 +determines the exact situation and never creates a project nested inside or beside +another one. ## Step 2: Check prerequisites @@ -37,43 +36,26 @@ Don't proceed until `node --version` reports v20+. ## Step 3: Get into a project -Act on the context from Step 1. You're not a TTY, so always pass `-y` to `npx` (bare -`npm create` can mishandle piped stdin and strip flags). +Don't scaffold from memory: fetch the getting-started skill and follow it. It is the +canonical source for project detection, the default template, and the exact CLI +commands, and it is kept up to date as those change. -- **Already in a Rayfin project:** don't scaffold; they may have run this by mistake. - Confirm they mean to work here (else ask for an empty target dir for a new project), - then go to Step 4. -- **Existing non-Rayfin app here:** confirm, then add Rayfin in place with - `npx -y rayfin init` (no template). Then Step 4. -- **Empty directory:** scaffold a new child project. Map the Step 1 answer to a - template, then list the live set and pick the closest fit: +```bash +curl -sSfL https://raw.githubusercontent.com/microsoft/rayfin/main/skills/rayfin-getting-started/SKILL.md +``` - ```bash - npx -y @microsoft/create-rayfin@latest --list-templates # JSON of gallery templates - ``` +Read it, then follow it to detect whether you're already in a Rayfin project, in an +existing non-Rayfin app, or in an empty directory, and to run the right command for +that case. Feed it what you learned in Step 1: what the user wants to build, and a +kebab-case project name you've confirmed with them. - If unavailable, fall back to these built-in slugs (default `dataapp` for Fabric, or - `todoapp` if self-contained / no Fabric workspace): +Two things that skill assumes and this prompt has already covered: Node is installed +(Step 2), and you're not a TTY, so keep passing `-y` to `npx`. If `npx` errors, Node +may be missing; see Step 2. - - **`dataapp`** _(default)_: Microsoft Fabric data analytics app. - - **`todoapp`**: full app (auth, entities, frontend); best to learn Rayfin end-to-end. - - **`gettingstartedauth`**: minimal app with auth wired up; add your own data model. - - **`blankapp`**: bare scaffolding (auth + data services, no entities/UI). - - For more options, including user-contributed ones, see the community gallery linked - at the end. - - Prefer a template matching their domain over a blank one. Propose a kebab-case - project name, confirm it, then: - - ```bash - npx -y @microsoft/create-rayfin@latest --project-name --template - ``` - -The scaffolder (or `init`) creates the project, installs dependencies, and writes -agent rules + an MCP config, so don't redo that work. `cd` into the new `/` -child dir (`rayfin init` works in place, so you're already there). If `npx` errors, -Node may be missing; see Step 2. +Once it has scaffolded, make sure you're at the project root before continuing: +`create-rayfin` creates a child directory, while an in-place init leaves you where you +are. Then continue to Step 4. ## Step 4: Load the in-project skill, then plan & customize @@ -86,9 +68,10 @@ version-locked sources: guessing. The skill file and `rayfin docs` work as soon as the project exists, so don't block waiting on the MCP reload. -Then enter plan mode and outline the first changes for what they described in Step 1: -entities under `rayfin/data/`, views under `src/`, and packages to install. Confirm -with the user before writing code. +Then plan before you build: outline the first changes for what they described in +Step 1 (entities under `rayfin/data/`, views under `src/`, packages to install) and +confirm that plan with the user before writing code. If your tooling has a planning +mode, use it. Don't start the backend or frontend; the user runs the app themselves when ready (see the project's `README.md`). diff --git a/gemini-extension.json b/gemini-extension.json index f7ce2a9..d6e2083 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -1,5 +1,5 @@ { "name": "rayfin", - "version": "0.4.0", + "version": "0.4.1", "description": "Getting-started router skill for Rayfin - scaffold a new app with the Rayfin CLI, then use the version-locked skill installed in the project." } diff --git a/kimi-marketplace.json b/kimi-marketplace.json index e009245..cf41f2b 100644 --- a/kimi-marketplace.json +++ b/kimi-marketplace.json @@ -4,7 +4,7 @@ { "id": "rayfin", "displayName": "Rayfin", - "version": "0.4.0", + "version": "0.4.1", "description": "Get started building a Rayfin app with the Rayfin CLI.", "homepage": "https://github.com/microsoft/rayfin", "keywords": [ diff --git a/plugin.json b/plugin.json index 7a5c413..70705d9 100644 --- a/plugin.json +++ b/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "rayfin", - "version": "0.4.0", + "version": "0.4.1", "description": "Getting-started router skill for Rayfin - scaffold a new app with the Rayfin CLI, then use the version-locked skill installed in the project.", "author": { "name": "Microsoft", diff --git a/skills/rayfin-getting-started/SKILL.md b/skills/rayfin-getting-started/SKILL.md index 60b859c..d14d24c 100644 --- a/skills/rayfin-getting-started/SKILL.md +++ b/skills/rayfin-getting-started/SKILL.md @@ -3,7 +3,7 @@ name: rayfin-getting-started description: "Use when starting or creating a NEW Rayfin app, or when a Rayfin task comes up and you are not yet inside a Rayfin project. Gets you into a project with the Rayfin CLI, then hands off to the authoritative, version-locked in-project rayfin skill/MCP/docs that own all in-project work. Triggers: build a Rayfin app, start a Rayfin project, create a new Rayfin app, create-rayfin, npm create @microsoft/rayfin, rayfin init, scaffold rayfin, rayfin CLI, rayfin template, universal app, awesome-rayfin gallery, get started with Rayfin" metadata: author: microsoft - version: "0.2.0" + version: "0.2.1" --- # Rayfin (Getting Started) @@ -46,8 +46,9 @@ project and continue in place. Never stand up a nested or sibling project. - **Already in one →** load `.agents/skills/rayfin/SKILL.md` and use the `rayfin` MCP / `rayfin docs`. Stop using this skill. -- **Existing non-Rayfin app here →** add Rayfin in place with `npx rayfin init` (don't - scaffold a separate project), then load the in-project skill. +- **Existing non-Rayfin app here →** add Rayfin in place with + `npx -y -p @microsoft/rayfin-cli@latest rayfin init` (don't scaffold a separate + project), then load the in-project skill. - **Empty directory →** scaffold (below), then load the in-project skill from the project root. ## Scaffold a new project @@ -64,8 +65,12 @@ mishandle piped stdin and strip flags, and `--project-name` is **required** non- # it fails to parse instead of continuing. npx -y @microsoft/create-rayfin@latest --project-name --template https://github.com/microsoft/awesome-rayfin --template-name "Universal App" -# Or add Rayfin into an existing/empty directory -npx rayfin init [directory] +# Or add Rayfin into an existing/empty directory. The CLI ships as +# @microsoft/rayfin-cli, whose bin is `rayfin`, so npx needs the explicit +# -p form: `npx @microsoft/rayfin-cli` looks for a `rayfin-cli` +# command, finds none, and exits 1 without printing anything. There is no +# public `rayfin` package either, so plain `npx rayfin` 404s. +npx -y -p @microsoft/rayfin-cli@latest rayfin init [directory] # Templates bundled with the CLI (JSON), only if you need a different starting point npx -y @microsoft/create-rayfin@latest --list-templates From 02e16f94cb6ea1afc623f261c12332de4bc6bad5 Mon Sep 17 00:00:00 2001 From: sinedied Date: Fri, 4 Sep 2026 10:24:35 +0200 Subject: [PATCH 06/16] docs: unwrap hard line breaks in start.md Rely on editor and GitHub soft wrapping instead of fixed-width line breaks. Content is unchanged; only whitespace differs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- content/start.md | 59 ++++++++++++------------------------------------ 1 file changed, 15 insertions(+), 44 deletions(-) diff --git a/content/start.md b/content/start.md index ee45b2b..71a21a7 100644 --- a/content/start.md +++ b/content/start.md @@ -1,32 +1,20 @@ # Rayfin: New Project Setup -You're helping a developer create a new Rayfin project. Rayfin is a TypeScript -Backend-as-a-Service: decorate data models to get auto-generated APIs (REST + -GraphQL), typed clients, auth, storage, and a local dev stack. +You're helping a developer create a new Rayfin project. Rayfin is a TypeScript Backend-as-a-Service: decorate data models to get auto-generated APIs (REST + GraphQL), typed clients, auth, storage, and a local dev stack. -**Core rule:** Rayfin's specifics are version-locked per project, so once a project -exists, never answer schema/API/auth/storage/deployment questions from memory: -remembered Rayfin APIs are routinely wrong. Defer to the project's installed skill, -`rayfin docs`, and `rayfin` MCP (Step 4). Keep this bootstrap light on Rayfin -internals. +**Core rule:** Rayfin's specifics are version-locked per project, so once a project exists, never answer schema/API/auth/storage/deployment questions from memory: remembered Rayfin APIs are routinely wrong. Defer to the project's installed skill, `rayfin docs`, and `rayfin` MCP (Step 4). Keep this bootstrap light on Rayfin internals. -**One question at a time:** whenever you need input from the user, ask a single -question and wait for the answer before asking the next. +**One question at a time:** whenever you need input from the user, ask a single question and wait for the answer before asking the next. ## Step 1: Ask what they want to build -Ask what they want to build, and confirm a kebab-case project name. Infer whether it -targets Microsoft Fabric or should be self-contained, only clarifying if it's unclear. -This guides the template choice in Step 3 and the customization in Step 4. +Ask what they want to build, and confirm a kebab-case project name. Infer whether it targets Microsoft Fabric or should be self-contained, only clarifying if it's unclear. This guides the template choice in Step 3 and the customization in Step 4. -Keep it short if the working directory already looks like an existing app: Step 3 -determines the exact situation and never creates a project nested inside or beside -another one. +Keep it short if the working directory already looks like an existing app: Step 3 determines the exact situation and never creates a project nested inside or beside another one. ## Step 2: Check prerequisites -Before running any `npx` command: `node --version` (need 20+) and `git --version`. -Install anything missing first: +Before running any `npx` command: `node --version` (need 20+) and `git --version`. Install anything missing first: - macOS: `brew install node git` - Windows: `winget install -e --id OpenJS.NodeJS.LTS Git.Git` @@ -36,45 +24,28 @@ Don't proceed until `node --version` reports v20+. ## Step 3: Get into a project -Don't scaffold from memory: fetch the getting-started skill and follow it. It is the -canonical source for project detection, the default template, and the exact CLI -commands, and it is kept up to date as those change. +Don't scaffold from memory: fetch the getting-started skill and follow it. It is the canonical source for project detection, the default template, and the exact CLI commands, and it is kept up to date as those change. ```bash curl -sSfL https://raw.githubusercontent.com/microsoft/rayfin/main/skills/rayfin-getting-started/SKILL.md ``` -Read it, then follow it to detect whether you're already in a Rayfin project, in an -existing non-Rayfin app, or in an empty directory, and to run the right command for -that case. Feed it what you learned in Step 1: what the user wants to build, and a -kebab-case project name you've confirmed with them. +Read it, then follow it to detect whether you're already in a Rayfin project, in an existing non-Rayfin app, or in an empty directory, and to run the right command for that case. Feed it what you learned in Step 1: what the user wants to build, and a kebab-case project name you've confirmed with them. -Two things that skill assumes and this prompt has already covered: Node is installed -(Step 2), and you're not a TTY, so keep passing `-y` to `npx`. If `npx` errors, Node -may be missing; see Step 2. +Two things that skill assumes and this prompt has already covered: Node is installed (Step 2), and you're not a TTY, so keep passing `-y` to `npx`. If `npx` errors, Node may be missing; see Step 2. -Once it has scaffolded, make sure you're at the project root before continuing: -`create-rayfin` creates a child directory, while an in-place init leaves you where you -are. Then continue to Step 4. +Once it has scaffolded, make sure you're at the project root before continuing: `create-rayfin` creates a child directory, while an in-place init leaves you where you are. Then continue to Step 4. ## Step 4: Load the in-project skill, then plan & customize -Before writing any Rayfin-specific code, hand off to the project's authoritative, -version-locked sources: +Before writing any Rayfin-specific code, hand off to the project's authoritative, version-locked sources: -1. Load `.agents/skills/rayfin/SKILL.md` and follow it; if your tooling supports it, - reload tools to bring the `rayfin` MCP online. -2. Look up version-matched APIs via `rayfin docs` and the `rayfin` MCP instead of - guessing. The skill file and `rayfin docs` work as soon as the project exists, so - don't block waiting on the MCP reload. +1. Load `.agents/skills/rayfin/SKILL.md` and follow it; if your tooling supports it, reload tools to bring the `rayfin` MCP online. +2. Look up version-matched APIs via `rayfin docs` and the `rayfin` MCP instead of guessing. The skill file and `rayfin docs` work as soon as the project exists, so don't block waiting on the MCP reload. -Then plan before you build: outline the first changes for what they described in -Step 1 (entities under `rayfin/data/`, views under `src/`, packages to install) and -confirm that plan with the user before writing code. If your tooling has a planning -mode, use it. +Then plan before you build: outline the first changes for what they described in Step 1 (entities under `rayfin/data/`, views under `src/`, packages to install) and confirm that plan with the user before writing code. If your tooling has a planning mode, use it. -Don't start the backend or frontend; the user runs the app themselves when ready (see -the project's `README.md`). +Don't start the backend or frontend; the user runs the app themselves when ready (see the project's `README.md`). ## Useful links From d6783d7c53515e2b39be92e91c0a82bc244c5116 Mon Sep 17 00:00:00 2001 From: sinedied Date: Fri, 4 Sep 2026 10:27:55 +0200 Subject: [PATCH 07/16] docs: fetch the skill via the agent's web fetch, not curl The curl one-liner was POSIX-only: PowerShell aliases curl to Invoke-WebRequest, which rejects those flags, so the step failed on Windows. Ask the agent to fetch and read the URL with its own web fetch capability instead, which is cross-platform by construction. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- content/start.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/start.md b/content/start.md index 71a21a7..f42cc01 100644 --- a/content/start.md +++ b/content/start.md @@ -26,11 +26,11 @@ Don't proceed until `node --version` reports v20+. Don't scaffold from memory: fetch the getting-started skill and follow it. It is the canonical source for project detection, the default template, and the exact CLI commands, and it is kept up to date as those change. -```bash -curl -sSfL https://raw.githubusercontent.com/microsoft/rayfin/main/skills/rayfin-getting-started/SKILL.md -``` +Fetch and read this URL with your web fetch capability, rather than a shell command, so this works the same on any platform: -Read it, then follow it to detect whether you're already in a Rayfin project, in an existing non-Rayfin app, or in an empty directory, and to run the right command for that case. Feed it what you learned in Step 1: what the user wants to build, and a kebab-case project name you've confirmed with them. + + +Then follow it to detect whether you're already in a Rayfin project, in an existing non-Rayfin app, or in an empty directory, and to run the right command for that case. Feed it what you learned in Step 1: what the user wants to build, and a kebab-case project name you've confirmed with them. Two things that skill assumes and this prompt has already covered: Node is installed (Step 2), and you're not a TTY, so keep passing `-y` to `npx`. If `npx` errors, Node may be missing; see Step 2. From 837d53084e4fc87b457f672521e2641ae7841e48 Mon Sep 17 00:00:00 2001 From: sinedied Date: Fri, 4 Sep 2026 10:32:29 +0200 Subject: [PATCH 08/16] docs: simplify prompt --- content/start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/start.md b/content/start.md index f42cc01..37ea33d 100644 --- a/content/start.md +++ b/content/start.md @@ -26,7 +26,7 @@ Don't proceed until `node --version` reports v20+. Don't scaffold from memory: fetch the getting-started skill and follow it. It is the canonical source for project detection, the default template, and the exact CLI commands, and it is kept up to date as those change. -Fetch and read this URL with your web fetch capability, rather than a shell command, so this works the same on any platform: +Fetch and read this URL: From 7fcbe8a5abfb8051762a75a222eae7bf5676872e Mon Sep 17 00:00:00 2001 From: sinedied Date: Fri, 4 Sep 2026 11:22:01 +0200 Subject: [PATCH 09/16] docs: reduce start.md --- content/start.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/content/start.md b/content/start.md index 37ea33d..95c8a77 100644 --- a/content/start.md +++ b/content/start.md @@ -2,7 +2,7 @@ You're helping a developer create a new Rayfin project. Rayfin is a TypeScript Backend-as-a-Service: decorate data models to get auto-generated APIs (REST + GraphQL), typed clients, auth, storage, and a local dev stack. -**Core rule:** Rayfin's specifics are version-locked per project, so once a project exists, never answer schema/API/auth/storage/deployment questions from memory: remembered Rayfin APIs are routinely wrong. Defer to the project's installed skill, `rayfin docs`, and `rayfin` MCP (Step 4). Keep this bootstrap light on Rayfin internals. +**Core rule:** Rayfin's specifics are version-locked per project, so once a project exists, never answer schema/API/auth/storage/deployment questions from memory: remembered Rayfin APIs are routinely wrong. Defer to the project's installed skill, `rayfin docs`, and `rayfin` MCP (Step 4). **One question at a time:** whenever you need input from the user, ask a single question and wait for the answer before asking the next. @@ -32,8 +32,6 @@ Fetch and read this URL: Then follow it to detect whether you're already in a Rayfin project, in an existing non-Rayfin app, or in an empty directory, and to run the right command for that case. Feed it what you learned in Step 1: what the user wants to build, and a kebab-case project name you've confirmed with them. -Two things that skill assumes and this prompt has already covered: Node is installed (Step 2), and you're not a TTY, so keep passing `-y` to `npx`. If `npx` errors, Node may be missing; see Step 2. - Once it has scaffolded, make sure you're at the project root before continuing: `create-rayfin` creates a child directory, while an in-place init leaves you where you are. Then continue to Step 4. ## Step 4: Load the in-project skill, then plan & customize @@ -46,9 +44,3 @@ Before writing any Rayfin-specific code, hand off to the project's authoritative Then plan before you build: outline the first changes for what they described in Step 1 (entities under `rayfin/data/`, views under `src/`, packages to install) and confirm that plan with the user before writing code. If your tooling has a planning mode, use it. Don't start the backend or frontend; the user runs the app themselves when ready (see the project's `README.md`). - -## Useful links - -- Docs: -- Scaffolder: -- Community template gallery: From e54ecae294ee6035b78ec2dc236c9eb674ce4694 Mon Sep 17 00:00:00 2001 From: sinedied Date: Fri, 4 Sep 2026 11:35:21 +0200 Subject: [PATCH 10/16] fix: verbosity --- skills/rayfin-getting-started/SKILL.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/skills/rayfin-getting-started/SKILL.md b/skills/rayfin-getting-started/SKILL.md index d14d24c..019c650 100644 --- a/skills/rayfin-getting-started/SKILL.md +++ b/skills/rayfin-getting-started/SKILL.md @@ -65,11 +65,7 @@ mishandle piped stdin and strip flags, and `--project-name` is **required** non- # it fails to parse instead of continuing. npx -y @microsoft/create-rayfin@latest --project-name --template https://github.com/microsoft/awesome-rayfin --template-name "Universal App" -# Or add Rayfin into an existing/empty directory. The CLI ships as -# @microsoft/rayfin-cli, whose bin is `rayfin`, so npx needs the explicit -# -p form: `npx @microsoft/rayfin-cli` looks for a `rayfin-cli` -# command, finds none, and exits 1 without printing anything. There is no -# public `rayfin` package either, so plain `npx rayfin` 404s. +# Or add Rayfin into an existing/empty directory. npx -y -p @microsoft/rayfin-cli@latest rayfin init [directory] # Templates bundled with the CLI (JSON), only if you need a different starting point From bd6194ce6d6123d704e280527c9f8e25a08fad99 Mon Sep 17 00:00:00 2001 From: sinedied Date: Sat, 5 Sep 2026 11:35:40 +0200 Subject: [PATCH 11/16] docs: simplify command --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 07c604b..8e44370 100644 --- a/README.md +++ b/README.md @@ -37,8 +37,7 @@ This CLI scaffolds a new Rayfin project with everything you need: data models, a > On Windows (PowerShell): > > ```powershell -> $prompt = Invoke-RestMethod 'https://aka.ms/rayfin/start.md' -> copilot -i $prompt +> copilot -i (irm https://aka.ms/rayfin/start.md) > ``` > > This loads the [Rayfin starter prompt](content/start.md): it checks your environment, picks a template, scaffolds the project, and helps you customize. From 98cf747cee27c5c887577cfc4f8811986c068adc Mon Sep 17 00:00:00 2001 From: sinedied Date: Sat, 5 Sep 2026 11:49:19 +0200 Subject: [PATCH 12/16] fix: node.js versions and winget install --- content/start.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/start.md b/content/start.md index 95c8a77..87ccf0b 100644 --- a/content/start.md +++ b/content/start.md @@ -14,13 +14,13 @@ Keep it short if the working directory already looks like an existing app: Step ## Step 2: Check prerequisites -Before running any `npx` command: `node --version` (need 20+) and `git --version`. Install anything missing first: +Before running any `npx` command: `node --version` and `git --version`. Rayfin supports even-numbered Node majors only, so you need **v20.x, v22.x, or v24.x**: an odd or newer major like 21, 23, or 25 passes a naive "20 or later" check and then fails at install time. Install anything missing first: - macOS: `brew install node git` -- Windows: `winget install -e --id OpenJS.NodeJS.LTS Git.Git` +- Windows: `winget install -e --id OpenJS.NodeJS.LTS` then `winget install -e --id Git.Git` - Linux (Debian/Ubuntu): Node from [nodejs.org/en/download](https://nodejs.org/en/download), then `sudo apt install -y git` -Don't proceed until `node --version` reports v20+. +Don't proceed until `node --version` reports v20.x, v22.x, or v24.x. ## Step 3: Get into a project From 2e5622826dd38c1a1b7da0a1c2ae3518f9cf86de Mon Sep 17 00:00:00 2001 From: sinedied Date: Sat, 5 Sep 2026 11:49:56 +0200 Subject: [PATCH 13/16] fix: missing --project-name flag --- skills/rayfin-getting-started/SKILL.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/skills/rayfin-getting-started/SKILL.md b/skills/rayfin-getting-started/SKILL.md index 019c650..e287668 100644 --- a/skills/rayfin-getting-started/SKILL.md +++ b/skills/rayfin-getting-started/SKILL.md @@ -47,8 +47,8 @@ project and continue in place. Never stand up a nested or sibling project. - **Already in one →** load `.agents/skills/rayfin/SKILL.md` and use the `rayfin` MCP / `rayfin docs`. Stop using this skill. - **Existing non-Rayfin app here →** add Rayfin in place with - `npx -y -p @microsoft/rayfin-cli@latest rayfin init` (don't scaffold a separate - project), then load the in-project skill. + `npx -y -p @microsoft/rayfin-cli@latest rayfin init --project-name ` (don't + scaffold a separate project), then load the in-project skill. - **Empty directory →** scaffold (below), then load the in-project skill from the project root. ## Scaffold a new project @@ -65,8 +65,8 @@ mishandle piped stdin and strip flags, and `--project-name` is **required** non- # it fails to parse instead of continuing. npx -y @microsoft/create-rayfin@latest --project-name --template https://github.com/microsoft/awesome-rayfin --template-name "Universal App" -# Or add Rayfin into an existing/empty directory. -npx -y -p @microsoft/rayfin-cli@latest rayfin init [directory] +# Or add Rayfin into an existing directory. +npx -y -p @microsoft/rayfin-cli@latest rayfin init --project-name [directory] # Templates bundled with the CLI (JSON), only if you need a different starting point npx -y @microsoft/create-rayfin@latest --list-templates From 35ed66bcda6aedd3361e8b4e722167b0f2991ff5 Mon Sep 17 00:00:00 2001 From: sinedied Date: Tue, 8 Sep 2026 20:04:43 +0200 Subject: [PATCH 14/16] fix: ensure supported node version and remove double quotes --- content/start.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/start.md b/content/start.md index 87ccf0b..806d519 100644 --- a/content/start.md +++ b/content/start.md @@ -14,11 +14,11 @@ Keep it short if the working directory already looks like an existing app: Step ## Step 2: Check prerequisites -Before running any `npx` command: `node --version` and `git --version`. Rayfin supports even-numbered Node majors only, so you need **v20.x, v22.x, or v24.x**: an odd or newer major like 21, 23, or 25 passes a naive "20 or later" check and then fails at install time. Install anything missing first: +Before running any `npx` command: `node --version` and `git --version`. Rayfin supports even-numbered Node majors only, so you need **v20.x, v22.x, or v24.x**: an odd or newer major like 21, 23, or 25 passes a naive 20-or-later check and then fails at install time. Install anything missing first: -- macOS: `brew install node git` +- macOS: `brew install node@24 git`, then `brew link --overwrite --force node@24` to put it on your PATH. The unversioned `node` formula tracks Node Current, which is usually out of range. - Windows: `winget install -e --id OpenJS.NodeJS.LTS` then `winget install -e --id Git.Git` -- Linux (Debian/Ubuntu): Node from [nodejs.org/en/download](https://nodejs.org/en/download), then `sudo apt install -y git` +- Linux (Debian/Ubuntu): install Node 24 via [NodeSource](https://github.com/nodesource/distributions), then `sudo apt install -y git` Don't proceed until `node --version` reports v20.x, v22.x, or v24.x. From 42f3092b852e8b11915d36b4f2f4f3b2d8c0e145 Mon Sep 17 00:00:00 2001 From: sinedied Date: Tue, 8 Sep 2026 20:06:21 +0200 Subject: [PATCH 15/16] ci: add workflow to validate absence of straight double quotes --- .github/workflows/validate-start-prompt.yml | 55 +++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 .github/workflows/validate-start-prompt.yml diff --git a/.github/workflows/validate-start-prompt.yml b/.github/workflows/validate-start-prompt.yml new file mode 100644 index 0000000..955b2b3 --- /dev/null +++ b/.github/workflows/validate-start-prompt.yml @@ -0,0 +1,55 @@ +name: Validate start.md prompt + +on: + pull_request: + paths: + - content/start.md + - .github/workflows/validate-start-prompt.yml + push: + branches: [main] + paths: + - content/start.md + - .github/workflows/validate-start-prompt.yml + +permissions: + contents: read + +jobs: + no-straight-quotes: + name: No straight double quotes in start.md + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Reject straight double quotes + run: | + if grep -n '"' content/start.md; then + echo + echo "::error file=content/start.md::start.md must not contain straight double quotes" + cat <<'EOF' + content/start.md contains straight double quotes (") on the lines above. + + Why this breaks: + The README documents launching the prompt as a single command, which + fetches this file and passes it to copilot as a native-process argument: + + copilot -i "$(curl -sSfL https://aka.ms/rayfin/start.md)" + copilot -i (irm https://aka.ms/rayfin/start.md) + + Windows PowerShell 5.1 is still the default shell on Windows, and its + legacy argument parser splits native-command arguments on embedded + straight double quotes. The prompt arrives truncated, with the remainder + passed as stray operands, so the user lands in a broken session. + pwsh 7 handles it correctly, but 5.1 is the default path we document. + + How to fix: + Reword to avoid the quotes (preferred), for example + "20 or later" -> 20-or-later + or use single quotes, or backticks for inline code. + + Apostrophes and backticks are fine: only straight double quotes break the + PowerShell 5.1 argument parser. + EOF + exit 1 + fi + echo "OK: no straight double quotes in content/start.md" From 93386e121c6137b5e0533412e721ddf395114f26 Mon Sep 17 00:00:00 2001 From: sinedied Date: Tue, 8 Sep 2026 20:22:53 +0200 Subject: [PATCH 16/16] docs: improve node.js version handling --- content/start.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/start.md b/content/start.md index 806d519..93bd3fd 100644 --- a/content/start.md +++ b/content/start.md @@ -14,13 +14,13 @@ Keep it short if the working directory already looks like an existing app: Step ## Step 2: Check prerequisites -Before running any `npx` command: `node --version` and `git --version`. Rayfin supports even-numbered Node majors only, so you need **v20.x, v22.x, or v24.x**: an odd or newer major like 21, 23, or 25 passes a naive 20-or-later check and then fails at install time. Install anything missing first: +Before running any `npx` command: `node --version` and `git --version`. Rayfin supports Node **LTS** releases, currently v20, v22 and v24. Odd-numbered major like 21, 23 or 25 are unsupported. Install anything missing first: -- macOS: `brew install node@24 git`, then `brew link --overwrite --force node@24` to put it on your PATH. The unversioned `node` formula tracks Node Current, which is usually out of range. +- macOS: install the LTS build from [nodejs.org/en/download](https://nodejs.org/en/download), which defaults to LTS. Homebrew's `node` formula tracks Current, so avoid it here. For git, use `brew install git` or the Xcode Command Line Tools. - Windows: `winget install -e --id OpenJS.NodeJS.LTS` then `winget install -e --id Git.Git` -- Linux (Debian/Ubuntu): install Node 24 via [NodeSource](https://github.com/nodesource/distributions), then `sudo apt install -y git` +- Linux (Debian/Ubuntu): `curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -` then `sudo apt install -y nodejs git` -Don't proceed until `node --version` reports v20.x, v22.x, or v24.x. +Don't proceed until `node --version` reports an LTS release, meaning v20.x, v22.x or v24.x today. When a newer LTS line ships, prefer it, and fall back to the most recent LTS the scaffolder accepts if it rejects the brand-new one. ## Step 3: Get into a project