# GymSpotter OS > GymSpotter OS is one app for running a gym equipment business. It shows your customers, invoices, purchase orders, expenses, stock, deliveries, sales leads and marketing in one place. It reads the QuickBooks reports and PDF files you already keep in your business folder. A built-in AI helper on the right side of the screen can explain things, fill in forms and do tasks for you, but it always asks you before it saves anything. This guide is written in plain words, about a 9th-grade reading level. It is also written so an AI model can understand the whole app. The same text is saved as llm.txt and llms.txt. ## Words to know - App: the GymSpotter OS program you open in your web browser. - Module: a group of pages for one part of the business. The sidebar shows the Finance, Dispatch, Warehouse, Leads, Marketing, Company & Team and Reports modules. The Communications module supplies the calls, texts, chats, forms and email that the Leads pages show. - Page: one screen in the app, like the Invoices page. - Record: one saved item, like one invoice, one customer or one delivery. - Invoice: a bill you send to a customer. - Purchase order (PO): an order you send to a vendor (a company you buy from). - Expense: money the business spent, like a fee or a bill. - Vendor: a company you buy equipment or services from. - SKU: a short code that names one product, like CF-3165. - Hub: a warehouse or storage location. - Dispatch: getting equipment delivered to a customer. - Lead: a person or business that might buy from you. - Contact: anyone who called, texted, chatted, filled in a website form, emailed or got your marketing email. A contact can be a prospect (got in touch, has not bought yet) or marketing only. - Customer: someone who has paid you: they have an account in QuickBooks and invoices. - Communications: the calls, texts, web chats, website forms and emails the app captures for each business. - QuickBooks export: a report file (CSV, XLS or XLSX) or a PDF that you download from QuickBooks. - CSV, XLS, XLSX: spreadsheet files. PDF: a document file, like a printed invoice. - Business folder: the folder on your computer that holds your QuickBooks files. - AI helper: the assistant in the right-side panel. - API key: a private password that lets the app use an AI company's service. - Model: the specific AI brain you pick, like a Claude, GPT, Gemini or Grok model. - WebMCP: a standard way for an AI to see and use the controls on a web page, like buttons and form fields. ## How to start the app 1. Double-click "Start GymSpotter OS.cmd". It starts GymSpotter OS in the background (no window to keep open) and opens the GymSpotter OS app. 2. The first time, the app is not installed yet: the start file opens Chrome or Edge with a "Get the GymSpotter OS apps" window. Click "Install the desktop app", then "Install". GymSpotter OS then has its own window and an icon in the Start menu (right-click it there to pin it to the taskbar). 3. The start file also sets GymSpotter OS to start by itself when you sign in to Windows, so the app icon always works. Its window says what it did and counts down "5... 4... 3... 2... 1..." before it closes. (To turn starting with Windows off, run launch-gymspotter.ps1 -NoAutostart.) 4. From then on, open GymSpotter OS with its app icon, or with the start file (it opens the app). "Stop GymSpotter OS.cmd" stops it. If the app opens while GymSpotter OS is stopped, it shows a "GymSpotter OS isn't running yet" page that opens the app by itself as soon as it starts. "Start GymSpotter OS Offline.cmd" starts it with internet AI turned off. The app always runs from the folder the start file is in (for example D:\GymSpotter OS on the USB drive), and the business folders are inside it ("Gym Tech Fitness\", "Fit Movers 123\"). Moving the whole GymSpotter OS folder, or plugging the drive in under another letter, needs no change: start it with the start file in its new place, and a copy still running from an old place is replaced. Do not add a fixed -DataPath to the start file. Its log is in %LOCALAPPDATA%\GymSpotter OS\server.log. Using GymSpotter OS in an ordinary browser tab works too, but the app keeps asking (once per browser session) and the bell shows a pinned "Get the Desktop and Phone app" notification until you use the installed app. The same window shows a QR code to put GymSpotter OS on your phone once this computer shares it over a secure link (GYMSPOTTER_PUBLIC_URL in .env). Opening an .html file by double-clicking it is not the same thing. Without the start file, the app cannot load your folder by itself or use AI. Always use the start file or the app icon. ## Learning the app: welcome tour, page guides, videos and the knowledge base - Choose a business: when GymSpotter OS opens and there is more than one business, it first shows "Choose a business" with each business's logo. Pick one with the mouse or the arrow keys and Enter. Nothing loads until you choose. The last one you opened is marked. You can still switch later with the arrow beside the sidebar logo. - Welcome tour: the first time you open a business, "Welcome to {business} Business App" walks through every module, how your data works, where to get help and a getting-started checklist. Replay it from Documentation → Learning center. - Page guides: the first time you open a page, its guide opens: what the page is for, every feature and function, how-tos, tips, questions to ask the AI co-pilot, related pages and the module's explainer video at that page's chapter. Open it again any time with the Guide button in the top bar or F1. "Show me around" walks through the real page with a spotlight. Untick "Open the guide the first time I open a page" to stop the automatic guides. - Explainer videos: one per module, recorded from the real app with an invented sample business (Summit Fitness Supply). They are narrated by a professional voice, with chapters per page and a transcript. The voice and the closed captions are separate layers: the player keeps the narration in sync with the picture, shows English captions by default (turn them off or pick another language from the CC menu, and another audio language when one exists), and Download gives the video with the chosen language's audio and captions built in (on by default). - Learning center (Documentation page): every module's video and every page guide, and links to the AI guides. ### The knowledge base for AI models (guides/) The detailed guides live in the guides folder, one folder per module. An AI should read the guide of each module a question touches: | Module | Pages (page keys) | AI guide | |---|---|---| | Getting started | dashboard, search, docs + the app shell | guides/overview/llm.txt | | Finance | finance, customers, invoices, purchases | guides/finance/llm.txt | | Dispatch | dispatchOverview, dispatch, dispatchCal, kanban, createDispatch | guides/dispatch/llm.txt | | Warehouse | warehouse, inventory, itemSkus, shipping | guides/warehouse/llm.txt | | Leads | pipeline, leadsOverview, contacts, leadsWebForms, leadsPhone, leadsSms, leadsChat, leadsEmail | guides/leads/llm.txt | | Marketing | mktGoogleAds, mktMetaAds, mktSocialPosts, mktSocialCalendar, mktEmail | guides/marketing/llm.txt | | Company & Team | company, team | guides/company/llm.txt | | Reports | reports (17 views) | guides/reports/llm.txt | | Settings & Integrations | integrations + the Settings drawer | guides/settings/llm.txt | - guides/index.json lists the modules, their pages and a "topics" map (for example sales → finance, leads, reports; inventory → warehouse, finance). A sales and stock question needs both the finance and the warehouse guides. - Each guides//guide.json holds the user-facing page guides and the storyboard of the module's explainer video (guides/README.md describes the format). - Inside the app, the AI co-pilot always has the guide of the module you are working in. It reads any other module's guide with the read_app_guide tool and can open a page guide for you with show_page_guide. ## Business accounts: one app, several businesses GymSpotter OS can run more than one business, each with its own data. The businesses are listed in config\accounts.json; today they are Gym Tech Fitness and Fit Movers 123. - Choose at start: with more than one business, the app opens on "Choose a business" (see "Learning the app" above). - Switch business: click the arrow beside "GymSpotter OS" at the top of the sidebar (or the business name under it) and choose the business. GymSpotter OS reloads as that business. The name under the logo always shows which business you are in. - Add a business: same menu → "Add a business…". It gets its own folder in the GymSpotter OS folder, named after the business, with Company, Invoices, Purchases, Orders, Inventory, Customers and Sessions inside, and opens Company & Brand Kit so you can fill it in. - What stays separate: each business's folders (Invoices, Purchases, Orders, Inventory, Customers, Sessions), its Reports data, its company profile and team, and everything the browser remembers for it (saved invoices, leads, settings, QuickBooks and Google Sheets connections, AI chat). Your own preferences (dark mode, sidebar, your name, the AI key) are shared by every business. - Where each business lives: each business is a folder at the top of the GymSpotter OS folder named after the business (for example "Gym Tech Fitness\" and "Fit Movers 123\"), holding everything for it: Company\ (brand kit, team, logo), Invoices\, Purchases\, Orders\, Inventory\, Customers\, Sessions\ and Reports\ (the Reports module's files), plus Expenses.xls once you put the QuickBooks expense list there, and Communications\ once Communications is set up ("Set up Communications"). Today Gym Tech Fitness has both; Fit Movers 123 has neither yet. A new folder at the top with a Company folder inside is added as a business by itself; with more than one business, GymSpotter OS asks which one to open. - Reports and Integrations show the business you are in. A business without Reports shows a "Set up Reports" button. ## Your business folder: what goes where Your business folder has these folders inside it. Put each QuickBooks file in the folder that matches it. - Invoices: QuickBooks invoice reports (CSV, XLS or XLSX) and invoice PDFs. Packing slip PDFs can go here too. - Purchases: purchase order PDFs, expense voucher PDFs, and QuickBooks purchase or expense reports. - Orders: delivery (dispatch) reports from the delivery system, like "Orders Report.csv". - Inventory: stock reports, like "Unallocated Items Report". - Customers: QuickBooks customer and vendor lists (Customers.xls, Vendors.xls). - Sessions: activity logs the app saves. These are history, not backups. - Expenses.xls: the QuickBooks expense list. It sits right in the business folder, not inside a subfolder. Rules that keep loading reliable: - Report spreadsheets go directly inside their folder. PDFs can also go inside subfolders, like Invoices/WOODBURY. - File names do not matter. The app reads what is printed inside each file. - Do not edit the exported files by hand. Export them again from QuickBooks instead. - Keep your own backups. The app reads your files when it loads. It only writes when you save something or use a file action. ### Which QuickBooks exports work The app finds the real column headings even when QuickBooks adds title rows, date-range rows, group rows, "Total" rows or a footer with the export time. It understands these: - Invoice lists: the QuickBooks Online Sales list export and the classic Invoice List report. The number column can be called Num, No., Number or Invoice no. In reports that mix payments, credit memos and invoices, only invoices are used. Statuses like "Due in 5 days", "Deposited" or "Partially paid" are turned into the app's statuses (Draft, Sent, Paid, Overdue, Cancelled). - Expense lists (Expenses.xls or an expense export saved in Purchases): Expense, Check, Bill, Cash Expense and Credit Card Expense rows count as spending. Vendor Credit and Credit Card Credit lower spending. Purchase Order rows become purchase orders. Bill Payment rows are skipped, because the bill itself was already counted. - Purchase order reports, including the Open Purchase Order List. - Customer and vendor lists. - Inventory reports, including QuickBooks Inventory Valuation Summary. - Dates like 07/16/2026, 7/16/26, July 16, 2026 and Excel date cells. - Money like $1,234.56, -$50.00 and (50.00) for negative numbers. - Plain CSV files saved as UTF-8 or as older Windows text, so names like "Café" show correctly. - Excel files with thousands of empty columns load quickly. If a report has no usable rows, the app tells you why in Data Sources. For example, your current "Purchases/Purchase Orders.xls" was exported by QuickBooks with the order number, vendor, date and total columns left empty. The app cannot use it, so it gets purchase orders from Expenses.xls and from the PO PDFs instead. To fix it, export that report again from QuickBooks with those columns turned on. ### How the app reads PDFs The app finds PDFs in Invoices, Purchases and Orders, including year folders. For invoices from the splitter, it first reads the metadata index beside the folders. If that data is missing, it checks metadata inside the PDF and then the printed text. Reviewed values in the folder index take priority. It understands these QuickBooks PDFs: - Invoices, in both the newer QuickBooks Online look and the classic template. - Purchase orders, in both looks. - Expense vouchers. - Packing slips. From each PDF it reads the document number, date, due date, terms, sales rep, customer or vendor, bill-to and ship-to addresses, line items, subtotal, tax, total, payments and balance due. Then it connects each PDF to the right record: - A split invoice PDF joins its master record by its saved record ID. Other invoice PDFs need matching invoice details. The invoice date matters because the same number can appear more than once. - With a complete master report, All Sources uses that report for financial totals. PDFs outside it stay available for review. Without a complete master report, newer PDFs can make their own records. - A purchase order PDF joins the purchase order with the same number. If the PDF total is different from QuickBooks, the record shows a note so you can check it. - An expense voucher joins the expense with the same date and amount. Vouchers newer than Expenses.xls become new expenses. - A packing slip attaches to the invoice with the same number. - A second copy of the same PDF attaches to the same record. It is never counted twice. Line items are kept only when they add up to the printed subtotal. If they do not, the record says so, and you can open the PDF to see the items. The metadata index lets the app load split invoices without opening each PDF body. Older PDFs without an index are read once, and the results are remembered on this computer. A progress line shows the files being processed. The load time depends on the number of files and the computer. Scanned PDFs that are only pictures have no text to read. Enter those by hand, or use the AI helper's document reading with a model that can read images. ### What your latest folder loaded (October 12, 2026) - 12,063 master invoice records. Their total value is $24,478,993.01 and their open balance is $991,240.61. The five older report tabs remain available. - 8,902 new split invoice PDFs, added to the 230 older invoice documents. Each new file has metadata, a stable file ID and the original invoice date. The 100 repeated prints do not add extra revenue. - Eight new PDFs need review: five include late fees missing from the master, and three are absent from it. Nine older PDFs also need review against the new master. These documents stay available without adding money to Finance. - 3,264 of the master invoices are from 2023. No 2023 PDF binders were supplied in this batch, so these records do not get new PDFs from the splitter. - 1,197 purchase orders and 1,301 expenses. - 846 stock records (item and hub), with 2,270 on hand and 2,698 waiting to arrive. - 359 delivery orders and 7,900 contacts (7,854 customers and 46 vendors). The first load indexes all 9,340 PDFs across the business folders. It reads the 8,902 new documents from their metadata index and opens the 438 older PDFs once. Saved results help later pages load without repeating those reads. Data Sources shows the current counts and any warnings after a refresh. ### Data Sources Open Settings, then Folder, then "Review loaded data" to see Data Sources. It lists every report and how many rows it gave, how many PDFs were read and linked, and any warnings. A warning tells you what is wrong and how to fix it. ## The modules Each module is a group of pages. The left menu shows the modules and their pages. ### Finance module Finance Overview (finance.html) - Shows revenue (invoice value), money collected, money still owed (open A/R), overdue money, expenses, draft and open purchase-order totals, and estimated net. - Open PO total uses the full values of Draft, Sent and Partial purchase orders. The supplied expense report does not provide unpaid supplier-bill balances. Finance exports explain what each amount means. - Pick a date range like This Month, This Year or All Time. - A chart compares revenue and expenses by month. A "View chart data" table under the chart shows the same numbers as text. - Recent activity lists the newest invoices and purchase orders. Click a row to open it. - The Expenses table lists each expense. A "PDF" button opens its QuickBooks expense voucher. - Export CSV saves the numbers to a spreadsheet. - These numbers are a helpful estimate. They do not replace an accountant. Customers (customers.html) - Search and view customers and vendors from your QuickBooks lists. - Add or edit a contact, see their invoices, orders and deliveries, and export the list. Invoices (invoices.html) - Shows every invoice, newest first. Each row shows its PDF when one is linked. - Search, filter by status, date, amount or service level, and sort any column. - Click an invoice to see its details, line items, totals, bill-to address, and its documents (the invoice PDF, packing slip or copies). - Create a new invoice, edit fields, change status, print or export to PDF, and export a list to CSV. - A paid invoice can be turned into a delivery order with "Convert to Dispatch". Purchase Orders (purchases.html) - Shows every purchase order, newest first, with its PDF when linked. - Create or edit a PO: vendor, dates, ship-to hub, line items and totals. - Mark a PO fully or partly received. Receiving can add the items to inventory. - If a PO's PDF total differs from QuickBooks, the PO shows a note. ### Dispatch module Dispatch Overview (dispatch-overview.html) - A summary of deliveries: how many are pending, on the way, delivered or have a problem. Dispatch Orders (dispatch-orders.html) - The full list of delivery orders from your Orders report. - Search and filter by date, status, hub and more. Open an order to see details. - Update status and notes, print order documents, and export the list. Dispatch Calendar (dispatch-calendar.html) - Shows deliveries on a month calendar. Move between months or jump to today. Kanban Board (kanban-board.html) - Shows delivery orders as cards in columns: Pending Arrival, Received at Hub, Out for Delivery, Delivered, On Hold, Delivery Failed, Cancelled and Returned. - Drag a card to move it, or use the card's "Move to" menu if you cannot drag. New Dispatch Order (new-dispatch-order.html) - A form to set up a new delivery: customer, address, items, hub and service level. - Sending it to the outside delivery system needs that connection to be set up. ### Warehouse module Warehouse (warehouse.html) - Stock at each hub, low-stock alerts, and shortcuts for receiving and moving stock. Inventory (inventory.html) - Every stock record from your inventory reports. Search, filter, sort and see item details. - Change quantities, add items, record stock you received or moved, and export. - Stock is tracked by item and hub, so changing one hub never changes another. Item SKUs (item-skus.html) - The product list by SKU, with names, vendors and sizes used for shipping. Ship Calculator (shipping-calculator.html) - Enter ZIP codes, service level, equipment, weight and quantity to estimate shipping. - A real carrier price needs the shipping connection to be set up. ### Leads module Sales Pipeline (pipeline.html) - Follow possible sales through stages, from quote to delivered. See the value at each stage. Leads Overview (leads-overview.html) - Every channel at a glance (web chats, calls, texts, website forms, email), what needs a reply, incoming by month, who the people are (customers, prospects, marketing only), then the lead pipeline. Contacts (contacts.html) - Everyone who got in touch on any channel, one contact per person, with whether they are a customer, their whole history and their HubSpot record. Web Form Leads (leads-web-forms.html), Phone Leads (leads-phone.html), SMS & Text Leads (leads-sms.html), Chat & DM Leads (leads-chat.html), Email Inbox (leads-email.html) - One page per channel: every website form submission (HubSpot), phone call (Bland AI phone agent, Twilio call log), text conversation (Twilio), web chat (Voiceflow) and email (mailboxes), with search, year, filters and the full record. Export CSV saves every row that matches the search, filter and year. Track as lead puts the person in the lead pipeline below. Lead statuses are New, Contacted, Qualified, Converted and Lost. The conversations are captured by the Communications module (below); the lead pipeline holds the people your team is following up. You can also add leads by hand. A lead tracked from a communication keeps only a pointer to it, the person's name (or their email address or phone number when no name was captured) and its own status and owner (in this browser). Its email, phone, subject and summary are read from the Communications folder each time a page shows them, so only Name, Status and Owner can be changed when you edit it. Deleting the lead leaves the communication in place. ### Marketing module Google Ads (marketing-google-ads.html) - Keep ad campaign numbers: budget, spend, clicks, conversions and return. Import a Google Ads CSV report and export your data. Meta Ads (marketing-meta-ads.html) - The same for Facebook and Instagram ads. Social Posts (marketing-social-posts.html) - Write posts for Instagram, Facebook, TikTok, LinkedIn, YouTube and X. Save drafts and plan dates. Social Calendar (marketing-social-calendar.html) - See planned posts on a month calendar. Email Campaigns (marketing-email-campaigns.html) - The marketing emails already sent through HubSpot with their real results, templates and segments, and your campaign drafts: subject line, preheader, message and audience. - When the business has Communications, drafts are kept in the business folder (Communications\campaigns\drafts.csv) and the audiences come from Contacts: everyone with an email address, customers (QuickBooks account with invoices), prospects, marketing-only contacts, QuickBooks accounts without invoices, saved segments, or a manual list of pasted addresses. People who unsubscribed are left out. - Without Communications, the page says "This browser only": drafts stay in this browser and the audiences come from the customer list, which cannot be checked against people who unsubscribed. While the business folder is still opening, drafts saved meanwhile stay in this browser and move into the folder once it opens. - Opens and clicks are counted as events (repeat opens count again), so there is no open rate. Sending is not connected: Schedule only sets a reminder. To send, export the audience with the button beside Audience (Export recipient list) and use your own email tool. Live ad numbers and automatic posting each need their outside service connected. Saving an account ID alone does not connect it. Sending email is not connected (see Email Campaigns). The Google Ads, Meta Ads, Phone Leads, Web Form Leads and Leads Overview pages also show a "From Reports" strip: the latest finished month's real numbers from the Reports module, with a link to the full report. ### Company & Team Company & Brand Kit (company.html) is this business's profile, and the "brand kit" everything else uses: - Company: name, legal name, tagline, industry, year started, what the business does, services, service area, time zone and currency. - Logo & colors: upload the logo (PNG, JPG, SVG or WebP); pick the brand colors and fonts. - Contact & location: phone (and how it is printed), email, website, address, hours, Google Business Profile, and the Google Workspace domain allowed to sign in to Google Sheets sync. - Letterhead & documents: letterhead tagline, payment terms, the ship-to name on purchase orders, who signs, remit-to and the invoice footer. - Legal, Social & reviews. - Brand voice for AI: personality, tone, audience, why customers choose you, key messages, words to use and avoid, style rules, call to action, "about us" text and examples. The AI helper reads this "AI brand brief" before it writes anything for the business. Invoices, purchase orders, delivery slips, printed tables and emails use these details (name, logo, tagline, website, phone, terms). A live letterhead preview shows the result before you save. Saved to the business's Company\profile.json; the logo to Company\logo.. Team & Assignments (team.html) is where you manage the people at this business and what they are working on, like the owner and activity timeline in HubSpot or Salesforce: - Team members: name, role, email, phone, start date, color, "also known as" names, and former members (kept for history). - Assign work: a task, a job (dispatch order), a sale (invoice), a lead (OS leads, plus calls and forms from Reports) or a customer. Each has a status (Open, In progress, Waiting, Done, Cancelled), priority, due date, value and notes. - Every assignment and status change goes into the History with who made it and when. Each member shows open and overdue work, work done in the last 30 days, completion rate and average days to done. - Invoices whose QuickBooks sales rep, or leads whose owner, matches a member's name or "also known as" names are suggested for that member's list. Saved to the business's Company\team.json. ### Reports module Reports (reports.html, sidebar → Reports module) was the separate GymSpotter Reports app. It now lives inside GymSpotter OS. It shows the business you are in; switch businesses with the arrow beside the sidebar logo. - Overview, This month, Trends: leads, calls, forms, texts, missed calls, cost per lead and ad spend, compared with last month and last year. - Lead map and Lead sources: where leads come from (ZIP, town, county, state) and how they found the business. - All leads: every call, form and text, with each person's history. - Calls, Forms, Texts, Google Ads results, Meta Ads results, SEO rankings: one page per channel. - Monthly reports: each month's client report (interactive HTML and Letter PDF), screenshots and exports. Build report writes a new one. - Import & sync: load the same exports as always (800.com Calls and Messages CSVs, Google Takeout of form and text emails, Google Ads tables, Meta Ads exports, GA4, Search Console, Ahrefs, HubSpot deals), or pull them through the APIs connected in Integrations. - Data & CSVs and Shared documents: the tables behind every number, and documents that are not tied to one month. - Hide contact info masks names, phone numbers and emails before you share your screen. The Reports module runs a small local engine that needs Node.js 18 or newer. Start GymSpotter OS.cmd starts and stops it. Each business's Reports data is in its own folder (config\accounts.json); a business has Reports once its folder holds a client.json, which "Set up Reports" creates. ### Communications module Communications was the separate GymSpotter web chat app. It now lives inside GymSpotter OS and is where the app captures every conversation with the people who contact a business: web chat (Voiceflow), phone calls (Bland AI phone agent, Twilio call log), texts (Twilio), website forms (HubSpot), email (mailbox imports) and the HubSpot email marketing library, tied together in one contact list. It is the source of this data: the Leads pages, Contacts, Customers, the Dashboard, Global Search and Email Campaigns all read it from there. - Customer or contact: a customer has paid (a QuickBooks account with invoices). A contact matched to a QuickBooks account with no invoices yet shows as QuickBooks account, and a supplier as Vendor. Everyone else is a prospect (got in touch, not a customer yet) or marketing only (only marketing email or a HubSpot profile). People are matched across channels by exact email address or full phone number, never by name alone. - Each business keeps these records in its own folder, \Communications (Gym Tech Fitness has its web chat, calls, forms, HubSpot export and email marketing there). A business without the folder gets "Set up Communications". - Connections are made in Integrations → Communications: Twilio (texts and calls; one account for both), Voiceflow, Bland AI, HubSpot website forms and marketing email, mailboxes, GA4. Keys stay on this computer, outside the business folder. Each card's Guide button opens that provider's guide. - With "Keep connected after a restart" checked (the default), Twilio, Voiceflow, Bland AI and HubSpot website forms reconnect by themselves about 15 seconds after the engine starts. Mailbox tokens expire within the hour and are never kept. - While GymSpotter OS runs, connected Voiceflow, Bland AI and HubSpot website forms are checked on the interval chosen on their card (30 seconds to 10 minutes), and connected mailboxes every 5 minutes. Twilio texts arrive with Sync texts or through the signed incoming-text webhook. - Nothing is ever sent automatically. A text goes out only when Twilio sending is switched on and you click Send text on a saved draft and then Send now. - It runs a small local engine that needs Node.js 22.5 or newer; Start GymSpotter OS.cmd starts and stops it. The AI helper's comms_* tools read it (see guides/leads/llm.txt and modules/communications/README.md). ### GymSpotter Tools GymSpotter Tools are apps made only for the fitness equipment industry, opened from the GymSpotter Tools button in the top bar (and the GymSpotter Tools section of the sidebar). Each also works on its own outside the OS. See guides/tools/llm.txt. - Gym Designer (gym-designer.html): plan a gym floor to scale, view it in 3D, check clearances, walkways, exits, ceiling, power and floor load, and build a proposal (PDF). Its equipment is the product listing of the business's own website (Company & Brand Kit → Website; WooCommerce or Shopify), so each business plans only with what it sells; a business without a store website sees demo equipment and why. On the proposal, "Find a customer in GymSpotter OS" searches this business's customers, and "Create invoice in GymSpotter OS" opens Invoices with the New Invoice filled in (customer, equipment and extras lines, discount, tax, notes) for the user to check and save. - It runs a small local engine (modules/gym-designer) that needs Node.js 18 or newer; Start GymSpotter OS.cmd starts and stops it. Catalogs are kept on this computer and read again every 6 hours; "Refresh products" reads the website now. ## Pages and tools for every module - Dashboard (dashboard.html): totals for the whole business, delivery status, stock, recent work and a calendar. Quick Lookup finds an order by its ID or PO number. - Global Search (global-search.html): search everything that is loaded and open the match. An email address, or a phone number typed in any common format (with spaces, dashes, dots, brackets or +1, or digits only), also finds the contact and their calls, texts, chats, forms and emails (the Communications section after Customers). - Documentation (documentation.html): help, shortcuts, and a link to this guide. - Company & Brand Kit (company.html) and Team & Assignments (team.html): sidebar → Company & Team. See "Company & Team" above. - Gym Designer (gym-designer.html): the GymSpotter Tools button in the top bar, or sidebar → GymSpotter Tools. See "GymSpotter Tools" above. - Resources (sidebar): Documentation, Grasshopper Platform, QuickBooks Online, HubSpot and the business's own website ("Gym Tech Fitness Website" for Gym Tech). - Integrations (integrations.html): every connection in one place: QuickBooks, Google Sheets, Grasshopper, the Communications connections (Twilio, Voiceflow, Bland AI, HubSpot website forms and email library, mailboxes, Google Analytics import, the Communications folder), HubSpot, 800.com, website forms (Gmail), Google Ads, Meta Ads, GA4, Search Console, Ahrefs, the Google sign-in, MCP servers for AI agents, and the Reports data folder. Open it with the Integrations button in the top bar (the arrow beside it shows each connection's status), Settings → Integrations, or sidebar → Settings. Tokens stay on this computer and are never shown again in full. - Settings: Integrations (QuickBooks, Google Sheets and Grasshopper forms), folder, theme (light or dark), table columns, webhooks, activity log and help. - File browser (left side): see the files in your business folder and open them. - Quick search: Ctrl+K (or Cmd+K on a Mac) opens quick search (typed searches work on the Global Search page). It does not include calls, texts, chats, forms or email; use Global Search for those. ## The AI helper (right panel) Open the AI helper with the AI button at the top of the screen. You can ask it to: - Explain a page, a number or a record. - Find invoices, purchase orders, customers, stock or deliveries. - Fill in a form for you, like a new invoice, purchase order, delivery or lead. - Open a record's PDF, change a status, or move to another page. It can read a PDF or image you add, if the model you chose can read documents. How it stays safe: - Before anything is saved, sent, created or deleted, the AI shows an Approve and Cancel card. Only your own click on Approve lets it happen. The AI cannot approve for you. - Cancel stops the action and keeps what was filled in, so you can check it. - If you press the form's own Save button, the AI's waiting action is canceled so nothing saves twice. - It cannot see or change passwords or API keys, and it cannot skip the app's checks. - It cannot pick files on your computer. You must click a file or folder picker yourself. - Always check the saved record. A message saying "done" is not proof. ### AI settings: API keys and models Open the AI panel, then the key button, to open AI settings. Setup has two steps. Step 1: API keys. There is a box for each AI company: - OpenAI (GPT models) - Anthropic (Claude models) - Google Gemini - xAI Grok - Local model (optional, an AI running on your own computer, like Ollama) Paste a key and press Save key. You can save a key for every company at the same time. Each box also has: - Test connection: sends a tiny real request and tells you if the key and model work. - Load models: asks that company which models your key can use and fills the model lists. - Remove key: deletes the saved key. Step 2: pick a model for each job. Each job can use a different company: - Chat & actions: normal chat, and filling forms or doing tasks on the page. Pick a model that can use tools. - Quick replies: fast, low-cost answers. - Document reading: reads PDFs and images for AI Scan and attached files. A company without a saved key shows "(add key first)". If a model is not listed, choose "Other model ID…" and type its exact name. Press Save task models when you are done. The first key you save sets all three jobs to that company's suggested models, so the helper works right away. Suggested models (checked October 10, 2026; use Load models to see what your account has): - OpenAI: gpt-6-astra for chat and documents, gpt-6-luna for quick replies. - Anthropic: claude-opus-5-5 for chat, claude-haiku-4-5-20251001 for quick replies, claude-sonnet-5-5 for documents. - Google Gemini: gemini-3.8-flash for chat and documents, gemini-3.5-flash-lite for quick replies. - xAI Grok: grok-4.7 for chat, grok-4.20-0309-non-reasoning for quick replies. Grok and local models read images, not PDFs. Use OpenAI, Anthropic or Google for reading PDFs. How your keys are kept safe: - Saved keys are locked (encrypted) with your Windows account and stored in config\ai-settings.json inside the GymSpotter OS folder. They only work for the same Windows user on the same computer. - The web page never receives your keys. It only learns that a key exists and its last four characters. - Keys are never shown in the black launcher window or in error messages. - Keys go only from the launcher to the AI company you chose. - An older .env file still works as a backup. A key saved in the app is used first. - Never share the config folder or a .env file that has keys in it. What gets sent: when you send a message, the AI company you chose for that job gets your message, the conversation and the information on the current page. Adding a file or using AI Scan sends that file too. A local model keeps everything on your computer. Offline mode blocks all internet AI. ## WebMCP: how an AI uses the app WebMCP is a web standard that lets an AI see and use a web page's buttons and forms. Every one of the 33 pages has the same 29 WebMCP tools, and some pages add their module's own: reports_* on Reports, brand_* on Company & Brand Kit, team_* on Team & Assignments, and comms_* (calls, texts, chats, forms, email and contacts) on every page that shows Communications. The AI helper in the right panel uses them. So can an AI built into your web browser, if your browser supports WebMCP (the app connects to it automatically). Every form on every page is also labeled for AIs. That is 67 forms in all, each with a name, a description and a plain description of each field. Tools that read (they never change anything): - get_page_context: what page this is and what it shows. - list_pages: every page with its title and file. - get_app_overview: the modules, pages and how much data loaded. - search_records: find invoices, purchase orders, expenses, deliveries, customers, vendors, stock, leads or campaigns by words, number, status, date or amount. Email campaign drafts kept in the business folder are found only on the Email Campaigns page, once that page has loaded them (get_app_overview counts them the same way). - comms_overview, comms_search, comms_list, comms_get, comms_contact_history, comms_customer_communications: read calls, texts, web chats, website forms, email and contacts (on the pages that show Communications). - get_record: all the details of one record, including the name of its PDF. - get_finance_summary: the same totals the Finance page shows. - list_controls, inspect_control: find buttons and fields on the page and read them. - list_forms: list the open forms and their fields. - read_table: read the rows of a table. Tools that fill in or prepare (they do not save): - set_field, set_fields, fill_form: type into fields. Every value is checked first. If one value is wrong, nothing changes. - start_invoice, start_purchase_order, start_dispatch_order, start_customer, start_lead, start_campaign_or_post: open the right form and fill it in, ready for you to check. For an email campaign, start_campaign_or_post first waits (up to 20 seconds) for Email Campaigns to finish opening the business folder. - open_record_document: open a record's PDF in the app's viewer. - navigate_page: go to another page. Tools that change things (every change waits for your Approve click): - activate_control, submit_form: press a button or send a form, like Save. A button that saves, sends, deletes, connects, pulls data or links records shows the Approve card first; one that only opens, filters or switches a view is pressed right away. The Communications pages mark such buttons for approval (data-gymspotter-final): Track as lead, the contact dialog's Detach and Link the record, the Add tag dialog's save button, Set up Communications, Refresh customer matches, Refresh from HubSpot (Email Campaigns), and every Integrations card button except Guide and "Show the yearly archives". - update_record_status: change an invoice, purchase order, delivery, lead, or campaign or post status (for a campaign it waits for Email Campaigns the same way). - mark_po_received: record that a purchase order arrived. - convert_invoice_to_dispatch: turn a paid invoice into a delivery order. - adjust_stock: change a stock count. - comms_save_message_draft: save a text or email draft for a contact (it opens the message window first). comms_send_sms: send a saved text through Twilio; after you approve, the app still asks you to press Send now. Rules every tool follows: - Saving, sending, deleting, receiving, changing stock, and connecting or pulling data always show an Approve and Cancel card first. Only a real click or key press from you approves it. The AI cannot approve its own action, and a "confirmed" value sent by the AI is ignored. - Fields that save the moment they change cannot be changed by the AI. For table cells it uses the full form instead, so you can check it. Selects marked data-gymspotter-saves-on-change (a tracked lead's status, and a web chat's Conversation status and Assigned to) are refused by set_field with "Ask the user to change it in the app." - The AI cannot see or change passwords, API keys, or the connection settings for the bridge, Google Sheets and QuickBooks. - The AI cannot use hidden, locked or read-only fields, and cannot skip the app's checks. - File and folder pickers still need your own click. - If a tool needs a different page, it opens that page and finishes there. - An open form is never cleared by a tool. For developers: the tools are registered with document.modelContext.registerTool (and the older navigator.modelContext where it exists), following the W3C WebMCP draft of October 2026. Forms carry the declarative attributes toolname, tooldescription, toolparamtitle and toolparamdescription. toolautosubmit is used only on read-only forms. The same tools can be called from page code with window.GYMSPOTTER_WEB_MCP.invoke(name, args). ## Accessibility The app is built to meet WCAG 2.2 level AA: - Everything works with a keyboard. Tab moves forward, Shift+Tab moves back, Enter and Space press buttons, and Escape closes pop-ups. - The first Tab shows a "Skip to main content" link. - The control you are on always has a clear outline. - Pop-up windows keep the keyboard inside them, and focus goes back where you were when they close. - Every field, button and table has a name a screen reader can read. Charts have a text table with the same numbers. - Text and important lines have strong color contrast in light and dark themes. - Buttons are big enough to tap. Pages work at 320 pixels wide and at 200% zoom with no sideways scrolling. - Anything you can drag also has a button or menu that does the same thing. - Reduced motion and high-contrast (forced colors) settings are respected. Automated checks and keyboard tests passed, but they cannot prove full legal ADA compliance. Testing with real screen reader users is still recommended before claiming it. ## Common problems and fixes Nothing shows up - Start the app with "Start GymSpotter OS.cmd", not by opening an .html file. - Read the black window. It says which folder it uses and how many files it found. - Open Data Sources and read the warnings. - Check that a filter or date range is not hiding records. - If you picked a folder by hand, pick the folder that holds Invoices, Purchases, Orders, Inventory and Customers, not one of those folders. The old "GymTech App" folder inside your business folder has only empty folders. Do not pick it. A PDF is not linked to its record - Check that it is a QuickBooks PDF with real text (not a scanned picture). - Check Data Sources for a warning about that PDF. - Open the record and use Attach, or link the file from the file browser. A total looks different from QuickBooks - Open the record. A note shows if the PDF and the report disagree. - Export the report again from QuickBooks so both match, then click "Refresh folder data". The first load is slow - PDFs from the splitter have a metadata index, so the app can read their values without opening every PDF. Older PDFs without that index are read once. Leave the window open until the load finishes. The AI does not answer - Check AI settings: the right provider, a saved key, and a model your account can use. - Use "Test connection" in AI settings. - Offline mode blocks internet AI. Use the normal start file, or a local model. A connection says "saved" but nothing happens - Saving an account ID or address only stores it. The outside service still has to be connected and working. ## Quick reference for AI models - Local address: http://localhost:8787 (the start file prints the real address). - Pages (all 33; page keys in shared/shell.js, GYMSPOTTER_PAGE_FILES): dashboard.html, global-search.html, finance.html, customers.html, invoices.html, purchases.html, dispatch-overview.html, dispatch-orders.html, dispatch-calendar.html, kanban-board.html, new-dispatch-order.html, warehouse.html, inventory.html, item-skus.html, shipping-calculator.html, pipeline.html, leads-overview.html, contacts.html, leads-web-forms.html, leads-phone.html, leads-sms.html, leads-chat.html, leads-email.html, marketing-google-ads.html, marketing-meta-ads.html, marketing-social-posts.html, marketing-social-calendar.html, marketing-email-campaigns.html, company.html, team.html, reports.html, integrations.html, documentation.html. - Modules: Finance (finance, customers, invoices, purchases), Dispatch (dispatch-overview, dispatch-orders, dispatch-calendar, kanban-board, new-dispatch-order), Warehouse (warehouse, inventory, item-skus, shipping-calculator), Leads (pipeline, leads-overview, contacts, leads-web-forms, leads-phone, leads-sms, leads-chat, leads-email), Marketing (marketing-google-ads, marketing-meta-ads, marketing-social-posts, marketing-social-calendar, marketing-email-campaigns), Company & Team (company, team), Reports (reports), Settings (integrations). Dashboard, Global Search and Documentation are app-wide pages. - Invoice statuses: Draft, Sent, Paid, Overdue, Converted, Cancelled, Needs review. - Purchase order statuses: Draft, Sent, Partial, Received, Cancelled, Needs review. - Lead statuses: New, Contacted, Qualified, Converted, Lost. - Records read from a PDF carry the PDF's file name. Linked PDFs open with the record. - Data is ready when window.gymspotter.state.folderDataReady is true, or after awaiting window.gymspotter.dataReady. ## QB Bulk Print Splitter Tool This separate local tool turns a large QuickBooks PDF into one PDF per invoice. An invoice with several pages keeps all of its pages. Open it with Start QB Bulk Print Splitter Tool.cmd in D:\GYM TECH QB FILES\QB Bulk Print Splitter Tool. It works offline and can be reused for other companies. Choose the PDF folder, master sales report, optional customer report and a new output folder. Check the columns, analyze the files and review the plan. Company names go before the person's last and first names. Company and joint names are kept whole when the source has no clear person name. You can edit a name before running. A real click or keyboard action approves the plan in the browser. New PDFs go into year folders. Their PDF metadata and Windows Created and Modified dates use the invoice date at midnight in the chosen time zone. The separate processing date shows when the tool made the new file. Originals stay unchanged. Repeated prints get different file IDs and can link to the same master invoice without adding extra revenue. Each matched PDF carries a stable file ID, master record ID, customer and parent details, all original report values, source page numbers and match evidence. The same data is also in an attached JSON file, XMP and a metadata index beside the year folders. The index lets GymSpotter read invoice data even when a PDF cannot be opened. The normalized master CSV controls financial totals. It preserves the original columns and does not invent line items. Files that disagree with the master go into Needs Review. Their printed values and any possible master records stay in the metadata for review. They do not add money to Finance. Older report tabs remain available, while All Sources uses the complete master report when it is present. Older rows absent from the master have a warning. Canceling a run keeps already completed files and a partial manifest; use a new output folder for a fresh run. The splitter offers 13 WebMCP actions for choosing files, checking columns, reading and editing the plan, starting an approved run, getting results and canceling work or reconnecting to a running job. An AI cannot approve its own plan. No API key is needed for splitting. The tool rejects unsupported PDF formats with an error.