Skip to main content

Update the bible

The bible is the single source of truth for how Helm works. When the code changes, the bible changes. When the bible changes, the code matches.

Drafted from planning · v0.1

The principle​

A doc that's wrong is worse than a doc that's missing. A missing doc forces you to read the code; a wrong doc actively misleads. Keep the bible accurate or delete the section.

When to update​

Update the bible whenever you change:

  • A schema migration (update domain/entities/*)
  • An endpoint signature or behavior (update the relevant slice or reference page)
  • A lifecycle (update domain/lifecycles/*)
  • An ADR's outcome (mark superseded; write a new ADR)
  • A core principle (update the principles page; rare)
  • A new feature (update the slice page; possibly add a lifecycle or entity)
  • An onboarding/deployment step (update the runbook)

Workflow​

  1. Make the code change on a branch
  2. Update the bible files in the same PR (or in a coordinated bible-repo PR)
  3. Review both changes together
  4. Merge

For changes that span both repos (Helm + bible):

  • Helm PR description references the bible PR
  • Bible PR description references the Helm PR
  • Merge in the order that keeps the bible accurate (usually bible last, after code is live)

Adding a new page​

# Pick the right section under docs/
# Use kebab-case-file-names.md (or .mdx for mermaid)

# Frontmatter required:
---
sidebar_position: <next-number-in-section>
title: <Page title>
description: <One-line description>
---

# <Page title>

<First paragraph: what this page is about>

:::note[Drafted from planning · v0.1]
:::

<Content>

## See also
<related links>

Add a "See also" section at the bottom of every non-trivial page. The bible's value compounds with cross-links.

Adding a new ADR​

# In docs/decisions/
# Number is one higher than the highest existing ADR
# File name: 00XX-short-kebab-case-title.md

# Frontmatter + Nygard format (see existing ADRs)

ADR template:

---
sidebar_position: <number>
title: ADR-00XX — <Decision>
description: <One-line summary>
---

# ADR-00XX — <Decision>

- **Status**: Accepted | Superseded | Deprecated
- **Date**: <YYYY-MM-DD>
- **Decision-makers**: <names>
- **Supersedes**: <ADR-N or —>
- **Superseded by**: <ADR-N or —>

## Context
<Why we're deciding this>

## Decision
<What we chose>

## Consequences
**Positive:** ...
**Negative:** ...

## Notes
<Anything else>

## See also
<links>

Diagrams​

Use Mermaid inline; see ADR-0017. Reference the color tokens already established:

  • Internal systems: #c8410c
  • External services: #f6f1eb
  • Storage: #1e3a5f
  • Routes: #3b82f6

Voice and style​

  • Active voice. "The Worker writes the audit row," not "The audit row is written by the Worker."
  • Short sentences when possible.
  • Use "we" for the team / Kvick. Use "the shop" for the bike shop. Use "the operator" for the staff using Helm.
  • Lead with the conclusion; then the supporting detail.
  • Show examples; don't just describe.
  • Always include a "See also" section. Cross-linking is what makes the bible valuable.

Testing the build locally​

cd C:\KVICK\KVICK.BIKE\Swicked-Cycles\Bible\docs-site
npm run start

Opens http://localhost:3000. Hot reload on save.

For a full build (catches broken links, MDX errors):

npm run build

A build failure on main blocks deploy. Fix locally before pushing.

Deploy​

Push to main. Cloudflare Pages auto-deploys via GitHub integration. ~60 seconds from push to live at bible.kvick.bike.

See also​