@donotdev/cli 0.0.15 → 0.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donotdev/cli",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "Command-line interface for DoNotDev Framework",
   "type": "module",
   "private": false,
@@ -30,7 +30,7 @@
     "build": "dndev bundle --package @donotdev/cli",
     "dev": "tsc --watch",
     "clean": "rimraf dist tsconfig.tsbuildinfo",
-    "type-check": "tsc --noEmit"
+    "type-check": "bunx tsc --noEmit"
   },
   "dependencies": {
     "@clack/prompts": "^1.0.1",

package/templates/app-expo/.env.example

@@ -28,29 +28,9 @@ EXPO_PUBLIC_DONOTDEV_LICENSE_KEY=dndev_your_key_here
 # EXPO_PUBLIC_SPOTIFY_CLIENT_ID=your_spotify_client_id
 
 # =============================================================================
-# Firebase Configuration
+# Backend-specific vars are appended below by your backend choice
+# (Firebase, Supabase, etc.) — see overlay templates
 # =============================================================================
-# Get these values from your Firebase project settings
-# Run `dndev firebase:setup` to auto-populate, or copy from Firebase Console
-EXPO_PUBLIC_FIREBASE_API_KEY=
-EXPO_PUBLIC_FIREBASE_PROJECT_ID=
-EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN=
-EXPO_PUBLIC_FIREBASE_STORAGE_BUCKET=
-EXPO_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
-EXPO_PUBLIC_FIREBASE_APP_ID=
-EXPO_PUBLIC_FIREBASE_MEASUREMENT_ID=
-EXPO_PUBLIC_FIREBASE_FUNCTIONS_REGION=
-
-# =============================================================================
-# Firebase Emulator (Development only)
-# =============================================================================
-# Set to true to use Firebase emulators instead of production services
-EXPO_PUBLIC_USE_FIREBASE_EMULATOR=false
-EXPO_PUBLIC_FIREBASE_EMULATOR_HOST=localhost
-EXPO_PUBLIC_FIREBASE_EMULATOR_PORT=9099
-EXPO_PUBLIC_FIREBASE_AUTH_EMULATOR_HOST=http://localhost:9099
-EXPO_PUBLIC_FIREBASE_FIRESTORE_EMULATOR_HOST=localhost:8080
-EXPO_PUBLIC_FIREBASE_FUNCTIONS_EMULATOR_PORT=5001
 
 # =============================================================================
 # Stripe Configuration (if using billing)

package/templates/app-expo/README.md.example

@@ -8,7 +8,7 @@ Mobile app built with DoNotDev Framework and Expo.
 
 - Node.js 20+ and Bun 1.3+
 - Expo Go app on your phone (for development)
-- Firebase project (run `dndev firebase:setup`)
+- Firebase project (run `dndev setup firebase`)
 
 ### Development
 

package/templates/app-expo/src/config/app.ts.example

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Application Configuration (Expo)
+ *
+ * THIS FILE IS YOUR MAIN CONFIGURATION. Update the values below.
+ *
+ * QUICK START:
+ * 1. Set APP_NAME and APP_SHORT_NAME
+ * 2. Run `bun dev` - everything else is automatic
+ */
+
+import type { AppConfig } from '@donotdev/core';
+
+// ============================================================================
+// APP IDENTITY - Update these values
+// ============================================================================
+
+export const APP_NAME = '{{appName}}';
+export const APP_SHORT_NAME = '{{appShortName}}';
+export const APP_DESCRIPTION = 'Built with DoNotDev Framework';
+
+// ============================================================================
+// MAIN CONFIGURATION
+// ============================================================================
+
+export const appConfig: AppConfig = {
+  app: {
+    name: APP_NAME,
+    shortName: APP_SHORT_NAME,
+    description: APP_DESCRIPTION,
+  },
+
+  // ==========================================================================
+  // FEATURES - Uncomment to enable
+  // ==========================================================================
+  features: {
+    // debug: true, // Enable debug tools in development
+  },
+
+  // ==========================================================================
+  // AUTH CONFIG - Uncomment to customize
+  // ==========================================================================
+  // auth: {
+  //   authRoute: '/signin',
+  //   profilePath: '/profile',
+  // },
+};

package/templates/app-expo/src/config/providers.ts.example

@@ -0,0 +1,7 @@
+// src/config/providers.ts — Provider bootstrap
+// Auto-generated by DoNotDev scaffolding. Edit freely.
+// When you add a backend (Firebase, Supabase), replace this file with the appropriate provider setup.
+// See: guides/dndev/SETUP_PROVIDERS.md
+
+// No backend configured — nothing to register.
+// To add a backend later, run: dndev create-app (in an existing project, it merges)

package/templates/app-next/src/config/providers.ts.example

@@ -0,0 +1,7 @@
+// src/config/providers.ts — Provider bootstrap
+// Auto-generated by DoNotDev scaffolding. Edit freely.
+// When you add a backend (Firebase, Supabase), replace this file with the appropriate provider setup.
+// See: guides/dndev/SETUP_PROVIDERS.md
+
+// No backend configured — nothing to register.
+// To add a backend later, run: dndev create-app (in an existing project, it merges)

package/templates/app-vite/src/config/providers.ts.example

@@ -0,0 +1,7 @@
+// src/config/providers.ts — Provider bootstrap
+// Auto-generated by DoNotDev scaffolding. Edit freely.
+// When you add a backend (Firebase, Supabase), replace this file with the appropriate provider setup.
+// See: guides/dndev/SETUP_PROVIDERS.md
+
+// No backend configured — nothing to register.
+// To add a backend later, run: dndev create-app (in an existing project, it merges)

package/templates/app-vite/src/pages/HomePage.tsx.example

@@ -53,7 +53,7 @@ export default function HomePage() {
           <Card
             title="2. Firebase Setup"
             content={[
-              'Run: dndev firebase:setup',
+              'Run: dndev setup firebase',
               'This will:',
               '  - Create or select a Firebase project',
               '  - Create a web app if needed',

package/templates/functions-firebase/README.md.example

@@ -76,7 +76,7 @@ GITHUB_REPO_NAME=your-repo
 
 # Firebase Configuration
 FIREBASE_PROJECT_ID=your-project-id
-FIREBASE_REGION=us-central1
+FIREBASE_REGION={{YOUR_REGION}}
 ```
 
 ### Setup Instructions

package/templates/functions-firebase/functions-firebase/.env.example.example

@@ -35,7 +35,7 @@ STRIPE_WEBHOOK_SECRET=whsec_...
 # Firebase Configuration (auto-detected, rarely needed manually)
 # =============================================================================
 FIREBASE_PROJECT_ID=your-project-id
-FIREBASE_REGION=us-central1
+FIREBASE_REGION={{YOUR_REGION}}
 
 # =============================================================================
 # Development

package/templates/functions-firebase/functions-firebase/README.md.example

@@ -49,7 +49,7 @@ GITHUB_REPO_NAME=your-repo
 
 # Firebase Configuration
 FIREBASE_PROJECT_ID=your-project-id
-FIREBASE_REGION=us-central1
+FIREBASE_REGION={{YOUR_REGION}}
 ```
 
 ### Setup Instructions

package/templates/functions-firebase/functions-firebase/tsconfig.json.example

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.functions.json",
+  "extends": "../../../../tsconfig.functions.json",
   "compilerOptions": {
     "outDir": "./lib",
     "rootDir": "./src",

package/templates/functions-firebase/functions.config.js.example

@@ -14,7 +14,7 @@
 
 export const functionsConfig = {
   defaults: {
-    region: ['us-central1'],
+    region: ['{{YOUR_REGION}}'],
     platform: 'gcfv2',
     labels: { app: '{{APP_NAME}}' },
   },

package/templates/functions-supabase/supabase/config.toml.example

@@ -0,0 +1,59 @@
+# For detailed configuration reference documentation, visit:
+# https://supabase.com/docs/guides/local-development/cli/config
+project_id = "{{projectName}}"
+
+[api]
+enabled = true
+port = 54321
+schemas = ["public", "graphql_public"]
+extra_search_path = ["public", "extensions"]
+max_rows = 1000
+
+[db]
+port = 54322
+shadow_port = 54320
+major_version = 17
+
+[db.pooler]
+enabled = false
+port = 54329
+pool_mode = "transaction"
+default_pool_size = 20
+max_client_conn = 100
+
+[db.migrations]
+enabled = true
+
+[db.seed]
+enabled = true
+sql_paths = ["./seed.sql"]
+
+[auth]
+enabled = true
+site_url = "http://127.0.0.1:3000"
+additional_redirect_urls = ["https://127.0.0.1:3000"]
+jwt_expiry = 3600
+enable_refresh_token_rotation = true
+refresh_token_reuse_interval = 10
+enable_signup = true
+enable_anonymous_sign_ins = false
+minimum_password_length = 6
+
+[auth.email]
+enable_signup = true
+double_confirm_changes = true
+enable_confirmations = false
+
+[storage]
+enabled = true
+file_size_limit = "50MiB"
+
+[edge_runtime]
+enabled = true
+policy = "per_worker"
+inspector_port = 8083
+
+[analytics]
+enabled = true
+port = 54327
+backend = "postgres"

package/templates/functions-supabase/supabase/functions/.env.example

@@ -0,0 +1,13 @@
+# =============================================================================
+# Supabase Edge Functions — Secret Keys (DO NOT COMMIT)
+# =============================================================================
+# Get these from: https://supabase.com/dashboard > your project > Settings
+#
+# Secret key: Settings > API > service_role key (or "Secret key" on new projects)
+# DB URL:     Settings > Database > Connection string > URI
+#
+# These are SERVER-SIDE ONLY. Never expose in client code.
+# =============================================================================
+
+SUPABASE_SECRET_KEY=
+SUPABASE_DB_URL=

package/templates/functions-supabase/supabase/functions/deno.json.example

@@ -0,0 +1,8 @@
+{
+  "imports": {
+    "@donotdev/functions/supabase": "npm:@donotdev/functions/supabase",
+    "@donotdev/core/server": "npm:@donotdev/core/server",
+    "@supabase/supabase-js": "npm:@supabase/supabase-js",
+    "valibot": "npm:valibot"
+  }
+}

package/templates/overlay-firebase/env.fragment.example

@@ -3,7 +3,7 @@
 # Firebase Configuration
 # =============================================================================
 # Get these values from your Firebase project settings
-# Run `dndev firebase:setup` to auto-populate, or copy from Firebase Console
+# Run `dndev setup firebase` to auto-populate, or copy from Firebase Console
 VITE_FIREBASE_API_KEY=
 VITE_FIREBASE_PROJECT_ID=
 # Copy from Firebase Console. Framework uses APP_URL hostname in production automatically.

package/templates/overlay-firebase/env.fragment.expo.example

@@ -3,7 +3,7 @@
 # Firebase Configuration
 # =============================================================================
 # Get these values from your Firebase project settings
-# Run `dndev firebase:setup` to auto-populate, or copy from Firebase Console
+# Run `dndev setup firebase` to auto-populate, or copy from Firebase Console
 EXPO_PUBLIC_FIREBASE_API_KEY=
 EXPO_PUBLIC_FIREBASE_PROJECT_ID=
 # Copy from Firebase Console. Framework uses APP_URL hostname in production automatically.

package/templates/overlay-firebase/env.fragment.nextjs.example

@@ -3,7 +3,7 @@
 # Firebase Configuration
 # =============================================================================
 # Get these values from your Firebase project settings
-# Run `dndev firebase:setup` to auto-populate, or copy from Firebase Console
+# Run `dndev setup firebase` to auto-populate, or copy from Firebase Console
 NEXT_PUBLIC_FIREBASE_API_KEY=
 NEXT_PUBLIC_FIREBASE_PROJECT_ID=
 # Copy from Firebase Console. Framework uses APP_URL hostname in production automatically.

package/templates/overlay-supabase/env.fragment.example

@@ -1,7 +1,12 @@
 
 # =============================================================================
-# Supabase Configuration
+# Supabase Configuration (PUBLIC — safe to commit)
+# =============================================================================
+# Get these from: https://supabase.com/dashboard > your project > Settings > API
+#   - Project URL: the https://xxx.supabase.co URL
+#   - Public key:  "Publishable key" (sb_publishable_...) or legacy "anon key" (eyJ...)
+#
+# Then run: dndev setup supabase
 # =============================================================================
-# Get these values from your Supabase project settings > API
 VITE_SUPABASE_URL=
-VITE_SUPABASE_ANON_KEY=
+VITE_SUPABASE_PUBLIC_KEY=

package/templates/overlay-supabase/env.fragment.expo.example

@@ -1,7 +1,12 @@
 
 # =============================================================================
-# Supabase Configuration
+# Supabase Configuration (PUBLIC — safe to commit)
+# =============================================================================
+# Get these from: https://supabase.com/dashboard > your project > Settings > API
+#   - Project URL: the https://xxx.supabase.co URL
+#   - Public key:  "Publishable key" (sb_publishable_...) or legacy "anon key" (eyJ...)
+#
+# Then run: dndev setup supabase
 # =============================================================================
-# Get these values from your Supabase project settings > API
 EXPO_PUBLIC_SUPABASE_URL=
-EXPO_PUBLIC_SUPABASE_ANON_KEY=
+EXPO_PUBLIC_SUPABASE_PUBLIC_KEY=

package/templates/overlay-supabase/env.fragment.nextjs.example

@@ -1,7 +1,12 @@
 
 # =============================================================================
-# Supabase Configuration
+# Supabase Configuration (PUBLIC — safe to commit)
+# =============================================================================
+# Get these from: https://supabase.com/dashboard > your project > Settings > API
+#   - Project URL: the https://xxx.supabase.co URL
+#   - Public key:  "Publishable key" (sb_publishable_...) or legacy "anon key" (eyJ...)
+#
+# Then run: dndev setup supabase
 # =============================================================================
-# Get these values from your Supabase project settings > API
 NEXT_PUBLIC_SUPABASE_URL=
-NEXT_PUBLIC_SUPABASE_ANON_KEY=
+NEXT_PUBLIC_SUPABASE_PUBLIC_KEY=

package/templates/overlay-vercel/env.fragment.example

@@ -3,7 +3,7 @@
 # Firebase Configuration (data layer for Vercel-hosted app)
 # =============================================================================
 # Get these values from your Firebase project settings
-# Run `dndev firebase:setup` to auto-populate, or copy from Firebase Console
+# Run `dndev setup firebase` to auto-populate, or copy from Firebase Console
 VITE_FIREBASE_API_KEY=
 VITE_FIREBASE_PROJECT_ID=
 # Copy from Firebase Console. Framework uses APP_URL hostname in production automatically.

package/templates/overlay-vercel/env.fragment.nextjs.example

@@ -3,7 +3,7 @@
 # Firebase Configuration (data layer for Vercel-hosted app)
 # =============================================================================
 # Get these values from your Firebase project settings
-# Run `dndev firebase:setup` to auto-populate, or copy from Firebase Console
+# Run `dndev setup firebase` to auto-populate, or copy from Firebase Console
 NEXT_PUBLIC_FIREBASE_API_KEY=
 NEXT_PUBLIC_FIREBASE_PROJECT_ID=
 # Copy from Firebase Console. Framework uses APP_URL hostname in production automatically.

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

@@ -36,6 +36,21 @@ approve_phase()         → phase done, move to next
 
 Without MCP: read `.d.ts` files directly from `node_modules/@donotdev/*/dist/`.
 
+## CLI Commands
+
+`dndev` is an **installed CLI** (globally via `npm install -g @donotdev/cli`). Run it directly — **never** use `bunx dndev` or `npx dndev`.
+
+| Command | What it does |
+|---------|-------------|
+| `dndev create-app` | Interactive wizard — creates a new app in the monorepo |
+| `dndev dev` | Start the dev server (Vite/Next.js via Turbo) |
+| `dndev emu start` | Start Firebase emulators |
+| `dndev deploy` | Deploy to production |
+| `dndev setup firebase` | Configure Firebase project + .env |
+| `dndev setup supabase` | Configure Supabase project + .env |
+
+`dndev create-app` is **interactive** — it prompts for builder (Vite/Next.js/Expo), backend (Firebase/Supabase/none), and features. There is no `--preset` flag.
+
 ## Rules
 
 - **ESM only** — never `require()`

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

@@ -46,7 +46,7 @@ Call `start_phase(N)` to begin each phase. It returns the blueprint, agent perso
 
 ### Phase 1: SCAFFOLD (Extractor)
 - **MCP:** `start_phase(1)`
-- **Goal:** Running skeleton. Use `dndev create-app` and create `*Page.tsx` stubs.
+- **Goal:** Running skeleton. Run `dndev create-app` (interactive wizard, run directly — never `bunx`) and create `*Page.tsx` stubs.
 
 ### Phase 2: ENTITIES (Architect)
 - **MCP:** `start_phase(2)`
@@ -81,7 +81,7 @@ Check that the user has completed environment setup:
 2. Service account key exists? (`service-account-key.json` in app root)
 3. Emulators work? (`dndev emu start` runs without errors)
 
-If not, coach them: "Run `dndev firebase:setup` first, then follow the prompts." See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md).
+If not, coach them: "Run `dndev setup firebase` first, then follow the prompts." See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md).
 
 ---
 

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

@@ -11,9 +11,9 @@ If you haven’t run `dndev init` yet, see [AGENT_START_HERE.md](./AGENT_START_H
 ```
 bun install                    -> install dependencies
 bun dev                        -> start app, read the homepage setup guide
-dndev firebase:setup           -> configure Firebase project + .env
+dndev setup firebase           -> configure Firebase project + .env
   -- or --
-dndev supabase:setup           -> configure Supabase project + .env
+dndev setup supabase           -> configure Supabase project + .env
 dndev emu start                -> test locally with emulators (Firebase)
 dndev deploy                   -> deploy to production
 ```
@@ -52,7 +52,7 @@ git push -u origin main
 ### Firebase
 
 ```bash
-dndev firebase:setup
+dndev setup firebase
 ```
 
 Automates: project selection/creation, web app, SDK config -> `.env`, `.firebaserc`.
@@ -66,7 +66,7 @@ See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md) for full details.
 ### Supabase
 
 ```bash
-dndev supabase:setup
+dndev setup supabase
 ```
 
 Asks for your **public** project URL and anon key (both safe to share -- shipped in client bundle).
@@ -188,8 +188,8 @@ my-project/
 |---------|-------------|
 | `bun dev` | Start dev server |
 | `dndev emu start` | Start Firebase emulators |
-| `dndev firebase:setup` | Configure Firebase project + .env |
-| `dndev supabase:setup` | Configure Supabase project + .env |
+| `dndev setup firebase` | Configure Firebase project + .env |
+| `dndev setup supabase` | 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 runtime (Firebase/Vercel) |

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

@@ -11,8 +11,8 @@
 - **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_FIREBASE.md](./SETUP_FIREBASE.md) - Firebase project setup (`dndev setup firebase`)
+- [SETUP_SUPABASE.md](./SETUP_SUPABASE.md) - Supabase project setup (`dndev setup supabase`, `dn generate sql`)
 - [SETUP_TESTING.md](./SETUP_TESTING.md) - Test generation (Phase 4)
 
 ---

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

@@ -109,14 +109,14 @@ export default defineViteConfig({
 
 **Vite loads `.env` from the app directory only.** Not the repo root.
 
-Run `dndev firebase:setup` to auto-populate Firebase config. See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md).
+Run `dndev setup firebase` to auto-populate Firebase config. See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md).
 
 ```bash
 # apps/<your-app>/.env — client-side variables (exposed to browser)
 VITE_APP_URL=http://localhost:5173
 VITE_DONOTDEV_LICENSE_KEY=dndev_your_key_here
-VITE_FIREBASE_API_KEY=...          # Written by dndev firebase:setup
-VITE_FIREBASE_PROJECT_ID=...       # Written by dndev firebase:setup
+VITE_FIREBASE_API_KEY=...          # Written by dndev setup firebase
+VITE_FIREBASE_PROJECT_ID=...       # Written by dndev setup firebase
 VITE_AUTH_PARTNERS=github,google
 VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...
 

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

@@ -866,6 +866,104 @@ declare module '@donotdev/core' {
 
 Then in entity fields you can use `type: 'repairOperations'` and `options: { fieldSpecific: { maxItems: 10 } }` without type errors or `as any`.
 
+### Reference Select Fields (Entity Lookup)
+
+A common pattern: a field stores a **reference ID** (e.g. `author_ref`) pointing to another entity (e.g. `Author`). The form needs a select/combobox populated with that entity's records, and list/detail views need to display a human-readable label instead of a raw ID.
+
+The framework's built-in `reference` type uses `fieldSpecific.displayField` and `fieldSpecific.searchFields`. For **custom** reference types (e.g. `author-select`), follow the same pattern with `fieldSpecific.labelFields`.
+
+**Step 1: Augment `CustomFieldOptionsMap`** so `labelFields` is typed:
+
+```typescript
+// entities/crud.d.ts
+import '@donotdev/core';
+declare module '@donotdev/core' {
+  interface CustomFieldOptionsMap {
+    'author-select': { labelFields: string[] };
+  }
+}
+```
+
+**Step 2: Declare `labelFields` in the entity definition** (SSOT — never hardcode field names in components):
+
+```typescript
+// entities/book.ts
+import { defineEntity } from '@donotdev/core';
+
+export const bookEntity = defineEntity({
+  name: 'Book',
+  collection: 'books',
+  fields: {
+    author_ref: {
+      name: 'author_ref',
+      label: 'fields.author',
+      type: 'author-select',
+      visibility: 'admin',
+      validation: { required: false, reference: 'authors' },
+      options: { fieldSpecific: { labelFields: ['first_name', 'last_name'] } },
+    },
+    // ...
+  },
+});
+```
+
+**Step 3: Build labels from `labelFields`** in your shared formatters:
+
+```typescript
+// entities/formatters.ts
+/**
+ * Build a display label from a record using labelFields from entity field config.
+ * Handles Supabase fieldMapper camelCase conversion: tries camelCase first, then snake_case.
+ */
+export function buildRecordLabel(
+  record: Record<string, unknown>,
+  labelFields: string[],
+): string {
+  return labelFields
+    .map((field) => {
+      const camel = field.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
+      return record[camel] ?? record[field] ?? '';
+    })
+    .join(' ')
+    .trim();
+}
+```
+
+**Step 4: Read `labelFields` in your custom component** (never hardcode field names):
+
+```typescript
+// components/fields/AuthorSelectField.tsx
+import { buildRecordLabel } from 'entities/formatters';
+
+// Inside the component:
+const labelFields: string[] =
+  fieldConfig.options?.fieldSpecific?.labelFields ?? [];
+
+const options = useMemo(() => {
+  return items.map((item) => ({
+    value: String(item.id ?? ''),
+    label: buildRecordLabel(item, labelFields),
+  }));
+}, [items, labelFields]);
+```
+
+**Step 5: Use the same utility for `displayFormatter`** so list/detail views resolve IDs to labels:
+
+```typescript
+// In registerFieldType or in your display formatter
+displayFormatter: (value, config) => {
+  if (value == null) return '';
+  const options = config?.validation?.options;
+  if (Array.isArray(options)) {
+    const match = options.find((opt: any) => opt.value === value);
+    if (match?.label) return String(match.label);
+  }
+  return String(value);
+}
+```
+
+> **Key principle:** Entity field definitions are SSOT. Components read `fieldConfig.options.fieldSpecific.labelFields` — they never hardcode which fields to display. This means changing the label format (e.g. adding `company_name`) only requires editing the entity definition, not every component.
+
 ### Custom Schemas (No Custom UI)
 
 For custom validation without custom UI, just define the schema:

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

@@ -7,7 +7,7 @@
 ## Step 1: Run Firebase Setup
 
 ```bash
-dndev firebase:setup
+dndev setup firebase
 ```
 
 This command:
@@ -94,7 +94,7 @@ This handles everything:
 | `functions/.env` | Server secrets: STRIPE_SECRET_KEY, OAuth secrets | Cloud Functions runtime |
 | Root `.env` | **Not read by Vite.** Reference only. | Nothing |
 
-**`dndev firebase:setup` writes Firebase vars to `apps/<app>/.env` automatically.**
+**`dndev setup firebase` writes Firebase vars to `apps/<app>/.env` automatically.**
 
 **Custom domains:** Framework uses `APP_URL` hostname as `authDomain` in production (not Firebase's `projectId.firebaseapp.com`). Copy/paste `FIREBASE_AUTH_DOMAIN` from Firebase Console in both `.env.local` and `.env.production` — framework handles the rest.
 
@@ -103,7 +103,7 @@ This handles everything:
 ## Staging Environment (Optional)
 
 1. Create a second Firebase project (e.g., `my-app-staging`)
-2. Run `dndev firebase:setup` again and select the staging project
+2. Run `dndev setup firebase` again and select the staging project
 3. Add to `.firebaserc`: `{ "projects": { "staging": "my-app-staging" } }`
 4. Create `service-account-key.staging.json` (same steps as production)
 5. Deploy: `dndev staging`
@@ -171,4 +171,4 @@ If you deploy manually with `firebase deploy`, you'll need to run this yourself.
 
 ---
 
-**`dndev firebase:setup` → download service account key → enable Auth + Firestore → `dndev emu start` → `dndev deploy`. That's it.**
+**`dndev setup firebase` → download service account key → enable Auth + Firestore → `dndev emu start` → `dndev deploy`. That's it.**