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
- [x] Application admin model: define app-wide `admin` as a separate identity domain from workspace memberships (`owner`/`member`).
- [x] Implement DB-backed app-admin identities as the primary source of truth (active/disabled status, normalized email principal, optional scoped permissions, audit fields).
- [x] Add migration path for current internal admin access: keep temporary env fallback only during rollout, then remove once DB-seeded admins are verified.
- [x] Centralize admin authorization middleware (`requireAdmin`) and replace route-local billing-admin checks so `/admin/*` authorization semantics are consistent.
- [x] Add admin audit visibility: log admin route access and key admin support actions with actor, route/action, target workspace, and timestamp.
- [x] 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) Admin Dashboard / Console Incremental Plan
- [x] Phase A (Read-only Admin Console foundation): Create dedicated admin page(s) separate from Account page and gate all access to app-admin users only.
- [x] Phase A (Read-only Admin Console foundation): Add admin navigation entry/tab visible only to app-admin users.
- [x] Phase A (Read-only Admin Console foundation): Move existing admin billing visibility tools (workspace search + workspace detail) from Account page to admin page.
- [x] Phase A (Read-only Admin Console foundation): Add admin analytics summary panel on admin page powered by `/admin/analytics/summary`.
- [x] Phase A (Read-only Admin Console foundation): Keep server-side `requireAdmin` as the source of truth (UI checks are convenience only).
- [x] Phase B (Admin Access Management): Add admin-only APIs for listing, adding, disabling, and re-enabling application admins.
- [x] Phase B (Admin Access Management): Add admin UI for managing app-admin identities with status visibility (active/disabled).
- [x] Phase B (Admin Access Management): Prevent accidental lockout with guardrails (e.g., disallow disabling the last active admin).
- [x] Phase B (Admin Access Management): Add explicit audit entries for admin identity mutations.
- [x] Phase C execution split (implementation sequencing)
  - [x] Sub-step 1 (Backend foundations): ship admin audit list API + security posture API + diagnostics aggregate API, plus shared types/client contracts.
  - [x] Sub-step 2 (Admin Console UI): add audit explorer table/filters, security posture card, and diagnostics widgets with drill-down links.
  - [x] Sub-step 3 (Hardening & operations): normalize audit action taxonomy, tune indexes/query performance, and finalize runbook/alerts for repeated failures.
- [x] Phase C (Audit & Support Operations): Add admin audit log page/table with filters (actor, action, workspace, date window).
  - [x] Add backend admin audit-list endpoint with filters for actor email, action, workspace ID, date range, and pagination.
  - [x] Review audit-log query performance and indexes to ensure efficient filtering and default sorting by `occurred_at DESC`.
  - [x] Implement admin audit table UI with filter controls plus clear loading, empty, and error states.
  - [x] Normalize admin audit action taxonomy so admin-route events use consistent action names.
- [x] Phase C (Audit & Support Operations): Expose bootstrap/security posture checks in admin UI (bootstrap enabled state, fallback allowlist usage warnings).
  - [x] Add backend admin security-posture endpoint returning `bootstrapRequired`, `bootstrapEnabled`, and fallback allowlist usage status.
  - [x] Add warning semantics when deprecated `BILLING_ADMIN_EMAILS` fallback is active.
  - [x] Add admin UI security-posture card with explicit remediation guidance for risky states.
  - [x] Document post-bootstrap hardening checklist: disable bootstrap, rotate bootstrap token, and verify at least two active admins.
- [x] Phase C (Audit & Support Operations): Add support-oriented diagnostics widgets (recent webhook issues, billing sync errors, timeline anomalies).
  - [x] Add backend diagnostics endpoint aggregating recent failed webhook events, stale billing-sync accounts, and recent timeline-anomaly counts.
  - [x] Define timeline-anomaly heuristics (for example: repeated `payment_failed`, pending plan effective date in the past, and stale sync threshold breaches).
  - [x] Add admin diagnostics widgets with counts and drill-down links to existing workspace detail views.
  - [x] Define alerting and runbook follow-up tasks for repeated failures surfaced by diagnostics.
- [ ] Phase D (Safe Mutations, later): Keep initial admin console read-only for billing data; defer write/mutation actions until policies and runbooks are defined.
  - [x] Pilot: add constrained `billing resync` admin mutation with non-destructive intent and explicit operator guidance.
- [ ] Phase D (Safe Mutations, later): For future write actions, require explicit confirmations, actor attribution, and rollback guidance.
  - [x] Pilot guardrails in place: required reason, typed confirmation (`RESYNC`), optional `ticketRef`, and admin audit attribution.

## 13) [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.

## 14) [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.

## 15) 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 7a: ship dedicated read-only admin console and migrate existing admin billing tools out of the account page.
- [ ] Phase 7b: ship app-admin identity management APIs/UI with last-admin lockout protection and audit logging.
- [x] Phase 7c: ship admin audit explorer and support diagnostics views (Phase C from section 12).
- [ ] Phase 7d: evaluate controlled admin write-actions only after policy/runbook readiness.
- [ ] Phase 7e: MinIO/object-storage foundation + dataset registry schema.
- [ ] Phase 7f: postal ingestion worker pipeline + admin APIs.
- [ ] Phase 7g: admin console postal dataset operations and activation workflow.
- [ ] 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.

## 16) Multi-Country Postal Dataset Onboarding (MinIO-backed)
- Architecture decision
  - [ ] Standardize on self-hosted MinIO (S3-compatible) for postal dataset storage and processing.
  - [ ] Retire host-mounted files and manual CLI-only import as primary onboarding paths.
- Infrastructure/bootstrap
  - [ ] Add MinIO service to Docker deployment with persistent volume and health checks.
  - [ ] Define credential bootstrap/rotation expectations and automated bucket creation for postal datasets.
  - [ ] Document backup/restore expectations (RPO/RTO target, snapshot cadence, and restore verification).
- Config/env
  - [ ] Add and document `S3_ENDPOINT`, `S3_REGION`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_FORCE_PATH_STYLE`, and `S3_BUCKET_POSTAL_DATASETS`.
  - [ ] Wire S3-compatible config into both API and worker runtime boot paths.
- Data model
  - [ ] Add `postal_datasets` schema for object metadata, versioning, and activation status lifecycle.
  - [ ] Add `postal_dataset_runs` schema for run tracking, timing, actor/source metadata, and run types.
  - [ ] Add `postal_country_support` schema/state fields for per-country readiness, coverage, and active dataset linkage.
  - [ ] Define lifecycle states and transitions (draft, uploaded, validated, processing, ready, active, failed, archived) and enforce transition guards.
- API/admin flows
  - [ ] Add admin-authenticated dataset register + upload URL flow for object ingest.
  - [ ] Add validate/process/activate endpoints and dataset run history/read APIs.
  - [ ] Require admin authorization and audit logging for all mutating dataset actions.
- Worker pipeline
  - [ ] Implement queued jobs: `postal.validate`, `postal.import`, `postal.neighbors`, `postal.check`, `postal.activate`.
  - [ ] Enforce idempotency keys and per-country mutex/locking to prevent conflicting runs.
  - [ ] Track progress checkpoints and standard retry/backoff policy with terminal failure states.
- Country adapters
  - [ ] Implement pluggable country-specific validation/normalization profiles.
  - [ ] Enforce country geometry/topology constraints (bounds, shapes, adjacency expectations) during validation.
- Safety/operability
  - [ ] Keep activation behind an explicit admin gate after successful checks.
  - [ ] Preserve previous active dataset for rollback and support fast re-activation.
  - [ ] Add alerts and runbook steps for failed, stalled, or long-running jobs.
- UX/admin console
  - [ ] Add postal dataset list with status, country, version, and activation markers.
  - [ ] Add run logs/error visibility and filtered run history in admin console.
  - [ ] Add activation controls with confirmation guardrails and rollback visibility.
  - [ ] Add per-country readiness visibility so operators can see launch coverage at a glance.