Client Proposals

A Client Proposal is a presentation layer built on top of an estimate — distinct from the estimate itself. It selects which cost information is visible to the client, controls the pricing display mode, governs how margins are redistributed before issuance, generates narrative sections, and produces a formatted PDF document for delivery.

Create a Proposal From an Estimation

Client proposals belong to a specific estimation revision. To create or manage one:

Open the project and select the estimation revision from Estimations.
Open its Estimation Workspace.
Select the Proposal tab.
Create a draft proposal or open an existing proposal for that revision.
Configure the audience-visible content, then finalize and record delivery when ready.

The Proposal tab is a hub: it shows the draft’s state, totals, and last-modified time, and opens the full-page proposal editor for detailed work. The Client record holds the relationship, contacts, projects, requests, and files. It is not where proposals are built or delivered.

Pricing Display Modes

Client Proposals support four pricing display modes, giving full control over how much cost detail the client sees:

Mode	Meaning
Total Only	Just the bottom-line total — the default, most conservative view
Scope Value Summary	Scope-level groupings with their value, no cost breakdown
Commercial Summary	Aggregated commercial view suitable for executive or client review
Detailed Estimate Backup	Full itemized pricing — section and item-level pricing, quantities, unit rates

Additional visibility toggles control cost breakdown, quantities, unit prices, material-labor-expense splits, and appendix inclusion. These controls allow the same estimate to serve both internal review and external presentation without duplicating data.

Markup Distribution

Markup Distribution is a governed way to move margin between the disclosed rows of a proposal before it goes out, without changing the total. It is the record that ties what Darwin held internally to what left the building — and proves the total was unchanged.

When It Is Available

The feature is deliberately unavailable on most proposals. Where no unit prices are disclosed, aggregation already hides the cost basis, so there is nothing to protect. Darwin shows a requirement checklist — never just the first failure — and all of these must hold:

the proposal is in Draft
it discloses unit prices
it does not show the material/labor/expense split
the grouping produces unit rates (at least one rate-bearing row)
at least two eligible rate-bearing rows exist

Ineligible rows stay visible and read-only, with their reason, and contribute their unchanged balanced amount to both sides of the total.

Lifecycle and Authority

Draft → Submitted → Approved | Rejected → Superseded

The estimator moves amounts between disclosed rows; the document must tie to the last minor unit to save. On submit, an action-required task is routed to the project’s approver. Only the project approver may approve or reject, and on approval the version becomes immutable — a content hash is recorded and the signature stamped. Approval tasks are routed as deep-linked tasks so an approval request is never silently lost.

On bid day a rejection is not a dead end: it returns the distribution to an editable Draft while preserving the exact submitted content as an immutable review event, so the estimator can act on the comment without losing their work.

Deviation Policy

Two tenant-configurable thresholds capture intent without ever refusing work:

Threshold	Default	Effect
Rationale	±15%	A stated reason becomes mandatory
Warning	±30%	The workspace warns prominently; the reason stays mandatory

A hard stop would only push the work into a spreadsheet — losing exactly the record the feature exists to keep.

Boundaries

M/L/E split is prohibited on a distributed artifact — printing the cost composition beside redistributed margin is self-defeating
No distributed value leaks into internal cost data — cost control, variance, and module attribution are byte-identical before and after a distribution
Preview of a distributed artifact is watermarked so it cannot be mistaken for an issuable document

The Full-Page Proposal Editor

Beyond the Proposal tab’s right-rail card, a dedicated full-page editor (/projects/:projectId/estimations/:estimationId/proposals/:proposalId) hosts the complete proposal workflow:

Proposal head and narrative — the proposal title, narrative sections, and pricing/visibility panels
Snapshot summary — the finalized totals with their approval lineage
Markup Distribution card — opens the distribution workspace when available
Record Decision — the client’s response, recorded against the proposal

The editor guards unsaved work against proposal navigation, tab changes, browser close, Preview, Submit, and Finalize. Preview requires a tied, saved draft, so an older allocation is never rendered while newer values sit on screen.

Status Lifecycle

Draft → Finalized → Sent → Accepted / Declined / Superseded

Draft — the proposal is editable; visibility settings and narrative are configured
Finalize — the cost is locked in by the project’s approver. Finalize requires the project approver and an exact, non-preliminary formal approval, and it is where the approved sell amount, the frozen schedule, any distribution total, and the proposal total reconcile atomically. It records which approval produced the figure and how that figure was sourced, localizes the schedule, and computes a content hash for later verification. From this point the proposal is immune to subsequent changes in the source estimate. Regenerating requires creating a new proposal
Sent — marks delivery to the client. Darwin renders and retains the exact PDF bytes that went out the door, with immutable metadata. Sending records the issuance in Darwin; it does not prove that email was delivered or that the recipient received the PDF
Accepted / Declined / Superseded — terminal states reflecting the client’s response

Decisions and Loss Reasons

The client’s response to a finalized proposal is recorded as a separate decision record, not a field on the proposal. Decision outcomes include:

Accepted — the proposal was accepted
Declined — the proposal was declined, optionally with a structured loss reason
Negotiation Requested — the client requests changes; a new proposal can be created

Each decision records the proposal number, amount, currency, and estimation code as they stood at decision time. Decisions are numbered per project via DecisionCycleNumber, enabling Darwin to track a negotiation across multiple proposal rounds.

Proposal Narrative

Client proposals can include AI-generated or authored narrative sections that explain:

Scope of work covered by the estimate
Key assumptions and exclusions
Pricing basis and market context
Commercial adjustments or alternates

The narrative layer is separate from the cost data, allowing independent editing.

Audience Boundary

A newly created proposal defaults to the most conservative visibility settings — Total Only pricing, no cost breakdown, no detailed appendix. Detailed cost backup is rendered only when explicitly opted in, and detailed estimate backup never exposes Darwin’s internal base-cost rows.

Workflow Role

An estimate is built and reviewed internally
A Client Proposal is created from the estimate (or cloned from a prior proposal) as a Draft
Visibility settings and narrative are configured
When eligible, the estimator distributes margin and the project approver approves it (Markup Distribution)
The approver finalizes — locking in the reconciled total — and Send marks delivery
The client’s response is recorded as a decision
A declined or negotiation-requested outcome can lead to a revised estimate and a new proposal

Next Steps

➡️ Estimation Workspace
➡️ Revisions