@polymorphism-tech/morph-spec 8.25.0 → 8.27.0

package/framework/templates/README.md

@@ -1,12 +1,16 @@
 # MORPH-SPEC Template System
 
-> **Technology-Based Organization for Multi-Stack Reusability**
+> Handlebars templates organized by **technology**, indexed by `REGISTRY.json`.
 
 ## Overview
 
-The MORPH-SPEC template system provides **57 production-ready templates** organized by **technology** (not by stack) to enable maximum reusability across current and future stacks.
+**89 templates**, grouped by the technology they target (dotnet, typescript, sql, docker,
+nextjs) rather than by stack. A template for a .NET slice serves every stack with a .NET
+backend, so a new stack reuses what exists instead of copying it.
 
-**Key Principle:** Templates are grouped by the **technology they use** (dotnet, typescript, sql, docker), allowing new stacks like `vue-firebase` or `angular-mongodb` to reuse existing templates for .NET, TypeScript, SQL, etc.
+`REGISTRY.json` is the source of truth: it maps each template `id` to its `path`, category,
+technology and applicable stacks. Nothing resolves a template by hardcoded path — code goes
+through the registry, and this README never repeats a path the registry already owns.
 
 ---
 
@@ -14,135 +18,57 @@ The MORPH-SPEC template system provides **57 production-ready templates** organi
 
 ```
 framework/templates/
-├── docs/              # Universal documentation templates
-│   ├── proposal.md    # Feature proposal (required)
-│   └── spec.md        # Technical specification (required)
+├── docs/              # Phase documents (proposal, spec, user-stories, ui-*, onboarding…)
+├── feature/           # decisions.md, recap.md
+├── context/           # ARCHITECTURE.md, design-system.md
 │
-├── feature/           # Feature management
-│   ├── decisions.md   # Architecture Decision Records (required)
-│   └── recap.md       # Post-implementation summary (required)
+├── code/              # Code templates, by technology
+│   ├── dotnet/        # abstractions, ai-agents, constants, contracts, database,
+│   │                  #   exceptions, extensions, feature, jobs, pipelines
+│   ├── typescript/    # contracts.ts
+│   └── sql/           # postgresql migrations, RLS policy, ai-agents
 │
-├── context/           # Context generation
-│   ├── CONTEXT.md            # Project-level context
-│   └── CONTEXT-FEATURE.md    # Feature-level context
-│
-├── code/              # Code templates organized by technology
-│   ├── dotnet/
-│   │   ├── backend/
-│   │   │   ├── service.cs          # Service layer
-│   │   │   └── test.cs             # Unit tests
-│   │   ├── database/
-│   │   │   └── migration.cs        # EF Core migrations
-│   │   ├── jobs/
-│   │   │   ├── job.cs              # Hangfire background jobs
-│   │   │   └── agent.cs            # MS Agent Framework agents
-│   │   └── contracts/
-│   │       ├── contracts.cs        # Base contracts
-│   │       ├── Commands.cs         # CQRS commands
-│   │       ├── Queries.cs          # CQRS queries
-│   │       ├── Entities.cs         # Domain entities
-│   │       ├── api-contracts.cs    # API contracts
-│   │       └── README.md           # Contracts documentation
-│   │
-│   ├── typescript/
-│   │   └── contracts.ts            # TypeScript type definitions
-│   │
-│   └── sql/
-│       ├── postgresql-migration.sql          # Basic migration
-│       ├── postgresql-migration.template.sql # Enhanced migration
-│       └── postgresql-rls-policy.sql                  # Row-level security
+├── frontend/
+│   └── nextjs/        # page, client-component, feature-form, use-feature, env, tsconfig…
 │
 ├── infrastructure/
-│   ├── docker/        # Docker & Coolify
-│   │   ├── dockerfile-api.dockerfile       # .NET API
-│   │   ├── dockerfile-web.dockerfile       # Next.js web
-│   │   ├── Dockerfile.template             # Generic
-│   │   ├── docker-compose.template.yml     # Compose
-│   │   └── coolify.template.json           # Coolify config
-│   │
-│   └── github/        # GitHub Actions CI/CD
-│       ├── workflows/                      # Reusable workflow templates
-│       │   ├── dotnet-build.yml.hbs       # .NET restore, build, test
-│       │   ├── docker-build-push.yml.hbs  # Docker build & push
-│       │   └── deploy-coolify.yml.hbs     # Coolify deployment (via SSH)
-│       │
-│       ├── actions/                        # Composite action templates
-│       │   ├── docker-build-push/action.yml.hbs
-│       │   └── health-check/action.yml.hbs
-│       │
-│       └── README.md                       # GitHub Actions docs
-│
-├── integrations/      # Platform-agnostic integrations
-│   ├── asaas-client.cs           # Asaas financial API
-│   ├── asaas-webhook.cs          # Asaas webhooks
-│   └── neon-auth-config.cs       # Neon Auth (Better Auth)
-│
-├── ui/                # Design systems
-│   └── design-system.css         # CSS tokens
+│   ├── docker/        # Dockerfiles, compose, Coolify config
+│   └── github/        # Actions workflows + composite actions (.hbs)
 │
-├── saas/              # Multi-tenant patterns
-│
-├── examples/          # Reference implementations
-│   ├── spec-examples.md          # Example specs
-│   └── design-system-examples.md # Design system examples
-│
-└── REGISTRY.json      # Template metadata registry
+├── integrations/      # asaas-client, asaas-webhook, neon-auth-config
+├── ui/                # design-system.css
+├── meta-prompts/      # fusion, squad-leaders, validators
+├── examples/          # spec-examples.md, design-system-examples.md
+└── REGISTRY.json      # template metadata — the index every consumer reads
 ```
 
 ---
 
-## 🏗️ Technology-Based Architecture
-
-**Why organize by technology instead of by stack?**
-
-| Organization | Pros | Cons | Best For |
-|--------------|------|------|----------|
-| **By Stack** (old v1) | Stack-specific optimizations | Duplicate templates, hard to reuse | Single-stack projects |
-| **By Technology** (new v2) | Reusable, DRY, future-proof | Requires stack override mechanism | Multi-stack frameworks |
-
-**Example:** A `.NET service.cs` template works for both `dotnet-nextjs` and `nextjs-neon` stacks (both use .NET backend). No need to duplicate!
-
-**Future-proof:** When we create `vue-firebase` stack, we can reuse:
-- `code/typescript/` templates
-- `infrastructure/docker/` templates
-- `integrations/` templates (Neon Auth, etc.)
-
-**Only create NEW templates for Vue-specific code.**
-
----
-
 ## ⚙️ Template Engine: Handlebars
 
-All templates use **Handlebars** with **20+ custom helpers**.
-
-### Basic Syntax
+All templates render through Handlebars with custom helpers registered in
+`src/core/templates/template-renderer.js`.
 
 ```handlebars
 # Feature: {{titleCase FEATURE_NAME}}
 
-Namespace: {{pascalCase FEATURE_NAME}}
+namespace {{pascalCase FEATURE_NAME}};
 
-Created: {{DATE}}
+Created: {{now}}
 ```
 
-### Available Helpers
-
-| Helper | Input | Output | Usage |
-|--------|-------|--------|-------|
-| `{{pascalCase str}}` | `user-profile` | `UserProfile` | Class names |
-| `{{camelCase str}}` | `user-profile` | `userProfile` | Variable names |
-| `{{snakeCase str}}` | `user-profile` | `user_profile` | SQL tables |
-| `{{upperSnakeCase str}}` | `user-profile` | `USER_PROFILE` | Constants |
-| `{{titleCase str}}` | `user-profile` | `User Profile` | Titles |
-| `{{kebabCase str}}` | `User Profile` | `user-profile` | URLs |
-| `{{pluralize str}}` | `user` | `users` | Collections |
-| `{{singularize str}}` | `users` | `user` | Entities |
-| `{{eq a b}}` | `"nextjs" "nextjs"` | `true` | Conditionals |
-| `{{or a b}}` | `false true` | `true` | Logical OR |
-| `{{and a b}}` | `true false` | `false` | Logical AND |
-| `{{default val fallback}}` | `null "default"` | `"default"` | Defaults |
-
-### Conditional Logic
+### Available helpers
+
+| Group | Helpers |
+|-------|---------|
+| **Case** | `pascalCase` `camelCase` `snakeCase` `upperSnakeCase` `kebabCase` `titleCase` `uppercase` `lowercase` `capitalize` |
+| **Words** | `pluralize` `singularize` |
+| **Comparison** | `eq` `ne` `lt` `gt` `lte` `gte` |
+| **Logic** | `and` `or` `not` `default` |
+| **String** | `trim` `replace` `concat` `substr` `startsWith` `endsWith` `contains` `length` |
+| **Math** | `add` `subtract` `multiply` `divide` `mod` `round` |
+| **Array** | `join` `first` `last` `slice` |
+| **Misc** | `json` `now` `year` `formatDate` |
 
 ```handlebars
 {{#if (eq STACK "nextjs-neon")}}
@@ -152,556 +78,59 @@ Created: {{DATE}}
 {{/if}}
 ```
 
-### Deprecated: Pre-computed Variables
-
-**❌ Old (v1):**
-```handlebars
-{{pascalCase FEATURE_NAME}}  <!-- Pre-computed in bin/render-template.js -->
-```
-
-**✅ New (v2):**
-```handlebars
-{{pascalCase FEATURE_NAME}}  <!-- Computed via Handlebars helper -->
-```
-
----
-
-## 🛠️ CLI Commands
-
-### List All Templates
-
-```bash
-# List all templates
-morph-spec template list
-
-# Filter by category
-morph-spec template list --category code
-morph-spec template list --category infrastructure
-
-# Filter by phase
-morph-spec template list --phase implement
-
-# Filter by stack applicability
-morph-spec template list --stack dotnet-nextjs
-
-# Show only required templates
-morph-spec template list --required
-```
-
-**Output:**
-```
-📦 Universal Templates (9)
-  proposal             Feature Proposal          [REQUIRED] [UNIVERSAL] [HBS]
-  spec                 Technical Specification   [REQUIRED] [UNIVERSAL] [HBS]
-  tasks                Implementation Tasks      [REQUIRED] [UNIVERSAL] [HBS]
-  ...
-
-📦 Technology-Based Templates (48)
-  dotnet-backend-service    .NET Service Class          [UNIVERSAL] [HBS] (dotnet)
-  typescript-contracts      TypeScript Contracts        [UNIVERSAL] [HBS] (typescript)
-  ...
-```
-
-### Show Template Details
-
-```bash
-# Show metadata
-morph-spec template show dotnet-backend-service
-
-# Show with file preview
-morph-spec template show dotnet-backend-service --preview
-
-# Show with resolved path
-morph-spec template show dotnet-backend-service --show-path
-```
-
-**Output:**
-```
-Template: dotnet-backend-service
-
-📋 Metadata
-  ID: dotnet-backend-service
-  Name: .NET Service Class
-  Path: code/dotnet/backend/service.cs
-  Location: framework
-  Category: code
-  Phase: implement
-  Required: No
-  Technology: dotnet
-  Applicable Stacks: dotnet-nextjs, nextjs-neon
-
-📝 Description
-  C# service class template with dependency injection and interface pattern
-
-🔑 Variables
-  {{FEATURE_NAME}}
-  {{NAMESPACE}}
-
-📄 Output Name
-  {FeatureName}Service.cs
-
-💡 Usage Hint
-  morph-spec template render dotnet-backend-service output.cs '{"FEATURE_NAME":"user-auth","NAMESPACE":"MyApp"}'
-```
-
-### Render Template
-
-```bash
-# Render to file
-morph-spec template render dotnet-backend-service UserAuthService.cs '{
-  "FEATURE_NAME": "user-auth",
-  "NAMESPACE": "MyApp.Services"
-}'
-
-# Dry run (preview only)
-morph-spec template render dotnet-backend-service output.cs '{"FEATURE_NAME":"test"}' --dry-run
-
-# Auto-resolve path (searches framework → stack override)
-morph-spec template render proposal proposal.md '{"FEATURE_NAME":"auth"}' --resolve-path
-```
-
-**Default Variables (auto-injected):**
-- `DATE`: `2026-02-17`
-- `YEAR`: `2026`
-- `TIMESTAMP`: `2026-02-17T19:38:00.000Z`
-
-### Customize Template (Stack Override)
-
-```bash
-# Copy to stack-specific directory (override framework version)
-morph-spec template customize dotnet-backend-service --stack dotnet-nextjs
-
-# Copy to project-local (cross-stack override)
-morph-spec template customize dotnet-backend-service --local
-
-# Force overwrite if exists
-morph-spec template customize dotnet-backend-service --stack dotnet-nextjs --force
-```
-
-**Output:**
-```
-Source: framework/templates/code/dotnet/backend/service.cs
-Destination: stacks/dotnet-nextjs/.morph/framework/templates/code/dotnet/backend/service.cs
-
-✅ Template copied for customization
-
-📝 Next Steps
-  1. Edit the template file:
-     stacks/dotnet-nextjs/.morph/framework/templates/code/dotnet/backend/service.cs
-
-  2. Template will now be used instead of framework version
-     (Stack-specific templates take precedence)
-
-  3. Test rendering:
-     morph-spec template render dotnet-backend-service output.cs '{"FEATURE_NAME":"test"}'
-
-⚠️  Customized templates won't receive framework updates
-   To get updates: delete customized version and re-run this command
-```
-
----
-
-## 🔄 GitHub Actions Templates
-
-The framework provides reusable GitHub Actions workflows and composite actions for CI/CD automation.
-
-### Structure
-
-```
-infrastructure/github/
-├── workflows/                      # Reusable workflow templates
-│   ├── dotnet-build.yml.hbs       # .NET restore, build, test
-│   ├── docker-build-push.yml.hbs  # Docker build & push
-│   └── deploy-coolify.yml.hbs     # Coolify deployment via SSH
-│
-└── actions/                        # Composite action templates
-    ├── docker-build-push/action.yml.hbs
-    └── health-check/action.yml.hbs
-```
-
-### Reusable Workflows vs Composite Actions
-
-| Type | Purpose | Location | Usage |
-|------|---------|----------|-------|
-| **Reusable Workflows** | Complete CI/CD pipelines (multi-job) | `workflows/*.yml.hbs` | Called via `uses:` from stack workflows |
-| **Composite Actions** | Reusable step logic (single responsibility) | `actions/*/action.yml.hbs` | Called via `uses:` in workflow steps |
-
-### Deployment Strategy Difference
-
-**NextJS-Neon:** Docker containers to Coolify
-- `docker build` → `docker push` → Coolify deploy triggered via SSH (Coolify's API is not publicly exposed — the runner SSHes into the VPS and calls `localhost:8000/api/v1/deploy` there)
-- Multi-service deployment (API + Web)
-- Registry: GitHub Container Registry (ghcr.io)
-
-### Template Rendering
-
-**GitHub Actions Constraint:**
-- ❌ GitHub Actions CANNOT reference parent directories (`../../../../framework/`)
-- ✅ Solution: Framework templates are **rendered** into each stack's `.github/` directory
-- Rendered `.yml` files are **committed** to repos (not `.yml.hbs` templates)
-
-**Rendering Process:**
-```bash
-# Render all GitHub Actions templates for a stack (manual for now)
-# Future: morph-spec template render github-workflows --stack dotnet-nextjs
-```
-
-### Handlebars Variables
-
-- `{{APP_NAME}}` - Application name from config.json
-- `{{DOTNET_VERSION}}` - .NET SDK version
-- `{{GITHUB_OWNER}}` - GitHub organization/user
-- `{{kebabCase APP_NAME}}` - Docker image name format
-- `${{{{ inputs.* }}}}` - GitHub Actions runtime syntax (escaped with `{{{{raw}}}}`)
-
-### Authentication & Secrets
-
-**Docker Registry (NextJS-Neon):**
-```yaml
-# GitHub Container Registry (ghcr.io)
-- uses: docker/login-action@v3
-  with:
-    registry: ghcr.io
-    username: ${{{{ github.actor }}}}
-    password: ${{{{ secrets.GITHUB_TOKEN }}}}
-```
-
-**GitHub Secrets to Configure:**
-- NextJS-Neon: `GITHUB_TOKEN` (auto), `COOLIFY_SSH_HOST`, `COOLIFY_SSH_USER`, `COOLIFY_SSH_KEY`, `COOLIFY_APPLICATION_UUID`
-
-### Stack-Specific Overrides
-
-Stack-specific workflow templates in:
-- `stacks/nextjs-neon/.morph/framework/templates/infrastructure/github/workflows/`
-
-**Resolution Order:**
-1. Project-local: `.morph/framework/templates/infrastructure/github/workflows/ci-build.yml.hbs`
-2. Stack default: `stacks/{stack}/.morph/framework/templates/infrastructure/github/workflows/ci-build.yml.hbs`
-3. Framework fallback: `framework/templates/infrastructure/github/workflows/dotnet-build.yml.hbs`
-
----
-
-## 🔀 Stack Override Mechanism
-
-**Resolution Order:**
-
-1. **Stack-specific override** (highest priority)
-   - `stacks/{stack}/.morph/framework/templates/code/dotnet/backend/service.cs`
-
-2. **Project-local override** (medium priority)
-   - `.morph/framework/templates/code/dotnet/backend/service.cs`
-
-3. **Framework template** (fallback)
-   - `framework/templates/code/dotnet/backend/service.cs`
-
-**Use Cases for Overrides:**
-
-| Scenario | Override Location | Example |
-|----------|-------------------|---------|
-| Stack-specific tweak | `stacks/{stack}/.morph/framework/templates/` | Stack uses different DI pattern |
-| Project-wide customization | `.morph/framework/templates/` | Company-specific code style |
-| Use framework default | None (no override) | Standard templates work fine |
-
-**Example:**
-
-```bash
-# Create stack override
-morph-spec template customize dotnet-backend-service --stack dotnet-nextjs
-
-# Edit the override
-code stacks/dotnet-nextjs/.morph/framework/templates/code/dotnet/backend/service.cs
-
-# Now all renders for dotnet-nextjs will use the override
-morph-spec template render dotnet-backend-service UserService.cs '...' --stack dotnet-nextjs
-```
-
----
-
-## 📊 Template Registry (REGISTRY.json)
-
-The `REGISTRY.json` file is the **single source of truth** for all template metadata.
-
-### Schema
-
-```json
-{
-  "version": "2.0.0",
-  "templates": [
-    {
-      "id": "dotnet-backend-service",
-      "name": ".NET Service Class",
-      "path": "code/dotnet/backend/service.cs",
-      "location": "framework",
-      "category": "code",
-      "phase": "implement",
-      "required": false,
-      "technology": "dotnet",
-      "applicableStacks": ["dotnet-nextjs", "nextjs-neon"],
-      "engine": "handlebars",
-      "placeholders": ["FEATURE_NAME", "NAMESPACE"],
-      "outputName": "{FeatureName}Service.cs",
-      "deprecated": false
-    }
-  ]
-}
-```
-
-### Discovery API
-
-```javascript
-import {
-  getAllTemplates,
-  getTemplateById,
-  getTemplatesByCategory,
-  getTemplatesByTechnology,
-  resolveTemplatePathById
-} from '../src/lib/template-registry.js';
-
-// Get all templates
-const all = getAllTemplates();
-
-// Get specific template
-const service = getTemplateById('dotnet-backend-service');
-
-// Filter by category
-const codeTemplates = getTemplatesByCategory('code');
-
-// Filter by technology
-const dotnetTemplates = getTemplatesByTechnology('dotnet');
-
-// Resolve path with fallback
-const path = resolveTemplatePathById('dotnet-backend-service', '/project', 'dotnet-nextjs');
-// Returns: framework/templates/code/dotnet/backend/service.cs
-// Or: stacks/dotnet-nextjs/.morph/framework/templates/code/dotnet/backend/service.cs (if override exists)
-```
-
 ---
 
-## 🚀 Creating New Templates
+## 🔗 How templates are consumed
 
-### 1. Create Template File
+Templates are **resolved from the installed npm package**, not copied into projects.
+`morph-spec setup-infra` deliberately skips copying `framework/templates/` — a target project
+gets the package's templates for free and stays current on every upgrade.
 
-```bash
-# For .NET templates
-touch framework/templates/code/dotnet/backend/my-template.cs
-
-# For infrastructure templates
-touch framework/templates/infrastructure/docker/my-resource.dockerfile
-```
-
-### 2. Add Handlebars Placeholders
-
-```handlebars
-namespace {{pascalCase NAMESPACE}};
-
-public class {{pascalCase FEATURE_NAME}}Service
-{
-    // TODO: Implement {{titleCase FEATURE_NAME}} logic
-}
-```
-
-### 3. Register in REGISTRY.json
-
-```json
-{
-  "id": "dotnet-backend-my-template",
-  "name": "My Custom Template",
-  "path": "code/dotnet/backend/my-template.cs",
-  "location": "framework",
-  "category": "code",
-  "phase": "implement",
-  "required": false,
-  "technology": "dotnet",
-  "applicableStacks": ["dotnet-nextjs"],
-  "engine": "handlebars",
-  "placeholders": ["FEATURE_NAME", "NAMESPACE"],
-  "outputName": "{FeatureName}MyTemplate.cs",
-  "deprecated": false
-}
-```
-
-### 4. Test Rendering
+**The consumer is the scaffolder**, which pairs a REGISTRY `id` with an output shape:
 
 ```bash
-morph-spec template render dotnet-backend-my-template output.cs '{
-  "FEATURE_NAME": "user-auth",
-  "NAMESPACE": "MyApp.Services"
-}'
-```
-
----
-
-## 📦 Migration Guide: v1 → v2
-
-### What Changed
-
-| Aspect | v1 (Stack-Based) | v2 (Technology-Based) |
-|--------|------------------|----------------------|
-| **Location** | `stacks/{stack}/.morph/framework/templates/` | `framework/templates/{technology}/` |
-| **Organization** | By stack (dotnet-nextjs, nextjs-neon) | By technology (dotnet, docker) |
-| **Duplication** | High (proposal.md × 2, decisions.md × 2) | Low (shared templates in framework) |
-| **Template Engine** | 3 engines (custom, Handlebars, mixed) | 1 engine (Handlebars with helpers) |
-| **Pre-computed Variables** | `{{pascalCase FEATURE_NAME}}` | `{{pascalCase FEATURE_NAME}}` (helpers) |
-| **Registry** | None (hardcoded paths) | `REGISTRY.json` (centralized metadata) |
-| **CLI** | None | `morph-spec template list/show/render/customize` |
-| **Future Stacks** | Must copy templates | Reuse existing technology templates |
-
-### Breaking Changes
-
-**1. Template Paths**
-
-```diff
-- stacks/dotnet-nextjs/.morph/framework/templates/service.cs
-+ framework/templates/code/dotnet/backend/service.cs
-
-- stacks/nextjs-neon/.morph/framework/templates/dockerfile-web.dockerfile
-+ framework/templates/infrastructure/docker/dockerfile-web.dockerfile
-```
-
-**2. Pre-computed Variables**
-
-```diff
-- {{pascalCase FEATURE_NAME}}
-+ {{pascalCase FEATURE_NAME}}
-
-- {{camelCase FEATURE_NAME}}
-+ {{camelCase FEATURE_NAME}}
-
-- {{snakeCase FEATURE_NAME}}
-+ {{snakeCase FEATURE_NAME}}
-```
-
-**3. Template Resolution**
-
-```javascript
-// Old (v1)
-const templatePath = join(resolveTemplatesDir(projectPath), 'service.cs');
-
-// New (v2)
-const templatePath = resolveTemplatePath(projectPath, 'code/dotnet/backend/service.cs', stackId);
-// Automatically falls back: stack override → framework
-```
-
-### Migration Steps
-
-**Step 1:** Update code to use `resolveTemplatePath()`
-
-```javascript
-import { resolveTemplatePath } from '../lib/stack-resolver.js';
-
-// Before
-const path = join(resolveTemplatesDir(process.cwd()), 'service.cs');
-
-// After
-const path = resolveTemplatePath(process.cwd(), 'code/dotnet/backend/service.cs', 'dotnet-nextjs');
+morph-spec scaffold dotnet <feature> <slice-name>   # VSA slice (endpoint, handler, request,
+                                                    #   response, validator, errors, entity)
+morph-spec scaffold nextjs <feature>                # page, client component, form, hook
 ```
 
-**Step 2:** Update template syntax to Handlebars
+There is **no `morph-spec template` command** — the v4 CLI surface (`list`/`show`/`render`/
+`customize`) was removed in the v4→v5 migration. To use a template by hand, read the file and
+follow its pattern, or call `renderTemplate()` from the renderer module.
 
-```handlebars
-<!-- Before -->
-namespace {{NAMESPACE}};
-public class {{pascalCase FEATURE_NAME}}Service { }
-
-<!-- After -->
-namespace {{pascalCase NAMESPACE}};
-public class {{pascalCase FEATURE_NAME}}Service { }
-```
-
-**Step 3:** Use CLI commands instead of hardcoded paths
-
-```bash
-# Before (hardcoded)
-cp framework/templates/proposal.md .morph/features/user-auth/proposal.md
+### Local override
 
-# After (CLI)
-morph-spec template render proposal .morph/features/user-auth/proposal.md '{
-  "FEATURE_NAME": "user-auth"
-}'
-```
+A project may shadow any packaged template by placing a file at the same relative path under
+`.morph/framework/templates/{path}`. The local copy wins, and **stops receiving framework
+updates** — only override when the packaged template genuinely does not fit.
 
 ---
 
-## 🎯 Best Practices
-
-### 1. **Use Helpers, Not Pre-computed Variables**
-
-```handlebars
-✅ GOOD:
-{{pascalCase FEATURE_NAME}}Service
-
-❌ BAD:
-{{pascalCase FEATURE_NAME}}Service  // Deprecated, won't work
-```
-
-### 2. **Keep Templates Technology-Agnostic**
-
-```handlebars
-✅ GOOD: code/dotnet/backend/service.cs
-  Works for: dotnet-nextjs, nextjs-neon, future-dotnet-stack
-
-❌ BAD: code/stack-specific/service.cs
-  Locked to one stack only
-```
-
-### 3. **Use Stack Conditionals for Differences**
-
-```handlebars
-{{#if (eq STACK "nextjs-neon")}}
-// Neon-specific implementation
-{{else}}
-// Generic implementation
-{{/if}}
-```
-
-### 4. **Document Applicability in Registry**
-
-```json
-{
-  "technology": "dotnet",
-  "applicableStacks": ["dotnet-nextjs", "nextjs-neon"],
-  "description": "Works with any .NET backend stack"
-}
-```
+## ➕ Adding a template
 
-### 5. **Override Only When Necessary**
+1. Create the file under the right technology directory:
+   `framework/templates/code/{technology}/...` (Handlebars syntax, `.hbs` when the extension
+   would otherwise confuse tooling).
+2. Register it in `REGISTRY.json` with a unique `id`, its `path`, `category`, `technology`
+   and applicable stacks.
+3. If a generator should emit it, add the `id` to the relevant list in
+   `src/lib/generators/scaffold-generator.js`.
 
-```bash
-# Only customize if framework template doesn't meet needs
-morph-spec template customize dotnet-backend-service --stack dotnet-nextjs
+### Deprecating a template
 
-# Otherwise, use framework version (gets updates automatically)
-morph-spec template render dotnet-backend-service output.cs '...'
-```
+Add `"deprecated": true` plus `"deprecationReason"` to its `REGISTRY.json` entry. Keep the
+file until a major version bump.
 
 ---
 
 ## 📚 References
 
-- **Template Registry API:** [`src/lib/template-registry.js`](../../src/lib/template-registry.js)
-- **Template Renderer:** [`src/lib/template-renderer.js`](../../src/lib/template-renderer.js)
-- **Stack Resolver:** [`src/lib/stack-resolver.js`](../../src/lib/stack-resolver.js)
-- **CLI Commands:** [`src/commands/template-*.js`](../../src/commands/)
-- **Handlebars Docs:** https://handlebarsjs.com/
-
----
-
-## 🤝 Contributing
-
-### Adding New Technology
-
-1. Create directory: `framework/templates/code/{technology}/`
-2. Add templates with Handlebars syntax
-3. Register in `REGISTRY.json` with `"technology": "{technology}"`
-4. Test with `morph-spec template render`
-5. Document in this README
-
-### Deprecating Templates
-
-1. Add `"deprecated": true` to `REGISTRY.json`
-2. Add `"deprecationReason": "Reason here"`
-3. Keep file for backward compatibility or remove after major version bump
+- **Registry API:** [`src/core/templates/template-registry.js`](../../src/core/templates/template-registry.js)
+- **Renderer + helpers:** [`src/core/templates/template-renderer.js`](../../src/core/templates/template-renderer.js)
+- **Scaffold generator:** [`src/lib/generators/scaffold-generator.js`](../../src/lib/generators/scaffold-generator.js)
+- **Stack filtering:** [`src/lib/stack-filter.js`](../../src/lib/stack-filter.js)
+- **Handlebars docs:** https://handlebarsjs.com/
 
 ---
 
-**MORPH-SPEC Template System v2.0** - Technology-Based, Future-Proof, DRY ✨
+**MORPH-SPEC Template System** — technology-based, registry-indexed, resolved from the package.