What the app writes into my Booking HQ files (Deal stage, Next action due, and gate lines)

You opened your Booking HQ folder in a text editor, read a couple of lead.md files, and came away thinking Booked Solid stores its operating state as freeform markdown with no schema and no required fields, so anything goes and nothing is ever checked. That is a fair reading of a workspace that has been through a few versions of the app, and it is not true of the app you are running now. There is a schema. This page is the reference for it, written for the person who tells us I am editing my BookingHQ files by hand and wants to know exactly what the app will do with the result.

One thing to settle before the details. If your own files show the loose behaviour described below, such as a gig with no stage line, a next action with no due date, or parked decisions in two different shapes, that is almost certainly a workspace carrying structures from before those fields existed, or lines someone wrote by hand. It is not what a current Booked Solid writes fresh.

Which lines the app actually reads

Each gig lives in its own folder under leads/, and the record is that folder's lead.md. Your gig list (the Gig Desk tab, called Leads in older builds), the Dashboard, the Calendar and the money views read only the typed - Label: value bullet lines at the top of that file: the lines below the # Lead: name title and above the first ## heading.

Understand this part before you change anything, because it explains most of the confusion. A fact written in prose, inside a ## section, down in the log, or under a label the app does not know is invisible to the app. The card shows a blank field, the gig sits in the wrong column, and nothing tells you why. So the rules of the top block are:

• Every fact the app reads sits on its own - Label: value line.
• Each label appears at most once. A repeated label is reported as a problem, not merged.
• Never two labels on one line.
• ## Log and everything under it is append-only history. The top lines are the current state.

The typed labels the app writes up there cover the buyer (Buyer name, Organization, Email, Phone), the show (Event type, Show format, Event date, Start time, Duration minutes, Venue, City, Audience size, Room notes), the money (Currency, Budget amount, Quoted fee, Agreed fee, Deposit amount, and the cost lines Travel cost, Marketplace cost, Assistant cost, Materials cost, Other cost), where it came from (Source channel, Source detail, Source reference, Source external id), what happens next (Next action, Next action due, Blocker), response timing (Inquiry captured, First response, Last client contact), the growth lines (Proof permission, Review status, Referral source, Referred by deal, Rebook date), milestone lines such as proposal-sent at, accepted at, signed at, retainer-paid at and show-completed at, and the stamps Deal created and Record updated. Records also carry the older lines Event, Date, Contact, Source, Budget signal and Status. Those came first, they are still read as a fallback, and the app keeps writing them alongside the typed ones so nothing that reads the old shape goes blind.

For the rest of the folder, the map of what lives where is written into your own workspace at _config/where-things-are.md, and you can ask Otto in chat where things are and get the same answer, checked against the folders you actually have.

Deal stage is the canonical status field

If the question you came here with is should Deal stage be the canonical machine-readable status of a gig, the answer is yes, and it already is. The line looks like this:

- Deal stage: proposal-sent

Whenever that line is present and carries a value the app recognises, it wins outright. Your board column, the Dashboard pipeline counts, the Calendar layers, and every open-or-closed judgement the app makes come from it. The older - Status: line is read only when there is no usable Deal stage line at all. That fallback exists for records written before the typed field, and for nothing else.

What are the valid stages

Deal stage is a controlled vocabulary, not free text. Type the value exactly as shown here: lowercase, hyphen where there is a hyphen, no spaces. The name after each one is what the app calls the same stage in its Stage dropdown, so you can match what you see on screen to what is on disk.

• new is New inquiry.
• prospecting is Prospecting.
• qualifying is Qualifying.
• proposal-draft is Proposal in progress.
• proposal-sent is Proposal sent.
• negotiating is In conversation.
• accepted is Accepted, not yet secured.
• hold is Date on hold.
• booked is Booked.
• completed is Show completed.
• lost is Lost.

In practice the moves are: a proposal went out means proposal-sent, they said yes means accepted, the retainer is paid or the date is locked means booked, the show happened means completed, and it died means lost.

Two things go wrong here, and both are reported rather than guessed at. A Deal stage line carrying anything outside that list comes back as The saved stage is not recognized. and the app falls back to the old Status line in the meantime, which is usually why a gig lands somewhere you did not expect. Two Deal stage lines in one file come back as This field appears more than once. Both appear in the gig editor under the heading This older record needs review.

Status: is freeform, and that is on purpose

The - Status: line is freeform. The app never checks its wording, because that line is yours for colour and context. Write what helps you.

What the app does do with it is narrow and worth knowing before it surprises you. When you save a record through the gig editor, it keeps your own Status wording if that wording still means the same stage you saved. If it no longer does, it rewrites the line in plain words to match the new stage and moves your old text down to a - Legacy Status detail: line rather than deleting it.

Almost everyone who wants to move a gig by hand edits - Status: first, because it is the line that reads like the status. If the file also has a Deal stage line, that edit changes nothing anywhere in the app. Skip that step and change - Deal stage: instead.

One more trap in the same area: do not copy the filter chip labels from your gig list into the Deal stage line. Those chips are a short presentation list for filtering, and some of them stand for more than one stored stage. The eleven values above are the stored vocabulary. The chips are covered in The Leads tab: search, filter, and read any lead's history.

Next action and Next action due travel together

A gig record carries two paired lines:

• - Next action: Send the three option proposal
• - Next action due: 2026-08-19

In the gig editor these two fields are labelled Next move and Next move due, and saving writes them out under the names above. The due date is validated on save. A malformed one is refused with Next action due date must use year, month, and day.

If you are typing it yourself, use YYYY-MM-DD and nothing else, on its own bullet line in the top block. That exact shape is what the Due now list on Today and Otto's own follow-up sweep read first. A date sitting in prose is only picked up when a follow-up word sits in the same sentence, so it is far less dependable than the typed line.

Now the part that surprises people. The due date is not required, and that is deliberate. The app does not block a save that leaves it empty. Otto's operating instructions tell him to write the due line alongside the action every time, but that is an instruction, not a hard gate, because a half-known next step is still worth recording. So a booked lead whose next action has no due line is not something you broke: that record either predates the typed field or was written outside the gig editor. Add the due line and the gig starts showing up in your day.

Parked decisions and the gate to: field

When the app parks something that is genuinely your call, it writes it into queue/needs-human.md. Each parked item is a numbered entry with a bold plain title, one sentence on why it is waiting, a Your move: line, and then a fenced block opened with three backticks and the word gate. Inside that fence the typed fields sit one per line as key: value.

The one people ask about is the gate to: field. It has one definition: the recipient email or name, for anything aimed at a specific person, which means any send, quote, or date commitment. It is there so your do-not-contact rule can be checked against a real recipient before anything is approved. The other fields you will see in the fence are token, kind, fee, currency, date, touches, summary and draft, plus notice on a pure heads-up and goto on an item that is really a hand-off to another screen. Only the ones that apply are written.

If your needs-human file shows mixed shapes, a bare email address on one item and a name with contact details on another, those gates were written by hand or by an older instruction set. New gates the app parks follow the one shape.

This matters more than tidiness. A parked item with no proper gate fence still appears on your board, but it carries no typed fields, so your house rules fail closed against it. If you have saved any house rule at all, a floor rate, a do-not-contact list, or a follow-up cap, the Approve button is greyed out and the card reads Couldn't check this against your house rules: the details weren't spelled out. Edit it to confirm before approving. A fence that is present but leaves to: out of a send, quote, or date commitment gets the narrower version of the same refusal, Couldn't confirm who this goes to, so I can't check it against your do-not-contact list. Either way, an item written by hand without a proper fence is an item you cannot approve. If you are writing one, write the fence.

Editing by hand without breaking the record

1. Close the gig editor before you edit the file. If you change lead.md on disk while the editor has it open, saving comes back with This record changed after you opened it. Reload it before saving so no newer work is lost. and a Load the newest version button.
2. Keep every typed line in the top block, above the first ## heading, each starting with - .
3. Use the exact label spellings, one label per line, each label once.
4. Dates are YYYY-MM-DD. Times are 24 hour HH:MM.
5. Money lines take plain numbers with no currency symbol. The currency is its own three letter line, such as - Currency: USD.
6. Never write unknown, TBD, or a guess into a typed line. Leave the line out entirely until you know the value.
7. Leave ## Log alone except to add a line at the end. It is history, not state.

The safer paths, and when each one is right

• The gig editor. On your gig list, open the gig and click Edit gig details. Every field runs through validation, the previous version of the file is backed up before anything is written, and the app reads the file back afterwards to prove the save landed.
• Dragging a card on the board. The Board view changes one thing: it rewrites the Deal stage line, its Status mirror, and the updated stamp, and leaves every other byte of the file exactly as it was. This is the right move on an old record that has a flaw somewhere else you do not want to touch yet.
• Asking Otto. He has tools that write these exact lines, verify them, and add a dated note to the log. His own instructions tell him to edit the typed lines by hand only when those tools are unavailable. That is a reasonable rule for you too.

One rule outranks all of this. Keep your Booking HQ in a plain local folder. Never put it inside OneDrive, Dropbox, Google Drive, or on a network drive, because those locations silently block gig saves, so work can look done and quietly never land on disk. Where the folder lives and how to move it is covered in Your Booking HQ folder: change it, find it, restore a backup, tune it up.

If the board still shows a stage you did not type

1. Open that gig's lead.md and search it for Deal stage. If there is more than one such line, that is the answer.
2. Check the value is one of the eleven above, spelled exactly, with no trailing text after it.
3. Check the line sits above the first ## heading and starts with - . A stage line that slipped below a heading is not read at all.
4. Open the record in the gig editor. If the This older record needs review. banner appears, read the fields it lists, then save once. That replaces the named booking fields and leaves your notes and other sections untouched.

Still stuck? Email bookedsolid@kivimedia.freshdesk.com with the gig's folder name and the top block of its lead.md pasted in, and a person will help.