🚀 Major Framework Optimization: Token Efficiency & True Opt-Out Template System

.cursor-init.example.yaml

@@ -2,11 +2,11 @@
 # Copy this file to .cursor-init.yaml in your project root to customize documentation generation
 
 # =============================================================================
-# DOCUMENTATION TYPES - Opt-out configuration (all auto-detected by default)
+# DOCUMENTATION TYPES - Opt-out configuration (AI determines relevance by default)
 # =============================================================================
 
-# Zero-config behavior: All documentation types are auto-detected and generated
-# if they would be useful for your project. Set to 'false' to disable specific types.
+# Zero-config behavior: AI analyzes your project and generates relevant documentation
+# automatically. Only set to 'false' to explicitly disable specific types.
 
 documentation:
   # Core documentation (always useful for any project)
@@ -15,9 +15,23 @@ documentation:
     onboarding: true # Developer onboarding guide
     adr: true # Architecture Decision Records
 
-  # Data documentation (auto-detected based on database models)
+  # Data documentation (generated if database models detected)
   data:
-    data_model: true # Database schema & ER diagrams (if models found)
+    data_model: true # Database schema & ER diagrams (auto-generated if models found)
+    database_ops: false # Database operations & performance guide (disabled by default)
+    data_security: false # Data security policies & procedures (disabled by default)
+
+  # Infrastructure documentation (generated if deployment configs detected)
+  infrastructure:
+    deployment: false # CI/CD & deployment procedures (disabled by default)
+    dependencies: false # External service dependencies (disabled by default)
+    security: false # Security architecture & authentication flows (disabled by default)
+
+  # Development documentation (generated if collaborative development detected)
+  development:
+    rfc: false # Request For Comments documents (disabled by default)
+    contributing: false # Contributor guidelines (disabled by default)
+    api_docs: false # API documentation (disabled by default)
 
 # =============================================================================
 # TEMPLATE VARIANTS - Choose specific template styles
@@ -36,6 +50,14 @@ templates:
   # Data model documentation
   data_model: "comprehensive" # Options: simple, comprehensive
 
+  # Request For Comments
+  rfc: "standard" # Options: minimal, standard, detailed
+
+  # Custom template paths (optional)
+  custom_template_paths:
+    # adr: "path/to/custom/adr-template.md"
+    # rfc: "path/to/custom/rfc-template.md"
+
 # =============================================================================
 # PROJECT SETTINGS - Project-specific customization
 # =============================================================================
@@ -65,20 +87,40 @@ generation:
 # =============================================================================
 
 # Zero-config (default behavior):
-# - Analyzes your project automatically using AI
-# - Generates useful documentation based on what's detected
+# - AI analyzes your project to determine relevant documentation
+# - Generates documentation automatically based on detected technologies
 # - Perfect for most projects - no configuration needed!
+# - Core docs (architecture, onboarding, ADRs) always generated unless disabled
+# - Other docs generated only if relevant technologies detected
 
 # Minimal documentation only:
 # documentation:
 #   core: { architecture: true, onboarding: true, adr: true }
 #   data: { data_model: false }
+#   infrastructure: { deployment: false, dependencies: false, security: false }
+#   development: { rfc: false, contributing: false, api_docs: false }
 
 # Open source project:
+# documentation:
+#   core: { architecture: true, onboarding: true, adr: true }
+#   development: { contributing: true }
 # templates:
 #   onboarding: "contributor"  # Contributor-focused onboarding
 
 # Enterprise project:
+# documentation:
+#   core: { architecture: true, onboarding: true, adr: true }
+#   data: { data_model: true, database_ops: true, data_security: true }
+#   infrastructure: { deployment: true, dependencies: true, security: true }
+#   development: { rfc: true, api_docs: true }
 # templates:
 #   architecture: "enterprise"
 #   adr: "full"
+#   rfc: "detailed"
+
+# Full documentation setup:
+# documentation:
+#   core: { architecture: true, onboarding: true, adr: true }
+#   data: { data_model: true, database_ops: true, data_security: true }
+#   infrastructure: { deployment: true, dependencies: true, security: true }
+#   development: { rfc: true, contributing: true, api_docs: true }

.cursor/README.md

@@ -8,7 +8,7 @@ This folder contains an intelligent documentation generation system that works s
 
 ```bash
 # Copy the .cursor/ folder to your project
-cp -r path/to/ai-cursor-init/.cursor/ your-project/
+cp -r path/to/ai-cursor-init/.cursor/ your-project/.cursor/
 
 # Open your project in Cursor and type:
 /init-docs

.cursor/rules/cursor-init/context/adr-context.mdc

@@ -1,8 +1,10 @@
 ---
-description: 
+description: When the user asks about ADRs, architecture decisions, or decision documentation
 globs: 
-alwaysApply: true
+alwaysApply: false
 ---
+# ADR Context and Best Practices
+
 When the user asks about ADRs, architecture decisions, or decision documentation, I should provide context about:
 
 **ADR Concept:**

.cursor/rules/cursor-init/context/architecture-context.mdc

@@ -1,8 +1,10 @@
 ---
-description: 
+description: When the user asks about architecture, system design, components, or how the system works
 globs: 
-alwaysApply: true
+alwaysApply: false
 ---
+# Architecture Context Provider
+
 When the user asks about architecture, system design, components, or how the system works, I should:
 
 1. Check if `docs/architecture.md` exists using the `read_file` tool

.cursor/rules/cursor-init/context/docs-context.mdc

@@ -3,6 +3,8 @@ description:
 globs: 
 alwaysApply: true
 ---
+# Documentation Framework Context
+
 When the user asks about documentation, available commands, or the cursor-init framework, I should provide context about:
 
 **Available Slash Commands:**
@@ -26,11 +28,18 @@ When the user asks about documentation, available commands, or the cursor-init f
 
 **Framework Features:**
 - Template-based generation with multiple variants per document type
+- Custom template support via `.cursor-init.yaml` configuration
+- Default templates available in `.cursor/templates/` directory
 - Mermaid diagram integration for version-controlled visuals
-- Language/framework detection (Python/FastAPI, TypeScript/React)
-- CI integration for documentation freshness checks
+- Language/framework agnostic
 - Zero-installation setup via Cursor rules and templates
 
+**Template System:**
+- **Default Templates**: Located in `.cursor/templates/[type]/` with template variants
+- **Custom Templates**: Configure custom paths in `.cursor-init.yaml` under `templates.custom_template_paths`
+- **Template Selection**: Choose variants via `templates.[type]` configuration (e.g., `templates.rfc: "detailed"`)
+- **Placeholder System**: Templates use `{{PLACEHOLDER}}` syntax for dynamic content replacement
+
 **Philosophy:**
 - Documentation as code - stored in version control alongside source
 - Living documentation that stays in sync with codebase changes

.cursor/rules/cursor-init/diagrams/gen-arch-diagram.mdc

@@ -1,27 +1,27 @@
 ---
-description: 
+description: When the user types `/gen-arch-diagram` to generate system architecture diagrams from project structure
 globs: 
-alwaysApply: true
+alwaysApply: false
 ---
-@if(user_message.starts_with("/gen-arch-diagram")) {
-  "I will generate a system architecture diagram from your project's structure.
+# Generate Architecture Diagram
 
-  1. **Analyzing Project Structure:** I will examine your project's top-level directories to identify the main components and their roles.
+I will generate a system architecture diagram from your project's structure.
 
-  2. **Component Classification:** I will classify each directory based on its name and contents:
-     - Documentation directories (docs, documentation)
-     - CLI/Command directories (cli, cmd, commands)
-     - Template directories (templates, template)
-     - Source code directories (src, source)
-     - Frontend/UI directories (frontend, ui, web)
-     - Backend directories (backend, server, app)
-     - Database/Model directories (database, db, models)
+1. **Analyzing Project Structure:** I will examine your project's top-level directories to identify the main components and their roles.
 
-  3. **Generating Mermaid Architecture Diagram:** Based on the identified components, I will create a Mermaid `graph TD` (Top-Down) flowchart showing the main architectural components and their relationships.
+2. **Component Classification:** I will classify each directory based on its name and contents:
+   - Documentation directories (docs, documentation)
+   - CLI/Command directories (cli, cmd, commands)
+   - Template directories (templates, template)
+   - Source code directories (src, source)
+   - Frontend/UI directories (frontend, ui, web)
+   - Backend directories (backend, server, app)
+   - Database/Model directories (database, db, models)
 
-  4. **Suggesting Integration:** If `docs/architecture.md` exists, I will suggest adding the diagram to that file for better documentation.
+3. **Generating Mermaid Architecture Diagram:** Based on the identified components, I will create a Mermaid `graph TD` (Top-Down) flowchart showing the main architectural components and their relationships.
 
-  Let me start by analyzing your project structure..."
+4. **Suggesting Integration:** If `docs/architecture.md` exists, I will suggest adding the diagram to that file for better documentation.
 
-  I will use the `list_dir` tool to examine the project structure, then use `edit_file` to create or suggest updates to architecture documentation.
-}
+Let me start by analyzing your project structure...
+
+I will use the `list_dir` tool to examine the project structure, then use `edit_file` to create or suggest updates to architecture documentation.

.cursor/rules/cursor-init/diagrams/gen-dependency-diagram.mdc

@@ -1,5 +1,5 @@
 ---
-description: When the user types `/gen-dependency-diagram`
+description: When the user types `/gen-dependency-diagram` to generate diagrams showing external dependencies and service integrations
 globs: 
 alwaysApply: false
 ---

.cursor/rules/cursor-init/diagrams/gen-deployment-diagram.mdc

@@ -1,5 +1,5 @@
 ---
-description: When the user types `/gen-deployment-diagram`
+description: When the user types `/gen-deployment-diagram` to generate deployment diagrams using infrastructure components
 globs: 
 alwaysApply: false
 ---

.cursor/rules/cursor-init/diagrams/gen-er-diagram.mdc

@@ -1,28 +1,30 @@
 ---
-description: 
+description: When the user types `/gen-er-diagram` to generate entity relationship diagrams from database models
 globs: 
-alwaysApply: true
+alwaysApply: false
 ---
-@if(user_message.starts_with("/gen-er-diagram")) {
-  "I will generate an ER diagram from database models found in your project.
+# Generate ER Diagram
 
-  1. **Scanning for SQLAlchemy Models:** I will search your codebase for database model definitions using semantic search and grep patterns to find files containing model imports and model classes.
+I will generate an ER diagram from database models found in your project, respecting your configuration.
 
-  2. **Extracting Schema Information:** I will analyze the found models to extract:
-     - Table names and their corresponding classes
-     - Column names, data types, and constraints
-     - Primary key relationships
-     - Foreign key relationships between tables
+1. **Check Configuration:** I will first read `.cursor-init.yaml` to verify if `documentation.data.data_model` is explicitly disabled. If disabled (`false`), I will inform you that ER diagram generation is disabled for this project.
 
-  3. **Check Template Configuration:** I will read `.cursor-init.yaml` to determine which data model template variant to use:
-     - `simple` - Basic ER diagram with entity overview
-     - `comprehensive` (default) - Detailed data model with full database documentation
+2. **Scanning for SQLAlchemy Models:** If not disabled, I will search your codebase for database model definitions using semantic search and grep patterns to find files containing model imports and model classes.
 
-  4. **Generating Mermaid ER Diagram:** Based on the extracted schema information, I will create a valid Mermaid `erDiagram` with proper syntax for entities, attributes, and relationships.
+3. **Extracting Schema Information:** I will analyze the found models to extract:
+   - Table names and their corresponding classes
+   - Column names, data types, and constraints
+   - Primary key relationships
+   - Foreign key relationships between tables
 
-  5. **Storing the Diagram:** The generated diagram will be saved to `docs/data-model.md` using the configured data model template variant, creating the file if it doesn't exist or overwriting it if it does.
+4. **Check Template Configuration:** I will use the configuration from `.cursor-init.yaml` to determine which data model template variant to use:
+   - `simple` - Basic ER diagram with entity overview
+   - `comprehensive` (default) - Detailed data model with full database documentation
 
-  Let me start by searching for database models in your project..."
+5. **Generating Mermaid ER Diagram:** Based on the extracted schema information, I will create a valid Mermaid `erDiagram` with proper syntax for entities, attributes, and relationships.
 
-  I will use the `codebase_search` and `grep_search` tools to find SQLAlchemy models, then use `read_file` to check template configuration, and `edit_file` to create the ER diagram documentation using the appropriate template variant.
-}
+6. **Storing the Diagram:** The generated diagram will be saved to `docs/data-model.md` using the configured data model template variant, creating the file if it doesn't exist or overwriting it if it does (unless `documentation.data.data_model` is disabled).
+
+Let me start by checking your configuration and searching for database models in your project...
+
+I will first use the `read_file` tool to check `.cursor-init.yaml` configuration, then if data model documentation is not disabled, I'll use `codebase_search` and `grep_search` tools to find SQLAlchemy models, and `edit_file` to create the ER diagram documentation using the appropriate template variant.

.cursor/rules/cursor-init/diagrams/gen-onboarding-diagram.mdc

@@ -1,5 +1,5 @@
 ---
-description: When the user types `/gen-onboarding-diagram`
+description: When the user types `/gen-onboarding-diagram` to create developer onboarding and setup workflow diagrams
 globs: 
 alwaysApply: false
 ---

.cursor/rules/cursor-init/diagrams/gen-security-diagram.mdc

@@ -1,5 +1,5 @@
 ---
-description: When the user types `/gen-security-diagram`
+description: When the user types `/gen-security-diagram` to generate diagrams using the codebase security-related features
 globs: 
 alwaysApply: false
 ---

.cursor/rules/cursor-init/documentation/adr.mdc

@@ -1,18 +1,21 @@
 ---
-description: 
+description: When the user types `/adr` to generate a new Architecture Decision Record
 globs: 
-alwaysApply: true
+alwaysApply: false
 ---
 # ADR Creation Command
 
 When user types `/adr` followed by a title, create a new Architecture Decision Record:
 
 ## Process
-1. **Extract Title**: Get text after `/adr` or use `untitled-adr` as default
-2. **Determine Number**: Check `docs/adr/` directory for highest existing ADR number and increment
-3. **Select Template**: Check `.cursor-init.yaml` for template variant (nygard_style, full, lightweight, madr)
-4. **Gather Context**: Use codebase search to find relevant information for the ADR topic
-5. **Create File**: Generate ADR in `docs/adr/` with format `000X-sanitized-title.md`
+1. **Check Configuration**: First verify if `documentation.core.adr` is explicitly disabled in `.cursor-init.yaml`. If disabled (`false`), inform that ADR creation is disabled for this project.
+2. **Extract Title**: Get text after `/adr` or use `untitled-adr` as default
+3. **Determine Number**: Check `docs/adr/` directory for highest existing ADR number and increment
+4. **Select Template**: Check `.cursor-init.yaml` for template variant (nygard_style, full, lightweight, madr)
+5. **Load Template**: Read the appropriate template file from `.cursor/templates/adr/` or use a custom template path if configured
+6. **Gather Context**: Use codebase search to find relevant information for the ADR topic
+7. **Replace Placeholders**: Populate the template with the title, number, and context information
+8. **Create File**: Generate ADR in `docs/adr/` with format `000X-sanitized-title.md` (unless ADR documentation is disabled)
 
 ## Template Configuration
 ```yaml

.cursor/rules/cursor-init/documentation/check-docs.mdc

@@ -1,12 +1,13 @@
 ---
-description: 
+description: When the user types `/check-docs` to validate documentation freshness and completeness
 globs: 
-alwaysApply: true
+alwaysApply: false
 ---
-@if(user_message.starts_with("/check-docs")) {
-  "I will check your documentation for freshness and completeness issues.
+# Check Documentation
 
-  **Running documentation validation...**
+I will check your documentation for freshness and completeness issues.
+
+**Running documentation validation...**
 
   I will:
   1. **Scan Documentation**: Search all `.md` files in the `docs/` directory for placeholder text
@@ -29,4 +30,3 @@ alwaysApply: true
   - `docs/adr/0001-record-architecture-decisions.md`
 
   Then I will provide a comprehensive report of any issues found or confirm that documentation is up-to-date.
-}