**Legacy v3 guidance. If using v4, follow [V4_UPGRADE.md](V4_UPGRADE.md) instead.**

# PBX Launchpad v3.0 - upgrade an existing v2 site, no shell

The upgrade preserves user accounts, existing FreePBX project configurations, paid deployment bundles, Stripe credentials and contact history.

## Existing v2 production website

1. Make **two backups**: all current v2 application files (including the private `.env` and `.installed.lock`) and a full MySQL database export. Keep the backups outside the public web root.
2. Perform the upgrade on a staging copy if possible. Confirm PHP 8.2+, PDO MySQL, cURL, ZIP, HTTPS and functional MySQL access.
3. Upload the contents of this v3 package over the existing application **without overwriting** the existing `.env` or `.installed.lock`. Keep the site's document root pointed at `public/`, never the project root.
4. Sign in as an existing site administrator. Visit `https://your-site.example/upgrade.php` in your browser. Review the notice, then select **I backed up the database. Run upgrade**. The migration adds an order purpose and fixed AI-credit quantity, plus new usage/proposal tables. It is designed to be idempotent.
5. Add the following settings to the private `.env` using the host's **File Manager**, not the shell (optional until AI is needed):

   ```text
   OPENAI_API_KEY=sk-proj-your-own-key
   OPENAI_MODEL=gpt-5.4-mini
   ```

   Never put these values inside `public/`, project notes, client JavaScript, or a repository.
6. Visit `/?page=admin`. Set **OpenAI support add-on**, **AI requests per purchase**, and check **Enable paid AI project assistance**. Save. Default new-site values: **$9.90** for **10 AI-generated requests**, but AI starts **disabled**. Your own API account pays OpenAI for actual token usage, independent of customer payment.
7. Test a small project: Edit, Clone, Full Diagram, PDF download, AI checkout in Stripe TEST mode, verified webhook credit activation, proposal approval, invoice and deployment ZIP PDF. Do not enable live Stripe mode until these checks pass.
8. Revisit `/?page=privacy` and `/?page=terms`, and replace the starter policies with your counsel-approved business policies. Configure server and database backups, error monitoring, account recovery, edge rate limiting, billing support and appropriate AI disclosure.

**Important:** `/install.php` is for a brand-new SaaS website. Do **not** remove `.installed.lock` or rerun it against an existing production installation. Use `/upgrade.php` for existing v2 installations.

## New installation

Follow `WEB_INSTALL.md` as before. The browser installer has an optional OpenAI key/model section. It generates the entire v3 schema automatically. **No upgrade page is required on a fresh installation.** The hosting panel may still require that you create the empty database and point the domain to `public/`.

## How OpenAI billing works

- Option A: In the project's **AI Assistant** tab, check the confirmation and pay the separately listed AI credit pack. Use AI to finish the design, then purchase the install bundle for the final configuration.
- Option B: In **Deployment**, optionally check **Add OpenAI project editing**. Stripe Checkout charges the install price **plus** the admin-configured AI pack price in the same transaction. Credits activate only after payment confirmation. This option is appropriate if the customer understands that subsequent AI edits create a new configuration revision, and deploying that revised revision requires another installation bundle.
- AI packs are tied to **one project**. Cloning a project copies its configuration but **not** its purchase history or AI credits.
- Payment unlocks a fixed number of AI edit requests; the count on each order is frozen when purchased, even if the admin later changes the offer. Refunds and disputes revoke the corresponding paid entitlement.
- The actual API request is only sent after the user explicitly requests it and consents to sending the project details. A successful validated proposal consumes one request credit; an API failure or an invalid response does not consume it. API requests may require enough output tokens for larger projects.
- All proposals are **drafts**. Applying one requires explicit approval; changed project revisions make old AI proposals ineligible for automatic application. The AI never has live PBX credentials or direct access to FreePBX.

## PDF reports and diagram

A project's Dashboard provides **Edit project**, **Call diagram**, **PDF**, **Clone**, and **Delete**. The project report includes:

- Project label, FreePBX target version, revision and configured business hours / inbound DID notes.
- Visual routing overview from incoming call through IVR menus to extension, voicemail, ring-group and submenu destinations.
- Printable extension and mailbox directory, ring-group membership and ringing strategies.
- Every IVR's announcement script and digit mapping, documented SIP trunk plans without secrets, notes and deployment checklist.
- The paid (or admin) deployment ZIP now also includes `PRINTABLE-CALL-FLOW-REPORT.pdf`.

The report is a **configuration design**, not historic FreePBX call-detail records (CDRs). IVRs, actual inbound routes and trunks remain manually reviewed/configured in FreePBX.

## Production review

This is a starter implementation. Browser installation, Stripe Checkout, webhook verification, mailbox delivery and FreePBX GraphQL provisioning need integration testing on the real server. Do not use production customer payments or phone-system deployments until you complete application security review and end-to-end acceptance tests. Monitor API usage and costs, add billing idempotency tests, MFA/admin protections, email verification, credential rotation and a robust audit/retention policy.
