Agency Product Baseline Audit

Status: working product and design baseline
Audited: 2026-07-11
Audience: product owner, design, engineering, and future implementation agents
Scope: the product app in apps/app and its Convex backend in packages/backend. This is not a marketing-site or infrastructure audit.

How To Read This Document

This is the starting point for hardening the product before and during internal adoption.

• Observed means evidenced by routes, UI composition, backend APIs, schema, or tests in this repository at audit time.
• Intended means established by the product documentation, but not necessarily complete in the UI.
• Recommendation is a proposed decision or improvement, not a statement of current behavior.
• Stage 2 gate means work that should be tested deliberately while the owner's agency uses the product. It is not necessarily a prerequisite for starting Stage 2.

Existing product documents remain useful supporting material, especially product-spec.md, operating-model.md, feature-contract.md, and cross-feature-link-matrix.md. This document consolidates them against the implementation and should be updated when a product decision changes.

Decisions made during the hardening process are recorded in product-decision-log.md.

Executive Summary

aegi is an agency operating system with a client portal. It is designed to replace the fragmented parts of an agency-client relationship: spreadsheets and ad hoc client lists, disconnected project status, personal notes, unstructured files, time records, billing visibility, and email-based client updates.

The product's distinctive idea is not merely "agency project management." It is a client-centered operating system: a clientAccount is the parent business context; internal agency staff operate across that client's work; the client portal exposes a deliberate, safe projection of the same relationship. Projects, time, contracts, commercial records, files, links, portal access, and activity are all meaningful because they are connected to a client account.

The repository is substantially beyond a visual mock-up. It has three isolated product surfaces, persistence models for the core domains, role/capability checks, Stripe Connect-backed client billing flows, a portal access model, rich editing, notifications, audit trails, and a sizeable automated test suite. Its weakness is not lack of features. The weakness is that the app contains more operational depth than its information architecture and interface consistency currently communicate. Some pages are mature workspace experiences; others are list-first queues or settings-like forms. The result can feel dense, inconsistent, and unclear about what the next useful action is.

The correct next move is not broad feature expansion. It is to use the owner's agency as a structured proving ground: validate the end-to-end client lifecycle, record friction at the point it happens, normalize page and detail-page patterns, then address the gaps that block repeated real work.

The Problem Being Solved

Agency problem

Small and growing agencies commonly operate a single client relationship across many disconnected tools:

• client facts and contact details in a spreadsheet, CRM, inbox, or memory;
• project status in a task tool, chat, and meetings;
• time in a timer or ad hoc notes;
• contracts and files in cloud storage and email;
• invoices and subscriptions in Stripe; and
• client communication through repeated status emails and file links.

This fragmentation produces four operational failures:

1. No single person can quickly see the state of a client relationship.
2. Internal agency delivery work and client-facing information become mixed, duplicated, or accidentally exposed.
3. Billing and delivery lose context: a paid invoice, an active retainer, a blocked project, and unbilled time are not visible together.
4. Clients must ask the agency for routine answers: what is happening, what changed, what needs review, where is the file, and what is due.

Product response

The app should make each client relationship legible to both sides without pretending to be every category of business software. It should provide:

• one internal operational home for each client;
• cross-client agency workspaces for people who manage a domain at scale;
• a client portal that exposes delivery, commercial, and shared-file truth without exposing internal operations;
• finance behavior grounded in Stripe rather than a competing ledger; and
• traceable, permission-aware links between the records that make up a client relationship.

What the product is not

The intended boundary is important. This is not currently intended to become:

• a full CRM and lead-to-close pipeline;
• a deep task, sprint, or resource-planning suite;
• a general accounting ledger;
• a full help desk; or
• an enterprise digital asset manager.

Those categories may integrate with the product later, but they must not dilute the core job: run and communicate an active agency-client relationship with confidence.

End Objective And Rollout

Long-term objective

Provide a trustworthy SaaS product that agencies can use to run client operations and give clients a credible portal. The product must first earn that right through daily use in the owner's agency, then prove understandable to other agencies, then a small public beta, before a broader release.

Staged rollout

Stage	Goal	Evidence of success	Current assessment
1. Build	Establish the core product and enough workflow depth for real use.	Core records can be created, connected, viewed, and protected.	Near completion. The implementation is broad enough to begin proving real workflows.
2. Owner agency	Use it as the primary operating tool and find real friction, defects, and missing workflow depth.	Work is completed in aegi repeatedly, with a structured issue log.	Next.
3. Friendly agencies	Validate that the model is understandable outside the builder's own habits.	External agencies can onboard, configure, and complete core workflows with limited guidance.	After repeated internal use stabilizes.
4. Public beta	Serve roughly 20 selected agencies and learn support, onboarding, reliability, and prioritization realities.	Stable operational support, observability, backups, security review, and a bounded beta program.	Later.
5. General release	Offer a dependable paid product.	Proven onboarding, billing, support, reliability, documentation, and product focus.	Later.

Stage 2 definition of success

Stage 2 should not mean "use every page." It should prove that a normal client lifecycle can be operated without workaround systems being the hidden source of truth:

1. Create a client, primary contact, and portal access.
2. Create and run one or more projects.
3. Log and review time against real client work.
4. Publish at least one client-visible project update.
5. Share and retrieve a real file or authored document in the right context.
6. Create or synchronize a real invoice or subscription through the Stripe connection.
7. Give the client a portal experience that answers what is active, changed, due, and shared.
8. Resolve one normal exception, such as a late payment, blocked project, client access change, or file request.

Product Model

The core ownership rule

The client account is the root business context.

This is the most important design and architecture rule in the repository. A feature may own its own records and workflows, but those records remain part of a client relationship first. Therefore:

• clients/[clientId] should answer: what does this client own, and what is happening with them?
• top-level agency workspaces should answer: how do we operate across one or many clients in this domain?
• the portal should answer: what is relevant to the client contact's permitted client account(s)?

This is already reflected in the schema. projects, timeEntries, invoiceRecords, quoteRecords, subscriptionRecords, contracts, driveItems, clientLinks, and portal access records all connect through clientAccounts directly or through their owning records.

Source-of-truth rules

Domain	Primary truth	Why it matters
Agency-client relationship	clientAccounts	Prevents projects, files, or portal users from becoming the accidental client record.
Delivery state	projects and projectUpdates	Keeps client-facing progress separate from finance and internal notes.
Internal work effort	timeEntries	Makes reporting and invoicing inputs derived from explicit records.
Finance state	Stripe, mirrored by client billing, invoice, quote, subscription, and transaction records	Avoids an app-only competing billing ledger.
Legal/commercial authored agreement	contracts and contractAttachments	Contracts remain commercial/legal records, not generic Drive files.
Shared collaboration asset	driveItems, fileAssets, richDocuments, and requests/shares	Gives files explicit ownership, visibility, and provenance.
Agency-side authorization	org membership, role policy, overrides, and client access assignments	Keeps staff access distinct from client portal access.
Client portal authorization	portal identity and portalAccessGrants	Prevents a portal user from being treated as a reduced agency user.

Three product surfaces

Surface	Audience	Primary purpose	Current implementation position
Organization (org)	Agency owner and staff	Operate clients, delivery, commercial work, files, access, and agency settings.	The main and most developed product surface.
Portal (portal)	Client contacts	Safely view the client relationship, delivery, billing, files, links, activity, support, and account settings.	Functional client-facing projection with a smaller feature set.
Platform (platform)	aegi operator/admin	Manage organizations, users, SaaS subscriptions, audits, control plane, system notices, and blog content.	Present for future SaaS operations; not the immediate product-use priority.

The surfaces intentionally do not need identical layouts or density. They must, however, use internally consistent patterns and shared terms where they describe the same business truth.

Observed Feature Inventory

The following is a code-grounded inventory. "Maturity" describes product readiness for Stage 2, not code quality.

Foundation And Access

Feature	Observed current behavior	Key interactions	Maturity
Agency organization and staff	Organization selection/creation, onboarding, organization settings, membership, invites, role policies, capability checks, client-access assignments, audit logging, account/security controls.	Gates everything on org; determines which client records staff can see.	Strong foundation.
Client portal access	Portal identities are separate from org identities; access grants associate a portal identity with a client account and local contact. Invite, login, reset, MFA, account selection, suspension, and support-handoff routes exist.	Determines portal projections for projects, billing, files, links, activity, and contracts.	Strong architecture; Stage 2 must validate user comprehension.
Notifications and audit	Notification inbox and preferences exist across product surfaces; audit modules, org audit-log settings, and platform audit views exist.	Should make significant access, billing, and delivery events traceable.	Present; event usefulness and noise need user validation.
Search, launchpad, pins, quick views, hotkeys	Org shell includes global search, command/launchpad, pinned work, entity quick views, quick-create dialogs, hotkeys, calendar/time/note quick views, and notification entry.	Cross-cuts all agency workflows.	Feature-rich; high risk of cognitive overload without a deliberate hierarchy.

Client Relationship And Delivery

Feature	Observed current behavior	Key interactions	Maturity
Client accounts	List, search/filter, create, edit, archive, relationship metadata, contacts, billing details, staff access, portal context, and a client detail workspace. Schema includes status, health state, ownership, billing identity, and localization; project billing treatment and subscription allowances live on their owning records.	The anchor for projects, time, drive, contracts, quotes, invoices, subscriptions, portal grants, links, and activity.	Core and ready for Stage 2.
Client detail workspace	Routes exist for overview plus client-local sections. Current components and route helpers cover people, projects, time, drive, contracts, billing, activity, and links. Overview composes relationship, billing, project, drive, and time signals.	Should be the fastest way to understand a single client.	Core, but it needs a design-consistency audit against top-level workspaces.
Projects	Cross-client list, creation, status, owner, target date, visibility, archive lifecycle, and project detail workspace. Detail tabs are overview, notes, time, files, and updates; project updates support draft, publish, archive, restore, and delete.	Required client relationship; optional project links for time, contracts, files, invoices, quotes, and subscriptions. Project updates are projected into the portal when published/visible.	Core and credible; deliberately light rather than task-management-heavy.
Project updates	Rich authored updates with draft/published workflow.	Gives the portal delivery truth without exposing internal notes or task noise.	Important differentiator; Stage 2 should confirm that publishing is easy enough to become routine.
Notes and Today	Personal/client/project-scoped rich notes, pins, archives, and a Today workspace that projects accessible open project tasks.	Supports internal working memory and cross-project follow-through without creating a parallel checklist; it must never become client-facing by accident.	Useful supporting layer; ensure it does not compete confusingly with project updates.
Time tracking	Time list, detail route, timer route, direct creation, client/project assignment, billable flag, draft/submitted/approved states, lock/archive fields, insight rollups, readiness signals, and client/project time sections.	Feeds operating visibility and can inform invoice readiness, but billing remains human-controlled.	Strong base; approvals and invoice handoff should be exercised with real use.
Calendar	Agency calendar route and event dialog with optional client/project context.	Complements delivery/timing awareness and project target dates.	Supporting workflow; clarify whether it is a real operational calendar or a convenience view.

Commercial, Legal, And Finance

Feature	Observed current behavior	Key interactions	Maturity
Agency Stripe connection	Organization-level Stripe Connect connection state, authorization flow, webhook tracking, connection health, catalog synchronization, and billing actions exist.	Enables client billing features; distinct from aegi's own SaaS subscription.	Technically substantial; must be tested with real Stripe accounts and failure cases.
Client billing profile	Client-level Stripe customer mapping, billing contact/currency/state, invoice and subscription activity.	Client account is the billing anchor; shared by invoices, subscriptions, quotes, and transactions.	Core dependency.
Catalog	Product and price list/detail routes, catalog creation dialogs, Stripe product/price IDs and active status.	Supplies reusable commercial line items for invoices, quotes, and subscriptions.	Useful back-office capability; must be kept visually secondary to client workflow.
Quotes	Client-scoped quote list/detail, Stripe-backed creation, finalize/cancel flows, and PDF token support.	May hand off to contracts, invoices, or subscriptions; should not become a Drive artifact. Portal currently has no dedicated quote navigation.	Present but needs a clear post-acceptance workflow.
Invoices	List, create, detail, Stripe-backed action layer, statuses, hosted invoice/PDF fields, payment and transaction context, client portal billing list/detail.	Always belongs to client; may optionally reference project/quote/contract context.	Core; must be tested end-to-end including late/failed/void/refund realities.
Subscriptions/retainers	List, create, detail, Stripe-backed flow, lifecycle state, portal billing views, and client retainer/time context.	Belongs to client; may optionally contextualize a project but must not depend on one.	Core for recurring agency work; Stage 2 should validate the terminology "subscription" versus "retainer."
Transactions	Cross-client finance view with payment/balance-adjustment records and invoice/subscription references.	Operational reporting and reconciliation; client context should remain primary.	Advanced agency view; should not be the default starting point for routine billing.
Contracts	Contract list/detail, rich authored content, draft/publish/archive lifecycle, contract types, visibility, optional project link, attachment upload/registration, and portal contract projection.	Belongs to client, may govern projects/subscriptions/invoices, but is not owned by Drive.	Good base; signatures, acceptance, and quote handoff depth require a separate product decision.

Collaboration And Client Communication

Feature	Observed current behavior	Key interactions	Maturity
Drive	Global client-scoped finder, folders, uploads, authored rich documents, project context, sharing, public/access links, file requests, contributor-upload intake, external upload submissions, and portal file access.	Collaboration-owned assets belong here; project files can be handled in project context. Contract and billing attachments remain owned by their source workflow.	Strong capability; IA and terminology must make ownership boundaries obvious.
Links	Org and portal link workspaces with client-scoped links and brand icons.	Supports useful external resources without forcing them into file storage.	Supporting capability; verify that users understand its difference from Drive.
File requests/upload links	Drive request dialogs and public upload-link flow; backend records for requests, access links, challenges, sessions, and submissions.	Lets agency collect files from clients or contributors in client/project context.	Valuable differentiator; test trust, expiry, and client comprehension.
Portal activity and support	Portal activity page, support workspace, context requests/messages, support handoff, and client-visible account interactions.	Lets a client see changes and request help without accessing internal operations.	Present; needs a content/notification policy review so it feels useful rather than empty or noisy.

Agency Oversight, Settings, And SaaS Administration

Feature	Observed current behavior	Key interactions	Maturity
Overview and analytics	Org overview is an operational summary. Analytics route/API includes client/project/time, invoice, collection, subscription, storage, and request signals across 90/180/365 day ranges.	Turns detail records into agency health and attention views.	Present; validate whether users can tell overview from analytics.
Portals management	Cross-client portal list/detail sections for readiness, people/access, and support context.	Connects staff administration to portal-client access.	Necessary administration; may be duplicative if client details already provide enough access controls.
Settings and premium controls	Org routes cover organization, team, roles, account, security, billing, branding, custom domain, integrations, API access, webhooks, audit log, exports, marketing, consent, usage, and advanced settings.	Configures tenant operation and paid product capabilities.	Broad, but a separate settings IA audit is needed.
Platform	Admins, organizations, users, subscriptions, audit, control plane, system settings, blog, invitations, and recovery flows.	Operates the future multi-agency SaaS, not day-to-day agency delivery.	Deprioritize for Stage 2 except where it blocks support or reliability.

How Features Should Plug Together

Canonical relationship map

Agency organization
  -> staff memberships, roles, client access assignments
  -> client account
       -> contacts and portal access grants
       -> projects -> updates, time, notes, project-context files, optional contracts
       -> billing profile -> quotes, invoices, subscriptions, transactions
       -> contracts and contract attachments
       -> Drive items, rich documents, links, file requests
       -> client portal projections

Required, optional, and prohibited links

Relationship	Rule	Product consequence
Client -> project, contract, quote, invoice, subscription, Drive item, portal grant	Required ownership	The client must remain visible and navigable everywhere.
Project -> time	Required when a time entry is project-specific; project itself remains optional on time entries.	Work can be client-level without inventing a project.
Project -> contract, invoice, quote, subscription, Drive item	Optional context	Show a link only where it helps explain a real relationship. Do not force it in forms.
Quote -> contract/invoice/subscription	Workflow handoff	Preserve the commercial history without collapsing distinct record types.
Project -> portal	Projection only	The portal reads agency-owned project truth; it does not create another project system.
Contract/invoice/subscription -> Drive	Not canonical ownership	Attachments and retrieval can be convenient, but commercial/legal records must retain their own context and lifecycle.

Expected navigation behavior

• From a client detail, a staff member should be able to reach every relevant domain without losing the client context.
• From a cross-client list, opening an item should show the item first and its client context prominently.
• From a project, the client, updates, time, files, and any explicit commercial/legal context should be available, but unrelated billing should not be forced into the page.
• From an invoice, subscription, quote, or contract, the client and the applicable commercial actions must be primary. Do not use a generic Drive link as a substitute for finance/legal context.
• From the portal, users should encounter client-safe projections, never separate records that have to be reconciled with the agency view.

Current Information Architecture Assessment

What is working

1. The organization sidebar groups work into Home, Accounts, Work, and Revenue. That is a sensible agency-operating taxonomy.
2. The product has both client-centric and cross-client views, which is the right response to agency work rather than forcing all workflows through a single dashboard.
3. Project detail has a clear tabbed model and embeds files, time, notes, updates, contracts, and client context without making Drive the universal destination.
4. The portal has a deliberately smaller navigation set: overview, projects, files, billing, support, links, and settings.
5. Commercial records are separate first-class workspaces rather than being collapsed into generic documents.

Where the information architecture is likely to feel unclear

1. Client versus Portal management: agency staff can manage portal-related information in both client context and dedicated portals routes. The job boundary needs an explicit rule: client detail is the relationship home; Portals is the cross-client readiness/access queue.
2. Overview versus Today versus Analytics: all three are agency-awareness surfaces. Their roles need to be sharply defined: Overview = operational health; Today = my immediate work; Analytics = trends and management reporting.
3. Drive versus files in feature detail: the code follows the right ownership rule, but users need consistent labels and entry points so they do not believe Drive is required for project, contract, or billing files.
4. Notes versus project updates: notes are internal working memory; updates are a controlled client-facing publication workflow. The visual treatment and language must make that distinction unmistakable.
5. Revenue breadth: quotes, invoices, subscriptions, catalog, and transactions are all useful, but the first four may overwhelm a small agency. The client account and invoice/subscription flows should lead; catalog and transactions should read as advanced operations.
6. Calendar and links: both may be useful, but their product role is less central than the client/project/billing loop. Stage 2 should determine whether they earn top-level navigation or belong under a secondary workspace/utility pattern.
7. Settings sprawl: the number of settings routes is appropriate for a SaaS but may not yet be organized around the decisions an agency owner needs to make.

Design Language Baseline

Existing design assets and conventions

Observed shared infrastructure includes theme packages for base, org, portal, platform, and marketing; reusable UI primitives; a dashboard shell; tokenized sidebar and page spacing; responsive mobile navigation; loading skeleton primitives; dialogs/drawers; rich-text components; data grids/tables; badges/status components; and translated UI dictionaries.

The baseline repository rules correctly allow org, portal, and platform to diverge as separate products. The goal is not visual sameness everywhere. The goal is predictability within a surface and in equivalent workflows.

Required shared behavior

The following should be non-negotiable across the org surface unless a documented exception applies:

Pattern	Standard
List workspace	Clear page title, primary create action when permitted, concise filter/search toolbar, readable result model, empty state with an actionable next step, and stable row/card click behavior.
Detail workspace	Prominent title and status, visible client context, back path that preserves origin when useful, a bounded set of tabs/sections, one obvious primary action, and a compact facts/actions rail or equivalent.
Client context	Client name must be visible near the title of every client-owned record; clicking it should return to client detail.
Status	Use the same status badge family, color semantics, and wording for delivery, finance, legal, access, and approval states. Never reuse one color/status label to mean unrelated business states.
Actions	Put the irreversible or uncommon actions in a menu; keep the one likely next action visible. Avoid a row of equally weighted buttons.
Tables	Use common column density, type hierarchy, cell alignment, row click affordances, and mobile fallback behavior.
Forms	Group by business decision, not database fields; show only context that affects the decision; preserve unsaved-work protection; make optional project context visibly optional.
Empty states	Explain the missing business object and provide the action that creates it. Do not use generic illustration or filler copy.
Loading and errors	Use local skeletons for known layouts and actionable error messages. Avoid generic full-page placeholders for normal transitions.
Client-safe visibility	Any internal/client-visible control must use clear language and a consistent visual treatment. Publishing should be a deliberate act.

Detail-page standard to adopt

Every agency detail page should be assessed against this structure, not copied mechanically:

1. Identity band: record type, name, status, client link, and the one primary next action.
2. Decision context: the few facts that change what the operator should do next, such as due date, owner, payment state, visibility, or approval state.
3. Focused sections/tabs: only persistent subdomains that need independent attention. Do not use tabs to hide a handful of fields.
4. Related records: show only canonical or explicitly linked context, ordered by operational relevance.
5. Lifecycle and audit: archive/delete/restore, timestamps, and history should be present but visually subordinate.

The project detail page is closest to this model today. Client, contract, invoice, subscription, quote, and Drive detail experiences should be compared to it deliberately, while preserving their domain-specific needs.

Density and readability principles

• A dashboard should prioritize exceptions and next actions, not summarize every available metric.
• A list should answer one scanning question. Extra columns should be hidden, filterable, or reserved for detail.
• A detail page should start with current state and next decision, then offer full context below.
• Metadata should be compact and grouped; labels should not compete visually with the primary business value.
• Text-heavy rich content should use comfortable reading widths, stronger hierarchy, and a clear distinction between authored content and surrounding app chrome.
• Client-facing portal screens should prioritize trust and clarity over operational density.

Feature-Level Product Decisions Still Needed

These are product decisions, not implementation tickets. Resolve them before spending heavily on polish in each area.

Area	Decision to make	Why it matters
Project	Is the project primarily a delivery-status container, or does it need lightweight milestones/deliverables as first-class records?	Determines whether updates/files/time are sufficient or the model needs another layer.
Project updates	What cadence and template makes client updates actually happen?	A strong publishing system is useless if updates are too expensive to write.
Client visibility	Is the app willing to keep multiple exposure vocabularies, or should it enforce one app-wide model of Client visible versus Internal?	Prevents projects, Drive, and contracts from teaching different rules for the same underlying client-safety decision.
Notes	Should client/project notes remain private to their author or become collaborative internal notes?	Changes visibility, workflow, and trust expectations.
Time	Who submits, approves, locks, and turns time into billing recommendations?	The states exist; the operating policy must be defined.
Invoices	Which common Stripe actions must be operable in aegi versus by opening Stripe?	Prevents a misleading promise of fully native billing management.
Retainers	Should user-facing language prefer "retainer" when a Stripe subscription represents agency services?	User terminology should match how agencies sell work.
Quotes to contracts	What exactly happens after a quote is accepted?	This is the largest commercial handoff ambiguity.
Contracts	Is signature/acknowledgment in scope, or are contracts authored/shared records only for now?	Avoids a false impression that a published contract is legally executed.
Drive	Which artifacts belong in Drive versus feature-owned attachments, and how are they presented in search?	Core to preventing file-context confusion.
Links	Does Links solve a recurring client problem distinct from Drive, or should it be folded into client/project context?	Determines whether top-level navigation is justified.
Calendar	Is Calendar a planning source of truth, a derived schedule view, or a personal utility?	Determines integration and prioritization.
Portal	Which client actions beyond viewing are essential: file upload, acknowledgment, support request, payment, approval, or something else?	Defines portal value beyond passive visibility.

Stage 2 Validation Plan

Operating rule

Use the app for actual agency work wherever safe. Do not judge a feature only by whether it can be demonstrated. Judge it by whether it is faster, clearer, and safer than the previous workaround.

Capture every issue in one backlog

For each observed issue, record:

• date and workflow attempted;
• actor and surface (org, portal, or platform);
• client and record context, without sensitive content;
• expected outcome;
• actual outcome;
• workaround used;
• severity: blocker, serious friction, minor friction, visual inconsistency, or idea;
• repeat count; and
• screenshot/video only when it adds clarity.

Classify the cause separately:

• correctness or data integrity;
• authorization/security;
• missing workflow;
• unclear information architecture;
• interaction usability;
• visual hierarchy/density/consistency;
• performance/reliability; or
• product policy decision.

Weekly review questions

1. Which external tool remained the real source of truth this week, and why?
2. Which records were hard to find after they were created?
3. Which page failed to make the next action obvious?
4. Which repeated action took too many clicks or too much context switching?
5. Which information was present but unreadable because of density or hierarchy?
6. Which portal question still came through email or chat?
7. Did any visibility, access, or billing state create uncertainty or risk?
8. Which feature was used repeatedly without friction and should therefore be protected from unnecessary redesign?

Suggested Stage 2 sequence

1. Start with two real clients, not the entire book of business.
2. Run the complete client-onboarding flow for one new or recreated client.
3. Run delivery, time, file sharing, and portal updates for an active client for two weeks.
4. Run at least one invoice/subscription workflow in a safe Stripe environment, then real billing when operationally ready.
5. Invite one real client contact only after the portal content and access model feel credible.
6. Review the issue backlog weekly; address correctness, security, and data-integrity issues before visual polish.
7. Do not add broad new domains during this period unless a repeated workaround proves a core gap.

Prioritization Framework

Use this order when turning the baseline into implementation work:

1. Trust: data correctness, access isolation, Stripe/webhook reliability, destructive-action safety, backups, and recoverability.
2. Core loop: client creation -> project work -> client update -> time -> billing/file delivery -> portal comprehension.
3. Findability: client context, navigation, search, record links, and clear ownership.
4. Usability: primary actions, form design, dense tables, responsive behavior, loading, and error recovery.
5. Consistency: shared design patterns, status language, page structures, and terminology.
6. Depth: workflow features proven necessary through repeated use.
7. Breadth: additional modules, automation, and platform polish.

Do not prioritize a feature only because it has a visible route or a partially implemented backend. Prioritize it when it strengthens the core loop or removes a repeated operational workaround.

Immediate Baseline Actions Before Heavy Redesign

1. Treat this document as the current product narrative and update it alongside material behavior changes.
2. Create a small Stage 2 issue backlog using the capture format above.
3. Run the first end-to-end client lifecycle and document where the current pages break the client-centered model.
4. Audit one representative list/detail pair in each major domain: clients, projects, invoices, contracts, Drive, and portal projects/files.
5. Write a concise design-system contract from the "Required shared behavior" and "Detail-page standard" sections before redesigning multiple pages independently.
6. Decide the unresolved product-policy questions that block repeated real work, especially time approval/invoicing, quote-to-contract handoff, contract execution, portal actions, and the Drive boundary.

Evidence Base

This audit was grounded in the following implementation areas:

• org, portal, and platform route trees under apps/app/src/app/[locale];
• org navigation in org/(dashboard)/_components/shell/nav.ts;
• org and portal Convex API contracts under apps/app/src/app/[locale]/_lib/convex/api;
• domain tables in packages/backend/convex/schema.ts;
• domain modules under packages/backend/convex/org, packages/backend/convex/portal, packages/backend/convex/organizations, and packages/backend/convex/notifications;
• client/project detail composition, including the project detail tab model and client-local route structure;
• existing automated tests under apps/app/tests and packages/backend/tests; and
• the existing product documentation referenced at the top of this document.

Audit limitations

This is a repository audit, not a live-environment certification. It does not prove production configuration, Stripe account behavior, email deliverability, deployment health, performance under load, accessibility with assistive technologies, data migration status, or actual user comprehension. Those must be tested during Stage 2 and later release preparation.