robodev 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "robodev",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "CLI for Robodev Starbase — create, auth, link, and deploy hosted apps",
   "type": "module",
   "license": "MIT",

package/src/emit-starter.test.ts

@@ -38,6 +38,20 @@ test("emitStarter rewrites root package.json name only", async () => {
   }
 });
 
+test("collectFiles for auth-chat starter is Tiny APIs without apps/fe", async () => {
+  const files = await collectFiles(join(cliRoot(), "..", "starters", "auth-chat"));
+  const paths = new Set(files.map((file) => file.path));
+  assert.ok(paths.has("database.ts"));
+  assert.ok(paths.has("api/messages.ts"));
+  assert.ok(paths.has("api/invite.ts"));
+  assert.ok(paths.has("api/health.ts"));
+  assert.ok(paths.has("api/me.ts"));
+  assert.ok(!paths.has("index.html"));
+  assert.ok(!paths.has("src/main.tsx"));
+  assert.ok([...paths].every((path) => !path.startsWith("apps/")));
+  assert.ok(files.length < 200);
+});
+
 test("collectFiles for space starter is Tiny APIs without apps/fe", async () => {
   const files = await collectFiles(join(cliRoot(), "..", "starters", "space"));
   const paths = new Set(files.map((file) => file.path));

package/src/index.ts

@@ -25,6 +25,7 @@ import {
   resolveStarterTree,
   type Starter,
 } from "./emit-starter.js";
+import { parseCreateArgs } from "./parse-create-args.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -38,7 +39,7 @@ Commands:
   logout               Remove stored credentials
   whoami               Show the signed-in user
   projects             List your projects
-  create [path] [--starter <id>] [--empty]  Create a project, scaffold a starter, and deploy
+  create [path] [--starter <id>] [--empty] [--org <id>]  Create a project, scaffold a starter, and deploy
   link [projectId]     Write .robodev in the current folder
   deploy [--force]     Deploy database.ts, api/*.ts, jobs, and frontend files (no Vite / npm run build)
 `);
@@ -279,48 +280,47 @@ function validIdsMessage(starters: Starter[]): string {
   return `Valid ids: ${starters.map((starter) => starter.id).join(", ")}`;
 }
 
-function parseCreateArgs(args: string[]): { path?: string; starterId?: string } {
-  let path: string | undefined;
-  let starterId: string | undefined;
-  let empty = false;
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--empty") {
-      empty = true;
-      continue;
-    }
-    if (arg === "--starter") {
-      const value = args[i + 1];
-      if (!value || value.startsWith("-")) {
-        throw new Error("Missing value for --starter");
-      }
-      starterId = value;
-      i += 1;
-      continue;
-    }
-    if (arg.startsWith("--starter=")) {
-      const value = arg.slice("--starter=".length);
-      if (!value) {
-        throw new Error("Missing value for --starter");
-      }
-      starterId = value;
-      continue;
-    }
-    if (arg.startsWith("-")) {
-      throw new Error(`Unknown flag ${arg}`);
-    }
-    if (path !== undefined) {
-      throw new Error(`Unexpected argument ${arg}`);
-    }
-    path = arg;
+type Organization = {
+  id: string;
+  name: string;
+  plan: string;
+  createdAt: string;
+  role: "admin" | "developer";
+};
+
+function validOrgIdsMessage(orgs: Organization[]): string {
+  return `Valid ids: ${orgs.map((org) => org.id).join(", ")}`;
+}
+
+async function resolveOrganization(flagId: string | undefined): Promise<string | undefined> {
+  const { organizations } = await authed<{ organizations: Organization[] }>("/v1/organizations");
+  const adminOrgs = organizations.filter((org) => org.role === "admin");
+  if (flagId !== undefined) {
+    return flagId;
   }
-  if (empty && starterId !== undefined) {
-    throw new Error("Use either --empty or --starter, not both.");
+  if (adminOrgs.length === 0) {
+    throw new Error("You need an admin role in an organization to create a project.");
   }
-  if (empty) {
-    starterId = "empty";
+  if (adminOrgs.length === 1 || !stdin.isTTY) {
+    return undefined;
   }
-  return { path, starterId };
+  console.log("Organizations:");
+  adminOrgs.forEach((org, i) => {
+    console.log(`  ${i + 1}. ${org.name} (${org.id})`);
+  });
+  const answer = (await prompt("Organization number or id: ")).trim();
+  if (!answer) {
+    throw new Error(`Unknown organization "". ${validOrgIdsMessage(adminOrgs)}`);
+  }
+  const asIndex = Number(answer);
+  if (Number.isInteger(asIndex) && asIndex >= 1 && asIndex <= adminOrgs.length) {
+    return adminOrgs[asIndex - 1].id;
+  }
+  const found = adminOrgs.find((org) => org.id === answer);
+  if (!found) {
+    throw new Error(`Unknown organization "${answer}". ${validOrgIdsMessage(adminOrgs)}`);
+  }
+  return found.id;
 }
 
 async function resolveStarter(flagId: string | undefined): Promise<Starter> {
@@ -406,7 +406,15 @@ async function bunAvailable(): Promise<boolean> {
   }
 }
 
-function printSpaceNextSteps(displayPath: string): void {
+async function hasAppsFe(root: string): Promise<boolean> {
+  try {
+    return (await stat(join(root, "apps/fe"))).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function printFeNextSteps(displayPath: string): void {
   if (displayPath !== ".") {
     console.log(`  cd ${displayPath}`);
   }
@@ -430,9 +438,10 @@ async function runCreate(args: string[]): Promise<void> {
   await assertCreatable(root);
 
   const name = projectNameFromPath(root);
+  const organizationId = await resolveOrganization(parsed.orgId);
   const project = await authed<Project>("/v1/projects", {
     method: "POST",
-    body: JSON.stringify({ name }),
+    body: JSON.stringify(organizationId ? { name, organizationId } : { name }),
   });
 
   const { treeRoot } = await resolveStarterTree();
@@ -464,7 +473,7 @@ async function runCreate(args: string[]): Promise<void> {
         "npm install failed. Copy the API URL printed above into Lovable, Bolt, or v0 as VITE_API_URL.",
       );
       console.log("https://robodev.povio.dev/docs/frontend");
-    } else if (starter.id === "space") {
+    } else if (await hasAppsFe(root)) {
       console.log("Run `npm install` in the project folder.");
       console.log("bun is required for apps/fe. APIs are already deployed.");
     } else {
@@ -476,11 +485,11 @@ async function runCreate(args: string[]): Promise<void> {
   const displayPath = relative(process.cwd(), root) || ".";
   console.log("");
   console.log("Next:");
-  if (starter.id === "space") {
+  if (await hasAppsFe(root)) {
     if (!(await bunAvailable())) {
       console.log("bun is required for apps/fe. APIs are already deployed.");
     }
-    printSpaceNextSteps(displayPath);
+    printFeNextSteps(displayPath);
   } else if (starter.kind === "backend") {
     if (displayPath !== ".") {
       console.log(`  cd ${displayPath}`);

package/src/parse-create-args.test.ts

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { parseCreateArgs } from "./parse-create-args.js";
+
+test("parseCreateArgs accepts --org with starter flags", () => {
+  assert.deepEqual(parseCreateArgs(["app", "--starter", "space", "--org", "org_1"]), {
+    path: "app",
+    starterId: "space",
+    orgId: "org_1",
+  });
+  assert.deepEqual(parseCreateArgs(["--empty", "--org=org_2"]), {
+    path: undefined,
+    starterId: "empty",
+    orgId: "org_2",
+  });
+});
+
+test("parseCreateArgs rejects a missing --org value", () => {
+  assert.throws(() => parseCreateArgs(["--org"]), /Missing value for --org/);
+  assert.throws(() => parseCreateArgs(["--org="]), /Missing value for --org/);
+  assert.throws(() => parseCreateArgs(["--org", "--empty"]), /Missing value for --org/);
+});
+
+test("parseCreateArgs rejects unknown flags including --organization", () => {
+  assert.throws(() => parseCreateArgs(["--organization", "org_1"]), /Unknown flag --organization/);
+});

package/src/parse-create-args.ts

@@ -0,0 +1,63 @@
+export type CreateArgs = { path?: string; starterId?: string; orgId?: string };
+
+export function parseCreateArgs(args: string[]): CreateArgs {
+  let path: string | undefined;
+  let starterId: string | undefined;
+  let orgId: string | undefined;
+  let empty = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--empty") {
+      empty = true;
+      continue;
+    }
+    if (arg === "--starter") {
+      const value = args[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --starter");
+      }
+      starterId = value;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--starter=")) {
+      const value = arg.slice("--starter=".length);
+      if (!value) {
+        throw new Error("Missing value for --starter");
+      }
+      starterId = value;
+      continue;
+    }
+    if (arg === "--org") {
+      const value = args[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --org");
+      }
+      orgId = value;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--org=")) {
+      const value = arg.slice("--org=".length);
+      if (!value) {
+        throw new Error("Missing value for --org");
+      }
+      orgId = value;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown flag ${arg}`);
+    }
+    if (path !== undefined) {
+      throw new Error(`Unexpected argument ${arg}`);
+    }
+    path = arg;
+  }
+  if (empty && starterId !== undefined) {
+    throw new Error("Use either --empty or --starter, not both.");
+  }
+  if (empty) {
+    starterId = "empty";
+  }
+  return { path, starterId, orgId };
+}

package/templates/auth-chat/.config/local.spa.template.yml

@@ -0,0 +1,27 @@
+STAGE: "local"
+OUTPUT: "export"
+
+ANALYZE: "false"
+NEXT_TELEMETRY_DISABLED: "1"
+
+VITE_PUBLIC_RELEASE: ${env:RELEASE}
+VITE_PUBLIC_STAGE: ${func:stage}
+
+APP_PUBLIC_API_URL: &APP_PUBLIC_API_URL "http://localhost:4000"
+APP_PUBLIC_API_MODE: &APP_PUBLIC_API_MODE "real"
+VITE_PUBLIC_API_URL: *APP_PUBLIC_API_URL
+VITE_PUBLIC_API_MODE: *APP_PUBLIC_API_MODE
+
+VITE_PUBLIC_LOG_LEVEL: "trace"
+
+VITE_PUBLIC_SENTRY_DSN: ""
+VITE_PUBLIC_SENTRY_ENVIRONMENT: ${func:stage}
+VITE_PUBLIC_SENTRY_TRACES_SAMPLE_RATE: "0"
+VITE_PUBLIC_SENTRY_REPLAYS_SESSION_SAMPLE_RATE: "0"
+VITE_PUBLIC_SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE: "0"
+
+VITE_PUBLIC_AUTH_CUSTOM_JWT_ENABLE_MAGIC_LINK: "true"
+
+VITE_PUBLIC_GOOGLE_ANALYTICS_MEASUREMENT_ID: ""
+
+VITE_DEV_PORT: "3000"

package/templates/auth-chat/.oxlint-base.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "apps/fe/node_modules/oxlint/configuration_schema.json",
+  "plugins": ["eslint", "typescript", "unicorn", "import", "oxc", "promise", "vitest"],
+  "categories": {
+    "correctness": "error",
+    "perf": "error",
+    "pedantic": "off",
+    "style": "off",
+    "restriction": "off",
+    "suspicious": "off",
+    "nursery": "off"
+  },
+  "env": {
+    "builtin": true,
+    "node": true,
+    "shared-node-browser": true
+  },
+  "rules": {
+    "eslint/eqeqeq": [
+      "error",
+      "always",
+      {
+        "null": "ignore"
+      }
+    ],
+    "typescript/no-floating-promises": "off",
+    "eslint/capitalized-comments": "off"
+  }
+}

package/templates/auth-chat/.oxlintrc.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "apps/fe/node_modules/oxlint/configuration_schema.json",
+  "extends": [".oxlint-base.json"],
+  "plugins": [
+    "eslint",
+    "typescript",
+    "unicorn",
+    "import",
+    "vitest",
+    "react",
+    "react-perf",
+    "jsx-a11y"
+  ],
+  "categories": {
+    "style": "error"
+  },
+  "ignorePatterns": [
+    "openapi-codegen.config.ts",
+    "postcss.config.js",
+    "out",
+    "dist",
+    "public",
+    "scripts",
+    ".vscode",
+    ".turbo",
+    "node_modules",
+    "apps/fe/src/routeTree.gen.ts",
+    "apps/fe/src/openapi",
+    "apps/fe/public"
+  ],
+  "overrides": [
+    {
+      "files": ["vite-plugin-*.ts", "apps/fe/vite-plugin-*.ts"],
+      "rules": {
+        "import/no-nodejs-modules": "off"
+      }
+    }
+  ],
+  "rules": {
+    "eslint/no-implicit-coercion": "off",
+    "no-map-spread": "off",
+    "eslint/sort-keys": "off",
+    "eslint/sort-imports": "off",
+    "eslint/no-ternary": "off",
+    "eslint/id-length": "off",
+    "eslint/no-magic-numbers": "off",
+    "eslint/arrow-body-style": "off",
+    "eslint/max-params": "off",
+    "eslint/func-style": "off",
+    "eslint/new-cap": "off",
+    "eslint/no-continue": "off",
+    "eslint/max-statements": "off",
+    "eslint/no-duplicate-imports": [
+      "error",
+      {
+        "allowSeparateTypeImports": true
+      }
+    ],
+    "react/exhaustive-deps": "off",
+    "react/jsx-props-no-spreading": "off",
+    "react/jsx-max-depth": "off",
+    "react-perf/jsx-no-new-object-as-prop": "off",
+    "react-perf/jsx-no-new-function-as-prop": "off",
+    "react-perf/jsx-no-new-array-as-prop": "off",
+    "react-perf/jsx-no-jsx-as-prop": "off",
+    "typescript/no-empty-interface": "off",
+    "import/no-named-export": "off",
+    "import/group-exports": "off",
+    "import/prefer-default-export": "off",
+    "import/exports-last": "off",
+    "import/consistent-type-specifier-style": "off",
+    "jest/require-hook": "off",
+    "unicorn/filename-case": "off",
+    "unicorn/prefer-global-this": "off",
+    "unicorn/no-await-expression-member": "off",
+    "unicorn/no-null": "off"
+  }
+}

package/templates/auth-chat/.rulesync/rules/frontend-api-boundary.md

@@ -0,0 +1,36 @@
+---
+root: false
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Frontend must consume generated OpenAPI queries and models, not backend internals."
+globs: ["apps/fe/src/**/*.{ts,tsx}"]
+cursor:
+  alwaysApply: false
+  description: "Apply when editing frontend components, hooks, providers, pages, or clients that call the API."
+  globs: ["apps/fe/src/**/*.{ts,tsx}"]
+---
+
+# Frontend API Boundary
+
+Frontend application code must consume the API through generated files in `apps/fe/src/openapi`.
+
+Use generated modules such as:
+
+- `@/openapi/<domain>/<domain>.queries`
+- `@/openapi/<domain>/<domain>.models`
+- `@/openapi/queryModules`
+
+For generated mutations, pass invalidation through the mutation options instead of importing `queryClient` or calling `invalidateQueries` with generated query keys. The current module is invalidated by default through `invalidateCurrentModule: true`; invalidate dependent modules explicitly with `invalidateModules: [QueryModule.someModule]`.
+
+After mutations, derive follow-up UI state from canonical API response or query state instead of leaving action controls unchanged. Disable duplicate submissions when the API state already represents a pending or completed action, and surface mutation errors through the default generated-client error handler or a feature-specific message.
+
+Do not import `@robodev-ai/sdk`, `database.ts`, Drizzle tables, or API helper modules into frontend features.
+
+`apps/fe/src/openapi` is generated by `@povio/openapi-codegen-cli` from root `openapi.json` (or a live project `/openapi.json` when `OPENAPI_LIVE=true`). Do not hand-edit generated OpenAPI client files.
+
+When API contracts change:
+
+1. Update `api/` handlers and `openapi.json` if the documented contract changed.
+2. Run `bun openapi:gen` from `apps/fe`.
+3. Update frontend code to use the regenerated queries and models.
+
+Point `VITE_PUBLIC_API_URL` at the Starbase project host origin only. Do not append `/api`.

package/templates/auth-chat/.rulesync/rules/frontend-component-structure.md

@@ -0,0 +1,38 @@
+---
+root: false
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Frontend component extraction and feature subcomponent structure conventions."
+globs: ["apps/fe/src/**/*.{ts,tsx}"]
+cursor:
+  alwaysApply: false
+  description: "Apply when organizing frontend feature components, page sections, mapped items, or reusable UI."
+  globs: ["apps/fe/src/**/*.{ts,tsx}"]
+---
+
+# Frontend Component Structure
+
+Extract repeatable UI into subcomponents. Every named React component should live in its own file, even when it is currently used only once. Keep the component file near the feature, layout, page, or shared UI area that owns it.
+
+Extract large or complex sections of pages into named components so route and page components stay readable. Anything mapped from an array should usually be a component, such as cards, table row actions, repeated sections, or list items.
+
+The planets feature is the reference example while the template is still a prototype:
+
+- `PlanetCard` for mapped grid cards.
+- `PlanetsFilters` for shared filter controls.
+- `PlanetsTableActions` for repeated row actions.
+- `PlanetsTable` and `PlanetsTableInfinite` for table wrappers.
+- `PlanetDetailsPage` and `PlanetEditPage` for large route-owned views.
+
+When implementing a real app, remove the planets and aliens links from app navigation such as `apps/fe/src/components/layout/AppHeader.tsx` so these examples are not directly accessible in the product UI, but keep the example implementation available as a reference unless the team intentionally deletes the demo layer.
+
+Route files should own routing, document metadata, and route data boundaries. Feature components should own the page UI and interaction details.
+
+Exception: route-local wrappers such as `PageComponent` or layout guard components may stay in route files when they only connect routing primitives to feature components.
+
+## Shared Utilities
+
+Keep generic formatting, parsing, calculation, and data-shaping helpers in `apps/fe/src/utils/*.utils.ts` files instead of defining them inside component files. Export helpers through namespaces such as `DateUtils.formatDate(...)` or `NumberUtils.formatInteger(...)` so call sites stay explicit and related helpers stay grouped.
+
+Component files may keep UI-local glue helpers only when the logic is tightly coupled to that component's JSX, such as adapting one component's prop shape or handling a local event. If the helper describes dates, numbers, arrays, strings, IDs, or other domain-neutral data, move it into a shared utility file.
+
+For apps with multiple user roles that require distinct UI or business workflows, also apply the role-based app structure rule.

package/templates/auth-chat/.rulesync/rules/frontend-forms.md

@@ -0,0 +1,32 @@
+---
+root: false
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Frontend form patterns with Povio UI useForm, generated schemas, and formControl wiring."
+globs: ["apps/fe/src/**/*.{ts,tsx}"]
+cursor:
+  alwaysApply: false
+  description: "Apply when building or changing frontend forms, modals, edit pages, or input components."
+  globs: ["apps/fe/src/**/*.{ts,tsx}"]
+---
+
+# Frontend Forms
+
+Use `useForm` and form-aware inputs from `@povio/ui/tanstack` with generated OpenAPI Zod schemas for API-backed forms. The planets feature is the reference example while the template is still a prototype:
+
+- Create form: `apps/fe/src/components/features/planets/list/PlanetCreateModal.tsx`
+- Edit form: `apps/fe/src/components/features/planets/details/PlanetEditPage.tsx`
+
+Prefer this shape:
+
+```tsx
+const form = useForm({
+  zodSchema: PlanetsModels.PlanetsCreateInputSchema,
+  defaultValues: { name: "" },
+});
+```
+
+Pass form state into Povio UI inputs with `field={{ form, name: "fieldName" }}`. Use `form.handleSubmit`, `form.reset`, and `form.setFieldValue` for form actions, and `useFormValue(form, selector)` for reactive field reads.
+
+Avoid local `useState`, custom `value`, and custom `onChange` plumbing for fields that belong to the form. Use TanStack Form's `form.Field` adapter only when a component cannot accept the Povio UI `field` binding.
+
+Use generated OpenAPI queries and mutations for submit handlers. Keep toast feedback and navigation close to the feature interaction that owns them.

package/templates/auth-chat/.rulesync/rules/frontend-notifications.md

@@ -0,0 +1,24 @@
+---
+root: false
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Frontend notification inbox, preferences, push permission, service worker, and token registration boundaries."
+globs: ["apps/fe/src/**/*.{ts,tsx}", "apps/fe/public/**/*.{js,ts}"]
+cursor:
+  alwaysApply: false
+  description: "Apply when frontend work handles notifications, push permission, service workers, push tokens, unread counts, or notification preferences."
+  globs: ["apps/fe/src/**/*.{ts,tsx}", "apps/fe/public/**/*.{js,ts}"]
+---
+
+# Frontend Notifications
+
+Use generated `@/openapi` queries, mutations, and models for notification history, preferences, and push-token registration. Do not import `@robodev-ai/sdk` or `database.ts` into frontend feature code.
+
+Request push permission only after an explanatory UI and explicit user gesture. Never request it automatically during initial application load. Handle unsupported, default, denied, granted, registered, expired, and failed-registration states.
+
+Register the service worker and provider subscription through a small browser integration, then persist the token/subscription through the generated authenticated user API. Clean up or detach the current device registration on logout when required by the security model.
+
+Keep push payloads minimal and privacy-safe. Validate internal deep links before navigation. Never depend on push as the only record of an important event; provide a paginated in-app notification list and unread state.
+
+Use generated mutation invalidation options for unread counts, mark-read actions, preferences, and token changes. Do not access the query client directly for generated API state.
+
+Use `@povio/ui` for permission prompts, notification lists, menus/popovers, tags, forms, confirmations, and toasts. Use `povio-ui-styling` for styling-layer decisions.

package/templates/auth-chat/.rulesync/rules/frontend-povio-components.md

@@ -0,0 +1,42 @@
+---
+root: false
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Frontend interactive controls and typography must use Povio UI primitives instead of native replacements."
+globs: ["apps/fe/src/**/*.{ts,tsx}"]
+cursor:
+  alwaysApply: false
+  description: "Apply when creating or editing React components, controls, forms, tables, overlays, or user-facing text."
+  globs: ["apps/fe/src/**/*.{ts,tsx}"]
+---
+
+# Use Povio UI Components
+
+Use a component from `@povio/ui` whenever it provides the required primitive. Do not recreate an available Povio component with a native element plus Tailwind or custom CSS.
+
+Required replacements include:
+
+- `Button`, `TextButton`, or the appropriate Povio action component instead of a styled `<button>`.
+- `TextInput`, `PasswordInput`, `TextArea`, checkbox, radio, select, autocomplete, and other Povio form controls instead of native form controls.
+- `Typography` instead of directly styling user-facing headings, paragraphs, labels, or spans.
+- `Table` or `InfiniteTable` instead of a hand-built native data table.
+- `Modal`, `Confirmation`, `Drawer`, `BottomSheet`, `Menu`, `Tooltip`, or `ResponsivePopover` instead of custom overlay primitives.
+- `FileUpload` instead of a directly exposed file input.
+- Povio hooks such as `useForm` and `useToast` instead of parallel custom infrastructure.
+
+Before creating a control:
+
+1. Search `@povio/ui` usage in the repository.
+2. Inspect existing feature components for the same primitive.
+3. Use the existing Povio props and variants.
+4. Apply the `povio-ui-styling` skill when choosing between local Tailwind, `UIConfig`, `UIOverrides`, a shared wrapper, or scoped CSS.
+
+Native semantic and structural elements such as `<main>`, `<section>`, `<article>`, `<nav>`, `<form>`, `<div>`, and list elements remain appropriate for document structure and layout. Use TanStack Router navigation primitives for routing. This rule prohibits native replacements for available Povio UI behavior; it does not prohibit semantic HTML.
+
+If Povio UI has no suitable primitive:
+
+- Compose existing Povio components first.
+- Put a reusable project-specific primitive under `apps/fe/src/components/shared/ui`.
+- Preserve keyboard behavior, focus visibility, accessible names, disabled state, validation state, and loading state.
+- Keep the exception narrow; do not introduce another general-purpose UI library.
+
+When touching an existing native control that has a Povio equivalent, migrate it when the change is safely within scope. Do not expand a narrowly requested fix into a broad unrelated rewrite.

package/templates/auth-chat/.rulesync/rules/frontend-povio-ui.md

@@ -0,0 +1,45 @@
+---
+root: false
+targets: ["claudecode", "codexcli", "cursor"]
+description: "Frontend UI uses Povio UI primitives first and semantic Tailwind tokens."
+globs: ["apps/fe/src/**/*.{ts,tsx,css}"]
+cursor:
+  alwaysApply: false
+  description: "Apply when editing frontend UI, styling, layout, components, or CSS."
+  globs: ["apps/fe/src/**/*.{ts,tsx,css}"]
+---
+
+# Frontend UI
+
+## Use `@povio/ui` First
+
+Always use components and hooks from `@povio/ui` when a suitable primitive exists, including `Button`, `Typography`, `Table`, `Modal`, `Confirmation`, `TextButton`, `TextInput`, `TextArea`, `PasswordInput`, `FileUpload`, `useForm`, `useToast`, and `Tag`.
+
+Create project-specific UI only when `@povio/ui` does not provide the needed primitive. Shared custom primitives live under `apps/fe/src/components/shared/ui`.
+
+Feature components should compose existing layout and shared primitives such as `PageHeader`, `BackHeader`, `LoadingState`, `ErrorText`, and `Card` before introducing new wrappers.
+
+When implementing a real app, remove the demo planets and aliens links from app navigation such as `apps/fe/src/components/layout/app-header/AppHeader.tsx` so they are not directly accessible in the product UI, but keep the example code available as a reference unless the team intentionally deletes the demo layer.
+
+## Tailwind Tokens
+
+The default Tailwind color palette is removed in `apps/fe/src/styles/base.css`. Do not use default color utilities such as:
+
+- `text-red-500`
+- `bg-blue-600`
+- `border-gray-200`
+- `ring-emerald-400`
+
+Use semantic tokens exported from Figma in `apps/fe/src/styles/theme.css` and exposed through Tailwind, for example:
+
+- Surface, fill, and outline: `bg-elevation-fill-default-1`, `border-elevation-outline-default-1`
+- Text: `text-text-default-1`, `text-text-default-2`, `text-text-error-1`
+- Interactive: `bg-interactive-contained-primary-idle`, `hover:bg-interactive-contained-primary-hover`
+
+Do not manually edit `apps/fe/src/styles/theme.css`; it is exported from Figma. If a hand-written semantic token or Tailwind theme mapping is needed, add it only in `apps/fe/src/styles/base.css` before referencing it from JSX or CSS.
+
+## Forms And API Data
+
+For forms backed by API requests, prefer generated OpenAPI model schemas with `@povio/ui` `useForm`, for example `useForm({ zodSchema: UserModels.UpdateProfileBodySchema })`.
+
+Use generated OpenAPI queries and mutations for all API state. Keep API side effects, toast feedback, loading states, and query invalidation close to the feature that owns the interaction. For mutation invalidation, pass generated mutation options such as `invalidateModules`; do not import `queryClient` into feature code for generated API queries.