WaxFrame User Manual

WaxFrame runs multiple AI assistants on your document at the same time. Most of them act as reviewers — they each read your document independently and produce numbered, specific suggestions for improvement. One AI acts as the Builder — it reads every suggestion from every reviewer, decides which ones are the strongest, and rewrites the document incorporating them. You review the result, resolve any disagreements between AIs, and run another round if needed. Each round the document improves — you stop when you're satisfied with the result.

WaxFrame works whether you are starting from a blank page, improving an existing draft, uploading a file, or pasting content in. It handles any kind of written document — business proposals, technical reports, cover letters, blog posts, marketing copy, executive summaries, policy documents, résumés, and more.

WaxFrame walks you through five setup screens in order before you reach the Work screen. Each screen is dedicated to one task, and you can move forward or back freely using the navigation buttons at the top of each screen.

Screen	What you do there
Setup 1 — Worker Bees	Connect your AI assistants by saving their API keys. This is a one-time setup — your configuration is saved automatically and is there every time you return.
Setup 2 — Builder	Choose which AI will act as the Builder — the AI that rewrites your document each round.
Setup 3 — Your Project	Name your project and fill in the structured goal fields that guide every AI.
Setup 4 — Reference Material	Optional. Paste or upload source material The Hive will reference on every round but never edit — job descriptions (rules and responsibilities), RFP requirements, style guides, scoring rubrics, prior decisions, vendor claims.
Setup 5 — Starting Document	Upload a file, paste text, or choose to start from scratch and let the AIs write the first draft.
Work	Run rounds, read the updated document, resolve conflicts between AIs, refine further if needed, and export when you are done.

WaxFrame connects to AI providers using API keys. An API key is a unique code — like a password — that gives WaxFrame permission to use a specific AI on your behalf. You need at least two API keys from any combination of the supported providers: ChatGPT (OpenAI), Claude (Anthropic), Gemini (Google), Grok (xAI), Perplexity, or DeepSeek.

You pay each AI provider directly for the tokens you use. WaxFrame itself does not charge per use — it requires only a one-time license fee after your first three free rounds.

↑ Back to top

Every new installation of WaxFrame includes three free rounds. A round is one complete cycle — all your reviewer AIs process the document and the Builder produces an updated version. Three rounds is enough to see meaningful improvement on most documents. The free round count is stored in your browser and persists across sessions — it does not reset when you start a new project.

After your three free rounds, WaxFrame requires a license key to run additional rounds. Purchase one at weirdave.gumroad.com/l/WaxFrame. Your key arrives by email immediately after purchase. The license is a one-time purchase with no subscription or renewal fee.

1. 1Click the Menu button in the top left corner of any screen. It shows three horizontal lines with the word Menu next to it.
2. 2In the menu panel that slides in from the left, click 🔑 Enter License Key.
3. 3A dialog box appears. Paste your license key into the field and click Unlock Pro.
4. 4WaxFrame validates the key against the server. If valid, a confirmation animation plays and unlimited rounds are unlocked immediately. A small license badge appears in the top bar of the Work screen to confirm your status.

↑ Back to top

File / Folder	What it is
index.html	The main application. Double-click this to open WaxFrame in your browser. This is the only file you interact with directly.
style.css	Visual styling for the application. Do not edit.
app.js	All application logic. Do not edit.
version.js	Application version number. Do not edit.
api-links.js	API console links used by helper pages. Do not edit.
theme.js	Light/dark theme logic for helper pages. Do not edit.
api-details.html	The API Key Guide — a separate page with step-by-step instructions for getting an API key from each supported provider, including direct links to each provider's signup page and key console.
waxframe-user-manual.html	This document.
document-playbooks.html	A library of ready-made project goals for common document types — résumés, business proposals, blog posts, RFPs, cover letters, and more. Open this when you are not sure what to write for your project goal.
what-are-tokens.html	A plain-English explanation of AI tokens, how they are counted, what they cost, and how to manage your spending across providers.
prompt-editor.html	An advanced tool for customising the exact instructions WaxFrame sends to your AIs each round. For experienced users only.
images/	All icons and images used by the application.
sounds/	Sound effects played during rounds and at completion.
docs/	PDF versions of this manual and the Getting Started guide for printing or offline reference.

WaxFrame is a browser-based application. There is nothing to install — you open index.html in any modern web browser and the app runs entirely in that browser window. Your API keys, settings, and session data are saved in your browser's local storage, not in the folder. This means the files in the folder never change as you use the app.

Once you have index.html open, bookmark it in your browser using Ctrl+D on Windows or Cmd+D on Mac so you can open it quickly in future. On Windows you can also right-click the file in File Explorer and choose Send to → Desktop (create shortcut). On Mac, drag the file to your Dock to pin it.

↑ Back to top

After clicking Let's get started → on the welcome screen, you arrive at the first setup screen: Worker Bees. This is a full-width screen dedicated to connecting your AI assistants. Your Worker Bees are the AI assistants that act as reviewers each round. They each read your document independently and produce a numbered list of specific suggestions. You need at least two Worker Bees with saved API keys before WaxFrame will allow you to proceed — but three or more is the empirical recommendation because runs converge faster with three reviewers and reviewer disagreements get resolved automatically by majority instead of pausing the run for your decision. A status indicator at the bottom of the screen shows whether the minimum is met.

Directly above the list of AIs, a hive count chip shows the total number of AIs in your hive and how many of them have saved API keys. This is purely informational — WaxFrame's convergence logic is a threshold check (a majority of the hive must agree on "no more changes"), not an either-or vote between competing proposals, so there is no tie risk on convergence regardless of whether your count is even or odd. (This is different from how reviewers resolve specific change disagreements during a round — with only two reviewers a disagreement can tie and pause the run for your decision, which is why three or more is recommended. See Step 5 below.)

WaxFrame talks to each AI through its API, not through the consumer chat product you might already pay a monthly fee for. This matters for cost: APIs charge per usage in one-time credits, not as a recurring subscription. You pay only for the tokens you actually send and receive — typically a fraction of a cent per round per reviewer.

Gemini's API is currently free within Google's published rate limits. This makes Gemini a useful free reviewer to anchor your hive, and it's why Gemini-as-Builder is a common starting configuration. The other five default providers — ChatGPT (OpenAI), Claude (Anthropic), DeepSeek, xAI (Grok), Perplexity — each require a one-time minimum API credit purchase, typically starting at $5. Once loaded, the credit stays in your account and only depletes as you actually use the API; an unused credit doesn't expire monthly the way an unused subscription month does.

Gemini paid-tier caveat. Gemini's free tier applies only while your Google AI Studio account has billing disabled. The moment you add a credit card and enable billing — even if you intended to stay on the free tier — Gemini requests can route through paid-tier paths and charge per token. The Builder role amplifies this because it reads project setup, reference material, the full working document, and every reviewer's suggestions every round, then writes the document back out. A multi-round session with paid-tier Gemini as Builder on a long document with reference material attached can chew through a few dollars unexpectedly. For casual use, keep billing off on AI Studio. If billing is on, check the AI Studio usage page after longer runs, and consider keeping Gemini as a Reviewer (lighter token load) rather than the Builder.

Practical cost ladder:

• Cheapest entry point: Gemini (free) + one paid provider with the minimum $5 credit = 2-AI hive, about $5 in one-time credits. Meets the WaxFrame minimum to continue and runs an entire document refinement session.
• Recommended hive: Gemini (free) + two paid providers = 3-AI hive, about $10 in one-time credits. Hits the empirical 3+ recommendation for faster convergence and automatic resolution of reviewer disagreements (see the status bar block for why 2 vs 3 matters).
• Full default hive: All six default providers loaded with minimum credits = about $30 total in one-time credits.

For context: the equivalent consumer subscription stack — ChatGPT Plus, Claude Pro, Gemini Advanced, and the paid tiers of Perplexity, xAI, and DeepSeek combined — runs around $120 per month. WaxFrame's API-based approach is dramatically cheaper for document refinement because you only pay for the tokens you process, not for unused capacity.

If you're cost-conscious, the temptation is to stop at the $5 minimum (one paid provider + free Gemini). That works — you'll meet the 2-AI requirement and complete real document runs — but the jump from about $5 to about $10 in one-time credits (adding one more paid provider) buys you the 3+ hive that the empirical Brightwater testing showed converges faster and resolves disagreements automatically. The $5 difference is the gap between "barely works" and "works reliably."

Directly under the Your Worker Bees heading and above the toolbar, two big buttons toggle the screen between two modes. The active one is highlighted:

Flipping the toggle filters the visible AI list and rebuilds the toolbar — the underlying inventory is unchanged. You can move freely between modes without losing anything.

In Internet mode (the default), the toolbar across the top of the Worker Bees panel shows five buttons followed by two compact row controls on the right. In order, left to right:

In Server mode, the toolbar shows a narrower set of buttons appropriate for managing AIs imported from a model server:

Not in Server mode: the API Key Guide button (the default-provider key-acquisition flow doesn't apply), Recommend Models for All (server-hosted models are picked by your gateway operator, not by web research), and Open default AI websites (server endpoints don't have provider billing dashboards).

Once you've added at least one custom AI (via Add Custom AI or Import from Model Server), a small toolbar appears between the main toolbar and the AI list. It exists for removing customs in batch instead of one at a time. When no customs exist, this row is hidden and the AI list sits directly under the main toolbar.

The toolbar shows:

Below the toolbars is the list of your Worker Bees. By default, six AIs are shown in Internet mode: ChatGPT, Claude, DeepSeek, Gemini, Grok, and Perplexity. Each AI is a collapsible row with two states.

Collapsed (default state) — the row shows just the basics:

Expanded state — clicking the row reveals the setup panel, containing all the controls for entering a key and picking a model:

1. 1Locate the AI you want to connect in the list — for example, ChatGPT.
2. 2Click the API Key field next to that AI — the field with the placeholder text Paste key — Enter to save…
3. 3Paste your API key using Ctrl+V on Windows or Cmd+V on Mac, then press Enter. The key status indicator changes to 🔑 to confirm the key is saved.
4. 4Click the Test button that now appears next to the key field. Confirm the test passes before continuing.
5. 5Repeat steps 1–4 for at least two more AIs. Two AIs is the technical minimum to proceed, but three or more is strongly recommended — runs converge faster with three reviewers, and disagreements between reviewers about specific changes get resolved automatically by majority instead of pausing the run for your decision. In our reference Brightwater Canoe and Kayak business proposal test (May 2026, three measured runs): the early v1.0 scaffold with a three-AI hive converged in 3 rounds in about 8 minutes; the polished v3.0 scaffold (a more developed version of the same project with more constraints to satisfy) with a three-AI hive converged in 5 rounds in about 10 minutes; the v2.0 stress test with only two AIs took 11 rounds in about 16 minutes because Round 5 hit a tied reviewer disagreement that paused the run for manual resolution. The two-AI tie-halt is what drove the move to recommending three or more reviewers.

At the very bottom of the Setup screen, a status bar shows exactly what is still needed before you can continue. It reads: To continue you need: followed by two indicators:

• ✗ At least 2 AIs set up — shows a red ✗ until two or more AIs have saved keys (the indicator also includes a live count, e.g. (1 so far)). Turns green ✓ when the requirement is met.
• ✗ Builder selected — shows a red ✗ until you have selected a Builder on the next screen (Setup 2). Turns green ✓ when selected.

The Continue — Choose Builder → button at the bottom right of the screen remains inactive until the keys indicator is green.

↑ Back to top

After continuing from the Worker Bees screen, you arrive at Setup 2: Builder. This is a full-width screen dedicated to choosing which AI will rewrite your document each round. While your Worker Bees (reviewers) each produce numbered suggestions, the Builder reads all of those suggestions and the full document and produces the updated version.

Every Worker Bee reads the document and gives suggestions. The Builder does the actual writing. Because the Builder must process the entire document plus all reviewer suggestions every single round, it consumes significantly more tokens than any individual reviewer. This has two practical implications:

• The Builder must have a paid API subscription with sufficient token capacity. Free-tier API accounts have low limits and will cause rounds to fail mid-way through.
• Choosing a capable, reliable AI as your Builder matters more than your choice of reviewers. The Builder's output is what you see in the working document after each round.

The Builder plays two distinct roles in WaxFrame. In a full round (when you click Smoke the Hive), it acts as the synthesizer — reading every reviewer's suggestions plus the full document and producing the new version that incorporates the consensus.

Between full rounds, the Builder also acts as your handyman. Open the Notes drawer (📝 Notes button in the top bar), write a directive — anything from "rewrite the first paragraph" to "stop using the word 'refine' so much" to "the conclusion needs to be more decisive" — then click Send to Builder in the footer. The Builder performs just that one task without running the reviewers, saving tokens and time. After the Builder finishes, you can click Smoke the Hive to see if the reviewers agree with the change.

This pairing is one of WaxFrame's most useful workflows: targeted edits via Notes + Send to Builder, then full reviewer feedback via Smoke the Hive when you want validation. Use it when you have a specific change in mind that you don't need the whole hive to debate first.

The screen body shows a grid of cards, one for each AI that has a saved API key in your hive. AIs without a saved key do not appear here — you must save a key for an AI in Step 1 before it can be selected as Builder.

Each card shows the AI's name and icon. Click a card to select that AI as your Builder. The selected card is highlighted and marked with a small Builder badge in the top-right corner — the Builder Bee mascot image — that indicates this AI is the current Builder. Only one AI can be the Builder at a time. You can change your Builder at any time, including from the Work screen during an active session, where the selected Builder is shown with a 👑 crown label in the Change Builder modal.

Once the status bar at the bottom shows ✓ Builder selected in green, the Continue — Your Project → button at the bottom right of the screen activates. Click it to move to the Project screen. Your Builder selection is saved automatically — it will be there every time you return to WaxFrame.

↑ Back to top

Setup 3 — Your Project — is a single scrollable screen. At the top is your project name and version, followed by the Project Goal section with six structured fields. Work through the fields top to bottom.

You can either fill in the goal fields manually, or click 📋 Use Template in the section header to pre-fill them from a curated library of document types. If this is your first time running WaxFrame, click 📋 Use Template, pick Starting from scratch on the path picker, then choose ⭐ Quick Start — a small, low-stakes project where the hive writes and refines a real chocolate-chip-cookie recipe across a few rounds. Identical flow to any other project; the recipe is small enough to see convergence quickly and the topic is harmless enough that nothing rides on the outcome.

The 📋 Use Template button at the top of the Project section opens a gallery of 19 templates organised into 6 categories. The gallery first asks whether you are starting from scratch or refining an existing draft (the path picker), then shows the templates that fit your chosen path. Click any card to populate all six Project Goal fields with proven starting content for that document type.

Category	Templates
Quick Start	⭐ Quick Start (chocolate chip cookies — recommended for new users; scratch path only)
Career & Hiring	✉️ Cover Letter · 🔍 Job Description · 📄 Résumé · 🔗 LinkedIn About · 🙏 Thank-You Letter
Business & Sales	💼 Business Proposal · 📬 Email & Outreach · 📊 Executive Summary · 📋 RFP Response
Content & Marketing	📝 Blog Post / Article · 🖥️ Presentation Outline · 💼 LinkedIn Post
Personal & Everyday	🍳 Recipe · 🧾 Contractor / Vendor Letter
Reviews & Recommendations	🍽️ Restaurant Review · 🏨 Hotel Review · 🧾 Business / Service Review · ✈️ Trim to TripAdvisor · 📍 Trim to Google Maps · 💬 Rewrite as Yelp (the three platform templates are refine-only — they reshape an existing review)

How template apply works. Click a card → if the Goal fields are empty, the template populates silently. If any field has content, a confirmation prompt appears warning that current entries will be replaced. Project name, version, length constraint, Reference Material, and Starting Document are never touched — only the six Goal fields.

Template Hint banner. Most templates contain [bracketed] placeholders the user must fill in — for example [company name] or [job title]. After applying a template with placeholders, an amber-bordered banner appears above the Project Name with a per-field bulleted list telling you exactly which form field to look at and what to fix there. Templates that ship clean (Quick Start, Executive Summary) skip the banner entirely.

At the top of the screen, below the intro, is the project name field. Type a name for your project here. This name is used in the export filename and appears in the round history. It has no effect on how the AIs work — it is purely for your own organisation. Examples: Q3 Board Report, Marketing Email — Product Launch, Cover Letter — Senior Engineer Role.

The smaller field next to the project name has the placeholder text Version — e.g. v1. Enter a version identifier here. This is also used in the export filename. Use whatever versioning makes sense to you — v1, draft1, 2.0, final. Like the project name, it does not affect how the AIs work.

Below the goal fields is a section headed Length Constraint. This is where you tell WaxFrame what kind of length rule applies to your document — not in the goal fields. As of v3.33.0 there are four modes covering the common cases:

Mode	What it does	When to use it
No limit	No length gating. Reviewers and Builder receive no length instruction. No round-end or convergence-time guards fire.	Default for documents where length is irrelevant or you want the hive to choose what fits.
Hard cap	Ceiling only. The Builder is told "stay at or below the limit; shorter is fine." Round-end and convergence-time guards fire only when the document goes over.	Documents with a maximum but no minimum — a tweet under 280 characters, a cover letter under 500 words, a report under 10 pages.
Target	Aim to hit the target value exactly. Both ceiling and floor guards are armed against the same value. Round-end checks are trajectory-aware so you only get prompted on rounds that move away from the target — a Builder converging from 320 down to 305 toward a 300-word target won't nag you, but a Builder going 305 to 320 will.	Documents where you want the hive aiming at a specific length — a 500-word essay, a 10-line poem, a strict word-count submission.
Range	Stay between a minimum and a maximum that you supply. The Builder is told "aim for the middle of that range." Both guards armed against their respective bounds.	Documents with both a floor and a ceiling — "between 800 and 1200 words", "3 to 5 paragraphs", "2 to 4 pages".

Important: put your length rule here — not in the Scope & constraints goal field. If you put "under 200 words" in your goal text, the AIs receive it as loose instruction mixed in with everything else, and it is easy to miss. When you pick a mode here, WaxFrame formats and enforces it explicitly in every round as a hard constraint separate from the rest of your goal.

Behind the scenes, after the Builder returns each round, WaxFrame measures the output in the exact unit you chose. If the result violates your active mode (over the cap, away from the target, outside the range), the gate prompts you with three options: Discard the round, Keep it anyway, or Continue anyway (which disables the guard for the rest of the project). The prior document is preserved on Discard — you never lose work to a gate failure. Here is how each unit is counted:

Unit	How it is counted	Notes
Characters	Every character in the text, including spaces.	Matches how web forms, SMS counters, and social media count. Accurate for plain English. Emoji and complex scripts can count differently than what appears on screen.
Words	Tokens separated by whitespace.	Matches how most submission forms count. Can differ from Microsoft Word by 1–2% on hyphenated terms or URLs. For hard ceilings elsewhere, trim a few words under your target as a buffer.
Paragraphs	Blocks of text separated by blank lines.	Matches how markdown, plain text, and Word documents denote paragraph breaks. Headings and bullet lists count as paragraphs if they are separated by blank lines.
Pages	Approximated using 600 words per single-spaced 12pt page (industry-standard typewriter math — Word's default and what most word processors round to). 1 page ≈ 600 words, 2 pages ≈ 1200 words, 5 pages ≈ 3000 words.	This is the one unit WaxFrame cannot measure directly — actual page count depends on your font, margins, and line spacing. For firm limits (court filings, one-page résumés), aim slightly under the target to leave headroom.

The convergence-time gate is symmetric: when the hive converges (unanimous or majority), WaxFrame checks the final document against your mode's bounds before celebrating. If the doc is over a cap, under a target, or outside a range, you get the same three-option prompt — Discard returns you to the work screen to edit and re-run, Keep accepts the convergence, Continue anyway accepts and silences the guard for the rest of the project session.

Who actually responds to length directives. Reviewers focus on prose quality — clarity, structure, persuasion, accuracy — and do not address length. Only the Builder responds to length directives, including the ✂ Trim, 📈 Expand, and 📐 Match Notes templates. If the document consistently overshoots your target across multiple reviewer rounds, that is expected — the reviewers are doing their job and the Builder is the lever for size. The standard playbook: wait for a round where reviewers signal they are done with prose changes, then run a Builder-Only round with the ✂ Trim template injected to compress the output. Real-world reference: a 1499-word document compressed to 1083 words (a 27.6% reduction) in a single Builder-Only round with one Trim injection.

Below the project name and version is the Project Goal section — six labelled fields assembled into a structured brief that every AI reads before each round. You do not need to fill all six — even two or three give the hive a strong foundation. Here is what each field is for:

Field	What to write
Document type	State the format clearly — a business proposal, a technical comparison, a cover letter, an executive summary. This is the first thing assembled into the brief and is always included when a document exists.
Target audience	Who will read this? IT Director, hiring manager, VP of Facilities, small business owners? The audience shapes the tone, language, and depth every AI uses.
Desired outcome	What do you want the reader to walk away able to do, decide, or understand? Give the AIs a finish line.
Scope & constraints	What must be covered — and what should be left out? AIs expand into adjacent topics unless you draw the boundary clearly. If you want wireless only and not switching or routing, say so here.
Tone & voice	Formal or conversational? Technical or plain-English? Confident or cautious? The more specific, the more consistent the output will be across rounds.
Additional instructions	Anything else the AIs need to know — style preferences, things to avoid, structure requirements, sections that must not be changed.

Every AI reads your assembled brief before touching your document. The goal works identically whether you are uploading a file, pasting text, or starting from scratch. The difference is only in what the AIs have to work with — not in how the brief is applied.

Vague fields produce a vague document. Specific, detailed fields produce something you can actually use.

The goal works the same whether you are uploading an existing document, pasting text, or starting from scratch. The AIs have nothing else to work from — no access to the internet, no knowledge of your organisation, no understanding of what you want unless you tell them. The more you put in, the better every round will be.

The most common mistake is writing a goal so short and vague that the AIs have to guess. They will guess — and they will all guess differently, which produces drift and conflicts that never resolve.

Too vague "Make this proposal better."

Much better "This is a wireless network infrastructure upgrade proposal for a 950,000 sq ft warehouse. Audience: IT Director (technical) and VP of Facilities (budget-focused). The technical sections and vendor comparison table are solid — do not change them. Focus all improvements on the executive summary, which is too long and too jargon-heavy for the VP, and on the cost justification section, which needs a clearer ROI narrative. Tone: confident and direct, not salesy. Do not add any new sections."

Too vague "Write a report about wireless networking."

Much better "Technical comparison of enterprise wireless networking platforms — HPE Aruba, Cisco Meraki, Juniper Mist, and Extreme Networks. Audience: IT infrastructure team evaluating a campus-wide refresh. Scope: strictly wireless — APs, controllers, cloud management, licensing. Exclude switching, routing, firewalls. Tone: technical and neutral. Include a summary comparison table at the top, a dedicated section per vendor covering strengths, weaknesses, and pricing, then a shortlist recommendation."

Field	What it controls	Tips
Document type	Sets the format, length conventions, and depth every AI aims for on every round. This is the first thing assembled into the brief and is always sent.	Be specific. Cover letter not document. If there is one thing the AIs should never forget, make it part of this field.
Target audience	Calibrates tone, vocabulary, and how much to explain. Without it, different AIs write for different audiences and the document becomes inconsistent.	IT Director and VP of Facilities is better than business audience. Specify seniority, technical level, and any split audience.
Desired outcome	Gives the AIs a finish line. The most impactful field — this is what every suggestion and every rewrite is ultimately working toward.	Approve the budget, schedule an interview, understand the three options and pick one. Vague here means vague everywhere.
Scope & constraints	Draws the fence. AIs expand into adjacent topics unless you stop them explicitly.	Cover both sides — what must be included and what must not. Wireless only — no switching, routing, or security products.
Tone & voice	Prevents tone drift across rounds when multiple AIs are writing in different styles.	A few adjectives is a floor. Richer is better: Direct and confident, not stiff — like a peer they'd want to work with. Say what to sound like, what to avoid, and who's reading.
Additional instructions	Hard rules that must survive every round — things the AIs must always or never do regardless of what the document looks like.	Do not add new sections. Never change the numbers in the cost table. Always use Oxford commas. For one-round-only instructions, use the Notes drawer on the Work screen instead.

Below the goal fields are two clear buttons:

• ✕ Clear Goal — erases all six goal fields. Your project name, version, and all other settings are kept.
• 🗑 Clear Project — erases everything on the Your Project screen: name, version, all goal fields, and length constraint. Your API keys and Builder selection are not affected.

↑ Back to top

After continuing from the Your Project screen, you arrive at Setup 4: Reference Material. This is a full-width screen with a small ⓘ info button next to the heading. Reference material is optional — most projects do not need it. The Continue button is always active and you can skip the screen entirely if your project has no source material to cite against.

This screen is where you provide source documentation that the hive should consult on every round but never edit. The hive sees this content alongside your starting document, but the prompt explicitly tells every reviewer and the Builder to treat it as read-only authoritative source — not as something to rewrite.

Reference material is the right tool when there is a specific document the hive needs to cross-check against. Common cases:

• RFP responses — paste the RFP itself so the hive can verify your response addresses every required section, scoring criterion, and constraint.
• Cover letters and résumés — paste the job description so every revision is checked against the actual role requirements, not a generic idea of the job.
• Brand or style guides — paste your organization's style rules so the hive enforces them on every round without needing you to repeat them in Notes.
• Scoring rubrics — paste a grading rubric or evaluation criteria so the hive can self-score against it as it refines.
• Prior decisions or vendor claims — paste the agreed positions, technical specifications, or contractual claims you must stay consistent with.

Most short documents do not need reference material. A cookie recipe, a thank-you note, a personal blog post, or a quick email rarely has external source material to cite against. If you cannot name what the hive would be checking against, leave Setup 4 empty and continue.

Three places hold instructions or content for the hive. They are distinct, and using the wrong one is a common cause of confusion.

Field	Role	How the hive treats it
Project Goal (Setup 3)	Standing target — what you are trying to produce	Sent every round, never changes within a session
Reference Material (Setup 4)	Standing source material — what the document must cite against	Sent every round, can be edited mid-session, never edited by the hive
Starting Document (Setup 5)	The document under construction	Line-numbered, reviewed, rewritten by the Builder each round
Notes (Work screen)	Round-to-round directives for the Builder only	Sent on the next round only; cleared automatically after that round runs

Setup 4 is built around a list of reference document cards. You can add as many as you need — RFP requirements alongside scoring rubrics, style guides alongside brand voice references, prior decisions alongside vendor claims. Each card is independently named, ordered, removable, and editable. The hive sees them in array order with labeled section headers in the prompt envelope so AIs can cite specific documents by name.

Two action panels above the reference list let you add new ones:

• Paste Text — clicking this panel (it has a clipboard icon) adds a new editable reference with an empty textarea below. Paste your text in and it becomes the reference's content. The reference name defaults to Reference N — rename it to something meaningful (e.g. RFP Requirements, Style Guide, Job Description) so the hive can cite it by name.
• Upload File — clicking this panel (it has a stack-of-document-types icon) opens a file picker, or you can drag & drop a file directly onto it (the panel is the drop target). The file is read once and its content is loaded into a new read-only reference with the original filename as the name. Supported formats: Word (.docx), PDF (.pdf), PowerPoint (.pptx), Excel (.xlsx, .xlsm), plain text (.txt), and Markdown (.md). For Excel workbooks with multiple visible sheets, a sheet picker appears and each selected sheet becomes its own independent reference. For the canonical breakdown of what gets extracted from each format and what does not, see File Ingestion ↓.

Each card has the same controls: a position number badge at the top-left (the hive reads cards in the order shown, top-down), a source-icon badge (showing which file type the content came from — DOCX, PDF, paste, etc.), a character / word / token counter, ▲ and ▼ arrow buttons to reorder, and a ✕ remove button. Paste cards have a fully editable textarea below the header row; upload cards are read-only — to replace an uploaded card's content, remove it and re-upload.

A soft warning banner appears at the top of Setup 4 if the total token count across all cards exceeds approximately 150,000. Most provider context windows in 2026 are 100k–1M tokens; the threshold is conservative and informational — it never blocks, just flags genuinely heavy use so you can split across rounds, remove low-priority documents, or switch to a long-context Builder before launching.

Below the input area is a live counter showing characters, words, and an estimated token count. The token estimate uses the rule of thumb characters ÷ 4, which is the standard approximation for English text in OpenAI-family tokenizers. Real tokenizers vary by model, language, and content type — treat the number as an order-of-magnitude estimate, not a precise count. The ⓘ button next to the token count opens a brief explainer with more detail.

Reference material is sent to every reviewer every round. A 5,000-character RFP is roughly 1,250 tokens per request. A six-bee hive running four rounds is 30,000 tokens spent just transmitting the reference material — before any document content, project goal, or response is counted.

Two consequences follow:

• Trim aggressively. Paste only what is most important. If a 40-page RFP has three pages of substantive requirements and 37 pages of boilerplate, paste the three pages.
• Pick a cost-conscious Builder. When reference material is large, switch your Builder to a model with low input-token pricing — DeepSeek and Gemini Flash are typically the cheapest options. The Builder is sent the largest prompt every round, so changing it has the biggest cost impact.

For the full breakdown of how tokens are priced and why per-round costs scale the way they do, see the What Are Tokens? ↗ guide.

Once you launch a session, the Work screen toolbar shows a new 📚 Reference button between Notes and Finish. Clicking it opens a drawer that slides up from the bottom of the screen, showing the current reference material in an editable textarea with the same character / word / token counter.

Edits saved from this drawer apply to the next round — past rounds keep the snapshot of the reference material that was active when they ran. This is intentional: each entry in Round History stores the reference material as it existed at the moment that round was generated, so the transcript stays internally consistent even if you change the source material between rounds.

The drawer has three actions: 📋 Copy (copies the current text to your clipboard), ✕ Clear (wipes the field with confirmation — does not affect past rounds), and 💾 Save & Close (commits the edit and closes the drawer).

↑ Back to top

After continuing from the Your Project screen, you arrive at Setup 5: Starting Document. This is a full-width screen with a small ⓘ info button next to the heading. This is where you tell WaxFrame what to work with. There are three ways to provide a starting point, selected using the three buttons at the top of the screen.

Important: These three buttons — Upload File, Paste Text, and Start from Scratch — are mode selectors, not action buttons. Each carries a small distinct icon to its left (a stack of file-type cards for Upload, a clipboard for Paste, a blank-page-with-sparkles for Scratch). Clicking one selects that mode and changes what appears below the buttons. You then interact with the area below them to actually provide your content. A brief instruction line directly below the buttons updates to tell you exactly what to do next.

Below the mode selector buttons and above the content area is a row labelled 💾 Export filename. This field controls what your downloaded document file will be named when you export it at the end of your session. It uses two tokens:

• {name} — replaced with your project name, with spaces and special characters converted to underscores.
• {version} — replaced with your version number.

The default value is {name}_{version}, which produces a filename like Q3_Executive_Summary_v1.txt. You can customise this — for example {name}_FINAL_{version} — or leave it as the default. A live preview of the resulting filename appears to the right of the field as you type, using your actual project name and version. Click the small ⓘ button next to the label for a full explanation of available tokens.

Click Upload File to select Upload mode. A drop zone appears below — a dashed bordered area with the text Drag & drop or click to browse. To upload your file:

• Click anywhere inside the drop zone to open your operating system's file browser. Navigate to your file and select it.
• Or drag your file from any folder on your computer and drop it directly onto the drop zone.

Supported file formats: Word documents (.docx), PDFs (.pdf), PowerPoint presentations (.pptx), Excel workbooks (.xlsx, .xlsm), plain text files (.txt), and Markdown files (.md). WaxFrame extracts the text content from the file and loads it into the working document automatically. A confirmation message appears below the drop zone once the file is processed successfully, showing the filename and word count. For Excel workbooks with multiple visible sheets, a sheet picker appears and selected sheets are concatenated into a single document with ## Sheet: dividers. For the canonical breakdown of what gets extracted from each format and what does not, see File Ingestion — What Gets Extracted ↓.

Click Paste Text to select Paste mode. A text editor appears below the buttons — the same line-numbered editor used on the Work screen. Click anywhere inside the editor to place your cursor, then paste your text using Ctrl+V on Windows or Cmd+V on Mac. You can also type directly into the editor.

Use this option when your content comes from a website, an email, a Google Doc, another application, or any source where you can copy and paste text but do not have or do not want to use a file. There is no size limit on pasted text other than your Builder's token capacity.

The editor uses a fixed 80-character-wide column — the same width as the working document on the Work screen. This is intentional and ensures consistent formatting throughout your session.

Click Start from Scratch to select Scratch mode. A confirmation panel appears indicating that WaxFrame will generate the first draft entirely from your project goal. There is nothing else to do in this panel — no file to upload, no text to paste.

In this mode, your project goal is the only context the AIs have. Write it in as much detail as possible before launching. The more specific and complete your goal, the closer the first draft will be to what you actually need.

The small ⓘ button next to the Starting Document heading opens an overlay that explains the three mode buttons and what to do after selecting each one — a quick in-app reference to this section of the manual.

↑ Back to top

At the bottom of each setup screen is a requirements bar showing exactly what is still needed before you can continue or launch. On the Starting Document screen it reads: To launch you need: followed by one indicator:

• ✗ Document — upload a file, paste text, or choose Start from Scratch — turns green ✓ when a starting document mode is selected and, for Upload and Paste modes, content has been provided.

On the Your Project screen the requirements are: Project name, Version, Document type, Target audience, and Desired outcome — all five must be filled before you can continue to the Starting Document screen.

The Launch WaxFrame → button at the bottom right of the Starting Document screen is inactive until the document requirement is green. Once it is, click Launch WaxFrame → to move to the Work screen and begin your session. WaxFrame saves your project configuration automatically at this point.

↑ Back to top

The Work screen is where all rounds happen. It has a top bar, a three-column main area (left panel · Working Document · right panel), and a footer bar at the bottom. Most of the screen's controls are clustered into those four zones. Here is what each contains, top to bottom and left to right.

Running across the very top of the Work screen, three zones — left, centre, right:

Top bar — left zone

Top bar — centre zone

Top bar — right zone (left to right):

Round History is reachable via the Menu (top-left) — covered in detail in Step 10.

The left column contains two sections stacked vertically: The Hive at the top and Conflicts below it.

The Hive section has a small ⓘ info button and two buttons in its header:

Below the header, the AI status area displays differently depending on your screen size:

Below the AI status area is the Conflicts section, also in the left column:

The centre column is headed 📄 Working Document with a small ⓘ info button. This is where your document lives and is updated after each round.

The right column contains three elements stacked vertically: the WaxFrame logo and version stamp, the dual-face clock widget, and the Live Console.

At the very bottom of the Work screen is the footer bar. Three zones — left status, centre actions, right indicators.

Footer — left zone

Footer — centre zone (the two big round-trigger buttons)

Footer — right zone (indicators and info, left to right)

↑ Back to top

Click the Smoke the Hive button in the footer bar to start a round. All your active reviewer AIs begin processing simultaneously — having more AIs does not make the round take longer, since they all run at the same time. You can watch each AI's progress in the Hive panel on the left — each icon animates as its AI works.

Do not close the browser tab or navigate away while a round is running. If the round is interrupted, the document will not be updated and the round will not be saved to history, though your API call tokens will still have been consumed.

1. 1WaxFrame sends each reviewer AI a prompt containing your goal, the current document, and instructions for their role. All reviewer AIs receive the same prompt simultaneously.
2. 2Each reviewer AI returns a numbered list of specific suggestions. You can see these in the Live Console as they arrive, and in the Conflicts section of the left column after the round.
3. 3Once all reviewers complete, WaxFrame sends the Builder AI a prompt containing the current document, all reviewer suggestions, and your goal. The Builder incorporates the strongest suggestions and produces an updated document.
4. 4The updated document appears in the Working Document panel. Any significant disagreements between your AIs are flagged as conflicts in the left column for your decision. The round is saved to history automatically.

WaxFrame decides how to use your goal based on one simple question: does a document exist? You do not choose or configure this — it is handled automatically.

↑ Back to top

After a round completes, the centre column shows the updated document. Read it carefully before running another round. Each version is saved automatically to the Round History — open the Menu and click 📖 Round History to access any previous version and restore it if needed.

A conflict appears in the left column when your AIs gave the Builder genuinely incompatible suggestions — recommendations that point in different directions strongly enough that the Builder flagged the decision for you rather than choosing arbitrarily. Common scenarios: one AI suggested removing a section while another suggested expanding it; reviewers proposed different conclusions; AIs disagreed on tone, phrasing, or structure for a key passage.

Conflicts are not a sign something went wrong. They are a signal that your AIs found a real decision point — one that genuinely depends on your intent and cannot be resolved by the AI alone. When you see conflicts, the hive is working correctly.

Each conflict card shows:

• The original text in dispute, labelled Current: — click this text to jump directly to that passage in the Working Document. Essential on long documents.
• Two or more options proposed by your AIs, each clearly labelled
• A Custom option where you type your own resolution
• A Keep Original option to leave that passage unchanged

Read the current text in context, read each option, and click the one that best matches your intent. Once you have selected every conflict, click Apply Decisions to update the document. Resolved conflicts are locked — WaxFrame tells the Builder about your decisions in future rounds and instructs it not to re-raise them.

This happens. Some AIs — particularly those running under a proxy or enterprise gateway — do not consistently carry resolution instructions into the next round. The conflict card disappears, but the next round produces the same issue. Here is what to do, in order:

Step 1 — Reinforce it in Notes. Before the next round, open the Notes drawer and write the resolution explicitly. Do not paraphrase — quote the exact text you want locked:

"This line is final and must not be changed under any circumstances: "The recommended solution is a cloud-managed architecture." Do not re-raise this as a conflict. Do not offer alternatives."

The Notes drawer has a 🔒 Lock a line template button that pre-fills this format for you. Paste the exact text into the placeholder and run the round.

Step 2 — Add it to your Project Goal. If the same issue returns after two rounds of Notes reinforcement, it means the AI is not reading the resolution at all — it needs the instruction in the permanent brief. Open the Project screen via the Menu, add the constraint to Additional instructions, and return to the Work screen. The goal is sent every round; Notes are cleared after each round.

Step 3 — Remove the offending AI. If one specific AI keeps re-raising a resolved conflict after both Notes and goal reinforcement, it is not reading your instructions. Use Edit Hive (laptop) or toggle its card directly (desktop) to remove it from the session. The hive will converge faster without it.

No conflicts does not always mean convergence — it can mean the AIs are making changes that do not produce disagreement, or that the Builder is silently overriding suggestions. If the document is drifting in a direction you do not want but no conflicts are flagged, use Notes to give the Builder explicit direction: what to fix, what to leave alone, and what the next round must accomplish. Then run the round and check the console to see which AIs responded and what they said.

Rather than treating conflicts as a problem to dismiss quickly, use them as a tool. They surface real decisions about the document's direction — questions about emphasis, tone, structure, or argument that you will need to answer to get the document where you want it. Each resolution tells the entire hive which direction to take. A well-resolved conflict round is often the most productive round in a session.

↑ Back to top

After your first round, the process repeats: click Smoke the Hive, wait for the round to complete, read the updated document, resolve any conflicts, make any direct edits you want, and decide whether to run another round. Most documents reach a high quality in three to five rounds. Some need more; some need fewer. The right time to stop is when the document reads the way you want it to.

Every reviewer is constrained to its top three most impactful suggestions per round. This keeps responses focused and prevents long lists of trivial nitpicks. On a small document this is plenty of coverage. On a long or complex document, six reviewers picking three issues each only adds up to eighteen specific spots — and they do not always pick the same spots.

The practical effect: one round may concentrate every reviewer on the opening section, the next round may scatter them across the middle, and a third round may surface things in the conclusion that nobody flagged before. A round can complete with zero conflicts not because the document is finished, but because the reviewers happened to focus on different parts and none of their suggestions overlapped enough to disagree about.

This is how prioritised review works, not a bug. The real "done" signal is not "no conflicts in the last round" — it is a round where every reviewer responds with NO CHANGES NEEDED. Until you reach that, keep running rounds. On a big document, expect to run more rounds than you would on a small one, and expect the focus to move around between them. That is the system covering ground three issues at a time.

Click 📝 Notes in the top bar to open the Notes drawer. This is where you write direct instructions for the Builder for the next round only. Notes are not sent to reviewers — only the Builder receives them. They are cleared automatically after each round so they do not carry over unintentionally.

Use Notes when you want something specific to happen in the next round that your goal alone would not produce — a targeted fix, a section to protect, a direction to push toward.

The Notes drawer has a row of template buttons that pre-fill common instructions for you. Click one and the textarea fills with a ready-made instruction — the placeholder text is automatically selected so you can type your replacement immediately.

Notes work best when they are specific and direct. The Builder reads them as instruction, not suggestion.

Situation	What to write in Notes
Tighten a section	"The executive summary is too long. Rewrite it so it is no more than three sentences."
Remove something specific	"Remove the third paragraph in the Cost section — it repeats what was already said in paragraph one."
Strengthen a weak part	"The conclusion is weak and non-committal. Rewrite it to be decisive and action-oriented."
Lock a line	"This line is final — do not change it: "The recommended solution is a cloud-managed architecture.""
Lock a section	"Do not change anything in the Technical Specifications section. The section begins with: "The proposed system consists of…""
Block new content	"Do not add any new sections or headings. Work only with the existing structure."
After reverting the document	"I have reverted the document to a previous version. Ignore any changes from the previous round and work from what is here now."

If the Builder or reviewers keep modifying a line you need to preserve — a specific metric, a name, a legal phrase, a date — quote the exact text in your Notes instruction. Do not paraphrase it. The Builder pattern-matches against what it sees in the document and needs the exact wording to recognise what you are protecting.

Use the 🔒 Lock a line template button in the Notes drawer. It pre-fills:

"Lock this line exactly as written — do not change it: "[PASTE THE EXACT LINE HERE]""

Replace the placeholder with the exact text from your document — copy and paste it directly. Then run the round. If the issue persists after two rounds of this, add the same instruction to your Additional instructions goal field so it is sent permanently, not just for one round.

The Working Document editor is fully editable at any time between rounds. If you can see exactly what needs to change — remove a paragraph, fix a factual error, rewrite a heading — just do it directly. The AIs will work with whatever is in the editor when the next round starts. If you remove something intentionally and want to make sure the AIs do not reintroduce it, add a Note: "I have removed [X] — do not reintroduce it."

On desktop screens, toggle individual AIs directly on their cards in the Hive panel. On laptop screens, click Edit Hive in the Hive header to open the toggle modal. Click Change Builder to switch which AI is doing the writing. Neither action requires going back to Setup or losing your current session. Both take effect on the next round you run.

When you have made direct edits to the document and want the Builder to integrate and clean them up — without running a full reviewer cycle — click Send to Builder in the footer bar instead of Smoke the Hive. The Builder rewrites the document based on your current version and your Notes (if any), but the reviewers do not run. This saves time and tokens when you already know what direction to take and just need the Builder to execute it cleanly.

Watch for these signals that the document is ready:

• Your AIs are agreeing more than they are disagreeing — conflicts are rare or minor.
• Conflicts are about word choices rather than structural or argument issues.
• You are accepting most suggestions without hesitation.
• Reading the document feels like reading a finished piece, not a draft.

Running more rounds past this point produces diminishing returns. When the document reads the way you want it to, stop and export.

↑ Back to top

Click the 🏁 Finish button in the top right of the Work screen to open the Finish panel. A modal dialog appears titled 🏁 Project Complete! with three buttons and two secondary options at the bottom.

↑ Back to top

The goal fields on Setup 3 aren't optional decoration. Reviewers can only judge whether a document fits the goal if the goal is clearly stated, and the more specifically you state it, the faster the hive converges.

A curated set of measured runs that illustrate patterns. Full data lives in docs/WaxFrame_Playbook_Test_Master.txt. The point of these isn't completeness — it's to show how setup specificity, hive size, and scaffold quality drive convergence rounds.

• Job Description (Altura test): specific company name, role, seniority, and reporting structure filled into the structured goal fields — 20–22 rounds convergence on a complex multi-page document.
• Résumé (Dana Reyes test): specific candidate background and target industry filled at setup, with mid-stream notes injection added between Round 2 and 3 — 10–12 rounds convergence.
• Business Proposal (Brightwater Canoe and Kayak): v3.0 scaffold, 3-AI hive on a from-scratch run with a fully-populated identity scaffold in Scope & constraints — 5 rounds, ≈10 minutes. Earlier v2.0 scaffold with a 2-AI hive: 11 rounds, ≈16 minutes (extra rounds came from a tied USER DECISION block at Round 5 that halted Auto Mode for manual selection). The third reviewer is what breaks decision ties automatically. For reference, the original v1.0 scaffold with a 3-AI hive converged faster (3 rounds, ≈8 minutes) because the scaffold had fewer constraints to satisfy; v3.0 is the polished version reflected in the in-app Business Proposal template today.
• LinkedIn Post (DFS in defense): 3-AI hive on a sharply-scoped social post with a clear opinion in the Tone field — 2 rounds, ≈1 minute. Posted to live LinkedIn. A vaguer prompt on the same category previously took 5 rounds; setup specificity is the difference.
• LinkedIn About profile (wireless engineer): 3-AI hive with a 1,163-character identity scaffold pasted into Reference Material plus a Round 1 buzzword guard in Notes — 2 rounds. The Reference Material did most of the work; the buzzword guard kept the draft clean from Round 1.
• Thank-You Letter (from scratch vs refining a draft): same final document type, same hive, same goal fields. Starting from scratch with empty starting document → 2 rounds. Refining a misaligned draft → 13 rounds. The misaligned draft cost 6× more rounds.

Three patterns repeat across these runs.

1. Setup specificity drives convergence. The structured goal fields — audience, outcome, scope, tone — pay back as rounds you don't have to run. The minutes you spend on the Project screen save you minutes on the work screen, and usually more than break even.

2. Three or more AIs converges faster than two. When two reviewers disagree on a specific change, the run pauses and asks you to break the tie; with three or more reviewers, disagreements resolve automatically by majority and the run keeps moving. The cost is one more reviewer per round; the win is fewer interruptions and noticeably faster wall-clock — the Brightwater data above is the clearest example.

3. Reference Material is high-leverage. When the hive needs a body of facts to draw from (an identity scaffold, a job description, a research brief, a source recipe), pasting that into Setup 4 — Reference Material delivers more value per character than expanding the goal fields. The hive pulls from it on every round; you only have to type it once. Demonstrated in the Recipe (Publix-style Southern potato salad) test: a 2,636-character reference recipe paired with an empty Starting Document and a fully-populated Project scaffold converged in 4 rounds, well below the 5–20+ range estimated for traditional recipe refinement. When the source recipe instead sits in the Starting Document, the hive treats it as a draft to fight; when it's in Reference Material, the hive builds fresh from the scaffold. Same source content, very different convergence shape.

If your hive is struggling to converge after Round 3 or 4, open the Project screen and read your goal fields aloud — would a reviewer know what success looks like from those words alone? If not, expand them. Then check whether you should be using Reference Material instead of cramming everything into Scope.

↑ Back to top

When a starting document is misaligned with the goal you've defined, the hive can spend many rounds dragging it toward what was actually wanted. Sometimes the faster path is to discard the draft entirely and let the hive build from scratch using only the goal fields.

A Thank-You note converged in 2 rounds when started from scratch (Start from Scratch button on Setup 5, empty starting document) versus 13 rounds when refining a rough draft pulled from a pre-existing template. Same final document type, same hive, same goal fields. The only variable was whether the run started with a 0-character document or a misaligned draft. The misaligned draft cost roughly 6× more rounds.

This isn't a universal rule. When your starting draft is already well-aligned with the goal — your existing résumé that just needs polish, an article draft you're happy with the bones of — refining is faster than starting over. The decision point: does the starting document already reflect the goal, or is it a different goal that needs reshaping? If the latter, scratch usually wins.

↑ Back to top

The Builder does heavier synthesis work than reviewers — it accepts, rejects, and integrates change proposals across the hive every round, and the reviewers then judge its output. The Builder is also usually a reviewer itself, which means its synthesis style is being judged against its own preferences as well as the other reviewers'.

A Builder mismatched to the document type tends to invite more reviewer dissent, which extends convergence. We don't yet have systematic measured data comparing specific Builders across document types — as more runs are measured, this section will be updated with concrete recommendations.

If you've run two or three rounds where reviewers keep flagging the same kinds of issues, and the Builder's output keeps drifting away from the goal in a consistent direction, try changing the Builder on the Worker Bees screen and re-run. The hive's convergence behavior often shifts immediately when the Builder is better matched.

↑ Back to top

The six default AIs (ChatGPT, Claude, Gemini, Grok, Perplexity, DeepSeek) cover the most widely-used public AI providers. Use Add Custom AI when you want to connect an AI that is not in that default list — for example, Mistral, Together AI, Cohere, Ollama running locally on your machine, LM Studio, or any other AI service that exposes an API endpoint accepting chat completion requests in OpenAI-compatible, Anthropic, or Google format.

To open the form: go to the Setup screen and click Add Custom AI in the toolbar above the Worker Bees list.

After entering your URL and API key, click Fetch Models. WaxFrame sends a request to the provider's models endpoint and retrieves the list of available models. A dropdown appears below the Model field showing all available models — click the one you want to use. This is significantly more reliable than typing a model ID manually and eliminates the risk of typo errors.

Click Test Connection before adding the AI. WaxFrame sends a minimal test message to the endpoint and opens a result panel showing the exact endpoint used, the full JSON body sent, the HTTP status code and response time, and the complete raw JSON response received. A passing test shows a green success message. A failing test shows a red error with a plain-English explanation:

• 401 / 403 — bad or missing API key
• 404 — wrong endpoint URL or path
• 405 — method not allowed — the endpoint may not support chat completions at this path
• 429 — rate limited — wait a moment and try again
• Network Error — the endpoint is unreachable, or a CORS policy is blocking the request from a local file origin (CORS — Cross-Origin Resource Sharing — is the browser security check that decides whether one origin is allowed to call another; see the CORS troubleshooting block below)

↑ Back to top

If you have a local or enterprise AI server running — such as Open WebUI, Ollama, or LM Studio — and it hosts multiple models, Import from Model Server lets you fetch the complete list of models from that server and add several AIs to your hive at once, instead of adding them one by one using the Add Custom AI form. To open the form: go to the Setup screen and click Import from Model Server in the toolbar.

The Import from Model Server form is a single-screen workflow laid out in three columns: inputs on the left, context in the middle, and the model list on the right. At laptop viewport widths the middle and right columns merge into one region that shows the right content for the current state, so you always see what matters most.

1. 1Fill in the Chat Endpoint, Models Endpoint, and API Key fields on the left (or use Quick Add to pre-fill them). When the form is empty, a What you'll need guide is shown to explain each field.
2. 2Click Fetch Models. WaxFrame queries your Models Endpoint and retrieves the full list of available models. On success, the model checklist appears on the right and a 📋 View raw response button appears under the Fetch button so you can inspect the server response if you want. The header of the checklist shows a live Fetched Xs ago timestamp so you always know how fresh the list is.
3. 3Review the checklist on the right. Models that are already in your hive from this same server are filtered out of the list — the purpose of this screen is "what can I add?", not "what do I already have?". The header shows how many were filtered out, for example 29 available · 0 selected · 8 already in hive. To remove a model from your hive, use the delete button next to it on the Worker Bees setup page.
4. 4Adjust the checklist as needed. All available models are checked by default. Use All or None at the top of the list to toggle everything. Edit any model's display name in the text field beside its ID.
5. 5Click Add N to Hive in the footer. WaxFrame adds each selected model as a separate AI in your Worker Bees list, using the Chat Endpoint you provided and the model ID for each one. The server config is saved for next time.

↑ Back to top

Many organisations run their own AI infrastructure — platforms like Open WebUI connected to internally hosted models, or enterprise subscriptions to OpenAI or Anthropic with private endpoints and access controls. WaxFrame connects to these through the Add Custom AI form (Appendix A) or Import from Model Server (Appendix B), provided the platform exposes an API endpoint that accepts chat completion requests.

What you need	What to ask for
API endpoint URL	"What is the chat completions API endpoint URL for our AI platform, including the full path?"
Authentication method	"How do I authenticate API requests — is it a bearer token, an API key in a header, or something else?"
Model name	"What is the exact model ID string I should use in API calls?"
API format	"Is the API OpenAI-compatible?" (The answer is almost always yes for enterprise platforms.)
CORS policy	"Does the API allow requests from file:// origins, or does it need to be accessed from a web server?"

If your organisation uses only internal AI models and you do not want the six default public AIs (ChatGPT, Claude, etc.) visible in your list, flip the 🖥 Server Based AI toggle at the top of Setup 1 — Worker Bees. This hides the six defaults and any direct-API customs from view (their saved keys are preserved — they reappear if you switch back to Internet mode) and shows only AIs imported from a model server. You can then click Import from Model Server in the toolbar to fetch the models available from your gateway (Open WebUI, Ollama, LM Studio, an internal endpoint like Anduril's Alfredo, or any other OpenAI-compatible server) and add several at once. See Appendix B — Importing from a Model Server for the full walkthrough.

Internal AI servers — Open WebUI, LM Studio, on-prem deployments serving multiple models — are common in defense, healthcare, financial, and other secure-network environments. They behave differently from the public-AI hives you'd run at home.

The substrate matters. A typical internal AI server hosts whatever models the deployment has been configured to serve. Those models can have knowledge cutoffs months apart, sometimes years apart. Two AIs in the same hive may have been trained against entirely different snapshots of reality.

What this means in practice:

• For a factually-anchored document (a technical paper, a current-events post, a vendor comparison), one AI may know information the others don't. The hive can't fact-check itself on knowledge it doesn't share.
• For an opinion-or-style-driven document (a personal observation, an essay, a stylistic refinement), cutoff variance matters much less because the content doesn't depend on shared current knowledge.
• Possible failure modes on factual content: non-convergence (one AI insists on a fact the others won't accept), or false convergence (every AI hallucinates plausible-sounding filler that drifts apart on subsequent rounds).

The hive's output quality is bounded by the substrate it runs on. This is not a defect in WaxFrame — it's a property of the underlying models you're orchestrating.

When you need to run factually-anchored work on an internal AI server, three approaches help:

1. 1Inject a shared baseline via Setup 4 (Reference Material). Reference Material is shown to every AI every round as authoritative context. Cutoffs stop mattering for facts that live in the reference document — every AI works from the same source of truth. Use this for any current-events, technical, or fact-heavy run on an internal server.
2. 2Keep the hive small. Three or four AIs from the same model family (the most recent three of one vendor on the server) tends to give better consistency than mixing six AIs across vendors and ages. The variance you fight is roughly proportional to the spread.
3. 3Use a public-AI hive at home as a control before blaming WaxFrame. If a run won't converge on your work server and you're not sure why, run the same project setup at home on a public-AI hive (ChatGPT, Claude.ai, Gemini, all current). If it converges there but not at work, the substrate is the variable. If it fails to converge in both, the goal fields or starting document likely need work.

A 6-AI hive on a corporate internal AI server, refining a 16,214-character research report into a 300-word LinkedIn post, converged via the engine's majority path (4 of 6 AIs satisfied) in 5 rounds and 7 minutes.

Setting	Value
Document type	LinkedIn Post
Target audience	Fellow Wi-Fi nerds and friends from various life stages
Tone	A specific voice description (one full sentence)
Length limit	300 words
Starting document	16,214 characters (a research report on the topic)
Hive	6 AIs across three vendor families
Builder	One of the reviewers, doubling as Builder
Result	Engine-triggered majority convergence (4 of 6) at Round 5, 7 minutes total

The run shows that internal AI servers can converge cleanly on heavy compression tasks (an 80× length reduction in this case) when the goal fields are filled specifically. This single run does not prove that goal-field specificity caused the convergence — only that the run had these properties and converged via the engine's normal majority path. As more runs are measured systematically, this guide will be updated with broader patterns.

WaxFrame opens as a local HTML file in your browser. Some internal AI servers block requests from file:// origins as a CORS policy — this is a security measure that prevents arbitrary web pages from connecting to internal servers. If you see a Network Error or CORS error when testing a connection, you have two options:

• Ask your IT team to add file:// to the allowed origins on the AI server's CORS configuration.
• Serve WaxFrame from a simple local web server. On most machines this can be done by opening a terminal in the WaxFrame folder and running python -m http.server 8080, then opening http://localhost:8080 in your browser instead of the file directly. Requests from localhost are typically allowed by internal servers.

↑ Back to top

Format	Extensions	What it is good for
Word	.docx	Most documents that originated in Word — proposals, reports, letters, templates, résumés.
PDF	.pdf	Anything you cannot get back to its original source — published reports, downloaded specs, scanned documents.
PowerPoint	.pptx	Slide decks, especially when the substance lives in speaker notes rather than on-slide bullets.
Excel	.xlsx, .xlsm	Tabular data — pricing sheets, requirement matrices, scoring rubrics, comparison tables.
Plain text	.txt	Already-clean text from any source.
Markdown	.md	Already-clean structured text. Markdown formatting is preserved as-is.

Preserved: Heading hierarchy rendered as markdown headings, bullet and numbered lists, tables, bold and italic emphasis, comments rendered as a Comments section with author and text, footnotes and endnotes (numbered), headers and footers (deduplicated so boilerplate appears once), text boxes (Word's native text-box content that other importers silently drop), and tracked-change accepted text — insertions are kept, deletions are dropped.

Not preserved: Embedded images, charts, exact fonts and styling, page break locations, drop caps, watermarks. The text and structure survive; the visual layout does not.

Native text PDFs: Position-aware text extraction with detected tables converted to markdown, plus the document outline (TOC) when present, AcroForm form-field values when filled, and annotation comments and highlights inlined as [Note on page N: contents] markers at the page where they appear. Table detection is heuristic — works well for clean grid-aligned tables, may miss heavily-styled tables or those with merged-cell headers.

Scanned or image-only PDFs: Routed automatically to AI vision transcription using the first vision-capable AI in your hive (ChatGPT, Claude, Gemini, or Grok). The result appears as the working document with a warning to verify accuracy. If no vision-capable AI key is configured, the importer returns whatever text it could extract along with a warning.

Mixed PDFs (mostly text with sparse pages): Pages with very little extractable text in an otherwise text-rich document trigger a heuristic OCR pass. The sparse pages are rendered to images and OCR'd via your vision-capable AI. The OCR output is appended as a separate section so the original text is preserved alongside it. This catches the common "screenshot of a table embedded in an otherwise text PDF" case that previously dropped silently.

Re-extract on demand: If the initial extraction for a PDF looks garbled or wrong, the work screen shows a banner offering to re-extract using AI vision. This re-runs the full-document vision transcription regardless of the original detection.

Preserved: Slide order, slide titles separated from body content (each slide becomes ## Slide N: Title), bullet content on each slide, speaker notes (rendered as **Speaker notes:** directly under each slide), embedded tables converted to markdown, SmartArt diagram text, and chart titles, category labels, and series names.

Not preserved: Slide layouts and themes, animations and transitions, embedded images, chart visualizations themselves (only the labels survive), per-element positioning. Decks that rely heavily on visual composition rather than text content will lose most of their meaning — paste the key takeaways manually if that is what matters.

Note on speaker notes: The importer maps notes to slides by filename (notesSlide1.xml ↔ slide1.xml). For typical decks this works correctly. For decks rebuilt from templates with non-default note ordering, notes may appear under the wrong slide — rare but worth knowing about.

Workbooks with two or more visible sheets show a sheet picker modal on import. Pick which sheets to ingest. The picker shows the cell count and an estimated token count for each sheet so you can make informed selections. Single-sheet workbooks ingest directly with no modal.

Setup 4 (Reference Material): Each selected sheet becomes its own independent reference card with its own name, token chip, and reorder controls. Leverages the multi-document support added in v3.24.0.

Setup 5 (Starting Document): Selected sheets are concatenated into a single document with ## Sheet: H2 dividers between them. If you only want one sheet, uncheck the others in the picker.

Per-sheet conversion: Cell values are extracted with formulas evaluated to their displayed values — a cell showing $1,250.00 from a SUM formula appears as $1,250.00 in the output, not the raw number or the formula text. Merged cells are flattened by repeating the top-left value across the merged span. Cell comments are captured in a per-sheet **Cell notes:** footer. Workbook-level defined names are surfaced as a glossary header. Sheets with more than 15 columns prepend a warning that markdown table comprehension by AIs may degrade past that width — there is no hard cap.

Not preserved: Cell colors and conditional formatting, chart visualizations and embedded images, pivot table source data (cached display values are shown for pivots), macros (not run), hidden sheets (skipped — count surfaced via warning).

Read directly into the working document or reference card with no transformation. Markdown formatting is preserved as-is — most reviewers handle markdown structure naturally and will respect heading hierarchy, lists, and emphasis when reasoning about the document.

Vision OCR runs automatically when the standard text extraction yields garbled or near-empty output (scanned PDFs, image-only PDFs, or PDFs with sparse-text pages where embedded screenshots dominate). It uses the first vision-capable AI from your hive in this priority order: ChatGPT, Claude, Gemini, Grok. If none of those four providers have a key configured, the importer skips the OCR step and returns whatever text it could extract along with a warning suggesting which keys to add.

OCR runs add latency — typically 15–30 seconds for a short document, longer for many pages. They also add cost (a vision API call per page or batch of pages). The importer is conservative about firing OCR — it only does so when the standard extraction quality is genuinely poor.

The importer is best-effort. For documents where exact wording matters — a legal contract, a regulatory specification, a customer email you must respond to verbatim — paste the text manually rather than relying on extraction. Two clicks of copy/paste from the source application will always be more accurate than any importer because there is no extraction step at all.

For documents where structure and bulk content matter more than exact wording — research papers, long reports, drafts you want feedback on, RFP requirements you want the hive to cite against — the importer is more than good enough. Spot-check the result if you have any doubt about a critical passage.

All four ingestion libraries (PDF.js, Mammoth, JSZip, SheetJS) ship inside the WaxFrame source tree at /lib/. There is no CDN reach-back at runtime — the page works end-to-end on networks that block external fetches. This is the recommended configuration for defense, healthcare, financial, and other secure environments. Total library footprint is approximately 3.1 MB added to first-load.

Situation	What to do
Tone is wrong throughout	Open Notes before the next round and write explicitly: "The tone throughout the entire document must be [formal / conversational / technical / plain-English]. Rewrite any passages that do not match this." Be specific about what you want.
AIs keep adding content you do not want	Edit your project goal to explicitly exclude it. Add a Note reinforcing the exclusion. If one specific AI keeps doing it, use Edit Hive (laptop) or toggle the AI card directly (desktop) to remove that AI for a round or two.
The document has drifted badly from where you want it	Open the Menu and click 📖 Round History to restore an earlier version. Add a Note explaining the direction the next round should take. If your goal was too vague, edit it on the Project screen before running another round — click the project name in the top bar to open the goal viewer without leaving the Work screen.
It would be faster to start over	Click 🏁 Finish → Start New Project. This clears the document and history but keeps your API keys. Return to the Project screen, rewrite your goal with tighter scope, and begin again.

This means the Builder returned output that WaxFrame could not parse — usually because the document was too long or complex for that AI to follow the required output format precisely under that token load. Click Change Builder in the Hive panel, switch to ChatGPT or Gemini, and run the round again. Your document was not changed by the failed round, and the failed attempt is recorded in your Round History for reference.

Open the Notes drawer before the next round and quote the exact text you resolved. Do not paraphrase — use the 🔒 Lock a line template button and paste the exact passage from your document into the placeholder. Write clearly that this decision is final and must not be re-raised. If the problem persists after two rounds, add the same instruction to Additional instructions on the Project screen so it is sent every round permanently. If it still continues after that, toggle the offending AI off via Edit Hive (laptop) or directly on its card (desktop).

Click the Test button next to that AI on the Setup screen. The result panel shows the exact error. Common causes: the key was copied incorrectly (extra space at the start or end is a frequent culprit), the key has been revoked or expired at the provider's end, the account has run out of credit, or the account is on a free plan that does not include API access. To visit that provider's API console directly, expand that AI's row by clicking it, then click the Open [provider] account ↗ link inside the expanded panel — and verify your key and account status.

WaxFrame requires at least two AIs with saved, working keys and a Builder selected before the Smoke the Hive button activates. If it is greyed out or inactive, open the Menu and navigate to Setup 1 — Worker Bees. Verify that at least two AI key fields show the 🔑 icon. Then navigate to Setup 2 — Builder and confirm a Builder is selected. Note: two AIs is the technical minimum, but three or more is the empirical recommendation for faster convergence and automatic resolution of reviewer disagreements — see Step 5 above.

AI provider websites change their navigation regularly. If a link in WaxFrame leads to a dead or moved page, open the API Key Guide ↗ from the Menu — it is updated with each WaxFrame release and contains current direct links for every supported provider.

↑ Back to top

WaxFrame does not charge per use. The cost of running rounds comes from the API calls WaxFrame makes to your AI providers on your behalf — and those are billed directly to your account at each provider. WaxFrame requires only a one-time license fee after the first three free rounds.

API costs are measured in tokens — small units of text (roughly 0.75 words per token). You are charged for both the tokens sent in the prompt and the tokens returned in the response. For a detailed explanation of how tokens work and how to estimate your costs, see What Are Tokens? ↗

Click Open API Websites on the Setup screen to open the billing or usage dashboard for every AI in your hive simultaneously. Check your usage after your first few sessions to understand your actual per-round cost. Provider pricing changes periodically — bookmark your billing dashboards and check them at least monthly.

Perplexity requires you to explicitly enable auto-billing in your account settings before API calls will succeed. If Perplexity's Test button returns a billing-related error, log into your Perplexity account at console.perplexity.ai, enable auto-billing, and retry the test.

The Open API Websites button opens multiple browser tabs simultaneously. Most browsers block this by default and show a pop-up blocked notification in the address bar. Click the notification and choose Always allow pop-ups from this site, then click Open API Websites again. This only needs to be done once per browser.

AI	Default model	Provider billing page
ChatGPT	gpt-4.1	platform.openai.com ↗
Claude	claude-sonnet-4-6	console.anthropic.com ↗
Gemini	gemini-2.5-flash	aistudio.google.com ↗
Grok	grok-4-fast-non-reasoning	console.x.ai ↗
Perplexity	sonar-pro	console.perplexity.ai ↗
DeepSeek	deepseek-chat	platform.deepseek.com ↗

To change the model for any AI, go to the Setup screen and click the model name shown below that AI's key field. A dropdown appears with all models currently available on your account with that provider, fetched live at the time you open it.

↑ Back to top