@compilr-dev/factory 0.1.3 → 0.1.6

package/LICENSE

@@ -0,0 +1,108 @@
+Functional Source License, Version 1.1, MIT Future License
+
+Abbreviation: FSL-1.1-MIT
+
+Notice
+
+Copyright 2026 Carmelo Scozzola
+
+Terms and Conditions
+
+Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,23 +1,40 @@
 # @compilr-dev/factory
 
-AI-driven application scaffolder for the compilr-dev ecosystem. Generates working full-stack MVPs from an Application Model — a declarative description of what an app is (entities, fields, relationships, layout, features).
-
-## Architecture
-
 ```
-@compilr-dev/agents → @compilr-dev/sdk → @compilr-dev/factory → @compilr-dev/cli
-                                          ↑ peer dep on SDK
+      \|/
+    ╭══════════╮     ___  ___  _ __ ___  _ __ (_) |_ __
+    ║'  ▐▌  ▐▌ │    / __|/ _ \| '_ ` _ \| '_ \| | | '__|
+    ║          │   | (__| (_) | | | | | | |_) | | | |
+    ╰─═──────═─╯    \___|\___/|_| |_| |_| .__/|_|_|_|
+      \________\                        | | .dev
+                                        |_| factory
 ```
 
-The factory provides **5 tools** (via MetaToolsRegistry) and **1 skill**:
+> AI-driven application scaffolder — from declarative model to working full-stack MVP
 
-| Tool | Purpose |
-|------|---------|
-| `app_model_get` | Scoped reads of the Application Model |
-| `app_model_update` | Semantic operations (addEntity, updateField, etc.) |
-| `app_model_validate` | Check model health |
-| `factory_scaffold` | Generate files from model + toolkit |
-| `factory_list_toolkits` | List available toolkits |
+[![npm version](https://img.shields.io/npm/v/@compilr-dev/factory.svg)](https://www.npmjs.com/package/@compilr-dev/factory)
+[![License: FSL-1.1-MIT](https://img.shields.io/badge/License-FSL--1.1--MIT-blue.svg)](https://fsl.software/)
+
+> [!WARNING]
+> This package is in beta. APIs may change between minor versions.
+
+## Overview
+
+The factory takes an **Application Model** — a declarative description of what an app is (entities, fields, relationships, layout, features, theme) — and generates a complete, working full-stack project. It provides tools and skills that let AI agents design and scaffold applications through conversation.
+
+## Features
+
+- **Application Model** — declarative schema for entities, fields, relationships, layout, theme
+- **Semantic Operations** — type-safe mutations (addEntity, updateField, addRelationship, etc.)
+- **Optimistic Locking** — revision counter prevents lost updates
+- **Auto-Inverse Relationships** — adding `belongsTo` auto-creates `hasMany` on target
+- **Cascading Operations** — renaming an entity updates all relationship targets
+- **Validation** — comprehensive model health checks with actionable error messages
+- **Toolkit Registry** — extensible generator system (React+Node built-in)
+- **5 Agent Tools** — model CRUD, validation, scaffolding, toolkit listing
+- **1 Skill** — guided scaffolding workflow for AI agents
+- **Full Color Palette** — auto-generates 50–950 Tailwind shades from single hex
+- **Implicit Timestamps** — `createdAt`/`updatedAt` on all entity records
 
 ## Installation
 
@@ -25,31 +42,28 @@ The factory provides **5 tools** (via MetaToolsRegistry) and **1 skill**:
 npm install @compilr-dev/factory
 ```
 
-Peer dependency: `@compilr-dev/sdk ^0.1.11`
+Peer dependency:
 
-## Usage
-
-```typescript
-import { createModelTools } from '@compilr-dev/factory';
-import type { PlatformContext } from '@compilr-dev/sdk';
+```bash
+npm install @compilr-dev/sdk
+```
 
-// Create the 3 model tools (get, update, validate)
-const tools = createModelTools({
-  context: platformContext, // PlatformContext with documents repo
-});
+## Quick Start
 
-// Or use individual utilities
+```typescript
 import {
   createDefaultModel,
-  createDefaultEntity,
   applyOperation,
   validateModel,
 } from '@compilr-dev/factory';
 
+// Define your application
 const model = createDefaultModel({
   identity: { name: 'Restaurant Manager', description: 'Manage reservations', version: '1.0.0' },
+  theme: { primaryColor: '#E65100' },
 });
 
+// Add entities through semantic operations
 const updated = applyOperation(model, {
   op: 'addEntity',
   entity: {
@@ -66,10 +80,34 @@ const updated = applyOperation(model, {
   },
 });
 
+// Validate
 const result = validateModel(updated);
 // { valid: true, errors: [] }
 ```
 
+### Agent Tools
+
+```typescript
+import { createModelTools, createFactoryTools } from '@compilr-dev/factory';
+import type { PlatformContext } from '@compilr-dev/sdk';
+
+// 3 model tools (get, update, validate)
+const modelTools = createModelTools({ context: platformContext });
+
+// 2 factory tools (scaffold, list-toolkits)
+const factoryTools = createFactoryTools({ context: platformContext });
+```
+
+## Agent Tools Reference
+
+| Tool | Purpose |
+|------|---------|
+| `app_model_get` | Scoped reads of the Application Model (summary, entities, identity, etc.) |
+| `app_model_update` | Semantic operations with optimistic locking |
+| `app_model_validate` | Check model health and get actionable errors |
+| `factory_scaffold` | Generate files from model + toolkit |
+| `factory_list_toolkits` | List available toolkits with descriptions |
+
 ## Application Model
 
 The model describes **what** an application is, independently of how it's built:
@@ -87,45 +125,86 @@ ApplicationModel
 
 ### Semantic Operations
 
-The model is never edited as raw JSON. All changes go through typed operations:
+All model changes go through typed operations — never raw JSON editing:
 
-**Entity:** addEntity, updateEntity, removeEntity, renameEntity, reorderEntities
-**Field:** addField, updateField, removeField, renameField
-**Relationship:** addRelationship, removeRelationship (with auto-inverse management)
-**Section:** updateIdentity, updateLayout, updateFeatures, updateTheme, updateTechStack
+| Category | Operations |
+|----------|------------|
+| **Entity** | addEntity, updateEntity, removeEntity, renameEntity, reorderEntities |
+| **Field** | addField, updateField, removeField, renameField |
+| **Relationship** | addRelationship, removeRelationship (with auto-inverse) |
+| **Section** | updateIdentity, updateLayout, updateFeatures, updateTheme, updateTechStack |
 
 Every operation follows: **READ → CHECK → APPLY → VALIDATE → WRITE**.
 
-### Key Features
+### Key Design Choices
 
 - **Name-based addressing** — `entity: "Reservation"`, not `entities[2]`
 - **Optimistic locking** — revision counter prevents lost updates
 - **Auto-inverse relationships** — adding `belongsTo` auto-adds `hasMany` on target
-- **Cascading operations** — renaming an entity updates all relationship targets
+- **Cascading renames** — renaming an entity updates all FK references
 - **Scoped reads** — `app_model_get({ scope: "summary" })` for lightweight overview
 
+## Toolkits
+
+### React + Node (`react-node`)
+
+Generates a complete full-stack application:
+
+| Category | Generated Files |
+|----------|----------------|
+| **Config** | package.json, vite.config.ts, tailwind.config.js, tsconfig.json, postcss.config.js |
+| **Server** | Express API with CRUD routes, in-memory data stores, seed data |
+| **Pages** | List (card + table views), Detail, Dashboard |
+| **Components** | Cards, Forms, SearchBar, ViewToggle, FilterBar, DarkModeToggle |
+| **Routing** | React Router with nested layouts |
+| **Shell** | Sidebar + header layout, responsive navigation |
+| **Static** | index.html, global CSS, favicon |
+
+**Highlights:**
+- `@tailwindcss/forms` plugin included
+- Full primary color palette (50–950 shades) auto-generated from theme
+- Implicit `createdAt`/`updatedAt` timestamps on all entities
+- Enum fields get filter bars on list pages
+- `belongsTo` relationships get populated API responses and form dropdowns
+- `hasMany` relationships shown as linked lists on detail pages
+- Deterministic seed data (8 items per entity with realistic values)
+
 ## Development
 
 ```bash
 npm run build          # Compile TypeScript
 npm run lint           # ESLint (strict, 0 errors required)
 npm run format:check   # Prettier check
-npm test -- --run      # Run 143 tests
+npm test -- --run      # Run 290 tests
 npm run typecheck      # Type-check without emitting
 ```
 
-## Implementation Status
+## Requirements
+
+- **Node.js** 18 or higher
+- **@compilr-dev/sdk** ^0.1.12 (peer dependency)
 
-| Phase | Status | Description |
-|-------|--------|-------------|
-| 1 | ✅ | Types, validation, naming, defaults |
-| 2 | ✅ | Model operations, persistence, 3 tools |
-| 3 | 🔲 | Factory infrastructure (toolkit registry, scaffold tool) |
-| 4 | 🔲 | React+Node toolkit (~37 file generators) |
-| 5 | 🔲 | Skill prompt (factory-scaffold) |
-| 6 | 🔲 | SDK integration (DocumentType extension) |
-| 7 | 🔲 | CLI integration |
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [@compilr-dev/sdk](https://www.npmjs.com/package/@compilr-dev/sdk) | Universal agent runtime |
+| [@compilr-dev/agents](https://www.npmjs.com/package/@compilr-dev/agents) | Multi-LLM agent library |
+| [@compilr-dev/agents-coding](https://www.npmjs.com/package/@compilr-dev/agents-coding) | Coding-specific tools and language analysis |
+| [@compilr-dev/cli](https://www.npmjs.com/package/@compilr-dev/cli) | AI-powered coding assistant for your terminal |
+
+## Links
+
+- [Website](https://compilr.dev)
+- [npm Package](https://www.npmjs.com/package/@compilr-dev/factory)
+- [Report Issues](https://github.com/compilr-dev/factory/issues)
 
 ## License
 
-MIT
+[FSL-1.1-MIT](https://fsl.software/) - See [LICENSE](LICENSE) for details. Converts to MIT after 2 years per version.
+
+---
+
+<p align="center">
+  <strong>Built with care by <a href="https://compilr.dev">compilr.dev</a></strong>
+</p>

package/dist/factory/skill.js

@@ -33,7 +33,7 @@ You have access to these tools:
 Before building the model, understand the project:
 
 1. Check for existing context:
-   - Use \`project_document_get_by_type\` to look for PRD, architecture, and design docs
+   - Use \`project_document_get\` to look for PRD, architecture, and design docs
    - Read any existing Application Model with \`app_model_get\`
 
 2. If NO model exists, gather requirements from the user:

package/dist/factory/tools.js

@@ -9,8 +9,9 @@ import { createListToolkitsTool } from './list-toolkits-tool.js';
 import { defaultRegistry } from './registry.js';
 export function createFactoryTools(config) {
     const registry = config.registry ?? defaultRegistry;
+    const validToolkitIds = registry.list().map((t) => t.id);
     return [
-        ...createModelTools(config),
+        ...createModelTools({ ...config, validToolkitIds }),
         createScaffoldTool({ ...config, registry }),
         createListToolkitsTool(registry),
     ];

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  */
 export type { ApplicationModel, Entity, Field, FieldType, View, Relationship, RelationshipType, Identity, Layout, ShellType, Features, Theme, TechStack, Meta, } from './model/types.js';
 export { validateModel } from './model/schema.js';
-export type { ValidationError, ValidationResult } from './model/schema.js';
+export type { ValidationError, ValidationResult, ValidateModelOptions } from './model/schema.js';
 export { createDefaultModel, createDefaultEntity, createDefaultField } from './model/defaults.js';
 export { toPascalCase, toCamelCase, toKebabCase, toPlural, isPascalCase, isCamelCase, isValidHexColor, } from './model/naming.js';
 export type { FactoryFile, FactoryResult, FactoryToolkit } from './toolkits/types.js';

package/dist/model/operations-entity.js

@@ -3,7 +3,7 @@
  *
  * addEntity, updateEntity, removeEntity, renameEntity, reorderEntities
  */
-import { isPascalCase } from './naming.js';
+import { isPascalCase, toCamelCase } from './naming.js';
 function findEntity(model, name) {
     const entity = model.entities.find((e) => e.name === name);
     if (!entity) {
@@ -72,15 +72,22 @@ export function renameEntity(model, op) {
             if (entity.name === op.entity) {
                 entity = { ...entity, name: op.newName };
             }
-            // Update relationship targets
+            // Update relationship targets and cascade fieldName
             const hasTargetRef = entity.relationships.some((r) => r.target === op.entity);
             if (hasTargetRef) {
+                const oldDefaultFieldName = toCamelCase(op.entity) + 'Id';
+                const newDefaultFieldName = toCamelCase(op.newName) + 'Id';
                 entity = {
                     ...entity,
                     relationships: entity.relationships.map((r) => {
                         if (r.target !== op.entity)
                             return r;
-                        return { ...r, target: op.newName };
+                        const updated = { ...r, target: op.newName };
+                        // Cascade fieldName if it matches the old default pattern (or is undefined/implicit)
+                        if (r.fieldName === undefined || r.fieldName === oldDefaultFieldName) {
+                            updated.fieldName = newDefaultFieldName;
+                        }
+                        return updated;
                     }),
                 };
             }

package/dist/model/schema.d.ts

@@ -12,4 +12,7 @@ export interface ValidationResult {
     readonly valid: boolean;
     readonly errors: readonly ValidationError[];
 }
-export declare function validateModel(model: ApplicationModel): ValidationResult;
+export interface ValidateModelOptions {
+    readonly validToolkitIds?: readonly string[];
+}
+export declare function validateModel(model: ApplicationModel, options?: ValidateModelOptions): ValidationResult;

package/dist/model/schema.js

@@ -206,7 +206,7 @@ function validateTheme(model) {
     }
     return errors;
 }
-function validateTechStack(model) {
+function validateTechStack(model, validToolkitIds) {
     const errors = [];
     if (model.techStack.toolkit.trim().length === 0) {
         errors.push({
@@ -214,6 +214,12 @@ function validateTechStack(model) {
             message: 'Toolkit is required',
         });
     }
+    else if (validToolkitIds && !validToolkitIds.includes(model.techStack.toolkit)) {
+        errors.push({
+            path: 'techStack.toolkit',
+            message: `Unknown toolkit "${model.techStack.toolkit}". Valid toolkits: ${validToolkitIds.join(', ')}`,
+        });
+    }
     return errors;
 }
 function validateMeta(model) {
@@ -235,10 +241,7 @@ function validateMeta(model) {
     }
     return errors;
 }
-// =============================================================================
-// Public API
-// =============================================================================
-export function validateModel(model) {
+export function validateModel(model, options) {
     const errors = [];
     errors.push(...validateIdentity(model));
     // Entity uniqueness
@@ -260,7 +263,7 @@ export function validateModel(model) {
     errors.push(...validateLayout(model));
     errors.push(...validateFeatures(model));
     errors.push(...validateTheme(model));
-    errors.push(...validateTechStack(model));
+    errors.push(...validateTechStack(model, options?.validToolkitIds));
     errors.push(...validateMeta(model));
     return {
         valid: errors.length === 0,

package/dist/model/tools.d.ts

@@ -10,5 +10,6 @@ import type { PlatformContext } from '@compilr-dev/sdk';
 export interface ModelToolsConfig {
     readonly context: PlatformContext;
     readonly cwd?: string;
+    readonly validToolkitIds?: readonly string[];
 }
 export declare function createModelTools(config: ModelToolsConfig): Tool<never>[];

package/dist/model/tools.js

@@ -222,7 +222,9 @@ EXAMPLES:
                 // Apply
                 const updated = applyOperation(model, operation);
                 // Validate result
-                const validation = validateModel(updated);
+                const validation = validateModel(updated, {
+                    validToolkitIds: config.validToolkitIds,
+                });
                 if (!validation.valid) {
                     const msgs = validation.errors.map((e) => `${e.path}: ${e.message}`).join('; ');
                     return createErrorResult(`Operation would produce invalid model: ${msgs}`);
@@ -422,7 +424,7 @@ function createAppModelValidateTool(config) {
                         errors: [{ path: '', message: 'No Application Model found' }],
                     });
                 }
-                const result = validateModel(model);
+                const result = validateModel(model, { validToolkitIds: config.validToolkitIds });
                 return createSuccessResult({
                     valid: result.valid,
                     errors: result.errors,

package/dist/toolkits/react-node/api.js

@@ -69,6 +69,8 @@ function generateDataStore(model, entity) {
     for (const rel of belongsToRels(entity)) {
         typeFields.push(`  ${fkFieldName(rel)}: number;`);
     }
+    typeFields.push('  createdAt: string;');
+    typeFields.push('  updatedAt: string;');
     const seedData = generateSeedData(model, entity);
     return {
         path: `server/data/${fileName}.ts`,
@@ -91,8 +93,9 @@ export function getById(id: number): ${typeName}Record | undefined {
   return items.find((item) => item.id === id);
 }
 
-export function create(data: Omit<${typeName}Record, 'id'>): ${typeName}Record {
-  const item = { ...data, id: nextId++ };
+export function create(data: Omit<${typeName}Record, 'id' | 'createdAt' | 'updatedAt'>): ${typeName}Record {
+  const now = new Date().toISOString();
+  const item = { ...data, id: nextId++, createdAt: now, updatedAt: now };
   items.push(item);
   return item;
 }
@@ -100,7 +103,7 @@ export function create(data: Omit<${typeName}Record, 'id'>): ${typeName}Record {
 export function update(id: number, data: Partial<${typeName}Record>): ${typeName}Record | undefined {
   const index = items.findIndex((item) => item.id === id);
   if (index === -1) return undefined;
-  items[index] = { ...items[index], ...data, id };
+  items[index] = { ...items[index], ...data, id, updatedAt: new Date().toISOString() };
   return items[index];
 }
 

package/dist/toolkits/react-node/config.d.ts

@@ -7,3 +7,7 @@
 import type { ApplicationModel } from '../../model/types.js';
 import type { FactoryFile } from '../types.js';
 export declare function generateConfigFiles(model: ApplicationModel): FactoryFile[];
+declare function hexToHsl(hex: string): [number, number, number];
+declare function hslToHex(h: number, s: number, l: number): string;
+declare function generateColorShades(hex: string): string;
+export { hexToHsl, hslToHex, generateColorShades };

package/dist/toolkits/react-node/config.js

@@ -43,6 +43,7 @@ function generatePackageJson(appSlug) {
             cors: '^2.8.5',
             express: '^4.21.1',
             postcss: '^8.4.49',
+            '@tailwindcss/forms': '^0.5.9',
             tailwindcss: '^3.4.15',
             tsx: '^4.19.2',
             typescript: '^5.6.3',
@@ -71,18 +72,20 @@ export default defineConfig({
 function generateTailwindConfig(model) {
     return {
         path: 'tailwind.config.js',
-        content: `/** @type {import('tailwindcss').Config} */
+        content: `import forms from '@tailwindcss/forms';
+
+/** @type {import('tailwindcss').Config} */
 export default {
   content: ['./index.html', './src/**/*.{ts,tsx}'],
   darkMode: 'class',
   theme: {
     extend: {
       colors: {
-        primary: '${model.theme.primaryColor}',
+        primary: ${generateColorShades(model.theme.primaryColor)},
       },
     },
   },
-  plugins: [],
+  plugins: [forms],
 };
 `,
     };
@@ -106,6 +109,90 @@ function generateTsConfig() {
     };
     return { path: 'tsconfig.json', content: JSON.stringify(config, null, 2) + '\n' };
 }
+// =============================================================================
+// Color Shade Utilities
+// =============================================================================
+const SHADE_LIGHTNESS = {
+    '50': 97,
+    '100': 94,
+    '200': 86,
+    '300': 77,
+    '400': 66,
+    '500': 55,
+    '600': 44,
+    '700': 36,
+    '800': 27,
+    '900': 20,
+    '950': 14,
+};
+function hexToHsl(hex) {
+    const raw = hex.replace('#', '');
+    const r = parseInt(raw.substring(0, 2), 16) / 255;
+    const g = parseInt(raw.substring(2, 4), 16) / 255;
+    const b = parseInt(raw.substring(4, 6), 16) / 255;
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    const l = (max + min) / 2;
+    if (max === min)
+        return [0, 0, Math.round(l * 100)];
+    const d = max - min;
+    const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    let h = 0;
+    if (max === r)
+        h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+    else if (max === g)
+        h = ((b - r) / d + 2) / 6;
+    else
+        h = ((r - g) / d + 4) / 6;
+    return [Math.round(h * 360), Math.round(s * 100), Math.round(l * 100)];
+}
+function hslToHex(h, s, l) {
+    const sN = s / 100;
+    const lN = l / 100;
+    const c = (1 - Math.abs(2 * lN - 1)) * sN;
+    const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+    const m = lN - c / 2;
+    let r = 0, g = 0, b = 0;
+    if (h < 60)
+        [r, g, b] = [c, x, 0];
+    else if (h < 120)
+        [r, g, b] = [x, c, 0];
+    else if (h < 180)
+        [r, g, b] = [0, c, x];
+    else if (h < 240)
+        [r, g, b] = [0, x, c];
+    else if (h < 300)
+        [r, g, b] = [x, 0, c];
+    else
+        [r, g, b] = [c, 0, x];
+    const toHex = (v) => Math.round((v + m) * 255)
+        .toString(16)
+        .padStart(2, '0');
+    return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+function generateColorShades(hex) {
+    const [h, s] = hexToHsl(hex);
+    const entries = [];
+    for (const [shade, lightness] of Object.entries(SHADE_LIGHTNESS)) {
+        entries.push(`          ${shade}: '${hslToHex(h, s, lightness)}',`);
+    }
+    // Find the shade closest to the original for DEFAULT
+    const [, , originalL] = hexToHsl(hex);
+    let closestShade = '500';
+    let closestDiff = Infinity;
+    for (const [shade, lightness] of Object.entries(SHADE_LIGHTNESS)) {
+        const diff = Math.abs(lightness - originalL);
+        if (diff < closestDiff) {
+            closestDiff = diff;
+            closestShade = shade;
+        }
+    }
+    const defaultHex = hslToHex(h, s, SHADE_LIGHTNESS[closestShade]);
+    entries.push(`          DEFAULT: '${defaultHex}',`);
+    return `{\n${entries.join('\n')}\n        }`;
+}
+// Export for testing
+export { hexToHsl, hslToHex, generateColorShades };
 function generatePostCssConfig() {
     return {
         path: 'postcss.config.js',

package/dist/toolkits/react-node/dashboard.js

@@ -7,16 +7,21 @@ import { toKebabCase, toCamelCase } from '../../model/naming.js';
 export function generateDashboard(model) {
     if (!model.features.dashboard)
         return [];
+    const typeImports = model.entities.map((e) => e.name).join(', ');
+    // State: counts + recent items
+    const stateLines = model.entities
+        .map((e) => {
+        const camel = toCamelCase(e.name);
+        return `  const [${camel}Count, set${e.name}Count] = useState(0);\n  const [recent${e.name}s, setRecent${e.name}s] = useState<${e.name}[]>([]);`;
+    })
+        .join('\n');
+    // Fetch: counts + recent items
     const fetchCalls = model.entities
         .map((e) => {
         const apiUrl = '/api/' + toKebabCase(e.pluralName).toLowerCase();
-        return `      fetch('${apiUrl}').then(r => r.json()).then((d: ${e.name}[]) => set${e.name}Count(d.length)),`;
+        return `      fetch('${apiUrl}').then(r => r.json()).then((d: ${e.name}[]) => { set${e.name}Count(d.length); setRecent${e.name}s(d.slice(-5).reverse()); }),`;
     })
         .join('\n');
-    const stateLines = model.entities
-        .map((e) => `  const [${toCamelCase(e.name)}Count, set${e.name}Count] = useState(0);`)
-        .join('\n');
-    const typeImports = model.entities.map((e) => e.name).join(', ');
     const cards = model.entities
         .map((e) => {
         const path = '/' + toKebabCase(e.pluralName).toLowerCase();
@@ -27,6 +32,21 @@ export function generateDashboard(model) {
         </Link>`;
     })
         .join('\n');
+    // Find first string field per entity for display name
+    const recentRows = model.entities
+        .map((e) => {
+        const firstStringField = e.fields.find((f) => f.type === 'string');
+        const displayExpr = firstStringField ? `item.${firstStringField.name}` : `String(item.id)`;
+        const path = '/' + toKebabCase(e.pluralName).toLowerCase();
+        return `            {recent${e.name}s.map((item) => (
+              <tr key={item.id}>
+                <td className="px-4 py-2 text-sm">${e.icon} ${e.name}</td>
+                <td className="px-4 py-2 text-sm"><Link to={\`${path}/\${String(item.id)}\`} className="text-primary hover:underline">{${displayExpr}}</Link></td>
+                <td className="px-4 py-2 text-sm text-gray-500">{String(item.id)}</td>
+              </tr>
+            ))}`;
+    })
+        .join('\n');
     return [
         {
             path: 'src/pages/Dashboard.tsx',
@@ -51,6 +71,22 @@ ${fetchCalls}
       <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-${String(Math.min(model.entities.length, 4))}">
 ${cards}
       </div>
+
+      <h2 className="mb-4 mt-8 text-xl font-bold text-gray-900 dark:text-white">Recent Activity</h2>
+      <div className="overflow-x-auto rounded-lg border border-gray-200 dark:border-gray-700">
+        <table className="w-full text-left">
+          <thead className="bg-gray-50 dark:bg-gray-800">
+            <tr>
+              <th className="px-4 py-2 text-sm font-medium text-gray-500 dark:text-gray-400">Type</th>
+              <th className="px-4 py-2 text-sm font-medium text-gray-500 dark:text-gray-400">Name</th>
+              <th className="px-4 py-2 text-sm font-medium text-gray-500 dark:text-gray-400">ID</th>
+            </tr>
+          </thead>
+          <tbody className="divide-y divide-gray-200 dark:divide-gray-700">
+${recentRows}
+          </tbody>
+        </table>
+      </div>
     </div>
   );
 }

package/dist/toolkits/react-node/entity.js

@@ -253,6 +253,14 @@ export default function ${entity.name}Detail() {
 
       <dl className="grid grid-cols-1 gap-4 sm:grid-cols-2">
 ${fieldRows}
+          <div>
+            <dt className="text-sm font-medium text-gray-500 dark:text-gray-400">Created</dt>
+            <dd className="mt-1 text-gray-900 dark:text-white">{new Date(item.createdAt).toLocaleString()}</dd>
+          </div>
+          <div>
+            <dt className="text-sm font-medium text-gray-500 dark:text-gray-400">Last Updated</dt>
+            <dd className="mt-1 text-gray-900 dark:text-white">{new Date(item.updatedAt).toLocaleString()}</dd>
+          </div>
 ${relLinks}
       </dl>${hasManyRender}
     </div>

package/dist/toolkits/react-node/router.js

@@ -7,6 +7,7 @@ import { toKebabCase } from '../../model/naming.js';
 export function generateRouter(model) {
     const imports = [];
     const routes = [];
+    const topLevelRoutes = [];
     // Layout import
     imports.push("import Layout from './components/layout/Layout';");
     // Dashboard
@@ -28,6 +29,24 @@ export function generateRouter(model) {
         routes.push(`      { path: '${routeBase}/:id', element: <${entity.name}Detail /> },`);
         routes.push(`      { path: '${routeBase}/:id/edit', element: <${entity.name}Form /> },`);
     }
+    // Settings route (inside Layout)
+    if (model.features.settings) {
+        imports.push("import Settings from './pages/Settings';");
+        routes.push("      { path: 'settings', element: <Settings /> },");
+    }
+    // Profile route (inside Layout)
+    if (model.features.userProfiles) {
+        imports.push("import Profile from './pages/Profile';");
+        routes.push("      { path: 'profile', element: <Profile /> },");
+    }
+    // Auth routes (top-level, outside Layout)
+    if (model.features.auth) {
+        imports.push("import Login from './pages/Login';");
+        imports.push("import Register from './pages/Register';");
+        topLevelRoutes.push("  { path: '/login', element: <Login /> },");
+        topLevelRoutes.push("  { path: '/register', element: <Register /> },");
+    }
+    const topLevelSection = topLevelRoutes.length > 0 ? '\n' + topLevelRoutes.join('\n') : '';
     return [
         {
             path: 'src/router.tsx',
@@ -41,7 +60,7 @@ export const router = createBrowserRouter([
     children: [
 ${routes.join('\n')}
     ],
-  },
+  },${topLevelSection}
 ]);
 `,
         },

package/dist/toolkits/react-node/seed.js

@@ -136,6 +136,13 @@ export function generateSeedData(model, entity) {
             const targetCount = targetEntity ? SEED_COUNT : SEED_COUNT;
             lines.push(`    ${fk}: ${String((i % targetCount) + 1)},`);
         }
+        // Implicit timestamps (deterministic)
+        const createdDate = new Date('2025-06-01T10:00:00Z');
+        createdDate.setDate(createdDate.getDate() + i * 2);
+        const updatedDate = new Date(createdDate);
+        updatedDate.setDate(updatedDate.getDate() + i);
+        lines.push(`    createdAt: '${createdDate.toISOString()}',`);
+        lines.push(`    updatedAt: '${updatedDate.toISOString()}',`);
         lines.push('  },');
     }
     lines.push('];');

package/dist/toolkits/react-node/shell.js

@@ -5,7 +5,22 @@
  */
 import { toKebabCase } from '../../model/naming.js';
 export function generateShellFiles(model) {
-    return [generateApp(model), generateLayout(model), generateSidebar(model), generateHeader(model)];
+    const files = [
+        generateApp(model),
+        generateLayout(model),
+        generateSidebar(model),
+        generateHeader(model),
+    ];
+    if (model.features.settings) {
+        files.push(generateSettingsPage());
+    }
+    if (model.features.auth) {
+        files.push(...generateAuthPages());
+    }
+    if (model.features.userProfiles) {
+        files.push(generateProfilePage());
+    }
+    return files;
 }
 function generateApp(_model) {
     return {
@@ -63,15 +78,21 @@ export default function Layout() {
     };
 }
 function generateSidebar(model) {
-    const navItems = model.entities
-        .map((e) => {
+    const items = [];
+    if (model.features.dashboard) {
+        items.push("  { label: '\u{1F4CA} Dashboard', path: '/' },");
+    }
+    for (const e of model.entities) {
         const path = '/' + toKebabCase(e.pluralName).toLowerCase();
-        return `  { label: '${e.icon} ${e.pluralName}', path: '${path}' },`;
-    })
-        .join('\n');
+        items.push(`  { label: '${e.icon} ${e.pluralName}', path: '${path}' },`);
+    }
+    if (model.features.settings) {
+        items.push("  { label: '\u2699\uFE0F Settings', path: '/settings' },");
+    }
+    const navItems = items.join('\n');
     return {
         path: 'src/components/layout/Sidebar.tsx',
-        content: `import { useState } from 'react';
+        content: `import { useState, useEffect } from 'react';
 import { Link, useLocation } from 'react-router-dom';
 
 const navItems = [
@@ -79,9 +100,15 @@ ${navItems}
 ];
 
 export default function Sidebar() {
-  const [collapsed, setCollapsed] = useState(false);
+  const [collapsed, setCollapsed] = useState(window.innerWidth < 1024);
   const location = useLocation();
 
+  useEffect(() => {
+    const onResize = () => setCollapsed(window.innerWidth < 1024);
+    window.addEventListener('resize', onResize);
+    return () => window.removeEventListener('resize', onResize);
+  }, []);
+
   return (
     <aside
       className={\`\${collapsed ? 'w-16' : 'w-64'} flex flex-col border-r border-gray-200 bg-white transition-all dark:border-gray-700 dark:bg-gray-800\`}
@@ -121,6 +148,7 @@ export default function Sidebar() {
     };
 }
 function generateHeader(model) {
+    const hasSidebar = model.layout.shell === 'sidebar-header';
     const darkModeToggle = model.features.darkMode
         ? `
         <button
@@ -130,6 +158,10 @@ function generateHeader(model) {
           🌓
         </button>`
         : '';
+    const appNameSection = !hasSidebar
+        ? `
+      <span className="text-lg font-bold text-gray-900 dark:text-white">${model.identity.name}</span>`
+        : '';
     return {
         path: 'src/components/layout/Header.tsx',
         content: `import { useLocation } from 'react-router-dom';
@@ -141,7 +173,9 @@ export default function Header() {
 
   return (
     <header className="flex h-14 items-center justify-between border-b border-gray-200 bg-white px-6 dark:border-gray-700 dark:bg-gray-800">
-      <span className="text-sm text-gray-500 dark:text-gray-400">{breadcrumb}</span>
+      <div className="flex items-center gap-4">${appNameSection}
+        <span className="text-sm text-gray-500 dark:text-gray-400">{breadcrumb}</span>
+      </div>
       <div className="flex items-center gap-2">${darkModeToggle}
       </div>
     </header>
@@ -150,3 +184,105 @@ export default function Header() {
 `,
     };
 }
+function generateSettingsPage() {
+    return {
+        path: 'src/pages/Settings.tsx',
+        content: `export default function Settings() {
+  return (
+    <div>
+      <h1 className="mb-6 text-2xl font-bold text-gray-900 dark:text-white">Settings</h1>
+      <p className="text-gray-500 dark:text-gray-400">
+        Application settings will be configured here.
+      </p>
+    </div>
+  );
+}
+`,
+    };
+}
+function generateAuthPages() {
+    return [
+        {
+            path: 'src/pages/Login.tsx',
+            content: `import { Link } from 'react-router-dom';
+
+export default function Login() {
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-gray-50 dark:bg-gray-900">
+      <div className="w-full max-w-md rounded-lg border border-gray-200 bg-white p-8 shadow-sm dark:border-gray-700 dark:bg-gray-800">
+        <h1 className="mb-6 text-2xl font-bold text-gray-900 dark:text-white">Login</h1>
+        <form className="space-y-4">
+          <div>
+            <label className="block text-sm font-medium text-gray-700 dark:text-gray-300">Email</label>
+            <input type="email" className="mt-1 block w-full rounded border border-gray-300 px-3 py-2 dark:border-gray-600 dark:bg-gray-700 dark:text-white" />
+          </div>
+          <div>
+            <label className="block text-sm font-medium text-gray-700 dark:text-gray-300">Password</label>
+            <input type="password" className="mt-1 block w-full rounded border border-gray-300 px-3 py-2 dark:border-gray-600 dark:bg-gray-700 dark:text-white" />
+          </div>
+          <button type="submit" className="w-full rounded bg-primary px-4 py-2 text-white hover:bg-primary/90">
+            Sign In
+          </button>
+        </form>
+        <p className="mt-4 text-center text-sm text-gray-500 dark:text-gray-400">
+          Don&apos;t have an account? <Link to="/register" className="text-primary hover:underline">Register</Link>
+        </p>
+      </div>
+    </div>
+  );
+}
+`,
+        },
+        {
+            path: 'src/pages/Register.tsx',
+            content: `import { Link } from 'react-router-dom';
+
+export default function Register() {
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-gray-50 dark:bg-gray-900">
+      <div className="w-full max-w-md rounded-lg border border-gray-200 bg-white p-8 shadow-sm dark:border-gray-700 dark:bg-gray-800">
+        <h1 className="mb-6 text-2xl font-bold text-gray-900 dark:text-white">Register</h1>
+        <form className="space-y-4">
+          <div>
+            <label className="block text-sm font-medium text-gray-700 dark:text-gray-300">Name</label>
+            <input type="text" className="mt-1 block w-full rounded border border-gray-300 px-3 py-2 dark:border-gray-600 dark:bg-gray-700 dark:text-white" />
+          </div>
+          <div>
+            <label className="block text-sm font-medium text-gray-700 dark:text-gray-300">Email</label>
+            <input type="email" className="mt-1 block w-full rounded border border-gray-300 px-3 py-2 dark:border-gray-600 dark:bg-gray-700 dark:text-white" />
+          </div>
+          <div>
+            <label className="block text-sm font-medium text-gray-700 dark:text-gray-300">Password</label>
+            <input type="password" className="mt-1 block w-full rounded border border-gray-300 px-3 py-2 dark:border-gray-600 dark:bg-gray-700 dark:text-white" />
+          </div>
+          <button type="submit" className="w-full rounded bg-primary px-4 py-2 text-white hover:bg-primary/90">
+            Create Account
+          </button>
+        </form>
+        <p className="mt-4 text-center text-sm text-gray-500 dark:text-gray-400">
+          Already have an account? <Link to="/login" className="text-primary hover:underline">Login</Link>
+        </p>
+      </div>
+    </div>
+  );
+}
+`,
+        },
+    ];
+}
+function generateProfilePage() {
+    return {
+        path: 'src/pages/Profile.tsx',
+        content: `export default function Profile() {
+  return (
+    <div>
+      <h1 className="mb-6 text-2xl font-bold text-gray-900 dark:text-white">Profile</h1>
+      <p className="text-gray-500 dark:text-gray-400">
+        User profile information will be displayed here.
+      </p>
+    </div>
+  );
+}
+`,
+    };
+}

package/dist/toolkits/react-node/static.js

@@ -32,12 +32,26 @@ VITE_API_URL=http://localhost:3001
     };
 }
 function generateReadme(model) {
+    let entitiesSection = '';
+    if (model.entities.length > 0) {
+        const entityLines = model.entities
+            .map((e) => {
+            const relCount = e.relationships.length;
+            const parts = [`${String(e.fields.length)} fields`];
+            if (relCount > 0) {
+                parts.push(`${String(relCount)} relationship${relCount > 1 ? 's' : ''}`);
+            }
+            return `- **${e.name}** (${e.icon}) — ${parts.join(', ')}`;
+        })
+            .join('\n');
+        entitiesSection = `\n## Entities\n\n${entityLines}\n`;
+    }
     return {
         path: 'README.md',
         content: `# ${model.identity.name}
 
 ${model.identity.description}
-
+${entitiesSection}
 ## Getting Started
 
 \`\`\`bash

package/dist/toolkits/react-node/types-gen.js

@@ -26,6 +26,9 @@ function generateInterface(entity) {
         lines.push(`  ${fk}: number;`);
         lines.push(`  ${rel.target.charAt(0).toLowerCase() + rel.target.slice(1)}?: ${rel.target};`);
     }
+    // Implicit timestamps
+    lines.push('  createdAt: string;');
+    lines.push('  updatedAt: string;');
     lines.push('}');
     return lines.join('\n');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/factory",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "AI-driven application scaffolder for the compilr-dev ecosystem",
   "type": "module",
   "main": "dist/index.js",
@@ -37,7 +37,7 @@
     "typescript-eslint": "^8.18.1",
     "vitest": "^2.1.8"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/scozzola/compilr-dev-factory"