@donotdev/cli 0.0.13 → 0.0.15

package/templates/root-consumer/GEMINI.md.example

@@ -0,0 +1 @@
+Enforce AI.md

package/templates/root-consumer/firebase.json.example

@@ -314,7 +314,7 @@
         "**/*.test.ts",
         "**/__tests__/**"
       ],
-      "runtime": "nodejs20"
+      "runtime": "nodejs22"
     }
   ],
   "firestore": {

package/templates/root-consumer/guides/dndev/AGENT_START_HERE.md.example

@@ -9,6 +9,26 @@
 
 ---
 
+## Getting Started (for humans)
+
+**Canonical flow:** The showcase app’s **Get Started** page is the single source of truth: `apps/showcase/src/pages/GetStartedPage.tsx` and `apps/showcase/src/pages/locales/getstarted_*.json`. Below is the same flow in short form.
+
+1. **P0 — Prerequisites**
+   - **Runtime:** **Node.js 24** (nodejs.org) and **Bun 1.3+** (bun.sh). Both required.
+   - **IDE:** Any IDE (Cursor, VS Code, Windsurf, etc.). Need help? Use the collapsible “Need help setting up?” on the Get Started page.
+2. **Install our CLI and create your project’s monorepo**
+   - `npm install -g @donotdev/cli`
+   - `dndev init my-app`
+3. **Open the repo in your IDE, terminal, bun install**
+   - Start your IDE in that repo, open the terminal: `cd my-app` → `bun install`
+4. **Enable MCP, then read AI.md and follow the flow**
+   - Talk with your agent; ask it to load the MCP (Cursor: Ctrl+Shift+P → “MCP Server” → enable “donotdev”; other IDEs: see “How to enable MCP” collapsible on the Get Started page).
+   - Then have the agent read the root **`AI.md`** and this file (**`guides/dndev/AGENT_START_HERE.md`**). Follow the phases.
+5. **AI helps with provider; cd there, bun install, run**
+   - AI helps you choose and set up your provider (Firebase, Supabase, or custom). Then `cd` into the app directory if needed, `bun install`, and `dndev dev` / `dndev build` / `dndev deploy`.
+
+---
+
 ## First Thing to Call: list_features()
 
 Call **`list_features()`** before designing or coding. It lists all framework packages with a one-line summary from each README (templates, core, ui, auth, billing, etc.). Use it so you don't reinvent what the framework already provides (blog, CRUD, billing, legal pages, etc.).
@@ -63,4 +83,38 @@ Check that the user has completed environment setup:
 
 If not, coach them: "Run `dndev firebase:setup` first, then follow the prompts." See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md).
 
+---
+
+## Project Args (`.dndev/args.json`)
+
+Generated by `dndev init`. All features ON by default — Phase 0 narrows down based on what the user actually needs.
+
+```json
+{
+  "platform": "firebase",
+  "strictness": "enforced",
+  "features": ["crud", "auth", "i18n", "billing", "oauth", "functions"],
+  "region": "europe-west1"
+}
+```
+
+| Field | Values | Effect |
+|-------|--------|--------|
+| `platform` | `firebase`, `vercel` | Derived from builder choice |
+| `strictness` | `enforced`, `warnings`, `permissive` | `enforced` = blocks `complete_phase` on convention violations. `warnings` = reports but allows. `permissive` = skips checks. |
+| `features` | `crud`, `auth`, `i18n`, `billing`, `oauth`, `functions` | Filters gotchas — remove features the project doesn't use to reduce noise |
+| `region` | any GCP region | Informational, shown in `start_phase` context |
+
+`start_phase()` returns project args + phase-relevant gotchas automatically. `complete_phase()` respects `strictness`.
+
+**Without MCP:** `args.json` and `GOTCHAS.md` are plain files. Any agent can read them directly.
+
+---
+
+## Gotchas (`guides/dndev/GOTCHAS.md`)
+
+Common mistakes, phase-tagged. `start_phase(N)` automatically filters and returns only the gotchas relevant to phase N and your enabled features. Read the full file for reference: [GOTCHAS.md](../guides/dndev/GOTCHAS.md).
+
+---
+
 **Starting:** Call `list_features()` first, then `get_phase_status()` to see where you are, then `start_phase(0)` to begin.

package/templates/root-consumer/guides/dndev/COMPONENTS_ADV.md.example

@@ -335,24 +335,6 @@ import { StartChallengeForm } from '@donotdev/adv-comps';
 />
 ```
 
-### Waterfall
-
-Waterfall component with lazy loading built-in. Features clean cascade layout with diagonal staircase effect, perfect for step-by-step processes or feature showcases.
-
-```tsx
-import { Waterfall } from '@donotdev/adv-comps';
-import type { WaterfallProps } from '@donotdev/adv-comps';
-
-<Waterfall
-  items: ComponentData[]
-  className?: string
-  connectorClassName?: string
-  density?: 'compact' | 'comfortable'
-  ariaLabel?: string
-  direction?: 'horizontal' | 'descending'
-/>
-```
-
 ## Notes
 
 - All components are lazy-loaded by default for optimal performance

package/templates/root-consumer/guides/dndev/COMPONENTS_UI.md.example

@@ -83,7 +83,7 @@
 - **usePrefetch** - Prefetch route data.
 - **useLocation** - Get current location.
 - **useParams** - Get route parameters.
-- **useSearchParams** - Get URL search parameters.
+- **useSearchParams** - Get URL search parameters. Returns `URLSearchParams` directly (NOT a tuple). Use `.get('key')` to read values.
 - **useMatch** - Match current route pattern.
 - **useQueryParams** - Get and set query parameters.
 - **useRedirectGuard** - Guard against redirects.

package/templates/root-consumer/guides/dndev/ENV_SETUP.md.example

@@ -2,16 +2,20 @@
 
 **The complete onboarding flow — from `dndev init` to deployed app.**
 
+If you haven’t run `dndev init` yet, see [AGENT_START_HERE.md](./AGENT_START_HERE.md) § **Getting started (for humans)** (P0 → Install CLI → Run AI.md → Enjoy).
+
 ---
 
 ## The Flow
 
 ```
-bun install                    → install dependencies
-bun dev                        → start app, read the homepage setup guide
-dndev firebase:setup           → configure Firebase project + .env
-dndev emu start                → test locally with emulators
-dndev deploy                   → deploy to production
+bun install                    -> install dependencies
+bun dev                        -> start app, read the homepage setup guide
+dndev firebase:setup           -> configure Firebase project + .env
+  -- or --
+dndev supabase:setup           -> configure Supabase project + .env
+dndev emu start                -> test locally with emulators (Firebase)
+dndev deploy                   -> deploy to production
 ```
 
 ---
@@ -43,29 +47,45 @@ git push -u origin main
 
 ---
 
-## Step 3: Firebase
+## Step 3: Backend Setup
+
+### Firebase
 
 ```bash
 dndev firebase:setup
 ```
 
-Automates: project selection/creation, web app, SDK config → `.env`, `.firebaserc`.
+Automates: project selection/creation, web app, SDK config -> `.env`, `.firebaserc`.
 
 Then 2 manual steps (CLI gives you direct links):
-1. Download service account key → save as `service-account-key.json`
+1. Download service account key -> save as `service-account-key.json`
 2. Enable Auth + Firestore in Firebase Console
 
 See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md) for full details.
 
+### Supabase
+
+```bash
+dndev supabase:setup
+```
+
+Asks for your **public** project URL and anon key (both safe to share -- shipped in client bundle).
+
+Get them from: https://supabase.com/dashboard -> your project -> Settings -> API
+
+See [SETUP_SUPABASE.md](./SETUP_SUPABASE.md) for full details (tables, RLS, `dn generate sql`). See [Secrets Philosophy](#secrets-philosophy) for how we handle secret keys.
+
 ---
 
 ## Step 4: Test Locally
 
 ```bash
-dndev emu start
+dndev emu start          # Firebase emulators
 ```
 
-Select Auth + Firestore + Functions. Develops against local emulators.
+Select services: Auth + Firestore + Functions. This starts Firebase emulators so you can develop without touching production.
+
+For Supabase, development runs against your Supabase project directly (or use `supabase start` for local Supabase if installed).
 
 ---
 
@@ -74,11 +94,11 @@ Select Auth + Firestore + Functions. Develops against local emulators.
 Open the project in **Cursor**, **Claude Code**, **Windsurf**, or **AntiGravity**.
 
 The AI reads `AI.md` and follows the WAI-WAY protocol:
-- Phase 0: Brainstorm → produce a spec
-- Phase 1: Scaffold → create pages
-- Phase 2: Entities → define data models
-- Phase 3: Compose → build pages with components
-- Phase 4: Configure → generate tests, firestore rules, CI/CD
+- Phase 0: Brainstorm -> produce a spec
+- Phase 1: Scaffold -> create pages
+- Phase 2: Entities -> define data models
+- Phase 3: Compose -> build pages with components
+- Phase 4: Configure -> generate tests, firestore rules, CI/CD
 
 Read `guides/wai-way/WAI_WAY_CLI.md` for the full workflow.
 
@@ -90,7 +110,51 @@ Read `guides/wai-way/WAI_WAY_CLI.md` for the full workflow.
 dndev deploy
 ```
 
-Deploys hosting + functions + rules. Cloud Run IAM handled automatically.
+Deploys hosting + functions + rules. Syncs runtime secrets automatically before deploying functions.
+
+---
+
+## Secrets Philosophy
+
+**DoNotDev follows strict rules about credentials:**
+
+### Tier 1: Public Keys -- We Ask Directly
+
+These are safe to share, shipped in your client JS bundle. We ask for them during setup.
+
+| Key | Where It Goes |
+|-----|--------------|
+| Firebase API key, project ID, auth domain, etc. | `apps/<app>/.env` as `VITE_FIREBASE_*` |
+| Supabase project URL | `apps/<app>/.env` as `VITE_SUPABASE_URL` |
+| Supabase anon key (public JWT) | `apps/<app>/.env` as `VITE_SUPABASE_ANON_KEY` |
+| Stripe publishable key | `apps/<app>/.env` as `VITE_STRIPE_PUBLISHABLE_KEY` |
+
+### Tier 2: Secret Keys -- We NEVER Ask, We Tell You Where To Put Them
+
+These are server-side only. We never prompt for them, never store them in client code.
+
+| Key | Where It Goes | How To Get It |
+|-----|--------------|---------------|
+| Stripe secret key | `functions/.env` as `STRIPE_SECRET_KEY` | https://dashboard.stripe.com/apikeys |
+| Stripe webhook secret | `functions/.env` as `STRIPE_WEBHOOK_SECRET` | Stripe Dashboard -> Webhooks |
+| Supabase service_role key | `functions/.env` as `SUPABASE_SERVICE_ROLE_KEY` | Supabase Dashboard -> Settings -> API |
+| OAuth client secrets | `functions/.env` as `*_CLIENT_SECRET` | Provider dashboard |
+
+Then sync to your runtime:
+
+```bash
+dndev sync-secrets                    # -> Firebase Secret Manager or Vercel env
+dndev sync-secrets --target github    # -> GitHub Secrets (for CI/CD)
+```
+
+### Tier 3: Service Account Files -- Download, Place, Gitignore
+
+| File | Where It Goes | How To Get It |
+|------|--------------|---------------|
+| `service-account-key.json` | App root (next to firebase.json) | Firebase Console -> Settings -> Service Accounts |
+| `service-account-key.staging.json` | Same location, for staging | Same, from staging project |
+
+These files are `.gitignored`. Never commit them. For CI/CD, upload the file content as a GitHub Secret and decode it in your workflow.
 
 ---
 
@@ -100,18 +164,21 @@ Deploys hosting + functions + rules. Cloud Run IAM handled automatically.
 
 ```
 my-project/
-├── .env.example              ← NOT loaded by Vite (reference only)
-├── apps/
-│   └── my-app/
-│       ├── .env              ← Vite reads THIS
-│       ├── .env.local        ← Overrides .env (gitignored)
-│       ├── .env.staging      ← Used by dndev staging
-│       └── .env.production   ← Production overrides
-└── functions/
-    └── .env                  ← Server secrets (Stripe, OAuth)
++-- .env.example              <-- NOT loaded by Vite (reference only)
++-- apps/
+|   +-- my-app/
+|       +-- .env              <-- Vite reads THIS (public keys: VITE_*)
+|       +-- .env.local        <-- Overrides .env (gitignored)
+|       +-- .env.staging      <-- Used by dndev staging
+|       +-- .env.production   <-- Production overrides
++-- functions/
+    +-- .env                  <-- Server secrets (Stripe, OAuth, service_role)
 ```
 
-**Rule:** `VITE_*` vars go in `apps/<app>/.env`. Server secrets go in `functions/.env`.
+**Rules:**
+- `VITE_*` / `NEXT_PUBLIC_*` vars -> `apps/<app>/.env` (public, shipped to browser)
+- Server secrets -> `functions/.env` (never exposed to client)
+- Service account files -> app root, gitignored
 
 ---
 
@@ -122,9 +189,11 @@ my-project/
 | `bun dev` | Start dev server |
 | `dndev emu start` | Start Firebase emulators |
 | `dndev firebase:setup` | Configure Firebase project + .env |
-| `dndev deploy` | Deploy to Firebase (hosting + functions + rules) |
+| `dndev supabase:setup` | Configure Supabase project + .env |
+| `dndev deploy` | **Firebase:** hosting + functions + rules. **Supabase:** deploys frontend to [Vercel](https://vercel.com) (via scaffolded vercel.json) and Edge Functions to Supabase. Set `VITE_SUPABASE_*` in Vercel project env. |
 | `dndev staging` | Deploy to staging environment |
-| `dndev sync-secrets` | Push functions/.env to Firebase Secret Manager |
+| `dndev sync-secrets` | Push functions/.env to runtime (Firebase/Vercel) |
+| `dndev sync-secrets --target github` | Push secrets to GitHub Secrets (CI/CD) |
 | `bun test` | Run tests (after Phase 4) |
 | `bun run type-check` | TypeScript validation |
 
@@ -135,8 +204,8 @@ my-project/
 | Feature | Required? | When to Set Up |
 |---------|-----------|---------------|
 | Git + GitHub | Recommended | Before starting development |
-| Firebase (Auth + Firestore) | Yes | Before building any features |
-| Cloud Functions | If using backend | Before deploying functions |
+| Firebase or Supabase | Yes (pick one) | Before building any features |
+| Cloud Functions | If using server logic | Before deploying functions |
 | Stripe | If using billing | When adding payment features |
 | GitHub Actions CI/CD | Optional | Phase 4 generates the workflow |
 | Staging environment | Optional | When you want a test environment |

package/templates/root-consumer/guides/dndev/GOTCHAS.md.example

@@ -0,0 +1,186 @@
+# Framework Gotchas
+
+**Common mistakes. Read before coding. Phase tags show when each matters most.**
+
+---
+
+## Imports [Phase 1, 2, 3]
+
+**Server code MUST use `/server` imports — client imports crash on deploy.**
+
+```typescript
+// ✅ CORRECT
+import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
+import { handleError } from '@donotdev/core/server';
+
+// ❌ WRONG - crashes on deploy
+import { getFirestore } from '@donotdev/firebase';
+import { handleError } from '@donotdev/core';
+```
+
+**Rule:** Always use `/server` suffix for `@donotdev/firebase/server`, `@donotdev/core/server`, `@donotdev/utils/server`.
+
+**ESM only — never use `require()`.**
+
+```typescript
+// ❌ WRONG
+const { something } = require('@donotdev/package');
+
+// ✅ CORRECT
+import { something } from '@donotdev/package';
+```
+
+**Import ordering is mandatory:**
+1. React (values, then types)
+2. Other vendors (values, then types)
+3. `@donotdev/*` packages (values, then types)
+4. Relative imports (values, then types)
+
+One line for values, one line for types. Blank line between categories.
+
+---
+
+## Routing [Phase 1, 3]
+
+**Never import from `react-router-dom` — use framework routing.**
+
+```tsx
+// ❌ WRONG - breaks framework features
+import { Link, useNavigate, useParams } from 'react-router-dom';
+
+// ✅ CORRECT
+import { Link, useNavigate, useParams } from '@donotdev/ui/routing';
+```
+
+**Routes are auto-discovered** from `src/pages/*Page.tsx` with `pageMeta`. Don't use `<Routes>`, `<Route>`, or manual `<Outlet />`.
+
+**Use `useRouteParam('id')` for typed route params** — not `useParams()` from react-router-dom.
+
+**Navigation is auto-built.** Use `<DnDevNavigationMenu>` or `useNavigationItems()`. Don't build nav manually — you lose auth filtering and route discovery.
+
+---
+
+## Styling [Phase 3, 4]
+
+**No inline `fontSize` or `font-size` — use `Text` level prop.**
+
+```tsx
+// ❌ WRONG
+<Text style={{ fontSize: '18px' }}>Title</Text>
+
+// ✅ CORRECT
+<Text level="h2">Title</Text>
+```
+
+Levels: `h1`, `h2`, `h3`, `h4`, `body`, `small`, `caption`. Limit to 2–3 levels per page.
+
+**RTL: Always use `start`/`end` — never `left`/`right`.**
+
+```css
+/* ❌ WRONG - breaks RTL */
+text-align: left;
+
+/* ✅ CORRECT - works in both LTR and RTL */
+text-align: start;
+```
+
+Same for inline styles: `textAlign: 'start'` not `textAlign: 'left'`. Same for data attributes: `data-text-align="start|center|end"`.
+
+---
+
+## Components [Phase 3]
+
+**Always `lookup_symbol` before using any `@donotdev` component.** Never guess props.
+
+Common wrong props:
+- `Button`: no `size`, `tone`, `gap` — use `variant`, `display`
+- `Text`: no `size`, `tone`, `color` — use `level`, `variant`
+- `Stack`: no `spacing`, `size` — use `gap`
+- `Card`: no `padding`, `margin`, `size` — use `title`, `subtitle`, `content`, `footer`
+- `Grid`: no `columns` — use `cols`
+
+**If you can't do it with framework components:** Stop. Tell the user what's missing. Don't invent custom workarounds.
+
+---
+
+## CRUD [Phase 2, 3]
+
+**Hidden fields are auto-added by `defineEntity()` — don't define them manually:**
+- `id`, `createdAt`, `updatedAt`, `createdById`, `updatedById`, `status`
+
+**Scope field is auto-added** when `scope` is configured. Don't manually define the scope field (e.g., `companyId`).
+
+**Custom form fields MUST use framework's `useController`:**
+
+```typescript
+// ❌ WRONG
+import { useController } from 'react-hook-form';
+
+// ✅ CORRECT
+import { useController } from '@donotdev/crud';
+```
+
+**Form components receive `control` prop, not `field` prop.**
+
+**Price field is structured:** `{ amount, currency, vatIncluded, discountPercent }`. Don't store computed discount amounts.
+
+**File uploads are deferred** — files upload on form submit, not on selection. Images show optimistic blob URLs.
+
+**Entity namespace defaults to `entity-{name}`** (lowercase). Translation files must match: `locales/entity-product_en.json`.
+
+---
+
+## Functions [Phase 3, 4]
+
+**Use `createFunction` for custom functions — 3 params, everything included:**
+
+```typescript
+import { createFunction } from '@donotdev/functions/firebase';
+
+export const myFunction = createFunction(schema, 'operation_name', async (data, { uid }) => {
+  // Your logic
+});
+```
+
+**Use `createBaseFunction` only when you need custom config** (memory, timeout, region override).
+
+**Deploy with `dndev deploy`** — not `firebase deploy`. Manual deploy causes CORS 403 on preflight because Cloud Run blocks unauthenticated OPTIONS by default.
+
+**Naming:** Export in camelCase (`getDashboardMetrics`), operation ID in snake_case (`get_dashboard_metrics`).
+
+**CRUD functions are one-liner:** `export const crud = createCrudFunctions(entities);` — generates all CRUD endpoints per entity. Access controlled via `entity.access`.
+
+---
+
+## i18n [Phase 3, 4]
+
+**Phase 3: hardcode strings. Phase 4: add translations.** Don't i18n too early.
+
+**Two loading strategies:**
+- **Eager** (always loaded): `src/locales/common_en.json` — navigation, buttons, common UI
+- **Lazy** (loaded per page): `src/pages/locales/home_en.json` — page-specific content
+
+**Status field translations** fall back: `entity-{name}` namespace → `crud` namespace.
+
+**Rich text uses `<Trans>` component** with supported tags only: `<accent>`, `<primary>`, `<muted>`, `<success>`, `<warning>`, `<error>`, `<bold>`, `<code>`.
+
+**Array translations use `tList`:**
+```tsx
+import { tList } from '@donotdev/ui';
+<Card content={tList(t, 'features.items', 4)} />
+```
+
+---
+
+## Dependencies [Phase 1]
+
+**Apps don't declare bundled deps.** Framework packages (`@donotdev/*`) provide everything. Don't add `react-router-dom`, `react-hook-form`, `valibot`, etc. to app's `package.json` — they come through framework deps.
+
+**Environment variables:**
+- Client: `apps/my-app/.env` (prefix with `VITE_*`)
+- Server: `functions/.env` (secrets: `STRIPE_*`, OAuth tokens)
+- Local overrides: `.env.local` (gitignored)
+
+---
+
+**When in doubt: search the codebase first, ask the user second, never guess.**

package/templates/root-consumer/guides/dndev/INDEX.md.example

@@ -8,8 +8,11 @@
 
 ## Getting Started
 
-- [ENV_SETUP.md](./ENV_SETUP.md) - **START HERE** — Full onboarding flow (install → firebase → deploy)
+- **Human flow:** P0 (Bun/Node + AI IDE) → Install CLI & `dndev init` → Run **AI.md** → Enjoy. See [AGENT_START_HERE.md](./AGENT_START_HERE.md) § Getting started (for humans).
+- [ENV_SETUP.md](./ENV_SETUP.md) — After `dndev init`: env, Firebase/Supabase, deploy
+- [GOTCHAS.md](./GOTCHAS.md) - **Common mistakes & pitfalls** (phase-tagged, read before coding)
 - [SETUP_FIREBASE.md](./SETUP_FIREBASE.md) - Firebase project setup (`dndev firebase:setup`)
+- [SETUP_SUPABASE.md](./SETUP_SUPABASE.md) - Supabase project setup (`dndev supabase:setup`, `dn generate sql`)
 - [SETUP_TESTING.md](./SETUP_TESTING.md) - Test generation (Phase 4)
 
 ---