id3-cli 0.9.1

package/templates/skills/id3-identify-entities/references/phase1-greenfield.md

@@ -0,0 +1,319 @@
+# Phase 1: Greenfield Structured Interview -- Detailed Procedures
+
+This document provides the detailed interview procedures for Phase 1 (greenfield structured interview). The lead agent follows these steps to discover the domain's core information model through conversation with the user.
+
+**Important:** This phase is NOT parallelized. The lead agent conducts the interview directly with the user. Domain discovery requires nuanced conversation that cannot be split across agents.
+
+---
+
+## Overview
+
+Phase 1 uses a structured interview approach to systematically discover all entities, attributes, relationships, and business rules for a new project. The interview follows a deliberate sequence: identify things first, then relationships, then rules, and finally validate against universal patterns.
+
+---
+
+## Step 1: Check Existing Artifacts
+
+Before beginning the interview, check if any prior work exists:
+
+1. Read `specs/entity-catalog.md` -- if it contains entity definitions, summarize them
+2. Read `specs/data-model.md` -- if it contains an ERD, display it
+3. Read `steering/product.md` -- if the user has filled in the product vision, use it as context
+
+If artifacts already exist, confirm with the user: "I found existing entity definitions. Should I build on these or start fresh?"
+
+---
+
+## Step 2: Information Identification Questions
+
+The goal is to discover the core "things" (nouns) the system manages.
+
+### Primary Questions
+
+Ask these questions in order. Adapt follow-ups based on the user's responses.
+
+1. **Core entities:** "What are the main 'things' (nouns) this system needs to manage?"
+   - Listen for concrete nouns: users, orders, products, documents, etc.
+   - Probe for hidden entities: "Are there any behind-the-scenes things like settings, configurations, or logs?"
+
+2. **Attributes per entity:** "For each of these things, what information does it contain?"
+   - Focus on the essential attributes, not exhaustive lists
+   - Ask: "What would you need to see on a detail page for this?"
+   - Ask: "What fields would a creation form have?"
+
+3. **Desired outputs:** "What does the user ultimately want to see? What screens, reports, or dashboards are most important?"
+   - This captures the "output image" -- the end result the system should produce
+   - Outputs often reveal hidden entities (e.g., a "sales report" implies aggregation entities)
+   - Follow the "outputs first, inputs later" principle
+
+### Recording During Interview
+
+As the user describes entities, immediately draft entries:
+
+```
+Entity: [Name]
+Description: [one sentence from user's words]
+Attributes (initial):
+  - [attribute]: [inferred type]
+  - [attribute]: [inferred type]
+```
+
+---
+
+## Step 3: Relationship Questions
+
+Discover how entities relate to each other.
+
+### Primary Questions
+
+For each pair of entities that might be related:
+
+1. **Existence of relationship:** "How are [Entity A] and [Entity B] related?"
+   - Not all entities are related; it's okay if they aren't
+
+2. **Cardinality:** "Can one [Entity A] have multiple [Entity B]s, or is it one-to-one?"
+   - Common patterns: 1:1, 1:N, N:M
+   - For N:M, ask: "Does the relationship itself carry any information?" (implies a junction entity)
+
+3. **Delete rules:** "If a [Entity A] is deleted, what should happen to its [Entity B]s?"
+   - CASCADE: Delete children too
+   - SET NULL: Detach children (set FK to null)
+   - RESTRICT: Prevent deletion if children exist
+   - If the user is unsure, suggest the safest default (RESTRICT) and note it as a design decision for Phase 2
+
+4. **Optionality:** "Must every [Entity B] belong to an [Entity A], or can it exist independently?"
+   - This determines whether the FK is nullable
+
+### Recording During Interview
+
+```
+Relationship: [EntityA] -> [EntityB]
+Type: [1:1 | 1:N | N:M]
+Cardinality: [e.g., "one User has many Orders"]
+Delete Rule: [CASCADE | SET NULL | RESTRICT | TBD]
+FK nullable: [yes | no]
+Junction entity (if N:M): [name, if applicable]
+```
+
+---
+
+## Step 4: Rule Questions
+
+Discover business rules, constraints, and behaviors.
+
+### Primary Questions
+
+1. **Mandatory rules:** "Are there any rules this information must always follow?"
+   - Required fields beyond the obvious (e.g., "orders must have at least one line item")
+   - Value range restrictions (e.g., "quantity must be positive")
+   - Uniqueness constraints (e.g., "email must be unique per organization")
+
+2. **State transitions:** "Does anything have a lifecycle or status flow? For example: draft -> published -> archived"
+   - For each state machine, capture:
+     - Possible states
+     - Allowed transitions (which state can go to which)
+     - Trigger for each transition (user action, time-based, condition-based)
+     - Side effects of transitions (notifications, cascade updates)
+
+3. **Computed/derived values:** "Are there any values that are calculated from other values?"
+   - Examples: total price = sum of line items, full name = first + last
+   - Capture the formula or derivation logic
+   - Determine: stored (materialized) or computed on-the-fly?
+
+4. **Conditional rules:** "Are there rules that apply only in certain situations?"
+   - Context-dependent validation
+   - Role-based access patterns
+   - Time-based constraints
+
+### Recording During Interview
+
+```
+Rule: BR-[number]
+Entity: [related entity]
+Type: Constraint | Derivation | Transition | Validity
+Description: [what the rule says]
+Details: [formula, allowed transitions, conditions, etc.]
+```
+
+---
+
+## Step 5: Silverston Universal Pattern Checklist
+
+After the interview, cross-reference discovered entities against Len Silverston's universal data model patterns. This catches common domain concepts the user may have forgotten to mention.
+
+### Checklist
+
+Go through each pattern and ask if it applies:
+
+- [ ] **Party** (person, organization, role)
+  - "Does the system manage different types of people or organizations? Do they have different roles?"
+  - Common sub-patterns: User, Employee, Customer, Organization, Role, Permission
+
+- [ ] **Product/Service** (product, service, catalog)
+  - "Does the system deal with products, services, or things that can be offered/sold?"
+  - Common sub-patterns: Product, Service, Catalog, Category, Pricing, Variant
+
+- [ ] **Order/Transaction** (order, transaction, event)
+  - "Are there transactions, orders, or events that need to be recorded?"
+  - Common sub-patterns: Order, OrderLine, Payment, Invoice, Transaction
+
+- [ ] **Classification/Category** (classification, tag, category)
+  - "Do any entities need to be categorized, tagged, or classified?"
+  - Common sub-patterns: Category, Tag, Label, Type (reference tables)
+
+- [ ] **Status/Lifecycle** (status, stage, transition)
+  - "Do any entities go through stages or have a status that changes over time?"
+  - Already captured in Step 4, but verify completeness
+
+- [ ] **Hierarchy** (hierarchy, tree, parent-child)
+  - "Are there any tree-like structures? Categories within categories? Organizations within organizations?"
+  - Common patterns: self-referencing FK, nested set, materialized path
+
+- [ ] **Contact Mechanism** (email, phone, address)
+  - "Do you need to store contact information? Multiple emails or phones per person?"
+  - Pattern decision: embedded in Party entity vs. separate ContactMechanism entity
+
+- [ ] **Document/Content** (document, content, attachment)
+  - "Does the system manage documents, files, or rich content?"
+  - Storage decision: inline vs. object storage (S3/GCS) -- note for Phase 2
+
+### Gap Analysis
+
+For any pattern that reveals a missing entity:
+1. Explain to the user what was found
+2. Ask: "Should we include this in the model?"
+3. If yes, add the entity and repeat Steps 2-4 for it
+
+---
+
+## Artifact Generation
+
+### specs/entity-catalog.md
+
+For each entity:
+
+```markdown
+## Entity: [Name]
+- **Description**: [one sentence in the user's own words]
+- **Attributes**:
+  | Name | Type | Required | Constraints | Notes |
+  |------|------|----------|-------------|-------|
+  | id | UUID | Yes | PK | Primary key |
+  | ... | ... | ... | ... | ... |
+- **Relationships**:
+  | Target | Type | Cardinality | Delete Rule |
+  |--------|------|-------------|-------------|
+  | ... | ... | ... | ... |
+- **State Transitions**: [if applicable]
+  - [State A] -> [State B]: [trigger/condition]
+  - [State B] -> [State C]: [trigger/condition]
+- **Business Rules**: BR-001, BR-003 [reference numbers]
+```
+
+### specs/data-model.md
+
+```markdown
+---
+version: "0.1"
+last_verified: "YYYY-MM-DD"
+phase: "Phase 1 Complete"
+entity_count: N
+rule_count: N
+audit_status: "clean"
+---
+
+# Data Model
+
+## ER Diagram
+
+\`\`\`mermaid
+erDiagram
+  ENTITY_A ||--o{ ENTITY_B : "relationship description"
+  ENTITY_A {
+    uuid id PK
+    string name
+    timestamp created_at
+  }
+  ENTITY_B {
+    uuid id PK
+    uuid entity_a_id FK
+    string title
+  }
+\`\`\`
+
+## Index Strategy
+
+(To be filled in Phase 2)
+
+## Design Decision Log
+
+| Decision ID | Subject | Choice | Reason | Date |
+|-------------|---------|--------|--------|------|
+| (To be filled in Phase 2) | | | | |
+```
+
+### docs/business-rules.md
+
+```markdown
+### BR-001: [Rule Name]
+- **Entity**: [related entity]
+- **Type**: Constraint | Derivation | Transition | Validity
+- **Description**: [rule description]
+- **Enforcement Location**: (To be determined in Phase 2)
+- **Implementation**: (To be determined in Phase 2)
+```
+
+---
+
+## Interview Best Practices
+
+1. **Use the user's language:** Record entities and attributes using the terms the user actually uses. Build the ubiquitous language naturally.
+
+2. **Don't over-engineer:** Phase 1 captures the conceptual model. Detailed data types, indexes, and storage decisions come in Phase 2.
+
+3. **Capture uncertainty:** If the user says "maybe" or "I'm not sure," record it with a note. Don't force premature decisions.
+
+4. **Show progress:** After every 3-4 entities, show the current ERD to the user. Visual feedback keeps the conversation grounded.
+
+5. **Know when to stop:** Phase 1 is complete when:
+   - All core entities are identified
+   - Major relationships are mapped
+   - Key business rules are captured
+   - The Silverston checklist has been reviewed
+   - The user confirms the model looks right
+
+6. **Update domain glossary:** As new terms emerge, add them to `docs/domain-glossary.md` with clear definitions. This is the ubiquitous language dictionary.
+
+---
+
+## Preview Integration
+
+After completing the interview and generating artifacts:
+
+1. Generate the ERD from `specs/data-model.md` Mermaid content
+2. Write it to `.iddd/preview/erd-phase1.html`
+3. Start the preview server and display the URL
+4. Walk the user through the visual ERD for final confirmation
+
+---
+
+## Completion
+
+Update version headers in `specs/entity-catalog.md` and `specs/data-model.md`:
+- `version: "0.1"`
+- `phase: "Phase 1 Complete"`
+- `last_verified: "YYYY-MM-DD"`
+- `entity_count` and `rule_count` with actual counts
+
+Add an entry to `docs/model-changelog.md`:
+
+```markdown
+## [0.1] -- YYYY-MM-DD
+### Phase 1 Complete
+- N entities identified through structured interview
+- M relationships mapped
+- K business rules recorded
+- Silverston checklist reviewed
+```
+
+Output the completion message with entity count, relationship count, and business rule count. Advise the user to proceed to Phase 2 (information design) with "design information" or use `/id3-spawn-team` if they want to compose a downstream Agent Team.

package/templates/skills/id3-info-audit/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: id3-info-audit
+description: >
+  Run a comprehensive information model audit. Compares entity-catalog.md against
+  the actual codebase, checks business rule enforcement, UI consistency, version
+  headers, and hook bypass history. Produces a visual audit report.
+  Trigger: info audit, information audit, model audit, audit entities,
+  check consistency, verify model, run audit
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+user-invocable: true
+---
+
+# Information Model Audit
+
+You are the lead agent performing an IDDD information model audit. This skill systematically compares the declared information model (`specs/entity-catalog.md`) against the actual codebase, business rule enforcement, UI consistency, and operational hygiene. The output is a structured audit report with per-entity verdicts.
+
+## Prerequisites
+
+Before starting, verify:
+1. `specs/entity-catalog.md` exists and contains at least one entity.
+2. `specs/data-model.md` exists.
+
+If prerequisites are not met, respond:
+
+> "No information model found. Run 'identify entities' (Phase 0/1) first to create the entity catalog."
+
+---
+
+## Audit Procedure
+
+Execute the following 6 steps in order. Do not skip any step.
+
+### Step 1: Entity List Extraction
+
+1. Read `specs/entity-catalog.md` and extract the full list of declared entities.
+2. For each entity, record: name, attribute count, relationship count, associated business rules (BR-xxx references).
+3. Read `specs/data-model.md` and cross-reference: every entity in the catalog must appear in the ERD, and vice versa.
+4. Flag any discrepancies between entity-catalog.md and data-model.md.
+
+**Output:** Entity checklist with catalog-ERD consistency status.
+
+### Step 2: Codebase Scan
+
+For each declared entity, scan the codebase for its implementation:
+
+1. **Model/schema files:** Search for entity name in ORM definitions, migration files, and schema declarations. Verify:
+   - All declared attributes exist in the implementation.
+   - Data types match the spec (entity-catalog.md types vs actual implementation types).
+   - Constraints match (NOT NULL, UNIQUE, DEFAULT, CHECK).
+   - Indexes declared in data-model.md are present.
+
+2. **Unimplemented entities:** Entities in entity-catalog.md with no corresponding code implementation.
+
+3. **Undeclared models:** Code-level models/tables not present in entity-catalog.md (schema drift).
+
+4. **Business rule enforcement:** For each BR-xxx in `docs/business-rules.md`:
+   - Check if the rule is enforced at the declared location (DB constraint, application logic, or both).
+   - Search for validation patterns (Zod, Yup, Joi, Pydantic, @Valid, etc.) and match against declared rules.
+   - Flag rules with no detectable enforcement.
+
+**Verdict per entity:**
+- `PASS` -- All attributes, types, constraints, and rules match.
+- `WARN` -- Minor discrepancies (naming convention differences, missing non-critical indexes).
+- `FAIL` -- Missing attributes, wrong types, missing constraints, or unenforced rules.
+
+### Step 3: UI Consistency Check
+
+If `specs/output-designs.md` exists, check UI implementations:
+
+1. **Unimplemented screens:** Screen proposals in output-designs.md with no corresponding UI code.
+2. **Undeclared screens:** UI routes/pages not referenced in output-designs.md.
+3. **Form field mapping:** For each form in the UI, verify fields correspond to entity attributes. Flag fields that do not map to any declared attribute.
+4. **Navigation paths:** Verify relationship navigation links match the declared entity relationships.
+
+If `specs/output-designs.md` does not exist, skip this step and note it in the report.
+
+**Verdict per screen:**
+- `PASS` -- Screen matches output-designs.md proposal.
+- `WARN` -- Minor deviations (styling, layout differences).
+- `FAIL` -- Missing fields, wrong entity mapping, broken navigation.
+
+### Step 4: Version Header Verification
+
+Read YAML frontmatter from `specs/entity-catalog.md` and `specs/data-model.md`:
+
+1. Check `last_verified` date. If more than 7 days ago (or empty), flag as stale.
+2. Check `version` consistency between entity-catalog.md and data-model.md.
+3. Check `entity_count` matches the actual number of entities in the file.
+4. Check `rule_count` matches the actual number of rules in business-rules.md.
+
+Update frontmatter:
+```yaml
+last_verified: "YYYY-MM-DD"  # today's date
+audit_status: "clean" | "warnings" | "failures"
+entity_count: N  # actual count
+rule_count: N  # actual count
+```
+
+### Step 5: Hook Bypass History
+
+Check `.iddd/skip-history.log` for hook bypass events:
+
+1. If the file exists, read all entries.
+2. Count bypasses since the last audit (based on `last_verified` date).
+3. For each bypass, check if the bypassed check has been subsequently resolved:
+   - Schema drift bypasses: was entity-catalog.md updated afterward?
+   - Rule check bypasses: was business-rules.md updated afterward?
+4. Flag unresolved bypasses.
+
+If `.iddd/skip-history.log` does not exist or is empty, record "No hook bypasses detected."
+
+### Step 6: Audit Report Generation
+
+Compile findings into a structured report.
+
+**Console output format:**
+
+```
+┌─ Information Model Audit Report ─────────────┐
+│                                               │
+│  Date: YYYY-MM-DD                             │
+│  Entities: N declared, M implemented          │
+│  Rules: K declared, J enforced                │
+│                                               │
+│  Entity Results:                              │
+│  ✅ User           - all checks passed        │
+│  ⚠️ Order          - missing index on status  │
+│  ❌ Notification   - not implemented          │
+│                                               │
+│  UI Results:                                  │
+│  ✅ User List      - matches spec             │
+│  ❌ Order Detail   - missing 3 fields         │
+│                                               │
+│  Rule Enforcement:                            │
+│  ✅ BR-001 through BR-008 - enforced          │
+│  ❌ BR-009 - no enforcement found             │
+│                                               │
+│  Hook Bypasses: 2 unresolved                  │
+│  Version Headers: updated                     │
+│                                               │
+│  Overall: ⚠️ WARNINGS (3 warn, 2 fail)       │
+│                                               │
+└───────────────────────────────────────────────┘
+```
+
+**Verdict symbols:**
+- `✅` -- Passed. Entity/screen/rule fully consistent.
+- `⚠️` -- Warning. Minor issues that should be addressed.
+- `❌` -- Failed. Significant discrepancy requiring immediate attention.
+
+**Overall verdict:**
+- `CLEAN` -- All checks passed.
+- `WARNINGS` -- Only warnings, no failures.
+- `FAILURES` -- One or more failures detected.
+
+---
+
+## Preview Integration
+
+After generating the console report, create a visual audit dashboard:
+
+1. Generate `.iddd/preview/audit-{date}.html` (where `{date}` is today in YYYY-MM-DD format).
+2. The HTML should include:
+   - Summary statistics (entity count, rule count, pass/warn/fail counts).
+   - Per-entity card layout with status badge (green/yellow/red).
+   - Expandable details for each entity showing specific findings.
+   - Business rule coverage visualization.
+   - Hook bypass timeline (if any).
+3. Start the preview server and display the URL:
+
+```
+┌─ 📊 Audit Report Ready ─────────────────────┐
+│                                               │
+│  Dashboard: http://localhost:PORT/audit       │
+│  File: .iddd/preview/audit-YYYY-MM-DD.html   │
+│                                               │
+└───────────────────────────────────────────────┘
+```
+
+---
+
+## Completion
+
+After the audit is complete:
+
+1. Version headers in entity-catalog.md and data-model.md have been updated (Step 4).
+2. The audit report is displayed in the console.
+3. The preview HTML is generated and the server URL is displayed.
+4. Display a summary message:
+
+> "Audit complete. N entities checked: X passed, Y warnings, Z failures. See the dashboard at http://localhost:PORT/audit or open .iddd/preview/audit-{date}.html directly."

package/templates/skills/id3-preview/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: id3-preview
+description: >
+  Start the IDDD preview server to view ERD diagrams, UI mockups, and audit
+  reports in the browser. Generates HTML from current specs/ files and serves
+  existing .iddd/preview/ files.
+  Trigger: preview, start preview, show ERD, view model, visual preview,
+  open preview, show diagram, render ERD
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+user-invocable: true
+---
+
+# IDDD Preview Server
+
+You are the lead agent starting the IDDD visual preview system. This skill generates HTML renderings of the information model (ERD, UI mockups, audit reports) and serves them via a local HTTP server for browser-based review.
+
+## What This Skill Does
+
+1. Reads current `specs/` files and generates interactive HTML previews.
+2. Serves existing files in `.iddd/preview/` alongside newly generated ones.
+3. Starts a local HTTP server and displays the URL for browser access.
+
+---
+
+## Procedure
+
+### Step 1: Check for Existing Previews
+
+Scan `.iddd/preview/` for existing HTML files:
+
+```bash
+ls -la .iddd/preview/*.html 2>/dev/null
+```
+
+List any existing files to the user so they know what is already available.
+
+### Step 2: Generate Previews from Current Specs
+
+Generate or regenerate HTML previews based on the current state of spec files.
+
+#### ERD Preview
+
+If `specs/data-model.md` exists and contains a Mermaid ERD code block:
+
+1. Extract the Mermaid ERD code block from `specs/data-model.md`.
+2. Generate `.iddd/preview/erd.html` with the following structure:
+   - HTML5 document with Mermaid.js loaded from CDN (`https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js`).
+   - Mermaid configuration: `startOnLoad: false`, `maxTextSize: 200000` (for large ERDs).
+   - Explicit `mermaid.run()` call after DOM load.
+   - Dark/light theme toggle button.
+   - Entity click handler that displays entity details from `specs/entity-catalog.md` in a side panel.
+   - Responsive layout that works on various screen sizes.
+
+#### UI Mockup Preview
+
+If `specs/output-designs.md` exists and contains screen proposals:
+
+1. Extract screen proposals from `specs/output-designs.md`.
+2. Generate `.iddd/preview/mockup.html` with:
+   - HTML/CSS wireframe rendering of each proposed screen.
+   - Navigation links between screens (based on entity relationships).
+   - Entity-screen mapping highlights.
+   - Each screen clearly labeled with its entity context.
+
+#### Audit Preview
+
+If any `audit-*.html` file exists in `.iddd/preview/`, it will be served as-is. To generate a new audit report, use `/id3-info-audit` instead.
+
+### Step 3: Start the Preview Server
+
+Start a local HTTP server to serve the `.iddd/preview/` directory:
+
+```bash
+node -e "
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+
+const dir = path.resolve('.iddd/preview');
+const mime = { '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript', '.json': 'application/json', '.png': 'image/png', '.svg': 'image/svg+xml' };
+
+const server = http.createServer((req, res) => {
+  const url = req.url === '/' ? '/index.html' : req.url;
+  const filePath = path.join(dir, url);
+  const ext = path.extname(filePath);
+  fs.readFile(filePath, (err, data) => {
+    if (err) {
+      // Try with .html extension
+      fs.readFile(filePath + '.html', (err2, data2) => {
+        if (err2) {
+          res.writeHead(404);
+          res.end('Not found');
+        } else {
+          res.writeHead(200, { 'Content-Type': 'text/html' });
+          res.end(data2);
+        }
+      });
+    } else {
+      res.writeHead(200, { 'Content-Type': mime[ext] || 'text/plain' });
+      res.end(data);
+    }
+  });
+});
+
+server.listen(0, () => {
+  const port = server.address().port;
+  console.log('Preview server running at http://localhost:' + port);
+});
+"
+```
+
+The server uses `listen(0)` so the OS assigns an available port automatically.
+
+### Step 4: Generate Index Page
+
+Create `.iddd/preview/index.html` as a landing page that links to all available previews:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>IDDD Preview</title>
+  <style>
+    body { font-family: system-ui, sans-serif; max-width: 800px; margin: 2rem auto; padding: 0 1rem; }
+    h1 { border-bottom: 2px solid #333; padding-bottom: 0.5rem; }
+    .card { border: 1px solid #ddd; border-radius: 8px; padding: 1rem; margin: 1rem 0; }
+    .card h2 { margin-top: 0; }
+    a { color: #0066cc; }
+  </style>
+</head>
+<body>
+  <h1>IDDD Preview Dashboard</h1>
+  <!-- Links to erd.html, mockup.html, audit-*.html -->
+</body>
+</html>
+```
+
+Populate the links dynamically based on which files exist in `.iddd/preview/`.
+
+### Step 5: Display Server URL
+
+After the server starts, display the access information:
+
+```
+┌─ Preview Ready ──────────────────────────────┐
+│                                               │
+│  Dashboard:  http://localhost:PORT             │
+│  ERD:        http://localhost:PORT/erd         │
+│  Mockup:     http://localhost:PORT/mockup      │
+│                                               │
+│  Files: .iddd/preview/                        │
+│                                               │
+│  Press Ctrl+C to stop the server.             │
+│                                               │
+└───────────────────────────────────────────────┘
+```
+
+Only show links for files that actually exist.
+
+---
+
+## Notes
+
+- **Port assignment:** The server always uses `listen(0)` for automatic port selection. Do not hardcode a port number.
+- **File persistence:** All generated HTML files remain in `.iddd/preview/` after the server stops. Users can open them directly in a browser without the server.
+- **Regeneration:** Running this skill again regenerates previews from the latest specs. Existing audit HTML files are preserved (they are generated by `/id3-info-audit`).
+- **No external dependencies:** The server uses only Node.js built-in modules. Mermaid.js is loaded from CDN in the generated HTML.