# Equipment Service Guide System — Design & Roadmap

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.1
Owner: Sam / Same Solutions LLC
Last updated: 2026-04-26

---

## 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 `<svg>` 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

---

## 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.1