# Equipment Service Guide System — Design & Roadmap > **Governance / how-it-works doc set** -- one canonical entry + cross-refs (consolidated 2026-07-15). > Start at **METHODOLOGY.md** (canonical entry). The set: METHODOLOGY = the how-to discipline | > **PRINCIPLES.md** = how/why Sam operates | **ARCHITECTURE.md** = what exists (factual map) | > **SYSTEM-DESIGN.md** = doc-format standard + data model (this) | **SESSION-PRELUDE.md** = session protocol. > Distinct companions, kept separate + cross-linked (not merged) so each stays a single clear subject. System design and roadmap for the equipment service guide infrastructure. Methodology lives in [METHODOLOGY.md](./METHODOLOGY.md) — this doc covers document format, /manage app integration, and forward-looking scope only. Version: 1.3 Owner: Sam / Same Solutions LLC Last updated: 2026-04-28 --- ## Section 1 — Document Format Standard Every equipment service guide should follow this structure to allow consistent rendering and cross-document searching when integrated into the /manage app. ### 1.1 File naming `{equipment-class}-{model}-service-guide-v{N}.html` Examples: - `lt180-service-guide-v3.html` - `fourwinns-h200-service-guide-v1.html` - `seadoo-rxp-service-guide-v2.html` Versioned files coexist with a `latest.html` alias per equipment folder. See [architecture/2026-04-26-versioning-and-aliases.md](./architecture/2026-04-26-versioning-and-aliases.md). ### 1.2 Required sections | Section | Purpose | Notes | |---------|---------|-------| | Header | Equipment identity, verified specs, quick nav | Include PIN/serial, parts catalog code, build year | | DO NOW | Ordered action checklist | Top of page; what to execute today | | Erratum | Corrections from prior versions | Only if applicable | | Numbered Parts | Repair sections by system | PTO, Engine, Electrical, Hydraulic, etc. | | Shopping List | Tiered parts table | Tier 1 mandatory / Tier 2 recommended / Tier 3 as-needed | | References | Sources cited | Manufacturer docs, forums, verified part numbers | | Document History | Version changelog | Track what changed and why | ### 1.3 Visual design tokens ```css --bg: #0e1518; /* dark service manual background */ --accent: #FFB81C; /* JD-yellow caution/highlight */ --green: #5c8a3a; /* success/safe */ --warn: #e85a3c; /* warning/danger */ --ink: #e8e3d6; /* primary text */ --dim: #8a9097; /* secondary text */ ``` Fonts: - **Bebas Neue** — section headers (display) - **JetBrains Mono** — part numbers, specs, technical labels - **Spectral** — body prose ### 1.4 Required elements - Every claim with a source needs a citation in the References section - Every part number must be verified against the manufacturer parts catalog before publication; if unverified, flag with `// UNVERIFIED` comment - Errata block at top if any prior version contained errors - Quick-nav anchor links at top for mobile usability --- ## Section 2 — /manage App Integration ### 2.1 Recommended approach: Knowledge Base extension The /manage app already has a knowledge base with RC vehicle entries. Extend that pattern for equipment service guides. ### 2.2 Firebase data model ``` serviceGuides/ {guideId}/ equipmentId: string // FK to equipment table title: string // "JD LT180 + 48C" version: string // "3.0" status: "draft" | "verified" | "deprecated" createdAt: timestamp updatedAt: timestamp specs: map // verified equipment specs pin: string partsCatalogCode: string year: number [key]: any // arbitrary spec fields sections: array // ordered repair sections - id: string title: string order: number contentMd: string // markdown source figures: array // SVG/image references relatedPartIds: array // FK to parts in catalog actions: array // DO NOW checklist items - text: string priority: number completed: boolean parts: array // tiered shopping list - tier: 1 | 2 | 3 partNumber: string description: string sources: array - vendor: string url: string priceUsd: number verifiedDate: timestamp references: array - type: "manual" | "forum" | "verified" title: string url: string citation: string history: array // version log - version: string date: timestamp changes: string equipment/ {equipmentId}/ name: string // "John Deere LT180" serialNumber: string yearAcquired: number location: string // "home" | "shop" | etc. activeGuideId: string // FK to current guide archivedGuideIds: array ``` The `equipment/` collection is the source of truth for equipment status (active issues, parts ordered, repair history). The repo intentionally does not duplicate this — see footnote on inventory tracking below. ### 2.3 Integration with existing app architecture Given v1.7.0 includes the Unified Document Renderer: - Store section content as markdown in Firebase (matches your current model where renderer accepts markdown) - Render guides through the same component used for other long-form docs - Add a new tab "Equipment" alongside Customers / Quotes / Invoices - Each equipment record has a "Service Guide" sub-view that renders its active guide ### 2.4 Migration path for existing HTML guides For the LT180 v3 guide currently in HTML: 1. Extract sections into markdown chunks (one per Part) 2. Extract the SVG diagrams as inline `` blocks within the markdown 3. Extract parts table into the structured `parts` array 4. Extract references into the structured `references` array 5. Create equipment record + service guide record in Firebase 6. Verify rendering matches the original HTML Estimated effort: 1-2 hours per existing guide. ### 2.5 Cross-guide features unlocked by structuring Once guides are data instead of HTML files: - **Unified parts catalog** — see all parts you've referenced across all equipment, with vendor links and price history - **Search across guides** — "where have I used a 6204 bearing?" - **Service history per equipment** — log when each repair was actually done, by whom, for how much - **Job-link** — when working a customer job, attach a service guide to the job for reference - **Cost rollup** — aggregate parts costs across equipment for accounting --- ## Section 3 — Future Equipment Candidates Equipment likely to need service guides over time: - F-150 / personal vehicle - Foran's transmission shop equipment (separate scope, different ownership) - Customer property HVAC / appliances (already partly tracked via knowledge base) - 3D printer (Bambu A1) — different category, but same documentation pattern works --- ## Section 4 — How to Use This System ### When starting a new repair project 1. Open a new Claude chat 2. Provide the session-start context block (see METHODOLOGY.md, "Session lifecycle") 3. Specify equipment and symptoms 4. Work through diagnosis collaboratively 5. When repair is complete (or paused at a stopping point), render a versioned HTML guide following Section 1 format above 6. If integrating into /manage app, follow Section 2.4 migration path ### When updating an existing guide 1. Open new chat OR continue existing chat 2. Reference the current guide version 3. Apply changes 4. Increment version number (v3 → v4) — keep prior versioned files in place 5. Update `latest.html` alias (see versioning ADR) 6. Add entry to document history with what changed 7. Add erratum block at top if a prior version was wrong ### When something goes wrong with the methodology The LT180 chat ran into trouble three times — confidently stated wrong info (electric clutch), backed off too aggressively (wrong direction), and didn't search the web when it should have. Lessons baked into METHODOLOGY.md: - Search the web before stating part numbers, configuration, or specs - When pushed back on, reconsider rather than capitulate immediately — but admit uncertainty when warranted - Photos beat assumptions every time - Forum confirmations validate diagnoses; one matching report is good, three is excellent --- ## Section 5 — Operational policies ### 5.1 Load-bearing paths The following paths are referenced by methodology, by chat session-start protocol, and by any future /manage app integration. They must not be moved, renamed, or deleted without an ADR committed in the same change. Adding new content under these paths is fine; restructuring the paths themselves is not. | Path | Purpose | |---|---| | `/METHODOLOGY.md` | Canonical methodology, fetched at session start | | `/SESSION-PRELUDE.md` | Kind-specific behavior layer, fetched at session start | | `/SYSTEM-DESIGN.md` | System documentation, fetched as needed for context | | `/index//.md` | Per-entity prior state, fetched at session start | | `/architecture/pending/` | Open Decision Requests, fetched at session start | | `/architecture/-.md` | Accepted ADRs (date-prefixed, never renamed) | | `/templates/equipment-service-guide-template.html` | Skeleton referenced by methodology | | `/guides//latest.html` | Stable per-equipment alias (see ADR-002) | | `/handoff-blocks/-.md` | Per-session state captures (referenced by methodology session-end) | | `/customer-jobs/--/` | Customer job research bins (canonical per SESSION-PRELUDE `kind: customer`) | | `/properties//dossier.md` | Property dossiers (canonical per SESSION-PRELUDE `kind: property`) | | `/digests/maintenance.md` | Generated weekly by CI; do not hand-edit | These paths are also exposed without authentication via Cloudflare Access bypass policy (see 5.3 below) so chat sessions can fetch them at session start without solving auth challenges. Renaming a load-bearing path without updating the bypass policy will break session bootstrap silently; methodology's substrate-failure rule will surface the error, but the user still has to trace it. ### 5.2 Lint policy: CI digest, not pre-commit Repo hygiene checks run as scheduled CI in `.github/workflows/weekly-maintenance.yml`. Output regenerates `/digests/maintenance.md` weekly. Checks include: - Internal + external link integrity (lychee) - `// UNVERIFIED` marker count - Stale guide flags (>180 days unmodified, excluding `latest.html` aliases) **No pre-commit hooks.** Rationale: - One committer (Sam, via Claude Code on instruction). Pre-commit hooks add per-machine setup tax without adding review pressure that wasn't already being applied. - Pre-commit hooks are bypassable with `--no-verify`. Weekly CI is not. - Lint findings as a published digest let Sam triage on his own cadence rather than blocking commits at submission time. Premature linting is its own coordination tax. If a second committer joins the repo, add a path-guard CI workflow to enforce load-bearing path stability (5.1) on every push. Until then, discipline plus the documented list above is the enforcement. Format-specific lint (frontmatter validators, errata-block field checkers, citation density) is deferred until the formats they validate have ≥3 production examples. Building validators for content that doesn't exist yet means guessing wrong about what to validate. ### 5.3 Deploy access policy Cloudflare Access protects the deployed Pages site. The following paths are explicitly **bypassed** (no auth required) so chat sessions can `web_fetch` them at session start without auth challenges: ``` /METHODOLOGY.md /SESSION-PRELUDE.md /SYSTEM-DESIGN.md /templates/* /architecture/* /index/* ``` All other paths require Access authentication. In particular, `/guides/*`, `/handoff-blocks/*`, `/customer-jobs/*`, `/properties/*`, `/digests/*`, and root `/index.html` are gated. These contain references to specific equipment serials, customer property addresses, and pricing that should not be publicly indexed. Adding a new substrate path that needs anonymous fetch (e.g. a future `properties/index.md`) requires updating both this list and the Cloudflare Access policy. The two must stay in sync; an ADR for the path addition is the right place to document the corresponding Access update. --- ## Note on inventory tracking Earlier drafts of this doc included a per-equipment status table here. That data is mutable state (parts on order, active issues, repair completion dates) and properly belongs in the /manage app's `equipment/` collection, not a markdown file that nobody will keep current. The repo holds guides and methodology; /manage holds status. --- End of system design v1.3