# ellich Station Field Pilot Packet

Date: 2026-06-28

Use this packet during the first real store pilot after cloud readiness has passed. The goal is to prove that every installed surface works on physical hardware, not only in cloud automation.

## Pilot Entry

1. Open tenant admin.
2. Go to `/adm/pos/hardware?section=installers`.
3. Open `Multi-device field install plan` and keep that tenant-specific address table visible.
4. Click `Download worksheet` so the store team has a prefilled CSV row for every required physical device.
5. Open `Manifest / checksums` and compare the full SHA-256 before installing Windows or Android packages.
6. Download the POS / Store Edge installer first.
7. Install the first machine as Main POS / Store Edge.
8. Log in with a tenant owner, admin, or manager account only for setup.
9. Confirm Main POS activation and runtime sync.
10. Download and install the role-specific package for each secondary Windows device: Kiosk, KDS, Customer Display, Operations Board, or Table Order Kiosk.
11. Pair secondary POS, kiosk, KDS, customer display, printer agent, operating board, and signage devices from the generated plan.
12. Use staff PINs for POS floor actions. Do not use the setup login as a POS permission substitute.
13. Record field feedback from the tenant admin installer page, or upload the completed worksheet with `Import worksheet`.
14. Export CSV after the pilot session.

Every station release version must publish the full installer family. Do not run a pilot from a single generic Windows Station installer when the customer handoff requires role-specific POS, Kiosk, KDS, Customer Display, Operations Board, and Table Order Kiosk files.

## Sign-Off Rule

Physical production sign-off requires every required surface to have physical-device `WORKING` feedback with a valid `http://` or `https://` evidence URL that meets its minimum count and no `HIGH` or `BLOCKER` issue.

Cloud-only checks, screenshots from a browser, or automated verifier notes do not count as physical sign-off.

## Required Physical Surfaces

| Surface | Minimum count | Required proof |
| --- | ---: | --- |
| Main POS / Store Edge | 1 | Installer launched; tenant admin login completed; runtime settings synced; secondary device pairing available. |
| Additional POS terminals | 2 | Pairing completed; staff PIN accepted; payment, void, discount permissions checked. |
| Kiosk terminals | 2 | Public/device session opened; menu loaded; order handoff reached POS/KDS. |
| KDS screens | 2 | Station binding selected; tickets streamed; bump/recall actions worked. |
| Customer displays | 2 | Display paired; cart/total stream updated; idle state recovered. |
| Digital signage screens | 2 | Screen token opened; board survived reload; TV/player reboot recovery checked. |
| Operating boards | 1 | Date filter checked; task/inventory review worked; table assignment visible. |
| Receipt/kitchen printers | 2 | Receipt print worked; kitchen print worked; USB/LAN recovery checked. |

Minimum physical device count: 14.

Use the tenant admin `Multi-device field install plan` for the live URLs. It is generated per tenant and includes the Main POS first-run row, every secondary surface, minimum physical counts, setup action, verification point, and auth boundary.

Use `Download worksheet` before the install starts when the team needs an offline checklist. The worksheet is generated per tenant and pre-fills one CSV row per required physical device with the device surface, live address, setup action, verification point, auth boundary, feedback endpoint, and CSV export endpoint. After the team fills result, summary, and details, upload it with `Import worksheet` to save completed rows into tenant field feedback.

## Installer Smoke Evidence

Run installer smoke on the physical device when possible:

```powershell
npm run station:smoke:windows
npm run station:smoke:android:device
```

Windows smoke writes `artifacts/station-release/physical-windows/.../windows-installer-smoke.json`. Android physical-device smoke writes `artifacts/station-release/physical-android/.../android-physical-smoke.json` plus a screenshot and UI dump. The Android command requires one USB-debugging physical device and rejects emulators unless `--allow-emulator` is explicitly supplied for rehearsal.

Each smoke command also writes `field-feedback-draft.json`. Upload the screenshot/photos/receipt/network notes to an `http://` or `https://` evidence location, set that URL in the field feedback row, and mark `Physical device` only for the actual installed hardware.

Before submitting, validate the latest draft:

```powershell
npm run station:field:submit-draft -- --dry-run --evidence-url https://example.com/evidence/device
npm run station:physical:audit
```

When a tenant admin session cookie is available, `station:field:submit-draft` can submit the draft directly with `ELLICH_FIELD_FEEDBACK_COOKIE` and `ELLICH_FIELD_EVIDENCE_URL`. Re-run `station:physical:audit` after each submitted batch to see remaining surfaces.

For already verified Android kiosk and printer installs, generate a completed worksheet:

```powershell
npm run station:physical:success-worksheet -- --kiosk-count 2 --printer-count 2 --evidence-url https://example.com/evidence/store-install
```

Import that CSV from tenant admin after replacing placeholder evidence links with real photo/video/receipt/network-note URLs.

## Feedback Fields

For every tested device or grouped surface, capture:

- Device surface
- Result: `WORKING`, `ISSUE`, `SUGGESTION`, or `QUESTION`
- Severity: `LOW`, `MEDIUM`, `HIGH`, or `BLOCKER`
- Device count
- Device label
- Location
- App version
- Installer version
- Network mode
- Physical device checkbox
- Summary
- Details
- Evidence URL for photos, videos, receipts, or network notes; use an `http://` or `https://` link, not plain text

Use one feedback row per surface group when all devices in the group share the same result. Split feedback rows when individual devices behave differently.

## Blocker Handling

Use `BLOCKER` when a store cannot continue the pilot because of the issue. Use `HIGH` when the issue does not block the entire pilot but would block production sign-off for that surface.

Examples:

- POS cannot pair or staff PIN does not open the POS flow: `BLOCKER`
- KDS does not receive tickets on one screen: `HIGH`
- Digital signage works but does not recover after TV reboot: `HIGH`
- Cosmetic text clipping on one admin page: `LOW` or `MEDIUM`

## Export Evidence

After the pilot:

1. Go to `/adm/pos/hardware?section=installers`.
2. Open Field test feedback.
3. Click `Import worksheet` and select the completed worksheet CSV.
4. Keep the completed worksheet with any install photos, payment/print test notes, and network notes.
5. Click `Export CSV`.
6. Keep the exported evidence CSV with the worksheet.

The CSV includes summary rows for every required surface and feedback rows for each submitted note. Use `remaining_physical_count`, `invalid_evidence_count`, and `next_action` in the summary rows to see which surface still needs valid http/https evidence links, evidence-backed physical checks, or blocker resolution.

## Completion

The pilot is complete only when:

- The customer field pilot gate is `yes`.
- Physical production sign-off is `passed`.
- All 8 surfaces are signed off.
- At least 14 physical devices are verified.
- There are no `HIGH` or `BLOCKER` feedback rows.