=== PaintClarity ===
Contributors: paintops, freemius
Tags: painting, contractor, estimates, scheduling, invoicing
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.2.092
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Run your painting business from WordPress: quotes to invoices, crews, scheduling, customers, photos, profit reports, optional AI and card payments.

== Description ==

**PaintClarity turns your WordPress site into the back office for your painting business.** *(PaintClarity was formerly known as PaintOps. Same plugin, same team, same data.)* Create Quotes, Estimates and Bids your customers can open and sign online. Schedule crews and follow each job from the first request to the final payment. Pro adds online deposits through Stripe and profit reports by job, crew and worker.

It was built by a painter, for painters. The quote builder understands painting scope: interior/exterior components, standard inclusions and exclusions, and the disclaimer language that keeps you out of disputes. Your data lives in your own WordPress database, not locked inside someone else's SaaS, and the free plugin is a complete system on its own.

= Quote to invoice, start to finish =

* **Quotes, estimates & bids**: a scope-aware builder with reusable inclusions/exclusions, itemized or lump-sum pricing, trade calculators that add their numbers straight to the quote, printable output, and email delivery. **Preview Online Quote** shows you exactly what the customer will see before you send it.
* **A professional customer page**: your customer opens a clean, branded page (your logo, your terms & conditions) and accepts by typing their name. PaintClarity records the name and time. They can also decline with a reason, or ask a question, and the plugin attempts to email your office either way. You see when the quote was viewed.
* **Saving an online acceptance changes the request to a Job.** The document keeps its Quote, Estimate or Bid label. For work agreed by phone or in person, choose "Mark as Won, convert to Job" on the request page.
* **Payments**: every job has a Payments page. Record cash, check, or in-person card payments and refunds, and see Billed, Paid, and Still Owed at a glance. A payment flips the matching invoice to paid, so balances always agree.
* **Hours and job receipts**: log who worked a job, which day and how many hours (or let the crew's Time Clock do it), and file receipts against a job from a phone with Add Expense.
* **Sales tax, one or two**: a default rate plus any number of additional rates, each stamped on the job when it is created so a later rate change never rewrites old paperwork. Provinces that charge GST and PST (or GST and QST) on the same work can enter both, and quotes and invoices print each tax on its own line.
* **Communication History**: every email the plugin sent, every call or text link tapped, and every conversation you logged by hand, in one place per job, each marked by how much it can be trusted: sent by PaintClarity, link opened, or recorded by hand.
* **Receivables at a glance**: unpaid invoices surface on your dashboard with amounts and age, and a quote that has gone quiet shows up under Needs Your Attention with a one-tap follow-up email or text.
* **Request Performance**: how often your quotes turn into jobs, counted per job rather than per revision, so three rounds of edits before a yes count as one win, not two losses.

= Running the work =

* **Jobs, two ways**: a row view with Requests, Upcoming, Active, and Completed sections (unpaid balances right on the Completed section), and a **board / pipeline** view, Quote → Active → Completed, plus a lost-leads drawer with the customer's decline reason so you can revive the ones worth re-working.
* **Follow-up visits** without re-entering the job: schedule a callback, a punch list, or approved add-on work (with its own price and balance) against the original job in a short form. It lands on the calendar, the board, and the crew's phones like any other job.
* **Scheduling calendar** with crew filtering, worker badges, time-off, and a subscribe link for Google/Apple/Outlook. Add your own recurring holiday labels.
* **Crews**: group your painters into named, colored crews; staff a job with one tap and filter the calendar and reports by crew.
* **A real app for your painters**: install-to-home-screen (PWA), a "My Jobs" home, one-tap directions (Google/Apple/Waze), per-job check-in/out that works offline and syncs, photo/receipt/note logging, a "My Hours" view of their own time and pay, and a "Mark Job Complete" button that attempts to email the office and tells the worker if the website could not send it. Email delivery is not guaranteed. Workers see only what their permissions allow, never your numbers.
* **Production Rates**: the one number every quote leans on and most shops only half-remember. PaintClarity already holds the hours and the paintable area of every completed job, so this screen divides one by the other over your recent jobs and shows the work, per job and as a median, measured from your own crews. It measures; it never changes a quote behind your back, and a quiet Use measured rate button copies a figure into your settings only when you press it.
* **Business Checkup**: nine read-only scans of the whole business on one page: completed jobs with a balance due, jobs past their end date not marked complete, won jobs never scheduled, started jobs with no hours or no expenses logged, requests waiting more than two weeks, requests with no quote document, expenses missing a receipt image, and open records with no phone or email. Every line links to the record so it can be fixed in two clicks. It also tells you when the site is not on HTTPS and which features that holds back.
* **Customers**: a directory with contact details, lifetime value, job history, and **multiple service addresses per customer**, built for landlords, realtors, property managers, and GCs whose one account means a dozen properties.
* **Bring your existing records**: import customers, and jobs and quotes, from a CSV under Settings. The importer recognizes exports from Joist, Housecall Pro, and Jobber as well as a plain spreadsheet, and shows you the column match and exactly what will happen before anything is written.
* **Business Notes**: a simple notebook for vendor account numbers, insurance renewal dates, and reminders, plus "Add a Note to a Job" to drop a note onto any open job's log without leaving the page.
* **Before/After photos** with camera alignment overlay and a compare slider.
* **Color Visualizer**: load a photo of the house or the room, select the surface, and turn a color wheel until it is the color you are proposing. The wall changes color and keeps its own shading, grain and texture. Select by fill, by matching color, or by dragging a box over a big flat wall. Handles stucco, siding, brick, concrete block and interior drywall, takes the Sherwin-Williams or Benjamin Moore number alongside it, and prints or saves the render for the customer. The Manual tab runs entirely in your browser: no photo is uploaded anywhere.
* **AI Visualizer** (Pro): the other tab. Upload or take a photo, pick colors by brand and name from the Sherwin-Williams and Benjamin Moore books, add a note like "paint the stone wall too, in Alabaster", and get back a realistic repainted photo to show the customer. This tab sends the photo to OpenAI under your own API key (Settings > AI), billed to your OpenAI account at a few cents per render. Renders can be saved to the job's photos. Colors on screen are approximate; brand and color names are trademarks of their owners and PaintClarity is not affiliated with any paint manufacturer.
* **Trade calculators, paint-color tracking, and resource links.**
* **A choice of visual themes** (light, dark, industrial, and more) with a modern app-style navigation bar on desktop and phone, or a full-screen sidebar layout that hides the site's header and footer.
* **Works with your browser's translation.** The app's own text is English. Chrome, Safari and Edge page translation, and front-end translation plugins, are supported: customer names, addresses, amounts, dates, job numbers and paint color codes are marked so they stay exactly as entered.
* **Help built in**: a five-minute walkthrough video with chapter links, a setup checklist, and a Setup Health panel that says what is still missing before the first quote goes out.

= What Pro adds =

* **Invoices**: numbered invoices for the balance (full or partial), emailed or shared by link, payable online through Stripe or marked paid for check/cash. Invoicing more than the job is billing asks first, so a number never slips past you. On the free plugin, invoices already sent stay viewable and can still be marked paid.
* **Job financials & profitability**: one Financials page per job for costs, materials, expenses, hours and pay; gross, profit, and margin per job; a Profits dashboard with profit-by-classification, profit-per-hour rankings, and **profit by crew and by worker** (allocated by logged hours).
* **Job Pulse**: one page that answers "how is this job doing?" in whatever terms apply right now: a quote waiting on the customer, a job about to start, a job that is running (hours against the quote's labor, payroll against the price), or a finished job's after-action review.
* **Expense reporting**: the Expenses page (a year of spending by category and month), business overhead and vehicle expense tracking, spend by vendor, and a duplicate-receipt finder. Filing job receipts and logging hours are free.
* **Business Financial Report** for your accountant: income and expenses for the year, with **sales tax to remit by filing period**, one table per tax name and rate, by quarter or by month, on a cash basis following the payment date.
* **A quote request form for your website**: add `[paintops_quote_form]` to a page so customers can ask for a price. Saved website inquiries appear in Leads, unless they need review in Unverified requests. Spam checks help you sort them. Optional Cloudflare Turnstile adds another spam check. Requests that cannot be checked or do not pass can be saved in Unverified requests for you to review. These are set to be deleted 30 days after they arrive. Some requests cannot be saved, including ones over the form limits. Convert to Request opens a new request form. Choose Quote, Estimate, Bid or Job, then save to create the record. You are asked to check any possible match with an existing customer.

The form allows 5 requests per internet address (IP address) per hour, 100 across your website per hour and 500 across your website per day. Limits also apply to how much can be entered in one request. Office alerts about Unverified requests follow your email settings and are never sent more than once an hour. A passed spam check does not guarantee a genuine customer.
* **Online payments**: deposits on quote acceptance and invoice balances through Stripe Checkout, recorded automatically.
* **AI tools (bring your own OpenAI key)**: every AI feature is Pro. Estimate dimensions, gallons, and a Description of Work from a photo; scan receipts to auto-fill expenses and suggest a category; get feedback on, a rewrite of, or a materials list for your quote wording; AI Visualizer renders; plain-language Job Pulse, variance and profit summaries; draft a payment reminder for an unpaid invoice; suggest resource links.

Pro is a paid upgrade handled through Freemius. The free plugin is fully functional on its own; Pro is optional.

== Bundled artwork ==

The four ready-made logos offered under Business > Logo URL (assets/img/logos/) are AI-generated original artwork created for this plugin. They carry no third-party rights and are distributed under the same GPLv2-or-later license as the rest of the plugin. They are optional, off by default, and carry no PaintClarity branding or link.

== External services ==

This plugin can connect to the following third-party services. Some are optional and only run when you enable and configure the corresponding feature.

**OpenAI (Pro AI features, optional).** Uses **your own** OpenAI API key. Nothing is sent until you press an AI button, and then only what that tool needs goes to https://api.openai.com: Photo Estimate sends the photos you pick; Receipt Scan (job, business and vehicle receipts) sends the receipt image or PDF; Quote Feedback, Rewrite and Materials List send the quote's Description of Work; the AI Visualizer sends the house or room photo and your color note; Job Pulse, Variance and Profit Summary send that job's calculated figures; Invoice Reminder sends your business name, the customer's first name, the amount, invoice number and pay link; Expense Category sends the vendor name and note; Resource Suggestions sends your job categories and recent job titles. The AI Visualizer also reads your account's model list (https://api.openai.com/v1/models) to pick an image model. See OpenAI's Terms (https://openai.com/policies/terms-of-use) and Privacy Policy (https://openai.com/policies/privacy-policy).

**Cloudflare Turnstile (Pro quote request form, optional).** If you add Turnstile keys, the quote request form loads Cloudflare's check from https://challenges.cloudflare.com, and on submit your site sends a short check result (called a token), your private Cloudflare key and the visitor's internet address (IP address) to Cloudflare to check the result. A successful check does not guarantee that a request is genuine. See Cloudflare's Terms (https://www.cloudflare.com/terms/) and Turnstile Privacy Addendum (https://www.cloudflare.com/turnstile-privacy-policy/).

**Stripe (Pro online payments, optional).** If you enable card payments and a customer pays online, the plugin creates a Stripe Checkout session and verifies Stripe's webhook using your own Stripe keys. Order/amount details are exchanged with Stripe to process the payment. Requests go to https://api.stripe.com. See Stripe's Services Agreement (https://stripe.com/legal/ssa) and Privacy Policy (https://stripe.com/privacy).

**Google Maps Platform (optional).** If you add a Google Maps API key, address fields use Google Places/Geocoding for autocomplete and validation, and job locations may be shown on an embedded map. The address text you type is sent to Google to return suggestions. Requests go to https://maps.googleapis.com and related Google Maps endpoints. See Google's Terms (https://cloud.google.com/maps-platform/terms) and Privacy Policy (https://policies.google.com/privacy). (One-tap turn-by-turn Directions for your crew use keyless map links and need no API key.)

**YouTube and Vimeo (Resources page video embeds, optional).** The Resources page (staff-facing, inside your admin area) lets you save links to training videos, and seeds a starter list of publicly available painting tutorials on YouTube. When a staff member clicks a saved YouTube or Vimeo link's play button, the video is embedded on the page via the provider's standard embed player (www.youtube.com / player.vimeo.com), which loads content from that provider and is subject to its terms; no data is sent until the play button is clicked, and you can delete any or all saved links. See YouTube's Terms (https://www.youtube.com/t/terms) and Google's Privacy Policy (https://policies.google.com/privacy), and Vimeo's Terms (https://vimeo.com/terms) and Privacy Policy (https://vimeo.com/privacy).

**Freemius (licensing & updates).** PaintClarity uses the Freemius SDK to manage Pro licenses, deliver Pro updates, and (optionally) collect anonymous usage diagnostics you can opt out of. Site and license information is exchanged with Freemius. See Freemius's Terms (https://freemius.com/terms/) and Privacy Policy (https://freemius.com/privacy/).

Some services need a private setup key before they can be used. Others, such as license checks, updates, videos you play and links you open, can contact outside services without those keys. Each service is explained above.

== Privacy ==

Your customers' details live in your own WordPress database. PaintClarity's author never sees them, and nothing is sent to a PaintClarity server. That also means you, not the plugin, are the one a customer asks when they want to know what you hold about them, so the plugin helps you find and export those records.

**Private document links should only be shared with their intended recipients.** Quote, invoice and color pages use private links rather than passwords. Anyone with a valid link may be able to open it. PaintClarity asks search engines not to list or keep copies of these pages. This does not block someone who has the link or guarantee the page will stay out of search results.

**Data requests work out of the box.** Under Tools -> Export Personal Data and Tools -> Erase Personal Data, WordPress can search PaintClarity by email address. Export collects the customer record, their jobs, quotes, invoices, payments, and the emails you sent them. Erase removes their details from all of it.

**Erasing does not destroy your books.** Quotes, invoices and payments are kept and stripped of the name, address, phone, email, typed signature and IP address instead of being deleted, because a business is required to keep financial records for years and data protection law allows exactly that. Any quote or invoice link previously sent to that customer stops working. Job photos are left for you to review yourself rather than deleted automatically.

**Suggested privacy policy wording** for what PaintClarity stores and which services can receive data is added to Settings -> Privacy -> Policy Guide.

**Three optional limits, all off by default**, under PaintClarity -> Settings -> Privacy & Customer Data: delete the emailed-communication log after N months, forget the IP address recorded when a quote was signed online after N months, and make quote and invoice links stop working after N days. A business working only in the United States can leave all three off and nothing changes.

None of this is Pro. It is all in the free plugin.

== Installation ==

1. Install PaintClarity from the Plugins screen (Plugins → Add New → search "PaintClarity"), or upload the plugin ZIP under Plugins → Add New → Upload Plugin. Activate it.
2. Create a WordPress Page and add the shortcode `[paintops_app]`. This one page is your whole PaintClarity app; it routes internally.
3. Go to **PaintClarity → Settings** and set your Company Profile (business name, logo, country, currency), and review the Setup Health panel.
4. (Optional) Add team members under **PaintClarity → Painters/Helpers**, set their permissions, and group them into Crews.
5. (Optional) Add your Quote Terms & Conditions under Business Settings so customers see and sign against them.
6. (Optional, Pro) Under **Settings → AI Settings** connect OpenAI, and under **Stripe Payments** add your Stripe secret key AND webhook signing secret (both are required before online payment buttons appear). (Optional, any plan) Add a Google Maps API key for address autocomplete.

== Frequently Asked Questions ==

= Do I need a paid account to use it? =
No. The free plugin runs entirely on your own WordPress site and lets you quote, schedule, and manage unlimited jobs. Pro is an optional upgrade.

= What happens to my data if I deactivate or delete the plugin? =
Nothing is deleted. Your jobs, quotes, customers, payments, hours, and photos stay in your WordPress database, so nothing is lost if you deactivate temporarily or reinstall later. If you truly want the data gone, delete the plugin's tables from your database and the paintops-private folder from your uploads.

= Does it work without OpenAI, Stripe, or Google Maps? =
Yes. Those are optional integrations. If you don't enter their keys, the related features simply stay off and everything else works, including keyless turn-by-turn directions for your crew.

= Can my customers really sign a quote online? =
They accept by typing their full name, which is stored with a timestamp and IP address alongside your Terms & Conditions, a solid acceptance record. They can also decline with a reason, and change their minds later.

= Who pays for the AI usage? =
You do, through your own OpenAI account and key, typically a fraction of a cent to a few cents per action. PaintClarity adds per-month usage caps you control so costs stay predictable.

= Can my painters log in without seeing my numbers? =
Yes. Painters/Helpers get a dedicated role with opt-in permissions and their own app view: My Jobs, My Hours (their own time and pay only), directions, check-in/out, photos and receipts. Financial figures are owner-level and hidden from workers unless you explicitly grant access.

= Does it work in the field with bad reception? =
The app installs to a phone's home screen, and Time Clock check-in/out keeps working offline and syncs when a connection returns.

= Where is my data stored? =
In your own WordPress database. PaintClarity doesn't host your business data on an external server. You can download all of it any time, on any plan: PaintClarity > Business > Your Data gives you a ZIP of CSV files, one per table, plus your settings.

= Can I bring in my customers and jobs from another app? =
Yes. Settings has two importers, Import Customers and Import Jobs and Quotes, that take a CSV file. Exports from Joist, Housecall Pro and Jobber are recognized by their column names, and any spreadsheet with a name column works. You match the columns, see exactly what will be created, and then import. Both are in the free plugin.

= I charge two taxes on the same job (GST and PST). Can PaintClarity do that? =
Yes. Under Business > Pricing Rules, each tax rate takes an optional second tax name and rate. A job created with that pair carries both, and quotes and invoices print the two lines separately. Shops with one tax see no change.

= Is the app available in other languages? =
The app's own text is English. It is built to work with your browser's page translation (Chrome, Safari, Edge) and with front-end translation plugins: customer names, addresses, amounts, dates, job numbers and paint color codes are marked so they are never altered by the translation.

== Screenshots ==

1. The document builder for Quotes, Estimates and Bids: standard scope lines for each job category, your description of work, and an exclusions checklist.
2. The customer's quote page: your branding, optional add-ons, deposit terms and a typed e-signature to accept. With Pro and Stripe, the customer pays the deposit online.
3. The scheduling calendar on a phone: each day's jobs with worker badges and time off, filterable by crew.
4. A painter's phone view: today's job with Check In and Directions. Check-ins save without a signal and upload when the connection returns.
5. The Profits dashboard (Pro): profit by month, with each month opening to its jobs' revenue, expenses, profit and margin. Profit by crew and by worker are on the same page.
6. An invoice (Pro): print or save as PDF, email it to the customer, or mark it paid by check or cash. With Pro and Stripe, the email includes a secure link to pay by card online.
7. Settings > Appearance: five color themes and a full-screen side menu. You can also stop other plugins from loading extra code on the app page. Stripe and AI settings (Pro) are on the same screen. Your Company Profile and logo are under PaintClarity > Business.
8. The Color Visualizer: select a surface in the customer's photo and turn the wheel until it is the color you are proposing. The basic tool works in your browser. Pro adds AI-generated images.

== Changelog ==
= 1.2.092 =
* Added (Pro): sharing buttons on a completed job. Copy review link, Copy text message and Open Messages.
* Added (Pro): these work for customers with only a phone number. Nothing is sent for you. You send the text yourself.
* Added (Pro): the review request text and email now list the job's paint colors to keep for touch-ups: color, product, sheen and where it goes. Then they ask for the review. Gallons are left out.
* Added (Pro): Create color link makes an optional private page with the job's colors. A text with more than 6 colors links to it for the rest.
* Added (Pro): a color link keeps working until you choose Turn off color link. It only works while paint color sharing is on in Google Reviews settings.
* Added (Pro): quote requests that do not pass the Cloudflare Turnstile spam check, or could not be checked, are no longer lost.
* Added (Pro): they wait in Unverified requests. Add them to Leads or delete them. They are deleted after 30 days.
* Changed (Pro): the visitor is told their request is waiting for review. It does not say it was sent.
* Changed (Pro): office emails about unverified requests follow your email settings, at most one an hour.
* Changed (Pro): the completed job page says plainly that marking a job complete sends nothing to the customer.
* Changed (Pro): the quote form's thank-you and saved-for-review messages, and the paint color page, are easier to read on a phone.
* Changed: when a Quote, Estimate or Bid becomes a Job, it keeps its type. Editing the Job later keeps it too.
* Changed: office emails and help text name Quote, Estimate and Bid correctly. Clearer wording in many places.
* Changed: warning boxes have an even outline instead of a thick colored edge on one side.
* Fixed (Pro): a quote request sent twice at the same moment is saved once.
* Fixed: data export and erase show an error if the database fails, instead of a part result that looks complete.
* Fixed: on WordPress Playground and Studio, the calendar was empty and receipts did not suggest jobs.
* Fixed: Business Checkup now finds jobs that should be finished on those sites too.
* Fixed: a Quote, Estimate or Bid you mark as won says "marked as won by your office" instead of also saying the customer has not viewed it.

= 1.2.090 =
* Added: Profit by Month on the Profits page. One strip per month, like the Expenses page: the bar is the month's revenue against the year's biggest month with the profit share drawn inside it, and a month opens to the jobs that make it up, each with its revenue, expenses, profit and margin. A job counts in the month it started, which is how the year counts it, so the twelve months add up to the year exactly.
* Changed: on Financials, a saved hours row reads as a record (the date, the worker, the hours, the pay) with Edit and Remove beside it; Edit turns that row back into fields, Add Hours starts a new one. After Save Financials the section you were in stays open and says what is on file ("Saved. 3 rows, 21.15 hours on this job."). The rows no longer look like a form that was never sent.
* Changed: the Expenses list on Financials had five buttons stacked in the Receipt cell of every row. The cell now holds one Add Receipt button (a tap offers Take Photo or Choose Photo/PDF, and the pick uploads by itself), and Edit and Remove are text links in a column of their own.
* Changed: on the customer's quote page, Show Quote Details is a button the size of the Accept button instead of a small link, so a customer who sees the add-ons also sees where the full quote is.
* Changed: "Record a contact" on Communication History is "Log communication" now, and its button reads "Log it".
* Security: receipt PDFs open with script evaluation off.
* Security: Send Quote attachments are deleted from the server after sending.
* Security: spreadsheet exports, Vehicle Log CSV included, keep formula-like text as plain text.
* Fixed: the Profits page loads faster.
* Fixed: deactivating removes all scheduled tasks.
* Fixed: the Pro welcome screen now points to PaintClarity > Business.
* Fixed: Send Quote with an attached file from the app page stopped with a fatal error.
* Fixed: the Pro welcome screen after activation could not be opened and sent you to the app instead.
* Fixed: on a phone, an opened month in Profit by Month shows its total as a card of label and value lines like the jobs above it.

= 1.2.089 =
* Changed: the paragraphs that explained a section at the top of it (Add Expense, the Payments, Hours and Invoices sections of Financials, Reach the customer and History on Communication History) sit behind a small round "?" beside the section name now. One tap or click opens the text right there and another closes it; the screens start with the task instead of the reading.
* Changed: the sentence that opened New Photo or Note repeated what the box already says; it is gone.
* Changed: the Expenses page's "Where it went" is a pie now. The bars it replaces were each scaled to the biggest item in their own group, so a small gas bar could run as long as a large materials bar; every slice is a category as a share of the whole year, with the table beside it.
* Changed: the text size and map direction switches at the foot of the side menu fold under a "Page Settings" link; open it once and it stays open on that device.

The full history is in changelog.txt in the plugin folder.

== Upgrade Notice ==
= 1.2.092 =
Pro: review requests by text or email now give customers their paint colors, including phone-only customers. Quote requests that fail the spam check are kept for review, not lost. All: a Quote, Estimate or Bid keeps its type when it becomes a Job.
