In-situ editing
The principle
The object being changed is the locus of change.
When James notices that Chain Lube should be on the Frequent tab, the path to fix that starts at the Frequent tab — not at Settings → POS → Frequent Items. When a customer's name is wrong, the path to fix it is to click the name on the customer card — not to navigate to Customers → Edit Profile → Save.
Software that requires you to leave the thing you're working on to change how the thing works is software that puts the system's needs ahead of yours. It also discourages people from making changes at all, because each change carries a context-switching tax that adds up to "not worth it" for small frictions.
Helm rejects that pattern. The Settings page exists, but it is the secondary surface — for things with no on-screen representation to edit (API keys, integration credentials, role definitions, billing). The default path to change anything visible runs through the screen the change applies to.
Why this matters
- Cognitive load. When the operator has to leave context, find a setting, change it, and return, they spend mental energy remembering what they were doing on top of making the change. In-situ editing eliminates the first cost entirely.
- Behavioural compounding. Low-friction edits get made. High-friction ones don't. A bike shop on AIM accumulates hundreds of "we should fix that someday" frustrations that never get fixed. A bike shop on the Hub fixes them continuously, in the moment.
- Strategic differentiation. AIM, Lightspeed, and the generalist POSes don't have in-situ editing. It is one of the Hub's few primitives that competitors cannot easily copy without rebuilding their UI from scratch.
- Doctrinal alignment. The Doctrine says the software adapts to the shop. In-situ editing is the affordance that lets that adaptation happen in the moment, on the screen the change applies to, without context-switching.
The implementation
In-situ editing is the principle. The chassis is helm-editable — a single CSS + JS vocabulary used everywhere editable text lives.
Two modes:
| Mode | Cue | Save | Use for |
|---|---|---|---|
| Inline value cell | Dashed-underline on hover → contenteditable on click | Auto-save on blur | Single values: line price, customer name, PO unit cost, line qty |
| Composite-till modal (v0.6.383+) | Dashed-underline on hover → modal opens focused on the clicked field | Operator clicks Save once after typing through all fields | Composite records: Service Slot ticket details, Trade-in intake, Customer card |
Both modes carry the same visual cue (dashed underline). The operator doesn't have to learn which surfaces are inline vs. modal — the click takes them where they need to go.
What lives on the Settings page (and what doesn't)
The Settings page exists, but its scope is narrow:
| Lives in Settings | Lives in-situ |
|---|---|
| Stripe API keys, Twilio credentials, integration secrets | Frequent-tab tile order, tile labels |
| Role definitions, permission grants, staff PINs | Service ticket statuses, color palette |
| Tax registration numbers, GST/PST/HST treatment defaults | Dashboard card layout |
| Shop hours, address, branding (logo, palette) | Customer profile fields, popup notes |
| Cron schedules, webhook URLs | Service category prices, labor rate |
| Backup retention, audit-chain verification cadence | Receipt template, public-site content |
The test: if it has a visible on-screen representation, it edits there. If it doesn't, it goes in Settings.
Permission gating
Editing affordances respect role permissions. If the current user lacks edit permission for the surface they're looking at, the helm-editable cells render as plain text without the hover affordance — no dashed underline, no cursor change. The setting is still visible (the operator can see what's configured); they just can't edit it.
This is intentional. Hiding visible-but-not-yet-editable settings entirely would make junior staff think the Hub can't do something, when in fact the manager could change it for them. The visible-but-uneditable state is an honest signal.
Audit-chain treatment is identical to any other mutation: every in-situ edit lands in audit_mutations with trigger_source set to a per-surface tag (customer-edit, slot-edit, tradein-edit, etc.). See audit-everything.
The moat
The helm-editable chassis is the visible signature of this philosophy. Once an operator has used it for a week, they can't go back. The friction of leaving-context-to-change-things becomes intolerable. That's the moat.
See also
- helm-editable doctrine — the implementation (states, classes, composite-till modal pattern)
- Substrate Line — what's editable (surface) vs what isn't (substrate)
- The Doctrine — the philosophy this operationalizes
- ADR-0019 — in-situ editing as primary UX
- Audit everything — every in-situ edit lands in the chain