1. Plain-English Accounting: Commercial Quote vs. Pro-Forma Invoice vs. Tax Invoice

One of the most common mistakes in business accounting is issuing a Tax Invoice just to ask a customer for a deposit before work starts. If the client changes their mind or cancels the deal, you are stuck reversing Output VAT/Tax you haven't even collected! Keystone X solves this with a Dual-Stream Document Engine:

2. Dual-Stream Command Center & 3 View Modes (quote/index)

Navigate to Sales & CRM → Quotes & Proposals (quote/index).

A. Top Command Bar & 3 View Mode Switchers

B. The 6 Commercial KPI Cards

C. Row Action Icons & 3-Dot ERP Conversion Menu

Every row in the Quote Ledger (`quote/index?view=list`) features 3 direct action buttons plus a 3-Dot Quick ERP Workflow Menu ():

• Open Proposal Cockpit (`quote/preview/{id}`): Opens the interactive executive preview & conversion bridge.
• Edit Document (`quote/edit/{id}`): Modifies line items, scope, or deposit terms.
• Download PDF (`quote/pdf/{id}`): Generates the print-ready PDF in a new tab.
• Quick ERP Workflow Dropdown:
  • Convert to Tax Invoice (`quote/convertToInvoice/{id}`): Converts the quote into a formal Tax Invoice (`INV-`).
  • Switch to Pro-Forma Invoice / Commercial Quote (`quote/convertToProForma/{id}`): Flips the document between `QUO-` and `PRO-` stream instantaneously.
  • Create New Revision (`quote/revise/{id}`): Clones the quote into `v2` (or `v3`, `v4`...) so you can revise pricing while preserving the original revision history.
  • Launch ERP Project (`quote/convertToProject/{id}`): Creates a new project in the Project Management Suite pre-populated with this quote's client, budget, and scope.
  • Dispatch Field Job Card (`quote/convertToJobcard/{id}`): Creates a Field Service Job Card (`JC-`) directly from the quote's line items.

3. Rapid Generation: The "From Blueprint" Modal (#quickProposalModal)

Clicking From Blueprint in the top bar opens a modal (`#quickProposalModal`) that generates a complete proposal in seconds using templates saved in your Studio:

1. Select Proposal Blueprint (`template_id`): Choose a saved template (e.g., "10kVA Solar Backup Package" or "Annual SLA Retainer"). Choosing a blueprint automatically fills in the default Document Type (`Quote` vs `Pro-Forma Invoice`), Deal Title, and Required Mobilization Deposit %!
2. Client / Customer (`customer_id`): Select the target customer.
3. Document Type (`document_type`): Choose Commercial Quote (`QUO-`) or Pro-Forma Invoice (`PRO-`).
4. Deal / Reference Title (`reference_title`): Custom project or deal headline.
5. Link to ERP Project (`project_id`): Optional project association.
6. Required Mobilization Deposit % (`deposit_percentage`): Percentage deposit required upfront. Click Generate Document to create the populated proposal immediately.

4. Building a Proposal or Pro-Forma (quote/add & quote/edit)

Whether you click + New Quote or + New Pro-Forma, Keystone X opens the interactive Commercial Document Builder (`quote/add`).

A. Document Header, Commercial Metadata & Deposit Settings

5. Line-Item Pricing, Cost Price & Live Gross Margin Guard

Sales reps often accidentally underquote deals when giving discounts. Keystone X includes a built-in Staff-Only Gross Margin & Profit Guard inside the Quote Builder (`quote/add` and `quote/edit`):

• Catalog Picker (`item_id[]`) + Rich Description (`item_description[]`): Select any SKU from your Inventory Catalog to auto-fill its Selling Price (`unit_price[]`), Unit Cost (`unit_cost[]`), and Tax Rate (`tax_rate[]`), or type a freeform custom service item and multi-line scope description.
• Optional Item Checkbox (`is_optional[]`): Tick the Optional Add-on checkbox on any row to present an upsell option to the customer without adding its price into the mandatory Grand Total!
• Internal Unit Cost & Row Margin Badge (`unit_cost[]`): Visible only to internal staff (never printed on client PDFs). Shows your unit cost and calculates a live Row Margin % Badge.
• Live Deal Gross Margin Banner: Above the line items table and inside the summary card, Keystone X calculates total Estimated Profit and Overall Deal Margin %. If the deal's margin drops below your Studio Minimum Gross Margin Target % (e.g., 20%), the badge turns **Red (Below Target)** to warn the salesperson before they send the quote!

Narrative Proposal Sections (Below the Line Items)

• Executive Summary / Cover Letter (`introduction_text`): Printed at the top of the proposal PDF before the pricing table to introduce your company's value proposition.
• Scope of Work / Technical Deliverables (`scope_of_work`): Detailed breakdown of phases, milestones, inclusions, and exclusions.
• Terms, Conditions & Payment Milestones (`terms`): Legal validity, warranty terms, and deposit conditions.
• Private Staff Deal Notes (`internal_notes`): Strictly internal notes for managers and technicians; hidden from client PDFs and the Client Portal.

6. The Proposal Cockpit, Revisions (v1, v2) & 4-Card ERP Conversion Bridge (quote/preview/{id})

Clicking any quote number or the preview icon opens the **Proposal & Pro-Forma Cockpit** (`quote/preview/{id}`).

A. Top Cockpit Controls & Version Revisions

• New Revision (`v2`, `v3`...): Clicking New Revision (`quote/revise/{id}`) creates a linked child revision (e.g., `QUO-0042 v2`) and displays a Revision History Switcher Bar at the top of the cockpit so you can toggle between `v1`, `v2`, and `v3` at any time.
• Email to Client (`#emailQuoteModal`): Opens a modal pre-filled with the client's email (respecting your Customer Document Routing settings!) and dispatches the PDF proposal + online portal acceptance link (`quote/sendEmail/{id}`).
• 5-Stage Visual Lifecycle Stepper: Shows the real-time progress across 1. Draft → 2. Sent to Client → 3. Client Viewed → 4. Approved / Won → 5. Invoiced, along with quick Mark Approved and Mark Rejected buttons.

B. The 4-Card ERP Downstream Conversion Bridge

Directly beneath the lifecycle stepper sits the 4-Card ERP Conversion Bridge, connecting pre-sales quoting to every operational and financial module in Keystone X:

7. Quotes, Proposals & Pro-Forma Studio (quote/settings)

Click the Gear Icon () on `quote/index` to open the **Quotes, Proposals & Pro-Forma Studio** (`quote/settings`). It is organized into **4 Governance Tabs**: