neotoma 0.3.0 → 0.3.2

package/docs/feature_units/completed/FU-702/manifest.yaml

@@ -1,418 +0,0 @@
-feature_id: "fu_702"
-version: "1.0.0"
-status: "draft"
-priority: "p1"
-risk_level: "medium"
-
-metadata:
-  title: "Billing and Subscription Management"
-  description: "Implement billing system for revenue collection (€3k–€15k/yr ACVs)"
-  owner: "engineering@neotoma.com"
-  reviewers:
-    - "techlead@neotoma.com"
-    - "product@neotoma.com"
-  created_at: "2025-01-XX"
-  target_release: "v1.0.0"
-
-subsystems:
-  - name: "billing"
-    changes: "New billing subsystem with Stripe integration"
-  - name: "auth"
-    changes: "Subscription status checks in auth middleware"
-  - name: "database"
-    changes: "New tables: subscriptions, invoices, usage_metrics, billing_plans"
-
-schema_changes:
-  - table: "subscriptions"
-    operation: "create_table"
-    columns:
-      - name: "id"
-        type: "UUID"
-        primary_key: true
-      - name: "user_id"
-        type: "UUID"
-        nullable: false
-        foreign_key: "auth.users(id)"
-      - name: "team_id"
-        type: "UUID"
-        nullable: true
-        foreign_key: "teams(id)"
-      - name: "plan_id"
-        type: "TEXT"
-        nullable: false
-      - name: "stripe_subscription_id"
-        type: "TEXT"
-        nullable: false
-        unique: true
-      - name: "status"
-        type: "TEXT"
-        nullable: false
-
-  - table: "invoices"
-    operation: "create_table"
-    columns:
-      - name: "id"
-        type: "UUID"
-        primary_key: true
-      - name: "subscription_id"
-        type: "UUID"
-        nullable: false
-        foreign_key: "subscriptions(id)"
-      - name: "stripe_invoice_id"
-        type: "TEXT"
-        nullable: false
-        unique: true
-      - name: "amount_cents"
-        type: "INTEGER"
-        nullable: false
-      - name: "status"
-        type: "TEXT"
-        nullable: false
-
-  - table: "usage_metrics"
-    operation: "create_table"
-    columns:
-      - name: "id"
-        type: "UUID"
-        primary_key: true
-      - name: "user_id"
-        type: "UUID"
-        nullable: true
-        foreign_key: "auth.users(id)"
-      - name: "team_id"
-        type: "UUID"
-        nullable: true
-        foreign_key: "teams(id)"
-      - name: "metric_type"
-        type: "TEXT"
-        nullable: false
-      - name: "metric_value"
-        type: "INTEGER"
-        nullable: false
-
-  - table: "billing_plans"
-    operation: "create_table"
-    columns:
-      - name: "id"
-        type: "TEXT"
-        primary_key: true
-      - name: "name"
-        type: "TEXT"
-        nullable: false
-      - name: "price_cents_monthly"
-        type: "INTEGER"
-        nullable: false
-      - name: "price_cents_annual"
-        type: "INTEGER"
-        nullable: true
-
-api_changes:
-  endpoints:
-    - path: "/api/billing/subscription"
-      method: "GET"
-      change_type: "new"
-      description: "Get current subscription"
-
-    - path: "/api/billing/subscribe"
-      method: "POST"
-      change_type: "new"
-      description: "Create subscription"
-
-    - path: "/api/billing/update-subscription"
-      method: "POST"
-      change_type: "new"
-      description: "Update subscription"
-
-    - path: "/api/billing/cancel-subscription"
-      method: "POST"
-      change_type: "new"
-      description: "Cancel subscription"
-
-    - path: "/api/billing/invoices"
-      method: "GET"
-      change_type: "new"
-      description: "List invoices"
-
-    - path: "/api/billing/usage"
-      method: "GET"
-      change_type: "new"
-      description: "Get usage metrics"
-
-    - path: "/api/billing/webhook"
-      method: "POST"
-      change_type: "new"
-      description: "Stripe webhook handler"
-
-ui:
-  components:
-    - name: "BillingSettings"
-      change_type: "new"
-      path: "frontend/src/components/BillingSettings.tsx"
-      description: "Main billing page"
-
-    - name: "SubscriptionCard"
-      change_type: "new"
-      path: "frontend/src/components/SubscriptionCard.tsx"
-      description: "Display current subscription"
-
-    - name: "PlanSelector"
-      change_type: "new"
-      path: "frontend/src/components/PlanSelector.tsx"
-      description: "Plan selection UI"
-
-    - name: "InvoiceTable"
-      change_type: "new"
-      path: "frontend/src/components/InvoiceTable.tsx"
-      description: "Invoice history table"
-
-    - name: "UsageDashboard"
-      change_type: "new"
-      path: "frontend/src/components/UsageDashboard.tsx"
-      description: "Usage metrics visualization"
-
-    - name: "SettingsUI"
-      change_type: "modified"
-      changes: "Add billing tab/section"
-
-  accessibility:
-    keyboard_navigation: true
-    aria_labels:
-      - element: "plan-selector"
-        label: "Select subscription plan"
-      - element: "payment-form"
-        label: "Payment information"
-    focus_management: "Focus moves to success message after subscription change"
-
-  i18n:
-    translatable_strings:
-      - key: "billing.subscription.active"
-        en: "Active Subscription"
-        es: "Suscripción Activa"
-      - key: "billing.plan.monthly"
-        en: "Monthly"
-        es: "Mensual"
-      - key: "billing.plan.annual"
-        en: "Annual"
-        es: "Anual"
-    locale_formatting:
-      - type: "currency"
-        fields: ["amount_cents"]
-      - type: "date"
-        fields: ["current_period_end", "paid_at"]
-
-observability:
-  metrics:
-    - name: "subscription_created_total"
-      type: "counter"
-      labels:
-        - "plan_id"
-        - "billing_cycle"
-      description: "Total subscriptions created"
-
-    - name: "subscription_updated_total"
-      type: "counter"
-      labels:
-        - "plan_id"
-        - "status"
-      description: "Total subscriptions updated"
-
-    - name: "payment_processed_total"
-      type: "counter"
-      labels:
-        - "status"
-      description: "Total payments processed"
-
-    - name: "payment_processed_amount_cents"
-      type: "histogram"
-      buckets: [10000, 50000, 100000, 500000, 1000000]
-      description: "Payment amounts in cents"
-
-    - name: "stripe_webhook_processed_total"
-      type: "counter"
-      labels:
-        - "event_type"
-        - "status"
-      description: "Stripe webhooks processed"
-
-  logs:
-    - level: "info"
-      event: "subscription_created"
-      fields:
-        - "subscription_id"
-        - "plan_id"
-        - "user_id"
-
-    - level: "info"
-      event: "payment_processed"
-      fields:
-        - "invoice_id"
-        - "amount_cents"
-        - "status"
-
-    - level: "error"
-      event: "payment_failed"
-      fields:
-        - "subscription_id"
-        - "error_code"
-        - "trace_id"
-
-    - level: "error"
-      event: "stripe_webhook_error"
-      fields:
-        - "event_type"
-        - "error_code"
-        - "trace_id"
-
-  events:
-    - event_type: "subscription.created"
-      payload:
-        - "subscription_id"
-        - "plan_id"
-      emitted_when: "Subscription successfully created"
-
-    - event_type: "subscription.updated"
-      payload:
-        - "subscription_id"
-        - "old_status"
-        - "new_status"
-      emitted_when: "Subscription status changed"
-
-    - event_type: "invoice.paid"
-      payload:
-        - "invoice_id"
-        - "amount_cents"
-      emitted_when: "Invoice payment succeeded"
-
-testing:
-  unit_tests:
-    - file: "src/services/billing.test.ts"
-      tests:
-        - "calculateSubscriptionPrice"
-        - "formatCurrency"
-        - "validatePlanTransition"
-        - "parseStripeWebhook"
-
-  integration_tests:
-    - file: "src/services/billing.integration.test.ts"
-      tests:
-        - "create subscription and verify Stripe customer"
-        - "update subscription and verify Stripe subscription"
-        - "cancel subscription and verify Stripe subscription"
-        - "handle payment webhook and update subscription"
-        - "generate invoice and verify database"
-
-  e2e_tests:
-    - file: "playwright/tests/billing.spec.ts"
-      tests:
-        - "user subscribes to individual plan"
-        - "user upgrades to team plan"
-        - "user cancels subscription"
-        - "user views invoice history"
-        - "payment fails and user sees past_due status"
-
-  fixtures:
-    - name: "stripe_webhook_subscription_created.json"
-      location: "playwright/fixtures/stripe_webhook_subscription_created.json"
-      description: "Stripe webhook payload for subscription.created event"
-
-    - name: "stripe_webhook_payment_succeeded.json"
-      location: "playwright/fixtures/stripe_webhook_payment_succeeded.json"
-      description: "Stripe webhook payload for payment succeeded"
-
-  coverage:
-    lines: 85
-    branches: 85
-    critical_paths: 100
-
-dependencies:
-  requires:
-    - feature_id: "fu_700"
-      reason: "Authentication required for billing"
-    - feature_id: "fu_701"
-      reason: "RLS required for team billing isolation"
-
-  blocks:
-    - feature_id: "revenue_collection"
-      reason: "Enables revenue collection (M2 milestone: €5k MRR)"
-
-feature_flags:
-  enabled: true
-  flags:
-    - name: "enable_billing"
-      default_value: false
-      description: "Enable billing and subscription management"
-
-rollout:
-  strategy: "phased"
-  phases:
-    - name: "internal"
-      percentage: 100
-      duration_days: 7
-      description: "Internal team testing"
-    - name: "beta"
-      percentage: 10
-      duration_days: 7
-      description: "Beta user testing"
-    - name: "general"
-      percentage: 100
-      duration_days: 0
-      description: "General availability"
-
-  rollback:
-    steps:
-      - "Disable enable_billing feature flag"
-      - "Stripe subscriptions remain active (no data loss)"
-      - "Users can access via Stripe dashboard"
-    triggers:
-      - condition: "payment_success_rate < 90%"
-        action: "Automatic rollback"
-
-  monitoring:
-    key_metrics:
-      - metric: "subscription_created_total"
-        threshold: ">10 subscriptions/week (M2: €5k MRR)"
-      - metric: "payment_processed_total"
-        threshold: "success_rate > 95%"
-      - metric: "payment_processed_amount_cents"
-        threshold: "Track revenue (€5k MRR by M2)"
-
-documentation:
-  files_created:
-    - path: "docs/feature_units/completed/FU-702/billing_spec.md"
-      purpose: "Billing feature unit specification"
-    - path: "docs/subsystems/billing.md"
-      purpose: "Billing subsystem documentation"
-
-risks:
-  - category: "payment_processing"
-    likelihood: "medium"
-    impact: "high"
-    mitigation: "Stripe handles payment processing, webhook retry logic, payment failure handling"
-
-  - category: "data_loss"
-    likelihood: "low"
-    impact: "high"
-    mitigation: "Transactional subscription updates, Stripe as source of truth"
-
-  - category: "security"
-    likelihood: "low"
-    impact: "high"
-    mitigation: "No card storage, Stripe tokens only, webhook signature verification"
-
-notes: |
-  Billing is required for revenue collection to meet M2 milestone (€5k MRR by Jan 10, 2026).
-
-  Pricing strategy:
-  - Individual plans: €250–€1,250/month (€3k–€15k/yr)
-  - Team plans: €500–€2,500/month (€6k–€30k/yr) for 2–20 users
-  - Annual billing: 20% discount
-
-  Enables Tier 1 ICPs (individuals and small teams) to pay after experiencing value.
-
-links:
-  - title: "Stripe API Documentation"
-    url: "https://stripe.com/docs/api"
-  - title: "Revenue Timeline"
-    url: "../strategy_governance/revenue_timeline.md"
-  - title: "ICP Profiles"
-    url: "../specs/ICP_PROFILES.md"

package/docs/feature_units/standards/DISCOVERY_CAGAN_ALIGNMENT.md

@@ -1,214 +0,0 @@
-# Discovery Process Alignment with Marty Cagan Principles
-## Cagan's Four Product Risks
-### 1. Value Risk: Will users buy or choose to use this?
-**How Discovery Addresses This:**
-**Pre-Release Discovery:**
-- **Value Discovery Interviews**: Conduct 5-10 ICP interviews to validate:
-  - Do users actually have this problem?
-  - Does our value proposition resonate?
-  - Would users choose this over current solutions?
-- **Success Criteria**: ≥70% validate problem exists, ≥60% express interest
-**Continuous Discovery:**
-- Weekly user interviews during development
-- Validate value assumptions as features are built
-- Rapid iteration based on value feedback
-**Outcome:** Build only features that address validated user problems.
-### 2. Usability Risk: Can users figure out how to use this?
-**How Discovery Addresses This:**
-**Pre-Release Discovery:**
-- **Usability Discovery (Prototype Testing)**: User test core workflows with 5-8 users:
-  - Can users complete workflows without guidance?
-  - Is the UI discoverable?
-  - Are interactions intuitive?
-- **Success Criteria**: ≥80% complete workflows successfully, ≥80% rate usability acceptable
-**Continuous Discovery:**
-- Prototype testing after each major UI Feature Unit
-- Weekly usability check-ins during development
-- Rapid fixes based on usability findings
-**Outcome:** Build only features that users can actually use.
-### 3. Feasibility Risk: Can our engineers build this?
-**How Discovery Addresses This:**
-**Pre-Release Discovery:**
-- **Feasibility Validation**: Technical proof of concept for high-risk assumptions:
-  - Can we achieve performance targets?
-  - Are there architectural blockers?
-  - Is the technical approach viable?
-- **Success Criteria**: POC meets requirements, no architectural blockers
-**Technical Architecture:**
-- Existing feasibility validation through technical specs and architecture docs
-- Feasibility is well-validated in current plan
-**Outcome:** Build only features that are technically feasible.
-### 4. Business Viability Risk: Will this solution work for our business?
-**How Discovery Addresses This:**
-**Pre-Release Discovery:**
-- **Business Viability Discovery (Pricing Validation)**: Test business model assumptions:
-  - Will users pay for this?
-  - What price point is acceptable?
-  - What are the value drivers for paying?
-- **Success Criteria**: ≥50% express willingness to pay, ≥40% accept target price
-**Business Model Validation:**
-- Unit economics modeling
-- Customer acquisition strategy validation
-- Revenue model validation
-**Outcome:** Build only features that support a viable business model.
-## Discovery Before Delivery (Cagan's Core Principle)
-### Current Workflow (Before Discovery Integration)
-```
-Planning → Build → Deploy → Validate
-```
-**Problem:** Validates after building (too late to pivot).
-### Enhanced Workflow (With Discovery Integration)
-```
-Planning → Discover → Build → Deploy → Validate
-         ↑
-    Validate BEFORE building
-```
-**Solution:** Validates before building (can pivot early).
-## How Discovery is Integrated
-### Step 0.5: Pre-Release Discovery
-**Timeline:** 1-3 weeks before building
-**Activities:**
-1. **Value Discovery** (Week 1-2): ICP interviews validate problem and value prop
-2. **Usability Discovery** (Week 1-2): Prototype testing validates workflows
-3. **Business Viability Discovery** (Week 2): Pricing validation tests business model
-4. **Feasibility Validation** (Week 1-2): Technical POC validates assumptions
-**Go/No-Go Decision:**
-- **Go**: All critical hypotheses validated → Proceed to build
-- **Pivot**: Some hypotheses validated, some failed → Adjust scope, re-validate
-- **No-Go**: Critical hypotheses failed → Cancel or defer Release
-### Continuous Discovery During Development
-**Timeline:** Weekly during Step 1 (Execute FU Batches)
-**Activities:**
-- Weekly user interviews (2-3 users per week)
-- Prototype testing after each major UI FU
-- Rapid iteration based on feedback
-**Outcome:** Continuous validation ensures we're building the right thing.
-## Discovery Success Criteria
-### Value Discovery
-- ✅ **Problem Validation**: ≥70% of users validate problem exists
-- ✅ **Interest in Solution**: ≥60% express interest in solution
-- ✅ **Value Proposition**: ≥50% see clear value proposition
-### Usability Discovery
-- ✅ **Workflow Completion**: ≥80% complete core workflows successfully
-- ✅ **Usability Rating**: ≥80% rate usability as acceptable (≥3/5)
-- ✅ **Critical Blockers**: ≤2 critical usability blockers identified
-### Business Viability Discovery
-- ✅ **Willingness to Pay**: ≥50% express willingness to pay
-- ✅ **Price Point Acceptance**: ≥40% accept target price point
-- ✅ **Value Drivers**: Clear value drivers for paying identified
-### Feasibility Validation
-- ✅ **POC Success**: Technical POC meets requirements
-- ✅ **No Blockers**: No architectural blockers identified
-- ✅ **Performance**: Performance targets achievable
-## Discovery vs Validation
-### Discovery (Before Building)
-**Purpose:** Validate assumptions before committing resources
-**Timeline:** Pre-release (Step 0.5)
-**Methods:**
-- ICP interviews (value, business viability)
-- Prototype user testing (usability)
-- Technical POC (feasibility)
-**Outcome:** Go/No-Go decision to build or pivot
-### Validation (After Building)
-**Purpose:** Confirm outcomes after deployment
-**Timeline:** Post-release (Step 6, Release Validation Process)
-**Methods:**
-- Automated metrics retrieval (quantitative)
-- ICP interviews (qualitative)
-- User feedback analysis
-**Outcome:** Learnings for next release
-**Both are important:**
-- **Discovery**: Prevents building the wrong thing
-- **Validation**: Confirms we built the right thing
-## Example: MVP Discovery
-### Value Discovery
-**Hypothesis:** "AI-Native Operators will find value in unified document search via MCP"
-**Method:** 5-10 ICP interviews with AI-Native Individual Operators
-**Questions:**
-- Do you have a problem with fragmented documents?
-- How do you currently search for documents?
-- Would unified search via MCP be valuable?
-**Success Criteria:**
-- ≥70% validate problem exists
-- ≥60% express interest in solution
-### Usability Discovery
-**Hypothesis:** "Users can complete upload → extraction → timeline workflow without guidance"
-**Method:** Prototype user testing with 5-8 users
-**Tasks:**
-- Upload a document
-- View extracted fields
-- Navigate to timeline view
-- Ask an AI question
-**Success Criteria:**
-- ≥80% complete workflow successfully
-- ≥80% rate usability acceptable
-### Business Viability Discovery
-**Hypothesis:** "Tier 1 ICPs will pay €250-€1,250/month for Neotoma"
-**Method:** Willingness-to-pay interviews with 5-10 users
-**Questions:**
-- Would you pay for this solution?
-- What price point?
-- What features are must-have for paying?
-**Success Criteria:**
-- ≥50% express willingness to pay
-- ≥40% accept target price point
-## Key Benefits
-### 1. Reduce Risk of Building Wrong Product
-**Before Discovery:**
-- Build based on assumptions
-- Risk: Users don't want it
-- Risk: Users can't use it
-- Risk: Users won't pay for it
-**After Discovery:**
-- Build based on validated assumptions
-- Lower risk: Users validated problem
-- Lower risk: Users validated usability
-- Lower risk: Users validated pricing
-### 2. Faster Time to Product-Market Fit
-**Before Discovery:**
-- Build → Deploy → Learn → Pivot → Rebuild
-- Multiple cycles to find fit
-**After Discovery:**
-- Discover → Build → Deploy → Validate
-- Faster path to fit (fewer cycles)
-### 3. Better Resource Allocation
-**Before Discovery:**
-- Waste resources on unvalidated features
-- Build features users don't want
-**After Discovery:**
-- Focus resources on validated features
-- Build features users actually want
-## Alignment with Cagan Principles
-### ✅ Continuous Discovery
-**Cagan:** "Discovery should be continuous, not just at the beginning"
-**Neotoma Implementation:**
-- Pre-release discovery (Step 0.5)
-- Continuous discovery during development (weekly interviews)
-- Post-release validation (Step 6)
-### ✅ Discovery Before Delivery
-**Cagan:** "Validate assumptions before building"
-**Neotoma Implementation:**
-- Step 0.5 validates assumptions before Step 1 (Execute FU Batches)
-- Go/No-Go decision before committing resources
-### ✅ Testable Hypotheses
-**Cagan:** "Make assumptions explicit and testable"
-**Neotoma Implementation:**
-- Discovery plan defines explicit hypotheses
-- Success criteria are quantifiable
-- Go/No-Go decision based on evidence
-### ✅ Risk-First Approach
-**Cagan:** "Address highest risks first"
-**Neotoma Implementation:**
-- Value Risk: Value discovery interviews
-- Usability Risk: Prototype user testing
-- Feasibility Risk: Technical POC
-- Business Viability Risk: Pricing validation
-## Summary
-Neotoma's Discovery Process fully addresses Cagan's discovery vs delivery principles:
-1. **✅ Discovery Before Delivery**: Step 0.5 validates assumptions before building
-2. **✅ Continuous Discovery**: Weekly interviews and prototype testing during development
-3. **✅ Addresses All Four Risks**: Value, Usability, Feasibility, Business Viability
-4. **✅ Testable Hypotheses**: Explicit hypotheses with quantifiable success criteria
-5. **✅ Risk-First Approach**: Validates highest risks first
-**Result:** Build the right product, faster, with lower risk.
-**END OF DOCUMENT**