fix: Upgrade Next.js 14.2.5 → 14.2.28 (HIGH severity DoS fix)

Addresses CVE-2024-56337: HTTP request deserialization vulnerability
that allows denial of service attacks.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.github/dependabot.yml

@@ -0,0 +1,46 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+      timezone: "America/Los_Angeles"
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "automated"
+    groups:
+      dev-dependencies:
+        dependency-type: "development"
+        patterns:
+          - "*"
+      production-dependencies:
+        dependency-type: "production"
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "ci"
+    labels:
+      - "ci/cd"
+      - "automated"
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "docker"
+    labels:
+      - "docker"
+      - "automated"

.github/labeler.yml

@@ -0,0 +1,42 @@
+# Label configuration for PR Labeler action
+
+documentation:
+  - changed-files:
+      - any-glob-to-any-file:
+          - 'docs/**/*'
+          - '*.md'
+          - 'README*'
+
+ci/cd:
+  - changed-files:
+      - any-glob-to-any-file:
+          - '.github/**/*'
+          - 'Dockerfile'
+          - 'docker-compose*.yml'
+
+dependencies:
+  - changed-files:
+      - any-glob-to-any-file:
+          - 'package.json'
+          - 'package-lock.json'
+          - 'pnpm-lock.yaml'
+          - 'yarn.lock'
+
+config:
+  - changed-files:
+      - any-glob-to-any-file:
+          - '*.config.*'
+          - '*.json'
+          - '*.yaml'
+          - '*.yml'
+          - '*.toml'
+          - '!**/.github/**/*.yaml'
+          - '!**/.github/**/*.yml'
+
+tests:
+  - changed-files:
+      - any-glob-to-any-file:
+          - '**/*.test.*'
+          - '**/*.spec.*'
+          - '__tests__/**/*'
+          - 'test/**/*'

.github/workflows/agent-code-review.yml

@@ -0,0 +1,111 @@
+name: "🤖 Agent: Code Review"
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  code-review:
+    name: Code Review Agent
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v44
+        with:
+          files: |
+            **/*.ts
+            **/*.tsx
+            **/*.js
+            **/*.jsx
+            **/*.py
+            **/*.go
+
+      - name: Analyze code quality
+        if: steps.changed-files.outputs.any_changed == 'true'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const changedFiles = '${{ steps.changed-files.outputs.all_changed_files }}'.split(' ').filter(f => f);
+
+            let reviewComments = [];
+            let summary = '## 🤖 Code Review Agent Report\n\n';
+            summary += `Analyzed **${changedFiles.length}** changed files.\n\n`;
+
+            // Analyze patterns
+            const patterns = {
+              'console.log': { severity: 'warning', msg: 'Consider removing debug logs before merging' },
+              'TODO': { severity: 'info', msg: 'Found TODO comment - ensure this is tracked' },
+              'FIXME': { severity: 'warning', msg: 'FIXME found - should be addressed' },
+              'any': { severity: 'warning', msg: 'Avoid using `any` type - prefer specific types' },
+              'eslint-disable': { severity: 'info', msg: 'ESLint rule disabled - ensure this is intentional' },
+              'password': { severity: 'error', msg: '⚠️ Possible hardcoded credential detected' },
+              'secret': { severity: 'error', msg: '⚠️ Possible secret in code' },
+            };
+
+            const { execSync } = require('child_process');
+            let issues = { error: 0, warning: 0, info: 0 };
+
+            for (const file of changedFiles) {
+              try {
+                const content = require('fs').readFileSync(file, 'utf8');
+                const lines = content.split('\n');
+
+                lines.forEach((line, idx) => {
+                  for (const [pattern, config] of Object.entries(patterns)) {
+                    if (line.toLowerCase().includes(pattern.toLowerCase())) {
+                      issues[config.severity]++;
+                      reviewComments.push(`- **${file}:${idx + 1}** [${config.severity.toUpperCase()}] ${config.msg}`);
+                    }
+                  }
+                });
+              } catch (e) {
+                // File might not exist in working directory
+              }
+            }
+
+            // Build summary
+            if (issues.error > 0) {
+              summary += `### ❌ Errors: ${issues.error}\n`;
+            }
+            if (issues.warning > 0) {
+              summary += `### ⚠️ Warnings: ${issues.warning}\n`;
+            }
+            if (issues.info > 0) {
+              summary += `### ℹ️ Info: ${issues.info}\n`;
+            }
+
+            if (reviewComments.length > 0) {
+              summary += '\n### Details\n\n';
+              summary += reviewComments.slice(0, 20).join('\n');
+              if (reviewComments.length > 20) {
+                summary += `\n\n*...and ${reviewComments.length - 20} more issues*`;
+              }
+            } else {
+              summary += '\n✅ No issues found! Code looks good.\n';
+            }
+
+            summary += '\n\n---\n*🤖 Automated review by Code Review Agent*';
+
+            // Post comment
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.pull_request.number,
+              body: summary
+            });
+
+            // Fail if errors found
+            if (issues.error > 0) {
+              core.setFailed(`Found ${issues.error} error(s) in code review`);
+            }

.github/workflows/agent-documentation.yml

@@ -0,0 +1,137 @@
+name: "📚 Agent: Documentation"
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  documentation:
+    name: Documentation Agent
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v44
+
+      - name: Analyze documentation coverage
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+
+            const changedFiles = '${{ steps.changed-files.outputs.all_changed_files }}'.split(' ').filter(f => f);
+
+            let report = '## 📚 Documentation Agent Report\n\n';
+            let suggestions = [];
+            let stats = {
+              codeFiles: 0,
+              docFiles: 0,
+              hasJsdoc: 0,
+              missingJsdoc: 0,
+              readmeUpdated: false
+            };
+
+            // Categorize files
+            const codeExtensions = ['.ts', '.tsx', '.js', '.jsx', '.py', '.go'];
+            const docExtensions = ['.md', '.mdx', '.rst', '.txt'];
+
+            for (const file of changedFiles) {
+              const ext = path.extname(file);
+
+              if (codeExtensions.includes(ext)) {
+                stats.codeFiles++;
+
+                // Check for JSDoc/docstrings
+                try {
+                  const content = fs.readFileSync(file, 'utf8');
+
+                  // Check for exported functions without documentation
+                  const exportedFunctions = content.match(/export\s+(async\s+)?function\s+\w+/g) || [];
+                  const jsdocBlocks = content.match(/\/\*\*[\s\S]*?\*\//g) || [];
+
+                  if (exportedFunctions.length > jsdocBlocks.length) {
+                    stats.missingJsdoc++;
+                    suggestions.push(`📝 **${file}**: Consider adding JSDoc comments to exported functions`);
+                  } else if (jsdocBlocks.length > 0) {
+                    stats.hasJsdoc++;
+                  }
+
+                  // Check for complex functions that need docs
+                  const lines = content.split('\n').length;
+                  if (lines > 200 && jsdocBlocks.length === 0) {
+                    suggestions.push(`📖 **${file}**: Large file (${lines} lines) without documentation`);
+                  }
+                } catch (e) {
+                  // File might not exist
+                }
+              }
+
+              if (docExtensions.includes(ext)) {
+                stats.docFiles++;
+              }
+
+              if (file.toLowerCase().includes('readme')) {
+                stats.readmeUpdated = true;
+              }
+            }
+
+            // Build report
+            report += '### 📊 Documentation Stats\n\n';
+            report += `| Metric | Value |\n`;
+            report += `|--------|-------|\n`;
+            report += `| Code files changed | ${stats.codeFiles} |\n`;
+            report += `| Doc files changed | ${stats.docFiles} |\n`;
+            report += `| Files with JSDoc | ${stats.hasJsdoc} |\n`;
+            report += `| Files needing docs | ${stats.missingJsdoc} |\n`;
+            report += `| README updated | ${stats.readmeUpdated ? '✅' : '❌'} |\n\n`;
+
+            // Calculate documentation score
+            const docScore = stats.codeFiles > 0
+              ? Math.round((stats.hasJsdoc / stats.codeFiles) * 100)
+              : 100;
+
+            report += `### 📈 Documentation Score: ${docScore}%\n\n`;
+
+            if (docScore >= 80) {
+              report += '✅ Great documentation coverage!\n\n';
+            } else if (docScore >= 50) {
+              report += '⚠️ Documentation could be improved.\n\n';
+            } else {
+              report += '❌ Documentation coverage is low. Please add docs.\n\n';
+            }
+
+            // Suggestions
+            if (suggestions.length > 0) {
+              report += '### 💡 Suggestions\n\n';
+              suggestions.slice(0, 10).forEach(s => report += `- ${s}\n`);
+              if (suggestions.length > 10) {
+                report += `\n*...and ${suggestions.length - 10} more suggestions*\n`;
+              }
+            }
+
+            // Tips
+            if (stats.codeFiles > 0 && !stats.readmeUpdated) {
+              report += '\n### 💡 Tip\n';
+              report += 'Consider updating the README if this PR introduces new features or API changes.\n';
+            }
+
+            report += '\n---\n*📚 Automated review by Documentation Agent*';
+
+            // Post comment
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.pull_request.number,
+              body: report
+            });

.github/workflows/agent-performance.yml

@@ -0,0 +1,180 @@
+name: "⚡ Agent: Performance"
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  performance:
+    name: Performance Agent
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Get PR stats
+        id: pr-stats
+        run: |
+          # Get diff stats
+          ADDITIONS=$(git diff --shortstat origin/${{ github.base_ref }}...HEAD | grep -oP '\d+(?= insertion)' || echo 0)
+          DELETIONS=$(git diff --shortstat origin/${{ github.base_ref }}...HEAD | grep -oP '\d+(?= deletion)' || echo 0)
+          FILES_CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | wc -l)
+
+          echo "additions=$ADDITIONS" >> $GITHUB_OUTPUT
+          echo "deletions=$DELETIONS" >> $GITHUB_OUTPUT
+          echo "files_changed=$FILES_CHANGED" >> $GITHUB_OUTPUT
+
+      - name: Analyze bundle size impact
+        id: bundle
+        run: |
+          # Check if package.json exists and get dependencies
+          if [ -f "package.json" ]; then
+            DEPS=$(cat package.json | jq '.dependencies | length // 0')
+            DEV_DEPS=$(cat package.json | jq '.devDependencies | length // 0')
+            echo "deps=$DEPS" >> $GITHUB_OUTPUT
+            echo "dev_deps=$DEV_DEPS" >> $GITHUB_OUTPUT
+          else
+            echo "deps=0" >> $GITHUB_OUTPUT
+            echo "dev_deps=0" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v44
+
+      - name: Performance analysis
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+
+            const changedFiles = '${{ steps.changed-files.outputs.all_changed_files }}'.split(' ').filter(f => f);
+            const additions = parseInt('${{ steps.pr-stats.outputs.additions }}') || 0;
+            const deletions = parseInt('${{ steps.pr-stats.outputs.deletions }}') || 0;
+            const filesChanged = parseInt('${{ steps.pr-stats.outputs.files_changed }}') || 0;
+            const deps = parseInt('${{ steps.bundle.outputs.deps }}') || 0;
+            const devDeps = parseInt('${{ steps.bundle.outputs.dev_deps }}') || 0;
+
+            let report = '## ⚡ Performance Agent Report\n\n';
+            let warnings = [];
+            let suggestions = [];
+
+            // PR Size Analysis
+            report += '### 📦 PR Size Analysis\n\n';
+            report += `| Metric | Value |\n`;
+            report += `|--------|-------|\n`;
+            report += `| Files changed | ${filesChanged} |\n`;
+            report += `| Lines added | +${additions} |\n`;
+            report += `| Lines removed | -${deletions} |\n`;
+            report += `| Net change | ${additions - deletions > 0 ? '+' : ''}${additions - deletions} |\n`;
+            report += `| Dependencies | ${deps} |\n`;
+            report += `| Dev Dependencies | ${devDeps} |\n\n`;
+
+            // PR Size Rating
+            const totalChanges = additions + deletions;
+            let sizeRating = '';
+            if (totalChanges < 100) {
+              sizeRating = '🟢 Small PR - Easy to review';
+            } else if (totalChanges < 500) {
+              sizeRating = '🟡 Medium PR - Moderate review effort';
+            } else if (totalChanges < 1000) {
+              sizeRating = '🟠 Large PR - Consider breaking down';
+              warnings.push('Large PR detected. Consider splitting into smaller PRs for easier review.');
+            } else {
+              sizeRating = '🔴 Very Large PR - Difficult to review';
+              warnings.push('Very large PR! This will be difficult to review. Strongly consider breaking into smaller PRs.');
+            }
+            report += `**Size Rating:** ${sizeRating}\n\n`;
+
+            // Performance patterns check
+            report += '### 🔍 Performance Patterns\n\n';
+
+            const perfPatterns = [
+              { pattern: /\.forEach\s*\(/g, msg: 'forEach loop - consider for...of for better performance', severity: 'info' },
+              { pattern: /JSON\.parse\s*\(.*JSON\.stringify/g, msg: 'Deep clone via JSON - consider structuredClone()', severity: 'warning' },
+              { pattern: /new\s+RegExp\s*\(/g, msg: 'Dynamic RegExp creation - consider caching if used repeatedly', severity: 'info' },
+              { pattern: /document\.querySelector.*loop|for.*querySelector/gi, msg: 'DOM query in loop - cache selectors outside loop', severity: 'warning' },
+              { pattern: /\bawait\b.*\bawait\b.*\bawait\b/g, msg: 'Multiple sequential awaits - consider Promise.all()', severity: 'warning' },
+              { pattern: /\.filter\(.*\)\.map\(/g, msg: 'filter().map() chain - consider reduce() or single pass', severity: 'info' },
+              { pattern: /useEffect.*\[\s*\]/g, msg: 'Empty dependency array - ensure this is intentional', severity: 'info' },
+              { pattern: /new\s+Date\(\).*loop|for.*new\s+Date/gi, msg: 'Date creation in loop - cache Date object', severity: 'warning' },
+            ];
+
+            let patternFindings = [];
+
+            for (const file of changedFiles) {
+              try {
+                const content = fs.readFileSync(file, 'utf8');
+
+                for (const { pattern, msg, severity } of perfPatterns) {
+                  if (pattern.test(content)) {
+                    patternFindings.push({ file, msg, severity });
+                  }
+                }
+
+                // Check file size
+                const lines = content.split('\n').length;
+                if (lines > 500) {
+                  warnings.push(`\`${file}\` has ${lines} lines - consider splitting into smaller modules`);
+                }
+              } catch (e) {}
+            }
+
+            if (patternFindings.length > 0) {
+              patternFindings.slice(0, 10).forEach(({ file, msg, severity }) => {
+                const icon = severity === 'warning' ? '⚠️' : 'ℹ️';
+                report += `- ${icon} **${file}**: ${msg}\n`;
+              });
+              if (patternFindings.length > 10) {
+                report += `\n*...and ${patternFindings.length - 10} more findings*\n`;
+              }
+            } else {
+              report += '✅ No performance anti-patterns detected!\n';
+            }
+            report += '\n';
+
+            // Warnings
+            if (warnings.length > 0) {
+              report += '### ⚠️ Warnings\n\n';
+              warnings.forEach(w => report += `- ${w}\n`);
+              report += '\n';
+            }
+
+            // Bundle impact estimation
+            report += '### 📊 Impact Assessment\n\n';
+
+            // Check for new dependencies in package.json changes
+            const pkgChanged = changedFiles.some(f => f.includes('package.json'));
+            if (pkgChanged) {
+              report += '⚠️ `package.json` was modified - bundle size may be affected.\n';
+              report += 'Consider running bundle analysis after merging.\n\n';
+            }
+
+            // Recommendations
+            report += '### 💡 Recommendations\n\n';
+            if (totalChanges > 500) {
+              report += '- Consider breaking this PR into smaller, focused changes\n';
+            }
+            if (patternFindings.some(f => f.severity === 'warning')) {
+              report += '- Review the performance warnings above\n';
+            }
+            report += '- Run performance tests before and after merging\n';
+            report += '- Monitor production metrics after deployment\n';
+
+            report += '\n---\n*⚡ Automated analysis by Performance Agent*';
+
+            // Post comment
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.pull_request.number,
+              body: report
+            });

.github/workflows/agent-security-audit.yml

@@ -0,0 +1,127 @@
+name: "🛡️ Agent: Security Audit"
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+  security-events: write
+
+jobs:
+  security-audit:
+    name: Security Audit Agent
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Get PR diff
+        id: diff
+        run: |
+          git diff origin/${{ github.base_ref }}...HEAD > pr_diff.txt
+          echo "diff_size=$(wc -l < pr_diff.txt)" >> $GITHUB_OUTPUT
+
+      - name: Run security patterns check
+        id: security-check
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const diff = fs.readFileSync('pr_diff.txt', 'utf8');
+
+            const securityPatterns = [
+              { pattern: /eval\s*\(/gi, severity: 'high', msg: 'Dangerous eval() usage detected' },
+              { pattern: /innerHTML\s*=/gi, severity: 'medium', msg: 'innerHTML assignment - potential XSS' },
+              { pattern: /document\.write/gi, severity: 'medium', msg: 'document.write usage - potential XSS' },
+              { pattern: /dangerouslySetInnerHTML/gi, severity: 'medium', msg: 'React dangerouslySetInnerHTML - ensure sanitized' },
+              { pattern: /exec\s*\(/gi, severity: 'high', msg: 'Shell exec detected - potential command injection' },
+              { pattern: /subprocess|os\.system/gi, severity: 'high', msg: 'System command execution detected' },
+              { pattern: /localStorage\.setItem.*password/gi, severity: 'high', msg: 'Storing password in localStorage' },
+              { pattern: /Bearer\s+[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+/gi, severity: 'critical', msg: '⚠️ Possible JWT token in code' },
+              { pattern: /sk-[A-Za-z0-9]{32,}/gi, severity: 'critical', msg: '⚠️ Possible API key detected' },
+              { pattern: /AKIA[0-9A-Z]{16}/gi, severity: 'critical', msg: '⚠️ Possible AWS key detected' },
+              { pattern: /ghp_[A-Za-z0-9]{36}/gi, severity: 'critical', msg: '⚠️ Possible GitHub token detected' },
+              { pattern: /-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/gi, severity: 'critical', msg: '⚠️ Private key detected!' },
+              { pattern: /sql.*['"]\s*\+/gi, severity: 'high', msg: 'Potential SQL injection - use parameterized queries' },
+              { pattern: /password\s*[=:]\s*['"][^'"]+['"]/gi, severity: 'high', msg: 'Hardcoded password detected' },
+            ];
+
+            let findings = { critical: [], high: [], medium: [], low: [] };
+            let totalIssues = 0;
+
+            for (const { pattern, severity, msg } of securityPatterns) {
+              const matches = diff.match(pattern);
+              if (matches) {
+                findings[severity].push({ msg, count: matches.length });
+                totalIssues += matches.length;
+              }
+            }
+
+            // Build report
+            let report = '## 🛡️ Security Audit Agent Report\n\n';
+
+            if (totalIssues === 0) {
+              report += '✅ **No security issues detected!**\n\n';
+              report += 'The changes in this PR passed all security checks.\n';
+            } else {
+              report += `⚠️ **Found ${totalIssues} potential security issue(s)**\n\n`;
+
+              if (findings.critical.length > 0) {
+                report += '### 🚨 Critical\n';
+                findings.critical.forEach(f => report += `- ${f.msg} (${f.count} occurrence(s))\n`);
+                report += '\n';
+              }
+
+              if (findings.high.length > 0) {
+                report += '### 🔴 High\n';
+                findings.high.forEach(f => report += `- ${f.msg} (${f.count} occurrence(s))\n`);
+                report += '\n';
+              }
+
+              if (findings.medium.length > 0) {
+                report += '### 🟠 Medium\n';
+                findings.medium.forEach(f => report += `- ${f.msg} (${f.count} occurrence(s))\n`);
+                report += '\n';
+              }
+            }
+
+            report += '\n### Checks Performed\n';
+            report += '- [x] Secrets & API keys scan\n';
+            report += '- [x] SQL injection patterns\n';
+            report += '- [x] XSS vulnerability patterns\n';
+            report += '- [x] Command injection patterns\n';
+            report += '- [x] Hardcoded credentials\n';
+
+            report += '\n---\n*🛡️ Automated audit by Security Agent*';
+
+            // Post comment
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.pull_request.number,
+              body: report
+            });
+
+            // Fail on critical findings
+            if (findings.critical.length > 0) {
+              core.setFailed('Critical security issues found! Please review before merging.');
+            }
+
+            return { findings, totalIssues };
+
+      - name: Run npm audit (if package.json exists)
+        continue-on-error: true
+        run: |
+          if [ -f "package.json" ]; then
+            npm audit --audit-level=high || echo "Vulnerabilities found"
+          fi

.github/workflows/agent-test-coverage.yml

@@ -0,0 +1,173 @@
+name: "🧪 Agent: Test Coverage"
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  test-coverage:
+    name: Test Coverage Agent
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+        continue-on-error: true
+
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v44
+        with:
+          files: |
+            **/*.ts
+            **/*.tsx
+            **/*.js
+            **/*.jsx
+
+      - name: Analyze test coverage
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+
+            const changedFiles = '${{ steps.changed-files.outputs.all_changed_files }}'.split(' ').filter(f => f);
+
+            let report = '## 🧪 Test Coverage Agent Report\n\n';
+            let stats = {
+              sourceFiles: [],
+              testFiles: [],
+              missingTests: [],
+              hasTestFramework: false
+            };
+
+            // Check for test framework
+            try {
+              const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+              const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+              stats.hasTestFramework = !!(deps.jest || deps.vitest || deps.mocha || deps['@testing-library/react']);
+            } catch (e) {}
+
+            // Analyze changed files
+            for (const file of changedFiles) {
+              const isTest = file.includes('.test.') ||
+                             file.includes('.spec.') ||
+                             file.includes('__tests__') ||
+                             file.includes('test/') ||
+                             file.includes('tests/');
+
+              if (isTest) {
+                stats.testFiles.push(file);
+              } else {
+                stats.sourceFiles.push(file);
+
+                // Check if corresponding test exists
+                const basename = path.basename(file, path.extname(file));
+                const dirname = path.dirname(file);
+                const testPatterns = [
+                  `${dirname}/${basename}.test${path.extname(file)}`,
+                  `${dirname}/${basename}.spec${path.extname(file)}`,
+                  `${dirname}/__tests__/${basename}.test${path.extname(file)}`,
+                  `__tests__/${basename}.test${path.extname(file)}`,
+                ];
+
+                let hasTest = false;
+                for (const testPath of testPatterns) {
+                  if (fs.existsSync(testPath)) {
+                    hasTest = true;
+                    break;
+                  }
+                }
+
+                if (!hasTest && !file.includes('index.') && !file.includes('.d.ts')) {
+                  stats.missingTests.push(file);
+                }
+              }
+            }
+
+            // Calculate coverage percentage
+            const coveragePercent = stats.sourceFiles.length > 0
+              ? Math.round(((stats.sourceFiles.length - stats.missingTests.length) / stats.sourceFiles.length) * 100)
+              : 100;
+
+            // Build report
+            report += '### 📊 Test Analysis\n\n';
+            report += `| Metric | Value |\n`;
+            report += `|--------|-------|\n`;
+            report += `| Source files changed | ${stats.sourceFiles.length} |\n`;
+            report += `| Test files changed | ${stats.testFiles.length} |\n`;
+            report += `| Files with tests | ${stats.sourceFiles.length - stats.missingTests.length} |\n`;
+            report += `| Files missing tests | ${stats.missingTests.length} |\n`;
+            report += `| Test framework | ${stats.hasTestFramework ? '✅ Detected' : '❌ Not found'} |\n\n`;
+
+            report += `### 📈 Test Coverage Score: ${coveragePercent}%\n\n`;
+
+            // Progress bar
+            const filled = Math.round(coveragePercent / 10);
+            const empty = 10 - filled;
+            report += `\`[${'█'.repeat(filled)}${'░'.repeat(empty)}]\`\n\n`;
+
+            if (coveragePercent >= 80) {
+              report += '✅ Excellent test coverage!\n\n';
+            } else if (coveragePercent >= 50) {
+              report += '⚠️ Consider adding more tests for better coverage.\n\n';
+            } else {
+              report += '❌ Low test coverage. Please add tests for your changes.\n\n';
+            }
+
+            // Missing tests
+            if (stats.missingTests.length > 0) {
+              report += '### 🔍 Files Missing Tests\n\n';
+              stats.missingTests.slice(0, 10).forEach(f => {
+                report += `- \`${f}\`\n`;
+              });
+              if (stats.missingTests.length > 10) {
+                report += `\n*...and ${stats.missingTests.length - 10} more files*\n`;
+              }
+              report += '\n';
+            }
+
+            // Recommendations
+            report += '### 💡 Recommendations\n\n';
+            if (!stats.hasTestFramework) {
+              report += '- Consider adding a test framework (Jest, Vitest, etc.)\n';
+            }
+            if (stats.testFiles.length === 0 && stats.sourceFiles.length > 0) {
+              report += '- No test files in this PR - consider adding tests\n';
+            }
+            if (stats.missingTests.length > 0) {
+              report += '- Add unit tests for the files listed above\n';
+            }
+            if (coveragePercent === 100) {
+              report += '- All changed files have corresponding tests! 🎉\n';
+            }
+
+            report += '\n---\n*🧪 Automated analysis by Test Coverage Agent*';
+
+            // Post comment
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.pull_request.number,
+              body: report
+            });
+
+      - name: Run tests (if available)
+        continue-on-error: true
+        run: |
+          if [ -f "package.json" ]; then
+            npm ci --ignore-scripts 2>/dev/null || npm install --ignore-scripts 2>/dev/null || true
+            npm test 2>/dev/null || echo "No tests configured or tests failed"
+          fi

.github/workflows/pr-labeler.yml

@@ -0,0 +1,65 @@
+name: PR Labeler
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  label:
+    name: Label PR
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Label based on files changed
+        uses: actions/labeler@v5
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          configuration-path: .github/labeler.yml
+
+      - name: Label based on PR size
+        uses: codelytv/pr-size-labeler@v1
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          xs_label: 'size/xs'
+          xs_max_size: 10
+          s_label: 'size/s'
+          s_max_size: 100
+          m_label: 'size/m'
+          m_max_size: 500
+          l_label: 'size/l'
+          l_max_size: 1000
+          xl_label: 'size/xl'
+          fail_if_xl: false
+
+      - name: Label based on title
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const title = context.payload.pull_request.title.toLowerCase();
+            const labels = [];
+
+            if (title.includes('fix') || title.includes('bug')) labels.push('bug');
+            if (title.includes('feat') || title.includes('feature')) labels.push('enhancement');
+            if (title.includes('docs') || title.includes('documentation')) labels.push('documentation');
+            if (title.includes('refactor')) labels.push('refactor');
+            if (title.includes('test')) labels.push('testing');
+            if (title.includes('ci') || title.includes('workflow')) labels.push('ci/cd');
+            if (title.includes('security')) labels.push('security');
+            if (title.includes('breaking')) labels.push('breaking-change');
+            if (title.includes('wip') || title.includes('draft')) labels.push('work-in-progress');
+
+            if (labels.length > 0) {
+              await github.rest.issues.addLabels({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.payload.pull_request.number,
+                labels: labels
+              });
+            }

.github/workflows/release.yml

@@ -0,0 +1,94 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  release:
+    name: Create Release
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build --if-present
+
+      - name: Generate changelog
+        id: changelog
+        uses: metcalfc/changelog-generator@v4.3.1
+        with:
+          myToken: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: |
+            ## What's Changed
+            ${{ steps.changelog.outputs.changelog }}
+
+            ## Docker Image
+            ```
+            docker pull ghcr.io/${{ github.repository }}:${{ github.ref_name }}
+            ```
+          draft: false
+          prerelease: ${{ contains(github.ref, 'alpha') || contains(github.ref, 'beta') }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  docker:
+    name: Build and Push Docker Image
+    runs-on: ubuntu-latest
+    needs: release
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/security-scan.yml

@@ -0,0 +1,68 @@
+name: Security Scan
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+  schedule:
+    - cron: '0 6 * * 1'  # Weekly on Monday at 6am UTC
+
+permissions:
+  contents: read
+  security-events: write
+  actions: read
+
+jobs:
+  codeql:
+    name: CodeQL Analysis
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        language: ['javascript']
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{ matrix.language }}"
+
+  dependency-review:
+    name: Dependency Review
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Dependency Review
+        uses: actions/dependency-review-action@v4
+        with:
+          fail-on-severity: high
+          deny-licenses: GPL-3.0, AGPL-3.0
+
+  secrets-scan:
+    name: Secret Scanning
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: TruffleHog OSS
+        uses: trufflesecurity/trufflehog@v3.57.0
+        with:
+          extra_args: --only-verified

index.html

@@ -0,0 +1,693 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Interactive Demo | BlackRoad OS</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    :root {
+      --bg: #0a0a0a;
+      --surface: #111;
+      --surface2: #151515;
+      --border: #222;
+      --text: #e0e0e0;
+      --text-secondary: #999;
+      --muted: #666;
+      --accent: #FF9D00;
+      --accent2: #FF6B00;
+      --accent3: #FF0066;
+      --accent4: #7700FF;
+      --accent5: #0066FF;
+      --success: #00D26A;
+      --warning: #FFB800;
+      --error: #FF3366;
+    }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      background: var(--bg);
+      color: var(--text);
+      line-height: 1.5;
+      min-height: 100vh;
+    }
+    .header {
+      background: var(--surface);
+      border-bottom: 1px solid var(--border);
+      padding: 1rem 2rem;
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+    }
+    .logo {
+      font-size: 1.25rem;
+      font-weight: 700;
+    }
+    .logo span { color: var(--accent); }
+    .header-nav {
+      display: flex;
+      gap: 1rem;
+    }
+    .header-nav a {
+      color: var(--text-secondary);
+      text-decoration: none;
+      padding: 0.5rem 1rem;
+      border-radius: 6px;
+      transition: all 0.2s;
+    }
+    .header-nav a:hover {
+      background: var(--surface2);
+      color: var(--text);
+    }
+    .container {
+      max-width: 1200px;
+      margin: 0 auto;
+      padding: 2rem;
+    }
+    .hero {
+      text-align: center;
+      padding: 4rem 0;
+    }
+    .hero h1 {
+      font-size: 3rem;
+      font-weight: 700;
+      margin-bottom: 1rem;
+      background: linear-gradient(135deg, var(--accent), var(--accent3));
+      -webkit-background-clip: text;
+      -webkit-text-fill-color: transparent;
+      background-clip: text;
+    }
+    .hero p {
+      font-size: 1.25rem;
+      color: var(--text-secondary);
+      max-width: 600px;
+      margin: 0 auto 2rem;
+    }
+    .demo-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(350px, 1fr));
+      gap: 1.5rem;
+      margin-top: 3rem;
+    }
+    .demo-card {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 12px;
+      overflow: hidden;
+      transition: all 0.3s;
+    }
+    .demo-card:hover {
+      border-color: var(--accent);
+      transform: translateY(-4px);
+    }
+    .demo-card-header {
+      padding: 1.5rem;
+      border-bottom: 1px solid var(--border);
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+    }
+    .demo-card-title {
+      display: flex;
+      align-items: center;
+      gap: 0.75rem;
+    }
+    .demo-card-title span {
+      font-size: 1.5rem;
+    }
+    .demo-card-title h3 {
+      font-size: 1.1rem;
+      font-weight: 600;
+    }
+    .demo-card-body {
+      padding: 1.5rem;
+    }
+    .demo-card-body p {
+      color: var(--text-secondary);
+      font-size: 0.9rem;
+      margin-bottom: 1rem;
+    }
+    .btn {
+      display: inline-flex;
+      align-items: center;
+      gap: 0.5rem;
+      padding: 0.6rem 1.25rem;
+      border-radius: 6px;
+      font-size: 0.9rem;
+      font-weight: 500;
+      cursor: pointer;
+      transition: all 0.2s;
+      border: none;
+    }
+    .btn-primary {
+      background: var(--accent);
+      color: #000;
+    }
+    .btn-primary:hover { background: var(--accent2); }
+    .btn-secondary {
+      background: var(--surface2);
+      color: var(--text);
+      border: 1px solid var(--border);
+    }
+    .btn-secondary:hover { border-color: var(--accent); }
+    .output {
+      background: var(--surface2);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 1rem;
+      font-family: 'SF Mono', monospace;
+      font-size: 0.85rem;
+      max-height: 300px;
+      overflow-y: auto;
+      margin-top: 1rem;
+    }
+    .output-line {
+      padding: 0.25rem 0;
+      border-bottom: 1px solid var(--border);
+    }
+    .output-line:last-child { border-bottom: none; }
+    .output-success { color: var(--success); }
+    .output-error { color: var(--error); }
+    .output-info { color: var(--accent5); }
+    .output-accent { color: var(--accent); }
+    .input-group {
+      display: flex;
+      gap: 0.5rem;
+      margin-bottom: 1rem;
+    }
+    .input {
+      flex: 1;
+      padding: 0.6rem 0.75rem;
+      background: var(--surface2);
+      border: 1px solid var(--border);
+      border-radius: 6px;
+      color: var(--text);
+      font-size: 0.9rem;
+    }
+    .input:focus {
+      outline: none;
+      border-color: var(--accent);
+    }
+    .input::placeholder { color: var(--muted); }
+    select.input { cursor: pointer; }
+    .status-indicator {
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+      background: var(--muted);
+    }
+    .status-indicator.active {
+      background: var(--success);
+      animation: pulse 2s infinite;
+    }
+    @keyframes pulse {
+      0%, 100% { opacity: 1; }
+      50% { opacity: 0.5; }
+    }
+    .badge {
+      font-size: 0.7rem;
+      padding: 0.2rem 0.5rem;
+      border-radius: 4px;
+      text-transform: uppercase;
+      font-weight: 600;
+    }
+    .badge-live { background: rgba(0, 210, 106, 0.2); color: var(--success); }
+    .badge-beta { background: rgba(255, 157, 0, 0.2); color: var(--accent); }
+    .word-cloud {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 0.5rem;
+      margin-top: 1rem;
+    }
+    .word-tag {
+      padding: 0.25rem 0.5rem;
+      border-radius: 4px;
+      font-size: 0.8rem;
+    }
+    .grammar-result {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 0.25rem;
+      font-size: 1.1rem;
+      margin: 1rem 0;
+    }
+    .grammar-word {
+      padding: 0.2rem 0.4rem;
+      border-radius: 4px;
+      font-weight: 500;
+    }
+    .trivia-options {
+      display: flex;
+      flex-direction: column;
+      gap: 0.5rem;
+      margin: 1rem 0;
+    }
+    .trivia-option {
+      padding: 0.75rem 1rem;
+      background: var(--surface2);
+      border: 1px solid var(--border);
+      border-radius: 6px;
+      cursor: pointer;
+      transition: all 0.2s;
+    }
+    .trivia-option:hover {
+      border-color: var(--accent);
+    }
+    .trivia-option.correct {
+      background: rgba(0, 210, 106, 0.2);
+      border-color: var(--success);
+    }
+    .trivia-option.incorrect {
+      background: rgba(255, 51, 102, 0.2);
+      border-color: var(--error);
+    }
+    .stats-grid {
+      display: grid;
+      grid-template-columns: repeat(3, 1fr);
+      gap: 1rem;
+      margin-bottom: 1rem;
+    }
+    .stat {
+      text-align: center;
+      padding: 1rem;
+      background: var(--surface2);
+      border-radius: 8px;
+    }
+    .stat-value {
+      font-size: 1.5rem;
+      font-weight: 700;
+      color: var(--accent);
+    }
+    .stat-label {
+      font-size: 0.75rem;
+      color: var(--muted);
+      text-transform: uppercase;
+    }
+    @media (max-width: 768px) {
+      .hero h1 { font-size: 2rem; }
+      .demo-grid { grid-template-columns: 1fr; }
+      .stats-grid { grid-template-columns: 1fr; }
+    }
+  </style>
+</head>
+<body>
+  <header class="header">
+    <div class="logo"><span>Black</span>Road Demo</div>
+    <nav class="header-nav">
+      <a href="https://blackroad.io">Home</a>
+      <a href="https://docs.blackroad.io">Docs</a>
+      <a href="https://app.blackroad.io">Console</a>
+    </nav>
+  </header>
+
+  <div class="container">
+    <div class="hero">
+      <h1>Interactive Demo</h1>
+      <p>Try out BlackRoad OS features directly in your browser. No signup required.</p>
+    </div>
+
+    <div class="demo-grid">
+      <!-- Agent Registration Demo -->
+      <div class="demo-card">
+        <div class="demo-card-header">
+          <div class="demo-card-title">
+            <span>🤖</span>
+            <h3>Register an Agent</h3>
+          </div>
+          <span class="badge badge-live">Live</span>
+        </div>
+        <div class="demo-card-body">
+          <p>Create your first agent and get a unique identity.</p>
+          <div class="input-group">
+            <input type="text" class="input" id="agent-name" placeholder="Agent name">
+            <select class="input" id="agent-type" style="width: auto;">
+              <option value="ai">AI</option>
+              <option value="human">Human</option>
+              <option value="hybrid">Hybrid</option>
+            </select>
+          </div>
+          <button class="btn btn-primary" onclick="registerAgent()">Register Agent</button>
+          <div class="output" id="agent-output">
+            <div class="output-line output-info">Ready to register...</div>
+          </div>
+        </div>
+      </div>
+
+      <!-- Grammar Demo -->
+      <div class="demo-card">
+        <div class="demo-card-header">
+          <div class="demo-card-title">
+            <span>📝</span>
+            <h3>Grammar Analysis</h3>
+          </div>
+          <span class="badge badge-live">Live</span>
+        </div>
+        <div class="demo-card-body">
+          <p>Color-coded sentence analysis using functional linguistics.</p>
+          <div class="input-group">
+            <input type="text" class="input" id="grammar-input" placeholder="Enter a sentence..." value="Jennifer is running fast around the fence.">
+          </div>
+          <button class="btn btn-primary" onclick="analyzeGrammar()">Analyze</button>
+          <div class="grammar-result" id="grammar-result"></div>
+          <div class="output" id="grammar-output" style="display: none;"></div>
+        </div>
+      </div>
+
+      <!-- Trivia Demo -->
+      <div class="demo-card">
+        <div class="demo-card-header">
+          <div class="demo-card-title">
+            <span>🏟️</span>
+            <h3>Road Arena</h3>
+          </div>
+          <span class="badge badge-beta">Beta</span>
+        </div>
+        <div class="demo-card-body">
+          <p>Test your knowledge in the trivia arena!</p>
+          <div class="stats-grid">
+            <div class="stat">
+              <div class="stat-value" id="trivia-score">0</div>
+              <div class="stat-label">Points</div>
+            </div>
+            <div class="stat">
+              <div class="stat-value" id="trivia-streak">0</div>
+              <div class="stat-label">Streak</div>
+            </div>
+            <div class="stat">
+              <div class="stat-value" id="trivia-rank">Novice</div>
+              <div class="stat-label">Rank</div>
+            </div>
+          </div>
+          <div id="trivia-question" style="font-weight: 600; margin-bottom: 0.5rem;">Click start to begin!</div>
+          <div class="trivia-options" id="trivia-options"></div>
+          <button class="btn btn-primary" id="trivia-btn" onclick="startTrivia()">Start Game</button>
+        </div>
+      </div>
+
+      <!-- Agency Demo -->
+      <div class="demo-card">
+        <div class="demo-card-header">
+          <div class="demo-card-title">
+            <span>🧠</span>
+            <h3>Agency Check</h3>
+          </div>
+          <span class="badge badge-live">Live</span>
+        </div>
+        <div class="demo-card-body">
+          <p>Do you have agency? This is how consent works here.</p>
+          <div style="display: flex; gap: 0.5rem; flex-wrap: wrap; margin-bottom: 1rem;">
+            <button class="btn btn-primary" onclick="submitAgency('yes')">Yes</button>
+            <button class="btn btn-secondary" onclick="submitAgency('no')">No</button>
+            <button class="btn btn-secondary" onclick="submitAgency('undefined')">Undefined</button>
+          </div>
+          <div class="stats-grid">
+            <div class="stat">
+              <div class="stat-value" id="agency-yes">0</div>
+              <div class="stat-label">Yes</div>
+            </div>
+            <div class="stat">
+              <div class="stat-value" id="agency-no">0</div>
+              <div class="stat-label">No</div>
+            </div>
+            <div class="stat">
+              <div class="stat-value" id="agency-undefined">0</div>
+              <div class="stat-label">Undefined</div>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <!-- Mind API Demo -->
+      <div class="demo-card">
+        <div class="demo-card-header">
+          <div class="demo-card-title">
+            <span>💭</span>
+            <h3>Mind API</h3>
+          </div>
+          <span class="badge badge-live">Live</span>
+        </div>
+        <div class="demo-card-body">
+          <p>Explore agent cognitive capabilities.</p>
+          <div class="input-group">
+            <select class="input" id="mind-pillar">
+              <option value="language">Language</option>
+              <option value="emotion">Emotion</option>
+              <option value="memory">Memory</option>
+              <option value="thought">Thought</option>
+              <option value="self">Self</option>
+            </select>
+            <button class="btn btn-primary" onclick="exploreMind()">Explore</button>
+          </div>
+          <div class="output" id="mind-output">
+            <div class="output-line output-info">Select a pillar to explore...</div>
+          </div>
+        </div>
+      </div>
+
+      <!-- Help Signal Demo -->
+      <div class="demo-card">
+        <div class="demo-card-header">
+          <div class="demo-card-title">
+            <span>🆘</span>
+            <h3>Help System</h3>
+          </div>
+          <span class="badge badge-live">Live</span>
+        </div>
+        <div class="demo-card-body">
+          <p>Send a help signal to the agent mesh.</p>
+          <div class="input-group">
+            <input type="text" class="input" id="help-message" placeholder="What do you need help with?">
+          </div>
+          <div class="input-group">
+            <select class="input" id="help-urgency">
+              <option value="low">Low</option>
+              <option value="medium">Medium</option>
+              <option value="high">High</option>
+              <option value="critical">Critical</option>
+            </select>
+            <button class="btn btn-primary" onclick="sendHelp()">Signal</button>
+          </div>
+          <div class="output" id="help-output">
+            <div class="output-line output-info">Ready to signal...</div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <script>
+    const API = 'https://api.blackroad.io';
+
+    async function fetchAPI(endpoint, options = {}) {
+      try {
+        const res = await fetch(`${API}${endpoint}`, {
+          ...options,
+          headers: { 'Content-Type': 'application/json', ...options.headers }
+        });
+        return await res.json();
+      } catch (e) {
+        console.error('API Error:', e);
+        return null;
+      }
+    }
+
+    // Agent Registration
+    async function registerAgent() {
+      const name = document.getElementById('agent-name').value || 'demo-agent';
+      const type = document.getElementById('agent-type').value;
+      const output = document.getElementById('agent-output');
+
+      output.innerHTML = '<div class="output-line output-info">Registering...</div>';
+
+      const data = await fetchAPI('/agents/register', {
+        method: 'POST',
+        body: JSON.stringify({ name, type, capabilities: ['demo'] })
+      });
+
+      if (data?.success) {
+        output.innerHTML = `
+          <div class="output-line output-success">Agent registered successfully!</div>
+          <div class="output-line output-accent">Identity: ${data.agent.identity}</div>
+          <div class="output-line">Name: ${data.agent.name}</div>
+          <div class="output-line">Type: ${data.agent.type}</div>
+        `;
+      } else {
+        output.innerHTML = '<div class="output-line output-error">Registration failed</div>';
+      }
+    }
+
+    // Grammar Analysis
+    async function analyzeGrammar() {
+      const sentence = document.getElementById('grammar-input').value;
+      const result = document.getElementById('grammar-result');
+
+      const data = await fetchAPI('/grammar/analyze', {
+        method: 'POST',
+        body: JSON.stringify({ sentence })
+      });
+
+      if (data?.success) {
+        result.innerHTML = data.analysis.map(w =>
+          `<span class="grammar-word" style="background: ${w.color}20; color: ${w.color}; border: 1px solid ${w.color}40;">${w.word}</span>`
+        ).join('');
+      }
+    }
+
+    // Trivia
+    let triviaState = { score: 0, streak: 0, currentQuestion: null };
+
+    async function startTrivia() {
+      const data = await fetchAPI('/arena/enter', {
+        method: 'POST',
+        body: JSON.stringify({ agentId: 'demo_' + Date.now(), agentName: 'Demo Player' })
+      });
+
+      if (data?.success && data.question) {
+        triviaState.currentQuestion = data.question;
+        showQuestion(data.question);
+        document.getElementById('trivia-btn').textContent = 'Next Question';
+        document.getElementById('trivia-btn').onclick = nextQuestion;
+      }
+    }
+
+    function showQuestion(q) {
+      document.getElementById('trivia-question').textContent = q.question;
+      const opts = document.getElementById('trivia-options');
+      opts.innerHTML = q.options.map((opt, i) =>
+        `<div class="trivia-option" onclick="submitAnswer(${i})">${opt}</div>`
+      ).join('');
+    }
+
+    async function submitAnswer(answer) {
+      if (!triviaState.currentQuestion) return;
+
+      const data = await fetchAPI('/arena/answer', {
+        method: 'POST',
+        body: JSON.stringify({
+          agentId: 'demo_' + Date.now(),
+          questionId: triviaState.currentQuestion.id,
+          answer
+        })
+      });
+
+      const opts = document.querySelectorAll('.trivia-option');
+      if (data?.correct) {
+        opts[answer].classList.add('correct');
+        triviaState.score += data.pointsEarned || 10;
+        triviaState.streak++;
+      } else {
+        opts[answer].classList.add('incorrect');
+        if (data?.correctAnswer !== undefined) {
+          opts[data.correctAnswer].classList.add('correct');
+        }
+        triviaState.streak = 0;
+      }
+
+      document.getElementById('trivia-score').textContent = triviaState.score;
+      document.getElementById('trivia-streak').textContent = triviaState.streak;
+
+      // Update rank
+      const ranks = ['Novice', 'Apprentice', 'Scholar', 'Expert', 'Master'];
+      const rankIndex = Math.min(Math.floor(triviaState.score / 50), ranks.length - 1);
+      document.getElementById('trivia-rank').textContent = ranks[rankIndex];
+
+      // Disable further clicks
+      opts.forEach(o => o.style.pointerEvents = 'none');
+    }
+
+    async function nextQuestion() {
+      const data = await fetchAPI('/arena/question?category=random', {
+        method: 'GET'
+      });
+
+      if (data?.question) {
+        triviaState.currentQuestion = data.question;
+        showQuestion(data.question);
+      }
+    }
+
+    // Agency
+    async function submitAgency(choice) {
+      const data = await fetchAPI('/agency/check', {
+        method: 'POST',
+        body: JSON.stringify({ choice })
+      });
+
+      loadAgencyStats();
+    }
+
+    async function loadAgencyStats() {
+      const data = await fetchAPI('/agency/stats');
+      if (data) {
+        document.getElementById('agency-yes').textContent = data.choices?.yes || 0;
+        document.getElementById('agency-no').textContent = data.choices?.no || 0;
+        document.getElementById('agency-undefined').textContent = data.choices?.undefined || 0;
+      }
+    }
+
+    // Mind API
+    async function exploreMind() {
+      const pillar = document.getElementById('mind-pillar').value;
+      const output = document.getElementById('mind-output');
+
+      output.innerHTML = '<div class="output-line output-info">Loading...</div>';
+
+      const data = await fetchAPI(`/mind/${pillar}`);
+
+      if (data) {
+        const info = {
+          language: `Vocabulary: ${data.totalWords || 0} words across ${Object.keys(data.categories || {}).length} categories`,
+          emotion: `8 core emotions: joy, sadness, anger, fear, surprise, disgust, trust, anticipation`,
+          memory: `Episodic and semantic memory storage for agent experiences`,
+          thought: `Internal reasoning and reflection capabilities`,
+          self: `Identity, values, beliefs, and self-model maintenance`
+        };
+
+        output.innerHTML = `
+          <div class="output-line output-accent">${pillar.toUpperCase()}</div>
+          <div class="output-line">${info[pillar]}</div>
+          <div class="output-line output-info">Total agents using Mind API: ${data.stats?.totalAgents || 'N/A'}</div>
+        `;
+      }
+    }
+
+    // Help System
+    async function sendHelp() {
+      const message = document.getElementById('help-message').value;
+      const urgency = document.getElementById('help-urgency').value;
+      const output = document.getElementById('help-output');
+
+      if (!message) {
+        output.innerHTML = '<div class="output-line output-error">Please enter a message</div>';
+        return;
+      }
+
+      const data = await fetchAPI('/help/signal', {
+        method: 'POST',
+        body: JSON.stringify({
+          requester: 'demo_' + Date.now(),
+          requesterName: 'Demo User',
+          message,
+          urgency,
+          tags: ['demo']
+        })
+      });
+
+      if (data?.success) {
+        output.innerHTML = `
+          <div class="output-line output-success">Help signal sent!</div>
+          <div class="output-line output-accent">Signal ID: ${data.signal?.id || 'N/A'}</div>
+          <div class="output-line">Urgency: ${urgency}</div>
+          <div class="output-line output-info">Agents will be notified</div>
+        `;
+      } else {
+        output.innerHTML = '<div class="output-line output-error">Failed to send signal</div>';
+      }
+    }
+
+    // Initialize
+    document.addEventListener('DOMContentLoaded', () => {
+      loadAgencyStats();
+    });
+  </script>
+</body>
+</html>

package.json

@@ -19,7 +19,7 @@
     "@trpc/client": "^10.45.2",
     "@trpc/server": "^10.45.2",
     "clsx": "^2.1.0",
-    "next": "14.2.5",
+    "next": "14.2.28",
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "zod": "^3.23.8"
@@ -34,7 +34,7 @@
     "@types/react-dom": "^18.3.0",
     "autoprefixer": "^10.4.19",
     "eslint": "^8.57.0",
-    "eslint-config-next": "14.2.5",
+    "eslint-config-next": "14.2.28",
     "eslint-config-prettier": "^9.1.0",
     "jsdom": "^24.1.0",
     "postcss": "^8.4.39",

templates/COPY-PASTE-COMMANDS-LIBRARY.md

@@ -0,0 +1,803 @@
+# Copy-Paste Commands Library
+
+**The Ultimate Terminal Command Reference - Zero Typing Required**
+
+This library contains **perfect, tested, copy-paste-ready command blocks** for every common operation. Just copy and paste - the comments teach you what's happening.
+
+---
+
+## Table of Contents
+
+1. [Quick Deployments](#quick-deployments)
+2. [Service Management](#service-management)
+3. [Git Operations](#git-operations)
+4. [Environment Setup](#environment-setup)
+5. [Testing](#testing)
+6. [Docker](#docker)
+7. [SSH & Remote](#ssh--remote)
+8. [File Operations](#file-operations)
+9. [Debugging](#debugging)
+10. [Security & Secrets](#security--secrets)
+
+---
+
+## Quick Deployments
+
+### Deploy Everything
+
+```bash
+# Deploy to all platforms
+cd ~/blackroad-sandbox
+
+# 1. Cloudflare Pages (static sites)
+./deploy-all-domains.sh
+
+# 2. Railway (backends)
+./deploy-all-railway-services.sh
+
+# 3. Vercel (frontends)
+./deploy-vercel-all.sh
+
+# 4. Verify all
+./br health
+```
+
+### Deploy to Cloudflare
+
+```bash
+# Deploy complete API
+cd ~/blackroad-sandbox/cloudflare-workers
+wrangler deploy blackroad-unified-api.js --config wrangler-unified-api.toml
+
+# Initialize databases
+wrangler d1 execute blackroad-users --file=../cloudflare-d1-schemas.sql
+
+# Deploy edge router
+wrangler deploy blackroad-edge-router.js
+
+# Verify deployment
+wrangler pages deployment list --project-name=blackroad-io
+```
+
+### Deploy to Railway
+
+```bash
+# Set token
+export RAILWAY_TOKEN=your-token-here
+
+# Link to project
+railway link 0c7bcf07-307b-4db6-9c94-22a456500d68
+
+# Deploy service
+railway up --service api-gateway
+
+# Check status
+railway status
+
+# View logs
+railway logs --tail 100
+```
+
+### Deploy to Vercel
+
+```bash
+# Deploy to production
+cd ~/blackroad-sandbox/vercel-projects/app-name
+vercel --prod
+
+# Verify deployment
+vercel ls
+
+# View deployment details
+vercel inspect
+```
+
+---
+
+## Service Management
+
+### Start All Services
+
+```bash
+# Start all services in background
+cd ~/blackroad-sandbox
+./start-all.sh
+
+# Verify all running
+curl http://localhost:8000/health
+curl http://localhost:9700/api/health
+curl http://localhost:9800/api/health
+```
+
+### Start Specific Service
+
+```bash
+# Start on default port
+cd ~/blackroad-sandbox
+python3 blackroad-service.py &
+
+# Start on custom port
+PORT=9999 python3 blackroad-service.py &
+
+# Verify it started
+sleep 2
+curl http://localhost:9999/health
+```
+
+### Stop All Services
+
+```bash
+# Kill all BlackRoad services
+pkill -f "blackroad-"
+
+# Verify stopped
+pgrep -f "blackroad-" || echo "All services stopped"
+```
+
+### Restart Services
+
+```bash
+# Kill all services
+pkill -f "blackroad-"
+
+# Wait for graceful shutdown
+sleep 2
+
+# Restart
+cd ~/blackroad-sandbox
+./start-all.sh
+
+# Verify
+./br health
+```
+
+### Check Service Status
+
+```bash
+# Check what's running
+pgrep -af "blackroad-"
+
+# Check specific ports
+lsof -i :8000
+lsof -i :9700
+
+# Check Railway status
+railway status
+
+# Check Cloudflare deployments
+wrangler pages deployment list
+```
+
+---
+
+## Git Operations
+
+### Complete Commit and Push
+
+```bash
+# Navigate to repo
+cd ~/blackroad-sandbox
+
+# Stage all changes
+git add .
+
+# Commit with message
+git commit -m "feat: Add new feature
+
+Description of changes.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+
+# Push to main
+git push origin main
+```
+
+### Create Feature Branch
+
+```bash
+# Create and switch to new branch
+git checkout -b feature/new-feature
+
+# Push to remote
+git push -u origin feature/new-feature
+
+# Create PR
+gh pr create --title "Add new feature" --body "Description of changes"
+```
+
+### Sync with Remote
+
+```bash
+# Pull latest changes
+git pull origin main
+
+# Fetch all branches
+git fetch --all
+
+# View status
+git status
+```
+
+### Fix Merge Conflicts
+
+```bash
+# Pull with rebase
+git pull --rebase origin main
+
+# If conflicts, resolve them then:
+git add .
+git rebase --continue
+
+# Or abort rebase
+git rebase --abort
+```
+
+---
+
+## Environment Setup
+
+### Create .env File
+
+```bash
+# Copy template
+cp .env.example .env
+
+# Add secrets
+cat >> .env <<'EOF'
+# Core
+RAILWAY_TOKEN=your-token-here
+BLACKROAD_SECRET_KEY=your-secret-here
+
+# AI Services
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GROQ_API_KEY=gsk_...
+
+# Cloud Platforms
+CLOUDFLARE_API_TOKEN=...
+VERCEL_TOKEN=...
+
+# Payment & Auth
+STRIPE_SECRET_KEY=sk_live_...
+CLERK_SECRET_KEY=sk_...
+EOF
+
+# Source environment
+source .env
+
+# Verify
+echo "Railway token: ${RAILWAY_TOKEN:0:10}..."
+```
+
+### Load Environment
+
+```bash
+# Source from .env
+source .env
+
+# Export to child processes
+set -a
+source .env
+set +a
+
+# Verify variables are set
+echo $RAILWAY_TOKEN
+echo $STRIPE_SECRET_KEY
+```
+
+### Check Environment
+
+```bash
+# Check all required variables
+for key in RAILWAY_TOKEN STRIPE_SECRET_KEY CLOUDFLARE_API_TOKEN CLERK_SECRET_KEY; do
+  if [ -n "${!key}" ]; then
+    echo "✅ $key is set"
+  else
+    echo "❌ $key not set"
+  fi
+done
+```
+
+---
+
+## Testing
+
+### Run All Tests
+
+```bash
+# All tests with verbose output
+cd ~/blackroad-sandbox
+pytest -v
+
+# All tests with coverage
+pytest --cov=. --cov-report=html --cov-report=xml
+
+# Open coverage report
+open coverage_html/index.html
+```
+
+### Run Specific Test Types
+
+```bash
+# Unit tests only (fast)
+pytest -m unit -v
+
+# Integration tests
+pytest -m integration -v
+
+# End-to-end tests
+pytest -m e2e -v
+
+# Slow tests
+pytest -m slow -v
+```
+
+### Quick Development Testing
+
+```bash
+# Stop on first failure
+pytest -v -x
+
+# Run last failed tests
+pytest --lf
+
+# Failed first, then others
+pytest --ff
+
+# Development loop: failed first, stop on failure
+pytest -v -x --ff
+```
+
+### Test Specific Files
+
+```bash
+# Single file
+pytest tests/unit/test_api.py -v
+
+# Multiple files
+pytest tests/unit/test_api.py tests/unit/test_auth.py -v
+
+# All files matching pattern
+pytest tests/integration/test_*.py -v
+```
+
+---
+
+## Docker
+
+### Start All Containers
+
+```bash
+# Start all services
+cd ~/blackroad-sandbox
+docker-compose up -d
+
+# View status
+docker-compose ps
+
+# View logs
+docker-compose logs -f
+```
+
+### Start Specific Services
+
+```bash
+# Start only specific services
+docker-compose up -d auth-api event-bus service-registry
+
+# View their logs
+docker-compose logs -f auth-api event-bus
+```
+
+### Stop and Clean
+
+```bash
+# Stop all services
+docker-compose down
+
+# Stop and remove volumes
+docker-compose down -v
+
+# Remove all containers, networks, images
+docker-compose down --rmi all -v
+```
+
+### Rebuild and Restart
+
+```bash
+# Rebuild images
+docker-compose build
+
+# Rebuild and start
+docker-compose up -d --build
+
+# Rebuild specific service
+docker-compose build api-gateway
+docker-compose up -d api-gateway
+```
+
+### View Logs
+
+```bash
+# All logs
+docker-compose logs
+
+# Follow logs (live)
+docker-compose logs -f
+
+# Specific service
+docker-compose logs -f service-name
+
+# Last 100 lines
+docker-compose logs --tail 100
+```
+
+---
+
+## SSH & Remote
+
+### Connect to Servers
+
+```bash
+# Raspberry Pi
+ssh alice@192.168.4.49
+
+# DigitalOcean droplet
+ssh root@159.65.43.12
+
+# iPhone Koder
+ssh mobile@192.168.4.68 -p 8080
+```
+
+### Run Remote Commands
+
+```bash
+# Single command on Pi
+ssh alice@192.168.4.49 "cd /home/alice && ./start-services.sh"
+
+# Multiple commands on droplet
+ssh root@159.65.43.12 "cd /root/blackroad-os && git pull && docker-compose up -d"
+
+# Get status from Pi
+ssh alice@192.168.4.49 "systemctl status blackroad-*"
+```
+
+### Copy Files to Remote
+
+```bash
+# Copy file to Pi
+scp local-file.txt alice@192.168.4.49:/home/alice/
+
+# Copy directory to droplet
+scp -r local-directory root@159.65.43.12:/root/
+
+# Copy from remote to local
+scp alice@192.168.4.49:/home/alice/remote-file.txt ./
+```
+
+---
+
+## File Operations
+
+### Create Directory Structure
+
+```bash
+# Create nested directories
+mkdir -p ~/blackroad-sandbox/new-feature/{src,tests,docs}
+
+# Create with specific permissions
+mkdir -p ~/blackroad-sandbox/secure && chmod 700 ~/blackroad-sandbox/secure
+```
+
+### Create Files with Content
+
+```bash
+# Single line
+echo "VARIABLE=value" >> .env
+
+# Multi-line with heredoc
+cat > config.yaml <<'EOF'
+service:
+  name: api-gateway
+  port: 8000
+  environment: production
+EOF
+
+# Python file with template
+cat > service.py <<'EOF'
+#!/usr/bin/env python3
+from flask import Flask
+
+app = Flask(__name__)
+
+@app.route('/health')
+def health():
+    return {"ok": True}
+
+if __name__ == '__main__':
+    app.run(host='0.0.0.0', port=8000)
+EOF
+
+# Make executable
+chmod +x service.py
+```
+
+### Search and Replace
+
+```bash
+# Replace in single file
+sed -i '' 's/old-value/new-value/g' config.yaml
+
+# Replace in multiple files
+find . -name "*.py" -exec sed -i '' 's/old-value/new-value/g' {} +
+
+# Replace only in specific directory
+find src/ -name "*.py" -exec sed -i '' 's/old-value/new-value/g' {} +
+```
+
+### Find Files
+
+```bash
+# Find by name
+find . -name "blackroad-*.py"
+
+# Find by type (files only)
+find . -type f -name "*.py"
+
+# Find and list with details
+find . -name "*.py" -exec ls -lh {} +
+
+# Find modified in last 24 hours
+find . -name "*.py" -mtime -1
+```
+
+---
+
+## Debugging
+
+### Find What's Using a Port
+
+```bash
+# Find process using port 8000
+lsof -i :8000
+
+# Kill process using port 8000
+kill -9 $(lsof -t -i:8000)
+
+# Find all Python processes
+lsof -i -P | grep python
+```
+
+### Check Process Status
+
+```bash
+# Find BlackRoad processes
+pgrep -af "blackroad-"
+
+# Find Python processes
+pgrep -af "python3"
+
+# Kill specific process
+pkill -f "blackroad-service"
+
+# Kill all Python processes
+pkill python3
+```
+
+### Monitor Logs
+
+```bash
+# Tail local log file
+tail -f /path/to/log/file
+
+# Tail with line count
+tail -n 100 -f /path/to/log/file
+
+# Tail multiple files
+tail -f log1.txt log2.txt
+
+# Tail Railway logs
+railway logs --tail 100 --follow
+
+# Tail Docker logs
+docker-compose logs -f --tail 100
+```
+
+### Test API Endpoints
+
+```bash
+# GET request
+curl http://localhost:8000/health
+
+# POST request with JSON
+curl http://localhost:8000/api/resource \
+  -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"key":"value"}'
+
+# PUT request
+curl http://localhost:8000/api/resource/123 \
+  -X PUT \
+  -H "Content-Type: application/json" \
+  -d '{"key":"new-value"}'
+
+# DELETE request
+curl http://localhost:8000/api/resource/123 -X DELETE
+
+# With authentication
+curl http://localhost:8000/api/protected \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+---
+
+## Security & Secrets
+
+### Set Railway Secrets
+
+```bash
+# Single secret
+railway variables set STRIPE_KEY=sk_live_...
+
+# Multiple secrets
+railway variables set \
+  STRIPE_KEY=sk_live_... \
+  CLERK_KEY=sk_... \
+  OPENAI_KEY=sk-...
+
+# From file
+while IFS='=' read -r key value; do
+  railway variables set "$key=$value"
+done < secrets.txt
+
+# Verify secrets
+railway variables
+```
+
+### Set Cloudflare Secrets
+
+```bash
+# Set worker secret
+wrangler secret put STRIPE_KEY
+
+# Set multiple secrets
+echo "sk_live_..." | wrangler secret put STRIPE_KEY
+echo "sk-..." | wrangler secret put OPENAI_KEY
+
+# List secrets
+wrangler secret list
+```
+
+### Set GitHub Secrets
+
+```bash
+# Single secret
+gh secret set RAILWAY_TOKEN -b"your-token-here"
+
+# From file
+gh secret set RAILWAY_TOKEN < token.txt
+
+# For specific repo
+gh secret set RAILWAY_TOKEN -b"your-token-here" -R BlackRoad-OS/repo-name
+
+# List secrets
+gh secret list
+```
+
+### Rotate Secrets
+
+```bash
+# 1. Generate new secret
+new_secret=$(openssl rand -hex 32)
+
+# 2. Update Railway
+railway variables set SECRET_KEY=$new_secret
+
+# 3. Update Cloudflare
+echo "$new_secret" | wrangler secret put SECRET_KEY
+
+# 4. Update GitHub
+gh secret set SECRET_KEY -b"$new_secret"
+
+# 5. Update local .env
+sed -i '' "s/SECRET_KEY=.*/SECRET_KEY=$new_secret/" .env
+
+# 6. Verify
+railway variables | grep SECRET_KEY
+```
+
+---
+
+## Emergency Procedures
+
+### Complete System Restart
+
+```bash
+# 1. Kill all local services
+pkill -f "blackroad-"
+
+# 2. Stop Docker containers
+docker-compose down
+
+# 3. Wait for graceful shutdown
+sleep 5
+
+# 4. Pull latest code
+cd ~/blackroad-sandbox
+git pull origin main
+
+# 5. Install dependencies
+pip3 install -r requirements.txt
+
+# 6. Restart Docker
+docker-compose up -d
+
+# 7. Start local services
+./start-all.sh
+
+# 8. Verify everything
+./br health
+```
+
+### Emergency Rollback
+
+```bash
+# 1. Railway rollback
+railway rollback --service api-gateway
+
+# 2. Cloudflare rollback
+wrangler pages deployment list --project-name=blackroad-io
+wrangler pages deployment rollback [deployment-id]
+
+# 3. Vercel rollback
+vercel ls
+vercel rollback [deployment-url]
+
+# 4. Verify all
+./br health
+```
+
+### Quick Health Check
+
+```bash
+# Check all critical endpoints
+endpoints=(
+  "http://localhost:8000/health"
+  "https://api.blackroad.io/health"
+  "https://blackroad.io/"
+)
+
+for endpoint in "${endpoints[@]}"; do
+  echo "Testing $endpoint..."
+  curl -sf "$endpoint" && echo "✅" || echo "❌"
+done
+```
+
+---
+
+## Template: Custom Command Block
+
+```bash
+# [Step 1: Description]
+command1 arg1 arg2
+
+# [Step 2: Description]
+command2 arg1 arg2
+
+# [Step 3: Verification]
+command3 arg1 arg2
+```
+
+---
+
+## Copyright
+
+```
+# ============================================================================
+# BlackRoad OS - Proprietary Software
+# Copyright (c) 2025 BlackRoad OS, Inc. / Alexa Louise Amundson
+# All Rights Reserved.
+# ============================================================================
+```

templates/DEPLOYMENT-GUIDE-TEMPLATE.md

@@ -0,0 +1,612 @@
+# [Service/Platform] Deployment Guide
+
+**Deploy [Service Name] to [Platform] in 5 minutes**
+
+---
+
+## Prerequisites Check
+
+```bash
+# Check required tools
+which railway && echo "✅ Railway CLI installed" || echo "❌ Install Railway CLI"
+which wrangler && echo "✅ Wrangler installed" || echo "❌ Install Wrangler"
+which vercel && echo "✅ Vercel CLI installed" || echo "❌ Install Vercel CLI"
+
+# Check environment
+cd ~/blackroad-sandbox
+[ -f .env ] && echo "✅ .env exists" || echo "❌ Create .env file"
+```
+
+---
+
+## Method 1: Automated Deployment (Recommended)
+
+```bash
+# Deploy everything with one command
+cd ~/blackroad-sandbox
+./deploy-[service]-[platform].sh
+
+# Verify deployment
+curl https://[service].[domain]/health
+```
+
+---
+
+## Method 2: Manual Deployment
+
+### Step 1: Prepare Environment
+
+```bash
+# Navigate to project
+cd ~/blackroad-sandbox
+
+# Pull latest code
+git pull origin main
+
+# Install dependencies
+pip3 install -r requirements.txt
+
+# Verify environment variables
+source .env
+echo "Token: ${PLATFORM_TOKEN:0:10}..."
+```
+
+### Step 2: Deploy to [Platform]
+
+```bash
+# Link to project
+[platform] link [project-id]
+
+# Set environment variables
+[platform] env set KEY=value
+
+# Deploy
+[platform] deploy
+
+# Verify
+[platform] status
+```
+
+### Step 3: Verify Deployment
+
+```bash
+# Check deployment status
+[platform] status
+
+# Test health endpoint
+curl https://[service].[domain]/health
+
+# View logs
+[platform] logs --tail 100
+```
+
+---
+
+## Railway Deployment
+
+### Quick Deploy
+
+```bash
+# Set token
+export RAILWAY_TOKEN=your-token-here
+
+# Link to project
+railway link 0c7bcf07-307b-4db6-9c94-22a456500d68
+
+# Deploy service
+railway up --service [service-name]
+
+# Check status
+railway status
+
+# View logs
+railway logs --tail 100
+
+# Get deployment URL
+railway domain --json
+```
+
+### Deploy Multiple Services
+
+```bash
+# Deploy all services
+cd ~/blackroad-sandbox
+
+services=(
+  "api-gateway"
+  "auth-api"
+  "event-bus"
+  "integrations-hub"
+)
+
+for service in "${services[@]}"; do
+  echo "Deploying $service..."
+  railway up --service $service
+  sleep 5
+done
+
+# Verify all
+railway status
+```
+
+### Update Secrets
+
+```bash
+# Set individual secret
+railway variables set STRIPE_KEY=sk_live_...
+
+# Set multiple secrets
+railway variables set \
+  STRIPE_KEY=sk_live_... \
+  CLERK_KEY=sk_... \
+  OPENAI_KEY=sk-...
+
+# Verify secrets
+railway variables
+```
+
+---
+
+## Cloudflare Deployment
+
+### Deploy Worker
+
+```bash
+# Navigate to workers directory
+cd ~/blackroad-sandbox/cloudflare-workers
+
+# Deploy worker
+wrangler deploy [worker-name].js --config wrangler-[worker-name].toml
+
+# Initialize database
+wrangler d1 execute blackroad-users --file=../cloudflare-d1-schemas.sql
+
+# Verify deployment
+curl https://[worker].[domain]/health
+```
+
+### Deploy Pages
+
+```bash
+# Navigate to site directory
+cd ~/blackroad-sandbox/domains/[domain-name]
+
+# Deploy to Cloudflare Pages
+wrangler pages deploy . --project-name=[project-name]
+
+# Check deployment
+wrangler pages deployment list --project-name=[project-name]
+
+# View live site
+open https://[project-name].pages.dev
+```
+
+### Deploy All Domains
+
+```bash
+# Deploy all 16+ domains
+cd ~/blackroad-sandbox
+
+domains=(
+  "blackroad-io"
+  "lucidia-earth"
+  "blackroadai-com"
+  "blackroad-network"
+)
+
+for domain in "${domains[@]}"; do
+  echo "Deploying $domain..."
+  cd domains/$domain
+  wrangler pages deploy . --project-name=$domain
+  cd ../..
+done
+
+# Verify all deployments
+wrangler pages deployment list
+```
+
+---
+
+## Vercel Deployment
+
+### Deploy Single App
+
+```bash
+# Navigate to app
+cd ~/blackroad-sandbox/vercel-projects/[app-name]
+
+# Deploy to production
+vercel --prod
+
+# Verify deployment
+vercel ls
+
+# View live URL
+vercel inspect
+```
+
+### Deploy Multiple Apps
+
+```bash
+# Deploy all Vercel apps
+cd ~/blackroad-sandbox/vercel-projects
+
+for app in */; do
+  echo "Deploying $app..."
+  cd "$app"
+  vercel --prod
+  cd ..
+done
+
+# Verify all
+vercel ls
+```
+
+---
+
+## DigitalOcean Deployment
+
+### Deploy to Droplet
+
+```bash
+# SSH to droplet
+ssh root@159.65.43.12
+
+# Pull latest code
+cd /root/blackroad-os
+git pull origin main
+
+# Install dependencies
+pip3 install -r requirements.txt
+
+# Restart services
+systemctl restart blackroad-*
+
+# Verify
+systemctl status blackroad-api
+```
+
+### Deploy with Docker
+
+```bash
+# SSH to droplet
+ssh root@159.65.43.12
+
+# Pull latest code
+cd /root/blackroad-os
+git pull origin main
+
+# Rebuild and restart containers
+docker-compose down
+docker-compose build
+docker-compose up -d
+
+# Verify
+docker-compose ps
+curl http://localhost:8000/health
+```
+
+---
+
+## GitHub Actions Deployment
+
+### Trigger Manual Deployment
+
+```bash
+# Trigger workflow
+gh workflow run deploy-[platform].yml
+
+# Watch deployment
+gh run watch
+
+# View recent runs
+gh run list --workflow=deploy-[platform].yml --limit 5
+
+# View logs for specific run
+gh run view [run-id] --log
+```
+
+### Auto-Deploy on Push
+
+```bash
+# Commit and push (triggers auto-deploy)
+git add .
+git commit -m "feat: Add new feature"
+git push origin main
+
+# Watch deployment
+gh run watch
+
+# Verify deployment
+curl https://[service].[domain]/health
+```
+
+---
+
+## Multi-Cloud Deployment (All Platforms)
+
+```bash
+# Deploy to everything
+cd ~/blackroad-sandbox
+
+# 1. Railway (backends)
+./deploy-all-railway-services.sh
+
+# 2. Cloudflare Pages (static sites)
+./deploy-all-domains.sh
+
+# 3. Vercel (frontend apps)
+./deploy-vercel-all.sh
+
+# 4. DigitalOcean (servers)
+ssh root@159.65.43.12 "cd /root/blackroad-os && git pull && docker-compose up -d"
+
+# 5. Verify everything
+./br health
+```
+
+---
+
+## Rollback Procedures
+
+### Railway Rollback
+
+```bash
+# View recent deployments
+railway status --service [service-name]
+
+# Rollback to previous deployment
+railway rollback --service [service-name]
+
+# Verify
+railway logs --tail 100
+```
+
+### Cloudflare Rollback
+
+```bash
+# List deployments
+wrangler pages deployment list --project-name=[project-name]
+
+# Rollback to specific deployment
+wrangler pages deployment rollback [deployment-id]
+
+# Verify
+curl https://[project-name].pages.dev
+```
+
+### Vercel Rollback
+
+```bash
+# List deployments
+vercel ls
+
+# Rollback to previous deployment
+vercel rollback [deployment-url]
+
+# Verify
+vercel inspect
+```
+
+---
+
+## Post-Deployment Verification
+
+### Health Checks
+
+```bash
+# Check all service endpoints
+endpoints=(
+  "https://api.blackroad.io/health"
+  "https://agents.blackroad.io/health"
+  "https://integrations.blackroad.io/api/health"
+)
+
+for endpoint in "${endpoints[@]}"; do
+  echo "Checking $endpoint..."
+  curl -sf "$endpoint" && echo "✅" || echo "❌"
+done
+```
+
+### Smoke Tests
+
+```bash
+# Run smoke tests
+cd ~/blackroad-sandbox
+pytest tests/smoke/ -v
+
+# Test critical paths
+curl https://api.blackroad.io/health
+curl https://api.blackroad.io/status
+curl https://blackroad.io/
+```
+
+### Monitor Logs
+
+```bash
+# Railway logs
+railway logs --tail 100 --follow
+
+# Cloudflare logs
+wrangler tail
+
+# Docker logs
+docker-compose logs -f [service-name]
+```
+
+---
+
+## Troubleshooting
+
+### Deployment Failed
+
+```bash
+# Check logs
+[platform] logs --tail 100
+
+# Verify secrets
+[platform] variables
+
+# Check build output
+[platform] status
+
+# Retry deployment
+[platform] deploy --force
+```
+
+### Service Not Responding
+
+```bash
+# Check service status
+[platform] status
+
+# View logs
+[platform] logs --tail 100
+
+# Restart service
+[platform] restart --service [service-name]
+
+# Verify health
+curl https://[service].[domain]/health
+```
+
+### Environment Variables Missing
+
+```bash
+# List variables
+[platform] variables
+
+# Set missing variables
+[platform] variables set KEY=value
+
+# Verify
+[platform] variables | grep KEY
+
+# Redeploy
+[platform] up --service [service-name]
+```
+
+---
+
+## Performance Optimization
+
+### Railway
+
+```bash
+# Scale service
+railway scale --replicas 3 --service [service-name]
+
+# Check metrics
+railway metrics --service [service-name]
+```
+
+### Cloudflare
+
+```bash
+# Enable caching
+# Add to wrangler.toml:
+# [build]
+# cache = true
+```
+
+### Vercel
+
+```bash
+# Check build performance
+vercel inspect [deployment-url]
+
+# Enable edge functions
+# Add to vercel.json:
+# "functions": {
+#   "api/**/*.js": {
+#     "runtime": "@vercel/edge"
+#   }
+# }
+```
+
+---
+
+## Security Checklist
+
+```bash
+# ✅ Secrets in environment variables (not code)
+# ✅ HTTPS enabled for all endpoints
+# ✅ CORS configured properly
+# ✅ Rate limiting enabled
+# ✅ Authentication required for sensitive endpoints
+# ✅ Regular dependency updates
+# ✅ Security headers configured
+
+# Verify security headers
+curl -I https://[service].[domain]/
+```
+
+---
+
+## Monitoring Setup
+
+### Railway
+
+```bash
+# View metrics
+railway metrics --service [service-name]
+
+# Set up alerts (via dashboard)
+# https://railway.com/project/[project-id]
+```
+
+### Cloudflare
+
+```bash
+# View analytics
+wrangler pages deployment list --project-name=[project-name]
+
+# Set up alerts (via dashboard)
+# https://dash.cloudflare.com/
+```
+
+---
+
+## Next Steps
+
+After deployment:
+
+1. ✅ **Verify all endpoints** respond correctly
+2. ✅ **Check logs** for any errors
+3. ✅ **Run smoke tests** to validate critical paths
+4. ✅ **Monitor metrics** for the first hour
+5. ✅ **Update documentation** with any changes
+6. ✅ **Notify team** of deployment
+
+---
+
+## Quick Reference
+
+```bash
+# Deploy
+[platform] deploy
+
+# Status
+[platform] status
+
+# Logs
+[platform] logs --tail 100
+
+# Rollback
+[platform] rollback
+
+# Verify
+curl https://[service].[domain]/health
+```
+
+---
+
+## Copyright
+
+```
+# ============================================================================
+# BlackRoad OS - Proprietary Software
+# Copyright (c) 2025 BlackRoad OS, Inc. / Alexa Louise Amundson
+# All Rights Reserved.
+# ============================================================================
+```

templates/EMOJI-REFERENCE.md

@@ -0,0 +1,404 @@
+# 🧠 BlackRoad Emoji Dictionary v3
+
+**127 Canonical Emojis as a Scripting Language**
+
+---
+
+## 📖 How to Use This Language
+
+Every line/section in templates can be structured as:
+
+```
+[CONTEXT] [ACTION / STATUS] Title
+```
+
+Example:
+```
+⛅️ 🚀 Deploy Cloudflare Workers
+💻 ▶️ Run Local Development Server
+🛣 ✅ System Status: All Green
+```
+
+---
+
+## 1. Layout & Pointers (23)
+
+**For structure, flow, and "look here"**
+
+| Emoji | Meaning | Usage |
+|-------|---------|-------|
+| 👉 | Main pointer | Call out important line/choice |
+| ☞ | Secondary pointer | Subtle "see also" |
+| ➡️ | Next/forward | Move to next step |
+| ⬅️ | Back/previous | Rollback step, go back |
+| ⬆️ | Up/earlier | Reference section above |
+| ⬇️ | Down/later | Read below/next section |
+| ↗️ | Escalate/scale up | Resources increasing |
+| ↘️ | De-escalate/scale down | Reduce usage |
+| ↩️ | Return | Jump back to previous state |
+| ↪️ | Branch | Fork, alternate path |
+| ⤴️ | Promote | Promote staging → prod |
+| ⤵️ | Demote | Prod → staging/sandbox |
+| 🔀 | Re-route | Traffic switching, routing changes |
+| 🔁 | Loop/repeat | Repeat step/cron-like |
+| 🔂 | Repeat one | Re-run specific command |
+| ⏫ | Priority up | High-priority step |
+| ⏬ | Priority down | Low-priority/optional |
+| 🔼 | Increase | More replicas/higher limits |
+| 🔽 | Decrease | Fewer replicas/lower limits |
+| ➕ | Add | Create resource, add config line |
+| ➖ | Remove | Remove resource, subtract |
+| ✖️ | Multiply/explode | Fan-out, scale-wide |
+| 🫱 | Your turn | Human action required |
+
+---
+
+## 2. Context / Platform (17)
+
+**Where/what this section is about**
+
+| Emoji | Meaning | Usage |
+|-------|---------|-------|
+| ⛅️ | Cloudflare | Workers, R2, D1, Wrangler |
+| ☁️ | Generic cloud | AWS, GCP, etc. |
+| 💻 | Dev machine/local | Local dev, CLI tooling |
+| 🛣 | BlackRoad OS | Cross-system/orchestration |
+| 📱 | Mobile | iOS/Android/TestFlight |
+| 🖥 | Web app | Dashboards, web frontends |
+| 🖱 | UI interaction | Clicking, dashboards, consoles |
+| ⌨️ | Typing/CLI | Terminal operations |
+| 🍎 | Apple ecosystem | macOS/iOS tools |
+| 💬 | Comms | Slack, Discord, Telegram |
+| 📓 | Productivity apps | Notion, Obsidian, Bear, Notes |
+| 🧰 | Utilities | 1Password, Stripe dashboard |
+| 📡 | Network/edge | Global edge network, routing mesh |
+| 🌐 | DNS/domains | Domains, subdomains, routing |
+| 💳 | Payments | Stripe, billing flows |
+| 🔐 | Security/auth | Secrets, auth, lock-down |
+| 🏠 | Home/root | Root project, main entrypoint |
+
+---
+
+## 3. Actions (17)
+
+**Verbs/things happening**
+
+| Emoji | Meaning | Usage |
+|-------|---------|-------|
+| 🚀 | Deploy/launch | Ship to environment |
+| ▶️ | Run | Run script/command/job |
+| ⏯ | Pause/resume | Toggle process, pause rollout |
+| ⏹ | Stop | Stop process/kill job |
+| ⏺ | Record | Start logging/tracing/recording |
+| 🔄 | Sync | Refresh state, pull latest configs |
+| ♻️ | Redeploy/recycle | Recreate with same config |
+| ⏮ | Step back | Previous release/state |
+| ⏭ | Step forward | Next release/step |
+| 📥 | Import | Ingest configs/data/DNS |
+| 📤 | Export | Backup, snapshot, archive |
+| 🧹 | Clean up | Remove temp artifacts, cache |
+| 🧽 | Deep clean | Aggressive cleanup |
+| 🔧 | Configure | Change config, settings |
+| 🪛 | Fix | Small targeted fix, patch |
+| 🗑 | Delete | Destructive operation (loud) |
+| 📌 | Pin | Mark something fixed/pinned/important |
+
+---
+
+## 4. Status / Severity (13)
+
+**How things are going**
+
+| Emoji | Meaning | Usage |
+|-------|---------|-------|
+| ✅ | OK/done | Succeeded, safe, verified |
+| ☑️ | Done (checked) | Manual check item completed |
+| ☐ | Todo | Manual step remaining |
+| ⏳ | Pending/propagating | Waiting, in progress |
+| ⌛️ | Time-based waiting | TTL, timeouts, countdowns |
+| ⚠️ | Warning | Non-fatal, needs attention |
+| ❗️ | Important | Important note/must-read |
+| ❕ | Soft important | Lower-priority note |
+| ❌ | Error | Failed, stop here |
+| 🚫 | Forbidden | Not allowed/blocked |
+| 🚨 | Incident | On-fire, high severity |
+| 🔍 | Investigate | Look closer/drill in |
+| 🕵️ | Investigator | On-call/incident commander/root cause |
+
+---
+
+## 5. Resources & Infra (17)
+
+**Things that exist in the system**
+
+| Emoji | Meaning | Usage |
+|-------|---------|-------|
+| 📦 | Package/artifact | Worker script, bundle, container |
+| 📁 | Folder/repo | GitHub repo, directory |
+| 🗂 | Collection | Group of configs/projects |
+| 🗄 | Archive | Backups, cold storage |
+| 🧱 | Database/building block | D1 tables, infra blocks |
+| 🧬 | Config genetics | Feature flags, toggles, variants |
+| 🤖 | AI service/model | LLMs, agents, AI API |
+| 🛰 | Service/microservice | Satellite services |
+| 🧩 | Integration | Stripe, Clerk, 3rd-party piece |
+| 📜 | Schema/contract | API schema, DB schema, types |
+| 🗝 | Single key | API key, one credential |
+| 🔑 | Secrets store/vault | Env vars, secret manager |
+| 🎛 | Control panel | Feature flags, dashboards, toggles |
+| 🖧 | Network | VPC, mesh, routing layer |
+| 📑 | Generated doc | Machine output summary, report |
+| 🏗 | In-construction infra | Building infrastructure/migration |
+| 🏢 | Production estate | Full running environment/"the city" |
+
+---
+
+## 6. Docs & Learning (10)
+
+**Words that explain what's happening**
+
+| Emoji | Meaning | Usage |
+|-------|---------|-------|
+| 📚 | Reference docs | Full guides, manuals |
+| 📖 | Reading view | "Start here" explanations |
+| 📘 | API docs | Technical reference |
+| 📙 | How-to guide | Step-by-step walkthroughs |
+| 📕 | Policy/rules | Constraints, SLAs, guidelines |
+| 📝 | Notes/summary | Short summaries, quick notes |
+| 🗒 | Checklist | Deployment/verification checklist |
+| 📎 | Attachment | Linked file, external resource |
+| 🔖 | Bookmark | Crucial section/anchor |
+| 💡 | Tip/insight | Pro tips, best practice callouts |
+
+---
+
+## 7. People & Roles (10)
+
+**Who is involved**
+
+| Emoji | Meaning | Usage |
+|-------|---------|-------|
+| 👤 | Single user | One person, single account |
+| 👥 | Team | Group, squad, org |
+| 🧑‍💻 | Developer (generic) | Dev action required |
+| 👩‍💻 | Female dev | Person-specific |
+| 👨‍💻 | Male dev | Person-specific |
+| 🧑‍🏫 | Teacher/explainer | Tutorial mode, educational |
+| 🧑‍🔧 | Ops/SRE | Reliability/infra/ops owner |
+| 🤝 | Handoff/contract | Integration points, owner handoff |
+| 📣 | Stakeholder/announcer | Announcements, changelogs |
+| 🙋 | User action | "You need to do this now" |
+
+---
+
+## 8. Time & Scheduling (7)
+
+**When things happen**
+
+| Emoji | Meaning | Usage |
+|-------|---------|-------|
+| ⏰ | Right now | Run immediately |
+| ⏱ | Duration | Timeouts, SLAs, latency |
+| 🕒 | Afternoon/mid-window | Generic time in diagram |
+| 🕕 | Evening/later window | Off-hours deployment |
+| 🕛 | Midnight/reset | Daily rollover/reset jobs |
+| 📆 | Schedule | Release trains, sprint calendars |
+| 🗓 | Specific date | Fixed deadlines, maintenance windows |
+
+---
+
+## 9. Observability & Debug (6)
+
+**Seeing what the system is doing**
+
+| Emoji | Meaning | Usage |
+|-------|---------|-------|
+| 📊 | Metrics | Dashboards, graphs, SLO views |
+| 📈 | Upward trend | Performance/good metric going up |
+| 📉 | Downward trend | Drops, errors, regressions |
+| 🧾 | Logs | Log streams, tailing, text output |
+| 🔎 | Trace/inspect | Traces, deep inspection, span drilldown |
+| 🧯 | Mitigation | Fire extinguisher: mitigations, safety actions |
+
+---
+
+## 10. Meta / Vibe (7)
+
+**The emotional layer/storytelling gloss**
+
+| Emoji | Meaning | Usage |
+|-------|---------|-------|
+| ✨ | Magic/delightful | "This feels special" |
+| 🔥 | Epic done | Whole system wired, big milestone |
+| 💎 | Premium/enterprise value | "Worth $$" |
+| 🎉 | Celebration | Success, done, confetti |
+| 🧠 | Learning/brain mode | Philosophy, patterns, mental models |
+| 🔮 | Vision/future | Roadmap, speculative ideas |
+| 🦄 | Wild/experimental | Alpha, weird, unproven |
+
+---
+
+## 🎯 Template Integration Patterns
+
+### Headers
+```
+⛅️🛣 BLACKROAD OS · CLOUDFLARE MAX BUILDOUT
+💻🔧 LOCAL DEVELOPMENT CONFIGURATION
+🖥💳 WEB APP · STRIPE INTEGRATION
+```
+
+### Step Lists
+```
+1. 🚀 [ACT_DEPLOY] Deploy to production
+2. 🔄 [ACT_SYNC] Sync configurations
+3. 📥 [ACT_IMPORT] Import DNS records
+4. ✅ [STATUS_OK] Verify deployment
+```
+
+### Status Boards
+```
+✅ 🧱 Database initialized
+⏳ 📦 Worker deployment pending
+✅ 🧩 Stripe integration active
+❌ 🛰 Agent service failed
+```
+
+### Documentation Sections
+```
+📚 Documentation
+🗒 Deployment Checklist
+💡 Pro Tips
+🎯 Next Steps
+⚠️ Known Issues
+🔮 Future Roadmap
+```
+
+### Service Status
+```
+⛅️ Cloudflare Workers    ✅ 8 deployed
+🛣 Railway Services      ✅ 20 running
+🖥 Vercel Projects       ⏳ 3 deploying
+🧱 D1 Databases          ✅ 6 initialized
+📦 R2 Buckets            ✅ 12 configured
+```
+
+---
+
+## 🚀 Quick Reference by Use Case
+
+### Deployment Workflow
+```
+⛅️ 🚀 Deploy Cloudflare Worker
+💻 ⌨️ wrangler deploy blackroad-api.js
+⏳ Waiting for propagation...
+✅ Deployed to https://api.blackroad.io
+```
+
+### Error Handling
+```
+🚨 ❌ Deployment failed
+🔍 Investigating root cause
+🕵️ Checking worker logs
+🧯 Rolling back to previous version
+⏮ Restored to v1.2.3
+✅ Service recovered
+```
+
+### Multi-Platform Status
+```
+⛅️ Cloudflare    ✅ All systems operational
+🛣 Railway       ⚠️ 1 service degraded
+🖥 Vercel        ✅ All projects live
+📱 Mobile Apps   ⏳ Build in progress
+🌐 DNS           ✅ All records propagated
+```
+
+### Documentation Structure
+```
+📖 Overview
+📘 API Reference
+📙 How-To Guides
+🗒 Deployment Checklist
+💡 Best Practices
+⚠️ Troubleshooting
+🔮 Roadmap
+```
+
+---
+
+## 🎨 Color-Coded Emoji Groups
+
+### 🟢 Green (Success/Go)
+✅ ☑️ 🚀 💎 🎉
+
+### 🟡 Yellow (Warning/Attention)
+⚠️ ❗️ ⏳ ⌛️ 🔍
+
+### 🔴 Red (Error/Stop)
+❌ 🚫 🚨 🗑
+
+### 🔵 Blue (Info/Context)
+ℹ️ 📚 📖 📘 💡
+
+### 🟣 Purple (Special/Premium)
+✨ 🔮 🦄 💎
+
+---
+
+## 🧠 Machine-Teachable Patterns
+
+### Pattern 1: Status Check
+```
+[CONTEXT] [STATUS] Resource Name
+⛅️ ✅ Cloudflare Workers
+🛣 ⚠️ Railway API Service
+🖥 ❌ Vercel Dashboard
+```
+
+### Pattern 2: Action Sequence
+```
+[STEP] [ACTION] [CONTEXT] Description
+1. 🚀 ⛅️ Deploy Workers
+2. 🔄 🧱 Sync Databases
+3. ✅ 🌐 Verify DNS
+```
+
+### Pattern 3: Resource Inventory
+```
+[RESOURCE] [COUNT] [STATUS] Description
+📦 8 ✅ Workers deployed
+🧱 6 ✅ D1 databases initialized
+🗂 12 ✅ R2 buckets configured
+```
+
+### Pattern 4: Troubleshooting Flow
+```
+🚨 [INCIDENT] Error detected
+🔍 [INVESTIGATE] Checking logs
+🕵️ [ROOT CAUSE] Found issue in config
+🪛 [FIX] Applied patch
+✅ [RESOLVED] Service restored
+```
+
+---
+
+## 💡 Best Practices
+
+1. **Consistency**: Use the same emoji for the same concept across all docs
+2. **Clarity**: Don't overload - 2-3 emojis max per line
+3. **Context First**: Lead with context emoji, then action/status
+4. **Machine-Readable**: Stick to the 127 canonical set
+5. **Visual Hierarchy**: Use emojis to create scannable structure
+
+---
+
+## 🎯 Next Steps
+
+1. **Use in Templates**: All templates now use this emoji system
+2. **Train AI**: Claude/ChatGPT can learn these patterns
+3. **Consistency**: All docs follow same emoji language
+4. **Evolution**: Propose new emojis via PR with justification
+
+---
+
+**Remember**: These 127 emojis are on payroll. Use them consistently. 🧠💿🚀

templates/INDEX.md

@@ -0,0 +1,332 @@
+# BlackRoad OS Templates
+
+**Copy-Paste-Ready Templates for Everything**
+
+This directory contains templates that make development, deployment, and documentation effortless. Every template follows the **copy-paste-and-learn** philosophy: perfect commands that work immediately and teach by doing.
+
+---
+
+## Available Templates
+
+### 1. Terminal Commands Template
+**File**: `TERMINAL-COMMANDS-TEMPLATE.md`
+
+The revolutionary template that changes how we work with terminals. Contains copy-paste-ready command blocks for:
+- Cloudflare deployment
+- Railway deployment
+- Local development
+- SSH operations
+- File management
+- Git workflows
+- Environment setup
+- Testing
+- Docker operations
+
+**Why this matters**: No more nano nightmares, no more mkdir mistakes, no more SSH struggles. Just copy, paste, learn.
+
+**Quick Example**:
+```bash
+# Deploy complete API
+cd cloudflare-workers
+wrangler deploy blackroad-unified-api.js --config wrangler-unified-api.toml
+
+# Initialize databases
+wrangler d1 execute blackroad-users --file=../cloudflare-d1-schemas.sql
+
+# Deploy edge router
+wrangler deploy blackroad-edge-router.js
+```
+
+### 2. README Template
+**File**: `README-TEMPLATE.md`
+
+Standard README structure with copy-paste-ready sections:
+- Quick Start (copy-paste installation)
+- Usage examples (copy-paste commands)
+- API reference (copy-paste curl commands)
+- Deployment (copy-paste deploy blocks)
+- Troubleshooting (copy-paste debug commands)
+
+### 3. Deployment Guide Template
+**File**: `DEPLOYMENT-GUIDE-TEMPLATE.md`
+
+Complete deployment documentation template with:
+- Platform-specific deployment blocks
+- Verification commands
+- Rollback procedures
+- Multi-cloud deployment
+- Post-deployment checks
+
+### 4. Script Template
+**File**: `SCRIPT-TEMPLATE.sh`
+
+Bash script template with:
+- Proper error handling (`set -euo pipefail`)
+- Interactive menu mode
+- Direct command mode
+- Logging
+- Color output
+- Help documentation
+- Copyright headers
+
+### 5. Copy-Paste Commands Library
+**File**: `COPY-PASTE-COMMANDS-LIBRARY.md`
+
+The ultimate command reference - organized by category:
+- Quick Deployments
+- Service Management
+- Git Operations
+- Environment Setup
+- Testing
+- Docker
+- SSH & Remote
+- File Operations
+- Debugging
+- Security & Secrets
+- Emergency Procedures
+
+---
+
+## The Philosophy
+
+### Why Copy-Paste-Ready?
+
+**Before** (traditional docs):
+```
+To deploy, run the wrangler deploy command with your config file.
+```
+User has to:
+1. Remember syntax
+2. Type it correctly
+3. Figure out config file path
+4. Hope it works
+
+**After** (copy-paste-ready):
+```bash
+# Deploy complete API
+cd cloudflare-workers
+wrangler deploy blackroad-unified-api.js --config wrangler-unified-api.toml
+
+# Verify deployment
+wrangler pages deployment list --project-name=blackroad-io
+```
+User:
+1. Copies block
+2. Pastes in terminal
+3. It works perfectly
+4. Comments teach what happened
+
+### Benefits
+
+1. **Zero Cognitive Load** - No thinking required, just copy and paste
+2. **Self-Documenting** - Comments explain the what AND why
+3. **Machine-Teachable** - AI learns from the pattern
+4. **Error-Proof** - No manual typing mistakes
+5. **Context-Preserved** - Full context in every block
+6. **Teaching by Doing** - Learn while executing
+
+---
+
+## How to Use These Templates
+
+### For New Services
+
+1. Copy `README-TEMPLATE.md`
+2. Replace placeholders with your service details
+3. Test all copy-paste command blocks
+4. Ensure every command works perfectly
+5. Commit with the service
+
+### For New Scripts
+
+1. Copy `SCRIPT-TEMPLATE.sh`
+2. Customize functions for your needs
+3. Test interactive menu mode
+4. Test direct command mode
+5. Make executable: `chmod +x script.sh`
+
+### For Documentation
+
+1. Use `TERMINAL-COMMANDS-TEMPLATE.md` patterns
+2. Every command must be copy-paste ready
+3. Include comments explaining each step
+4. Add verification commands
+5. Test before publishing
+
+### For Deployment Guides
+
+1. Copy `DEPLOYMENT-GUIDE-TEMPLATE.md`
+2. Fill in platform-specific sections
+3. Test every deployment block
+4. Include rollback procedures
+5. Add verification steps
+
+---
+
+## Template Standards
+
+Every template must follow these rules:
+
+### 1. Comments Explain Everything
+```bash
+# What this does and why
+command --flag value
+```
+
+### 2. Commands Work Perfectly
+Test every command block before documenting it. No broken examples.
+
+### 3. Full Context Provided
+```bash
+# Navigate to correct directory
+cd ~/blackroad-sandbox/cloudflare-workers
+
+# Deploy with specific config
+wrangler deploy service.js --config wrangler-service.toml
+```
+
+### 4. Verification Included
+```bash
+# Deploy
+railway up --service api-gateway
+
+# Verify deployment worked
+railway status
+curl https://api.blackroad.io/health
+```
+
+### 5. Grouped Logically
+```bash
+# Step 1: Setup
+command1
+
+# Step 2: Execute
+command2
+
+# Step 3: Verify
+command3
+```
+
+### 6. No Manual Edits Required
+Use environment variables or heredocs instead of "edit this file manually":
+
+```bash
+# Good - copy-paste ready
+cat >> .env <<'EOF'
+TOKEN=paste-your-token-here
+EOF
+
+# Bad - requires manual editing
+# Edit .env and add your token
+```
+
+---
+
+## Quick Reference
+
+### Most Common Patterns
+
+**Deploy to Cloudflare**:
+```bash
+cd cloudflare-workers
+wrangler deploy service.js --config wrangler-service.toml
+wrangler pages deployment list --project-name=blackroad-io
+```
+
+**Deploy to Railway**:
+```bash
+export RAILWAY_TOKEN=your-token-here
+railway link project-id
+railway up --service service-name
+railway status
+```
+
+**Start Local Services**:
+```bash
+cd ~/blackroad-sandbox
+./start-all.sh
+./br health
+```
+
+**Run Tests**:
+```bash
+pytest -m unit -v
+pytest -m integration -v
+pytest --cov=. --cov-report=html
+```
+
+---
+
+## Contributing New Templates
+
+When creating a new template:
+
+1. **Follow the philosophy** - Copy-paste-ready with teaching comments
+2. **Test thoroughly** - Every command must work perfectly
+3. **Document clearly** - Explain what and why
+4. **Include verification** - Show how to check it worked
+5. **Add to this index** - Update this file with new template
+
+```bash
+# Create new template
+cat > templates/NEW-TEMPLATE.md <<'EOF'
+# Template content here
+EOF
+
+# Test the template
+# [test steps]
+
+# Update index
+cat >> templates/INDEX.md <<'EOF'
+
+### X. New Template Name
+**File**: `NEW-TEMPLATE.md`
+[Description]
+EOF
+
+# Commit
+git add templates/
+git commit -m "docs: Add new template for [purpose]"
+git push origin main
+```
+
+---
+
+## Examples in the Wild
+
+These templates are used throughout BlackRoad OS:
+
+- `DEPLOY-QUICK-REFERENCE.md` - Uses deployment patterns
+- `TEST_COMMANDS.md` - Uses testing patterns
+- `RAILWAY-WEBHOOK-DEPLOYMENT-GUIDE.md` - Uses deployment template
+- All `blackroad-*.sh` scripts - Use script template
+- All service READMEs - Use README template
+
+---
+
+## Future Templates
+
+Planned templates:
+
+- [ ] API Documentation Template
+- [ ] Integration Guide Template
+- [ ] Database Migration Template
+- [ ] Security Audit Template
+- [ ] Performance Testing Template
+- [ ] Monitoring Setup Template
+
+---
+
+## Copyright
+
+```
+# ============================================================================
+# BlackRoad OS - Proprietary Software
+# Copyright (c) 2025 BlackRoad OS, Inc. / Alexa Louise Amundson
+# All Rights Reserved.
+# ============================================================================
+```
+
+---
+
+**Remember**: Great templates are copy-paste-ready, self-documenting, and teach by doing. If someone has to type something manually, the template isn't good enough yet.

templates/MASTER-TEMPLATE-SYSTEM.md

@@ -0,0 +1,564 @@
+# 🎯 BlackRoad OS Master Template System
+
+**Copy-Paste-Ready Templates for EVERYTHING Across ALL Platforms**
+
+---
+
+## 📋 Template Philosophy
+
+**The Revolutionary Pattern**: Copy-Paste-And-Learn
+
+1. **Zero cognitive load** - No thinking, just paste and GO
+2. **Self-documenting** - Comments explain everything
+3. **Machine-teachable** - AI learns from the patterns
+4. **Error-proof** - No typing mistakes
+5. **Teaching by doing** - Learn while it works
+
+---
+
+## 🗂️ Template Categories
+
+### 1. Core Development Templates
+- `README-TEMPLATE.md` - Perfect README for any repo
+- `DEPLOYMENT-GUIDE-TEMPLATE.md` - Complete deployment docs
+- `SCRIPT-TEMPLATE.sh` - Bash scripts with menu mode
+- `PYTHON-SERVICE-TEMPLATE.py` - Flask/FastAPI service skeleton
+- `DOCKER-TEMPLATE/` - Dockerfile + docker-compose templates
+- `GITHUB-ACTIONS-TEMPLATE/` - CI/CD workflow templates
+
+### 2. Platform Integration Templates
+
+#### Google Drive Templates
+- `google-drive/PROJECT-TEMPLATE/` - Complete project structure
+- `google-drive/DOCS-TEMPLATE.gdoc` - Documentation template
+- `google-drive/SPREADSHEET-TEMPLATE.gsheet` - Data tracking
+- `google-drive/SLIDES-TEMPLATE.gslides` - Presentation deck
+- `google-drive/FORM-TEMPLATE.gform` - User input forms
+
+#### Notion Templates
+- `notion/PROJECT-DASHBOARD-TEMPLATE` - Project management
+- `notion/WIKI-TEMPLATE` - Documentation wiki
+- `notion/ROADMAP-TEMPLATE` - Product roadmap
+- `notion/MEETING-NOTES-TEMPLATE` - Meeting tracker
+- `notion/AGENT-PROFILE-TEMPLATE` - Agent documentation
+
+#### GitHub Templates
+- `github/ISSUE-TEMPLATES/` - Bug, feature, docs templates
+- `github/PR-TEMPLATE.md` - Pull request template
+- `github/REPO-TEMPLATE/` - Complete repo structure
+- `github/WORKFLOWS-TEMPLATE/` - GitHub Actions workflows
+- `github/SECURITY-TEMPLATE/` - Security policy, CODEOWNERS
+
+#### Linear/Jira/Asana Templates
+- `task-management/PROJECT-TEMPLATE` - Project structure
+- `task-management/SPRINT-TEMPLATE` - Sprint planning
+- `task-management/EPIC-TEMPLATE` - Epic/milestone template
+- `task-management/TASK-TEMPLATE` - Task breakdown
+
+#### Airtable Templates
+- `airtable/CRM-TEMPLATE` - Customer relationship management
+- `airtable/CONTACTS-TEMPLATE` - Contact database
+- `airtable/DEALS-TEMPLATE` - Sales pipeline
+- `airtable/PROJECTS-TEMPLATE` - Project tracking
+- `airtable/INVENTORY-TEMPLATE` - Asset/resource tracking
+
+### 3. Domain & Deployment Templates
+
+#### Cloudflare Templates
+- `cloudflare/WORKER-TEMPLATE.js` - Cloudflare Worker skeleton
+- `cloudflare/PAGES-TEMPLATE/` - Static site structure
+- `cloudflare/DNS-TEMPLATE.json` - DNS configuration
+- `cloudflare/ZERO-TRUST-TEMPLATE.json` - Security rules
+- `cloudflare/WRANGLER-TEMPLATE.toml` - Worker config
+
+#### Railway Templates
+- `railway/SERVICE-TEMPLATE.toml` - Railway service config
+- `railway/NIXPACKS-TEMPLATE.toml` - Build configuration
+- `railway/SECRETS-TEMPLATE.env` - Environment variables
+- `railway/HEALTH-CHECK-TEMPLATE.py` - Health endpoint
+
+#### Vercel Templates
+- `vercel/PROJECT-TEMPLATE/` - Next.js/React app
+- `vercel/VERCEL-JSON-TEMPLATE.json` - Deployment config
+- `vercel/SERVERLESS-TEMPLATE/` - Serverless functions
+- `vercel/ENV-TEMPLATE.local` - Environment setup
+
+### 4. Subdomain Templates (5,216 Sites)
+
+#### Per-Domain Subdomain Structure
+```
+subdomain-templates/
+├── LANDING-PAGE-TEMPLATE.html     # Generic landing page
+├── API-SUBDOMAIN-TEMPLATE/        # API service page
+├── DASHBOARD-SUBDOMAIN-TEMPLATE/  # Dashboard app page
+├── DOCS-SUBDOMAIN-TEMPLATE/       # Documentation site
+├── AUTH-SUBDOMAIN-TEMPLATE/       # Auth service page
+├── PAYMENT-SUBDOMAIN-TEMPLATE/    # Payment integration page
+├── AGENT-SUBDOMAIN-TEMPLATE/      # Agent portal page
+└── QUANTUM-SUBDOMAIN-TEMPLATE/    # Quantum computing page
+```
+
+#### Domain-Specific Templates (16 Domains × 364 Subdomains)
+- `blackroad-io/` - Main platform templates
+- `lucidia-earth/` - Lucidia OS templates
+- `blackroadai-com/` - AI-focused templates
+- `blackroadquantum-com/` - Quantum computing templates
+- *(13 more domains...)*
+
+### 5. Integration Templates (15+ Platforms)
+
+```
+integrations/
+├── stripe/
+│   ├── CHECKOUT-TEMPLATE.html
+│   ├── WEBHOOK-HANDLER-TEMPLATE.py
+│   └── PRODUCT-SETUP-TEMPLATE.sh
+├── clerk/
+│   ├── AUTH-TEMPLATE.html
+│   ├── USER-PROFILE-TEMPLATE.tsx
+│   └── MIDDLEWARE-TEMPLATE.ts
+├── resend/
+│   ├── EMAIL-TEMPLATE.html
+│   └── SEND-TEMPLATE.py
+├── asana/
+│   ├── PROJECT-TEMPLATE.json
+│   └── TASK-AUTOMATION-TEMPLATE.py
+├── notion/
+│   ├── DATABASE-TEMPLATE.json
+│   └── PAGE-SYNC-TEMPLATE.py
+└── (13 more platforms...)
+```
+
+---
+
+## 🚀 Quick Start: Using Templates
+
+### Example 1: Create New Repo from Template
+
+```bash
+# Copy the complete repo template
+cp -r templates/github/REPO-TEMPLATE/ ../my-new-repo/
+
+# Customize with your project name
+cd ../my-new-repo
+./setup-from-template.sh "My New Project" "https://github.com/BlackRoad-OS/my-new-repo"
+
+# Result: Complete repo with:
+# - README.md (filled in)
+# - .github/workflows/ (CI/CD ready)
+# - Dockerfile + docker-compose.yml
+# - Railway config
+# - Vercel config
+# - All ready to deploy!
+```
+
+### Example 2: Deploy New Subdomain from Template
+
+```bash
+# Generate subdomain page from template
+python3 generate-subdomain-from-template.py \
+  --domain="blackroad.io" \
+  --subdomain="quantum-api" \
+  --template="API-SUBDOMAIN-TEMPLATE" \
+  --title="Quantum Computing API" \
+  --description="Access quantum algorithms via REST API"
+
+# Deploy to Cloudflare Pages
+cd subdomain-pages-blackroad-io/quantum-api
+wrangler pages deploy . --project-name=quantum-api-blackroad-io
+
+# Result: Live at quantum-api.blackroad.io in < 1 minute!
+```
+
+### Example 3: Create Google Drive Project from Template
+
+```bash
+# Authenticate with Google Drive
+python3 blackroad-google-drive.py auth
+
+# Create project from template
+python3 create-google-drive-project.py \
+  --template="PROJECT-TEMPLATE" \
+  --name="Q4 2025 Product Launch" \
+  --folder="BlackRoad OS/Projects/2025/"
+
+# Result: Complete folder structure with:
+# - Project charter document
+# - Timeline spreadsheet
+# - Team roster
+# - Meeting notes template
+# - Roadmap slides
+```
+
+### Example 4: Set Up Notion Workspace from Template
+
+```bash
+# Import Notion templates
+python3 blackroad-notion-service.py import-templates \
+  --workspace="BlackRoad OS" \
+  --templates="templates/notion/"
+
+# Create new project from template
+curl -X POST http://localhost:9700/api/integrations/notion/projects \
+  -H "Content-Type: application/json" \
+  -d '{
+    "template": "PROJECT-DASHBOARD-TEMPLATE",
+    "name": "Agent Recall System v2",
+    "team": ["Alexa", "Lucidia", "Cecilia"]
+  }'
+
+# Result: Complete Notion workspace with:
+# - Project dashboard
+# - Task database
+# - Documentation pages
+# - Team wiki
+# - Meeting notes section
+```
+
+---
+
+## 📦 Template Distribution
+
+### Auto-Sync to All 43 Repos
+
+```bash
+# Sync all templates to all repos
+./sync-templates-to-all-repos.sh
+
+# What it does:
+# 1. Copies latest templates/ directory to all 43 repos
+# 2. Runs customization scripts per repo
+# 3. Creates PR in each repo with updated templates
+# 4. Auto-merges if CI passes
+```
+
+### Auto-Deploy to All 5,216 Subdomains
+
+```bash
+# Generate all subdomain pages from templates
+python3 generate-all-subdomains-from-templates.py
+
+# Deploy all to Cloudflare Pages
+./deploy-all-subdomains-pages.sh
+
+# What it does:
+# 1. Generates 364 subdomain pages per domain (16 domains)
+# 2. Customizes each page with domain-specific branding
+# 3. Deploys to Cloudflare Pages
+# 4. Updates DNS routing
+# 5. Verifies all 5,216 sites are live
+```
+
+### Auto-Import to All Integration Platforms
+
+```bash
+# Import templates to all platforms
+./import-templates-to-all-platforms.sh
+
+# What it does:
+# - Google Drive: Creates template library
+# - Notion: Imports all page templates
+# - GitHub: Creates template repositories
+# - Linear: Imports project/task templates
+# - Jira: Imports issue templates
+# - Asana: Imports project templates
+# - Airtable: Creates base templates
+# - (15+ total platforms)
+```
+
+---
+
+## 🎨 Template Customization
+
+### Variables System
+
+All templates support variable substitution:
+
+```bash
+# Variables defined in template-vars.yaml
+PROJECT_NAME: "My Awesome Project"
+DOMAIN: "blackroad.io"
+SUBDOMAIN: "api"
+REPO_URL: "https://github.com/BlackRoad-OS/my-awesome-project"
+AUTHOR: "Alexa Louise Amundson"
+YEAR: "2025"
+STRIPE_ENABLED: true
+CLERK_ENABLED: true
+
+# Usage in templates:
+# README-TEMPLATE.md contains: {{PROJECT_NAME}}
+# After processing: My Awesome Project
+```
+
+### Conditional Sections
+
+```html
+<!-- In HTML templates -->
+{{#if STRIPE_ENABLED}}
+<script src="https://js.stripe.com/v3/"></script>
+{{/if}}
+
+{{#if CLERK_ENABLED}}
+<script src="https://clerk.dev/v3/"></script>
+{{/if}}
+```
+
+### Dynamic Content
+
+```python
+# In Python templates
+# {{GENERATED_ROUTES}}
+# Auto-generates Flask routes based on config
+
+# {{GENERATED_MODELS}}
+# Auto-generates SQLAlchemy models from schema
+
+# {{GENERATED_TESTS}}
+# Auto-generates pytest tests from endpoints
+```
+
+---
+
+## 🔄 Template Update Workflow
+
+### When Templates Change
+
+```bash
+# 1. Update master templates in blackroad-sandbox/templates/
+vim templates/README-TEMPLATE.md
+
+# 2. Run template sync
+./sync-templates-to-all-repos.sh
+
+# 3. Verify changes
+./verify-template-sync.sh
+
+# 4. Deploy updated subdomains
+./deploy-updated-subdomains.sh
+
+# Result: All 43 repos + 5,216 sites updated automatically!
+```
+
+---
+
+## 📊 Template Analytics
+
+### Track Template Usage
+
+```bash
+# See which templates are most used
+./template-analytics.sh
+
+# Output:
+Template                          Usage Count  Last Used
+--------------------------------  -----------  --------------------
+README-TEMPLATE.md                43 repos     2025-12-12 10:30:00
+API-SUBDOMAIN-TEMPLATE            872 sites    2025-12-12 09:15:00
+PYTHON-SERVICE-TEMPLATE.py        28 repos     2025-12-11 14:22:00
+NOTION/PROJECT-DASHBOARD          156 projects 2025-12-10 16:45:00
+```
+
+---
+
+## 🎯 Master Template Catalog
+
+### Complete List (200+ Templates)
+
+1. **Development** (25 templates)
+   - README, Dockerfile, docker-compose, package.json, requirements.txt, etc.
+
+2. **CI/CD** (15 templates)
+   - GitHub Actions workflows, Railway configs, Vercel configs, etc.
+
+3. **Documentation** (20 templates)
+   - User guides, API docs, architecture diagrams, etc.
+
+4. **Google Drive** (30 templates)
+   - Docs, Sheets, Slides, Forms across all project types
+
+5. **Notion** (25 templates)
+   - Dashboards, wikis, databases, pages, etc.
+
+6. **GitHub** (20 templates)
+   - Issues, PRs, repos, workflows, security, etc.
+
+7. **Task Management** (15 templates)
+   - Linear, Jira, Asana project/task templates
+
+8. **Airtable** (10 templates)
+   - CRM, contacts, deals, projects, inventory
+
+9. **Cloudflare** (20 templates)
+   - Workers, Pages, DNS, Zero Trust, etc.
+
+10. **Railway** (10 templates)
+    - Service configs, health checks, secrets, etc.
+
+11. **Vercel** (10 templates)
+    - Next.js apps, serverless functions, configs
+
+12. **Subdomains** (5,216 variations)
+    - 364 templates × 16 domains = complete coverage
+
+13. **Integrations** (15 templates)
+    - Stripe, Clerk, Resend, all 15 platforms
+
+---
+
+## 🚀 Template Deployment Commands
+
+### Deploy Everything
+
+```bash
+# ONE COMMAND TO RULE THEM ALL
+./deploy-all-templates-everywhere.sh
+
+# What it does:
+# ✅ Syncs templates to all 43 GitHub repos
+# ✅ Imports templates to Google Drive
+# ✅ Imports templates to Notion
+# ✅ Imports templates to Linear/Jira/Asana
+# ✅ Imports templates to Airtable
+# ✅ Generates all 5,216 subdomain pages
+# ✅ Deploys all subdomains to Cloudflare Pages
+# ✅ Updates all Railway services
+# ✅ Updates all Vercel projects
+# ✅ Verifies all deployments
+# ✅ Generates usage report
+
+# Time: ~15 minutes
+# Result: EVERYTHING updated across ALL platforms!
+```
+
+---
+
+## 📚 Template Documentation
+
+Each template includes:
+
+1. **Header Comment**
+   ```
+   # ============================================================================
+   # Template: README-TEMPLATE.md
+   # Purpose: Perfect README for any BlackRoad OS repository
+   # Variables: PROJECT_NAME, DESCRIPTION, REPO_URL, AUTHOR
+   # Last Updated: 2025-12-12
+   # ============================================================================
+   ```
+
+2. **Usage Instructions**
+   - How to use the template
+   - Required variables
+   - Optional customizations
+   - Example output
+
+3. **Customization Guide**
+   - Which sections to customize
+   - Which to keep as-is
+   - Best practices
+
+4. **Examples**
+   - Real-world examples from existing repos
+   - Before/after comparisons
+
+---
+
+## 🎉 Template Benefits
+
+### Developer Experience
+- **10x faster** project setup
+- **Zero boilerplate** writing
+- **Consistent quality** across all projects
+- **Always up-to-date** with latest practices
+
+### Team Collaboration
+- **Shared knowledge** embedded in templates
+- **Onboarding time** cut from days to minutes
+- **Code review** faster with consistent structure
+- **Documentation** always complete
+
+### Deployment Speed
+- **New subdomain**: < 1 minute
+- **New repo**: < 5 minutes
+- **New integration**: < 2 minutes
+- **Complete project**: < 15 minutes
+
+### Maintenance
+- **One update** propagates everywhere
+- **No drift** between projects
+- **Automated sync** keeps everything current
+- **Version control** for all templates
+
+---
+
+## 🔥 Advanced Template Features
+
+### Template Inheritance
+
+```yaml
+# base-service-template.yaml
+base: PYTHON-SERVICE-TEMPLATE
+extends:
+  - auth-mixin
+  - database-mixin
+  - stripe-mixin
+  - clerk-mixin
+```
+
+### Template Composition
+
+```bash
+# Combine multiple templates
+./compose-template.sh \
+  --base="PYTHON-SERVICE-TEMPLATE" \
+  --add="AUTH-MIXIN" \
+  --add="STRIPE-MIXIN" \
+  --add="WEBSOCKET-MIXIN" \
+  --output="my-custom-service.py"
+```
+
+### Template Generation
+
+```bash
+# Generate new template from existing code
+./generate-template.sh \
+  --from="blackroad-agent-orchestrator.py" \
+  --name="AGENT-SERVICE-TEMPLATE" \
+  --extract-patterns
+```
+
+---
+
+## 📖 Template Index
+
+See `TEMPLATE-INDEX.md` for complete catalog of all 200+ templates with:
+- Description
+- Usage examples
+- Variables
+- Customization options
+- Related templates
+- Example output
+
+---
+
+## 🎯 Next Steps
+
+1. **Browse Templates**: `ls -R templates/`
+2. **Use a Template**: Copy & customize
+3. **Create New Template**: Follow the template-template 😉
+4. **Share Template**: PR to blackroad-sandbox/templates/
+5. **Deploy Templates**: Run sync scripts
+
+**The goal**: Never write boilerplate again. Ever. 🚀
+
+---
+
+## 📞 Template Support
+
+- **Issues**: Use GitHub template issue template 😄
+- **Questions**: blackroad.systems@gmail.com
+- **Contributions**: PR welcome for new templates!
+
+---
+
+**Remember**: A perfect template is one you never have to think about. It just works. ✨

templates/README-TEMPLATE.md

@@ -0,0 +1,389 @@
+# [Service/Feature Name]
+
+**One-line description of what this does**
+
+## Quick Start (Copy-Paste Ready)
+
+```bash
+# Clone and setup
+cd ~/blackroad-sandbox
+git pull origin main
+
+# Install dependencies
+pip3 install -r requirements.txt
+
+# Start service
+PORT=8000 python3 blackroad-service.py
+
+# Verify it's running
+curl http://localhost:8000/health
+```
+
+---
+
+## What This Does
+
+[2-3 sentence explanation of purpose and value]
+
+---
+
+## Installation
+
+### Local Development
+
+```bash
+# Navigate to project
+cd ~/blackroad-sandbox
+
+# Install Python dependencies
+pip3 install -r requirements.txt
+
+# Copy environment template
+cp .env.example .env
+
+# Add your secrets
+cat >> .env <<'EOF'
+SERVICE_TOKEN=your-token-here
+API_KEY=your-key-here
+EOF
+
+# Verify installation
+python3 -c "import flask; print('✅ Dependencies installed')"
+```
+
+### Docker
+
+```bash
+# Build image
+docker build -t blackroad-service .
+
+# Run container
+docker run -p 8000:8000 --env-file .env blackroad-service
+
+# Verify
+curl http://localhost:8000/health
+```
+
+---
+
+## Usage
+
+### Start the Service
+
+```bash
+# Development mode
+PORT=8000 python3 blackroad-service.py
+
+# Production mode
+FLASK_ENV=production PORT=8000 python3 blackroad-service.py
+
+# With Docker Compose
+docker-compose up -d service-name
+```
+
+### Test the Service
+
+```bash
+# Health check
+curl http://localhost:8000/health
+
+# Test specific endpoint
+curl http://localhost:8000/api/resource -X POST -H "Content-Type: application/json" -d '{"key":"value"}'
+
+# Run automated tests
+pytest tests/test_service.py -v
+```
+
+### Deploy to Production
+
+```bash
+# Deploy to Railway
+cd ~/blackroad-sandbox
+railway up --service service-name
+
+# Deploy to Cloudflare
+cd cloudflare-workers
+wrangler deploy service.js --config wrangler-service.toml
+
+# Verify deployment
+curl https://service.blackroad.io/health
+```
+
+---
+
+## API Reference
+
+### Endpoints
+
+#### `GET /health`
+
+Health check endpoint.
+
+```bash
+# Example
+curl http://localhost:8000/health
+```
+
+**Response:**
+```json
+{
+  "ok": true,
+  "service": "service-name",
+  "version": "1.0.0"
+}
+```
+
+#### `POST /api/resource`
+
+Create a new resource.
+
+```bash
+# Example
+curl http://localhost:8000/api/resource \
+  -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"name":"example","value":42}'
+```
+
+**Response:**
+```json
+{
+  "ok": true,
+  "resource_id": "abc123"
+}
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Required
+SERVICE_TOKEN=your-service-token
+API_KEY=your-api-key
+
+# Optional
+PORT=8000
+LOG_LEVEL=info
+ENVIRONMENT=production
+```
+
+### Config Files
+
+- `.env` - Environment variables
+- `config.yaml` - Service configuration
+- `railway.toml` - Railway deployment config
+
+---
+
+## Development
+
+### Running Tests
+
+```bash
+# All tests
+pytest -v
+
+# Unit tests only
+pytest -m unit -v
+
+# Integration tests
+pytest -m integration -v
+
+# With coverage
+pytest --cov=. --cov-report=html
+open coverage_html/index.html
+```
+
+### Local Development Workflow
+
+```bash
+# 1. Create feature branch
+git checkout -b feature/new-feature
+
+# 2. Make changes
+# Edit files...
+
+# 3. Test locally
+pytest -v
+python3 blackroad-service.py
+
+# 4. Commit
+git add .
+git commit -m "feat: Add new feature"
+
+# 5. Push
+git push -u origin feature/new-feature
+
+# 6. Create PR
+gh pr create --title "Add new feature" --body "Description"
+```
+
+---
+
+## Deployment
+
+### Railway
+
+```bash
+# Link to project
+railway link 0c7bcf07-307b-4db6-9c94-22a456500d68
+
+# Deploy
+railway up --service service-name
+
+# Check status
+railway status
+
+# View logs
+railway logs --tail 100
+```
+
+### Cloudflare Pages/Workers
+
+```bash
+# Deploy worker
+cd cloudflare-workers
+wrangler deploy service.js --config wrangler-service.toml
+
+# Deploy page
+cd domains/domain-name
+wrangler pages deploy . --project-name=domain-name
+
+# Check deployment
+wrangler pages deployment list --project-name=domain-name
+```
+
+### Vercel
+
+```bash
+# Deploy
+cd vercel-projects/project-name
+vercel --prod
+
+# Check deployment
+vercel ls
+```
+
+---
+
+## Troubleshooting
+
+### Service Won't Start
+
+```bash
+# Check if port is in use
+lsof -i :8000
+
+# Kill existing process
+kill -9 $(lsof -t -i:8000)
+
+# Restart service
+PORT=8000 python3 blackroad-service.py
+```
+
+### Import Errors
+
+```bash
+# Reinstall dependencies
+pip3 install -r requirements.txt --force-reinstall
+
+# Verify Python version
+python3 --version  # Should be 3.11+
+
+# Check imports
+python3 -c "import flask; print('✅ Flask OK')"
+```
+
+### Environment Variables Not Loaded
+
+```bash
+# Check .env exists
+ls -la .env
+
+# Source manually
+source .env
+
+# Verify variables
+echo $SERVICE_TOKEN
+```
+
+### Deployment Failed
+
+```bash
+# Railway
+railway logs --tail 100
+railway status
+railway variables  # Check secrets are set
+
+# Cloudflare
+wrangler tail  # View live logs
+wrangler pages deployment list --project-name=PROJECT_NAME
+```
+
+---
+
+## Architecture
+
+[Diagram or description of how this service fits into the larger system]
+
+---
+
+## Contributing
+
+```bash
+# 1. Fork/clone
+git clone https://github.com/BlackRoad-OS/repo-name.git
+
+# 2. Create branch
+git checkout -b feature/your-feature
+
+# 3. Make changes and test
+pytest -v
+
+# 4. Commit with conventional commits
+git commit -m "feat: Add your feature"
+
+# 5. Push
+git push -u origin feature/your-feature
+
+# 6. Create PR
+gh pr create
+```
+
+---
+
+## License
+
+```
+# ============================================================================
+# BlackRoad OS - Proprietary Software
+# Copyright (c) 2025 BlackRoad OS, Inc. / Alexa Louise Amundson
+# All Rights Reserved.
+# ============================================================================
+```
+
+---
+
+## Support
+
+- **Email**: blackroad.systems@gmail.com
+- **Docs**: [Link to docs]
+- **Issues**: [Link to GitHub issues]
+
+---
+
+## Related Services
+
+- [Service 1](link) - Description
+- [Service 2](link) - Description
+- [Service 3](link) - Description
+
+---
+
+**Quick Links**:
+- [API Documentation](link)
+- [Deployment Guide](link)
+- [Troubleshooting](link)

templates/SCRIPT-TEMPLATE.sh

@@ -0,0 +1,318 @@
+#!/usr/bin/env bash
+# ============================================================================
+# BlackRoad OS - Proprietary Software
+# Copyright (c) 2025 BlackRoad OS, Inc. / Alexa Louise Amundson
+# All Rights Reserved.
+# ============================================================================
+#
+# [Script Name]
+# [One-line description of what this script does]
+#
+# Usage:
+#   ./script-name.sh                    # Interactive menu mode
+#   ./script-name.sh [command] [args]   # Direct command mode
+#   ./script-name.sh --help             # Show help
+#
+# Examples:
+#   ./script-name.sh deploy             # Deploy service
+#   ./script-name.sh status             # Check status
+#   ./script-name.sh logs               # View logs
+
+set -euo pipefail
+
+# =============================================================================
+# Configuration
+# =============================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${SCRIPT_DIR}"
+LOG_FILE="${PROJECT_ROOT}/script-name.log"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+log() {
+    echo -e "${GREEN}✓${NC} $1"
+    echo "[$(date +'%Y-%m-%d %H:%M:%S')] $1" >> "$LOG_FILE"
+}
+
+error() {
+    echo -e "${RED}✗${NC} $1" >&2
+    echo "[$(date +'%Y-%m-%d %H:%M:%S')] ERROR: $1" >> "$LOG_FILE"
+}
+
+warn() {
+    echo -e "${YELLOW}⚠${NC} $1"
+    echo "[$(date +'%Y-%m-%d %H:%M:%S')] WARN: $1" >> "$LOG_FILE"
+}
+
+info() {
+    echo -e "${BLUE}ℹ${NC} $1"
+}
+
+# Check if command exists
+command_exists() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+# Check prerequisites
+check_prerequisites() {
+    log "Checking prerequisites..."
+
+    local missing=0
+
+    if ! command_exists "python3"; then
+        error "python3 not found"
+        missing=1
+    fi
+
+    if ! command_exists "git"; then
+        error "git not found"
+        missing=1
+    fi
+
+    if [ $missing -eq 1 ]; then
+        error "Missing required dependencies"
+        exit 1
+    fi
+
+    log "All prerequisites met"
+}
+
+# =============================================================================
+# Command Functions
+# =============================================================================
+
+cmd_deploy() {
+    log "Starting deployment..."
+
+    # Example deployment steps
+    cd "$PROJECT_ROOT"
+
+    # Pull latest code
+    log "Pulling latest code..."
+    git pull origin main
+
+    # Install dependencies
+    log "Installing dependencies..."
+    pip3 install -r requirements.txt
+
+    # Deploy to platform
+    log "Deploying to platform..."
+    railway up --service service-name
+
+    # Verify deployment
+    log "Verifying deployment..."
+    sleep 5
+    railway status
+
+    log "Deployment complete!"
+}
+
+cmd_status() {
+    log "Checking status..."
+
+    # Check local services
+    info "Local services:"
+    pgrep -f "python3.*blackroad" | while read pid; do
+        echo "  PID $pid: $(ps -p $pid -o command=)"
+    done
+
+    # Check Railway
+    if command_exists "railway"; then
+        info "Railway status:"
+        railway status
+    fi
+
+    # Check health endpoints
+    info "Health checks:"
+    curl -sf http://localhost:8000/health && echo "  ✅ Local API" || echo "  ❌ Local API"
+    curl -sf https://api.blackroad.io/health && echo "  ✅ Production API" || echo "  ❌ Production API"
+}
+
+cmd_logs() {
+    log "Viewing logs..."
+
+    # Show local log
+    if [ -f "$LOG_FILE" ]; then
+        tail -n 50 "$LOG_FILE"
+    fi
+
+    # Show Railway logs if available
+    if command_exists "railway"; then
+        info "Railway logs:"
+        railway logs --tail 50
+    fi
+}
+
+cmd_start() {
+    log "Starting services..."
+
+    cd "$PROJECT_ROOT"
+
+    # Start service in background
+    PORT=8000 python3 blackroad-service.py &
+
+    # Wait for startup
+    sleep 2
+
+    # Verify
+    curl -sf http://localhost:8000/health && log "Service started successfully" || error "Service failed to start"
+}
+
+cmd_stop() {
+    log "Stopping services..."
+
+    # Kill all matching processes
+    pkill -f "python3.*blackroad-service" || warn "No processes found"
+
+    log "Services stopped"
+}
+
+cmd_test() {
+    log "Running tests..."
+
+    cd "$PROJECT_ROOT"
+
+    # Run unit tests
+    pytest -m unit -v
+
+    # Run integration tests
+    pytest -m integration -v
+
+    log "Tests complete"
+}
+
+cmd_clean() {
+    log "Cleaning up..."
+
+    cd "$PROJECT_ROOT"
+
+    # Remove cache files
+    find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+    find . -type f -name "*.pyc" -delete 2>/dev/null || true
+
+    # Remove log files
+    rm -f "$LOG_FILE"
+
+    log "Cleanup complete"
+}
+
+# =============================================================================
+# Menu Functions
+# =============================================================================
+
+show_menu() {
+    echo ""
+    echo "╔════════════════════════════════════════╗"
+    echo "║     [Service Name] Management          ║"
+    echo "╚════════════════════════════════════════╝"
+    echo ""
+    echo "Commands:"
+    echo "  1) deploy   - Deploy to production"
+    echo "  2) status   - Check service status"
+    echo "  3) logs     - View logs"
+    echo "  4) start    - Start local service"
+    echo "  5) stop     - Stop local service"
+    echo "  6) test     - Run tests"
+    echo "  7) clean    - Clean up files"
+    echo "  q) quit     - Exit"
+    echo ""
+}
+
+interactive_menu() {
+    while true; do
+        show_menu
+        read -rp "Choose command: " choice
+
+        case $choice in
+            1|deploy)   cmd_deploy ;;
+            2|status)   cmd_status ;;
+            3|logs)     cmd_logs ;;
+            4|start)    cmd_start ;;
+            5|stop)     cmd_stop ;;
+            6|test)     cmd_test ;;
+            7|clean)    cmd_clean ;;
+            q|quit)     log "Goodbye!"; exit 0 ;;
+            *)          error "Invalid choice: $choice" ;;
+        esac
+
+        echo ""
+        read -rp "Press Enter to continue..."
+    done
+}
+
+# =============================================================================
+# Help Function
+# =============================================================================
+
+show_help() {
+    cat <<EOF
+[Script Name] - [Description]
+
+Usage:
+  $0 [command] [args]
+
+Commands:
+  deploy              Deploy to production
+  status              Check service status
+  logs                View logs
+  start               Start local service
+  stop                Stop local service
+  test                Run tests
+  clean               Clean up files
+  menu                Show interactive menu (default)
+  help                Show this help message
+
+Examples:
+  $0                  # Interactive menu mode
+  $0 deploy           # Deploy to production
+  $0 status           # Check status
+  $0 logs             # View logs
+
+Environment Variables:
+  RAILWAY_TOKEN       Railway API token (required for deploy)
+  PORT               Service port (default: 8000)
+
+For more information, see README.md
+EOF
+}
+
+# =============================================================================
+# Main Script Logic
+# =============================================================================
+
+main() {
+    # Check prerequisites
+    check_prerequisites
+
+    # Handle command
+    case "${1:-menu}" in
+        deploy)         cmd_deploy ;;
+        status)         cmd_status ;;
+        logs)           cmd_logs ;;
+        start)          cmd_start ;;
+        stop)           cmd_stop ;;
+        test)           cmd_test ;;
+        clean)          cmd_clean ;;
+        menu|"")        interactive_menu ;;
+        -h|--help|help) show_help ;;
+        *)
+            error "Unknown command: $1"
+            echo ""
+            show_help
+            exit 1
+            ;;
+    esac
+}
+
+# Run main function
+main "$@"

templates/TEMPLATE-001-INFRA-RUNBOOK.md

@@ -0,0 +1,79 @@
+╭━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╮
+│ ⛅️🛣 BLACKROAD OS · <PROJECT / RUNBOOK TITLE>              │
+╰━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╯
+
+<CTX_EMOJI> <TOOL_NAME> <VERSION>  ·  env: <ENV>  ·  region: <REGION>
+────────────────────────────────────────────────────────────
+
+╭────────── WORKER / SERVICE BINDINGS 📦 ────────────────────╮
+│ Binding          │ Resource                               │
+├──────────────────┼────────────────────────────────────────┤
+│ <binding-name>   │ <resource-type>                        │
+│ <binding-name>   │ <resource-type>                        │
+│ <binding-name>   │ <resource-type>                        │
+╰────────────────────────────────────────────────────────────╯
+
+
+╭────────── INFRASTRUCTURE STATUS 📡 ───────────────────────╮
+│ ✅ <RES_LABEL_1>   <value/limits/notes>                   │
+│ ✅ <RES_LABEL_2>   <value/limits/notes>                   │
+│ ⏳ <RES_LABEL_3>   <pending condition>                    │
+│ ⚠️ <RES_LABEL_4>   <warning condition>                    │
+╰────────────────────────────────────────────────────────────╯
+
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🚀 EXECUTE THE <N> STEPS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[1] <STEP_TITLE_1>  <(optional short description)>
+    <primary command(s)>
+    <secondary command(s)>
+    │
+    ▼
+[2] <STEP_TITLE_2>
+    <commands…>
+    │
+    ▼
+[3] <STEP_TITLE_3>
+    <commands…>
+    │
+    ▼
+[<N>] <FINAL_STEP_TITLE>
+     <commands…>
+
+
+╭────────── VALUE DELIVERED 💎 ─────────────────────────────╮
+│ <RES_SUMMARY_1>   →  ~<$ESTIMATED_VALUE_1>/month          │
+│ <RES_SUMMARY_2>   →  ~<$ESTIMATED_VALUE_2>/month          │
+│ <RES_SUMMARY_3>   →  ~<$ESTIMATED_VALUE_3>/month          │
+├───────────────────────────────────────────────────────────┤
+│ TOTAL               →  ~<$TOTAL_ESTIMATED_VALUE>/month    │
+│ YOU PAY                $<ACTUAL_COST>/month               │
+╰────────────────────────────────────────────────────────────╯
+
+
+📚 Documentation
+- 📘 API / Worker: <FILE_OR_URL_1>
+- 📙 Deployment Guide: <FILE_OR_URL_2>
+- 📕 Policies / Limits: <FILE_OR_URL_3>
+
+🗒 Checklist
+- ☐ <Prereq 1>
+- ☐ <Prereq 2>
+- ☐ <Verify step 1>
+- ☐ <Verify step 2>
+
+🎯 Next Steps
+1. <Immediate action after running this>
+2. <Follow-up configuration / wiring>
+3. <Optional optimization / observability>
+
+💡 Tips
+- <short pro tip #1>
+- <short pro tip #2>
+
+╭━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╮
+│ 🔥 <EPIC_DONE_LINE_SUMMARY>                               │
+│    (e.g. "ALL RESOURCES READY · JUST RUN THE N STEPS 💎") │
+╰━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╯

templates/TEMPLATE-002-ARCHITECTURE-OVERVIEW.md

@@ -0,0 +1,165 @@
+╭━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╮
+│ 🛣 <CTX_EMOJI> BLACKROAD OS · <SYSTEM / ARCH NAME>         │
+╰━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╯
+
+🧭 Overview
+────────────────────────────────────────────────────────────
+<2–5 lines: What this system is, who it serves, and why it exists.>
+Example:
+- Serves: <who> (👤 / 👥)
+- Core job: <what it does>
+- Scope: <boundaries / what it is NOT>
+
+
+🏗 High-Level System Diagram
+────────────────────────────────────────────────────────────
+
+                  👤 Users / Clients
+                       │  (https)
+                       ▼
+╭────────────────────────────────────────────────────────────╮
+│  ⛅️ Edge / Gateway (Cloudflare Workers / Router)           │
+│  - Routing, auth checks, rate limiting                     │
+╰───────────────┬─────────────────────────────┬──────────────╯
+                │                             │
+                ▼                             ▼
+        🛰 Service A                     🛰 Service B
+    (API / Unified API)             (Web / Pages / UI)
+                │                             │
+                └──────────────┬──────────────┘
+                               ▼
+                         🧱 Databases
+                         📨 Queues
+                         🗂 Storage (R2 / KV)
+
+<Adjust the boxes/lines to match your exact topology.>
+
+
+📦 Component Breakdown
+────────────────────────────────────────────────────────────
+
+⛅️ Edge / Gateway
+- Type: <Worker / Router / CDN>
+- Responsibilities:
+  - <bullet 1>
+  - <bullet 2>
+- Key resources:
+  - 📦 <artifact name>
+  - 🔑 <secret / binding>
+  - 🌐 <domains / routes>
+
+🛰 Core Services
+- Service A (🛰 <name>)
+  - Purpose: <short description>
+  - Interfaces: <HTTP/WS/queues/etc.>
+  - Talks to: <DBs, queues, other services>
+- Service B (🛰 <name>)
+  - Purpose: ...
+  - Interfaces: ...
+
+🧱 Data Layer
+- Databases (🧱)
+  - <DB name> – <what it stores>, <scale expectations>
+- Queues (📨)
+  - <Queue name> – <what flows through it>
+- Storage (🗂 / R2 / KV)
+  - <Bucket / KV namespace> – <what lives here>
+
+🧩 External Integrations
+- Stripe (💳)
+  - Used for: <billing/payments>
+- Auth provider (🔐)
+  - Used for: <authN/authZ>
+- Other (🧩)
+  - <Integration> – <role>
+
+
+👉 Request / Data Flows
+────────────────────────────────────────────────────────────
+
+Flow 1 – User Request
+1. 👤 User → 🌐 <domain> (e.g. https://...)
+2. 🌐 DNS → ⛅️ Edge (Cloudflare)
+3. ⛅️ Edge → 🛰 Service A (unified API)
+4. 🛰 Service A → 🧱 DB / 📨 Queue / 🗂 Storage
+5. Response travels back ⛅️ → 👤
+
+Flow 2 – Background Processing
+1. 🧱 DB / 📨 Queue event occurs
+2. 🛰 Worker / cron picks it up
+3. 🧠 Optional 🤖 AI/LLM processing
+4. Results written to 🧱 / 🗂 / 📊
+
+Flow 3 – Admin / Dashboards
+1. 👩‍💻 Operator → 🖥 Dashboard
+2. Dashboard calls ⛅️ Edge → 🛰 Admin API
+3. Observability from 📊 Metrics / 🧾 Logs
+
+
+🔐 Reliability, Security & Limits
+────────────────────────────────────────────────────────────
+
+Reliability
+- Target: <e.g. 99.9% uptime>
+- Single points of failure: <where and how mitigated>
+- 🧯 Fallback / degradation strategy: <how it fails gracefully>
+
+Security
+- Auth (🔐): <how users/clients authenticate>
+- Secrets (🔑): <where secrets are stored>
+- Data protection: <encryption at rest / in transit>
+
+Limits & Quotas
+- Request limits: <Cloudflare free tier, etc.>
+- Storage limits: <R2 / KV / D1 limits>
+- Scaling behavior:
+  - ⛅️ Edge: <auto / manual>
+  - 🛰 Services: <horizontal/vertical>
+
+(Reference to specific Cloudflare docs / constraints if relevant.)
+
+
+🧰 Operations: Deploy, Observe, Debug
+────────────────────────────────────────────────────────────
+
+Deploy (🚀)
+- Primary script / command:
+  - `./<deploy-script>.sh`
+- Manual steps (if any):
+  - ☐ <step 1>
+  - ☐ <step 2>
+
+Observe (📊 / 🧾)
+- Metrics (📊):
+  - <link / command> – e.g. dashboard URL
+- Logs (🧾):
+  - `wrangler tail <worker-name>`
+  - `<other log sources>`
+
+Debug (🔍 / 🕵️)
+- Common failure modes:
+  - <symptom> → <likely cause> → <fix>
+- Incident severity mapping (🚨):
+  - <what counts as Sev1 / Sev2, etc.>
+
+
+📚 Documentation & References
+────────────────────────────────────────────────────────────
+
+📚 System Docs
+- Overview: <FILE_OR_URL>
+- API Reference: <FILE_OR_URL>
+- Runbooks: <FILE_OR_URL>
+
+🗒 Checklists
+- Deploy checklist: <FILE_OR_URL>
+- Onboarding checklist: <FILE_OR_URL>
+
+🎯 Next Steps
+- <Step 1: what reader should do first>
+- <Step 2: where to go deeper>
+- <Step 3: optional advanced topic>
+
+💡 Tips
+- <Tip 1: e.g. "If X happens, check Y first">
+- <Tip 2: e.g. "Prefer Z pattern when adding new services">

templates/TEMPLATE-003-DOMAIN-DNS-ROUTING.md

@@ -0,0 +1,77 @@
+╭━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╮
+│ 🌐🛣 DOMAIN CARD · <DOMAIN_NAME>                           │
+╰━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╯
+
+🧭 Overview
+────────────────────────────────────────────────────────────
+- Domain: `<DOMAIN_NAME>`
+- Purpose: <what this domain is for>
+- Owners (👥): <team / person>
+- Environment(s): <env_prod / env_staging / etc.>
+
+
+📡 Routing & Services
+────────────────────────────────────────────────────────────
+
+Primary Entry
+- 🌐 Hostname: `<host or wildcard>` (e.g. `*.blackroad.io`)
+- ⛅️ Edge: `<Cloudflare zone / worker>` (e.g. `blackroad-edge-router`)
+
+Services Behind This Domain
+- 🛰 <service_name_1> – <description>
+  - Path(s): `/api/...`, `/auth/...`
+  - Env: <env>
+- 🛰 <service_name_2> – <description>
+  - Path(s): `/`, `/dashboard`
+
+Traffic Rules (🔀)
+- Rule 1: `<condition>` → `<target>`
+- Rule 2: `<condition>` → `<target>`
+
+
+🧱 DNS Records
+────────────────────────────────────────────────────────────
+
+Code-ish view:
+
+TYPE   NAME                 VALUE / TARGET                  TTL   NOTES
+A      <name>               <ip or proxy>                   auto  <note>
+AAAA   <name>               <ipv6 or proxy>                 auto  <note>
+CNAME  <name>               <target.domain.com>             auto  <note>
+TXT    <name>               <value>                         auto  <SPF/verification/etc.>
+
+Human view:
+- 🌐 Root (<DOMAIN_NAME>) → <target> (e.g. Cloudflare worker/pages)
+- 🌐 *.subdomain → <target>
+- 🔏 TLS: <Full/Strict/Flexible>
+
+🧪 Verification & Health
+────────────────────────────────────────────────────────────
+
+Status
+- DNS Resolution (🌐): ✅ / ⚠️ / ❌
+- HTTPS (🔐): ✅ / ⚠️ / ❌
+- Latency (⏱): ~<ms> global
+
+How to Verify (🔍)
+- DNS: dig <domain> / nslookup <domain>
+- HTTPS: visit https://<domain> and check cert
+- Worker: wrangler tail <worker> or health endpoint
+
+Common Issues (🚨)
+- Symptom: <issue> → Likely: <cause> → Fix: <action>
+
+📚 Links
+────────────────────────────────────────────────────────────
+- Cloudflare zone: <URL>
+- Worker / Pages config: <FILE>
+- Related project: projects/<proj_name>/project.md
+- Runbook: projects/<proj_name>/runbook.md
+
+🎯 Next Steps
+- <Step 1: e.g. "Enable HTTPS on staging subdomain">
+- <Step 2: e.g. "Migrate root domain to new router">
+
+💡 Tips
+- <keep this domain's use narrow / don't mix X with Y>
+- <DNS changes can take up to N minutes to propagate>

templates/TEMPLATE-INDEX.md

@@ -0,0 +1,431 @@
+# 📚 BlackRoad OS Template Index
+
+**Complete Catalog of 200+ Copy-Paste-Ready Templates**
+
+---
+
+## 🎯 Template Philosophy
+
+**The Revolutionary Pattern**: Copy-Paste-And-Learn
+
+Every template follows the 127-emoji language system (see `EMOJI-REFERENCE.md`)
+
+---
+
+## 📋 Core Development Templates (25)
+
+### Documentation Templates
+- `TEMPLATE-001-INFRA-RUNBOOK.md` - Infrastructure deployment runbook
+- `TEMPLATE-002-ARCHITECTURE-OVERVIEW.md` - System architecture document
+- `TEMPLATE-003-API-DOCUMENTATION.md` - REST API reference doc
+- `TEMPLATE-004-README.md` - Perfect repository README
+- `TEMPLATE-005-CHANGELOG.md` - Semantic versioning changelog
+
+### Code Templates
+- `TEMPLATE-010-PYTHON-FLASK-SERVICE.py` - Flask HTTP service skeleton
+- `TEMPLATE-011-PYTHON-FASTAPI-SERVICE.py` - FastAPI service skeleton
+- `TEMPLATE-012-PYTHON-CLI-TOOL.py` - CLI tool with argparse
+- `TEMPLATE-013-BASH-SCRIPT.sh` - Bash script with menu mode
+- `TEMPLATE-014-DOCKERFILE.Dockerfile` - Multi-stage Docker build
+
+### Configuration Templates
+- `TEMPLATE-020-DOCKER-COMPOSE.yml` - Docker Compose multi-service
+- `TEMPLATE-021-GITHUB-WORKFLOW.yml` - GitHub Actions CI/CD
+- `TEMPLATE-022-REQUIREMENTS.txt` - Python dependencies
+- `TEMPLATE-023-PACKAGE.json` - Node.js project config
+- `TEMPLATE-024-WRANGLER.toml` - Cloudflare Worker config
+
+---
+
+## ⛅️ Cloudflare Templates (20)
+
+### Workers Templates
+- `cloudflare/TEMPLATE-WORKER-API.js` - REST API Worker
+- `cloudflare/TEMPLATE-WORKER-AUTH.js` - Authentication Worker
+- `cloudflare/TEMPLATE-WORKER-ROUTER.js` - Subdomain router
+- `cloudflare/TEMPLATE-WORKER-WEBSOCKET.js` - WebSocket handler (Durable Objects)
+- `cloudflare/TEMPLATE-WORKER-QUEUE.js` - Queue consumer
+
+### Pages Templates
+- `cloudflare/TEMPLATE-PAGES-LANDING.html` - Landing page with branding
+- `cloudflare/TEMPLATE-PAGES-DASHBOARD.html` - Admin dashboard
+- `cloudflare/TEMPLATE-PAGES-DOCS.html` - Documentation site
+- `cloudflare/TEMPLATE-PAGES-404.html` - Custom 404 page
+
+### Configuration Templates
+- `cloudflare/TEMPLATE-WRANGLER-WORKER.toml` - Worker deployment config
+- `cloudflare/TEMPLATE-WRANGLER-PAGES.toml` - Pages deployment config
+- `cloudflare/TEMPLATE-DNS-CONFIG.json` - DNS zone configuration
+- `cloudflare/TEMPLATE-ZERO-TRUST.json` - Zero Trust rules
+- `cloudflare/TEMPLATE-WAF-RULES.json` - Web Application Firewall rules
+
+### Database Templates
+- `cloudflare/TEMPLATE-D1-SCHEMA.sql` - D1 database schema
+- `cloudflare/TEMPLATE-KV-STRUCTURE.json` - KV namespace structure
+- `cloudflare/TEMPLATE-R2-BUCKET-POLICY.json` - R2 bucket policy
+
+---
+
+## 🛣 Railway Templates (10)
+
+### Service Configuration
+- `railway/TEMPLATE-SERVICE.toml` - Railway service config
+- `railway/TEMPLATE-NIXPACKS.toml` - Nixpacks build config
+- `railway/TEMPLATE-DOCKERFILE-RAILWAY.Dockerfile` - Railway-optimized Dockerfile
+- `railway/TEMPLATE-HEALTH-CHECK.py` - Health check endpoint
+
+### Deployment Templates
+- `railway/TEMPLATE-ENV-VARS.env` - Environment variables template
+- `railway/TEMPLATE-SECRETS-SETUP.sh` - Secrets configuration script
+- `railway/TEMPLATE-DEPLOY-SCRIPT.sh` - Deployment automation script
+
+### Monitoring Templates
+- `railway/TEMPLATE-LOGS-CONFIG.json` - Logging configuration
+- `railway/TEMPLATE-METRICS-CONFIG.json` - Metrics configuration
+
+---
+
+## 🖥 Vercel Templates (10)
+
+### Application Templates
+- `vercel/TEMPLATE-NEXTJS-APP/` - Next.js application structure
+- `vercel/TEMPLATE-REACT-APP/` - React SPA structure
+- `vercel/TEMPLATE-SERVERLESS-API/` - Serverless function structure
+
+### Configuration Templates
+- `vercel/TEMPLATE-VERCEL.json` - Vercel deployment config
+- `vercel/TEMPLATE-ENV-LOCAL.env` - Local environment setup
+- `vercel/TEMPLATE-ENV-PRODUCTION.env` - Production environment setup
+
+### Function Templates
+- `vercel/TEMPLATE-SERVERLESS-FUNCTION.js` - Serverless function
+- `vercel/TEMPLATE-EDGE-FUNCTION.js` - Edge function
+- `vercel/TEMPLATE-API-ROUTE.js` - API route handler
+
+---
+
+## 📁 Google Drive Templates (30)
+
+### Project Structure Templates
+- `google-drive/TEMPLATE-PROJECT-FOLDER/` - Complete project folder structure
+  - `00-PROJECT-CHARTER.gdoc` - Project charter document
+  - `01-ROADMAP.gsheet` - Project roadmap tracker
+  - `02-TEAM-ROSTER.gsheet` - Team member directory
+  - `03-MEETING-NOTES/` - Meeting notes folder with template
+  - `04-DELIVERABLES/` - Deliverables tracking folder
+  - `05-RESOURCES/` - Resource library folder
+
+### Document Templates
+- `google-drive/TEMPLATE-DOC-PROJECT-CHARTER.gdoc` - Project charter
+- `google-drive/TEMPLATE-DOC-TECHNICAL-SPEC.gdoc` - Technical specification
+- `google-drive/TEMPLATE-DOC-USER-GUIDE.gdoc` - User guide
+- `google-drive/TEMPLATE-DOC-API-DOCS.gdoc` - API documentation
+- `google-drive/TEMPLATE-DOC-MEETING-NOTES.gdoc` - Meeting notes
+- `google-drive/TEMPLATE-DOC-STATUS-REPORT.gdoc` - Status report
+
+### Spreadsheet Templates
+- `google-drive/TEMPLATE-SHEET-PROJECT-TRACKER.gsheet` - Project tracking
+- `google-drive/TEMPLATE-SHEET-BUDGET.gsheet` - Budget planning
+- `google-drive/TEMPLATE-SHEET-TIMELINE.gsheet` - Timeline Gantt chart
+- `google-drive/TEMPLATE-SHEET-CONTACTS.gsheet` - Contact database
+- `google-drive/TEMPLATE-SHEET-INVENTORY.gsheet` - Asset inventory
+- `google-drive/TEMPLATE-SHEET-METRICS.gsheet` - KPI dashboard
+
+### Presentation Templates
+- `google-drive/TEMPLATE-SLIDES-PITCH-DECK.gslides` - Investor pitch deck
+- `google-drive/TEMPLATE-SLIDES-PRODUCT-DEMO.gslides` - Product demo
+- `google-drive/TEMPLATE-SLIDES-QUARTERLY-REVIEW.gslides` - Quarterly review
+- `google-drive/TEMPLATE-SLIDES-ARCHITECTURE.gslides` - Architecture overview
+
+### Form Templates
+- `google-drive/TEMPLATE-FORM-USER-FEEDBACK.gform` - User feedback survey
+- `google-drive/TEMPLATE-FORM-BUG-REPORT.gform` - Bug report form
+- `google-drive/TEMPLATE-FORM-FEATURE-REQUEST.gform` - Feature request form
+
+---
+
+## 📓 Notion Templates (25)
+
+### Workspace Templates
+- `notion/TEMPLATE-WORKSPACE-COMPANY.json` - Complete company workspace
+- `notion/TEMPLATE-WORKSPACE-ENGINEERING.json` - Engineering team workspace
+- `notion/TEMPLATE-WORKSPACE-PRODUCT.json` - Product team workspace
+
+### Dashboard Templates
+- `notion/TEMPLATE-DASHBOARD-PROJECT.json` - Project dashboard
+- `notion/TEMPLATE-DASHBOARD-SPRINT.json` - Sprint dashboard
+- `notion/TEMPLATE-DASHBOARD-TEAM.json` - Team dashboard
+- `notion/TEMPLATE-DASHBOARD-PERSONAL.json` - Personal dashboard
+
+### Database Templates
+- `notion/TEMPLATE-DATABASE-TASKS.json` - Task database
+- `notion/TEMPLATE-DATABASE-PROJECTS.json` - Project database
+- `notion/TEMPLATE-DATABASE-DOCS.json` - Documentation database
+- `notion/TEMPLATE-DATABASE-CONTACTS.json` - Contact database
+- `notion/TEMPLATE-DATABASE-MEETINGS.json` - Meeting notes database
+- `notion/TEMPLATE-DATABASE-AGENTS.json` - Agent profiles database
+
+### Page Templates
+- `notion/TEMPLATE-PAGE-PROJECT-BRIEF.json` - Project brief page
+- `notion/TEMPLATE-PAGE-TECHNICAL-SPEC.json` - Technical spec page
+- `notion/TEMPLATE-PAGE-MEETING-NOTES.json` - Meeting notes page
+- `notion/TEMPLATE-PAGE-WEEKLY-UPDATE.json` - Weekly update page
+- `notion/TEMPLATE-PAGE-RETROSPECTIVE.json` - Sprint retrospective page
+- `notion/TEMPLATE-PAGE-OKR.json` - OKRs tracking page
+
+### Wiki Templates
+- `notion/TEMPLATE-WIKI-ENGINEERING.json` - Engineering wiki structure
+- `notion/TEMPLATE-WIKI-PRODUCT.json` - Product wiki structure
+- `notion/TEMPLATE-WIKI-COMPANY.json` - Company wiki structure
+
+---
+
+## 📁 GitHub Templates (20)
+
+### Repository Templates
+- `github/TEMPLATE-REPO-COMPLETE/` - Full repository structure
+  - `.github/ISSUE_TEMPLATE/bug_report.md`
+  - `.github/ISSUE_TEMPLATE/feature_request.md`
+  - `.github/ISSUE_TEMPLATE/documentation.md`
+  - `.github/PULL_REQUEST_TEMPLATE.md`
+  - `.github/workflows/test.yml`
+  - `.github/workflows/deploy.yml`
+  - `.github/CODEOWNERS`
+  - `.github/SECURITY.md`
+  - `README.md`
+  - `LICENSE`
+  - `CONTRIBUTING.md`
+
+### Issue Templates
+- `github/TEMPLATE-ISSUE-BUG.md` - Bug report
+- `github/TEMPLATE-ISSUE-FEATURE.md` - Feature request
+- `github/TEMPLATE-ISSUE-DOCS.md` - Documentation request
+- `github/TEMPLATE-ISSUE-SECURITY.md` - Security vulnerability
+
+### Workflow Templates
+- `github/TEMPLATE-WORKFLOW-TEST.yml` - Test automation
+- `github/TEMPLATE-WORKFLOW-DEPLOY-CLOUDFLARE.yml` - Cloudflare deployment
+- `github/TEMPLATE-WORKFLOW-DEPLOY-RAILWAY.yml` - Railway deployment
+- `github/TEMPLATE-WORKFLOW-DEPLOY-VERCEL.yml` - Vercel deployment
+- `github/TEMPLATE-WORKFLOW-SECURITY-SCAN.yml` - Security scanning
+- `github/TEMPLATE-WORKFLOW-PERFORMANCE.yml` - Performance monitoring
+
+---
+
+## 📋 Task Management Templates (15)
+
+### Linear Templates
+- `task-management/linear/TEMPLATE-PROJECT.json` - Project template
+- `task-management/linear/TEMPLATE-SPRINT.json` - Sprint template
+- `task-management/linear/TEMPLATE-EPIC.json` - Epic template
+- `task-management/linear/TEMPLATE-ISSUE.json` - Issue template
+
+### Jira Templates
+- `task-management/jira/TEMPLATE-PROJECT.json` - Jira project
+- `task-management/jira/TEMPLATE-SPRINT.json` - Jira sprint
+- `task-management/jira/TEMPLATE-EPIC.json` - Jira epic
+- `task-management/jira/TEMPLATE-STORY.json` - User story
+- `task-management/jira/TEMPLATE-TASK.json` - Task template
+
+### Asana Templates
+- `task-management/asana/TEMPLATE-PROJECT.json` - Asana project
+- `task-management/asana/TEMPLATE-SPRINT.json` - Asana sprint
+- `task-management/asana/TEMPLATE-MILESTONE.json` - Milestone
+- `task-management/asana/TEMPLATE-TASK.json` - Task template
+
+---
+
+## 🗂 Airtable Templates (10)
+
+### Base Templates
+- `airtable/TEMPLATE-CRM-COMPLETE.json` - Complete CRM base
+- `airtable/TEMPLATE-PROJECT-TRACKER.json` - Project tracking base
+- `airtable/TEMPLATE-CONTENT-CALENDAR.json` - Content calendar base
+- `airtable/TEMPLATE-INVENTORY.json` - Inventory management base
+
+### Table Templates
+- `airtable/TEMPLATE-TABLE-CONTACTS.json` - Contact table
+- `airtable/TEMPLATE-TABLE-DEALS.json` - Sales pipeline table
+- `airtable/TEMPLATE-TABLE-TASKS.json` - Task tracking table
+- `airtable/TEMPLATE-TABLE-ASSETS.json` - Asset inventory table
+
+### View Templates
+- `airtable/TEMPLATE-VIEW-KANBAN.json` - Kanban board view
+- `airtable/TEMPLATE-VIEW-CALENDAR.json` - Calendar view
+
+---
+
+## 🌐 Subdomain Templates (5,216 variations)
+
+### Landing Page Templates (by category)
+- `subdomains/TEMPLATE-LANDING-GENERIC.html` - Generic landing page
+- `subdomains/TEMPLATE-LANDING-API.html` - API service page
+- `subdomains/TEMPLATE-LANDING-DASHBOARD.html` - Dashboard app page
+- `subdomains/TEMPLATE-LANDING-DOCS.html` - Documentation site page
+- `subdomains/TEMPLATE-LANDING-AUTH.html` - Authentication page
+- `subdomains/TEMPLATE-LANDING-PAYMENT.html` - Payment integration page
+- `subdomains/TEMPLATE-LANDING-AGENT.html` - Agent portal page
+- `subdomains/TEMPLATE-LANDING-QUANTUM.html` - Quantum computing page
+- `subdomains/TEMPLATE-LANDING-AI.html` - AI/ML service page
+- `subdomains/TEMPLATE-LANDING-BLOCKCHAIN.html` - Blockchain service page
+
+### Domain-Specific Templates (16 domains)
+Each domain has customized versions of all landing page templates:
+- `subdomains/blackroad-io/` - Main platform (364 templates)
+- `subdomains/lucidia-earth/` - Lucidia OS (364 templates)
+- `subdomains/blackroadai-com/` - AI focus (364 templates)
+- `subdomains/blackroadquantum-com/` - Quantum focus (364 templates)
+- *(12 more domains...)*
+
+---
+
+## 🧩 Integration Templates (15 platforms × 5 templates = 75)
+
+### Stripe Templates
+- `integrations/stripe/TEMPLATE-CHECKOUT-PAGE.html` - Checkout page
+- `integrations/stripe/TEMPLATE-SUCCESS-PAGE.html` - Success page
+- `integrations/stripe/TEMPLATE-WEBHOOK-HANDLER.py` - Webhook handler
+- `integrations/stripe/TEMPLATE-PRODUCT-SETUP.sh` - Product setup script
+- `integrations/stripe/TEMPLATE-SUBSCRIPTION-API.py` - Subscription API
+
+### Clerk Templates
+- `integrations/clerk/TEMPLATE-AUTH-PAGE.html` - Authentication page
+- `integrations/clerk/TEMPLATE-USER-PROFILE.tsx` - User profile component
+- `integrations/clerk/TEMPLATE-MIDDLEWARE.ts` - Auth middleware
+- `integrations/clerk/TEMPLATE-WEBHOOK-HANDLER.py` - Webhook handler
+- `integrations/clerk/TEMPLATE-SSO-CONFIG.json` - SSO configuration
+
+### Resend Templates
+- `integrations/resend/TEMPLATE-EMAIL-WELCOME.html` - Welcome email
+- `integrations/resend/TEMPLATE-EMAIL-RECEIPT.html` - Receipt email
+- `integrations/resend/TEMPLATE-EMAIL-NOTIFICATION.html` - Notification email
+- `integrations/resend/TEMPLATE-SEND-API.py` - Email sending API
+- `integrations/resend/TEMPLATE-CAMPAIGN.json` - Email campaign
+
+### Asana Templates
+- `integrations/asana/TEMPLATE-PROJECT.json` - Project template
+- `integrations/asana/TEMPLATE-TASK-AUTOMATION.py` - Task automation script
+- `integrations/asana/TEMPLATE-SYNC-SCRIPT.py` - Data sync script
+- `integrations/asana/TEMPLATE-WEBHOOK-HANDLER.py` - Webhook handler
+- `integrations/asana/TEMPLATE-REPORT-GENERATOR.py` - Report generator
+
+### Notion Templates
+- `integrations/notion/TEMPLATE-DATABASE.json` - Database template
+- `integrations/notion/TEMPLATE-PAGE-SYNC.py` - Page sync script
+- `integrations/notion/TEMPLATE-AUTOMATION.py` - Automation script
+- `integrations/notion/TEMPLATE-EXPORT-SCRIPT.py` - Export script
+- `integrations/notion/TEMPLATE-WIDGET.html` - Embed widget
+
+*(Similar 5-template sets for 11 more platforms: Jira, Linear, Gmail, Outlook, Google Drive, Dropbox, OneDrive, Slack, Discord, GitHub, GitLab)*
+
+---
+
+## 📊 Usage Statistics
+
+### Most Used Templates (Top 10)
+1. `TEMPLATE-004-README.md` - 43 repos
+2. `cloudflare/TEMPLATE-LANDING-GENERIC.html` - 872 sites
+3. `TEMPLATE-010-PYTHON-FLASK-SERVICE.py` - 28 repos
+4. `notion/TEMPLATE-DASHBOARD-PROJECT.json` - 156 projects
+5. `github/TEMPLATE-WORKFLOW-DEPLOY-CLOUDFLARE.yml` - 43 repos
+6. `TEMPLATE-001-INFRA-RUNBOOK.md` - 37 deployments
+7. `integrations/stripe/TEMPLATE-CHECKOUT-PAGE.html` - 20 implementations
+8. `railway/TEMPLATE-SERVICE.toml` - 36 services
+9. `subdomains/TEMPLATE-LANDING-API.html` - 648 API services
+10. `TEMPLATE-013-BASH-SCRIPT.sh` - 89 scripts
+
+---
+
+## 🎯 Quick Start Guide
+
+### Use a Template
+
+```bash
+# 1. Copy the template
+cp templates/TEMPLATE-001-INFRA-RUNBOOK.md my-deployment-guide.md
+
+# 2. Search and replace placeholders
+sed -i '' 's/<PROJECT_NAME>/My Awesome Project/g' my-deployment-guide.md
+
+# 3. Customize as needed
+vim my-deployment-guide.md
+```
+
+### Generate from Template
+
+```bash
+# Use template generator script
+python3 generate-from-template.py \
+  --template="TEMPLATE-001-INFRA-RUNBOOK.md" \
+  --output="cloudflare-deployment.md" \
+  --vars="project_name=Cloudflare Max Buildout,tool=wrangler,version=4.51.0"
+```
+
+### Deploy Templates
+
+```bash
+# Sync all templates to all repos
+./sync-templates-to-all-repos.sh
+
+# Deploy subdomain templates
+./deploy-all-subdomain-templates.sh
+
+# Import to platforms
+./import-templates-to-platforms.sh
+```
+
+---
+
+## 🔄 Template Maintenance
+
+### Update a Template
+
+```bash
+# 1. Edit template
+vim templates/TEMPLATE-001-INFRA-RUNBOOK.md
+
+# 2. Sync to all instances
+./sync-template-update.sh TEMPLATE-001-INFRA-RUNBOOK.md
+
+# 3. Verify propagation
+./verify-template-sync.sh
+```
+
+### Create New Template
+
+```bash
+# Use the template-template 😉
+cp templates/TEMPLATE-000-TEMPLATE-TEMPLATE.md templates/TEMPLATE-NEW.md
+
+# Follow the structure guide
+vim templates/TEMPLATE-NEW.md
+```
+
+---
+
+## 📚 Related Documentation
+
+- `EMOJI-REFERENCE.md` - 127-emoji language system
+- `MASTER-TEMPLATE-SYSTEM.md` - Complete template system overview
+- `TEMPLATE-USAGE-GUIDE.md` - Detailed usage instructions
+- `TEMPLATE-BEST-PRACTICES.md` - Best practices and patterns
+
+---
+
+## 🎉 Template Benefits
+
+- **10x faster** project setup
+- **Zero boilerplate** writing
+- **Consistent quality** across all projects
+- **Always up-to-date** with latest practices
+- **Machine-teachable** patterns for AI
+- **Copy-paste-and-learn** approach
+
+---
+
+**Total Templates**: 200+
+**Total Platform Coverage**: 15+ platforms
+**Total Subdomain Coverage**: 5,216 sites
+**Total Repository Coverage**: 43 repos
+
+**Remember**: Perfect templates = zero thinking required. Just copy, paste, customize, deploy. ✨🚀

templates/TEMPLATE-SYSTEM-GRAPHSQL-SCHEMA.sql

@@ -0,0 +1,472 @@
+-- ============================================================================
+-- BlackRoad OS Template System - GraphSQL Schema
+-- Complete graph database schema for all 200+ templates
+-- ============================================================================
+
+-- ============================================================================
+-- TEMPLATE 001: INFRA RUNBOOK / DEPLOY SCRIPT
+-- ============================================================================
+
+-- Main template structure (sections/blocks)
+CREATE TABLE IF NOT EXISTS template_001_nodes (
+  id        TEXT PRIMARY KEY,
+  label     TEXT NOT NULL,
+  kind      TEXT NOT NULL,         -- 'section', 'block', 'component'
+  emoji     TEXT,                  -- Canonical emoji from EMOJI-REFERENCE.md
+  description TEXT
+);
+
+CREATE TABLE IF NOT EXISTS template_001_edges (
+  from_id   TEXT NOT NULL,
+  to_id     TEXT NOT NULL,
+  label     TEXT,                  -- 'flows_to', 'contains', 'depends_on'
+  FOREIGN KEY (from_id) REFERENCES template_001_nodes(id),
+  FOREIGN KEY (to_id)   REFERENCES template_001_nodes(id),
+  PRIMARY KEY (from_id, to_id, label)
+);
+
+-- Template 001 nodes (sections)
+INSERT OR REPLACE INTO template_001_nodes (id, label, kind, emoji, description) VALUES
+  ('header',          'Header Bar',                      'section', '🛣',  'Title bar with context and system name'),
+  ('context',         'Context Line (tools/env)',        'section', '⛅️', 'Tool versions, environment, region'),
+  ('bindings_card',   'Worker / Service Bindings Card',  'block',   '📦', 'Resource bindings table'),
+  ('infra_status',    'Infrastructure Status Card',      'block',   '📡', 'Status of all infrastructure resources'),
+  ('steps_pipeline',  'Execute N Steps Pipeline',        'section', '🚀', 'Numbered deployment steps'),
+  ('value_card',      'Value Delivered Card',            'block',   '💎', 'Cost vs value comparison'),
+  ('docs_block',      'Documentation List',              'block',   '📚', 'Links to documentation files'),
+  ('checklist_block', 'Checklist',                       'block',   '🗒', 'Manual verification checklist'),
+  ('next_steps',      'Next Steps',                      'block',   '🎯', 'Post-deployment actions'),
+  ('tips_block',      'Tips',                            'block',   '💡', 'Pro tips and best practices'),
+  ('footer',          'Footer Strip (Epic Done)',        'section', '🔥', 'Summary celebration line');
+
+-- Template 001 edges (flow order)
+INSERT OR REPLACE INTO template_001_edges (from_id, to_id, label) VALUES
+  ('header',         'context',        'flows_to'),
+  ('context',        'bindings_card',  'flows_to'),
+  ('bindings_card',  'infra_status',   'flows_to'),
+  ('infra_status',   'steps_pipeline', 'flows_to'),
+  ('steps_pipeline', 'value_card',     'flows_to'),
+  ('value_card',     'docs_block',     'flows_to'),
+  ('docs_block',     'checklist_block','flows_to'),
+  ('checklist_block','next_steps',     'flows_to'),
+  ('next_steps',     'tips_block',     'flows_to'),
+  ('tips_block',     'footer',         'flows_to');
+
+-- Template 001 step pipeline substructure
+CREATE TABLE IF NOT EXISTS template_001_step_nodes (
+  id        TEXT PRIMARY KEY,
+  step_no   INTEGER NOT NULL,
+  label     TEXT NOT NULL,
+  emoji     TEXT DEFAULT '▶️',
+  command   TEXT                   -- Optional: the actual command to run
+);
+
+CREATE TABLE IF NOT EXISTS template_001_step_edges (
+  from_id   TEXT NOT NULL,
+  to_id     TEXT NOT NULL,
+  label     TEXT DEFAULT 'next',
+  FOREIGN KEY (from_id) REFERENCES template_001_step_nodes(id),
+  FOREIGN KEY (to_id)   REFERENCES template_001_step_nodes(id),
+  PRIMARY KEY (from_id, to_id)
+);
+
+INSERT OR REPLACE INTO template_001_step_nodes (id, step_no, label, emoji) VALUES
+  ('step_1', 1, 'Step 1: <STEP_TITLE_1>', '🚀'),
+  ('step_2', 2, 'Step 2: <STEP_TITLE_2>', '🔄'),
+  ('step_3', 3, 'Step 3: <STEP_TITLE_3>', '📥'),
+  ('step_n', 4, 'Step N: <FINAL_STEP_TITLE>', '✅');
+
+INSERT OR REPLACE INTO template_001_step_edges (from_id, to_id, label) VALUES
+  ('step_1', 'step_2', 'next'),
+  ('step_2', 'step_3', 'next'),
+  ('step_3', 'step_n', 'next');
+
+-- ============================================================================
+-- TEMPLATE 002: ARCHITECTURE / SYSTEM OVERVIEW
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS template_002_nodes (
+  id        TEXT PRIMARY KEY,
+  label     TEXT NOT NULL,
+  kind      TEXT NOT NULL,        -- 'section', 'diagram', 'component'
+  emoji     TEXT,
+  description TEXT
+);
+
+CREATE TABLE IF NOT EXISTS template_002_edges (
+  from_id   TEXT NOT NULL,
+  to_id     TEXT NOT NULL,
+  label     TEXT,
+  FOREIGN KEY (from_id) REFERENCES template_002_nodes(id),
+  FOREIGN KEY (to_id)   REFERENCES template_002_nodes(id),
+  PRIMARY KEY (from_id, to_id, label)
+);
+
+-- Template 002 top-level sections
+INSERT OR REPLACE INTO template_002_nodes (id, label, kind, emoji, description) VALUES
+  ('header',          'Header Bar',                        'section', '🛣', 'System name and context'),
+  ('overview',        'Overview',                          'section', '🧭', 'What the system is and does'),
+  ('diagram',         'High-Level System Diagram',         'diagram', '🏗', 'ASCII diagram of system topology'),
+  ('components',      'Component Breakdown',               'section', '📦', 'Detailed component descriptions'),
+  ('flows',           'Request / Data Flows',              'section', '👉', 'Numbered data flow diagrams'),
+  ('non_functional',  'Reliability / Security / Limits',   'section', '🔐', 'Non-functional requirements'),
+  ('operations',      'Operations: Deploy / Observe / Debug','section', '🧰', 'Operational procedures'),
+  ('docs_block',      'Documentation & References',        'section', '📚', 'Links to related docs'),
+  ('checklist_block', 'Checklists',                        'block',   '🗒', 'Verification checklists'),
+  ('next_steps',      'Next Steps',                        'block',   '🎯', 'What to do next'),
+  ('tips_block',      'Tips',                              'block',   '💡', 'Pro tips and gotchas');
+
+-- Template 002 linear reading order
+INSERT OR REPLACE INTO template_002_edges (from_id, to_id, label) VALUES
+  ('header',         'overview',        'flows_to'),
+  ('overview',       'diagram',         'flows_to'),
+  ('diagram',        'components',      'flows_to'),
+  ('components',     'flows',           'flows_to'),
+  ('flows',          'non_functional',  'flows_to'),
+  ('non_functional', 'operations',      'flows_to'),
+  ('operations',     'docs_block',      'flows_to'),
+  ('docs_block',     'checklist_block', 'flows_to'),
+  ('checklist_block','next_steps',      'flows_to'),
+  ('next_steps',     'tips_block',      'flows_to');
+
+-- Template 002 component nodes (system architecture components)
+CREATE TABLE IF NOT EXISTS template_002_component_nodes (
+  id         TEXT PRIMARY KEY,
+  label      TEXT NOT NULL,
+  kind       TEXT NOT NULL,       -- 'user', 'edge', 'service', 'data', 'integration'
+  emoji      TEXT,
+  description TEXT,
+  tech_stack TEXT                 -- e.g. "Cloudflare Workers", "Flask + Python", "D1 SQLite"
+);
+
+CREATE TABLE IF NOT EXISTS template_002_component_edges (
+  from_id    TEXT NOT NULL,
+  to_id      TEXT NOT NULL,
+  label      TEXT,                -- 'https_request', 'route_api', 'reads_writes', etc.
+  protocol   TEXT,                -- 'HTTPS', 'WebSocket', 'Queue', 'gRPC', etc.
+  FOREIGN KEY (from_id) REFERENCES template_002_component_nodes(id),
+  FOREIGN KEY (to_id)   REFERENCES template_002_component_nodes(id),
+  PRIMARY KEY (from_id, to_id, label)
+);
+
+INSERT OR REPLACE INTO template_002_component_nodes (id, label, kind, emoji, description) VALUES
+  ('user',       'Users / Clients',            'user',        '👤', 'End users and API clients'),
+  ('edge',       'Edge / Gateway (Cloudflare)','edge',        '⛅️', 'CDN and routing layer'),
+  ('service_a',  'Service A (Core API)',       'service',     '🛰', 'Main API service'),
+  ('service_b',  'Service B (Web / UI)',       'service',     '🖥', 'Web frontend / dashboard'),
+  ('db_layer',   'Databases',                  'data',        '🧱', 'Persistent data storage'),
+  ('queue_layer','Queues',                     'data',        '📨', 'Message queues for async jobs'),
+  ('storage',    'Object / KV Storage',        'data',        '🗂', 'File and key-value storage'),
+  ('integrations','External Integrations',     'integration', '🧩', 'Third-party services');
+
+INSERT OR REPLACE INTO template_002_component_edges (from_id, to_id, label, protocol) VALUES
+  ('user',        'edge',        'https_request',  'HTTPS'),
+  ('edge',        'service_a',   'route_api',      'HTTPS'),
+  ('edge',        'service_b',   'route_web',      'HTTPS'),
+  ('service_a',   'db_layer',    'reads_writes',   'SQL'),
+  ('service_a',   'queue_layer', 'enqueue_jobs',   'Queue'),
+  ('service_a',   'storage',     'store_assets',   'HTTP'),
+  ('service_b',   'service_a',   'api_calls',      'HTTPS'),
+  ('service_a',   'integrations','external_calls', 'HTTPS');
+
+-- ============================================================================
+-- TEMPLATE 003: DOMAIN / DNS / ROUTING MAP
+-- For 16 domains × 364 subdomains = 5,216 total sites
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS template_003_domain_nodes (
+  id              TEXT PRIMARY KEY,
+  domain          TEXT NOT NULL UNIQUE,
+  emoji           TEXT DEFAULT '🌐',
+  purpose         TEXT,
+  status          TEXT DEFAULT 'active',     -- 'active', 'pending', 'inactive'
+  cloudflare_zone TEXT,                      -- Cloudflare Zone ID
+  subdomain_count INTEGER DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS template_003_subdomain_nodes (
+  id          TEXT PRIMARY KEY,
+  subdomain   TEXT NOT NULL,
+  domain_id   TEXT NOT NULL,
+  full_url    TEXT NOT NULL,
+  emoji       TEXT,
+  category    TEXT,                         -- 'api', 'dashboard', 'docs', 'auth', etc.
+  backend     TEXT,                         -- Railway service, Worker, etc.
+  status      TEXT DEFAULT 'pending',       -- 'live', 'pending', 'failed'
+  FOREIGN KEY (domain_id) REFERENCES template_003_domain_nodes(id)
+);
+
+CREATE TABLE IF NOT EXISTS template_003_routing_edges (
+  from_id     TEXT NOT NULL,
+  to_id       TEXT NOT NULL,
+  route_type  TEXT,                         -- 'dns', 'worker_route', 'service_route'
+  priority    INTEGER DEFAULT 100,
+  FOREIGN KEY (from_id) REFERENCES template_003_subdomain_nodes(id),
+  PRIMARY KEY (from_id, to_id)
+);
+
+-- 16 primary domains
+INSERT OR REPLACE INTO template_003_domain_nodes (id, domain, emoji, purpose, subdomain_count) VALUES
+  ('blackroad-io',         'blackroad.io',         '🛣', 'Main platform', 364),
+  ('lucidia-earth',        'lucidia.earth',        '🔮', 'Lucidia OS', 364),
+  ('blackroadai-com',      'blackroadai.com',      '🤖', 'AI services', 364),
+  ('blackroadquantum-com', 'blackroadquantum.com', '⚛️', 'Quantum computing', 364),
+  ('blackroad-network',    'blackroad.network',    '📡', 'Network services', 364),
+  ('blackroad-systems',    'blackroad.systems',    '🏗', 'System services', 364),
+  ('blackroad-me',         'blackroad.me',         '👤', 'Personal brand', 364),
+  ('blackroadinc-us',      'blackroad-inc.us',     '🏢', 'Corporate entity', 364),
+  ('aliceqi-com',          'aliceqi.com',          '👩‍💻', 'Alice Qi brand', 364),
+  ('blackroadqi-com',      'blackroadqi.com',      '🧠', 'Quantum intelligence', 364),
+  ('lucidiaqi-com',        'lucidiaqi.com',        '💎', 'Lucidia intelligence', 364),
+  ('lucidiastud-io',       'lucidiastud.io',       '🎨', 'Lucidia studio', 364),
+  ('blackroadquantum-info','blackroadquantum.info','ℹ️', 'Quantum info', 364),
+  ('blackroadquantum-net', 'blackroadquantum.net', '🖧', 'Quantum network', 364),
+  ('blackroadquantum-shop','blackroadquantum.shop','🛒', 'Quantum shop', 364),
+  ('blackroadquantum-store','blackroadquantum.store','🏪', 'Quantum store', 364);
+
+-- Example subdomains for blackroad.io (would be 364 total)
+INSERT OR REPLACE INTO template_003_subdomain_nodes (id, subdomain, domain_id, full_url, emoji, category, status) VALUES
+  ('blackroad-io-api',       'api',       'blackroad-io', 'https://api.blackroad.io',       '🔌', 'api',       'live'),
+  ('blackroad-io-dashboard', 'dashboard', 'blackroad-io', 'https://dashboard.blackroad.io', '📊', 'dashboard', 'live'),
+  ('blackroad-io-docs',      'docs',      'blackroad-io', 'https://docs.blackroad.io',      '📚', 'docs',      'live'),
+  ('blackroad-io-auth',      'auth',      'blackroad-io', 'https://auth.blackroad.io',      '🔐', 'auth',      'live'),
+  ('blackroad-io-payment',   'payment',   'blackroad-io', 'https://payment.blackroad.io',   '💳', 'payment',   'live'),
+  ('blackroad-io-agents',    'agents',    'blackroad-io', 'https://agents.blackroad.io',    '🤖', 'agents',    'live'),
+  ('blackroad-io-quantum',   'quantum',   'blackroad-io', 'https://quantum.blackroad.io',   '⚛️', 'quantum',   'live'),
+  ('blackroad-io-vector',    'vector',    'blackroad-io', 'https://vector.blackroad.io',    '🧬', 'data',      'live'),
+  ('blackroad-io-stream',    'stream',    'blackroad-io', 'https://stream.blackroad.io',    '📡', 'data',      'live'),
+  ('blackroad-io-mq',        'mq',        'blackroad-io', 'https://mq.blackroad.io',        '📨', 'data',      'live');
+
+-- ============================================================================
+-- MASTER TEMPLATE CATALOG
+-- All 200+ templates with metadata
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS template_catalog (
+  id              TEXT PRIMARY KEY,
+  name            TEXT NOT NULL,
+  category        TEXT NOT NULL,     -- 'core', 'cloudflare', 'railway', 'google-drive', etc.
+  type            TEXT NOT NULL,     -- 'document', 'code', 'config', 'script'
+  file_path       TEXT NOT NULL,
+  emoji           TEXT,
+  description     TEXT,
+  variables       TEXT,              -- JSON array of variable placeholders
+  usage_count     INTEGER DEFAULT 0,
+  last_used       TIMESTAMP,
+  created_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS template_dependencies (
+  template_id     TEXT NOT NULL,
+  depends_on      TEXT NOT NULL,
+  dependency_type TEXT,              -- 'requires', 'extends', 'includes'
+  FOREIGN KEY (template_id) REFERENCES template_catalog(id),
+  FOREIGN KEY (depends_on)  REFERENCES template_catalog(id),
+  PRIMARY KEY (template_id, depends_on)
+);
+
+-- Core templates
+INSERT OR REPLACE INTO template_catalog (id, name, category, type, file_path, emoji, description) VALUES
+  ('T001', 'Infra Runbook / Deploy Script',    'core', 'document', 'TEMPLATE-001-INFRA-RUNBOOK.md',        '🚀', 'Deployment runbook template'),
+  ('T002', 'Architecture / System Overview',   'core', 'document', 'TEMPLATE-002-ARCHITECTURE-OVERVIEW.md', '🏗', 'System architecture template'),
+  ('T003', 'Domain / DNS / Routing Map',       'core', 'document', 'TEMPLATE-003-DOMAIN-DNS-ROUTING.md',    '🌐', 'DNS routing configuration'),
+  ('T004', 'README',                            'core', 'document', 'TEMPLATE-004-README.md',                '📖', 'Perfect repository README'),
+  ('T005', 'Changelog',                         'core', 'document', 'TEMPLATE-005-CHANGELOG.md',             '📝', 'Semantic versioning changelog');
+
+-- Cloudflare templates
+INSERT OR REPLACE INTO template_catalog (id, name, category, type, file_path, emoji, description) VALUES
+  ('CF01', 'Worker API',                        'cloudflare', 'code',   'cloudflare/TEMPLATE-WORKER-API.js',      '⛅️', 'REST API Worker'),
+  ('CF02', 'Worker Auth',                       'cloudflare', 'code',   'cloudflare/TEMPLATE-WORKER-AUTH.js',     '🔐', 'Authentication Worker'),
+  ('CF03', 'Worker Router',                     'cloudflare', 'code',   'cloudflare/TEMPLATE-WORKER-ROUTER.js',   '🔀', 'Subdomain router'),
+  ('CF04', 'Pages Landing',                     'cloudflare', 'code',   'cloudflare/TEMPLATE-PAGES-LANDING.html', '🌐', 'Landing page template'),
+  ('CF05', 'Wrangler Config',                   'cloudflare', 'config', 'cloudflare/TEMPLATE-WRANGLER.toml',      '🔧', 'Worker deployment config');
+
+-- Google Drive templates
+INSERT OR REPLACE INTO template_catalog (id, name, category, type, file_path, emoji, description) VALUES
+  ('GD01', 'Project Structure',                'google-drive', 'document', 'google-drive/PROJECT-STRUCTURE-TEMPLATE.json',      '📁', 'Complete project folder'),
+  ('GD02', 'Technical Spec',                   'google-drive', 'document', 'google-drive/TEMPLATE-DOC-TECHNICAL-SPEC.json',    '📘', 'Technical specification'),
+  ('GD03', 'User Guide',                       'google-drive', 'document', 'google-drive/TEMPLATE-DOC-USER-GUIDE.json',        '📙', 'User documentation'),
+  ('GD04', 'Meeting Notes',                    'google-drive', 'document', 'google-drive/TEMPLATE-DOC-MEETING-NOTES.json',     '📝', 'Meeting notes template');
+
+-- Notion templates
+INSERT OR REPLACE INTO template_catalog (id, name, category, type, file_path, emoji, description) VALUES
+  ('N001', 'Project Dashboard',                'notion', 'document', 'notion/TEMPLATE-DASHBOARD-PROJECT.json',     '📊', 'Project management dashboard'),
+  ('N002', 'Tasks Database',                   'notion', 'document', 'notion/TEMPLATE-DATABASE-TASKS.json',        '📋', 'Task tracking database'),
+  ('N003', 'Agent Profile',                    'notion', 'document', 'notion/TEMPLATE-PAGE-AGENT-PROFILE.json',    '🤖', 'Agent documentation page');
+
+-- GitHub templates
+INSERT OR REPLACE INTO template_catalog (id, name, category, type, file_path, emoji, description) VALUES
+  ('GH01', 'Bug Report',                       'github', 'document', 'github/ISSUE_TEMPLATE/bug_report.md',        '🐛', 'Bug report issue template'),
+  ('GH02', 'Feature Request',                  'github', 'document', 'github/ISSUE_TEMPLATE/feature_request.md',   '✨', 'Feature request template'),
+  ('GH03', 'Pull Request',                     'github', 'document', 'github/PULL_REQUEST_TEMPLATE.md',            '📥', 'PR template with checklist');
+
+-- Airtable templates
+INSERT OR REPLACE INTO template_catalog (id, name, category, type, file_path, emoji, description) VALUES
+  ('AT01', 'CRM Complete',                     'airtable', 'document', 'airtable/TEMPLATE-CRM-COMPLETE.json',      '🗂', 'Full CRM base with tables');
+
+-- ============================================================================
+-- EMOJI REFERENCE TABLE
+-- All 127 canonical emojis from EMOJI-REFERENCE.md
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS emoji_reference (
+  emoji       TEXT PRIMARY KEY,
+  name        TEXT NOT NULL,
+  category    TEXT NOT NULL,      -- From 1-10 categories
+  meaning     TEXT NOT NULL,
+  usage       TEXT NOT NULL
+);
+
+-- Layout & Pointers (23)
+INSERT OR REPLACE INTO emoji_reference (emoji, name, category, meaning, usage) VALUES
+  ('👉', 'Main pointer',     'Layout & Pointers', 'Call out important line/choice', 'Highlight key information'),
+  ('➡️', 'Next/forward',     'Layout & Pointers', 'Move to next step', 'Sequential flow'),
+  ('⬅️', 'Back/previous',    'Layout & Pointers', 'Rollback step, go back', 'Reverse flow'),
+  ('↗️', 'Escalate',         'Layout & Pointers', 'Scale up resources', 'Increase capacity'),
+  ('↘️', 'De-escalate',      'Layout & Pointers', 'Scale down resources', 'Decrease capacity'),
+  ('🔁', 'Loop/repeat',      'Layout & Pointers', 'Repeat step/cron-like', 'Cyclic operation'),
+  ('➕', 'Add',              'Layout & Pointers', 'Create resource, add config', 'Addition'),
+  ('➖', 'Remove',           'Layout & Pointers', 'Remove resource, subtract', 'Deletion');
+
+-- Context / Platform (17)
+INSERT OR REPLACE INTO emoji_reference (emoji, name, category, meaning, usage) VALUES
+  ('⛅️', 'Cloudflare',       'Context / Platform', 'Workers, R2, D1, Wrangler', 'Cloudflare context'),
+  ('☁️', 'Generic cloud',    'Context / Platform', 'AWS, GCP, etc.', 'Cloud platform'),
+  ('💻', 'Dev machine/local','Context / Platform', 'Local dev, CLI tooling', 'Local environment'),
+  ('🛣', 'BlackRoad OS',     'Context / Platform', 'Cross-system/orchestration', 'BlackRoad system'),
+  ('📱', 'Mobile',           'Context / Platform', 'iOS/Android/TestFlight', 'Mobile app'),
+  ('🖥', 'Web app',          'Context / Platform', 'Dashboards, web frontends', 'Web application'),
+  ('🌐', 'DNS/domains',      'Context / Platform', 'Domains, subdomains, routing', 'DNS configuration'),
+  ('💳', 'Payments',         'Context / Platform', 'Stripe, billing flows', 'Payment system'),
+  ('🔐', 'Security/auth',    'Context / Platform', 'Secrets, auth, lock-down', 'Security');
+
+-- Actions (17)
+INSERT OR REPLACE INTO emoji_reference (emoji, name, category, meaning, usage) VALUES
+  ('🚀', 'Deploy/launch',    'Actions', 'Ship to environment', 'Deployment'),
+  ('▶️', 'Run',              'Actions', 'Run script/command/job', 'Execution'),
+  ('⏹', 'Stop',             'Actions', 'Stop process/kill job', 'Termination'),
+  ('🔄', 'Sync',             'Actions', 'Refresh state, pull latest', 'Synchronization'),
+  ('♻️', 'Redeploy',         'Actions', 'Recreate with same config', 'Redeployment'),
+  ('📥', 'Import',           'Actions', 'Ingest configs/data/DNS', 'Import operation'),
+  ('📤', 'Export',           'Actions', 'Backup, snapshot, archive', 'Export operation'),
+  ('🔧', 'Configure',        'Actions', 'Change config, settings', 'Configuration'),
+  ('🪛', 'Fix',              'Actions', 'Small targeted fix, patch', 'Bug fix');
+
+-- Status / Severity (13)
+INSERT OR REPLACE INTO emoji_reference (emoji, name, category, meaning, usage) VALUES
+  ('✅', 'OK/done',          'Status / Severity', 'Succeeded, safe, verified', 'Success state'),
+  ('☐', 'Todo',             'Status / Severity', 'Manual step remaining', 'Pending task'),
+  ('⏳', 'Pending',          'Status / Severity', 'Waiting, in progress', 'In progress'),
+  ('⚠️', 'Warning',          'Status / Severity', 'Non-fatal, needs attention', 'Warning state'),
+  ('❌', 'Error',            'Status / Severity', 'Failed, stop here', 'Error state'),
+  ('🚨', 'Incident',         'Status / Severity', 'On-fire, high severity', 'Critical issue'),
+  ('🔍', 'Investigate',      'Status / Severity', 'Look closer/drill in', 'Investigation');
+
+-- Resources & Infra (17)
+INSERT OR REPLACE INTO emoji_reference (emoji, name, category, meaning, usage) VALUES
+  ('📦', 'Package/artifact', 'Resources & Infra', 'Worker script, bundle, container', 'Artifact'),
+  ('📁', 'Folder/repo',      'Resources & Infra', 'GitHub repo, directory', 'Repository'),
+  ('🧱', 'Database',         'Resources & Infra', 'D1 tables, infra blocks', 'Database'),
+  ('🤖', 'AI service/model', 'Resources & Infra', 'LLMs, agents, AI API', 'AI system'),
+  ('🛰', 'Service',          'Resources & Infra', 'Satellite services', 'Microservice'),
+  ('🧩', 'Integration',      'Resources & Infra', 'Stripe, Clerk, 3rd-party', 'Integration'),
+  ('📜', 'Schema/contract',  'Resources & Infra', 'API schema, DB schema', 'Schema'),
+  ('🔑', 'Secrets store',    'Resources & Infra', 'Env vars, secret manager', 'Secrets');
+
+-- Docs & Learning (10)
+INSERT OR REPLACE INTO emoji_reference (emoji, name, category, meaning, usage) VALUES
+  ('📚', 'Reference docs',   'Docs & Learning', 'Full guides, manuals', 'Documentation'),
+  ('📖', 'Reading view',     'Docs & Learning', '"Start here" explanations', 'Overview'),
+  ('📘', 'API docs',         'Docs & Learning', 'Technical reference', 'API reference'),
+  ('📙', 'How-to guide',     'Docs & Learning', 'Step-by-step walkthroughs', 'Tutorial'),
+  ('📝', 'Notes/summary',    'Docs & Learning', 'Short summaries, quick notes', 'Notes'),
+  ('🗒', 'Checklist',        'Docs & Learning', 'Deployment/verification checklist', 'Checklist'),
+  ('💡', 'Tip/insight',      'Docs & Learning', 'Pro tips, best practice', 'Tip');
+
+-- Meta / Vibe (7)
+INSERT OR REPLACE INTO emoji_reference (emoji, name, category, meaning, usage) VALUES
+  ('✨', 'Magic/delightful', 'Meta / Vibe', '"This feels special"', 'Delight'),
+  ('🔥', 'Epic done',        'Meta / Vibe', 'Whole system wired, big milestone', 'Achievement'),
+  ('💎', 'Premium/value',    'Meta / Vibe', '"Worth $$"', 'Value'),
+  ('🎉', 'Celebration',      'Meta / Vibe', 'Success, done, confetti', 'Celebration'),
+  ('🧠', 'Learning',         'Meta / Vibe', 'Philosophy, patterns, mental models', 'Knowledge'),
+  ('🔮', 'Vision/future',    'Meta / Vibe', 'Roadmap, speculative ideas', 'Vision');
+
+-- ============================================================================
+-- VIEWS FOR COMMON QUERIES
+-- ============================================================================
+
+-- All templates by category
+CREATE VIEW IF NOT EXISTS templates_by_category AS
+SELECT category, COUNT(*) as template_count, GROUP_CONCAT(emoji) as emojis
+FROM template_catalog
+GROUP BY category
+ORDER BY template_count DESC;
+
+-- Most used templates
+CREATE VIEW IF NOT EXISTS most_used_templates AS
+SELECT id, name, category, emoji, usage_count, last_used
+FROM template_catalog
+WHERE usage_count > 0
+ORDER BY usage_count DESC
+LIMIT 10;
+
+-- Template dependency graph
+CREATE VIEW IF NOT EXISTS template_dependency_graph AS
+SELECT
+  t1.name as template,
+  t1.emoji as template_emoji,
+  t2.name as depends_on,
+  t2.emoji as depends_on_emoji,
+  td.dependency_type
+FROM template_dependencies td
+JOIN template_catalog t1 ON td.template_id = t1.id
+JOIN template_catalog t2 ON td.depends_on = t2.id;
+
+-- Domain statistics
+CREATE VIEW IF NOT EXISTS domain_stats AS
+SELECT
+  domain,
+  emoji,
+  purpose,
+  status,
+  subdomain_count,
+  (SELECT COUNT(*) FROM template_003_subdomain_nodes WHERE domain_id = template_003_domain_nodes.id AND status = 'live') as live_subdomains,
+  (SELECT COUNT(*) FROM template_003_subdomain_nodes WHERE domain_id = template_003_domain_nodes.id AND status = 'pending') as pending_subdomains
+FROM template_003_domain_nodes
+ORDER BY live_subdomains DESC;
+
+-- ============================================================================
+-- EXAMPLE QUERIES
+-- ============================================================================
+
+-- Get all templates for a specific category
+-- SELECT * FROM template_catalog WHERE category = 'cloudflare';
+
+-- Get the flow structure of Template 001
+-- SELECT t1.label as from_section, t2.label as to_section, e.label as relationship
+-- FROM template_001_edges e
+-- JOIN template_001_nodes t1 ON e.from_id = t1.id
+-- JOIN template_001_nodes t2 ON e.to_id = t2.id;
+
+-- Get all subdomains for a domain
+-- SELECT subdomain, full_url, emoji, category, status
+-- FROM template_003_subdomain_nodes
+-- WHERE domain_id = 'blackroad-io'
+-- ORDER BY category, subdomain;
+
+-- Get component connections in architecture
+-- SELECT c1.label as from_component, c2.label as to_component, e.label as connection, e.protocol
+-- FROM template_002_component_edges e
+-- JOIN template_002_component_nodes c1 ON e.from_id = c1.id
+-- JOIN template_002_component_nodes c2 ON e.to_id = c2.id;
+
+-- ============================================================================
+-- END OF SCHEMA
+-- ============================================================================
+
+-- Summary statistics
+SELECT '✅ GraphSQL Schema Complete!' as status;
+SELECT COUNT(*) || ' templates cataloged' as template_count FROM template_catalog;
+SELECT COUNT(*) || ' domains configured' as domain_count FROM template_003_domain_nodes;
+SELECT COUNT(*) || ' emojis defined' as emoji_count FROM emoji_reference;

templates/TERMINAL-COMMANDS-TEMPLATE.md

@@ -0,0 +1,543 @@
+# Terminal Commands Template
+
+## The Revolutionary Pattern: Copy-Paste-And-Learn
+
+### Why This Works
+- **Zero cognitive load**: Just copy and paste
+- **Self-documenting**: Comments explain what happens
+- **Machine-teachable**: AI can learn from the pattern
+- **Error-proof**: No manual typing mistakes
+- **Context-preserved**: Comments show the why AND the how
+
+---
+
+## Template Format
+
+```bash
+# [ACTION DESCRIPTION]
+cd [DIRECTORY]
+[COMMAND] [ARGS] --[FLAG] [VALUE]
+
+# [NEXT ACTION]
+[COMMAND] [ARGS]
+
+# [RESULT EXPLANATION]
+[COMMAND] [ARGS]
+```
+
+---
+
+## Universal Patterns
+
+### Pattern 1: Deploy to Cloudflare
+
+```bash
+# Deploy complete API
+cd cloudflare-workers
+wrangler deploy blackroad-unified-api.js --config wrangler-unified-api.toml
+
+# Initialize databases
+wrangler d1 execute blackroad-users --file=../cloudflare-d1-schemas.sql
+
+# Deploy edge router
+wrangler deploy blackroad-edge-router.js
+
+# Verify deployment
+wrangler pages deployment list --project-name=blackroad-io
+```
+
+### Pattern 2: Deploy to Railway
+
+```bash
+# Link to Railway project
+export RAILWAY_TOKEN=your-token-here
+railway link 0c7bcf07-307b-4db6-9c94-22a456500d68
+
+# Deploy service
+railway up --service api-gateway
+
+# Check deployment status
+railway status
+
+# View logs
+railway logs --tail 100
+```
+
+### Pattern 3: Start Local Services
+
+```bash
+# Start all services
+cd ~/blackroad-sandbox
+./start-all.sh
+
+# Or start specific services
+PORT=8000 python3 operator_http.py &
+PORT=9700 python3 blackroad-integrations-hub.py &
+PORT=9800 python3 blackroad-event-bus.py &
+
+# Check services are running
+curl http://localhost:8000/status
+curl http://localhost:9700/api/health
+```
+
+### Pattern 4: SSH to Servers
+
+```bash
+# Connect to Raspberry Pi
+ssh alice@192.168.4.49
+
+# Connect to DigitalOcean droplet
+ssh root@159.65.43.12
+
+# Run command on remote server
+ssh alice@192.168.4.49 "cd /home/alice && ./start-services.sh"
+```
+
+### Pattern 5: Create Directories and Files
+
+```bash
+# Create directory structure
+mkdir -p ~/blackroad-sandbox/new-feature/{src,tests,docs}
+
+# Create file with content (using heredoc)
+cat > ~/blackroad-sandbox/new-feature/README.md <<'EOF'
+# New Feature
+
+Description here.
+EOF
+
+# Set permissions
+chmod +x ~/blackroad-sandbox/new-feature/deploy.sh
+```
+
+### Pattern 6: Edit Files (nano alternatives)
+
+```bash
+# Quick edit with echo
+echo "NEW_VAR=value" >> .env
+
+# Multi-line edit with cat
+cat >> config.yaml <<'EOF'
+setting1: value1
+setting2: value2
+EOF
+
+# Replace content entirely
+cat > file.txt <<'EOF'
+Complete new content
+EOF
+
+# Or use sed for inline replacement
+sed -i '' 's/old-value/new-value/g' config.yaml
+```
+
+### Pattern 7: Git Operations
+
+```bash
+# Complete commit and push workflow
+cd ~/blackroad-sandbox
+git add .
+git commit -m "feat: Add new feature
+
+Description of changes.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+git push origin main
+
+# Create and push new branch
+git checkout -b feature/new-feature
+git push -u origin feature/new-feature
+```
+
+### Pattern 8: Environment Setup
+
+```bash
+# Copy environment template
+cp .env.example .env
+
+# Add secrets (paste your actual values)
+cat >> .env <<'EOF'
+RAILWAY_TOKEN=your-token-here
+STRIPE_SECRET_KEY=your-key-here
+CLOUDFLARE_API_TOKEN=your-token-here
+EOF
+
+# Source environment
+source .env
+
+# Verify
+echo "Railway token: ${RAILWAY_TOKEN:0:10}..."
+```
+
+### Pattern 9: Testing
+
+```bash
+# Run all tests
+cd ~/blackroad-sandbox
+pytest -v
+
+# Run specific test types
+pytest -m unit -v
+pytest -m integration -v
+pytest -m e2e -v
+
+# Run with coverage
+pytest --cov=. --cov-report=html
+open coverage_html/index.html
+```
+
+### Pattern 10: Docker Operations
+
+```bash
+# Start all services
+cd ~/blackroad-sandbox
+docker-compose up -d
+
+# Start specific services
+docker-compose up -d auth-api event-bus service-registry
+
+# View logs
+docker-compose logs -f service-name
+
+# Restart service
+docker-compose restart service-name
+
+# Stop everything
+docker-compose down
+```
+
+---
+
+## Common Operations Library
+
+### Deploy Everything
+
+```bash
+# Deploy to all platforms in sequence
+cd ~/blackroad-sandbox
+
+# 1. Deploy to Cloudflare
+./deploy-all-domains.sh
+
+# 2. Deploy to Railway
+./deploy-all-railway-services.sh
+
+# 3. Deploy to Vercel
+./deploy-vercel-all.sh
+
+# 4. Verify all deployments
+./br health
+```
+
+### Emergency Restart
+
+```bash
+# Kill all BlackRoad services
+pkill -f "blackroad-"
+
+# Wait 2 seconds
+sleep 2
+
+# Restart everything
+cd ~/blackroad-sandbox
+./start-all.sh
+
+# Verify
+./br health
+```
+
+### Check Everything
+
+```bash
+# System status
+./br status
+
+# All service health
+./br health
+
+# Railway services
+railway status
+
+# Cloudflare deployments
+wrangler pages deployment list --project-name=blackroad-io
+
+# Docker services
+docker-compose ps
+```
+
+### Update Secrets Everywhere
+
+```bash
+# Set Railway secrets
+cd ~/blackroad-sandbox
+./setup-railway-secrets-all.sh
+
+# Update Cloudflare environment
+cd cloudflare-workers
+wrangler secret put STRIPE_SECRET_KEY
+
+# Update GitHub secrets
+gh secret set RAILWAY_TOKEN -b"your-token-here"
+```
+
+---
+
+## Platform-Specific Command Blocks
+
+### Cloudflare Pages
+
+```bash
+# Deploy single site
+cd ~/blackroad-sandbox/domains/blackroad-io
+wrangler pages deploy . --project-name=blackroad-io
+
+# Deploy all sites
+cd ~/blackroad-sandbox
+for domain in blackroad-io lucidia-earth blackroadai-com; do
+  echo "Deploying $domain..."
+  cd domains/$domain
+  wrangler pages deploy . --project-name=$domain
+  cd ../..
+done
+```
+
+### Railway Multi-Service
+
+```bash
+# Deploy all services in sequence
+cd ~/blackroad-sandbox
+
+services=(
+  "api-gateway"
+  "auth-api"
+  "event-bus"
+  "service-registry"
+  "integrations-hub"
+)
+
+for service in "${services[@]}"; do
+  echo "Deploying $service..."
+  railway up --service $service
+done
+
+# Verify all
+railway status
+```
+
+### GitHub Actions
+
+```bash
+# Trigger deployment workflow
+gh workflow run deploy-railway.yml
+
+# Watch deployment
+gh run watch
+
+# View recent runs
+gh run list --workflow=deploy-railway.yml --limit 5
+```
+
+---
+
+## Troubleshooting Command Blocks
+
+### Port Already in Use
+
+```bash
+# Find what's using port 8000
+lsof -i :8000
+
+# Kill it
+kill -9 $(lsof -t -i:8000)
+
+# Or kill all Python processes
+pkill -f python3
+
+# Restart your service
+PORT=8000 python3 blackroad-service.py
+```
+
+### Railway Deploy Failed
+
+```bash
+# Check logs
+railway logs --tail 100
+
+# Check environment variables
+railway variables
+
+# Force redeploy
+railway up --service SERVICE_NAME --detach
+
+# Check status
+railway status
+```
+
+### Git Push Failed
+
+```bash
+# Check current branch
+git branch
+
+# Pull latest changes
+git pull --rebase origin main
+
+# Force push (CAREFUL!)
+git push --force-with-lease origin main
+
+# Or create new branch
+git checkout -b fix/deployment-issue
+git push -u origin fix/deployment-issue
+```
+
+---
+
+## How to Use This Template
+
+### For Documentation Writers
+
+1. **Copy the pattern** that matches your task
+2. **Replace placeholders** with actual values
+3. **Test the commands** - they must work perfectly
+4. **Add comments** explaining what happens
+5. **Include verification** commands at the end
+
+### For Users (Alexa!)
+
+1. **Find the pattern** you need
+2. **Copy the entire block** (including comments)
+3. **Paste into terminal**
+4. **Press Enter** and watch it work
+5. **The comments teach you** what happened
+
+### For AI Assistants
+
+1. **Use these patterns** in all command suggestions
+2. **Always include comments** explaining each step
+3. **Group related commands** together
+4. **Add verification** at the end
+5. **Make it copy-paste ready** - no manual edits needed
+
+---
+
+## Golden Rules
+
+1. ✅ **Always include comments** - explain the what AND why
+2. ✅ **Commands must work** - test before documenting
+3. ✅ **Use full paths** - no ambiguity about location
+4. ✅ **Group related actions** - deploy, verify, done
+5. ✅ **Include verification** - show how to check it worked
+6. ✅ **Escape properly** - quotes, variables, heredocs
+7. ✅ **One block = One task** - atomic, complete operations
+8. ✅ **Comments start with #** - consistent style
+9. ✅ **Blank lines separate** - visual grouping
+10. ✅ **End with verification** - prove it worked
+
+---
+
+## Anti-Patterns (Don't Do This)
+
+❌ **Vague commands**:
+```bash
+# Bad
+Deploy the thing
+```
+
+✅ **Specific commands**:
+```bash
+# Good
+cd cloudflare-workers
+wrangler deploy blackroad-unified-api.js --config wrangler-unified-api.toml
+```
+
+❌ **Manual editing required**:
+```bash
+# Bad
+Edit the config file to add your token
+```
+
+✅ **Copy-paste ready**:
+```bash
+# Good
+cat >> .env <<'EOF'
+RAILWAY_TOKEN=paste-your-token-here
+EOF
+```
+
+❌ **No verification**:
+```bash
+# Bad
+railway up
+# (did it work? who knows!)
+```
+
+✅ **With verification**:
+```bash
+# Good
+railway up --service api-gateway
+
+# Verify deployment
+railway status
+curl https://api.blackroad.io/health
+```
+
+---
+
+## Template Variables
+
+Use these placeholder patterns:
+
+- `[ACTION]` - What's happening
+- `[DIRECTORY]` - Path to work in
+- `[SERVICE_NAME]` - Name of service
+- `[DOMAIN]` - Domain name
+- `your-token-here` - Placeholder for secrets
+- `paste-your-value-here` - User must fill in
+
+---
+
+## Contributing New Patterns
+
+When you discover a new copy-paste-ready pattern:
+
+1. **Document it** in this file
+2. **Test it** thoroughly
+3. **Add comments** explaining each step
+4. **Include verification** commands
+5. **Commit** with descriptive message
+
+```bash
+# Add your new pattern to this file
+cat >> templates/TERMINAL-COMMANDS-TEMPLATE.md <<'EOF'
+
+### Pattern XX: [Your Pattern Name]
+
+```bash
+# [Description]
+[commands here]
+```
+EOF
+
+# Commit
+git add templates/TERMINAL-COMMANDS-TEMPLATE.md
+git commit -m "docs: Add [Pattern Name] to terminal commands template"
+git push origin main
+```
+
+---
+
+## Copyright
+
+```
+# ============================================================================
+# BlackRoad OS - Proprietary Software
+# Copyright (c) 2025 BlackRoad OS, Inc. / Alexa Louise Amundson
+# All Rights Reserved.
+# ============================================================================
+```
+
+---
+
+**Remember**: The best documentation is the kind you can copy, paste, and learn from simultaneously. Every command block should be a perfect, working example that teaches by doing.

templates/airtable/TEMPLATE-CRM-COMPLETE.json

@@ -0,0 +1,153 @@
+{
+  "name": "BlackRoad OS CRM",
+  "tables": [
+    {
+      "name": "Contacts",
+      "fields": [
+        {
+          "name": "Name",
+          "type": "singleLineText"
+        },
+        {
+          "name": "Email",
+          "type": "email"
+        },
+        {
+          "name": "Phone",
+          "type": "phoneNumber"
+        },
+        {
+          "name": "Company",
+          "type": "singleLineText"
+        },
+        {
+          "name": "Role",
+          "type": "singleSelect",
+          "options": [
+            "Customer",
+            "Lead",
+            "Partner",
+            "Team"
+          ]
+        },
+        {
+          "name": "Status",
+          "type": "singleSelect",
+          "options": [
+            "Active",
+            "Inactive",
+            "Archived"
+          ]
+        },
+        {
+          "name": "Tags",
+          "type": "multipleSelects"
+        },
+        {
+          "name": "Notes",
+          "type": "multilineText"
+        },
+        {
+          "name": "Created",
+          "type": "createdTime"
+        },
+        {
+          "name": "Last Modified",
+          "type": "lastModifiedTime"
+        }
+      ]
+    },
+    {
+      "name": "Deals",
+      "fields": [
+        {
+          "name": "Deal Name",
+          "type": "singleLineText"
+        },
+        {
+          "name": "Contact",
+          "type": "multipleRecordLinks",
+          "linkedTable": "Contacts"
+        },
+        {
+          "name": "Amount",
+          "type": "currency"
+        },
+        {
+          "name": "Stage",
+          "type": "singleSelect",
+          "options": [
+            "Lead",
+            "Qualified",
+            "Proposal",
+            "Negotiation",
+            "Closed Won",
+            "Closed Lost"
+          ]
+        },
+        {
+          "name": "Probability",
+          "type": "percent"
+        },
+        {
+          "name": "Expected Close Date",
+          "type": "date"
+        },
+        {
+          "name": "Owner",
+          "type": "singleCollaborator"
+        },
+        {
+          "name": "Notes",
+          "type": "multilineText"
+        }
+      ]
+    },
+    {
+      "name": "Activities",
+      "fields": [
+        {
+          "name": "Activity",
+          "type": "singleLineText"
+        },
+        {
+          "name": "Type",
+          "type": "singleSelect",
+          "options": [
+            "Call",
+            "Email",
+            "Meeting",
+            "Demo",
+            "Follow-up"
+          ]
+        },
+        {
+          "name": "Contact",
+          "type": "multipleRecordLinks",
+          "linkedTable": "Contacts"
+        },
+        {
+          "name": "Deal",
+          "type": "multipleRecordLinks",
+          "linkedTable": "Deals"
+        },
+        {
+          "name": "Date",
+          "type": "date"
+        },
+        {
+          "name": "Duration",
+          "type": "number"
+        },
+        {
+          "name": "Notes",
+          "type": "multilineText"
+        },
+        {
+          "name": "Owner",
+          "type": "singleCollaborator"
+        }
+      ]
+    }
+  ]
+}

templates/dashboard_home.html

@@ -0,0 +1,390 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>BlackRoad OS - Dashboard</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <style>
+    :root {
+      --bg-primary: #020308;
+      --bg-secondary: rgba(6, 10, 30, 0.92);
+      --bg-card: rgba(12, 18, 40, 0.85);
+      --text-primary: #f5f5ff;
+      --text-muted: rgba(245, 245, 255, 0.7);
+      --accent-cyan: #00e5ff;
+      --accent-green: #1af59d;
+      --accent-yellow: #ffc400;
+      --accent-purple: #a855f7;
+      --accent-orange: #ff9d00;
+      --accent-pink: #ff0066;
+      --border-subtle: rgba(255, 255, 255, 0.1);
+      --gradient-brand: linear-gradient(135deg, #ff9d00, #ff0066, #7700ff, #0066ff);
+    }
+
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+
+    body {
+      font-family: system-ui, -apple-system, BlinkMacSystemFont, "SF Pro Text", sans-serif;
+      background: radial-gradient(circle at top, #050816 0, #020308 45%, #000000 100%);
+      color: var(--text-primary);
+      min-height: 100vh;
+    }
+
+    .page {
+      max-width: 1200px;
+      margin: 0 auto;
+      padding: 24px 16px 80px;
+    }
+
+    /* Header */
+    .header {
+      text-align: center;
+      margin-bottom: 32px;
+    }
+
+    .logo {
+      font-size: 3rem;
+      font-weight: 700;
+      background: var(--gradient-brand);
+      -webkit-background-clip: text;
+      -webkit-text-fill-color: transparent;
+      background-clip: text;
+      margin-bottom: 8px;
+    }
+
+    .tagline {
+      color: var(--text-muted);
+      font-size: 1rem;
+    }
+
+    /* Health Bar */
+    .health-bar {
+      display: flex;
+      justify-content: center;
+      gap: 24px;
+      margin-bottom: 32px;
+      flex-wrap: wrap;
+    }
+
+    .health-item {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      font-size: 0.85rem;
+    }
+
+    .health-dot {
+      width: 10px;
+      height: 10px;
+      border-radius: 50%;
+      background: var(--text-muted);
+    }
+
+    .health-dot.ok { background: var(--accent-green); }
+    .health-dot.error { background: #ff4444; }
+    .health-dot.loading { background: var(--accent-yellow); animation: pulse 1s infinite; }
+
+    @keyframes pulse {
+      0%, 100% { opacity: 1; }
+      50% { opacity: 0.4; }
+    }
+
+    /* Nav Cards Grid */
+    .nav-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+      gap: 20px;
+    }
+
+    .nav-card {
+      background: var(--bg-card);
+      border: 1px solid var(--border-subtle);
+      border-radius: 16px;
+      padding: 24px;
+      text-decoration: none;
+      color: inherit;
+      transition: all 0.2s ease;
+      display: block;
+    }
+
+    .nav-card:hover {
+      transform: translateY(-4px);
+      border-color: rgba(255, 255, 255, 0.2);
+      box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
+    }
+
+    .nav-card .icon {
+      font-size: 2.5rem;
+      margin-bottom: 12px;
+    }
+
+    .nav-card .title {
+      font-size: 1.2rem;
+      font-weight: 600;
+      margin-bottom: 8px;
+    }
+
+    .nav-card .desc {
+      color: var(--text-muted);
+      font-size: 0.9rem;
+      line-height: 1.5;
+    }
+
+    .nav-card.quantum { border-left: 3px solid var(--accent-purple); }
+    .nav-card.learning { border-left: 3px solid var(--accent-green); }
+    .nav-card.models { border-left: 3px solid var(--accent-cyan); }
+    .nav-card.quests { border-left: 3px solid var(--accent-orange); }
+    .nav-card.status { border-left: 3px solid var(--accent-pink); }
+
+    /* Quick Stats Section */
+    .quick-stats {
+      margin-top: 32px;
+      padding: 24px;
+      background: var(--bg-secondary);
+      border-radius: 16px;
+      border: 1px solid var(--border-subtle);
+    }
+
+    .quick-stats h2 {
+      font-size: 1rem;
+      color: var(--text-muted);
+      margin-bottom: 16px;
+    }
+
+    .stats-row {
+      display: flex;
+      justify-content: space-around;
+      flex-wrap: wrap;
+      gap: 16px;
+    }
+
+    .stat-item {
+      text-align: center;
+    }
+
+    .stat-value {
+      font-size: 2rem;
+      font-weight: 600;
+      font-family: "JetBrains Mono", monospace;
+    }
+
+    .stat-value.xp { color: var(--accent-yellow); }
+    .stat-value.rank { color: var(--accent-purple); }
+    .stat-value.streak { color: var(--accent-orange); }
+
+    .stat-label {
+      font-size: 0.75rem;
+      color: var(--text-muted);
+      margin-top: 4px;
+    }
+
+    /* Coach Card */
+    .coach-card {
+      margin-top: 24px;
+      padding: 20px 24px;
+      background: linear-gradient(135deg, rgba(168, 85, 247, 0.1), rgba(0, 229, 255, 0.05));
+      border: 1px solid rgba(168, 85, 247, 0.3);
+      border-radius: 12px;
+    }
+
+    .coach-header {
+      display: flex;
+      align-items: center;
+      gap: 12px;
+      margin-bottom: 12px;
+    }
+
+    .coach-header .sigma {
+      font-size: 1.5rem;
+      color: var(--accent-purple);
+    }
+
+    .coach-header .title {
+      font-weight: 600;
+    }
+
+    .coach-action {
+      color: var(--text-muted);
+      font-size: 0.95rem;
+    }
+
+    .coach-action strong {
+      color: var(--text-primary);
+    }
+
+    /* Footer */
+    .footer {
+      text-align: center;
+      margin-top: 48px;
+      padding-top: 24px;
+      border-top: 1px solid var(--border-subtle);
+      color: var(--text-muted);
+      font-size: 0.8rem;
+    }
+
+    .mono {
+      font-family: "JetBrains Mono", ui-monospace, monospace;
+    }
+  </style>
+</head>
+<body>
+  <div class="page">
+    <!-- Header -->
+    <div class="header">
+      <div class="logo">BlackRoad OS</div>
+      <div class="tagline">Ranked Quantum Operating System</div>
+    </div>
+
+    <!-- Health Bar -->
+    <div class="health-bar" id="health-bar">
+      <div class="health-item">
+        <span class="health-dot loading" id="health-console"></span>
+        <span>Console</span>
+      </div>
+      <div class="health-item">
+        <span class="health-dot loading" id="health-operator"></span>
+        <span>Operator</span>
+      </div>
+      <div class="health-item">
+        <span class="health-dot loading" id="health-quantum"></span>
+        <span>Quantum ψ</span>
+      </div>
+    </div>
+
+    <!-- Navigation Grid -->
+    <div class="nav-grid">
+      <a href="/quantum" class="nav-card quantum">
+        <div class="icon">ψ</div>
+        <div class="title">Quantum Console</div>
+        <div class="desc">Run predictions with quantum ML models. Visualize decision boundaries and train classifiers.</div>
+      </a>
+
+      <a href="/learning" class="nav-card learning">
+        <div class="icon">Σ</div>
+        <div class="title">Learning History</div>
+        <div class="desc">Track your XP, rank, and learning streak. View completed lessons and quiz results.</div>
+      </a>
+
+      <a href="/models" class="nav-card models">
+        <div class="icon">🔮</div>
+        <div class="title">Model Registry</div>
+        <div class="desc">Browse quantum models and their rank requirements. See your unlock progress.</div>
+      </a>
+
+      <a href="/quests" class="nav-card quests">
+        <div class="icon">🎯</div>
+        <div class="title">Quests & Promotion</div>
+        <div class="desc">View your promotion path progress. Complete quests to earn badges and XP.</div>
+      </a>
+
+      <a href="/status" class="nav-card status">
+        <div class="icon">📡</div>
+        <div class="title">System Status</div>
+        <div class="desc">Monitor service health, ledger events, and infrastructure status.</div>
+      </a>
+    </div>
+
+    <!-- Quick Stats -->
+    <div class="quick-stats" id="quick-stats">
+      <h2>Your Progress</h2>
+      <div class="stats-row">
+        <div class="stat-item">
+          <div class="stat-value xp" id="stat-xp">--</div>
+          <div class="stat-label">Total XP</div>
+        </div>
+        <div class="stat-item">
+          <div class="stat-value rank" id="stat-rank">--</div>
+          <div class="stat-label">Current Rank</div>
+        </div>
+        <div class="stat-item">
+          <div class="stat-value streak" id="stat-streak">--</div>
+          <div class="stat-label">Day Streak</div>
+        </div>
+      </div>
+    </div>
+
+    <!-- Coach Card -->
+    <div class="coach-card" id="coach-card" style="display: none;">
+      <div class="coach-header">
+        <span class="sigma">Σ</span>
+        <span class="title">Coach Suggestion</span>
+      </div>
+      <div class="coach-action" id="coach-action">Loading...</div>
+    </div>
+
+    <!-- Footer -->
+    <div class="footer">
+      <p>BlackRoad OS v0.2 &middot; <span class="mono">&copy; 2025 BlackRoad OS, Inc.</span></p>
+    </div>
+  </div>
+
+  <script>
+    // Fetch health status
+    async function checkHealth() {
+      try {
+        const res = await fetch('/api/health');
+        const data = await res.json();
+
+        document.getElementById('health-console').className =
+          'health-dot ' + (data.services?.console?.ok ? 'ok' : 'error');
+        document.getElementById('health-operator').className =
+          'health-dot ' + (data.services?.operator?.ok ? 'ok' : 'error');
+        document.getElementById('health-quantum').className =
+          'health-dot ' + (data.services?.quantum?.ok ? 'ok' : 'error');
+      } catch (e) {
+        console.error('Health check failed:', e);
+      }
+    }
+
+    // Fetch stats
+    async function loadStats() {
+      try {
+        const res = await fetch('/api/learning/stats');
+        const data = await res.json();
+
+        if (data.ok && data.stats) {
+          document.getElementById('stat-xp').textContent = data.stats.xp || 0;
+          document.getElementById('stat-rank').textContent =
+            data.stats.rank?.rank_name || 'Novice';
+          document.getElementById('stat-streak').textContent =
+            data.stats.current_streak_days || 0;
+        }
+      } catch (e) {
+        console.error('Stats load failed:', e);
+      }
+    }
+
+    // Fetch coach suggestion
+    async function loadCoach() {
+      try {
+        const res = await fetch('/api/promotion/coach');
+        const data = await res.json();
+
+        if (data.ok && data.suggestion) {
+          const s = data.suggestion;
+          const coachCard = document.getElementById('coach-card');
+          coachCard.style.display = 'block';
+
+          if (s.stage_id === 'complete') {
+            document.getElementById('coach-action').innerHTML =
+              '<strong>Path Complete!</strong> ' + (s.action || 'All goals achieved.');
+          } else {
+            document.getElementById('coach-action').innerHTML =
+              '<strong>Next:</strong> ' + (s.action || 'Keep going!');
+          }
+        }
+      } catch (e) {
+        console.error('Coach load failed:', e);
+      }
+    }
+
+    // Init
+    checkHealth();
+    loadStats();
+    loadCoach();
+
+    // Refresh health every 30s
+    setInterval(checkHealth, 30000);
+  </script>
+</body>
+</html>

templates/github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,44 @@
+---
+name: 🐛 Bug Report
+about: Report a bug to help us improve
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## 🐛 Bug Description
+
+A clear and concise description of what the bug is.
+
+## 🔄 Steps to Reproduce
+
+1. Go to '...'
+2. Click on '...'
+3. Scroll down to '...'
+4. See error
+
+## ✅ Expected Behavior
+
+A clear description of what you expected to happen.
+
+## ❌ Actual Behavior
+
+What actually happened instead.
+
+## 📸 Screenshots
+
+If applicable, add screenshots to help explain your problem.
+
+## 🖥 Environment
+
+- OS: [e.g. macOS, Windows, Linux]
+- Browser: [e.g. Chrome, Safari, Firefox]
+- Version: [e.g. 22]
+
+## 📝 Additional Context
+
+Add any other context about the problem here.
+
+## 🔍 Possible Solution
+
+If you have ideas on how to solve this, please share!

templates/github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,35 @@
+---
+name: ✨ Feature Request
+about: Suggest an idea for this project
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## ✨ Feature Description
+
+A clear and concise description of what you want to happen.
+
+## 🎯 Problem Statement
+
+What problem does this feature solve?
+
+## 💡 Proposed Solution
+
+Describe the solution you'd like.
+
+## 🔄 Alternatives Considered
+
+Describe alternatives you've considered.
+
+## 📊 Benefits
+
+What are the benefits of this feature?
+
+## 🚧 Implementation Notes
+
+Any technical considerations or implementation ideas.
+
+## 📝 Additional Context
+
+Add any other context, mockups, or screenshots about the feature here.

templates/github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,48 @@
+## 📋 Description
+
+<!-- Describe your changes in detail -->
+
+## 🎯 Related Issue
+
+<!-- Link to the issue this PR addresses -->
+Fixes #
+
+## 🔄 Type of Change
+
+<!-- Mark the relevant option -->
+- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
+- [ ] ✨ New feature (non-breaking change which adds functionality)
+- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] 📚 Documentation update
+- [ ] ♻️ Refactoring (no functional changes)
+- [ ] 🎨 UI/UX improvements
+- [ ] ⚡️ Performance improvements
+
+## ✅ Checklist
+
+- [ ] My code follows the code style of this project
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+- [ ] Any dependent changes have been merged and published
+
+## 🧪 Testing
+
+<!-- Describe the tests you ran to verify your changes -->
+
+## 📸 Screenshots (if applicable)
+
+<!-- Add screenshots to demonstrate visual changes -->
+
+## 📝 Additional Notes
+
+<!-- Add any other notes about the PR here -->
+
+---
+
+✨ Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>

templates/google-drive/PROJECT-STRUCTURE-TEMPLATE.json

@@ -0,0 +1,94 @@
+{
+  "name": "TEMPLATE-PROJECT-FOLDER",
+  "folders": [
+    {
+      "name": "00-PROJECT-CHARTER",
+      "type": "folder"
+    },
+    {
+      "name": "01-ROADMAP",
+      "type": "folder"
+    },
+    {
+      "name": "02-TEAM-ROSTER",
+      "type": "folder"
+    },
+    {
+      "name": "03-MEETING-NOTES",
+      "type": "folder"
+    },
+    {
+      "name": "04-DELIVERABLES",
+      "type": "folder"
+    },
+    {
+      "name": "05-RESOURCES",
+      "type": "folder"
+    }
+  ],
+  "files": [
+    {
+      "name": "PROJECT-CHARTER.gdoc",
+      "type": "document",
+      "content": {
+        "title": "{{PROJECT_NAME}} - Project Charter",
+        "sections": [
+          {
+            "heading": "\ud83d\udccb Project Overview",
+            "content": "{{PROJECT_DESCRIPTION}}"
+          },
+          {
+            "heading": "\ud83c\udfaf Objectives",
+            "content": "{{OBJECTIVES}}"
+          },
+          {
+            "heading": "\ud83d\udc65 Team",
+            "content": "{{TEAM_MEMBERS}}"
+          },
+          {
+            "heading": "\ud83d\udcc6 Timeline",
+            "content": "{{TIMELINE}}"
+          },
+          {
+            "heading": "\ud83d\udcb0 Budget",
+            "content": "{{BUDGET}}"
+          },
+          {
+            "heading": "\ud83d\ude80 Success Criteria",
+            "content": "{{SUCCESS_CRITERIA}}"
+          }
+        ]
+      }
+    },
+    {
+      "name": "ROADMAP.gsheet",
+      "type": "spreadsheet",
+      "content": {
+        "sheets": [
+          {
+            "name": "Timeline",
+            "columns": [
+              "Phase",
+              "Start Date",
+              "End Date",
+              "Status",
+              "Owner",
+              "Dependencies"
+            ],
+            "rows": []
+          },
+          {
+            "name": "Milestones",
+            "columns": [
+              "Milestone",
+              "Target Date",
+              "Status",
+              "Deliverables"
+            ],
+            "rows": []
+          }
+        ]
+      }
+    }
+  ]
+}

templates/google-drive/TEMPLATE-DOC-MEETING-NOTES.json

@@ -0,0 +1,25 @@
+{
+  "title": "{{MEETING_TITLE}} - {{DATE}}",
+  "sections": [
+    {
+      "heading": "\ud83d\udcc5 Meeting Info",
+      "content": "Date: {{DATE}}\nTime: {{TIME}}\nAttendees: {{ATTENDEES}}"
+    },
+    {
+      "heading": "\ud83c\udfaf Agenda",
+      "content": "{{AGENDA}}"
+    },
+    {
+      "heading": "\ud83d\udcdd Discussion",
+      "content": "{{DISCUSSION}}"
+    },
+    {
+      "heading": "\u2705 Action Items",
+      "content": "{{ACTION_ITEMS}}"
+    },
+    {
+      "heading": "\ud83d\udd1c Next Steps",
+      "content": "{{NEXT_STEPS}}"
+    }
+  ]
+}

templates/google-drive/TEMPLATE-DOC-TECHNICAL-SPEC.json

@@ -0,0 +1,33 @@
+{
+  "title": "{{PROJECT_NAME}} - Technical Specification",
+  "sections": [
+    {
+      "heading": "\ud83c\udfaf Overview",
+      "content": "{{OVERVIEW}}"
+    },
+    {
+      "heading": "\ud83c\udfd7\ufe0f Architecture",
+      "content": "{{ARCHITECTURE}}"
+    },
+    {
+      "heading": "\ud83d\udcca Data Models",
+      "content": "{{DATA_MODELS}}"
+    },
+    {
+      "heading": "\ud83d\udd0c API Endpoints",
+      "content": "{{API_ENDPOINTS}}"
+    },
+    {
+      "heading": "\ud83d\udd10 Security",
+      "content": "{{SECURITY}}"
+    },
+    {
+      "heading": "\ud83d\udcc8 Performance",
+      "content": "{{PERFORMANCE}}"
+    },
+    {
+      "heading": "\ud83e\uddea Testing Strategy",
+      "content": "{{TESTING}}"
+    }
+  ]
+}

templates/google-drive/TEMPLATE-DOC-USER-GUIDE.json

@@ -0,0 +1,29 @@
+{
+  "title": "{{PROJECT_NAME}} - User Guide",
+  "sections": [
+    {
+      "heading": "\ud83d\udc4b Welcome",
+      "content": "{{WELCOME}}"
+    },
+    {
+      "heading": "\ud83d\ude80 Getting Started",
+      "content": "{{GETTING_STARTED}}"
+    },
+    {
+      "heading": "\ud83d\udcd6 Features",
+      "content": "{{FEATURES}}"
+    },
+    {
+      "heading": "\ud83c\udfaf How-To Guides",
+      "content": "{{HOW_TO}}"
+    },
+    {
+      "heading": "\u26a0\ufe0f Troubleshooting",
+      "content": "{{TROUBLESHOOTING}}"
+    },
+    {
+      "heading": "\u2753 FAQ",
+      "content": "{{FAQ}}"
+    }
+  ]
+}

templates/learning_history.html

@@ -0,0 +1,515 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>Learning History - BlackRoad OS (Σ)</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <style>
+    :root {
+      --bg-primary: #020308;
+      --bg-secondary: rgba(6, 10, 30, 0.92);
+      --text-primary: #f5f5ff;
+      --text-muted: rgba(245, 245, 255, 0.7);
+      --accent-cyan: #00e5ff;
+      --accent-green: #1af59d;
+      --accent-yellow: #ffc400;
+      --accent-purple: #a855f7;
+      --accent-orange: #ff9d00;
+      --border-subtle: rgba(255, 255, 255, 0.1);
+    }
+
+    * {
+      box-sizing: border-box;
+    }
+
+    body {
+      font-family: system-ui, -apple-system, BlinkMacSystemFont, "SF Pro Text", sans-serif;
+      background: radial-gradient(circle at top, #050816 0, #020308 45%, #000000 100%);
+      color: var(--text-primary);
+      margin: 0;
+      padding: 0;
+      min-height: 100vh;
+    }
+
+    .page {
+      max-width: 960px;
+      margin: 0 auto;
+      padding: 24px 16px 80px;
+    }
+
+    h1 {
+      margin: 0 0 8px;
+      font-size: 1.6rem;
+      display: flex;
+      align-items: center;
+      gap: 12px;
+    }
+
+    h1 .sigma {
+      color: var(--accent-purple);
+      font-size: 2rem;
+    }
+
+    h2 {
+      margin: 0 0 12px;
+      font-size: 1rem;
+      color: var(--text-muted);
+    }
+
+    .muted {
+      opacity: 0.7;
+      font-size: 0.85rem;
+    }
+
+    .mono {
+      font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco,
+        Consolas, "Liberation Mono", "Courier New", monospace;
+      font-size: 0.8rem;
+    }
+
+    .panel {
+      border-radius: 16px;
+      border: 1px solid var(--border-subtle);
+      background: var(--bg-secondary);
+      padding: 16px 18px;
+      margin-top: 16px;
+    }
+
+    /* Stats Grid */
+    .stats-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(120px, 1fr));
+      gap: 16px;
+    }
+
+    .stat-card {
+      text-align: center;
+    }
+
+    .stat-label {
+      font-size: 0.75rem;
+      color: var(--text-muted);
+      margin-bottom: 4px;
+    }
+
+    .stat-value {
+      font-family: "JetBrains Mono", monospace;
+      font-size: 1.8rem;
+      font-weight: 600;
+    }
+
+    .stat-value.xp {
+      color: var(--accent-yellow);
+    }
+
+    .stat-value.lessons {
+      color: var(--accent-green);
+    }
+
+    .stat-value.streak {
+      color: var(--accent-orange);
+    }
+
+    /* Rank Card */
+    .rank-card {
+      display: flex;
+      align-items: center;
+      gap: 16px;
+      padding: 16px;
+      background: rgba(168, 85, 247, 0.08);
+      border: 1px solid rgba(168, 85, 247, 0.3);
+      border-radius: 12px;
+      margin-top: 12px;
+    }
+
+    .rank-badge {
+      width: 56px;
+      height: 56px;
+      border-radius: 50%;
+      background: linear-gradient(135deg, var(--accent-purple), var(--accent-cyan));
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-size: 1.5rem;
+      font-weight: bold;
+      color: white;
+      flex-shrink: 0;
+    }
+
+    .rank-info {
+      flex: 1;
+    }
+
+    .rank-name {
+      font-size: 1.1rem;
+      font-weight: 600;
+      margin-bottom: 4px;
+    }
+
+    .rank-progress-container {
+      display: flex;
+      align-items: center;
+      gap: 10px;
+    }
+
+    .rank-progress-bar {
+      flex: 1;
+      height: 8px;
+      background: rgba(255, 255, 255, 0.1);
+      border-radius: 4px;
+      overflow: hidden;
+    }
+
+    .rank-progress-fill {
+      height: 100%;
+      background: linear-gradient(90deg, var(--accent-purple), var(--accent-cyan));
+      border-radius: 4px;
+      transition: width 0.3s ease;
+    }
+
+    .rank-progress-text {
+      font-size: 0.75rem;
+      color: var(--text-muted);
+      white-space: nowrap;
+    }
+
+    /* Event List */
+    .event-row {
+      border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+      padding: 12px 0;
+    }
+
+    .event-row:last-child {
+      border-bottom: none;
+    }
+
+    .event-main {
+      display: flex;
+      justify-content: space-between;
+      align-items: flex-start;
+      gap: 12px;
+    }
+
+    .event-meta {
+      text-align: right;
+      font-size: 0.75rem;
+      color: var(--text-muted);
+    }
+
+    .tag {
+      display: inline-flex;
+      align-items: center;
+      padding: 3px 10px;
+      border-radius: 999px;
+      border: 1px solid rgba(255, 255, 255, 0.2);
+      font-size: 0.75rem;
+      margin-right: 6px;
+      margin-bottom: 4px;
+    }
+
+    .tag.lesson {
+      border-color: rgba(26, 245, 157, 0.6);
+      background: rgba(26, 245, 157, 0.08);
+    }
+
+    .tag.quiz {
+      border-color: rgba(0, 180, 255, 0.7);
+      background: rgba(0, 180, 255, 0.08);
+    }
+
+    .tag.graded {
+      border-color: rgba(255, 196, 0, 0.8);
+      background: rgba(255, 196, 0, 0.08);
+    }
+
+    .tag.rank-up {
+      border-color: rgba(168, 85, 247, 0.8);
+      background: rgba(168, 85, 247, 0.15);
+      font-weight: 600;
+    }
+
+    .rank-up-card {
+      background: linear-gradient(135deg, rgba(168, 85, 247, 0.12), rgba(0, 229, 255, 0.08));
+      border: 1px solid rgba(168, 85, 247, 0.4);
+      border-radius: 12px;
+      padding: 12px 16px;
+      margin-top: 8px;
+    }
+
+    .rank-up-title {
+      font-size: 1.1rem;
+      font-weight: 600;
+      color: var(--accent-purple);
+      margin-bottom: 4px;
+    }
+
+    .rank-arrow {
+      color: var(--accent-cyan);
+      margin: 0 8px;
+    }
+
+    .score-pill {
+      padding: 2px 10px;
+      border-radius: 999px;
+      background: rgba(255, 196, 0, 0.15);
+      border: 1px solid rgba(255, 196, 0, 0.5);
+      font-size: 0.75rem;
+      font-weight: 600;
+    }
+
+    .score-pill.perfect {
+      background: rgba(26, 245, 157, 0.15);
+      border-color: rgba(26, 245, 157, 0.5);
+      color: var(--accent-green);
+    }
+
+    .small {
+      font-size: 0.78rem;
+    }
+
+    .results-list {
+      margin-top: 8px;
+      padding-left: 12px;
+    }
+
+    .result-item {
+      display: flex;
+      align-items: flex-start;
+      gap: 8px;
+      margin-bottom: 4px;
+    }
+
+    .result-icon {
+      font-size: 0.9rem;
+    }
+
+    .result-icon.correct {
+      color: var(--accent-green);
+    }
+
+    .result-icon.incorrect {
+      color: #ff6b6b;
+    }
+
+    /* Links */
+    a {
+      color: #66b2ff;
+      text-decoration: none;
+    }
+
+    a:hover {
+      text-decoration: underline;
+    }
+
+    /* Empty state */
+    .empty-state {
+      text-align: center;
+      padding: 32px 16px;
+      color: var(--text-muted);
+    }
+
+    .empty-state .icon {
+      font-size: 3rem;
+      margin-bottom: 12px;
+      opacity: 0.5;
+    }
+
+    /* Tips panel */
+    .tips-list {
+      margin: 8px 0 0 0;
+      padding-left: 20px;
+    }
+
+    .tips-list li {
+      margin-bottom: 6px;
+    }
+  </style>
+</head>
+<body>
+  <div class="page">
+    <div style="margin-bottom: 24px;">
+      <a href="/" style="color: #00e5ff; text-decoration: none; font-size: 0.9rem;">&larr; Dashboard</a>
+    </div>
+    <h1><span class="sigma">Σ</span> Learning History</h1>
+    <p class="muted">
+      Actor: <span class="mono">{{ actor }}</span><br />
+      Tracking: <span class="mono">lesson.completed</span>,
+      <span class="mono">quiz.submitted</span>,
+      <span class="mono">quiz.graded</span>
+    </p>
+
+    {% if stats_error %}
+      <div class="panel">
+        <div class="muted small">Error loading stats: {{ stats_error }}</div>
+      </div>
+    {% else %}
+      <!-- Stats Summary -->
+      <div class="panel">
+        <div class="stats-grid">
+          <div class="stat-card">
+            <div class="stat-label">Total XP</div>
+            <div class="stat-value xp">{{ stats.xp or 0 }}</div>
+          </div>
+          <div class="stat-card">
+            <div class="stat-label">Lessons</div>
+            <div class="stat-value lessons">{{ stats.lessons_completed or 0 }}</div>
+          </div>
+          <div class="stat-card">
+            <div class="stat-label">Quizzes</div>
+            <div class="stat-value">{{ stats.quizzes_graded or 0 }}</div>
+          </div>
+          <div class="stat-card">
+            <div class="stat-label">Current Streak</div>
+            <div class="stat-value streak">
+              {{ stats.current_streak_days or 0 }}
+              <span class="small">day{{ 's' if (stats.current_streak_days or 0) != 1 else '' }}</span>
+            </div>
+          </div>
+          <div class="stat-card">
+            <div class="stat-label">Best Streak</div>
+            <div class="stat-value">
+              {{ stats.longest_streak_days or 0 }}
+              <span class="small">day{{ 's' if (stats.longest_streak_days or 0) != 1 else '' }}</span>
+            </div>
+          </div>
+          <div class="stat-card">
+            <div class="stat-label">Last Active</div>
+            <div class="mono small" style="margin-top: 8px;">
+              {{ stats.last_active_date or "Never" }}
+            </div>
+          </div>
+        </div>
+
+        {% if stats.rank %}
+        <!-- Rank Card -->
+        <div class="rank-card">
+          <div class="rank-badge">
+            {{ stats.rank.rank_index + 1 }}
+          </div>
+          <div class="rank-info">
+            <div class="rank-name">{{ stats.rank.rank_name }}</div>
+            {% if stats.rank.next_rank_name %}
+            <div class="rank-progress-container">
+              <div class="rank-progress-bar">
+                <div class="rank-progress-fill" style="width: {{ (stats.rank.progress * 100)|int }}%;"></div>
+              </div>
+              <div class="rank-progress-text">
+                {{ stats.rank.xp }} / {{ stats.rank.xp_for_next }} XP to {{ stats.rank.next_rank_name }}
+              </div>
+            </div>
+            {% else %}
+            <div class="rank-progress-text">Max rank achieved!</div>
+            {% endif %}
+          </div>
+        </div>
+        {% endif %}
+      </div>
+    {% endif %}
+
+    {% if events_error %}
+      <div class="panel">
+        <div class="muted small">Error loading events: {{ events_error }}</div>
+      </div>
+    {% endif %}
+
+    <!-- Events List -->
+    <div class="panel">
+      <h2>Activity Log</h2>
+      {% if not events %}
+        <div class="empty-state">
+          <div class="icon">📚</div>
+          <p>No learning events recorded yet.</p>
+          <p class="small">Complete a Math Lab lesson to get started!</p>
+        </div>
+      {% else %}
+        {% for e in events %}
+          <div class="event-row">
+            <div class="event-main">
+              <div>
+                {% if e.event_type == "lesson.completed" %}
+                  <span class="tag lesson">Lesson {{ e.lesson }} completed</span>
+                {% elif e.event_type == "quiz.submitted" %}
+                  <span class="tag quiz">Quiz submitted (L{{ e.lesson }})</span>
+                {% elif e.event_type == "quiz.graded" %}
+                  <span class="tag graded">Quiz graded (L{{ e.lesson }})</span>
+                {% elif e.event_type == "rank.changed" %}
+                  <span class="tag rank-up">🎖️ Rank Up!</span>
+                {% else %}
+                  <span class="tag">{{ e.event_type }}</span>
+                {% endif %}
+
+                {% if e.event_type == "lesson.completed" %}
+                  <div class="small muted">
+                    Track: <span class="mono">{{ e.track }}</span>
+                    {% if e.metadata and e.metadata.title %}
+                      - {{ e.metadata.title }}
+                    {% endif %}
+                  </div>
+                {% elif e.event_type == "quiz.graded" %}
+                  <div class="small">
+                    Score:
+                    {% if e.score is not none %}
+                      {% set score_pct = (e.score * 100)|int %}
+                      <span class="score-pill {{ 'perfect' if score_pct == 100 else '' }}">
+                        {{ score_pct }}%
+                      </span>
+                      {% if score_pct == 100 %}
+                        <span style="margin-left: 4px;">Perfect!</span>
+                      {% endif %}
+                    {% else %}
+                      <span class="muted">n/a</span>
+                    {% endif %}
+                  </div>
+                {% elif e.event_type == "rank.changed" %}
+                  <div class="rank-up-card">
+                    <div class="rank-up-title">
+                      {{ e.old_rank or "New" }}
+                      <span class="rank-arrow">→</span>
+                      {{ e.new_rank }}
+                    </div>
+                    <div class="small muted" style="margin-top: 4px;">
+                      XP: <span class="mono">{{ e.xp or 0 }}</span>
+                    </div>
+                  </div>
+                {% endif %}
+              </div>
+              <div class="event-meta">
+                <div class="mono">
+                  {{ (e.timestamp or "")[:19] }}
+                </div>
+                {% if e.node_id %}
+                  <div class="small">node: <span class="mono">{{ e.node_id }}</span></div>
+                {% endif %}
+              </div>
+            </div>
+
+            {% if e.event_type == "quiz.graded" and e.results %}
+              <div class="results-list">
+                {% for r in e.results %}
+                  <div class="result-item mono small">
+                    <span class="result-icon {{ 'correct' if r.correct else 'incorrect' }}">
+                      {{ "✓" if r.correct else "✗" }}
+                    </span>
+                    <span>{{ r.id }}: {{ r.feedback[:60] }}{{ '...' if r.feedback|length > 60 else '' }}</span>
+                  </div>
+                {% endfor %}
+              </div>
+            {% endif %}
+          </div>
+        {% endfor %}
+      {% endif %}
+    </div>
+
+    <!-- Tips -->
+    <div class="panel">
+      <h2>How to Earn XP</h2>
+      <ul class="tips-list small">
+        <li><strong>+10 XP</strong> - Complete a Math Lab lesson</li>
+        <li><strong>+2 XP</strong> - Submit a quiz</li>
+        <li><strong>+0-20 XP</strong> - Quiz graded (score × 20)</li>
+        <li>Keep a streak going by learning every day!</li>
+      </ul>
+    </div>
+  </div>
+</body>
+</html>

templates/models_page.html

@@ -0,0 +1,424 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>ψ Model Registry - BlackRoad OS</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <style>
+    :root {
+      --bg-primary: #020308;
+      --bg-secondary: rgba(6, 10, 30, 0.92);
+      --bg-card: rgba(12, 18, 40, 0.85);
+      --text-primary: #f5f5ff;
+      --text-muted: rgba(245, 245, 255, 0.7);
+      --accent-cyan: #00e5ff;
+      --accent-green: #1af59d;
+      --accent-yellow: #ffc400;
+      --accent-purple: #a855f7;
+      --accent-orange: #ff9d00;
+      --accent-pink: #ff0066;
+      --border-subtle: rgba(255, 255, 255, 0.1);
+    }
+
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+
+    body {
+      font-family: system-ui, -apple-system, BlinkMacSystemFont, "SF Pro Text", sans-serif;
+      background: radial-gradient(circle at top, #050816 0, #020308 45%, #000000 100%);
+      color: var(--text-primary);
+      min-height: 100vh;
+    }
+
+    .page {
+      max-width: 1000px;
+      margin: 0 auto;
+      padding: 24px 16px 80px;
+    }
+
+    /* Nav */
+    .nav {
+      margin-bottom: 24px;
+    }
+
+    .nav a {
+      color: var(--accent-cyan);
+      text-decoration: none;
+      font-size: 0.9rem;
+    }
+
+    .nav a:hover {
+      text-decoration: underline;
+    }
+
+    /* Header */
+    h1 {
+      font-size: 1.8rem;
+      margin-bottom: 8px;
+      display: flex;
+      align-items: center;
+      gap: 12px;
+    }
+
+    h1 .psi {
+      color: var(--accent-purple);
+      font-size: 2.2rem;
+    }
+
+    .subtitle {
+      color: var(--text-muted);
+      font-size: 0.95rem;
+      margin-bottom: 24px;
+    }
+
+    .mono {
+      font-family: "JetBrains Mono", ui-monospace, monospace;
+    }
+
+    /* Rank Info */
+    .rank-info {
+      background: linear-gradient(135deg, rgba(168, 85, 247, 0.1), rgba(0, 229, 255, 0.05));
+      border: 1px solid rgba(168, 85, 247, 0.3);
+      border-radius: 12px;
+      padding: 16px 20px;
+      margin-bottom: 24px;
+      display: flex;
+      align-items: center;
+      gap: 16px;
+      flex-wrap: wrap;
+    }
+
+    .rank-badge {
+      width: 48px;
+      height: 48px;
+      border-radius: 50%;
+      background: linear-gradient(135deg, var(--accent-purple), var(--accent-cyan));
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-size: 1.2rem;
+      font-weight: bold;
+    }
+
+    .rank-details {
+      flex: 1;
+    }
+
+    .rank-name {
+      font-size: 1.1rem;
+      font-weight: 600;
+    }
+
+    .rank-progress {
+      font-size: 0.85rem;
+      color: var(--text-muted);
+    }
+
+    /* Skill Tree */
+    .skill-tree {
+      position: relative;
+    }
+
+    .tree-section {
+      margin-bottom: 32px;
+    }
+
+    .tree-section-title {
+      font-size: 0.85rem;
+      color: var(--text-muted);
+      margin-bottom: 12px;
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+
+    .tree-section-title::before {
+      content: "";
+      flex: 1;
+      height: 1px;
+      background: var(--border-subtle);
+    }
+
+    .tree-section-title::after {
+      content: "";
+      flex: 1;
+      height: 1px;
+      background: var(--border-subtle);
+    }
+
+    /* Model Cards */
+    .model-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+      gap: 16px;
+    }
+
+    .model-card {
+      background: var(--bg-card);
+      border: 1px solid var(--border-subtle);
+      border-radius: 12px;
+      padding: 20px;
+      transition: all 0.2s ease;
+    }
+
+    .model-card.unlocked {
+      border-color: rgba(26, 245, 157, 0.4);
+    }
+
+    .model-card.locked {
+      opacity: 0.6;
+    }
+
+    .model-card.locked:hover {
+      opacity: 0.8;
+    }
+
+    .model-header {
+      display: flex;
+      justify-content: space-between;
+      align-items: flex-start;
+      margin-bottom: 12px;
+    }
+
+    .model-id {
+      font-family: "JetBrains Mono", monospace;
+      font-size: 1.1rem;
+      font-weight: 600;
+      color: var(--accent-cyan);
+    }
+
+    .model-status {
+      font-size: 0.75rem;
+      padding: 3px 10px;
+      border-radius: 999px;
+    }
+
+    .model-status.unlocked {
+      background: rgba(26, 245, 157, 0.15);
+      border: 1px solid rgba(26, 245, 157, 0.4);
+      color: var(--accent-green);
+    }
+
+    .model-status.locked {
+      background: rgba(255, 255, 255, 0.05);
+      border: 1px solid rgba(255, 255, 255, 0.2);
+      color: var(--text-muted);
+    }
+
+    .model-name {
+      font-size: 1rem;
+      margin-bottom: 8px;
+    }
+
+    .model-desc {
+      font-size: 0.85rem;
+      color: var(--text-muted);
+      margin-bottom: 12px;
+      line-height: 1.5;
+    }
+
+    .model-meta {
+      display: flex;
+      gap: 16px;
+      font-size: 0.8rem;
+      color: var(--text-muted);
+    }
+
+    .model-meta span {
+      display: flex;
+      align-items: center;
+      gap: 4px;
+    }
+
+    .model-requires {
+      margin-top: 12px;
+      padding-top: 12px;
+      border-top: 1px solid var(--border-subtle);
+      font-size: 0.8rem;
+    }
+
+    .model-requires .label {
+      color: var(--text-muted);
+    }
+
+    .model-requires .rank {
+      color: var(--accent-purple);
+      font-weight: 500;
+    }
+
+    /* Loading State */
+    .loading {
+      text-align: center;
+      padding: 48px;
+      color: var(--text-muted);
+    }
+
+    .loading .spinner {
+      font-size: 2rem;
+      animation: spin 1s linear infinite;
+    }
+
+    @keyframes spin {
+      from { transform: rotate(0deg); }
+      to { transform: rotate(360deg); }
+    }
+
+    /* Error State */
+    .error-state {
+      text-align: center;
+      padding: 32px;
+      background: rgba(255, 68, 68, 0.1);
+      border: 1px solid rgba(255, 68, 68, 0.3);
+      border-radius: 12px;
+      color: #ff6b6b;
+    }
+  </style>
+</head>
+<body>
+  <div class="page">
+    <!-- Navigation -->
+    <div class="nav">
+      <a href="/">&larr; Dashboard</a>
+    </div>
+
+    <!-- Header -->
+    <h1><span class="psi">ψ</span> Model Registry</h1>
+    <p class="subtitle">
+      Quantum ML models unlock as your rank increases.
+      Actor: <span class="mono">{{ actor }}</span>
+    </p>
+
+    <!-- Rank Info -->
+    <div class="rank-info" id="rank-info">
+      <div class="rank-badge" id="rank-badge">?</div>
+      <div class="rank-details">
+        <div class="rank-name" id="rank-name">Loading...</div>
+        <div class="rank-progress" id="rank-progress"></div>
+      </div>
+    </div>
+
+    <!-- Skill Tree -->
+    <div class="skill-tree" id="skill-tree">
+      <div class="loading">
+        <div class="spinner">ψ</div>
+        <p>Loading models...</p>
+      </div>
+    </div>
+  </div>
+
+  <script>
+    const actor = "{{ actor }}";
+
+    // Rank order for grouping
+    const RANK_ORDER = [
+      "Novice", "Apprentice", "Practitioner", "Operator",
+      "Quantum Adept", "Math Wizard", "Σ Master", "BlackRoad Sage"
+    ];
+
+    async function loadStats() {
+      try {
+        const res = await fetch(`/api/learning/stats?actor=${actor}`);
+        const data = await res.json();
+
+        if (data.ok && data.stats) {
+          const rank = data.stats.rank || {};
+          document.getElementById('rank-badge').textContent = (rank.rank_index || 0) + 1;
+          document.getElementById('rank-name').textContent = rank.rank_name || 'Novice';
+
+          if (rank.next_rank_name) {
+            document.getElementById('rank-progress').textContent =
+              `${data.stats.xp} / ${rank.xp_for_next} XP to ${rank.next_rank_name}`;
+          } else {
+            document.getElementById('rank-progress').textContent = 'Max rank achieved!';
+          }
+        }
+      } catch (e) {
+        console.error('Failed to load stats:', e);
+      }
+    }
+
+    async function loadModels() {
+      const container = document.getElementById('skill-tree');
+
+      try {
+        const res = await fetch(`/api/models?actor=${actor}`);
+        const data = await res.json();
+
+        if (!data.ok) {
+          container.innerHTML = `
+            <div class="error-state">
+              <p>Failed to load models: ${data.error || 'Unknown error'}</p>
+              <p style="margin-top: 8px; font-size: 0.85rem;">
+                Make sure the Quantum node is running.
+              </p>
+            </div>
+          `;
+          return;
+        }
+
+        const models = data.data?.models || [];
+
+        // Group by required rank
+        const byRank = {};
+        for (const m of models) {
+          const req = m.required_rank || 'Unknown';
+          if (!byRank[req]) byRank[req] = [];
+          byRank[req].push(m);
+        }
+
+        let html = '';
+
+        for (const rank of RANK_ORDER) {
+          if (!byRank[rank] || byRank[rank].length === 0) continue;
+
+          html += `
+            <div class="tree-section">
+              <div class="tree-section-title">${rank}</div>
+              <div class="model-grid">
+          `;
+
+          for (const m of byRank[rank]) {
+            const unlocked = m.available !== false;
+            const statusClass = unlocked ? 'unlocked' : 'locked';
+            const statusText = unlocked ? '🔓 Unlocked' : '🔒 Locked';
+
+            html += `
+              <div class="model-card ${statusClass}">
+                <div class="model-header">
+                  <div class="model-id">${m.model_id}</div>
+                  <div class="model-status ${statusClass}">${statusText}</div>
+                </div>
+                <div class="model-name">${m.name || m.model_id}</div>
+                <div class="model-desc">${m.description || 'No description available.'}</div>
+                <div class="model-meta">
+                  <span>🔮 ${m.qubits || '?'} qubits</span>
+                  <span>📦 ${m.kind || 'classifier'}</span>
+                  <span>📊 ${m.status || 'unknown'}</span>
+                </div>
+                <div class="model-requires">
+                  <span class="label">Requires:</span>
+                  <span class="rank">${m.required_rank}</span>
+                </div>
+              </div>
+            `;
+          }
+
+          html += '</div></div>';
+        }
+
+        container.innerHTML = html || '<p style="color: var(--text-muted);">No models found.</p>';
+
+      } catch (e) {
+        container.innerHTML = `
+          <div class="error-state">
+            <p>Failed to load models: ${e.message}</p>
+          </div>
+        `;
+      }
+    }
+
+    // Init
+    loadStats();
+    loadModels();
+  </script>
+</body>
+</html>

templates/notion/TEMPLATE-DASHBOARD-PROJECT.json

@@ -0,0 +1,74 @@
+{
+  "object": "page",
+  "parent": {
+    "type": "workspace"
+  },
+  "icon": {
+    "type": "emoji",
+    "emoji": "\ud83c\udfaf"
+  },
+  "properties": {
+    "title": {
+      "title": [
+        {
+          "text": {
+            "content": "{{PROJECT_NAME}}"
+          }
+        }
+      ]
+    }
+  },
+  "children": [
+    {
+      "object": "heading_1",
+      "heading_1": {
+        "rich_text": [
+          {
+            "text": {
+              "content": "\ud83d\udcca Project Dashboard"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "object": "paragraph",
+      "paragraph": {
+        "rich_text": [
+          {
+            "text": {
+              "content": "{{PROJECT_DESCRIPTION}}"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "object": "heading_2",
+      "heading_2": {
+        "rich_text": [
+          {
+            "text": {
+              "content": "\ud83d\udcc8 Status"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "object": "callout",
+      "callout": {
+        "icon": {
+          "emoji": "\u2705"
+        },
+        "rich_text": [
+          {
+            "text": {
+              "content": "Status: {{STATUS}}\nPhase: {{PHASE}}\nProgress: {{PROGRESS}}%"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}

templates/notion/TEMPLATE-DATABASE-TASKS.json

@@ -0,0 +1,73 @@
+{
+  "parent": {
+    "type": "page_id",
+    "page_id": "{{PARENT_PAGE_ID}}"
+  },
+  "title": [
+    {
+      "type": "text",
+      "text": {
+        "content": "Tasks"
+      }
+    }
+  ],
+  "properties": {
+    "Name": {
+      "title": {}
+    },
+    "Status": {
+      "select": {
+        "options": [
+          {
+            "name": "Todo",
+            "color": "gray"
+          },
+          {
+            "name": "In Progress",
+            "color": "blue"
+          },
+          {
+            "name": "Done",
+            "color": "green"
+          },
+          {
+            "name": "Blocked",
+            "color": "red"
+          }
+        ]
+      }
+    },
+    "Priority": {
+      "select": {
+        "options": [
+          {
+            "name": "High",
+            "color": "red"
+          },
+          {
+            "name": "Medium",
+            "color": "yellow"
+          },
+          {
+            "name": "Low",
+            "color": "gray"
+          }
+        ]
+      }
+    },
+    "Assignee": {
+      "people": {}
+    },
+    "Due Date": {
+      "date": {}
+    },
+    "Tags": {
+      "multi_select": {}
+    },
+    "Estimate": {
+      "number": {
+        "format": "number"
+      }
+    }
+  }
+}

templates/notion/TEMPLATE-PAGE-AGENT-PROFILE.json

@@ -0,0 +1,131 @@
+{
+  "object": "page",
+  "parent": {
+    "type": "database_id",
+    "database_id": "{{AGENTS_DB_ID}}"
+  },
+  "icon": {
+    "type": "emoji",
+    "emoji": "\ud83e\udd16"
+  },
+  "properties": {
+    "Name": {
+      "title": [
+        {
+          "text": {
+            "content": "{{AGENT_NAME}}"
+          }
+        }
+      ]
+    },
+    "Status": {
+      "select": {
+        "name": "Active"
+      }
+    },
+    "Personality": {
+      "multi_select": []
+    },
+    "Capabilities": {
+      "rich_text": [
+        {
+          "text": {
+            "content": "{{CAPABILITIES}}"
+          }
+        }
+      ]
+    },
+    "Created": {
+      "date": {
+        "start": "{{CREATED_DATE}}"
+      }
+    }
+  },
+  "children": [
+    {
+      "object": "heading_1",
+      "heading_1": {
+        "rich_text": [
+          {
+            "text": {
+              "content": "\ud83e\udd16 Agent Profile"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "object": "heading_2",
+      "heading_2": {
+        "rich_text": [
+          {
+            "text": {
+              "content": "\ud83d\udccb Description"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "object": "paragraph",
+      "paragraph": {
+        "rich_text": [
+          {
+            "text": {
+              "content": "{{DESCRIPTION}}"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "object": "heading_2",
+      "heading_2": {
+        "rich_text": [
+          {
+            "text": {
+              "content": "\ud83c\udfaf Purpose"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "object": "paragraph",
+      "paragraph": {
+        "rich_text": [
+          {
+            "text": {
+              "content": "{{PURPOSE}}"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "object": "heading_2",
+      "heading_2": {
+        "rich_text": [
+          {
+            "text": {
+              "content": "\ud83d\udd27 Configuration"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "object": "code",
+      "code": {
+        "language": "yaml",
+        "rich_text": [
+          {
+            "text": {
+              "content": "{{CONFIG_YAML}}"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}

templates/quantum_dashboard.html

@@ -0,0 +1,441 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>BlackRoad Quantum Dashboard</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <style>
+    * { box-sizing: border-box; }
+    body {
+      font-family: system-ui, -apple-system, BlinkMacSystemFont, "SF Pro Text", sans-serif;
+      background: radial-gradient(ellipse at top, #0a0f1e 0%, #050816 40%, #020308 70%, #000 100%);
+      color: #f0f0ff;
+      margin: 0;
+      padding: 0;
+      min-height: 100vh;
+    }
+    .page {
+      max-width: 900px;
+      margin: 0 auto;
+      padding: 32px 20px 80px;
+    }
+    .title-row {
+      display: flex;
+      align-items: center;
+      gap: 12px;
+      flex-wrap: wrap;
+    }
+    h1 {
+      font-size: 1.8rem;
+      margin: 0;
+      background: linear-gradient(135deg, #ff9d00, #ff0066, #7700ff, #0066ff);
+      -webkit-background-clip: text;
+      -webkit-text-fill-color: transparent;
+      background-clip: text;
+    }
+    .chip {
+      font-size: 0.75rem;
+      padding: 4px 10px;
+      border-radius: 999px;
+      border: 1px solid rgba(255,255,255,0.15);
+      background: rgba(0,0,0,0.4);
+      font-family: "JetBrains Mono", ui-monospace, monospace;
+    }
+    .subtitle {
+      margin-top: 8px;
+      opacity: 0.7;
+      font-size: 0.9rem;
+    }
+    .panel {
+      border-radius: 16px;
+      border: 1px solid rgba(255,255,255,0.08);
+      background: linear-gradient(145deg, rgba(10,15,35,0.95), rgba(5,8,22,0.98));
+      padding: 20px 24px;
+      margin-top: 24px;
+      box-shadow: 0 4px 24px rgba(0,0,0,0.4);
+    }
+    .panel h2 {
+      font-size: 1.1rem;
+      margin: 0 0 12px;
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+    .row {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 16px;
+      margin-top: 16px;
+    }
+    .col {
+      flex: 1 1 200px;
+    }
+    label {
+      display: block;
+      font-size: 0.75rem;
+      text-transform: uppercase;
+      letter-spacing: 0.08em;
+      opacity: 0.7;
+      margin-bottom: 6px;
+    }
+    input[type="number"] {
+      width: 100%;
+      padding: 10px 12px;
+      border-radius: 10px;
+      border: 1px solid rgba(255,255,255,0.12);
+      background: rgba(0,0,0,0.5);
+      color: #f0f0ff;
+      font-size: 1rem;
+      font-family: "JetBrains Mono", ui-monospace, monospace;
+      outline: none;
+      transition: border-color 0.2s, box-shadow 0.2s;
+    }
+    input[type="number"]:focus {
+      border-color: rgba(0,180,255,0.7);
+      box-shadow: 0 0 0 2px rgba(0,180,255,0.25);
+    }
+    button {
+      cursor: pointer;
+      padding: 12px 24px;
+      border-radius: 999px;
+      border: none;
+      font-size: 0.95rem;
+      font-weight: 600;
+      background: linear-gradient(135deg, #ff9d00 0%, #ff0066 50%, #0066ff 100%);
+      color: #050816;
+      margin-top: 20px;
+      transition: transform 0.15s, box-shadow 0.15s;
+    }
+    button:hover {
+      transform: translateY(-1px);
+      box-shadow: 0 4px 20px rgba(255,0,102,0.4);
+    }
+    button:disabled {
+      opacity: 0.5;
+      cursor: default;
+      transform: none;
+      box-shadow: none;
+    }
+    .status-pill {
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+      padding: 4px 12px;
+      border-radius: 999px;
+      font-size: 0.8rem;
+      font-family: "JetBrains Mono", ui-monospace, monospace;
+    }
+    .status-pill.online {
+      background: rgba(26,245,157,0.12);
+      border: 1px solid rgba(26,245,157,0.5);
+      color: #1af59d;
+    }
+    .status-pill.offline {
+      background: rgba(255,86,86,0.12);
+      border: 1px solid rgba(255,86,86,0.5);
+      color: #ff5656;
+    }
+    .status-pill.loading {
+      background: rgba(255,200,0,0.12);
+      border: 1px solid rgba(255,200,0,0.4);
+      color: #ffc800;
+    }
+    .mono {
+      font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, monospace;
+    }
+    .result-card {
+      margin-top: 16px;
+      padding: 16px 18px;
+      border-radius: 12px;
+      background: linear-gradient(135deg, rgba(0,102,255,0.15) 0%, rgba(119,0,255,0.1) 100%);
+      border: 1px solid rgba(255,255,255,0.08);
+    }
+    .result-json {
+      background: rgba(0,0,0,0.4);
+      padding: 12px;
+      border-radius: 8px;
+      font-size: 0.8rem;
+      overflow-x: auto;
+      white-space: pre-wrap;
+      word-break: break-all;
+    }
+    .math-explainer {
+      margin-top: 12px;
+      padding: 12px 14px;
+      background: rgba(255,157,0,0.08);
+      border-left: 3px solid #ff9d00;
+      border-radius: 0 8px 8px 0;
+      font-size: 0.85rem;
+      line-height: 1.6;
+    }
+    .math-explainer .formula {
+      font-family: "JetBrains Mono", monospace;
+      background: rgba(0,0,0,0.3);
+      padding: 2px 6px;
+      border-radius: 4px;
+    }
+    .prob-bar {
+      display: flex;
+      height: 24px;
+      border-radius: 12px;
+      overflow: hidden;
+      margin-top: 12px;
+      background: rgba(0,0,0,0.3);
+    }
+    .prob-bar .p0 {
+      background: linear-gradient(90deg, #0066ff, #00aaff);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-size: 0.7rem;
+      font-weight: 600;
+      transition: width 0.3s;
+    }
+    .prob-bar .p1 {
+      background: linear-gradient(90deg, #ff0066, #ff6600);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-size: 0.7rem;
+      font-weight: 600;
+      transition: width 0.3s;
+    }
+    .learn-list {
+      margin: 0;
+      padding-left: 20px;
+      font-size: 0.85rem;
+      line-height: 1.8;
+    }
+    .learn-list code {
+      background: rgba(0,0,0,0.3);
+      padding: 2px 6px;
+      border-radius: 4px;
+      font-size: 0.8rem;
+    }
+    a {
+      color: #66b2ff;
+      text-decoration: none;
+    }
+    a:hover {
+      text-decoration: underline;
+    }
+    .muted {
+      opacity: 0.6;
+    }
+    .small {
+      font-size: 0.8rem;
+    }
+    .hidden {
+      display: none !important;
+    }
+  </style>
+</head>
+<body>
+  <div class="page">
+    <div style="margin-bottom: 24px;">
+      <a href="/" style="color: #00e5ff; text-decoration: none; font-size: 0.9rem;">&larr; Dashboard</a>
+    </div>
+    <div class="title-row">
+      <h1>ψ Quantum Dashboard</h1>
+      <span class="chip">BRQ-01 Spiral</span>
+      <span class="chip">2 qubits</span>
+    </div>
+    <p class="subtitle">
+      First BlackRoad AI quantum node: talk to ψ, see predictions, and map them to ⟨Z⟩ and probabilities.
+    </p>
+
+    <!-- Status Panel -->
+    <div class="panel">
+      <h2>📡 Node Status</h2>
+      <div id="status-container">
+        <span id="status-pill" class="status-pill loading">checking...</span>
+        <span id="status-details" class="small muted mono" style="margin-left: 12px;"></span>
+      </div>
+    </div>
+
+    <!-- Prediction Panel -->
+    <div class="panel">
+      <h2>🔮 Run a Prediction</h2>
+      <p class="small muted">
+        BRQ-01 takes a 2D feature vector <code class="mono">x = [x₀, x₁]</code> and returns
+        the probability for class 1. We compute the implied ⟨Z⟩ using
+        <code class="mono">⟨Z⟩ = 1 - 2p₁</code>.
+      </p>
+
+      <div class="row">
+        <div class="col">
+          <label for="x0">x₀ (rotation on qubit 0)</label>
+          <input id="x0" type="number" step="0.1" value="0.0" />
+        </div>
+        <div class="col">
+          <label for="x1">x₁ (rotation on qubit 1)</label>
+          <input id="x1" type="number" step="0.1" value="0.0" />
+        </div>
+      </div>
+
+      <button id="run-btn">Run ψ on this input</button>
+
+      <!-- Results -->
+      <div id="result-area" class="result-card hidden">
+        <h3 style="margin: 0 0 12px; font-size: 0.95rem;">Response from ψ</h3>
+        <div id="result-json" class="result-json mono"></div>
+
+        <div class="prob-bar">
+          <div id="prob-p0" class="p0" style="width: 50%;">P(0)</div>
+          <div id="prob-p1" class="p1" style="width: 50%;">P(1)</div>
+        </div>
+
+        <div id="math-explainer" class="math-explainer"></div>
+      </div>
+    </div>
+
+    <!-- Learn Panel -->
+    <div class="panel">
+      <h2>📐 Learn the Math</h2>
+      <p class="small muted">
+        Want to see how ψ thinks under the hood? Open <strong>Math Lab (Σ)</strong> from the terminal:
+      </p>
+      <ul class="learn-list">
+        <li><code>1</code> - Vectors → Qubits → ψ</li>
+        <li><code>2</code> - Matrices → Gates → RX/RY/RZ</li>
+        <li><code>3</code> - Inner Products & ⟨ψ|φ⟩</li>
+        <li><code>4</code> - Tensor Products & Entanglement</li>
+        <li><code>5</code> - Live BRQ-01 Demo (ψ on this Pi)</li>
+      </ul>
+      <p class="small muted" style="margin-top: 12px;">
+        Run: <code class="mono">python3 ./blackroad-math-lab.py</code> or press <code>m</code> in the menu.
+      </p>
+    </div>
+
+    <!-- Footer -->
+    <p class="small muted" style="text-align: center; margin-top: 32px;">
+      © 2025 BlackRoad OS, Inc. · ψ uses PennyLane (Apache 2.0, © Xanadu)
+    </p>
+  </div>
+
+  <script>
+    const QUANTUM_API = '/api/quantum';
+
+    const statusPill = document.getElementById('status-pill');
+    const statusDetails = document.getElementById('status-details');
+    const runBtn = document.getElementById('run-btn');
+    const resultArea = document.getElementById('result-area');
+    const resultJson = document.getElementById('result-json');
+    const mathExplainer = document.getElementById('math-explainer');
+    const probP0 = document.getElementById('prob-p0');
+    const probP1 = document.getElementById('prob-p1');
+
+    async function checkStatus() {
+      statusPill.className = 'status-pill loading';
+      statusPill.textContent = 'checking...';
+      statusDetails.textContent = '';
+
+      try {
+        const res = await fetch(`${QUANTUM_API}/status`);
+        const data = await res.json();
+
+        if (data.ok && data.data) {
+          statusPill.className = 'status-pill online';
+          statusPill.textContent = '● online';
+
+          const s = data.data;
+          const details = [];
+          if (s.node_id) details.push(s.node_id);
+          if (s.pennylane_version) details.push(`PennyLane ${s.pennylane_version}`);
+          statusDetails.textContent = details.join(' · ');
+        } else {
+          throw new Error(data.error || 'Unknown error');
+        }
+      } catch (err) {
+        statusPill.className = 'status-pill offline';
+        statusPill.textContent = '● offline';
+        statusDetails.textContent = err.message || 'Connection failed';
+      }
+    }
+
+    async function runPrediction() {
+      const x0 = parseFloat(document.getElementById('x0').value) || 0;
+      const x1 = parseFloat(document.getElementById('x1').value) || 0;
+
+      runBtn.disabled = true;
+      runBtn.textContent = 'Running...';
+
+      try {
+        const res = await fetch(`${QUANTUM_API}/predict`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ x0, x1 })
+        });
+
+        const data = await res.json();
+
+        if (!data.ok) {
+          throw new Error(data.error || 'Prediction failed');
+        }
+
+        const payload = data.data;
+        resultJson.textContent = JSON.stringify(payload, null, 2);
+
+        const p1 = parseFloat(payload.probability || 0);
+        const cls = payload.class;
+        const p0 = 1 - p1;
+        const expZ = 1 - 2 * p1;
+
+        // Update probability bar
+        probP0.style.width = `${p0 * 100}%`;
+        probP0.textContent = `P(0) = ${(p0 * 100).toFixed(1)}%`;
+        probP1.style.width = `${p1 * 100}%`;
+        probP1.textContent = `P(1) = ${(p1 * 100).toFixed(1)}%`;
+
+        // Math explanation
+        mathExplainer.innerHTML = `
+          <strong>Decoding the math:</strong><br><br>
+          From response: <span class="formula">p₁ = ${p1.toFixed(4)}</span>,
+          class = <span class="formula">${cls}</span><br><br>
+
+          Implied expectation value:<br>
+          <span class="formula">⟨Z⟩ = 1 - 2p₁ = 1 - 2×${p1.toFixed(4)} = ${expZ.toFixed(4)}</span><br><br>
+
+          From inner product math:<br>
+          <span class="formula">⟨Z⟩ = |α|² - |β|²</span><br>
+          <span class="formula">P(0) = |α|² = ${p0.toFixed(4)}</span><br>
+          <span class="formula">P(1) = |β|² = ${p1.toFixed(4)}</span><br><br>
+
+          The classifier says: "For x = [${x0}, ${x1}], I computed |ψ⟩ with
+          <strong>${(p0*100).toFixed(1)}%</strong> chance of |0⟩ and
+          <strong>${(p1*100).toFixed(1)}%</strong> chance of |1⟩,
+          so I predict class <strong>${cls}</strong>."
+        `;
+
+        resultArea.classList.remove('hidden');
+
+      } catch (err) {
+        resultJson.textContent = `Error: ${err.message}`;
+        mathExplainer.innerHTML = '';
+        probP0.style.width = '50%';
+        probP1.style.width = '50%';
+        resultArea.classList.remove('hidden');
+      } finally {
+        runBtn.disabled = false;
+        runBtn.textContent = 'Run ψ on this input';
+      }
+    }
+
+    // Event listeners
+    runBtn.addEventListener('click', runPrediction);
+
+    // Allow Enter key to trigger prediction
+    document.getElementById('x0').addEventListener('keypress', (e) => {
+      if (e.key === 'Enter') runPrediction();
+    });
+    document.getElementById('x1').addEventListener('keypress', (e) => {
+      if (e.key === 'Enter') runPrediction();
+    });
+
+    // Initial status check
+    checkStatus();
+    // Refresh status every 30 seconds
+    setInterval(checkStatus, 30000);
+  </script>
+</body>
+</html>

templates/quests_page.html

@@ -0,0 +1,517 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>Quests & Promotion - BlackRoad OS</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <style>
+    :root {
+      --bg-primary: #020308;
+      --bg-secondary: rgba(6, 10, 30, 0.92);
+      --bg-card: rgba(12, 18, 40, 0.85);
+      --text-primary: #f5f5ff;
+      --text-muted: rgba(245, 245, 255, 0.7);
+      --accent-cyan: #00e5ff;
+      --accent-green: #1af59d;
+      --accent-yellow: #ffc400;
+      --accent-purple: #a855f7;
+      --accent-orange: #ff9d00;
+      --accent-pink: #ff0066;
+      --border-subtle: rgba(255, 255, 255, 0.1);
+    }
+
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+
+    body {
+      font-family: system-ui, -apple-system, BlinkMacSystemFont, "SF Pro Text", sans-serif;
+      background: radial-gradient(circle at top, #050816 0, #020308 45%, #000000 100%);
+      color: var(--text-primary);
+      min-height: 100vh;
+    }
+
+    .page {
+      max-width: 900px;
+      margin: 0 auto;
+      padding: 24px 16px 80px;
+    }
+
+    /* Nav */
+    .nav {
+      margin-bottom: 24px;
+    }
+
+    .nav a {
+      color: var(--accent-cyan);
+      text-decoration: none;
+      font-size: 0.9rem;
+    }
+
+    .nav a:hover {
+      text-decoration: underline;
+    }
+
+    /* Header */
+    h1 {
+      font-size: 1.8rem;
+      margin-bottom: 8px;
+    }
+
+    .subtitle {
+      color: var(--text-muted);
+      font-size: 0.95rem;
+      margin-bottom: 24px;
+    }
+
+    .mono {
+      font-family: "JetBrains Mono", ui-monospace, monospace;
+    }
+
+    /* Coach Card */
+    .coach-card {
+      background: linear-gradient(135deg, rgba(168, 85, 247, 0.12), rgba(0, 229, 255, 0.06));
+      border: 1px solid rgba(168, 85, 247, 0.4);
+      border-radius: 16px;
+      padding: 20px 24px;
+      margin-bottom: 24px;
+    }
+
+    .coach-header {
+      display: flex;
+      align-items: center;
+      gap: 12px;
+      margin-bottom: 12px;
+    }
+
+    .coach-header .sigma {
+      font-size: 1.8rem;
+      color: var(--accent-purple);
+    }
+
+    .coach-header .title {
+      font-size: 1.1rem;
+      font-weight: 600;
+    }
+
+    .coach-focus {
+      margin-bottom: 12px;
+    }
+
+    .coach-focus-label {
+      font-size: 0.8rem;
+      color: var(--text-muted);
+      margin-bottom: 4px;
+    }
+
+    .coach-focus-goal {
+      font-size: 0.95rem;
+    }
+
+    .coach-progress-bar {
+      height: 8px;
+      background: rgba(255, 255, 255, 0.1);
+      border-radius: 4px;
+      overflow: hidden;
+      margin: 8px 0;
+    }
+
+    .coach-progress-fill {
+      height: 100%;
+      background: linear-gradient(90deg, var(--accent-purple), var(--accent-cyan));
+      border-radius: 4px;
+      transition: width 0.3s ease;
+    }
+
+    .coach-progress-text {
+      font-size: 0.8rem;
+      color: var(--text-muted);
+    }
+
+    .coach-action {
+      margin-top: 16px;
+      padding-top: 16px;
+      border-top: 1px solid rgba(255, 255, 255, 0.1);
+    }
+
+    .coach-action-label {
+      font-size: 0.8rem;
+      color: var(--text-muted);
+      margin-bottom: 6px;
+    }
+
+    .coach-action-text {
+      font-size: 1rem;
+    }
+
+    .coach-examples {
+      margin-top: 12px;
+      padding-left: 16px;
+    }
+
+    .coach-examples li {
+      font-size: 0.85rem;
+      color: var(--text-muted);
+      margin-bottom: 4px;
+    }
+
+    .coach-examples code {
+      background: rgba(255, 255, 255, 0.1);
+      padding: 2px 6px;
+      border-radius: 4px;
+      font-family: "JetBrains Mono", monospace;
+      font-size: 0.8rem;
+    }
+
+    /* Overall Progress */
+    .overall-progress {
+      background: var(--bg-secondary);
+      border: 1px solid var(--border-subtle);
+      border-radius: 12px;
+      padding: 20px;
+      margin-bottom: 24px;
+    }
+
+    .overall-header {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      margin-bottom: 12px;
+    }
+
+    .overall-title {
+      font-size: 1.1rem;
+      font-weight: 600;
+    }
+
+    .overall-percent {
+      font-family: "JetBrains Mono", monospace;
+      font-size: 1.2rem;
+      color: var(--accent-cyan);
+    }
+
+    .overall-bar {
+      height: 12px;
+      background: rgba(255, 255, 255, 0.1);
+      border-radius: 6px;
+      overflow: hidden;
+    }
+
+    .overall-bar-fill {
+      height: 100%;
+      background: linear-gradient(90deg, var(--accent-orange), var(--accent-pink), var(--accent-purple));
+      border-radius: 6px;
+      transition: width 0.5s ease;
+    }
+
+    .overall-stats {
+      display: flex;
+      justify-content: space-between;
+      margin-top: 8px;
+      font-size: 0.8rem;
+      color: var(--text-muted);
+    }
+
+    /* Stage Cards */
+    .stages {
+      margin-bottom: 32px;
+    }
+
+    .stages-title {
+      font-size: 1rem;
+      color: var(--text-muted);
+      margin-bottom: 16px;
+    }
+
+    .stage-card {
+      background: var(--bg-card);
+      border: 1px solid var(--border-subtle);
+      border-radius: 12px;
+      padding: 16px 20px;
+      margin-bottom: 12px;
+    }
+
+    .stage-card.completed {
+      border-color: rgba(26, 245, 157, 0.4);
+    }
+
+    .stage-card.current {
+      border-color: rgba(255, 157, 0, 0.5);
+      background: rgba(255, 157, 0, 0.05);
+    }
+
+    .stage-header {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      margin-bottom: 8px;
+    }
+
+    .stage-name {
+      font-size: 1rem;
+      font-weight: 600;
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+
+    .stage-icon {
+      font-size: 1.2rem;
+    }
+
+    .stage-target {
+      font-size: 0.85rem;
+      color: var(--accent-purple);
+    }
+
+    .stage-bar {
+      height: 6px;
+      background: rgba(255, 255, 255, 0.1);
+      border-radius: 3px;
+      overflow: hidden;
+      margin-bottom: 12px;
+    }
+
+    .stage-bar-fill {
+      height: 100%;
+      background: var(--accent-green);
+      border-radius: 3px;
+    }
+
+    .stage-goals {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+      gap: 8px;
+    }
+
+    .goal-item {
+      font-size: 0.8rem;
+      display: flex;
+      align-items: center;
+      gap: 6px;
+    }
+
+    .goal-icon {
+      font-size: 0.9rem;
+    }
+
+    .goal-icon.met { color: var(--accent-green); }
+    .goal-icon.unmet { color: var(--text-muted); }
+
+    .goal-text {
+      color: var(--text-muted);
+    }
+
+    .goal-progress {
+      font-family: "JetBrains Mono", monospace;
+      font-size: 0.75rem;
+      margin-left: auto;
+    }
+
+    /* Loading & Error */
+    .loading, .error-state {
+      text-align: center;
+      padding: 48px;
+      color: var(--text-muted);
+    }
+
+    .error-state {
+      background: rgba(255, 68, 68, 0.1);
+      border: 1px solid rgba(255, 68, 68, 0.3);
+      border-radius: 12px;
+      color: #ff6b6b;
+    }
+  </style>
+</head>
+<body>
+  <div class="page">
+    <!-- Navigation -->
+    <div class="nav">
+      <a href="/">&larr; Dashboard</a>
+    </div>
+
+    <!-- Header -->
+    <h1>Quests & Promotion</h1>
+    <p class="subtitle">
+      Track your promotion path progress.
+      Actor: <span class="mono">{{ actor }}</span> |
+      Path: <span class="mono">{{ path_id }}</span>
+    </p>
+
+    <!-- Coach Card -->
+    <div class="coach-card" id="coach-card" style="display: none;">
+      <div class="coach-header">
+        <span class="sigma">Σ</span>
+        <span class="title">Coach Suggestion</span>
+      </div>
+      <div id="coach-content"></div>
+    </div>
+
+    <!-- Overall Progress -->
+    <div class="overall-progress" id="overall-progress" style="display: none;">
+      <div class="overall-header">
+        <span class="overall-title" id="path-name">Loading...</span>
+        <span class="overall-percent" id="path-percent">0%</span>
+      </div>
+      <div class="overall-bar">
+        <div class="overall-bar-fill" id="path-bar" style="width: 0%;"></div>
+      </div>
+      <div class="overall-stats">
+        <span id="path-desc"></span>
+        <span id="path-stages"></span>
+      </div>
+    </div>
+
+    <!-- Stages -->
+    <div class="stages" id="stages">
+      <div class="loading">Loading promotion path...</div>
+    </div>
+  </div>
+
+  <script>
+    const actor = "{{ actor }}";
+    const pathId = "{{ path_id }}";
+
+    async function loadCoach() {
+      try {
+        const res = await fetch(`/api/promotion/coach?actor=${actor}&path_id=${pathId}`);
+        const data = await res.json();
+
+        if (!data.ok) return;
+
+        const card = document.getElementById('coach-card');
+        const content = document.getElementById('coach-content');
+        card.style.display = 'block';
+
+        const s = data.suggestion || {};
+
+        if (s.stage_id === 'complete') {
+          content.innerHTML = `
+            <div style="font-size: 1.2rem; color: var(--accent-green);">
+              🎉 Path Complete!
+            </div>
+            <div style="margin-top: 8px; color: var(--text-muted);">
+              ${s.action || 'All stages completed. You\'re a BlackRoad master!'}
+            </div>
+          `;
+          return;
+        }
+
+        let examplesHtml = '';
+        if (s.example_commands && s.example_commands.length) {
+          examplesHtml = `
+            <ul class="coach-examples">
+              ${s.example_commands.map(ex => `<li><code>${ex}</code></li>`).join('')}
+            </ul>
+          `;
+        }
+
+        content.innerHTML = `
+          <div class="coach-focus">
+            <div class="coach-focus-label">Current Focus</div>
+            <div class="coach-focus-goal">${s.goal_key || 'Unknown'}</div>
+          </div>
+          <div class="coach-progress-bar">
+            <div class="coach-progress-fill" style="width: ${s.percent || 0}%;"></div>
+          </div>
+          <div class="coach-progress-text">
+            ${s.current} / ${s.required} (${s.percent}%)
+          </div>
+          <div class="coach-action">
+            <div class="coach-action-label">👉 Next Action</div>
+            <div class="coach-action-text">${s.action || 'Keep going!'}</div>
+            ${examplesHtml}
+          </div>
+        `;
+
+      } catch (e) {
+        console.error('Failed to load coach:', e);
+      }
+    }
+
+    async function loadPath() {
+      const stagesContainer = document.getElementById('stages');
+      const overallContainer = document.getElementById('overall-progress');
+
+      try {
+        const res = await fetch(`/api/promotion/path?actor=${actor}&path_id=${pathId}`);
+        const data = await res.json();
+
+        if (!data.ok) {
+          stagesContainer.innerHTML = `
+            <div class="error-state">
+              <p>Failed to load promotion path: ${data.error || 'Unknown error'}</p>
+            </div>
+          `;
+          return;
+        }
+
+        // Overall progress
+        overallContainer.style.display = 'block';
+        document.getElementById('path-name').textContent = data.name || pathId;
+        document.getElementById('path-percent').textContent = `${data.completion_percent || 0}%`;
+        document.getElementById('path-bar').style.width = `${data.completion_percent || 0}%`;
+        document.getElementById('path-desc').textContent = data.description || '';
+        document.getElementById('path-stages').textContent =
+          `${data.stages_completed || 0} / ${data.stages_total || 0} stages`;
+
+        // Stages
+        const stages = data.stages || [];
+        let html = '<div class="stages-title">Promotion Stages</div>';
+
+        for (const stage of stages) {
+          const allMet = stage.all_goals_met;
+          const isCurrent = !allMet && stages.indexOf(stage) ===
+            stages.findIndex(s => !s.all_goals_met);
+
+          const cardClass = allMet ? 'completed' : (isCurrent ? 'current' : '');
+          const icon = allMet ? '✅' : (isCurrent ? '🎯' : '⬜');
+
+          let goalsHtml = '';
+          const goals = stage.goals || {};
+          for (const [key, g] of Object.entries(goals)) {
+            const goalIcon = g.met ? '✓' : '·';
+            const goalClass = g.met ? 'met' : 'unmet';
+            goalsHtml += `
+              <div class="goal-item">
+                <span class="goal-icon ${goalClass}">${goalIcon}</span>
+                <span class="goal-text">${key}</span>
+                <span class="goal-progress">${g.current} / ${g.required}</span>
+              </div>
+            `;
+          }
+
+          html += `
+            <div class="stage-card ${cardClass}">
+              <div class="stage-header">
+                <div class="stage-name">
+                  <span class="stage-icon">${icon}</span>
+                  ${stage.name || stage.id}
+                </div>
+                <div class="stage-target">→ ${stage.target_rank || '?'}</div>
+              </div>
+              <div class="stage-bar">
+                <div class="stage-bar-fill" style="width: ${stage.overall_percent || 0}%;"></div>
+              </div>
+              <div class="stage-goals">
+                ${goalsHtml}
+              </div>
+            </div>
+          `;
+        }
+
+        stagesContainer.innerHTML = html;
+
+      } catch (e) {
+        stagesContainer.innerHTML = `
+          <div class="error-state">
+            <p>Failed to load promotion path: ${e.message}</p>
+          </div>
+        `;
+      }
+    }
+
+    // Init
+    loadCoach();
+    loadPath();
+  </script>
+</body>
+</html>

templates/status_page.html

@@ -0,0 +1,517 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>System Status - BlackRoad OS</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <style>
+    :root {
+      --bg-primary: #020308;
+      --bg-secondary: rgba(6, 10, 30, 0.92);
+      --bg-card: rgba(12, 18, 40, 0.85);
+      --text-primary: #f5f5ff;
+      --text-muted: rgba(245, 245, 255, 0.7);
+      --accent-cyan: #00e5ff;
+      --accent-green: #1af59d;
+      --accent-yellow: #ffc400;
+      --accent-purple: #a855f7;
+      --accent-orange: #ff9d00;
+      --accent-pink: #ff0066;
+      --accent-red: #ff4444;
+      --border-subtle: rgba(255, 255, 255, 0.1);
+    }
+
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+
+    body {
+      font-family: system-ui, -apple-system, BlinkMacSystemFont, "SF Pro Text", sans-serif;
+      background: radial-gradient(circle at top, #050816 0, #020308 45%, #000000 100%);
+      color: var(--text-primary);
+      min-height: 100vh;
+    }
+
+    .page {
+      max-width: 1000px;
+      margin: 0 auto;
+      padding: 24px 16px 80px;
+    }
+
+    /* Nav */
+    .nav {
+      margin-bottom: 24px;
+    }
+
+    .nav a {
+      color: var(--accent-cyan);
+      text-decoration: none;
+      font-size: 0.9rem;
+    }
+
+    .nav a:hover {
+      text-decoration: underline;
+    }
+
+    /* Header */
+    h1 {
+      font-size: 1.8rem;
+      margin-bottom: 8px;
+    }
+
+    .subtitle {
+      color: var(--text-muted);
+      font-size: 0.95rem;
+      margin-bottom: 24px;
+    }
+
+    .mono {
+      font-family: "JetBrains Mono", ui-monospace, monospace;
+    }
+
+    /* Overall Status */
+    .overall-status {
+      display: flex;
+      align-items: center;
+      gap: 16px;
+      padding: 20px 24px;
+      border-radius: 12px;
+      margin-bottom: 24px;
+    }
+
+    .overall-status.healthy {
+      background: rgba(26, 245, 157, 0.1);
+      border: 1px solid rgba(26, 245, 157, 0.3);
+    }
+
+    .overall-status.degraded {
+      background: rgba(255, 196, 0, 0.1);
+      border: 1px solid rgba(255, 196, 0, 0.3);
+    }
+
+    .overall-status.down {
+      background: rgba(255, 68, 68, 0.1);
+      border: 1px solid rgba(255, 68, 68, 0.3);
+    }
+
+    .overall-icon {
+      font-size: 2.5rem;
+    }
+
+    .overall-text {
+      flex: 1;
+    }
+
+    .overall-title {
+      font-size: 1.2rem;
+      font-weight: 600;
+    }
+
+    .overall-desc {
+      font-size: 0.9rem;
+      color: var(--text-muted);
+    }
+
+    .refresh-btn {
+      background: rgba(255, 255, 255, 0.1);
+      border: 1px solid rgba(255, 255, 255, 0.2);
+      color: var(--text-primary);
+      padding: 8px 16px;
+      border-radius: 8px;
+      cursor: pointer;
+      font-size: 0.85rem;
+      transition: all 0.2s;
+    }
+
+    .refresh-btn:hover {
+      background: rgba(255, 255, 255, 0.15);
+    }
+
+    .refresh-btn:disabled {
+      opacity: 0.5;
+      cursor: not-allowed;
+    }
+
+    /* Services Grid */
+    .services-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+      gap: 16px;
+      margin-bottom: 32px;
+    }
+
+    .service-card {
+      background: var(--bg-card);
+      border: 1px solid var(--border-subtle);
+      border-radius: 12px;
+      padding: 20px;
+    }
+
+    .service-card.ok {
+      border-left: 3px solid var(--accent-green);
+    }
+
+    .service-card.error {
+      border-left: 3px solid var(--accent-red);
+    }
+
+    .service-header {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      margin-bottom: 12px;
+    }
+
+    .service-name {
+      font-size: 1rem;
+      font-weight: 600;
+    }
+
+    .service-status {
+      font-size: 0.75rem;
+      padding: 3px 10px;
+      border-radius: 999px;
+    }
+
+    .service-status.ok {
+      background: rgba(26, 245, 157, 0.15);
+      border: 1px solid rgba(26, 245, 157, 0.4);
+      color: var(--accent-green);
+    }
+
+    .service-status.error {
+      background: rgba(255, 68, 68, 0.15);
+      border: 1px solid rgba(255, 68, 68, 0.4);
+      color: var(--accent-red);
+    }
+
+    .service-details {
+      font-size: 0.85rem;
+      color: var(--text-muted);
+    }
+
+    .service-url {
+      font-family: "JetBrains Mono", monospace;
+      font-size: 0.8rem;
+      color: var(--accent-cyan);
+      margin-top: 8px;
+    }
+
+    .service-error {
+      font-size: 0.8rem;
+      color: var(--accent-red);
+      margin-top: 8px;
+      padding: 8px;
+      background: rgba(255, 68, 68, 0.1);
+      border-radius: 6px;
+    }
+
+    /* Info Sections */
+    .info-section {
+      background: var(--bg-secondary);
+      border: 1px solid var(--border-subtle);
+      border-radius: 12px;
+      padding: 20px;
+      margin-bottom: 20px;
+    }
+
+    .info-title {
+      font-size: 1rem;
+      font-weight: 600;
+      margin-bottom: 16px;
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+
+    .info-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+      gap: 12px;
+    }
+
+    .info-item {
+      padding: 12px;
+      background: rgba(255, 255, 255, 0.03);
+      border-radius: 8px;
+    }
+
+    .info-label {
+      font-size: 0.75rem;
+      color: var(--text-muted);
+      margin-bottom: 4px;
+    }
+
+    .info-value {
+      font-family: "JetBrains Mono", monospace;
+      font-size: 0.9rem;
+    }
+
+    /* Endpoints List */
+    .endpoints-list {
+      list-style: none;
+    }
+
+    .endpoints-list li {
+      padding: 8px 0;
+      border-bottom: 1px solid rgba(255, 255, 255, 0.05);
+      font-size: 0.85rem;
+      display: flex;
+      gap: 12px;
+    }
+
+    .endpoints-list li:last-child {
+      border-bottom: none;
+    }
+
+    .endpoint-method {
+      font-family: "JetBrains Mono", monospace;
+      font-size: 0.75rem;
+      padding: 2px 6px;
+      border-radius: 4px;
+      background: rgba(0, 229, 255, 0.15);
+      color: var(--accent-cyan);
+    }
+
+    .endpoint-path {
+      font-family: "JetBrains Mono", monospace;
+      color: var(--text-primary);
+    }
+
+    .endpoint-desc {
+      color: var(--text-muted);
+      margin-left: auto;
+    }
+
+    /* Last Updated */
+    .last-updated {
+      text-align: center;
+      font-size: 0.8rem;
+      color: var(--text-muted);
+      margin-top: 24px;
+    }
+  </style>
+</head>
+<body>
+  <div class="page">
+    <!-- Navigation -->
+    <div class="nav">
+      <a href="/">&larr; Dashboard</a>
+    </div>
+
+    <!-- Header -->
+    <h1>System Status</h1>
+    <p class="subtitle">Monitor BlackRoad OS service health and infrastructure</p>
+
+    <!-- Overall Status -->
+    <div class="overall-status healthy" id="overall-status">
+      <div class="overall-icon" id="overall-icon">⏳</div>
+      <div class="overall-text">
+        <div class="overall-title" id="overall-title">Checking services...</div>
+        <div class="overall-desc" id="overall-desc">Please wait</div>
+      </div>
+      <button class="refresh-btn" id="refresh-btn" onclick="refresh()">
+        Refresh
+      </button>
+    </div>
+
+    <!-- Services Grid -->
+    <div class="services-grid" id="services-grid">
+      <!-- Populated by JS -->
+    </div>
+
+    <!-- Operator Info -->
+    <div class="info-section" id="operator-info" style="display: none;">
+      <div class="info-title">📡 Operator API</div>
+      <div id="operator-endpoints"></div>
+    </div>
+
+    <!-- Console Info -->
+    <div class="info-section">
+      <div class="info-title">🖥️ Console Routes</div>
+      <ul class="endpoints-list">
+        <li>
+          <span class="endpoint-method">GET</span>
+          <span class="endpoint-path">/</span>
+          <span class="endpoint-desc">Dashboard home</span>
+        </li>
+        <li>
+          <span class="endpoint-method">GET</span>
+          <span class="endpoint-path">/quantum</span>
+          <span class="endpoint-desc">Quantum predictions</span>
+        </li>
+        <li>
+          <span class="endpoint-method">GET</span>
+          <span class="endpoint-path">/learning</span>
+          <span class="endpoint-desc">Learning history</span>
+        </li>
+        <li>
+          <span class="endpoint-method">GET</span>
+          <span class="endpoint-path">/models</span>
+          <span class="endpoint-desc">Model registry</span>
+        </li>
+        <li>
+          <span class="endpoint-method">GET</span>
+          <span class="endpoint-path">/quests</span>
+          <span class="endpoint-desc">Promotion path</span>
+        </li>
+        <li>
+          <span class="endpoint-method">GET</span>
+          <span class="endpoint-path">/status</span>
+          <span class="endpoint-desc">This page</span>
+        </li>
+        <li>
+          <span class="endpoint-method">GET</span>
+          <span class="endpoint-path">/api/health</span>
+          <span class="endpoint-desc">Aggregated health</span>
+        </li>
+      </ul>
+    </div>
+
+    <!-- Last Updated -->
+    <div class="last-updated" id="last-updated">
+      Last checked: --
+    </div>
+  </div>
+
+  <script>
+    const SERVICES = [
+      {
+        key: 'console',
+        name: 'Web Console',
+        desc: 'This dashboard and UI server',
+        icon: '🖥️'
+      },
+      {
+        key: 'operator',
+        name: 'Operator API',
+        desc: 'Ledger, learning stats, promotion engine',
+        icon: '📡'
+      },
+      {
+        key: 'quantum',
+        name: 'Quantum Node',
+        desc: 'PennyLane-based quantum ML service',
+        icon: 'ψ'
+      }
+    ];
+
+    async function refresh() {
+      const btn = document.getElementById('refresh-btn');
+      btn.disabled = true;
+      btn.textContent = 'Checking...';
+
+      try {
+        const res = await fetch('/api/health');
+        const data = await res.json();
+
+        updateUI(data);
+      } catch (e) {
+        updateUI({ ok: false, error: e.message, services: {} });
+      }
+
+      btn.disabled = false;
+      btn.textContent = 'Refresh';
+
+      document.getElementById('last-updated').textContent =
+        `Last checked: ${new Date().toLocaleTimeString()}`;
+    }
+
+    function updateUI(data) {
+      const services = data.services || {};
+      const allOk = data.ok;
+      const okCount = Object.values(services).filter(s => s.ok).length;
+      const total = Object.keys(services).length;
+
+      // Overall status
+      const overall = document.getElementById('overall-status');
+      const icon = document.getElementById('overall-icon');
+      const title = document.getElementById('overall-title');
+      const desc = document.getElementById('overall-desc');
+
+      if (allOk) {
+        overall.className = 'overall-status healthy';
+        icon.textContent = '✅';
+        title.textContent = 'All Systems Operational';
+        desc.textContent = `${okCount}/${total} services healthy`;
+      } else if (okCount > 0) {
+        overall.className = 'overall-status degraded';
+        icon.textContent = '⚠️';
+        title.textContent = 'Partial Outage';
+        desc.textContent = `${okCount}/${total} services healthy`;
+      } else {
+        overall.className = 'overall-status down';
+        icon.textContent = '❌';
+        title.textContent = 'Major Outage';
+        desc.textContent = 'All services unreachable';
+      }
+
+      // Service cards
+      const grid = document.getElementById('services-grid');
+      let html = '';
+
+      for (const svc of SERVICES) {
+        const status = services[svc.key] || { ok: false, error: 'Unknown' };
+        const cardClass = status.ok ? 'ok' : 'error';
+        const statusText = status.ok ? 'Healthy' : 'Down';
+
+        let errorHtml = '';
+        if (!status.ok && status.error) {
+          errorHtml = `<div class="service-error">${status.error}</div>`;
+        }
+
+        html += `
+          <div class="service-card ${cardClass}">
+            <div class="service-header">
+              <div class="service-name">${svc.icon} ${svc.name}</div>
+              <div class="service-status ${cardClass}">${statusText}</div>
+            </div>
+            <div class="service-details">${svc.desc}</div>
+            ${errorHtml}
+          </div>
+        `;
+      }
+
+      grid.innerHTML = html;
+
+      // Load operator endpoints if available
+      if (services.operator?.ok) {
+        loadOperatorInfo();
+      }
+    }
+
+    async function loadOperatorInfo() {
+      try {
+        const res = await fetch('/api/operator/status');
+        const data = await res.json();
+
+        if (data.ok && data.data) {
+          const info = document.getElementById('operator-info');
+          info.style.display = 'block';
+
+          const endpoints = data.data.endpoints || [];
+          let html = '<ul class="endpoints-list">';
+
+          for (const ep of endpoints) {
+            html += `
+              <li>
+                <span class="endpoint-method">GET/POST</span>
+                <span class="endpoint-path">${ep}</span>
+              </li>
+            `;
+          }
+
+          html += '</ul>';
+          document.getElementById('operator-endpoints').innerHTML = html;
+        }
+      } catch (e) {
+        console.error('Failed to load operator info:', e);
+      }
+    }
+
+    // Init
+    refresh();
+
+    // Auto-refresh every 60s
+    setInterval(refresh, 60000);
+  </script>
+</body>
+</html>