@uluops/ops-sdk 6.1.0 → 6.4.1

package/CHANGELOG.md

@@ -4,6 +4,96 @@ All notable changes to `@uluops/ops-sdk` will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [6.4.1] - 2026-09-15
+
+6.4.0 reached Verdaccio only; the review of that change set (anxiety-reader 84 / docs-validator 81 / dx-validator 83 / code-auditor 98, all on the `feat/rehome-surfaces` diff) folded into this release before npm. What changed against 6.4.0:
+
+### Added
+
+- **`login(email, password, { autoRefresh })`.** The default (`true`) is unchanged; `false` installs the session without the password so a 401 surfaces untouched. Why it exists: sdk-core's refresh is a *fresh login*, and under the API's default single-session policy a login **revokes the user's other sessions**; the mutation that hit the 401 is then *not* retried, and the budget is one. A script that must treat 401 as "stop" (spec §4.7) was having the SDK act first. Tested both ways: no `/auth/login` on a 401 with the option, exactly one without.
+- **`isInsufficientRoleError`** — the fifth 403 code gains the guard every other one has.
+- `admin.rehomeProject` / `admin.releaseProjectRehome` **refuse a non-UUID client-side** (`InputValidationError`) — `validateUuid` existed and was dead code; the admin route is id-only and answers 400 to a name, and the whole `projects.*` surface trains callers to pass names.
+- TSDoc `@param`/`@returns`/`@example` on the new operations and validators; `@throws {MfaRequiredError}` on `login`.
+
+### Changed
+
+- **`admin.releaseProjectRehome` shape failure is a `ZodError`**, like every other shape failure in this SDK, not a bare `Error` — and the doc says what it means: the server answers 200 after the row is gone, so a shape failure is most likely a *completed* release.
+- The admin path's missing-`reason` message says why it is required ("the target org's only standing for the move") instead of Zod's "expected nonoptional".
+- `OrgAuditFeedQuery.limit` is documented as **1–100, not clamped** (the API answers 400) — the JSDoc said "1–200 (API-clamped)", which was false on both counts.
+
+### Fixed — documentation that overclaimed
+
+- The 6.4.0 entry said "an MFA-enrolled account could not log in through the SDK … Fixed". True for `login()`/`auth.login()` only: a client constructed with `{ email, password }` (or autoloaded credentials) logs in inside sdk-core, which cannot see the challenge and surfaces a generic `UnauthorizedError`. Documented on `OpsClientConfig`, `MfaRequiredError` and in the README; not fixable from this package without intercepting sdk-core's strategy.
+- The MFA challenge token is **single-use and consumed before the code is verified** (API `totp-service.verifyLogin`) — a mistyped code burns it. The README example read as retryable; it no longer does.
+- **`same_org` is the idempotence signal of the ADMIN path only.** The member path's lookup is source-scoped, so a re-run after the move answers 404, not `same_org`. `projects.rehome`'s doc, the README table and `rehomeRefusalReason`'s doc now say so, and the table gained the two missing reasons (`project_soft_deleted`, `project_has_no_org`) plus a row for *no HTTP answer* (`null` from `rehomeRefusalReason` is "not a refusal I can name", not "safe to retry").
+- README "automatic token refresh" is now qualified with the three properties above.
+
+### Known, not fixed here
+
+- sdk-core's 401 branch inspects the *client's* auth strategy, not the request's `skipAuth`, so a wrong TOTP code on a bare client says "Set ULUOPS_API_KEY" — the one remedy D20 forbids. Filed against sdk-core.
+- A TOTP-installed session's expiry message ("credentials were cleared after login") is sdk-core's and wrong for this path; `JwtSessionAuth` has no way to be handed `expiresAt`.
+
+## [6.4.0] - 2026-09-15 (Verdaccio only)
+
+### Added
+
+The client side of project re-home (project-org-routing-and-rehome spec §4; API deployed 2026-09-15). Three surfaces for three audiences — a member capability, a member feed, and a platform-admin namespace — plus the login branch the admin path made unavoidable.
+
+- **`projects.rehome(idOrName, { targetOrg, reason? }, options?)`** — the member path (`POST /projects/:id/rehome`). The SOURCE is the call's org scope (`options.org` / client `orgSlug`); the project is looked up there, so a work-org project moved without scope is a 404, not a silent personal-org lookup. Returns `RehomeResponse`: the project after the move plus `rehome.{from_org, to_org, audit_ids}` (snake_case by contract; `audit_ids` is `[]` today because the platform ACL returns no ids — the ledger is the durable record). Body is built as the API's `.strict()` schema wants it: `reason` is omitted, never sent as null.
+- **`rehomeRefusalReason(err)`** and `REHOME_REFUSAL_REASONS` — reads `details.reason` on the 400/409 refusals (`same_org`, `moved_during_request`, `deadlock_retry`, `concurrent_modification`, `name_collision`, `soft_deleted_conflict`, `rehomed_away_conflict`, `export_in_progress`, `project_soft_deleted`, `project_has_no_org`) and returns `null` for anything else, an unknown reason included. Enumerated because the Phase 4 runbook (spec §4.7) assigns each a disposition and a script that types the strings itself will misspell one.
+- **`orgs.getVisibleAuditLog(slug, { cursor?, limit? })`** — the D19 feed (`GET /orgs/:slug/audit-log/global`): rows a writer marked `visibility: 'org'`, readable by any member; today, projects leaving the org for a personal org. New `orgs` namespace (reads only). **`readRehomeAuditDetails(entry)`** narrows an entry's `details` to the re-home writer's shape (`RehomeAuditDetails`) or `null`, so a renderer can print a move in one line and everything else raw.
+- **`admin.*` namespace** — `rehomeProject(projectId, { targetOrg, reason })` (the D8 platform path: any project, any orgs, by UUID, `reason` REQUIRED), `listProjectRehomes(query?)` (the reservation/redirect table), `listProjectRehomeEvents(query?)` (the D21 append-only ledger, paged by `seq`; unknown event kinds parse verbatim), `releaseProjectRehome(rehomeId)`. All four need the PLATFORM admin role (`403 INSUFFICIENT_ROLE` otherwise); the two writes are session-only (D20). This is the Phase 4 migration script's substrate; no MCP tool wraps it, on purpose.
+- **`SESSION_REQUIRED`** / **`isSessionRequiredError`** and **`INSUFFICIENT_ROLE`** — the two 403 codes the admin path adds to the org-routing set.
+- **MFA login.** `login()` / `auth.login()` now throw **`MfaRequiredError`** (`mfaChallengeToken`, `expiresAt`, `mfaMethods`; guard `isMfaRequiredError`) when `POST /auth/login` answers the challenge shape, and **`OpsClient.loginWithTotp(challengeToken, code)`** / `auth.totpLogin()` complete it (`POST /auth/totp/login`) and install the session. Not a nice-to-have: D20 makes the admin re-home route session-only and the operator account may be MFA-enrolled, and the SDK could not log such an account in at all — see Fixed. A TOTP-installed session carries no password, so it is NOT auto-refreshed; on expiry requests fail 401 and the caller logs in again (a migration script treats that as "stop", never "retry with the key").
+- `ProjectResponseSchema` gains **`orgId`** (nullable, optional). The API has emitted it on every project read since org scoping landed; `z.object()` was stripping it, so a re-homed project's new org was invisible through the SDK.
+
+### Fixed
+
+- **An MFA-enrolled account could not log in through the SDK.** `LoginResponseSchema` required `sessionToken`, and the API's `200 { mfa_required: true, mfa_challenge_token, ... }` challenge body therefore surfaced as a raw `ZodError` on `sessionToken` — a parse failure on a successful request, with the challenge token discarded. The challenge is now parsed first (narrower literal) and thrown as `MfaRequiredError`; a session body still parses (tested as the control).
+
+### Notes
+
+- Live-verified 2026-09-15 against the current API build on a prod-copy database, not only against nock: member round trip personal → team → personal, `410 PROJECT_REHOMED` at the vacated address on a write (reads there 404 — D14 is a write-path check), `same_org`, the source-scope 404, C6 (owner moving into their own personal org), annihilation on reversal, the D19 feed on both orgs with a non-member `ORG_ACCESS_DENIED` control, and the key→session login ladder. The admin ledger schemas were checked against the controller and nock only — the smoke user was not a platform admin (`INSUFFICIENT_ROLE` on all four, which also fixes the middleware order: platform role before the session gate).
+- Spec §4.1 says the response carries `orgSlug`; the API emits `orgId` and the slug inside `rehome.to_org`. The schema follows the wire; the spec changelog records the drift.
+
+## [6.3.1] - 2026-09-13
+
+### Security
+
+Security audit of the org-routing train (ops-uluops-api run #187, 2026-09-13). None of these was a bypass; each is a channel by which the wrong org could be chosen silently.
+
+- **`resolveWorkspaceOrg` walk is bounded by the home directory** when `cwd` is under it: a `.uluops.json` at `/`, `/Users` or a container root can no longer become the default for every checkout beneath it (the single-default leak D13 exists to remove, one layer down). Outside home the walk still reaches the root. New `home` option (default `os.homedir()`), injectable for tests.
+- **A workspace file owned by another user is refused**, not skipped — the planting vector is a shared parent directory. New `uid` option (default `process.getuid()`; `undefined` disables the check on platforms without uids).
+- **The workspace file's key check is an allowlist** (`org`, `$schema`). It was a ten-name denylist while the error said "may carry only org"; `baseURL`, `apikey`, `token` passed. Inert (only `org` was read), but the stated invariant is now the enforced one.
+- **`"personal"` is honoured as an explicit value** (`resolveWorkspaceOrg({ explicit: 'personal' })`, `withOrg('personal')`): no header, `source: 'explicit'`. It used to go to the wire as a slug (404 `ORG_NOT_FOUND`, or a real org if anyone registers the name). `withOrg('personal')` does not cancel a constructor `orgSlug`.
+- **Per-call org header is set last, and an org header in `options.headers` is refused** on a scoped view. The spread order let a caller header win, and `X-Org-Id` outranks `X-Org-Slug` server-side — no live caller did this; the invariant held by luck.
+
+## [6.3.0] - 2026-09-13
+
+### Added
+
+- **`resolveWorkspaceOrg()` — the D13 workspace default** (project-org-routing-and-rehome spec D13, §2.0). Walks upward from `cwd` to the nearest `.uluops.json` and honours only its `org`; the reserved value `"personal"` stops the walk and means "no org" (a personal repo cloned under a work tree carries it so the outer file does not win). Precedence: `explicit` (a `--org` flag, an MCP tool's `org` argument) > nearest workspace file > `ULUOPS_ORG_SLUG` (kept as the lowest fall-through for headless environments) > personal. Returns `{ org, source, path }` so a caller can print *why* a call landed where it did.
+
+  **The file may carry only `org`.** `apiKey`, `baseUrl`, `profile`, `credentials`, `sessionToken`, `email`, `password` are refused with `InputValidationError`, not ignored — a `.env` in cwd once retargeted the CLI's base URL, and the one guard that keeps that footgun from transferring is that this file cannot name a target or an identity. Malformed JSON and invalid slugs are refused loudly for the same reason: a silently ignored file is a silently wrong org. The slug is server-relative, so "where it landed" output should print the base URL beside the org.
+
+  Lives here, not in each consumer: the CLI and the tracker MCP both need it, and two copies of a walk-up function in two repos are the drift class the spec exists to remove. `findWorkspaceOrgFile` and `readWorkspaceOrgFile` are exported for tooling that wants to explain the answer. `ENV_VARS.ORG_SLUG` added. Tests build their own temp trees and pass `stopAt` so a real `.uluops.json` above the temp dir cannot leak in — this workspace will carry one.
+
+## [6.2.0] - 2026-09-13
+
+### Added
+
+- **Per-call `org` on every project, run, issue and analytics operation** (project-org-routing-and-rehome spec §3.2, D12). Each method on `client.projects`, `client.runs`, `client.issues` and `client.analytics` takes a trailing `options?: { org?: string }` (run writes: `RunCallOptions`, which also carries the existing `_skipClientValidation`). `org` is the target org's slug and becomes `X-Org-Slug` on that one request, overriding the constructor-level `orgSlug`. **Precedence on the wire, lowest to highest: personal org (no header) < constructor `orgSlug` < per-call `org`; an API key BOUND to an org ignores both headers and returns `403 ORG_ACCESS_DENIED` if they name a different org** — the platform's rule, surfaced verbatim. The API never infers an org from a project name (spec D2): a call that names no org creates or targets the *personal* project of that name even when a work org has one by the same name.
+
+  **Mechanism, because it differs from the spec's plan and the difference is worth knowing.** The spec (§3.2) said every operation would migrate from sdk-core's verb helpers to `client.request(..., { headers })`. sdk-core's `get/post/patch/put/delete` all delegate to `this.request`, so instead `OpsHttpClient` overrides `request` and exposes `withOrg(slug)`, a prototype-chained VIEW of the client that merges the header on every request it makes. One seam, zero operation rewrites, and the view shares the root's auth strategy, so a session installed on the root is honoured. `OpsClient` mints the view per call. Same wire contract; the test file asserts on the outgoing request as nock sees it, including a `badheaders` control proving the root client sends no header and that minting a view does not mutate the root.
+
+- **`OpsHttpClient.withOrg(slug)`** and **`scopedOrg`** (read-only, for diagnostics) on the low-level client; `ORG_SLUG_PATTERN` and `ORG_SLUG_HEADER` exported. `withOrg` validates the slug with the same pattern as `orgSlug` and throws `InputValidationError` — it is a header value, so CRLF and whitespace can never reach the wire.
+
+- **Org-routing error codes and type guards**: `INSUFFICIENT_ORG_ROLE` / `isInsufficientOrgRoleError` (403 — below the org's write floor; on tracker writes the API's body carries `details.applied: false` and forbids retrying without `org`: **do not retry the same call org-less — that is not a fallback, it files the work in the caller's personal org**), `ORG_ACCESS_DENIED` / `isOrgAccessDeniedError` (403 — not a member, or a bound key naming another org), and `PROJECT_REHOMED` / `isProjectRehomedError` with `ProjectRehomedDetails` (410 — spec D14: the project this name once denoted in this org now lives in `details.target_org.slug`; pass it as `org` and the same call succeeds). The rehomed guard requires the details shape it promises, not only the code, so a narrowed error is safe to dereference. `InsufficientOrgRoleDetails` declared.
+
+### Changed
+
+- `client.runs.*` write and preview options are typed `RunCallOptions` (`OrgScopedOptions & { _skipClientValidation? }`) instead of the inline `{ _skipClientValidation?: boolean }`. Structurally compatible; nothing a caller wrote breaks.
+
 ## [6.1.0] - 2026-09-10
 
 ### Added
@@ -115,7 +205,9 @@ deploys; SDK 6.0.0 (after the flip) re-pins the new shapes strictly.
 
 ### Added
 
-- **`runs.save()` surfaces the `analysisWrite` confirmation** (tool-sweep T21; API ≥1.71.0).
+- **`runs.save()` surfaces the `analysisWrite` confirmation** (tool-sweep T21; API 2.0.0+, or a
+  1.70.0 deploy after 2026-08-19 — this read "≥1.71.0" until 2026-09-13; no such version was
+  ever declared, see ops-uluops-api issue `aea76608`).
   The save response envelope now carries `analysisWrite` as a sibling of `data` — the same
   placement as the update envelope — read via `rawEnvelope` and returned on the result
   (`analysisWrite: AnalysisWriteEcho | null`; `recordMode: 'initial'` on this path). Like the

package/README.md

@@ -95,6 +95,8 @@ for (const [domain, trend] of Object.entries(burndown.trends)) {
   - [Issue Operations](#issue-operations)
   - [Analytics Operations](#analytics-operations)
   - [Taxonomy Operations](#taxonomy-operations)
+  - [Org Operations](#org-operations)
+  - [Admin Operations](#admin-operations)
   - [Health Check](#health-check)
 - [Environment Variables](#environment-variables)
 - [Error Handling](#error-handling)
@@ -170,7 +172,7 @@ console.log(client.getAuthType()); // 'api_key'
 
 ### Session-Based Authentication
 
-For interactive applications, use `client.login()` which automatically configures token auto-refresh:
+For interactive applications, use `client.login()` which installs the session and, by default, re-logs in on a 401:
 
 ```typescript
 import { OpsClient } from '@uluops/ops-sdk';
@@ -192,6 +194,43 @@ await client.logout();
 
 > **Note:** Prefer `client.login()` over `client.auth.login()`. The latter only returns the token without installing it, requiring manual client construction.
 
+**Accounts with MFA (6.4.0).** For an account with TOTP or a passkey enrolled, `POST /auth/login`
+answers a *challenge*, not a session, and `client.login()` throws `MfaRequiredError` carrying
+`mfaChallengeToken`, `expiresAt` and `mfaMethods`. Complete it with the current code:
+
+```typescript
+import { isMfaRequiredError } from '@uluops/ops-sdk';
+
+try {
+  await client.login(email, password);
+} catch (err) {
+  if (!isMfaRequiredError(err)) throw err;
+  await client.loginWithTotp(err.mfaChallengeToken, '123456'); // installs the session
+}
+```
+
+**The challenge token is single-use and is consumed before the code is checked** — a mistyped
+code burns it; do not loop on `loginWithTotp` with the same token, call `login()` again for a fresh
+challenge. A TOTP-installed session has no password to re-login with, so it is **not**
+auto-refreshed: when it expires, requests fail `401` and you log in again. (Before 6.4.0 an MFA
+account could not log in through `login()` at all — the challenge body failed the session schema
+with a `ZodError`.) `MfaRequiredError` is raised by `login()` / `auth.login()` **only**: a client
+constructed with `{ email, password }` (or autoloaded credentials) logs in inside sdk-core, which
+cannot see the challenge and surfaces a generic `UnauthorizedError` — MFA accounts must use the
+two-step path. WebAuthn completion is not offered here.
+
+**What "auto-refresh" does — read before scripting against a session.** With the default
+`login()`, the password is kept so sdk-core can re-login when a request answers 401. That refresh
+is a *fresh login*: under the API's default single-session policy it **revokes the user's other
+sessions** (your dashboard tab); **mutations are not retried** afterwards (the POST that hit the 401
+still throws it); and the budget is **one** (the password is cleared after the first re-login).
+For a script — the Phase 4 migration, anything that shares the account with a dashboard — pass
+`{ autoRefresh: false }` so a 401 means *stop*, untouched:
+
+```typescript
+await client.login(email, password, { autoRefresh: false }); // session without a password → no re-login
+```
+
 ### Credential Priority Chain
 
 The SDK loads credentials in the following order:
@@ -307,7 +346,8 @@ const client = new OpsClient({
   debug: false,                // Enable debug logging
 
   // Multi-tenancy
-  orgSlug: 'my-org',           // Org slug (sets X-Org-Slug header on all requests)
+  orgSlug: 'my-org',           // Org slug (sets X-Org-Slug header on all requests);
+                               // any method's trailing `{ org }` overrides it per call
 
   // Callbacks
   onTokenRefresh: (token) => { /* handle token refresh */ },
@@ -321,6 +361,47 @@ const client = new OpsClient({
 });
 ```
 
+#### Org routing — which org a call lands in
+
+Every project, run, issue and analytics method takes a trailing `options` with `org?: string`
+(run writes: `RunCallOptions`, which also carries `_skipClientValidation`). It becomes the
+`X-Org-Slug` header on that one request.
+
+```typescript
+await client.runs.save(input, { org: 'ulu-labs' });          // this call → ulu-labs
+await client.projects.list({ org: 'ulu-labs' });               // reads take it too
+await client.projects.list();                                  // → constructor orgSlug, else your personal org
+```
+
+**Precedence on the wire, lowest to highest:** personal org (no header) < constructor `orgSlug`
+< per-call `org`. An API key **bound** to an org ignores both headers and answers
+`403 ORG_ACCESS_DENIED` if they name a different org. The API never infers an org from a project
+name: a call that names no org creates or targets the *personal* project of that name, even when
+a work org has one by the same name (spec D2). Name the org.
+
+Three org-routing errors are worth branching on (all exported with type guards):
+
+| Code | Status | Guard | What to do |
+|---|---|---|---|
+| `INSUFFICIENT_ORG_ROLE` | 403 | `isInsufficientOrgRoleError` | Your role in that org is below `publisher`. **Do not retry without `org`** — an org-less retry files the work in your personal org; the API says so in the body (`details.applied: false`). |
+| `ORG_ACCESS_DENIED` | 403 | `isOrgAccessDeniedError` | Not a member of that org, or your key is bound to a different one. Terminal. |
+| `PROJECT_REHOMED` | 410 | `isProjectRehomedError` | The project moved orgs. `err.details.target_org.slug` is where it lives — pass it as `org` and retry the same call. |
+| `SESSION_REQUIRED` | 403 | `isSessionRequiredError` | A session-only admin route refused an API key (D20). Log in; never mint another key to get past it. |
+| `INSUFFICIENT_ROLE` | 403 | `isInsufficientRoleError` | The admin path needs the *platform* role (`users.role = admin`); no `org` argument changes it. Terminal. |
+
+Low-level: `new OpsHttpClient(cfg).withOrg('acme')` returns a view of the client scoped to that org.
+
+**Where does the default come from?** For tools that run inside a checkout (the CLI, the tracker
+MCP), `resolveWorkspaceOrg({ explicit, cwd })` implements the spec's D13 rule: an explicit value
+wins; else the nearest `.uluops.json` above `cwd` (`{ "org": "ulu-labs" }`, or `{ "org": "personal" }`
+to stop the walk in a personal repo nested under a work tree); else `ULUOPS_ORG_SLUG`; else your
+personal org. The file may carry only `org` (and `$schema`) — any other key is refused, not ignored.
+Two more refusals since 6.3.1 (security audit run #187): the walk never rises above your home
+directory (a file at `/` or `/Users` cannot become everyone's default), and a file owned by another
+user is refused (a shared parent directory is the planting vector). `"personal"` is also honoured as
+an explicit value — `{ org: 'personal' }` sends no header. On a scoped call the per-call org header
+is set last and an `X-Org-Slug`/`X-Org-Id` in `options.headers` is refused.
+
 ---
 
 ### Security Events
@@ -769,6 +850,52 @@ const result = await client.projects.mergeIssues('my-project', {
 });
 ```
 
+#### `client.projects.rehome(idOrName, input, options?)` — move a project to another org
+
+Moves the project and its whole history (runs, issues, analytics) into another org
+(project-org-routing-and-rehome spec §4.1, D14). **The source org is this call's org scope** —
+pass `{ org: '<source>' }` (or set the client `orgSlug`) unless the project is in your personal
+org; the project is looked up *there*, and an unscoped call for a work-org project is a 404. You
+need `admin`/`owner` in both orgs; a personal org as *target* only when it is yours.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `targetOrg` | `string` | Yes | Slug of the destination org |
+| `reason` | `string` | No | ≤ 500 chars; stored on the tombstone, never rendered into an error |
+
+```typescript
+const moved = await client.projects.rehome('billing', { targetOrg: 'ulu-labs', reason: 'team took it over' }, { org: 'acme' });
+moved.orgId;               // the target org's id
+moved.rehome.from_org;     // { id, slug: 'acme' }
+moved.rehome.to_org;       // { id, slug: 'ulu-labs' }
+moved.rehome.audit_ids;    // [] today — the ledger, not this array, is the durable record
+```
+
+After the move the old `(org, name)` address is a **tombstone**: an org-less *write* naming the
+project there (a `save` or a `create`) gets `410 PROJECT_REHOMED` naming the target
+(`isProjectRehomedError`) instead of silently forking a new project. Reads at the old address 404.
+Moving back is an ordinary `rehome` the other way and annihilates the tombstone.
+
+Refusals a caller branches on — `rehomeRefusalReason(err)` reads the enumerated
+`details.reason` values and returns `null` for anything else:
+
+| Answer | Meaning | Disposition |
+|---|---|---|
+| `400` `same_org` | already there | done (idempotent re-run) |
+| `409` `moved_during_request` / `deadlock_retry` / `concurrent_modification` | lost a race | re-read, retry once |
+| `409` `name_collision` / `soft_deleted_conflict` / `rehomed_away_conflict` | the name is taken in the target (live, soft-deleted, or reserved by another move) | skip and report |
+| `409` `export_in_progress` | an export holds one of the orgs | wait, retry |
+| `409` `project_soft_deleted` | the project is soft-deleted in the source | restore it there first, then move |
+| `400` `project_has_no_org` | pre-org legacy row | stop; an operator repairs the row |
+| `403` `INSUFFICIENT_ORG_ROLE` / `ORG_ACCESS_DENIED` / `ORG_SUSPENDED` | authority (source role, target membership or a personal target, C3) | stop |
+| `402` `PROJECT_LIMIT` | target org at its project cap | stop |
+| *no HTTP answer* (`isTimeoutError` / `isNetworkError`; `rehomeRefusalReason` → `null`) | the server may have committed the move before the response was lost | do **not** retry blind — read the project with `{ org: targetOrg }` (or the admin ledger); on the member path a blind retry is a 404, not `same_org` |
+
+**Re-runs.** `same_org` is the idempotence signal of the **admin** path (lookup by id, unscoped).
+On the member path the lookup is source-scoped, so the same call after the move answers **404**
+(the source address is a tombstone) — not `same_org`. A member-path script that wants "already
+done" checks the target org, not the refusal code.
+
 ---
 
 ### Run Operations
@@ -1783,6 +1910,108 @@ console.log('Priorities:', taxonomy.priorities);
 
 ---
 
+### Org Operations
+
+Reads any **member** of an org can make. (Org CRUD, membership and invitations are dashboard
+surfaces and are not wrapped by this SDK.)
+
+#### `client.orgs.getVisibleAuditLog(slug, query?)` — the org-visible audit feed (D19)
+
+The subset of an org's audit log that any member may read: rows whose writer marked
+`details.visibility = 'org'`. Today that is one class — a project **leaving this org for someone's
+personal org** (an org admin may do that; before D19 the org's owner could not see it). The full
+audit log stays admin+ and is not wrapped here.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `cursor` | `string` | Opaque keyset cursor — pass a prior page's `nextCursor` back verbatim |
+| `limit` | `number` | Page size, 1–100 — the API answers 400 outside that range (it does not clamp) |
+
+```typescript
+import { readRehomeAuditDetails } from '@uluops/ops-sdk';
+
+const feed = await client.orgs.getVisibleAuditLog('acme', { limit: 50 });
+for (const entry of feed.data.entries) {
+  const move = readRehomeAuditDetails(entry);      // null for rows written by anything else
+  if (move) console.log(`${move.project_name}: ${move.from_org.slug} → ${move.to_org.slug} (${move.action})`);
+}
+// feed.count is the page size, feed.hasMore / feed.nextCursor page it
+```
+
+`action` on every row is the platform's closed enum (`org.updated`); the real event is
+`details.action` (`project.rehome_out` on the source org's feed, `project.rehome_in` on the
+target's). A non-member gets `403 ORG_ACCESS_DENIED`.
+
+---
+
+### Admin Operations
+
+The **platform-admin** surface (`users.role = 'admin'` — a platform role, not an org role). The two
+writes additionally require a **login-issued session**: an API key, even an admin's, answers
+`403 SESSION_REQUIRED` (`isSessionRequiredError`) — that is D20, the compensation for a stolen
+admin key being able to move any project anywhere in one call. Log in with `client.login()` (and
+`loginWithTotp()` if challenged) and the session bearer is what these calls send. A non-admin
+principal gets `403 INSUFFICIENT_ROLE` on all four. There is deliberately no MCP tool for any of
+this.
+
+#### `client.admin.rehomeProject(projectId, { targetOrg, reason })` — session only
+
+Move **any** project between **any** two orgs by UUID; no source- or target-membership
+requirement, so `reason` is **required** (on this path the target org's only standing is the audit
+row plus that text). Resolves the project unscoped — the route takes a UUID and the SDK refuses a
+name client-side (`InputValidationError`). Answers the same refusals as the member path; here
+`same_org` does mean "already done" (the lookup is by id, so the moved project is found wherever
+it is), which is what makes a scripted pass over a list idempotent.
+
+```typescript
+await client.login(email, password, { autoRefresh: false });   // or loginWithTotp(...) after an MfaRequiredError
+try {
+  const moved = await client.admin.rehomeProject(projectId, { targetOrg: 'ulu-labs', reason: 'OQ-4 row 7' });
+  console.log(moved.rehome.from_org.slug, '→', moved.rehome.to_org.slug);
+} catch (err) {
+  if (rehomeRefusalReason(err) === 'same_org') { /* done on a previous run */ }
+  else throw err;
+}
+```
+
+#### `client.admin.listProjectRehomes(query?)` — key-readable
+
+The **current redirect table**: one row per vacated `(sourceOrgId, name)` and the `targetOrgId` it
+points at. A reversal annihilates its row and a release deletes it, so this is state, not history.
+`org` takes a UUID or a slug; `total` is the matching count and `returned` the page.
+
+```typescript
+const { data, total } = await client.admin.listProjectRehomes({ org: 'system', limit: 100 });
+// data[0] → { id, sourceOrgId, name, projectId, targetOrgId, actorId, reason, createdAt }
+```
+
+#### `client.admin.listProjectRehomeEvents(query?)` — key-readable
+
+The **append-only ledger** (D21): every `moved`, `repointed`, `annihilated`, `degenerate_dropped`,
+`released` and `hard_deleted` event, written in the same transaction as the change; nothing the API
+offers removes a row. Pages by `seq` (insertion order) — `nextCursor` is the `seq` to continue
+below; pass it back verbatim. **Reconcile a migration against this**, not against the reservation
+table and not against the script's own log. Unknown future event kinds parse verbatim
+(`PROJECT_REHOME_EVENT_KINDS` lists the known six).
+
+```typescript
+const page = await client.admin.listProjectRehomeEvents({ org: 'ulu-labs', event: 'moved', limit: 100 });
+page.data[0]; // { seq, event, projectId, projectName, fromOrgId, toOrgId, viaAdminPath, reason, createdAt, ... }
+```
+
+#### `client.admin.releaseProjectRehome(rehomeId)` — session only
+
+Release a vacated address so the old `(org, name)` is creatable again — a by-name writer there then
+gets a **new** project instead of a 410. Audited (a `released` ledger row); never done by time.
+
+```typescript
+await client.admin.releaseProjectRehome(reservationId); // → { released: true }
+```
+A `ZodError` here means the 200 body was not `{ released: true }` — and since the server answers
+after the row is gone, the release most likely happened; re-read the listing before retrying.
+
+---
+
 ### Health Check
 
 Check API server status. This endpoint does not require authentication.