@equilateral_ai/mindmeld 3.0.0

package/README.md

@@ -0,0 +1,300 @@
+# Rapport v3 - mindmeld.dev
+
+**Collaboration memory that compounds.**
+
+Rapport is a project-scoped collaboration memory system that enables teams to share critical context, accelerate learning, and avoid repeated mistakes.
+
+**Integration**: Claude Code CLI (terminal/IDE) - NOT web browser
+**Architecture**: Lambda + API Gateway + PostgreSQL (Tim-Combo pattern)
+
+## Quick Start
+
+### For Developers (CLI Integration)
+
+```bash
+# Install Rapport CLI package
+npm install -g @mindmeld/rapport
+
+# Setup Claude Code hook
+# Add to .claude/hooks/session-start.js:
+const { RapportClient } = require('@mindmeld/rapport');
+const rapport = new RapportClient({ projectPath: process.cwd() });
+const context = await rapport.detectProject();
+
+# Start Claude Code (Rapport auto-detects project)
+cd ~/Source/your-project
+claude
+```
+
+### For Team Admins (Web Dashboard)
+
+```bash
+# Visit web dashboard
+open https://mindmeld.dev/login
+
+# View team analytics, manage projects
+```
+
+## Core Concept
+
+**Traditional team context** (isolated learning):
+- Developer A learns pattern -> uses successfully
+- Developer B encounters same problem -> learns independently
+- Developer C makes mistake A avoided -> repeats failure
+
+**Rapport v3** (compound learning):
+- Developer A learns pattern -> uses successfully -> stored as reinforced
+- Developer B encounters problem -> sees A's pattern -> applies immediately
+- Developer C gets pattern auto-suggested -> avoids mistake entirely
+
+**Result**: Team learns 3-5x faster, avoids 80% of repeated mistakes, generates 30x ROI.
+
+## Features
+
+### 1. Claude Code Integration
+- Session start hooks inject relevant context
+- Pre-compact hooks detect and store patterns
+- Standards validation during development
+- < 500ms hook execution target
+
+### 2. Standards Ingestion (Phase 1)
+- Ingests 100+ patterns from .equilateral-standards/
+- Extracts enforcement rules, anti-patterns, examples, cost impacts
+- Stores in `rapport.standards_patterns` database table
+- Enables intelligent context injection (only relevant standards)
+
+### 3. Relevance Detection (Phase 2)
+- Analyzes project context (files, git history, current work)
+- Identifies applicable standards for current session
+- Prioritizes top 10 most relevant standards for injection
+
+### 4. Pattern Validation (Phase 3)
+- Validates patterns against known standards
+- Detects anti-pattern usage
+- Records violations for team learning
+
+### 5. Curation Engine (Phase 4)
+- Aggregates patterns across projects and teams
+- Detects patterns ready for promotion to standards
+- Tracks pattern metrics (usage, success rate, project count)
+
+### 6. Team Load-Bearing Detection
+- Aggregates context across all team members
+- Auto-detects critical patterns (>70% correlation with success)
+- Higher confidence through team agreement
+
+### 7. Team Learning Metrics
+- Learning velocity (how much faster than solo)
+- Shared patterns (learned by one, used by all)
+- Avoided mistakes (failures prevented by shared learning)
+- ROI calculation (savings vs cost)
+
+## Architecture
+
+**Integration Model**: CLI-first, Web-optional
+
+```
+Claude Code CLI (Terminal/IDE)
+    | (hooks: SessionStart, PreCompact)
+RapportClient (npm package)
+    | (API calls)
+Lambda + API Gateway
+    | (queries)
+PostgreSQL (Tim-Combo schema)
+```
+
+**Project Structure**:
+```
+rapport/
+├── src/
+│   ├── index.js              # RapportClient (npm package)
+│   ├── handlers/             # Lambda handlers (method-specific)
+│   │   ├── helpers/          # Standard helpers (flattened in build)
+│   │   ├── projects/         # Project CRUD
+│   │   ├── sessions/         # Session tracking
+│   │   ├── patterns/         # Pattern storage
+│   │   ├── users/            # User profile + entitlements
+│   │   └── stripe/           # Subscription management
+│   └── core/
+│       ├── CurationEngine.js       # Pattern promotion
+│       ├── PatternValidator.js     # Standards validation
+│       ├── RelevanceDetector.js    # Context-aware detection
+│       ├── StandardsIngestion.js   # Standards parsing
+│       └── TeamLoadBearingDetector.js
+├── hooks/
+│   ├── session-start.js      # Claude Code session hook
+│   └── pre-compact.js        # Pre-compact hook
+├── frontend/
+│   ├── index.html            # Landing page
+│   ├── dashboard.html        # User dashboard
+│   └── admin/                # React admin panel
+├── database/
+│   └── schema.sql            # PostgreSQL schema
+├── scripts/
+│   └── build-handlers.sh     # Lambda build script
+├── template.yaml             # SAM template
+└── docs/                     # Documentation
+```
+
+**See**: `docs/INTEGRATION_ARCHITECTURE.md` for detailed explanation of CLI vs Web model
+
+## API
+
+### Project Management
+```
+GET  /api/projects                    # List user's projects
+POST /api/projects                    # Create project
+PUT  /api/projects/:projectId         # Update project
+DELETE /api/projects/:projectId       # Archive project
+```
+
+### User Management
+```
+GET /api/users/me                     # Get current user profile
+GET /api/users/entitlements           # Get user entitlements
+```
+
+### Subscriptions (Stripe)
+```
+POST /api/stripe/subscription/create  # Create checkout session
+PUT  /api/stripe/subscription/update  # Upgrade/downgrade
+DELETE /api/stripe/subscription/cancel # Cancel subscription
+POST /api/stripe/webhook              # Stripe webhooks
+```
+
+## Subscription Tiers (Proof-of-Contribution Model)
+
+Contributing teams receive a $50/month discount at every tier. This creates a knowledge flywheel where shared patterns become community standards.
+
+### Solo (Free)
+- OSS adoption funnel
+- 3 projects, 1 collaborator
+- Basic invariants only
+- "Powered by MindMeld" attribution
+
+### Team ($99/user or $49/user Contributing)
+- 5 projects, 5 collaborators
+- Community standards (~25 curated patterns)
+- Cross-platform sync, team memory
+- **Contributing**: Patterns flow to community pool
+
+### Professional ($199/user or $149/user Contributing)
+- Unlimited projects, 10 collaborators
+- Full standards library (100+ patterns)
+- Standards picker (choose what to enable)
+- Analytics
+- **Contributing**: Selection signals inform curation
+
+### Enterprise ($990/user)
+- Unlimited everything
+- Custom standards packs
+- SSO integration, audit trail
+- SOC 2 Type II, dedicated isolation
+- Private standards (no contribution option)
+
+**The $50 Contribution Credit**: Not a discount—payment for strengthening the platform. Your anonymized patterns help all teams learn faster.
+
+## Development
+
+### Commands
+```bash
+# Build Lambda handlers
+npm run build
+
+# Deploy to AWS (dev)
+npm run deploy:dev
+
+# Test hooks
+npm run test:hooks
+npm run test:session-start
+npm run test:pre-compact
+
+# Test standards parsing (no database)
+node scripts/demo-standards-parsing.js
+
+# Test standards ingestion (requires database)
+node scripts/test-standards-ingestion.js
+```
+
+### Prerequisites
+- Node.js >= 18
+- AWS SAM CLI
+- PostgreSQL database
+- AWS account with appropriate permissions
+
+### Environment Variables
+```bash
+# Database (SSM resolved at deploy)
+DB_HOST, DB_USER, DB_PASS, DB_NAME, DB_PORT
+
+# Stripe
+STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
+
+# Application
+NODE_ENV, APP_URL
+```
+
+## Standards Integration
+
+Rapport integrates with `.equilateral-standards/` to provide context-aware standards injection:
+
+**What it does**:
+- Ingests 100+ patterns from .equilateral-standards/ markdown files
+- Extracts enforcement rules, anti-patterns, examples, cost impacts
+- Stores in `rapport.standards_patterns` database table
+- Enables intelligent context injection (only relevant standards)
+
+**Test it**:
+```bash
+# Demo parsing (no database required)
+node scripts/demo-standards-parsing.js
+
+# Full ingestion test (requires database)
+node scripts/test-standards-ingestion.js
+```
+
+## Value Proposition
+
+**Junior → Mid-Level Arbitrage**: With battle-tested standards injected at every AI session, junior developers perform like mid-level engineers.
+
+| Role | Annual Salary | With MindMeld |
+|------|---------------|---------------|
+| Junior ($75K) | Performs like mid-level | +$44,652 value |
+| Mid-Level ($120K) | Performs like senior | +$45,000 value |
+| Senior ($165K) | Stops doing KT, does architecture | Leverage multiplied |
+
+**For 10-person engineering team (Professional Contributing)**:
+- Value created: $44,652/dev × 10 devs = $446,520/year
+- Cost: $149/user × 10 users × 12 months = $17,880/year
+- **ROI: 25x** (and your patterns strengthen the platform)
+
+**Knowledge Transfer Elimination**: Traditional KT costs $3,840-$7,680 per junior onboarded. MindMeld eliminates this through automated standards injection.
+
+**Institutional Knowledge Insurance**: When a senior leaves, 6-12 months of institutional knowledge walks out. MindMeld captures and hardens this automatically.
+
+## Domain
+
+**Production**: https://mindmeld.dev
+**API**: https://api.mindmeld.dev
+**Dashboard**: https://mindmeld.dev/dashboard.html
+
+## Documentation
+
+- [Integration Architecture](./docs/INTEGRATION_ARCHITECTURE.md) - CLI vs Web model
+- [API Architecture](./docs/API_ARCHITECTURE.md) - Lambda patterns
+- [Deployment Guide](./docs/DEPLOYMENT.md) - AWS deployment
+- [Standards Integration](./docs/PHASE_1_STANDARDS_INGESTION.md) - Phase 1 details
+- [Relevance Detection](./docs/PHASE_2_RELEVANCE_DETECTION.md) - Phase 2 details
+- [Pattern Validation](./docs/PHASE_3_PATTERN_VALIDATION.md) - Phase 3 details
+- [Curation Engine](./docs/PHASE_4_CURATION_ENGINE.md) - Phase 4 details
+- [Claude Code Integration](./docs/PHASE_5_CLAUDE_CODE_INTEGRATION.md) - Hooks
+
+## License
+
+Proprietary - Equilateral AI (Pareidolia LLC)
+
+## Contact
+
+**Author**: Jim Ford (jim@equilateral.ai)
+**Website**: https://equilateral.ai
+**Product**: https://mindmeld.dev