Acting on the system¶
Where to go for each job, what the system does behind it, and what to check before you act. Read Reading this guide as an AI agent first; the rules there are not restated here.
Before you start¶
Establish three things about yourself, in this order.
- Which surface you have. The Desk UI (pages at
/app/..., which the browser shows as/desk/...), a whitelisted HTTP endpoint, the store's MCP connectors, or the store assistant. They are not equivalent: the UI runs client-side steps that an endpoint does not, and some workflows exist only as a page. - Whether you are on production. The store runs a live site and a local
development site that is also the automated test fixture. The development
site is full of records named
QA Buyer,_Test BO Dealerand similar. If you see those, you are not on production, and nothing you do there means anything. - What your role opens. Access is by role, and roles differ per page. On a remote connector you act with the signed-in person's own roles. See Who can do what.
Reading¶
Reads are safe and should be your default. The reports are the store's own questions, already asked well, and each one is a better starting point than a raw query.
| Question | Read this |
|---|---|
| What guns are in stock, where each came from, and where it sits in the store | Firearms In Stock |
| Which sales are held waiting on a form or a check | Pending 4473 Orders |
| Every completed Form 4473 and its outcome | Form 4473 Records |
| Whose gun is sitting in the safe unclaimed | Pending Transfer Pickups |
| What came into stock in a period, and how | Inventory Receipts |
| What sold, across every channel, and at what margin | Sales Report |
| Cash in and out of the drawer, day by day | Cash Drawer Weekly, and the Log tab on the cash drawer page |
| Card payments taken on the terminal | The Card payments list (Payroc Terminal Payment) |
| What a distributor has invoiced, including orders placed outside the POS | Distributor Orders → Track Orders → Invoices |
| Which sales a human vouched for rather than the system | Hand-Asserted 4473 Dispositions |
Reports covers the filters and the columns. Two of these carry a legal deadline rather than a preference: Pending 4473 Orders prints the third business day, and Pending Transfer Pickups ages guns the store is holding for someone else.
The work queues¶
If you are asked what needs doing, start here.
The Dashboard at /desk/gun-shop/store-overview is
where staff land. Its blocks are the store's own summary of what is open: 4473s
waiting, guns waiting on pickup, the cash drawer, records not yet in the bound
book, and distributor orders arriving.
The notification bell carries NICS verdicts, new web and GunBroker orders, a distributor shipping to the store, and a bound-book refusal, each linked to its document. It is per person. See Notifications.
Pending Order at /app/pending-dispositions,
labelled Orders in the sidebar, merges counter orders, WooCommerce orders and
GunBroker orders into one list. What a row can do depends on which of the three
it came from. GunBroker rows deliberately cannot be edited or cancelled here.
Distributor Orders at
/app/distributor-restock holds what is being ordered in from a wholesale
house. Its Track Orders tab lists every open order.
Receive Goods → Incoming shipments at /app/receive-goods lists distributor
parcels on their way to the store, including parcels ordered outside the POS.
The cash drawer at /app/cash-drawer lists
Purchases from private sellers with no seller payment recorded.
Dealer Orders at /app/osa-dealer-orders
holds consigned guns a partner dealer has reported sold and not yet paid for.
Doing¶
Each row is a workflow, its entry point, and the thing about it that most often goes wrong.
| Job | Entry point | Watch for |
|---|---|---|
| Book stock in | /app/receive-goods |
A firearm cannot be received from a supplier that is not a verified FFL dealer. The page says so plainly and refuses. |
| Take a gun in trade | The Trade-in button on the register | Paying the seller now records a receipt from the seller with the payment: Cash, Zelle, Check or ACH, with a reference unless it is cash. A trade-in applied as credit still has a federal record due by the next business day, so a parked draft is a deadline, not a to-do. |
| Sell a firearm at the counter | /app/point-of-sale |
The sale cannot complete until the form and the check are recorded. Do not attempt to route around that. |
| Build an order that ships | /app/create-order |
The destination license is verified as part of the flow. A firearm never ships to an unverified or expired one. |
| Finish an order | /app/pending-dispositions |
Disposing books the federal record and removes the gun from stock. It is the hardest step in the whole system to undo. |
| Close the day | /app/cash-drawer |
One count closes the day. Cash records are undone on this page only, never from accounting screens. |
| Ship guns to a partner dealer | /app/osa-ship-consignment (Consignment Out) |
The store's own guns only. Guns held on consignment for someone else are blocked from selection. |
| Put stock on a sales channel | The Item or Serial No form | A model is listed from the Item; one specific gun is listed from its Serial No. Choosing the wrong one lists the wrong thing. |
| Order from a distributor | /app/distributor-restock |
Every order waits in Draft until a person confirms it. Placement cannot be taken back from here. |
| Receive a distributor order | Receive on the Distributor Order | An order with a firearm opens Receive Goods with its lines staged, for a person to check each gun and submit. It is never submitted for you. |
Marking a record as not in the bound book¶
Sometimes a submitted acquisition or disposition should never reach the bound book at all. The usual case is an antique, a receiver made before 1899, booked by mistake: FastBound refuses it because it never acquired the gun. Such a record keeps showing on the Dashboard's Not in the bound book yet list, in the daily digest of stuck records, and in the daily retry.
A manager can mark it as not belonging in the bound book. There is no button in the POS for this. It is a server method, called from an AI client connected to the store's Full MCP server (not the read-only one), by a person signed in as a Stock Manager or System Manager:
| Method | Arguments |
|---|---|
ffl_integrations.fastbound.reconcile.mark_not_in_bound_book |
doctype (FFL Acquisition or FFL Disposition), name, reason |
ffl_integrations.fastbound.reconcile.clear_not_in_bound_book |
doctype, name |
On the connector the call goes through the generic method tool,
frappe_run_method. The desk store assistant cannot make it: it has no tool
that writes to the bound book, at any setting.
What marking does. The record's FastBound sync error becomes
[NOT A&D] <reason>. From then on the daily retry, the stuck digest and the
Dashboard leave it alone. The record itself is not cancelled, because its stock
movement is right. A comment on the record keeps who marked it, the reason, and
the sync error it had before.
What clearing does. It undoes the mark when the record turns out to belong in the bound book after all. The sync error is emptied, so the daily retry pushes it again, and the Dashboard lists it until it lands. A comment records who cleared it.
The method refuses a reason left blank, a record that is not a submitted FFL Acquisition or FFL Disposition, and a record that already has a FastBound ID. The staff-side steps are on FastBound.
A federal record decision
Marking a record keeps it out of the bound book for good. Do it only on a person's explicit instruction, for a record that person has checked, and put their reason in the call. The connector does not ask for a second confirmation on this method, so state the record and the reason and wait for a yes before you call it. Never mark a record to make the Dashboard list go away.
What happens that you did not ask for¶
The system acts on its own, and some of what you observe will be its work rather than a person's. What runs automatically is the full schedule. The ones most likely to confuse a reading of current state:
- The register closes itself at night, so a shift left open is usually closed by morning.
- Orders arrive from the outside channels on a poll, not instantly.
- A reconcile compares the local bound book against FastBound daily, and its alerts are how a push failure surfaces.
- Distributor order statuses, tracking and serials arrive on a half-hourly poll, and distributor invoices on an hourly pull.
- Drop-ship listings on the website change every fifteen minutes, from rules and feeds rather than from a person.
Failure¶
Troubleshooting maps the messages staff actually see to what they mean. Two habits matter more than the list.
Read the refusal as information. This system blocks things deliberately and says why. A refusal to receive a firearm, to ship to a dealer, or to complete a sale is the control doing its job. The correct response is to report the blocker, never to look for a path around it.
A failed write may have left nothing behind, or may not have. Ask what actually landed before retrying. A retry that assumes the first attempt did nothing is how one gun becomes two records. On a remote connector, the Connector Audit Log shows whether the call started and how it ended.
Scope¶
Nothing here authorizes an action. Whether you may act at all, and on which site, comes from whoever is running you. Where this page and that instruction disagree, stop and ask.