docs: update build pattern conversion plan with consistent naming and mode handling

- Change build:* naming from hyphen to colon (build:web-dev → build:web:dev) - Add missing build:web:test and build:web:prod scripts - Update build:electron:dev to include electron startup (build + start) - Remove hardcoded --mode electron to allow proper mode override - Add comprehensive mode override behavior documentation - Fix mode conflicts between hardcoded and passed --mode arguments The plan now properly supports: - Development builds with default --mode development - Testing builds with explicit --mode test override - Production builds with explicit --mode production override - Consistent naming across all platforms (web, capacitor, electron)
2025-07-09 13:13:44 +00:00
parent 95b038c717
commit b35c1d693f
11 changed files with 4209 additions and 0 deletions
--- a/.cursor/rules/markdown.mdc
+++ b/.cursor/rules/markdown.mdc
@@ -0,0 +1,314 @@
+---
+globs: *.md
+alwaysApply: false
+---
+# Cursor Markdown Ruleset for TimeSafari Documentation
+
+## Overview
+
+This ruleset enforces consistent markdown formatting standards across all project
+documentation, ensuring readability, maintainability, and compliance with
+markdownlint best practices.
+
+## General Formatting Standards
+
+### Line Length
+
+- **Maximum line length**: 80 characters
+- **Exception**: Code blocks (JSON, shell, TypeScript, etc.) - no line length
+  enforcement
+- **Rationale**: Ensures readability across different screen sizes and terminal
+  widths
+
+### Blank Lines
+
+- **Headings**: Must be surrounded by blank lines above and below
+- **Lists**: Must be surrounded by blank lines above and below
+- **Code blocks**: Must be surrounded by blank lines above and below
+- **Maximum consecutive blank lines**: 1 (no multiple blank lines)
+- **File start**: No blank lines at the beginning of the file
+- **File end**: Single newline character at the end
+
+### Whitespace
+
+- **No trailing spaces**: Remove all trailing whitespace from lines
+- **No tabs**: Use spaces for indentation
+- **Consistent indentation**: 2 spaces for list items and nested content
+
+## Heading Standards
+
+### Format
+
+- **Style**: ATX-style headings (`#`, `##`, `###`, etc.)
+- **Case**: Title case for general headings
+- **Code references**: Use backticks for file names and technical terms
+  - ✅ `### Current package.json Scripts`
+  - ❌ `### Current Package.json Scripts`
+
+### Hierarchy
+
+- **H1 (#)**: Document title only
+- **H2 (##)**: Major sections
+- **H3 (###)**: Subsections
+- **H4 (####)**: Sub-subsections
+- **H5+**: Avoid deeper nesting
+
+## List Standards
+
+### Unordered Lists
+
+- **Marker**: Use `-` (hyphen) consistently
+- **Indentation**: 2 spaces for nested items
+- **Blank lines**: Surround lists with blank lines
+
+### Ordered Lists
+
+- **Format**: `1.`, `2.`, `3.` (sequential numbering)
+- **Indentation**: 2 spaces for nested items
+- **Blank lines**: Surround lists with blank lines
+
+### Task Lists
+
+- **Format**: `- [ ]` for incomplete, `- [x]` for complete
+- **Use case**: Project planning, checklists, implementation tracking
+
+## Code Block Standards
+
+### Fenced Code Blocks
+
+- **Syntax**: Triple backticks with language specification
+- **Languages**: `json`, `bash`, `typescript`, `javascript`, `yaml`, `markdown`
+- **Blank lines**: Must be surrounded by blank lines above and below
+- **Line length**: No enforcement within code blocks
+
+### Inline Code
+
+- **Format**: Single backticks for inline code references
+- **Use case**: File names, commands, variables, properties
+
+## Special Content Standards
+
+### JSON Examples
+
+```json
+{
+  "property": "value",
+  "nested": {
+    "property": "value"
+  }
+}
+```
+
+### Shell Commands
+
+```bash
+# Command with comment
+npm run build:web
+
+# Multi-line command
+VITE_GIT_HASH=`git log -1 --pretty=format:%h` \
+  vite build --config vite.config.web.mts
+```
+
+### TypeScript Examples
+
+```typescript
+// Function with JSDoc
+/**
+ * Get environment configuration
+ * @param env - Environment name
+ * @returns Environment config object
+ */
+const getEnvironmentConfig = (env: string) => {
+  switch (env) {
+    case 'prod':
+      return { /* production settings */ };
+    default:
+      return { /* development settings */ };
+  }
+};
+```
+
+## File Structure Standards
+
+### Document Header
+
+```markdown
+# Document Title
+
+**Author**: Matthew Raymer
+**Date**: YYYY-MM-DD
+**Status**: 🎯 **STATUS** - Brief description
+
+## Overview
+
+Brief description of the document's purpose and scope.
+```
+
+### Section Organization
+
+1. **Overview/Introduction**
+2. **Current State Analysis**
+3. **Implementation Plan**
+4. **Technical Details**
+5. **Testing & Validation**
+6. **Next Steps**
+
+## Markdownlint Configuration
+
+### Required Rules
+
+```json
+{
+  "MD013": { "code_blocks": false },
+  "MD012": true,
+  "MD022": true,
+  "MD031": true,
+  "MD032": true,
+  "MD047": true,
+  "MD009": true
+}
+```
+
+### Rule Explanations
+
+- **MD013**: Line length (disabled for code blocks)
+- **MD012**: No multiple consecutive blank lines
+- **MD022**: Headings should be surrounded by blank lines
+- **MD031**: Fenced code blocks should be surrounded by blank lines
+- **MD032**: Lists should be surrounded by blank lines
+- **MD047**: Files should end with a single newline
+- **MD009**: No trailing spaces
+
+## Validation Commands
+
+### Check Single File
+
+```bash
+npx markdownlint docs/filename.md
+```
+
+### Check All Documentation
+
+```bash
+npx markdownlint docs/
+```
+
+### Auto-fix Common Issues
+
+```bash
+# Remove trailing spaces
+sed -i 's/[[:space:]]*$//' docs/filename.md
+
+# Remove multiple blank lines
+sed -i '/^$/N;/^\n$/D' docs/filename.md
+
+# Add newline at end if missing
+echo "" >> docs/filename.md
+```
+
+## Common Patterns
+
+### Implementation Plans
+
+```markdown
+## Implementation Plan
+
+### Phase 1: Foundation (Day 1)
+
+#### 1.1 Component Setup
+
+- [ ] Create new component file
+- [ ] Add basic structure
+- [ ] Implement core functionality
+
+#### 1.2 Configuration
+
+- [ ] Update configuration files
+- [ ] Add environment variables
+- [ ] Test configuration loading
+```
+
+### Status Tracking
+
+```markdown
+**Status**: ✅ **COMPLETE** - All phases finished
+**Progress**: 75% (15/20 components)
+**Next**: Ready for testing phase
+```
+
+### Performance Metrics
+
+```markdown
+#### 📊 Performance Metrics
+- **Build Time**: 2.3 seconds (50% faster than baseline)
+- **Bundle Size**: 1.2MB (30% reduction)
+- **Success Rate**: 100% (no failures in 50 builds)
+```
+
+## Enforcement
+
+### Pre-commit Hooks
+
+- Run markdownlint on all changed markdown files
+- Block commits with linting violations
+- Auto-fix common issues when possible
+
+### CI/CD Integration
+
+- Include markdownlint in build pipeline
+- Generate reports for documentation quality
+- Fail builds with critical violations
+
+### Team Guidelines
+
+- All documentation PRs must pass markdownlint
+- Use provided templates for new documents
+- Follow established patterns for consistency
+
+## Templates
+
+### New Document Template
+
+```markdown
+# Document Title
+
+**Author**: Matthew Raymer
+**Date**: YYYY-MM-DD
+**Status**: 🎯 **PLANNING** - Ready for Implementation
+
+## Overview
+
+Brief description of the document's purpose and scope.
+
+## Current State
+
+Description of current situation or problem.
+
+## Implementation Plan
+
+### Phase 1: Foundation
+
+- [ ] Task 1
+- [ ] Task 2
+
+## Next Steps
+
+1. **Review and approve plan**
+2. **Begin implementation**
+3. **Test and validate**
+
+---
+
+**Status**: Ready for implementation
+**Priority**: Medium
+**Estimated Effort**: X days
+**Dependencies**: None
+**Stakeholders**: Development team
+```
+
+---
+
+**Last Updated**: 2025-07-09
+**Version**: 1.0
+**Maintainer**: Matthew Raymer