The Hub Feature List — foundation & expectations

Scope

This document governs the SECTIONS array inside public/index.html — the inventory-of-capabilities popup that opens when the operator clicks the Shop icon (top-left brand mark) or the ✨ Features item in the user menu's modal trigger path.

It does not govern the Features comparison screen (a separate full-screen page with three-column AIM / Lightspeed / Hub comparison + traffic-light dots + editorial commentary). That screen is hand-edited by the partnership and is explicitly out of scope for the maintainer described below.

What the list is for

The Hub Feature List ("Does it do this?") is the sales-meeting weapon. James opens it across a table from a prospect and the prospect mentally compares it against the stack of tools they currently use. The desired reaction is consistent: "I cannot replicate this with what I already have."

The list is not a release log. It is not a roadmap. It is not internal product documentation. Those exist elsewhere. This list is the customer-facing inventory of what Hub does, in bike-shop language, organized for sales-floor consumption.

Who reads it

• Independent bike shop owners considering switching from Lightspeed, Square, or paper
• Their accountant, who they will forward it to
• Bookkeepers and shop managers tasked with evaluating
• Industry peers James talks to who want to see what Swicked is running
• Eventually, owners of other specialty retail businesses being shown what's possible

The reader is not a developer. The reader is not a Kvick employee. The reader has run a small business for between five and forty years and has been burned by software vendors at least twice.

What the maintainer maintains

The maintainer is responsible for keeping the list current. Specifically:

1. Add new items when a new feature ships at Swicked or in chassis-canonical Hub
2. Update annotations when a (planned) item ships and becomes live
3. Promote and demote items between categories when the system reorganizes them
4. Rewrite phrasing that drifts away from bike-shop language as the codebase matures
5. Add new categories when a new operational area opens up
6. Soft-deprecate items that have been removed from the product (strike-through with date, then remove after 60 days)

The maintainer maintains only the SECTIONS array in public/index.html. Everything else — the surrounding modal chrome, the Features comparison screen, the page CSS, the build pipeline — is out of scope.

The maintainer does not:

• Decide what to ship next (that is the partnership's decision)
• Edit the comparison or pricing scaffolding around the list (that is hand-edited)
• Edit the Features comparison screen (also hand-edited)
• Remove (planned) annotations unless the feature has been live in production at Swicked for at least 14 consecutive days
• Translate items into other languages
• Add items based on internal discussion or design documents that have not yet produced shipped code

Tier of status

Every item carries a clear status. Three tiers, in order of strength:

Live. The feature is shipping in production at Swicked Cycles right now. James can show it on his screen during a sales call. No annotation needed in the bullet text itself.

(planned). The feature is on the active roadmap with a target release window in the bible. It has design or in-progress code. It is not yet live in production. Annotated with "(planned)" appended to the bullet.

(coming soon). The feature is currently being tested at Swicked but not yet stable enough to be called live. Used sparingly — items spend at most 30 days in this state before either moving to Live or being demoted back to (planned). Annotated with "(coming soon)" appended.

No fourth tier. Items either ship soon or they are planned. If something is uncertain enough that neither label applies, it does not appear on the list at all.

Format conventions

Each item is a single bullet, written as one short sentence that describes what the operator does. The sentence starts with a verb — Ring, See, Track, Apply, Filter, Pull, Send, Print, Run — and avoids vague verbs like "manage," "support," or "handle." If a bullet starts with "manage," the maintainer rewrites it to a stronger verb that names the operator's actual action.

Bullets are written in the owner's voice, not the developer's. The reader is the shop owner doing the action. Examples:

• ✗ Customers can be searched by phone, email, or account number.

• ✓ Search customers by name, account number, phone fragment, or email.

• ✗ The system supports per-customer pricing tiers.

• ✓ Honour a customer's pricing tier automatically on every line (wholesale / member / pro / staff / retail).

• ✗ Audit logging is available for all transactions.

• ✓ See every refund, void, write-off, and price override stamped with the staff member responsible.

The voice is direct, specific, and operational. The reader recognizes the action because they do it every day.

Industry language

Bullets use bike-shop vocabulary, not software vocabulary:

Don't say	Do say
Item	Bike, part, accessory
Inventory item	SKU, variant, model, size, colour
Customer record	Customer, rider
Service order	Service ticket, ticket
Transaction	Sale, ring-up, till
Discount tier	Pricing tier (wholesale / member / pro / staff / retail)
Refund flow	Return, refund, exchange
Invoice line	Till line, line
Payment method	Tender
Sales associate	Sales staff, cashier
Technician	Mechanic
End of day	Cash-out, EOD

When a term has both an industry name and a software name, prefer the industry name. The vocabulary table lives in the bible and is consulted before phrasing a new bullet.

Sectioning

The list is organized into named categories. Categories reflect the operator's mental model of their shop, not the codebase structure. Example: there is no "API" section because owners don't think in APIs. There is no "Database" section because owners don't think in tables.

The current category set, in approximate priority order for sales-meeting consumption:

1. Sign in & access
2. Sales (Ring-Up)
3. Service tickets
4. Customers
5. Inventory
6. Purchases (Bucket + Purchase Orders)
7. Estimates & quotes
8. Reports
9. Rentals & demo fleet
10. Trade-ins & consignment
11. E-commerce & online
12. Marketing & customer engagement
13. Today dashboard
14. Audit & forensics
15. Staff & access control
16. Settings & customization
17. Integrations
18. Hardware
19. Customer feedback (in-product)
20. Offline behaviour
21. Migration from your old system
22. Platform & ownership
23. Kvick-internal (clearly labelled as not customer-facing — kept for completeness)

The order on the page itself is sales-floor strategic, not alphabetical. Service tickets, Sales, and Customers come first because they're the operator's hot zones. Audit, Settings, and Platform come later because they're trust-building rather than pain-relieving.

Granularity

Bullets describe operator actions, not technical capabilities. The granularity test is: would a shop owner ever say this sentence out loud to describe what they're doing? If yes, it's a bullet. If no, it's either too granular (an implementation detail) or too coarse (a category description).

Examples of correct granularity:

• ✓ Take a deposit toward a Special Order (item not in stock; auto-creates the reorder line earmarked to the customer)
• ✓ Refund a posted sale partial-or-full with auto-computed restocking fee and the stock returned to inventory
• ✓ Hover a customer name anywhere to see a quick-card without navigating

Too granular:

• ✗ POST /api/v1/sales returns a 201 response with the created sale ID
• ✗ The customer record validates the email field with a regex

Too coarse:

• ✗ Sell things
• ✗ Manage inventory

Length and density

The list runs long on purpose. Mass is part of the weapon. The target density is roughly:

• 30-50 bullets per major category (Sales, Inventory, Service tickets, Customers)
• 10-25 bullets per supporting category
• 5-15 bullets per niche category

If a category drifts above 60 bullets, the maintainer considers splitting it into sub-categories. If a category drifts below 8 bullets, the maintainer considers merging it into an adjacent category or marking it as an emerging area.

There is no upper bound on total list size. A 400-bullet list that's all true is better than a 200-bullet list that omits half of what Hub does.

What goes on the list

A feature qualifies for the list when:

• It is shipping in production at Swicked Cycles, or
• It is on the active roadmap with a target release window, and the partnership has signed off on including it as (planned)

A feature does not go on the list when:

• It exists only in internal tooling not exposed to the operator
• It is a Kvick-internal capability (e.g. deployment pipelines, registry, monitoring) unless it has direct customer-visible effect
• It is design-stage only with no committed timeline
• It is a chassis primitive that the operator never directly invokes (e.g. the override system, the bible mechanism)

The Kvick-internal section is the exception — it lists internal capabilities deliberately, clearly flagged as not customer-facing, to demonstrate the depth of the operation to a sophisticated buyer who asks about it.

What stays off the list

Even when true, these things stay off:

• The technology stack (Cloudflare, D1, R2, Workers — these go on the Platform section in business terms only, never branded)
• Implementation details (database schemas, function names, route paths)
• Pricing scaffolding (separate page)
• Comparisons to specific competitors by name (the comparison page sits adjacent, not inside)
• Performance numbers that fluctuate (response times, Lighthouse scores — these belong in technical documentation, not the customer-facing list)
• Anything that could read as a promise the system cannot keep
• The mechanisms behind how features are produced (the customer buys outcomes, not mechanisms)

Authenticity bar

Every bullet must be testable. A shop owner reading the list should be able to ask James "show me that one" and James should be able to demonstrate it on his screen at Swicked, today, in real time. If James cannot demonstrate it on the spot, the bullet either needs a (planned) annotation or needs to come off the list.

The maintainer's primary safeguard: when in doubt, add (planned). It's better to flag something as planned and ship it next week than to claim it's live and have James caught short in a meeting.

Source of truth

The bible is the authoritative reference for what's shipped. The maintainer reads from the bible:

• docs/changelog/*.md — the per-release change logs
• docs/modules/*.md — the module documentation for each feature area
• docs/schema/migrations.md — the schema state as of each release
• docs/roadmap.md — what's planned and when

The maintainer does not read from:

• Live customer code (privacy + accidental capture)
• Internal chat or email
• Sales call notes
• Pricing or contract documents

If the maintainer encounters a discrepancy between the bible and the existing list, the bible wins. The list updates to match.

Update cadence

The maintainer runs after every chassis release that produces customer-visible changes. The trigger is the publication of a new changelog entry to the bible. The maintainer:

1. Reads the changelog entry
2. Identifies items that map to new bullets, modified bullets, or removed bullets
3. Updates the list accordingly
4. Writes a brief change summary to docs/feature-list/audit.md
5. Increments the list's build-version stamp at the top

Updates run in response to actual ship events, not on a calendar schedule.

Build-version stamp

The list always shows the build version it reflects at the top of the page. Example:

Hub Feature List · Build v0.6.371 · Last updated 24 May 2026

The stamp is the operator's anchor when reading. It also gives James a clean answer when a prospect asks "is this list current?" — "that's the build we're on this week."

Format on the page

Output format is HTML matching the existing page conventions:

• SECTIONS is a JavaScript array of { title, items } objects
• Items are template literal strings, single bullets each
• Backticks (not quotes) so apostrophes don't escape
• Order within each section is: most-used / hottest features first, edge cases later

The maintainer edits the SECTIONS array directly. It does not edit the surrounding HTML, CSS, or page chrome. Those are hand-maintained.

Soft-deprecation

When a feature is removed or significantly changed, the maintainer does not silently delete the bullet. Instead:

1. The bullet text is preserved with a strike-through wrapper and a date: <del>old text</del> (removed 24 May 2026)
2. The bullet remains visible for 60 days so that anyone who has seen the list in the past month doesn't think they imagined it
3. After 60 days, the bullet is removed from the page entirely
4. The audit log retains the full history

What James should be able to do at any moment

The maintainer's success criterion is operational, not editorial. The list works if:

• James can open it on his phone in a meeting and project it
• He can read down a section and demonstrate each bullet on his screen
• The prospect can compare each section against their current stack
• The build-version stamp is current to within the last week
• Nothing on the list as Live is missing from the system as built

If any of those are false, the maintainer has drifted from its mandate and needs the partnership's intervention.

Out of scope for the maintainer

The maintainer does not generate:

• The comparison-stack header (the "replace these tools" block)
• The cost-summary block (the "your current stack costs ~$370/month" math)
• The closing page (the $199-flat statement)
• Category reordering for sales strategy
• The voice and tone of the surrounding page
• The Features comparison screen (the three-column AIM / Lightspeed / Hub teardown opened from the user-menu)

These are hand-curated by the partnership. The maintainer maintains the inventory of features. The framing around the inventory is editorial work.

Final principle

The list is the answer to the question James gets asked thirty times a year: "so what does it actually do?" The answer should leave the prospect unable to assemble an equivalent stack from anything else they could buy. The maintainer's job is to ensure that, as Hub grows, the list keeps growing too — accurately, in the operator's language, in service of the close.

See also

• Update bible — the "review and update" loop the maintainer runs after each batch of shipped commits