# Sojourncase

> Sojourncase is a workspace for assembling an immigration petition — tracking evidence, building specialized trackers, drafting the petition brief, and managing the case end to end. AGENTS: this is a JSON-API app — prefer the agentic layer; do not scrape the DOM or drive a browser unless the user's task needs the human UI (e.g. filling a form) or they tell you to. Every user-facing screen has a machine-readable JSON mirror at /.agentic/<path> (e.g. /build/<trackerId> → /.agentic/build/<caseId>/<trackerId>); any page URL fetched with Accept: text/markdown or application/json returns its machine playbook. Authenticate via the device-grant at /agents.dir/login.md (you get your own scoped token; the user approves once), start at GET /.agentic, and follow the hypermedia _links.

## Start here

- [Agent entrypoint (agents.md)](https://sojourn.cross-fare.com/agents.md): What the agentic layer is, the three pillars (the /.agentic mirror, /openapi.json + api-reference, this doc set), how to authenticate with a Bearer JWT, and the "start here" loop.
- [GET /.agentic](https://sojourn.cross-fare.com/.agentic): The live entrypoint envelope — caller identity, credit balance, accessible cases, and a link to the visa catalog. Requires Authorization: Bearer <JWT>.

## Documentation

- [Navigation guide](https://sojourn.cross-fare.com/agents.dir/navigation.md): The core loop — read data, follow safe _links to sibling /.agentic screens, perform unsafe actions against the real /api endpoints, and resolve meta.docs anchors. Covers RFC 6570 templated links, the rel vocabulary, case-scoping, and cursor paging.
- [Envelope format](https://sojourn.cross-fare.com/agents.dir/envelope.md): The exact shape of the agentic envelope — @context/@type/@id, data, _links (HAL), actions (Siren), and meta — with its invariants.
- [Route list](https://sojourn.cross-fare.com/agents.dir/routes.md): Every /.agentic route and the UI screen it mirrors (today, build, evidence, draft, case, credits, visa-types, new).
- [Domain model](https://sojourn.cross-fare.com/agents.dir/domain-model.md): The entities — cases, trackers, records, fields, tasks, columns, evidence groups, docs, drafts, credits — and how they relate.
- [API reference](https://sojourn.cross-fare.com/agents.dir/api-reference.md): Every /api endpoint by operationId (login, createCase, addRecord, autofillRecord, generateBrief, …), with request/response shapes. Anchors match the action names in meta.docs.endpoints.

## API contract

- [OpenAPI spec (/openapi.json)](https://sojourn.cross-fare.com/openapi.json): The machine-readable REST contract. operationIds are stable and identical to the agentic action names, so meta.docs can deep-link into it.

## Authentication

- [Agent login — device-grant (login.md)](https://sojourn.cross-fare.com/agents.dir/login.md): RECOMMENDED for agents — get your OWN scoped token (sjc_agent_…) without the user's password. POST /.agentic/login/transient {name} → send the user to loginUrl to approve → POST .../claim {claimSecret} → the token, shown once. Scope read = GET-only, write = full; revocable by the user under Account → Connected agents.
- [POST /api/auth/login](https://sojourn.cross-fare.com/openapi.json): The user-JWT path (what the human SPA uses). Exchange { email, password } for { token, user }. Send the token as Authorization: Bearer <JWT> on every /api and /.agentic request. Register at POST /api/auth/register; confirm a token with GET /api/auth/me.