@donotdev/cli 0.0.9 → 0.0.11

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

@@ -1,6 +1,8 @@
 # DoNotDev Framework Guides
 
-**For AI Agents:** See [AGENT_START_HERE.md](./AGENT_START_HERE.md)
+**For AI Agents:** See [AGENT_START_HERE.md](./AGENT_START_HERE.md) ← **START HERE**
+
+**AI System:** Commands in `.claude/commands/`, agents in `.claude/agents/` (synced via `dndev bump`)
 
 ---
 

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

@@ -12,7 +12,7 @@
 | **Display Utilities** (`formatValue`, `DisplayFieldRenderer`, `EntityFilters`, `translateFieldLabel`) | `@donotdev/crud` |
 | **Form Components** (`FormFieldRenderer`, `Controlled*Field`, `UploadProvider`) | `@donotdev/crud` |
 | **Routing-Aware Components** (`EntityFormRenderer`, `EntityList`, `EntityCardList`, `EntityDisplayRenderer`) | `@donotdev/ui` |
-| **Specialized Templates** (`ProductCardListTemplate`, `CarCardListTemplate`) | `@donotdev/templates` |
+| **Specialized Templates** (`ProductCardListTemplate`, `CarCardListTemplate`, `InquiryFormTemplate`, `InquiryAdminTemplate`) | `@donotdev/templates` |
 | **Routing** (`useNavigate`, `Link`, `useParams`) | `@donotdev/ui` |
 | **Entity Definition** (`defineEntity`) | `@donotdev/core` |
 
@@ -147,8 +147,49 @@ registerScopeProvider('tenant', () => tenantStore.getState().currentTenantId);
 | `'user'` | Authenticated |
 | `'admin'` | Admins |
 | `'super'` | Super admins |
+| `'technical'` | Admins only (read-only in forms; e.g. scope field) |
+| `'owner'` | Only when the current user is a stakeholder (see **Stakeholder Access** below) |
 | `'hidden'` | Never |
 
+### Stakeholder Access (ownership)
+
+For marketplace-style entities: documents **public when available**, **private to stakeholders** (e.g. partner, customer) when booked.
+
+**1. Add `ownership` to the entity:**
+
+```typescript
+ownership: {
+  ownerFields: ['providerId', 'customerId'],   // Document fields whose value is a user id
+  publicCondition: [                            // When can anyone read? (AND together)
+    { field: 'status', op: '==', value: 'available' },
+  ],
+},
+```
+
+**2. Use `visibility: 'owner'`** for fields only stakeholders should see (e.g. internal notes, customer contact after booking):
+
+```typescript
+internalNotes: {
+  name: 'internalNotes',
+  label: 'Internal notes',
+  type: 'textarea',
+  visibility: 'owner',   // Returned only when request.auth.uid matches one of ownerFields
+  editable: true,
+  validation: { required: false },
+},
+```
+
+**3. Firestore rules (read and update):** Use the framework helper, then paste the condition into your hand-written `firestore.rules`:
+
+```typescript
+import { generateFirestoreRuleCondition } from '@donotdev/core';
+
+const condition = generateFirestoreRuleCondition(scheduleEntity.ownership);
+// Paste into firestore.rules: allow read, update: if <condition>;
+```
+
+**Behavior:** `listCard_` returns only documents matching `publicCondition` (e.g. public slots). `list_` returns only documents where the current user is in one of `ownerFields` ("mine"). Same condition is used for **allow read** and **allow update** so owners can update (e.g. status to cancelled, notes). For multiple owner fields, prefer an `ownerIds` array and `array-contains` in rules and queries.
+
 ### Entity Access (who CAN DO)
 ```typescript
 access: {
@@ -365,6 +406,85 @@ export default function ShopPage() {
 }
 ```
 
+#### Contact/Inquiry Form (Specialized Template)
+
+For contact forms that create both a Customer and an Inquiry record:
+
+```tsx
+import { InquiryFormTemplate } from '@donotdev/templates';
+import { customerEntity, inquiryEntity } from 'entities';
+
+export default function ContactPage() {
+  return (
+    <PageContainer>
+      <InquiryFormTemplate
+        customerEntity={customerEntity}
+        inquiryEntity={inquiryEntity}
+        // Optional: contextId="car123" - links inquiry to a car/product
+        // Optional: contextName="BMW X5 2024" - shown in message placeholder
+        // Optional: contextDetails="BMW X5 2024 • 50,000 km • €45,000" - detailed placeholder
+        // Optional: messageField="message" - defaults to 'message'
+        // Optional: contextField="carId" - defaults to 'carId'
+        // Optional: customerFields={['firstName', 'lastName', 'email', 'phone']} - fields to show
+        // Optional: onSuccess={() => navigate('/thank-you')}
+      />
+    </PageContainer>
+  );
+}
+```
+
+**What it does:**
+- Creates a Customer record (with `findOrCreate` logic via `uniqueKeys` - prevents duplicates by email/phone)
+- Creates an Inquiry record linked to the customer
+- Handles GDPR consent tracking
+- Auto-fills message with context details if provided
+- Shows success state after submission
+
+**Requirements:**
+- Customer entity must have `uniqueKeys` configured (e.g., `{ fields: ['email'], findOrCreate: true }`)
+- Inquiry entity should have `customerId` field (type: `reference`)
+- Both entities should have `status` field (defaults to `'draft'`)
+
+#### Inquiry Admin Dashboard (Specialized Template)
+
+For admin pages to review and respond to inquiries with one-click actions:
+
+```tsx
+import { InquiryAdminTemplate } from '@donotdev/templates';
+import { customerEntity, inquiryEntity } from 'entities';
+
+export default function InquiriesAdminPage() {
+  return (
+    <PageContainer>
+      <InquiryAdminTemplate
+        customerEntity={customerEntity}
+        inquiryEntity={inquiryEntity}
+        // Optional: customerBasePath="/customers" - defaults to '/customers'
+      />
+    </PageContainer>
+  );
+}
+```
+
+**What it does:**
+- Shows all inquiries in a responsive card grid (1 column mobile, 2 columns desktop)
+- Displays inquiry message preview (first 150 chars)
+- Shows customer info inline (name, email, phone)
+- One-click actions:
+  - **Email** - Opens `mailto:` link (includes subject if `carId` present)
+  - **Call** - Opens `tel:` link
+  - **View Customer** - Navigates to customer detail page
+  - **Mark Responded** - Updates inquiry status to `'responded'` (only shown if not already responded)
+- Status badges with icons (✓ for responded, ⏰ for pending)
+- Auto-sorted by priority: available → draft → responded → deleted (then by date, newest first)
+
+**Features:**
+- Fetches all inquiries and customers in parallel
+- Efficient customer lookup via Map (no N+1 queries)
+- Loading state with spinner
+- Empty state message
+- Responsive grid layout
+
 ---
 
 ## 5. Component Props
@@ -765,6 +885,42 @@ export const productEntity = defineEntity({
 
 Field `label` → translation key in `fields.*`
 
+### Status Field Translations
+
+The `status` field uses CRUD namespace translations with entity-specific overrides:
+
+**Translation Fallback Order:**
+1. **Entity namespace** (`entity-{name}`) - User overrides take priority
+2. **CRUD namespace** (`crud`) - Framework defaults
+
+**Framework Defaults** (in `crud` namespace):
+- `crud:status.draft` → "Draft"
+- `crud:status.available` → "Available"
+- `crud:status.deleted` → "Deleted"
+
+**Override in Entity Translation File:**
+
+```json
+// locales/entity-inquiry_en.json
+{
+  "status": {
+    "draft": "New",
+    "available": "Read",
+    "deleted": "Closed"
+  }
+}
+```
+
+**How it works:**
+- Framework components (`EntityList`, `EntityFormRenderer`, etc.) automatically use `[entity.namespace, 'crud']` translation namespaces
+- Status labels are translated via `translateLabel()` which tries entity namespace first, then falls back to `crud`
+- No `dndev` namespace fallback - CRUD is optional and doesn't pollute core framework translations
+
+**Example:** For an `inquiry` entity:
+- If `entity-inquiry_en.json` has `"status.draft": "New"` → displays "New"
+- If not found → falls back to `crud:status.draft` → displays "Draft"
+- Never falls back to `dndev` namespace
+
 ---
 
 ## 11. Display Utilities