KVICK.BIKE Bible

Public · comprehensive · successional. This is the whole picture — every architectural decision, every operational doctrine, every domain rule, every trade-off Kvick made along the way. Nothing's hidden in a private wiki; nothing's withheld for an internal tier. If a shop, an operator, a developer, an auditor, or a successor needs to understand how the system works (or why it works that way), the answer is in here.

This Bible covers the clean-room bike-vertical Hub — the kvick-bike Worker that ships at kvick-bike.solitary-poetry-5fcc.workers.dev. One Worker, one D1, three strata, modular bricks.

This Bible is one of many

Every KVICK customer's deployment ships with its own Bible, public at its own URL. The shared canon (foundation, principles, decisions, domain) is identical across every bike-shop instance; each customer's Bible additionally records the deviations they chose. The Bible is the spec the shop bought into, and the record of how their copy diverged. See Per-build pattern below.

Who reads this

Shop owners weighing a switch	Start with What is Kvick?, the Doctrine and Customer Compact — they say plainly what you're buying into. The Business model page covers price + terms.
Operators + staff	The Principles section answers most "why does it do this?" questions. The Domain section maps the entities (customers, bikes, tickets, transactions) and lifecycles you'll work with daily.
Developers joining cold	Substrate Line → Three Scenarios → Slice overview, then the slice you're touching. Local setup is in Runbooks.
AI agents (the off-app auditor, the in-Hub Support bubble when it lands)	The corpus is structured for retrieval; the conformance suite reads it as the canon to grade against.
Partners, auditors, successors	Whatever you need to know, the Bible has the full text. ADRs (Decisions) capture the reasoning behind every load-bearing choice.
Anyone curious	Welcome. Read freely.

Build it as we code

This Bible grows page-by-page as code lands. No history-book content. No planning documents that don't reflect shipped state. If a page can't be deleted without losing load-bearing information, it earns its keep. If it can, it goes.

The discipline is the review-and-update loop: every meaningful commit on the operator Hub either updates an existing page or earns a new one in the same commit window.

Why a per-build Bible

Every KVICK build ships with its own Bible — public at its own URL. The reasons:

1. It's the spec the shop bought. The vertical canon (the bike-shop doctrine, the architectural choices, the domain model) is identical across every bike-shop instance. Each customer's Bible additionally records the L3 deviations they chose — "our walk-in deposit is 25%, not the canon 20%" lives in their Bible, signed by them.
2. It substitutes for institutional memory. Twelve months from now, someone — a new owner, a new developer, an AI agent, the original team — needs to know why this shop's deposit rule is what it is. The Bible is the answer.
3. It's the input to the off-app auditor. Per the conformance-suite doctrine, the auditor grades the running system against the canon — not against itself. The Bible is the canon's human-readable face; the Process Library (BIKE.L<n>-NNNN designations + realizes_links(spec→binding) edges) is its machine-readable face. Same canon, two surfaces.
4. It's a public-trust instrument. Customers can read the Bible before signing. They see the audit-chain commitment, the data ownership ADR, the single-tenant guarantee, the privacy policy. The Bible's public surface is part of how Kvick earns trust.

What's here today

139 pages spanning the full vertical canon and the implementation substrate that's shipped so far. Browse by category:

• Foundation — the load-bearing doctrine (read this first; Three strata describes how the system is organized)
• Overview — what Kvick is, business model, customer + market, tech stack, roadmap
• Principles — the "why does it do this?" answers
• Architecture — the system's mechanics
• Decisions — the ADRs explaining every load-bearing choice
• Domain — entities, lifecycles, slices (the bike-shop model), and Modules — the business bricks shipped on the chassis (see below)
• Runbooks — operational playbooks
• Contributing — engineering discipline
• Playbooks — situational scripts (tax jurisdiction, customer erasure, Stripe dispute, data export)
• Reference — tables and registries

Modules shipped

Module	What it does
Sales	The POS sell screen · split-tender · estimates (convert-to-sale) · layaway / special-order deposits (deposit-to-sale with credit) · resume-for-edit · hold/resume · Return with pick-destination-at-completion + store credit · payment reversal · cancel-and-refund · line + cart discount rule engine · per-line tax override + BC bundled-accessory rule · status-card exemption · void
Migration	sys-admin only · one-time AIM cutover tool (BIKE.L1-0016) — backup picker (local agent) → D1 staging → fidelity gate → wipe → convert (catalog → suppliers → customers → sales → bikes → service → purchasing → finalize) → parity report → commit or Time Travel rollback
My Hub	Staff home surface — live weather chip · End-of-Day report · Shop Tasks (ad-hoc + recurring templates, audited) · Shop Board (rich-text announcements + images, pin + expiry, audited) · Messages board
Service	Workshop work-orders — search + today's-service-orders ledger grouped by status · drop-off → labour (service_menu) + parts (variants) · status lifecycle (Start Work / Wait for Parts / Stop·Call / Ready / Notify) · pickup invoices as sale
Customers	Customer search (FTS5, family-member-searchable) · year-over-year header · spend-over-time bar chart · 9 section pills · credit-debit · Merge · Print · loyalty enrol · PIPA export/erase
Purchases	PO ledger · Purchase Cart (vendor-grouped, per-line steppers) · Vendors management · PO lifecycle (pending_order → ordered → received) · editable Order Card · receiving depth (cost-override, cost ladder, over-receipt) · rich vendor record · special-orders auto-post from Sales
Inventory	SKU search · variant detail (Hero / Stock / Vendors / IDs / Description) · Product Card editor · 3 stock actions · 7-view analytical ledger · Recent purchasers · Print tag · Reorder dashboard · Vendor RMA
Settings	Users + Staff management · editable Permissions Inspector with custom roles + per-staff overrides + Reset Owner · Discount builder

More modules — Rent · Maintenance — land as they ship, each with its own Bible page in the same commit window.

About the eComm tab

As of v0.7.405 an eComm tab appears in the strip (between Inventory at 21 and Settings at 90, tab-order 23 after v0.7.406's collision-fix with Trades). It is a layout preview only — the module folder holds view.ts + index.ts and nothing else: no client script, no API, no route, no database query. Every control is rendered disabled and a banner on the screen says plainly that nothing is live and the rows are typed into the page. Requested by Tom as "a mock up with no code except to show the layout in the Hub"; the eight eComm entries stay on the docket as unbuilt work. No shipped functionality; no designation claimed; not in the shipped-modules table above.

How this Bible is built + deployed

This Bible is a standalone Cloudflare Pages deployment (source: KVICKADMIN/KVICK.BIKE.BIBLE). It owns its own public URL end-to-end; the kvick-bike Worker (the operator app) links to it from the user-menu but serves none of the content. Decoupled by construction — Bible edits never touch the Hub's deploy; Hub deploys never touch the Bible.

The source is open. The build is reproducible (npm install && npm run build). The deploy is one command (npx wrangler pages deploy). The discipline is documented in Update Bible and Documentation maintenance.

See also

• This build's operator app — kvick-bike.solitary-poetry-5fcc.workers.dev — the Hub itself
• KVICK — kvick-hub.solitary-poetry-5fcc.workers.dev — the cockpit hosting the Process Library + the off-app Auditor