@lunch-money/developer-docs 2.11.2 → 2.11.4-preview.1

package/docs/oauth/troubleshooting.md

@@ -0,0 +1,159 @@
+# Troubleshoot OAuth
+
+OAuth problems are usually easiest to resolve once you identify where the flow stopped. An OAuth-related failure can occur in one of three places:
+
+- **Authorization and callback:** your application sends the user to Lunch Money to authorize access, then Lunch Money returns the browser to your registered callback.
+- **Token endpoint:** your application exchanges an authorization code for tokens or uses a refresh token to request replacements.
+- **v2 API:** your application presents an access token while making a request for Lunch Money data.
+
+When collecting diagnostic details, preserve nonsensitive information such as timestamps and error names, but leave credentials and full callback URLs out of logs and support messages.
+
+For a runnable comparison, [try OAuth with the confidential Node.js sample](/oauth/sample-applications#try-oauth-with-your-lunch-money-account). Reproduce the same stage in its end-to-end flow, then compare the result with the sample repository's [troubleshooting guide](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/TROUBLESHOOTING.md) without copying credentials or full callback URLs.
+
+> [!NOTE] Two error formats
+> OAuth protocol endpoints under `/oauth/` use lower-case OAuth error names such as `invalid_grant`. The v2 API uses the Lunch Money response format, with a `message` and an `errors` array whose entries contain `errMsg`.
+
+## Authorization endpoint failures
+
+Authorization can fail before your application reaches the token endpoint. Lunch Money may return a lower-case OAuth error such as `invalid_request`, `invalid_scope`, or `access_denied`.
+
+When Lunch Money can safely use the registered callback, it redirects the user's browser with an `error`, an optional `error_description`, the original `state`, and the authorization-server issuer `iss` as query parameters:
+
+```text
+https://example.com/oauth/callback?error=access_denied&state=RETURNED_STATE&iss=https%3A%2F%2Fapi.lunchmoney.dev
+```
+
+Match on `error` when it is returned, verify `state`, and treat `error_description` as human-readable text that may change. Decode `iss` and compare it with the `issuer` value from authorization-server metadata using exact string comparison. Reject the callback if `iss` is missing or does not match; do not exchange a returned code.
+
+| OAuth error | Likely cause | What to do |
+| --- | --- | --- |
+| `invalid_request` | A required parameter is missing, duplicated, or malformed | Compare the request with discovery metadata; send `response_type=code`, exact redirect URI, `state`, and PKCE `S256` values. |
+| `invalid_scope` | The client does not have a usable registered scope set | Open the client in the [Developer Portal](/oauth/applications) and review its assigned scopes. Registered clients always use that complete set. |
+| `access_denied` | The user declined or the application is unavailable to that user | Treat denial normally. During development, only the owner may authorize; other users require an active approved application. |
+
+### Users cannot authorize an unapproved client
+
+Until a client is approved, only its owner may authorize the application. Anyone else is stopped at the consent screen and is never returned to your application, so you will see no callback and no `error` parameter for these attempts.
+
+Those users are shown the support email registered with your client so they can reach you. For an active client with a support-email update under review, Lunch Money shows the last approved address rather than the newly saved one. If you did not expect authorization to be unavailable, check the client in the [Developer Portal](/oauth/applications). A client stays in development until it is submitted for review and approved. A rejected or disabled client also prevents other users from authorizing the application.
+
+### Redirect URI problems
+
+If the callback address cannot be matched to one registered for the client, Lunch Money cannot safely return the browser to your application. It stops locally and shows the user a page explaining what happened, rather than redirecting with an `error`. Your application receives no callback for these attempts.
+
+The page displays one of two codes, a UTC timestamp, and the application name and public client ID once the client has been resolved.
+
+| Code | Likely cause | What to do |
+| --- | --- | --- |
+| `redirect_uri_mismatch` | The address your application sent is not registered for the client, or differs from a registered one | Open the client in the [Developer Portal](/oauth/applications) and compare the address with its registered redirect URIs. Web-client redirects and native HTTPS or private-use scheme redirects must match every component exactly. For a native HTTP loopback redirect, the scheme, host, path, and query string must match, but the ephemeral port may differ. See [local callback failures](#local-callback-failures). |
+| `redirect_uri_missing` | No `redirect_uri` was sent, and the client has more than one registered, so Lunch Money cannot choose | Send the parameter explicitly. A client with exactly one registered address may omit it; Lunch Money then uses the registered value. |
+
+The page offers the user a prefilled message addressed to the support email registered with your client. For an active client with a support-email update under review, this is the last approved address, which can differ from the address currently saved in the Developer Portal. The message contains the error code, the timestamp, the application name and client ID, and the callback address your application sent, reduced to its origin and path with any query string removed. Compare that sanitized callback address with the redirect URIs registered for the client, then correct either the registered URI or the address your application sends.
+
+## Callback validation failures
+
+After Lunch Money returns the browser to the registered callback, your application must verify that the returned `state` matches the authorization attempt and that `iss` exactly matches the discovered issuer. A missing, changed, or reused `state`, or a missing or mismatched `iss`, is a callback validation failure detected by your application, not an error reported by Lunch Money. Stop the flow, discard the authorization code, clear the one-time state, and begin again. Never exchange the code.
+
+Your application should show the user a safe error message and enough internal reference information for your team to find the failed attempt without exposing the callback URL or its parameters.
+
+## Token endpoint failures
+
+The token endpoint (`POST /oauth/token`) returns OAuth 2.0 errors rather than the Lunch Money v2 API error format. The error name appears in an `error` field and is always lower case:
+
+```json
+{
+  "error": "invalid_grant",
+  "error_description": "grant request is invalid"
+}
+```
+
+Match on `error`. Treat `error_description` as human-readable text that may change; it does not identify the specific cause.
+
+| `error` value | Likely cause | What to do |
+| --- | --- | --- |
+| `invalid_request` | The request is incomplete or malformed, a parameter is duplicated, client authentication is missing or supplied more than once, or the requested grant is not enabled for this client | Do not retry the unchanged request. Confirm that the body is form encoded, each required parameter appears exactly once, and the client uses its registered authentication method. Confidential clients use HTTP Basic; public clients send `client_id` without a secret. |
+| `invalid_client` | The client ID is unknown, the secret is wrong or expired, the authentication method does not match the registered client type, or Lunch Money disabled or deleted the client | Confirm the client ID, client type, and authentication method. For a confidential client, confirm that HTTP Basic uses an active secret. If previously working credentials are still configured correctly, stop requests and contact [developer support](mailto:developer-support@lunchmoney.app). Reauthorizing users will not restore a disabled client. |
+| `invalid_grant` during code exchange | The code expired, was already used, has the wrong PKCE verifier, or does not match the redirect/client | Start a new authorization. Do not retry the same code. |
+| `invalid_grant` during refresh | The refresh token expired, was revoked, was replayed, or the grant is no longer usable | Stop retrying, discard the token set, and ask the user to authorize again. If the error recurs for the same user shortly after a successful refresh, investigate concurrent refreshes before reauthorizing. |
+| `invalid_scope` | `scope` is malformed or a refresh request asks for a scope that the authorization did not grant | Omit `scope` to retain the existing scopes, or send only scopes already granted to the refresh token. Refresh cannot expand an authorization's scopes. |
+| `unsupported_grant_type` | `grant_type` names a grant that the token endpoint does not support | Use `authorization_code` when exchanging a code or `refresh_token` when refreshing. Send the exact value in a form-encoded request. |
+| `invalid_target` | A `resource` value is missing where required, malformed, repeated, unknown, or was not granted during authorization | Use the exact resource from authorization-server metadata or the resource previously authorized. After correcting a refresh request, you may retry with the same refresh token because Lunch Money validates the resource before consuming it. |
+
+A network failure or `5xx` response is not an OAuth protocol result. Use bounded retries for transient failures only when repeating the request is safe. A refresh may have succeeded even when its response was lost, so never retry a consumed refresh token after receiving `invalid_grant`.
+
+An `invalid_grant` response does not distinguish a replayed refresh token from one that expired or is otherwise unknown. Recurrence shortly after a successful refresh is the useful signal: Lunch Money rotates refresh tokens on every use, and replaying a consumed token revokes the entire grant. Serialize refreshes for each grant and persist every replacement before discarding the previous token, as described in [Refresh access](/oauth/tokens#refresh-access).
+
+If a successful authorization-code exchange does not include a refresh token, confirm that the client was registered with `offline_access`. If it was not, create a replacement client that includes `offline_access`; test and review it, then reauthorize users. If it was, contact [developer support](mailto:developer-support@lunchmoney.app).
+
+## API failures
+
+Treat an OAuth `401` as an unknown access-token failure unless a refresh request establishes what happened. When an eligible refresh token is available, attempt one refresh and handle the token endpoint's result, which uses the OAuth format shown above rather than the v2 API format:
+
+1. On success, save the replacement tokens and retry the API request once. The access token had merely expired.
+2. On `invalid_grant`, treat that connection as revoked: mark the connection for the selected user/account as inactive and discard its tokens. Prompt the user to authorize that connection again the next time they need it rather than repeatedly interrupting them. Leave the user's other budget-account connections unchanged.
+3. On `invalid_client`, stop requests for every user of the client and contact [developer support](mailto:developer-support@lunchmoney.app). Lunch Money may have disabled the client; retrying or asking users to authorize again will not help.
+
+If no eligible refresh token is available, discard the rejected access token and ask the user to authorize again.
+
+An OAuth access token can fail because it expired, access was revoked, the client was disabled, the token was revoked or rotated, or the user lost access to the budget account. Every OAuth access-token failure returns the same generic `401` response:
+
+```http
+HTTP/1.1 401
+WWW-Authenticate: Bearer error="invalid_token"
+```
+
+```json
+{
+  "message": "Unauthorized",
+  "errors": [
+    {
+      "errMsg": "Access token does not exist."
+    }
+  ]
+}
+```
+
+The response does not identify the cause. Follow the refresh-first recovery path above rather than inferring whether the token expired or another event ended access.
+
+### Insufficient scope
+
+An `insufficient_scope` response cannot be fixed by retrying, refreshing, or asking the user to authorize the existing client again. It means the client was created without all the scopes required for the operation. This applies to development clients as well as approved clients. The only recovery is to [replace the client](#replace-a-client-to-change-scopes).
+
+```http
+HTTP/1.1 403
+WWW-Authenticate: Bearer error="insufficient_scope", scope="transactions:read"
+```
+
+```json
+{
+  "message": "Forbidden",
+  "errors": [
+    {
+      "errMsg": "Required OAuth scope: transactions:read"
+    }
+  ]
+}
+```
+
+The `scope` parameter names every scope the endpoint requires, including any the client may already have. It is not a list of only the missing scopes. Check the operation in the [V2 API reference](/v2/docs) or [OAuth scopes](/oauth/scopes) to confirm its requirements.
+
+### Replace a client to change scopes
+
+Adding `scope` to an authorization URL cannot upgrade or narrow a grant. Lunch Money ignores the requested value and uses the client's complete registered scope set. To change scopes, create a replacement client, test all functionality, complete any required review, update the deployed client ID and credentials, and send every existing user through authorization again.
+
+## Support email is not confirmed
+
+You cannot submit a client for review until its support email is confirmed. Open the client in the [Developer Portal](/oauth/applications), check that the address is correct, and resend the confirmation email if needed. Check the mailbox's spam or junk folder for a message from `support@lunchmoney.app`.
+
+Each confirmation link expires after 72 hours. You can resend at most once per hour; the Developer Portal shows when another resend is available. If the link reports that it is invalid or expired, return to the client and request a new one. Changing the support address also invalidates any link sent to the previous address.
+
+## Local callback failures
+
+For local development, use a supported loopback host: `localhost`, `127.0.0.1`, or `[::1]`. Matching depends on the client type:
+
+- **Native or public client:** The scheme, host, path, and query string must match exactly. The port is ignored for a loopback redirect, so register one URI without a port, such as `http://localhost/callback`, and let the application use the ephemeral port it binds at runtime.
+- **Confidential web client:** Every component, including the port, must match the registered redirect URI exactly.
+
+Host matching is exact for both client types: a redirect registered with `127.0.0.1` does not match one sent with `localhost`. The browser must also be able to reach the application on the selected host and port. See [development and loopback guidance](/oauth/development#local-loopback-callbacks).
+
+If the safe guidance here does not resolve the problem, contact [developer support](mailto:developer-support@lunchmoney.app) with the client ID, stage, timestamp, and nonsensitive error code. Do not send tokens, secrets, codes, or cookies.

package/docs/rate-limiting.md

@@ -12,6 +12,12 @@ If you exceed this limit, you will receive a `429 Too Many Requests` response.
 > [!NOTE] Rate limit scope
 > Rate limiting is applied per IP address. Requests from the same IP address share the same rate limit quotas.
 
+## OAuth token requests
+
+Requests to `/oauth/token`, including refresh requests, use a separate per-IP OAuth limit shared with `/oauth/introspect`. The default is 300 requests per window, and the default window is one minute. These requests do not count against the API limit applied to `/v1/` and `/v2/` resource requests.
+
+Because this limit is keyed by IP address, unrelated users behind the same office, mobile-carrier, or other network address translation (NAT) gateway can share it. If the token endpoint returns `429 Too Many Requests`, respect `Retry-After` and back off with jitter instead of repeatedly sending the token request.
+
 ## Rate limit response
 
 When you exceed a rate limit, the API returns a `429 Too Many Requests` response:

package/docs/using-with-ai.md

@@ -75,7 +75,7 @@ const token = process.env.LUNCH_MONEY_ACCESS_TOKEN;
 
 ## Best practices
 
-1. **Start with a test budget** — API changes are permanent. Use a test budget while you're learning so your real data stays safe. See the [Getting Started guide](/getting-started) for instructions.
+1. **Start with a test budget account** — API changes are permanent. Use a test budget account while you're learning so your real data stays safe. See the [Getting Started guide](/getting-started) for instructions.
 
 2. **Prefer read-only workflows** — A workflow that only reads data is lower risk than one that can create, update, or delete records.
 
@@ -95,7 +95,7 @@ If you want to experiment, here are a few low-risk starting points:
 4. Ask for patterns in merchant names that might deserve new rules or categories.
 5. Build a reusable "money questions" notebook with prompts you revisit each month.
 
-Start small, and use a test budget while you're learning.
+Start small, and use a test budget account while you're learning.
 
 ## Need help?
 

package/manifest.json

@@ -73,6 +73,102 @@
       "type": "markdown",
       "aliases": ["/v2/branding-your-app"]
     },
+    {
+      "path": "/oauth",
+      "file": "docs/oauth/index.md",
+      "title": "OAuth Overview",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth", "/v2/oauth/"]
+    },
+    {
+      "path": "/oauth/concepts",
+      "file": "docs/oauth/concepts.md",
+      "title": "OAuth Concepts",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/concepts"]
+    },
+    {
+      "path": "/oauth/register-client",
+      "file": "docs/oauth/register-client.md",
+      "title": "Register an OAuth Client",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/register-client"]
+    },
+    {
+      "path": "/oauth/authorization-code",
+      "file": "docs/oauth/authorization-code.md",
+      "title": "Implement Authorization",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/authorization-code"]
+    },
+    {
+      "path": "/oauth/sample-applications",
+      "file": "docs/oauth/sample-applications.md",
+      "title": "OAuth Sample Applications",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/sample-applications"]
+    },
+    {
+      "path": "/oauth/development",
+      "file": "docs/oauth/development.md",
+      "title": "Develop and Test",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/development"]
+    },
+    {
+      "path": "/oauth/tokens",
+      "file": "docs/oauth/tokens.md",
+      "title": "Token Lifecycle",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/tokens"]
+    },
+    {
+      "path": "/oauth/security",
+      "file": "docs/oauth/security.md",
+      "title": "OAuth Security",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/security"]
+    },
+    {
+      "path": "/oauth/troubleshooting",
+      "file": "docs/oauth/troubleshooting.md",
+      "title": "Troubleshoot OAuth",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/troubleshooting"]
+    },
+    {
+      "path": "/oauth/review-and-approval",
+      "file": "docs/oauth/review-and-approval.md",
+      "title": "OAuth Client Review and Approval",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/review-and-approval"]
+    },
+    {
+      "path": "/oauth/native-apps",
+      "file": "docs/oauth/native-apps.md",
+      "title": "Native Apps",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/native-apps"]
+    },
+    {
+      "path": "/oauth/scopes",
+      "file": "docs/oauth/scopes.md",
+      "title": "OAuth Scopes",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/scopes"]
+    },
     {
       "path": "/v2/overview",
       "file": "v2/docs/intro-to-v2.md",
@@ -211,6 +307,20 @@
         { "label": "Using the API with AI", "path": "/using-with-ai" },
         { "label": "Branding your App", "path": "/branding-your-app" }
       ]},
+      { "section": "OAUTH", "collapsed": true, "items": [
+        { "label": "OAuth Overview", "path": "/oauth" },
+        { "label": "Concepts", "path": "/oauth/concepts" },
+        { "label": "Register a Client", "path": "/oauth/register-client" },
+        { "label": "Implement Authorization", "path": "/oauth/authorization-code" },
+        { "label": "Sample Applications", "path": "/oauth/sample-applications" },
+        { "label": "Develop and Test", "path": "/oauth/development" },
+        { "label": "Token Lifecycle", "path": "/oauth/tokens" },
+        { "label": "Security", "path": "/oauth/security" },
+        { "label": "Troubleshooting", "path": "/oauth/troubleshooting" },
+        { "label": "Review and Approval", "path": "/oauth/review-and-approval" },
+        { "label": "Native Apps", "path": "/oauth/native-apps" },
+        { "label": "Scopes", "path": "/oauth/scopes" }
+      ]},
       { "section": "REFERENCE", "items": [
         { "label": "v2 API Overview", "path": "/v2/overview" },
         { "label": "v2 API Reference", "path": "/v2/docs", "external": true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunch-money/developer-docs",
-  "version": "2.11.2",
+  "version": "2.11.4-preview.1",
   "description": "Developer documentation content for Lunch Money APIs",
   "exports": {
     ".": "./package.json",
@@ -18,8 +18,8 @@
     "access": "public"
   },
   "scripts": {
-    "validate:manifest": "node scripts/validate-manifest.js",
-    "prepack": "node scripts/validate-manifest.js && node scripts/prepack.js",
+    "validate:manifest": "node ../../scripts/generate-oauth-scope-catalog.js --check && node scripts/validate-manifest.js",
+    "prepack": "node ../../scripts/generate-oauth-scope-catalog.js --check && node scripts/validate-manifest.js && node scripts/prepack.js",
     "postpack": "node scripts/postpack.js"
   },
   "keywords": [

package/v2/docs/intro-to-v2.md

@@ -10,7 +10,7 @@ All API requests require a Bearer token in the `Authorization` header:
 Authorization: Bearer YOUR_ACCESS_TOKEN
 ```
 
-Get your access token from the <a href="https://my.lunchmoney.app/developers" target="_blank" rel="noopener noreferrer">Lunch Money Developers page</a>. See the [Getting started guide](/getting-started) for a step-by-step walkthrough including how to create a test budget.
+Use a personal access token for API exploration or work with your own budget account. The [Getting started guide](/getting-started) walks through creating one on the <a href="https://my.lunchmoney.app/developers" target="_blank" rel="noopener noreferrer">Lunch Money Developers page</a> and making your first request. Applications built for other Lunch Money users should use an [OAuth access token issued after the user authorizes the application](/oauth).
 
 ## Base URL
 

package/v2/docs/version-history.md

@@ -5,6 +5,13 @@ The Lunch Money API spec uses a modified version of SEMVER for its versioning me
 - The minor version represents the number of main endpoints the current version of the spec supports.  For example, a version of the API that supports the /me, /categories, and /transactions endpoints would have a minor version of 3.
 - The revision number represents the number of updates since the last endpoint was added.  For example, each time changes are made to one of the existing three APIs as described above, the revision number will be bumped.
 
+## v2.11.4 - TBD
+- Add OAuth 2.0 bearer-token authentication to the v2 API, allowing applications to access Lunch Money on behalf of users who authorize them
+- Document and enforce required OAuth scopes for every v2 operation and publish the scope and scope-group catalog mapped to V2 `operationId` values.
+  - Added a new `403` `insufficient_scope` response
+- Document the OAuth 2.0 authorization-code flow used to obtain access tokens
+- Add `include_files` query parameter to `GET /transactions/{id}`
+
 ## v2.11.2 - Nov 7, 2026
 - Allow `balance_as_of` to be `null` in manual account responses
 

package/v2/images/oauth-authorization-flow.svg

@@ -0,0 +1,35 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1120" height="960" viewBox="0 0 1120 960" role="img" aria-labelledby="title desc">
+  <title id="title">Lunch Money OAuth authorization-code flow</title>
+  <desc id="desc">A sequence diagram with three actors: your application, the Lunch Money user, and Lunch Money. The application redirects the user's browser to Lunch Money. When necessary, Lunch Money presents its sign-in screen and the user signs in directly with Lunch Money. Lunch Money then presents the budget-account selector and requested scopes, the user selects an account and approves access, Lunch Money returns an authorization code, and the application exchanges it for tokens. The application calls GET /v2/me, saves the identified connection, and calls the API for that account.</desc>
+  <defs>
+    <marker id="app-arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#b45309"/></marker>
+    <marker id="user-arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#9a6700"/></marker>
+    <marker id="lm-arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#0f766e"/></marker>
+  </defs>
+  <style>
+    .actor{stroke-width:2}.app{fill:#ffedd5;stroke:#b45309}.user{fill:#fef3c7;stroke:#9a6700}.lm{fill:#ccfbf1;stroke:#0f766e}
+    .actor-label{font:700 19px system-ui,sans-serif;fill:#172b2a}.actor-detail{font:14px system-ui,sans-serif;fill:#334e4b}
+    .lifeline{stroke:#94a3b8;stroke-width:2;stroke-dasharray:7 7}.flow{stroke-width:2.5;fill:none}.app-flow{stroke:#b45309;marker-end:url(#app-arrow)}.user-flow{stroke:#9a6700;marker-end:url(#user-arrow)}.lm-flow{stroke:#0f766e;marker-end:url(#lm-arrow)}
+    .step-bg{fill:#fff;stroke:#cbd5e1;stroke-width:1}.step{font:600 14px system-ui,sans-serif;fill:#172b2a}
+  </style>
+  <rect class="actor app" x="40" y="25" width="260" height="72" rx="12"/>
+  <text class="actor-label" x="170" y="56" text-anchor="middle">Your application</text><text class="actor-detail" x="170" y="79" text-anchor="middle">browser route and server</text>
+  <rect class="actor user" x="430" y="25" width="260" height="72" rx="12"/>
+  <text class="actor-label" x="560" y="56" text-anchor="middle">Lunch Money user</text><text class="actor-detail" x="560" y="79" text-anchor="middle">browser, sign-in, and approval</text>
+  <rect class="actor lm" x="820" y="25" width="260" height="72" rx="12"/>
+  <text class="actor-label" x="950" y="56" text-anchor="middle">Lunch Money</text><text class="actor-detail" x="950" y="79" text-anchor="middle">authorization server and API</text>
+  <path class="lifeline" d="M170 105 V930"/><path class="lifeline" d="M560 105 V930"/><path class="lifeline" d="M950 105 V930"/>
+  <path class="flow app-flow" d="M170 140 H550"/><rect class="step-bg" x="278" y="118" width="180" height="28" rx="6"/><text class="step" x="368" y="137" text-anchor="middle">1. Redirect the user</text>
+  <path class="flow user-flow" d="M560 200 H940"/><rect class="step-bg" x="652" y="178" width="196" height="28" rx="6"/><text class="step" x="750" y="197" text-anchor="middle">2. Request authorization</text>
+  <path class="flow lm-flow" d="M950 260 H570"/><rect class="step-bg" x="640" y="238" width="240" height="28" rx="6"/><text class="step" x="760" y="257" text-anchor="middle">3. Show sign-in, when needed</text>
+  <path class="flow user-flow" d="M560 320 H940"/><rect class="step-bg" x="605" y="298" width="290" height="28" rx="6"/><text class="step" x="750" y="317" text-anchor="middle">4. Sign in directly with Lunch Money</text>
+  <path class="flow lm-flow" d="M950 380 H570"/><rect class="step-bg" x="545" y="358" width="430" height="28" rx="6"/><text class="step" x="760" y="377" text-anchor="middle">5. Present budget-account selector and scopes</text>
+  <path class="flow user-flow" d="M560 440 H940"/><rect class="step-bg" x="585" y="418" width="330" height="28" rx="6"/><text class="step" x="750" y="437" text-anchor="middle">6. Select budget account and approve</text>
+  <path class="flow lm-flow" d="M950 500 H180"/><rect class="step-bg" x="385" y="478" width="360" height="28" rx="6"/><text class="step" x="565" y="497" text-anchor="middle">7. Redirect to callback with authorization code</text>
+  <path class="flow app-flow" d="M170 580 H940"/><rect class="step-bg" x="335" y="558" width="460" height="28" rx="6"/><text class="step" x="565" y="577" text-anchor="middle">8. Exchange code with PKCE (+ client secret for confidential client)</text>
+  <path class="flow lm-flow" d="M950 640 H180"/><rect class="step-bg" x="385" y="618" width="360" height="28" rx="6"/><text class="step" x="565" y="637" text-anchor="middle">9. Return access token + optional refresh token</text>
+  <path class="flow app-flow" d="M170 700 H940"/><rect class="step-bg" x="430" y="678" width="270" height="28" rx="6"/><text class="step" x="565" y="697" text-anchor="middle">10. Call GET /v2/me</text>
+  <path class="flow lm-flow" d="M950 760 H180"/><rect class="step-bg" x="350" y="738" width="430" height="28" rx="6"/><text class="step" x="565" y="757" text-anchor="middle">11. Return user id, account_id, and budget_name</text>
+  <path class="flow app-flow" d="M170 800 H330 V840 H180"/><rect class="step-bg" x="285" y="798" width="330" height="28" rx="6"/><text class="step" x="450" y="817" text-anchor="middle">12. Save connection and make it active</text>
+  <path class="flow app-flow" d="M170 890 H940"/><rect class="step-bg" x="385" y="868" width="360" height="28" rx="6"/><text class="step" x="565" y="887" text-anchor="middle">13. Call the V2 API for the active account</text>
+</svg>

package/v2/images/oauth-token-lifecycle.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="990" height="300" viewBox="0 0 990 300" role="img" aria-labelledby="title desc">
+  <title id="title">OAuth token lifecycle and recovery</title>
+  <desc id="desc">Authorization yields a short-lived access token and, when offline access applies, a finite refresh token. Refresh replaces tokens. Expiration, revocation, or a terminal refresh failure leads to fresh authorization.</desc>
+  <defs><marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#0f766e"/></marker></defs>
+  <style>.box{fill:#f0f9f8;stroke:#2a6b64;stroke-width:2}.warn{fill:#fff4dc;stroke:#9a6a16;stroke-width:2}.label{font:600 17px system-ui,sans-serif;fill:#173f3b}.small{font:14px system-ui,sans-serif;fill:#294744}.line{stroke:#0f766e;stroke-width:2.5;fill:none;marker-end:url(#arrow)}.annotation-bg{fill:#fff;stroke:#cbd5e1;stroke-width:1}.annotation{font:600 14px system-ui,sans-serif;fill:#172b2a}</style>
+  <rect class="box" x="35" y="65" width="180" height="70" rx="12"/><text class="label" x="125" y="94" text-anchor="middle">Authorization</text><text class="small" x="125" y="117" text-anchor="middle">user present</text>
+  <rect class="box" x="300" y="35" width="200" height="70" rx="12"/><text class="label" x="400" y="64" text-anchor="middle">Access token</text><text class="small" x="400" y="87" text-anchor="middle">short-lived</text>
+  <rect class="box" x="300" y="165" width="200" height="70" rx="12"/><text class="label" x="400" y="194" text-anchor="middle">Refresh token</text><text class="small" x="400" y="217" text-anchor="middle">finite; offline_access</text>
+  <rect class="box" x="590" y="100" width="170" height="70" rx="12"/><text class="label" x="675" y="129" text-anchor="middle">Refresh</text><text class="small" x="675" y="152" text-anchor="middle">store replacements</text>
+  <rect class="warn" x="790" y="100" width="140" height="70" rx="12"/><text class="label" x="860" y="129" text-anchor="middle">Terminal failure</text><text class="small" x="860" y="152" text-anchor="middle">reauthorize</text>
+  <path class="line" d="M215 88 L290 72"/><path class="line" d="M215 112 L290 185"/><path class="line" d="M500 200 L580 150"/><path class="line" d="M760 135 H780"/><path class="line" d="M675 95 C675 25 500 15 470 35"/>
+  <rect class="annotation-bg" x="530" y="10" width="170" height="28" rx="6"/><text class="annotation" x="615" y="29" text-anchor="middle">replacement token set</text>
+  <rect class="annotation-bg" x="740" y="198" width="240" height="36" rx="6"/><text class="annotation" x="860" y="221" text-anchor="middle">expired, revoked, or rejected</text>
+</svg>

package/v2/spec/AGENTS.md

@@ -41,6 +41,12 @@ Follow these rules whenever editing `v2/spec/lunch-money-api-v2.yaml`:
 - Add links when they materially help consumers discover a related endpoint or relevant guide.
 - Do not add links that merely restate obvious navigation.
 
+### YAML formatting
+
+- Write each description paragraph as a single line. Never hard-wrap prose to a column: inside a folded scalar a line break becomes a space, so a wrap landing beside punctuation or markup silently corrupts the rendered text.
+- Use a folded block (`>-`) only when a description has more than one paragraph, separated by a blank line. A single-paragraph description stays on the key line.
+- Never use a literal block (`|`, `|-`) for prose — newlines become significant, so reflowing later changes the output.
+
 ### Examples
 
 Examples are selective documentation aids, not a required artifact for every spec change.