vibe-me 3.1.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.
 
 ---
 
@@ -206,6 +211,7 @@ Download [`Vibe.bat`](Vibe.bat), drop it in any project folder, and double-click
 | | |
 | `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 |
 
 ---
@@ -315,19 +321,29 @@ What it catches:
 
 ---
 
-## 🗂️ Vibes Hub — Cross-Project Sync + Intelligence
+## 🗂️ 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.
 
-When you're running vibes across multiple projects (and multiple computers), the **hub** lets you collect, compare, and analyze them all in one place.
+```
+┌─────────────┐     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│
+                                      └──────────────┘
+```
 
-### One-time setup
+### Step 1: Set up the hub (one time)
 
 ```bash
 vibes hub ~/Documents/VibeHub
 ```
 
-This creates a folder with git, a README, and an `_insights/` intelligence layer — then walks you through connecting it to a private GitHub repo.
+Creates a folder with git, a README, and an `_insights/` intelligence layer. Connect it to a private GitHub repo so it syncs across machines.
 
-### Export from any project
+### Step 2: Export from each project
 
 ```bash
 cd your-project
@@ -336,13 +352,9 @@ vibes export
 
 Copies `.vibe/` and `docs/` into your hub, organized by project name. Auto-generates an `index.md` dashboard.
 
-### Sync across machines
-
-Push from one machine, pull on another. Same private repo, all your projects.
-
-### Cross-project intelligence
+### Step 3: AI analysis (after 3+ projects)
 
-After exporting 3+ projects, tell your AI agent:
+Tell your AI agent:
 
 > *"Read `_insights/ANALYZE.md` in my Vibes Hub and follow the instructions."*
 
@@ -350,29 +362,69 @@ 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 projects |
-| `_insights/standards.md` | Universal rules that should apply everywhere |
-| `_insights/opportunities.md` | "Omni does X well → JustLegal should adopt it" |
+| `_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
+
+  ── 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
+├── 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
-├── Omni/
+│   ├── ANALYZE.md          Prompt for AI analysis
+│   ├── patterns.md         Cross-project patterns
+│   ├── standards.md        Universal standards
+│   └── opportunities.md    Transferable improvements
+├── ProjectA/
 │   ├── .vibe/
 │   └── docs/
-├── JustLegal/
+├── ProjectB/
 │   ├── .vibe/
 │   └── docs/
 └── ...
 ```
 
-One project's best practice becomes every project's standard.
-
 ---
 
 ## 🌍 Works With Everything

package/bin/vibes.js

@@ -11,6 +11,7 @@ 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');
@@ -370,6 +371,17 @@ function cmdCheck(targetDir) {
     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; }
@@ -394,6 +406,22 @@ function cmdCheck(targetDir) {
     }
   }
 
+  // ─── 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 = '';
@@ -870,6 +898,101 @@ function cmdHub(hubPathArg) {
   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:'));
@@ -896,6 +1019,7 @@ function printHelp() {
   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('');
@@ -934,8 +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 '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.1.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"
 }