Continu V1 Port Ledger

This document is the source of truth for rebuilding the proven Continu v1 behavior inside the new starter scaffold.

Use it to answer four questions without guesswork:

1. What existed in Continu v1?
2. What already exists in the current starter?
3. What is only partially ported?
4. What is still missing and needs an explicit decision or implementation pass?

This replaces a journey-only checklist with a status-tracked port ledger.

Goal

Rebuild the Continu v1 product behavior inside apps/app and packages/backend using the new surface-first structure:

• behavior and product rules from v1
• route ownership, file placement, and simplification from the current starter

The target is not a pixel-for-pixel or file-for-file copy. The target is a cleaner, easier-to-maintain version of the same product.

Status Legend

• Done: current repo already preserves the v1 behavior closely enough to build on it
• Partial: some route/backend/test coverage exists, but v1 parity is incomplete or only the main slice is present
• Missing: no meaningful v1 parity yet
• Intentional defer: v1 had it, but it should not block the current core loop and must be scheduled explicitly before porting

Non-Negotiable Port Rules

• Copy behavior, not folder structure.
• Preserve business rules, permissions, lifecycle states, and edge cases.
• Do not recreate v1 feature scaffolding inside the new app.
• Keep route files thin and keep route-owned composition local.
• Promote code only when reuse is real.
• Treat any v1 surface as incomplete until its backend behavior, UI state handling, and critical tests all agree.
• If a v1 capability is intentionally not being ported, record that explicitly instead of silently omitting it.

Snapshot

Area	Status	Notes
Org onboarding and org creation	Done	Core creation flow and current-org initialization are in place
Current org context and org switching	Done	Selected-org persistence and switching are already landed
Org-managed portal access	Partial	Main invite/member lifecycle exists; broader settings parity is not complete
Portal first-run and welcome flow	Done	First-run profile creation and tenant-aware welcome flow are landed
Portal dashboard and settings parity	Partial	Overview, settings, activity, support, notifications/preferences, and suspended flow all exist; staff-facing activity visibility decisions and legacy preference migration are the only remaining open items
Org settings suite	Partial	Root surface plus account, billing, custom-domain, api-access, webhooks, audit-log, exports, notifications, roles, security, and the team-management surface all exist; billing depth and a broader parity sweep on edge states still remain
Platform auth and invite/bootstrap flow	Done	Public auth, first-admin bootstrap, platform invite lifecycle, and the platform-admin boundary are all in place
Platform console	Partial	Admin management, org/user oversight with detail drill-downs, subscriptions control plane, audit, and settings with control-plane and MFA recovery are all live; fuller cross-tenant governance and system-settings depth remain
Billing, trials, subscriptions, and entitlements	Partial	Subscription/trial state, Polar reconciliation, cancellation/reactivation, platform subscriptions control plane, and entitlement-backed settings surfaces all exist; plan-change/downgrade UX, product-usage limits, and Polar products cache/reconciliation are still missing
API keys, webhooks, custom domains, and advanced org ops	Partial	API access, webhooks, custom-domain, exports, usage/automation visibility, and session governance are all live; plan-change/downgrade UX and any remaining security-governance depth are still open
Audit logs, exports, and ops side effects	Partial	First-pass entitlement-backed org settings visibility now exists, org audit-log browsing is live, and export request/download workflows now cover a broader tenant-operations snapshot, but broader audit coverage and deeper operational exports still remain incomplete
Feature flags and platform-level system controls	Partial	First-pass maintenance mode, platform feature flags, backend kill switches, governance audit visibility, and starterkit proxy/public maintenance handling now exist, but the remaining cross-tenant system controls are still incomplete

Detailed Inventory

1. Org Foundation

1.1 Org onboarding and creation

• Status: Done
• V1 source anchors:
  • reference-apps/continu/apps/app/src/app/[locale]/org/onboarding/page.tsx
  • reference-apps/continu/apps/app/src/features/organization/onboarding/*
  • reference-apps/continu/packages/backend/convex/organizations/creation.ts
• Current starter anchors:
  • apps/app/src/app/[locale]/org/onboarding/page.tsx
  • packages/backend/convex/organizations/creation.ts
• Behavior that must survive:
  • first organization creation
  • subdomain reservation and validation
  • selected/current organization initialization after creation
  • clean already-complete state
• Remaining gaps:
  • verify any v1-specific copy variants or setup-complete nuance before calling this permanently closed

1.2 Current organization context and switching

• Status: Done
• V1 source anchors:
  • reference-apps/continu/packages/backend/convex/organizations/switching.ts
  • v1 org context/provider behavior in the organization surface
• Current starter anchors:
  • packages/backend/convex/organizations/current.ts
  • packages/backend/convex/organizations/switching.ts
  • org account-menu switching in the current app shell
• Behavior that must survive:
  • multi-org support
  • selected-org persistence
  • zero-org, one-org, and many-org handling
  • role-aware org context delivery
• Remaining gaps:
  • none currently blocking the core loop

1.3 Org staff invites, memberships, and ownership

• Status: Partial
• V1 source anchors:
  • reference-apps/continu/packages/backend/convex/organizations/invitation_management.ts
  • reference-apps/continu/packages/backend/convex/organizations/invitation_acceptance.ts
  • reference-apps/continu/packages/backend/convex/organizations/organization_staff_management.ts
  • reference-apps/continu/packages/backend/convex/organizations/organization_staff_ownership.ts
• Current starter anchors:
  • org invitation and membership modules in packages/backend/convex/organizations/*
  • org-facing settings surfaces under apps/app/src/app/[locale]/org/(dashboard)/settings*
• Behavior that must survive:
  • org invite create/resend/revoke/accept lifecycle
  • staff role changes and removal
  • ownership transfer and membership safety rules
• What is already true:
  • organization-scoped staff membership and selected-org persistence are already implemented in the backend baseline
• Remaining gaps:
  • treat the full v1 org staff management surface as incomplete until the UI flow, edge states, and tests are deliberately confirmed

2. Org-Managed Portal Access

2.1 Portal invite and member lifecycle from the org dashboard

• Status: Partial
• V1 source anchors:
  • reference-apps/continu/packages/backend/convex/organizations/portal_invitations.ts
  • reference-apps/continu/packages/backend/convex/organizations/portal_directory.ts
  • reference-apps/continu/packages/backend/convex/organizations/portal_lookup.ts
  • v1 org-facing portal access UI in reference-apps/continu/apps/app/src/features/organization/*
• Current starter anchors:
  • current portal-access content inside the org dashboard settings surface
  • packages/backend/convex/organizations/portal_*
• Behavior that must survive:
  • invite create/resend/revoke/accept
  • org-scoped portal membership management
  • conflict guards for staff/platform-admin/duplicate portal identities
  • clear member and invite status rules
• What is already true:
  • main invite/member backend behavior is landed
  • focused tests exist for create/resend/revoke and inline invite feedback
• Remaining gaps:
  • verify the full v1 lifecycle state machine end to end
  • confirm parity for all org-facing role/status transitions, not just the main happy path

3. Portal Surface

3.1 Portal first-run and welcome flow

• Status: Done
• V1 source anchors:
  • portal welcome/onboarding flows in reference-apps/continu/apps/app/src/features/portal/onboarding/*
  • reference-apps/continu/packages/backend/convex/organizations/portal_profile.ts
• Current starter anchors:
  • apps/app/src/app/[locale]/portal/(public)/page.tsx
  • packages/backend/convex/organizations/portal_profile.ts
• Behavior that must survive:
  • unauthenticated state
  • first-run profile creation
  • already-authorized redirect behavior
  • tenant-aware copy and context
• Remaining gaps:
  • none currently blocking the core first-run path

3.2 Portal dashboard and settings parity

• Status: Partial
• V1 source anchors:
  • reference-apps/continu/apps/app/src/features/portal/dashboard/*
  • reference-apps/continu/apps/app/src/features/portal/settings/*
  • reference-apps/continu/apps/app/src/features/portal/activity/*
  • reference-apps/continu/apps/app/src/features/portal/support/*
• Current starter anchors:
  • apps/app/src/app/[locale]/portal/(dashboard)/overview/page.tsx
  • apps/app/src/app/[locale]/portal/(dashboard)/settings/page.tsx
• Behavior that must survive:
  • portal overview/dashboard entry
  • profile/security/activity settings semantics
  • clear tenant-only access enforcement
• What is already true:
  • portal overview, settings, and activity now have tenant-clean route handling instead of relying only on internal /portal/* paths
  • portal settings now exposes a first real support/help surface and tenant support-contact guidance
  • suspended portal memberships now route to a dedicated public suspended flow instead of falling through generic holding states
  • portal activity and settings loading states now use shaped placeholders instead of message-only loading panels
  • portal preferences now split product, support, account-activity, marketing, and digest settings while keeping the rollout backward-compatible with older preference rows
  • portal activity now persists real account/access events instead of relying only on a first-pass derived timeline
• Remaining gaps:
  • staff-facing parity decisions for which portal activity should also be visible from org operations
  • any future migration pass to remove the legacy coarse preference columns after backfill

3.3 Portal email preferences, activity, and suspended handling

• Status: Partial
• V1 source anchors:
  • reference-apps/continu/packages/backend/convex/organizations/portal_email_preferences.ts
  • reference-apps/continu/packages/backend/convex/organizations/portals_activity.ts
  • suspended route handling in the v1 portal public flow
• Current starter anchors:
  • current portal route tree under apps/app/src/app/[locale]/portal
• Behavior that must survive:
  • tenant-scoped preferences
  • activity visibility for portal members and staff
  • suspended-route enforcement and portal-state clarity
• What is already true:
  • tenant portal activity now has working clean-route access, a persisted real-event history, and richer status-aware timeline entries
  • tenant portal settings now include clearer support-email semantics and a dedicated support/help route
  • suspended portal memberships now have a dedicated public /portal/suspended flow, and tenant-host routing now redirects suspended users there instead of letting them wander protected routes
• Remaining gaps:
  • broader portal/staff shared visibility decisions for activity data
  • any later migration cleanup for legacy preference fields once existing rows are backfilled everywhere

4. Org Settings Suite

4.1 Root settings surface

• Status: Partial
• V1 source anchors:
  • reference-apps/continu/apps/app/src/features/organization/settings/*
• Current starter anchors:
  • apps/app/src/app/[locale]/org/(dashboard)/settings/page.tsx
• Behavior that must survive:
  • one clear org settings entry surface
  • access to the important operational sub-surfaces without v1-style sprawl
• Remaining gaps:
  • decide what belongs as first-class tabs/pages in the simpler v2 structure

4.2 Settings sub-surfaces present in v1 and still missing or incomplete

• Status: Partial
• V1 source anchors:
  • reference-apps/continu/apps/app/src/features/organization/api-keys/*
  • reference-apps/continu/apps/app/src/features/organization/audit-logs/*
  • reference-apps/continu/apps/app/src/features/organization/custom-domain/*
  • reference-apps/continu/apps/app/src/features/organization/data-export/*
  • reference-apps/continu/apps/app/src/features/organization/security/*
  • reference-apps/continu/apps/app/src/features/organization/usage/*
  • reference-apps/continu/apps/app/src/features/organization/webhooks/*
• Current starter anchors:
  • apps/app/src/app/[locale]/org/(dashboard)/settings/page.tsx
• V1 behaviors to account for explicitly:
  • API key creation/revocation and protected access
  • webhook CRUD and delivery visibility
  • custom domain add/verify/remove
  • audit-log visibility
  • export request lifecycle
  • usage/entitlement visibility
  • security settings beyond the basic auth baseline
• What is already true:
  • org settings now includes a first entitlement-backed premium-operations section for API access, webhooks, audit logs, and exports
  • entitlement state is derived from the current live subscription snapshot rather than custom-domain-only gating
  • org settings now has the first real audit-log workflow, backed by persisted organization audit entries for settings, billing, and custom-domain changes
  • org settings now has the first real webhook management workflow, including endpoint creation, test delivery, signing-secret rotation, enable/disable, deletion, delivery-attempt history, manual retry visibility, and real deliveries from live org events
  • org settings now has the first real API access workflow through credential issuance, revocation, and a starterkit operational endpoint that records last-used timestamps on real token-authenticated calls
  • org settings now has the first real export workflow through request creation, status tracking, and JSON download for a broader tenant-operations snapshot
  • org settings now has a dedicated usage and automation visibility slice, surfacing plan-backed entitlement state, operator footprint, recent webhook/API/export activity, and actionable health signals for premium operations
  • org settings now has a dedicated security-depth session-governance slice, surfacing active-session posture, per-session MFA and session-security visibility, and a revoke-other-session workflow that also clears revoked-session security state
• Port note:
  • these should not be treated as complete until the remaining broader cross-surface security and operator-governance work lands outside the org-owned settings slice

5. Platform Surface

5.1 Platform public auth versus actual admin bootstrap

• Status: Done
• V1 source anchors:
  • reference-apps/continu/apps/app/src/app/[locale]/platform/(public)/(setup)/invite/page.tsx
  • reference-apps/continu/apps/app/src/features/platform/setup/*
  • reference-apps/continu/packages/backend/convex/platform/invitations.ts
  • reference-apps/continu/packages/backend/convex/platform/bootstrap.ts
• Current starter anchors:
  • apps/app/src/app/[locale]/platform/(public)/(auth)/login/page.tsx
  • apps/app/src/app/[locale]/platform/(public)/(auth)/signup/page.tsx
  • apps/app/src/app/[locale]/platform/(public)/(auth)/forgot-password/page.tsx
  • apps/app/src/app/[locale]/platform/(public)/(flow)/setup/page.tsx
  • apps/app/src/app/[locale]/platform/(public)/(flow)/invite/page.tsx
  • packages/backend/convex/system/bootstrap.ts
  • packages/backend/convex/platform/invitations.ts
• What is already true:
  • public auth routes exist
  • first-platform-admin bootstrap now has a public setup flow at /platform/setup backed by system/bootstrap:getPlatformSetupState and system/bootstrap:initializeFirstPlatformAdmin
  • platform invite acceptance now has a public /platform/invite flow backed by the grouped platform/invitations lifecycle
  • platform invite create/resend/revoke behavior now exists on top of the same platformUsers membership model instead of introducing a parallel access path
  • the minimal platform-admin boundary is now explicit in backend invitation checks and platform access queries

5.2 Platform console and oversight surfaces

• Status: Partial
• V1 source anchors:
  • reference-apps/continu/apps/app/src/features/platform/overview/*
  • reference-apps/continu/apps/app/src/features/platform/users/*
  • reference-apps/continu/apps/app/src/features/platform/platform-admins/*
  • reference-apps/continu/apps/app/src/features/platform/organizations/*
  • reference-apps/continu/apps/app/src/features/platform/analytics/*
  • reference-apps/continu/apps/app/src/features/platform/subscriptions/*
  • reference-apps/continu/apps/app/src/features/platform/audit-logs/*
  • reference-apps/continu/apps/app/src/features/platform/settings/*
  • reference-apps/continu/packages/backend/convex/platform/*
• Current starter anchors:
  • apps/app/src/app/[locale]/platform/(dashboard)/page.tsx
  • apps/app/src/app/[locale]/platform/(dashboard)/organizations/page.tsx
  • apps/app/src/app/[locale]/platform/(dashboard)/users/page.tsx
  • packages/backend/convex/platform/directory.ts
• Behavior that must survive:
  • platform overview
  • cross-org user/org/portal visibility
  • platform-admin invitations and admin management
  • system analytics, subscription oversight, audit logs, and system settings
• What is already true:
  • /platform now ships the first real oversight surface instead of a placeholder shell
  • platform admins can issue invites, resend or revoke pending invites, inspect outstanding invite state, and review current platform admin memberships from the dashboard
  • platform organizations now surface owner identity, active org/portal membership counts, and first-pass subscription/trial state
  • platform users now surface org membership counts, portal membership counts, active platform status, and whether a platform identity remains exclusive
  • platform user detail now exposes the first real operator-management slice from v1 parity work: suspend/reactivate with required reason capture, forced email verification, password-reset dispatch, guarded account deletion, delete-block visibility for owned organizations or last-admin cases, and per-membership org/portal suspension controls from the same platform surface
  • platform dashboard now includes aggregate analytics, a subscription watchlist, and recent cross-tenant activity visibility derived from live membership/invite/org records
  • platform organization detail pages now provide tenant-level billing drill-downs with richer lifecycle visibility, entitlement impact summaries, and operator guidance
  • dedicated /platform/subscriptions, /platform/audit, and /platform/settings surfaces now exist for subscription oversight, platform security audit review, and operator security/preferences management
  • platform settings now includes a first real control-plane slice for maintenance mode and platform feature flags, backed by persisted system settings and governance audit entries
  • maintenance mode now routes non-platform traffic through a public maintenance page in the v2 proxy while preserving platform auth and platform-admin access as the operator recovery path
  • platform feature flags now gate real backend behavior for organization creation, portal invitations, org audit visibility, org API credential usage, exports, and webhook operations instead of acting as display-only toggles
  • platform-admin MFA recovery now uses a reasoned request plus separate approval-note workflow, and the requester cannot approve the same reset
• Remaining gaps:
  • fuller platform system-settings depth still needs deliberate v2 ports, including the remaining cross-tenant governance workflows beyond the first flag-backed kill switches

6. Billing, Trials, Subscriptions, and Entitlements

6.1 Billing model and backend integration

• Status: Partial
• V1 source anchors:
  • reference-apps/continu/packages/backend/convex/subscriptions/core.ts
  • reference-apps/continu/packages/backend/convex/subscriptions/trial.ts
  • reference-apps/continu/packages/backend/convex/subscriptions/billing.ts
  • reference-apps/continu/packages/backend/convex/subscriptions/checkouts.ts
  • reference-apps/continu/packages/backend/convex/subscriptions/products_cache.ts
  • reference-apps/continu/packages/backend/convex/subscriptions/billing_cache.ts
  • reference-apps/continu/packages/backend/convex/subscriptions/create_billing_account.ts
  • reference-apps/continu/packages/backend/convex/organizations/subscription_info.ts
  • reference-apps/continu/packages/backend/convex/platform/subscriptions.ts
• Behavior that must survive:
  • organization-level subscription state
  • trials and trial end semantics
  • checkout generation and billing portal entry
  • subscription cache/sync model
  • entitlements and plan limits
  • platform-side subscription oversight
• Current starter reality:
  • organizations now carry first-pass subscription and trial state directly on the organization record
  • orgs can start an initial trial from the current starter
  • platform organization oversight can now inspect trial/subscription state across tenants
  • platform now has a dedicated subscriptions control plane for cross-tenant billing review in addition to dashboard watchlists and tenant drill-down pages
  • org settings now exposes configured paid-plan checkout actions and billing-portal launch entry
  • Polar webhook intake now exists and can reconcile customer id, subscription id, tier, cancellation-window fields, and richer subscription lifecycle status back onto organizations
  • org settings now supports direct period-end cancellation and reactivation on top of synced Polar subscription state
  • first-pass entitlement enforcement now exists: custom-domain creation is gated from the organization subscription state instead of being UI-only
  • org settings now exposes first-pass entitlement-backed premium operations visibility for API access, webhooks, audit logs, and exports
  • platform organizations now support tenant-level billing drill-downs for richer subscription attention states beyond the dashboard watchlist
• Port note:
  • product cache/reconciliation and the remaining entitlement-backed org surfaces are still missing

6.2 Org-facing billing UI

• Status: Partial
• V1 source anchors:
  • reference-apps/continu/apps/app/src/features/organization/subscription/*
• Current starter anchors:
  • apps/app/src/app/[locale]/org/(dashboard)/overview/page.tsx
  • apps/app/src/app/[locale]/org/(dashboard)/settings/page.tsx
  • packages/backend/convex/organizationBilling.ts
• Behavior that must survive:
  • current subscription state visibility
  • trial visibility
  • upgrade/downgrade and cancellation entrypoints
  • billing-portal access
  • What is already true:
    • org overview and settings now show the current subscription/trial state
    • org settings now has a first trial-start action for the current organization
    • org settings now exposes plan-selection checkout actions and keeps plan changes, cancellation, and reactivation in-app
    • org settings now exposes the provider billing portal only when one synced Polar customer maps cleanly to one organization
    • org settings now supports direct period-end cancellation and reactivation when a synced Polar subscription exists
    • org overview/settings now surface richer subscription lifecycle states beyond active/canceled
  • Remaining gaps:
    • product-usage limits and deeper in-app invoice/payment-method workflows for shared-provider-customer cases are still missing

7. Shared Auth, Invites, and Supporting Control Planes

7.1 Shared auth baseline

• Status: Partial
• V1 source anchors:
  • auth/session/two-factor/user-account modules across reference-apps/continu/packages/backend/convex/auth/* and related user modules
• Current starter anchors:
  • current auth/session baseline in packages/backend/convex/auth/*
• What is already true:
  • the starter already has meaningful auth foundations
• Remaining gaps relative to v1 parity:
  • confirm whether broader step-up coverage, session-management polish, and any v1-specific device/session governance requirements still need to be carried over

7.2 Platform-level feature flags and system settings

• Status: Partial
• V1 source anchors:
  • reference-apps/continu/packages/backend/convex/platform/system_settings.ts
  • reference-apps/continu/packages/backend/convex/platform/feature_flags.ts
• Behavior that must survive:
  • maintenance/system settings
  • feature-flag gating where product behavior depends on platform controls
• Current v2 state:
  • persisted platform system settings now back maintenance mode, a maintenance message, and starterkit feature flags from /platform/settings
  • the app proxy now rewrites non-platform traffic to a public maintenance page while preserving platform auth and platform-admin access during maintenance windows
  • organization creation, portal invitations, audit visibility, API access, webhook operations, and export behavior now honor platform feature flags
• Remaining port note:
  • deeper cross-tenant system settings and any broader governance workflows still need an explicit implementation pass

7.3 Audit logs, exports, and ops side effects

• Status: Partial
• V1 source anchors:
  • reference-apps/continu/packages/backend/convex/audit/system.ts
  • reference-apps/continu/packages/backend/convex/data_export.ts
  • email render/send/event modules
• Current starter anchors:
  • backend email and operational side-effect baseline in packages/backend/convex/*
• Behavior that must survive:
  • audit visibility for sensitive changes
  • export lifecycle
  • critical email-driven operational flows
• Remaining gaps:
  • current starter should not be treated as v1-parity here until the remaining platform-side export/system side-effect decisions are made explicit

Port Priority From This Point

Use this order unless a dependency forces a change:

1. Portal invite and member lifecycle: verify the full org-managed state machine end to end, not just the happy path
2. Billing depth: plan-change/downgrade UX, product-usage limits, and Polar products cache/reconciliation
3. Platform system-settings depth: remaining cross-tenant governance workflows beyond the first flag-backed kill switches
4. Portal/staff shared activity visibility: decide which portal events are visible from org operations and close any remaining preference migration cleanup
5. Shared auth hardening pass: confirm step-up coverage, broader session-management polish, and any remaining device/session governance depth beyond the now-landed org security pass

Definition Of Success

This port is complete when:

• the current starter reproduces the same core product outcomes as Continu v1
• every major v1 surface is marked Done, Intentional defer, or explicitly removed by decision
• there is no ambiguity about what still needs porting
• the new codebase stays simpler than v1 while preserving the important behavior

Maintenance Rule

When a v1-related slice changes state:

1. update this ledger
2. update docs/app/planning/active-priority.md if the next-task stack changed
3. update docs/app/planning/current-state.md if repo reality materially changed

Do not finish a porting task with stale status markers in this file.