@specverse/engine-realize 3.5.3

package/assets/templates/default/docs/README.md

@@ -0,0 +1,50 @@
+# {{projectName}} Documentation
+
+This directory contains project-specific documentation for your SpecVerse application.
+
+## Documentation Structure
+
+```
+docs/
+├── README.md                           # This file
+├── example-documentation-template.md   # Template for creating documentation
+├── api/                               # API documentation (generated)
+├── diagrams/                          # Generated diagrams
+└── guides/                            # Project-specific guides
+```
+
+## Generated Content
+
+When you run SpecVerse generation commands, documentation will be created in:
+
+- `diagrams/` - UML diagrams (ER, sequence, architecture, lifecycle, deployment)
+- `api/` - API documentation generated from specifications
+
+## SpecVerse Schema Reference
+
+For complete SpecVerse language documentation and schema reference, see:
+
+- **Main Schema**: `../../schema/SPECVERSE-SCHEMA.json`
+- **Schema Guidance**: Maintained in the main project
+
+These files contain the authoritative SpecVerse v3.3 language specification and are maintained in the main project.
+
+## Creating Project Documentation
+
+1. Use `example-documentation-template.md` as a starting point
+2. Run `npm run generate:docs` to generate API documentation
+3. Run `npm run generate:diagrams` to create visual diagrams
+4. Add project-specific guides in the `guides/` directory
+
+## Generation Commands
+
+```bash
+# Generate all documentation
+npm run generate:docs
+
+# Generate diagrams only
+npm run generate:diagrams
+
+# Generate specific diagram types
+npm run generate:diagram:deployment
+```

package/assets/templates/default/docs/api/README.md

@@ -0,0 +1,7 @@
+# API Documentation
+
+Generated API documentation will appear here when you run:
+
+```bash
+npm run generate:docs
+```

package/assets/templates/default/docs/diagrams/README.md

@@ -0,0 +1,85 @@
+# Generated Diagrams
+
+This directory contains auto-generated Mermaid diagrams from your SpecVerse specification.
+
+## Diagram Types
+
+### Entity-Relationship (er-diagram)
+Shows models, attributes, and relationships.
+
+**Generate**: `npm run generate:diagram:er`
+**Best For**: Understanding data structure
+
+### Event-Flow-Layered (event-flow-layered)
+Shows event-driven architecture with topological sorting.
+
+**Generate**: `npm run generate:diagram:event-flow`
+**Best For**: Understanding event flow and component dependencies
+**Features**:
+- Dynamic layer assignment based on dependency depth
+- Topological sorting for proper component ordering
+- Color-coded domain vs application events
+- Simplified labels showing event counts (↑ publishes, ↓ subscribes)
+
+### Lifecycle (lifecycle)
+Shows state machine transitions for model lifecycles.
+
+**Generate**: `npm run generate:diagram:lifecycle`
+**Best For**: Understanding state transitions
+
+### Deployment (deployment-topology)
+Shows deployment instances and capability mappings.
+
+**Generate**: `npm run generate:diagram:deployment`
+**Best For**: Understanding deployment architecture
+
+### Model Architecture (model-architecture)
+Shows component relationships and dependencies.
+
+**Generate**: `npm run generate:diagram:architecture`
+**Best For**: High-level system overview
+
+## Viewing Diagrams
+
+Mermaid diagrams can be viewed in:
+- **GitHub**: Automatically rendered in .md files
+- **VSCode**: Use Markdown Preview Mermaid Support extension
+- **Mermaid Live Editor**: https://mermaid.live/
+- **Documentation Sites**: Most support Mermaid rendering
+
+## Programmatic Generation
+
+```typescript
+import { UnifiedDiagramGenerator, EventFlowPlugin } from '@specverse/lang/diagram-engine';
+import { SpecVerseParser } from '@specverse/lang';
+import { readFileSync, writeFileSync } from 'fs';
+
+// 1. Parse your specification
+const schema = JSON.parse(
+  readFileSync('node_modules/@specverse/lang/schema/SPECVERSE-SCHEMA.json', 'utf8')
+);
+const parser = new SpecVerseParser(schema);
+const parseResult = parser.parseFile('specs/main.specly');
+
+// 2. Create diagram generator with desired plugins
+const generator = new UnifiedDiagramGenerator({
+  plugins: [
+    new EventFlowPlugin(),
+    new ERDiagramPlugin(),
+    new LifecyclePlugin(),
+    new DeploymentPlugin()
+  ],
+  theme: 'default'
+});
+
+// 3. Generate specific diagram type
+const mermaidCode = generator.generate(parseResult.ast, 'event-flow-layered', {
+  title: 'Event Flow Architecture',
+  direction: 'TD'
+});
+
+// 4. Save to file
+writeFileSync('docs/diagrams/event-flow-layered.mmd', mermaidCode);
+```
+
+See [example 11-diagrams documentation](https://github.com/SpecVerse/specverse-lang/tree/main/examples/11-diagrams) for complete API reference and more examples

package/assets/templates/default/docs/example-documentation-template.md

@@ -0,0 +1,269 @@
+# Example Template for SpecVerse Example Documentation
+
+This template provides a consistent structure for documenting SpecVerse examples. Use this when adding new examples to maintain consistency across the documentation.
+
+## Common Structure Pattern
+
+Based on analysis of existing examples, here's the standard structure:
+
+### Basic Structure (for fundamental examples)
+```markdown
+# Example XX-YY: [Descriptive Title]
+
+This example demonstrates [brief description of what the example shows] in SpecVerse.
+
+## Learning Objectives
+
+- [First learning objective]
+- [Second learning objective]
+- [Third learning objective]
+- [Fourth learning objective]
+
+## Key Concepts
+
+### [First Concept Name]
+[Description of the concept with code example]
+```specly
+[code example]
+```
+
+### [Second Concept Name]
+[Description with code example]
+
+## Visual Diagram
+
+import Mermaid from '@site/src/components/Mermaid';
+
+{/* Auto-generated diagram from canonical examples */}
+
+{/* Generated: [TIMESTAMP] */}
+
+<div className="diagram-generated">
+
+<Mermaid chart={`
+[mermaid diagram content]
+`} />
+
+</div>
+
+## Complete Example
+
+### Primary: Specly DSL Format (.specly)
+```specly
+[complete example code]
+```
+
+See the full file: [XX-YY-example-name.specly](./XX-YY-example-name.specly)
+
+### Generated: YAML Format
+The YAML format is automatically generated from the Specly DSL using:
+```bash
+specverse gen yaml XX-YY-example-name.specly -o XX-YY-example-name.yaml
+```
+
+## Key Features Demonstrated
+
+- [Feature 1]
+- [Feature 2]
+- [Feature 3]
+
+## Validation
+
+Test this example:
+```bash
+# Validate the Specly source file
+specverse validate examples/[category]/XX-YY-example-name.specly
+
+# Run full test cycle
+specverse test cycle examples/[category]/XX-YY-example-name.specly
+```
+
+## Next Steps
+
+Continue to [Example XX-YY: Next Example](./XX-YY-next-example) to learn about [next topic].
+
+## Related Examples
+
+- [Example AA-BB: Related Example](../category/AA-BB-related-example) - [Brief description]
+- [Example CC-DD: Another Related](../category/CC-DD-another-related) - [Brief description]
+```
+
+### Advanced Structure (for architecture/domain examples)
+```markdown
+# Example XX-YY: [Descriptive Title]
+
+This [comprehensive/advanced] example demonstrates [complex scenario description] in SpecVerse, showcasing [list of major features].
+
+## Learning Objectives
+
+- [Learning objective focused on real-world application]
+- [Learning objective about integration]
+- [Learning objective about advanced patterns]
+- [Learning objective about scalability]
+
+## Business Domain / Use Case
+
+[Description of the business domain or real-world scenario this example addresses]
+
+## Key Features
+
+### [Feature Category 1]
+```specly
+[code example showing this feature]
+```
+
+### [Feature Category 2] 
+```specly
+[code example]
+```
+
+## Visual Diagram
+
+[Same diagram structure as basic]
+
+## Architecture Patterns
+
+### [Pattern Name 1]
+- [Description of the pattern]
+- [When to use it]
+- [Benefits]
+
+### [Pattern Name 2]
+- [Description]
+- [Implementation details]
+
+## Complete Example
+
+### Primary: Specly DSL Format
+```specly
+[full example]
+```
+
+## Key Features Demonstrated
+
+### V3.1 Core Features
+- [Core feature 1]
+- [Core feature 2]
+
+### Advanced Patterns
+- [Advanced pattern 1]
+- [Advanced pattern 2]
+
+## Business Use Cases
+
+- [Use case 1]
+- [Use case 2]
+
+## Validation
+
+[Same validation structure]
+
+## Next Steps / Related Examples
+
+[Same structure]
+```
+
+### Special Structure (for feature demonstration like steps)
+```markdown
+# Example XX-YY: [Feature Name]
+
+**Example**: `XX-YY-feature-name.specly`  
+**Category**: [Category]  
+**Demonstrates**: [Brief description of the specific feature being demonstrated]
+
+## Overview
+
+[Detailed description of what the feature does and why it's useful]
+
+## Key Features
+
+### [Feature Name] Support
+- **Context 1**: [How it works in first context]
+- **Context 2**: [How it works in second context]  
+- **Context 3**: [How it works in third context]
+
+### Format and Usage
+```yaml
+[example showing the feature syntax]
+```
+
+## Implementation Details
+
+### [Context 1] with [Feature]
+[Description of how the feature is used in this context]
+
+### [Context 2] with [Feature]
+[Description of usage in second context]
+
+## Benefits
+
+### [Benefit Category 1]
+- [Specific benefit 1]
+- [Specific benefit 2]
+
+### [Benefit Category 2]
+- [Specific benefit 3]
+- [Specific benefit 4]
+
+## Schema Validation
+
+[Description of how the feature is validated]
+
+```json
+[schema snippet if relevant]
+```
+
+## Backward Compatibility
+
+[Description of compatibility considerations]
+
+## Usage Guidelines
+
+### When to Use [Feature]
+- [Scenario 1]
+- [Scenario 2]
+
+### Best Practices
+- [Practice 1]
+- [Practice 2]
+
+[Rest follows standard structure]
+```
+
+## Template Usage Instructions
+
+1. **Choose the appropriate structure** based on your example type:
+   - **Basic**: For fundamental concepts (01-fundamentals)
+   - **Advanced**: For architecture/domain examples (03-architecture, 04-domains)
+   - **Special**: For specific feature demonstrations
+
+2. **Replace placeholder content**:
+   - `XX-YY`: Replace with actual example number
+   - `[Descriptive Title]`: Replace with clear, descriptive title
+   - `[Category]`: Replace with category name (Fundamentals, Architecture, etc.)
+   - All bracketed placeholders with actual content
+
+3. **Maintain consistency**:
+   - Use the same section headings across similar examples
+   - Keep code examples properly formatted with ```specly blocks
+   - Include validation commands for all examples
+   - Always link to related examples
+
+4. **Key sections that should always be present**:
+   - Learning Objectives (3-5 bullet points)
+   - Key Concepts (with code examples)
+   - Complete Example (full .specly code)
+   - Validation (with bash commands)
+   - Next Steps / Related Examples
+
+5. **Visual diagrams**: 
+   - Include the standard Mermaid import and structure
+   - The diagram content is auto-generated, so use placeholder text
+   - Always include the "Generated: [TIMESTAMP]" comment
+
+6. **File naming**:
+   - MD file should match .specly file name exactly
+   - Use descriptive, hyphenated names
+   - Follow category numbering convention
+
+This template ensures consistency across all SpecVerse examples while allowing flexibility for different types of content.

package/assets/templates/default/docs/guides/README.md

@@ -0,0 +1,15 @@
+# Project Guides
+
+Add your project-specific documentation and guides here.
+
+## Suggested Structure
+
+- `getting-started.md` - How to set up and run the project
+- `architecture.md` - System architecture overview
+- `deployment.md` - Deployment and scaling guide
+- `api.md` - API usage examples
+- `troubleshooting.md` - Common issues and solutions
+
+## Example
+
+Use `../example-documentation-template.md` as a starting point for creating guides.

package/assets/templates/default/dot.env.example

@@ -0,0 +1,18 @@
+# Database Configuration
+# Default database name is based on project name: spv_{{projectNameKebab}}_dev
+DATABASE_URL="postgresql://{{DB_USER}}:{{DB_PASSWORD}}@localhost:5432/spv_{{projectNameKebab}}_dev"
+
+# API Configuration
+PORT=3000
+NODE_ENV=development
+
+# Frontend Configuration (if using views)
+VITE_API_URL="http://localhost:3000"
+
+# Security (generate secure values for production)
+JWT_SECRET="your-secret-key-here"
+SESSION_SECRET="your-session-secret-here"
+
+# Optional: Override default database user
+# DB_USER=your_username
+# DB_PASSWORD=your_password

package/assets/templates/default/generated/README.md

@@ -0,0 +1,56 @@
+# Generated Directory
+
+This directory contains specifications and artifacts generated by SpecVerse tools.
+
+## Generated Content
+
+When you run SpecVerse generation commands, files will be created here:
+
+### Inferred Specifications
+- **Complete Specifications**: AI-expanded specifications with full architecture
+- **Deployment Specifications**: Environment-specific deployment configurations
+- **Enhanced Specifications**: Minimally enhanced specifications
+
+### Documentation (`docs/` subdirectory)
+- **Generated Documentation**: Markdown documentation for inferred specifications
+- **UML Diagrams**: Entity-relationship and deployment diagrams
+- **API Documentation**: Generated API specifications
+
+### Other Artifacts
+- **Processed YAML**: Processed specification files
+- **Type Definitions**: Generated type definitions
+- **Database Schemas**: SQL DDL scripts and migrations
+
+## Generation Commands
+
+```bash
+# Generate complete specification with docs
+npm run infer
+
+# Generate deployment specifications with docs  
+npm run infer:deployment
+npm run infer:deployment:prod
+
+# Generate minimal enhancements
+npm run infer:minimal
+
+# Generate documentation for existing files
+npm run generate:docs
+npm run generate:diagrams
+```
+
+## Git Ignore
+
+This directory is ignored by git (see `.gitignore`) because generated files should not be committed to version control. They can be recreated from your specifications at any time.
+
+## Cleaning
+
+To clean generated files:
+
+```bash
+# Remove all generated files
+rm -rf generated/*
+
+# Regenerate from specifications
+npm run generate:all
+```