mindforge-cc 9.0.0 → 10.0.1

package/docs/Templates/Codebase/integrations.md

@@ -1,280 +0,0 @@
-# External Integrations Template
-
-Template for `.mindforge/codebase/INTEGRATIONS.md` - captures external service dependencies.
-
-**Purpose:** Document what external systems this codebase communicates with. Focused on "what lives outside our code that we depend on."
-
----
-
-## File Template
-
-```markdown
-# External Integrations
-
-**Analysis Date:** [YYYY-MM-DD]
-
-## APIs & External Services
-
-**Payment Processing:**
-- [Service] - [What it's used for: e.g., "subscription billing, one-time payments"]
-  - SDK/Client: [e.g., "stripe npm package v14.x"]
-  - Auth: [e.g., "API key in STRIPE_SECRET_KEY env var"]
-  - Endpoints used: [e.g., "checkout sessions, webhooks"]
-
-**Email/SMS:**
-- [Service] - [What it's used for: e.g., "transactional emails"]
-  - SDK/Client: [e.g., "sendgrid/mail v8.x"]
-  - Auth: [e.g., "API key in SENDGRID_API_KEY env var"]
-  - Templates: [e.g., "managed in SendGrid dashboard"]
-
-**External APIs:**
-- [Service] - [What it's used for]
-  - Integration method: [e.g., "REST API via fetch", "GraphQL client"]
-  - Auth: [e.g., "OAuth2 token in AUTH_TOKEN env var"]
-  - Rate limits: [if applicable]
-
-## Data Storage
-
-**Databases:**
-- [Type/Provider] - [e.g., "PostgreSQL on Supabase"]
-  - Connection: [e.g., "via DATABASE_URL env var"]
-  - Client: [e.g., "Prisma ORM v5.x"]
-  - Migrations: [e.g., "prisma migrate in migrations/"]
-
-**File Storage:**
-- [Service] - [e.g., "AWS S3 for user uploads"]
-  - SDK/Client: [e.g., "@aws-sdk/client-s3"]
-  - Auth: [e.g., "IAM credentials in AWS_* env vars"]
-  - Buckets: [e.g., "prod-uploads, dev-uploads"]
-
-**Caching:**
-- [Service] - [e.g., "Redis for session storage"]
-  - Connection: [e.g., "REDIS_URL env var"]
-  - Client: [e.g., "ioredis v5.x"]
-
-## Authentication & Identity
-
-**Auth Provider:**
-- [Service] - [e.g., "Supabase Auth", "Auth0", "custom JWT"]
-  - Implementation: [e.g., "Supabase client SDK"]
-  - Token storage: [e.g., "httpOnly cookies", "localStorage"]
-  - Session management: [e.g., "JWT refresh tokens"]
-
-**OAuth Integrations:**
-- [Provider] - [e.g., "Google OAuth for sign-in"]
-  - Credentials: [e.g., "GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET"]
-  - Scopes: [e.g., "email, profile"]
-
-## Monitoring & Observability
-
-**Error Tracking:**
-- [Service] - [e.g., "Sentry"]
-  - DSN: [e.g., "SENTRY_DSN env var"]
-  - Release tracking: [e.g., "via SENTRY_RELEASE"]
-
-**Analytics:**
-- [Service] - [e.g., "Mixpanel for product analytics"]
-  - Token: [e.g., "MIXPANEL_TOKEN env var"]
-  - Events tracked: [e.g., "user actions, page views"]
-
-**Logs:**
-- [Service] - [e.g., "CloudWatch", "Datadog", "none (stdout only)"]
-  - Integration: [e.g., "AWS Lambda built-in"]
-
-## CI/CD & Deployment
-
-**Hosting:**
-- [Platform] - [e.g., "Vercel", "AWS Lambda", "Docker on ECS"]
-  - Deployment: [e.g., "automatic on main branch push"]
-  - Environment vars: [e.g., "configured in Vercel dashboard"]
-
-**CI Pipeline:**
-- [Service] - [e.g., "GitHub Actions"]
-  - Workflows: [e.g., "test.yml, deploy.yml"]
-  - Secrets: [e.g., "stored in GitHub repo secrets"]
-
-## Environment Configuration
-
-**Development:**
-- Required env vars: [List critical vars]
-- Secrets location: [e.g., ".env.local (gitignored)", "1Password vault"]
-- Mock/stub services: [e.g., "Stripe test mode", "local PostgreSQL"]
-
-**Staging:**
-- Environment-specific differences: [e.g., "uses staging Stripe account"]
-- Data: [e.g., "separate staging database"]
-
-**Production:**
-- Secrets management: [e.g., "Vercel environment variables"]
-- Failover/redundancy: [e.g., "multi-region DB replication"]
-
-## Webhooks & Callbacks
-
-**Incoming:**
-- [Service] - [Endpoint: e.g., "/api/webhooks/stripe"]
-  - Verification: [e.g., "signature validation via stripe.webhooks.constructEvent"]
-  - Events: [e.g., "payment_intent.succeeded, customer.subscription.updated"]
-
-**Outgoing:**
-- [Service] - [What triggers it]
-  - Endpoint: [e.g., "external CRM webhook on user signup"]
-  - Retry logic: [if applicable]
-
----
-
-*Integration audit: [date]*
-*Update when adding/removing external services*
-```
-
-<good_examples>
-```markdown
-# External Integrations
-
-**Analysis Date:** 2025-01-20
-
-## APIs & External Services
-
-**Payment Processing:**
-- Stripe - Subscription billing and one-time course payments
-  - SDK/Client: stripe npm package v14.8
-  - Auth: API key in STRIPE_SECRET_KEY env var
-  - Endpoints used: checkout sessions, customer portal, webhooks
-
-**Email/SMS:**
-- SendGrid - Transactional emails (receipts, password resets)
-  - SDK/Client: @sendgrid/mail v8.1
-  - Auth: API key in SENDGRID_API_KEY env var
-  - Templates: Managed in SendGrid dashboard (template IDs in code)
-
-**External APIs:**
-- OpenAI API - Course content generation
-  - Integration method: REST API via openai npm package v4.x
-  - Auth: Bearer token in OPENAI_API_KEY env var
-  - Rate limits: 3500 requests/min (tier 3)
-
-## Data Storage
-
-**Databases:**
-- PostgreSQL on Supabase - Primary data store
-  - Connection: via DATABASE_URL env var
-  - Client: Prisma ORM v5.8
-  - Migrations: prisma migrate in prisma/migrations/
-
-**File Storage:**
-- Supabase Storage - User uploads (profile images, course materials)
-  - SDK/Client: @supabase/supabase-js v2.x
-  - Auth: Service role key in SUPABASE_SERVICE_ROLE_KEY
-  - Buckets: avatars (public), course-materials (private)
-
-**Caching:**
-- None currently (all database queries, no Redis)
-
-## Authentication & Identity
-
-**Auth Provider:**
-- Supabase Auth - Email/password + OAuth
-  - Implementation: Supabase client SDK with server-side session management
-  - Token storage: httpOnly cookies via @supabase/ssr
-  - Session management: JWT refresh tokens handled by Supabase
-
-**OAuth Integrations:**
-- Google OAuth - Social sign-in
-  - Credentials: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET (Supabase dashboard)
-  - Scopes: email, profile
-
-## Monitoring & Observability
-
-**Error Tracking:**
-- Sentry - Server and client errors
-  - DSN: SENTRY_DSN env var
-  - Release tracking: Git commit SHA via SENTRY_RELEASE
-
-**Analytics:**
-- None (planned: Mixpanel)
-
-**Logs:**
-- Vercel logs - stdout/stderr only
-  - Retention: 7 days on Pro plan
-
-## CI/CD & Deployment
-
-**Hosting:**
-- Vercel - Next.js app hosting
-  - Deployment: Automatic on main branch push
-  - Environment vars: Configured in Vercel dashboard (synced to .env.example)
-
-**CI Pipeline:**
-- GitHub Actions - Tests and type checking
-  - Workflows: .github/workflows/ci.yml
-  - Secrets: None needed (public repo tests only)
-
-## Environment Configuration
-
-**Development:**
-- Required env vars: DATABASE_URL, NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY
-- Secrets location: .env.local (gitignored), team shared via 1Password vault
-- Mock/stub services: Stripe test mode, Supabase local dev project
-
-**Staging:**
-- Uses separate Supabase staging project
-- Stripe test mode
-- Same Vercel account, different environment
-
-**Production:**
-- Secrets management: Vercel environment variables
-- Database: Supabase production project with daily backups
-
-## Webhooks & Callbacks
-
-**Incoming:**
-- Stripe - /api/webhooks/stripe
-  - Verification: Signature validation via stripe.webhooks.constructEvent
-  - Events: payment_intent.succeeded, customer.subscription.updated, customer.subscription.deleted
-
-**Outgoing:**
-- None
-
----
-
-*Integration audit: 2025-01-20*
-*Update when adding/removing external services*
-```
-</good_examples>
-
-<guidelines>
-**What belongs in INTEGRATIONS.md:**
-- External services the code communicates with
-- Authentication patterns (where secrets live, not the secrets themselves)
-- SDKs and client libraries used
-- Environment variable names (not values)
-- Webhook endpoints and verification methods
-- Database connection patterns
-- File storage locations
-- Monitoring and logging services
-
-**What does NOT belong here:**
-- Actual API keys or secrets (NEVER write these)
-- Internal architecture (that's ARCHITECTURE.md)
-- Code patterns (that's PATTERNS.md)
-- Technology choices (that's STACK.md)
-- Performance issues (that's CONCERNS.md)
-
-**When filling this template:**
-- Check .env.example or .env.template for required env vars
-- Look for SDK imports (stripe, @sendgrid/mail, etc.)
-- Check for webhook handlers in routes/endpoints
-- Note where secrets are managed (not the secrets)
-- Document environment-specific differences (dev/staging/prod)
-- Include auth patterns for each service
-
-**Useful for phase planning when:**
-- Adding new external service integrations
-- Debugging authentication issues
-- Understanding data flow outside the application
-- Setting up new environments
-- Auditing third-party dependencies
-- Planning for service outages or migrations
-
-**Security note:**
-Document WHERE secrets live (env vars, Vercel dashboard, 1Password), never WHAT the secrets are.
-</guidelines>

package/docs/Templates/Codebase/stack.md

@@ -1,186 +0,0 @@
-# Technology Stack Template
-
-Template for `.mindforge/codebase/STACK.md` - captures the technology foundation.
-
-**Purpose:** Document what technologies run this codebase. Focused on "what executes when you run the code."
-
----
-
-## File Template
-
-```markdown
-# Technology Stack
-
-**Analysis Date:** [YYYY-MM-DD]
-
-## Languages
-
-**Primary:**
-- [Language] [Version] - [Where used: e.g., "all application code"]
-
-**Secondary:**
-- [Language] [Version] - [Where used: e.g., "build scripts, tooling"]
-
-## Runtime
-
-**Environment:**
-- [Runtime] [Version] - [e.g., "Node.js 20.x"]
-- [Additional requirements if any]
-
-**Package Manager:**
-- [Manager] [Version] - [e.g., "npm 10.x"]
-- Lockfile: [e.g., "package-lock.json present"]
-
-## Frameworks
-
-**Core:**
-- [Framework] [Version] - [Purpose: e.g., "web server", "UI framework"]
-
-**Testing:**
-- [Framework] [Version] - [e.g., "Jest for unit tests"]
-- [Framework] [Version] - [e.g., "Playwright for E2E"]
-
-**Build/Dev:**
-- [Tool] [Version] - [e.g., "Vite for bundling"]
-- [Tool] [Version] - [e.g., "TypeScript compiler"]
-
-## Key Dependencies
-
-[Only include dependencies critical to understanding the stack - limit to 5-10 most important]
-
-**Critical:**
-- [Package] [Version] - [Why it matters: e.g., "authentication", "database access"]
-- [Package] [Version] - [Why it matters]
-
-**Infrastructure:**
-- [Package] [Version] - [e.g., "Express for HTTP routing"]
-- [Package] [Version] - [e.g., "PostgreSQL client"]
-
-## Configuration
-
-**Environment:**
-- [How configured: e.g., ".env files", "environment variables"]
-- [Key configs: e.g., "DATABASE_URL, API_KEY required"]
-
-**Build:**
-- [Build config files: e.g., "vite.config.ts, tsconfig.json"]
-
-## Platform Requirements
-
-**Development:**
-- [OS requirements or "any platform"]
-- [Additional tooling: e.g., "Docker for local DB"]
-
-**Production:**
-- [Deployment target: e.g., "Vercel", "AWS Lambda", "Docker container"]
-- [Version requirements]
-
----
-
-*Stack analysis: [date]*
-*Update after major dependency changes*
-```
-
-<good_examples>
-```markdown
-# Technology Stack
-
-**Analysis Date:** 2025-01-20
-
-## Languages
-
-**Primary:**
-- TypeScript 5.3 - All application code
-
-**Secondary:**
-- JavaScript - Build scripts, config files
-
-## Runtime
-
-**Environment:**
-- Node.js 20.x (LTS)
-- No browser runtime (CLI tool only)
-
-**Package Manager:**
-- npm 10.x
-- Lockfile: `package-lock.json` present
-
-## Frameworks
-
-**Core:**
-- None (vanilla Node.js CLI)
-
-**Testing:**
-- Vitest 1.0 - Unit tests
-- tsx - TypeScript execution without build step
-
-**Build/Dev:**
-- TypeScript 5.3 - Compilation to JavaScript
-- esbuild - Used by Vitest for fast transforms
-
-## Key Dependencies
-
-**Critical:**
-- commander 11.x - CLI argument parsing and command structure
-- chalk 5.x - Terminal output styling
-- fs-extra 11.x - Extended file system operations
-
-**Infrastructure:**
-- Node.js built-ins - fs, path, child_process for file operations
-
-## Configuration
-
-**Environment:**
-- No environment variables required
-- Configuration via CLI flags only
-
-**Build:**
-- `tsconfig.json` - TypeScript compiler options
-- `vitest.config.ts` - Test runner configuration
-
-## Platform Requirements
-
-**Development:**
-- macOS/Linux/Windows (any platform with Node.js)
-- No external dependencies
-
-**Production:**
-- Distributed as npm package
-- Installed globally via npm install -g
-- Runs on user's Node.js installation
-
----
-
-*Stack analysis: 2025-01-20*
-*Update after major dependency changes*
-```
-</good_examples>
-
-<guidelines>
-**What belongs in STACK.md:**
-- Languages and versions
-- Runtime requirements (Node, Bun, Deno, browser)
-- Package manager and lockfile
-- Framework choices
-- Critical dependencies (limit to 5-10 most important)
-- Build tooling
-- Platform/deployment requirements
-
-**What does NOT belong here:**
-- File structure (that's STRUCTURE.md)
-- Architectural patterns (that's ARCHITECTURE.md)
-- Every dependency in package.json (only critical ones)
-- Implementation details (defer to code)
-
-**When filling this template:**
-- Check package.json for dependencies
-- Note runtime version from .nvmrc or package.json engines
-- Include only dependencies that affect understanding (not every utility)
-- Specify versions only when version matters (breaking changes, compatibility)
-
-**Useful for phase planning when:**
-- Adding new dependencies (check compatibility)
-- Upgrading frameworks (know what's in use)
-- Choosing implementation approach (must work with existing stack)
-- Understanding build requirements
-</guidelines>