robodev 0.46.0 → 0.47.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "robodev",
-  "version": "0.46.0",
+  "version": "0.47.1",
   "description": "CLI for Robodev Starbase — create, auth, link, deploy, load, and run a project locally with robodev dev",
   "type": "module",
   "license": "MIT",

package/src/emit-starter.test.ts

@@ -149,6 +149,7 @@ test("collectFiles for empty starter includes hosted Welcome source", async () =
   assert.ok(paths.has("robodev/api/health.ts"));
   assert.ok(paths.has("index.html"));
   assert.ok(paths.has("src/main.tsx"));
+  assert.ok(paths.has("ROBODEV.md"));
   assert.ok(!paths.has("robodev/api/planets.ts"));
   assert.ok([...paths].every((path) => !path.startsWith("apps/")));
   assert.ok(files.length < 200);
@@ -167,9 +168,19 @@ test("emitStarter shadcn includes hosted Welcome plus orval and shadcn files", a
     assert.match(index, /<title>Kit<\/title>/);
     assert.match(index, /src\/main\.tsx/);
     const app = await readFile(join(dest, "src/App.tsx"), "utf8");
-    assert.match(app, /<h1>Welcome<\/h1>/);
+    assert.match(app, /<Route path="\/" element=\{<Home \/>\} \/>/);
     assert.doesNotMatch(app, /<h1>Kit<\/h1>/);
-    assert.match(app, /getHealth/);
+    assert.doesNotMatch(app, /<h1>Welcome<\/h1>/);
+    const home = await readFile(join(dest, "src/pages/Home.tsx"), "utf8");
+    assert.match(home, /<h1>Welcome<\/h1>/);
+    assert.match(home, /getHealth/);
+    const main = await readFile(join(dest, "src/main.tsx"), "utf8");
+    assert.match(main, /BrowserRouter/);
+    const notes = await readFile(join(dest, "ROBODEV.md"), "utf8");
+    assert.match(notes, /react-router-dom/);
+    assert.match(notes, /src\/pages\/Home\.tsx/);
+    assert.match(notes, /robodev-email templates list/);
+    assert.match(notes, /Do not write `robodev\/emails\/\*\.html`/);
     const endpoints = await readFile(join(dest, "src/api/generated/endpoints.ts"), "utf8");
     assert.match(endpoints, /export const getHealth/);
     assert.doesNotMatch(endpoints, /axios|@tanstack\/react-query/);
@@ -184,6 +195,7 @@ test("emitStarter shadcn includes hosted Welcome plus orval and shadcn files", a
     assert.equal(pkg.scripts?.["dev:fe"], "vite");
     assert.equal(pkg.scripts?.["generate:api"], "orval");
     assert.equal(pkg.dependencies?.["@robodev-ai/client"], "^0.12.0");
+    assert.match(pkg.dependencies?.["react-router-dom"] ?? "", /^\^6/);
     assert.match(pkg.devDependencies?.orval ?? "", /^\^/);
     const readme = await readFile(join(dest, "README.md"), "utf8");
     assert.match(readme, /^# Kit/m);
@@ -200,6 +212,8 @@ test("collectFiles for shadcn starter includes hosted Welcome and tooling config
   assert.ok(paths.has("robodev/api/health.ts"));
   assert.ok(paths.has("index.html"));
   assert.ok(paths.has("src/main.tsx"));
+  assert.ok(paths.has("src/pages/Home.tsx"));
+  assert.ok(paths.has("ROBODEV.md"));
   assert.ok(paths.has("src/components/ui/button.tsx"));
   assert.ok(paths.has("src/api/generated/endpoints.ts"));
   assert.ok(paths.has("src/api/openapi.json"));
@@ -219,6 +233,7 @@ test("collectFiles for space starter is Tiny APIs without apps/fe", async () =>
   assert.ok(paths.has("robodev/api/planets.ts"));
   assert.ok(paths.has("robodev/api/planets/paginate.ts"));
   assert.ok(paths.has("robodev/api/aliens/labels.ts"));
+  assert.ok(paths.has("ROBODEV.md"));
   assert.ok(!paths.has("robodev/api/files/upload-request.ts"));
   assert.ok(!paths.has("robodev/api/files/upload.ts"));
   assert.ok(!paths.has("index.html"));

package/templates/auth-chat/README.md

@@ -1,6 +1,6 @@
 # {{NAME}}
 
-Starter from `robodev create --starter auth-chat`: Tiny chat APIs (`chat` database, `messages` table), authenticated invite email, and a Povio UI in `apps/fe`.
+Starter from `robodev create --starter auth-chat`: Tiny chat APIs (`chat` database, `messages` table), authenticated invite email, and a Povio UI in `apps/fe`. Agents: read `ROBODEV.md`.
 
 After a CLI create or deploy with `.robodev` `frontend` set (the default for this starter), the project host serves the built Tiny SPA at `GET /`. APIs and Swagger still win over static files.
 

package/templates/auth-chat/ROBODEV.md

@@ -0,0 +1,71 @@
+# Robodev
+
+Use this file for Robodev and SDK facts. Do not web-search the SDK.
+
+## defineApi (copy-paste)
+
+`db`, `email`, `storage`, and `env` are injected. Never `import { db } from "@robodev-ai/sdk"`.
+The SDK is not installed in the runner. Do not `import("@robodev-ai/sdk")`. Do not search `/opt`, `node_modules`, or grok/gemini home for it.
+
+```ts
+import { defineApi, z } from "@robodev-ai/sdk";
+
+export const get = defineApi({
+  response: z.object({ ok: z.literal(true) }),
+  handler: async ({ db, email, storage, env }) => {
+    void db;
+    void email;
+    void storage;
+    void env;
+    return { ok: true as const };
+  },
+});
+```
+
+## Hard rules
+
+- Do not run npm, pnpm, or yarn install.
+- Do not start npm run dev, vite, or any local server.
+- Do not run tsc (node_modules is not installed in this runner).
+- Do not port-scan or curl/fetch localhost.
+- Preview is the WebContainer. Live APIs exist only after `robodev-publish be`.
+- Publish backend after a batch of file edits, not after every file.
+- Do not publish the frontend.
+
+## Backend
+
+- Auth: robodev-auth get / set / users / users-delete. Do not invent control-plane HTTP.
+- Secrets: robodev-secret list / set / delete. Use env.NAME in defineApi. List names only.
+- SQL: psql or robodev-sql for DML, SELECT, and seed only. Never print DATABASE_URL. Never run DDL.
+- Publish backend only with robodev-publish be. Do not publish the frontend.
+- Email settings: robodev-email get / set / validate / logs.
+
+## Email templates
+
+Hosted mail is the Email page. Changes apply immediately through these helpers — no Code save or deploy.
+
+- `robodev-email templates list`
+- `robodev-email templates get --slug <slug>`
+- `robodev-email templates set --slug <slug> [--subject] [--html] [--text]`
+
+`set` edits an existing slug. If the slug is missing and is a custom slug (`^[a-z][a-z0-9-]{0,62}$`, not `auth.*`), `set` creates it.
+
+System slugs: `auth.welcome` (`{{email}}`, `{{name}}`), `auth.magic-link` (`{{link}}`, `{{email}}`, `{{name}}`, `{{appUrl}}`), `auth.forgot-password` (`{{link}}`, `{{code}}`, `{{email}}`, `{{name}}`, `{{appUrl}}`). Keep placeholders exact. Do not delete system templates. Do not invent `auth.*` slugs.
+
+Send with `ctx.email.send({ template: "<slug>", to, vars })`.
+
+Do not write `robodev/emails/*.html` or `robodev/emails/*.json` for hosted templates. Those files do not update the live project.
+
+Never write `.env` or secrets. Never write `.robodev`.
+
+## Layout
+
+CLI Tiny-family: `robodev/database.ts` + `robodev/api/**`, Povio UI in `apps/fe`. Keep that layout.
+
+- Schema: `robodev/database.ts` (`defineDatabase` from `@robodev-ai/sdk`)
+- HTTP handlers: `robodev/api/**/*.ts`
+- Optional jobs / sockets / hooks under `robodev/`
+- Frontend: `apps/fe` (Povio UI)
+- Auth is reserved at `/api/user/*`. Do not add `robodev/api/user/**`.
+
+Allowed paths: `robodev/database.ts`, `robodev/api/**/*.ts`, `robodev/jobs/**/*.ts`, `robodev/sockets/**/*.ts`, `robodev/hooks/**/*.ts`, `robodev/package.json`, `apps/fe/**`, `.rulesync/**`, `openapi.json`, `package.json`, `README.md`, `ROBODEV.md`, `.gitignore`.

package/templates/auth-chat/package.json

@@ -12,7 +12,7 @@
     "@robodev-ai/sdk": "^0.13.0"
   },
   "devDependencies": {
-    "robodev": "^0.46.0",
+    "robodev": "^0.47.1",
     "rulesync": "^8.18.0",
     "typescript": "^5.9.2"
   }

package/templates/backend/README.md

@@ -1,6 +1,6 @@
 # {{NAME}}
 
-Tiny Template planets, aliens, and media APIs — no Vite UI. For Lovable, Bolt, or v0.
+Tiny Template planets, aliens, and media APIs — no Vite UI. For Lovable, Bolt, or v0. Agents: read `ROBODEV.md`.
 
 Deploy `robodev/database.ts` and `robodev/api/` from a real terminal:
 

package/templates/backend/ROBODEV.md

@@ -0,0 +1,69 @@
+# Robodev
+
+Use this file for Robodev and SDK facts. Do not web-search the SDK.
+
+## defineApi (copy-paste)
+
+`db`, `email`, `storage`, and `env` are injected. Never `import { db } from "@robodev-ai/sdk"`.
+The SDK is not installed in the runner. Do not `import("@robodev-ai/sdk")`. Do not search `/opt`, `node_modules`, or grok/gemini home for it.
+
+```ts
+import { defineApi, z } from "@robodev-ai/sdk";
+
+export const get = defineApi({
+  response: z.object({ ok: z.literal(true) }),
+  handler: async ({ db, email, storage, env }) => {
+    void db;
+    void email;
+    void storage;
+    void env;
+    return { ok: true as const };
+  },
+});
+```
+
+## Hard rules
+
+- Do not run npm, pnpm, or yarn install.
+- Do not start npm run dev, vite, or any local server.
+- Do not run tsc (node_modules is not installed in this runner).
+- Do not port-scan or curl/fetch localhost.
+- Preview is the WebContainer. Live APIs exist only after `robodev-publish be`.
+- Publish backend after a batch of file edits, not after every file.
+- Do not publish the frontend.
+
+## Backend
+
+- Auth: robodev-auth get / set / users / users-delete. Do not invent control-plane HTTP.
+- Secrets: robodev-secret list / set / delete. Use env.NAME in defineApi. List names only.
+- SQL: psql or robodev-sql for DML, SELECT, and seed only. Never print DATABASE_URL. Never run DDL.
+- Publish backend only with robodev-publish be. Do not publish the frontend.
+- Email settings: robodev-email get / set / validate / logs.
+
+## Email templates
+
+Hosted mail is the Email page. Changes apply immediately through these helpers — no Code save or deploy.
+
+- `robodev-email templates list`
+- `robodev-email templates get --slug <slug>`
+- `robodev-email templates set --slug <slug> [--subject] [--html] [--text]`
+
+`set` edits an existing slug. If the slug is missing and is a custom slug (`^[a-z][a-z0-9-]{0,62}$`, not `auth.*`), `set` creates it.
+
+System slugs: `auth.welcome` (`{{email}}`, `{{name}}`), `auth.magic-link` (`{{link}}`, `{{email}}`, `{{name}}`, `{{appUrl}}`), `auth.forgot-password` (`{{link}}`, `{{code}}`, `{{email}}`, `{{name}}`, `{{appUrl}}`). Keep placeholders exact. Do not delete system templates. Do not invent `auth.*` slugs.
+
+Send with `ctx.email.send({ template: "<slug>", to, vars })`.
+
+Do not write `robodev/emails/*.html` or `robodev/emails/*.json` for hosted templates. Those files do not update the live project.
+
+Never write `.env` or secrets. Never write `.robodev`.
+
+## Layout
+
+APIs only: `robodev/`. No Vite UI.
+
+- Schema: `robodev/database.ts`
+- HTTP handlers: `robodev/api/**/*.ts`
+- Auth is reserved at `/api/user/*`. Do not add `robodev/api/user/**`.
+
+Allowed paths: `robodev/database.ts`, `robodev/api/**/*.ts`, `robodev/jobs/**/*.ts`, `robodev/sockets/**/*.ts`, `robodev/hooks/**/*.ts`, `robodev/package.json`, `package.json`, `README.md`, `ROBODEV.md`, `.gitignore`.

package/templates/backend/package.json

@@ -11,7 +11,7 @@
     "@robodev-ai/sdk": "^0.13.0"
   },
   "devDependencies": {
-    "robodev": "^0.46.0",
+    "robodev": "^0.47.1",
     "typescript": "^5.9.2"
   }
 }

package/templates/empty/README.md

@@ -2,7 +2,7 @@
 
 Blank `robodev/database.ts` and `GET /api/health` plus a hosted Welcome page. No sample schema.
 
-The project App URL serves the hosted Welcome page. Edit `index.html` and `src/`, then `robodev deploy` (or Code + Save).
+The project App URL serves the hosted Welcome page. Edit `index.html` and `src/`, then `robodev deploy` (or Code + Save). Agents: read `ROBODEV.md`.
 
 ```bash
 robodev create my-app

package/templates/empty/ROBODEV.md

@@ -0,0 +1,72 @@
+# Robodev
+
+Use this file for Robodev and SDK facts. Do not web-search the SDK.
+
+## defineApi (copy-paste)
+
+`db`, `email`, `storage`, and `env` are injected. Never `import { db } from "@robodev-ai/sdk"`.
+The SDK is not installed in the runner. Do not `import("@robodev-ai/sdk")`. Do not search `/opt`, `node_modules`, or grok/gemini home for it.
+
+```ts
+import { defineApi, z } from "@robodev-ai/sdk";
+
+export const get = defineApi({
+  response: z.object({ ok: z.literal(true) }),
+  handler: async ({ db, email, storage, env }) => {
+    void db;
+    void email;
+    void storage;
+    void env;
+    return { ok: true as const };
+  },
+});
+```
+
+## Hard rules
+
+- Do not run npm, pnpm, or yarn install.
+- Do not start npm run dev, vite, or any local server.
+- Do not run tsc (node_modules is not installed in this runner).
+- Do not port-scan or curl/fetch localhost.
+- Preview is the WebContainer. Live APIs exist only after `robodev-publish be`.
+- Publish backend after a batch of file edits, not after every file.
+- Do not publish the frontend.
+
+## Backend
+
+- Auth: robodev-auth get / set / users / users-delete. Do not invent control-plane HTTP.
+- Secrets: robodev-secret list / set / delete. Use env.NAME in defineApi. List names only.
+- SQL: psql or robodev-sql for DML, SELECT, and seed only. Never print DATABASE_URL. Never run DDL.
+- Publish backend only with robodev-publish be. Do not publish the frontend.
+- Email settings: robodev-email get / set / validate / logs.
+
+## Email templates
+
+Hosted mail is the Email page. Changes apply immediately through these helpers — no Code save or deploy.
+
+- `robodev-email templates list`
+- `robodev-email templates get --slug <slug>`
+- `robodev-email templates set --slug <slug> [--subject] [--html] [--text]`
+
+`set` edits an existing slug. If the slug is missing and is a custom slug (`^[a-z][a-z0-9-]{0,62}$`, not `auth.*`), `set` creates it.
+
+System slugs: `auth.welcome` (`{{email}}`, `{{name}}`), `auth.magic-link` (`{{link}}`, `{{email}}`, `{{name}}`, `{{appUrl}}`), `auth.forgot-password` (`{{link}}`, `{{code}}`, `{{email}}`, `{{name}}`, `{{appUrl}}`). Keep placeholders exact. Do not delete system templates. Do not invent `auth.*` slugs.
+
+Send with `ctx.email.send({ template: "<slug>", to, vars })`.
+
+Do not write `robodev/emails/*.html` or `robodev/emails/*.json` for hosted templates. Those files do not update the live project.
+
+Never write `.env` or secrets. Never write `.robodev`.
+
+## Layout
+
+This is the hosted Empty layout. Keep it.
+
+- Schema: `robodev/database.ts`
+- HTTP handlers: `robodev/api/**/*.ts`
+- Frontend: root `index.html` + `src/**`
+- Auth is reserved at `/api/user/*`. Do not add `robodev/api/user/**`.
+
+Do not write a `frontend` block in `robodev/.robodev`. Root `index.html` + `src/` deploy as hosted React.
+
+Allowed paths: `robodev/database.ts`, `robodev/api/**/*.ts`, `robodev/jobs/**/*.ts`, `robodev/sockets/**/*.ts`, `robodev/hooks/**/*.ts`, `robodev/package.json`, `index.html`, `src/**`, `package.json`, `README.md`, `ROBODEV.md`, `.gitignore`.

package/templates/empty/package.json

@@ -16,7 +16,7 @@
     "react-dom": "^18.3.1"
   },
   "devDependencies": {
-    "robodev": "^0.46.0",
+    "robodev": "^0.47.1",
     "typescript": "^5.9.2",
     "vite": "^6.0.0"
   }

package/templates/marketplace/README.md

@@ -1,6 +1,6 @@
 # {{NAME}}
 
-Starter from `robodev create --starter marketplace`: Marketplace C2C marketplace schema (`categories`, `listings`, `cart_items`, `orders`, `watches`, `reviews`, `media`), file-based APIs in `robodev/api/`, and a Povio UI in `apps/fe`.
+Starter from `robodev create --starter marketplace`: Marketplace C2C marketplace schema (`categories`, `listings`, `cart_items`, `orders`, `watches`, `reviews`, `media`), file-based APIs in `robodev/api/`, and a Povio UI in `apps/fe`. Agents: read `ROBODEV.md`.
 
 After a CLI create or deploy with `.robodev` `frontend` set (the default for this starter), the project host serves the built Marketplace SPA at `GET /`. APIs and Swagger still win over static files.
 

package/templates/marketplace/ROBODEV.md

@@ -0,0 +1,71 @@
+# Robodev
+
+Use this file for Robodev and SDK facts. Do not web-search the SDK.
+
+## defineApi (copy-paste)
+
+`db`, `email`, `storage`, and `env` are injected. Never `import { db } from "@robodev-ai/sdk"`.
+The SDK is not installed in the runner. Do not `import("@robodev-ai/sdk")`. Do not search `/opt`, `node_modules`, or grok/gemini home for it.
+
+```ts
+import { defineApi, z } from "@robodev-ai/sdk";
+
+export const get = defineApi({
+  response: z.object({ ok: z.literal(true) }),
+  handler: async ({ db, email, storage, env }) => {
+    void db;
+    void email;
+    void storage;
+    void env;
+    return { ok: true as const };
+  },
+});
+```
+
+## Hard rules
+
+- Do not run npm, pnpm, or yarn install.
+- Do not start npm run dev, vite, or any local server.
+- Do not run tsc (node_modules is not installed in this runner).
+- Do not port-scan or curl/fetch localhost.
+- Preview is the WebContainer. Live APIs exist only after `robodev-publish be`.
+- Publish backend after a batch of file edits, not after every file.
+- Do not publish the frontend.
+
+## Backend
+
+- Auth: robodev-auth get / set / users / users-delete. Do not invent control-plane HTTP.
+- Secrets: robodev-secret list / set / delete. Use env.NAME in defineApi. List names only.
+- SQL: psql or robodev-sql for DML, SELECT, and seed only. Never print DATABASE_URL. Never run DDL.
+- Publish backend only with robodev-publish be. Do not publish the frontend.
+- Email settings: robodev-email get / set / validate / logs.
+
+## Email templates
+
+Hosted mail is the Email page. Changes apply immediately through these helpers — no Code save or deploy.
+
+- `robodev-email templates list`
+- `robodev-email templates get --slug <slug>`
+- `robodev-email templates set --slug <slug> [--subject] [--html] [--text]`
+
+`set` edits an existing slug. If the slug is missing and is a custom slug (`^[a-z][a-z0-9-]{0,62}$`, not `auth.*`), `set` creates it.
+
+System slugs: `auth.welcome` (`{{email}}`, `{{name}}`), `auth.magic-link` (`{{link}}`, `{{email}}`, `{{name}}`, `{{appUrl}}`), `auth.forgot-password` (`{{link}}`, `{{code}}`, `{{email}}`, `{{name}}`, `{{appUrl}}`). Keep placeholders exact. Do not delete system templates. Do not invent `auth.*` slugs.
+
+Send with `ctx.email.send({ template: "<slug>", to, vars })`.
+
+Do not write `robodev/emails/*.html` or `robodev/emails/*.json` for hosted templates. Those files do not update the live project.
+
+Never write `.env` or secrets. Never write `.robodev`.
+
+## Layout
+
+CLI Tiny-family: `robodev/database.ts` + `robodev/api/**`, Povio UI in `apps/fe`. Keep that layout.
+
+- Schema: `robodev/database.ts` (`defineDatabase` from `@robodev-ai/sdk`)
+- HTTP handlers: `robodev/api/**/*.ts`
+- Optional jobs / sockets / hooks under `robodev/`
+- Frontend: `apps/fe` (Povio UI)
+- Auth is reserved at `/api/user/*`. Do not add `robodev/api/user/**`.
+
+Allowed paths: `robodev/database.ts`, `robodev/api/**/*.ts`, `robodev/jobs/**/*.ts`, `robodev/sockets/**/*.ts`, `robodev/hooks/**/*.ts`, `robodev/package.json`, `apps/fe/**`, `.rulesync/**`, `openapi.json`, `package.json`, `README.md`, `ROBODEV.md`, `.gitignore`.

package/templates/marketplace/package.json

@@ -12,7 +12,7 @@
     "@robodev-ai/sdk": "^0.13.0"
   },
   "devDependencies": {
-    "robodev": "^0.46.0",
+    "robodev": "^0.47.1",
     "rulesync": "^8.18.0",
     "typescript": "^5.9.2"
   }

package/templates/shadcn/README.md

@@ -2,7 +2,7 @@
 
 Blank `robodev/database.ts` and `GET /api/health` plus a hosted Welcome page with shadcn and an orval client. No sample schema.
 
-The project App URL serves the hosted Welcome page. Edit `index.html` and `src/`, then `robodev deploy` (or Code + Save).
+The project App URL serves the hosted Welcome page (`/` via React Router in `src/pages/Home.tsx`). Edit `index.html` and `src/`, then `robodev deploy` (or Code + Save). Agents: read `ROBODEV.md`.
 
 ```bash
 robodev create my-app --template shadcn

package/templates/shadcn/ROBODEV.md

@@ -0,0 +1,78 @@
+# Robodev
+
+Use this file for Robodev and SDK facts. Do not web-search the SDK.
+
+## defineApi (copy-paste)
+
+`db`, `email`, `storage`, and `env` are injected. Never `import { db } from "@robodev-ai/sdk"`.
+The SDK is not installed in the runner. Do not `import("@robodev-ai/sdk")`. Do not search `/opt`, `node_modules`, or grok/gemini home for it.
+
+```ts
+import { defineApi, z } from "@robodev-ai/sdk";
+
+export const get = defineApi({
+  response: z.object({ ok: z.literal(true) }),
+  handler: async ({ db, email, storage, env }) => {
+    void db;
+    void email;
+    void storage;
+    void env;
+    return { ok: true as const };
+  },
+});
+```
+
+## Hard rules
+
+- Do not run npm, pnpm, or yarn install.
+- Do not start npm run dev, vite, or any local server.
+- Do not run tsc (node_modules is not installed in this runner).
+- Do not port-scan or curl/fetch localhost.
+- Preview is the WebContainer. Live APIs exist only after `robodev-publish be`.
+- Publish backend after a batch of file edits, not after every file.
+- Do not publish the frontend.
+
+## Backend
+
+- Auth: robodev-auth get / set / users / users-delete. Do not invent control-plane HTTP.
+- Secrets: robodev-secret list / set / delete. Use env.NAME in defineApi. List names only.
+- SQL: psql or robodev-sql for DML, SELECT, and seed only. Never print DATABASE_URL. Never run DDL.
+- Publish backend only with robodev-publish be. Do not publish the frontend.
+- Email settings: robodev-email get / set / validate / logs.
+
+## Email templates
+
+Hosted mail is the Email page. Changes apply immediately through these helpers — no Code save or deploy.
+
+- `robodev-email templates list`
+- `robodev-email templates get --slug <slug>`
+- `robodev-email templates set --slug <slug> [--subject] [--html] [--text]`
+
+`set` edits an existing slug. If the slug is missing and is a custom slug (`^[a-z][a-z0-9-]{0,62}$`, not `auth.*`), `set` creates it.
+
+System slugs: `auth.welcome` (`{{email}}`, `{{name}}`), `auth.magic-link` (`{{link}}`, `{{email}}`, `{{name}}`, `{{appUrl}}`), `auth.forgot-password` (`{{link}}`, `{{code}}`, `{{email}}`, `{{name}}`, `{{appUrl}}`). Keep placeholders exact. Do not delete system templates. Do not invent `auth.*` slugs.
+
+Send with `ctx.email.send({ template: "<slug>", to, vars })`.
+
+Do not write `robodev/emails/*.html` or `robodev/emails/*.json` for hosted templates. Those files do not update the live project.
+
+Never write `.env` or secrets. Never write `.robodev`.
+
+## Layout
+
+This is the hosted Shadcn layout. Keep it. Do not convert this tree to Tiny (`packages/be` + `apps/fe`).
+
+- Schema: `robodev/database.ts` (`defineDatabase` from `@robodev-ai/sdk`)
+- HTTP handlers: `robodev/api/**/*.ts` (`defineApi` from `@robodev-ai/sdk`)
+- Optional jobs: `robodev/jobs/**/*.ts`. Optional sockets: `robodev/sockets/**/*.ts` (`defineSocket`). Optional runtime packages go in `robodev/package.json` (allowlisted exact semver only). Do not npm install in this runner — Starbase installs on publish.
+- Frontend: root `index.html` + `src/**` (React, React Router, shadcn, generated orval client)
+- Auth is reserved at `/api/user/*`. Do not add `robodev/api/user/**`.
+
+Do not write a `frontend` block in `robodev/.robodev` — that block is for Tiny `apps/fe`. Root `index.html` + `src/` deploy as hosted React.
+
+- Route with React Router in `src/`. `src/pages/Home.tsx` is `/`. Add a page by adding a component and a `<Route>` in `src/App.tsx`.
+- Call APIs through the committed orval client under `src/api/generated`. After API changes, update `src/api/openapi.json` and regenerate.
+- UI: shadcn under `src/components/ui`. Hosted compile does not run Tailwind. Keep hosted CSS in `src/app.css`. `tailwind.config.ts` and `postcss.config.js` are for local `shadcn add` / Vite only.
+- Hosted FE packages: `react`, `react-dom`, `react-router-dom`, `@robodev-ai/client`. Do not import other npm packages in `src/` — hosted compile will fail.
+
+Allowed paths: `robodev/database.ts`, `robodev/api/**/*.ts`, `robodev/jobs/**/*.ts`, `robodev/sockets/**/*.ts`, `robodev/hooks/**/*.ts`, `robodev/package.json`, `index.html`, `src/**`, `package.json`, `README.md`, `ROBODEV.md`, `.gitignore`.

package/templates/shadcn/package.json

@@ -14,13 +14,14 @@
     "@robodev-ai/sdk": "^0.13.0",
     "@robodev-ai/client": "^0.5.0",
     "react": "^18.3.1",
-    "react-dom": "^18.3.1"
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.30.1"
   },
   "devDependencies": {
     "autoprefixer": "^10.4.21",
     "orval": "^7.11.2",
     "postcss": "^8.5.6",
-    "robodev": "^0.46.0",
+    "robodev": "^0.47.1",
     "shadcn": "^2.10.0",
     "tailwindcss": "^3.4.17",
     "typescript": "^5.9.2",

package/templates/shadcn/src/App.tsx

@@ -1,35 +1,10 @@
-import { useEffect, useState } from "react";
-import { getHealth } from "@/api/generated/endpoints";
-import { Button } from "@/components/ui/button";
+import { Route, Routes } from "react-router-dom";
+import { Home } from "./pages/Home";
 
 export function App() {
-  const [status, setStatus] = useState("Checking health…");
-
-  async function loadHealth() {
-    try {
-      const result = await getHealth();
-      if (result.status !== 200 || result.data.ok !== true) {
-        setStatus(`Request failed (${result.status})`);
-        return;
-      }
-      setStatus("{ ok: true }");
-    } catch (error) {
-      setStatus(error instanceof Error ? error.message : "Request failed");
-    }
-  }
-
-  useEffect(() => {
-    void loadHealth();
-  }, []);
-
   return (
-    <main>
-      <h1>Welcome</h1>
-      <p>Your app is ready.</p>
-      <Button type="button" onClick={() => void loadHealth()}>
-        Check health
-      </Button>
-      <p>{status}</p>
-    </main>
+    <Routes>
+      <Route path="/" element={<Home />} />
+    </Routes>
   );
 }

package/templates/shadcn/src/main.tsx

@@ -1,5 +1,10 @@
 import { createRoot } from "react-dom/client";
+import { BrowserRouter } from "react-router-dom";
 import { App } from "./App";
 import "./app.css";
 
-createRoot(document.getElementById("root")!).render(<App />);
+createRoot(document.getElementById("root")!).render(
+  <BrowserRouter>
+    <App />
+  </BrowserRouter>,
+);

package/templates/shadcn/src/pages/Home.tsx

@@ -0,0 +1,35 @@
+import { useEffect, useState } from "react";
+import { getHealth } from "@/api/generated/endpoints";
+import { Button } from "@/components/ui/button";
+
+export function Home() {
+  const [status, setStatus] = useState("Checking health…");
+
+  async function loadHealth() {
+    try {
+      const result = await getHealth();
+      if (result.status !== 200 || result.data.ok !== true) {
+        setStatus(`Request failed (${result.status})`);
+        return;
+      }
+      setStatus("{ ok: true }");
+    } catch (error) {
+      setStatus(error instanceof Error ? error.message : "Request failed");
+    }
+  }
+
+  useEffect(() => {
+    void loadHealth();
+  }, []);
+
+  return (
+    <main>
+      <h1>Welcome</h1>
+      <p>Your app is ready.</p>
+      <Button type="button" onClick={() => void loadHealth()}>
+        Check health
+      </Button>
+      <p>{status}</p>
+    </main>
+  );
+}

package/templates/space/README.md

@@ -1,6 +1,6 @@
 # {{NAME}}
 
-Starter from `robodev create`: Tiny Template schema (`planets`, `aliens`, `media`, `planet_likes`), file-based APIs in `robodev/api/`, and a Povio UI in `apps/fe`.
+Starter from `robodev create`: Tiny Template schema (`planets`, `aliens`, `media`, `planet_likes`), file-based APIs in `robodev/api/`, and a Povio UI in `apps/fe`. Agents: read `ROBODEV.md`.
 
 After a CLI create or deploy with `.robodev` `frontend` set (the default for this starter), the project host serves the built Tiny SPA at `GET /`. APIs and Swagger still win over static files.
 

package/templates/space/ROBODEV.md

@@ -0,0 +1,71 @@
+# Robodev
+
+Use this file for Robodev and SDK facts. Do not web-search the SDK.
+
+## defineApi (copy-paste)
+
+`db`, `email`, `storage`, and `env` are injected. Never `import { db } from "@robodev-ai/sdk"`.
+The SDK is not installed in the runner. Do not `import("@robodev-ai/sdk")`. Do not search `/opt`, `node_modules`, or grok/gemini home for it.
+
+```ts
+import { defineApi, z } from "@robodev-ai/sdk";
+
+export const get = defineApi({
+  response: z.object({ ok: z.literal(true) }),
+  handler: async ({ db, email, storage, env }) => {
+    void db;
+    void email;
+    void storage;
+    void env;
+    return { ok: true as const };
+  },
+});
+```
+
+## Hard rules
+
+- Do not run npm, pnpm, or yarn install.
+- Do not start npm run dev, vite, or any local server.
+- Do not run tsc (node_modules is not installed in this runner).
+- Do not port-scan or curl/fetch localhost.
+- Preview is the WebContainer. Live APIs exist only after `robodev-publish be`.
+- Publish backend after a batch of file edits, not after every file.
+- Do not publish the frontend.
+
+## Backend
+
+- Auth: robodev-auth get / set / users / users-delete. Do not invent control-plane HTTP.
+- Secrets: robodev-secret list / set / delete. Use env.NAME in defineApi. List names only.
+- SQL: psql or robodev-sql for DML, SELECT, and seed only. Never print DATABASE_URL. Never run DDL.
+- Publish backend only with robodev-publish be. Do not publish the frontend.
+- Email settings: robodev-email get / set / validate / logs.
+
+## Email templates
+
+Hosted mail is the Email page. Changes apply immediately through these helpers — no Code save or deploy.
+
+- `robodev-email templates list`
+- `robodev-email templates get --slug <slug>`
+- `robodev-email templates set --slug <slug> [--subject] [--html] [--text]`
+
+`set` edits an existing slug. If the slug is missing and is a custom slug (`^[a-z][a-z0-9-]{0,62}$`, not `auth.*`), `set` creates it.
+
+System slugs: `auth.welcome` (`{{email}}`, `{{name}}`), `auth.magic-link` (`{{link}}`, `{{email}}`, `{{name}}`, `{{appUrl}}`), `auth.forgot-password` (`{{link}}`, `{{code}}`, `{{email}}`, `{{name}}`, `{{appUrl}}`). Keep placeholders exact. Do not delete system templates. Do not invent `auth.*` slugs.
+
+Send with `ctx.email.send({ template: "<slug>", to, vars })`.
+
+Do not write `robodev/emails/*.html` or `robodev/emails/*.json` for hosted templates. Those files do not update the live project.
+
+Never write `.env` or secrets. Never write `.robodev`.
+
+## Layout
+
+CLI Tiny-family: `robodev/database.ts` + `robodev/api/**`, Povio UI in `apps/fe`. Keep that layout.
+
+- Schema: `robodev/database.ts` (`defineDatabase` from `@robodev-ai/sdk`)
+- HTTP handlers: `robodev/api/**/*.ts`
+- Optional jobs / sockets / hooks under `robodev/`
+- Frontend: `apps/fe` (Povio UI)
+- Auth is reserved at `/api/user/*`. Do not add `robodev/api/user/**`.
+
+Allowed paths: `robodev/database.ts`, `robodev/api/**/*.ts`, `robodev/jobs/**/*.ts`, `robodev/sockets/**/*.ts`, `robodev/hooks/**/*.ts`, `robodev/package.json`, `apps/fe/**`, `.rulesync/**`, `openapi.json`, `package.json`, `README.md`, `ROBODEV.md`, `.gitignore`.

package/templates/space/package.json

@@ -12,7 +12,7 @@
     "@robodev-ai/sdk": "^0.13.0"
   },
   "devDependencies": {
-    "robodev": "^0.46.0",
+    "robodev": "^0.47.1",
     "rulesync": "^8.18.0",
     "typescript": "^5.9.2"
   }