# Same Solutions — Equipment Service Guides

Canonical source for AI-assisted equipment diagnostic and service work at
Same Solutions LLC. Each equipment item (lawn tractor, jetski, boat, etc.)
gets a versioned HTML field service guide produced collaboratively in a
per-equipment Claude chat session, governed by a shared methodology, hosted
here for durability beyond any single session.

**Deployed:** [URL pending Cloudflare Pages setup]
**Visibility:** Private repo, Cloudflare Access in front of guides
**Owner:** Sam Foran / Same Solutions LLC

---

## What's in here

| Path | Purpose |
|---|---|
| [METHODOLOGY.md](./METHODOLOGY.md) | Canonical methodology — verification discipline, source citation, role split. Equipment chats fetch this at session start. |
| [SYSTEM-DESIGN.md](./SYSTEM-DESIGN.md) | Document format standard, Firebase data model for /manage integration, roadmap. |
| [architecture/](./architecture/) | Architecture decision records (ADRs). |
| [templates/](./templates/) | Skeleton HTML for new guides. Copy + fill in. |
| [guides/](./guides/) | One folder per equipment item, versioned HTML guides + assets. |
| [handoff-blocks/](./handoff-blocks/) | Per-session state captures so the next chat for the same equipment can resume context. |

---

## Roles

The system uses three roles with explicit boundaries
([ADR 001](./architecture/2026-04-26-role-split-decision.md)):

| Role | Owner | Outputs |
|---|---|---|
| Diagnostic + content | Per-equipment Claude chats | Versioned HTML guides, handoff blocks, photos, source citations |
| Infrastructure + integration | Claude Code | Repo setup, deploy pipeline, /manage Equipment tab, schema, migrations, CI |
| Coordination + prioritization | Sam | Workstream priorities, "done enough" calls, methodology revision decisions |

---

## How to start a new equipment chat

Paste this at the top of a new Claude.ai session:

```
Equipment service work using my standardized methodology. Pull the current
methodology from <DEPLOY_URL>/METHODOLOGY.md before proceeding.
Equipment for this chat: [X]. Current symptoms: [Y].
```

Replace `<DEPLOY_URL>` with the Cloudflare Pages URL for this repo.

The methodology path is intentionally exposed without Access (bypass policy);
the rest of the deploy is gated. See "Access policy" below.

---

## How to add a new equipment guide

1. Open a new Claude chat with the session-start block above.
2. Diagnostic work proceeds against METHODOLOGY.md.
3. When done, the chat renders a versioned HTML guide following the format
   in SYSTEM-DESIGN.md Section 1, using `templates/equipment-service-guide-template.html`
   as the skeleton.
4. You (Sam) save the file as `guides/<equipment-id>/<equipment-id>-service-guide-v1.html`.
5. Create `guides/<equipment-id>/latest.html` as a meta-refresh redirect
   to the v1 file (see [versioning ADR](./architecture/2026-04-26-versioning-and-aliases.md)).
6. Drop any photos into `guides/<equipment-id>/assets/` using the convention
   `<equipment>-<subject>-<YYYYMMDD>.jpg`.
7. Commit + push. Cloudflare Pages auto-deploys.
8. Capture session state into `handoff-blocks/<equipment-id>-<YYYY-MM-DD>.md`
   so the next chat can resume.

---

## How to update an existing guide

1. New chat references the current `<equipment>-service-guide-v<N>.html`.
2. Apply changes, increment version → v(N+1).
3. Add an erratum block to the new version if prior info was wrong.
4. Update `latest.html` to redirect to the new versioned filename.
5. Commit the new version and the updated `latest.html` together.
6. Old versions stay in place — they are referenced by later errata.

---

## Access policy

Cloudflare Access protects most of this deploy. The following paths are
**bypassed** so equipment chat sessions can `web_fetch` them without auth:

- `/METHODOLOGY.md`
- `/templates/*`
- `/architecture/*`

These contain no customer data, equipment serials, or pricing. Everything
else (`/guides/*`, `/handoff-blocks/*`, `/SYSTEM-DESIGN.md` if it ever
gains sensitive content) requires Access auth.

---

## Local viewing

Clone the repo. Open any guide HTML directly in a browser via `file://` —
no build step, no server. The `latest.html` alias works locally too.
Field service notes are designed to function offline on a phone.