leads4less/TODO-pricing.md

TODO: LocaleScope Pricing & Packaging Design

Goals

• Position LocaleScope as a local market intelligence platform, not a scraper/export commodity.
• Align pricing, packaging, product capabilities, and billing enforcement to a single plan model.
• Protect infrastructure with quotas, credits, throttling, and priority processing.
• Preserve room for future AI, enrichment, API, collaboration, and enterprise expansion.

Open Questions

• What is the initial break-glass process if all app admins are disabled or misconfigured (seed command, SQL playbook, or deployment-time bootstrap)?
• Should app-admin permissions launch as full-access first, or start with explicit scopes (e.g., billing.read, analytics.read) from day one?
• Will research capacity be marketed as runs, credits, or both?
• Which collaboration/team features are truly launch-ready?
• Should workspace limits be hard-enforced at launch or soft-gated initially?
• Which add-ons launch on day one vs later?
• Is founder/LTD part of launch or a separate campaign?
• What exact enterprise triggers require custom sales instead of self-serve?
• Which plan data belongs in the canonical catalog versus presentation metadata?

1) Product & Marketing Alignment

• Decide whether to update historical/internal naming artifacts separately:
  • CHANGELOG.md historical branding references
  • package.json package name

2) Canonical Plan Definitions

• Follow-up recommendation: clarify whether getPlanByCode should stay active-catalog-only or be renamed to make reserved-code behavior explicit.
• Follow-up recommendation: revisit whether planFamily should remain separate from tier or be consolidated later.
• Follow-up recommendation: consider moving shared plan price/period formatting helpers into the billing domain once account and pricing UI expand.
• Follow-up recommendation: extend readiness modeling beyond feature flags if later steps need readiness for support, processing, or add-on availability.

3) Packaging & Entitlement Model

• Future note: evaluateActionEntitlement() is policy-only and later steps must provide real remaining-usage inputs from subscription/account state.
• Future note: missing readiness metadata currently implies launch_ready; keep readiness annotations current as new gated features are added.
• Future note: api_requests and enrichments are modeled ahead of full product implementation; do not treat them as launch-ready by default.
• Future note: deep research costing should stay aligned with preview-derived estimates and should not diverge into a second billing algorithm.
• Future note: export policy is defined, but reliable export enforcement requires a future backend export endpoint.
• Future note: usage subject remains user until workspace-scoped ownership and pooled usage are ready.
• Future note: territoryMapping currently carries deep-research capability semantics and may need a dedicated capability later if gating becomes more granular.

4) Feature Gates by Plan

• Future note: make upgrade recommendations readiness-aware so users are not prompted to upgrade into tiers where the target feature is still coming_soon.
• Future note: consolidate action ↔ feature mapping into one canonical source shared by entitlements.ts and feature-gates.ts to avoid drift between UI gating and backend action policy.
• Future note: for Enterprise plans, included-but-not-ready features should usually resolve to coming_soon instead of contact_sales.
• Future note: revisit the fallback coming_soon state for unavailable or unmapped features before broad UI rollout so hidden vs upgrade vs future behavior stays intentional.

5) Billing & Data Model Design

• Future note: remaining = 0 for not_available resources is intentional and should stay aligned with entitlement semantics.
• Future note: expired billing periods should fail closed for current usage-window resolution until subscription lifecycle automation can advance billing periods reliably.
• Future note: consider exposing usagePeriodId later if enforcement, debugging, or admin tooling needs period-level traceability.
• Future note: add transactional workflows around billing-account updates, usage updates, and add-on purchase/balance mutations once real payment flows are introduced.
• Future note: plan_code is currently unconstrained text in the database; keep application-side validation strict unless a later migration adds stronger DB validation.
• Future note: usage ownership is workspace-scoped in storage, but current operational enforcement is still catching up to that model.

6) Enforcement Architecture

• Future note: the current enforcement slice should be treated as the core entitlement/runtime gate, not the full operational control layer.
• Future note: the default Starter bootstrap is a pre-payments usability policy and should be revisited when real subscription lifecycle automation is implemented.

7) Workspace, User, and Collaboration Readiness

• Future note: before true collaboration is sold as real runtime behavior, core domain entities need workspace_id ownership and repository/query updates.
• Future note: users included and workspace limits should remain soft-gated until multi-workspace UX and shared data ownership mature.
• Future note: shared lists, tagging/notes, and collaboration permissions should not be treated as hard-enforceable features until the workspace migration is complete.

8) Pricing Page & Account UX

• Future note: the pricing comparison table should stay aligned with workspace-readiness decisions as collaboration and shared asset features move toward workspace ownership.
• Future note: upgrade CTAs are present, but actual checkout/subscription management should remain tied to the post-payments hardening step.
• Future note: pricing and account UX should keep users included, workspace limits, and collaboration-adjacent promises explicitly soft-gated until workspace-owned shared data and hard enforcement are ready.
• Future note: replace placeholder upgrade CTAs in the account billing UI with a real upgrade path, pricing-page jump, contact-sales flow, or explicit coming soon behavior before broader rollout.

9) Add-On Strategy

• Future note: launch active add-ons should stay limited to one-time export packs until enrichment delivery and payments lifecycle handling are live.
• Future note: recurring feature add-ons should not be sold until the underlying capabilities and subscription management flows exist end-to-end.

10) Payments Integration

• Future note: Stripe is now the active integration path; keep the internal plan/add-on catalog as the canonical packaging source and treat Stripe price IDs as environment-specific mappings.
• Future note: the current customer-facing integration supports self-serve subscriptions, export-pack checkout, and the Stripe billing portal, while enterprise invoicing remains a manual sales workflow.
• Future note: webhook idempotency currently relies on the billing_webhook_events store; keep Stripe event processing centralized there as billing lifecycle coverage expands.
• Future note: post-payments hardening should tighten downgrade, cancellation, retry, and grace-period policy before broad rollout so Stripe portal actions and runtime entitlements stay aligned.

11) Post-Payments Hardening & Admin Visibility

• Application admin model: define app-wide admin as a separate identity domain from workspace memberships (owner/member).
• Implement DB-backed app-admin identities as the primary source of truth (active/disabled status, normalized email principal, optional scoped permissions, audit fields).
• Add migration path for current internal admin access: keep temporary env fallback only during rollout, then remove once DB-seeded admins are verified.
• Centralize admin authorization middleware (requireAdmin) and replace route-local billing-admin checks so /admin/* authorization semantics are consistent.
• Add admin audit visibility: log admin route access and key admin support actions with actor, route/action, target workspace, and timestamp.
• Define explicit downgrade behavior:
  • effective timing for scheduled vs immediate plan changes
  • entitlement/usage treatment when the target plan is below current usage
  • account messaging for pending downgrade state

12) [DEFER] Operational Enforcement Follow-Up

• Add queue prioritization by plan tier.
• Add throttling/fair-usage controls.
• Add export-route enforcement once CSV/export generation moves to a backend endpoint.
• Add enrichment-route enforcement once enrichment actions/routes are implemented.
• Future note: queue prioritization is deferred until async worker routing or higher-volume queued execution becomes an active runtime path.
• Future note: throttling/fair-usage controls are deferred until higher-volume execution patterns require operational protection.
• Future note: export enforcement remains deferred until CSV/export generation moves to a backend endpoint.
• Future note: enrichment-route enforcement remains deferred until enrichment actions/routes are implemented.

13) [DEFER] Founder / LTD Strategy

• Decide whether to launch founder LTD at all.
• If yes, define strict quantity cap (e.g. first 100-250 customers).
• Define founder SKUs:
  • Founder Plan = $249 one-time
  • Founder Pro = $499 one-time
• Ensure founder plans have monthly quotas and exclude unlimited compute/API.
• Define which future features are excluded from LTD plans.

14) Rollout Plan

• Phase 1: finalize canonical plan definitions, presentation metadata boundaries, and entitlement model.
• Phase 2: implement usage ledger and backend enforcement.
• Phase 3: review workspace, user, and collaboration readiness before expanding team/workspace promises.
• Phase 3a: execute workspace-role migration (owner/member only), convert legacy workspace admins to members by default, and validate owner-only management paths.
• Phase 3b: launch DB-backed app-admin identity management and migrate /admin/* authorization to centralized app-admin middleware.
• Phase 4: update pricing page and account/billing UI based on the workspace/collaboration readiness decisions.
• Phase 5: finalize add-on strategy before wiring payment products.
• Phase 6: integrate payments and subscription lifecycle handling.
• Phase 7: harden post-payments lifecycle handling, wire real billing CTAs, and add pragmatic admin billing visibility before broader commercialization work.
• Phase 8: expand analytics, ops, and revenue instrumentation around the live billing and upgrade flows.
• Phase 9: launch collaboration, API, enrichment, and enterprise features as architecture matures.
• Phase 10: complete deferred operational enforcement work such as queue prioritization, throttling, and backend export enforcement when runtime scale justifies it.
• Phase 11: decide and implement founder/LTD strategy only after the app/site, billing lifecycle, admin/support visibility, analytics, and broader product maturity work are in place.