# SHiRE ScanForge Agent Integration Handover

## Intended location

`SHiRE → Agents → ScanForge Scanner Agent`

Primary route:

`/agents/scanforge`

The module must open inside SHiRE's existing fullscreen workspace. It must not open another user-facing window or require another login.

## Build targets

Install dependencies in a development clone, then run:

```bash
npm run build:shire
npm run build:standalone
```

Expected outputs:

- `dist/shire-module`
- `dist/standalone`

The SHiRE build uses `.env.shire`; the standalone build uses `.env.standalone`.

## SHiRE session handoff

The module accepts context in three ways, in order:

1. `window.__SHIRE_MODULE_CONTEXT__`
2. A same-origin `shire:module-context` custom event
3. A same-origin `postMessage` response with type `SHIRE_MODULE_CONTEXT`
4. Same-origin fetch fallback at `/api/v1/modules/scanforge/context`

Minimum context:

```json
{
  "sessionId": "short-lived-session-id",
  "userId": "current-user-id",
  "userRole": "owner",
  "deviceId": "shire-mini",
  "apiBaseUrl": "",
  "agentId": "scanforge",
  "permissions": ["scanforge.read", "scanforge.control"],
  "accessToken": "optional-short-lived-token"
}
```

A same-origin secure cookie may be used instead of exposing an access token to the frontend.

## Required SHiRE endpoints

- `GET /api/v1/agents/scanforge`
- `GET /api/v1/agents/scanforge/status`
- `GET /api/v1/agents/scanforge/capabilities`
- `POST /api/v1/agents/scanforge/start`
- `POST /api/v1/agents/scanforge/stop`
- `POST /api/v1/agents/scanforge/restart`
- `GET /api/v1/agents/scanforge/projects`
- `GET /api/v1/agents/scanforge/jobs`
- `POST /api/v1/agents/scanforge/actions`
- `WS /ws/v1/agents/scanforge`

Schemas are under `contracts/`.

## Main Agents registry

Register `public/shire-agent-manifest.json` in SHiRE's global Agents registry. The main Agents tab should load status from the backend, then pass it to `AgentCard` or render the same fields natively.

The card must never display `Ready` unless:

- `bridgeState` is `connected`, and
- `kinectState` is `ready`.

## Scan Bridge responsibility

The future local bridge on SHiRE Mini must own:

- Kinect v1 USB detection and power-state checks.
- RGB and depth capture using `libfreenect`.
- Frame synchronisation and calibration.
- Point-cloud and mesh processing.
- Local raw-data storage.
- Authenticated preview/status WebSockets.
- File exports and SHA-256 generation.
- SHiREVault presence, identity, write, read-back and checksum verification.

The browser module must never claim direct USB access.

## Security requirements

- No public inbound ports.
- Local HTTPS and authenticated WebSockets only.
- Tailscale for approved remote access.
- Short-lived credentials.
- Pairing attempts must be rate limited.
- Raw filesystem paths must not be exposed to unauthorised clients.
- Demo mode must never be reported as real hardware.

## SHiREVault rule

Canonical backup destination:

`/SHiREVault/Backup/OSBackups`

This is a network-mounted destination. Before any backup-dependent action, verify the mount is present, has the expected identity, is writable, supports read-back and has a verified checksum. Stop on failure. Do not silently use a local fallback.

## Forge handoff rule

`Send to SHiRE Forge` creates imported source geometry only. It does not certify scale, approve manufacturing, remove warnings, select a printer without confirmation, unlock Forge automatically or generate socket/implant/load-bearing prosthetic geometry.

## Safe installation sequence on SHiRE Mini

1. Resolve and verify the SHiREVault network mount.
2. Create and checksum a backup of the current ARMOR UI and Agents registry under `/SHiREVault/Backup/OSBackups`.
3. Verify the backup by read-back before modifying ARMOR.
4. Build this source in a staging directory.
5. Run lint, typecheck and production build checks.
6. Serve the module under `/agents/scanforge` in staging.
7. Add the manifest to the Agents registry without enabling hardware control.
8. Confirm the module shows `SHIRE AGENT CONNECTION UNAVAILABLE` rather than fake data.
9. Implement the ScanForge Agent backend.
10. Implement and test the local Scan Bridge with a harmless household object.
11. Enable real capture only after Kinect detection, depth stream, calibration, storage and emergency-stop tests pass.

No automatic Forge unlock is permitted.