# Nuuk TMS

> Staff fleet TMS. Sign in is required. Write tools propose. Confirm applies a pending action in Nuuk or via `confirm_action` when it is still confirmable.

Do not invent VINs, treat trailers as trucks, or invent a confirmation token.

## Discovery

- [/llms.txt](/llms.txt): this brief
- [/llms.json](/llms.json): machine catalog of destinations, query keys, and DOM hooks
- [/.well-known/llms.txt](/.well-known/llms.txt): pointer for operators that look in well-known
- [/robots.txt](/robots.txt): Allow list pointing here
- HTML `<link rel="describedby" href="/llms.txt">` and `<link rel="alternate">` on every page

## Destinations

Every signed-in staff page is operable. The page stays visible. The assistant docks beside it unless you are on `/assistant`.

Ask AI, the header assistant button, and the command palette write `mode=docked` (and `prompt` / `entity` when known) onto the **current** URL so the destination is shareable without leaving the page.

### Records

- [/loads](/loads) · [/loads/42](/loads/42): Loads. Detail infers `entity=load/42`.
- [/trips](/trips) · [/trips/7](/trips/7): Trips.
- [/list/drivers](/list/drivers): Drivers.
- [/accounting/invoices](/accounting/invoices): Invoices. Pass `?entity=invoice/9` (detail is a drawer).
- [/accounting/customers](/accounting/customers): Customers.
- [/trailers](/trailers): Trailers (not trucks).
- [/vehicle](/vehicle): Trucks only.

### Workspaces

- [/dispatch-board](/dispatch-board)
- [/integrations](/integrations)
- [/email-intake](/email-intake)
- [/fuel](/fuel)
- [/fleet/gps-trackers](/fleet/gps-trackers)
- [/maintenance](/maintenance)
- [/files](/files)
- [/accounting/driver-financials](/accounting/driver-financials)
- [/accounting/vendor-bills](/accounting/vendor-bills)
- [/accounting/credit-memos](/accounting/credit-memos)
- [/accounting/reports](/accounting/reports)
- [/payroll](/payroll)
- [/toll](/toll)
- [/accidents](/accidents)
- [/inventory](/inventory)
- [/documents](/documents)
- [/team](/team)
- [/sent-emails](/sent-emails)
- [/owner-dashboard](/owner-dashboard)
- [/collisions](/collisions)
- [/hr/applicants](/hr/applicants)
- [/accounting/deductions](/accounting/deductions)
- [/accounting/banking](/accounting/banking)
- [/compliance-matrix](/compliance-matrix)
- [/subscription](/subscription)
- [/audit-logs](/audit-logs)
- [/notification-settings](/notification-settings)
- [/cameras](/cameras)
- [/live-cameras](/live-cameras)
- [/video-library](/video-library)
- [/accounting/bank-accounts](/accounting/bank-accounts)
- [/accounting/reconciliation](/accounting/reconciliation)
- [/hr/documents](/hr/documents)
- [/hr/tasks](/hr/tasks)
- [/companies](/companies)
- [/users](/users)
- [/billing](/billing)

### Assistant

- [/assistant](/assistant): Dedicated chat workspace. `mode=agent` fills this page only.
- [/assistant?prompt=Diagnose%20this%20load&entity=load/42&mode=agent](/assistant?prompt=Diagnose%20this%20load&entity=load/42&mode=agent): Prefill. Does not send. Does not Confirm.
- [/loads/42?prompt=Diagnose%20this%20load](/loads/42?prompt=Diagnose%20this%20load): Same prefill on the load page. Page stays visible. `mode=agent` docks.
- [/assistant/settings](/assistant/settings): Staff MCP key.

Query `prompt`: composer text only (max 2000 characters).
Query `entity`: `load/{id}`, `trip/{id}`, `driver/{id}`, `invoice/{id}`, or `customer/{id}`. Not trailers or vehicles. On a detail URL the record is inferred when `entity` is omitted.
Query `mode`: `agent` fills `/assistant` only. On any other page it docks so the record stays usable.
Logged-out visits go to `/login?next=…` (same-origin only).

## MCP

- Endpoint: `{API}/api/agent/mcp` (streamable HTTP). POST JSON-RPC 2.0 (`initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read`). GET with `Accept: text/event-stream` opens the session stream.
- Auth: header `X-API-KEY: nuuk_mcp_…` or `Authorization: Bearer nuuk_mcp_…`. Company integration API keys cannot call this (401).
- Write tools return a pending action (60 minutes). Call `list_pending_actions` to recover `actionId` + `confirmationToken`, `reissue_action` to extend TTL, then `confirm_action` to apply or `reject_action` to discard. Do not invent a token.
- Page context: `set_page_context`, header `X-Nuuk-Pathname` / `X-Nuuk-Entity`, `describe_page`, or read `nuuk://pages/catalog` and `nuuk://context/current`.
- Files: `POST {API}/api/agent/mcp/files` (same MCP key, multipart field `file`) returns `companyFileId`. Pass that on propose tools. Fuel Confirm commits when headers match field names or you pass `mapping`.

## How to operate any page

- Current page: `[data-nuuk-region="main"][data-nuuk-page]`. Examples: `loads`, `load`, `trips`, `trip`, `invoices`, `integrations`.
- Current record: `[data-nuuk-entity]` such as `load:42` on the main column and on the assistant panel.
- Page title: `[data-nuuk-heading="page"]` (visible `h1` or sr-only heading).
- Header: `[data-nuuk-region="header"]`. Nav: `[data-nuuk-region="nav"]`.
- Sidebar leaf: `[data-nuuk-nav="loads"]` (path without a leading slash).
- List surface: `[data-nuuk-list]` values include `loads`, `trips`, `drivers`, `invoices`, `customers`, `trailers`, `vehicles`, `files`, `email-intake`, `locations`, `expenses`, `vendor-bills`, `fuel-transactions`, `fuel-cards`, `team`, `accidents`, `inventory`, `statements`, `deductions`, `sent-emails`, `documents`, `credit-memos`, `collisions`, `hr-applicants`, `hr-documents`, `hr-tasks`, `hr-applicant-documents`, `toll-transactions`, `toll-transponders`, `payroll-scheduled-payments`, `payroll-driver-balances`, `payroll-one-time-charges`, `payroll-one-time-credits`, `settlement-batches`, `driver-settlements`, `service-records`, `pm-schedules`, `service-types`, `maintenance-vendors`, `bank-accounts`, `bank-transactions`, `reconciliation-transactions`, `reconciliation-sessions`, `audit-logs`, `gps-trackers`, `billing-invoices`, `billing-payments`, `camera-devices`, `video-clips`, `dispatch-board`, `dispatch-planning`, `driver-financial-summary`, `invoice-batches`, `companies`, `users`, `ar-aging`, `ap-aging`, `top-customers-ar`, `financial-transactions`, `driver-loans`.
- List row: `[data-nuuk-row="load"][data-nuuk-entity="load:42"]`. Same pattern for trip, driver, invoice, customer. Other row types are click targets only — do not pass them as `entity=`.
- Page Ask AI: button name starts with "Ask AI about". Suggestion chips: `[data-nuuk-suggestion]`.
- Open assistant: button name starts with "Open assistant". Ask AI buttons use `[data-nuuk-ask="true"]`.
- Composer: textbox "Message to assistant".
- Send: "Send message". Enter sends; it does not auto-apply a proposal.
- Confirm a proposal: `[data-nuuk-region="action-card"] [data-nuuk-action="confirm"]`, or MCP `confirm_action` with that action's `actionId` and `confirmationToken`. Reject uses `data-nuuk-action="reject"` or MCP `reject_action`.
- Other regions: `assistant` | `composer` | `action-card` | `assistant-page` | `assistant-mcp-settings`.

## Docs

- [Assistant usage](/docs/guide/tms-agent): Propose → Confirm, page destinations, MCP.
- [Help Center](/docs/guide): Product guide index.
- [Getting started](/docs/guide/getting-started): Sign-in and navigation.

## Rules

- Staff roles only (same as `/api/agent/*`). Drivers cannot use the assistant.
- External agents may propose. Confirm applies only a pending, token-matched action owned by this staff user.
- Trailers are not trucks. `search_vehicles` is trucks only.
- Do not invent a CMV VIN. Confirm copy must stay honest.