vibe-me 3.0.0 → 3.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 # 🌀 vibes
 
-### Every project should contain a continuously maintained,<br>AI-readable and human-readable model of itself.
+### Project memory. Cross-project intelligence.<br>One command per project. One hub for all of them.
 
 [![npm version](https://img.shields.io/npm/v/vibe-me?style=flat-square&color=7c3aed&label=npm)](https://www.npmjs.com/package/vibe-me)
 [![license](https://img.shields.io/badge/license-MIT-10b981?style=flat-square)](LICENSE)
@@ -11,16 +11,19 @@
 
 <br>
 
-**One command. Full project memory. Total clarity.**
+**Scaffold. Fill. Validate. Sync. Get feedback.**
 
-`vibes` creates a `.vibe/` semantic layer and a standardized `docs/` folder —<br>
-so any human or AI can understand your project, your product, and your business<br>
-without reading the source code.
+`vibes` gives every project a `.vibe/` semantic layer and `docs/` folder —<br>
+then connects all your projects through a **Vibes Hub** that finds patterns,<br>
+surfaces improvements, and lets your best work raise the bar everywhere.
 
 <br>
 
-```bash
-npx vibe-me all
+```
+npx vibe-me all          # scaffold .vibe/ + docs/ in any project
+npx vibe-me check        # validate quality (catches unfilled templates)
+npx vibe-me export       # sync to your hub
+npx vibe-me insights     # get cross-project feedback
 ```
 
 <br>
@@ -69,6 +72,7 @@ Not a wiki. Not a Confluence graveyard. Not a 200-page design doc nobody reads.
 - Nobody knows the pricing rationale or competitive landscape
 - User frustrations are invisible — product decisions are guesswork
 - Documentation rots because nobody owns it
+- Your projects are islands — lessons learned in one are invisible to others
 
 </td>
 <td width="50%">
@@ -81,14 +85,15 @@ Not a wiki. Not a Confluence graveyard. Not a 200-page design doc nobody reads.
 - Business strategy, pricing, and market position are documented
 - User personas include emotional reality — fears, confusion, goals
 - Documentation stays fresh because the AI updates it
+- **Hub connects all your projects** — patterns, standards, and improvements flow between them
 
 </td>
 </tr>
 </table>
 
-> **This isn't documentation. It's a digital twin of your entire venture.**<br>
+> **This isn't documentation. It's a digital twin of your entire portfolio.**<br>
 > Repository memory. Product memory. Business memory. AI instructions. Living context.<br>
-> It's the difference between a repository and a *project that explains itself.*
+> Each project explains itself — and the hub makes all your projects learn from each other.
 
 ---
 
@@ -200,9 +205,13 @@ Download [`Vibe.bat`](Vibe.bat), drop it in any project folder, and double-click
 | `vibes init` | Create `.vibe/` with the full suite — 15 files + guide |
 | `vibes docs` | Create `docs/` operational documentation — 11 files |
 | `vibes all` | Create both `.vibe/` and `docs/` at once |
-| `vibes check` | Validate all files for completeness and quality |
+| `vibes check` | Validate all files — catches unfilled templates, empty sections, missing structure |
 | `vibes status` | Quick health dashboard with filled/N-A/empty counts |
 | `vibes reset` | Delete and recreate everything |
+| | |
+| `vibes hub <path>` | Set up a central hub — git inits, creates `_insights/`, saves config |
+| `vibes export` | Export `.vibe/` + `docs/` from current project to your hub |
+| `vibes insights` | Show hub feedback for this project — opportunities, standards, anti-patterns |
 | `vibes help` | Show all commands |
 
 ---
@@ -257,10 +266,27 @@ Every line in `.vibe/` should pass this test:
 
 ## 🔍 Quality Validation
 
+`vibes check` doesn't just count lines — it catches real problems:
+
 ```bash
 vibes check
 ```
 
+**On a freshly scaffolded project (before AI fills it out):**
+```
+  🔍 vibes check
+
+  ── .vibe/ ──
+
+  ✖ purpose.md — still contains template instructions (unfilled)
+  ✖ architecture.md — still contains template instructions (unfilled)
+  ✖ flows.md — still contains template instructions (unfilled)
+  ...
+
+  Result: 24 failed, 1 warnings, 0 passed
+```
+
+**After your AI agent fills everything out:**
 ```
   🔍 vibes check
 
@@ -270,7 +296,7 @@ vibes check
   ✔ architecture.md — 86 lines
   ✔ flows.md — 144 lines
   ✔ entities.md — 135 lines
-  ✔ decisions.md — 91 lines
+  ⚠ decisions.md — 91 lines (no dependency graph fields)
   ✔ state.json — 82 lines
   ✔ context.md — 28 lines
   ✔ ai.md — 45 lines
@@ -280,25 +306,124 @@ vibes check
   ✔ experiments.md — 19 lines
   ⊘ business.md — N/A (not applicable)
   ⊘ market.md — N/A (not applicable)
-  ⊘ risks.md — 34 lines
-
-  ── docs/ ──
-
-  ✔ README.md — 45 lines
-  ✔ topology.md — 120 lines
-  ✔ architecture.md — 89 lines
-  ✔ api.md — 200 lines
-  ✔ issues.md — 34 lines
-  ✔ resolved.md — 67 lines
-  ✔ roadmap.md — 42 lines
-  ✔ developer_guide.md — 95 lines
-  ✔ troubleshooting.md — 55 lines
-  ✔ glossary.md — 28 lines
-
-  Result: 2 N/A, 23 passed ✔
+  ✔ risks.md — 34 lines
+
+  Result: 2 N/A, 1 warnings, 22 passed
+```
+
+What it catches:
+- **Unfilled templates** — files that still have `INSTRUCTIONS FOR AI AGENT` (hard fail)
+- **Missing structure** — `purpose.md` without a "NOT do" section, `decisions.md` without dependency graph
+- **Empty bullets/tables** — placeholder content that wasn't filled in
+- **Stale data** — `state.json` not updated in 30+ days
+- **Missing emotional reality** — `users.md` without frustrations, fears, or goals
+- **N/A files** — recognized and not penalized
+
+---
+
+## 🗂️ Vibes Hub — Your Projects Talking to Each Other
+
+The hub is where the magic happens. Every project you work on — across any number of computers — exports its `.vibe/` and `docs/` into one central repo. An AI analyzes them all and finds patterns, anti-patterns, and improvements that flow **back** into each project.
+
+```
+┌─────────────┐     vibes export     ┌──────────────┐     vibes insights     ┌─────────────┐
+│  Project A   │ ──────────────────→  │   Vibes Hub  │  ←────────────────────  │  Project B  │
+│  .vibe/      │                      │  _insights/  │                         │  .vibe/     │
+│  docs/       │                      │  patterns    │   "You should adopt     │  docs/      │
+└─────────────┘                       │  standards   │    Project A's auth"    └─────────────┘
+                                      │  opportunities│
+                                      └──────────────┘
+```
+
+### Step 1: Set up the hub (one time)
+
+```bash
+vibes hub ~/Documents/VibeHub
+```
+
+Creates a folder with git, a README, and an `_insights/` intelligence layer. Connect it to a private GitHub repo so it syncs across machines.
+
+### Step 2: Export from each project
+
+```bash
+cd your-project
+vibes export
+```
+
+Copies `.vibe/` and `docs/` into your hub, organized by project name. Auto-generates an `index.md` dashboard.
+
+### Step 3: AI analysis (after 3+ projects)
+
+Tell your AI agent:
+
+> *"Read `_insights/ANALYZE.md` in my Vibes Hub and follow the instructions."*
+
+The AI reads every project's `.vibe/` files and fills out:
+
+| File | What it finds |
+|:---|:---|
+| `_insights/patterns.md` | Architecture, security, and tech stack patterns across all projects |
+| `_insights/standards.md` | Universal rules that should apply everywhere (file size limits, schema validation, etc.) |
+| `_insights/opportunities.md` | Specific transfers — "Project A does X well → Project B should adopt it because Y" |
+
+### Step 4: Pull feedback into any project
+
+```bash
+cd your-project
+vibes insights
+```
+
+This reads the hub's `_insights/` and shows you **what applies to the project you're standing in**:
+
 ```
+  💡 vibes insights — JustLegal
 
-Files marked N/A are recognized as intentionally not applicable — not penalized.
+  ── Opportunities ──
+
+  ⚡ open-season → JustLegal
+     Adopt EXIF metadata scrubbing for user-uploaded files.
+  ⚡ JustPolitics → JustLegal / Spark
+     Mobile-responsive WebKit GPU blur optimizations.
+
+  ── Universal Standards ──
+
+  ◆ Strict File Size Limits
+  ◆ Structured Schema Validation
+  ◆ Local API Access Authentication
+
+  ── Anti-Patterns ──
+
+  ⚠ Unsecured Localhost APIs
+
+  16 insights found. Review _insights/ in your hub for full details.
+```
+
+One project's best practice becomes every project's standard. **Your portfolio gets smarter every time you export.**
+
+### Multi-machine sync
+
+The hub is a standard Git repo. Push from one machine, pull on another:
+
+1. **First machine:** `vibes hub ~/Documents/VibeHub` → push to private GitHub repo
+2. **Other machines:** Clone the repo → `vibes hub ~/path/to/cloned/VibeHub`
+3. Export projects on any machine → commit & push → pull on the other → `vibes insights`
+
+```
+VibeHub/
+├── index.md                Auto-generated dashboard
+├── _insights/
+│   ├── ANALYZE.md          Prompt for AI analysis
+│   ├── patterns.md         Cross-project patterns
+│   ├── standards.md        Universal standards
+│   └── opportunities.md    Transferable improvements
+├── ProjectA/
+│   ├── .vibe/
+│   └── docs/
+├── ProjectB/
+│   ├── .vibe/
+│   └── docs/
+└── ...
+```
 
 ---
 

package/bin/vibes.js

@@ -11,10 +11,12 @@ const path = require('path');
 // Config
 // ─────────────────────────────────────────────
 
+const CLI_VERSION = require(path.join(__dirname, '..', 'package.json')).version;
 const VIBE_DIR = '.vibe';
 const DOCS_DIR = 'docs';
 const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
 const SPEC_DIR = path.join(__dirname, '..', 'spec');
+const HUB_CONFIG = path.join(process.env.USERPROFILE || process.env.HOME || '', '.vibes-hub');
 
 // All .vibe/ files — the full suite, always installed
 const VIBE_FILES = [
@@ -208,6 +210,124 @@ function cmdCheck(targetDir) {
 
   let passed = 0, failed = 0, warnings = 0, na = 0;
 
+  // ─── Universal quality checks ───
+  function checkQuality(content, file) {
+    const issues = [];
+
+    // FAIL: Still has template instruction comments
+    if (content.includes('INSTRUCTIONS FOR AI AGENT')) {
+      issues.push({ level: 'fail', msg: 'still contains template instructions (unfilled)' });
+      return issues;
+    }
+
+    // FAIL: Too short to be real content
+    const lines = content.split('\n').length;
+    if (lines < 8) {
+      issues.push({ level: 'fail', msg: `only ${lines} lines — needs real content` });
+      return issues;
+    }
+
+    // WARN: Has unfilled placeholder brackets like [Component Name]
+    const placeholders = content.match(/\[(?:Component|Persona|Experiment|Decision|Error|Deliverable|Feature|Issue)\s*\w*\]/gi);
+    if (placeholders && placeholders.length > 1) {
+      issues.push({ level: 'warn', msg: `${placeholders.length} unfilled placeholders (${placeholders[0]}, ...)` });
+    }
+
+    // WARN: Empty bullet points (lines that are just "- " or "- \n")
+    const emptyBullets = (content.match(/^- ?\s*$/gm) || []).length;
+    if (emptyBullets > 2) {
+      issues.push({ level: 'warn', msg: `${emptyBullets} empty bullet points` });
+    }
+
+    // WARN: Empty table rows (| | | |)
+    const emptyRows = (content.match(/^\|\s*\|\s*\|\s*\|/gm) || []).length;
+    if (emptyRows > 1) {
+      issues.push({ level: 'warn', msg: `${emptyRows} empty table rows` });
+    }
+
+    return issues;
+  }
+
+  // ─── File-specific structure checks ───
+  function checkStructure(content, file) {
+    const issues = [];
+
+    switch (file) {
+      case 'purpose.md':
+        if (!content.toLowerCase().includes('not do') && !content.toLowerCase().includes('does not'))
+          issues.push({ level: 'warn', msg: 'missing "NOT do" / scope boundary section' });
+        if (!content.toLowerCase().includes('who'))
+          issues.push({ level: 'warn', msg: 'doesn\'t mention who uses it' });
+        break;
+
+      case 'architecture.md':
+        if (!content.includes('→') && !content.includes('->') && !content.includes('connects') && !content.includes('talks to'))
+          issues.push({ level: 'warn', msg: 'no data flow described (missing → or connection language)' });
+        break;
+
+      case 'flows.md':
+        const flowHeaders = (content.match(/^##\s+/gm) || []).length;
+        if (flowHeaders < 2) issues.push({ level: 'warn', msg: `only ${flowHeaders} flow(s) — most projects have 3+` });
+        break;
+
+      case 'entities.md':
+        if (!content.toLowerCase().includes('depends') && !content.toLowerCase().includes('relationship'))
+          issues.push({ level: 'warn', msg: 'no dependency/relationship info for entities' });
+        break;
+
+      case 'decisions.md':
+        const decisionHeaders = (content.match(/^##\s+/gm) || []).length;
+        if (decisionHeaders < 2) issues.push({ level: 'warn', msg: `only ${decisionHeaders} decision(s) — aim for 3+` });
+        if (!content.includes('Depends On') && !content.includes('Threatened By') && !content.includes('depends on'))
+          issues.push({ level: 'warn', msg: 'no dependency graph fields (Depends On, Threatened By)' });
+        break;
+
+      case 'state.json':
+        try {
+          const s = JSON.parse(content);
+          if (!s.vibe_updated) issues.push({ level: 'warn', msg: 'missing vibe_updated timestamp' });
+          else {
+            const days = (Date.now() - new Date(s.vibe_updated).getTime()) / 86400000;
+            if (days > 30) issues.push({ level: 'warn', msg: `last updated ${Math.floor(days)} days ago — stale?` });
+          }
+          if (!s.project) issues.push({ level: 'warn', msg: 'missing project name' });
+        } catch {
+          issues.push({ level: 'fail', msg: 'invalid JSON' });
+        }
+        break;
+
+      case 'context.md':
+        if (!content.includes('## Current Focus'))
+          issues.push({ level: 'warn', msg: 'missing "Current Focus" section' });
+        else {
+          const focusIdx = content.indexOf('## Current Focus');
+          const nextSection = content.indexOf('##', focusIdx + 16);
+          const focusContent = content.substring(focusIdx, nextSection > 0 ? nextSection : undefined);
+          const focusBullets = (focusContent.match(/^- .{3,}/gm) || []).length;
+          if (focusBullets === 0) issues.push({ level: 'warn', msg: 'Current Focus has no entries' });
+        }
+        break;
+
+      case 'ai.md':
+        if (!content.toLowerCase().includes('never') && !content.toLowerCase().includes('don\'t') && !content.toLowerCase().includes('do not'))
+          issues.push({ level: 'warn', msg: 'no constraints defined — what should agents NOT touch?' });
+        break;
+
+      case 'product.md':
+        if (!content.toLowerCase().includes('retention') && !content.toLowerCase().includes('why') && !content.toLowerCase().includes('value'))
+          issues.push({ level: 'warn', msg: 'missing value prop or retention drivers' });
+        break;
+
+      case 'users.md':
+        if (!content.toLowerCase().includes('frustrat') && !content.toLowerCase().includes('fear') && !content.toLowerCase().includes('pain') && !content.toLowerCase().includes('goal'))
+          issues.push({ level: 'warn', msg: 'missing emotional reality (frustrations, fears, goals)' });
+        break;
+    }
+
+    return issues;
+  }
+
+  // ─── Run checks on .vibe/ ───
   if (hasVibe) {
     console.log('');
     console.log(dim('  ── .vibe/ ──'));
@@ -220,59 +340,89 @@ function cmdCheck(targetDir) {
       const content = fs.readFileSync(fp, 'utf-8').trim();
       const lines = content.split('\n').length;
 
-      // Check for N/A files (product/business layers marked not applicable)
-      if (content.match(/^N\/A/m) || content.match(/^"?N\/A/m)) {
+      // N/A check
+      if (content.match(/^N\/A/m)) {
         console.log(dim('  ⊘ ') + file + dim(' — N/A (not applicable)'));
         na++;
         continue;
       }
 
-      if (lines < 5) { console.log(yellow('  ⚠ ') + file + ` — looks empty (${lines} lines)`); warnings++; continue; }
+      // Run quality + structure checks
+      const allIssues = [...checkQuality(content, file), ...checkStructure(content, file)];
+      const fails = allIssues.filter(i => i.level === 'fail');
+      const warns = allIssues.filter(i => i.level === 'warn');
 
-      // File-specific checks
-      let warn = null;
-      if (file === 'purpose.md' && !content.toLowerCase().includes('not do')) warn = 'missing "NOT do" section';
-      if (file === 'decisions.md' && (content.match(/^## Why /gm) || []).length < 2) warn = 'fewer than 2 decisions';
-      if (file === 'entities.md' && !content.includes('What depends on it')) warn = 'missing dependency fields';
-      if (file === 'flows.md' && (content.match(/^## \d+\./gm) || []).length < 2) warn = 'fewer than 2 flows';
-      if (file === 'state.json') {
-        try {
-          const s = JSON.parse(content);
-          if (!s.vibe_updated) warn = 'missing vibe_updated';
-          else {
-            const days = (Date.now() - new Date(s.vibe_updated).getTime()) / 86400000;
-            if (days > 30) warn = `stale (${Math.floor(days)} days old)`;
-          }
-        } catch { console.log(red('  ✖ ') + file + ' — invalid JSON'); failed++; continue; }
-      }
-      if (file === 'context.md') {
-        if (!content.includes('## Current Focus') || content.match(/^- $/m)) warn = 'Current Focus is empty';
-      }
-      if (file === 'decisions.md' && !content.includes('Depends On') && !content.includes('Threatened By')) {
-        // Only warn if decisions exist but lack graph relationships
-        if ((content.match(/^## Why /gm) || []).length >= 2) warn = 'decisions missing relationship fields (Depends On, Threatened By)';
+      if (fails.length > 0) {
+        console.log(red('  ✖ ') + file + ' — ' + fails[0].msg);
+        failed++;
+      } else if (warns.length > 0) {
+        console.log(yellow('  ⚠ ') + file + ` — ${lines} lines` + yellow(` (${warns.map(w => w.msg).join('; ')})`));
+        warnings++;
+      } else {
+        console.log(green('  ✔ ') + file + ` — ${lines} lines`);
+        passed++;
       }
-
-      if (warn) { console.log(yellow('  ⚠ ') + file + ` — ${warn}`); warnings++; }
-      else { console.log(green('  ✔ ') + file + ` — ${lines} lines`); passed++; }
     }
   }
 
+  // ─── Run checks on docs/ ───
   if (hasDocs) {
     console.log('');
     console.log(dim('  ── docs/ ──'));
     console.log('');
 
+    // Check for non-lowercase filenames in docs/
+    try {
+      const actualFiles = fs.readdirSync(docsDir).filter(f => f.endsWith('.md'));
+      for (const f of actualFiles) {
+        if (f !== 'README.md' && f !== f.toLowerCase()) {
+          console.log(yellow('  ⚠ ') + f + yellow(' — should be lowercase (' + f.toLowerCase() + ')'));
+          warnings++;
+        }
+      }
+    } catch {}
+
     for (const file of DOCS_FILES) {
       const fp = path.join(docsDir, file);
       if (!exists(fp)) { console.log(yellow('  ⚠ ') + file + ' — missing'); warnings++; continue; }
+
       const content = fs.readFileSync(fp, 'utf-8').trim();
       const lines = content.split('\n').length;
-      if (lines < 5) { console.log(yellow('  ⚠ ') + file + ` — looks empty (${lines} lines)`); warnings++; }
-      else { console.log(green('  ✔ ') + file + ` — ${lines} lines`); passed++; }
+
+      const allIssues = checkQuality(content, file);
+      const fails = allIssues.filter(i => i.level === 'fail');
+      const warns = allIssues.filter(i => i.level === 'warn');
+
+      if (fails.length > 0) {
+        console.log(red('  ✖ ') + file + ' — ' + fails[0].msg);
+        failed++;
+      } else if (warns.length > 0) {
+        console.log(yellow('  ⚠ ') + file + ` — ${lines} lines` + yellow(` (${warns.map(w => w.msg).join('; ')})`));
+        warnings++;
+      } else {
+        console.log(green('  ✔ ') + file + ` — ${lines} lines`);
+        passed++;
+      }
     }
   }
 
+  // ─── Cross-check: vibe_version staleness ───
+  const stateFile = path.join(vibeDir, 'state.json');
+  if (hasVibe && exists(stateFile)) {
+    try {
+      const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+      if (state.vibe_version && state.vibe_version !== CLI_VERSION) {
+        const major = (v) => (v || '').split('.')[0];
+        if (major(state.vibe_version) !== major(CLI_VERSION)) {
+          console.log('');
+          console.log(yellow('  ⚠ ') + `vibe_version in state.json is ${state.vibe_version}, CLI is ${CLI_VERSION}`);
+          warnings++;
+        }
+      }
+    } catch {}
+  }
+
+  // ─── Summary ───
   console.log('');
   let result = '';
   if (failed > 0) result = red(`${failed} failed`);
@@ -361,6 +511,488 @@ function cmdReset(targetDir) {
   cmdAll(targetDir);
 }
 
+function copyDirRecursive(src, dest) {
+  if (!exists(src)) return 0;
+  fs.mkdirSync(dest, { recursive: true });
+  let count = 0;
+  for (const item of fs.readdirSync(src)) {
+    const srcPath = path.join(src, item);
+    const destPath = path.join(dest, item);
+    const stat = fs.statSync(srcPath);
+    if (stat.isDirectory()) {
+      count += copyDirRecursive(srcPath, destPath);
+    } else {
+      if (item === 'VIBE_GUIDE.md') continue;
+      fs.writeFileSync(destPath, fs.readFileSync(srcPath));
+      count++;
+    }
+  }
+  return count;
+}
+
+function cmdExport(targetDir, hubPathArg) {
+  targetDir = path.resolve(targetDir);
+  let hubPath = hubPathArg;
+  if (!hubPath && exists(HUB_CONFIG)) {
+    hubPath = fs.readFileSync(HUB_CONFIG, 'utf-8').trim();
+  }
+  if (!hubPath) {
+    console.log(red('\n  ✖ No hub path specified.'));
+    console.log('');
+    console.log('  First time? Set your hub path:');
+    console.log(cyan('    vibes hub C:\\Users\\You\\Documents\\VibeHub'));
+    console.log('');
+    console.log('  Then run:');
+    console.log(cyan('    vibes export'));
+    console.log('');
+    process.exit(1);
+  }
+
+  hubPath = path.resolve(hubPath);
+  const name = getProjectName(targetDir);
+  const projectHub = path.join(hubPath, name);
+
+  console.log('');
+  console.log(bold('  📤 vibes export'));
+  console.log(dim(`  Exporting ${cyan(name)} → ${hubPath}`));
+  console.log('');
+
+  let total = 0;
+
+  const vibeDir = path.join(targetDir, VIBE_DIR);
+  if (exists(vibeDir)) {
+    const count = copyDirRecursive(vibeDir, path.join(projectHub, VIBE_DIR));
+    console.log(green('  ✔ ') + `.vibe/ — ${count} files`);
+    total += count;
+  } else {
+    console.log(yellow('  ⚠ ') + '.vibe/ not found, skipping');
+  }
+
+  const docsDir = path.join(targetDir, DOCS_DIR);
+  if (exists(docsDir)) {
+    const count = copyDirRecursive(docsDir, path.join(projectHub, DOCS_DIR));
+    console.log(green('  ✔ ') + `docs/ — ${count} files`);
+    total += count;
+  } else {
+    console.log(yellow('  ⚠ ') + 'docs/ not found, skipping');
+  }
+
+  const meta = { project: name, exported_at: now(), source: targetDir };
+  fs.writeFileSync(path.join(projectHub, 'export.json'), JSON.stringify(meta, null, 2), 'utf-8');
+  total++;
+
+  console.log('');
+  console.log(green(`  ✔ Exported ${total} files to ${projectHub}`));
+
+  generateHubIndex(hubPath);
+
+  console.log('');
+  console.log(dim('  Commit and push your hub repo to sync across machines:'));
+  console.log(cyan(`    cd "${hubPath}" && git add -A && git commit -m "export ${name}" && git push`));
+  console.log('');
+}
+
+function generateHubIndex(hubPath) {
+  const projects = [];
+  for (const dir of fs.readdirSync(hubPath)) {
+    const dirPath = path.join(hubPath, dir);
+    if (!fs.statSync(dirPath).isDirectory()) continue;
+    if (dir.startsWith('.') || dir.startsWith('_')) continue;
+
+    const exportFile = path.join(dirPath, 'export.json');
+    const vibeDir = path.join(dirPath, VIBE_DIR);
+    const docsDir = path.join(dirPath, DOCS_DIR);
+
+    let exportedAt = 'unknown';
+    if (exists(exportFile)) {
+      try {
+        const meta = JSON.parse(fs.readFileSync(exportFile, 'utf-8'));
+        exportedAt = meta.exported_at ? meta.exported_at.split('T')[0] : 'unknown';
+      } catch {}
+    }
+
+    let vibeFilled = 0, vibeNA = 0, vibeTotal = 0;
+    if (exists(vibeDir)) {
+      for (const f of VIBE_FILES) {
+        const fp = path.join(vibeDir, f);
+        if (!exists(fp)) continue;
+        vibeTotal++;
+        const content = fs.readFileSync(fp, 'utf-8').trim();
+        if (content.match(/^N\/A/m)) vibeNA++;
+        else if (content.split('\n').length >= 10) vibeFilled++;
+      }
+    }
+
+    let docsFilled = 0;
+    if (exists(docsDir)) {
+      for (const f of DOCS_FILES) {
+        const fp = path.join(docsDir, f);
+        if (!exists(fp)) continue;
+        if (fs.readFileSync(fp, 'utf-8').trim().split('\n').length >= 10) docsFilled++;
+      }
+    }
+
+    let purpose = '';
+    const purposeFile = path.join(vibeDir, 'purpose.md');
+    if (exists(purposeFile)) {
+      for (const line of fs.readFileSync(purposeFile, 'utf-8').split('\n')) {
+        const t = line.trim();
+        if (t && !t.startsWith('#') && !t.startsWith('<!--') && !t.startsWith('-->') && !t.startsWith('[')) {
+          purpose = t.substring(0, 80);
+          break;
+        }
+      }
+    }
+
+    projects.push({ name: dir, exportedAt, vibeFilled, vibeNA, vibeTotal, docsFilled, purpose });
+  }
+
+  if (projects.length === 0) return;
+
+  let md = `# Vibes Hub\n\n`;
+  md += `> Auto-generated index. Last updated: ${now().split('T')[0]}\n\n`;
+  md += `| Project | .vibe/ | docs/ | Last Export | Purpose |\n`;
+  md += `|---|---|---|---|---|\n`;
+  for (const p of projects.sort((a, b) => a.name.localeCompare(b.name))) {
+    const vs = p.vibeTotal > 0 ? `${p.vibeFilled}/${p.vibeTotal}` + (p.vibeNA > 0 ? ` (${p.vibeNA} N/A)` : '') : '—';
+    const ds = p.docsFilled > 0 ? `${p.docsFilled}/${DOCS_FILES.length}` : '—';
+    md += `| [${p.name}](./${p.name}/) | ${vs} | ${ds} | ${p.exportedAt} | ${p.purpose} |\n`;
+  }
+  md += `\n---\n\n**${projects.length} projects** tracked.\n`;
+
+  fs.writeFileSync(path.join(hubPath, 'index.md'), md, 'utf-8');
+  console.log(green('  ✔ ') + 'Updated hub index.md');
+}
+
+function cmdHub(hubPathArg) {
+  if (!hubPathArg) {
+    if (exists(HUB_CONFIG)) {
+      const saved = fs.readFileSync(HUB_CONFIG, 'utf-8').trim();
+      console.log(`\n  Hub path: ${cyan(saved)}\n`);
+    } else {
+      console.log(yellow('\n  No hub configured.'));
+      console.log(dim('  Set one with: vibes hub <path>\n'));
+    }
+    return;
+  }
+
+  const resolved = path.resolve(hubPathArg);
+  const isNew = !exists(resolved) || fs.readdirSync(resolved).length === 0;
+
+  // Create directory
+  fs.mkdirSync(resolved, { recursive: true });
+
+  console.log('');
+  console.log(bold('  🗂️  vibes hub setup'));
+  console.log('');
+
+  if (isNew) {
+    // Initialize git
+    const { execSync } = require('child_process');
+    try {
+      execSync('git init', { cwd: resolved, stdio: 'ignore' });
+      console.log(green('  ✔ ') + 'Created directory & initialized git');
+    } catch {
+      console.log(green('  ✔ ') + 'Created directory');
+      console.log(yellow('  ⚠ ') + 'Could not git init (git not found?)');
+    }
+
+    // Create README
+    const readme = [
+      '# Vibes Hub',
+      '',
+      'Central collection of `.vibe/` and `docs/` files from all my projects.',
+      '',
+      '## How this works',
+      '',
+      '1. Run `vibes export` from any project directory',
+      '2. Commit and push: `git add -A && git commit -m "update" && git push`',
+      '3. Pull on another machine: `git pull`',
+      '',
+      '## Projects',
+      '',
+      'See [index.md](index.md) for auto-generated dashboard.',
+      '',
+      '## Cross-Project Intelligence',
+      '',
+      'The `_insights/` folder is where AI analyzes patterns across all your projects.',
+      '',
+      '- **[ANALYZE.md](_insights/ANALYZE.md)** — Copy-paste prompt for your AI agent',
+      '- **[patterns.md](_insights/patterns.md)** — Architecture, security, and tech patterns',
+      '- **[standards.md](_insights/standards.md)** — Universal rules for all projects',
+      '- **[opportunities.md](_insights/opportunities.md)** — What one project can learn from another',
+      '',
+      'Export 3+ projects, then run the analysis prompt to find cross-project improvements.',
+      '',
+    ].join('\n');
+    fs.writeFileSync(path.join(resolved, 'README.md'), readme, 'utf-8');
+    console.log(green('  ✔ ') + 'Created README.md');
+
+    // Create .gitignore
+    fs.writeFileSync(path.join(resolved, '.gitignore'), 'node_modules/\n.DS_Store\nThumbs.db\n', 'utf-8');
+    console.log(green('  ✔ ') + 'Created .gitignore');
+
+    // Create _insights/ intelligence layer
+    const insightsDir = path.join(resolved, '_insights');
+    fs.mkdirSync(insightsDir, { recursive: true });
+
+    // Analysis prompt — the AI reads this to know what to do
+    const analyze = [
+      '# Hub Analysis Prompt',
+      '',
+      '> Copy-paste this to your AI agent after exporting 3+ projects.',
+      '',
+      '---',
+      '',
+      '```',
+      'I have a Vibes Hub — a central collection of .vibe/ and docs/ files',
+      'from all my projects. Read every project folder in this hub and:',
+      '',
+      '1. CROSS-PROJECT PATTERNS',
+      '   - What architectural patterns appear across multiple projects?',
+      '   - What security approaches are used? Are they consistent?',
+      '   - What tech stack choices are shared? Where do they diverge?',
+      '   - What naming conventions or coding standards are consistent?',
+      '',
+      '2. BEST PRACTICES TO REPLICATE',
+      '   - Which project has the best documentation quality?',
+      '   - Which project solved a problem that others still have?',
+      '   - What did one project do exceptionally well that could set',
+      '     the standard for all projects?',
+      '   - Are there security, testing, or deployment practices from',
+      '     one project that others are missing?',
+      '',
+      '3. TRANSFERABLE IMPROVEMENTS',
+      '   - For each project, list specific improvements it could adopt',
+      '     from another project. Be concrete: "Project A could adopt',
+      '     Project B\'s approach to X because Y."',
+      '   - Identify shared problems that could have a shared solution.',
+      '',
+      '4. RISKS AND GAPS',
+      '   - Which projects have risks that could affect other projects?',
+      '   - Are there shared dependencies that create portfolio risk?',
+      '   - Which projects have missing or weak documentation areas?',
+      '',
+      '5. UNIVERSAL STANDARDS',
+      '   - Based on what works best across projects, propose standards',
+      '     that should apply to ALL projects going forward.',
+      '   - These could be file size limits, security practices, naming',
+      '     conventions, documentation requirements, etc.',
+      '',
+      'Write your findings into the _insights/ folder:',
+      '- patterns.md — Cross-project patterns',
+      '- standards.md — Proposed universal standards',
+      '- opportunities.md — Specific transferable improvements',
+      '',
+      'Be specific. Reference actual project names and files.',
+      '```',
+      '',
+    ].join('\n');
+    fs.writeFileSync(path.join(insightsDir, 'ANALYZE.md'), analyze, 'utf-8');
+
+    // Patterns skeleton
+    const patterns = [
+      '# Cross-Project Patterns',
+      '',
+      '> Auto-populated by AI analysis. Run the prompt in ANALYZE.md.',
+      '',
+      '## Architecture Patterns',
+      '',
+      '<!-- What architectural approaches appear across multiple projects? -->',
+      '',
+      '## Security Patterns',
+      '',
+      '<!-- How do projects handle auth, encryption, secrets? -->',
+      '',
+      '## Shared Tech Stack',
+      '',
+      '<!-- Languages, frameworks, databases used across projects -->',
+      '',
+      '| Technology | Used In | Notes |',
+      '|---|---|---|',
+      '| | | |',
+      '',
+      '## Common Anti-Patterns',
+      '',
+      '<!-- Mistakes or bad patterns that appear in multiple projects -->',
+      '',
+    ].join('\n');
+    fs.writeFileSync(path.join(insightsDir, 'patterns.md'), patterns, 'utf-8');
+
+    // Standards skeleton
+    const standards = [
+      '# Universal Standards',
+      '',
+      '> Standards that should apply to ALL projects, based on what works best.',
+      '',
+      '## Code Standards',
+      '',
+      '<!-- File size limits, naming conventions, banned patterns -->',
+      '',
+      '## Documentation Standards',
+      '',
+      '<!-- What every project must document, minimum quality bar -->',
+      '',
+      '## Security Standards',
+      '',
+      '<!-- Auth patterns, encryption requirements, secrets management -->',
+      '',
+      '## AI Agent Standards',
+      '',
+      '<!-- Rules every AI agent must follow across all projects -->',
+      '',
+    ].join('\n');
+    fs.writeFileSync(path.join(insightsDir, 'standards.md'), standards, 'utf-8');
+
+    // Opportunities skeleton
+    const opportunities = [
+      '# Transferable Improvements',
+      '',
+      '> Specific things one project does well that others should adopt.',
+      '',
+      '## [Source Project] → [Target Project]',
+      '',
+      '**What:** [Specific practice or solution]',
+      '',
+      '**Why:** [Why the target project would benefit]',
+      '',
+      '**How:** [What the target project needs to change]',
+      '',
+      '---',
+      '',
+      '<!-- Copy the template above for each transferable improvement. -->',
+      '',
+    ].join('\n');
+    fs.writeFileSync(path.join(insightsDir, 'opportunities.md'), opportunities, 'utf-8');
+
+    console.log(green('  ✔ ') + 'Created _insights/ (analysis prompt + templates)');
+  } else {
+    console.log(green('  ✔ ') + 'Directory already exists');
+  }
+
+  // Save config
+  fs.writeFileSync(HUB_CONFIG, resolved, 'utf-8');
+  console.log(green('  ✔ ') + `Hub path saved: ${cyan(resolved)}`);
+
+  console.log('');
+  console.log(bold('  Next — connect to GitHub:'));
+  console.log('');
+  console.log(dim('  1. Go to ') + cyan('github.com/new'));
+  console.log(dim('     Name: ') + bold('VibeHub') + dim(' (or whatever you want)'));
+  console.log(dim('     Visibility: ') + bold('Private'));
+  console.log(dim('     Click "Create repository"'));
+  console.log('');
+  console.log(dim('  2. Run these commands:'));
+  console.log('');
+  console.log(cyan(`     cd "${resolved}"`));
+  console.log(cyan('     git remote add origin git@github.com:YOUR_USERNAME/VibeHub.git'));
+  console.log(cyan('     git add -A && git commit -m "init hub" && git push -u origin main'));
+  console.log('');
+  console.log(dim('  After that, exporting from any project is just:'));
+  console.log('');
+  console.log(cyan('     vibes export'));
+  console.log(cyan(`     cd "${resolved}" && git add -A && git commit -m "update" && git push`));
+  console.log('');
+  console.log(dim('  On another computer, clone the repo and run:'));
+  console.log(cyan('     vibes hub <path-to-cloned-repo>'));
+  console.log('');
+}
+
+function cmdInsights(targetDir) {
+  if (!exists(HUB_CONFIG)) {
+    console.log(red('\n  ✖ No hub configured. Run "vibes hub <path>" first.\n'));
+    process.exit(1);
+  }
+
+  const hubPath = fs.readFileSync(HUB_CONFIG, 'utf-8').trim();
+  const insightsDir = path.join(hubPath, '_insights');
+
+  if (!exists(insightsDir)) {
+    console.log(red('\n  ✖ No _insights/ folder in hub. Run the analysis prompt first.\n'));
+    process.exit(1);
+  }
+
+  const name = getProjectName(targetDir);
+  const nameL = name.toLowerCase();
+
+  console.log('');
+  console.log(bold(`  💡 vibes insights — ${name}`));
+
+  let totalHits = 0;
+
+  // ─── Scan opportunities.md ───
+  const oppFile = path.join(insightsDir, 'opportunities.md');
+  if (exists(oppFile)) {
+    const content = fs.readFileSync(oppFile, 'utf-8');
+    // Split by ## headers
+    const sections = content.split(/^## /gm).filter(s => s.trim());
+    const relevant = sections.filter(s => s.toLowerCase().includes(nameL));
+
+    if (relevant.length > 0) {
+      console.log('');
+      console.log(dim('  ── Opportunities ──'));
+      console.log('');
+      for (const section of relevant) {
+        const title = section.split('\n')[0].trim();
+        const whatMatch = section.match(/\*\*What:\*\*\s*(.+)/i);
+        const what = whatMatch ? whatMatch[1].trim() : '';
+        console.log(cyan('  ⚡ ') + title);
+        if (what) console.log(dim('     ') + what);
+        totalHits++;
+      }
+    }
+  }
+
+  // ─── Scan standards.md ───
+  const stdFile = path.join(insightsDir, 'standards.md');
+  if (exists(stdFile)) {
+    const content = fs.readFileSync(stdFile, 'utf-8');
+    const bullets = content.match(/^\d+\.\s+\*\*.+\*\*/gm) || [];
+
+    if (bullets.length > 0) {
+      console.log('');
+      console.log(dim('  ── Universal Standards ──'));
+      console.log('');
+      for (const bullet of bullets) {
+        const clean = bullet.replace(/^\d+\.\s+/, '').replace(/\*\*/g, '');
+        console.log(dim('  ◆ ') + clean);
+        totalHits++;
+      }
+    }
+  }
+
+  // ─── Scan patterns.md for anti-patterns mentioning this project ───
+  const patFile = path.join(insightsDir, 'patterns.md');
+  if (exists(patFile)) {
+    const content = fs.readFileSync(patFile, 'utf-8');
+    const antiSection = content.split('## Common Anti-Patterns')[1];
+    if (antiSection) {
+      const items = antiSection.split(/^\d+\./gm).filter(s => s.trim());
+      const relevant = items.filter(s => s.toLowerCase().includes(nameL));
+
+      if (relevant.length > 0) {
+        console.log('');
+        console.log(dim('  ── Anti-Patterns ──'));
+        console.log('');
+        for (const item of relevant) {
+          const title = item.match(/\*\*(.+?)\*\*/)?.[1] || item.split('\n')[0].trim();
+          console.log(yellow('  ⚠ ') + title);
+          totalHits++;
+        }
+      }
+    }
+  }
+
+  console.log('');
+  if (totalHits === 0) {
+    console.log(dim('  No specific insights found for this project.'));
+    console.log(dim('  Export 3+ projects, then run the analysis prompt in _insights/ANALYZE.md.'));
+  } else {
+    console.log(`  ${totalHits} insights found. Review _insights/ in your hub for full details.`);
+  }
+  console.log('');
+}
+
 function printNextSteps() {
   console.log('');
   console.log(bold('  What to do next:'));
@@ -381,13 +1013,19 @@ function printHelp() {
   console.log('');
   console.log('  ' + bold('Usage:'));
   console.log('');
-  console.log('    vibes init      Create .vibe/ with the full suite (15 files + guide)');
-  console.log('    vibes docs      Create docs/ operational documentation (11 files)');
-  console.log('    vibes all       Create both .vibe/ and docs/ at once');
-  console.log('    vibes check     Validate all files for completeness');
-  console.log('    vibes status    Quick health dashboard');
-  console.log('    vibes reset     Delete and recreate everything');
-  console.log('    vibes help      Show this help message');
+  console.log('    vibes init            Create .vibe/ with the full suite (15 files + guide)');
+  console.log('    vibes docs            Create docs/ operational documentation (11 files)');
+  console.log('    vibes all             Create both .vibe/ and docs/ at once');
+  console.log('    vibes check           Validate all files for completeness');
+  console.log('    vibes status          Quick health dashboard');
+  console.log('    vibes reset           Delete and recreate everything');
+  console.log('    vibes insights        Show hub feedback for this project');
+  console.log('');
+  console.log('  ' + bold('Hub (cross-project sync):'));
+  console.log('');
+  console.log('    vibes hub <path>      Set your central hub directory (saved globally)');
+  console.log('    vibes export          Export .vibe/ + docs/ to your hub');
+  console.log('    vibes export <path>   Export to a specific hub path');
   console.log('');
   console.log('  ' + bold('.vibe/') + dim(' — Project memory'));
   console.log(dim('  Core:      purpose · architecture · flows · entities · decisions · state'));
@@ -420,6 +1058,9 @@ switch (command) {
   case 'check':   cmdCheck(targetDir); break;
   case 'status':  cmdStatus(targetDir); break;
   case 'reset':   cmdReset(targetDir); break;
+  case 'export':    cmdExport('.', args[1]); break;
+  case 'hub':       cmdHub(args[1]); break;
+  case 'insights':  cmdInsights(targetDir); break;
   case 'help': case '--help': case '-h': printHelp(); break;
   default:
     console.log(red(`\n  Unknown command: ${command}`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-me",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "The complete semantic layer for any project. Repository memory, product memory, business memory, AI instructions, and living context — so any human or AI can understand your project without reading the source.",
   "keywords": [
     "vibes",

package/spec/VIBE_GUIDE.md

@@ -818,6 +818,57 @@ Never put API keys, passwords, internal URLs, or customer data in `.vibe/` files
 
 ---
 
+## Beyond One Project — The Vibes Hub
+
+Everything above describes how to create a `.vibe/` layer for **one** project. But the real power emerges when you connect multiple projects together.
+
+### The Problem
+
+You're building 5 projects. One has great authentication. Another has a clever caching strategy. A third has a security hole that the first project already solved. But you'd never know — because each project is an island.
+
+### The Solution: Hub + Insights
+
+The `vibe-me` CLI includes a **hub** — a central folder (synced via Git) that collects the `.vibe/` and `docs/` from all your projects. After exporting 3+ projects, an AI analyzes them all and generates cross-project intelligence:
+
+```bash
+# One-time: create a hub
+vibes hub ~/Documents/VibeHub
+
+# From any project: export to the hub
+vibes export
+
+# From any project: see what the hub knows about you
+vibes insights
+```
+
+The AI analysis produces three files in `_insights/`:
+
+- **patterns.md** — Architecture and security patterns shared across projects
+- **standards.md** — Universal rules that should apply everywhere (file size limits, schema validation, token auth, etc.)
+- **opportunities.md** — Specific transfers: "Project A does X well → Project B should adopt it because Y"
+
+Then `vibes insights` reads those files and shows you **only what applies to the project you're standing in** — opportunities targeted at you, standards you might be missing, and anti-patterns you share with other projects.
+
+### Why This Matters
+
+Without a hub, your best ideas are trapped in one project. With a hub:
+- Security patterns from one project become standards for all of them
+- A caching strategy you invented in one app gets recommended to another
+- An anti-pattern detected in one project gets flagged everywhere it appears
+- Your portfolio gets smarter every time you export
+
+### The Workflow
+
+```
+Scaffold (.vibe/) → Fill out → Validate (vibes check) → Export to hub → AI analysis → vibes insights
+       ↑                                                                                      │
+       └──────────────────── Apply feedback, improve ────────────────────────────────────────────┘
+```
+
+This is not just documentation. It's a **feedback loop across your entire portfolio**.
+
+---
+
 ## FAQ
 
 **Q: What if the project is tiny (one file, 200 lines)?**

package/templates/state.json

@@ -1,4 +1,5 @@
 {
+  "project": "PROJECT_NAME",
   "version": "0.1.0",
   "health": "active",
   "status": "prototype",
@@ -7,6 +8,6 @@
   "known_issues": [],
   "dependencies": [],
   "constraints": [],
-  "vibe_version": "1.0",
+  "vibe_version": "3.2.0",
   "vibe_updated": "TIMESTAMP"
 }