Skip to main content

active-priority

Billing Foundation Follow-up​

  • Stripe client billing foundation is now structurally in place across backend config, Connect callback handling, webhook ingestion, customer mapping, and org billing route scaffolding.
  • Stripe v1 production hardening is now structurally in place across existing-account import/review, persisted financial idempotency, granular finance permissions and step-up, webhook repair/reconciliation, dispute and external finance-event coverage, real Stripe account tax-ID selection, and revenue-recovery acknowledgement.
  • The first invoice/subscription operations slice is now live in the org billing workspace and client billing surfaces, including invoice draft/finalize/send/void, subscription create/update/cancel/reactivate actions, and shared catalog-backed line-item selection.
  • Billing relationships are now live on quote, invoice, subscription, and contract detail surfaces, the client overview exposes cross-track next actions anchored on the client account, and subscription detail includes derived plan-history and billing-timeline views.
  • Immediate next work for billing should focus on reporting, analytics, and remaining operational polish on top of the now-live provider-backed Stripe layer, including post-send invoice lifecycle depth and any remaining catalog synchronization edge cases.
  • Keep Stripe-hosted aegi SaaS subscriptions separate from the organization-operated Stripe Connect client-billing track. SaaS subscription management belongs in Stripe Customer Portal; client commercial operations remain in their existing aegi and connected-account surfaces.

Active Priority

Current Phase​

The client-work foundation baton has moved past basic org and portal scaffolding. The repo now has live org operations, org project delivery, and portal client-work visibility, so the phase is about finishing the remaining operational detail and cleanup work.

Core Logic Guardrails​

Before adding another product area, keep the system anchored to these rules:

  • clientAccount remains the company-level anchor for delivery, billing, drive, contracts, quotes, and portal access
  • clientContact remains the company-local human record; portal identity stays an access layer, not a second client directory
  • commercial records (invoiceRecords, quoteRecords, subscriptionRecords, contracts) must extend the client account's billing and legal/commercial context instead of forming parallel relationship models; contracts own their own workflow, content, and attachments and must not collapse back into the Files feature
  • the portal remains a client-facing projection of org truth plus explicit shared-collaboration records; do not invent portal-only business records that bypass the org model
  • overview remains the operational snapshot and analytics becomes the reporting drill-in; do not collapse both jobs into one page

What Is Complete In This Phase​

  • the production account/organization lifecycle pass is complete: realm-safe final-access anonymization, explicit offboarding handoff, atomic ownership transfer, retry-safe organization closure, audit coverage, destructive alert dialogs, and a legacy portal-grant repair migration now form one documented contract

  • org shell destinations, global create surfaces, shortcuts, and shortcut documentation now share a canonical capability-aware registry, including the corrected separation between client visibility and portal-management permission

  • client detail now mirrors the sidebar with direct client-scoped tabs instead of Work, Billing, and Collaboration umbrella tabs; People, Notes, and Activity remain useful client-only additions

  • project detail keeps Notes and Billing as explicit destinations while folding file requests into Files; authored updates remain in the focused Updates workspace

  • the first client-work schema and seed data are in the backend

  • org client accounts are live through the clients route

  • org client detail is live through clients/[clientId]

  • org project detail is live through projects/[projectId]

  • org detail-route IA now uses real subpaths for clients/[clientId]/* and projects/[projectId]/* instead of query-param tabs

  • org time and commercial queues now use real page paths for job switches: time vs time/timer and invoices vs subscriptions

  • org sidebar billing navigation now lands on explicit Invoices and Subscriptions entries instead of a single Billing collection entry

  • org time now treats Entries as the sidebar workspace and keeps Timer as a utility route and shell action instead of a second sidebar destination

  • org invoices now use the secondary bar for fixed status queues while keeping search and client filters local to the billing collection toolbar

  • org entries now use the secondary bar for status queues while keeping search local to the entries collection toolbar

  • org entries now use a capture-first workflow: reviewer-authorized members' time is immediately ready for billing, other staff time goes directly to review, returned corrections automatically re-enter review, and only reviewers see approve/return actions

  • Today now acts as the execution queue across project tasks, blockers, time submission/review, file-request review, client support requests, and client feedback; team workspaces default to personal/shared actionable work while solo workspaces suppress redundant team controls

  • client portal responses now have an explicit handled/reopened lifecycle with exact deep links back to the client relationship workspace

  • client portal responses now preserve typed, client-validated task, project-update, and organization-reply outcomes; edited client feedback automatically reopens instead of retaining stale handled state

  • project blocking is now a first-class workflow with cause, owner, next action, visibility, resolution history, automatic project-state restoration, and a client-visible portal projection

  • org overview attention now carries typed record, actor, state, action, and destination data instead of relying on aggregate client totals and generated copy alone

  • org clients now use one scalable dense list with assigned-member summaries, lifecycle scopes and stats in the secondary topbar, local search and sorting, and direct inline lifecycle changes instead of a separate drag-and-drop organize mode

  • org portals now use their own queue-switched operational workspace, separate from clients, for per-client portal access and workspace management

  • org shell search now uses a deliberate split: the launchpad remains the quick command surface, and the topbar Spotlight modal now handles paged operational search with type filters and broader entity coverage

  • org create, edit, and preview workflows now follow one shell-first dialog model: previews are full screen, invoices no longer have a create page, and contract create/edit share one composer while the detail route remains read-only

  • client create/edit now seeds the primary person's portal access from the canonical client-account record when portal access is enabled

  • client People now acts as the canonical company people list, with per-person portal access state and role shown directly in the org workspace

  • the org portals workspace now derives live/unlinked/attention state from the unified portal-access summary on each client account instead of a separate primary-contact heuristic

  • the org collection taxonomy is now explicit in docs/app/development/org-workspace-collection-ux.md: secondary bars are reserved for durable workspaces, queues, or genuinely different representations; collection toolbars and rows own search, filters, sorting, grouping, selection, and record changes

  • the client drive source-of-truth is now explicit in docs/app/product/client-drive-spec.md and docs/app/development/client-drive-implementation-plan.md

  • first-class client-contact create/edit workflows are live in the client detail workspace

  • org project updates now support draft and published states in the app

  • org project oversight now includes organization-owned, assigned, due-dated parent tasks with inline checklist-style subtasks, task-attached Requests the portal user can fulfill, a cross-project Today projection, and direct project tabs for Overview, Tasks, Updates, Files, Time, Notes, and Billing; parent-task completion and reopening create automatic timeline entries while subtask status stays inside the parent, and authored updates may stand alone or link tasks

  • the client overview now leads with current projects and direct Add update actions, while portal invites expose direct copy actions from portal overview, client overview, and per-contact access rows; sending an invite also copies the exact emailed link when possible without invalidating that link

  • scoped client visibility is live through clientAccessAssignments

  • org projects, time, billing, and the client-first Drive home are live

  • org time-to-billing rollups now derive client billing state from tracked work, invoices, and subscriptions

  • the org overview route is now a real operations dashboard backed by the workspace summary surface

  • the org collection-shell baseline is now in place across the rebuilt record-heavy workspace routes

  • the collection-shell baseline now includes one shared borderless toolbar with a stable fixed-width search field and one consistent list-container rule across every primary org feature list; Files keeps its finder/workspace content model but no longer diverges at the page-frame level

  • org time-entry detail is live through time/[timeEntryId]

  • org billing detail is live through the client billing tab plus invoices/[invoiceRecordId], subscriptions/[subscriptionRecordId], and quotes/[quoteRecordId]

  • Stripe-backed invoice and subscription write flows are now live from the org billing workspace, client billing tab entry points, and detail routes

  • commercial provenance blocks are now live across quote, invoice, subscription, and contract detail so cross-record follow-through is explicit without inventing fake ownership

  • commercial provenance now uses local quote-record IDs as application causality across quote revisions, contracts, invoices, and subscriptions while retaining Stripe IDs for provider reconciliation; new webhooks repair links regardless of arrival order and a resumable migration covers legacy rows

  • quote and contract surfaces now exist as client-account-scoped commercial artifacts and should remain attached to the same commercial/legal spine

  • client records now own rich billing identity/defaults, including Stripe customer sync inputs and invoice rendering template defaults

  • the client overview now acts as a real operating hub with state-based next actions across access, commercial, delivery, and collaboration

  • the portal has real authenticated client-work routes for overview, projects, billing, files, activity, settings, and support

  • the portal dashboard shell and page surfaces now share one responsive navigation/account-switching implementation and one consistent page-versus-section spacing contract; account settings and sign-out live in the top-right account menu rather than the client-work sidebar

  • portal request intent is now explicit without adding another client navigation destination: help stays in Support, new-work requests stay in Projects, and the agency receives both in one labeled and filterable Client requests queue

  • portal project drill-in is live through projects/[projectId]

  • the backend drive migration is now cut over to driveItems, fileAssets, and richDocuments; the legacy documents table is no longer part of the live collaboration model

  • portal session and workspace runtime are now grant-aware through portalAccessGrants, so one portal identity can hold multiple client-company grants inside the same agency organization

What Is Still Missing In This Phase​

  • remaining collaboration closeout decisions on top of the now-landed portal request inbox, response submission flow, acknowledgment step, and richer destination metadata
  • manager workflow polish on top of the now-landed paginated Entries billing-state, duration, range, trend, approval, and lock baseline
  • smaller operational polish and residue cleanup after package-wide validation was restored

Immediate Goal​

Finish the language, IA, and cross-feature coherence pass inside the existing org and portal client-work slice without reopening the rest of the product model.

The next work should keep the client-first model intact, build on the now-landed portal self-service people and time-lock slices, and deepen collaboration metadata plus reporting polish without reopening the corrected commercial and collaboration model.

The Stripe production-hardening baseline is now present, so the next billing work should stay on time-to-billing workflow depth, finance reporting, and customer-surface coherence instead of reopening the provider foundation. Hosted creation of new connected accounts and application-fee pricing remain an explicit post-v1 track.

Use docs/app/development/agency-owner-smart-workflows.md as the source of truth for anticipatory UX and cross-track follow-through during this polish pass.

The client and portal model is now explicit and should remain the source of truth:

  • clientAccount is the company-level client record
  • clientContact is a human inside that company
  • portal access is a capability and lifecycle state on that person, not a second parallel identity model in org UI
  • portalUser is the org-scoped portal identity for that person
  • portalAccessGrant is the company-specific grant that links that identity to one client company and one company-local person record
  • the org People tab is the canonical company-level person management surface
  • the org Portals workspace is the cross-client operational view over that same underlying access model

Use org-workspace-completion-milestone.md as the move-on gate for this baton.

Fundamental Logic Hardening Pass​

Before any broader product expansion, run this pass in order and treat each slice as a completion gate.

  1. Access and permissions coherence. Done means org-side visibility, role policy, and billing visibility rules read as one system instead of scattered feature-by-feature exceptions. Status: landed. See docs/app/planning/fundamental-logic-hardening-audit.md.

  2. Portal grant-model coherence. Done means portal and org people/access flows use portalAccessGrants as the only company-access mental model and stop depending on older single-company assumptions. Status: landed. See docs/app/planning/fundamental-logic-hardening-audit.md.

  3. Stripe truth versus app truth discipline. Done means billing flows, analytics, exports, and UI copy keep Stripe as finance truth while app-side billing records stay operational projections with client-account context. Status: landed. See docs/app/planning/fundamental-logic-hardening-audit.md.

  4. Collaboration closure rules. Done means the request lifecycle has an explicit lightweight definition of review, acknowledgment, and close without reopening heavy approval workflow design. Status: landed. See docs/app/planning/fundamental-logic-hardening-audit.md.

  5. Cross-feature ownership audit. Done means each major surface still points back to client account as the anchor and no track starts pretending to own another track's records. Status: landed. See docs/app/planning/fundamental-logic-hardening-audit.md.

Rule for this pass: do not add a new product area while one of these five slices is still logically unresolved.

Current Baton​

Owner dogfooding now drives the immediate polish order through docs/app/planning/owner-dogfooding-issue-inventory-2026-07-28.md. Each issue must be reproduced, bounded, implemented, and verified independently rather than bundled into one broad redesign.

  1. Confirm NOTE-01 through owner dogfooding after the canonical saved-note session synchronization and session-scoped save repair.
  2. Confirm I18N-01 through owner dogfooding after the structured notification metadata, localized catalog, and safe legacy-billing fallback repair.
  3. Confirm TIME-01 through owner dogfooding after making capture complete by default, moving staff review behind an organization opt-in, separating portal time visibility from review, adding explicit team-time permissions, moving the active timer to durable server state, snapshotting historical rate/currency context, replacing period-choice work with one confirmed Ready to bill recommendation, progressively disclosing advanced invoice controls, adding automatic rate-aware range value to Entries, and allowing client-wide invoices to combine separately priced project/general-work groups.
  4. Confirm NOTE-02 through owner dogfooding after the Notes page, topbar quick editor, and shared compose dialog moved to one revision-checked durable autosave contract with close/switch flushing, format-aware dirty detection, automatic draft-to-record promotion, and no routine Save buttons.
  5. Confirm NOTE-03 through owner dogfooding after the Notes-page create action moved into the existing page editor with an immediate selected draft row, contextual defaults, local incomplete-draft recovery, and create-once autosave; client, project, timer, and quick-capture note dialogs retain their compact presentation.
  6. Confirm NOTE-04 through owner dogfooding after topbar Starred and Recent note rows gained independent, accessible shell pin/unpin actions without mutating note-level Starred state.
  7. Confirm REM-02 through owner dogfooding after reminder creation gained explicit client → project context, client-focus and record-entry inheritance, optional related items, and server-authorized canonical context.
  8. Confirm REM-03 through owner dogfooding after reminder opening became a shell-first compact quick view with an explicit durable detail destination, canonical deep links, capability-aware actions, and creator-or-assignee visibility.
  9. Confirm NAV-01 through owner dogfooding after Today became the role-neutral organization home, moved ahead of Overview and Analytics, and gained live date rollover while intentional deep links remain preserved.
  10. Confirm TOP-01 through owner dogfooding after pinned projects became compact resume views with blocker context, viewer-first task ranking, inline completion, exact-context timers, task creation, and an explicit full-project destination.
  11. Preserve the confirmed PROD-01 experience doctrine: the workspace is quietly prepared rather than bossy; it distinguishes Needs you, Today, and Continue, while optional features never masquerade as required work.
  12. Confirm PROD-01A through owner dogfooding after one safe shell working-scope contract began carrying visible client/project context into global create actions without mutating persistent client focus.
  13. Confirm PROD-01B through owner dogfooding after absent optional features were removed from client Needs attention and permission-valid actions moved into quiet client-scoped Create choices.
  14. Confirm PROD-01C through owner dogfooding after timer quick-stop, reminder creation, and portal request creation gained optional exact-record handoffs, while response actions that already remain on their causal record stayed quiet and in place.
  15. Confirm PROD-01D through owner dogfooding after Today adopted deterministic Needs you, Today, and Continue lanes, removed its speculative task score, preserved all task and operational queues, and kept direct domain and record destinations.
  16. Confirm PROD-01E through owner dogfooding after All invoices gained one optional, period-based readiness surface; exact client/currency/period handoff into a separate invoice draft; historical-rate-safe calculation; and explicit confirmation before tracked time is reserved.
  17. Confirm PROD-01F through owner dogfooding after portal overview project, file, resource, support, request, update, agreement, and invoice spotlights began preserving exact authorized record identity; request responses already on their causal record remain quiet.
  18. Confirm PROD-01G through owner dogfooding after the quick-action dock gained one client-focus-aware operational cue: a single actionable record opens exactly, multiple records open the viewer's Needs you queue, and configured create actions remain stable.
  19. Continue through the inventory in its documented order, updating the issue status log after every completed slice.

The broader anticipatory UX and collaboration lifecycle work remains valid, but the owner-reported trust and correctness failures take precedence until the first dogfooding pass is clear.

Sequencing Rule​

Do not start a second wave of new tables before the current first-wave tables are actually used in the app.

Specifically:

  • use clientContacts before inventing another contact model
  • use projectUpdates before inventing a second project activity model
  • use the current billing records before adding parallel digest tables for convenience
  • do not add a second parallel file model beside the planned drive tables

Out Of Scope Until This Baton Clears​

  • a second wave of time workspace complexity beyond the current approval-plus-lock baseline
  • complex drive approval workflows beyond the lightweight request layer
  • general public browsing of client drive folders
  • recurrence and outbound email delivery for reminders before series/timezone and notification-policy behavior are specified
  • platform multi-agency operations