{
  "product": "Miles",
  "purpose": "Complete and verify authorized record-keeping tasks through labeled browser controls or the same-origin authenticated API",
  "version": 1,
  "access": {
    "session": "Use the user's existing authorized session or a disposable synthetic workspace. Never infer permission to send invoices, post to providers, run payroll or change team access from a screen visit.",
    "workspace": "Read /api/me and explicitly choose the intended workspace. Workspace API prefix is /api/w/{workspaceId}.",
    "csrf": "Mutations require the session cookie, same-origin request and X-Requested-With: miles. Direct APIs retain the same membership, closed-period and provider safeguards.",
    "privacy": "Do not include private statements, credentials, trip locations or amounts in public test reports. Prefer synthetic records for acceptance testing."
  },
  "browser": {
    "readiness": "Signed-in pages expose a named Page task region with data-task-state=busy|ready|error. Ready means observed page reads have settled and no request is pending; it does not mean all rows have been loaded or a financial workflow is complete.",
    "completion": "Read the task's receipt or stored record ID, then reload or use a source link. 202 means accepted, with background work still possible. A network failure can leave commit uncertain.",
    "dates": "Use the labeled native date input with YYYY-MM-DD values and an input or change event. Change another field and inspect the Save summary before saving. Verify the persisted travel date, not the DOM value attribute.",
    "correction": "Mileage → Review trip, Weekly review or Search records → selected trip exposes Trip date. Saving recalculates the rate for a changed travel date. Original toll dates are preserved.",
    "recovery": "Mileage → Recently deleted trips → select and confirm restore. Recovery copies begin with this version and retain saved source values and IDs until workspace deletion. Evidence, GPS links and assignments require explicit reconnection. Closed and billed records stay protected."
  },
  "tasks": {
    "manualTrips": {
      "page": "/trips",
      "schema": "/import-formats/trips.schema.json",
      "example": "/import-formats/trips-example.json",
      "batchLimit": 25,
      "workflow": "Paste rows, Preview trips, inspect row errors and totals, explicitly confirm. Retain request UUID and source JSON on an uncertain response. Reusing both returns the original IDs without extra trips. Sources and IDs are retained in the same browser tab, scoped by user and workspace, for reauthentication recovery.",
      "verify": "Compare saved IDs and dates against /trips and /trips/export.csv. Use /trips/summary for full filtered totals. CSV record IDs and review links avoid a second search traversal."
    },
    "fastrak": {
      "page": "/import",
      "schema": "/import-formats/fastrak.schema.json",
      "example": "/import-formats/fastrak-example.csv",
      "workflow": "Prepare a native or explicitly labeled statement-derived CSV, preview without writes, inspect travel/posting dates, replenishments, warnings and existing trip dates, then explicitly confirm import. Poll the returned import ID until done or failed.",
      "retrieval": "Native CSV can be exported from FasTrak Transactions. When downloaded statement PDFs already exist, use a reviewed conversion with source document/page columns rather than requiring another provider login. One reported iPhone Statements → View → Share → Copy handoff worked; this is not a universal device guarantee. PDF files are not accepted directly by Miles.",
      "identity": "Exact file and normalized-row identities prevent repeat toll rows. Preserve actual date/time, lane and tag/plate details. Same-day tolls with existing recorded mileage are left unlinked for explicit review instead of adding a duplicate mileage suggestion. Legitimate independent drives are never merged automatically."
    },
    "history": {
      "page": "/workspace/activity",
      "filters": ["action", "recordId", "operationId"],
      "requestEvidence": "Mutating workspace requests, except validation previews and workspace erasure, return X-Miles-Operation-Id and X-Miles-Audit-State. Activity records actor, route, status and available source IDs without request bodies or provider payloads. Transactional source events and request evidence are distinct. Audit unavailable does not mean the original write failed.",
      "limits": "This is available action history, not a claim of complete historical field diffs, successful file delivery or finished asynchronous provider operations."
    }
  },
  "pagination": "Bounded lists return X-Next-Cursor. Follow it until absent, keeping the original filters. If any page fails, treat the complete-list read as incomplete; never silently reconcile a partial list. Explicit UI Load more actions load additional pages.",
  "verification": "Use known expected fixtures. Reconcile IDs, travel dates, miles, classifications, totals, duplicates and side effects. Record browser build/version, viewport, fixture size, primitive actions, retries, accessibility snapshot bytes and handoffs. Separate cold discovery from warm execution. No Agent Optimized badge is awarded by the presence of this guide or an API."
}