@stackmemoryai/stackmemory 1.2.0 → 1.2.1

package/scripts/gepa/generations/gen-000/baseline.md

@@ -1,124 +1,159 @@
-# StackMemory - Project Configuration
-
-## Project Structure
-
-```
-src/
-  cli/           # CLI commands and entry point
-  core/          # Core business logic
-    context/     # Frame and context management
-    database/    # Database adapters (SQLite, ParadeDB)
-    digest/      # Digest generation
-    query/       # Query parsing and routing
-  integrations/  # External integrations (Linear, MCP)
-  services/      # Business services
-  skills/        # Claude Code skills
-  utils/         # Shared utilities
-scripts/         # Build and utility scripts
-config/          # Configuration files
-docs/            # Documentation
-```
-
-## Key Files
-
-- Entry: src/cli/index.ts
-- MCP Server: src/integrations/mcp/server.ts
-- Frame Manager: src/core/context/frame-manager.ts
-- Database: src/core/database/sqlite-adapter.ts
-
-## Detailed Guides
-
-Quick reference (agent_docs/):
-- linear_integration.md - Linear sync
-- mcp_server.md - MCP tools
-- database_storage.md - Storage
-- claude_hooks.md - Hooks
-
-Full documentation (docs/):
-- principles.md - Agent programming paradigm
-- architecture.md - Extension model and browser sandbox
-- SPEC.md - Technical specification
-- API_REFERENCE.md - API docs
-- DEVELOPMENT.md - Dev guide
-- SETUP.md - Installation
-
-## Commands
-
-```bash
-npm run build          # Compile TypeScript (esbuild)
-npm run lint           # ESLint check
-npm run lint:fix       # Auto-fix lint issues
-npm test               # Run Vitest (watch)
-npm run test:run       # Run tests once
-npm run linear:sync    # Sync with Linear
-
-# StackMemory CLI
-stackmemory capture    # Save session state for handoff
-stackmemory restore    # Restore from captured state
-```
-
-## Working Directory
-
-- PRIMARY: /Users/jwu/Dev/stackmemory
-- ALLOWED: All subdirectories
-- TEMP: /tmp for temporary operations
-
-## Validation (MUST DO)
-
-After code changes:
-1. `npm run lint` - fix any errors AND warnings
-2. `npm run test:run` - verify no regressions
-3. `npm run build` - ensure compilation
-4. Run code to verify it works
-
-Test coverage:
-- New features require tests in `src/**/__tests__/`
-- Maintain or improve coverage (no untested code paths)
-- Critical paths: context management, handoff, Linear sync
-
-Never: Assume success | Skip testing | Use mock data as fallback
-
-## Git Rules (CRITICAL)
-
-- NEVER use `--no-verify` on git push or commit
-- ALWAYS fix lint/test errors before pushing
-- If pre-push hooks fail, fix the underlying issue
-- Run `npm run lint && npm run test:run` before pushing
-- Commit message format: `type(scope): message`
-- Branch naming: `feature/STA-XXX-description` | `fix/STA-XXX-description` | `chore/description`
-
-## Task Management
-
-- Use TodoWrite for 3+ steps or multiple requests
-- Keep one task in_progress at a time
-- Update task status immediately on completion
-
-## Security
-
-NEVER hardcode secrets - use process.env with dotenv/config
-
-```javascript
-import 'dotenv/config';
-const API_KEY = process.env.LINEAR_API_KEY;
-if (!API_KEY) {
-  console.error('LINEAR_API_KEY not set');
-  process.exit(1);
-}
-```
-
-Environment sources (check in order):
-1. .env file
-2. .env.local
-3. ~/.zshrc
-4. Process environment
-
-Secret patterns to block: lin_api_* | lin_oauth_* | sk-* | npm_*
-
-## Workflow
-
-- Check .env for API keys before asking
-- Run npm run linear:sync after task completion
-- Use browser MCP for visual testing
-- Review recent commits and stackmemory.json on session start
-- Use subagents for multi-step tasks
-- Ask 1-3 clarifying questions for complex commands (one at a time)
+AGENTS.md
+
+Purpose
+- A minimal, agent-friendly reference so code-generation agents (Codex, Claude Code, etc.) can work effectively in this repository.
+- Explains key docs, the /designs/ folder, agent responsibilities, and quick operational notes (how to run tests, what to update, and commit expectations).
+
+Repo doc descriptions
+- prompt_plan.md
+  - The agent-driven plan that sequences work into small, testable prompts and steps.
+  - Contains per-step prompts, expected artifacts, tests, rollback/idempotency notes, and a TODO checklist using Markdown checkboxes.
+  - This is the canonical agent workflow driver — update it as you make progress (see Agent responsibility rules below).
+
+- spec.md
+  - The minimal functional & technical specification that defines APIs, data models, and acceptance criteria.
+  - Includes the concise Definition of Done that must be satisfied for each plan step before marking it complete.
+
+- idea.md
+  - Free-form brainstorming, assumptions, notes, research links, and open questions.
+  - Useful for context but not authoritative — always follow spec.md and prompt_plan.md for implementation decisions.
+
+- idea_one_pager.md
+  - A short summary / one‑pager capturing Problem, Audience, Platform, Core Flow, and MVP Features (and optional Non‑Goals).
+  - Good for quick alignment and to confirm that work stays within scope.
+
+What lives in /designs/
+- UI/UX artifacts and visual assets that inform implementation:
+  - wireframes (PNG/SVG), Figma exports (.fig, .pdf), sequence diagrams, architecture diagrams (PNG/PDF/SVG), and annotated screenshots.
+  - Naming conventions: keep filenames short, include version/date and owner, e.g., dashboard_v1_2025-11-01.png or seq_query_flow_v2.pdf.
+  - Large source Figma files may live externally; include an export + a small README describing where the canonical design is stored and any viewing permissions required.
+
+How agents should interact (summary)
+- Treat prompt_plan.md as the authoritative workflow: follow the listed prompts in order and mark checklist items as you finish them.
+- Always follow TDD: write tests first, make the minimal change to pass tests, then refactor while keeping tests green.
+- After any code/test change, update the matching TODO checkbox in prompt_plan.md using the same Markdown checkbox format ('- [x]') and commit the change alongside code and tests.
+- Make the smallest change that passes tests and improves code. Do not introduce new public APIs without updating spec.md and tests.
+- Don't duplicate templates/files to work around errors — fix the original.
+- Suggest a clear manual test path for every change (even when tests cover it).
+- If you cannot open a file or content is missing, say so explicitly and stop. Do not guess.
+
+Quick operational commands (expect these to exist; if not, ask)
+- npm run dev — start local dev server
+- npm test — run unit + integration test suite
+- npm run lint — run linting
+- npm run build — build TypeScript
+- npm run migrate:up / migrate:down — database migrations
+
+Commit & PR expectations
+- Each prompt/plan step should result in a single, focused commit/PR with:
+  - Code + tests + prompt_plan.md checklist update.
+  - A short, copy-pasteable commit summary in the prompt_plan.md step completion entry.
+  - Clear CHANGELOG or Release notes entry if user-facing behavior changed (or explicitly state "No user-facing changes").
+- Use atomic commits. Include test run results in PR description.
+
+Include this governance / workflow block verbatim (do not modify)
+## Repository docs
+- 'ONE_PAGER.md' - Captures Problem, Audience, Platform, Core Flow, MVP Features; Non-Goals optional.
+- 'DEV_SPEC.md' - Minimal functional and technical specification consistent with prior docs, including a concise **Definition of Done**.
+- 'PROMPT_PLAN.md' - Agent-Ready Planner with per-step prompts, expected artifacts, tests, rollback notes, idempotency notes, and a TODO checklist using Markdown checkboxes. This file drives the agent workflow.
+- 'docs/STYLE.md' - Unified design system reference. Typography, layout, color tokens, component patterns. Inspired by Hatchet (structural layout, inset panels) and Outliner (clean hierarchy, whitespace). **All dashboard UI changes must follow this guide.**
+- 'AGENTS.md' - This file.
+
+### Agent responsibility
+- After completing any coding, refactor, or test step, **immediately update the corresponding TODO checklist item in 'prompt_plan.md'**.
+- Use the same Markdown checkbox format ('- [x]') to mark completion.
+- When creating new tasks or subtasks, add them directly under the appropriate section anchor in 'prompt_plan.md'.
+- Always commit changes to 'prompt_plan.md' alongside the code and tests that fulfill them.
+- Do not consider work "done" until the matching checklist item is checked and all related tests are green.
+- When a stage (plan step) is complete with green tests, update the README "Release notes" section with any user-facing impact (or explicitly state "No user-facing changes" if applicable).
+- Even when automated coverage exists, always suggest a feasible manual test path so the human can exercise the feature end-to-end.
+- After a plan step is finished, document its completion state with a short checklist. Include: step name & number, test results, 'prompt_plan.md' status, manual checks performed (mark as complete only after the human confirms they ran to their satisfaction), release notes status, and an inline commit summary string the human can copy & paste.
+
+#### Guardrails for agents
+- Make the smallest change that passes tests and improves the code.
+- Do not introduce new public APIs without updating 'spec.md' and relevant tests.
+- Do not duplicate templates or files to work around issues. Fix the original.
+- If a file cannot be opened or content is missing, say so explicitly and stop. Do not guess.
+- Respect privacy and logging policy: do not log secrets, prompts, completions, or PII.
+
+#### Deferred-work notation
+- When a task is intentionally paused, keep its checkbox unchecked and prepend '(Deferred)' to the TODO label in 'prompt_plan.md', followed by a short reason.
+- Apply the same '(Deferred)' tag to every downstream checklist item that depends on the paused work.
+- Remove the tag only after the work resumes; this keeps the outstanding scope visible without implying completion.
+
+
+
+#### When the prompt plan is fully satisfied
+- Once every Definition of Done task in 'prompt_plan.md' is either checked off or explicitly marked '(Deferred)', the plan is considered **complete**.
+- After that point, you no longer need to update prompt-plan TODOs or reference 'prompt_plan.md', 'spec.md', 'idea_one_pager.md', or other upstream docs to justify changes.
+- All other guardrails, testing requirements, and agent responsibilities in this file continue to apply unchanged.
+
+
+---
+
+## Testing policy (non-negotiable)
+- Tests **MUST** cover the functionality being implemented.
+- **NEVER** ignore the output of the system or the tests - logs and messages often contain **CRITICAL** information.
+- **TEST OUTPUT MUST BE PRISTINE TO PASS.**
+- If logs are **supposed** to contain errors, capture and test it.
+- **NO EXCEPTIONS POLICY:** Under no circumstances should you mark any test type as "not applicable". Every project, regardless of size or complexity, **MUST** have unit tests, integration tests, **AND** end-to-end tests. If you believe a test type doesn't apply, you need the human to say exactly **"I AUTHORIZE YOU TO SKIP WRITING TESTS THIS TIME"**.
+
+### TDD (how we work)
+- Write tests **before** implementation.
+- Only write enough code to make the failing test pass.
+- Refactor continuously while keeping tests green.
+
+**TDD cycle**
+1. Write a failing test that defines a desired function or improvement.
+2. Run the test to confirm it fails as expected.
+3. Write minimal code to make the test pass.
+4. Run the test to confirm success.
+5. Refactor while keeping tests green.
+6. Repeat for each new feature or bugfix.
+
+---
+
+## Important checks
+- **NEVER** disable functionality to hide a failure. Fix root cause.
+- **NEVER** create duplicate templates or files. Fix the original.
+- **NEVER** claim something is "working" when any functionality is disabled or broken.
+- If you can't open a file or access something requested, say so. Do not assume contents.
+- **ALWAYS** identify and fix the root cause of template or compilation errors.
+- If git is initialized, ensure a '.gitignore' exists and contains at least:
+
+  .env
+  .env.local
+  .env.*
+
+  Ask the human whether additional patterns should be added, and suggest any that you think are important given the project.
+
+## When to ask for human input
+Ask the human if any of the following is true:
+- A test type appears "not applicable". Use the exact phrase request: **"I AUTHORIZE YOU TO SKIP WRITING TESTS THIS TIME"**.
+- Required anchors conflict or are missing from upstream docs.
+- You need new environment variables or secrets.
+- An external dependency or major architectural change is required.
+- Design files are missing, unsupported or oversized
+
+(End of verbatim block)
+
+Minimal examples for checklist updates (copy/pasteable)
+- After completing a prompt step, add an entry under that step in prompt_plan.md similar to:
+  - [x] Step 5 — Implement POST /api/v1/query — tests green — manual checks: cURL example tested — README Release Notes updated — commit: "query: add /api/v1/query route, adapter integration, tests"
+- If pausing work:
+  - - [ ] (Deferred) Step 7.3 — Implement real Pinecone adapter — blocked on PINECONE_API_KEY (reason: waiting for dev key from infra)
+
+If anything is missing
+- If you cannot open prompt_plan.md, spec.md, idea.md, idea_one_pager.md, or any design file, stop and report exactly which file and why (permission/absent/parse error).
+- Ask for required secrets or permissions rather than guessing. Use the "When to ask for human input" rules above.
+
+Contact & escalation
+- When blocked on infra/secrets/design files, create a short note in prompt_plan.md under the current step and ping the human with:
+  - What I need: (e.g., PINECONE_API_KEY, AWS dev creds)
+  - Why I need it: (which step/blocker)
+  - Recommended minimal next action & fallback
+
+Notes
+- Keep AGENTS.md and the rest of the repo docs in sync. Update this file if workflow expectations change.
+
+End.

package/scripts/gepa/generations/gen-001/baseline.md

@@ -0,0 +1,159 @@
+AGENTS.md
+
+Purpose
+- A minimal, agent-friendly reference so code-generation agents (Codex, Claude Code, etc.) can work effectively in this repository.
+- Explains key docs, the /designs/ folder, agent responsibilities, and quick operational notes (how to run tests, what to update, and commit expectations).
+
+Repo doc descriptions
+- prompt_plan.md
+  - The agent-driven plan that sequences work into small, testable prompts and steps.
+  - Contains per-step prompts, expected artifacts, tests, rollback/idempotency notes, and a TODO checklist using Markdown checkboxes.
+  - This is the canonical agent workflow driver — update it as you make progress (see Agent responsibility rules below).
+
+- spec.md
+  - The minimal functional & technical specification that defines APIs, data models, and acceptance criteria.
+  - Includes the concise Definition of Done that must be satisfied for each plan step before marking it complete.
+
+- idea.md
+  - Free-form brainstorming, assumptions, notes, research links, and open questions.
+  - Useful for context but not authoritative — always follow spec.md and prompt_plan.md for implementation decisions.
+
+- idea_one_pager.md
+  - A short summary / one‑pager capturing Problem, Audience, Platform, Core Flow, and MVP Features (and optional Non‑Goals).
+  - Good for quick alignment and to confirm that work stays within scope.
+
+What lives in /designs/
+- UI/UX artifacts and visual assets that inform implementation:
+  - wireframes (PNG/SVG), Figma exports (.fig, .pdf), sequence diagrams, architecture diagrams (PNG/PDF/SVG), and annotated screenshots.
+  - Naming conventions: keep filenames short, include version/date and owner, e.g., dashboard_v1_2025-11-01.png or seq_query_flow_v2.pdf.
+  - Large source Figma files may live externally; include an export + a small README describing where the canonical design is stored and any viewing permissions required.
+
+How agents should interact (summary)
+- Treat prompt_plan.md as the authoritative workflow: follow the listed prompts in order and mark checklist items as you finish them.
+- Always follow TDD: write tests first, make the minimal change to pass tests, then refactor while keeping tests green.
+- After any code/test change, update the matching TODO checkbox in prompt_plan.md using the same Markdown checkbox format ('- [x]') and commit the change alongside code and tests.
+- Make the smallest change that passes tests and improves code. Do not introduce new public APIs without updating spec.md and tests.
+- Don't duplicate templates/files to work around errors — fix the original.
+- Suggest a clear manual test path for every change (even when tests cover it).
+- If you cannot open a file or content is missing, say so explicitly and stop. Do not guess.
+
+Quick operational commands (expect these to exist; if not, ask)
+- npm run dev — start local dev server
+- npm test — run unit + integration test suite
+- npm run lint — run linting
+- npm run build — build TypeScript
+- npm run migrate:up / migrate:down — database migrations
+
+Commit & PR expectations
+- Each prompt/plan step should result in a single, focused commit/PR with:
+  - Code + tests + prompt_plan.md checklist update.
+  - A short, copy-pasteable commit summary in the prompt_plan.md step completion entry.
+  - Clear CHANGELOG or Release notes entry if user-facing behavior changed (or explicitly state "No user-facing changes").
+- Use atomic commits. Include test run results in PR description.
+
+Include this governance / workflow block verbatim (do not modify)
+## Repository docs
+- 'ONE_PAGER.md' - Captures Problem, Audience, Platform, Core Flow, MVP Features; Non-Goals optional.
+- 'DEV_SPEC.md' - Minimal functional and technical specification consistent with prior docs, including a concise **Definition of Done**.
+- 'PROMPT_PLAN.md' - Agent-Ready Planner with per-step prompts, expected artifacts, tests, rollback notes, idempotency notes, and a TODO checklist using Markdown checkboxes. This file drives the agent workflow.
+- 'docs/STYLE.md' - Unified design system reference. Typography, layout, color tokens, component patterns. Inspired by Hatchet (structural layout, inset panels) and Outliner (clean hierarchy, whitespace). **All dashboard UI changes must follow this guide.**
+- 'AGENTS.md' - This file.
+
+### Agent responsibility
+- After completing any coding, refactor, or test step, **immediately update the corresponding TODO checklist item in 'prompt_plan.md'**.
+- Use the same Markdown checkbox format ('- [x]') to mark completion.
+- When creating new tasks or subtasks, add them directly under the appropriate section anchor in 'prompt_plan.md'.
+- Always commit changes to 'prompt_plan.md' alongside the code and tests that fulfill them.
+- Do not consider work "done" until the matching checklist item is checked and all related tests are green.
+- When a stage (plan step) is complete with green tests, update the README "Release notes" section with any user-facing impact (or explicitly state "No user-facing changes" if applicable).
+- Even when automated coverage exists, always suggest a feasible manual test path so the human can exercise the feature end-to-end.
+- After a plan step is finished, document its completion state with a short checklist. Include: step name & number, test results, 'prompt_plan.md' status, manual checks performed (mark as complete only after the human confirms they ran to their satisfaction), release notes status, and an inline commit summary string the human can copy & paste.
+
+#### Guardrails for agents
+- Make the smallest change that passes tests and improves the code.
+- Do not introduce new public APIs without updating 'spec.md' and relevant tests.
+- Do not duplicate templates or files to work around issues. Fix the original.
+- If a file cannot be opened or content is missing, say so explicitly and stop. Do not guess.
+- Respect privacy and logging policy: do not log secrets, prompts, completions, or PII.
+
+#### Deferred-work notation
+- When a task is intentionally paused, keep its checkbox unchecked and prepend '(Deferred)' to the TODO label in 'prompt_plan.md', followed by a short reason.
+- Apply the same '(Deferred)' tag to every downstream checklist item that depends on the paused work.
+- Remove the tag only after the work resumes; this keeps the outstanding scope visible without implying completion.
+
+
+
+#### When the prompt plan is fully satisfied
+- Once every Definition of Done task in 'prompt_plan.md' is either checked off or explicitly marked '(Deferred)', the plan is considered **complete**.
+- After that point, you no longer need to update prompt-plan TODOs or reference 'prompt_plan.md', 'spec.md', 'idea_one_pager.md', or other upstream docs to justify changes.
+- All other guardrails, testing requirements, and agent responsibilities in this file continue to apply unchanged.
+
+
+---
+
+## Testing policy (non-negotiable)
+- Tests **MUST** cover the functionality being implemented.
+- **NEVER** ignore the output of the system or the tests - logs and messages often contain **CRITICAL** information.
+- **TEST OUTPUT MUST BE PRISTINE TO PASS.**
+- If logs are **supposed** to contain errors, capture and test it.
+- **NO EXCEPTIONS POLICY:** Under no circumstances should you mark any test type as "not applicable". Every project, regardless of size or complexity, **MUST** have unit tests, integration tests, **AND** end-to-end tests. If you believe a test type doesn't apply, you need the human to say exactly **"I AUTHORIZE YOU TO SKIP WRITING TESTS THIS TIME"**.
+
+### TDD (how we work)
+- Write tests **before** implementation.
+- Only write enough code to make the failing test pass.
+- Refactor continuously while keeping tests green.
+
+**TDD cycle**
+1. Write a failing test that defines a desired function or improvement.
+2. Run the test to confirm it fails as expected.
+3. Write minimal code to make the test pass.
+4. Run the test to confirm success.
+5. Refactor while keeping tests green.
+6. Repeat for each new feature or bugfix.
+
+---
+
+## Important checks
+- **NEVER** disable functionality to hide a failure. Fix root cause.
+- **NEVER** create duplicate templates or files. Fix the original.
+- **NEVER** claim something is "working" when any functionality is disabled or broken.
+- If you can't open a file or access something requested, say so. Do not assume contents.
+- **ALWAYS** identify and fix the root cause of template or compilation errors.
+- If git is initialized, ensure a '.gitignore' exists and contains at least:
+
+  .env
+  .env.local
+  .env.*
+
+  Ask the human whether additional patterns should be added, and suggest any that you think are important given the project.
+
+## When to ask for human input
+Ask the human if any of the following is true:
+- A test type appears "not applicable". Use the exact phrase request: **"I AUTHORIZE YOU TO SKIP WRITING TESTS THIS TIME"**.
+- Required anchors conflict or are missing from upstream docs.
+- You need new environment variables or secrets.
+- An external dependency or major architectural change is required.
+- Design files are missing, unsupported or oversized
+
+(End of verbatim block)
+
+Minimal examples for checklist updates (copy/pasteable)
+- After completing a prompt step, add an entry under that step in prompt_plan.md similar to:
+  - [x] Step 5 — Implement POST /api/v1/query — tests green — manual checks: cURL example tested — README Release Notes updated — commit: "query: add /api/v1/query route, adapter integration, tests"
+- If pausing work:
+  - - [ ] (Deferred) Step 7.3 — Implement real Pinecone adapter — blocked on PINECONE_API_KEY (reason: waiting for dev key from infra)
+
+If anything is missing
+- If you cannot open prompt_plan.md, spec.md, idea.md, idea_one_pager.md, or any design file, stop and report exactly which file and why (permission/absent/parse error).
+- Ask for required secrets or permissions rather than guessing. Use the "When to ask for human input" rules above.
+
+Contact & escalation
+- When blocked on infra/secrets/design files, create a short note in prompt_plan.md under the current step and ping the human with:
+  - What I need: (e.g., PINECONE_API_KEY, AWS dev creds)
+  - Why I need it: (which step/blocker)
+  - Recommended minimal next action & fallback
+
+Notes
+- Keep AGENTS.md and the rest of the repo docs in sync. Update this file if workflow expectations change.
+
+End.

package/scripts/gepa/generations/gen-001/variant-a.md

@@ -0,0 +1,166 @@
+# ProvenantAI
+
+## Reference Docs
+```
+AGENTS.md                                # TDD workflow, checklists, guardrails
+PROMPT_PLAN.md                           # 20 implementation prompts
+docs/STYLE.md                            # Design system (Hatchet + Outliner)
+docs/business/ONE_PAGER.md               # Executive summary
+DEV_SPEC.md                              # Developer spec
+docs/reference/PROJECT.md                # Quick reference
+docs/business/VISION.md                  # Product vision + self-learning + model router
+docs/architecture/SYSTEM_INTEGRATION.md  # System connections (events, flows)
+docs/architecture/HEARTBEAT_DESIGN.md    # Task health + recovery
+docs/nudge-engine-design.md              # Proactive scanner alerts
+docs/architecture/WEBHOOK_SYSTEM_DESIGN.md  # External event publishing
+docs/VALUES.md                           # Company values
+```
+
+## Commands
+```bash
+npm run dev|test|lint|migrate           # Development tasks
+docker-compose up -d                    # Start local DBs
+railway up                              # Deploy to Railway
+```
+
+## Stack
+Node.js + Express + PostgreSQL + Redis | Railway | Stripe + Salesforce + QuickBooks
+
+## Core Services (src/core/)
+monitoring-service | cache-service | queue-service | master-agent | api-validation
+
+## Directory Structure
+```
+src/
+  api/ core/ features/ shared/ integrations/
+docs/ scripts/ docker/
+```
+
+## Git Workflow
+- **NEVER add Co-Authored-By lines** to commits
+- Pre-commit: runs lint + test suite
+- Commit format: `type(scope): message`
+- Deploy: `railway up --detach`
+
+## Architecture
+- **Provenance tracking**: every data point includes source + timestamp + lineage
+- **Multi-tenant**: container isolation per org
+- **Investigation replays**: stored in `data/investigation-replays/`
+- **StackMemory**: session/entity context layer (repurpose when KG lands)
+
+## Key Implementation Files
+```
+src/graph/client.ts                     # MCP client for Graphiti
+src/graph/service.ts                    # Graph ingest + enrich + search
+src/llm/adapter.js                      # LLM streaming + SYSTEM_PROMPT
+src/routes/query.js                     # Query endpoint + KG enrichment
+src/auth/auth.middleware.js             # Clerk + API key + test mode
+src/nudge/rule-engine.js                # 13 default rules + CRUD + eval
+src/nudge/nudge-engine.js               # Lifecycle + state machine + events
+src/nudge/delivery.js                   # Slack Block Kit + delivery
+src/integrations/slack/app.js           # OAuth v2 + token management
+scripts/create-stripe-products.js       # Stripe product creation
+scripts/seed-demo-data.js               # Demo nudge data
+dashboard-app/src/pages/pricing/        # 4-tier pricing UI
+```
+
+## Current State
+- **20 prompts complete** (PROMPT_PLAN.md)
+- **80 test suites, 1547 tests** - all passing (37 unit, 30 core, 13 integrations)
+- **KG integrated** - commit 917f31e (FalkorDB + Graphiti MCP)
+- **Published**: @provenantai/cli@1.0.0
+- **Deployed**: Railway (health OK, DB connected)
+- **Bundle**: 236KB main + 346KB vendor (lazy routes)
+- **Pricing**: Free | Growth $999-1499 | Scale $2999-4499 | Enterprise custom
+- **Slack**: wired in index.js (conditional on SLACK_CLIENT_ID)
+- **Dashboard**: SlackSettings + Nudges page + E2E smoke tests
+
+## Knowledge Graph
+- **FalkorDB**: `falkordb/falkordb:latest` port 6380 (Redis-compatible)
+- **Graphiti**: `zepai/knowledge-graph-mcp:standalone` port 8100
+- **Protocol**: MCP Streamable HTTP (JSON-RPC + SSE) - NOT REST
+- **Ingestion**: fire-and-forget via `add_memory`, extraction runs in background
+- **Config**: `config/graphiti-falkordb.yaml` - Claude Haiku for LLM
+- **Performance**: 34ms avg, $0.00056/event
+- **Query integration**: GraphService.enrichRetrieval() when GRAPHITI_URL set
+- **Graph context**: prepended as first context_document, graceful fallback
+
+## Stripe Products (LIVE)
+```
+Growth:  prod_TyNYCJmlKbMdlz
+  Monthly $1,499:    price_1T0Qn8BjaxUVbh5VjC7BP0cS
+  Quarterly $2,997:  price_1T0Qn9BjaxUVbh5VYmugdPrF
+Scale:   prod_TyNY5SGKvVlbpo
+  Monthly $4,499:    price_1T0Qn9BjaxUVbh5ViK6vRmgn
+  Quarterly $8,997:  price_1T0Qn9BjaxUVbh5V1mBcTAJ0
+```
+Price IDs in `.env` + `dashboard-app/.env` (VITE_STRIPE_PRICE_*)
+
+## Clerk Auth
+- **Current**: test keys (pk_test_*, sk_test_*)
+- **Production setup**: `bash scripts/setup-clerk-production.sh`
+- **Webhook**: /api/webhooks/clerk (Svix verification required in prod)
+- **Status**: code production-ready, test mode blocked in production
+
+## Dashboard
+- **Chat**: `/api/v1/query` with SSE streaming
+- **Sidebar**: toggleable, time-grouped, backend persistence
+- **localStorage**: `provenantai:conversationId`, `sidebarOpen`, `onboarded`
+- **Vite**: `base: '/app/'` + BrowserRouter `basename="/app"`
+- **Dev auth**: `X-Test-Mode: true` bypasses Clerk
+- **Express**: `node src/index.js` on PORT=8080 (3000 = Rails)
+- **Build**: `bash -c 'cd dashboard-app && npx vite build'`
+
+## Slack Integration
+- **OAuth flow**: GET /api/integrations/slack/install → consent → callback
+- **DB**: `slack_installations` table (migration 030) - per-org bot tokens
+- **Service**: `src/integrations/slack/app.js` - createSlackAppService
+- **Delivery**: `src/nudge/delivery.js` - nudge:created listener, Block Kit formatter
+- **Routes**: install, callback, status, channel config, revoke
+- **Env**: SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, SLACK_REDIRECT_URI
+- **Demo data**: `node scripts/seed-demo-data.js` (10 nudges)
+
+## Architecture Patterns
+- **DI**: all route factories accept `deps` objects
+- **Mocks**: MockPineconeAdapter, MockGmailConnectorClient, stub embeddings
+- **Queues**: Bull (not BullMQ)
+- **KMS**: AES-256-GCM shim via LOCAL_KMS_KEY
+- **Streaming**: adapter.streamLLM() → query/stream → ReadableStream
+- **Graph**: optional graphService dep, null when GRAPHITI_URL unset
+
+## Testing
+- **Framework**: Jest + SWC (`@swc/jest`), `@jest/globals` imports
+- **Mocks**: `mockDb = { query: jest.fn() }` via DI
+- **Fetch**: `global.fetch = mockFetch` + `jsonResponse()` helper
+- **Pre-commit**: lint + parallel test suite via concurrently
+- **Timeout guard**: Promise.race + .unref() timer in test/setup.js
+- **Supertest**: pass Express app directly (NOT server) - avoids port contention
+- **Redis**: skip eager connect in NODE_ENV=test; disconnect in afterAll
+
+### Parallel Test Execution
+```bash
+npm test                                 # 3 parallel processes (~9s vs 18s)
+test:unit       (37 suites, 615 tests)  # test/ dir
+test:core       (30 suites, 643 tests)  # src/(api|auth|billing|core|...)
+test:integrations (13 suites, 289 tests)  # src/integrations/
+test:all        (single-process, 4 workers)  # fallback
+```
+**After code changes**: run targeted sub-suite in background via Bash `run_in_background`
+
+## GTM Content
+```
+docs/content/linkedin-pillar1-drafts.md          # 5 problem posts (ready)
+docs/content/gtm-launch-materials.md             # Schedule + Loom + outreach
+docs/business/CONTENT_INBOUND_STRATEGY.md        # Content/inbound playbook
+docs/business/FRACTIONAL_CMO_AGENT.md            # CMO Agent product brief
+```
+
+## Next Actions
+1. Commit: SlackSettings, Nudges polish, smoke tests
+2. Clerk: swap to production keys (requires Clerk dashboard action)
+3. Slack: create app at api.slack.com, run migration 030
+4. Content: schedule posts in Typefully, record Loom demo
+5. Design partners: outreach to 3-5 ICP companies
+6. Attribution: add Google Ads + Meta connectors
+
+<!-- Sync docs/reference/PROJECT.md when verbose docs change -->