robodev 0.47.2 → 0.48.0

package/templates/povio/.rulesync/rules/project-overview.md

@@ -0,0 +1,32 @@
+---
+root: true
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Project overview and Rulesync source-of-truth guidance."
+globs: ["**/*"]
+cursor:
+  alwaysApply: true
+  description: "Project overview and Rulesync source-of-truth guidance."
+  globs: ["**/*"]
+---
+
+# Povio UI starter AI rules
+
+This project is a Vite React frontend in `apps/fe` plus a Robodev backend under **`robodev/`** (`robodev/database.ts` + `robodev/api/**/*.ts` using `@robodev-ai/sdk`). There is no Expo / mobile app in this starter. End-user auth is reserved on the project host at `/api/user/*`. There is no in-browser fake backend.
+
+`robodev deploy` from this root uploads schema, APIs, and (when `.robodev` has a `frontend` block) the local Vite build as a hosted static SPA. Use bun in `apps/fe` to iterate locally.
+
+Shared AI rules and skills are authored in `.rulesync/`. Generated files for Codex, Claude Code, and Cursor are local outputs and should be regenerated with `bun rules:gen`.
+
+This is a blank seed: no sample features. The backend ships `robodev/database.ts` (placeholder `items` table + `media`) and `GET /api/health`; the frontend ships auth (login/register), a Home page, and a profile page built with `@povio/ui`. Build product features on these seams instead of restructuring them.
+
+When an app has multiple user roles with distinct UI or business workflows, use the conditional role-based app structure rule. Do not apply role splitting to simple single-role apps or small permission differences.
+
+Use the more specific generated rules for:
+
+- Robodev `defineDatabase` tables in `robodev/database.ts`.
+- Robodev `defineApi` routes in `api/`.
+- Reserved `/api/user/*` auth contracts (do not implement `api/user/**` in the project).
+- Frontend API boundaries around generated `@/openapi` queries and models.
+- Povio UI and semantic Tailwind token usage.
+- Frontend forms, tables/lists, `QueryAutocomplete`, translations, and component structure.
+- Role-based frontend structure when the app has multiple distinct user roles.

package/templates/povio/.rulesync/rules/robodev-api.md

@@ -0,0 +1,30 @@
+---
+root: false
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Robodev defineApi file routes and handler conventions."
+globs: ["robodev/api/**/*.ts"]
+cursor:
+  alwaysApply: false
+  description: "Apply when editing Starbase API routes."
+  globs: ["robodev/api/**/*.ts"]
+---
+
+# Robodev API
+
+Project APIs live in `robodev/api/`. `robodev/api/todos.ts` would be served at `/todos` and `/api/todos`. Prefer the `/api/...` path in OpenAPI and frontend clients.
+
+## File layout
+
+- `robodev/api/foo.ts` → `/api/foo`
+- `robodev/api/foo/[id].ts` → `/api/foo/:id`
+- Export `get` / `post` / `put` / `patch` / `delete` as `defineApi(...)`.
+- Shared helpers belong in `robodev/api/_lib.ts`. Do not export `defineApi` from `_lib.ts`.
+- Do not add `robodev/api/user/**`. Those paths are reserved for Robodev Auth.
+
+## Handlers
+
+- Use `auth: "required"` on routes that Tiny marked authenticated.
+- Handler context includes `db`, `user`, `email`, `storage`, `params`, `query`, `body`.
+- Return JSON for 200, or `{ status, body }` for errors (404/403/400).
+- Keep request/response shapes compatible with `openapi.json` so OpenAPI codegen stays stable.
+- After changing public contracts, update `openapi.json` if needed and run `bun openapi:gen` from `apps/fe`.

package/templates/povio/.rulesync/rules/robodev-auth.md

@@ -0,0 +1,40 @@
+---
+root: false
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Reserved Robodev /api/user auth contracts."
+globs: ["**/*.ts", "apps/fe/src/**/*.{ts,tsx}"]
+cursor:
+  alwaysApply: false
+  description: "Apply when touching auth, login, register, or /api/user clients."
+  globs:
+    [
+      "robodev/database.ts",
+      "robodev/api/**/*.ts",
+      "apps/fe/src/components/features/auth/**/*.{ts,tsx}",
+      "apps/fe/src/clients/**/*.ts",
+    ]
+---
+
+# Robodev Auth
+
+End-user auth is reserved on the project host. Do not implement `api/user/**` in this project.
+
+## Contracts
+
+| Method  | Path                                      | Notes                                                   |
+| ------- | ----------------------------------------- | ------------------------------------------------------- |
+| POST    | `/api/user/auth/login`                    | `{ email, password }` → `{ accessToken, refreshToken }` |
+| POST    | `/api/user/auth/register`                 | password min 12, 201, token pair                        |
+| POST    | `/api/user/auth/refresh`                  | `{ refreshToken }` → new pair                           |
+| GET     | `/api/user/auth/magic-link`               | query `email`, generic status                           |
+| GET     | `/api/user/auth/magic-link/callback`      | query `code` → tokens                                   |
+| POST    | `/api/user/auth/forgot-password`          | `{ email }`                                             |
+| POST    | `/api/user/auth/forgot-password/callback` | `{ code, password }`                                    |
+| GET     | `/api/user/auth/google`                   | start OAuth; `redirect_uri` required                    |
+| GET/PUT | `/api/user/me`                            | flat `{ id, name, email }`                              |
+
+Access tokens last 15 minutes. Refresh tokens last 30 days. Frontend stores both and refreshes on 401 via `UserAuthApi.accessToken`.
+
+Error `code` is top-level: `invalid-credentials`, `identity-already-exists`, `identity-not-found`, `nonce-invalid`.
+
+Codegen operationIds stay Tiny-shaped (`UserAuthLocalPasswordController_login`, `UserMeController_get`, …) in `openapi.json`.

package/templates/povio/.rulesync/rules/robodev-database.md

@@ -0,0 +1,22 @@
+---
+root: false
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Robodev database.ts Drizzle schema and deploy sync."
+globs: ["robodev/database.ts"]
+cursor:
+  alwaysApply: false
+  description: "Apply when editing the Starbase database schema."
+  globs: ["robodev/database.ts"]
+---
+
+# Robodev Database
+
+The backend schema lives in `robodev/database.ts`. Default-export `defineDatabase` with Drizzle `pgTable` definitions. `robodev deploy` from this root creates or syncs the named Postgres database. There are no migration files.
+
+## Rules
+
+- Import table helpers from `@robodev-ai/sdk` (`pgTable`, `uuid`, `text`, `timestamp`, `integer`, and query helpers).
+- Do not recreate User or auth tables. End users live in platform `robodev_auth`. Store `userId` as `text` matching `ctx.user.id`.
+- Prefer scalar columns and foreign keys. Destructive drops need deploy confirmation or `--force`.
+- Export named tables so API files can import them from `../database` or `robodev/api/_lib.ts`.
+- Seed demo rows in API handlers on first read (see `robodev/api/_lib.ts` `ensureSeed`), not with a separate seed runner.

package/templates/povio/.rulesync/rules/role-based-app-structure.md

@@ -0,0 +1,36 @@
+---
+root: false
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Conditional role-based frontend and API structure for apps with distinct user roles."
+globs: ["apps/fe/src/**/*.{ts,tsx}", "robodev/api/**/*.ts"]
+cursor:
+  alwaysApply: false
+  description: "Apply only when an app has multiple user roles with distinct UI surfaces or business workflows."
+  globs: ["apps/fe/src/**/*.{ts,tsx}", "robodev/api/**/*.ts"]
+---
+
+# Role-Based App Structure
+
+Apply this rule only when the app has multiple user roles with meaningfully different UI surfaces or business workflows. For single-role apps or small permission differences, keep normal feature-based structure and express authorization in handlers, ACL metadata, or UI affordances.
+
+## Frontend Structure
+
+Split role-specific frontend code by role first:
+
+- `apps/fe/src/components/features/<role>/<feature>/...` for role-owned feature UI, such as `admin/companies`, `manager/projects`, or `worker/timesheets`.
+- `apps/fe/src/pages/(private)/(<role>)/...` for role-owned private routes and layout guards.
+- Shared auth, profile, layout, and role-neutral UI should stay outside role folders.
+
+When two roles touch the same entity with different screens or permissions, prefer separate role-owned feature components over a single component with many role branches.
+
+## API Structure
+
+Create role-prefixed `defineApi` files for role-owned behavior even when the backing table is shared. For example, use `api/manager/projects.ts` and `api/worker/projects.ts` when managers can create projects while workers can only list assigned ones.
+
+Role-prefixed routes should keep the role visible across the API surface:
+
+- Files: `api/<role>/<resource>.ts`, such as `api/manager/projects.ts`.
+- HTTP paths: `/api/<role>/<resource>`, such as `/api/manager/projects/paginate`.
+- Generated client modules should follow the same names.
+
+Keep shared auth, user, and media contracts role-neutral. Auth stays reserved at `/api/user/*`.

package/templates/povio/.rulesync/skills/media-feature/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: media-feature
+description: "Use when adding or changing feature-level media/file upload support or frontend FileUpload handling."
+targets: ["claudecode", "codexcli", "cursor"]
+codexcli:
+  short-description: Add or update media upload support for features.
+---
+
+# Media Feature Skill
+
+Preserve the upload contract:
+
+1. Frontend selects a `File` and keeps it local until submit. Do not call `/api/files/*`.
+2. Feature create/update is one `multipart/form-data` request (`POST` / `PUT`) with text fields and an optional `file`.
+3. The handler validates text fields, optionally calls `saveImage` from `robodev/api/_lib.ts` (`ctx.storage.upload` public), and writes the feature row.
+4. Update may send `clearImage=true` when the user cleared an existing image and picked nothing new. A new `file` wins over `clearImage`.
+5. Feature reads resolve the stored media ID to `image: { id, url }`.
+
+Never use a standalone files API. File bytes stay on the device until submit.
+
+Media metadata lives in the `media` table in `robodev/database.ts`. Bytes live in Robodev storage.

package/templates/povio/.rulesync/skills/povio-ui-styling/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: povio-ui-styling
+description: Mandatory first skill for any Tiny Template web frontend UI work in apps/fe. Load and apply it before other frontend, design, UX, accessibility, responsive, animation, or performance skills when creating, changing, reviewing, debugging, polishing, or refactoring pages and React components. It requires checking and using @povio/ui primitives before raw HTML or custom controls, and governs UIConfig defaults, UIOverrides, Tailwind utilities, semantic tokens, shared UI wrappers, and dedicated CSS files.
+---
+
+# Povio UI Styling
+
+Apply the narrowest styling layer that expresses the intended scope. Preserve one source of truth for each visual rule.
+
+## Priority and Coordination
+
+This is the foundation skill for every UI task under `apps/fe`. Apply it first, before broader design, UX, accessibility, animation, responsive, or React performance skills. Those skills may improve the result, but they must preserve the component and styling decisions defined here.
+
+Use this skill for all work that creates, changes, reviews, or diagnoses visible or interactive frontend UI, including:
+
+- Pages, layouts, navigation, dashboards, cards, lists, and empty states
+- Forms, filters, search, inputs, validation, uploads, and settings
+- Buttons, links, menus, dialogs, drawers, popovers, tooltips, and toasts
+- Tables, pagination, tags, badges, typography, icons, and loading states
+- Responsive behavior, theming, accessibility, motion, and visual polish
+- Component extraction, shared wrappers, design-system alignment, and Figma implementation
+
+This skill does not replace feature-specific skills. Apply the relevant feature skill as well, after establishing the Povio UI component and styling layer.
+
+## Inspect Before Styling
+
+1. Read the target component and nearby feature components.
+2. Inspect existing `@povio/ui` usage in `apps/fe` for the relevant primitive.
+3. Inspect `apps/fe/src/styles/overrides/uiOverrides.override.ts` and the matching file under `styles/overrides/defaults` before changing a Povio primitive.
+4. Inspect `apps/fe/src/styles/theme.css` for available generated tokens, but never edit that file manually.
+5. Inspect `apps/fe/src/styles/base.css` and `globals.css` before adding global rules or tokens.
+
+## Use This Decision Order
+
+### 1. Use an Existing Povio UI Component
+
+Use `@povio/ui` whenever it provides the semantic control or presentation primitive. This includes buttons, links, typography, icons, inputs, textareas, selects, checkboxes, radios, switches, forms, uploads, tags, badges, tables, pagination, menus, tooltips, modals, confirmations, drawers, popovers, toasts, loading indicators, and empty or feedback states.
+
+Prefer the component's supported props and variants over restyling its internals. Do not recreate a primitive with a raw HTML element merely to get a different appearance.
+
+Before introducing a native interactive element, a custom control, or a third-party UI component, search `@povio/ui` exports and existing feature usage for an existing equivalent. Native structural elements such as `main`, `section`, `article`, `nav`, and layout containers remain appropriate when no Povio semantic component exists.
+
+### 2. Use `UIConfig` for Application-Wide Defaults
+
+Use the root `UIConfig.Provider` when an existing Povio variant or option is correct and only its default should change across the application.
+
+Examples:
+
+- Make all inputs default to `small`.
+- Set the default table-cell typography size.
+- Set the default tag text size.
+
+Do not use `UIConfig` for a one-off screen or to invent a new variant.
+
+### 3. Use Tailwind for Composition and Local Presentation
+
+Use Tailwind classes in JSX for:
+
+- Page and component layout
+- Grid and flex behavior
+- Width, height, spacing, alignment, and overflow
+- Responsive composition
+- A one-instance surface, border, or text treatment
+- State selectors that remain short and readable
+
+Use semantic project utilities such as `bg-elevation-fill-default-1`, `text-text-default-1`, and `border-elevation-outline-default-1`. Do not use removed default palette utilities such as `bg-blue-500`, and do not repeat raw hex values in components.
+
+Keep Povio component `className` additions focused on outer layout or a genuinely local treatment. Do not pile conflicting utilities onto a component to fight its configured CVA variants. If the same correction is required on most instances, move it to `UIConfig` or `UIOverrides`.
+
+### 4. Use `UIOverrides` for Design-System-Level Povio Changes
+
+Use `UIOverrides.defineOverride(...)` when a Povio primitive must change consistently throughout the application:
+
+- Change the base classes of every instance.
+- Add or change supported variants.
+- Change compound-variant behavior.
+- Change internal slots not exposed by ordinary component props.
+- Align a primitive with the application's Figma design system.
+
+Place overrides under `apps/fe/src/styles/overrides/defaults/<component>.override.ts` and register them in `uiOverrides.override.ts`. Use the existing `mode`, `base`, `config`, variant, and compound-variant patterns.
+
+Update `apps/fe/src/types/ui.d.ts` when a new override variant must augment public Povio component types.
+
+Do not use `UIOverrides` for:
+
+- Page layout
+- One feature's special card
+- One exceptional component instance
+- A workaround that can be expressed through an existing prop
+
+Changing an override affects every consumer. Search all uses of the primitive and verify representative screens before finishing.
+
+### 5. Use a Shared Wrapper for Repeated Product Semantics
+
+Create a component under `apps/fe/src/components/shared` when several features need the same product-specific composition but the base Povio primitive should remain unchanged.
+
+Examples:
+
+- `StatusTag` mapping domain statuses to Povio `Tag` variants
+- `WalkSchedule` composing typography, icons, and layout
+- `PageCard` applying a repeated application surface
+
+Expose semantic props rather than forwarding a growing collection of styling flags.
+
+### 6. Use Dedicated CSS for Selector-Heavy or Browser-Level Behavior
+
+Create or extend a `.css` file when CSS communicates the rule more clearly than Tailwind:
+
+- Pseudo-elements used for connected timelines or route lines
+- Multi-step keyframes
+- Complex descendant, sibling, or state selectors
+- Calendar grids and overlapping appointments
+- Map-library markers, popups, or third-party DOM overrides
+- Print styles
+- Browser-global behavior such as scrollbars
+- Rules driven by CSS custom properties that many descendants consume
+
+Co-locate feature CSS with its owning component and import it there. Use a narrow, feature-prefixed class namespace, for example `walk-route__marker`. Keep truly global rules in `globals.css` or `base.css`.
+
+Do not create a CSS file for ordinary spacing, flex/grid layout, a simple hover, or a semantic color already expressible with a short Tailwind class list.
+
+## Scope Guide
+
+| Desired scope                                                  | Styling layer               |
+| -------------------------------------------------------------- | --------------------------- |
+| Existing primitive behavior                                    | Povio UI props/variants     |
+| Default for every instance                                     | `UIConfig`                  |
+| One page or component composition                              | Tailwind                    |
+| Every instance or internal Povio slot                          | `UIOverrides`               |
+| Repeated product-specific composition                          | Shared wrapper              |
+| Pseudo-elements, keyframes, complex selectors, third-party DOM | Scoped `.css`               |
+| Generated design tokens                                        | Figma-generated `theme.css` |
+| Handwritten global token or browser rule                       | `base.css` or `globals.css` |
+
+Retheming the app means overriding tokens in `globals.css`, in `@layer base`, after the
+`theme.css` import — nowhere else redeclares them, so the last declaration in that layer wins.
+
+## Guardrails
+
+- Use `@povio/ui` before creating a custom primitive.
+- Do not let guidance from a general frontend or design skill replace an available `@povio/ui` primitive with raw HTML, a local reimplementation, or another component library.
+- Use semantic Tailwind tokens from the project theme.
+- Never manually edit `apps/fe/src/styles/theme.css`.
+- Avoid `!important`; resolve ownership or specificity instead.
+- Avoid inline `style` except for truly runtime numeric values such as map coordinates or calculated dimensions. Prefer CSS custom properties when descendants need the value.
+- Avoid Sass, CSS-in-JS, and a second styling system.
+- Preserve visible focus, disabled, hover, pressed, error, and loading states.
+- Respect `prefers-reduced-motion` for nonessential animation.
+- Keep touch targets at least 44 by 44 CSS pixels where practical.
+- Verify changes at mobile and desktop breakpoints.
+
+## Examples
+
+Use Tailwind for local layout:
+
+```tsx
+<section className="grid gap-4 rounded-modal-rounding-default border border-elevation-outline-default-1 bg-elevation-fill-default-1 p-4">
+  <Typography size="title-4">{title}</Typography>
+  {children}
+</section>
+```
+
+Use `UIConfig` for an existing global default:
+
+```tsx
+<UIConfig.Provider
+  config={{
+    input: { size: "small" },
+  }}
+>
+  {children}
+</UIConfig.Provider>
+```
+
+Use a scoped CSS file for a connected route line:
+
+```css
+.walk-route__marker::after {
+  content: "";
+  position: absolute;
+  inset-block: 1.25rem -0.75rem;
+  inset-inline-start: 50%;
+  width: 0.125rem;
+  background: rgb(var(--elevation-outline-default-1-base));
+  transform: translateX(-50%);
+}
+```
+
+Use `UIOverrides` only when the same primitive-level change is intentionally global:
+
+```ts
+export const tagOverride = UIOverrides.defineOverride("tag.cva", {
+  mode: "overrideCva",
+  base: ["inline-flex items-center border"],
+  config: {
+    variants: {
+      color: {
+        success: "border-interactive-subtle-success-idle bg-interactive-subtle-success-idle",
+      },
+    },
+  },
+});
+```
+
+## Verification
+
+1. Run formatting, linting, and TypeScript checks relevant to `apps/fe`.
+2. Inspect at least one representative use for every globally changed primitive.
+3. Check keyboard focus and disabled/error states.
+4. Check mobile and desktop layouts.
+5. Confirm no raw default-palette classes or duplicated design values were introduced.

package/templates/povio/.rulesync/skills/povio-ui-styling/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Povio UI Styling"
+  short_description: "Required first for all apps/fe UI work"
+  default_prompt: "Use $povio-ui-styling first for this apps/fe UI task, preserving @povio/ui primitives before applying other frontend guidance."

package/templates/povio/.rulesync/skills/robodev-api-route/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: robodev-api-route
+description: Add a defineApi route under robodev/api/.
+---
+
+# Add a Robodev API route
+
+1. Create `robodev/api/<path>.ts` or `robodev/api/<path>/[id].ts`.
+2. Export HTTP methods with `defineApi` from `@robodev-ai/sdk`.
+3. Use `auth: "required"` unless the route is public.
+4. Keep JSON shapes aligned with `openapi.json`.
+5. Do not create `robodev/api/user/**` files.
+6. Deploy from the project root (`robodev deploy`), then `bun openapi:gen` in `apps/fe` if the contract changed.

package/templates/povio/.rulesync/skills/robodev-table/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: robodev-table
+description: Add a Drizzle table to robodev/database.ts and wire it into defineApi handlers.
+---
+
+# Add a Robodev table
+
+1. Add a `pgTable` to `robodev/database.ts` and include it in `defineDatabase({ tables })`.
+2. Do not add a User table. Auth users are platform-managed; store `userId` as text.
+3. Import the table in `api/_lib.ts` or the route file that needs it.
+4. Deploy from the project root with `robodev deploy`. Destructive drops need confirmation or `--force`.
+5. If the frontend needs the new fields, update `openapi.json` and run `bun openapi:gen` from `apps/fe`.

package/templates/povio/README.md

@@ -0,0 +1,40 @@
+# {{NAME}}
+
+Blank starter with the real `@povio/ui` kit: empty schema (placeholder `items` + `media`), `GET /api/health`, file-based APIs in `robodev/api/`, and a Povio UI frontend in `apps/fe` with seeded auth (login/register), Home, and profile — no sample features. 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 SPA at `GET /`. APIs and Swagger still win over static files.
+
+Local Starbase occupies FE **:3000** and BE **:4000**. Point the CLI at it, then run starter Vite on **3001** so it does not steal the dashboard port:
+
+```bash
+STARBASE_URL=http://localhost:4000 STARBASE_FE_URL=http://localhost:3000
+# from starter root: auth / link / deploy as today
+cd apps/fe
+bun install
+bun openapi:gen
+bunx --bun vite --port 3001
+```
+
+`bun` is required for `apps/fe`.
+
+Auth, link, and deploy from this **root**:
+
+```bash
+npx robodev auth
+npx robodev link
+npx robodev deploy
+```
+
+`robodev create` / `robodev link` write `VITE_API_URL`, `VITE_PUBLIC_API_URL`, and `APP_PUBLIC_API_URL` in `.env`, rewrite `.config/local.spa.yml` so the FE talks to the project host, and (when `apps/fe/package.json` exists) add a `frontend` block to `.robodev`. `robodev deploy` then runs the local Vite build and uploads the static output.
+
+Dashboard create deploys schema + APIs only. The FE tree is copied by `robodev create`; a later CLI deploy hosts the SPA.
+
+Auth stays reserved at `/api/user/*`. Do not add `robodev/api/user/**`.
+
+Regenerate AI rules after editing `.rulesync/`:
+
+```bash
+bun rules:gen
+```
+
+Docs: https://robodev.povio.dev/docs

package/templates/povio/ROBODEV.md

@@ -0,0 +1,84 @@
+# 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 };
+  },
+});
+```
+
+Method exports: one export per method — `get` / `post` / `put` / `patch` / `delete`. `delete` is a reserved word — write `export const del = ...` or `export { remove as delete }`; both serve DELETE.
+
+`ctx.user.id` is a string like `usr_abc123`, not a UUID. Type user id columns as `text`, never `uuid`.
+
+Throw an Error with an integer `statusCode` (400-599) to answer with that status: `throw Object.assign(new Error("Not found"), { statusCode: 404 })`. Any other throw is a generic 500.
+
+## 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.
+
+## Auth and product data
+
+Persist primary product data with `defineApi` and `robodev-publish be`. Do not use localStorage as the product store unless the user asked for a public, static, or no-account page. Auth is on by default: add login and register and protect routes unless the product is public or unauthenticated. Use `auth: "required"` and `ctx.user.id`. Call reserved `/api/user/auth/*` — do not implement `api/user/**`. Tiny and Shadcn: reuse seed login/register and AuthGuard. Empty and legacy: create login/register with `@robodev-ai/client` tokens. A missing `.rulesync` skill is not a reason to skip APIs. Do not require `robodev-auth set` every run.
+
+## 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. This is a blank seed — no sample features.
+
+- Schema: `robodev/database.ts` (`defineDatabase` from `@robodev-ai/sdk`; placeholder `items` table + `media`)
+- HTTP handlers: `robodev/api/**/*.ts` (`GET /api/health` is seeded; shared helpers in `robodev/api/_lib.ts`)
+- Optional jobs / sockets / hooks under `robodev/`
+- Frontend: `apps/fe` (real `@povio/ui` kit, TanStack Router + Query, generated `@/openapi` client). Seeded: login/register (`(guest)`), Home and profile (`(private)`). Reuse the seeded auth — never rebuild token handling.
+- After schema or API changes, update root `openapi.json` and regenerate the client (`cd apps/fe && bun openapi:gen`), then `robodev-publish be`.
+- Add new pages under `apps/fe/src/pages/(private)/` and link them in `AppHeader.tsx` / `MobileNavigation.tsx`.
+- Auth is reserved at `/api/user/*`. Do not add `robodev/api/user/**`.
+- AI rules live in `.rulesync/` — read `.rulesync/rules/project-overview.md` first.
+
+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/povio/apps/fe/index.html

@@ -0,0 +1,24 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link
+      rel="icon"
+      type="image/svg+xml"
+      href="/favicon.svg"
+    />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0"
+    />
+    <title>Povio UI</title>
+  </head>
+
+  <body class="bg-elevation-fill-default-2 text-text-default-1">
+    <div id="app"></div>
+    <script
+      type="module"
+      src="/src/main.tsx"
+    ></script>
+  </body>
+</html>

package/templates/povio/apps/fe/openapi-codegen.config.ts

@@ -0,0 +1,72 @@
+/* oxlint-disable import/no-nodejs-modules */
+import type { OpenAPICodegenConfig } from "@povio/openapi-codegen-cli";
+import { resolveConfigSync } from "@povio/resolve-config";
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const COMPACT_OPENAPI_INPUT = "../../openapi.json";
+const repoRoot = resolve(process.cwd(), "../..");
+
+function readDotEnvKey(root: string, key: string): string | undefined {
+  try {
+    const content = readFileSync(join(root, ".env"), "utf8");
+    const line = content.split(/\r?\n/).find((row) => row.startsWith(`${key}=`));
+    const value = line?.slice(key.length + 1).trim();
+    return value || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function loadResolvedSpaEnv(cwd: string): Record<string, string | undefined> {
+  try {
+    const resolved = resolveConfigSync({ cwd, module: "spa", target: "resolved" });
+    if (resolved && typeof resolved === "object") {
+      return resolved as Record<string, string | undefined>;
+    }
+  } catch {
+    // unnamed or missing spa manifest
+  }
+  return {};
+}
+
+const env = loadResolvedSpaEnv(repoRoot);
+
+function fallbackApiUrl(): string {
+  return (
+    env.VITE_PUBLIC_API_URL ||
+    process.env.VITE_PUBLIC_API_URL ||
+    readDotEnvKey(repoRoot, "VITE_PUBLIC_API_URL") ||
+    "http://localhost:4000"
+  );
+}
+
+function resolveLiveOpenApiInput(apiUrl = fallbackApiUrl()) {
+  const usable = apiUrl.trim();
+  if (!usable) return COMPACT_OPENAPI_INPUT;
+  return `${usable.replace(/\/+$/, "")}/openapi.json`;
+}
+
+export function resolveOpenApiInput() {
+  if (process.env.OPENAPI_INPUT) return process.env.OPENAPI_INPUT;
+  if (process.env.OPENAPI_LIVE === "true") return resolveLiveOpenApiInput();
+  return COMPACT_OPENAPI_INPUT;
+}
+
+const config: OpenAPICodegenConfig = {
+  input: resolveOpenApiInput(),
+  output: "src/openapi",
+  tsPath: "@/openapi",
+  restClientImportPath: "@/clients/app-rest-client",
+  clearOutput: true,
+  excludeRedundantZodSchemas: false,
+  checkAcl: false,
+  acl: false,
+  replaceOptionalWithNullish: true,
+  infiniteQueries: true,
+  mutationDefaultOnError: true,
+  modelsInCommon: true,
+  axiosRequestConfig: true,
+};
+
+export default config;