feat: add guided setup prompt for coding agents (start.md)

.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": "./"
     }
   ]

.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",

.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",

.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",

.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": "./"
     }
   ]

.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"

.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",

.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",

README.md

@@ -26,6 +26,22 @@ 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)"
+> ```
+>
+> On Windows (PowerShell):
+>
+> ```powershell
+> 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.
+
 ### Agent plugin
 
 Install the Rayfin getting-started skill through your agent's native marketplace or extension manager:

content/start.md

@@ -0,0 +1,46 @@
+# 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).
+
+**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.
+
+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` 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: 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): `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 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
+
+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:
+
+<https://raw.githubusercontent.com/microsoft/rayfin/main/skills/rayfin-getting-started/SKILL.md>
+
+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.
+
+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:
+
+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.
+
+Don't start the backend or frontend; the user runs the app themselves when ready (see the project's `README.md`).

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."
 }

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": [

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",

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,7 +46,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 rayfin init` (don't
+- **Existing non-Rayfin app here →** add Rayfin in place with
+  `npx -y -p @microsoft/rayfin-cli@latest rayfin init --project-name <app-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.
 
@@ -64,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 <app-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 directory.
+npx -y -p @microsoft/rayfin-cli@latest rayfin init --project-name <app-name> [directory]
 
 # Templates bundled with the CLI (JSON), only if you need a different starting point
 npx -y @microsoft/create-rayfin@latest --list-templates