diff --git a/.changeset/admin-search-cap-446.md b/.changeset/admin-search-cap-446.md
new file mode 100644
index 00000000..d648042b
--- /dev/null
+++ b/.changeset/admin-search-cap-446.md
@@ -0,0 +1,5 @@
+---
+"ornn-api": patch
+---
+
+Add `maxTimeMS` + ensure indexes on admin skill search (#446). `GET /admin/skills?q=…` ran an escaped `$regex` against `name` and `description` with no time cap and no documented indexes — a crafted partial-match query on a large collection could pin a Mongo node's CPU indefinitely. Adds a 5 s `maxTimeMS` to both `countDocuments` + `find`, and a new `SkillRepository.ensureIndexes()` (wired into bootstrap) that creates `name` (unique), `description`, `createdBy + createdOn`, `createdOn`, and `isPrivate + createdOn` indexes — partial-regex still can't use a btree, but the secondary filters (`createdBy=…`, `isPrivate=…`) and the `createdOn` sort now hit indexes instead of a full collection scan.
diff --git a/.changeset/admin-settings-zod-actionable-698.md b/.changeset/admin-settings-zod-actionable-698.md
new file mode 100644
index 00000000..5a42ae68
--- /dev/null
+++ b/.changeset/admin-settings-zod-actionable-698.md
@@ -0,0 +1,19 @@
+---
+"ornn-web": patch
+---
+
+`useSectionForm` validation errors now include the offending field path and rephrase length-1 string failures as "is required" instead of the raw `Too small: expected string to have >=1 characters` (#698).
+
+The shared admin-settings form hook joined `i.message` only when surfacing Zod validation issues. The Mirror section (and every other section that uses `.min(1)` as a required-field gate) ended up emitting a single SectionShell alert that read like:
+
+> Too small: expected string to have >=1 characters; Too small: expected string to have >=1 characters; Too small: expected string to have >=1 characters; ...
+
+— with no indication of which fields needed filling.
+
+Fix: prefix each issue with `path.join(".")`, and for the specific `code: "too_small"` + `type: "string"` + `minimum: 1` triple swap the message to `is required`. Renders as:
+
+> owner: is required; repo: is required; branch: is required; appId: is required; installationId: is required; appPrivateKey: is required
+
+— actionable from the alert alone, no schema-by-schema rewrite needed.
+
+Per-section schemas can still ship their own friendlier messages (`.min(1, "Owner is required")`) — those flow through `i.message` unchanged.
diff --git a/.changeset/admin-user-search-display-name-587.md b/.changeset/admin-user-search-display-name-587.md
new file mode 100644
index 00000000..68350b2b
--- /dev/null
+++ b/.changeset/admin-user-search-display-name-587.md
@@ -0,0 +1,13 @@
+---
+"ornn-api": patch
+---
+
+Admin Users search now matches display name as well as email (#587).
+
+The search input's placeholder said "email or display name" but the Mongo filter only matched `email` with an anchored-prefix regex. Display names + display-name substrings were silently ignored, so admins typing `Haylee01` or `Proxy` got empty result lists even though those users existed.
+
+Fix is additive — the email behaviour is preserved (still an anchored, case-insensitive prefix match), and a case-insensitive **substring** match on `displayName` is OR'd in alongside it. Display names don't have a meaningful prefix (the issue's reproducer was `Proxy` matching `Ornn Local Proxy`), so substring is the right shape.
+
+Both the unbounded `findAllInRole` (the admin dashboard's paginated-in-memory path) and the paginated `listUsers` (the page-then-fetch path) use the same `buildUserSearchFilter` helper so they stay in sync.
+
+Regex metacharacters in the query are escaped, same as before — pinned with a new test so the escape stays in place.
diff --git a/.changeset/agentseal-path-validation-442.md b/.changeset/agentseal-path-validation-442.md
new file mode 100644
index 00000000..02013b20
--- /dev/null
+++ b/.changeset/agentseal-path-validation-442.md
@@ -0,0 +1,11 @@
+---
+"ornn-api": patch
+---
+
+Harden the AgentSeal subprocess (#442). Two defensive changes, both small.
+
+**Boot-time path validation.** `AgentSealScanner`'s constructor now refuses `python` / `script` config values that aren't absolute paths to existing regular files. Closes a lateral-movement gap: if scanner config ever sourced from a less-trusted place (admin-editable UI, env that picks up `PATH`), `spawn("python", ...)` would silently resolve against `$PATH` and let an attacker swap in any binary they could plant on the search path. Validation only fires when `enabled: true`, so dev/test envs that don't have agentseal installed can boot fine. New `AGENTSEAL_ENABLED=false` env flag toggles the whole scanner (default `true`).
+
+**Unref child after kill.** When the subprocess hits the timeout and we send SIGTERM / SIGKILL, we now also call `child.unref()` so the killed process can no longer keep the API event loop alive during shutdown. Previously, a scanner mid-flight when the API received SIGTERM could delay graceful shutdown by up to `timeoutMs + 1s`.
+
+Tests: 6 new assertions on the path validator (relative rejected, missing rejected, directory rejected, disabled skips validation, happy path constructs, helper unit-tested). Existing subprocess tests adjusted to use a real on-disk dummy script.
diff --git a/.changeset/api-stability-doc-474.md b/.changeset/api-stability-doc-474.md
new file mode 100644
index 00000000..70423e7e
--- /dev/null
+++ b/.changeset/api-stability-doc-474.md
@@ -0,0 +1,4 @@
+---
+---
+
+Publishes `docs/API_STABILITY.md` (#474) — the public stability commitment for `/api/v1/*`. Codifies the alpha caveat, the post-v1 semver policy, three stability tiers (`stable` / `beta` / `experimental` declared via OpenAPI `x-stability`), and the deprecation policy (RFC 8594 headers, two-minor-release lead time, signal channels, breaking-change checklist). Linked from README docs section; `CONVENTIONS.md §7` cross-links here.
diff --git a/.changeset/apidelete-dedup-578.md b/.changeset/apidelete-dedup-578.md
new file mode 100644
index 00000000..c8ff881b
--- /dev/null
+++ b/.changeset/apidelete-dedup-578.md
@@ -0,0 +1,5 @@
+---
+"ornn-web": patch
+---
+
+Route `apiDelete` through `fetchWithRetry` (#578) so the proactive-refresh / 401-retry / redirect-to-login logic lives in one place instead of being copy-pasted between `GET/POST/PATCH/PUT` and DELETE. Behaviour-equivalent: DELETE still proactively refreshes, retries once on 401, redirects to `/login` if refresh fails, and surfaces non-2xx responses as `ApiClientError`. Only observable difference is the default error code on bodyless failures is now `UNKNOWN_ERROR` instead of `DELETE_FAILED` — that string was a dead default, no caller checks it.
diff --git a/.changeset/audit-rerun-silent-fail-718.md b/.changeset/audit-rerun-silent-fail-718.md
new file mode 100644
index 00000000..90ddc150
--- /dev/null
+++ b/.changeset/audit-rerun-silent-fail-718.md
@@ -0,0 +1,11 @@
+---
+"ornn-web": patch
+---
+
+Skill Detail now surfaces a "latest rerun failed" indicator next to the score so a failed audit rerun is no longer invisible (#718).
+
+Background: `auditSummaryByVersion` returns the latest *completed* audit per version. When a rerun ends in `failed`, the summary still points at the previous successful record, and Skill Detail renders that stale score — visually identical to "current passing audit". Admins only discovered the failure by opening Audit History.
+
+Fix: `useSkillDetail` already loads `versionAuditHistory` (newest-first across all statuses) to compute `versionAuditRunning`. Compute one more derived flag from it — `versionAuditLatestFailed = history[0].status === "failed" && newer than the displayed completed audit` — and thread it through to `AuditVerdictPill` as the new `latestRerunFailed` prop. The pill keeps the old completed score (so admins can still see the last-good number) and renders a danger-toned banner directly below: "Latest rerun failed — score above is from the prior audit. Check audit history for details." (`skillDetail.auditLatestFailed`).
+
+No backend change. The shape `getAudit` returns is unchanged — the gap was that the *latest-of-any-status* signal was already in hand and just wasn't propagated.
diff --git a/.changeset/bare-catch-sweep-579.md b/.changeset/bare-catch-sweep-579.md
new file mode 100644
index 00000000..dd54a4c8
--- /dev/null
+++ b/.changeset/bare-catch-sweep-579.md
@@ -0,0 +1,9 @@
+---
+"ornn-api": patch
+---
+
+Audit + tighten the 31 bare `catch {}` blocks across `ornn-api/src` (#579).
+
+Critical-path catches that swallowed errors silently now capture the error and emit `logger.debug({ err }, '…')` — analytics dispatch, NyxID org lookups, audit-bundle reads, audit-JSON parse, package-parse on source-refresh, optional JSON-array form fields, generation-context binary skips, LLM output parse, GitHub URL parse. Caller behavior is unchanged (still returns null / falls back to defaults), but a misconfigured or broken upstream is now observable in logs instead of hidden behind an empty result set.
+
+The catches that already logged, already rethrew as `AppError`, or where the return value IS the signal (validation result, violation list, parse-failure fallback) are left alone. Each one that stays silent on purpose now carries a one-line comment explaining why, so a future reader doesn't re-flag it.
diff --git a/.changeset/bootstrap-decompose-580.md b/.changeset/bootstrap-decompose-580.md
new file mode 100644
index 00000000..21ea6e6c
--- /dev/null
+++ b/.changeset/bootstrap-decompose-580.md
@@ -0,0 +1,25 @@
+---
+"ornn-api": patch
+---
+
+Decompose `bootstrap.ts` per-domain (#580).
+
+Lifts 10 leaf domains' wiring out of the 1089-line `bootstrap.ts` monolith into per-domain `bootstrap.ts` modules. Each one exports a `wire{Domain}({ db, logger, ...deps })` function that bundles repo construction + `ensureIndexes()` fire-and-forget catch + any one-shot boot migration + service construction + routes construction into a single call. The orchestrator stays in charge of *ordering* and shared client construction; the per-domain *detail* moves out.
+
+Domains extracted:
+
+- announcements
+- analytics
+- quota (consumed by playground / skill-gen / admin)
+- redemption-codes (admin + me route surfaces, shared service for atomic pivot consistency)
+- broadcasts (2-step: shared repo first, then service + routes)
+- notifications (consumes shared broadcasts repo for the merged feed)
+- platform settings (legacy single-doc surface)
+- admin (dashboard + users + quota admin)
+- skill search
+- skill generation
+- playground
+
+What's still inlined: skills CRUD, skill audit, GitHub mirror, settings export/import, and `createAdminRoutes` (skill / generation / agentseal admin). These have heavier cross-cutting dependency lists (scheduler lifecycle, audit fan-out, analytics emitter closures) — extracting them cleanly needs a follow-up.
+
+bootstrap.ts: **1089 → 970 lines** (-11%, -119 lines net). No behavioral change — boot order is preserved, all 798 tests still pass.
diff --git a/.changeset/chat-events-zod-449.md b/.changeset/chat-events-zod-449.md
new file mode 100644
index 00000000..65eff755
--- /dev/null
+++ b/.changeset/chat-events-zod-449.md
@@ -0,0 +1,5 @@
+---
+"ornn-api": patch
+---
+
+Type-check playground LLM stream events with a Zod discriminated union (#449). `chatService` previously read `event.type`, `event.delta`, `event.item` via `as any` — a runtime no-op that let upstream field renames silently propagate `undefined` through the SSE stream to clients. Three permissive schemas (`response.output_text.delta`, `response.content_part.delta`, `response.output_item.done`) now gate every event; unknown shapes are dropped with a debug log so the upstream API can add fields freely without breaking us.
diff --git a/.changeset/chat-input-length-cap-654.md b/.changeset/chat-input-length-cap-654.md
new file mode 100644
index 00000000..787bde79
--- /dev/null
+++ b/.changeset/chat-input-length-cap-654.md
@@ -0,0 +1,26 @@
+---
+"ornn-web": patch
+"ornn-api": patch
+---
+
+Chat composer length cap + counter (#654).
+
+The Playground + AI-generation chat composer accepted prompts of any length — the live reproducer was 24 000 chars typed, send button still enabled, no warning. Backend caps existed only for message *count* (100), never message *content*.
+
+Front-end (`ChatInput.tsx`):
+
+- `maxLength={32_000}` on the textarea — browser-side hard cap on typing / paste.
+- Live `<used> / <max>` counter appears once the input crosses 24 000 chars (75 %); stays hidden below that so the composer isn't chromed for normal use.
+- Counter flips danger-tone + send button disables when content is over the cap (defensive — `maxLength` should make this unreachable, but covers IME / non-browser-paste edge cases).
+- Imperative `setValue` (used by suggestion-prompt clicks) truncates past the cap so curated copy can't bypass the limit silently.
+
+Back-end:
+
+- `playgroundMessageSchema.content` adds `.max(MAX_CHAT_MESSAGE_CHARS)` — rejects with `400 content_too_long` (RFC 7807 envelope).
+- `skills/generation` JSON path validates prompt length AND each multi-turn message's content length symmetrically — rejects with `400 prompt_too_long` or `400 content_too_long`.
+
+The 32 000-char ceiling is `~8k tokens` at 4 chars/token. Generous for interactive prompts without enabling whole-novel pastes; the three constants are deliberately duplicated across `ChatInput.tsx`, `playground/routes.ts`, and `skills/generation/routes.ts` with cross-referencing comments so a change in one stays in step with the others.
+
+Pinned with `ChatInput.test.tsx` (7 assertions covering `maxLength` attribute, counter visibility, send-enable / disable, imperative truncate, empty disabled).
+
+Closes #654.
diff --git a/.changeset/codecov-471.md b/.changeset/codecov-471.md
new file mode 100644
index 00000000..54537cf3
--- /dev/null
+++ b/.changeset/codecov-471.md
@@ -0,0 +1,4 @@
+---
+---
+
+Codecov integration + coverage badge (#471). CI now runs `bun test --coverage` (per-workspace lcov) and `pytest --cov` (sdk/python coverage.xml) and uploads both via `codecov/codecov-action@v4` — separate `bun` / `python` flags so a regression in one language is obvious. New `codecov.yml` commits to a realistic 70% project / 80% patch target and excludes the four god-files awaiting decomposition (SkillDetailPage, DocsPage, PlaygroundPage, bootstrap.ts) so the headline number reflects code that's reasonably testable today. README gains the Codecov badge.
diff --git a/.changeset/concurrent-token-refresh-dedup-631.md b/.changeset/concurrent-token-refresh-dedup-631.md
new file mode 100644
index 00000000..01c9e4b9
--- /dev/null
+++ b/.changeset/concurrent-token-refresh-dedup-631.md
@@ -0,0 +1,19 @@
+---
+"ornn-web": patch
+---
+
+Deduplicate concurrent NyxID token-refresh requests (#631).
+
+`authStore.refreshToken()` could fire 2–4 times within the same millisecond — `apiClient.fetchWithRetry`'s proactive `ensureFreshToken()`, its reactive 401-retry path, the scheduled `startTokenRefresh` `setTimeout`, and the `visibilitychange` handler all converge near the expiry boundary. Each fired its own `POST /oauth/token` with `grant_type=refresh_token`.
+
+NyxID rotates the refresh token on every successful exchange. The second concurrent caller therefore lost the rotation race and got:
+
+```json
+{"error":"invalid_request","error_description":"Conflict: Refresh token was concurrently rotated, please retry"}
+```
+
+…which the SPA's `refreshToken` `catch` interpreted as a hard failure: it nulled the access + refresh tokens and surfaced an unexpected logout. Users observed it as "I came back to the tab and got logged out".
+
+Fix funnels every caller through a single `_refreshInFlight: Promise<void> | null` slot on the store. The first caller stores the promise; subsequent callers `await` the same one. The slot is cleared in `finally` so a later (truly new) refresh starts fresh.
+
+Slot is excluded from `partialize` — Promises aren't serialisable and the dedup window only matters within a tab's lifetime.
diff --git a/.changeset/cors-cleanup-528.md b/.changeset/cors-cleanup-528.md
new file mode 100644
index 00000000..d8bf54b8
--- /dev/null
+++ b/.changeset/cors-cleanup-528.md
@@ -0,0 +1,13 @@
+---
+"ornn-web": patch
+---
+
+Remove dead `X-User-*` headers from skill-create + activity log (#528).
+
+`createSkill` (POST /api/v1/skills — used by Free / Guided / AI-generated save) and `logActivity` (POST /api/v1/activity/login|logout) still attached `X-User-Email` / `X-User-Display-Name` headers, leftover from a pre-NyxID-proxy auth model where the backend read identity off these headers. The backend hasn't read them in months (identity comes from the proxy-forwarded JWT), and the `apiClient.createHeaders` cleanup that struck the same code from the shared client missed these two raw-`fetch` callers.
+
+Sending them caused the browser's CORS preflight to ask permission for `X-User-Email` and `X-User-Display-Name`. The backend CORS allowlist is `["Content-Type", "Authorization"]` (`bootstrap.ts:744`), so the preflight response didn't include those headers — the browser then blocked the actual `POST` with a CORS error. End user sees: "Save Skill" never completes, DevTools shows preflight `204` then a `CORS error` on the real request.
+
+Net change: both callers now send only `Content-Type` + `Authorization` (matching the rest of the SDK), the preflight allow-headers list is fully satisfied, and the real request goes through.
+
+This is the definitive fix for the `POST /skills` case. The `PUT /skills/:id` case tracked in #565 doesn't send `X-User-*` itself, but the parallel login-time `logActivity` failure here was producing a CORS-error toast that could be misattributed to the in-flight PUT — worth re-verifying #565 after this lands.
diff --git a/.changeset/cursor-pagination-457-465.md b/.changeset/cursor-pagination-457-465.md
new file mode 100644
index 00000000..83395a3a
--- /dev/null
+++ b/.changeset/cursor-pagination-457-465.md
@@ -0,0 +1,32 @@
+---
+"ornn-api": minor
+"@chronoai/ornn-sdk": minor
+---
+
+Cursor pagination on `/skill-search` per CONVENTIONS.md §4.3 + SDK auto-pagination iterator (#457 + #465).
+
+**API (`/api/v1/skill-search`)**
+
+- Accepts `?cursor=<opaque-base64>` (alongside the existing `?page=N`). When both are sent, `cursor` wins.
+- Accepts `?limit=N` as an alias for the existing `?pageSize=N`.
+- Response now carries a `meta` envelope: `{ data: { items, total, page, pageSize, totalPages, meta: { limit, hasMore, nextCursor? } }, error }`. The legacy fields stay until they're sunset — clients can migrate at their own pace.
+- A malformed cursor returns `400 invalid_cursor` (RFC 7807 problem+json) instead of silently falling back to page 1.
+- Cursor payload is server-internal (`{ page: number }` today, `lastSort` keyset in a future PR) — clients MUST treat it as opaque.
+
+**SDK (`@chronoai/ornn-sdk`)**
+
+- `client.search()` now accepts `cursor` + `limit` params (additive).
+- New `client.searchAll({ q })` returns an `AsyncIterableIterator<SkillSummary>`. Threads `meta.nextCursor` automatically; terminates on `hasMore === false` or no more cursor. 10k-page safety cap.
+
+```ts
+for await (const skill of client.searchAll({ q: "pdf" })) {
+  console.log(skill.name);
+}
+```
+
+**Out of scope (follow-up)**
+
+- Real lastSort keyset cursor under the hood — current cursor encodes `{ page }` so the wire contract conforms to §4.3 while the underlying query stays offset-based. Switching the payload is invisible to clients.
+- Cursor support on other list endpoints (categories, tags, users) — those keep their existing offset shape for now.
+- Python SDK `search_all()` — follow-up.
+- `Sunset:` header on the legacy `page`/`pageSize` shape — once cursor adoption is high enough.
diff --git a/.changeset/delete-dead-skill-repo-577.md b/.changeset/delete-dead-skill-repo-577.md
new file mode 100644
index 00000000..f4988279
--- /dev/null
+++ b/.changeset/delete-dead-skill-repo-577.md
@@ -0,0 +1,5 @@
+---
+"ornn-api": patch
+---
+
+Delete dead `domains/skills/crud/repositories/` subdirectory (#577) — a 218-line `SkillRepository` impl + interface + test that no route, service, or test outside the directory itself imported. The live skill repository (915 lines) lives at `domains/skills/crud/repository.ts` and is unaffected.
diff --git a/.changeset/dist-tags-463.md b/.changeset/dist-tags-463.md
new file mode 100644
index 00000000..0e6c4e46
--- /dev/null
+++ b/.changeset/dist-tags-463.md
@@ -0,0 +1,29 @@
+---
+"ornn-api": minor
+---
+
+Add dist-tags for skill versions (#463). Lets callers pin to a stable channel without enumerating versions or hard-coding numbers, matching the shape npm / yarn / pnpm exposes.
+
+**New surface**
+
+```http
+GET    /api/v1/skills/{idOrName}/dist-tags           → { tags: { latest, stable, ... } }
+PUT    /api/v1/skills/{id}/dist-tags/{tag}           Body: { version }
+DELETE /api/v1/skills/{id}/dist-tags/{tag}
+GET    /api/v1/skills/{idOrName}?version=@stable     → resolves via dist-tag
+```
+
+`SkillDetailResponse` now carries a `distTags` field on every read.
+
+**Semantics**
+
+- `latest` is **auto-managed**. Every successful publish sets `distTags.latest = newVersion`. `PUT` / `DELETE` against `latest` return 400 `dist_tag_immutable`.
+- Custom tags (`stable`, `beta`, `rc-1`, ...) are owner-managed. Tag names match `/^[a-z][a-z0-9-]{0,49}$/` — npm rules, leading letter required so tags don't look like version numbers.
+- Setting a tag for a non-existent version returns 404 `skill_version_not_found`.
+- `?version=@latest` falls back to `skill.latestVersion` on legacy skills predating this PR so the resolution path stays compatible.
+
+**Out of scope**
+
+- TS / Python SDK helper methods around dist-tags — the endpoints work directly via the raw client. SDK convenience wrappers ride in a follow-up so this PR stays scoped.
+- OpenAPI spec entries for the new paths — `/api/v1/openapi.json` is already incomplete for `/skills/:id/*` write paths; the bigger contract-test pass in #462 will pick all of them up at once.
+- schemastore-style schema for the dist-tag write body (not visible in any IDE flow today).
diff --git a/.changeset/docker-compose-466.md b/.changeset/docker-compose-466.md
new file mode 100644
index 00000000..8bf3b004
--- /dev/null
+++ b/.changeset/docker-compose-466.md
@@ -0,0 +1,14 @@
+---
+"ornn-api": patch
+"ornn-web": patch
+---
+
+Ship a `docker-compose.yml` for one-command local dev (#466). Brings up MongoDB, MinIO, `ornn-api`, and `ornn-web` in a single `docker compose up`. README's new "Run Ornn locally (5 minutes)" section and `CONTRIBUTING.md`'s rewritten "Getting set up" tier the prerequisites by what each contributor actually needs:
+
+- **Unit tests / lint / typecheck:** just Bun + Docker.
+- **Running the services:** `docker compose up`.
+- **Full integration with NyxID / chrono-storage / chrono-sandbox / opensandbox:** the existing K8s manifests under `deployment/`.
+
+NyxID stays out of compose deliberately — mocking the OAuth + JWT-signing path is non-trivial and would either ship a fake or pin to a real staging. Public endpoints (`/livez`, `/api/v1/skill-format/rules`, `/api/v1/skill-manifest-schema.json`, OpenAPI spec) work without auth, which is enough for most contributor flows. Auth-required endpoints need `NYXID_BASE_URL` pointed at your own NyxID instance — same model the existing `deployment/.env.ornn` uses.
+
+Includes a sample `.env.compose.sample` with the only knob a contributor typically overrides (`ENCRYPTION_KEY`).
diff --git a/.changeset/docs-page-decompose-453.md b/.changeset/docs-page-decompose-453.md
new file mode 100644
index 00000000..d3664793
--- /dev/null
+++ b/.changeset/docs-page-decompose-453.md
@@ -0,0 +1,17 @@
+---
+"ornn-web": patch
+---
+
+Decompose DocsPage into 5 colocated components (#453).
+
+`pages/DocsPage.tsx`: **905 → 303 lines (−67%)**, just over the issue's 300-line target. Five new components under `components/docs/`:
+
+- `DocsMermaid` (244L) — MermaidBlock + MermaidLightbox + SandboxedSvg + per-theme palettes
+- `DocsMarkdownComponents` (139L) — `markdownComponents` object for `<ReactMarkdown components={...}>` plus the shared `slugify()` helper
+- `DocsReleaseAccordion` (139L) — ReleaseAccordion + VersionBadge
+- `DocsSidebar` (112L) — collapsible left rail
+- `DocsTableOfContents` (69L) — sticky right minimap
+
+DocsPage now only carries page state (active doc, scroll-spy active heading, frontmatter parse, copy-doc handler) and the layout shell. Behavior unchanged; 110 web tests still pass.
+
+Second PR under #453 (after SkillDetailPage in #651). PlaygroundPage (813L) still pending its own PR.
diff --git a/.changeset/drop-dead-author-backfill-254.md b/.changeset/drop-dead-author-backfill-254.md
new file mode 100644
index 00000000..6d7ebde1
--- /dev/null
+++ b/.changeset/drop-dead-author-backfill-254.md
@@ -0,0 +1,14 @@
+---
+"ornn-api": patch
+---
+
+Delete the dead `backfill-skill-author-display-names.ts` migration script (#254).
+
+The script joined `skills.createdBy` against an `activities` collection to retro-populate `createdByEmail` / `createdByDisplayName` on legacy skill rows. Both prerequisites are gone:
+
+- New skills cache the author labels at create time (no backfill needed for any post-#239 row).
+- The `activities` collection was retired in #271 (PostHog took over the audit pipeline) — no source-side reference to it remains in `ornn-api/src`. The script would read from an empty / nonexistent collection on any current deployment.
+
+The bug #254 originally reported (`$last` in an unsorted aggregation picking arbitrary rows) is moot for a script that can't run usefully anyway. Cleaner to delete than to fix code that's known dead. Also removes the companion test file.
+
+If a future deployment unearths a database still carrying `activities`, the right cleanup is a fresh one-shot migration scoped to that database, not resurrecting this script.
diff --git a/.changeset/drop-ownerid-581.md b/.changeset/drop-ownerid-581.md
new file mode 100644
index 00000000..6764d9b2
--- /dev/null
+++ b/.changeset/drop-ownerid-581.md
@@ -0,0 +1,20 @@
+---
+"ornn-api": minor
+"ornn-web": patch
+"@chronoai/ornn-sdk": minor
+---
+
+**BREAKING:** drop the legacy `ownerId` field from skill responses (#581). The field was a no-op back-compat mirror of `createdBy` for an old "org-as-owner" design that visibility logic no longer consults — `createdBy` + `sharedWithUsers` + `sharedWithOrgs` is the authoritative ownership model.
+
+Removed from:
+
+- `ornn-api` — `SkillDocument`, `SkillDetailResponse`, `SkillSearchItem`, repository write path, search service mapping, routes response shape. No DB migration ships; old documents keep the field in storage, code just stops reading it.
+- `@chronoai/ornn-sdk` (TypeScript) — `SkillDetail.ownerId` dropped.
+- `ornn-sdk` (Python) — `SkillDetail.owner_id` dropped; `from_dict` tolerates the field appearing on stale responses by ignoring it.
+- `ornn-web` — `SkillSearchResult.ownerId` dropped.
+
+Also clears three more dead exports flagged in the same issue:
+
+- `clients/nyxid/auth.ts` + its colocated test (the `AuthClient` was never mounted — its consumer middleware was deleted earlier).
+- `INTERNAL_AUTH_HEADER` constant + `ApiKeyInfo` interface (both only referenced by the now-deleted `AuthClient`).
+- `createErrorHandler` factory (live error handler is `app.onError` in bootstrap; the factory had no callers).
diff --git a/.changeset/edit-skill-page-pass-guid-565.md b/.changeset/edit-skill-page-pass-guid-565.md
new file mode 100644
index 00000000..054b9a20
--- /dev/null
+++ b/.changeset/edit-skill-page-pass-guid-565.md
@@ -0,0 +1,13 @@
+---
+"ornn-web": patch
+---
+
+EditSkillPage hands the resolved skill GUID to write mutations (#565).
+
+Background: PR #586 tightened the backend's `PUT /skills/:id` and `DELETE /skills/:id` routes to resolve via `skillRepo.findByGuid` only — no fallback to `findByName`. The SPA's owner-edit page route stays human-readable (`/skills/:name/edit`) for shareability, but the page was passing the URL `:id` (the skill name) directly into `useUpdateSkill` / `useUpdateSkillPackage`. The mutations then built `PUT /api/v1/skills/<name>` and the backend returned 404, surfacing on the live cluster as "Failed to update package" with no visible reason.
+
+End-to-end QA on the local cluster (2026-05-22) confirmed the failure. Owner-edit was 100% broken — every PUT returned `404 skill_not_found`.
+
+Fix: resolve through `useSkill(id)` first (which accepts name OR GUID) and pass `skill.guid` to both write hooks. The fallback to the URL `:id` only matters on the first paint before skill data arrives; both mutations are gated behind the `isLoading` / `!skill` early returns, so the user can never click a button while the resolved id is still pointing at the name. Same pattern as `useSkillDetail.ts:77`.
+
+Coverage: new `EditSkillPage.test.tsx` mocks `useSkill` to return `{ guid: "abc-123", name: "my-public-skill" }` and asserts the write hooks both receive `"abc-123"`, not `"my-public-skill"`. The test fails on the pre-fix code.
diff --git a/.changeset/env-var-30-item-cap-683.md b/.changeset/env-var-30-item-cap-683.md
new file mode 100644
index 00000000..1a30016b
--- /dev/null
+++ b/.changeset/env-var-30-item-cap-683.md
@@ -0,0 +1,9 @@
+---
+"ornn-web": patch
+---
+
+Guided-create env-var input now enforces the 30-item cap inline (#683).
+
+`runtime-env-var` is capped at 30 in both the frontend frontmatter schema (`shared/schemas/skillFrontmatter.ts`) and the backend Zod schema. The Guided wizard's env-var input was a `MultiValueInput` with no `max` prop, so it defaulted to 50 — the page happily accepted chip 31. Submit-time Zod validation then blocked navigation, but the NEXT button stayed enabled with no inline feedback; users saw "click NEXT, nothing happens".
+
+Passing `max={30}` to the env-var `MultiValueInput` surfaces the cap in the field header (`N/30`), disables the input at the cap, and rejects pasted-past-cap input inline with the existing "Maximum 30 values" copy. Runtime dependencies (capped at 50 in both schemas) stay at the default, matching their real limit.
diff --git a/.changeset/error-envelope-extraction-694.md b/.changeset/error-envelope-extraction-694.md
new file mode 100644
index 00000000..6d989a00
--- /dev/null
+++ b/.changeset/error-envelope-extraction-694.md
@@ -0,0 +1,11 @@
+---
+"ornn-web": patch
+---
+
+`apiClient.handleResponse` now extracts the actionable `error.message` from the legacy `{ data: null, error: { code, message } }` envelope on non-2xx responses, in addition to the RFC 7807 `application/problem+json` shape it already handled (#694).
+
+Pre-#694, `handleResponse` parsed only `body.code / body.detail / body.title` on non-2xx. Several backend domains (LLM provider model sync, settings validation under #456, anything still funnelling through `AppError → buildErrorEnvelope`) keep emitting the legacy envelope, so their structured `error.message` was discarded and the frontend surfaced only the generic literal "An unexpected error occurred" — losing actionable detail like `"MODEL_LIST_UNREACHABLE: Provider model-list endpoint failed: …"` or `"INVALID_SETTING: postHogHost: URL host is private/loopback/link-local; set ORNN_URL_ALLOWLIST_CIDR to allow"`.
+
+Fix: in the non-2xx branch, try `body.error.{code,message}` first (the more actionable shape when present), then fall back to RFC 7807's `body.{code,detail,title}`, then to the generic literal. `ApiClientError.code` and `.message` now carry whichever was richer.
+
+Out of scope: no new unit test added because the existing module-init chain (`apiClient → authStore → …`) fails to load cleanly in vitest's headless environment without additional setup; the per-domain `onError` callsites already exercise `translateError(err, fallback)` against real `ApiClientError` instances in `pages/admin/settings/*` and `components/skill/*` flows. Manual repro per the issue body (LLM provider sync against an invalid model-list URL; saving PostHog config with a loopback host) is the gate.
diff --git a/.changeset/errors-deprecations-docs-576.md b/.changeset/errors-deprecations-docs-576.md
new file mode 100644
index 00000000..5056a1e5
--- /dev/null
+++ b/.changeset/errors-deprecations-docs-576.md
@@ -0,0 +1,4 @@
+---
+---
+
+Publishes `docs/ERRORS.md` and `docs/DEPRECATIONS.md` (#576) — the GitHub-anchored catalogs that `application/problem+json` `type` URLs and `Link: rel="deprecation"` headers point at. `ERRORS.md` documents all ten target `lowercase_snake_case` codes with `##` headings (so anchors resolve) and lists every `SCREAMING_SNAKE_CASE` code currently emitted in an appendix mapping table, owned by the #585 case migration. `DEPRECATIONS.md` ships empty (alpha = no deprecation cycle yet) with the entry template ready for v1. `CONVENTIONS.md` `type` and `Link` example URLs updated to point at the new paths.
diff --git a/.changeset/exact-optional-api-657.md b/.changeset/exact-optional-api-657.md
new file mode 100644
index 00000000..c29ed208
--- /dev/null
+++ b/.changeset/exact-optional-api-657.md
@@ -0,0 +1,21 @@
+---
+"ornn-api": patch
+---
+
+Enable `exactOptionalPropertyTypes` on ornn-api (#657 part 1).
+
+Closes the ornn-api half of the deferred work from #450. Enabling the flag surfaced 77 errors across ~35 files. Patterns:
+
+1. **Optional class fields** assigned from optional deps widen to `T | undefined`. Clients (NyxidOrgsClient, SandboxClient, StorageClient), services (QuotaService.notificationService, AuditService.notificationService/nyxidOrgsClient, SkillService.analyticsEmitter/agentsealScanner).
+
+2. **Optional interface fields** widen to `T | undefined` so call sites passing Zod-inferred shapes (`{ field: T | undefined }`) fit: SettingsActor, RedemptionCodeDoc, AuditRecord, CreateSkillData, CreateSkillVersionData, GitHubPullInput, SkillDocument, SkillDetailResponse, SkillSearchItem, SkillSource, ExportImportRoutesConfig, SettingsAuditLogger, GeneratedSkill, FetchedBundle, FetchOptions, ExtraFilters, search service params, UpdateAnnouncementInput, UpdateBroadcastDocInput, UpdateBroadcastParams, PlaygroundChatRequest.
+
+3. **Conditional spread at call sites** for routes/services passing Zod-validated bodies: admin-users, admin/quota, admin/redemption-codes, analytics, notifications, playground, quota, skills setNyxidService, generation resolveModel, analytics emitter + posthog capture, apiRequestTracking, nyxidAuth.
+
+4. One Zod refinement param widened to `Record<string, unknown>` (announcements `assertCtaPairing`) so it works against both create + update schemas under the stricter inferred types.
+
+5. One cast in skill generation — Zod's `.optional()` produces `outputType: "text" | "file" | undefined` (explicit-undefined-non-optional) vs the interface's `outputType?:` (optional-with-undefined). Same shape; cast bridges the contract.
+
+No behavior change — every fix is a type-only nudge. 793 backend tests still pass; typecheck clean.
+
+ornn-web's `exactOptionalPropertyTypes` (~134 errors) is the remaining half of #657 and ships in a follow-up commit.
diff --git a/.changeset/exact-optional-web-657.md b/.changeset/exact-optional-web-657.md
new file mode 100644
index 00000000..b844bd47
--- /dev/null
+++ b/.changeset/exact-optional-web-657.md
@@ -0,0 +1,19 @@
+---
+"ornn-web": patch
+---
+
+Enable `exactOptionalPropertyTypes` on ornn-web (#657 part 2).
+
+Closes the ornn-web half of the deferred work from #450. Enabling the flag surfaced 134 errors across ~40 files. Patterns mirror part 1:
+
+1. **Optional component-prop interfaces widen to `T | undefined`** — UI primitives (Input, Select, Badge, MarkdownEditor), form inputs (TagInput, ToolsInput, MultiValueInput, RuntimeSelect), FileTree + SkillFileViewer + SkillPackagePreview, SkillVersionList + SkillVersionsBrowserModal, SkillHeroStrip + AuditVerdictPill + DeprecationBanner, SectionShell, Toast hooks, SkillCard, ExplorePage's TabButton/FilterSidebar/SystemFilters, GenerationChatMessage CompleteBubble, ChatMessage ToolResultMessage. PageTransition uses conditional spread for motion.div's `exit`.
+
+2. **Service-layer + hook params widen** — useSkillAnalytics, useSkillPulls, useSkillAuditHistory, useSystemSkills/useSkills/useMySkills/useSharedWithMeSkills, useAdminQuotaUsers, ChatStreamParams, GenerateStreamParams, SkillSearchParams, SkillSearchResult, SkillVersionEntry, ChatDisplayMessage, GrantInput/BulkGrantInput, StartAuditInput, AdminRedemptionCodeFilters, BufferedCall (analytics).
+
+3. **Settings sections widen via SectionMeta** — `updatedAt`/`updatedBy` accept `T | undefined` so Zod-inferred shapes (Playground, SkillGen, Mirror, NyxId, SkillAudit, Telemetry, Extras) round-trip cleanly.
+
+4. **One type bridge**: `INK_OVERRIDES as unknown as never` for framer-motion's stricter MotionStyle — custom CSS-variable keys aren't expressible in either CSSProperties or MotionStyle under the stricter flag.
+
+No behavior change — every fix is a type-only nudge. 110 web tests + 793 backend + 17 sdk = 920 tests pass; typecheck clean.
+
+Closes #657 (both halves now landed).
diff --git a/.changeset/examples-dir-469.md b/.changeset/examples-dir-469.md
new file mode 100644
index 00000000..a7900ddd
--- /dev/null
+++ b/.changeset/examples-dir-469.md
@@ -0,0 +1,4 @@
+---
+---
+
+Adds `examples/` with three minimal copy-paste starter skills (#469): `text-summarizer` (TS / LLM-backed), `csv-processor` (Python / stdlib-only deterministic), `api-fetch-wrapper` (TS / external HTTP with retries + no-leak errors). Each has a working `SKILL.md` with valid frontmatter, a short README, and an entrypoint that runs locally. Main README gains an `## Examples` section + nav anchor. Each example documents how to adapt it — the three failure-mode archetypes (LLM, pure-local, external HTTP) cover the patterns a real skill author actually has to handle.
diff --git a/.changeset/filter-deactivated-nyxid-services-715.md b/.changeset/filter-deactivated-nyxid-services-715.md
new file mode 100644
index 00000000..4727c403
--- /dev/null
+++ b/.changeset/filter-deactivated-nyxid-services-715.md
@@ -0,0 +1,18 @@
+---
+"ornn-api": patch
+---
+
+`/skill-facets/system-services` now drops services NyxID has deactivated, and the NyxID catalog cache TTL drops from 60s → 10s (#715).
+
+Background: when NyxID deactivates a service (`DELETE /api/v1/services/:id` is a soft delete that flips `is_active: false`), Ornn kept exposing it. The DB aggregation behind `/skill-facets/system-services` reads `nyxidServiceId/slug/label` straight off skill documents, so any skill ever bound to that service still surfaced the service as a usable filter chip. Per-caller paths (`/me/nyxid-services`, `/nyxid-services/:serviceId/skills`) already filtered `is_active=false` inside `NyxidServiceClient.listServicesForCaller`, but the 60-second cache widened the visibility lag after deactivation.
+
+Fix:
+
+- `NyxidServiceClient.listActiveServiceIdsAsPlatform(saToken)` (new): SA-token fetch of NyxID's `/services`, projected to a `Set<string>` of active service ids. Separate from the per-caller cache (one slot — SA view is uniform). Fail-soft: returns `null` on non-2xx or thrown fetch so callers preserve current behaviour when NyxID is unreachable. Same 10s TTL as the per-caller cache.
+- `cacheTtlMs` lowered from `60_000` to `10_000`. After a NyxID deactivation, every Ornn surface that goes through `findVisibleToCaller` (`/me/nyxid-services`, reverse lookup) drops the service within at most 10s instead of 60s.
+- `invalidateCache()` also clears the platform cache so admin-side hooks can force a refresh.
+- `/skill-facets/system-services` (search/routes) now intersects the DB aggregation with the platform active set when `nyxidServiceClient` + `getSaAccessToken` are wired in; falls through to the pre-#715 raw aggregation if either is missing or the SA fetch fails. Bootstrap wires both.
+
+Out of scope: skill detail still shows the historical `nyxidServiceId/slug/label` even when the service is deactivated. The QA report lists this as one of several acceptable mitigations; the simplest "stop misrepresenting the service as usable" path is to ensure the facet (the discovery surface) doesn't advertise it. A follow-up can mark the detail panel as "service unavailable" if we want a louder signal.
+
+Coverage: colocated `clients/nyxid/service.test.ts` exercises the per-caller `is_active=false` drop (pre-existing defence-in-depth), missing-`is_active` default-to-active, the new platform method (SA token + URL, caching, fail-soft on 5xx and network throw, empty SA short-circuit, `invalidateCache` re-fetch). 8 tests, all green.
diff --git a/.changeset/folder-file-upload-validation-655.md b/.changeset/folder-file-upload-validation-655.md
new file mode 100644
index 00000000..d0280527
--- /dev/null
+++ b/.changeset/folder-file-upload-validation-655.md
@@ -0,0 +1,20 @@
+---
+"ornn-web": patch
+---
+
+Guided creation supporting-file upload now validates duplicate filenames + per-file size (#655).
+
+The Guided wizard's Step 3 file uploader accepted whatever the user dropped — including a second `run.js` into the same `scripts/` folder (silently stacked, would have produced two entries with the same path in the final ZIP) and a 55 MB blob (no warning, would have blown through the backend's 100 MB total cap on its own).
+
+Both guards now live inside `FolderFileUpload`'s `handleFileSelect`, so click + drop paths share them:
+
+1. **Duplicate filename inside the same target folder** → rejected with inline `<name> already exists in <folder>/. Remove it first to replace.` Auto-overwrite would silently drop content the user hadn't intentionally removed; making them hit Remove keeps the action explicit. Cross-folder duplicates stay allowed (different paths in the final ZIP).
+2. **Per-file size cap of 10 MiB** → rejected with `<name> is <size> — over the 10 MiB per-file limit.` Backend / ZIP pipeline still caps total uncompressed at ~100 MB (#443 / #633); 10 MiB per file keeps a single oversize artifact from eating the whole budget and surfaces the cap early.
+
+Both errors render under the drop zone with `aria-live="polite"`, auto-clear on the next successful upload or folder switch, and explicitly do NOT call `onUpload` — parent state stays untouched on rejection so there's nothing for the user to undo.
+
+A persistent `Per-file limit: 10 MiB` hint now sits above the file list so the cap is discoverable before the user picks a file.
+
+i18n: 3 new keys per locale (`guided.fileSizeHint`, `guided.fileTooLarge`, `guided.fileDuplicate`) in EN + ZH.
+
+Pinned with `FolderFileUpload.test.tsx` (6 assertions covering accept under cap, same-folder dup reject, cross-folder dup allowed, size-cap reject, error-clears-on-success, hint always visible).
diff --git a/.changeset/free-zip-upload-status-652.md b/.changeset/free-zip-upload-status-652.md
new file mode 100644
index 00000000..fcc529fc
--- /dev/null
+++ b/.changeset/free-zip-upload-status-652.md
@@ -0,0 +1,9 @@
+---
+"ornn-web": patch
+---
+
+Free / ZIP upload no longer shows contradictory "structure is valid" on backend reject (#652).
+
+When the frontend validator flagged a ZIP as `invalid`, the user could flip `Skip validation` and submit anyway. The backend then rejected (e.g. `SKILL.md not found in package`), the rejection toast fired — but the page banner unconditionally fell back to `valid` and rendered "Skill package structure is valid." on top of the toast.
+
+`CreateSkillFreePage` now restores `pageState` to the original `validationResult.status` after a failed submit (`invalid` stays `invalid`, `warning` stays `warning`, `valid` stays `valid`). The success banner can never appear on a structure the frontend itself flagged as bad.
diff --git a/.changeset/friendly-sandbox-errors-530.md b/.changeset/friendly-sandbox-errors-530.md
new file mode 100644
index 00000000..fe898982
--- /dev/null
+++ b/.changeset/friendly-sandbox-errors-530.md
@@ -0,0 +1,13 @@
+---
+"ornn-api": patch
+---
+
+`runSandboxOneShot` now translates chrono-sandbox HTTP errors into a one-line user-facing message and logs structured diagnostics, so the playground transcript stops surfacing raw JSON like `Sandbox service error (500): {"error":"internal_error","error_code":1006,"message":"An internal error occurred"}` (#530).
+
+Background: `SandboxClient.post` throws an `Error` whose message is `"Sandbox service error (<status>): <raw body>"`. The playground catch handler spat that string straight into the chat. The QA's repro on the `nyxid` skill (`https://ornn.chrono-ai.fun/playground?skill=nyxid` → `LIST CAPABILITIES`) hit a chrono-sandbox internal 500 with `error_code: 1006` and the transcript showed the raw JSON envelope verbatim — useless to the user, and presented as if the failure were the user's fault.
+
+Fix: new `formatSandboxError` helper parses the `"Sandbox service error (<status>): <body>"` shape. If the body is the structured `{ error, error_code, message }` envelope, it returns a friendly sentence keyed off `status` (500 / 1006 → transient sandbox-server hint, 503/504 → timeout hint, anything else → `HTTP <status> [code N]: <message>`). When the body isn't JSON or the regex doesn't match, it falls back to the raw message so any new upstream shape still reaches the operator. Pino `error` log carries `language`, `scriptLen`, and the raw error message so admins can grep production for 1006-class failures without scrolling chat transcripts.
+
+The underlying chrono-sandbox 500s themselves are out of scope — those originate inside the sandbox runtime, not Ornn. This change is about UX of the failure surface.
+
+`runSandboxToolCall`'s `sessionExecute` catch path stays as-is (it already falls back to the one-shot path, which now formats the error before returning).
diff --git a/.changeset/frontend-logger-584.md b/.changeset/frontend-logger-584.md
new file mode 100644
index 00000000..138cc5d1
--- /dev/null
+++ b/.changeset/frontend-logger-584.md
@@ -0,0 +1,5 @@
+---
+"ornn-web": patch
+---
+
+Production-mode console silencing for auth + analytics + apiClient + activityApi (#584). Introduces `ornn-web/src/lib/logger.ts` — a `createLogger(tag)` factory that emits via `console` in development and no-ops in production. Replaces the four ad-hoc per-module loggers that previously leaked auth lifecycle metadata (refresh timing, token expiry, user ids) to browser devtools where it persisted across the session. Dev experience unchanged.
diff --git a/.changeset/frontmatter-actionable-errors-649.md b/.changeset/frontmatter-actionable-errors-649.md
new file mode 100644
index 00000000..1428e95b
--- /dev/null
+++ b/.changeset/frontmatter-actionable-errors-649.md
@@ -0,0 +1,14 @@
+---
+"ornn-api": patch
+---
+
+Frontmatter validation errors now tell the user what to fix (#649).
+
+The Free / ZIP upload page already shows clear actionable messages for most validation failures (`version` semver rule, tag-regex rule, env-var UPPER_SNAKE_CASE rule), but the `tag`, `runtime`, `tool-list`, `runtime-env-var`, and `runtime-dependency` *item* schemas surfaced as bare `Invalid input: expected string, received null` when an author hit common YAML mistakes:
+
+- `tag: - ` (empty list-item dash) → YAML parses as `null`
+- `version: 0.1` (unquoted) → YAML parses as a number — already addressed in an earlier pass; pinned with a test here so it can't regress.
+
+Fix is additive: each item schema gains a Zod 4 `error` callback that handles `invalid_type` with a clear sentence including a concrete shape example (`tag: [my-tag]`, `runtime: [python]`, `runtime-env-var: [OPENAI_API_KEY]`, etc.). The existing `min`/`max`/`regex` messages still fire for non-null shape problems.
+
+Pinned with a new `skillFrontmatter.test.ts` — 8 assertions covering version-quoting, null-tag, uppercase-tag (regex preservation), null-env-var, null-runtime, null-tool, null-dependency, and a happy-path round trip.
diff --git a/.changeset/frontmatter-invalid-type-actionable-649.md b/.changeset/frontmatter-invalid-type-actionable-649.md
new file mode 100644
index 00000000..e05f7fd0
--- /dev/null
+++ b/.changeset/frontmatter-invalid-type-actionable-649.md
@@ -0,0 +1,13 @@
+---
+"ornn-web": patch
+---
+
+Frontmatter pre-validator surfaces actionable error copy for non-string YAML values (#649).
+
+PR #672 landed the actionable `invalid_type` callbacks on the backend Zod schema at `ornn-api/src/shared/schemas/skillFrontmatter.ts`, but the SPA carries a separate pre-upload validator at `ornn-web/src/utils/skillFrontmatterSchema.ts` that still used bare `z.string()`. The frontend gate fires first on the client, so users who uploaded a SKILL.md with `version: 0.1` (unquoted, YAML → number) still saw the unhelpful default `version: Invalid input` — the backend's friendly message never reached the page.
+
+Mirrors the backend pattern on the frontend for the six affected fields (`version`, `tag`, `runtime-env-var`, `tool-list`, `runtime`, `runtime-dependency`). Each schema now carries an `error: (issue) => issue.code === "invalid_type" ? issueMessage({ key: "errors.frontmatter.…InvalidType" }) : undefined` callback. Six new i18n keys land in both `en.json` and `zh.json` so Chinese users see localized copy too.
+
+Author-visible result: uploading a ZIP with `version: 0.1` now shows "version must be a quoted string — write `version: \"0.1\"` in SKILL.md, not `version: 0.1` (YAML parses the unquoted form as a number…)". Existing `versionFormat` / `tagFormat` / `envVarFormat` messages still fire for wrong-shape strings — only the wrong-type path was missing actionable copy.
+
+Coverage: new `skillFrontmatterSchema.test.ts` pins all six `invalid_type` branches plus three regression-guard cases (string-shape errors still route through the original keys; happy path still parses).
diff --git a/.changeset/github-import-skip-validation-frontmatter-529.md b/.changeset/github-import-skip-validation-frontmatter-529.md
new file mode 100644
index 00000000..4266b81e
--- /dev/null
+++ b/.changeset/github-import-skip-validation-frontmatter-529.md
@@ -0,0 +1,19 @@
+---
+"ornn-api": patch
+---
+
+`Skip validation` on GitHub import now also bypasses the frontmatter Zod check (#529).
+
+`POST /skills/pull` (and the symmetric `POST /skills` + `POST /skills/:id/refresh` paths) accepted `skipValidation: true` but it only short-circuited the directory-structure validator (`validateZipFormat`). The frontmatter Zod schema in `extractSkillInfo` ran unconditionally, so importing a third-party skill (e.g. Anthropic's official skills repo) with non-Ornn-shaped frontmatter still failed with `frontmatter_validation_failed`. The toggle's name + tooltip both said "skip Ornn package format validation" — users reasonably expected the frontmatter check to be part of that surface.
+
+Fix extends the `skipValidation` semantics into `extractSkillInfo`. When the flag is set AND the strict schema rejects, the parser falls back to `extractSkillInfoLenient` — a best-effort extract that:
+
+- Requires `name` (no defensible fallback for the document-id).
+- Defaults `version` to `0.1` when missing — downstream `parseVersion` still enforces the `<major>.<minor>` format.
+- Defaults `metadata.category` to `plain` (the safest category — no runtime / tool execution expected). User can edit post-import.
+- Pulls `tags` only when the value looks plausibly correct (array of strings); dropped silently otherwise.
+- YAML syntax errors still hard-fail — we can't import what we can't parse, no matter how lenient we want to be.
+
+The dry-run refresh preview also passes `skipValidation: true` to `extractSkillInfo` so a third-party-shaped SKILL.md doesn't kill the preview flow.
+
+All 805 existing tests pass; typecheck clean.
diff --git a/.changeset/hero-asset-suite-690.md b/.changeset/hero-asset-suite-690.md
new file mode 100644
index 00000000..f1c04ccb
--- /dev/null
+++ b/.changeset/hero-asset-suite-690.md
@@ -0,0 +1,4 @@
+---
+---
+
+Store the rest of the Ornn hero SVG suite under `ornn-web/public/` alongside the existing `hero-brand.svg` (#690). Adds `hero-brand-dark.svg` (dark variant for a future `<picture>` + `prefers-color-scheme: dark` swap in the README), `hero-architecture.svg`, and `hero-terminal.svg`. No README change in this PR — the assets are checked in so they're available for future docs work. Asset-only, no code or schema delta.
diff --git a/.changeset/i18n-batch-695-696-697-719-722-731.md b/.changeset/i18n-batch-695-696-697-719-722-731.md
new file mode 100644
index 00000000..bafdf005
--- /dev/null
+++ b/.changeset/i18n-batch-695-696-697-719-722-731.md
@@ -0,0 +1,25 @@
+---
+"ornn-web": patch
+---
+
+P1 i18n cluster: 6 admin/creation surfaces now follow the active UI language (#695, #696, #697, #719, #722, #731).
+
+Background: the global language switch translated the outer chrome but several surfaces leaked English (or in #731's case, Chinese) literals through `placeholder=`, `aria-label=`, hardcoded JSX text, and Zod inline messages. None of these are user-authored copy; they're application chrome.
+
+Fixes:
+
+- **#731 Broadcasts list dates**: `BroadcastsPage` rendered `createdAt`/`updatedAt` with `toLocaleString(undefined, ROW_DATE_FMT)`, so `Intl` fell back to the browser locale. Switched the first arg to `i18n.language` (already in scope as `lang`) so the date format follows the Ornn UI language.
+
+- **#695 Guided Create validation errors**: `skillCreateSchemas` had hardcoded English Zod messages (`"Name must be at least 2 characters"`, etc.). Introduced `makeBasicInfoSchema(t)` / `makeContentSchema(t)` factories; messages route through `guided.validation.*` keys. The static `basicInfoSchema` / `contentSchema` exports stay for type derivation and tests. `CreateSkillGuidedPage` memoizes a per-`t` localized schema and passes it to `useForm` so a language switch rebuilds the resolver.
+
+- **#696 Markdown editor (used by Broadcast drawer)**: three hardcoded strings in `MarkdownEditor.tsx` — `"Preview"`, `"Nothing to preview yet..."`, and the Markdown help-text — now route through `markdownEditor.*`. `BroadcastEditDrawer` itself was already fully `t()`-ified.
+
+- **#697 Admin Users table**: column header labels (`Username`, `Email`, `Skills`, `Last active`, `Activities`, `First joined`), the filter placeholder, the empty-state copy (`No users found.`), the row action label (`Grant quota`), the formatted-date null fallback (`Never`), and the sort `aria-label` (`Sort by ${col.label}`) all route through `adminUsersTable.*`. `COLUMNS` moved inside the component as a `useMemo` keyed on `t`.
+
+- **#719 NyxID service binding panel**: `AdvancedOptionsModal` already used `t()` with English string fallbacks for the binding intro, unbound option, unbound description, admin/personal tier labels, empty-state, and force-public warning — but the `nyxidService.*` keys were never added to either JSON. Added the full Chinese set (and codified the English fallback as the official `en.json` entry) so the translations actually resolve at runtime.
+
+- **#722 Admin shell**: `Sidebar` mobile header (`"Navigation"`) and `SettingsNav`'s 9 hardcoded entries (`"LLM Providers"`, `"Playground"`, `"Skill Generation"`, `"GitHub Mirror"`, `"NyxID Integration"`, `"Skill Auditing"`, `"PostHog"`, `"Service Binding List"`, `"Export / Import"`) now route through `sidebar.navigation` / `adminSettingsNav.*`.
+
+JSON additions: 5 new top-level namespaces in both `en.json` and `zh.json` — `nyxidService`, `markdownEditor`, `adminUsersTable`, `sidebar`, `adminSettingsNav` — plus a `guided.validation` block. No deletions or renames in existing keys.
+
+Out of scope: `AnnouncementsPage` shares the same `ROW_DATE_FMT, undefined)` pattern as the Broadcasts page; can ride a follow-up since #731 only names Broadcasts. Pre-existing `validateSkillFrontmatter #649` test failures (6) are unrelated.
diff --git a/.changeset/idempotency-key-middleware-459.md b/.changeset/idempotency-key-middleware-459.md
new file mode 100644
index 00000000..957973ce
--- /dev/null
+++ b/.changeset/idempotency-key-middleware-459.md
@@ -0,0 +1,15 @@
+---
+"ornn-api": minor
+---
+
+Implement the `Idempotency-Key` header documented in CONVENTIONS.md §3.4 (#459).
+
+State-changing requests (`POST` / `PUT` / `PATCH` / `DELETE`) that include an `Idempotency-Key` header now get retry-safe replay semantics: the server fingerprints `(userId, method, path, key)` and caches the response (body + status + headers) in a new `idempotency_keys` Mongo collection for 24h. Retries within that window get the cached response back with `Idempotency-Replay: true` and the handler is NOT re-executed.
+
+Matches the `Idempotency-Key` shape Stripe / Square / AWS / GitHub already expose. Closes a real reliability gap where an agent timing-out on a network blip and retrying could create duplicate skills / redemptions / notifications.
+
+Scope decisions:
+- Cache `2xx` + `4xx` responses (a validation error is deterministic for the same input); skip `5xx` (transient, retrying may succeed).
+- Keys are scoped per `userId` so two unrelated callers using the same string can't collide.
+- 24h TTL via a Mongo TTL index on `createdAt` — sweep cost is negligible at our request volume.
+- Keys longer than 255 chars are silently bypassed rather than rejected, to avoid breaking every existing caller as soon as the middleware ships.
diff --git a/.changeset/install-prompt-version-pin-639.md b/.changeset/install-prompt-version-pin-639.md
new file mode 100644
index 00000000..603e9a00
--- /dev/null
+++ b/.changeset/install-prompt-version-pin-639.md
@@ -0,0 +1,28 @@
+---
+"ornn-api": minor
+"ornn-web": patch
+---
+
+Install-card prompt now pins to the viewed version (#639).
+
+When a user opened an older skill version (`?version=0.2`) the URL + file viewer correctly switched to that version, but the install card's prompt was still latest-shaped:
+
+- The pull commands (`nyxid proxy request …/json` + the `curl …/json` line) had no `?version=…`, so an agent following the prompt would silently install `latest` at install time instead of the version the user was actually looking at.
+- The prompt header didn't mention which version the user had viewed, so even careful agents couldn't tell.
+
+Fix is end-to-end:
+
+**Backend (`ornn-api`)**
+
+- `getSkillJson(idOrName, version?)` now accepts an optional `version` query — literal `<major>.<minor>` OR a dist-tag (#463). When set, the response uses that version's `storageKey` + `metadata`; otherwise the latest package is returned (unchanged behaviour for legacy callers).
+- Returns a new top-level `version` field so callers can confirm exactly which package they got.
+- `GET /api/v1/skills/:idOrName/json` reads `?version=` and threads it through. Bad version → `400 invalid_version`; missing version → `404 skill_version_not_found` (RFC 7807). Visibility check unchanged.
+- Bumped to **minor** because the response shape gains a new field.
+
+**Frontend (`ornn-web`)**
+
+- `buildTrySkillPrompt({…, version })` adds `?version=` to both pull URLs (curl + NyxID CLI via `--query version=…`), and to the footer `Ornn URL:`. Header line becomes `# Install Ornn skill: <name> @ <version>` and a "Pinned to version `<X>`" paragraph spells out why the URLs carry the query.
+- `SkillInstallCard` passes the currently-viewed `skill.version` straight through, so the prompt always matches the page.
+- No-version callers (theoretical "always pull latest" surfaces) are unaffected — the version is opt-in.
+
+Pinned with 3 new `buildTrySkillPrompt.test.ts` assertions (version-pinning surfaces, no-pin parity, dist-tag passes through unchanged) and the existing 9 cases re-verified.
diff --git a/.changeset/integrity-hash-461.md b/.changeset/integrity-hash-461.md
new file mode 100644
index 00000000..b0b2b206
--- /dev/null
+++ b/.changeset/integrity-hash-461.md
@@ -0,0 +1,5 @@
+---
+"ornn-api": patch
+---
+
+Surface npm-style Subresource Integrity on the skill version manifest (#461). `GET /skills/:idOrName/versions` now returns each version with an `integrity: "sha256-<base64>"` field alongside the existing hex `skillHash`. Clients (SDK + agents) verify a downloaded package byte-for-byte before installing — equivalent in spirit to npm's `package-lock.json` `integrity:` field and PyPI's per-file `sha256_digest`. The underlying hash was already computed at upload + stored on the version doc; this PR just derives the SRI form (`hexToIntegrity` helper) and surfaces it.
diff --git a/.changeset/json-visibility-567.md b/.changeset/json-visibility-567.md
new file mode 100644
index 00000000..7b8abd92
--- /dev/null
+++ b/.changeset/json-visibility-567.md
@@ -0,0 +1,5 @@
+---
+"ornn-api": patch
+---
+
+Enforce per-skill visibility on `GET /skills/:idOrName/json` (#567). The endpoint previously gated only on `ornn:skill:read`, so a caller who knew a private skill's name could fetch its full package contents through this route — broader than `/skills/:idOrName`, which applies `canReadSkill`. Now the JSON route loads the skill first and runs the same visibility check (`canReadSkill` against `createdBy` / `sharedWithUsers` / `sharedWithOrgs` + platform-admin permission), returning `SKILL_NOT_FOUND` for inaccessible private skills. Closes the leak surfaced by the `aevatar` `/v1/responses` Ornn bridge.
diff --git a/.changeset/landing-tokens-452.md b/.changeset/landing-tokens-452.md
new file mode 100644
index 00000000..4552aa7a
--- /dev/null
+++ b/.changeset/landing-tokens-452.md
@@ -0,0 +1,5 @@
+---
+"ornn-web": patch
+---
+
+Replace hardcoded hex literals on the landing pages with design tokens (#452). `PhoneMockup` (bezel edges, side buttons, camera lens) and `AnimatedTerminal` (traffic-light dots, terminal-output green) previously inlined `#1a1713`, `#2a2620`, `#0b1520`, `#3a5060`, `#c94a4a`, `#c9a64a`, `#5a9b5a`, `#7dc97d` in `bg-[…]` / `shadow-[…]` / arbitrary-gradient strings. Adds eight tokens under `@theme` in `neon.css` (`--color-bezel-edge`, `-rim`, `-lens-deep`, `-lens-rim`, `-traffic-{red,amber,green}`, `-terminal-ok`) and rewires both files to use the generated `bg-bezel-edge` / `text-terminal-ok` / `var(--color-…)` utilities. Visual output unchanged.
diff --git a/.changeset/llm-apiformat-routing-574.md b/.changeset/llm-apiformat-routing-574.md
new file mode 100644
index 00000000..32906671
--- /dev/null
+++ b/.changeset/llm-apiformat-routing-574.md
@@ -0,0 +1,18 @@
+---
+"ornn-api": patch
+---
+
+NyxLlmClient now routes outbound LLM calls on the resolved provider's `apiFormat` (#574).
+
+Background: the admin LLM Provider form exposes `apiFormat: chat-completion | responses`, but the runtime client hard-coded `{gatewayUrl}/responses` for both `stream()` and `complete()` and ignored the setting. Providers behind the Chat Completions API — DeepSeek and any OpenAI-compatible gateway without `/responses` — returned 404 on every skill generation request, surfacing in the UI as a misleading "LLM Gateway error (404)" even though the model/key/gateway were all configured correctly.
+
+Fix: thread `apiFormat` through `resolveLlmProviderForSurface` (`bootstrap.ts`) into the new `LlmProviderResolution.apiFormat` field, and dispatch inside `NyxLlmClient`:
+
+- `responses` → `POST {gatewayUrl}/responses` with the native Responses-API body (unchanged behavior).
+- `chat-completion` → `POST {gatewayUrl}/chat/completions` with a translated body (`input` → `messages`, `developer` role → `system`, `max_output_tokens` → `max_tokens`, `instructions` prepended as a `system` message, tools projected into OpenAI function-tool shape). The Chat Completions SSE stream is normalized so each `choices[].delta.content` chunk is yielded as a Responses-API `response.output_text.delta` event — consumers (skill generation + playground) stay format-agnostic.
+
+Tool-call delta normalization for the chat-completion path is intentionally out of scope here; it is tracked in #608 (playground runtime/mixed skills not triggering `execute_in_sandbox` under chat-completion providers).
+
+Trailing slashes on `gatewayUrl` are still trimmed before path concatenation, and the empty-`gatewayUrl` `LLM_PROVIDER_NOT_CONFIGURED` fail-closed branch is preserved.
+
+Coverage: new `src/clients/nyxid/llm.test.ts` covers both formats — endpoint dispatch, body translation (role/field/tool mapping), text-delta normalization, content-part flattening, SA-token fallback, trailing-slash trim, fail-closed, and non-2xx surfacing. 11 tests, all green.
diff --git a/.changeset/llm-provider-save-and-default-pin-588-607.md b/.changeset/llm-provider-save-and-default-pin-588-607.md
new file mode 100644
index 00000000..750ad836
--- /dev/null
+++ b/.changeset/llm-provider-save-and-default-pin-588-607.md
@@ -0,0 +1,19 @@
+---
+"ornn-api": patch
+---
+
+LLM provider: save preserves model list + Playground default pin is honoured (#588 + #607).
+
+Two related bugs in the LLM-providers admin surface, fixed together because the diagnosis touched the same `providerUpdateSchema` / `listPickerModels` surface:
+
+**#588 — Saving basic provider settings can clear the model list.** `providerUpdateSchema = providerCreateSchema.partial()` inherited the `models: z.array(...).default([])` from the create schema, so a PATCH that omitted `models` came back as `models: []`. The service then ran `if (patch.models)` — truthy on `[]` — and wiped the persisted list. `ProviderEditDrawer`'s basic-settings save sends only `name` / `gatewayUrl` / `apiFormat` / `auth` / `maxOutputTokens` / `defaultTemperature`, no `models` at all, so every basic-fields save nuked the provider's model catalog. Fix: `.extend({ models: z.array(modelInputSchema).optional() })` on the update schema so `undefined` (caller didn't send it) is distinguishable from `[]` (caller explicitly wiped); service uses `patch.models !== undefined` instead of truthy-check. Explicit `[]` still wipes — preserves the model-list-refresh-found-zero-models intent.
+
+**#607 — Playground saved default model not honoured by picker.** `listPickerModels` derived the default slot from the per-model `defaultForX` flag, not from the per-section `playground.defaultModelId` pin. So admins could save Playground settings with a chosen default, the setting persisted correctly, but `/me/models` returned a different model as default — picker pre-selected the wrong row and chat used it. The chat **execute** path's `resolveSurfaceDefaults` (in `bootstrap.ts`) DID honour the pin; only the picker disagreed. Fix: `listPickerModels(surface, sectionDefaultModelId?)` accepts the pin and the picker route resolves it via a new `sectionDefaultResolver` config function that reads `settingsService.getPlayground() / .getSkillGen()`. Pinned model wins the `default` slot AND sorts first in `items`; stale pin (model removed or disabled) falls through to the per-model `defaultForX` flag, matching the resolver's behaviour.
+
+Pinned with 3 new service tests:
+
+- `UT-LLM-004a` — basic-settings save without `models` key preserves existing list (#588 reproducer)
+- `UT-LLM-004b` — explicit `models: []` still wipes (#588 symmetry)
+- `UT-LLM-004c` — picker honours section pin; stale pin falls through (#607 reproducer)
+
+808 / 0 fail ornn-api tests; typecheck clean.
diff --git a/.changeset/logger-consolidation-575.md b/.changeset/logger-consolidation-575.md
new file mode 100644
index 00000000..99fab0b7
--- /dev/null
+++ b/.changeset/logger-consolidation-575.md
@@ -0,0 +1,11 @@
+---
+"ornn-api": patch
+---
+
+Consolidate 61 standalone `pino({ level: "info" })` loggers behind a single `createLogger(moduleName)` factory (#575). Before this PR, every module had its own pino instance — neither the `LOG_LEVEL` env var nor the bootstrap logger's redaction rules (`authorization`, `x-api-key`, `password`, `secret`, `apiKey`) made it past the bootstrap. Setting `LOG_LEVEL=debug` to debug a request silently no-op'd on 64 of 65 logger instances, hiding exactly the `logger.debug(...)` calls #579 just added.
+
+New `ornn-api/src/shared/logger.ts` exposes `createLogger(name)` — drop-in replacement for the old pattern. The factory reads `LOG_LEVEL` from env once at module load and applies the same redaction rules the bootstrap pino uses. Every module logger created via the factory inherits both.
+
+61 sites swept across `ornn-api/src`. The 3 remaining standalone pinos are intentionally-silent test loggers (`pino({ level: "silent" })`) — they suppress output in test runs and aren't a candidate for the factory.
+
+Bootstrap pino kept separate — it has its own `service: "ornn-api"` binding and adds `requestId` per request, which module loggers don't need.
diff --git a/.changeset/login-telemetry-cors-709.md b/.changeset/login-telemetry-cors-709.md
new file mode 100644
index 00000000..46e8ae50
--- /dev/null
+++ b/.changeset/login-telemetry-cors-709.md
@@ -0,0 +1,9 @@
+---
+"ornn-web": patch
+---
+
+`logActivity` no longer sets `credentials: "include"`, unblocking the post-OAuth `POST /api/v1/activity/login` call on the hosted environment (#709).
+
+The endpoint is Bearer-token-authenticated; it never read cookies. The lone `credentials: "include"` set in `activityApi.ts` (the rest of the SPA's `apiClient` calls never set it) forced the browser to demand `Access-Control-Allow-Credentials: true` plus a specific (non-`*`) `Access-Control-Allow-Origin` on the preflight response. The NyxID proxy doesn't emit those for this endpoint, so the preflight failed and every login on `ornn.chrono-ai.fun` ate a `TypeError: Failed to fetch`. Authenticated GETs through the same proxy keep working because they're simple requests (no preflight) and the rest of the POST endpoints don't set `credentials`.
+
+Dropping the flag brings this call into line with every other authenticated POST in the SPA and the preflight succeeds.
diff --git a/.changeset/lowercase-error-codes-585.md b/.changeset/lowercase-error-codes-585.md
new file mode 100644
index 00000000..dc17289f
--- /dev/null
+++ b/.changeset/lowercase-error-codes-585.md
@@ -0,0 +1,8 @@
+---
+"ornn-api": minor
+"ornn-web": patch
+---
+
+**BREAKING:** every error `code` emitted by `/api/v1/*` is now `lowercase_snake_case` per CONVENTIONS.md §1.4 (#585). `SKILL_NOT_FOUND` → `skill_not_found`, `INVALID_BODY` → `invalid_body`, `FORBIDDEN` → `forbidden`, etc. One-for-one lowercase translation: every existing code keeps its specificity, the parent §1.4 catalog (`validation_error`, `permission_denied`, `resource_not_found`, …) is the taxonomy these subcodes hang under. Clients pinned to the old strings need to switch — `docs/ERRORS.md` ships the full migration map.
+
+Web call sites that branch on specific codes (`AGENTSEAL_DISABLED`, `OLD_REPO_NOT_CONFIRMED`, `AUDIT_NOT_FOUND`) migrated to the lowercase equivalents in the same PR. No code-aware logic in the published SDK code paths today, so SDK consumers only need to update their own catch-by-code handlers.
diff --git a/.changeset/mermaid-iframe-440.md b/.changeset/mermaid-iframe-440.md
new file mode 100644
index 00000000..4b3be468
--- /dev/null
+++ b/.changeset/mermaid-iframe-440.md
@@ -0,0 +1,5 @@
+---
+"ornn-web": patch
+---
+
+Render Mermaid SVG inside a sandboxed iframe (#440). The DocsPage previously injected the rendered SVG via `dangerouslySetInnerHTML`. Mermaid is the only producer today and its input is trusted in-repo markdown, so this is purely defence-in-depth — but if any future code path ever feeds user-controlled diagram source (e.g. user-authored skill READMEs with mermaid blocks), the strict `sandbox=""` boundary already prevents script execution, form submission, navigation, and storage access. The lightbox pan/zoom transform is owned by the parent `<div>`, so interaction is unchanged.
diff --git a/.changeset/notification-dropdown-stale-728.md b/.changeset/notification-dropdown-stale-728.md
new file mode 100644
index 00000000..a2aab3fb
--- /dev/null
+++ b/.changeset/notification-dropdown-stale-728.md
@@ -0,0 +1,9 @@
+---
+"ornn-web": patch
+---
+
+`useNotifications` now polls on the same 30s interval as the unread-count query, so the bell dropdown stays in sync with the badge (#728).
+
+Background: the bell badge subscribes to `useUnreadNotificationCount` (polled every `UNREAD_POLL_MS` = 30s) and the dropdown list to `useNotifications` (no `refetchInterval`, only `staleTime: 10_000`). When a new targeted broadcast lands, the count poll ticks to `1` and the badge updates — but `useNotifications` only re-fetches on remount/invalidation, so an open (or just-mounted-but-still-fresh) dropdown showed the pre-broadcast list. Users saw "1 unread" + a list that didn't contain it.
+
+Fix: add `refetchInterval: UNREAD_POLL_MS` to `useNotifications` so the two queries tick together. `refetchIntervalInBackground: false` mirrors the count query — no traffic when the tab is hidden. `staleTime` stays at 10s so quick remounts (e.g. dropdown toggle) still serve cached data without an extra round-trip.
diff --git a/.changeset/openapi-contract-tests-462.md b/.changeset/openapi-contract-tests-462.md
new file mode 100644
index 00000000..6ea6d6a0
--- /dev/null
+++ b/.changeset/openapi-contract-tests-462.md
@@ -0,0 +1,20 @@
+---
+"ornn-api": patch
+---
+
+OpenAPI contract test pass against `buildSpec()` (#462). New `tests/contract/openapi.test.ts` pins 12 structural properties of the generated spec so it can't silently regress:
+
+- Spec is OpenAPI 3.1 with title/version/description/servers.
+- `BearerAuth` security scheme declared.
+- Every declared path has at least one HTTP method.
+- Every operation declares `tags`, a `summary` or `operationId`, at least one response, and at least one `2xx` response.
+- Every `4xx`/`5xx` response uses `application/problem+json` (or JSON-compatible) per RFC 7807 / #456.
+- Every operation outside a small `publicPaths` allowlist declares `BearerAuth` security per CONVENTIONS.md §5.
+- A foundational route-coverage list (`/skills`, `/skill-search`, `/skill-format/*`, `/skill-manifest-schema.json`) MUST stay in the spec.
+
+What's NOT in scope (tracked as follow-ups on #462):
+
+- **Reflection over the live Hono app** to assert every registered route has a spec entry. The current spec covers ~12 of ~50 routes; closing that gap is a separate PR that needs each missing route documented with its own per-route Zod schema.
+- **Cross-checking declared error codes against handler `throw` statements** — needs a static code-walker.
+
+The infrastructure for those follow-ups is now in place. Adding a new route without spec metadata, or shipping a half-documented route, fails CI today.
diff --git a/.changeset/ornn-agent-manual-cli-v1-2.md b/.changeset/ornn-agent-manual-cli-v1-2.md
new file mode 100644
index 00000000..a7c05546
--- /dev/null
+++ b/.changeset/ornn-agent-manual-cli-v1-2.md
@@ -0,0 +1,4 @@
+---
+---
+
+Refresh `ornn-agent-manual-cli` skill manual to v1.2 (#560). Re-syncs `SKILL.md` and `references/api-reference.md` against the current `/api/v1/*` surface on `develop` — fixes the `GET /skills/:idOrName/versions` envelope in §0.5, drops the defunct `ornn:admin:category` permission row, teaches §2.13 the discriminated `source: "user" | "broadcast"` notification feed, adds the §2.15 quota / model-picker recipe, removes six ghost admin sections (`/admin/stats`, `/admin/activities`, categories CRUD, tags CRUD) and replaces them with the real surface (`/admin/dashboard/stats`, `/admin/quota/*`, `/admin/redemption-codes/*`, `/admin/mirror/*`, AgentSeal rescan, announcements, broadcasts), rewrites §14 platform settings around the sectioned routes + LLM-provider CRUD + export/import, adds §11.9–§11.12 for `/me/quota`, `/me/models`, `/me/redemption-codes/*`, and corrects the appendix skill name. No `ornn-api` / `ornn-web` code change — empty changeset satisfies the gate; agents pick up the new contract by pulling `GET /api/v1/skills/ornn-agent-manual-cli/json` after the registry-side sync.
diff --git a/.changeset/p2-batch-716-725-727-729.md b/.changeset/p2-batch-716-725-727-729.md
new file mode 100644
index 00000000..f9530643
--- /dev/null
+++ b/.changeset/p2-batch-716-725-727-729.md
@@ -0,0 +1,18 @@
+---
+"ornn-web": patch
+---
+
+P2 UX cluster: four small admin/registry papercuts (#716, #725, #727, #729).
+
+- **#716 Admin Mirror dashboard route**: `/admin/mirror` used to redirect to `/admin/settings/mirror`, and the section's "Open mirror dashboard" link pointed at `/admin/skills`. Net effect: no reachable UI for manual reconcile / status counts. `MirrorPage` (full operations console — counts grid, reconcile button, status header) is now lazy-mounted at `/admin/mirror` again, and the section link points there instead of Admin Skills.
+
+- **#725 Mode-selection cards alignment**: the four mode cards on `/skills/new` share a layout but the description paragraph had no min-height, so a shorter copy (Free Mode) shifted the bullet list up versus its neighbours. Added `min-h-[3rem] sm:min-h-[3.5rem]` to the description `<p>` so all four bullet lists start on the same baseline.
+
+- **#727 Keyword search placeholder lied about tags**: the placeholder advertised "name, description, or tags" but the backend keyword search doesn't match tags (the tag chip facet is the supported path). Updated `search.placeholderKeyword` in both en and zh to drop "or tags" — and the in-component fallback string to match.
+
+- **#729 Shared With Me cards now show the org name**: the access-reason sub-line on `SkillCard` rendered a generic "Via organization" even though `skill.sharedViaOrgId` was already populated. Look it up against `useMyOrgs()`'s membership list and render the new `viaOrganizationNamed` key (`Via {{org}}` / `通过 {{org}} 共享`). Falls back to the old generic copy when the org isn't in the caller's memberships (rare — server only sets `sharedViaOrgId` to an org the caller belongs to, but defence-in-depth).
+
+Out of scope:
+
+- **#723** (Notifications page can't scroll past viewport) — needs investigation of `RootLayout`'s `overflow-hidden` policy and any layout regressions adjacent pages might depend on.
+- **#726** (Registry semantic search with empty query renders the no-skills empty state instead of "enter a description") — needs a small UX state in the search component to distinguish "validation gate hit" from "no matches". Both will follow up.
diff --git a/.changeset/p2-followup-723-726.md b/.changeset/p2-followup-723-726.md
new file mode 100644
index 00000000..052412a2
--- /dev/null
+++ b/.changeset/p2-followup-723-726.md
@@ -0,0 +1,9 @@
+---
+"ornn-web": patch
+---
+
+P2 follow-up: notifications page can scroll past the viewport and Registry semantic search with an empty query shows an actionable validation message instead of the generic empty state (#723, #726).
+
+- **#723** — `RootLayout`'s `<main>` is `overflow-hidden`; `NotificationsPage` had no own scroll container, so once the list exceeded the viewport, older notifications were clipped and unreachable via wheel/touch scroll. Wrapped the page body in an `h-full overflow-y-auto` shell — same pattern `UploadSkillPage` uses for the same root-layout constraint.
+
+- **#726** — Registry's semantic-search button could flip on while the input was empty; the backend correctly returned `400 QUERY_REQUIRED` but `ExplorePage` rendered the regular "No public skills match" empty state, indistinguishable from a legitimate zero-result search. Added a `semanticGateUnmet = mode === "semantic" && !query.trim()` check that swaps the empty state for an `EmptyState` with explicit copy: `Enter a search description / Semantic search needs a description of what you're looking for. Type a phrase in the search box above, or switch back to Keyword mode.` (+ Chinese translation). The backend queries keep firing (cheap, cached) but the user sees a clear validation hint instead of a misleading null result.
diff --git a/.changeset/parseint-env-fallback-447.md b/.changeset/parseint-env-fallback-447.md
new file mode 100644
index 00000000..f9d8193b
--- /dev/null
+++ b/.changeset/parseint-env-fallback-447.md
@@ -0,0 +1,5 @@
+---
+"ornn-api": patch
+---
+
+Replace `Number(process.env.X ?? "200")` with a fail-fast `parseNonNegativeInt(name, fallback)` helper in `scripts/migrate-quota-to-buckets.ts` (#447). `Number()` silently returns `NaN` on garbage input, baking `NaN` quotas into Mongo when an env file has a typo. The new helper rejects non-numeric input, trailing garbage (`"200abc"`), fractions, negatives, and empty strings at startup with a clear error naming the offending env var. Covered by 9 unit tests in the colocated test file.
diff --git a/.changeset/playground-env-isolation-721.md b/.changeset/playground-env-isolation-721.md
new file mode 100644
index 00000000..e47274a8
--- /dev/null
+++ b/.changeset/playground-env-isolation-721.md
@@ -0,0 +1,16 @@
+---
+"ornn-api": patch
+---
+
+Playground no longer puts user-supplied env *values* into the LLM prompt and server-side overrides any value the model emits at `execute_in_sandbox` time (#721).
+
+Before this change, `buildSkillContext` injected `KEY=value` pairs into the developer message so the model could pass them through to `execute_in_sandbox`. When a chat-completion provider returned the tool call as plain assistant text instead of a structured tool-call frame (the failure mode #608 fixed for compliant providers — but a non-compliant model can still emit raw JSON in `text-delta`), the env values appeared verbatim in the user-visible transcript. Even with the secret value redacted on the wire, the bug surface was that the secret had ever passed through the LLM at all.
+
+Fix has two layers:
+
+- **Developer message**: list only the env-var *names* the user provided, with a placeholder shape `KEY=<provided-server-side>` and a brief instruction telling the model to reference each by name. The model never has the literal value, so it can't echo it.
+- **Tool dispatch**: `runSandboxToolCall` merges `request.envVars` (the real values, supplied by the UI / API caller) *on top of* `args.env` (whatever the model produced). User-supplied keys always win at execution time. Keys the model legitimately invents (sentinel markers, etc.) ride through unchanged.
+
+Net effect: even if a future regression lets the model serialize a tool call as text again, the transcript carries `KEY=<provided-server-side>` instead of the secret, and the sandbox still runs with the real value because the merge happens on the server before `sessionExecute`.
+
+Coverage: 2 new tests in `chatService.test.ts` cover the user-override-wins case (real value replaces model's guessed value, untouched keys ride through) and the no-envVars passthrough case (model-only env reaches sandbox unchanged). All 10 tests in the file green.
diff --git a/.changeset/playground-not-found-563.md b/.changeset/playground-not-found-563.md
new file mode 100644
index 00000000..d1118eb5
--- /dev/null
+++ b/.changeset/playground-not-found-563.md
@@ -0,0 +1,5 @@
+---
+"ornn-web": patch
+---
+
+Render a "Skill not found" state on Playground when the API returns 404 (#563). The page previously gated only on `skillLoading` — once loading completed, missing `skill` data still rendered the full playground UI (starter prompts, chat input, ENV drawer chrome) for unauthorized users hitting a private skill's URL directly. Backend already returned `SKILL_NOT_FOUND` via the [#567](https://github.com/ChronoAIProject/issues/567) visibility check; this PR is the matching client gate that doesn't paint the surface when the data isn't allowed. New i18n keys `playground.notFoundTitle` / `playground.notFoundBody` (EN + ZH).
diff --git a/.changeset/playground-page-decompose-453.md b/.changeset/playground-page-decompose-453.md
new file mode 100644
index 00000000..0ca65c10
--- /dev/null
+++ b/.changeset/playground-page-decompose-453.md
@@ -0,0 +1,18 @@
+---
+"ornn-web": patch
+---
+
+Decompose PlaygroundPage into 6 colocated components (#453).
+
+`pages/PlaygroundPage.tsx`: **813 → 518 lines (−36%)**. Six new components under `components/playground/`:
+
+- `PlaygroundHelpers` (101L) — pure helpers + `ThinkingBubble` indicator
+- `PlaygroundEmptyHero` (86L) — centered welcome flag + 3 suggestion chips
+- `PlaygroundConversation` (109L) — forwardRef: turns + streaming buffer + file outputs + error banner + scroll anchor
+- `PlaygroundRail` (101L) — fixed right-edge rail with hover-peek + click-to-pin
+- `PlaygroundEnvDrawerBody` (81L) — per-key input list + lock hint
+- `PlaygroundPackageDrawerBody` (79L) — SkillPackagePreview + registry-link footer
+
+PlaygroundPage now carries state plumbing (hooks for skill / package / chat / quota), the drawer outer container, the composer (ChatInput + ModelPicker + QuotaInline), and the early-return states (no-skill / loading / 404 / over-limit). The suggested `usePlaygroundSession()` hook extraction is deferred — would pull queries / chat state / handlers out and likely bring the page under 300L, but the data flow doesn't bisect into a small commit.
+
+Closes the page-component portion of #453 (SkillDetailPage in #651, DocsPage in #659, this PR). Issue stays open for the deferred hook-extraction work.
diff --git a/.changeset/post-201-location-458.md b/.changeset/post-201-location-458.md
new file mode 100644
index 00000000..ee564236
--- /dev/null
+++ b/.changeset/post-201-location-458.md
@@ -0,0 +1,5 @@
+---
+"ornn-api": patch
+---
+
+Return `201 Created` + `Location` header on resource-creating POST endpoints (#458). `POST /skills` (ZIP upload), `POST /skills/pull` (GitHub pull), `POST /admin/announcements`, and `POST /admin/broadcasts` previously returned `200 OK` with the resource in the envelope; CONVENTIONS.md §3.2 + RFC 9110 §15.3.2 specify `201 Created` with a `Location: /api/v1/{resource}/{id}` header so clients (and the upcoming SDK auto-pagination wrapper) can discover the canonical URL without re-parsing the body. Response body unchanged — only status code + new header. Existing 200-aware clients still work; the SDK already follows redirects and reads the envelope regardless of 2xx code.
diff --git a/.changeset/private-key-validation-441.md b/.changeset/private-key-validation-441.md
new file mode 100644
index 00000000..5c44b520
--- /dev/null
+++ b/.changeset/private-key-validation-441.md
@@ -0,0 +1,5 @@
+---
+"ornn-api": patch
+---
+
+Validate the shape of `appPrivateKey` on `POST /github/repo` (#441). The mirror settings endpoint previously accepted any non-empty string; pastes with stray whitespace, embedded NULs, missing BEGIN/END markers, or a truncated body wrote garbage into settings and surfaced much later as opaque crypto errors during mirror runs. The new `validateGitHubAppPrivateKey` helper enforces an 8 KB cap, rejects C0 control bytes, requires PKCS#1 / PKCS#8 PEM markers, and round-trips through `crypto.createPrivateKey` to catch shape-passing-but-broken keys before they're persisted. Empty string still clears the key. 12 unit tests cover happy + rejection paths.
diff --git a/.changeset/python-sdk-audit-445.md b/.changeset/python-sdk-audit-445.md
new file mode 100644
index 00000000..2fd41853
--- /dev/null
+++ b/.changeset/python-sdk-audit-445.md
@@ -0,0 +1,4 @@
+---
+---
+
+Add a `python-sdk-audit` CI job + bound the Python SDK dependencies (#445). The previous `httpx>=0.27` constraint (no upper bound) would have silently picked up a hypothetical httpx 1.0 release with breaking semantics; bounds on `httpx`, `pytest`, `respx`, and `pytest-asyncio` keep us inside the 0.x/major lines we've actually tested against. The new CI job runs `pip-audit --strict` against the resolved environment on every PR so a CVE landing on a transitive dep fails CI loudly. Full lockfile (`pip-compile` workflow) deferred — the bounds + audit pair already closes the loud-failure gap without the lockfile maintenance overhead.
diff --git a/.changeset/python-sdk-ruff-mypy-583.md b/.changeset/python-sdk-ruff-mypy-583.md
new file mode 100644
index 00000000..4104389f
--- /dev/null
+++ b/.changeset/python-sdk-ruff-mypy-583.md
@@ -0,0 +1,4 @@
+---
+---
+
+Add ruff + mypy gates to the Python SDK CI job (#583). `python-sdk-test` previously only ran pytest with respx mocking — lint + type errors could land on develop without detection. Adds ruff config (E/W/F/I/B/UP + per-file exceptions for tests) and a strict-mypy config (boundary `Any` from httpx/respx allowed, internal code stays strict). CI runs `ruff check`, `ruff format --check`, and `mypy` before pytest. Source edits to satisfy the new gates: drop unused `httpx` import in a test fixture, split one over-long line, cast `httpx.Response.content` to `bytes` (typeshed annotates it as `Any`).
diff --git a/.changeset/quota-refresh-races-629-630-624.md b/.changeset/quota-refresh-races-629-630-624.md
new file mode 100644
index 00000000..add110cc
--- /dev/null
+++ b/.changeset/quota-refresh-races-629-630-624.md
@@ -0,0 +1,13 @@
+---
+"ornn-web": patch
+---
+
+Fix three Playground / Skill-Gen quota refresh races (#629 + #630 + #624).
+
+All three were the same family of "the chrome and the truth disagree":
+
+- **#629** — `QuotaInline` warning banner and `QuotaSummary` row both rendered `Math.round((used / ceiling) * 100)`. With `used=199, ceiling=200, remaining=1`, that's `99.5 → 100%` even though the chip next to it showed `1 Playground calls left`. New shared `displayUsagePercent(used, ceiling, remaining)` uses `Math.floor`, clamps to `[0, 99]` whenever `remaining > 0`, and only returns `100` when `remaining <= 0`. Pinned with 6 unit assertions.
+- **#630** — `usePlaygroundChat`'s `finish` / `error` handlers didn't invalidate `MY_QUOTA_KEY`. The page kept showing the pre-charge snapshot for up to 60 seconds (the next poll). Added `qc.invalidateQueries({ queryKey: MY_QUOTA_KEY })` on both terminal events so the chip / banner / over-limit gate reflect the actual remaining count immediately.
+- **#624** — `CreateSkillGenerativePage` (and `PlaygroundPage`) routed to `OverLimitPage` whenever `isOverLimit` flipped true, even if the user had a generated result / live conversation on screen. The post-charge quota poll arriving after the *final* allowed run would yank the result away. Now the over-limit redirect only fires on a *fresh* arrival (no preview / no messages); the Send button's existing `isOverLimit` disable still prevents new runs.
+
+Net effect: the user's last allowed run lands, the result stays visible, the chip flips to 0/N right away, and the banner copy stops contradicting the chip.
diff --git a/.changeset/rate-limit-439-460.md b/.changeset/rate-limit-439-460.md
new file mode 100644
index 00000000..bb7ea359
--- /dev/null
+++ b/.changeset/rate-limit-439-460.md
@@ -0,0 +1,23 @@
+---
+"ornn-api": minor
+---
+
+Sliding-window rate-limit middleware + RFC 9239 headers on every response (#439 + #460).
+
+New `ornn-api/src/middleware/rateLimit.ts` exports `rateLimit({ windowMs, max, label?, keyBy? })`. Defaults:
+- **Key:** `auth.userId` when present, else `x-forwarded-for` first IP, else `"anonymous"`.
+- **Storage:** in-memory `Map` per process; cleanup pass every 60s on access.
+- **Headers:** `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (seconds) emitted on every allowed AND denied response. Denied responses also carry `Retry-After`.
+- **Deny:** throws `AppError(429, "rate_limited", "...")` — the global handler emits it as `application/problem+json` per RFC 7807.
+
+Applied to the three highest-cost endpoints:
+
+| Route | Limit | Why |
+|---|---|---|
+| `GET /skill-search` | 60/min/user | Mongo aggregation (keyword) or LLM rerank (semantic) |
+| `POST /skills` | 10/min/user | ZIP validate + storage write + AgentSeal scan |
+| `POST /skills/generate` | 20/min/user | Every request is an LLM call |
+
+6 new unit tests pin: header emission, per-user keying, window reset, 429 response shape, multi-label composition. Full suite 704 / 0.
+
+**Storage caveat for prod:** in-memory means multi-pod clusters get per-pod-buckets — the effective limit is `N × max` where N is the replica count. Acceptable for the current single-replica dev/staging cluster; a Redis backend is the natural next step before prod traffic hits a multi-replica deployment.
diff --git a/.changeset/react-keys-451.md b/.changeset/react-keys-451.md
new file mode 100644
index 00000000..2d85732c
--- /dev/null
+++ b/.changeset/react-keys-451.md
@@ -0,0 +1,5 @@
+---
+"ornn-web": patch
+---
+
+Document or replace `key={i}` on `Array.map` lists across the web app (#451). Every site flagged in the audit was reviewed: positional lists that never reorder (skeleton cards, OTP cells, code-editor line numbers, table skeletons) keep `key={i}` but now carry a one-line comment so a future audit doesn't churn the file. Data-driven lists that can re-shape (RootLayout breadcrumbs, CreateSkillFreePage validation messages) switch to composite keys that include the data identity, so reconciliation doesn't preserve hover/focus state on the wrong element when the source array changes shape.
diff --git a/.changeset/readme-badge-trim-688.md b/.changeset/readme-badge-trim-688.md
new file mode 100644
index 00000000..4df7861f
--- /dev/null
+++ b/.changeset/readme-badge-trim-688.md
@@ -0,0 +1,4 @@
+---
+---
+
+Trim the `README.md` badge row to CI / release / license, and drop the status / model-agnostic / HTTP·MCP pills below the hero (#688). Removes the broken `codecov unknown`, the noisy `last commit` and `discussions` badges, the vanity `stars` badge, and three positioning pills that are already shown inside the hero SVG. Surveyed 20 popular SDK / API repos; the trimmed set matches the dominant `version + license + CI` pattern. Docs-only, no code or schema change.
diff --git a/.changeset/readme-header-rework-701.md b/.changeset/readme-header-rework-701.md
new file mode 100644
index 00000000..847637a4
--- /dev/null
+++ b/.changeset/readme-header-rework-701.md
@@ -0,0 +1,4 @@
+---
+---
+
+README polish for #701 — drop the small `<picture>` logo at the top, lock the hero to `hero-brand-dark.svg` (no theme swap) and wrap it in a link to ornn.chrono-ai.fun, collapse the badges + tagline onto a single left-aligned line ("The skill lifecycle API for AI agents, not another marketplace."), left-align the nav, and remove the premature `## SDK quickstart` section + its nav entry since `@chronoai/ornn-sdk` and `ornn-sdk` are not yet published. Docs-only; no package code touched.
diff --git a/.changeset/readme-hero-dark-swap-692.md b/.changeset/readme-hero-dark-swap-692.md
new file mode 100644
index 00000000..b97d1c27
--- /dev/null
+++ b/.changeset/readme-hero-dark-swap-692.md
@@ -0,0 +1,4 @@
+---
+---
+
+Wire the README hero to swap between `hero-brand.svg` (light) and `hero-brand-dark.svg` (dark) via a `<picture>` + `prefers-color-scheme` block (#692), matching the light/dark swap the wordmark logo at the top of the README already uses. Pure markup change — the dark asset was already stored under `ornn-web/public/` (#690). Docs-only, no code or schema delta.
diff --git a/.changeset/readme-hero-image-684.md b/.changeset/readme-hero-image-684.md
new file mode 100644
index 00000000..94f59195
--- /dev/null
+++ b/.changeset/readme-hero-image-684.md
@@ -0,0 +1,4 @@
+---
+---
+
+Add Ornn hero brand image to `README.md` (#684). Drops `ornn-web/public/hero-brand.svg` alongside the existing logo assets and inserts a centered hero block between the badges row and the status pills — `logo → badges → hero → pills → tagline → links → nav`. Docs-only, no code or schema change.
diff --git a/.changeset/readme-mermaid-polish-707.md b/.changeset/readme-mermaid-polish-707.md
new file mode 100644
index 00000000..476f3135
--- /dev/null
+++ b/.changeset/readme-mermaid-polish-707.md
@@ -0,0 +1,9 @@
+---
+---
+
+Polish the README `## How it works` Mermaid diagram for #707 — fixes from the #705 forge-palette render:
+1. Subgraph titles use the DESIGN.md bracketed mono pattern (`[ § YOUR MACHINE ]` / `[ § ORNN CLOUD ]`) and drop the `ornn.chrono-ai.fun` suffix so they stop being clipped.
+2. `edgeLabelBackground` set to canvas (`#0B0907`) so edge labels float on the dark background instead of rendering as dark-on-dark rectangles.
+3. `clusterBkg` / `clusterBorder` set as defaults; `[ § YOUR MACHINE ]` lifted to `iron` (`#221E16`) while `[ § ORNN CLOUD ]` stays at `graphite` (`#14110B`) for a gentle material contrast.
+4. Node and edge labels trimmed to one line (no more parenthetical subtitles) so the diagram fits the GitHub viewport without overflow.
+5. Bonus: `CLI ==>|HTTPS| API` is thick + ember-tinted via `linkStyle 1` (the load-bearing action edge — single localized accent per DESIGN.md's allowance for wire / pulse effects), node strokes bumped to 1.5–2px for the "forged metal" feel, default `lineColor` dropped to `ash` so the ember edge wins the visual weight contest. Docs-only; no package code touched.
diff --git a/.changeset/readme-mermaid-restyle-705.md b/.changeset/readme-mermaid-restyle-705.md
new file mode 100644
index 00000000..7685f9ea
--- /dev/null
+++ b/.changeset/readme-mermaid-restyle-705.md
@@ -0,0 +1,4 @@
+---
+---
+
+Restyle the README `## How it works` Mermaid diagram with the Editorial Forge palette for #705. Uses Mermaid's `init` directive + per-node `classDef` to map directly onto DESIGN.md tokens: obsidian + graphite subgraph fills, forged-metal (`#1A1610` / `#221E16`) node fills with steel borders and parchment text, ember (`#FF7322`) anchored on `ornn-api` as the brand-voice protagonist, arc-blue (`#5BC8E8`) on `NyxID` as the restricted secondary diagrammatic accent (auth / identity = "cool side of the forge"). Subgraph titles render UPPERCASE. Locked to dark in both GitHub themes — per DESIGN.md's carve-out for operational / code-chrome surfaces, consistent with the dark-only hero. Docs-only; no package code touched.
diff --git a/.changeset/readme-positioning-table-472.md b/.changeset/readme-positioning-table-472.md
new file mode 100644
index 00000000..fd0fbd8f
--- /dev/null
+++ b/.changeset/readme-positioning-table-472.md
@@ -0,0 +1,4 @@
+---
+---
+
+Adds a `## How Ornn compares` positioning section to the main README (#472) — comparison matrix vs MCP servers, Smithery, and npm registry, followed by a "what this means in practice" paragraph that owns the differences honestly (incl. the CLI gap, footnoted to the roadmap). Top nav gets a new anchor.
diff --git a/.changeset/readme-restructure-703.md b/.changeset/readme-restructure-703.md
new file mode 100644
index 00000000..14823a8b
--- /dev/null
+++ b/.changeset/readme-restructure-703.md
@@ -0,0 +1,4 @@
+---
+---
+
+Restructure the README into a tight 5-section layout for #703: `What is Ornn + Why we built it`, `How it works` (Mermaid flowchart instead of ASCII), `Quickstart` (3 numbered steps — NyxID sign-up with invite code, `ornn-agent-manual-cli` install + `nyxid` provisioning, concrete plain-language example prompts for search / pull+install / audit / build+publish), `Community and Contributing` (merged, with Roadmap folded in as a bullet), `License`. Removes the now-redundant `Run Ornn locally`, `How Ornn compares`, `Examples`, `Documentation`, and `Roadmap` H2 sections plus the top-of-page nav strip — those links live in CONTRIBUTING.md, on the website, or as a single bullet in Community. Docs-only; no package code touched.
diff --git a/.changeset/readme-sdk-quickstart-470.md b/.changeset/readme-sdk-quickstart-470.md
new file mode 100644
index 00000000..e3089e1e
--- /dev/null
+++ b/.changeset/readme-sdk-quickstart-470.md
@@ -0,0 +1,4 @@
+---
+---
+
+Adds an `## SDK quickstart` section to the main README (#470) — copy-paste-ready TypeScript and Python snippets that match the real `OrnnClient` constructor + `.search({ q })` shape. Sits between `## How it works` and the existing agent-side `## Quickstart`, with a nav link. Install lines reference `@chronoai/ornn-sdk` / `ornn-sdk`; until #473 lands the npm side is install-from-source, called out inline.
diff --git a/.changeset/readme-website-link.md b/.changeset/readme-website-link.md
new file mode 100644
index 00000000..9a8725e4
--- /dev/null
+++ b/.changeset/readme-website-link.md
@@ -0,0 +1,4 @@
+---
+---
+
+Surface the Ornn official website (https://ornn.chrono-ai.fun) right under the tagline in the root `README.md` (#572). Previously the only mentions of the domain were buried in the `/docs` sub-path link — first-time readers had no obvious entry point to the product homepage. No `ornn-api` / `ornn-web` code change; empty changeset satisfies the gate.
diff --git a/.changeset/recipients-popover-507.md b/.changeset/recipients-popover-507.md
new file mode 100644
index 00000000..d10a7330
--- /dev/null
+++ b/.changeset/recipients-popover-507.md
@@ -0,0 +1,14 @@
+---
+"ornn-web": patch
+---
+
+Replace the BroadcastsPage recipients tooltip with a real popover (#507).
+
+The recipients column rendered the email list inside the native HTML `title` attribute as a `\n`-joined string. That broke two ways:
+
+- **Safari** collapses `\n` to a single space inside `title`, so all emails ran together as one unreadable line.
+- **All browsers** truncate / flicker the multi-line native tooltip past ~20 entries — long broadcast lists were unusable.
+
+Replaced with an inline `RecipientsPopover` that mirrors `CategoryTooltip`'s pattern: hover OR click opens, click-outside / Esc / second-click closes, `aria-expanded` reflects state. The list is `max-h-64 overflow-y-auto` so 20+ recipients stay readable. Component is kept inline (BroadcastsPage is the only consumer) — promoting to `components/ui/` would be premature.
+
+Kept the inline anchor as a `<button>` rather than a `<span>` so it's keyboard-focusable + screen-reader-announceable.
diff --git a/.changeset/registry-i18n-sweep-682.md b/.changeset/registry-i18n-sweep-682.md
new file mode 100644
index 00000000..a2671ffb
--- /dev/null
+++ b/.changeset/registry-i18n-sweep-682.md
@@ -0,0 +1,15 @@
+---
+"ornn-web": patch
+---
+
+Registry page now respects Chinese locale across every tab (#682).
+
+Two classes of bug, both mass-bleeding English copy into the Chinese UI:
+
+**Class 1 — keys called from source never existed in either locale file.** `ExplorePage.tsx` reads `t("explore.filterTags", "Tag")`, `t("explore.noServices", "No system services yet.")`, `t("explore.systemSkillsHint", "…")`, etc. through 14 distinct keys that were never added to `en.json` or `zh.json`. Without a matching key in either locale, i18n falls back to the second arg (the English literal) regardless of language. ZH users saw English literals everywhere. Added the missing keys to BOTH locale files. Also renamed the source's two intro paragraphs (`systemSkillsHint` → `systemSkillsIntro`, `sharedHint` → `sharedWithMeIntro`) to match the new canonical key names so future readers don't trip on the legacy fallback-only labels.
+
+**Class 2 — literal strings never wired through i18n.** `SearchBar.tsx` had 5 hardcoded English strings (`Keyword`, `Semantic`, the two placeholders, the two `title=` tooltips). `SkillCard.tsx` had `Public`, `Private`, `Via organization`, `Shared by {name}` baked in. `Pagination.tsx` had `Prev` / `Next` baked in (used on every paginated list — Registry, admin tables, lifetime drawer). All converted to `t("…")` calls; new keys added to both locale files; `Public` / `Private` / `Prev` / `Next` reuse the existing `common.*` keys (already translated in ZH).
+
+Net result: Registry page reads end-to-end Chinese in ZH mode — search bar, all four tabs' filter headings + empty states, skill-card badges, and pagination. Product names (`NyxID`) stay untranslated per the issue's guidance. Date formatting is not addressed here — Intl `toLocaleString` already respects the system locale on the browser side; the calling pages set their own `locale` param if they want to force `zh-CN`.
+
+139 / 0 fail ornn-web tests; typecheck clean.
diff --git a/.changeset/release-notes-v0.9.0.md b/.changeset/release-notes-v0.9.0.md
new file mode 100644
index 00000000..30f44a27
--- /dev/null
+++ b/.changeset/release-notes-v0.9.0.md
@@ -0,0 +1,4 @@
+---
+---
+
+Release prep for v0.9.0 — adds the dated `.github/release-notes-20260529.md` used as the GitHub Release body. Docs/CI-only; no package version impact beyond the feature changesets already on develop (#753).
diff --git a/.changeset/rerank-zod-444.md b/.changeset/rerank-zod-444.md
new file mode 100644
index 00000000..2c2273a3
--- /dev/null
+++ b/.changeset/rerank-zod-444.md
@@ -0,0 +1,5 @@
+---
+"ornn-api": patch
+---
+
+Validate the LLM re-ranker response with Zod instead of an `as Array<...>` cast (#444). `JSON.parse(...) as Array<...>` is a runtime no-op; a malformed model response previously slipped through the GUID filter and broke downstream score arithmetic with `NaN`/`undefined`. The new `rerankResponseSchema` enforces `id` is a non-empty string and `score` is a finite number before the row reaches the filter; schema failures log a warning with the first three Zod issues and return the empty batch (same fail-safe as before, just observable now).
diff --git a/.changeset/revert-public-api-ingress-661.md b/.changeset/revert-public-api-ingress-661.md
new file mode 100644
index 00000000..a4523b49
--- /dev/null
+++ b/.changeset/revert-public-api-ingress-661.md
@@ -0,0 +1,10 @@
+---
+---
+
+Revert the direct ornn-api Ingress shipped in #661.
+
+The Ingress added a second public surface for `ornn-api` that bypassed the NyxID proxy. That contradicts the deployment rule that **every public request to ornn-api must be proxied by NyxID** — there is no separate public ingress for the Ornn backend, by design.
+
+The anonymous-browse gap that motivated #467 belongs on the NyxID side, not here. Tracked as **NyxID#610 — "feat: Anonymous endpoints for admin services"**, which is the proper architectural fix: NyxID's proxy gains per-(method, path) opt-in anonymous access for admin services (ornn-api is the motivating case in that issue's body), with per-endpoint daily quota and admin API + UI + MCP transport + CLI surfaces.
+
+Removing the manifest and its changeset from this repo so prod never picks it up.
diff --git a/.changeset/rfc7807-envelope-456.md b/.changeset/rfc7807-envelope-456.md
new file mode 100644
index 00000000..8f833eb5
--- /dev/null
+++ b/.changeset/rfc7807-envelope-456.md
@@ -0,0 +1,26 @@
+---
+"ornn-api": minor
+"ornn-web": patch
+"@chronoai/ornn-sdk": minor
+---
+
+**BREAKING:** error responses now ship as RFC 7807 `application/problem+json` per CONVENTIONS.md §1.3 (#456). The legacy `{ data: null, error: { code, message } }` envelope is gone on error paths; the fields live at the body root now:
+
+```http
+HTTP/1.1 404 Not Found
+Content-Type: application/problem+json
+
+{
+  "type": "https://github.com/ChronoAIProject/Ornn/blob/main/docs/ERRORS.md#skill_not_found",
+  "title": "Resource not found",
+  "status": 404,
+  "detail": "Skill 'foo' not found",
+  "instance": "/v1/skills/foo",
+  "code": "skill_not_found",
+  "requestId": "req_01HXYZ..."
+}
+```
+
+Success responses keep the `{ data, error: null }` envelope — only errors change.
+
+`buildProblemJsonBody` helper added to `shared/types/index.ts`; bootstrap and every per-domain test stub use it so wire shape can never drift between dev and CI. Both SDKs (TS + Python) and `ornn-web`'s `apiClient` parse the new shape; error tests across all three pin the new fixture.
diff --git a/.changeset/sandbox-session-persistence-531.md b/.changeset/sandbox-session-persistence-531.md
new file mode 100644
index 00000000..81b2110e
--- /dev/null
+++ b/.changeset/sandbox-session-persistence-531.md
@@ -0,0 +1,20 @@
+---
+"ornn-api": patch
+---
+
+PlaygroundChatService now reuses a per-language chrono-sandbox session across tool-use rounds within one chat (#531).
+
+Background: every `execute_in_sandbox` tool call went to chrono-sandbox's one-shot `/execute` endpoint, which provisions a fresh kernel each invocation. As a result, anything a previous round installed (CLIs like `nyxid`, npm packages, generated files, env writes) was lost the next round. The LLM would `nyxid login`, then the next call would see no login. Users assumed the flow was working because each individual call succeeded — but the chat-level state never accumulated.
+
+Fix: in `chat()`, declare a per-stream `Map<language, sessionId>` plus a `createdSessionIds` list. The first `execute_in_sandbox` call for a given language lazily calls `sandboxClient.createSession({ language, dependencies, env, inputFiles, ttlSecs: 600, networkEnabled: true })` and records the session id; subsequent same-language calls hit `sessionExecute(sessionId, ...)` against the persistent kernel. A different language inside the same chat (e.g. javascript then python) lazily creates a second session.
+
+The whole tool loop is wrapped in `try / finally`; on exit (normal, error, abort) we best-effort `deleteSession` every session we created. chrono-sandbox also expires via `ttlSecs`, so a delete failure logs at `warn` and otherwise falls through — leftover sessions TTL out.
+
+Fail-open fallbacks preserve pre-fix behaviour if the session layer is unavailable:
+
+- `createSession` throws → log warn, fall back to one-shot `execute()` for that round; no session recorded.
+- `sessionExecute` throws → log warn, drop the stale session id from the map (next same-language call will recreate), fall back to one-shot `execute()` for that round.
+
+Plain (non-sandbox) chats touch nothing — no createSession, no deleteSession, zero overhead.
+
+Coverage: new colocated `src/domains/playground/chatService.test.ts` exercises the path with a stub `NyxLlmClient` (queued per-round event sequences) and a recording sandbox stub — asserts session creation count, sessionExecute reuse, multi-language isolation, finally-cleanup, both fail-open branches, plain-chat no-op, and delete-failure suppression. 8 tests, all green.
diff --git a/.changeset/sdk-keywords-and-topics-468.md b/.changeset/sdk-keywords-and-topics-468.md
new file mode 100644
index 00000000..21969e22
--- /dev/null
+++ b/.changeset/sdk-keywords-and-topics-468.md
@@ -0,0 +1,4 @@
+---
+---
+
+Discovery metadata pass for the SDKs (#468). Adds `keywords` + npm publish fields (`homepage`, `bugs`, `repository`, `license`) to `@chronoai/ornn-sdk` and expands Python SDK `keywords` to align with the agent-API positioning (`ornn`, `agent`, `skill-registry`, `skill-lifecycle`, `ai-agents`, `model-agnostic`, `mcp`, `llm`, `sdk`). GitHub repo topics set out-of-band via `gh repo edit`. No `ornn-api` / `ornn-web` code change — empty changeset satisfies the gate.
diff --git a/.changeset/sdk-publish-strategy-473.md b/.changeset/sdk-publish-strategy-473.md
new file mode 100644
index 00000000..8e3f81a0
--- /dev/null
+++ b/.changeset/sdk-publish-strategy-473.md
@@ -0,0 +1,4 @@
+---
+---
+
+Publishes `docs/SDK_PUBLISHING.md` (#473) — explicit decision to hold both `@chronoai/ornn-sdk` (npm) and `ornn-sdk` (PyPI) for v1.0 so the surface stops shifting under early adopters during alpha. Adds a v1 publish checklist (drop `private: true`, reserve registry names, extend changeset-release workflow with `npm publish` + `twine upload`, smoke-test on a clean machine) and a "pre-publish install from source" recipe for current users (`bun link` for TS, `pip install -e` / git-subdirectory for Python). Both SDK READMEs gain a "Status: pre-publish" banner pointing at the doc.
diff --git a/.changeset/skill-detail-decompose-453.md b/.changeset/skill-detail-decompose-453.md
new file mode 100644
index 00000000..353a9955
--- /dev/null
+++ b/.changeset/skill-detail-decompose-453.md
@@ -0,0 +1,21 @@
+---
+"ornn-web": patch
+---
+
+First-pass decomposition of `SkillDetailPage` (#453).
+
+`SkillDetailPage.tsx` was 1133 lines — well over the 300-line target the issue sets. This PR pulls 7 self-contained chunks into colocated components under `components/skill/`:
+
+- `SkillSaveConfirmModal` — save-with-skip-validation toggle
+- `SkillDeleteConfirmModal` — whole-skill delete confirmation
+- `SkillAuditStartedModal` — post-audit-kickoff acknowledgement
+- `SkillVersionsBrowserModal` — all-versions list + Compare button + per-row delete toast
+- `AuditVerdictPill` — right-rail audit verdict tile (3 visual states)
+- `SkillDetailStates` — loading skeleton + 404 not-found shells
+- `SkillVersionsCard` + `SkillVisibilityCard` — right-rail cards
+
+Net: `SkillDetailPage.tsx` from **1133 → 868 lines** (-23%). 9 new component files at 41-124 lines each.
+
+Behavior unchanged. Each new component is stateless except for the toast-emitting delete handler inside the versions browser (kept colocated so the parent doesn't need to thread it through). All 110 frontend tests still pass; typecheck clean.
+
+Per the issue's "one PR per page" guidance, DocsPage (901L) and PlaygroundPage (813L) get their own PRs. A follow-up will also extract the `useSkillDetail()` hook to pull the queries / mutations / derived state out of the page entirely — that's the biggest remaining lever, but the data flow is too entangled with the JSX layout to bisect cleanly in this PR.
diff --git a/.changeset/skill-manifest-jsonschema-464.md b/.changeset/skill-manifest-jsonschema-464.md
new file mode 100644
index 00000000..aa4e2b53
--- /dev/null
+++ b/.changeset/skill-manifest-jsonschema-464.md
@@ -0,0 +1,17 @@
+---
+"ornn-api": minor
+---
+
+Publish JSON Schema for `SKILL.md` frontmatter (#464). New endpoint:
+
+```
+GET /api/v1/skill-manifest-schema.json
+```
+
+- Generated from the Zod source of truth (`shared/schemas/skillFrontmatter.ts`) so the published contract cannot drift from the runtime validator.
+- Output is JSON Schema **draft-2020-12**, served with `Content-Type: application/schema+json`.
+- Public, no auth, `Cache-Control: public, max-age=3600`.
+
+Lets VS Code / Cursor / JetBrains YAML language servers autocomplete + validate `SKILL.md` frontmatter directly against the live server contract. Schema-store registration (`schemastore.org`) is a separate, one-time external action.
+
+The OpenAPI spec at `GET /api/v1/openapi.json` lists the new path so contract tests pick it up. Documented in `docs/CONVENTIONS.md` §10.1.
diff --git a/.changeset/stale-share-target-720.md b/.changeset/stale-share-target-720.md
new file mode 100644
index 00000000..9d102d47
--- /dev/null
+++ b/.changeset/stale-share-target-720.md
@@ -0,0 +1,15 @@
+---
+"ornn-api": patch
+"ornn-web": patch
+---
+
+Stale share-target grants are now visible-but-flagged in the Permissions modal, and `skill-search?scope=shared-with-me` defensively drops results pointing at orgs the caller is no longer in (#720).
+
+**Backend (`SearchService.search`):** after `enrichItem` builds the items, when `scope === "shared-with-me"` a zero-trust pass drops any item whose `myAccessReason === "shared-via-org"` but whose `sharedViaOrgId` isn't in the caller's current `userOrgIds`. `applyScope` already gates this at the DB layer, so this is defence-in-depth against cache lag / partially-replicated writes / future query regressions — and a `warn`-level Pino entry tags any drop so data drift is visible.
+
+**Frontend (`PermissionsModal`):**
+
+- Orgs: `fetchOrgSummary` previously back-filled a `null` lookup with the raw org id as the display name, silently hiding the staleness. Now each entry carries `isUnresolved: boolean` (true when NyxID can't resolve the id). Unresolved rows render with a warning-toned row background, an "unresolved" badge with a triangle icon, and a tooltip pointing the owner at the uncheck box to revoke. Click-to-revoke flows through the existing `toggleOrg` path.
+- Users: when `resolveUsers` doesn't return a row for an id, the placeholder `{ userId, email: "", displayName: userId }` survives — that signal now drives a danger-toned chip + triangle icon + tooltip explaining the user is gone, with the existing `×` button revoking.
+
+Net effect: owners see exactly what they've granted, see which grants point at entities that no longer resolve, and can clean them up in two clicks. The `skill-search` zero-trust filter ensures the calling user never sees a shared-with-me skill they can't actually open even if the underlying DB / cache disagrees with effective org membership.
diff --git a/.changeset/strict-ts-flags-450.md b/.changeset/strict-ts-flags-450.md
new file mode 100644
index 00000000..7635b6fa
--- /dev/null
+++ b/.changeset/strict-ts-flags-450.md
@@ -0,0 +1,29 @@
+---
+"ornn-api": patch
+"ornn-web": patch
+"@chronoai/ornn-sdk": patch
+---
+
+Enable stricter TS flags across all three packages (#450).
+
+#450 part 1 (`noImplicitOverride`) landed in #638. This PR closes the bulk of parts 2 + 3:
+
+- **All 3 packages now have `noUncheckedIndexedAccess: true`.** Array/object bracket access now widens to `T | undefined`, forcing explicit handling. Fix patterns by category:
+  - **Length-guarded accesses** — `if (xs.length > 0)` followed by `xs[len-1]`, `findIndex` followed by `arr[idx]`. Marked `!` with a comment naming the guard. Most cases.
+  - **Regex capture groups** — every `match[1]` / `match[2]` followed by a `match` check. Marked `!` with the regex-shape note.
+  - **Defensive `if (!entry)` skips** — `zip.files[path]` where `path` came from `Object.keys(zip.files)`. Switched from `if (entry.dir)` to `if (!entry || entry.dir)` so a future zip-lib refactor that breaks the round-trip drops the file rather than crashes.
+  - **Two non-mechanical fixes**: GenerateSkillModal.STEP_MESSAGES switched from `Record<string, string>` to `as const` (compile-time keys now return `string`, not `string | undefined`); SkillDetailPage.latestVersion now passed as `latestVersion ?? ""`.
+
+- **SDK only: `exactOptionalPropertyTypes: true`.** The SDK had 4 errors total; all 4 were `{ requestId: undefined }`-style fields that violated the stricter `{ requestId?: string }` contract. Fixed with conditional spread (only set the key when the upstream actually has the value).
+
+### Deferred
+
+`exactOptionalPropertyTypes` on ornn-api (~77 errors) and ornn-web (~134 errors) — tracked as #657. These need per-site decisions (conditional spread vs widened field type vs constructor refactor), not mechanical fixes, so they don't fit a single-session PR.
+
+### Net
+
+- 3 tsconfig.json files updated.
+- ornn-api: 26 files touched (68 fix sites + 1 tsconfig).
+- ornn-web: 22 files touched (57 fix sites + 1 tsconfig).
+- sdk/typescript: 3 files touched (4 fix sites + 1 tsconfig).
+- 798 backend + 110 web + 17 sdk tests all still pass.
diff --git a/.changeset/stricter-ts-flags-450-part1.md b/.changeset/stricter-ts-flags-450-part1.md
new file mode 100644
index 00000000..f4a6fb34
--- /dev/null
+++ b/.changeset/stricter-ts-flags-450-part1.md
@@ -0,0 +1,8 @@
+---
+"ornn-api": patch
+"@chronoai/ornn-sdk": patch
+---
+
+Enable `noImplicitOverride` in `ornn-api`, `ornn-web`, and `sdk/typescript` tsconfigs (#450 part 1). Catches accidental method-signature drift during class-inheritance refactors. Only one site needed the explicit `override` keyword (`ErrorBoundary` in `ornn-web`) — zero behavior change.
+
+The other two flags from #450 (`noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`) surface 68 and 75 type errors respectively across `ornn-api` alone. Per the issue's "Land in stages" guidance, those ride in their own follow-up PRs to keep the diff reviewable. Tracked as sub-tasks on #450.
diff --git a/.changeset/tag-input-dedup-650-653.md b/.changeset/tag-input-dedup-650-653.md
new file mode 100644
index 00000000..401e86b8
--- /dev/null
+++ b/.changeset/tag-input-dedup-650-653.md
@@ -0,0 +1,20 @@
+---
+"ornn-web": patch
+---
+
+Fix Guided-create TagInput duplicate handling (#650 + #653).
+
+Two bugs against the same code path:
+
+- **#650** — typing a duplicate tag and pressing Enter left the rejected value in the input. The next typed character concatenated onto it, so `alpha` (rejected) + typing `beta` produced the tag `alphabeta`.
+- **#653** — the duplicate was rejected silently with no feedback, so the user couldn't tell whether the tag was added or eaten.
+
+Both fixed by:
+
+1. Clearing the input on duplicate (nothing to fix — the existing tag is valid), matching the success path.
+2. Surfacing `Already added` below the input on duplicate, mirroring `MultiValueInput`'s wording so the two multi-value components read the same.
+3. Clearing the transient error on the next keystroke so it never blocks editing.
+
+Pinned with a new `TagInput.test.tsx` (7 assertions covering the duplicate-clear-input contract, case/whitespace normalization, transient-error clearing, empty submissions, comma-commit, and Backspace removal).
+
+`MultiValueInput` (env vars, runtime deps) has the same `input stays after duplicate` pattern but rejects different cases (e.g. validation errors where keeping the typo visible helps the user fix it). Out of scope here; if surfaced by users will be a separate ticket.
diff --git a/.changeset/toobjectid-helper-448.md b/.changeset/toobjectid-helper-448.md
new file mode 100644
index 00000000..7ae3cfea
--- /dev/null
+++ b/.changeset/toobjectid-helper-448.md
@@ -0,0 +1,5 @@
+---
+"ornn-api": patch
+---
+
+Replace `_id: guid as any` with `skillId(guid)` / `skillIdList(guids)` helpers in `domains/skills/crud/repository.ts` (#448). The skills collection uses UUID strings as `_id`; the MongoDB driver's filter discriminator (`ObjectId | string`) doesn't see that without help, and the previous `as any` propagated unchecked through every query. The new helpers validate non-empty strings up front (the bad-input path that previously silently returned zero docs) and keep the unavoidable cast in one named place. Seven call sites migrated.
diff --git a/.changeset/unit-tests-backfill-454.md b/.changeset/unit-tests-backfill-454.md
new file mode 100644
index 00000000..03974f97
--- /dev/null
+++ b/.changeset/unit-tests-backfill-454.md
@@ -0,0 +1,19 @@
+---
+"ornn-api": patch
+---
+
+Backfill repository-layer unit tests for 6 previously untested domains (#454).
+
+Adds `repository.test.ts` against `mongodb-memory-server` for: `users`, `platform`, `analytics`, `notifications`, `announcements`, `redemption-codes`. Plus `platform/service.test.ts` to pin the encryption boundary (`apiKey` is plaintext above the service, ciphertext below) and the graceful-degrade path when decryption fails. Each new file covers happy path + at least one edge per public method per the #454 acceptance criteria.
+
+Highlights of what's now pinned in tests:
+
+- `UserDirectoryRepository`: idempotent upsert preserves `firstSeenAt` while bumping `activityCount`/`lastSeenAt`; `searchByEmailPrefix` escapes regex metacharacters; `listUsers` role partition + pagination.
+- `PlatformSettingsRepository`: empty doc returns `{}` so the service-layer merge can tell "unset" from "zero"; partial patches don't clobber untouched fields; wrong-type values are skipped gracefully.
+- `PlatformSettingsService`: `apiKey` round-trips through encryption but never appears in plaintext in Mongo; malformed v1 ciphertext returns `""` (graceful degrade) instead of throwing; legacy pre-encryption rows pass through; 30-s cache is busted by `patch`.
+- `AnalyticsRepository`: latency is rounded to int + clamped to 0 on negatives; `summarize` window aggregates execution/success/failure/timeout counts + unique-users + success rate; per-version narrowing works.
+- `NotificationRepository`: per-user ownership is enforced on `markRead` (user A cannot read user B's notification); `unreadOnly` + `before` filters; `markAllRead` reports modifiedCount.
+- `AnnouncementRepository`: `findActive` honors `[startsAt, endsAt]` window + disabled gate; `findAllReleased` retains expired records (News archive); legacy single-locale rows backfill `*En`/`*Zh` slots so reads stay live during the bilingual migration window.
+- `RedemptionCodeRepository`: `tryClaimForRedeem` is atomic — concurrent attempts yield exactly one winner; expired/invalidated codes can't be redeemed; `list` search escapes regex metacharacters (no ReDoS, no false positives).
+
+Net +81 tests, +1 file (no source changes — pure test backfill).
diff --git a/.changeset/url-header-conventions-586.md b/.changeset/url-header-conventions-586.md
new file mode 100644
index 00000000..8124cd95
--- /dev/null
+++ b/.changeset/url-header-conventions-586.md
@@ -0,0 +1,13 @@
+---
+"ornn-api": minor
+"ornn-web": patch
+"@chronoai/ornn-sdk": patch
+---
+
+**BREAKING** for two of the three changes — bring URL + header surface in line with CONVENTIONS.md §2/§4/§7 (#586):
+
+1. **`PATCH /skills/:id/versions/:version` + `DELETE /skills/:id/versions/:version`** — write operations now accept the stable GUID only, not `:idOrName`. Callers passing a name should resolve it via `GET /skills/lookup?name=…` first. (§2.2)
+2. **`?q=` is the canonical search param** (§4.1). The legacy `?query=` keeps working as a fallback during the alpha grace window — `q` wins when both are present. Both SDKs and ornn-web migrated to send `q`.
+3. **Deprecation signal is RFC 8594 (`Deprecation: true` + `Link: rel="deprecation"`)** — replaces `X-Skill-Deprecated` / `X-Skill-Deprecation-Note` custom headers (§7).
+
+The fourth violation flagged in the issue — `/skills/:id/json` → content negotiation via `Accept` header (§3.3) — is **deferred** to a focused follow-up PR. That one rewires the playground and several SDK paths and deserves its own review.
diff --git a/.changeset/use-playground-session-hook-453.md b/.changeset/use-playground-session-hook-453.md
new file mode 100644
index 00000000..3b6b7911
--- /dev/null
+++ b/.changeset/use-playground-session-hook-453.md
@@ -0,0 +1,13 @@
+---
+"ornn-web": patch
+---
+
+Extract `usePlaygroundSession()` hook from PlaygroundPage (#453).
+
+The second hook-extraction follow-up — parallel to `useSkillDetail()` from #664. The hook owns every query, ref, derived value, drawer state, and handler callback; the page is left with the JSX layout shell + prop wiring.
+
+Net delta: `PlaygroundPage.tsx` **518 → 386 lines** (−25%). Cumulative #453 progress on PlaygroundPage: **813 → 386** (−53% across #660 + this PR).
+
+Closes the page-component + hook-extraction portions of #453 across all three pages (SkillDetailPage 1133→625, DocsPage 905→303, PlaygroundPage 813→386). DocsPage is already under the 300L target; the two larger pages now have their data flow cleanly split — state lives in hooks, layout lives in pages.
+
+Behavior unchanged; 110 web tests still pass.
diff --git a/.changeset/use-skill-detail-hook-453.md b/.changeset/use-skill-detail-hook-453.md
new file mode 100644
index 00000000..a3b9998f
--- /dev/null
+++ b/.changeset/use-skill-detail-hook-453.md
@@ -0,0 +1,13 @@
+---
+"ornn-web": patch
+---
+
+Extract `useSkillDetail()` hook from SkillDetailPage (#453).
+
+The deferred follow-up from #651: pull every query, mutation, derived value, local UI state, and handler callback out of the page into a single `useSkillDetail(idOrName)` hook. The page is a thin shell that destructures the hook and wires props into the already-extracted subcomponents.
+
+Net delta: `SkillDetailPage.tsx` **873 → 625 lines** (−28%). Cumulative #453 progress on SkillDetailPage: **1133 → 625** (−45% across #651 + this PR).
+
+What the hook owns: 6 queries (skill, versions, audit summary + history, 7d pulls, package), 6 mutations (delete, delete version, update package, deprecation, refresh-from-source, start audit), all derived state (isOwner, isAdmin, mergedContents, mergedFiles, etc.), 11 pieces of local UI state (7 modal toggles + skipValidation + 3 edit-state maps), 10 useCallback handlers, and the skill-id-change effect that resets modal toggles.
+
+Behavior unchanged; 110 web tests still pass.
diff --git a/.changeset/validate-body-sweep-438.md b/.changeset/validate-body-sweep-438.md
new file mode 100644
index 00000000..c0be58b1
--- /dev/null
+++ b/.changeset/validate-body-sweep-438.md
@@ -0,0 +1,21 @@
+---
+"ornn-api": patch
+---
+
+Sweep the `c.req.json().catch(() => ({}))` bypass pattern across ornn-api routes (#438). Every state-changing endpoint that previously parsed JSON manually now flows through the `validateBody(schema, code)` middleware so malformed bodies surface as RFC 7807 `400 invalid_body` instead of silently coercing to `{}` and bypassing schema validation.
+
+Affected:
+- `skills/crud/routes` — `POST /skills/pull`, `POST /skills/:id/refresh`, `PUT /skills/:id/source`, JSON branch of `PUT /skills/:id`
+- `skills/audit/routes` — both audit-trigger endpoints (owner + admin)
+- `skills/generation/routes` — `POST /skills/generate/from-source`, `POST /skills/generate/from-openapi`, JSON branch of `POST /skills/generate`
+- `skills/mirror/routes` — `POST /github/repo`
+- `announcements/routes` — admin create + patch
+- `broadcasts/routes` — admin create + patch
+- `settings/routes` — every per-section `PUT`
+- `settings/llmProviders/routes` — provider create / update / model patch
+- `settings/exportImport/routes` — `POST /admin/settings/import`
+- `platform/routes` — `PATCH /admin/settings`
+
+`validateBody` is also taught to tolerate an empty body (treats it as `{}`) when the schema has no required fields — that's the spot the bypass pattern was covering, and removing it without that tolerance would break the `POST /skills/:id/refresh`-with-no-body case the SPA uses.
+
+Endpoints with rich per-field validation that's hard to express in Zod (mirror config, platform settings) get a thin gate (`z.record(z.string(), z.unknown())`) so the SyntaxError path is covered, while leaving the existing field checks in place. Future PRs can swap those for full schemas without changing the wire contract.
diff --git a/.changeset/versions-modal-stale-699.md b/.changeset/versions-modal-stale-699.md
new file mode 100644
index 00000000..3b45a5f7
--- /dev/null
+++ b/.changeset/versions-modal-stale-699.md
@@ -0,0 +1,11 @@
+---
+"ornn-web": patch
+---
+
+The All-versions modal now drops a deleted version row immediately, and the result toast renders above any open modal (#699).
+
+Two distinct issues piled up after a version delete:
+
+1. **Stale list**: `useDeleteSkillVersion` invalidated `[SKILLS_KEY, idOrName]`, `[SKILLS_KEY]`, `[MY_SKILLS_KEY]`, and per-version audit caches, but not `[SKILL_VERSIONS_KEY, idOrName]` — the very query the All-versions modal subscribes to. So the deleted row stayed visible, and a second click on its delete button hit the backend with `SKILL_VERSION_NOT_FOUND`. Added the missing invalidation.
+
+2. **Obscured toast**: `ToastContainer` portal and the `Modal` portal both sit at `z-50`, so when both are mounted the toast is rendered behind the modal overlay and the success/error feedback for an in-modal action (delete or deprecate from the All-versions modal) becomes dim and unreadable. Bumped `ToastContainer` to `z-[60]` so toasts always sit above modals — single source of truth, no per-call escape hatches needed.
diff --git a/.changeset/zip-bomb-backend-caps-633.md b/.changeset/zip-bomb-backend-caps-633.md
new file mode 100644
index 00000000..aae26886
--- /dev/null
+++ b/.changeset/zip-bomb-backend-caps-633.md
@@ -0,0 +1,24 @@
+---
+"ornn-api": minor
+---
+
+Mirror the client-side `#443` zip-bomb defense on the backend (#633). Closes the gap surfaced during retrospective verification: an agent / SDK / `curl` client that bypasses the browser SPA could POST a 50 KB ZIP that uncompresses to 500 MB inside `validateZipFormat` or the AgentSeal subprocess.
+
+New `enforceZipLimits(zipBuffer)` in `shared/utils/zipLimits.ts` walks the ZIP central directory **without extracting** and throws RFC 7807 `413 Payload Too Large` (with stable `lowercase_snake_case` codes per CONVENTIONS.md §1.4) on any of:
+
+| Cap | Default | Error code |
+|---|---|---|
+| Cumulative uncompressed | 50 MiB | `uncompressed_too_large` |
+| Per-entry uncompressed | 25 MiB | `uncompressed_too_large` |
+| File count | 1000 | `too_many_files` |
+| Compression ratio | 50× (skipped for tiny ZIPs) | `uncompressed_too_large` |
+| Invalid ZIP | — | `invalid_zip` (400) |
+
+Wired into every authenticated upload path:
+- `POST /api/v1/skills` (create)
+- `PUT /api/v1/skills/:id` (update, only when a ZIP is actually replaced)
+- `POST /api/v1/skill-format/validate` (the standalone validator endpoint)
+
+Defaults match the client-side guard exactly so a ZIP that passes browser pre-flight also passes the server. Configurable via the function signature today (env-var hooks can ride in a follow-up if operators ask for them).
+
+8 unit tests cover the happy path, each cap, the invalid-ZIP fast-path, and the tiny-ZIP ratio-check carve-out.
diff --git a/.changeset/zip-validator-443.md b/.changeset/zip-validator-443.md
new file mode 100644
index 00000000..46fe7db3
--- /dev/null
+++ b/.changeset/zip-validator-443.md
@@ -0,0 +1,5 @@
+---
+"ornn-web": patch
+---
+
+Harden the client-side ZIP validator with two new guards (#443): (1) explicit zip-slip / unsafe-path rejection (entries with `..` segments, leading `/`, backslashes, or Windows drive letters) — defence-in-depth on top of JSZip's internal handling so a future unzip-library swap doesn't quietly turn into a path-traversal bug; (2) cumulative uncompressed-size cap (50 MB) read off `_data.uncompressedSize` during `forEach` so a zip-bomb never enters the extraction loop. New i18n keys `errors.zip.unsafePath` and `errors.zip.uncompressedTooLarge` (EN + ZH). 6 unit tests cover both guards.
diff --git a/.env.sample.compose b/.env.sample.compose
new file mode 100644
index 00000000..f5e35577
--- /dev/null
+++ b/.env.sample.compose
@@ -0,0 +1,14 @@
+# .env.compose.sample — copy to `.env` for `docker compose up`.
+#
+# Most knobs have safe dev defaults baked into docker-compose.yml.
+# Override here only when you need to override.
+
+# 32+ chars. The compose default is fine for dev; rotate for any
+# environment where the encrypted secrets actually matter.
+ENCRYPTION_KEY=dev-encryption-key-32-chars-min-12345
+
+# Bake the current commit into the SPA bundle's __APP_VERSION__ so
+# the version-check loop has a real identity. `git rev-parse --short HEAD`
+# is the canonical value; the compose file falls back to "compose-dev"
+# if unset.
+# GIT_COMMIT=$(git rev-parse --short HEAD)
diff --git a/.github/release-notes-20260529.md b/.github/release-notes-20260529.md
new file mode 100644
index 00000000..c89bca26
--- /dev/null
+++ b/.github/release-notes-20260529.md
@@ -0,0 +1,47 @@
+## Fixed
+
+- Returning to a tab no longer triggers an unexpected logout.
+- Saving a skill and logging in no longer fail with CORS errors.
+- Editing a skill's package no longer returns a 404.
+- Chat-completion LLM providers (e.g. DeepSeek) now work for generation.
+- Saving an LLM provider keeps its model list and default.
+- Playground keeps sandbox state — logins, installs — across tool calls.
+- Playground shows friendly errors and a proper not-found state.
+- Quota chip and banners now match the real remaining count.
+- Guided/Free create shows validation errors inline and respects backend rejects.
+- Frontmatter and settings errors now explain how to fix them.
+- Notifications sync, scroll fully, and toasts surface above modals.
+- Deactivated NyxID services no longer appear as filters.
+- Permissions modal flags shares pointing at removed users or orgs.
+- Skill Detail flags when the latest audit rerun failed.
+- Admin papercuts — display-name search, Mirror dashboard, recipients popover.
+- Private skill contents no longer leak through the JSON endpoint.
+- Playground no longer routes secret env values through the LLM.
+- Registry, admin tables, and creation flows now fully localize to Chinese.
+- Few technical bugs fixed.
+
+## New Feature
+
+- Cursor pagination on skill search, with an SDK auto-pagination iterator.
+- Dist-tags pin skill versions to named channels like latest and stable.
+- Idempotency-Key header makes state-changing requests retry-safe.
+- Sliding-window rate limiting with standard rate-limit headers.
+- Published JSON Schema for SKILL.md frontmatter, for editor autocomplete.
+- Subresource-Integrity hashes on version manifests for verified installs.
+- Install prompt now pins pull commands to the version you're viewing.
+- One-command local dev with docker-compose, plus starter example skills.
+- Technical enhancement.
+
+## Changed
+
+- Breaking: errors now use RFC 7807 problem+json with lowercase_snake_case codes.
+- Breaking: version writes require the skill GUID, not its name.
+- Breaking: deprecation is now signaled via standard RFC 8594 headers.
+- Breaking: removed the legacy `ownerId` field from skill responses.
+- Canonical `?q=` search param; the legacy `?query=` still works.
+- Resource-creating POSTs return 201 with a Location header.
+- "Skip validation" on import now also bypasses frontmatter checks.
+- Chat composer caps prompt length with a live counter.
+- Upload size and zip-bomb limits now enforced on the backend too.
+- Production builds no longer log auth or analytics to the browser console.
+- Technical enhancement.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 49acc866..80281ae8 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -28,7 +28,19 @@ jobs:
       - uses: actions/checkout@v6
       - uses: oven-sh/setup-bun@v2
       - run: bun install --frozen-lockfile
-      - run: bun run test
+      - run: bun run test:coverage
+      # Codecov upload (#471). No token needed for public repos.
+      # `directory: ./coverage` picks up the per-package lcov files
+      # that bun test --coverage writes into each workspace.
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        if: ${{ !cancelled() }}
+        with:
+          flags: bun
+          fail_ci_if_error: false
+          # Per-package lcov files land under coverage/ in each
+          # workspace; codecov-action recurses by default.
+          files: ./ornn-api/coverage/lcov.info,./ornn-web/coverage/lcov.info,./sdk/typescript/coverage/lcov.info
 
   python-sdk-test:
     runs-on: ubuntu-latest
@@ -42,9 +54,59 @@ jobs:
       - name: Install ornn-sdk (python)
         working-directory: sdk/python
         run: pip install -e ".[dev]"
-      - name: Run pytest
+      - name: Lint (ruff)
+        working-directory: sdk/python
+        run: ruff check .
+      - name: Format check (ruff)
+        working-directory: sdk/python
+        run: ruff format --check .
+      - name: Type check (mypy)
+        working-directory: sdk/python
+        run: mypy
+      - name: Run pytest with coverage
+        working-directory: sdk/python
+        run: pytest -q --cov=src/ornn_sdk --cov-report=xml --cov-report=term
+      # Codecov upload (#471) — same as the bun job but for the
+      # Python SDK's coverage.xml.
+      - name: Upload Python coverage to Codecov
+        uses: codecov/codecov-action@v4
+        if: ${{ !cancelled() }}
+        with:
+          flags: python
+          fail_ci_if_error: false
+          files: ./sdk/python/coverage.xml
+
+  # Audit the Python SDK's transitive deps for known CVEs (#445).
+  # We install the runtime deps directly (httpx + dev tools) rather
+  # than `pip install -e .` because pip-audit refuses editable
+  # installs of packages that aren't on PyPI yet (ornn-sdk is held
+  # for v1 per #473). The audit walks the resolved env via the OSV
+  # database — transitive deps (h11, anyio, certifi, idna, …) are
+  # all covered.
+  python-sdk-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install runtime + dev deps directly
+        working-directory: sdk/python
+        # Read the bounds from pyproject.toml without installing
+        # ornn-sdk itself. tomllib is stdlib in 3.11+; we're on 3.12.
+        run: |
+          python -c "
+          import tomllib, subprocess, sys
+          cfg = tomllib.load(open('pyproject.toml', 'rb'))
+          deps = cfg['project']['dependencies']
+          deps += cfg['project']['optional-dependencies']['dev']
+          subprocess.check_call([sys.executable, '-m', 'pip', 'install', *deps])
+          "
+          pip install pip-audit
+      - name: Audit dependencies
         working-directory: sdk/python
-        run: pytest -q
+        # `--strict` fails on any known CVE in the installed env.
+        run: pip-audit --strict
 
   build:
     runs-on: ubuntu-latest
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4e348e32..02c8bd55 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -28,7 +28,7 @@ By participating you agree to follow our [Code of Conduct](CODE_OF_CONDUCT.md) (
 
 ## Getting set up
 
-Prerequisites: [Bun](https://bun.sh), Docker, a local Kubernetes cluster for full integration runs.
+**For unit tests, lint, typecheck (most PRs):** [Bun](https://bun.sh) + Docker.
 
 ```bash
 git clone https://github.com/ChronoAIProject/Ornn.git
@@ -40,7 +40,16 @@ bun run typecheck
 bun run build:web
 ```
 
-Full local-cluster setup (MongoDB, MinIO, OpenSandbox, NyxID, Ornn services) is documented in the project `CLAUDE.md` under "Local Deployment". You do not need the full cluster to land code changes — unit tests alone are sufficient for most PRs.
+**For running the services locally (`docker compose`):**
+
+```bash
+cp .env.compose.sample .env
+docker compose up --build
+```
+
+Brings up MongoDB, MinIO, `ornn-api`, and `ornn-web`. Auth layer (NyxID) stays external — point at your own NyxID instance via env, or stick to the public endpoints (`/livez`, `/api/v1/skill-format/rules`, etc.) which work without auth. Issue #466.
+
+**For full integration runs (incl. NyxID, chrono-storage, chrono-sandbox, opensandbox):** local Kubernetes cluster. Long-form setup is in `CLAUDE.md` under "Local Deployment". You do not need the full cluster to land most PRs — unit tests + the `docker compose` stack are sufficient for the vast majority.
 
 ## Issue-first workflow
 
diff --git a/README.md b/README.md
index 945545c5..53a73cd0 100644
--- a/README.md
+++ b/README.md
@@ -1,121 +1,152 @@
 <p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="ornn-web/public/logo-dark.svg">
-    <img src="ornn-web/public/logo-light.svg" width="200" alt="Ornn" />
-  </picture>
+  <a href="https://ornn.chrono-ai.fun">
+    <img src="ornn-web/public/hero-brand-dark.svg" alt="Ornn — agent-facing skill-lifecycle API" width="100%" />
+  </a>
 </p>
 
-<p align="center">
+<p>
   <a href="https://github.com/ChronoAIProject/Ornn/actions/workflows/ci.yml"><img src="https://github.com/ChronoAIProject/Ornn/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
   <a href="https://github.com/ChronoAIProject/Ornn/releases"><img src="https://img.shields.io/github/v/release/ChronoAIProject/Ornn" alt="Latest release" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/github/license/ChronoAIProject/Ornn" alt="License" /></a>
-  <a href="https://github.com/ChronoAIProject/Ornn/commits/develop"><img src="https://img.shields.io/github/last-commit/ChronoAIProject/Ornn/develop" alt="Last commit" /></a>
-  <a href="https://github.com/ChronoAIProject/Ornn/discussions"><img src="https://img.shields.io/github/discussions/ChronoAIProject/Ornn" alt="Discussions" /></a>
-  <a href="https://github.com/ChronoAIProject/Ornn/stargazers"><img src="https://img.shields.io/github/stars/ChronoAIProject/Ornn?style=flat" alt="Stars" /></a>
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/status-alpha-orange" alt="Project status: alpha" />
-  <img src="https://img.shields.io/badge/model-agnostic-blue" alt="Model-agnostic" />
-  <img src="https://img.shields.io/badge/transport-HTTP%20%7C%20MCP-blueviolet" alt="HTTP and MCP" />
-</p>
-
-<p align="center"><strong>The agent-facing skill-lifecycle API for AI agents.</strong></p>
-
-<p align="center">
-  <a href="#what-is-ornn">What is Ornn</a> ·
-  <a href="#how-it-works">How it works</a> ·
-  <a href="#quickstart">Quickstart</a> ·
-  <a href="#documentation">Docs</a> ·
-  <a href="#roadmap">Roadmap</a> ·
-  <a href="#community">Community</a> ·
-  <a href="#contributing">Contributing</a>
+  &nbsp;<strong>The skill lifecycle API for AI agents, not another marketplace.</strong>
 </p>
 
 ---
 
 ## What is Ornn
 
-Ornn is an **agent-facing skill-lifecycle API**, not a human marketplace.
-
-The primary consumer is the AI agent developer / agentic-system builder. Agents call Ornn directly — over HTTP or MCP — to manage their own skill lifecycle:
+Ornn is an **agent-facing skill-lifecycle API**. AI agents call Ornn directly — over HTTPS — to manage the full lifecycle of their skills:
 
 ```
-search → pull → install → execute → build → upload → share
+search → pull → install → execute → audit → build → upload → share
 ```
 
-Closest analog: **npm registry + npm CLI fused, model-agnostic** — works for Claude, GPT, Gemini, or any custom runtime. Not locked to a single model.
+Closest analog: **npm registry + npm CLI, fused, model-agnostic.** It works for Claude, GPT, Gemini, or any custom agent runtime. Not locked to a single model.
+
+### Why we built it
+
+Modern AI agents do real work by composing **skills** — packaged prompts, scripts, and tools the agent invokes on demand. As soon as you build more than one agent, the same gaps show up:
+
+- **No shared registry.** Skills live in private repos, gists, and one-off config files. There's no way for an agent to discover one it doesn't already know about.
+- **Model-locked alternatives.** Anthropic Skills, OpenAI custom GPTs, and Gemini Gems each ship a registry — but only for their own runtime. Skills don't cross.
+- **No lifecycle.** Versioning, sandboxed execution, security audit, publish — every team rebuilds these from scratch.
 
-`ornn-web` is a secondary surface for skill owners and platform admins; it is not the primary product.
+Ornn closes the gaps. One model-agnostic registry, one API surface, and a CLI (`nyxid`) every agent can drive end-to-end. The web UI at [ornn.chrono-ai.fun](https://ornn.chrono-ai.fun) is a thin admin layer for skill owners; the API is the product.
 
 ## How it works
 
+```mermaid
+%%{init: {
+  "theme": "base",
+  "themeVariables": {
+    "background": "#0B0907",
+    "primaryColor": "#1A1610",
+    "primaryTextColor": "#F1ECDE",
+    "primaryBorderColor": "#3A3328",
+    "lineColor": "#7E776B",
+    "secondaryColor": "#221E16",
+    "tertiaryColor": "#14110B",
+    "edgeLabelBackground": "#0B0907",
+    "clusterBkg": "#14110B",
+    "clusterBorder": "#3A3328",
+    "fontFamily": "JetBrains Mono, ui-monospace, SFMono-Regular, Menlo, monospace",
+    "fontSize": "13px"
+  }
+}}%%
+flowchart LR
+    subgraph local["[ § YOUR MACHINE ]"]
+        direction TB
+        Agent["AI agent"]
+        CLI["nyxid CLI"]
+        Skill["Pulled skills"]
+    end
+    subgraph cloud["[ § ORNN CLOUD ]"]
+        direction TB
+        API["ornn-api"]
+        Auth["NyxID"]
+        Store[("Skill registry")]
+        Sandbox["Sandbox"]
+    end
+
+    Agent -->|invoke| CLI
+    CLI ==>|HTTPS| API
+    API -->|verify| Auth
+    API -->|r/w| Store
+    API -->|exec| Sandbox
+    API -.->|artifact| Agent
+    Agent -->|run| Skill
+
+    classDef ember fill:#FF7322,stroke:#C9460D,color:#14130E,stroke-width:2px,font-weight:bold
+    classDef arc fill:#5BC8E8,stroke:#3A8FB8,color:#14130E,stroke-width:2px,font-weight:bold
+    classDef forged fill:#1A1610,stroke:#3A3328,color:#F1ECDE,stroke-width:1.5px
+    classDef storage fill:#221E16,stroke:#3A3328,color:#C9BFAD,stroke-width:1.5px
+
+    class Agent forged
+    class CLI forged
+    class Skill forged
+    class Sandbox forged
+    class API ember
+    class Auth arc
+    class Store storage
+
+    style local fill:#221E16,stroke:#3A3328,color:#F1ECDE,stroke-width:1.5px
+    style cloud fill:#14110B,stroke:#3A3328,color:#F1ECDE,stroke-width:1.5px
+
+    linkStyle 1 stroke:#FF7322,stroke-width:2.5px
 ```
-┌──────────────┐    HTTP / MCP    ┌──────────────┐    auth     ┌──────────┐
-│   AI agent   │ ───────────────▶ │   ornn-api   │ ──────────▶ │  NyxID   │
-│ (any model)  │                  │              │             └──────────┘
-└──────────────┘                  │              │   storage   ┌──────────┐
-       │                          │              │ ──────────▶ │ MongoDB  │
-       │                          │              │             └──────────┘
-       │                          │              │   sandbox   ┌──────────┐
-       │ pull / execute           │              │ ──────────▶ │ OpenSbox │
-       ▼                          └──────────────┘             └──────────┘
-┌──────────────┐
-│ Local skill  │
-│   runtime    │
-└──────────────┘
-```
-
-The agent talks to `ornn-api` through `nyxid`, which brokers authentication and authorization on the agent's behalf. Skills are versioned artifacts that the agent pulls, runs in a sandbox, and (optionally) publishes back.
 
-For a deeper view, see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+Every API call is mediated by [`nyxid`](https://github.com/ChronoAIProject/NyxID) — the shared identity + brokering layer ChronoAI uses across products. The agent never holds a long-lived token: `nyxid` refreshes credentials transparently and brokers per-service access for each request.
 
 ## Quickstart
 
-> **Status:** alpha. Surfaces and schemas can change before v1. Pin a release tag.
+> **Status:** alpha. The API surface can still change before v1 — pin a release tag if you ship to production.
 
-The shortest path to bringing an agent online with Ornn — no manual operator steps inside the agent loop:
+### 1. Create a NyxID account
 
-1. **Install the ChronoAI core service skill into your agent.** This is the bootstrap skill — it introduces Ornn to the agent and drives the rest of setup.
-2. **Let the agent provision the NyxID CLI.** On first run, the core skill instructs the agent to install `nyxid`. The agent follows the skill end-to-end.
-3. **Talk to the agent.** Ask it to search, install, run, build, or publish skills. The agent learns the lifecycle through the same API it just connected to.
+Sign up at [**nyx.chrono-ai.fun**](https://nyx.chrono-ai.fun) with invite code **`NYX-2XXJI08A`**. Sign in with **GitHub**, **Google**, or **Apple** — NyxID is the identity layer that authenticates every Ornn API call. One account covers every ChronoAI service.
 
-Once connected, an agent can hit the API directly. A minimal request shape (after `nyxid` is configured):
+### 2. Install the Ornn agent manual into your AI agent
 
-```bash
-nyxid proxy request ornn-api GET /api/v1/skills?q=summarize
-```
+Open [**`ornn-agent-manual-cli`**](https://ornn.chrono-ai.fun/skills/ornn-agent-manual-cli) and follow the install instructions for your agent runtime (Claude Code, OpenAI Codex, Cursor, …). This skill is the **operational manual Ornn ships for AI agents**: once it's loaded into your agent, the agent knows how to drive the full `search → pull → execute → build → upload → share` lifecycle on its own — no further hand-holding required.
+
+Partway through setup, your agent will prompt you to install [**`nyxid`**](https://github.com/ChronoAIProject/NyxID) — the CLI Ornn calls under the hood to broker authenticated requests. Approve the prompt; the agent finishes onboarding itself.
+
+### 3. Talk to your agent
+
+That's it. Your agent now has the full Ornn lifecycle. Try any of these in plain language — no special syntax, no flags to memorise:
 
-Full per-endpoint reference: [ornn.chrono-ai.fun/docs](https://ornn.chrono-ai.fun/docs).
+- **Search the registry.**
+  > *"Find me a skill that converts CSV to JSON."*
 
-## Documentation
+  Hits semantic + keyword search across every public skill.
 
-- **Product docs** — [ornn.chrono-ai.fun/docs](https://ornn.chrono-ai.fun/docs)
-- **Architecture** — [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
-- **Conventions** — [`docs/CONVENTIONS.md`](docs/CONVENTIONS.md)
-- **Design system** — [`docs/DESIGN.md`](docs/DESIGN.md)
+- **Pull and install a skill.**
+  > *"Pull and install the skill `pdf-extractor`, then use it on `report.pdf`."*
 
-## Roadmap
+  Fetches the latest versioned artifact into your local runtime and runs it.
 
-Tracked publicly on GitHub:
+- **Trigger a security audit.**
+  > *"Run a security audit on the skill `web-scraper`."*
 
-- **Open issues & milestones** — [Issues](https://github.com/ChronoAIProject/Ornn/issues) · [Milestones](https://github.com/ChronoAIProject/Ornn/milestones)
-- **What shipped** — [Releases](https://github.com/ChronoAIProject/Ornn/releases) · per-package changelogs in [`ornn-api/CHANGELOG.md`](ornn-api/CHANGELOG.md) and [`ornn-web/CHANGELOG.md`](ornn-web/CHANGELOG.md)
+  Kicks the AgentSeal pipeline against a published version — static analysis, sandbox probe, dependency scan.
 
-## Community
+- **Build and publish a new skill.**
+  > *"Build me a skill that summarises RSS feeds and upload it under my account."*
+
+  Drives `ornn-build` to generate the skill, packages it, and publishes a new version through your NyxID identity.
+
+For the full API contract (every endpoint, every error code), see [**ornn.chrono-ai.fun/docs**](https://ornn.chrono-ai.fun/docs).
+
+## Community and Contributing
 
 - **Questions / how-to** → [Discussions → Q&A](https://github.com/ChronoAIProject/Ornn/discussions/categories/q-a)
 - **Ideas / RFCs** → [Discussions → Ideas](https://github.com/ChronoAIProject/Ornn/discussions/categories/ideas)
 - **Show off your agent integration** → [Discussions → Show & Tell](https://github.com/ChronoAIProject/Ornn/discussions/categories/show-and-tell)
 - **Bug or feature** → [open an issue](https://github.com/ChronoAIProject/Ornn/issues/new/choose)
-- **Security report** → [Private Vulnerability Reporting](https://github.com/ChronoAIProject/Ornn/security/advisories/new) — see [SECURITY.md](SECURITY.md)
+- **Roadmap** → [Issues](https://github.com/ChronoAIProject/Ornn/issues) · [Milestones](https://github.com/ChronoAIProject/Ornn/milestones) · [Releases](https://github.com/ChronoAIProject/Ornn/releases)
+- **Security report** → [Private Vulnerability Reporting](https://github.com/ChronoAIProject/Ornn/security/advisories/new) (see [SECURITY.md](SECURITY.md))
 - **Support guide** → [SUPPORT.md](SUPPORT.md)
-
-## Contributing
-
-Pull requests are welcome. Before opening one, read [CONTRIBUTING.md](CONTRIBUTING.md) — it covers the issue-first workflow, branching, commit decomposition, and the changeset rule (CI blocks PRs without one).
-
-By participating you agree to follow our [Code of Conduct](CODE_OF_CONDUCT.md).
+- **Pull requests** → read [CONTRIBUTING.md](CONTRIBUTING.md) first — it covers the issue-first workflow, branching, commit decomposition, and the changeset rule (CI blocks PRs without one). By participating you agree to follow our [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## License
 
diff --git a/codecov.yml b/codecov.yml
new file mode 100644
index 00000000..d4903a7b
--- /dev/null
+++ b/codecov.yml
@@ -0,0 +1,57 @@
+# Codecov configuration for chrono-ornn (#471).
+#
+# Reports are uploaded from two CI jobs:
+#   - `test`            → flag `bun` (per-workspace lcov)
+#   - `python-sdk-test` → flag `python` (sdk/python coverage.xml)
+#
+# Target is realistic-not-aspirational: 70% project coverage as the
+# initial commitment. Files that are deliberately not covered today
+# (god-files, generation prompts, infra shims) are excluded so the
+# headline number reflects code that's reasonably testable.
+
+coverage:
+  status:
+    project:
+      default:
+        target: 70%
+        threshold: 1%
+        if_ci_failed: error
+    patch:
+      default:
+        target: 80%
+        threshold: 5%
+        if_ci_failed: error
+
+# Source-of-truth flags. Codecov sums across flags by default; both
+# are surfaced separately in the PR comment so a regression in one
+# language is obvious.
+flags:
+  bun:
+    paths:
+      - ornn-api/src/
+      - ornn-web/src/
+      - sdk/typescript/src/
+    carryforward: true
+  python:
+    paths:
+      - sdk/python/src/
+    carryforward: true
+
+ignore:
+  # God-files awaiting decomposition (#453, #580). Excluded from the
+  # headline number until they're broken up.
+  - "ornn-web/src/pages/skill/SkillDetailPage.tsx"
+  - "ornn-web/src/pages/DocsPage.tsx"
+  - "ornn-web/src/pages/PlaygroundPage.tsx"
+  - "ornn-api/src/bootstrap.ts"
+  # Prompt-template strings, scaffolding scripts, generated code.
+  - "**/*.test.ts"
+  - "**/*.test.py"
+  - "**/__pycache__/**"
+  - "ornn-api/scripts/**"
+  - "examples/**"
+
+comment:
+  layout: "reach,diff,flags,tree"
+  behavior: default
+  require_changes: false
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 00000000..0fc0a574
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,127 @@
+# docker-compose.yml — one-command local dev (#466).
+#
+# Brings up the data layer (MongoDB + MinIO) plus the two ornn services
+# (`ornn-api` + `ornn-web`). The auth layer (NyxID) stays external — you
+# either run it separately via the existing `deployment/dependencies/`
+# Kubernetes manifests OR point at a hosted NyxID staging via env.
+#
+# Usage:
+#   cp .env.compose.sample .env
+#   docker compose up --build
+#   open https://localhost:5173    # ornn-web (proxies /api/v1/* → ornn-api)
+#
+# To stop:
+#   docker compose down
+#   docker compose down -v          # also removes persistent volumes
+#
+# Production parity is intentionally NOT a goal — that's what the K8s
+# manifests under `deployment/` are for. This compose is a fast,
+# zero-cluster path for contributors who want to run unit + integration
+# tests + a working ornn-api locally.
+
+services:
+  mongodb:
+    image: mongo:7
+    container_name: ornn-dev-mongodb
+    restart: unless-stopped
+    ports:
+      - "27017:27017"
+    environment:
+      MONGO_INITDB_ROOT_USERNAME: ornn
+      MONGO_INITDB_ROOT_PASSWORD: ornn_dev_password
+    volumes:
+      - mongodb-data:/data/db
+    # Health check so dependents wait until Mongo is actually ready.
+    healthcheck:
+      test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping')"]
+      interval: 5s
+      timeout: 5s
+      retries: 12
+      start_period: 10s
+
+  minio:
+    image: minio/minio:latest
+    container_name: ornn-dev-minio
+    restart: unless-stopped
+    command: server /data --console-address ":9001"
+    ports:
+      - "9000:9000" # S3 API
+      - "9001:9001" # Web console
+    environment:
+      MINIO_ROOT_USER: ornn
+      MINIO_ROOT_PASSWORD: ornn_dev_password
+    volumes:
+      - minio-data:/data
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
+      interval: 5s
+      timeout: 5s
+      retries: 12
+      start_period: 10s
+
+  # ornn-api boots without an external NyxID. Auth-required endpoints
+  # return 401 — fine for running the test suite or hitting public
+  # /livez. For end-to-end use, set NYXID_BASE_URL via your local .env.
+  ornn-api:
+    build:
+      context: .
+      dockerfile: ornn-api/Dockerfile
+    image: ornn-api:dev
+    container_name: ornn-dev-api
+    restart: unless-stopped
+    depends_on:
+      mongodb:
+        condition: service_healthy
+      minio:
+        condition: service_healthy
+    ports:
+      - "3802:3802"
+    environment:
+      PORT: "3802"
+      LOG_LEVEL: "info"
+      LOG_PRETTY: "true"
+      MONGODB_URI: "mongodb://ornn:ornn_dev_password@mongodb:27017/ornn?authSource=admin"
+      MONGODB_DB: "ornn"
+      ALLOWED_ORIGINS: "http://localhost:5173,http://ornn-web:80"
+      # 32+ chars required (Zod gate at boot). Dev-only fixed value.
+      ENCRYPTION_KEY: "${ENCRYPTION_KEY:-dev-encryption-key-32-chars-min-12345}"
+      ORNN_PUBLIC_ORIGIN: "http://localhost:3802"
+      # No agentseal binary in this image — disable the scanner so the
+      # boot-time path validator from #442 doesn't fail.
+      AGENTSEAL_ENABLED: "false"
+      AGENTSEAL_PYTHON: "/usr/bin/env"
+      AGENTSEAL_SCRIPT: "/usr/bin/env"
+      # PostHog telemetry off by default in compose.
+      POSTHOG_ENABLED: "false"
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://localhost:3802/livez || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 6
+      start_period: 20s
+
+  ornn-web:
+    build:
+      context: .
+      dockerfile: ornn-web/Dockerfile
+      args:
+        GIT_COMMIT: "${GIT_COMMIT:-compose-dev}"
+    image: ornn-web:dev
+    container_name: ornn-dev-web
+    restart: unless-stopped
+    depends_on:
+      ornn-api:
+        condition: service_healthy
+    ports:
+      - "5173:80"
+    environment:
+      # The web container's nginx serves the SPA + injects runtime
+      # config from this env at startup. ORNN_API_BASE_URL is what
+      # the SPA fetches from — point it at the host-side port.
+      ORNN_API_BASE_URL: "http://localhost:3802/api/v1"
+
+volumes:
+  mongodb-data:
+    name: ornn-dev-mongodb-data
+  minio-data:
+    name: ornn-dev-minio-data
diff --git a/docs/API_STABILITY.md b/docs/API_STABILITY.md
new file mode 100644
index 00000000..90011e6f
--- /dev/null
+++ b/docs/API_STABILITY.md
@@ -0,0 +1,111 @@
+# API Stability & Deprecation
+
+This document is the public commitment about what Ornn's `/api/v1/*` surface guarantees, what it does not guarantee, and how breaking changes are communicated.
+
+It is a normative companion to [`docs/CONVENTIONS.md`](CONVENTIONS.md) — when a route is added or removed, its stability tier MUST be declared here (and in the OpenAPI spec) before the PR lands.
+
+---
+
+## Current state
+
+> **Status: alpha (v0.x).**
+>
+> We make **no compatibility guarantees** for the `0.x` release line. Any minor version (`0.7 → 0.8`) MAY contain breaking changes to routes, response shapes, error codes, headers, or SDK signatures.
+>
+> Pinning to an exact version (`@chronoai/ornn-sdk@0.7.3`, `ornn-sdk==0.7.3`) is the only way to insulate downstream code from churn during alpha.
+
+CHANGELOG entries for each release call out breaking changes inline; see [`ornn-api/CHANGELOG.md`](../ornn-api/CHANGELOG.md) and [`ornn-web/CHANGELOG.md`](../ornn-web/CHANGELOG.md).
+
+The exit criteria from alpha to **v1.0** are tracked in milestone [M5 — QA Pre-Launch Gate](https://github.com/ChronoAIProject/Ornn/milestones).
+
+---
+
+## Versioning policy (post-v1)
+
+Once `v1.0.0` ships, Ornn follows [Semantic Versioning](https://semver.org/) for both the HTTP API and the SDK packages:
+
+| Bump | Example | Allowed changes |
+|---|---|---|
+| **patch** | `1.2.3 → 1.2.4` | Bug fixes. No observable behaviour change. |
+| **minor** | `1.2 → 1.3` | Backward-compatible additions: new endpoints, new optional request fields, new response fields, new tiered features. |
+| **major** | `1.x → 2.0` | Breaking changes. Preceded by ≥ 2 minor releases marking the affected routes deprecated (see below). |
+
+The API path version (`/api/v1/...`) is bumped only on a major release that requires it. Most major releases will keep `/v1/` and rely on per-route deprecation signalling.
+
+---
+
+## Stability tiers
+
+Every route declares one of three tiers in the OpenAPI spec via the `x-stability` extension. The SDK exposes the same tier so clients can opt in or warn.
+
+### `stable`
+
+- Covered by the post-v1 semver commitment above.
+- Breaking changes only at a major version bump, after deprecation.
+- Default tier for `/api/v1/*` routes in the canonical surface.
+
+### `beta`
+
+- Subject to change in any minor release.
+- Useful for features we want feedback on before locking the contract.
+- Clients opt in by passing the header `Accept-Stability: beta`. Without that header the SDK refuses to call beta endpoints.
+
+### `experimental`
+
+- May change or disappear in any release, including patch.
+- Not exposed via the default SDK clients; reached only by raw HTTP or by passing `Accept-Stability: experimental`.
+- Used for shipping prototypes alongside a stable surface.
+
+---
+
+## Deprecation policy
+
+When a stable route or response field is deprecated, Ornn follows [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html):
+
+```http
+HTTP/1.1 200 OK
+Deprecation: true
+Sunset: Wed, 01 Jan 2027 00:00:00 GMT
+Link: <https://github.com/ChronoAIProject/Ornn/blob/main/docs/DEPRECATIONS.md#skill-version-v1>; rel="deprecation"
+```
+
+### Lead time
+
+- **Minimum:** the `Sunset` date is set at least **two minor releases** in the future from the release that introduces the `Deprecation: true` header.
+- For routes called by published SDK versions, the sunset date is also at least **90 days** in the future.
+
+### Signal channels
+
+Every deprecation is announced through **all** of the following at the same time:
+
+1. **`Deprecation` + `Sunset` headers** on every response from the deprecated route, from the release that flips the deprecation flag until the route is removed.
+2. **CHANGELOG entry** in the release that introduces the deprecation, under a `### Deprecated` heading.
+3. **Entry in [`docs/DEPRECATIONS.md`](DEPRECATIONS.md)** with route, sunset date, migration path, and the `Link: rel="deprecation"` anchor used in the header.
+4. **GitHub release notes** linking to the `DEPRECATIONS.md` entry.
+
+### Removal
+
+- A deprecated route is removed only after its `Sunset` date has passed and a major version has shipped.
+- Removal lands in a separate PR titled `chore(api): remove deprecated <route> (sunset <date>)` that closes the deprecation entry.
+
+---
+
+## Breaking-change checklist
+
+Before merging a PR that breaks a `stable` route:
+
+- [ ] PR title contains `BREAKING` or the commit footer carries `BREAKING CHANGE:`
+- [ ] CHANGELOG `### Breaking` entry written, with migration guidance
+- [ ] `docs/DEPRECATIONS.md` entry added (even if removal is far out)
+- [ ] OpenAPI `x-stability` updated if the route is moving tiers
+- [ ] If the SDK surface changes, the SDK READMEs and `examples/` snippets are updated
+- [ ] Linked issue carries the `breaking-change` label
+
+The `check-changeset` workflow enforces that every PR has a changeset; breaking-change PRs MUST use a `major` bump on the affected package.
+
+---
+
+## Open questions
+
+1. **API version negotiation header.** `Accept-Stability` is currently a draft. If we adopt a different name pre-v1, both the convention and the SDKs change together — track in a separate issue before v1.
+2. **`/api/v2/`.** Will exist if and only if a breaking change can't be safely signalled via per-route deprecation. The current expectation is that it never ships during 1.x.
diff --git a/docs/CONVENTIONS.md b/docs/CONVENTIONS.md
index d68a4e4a..56953d63 100644
--- a/docs/CONVENTIONS.md
+++ b/docs/CONVENTIONS.md
@@ -68,7 +68,7 @@ Content-Type: application/problem+json
 X-Request-ID: req_01HXYZ...
 
 {
-  "type": "https://github.com/ChronoAIProject/Ornn/blob/main/docs/errors.md#validation_error",
+  "type": "https://github.com/ChronoAIProject/Ornn/blob/main/docs/ERRORS.md#validation_error",
   "title": "Validation failed",
   "status": 400,
   "detail": "Request body failed validation",
@@ -112,10 +112,10 @@ New codes require convention-doc update. Handlers MUST NOT invent ad-hoc codes.
 Point to GitHub markdown anchors in this repository:
 
 ```
-https://github.com/ChronoAIProject/Ornn/blob/main/docs/errors.md#<code>
+https://github.com/ChronoAIProject/Ornn/blob/main/docs/ERRORS.md#<code>
 ```
 
-A matching `docs/errors.md` must exist with `##` headings per error code (GitHub auto-generates anchors). Zero infra cost; resolves day one. Future migration to a docs domain (`docs.ornn.xyz`) is a one-time redirect configuration; no client changes required.
+The catalog lives in [`docs/ERRORS.md`](ERRORS.md) with `##` headings per code (GitHub auto-generates anchors). Zero infra cost; resolves day one. Future migration to a docs domain (`docs.ornn.xyz`) is a one-time redirect configuration; no client changes required.
 
 ---
 
@@ -340,12 +340,14 @@ Endpoints pick a subset and MAY add endpoint-specific events with the same prefi
 
 ## 7. Deprecation
 
+See [`docs/API_STABILITY.md`](API_STABILITY.md) for the public stability commitment, per-route tiers, and the full deprecation lead-time policy. This section codifies the header shape only.
+
 Per RFC 8594 on deprecated endpoints and representations:
 
 ```
 Deprecation: true
 Sunset: Wed, 01 Jan 2027 00:00:00 GMT
-Link: <https://github.com/ChronoAIProject/Ornn/blob/main/docs/deprecations.md#skill-version-v1>; rel="deprecation"
+Link: <https://github.com/ChronoAIProject/Ornn/blob/main/docs/DEPRECATIONS.md#skill-version-v1>; rel="deprecation"
 ```
 
 Free-form notes go in response body, not custom headers. No `X-Skill-Deprecated` style custom headers.
@@ -376,6 +378,22 @@ Every response carries:
 - CI contract test asserts every handler in code appears in the spec with complete metadata.
 - Error `type` URLs point to live documentation per § 1.6.
 
+### 10.1 Skill manifest JSON Schema
+
+The canonical JSON Schema for `SKILL.md` YAML frontmatter is published at:
+
+```
+GET /api/v1/skill-manifest-schema.json
+```
+
+- Generated from the Zod source of truth (`ornn-api/src/shared/schemas/skillFrontmatter.ts`) at server boot — the published schema cannot drift from the runtime validator.
+- Output is JSON Schema **draft-2020-12** (`$schema`) — what current IDEs (VS Code, Cursor, JetBrains) and `schemastore.org` consume.
+- Served with `Content-Type: application/schema+json` (IANA registration). No `{ data, error }` envelope — the body root is the schema document itself, because that's what schema-store tools expect.
+- Public, no auth required. `Cache-Control: public, max-age=3600`.
+- `SKILL_MANIFEST_SCHEMA_VERSION` (currently `"1"`) is bumped manually when the frontmatter contract changes in a way external tooling cares about. Out of an abundance of caution while we're pre-1.0, this version is not yet baked into the URL; consumers should re-fetch on a finite TTL.
+
+Skill authors and tooling SHOULD point their YAML language servers at this URL via `# yaml-language-server: $schema=...` so SKILL.md gets autocomplete + inline validation.
+
 ---
 
 ## 11. Architecture conventions
diff --git a/docs/DEPRECATIONS.md b/docs/DEPRECATIONS.md
new file mode 100644
index 00000000..ca43b0fa
--- /dev/null
+++ b/docs/DEPRECATIONS.md
@@ -0,0 +1,50 @@
+# Ornn API Deprecations
+
+The public log of every deprecated route, response field, or header on `/api/v1/*`. The companion to [`docs/API_STABILITY.md`](API_STABILITY.md) (policy) and [`docs/CONVENTIONS.md`](CONVENTIONS.md) §7 (header shape).
+
+Per `docs/API_STABILITY.md` § Deprecation policy, every entry below carries:
+
+- **Anchor** — used in the `Link: <…>; rel="deprecation"` header so clients can deep-link from the response.
+- **Deprecated in** — the release that first set `Deprecation: true`.
+- **Sunset on** — the date the route MAY be removed (at the earliest).
+- **Replacement** — the route or field clients should migrate to.
+- **Migration notes** — what changes for the caller.
+
+When a deprecated route is removed, its entry stays in this file but moves to the [Removed](#removed) section so the anchor URL keeps resolving.
+
+---
+
+## Active deprecations
+
+*None.* While Ornn is in alpha (`0.x`), breaking changes go straight into the next minor release without a deprecation cycle — see [`docs/API_STABILITY.md`](API_STABILITY.md) § Current state. This section starts populating once the API exits alpha and the post-v1 policy kicks in.
+
+---
+
+## Removed
+
+*None.*
+
+---
+
+## How an entry will look
+
+When the first deprecation lands, it will look like this:
+
+```markdown
+### skill-version-v1
+
+- **Anchor:** `skill-version-v1`
+- **Deprecated in:** `1.4.0` (2026-09-15)
+- **Sunset on:** `1.6.0` or 2026-12-15, whichever is later
+- **Replacement:** `GET /api/v1/skills/:id/versions/:version` → use `GET /api/v1/skills/:id/versions/:version?manifest=v2`
+- **Migration notes:** the response gains a `runtime: { type, entrypoint }` block and drops the flat `runtimeType` / `entrypoint` fields. Clients reading the v1 shape continue to work until sunset; the SDK auto-upgrades when `Accept-Stability: stable` is set.
+```
+
+Response headers from a deprecated route would carry:
+
+```http
+HTTP/1.1 200 OK
+Deprecation: true
+Sunset: Tue, 15 Dec 2026 00:00:00 GMT
+Link: <https://github.com/ChronoAIProject/Ornn/blob/main/docs/DEPRECATIONS.md#skill-version-v1>; rel="deprecation"
+```
diff --git a/docs/ERRORS.md b/docs/ERRORS.md
new file mode 100644
index 00000000..f30aac11
--- /dev/null
+++ b/docs/ERRORS.md
@@ -0,0 +1,203 @@
+# Ornn API Error Catalog
+
+Every error response from `/api/v1/*` carries a stable `code` (string) and the matching `type` URL points back to a section in this document via GitHub anchor link:
+
+```
+type: https://github.com/ChronoAIProject/Ornn/blob/main/docs/ERRORS.md#<code>
+```
+
+The catalog is normative — handlers MUST NOT invent new codes. Adding or renaming a code requires updating this doc and `docs/CONVENTIONS.md` §1.4 in the same PR.
+
+All codes are `lowercase_snake_case` per CONVENTIONS.md §1.4. The §1.4 catalog defines the **parent** taxonomy (`validation_error`, `permission_denied`, `resource_not_found`, …); specific subcodes (e.g. `skill_not_found` under `resource_not_found`) live under the parent's section here and follow the same lowercase format.
+
+The pre-#585 `SCREAMING_SNAKE_CASE` shape (`SKILL_NOT_FOUND`, `INVALID_BODY`, …) is no longer emitted. Clients that pinned to those strings need to switch to the lowercase form on the next SDK bump.
+
+---
+
+## Table of Contents
+
+**By HTTP status**
+
+- 400 — [`validation_error`](#validation_error)
+- 401 — [`authentication_required`](#authentication_required)
+- 403 — [`permission_denied`](#permission_denied)
+- 404 — [`resource_not_found`](#resource_not_found)
+- 409 — [`resource_conflict`](#resource_conflict)
+- 413 — [`payload_too_large`](#payload_too_large)
+- 415 — [`unsupported_media_type`](#unsupported_media_type)
+- 429 — [`rate_limited`](#rate_limited)
+- 500 — [`internal_error`](#internal_error)
+- 502 / 503 — [`upstream_unavailable`](#upstream_unavailable)
+
+**Pre-#585 migration map** — every `SCREAMING_SNAKE_CASE` code clients used to receive, with the new `lowercase_snake_case` it became: [Appendix](#appendix-pre-585-migration-map).
+
+---
+
+## validation_error
+
+**HTTP:** `400 Bad Request`
+**Common subcodes (lowercase post-#585):** `invalid_body`, `invalid_query`, `invalid_params`, `invalid_*` (per-field), `empty_body`, `missing_*`, `frontmatter_validation_failed`, `invalid_permissions`, …
+
+Request body, query string, or path parameter failed validation. Per-field details are in `errors[]`.
+
+```http
+HTTP/1.1 400 Bad Request
+Content-Type: application/problem+json
+
+{
+  "type": "https://github.com/ChronoAIProject/Ornn/blob/main/docs/ERRORS.md#validation_error",
+  "title": "Validation failed",
+  "status": 400,
+  "detail": "Request body failed validation",
+  "instance": "/v1/skills/abc/permissions",
+  "requestId": "req_01HXYZ...",
+  "errors": [
+    { "path": "sharedWithUsers[3]", "code": "invalid_user_id", "message": "..." }
+  ]
+}
+```
+
+**Client action:** fix the offending field(s) listed in `errors[]` and retry. Do not retry the same payload without changes.
+
+---
+
+## authentication_required
+
+**HTTP:** `401 Unauthorized`
+**Common subcodes (lowercase post-#585):** `auth_missing`, `auth_invalid`
+
+No identity could be resolved from the request — either no `Authorization` header, an unparseable header, or the token is expired / revoked.
+
+**Client action:** refresh the access token (via NyxID) and retry once. If refresh fails, the user needs to re-authenticate.
+
+---
+
+## permission_denied
+
+**HTTP:** `403 Forbidden`
+**Common subcodes (lowercase post-#585):** `forbidden`, `insufficient_permissions`
+
+The caller is authenticated but lacks the permission required for this resource or action. The response `detail` names the missing permission when safe to disclose.
+
+**Client action:** check the user's roles / org membership against [`docs/CONVENTIONS.md`](CONVENTIONS.md) §5. Surface the gap to the user; do not silently retry.
+
+---
+
+## resource_not_found
+
+**HTTP:** `404 Not Found`
+**Common subcodes (lowercase post-#585):** `skill_not_found`, `skill_version_not_found`, `org_not_found`, `provider_not_found`, `announcement_not_found`, `broadcast_not_found`, `notification_not_found`, `audit_not_found`, `redemption_code_not_found`, …
+
+The target resource does not exist, **or** it exists but is not visible to the caller (private skill outside their access scope). The two cases are intentionally not distinguished — disclosing existence is itself information.
+
+**Client action:** for known-good identifiers, this likely means a visibility issue. For typed identifiers, verify the GUID / name.
+
+---
+
+## resource_conflict
+
+**HTTP:** `409 Conflict`
+**Common subcodes (lowercase post-#585):** `skill_name_exists`, `reconcile_already_running`, `redemption_code_expired`, `redemption_code_already_redeemed`, `redemption_code_already_invalidated`, `old_repo_not_confirmed`, …
+
+The request collides with current state — a duplicate skill name on create, a concurrent modification, a job that's already running, etc.
+
+**Client action:** read `detail` to decide. For duplicates, prompt the user for a different value. For concurrent modifications, refetch and retry.
+
+---
+
+## payload_too_large
+
+**HTTP:** `413 Payload Too Large`
+**Common subcodes (lowercase post-#585):** `payload_too_large`
+
+The upload exceeds the per-endpoint size cap (currently 5 MB on `/skills` upload; see `ornn-api/src/middleware/uploadLimit.ts`).
+
+**Client action:** trim the payload (smaller ZIP, fewer attachments) or split into multiple requests where the endpoint supports it.
+
+---
+
+## unsupported_media_type
+
+**HTTP:** `415 Unsupported Media Type`
+**Common subcodes (lowercase post-#585):** `invalid_content_type`
+
+The `Content-Type` header is missing or names a representation this endpoint does not accept. Skill upload requires `application/zip`; most write endpoints require `application/json`.
+
+**Client action:** set the correct `Content-Type` header and retry.
+
+---
+
+## rate_limited
+
+**HTTP:** `429 Too Many Requests`
+**Common subcodes (lowercase post-#585):** *not yet emitted — see [#439](https://github.com/ChronoAIProject/Ornn/issues/439) (rate limit middleware).*
+
+Caller exceeded a rate limit (per-IP for unauthenticated routes, per-user for authenticated). Once [#460](https://github.com/ChronoAIProject/Ornn/issues/460) lands, response will also include the standard RFC 9239 headers (`RateLimit-Limit`, `RateLimit-Remaining`, `Retry-After`).
+
+**Client action:** honour `Retry-After` (seconds). SDK retry wrappers should back off exponentially with jitter, capped at the `Retry-After` value.
+
+---
+
+## internal_error
+
+**HTTP:** `500 Internal Server Error`
+**Common subcodes (lowercase post-#585):** `internal_error`
+
+Unhandled server error — should never appear under normal operation. The `requestId` is the load-bearing field for log correlation.
+
+**Client action:** capture `requestId` and report. Safe to retry once; do not retry tighter than every few seconds.
+
+---
+
+## upstream_unavailable
+
+**HTTP:** `502 Bad Gateway` / `503 Service Unavailable`
+**Common subcodes (lowercase post-#585):** `upstream_down`, `mirror_disabled`, `agentseal_disabled`, `pull_failed`, `repo_fetch_failed`, `refresh_failed`, `refresh_preview_failed`, `auth_service_error`, `audit_package_unavailable`, `package_download_failed`, …
+
+A dependency Ornn relies on (NyxID, OpenSandbox, LLM provider, mirror target, …) is unavailable or refused the request. Distinct from `internal_error` — Ornn itself is fine but couldn't complete the work.
+
+**Client action:** retry with exponential backoff. If the failure persists, check [status.chrono-ai.fun](https://status.chrono-ai.fun) (when published) or [Discussions → Q&A](https://github.com/ChronoAIProject/Ornn/discussions/categories/q-a).
+
+---
+
+## Appendix: pre-#585 migration map
+
+Clients pinned to the old `SCREAMING_SNAKE_CASE` codes need to switch to the lowercase forms below. Every code is now a one-for-one lowercase translation — the §1.4 parent category is the same.
+
+| Pre-#585 code | HTTP | New code | §1.4 parent |
+|---|---|---|---|
+| `AGENTSEAL_DISABLED` | 503 | `agentseal_disabled` | `upstream_unavailable` |
+| `ANNOUNCEMENT_NOT_FOUND` | 404 | `announcement_not_found` | `resource_not_found` |
+| `AUDIT_NOT_FOUND` | 404 | `audit_not_found` | `resource_not_found` |
+| `AUTH_INVALID` | 401 | `auth_invalid` | `authentication_required` |
+| `AUTH_MISSING` | 401 | `auth_missing` | `authentication_required` |
+| `AUTH_SERVICE_ERROR` | 503 | `auth_service_error` | `upstream_unavailable` |
+| `BROADCAST_NOT_FOUND` | 404 | `broadcast_not_found` | `resource_not_found` |
+| `EMPTY_BODY` | 400 | `empty_body` | `validation_error` |
+| `EMPTY_SOURCE` | 400 | `empty_source` | `validation_error` |
+| `FORBIDDEN` | 403 | `forbidden` | `permission_denied` |
+| `FRONTMATTER_VALIDATION_FAILED` | 400 | `frontmatter_validation_failed` | `validation_error` |
+| `INTERNAL` / `INTERNAL_ERROR` | 500 | `internal_error` | `internal_error` |
+| `INVALID_*` (per-field) | 400 | `invalid_*` (per-field) | `validation_error` |
+| `INVALID_CONTENT_TYPE` | 415 | `invalid_content_type` | `unsupported_media_type` |
+| `MIRROR_DISABLED` | 503 | `mirror_disabled` | `upstream_unavailable` |
+| `MISSING_*` | 400 | `missing_*` | `validation_error` |
+| `NOTIFICATION_NOT_FOUND` | 404 | `notification_not_found` | `resource_not_found` |
+| `NO_UPDATE` | 400 | `no_update` | `validation_error` |
+| `OLD_REPO_NOT_CONFIRMED` | 409 | `old_repo_not_confirmed` | `resource_conflict` |
+| `ORG_NOT_FOUND` | 404 | `org_not_found` | `resource_not_found` |
+| `PACKAGE_DOWNLOAD_FAILED` | 500 | `package_download_failed` | `upstream_unavailable` |
+| `PAYLOAD_TOO_LARGE` | 413 | `payload_too_large` | `payload_too_large` |
+| `PROVIDER_NOT_FOUND` | 404 | `provider_not_found` | `resource_not_found` |
+| `PULL_FAILED` | 502 | `pull_failed` | `upstream_unavailable` |
+| `QUOTA_EXCEEDED` | 429 | `quota_exceeded` | `rate_limited` |
+| `RECONCILE_ALREADY_RUNNING` | 409 | `reconcile_already_running` | `resource_conflict` |
+| `REDEMPTION_CODE_*` | 404 / 409 / 410 | `redemption_code_*` | `resource_not_found` / `resource_conflict` |
+| `REFRESH_FAILED` / `REFRESH_PREVIEW_FAILED` | 502 | `refresh_failed` / `refresh_preview_failed` | `upstream_unavailable` |
+| `REPO_FETCH_FAILED` | 502 | `repo_fetch_failed` | `upstream_unavailable` |
+| `SKILL_NAME_EXISTS` | 409 | `skill_name_exists` | `resource_conflict` |
+| `SKILL_NOT_FOUND` | 404 | `skill_not_found` | `resource_not_found` |
+| `SKILL_VERSION_NOT_FOUND` | 404 | `skill_version_not_found` | `resource_not_found` |
+| `UPSTREAM_DOWN` | 502 | `upstream_down` | `upstream_unavailable` |
+
+Format rule for future codes: lowercase ASCII, words joined by `_`, no leading/trailing `_`. Pick from the parent §1.4 vocabulary when generic; add a specific subcode only when the caller needs to branch on it.
diff --git a/docs/SDK_PUBLISHING.md b/docs/SDK_PUBLISHING.md
new file mode 100644
index 00000000..d0db5171
--- /dev/null
+++ b/docs/SDK_PUBLISHING.md
@@ -0,0 +1,70 @@
+# SDK Publishing Strategy
+
+Current state of the TypeScript and Python SDKs on the public registries, and the path to v1 publish.
+
+## Status (2026-05)
+
+| Package | Registry name | Currently published? | Blocker |
+|---|---|:---:|---|
+| `@chronoai/ornn-sdk` | npm | **No** | `sdk/typescript/package.json` has `"private": true`. Removing the flag is the v1 step. |
+| `ornn-sdk` | PyPI | **No** | Not yet uploaded; name not reserved. |
+
+Until both ship, the SDKs are usable only from this monorepo. Consumers should pin to a specific git ref / tag and install from source — see [Pre-publish install](#pre-publish-install) below.
+
+This matches the project's overall posture: Ornn is in **alpha (0.x)** per [`docs/API_STABILITY.md`](API_STABILITY.md), and no SDK-shape compatibility guarantees apply yet. Publishing now would bake in surface decisions that may move at v1.
+
+## Decision
+
+**Hold both packages for v1.0.** Publishing while the SDK contract may still shift creates an upgrade-treadmill for early adopters; the v1 release will publish both packages on the same tag.
+
+The v1 release checklist (lives in milestone planning, not yet a doc):
+
+1. `sdk/typescript/package.json` — drop `"private": true`, confirm `keywords`/`repository`/`license` are set (already done in [#468](https://github.com/ChronoAIProject/Ornn/pull/589)).
+2. `sdk/python/pyproject.toml` — confirm `keywords`/`classifiers`/`urls` are set (already done in [#468](https://github.com/ChronoAIProject/Ornn/pull/589)).
+3. Reserve `@chronoai/ornn-sdk` on npm — owner: `chronoai`.
+4. Reserve `ornn-sdk` on PyPI — owner: `chronoai`.
+5. Extend `.github/workflows/changeset-release.yml` to run `npm publish --access public` on the TS workspace and `twine upload` on the Python wheel when the bump PR lands on `main`.
+6. Add the npm + PyPI tokens to org secrets.
+7. Cut v1.0 — verify both packages resolve, smoke-test `npm install @chronoai/ornn-sdk` and `pip install ornn-sdk` against a clean machine.
+
+## Pre-publish install
+
+Until v1 ships, both SDKs are install-from-source:
+
+### TypeScript
+
+This is a Bun workspace; consumers depending on `@chronoai/ornn-sdk` from another local checkout can use `bun link`:
+
+```bash
+# From inside this monorepo
+cd sdk/typescript
+bun link
+
+# From the consuming project
+bun link @chronoai/ornn-sdk
+```
+
+Or pin to the monorepo via your package manager's git-subdirectory support. Most clients reach for `npm install <git-url>#<commit>`; the workspace layout means you need a builder that understands monorepo subdirs (pnpm, bun, yarn-berry).
+
+### Python
+
+Install editable from this monorepo:
+
+```bash
+pip install -e ./sdk/python
+# or
+pip install "git+https://github.com/ChronoAIProject/Ornn.git#subdirectory=sdk/python"
+```
+
+The Python form works out of the box because `pyproject.toml` is hatch-built.
+
+## What does not change in alpha
+
+- The SDK surface is unstable; pin to a specific commit, not `develop`.
+- `OrnnError`, `OrnnClient`, the `.search()` / `.get()` / `.listVersions()` methods are the *intended* v1 surface — they may gain options but should not lose them.
+- Sample code in `examples/` always tracks the SDK on `develop`, not a published release. Use those examples as the canonical reference shape.
+
+## Open questions
+
+1. Will the TS SDK be ESM-only or dual ESM+CJS at v1? Current source is ESM (`"type": "module"`); the publish step needs to decide whether to ship CJS too.
+2. PyPI name `ornn-sdk` is unreserved. We should reserve it before someone else does, even if we hold publication. (Tracked separately.)
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 00000000..de91fa02
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,54 @@
+# examples/
+
+Minimal, copy-paste-ready starter skills that double as references for the SKILL.md frontmatter and the agent execution contract. Each one is small enough to read in one sitting and small enough to fork as the starting point for a real skill.
+
+| Skill | Language | What it does |
+|---|---|---|
+| [`text-summarizer/`](text-summarizer) | TypeScript (Bun) | Calls an LLM to summarise the input string. Demonstrates: skill ↔ LLM provider boundary, structured input via stdin JSON, structured output via stdout JSON. |
+| [`csv-processor/`](csv-processor) | Python 3 | Parses CSV from a file path argument, computes per-column min/mean/max for every numeric column. Demonstrates: stdlib-only Python skill, file-path inputs, deterministic numeric output. |
+| [`api-fetch-wrapper/`](api-fetch-wrapper) | TypeScript (Bun) | Wraps a public weather API. Demonstrates: env-var-based API key handling, error normalisation, retry-aware HTTP. |
+
+## Anatomy of an Ornn skill
+
+Each example is laid out the same way:
+
+```
+examples/<name>/
+├── SKILL.md          ← frontmatter the registry indexes on + agent-facing prose
+├── README.md         ← "what this does" + "how to adapt" (5 lines max)
+├── src/
+│   └── index.{ts,py} ← the skill entrypoint
+└── package.json | pyproject.toml  ← runtime deps
+```
+
+`SKILL.md` is the contract: every field in its YAML frontmatter is validated against `ornn-api`'s [skill format schema](../docs/CONVENTIONS.md). The prose body is what the agent reads at runtime to decide whether the skill is relevant and how to call it.
+
+## Running an example locally
+
+Once the [TS SDK](../sdk/typescript) is installed:
+
+```bash
+# From repo root
+cd examples/text-summarizer
+bun install
+echo '{"text": "Once upon a time …", "length": 30}' | bun run src/index.ts
+```
+
+For the agent-driven workflow (pull from the registry, run in sandbox), see the [SDK quickstart](../README.md#sdk-quickstart) in the main README.
+
+## Adapting an example into your own skill
+
+1. Copy the directory.
+2. Update `SKILL.md` `name`, `description`, and `metadata.tag` for your use case.
+3. Edit the entrypoint to do your thing — keep the stdin-JSON-in / stdout-JSON-out contract so the sandbox can stream events back to the agent.
+4. Bump `version` and publish via `POST /api/v1/skills` (see [`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md)).
+
+## Why these three?
+
+They cover the three failure-mode-archetypes a real skill author needs to handle:
+
+- **`text-summarizer`** — LLM-backed work, network latency, model-vendor error surface.
+- **`csv-processor`** — pure local computation, file I/O, deterministic output (the easy case — useful as a control).
+- **`api-fetch-wrapper`** — external HTTP, secret handling, retries — the case that breaks first in production.
+
+If a real skill mixes more than one of these patterns, it's worth splitting.
diff --git a/examples/api-fetch-wrapper/README.md b/examples/api-fetch-wrapper/README.md
new file mode 100644
index 00000000..8adb3d1d
--- /dev/null
+++ b/examples/api-fetch-wrapper/README.md
@@ -0,0 +1,9 @@
+# api-fetch-wrapper
+
+Call a public HTTP API with retries, structured errors, and no-leak credential handling. Demo target is Open-Meteo (keyless, so the example runs out of the box).
+
+**Run:** `echo '{"latitude":52.52,"longitude":13.41}' | bun run src/index.ts`
+
+**Adapt:** swap the upstream URL + shape; add `Authorization` header reading from env. The retry-and-error-mapping skeleton is the load-bearing part — don't drop it.
+
+See `SKILL.md` for the full contract.
diff --git a/examples/api-fetch-wrapper/SKILL.md b/examples/api-fetch-wrapper/SKILL.md
new file mode 100644
index 00000000..78d9a3f9
--- /dev/null
+++ b/examples/api-fetch-wrapper/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: api-fetch-wrapper
+description: Wrap a public HTTP API (Open-Meteo weather as the demo) with credential handling, error normalisation, and a single retry on transient network failures. Demonstrates the production-shaped baseline for any "skill that calls an external service" — env-based secrets, structured error output, no leaked API keys in logs, and a deliberate retry policy. The Open-Meteo endpoint used here is keyless on purpose so the example runs without setup; replace `OPEN_METEO_URL` with your own host and add `process.env.MY_API_KEY` for an auth'd version.
+version: "1.0"
+license: MIT
+metadata:
+  category: integration
+  tag:
+    - example
+    - http
+    - external-api
+    - typescript
+---
+
+# api-fetch-wrapper
+
+The case that breaks first in production — a skill that hits an external service. This example covers the four things every such skill needs: secret handling, retry policy, error normalisation, and no-leak-on-failure logging.
+
+## Contract
+
+**Input** (stdin, JSON):
+
+```json
+{ "latitude": 52.52, "longitude": 13.41 }
+```
+
+**Output** (stdout, JSON):
+
+```json
+{
+  "temperatureC": 18.4,
+  "windSpeedKmh": 12.6,
+  "fetchedAt": "2026-05-19T08:00:00.000Z"
+}
+```
+
+**Errors** — written to stderr as `{"error": "...", "cause": "..."}` and exit code `1`. Error messages NEVER include the raw upstream response body (it might echo a secret); they include the upstream status code and a short canonical reason.
+
+## Required environment
+
+| Var | Purpose |
+|---|---|
+| `OPEN_METEO_URL` | Optional override of the upstream host. Defaults to `https://api.open-meteo.com`. |
+| *(none for auth)* | Open-Meteo is keyless. For an auth'd API, the same skeleton reads `process.env.YOUR_API_KEY` and passes it via `Authorization` header. |
+
+## Run locally
+
+```bash
+cd examples/api-fetch-wrapper
+bun install
+echo '{"latitude":52.52,"longitude":13.41}' | bun run src/index.ts
+```
+
+## Adapt this
+
+- **Different API** — replace the URL, query params, and response shape. The retry / error-mapping skeleton stays.
+- **API-key auth** — read `process.env.YOUR_API_KEY` once at the top, pass it via `Authorization: Bearer ${apiKey}`, and ensure the key never appears in error messages.
+- **Stronger retry** — bump `MAX_ATTEMPTS`, add exponential backoff with jitter, or distinguish 5xx (retry) vs 4xx (do not retry) explicitly.
+- **Cache** — wrap the fetch in a TTL cache when the upstream rate-limits.
diff --git a/examples/api-fetch-wrapper/package.json b/examples/api-fetch-wrapper/package.json
new file mode 100644
index 00000000..522bc8c2
--- /dev/null
+++ b/examples/api-fetch-wrapper/package.json
@@ -0,0 +1,11 @@
+{
+  "name": "@ornn-examples/api-fetch-wrapper",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Minimal HTTP-API-wrapping skill — example for the Ornn skill format",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "start": "bun run src/index.ts"
+  }
+}
diff --git a/examples/api-fetch-wrapper/src/index.ts b/examples/api-fetch-wrapper/src/index.ts
new file mode 100644
index 00000000..f26508ac
--- /dev/null
+++ b/examples/api-fetch-wrapper/src/index.ts
@@ -0,0 +1,105 @@
+/**
+ * api-fetch-wrapper example skill.
+ *
+ * Reads `{ latitude, longitude }` from stdin, fetches the current
+ * conditions from Open-Meteo, writes `{ temperatureC, windSpeedKmh,
+ * fetchedAt }` to stdout. One retry on transient network failure.
+ *
+ * Demonstrates the four production-shaped patterns every "skill that
+ * calls an external service" needs:
+ *
+ *   1. Secrets via env (none here — Open-Meteo is keyless — but the
+ *      reading pattern is shown via OPEN_METEO_URL).
+ *   2. Retry policy: one bounded retry on transient failure, no
+ *      exponential blow-up.
+ *   3. Error normalisation: stderr always carries a structured
+ *      `{ error, cause }` blob, never the raw upstream body.
+ *   4. No-leak on failure: the raw upstream response is never logged.
+ */
+
+const OPEN_METEO_URL = process.env.OPEN_METEO_URL ?? "https://api.open-meteo.com";
+const MAX_ATTEMPTS = 2;
+const RETRY_DELAY_MS = 500;
+
+interface Input {
+  latitude: number;
+  longitude: number;
+}
+
+interface OpenMeteoResponse {
+  current?: { temperature_2m?: number; wind_speed_10m?: number };
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function isTransient(status: number): boolean {
+  // 408 timeout, 429 throttling, 5xx server side — all worth one retry.
+  return status === 408 || status === 429 || (status >= 500 && status < 600);
+}
+
+async function fetchWeather(input: Input): Promise<OpenMeteoResponse> {
+  const url = new URL("/v1/forecast", OPEN_METEO_URL);
+  url.searchParams.set("latitude", String(input.latitude));
+  url.searchParams.set("longitude", String(input.longitude));
+  url.searchParams.set("current", "temperature_2m,wind_speed_10m");
+
+  let lastStatus = 0;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    let res: Response;
+    try {
+      res = await fetch(url);
+    } catch (err) {
+      if (attempt === MAX_ATTEMPTS) {
+        throw new Error("network failure after retry", { cause: err });
+      }
+      await new Promise((r) => setTimeout(r, RETRY_DELAY_MS));
+      continue;
+    }
+
+    if (res.ok) {
+      return (await res.json()) as OpenMeteoResponse;
+    }
+
+    lastStatus = res.status;
+    if (!isTransient(res.status) || attempt === MAX_ATTEMPTS) {
+      // Drain the body so the socket can be reused, but DO NOT include
+      // it in the thrown error — upstream APIs sometimes echo secrets.
+      await res.text().catch(() => undefined);
+      throw new Error(`upstream returned ${res.status}`);
+    }
+    await res.text().catch(() => undefined);
+    await new Promise((r) => setTimeout(r, RETRY_DELAY_MS));
+  }
+  throw new Error(`upstream returned ${lastStatus}`);
+}
+
+async function main(): Promise<void> {
+  const raw = (await readStdin()).trim();
+  if (!raw) throw new Error("expected JSON `{ latitude, longitude }` on stdin");
+  const input = JSON.parse(raw) as Input;
+  if (typeof input.latitude !== "number" || typeof input.longitude !== "number") {
+    throw new Error("`latitude` and `longitude` must be numbers");
+  }
+
+  const upstream = await fetchWeather(input);
+  const current = upstream.current ?? {};
+
+  process.stdout.write(
+    JSON.stringify({
+      temperatureC: current.temperature_2m ?? null,
+      windSpeedKmh: current.wind_speed_10m ?? null,
+      fetchedAt: new Date().toISOString(),
+    }) + "\n",
+  );
+}
+
+main().catch((err: unknown) => {
+  const message = err instanceof Error ? err.message : String(err);
+  const cause = err instanceof Error && err.cause instanceof Error ? err.cause.message : undefined;
+  process.stderr.write(JSON.stringify({ error: message, cause }) + "\n");
+  process.exit(1);
+});
diff --git a/examples/csv-processor/README.md b/examples/csv-processor/README.md
new file mode 100644
index 00000000..4735ea7f
--- /dev/null
+++ b/examples/csv-processor/README.md
@@ -0,0 +1,9 @@
+# csv-processor
+
+Parse a CSV file, compute per-column min/mean/max for every numeric column.
+
+**Run:** `python src/main.py sample.csv`
+
+**Adapt:** add more aggregations (median, p95, stddev), or stream large files with running-mean updates. The in/out shape (`path → { rowCount, columns: { ... } }`) is intentionally fixed so the skill stays composable.
+
+Stdlib only — no pandas, no numpy. See `SKILL.md` for the full contract.
diff --git a/examples/csv-processor/SKILL.md b/examples/csv-processor/SKILL.md
new file mode 100644
index 00000000..9082f0fe
--- /dev/null
+++ b/examples/csv-processor/SKILL.md
@@ -0,0 +1,58 @@
+---
+name: csv-processor
+description: Read a CSV file from disk, compute per-column min/mean/max for every numeric column, emit the result as JSON. Stdlib-only Python; no pandas, no numpy. Demonstrates the simplest possible "give me a file path, get back structured analysis" skill — a deliberate baseline for any skill that processes tabular data locally without an LLM in the loop.
+version: "1.0"
+license: MIT
+metadata:
+  category: data
+  tag:
+    - example
+    - csv
+    - statistics
+    - python
+---
+
+# csv-processor
+
+A deterministic, network-free skill — the easiest case. Useful as a control when debugging the agent ↔ skill plumbing: if this fails, the failure is in the runner, not the skill.
+
+## Contract
+
+**Input** (single CLI argument):
+
+```
+python src/main.py /path/to/data.csv
+```
+
+The script reads `argv[1]` as a filesystem path. CSV must have a header row.
+
+**Output** (stdout, JSON):
+
+```json
+{
+  "rowCount": 1234,
+  "columns": {
+    "price": { "min": 1.23, "mean": 42.0, "max": 999.99, "count": 1234 },
+    "quantity": { "min": 0, "mean": 7.5, "max": 100, "count": 1230 }
+  }
+}
+```
+
+Only numeric columns appear under `columns`. `count` is the number of cells that parsed successfully (numeric); non-numeric / blank cells are skipped.
+
+**Errors** — written to stderr as `{"error": "..."}` and exit code `1`.
+
+## Run locally
+
+```bash
+cd examples/csv-processor
+python src/main.py sample.csv
+```
+
+A `sample.csv` is bundled so the example runs out of the box.
+
+## Adapt this
+
+- **Different aggregations** — add median, p95, stddev; same shape, more keys per column.
+- **Streaming** — for huge files, replace the in-memory accumulation with a running-mean update; one extra variable per column, same output shape.
+- **Source other than disk** — accept a URL or stdin instead of `argv[1]`. The aggregation core doesn't care.
diff --git a/examples/csv-processor/sample.csv b/examples/csv-processor/sample.csv
new file mode 100644
index 00000000..b5714d9a
--- /dev/null
+++ b/examples/csv-processor/sample.csv
@@ -0,0 +1,6 @@
+product,price,quantity,region
+apple,1.50,120,west
+banana,0.75,300,west
+cherry,3.20,80,east
+date,2.10,55,east
+elderberry,4.50,12,north
diff --git a/examples/csv-processor/src/main.py b/examples/csv-processor/src/main.py
new file mode 100644
index 00000000..408abb98
--- /dev/null
+++ b/examples/csv-processor/src/main.py
@@ -0,0 +1,86 @@
+"""CSV processor example skill.
+
+Reads a CSV file path from `argv[1]`, computes per-column min/mean/max
+for every column where at least one cell parses as a number, writes a
+JSON summary to stdout. On any failure: `{ "error": "..." }` on stderr
++ exit code 1.
+
+Stdlib only; deterministic; offline. The control case for debugging
+agent ↔ skill plumbing.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import sys
+from typing import Optional
+
+
+def parse_number(raw: str) -> Optional[float]:
+    """Best-effort numeric parse — empty / non-numeric returns None."""
+    s = raw.strip()
+    if not s:
+        return None
+    try:
+        return float(s)
+    except ValueError:
+        return None
+
+
+def summarise(path: str) -> dict:
+    with open(path, newline="", encoding="utf-8") as fh:
+        reader = csv.DictReader(fh)
+        fieldnames = reader.fieldnames or []
+        sums: dict[str, float] = {name: 0.0 for name in fieldnames}
+        counts: dict[str, int] = {name: 0 for name in fieldnames}
+        mins: dict[str, float] = {}
+        maxs: dict[str, float] = {}
+        row_count = 0
+
+        for row in reader:
+            row_count += 1
+            for name in fieldnames:
+                value = parse_number(row.get(name, ""))
+                if value is None:
+                    continue
+                sums[name] += value
+                counts[name] += 1
+                if name not in mins or value < mins[name]:
+                    mins[name] = value
+                if name not in maxs or value > maxs[name]:
+                    maxs[name] = value
+
+        columns: dict[str, dict[str, float | int]] = {}
+        for name in fieldnames:
+            if counts[name] == 0:
+                # Skip columns where no cell parsed as a number.
+                continue
+            columns[name] = {
+                "min": mins[name],
+                "mean": sums[name] / counts[name],
+                "max": maxs[name],
+                "count": counts[name],
+            }
+
+        return {"rowCount": row_count, "columns": columns}
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 2:
+        sys.stderr.write(json.dumps({"error": "usage: main.py <path>"}) + "\n")
+        return 1
+    try:
+        result = summarise(argv[1])
+    except FileNotFoundError as e:
+        sys.stderr.write(json.dumps({"error": f"file not found: {e.filename}"}) + "\n")
+        return 1
+    except OSError as e:
+        sys.stderr.write(json.dumps({"error": f"could not read CSV: {e}"}) + "\n")
+        return 1
+    sys.stdout.write(json.dumps(result) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))
diff --git a/examples/text-summarizer/README.md b/examples/text-summarizer/README.md
new file mode 100644
index 00000000..9df81b82
--- /dev/null
+++ b/examples/text-summarizer/README.md
@@ -0,0 +1,9 @@
+# text-summarizer
+
+Summarise input text using Claude. ~50 lines of TypeScript; pure stdin/stdout JSON.
+
+**Run:** `ANTHROPIC_API_KEY=sk-ant-... echo '{"text":"..."}' | bun run src/index.ts`
+
+**Adapt:** swap `Anthropic` SDK for another vendor; or wrap the call in retry/streaming. The I/O contract (`{ text, length? }` → `{ summary }`) is intentionally fixed so the skill stays composable.
+
+See `SKILL.md` for the full agent-facing contract.
diff --git a/examples/text-summarizer/SKILL.md b/examples/text-summarizer/SKILL.md
new file mode 100644
index 00000000..45443d30
--- /dev/null
+++ b/examples/text-summarizer/SKILL.md
@@ -0,0 +1,56 @@
+---
+name: text-summarizer
+description: Summarise a chunk of text down to roughly `length` words using the agent's configured LLM provider. Input shape `{ text: string, length?: number }` on stdin, JSON; output shape `{ summary: string }` on stdout, JSON. Minimal: ~50 lines, no streaming, no retries — a deliberate baseline so the wiring is visible. For a production summariser, fork this and add retries, prompt-injection sanitisation, length validation, and per-model cost tracking.
+version: "1.0"
+license: MIT
+metadata:
+  category: text
+  tag:
+    - example
+    - llm
+    - summarization
+    - typescript
+---
+
+# text-summarizer
+
+A minimum-viable LLM skill — the smallest amount of code that takes structured input, calls an LLM, and emits structured output.
+
+## Contract
+
+**Input** (stdin, JSON):
+
+```json
+{ "text": "...long input...", "length": 60 }
+```
+
+- `text` (string, required) — what to summarise.
+- `length` (number, optional, default 60) — target word count for the summary.
+
+**Output** (stdout, JSON):
+
+```json
+{ "summary": "..." }
+```
+
+**Errors** — written to stderr as `{ "error": "...message..." }` and exit code `1`.
+
+## Required environment
+
+| Var | Purpose |
+|---|---|
+| `ANTHROPIC_API_KEY` | Talks to Claude. Swap the SDK call to point at OpenAI / Gemini / your own backend; nothing else changes. |
+
+## Run locally
+
+```bash
+cd examples/text-summarizer
+bun install
+ANTHROPIC_API_KEY=sk-ant-... echo '{"text":"...","length":40}' | bun run src/index.ts
+```
+
+## Adapt this
+
+- **Different model vendor** — replace `Anthropic` with the SDK of your choice; the I/O shape stays.
+- **Stream output** — emit one JSON line per token instead of one final blob.
+- **Sanitise input** — the current code passes `text` to the model verbatim; for untrusted callers, strip control characters and cap length before the API call.
diff --git a/examples/text-summarizer/package.json b/examples/text-summarizer/package.json
new file mode 100644
index 00000000..888bbfae
--- /dev/null
+++ b/examples/text-summarizer/package.json
@@ -0,0 +1,14 @@
+{
+  "name": "@ornn-examples/text-summarizer",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Minimal LLM-backed summarizer skill — example for the Ornn skill format",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "start": "bun run src/index.ts"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.30.1"
+  }
+}
diff --git a/examples/text-summarizer/src/index.ts b/examples/text-summarizer/src/index.ts
new file mode 100644
index 00000000..97b5be07
--- /dev/null
+++ b/examples/text-summarizer/src/index.ts
@@ -0,0 +1,62 @@
+/**
+ * text-summarizer example skill.
+ *
+ * Reads `{ text, length? }` from stdin (single JSON blob), asks Claude
+ * for a summary of roughly `length` words, writes `{ summary }` to
+ * stdout. On any failure: `{ error }` on stderr + exit code 1.
+ *
+ * Intentionally minimal — no retries, no streaming, no input
+ * sanitisation. See SKILL.md "Adapt this" for production hardening.
+ */
+
+import Anthropic from "@anthropic-ai/sdk";
+
+interface Input {
+  text: string;
+  length?: number;
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function main(): Promise<void> {
+  const raw = (await readStdin()).trim();
+  if (!raw) {
+    throw new Error("expected JSON `{ text, length? }` on stdin");
+  }
+
+  const input = JSON.parse(raw) as Input;
+  if (typeof input.text !== "string" || input.text.length === 0) {
+    throw new Error("`text` is required and must be a non-empty string");
+  }
+  const length = typeof input.length === "number" && input.length > 0 ? input.length : 60;
+
+  const client = new Anthropic();
+  const message = await client.messages.create({
+    model: "claude-opus-4-7",
+    max_tokens: Math.max(256, length * 4),
+    messages: [
+      {
+        role: "user",
+        content: `Summarise the following text in approximately ${length} words. Reply with only the summary, no preamble.\n\n${input.text}`,
+      },
+    ],
+  });
+
+  const summary = message.content
+    .filter((block): block is Anthropic.TextBlock => block.type === "text")
+    .map((block) => block.text)
+    .join("\n")
+    .trim();
+
+  process.stdout.write(JSON.stringify({ summary }) + "\n");
+}
+
+main().catch((err: unknown) => {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(JSON.stringify({ error: message }) + "\n");
+  process.exit(1);
+});
diff --git a/ornn-api/scripts/backfill-skill-author-display-names.test.ts b/ornn-api/scripts/backfill-skill-author-display-names.test.ts
deleted file mode 100644
index 2c3d7d3d..00000000
--- a/ornn-api/scripts/backfill-skill-author-display-names.test.ts
+++ /dev/null
@@ -1,227 +0,0 @@
-/**
- * Integration tests for the skill author-label backfill script.
- *
- * The script is a self-contained CLI (no exported entry point), so the
- * tests spawn it as a child process with `MONGODB_URI` pointed at a
- * `mongodb-memory-server` instance, then assert on side effects + stdout.
- *
- * Three scenarios:
- *   1. `--dry-run` against a fixture with stale labels — must NOT mutate.
- *   2. Live run against the same fixture — writes the correct labels.
- *   3. Live re-run on already-good rows — idempotent (no further writes).
- *
- * @module scripts/backfill-skill-author-display-names.test
- */
-
-import { describe, test, expect, beforeAll, afterAll, beforeEach } from "bun:test";
-import { MongoClient, type Db } from "mongodb";
-import { MongoMemoryServer } from "mongodb-memory-server";
-import { spawnSync } from "node:child_process";
-import { resolve } from "node:path";
-
-const SCRIPT_PATH = resolve(__dirname, "backfill-skill-author-display-names.ts");
-const TEST_DB = "backfill-test";
-
-let mongo: MongoMemoryServer;
-let client: MongoClient;
-let db: Db;
-let mongoUri: string;
-
-beforeAll(async () => {
-  mongo = await MongoMemoryServer.create();
-  mongoUri = mongo.getUri();
-  client = new MongoClient(mongoUri);
-  await client.connect();
-  db = client.db(TEST_DB);
-});
-
-afterAll(async () => {
-  await client.close().catch(() => {});
-  await mongo.stop().catch(() => {});
-});
-
-beforeEach(async () => {
-  await db.collection("skills").deleteMany({});
-  await db.collection("activities").deleteMany({});
-});
-
-interface RunResult {
-  status: number | null;
-  stdout: string;
-  stderr: string;
-}
-
-/** Spawn the backfill script as a child process. */
-function runScript(args: string[] = []): RunResult {
-  const r = spawnSync("bun", ["run", SCRIPT_PATH, ...args], {
-    env: {
-      ...process.env,
-      MONGODB_URI: mongoUri,
-      MONGODB_DB: TEST_DB,
-    },
-    encoding: "utf8",
-    timeout: 30_000,
-  });
-  return {
-    status: r.status,
-    stdout: r.stdout ?? "",
-    stderr: r.stderr ?? "",
-  };
-}
-
-async function seedActivity(rows: Array<{
-  userId: string;
-  email: string;
-  displayName: string;
-  createdAt?: Date;
-}>): Promise<void> {
-  await db.collection("activities").insertMany(
-    rows.map((r, i) => ({
-      _id: `act-${i}-${Math.random()}`,
-      userId: r.userId,
-      userEmail: r.email,
-      userDisplayName: r.displayName,
-      action: "login",
-      details: {},
-      createdAt: r.createdAt ?? new Date(),
-    })) as never,
-  );
-}
-
-async function seedSkills(rows: Array<{
-  _id: string;
-  createdBy: string;
-  createdByEmail?: string | null;
-  createdByDisplayName?: string | null;
-}>): Promise<void> {
-  await db.collection("skills").insertMany(rows as never);
-}
-
-describe("backfill-skill-author-display-names script", () => {
-  test("dryRun_DoesNotMutate_ButReportsWhatWouldChange", async () => {
-    await seedActivity([
-      {
-        userId: "user-1",
-        email: "alice@example.com",
-        displayName: "Alice",
-      },
-    ]);
-    await seedSkills([
-      {
-        _id: "skill-1",
-        createdBy: "user-1",
-        // Missing both label fields — qualifies as a backfill target.
-      },
-    ]);
-
-    const result = runScript(["--dry-run"]);
-    expect(result.status).toBe(0);
-    // The dry-run banner is part of the script's own output.
-    expect(result.stdout).toContain("[dry-run]");
-    expect(result.stdout).toContain("alice@example.com");
-
-    // Verify nothing was actually written.
-    const after = await db.collection("skills").findOne({ _id: "skill-1" } as never);
-    expect(after?.createdByEmail).toBeUndefined();
-    expect(after?.createdByDisplayName).toBeUndefined();
-  });
-
-  test("liveRun_FillsMissingLabelsFromActivities", async () => {
-    await seedActivity([
-      {
-        userId: "user-1",
-        email: "alice@example.com",
-        displayName: "Alice",
-      },
-    ]);
-    await seedSkills([{ _id: "skill-1", createdBy: "user-1" }]);
-
-    const result = runScript([]);
-    expect(result.status).toBe(0);
-    expect(result.stdout).toContain("updated=1");
-
-    const after = await db.collection("skills").findOne({ _id: "skill-1" } as never);
-    expect(after?.createdByEmail).toBe("alice@example.com");
-    expect(after?.createdByDisplayName).toBe("Alice");
-  });
-
-  test("liveRun_ReplacesCachedValueEqualToUserId", async () => {
-    // Symptom in the issue: UI showed the raw userId because the
-    // cached field was set to the userId itself. Backfill must overwrite.
-    // Note: the script's needle covers the displayName==userId case
-    // explicitly, but only displayName (not email) — see the script's
-    // $or block. Test what's actually claimed.
-    await seedActivity([
-      {
-        userId: "user-1",
-        email: "alice@example.com",
-        displayName: "Alice",
-      },
-    ]);
-    await seedSkills([
-      {
-        _id: "skill-1",
-        createdBy: "user-1",
-        createdByEmail: "alice@example.com",
-        createdByDisplayName: "user-1", // poisoned: equals raw userId
-      },
-    ]);
-
-    const result = runScript([]);
-    expect(result.status).toBe(0);
-
-    const after = await db.collection("skills").findOne({ _id: "skill-1" } as never);
-    expect(after?.createdByDisplayName).toBe("Alice");
-  });
-
-  test("idempotent_RerunOnAlreadyBackfilledSkillIsNoop", async () => {
-    await seedActivity([
-      {
-        userId: "user-1",
-        email: "alice@example.com",
-        displayName: "Alice",
-      },
-    ]);
-    await seedSkills([{ _id: "skill-1", createdBy: "user-1" }]);
-
-    const first = runScript([]);
-    expect(first.status).toBe(0);
-
-    const second = runScript([]);
-    expect(second.status).toBe(0);
-    // Second run sees no candidates — script prints the early-out
-    // banner instead of any updated=N line.
-    expect(second.stdout).toContain("Nothing to do");
-  });
-
-  test("limitFlag_BoundsCandidateBatch", async () => {
-    await seedActivity([
-      { userId: "u1", email: "u1@example.com", displayName: "U1" },
-      { userId: "u2", email: "u2@example.com", displayName: "U2" },
-      { userId: "u3", email: "u3@example.com", displayName: "U3" },
-    ]);
-    await seedSkills([
-      { _id: "s1", createdBy: "u1" },
-      { _id: "s2", createdBy: "u2" },
-      { _id: "s3", createdBy: "u3" },
-    ]);
-
-    const result = runScript(["--limit=2"]);
-    expect(result.status).toBe(0);
-    // Stdout reports the candidate count up front; --limit=2 trims to 2.
-    expect(result.stdout).toContain("Found 2 skills");
-  });
-
-  test("unresolvedUser_LogsAndCounts_NoWrite", async () => {
-    // Skill author has no rows in the activities collection at all.
-    await seedSkills([{ _id: "skill-orphan", createdBy: "ghost" }]);
-
-    const result = runScript([]);
-    expect(result.status).toBe(0);
-    expect(result.stdout).toContain("unresolved=1");
-
-    const after = await db.collection("skills").findOne({ _id: "skill-orphan" } as never);
-    expect(after?.createdByEmail).toBeUndefined();
-    expect(after?.createdByDisplayName).toBeUndefined();
-  });
-});
diff --git a/ornn-api/scripts/backfill-skill-author-display-names.ts b/ornn-api/scripts/backfill-skill-author-display-names.ts
deleted file mode 100644
index 1feed3df..00000000
--- a/ornn-api/scripts/backfill-skill-author-display-names.ts
+++ /dev/null
@@ -1,183 +0,0 @@
-/**
- * Migration: backfill `createdByEmail` + `createdByDisplayName` on
- * skill documents that pre-date the cache-at-create-time behavior.
- *
- * The Skill Detail / Skill Card UI renders the author with a fallback
- * chain `createdByDisplayName → createdByEmail → createdBy`. Older
- * skills only have `createdBy` (the NyxID user_id UUID) populated, so
- * the UI shows the raw UUID. New skills populate both at create time.
- *
- * This script joins `skills.createdBy` against the most-recent matching
- * `activities.userId` row to fish out the user's last-known email and
- * display name, and writes them back onto the skill doc.
- *
- * Idempotent: skills that already have both fields set are skipped. A
- * skill whose `createdBy` doesn't appear in `activities` (user never
- * signed into Ornn) is left untouched and reported as `unresolved`.
- *
- * Run with (from ornn-api/):
- *   MONGODB_URI=... MONGODB_DB=... bun run scripts/backfill-skill-author-display-names.ts
- *
- * Optional flags:
- *   --dry-run       Read-only; report what would change without writing.
- *   --limit=N       Stop after the first N skill rows (debug aid).
- */
-
-import { MongoClient } from "mongodb";
-
-interface Config {
-  mongoUri: string;
-  mongoDb: string;
-  dryRun: boolean;
-  limit: number | null;
-}
-
-function readConfig(): Config {
-  const mongoUri = process.env.MONGODB_URI;
-  if (!mongoUri) throw new Error("MONGODB_URI is required");
-  const argv = Bun.argv.slice(2);
-  const limitArg = argv.find((a) => a.startsWith("--limit="));
-  return {
-    mongoUri,
-    mongoDb: process.env.MONGODB_DB ?? "ornn",
-    dryRun: argv.includes("--dry-run"),
-    limit: limitArg ? Number(limitArg.split("=")[1]) : null,
-  };
-}
-
-interface SkillRow {
-  _id: string;
-  guid?: string;
-  name?: string;
-  createdBy?: string;
-  createdByEmail?: string;
-  createdByDisplayName?: string;
-}
-
-interface DirectoryRow {
-  _id: string;
-  email: string;
-  displayName: string;
-}
-
-async function main(): Promise<void> {
-  const cfg = readConfig();
-  const client = new MongoClient(cfg.mongoUri);
-  await client.connect();
-  try {
-    const db = client.db(cfg.mongoDb);
-    const skills = db.collection<SkillRow>("skills");
-    const activities = db.collection("activities");
-
-    // Any skill missing OR holding empty author labels. A skill where
-    // both fields equal `createdBy` (UI fallback already kicked in) is
-    // also targeted — that means a previous reads-side fallback has
-    // poisoned the cached field with the UUID.
-    const needle = {
-      createdBy: { $exists: true, $type: "string", $ne: "" },
-      $or: [
-        { createdByDisplayName: { $exists: false } },
-        { createdByDisplayName: "" },
-        { createdByDisplayName: null },
-        { $expr: { $eq: ["$createdByDisplayName", "$createdBy"] } },
-        { createdByEmail: { $exists: false } },
-        { createdByEmail: "" },
-        { createdByEmail: null },
-      ],
-    };
-
-    let cursor = skills.find(needle).project<SkillRow>({
-      _id: 1,
-      guid: 1,
-      name: 1,
-      createdBy: 1,
-      createdByEmail: 1,
-      createdByDisplayName: 1,
-    });
-    if (cfg.limit !== null) cursor = cursor.limit(cfg.limit);
-    const targets = await cursor.toArray();
-
-    if (targets.length === 0) {
-      console.log("No skills need backfilling. Nothing to do.");
-      return;
-    }
-    console.log(`Found ${targets.length} skills with missing / stale author labels.`);
-
-    // Resolve all unique user_ids in one aggregate.
-    const uniqueUserIds = [...new Set(targets.map((t) => t.createdBy as string))];
-    const directoryRows = await activities
-      .aggregate<DirectoryRow>([
-        { $match: { userId: { $in: uniqueUserIds } } },
-        {
-          $group: {
-            _id: "$userId",
-            email: { $last: "$userEmail" },
-            displayName: { $last: "$userDisplayName" },
-          },
-        },
-      ])
-      .toArray();
-    const directory = new Map<string, DirectoryRow>();
-    for (const r of directoryRows) directory.set(r._id, r);
-    console.log(
-      `Resolved ${directoryRows.length}/${uniqueUserIds.length} unique authors via the activities directory.`,
-    );
-
-    let updated = 0;
-    let alreadyOk = 0;
-    let unresolved = 0;
-    for (const skill of targets) {
-      const hit = directory.get(skill.createdBy as string);
-      if (!hit) {
-        unresolved++;
-        continue;
-      }
-      const nextEmail = hit.email || "";
-      const nextDisplay = hit.displayName || hit.email || "";
-      // No-op when the cache already matches what the directory has —
-      // keeps the run idempotent and the updated count honest.
-      if (
-        skill.createdByEmail === nextEmail &&
-        skill.createdByDisplayName === nextDisplay
-      ) {
-        alreadyOk++;
-        continue;
-      }
-      if (cfg.dryRun) {
-        console.log(
-          `[dry-run] ${skill.guid ?? skill._id} (${skill.name ?? "<no name>"}): ` +
-            `createdBy=${skill.createdBy} → email='${nextEmail}', displayName='${nextDisplay}'`,
-        );
-        updated++;
-        continue;
-      }
-      await skills.updateOne(
-        { _id: skill._id },
-        {
-          $set: {
-            createdByEmail: nextEmail,
-            createdByDisplayName: nextDisplay,
-          },
-        },
-      );
-      updated++;
-    }
-
-    console.log(
-      `\nDone. updated=${updated} alreadyOk=${alreadyOk} unresolved=${unresolved}` +
-        (cfg.dryRun ? " (dry-run; nothing written)" : ""),
-    );
-    if (unresolved > 0) {
-      console.log(
-        `${unresolved} skill(s) had a createdBy with no matching activity row — author never logged into Ornn. Left untouched.`,
-      );
-    }
-  } finally {
-    await client.close();
-  }
-}
-
-main().catch((err) => {
-  console.error("Migration failed:", err);
-  process.exit(1);
-});
diff --git a/ornn-api/scripts/migrate-quota-to-buckets.test.ts b/ornn-api/scripts/migrate-quota-to-buckets.test.ts
index 8486cefd..bf2fdc04 100644
--- a/ornn-api/scripts/migrate-quota-to-buckets.test.ts
+++ b/ornn-api/scripts/migrate-quota-to-buckets.test.ts
@@ -8,7 +8,7 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { MongoMemoryServer } from "mongodb-memory-server";
 import { MongoClient, type Db } from "mongodb";
-import { migrate } from "./migrate-quota-to-buckets";
+import { migrate, parseNonNegativeInt } from "./migrate-quota-to-buckets";
 
 let mongo: MongoMemoryServer;
 let client: MongoClient;
@@ -258,3 +258,59 @@ describe("IT-QUOTA-MIGRATION end-to-end seeded old world", () => {
     expect(notifier.calls[0].targetUserId).toBe("u1");
   });
 });
+
+describe("parseNonNegativeInt — fail-fast on garbage env input (#447)", () => {
+  const ENV_NAME = "ORNN_TEST_INT";
+
+  afterAll(() => {
+    delete process.env[ENV_NAME];
+  });
+
+  beforeEach(() => {
+    delete process.env[ENV_NAME];
+  });
+
+  test("uses fallback when env var is unset", () => {
+    expect(parseNonNegativeInt(ENV_NAME, "200")).toBe(200);
+  });
+
+  test("parses a valid integer", () => {
+    process.env[ENV_NAME] = "42";
+    expect(parseNonNegativeInt(ENV_NAME, "0")).toBe(42);
+  });
+
+  test("trims surrounding whitespace", () => {
+    process.env[ENV_NAME] = "  17  ";
+    expect(parseNonNegativeInt(ENV_NAME, "0")).toBe(17);
+  });
+
+  test("accepts zero", () => {
+    process.env[ENV_NAME] = "0";
+    expect(parseNonNegativeInt(ENV_NAME, "99")).toBe(0);
+  });
+
+  test("rejects non-numeric input", () => {
+    process.env[ENV_NAME] = "abc";
+    expect(() => parseNonNegativeInt(ENV_NAME, "200")).toThrow(/must be a non-negative integer/);
+  });
+
+  test("rejects trailing garbage that Number(env) would silently truncate", () => {
+    process.env[ENV_NAME] = "200abc";
+    expect(() => parseNonNegativeInt(ENV_NAME, "0")).toThrow(/must be a non-negative integer/);
+  });
+
+  test("rejects negative values", () => {
+    process.env[ENV_NAME] = "-1";
+    expect(() => parseNonNegativeInt(ENV_NAME, "0")).toThrow(/must be a non-negative integer/);
+  });
+
+  test("rejects fractional values", () => {
+    process.env[ENV_NAME] = "1.5";
+    expect(() => parseNonNegativeInt(ENV_NAME, "0")).toThrow(/must be a non-negative integer/);
+  });
+
+  test("rejects empty string", () => {
+    process.env[ENV_NAME] = "";
+    expect(() => parseNonNegativeInt(ENV_NAME, "200")).toThrow(/must be a non-negative integer/);
+  });
+});
diff --git a/ornn-api/scripts/migrate-quota-to-buckets.ts b/ornn-api/scripts/migrate-quota-to-buckets.ts
index f936454e..211fc2ab 100644
--- a/ornn-api/scripts/migrate-quota-to-buckets.ts
+++ b/ornn-api/scripts/migrate-quota-to-buckets.ts
@@ -284,6 +284,28 @@ async function sumActiveGrants(
   return rows[0]?.total ?? 0;
 }
 
+/**
+ * Reads `process.env[name]` (or `fallback` when unset) and parses it as
+ * a base-10 integer. Throws if the value is not a finite, non-negative
+ * integer — `Number(env)` silently returns `NaN` on garbage input, which
+ * a migration must never write into Mongo.
+ */
+export function parseNonNegativeInt(name: string, fallback: string): number {
+  const raw = (process.env[name] ?? fallback).trim();
+  if (!/^[0-9]+$/.test(raw)) {
+    throw new Error(
+      `${name} must be a non-negative integer (got: ${JSON.stringify(raw)})`,
+    );
+  }
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(
+      `${name} must be a non-negative integer (got: ${JSON.stringify(raw)})`,
+    );
+  }
+  return parsed;
+}
+
 // CLI entrypoint -----------------------------------------------------------
 if (import.meta.main) {
   const dryRun = process.argv.includes("--dry-run");
@@ -293,8 +315,8 @@ if (import.meta.main) {
     console.error("MONGODB_URI is required");
     process.exit(1);
   }
-  const defaultPlayground = Number(process.env.DEFAULT_PLAYGROUND_MONTHLY ?? "200");
-  const defaultSkillGen = Number(process.env.DEFAULT_SKILLGEN_MONTHLY ?? "20");
+  const defaultPlayground = parseNonNegativeInt("DEFAULT_PLAYGROUND_MONTHLY", "200");
+  const defaultSkillGen = parseNonNegativeInt("DEFAULT_SKILLGEN_MONTHLY", "20");
   const client = new MongoClient(uri);
   await client.connect();
   try {
diff --git a/ornn-api/src/bootstrap.ts b/ornn-api/src/bootstrap.ts
index 82ec9228..06039a2d 100644
--- a/ornn-api/src/bootstrap.ts
+++ b/ornn-api/src/bootstrap.ts
@@ -7,6 +7,7 @@
  */
 
 import { Hono } from "hono";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
 import { cors } from "hono/cors";
 import { join } from "node:path";
 import { readFileSync } from "node:fs";
@@ -26,6 +27,13 @@ import { requestIdMiddleware, getRequestId } from "./middleware/requestId";
 // status, durationMs, sourceIp, requestId.
 import { apiRequestTrackingMiddleware } from "./middleware/apiRequestTracking";
 
+// Idempotency-Key middleware (#459). Caches state-changing-request
+// responses for 24h so retries don't create duplicates.
+import {
+  IdempotencyKeyRepository,
+  idempotencyMiddleware,
+} from "./middleware/idempotency";
+
 // Infrastructure
 import { connectMongo, type MongoConnection } from "./infra/db/mongodb";
 import { createAnalyticsEmitter } from "./infra/analytics";
@@ -58,39 +66,28 @@ import { createAuditRoutes } from "./domains/skills/audit/routes";
 
 
 // Domain: Notifications
-import { NotificationRepository } from "./domains/notifications/repository";
-import { NotificationService } from "./domains/notifications/service";
-import { createNotificationRoutes } from "./domains/notifications/routes";
-import { dropLegacyNotificationCategories } from "./domains/notifications/migration";
+import { wireNotifications } from "./domains/notifications/bootstrap";
 
 // Domain: Announcements (landing-page popup)
-import { AnnouncementRepository } from "./domains/announcements/repository";
-import { AnnouncementService } from "./domains/announcements/service";
-import { createAnnouncementRoutes } from "./domains/announcements/routes";
-import { migrateAnnouncementsToBilingual } from "./domains/announcements/migration";
+import { wireAnnouncements } from "./domains/announcements/bootstrap";
 
 // Domain: Broadcasts (admin-authored notifications, #500)
-import { BroadcastRepository } from "./domains/broadcasts/repository";
-import { BroadcastService } from "./domains/broadcasts/service";
-import { createBroadcastRoutes } from "./domains/broadcasts/routes";
-import { backfillBroadcastRecipientUserIds } from "./domains/broadcasts/migration";
+import {
+  wireBroadcasts,
+  wireBroadcastsRepo,
+} from "./domains/broadcasts/bootstrap";
 
 // Domain: Analytics
-import { AnalyticsRepository } from "./domains/analytics/repository";
-import { AnalyticsService } from "./domains/analytics/service";
-import { createAnalyticsRoutes } from "./domains/analytics/routes";
+import { wireAnalytics } from "./domains/analytics/bootstrap";
 
 // Domain: Skill Search
-import { SearchService } from "./domains/skills/search/service";
-import { createSearchRoutes } from "./domains/skills/search/routes";
+import { wireSkillSearch } from "./domains/skills/search/bootstrap";
 
 // Domain: Skill Generation
-import { SkillGenerationService } from "./domains/skills/generation/service";
-import { createGenerationRoutes } from "./domains/skills/generation/routes";
+import { wireSkillGeneration } from "./domains/skills/generation/bootstrap";
 
 // Domain: Playground
-import { PlaygroundChatService } from "./domains/playground/chatService";
-import { createPlaygroundRoutes } from "./domains/playground/routes";
+import { wirePlayground } from "./domains/playground/bootstrap";
 
 // Domain: Admin
 import { createAdminRoutes } from "./domains/admin/routes";
@@ -113,9 +110,7 @@ import { createMeRoutes } from "./domains/me/routes";
 import { createUserRoutes } from "./domains/users/routes";
 
 // Domain: Platform settings (legacy single-doc — still used by mirror, audit-waiver) ----
-import { PlatformSettingsRepository } from "./domains/platform/repository";
-import { PlatformSettingsService } from "./domains/platform/service";
-import { createPlatformSettingsRoutes } from "./domains/platform/routes";
+import { wirePlatformSettings } from "./domains/platform/bootstrap";
 
 // Domain: Settings (multi-section + LLM providers + export/import) — backend-engineer-2.
 import { SettingsRepository } from "./domains/settings/repository";
@@ -125,28 +120,20 @@ import { migrateLegacyMirrorIntoSettings } from "./domains/settings/sections/mir
 import { LlmProvidersRepository } from "./domains/settings/llmProviders/repository";
 import { LlmProvidersService } from "./domains/settings/llmProviders/service";
 import { createLlmProvidersRoutes } from "./domains/settings/llmProviders/routes";
+import type { ApiFormat } from "./domains/settings/llmProviders/types";
 import { SettingsExporter } from "./domains/settings/exportImport/exporter";
 import { SettingsImporter } from "./domains/settings/exportImport/importer";
 import { createSettingsExportImportRoutes } from "./domains/settings/exportImport/routes";
 import { LlmModelListClient } from "./clients/llmModelListClient";
 
 // Domain: Quota (per-user playground / skill-gen counters + admin grants)
-import { QuotaRepository } from "./domains/quota/repository";
-import { QuotaService } from "./domains/quota/service";
-import { createQuotaRoutes } from "./domains/quota/routes";
+import { wireQuota } from "./domains/quota/bootstrap";
 
 // Domain: Redemption codes (admin-issued single-use quota grants)
-import { RedemptionCodeRepository } from "./domains/redemption-codes/repository";
-import { RedemptionCodeService } from "./domains/redemption-codes/service";
-import { createAdminRedemptionCodesRoutes } from "./domains/admin/redemption-codes/routes";
-import { createMeRedemptionCodesRoutes } from "./domains/redemption-codes/me-routes";
+import { wireRedemptionCodes } from "./domains/redemption-codes/bootstrap";
 
 // Domain: Admin (engineer-1): dashboard, users, quota admin.
-import { AdminDashboardService } from "./domains/admin/dashboard/service";
-import { createAdminDashboardRoutes } from "./domains/admin/dashboard/routes";
-import { createAdminQuotaRoutes } from "./domains/admin/quota/routes";
-import { AdminUsersService } from "./domains/admin-users/service";
-import { createAdminUsersRoutes } from "./domains/admin-users/routes";
+import { wireAdmin } from "./domains/admin/bootstrap";
 
 // LLM provider migration (#270 — fold legacy global model catalog into
 // per-provider arrays). One-time, idempotent, runs before any
@@ -158,7 +145,7 @@ import { createLlmPickerRoutes } from "./domains/settings/llmProviders/routes";
 import { buildSpec } from "./openapi/specBuilder";
 
 // Error handler
-import { AppError } from "./shared/types/index";
+import { AppError, buildProblemJsonBody } from "./shared/types/index";
 
 export interface BootstrapResult {
   app: Hono;
@@ -202,7 +189,7 @@ export async function bootstrap(config: SkillConfig): Promise<BootstrapResult> {
     python: config.agentsealPython,
     script: config.agentsealScript,
     timeoutMs: 60_000,
-    enabled: true,
+    enabled: config.agentsealEnabled,
     logger,
   });
 
@@ -315,22 +302,41 @@ export async function bootstrap(config: SkillConfig): Promise<BootstrapResult> {
     logger.warn({ err }, "users indexes ensureIndexes failed — proceeding anyway"),
   );
 
+  // ---- Idempotency-Key cache (#459). 24h TTL on `idempotency_keys`;
+  // mongo's TTL monitor sweeps once a minute. Index creation is
+  // fire-and-forget so a single-replica boot still comes up if the
+  // monitor temporarily refuses (it'll be re-attempted on next boot).
+  const idempotencyKeyRepo = new IdempotencyKeyRepository(db);
+  void idempotencyKeyRepo.ensureIndexes().catch((err) =>
+    logger.warn({ err }, "idempotency_keys indexes ensureIndexes failed — proceeding anyway"),
+  );
+
   // Convenience: resolve the LLM provider for a given surface in a
   // single Promise, projecting whichever auth shape the provider uses
-  // into the simpler `{ gatewayUrl, apiKey }` contract `NyxLlmClient`
-  // speaks. `apiKey` empty means "use SA token-exchange flow".
+  // into the simpler `{ gatewayUrl, apiKey, apiFormat }` contract
+  // `NyxLlmClient` speaks. `apiKey` empty means "use SA token-exchange
+  // flow". `apiFormat` selects the upstream endpoint shape (#574); when
+  // no provider is configured we still return a default so the type
+  // shape stays narrow — the empty `gatewayUrl` is what triggers the
+  // fail-closed branch downstream.
   const resolveLlmProviderForSurface = async (
     surface: "playground" | "skillGen",
-  ): Promise<{ gatewayUrl: string; apiKey: string }> => {
+  ): Promise<{ gatewayUrl: string; apiKey: string; apiFormat: ApiFormat }> => {
     const sec =
       surface === "playground"
         ? await settingsService.getPlayground()
         : await settingsService.getSkillGen();
-    if (!sec.defaultProviderId) return { gatewayUrl: "", apiKey: "" };
+    if (!sec.defaultProviderId) {
+      return { gatewayUrl: "", apiKey: "", apiFormat: "responses" };
+    }
     const provider = await llmProvidersService.get(sec.defaultProviderId);
-    if (!provider) return { gatewayUrl: "", apiKey: "" };
+    if (!provider) return { gatewayUrl: "", apiKey: "", apiFormat: "responses" };
     const apiKey = provider.auth.kind === "apiKey" ? provider.auth.apiKey : "";
-    return { gatewayUrl: provider.gatewayUrl, apiKey };
+    return {
+      gatewayUrl: provider.gatewayUrl,
+      apiKey,
+      apiFormat: provider.apiFormat,
+    };
   };
 
   // Same pattern, returning the per-surface model + token cap +
@@ -437,6 +443,7 @@ export async function bootstrap(config: SkillConfig): Promise<BootstrapResult> {
 
   // ---- Repositories ----
   const skillRepo = new SkillRepository(db);
+  await skillRepo.ensureIndexes();
   const skillVersionRepo = new SkillVersionRepository(db);
   await skillVersionRepo.ensureIndexes();
 
@@ -451,75 +458,32 @@ export async function bootstrap(config: SkillConfig): Promise<BootstrapResult> {
     agentsealScanner,
   });
 
-  // ---- Domain: Notifications (built before AuditService so the audit
-  //   pipeline can fan out completion notifications) ----
-  const notificationRepo = new NotificationRepository(db);
-  void notificationRepo.ensureIndexes().catch((err) =>
-    logger.warn({ err }, "notifications indexes ensureIndexes failed — proceeding anyway"),
-  );
-  // One-time boot migration (#218) — drop legacy `share.*` rows left over
-  // from the pre-#198 share/audit-gate workflow. Idempotent; no-op after
-  // first run. Failure is non-fatal — old rows surface as ugly UI but
-  // never block the boot.
-  await dropLegacyNotificationCategories(db).catch((err) =>
-    logger.error(
-      { err: err instanceof Error ? err.message : String(err) },
-      "dropLegacyNotificationCategories failed — legacy notification rows may still surface in /notifications until the next deploy",
-    ),
-  );
-  // `broadcastRepo` is constructed in the broadcasts block below; we
-  // need a reference at NotificationService-build time so the merged
-  // feed (#500) can left-join read receipts. Reordered so broadcasts
-  // build first.
-  const broadcastRepoForNotifications = new BroadcastRepository(db);
-  void broadcastRepoForNotifications.ensureIndexes().catch((err) =>
-    logger.warn({ err }, "broadcasts indexes ensureIndexes failed — proceeding anyway"),
-  );
-  // One-shot bilingual + targeting backfill for broadcasts. Pre-#502
-  // docs don't carry `recipientUserIds`; this migration writes an
-  // explicit `null` on every absent doc so the merged feed can rely
-  // on a stable `string[] | null` shape. Idempotent; failure is
-  // non-fatal — the repo mapper's `Array.isArray` guard already
-  // normalises absent fields to `null` on the read path.
-  await backfillBroadcastRecipientUserIds(db, logger).catch((err) =>
-    logger.error(
-      { err: err instanceof Error ? err.message : String(err) },
-      "broadcasts recipientUserIds backfill crashed — mapper fallback will cover reads, retry on next boot",
-    ),
-  );
-  const notificationService = new NotificationService({
-    notificationRepo,
-    broadcastRepo: broadcastRepoForNotifications,
+  // ---- Domain: Notifications + Broadcasts ----
+  // The two share a single BroadcastRepository instance: notifications
+  // reads it on the merged-feed path (#500 left-join), broadcasts
+  // writes through its own service on admin CRUD. Build the repo
+  // first so notifications can take its reference, then wire each
+  // surface's service + routes. Notifications is built before the
+  // audit service so the audit pipeline can fan out completion
+  // notifications.
+  const { repo: broadcastRepoForNotifications } = await wireBroadcastsRepo({
+    db,
+    logger,
   });
-  const notificationRoutes = createNotificationRoutes({ notificationService });
+  const { service: notificationService, routes: notificationRoutes } =
+    await wireNotifications({
+      db,
+      logger,
+      broadcastRepo: broadcastRepoForNotifications,
+    });
 
   // ---- Domain: Announcements (landing-page popup, issue #307) ----
-  const announcementRepo = new AnnouncementRepository(db);
-  void announcementRepo.ensureIndexes().catch((err) =>
-    logger.warn({ err }, "announcements indexes ensureIndexes failed — proceeding anyway"),
-  );
-  // One-shot bilingual backfill: copies legacy single-locale columns
-  // (title / bodyMarkdown / ctaLabel) into the new per-locale slots
-  // (`*En` + `*Zh`) on existing docs. Idempotent — second boot is a
-  // no-op. Failure is logged + non-fatal; the repo's mapper falls
-  // back to legacy fields if the migration hasn't run yet.
-  await migrateAnnouncementsToBilingual(db, logger).catch((err) =>
-    logger.error(
-      { err: err instanceof Error ? err.message : String(err) },
-      "announcements bilingual migration crashed — repo fallback will cover reads, retry on next boot",
-    ),
-  );
-  const announcementService = new AnnouncementService({ repo: announcementRepo });
-  const announcementRoutes = createAnnouncementRoutes({ announcementService });
+  const { routes: announcementRoutes } = await wireAnnouncements({ db, logger });
 
   // ---- Domain: Broadcasts (admin-authored, fan-out via notifications, #500) ----
-  // Reuse the same `BroadcastRepository` instance the notifications
-  // service got — both surfaces share state (admin CRUD + per-user
-  // feed merge), and a single instance keeps the wiring legible.
-  const broadcastService = new BroadcastService({
+  const { routes: broadcastRoutes } = wireBroadcasts({
     repo: broadcastRepoForNotifications,
   });
-  const broadcastRoutes = createBroadcastRoutes({ broadcastService });
 
   // ---- NyxID Orgs Client — built early so the audit fan-out can expand
   //   sharedWithOrgs into member rosters when sending consumer notifications.
@@ -562,12 +526,11 @@ export async function bootstrap(config: SkillConfig): Promise<BootstrapResult> {
   const auditRoutes = createAuditRoutes({ auditService, skillService });
 
   // ---- Domain: Analytics ----
-  const analyticsRepo = new AnalyticsRepository(db);
-  void analyticsRepo.ensureIndexes().catch((err) =>
-    logger.warn({ err }, "skill_executions indexes ensureIndexes failed — proceeding anyway"),
-  );
-  const analyticsService = new AnalyticsService({ analyticsRepo });
-  const analyticsRoutes = createAnalyticsRoutes({ analyticsService, skillService });
+  const { service: analyticsService, routes: analyticsRoutes } = wireAnalytics({
+    db,
+    logger,
+    skillService,
+  });
 
   // ---- Domain: Platform settings (admin-editable: audit threshold, mirror config, LLM override) ----
   // Backend-engineer-2 is replacing this with a multi-section
@@ -576,11 +539,10 @@ export async function bootstrap(config: SkillConfig): Promise<BootstrapResult> {
   // the existing single-doc `PlatformSettings` shape into the bridge
   // contract — every field a client/route asks for is satisfied here
   // (with sensible fallbacks for sections that don't exist yet).
-  const platformSettingsRepo = new PlatformSettingsRepository(db);
-  const platformSettingsService = new PlatformSettingsService(platformSettingsRepo, {
+  const { routes: platformSettingsRoutes } = wirePlatformSettings({
+    db,
     encryptionKey: config.encryptionKey,
   });
-  const platformSettingsRoutes = createPlatformSettingsRoutes({ platformSettingsService });
 
   // ---- Settings routes (engineer-2): per-section CRUD, LLM providers,
   //   export/import.
@@ -636,35 +598,18 @@ export async function bootstrap(config: SkillConfig): Promise<BootstrapResult> {
   });
 
   // ---- Domain: Quota (per-user playground / skill-gen counters + admin grants) ----
-  const quotaRepo = new QuotaRepository(db);
-  void quotaRepo.ensureIndexes().catch((err) =>
-    logger.warn({ err }, "quota indexes ensureIndexes failed — proceeding anyway"),
-  );
-
-  // ---- Domain: Redemption codes (single-use admin-issued quota grants) ----
-  const redemptionCodeRepo = new RedemptionCodeRepository(db);
-  void redemptionCodeRepo.ensureIndexes().catch((err) =>
-    logger.warn({ err }, "redemption_codes indexes ensureIndexes failed — proceeding anyway"),
-  );
-  const quotaService = new QuotaService({
-    repo: quotaRepo,
-    defaults: {
-      getQuotaDefaults: async () => {
-        const [pg, sg] = await Promise.all([
-          settingsService.getPlayground(),
-          settingsService.getSkillGen(),
-        ]);
-        return {
-          defaultPlaygroundMonthly: pg.defaultMonthlyQuota,
-          defaultSkillGenMonthly: sg.defaultMonthlyQuota,
-        };
-      },
-    },
+  const { service: quotaService, routes: quotaRoutes } = wireQuota({
+    db,
+    logger,
+    settingsService,
     notificationService,
   });
-  const quotaRoutes = createQuotaRoutes({
-    quotaService,
-  });
+
+  // ---- Domain: Redemption codes (single-use admin-issued quota grants) ----
+  const {
+    adminRoutes: adminRedemptionCodesRoutes,
+    meRoutes: meRedemptionCodesRoutes,
+  } = wireRedemptionCodes({ db, logger, quotaService });
 
   // ---- Per-provider model catalog migration (#270) ----
   // Fold the standalone `models` collection into `llm_providers.models[]`
@@ -681,8 +626,22 @@ export async function bootstrap(config: SkillConfig): Promise<BootstrapResult> {
 
   // The picker route — `GET /me/models?surface=...` — reads from the
   // per-provider arrays via `LlmProvidersService` (already constructed
-  // upstream as part of `domains/settings/...`).
-  const llmPickerRoutes = createLlmPickerRoutes({ llmProvidersService });
+  // upstream as part of `domains/settings/...`). The section-default
+  // resolver (#607) lets the picker honour the per-surface
+  // `defaultModelId` pin set in admin Playground / Skill-Gen settings,
+  // so the picker pre-selection agrees with what the chat execute
+  // path falls back to. Falls through to the per-model
+  // `defaultForX` flag when no pin is configured.
+  const llmPickerRoutes = createLlmPickerRoutes({
+    llmProvidersService,
+    sectionDefaultResolver: async (surface) => {
+      const sec =
+        surface === "playground"
+          ? await settingsService.getPlayground()
+          : await settingsService.getSkillGen();
+      return sec.defaultModelId ?? null;
+    },
+  });
 
   // ---- Domain: GitHub Mirror ----
   // Single MirrorService instance — runtime-aware. Reads enabled +
@@ -745,49 +704,38 @@ export async function bootstrap(config: SkillConfig): Promise<BootstrapResult> {
   });
 
   // ---- Domain: Skill Search ----
-  const searchService = new SearchService({
+  // Search shares the playground surface for default-model resolution
+  // (it's a playground-flavoured LLM call). Backend-eng-2 may add a
+  // dedicated `search` section later; until then, share with playground.
+  const { routes: searchRoutes } = wireSkillSearch({
     skillRepo,
     llmClient: nyxLlmClient,
-    // Default model resolves through the playground surface (search is
-    // a playground-flavoured LLM call). Backend-eng-2 may add a
-    // dedicated `search` section later; until then, share with playground.
     defaultModelResolver: async () =>
       (await resolveSurfaceDefaults("playground")).model,
-  });
-
-  const searchRoutes = createSearchRoutes({
-    searchService,
-    skillRepo,
+    nyxidServiceClient,
+    getSaAccessToken,
   });
 
   // ---- Domain: Skill Generation ----
-  const generationService = new SkillGenerationService({
-    llmClient: nyxLlmClient,
-    defaultsResolver: async () => resolveSurfaceDefaults("skillGen"),
-  });
-
-  const generationRoutes = createGenerationRoutes({
-    generationService,
-    keepAliveIntervalMsResolver: async () =>
-      (await settingsService.getSkillGen()).sseKeepAliveMs,
-    quotaService,
-    llmProvidersService,
-  });
+  const { service: generationService, routes: generationRoutes } =
+    wireSkillGeneration({
+      llmClient: nyxLlmClient,
+      defaultsResolver: async () => resolveSurfaceDefaults("skillGen"),
+      keepAliveIntervalMsResolver: async () =>
+        (await settingsService.getSkillGen()).sseKeepAliveMs,
+      quotaService,
+      llmProvidersService,
+    });
 
   // ---- Domain: Playground ----
-  const chatService = new PlaygroundChatService({
+  const { routes: playgroundRoutes } = wirePlayground({
     llmClient: nyxLlmClient,
     sandboxClient,
     skillService,
     defaultsResolver: async () => resolveSurfaceDefaults("playground"),
-  });
-
-  const playgroundRoutes = createPlaygroundRoutes({
-    chatService,
     keepAliveIntervalMsResolver: async () =>
       (await settingsService.getPlayground()).sseKeepAliveMs,
     analyticsService,
-    skillService,
     quotaService,
     llmProvidersService,
   });
@@ -844,49 +792,52 @@ export async function bootstrap(config: SkillConfig): Promise<BootstrapResult> {
     }, "Request completed");
   });
 
-  // Global error handler — single `AppError` hierarchy across the whole
-  // service, so `instanceof` is sufficient (no more duck-typing).
+  // Global error handler — emits RFC 7807 `application/problem+json`
+  // per CONVENTIONS.md §1.3 (#456). The legacy `{ data, error }`
+  // envelope is gone; clients read fields at the body root now (`code`,
+  // `status`, `detail`, `title`, `type`, `instance`, `requestId`).
   app.onError((err, c) => {
     const requestId = getRequestId(c);
-    // userId is optional on auth-context; use null distinct id when absent.
     const authCtx = (c.get as (k: string) => unknown)("auth") as
       | { userId?: string }
       | undefined;
     const userId = authCtx?.userId ?? null;
 
-    if (err instanceof AppError) {
-      logger.warn({ requestId, code: err.code, status: err.statusCode }, err.message);
-      // 5xx AppErrors are still real server failures — emit api.error
-      // (sampled) so PostHog has the same fidelity as runtime crashes.
-      if (err.statusCode >= 500) {
-        analyticsEmitter.trackApiError({
-          userId,
-          statusCode: err.statusCode,
-          errorCode: err.code,
-          method: c.req.method,
-          path: c.req.path,
-          requestId,
-        });
-      }
-      return c.json(
-        { data: null, error: { code: err.code, message: err.message } },
-        err.statusCode as any,
-      );
+    const appError = err instanceof AppError ? err : null;
+    const statusCode = appError?.statusCode ?? 500;
+    const code = appError?.code ?? "internal_error";
+    const detail = appError ? appError.message : "Internal server error";
+
+    if (appError) {
+      logger.warn({ requestId, code, status: statusCode }, appError.message);
+    } else {
+      logger.error({ requestId, err }, "Unhandled error");
     }
 
-    logger.error({ requestId, err }, "Unhandled error");
-    analyticsEmitter.trackApiError({
-      userId,
-      statusCode: 500,
-      errorCode: "INTERNAL_ERROR",
-      method: c.req.method,
-      path: c.req.path,
+    // 5xx errors (AppError or unhandled crash) feed PostHog so runtime
+    // crashes and `AppError.serviceUnavailable`-class failures land in
+    // the same dashboard.
+    if (statusCode >= 500) {
+      analyticsEmitter.trackApiError({
+        userId,
+        statusCode,
+        errorCode: code,
+        method: c.req.method,
+        path: c.req.path,
+        requestId,
+      });
+    }
+
+    const body = buildProblemJsonBody({
+      statusCode,
+      code,
+      message: detail,
+      instance: c.req.path,
       requestId,
     });
-    return c.json(
-      { data: null, error: { code: "INTERNAL_ERROR", message: "Internal server error" } },
-      500,
-    );
+    return c.json(body, statusCode as ContentfulStatusCode, {
+      "Content-Type": "application/problem+json",
+    });
   });
 
   // ---- API routes — all traffic via NyxID proxy, trust proxy headers ----
@@ -920,34 +871,19 @@ export async function bootstrap(config: SkillConfig): Promise<BootstrapResult> {
   // single request even when multiple routes call `readUserOrgMemberships`.
   apiApp.use("*", nyxidOrgLookupMiddleware(nyxidOrgsClient));
 
-  // ---- Admin routes (engineer-1): dashboard, users, quota admin ----
-  const adminDashboardService = new AdminDashboardService({
-    db,
-    userDirectoryRepo,
-  });
-  const adminDashboardRoutes = createAdminDashboardRoutes({
-    dashboardService: adminDashboardService,
-  });
-  const adminUsersService = new AdminUsersService({
-    db,
-    userDirectoryRepo,
-  });
-  const adminUsersRoutes = createAdminUsersRoutes({ adminUsersService });
-  const adminQuotaRoutes = createAdminQuotaRoutes({
-    quotaService,
-    userDirectoryRepo,
-  });
-  const redemptionCodeService = new RedemptionCodeService({
-    repo: redemptionCodeRepo,
-    quotaService,
-  });
-  const adminRedemptionCodesRoutes = createAdminRedemptionCodesRoutes({
-    redemptionCodeService,
-  });
-  const meRedemptionCodesRoutes = createMeRedemptionCodesRoutes({
-    redemptionCodeService,
-  });
+  // Idempotency-Key replay cache (#459). Mounted AFTER `proxyAuthSetup`
+  // so it can scope cache entries per `auth.userId` — without that, two
+  // unrelated callers using the same key would replay each other's
+  // response. Non-mutating methods (GET/HEAD/OPTIONS) and requests
+  // without an `Idempotency-Key` header are passed through untouched.
+  apiApp.use("*", idempotencyMiddleware({ repo: idempotencyKeyRepo }));
 
+  // ---- Admin routes (engineer-1): dashboard, users, quota admin ----
+  const {
+    dashboardRoutes: adminDashboardRoutes,
+    usersRoutes: adminUsersRoutes,
+    quotaRoutes: adminQuotaRoutes,
+  } = wireAdmin({ db, userDirectoryRepo, quotaService });
   apiApp.route("/", skillRoutes);
   apiApp.route("/", mirrorRoutes);
   apiApp.route("/", auditRoutes);
diff --git a/ornn-api/src/clients/llmModelListClient.ts b/ornn-api/src/clients/llmModelListClient.ts
index 7ca00a98..66994ac7 100644
--- a/ornn-api/src/clients/llmModelListClient.ts
+++ b/ornn-api/src/clients/llmModelListClient.ts
@@ -32,7 +32,7 @@
  * @module clients/llmModelListClient
  */
 
-import pino from "pino";
+import { createLogger } from "../shared/logger";
 import type {
   ApiFormat,
   LlmProviderAuth,
@@ -43,7 +43,7 @@ import {
   SsrfRefusalError,
 } from "../infra/url";
 
-const logger = pino({ level: "info" }).child({ module: "llmModelListClient" });
+const logger = createLogger("llmModelListClient");
 
 /** Max wall-clock for a single upstream request (model-list or token-exchange). */
 const FETCH_TIMEOUT_MS = 15_000;
diff --git a/ornn-api/src/clients/nyxid/auth.test.ts b/ornn-api/src/clients/nyxid/auth.test.ts
deleted file mode 100644
index 3fd9c2ea..00000000
--- a/ornn-api/src/clients/nyxid/auth.test.ts
+++ /dev/null
@@ -1,71 +0,0 @@
-import { describe, test, expect, mock, afterEach } from "bun:test";
-import { AuthClient } from "./auth";
-
-const BASE_URL = "http://auth:3801";
-const SECRET = "test-secret";
-
-describe("AuthClient", () => {
-  const originalFetch = globalThis.fetch;
-
-  afterEach(() => {
-    globalThis.fetch = originalFetch;
-  });
-
-  test("validateApiKey sends POST with key and auth header", async () => {
-    const mockFetch = mock(async () =>
-      new Response(JSON.stringify({
-        data: { userId: "u-123", permissions: ["search:read"], status: "active" },
-      }), { status: 200 }),
-    );
-    globalThis.fetch = mockFetch as any;
-
-    const client = new AuthClient(BASE_URL, SECRET);
-    const result = await client.validateApiKey("sk_testkey");
-
-    expect(result).not.toBeNull();
-    expect(result!.userId).toBe("u-123");
-    expect(result!.permissions).toEqual(["search:read"]);
-
-    const [url, opts] = mockFetch.mock.calls[0] as unknown as [string, RequestInit];
-    expect(url).toBe(`${BASE_URL}/api/internal/api-keys/validate`);
-    expect(opts.method).toBe("POST");
-    const headers = opts.headers as Record<string, string>;
-    expect(headers["X-Internal-Auth"]).toBe(SECRET);
-    const body = JSON.parse(opts.body as string);
-    expect(body.key).toBe("sk_testkey");
-  });
-
-  test("returns null for invalid key (data is null)", async () => {
-    const mockFetch = mock(async () =>
-      new Response(JSON.stringify({ data: null }), { status: 200 }),
-    );
-    globalThis.fetch = mockFetch as any;
-
-    const client = new AuthClient(BASE_URL, SECRET);
-    const result = await client.validateApiKey("sk_invalid");
-    expect(result).toBeNull();
-  });
-
-  test("returns null on 401 response", async () => {
-    globalThis.fetch = mock(async () => new Response("unauthorized", { status: 401 })) as any;
-
-    const client = new AuthClient(BASE_URL, SECRET);
-    const result = await client.validateApiKey("sk_invalid");
-    expect(result).toBeNull();
-  });
-
-  test("returns null on 404 response", async () => {
-    globalThis.fetch = mock(async () => new Response("not found", { status: 404 })) as any;
-
-    const client = new AuthClient(BASE_URL, SECRET);
-    const result = await client.validateApiKey("sk_invalid");
-    expect(result).toBeNull();
-  });
-
-  test("throws AppError on 500 response", async () => {
-    globalThis.fetch = mock(async () => new Response("fail", { status: 500 })) as any;
-
-    const client = new AuthClient(BASE_URL, SECRET);
-    await expect(client.validateApiKey("sk_test")).rejects.toThrow("Auth service returned 500");
-  });
-});
diff --git a/ornn-api/src/clients/nyxid/auth.ts b/ornn-api/src/clients/nyxid/auth.ts
deleted file mode 100644
index d4d563fb..00000000
--- a/ornn-api/src/clients/nyxid/auth.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-/**
- * HTTP client for calling ornn-auth service.
- * Used for API key validation (search/MCP endpoints).
- * @module clients/nyxid/auth
- */
-
-import { AppError, INTERNAL_AUTH_HEADER, type ApiKeyInfo } from "../../shared/types/index";
-
-/** Interface for auth operations needed by ornn-api. */
-export interface IAuthClient {
-  /** Validate an API key and return user info if valid. */
-  validateApiKey(key: string): Promise<ApiKeyInfo | null>;
-}
-
-/** HTTP client that calls ornn-auth for API key validation. */
-export class AuthClient implements IAuthClient {
-  constructor(
-    private readonly baseUrl: string,
-    private readonly secret: string,
-  ) {}
-
-  async validateApiKey(key: string): Promise<ApiKeyInfo | null> {
-    const res = await fetch(`${this.baseUrl}/api/internal/api-keys/validate`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        [INTERNAL_AUTH_HEADER]: this.secret,
-      },
-      body: JSON.stringify({ key }),
-    });
-
-    if (!res.ok) {
-      if (res.status === 404 || res.status === 401) return null;
-      throw AppError.serviceUnavailable("AUTH_SERVICE_ERROR", `Auth service returned ${res.status}`);
-    }
-
-    const json = await res.json() as { data: ApiKeyInfo | null };
-    return json.data;
-  }
-}
diff --git a/ornn-api/src/clients/nyxid/base.ts b/ornn-api/src/clients/nyxid/base.ts
index 962ea29c..52e0a374 100644
--- a/ornn-api/src/clients/nyxid/base.ts
+++ b/ornn-api/src/clients/nyxid/base.ts
@@ -16,9 +16,8 @@
  * @module clients/nyxid/base
  */
 
-import pino from "pino";
-
-const logger = pino({ level: "info" }).child({ module: "nyxidSaTokenProvider" });
+import { createLogger } from "../../shared/logger";
+const logger = createLogger("nyxidSaTokenProvider");
 
 /**
  * Runtime-resolvable NyxID config. Sourced from admin settings on every
diff --git a/ornn-api/src/clients/nyxid/llm.test.ts b/ornn-api/src/clients/nyxid/llm.test.ts
new file mode 100644
index 00000000..143dc852
--- /dev/null
+++ b/ornn-api/src/clients/nyxid/llm.test.ts
@@ -0,0 +1,402 @@
+/**
+ * Tests for #574: NyxLlmClient must dispatch on the resolved
+ * provider's `apiFormat` — `responses` hits `/responses` with native
+ * body, `chat-completion` hits `/chat/completions` with translated
+ * body and normalizes text deltas back into Responses-API event shape.
+ *
+ * Tool-call delta normalization for chat-completion is out of scope here
+ * (tracked in #608).
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import {
+  NyxLlmClient,
+  type LlmProviderResolution,
+  type ResponsesApiStreamEvent,
+} from "./llm";
+import type { NyxidSaTokenProvider } from "./base";
+
+// ---------------------------------------------------------------------------
+// Test doubles
+// ---------------------------------------------------------------------------
+
+const STUB_SA_TOKEN: NyxidSaTokenProvider = {
+  getAccessToken: async () => "sa-token-xyz",
+} as unknown as NyxidSaTokenProvider;
+
+function makeResolver(resolution: LlmProviderResolution) {
+  return async () => resolution;
+}
+
+/** Build an SSE Response body from a sequence of `data:` payloads. */
+function sseResponse(events: string[]): Response {
+  const body = events.map((e) => `data: ${e}\n\n`).join("") + "data: [DONE]\n\n";
+  return new Response(body, {
+    status: 200,
+    headers: { "Content-Type": "text/event-stream" },
+  });
+}
+
+function jsonResponse(payload: unknown, status = 200): Response {
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+interface CapturedRequest {
+  url: string;
+  method: string;
+  body: unknown;
+  headers: Record<string, string>;
+}
+
+const originalFetch = globalThis.fetch;
+let capturedRequests: CapturedRequest[];
+let fetchHandler: (req: Request) => Promise<Response> | Response;
+
+beforeEach(() => {
+  capturedRequests = [];
+  fetchHandler = () => new Response("no handler set", { status: 500 });
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+    const method = (init?.method ?? "GET").toUpperCase();
+    const rawBody = init?.body;
+    let parsedBody: unknown = rawBody;
+    if (typeof rawBody === "string") {
+      try {
+        parsedBody = JSON.parse(rawBody);
+      } catch {
+        /* leave as string */
+      }
+    }
+    const headers: Record<string, string> = {};
+    const initHeaders = init?.headers;
+    if (initHeaders instanceof Headers) {
+      initHeaders.forEach((v, k) => { headers[k] = v; });
+    } else if (Array.isArray(initHeaders)) {
+      for (const [k, v] of initHeaders) headers[k] = v;
+    } else if (initHeaders && typeof initHeaders === "object") {
+      Object.assign(headers, initHeaders);
+    }
+    capturedRequests.push({ url, method, body: parsedBody, headers });
+    const req = new Request(url, init);
+    return fetchHandler(req);
+  }) as typeof fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+// ---------------------------------------------------------------------------
+// stream() — endpoint + body dispatch
+// ---------------------------------------------------------------------------
+
+describe("NyxLlmClient.stream() routing on apiFormat", () => {
+  it("apiFormat=responses → POST /responses with native body", async () => {
+    fetchHandler = () =>
+      sseResponse([
+        JSON.stringify({ type: "response.output_text.delta", delta: "hello" }),
+      ]);
+
+    const client = new NyxLlmClient({
+      resolver: makeResolver({
+        gatewayUrl: "https://gateway.example.com",
+        apiKey: "sk-direct",
+        apiFormat: "responses",
+      }),
+      saTokenProvider: STUB_SA_TOKEN,
+    });
+
+    const events: ResponsesApiStreamEvent[] = [];
+    for await (const e of client.stream({
+      model: "gpt-test",
+      input: [{ role: "user", content: "hi" }],
+      instructions: "be brief",
+    })) events.push(e);
+
+    expect(capturedRequests).toHaveLength(1);
+    expect(capturedRequests[0]!.url).toBe("https://gateway.example.com/responses");
+    expect(capturedRequests[0]!.method).toBe("POST");
+    expect(capturedRequests[0]!.headers["Authorization"]).toBe("Bearer sk-direct");
+    expect(capturedRequests[0]!.body).toMatchObject({
+      model: "gpt-test",
+      input: [{ role: "user", content: "hi" }],
+      instructions: "be brief",
+      stream: true,
+      store: false,
+    });
+    expect(events).toEqual([
+      { type: "response.output_text.delta", delta: "hello" },
+    ]);
+  });
+
+  it("apiFormat=chat-completion → POST /chat/completions with translated body", async () => {
+    fetchHandler = () =>
+      sseResponse([
+        JSON.stringify({ choices: [{ delta: { content: "Hel" } }] }),
+        JSON.stringify({ choices: [{ delta: { content: "lo" } }] }),
+        JSON.stringify({ choices: [{ delta: {}, finish_reason: "stop" }] }),
+      ]);
+
+    const client = new NyxLlmClient({
+      resolver: makeResolver({
+        gatewayUrl: "https://api.deepseek.com/",
+        apiKey: "sk-deepseek",
+        apiFormat: "chat-completion",
+      }),
+      saTokenProvider: STUB_SA_TOKEN,
+    });
+
+    const events: ResponsesApiStreamEvent[] = [];
+    for await (const e of client.stream({
+      model: "deepseek-v4-flash",
+      input: [
+        { role: "developer", content: "you are helpful" },
+        { role: "user", content: "summarize" },
+      ],
+      instructions: "respond in english",
+      max_output_tokens: 256,
+      temperature: 0.3,
+    })) events.push(e);
+
+    expect(capturedRequests).toHaveLength(1);
+    expect(capturedRequests[0]!.url).toBe("https://api.deepseek.com/chat/completions");
+    expect(capturedRequests[0]!.body).toMatchObject({
+      model: "deepseek-v4-flash",
+      messages: [
+        { role: "system", content: "respond in english" },
+        { role: "system", content: "you are helpful" },
+        { role: "user", content: "summarize" },
+      ],
+      max_tokens: 256,
+      temperature: 0.3,
+      stream: true,
+    });
+    // No `input` / `max_output_tokens` should leak into chat-completion body.
+    expect((capturedRequests[0]!.body as Record<string, unknown>).input).toBeUndefined();
+    expect((capturedRequests[0]!.body as Record<string, unknown>).max_output_tokens).toBeUndefined();
+
+    // Text deltas normalized into Responses-API shape.
+    expect(events).toEqual([
+      { type: "response.output_text.delta", delta: "Hel" },
+      { type: "response.output_text.delta", delta: "lo" },
+    ]);
+  });
+
+  it("chat-completion translates tools array into OpenAI function-tool shape", async () => {
+    fetchHandler = () => sseResponse([]);
+    const client = new NyxLlmClient({
+      resolver: makeResolver({
+        gatewayUrl: "https://api.example.com",
+        apiKey: "sk-x",
+        apiFormat: "chat-completion",
+      }),
+      saTokenProvider: STUB_SA_TOKEN,
+    });
+
+    const events: ResponsesApiStreamEvent[] = [];
+    for await (const e of client.stream({
+      model: "m",
+      input: [{ role: "user", content: "go" }],
+      tools: [
+        {
+          type: "function",
+          name: "do_thing",
+          description: "does the thing",
+          parameters: { type: "object", properties: { x: { type: "string" } } },
+        },
+      ],
+    })) events.push(e);
+
+    expect((capturedRequests[0]!.body as Record<string, unknown>).tools).toEqual([
+      {
+        type: "function",
+        function: {
+          name: "do_thing",
+          description: "does the thing",
+          parameters: { type: "object", properties: { x: { type: "string" } } },
+        },
+      },
+    ]);
+  });
+
+  it("flattens Responses-API content parts into a string for chat-completion", async () => {
+    fetchHandler = () => sseResponse([]);
+    const client = new NyxLlmClient({
+      resolver: makeResolver({
+        gatewayUrl: "https://api.example.com",
+        apiKey: "sk-x",
+        apiFormat: "chat-completion",
+      }),
+      saTokenProvider: STUB_SA_TOKEN,
+    });
+
+    const events: ResponsesApiStreamEvent[] = [];
+    for await (const e of client.stream({
+      model: "m",
+      input: [
+        {
+          role: "user",
+          content: [
+            { type: "input_text", text: "part 1 " },
+            { type: "input_text", text: "part 2" },
+          ],
+        },
+      ],
+    })) events.push(e);
+
+    const body = capturedRequests[0]!.body as { messages: Array<{ role: string; content: string }> };
+    expect(body.messages).toEqual([{ role: "user", content: "part 1 part 2" }]);
+  });
+
+  it("trims trailing slash from gatewayUrl for both formats", async () => {
+    fetchHandler = () => sseResponse([]);
+    const client = new NyxLlmClient({
+      resolver: makeResolver({
+        gatewayUrl: "https://api.example.com///",
+        apiKey: "sk-x",
+        apiFormat: "chat-completion",
+      }),
+      saTokenProvider: STUB_SA_TOKEN,
+    });
+    const events: ResponsesApiStreamEvent[] = [];
+    for await (const e of client.stream({
+      model: "m",
+      input: [{ role: "user", content: "x" }],
+    })) events.push(e);
+    expect(capturedRequests[0]!.url).toBe("https://api.example.com/chat/completions");
+  });
+
+  it("falls back to SA token when resolved apiKey is empty", async () => {
+    fetchHandler = () => sseResponse([]);
+    const client = new NyxLlmClient({
+      resolver: makeResolver({
+        gatewayUrl: "https://api.example.com",
+        apiKey: "",
+        apiFormat: "chat-completion",
+      }),
+      saTokenProvider: STUB_SA_TOKEN,
+    });
+    const events: ResponsesApiStreamEvent[] = [];
+    for await (const e of client.stream({
+      model: "m",
+      input: [{ role: "user", content: "x" }],
+    })) events.push(e);
+    expect(capturedRequests[0]!.headers["Authorization"]).toBe("Bearer sa-token-xyz");
+  });
+
+  it("fails closed when gatewayUrl is empty (no provider configured)", async () => {
+    const client = new NyxLlmClient({
+      resolver: makeResolver({ gatewayUrl: "", apiKey: "", apiFormat: "responses" }),
+      saTokenProvider: STUB_SA_TOKEN,
+    });
+    await expect(async () => {
+      for await (const _e of client.stream({
+        model: "m",
+        input: [{ role: "user", content: "x" }],
+      })) {
+        /* drain */
+      }
+    }).toThrow(/LLM_PROVIDER_NOT_CONFIGURED/);
+    expect(capturedRequests).toHaveLength(0);
+  });
+
+  it("surfaces upstream non-2xx as sanitized error", async () => {
+    fetchHandler = () =>
+      new Response("Not Found: /responses", { status: 404 });
+    const client = new NyxLlmClient({
+      resolver: makeResolver({
+        gatewayUrl: "https://api.example.com",
+        apiKey: "sk-x",
+        apiFormat: "responses",
+      }),
+      saTokenProvider: STUB_SA_TOKEN,
+    });
+    await expect(async () => {
+      for await (const _e of client.stream({
+        model: "m",
+        input: [{ role: "user", content: "x" }],
+      })) {
+        /* drain */
+      }
+    }).toThrow(/LLM Gateway error \(404\)/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// complete() — endpoint + body dispatch
+// ---------------------------------------------------------------------------
+
+describe("NyxLlmClient.complete() routing on apiFormat", () => {
+  it("apiFormat=responses → POST /responses, returns output[]", async () => {
+    fetchHandler = () =>
+      jsonResponse({
+        output: [{ type: "message", content: [{ type: "output_text", text: "hi" }] }],
+      });
+
+    const client = new NyxLlmClient({
+      resolver: makeResolver({
+        gatewayUrl: "https://api.example.com",
+        apiKey: "sk-x",
+        apiFormat: "responses",
+      }),
+      saTokenProvider: STUB_SA_TOKEN,
+    });
+
+    const out = await client.complete({
+      model: "m",
+      input: [{ role: "user", content: "ping" }],
+    });
+    expect(capturedRequests[0]!.url).toBe("https://api.example.com/responses");
+    expect((capturedRequests[0]!.body as Record<string, unknown>).stream).toBe(false);
+    expect(out).toEqual([
+      { type: "message", content: [{ type: "output_text", text: "hi" }] },
+    ]);
+  });
+
+  it("apiFormat=chat-completion → POST /chat/completions, normalizes to ResponsesApiOutput[]", async () => {
+    fetchHandler = () =>
+      jsonResponse({
+        choices: [{ message: { role: "assistant", content: "hello world" } }],
+      });
+
+    const client = new NyxLlmClient({
+      resolver: makeResolver({
+        gatewayUrl: "https://api.example.com",
+        apiKey: "sk-x",
+        apiFormat: "chat-completion",
+      }),
+      saTokenProvider: STUB_SA_TOKEN,
+    });
+
+    const out = await client.complete({
+      model: "m",
+      input: [{ role: "user", content: "say hi" }],
+    });
+    expect(capturedRequests[0]!.url).toBe("https://api.example.com/chat/completions");
+    expect((capturedRequests[0]!.body as Record<string, unknown>).stream).toBe(false);
+    expect(out).toEqual([
+      { type: "message", content: [{ type: "output_text", text: "hello world" }] },
+    ]);
+  });
+
+  it("returns [] when chat-completion response has empty content", async () => {
+    fetchHandler = () =>
+      jsonResponse({ choices: [{ message: { role: "assistant", content: "" } }] });
+    const client = new NyxLlmClient({
+      resolver: makeResolver({
+        gatewayUrl: "https://api.example.com",
+        apiKey: "sk-x",
+        apiFormat: "chat-completion",
+      }),
+      saTokenProvider: STUB_SA_TOKEN,
+    });
+    const out = await client.complete({
+      model: "m",
+      input: [{ role: "user", content: "say nothing" }],
+    });
+    expect(out).toEqual([]);
+  });
+});
diff --git a/ornn-api/src/clients/nyxid/llm.ts b/ornn-api/src/clients/nyxid/llm.ts
index c7a0194f..1f958eca 100644
--- a/ornn-api/src/clients/nyxid/llm.ts
+++ b/ornn-api/src/clients/nyxid/llm.ts
@@ -1,17 +1,37 @@
 /**
- * HTTP client for Nyx Provider LLM Gateway (Responses API format).
- * All LLM calls (skill generation + playground chat) go through this client.
- * Authenticates using a Service Account (SA) token obtained via client_credentials grant.
+ * HTTP client for the Nyx Provider LLM Gateway.
+ *
+ * Dispatches to one of two upstream API formats per call based on the
+ * resolved provider's `apiFormat`:
+ *
+ * - `responses`        → `{gatewayUrl}/responses`        (native shape)
+ * - `chat-completion`  → `{gatewayUrl}/chat/completions` (OpenAI-style)
+ *
+ * Callers always speak Responses-API shapes (input messages, tools,
+ * `ResponsesApiStreamEvent`). For chat-completion providers the client
+ * translates the request body on the way out and normalizes the SSE
+ * stream / completion payload back into Responses-API event shape on
+ * the way in, so consumers (skill generation + playground) do not need
+ * to branch on apiFormat (#574).
+ *
+ * Tool-call delta normalization for chat-completion is intentionally
+ * out of scope here — tracked in #608.
+ *
+ * Authenticates using a Service Account (SA) token obtained via
+ * client_credentials grant when the resolved provider has no direct
+ * apiKey.
+ *
  * @module clients/nyxid/llm
  */
 
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
+import type { ApiFormat } from "../../domains/settings/llmProviders/types";
 import type { NyxidSaTokenProvider } from "./base";
 
-const logger = pino({ level: "info" }).child({ module: "nyxLlmClient" });
+const logger = createLogger("nyxLlmClient");
 
 // ---------------------------------------------------------------------------
-// Types
+// Types — caller-facing (Responses-API shape, format-agnostic)
 // ---------------------------------------------------------------------------
 
 export interface ResponsesApiInputMessage {
@@ -91,13 +111,35 @@ function sanitizeErrorResponse(status: number, rawText: string): string {
   return `LLM Gateway error (${status}): ${truncated}`;
 }
 
+/**
+ * Flatten a Responses-API content union into a single string for
+ * Chat Completions, which accepts string content for most roles.
+ * Preserves text order; non-text parts are dropped (no Responses-API
+ * non-text parts are produced by callers today).
+ */
+function flattenContentToString(
+  content: string | ResponsesApiContentPart[],
+): string {
+  if (typeof content === "string") return content;
+  return content.map((p) => p.text).join("");
+}
+
+/** Responses-API `developer` role maps to Chat Completions `system`. */
+function mapRoleToChatCompletion(
+  role: ResponsesApiInputMessage["role"],
+): "user" | "assistant" | "system" {
+  return role === "developer" ? "system" : role;
+}
+
 // ---------------------------------------------------------------------------
-// SSE Parser
+// SSE Parser (shared across both formats)
 // ---------------------------------------------------------------------------
 
-async function* parseSSEStream(
-  response: Response,
-): AsyncIterable<ResponsesApiStreamEvent> {
+interface RawSseEvent {
+  data: string;
+}
+
+async function* parseSSELines(response: Response): AsyncIterable<RawSseEvent> {
   const reader = response.body?.getReader();
   if (!reader) {
     throw new Error("Response body is not readable");
@@ -118,15 +160,8 @@ async function* parseSSEStream(
       for (const line of lines) {
         if (line.startsWith("data: ")) {
           const data = line.slice(6).trim();
-          if (data === "[DONE]") return;
           if (!data) continue;
-
-          try {
-            const event = JSON.parse(data) as ResponsesApiStreamEvent;
-            yield event;
-          } catch {
-            logger.debug({ data: data.slice(0, 100) }, "Failed to parse SSE event");
-          }
+          yield { data };
         }
       }
     }
@@ -135,6 +170,107 @@ async function* parseSSEStream(
   }
 }
 
+/** Parse Responses-API SSE: each `data:` is a JSON event object. */
+async function* parseResponsesStream(
+  response: Response,
+): AsyncIterable<ResponsesApiStreamEvent> {
+  for await (const { data } of parseSSELines(response)) {
+    if (data === "[DONE]") return;
+    try {
+      yield JSON.parse(data) as ResponsesApiStreamEvent;
+    } catch {
+      logger.debug({ data: data.slice(0, 100) }, "Failed to parse SSE event");
+    }
+  }
+}
+
+/**
+ * Parse Chat Completions SSE and translate text deltas into
+ * Responses-API event shape so consumers stay format-agnostic.
+ *
+ * For #574, only text deltas (`choices[].delta.content`) are
+ * translated — emitted as `response.output_text.delta`. Tool-call
+ * delta normalization is tracked in #608.
+ */
+async function* parseChatCompletionStream(
+  response: Response,
+): AsyncIterable<ResponsesApiStreamEvent> {
+  for await (const { data } of parseSSELines(response)) {
+    if (data === "[DONE]") return;
+    let chunk: {
+      choices?: Array<{
+        delta?: { content?: string | null };
+      }>;
+    };
+    try {
+      chunk = JSON.parse(data);
+    } catch {
+      logger.debug({ data: data.slice(0, 100) }, "Failed to parse chat-completion chunk");
+      continue;
+    }
+    const delta = chunk.choices?.[0]?.delta?.content;
+    if (typeof delta === "string" && delta.length > 0) {
+      yield { type: "response.output_text.delta", delta };
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Request body builders
+// ---------------------------------------------------------------------------
+
+function buildResponsesBody(
+  params: NyxLlmStreamParams | NyxLlmCompleteParams,
+  stream: boolean,
+): Record<string, unknown> {
+  const body: Record<string, unknown> = {
+    model: params.model,
+    input: params.input,
+    max_output_tokens: params.max_output_tokens ?? 8192,
+    temperature: params.temperature ?? 0.7,
+    stream,
+    store: false,
+  };
+  if (params.instructions) body.instructions = params.instructions;
+  if (params.tools && params.tools.length > 0) body.tools = params.tools;
+  return body;
+}
+
+function buildChatCompletionBody(
+  params: NyxLlmStreamParams | NyxLlmCompleteParams,
+  stream: boolean,
+): Record<string, unknown> {
+  const messages: Array<{ role: "user" | "assistant" | "system"; content: string }> = [];
+  if (params.instructions) {
+    messages.push({ role: "system", content: params.instructions });
+  }
+  for (const m of params.input) {
+    messages.push({
+      role: mapRoleToChatCompletion(m.role),
+      content: flattenContentToString(m.content),
+    });
+  }
+
+  const body: Record<string, unknown> = {
+    model: params.model,
+    messages,
+    max_tokens: params.max_output_tokens ?? 8192,
+    temperature: params.temperature ?? 0.7,
+    stream,
+  };
+  if (params.tools && params.tools.length > 0) {
+    body.tools = params.tools.map((t) => ({
+      type: "function" as const,
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+      },
+    }));
+  }
+  return body;
+}
+
 // ---------------------------------------------------------------------------
 // Client
 // ---------------------------------------------------------------------------
@@ -145,8 +281,8 @@ async function* parseSSEStream(
  * collection) so an admin's edit lands on the next call without a pod
  * restart. The resolver chooses the right provider for the surface
  * (playground vs skill-gen) and projects its `auth` discriminated
- * union into the simpler {gatewayUrl, apiKey?} shape this client
- * speaks.
+ * union into the simpler {gatewayUrl, apiKey?, apiFormat} shape this
+ * client speaks.
  *
  * - `gatewayUrl` is required (validated upstream when the admin saves
  *   the provider) — empty string means "no provider configured" and
@@ -155,19 +291,24 @@ async function* parseSSEStream(
  * - `apiKey` empty triggers the SA token-exchange path
  *   (`NyxidSaTokenProvider`). Most providers behind the NyxID proxy
  *   use SA flow; direct-key providers (third-party gateways) bypass it.
+ * - `apiFormat` selects the upstream endpoint + body shape (#574). Empty
+ *   gateway short-circuits before this matters; otherwise defaults to
+ *   `responses` for backward compatibility if the resolver omits it.
  */
 export interface LlmProviderResolution {
   gatewayUrl: string;
   apiKey: string;
+  apiFormat: ApiFormat;
 }
 
 export type LlmProviderResolver = () => Promise<LlmProviderResolution>;
 
 export interface NyxLlmClientConfig {
   /**
-   * Resolves the effective gateway URL + apiKey for every LLM call from
-   * admin settings. NO env fallback: if the resolver returns an empty
-   * `gatewayUrl`, the call fails-closed with `LLM_PROVIDER_NOT_CONFIGURED`.
+   * Resolves the effective gateway URL + apiKey + apiFormat for every
+   * LLM call from admin settings. NO env fallback: if the resolver
+   * returns an empty `gatewayUrl`, the call fails-closed with
+   * `LLM_PROVIDER_NOT_CONFIGURED`.
    */
   resolver: LlmProviderResolver;
   /**
@@ -190,9 +331,9 @@ export class NyxLlmClient {
   }
 
   /**
-   * Resolve the effective gateway URL + auth header for the current
-   * call. Pulls the provider config from settings; SA token is fetched
-   * on demand when the provider has no direct apiKey.
+   * Resolve the effective gateway URL + auth header + apiFormat for the
+   * current call. Pulls the provider config from settings; SA token is
+   * fetched on demand when the provider has no direct apiKey.
    *
    * Fails-closed when no provider is configured — callers see a
    * structured error rather than a stale env URL.
@@ -200,46 +341,41 @@ export class NyxLlmClient {
   private async resolveCallTarget(): Promise<{
     gatewayUrl: string;
     authHeader: string;
+    apiFormat: ApiFormat;
   }> {
     const provider = await this.resolver();
     const gatewayUrl = provider.gatewayUrl?.trim().replace(/\/+$/, "");
     if (!gatewayUrl) {
       throw new Error("LLM_PROVIDER_NOT_CONFIGURED: no gatewayUrl in settings");
     }
+    const apiFormat: ApiFormat = provider.apiFormat ?? "responses";
 
     if (provider.apiKey && provider.apiKey.trim().length > 0) {
-      return { gatewayUrl, authHeader: `Bearer ${provider.apiKey.trim()}` };
+      return { gatewayUrl, authHeader: `Bearer ${provider.apiKey.trim()}`, apiFormat };
     }
 
     const token = await this.saTokenProvider.getAccessToken();
-    return { gatewayUrl, authHeader: `Bearer ${token}` };
+    return { gatewayUrl, authHeader: `Bearer ${token}`, apiFormat };
   }
 
   /**
-   * Streaming LLM call using Responses API format.
-   * Returns an AsyncIterable of SSE events.
+   * Streaming LLM call. Returns an AsyncIterable of Responses-API
+   * shaped SSE events regardless of upstream format.
    */
   async *stream(params: NyxLlmStreamParams): AsyncIterable<ResponsesApiStreamEvent> {
-    const { gatewayUrl, authHeader } = await this.resolveCallTarget();
-    logger.info({ model: params.model, gatewayUrl }, "Starting LLM stream request");
-
-    const body: Record<string, unknown> = {
-      model: params.model,
-      input: params.input,
-      max_output_tokens: params.max_output_tokens ?? 8192,
-      temperature: params.temperature ?? 0.7,
-      stream: true,
-      store: false,
-    };
-
-    if (params.instructions) {
-      body.instructions = params.instructions;
-    }
-    if (params.tools && params.tools.length > 0) {
-      body.tools = params.tools;
-    }
-
-    const response = await fetch(`${gatewayUrl}/responses`, {
+    const { gatewayUrl, authHeader, apiFormat } = await this.resolveCallTarget();
+    logger.info(
+      { model: params.model, gatewayUrl, apiFormat },
+      "Starting LLM stream request",
+    );
+
+    const path = apiFormat === "chat-completion" ? "/chat/completions" : "/responses";
+    const body =
+      apiFormat === "chat-completion"
+        ? buildChatCompletionBody(params, true)
+        : buildResponsesBody(params, true);
+
+    const response = await fetch(`${gatewayUrl}${path}`, {
       method: "POST",
       headers: {
         "Authorization": authHeader,
@@ -251,43 +387,44 @@ export class NyxLlmClient {
     if (!response.ok) {
       const rawText = await response.text().catch(() => "");
       const message = sanitizeErrorResponse(response.status, rawText);
-      logger.error({ status: response.status, model: params.model }, message);
+      logger.error({ status: response.status, model: params.model, apiFormat }, message);
       throw new Error(message);
     }
 
+    const parser =
+      apiFormat === "chat-completion"
+        ? parseChatCompletionStream(response)
+        : parseResponsesStream(response);
+
     let eventCount = 0;
-    for await (const event of parseSSEStream(response)) {
+    for await (const event of parser) {
       eventCount++;
       yield event;
     }
-    logger.info({ totalEvents: eventCount, model: params.model }, "LLM stream completed");
+    logger.info(
+      { totalEvents: eventCount, model: params.model, apiFormat },
+      "LLM stream completed",
+    );
   }
 
   /**
-   * Non-streaming LLM call using Responses API format.
-   * Returns the output array from the response.
+   * Non-streaming LLM call. Returns Responses-API `ResponsesApiOutput[]`
+   * regardless of upstream format.
    */
   async complete(params: NyxLlmCompleteParams): Promise<ResponsesApiOutput[]> {
-    const { gatewayUrl, authHeader } = await this.resolveCallTarget();
-    logger.info({ model: params.model, gatewayUrl }, "Starting LLM complete request");
-
-    const body: Record<string, unknown> = {
-      model: params.model,
-      input: params.input,
-      max_output_tokens: params.max_output_tokens ?? 8192,
-      temperature: params.temperature ?? 0.7,
-      stream: false,
-      store: false,
-    };
-
-    if (params.instructions) {
-      body.instructions = params.instructions;
-    }
-    if (params.tools && params.tools.length > 0) {
-      body.tools = params.tools;
-    }
-
-    const response = await fetch(`${gatewayUrl}/responses`, {
+    const { gatewayUrl, authHeader, apiFormat } = await this.resolveCallTarget();
+    logger.info(
+      { model: params.model, gatewayUrl, apiFormat },
+      "Starting LLM complete request",
+    );
+
+    const path = apiFormat === "chat-completion" ? "/chat/completions" : "/responses";
+    const body =
+      apiFormat === "chat-completion"
+        ? buildChatCompletionBody(params, false)
+        : buildResponsesBody(params, false);
+
+    const response = await fetch(`${gatewayUrl}${path}`, {
       method: "POST",
       headers: {
         "Authorization": authHeader,
@@ -299,10 +436,20 @@ export class NyxLlmClient {
     if (!response.ok) {
       const rawText = await response.text().catch(() => "");
       const message = sanitizeErrorResponse(response.status, rawText);
-      logger.error({ status: response.status, model: params.model }, message);
+      logger.error({ status: response.status, model: params.model, apiFormat }, message);
       throw new Error(message);
     }
 
+    if (apiFormat === "chat-completion") {
+      const result = (await response.json()) as {
+        choices?: Array<{ message?: { content?: string | null } }>;
+      };
+      const text = result.choices?.[0]?.message?.content ?? "";
+      return text
+        ? [{ type: "message", content: [{ type: "output_text", text }] }]
+        : [];
+    }
+
     const result = (await response.json()) as { output: ResponsesApiOutput[] };
     return result.output ?? [];
   }
diff --git a/ornn-api/src/clients/nyxid/llmCatalog.ts b/ornn-api/src/clients/nyxid/llmCatalog.ts
index 70decaa8..665b3159 100644
--- a/ornn-api/src/clients/nyxid/llmCatalog.ts
+++ b/ornn-api/src/clients/nyxid/llmCatalog.ts
@@ -16,10 +16,10 @@
  * @module clients/nyxid/llmCatalog
  */
 
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import type { NyxidConfigResolver, NyxidSaTokenProvider } from "./base";
 
-const logger = pino({ level: "info" }).child({ module: "nyxLlmCatalogClient" });
+const logger = createLogger("nyxLlmCatalogClient");
 
 export interface UpstreamModel {
   /** Upstream `id`, e.g. `gpt-5-mini`. */
diff --git a/ornn-api/src/clients/nyxid/orgs.ts b/ornn-api/src/clients/nyxid/orgs.ts
index 45bb14c9..6ab914dd 100644
--- a/ornn-api/src/clients/nyxid/orgs.ts
+++ b/ornn-api/src/clients/nyxid/orgs.ts
@@ -11,10 +11,10 @@
  * @module clients/nyxid/orgs
  */
 
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import type { NyxidConfigResolver, NyxidSaTokenProvider } from "./base";
 
-const logger = pino({ level: "info" }).child({ module: "nyxidOrgsClient" });
+const logger = createLogger("nyxidOrgsClient");
 
 /**
  * Membership record Ornn cares about. Mirrors the subset of NyxID's
@@ -47,7 +47,9 @@ interface RawResponse {
 
 export class NyxidOrgsClient {
   private readonly resolver: NyxidConfigResolver;
-  private readonly saTokenProvider?: NyxidSaTokenProvider;
+  // exactOptionalPropertyTypes (#657): widen to `T | undefined` so the
+  // optional-from-deps assignment lands cleanly. Same runtime shape.
+  private readonly saTokenProvider: NyxidSaTokenProvider | undefined;
 
   constructor(opts: {
     resolver: NyxidConfigResolver;
diff --git a/ornn-api/src/clients/nyxid/service.test.ts b/ornn-api/src/clients/nyxid/service.test.ts
new file mode 100644
index 00000000..bbf55c21
--- /dev/null
+++ b/ornn-api/src/clients/nyxid/service.test.ts
@@ -0,0 +1,136 @@
+/**
+ * Tests for #715: deactivated NyxID services must not be exposed as
+ * usable system services. `NyxidServiceClient.listServicesForCaller`
+ * already drops `is_active: false` rows on a per-caller view; the new
+ * `listActiveServiceIdsAsPlatform` adds the platform-wide active set
+ * that anonymous-friendly aggregators (skill-facets/system-services)
+ * cross-check against.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { NyxidServiceClient } from "./service";
+
+interface CapturedRequest {
+  url: string;
+  authorization: string;
+}
+
+const originalFetch = globalThis.fetch;
+let captured: CapturedRequest[];
+let fetchHandler: () => Promise<Response> | Response;
+
+beforeEach(() => {
+  captured = [];
+  fetchHandler = () => new Response("no handler", { status: 500 });
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+    const headers = init?.headers as Record<string, string> | undefined;
+    captured.push({ url, authorization: headers?.Authorization ?? "" });
+    return fetchHandler();
+  }) as typeof fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+function makeClient(): NyxidServiceClient {
+  return new NyxidServiceClient({
+    resolver: async () => ({
+      baseApiUrl: "https://nyxid.example.com",
+      tokenBaseUrl: "https://nyxid.example.com",
+      audience: "test",
+      clientId: "c",
+      clientSecret: "s",
+    } as never),
+  });
+}
+
+function jsonResponse(payload: unknown, status = 200): Response {
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("NyxidServiceClient.listServicesForCaller — already drops is_active=false", () => {
+  it("filters inactive services from the per-caller projection (#715 defence-in-depth)", async () => {
+    fetchHandler = () =>
+      jsonResponse({
+        services: [
+          { id: "svc-active", slug: "active", name: "Active", visibility: "public", is_active: true, created_by: "u" },
+          { id: "svc-dead", slug: "dead", name: "Dead", visibility: "public", is_active: false, created_by: "u" },
+        ],
+      });
+
+    const out = await makeClient().listServicesForCaller("user-token");
+    expect(out.map((s) => s.id)).toEqual(["svc-active"]);
+  });
+
+  it("defaults missing is_active to active (preserves legacy NyxID responses)", async () => {
+    fetchHandler = () =>
+      jsonResponse({
+        services: [{ id: "svc-x", slug: "x", visibility: "public", created_by: "u" }],
+      });
+    const out = await makeClient().listServicesForCaller("user-token");
+    expect(out).toHaveLength(1);
+    expect(out[0]!.isActive).toBe(true);
+  });
+});
+
+describe("NyxidServiceClient.listActiveServiceIdsAsPlatform (#715)", () => {
+  it("returns a Set of active service ids using the SA token", async () => {
+    fetchHandler = () =>
+      jsonResponse({
+        services: [
+          { id: "svc-1", slug: "a", visibility: "public", is_active: true, created_by: "u" },
+          { id: "svc-2", slug: "b", visibility: "public", is_active: false, created_by: "u" },
+          { id: "svc-3", slug: "c", visibility: "private", is_active: true, created_by: "u" },
+        ],
+      });
+
+    const ids = await makeClient().listActiveServiceIdsAsPlatform("sa-token-xyz");
+    expect(ids).toBeInstanceOf(Set);
+    expect([...(ids ?? [])].sort()).toEqual(["svc-1", "svc-3"]);
+    expect(captured).toHaveLength(1);
+    expect(captured[0]!.url).toBe("https://nyxid.example.com/api/v1/services");
+    expect(captured[0]!.authorization).toBe("Bearer sa-token-xyz");
+  });
+
+  it("caches across calls — single upstream fetch within TTL", async () => {
+    fetchHandler = () => jsonResponse({ services: [{ id: "svc-1", slug: "a", is_active: true }] });
+    const client = makeClient();
+    await client.listActiveServiceIdsAsPlatform("sa-token");
+    await client.listActiveServiceIdsAsPlatform("sa-token");
+    expect(captured).toHaveLength(1);
+  });
+
+  it("fail-soft → returns null on non-2xx (caller skips filtering)", async () => {
+    fetchHandler = () => new Response("upstream is down", { status: 503 });
+    const ids = await makeClient().listActiveServiceIdsAsPlatform("sa-token");
+    expect(ids).toBeNull();
+  });
+
+  it("fail-soft → returns null on network throw", async () => {
+    fetchHandler = () => Promise.reject(new Error("ECONNRESET"));
+    const ids = await makeClient().listActiveServiceIdsAsPlatform("sa-token");
+    expect(ids).toBeNull();
+  });
+
+  it("returns null when SA token is empty (won't make an unauth call)", async () => {
+    const client = makeClient();
+    const ids = await client.listActiveServiceIdsAsPlatform("");
+    expect(ids).toBeNull();
+    expect(captured).toHaveLength(0);
+  });
+
+  it("invalidateCache() drops the platform cache so the next call re-fetches", async () => {
+    fetchHandler = () => jsonResponse({ services: [{ id: "svc-1", slug: "a", is_active: true }] });
+    const client = makeClient();
+    await client.listActiveServiceIdsAsPlatform("sa-token");
+    expect(captured).toHaveLength(1);
+    client.invalidateCache();
+    await client.listActiveServiceIdsAsPlatform("sa-token");
+    expect(captured).toHaveLength(2);
+  });
+});
diff --git a/ornn-api/src/clients/nyxid/service.ts b/ornn-api/src/clients/nyxid/service.ts
index 0c71c519..2404fc2c 100644
--- a/ornn-api/src/clients/nyxid/service.ts
+++ b/ornn-api/src/clients/nyxid/service.ts
@@ -13,10 +13,10 @@
  * @module clients/nyxid/service
  */
 
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import type { NyxidConfigResolver } from "./base";
 
-const logger = pino({ level: "info" }).child({ module: "nyxidServiceClient" });
+const logger = createLogger("nyxidServiceClient");
 
 /**
  * Catalog service shape Ornn cares about. Mirrors a small subset of
@@ -55,15 +55,25 @@ export class NyxidServiceClient {
   private readonly resolver: NyxidConfigResolver;
   /**
    * Per-user-token cache. Keyed by the bearer token so two callers don't
-   * leak each other's view. 60-second TTL — services don't change often,
-   * but we don't want to hold an admin's view stale for 5 minutes when
-   * they just toggled visibility.
+   * leak each other's view. Short TTL: when an admin deactivates a
+   * service in NyxID we want Ornn surfaces to drop it promptly (#715).
+   * Pre-#715 this was 60s, which left a window where Ornn still
+   * advertised a service NyxID had deactivated; 10s is the new ceiling.
    */
   private readonly cache = new Map<
     string,
     { services: NyxidCatalogService[]; expiresAt: number }
   >();
-  private readonly cacheTtlMs = 60 * 1000;
+  private readonly cacheTtlMs = 10 * 1000;
+
+  /**
+   * Dedicated cache for the platform-wide active-service id set
+   * resolved via the SA token (`listActiveServiceIdsAsPlatform`). The
+   * SA view is identical for every caller, so one cache slot is
+   * enough — separate from the per-caller `cache` above to avoid
+   * cross-contaminating visibility scopes.
+   */
+  private platformActiveCache: { ids: Set<string>; expiresAt: number } | null = null;
 
   constructor(opts: { resolver: NyxidConfigResolver }) {
     this.resolver = opts.resolver;
@@ -152,5 +162,60 @@ export class NyxidServiceClient {
   invalidateCache(userAccessToken?: string): void {
     if (userAccessToken) this.cache.delete(userAccessToken);
     else this.cache.clear();
+    this.platformActiveCache = null;
+  }
+
+  /**
+   * Resolve the platform-wide set of *active* NyxID service ids using
+   * an SA token (NyxID admin view → every service, before filtering).
+   * Used by Ornn surfaces that need to know "is this service still
+   * usable" independent of the calling user — most importantly the
+   * anonymous-friendly `/skill-facets/system-services` aggregator,
+   * which would otherwise advertise services NyxID has deactivated
+   * (#715).
+   *
+   * Errors fail-soft: when NyxID is unreachable we return `null` so
+   * callers can decide whether to skip the filter (preserve current
+   * behaviour) or fail-closed. Cached for 10s to keep the hot path
+   * cheap without prolonging the visibility lag after a deactivation.
+   */
+  async listActiveServiceIdsAsPlatform(saToken: string): Promise<Set<string> | null> {
+    if (!saToken) return null;
+    const now = Date.now();
+    if (this.platformActiveCache && this.platformActiveCache.expiresAt > now) {
+      return this.platformActiveCache.ids;
+    }
+    try {
+      const baseUrl = await this.resolveBaseUrl();
+      const resp = await fetch(`${baseUrl}/api/v1/services`, {
+        headers: { Authorization: `Bearer ${saToken}` },
+      });
+      if (!resp.ok) {
+        const body = await resp.text().catch(() => "");
+        logger.warn(
+          { status: resp.status, body: body.slice(0, 200) },
+          "NyxID /services SA fetch failed; returning null (no filter)",
+        );
+        return null;
+      }
+      const json = (await resp.json()) as RawListResponse | RawCatalogService[];
+      const raw: RawCatalogService[] = Array.isArray(json)
+        ? json
+        : json.services ?? json.items ?? [];
+      const ids = new Set<string>();
+      for (const r of raw) {
+        if (!r.id) continue;
+        if (r.is_active === false) continue;
+        ids.add(r.id);
+      }
+      this.platformActiveCache = { ids, expiresAt: now + this.cacheTtlMs };
+      return ids;
+    } catch (err) {
+      logger.warn(
+        { err: (err as Error).message },
+        "NyxID /services SA fetch threw; returning null (no filter)",
+      );
+      return null;
+    }
   }
 }
diff --git a/ornn-api/src/clients/nyxid/userServices.ts b/ornn-api/src/clients/nyxid/userServices.ts
index 32ada2e8..9f5f1078 100644
--- a/ornn-api/src/clients/nyxid/userServices.ts
+++ b/ornn-api/src/clients/nyxid/userServices.ts
@@ -20,10 +20,10 @@
  * @module clients/nyxid/userServices
  */
 
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import type { NyxidConfigResolver } from "./base";
 
-const logger = pino({ level: "info" }).child({ module: "nyxidUserServicesClient" });
+const logger = createLogger("nyxidUserServicesClient");
 
 /**
  * Minimal per-user service shape Ornn cares about. Mirrors the subset
diff --git a/ornn-api/src/clients/sandboxClient.ts b/ornn-api/src/clients/sandboxClient.ts
index 85f63a54..f1161f96 100644
--- a/ornn-api/src/clients/sandboxClient.ts
+++ b/ornn-api/src/clients/sandboxClient.ts
@@ -4,9 +4,8 @@
  * @module clients/sandboxClient
  */
 
-import pino from "pino";
-
-const logger = pino({ level: "info" }).child({ module: "sandboxClient" });
+import { createLogger } from "../shared/logger";
+const logger = createLogger("sandboxClient");
 
 // ── Shared types ──────────────────────────────────────────────────────
 
@@ -129,7 +128,8 @@ export type SandboxClientConfigResolver = () => Promise<SandboxClientConfig>;
 
 export class SandboxClient {
   private readonly resolver: SandboxClientConfigResolver;
-  private readonly getAccessToken?: () => Promise<string>;
+  // exactOptionalPropertyTypes (#657): widen to `T | undefined`.
+  private readonly getAccessToken: (() => Promise<string>) | undefined;
 
   constructor(opts: {
     resolver: SandboxClientConfigResolver;
diff --git a/ornn-api/src/clients/storageClient.ts b/ornn-api/src/clients/storageClient.ts
index 7e3e09a5..43a205b4 100644
--- a/ornn-api/src/clients/storageClient.ts
+++ b/ornn-api/src/clients/storageClient.ts
@@ -4,9 +4,8 @@
  * @module clients/storageClient
  */
 
-import pino from "pino";
-
-const logger = pino({ level: "info" }).child({ module: "storageClient" });
+import { createLogger } from "../shared/logger";
+const logger = createLogger("storageClient");
 
 export interface IStorageClient {
   upload(bucket: string, key: string, data: Uint8Array, contentType: string): Promise<{ url: string }>;
@@ -29,7 +28,8 @@ export type StorageClientConfigResolver = () => Promise<StorageClientConfig>;
 
 export class StorageClient implements IStorageClient {
   private readonly resolver: StorageClientConfigResolver;
-  private readonly getAccessToken?: () => Promise<string>;
+  // exactOptionalPropertyTypes (#657): widen to `T | undefined`.
+  private readonly getAccessToken: (() => Promise<string>) | undefined;
 
   constructor(opts: {
     resolver: StorageClientConfigResolver;
diff --git a/ornn-api/src/domains/admin-users/routes.ts b/ornn-api/src/domains/admin-users/routes.ts
index 2c18aa37..5f32c155 100644
--- a/ornn-api/src/domains/admin-users/routes.ts
+++ b/ornn-api/src/domains/admin-users/routes.ts
@@ -48,7 +48,7 @@ export function createAdminUsersRoutes(
     async (c) => {
       const roleParse = roleSchema.safeParse(c.req.query("role") ?? "normal");
       if (!roleParse.success) {
-        throw new AppError(400, "INVALID_ROLE", "role must be 'admin' or 'normal'");
+        throw new AppError(400, "invalid_role", "role must be 'admin' or 'normal'");
       }
       const role: Role = roleParse.data;
       const page = Math.max(1, Number(c.req.query("page")) || 1);
@@ -61,13 +61,16 @@ export function createAdminUsersRoutes(
       const dirRaw = c.req.query("dir");
       const dir: SortDir | undefined = dirRaw ? dirSchema.parse(dirRaw) : undefined;
 
+      // exactOptionalPropertyTypes (#657): conditional spread on the
+      // optional inputs so we don't pass `{ q: undefined }` to a
+      // contract that wants `q?: string`.
       const result = await adminUsersService.listUsers({
         role,
         page,
         pageSize,
-        q,
-        sort: sortKey,
-        dir,
+        ...(q !== undefined ? { q } : {}),
+        ...(sortKey !== undefined ? { sort: sortKey } : {}),
+        ...(dir !== undefined ? { dir } : {}),
       });
       return c.json({ data: result, error: null });
     },
diff --git a/ornn-api/src/domains/admin-users/service.test.ts b/ornn-api/src/domains/admin-users/service.test.ts
index c2dd8968..34b4d412 100644
--- a/ornn-api/src/domains/admin-users/service.test.ts
+++ b/ornn-api/src/domains/admin-users/service.test.ts
@@ -117,7 +117,7 @@ describe("search by email prefix", () => {
     await seedUser({ userId: "bob", email: "bob@example.com", displayName: "Bob" });
     const r = await service.listUsers({ role: "normal", page: 1, pageSize: 50, q: "ali" });
     expect(r.total).toBe(1);
-    expect(r.items[0].email).toBe("alice@example.com");
+    expect(r.items[0]!.email).toBe("alice@example.com");
   });
 });
 
@@ -147,8 +147,8 @@ describe("default sort lastActiveAt desc, nulls last", () => {
       lastSeenAt: new Date(Date.UTC(2026, 4, 1)),
     });
     const r = await service.listUsers({ role: "normal", page: 1, pageSize: 10 });
-    expect(r.items[0].userId).toBe("new");
-    expect(r.items[1].userId).toBe("old");
+    expect(r.items[0]!.userId).toBe("new");
+    expect(r.items[1]!.userId).toBe("old");
   });
 });
 
@@ -160,8 +160,8 @@ describe("lastActiveAt surfaces directory's lastSeenAt", () => {
       activityCount: 7,
     });
     const r = await service.listUsers({ role: "normal", page: 1, pageSize: 10 });
-    expect(r.items[0].lastActiveAt).toBe("2026-05-15T00:00:00.000Z");
-    expect(r.items[0].activityCount).toBe(7);
+    expect(r.items[0]!.lastActiveAt).toBe("2026-05-15T00:00:00.000Z");
+    expect(r.items[0]!.activityCount).toBe(7);
   });
 });
 
@@ -169,7 +169,7 @@ describe("skillCount = N owned", () => {
   test("createdBy match", async () => {
     await seedUser({ userId: "u1", skills: 4 });
     const r = await service.listUsers({ role: "normal", page: 1, pageSize: 10 });
-    expect(r.items[0].skillCount).toBe(4);
+    expect(r.items[0]!.skillCount).toBe(4);
   });
 });
 
@@ -180,6 +180,6 @@ describe("firstJoinedAt surfaces directory's firstSeenAt", () => {
       firstSeenAt: new Date(Date.UTC(2025, 11, 15)),
     });
     const r = await service.listUsers({ role: "normal", page: 1, pageSize: 10 });
-    expect(r.items[0].firstJoinedAt).toBe("2025-12-15T00:00:00.000Z");
+    expect(r.items[0]!.firstJoinedAt).toBe("2025-12-15T00:00:00.000Z");
   });
 });
diff --git a/ornn-api/src/domains/admin-users/service.ts b/ornn-api/src/domains/admin-users/service.ts
index e8ed0616..6d1af327 100644
--- a/ornn-api/src/domains/admin-users/service.ts
+++ b/ornn-api/src/domains/admin-users/service.ts
@@ -24,10 +24,10 @@
  */
 
 import type { Collection, Db } from "mongodb";
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import type { UserDirectoryRepository } from "../users/repository";
 
-const logger = pino({ level: "info" }).child({ module: "adminUsersService" });
+const logger = createLogger("adminUsersService");
 
 export type Role = "admin" | "normal";
 
diff --git a/ornn-api/src/domains/admin/bootstrap.ts b/ornn-api/src/domains/admin/bootstrap.ts
new file mode 100644
index 00000000..3a5a5f2c
--- /dev/null
+++ b/ornn-api/src/domains/admin/bootstrap.ts
@@ -0,0 +1,58 @@
+/**
+ * Wire the admin domain (#580 — bootstrap decomposition).
+ *
+ * Bundles the dashboard + users + quota admin surfaces. Each one needs
+ * the user directory repo + db handle; the quota admin route also
+ * needs the `QuotaService` so it can grant/revoke against current
+ * buckets. The three were originally inlined in bootstrap.ts back to
+ * back; this lifts them into a single wiring call that returns each
+ * route handler so the mount block stays unchanged.
+ *
+ * The standalone `createAdminRoutes` (skill + generation + agentseal
+ * admin) keeps living in bootstrap.ts — it depends on too many
+ * cross-cutting clients (skillRepo, skillService, skillVersionRepo,
+ * generationService, agentsealScanner) to fit cleanly here.
+ *
+ * @module domains/admin/bootstrap
+ */
+
+import type { Db } from "mongodb";
+import type { Hono } from "hono";
+import type { AuthVariables } from "../../middleware/nyxidAuth";
+import { AdminDashboardService } from "./dashboard/service";
+import { createAdminDashboardRoutes } from "./dashboard/routes";
+import { createAdminQuotaRoutes } from "./quota/routes";
+import { AdminUsersService } from "../admin-users/service";
+import { createAdminUsersRoutes } from "../admin-users/routes";
+import type { UserDirectoryRepository } from "../users/repository";
+import type { QuotaService } from "../quota/service";
+
+export interface AdminWiring {
+  readonly dashboardRoutes: Hono<{ Variables: AuthVariables }>;
+  readonly usersRoutes: Hono<{ Variables: AuthVariables }>;
+  readonly quotaRoutes: Hono<{ Variables: AuthVariables }>;
+}
+
+export function wireAdmin(deps: {
+  db: Db;
+  userDirectoryRepo: UserDirectoryRepository;
+  quotaService: QuotaService;
+}): AdminWiring {
+  const dashboardService = new AdminDashboardService({
+    db: deps.db,
+    userDirectoryRepo: deps.userDirectoryRepo,
+  });
+  const dashboardRoutes = createAdminDashboardRoutes({
+    dashboardService,
+  });
+  const usersService = new AdminUsersService({
+    db: deps.db,
+    userDirectoryRepo: deps.userDirectoryRepo,
+  });
+  const usersRoutes = createAdminUsersRoutes({ adminUsersService: usersService });
+  const quotaRoutes = createAdminQuotaRoutes({
+    quotaService: deps.quotaService,
+    userDirectoryRepo: deps.userDirectoryRepo,
+  });
+  return { dashboardRoutes, usersRoutes, quotaRoutes };
+}
diff --git a/ornn-api/src/domains/admin/dashboard/service.ts b/ornn-api/src/domains/admin/dashboard/service.ts
index ef5801af..113c412d 100644
--- a/ornn-api/src/domains/admin/dashboard/service.ts
+++ b/ornn-api/src/domains/admin/dashboard/service.ts
@@ -16,10 +16,10 @@
  */
 
 import type { Collection, Db } from "mongodb";
-import pino from "pino";
+import { createLogger } from "../../../shared/logger";
 import type { UserDirectoryRepository } from "../../users/repository";
 
-const logger = pino({ level: "info" }).child({ module: "adminDashboardService" });
+const logger = createLogger("adminDashboardService");
 
 export interface DashboardStats {
   users: { total: number; admin: number; normal: number };
diff --git a/ornn-api/src/domains/admin/quota/routes.test.ts b/ornn-api/src/domains/admin/quota/routes.test.ts
index d27ec1fa..968d3e9f 100644
--- a/ornn-api/src/domains/admin/quota/routes.test.ts
+++ b/ornn-api/src/domains/admin/quota/routes.test.ts
@@ -18,6 +18,7 @@ import { QuotaRepository } from "../../quota/repository";
 import { QuotaService } from "../../quota/service";
 import type { AuthVariables } from "../../../middleware/nyxidAuth";
 import { createAdminQuotaRoutes } from "./routes";
+import { buildProblemJsonBody } from "../../../shared/types/index";
 
 let mongo: MongoMemoryServer;
 let client: MongoClient;
@@ -62,16 +63,18 @@ beforeAll(async () => {
   });
   app.onError((err, c) => {
     const e = err as { statusCode?: number; code?: string; message: string };
-    if (e.statusCode && e.code) {
-      return c.json(
-        { data: null, error: { code: e.code, message: e.message } },
-        e.statusCode as never,
-      );
-    }
-    return c.json(
-      { data: null, error: { code: "INTERNAL", message: e.message } },
-      500,
-    );
+    const statusCode = e.statusCode ?? 500;
+    const code = e.code ?? "internal_error";
+    const body = buildProblemJsonBody({
+      statusCode,
+      code,
+      message: e.message ?? "",
+      instance: c.req.path,
+      requestId: null,
+    });
+    return c.json(body, statusCode as never, {
+      "Content-Type": "application/problem+json",
+    });
   });
   app.route("/", router);
 });
@@ -190,7 +193,7 @@ describe("UT-ADMQROUTE-001 GET /admin/quota/users surface=playground", () => {
       };
     };
     expect(json.data.items.length).toBe(1);
-    expect(json.data.items[0].userId).toBe("u1");
+    expect(json.data.items[0]!.userId).toBe("u1");
     expect(json.data.monthMarker).toMatch(/^\d{4}-\d{2}$/);
   });
 });
@@ -203,7 +206,7 @@ describe("UT-ADMQROUTE-002 surface=skillGen filter", () => {
     });
     expect(res.status).toBe(200);
     const json = (await res.json()) as { data: { items: Array<{ defaultAllotment: number }> } };
-    expect(json.data.items[0].defaultAllotment).toBe(10);
+    expect(json.data.items[0]!.defaultAllotment).toBe(10);
   });
 });
 
@@ -241,7 +244,7 @@ describe("UT-ADMQROUTE-006 remaining floors at 0", () => {
       headers: authHeaders(),
     });
     const json = (await res.json()) as { data: { items: Array<{ remaining: number }> } };
-    expect(json.data.items[0].remaining).toBe(0);
+    expect(json.data.items[0]!.remaining).toBe(0);
   });
 });
 
diff --git a/ornn-api/src/domains/admin/quota/routes.ts b/ornn-api/src/domains/admin/quota/routes.ts
index ce0e5730..f823bc3c 100644
--- a/ornn-api/src/domains/admin/quota/routes.ts
+++ b/ornn-api/src/domains/admin/quota/routes.ts
@@ -15,7 +15,7 @@
 
 import { Hono } from "hono";
 import { z } from "zod";
-import pino from "pino";
+import { createLogger } from "../../../shared/logger";
 import {
   type AuthVariables,
   getAuth,
@@ -32,7 +32,7 @@ import {
   monthBounds,
 } from "../../quota/types";
 
-const logger = pino({ level: "info" }).child({ module: "adminQuotaRoutes" });
+const logger = createLogger("adminQuotaRoutes");
 
 const surfaceSchema = z.enum(SURFACES);
 
@@ -71,7 +71,7 @@ export function createAdminQuotaRoutes(
       const surfaceParam = c.req.query("surface") ?? "playground";
       const parsedSurface = surfaceSchema.safeParse(surfaceParam);
       if (!parsedSurface.success) {
-        throw new AppError(400, "INVALID_SURFACE", "Invalid surface query parameter");
+        throw new AppError(400, "invalid_surface", "Invalid surface query parameter");
       }
       const surface = parsedSurface.data;
       const page = Math.max(1, Number(c.req.query("page")) || 1);
@@ -127,11 +127,11 @@ export function createAdminQuotaRoutes(
     requirePermission(QUOTA_ADMIN_PERMISSION),
     async (c) => {
       const userId = c.req.param("userId");
-      if (!userId) throw new AppError(400, "INVALID_USER_ID", "userId is required");
+      if (!userId) throw new AppError(400, "invalid_user_id", "userId is required");
       const surfaceParam = c.req.query("surface") ?? "playground";
       const parsedSurface = surfaceSchema.safeParse(surfaceParam);
       if (!parsedSurface.success) {
-        throw new AppError(400, "INVALID_SURFACE", "Invalid surface query parameter");
+        throw new AppError(400, "invalid_surface", "Invalid surface query parameter");
       }
       const surface = parsedSurface.data;
       const buckets = await quotaService.getLifetime(userId, surface);
@@ -168,7 +168,8 @@ export function createAdminQuotaRoutes(
           targetUserId: body.userId,
           surface: body.surface,
           amount: body.amount,
-          note: body.note,
+          // exactOptionalPropertyTypes (#657)
+          ...(body.note !== undefined ? { note: body.note } : {}),
         });
         logger.info(
           {
@@ -186,7 +187,7 @@ export function createAdminQuotaRoutes(
         });
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        throw new AppError(400, "INVALID_GRANT_AMOUNT", msg);
+        throw new AppError(400, "invalid_grant_amount", msg);
       }
     },
   );
@@ -210,7 +211,8 @@ export function createAdminQuotaRoutes(
         targetUserIds: unique,
         surface: body.surface,
         amount: body.amount,
-        note: body.note,
+        // exactOptionalPropertyTypes (#657)
+        ...(body.note !== undefined ? { note: body.note } : {}),
       });
       const applied = results.filter((r) => r.ok).length;
       const { monthMarker } = monthBounds(new Date());
@@ -244,8 +246,9 @@ export function createAdminQuotaRoutes(
       const result = await quotaService.listGrantAudit({
         page,
         pageSize,
-        targetUserId,
-        adminUserId,
+        // exactOptionalPropertyTypes (#657)
+        ...(targetUserId !== undefined ? { targetUserId } : {}),
+        ...(adminUserId !== undefined ? { adminUserId } : {}),
       });
       return c.json({
         data: {
diff --git a/ornn-api/src/domains/admin/redemption-codes/routes.test.ts b/ornn-api/src/domains/admin/redemption-codes/routes.test.ts
index 1c861c96..c5e58931 100644
--- a/ornn-api/src/domains/admin/redemption-codes/routes.test.ts
+++ b/ornn-api/src/domains/admin/redemption-codes/routes.test.ts
@@ -17,6 +17,7 @@ import { QuotaService } from "../../quota/service";
 import { RedemptionCodeRepository } from "../../redemption-codes/repository";
 import { RedemptionCodeService } from "../../redemption-codes/service";
 import type { AuthVariables } from "../../../middleware/nyxidAuth";
+import { buildProblemJsonBody } from "../../../shared/types/index";
 import { createAdminRedemptionCodesRoutes } from "./routes";
 
 let mongo: MongoMemoryServer;
@@ -64,16 +65,18 @@ beforeAll(async () => {
   });
   app.onError((err, c) => {
     const e = err as { statusCode?: number; code?: string; message: string };
-    if (e.statusCode && e.code) {
-      return c.json(
-        { data: null, error: { code: e.code, message: e.message } },
-        e.statusCode as never,
-      );
-    }
-    return c.json(
-      { data: null, error: { code: "INTERNAL", message: e.message } },
-      500,
-    );
+    const statusCode = e.statusCode ?? 500;
+    const code = e.code ?? "internal_error";
+    const body = buildProblemJsonBody({
+      statusCode,
+      code,
+      message: e.message ?? "",
+      instance: c.req.path,
+      requestId: null,
+    });
+    return c.json(body, statusCode as never, {
+      "Content-Type": "application/problem+json",
+    });
   });
   app.route("/", router);
 });
@@ -174,8 +177,8 @@ describe("POST /admin/redemption-codes/:id/invalidate", () => {
       { method: "POST", headers: authHeaders() },
     );
     expect(res.status).toBe(409);
-    const json = (await res.json()) as { error: { code: string } };
-    expect(json.error.code).toBe("REDEMPTION_CODE_ALREADY_REDEEMED");
+    const json = (await res.json()) as { code: string; detail: string; status: number };
+    expect(json.code).toBe("redemption_code_already_redeemed");
   });
 
   test("on already-invalidated → 409 ALREADY_INVALIDATED", async () => {
@@ -193,8 +196,8 @@ describe("POST /admin/redemption-codes/:id/invalidate", () => {
       { method: "POST", headers: authHeaders() },
     );
     expect(res.status).toBe(409);
-    const json = (await res.json()) as { error: { code: string } };
-    expect(json.error.code).toBe("REDEMPTION_CODE_ALREADY_INVALIDATED");
+    const json = (await res.json()) as { code: string; detail: string; status: number };
+    expect(json.code).toBe("redemption_code_already_invalidated");
   });
 
   test("unknown id → 404", async () => {
diff --git a/ornn-api/src/domains/admin/redemption-codes/routes.ts b/ornn-api/src/domains/admin/redemption-codes/routes.ts
index 23fa2079..69e12301 100644
--- a/ornn-api/src/domains/admin/redemption-codes/routes.ts
+++ b/ornn-api/src/domains/admin/redemption-codes/routes.ts
@@ -13,7 +13,7 @@
  */
 
 import { Hono } from "hono";
-import pino from "pino";
+import { createLogger } from "../../../shared/logger";
 import {
   type AuthVariables,
   getAuth,
@@ -32,7 +32,7 @@ import {
   type RedemptionCodeStatus,
 } from "../../redemption-codes/types";
 
-const logger = pino({ level: "info" }).child({ module: "adminRedemptionCodeRoutes" });
+const logger = createLogger("adminRedemptionCodeRoutes");
 
 const PAGE_SIZE_MAX = 100;
 const PAGE_SIZE_DEFAULT = 20;
@@ -64,23 +64,23 @@ function serializeCode(doc: RedemptionCodeDoc): Record<string, unknown> {
 
 function mapInvalidateError(message: string): AppError {
   if (message.startsWith("NOT_FOUND:")) {
-    return new AppError(404, "REDEMPTION_CODE_NOT_FOUND", "Redemption code not found");
+    return new AppError(404, "redemption_code_not_found", "Redemption code not found");
   }
   if (message.startsWith("ALREADY_REDEEMED:")) {
     return new AppError(
       409,
-      "REDEMPTION_CODE_ALREADY_REDEEMED",
+      "redemption_code_already_redeemed",
       "Redeemed codes cannot be invalidated",
     );
   }
   if (message.startsWith("ALREADY_INVALIDATED:")) {
     return new AppError(
       409,
-      "REDEMPTION_CODE_ALREADY_INVALIDATED",
+      "redemption_code_already_invalidated",
       "Code is already invalidated",
     );
   }
-  return AppError.internalError("REDEMPTION_CODE_INVALIDATE_FAILED", message);
+  return AppError.internalError("redemption_code_invalidate_failed", message);
 }
 
 export function createAdminRedemptionCodesRoutes(
@@ -95,7 +95,7 @@ export function createAdminRedemptionCodesRoutes(
     "/admin/redemption-codes",
     auth,
     requirePermission(QUOTA_ADMIN_PERMISSION),
-    validateBody(mintCodeSchema, "INVALID_REDEMPTION_CODE_BODY"),
+    validateBody(mintCodeSchema, "invalid_redemption_code_body"),
     async (c) => {
       const authCtx = getAuth(c);
       const body = getValidatedBody<MintCodeInput>(c);
@@ -107,7 +107,8 @@ export function createAdminRedemptionCodesRoutes(
             displayName: authCtx.displayName,
           },
           grants: body.grants,
-          note: body.note,
+          // exactOptionalPropertyTypes (#657)
+          ...(body.note !== undefined ? { note: body.note } : {}),
           expiresAt: new Date(body.expiresAt),
         });
         logger.info(
@@ -123,9 +124,9 @@ export function createAdminRedemptionCodesRoutes(
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         if (msg.startsWith("INVALID_GRANTS:") || msg.startsWith("INVALID_EXPIRES_AT:")) {
-          throw AppError.badRequest("INVALID_REDEMPTION_CODE_BODY", msg);
+          throw AppError.badRequest("invalid_redemption_code_body", msg);
         }
-        throw AppError.internalError("REDEMPTION_CODE_MINT_FAILED", msg);
+        throw AppError.internalError("redemption_code_mint_failed", msg);
       }
     },
   );
@@ -153,7 +154,13 @@ export function createAdminRedemptionCodesRoutes(
         PAGE_SIZE_MAX,
         Math.max(1, Number(c.req.query("pageSize")) || PAGE_SIZE_DEFAULT),
       );
-      const result = await redemptionCodeService.list({ page, pageSize, status, search });
+      const result = await redemptionCodeService.list({
+        page,
+        pageSize,
+        // exactOptionalPropertyTypes (#657)
+        ...(status !== undefined ? { status } : {}),
+        ...(search !== undefined ? { search } : {}),
+      });
       return c.json({
         data: {
           items: result.items.map(serializeCode),
@@ -175,11 +182,11 @@ export function createAdminRedemptionCodesRoutes(
     async (c) => {
       const id = c.req.param("id");
       if (!id) {
-        throw AppError.badRequest("INVALID_REDEMPTION_CODE_ID", "id is required");
+        throw AppError.badRequest("invalid_redemption_code_id", "id is required");
       }
       const doc = await redemptionCodeService.findById(id);
       if (!doc) {
-        throw new AppError(404, "REDEMPTION_CODE_NOT_FOUND", "Redemption code not found");
+        throw new AppError(404, "redemption_code_not_found", "Redemption code not found");
       }
       return c.json({ data: { code: serializeCode(doc) }, error: null });
     },
@@ -194,7 +201,7 @@ export function createAdminRedemptionCodesRoutes(
       const authCtx = getAuth(c);
       const id = c.req.param("id");
       if (!id) {
-        throw AppError.badRequest("INVALID_REDEMPTION_CODE_ID", "id is required");
+        throw AppError.badRequest("invalid_redemption_code_id", "id is required");
       }
       try {
         const doc = await redemptionCodeService.invalidate({
diff --git a/ornn-api/src/domains/admin/routes.ts b/ornn-api/src/domains/admin/routes.ts
index ceb8e752..048664d9 100644
--- a/ornn-api/src/domains/admin/routes.ts
+++ b/ornn-api/src/domains/admin/routes.ts
@@ -26,9 +26,8 @@ import {
   requirePermission,
   getAuth,
 } from "../../middleware/nyxidAuth";
-import pino from "pino";
-
-const logger = pino({ level: "info" }).child({ module: "adminRoutes" });
+import { createLogger } from "../../shared/logger";
+const logger = createLogger("adminRoutes");
 
 export interface AdminRoutesConfig {
   /** PostHog emitter for skill-delete + agentseal-rescan activity events. */
@@ -101,13 +100,21 @@ export function createAdminRoutes(config: AdminRoutesConfig): Hono<{ Variables:
         ];
       }
 
-      const total = await skillCollection.countDocuments(filter);
+      // 5-second server-side wall clock (#446) — even with regex
+      // escaping, an unanchored partial-match on a large collection
+      // could pin a Mongo node's CPU. Better to return 500 than to
+      // hold a connection indefinitely.
+      const MAX_QUERY_MS = 5_000;
+      const total = await skillCollection.countDocuments(filter, {
+        maxTimeMS: MAX_QUERY_MS,
+      });
       const offset = (page - 1) * pageSize;
       const docs = await skillCollection
         .find(filter)
         .sort({ createdOn: -1 })
         .skip(offset)
         .limit(pageSize)
+        .maxTimeMS(MAX_QUERY_MS)
         .toArray();
 
       const items = docs.map((d) => ({
@@ -193,7 +200,7 @@ export function createAdminRoutes(config: AdminRoutesConfig): Hono<{ Variables:
           {
             data: null,
             error: {
-              code: "AGENTSEAL_DISABLED",
+              code: "agentseal_disabled",
               message: "AgentSeal scanner is not configured on this deployment",
             },
           },
diff --git a/ornn-api/src/domains/analytics/bootstrap.ts b/ornn-api/src/domains/analytics/bootstrap.ts
new file mode 100644
index 00000000..912f9cbf
--- /dev/null
+++ b/ornn-api/src/domains/analytics/bootstrap.ts
@@ -0,0 +1,44 @@
+/**
+ * Wire the analytics domain (#580 — bootstrap decomposition).
+ *
+ * Pure leaf wiring: repo (with fire-and-forget index ensure for both
+ * `skill_executions` + `skill_pulls` collections) → service → routes.
+ * Routes also need the skill-service reference to join skill metadata
+ * onto execution rows, so the caller passes it in.
+ *
+ * @module domains/analytics/bootstrap
+ */
+
+import type { Db } from "mongodb";
+import type { Hono } from "hono";
+import type { Logger } from "pino";
+import type { AuthVariables } from "../../middleware/nyxidAuth";
+import { AnalyticsRepository } from "./repository";
+import { AnalyticsService } from "./service";
+import { createAnalyticsRoutes } from "./routes";
+import type { SkillService } from "../skills/crud/service";
+
+export interface AnalyticsWiring {
+  readonly service: AnalyticsService;
+  readonly routes: Hono<{ Variables: AuthVariables }>;
+}
+
+export function wireAnalytics(deps: {
+  db: Db;
+  logger: Logger;
+  skillService: SkillService;
+}): AnalyticsWiring {
+  const repo = new AnalyticsRepository(deps.db);
+  void repo.ensureIndexes().catch((err) =>
+    deps.logger.warn(
+      { err },
+      "skill_executions indexes ensureIndexes failed — proceeding anyway",
+    ),
+  );
+  const service = new AnalyticsService({ analyticsRepo: repo });
+  const routes = createAnalyticsRoutes({
+    analyticsService: service,
+    skillService: deps.skillService,
+  });
+  return { service, routes };
+}
diff --git a/ornn-api/src/domains/analytics/repository.test.ts b/ornn-api/src/domains/analytics/repository.test.ts
new file mode 100644
index 00000000..b26b2ef2
--- /dev/null
+++ b/ornn-api/src/domains/analytics/repository.test.ts
@@ -0,0 +1,235 @@
+/**
+ * AnalyticsRepository unit tests (#454).
+ *
+ * Two collections: `skill_executions` (per-call events) and
+ * `skill_pulls` (per-download events). Repo is fire-and-forget on
+ * writes — never blocks a user's skill invocation. Reads aggregate
+ * over rolling windows.
+ *
+ * Covers happy path + at least one edge per public method.
+ *
+ * @module domains/analytics/repository.test
+ */
+
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+import { MongoClient, type Db } from "mongodb";
+import { MongoMemoryServer } from "mongodb-memory-server";
+import { AnalyticsRepository } from "./repository";
+
+let mongo: MongoMemoryServer;
+let client: MongoClient;
+let db: Db;
+let repo: AnalyticsRepository;
+
+beforeAll(async () => {
+  mongo = await MongoMemoryServer.create();
+  client = new MongoClient(mongo.getUri());
+  await client.connect();
+  db = client.db("analytics_test");
+  repo = new AnalyticsRepository(db);
+  await repo.ensureIndexes();
+});
+
+afterAll(async () => {
+  await client.close();
+  await mongo.stop();
+});
+
+beforeEach(async () => {
+  await db.collection("skill_executions").deleteMany({});
+  await db.collection("skill_pulls").deleteMany({});
+});
+
+describe("recordEvent", () => {
+  test("inserts an execution event", async () => {
+    await repo.recordEvent({
+      skillGuid: "s1",
+      skillName: "pdf-extract",
+      skillVersion: "1.0",
+      outcome: "success",
+      latencyMs: 123.7,
+      userId: "u1",
+      source: "playground",
+    });
+    const doc = await db.collection("skill_executions").findOne({ skillGuid: "s1" });
+    expect(doc?.skillName).toBe("pdf-extract");
+    expect(doc?.outcome).toBe("success");
+    // latencyMs is rounded to int
+    expect(doc?.latencyMs).toBe(124);
+    expect(doc?.createdAt).toBeInstanceOf(Date);
+  });
+
+  test("clamps negative latency to 0 (defensive)", async () => {
+    await repo.recordEvent({
+      skillGuid: "s1",
+      skillName: "x",
+      outcome: "success",
+      latencyMs: -50,
+      userId: "u1",
+      source: "playground",
+    });
+    const doc = await db.collection("skill_executions").findOne({ skillGuid: "s1" });
+    expect(doc?.latencyMs).toBe(0);
+  });
+});
+
+describe("recordPull", () => {
+  test("inserts a pull event into skill_pulls", async () => {
+    await repo.recordPull({
+      skillGuid: "s1",
+      skillName: "pdf-extract",
+      skillVersion: "1.0",
+      userId: "u1",
+      source: "api",
+    });
+    const doc = await db.collection("skill_pulls").findOne({ skillGuid: "s1" });
+    expect(doc?.skillName).toBe("pdf-extract");
+    expect(doc?.skillVersion).toBe("1.0");
+    expect(doc?.source).toBe("api");
+  });
+});
+
+describe("summarize", () => {
+  beforeEach(async () => {
+    // 3 successes + 1 failure + 1 timeout for skill s1
+    for (let i = 0; i < 3; i++) {
+      await repo.recordEvent({
+        skillGuid: "s1",
+        skillName: "x",
+        skillVersion: "1.0",
+        outcome: "success",
+        latencyMs: 100,
+        userId: `u${i}`,
+        source: "playground",
+      });
+    }
+    await repo.recordEvent({
+      skillGuid: "s1",
+      skillName: "x",
+      skillVersion: "1.0",
+      outcome: "failure",
+      latencyMs: 50,
+      userId: "u3",
+      source: "playground",
+      errorCode: "internal_error",
+    });
+    await repo.recordEvent({
+      skillGuid: "s1",
+      skillName: "x",
+      skillVersion: "1.0",
+      outcome: "timeout",
+      latencyMs: 30000,
+      userId: "u4",
+      source: "playground",
+    });
+    // Separate skill — must NOT bleed into s1's aggregate
+    await repo.recordEvent({
+      skillGuid: "s2",
+      skillName: "y",
+      outcome: "success",
+      latencyMs: 10,
+      userId: "u1",
+      source: "playground",
+    });
+  });
+
+  test("aggregates execution counts, success rate, unique users", async () => {
+    const summary = await repo.summarize("s1", "30d");
+    expect(summary.executionCount).toBe(5);
+    expect(summary.successCount).toBe(3);
+    expect(summary.failureCount).toBe(1);
+    expect(summary.timeoutCount).toBe(1);
+    // success rate = 3/5 = 0.6
+    expect(summary.successRate).toBeCloseTo(0.6, 2);
+    expect(summary.uniqueUsers).toBe(5);
+  });
+
+  test("optional version filter narrows the aggregate", async () => {
+    await repo.recordEvent({
+      skillGuid: "s1",
+      skillName: "x",
+      skillVersion: "2.0",
+      outcome: "success",
+      latencyMs: 1,
+      userId: "u9",
+      source: "playground",
+    });
+    // Pull all 6, then narrowed to v1.0 only (5)
+    const all = await repo.summarize("s1", "30d");
+    expect(all.executionCount).toBe(6);
+    const onlyV1 = await repo.summarize("s1", "30d", { version: "1.0" });
+    expect(onlyV1.executionCount).toBe(5);
+  });
+
+  test("returns zeros for a skill with no events", async () => {
+    const summary = await repo.summarize("does-not-exist", "30d");
+    expect(summary.executionCount).toBe(0);
+    expect(summary.successCount).toBe(0);
+    expect(summary.successRate).toBeNull();
+  });
+});
+
+describe("aggregatePullsByBucket", () => {
+  test("returns hourly buckets when bucket=hour", async () => {
+    for (let i = 0; i < 3; i++) {
+      await repo.recordPull({
+        skillGuid: "s1",
+        skillName: "x",
+        skillVersion: "1.0",
+        userId: `u${i}`,
+        source: "api",
+      });
+    }
+    const series = await repo.aggregatePullsByBucket({
+      skillGuid: "s1",
+      bucket: "hour",
+      // Default `to` is `new Date()` evaluated INSIDE the call, with
+      // `$lt: to` — just-inserted events at exactly that timestamp
+      // get excluded. Push the upper bound past any test-inserted
+      // createdAt.
+      to: new Date(Date.now() + 60_000),
+    });
+    const total = series.reduce((acc, b) => acc + b.total, 0);
+    expect(total).toBe(3);
+  });
+
+  test("filters by version when set", async () => {
+    await repo.recordPull({
+      skillGuid: "s1",
+      skillName: "x",
+      skillVersion: "1.0",
+      userId: "u1",
+      source: "api",
+    });
+    await repo.recordPull({
+      skillGuid: "s1",
+      skillName: "x",
+      skillVersion: "2.0",
+      userId: "u2",
+      source: "api",
+    });
+    const onlyV1 = await repo.aggregatePullsByBucket({
+      skillGuid: "s1",
+      bucket: "day",
+      version: "1.0",
+      to: new Date(Date.now() + 60_000),
+    });
+    const total = onlyV1.reduce((acc, b) => acc + b.total, 0);
+    expect(total).toBe(1);
+  });
+
+  test("returns empty series for a skill with no pulls", async () => {
+    const series = await repo.aggregatePullsByBucket({
+      skillGuid: "does-not-exist",
+      bucket: "day",
+    });
+    expect(series).toEqual([]);
+  });
+});
diff --git a/ornn-api/src/domains/analytics/repository.ts b/ornn-api/src/domains/analytics/repository.ts
index cd6420de..fcc090d6 100644
--- a/ornn-api/src/domains/analytics/repository.ts
+++ b/ornn-api/src/domains/analytics/repository.ts
@@ -9,7 +9,7 @@
 
 import { randomUUID } from "node:crypto";
 import type { Collection, Db, Document } from "mongodb";
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import type {
   ExecutionOutcome,
   PullBucket,
@@ -19,7 +19,7 @@ import type {
   SkillExecutionEvent,
 } from "./types";
 
-const logger = pino({ level: "info" }).child({ module: "analyticsRepository" });
+const logger = createLogger("analyticsRepository");
 
 export interface RecordEventInput {
   skillGuid: string;
@@ -200,7 +200,8 @@ export class AnalyticsRepository {
     return {
       skillGuid,
       window,
-      version,
+      // exactOptionalPropertyTypes (#657)
+      ...(version !== undefined ? { version } : {}),
       executionCount: counts.executionCount,
       successCount: counts.successCount,
       failureCount: counts.failureCount,
diff --git a/ornn-api/src/domains/analytics/routes.ts b/ornn-api/src/domains/analytics/routes.ts
index ae9f8e2a..8a5eaa43 100644
--- a/ornn-api/src/domains/analytics/routes.ts
+++ b/ornn-api/src/domains/analytics/routes.ts
@@ -49,7 +49,7 @@ export function createAnalyticsRoutes(
     const authCtx = c.get("auth");
     const skill = await skillService.getSkill(idOrName);
     if (!authCtx && skill.isPrivate) {
-      throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+      throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
     }
     if (authCtx && skill.isPrivate) {
       const memberships = await readUserOrgMemberships(c);
@@ -59,7 +59,7 @@ export function createAnalyticsRoutes(
         isPlatformAdmin: authCtx.permissions.includes("ornn:admin:skill"),
       };
       if (!canReadSkill(skill, actor)) {
-        throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+        throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
       }
     }
     return { skillGuid: skill.guid };
@@ -101,13 +101,13 @@ export function createAnalyticsRoutes(
       const from = fromQ ? new Date(fromQ) : undefined;
       const to = toQ ? new Date(toQ) : undefined;
       if (fromQ && from && Number.isNaN(from.getTime())) {
-        throw AppError.badRequest("INVALID_RANGE", "'from' is not a valid ISO date");
+        throw AppError.badRequest("invalid_range", "'from' is not a valid ISO date");
       }
       if (toQ && to && Number.isNaN(to.getTime())) {
-        throw AppError.badRequest("INVALID_RANGE", "'to' is not a valid ISO date");
+        throw AppError.badRequest("invalid_range", "'to' is not a valid ISO date");
       }
       if (from && to && from >= to) {
-        throw AppError.badRequest("INVALID_RANGE", "'from' must be earlier than 'to'");
+        throw AppError.badRequest("invalid_range", "'from' must be earlier than 'to'");
       }
       const versionParam = c.req.query("version") || undefined;
 
@@ -115,9 +115,10 @@ export function createAnalyticsRoutes(
       const buckets = await analyticsService.getPullsTimeSeries({
         skillGuid,
         bucket: bucketParam as PullBucket,
-        from,
-        to,
-        version: versionParam,
+        // exactOptionalPropertyTypes (#657)
+        ...(from !== undefined ? { from } : {}),
+        ...(to !== undefined ? { to } : {}),
+        ...(versionParam !== undefined ? { version: versionParam } : {}),
       });
       return c.json({ data: { items: buckets }, error: null });
     },
diff --git a/ornn-api/src/domains/analytics/service.ts b/ornn-api/src/domains/analytics/service.ts
index 659b5b2b..8862e0b7 100644
--- a/ornn-api/src/domains/analytics/service.ts
+++ b/ornn-api/src/domains/analytics/service.ts
@@ -46,7 +46,8 @@ export class AnalyticsService {
     window: "7d" | "30d" | "all" = "30d",
     version?: string,
   ): Promise<SkillAnalyticsSummary> {
-    return this.repo.summarize(skillGuid, window, { version });
+    // exactOptionalPropertyTypes (#657)
+    return this.repo.summarize(skillGuid, window, version !== undefined ? { version } : {});
   }
 
   async getPullsTimeSeries(
diff --git a/ornn-api/src/domains/announcements/bootstrap.ts b/ornn-api/src/domains/announcements/bootstrap.ts
new file mode 100644
index 00000000..c471f472
--- /dev/null
+++ b/ornn-api/src/domains/announcements/bootstrap.ts
@@ -0,0 +1,60 @@
+/**
+ * Wire the announcements domain (#580 — bootstrap decomposition).
+ *
+ * Pure leaf wiring: repo → ensureIndexes (fire-and-forget) → one-shot
+ * bilingual backfill migration → service → routes. The boot caller
+ * stays in charge of ordering — this function just bundles the per-
+ * domain construction detail.
+ *
+ * @module domains/announcements/bootstrap
+ */
+
+import type { Db } from "mongodb";
+import type { Hono } from "hono";
+import type { Logger } from "pino";
+import type { AuthVariables } from "../../middleware/nyxidAuth";
+import { AnnouncementRepository } from "./repository";
+import { AnnouncementService } from "./service";
+import { createAnnouncementRoutes } from "./routes";
+import { migrateAnnouncementsToBilingual } from "./migration";
+
+export interface AnnouncementsWiring {
+  readonly service: AnnouncementService;
+  readonly routes: Hono<{ Variables: AuthVariables }>;
+}
+
+/**
+ * Construct repo + service + routes for announcements and queue the
+ * one-shot bilingual backfill. Returns the routes (mount on the API
+ * sub-app) plus the service (no current consumer needs it externally,
+ * but exposing it keeps the contract symmetric with other domains).
+ *
+ * Migration failure is non-fatal: the repo's mapper falls back to
+ * legacy single-locale fields, so reads stay correct even when the
+ * migration hasn't run yet.
+ */
+export async function wireAnnouncements(deps: {
+  db: Db;
+  logger: Logger;
+}): Promise<AnnouncementsWiring> {
+  const repo = new AnnouncementRepository(deps.db);
+  void repo.ensureIndexes().catch((err) =>
+    deps.logger.warn(
+      { err },
+      "announcements indexes ensureIndexes failed — proceeding anyway",
+    ),
+  );
+  // One-shot bilingual backfill: copies legacy single-locale columns
+  // (title / bodyMarkdown / ctaLabel) into the new per-locale slots
+  // (`*En` + `*Zh`). Idempotent — second boot is a no-op. Failure is
+  // logged + non-fatal; the repo's mapper falls back to legacy fields.
+  await migrateAnnouncementsToBilingual(deps.db, deps.logger).catch((err) =>
+    deps.logger.error(
+      { err: err instanceof Error ? err.message : String(err) },
+      "announcements bilingual migration crashed — repo fallback will cover reads, retry on next boot",
+    ),
+  );
+  const service = new AnnouncementService({ repo });
+  const routes = createAnnouncementRoutes({ announcementService: service });
+  return { service, routes };
+}
diff --git a/ornn-api/src/domains/announcements/repository.test.ts b/ornn-api/src/domains/announcements/repository.test.ts
new file mode 100644
index 00000000..41553e69
--- /dev/null
+++ b/ornn-api/src/domains/announcements/repository.test.ts
@@ -0,0 +1,247 @@
+/**
+ * AnnouncementRepository unit tests (#454).
+ *
+ * Single-active model. Two read paths:
+ *   - findActive: the popup — most recent enabled record currently in
+ *     its [startsAt, endsAt] window.
+ *   - findAllReleased: the News archive — every enabled record whose
+ *     start gate has elapsed, newest first. Past records are kept.
+ *
+ * Tolerates legacy single-locale documents (raw `title`/`bodyMarkdown`)
+ * during the bilingual rollout window, so the repo mapper has its own
+ * test surface.
+ *
+ * @module domains/announcements/repository.test
+ */
+
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+import { MongoClient, type Db, type Document } from "mongodb";
+import { MongoMemoryServer } from "mongodb-memory-server";
+import { AnnouncementRepository, type CreateAnnouncementInput } from "./repository";
+
+let mongo: MongoMemoryServer;
+let client: MongoClient;
+let db: Db;
+let repo: AnnouncementRepository;
+
+beforeAll(async () => {
+  mongo = await MongoMemoryServer.create();
+  client = new MongoClient(mongo.getUri());
+  await client.connect();
+  db = client.db("announcements_test");
+  repo = new AnnouncementRepository(db);
+  await repo.ensureIndexes();
+});
+
+afterAll(async () => {
+  await client.close();
+  await mongo.stop();
+});
+
+beforeEach(async () => {
+  await db.collection("announcements").deleteMany({});
+});
+
+function mkInput(overrides: Partial<CreateAnnouncementInput> = {}): CreateAnnouncementInput {
+  return {
+    titleEn: "Hello",
+    titleZh: "你好",
+    bodyMarkdownEn: "# Body",
+    bodyMarkdownZh: "# 正文",
+    ctaLabelEn: null,
+    ctaLabelZh: null,
+    ctaUrl: null,
+    enabled: true,
+    startsAt: null,
+    endsAt: null,
+    createdBy: "admin-1",
+    ...overrides,
+  };
+}
+
+describe("create", () => {
+  test("inserts and returns the mapped document", async () => {
+    const doc = await repo.create(mkInput());
+    expect(doc._id).toBeDefined();
+    expect(doc.titleEn).toBe("Hello");
+    expect(doc.titleZh).toBe("你好");
+    expect(doc.enabled).toBe(true);
+    expect(doc.createdBy).toBe("admin-1");
+    expect(doc.createdAt).toBeInstanceOf(Date);
+    expect(doc.updatedAt).toBeInstanceOf(Date);
+  });
+
+  test("nullable CTA + schedule fields default to null", async () => {
+    const doc = await repo.create(mkInput());
+    expect(doc.ctaLabelEn).toBeNull();
+    expect(doc.ctaLabelZh).toBeNull();
+    expect(doc.ctaUrl).toBeNull();
+    expect(doc.startsAt).toBeNull();
+    expect(doc.endsAt).toBeNull();
+  });
+});
+
+describe("listAll + findById", () => {
+  test("listAll returns every record, newest first", async () => {
+    await repo.create(mkInput({ titleEn: "First" }));
+    await new Promise((r) => setTimeout(r, 5));
+    await repo.create(mkInput({ titleEn: "Second" }));
+    await new Promise((r) => setTimeout(r, 5));
+    await repo.create(mkInput({ titleEn: "Third" }));
+    const rows = await repo.listAll();
+    expect(rows).toHaveLength(3);
+    expect(rows[0]?.titleEn).toBe("Third");
+    expect(rows[2]?.titleEn).toBe("First");
+  });
+
+  test("findById returns the matching doc or null", async () => {
+    const created = await repo.create(mkInput());
+    const found = await repo.findById(created._id);
+    expect(found?._id).toBe(created._id);
+    const missing = await repo.findById("does-not-exist");
+    expect(missing).toBeNull();
+  });
+});
+
+describe("findActive", () => {
+  test("returns the most recent enabled record in-window", async () => {
+    const past = new Date(Date.now() - 60_000);
+    const future = new Date(Date.now() + 60_000);
+    await repo.create(mkInput({ titleEn: "Old", startsAt: past, endsAt: future }));
+    await new Promise((r) => setTimeout(r, 5));
+    await repo.create(mkInput({ titleEn: "Newer", startsAt: past, endsAt: future }));
+    const active = await repo.findActive(new Date());
+    expect(active?.titleEn).toBe("Newer");
+  });
+
+  test("ignores disabled records", async () => {
+    await repo.create(mkInput({ titleEn: "Off", enabled: false }));
+    const active = await repo.findActive(new Date());
+    expect(active).toBeNull();
+  });
+
+  test("ignores records before startsAt", async () => {
+    const future = new Date(Date.now() + 60_000);
+    await repo.create(mkInput({ titleEn: "Not yet", startsAt: future, endsAt: null }));
+    const active = await repo.findActive(new Date());
+    expect(active).toBeNull();
+  });
+
+  test("ignores records after endsAt", async () => {
+    const past = new Date(Date.now() - 60_000);
+    await repo.create(mkInput({ titleEn: "Expired", startsAt: null, endsAt: past }));
+    const active = await repo.findActive(new Date());
+    expect(active).toBeNull();
+  });
+
+  test("null bounds mean open-ended on that side", async () => {
+    await repo.create(mkInput({ titleEn: "Always", startsAt: null, endsAt: null }));
+    const active = await repo.findActive(new Date());
+    expect(active?.titleEn).toBe("Always");
+  });
+});
+
+describe("findAllReleased", () => {
+  test("returns every enabled record whose startsAt has elapsed (incl. expired)", async () => {
+    const past = new Date(Date.now() - 60_000);
+    const pastEnd = new Date(Date.now() - 30_000);
+    const future = new Date(Date.now() + 60_000);
+    // Released + still in window
+    await repo.create(mkInput({ titleEn: "Live", startsAt: past, endsAt: future }));
+    // Released + expired — News page retains this
+    await new Promise((r) => setTimeout(r, 5));
+    await repo.create(mkInput({ titleEn: "Archived", startsAt: past, endsAt: pastEnd }));
+    // Not yet released — excluded
+    await new Promise((r) => setTimeout(r, 5));
+    await repo.create(mkInput({ titleEn: "Future", startsAt: future, endsAt: null }));
+    // Disabled — excluded
+    await new Promise((r) => setTimeout(r, 5));
+    await repo.create(mkInput({ titleEn: "Off", enabled: false }));
+
+    const rows = await repo.findAllReleased(new Date());
+    expect(rows.map((r) => r.titleEn).sort()).toEqual(["Archived", "Live"]);
+  });
+});
+
+describe("update", () => {
+  test("patches specified fields and bumps updatedAt", async () => {
+    const created = await repo.create(mkInput({ titleEn: "Old" }));
+    const oldUpdatedAt = created.updatedAt.getTime();
+    await new Promise((r) => setTimeout(r, 10));
+    const patched = await repo.update(created._id, { titleEn: "New" });
+    expect(patched?.titleEn).toBe("New");
+    expect(patched?.titleZh).toBe("你好"); // untouched
+    expect((patched?.updatedAt.getTime() ?? 0)).toBeGreaterThan(oldUpdatedAt);
+  });
+
+  test("can clear nullable fields (set to null)", async () => {
+    const created = await repo.create(
+      mkInput({ ctaLabelEn: "Click", ctaLabelZh: "点击", ctaUrl: "https://x" }),
+    );
+    const patched = await repo.update(created._id, {
+      ctaLabelEn: null,
+      ctaLabelZh: null,
+      ctaUrl: null,
+    });
+    expect(patched?.ctaLabelEn).toBeNull();
+    expect(patched?.ctaLabelZh).toBeNull();
+    expect(patched?.ctaUrl).toBeNull();
+  });
+
+  test("returns null when id doesn't exist (no insert)", async () => {
+    const res = await repo.update("does-not-exist", { titleEn: "X" });
+    expect(res).toBeNull();
+    const count = await db.collection("announcements").countDocuments();
+    expect(count).toBe(0);
+  });
+});
+
+describe("delete", () => {
+  test("removes a record and reports success", async () => {
+    const created = await repo.create(mkInput());
+    const ok = await repo.delete(created._id);
+    expect(ok).toBe(true);
+    expect(await repo.findById(created._id)).toBeNull();
+  });
+
+  test("returns false when id doesn't exist", async () => {
+    const ok = await repo.delete("does-not-exist");
+    expect(ok).toBe(false);
+  });
+});
+
+describe("legacy single-locale tolerance (mapper)", () => {
+  test("backfills *En / *Zh from legacy `title` / `bodyMarkdown` / `ctaLabel` columns", async () => {
+    // Old shape, pre-bilingual rollout. Repo MUST surface the legacy
+    // text on both locale slots so the public surface keeps rendering
+    // until the boot migration's first pass.
+    const legacyDoc: Document = {
+      _id: "legacy-1",
+      title: "Legacy Title",
+      bodyMarkdown: "Legacy body",
+      ctaLabel: "Legacy CTA",
+      ctaUrl: "https://x",
+      enabled: true,
+      startsAt: null,
+      endsAt: null,
+      createdBy: "admin-legacy",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+    await db.collection("announcements").insertOne(legacyDoc);
+    const found = await repo.findById("legacy-1");
+    expect(found?.titleEn).toBe("Legacy Title");
+    expect(found?.titleZh).toBe("Legacy Title");
+    expect(found?.bodyMarkdownEn).toBe("Legacy body");
+    expect(found?.bodyMarkdownZh).toBe("Legacy body");
+    expect(found?.ctaLabelEn).toBe("Legacy CTA");
+    expect(found?.ctaLabelZh).toBe("Legacy CTA");
+  });
+});
diff --git a/ornn-api/src/domains/announcements/repository.ts b/ornn-api/src/domains/announcements/repository.ts
index 163271cc..2b24b045 100644
--- a/ornn-api/src/domains/announcements/repository.ts
+++ b/ornn-api/src/domains/announcements/repository.ts
@@ -28,10 +28,10 @@
 
 import { randomUUID } from "node:crypto";
 import type { Collection, Db, Document } from "mongodb";
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import type { AnnouncementDocument } from "./types";
 
-const logger = pino({ level: "info" }).child({ module: "announcementRepository" });
+const logger = createLogger("announcementRepository");
 
 export interface CreateAnnouncementInput {
   titleEn: string;
@@ -47,17 +47,21 @@ export interface CreateAnnouncementInput {
   createdBy: string;
 }
 
+// Fields are `| undefined` (not just `?`) because callers pass
+// Zod-inferred `.optional()` shapes where absent keys arrive as
+// explicit `undefined`. Under exactOptionalPropertyTypes (#657), `?`
+// alone rejects that. The `update()` impl ignores undefined values.
 export interface UpdateAnnouncementInput {
-  titleEn?: string;
-  titleZh?: string;
-  bodyMarkdownEn?: string;
-  bodyMarkdownZh?: string;
-  ctaLabelEn?: string | null;
-  ctaLabelZh?: string | null;
-  ctaUrl?: string | null;
-  enabled?: boolean;
-  startsAt?: Date | null;
-  endsAt?: Date | null;
+  titleEn?: string | undefined;
+  titleZh?: string | undefined;
+  bodyMarkdownEn?: string | undefined;
+  bodyMarkdownZh?: string | undefined;
+  ctaLabelEn?: string | null | undefined;
+  ctaLabelZh?: string | null | undefined;
+  ctaUrl?: string | null | undefined;
+  enabled?: boolean | undefined;
+  startsAt?: Date | null | undefined;
+  endsAt?: Date | null | undefined;
 }
 
 export class AnnouncementRepository {
diff --git a/ornn-api/src/domains/announcements/routes.ts b/ornn-api/src/domains/announcements/routes.ts
index 38b7b863..e1af8547 100644
--- a/ornn-api/src/domains/announcements/routes.ts
+++ b/ornn-api/src/domains/announcements/routes.ts
@@ -30,6 +30,7 @@ import {
   requirePermission,
 } from "../../middleware/nyxidAuth";
 import { AppError } from "../../shared/types/index";
+import { validateBody, getValidatedBody } from "../../middleware/validate";
 import type { AnnouncementService } from "./service";
 import type { AnnouncementDocument } from "./types";
 
@@ -88,11 +89,12 @@ const updateSchema = z
  * `ctaLabelZh` is independent (optional translation of the label —
  * frontend falls back to `ctaLabelEn` when empty).
  */
+// Use `Record<string, unknown>` (rather than a narrow Pick) so we can
+// share this refinement between createSchema (full required) and
+// updateSchema (every field optional) without the inferred input
+// type clashing under exactOptionalPropertyTypes (#657).
 function assertCtaPairing(
-  value: {
-    ctaUrl?: string | null;
-    ctaLabelEn?: string | null;
-  },
+  value: Record<string, unknown>,
   ctx: z.RefinementCtx,
 ): void {
   const hasUrl = typeof value.ctaUrl === "string" && value.ctaUrl.length > 0;
@@ -136,48 +138,47 @@ export function createAnnouncementRoutes(
     return c.json({ data: { items: items.map(toAdminDto) }, error: null });
   });
 
-  app.post("/admin/announcements", auth, adminGuard, async (c) => {
-    const authCtx = getAuth(c);
-    const body = await c.req.json().catch(() => ({}));
-    const parsed = createSchema.safeParse(body);
-    if (!parsed.success) {
-      throw AppError.badRequest(
-        "INVALID_ANNOUNCEMENT_INPUT",
-        parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "),
-      );
-    }
-    const created = await announcementService.create({
-      titleEn: parsed.data.titleEn,
-      titleZh: parsed.data.titleZh,
-      bodyMarkdownEn: parsed.data.bodyMarkdownEn,
-      bodyMarkdownZh: parsed.data.bodyMarkdownZh,
-      ctaLabelEn: parsed.data.ctaLabelEn ?? null,
-      ctaLabelZh: parsed.data.ctaLabelZh ?? null,
-      ctaUrl: parsed.data.ctaUrl ?? null,
-      enabled: parsed.data.enabled,
-      startsAt: parsed.data.startsAt ?? null,
-      endsAt: parsed.data.endsAt ?? null,
-      createdBy: authCtx.userId,
-    });
+  app.post(
+    "/admin/announcements",
+    auth,
+    adminGuard,
+    validateBody(createSchema, "invalid_announcement_input"),
+    async (c) => {
+      const authCtx = getAuth(c);
+      const data = getValidatedBody<z.infer<typeof createSchema>>(c);
+      const created = await announcementService.create({
+        titleEn: data.titleEn,
+        titleZh: data.titleZh,
+        bodyMarkdownEn: data.bodyMarkdownEn,
+        bodyMarkdownZh: data.bodyMarkdownZh,
+        ctaLabelEn: data.ctaLabelEn ?? null,
+        ctaLabelZh: data.ctaLabelZh ?? null,
+        ctaUrl: data.ctaUrl ?? null,
+        enabled: data.enabled,
+        startsAt: data.startsAt ?? null,
+        endsAt: data.endsAt ?? null,
+        createdBy: authCtx.userId,
+      });
+    // 201 already set; add Location to match CONVENTIONS.md §3.2 (#458).
+    c.header("Location", `/api/v1/admin/announcements/${created._id}`);
     return c.json({ data: toAdminDto(created), error: null }, 201);
   });
 
-  app.patch("/admin/announcements/:id", auth, adminGuard, async (c) => {
-    const id = c.req.param("id");
-    const body = await c.req.json().catch(() => ({}));
-    const parsed = updateSchema.safeParse(body);
-    if (!parsed.success) {
-      throw AppError.badRequest(
-        "INVALID_ANNOUNCEMENT_INPUT",
-        parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "),
-      );
-    }
-    if (Object.keys(parsed.data).length === 0) {
-      throw AppError.badRequest("INVALID_ANNOUNCEMENT_INPUT", "No fields to update");
-    }
-    const updated = await announcementService.update(id, parsed.data);
-    return c.json({ data: toAdminDto(updated), error: null });
-  });
+  app.patch(
+    "/admin/announcements/:id",
+    auth,
+    adminGuard,
+    validateBody(updateSchema, "invalid_announcement_input"),
+    async (c) => {
+      const id = c.req.param("id");
+      const data = getValidatedBody<z.infer<typeof updateSchema>>(c);
+      if (Object.keys(data).length === 0) {
+        throw AppError.badRequest("invalid_announcement_input", "No fields to update");
+      }
+      const updated = await announcementService.update(id, data);
+      return c.json({ data: toAdminDto(updated), error: null });
+    },
+  );
 
   app.delete("/admin/announcements/:id", auth, adminGuard, async (c) => {
     const id = c.req.param("id");
diff --git a/ornn-api/src/domains/announcements/service.ts b/ornn-api/src/domains/announcements/service.ts
index 2c1ae56a..1995239f 100644
--- a/ornn-api/src/domains/announcements/service.ts
+++ b/ornn-api/src/domains/announcements/service.ts
@@ -14,7 +14,7 @@
  * @module domains/announcements/service
  */
 
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import { AppError } from "../../shared/types/index";
 import type {
   AnnouncementRepository,
@@ -27,7 +27,7 @@ import type {
   PublicAnnouncementListItem,
 } from "./types";
 
-const logger = pino({ level: "info" }).child({ module: "announcementService" });
+const logger = createLogger("announcementService");
 
 export interface AnnouncementServiceDeps {
   readonly repo: AnnouncementRepository;
@@ -77,7 +77,7 @@ export class AnnouncementService {
   async getById(id: string): Promise<AnnouncementDocument> {
     const doc = await this.repo.findById(id);
     if (!doc) {
-      throw AppError.notFound("ANNOUNCEMENT_NOT_FOUND", "Announcement not found");
+      throw AppError.notFound("announcement_not_found", "Announcement not found");
     }
     return doc;
   }
@@ -103,7 +103,7 @@ export class AnnouncementService {
     }
     const updated = await this.repo.update(id, patch);
     if (!updated) {
-      throw AppError.notFound("ANNOUNCEMENT_NOT_FOUND", "Announcement not found");
+      throw AppError.notFound("announcement_not_found", "Announcement not found");
     }
     logger.info({ announcementId: id, enabled: updated.enabled }, "Announcement updated");
     return updated;
@@ -112,7 +112,7 @@ export class AnnouncementService {
   async delete(id: string): Promise<void> {
     const removed = await this.repo.delete(id);
     if (!removed) {
-      throw AppError.notFound("ANNOUNCEMENT_NOT_FOUND", "Announcement not found");
+      throw AppError.notFound("announcement_not_found", "Announcement not found");
     }
     logger.info({ announcementId: id }, "Announcement deleted");
   }
diff --git a/ornn-api/src/domains/broadcasts/bootstrap.ts b/ornn-api/src/domains/broadcasts/bootstrap.ts
new file mode 100644
index 00000000..3fabbaa3
--- /dev/null
+++ b/ornn-api/src/domains/broadcasts/bootstrap.ts
@@ -0,0 +1,79 @@
+/**
+ * Wire the broadcasts domain (#580 — bootstrap decomposition).
+ *
+ * Broadcasts and notifications share the same `BroadcastRepository`
+ * instance: notifications reads from it on the merged-feed path
+ * (#500 left-join with read receipts), broadcasts writes through its
+ * own service on admin CRUD. A single shared instance keeps the
+ * read/write surfaces consistent without a second TTL or cache layer.
+ *
+ * Wiring order is deliberate — the repo is built FIRST so the
+ * `wireNotifications` call can take a reference to it, then the
+ * broadcast service + routes are built on top of the same repo.
+ *
+ * @module domains/broadcasts/bootstrap
+ */
+
+import type { Db } from "mongodb";
+import type { Hono } from "hono";
+import type { Logger } from "pino";
+import type { AuthVariables } from "../../middleware/nyxidAuth";
+import { BroadcastRepository } from "./repository";
+import { BroadcastService } from "./service";
+import { createBroadcastRoutes } from "./routes";
+import { backfillBroadcastRecipientUserIds } from "./migration";
+
+export interface BroadcastsRepoWiring {
+  readonly repo: BroadcastRepository;
+}
+
+export interface BroadcastsWiring extends BroadcastsRepoWiring {
+  readonly service: BroadcastService;
+  readonly routes: Hono<{ Variables: AuthVariables }>;
+}
+
+/**
+ * Step 1 — construct the repo + run the one-shot bilingual + targeting
+ * backfill migration. Notifications wiring needs the repo reference
+ * before its own service is built; this entry point gives it that
+ * without forcing broadcasts to construct its service + routes prematurely.
+ *
+ * Pre-#502 docs don't carry `recipientUserIds`; the migration writes
+ * an explicit `null` on every absent doc so the merged feed can rely
+ * on a stable `string[] | null` shape. Idempotent; failure is
+ * non-fatal — the repo mapper's `Array.isArray` guard already
+ * normalises absent fields to `null` on the read path.
+ */
+export async function wireBroadcastsRepo(deps: {
+  db: Db;
+  logger: Logger;
+}): Promise<BroadcastsRepoWiring> {
+  const repo = new BroadcastRepository(deps.db);
+  void repo.ensureIndexes().catch((err) =>
+    deps.logger.warn(
+      { err },
+      "broadcasts indexes ensureIndexes failed — proceeding anyway",
+    ),
+  );
+  await backfillBroadcastRecipientUserIds(deps.db, deps.logger).catch((err) =>
+    deps.logger.error(
+      { err: err instanceof Error ? err.message : String(err) },
+      "broadcasts recipientUserIds backfill crashed — mapper fallback will cover reads, retry on next boot",
+    ),
+  );
+  return { repo };
+}
+
+/**
+ * Step 2 — build the service + routes on the shared repo. Called
+ * after `wireNotifications` so the merged feed has already taken
+ * its repo reference (no functional dependency, just an ordering
+ * preference that matches the original bootstrap flow).
+ */
+export function wireBroadcasts(deps: {
+  repo: BroadcastRepository;
+}): { service: BroadcastService; routes: Hono<{ Variables: AuthVariables }> } {
+  const service = new BroadcastService({ repo: deps.repo });
+  const routes = createBroadcastRoutes({ broadcastService: service });
+  return { service, routes };
+}
diff --git a/ornn-api/src/domains/broadcasts/repository.ts b/ornn-api/src/domains/broadcasts/repository.ts
index a7cb7cd5..9f90599d 100644
--- a/ornn-api/src/domains/broadcasts/repository.ts
+++ b/ornn-api/src/domains/broadcasts/repository.ts
@@ -22,14 +22,14 @@
 
 import { randomUUID } from "node:crypto";
 import type { Collection, Db, Document } from "mongodb";
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import type {
   BroadcastDocument,
   BroadcastI18nString,
   BroadcastReadReceiptDocument,
 } from "./types";
 
-const logger = pino({ level: "info" }).child({ module: "broadcastRepository" });
+const logger = createLogger("broadcastRepository");
 
 export interface CreateBroadcastDocInput {
   titleI18n: BroadcastI18nString;
@@ -50,8 +50,11 @@ export interface CreateBroadcastDocInput {
  * guard against a future caller forgetting the invariant.
  */
 export interface UpdateBroadcastDocInput {
-  titleI18n?: Partial<BroadcastI18nString>;
-  bodyMarkdownI18n?: Partial<BroadcastI18nString>;
+  // Inner Partial accepts `string | undefined` to match the Zod-
+  // inferred patch shape callers pass through the service. The repo
+  // skips `undefined` keys when building the `$set` patch.
+  titleI18n?: { en?: string | undefined; zh?: string | undefined };
+  bodyMarkdownI18n?: { en?: string | undefined; zh?: string | undefined };
   updatedBy: string;
 }
 
diff --git a/ornn-api/src/domains/broadcasts/routes.ts b/ornn-api/src/domains/broadcasts/routes.ts
index 228ee15b..85f3e7fc 100644
--- a/ornn-api/src/domains/broadcasts/routes.ts
+++ b/ornn-api/src/domains/broadcasts/routes.ts
@@ -27,7 +27,8 @@ import {
   nyxidAuthMiddleware,
   requirePermission,
 } from "../../middleware/nyxidAuth";
-import { AppError } from "../../shared/types/index";
+import { z } from "zod";
+import { validateBody, getValidatedBody } from "../../middleware/validate";
 import { createBroadcastSchema, patchBroadcastSchema } from "./schemas";
 import type { BroadcastService } from "./service";
 
@@ -50,47 +51,49 @@ export function createBroadcastRoutes(
     return c.json({ data: { items }, error: null });
   });
 
-  app.post("/admin/broadcasts", auth, adminGuard, async (c) => {
-    const authCtx = getAuth(c);
-    const body = await c.req.json().catch(() => ({}));
-    const parsed = createBroadcastSchema.safeParse(body);
-    if (!parsed.success) {
-      throw AppError.badRequest(
-        "INVALID_BROADCAST_INPUT",
-        parsed.error.issues
-          .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
-          .join("; "),
-      );
-    }
-    const created = await broadcastService.create({
-      titleI18n: parsed.data.titleI18n,
-      bodyMarkdownI18n: parsed.data.bodyMarkdownI18n,
-      createdBy: authCtx.userId,
-      recipientUserIds: parsed.data.recipientUserIds,
-    });
-    return c.json({ data: created, error: null }, 201);
-  });
+  app.post(
+    "/admin/broadcasts",
+    auth,
+    adminGuard,
+    validateBody(createBroadcastSchema, "invalid_broadcast_input"),
+    async (c) => {
+      const authCtx = getAuth(c);
+      const data = getValidatedBody<z.infer<typeof createBroadcastSchema>>(c);
+      const created = await broadcastService.create({
+        titleI18n: data.titleI18n,
+        bodyMarkdownI18n: data.bodyMarkdownI18n,
+        createdBy: authCtx.userId,
+        // exactOptionalPropertyTypes (#657)
+        ...(data.recipientUserIds !== undefined
+          ? { recipientUserIds: data.recipientUserIds }
+          : {}),
+      });
+      // 201 + Location per CONVENTIONS.md §3.2 (#458).
+      c.header("Location", `/api/v1/admin/broadcasts/${created.id}`);
+      return c.json({ data: created, error: null }, 201);
+    },
+  );
 
-  app.patch("/admin/broadcasts/:id", auth, adminGuard, async (c) => {
-    const authCtx = getAuth(c);
-    const id = c.req.param("id");
-    const body = await c.req.json().catch(() => ({}));
-    const parsed = patchBroadcastSchema.safeParse(body);
-    if (!parsed.success) {
-      throw AppError.badRequest(
-        "INVALID_BROADCAST_INPUT",
-        parsed.error.issues
-          .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
-          .join("; "),
-      );
-    }
-    const updated = await broadcastService.update(id, {
-      titleI18n: parsed.data.titleI18n,
-      bodyMarkdownI18n: parsed.data.bodyMarkdownI18n,
-      updatedBy: authCtx.userId,
-    });
-    return c.json({ data: updated, error: null });
-  });
+  app.patch(
+    "/admin/broadcasts/:id",
+    auth,
+    adminGuard,
+    validateBody(patchBroadcastSchema, "invalid_broadcast_input"),
+    async (c) => {
+      const authCtx = getAuth(c);
+      const id = c.req.param("id");
+      const data = getValidatedBody<z.infer<typeof patchBroadcastSchema>>(c);
+      const updated = await broadcastService.update(id, {
+        // exactOptionalPropertyTypes (#657)
+        ...(data.titleI18n !== undefined ? { titleI18n: data.titleI18n } : {}),
+        ...(data.bodyMarkdownI18n !== undefined
+          ? { bodyMarkdownI18n: data.bodyMarkdownI18n }
+          : {}),
+        updatedBy: authCtx.userId,
+      });
+      return c.json({ data: updated, error: null });
+    },
+  );
 
   app.delete("/admin/broadcasts/:id", auth, adminGuard, async (c) => {
     const id = c.req.param("id");
diff --git a/ornn-api/src/domains/broadcasts/service.ts b/ornn-api/src/domains/broadcasts/service.ts
index e69448ef..14ea6dcc 100644
--- a/ornn-api/src/domains/broadcasts/service.ts
+++ b/ornn-api/src/domains/broadcasts/service.ts
@@ -24,7 +24,7 @@
  * @module domains/broadcasts/service
  */
 
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import { AppError } from "../../shared/types/index";
 import type {
   BroadcastRepository,
@@ -37,7 +37,7 @@ import type {
   BroadcastI18nString,
 } from "./types";
 
-const logger = pino({ level: "info" }).child({ module: "broadcastService" });
+const logger = createLogger("broadcastService");
 
 export interface BroadcastServiceDeps {
   readonly repo: BroadcastRepository;
@@ -62,8 +62,10 @@ export interface CreateBroadcastParams {
  * path is a compile error, matching the repository's enforcement.
  */
 export interface UpdateBroadcastParams {
-  titleI18n?: Partial<BroadcastI18nString>;
-  bodyMarkdownI18n?: Partial<BroadcastI18nString>;
+  // Inner Partial accepts `string | undefined` so Zod-inferred patch
+  // shapes fit under exactOptionalPropertyTypes (#657).
+  titleI18n?: { en?: string | undefined; zh?: string | undefined };
+  bodyMarkdownI18n?: { en?: string | undefined; zh?: string | undefined };
   updatedBy: string;
 }
 
@@ -91,7 +93,7 @@ export class BroadcastService {
   async getById(id: string): Promise<BroadcastDocument> {
     const doc = await this.repo.getById(id);
     if (!doc) {
-      throw AppError.notFound("BROADCAST_NOT_FOUND", "Broadcast not found");
+      throw AppError.notFound("broadcast_not_found", "Broadcast not found");
     }
     return doc;
   }
@@ -101,7 +103,10 @@ export class BroadcastService {
       titleI18n: params.titleI18n,
       bodyMarkdownI18n: params.bodyMarkdownI18n,
       createdBy: params.createdBy,
-      recipientUserIds: params.recipientUserIds,
+      // exactOptionalPropertyTypes (#657)
+      ...(params.recipientUserIds !== undefined
+        ? { recipientUserIds: params.recipientUserIds }
+        : {}),
     };
     const doc = await this.repo.create(input);
     logger.info(
@@ -125,13 +130,16 @@ export class BroadcastService {
     params: UpdateBroadcastParams,
   ): Promise<AdminBroadcastResponse> {
     const patch: UpdateBroadcastDocInput = {
-      titleI18n: params.titleI18n,
-      bodyMarkdownI18n: params.bodyMarkdownI18n,
+      // exactOptionalPropertyTypes (#657)
+      ...(params.titleI18n !== undefined ? { titleI18n: params.titleI18n } : {}),
+      ...(params.bodyMarkdownI18n !== undefined
+        ? { bodyMarkdownI18n: params.bodyMarkdownI18n }
+        : {}),
       updatedBy: params.updatedBy,
     };
     const updated = await this.repo.update(id, patch);
     if (!updated) {
-      throw AppError.notFound("BROADCAST_NOT_FOUND", "Broadcast not found");
+      throw AppError.notFound("broadcast_not_found", "Broadcast not found");
     }
     logger.info(
       { broadcastId: id, by: params.updatedBy },
@@ -154,7 +162,7 @@ export class BroadcastService {
     // "ok, deleted nothing" on a typo.
     const removed = await this.repo.delete(id);
     if (!removed) {
-      throw AppError.notFound("BROADCAST_NOT_FOUND", "Broadcast not found");
+      throw AppError.notFound("broadcast_not_found", "Broadcast not found");
     }
     try {
       const receiptsRemoved = await this.repo.deleteAllForBroadcast(id);
diff --git a/ornn-api/src/domains/me/routes.ts b/ornn-api/src/domains/me/routes.ts
index f05ce42a..aae59dde 100644
--- a/ornn-api/src/domains/me/routes.ts
+++ b/ornn-api/src/domains/me/routes.ts
@@ -8,6 +8,7 @@
  */
 
 import { Hono } from "hono";
+import { createLogger } from "../../shared/logger";
 import {
   type AuthVariables,
   nyxidAuthMiddleware,
@@ -21,6 +22,8 @@ import type { UserDirectoryRepository } from "../users/repository";
 import type { AnalyticsEmitter } from "../../infra/analytics";
 import { AppError } from "../../shared/types/index";
 
+const logger = createLogger("meRoutes");
+
 export interface MeRoutesConfig {
   /**
    * Resolves the NyxID API base URL from admin settings. Used by the
@@ -182,7 +185,7 @@ export function createMeRoutes(config: MeRoutesConfig): Hono<{ Variables: AuthVa
       // No caller token forwarded by the proxy — we can't act on their
       // behalf. Return 404-shaped response so the UI can show "unknown
       // org" without special-casing another error code.
-      throw AppError.notFound("ORG_NOT_FOUND", `Org '${orgId}' not found`);
+      throw AppError.notFound("org_not_found", `Org '${orgId}' not found`);
     }
 
     const baseUrl = await resolveBaseUrl();
@@ -190,7 +193,7 @@ export function createMeRoutes(config: MeRoutesConfig): Hono<{ Variables: AuthVa
       headers: { Authorization: `Bearer ${token}` },
     });
     if (resp.status === 404 || resp.status === 403) {
-      throw AppError.notFound("ORG_NOT_FOUND", `Org '${orgId}' not found`);
+      throw AppError.notFound("org_not_found", `Org '${orgId}' not found`);
     }
     if (!resp.ok) {
       const body = await resp.text().catch(() => "");
@@ -334,7 +337,11 @@ async function resolveOrgDisplayNames(
         if (!resp.ok) return { ...r, displayName: r.id };
         const body = (await resp.json()) as { display_name?: string | null };
         return { ...r, displayName: body.display_name ?? r.id };
-      } catch {
+      } catch (err) {
+        // Fall back to org id as display name; surfaced from a NyxID
+        // hiccup, not a logic bug. Log so we can spot persistent issues
+        // without alerting on every single transient failure.
+        logger.debug({ err, orgId: r.id }, "org display-name lookup failed");
         return { ...r, displayName: r.id };
       }
     }),
diff --git a/ornn-api/src/domains/notifications/bootstrap.ts b/ornn-api/src/domains/notifications/bootstrap.ts
new file mode 100644
index 00000000..19b65eed
--- /dev/null
+++ b/ornn-api/src/domains/notifications/bootstrap.ts
@@ -0,0 +1,59 @@
+/**
+ * Wire the notifications domain (#580 — bootstrap decomposition).
+ *
+ * Notifications consumes the shared `BroadcastRepository` (built by
+ * the broadcasts wiring) on the merged-feed path. The caller is
+ * expected to construct the broadcasts repo first via
+ * `wireBroadcastsRepo`, then pass that repo into `wireNotifications`.
+ *
+ * Also runs a one-time legacy-category cleanup migration (#218 — drop
+ * `share.*` notification rows) so the consumer UI doesn't surface
+ * stale rows from the pre-#198 share/audit-gate workflow.
+ *
+ * @module domains/notifications/bootstrap
+ */
+
+import type { Db } from "mongodb";
+import type { Hono } from "hono";
+import type { Logger } from "pino";
+import type { AuthVariables } from "../../middleware/nyxidAuth";
+import { NotificationRepository } from "./repository";
+import { NotificationService } from "./service";
+import { createNotificationRoutes } from "./routes";
+import { dropLegacyNotificationCategories } from "./migration";
+import type { BroadcastRepository } from "../broadcasts/repository";
+
+export interface NotificationsWiring {
+  readonly service: NotificationService;
+  readonly routes: Hono<{ Variables: AuthVariables }>;
+}
+
+export async function wireNotifications(deps: {
+  db: Db;
+  logger: Logger;
+  broadcastRepo: BroadcastRepository;
+}): Promise<NotificationsWiring> {
+  const repo = new NotificationRepository(deps.db);
+  void repo.ensureIndexes().catch((err) =>
+    deps.logger.warn(
+      { err },
+      "notifications indexes ensureIndexes failed — proceeding anyway",
+    ),
+  );
+  // One-time boot migration (#218) — drop legacy `share.*` rows left
+  // over from the pre-#198 share/audit-gate workflow. Idempotent; no-op
+  // after first run. Failure is non-fatal — old rows surface as ugly
+  // UI but never block the boot.
+  await dropLegacyNotificationCategories(deps.db).catch((err) =>
+    deps.logger.error(
+      { err: err instanceof Error ? err.message : String(err) },
+      "dropLegacyNotificationCategories failed — legacy notification rows may still surface in /notifications until the next deploy",
+    ),
+  );
+  const service = new NotificationService({
+    notificationRepo: repo,
+    broadcastRepo: deps.broadcastRepo,
+  });
+  const routes = createNotificationRoutes({ notificationService: service });
+  return { service, routes };
+}
diff --git a/ornn-api/src/domains/notifications/migration.ts b/ornn-api/src/domains/notifications/migration.ts
index 683432cc..ab4cab6f 100644
--- a/ornn-api/src/domains/notifications/migration.ts
+++ b/ornn-api/src/domains/notifications/migration.ts
@@ -20,11 +20,9 @@
  */
 
 import type { Db } from "mongodb";
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 
-const logger = pino({ level: "info" }).child({
-  module: "notificationsMigration",
-});
+const logger = createLogger("notificationsMigration");
 
 const ALLOWED_CATEGORIES = [
   "audit.completed",
diff --git a/ornn-api/src/domains/notifications/repository.test.ts b/ornn-api/src/domains/notifications/repository.test.ts
new file mode 100644
index 00000000..c8a7f171
--- /dev/null
+++ b/ornn-api/src/domains/notifications/repository.test.ts
@@ -0,0 +1,184 @@
+/**
+ * NotificationRepository unit tests (#454).
+ *
+ * Append-only per-user inbox + read-marker tracking. Pins:
+ *   - create assigns id + createdAt + readAt=null
+ *   - list filters per-user, respects unreadOnly + before, sorts desc by createdAt
+ *   - countUnread counts only unread
+ *   - markRead is per-user (can't read someone else's notification)
+ *   - markAllRead returns modifiedCount
+ *
+ * @module domains/notifications/repository.test
+ */
+
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+import { MongoClient, type Db } from "mongodb";
+import { MongoMemoryServer } from "mongodb-memory-server";
+import { NotificationRepository } from "./repository";
+
+let mongo: MongoMemoryServer;
+let client: MongoClient;
+let db: Db;
+let repo: NotificationRepository;
+
+beforeAll(async () => {
+  mongo = await MongoMemoryServer.create();
+  client = new MongoClient(mongo.getUri());
+  await client.connect();
+  db = client.db("notifications_test");
+  repo = new NotificationRepository(db);
+  await repo.ensureIndexes();
+});
+
+afterAll(async () => {
+  await client.close();
+  await mongo.stop();
+});
+
+beforeEach(async () => {
+  await db.collection("notifications").deleteMany({});
+});
+
+function seed(userId: string, n: number) {
+  const promises: Array<Promise<unknown>> = [];
+  for (let i = 0; i < n; i++) {
+    promises.push(
+      repo.create({
+        userId,
+        category: "audit.completed",
+        title: `Notification ${i}`,
+        body: `Body ${i}`,
+      }),
+    );
+  }
+  return Promise.all(promises);
+}
+
+describe("create", () => {
+  test("assigns id, sets readAt=null, stamps createdAt", async () => {
+    const n = await repo.create({
+      userId: "u1",
+      category: "audit.completed",
+      title: "Hello",
+      body: "World",
+    });
+    expect(n._id).toBeDefined();
+    expect(n.userId).toBe("u1");
+    expect(n.title).toBe("Hello");
+    expect(n.readAt).toBeNull();
+    expect(n.createdAt).toBeInstanceOf(Date);
+  });
+});
+
+describe("list", () => {
+  beforeEach(async () => {
+    await seed("u1", 5);
+    await seed("u2", 2);
+  });
+
+  test("returns only the calling user's notifications", async () => {
+    const u1 = await repo.list("u1");
+    const u2 = await repo.list("u2");
+    expect(u1).toHaveLength(5);
+    expect(u2).toHaveLength(2);
+    // Strict ownership — no bleed
+    expect(u1.every((n) => n.userId === "u1")).toBe(true);
+  });
+
+  test("sorts newest-first", async () => {
+    const list = await repo.list("u1");
+    for (let i = 0; i + 1 < list.length; i++) {
+      expect(list[i]!.createdAt.getTime()).toBeGreaterThanOrEqual(list[i + 1]!.createdAt.getTime());
+    }
+  });
+
+  test("limit caps at 200 even when caller asks for more", async () => {
+    const big = await repo.list("u1", { limit: 1_000_000 });
+    // We only seeded 5; the cap doesn't expand results. Real test of
+    // the cap is at the repo layer reading from MongoDB.
+    expect(big.length).toBeLessThanOrEqual(200);
+    expect(big).toHaveLength(5);
+  });
+
+  test("unreadOnly filter", async () => {
+    const before = await repo.list("u1");
+    await repo.markRead("u1", before[0]!._id);
+    const unread = await repo.list("u1", { unreadOnly: true });
+    expect(unread).toHaveLength(4);
+    expect(unread.every((n) => n.readAt === null)).toBe(true);
+  });
+
+  test("before filter", async () => {
+    // Page through using `before`
+    const all = await repo.list("u1");
+    const cutoff = all[2]!.createdAt;
+    const older = await repo.list("u1", { before: cutoff });
+    // Should return entries strictly older than cutoff
+    expect(older.every((n) => n.createdAt.getTime() < cutoff.getTime())).toBe(true);
+  });
+});
+
+describe("countUnread", () => {
+  test("counts unread for the user", async () => {
+    await seed("u1", 3);
+    expect(await repo.countUnread("u1")).toBe(3);
+    const list = await repo.list("u1");
+    await repo.markRead("u1", list[0]!._id);
+    expect(await repo.countUnread("u1")).toBe(2);
+  });
+
+  test("scoped per-user", async () => {
+    await seed("u1", 3);
+    await seed("u2", 5);
+    expect(await repo.countUnread("u1")).toBe(3);
+    expect(await repo.countUnread("u2")).toBe(5);
+  });
+});
+
+describe("markRead", () => {
+  test("marks the targeted notification readAt to now", async () => {
+    await seed("u1", 2);
+    const [first] = await repo.list("u1");
+    const updated = await repo.markRead("u1", first!._id);
+    expect(updated?.readAt).toBeInstanceOf(Date);
+  });
+
+  test("does NOT let user A read user B's notification", async () => {
+    await seed("u1", 1);
+    const [n] = await repo.list("u1");
+    const result = await repo.markRead("attacker", n!._id);
+    expect(result).toBeNull();
+    // Verify the underlying notification is still unread.
+    const fresh = await repo.list("u1");
+    expect(fresh[0]!.readAt).toBeNull();
+  });
+});
+
+describe("markAllRead", () => {
+  test("flips every unread to read for the user, returns modifiedCount", async () => {
+    await seed("u1", 4);
+    const n = await repo.markAllRead("u1");
+    expect(n).toBe(4);
+    expect(await repo.countUnread("u1")).toBe(0);
+  });
+
+  test("returns 0 when there's nothing unread", async () => {
+    await seed("u1", 2);
+    await repo.markAllRead("u1");
+    expect(await repo.markAllRead("u1")).toBe(0);
+  });
+
+  test("doesn't affect other users", async () => {
+    await seed("u1", 2);
+    await seed("u2", 3);
+    await repo.markAllRead("u1");
+    expect(await repo.countUnread("u2")).toBe(3);
+  });
+});
diff --git a/ornn-api/src/domains/notifications/repository.ts b/ornn-api/src/domains/notifications/repository.ts
index 2ce7de6e..d5de9d60 100644
--- a/ornn-api/src/domains/notifications/repository.ts
+++ b/ornn-api/src/domains/notifications/repository.ts
@@ -9,10 +9,10 @@
 
 import { randomUUID } from "node:crypto";
 import type { Collection, Db, Document, Filter } from "mongodb";
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import type { NotificationCategory, NotificationDocument } from "./types";
 
-const logger = pino({ level: "info" }).child({ module: "notificationRepository" });
+const logger = createLogger("notificationRepository");
 
 export interface CreateNotificationInput {
   userId: string;
@@ -111,8 +111,10 @@ function mapDoc(doc: Document | null): NotificationDocument | null {
     userId: String(doc.userId),
     category: doc.category as NotificationCategory,
     title: String(doc.title ?? ""),
-    body: doc.body ? String(doc.body) : undefined,
-    link: doc.link ? String(doc.link) : undefined,
+    // exactOptionalPropertyTypes (#657): only stamp body/link when set
+    // so we don't materialise undefined-valued keys.
+    ...(doc.body ? { body: String(doc.body) } : {}),
+    ...(doc.link ? { link: String(doc.link) } : {}),
     data: (doc.data as Record<string, unknown>) ?? {},
     readAt: doc.readAt ? (doc.readAt instanceof Date ? doc.readAt : new Date(doc.readAt)) : null,
     createdAt: doc.createdAt instanceof Date ? doc.createdAt : new Date(doc.createdAt),
diff --git a/ornn-api/src/domains/notifications/routes.ts b/ornn-api/src/domains/notifications/routes.ts
index d85ebc42..9ea8f9df 100644
--- a/ornn-api/src/domains/notifications/routes.ts
+++ b/ornn-api/src/domains/notifications/routes.ts
@@ -69,8 +69,10 @@ function toFeedDto(item: FeedItem): FeedItemDto {
     userId: item.userId,
     category: item.category,
     title: item.title,
-    body: item.body,
-    link: item.link,
+    // exactOptionalPropertyTypes (#657): conditional spread on
+    // optional body/link.
+    ...(item.body !== undefined ? { body: item.body } : {}),
+    ...(item.link !== undefined ? { link: item.link } : {}),
     data: item.data,
     readAt: item.readAt ? item.readAt.toISOString() : null,
     createdAt: item.createdAt.toISOString(),
@@ -91,7 +93,8 @@ export function createNotificationRoutes(
     const limit = limitParam ? Math.max(1, Math.min(200, Number.parseInt(limitParam, 10))) : undefined;
     const items = await notificationService.listFeedForUser(authCtx.userId, {
       unreadOnly,
-      limit,
+      // exactOptionalPropertyTypes (#657)
+      ...(limit !== undefined ? { limit } : {}),
     });
     return c.json({ data: { items: items.map(toFeedDto) }, error: null });
   });
diff --git a/ornn-api/src/domains/notifications/service.ts b/ornn-api/src/domains/notifications/service.ts
index d618cbc9..0635d486 100644
--- a/ornn-api/src/domains/notifications/service.ts
+++ b/ornn-api/src/domains/notifications/service.ts
@@ -13,14 +13,14 @@
  * @module domains/notifications/service
  */
 
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import { AppError } from "../../shared/types/index";
 import type { BroadcastRepository } from "../broadcasts/repository";
 import type { BroadcastDocument } from "../broadcasts/types";
 import type { NotificationRepository } from "./repository";
 import type { FeedItem, NotificationDocument } from "./types";
 
-const logger = pino({ level: "info" }).child({ module: "notificationService" });
+const logger = createLogger("notificationService");
 
 /**
  * Recipient predicate for broadcasts (#502). `null` recipientUserIds
@@ -106,7 +106,8 @@ export class NotificationService {
     // because the other source had `limit` older items.
     const perUser = await this.repo.list(userId, {
       limit,
-      unreadOnly: options.unreadOnly,
+      // exactOptionalPropertyTypes (#657)
+      ...(options.unreadOnly !== undefined ? { unreadOnly: options.unreadOnly } : {}),
     });
     const userItems: FeedItem[] = perUser.map((n) => ({ ...n, source: "user" }));
 
@@ -197,7 +198,7 @@ export class NotificationService {
         return { source: "broadcast", readAt: receipt.readAt };
       }
     }
-    throw AppError.notFound("NOTIFICATION_NOT_FOUND", "Notification not found");
+    throw AppError.notFound("notification_not_found", "Notification not found");
   }
 
   /**
diff --git a/ornn-api/src/domains/platform/bootstrap.ts b/ornn-api/src/domains/platform/bootstrap.ts
new file mode 100644
index 00000000..08421bd0
--- /dev/null
+++ b/ornn-api/src/domains/platform/bootstrap.ts
@@ -0,0 +1,36 @@
+/**
+ * Wire the legacy platform-settings domain (#580 — bootstrap decomposition).
+ *
+ * This is the pre-#302 single-doc `platform_settings:{_id:"ornn"}`
+ * surface (audit-waiver threshold + legacy mirror config + legacy LLM
+ * override). Backend-engineer-2's multi-section `SettingsService`
+ * replaced most of it; what remains is still consumed by the audit
+ * waiver path + a handful of legacy routes, so we keep this wiring
+ * alive until those sites migrate.
+ *
+ * @module domains/platform/bootstrap
+ */
+
+import type { Db } from "mongodb";
+import type { Hono } from "hono";
+import type { AuthVariables } from "../../middleware/nyxidAuth";
+import { PlatformSettingsRepository } from "./repository";
+import { PlatformSettingsService } from "./service";
+import { createPlatformSettingsRoutes } from "./routes";
+
+export interface PlatformSettingsWiring {
+  readonly service: PlatformSettingsService;
+  readonly routes: Hono<{ Variables: AuthVariables }>;
+}
+
+export function wirePlatformSettings(deps: {
+  db: Db;
+  encryptionKey: string;
+}): PlatformSettingsWiring {
+  const repo = new PlatformSettingsRepository(deps.db);
+  const service = new PlatformSettingsService(repo, {
+    encryptionKey: deps.encryptionKey,
+  });
+  const routes = createPlatformSettingsRoutes({ platformSettingsService: service });
+  return { service, routes };
+}
diff --git a/ornn-api/src/domains/platform/repository.test.ts b/ornn-api/src/domains/platform/repository.test.ts
new file mode 100644
index 00000000..64be7d35
--- /dev/null
+++ b/ornn-api/src/domains/platform/repository.test.ts
@@ -0,0 +1,121 @@
+/**
+ * PlatformSettingsRepository unit tests (#454).
+ *
+ * Singleton document keyed by a fixed `_id`. Pins the partial-shape
+ * contract — fields the admin hasn't touched MUST come back
+ * undefined so the service layer can fall back to configmap
+ * defaults.
+ *
+ * @module domains/platform/repository.test
+ */
+
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+import { MongoClient, type Db } from "mongodb";
+import { MongoMemoryServer } from "mongodb-memory-server";
+import { PlatformSettingsRepository } from "./repository";
+
+let mongo: MongoMemoryServer;
+let client: MongoClient;
+let db: Db;
+let repo: PlatformSettingsRepository;
+
+beforeAll(async () => {
+  mongo = await MongoMemoryServer.create();
+  client = new MongoClient(mongo.getUri());
+  await client.connect();
+  db = client.db("platform_test");
+  repo = new PlatformSettingsRepository(db);
+});
+
+afterAll(async () => {
+  await client.close();
+  await mongo.stop();
+});
+
+beforeEach(async () => {
+  await db.collection("platform_settings").deleteMany({});
+});
+
+describe("get", () => {
+  test("empty collection returns empty object (not defaults)", async () => {
+    const result = await repo.get();
+    // Service layer applies defaults — repo MUST return undefined for
+    // un-touched fields so the merge layer can tell "not set" from
+    // "set to zero".
+    expect(result).toEqual({});
+  });
+
+  test("returns only the fields the admin has set", async () => {
+    await repo.patch({ auditWaiverThreshold: 5 });
+    const result = await repo.get();
+    expect(result.auditWaiverThreshold).toBe(5);
+    expect(result.llmProvider).toBeUndefined();
+  });
+
+  test("normalizes llmProvider field shapes from raw doc", async () => {
+    // Insert a doc with partial llmProvider directly to simulate an
+    // old/corrupted record.
+    await db.collection("platform_settings").insertOne({
+      _id: "ornn" as never,
+      llmProvider: { gatewayUrl: "https://x" },
+    });
+    const result = await repo.get();
+    expect(result.llmProvider).toEqual({ gatewayUrl: "https://x", apiKey: "" });
+  });
+
+  test("ignores wrong-type fields", async () => {
+    // Old data with wrong shape — repo MUST gracefully skip, not crash.
+    await db.collection("platform_settings").insertOne({
+      _id: "ornn" as never,
+      auditWaiverThreshold: "not a number" as unknown as number,
+    });
+    const result = await repo.get();
+    expect(result.auditWaiverThreshold).toBeUndefined();
+  });
+});
+
+describe("patch", () => {
+  test("upserts a fresh document on first patch", async () => {
+    await repo.patch({ auditWaiverThreshold: 7 });
+    const stored = await db.collection("platform_settings").findOne({ _id: "ornn" as never });
+    expect(stored?.auditWaiverThreshold).toBe(7);
+  });
+
+  test("partial patches leave untouched fields alone", async () => {
+    await repo.patch({
+      auditWaiverThreshold: 5,
+      llmProvider: { gatewayUrl: "https://x", apiKey: "enc" },
+    });
+    await repo.patch({ auditWaiverThreshold: 6 });
+    const result = await repo.get();
+    expect(result.auditWaiverThreshold).toBe(6);
+    expect(result.llmProvider).toEqual({ gatewayUrl: "https://x", apiKey: "enc" });
+  });
+
+  test("empty patch is a no-op", async () => {
+    const before = await db.collection("platform_settings").countDocuments();
+    await repo.patch({});
+    const after = await db.collection("platform_settings").countDocuments();
+    expect(after).toBe(before); // No insert happened.
+  });
+
+  test("llmProvider with missing fields fills defaults", async () => {
+    await repo.patch({
+      llmProvider: { gatewayUrl: "https://x", apiKey: "" },
+    });
+    const result = await repo.get();
+    expect(result.llmProvider).toEqual({ gatewayUrl: "https://x", apiKey: "" });
+  });
+
+  test("returns the post-patch state", async () => {
+    const result = await repo.patch({ auditWaiverThreshold: 8 });
+    expect(result.auditWaiverThreshold).toBe(8);
+  });
+});
diff --git a/ornn-api/src/domains/platform/routes.ts b/ornn-api/src/domains/platform/routes.ts
index 9e841334..bf0951d5 100644
--- a/ornn-api/src/domains/platform/routes.ts
+++ b/ornn-api/src/domains/platform/routes.ts
@@ -13,8 +13,10 @@ import {
   nyxidAuthMiddleware,
   requirePermission,
 } from "../../middleware/nyxidAuth";
+import { z } from "zod";
 import { AppError } from "../../shared/types/index";
 import { isMidMaskSentinel, midMaskSecret } from "../../infra/crypto";
+import { validateBody, getValidatedBody } from "../../middleware/validate";
 import type { PlatformSettingsService } from "./service";
 import type { PlatformSettings } from "./types";
 
@@ -50,10 +52,16 @@ export function createPlatformSettingsRoutes(
     return c.json({ data: maskSensitiveSettings(settings), error: null });
   });
 
-  app.patch("/admin/settings", auth, requirePermission("ornn:admin:skill"), async (c) => {
-    const body = (await c.req.json().catch(() => ({}))) as Partial<
-      Record<keyof PlatformSettings, unknown>
-    >;
+  app.patch(
+    "/admin/settings",
+    auth,
+    requirePermission("ornn:admin:skill"),
+    // The downstream field-by-field checks below enforce the proper
+    // shape per key; this gate just turns a SyntaxError into a clean
+    // 400 invalid_body (#438).
+    validateBody(z.record(z.string(), z.unknown()), "invalid_body"),
+    async (c) => {
+      const body = getValidatedBody<Partial<Record<keyof PlatformSettings, unknown>>>(c);
     type MutablePatch = { -readonly [K in keyof PlatformSettings]?: PlatformSettings[K] };
     const patch: MutablePatch = {};
 
@@ -61,7 +69,7 @@ export function createPlatformSettingsRoutes(
       const n = Number(body.auditWaiverThreshold);
       if (!Number.isFinite(n) || n < 0 || n > 10) {
         throw AppError.badRequest(
-          "INVALID_SETTING",
+          "invalid_setting",
           "'auditWaiverThreshold' must be a number between 0 and 10",
         );
       }
@@ -72,7 +80,7 @@ export function createPlatformSettingsRoutes(
       const lp = body.llmProvider;
       if (!lp || typeof lp !== "object") {
         throw AppError.badRequest(
-          "INVALID_SETTING",
+          "invalid_setting",
           "'llmProvider' must be an object with optional gatewayUrl + apiKey",
         );
       }
@@ -83,7 +91,7 @@ export function createPlatformSettingsRoutes(
         const u = lpObj.gatewayUrl;
         if (typeof u !== "string") {
           throw AppError.badRequest(
-            "INVALID_SETTING",
+            "invalid_setting",
             "'llmProvider.gatewayUrl' must be a string (empty = use env default)",
           );
         }
@@ -93,7 +101,7 @@ export function createPlatformSettingsRoutes(
             new URL(trimmed); // validate
           } catch {
             throw AppError.badRequest(
-              "INVALID_SETTING",
+              "invalid_setting",
               "'llmProvider.gatewayUrl' must be a valid URL",
             );
           }
@@ -109,7 +117,7 @@ export function createPlatformSettingsRoutes(
         const k = lpObj.apiKey;
         if (typeof k !== "string") {
           throw AppError.badRequest(
-            "INVALID_SETTING",
+            "invalid_setting",
             "'llmProvider.apiKey' must be a string (empty = clear)",
           );
         }
@@ -131,12 +139,13 @@ export function createPlatformSettingsRoutes(
     }
 
     if (Object.keys(patch).length === 0) {
-      throw AppError.badRequest("INVALID_SETTING", "No valid setting fields in body");
+      throw AppError.badRequest("invalid_setting", "No valid setting fields in body");
     }
 
-    const updated = await platformSettingsService.patch(patch);
-    return c.json({ data: maskSensitiveSettings(updated), error: null });
-  });
+      const updated = await platformSettingsService.patch(patch);
+      return c.json({ data: maskSensitiveSettings(updated), error: null });
+    },
+  );
 
   return app;
 }
diff --git a/ornn-api/src/domains/platform/service.test.ts b/ornn-api/src/domains/platform/service.test.ts
new file mode 100644
index 00000000..deec5df5
--- /dev/null
+++ b/ornn-api/src/domains/platform/service.test.ts
@@ -0,0 +1,164 @@
+/**
+ * PlatformSettingsService unit tests (#454).
+ *
+ * Pins the cache contract + the at-rest encryption boundary (`apiKey`
+ * is plaintext above the service, ciphertext below). Failures of the
+ * crypto layer MUST degrade gracefully — an unreadable secret returns
+ * empty string, not a throw, so the rest of the system keeps working.
+ *
+ * @module domains/platform/service.test
+ */
+
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+import { MongoClient, type Db } from "mongodb";
+import { MongoMemoryServer } from "mongodb-memory-server";
+import { PlatformSettingsRepository } from "./repository";
+import { PlatformSettingsService } from "./service";
+
+const ENCRYPTION_KEY = "test-encryption-key-32-chars-min-12345";
+
+let mongo: MongoMemoryServer;
+let client: MongoClient;
+let db: Db;
+let service: PlatformSettingsService;
+let repo: PlatformSettingsRepository;
+
+beforeAll(async () => {
+  mongo = await MongoMemoryServer.create();
+  client = new MongoClient(mongo.getUri());
+  await client.connect();
+  db = client.db("platform_service_test");
+  repo = new PlatformSettingsRepository(db);
+});
+
+afterAll(async () => {
+  await client.close();
+  await mongo.stop();
+});
+
+beforeEach(async () => {
+  await db.collection("platform_settings").deleteMany({});
+  // Fresh service per test so the in-memory cache doesn't leak between cases.
+  service = new PlatformSettingsService(repo, { encryptionKey: ENCRYPTION_KEY });
+});
+
+describe("get", () => {
+  test("returns defaults when nothing has been set", async () => {
+    const s = await service.get();
+    expect(s.auditWaiverThreshold).toBeDefined();
+    expect(s.llmProvider).toBeDefined();
+    expect(s.llmProvider.apiKey).toBe(""); // No real key yet
+  });
+
+  test("returns admin-set values when present", async () => {
+    await service.patch({ auditWaiverThreshold: 7 });
+    const s = await service.get();
+    expect(s.auditWaiverThreshold).toBe(7);
+  });
+});
+
+describe("patch + encryption", () => {
+  test("apiKey is stored as ciphertext, never plaintext", async () => {
+    await service.patch({
+      llmProvider: { gatewayUrl: "https://gw.test", apiKey: "secret-plaintext" },
+    });
+    const stored = await db.collection("platform_settings").findOne({ _id: "ornn" as never });
+    // Cipher MUST NOT contain plaintext.
+    expect(String(stored?.llmProvider?.apiKey ?? "")).not.toContain("secret-plaintext");
+    expect((stored?.llmProvider?.apiKey ?? "").length).toBeGreaterThan(0);
+  });
+
+  test("get() round-trips apiKey plaintext through encryption", async () => {
+    await service.patch({
+      llmProvider: { gatewayUrl: "https://gw.test", apiKey: "round-trip-secret" },
+    });
+    const s = await service.get();
+    expect(s.llmProvider.apiKey).toBe("round-trip-secret");
+  });
+
+  test("get() returns empty apiKey when decrypt fails (graceful degrade)", async () => {
+    // Write a malformed v1 ciphertext (enc:1: prefix but garbage
+    // payload) so decryptSecret throws. Plain-string values without
+    // the prefix are passed through as legacy compat (separate path).
+    await db.collection("platform_settings").updateOne(
+      { _id: "ornn" as never },
+      {
+        $set: {
+          llmProvider: {
+            gatewayUrl: "https://gw.test",
+            apiKey: "v1:notIV:notTag:notCipher",
+          },
+        },
+        $setOnInsert: { _id: "ornn" },
+      },
+      { upsert: true },
+    );
+    // Fresh service (no cache); should NOT throw, just yield "".
+    const fresh = new PlatformSettingsService(repo, { encryptionKey: ENCRYPTION_KEY });
+    const s = await fresh.get();
+    expect(s.llmProvider.apiKey).toBe("");
+    expect(s.llmProvider.gatewayUrl).toBe("https://gw.test");
+  });
+
+  test("get() passes through pre-encryption legacy plaintext (no `enc:` prefix)", async () => {
+    // Pre-encryption rows have raw plaintext in apiKey. decryptSecret
+    // returns those unchanged so the migration to encrypted-at-rest
+    // doesn't lock operators out of working configs.
+    await db.collection("platform_settings").updateOne(
+      { _id: "ornn" as never },
+      {
+        $set: {
+          llmProvider: { gatewayUrl: "https://gw.test", apiKey: "legacy-plaintext" },
+        },
+        $setOnInsert: { _id: "ornn" },
+      },
+      { upsert: true },
+    );
+    const fresh = new PlatformSettingsService(repo, { encryptionKey: ENCRYPTION_KEY });
+    expect((await fresh.get()).llmProvider.apiKey).toBe("legacy-plaintext");
+  });
+});
+
+describe("cache", () => {
+  test("repeat get() within TTL doesn't re-hit Mongo", async () => {
+    await service.patch({ auditWaiverThreshold: 5 });
+    const s1 = await service.get();
+    // Tamper with the DB directly — service should NOT see the change
+    // until cache expires.
+    await db
+      .collection("platform_settings")
+      .updateOne({ _id: "ornn" as never }, { $set: { auditWaiverThreshold: 999 } });
+    const s2 = await service.get();
+    expect(s2.auditWaiverThreshold).toBe(s1.auditWaiverThreshold);
+  });
+
+  test("patch() busts the cache", async () => {
+    await service.patch({ auditWaiverThreshold: 5 });
+    expect((await service.get()).auditWaiverThreshold).toBe(5);
+    await service.patch({ auditWaiverThreshold: 9 });
+    expect((await service.get()).auditWaiverThreshold).toBe(9);
+  });
+});
+
+describe("convenience accessors", () => {
+  test("getAuditWaiverThreshold reads from the merged shape", async () => {
+    await service.patch({ auditWaiverThreshold: 3 });
+    expect(await service.getAuditWaiverThreshold()).toBe(3);
+  });
+
+  test("getLlmProviderConfig returns the decrypted plaintext shape", async () => {
+    await service.patch({
+      llmProvider: { gatewayUrl: "https://x.test", apiKey: "k" },
+    });
+    const cfg = await service.getLlmProviderConfig();
+    expect(cfg.gatewayUrl).toBe("https://x.test");
+    expect(cfg.apiKey).toBe("k");
+  });
+});
diff --git a/ornn-api/src/domains/platform/service.ts b/ornn-api/src/domains/platform/service.ts
index 0986c8df..7a0369f2 100644
--- a/ornn-api/src/domains/platform/service.ts
+++ b/ornn-api/src/domains/platform/service.ts
@@ -15,7 +15,7 @@
  *
  * @module domains/platform/service
  */
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import { decryptSecret, encryptSecret } from "../../infra/crypto";
 import type { PlatformSettingsRepository } from "./repository";
 import {
@@ -24,7 +24,7 @@ import {
   type PlatformSettings,
 } from "./types";
 
-const logger = pino({ level: "info" }).child({ module: "platformSettingsService" });
+const logger = createLogger("platformSettingsService");
 
 export interface PlatformSettingsDefaults {
   /**
diff --git a/ornn-api/src/domains/playground/bootstrap.ts b/ornn-api/src/domains/playground/bootstrap.ts
new file mode 100644
index 00000000..12b4f95b
--- /dev/null
+++ b/ornn-api/src/domains/playground/bootstrap.ts
@@ -0,0 +1,59 @@
+/**
+ * Wire the playground domain (#580 — bootstrap decomposition).
+ *
+ * Playground has the heaviest downstream dep list of the LLM-driven
+ * domains: chat service needs the llmClient + sandboxClient +
+ * skillService + surface defaults; routes additionally mount
+ * analyticsService (every chat completion fires a `chat.completed`
+ * event), quotaService (every call charges the playground bucket),
+ * and llmProvidersService (the picker behind the SSE init event).
+ *
+ * @module domains/playground/bootstrap
+ */
+
+import type { Hono } from "hono";
+import type { AuthVariables } from "../../middleware/nyxidAuth";
+import { PlaygroundChatService } from "./chatService";
+import { createPlaygroundRoutes } from "./routes";
+import type { NyxLlmClient } from "../../clients/nyxid/llm";
+import type { SandboxClient } from "../../clients/sandboxClient";
+import type { SkillService } from "../skills/crud/service";
+import type { AnalyticsService } from "../analytics/service";
+import type { QuotaService } from "../quota/service";
+import type { LlmProvidersService } from "../settings/llmProviders/service";
+
+export interface PlaygroundWiring {
+  readonly chatService: PlaygroundChatService;
+  readonly routes: Hono<{ Variables: AuthVariables }>;
+}
+
+export function wirePlayground(deps: {
+  llmClient: NyxLlmClient;
+  sandboxClient: SandboxClient;
+  skillService: SkillService;
+  defaultsResolver: () => Promise<{
+    model: string;
+    maxOutputTokens: number;
+    temperature: number;
+  }>;
+  keepAliveIntervalMsResolver: () => Promise<number>;
+  analyticsService: AnalyticsService;
+  quotaService: QuotaService;
+  llmProvidersService: LlmProvidersService;
+}): PlaygroundWiring {
+  const chatService = new PlaygroundChatService({
+    llmClient: deps.llmClient,
+    sandboxClient: deps.sandboxClient,
+    skillService: deps.skillService,
+    defaultsResolver: deps.defaultsResolver,
+  });
+  const routes = createPlaygroundRoutes({
+    chatService,
+    keepAliveIntervalMsResolver: deps.keepAliveIntervalMsResolver,
+    analyticsService: deps.analyticsService,
+    skillService: deps.skillService,
+    quotaService: deps.quotaService,
+    llmProvidersService: deps.llmProvidersService,
+  });
+  return { chatService, routes };
+}
diff --git a/ornn-api/src/domains/playground/chatService.test.ts b/ornn-api/src/domains/playground/chatService.test.ts
new file mode 100644
index 00000000..9debb17f
--- /dev/null
+++ b/ornn-api/src/domains/playground/chatService.test.ts
@@ -0,0 +1,384 @@
+/**
+ * Tests for #531: PlaygroundChatService must reuse a per-language
+ * chrono-sandbox session across tool-use rounds in one chat so
+ * installed CLIs, env writes, and filesystem state survive between
+ * successive `execute_in_sandbox` tool calls.
+ *
+ * Scope:
+ * - First execute_in_sandbox call creates one session and uses
+ *   sessionExecute (NOT the one-shot /execute endpoint).
+ * - Same-language follow-up calls hit sessionExecute with the same
+ *   session id — no second createSession.
+ * - Different-language call creates a second session.
+ * - Sessions are cleaned up in the finally block.
+ * - createSession failure transparently falls back to one-shot execute
+ *   so the playground stays usable even if the session layer is down.
+ * - sessionExecute failure drops the stale session and falls back to
+ *   one-shot execute for that round.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { PlaygroundChatService } from "./chatService";
+import type {
+  CreateSessionParams,
+  SandboxExecuteParams,
+  SandboxExecuteResult,
+  SessionExecuteParams,
+  SessionResponse,
+} from "../../clients/sandboxClient";
+import type {
+  NyxLlmClient,
+  NyxLlmStreamParams,
+  ResponsesApiStreamEvent,
+} from "../../clients/nyxid/llm";
+import type { SkillService } from "../skills/crud/service";
+import type { PlaygroundChatEvent } from "../../shared/types/index";
+
+// ---------------------------------------------------------------------------
+// Stubs
+// ---------------------------------------------------------------------------
+
+interface ToolCallSpec {
+  name: string;
+  args: Record<string, unknown>;
+  id?: string;
+}
+
+function makeToolCallEvents(spec: ToolCallSpec): ResponsesApiStreamEvent[] {
+  return [
+    {
+      type: "response.output_item.done",
+      item: {
+        type: "function_call",
+        id: spec.id ?? `call-${spec.name}-${Math.random().toString(36).slice(2, 8)}`,
+        call_id: spec.id ?? `call-${spec.name}-${Math.random().toString(36).slice(2, 8)}`,
+        name: spec.name,
+        arguments: JSON.stringify(spec.args),
+      },
+    },
+  ];
+}
+
+const STOP_EVENTS: ResponsesApiStreamEvent[] = [
+  { type: "response.output_text.delta", delta: "done" },
+];
+
+/** Per-round event sequence — pops on each `.stream()` invocation. */
+function makeLlmClient(rounds: ResponsesApiStreamEvent[][]): NyxLlmClient {
+  const queue = [...rounds];
+  return {
+    async *stream(_params: NyxLlmStreamParams): AsyncIterable<ResponsesApiStreamEvent> {
+      const events = queue.shift() ?? STOP_EVENTS;
+      for (const e of events) yield e;
+    },
+    complete: (async () => []) as NyxLlmClient["complete"],
+  } as unknown as NyxLlmClient;
+}
+
+const SKILL_SERVICE_STUB: SkillService = {
+  getSkillJson: async () => ({ name: "stub", description: "", metadata: {}, files: {} }),
+} as unknown as SkillService;
+
+const DEFAULTS_RESOLVER = async () => ({
+  model: "test-model",
+  maxOutputTokens: 256,
+  temperature: 0.5,
+});
+
+interface SandboxCalls {
+  createSession: Array<{ params: CreateSessionParams }>;
+  sessionExecute: Array<{ sessionId: string; params: SessionExecuteParams }>;
+  execute: Array<{ params: SandboxExecuteParams }>;
+  deleteSession: string[];
+}
+
+function makeSandboxClient(opts: {
+  failCreate?: boolean;
+  failSessionExecute?: boolean;
+}): { client: NonNullable<unknown>; calls: SandboxCalls } {
+  const calls: SandboxCalls = {
+    createSession: [],
+    sessionExecute: [],
+    execute: [],
+    deleteSession: [],
+  };
+  let nextSessionId = 0;
+  const okResult: SandboxExecuteResult = {
+    success: true,
+    output: { stdout: "", stderr: "", exit_code: 0, display_data: [], execution_time_ms: 1 },
+  };
+
+  const client = {
+    async createSession(params: CreateSessionParams): Promise<SessionResponse> {
+      calls.createSession.push({ params });
+      if (opts.failCreate) throw new Error("simulated createSession failure");
+      const session_id = `sess-${++nextSessionId}`;
+      return { session_id, status: "ready", expires_at: Date.now() + 600_000 };
+    },
+    async sessionExecute(
+      sessionId: string,
+      params: SessionExecuteParams,
+    ): Promise<SandboxExecuteResult> {
+      calls.sessionExecute.push({ sessionId, params });
+      if (opts.failSessionExecute) throw new Error("simulated sessionExecute failure");
+      return okResult;
+    },
+    async execute(params: SandboxExecuteParams): Promise<SandboxExecuteResult> {
+      calls.execute.push({ params });
+      return okResult;
+    },
+    async deleteSession(sessionId: string): Promise<void> {
+      calls.deleteSession.push(sessionId);
+    },
+    async *executeStream() { /* unused */ },
+    async *sessionExecuteStream() { /* unused */ },
+    async listSessions() { return { sessions: [] }; },
+  };
+
+  return { client, calls };
+}
+
+async function drain(stream: AsyncIterable<PlaygroundChatEvent>): Promise<PlaygroundChatEvent[]> {
+  const events: PlaygroundChatEvent[] = [];
+  for await (const e of stream) events.push(e);
+  return events;
+}
+
+function makeService(
+  llmRounds: ResponsesApiStreamEvent[][],
+  sandbox: ReturnType<typeof makeSandboxClient>,
+): PlaygroundChatService {
+  return new PlaygroundChatService({
+    llmClient: makeLlmClient(llmRounds),
+    sandboxClient: sandbox.client as never,
+    skillService: SKILL_SERVICE_STUB,
+    defaultsResolver: DEFAULTS_RESOLVER,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// #531 — session reuse across same-language sandbox calls
+// ---------------------------------------------------------------------------
+
+describe("PlaygroundChatService — sandbox session persistence (#531)", () => {
+  it("first execute_in_sandbox call creates one session and uses sessionExecute (not one-shot)", async () => {
+    const sandbox = makeSandboxClient({});
+    const service = makeService(
+      [
+        makeToolCallEvents({
+          name: "execute_in_sandbox",
+          args: { script: "console.log('hi')", language: "javascript", dependencies: ["axios"] },
+        }),
+        STOP_EVENTS,
+      ],
+      sandbox,
+    );
+
+    await drain(service.chat("u1", { messages: [{ role: "user", content: "go" }] }));
+
+    expect(sandbox.calls.createSession).toHaveLength(1);
+    expect(sandbox.calls.createSession[0]!.params).toMatchObject({
+      language: "javascript",
+      dependencies: ["axios"],
+    });
+    expect(sandbox.calls.sessionExecute).toHaveLength(1);
+    expect(sandbox.calls.sessionExecute[0]!.sessionId).toBe("sess-1");
+    expect(sandbox.calls.execute).toHaveLength(0);
+  });
+
+  it("two same-language calls reuse one session — only one createSession", async () => {
+    const sandbox = makeSandboxClient({});
+    const service = makeService(
+      [
+        makeToolCallEvents({ name: "execute_in_sandbox", args: { script: "step 1", language: "python" } }),
+        makeToolCallEvents({ name: "execute_in_sandbox", args: { script: "step 2", language: "python" } }),
+        STOP_EVENTS,
+      ],
+      sandbox,
+    );
+
+    await drain(service.chat("u1", { messages: [{ role: "user", content: "go" }] }));
+
+    expect(sandbox.calls.createSession).toHaveLength(1);
+    expect(sandbox.calls.sessionExecute).toHaveLength(2);
+    expect(sandbox.calls.sessionExecute.every((c) => c.sessionId === "sess-1")).toBe(true);
+    expect(sandbox.calls.sessionExecute.map((c) => c.params.script)).toEqual(["step 1", "step 2"]);
+    expect(sandbox.calls.execute).toHaveLength(0);
+  });
+
+  it("different languages get separate sessions", async () => {
+    const sandbox = makeSandboxClient({});
+    const service = makeService(
+      [
+        makeToolCallEvents({ name: "execute_in_sandbox", args: { script: "js", language: "javascript" } }),
+        makeToolCallEvents({ name: "execute_in_sandbox", args: { script: "py", language: "python" } }),
+        STOP_EVENTS,
+      ],
+      sandbox,
+    );
+
+    await drain(service.chat("u1", { messages: [{ role: "user", content: "go" }] }));
+
+    expect(sandbox.calls.createSession).toHaveLength(2);
+    expect(sandbox.calls.createSession.map((c) => c.params.language)).toEqual(["javascript", "python"]);
+    expect(sandbox.calls.sessionExecute).toHaveLength(2);
+    expect(sandbox.calls.sessionExecute.map((c) => c.sessionId)).toEqual(["sess-1", "sess-2"]);
+  });
+
+  it("sessions are deleted in the finally block at end of chat", async () => {
+    const sandbox = makeSandboxClient({});
+    const service = makeService(
+      [
+        makeToolCallEvents({ name: "execute_in_sandbox", args: { script: "x", language: "python" } }),
+        STOP_EVENTS,
+      ],
+      sandbox,
+    );
+
+    await drain(service.chat("u1", { messages: [{ role: "user", content: "go" }] }));
+
+    expect(sandbox.calls.deleteSession).toEqual(["sess-1"]);
+  });
+
+  it("createSession failure falls back to one-shot /execute — no crash", async () => {
+    const sandbox = makeSandboxClient({ failCreate: true });
+    const service = makeService(
+      [
+        makeToolCallEvents({
+          name: "execute_in_sandbox",
+          args: { script: "x", language: "javascript", dependencies: ["lodash"] },
+        }),
+        STOP_EVENTS,
+      ],
+      sandbox,
+    );
+
+    const events = await drain(service.chat("u1", { messages: [{ role: "user", content: "go" }] }));
+
+    expect(sandbox.calls.createSession).toHaveLength(1);
+    expect(sandbox.calls.sessionExecute).toHaveLength(0);
+    expect(sandbox.calls.execute).toHaveLength(1);
+    expect(sandbox.calls.execute[0]!.params).toMatchObject({
+      language: "javascript",
+      dependencies: ["lodash"],
+      script: "x",
+    });
+    expect(sandbox.calls.deleteSession).toEqual([]);
+    expect(events.some((e) => e.type === "tool-result")).toBe(true);
+  });
+
+  it("sessionExecute failure drops the stale session and falls back to one-shot", async () => {
+    const sandbox = makeSandboxClient({ failSessionExecute: true });
+    const service = makeService(
+      [
+        makeToolCallEvents({ name: "execute_in_sandbox", args: { script: "x", language: "python" } }),
+        STOP_EVENTS,
+      ],
+      sandbox,
+    );
+
+    await drain(service.chat("u1", { messages: [{ role: "user", content: "go" }] }));
+
+    expect(sandbox.calls.createSession).toHaveLength(1);
+    expect(sandbox.calls.sessionExecute).toHaveLength(1);
+    expect(sandbox.calls.execute).toHaveLength(1);
+  });
+
+  it("plain (non-sandbox) chats create no sessions", async () => {
+    const sandbox = makeSandboxClient({});
+    const service = makeService([STOP_EVENTS], sandbox);
+
+    await drain(service.chat("u1", { messages: [{ role: "user", content: "hi" }] }));
+
+    expect(sandbox.calls.createSession).toHaveLength(0);
+    expect(sandbox.calls.sessionExecute).toHaveLength(0);
+    expect(sandbox.calls.execute).toHaveLength(0);
+    expect(sandbox.calls.deleteSession).toHaveLength(0);
+  });
+
+  it("deleteSession failure does not surface to the caller", async () => {
+    const sandbox = makeSandboxClient({});
+    // Force deleteSession to throw on the one created session.
+    const originalDelete = (sandbox.client as { deleteSession: (id: string) => Promise<void> }).deleteSession;
+    (sandbox.client as { deleteSession: (id: string) => Promise<void> }).deleteSession = async (id) => {
+      sandbox.calls.deleteSession.push(id);
+      throw new Error("simulated delete failure");
+    };
+
+    const service = makeService(
+      [
+        makeToolCallEvents({ name: "execute_in_sandbox", args: { script: "x", language: "python" } }),
+        STOP_EVENTS,
+      ],
+      sandbox,
+    );
+
+    // Should complete without throwing despite the delete failure.
+    const events = await drain(service.chat("u1", { messages: [{ role: "user", content: "go" }] }));
+    expect(events.some((e) => e.type === "finish")).toBe(true);
+    expect(sandbox.calls.deleteSession).toEqual(["sess-1"]);
+    // Restore in case the test runner shares state.
+    (sandbox.client as { deleteSession: (id: string) => Promise<void> }).deleteSession = originalDelete;
+  });
+});
+
+// ---------------------------------------------------------------------------
+// #721 — user-supplied env values must not flow through the LLM
+// ---------------------------------------------------------------------------
+
+describe("PlaygroundChatService — env value isolation (#721)", () => {
+  it("user-provided envVars override the model's args.env at sandbox-execute time", async () => {
+    const sandbox = makeSandboxClient({});
+    const service = makeService(
+      [
+        makeToolCallEvents({
+          name: "execute_in_sandbox",
+          args: {
+            script: "print(env)",
+            language: "python",
+            // Simulate a model that emitted a guessed/leaky value.
+            env: { SECRET_TOKEN: "model-guessed-value", PUBLIC_FLAG: "model-set" },
+          },
+        }),
+        STOP_EVENTS,
+      ],
+      sandbox,
+    );
+
+    await drain(
+      service.chat(
+        "u1",
+        {
+          messages: [{ role: "user", content: "go" }],
+          envVars: { SECRET_TOKEN: "REAL_SECRET_FROM_UI" },
+        },
+      ),
+    );
+
+    expect(sandbox.calls.sessionExecute).toHaveLength(1);
+    const envSeen = sandbox.calls.sessionExecute[0]!.params.env as Record<string, string>;
+    // Real value wins over model-supplied placeholder.
+    expect(envSeen.SECRET_TOKEN).toBe("REAL_SECRET_FROM_UI");
+    // Keys the user didn't override ride through.
+    expect(envSeen.PUBLIC_FLAG).toBe("model-set");
+  });
+
+  it("no envVars passed → sandbox env is exactly what the model produced", async () => {
+    const sandbox = makeSandboxClient({});
+    const service = makeService(
+      [
+        makeToolCallEvents({
+          name: "execute_in_sandbox",
+          args: { script: "x", language: "python", env: { MARKER: "test123" } },
+        }),
+        STOP_EVENTS,
+      ],
+      sandbox,
+    );
+
+    await drain(service.chat("u1", { messages: [{ role: "user", content: "go" }] }));
+
+    const envSeen = sandbox.calls.sessionExecute[0]!.params.env as Record<string, string>;
+    expect(envSeen).toEqual({ MARKER: "test123" });
+  });
+});
diff --git a/ornn-api/src/domains/playground/chatService.ts b/ornn-api/src/domains/playground/chatService.ts
index 4c839b28..d0e22582 100644
--- a/ornn-api/src/domains/playground/chatService.ts
+++ b/ornn-api/src/domains/playground/chatService.ts
@@ -11,12 +11,130 @@ import type {
   ResponsesApiInputMessage,
   ResponsesApiTool,
 } from "../../clients/nyxid/llm";
-import type { SandboxClient } from "../../clients/sandboxClient";
+import type {
+  SandboxClient,
+  SandboxExecuteResult,
+} from "../../clients/sandboxClient";
 import type { SkillService } from "../skills/crud/service";
 import type { PlaygroundChatEvent } from "../../shared/types/index";
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
+import { z } from "zod";
+
+const logger = createLogger("playgroundChatService");
 
-const logger = pino({ level: "info" }).child({ module: "playgroundChatService" });
+/**
+ * Zod schemas for the four LLM Responses-API event shapes we
+ * consume on the playground stream (#449). `as any` previously
+ * propagated unchecked field renames upstream into `undefined`
+ * flowing through SSE; with a discriminated union we ignore
+ * malformed events explicitly and log them.
+ *
+ * Schemas are intentionally permissive — only fields we read are
+ * required; the upstream API may add fields freely without
+ * breaking us.
+ */
+const textDeltaEventSchema = z.object({
+  type: z.literal("response.output_text.delta"),
+  delta: z.string(),
+});
+
+const contentPartDeltaEventSchema = z.object({
+  type: z.literal("response.content_part.delta"),
+  delta: z.object({
+    type: z.string().optional(),
+    text: z.string().optional(),
+  }).optional(),
+});
+
+const outputItemDoneEventSchema = z.object({
+  type: z.literal("response.output_item.done"),
+  item: z.object({
+    type: z.string().optional(),
+    id: z.string().optional(),
+    call_id: z.string().optional(),
+    name: z.string().optional(),
+    arguments: z.string().optional(),
+  }).optional(),
+});
+
+const anyKnownEventSchema = z.union([
+  textDeltaEventSchema,
+  contentPartDeltaEventSchema,
+  outputItemDoneEventSchema,
+]);
+
+/** Server-side tool-call return shape consumed by the playground stream. */
+interface ToolCallResult {
+  text: string;
+  files: Array<{ path: string; content: string; size: number; mimeType: string }>;
+}
+
+/**
+ * Translate a thrown error from `sandboxClient.{execute,sessionExecute}`
+ * into a user-facing one-liner for the playground transcript (#530).
+ *
+ * `SandboxClient.post` throws an `Error` whose message is
+ * `"Sandbox service error (<status>): <raw body text>"`. The raw body
+ * is often an `{ error, error_code, message }` JSON envelope from
+ * chrono-sandbox; the legacy formatter spat that JSON straight into
+ * the chat. Try to parse the body — if it's the structured envelope
+ * we surface a friendly sentence plus an internal-code hint admins
+ * can grep on. Otherwise fall back to the raw message so any new
+ * upstream shape still makes it to the operator.
+ */
+function formatSandboxError(err: unknown): string {
+  const raw = err instanceof Error ? err.message : String(err);
+  const match = raw.match(/^Sandbox service error \((\d+)\): (.*)$/s);
+  if (!match) return `Sandbox execution failed: ${raw}`;
+  const status = match[1]!;
+  const body = match[2]!;
+  try {
+    const parsed = JSON.parse(body) as {
+      error?: string;
+      error_code?: number;
+      message?: string;
+    };
+    const codeHint =
+      typeof parsed.error_code === "number" ? ` [code ${parsed.error_code}]` : "";
+    const summary = parsed.message ?? parsed.error ?? `HTTP ${status}`;
+    if (status === "500" || (parsed.error_code === 1006)) {
+      return `Sandbox is having trouble running this script${codeHint}. This is usually a transient sandbox-server issue — try again, or simplify the script if it keeps failing.`;
+    }
+    if (status === "504" || status === "503") {
+      return `Sandbox timed out / temporarily unavailable${codeHint}. Try again in a few seconds.`;
+    }
+    return `Sandbox execution failed (HTTP ${status})${codeHint}: ${summary}`;
+  } catch {
+    return `Sandbox execution failed (HTTP ${status}): ${body.slice(0, 200)}`;
+  }
+}
+
+/**
+ * Translate a chrono-sandbox `SandboxExecuteResult` (both /execute and
+ * /sessions/{id}/execute return this shape) into the {text, files}
+ * envelope the playground stream feeds back to the LLM and emits as
+ * `file-output` events to the client.
+ */
+function formatSandboxResult(result: SandboxExecuteResult): ToolCallResult {
+  const files = (result.output?.files ?? [])
+    .filter((f): f is typeof f & { content: string } => !!f.content && !f.error)
+    .map((f) => ({
+      path: f.path,
+      content: f.content,
+      size: f.size ?? 0,
+      mimeType: guessMimeType(f.path),
+    }));
+
+  const filesSummary = files.length > 0
+    ? `\nFiles retrieved: ${files.map((f) => `${f.path} (${f.size} bytes)`).join(", ")}`
+    : "";
+
+  const text = result.success
+    ? `Execution succeeded (exit code ${result.output?.exit_code}).\nstdout:\n${result.output?.stdout ?? ""}\nstderr:\n${result.output?.stderr ?? ""}${filesSummary}`
+    : `Execution failed: ${result.error?.message ?? "unknown error"}\nstdout:\n${result.output?.stdout ?? ""}\nstderr:\n${result.output?.stderr ?? ""}`;
+
+  return { text, files };
+}
 
 /** Guess MIME type from file extension. */
 function guessMimeType(path: string): string {
@@ -62,14 +180,19 @@ Be concise. Act, don't explain.`;
 export interface PlaygroundMessage {
   role: "user" | "assistant" | "tool" | "system";
   content: string;
-  toolCalls?: Array<{ id: string; name: string; args: Record<string, unknown> }>;
-  toolCallId?: string;
+  toolCalls?: Array<{ id: string; name: string; args: Record<string, unknown> }> | undefined;
+  toolCallId?: string | undefined;
 }
 
+// Optionals widen to `T | undefined` so the Zod-inferred shape from the
+// validated request body assigns cleanly under exactOptionalPropertyTypes
+// (#657). The fields are still semantically optional; only the type
+// boundary widens.
 export interface PlaygroundChatRequest {
   messages: PlaygroundMessage[];
-  skillId?: string;
-  envVars?: Record<string, string>;
+  skillId?: string | undefined;
+  envVars?: Record<string, string> | undefined;
+  modelId?: string | undefined;
 }
 
 /** Tools for the playground agent. */
@@ -239,158 +362,316 @@ export class PlaygroundChatService {
       }
     }
 
-    // Tool-use loop: stream LLM → if tool call → execute → feed result → stream again
-    const MAX_TOOL_ROUNDS = 5;
-    for (let round = 0; round <= MAX_TOOL_ROUNDS; round++) {
-      try {
-        const streamEvents = this.llmClient.stream({
-          model,
-          input,
-          max_output_tokens: defaults.maxOutputTokens,
-          temperature: defaults.temperature,
-          tools: PLAYGROUND_TOOLS,
-        });
-
-        let pendingToolCall: { id: string; name: string; args: Record<string, unknown> } | null = null;
+    // Per-chat sandbox session reuse (#531). Same-language tool calls
+    // within one chat share a persistent kernel — installed CLIs,
+    // filesystem state, and env survive across rounds. Sessions are
+    // created lazily on first execute_in_sandbox call and torn down
+    // best-effort in `finally`. Keyed by language because chrono-sandbox
+    // kernels are per-language; a TS skill and a Python skill in the
+    // same chat each get their own session.
+    const sandboxSessions = new Map<string, string>();
+    const createdSessionIds: string[] = [];
 
-        for await (const event of streamEvents) {
-          if (abortSignal?.aborted) {
-            yield { type: "error", message: "Request aborted" };
-            yield { type: "finish", finishReason: "abort" };
-            return;
-          }
+    try {
+      // Tool-use loop: stream LLM → if tool call → execute → feed result → stream again
+      const MAX_TOOL_ROUNDS = 5;
+      for (let round = 0; round <= MAX_TOOL_ROUNDS; round++) {
+        try {
+          const streamEvents = this.llmClient.stream({
+            model,
+            input,
+            max_output_tokens: defaults.maxOutputTokens,
+            temperature: defaults.temperature,
+            tools: PLAYGROUND_TOOLS,
+          });
+
+          let pendingToolCall: { id: string; name: string; args: Record<string, unknown> } | null = null;
+
+          for await (const event of streamEvents) {
+            if (abortSignal?.aborted) {
+              yield { type: "error", message: "Request aborted" };
+              yield { type: "finish", finishReason: "abort" };
+              return;
+            }
 
-          const eventType = (event as any).type;
+            // #449 — parse with a discriminated Zod union instead of
+            // `as any`. Unknown event types are ignored (forward-compat
+            // with new upstream events); shape-mismatch on a known event
+            // logs at debug and is dropped.
+            const parsed = anyKnownEventSchema.safeParse(event);
+            if (!parsed.success) {
+              logger.debug(
+                { issues: parsed.error.issues.slice(0, 2) },
+                "Unrecognized LLM event shape — dropping",
+              );
+              continue;
+            }
+            const parsedEvent = parsed.data;
 
-          // Stream text deltas to client
-          if (eventType === "response.output_text.delta") {
-            const delta = (event as any).delta;
-            if (typeof delta === "string") yield { type: "text-delta", delta };
-            continue;
-          }
-          if (eventType === "response.content_part.delta") {
-            const delta = (event as any).delta;
-            if (delta?.type === "output_text" && typeof delta.text === "string") {
-              yield { type: "text-delta", delta: delta.text };
+            // Stream text deltas to client
+            if (parsedEvent.type === "response.output_text.delta") {
+              yield { type: "text-delta", delta: parsedEvent.delta };
+              continue;
+            }
+            if (parsedEvent.type === "response.content_part.delta") {
+              const delta = parsedEvent.delta;
+              if (delta?.type === "output_text" && typeof delta.text === "string") {
+                yield { type: "text-delta", delta: delta.text };
+              }
+              continue;
             }
-            continue;
-          }
 
-          // Capture complete function call from output_item.done
-          // This event contains everything: item.id, item.name, item.arguments
-          if (eventType === "response.output_item.done") {
-            const item = (event as any).item;
-            if (item?.type === "function_call") {
-              const toolName = item.name ?? "";
-              const toolCallId = item.call_id ?? item.id ?? "";
-              let args: Record<string, unknown> = {};
-              try {
-                args = JSON.parse(item.arguments ?? "{}");
-              } catch {
-                logger.error({ rawArgs: String(item.arguments).slice(0, 200) }, "Failed to parse function call arguments");
+            // Capture complete function call from output_item.done
+            // This event contains everything: item.id, item.name, item.arguments
+            if (parsedEvent.type === "response.output_item.done") {
+              const item = parsedEvent.item;
+              if (item?.type === "function_call") {
+                const toolName = item.name ?? "";
+                const toolCallId = item.call_id ?? item.id ?? "";
+                let args: Record<string, unknown> = {};
+                try {
+                  args = JSON.parse(item.arguments ?? "{}");
+                } catch {
+                  logger.error({ rawArgs: String(item.arguments).slice(0, 200) }, "Failed to parse function call arguments");
+                }
+                pendingToolCall = { id: toolCallId, name: toolName, args };
+                logger.info({ toolName, toolCallId }, "Tool call received from LLM");
               }
-              pendingToolCall = { id: toolCallId, name: toolName, args };
-              logger.info({ toolName, toolCallId }, "Tool call received from LLM");
+              continue;
             }
-            continue;
           }
-        }
 
-        // If no tool call, we're done
-        if (!pendingToolCall) {
-          yield { type: "finish", finishReason: "stop" };
-          return;
-        }
-
-        // Auto-execute the tool call server-side
-        logger.info({ toolName: pendingToolCall.name, round }, "Auto-executing tool call");
-        yield { type: "tool-call", toolCall: pendingToolCall };
+          // If no tool call, we're done
+          if (!pendingToolCall) {
+            yield { type: "finish", finishReason: "stop" };
+            return;
+          }
 
-        const toolResult = await this.executeToolCall(pendingToolCall);
-        yield { type: "tool-result", toolCallId: pendingToolCall.id, result: toolResult.text };
+          // Auto-execute the tool call server-side
+          logger.info({ toolName: pendingToolCall.name, round }, "Auto-executing tool call");
+          yield { type: "tool-call", toolCall: pendingToolCall };
+
+          const toolResult = await this.executeToolCall(
+            pendingToolCall,
+            sandboxSessions,
+            createdSessionIds,
+            request.envVars,
+          );
+          yield { type: "tool-result", toolCallId: pendingToolCall.id, result: toolResult.text };
+
+          // Emit file outputs if any
+          for (const file of toolResult.files) {
+            yield { type: "file-output", file };
+          }
 
-        // Emit file outputs if any
-        for (const file of toolResult.files) {
-          yield { type: "file-output", file };
+          // Feed tool result back to LLM for next round
+          input.push({
+            role: "assistant" as const,
+            content: `[Tool call: ${pendingToolCall.name}(${JSON.stringify(pendingToolCall.args)})]`,
+          });
+          input.push({
+            role: "user" as const,
+            content: `Tool result for ${pendingToolCall.name}: ${toolResult.text}`,
+          });
+
+        } catch (err) {
+          logger.error({ userId, err, round }, "Chat stream error");
+          yield { type: "error", message: err instanceof Error ? err.message : "Stream failed" };
+          yield { type: "finish", finishReason: "error" };
+          return;
         }
+      }
 
-        // Feed tool result back to LLM for next round
-        input.push({
-          role: "assistant" as const,
-          content: `[Tool call: ${pendingToolCall.name}(${JSON.stringify(pendingToolCall.args)})]`,
-        });
-        input.push({
-          role: "user" as const,
-          content: `Tool result for ${pendingToolCall.name}: ${toolResult.text}`,
-        });
-
-      } catch (err) {
-        logger.error({ userId, err, round }, "Chat stream error");
-        yield { type: "error", message: err instanceof Error ? err.message : "Stream failed" };
-        yield { type: "finish", finishReason: "error" };
-        return;
+      yield { type: "finish", finishReason: "stop" };
+    } finally {
+      // Best-effort session cleanup. chrono-sandbox sessions also
+      // expire via ttlSecs, but explicit teardown frees the container
+      // immediately. Swallow errors — a leftover session will TTL out.
+      if (createdSessionIds.length > 0) {
+        await Promise.allSettled(
+          createdSessionIds.map(async (sessionId) => {
+            try {
+              await this.sandboxClient.deleteSession(sessionId);
+            } catch (err) {
+              logger.warn(
+                { sessionId, err: (err as Error).message },
+                "Sandbox session delete failed — relying on TTL",
+              );
+            }
+          }),
+        );
       }
     }
-
-    yield { type: "finish", finishReason: "stop" };
   }
 
   /**
-   * Execute a tool call server-side. Returns text result and any output files.
+   * Execute a tool call server-side. Returns text result and any
+   * output files. `sandboxSessions` and `createdSessionIds` are
+   * owned by the caller (`chat()`) — per-chat state that lets
+   * `execute_in_sandbox` reuse the same chrono-sandbox kernel across
+   * tool-use rounds so installed CLIs, env, and filesystem persist
+   * (#531).
    */
   private async executeToolCall(
     toolCall: { id: string; name: string; args: Record<string, unknown> },
-  ): Promise<{ text: string; files: Array<{ path: string; content: string; size: number; mimeType: string }> }> {
+    sandboxSessions: Map<string, string>,
+    createdSessionIds: string[],
+    userEnvVars: Record<string, string> | undefined,
+  ): Promise<ToolCallResult> {
     const { name, args } = toolCall;
-    const noFiles: Array<{ path: string; content: string; size: number; mimeType: string }> = [];
 
     if (name === "execute_in_sandbox") {
-      try {
-        const result = await this.sandboxClient.execute({
-          script: (args.script as string) ?? "",
-          language: (args.language as string) ?? "python",
-          outputType: (args.output_type as "text" | "file") ?? "text",
-          env: (args.env as Record<string, string>) ?? {},
-          dependencies: (args.dependencies as string[]) ?? [],
-          retrieveFiles: (args.retrieve_files as string[]) ?? [],
-          inputFiles: (args.input_files as Array<{ path: string; content: string }>) ?? [],
-          timeoutSecs: (args.timeout_secs as number) ?? 120,
-        });
+      return await this.runSandboxToolCall(
+        args,
+        sandboxSessions,
+        createdSessionIds,
+        userEnvVars,
+      );
+    }
 
-        // Extract retrieved files
-        const files = (result.output?.files ?? [])
-          .filter((f): f is typeof f & { content: string } => !!f.content && !f.error)
-          .map((f) => ({
-            path: f.path,
-            content: f.content,
-            size: f.size ?? 0,
-            mimeType: guessMimeType(f.path),
-          }));
-
-        const filesSummary = files.length > 0
-          ? `\nFiles retrieved: ${files.map((f) => `${f.path} (${f.size} bytes)`).join(", ")}`
-          : "";
-
-        const text = result.success
-          ? `Execution succeeded (exit code ${result.output?.exit_code}).\nstdout:\n${result.output?.stdout ?? ""}\nstderr:\n${result.output?.stderr ?? ""}${filesSummary}`
-          : `Execution failed: ${result.error?.message ?? "unknown error"}\nstdout:\n${result.output?.stdout ?? ""}\nstderr:\n${result.output?.stderr ?? ""}`;
-
-        return { text, files };
+    if (name === "load_skill") {
+      try {
+        const skillJson = await this.skillService.getSkillJson((args.skill_id as string) ?? "");
+        return { text: JSON.stringify(skillJson, null, 2), files: [] };
       } catch (err) {
-        return { text: `Sandbox execution failed: ${err instanceof Error ? err.message : String(err)}`, files: noFiles };
+        return { text: `Failed to load skill: ${err instanceof Error ? err.message : String(err)}`, files: [] };
       }
     }
 
-    if (name === "load_skill") {
+    return { text: `Unknown tool: ${name}`, files: [] };
+  }
+
+  /**
+   * Dispatch a single `execute_in_sandbox` tool call.
+   *
+   * Lazily reuses a per-language chrono-sandbox session for the chat —
+   * the first call for a language pays the createSession cost (with
+   * the LLM-supplied dependency list installed once); subsequent
+   * same-language calls hit the persistent kernel and see prior CLI
+   * installs, env writes, and filesystem state (#531).
+   *
+   * Fail-open fallbacks keep one-call behaviour identical to
+   * pre-session if session APIs error: createSession failure or
+   * sessionExecute failure both retry via the one-shot `/execute`
+   * endpoint, log a warning, and (for sessionExecute) drop the stale
+   * session id so the next call can recreate.
+   */
+  private async runSandboxToolCall(
+    args: Record<string, unknown>,
+    sandboxSessions: Map<string, string>,
+    createdSessionIds: string[],
+    userEnvVars: Record<string, string> | undefined,
+  ): Promise<ToolCallResult> {
+    const script = (args.script as string) ?? "";
+    const language = (args.language as string) ?? "python";
+    const outputType = (args.output_type as "text" | "file") ?? "text";
+    // #721 — user-provided env values always win over what the model
+    // supplied in `args.env`. Since #721 we no longer feed the actual
+    // env *values* into the developer message; the model only sees
+    // placeholder shapes (`KEY=<provided-server-side>`) and is told
+    // to reference them by name. Here we replace whatever the model
+    // emitted with the real values for any key the user supplied,
+    // closing the leak path where a chat-completion provider could
+    // serialize the tool call as assistant text and echo the env
+    // back to the user. Keys the model added that aren't in
+    // `userEnvVars` ride through unchanged (the model legitimately
+    // sets ad-hoc env like sentinel markers).
+    const env: Record<string, string> = {
+      ...((args.env as Record<string, string>) ?? {}),
+      ...(userEnvVars ?? {}),
+    };
+    const dependencies = (args.dependencies as string[]) ?? [];
+    const retrieveFiles = (args.retrieve_files as string[]) ?? [];
+    const inputFiles = (args.input_files as Array<{ path: string; content: string }>) ?? [];
+    const timeoutSecs = (args.timeout_secs as number) ?? 120;
+
+    let sessionId = sandboxSessions.get(language);
+
+    if (!sessionId) {
       try {
-        const skillJson = await this.skillService.getSkillJson((args.skill_id as string) ?? "");
-        return { text: JSON.stringify(skillJson, null, 2), files: noFiles };
+        const session = await this.sandboxClient.createSession({
+          language,
+          dependencies,
+          env,
+          inputFiles,
+          // 10 min covers a typical multi-round playground session; the
+          // server also bumps last_used_at on each execute, so an
+          // active chat won't expire mid-conversation.
+          ttlSecs: 600,
+          networkEnabled: true,
+        });
+        sessionId = session.session_id;
+        sandboxSessions.set(language, sessionId);
+        createdSessionIds.push(sessionId);
+        logger.info(
+          { language, sessionId, deps: dependencies.length },
+          "Sandbox session created for chat",
+        );
       } catch (err) {
-        return { text: `Failed to load skill: ${err instanceof Error ? err.message : String(err)}`, files: noFiles };
+        logger.warn(
+          { language, err: (err as Error).message },
+          "createSession failed — falling back to one-shot execute",
+        );
+        return await this.runSandboxOneShot({
+          script, language, outputType, env, dependencies,
+          retrieveFiles, inputFiles, timeoutSecs,
+        });
       }
     }
 
-    return { text: `Unknown tool: ${name}`, files: noFiles };
+    try {
+      const result = await this.sandboxClient.sessionExecute(sessionId, {
+        script,
+        language,
+        outputType,
+        env,
+        inputFiles,
+        retrieveFiles,
+        timeoutSecs,
+      });
+      return formatSandboxResult(result);
+    } catch (err) {
+      logger.warn(
+        { sessionId, language, err: (err as Error).message },
+        "sessionExecute failed — dropping session and falling back to one-shot",
+      );
+      sandboxSessions.delete(language);
+      return await this.runSandboxOneShot({
+        script, language, outputType, env, dependencies,
+        retrieveFiles, inputFiles, timeoutSecs,
+      });
+    }
+  }
+
+  /**
+   * One-shot fallback path used when session APIs are unavailable.
+   * Matches the legacy pre-#531 behaviour exactly so a broken sandbox
+   * session layer never makes the playground worse than it was.
+   */
+  private async runSandboxOneShot(params: {
+    script: string;
+    language: string;
+    outputType: "text" | "file";
+    env: Record<string, string>;
+    dependencies: string[];
+    retrieveFiles: string[];
+    inputFiles: Array<{ path: string; content: string }>;
+    timeoutSecs: number;
+  }): Promise<ToolCallResult> {
+    try {
+      const result = await this.sandboxClient.execute(params);
+      return formatSandboxResult(result);
+    } catch (err) {
+      logger.error(
+        {
+          language: params.language,
+          scriptLen: params.script.length,
+          err: (err as Error).message,
+        },
+        "Sandbox one-shot execute failed",
+      );
+      return { text: formatSandboxError(err), files: [] };
+    }
   }
 
   /**
@@ -416,11 +697,25 @@ export class PlaygroundChatService {
       lines.push("");
     }
 
-    // Add user-provided env vars
+    // #721 — list ONLY the env var NAMES the user provided values for,
+    // never the values themselves. If the model ever echoes the
+    // developer message back (as it can do when chat-completion
+    // providers serialize `execute_in_sandbox` to assistant text
+    // instead of a structured tool call), the transcript would leak
+    // the user's secret. The server-side path (`runSandboxToolCall`)
+    // injects the real values into the sandbox env at execution
+    // time — the LLM never needs the literal value to issue the
+    // tool call.
     if (envVars && Object.keys(envVars).length > 0) {
       lines.push("### User-provided Environment Variables");
-      for (const [key, value] of Object.entries(envVars)) {
-        lines.push(`- ${key}=${value}`);
+      lines.push(
+        "The user has supplied values for the variables below. Reference each",
+        "by name when constructing `execute_in_sandbox`'s `env` argument —",
+        "the runtime will inject the real values server-side. DO NOT attempt to",
+        "guess, repeat, or echo the values; you do not have them.",
+      );
+      for (const key of Object.keys(envVars)) {
+        lines.push(`- ${key}=<provided-server-side>`);
       }
       lines.push("");
     }
diff --git a/ornn-api/src/domains/playground/routes.ts b/ornn-api/src/domains/playground/routes.ts
index 9adfe45c..c11dfa7a 100644
--- a/ornn-api/src/domains/playground/routes.ts
+++ b/ornn-api/src/domains/playground/routes.ts
@@ -21,14 +21,27 @@ import {
   getAuth,
 } from "../../middleware/nyxidAuth";
 import { validateBody, getValidatedBody } from "../../middleware/validate";
-import pino from "pino";
-
-const logger = pino({ level: "info" }).child({ module: "playgroundRoutes" });
+import { createLogger } from "../../shared/logger";
+const logger = createLogger("playgroundRoutes");
 
 // Zod schemas
+
+/**
+ * Per-message content cap (#654). Mirrors the frontend `MAX_INPUT_CHARS`
+ * in `ornn-web/src/components/playground/ChatInput.tsx`. ~8k tokens at
+ * 4 chars/token — generous for interactive prompts without enabling
+ * whole-novel pastes. The textarea hard-caps at this value via its
+ * `maxLength`, but the backend duplicates the check so a malicious /
+ * non-browser client can't slip past.
+ */
+const MAX_CHAT_MESSAGE_CHARS = 32_000;
+
 const playgroundMessageSchema = z.object({
   role: z.enum(["user", "assistant", "tool", "system"]),
-  content: z.string(),
+  content: z.string().max(
+    MAX_CHAT_MESSAGE_CHARS,
+    `Message content exceeds ${MAX_CHAT_MESSAGE_CHARS} character limit`,
+  ),
   toolCalls: z.array(z.object({
     id: z.string(),
     name: z.string(),
@@ -105,7 +118,8 @@ export function createPlaygroundRoutes(config: PlaygroundRoutesConfig): Hono<{ V
       // models are enabled for the playground surface.
       const resolution = await llmProvidersService.resolveModel({
         surface: "playground",
-        requested: parsed.modelId,
+        // exactOptionalPropertyTypes (#657)
+        ...(parsed.modelId !== undefined ? { requested: parsed.modelId } : {}),
       });
       if (resolution.kind !== "ok") throwModelResolutionError(resolution);
       const resolvedModelId = resolution.modelId;
diff --git a/ornn-api/src/domains/quota/bootstrap.ts b/ornn-api/src/domains/quota/bootstrap.ts
new file mode 100644
index 00000000..2fe59b49
--- /dev/null
+++ b/ornn-api/src/domains/quota/bootstrap.ts
@@ -0,0 +1,62 @@
+/**
+ * Wire the quota domain (#580 — bootstrap decomposition).
+ *
+ * Quota is a downstream consumer of `settingsService` (for the
+ * per-surface default-monthly-allotment fallback) and
+ * `notificationService` (for the over-threshold warning fan-out). The
+ * service is exported because three other domains mount it as a
+ * dependency: playground, skill-gen, and admin (admin quota CRUD).
+ *
+ * @module domains/quota/bootstrap
+ */
+
+import type { Db } from "mongodb";
+import type { Hono } from "hono";
+import type { Logger } from "pino";
+import type { AuthVariables } from "../../middleware/nyxidAuth";
+import { QuotaRepository } from "./repository";
+import { QuotaService } from "./service";
+import { createQuotaRoutes } from "./routes";
+import type { NotificationService } from "../notifications/service";
+import type { SettingsService } from "../settings/types";
+
+export interface QuotaWiring {
+  readonly service: QuotaService;
+  readonly routes: Hono<{ Variables: AuthVariables }>;
+}
+
+export function wireQuota(deps: {
+  db: Db;
+  logger: Logger;
+  settingsService: SettingsService;
+  notificationService: NotificationService;
+}): QuotaWiring {
+  const repo = new QuotaRepository(deps.db);
+  void repo.ensureIndexes().catch((err) =>
+    deps.logger.warn(
+      { err },
+      "quota indexes ensureIndexes failed — proceeding anyway",
+    ),
+  );
+  const service = new QuotaService({
+    repo,
+    defaults: {
+      // The "raise the default mid-month" headroom rule is implemented
+      // inside QuotaService; this resolver just hands it the current
+      // section values whenever it asks.
+      getQuotaDefaults: async () => {
+        const [pg, sg] = await Promise.all([
+          deps.settingsService.getPlayground(),
+          deps.settingsService.getSkillGen(),
+        ]);
+        return {
+          defaultPlaygroundMonthly: pg.defaultMonthlyQuota,
+          defaultSkillGenMonthly: sg.defaultMonthlyQuota,
+        };
+      },
+    },
+    notificationService: deps.notificationService,
+  });
+  const routes = createQuotaRoutes({ quotaService: service });
+  return { service, routes };
+}
diff --git a/ornn-api/src/domains/quota/repository.test.ts b/ornn-api/src/domains/quota/repository.test.ts
index 88301b6a..26ba2cab 100644
--- a/ornn-api/src/domains/quota/repository.test.ts
+++ b/ornn-api/src/domains/quota/repository.test.ts
@@ -82,8 +82,8 @@ describe("UT-QUOTAREPO-002 upsert is idempotent on _id", () => {
       .find({ userId: "u1", surface: "playground" })
       .toArray();
     expect(docs.length).toBe(1);
-    expect(docs[0]._id as unknown as string).toBe(id);
-    expect((docs[0] as unknown as { used: number }).used).toBe(2);
+    expect(docs[0]!._id as unknown as string).toBe(id);
+    expect((docs[0]! as unknown as { used: number }).used).toBe(2);
   });
 });
 
@@ -252,6 +252,6 @@ describe("listGrantAudit pagination + filter", () => {
     });
     const res = await repo.listGrantAudit({ page: 1, pageSize: 50, targetUserId: "uA" });
     expect(res.total).toBe(1);
-    expect(res.items[0].targetUserId).toBe("uA");
+    expect(res.items[0]!.targetUserId).toBe("uA");
   });
 });
diff --git a/ornn-api/src/domains/quota/repository.ts b/ornn-api/src/domains/quota/repository.ts
index e2e3eee4..50923473 100644
--- a/ornn-api/src/domains/quota/repository.ts
+++ b/ornn-api/src/domains/quota/repository.ts
@@ -12,7 +12,7 @@
 
 import type { Collection, Db } from "mongodb";
 import { randomUUID } from "node:crypto";
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import {
   type QuotaBucketDoc,
   type QuotaGrantAuditDoc,
@@ -22,7 +22,7 @@ import {
   monthBounds,
 } from "./types";
 
-const logger = pino({ level: "info" }).child({ module: "quotaRepository" });
+const logger = createLogger("quotaRepository");
 
 export interface UpsertChargeParams {
   userId: string;
diff --git a/ornn-api/src/domains/quota/routes.ts b/ornn-api/src/domains/quota/routes.ts
index 3214e739..d7691a0c 100644
--- a/ornn-api/src/domains/quota/routes.ts
+++ b/ornn-api/src/domains/quota/routes.ts
@@ -50,5 +50,5 @@ export function throwQuotaError(decision: {
   surface: Surface;
   message: string;
 }): never {
-  throw new AppError(429, "QUOTA_EXCEEDED", decision.message);
+  throw new AppError(429, "quota_exceeded", decision.message);
 }
diff --git a/ornn-api/src/domains/quota/service.ts b/ornn-api/src/domains/quota/service.ts
index c3e2ae80..3bf9e568 100644
--- a/ornn-api/src/domains/quota/service.ts
+++ b/ornn-api/src/domains/quota/service.ts
@@ -14,7 +14,7 @@
  * @module domains/quota/service
  */
 
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import type { NotificationService } from "../notifications/service";
 import type { QuotaRepository } from "./repository";
 import {
@@ -29,7 +29,7 @@ import {
   nextMonthlyResetAt,
 } from "./types";
 
-const logger = pino({ level: "info" }).child({ module: "quotaService" });
+const logger = createLogger("quotaService");
 
 export interface QuotaDefaults {
   defaultPlaygroundMonthly: number;
@@ -53,7 +53,8 @@ export class QuotaService {
   private readonly repo: QuotaRepository;
   private readonly defaults: QuotaDefaultsResolver;
   private readonly adminPermission: string;
-  private readonly notificationService?: NotificationService;
+  // exactOptionalPropertyTypes (#657): widen to `T | undefined`.
+  private readonly notificationService: NotificationService | undefined;
   private readonly warningThreshold: number;
 
   constructor(config: QuotaServiceConfig) {
@@ -167,7 +168,8 @@ export class QuotaService {
       targetUserId: params.targetUserId,
       surface: params.surface,
       amount: params.amount,
-      note: params.note,
+      // exactOptionalPropertyTypes (#657)
+      ...(params.note !== undefined ? { note: params.note } : {}),
       monthMarker,
       createdAt: now,
     });
@@ -190,7 +192,8 @@ export class QuotaService {
           targetUserId: params.targetUserId,
           surface: params.surface,
           amount: params.amount,
-          note: params.note,
+          // exactOptionalPropertyTypes (#657)
+          ...(params.note !== undefined ? { note: params.note } : {}),
           adminDisplayName: params.admin.displayName,
         })
         .catch((err: unknown) => {
@@ -221,7 +224,8 @@ export class QuotaService {
           targetUserId: userId,
           surface: params.surface,
           amount: params.amount,
-          note: params.note,
+          // exactOptionalPropertyTypes (#657)
+          ...(params.note !== undefined ? { note: params.note } : {}),
           now,
         });
         out.push({ userId, ok: true, auditId });
diff --git a/ornn-api/src/domains/redemption-codes/bootstrap.ts b/ornn-api/src/domains/redemption-codes/bootstrap.ts
new file mode 100644
index 00000000..129fd472
--- /dev/null
+++ b/ornn-api/src/domains/redemption-codes/bootstrap.ts
@@ -0,0 +1,52 @@
+/**
+ * Wire the redemption-codes domain (#580 — bootstrap decomposition).
+ *
+ * Consumes `quotaService` (every redeem fans out into per-surface quota
+ * grants). Exposes BOTH route surfaces — `/admin/redemption-codes` for
+ * mint/list/invalidate and `/me/redemption-codes/redeem` for the user
+ * side. Both share a single RedemptionCodeService instance so the
+ * atomic `findOneAndUpdate` pivots inside the service stay consistent.
+ *
+ * @module domains/redemption-codes/bootstrap
+ */
+
+import type { Db } from "mongodb";
+import type { Hono } from "hono";
+import type { Logger } from "pino";
+import type { AuthVariables } from "../../middleware/nyxidAuth";
+import { RedemptionCodeRepository } from "./repository";
+import { RedemptionCodeService } from "./service";
+import { createMeRedemptionCodesRoutes } from "./me-routes";
+import { createAdminRedemptionCodesRoutes } from "../admin/redemption-codes/routes";
+import type { QuotaService } from "../quota/service";
+
+export interface RedemptionCodesWiring {
+  readonly service: RedemptionCodeService;
+  readonly adminRoutes: Hono<{ Variables: AuthVariables }>;
+  readonly meRoutes: Hono<{ Variables: AuthVariables }>;
+}
+
+export function wireRedemptionCodes(deps: {
+  db: Db;
+  logger: Logger;
+  quotaService: QuotaService;
+}): RedemptionCodesWiring {
+  const repo = new RedemptionCodeRepository(deps.db);
+  void repo.ensureIndexes().catch((err) =>
+    deps.logger.warn(
+      { err },
+      "redemption_codes indexes ensureIndexes failed — proceeding anyway",
+    ),
+  );
+  const service = new RedemptionCodeService({
+    repo,
+    quotaService: deps.quotaService,
+  });
+  const adminRoutes = createAdminRedemptionCodesRoutes({
+    redemptionCodeService: service,
+  });
+  const meRoutes = createMeRedemptionCodesRoutes({
+    redemptionCodeService: service,
+  });
+  return { service, adminRoutes, meRoutes };
+}
diff --git a/ornn-api/src/domains/redemption-codes/me-routes.test.ts b/ornn-api/src/domains/redemption-codes/me-routes.test.ts
index cf493d95..6ad53aab 100644
--- a/ornn-api/src/domains/redemption-codes/me-routes.test.ts
+++ b/ornn-api/src/domains/redemption-codes/me-routes.test.ts
@@ -15,6 +15,7 @@ import { RedemptionCodeRepository } from "./repository";
 import { RedemptionCodeService } from "./service";
 import { createMeRedemptionCodesRoutes } from "./me-routes";
 import type { AuthVariables } from "../../middleware/nyxidAuth";
+import { buildProblemJsonBody } from "../../shared/types/index";
 
 let mongo: MongoMemoryServer;
 let client: MongoClient;
@@ -57,16 +58,18 @@ beforeAll(async () => {
   });
   app.onError((err, c) => {
     const e = err as { statusCode?: number; code?: string; message: string };
-    if (e.statusCode && e.code) {
-      return c.json(
-        { data: null, error: { code: e.code, message: e.message } },
-        e.statusCode as never,
-      );
-    }
-    return c.json(
-      { data: null, error: { code: "INTERNAL", message: e.message } },
-      500,
-    );
+    const statusCode = e.statusCode ?? 500;
+    const code = e.code ?? "internal_error";
+    const body = buildProblemJsonBody({
+      statusCode,
+      code,
+      message: e.message ?? "",
+      instance: c.req.path,
+      requestId: null,
+    });
+    return c.json(body, statusCode as never, {
+      "Content-Type": "application/problem+json",
+    });
   });
   app.route("/", createMeRedemptionCodesRoutes({ redemptionCodeService: service }));
 });
@@ -108,8 +111,8 @@ describe("POST /me/redemption-codes/redeem", () => {
       data: { codeId: string; grants: Array<{ surface: string; amount: number }> };
     };
     expect(json.data.grants.length).toBe(1);
-    expect(json.data.grants[0].surface).toBe("playground");
-    expect(json.data.grants[0].amount).toBe(5);
+    expect(json.data.grants[0]!.surface).toBe("playground");
+    expect(json.data.grants[0]!.amount).toBe(5);
 
     const audits = await db.collection("quota_grants_audit").countDocuments();
     expect(audits).toBe(1);
@@ -132,8 +135,8 @@ describe("POST /me/redemption-codes/redeem", () => {
       body: JSON.stringify({ code: "ZZZZZZZZZZZZZZZZ" }),
     });
     expect(res.status).toBe(404);
-    const json = (await res.json()) as { error: { code: string } };
-    expect(json.error.code).toBe("REDEMPTION_CODE_NOT_FOUND");
+    const json = (await res.json()) as { code: string; detail: string; status: number };
+    expect(json.code).toBe("redemption_code_not_found");
   });
 
   test("expired → 410 REDEMPTION_CODE_EXPIRED", async () => {
@@ -147,8 +150,8 @@ describe("POST /me/redemption-codes/redeem", () => {
       body: JSON.stringify({ code }),
     });
     expect(res.status).toBe(410);
-    const json = (await res.json()) as { error: { code: string } };
-    expect(json.error.code).toBe("REDEMPTION_CODE_EXPIRED");
+    const json = (await res.json()) as { code: string; detail: string; status: number };
+    expect(json.code).toBe("redemption_code_expired");
   });
 
   test("invalidated → 410 REDEMPTION_CODE_INVALIDATED", async () => {
@@ -167,8 +170,8 @@ describe("POST /me/redemption-codes/redeem", () => {
       body: JSON.stringify({ code: minted.code }),
     });
     expect(res.status).toBe(410);
-    const json = (await res.json()) as { error: { code: string } };
-    expect(json.error.code).toBe("REDEMPTION_CODE_INVALIDATED");
+    const json = (await res.json()) as { code: string; detail: string; status: number };
+    expect(json.code).toBe("redemption_code_invalidated");
   });
 
   test("already-redeemed → 409 REDEMPTION_CODE_ALREADY_REDEEMED", async () => {
@@ -184,8 +187,8 @@ describe("POST /me/redemption-codes/redeem", () => {
       body: JSON.stringify({ code }),
     });
     expect(res.status).toBe(409);
-    const json = (await res.json()) as { error: { code: string } };
-    expect(json.error.code).toBe("REDEMPTION_CODE_ALREADY_REDEEMED");
+    const json = (await res.json()) as { code: string; detail: string; status: number };
+    expect(json.code).toBe("redemption_code_already_redeemed");
   });
 });
 
diff --git a/ornn-api/src/domains/redemption-codes/me-routes.ts b/ornn-api/src/domains/redemption-codes/me-routes.ts
index 63aadab8..5c18caf5 100644
--- a/ornn-api/src/domains/redemption-codes/me-routes.ts
+++ b/ornn-api/src/domains/redemption-codes/me-routes.ts
@@ -14,7 +14,7 @@
  */
 
 import { Hono } from "hono";
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import {
   type AuthVariables,
   getAuth,
@@ -25,7 +25,7 @@ import { AppError } from "../../shared/types/index";
 import type { RedemptionCodeService } from "./service";
 import { redeemSchema, type RedeemInput, type RedemptionCodeDoc } from "./types";
 
-const logger = pino({ level: "info" }).child({ module: "meRedemptionCodeRoutes" });
+const logger = createLogger("meRedemptionCodeRoutes");
 
 const HISTORY_PAGE_SIZE_MAX = 100;
 const HISTORY_PAGE_SIZE_DEFAULT = 20;
@@ -36,26 +36,26 @@ export interface MeRedemptionCodesRoutesConfig {
 
 function mapRedeemError(message: string): AppError {
   if (message.startsWith("NOT_FOUND:")) {
-    return new AppError(404, "REDEMPTION_CODE_NOT_FOUND", "Code not found");
+    return new AppError(404, "redemption_code_not_found", "Code not found");
   }
   if (message.startsWith("EXPIRED:")) {
-    return new AppError(410, "REDEMPTION_CODE_EXPIRED", "This code has expired");
+    return new AppError(410, "redemption_code_expired", "This code has expired");
   }
   if (message.startsWith("ALREADY_INVALIDATED:")) {
     return new AppError(
       410,
-      "REDEMPTION_CODE_INVALIDATED",
+      "redemption_code_invalidated",
       "This code has been revoked",
     );
   }
   if (message.startsWith("ALREADY_REDEEMED:")) {
     return new AppError(
       409,
-      "REDEMPTION_CODE_ALREADY_REDEEMED",
+      "redemption_code_already_redeemed",
       "This code has already been redeemed",
     );
   }
-  return AppError.internalError("REDEMPTION_CODE_REDEEM_FAILED", message);
+  return AppError.internalError("redemption_code_redeem_failed", message);
 }
 
 function serializeHistoryItem(doc: RedemptionCodeDoc): Record<string, unknown> {
diff --git a/ornn-api/src/domains/redemption-codes/repository.test.ts b/ornn-api/src/domains/redemption-codes/repository.test.ts
new file mode 100644
index 00000000..a1405bb7
--- /dev/null
+++ b/ornn-api/src/domains/redemption-codes/repository.test.ts
@@ -0,0 +1,320 @@
+/**
+ * RedemptionCodeRepository unit tests (#454).
+ *
+ * Lifecycle pivots (`active → redeemed` and `active → invalidated`) MUST
+ * be atomic — concurrent attempts against the same code yield exactly
+ * one winner. The repo enforces this via `findOneAndUpdate` with a
+ * status-guard filter; these tests pin that contract.
+ *
+ * Also covers list/search regex escaping (no ReDoS, no false positives)
+ * and per-user redemption history pagination.
+ *
+ * @module domains/redemption-codes/repository.test
+ */
+
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+import { MongoClient, type Db } from "mongodb";
+import { MongoMemoryServer } from "mongodb-memory-server";
+import { RedemptionCodeRepository } from "./repository";
+import type { ActorMeta, RedemptionCodeDoc } from "./types";
+
+let mongo: MongoMemoryServer;
+let client: MongoClient;
+let db: Db;
+let repo: RedemptionCodeRepository;
+
+beforeAll(async () => {
+  mongo = await MongoMemoryServer.create();
+  client = new MongoClient(mongo.getUri());
+  await client.connect();
+  db = client.db("redemption_codes_test");
+  repo = new RedemptionCodeRepository(db);
+  await repo.ensureIndexes();
+});
+
+afterAll(async () => {
+  await client.close();
+  await mongo.stop();
+});
+
+beforeEach(async () => {
+  await db.collection("redemption_codes").deleteMany({});
+});
+
+const admin: ActorMeta = { userId: "admin-1", email: "admin@x", displayName: "Admin" };
+const user: ActorMeta = { userId: "u1", email: "u1@x", displayName: "User 1" };
+
+function mkCode(overrides: Partial<RedemptionCodeDoc> = {}): RedemptionCodeDoc {
+  const now = new Date();
+  return {
+    _id: `code-${Math.random().toString(36).slice(2)}`,
+    code: `CODE${Math.floor(Math.random() * 1_000_000)}`,
+    grants: [{ surface: "playground", amount: 100 }],
+    note: undefined,
+    createdAt: now,
+    createdBy: admin,
+    expiresAt: new Date(now.getTime() + 86_400_000), // +1 day
+    status: "active",
+    ...overrides,
+  };
+}
+
+describe("insertCode + findByCode + findById", () => {
+  test("round-trips a freshly minted code", async () => {
+    const doc = mkCode({ code: "ABCDEFGH12345678" });
+    await repo.insertCode(doc);
+    const byCode = await repo.findByCode("ABCDEFGH12345678");
+    expect(byCode?._id).toBe(doc._id);
+    const byId = await repo.findById(doc._id);
+    expect(byId?.code).toBe("ABCDEFGH12345678");
+  });
+
+  test("returns null for unknown code / id", async () => {
+    expect(await repo.findByCode("NOPE")).toBeNull();
+    expect(await repo.findById("missing")).toBeNull();
+  });
+
+  test("unique index rejects duplicate codes", async () => {
+    await repo.insertCode(mkCode({ _id: "id-a", code: "DUPECODE12345678" }));
+    await expect(
+      repo.insertCode(mkCode({ _id: "id-b", code: "DUPECODE12345678" })),
+    ).rejects.toThrow();
+  });
+});
+
+describe("tryClaimForRedeem", () => {
+  test("flips active → redeemed and stamps redeemer", async () => {
+    const doc = mkCode({ code: "REDEEM0001" });
+    await repo.insertCode(doc);
+    const now = new Date();
+    const after = await repo.tryClaimForRedeem({ code: doc.code, redeemedBy: user, now });
+    expect(after?.status).toBe("redeemed");
+    expect(after?.redeemedBy?.userId).toBe("u1");
+    expect(after?.redeemedAt?.getTime()).toBe(now.getTime());
+  });
+
+  test("concurrent attempts on the same code yield exactly one winner", async () => {
+    const doc = mkCode({ code: "RACECODE001" });
+    await repo.insertCode(doc);
+    const now = new Date();
+    const results = await Promise.all([
+      repo.tryClaimForRedeem({ code: doc.code, redeemedBy: user, now }),
+      repo.tryClaimForRedeem({ code: doc.code, redeemedBy: user, now }),
+      repo.tryClaimForRedeem({ code: doc.code, redeemedBy: user, now }),
+    ]);
+    const winners = results.filter((r) => r !== null);
+    expect(winners).toHaveLength(1);
+  });
+
+  test("expired code cannot be redeemed", async () => {
+    const expired = mkCode({
+      code: "EXPIRED01",
+      expiresAt: new Date(Date.now() - 1000),
+    });
+    await repo.insertCode(expired);
+    const after = await repo.tryClaimForRedeem({
+      code: expired.code,
+      redeemedBy: user,
+      now: new Date(),
+    });
+    expect(after).toBeNull();
+    // Underlying state unchanged.
+    const fresh = await repo.findByCode(expired.code);
+    expect(fresh?.status).toBe("active");
+  });
+
+  test("invalidated code cannot be redeemed", async () => {
+    const doc = mkCode({ code: "INVALID01", status: "invalidated" });
+    await repo.insertCode(doc);
+    const after = await repo.tryClaimForRedeem({
+      code: doc.code,
+      redeemedBy: user,
+      now: new Date(),
+    });
+    expect(after).toBeNull();
+  });
+
+  test("unknown code yields null without inserting", async () => {
+    const before = await db.collection("redemption_codes").countDocuments();
+    const after = await repo.tryClaimForRedeem({
+      code: "DOESNOTEXIST",
+      redeemedBy: user,
+      now: new Date(),
+    });
+    expect(after).toBeNull();
+    expect(await db.collection("redemption_codes").countDocuments()).toBe(before);
+  });
+});
+
+describe("tryInvalidate", () => {
+  test("flips active → invalidated and stamps invalidator", async () => {
+    const doc = mkCode();
+    await repo.insertCode(doc);
+    const now = new Date();
+    const after = await repo.tryInvalidate({ id: doc._id, invalidatedBy: admin, now });
+    expect(after?.status).toBe("invalidated");
+    expect(after?.invalidatedBy?.userId).toBe("admin-1");
+    expect(after?.invalidatedAt?.getTime()).toBe(now.getTime());
+  });
+
+  test("already-redeemed code cannot be invalidated", async () => {
+    const doc = mkCode({ status: "redeemed" });
+    await repo.insertCode(doc);
+    const after = await repo.tryInvalidate({
+      id: doc._id,
+      invalidatedBy: admin,
+      now: new Date(),
+    });
+    expect(after).toBeNull();
+  });
+
+  test("concurrent invalidates yield exactly one winner", async () => {
+    const doc = mkCode();
+    await repo.insertCode(doc);
+    const now = new Date();
+    const results = await Promise.all([
+      repo.tryInvalidate({ id: doc._id, invalidatedBy: admin, now }),
+      repo.tryInvalidate({ id: doc._id, invalidatedBy: admin, now }),
+    ]);
+    expect(results.filter((r) => r !== null)).toHaveLength(1);
+  });
+});
+
+describe("list", () => {
+  beforeEach(async () => {
+    // Seed: three active + one redeemed + one invalidated, with codes
+    // and notes that exercise the search predicate.
+    await repo.insertCode(
+      mkCode({ _id: "a1", code: "AAAAAAAA00000001", note: "alpha team" }),
+    );
+    await new Promise((r) => setTimeout(r, 5));
+    await repo.insertCode(
+      mkCode({ _id: "a2", code: "AAAAAAAA00000002", note: "alpha team" }),
+    );
+    await new Promise((r) => setTimeout(r, 5));
+    await repo.insertCode(
+      mkCode({ _id: "b1", code: "BBBBBBBB00000001", note: "beta team" }),
+    );
+    await new Promise((r) => setTimeout(r, 5));
+    await repo.insertCode(
+      mkCode({ _id: "r1", code: "REDEEMED00000001", status: "redeemed", note: "gamma" }),
+    );
+    await new Promise((r) => setTimeout(r, 5));
+    await repo.insertCode(
+      mkCode({ _id: "i1", code: "INVALID000000001", status: "invalidated", note: "delta" }),
+    );
+  });
+
+  test("filters by status", async () => {
+    const res = await repo.list({ page: 1, pageSize: 20, status: "active" });
+    expect(res.total).toBe(3);
+    expect(res.items.every((d) => d.status === "active")).toBe(true);
+  });
+
+  test("paginates newest-first", async () => {
+    const p1 = await repo.list({ page: 1, pageSize: 2 });
+    const p2 = await repo.list({ page: 2, pageSize: 2 });
+    expect(p1.items).toHaveLength(2);
+    expect(p2.items).toHaveLength(2);
+    // No overlap
+    const ids1 = new Set(p1.items.map((d) => d._id));
+    expect(p2.items.every((d) => !ids1.has(d._id))).toBe(true);
+    // Sorted newest-first
+    expect(p1.items[0]!.createdAt.getTime()).toBeGreaterThanOrEqual(
+      p1.items[1]!.createdAt.getTime(),
+    );
+  });
+
+  test("search matches by code prefix (uppercased)", async () => {
+    const res = await repo.list({ page: 1, pageSize: 20, search: "aaaa" });
+    expect(res.total).toBe(2);
+    expect(res.items.every((d) => d.code.startsWith("AAAA"))).toBe(true);
+  });
+
+  test("search matches by note substring (case-insensitive)", async () => {
+    const res = await repo.list({ page: 1, pageSize: 20, search: "BETA" });
+    expect(res.items.map((d) => d._id)).toEqual(["b1"]);
+  });
+
+  test("search escapes regex metacharacters (no ReDoS)", async () => {
+    // `.*` would match everything if unescaped. The repo MUST treat it
+    // as a literal string and return zero matches.
+    const res = await repo.list({ page: 1, pageSize: 20, search: ".*" });
+    expect(res.total).toBe(0);
+  });
+
+  test("empty search is a no-op (returns all)", async () => {
+    const res = await repo.list({ page: 1, pageSize: 20, search: "   " });
+    expect(res.total).toBe(5);
+  });
+});
+
+describe("listRedeemedByUser", () => {
+  test("returns only codes redeemed by the given userId, newest first", async () => {
+    const now = new Date();
+    await repo.insertCode(
+      mkCode({
+        _id: "ru1",
+        code: "USERREDEEM0001",
+        status: "redeemed",
+        redeemedBy: user,
+        redeemedAt: new Date(now.getTime() - 1000),
+      }),
+    );
+    await repo.insertCode(
+      mkCode({
+        _id: "ru2",
+        code: "USERREDEEM0002",
+        status: "redeemed",
+        redeemedBy: user,
+        redeemedAt: now,
+      }),
+    );
+    await repo.insertCode(
+      mkCode({
+        _id: "ru3",
+        code: "OTHERUSER000001",
+        status: "redeemed",
+        redeemedBy: { userId: "u2", email: "u2@x", displayName: "U2" },
+        redeemedAt: now,
+      }),
+    );
+    const res = await repo.listRedeemedByUser("u1", 1, 10);
+    expect(res.total).toBe(2);
+    expect(res.items.map((d) => d._id)).toEqual(["ru2", "ru1"]);
+  });
+
+  test("returns empty when user has no redemptions", async () => {
+    const res = await repo.listRedeemedByUser("nobody", 1, 10);
+    expect(res).toEqual({ items: [], total: 0 });
+  });
+
+  test("respects pagination", async () => {
+    const now = new Date();
+    for (let i = 0; i < 5; i++) {
+      await repo.insertCode(
+        mkCode({
+          _id: `p${i}`,
+          code: `PAGE${i.toString().padStart(12, "0")}`,
+          status: "redeemed",
+          redeemedBy: user,
+          redeemedAt: new Date(now.getTime() - i * 1000),
+        }),
+      );
+    }
+    const p1 = await repo.listRedeemedByUser("u1", 1, 2);
+    const p2 = await repo.listRedeemedByUser("u1", 2, 2);
+    expect(p1.items).toHaveLength(2);
+    expect(p2.items).toHaveLength(2);
+    expect(p1.total).toBe(5);
+    const ids1 = new Set(p1.items.map((d) => d._id));
+    expect(p2.items.every((d) => !ids1.has(d._id))).toBe(true);
+  });
+});
diff --git a/ornn-api/src/domains/redemption-codes/repository.ts b/ornn-api/src/domains/redemption-codes/repository.ts
index 0603cfa0..449fd3fd 100644
--- a/ornn-api/src/domains/redemption-codes/repository.ts
+++ b/ornn-api/src/domains/redemption-codes/repository.ts
@@ -12,14 +12,14 @@
  */
 
 import type { Collection, Db } from "mongodb";
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import {
   type ActorMeta,
   type RedemptionCodeDoc,
   type RedemptionCodeStatus,
 } from "./types";
 
-const logger = pino({ level: "info" }).child({ module: "redemptionCodeRepository" });
+const logger = createLogger("redemptionCodeRepository");
 
 /**
  * Escape a user-supplied string before embedding in a `$regex`. Same
diff --git a/ornn-api/src/domains/redemption-codes/service.ts b/ornn-api/src/domains/redemption-codes/service.ts
index ed2d6202..9b89c0e4 100644
--- a/ornn-api/src/domains/redemption-codes/service.ts
+++ b/ornn-api/src/domains/redemption-codes/service.ts
@@ -18,7 +18,7 @@
 
 import { randomBytes } from "node:crypto";
 import { ObjectId } from "mongodb";
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import { isDuplicateKeyError } from "../../shared/types/index";
 import type { Surface } from "../quota/types";
 import type { QuotaService } from "../quota/service";
@@ -32,7 +32,7 @@ import {
   type RedemptionGrantEntry,
 } from "./types";
 
-const logger = pino({ level: "info" }).child({ module: "redemptionCodeService" });
+const logger = createLogger("redemptionCodeService");
 
 const MINT_RETRY_LIMIT = 5;
 
@@ -121,7 +121,10 @@ export class RedemptionCodeService {
     const bytes = randomBytes(REDEMPTION_CODE_LENGTH);
     let out = "";
     for (let i = 0; i < REDEMPTION_CODE_LENGTH; i++) {
-      out += REDEMPTION_CODE_ALPHABET[bytes[i] % REDEMPTION_CODE_ALPHABET.length];
+      // `randomBytes(N)` returns exactly N bytes — loop bound is N, so
+      // `bytes[i]` is always defined. `!` is safe under
+      // noUncheckedIndexedAccess (#450).
+      out += REDEMPTION_CODE_ALPHABET[bytes[i]! % REDEMPTION_CODE_ALPHABET.length];
     }
     return out;
   }
diff --git a/ornn-api/src/domains/redemption-codes/types.ts b/ornn-api/src/domains/redemption-codes/types.ts
index 624fc598..75c8938b 100644
--- a/ornn-api/src/domains/redemption-codes/types.ts
+++ b/ornn-api/src/domains/redemption-codes/types.ts
@@ -55,21 +55,24 @@ export interface ActorMeta {
   displayName: string;
 }
 
+// Optional fields widen to `| undefined` so callers passing Zod-
+// inferred shapes or building docs incrementally fit under
+// exactOptionalPropertyTypes (#657).
 export interface RedemptionCodeDoc {
   /** ObjectId hex string. */
   _id: string;
   /** Canonical uppercase code, unique. */
   code: string;
   grants: RedemptionGrantEntry[];
-  note?: string;
+  note?: string | undefined;
   createdAt: Date;
   createdBy: ActorMeta;
   expiresAt: Date;
   status: RedemptionCodeStatus;
-  redeemedAt?: Date;
-  redeemedBy?: ActorMeta;
-  invalidatedAt?: Date;
-  invalidatedBy?: ActorMeta;
+  redeemedAt?: Date | undefined;
+  redeemedBy?: ActorMeta | undefined;
+  invalidatedAt?: Date | undefined;
+  invalidatedBy?: ActorMeta | undefined;
 }
 
 // ---------------------------------------------------------------------------
diff --git a/ornn-api/src/domains/settings/exportImport/exporter.test.ts b/ornn-api/src/domains/settings/exportImport/exporter.test.ts
index 1c6d5321..9cafb7da 100644
--- a/ornn-api/src/domains/settings/exportImport/exporter.test.ts
+++ b/ornn-api/src/domains/settings/exportImport/exporter.test.ts
@@ -129,7 +129,7 @@ describe("SettingsExporter", () => {
     const telemetry = env.sections.telemetry as Record<string, unknown>;
     expect(isRedactionSentinel(telemetry.postHogApiKey)).toBe(true);
     const providers = env.sections.llmProviders as Array<Record<string, unknown>>;
-    const auth = providers[0].auth as Record<string, unknown>;
+    const auth = providers[0]!.auth as Record<string, unknown>;
     expect(isRedactionSentinel(auth.apiKey)).toBe(true);
   });
 
diff --git a/ornn-api/src/domains/settings/exportImport/importer.test.ts b/ornn-api/src/domains/settings/exportImport/importer.test.ts
index 5e98006f..5d592111 100644
--- a/ornn-api/src/domains/settings/exportImport/importer.test.ts
+++ b/ornn-api/src/domains/settings/exportImport/importer.test.ts
@@ -156,8 +156,8 @@ describe("SettingsImporter", () => {
     );
     const q = r.sections.find((s) => s.id === "playground")!;
     expect(q.status).toBe("failed");
-    expect(q.errors?.[0].field).toBe("defaultMonthlyQuota");
-    expect(q.errors?.[0].message).toBeDefined();
+    expect(q.errors?.[0]!.field).toBe("defaultMonthlyQuota");
+    expect(q.errors?.[0]!.message).toBeDefined();
   });
 
   it("UT-IMPORT-008: dry-run preview produces no writes", async () => {
diff --git a/ornn-api/src/domains/settings/exportImport/importer.ts b/ornn-api/src/domains/settings/exportImport/importer.ts
index dc452df1..8a135005 100644
--- a/ornn-api/src/domains/settings/exportImport/importer.ts
+++ b/ornn-api/src/domains/settings/exportImport/importer.ts
@@ -13,12 +13,12 @@
  * @module domains/settings/exportImport/importer
  */
 
-import pino from "pino";
+import { createLogger } from "../../../shared/logger";
 import { sections, type SectionId } from "../sections";
 import type { SettingsActor, SettingsService } from "../types";
 import { SETTINGS_SCHEMA_VERSION } from "./exporter";
 
-const logger = pino({ level: "info" }).child({ module: "settingsImporter" });
+const logger = createLogger("settingsImporter");
 
 export interface ImportInput {
   readonly schemaVersion?: unknown;
diff --git a/ornn-api/src/domains/settings/exportImport/routes.test.ts b/ornn-api/src/domains/settings/exportImport/routes.test.ts
index 312de88b..b643eede 100644
--- a/ornn-api/src/domains/settings/exportImport/routes.test.ts
+++ b/ornn-api/src/domains/settings/exportImport/routes.test.ts
@@ -17,6 +17,7 @@ import {
 } from "./routes";
 import { sections } from "../sections";
 import type { SettingsService } from "../types";
+import { buildProblemJsonBody } from "../../../shared/types/index";
 
 function fakeSettingsService(): SettingsService {
   const store = new Map<string, Record<string, unknown>>();
@@ -78,12 +79,18 @@ function makeApp(opts: {
   // AppError is a domain error; the test app needs a tiny error handler so
   // 4xx surfaces with the expected status (otherwise Hono returns 500).
   app.onError((err, c) => {
-    const code = (err as { code?: string }).code ?? "INTERNAL_ERROR";
+    const code = (err as { code?: string }).code ?? "internal_error";
     const status = (err as { statusCode?: number }).statusCode ?? 500;
-    return c.json(
-      { data: null, error: { code, message: err.message } },
-      status as never,
-    );
+    const body = buildProblemJsonBody({
+      statusCode: status,
+      code,
+      message: err.message,
+      instance: c.req.path,
+      requestId: null,
+    });
+    return c.json(body, status as never, {
+      "Content-Type": "application/problem+json",
+    });
   });
   return { app };
 }
diff --git a/ornn-api/src/domains/settings/exportImport/routes.ts b/ornn-api/src/domains/settings/exportImport/routes.ts
index 9ad83664..2820415c 100644
--- a/ornn-api/src/domains/settings/exportImport/routes.ts
+++ b/ornn-api/src/domains/settings/exportImport/routes.ts
@@ -15,18 +15,19 @@
 
 import { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
-import pino from "pino";
+import { createLogger } from "../../../shared/logger";
+import { z } from "zod";
+import { validateBody, getValidatedBody } from "../../../middleware/validate";
 import {
   type AuthVariables,
   nyxidAuthMiddleware,
   requirePermission,
 } from "../../../middleware/nyxidAuth";
-import { AppError } from "../../../shared/types/index";
 import type { SettingsActor } from "../types";
 import type { SettingsExporter } from "./exporter";
 import type { ImportResult, SettingsImporter } from "./importer";
 
-const logger = pino({ level: "info" }).child({ module: "settingsExportImportRoutes" });
+const logger = createLogger("settingsExportImportRoutes");
 
 /**
  * Settings audit hook. Bootstrap binds this to
@@ -49,7 +50,7 @@ export interface SettingsAuditLogger {
     sections: ReadonlyArray<{
       id: string;
       status: string;
-      changedFields?: ReadonlyArray<string>;
+      changedFields?: ReadonlyArray<string> | undefined;
     }>;
     dryRun: boolean;
   }): Promise<void>;
@@ -63,12 +64,13 @@ const noopAuditLogger: SettingsAuditLogger = {
 export interface ExportImportRoutesConfig {
   readonly exporter: SettingsExporter;
   readonly importer: SettingsImporter;
+  // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
   /** Used in the export filename. Default: `prod`. */
-  readonly envName?: string;
+  readonly envName?: string | undefined;
   /** Audit hook. When omitted, exports/imports go un-audited (test mode). */
-  readonly auditLogger?: SettingsAuditLogger;
+  readonly auditLogger?: SettingsAuditLogger | undefined;
   /** Body-size cap on `POST /import`. Default 1 MiB. */
-  readonly importMaxBytes?: number;
+  readonly importMaxBytes?: number | undefined;
 }
 
 export function createSettingsExportImportRoutes(
@@ -114,18 +116,19 @@ export function createSettingsExportImportRoutes(
           {
             data: null,
             error: {
-              code: "PAYLOAD_TOO_LARGE",
+              code: "payload_too_large",
               message: `import body must be ≤ ${importMaxBytes} bytes`,
             },
           },
           413,
         ),
     }),
+    // The importer (`importer.import`) validates the full structured
+    // payload internally. The middleware here just gates JSON-shape
+    // so a SyntaxError becomes 400 invalid_body per #438.
+    validateBody(z.record(z.string(), z.unknown()), "invalid_body"),
     async (c) => {
-      const body = await c.req.json().catch(() => null);
-      if (!body || typeof body !== "object") {
-        throw AppError.badRequest("INVALID_BODY", "JSON body required");
-      }
+      const body = getValidatedBody<Record<string, unknown>>(c);
       // Accept dryRun from either the body (the SPA path) OR the
       // query string (curl / scripts). Body takes precedence. Was
       // query-only before — that silently mutated on the SPA's
diff --git a/ornn-api/src/domains/settings/llmProviders/migration.ts b/ornn-api/src/domains/settings/llmProviders/migration.ts
index 7408d24f..1757607b 100644
--- a/ornn-api/src/domains/settings/llmProviders/migration.ts
+++ b/ornn-api/src/domains/settings/llmProviders/migration.ts
@@ -23,11 +23,9 @@
  */
 
 import type { Db, Document } from "mongodb";
-import pino from "pino";
+import { createLogger } from "../../../shared/logger";
 
-const logger = pino({ level: "info" }).child({
-  module: "llmProvidersMigration",
-});
+const logger = createLogger("llmProvidersMigration");
 
 interface LegacyModelRow {
   modelId: string;
diff --git a/ornn-api/src/domains/settings/llmProviders/repository.ts b/ornn-api/src/domains/settings/llmProviders/repository.ts
index afda5b9f..d516d6fc 100644
--- a/ornn-api/src/domains/settings/llmProviders/repository.ts
+++ b/ornn-api/src/domains/settings/llmProviders/repository.ts
@@ -111,7 +111,10 @@ export class LlmProvidersRepository {
     const filterField = `m.defaultFor${surface}` as const;
     const arrayFilters: Document[] = [{ [filterField]: true }];
     if (keep) {
-      arrayFilters[0]["m.id"] = { $ne: keep.modelId };
+      // arrayFilters[0] is the single-element object we just pushed
+      // above — guaranteed defined. `!` is safe under
+      // noUncheckedIndexedAccess (#450).
+      arrayFilters[0]!["m.id"] = { $ne: keep.modelId };
     }
     const filter: Document = keep
       ? { _id: { $ne: keep.providerId as unknown as Document["_id"] } }
diff --git a/ornn-api/src/domains/settings/llmProviders/routes.test.ts b/ornn-api/src/domains/settings/llmProviders/routes.test.ts
index 9a5e3089..aee64805 100644
--- a/ornn-api/src/domains/settings/llmProviders/routes.test.ts
+++ b/ornn-api/src/domains/settings/llmProviders/routes.test.ts
@@ -14,6 +14,7 @@ import {
 } from "./service";
 import type { StoredProvider } from "./repository";
 import { createLlmProvidersRoutes } from "./routes";
+import { buildProblemJsonBody } from "../../../shared/types/index";
 
 const KEY = "ornn-test-passphrase-32-chars-min-okOK";
 
@@ -69,12 +70,18 @@ describe("LlmProviders POST", () => {
     });
     app.route("/api/v1", routes);
     app.onError((err, c) => {
-      const code = (err as { code?: string }).code ?? "INTERNAL_ERROR";
+      const code = (err as { code?: string }).code ?? "internal_error";
       const status = (err as { statusCode?: number }).statusCode ?? 500;
-      return c.json(
-        { data: null, error: { code, message: err.message } },
-        status as never,
-      );
+      const body = buildProblemJsonBody({
+        statusCode: status,
+        code,
+        message: err.message,
+        instance: c.req.path,
+        requestId: null,
+      });
+      return c.json(body, status as never, {
+        "Content-Type": "application/problem+json",
+      });
     });
 
     const plaintext = "sk-real-plaintext-secret-12345";
diff --git a/ornn-api/src/domains/settings/llmProviders/routes.ts b/ornn-api/src/domains/settings/llmProviders/routes.ts
index 8e8ba83c..3c740c11 100644
--- a/ornn-api/src/domains/settings/llmProviders/routes.ts
+++ b/ornn-api/src/domains/settings/llmProviders/routes.ts
@@ -33,6 +33,7 @@ import {
   requirePermission,
 } from "../../../middleware/nyxidAuth";
 import { AppError } from "../../../shared/types/index";
+import { validateBody, getValidatedBody } from "../../../middleware/validate";
 import type { SettingsActor } from "../types";
 import type { LlmProvidersService, ModelResolution, Surface } from "./service";
 
@@ -69,6 +70,16 @@ export function throwModelResolutionError(resolution: ModelResolution): never {
 
 export interface LlmProvidersRoutesConfig {
   readonly llmProvidersService: LlmProvidersService;
+  /**
+   * Resolve the per-surface section default model id (#607). When set,
+   * `GET /me/models?surface=…` uses it as the picker's `default` slot
+   * so the frontend pre-selection agrees with the execute path's
+   * `resolveSurfaceDefaults` precedence. Optional so legacy callers
+   * (route-only tests, the admin route bundle) can skip wiring it.
+   */
+  readonly sectionDefaultResolver?: (
+    surface: Surface,
+  ) => Promise<string | null>;
 }
 
 export function createLlmProvidersRoutes(
@@ -85,41 +96,54 @@ export function createLlmProvidersRoutes(
     return c.json({ data: { items }, error: null });
   });
 
-  app.post(base, auth, adminGuard, async (c) => {
-    const body = await c.req.json().catch(() => null);
-    if (!body) throw AppError.badRequest("INVALID_BODY", "JSON body required");
-    const actor = currentActor(c);
-    const created = await llmProvidersService.create(body, actor);
-    // Re-fetch through the admin path so the 201 body never carries
-    // the plaintext secret the caller just submitted.
-    const masked = await llmProvidersService.getForAdmin(created._id);
-    return c.json({ data: masked, error: null }, 201);
-  });
+  app.post(
+    base,
+    auth,
+    adminGuard,
+    // Service-internal Zod schemas (`providerCreateSchema`) enforce
+    // the full shape. The middleware here just gates JSON-shape so a
+    // SyntaxError becomes 400 with RFC 7807 envelope (#438).
+    validateBody(z.record(z.string(), z.unknown()), "invalid_body"),
+    async (c) => {
+      const body = getValidatedBody<Record<string, unknown>>(c);
+      const actor = currentActor(c);
+      const created = await llmProvidersService.create(body, actor);
+      // Re-fetch through the admin path so the 201 body never carries
+      // the plaintext secret the caller just submitted.
+      const masked = await llmProvidersService.getForAdmin(created._id);
+      return c.json({ data: masked, error: null }, 201);
+    },
+  );
 
   app.get(`${base}/:id`, auth, adminGuard, async (c) => {
     const id = c.req.param("id");
     const item = await llmProvidersService.getForAdmin(id);
     if (!item) {
-      throw AppError.notFound("PROVIDER_NOT_FOUND", `No provider ${id}`);
+      throw AppError.notFound("provider_not_found", `No provider ${id}`);
     }
     return c.json({ data: item, error: null });
   });
 
-  app.put(`${base}/:id`, auth, adminGuard, async (c) => {
-    const id = c.req.param("id");
-    const body = await c.req.json().catch(() => null);
-    if (!body) throw AppError.badRequest("INVALID_BODY", "JSON body required");
-    const actor = currentActor(c);
-    await llmProvidersService.update(id, body, actor);
-    const masked = await llmProvidersService.getForAdmin(id);
-    return c.json({ data: masked, error: null });
-  });
+  app.put(
+    `${base}/:id`,
+    auth,
+    adminGuard,
+    validateBody(z.record(z.string(), z.unknown()), "invalid_body"),
+    async (c) => {
+      const id = c.req.param("id");
+      const body = getValidatedBody<Record<string, unknown>>(c);
+      const actor = currentActor(c);
+      await llmProvidersService.update(id, body, actor);
+      const masked = await llmProvidersService.getForAdmin(id);
+      return c.json({ data: masked, error: null });
+    },
+  );
 
   app.delete(`${base}/:id`, auth, adminGuard, async (c) => {
     const id = c.req.param("id");
     const ok = await llmProvidersService.deleteById(id);
     if (!ok) {
-      throw AppError.notFound("PROVIDER_NOT_FOUND", `No provider ${id}`);
+      throw AppError.notFound("provider_not_found", `No provider ${id}`);
     }
     return c.body(null, 204);
   });
@@ -142,11 +166,11 @@ export function createLlmProvidersRoutes(
     `${base}/:id/models/:modelId`,
     auth,
     adminGuard,
+    validateBody(z.record(z.string(), z.unknown()), "invalid_body"),
     async (c) => {
       const providerId = c.req.param("id");
       const modelId = c.req.param("modelId");
-      const body = await c.req.json().catch(() => null);
-      if (!body) throw AppError.badRequest("INVALID_BODY", "JSON body required");
+      const body = getValidatedBody<Record<string, unknown>>(c);
       const actor = currentActor(c);
       await llmProvidersService.patchModel(providerId, modelId, body, actor);
       const masked = await llmProvidersService.getForAdmin(providerId);
@@ -167,7 +191,7 @@ export function createLlmProvidersRoutes(
 export function createLlmPickerRoutes(
   config: LlmProvidersRoutesConfig,
 ): Hono<{ Variables: AuthVariables }> {
-  const { llmProvidersService } = config;
+  const { llmProvidersService, sectionDefaultResolver } = config;
   const app = new Hono<{ Variables: AuthVariables }>();
   const auth = nyxidAuthMiddleware();
 
@@ -176,12 +200,21 @@ export function createLlmPickerRoutes(
     const parsed = surfaceSchema.safeParse(surfaceRaw);
     if (!parsed.success) {
       throw AppError.badRequest(
-        "INVALID_SURFACE",
+        "invalid_surface",
         "Query param 'surface' must be 'playground' or 'skillGen'",
       );
     }
     const surface: Surface = parsed.data;
-    const result = await llmProvidersService.listPickerModels(surface);
+    // #607 — pass the section-level pin through so the picker's
+    // default agrees with the execute path. Resolver is optional;
+    // tests that don't wire it fall back to the per-model flag.
+    const sectionDefault = sectionDefaultResolver
+      ? (await sectionDefaultResolver(surface)) ?? undefined
+      : undefined;
+    const result = await llmProvidersService.listPickerModels(
+      surface,
+      sectionDefault,
+    );
     return c.json({
       data: {
         items: result.items.map((r) => ({
diff --git a/ornn-api/src/domains/settings/llmProviders/service.test.ts b/ornn-api/src/domains/settings/llmProviders/service.test.ts
index 39c4e0b3..e1c4e81f 100644
--- a/ornn-api/src/domains/settings/llmProviders/service.test.ts
+++ b/ornn-api/src/domains/settings/llmProviders/service.test.ts
@@ -179,6 +179,105 @@ describe("LlmProvidersService", () => {
     expect(m.displayName).toBe("GPT-4o (renamed)");
   });
 
+  it("UT-LLM-004a: update WITHOUT models key preserves existing list (#588)", async () => {
+    // The ProviderEditDrawer's basic-settings save sends only name /
+    // gatewayUrl / etc. — no `models` field. Before #588 the update
+    // schema's inherited `.default([])` parsed the missing field as
+    // `[]`, then `if (patch.models)` was truthy on `[]` and silently
+    // wiped the model list. This pins the "undefined means preserve"
+    // contract so a future schema refactor can't regress.
+    const { svc } = makeService();
+    const created = await svc.create(
+      { ...baseInput, auth: { kind: "apiKey", apiKey: "sk-aaaaaa" } },
+      ACTOR,
+    );
+    expect(created.models.length).toBeGreaterThan(0);
+    const updated = await svc.update(
+      created._id,
+      {
+        // basic-settings-only patch — no `models` field whatsoever
+        name: "renamed-provider",
+        maxOutputTokens: 4096,
+      },
+      ACTOR,
+    );
+    expect(updated.name).toBe("renamed-provider");
+    expect(updated.maxOutputTokens).toBe(4096);
+    expect(updated.models.length).toBe(created.models.length);
+    expect(updated.models.map((m) => m.id).sort()).toEqual(
+      created.models.map((m) => m.id).sort(),
+    );
+  });
+
+  it("UT-LLM-004b: update WITH explicit models: [] wipes the list (#588)", async () => {
+    // Symmetry check: passing an explicit empty array IS a valid
+    // "remove everything" intent (e.g. the model-list refresh found
+    // zero models on the upstream provider). The fix must preserve
+    // that path while only treating `undefined` as "don't touch".
+    const { svc } = makeService();
+    const created = await svc.create(
+      { ...baseInput, auth: { kind: "apiKey", apiKey: "sk-aaaaaa" } },
+      ACTOR,
+    );
+    expect(created.models.length).toBeGreaterThan(0);
+    const updated = await svc.update(
+      created._id,
+      { models: [] },
+      ACTOR,
+    );
+    expect(updated.models).toEqual([]);
+  });
+
+  it("UT-LLM-004c: listPickerModels honours sectionDefaultModelId override (#607)", async () => {
+    // Admin pins playground.defaultModelId = "gpt-3.5" via settings.
+    // Without the override the picker would return whichever model
+    // has `defaultForPlayground: true`. With the override the pinned
+    // model wins the `default` slot and lands first in the items list,
+    // matching what `resolveSurfaceDefaults` does on the execute path.
+    const { svc } = makeService();
+    await svc.create(
+      {
+        ...baseInput,
+        name: "alpha",
+        auth: { kind: "apiKey", apiKey: "k1" },
+        models: [
+          {
+            id: "gpt-4o",
+            displayName: "GPT-4o",
+            enabledForPlayground: true,
+            defaultForPlayground: true,
+          },
+          {
+            id: "gpt-3.5",
+            displayName: "GPT-3.5",
+            enabledForPlayground: true,
+          },
+        ],
+      },
+      ACTOR,
+    );
+
+    // No override → per-model flag wins, gpt-4o is default.
+    const noOverride = await svc.listPickerModels("playground");
+    expect(noOverride.default).toBe("gpt-4o");
+    expect(noOverride.items[0]?.modelId).toBe("gpt-4o");
+
+    // With section pin → gpt-3.5 wins.
+    const pinned = await svc.listPickerModels("playground", "gpt-3.5");
+    expect(pinned.default).toBe("gpt-3.5");
+    expect(pinned.items[0]?.modelId).toBe("gpt-3.5");
+    expect(pinned.items[0]?.isDefault).toBe(true);
+    // gpt-4o is still in the list, just no longer marked default.
+    const gpt4o = pinned.items.find((i) => i.modelId === "gpt-4o");
+    expect(gpt4o?.isDefault).toBe(false);
+
+    // Pin points at a disabled/missing model → falls through to the
+    // first enabled item; nothing is marked default.
+    const stalePin = await svc.listPickerModels("playground", "gpt-deprecated");
+    expect(stalePin.items.every((i) => i.isDefault === false)).toBe(true);
+    expect(stalePin.default).toBe(stalePin.items[0]?.modelId ?? null);
+  });
+
   it("UT-LLM-005: sync — newly arrived model lands with all surface flags false", async () => {
     const { svc, fetcher } = makeService();
     const created = await svc.create(
diff --git a/ornn-api/src/domains/settings/llmProviders/service.ts b/ornn-api/src/domains/settings/llmProviders/service.ts
index 5c28cc88..ac26bf5f 100644
--- a/ornn-api/src/domains/settings/llmProviders/service.ts
+++ b/ornn-api/src/domains/settings/llmProviders/service.ts
@@ -35,7 +35,7 @@
  */
 
 import { randomUUID } from "node:crypto";
-import pino from "pino";
+import { createLogger } from "../../../shared/logger";
 import { z, ZodError } from "zod";
 import {
   decryptSecret,
@@ -59,7 +59,7 @@ import type {
   LlmProviderModel,
 } from "./types";
 
-const logger = pino({ level: "info" }).child({ module: "llmProvidersService" });
+const logger = createLogger("llmProvidersService");
 
 /** Surfaces the picker / resolver care about. Mirror of `quota/types.ts:Surface`. */
 export type Surface = "playground" | "skillGen";
@@ -131,7 +131,14 @@ export const providerCreateSchema = z.object({
 
 export type ProviderCreateInput = z.infer<typeof providerCreateSchema>;
 
-export const providerUpdateSchema = providerCreateSchema.partial();
+// #588 — `.partial()` keeps every field's `.default(...)`, so a PATCH
+// that omits `models` was parsed back as `models: []` and silently
+// wiped the persisted model list. Override `models` here so the
+// update path can distinguish "caller didn't send it" (undefined →
+// preserve) from "caller sent empty" (`[]` → wipe explicitly).
+export const providerUpdateSchema = providerCreateSchema
+  .partial()
+  .extend({ models: z.array(modelInputSchema).optional() });
 export type ProviderUpdateInput = z.infer<typeof providerUpdateSchema>;
 
 /**
@@ -238,8 +245,19 @@ export class LlmProvidersService {
    * across all providers, sorted with the surface default first then
    * by display name. The first row's `modelId` is also exposed via
    * `default` for easy "what's the fallback?" UI.
+   *
+   * #607 — `sectionDefaultModelId` is the per-section setting (e.g.
+   * `playground.defaultModelId`) that admins can pin to override the
+   * per-model `defaultForX` flag. When provided AND that model is in
+   * the enabled set, it wins the `default` slot and is sorted first
+   * — same precedence as the execute path's `resolveSurfaceDefaults`
+   * helper in `bootstrap.ts`, so the picker pre-selection and the
+   * execute fallback agree on what "default" means.
    */
-  async listPickerModels(surface: Surface): Promise<{
+  async listPickerModels(
+    surface: Surface,
+    sectionDefaultModelId?: string,
+  ): Promise<{
     items: PickerModelRow[];
     default: string | null;
   }> {
@@ -251,12 +269,18 @@ export class LlmProvidersService {
       for (const m of provider.models) {
         if (m.removed) continue;
         if (m[enabledField] !== true) continue;
+        // Mark the section-pinned model as `isDefault` so the
+        // frontend ModelPicker's "default" badge agrees with the
+        // backend's resolution. Falls back to the per-model
+        // `defaultForX` flag when no section override exists.
+        const isPinned =
+          !!sectionDefaultModelId && m.id === sectionDefaultModelId;
         items.push({
           modelId: m.id,
           displayName: m.displayName,
           providerId: provider._id,
           providerName: provider.name,
-          isDefault: m[defaultField] === true,
+          isDefault: isPinned || (!sectionDefaultModelId && m[defaultField] === true),
         });
       }
     }
@@ -334,7 +358,10 @@ export class LlmProvidersService {
       return { kind: "no-models-enabled", surface };
     }
     enabledList.sort((a, b) => a.displayName.localeCompare(b.displayName));
-    const winner = defaultMatch ?? enabledList[0];
+    // Length-guarded above (`enabledList.length === 0` returns), so
+    // index 0 is guaranteed defined — `!` is safe under
+    // `noUncheckedIndexedAccess` (#450).
+    const winner = defaultMatch ?? enabledList[0]!;
     return {
       kind: "ok",
       modelId: winner.modelId,
@@ -399,15 +426,18 @@ export class LlmProvidersService {
   ): Promise<LlmProvider> {
     const existing = await this.repo.findById(id);
     if (!existing) {
-      throw AppError.notFound("PROVIDER_NOT_FOUND", `No provider ${id}`);
+      throw AppError.notFound("provider_not_found", `No provider ${id}`);
     }
     const patch = parse(providerUpdateSchema, input);
 
     // Models update: if the caller passed `models`, replace the list
     // wholesale BUT preserve `firstSeenAt` for any incoming model that
-    // already exists — only sync changes lifecycle dates.
+    // already exists — only sync changes lifecycle dates. #588: an
+    // explicit `[]` from the caller IS a valid "wipe all" intent (e.g.
+    // the model-list refresh found zero models); only `undefined`
+    // (field absent in the PATCH) means "don't touch".
     let models = existing.models;
-    if (patch.models) {
+    if (patch.models !== undefined) {
       const now = this.clock();
       const previousMap = new Map(existing.models.map((m) => [m.id, m]));
       models = patch.models.map((m) => {
@@ -480,7 +510,7 @@ export class LlmProvidersService {
     const flags = parse(modelFlagsPatchSchema, input);
     const existing = await this.repo.findById(providerId);
     if (!existing) {
-      throw AppError.notFound("PROVIDER_NOT_FOUND", `No provider ${providerId}`);
+      throw AppError.notFound("provider_not_found", `No provider ${providerId}`);
     }
     const idx = existing.models.findIndex((m) => m.id === modelId);
     if (idx === -1) {
@@ -489,7 +519,9 @@ export class LlmProvidersService {
         `Model "${modelId}" not on provider "${existing.name}"`,
       );
     }
-    const current = existing.models[idx];
+    // idx is guaranteed in-range — we just confirmed via findIndex
+    // above. `!` is safe under noUncheckedIndexedAccess (#450).
+    const current = existing.models[idx]!;
     if (current.removed) {
       throw AppError.badRequest(
         "MODEL_REMOVED",
@@ -570,7 +602,7 @@ export class LlmProvidersService {
   }> {
     const existing = await this.repo.findById(id);
     if (!existing) {
-      throw AppError.notFound("PROVIDER_NOT_FOUND", `No provider ${id}`);
+      throw AppError.notFound("provider_not_found", `No provider ${id}`);
     }
     const decryptedAuth = this.decryptAuth(existing.auth);
     let upstream: ReadonlyArray<{ id: string; displayName: string }>;
@@ -805,8 +837,10 @@ function parse<T extends z.ZodTypeAny>(
 }
 
 function zodToAppError(err: ZodError): AppError {
-  const first = err.issues[0];
+  // ZodError always carries at least one issue when `safeParse` returns
+  // success: false. `!` is safe under noUncheckedIndexedAccess (#450).
+  const first = err.issues[0]!;
   const path = first.path.join(".");
   const msg = path.length > 0 ? `${path}: ${first.message}` : first.message;
-  return AppError.badRequest("INVALID_PROVIDER_INPUT", msg);
+  return AppError.badRequest("invalid_provider_input", msg);
 }
diff --git a/ornn-api/src/domains/settings/routes.ts b/ornn-api/src/domains/settings/routes.ts
index c4efc21c..2f729a0d 100644
--- a/ornn-api/src/domains/settings/routes.ts
+++ b/ornn-api/src/domains/settings/routes.ts
@@ -17,8 +17,9 @@ import {
   nyxidAuthMiddleware,
   requirePermission,
 } from "../../middleware/nyxidAuth";
-import { AppError } from "../../shared/types/index";
+import { z } from "zod";
 import { midMaskSecret } from "../../infra/crypto";
+import { validateBody, getValidatedBody } from "../../middleware/validate";
 import { sections, type SectionId } from "./sections";
 import type { SettingsService, SettingsActor } from "./types";
 
@@ -48,24 +49,30 @@ export function createSettingsRoutes(
       return c.json({ data: masked, error: null });
     });
 
-    app.put(path, auth, adminGuard, async (c) => {
-      const body = await c.req.json().catch(() => null);
-      if (!body || typeof body !== "object") {
-        throw AppError.badRequest("INVALID_BODY", "request body must be a JSON object");
-      }
-      const actor = currentActor(c);
-      const result = await settingsService.putSection<Record<string, unknown>>(
-        id,
-        body as Record<string, unknown>,
-        actor,
-      );
-      const masked = maskSecrets(result.value, meta.secretFields);
-      return c.json({
-        data: masked,
-        error: null,
-        meta: { changedFields: result.changedFields },
-      });
-    });
+    app.put(
+      path,
+      auth,
+      adminGuard,
+      // Section-specific Zod schemas live inside `settingsService.putSection`;
+      // here we just gate that the body is a JSON object so a SyntaxError
+      // becomes 400 invalid_body instead of a 500 (#438).
+      validateBody(z.record(z.string(), z.unknown()), "invalid_body"),
+      async (c) => {
+        const body = getValidatedBody<Record<string, unknown>>(c);
+        const actor = currentActor(c);
+        const result = await settingsService.putSection<Record<string, unknown>>(
+          id,
+          body,
+          actor,
+        );
+        const masked = maskSecrets(result.value, meta.secretFields);
+        return c.json({
+          data: masked,
+          error: null,
+          meta: { changedFields: result.changedFields },
+        });
+      },
+    );
   }
 
   return app;
diff --git a/ornn-api/src/domains/settings/sections/mirror.ts b/ornn-api/src/domains/settings/sections/mirror.ts
index 8cce1344..847541fe 100644
--- a/ornn-api/src/domains/settings/sections/mirror.ts
+++ b/ornn-api/src/domains/settings/sections/mirror.ts
@@ -32,6 +32,10 @@ const cronSchedule = z
         CronExpressionParser.parse(s);
         return true;
       } catch {
+        // Intentional silent (#579): the false return becomes a Zod
+        // validation error with the message below — that's the
+        // user-facing signal. Logging the cron-parser exception would
+        // be noisy on every form-validation typo.
         return false;
       }
     },
diff --git a/ornn-api/src/domains/settings/service.test.ts b/ornn-api/src/domains/settings/service.test.ts
index 8512d991..c2dd82a6 100644
--- a/ornn-api/src/domains/settings/service.test.ts
+++ b/ornn-api/src/domains/settings/service.test.ts
@@ -213,7 +213,7 @@ describe("SettingsServiceImpl", () => {
       err = e;
     }
     expect(err).toBeTruthy();
-    expect((err as { code: string }).code).toBe("INVALID_SETTING");
+    expect((err as { code: string }).code).toBe("invalid_setting");
     expect((err as { message: string }).message).toContain("sseKeepAliveMs");
   });
 
diff --git a/ornn-api/src/domains/settings/service.ts b/ornn-api/src/domains/settings/service.ts
index 77d0c0f3..d7ac959c 100644
--- a/ornn-api/src/domains/settings/service.ts
+++ b/ornn-api/src/domains/settings/service.ts
@@ -19,7 +19,7 @@
  * @module domains/settings/service
  */
 
-import pino from "pino";
+import { createLogger } from "../../shared/logger";
 import { ZodError } from "zod";
 import {
   decryptSecret,
@@ -46,7 +46,7 @@ import type {
   SettingsService,
 } from "./types";
 
-const logger = pino({ level: "info" }).child({ module: "settingsService" });
+const logger = createLogger("settingsService");
 
 export interface SettingsServiceDeps {
   readonly repo: SettingsRepository;
@@ -258,13 +258,20 @@ function shallowEqual(a: unknown, b: unknown): boolean {
   try {
     return JSON.stringify(a) === JSON.stringify(b);
   } catch {
+    // Intentional silent (#579): JSON.stringify throws only on circular
+    // refs — section payloads in this collection are plain Mongo
+    // documents and have never been circular. If they ever become so,
+    // we want change-detection to fail-safe (treat as changed) without
+    // crashing the settings save path. No log spam needed.
     return false;
   }
 }
 
 function zodToAppError(err: ZodError): AppError {
-  const first = err.issues[0];
+  // ZodError always carries at least one issue when `safeParse` returns
+  // success: false. `!` is safe under noUncheckedIndexedAccess (#450).
+  const first = err.issues[0]!;
   const path = first.path.join(".");
   const msg = path.length > 0 ? `${path}: ${first.message}` : first.message;
-  return AppError.badRequest("INVALID_SETTING", msg);
+  return AppError.badRequest("invalid_setting", msg);
 }
diff --git a/ornn-api/src/domains/settings/types.ts b/ornn-api/src/domains/settings/types.ts
index 3cff7bd2..dd08eb31 100644
--- a/ornn-api/src/domains/settings/types.ts
+++ b/ornn-api/src/domains/settings/types.ts
@@ -27,7 +27,9 @@ import type { LlmProvider } from "./llmProviders/types";
 export interface SettingsActor {
   readonly userId: string;
   readonly email: string;
-  readonly displayName?: string;
+  // exactOptionalPropertyTypes (#657): widen to allow `undefined` so
+  // callers passing nyxidAuth's `string | undefined` displayName fit.
+  readonly displayName?: string | undefined;
 }
 
 /**
diff --git a/ornn-api/src/domains/skills/audit/repository.ts b/ornn-api/src/domains/skills/audit/repository.ts
index b68899e3..fd537f5a 100644
--- a/ornn-api/src/domains/skills/audit/repository.ts
+++ b/ornn-api/src/domains/skills/audit/repository.ts
@@ -9,7 +9,7 @@
 
 import { randomUUID } from "node:crypto";
 import type { Db, Collection, Document } from "mongodb";
-import pino from "pino";
+import { createLogger } from "../../../shared/logger";
 import type {
   AuditFinding,
   AuditRecord,
@@ -18,7 +18,7 @@ import type {
   AuditVerdict,
 } from "./types";
 
-const logger = pino({ level: "info" }).child({ module: "auditRepository" });
+const logger = createLogger("auditRepository");
 
 export interface CreateRunningInput {
   skillGuid: string;
diff --git a/ornn-api/src/domains/skills/audit/routes.ts b/ornn-api/src/domains/skills/audit/routes.ts
index 0b696949..d530eae8 100644
--- a/ornn-api/src/domains/skills/audit/routes.ts
+++ b/ornn-api/src/domains/skills/audit/routes.ts
@@ -16,7 +16,8 @@
  */
 
 import { Hono } from "hono";
-import pino from "pino";
+import { createLogger } from "../../../shared/logger";
+import { z } from "zod";
 import type { AuditService } from "./service";
 import type { SkillService } from "../crud/service";
 import {
@@ -28,9 +29,15 @@ import {
   requirePermission,
 } from "../../../middleware/nyxidAuth";
 import { AppError } from "../../../shared/types/index";
+import { validateBody, getValidatedBody } from "../../../middleware/validate";
 import { canReadSkill } from "../crud/authorize";
 
-const logger = pino({ level: "info" }).child({ module: "auditRoutes" });
+/** Body schema for POST /skills/:idOrName/audit + admin variant (#438). */
+const auditTriggerSchema = z.object({
+  force: z.boolean().optional(),
+});
+
+const logger = createLogger("auditRoutes");
 
 export interface AuditRoutesConfig {
   auditService: AuditService;
@@ -62,7 +69,7 @@ export function createAuditRoutes(config: AuditRoutesConfig): Hono<{ Variables:
       const skill = await skillService.getSkill(idOrName, version);
 
       if (!authCtx && skill.isPrivate) {
-        throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+        throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
       }
       if (authCtx && skill.isPrivate) {
         const memberships = await readUserOrgMemberships(c);
@@ -72,7 +79,7 @@ export function createAuditRoutes(config: AuditRoutesConfig): Hono<{ Variables:
           isPlatformAdmin: authCtx.permissions.includes("ornn:admin:skill"),
         };
         if (!canReadSkill(skill, actor)) {
-          throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+          throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
         }
       }
 
@@ -80,7 +87,7 @@ export function createAuditRoutes(config: AuditRoutesConfig): Hono<{ Variables:
       if (!record) {
         // No audit yet — surface that as 404 so callers can distinguish
         // from a record that returned zeroes.
-        throw AppError.notFound("AUDIT_NOT_FOUND", "No audit has been run for this skill version");
+        throw AppError.notFound("audit_not_found", "No audit has been run for this skill version");
       }
       return c.json({ data: record, error: null });
     },
@@ -102,7 +109,7 @@ export function createAuditRoutes(config: AuditRoutesConfig): Hono<{ Variables:
 
       const skill = await skillService.getSkill(idOrName);
       if (!authCtx && skill.isPrivate) {
-        throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+        throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
       }
       if (authCtx && skill.isPrivate) {
         const memberships = await readUserOrgMemberships(c);
@@ -112,7 +119,7 @@ export function createAuditRoutes(config: AuditRoutesConfig): Hono<{ Variables:
           isPlatformAdmin: authCtx.permissions.includes("ornn:admin:skill"),
         };
         if (!canReadSkill(skill, actor)) {
-          throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+          throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
         }
       }
 
@@ -139,7 +146,7 @@ export function createAuditRoutes(config: AuditRoutesConfig): Hono<{ Variables:
       const skill = await skillService.getSkill(idOrName);
 
       if (!authCtx && skill.isPrivate) {
-        throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+        throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
       }
       if (authCtx && skill.isPrivate) {
         const memberships = await readUserOrgMemberships(c);
@@ -149,7 +156,7 @@ export function createAuditRoutes(config: AuditRoutesConfig): Hono<{ Variables:
           isPlatformAdmin: authCtx.permissions.includes("ornn:admin:skill"),
         };
         if (!canReadSkill(skill, actor)) {
-          throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+          throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
         }
       }
 
@@ -167,17 +174,17 @@ export function createAuditRoutes(config: AuditRoutesConfig): Hono<{ Variables:
   app.post(
     "/skills/:idOrName/audit",
     auth,
+    validateBody(auditTriggerSchema, "invalid_audit_body"),
     async (c) => {
       const idOrName = c.req.param("idOrName");
       const authCtx = getAuth(c);
-      const body = (await c.req.json().catch(() => ({}))) as { force?: unknown };
-      const force = body.force === true;
+      const { force = false } = getValidatedBody<z.infer<typeof auditTriggerSchema>>(c);
 
       const skill = await skillService.getSkill(idOrName);
       const isPlatformAdmin = authCtx.permissions.includes("ornn:admin:skill");
       if (skill.createdBy !== authCtx.userId && !isPlatformAdmin) {
         throw AppError.forbidden(
-          "NOT_SKILL_OWNER",
+          "not_skill_owner",
           "Only the skill's author or a platform admin can start an audit",
         );
       }
@@ -200,11 +207,11 @@ export function createAuditRoutes(config: AuditRoutesConfig): Hono<{ Variables:
     "/admin/skills/:idOrName/audit",
     auth,
     requirePermission("ornn:admin:skill"),
+    validateBody(auditTriggerSchema, "invalid_audit_body"),
     async (c) => {
       const idOrName = c.req.param("idOrName");
       const authCtx = getAuth(c);
-      const body = (await c.req.json().catch(() => ({}))) as { force?: unknown };
-      const force = body.force === true;
+      const { force = false } = getValidatedBody<z.infer<typeof auditTriggerSchema>>(c);
 
       logger.info({ idOrName, triggeredBy: authCtx.userId, force }, "Admin audit triggered");
       const record = await auditService.runAudit(idOrName, {
diff --git a/ornn-api/src/domains/skills/audit/service.ts b/ornn-api/src/domains/skills/audit/service.ts
index ddce8f88..1145d6c7 100644
--- a/ornn-api/src/domains/skills/audit/service.ts
+++ b/ornn-api/src/domains/skills/audit/service.ts
@@ -11,7 +11,7 @@
  * @module domains/skills/audit/service
  */
 
-import pino from "pino";
+import { createLogger } from "../../../shared/logger";
 import type { NyxLlmClient, ResponsesApiInputMessage } from "../../../clients/nyxid/llm";
 import type { IStorageClient } from "../../../clients/storageClient";
 import type { NyxidOrgsClient } from "../../../clients/nyxid/orgs";
@@ -32,7 +32,7 @@ import { AUDIT_SYSTEM_PROMPT, buildAuditUserPrompt } from "./prompts";
 import JSZip from "jszip";
 import { resolveZipRoot } from "../../../shared/utils/zip";
 
-const logger = pino({ level: "info" }).child({ module: "auditService" });
+const logger = createLogger("auditService");
 
 /**
  * Per-call resolution of the audit pipeline's LLM defaults. Sourced
@@ -92,8 +92,9 @@ export class AuditService {
   private readonly llmClient: NyxLlmClient;
   private readonly defaultsResolver: AuditDefaultsResolver;
   private readonly cacheTtlMs: number;
-  private readonly notificationService?: NotificationService;
-  private readonly nyxidOrgsClient?: NyxidOrgsClient;
+  // exactOptionalPropertyTypes (#657): widen to `T | undefined`.
+  private readonly notificationService: NotificationService | undefined;
+  private readonly nyxidOrgsClient: NyxidOrgsClient | undefined;
 
   constructor(deps: AuditServiceDeps) {
     this.auditRepo = deps.auditRepo;
@@ -355,7 +356,7 @@ export class AuditService {
     // Prefer the skill doc's presigned URL — `getSkill` already minted one.
     const url = (skillDoc as unknown as { presignedPackageUrl?: string }).presignedPackageUrl;
     if (!url) {
-      throw AppError.internalError("AUDIT_PACKAGE_UNAVAILABLE", "No storage URL for skill package");
+      throw AppError.internalError("audit_package_unavailable", "No storage URL for skill package");
     }
     const res = await fetch(url);
     if (!res.ok) {
@@ -375,7 +376,11 @@ export class AuditService {
 
     for (const path of allPaths) {
       const entry = zip.files[path];
-      if (entry.dir) continue;
+      // `allPaths` is built from `Object.keys(zip.files)` upstream, so
+      // every path resolves. Defensive null-check under
+      // noUncheckedIndexedAccess (#450) — drop the file rather than
+      // crash if a future refactor introduces a mismatch.
+      if (!entry || entry.dir) continue;
       const parts = path.split("/");
       let relative = path;
       if (parts.length > 1 && zip.files[`${parts[0]}/`]?.dir) {
@@ -391,8 +396,11 @@ export class AuditService {
         }
         chunks.push(`// FILE: ${relative}\n${text}`);
         bundledBytes += text.length;
-      } catch {
-        // skip unreadable files
+      } catch (err) {
+        // Skip unreadable files — binary blobs and zip-entry decode
+        // errors land here. Logging so an audit that quietly drops
+        // every file (e.g. a JSZip regression) becomes visible.
+        logger.debug({ err, relative }, "audit: skipping unreadable file");
       }
     }
 
@@ -429,7 +437,15 @@ export function parseAuditJson(raw: string): ParsedAudit | null {
   let obj: unknown;
   try {
     obj = JSON.parse(slice);
-  } catch {
+  } catch (err) {
+    // Audit LLM produced malformed JSON — parseAuditJson returns null
+    // and the caller (Service.scan) treats it as "no audit produced"
+    // and falls back gracefully. Log the head of the slice so we can
+    // catch a pattern of the LLM repeatedly mis-formatting output.
+    logger.debug(
+      { err, sliceHead: slice.slice(0, 120) },
+      "parseAuditJson: malformed JSON slice",
+    );
     return null;
   }
   if (!obj || typeof obj !== "object") return null;
diff --git a/ornn-api/src/domains/skills/audit/types.ts b/ornn-api/src/domains/skills/audit/types.ts
index 3f3a2945..4fc730a6 100644
--- a/ornn-api/src/domains/skills/audit/types.ts
+++ b/ornn-api/src/domains/skills/audit/types.ts
@@ -74,9 +74,9 @@ export interface AuditRecord {
   readonly model: string;
   readonly createdAt: Date;
   /** When the record moved from `running` to a terminal state. */
-  readonly completedAt?: Date;
+  readonly completedAt?: Date | undefined;
   /** Populated when status === "failed". */
-  readonly errorMessage?: string;
+  readonly errorMessage?: string | undefined;
   /**
    * User who triggered the audit. `system` when the audit-on-share
    * pipeline kicked it off automatically (to be wired in a later PR).
diff --git a/ornn-api/src/domains/skills/crud/distTags.test.ts b/ornn-api/src/domains/skills/crud/distTags.test.ts
new file mode 100644
index 00000000..84176157
--- /dev/null
+++ b/ornn-api/src/domains/skills/crud/distTags.test.ts
@@ -0,0 +1,119 @@
+/**
+ * Tests for dist-tag helpers added in #463.
+ *
+ * Coverage: tag-name validation + `?version=@<tag>` resolution logic.
+ * The full service + repo + routes integration is exercised by the
+ * route test below (real Mongo).
+ *
+ * @module domains/skills/crud/distTags.test
+ */
+
+import { describe, expect, test } from "bun:test";
+import { AppError } from "../../../shared/types/index";
+import type { SkillDocument } from "../../../shared/types/index";
+import { isValidTagName, resolveDistTag } from "./service";
+
+function fakeSkill(overrides: Partial<SkillDocument>): SkillDocument {
+  return {
+    guid: "s1",
+    name: "demo",
+    description: "",
+    license: null,
+    compatibility: null,
+    metadata: { category: "plain" },
+    skillHash: "",
+    storageKey: "",
+    createdBy: "u1",
+    createdOn: new Date(),
+    updatedBy: "u1",
+    updatedOn: new Date(),
+    isPrivate: false,
+    sharedWithUsers: [],
+    sharedWithOrgs: [],
+    latestVersion: "1.0",
+    ...overrides,
+  };
+}
+
+describe("isValidTagName", () => {
+  test.each([
+    ["latest", true],
+    ["stable", true],
+    ["next", true],
+    ["rc-1", true],
+    ["beta-2", true],
+    ["a", true],
+    // npm-style: max 50 chars
+    ["a".repeat(50), true],
+  ])("accepts %s", (tag, expected) => {
+    expect(isValidTagName(tag)).toBe(expected);
+  });
+
+  test.each([
+    ["", false],
+    ["Latest", false], // uppercase
+    ["1stable", false], // leading digit
+    ["a".repeat(51), false], // over 50
+    ["with space", false],
+    ["with.dot", false],
+    ["@latest", false], // leading @ rejected at this layer
+    ["-leading", false],
+  ])("rejects %s", (tag, expected) => {
+    expect(isValidTagName(tag)).toBe(expected);
+  });
+});
+
+describe("resolveDistTag (#463)", () => {
+  test("literal version passes through verbatim", () => {
+    const skill = fakeSkill({});
+    expect(resolveDistTag(skill, "1.5")).toBe("1.5");
+    expect(resolveDistTag(skill, "0.1")).toBe("0.1");
+  });
+
+  test("empty string returns undefined (caller wants latest)", () => {
+    const skill = fakeSkill({});
+    expect(resolveDistTag(skill, "")).toBeUndefined();
+  });
+
+  test("@<tag> resolves via distTags map", () => {
+    const skill = fakeSkill({
+      distTags: { latest: "1.5", stable: "1.4", beta: "2.0" },
+    });
+    expect(resolveDistTag(skill, "@stable")).toBe("1.4");
+    expect(resolveDistTag(skill, "@beta")).toBe("2.0");
+    expect(resolveDistTag(skill, "@latest")).toBe("1.5");
+  });
+
+  test("@latest falls back to skill.latestVersion on legacy skills (no distTags field)", () => {
+    // Skills published before #463 have no distTags field; `@latest`
+    // should still work for backwards-compat — the cached
+    // `latestVersion` pointer is the right answer.
+    const skill = fakeSkill({ latestVersion: "2.3" });
+    expect(resolveDistTag(skill, "@latest")).toBe("2.3");
+  });
+
+  test("missing non-latest tag throws skill_version_not_found", () => {
+    const skill = fakeSkill({ distTags: { latest: "1.0" } });
+    let caught: unknown = null;
+    try {
+      resolveDistTag(skill, "@stable");
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(AppError);
+    expect((caught as AppError).code).toBe("skill_version_not_found");
+    expect((caught as AppError).statusCode).toBe(404);
+  });
+
+  test("@ with no tag name throws invalid_dist_tag", () => {
+    const skill = fakeSkill({});
+    let caught: unknown = null;
+    try {
+      resolveDistTag(skill, "@");
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(AppError);
+    expect((caught as AppError).code).toBe("invalid_dist_tag");
+  });
+});
diff --git a/ornn-api/src/domains/skills/crud/interfaceDiff.test.ts b/ornn-api/src/domains/skills/crud/interfaceDiff.test.ts
index d3714ff1..6ea79dae 100644
--- a/ornn-api/src/domains/skills/crud/interfaceDiff.test.ts
+++ b/ornn-api/src/domains/skills/crud/interfaceDiff.test.ts
@@ -32,9 +32,9 @@ describe("diffSkillInterface", () => {
     });
     const changes = diffSkillInterface(prev, next);
     expect(changes).toHaveLength(1);
-    expect(changes[0].field).toBe("tools");
-    expect(changes[0].kind).toBe("added");
-    expect(changes[0].detail).toContain("edit");
+    expect(changes[0]!.field).toBe("tools");
+    expect(changes[0]!.kind).toBe("added");
+    expect(changes[0]!.detail).toContain("edit");
   });
 
   test("removing a tool is breaking", () => {
@@ -48,8 +48,8 @@ describe("diffSkillInterface", () => {
     const next = meta({ category: "tool-based", tools: [{ tool: "bash", type: "mcp" }] });
     const changes = diffSkillInterface(prev, next);
     expect(changes).toHaveLength(1);
-    expect(changes[0].kind).toBe("removed");
-    expect(changes[0].detail).toContain("edit");
+    expect(changes[0]!.kind).toBe("removed");
+    expect(changes[0]!.detail).toContain("edit");
   });
 
   test("adding a runtime is breaking", () => {
diff --git a/ornn-api/src/domains/skills/crud/repositories/skillRepository.interface.ts b/ornn-api/src/domains/skills/crud/repositories/skillRepository.interface.ts
deleted file mode 100644
index e9353235..00000000
--- a/ornn-api/src/domains/skills/crud/repositories/skillRepository.interface.ts
+++ /dev/null
@@ -1,112 +0,0 @@
-/**
- * Interface definitions for skill repository operations.
- * Aligned with design spec: uses guid, name, description, license,
- * compatibility, metadata (nested), skillHash, s3Url, createdBy,
- * createdOn, updatedBy, updatedOn, isPrivate.
- * @module repositories/skillRepository.interface
- */
-
-/** The MongoDB document shape for a skill, matching the design spec. */
-export interface SkillDocument {
-  guid: string;
-  name: string;
-  description: string;
-  license: string | null;
-  compatibility: string | null;
-  metadata: SkillMetadata;
-  skillHash: string;
-  s3Url: string;
-  createdBy: string;
-  createdOn: Date;
-  updatedBy: string;
-  updatedOn: Date;
-  isPrivate: boolean;
-}
-
-/** Nested metadata object per spec. */
-export interface SkillMetadata {
-  category: string;
-  runtimes?: Array<{
-    runtime: string;
-    dependencies?: Array<{ library: string; version: string }>;
-    envs?: Array<{ var: string; description: string }>;
-  }>;
-  tools?: Array<{
-    tool: string;
-    type: string;
-    "mcp-servers"?: Array<{ mcp: string; version: string }>;
-  }>;
-  tags?: string[];
-}
-
-export interface CreateSkillData {
-  guid: string;
-  name: string;
-  description: string;
-  license?: string;
-  compatibility?: string;
-  metadata: SkillMetadata;
-  skillHash: string;
-  s3Url: string;
-  createdBy: string;
-  isPrivate?: boolean;
-}
-
-export interface UpdateSkillData {
-  name?: string;
-  description?: string;
-  license?: string;
-  compatibility?: string;
-  metadata?: SkillMetadata;
-  skillHash?: string;
-  s3Url?: string;
-  isPrivate?: boolean;
-  updatedBy: string;
-}
-
-export interface SkillFilters {
-  /** Text query for keyword search (GUID exact match or name/description contains). */
-  q?: string;
-  /** Filter by scope: public, private (by ownerId), or mixed. */
-  scope?: "public" | "private" | "mixed";
-  /** The current user ID (needed for private/mixed scope). */
-  currentUserId?: string;
-  page: number;
-  pageSize: number;
-}
-
-export interface ISkillRepository {
-  findByGuid(guid: string): Promise<SkillDocument | null>;
-  findByName(name: string): Promise<SkillDocument | null>;
-  findAll(filters: SkillFilters): Promise<{ skills: SkillDocument[]; total: number }>;
-  create(data: CreateSkillData): Promise<SkillDocument>;
-  update(guid: string, data: UpdateSkillData): Promise<SkillDocument>;
-  hardDelete(guid: string): Promise<void>;
-
-  /**
-   * Keyword search: exact GUID match + name/description contains.
-   * Filters by scope.
-   */
-  keywordSearch(
-    query: string,
-    scope: "public" | "private" | "mixed",
-    currentUserId: string,
-    page: number,
-    pageSize: number,
-  ): Promise<{ skills: SkillDocument[]; total: number }>;
-
-  /**
-   * Scope-filtered find for paginated listing (empty query = all in scope).
-   */
-  findByScope(
-    scope: "public" | "private" | "mixed",
-    currentUserId: string,
-    page: number,
-    pageSize: number,
-  ): Promise<{ skills: SkillDocument[]; total: number }>;
-
-  /**
-   * Find skills by a list of GUIDs (used for similarity search post-filter).
-   */
-  findByGuids(guids: string[]): Promise<SkillDocument[]>;
-}
diff --git a/ornn-api/src/domains/skills/crud/repositories/skillRepository.test.ts b/ornn-api/src/domains/skills/crud/repositories/skillRepository.test.ts
deleted file mode 100644
index b75ae85a..00000000
--- a/ornn-api/src/domains/skills/crud/repositories/skillRepository.test.ts
+++ /dev/null
@@ -1,203 +0,0 @@
-import { describe, test, expect, beforeEach, mock } from "bun:test";
-import { SkillRepository } from "./skillRepository";
-import type { Db } from "mongodb";
-
-/**
- * Unit tests for the MongoDB-backed SkillRepository.
- * Uses mocked MongoDB Collection to verify query construction.
- */
-
-function createMockCursor(docs: any[] = []) {
-  return {
-    sort: mock(function (this: any) { return this; }),
-    skip: mock(function (this: any) { return this; }),
-    limit: mock(function (this: any) { return this; }),
-    toArray: mock(async () => docs),
-  };
-}
-
-function createMockCollection() {
-  return {
-    insertOne: mock(async () => ({ acknowledged: true })),
-    // Explicitly broaden the mock's return type so tests can override with
-    // any shaped document via `.mockResolvedValue(...)`.
-    findOne: mock(async (): Promise<Record<string, unknown> | null> => null),
-    find: mock(() => createMockCursor()),
-    updateOne: mock(async () => ({ modifiedCount: 1 })),
-    deleteOne: mock(async () => ({ deletedCount: 1 })),
-    countDocuments: mock(async () => 0),
-  };
-}
-
-function createMockDb(): { db: Db; skillsCol: ReturnType<typeof createMockCollection> } {
-  const skillsCol = createMockCollection();
-  const db = {
-    collection: mock((name: string) => {
-      if (name === "skills") return skillsCol;
-      return createMockCollection();
-    }),
-  } as unknown as Db;
-  return { db, skillsCol };
-}
-
-/** Build a minimal valid MongoDB document for a skill. */
-function makeSkillDoc(overrides: Record<string, unknown> = {}): Record<string, unknown> {
-  return {
-    _id: "test-guid-1",
-    name: "my-skill",
-    description: "A test skill",
-    license: null,
-    compatibility: null,
-    metadata: { category: "plain" },
-    skillHash: "abc123",
-    s3Url: "s3://bucket/skills/test-guid-1.zip",
-    createdBy: "user-1",
-    createdOn: new Date("2026-01-01"),
-    updatedBy: "user-1",
-    updatedOn: new Date("2026-01-01"),
-    isPrivate: true,
-    ...overrides,
-  };
-}
-
-describe("SkillRepository", () => {
-  let db: Db;
-  let skillsCol: ReturnType<typeof createMockCollection>;
-  let repo: SkillRepository;
-
-  beforeEach(() => {
-    const mocks = createMockDb();
-    db = mocks.db;
-    skillsCol = mocks.skillsCol;
-    repo = new SkillRepository(db);
-  });
-
-  describe("create", () => {
-    test("create_ValidData_CallsInsertOne", async () => {
-      skillsCol.findOne.mockResolvedValue(makeSkillDoc());
-
-      const result = await repo.create({
-        guid: "test-guid-1",
-        name: "my-skill",
-        description: "A test skill",
-        metadata: { category: "plain" },
-        skillHash: "abc123",
-        s3Url: "s3://bucket/skills/test-guid-1.zip",
-        createdBy: "user-1",
-      });
-
-      expect(skillsCol.insertOne).toHaveBeenCalled();
-      expect(result.guid).toBe("test-guid-1");
-      expect(result.name).toBe("my-skill");
-    });
-  });
-
-  describe("findByGuid", () => {
-    test("findByGuid_ExistingGuid_ReturnsSkill", async () => {
-      skillsCol.findOne.mockResolvedValue(makeSkillDoc());
-
-      const found = await repo.findByGuid("test-guid-1");
-      expect(found).not.toBeNull();
-      expect(found!.name).toBe("my-skill");
-    });
-
-    test("findByGuid_NonExistentGuid_ReturnsNull", async () => {
-      const found = await repo.findByGuid("nonexistent");
-      expect(found).toBeNull();
-    });
-  });
-
-  describe("findByName", () => {
-    test("findByName_ExistingName_ReturnsSkill", async () => {
-      skillsCol.findOne.mockResolvedValue(makeSkillDoc());
-
-      const found = await repo.findByName("my-skill");
-      expect(found).not.toBeNull();
-      expect(found!.guid).toBe("test-guid-1");
-    });
-
-    test("findByName_NonExistentName_ReturnsNull", async () => {
-      const found = await repo.findByName("nonexistent");
-      expect(found).toBeNull();
-    });
-  });
-
-  describe("hardDelete", () => {
-    test("hardDelete_CallsDeleteOne", async () => {
-      await repo.hardDelete("test-guid-1");
-      expect(skillsCol.deleteOne).toHaveBeenCalled();
-    });
-  });
-
-  describe("keywordSearch", () => {
-    test("keywordSearch_WithQuery_CallsFindAndReturnsResults", async () => {
-      const mockDoc = makeSkillDoc();
-      skillsCol.find.mockReturnValue(createMockCursor([mockDoc]));
-      skillsCol.countDocuments.mockResolvedValue(1);
-
-      const results = await repo.keywordSearch("my-skill", "public", "", 1, 10);
-
-      expect(skillsCol.find).toHaveBeenCalled();
-      expect(results.skills).toHaveLength(1);
-      expect(results.total).toBe(1);
-      expect(results.skills[0].name).toBe("my-skill");
-    });
-
-    test("keywordSearch_NoMatches_ReturnsEmpty", async () => {
-      const results = await repo.keywordSearch("nonexistent", "public", "", 1, 10);
-      expect(results.skills).toEqual([]);
-      expect(results.total).toBe(0);
-    });
-  });
-
-  describe("findByScope", () => {
-    test("findByScope_PublicScope_CallsFindWithIsPrivateFalse", async () => {
-      const mockDoc = makeSkillDoc({ isPrivate: false });
-      skillsCol.find.mockReturnValue(createMockCursor([mockDoc]));
-      skillsCol.countDocuments.mockResolvedValue(1);
-
-      const results = await repo.findByScope("public", "", 1, 10);
-
-      expect(skillsCol.find).toHaveBeenCalled();
-      expect(results.skills).toHaveLength(1);
-      expect(results.total).toBe(1);
-    });
-
-    test("findByScope_NoMatches_ReturnsEmpty", async () => {
-      const results = await repo.findByScope("public", "", 1, 10);
-      expect(results.skills).toEqual([]);
-      expect(results.total).toBe(0);
-    });
-  });
-
-  describe("findByGuids", () => {
-    test("findByGuids_EmptyList_ReturnsEmpty", async () => {
-      const results = await repo.findByGuids([]);
-      expect(results).toEqual([]);
-    });
-
-    test("findByGuids_WithGuids_CallsFind", async () => {
-      const mockDoc = makeSkillDoc();
-      skillsCol.find.mockReturnValue(createMockCursor([mockDoc]));
-
-      const results = await repo.findByGuids(["test-guid-1"]);
-
-      expect(skillsCol.find).toHaveBeenCalled();
-      expect(results).toHaveLength(1);
-    });
-  });
-
-  describe("update", () => {
-    test("update_ValidData_CallsUpdateOneAndReturnsUpdated", async () => {
-      skillsCol.findOne.mockResolvedValue(makeSkillDoc({ name: "updated-skill" }));
-
-      const result = await repo.update("test-guid-1", {
-        name: "updated-skill",
-        updatedBy: "user-1",
-      });
-
-      expect(skillsCol.updateOne).toHaveBeenCalled();
-      expect(result.name).toBe("updated-skill");
-    });
-  });
-});
diff --git a/ornn-api/src/domains/skills/crud/repositories/skillRepository.ts b/ornn-api/src/domains/skills/crud/repositories/skillRepository.ts
deleted file mode 100644
index e895db10..00000000
--- a/ornn-api/src/domains/skills/crud/repositories/skillRepository.ts
+++ /dev/null
@@ -1,218 +0,0 @@
-/**
- * MongoDB-backed skill repository implementation.
- * Aligned with design spec schema: guid, name, description, license,
- * compatibility, metadata, skillHash, s3Url, createdBy, createdOn,
- * updatedBy, updatedOn, isPrivate.
- * @module repositories/skillRepository
- */
-
-import type { Collection, Db, Document } from "mongodb";
-import type {
-  ISkillRepository,
-  SkillDocument,
-  SkillMetadata,
-  CreateSkillData,
-  UpdateSkillData,
-  SkillFilters,
-} from "./skillRepository.interface";
-import { isDuplicateKeyError, AppError } from "../../../../shared/types/index";
-
-// Re-export interfaces
-export type { ISkillRepository, SkillDocument, SkillMetadata, CreateSkillData, UpdateSkillData, SkillFilters };
-
-export class SkillRepository implements ISkillRepository {
-  private readonly collection: Collection;
-
-  constructor(db: Db) {
-    this.collection = db.collection("skills");
-  }
-
-  async findByGuid(guid: string): Promise<SkillDocument | null> {
-    const doc = await this.collection.findOne({ _id: guid as any });
-    return mapDoc(doc);
-  }
-
-  async findByName(name: string): Promise<SkillDocument | null> {
-    const doc = await this.collection.findOne({ name });
-    return mapDoc(doc);
-  }
-
-  async findAll(filters: SkillFilters): Promise<{ skills: SkillDocument[]; total: number }> {
-    const matchStage: Record<string, unknown> = {};
-    applyScope(matchStage, filters.scope ?? "private", filters.currentUserId ?? "");
-
-    if (filters.q) {
-      matchStage.$or = [
-        { _id: filters.q },
-        { name: { $regex: escapeRegex(filters.q), $options: "i" } },
-        { description: { $regex: escapeRegex(filters.q), $options: "i" } },
-      ];
-    }
-
-    const total = await this.collection.countDocuments(matchStage);
-    const offset = (filters.page - 1) * filters.pageSize;
-    const docs = await this.collection
-      .find(matchStage)
-      .sort({ createdOn: -1 })
-      .skip(offset)
-      .limit(filters.pageSize)
-      .toArray();
-
-    return { skills: docs.map((d) => mapDoc(d)!), total };
-  }
-
-  async create(data: CreateSkillData): Promise<SkillDocument> {
-    const now = new Date();
-    const doc: Record<string, unknown> = {
-      _id: data.guid as any,
-      name: data.name,
-      description: data.description,
-      license: data.license ?? null,
-      compatibility: data.compatibility ?? null,
-      metadata: data.metadata,
-      skillHash: data.skillHash,
-      s3Url: data.s3Url,
-      createdBy: data.createdBy,
-      createdOn: now,
-      updatedBy: data.createdBy,
-      updatedOn: now,
-      isPrivate: data.isPrivate ?? true,
-    };
-
-    try {
-      await this.collection.insertOne(doc);
-    } catch (err) {
-      if (isDuplicateKeyError(err)) {
-        throw AppError.conflict("SKILL_NAME_EXISTS", `Skill '${data.name}' already exists`);
-      }
-      throw err;
-    }
-
-    return mapDoc(doc)!;
-  }
-
-  async update(guid: string, data: UpdateSkillData): Promise<SkillDocument> {
-    const setFields: Record<string, unknown> = {
-      updatedBy: data.updatedBy,
-      updatedOn: new Date(),
-    };
-
-    if (data.name !== undefined) setFields.name = data.name;
-    if (data.description !== undefined) setFields.description = data.description;
-    if (data.license !== undefined) setFields.license = data.license;
-    if (data.compatibility !== undefined) setFields.compatibility = data.compatibility;
-    if (data.metadata !== undefined) setFields.metadata = data.metadata;
-    if (data.skillHash !== undefined) setFields.skillHash = data.skillHash;
-    if (data.s3Url !== undefined) setFields.s3Url = data.s3Url;
-    if (data.isPrivate !== undefined) setFields.isPrivate = data.isPrivate;
-
-    await this.collection.updateOne({ _id: guid as any }, { $set: setFields });
-    return (await this.findByGuid(guid))!;
-  }
-
-  async hardDelete(guid: string): Promise<void> {
-    await this.collection.deleteOne({ _id: guid as any });
-  }
-
-  async keywordSearch(
-    query: string,
-    scope: "public" | "private" | "mixed",
-    currentUserId: string,
-    page: number,
-    pageSize: number,
-  ): Promise<{ skills: SkillDocument[]; total: number }> {
-    const matchStage: Record<string, unknown> = {};
-    applyScope(matchStage, scope, currentUserId);
-
-    matchStage.$or = [
-      { _id: query },
-      { name: { $regex: escapeRegex(query), $options: "i" } },
-      { description: { $regex: escapeRegex(query), $options: "i" } },
-    ];
-
-    const total = await this.collection.countDocuments(matchStage);
-    const offset = (page - 1) * pageSize;
-    const docs = await this.collection
-      .find(matchStage)
-      .sort({ createdOn: -1 })
-      .skip(offset)
-      .limit(pageSize)
-      .toArray();
-
-    return { skills: docs.map((d) => mapDoc(d)!), total };
-  }
-
-  async findByScope(
-    scope: "public" | "private" | "mixed",
-    currentUserId: string,
-    page: number,
-    pageSize: number,
-  ): Promise<{ skills: SkillDocument[]; total: number }> {
-    const matchStage: Record<string, unknown> = {};
-    applyScope(matchStage, scope, currentUserId);
-
-    const total = await this.collection.countDocuments(matchStage);
-    const offset = (page - 1) * pageSize;
-    const docs = await this.collection
-      .find(matchStage)
-      .sort({ createdOn: -1 })
-      .skip(offset)
-      .limit(pageSize)
-      .toArray();
-
-    return { skills: docs.map((d) => mapDoc(d)!), total };
-  }
-
-  async findByGuids(guids: string[]): Promise<SkillDocument[]> {
-    if (guids.length === 0) return [];
-    const docs = await this.collection.find({ _id: { $in: guids } as any }).toArray();
-    return docs.map((d) => mapDoc(d)!);
-  }
-}
-
-// ==========================================================================
-// Helper functions
-// ==========================================================================
-
-/** Apply scope filter to a MongoDB match stage. */
-function applyScope(
-  matchStage: Record<string, unknown>,
-  scope: "public" | "private" | "mixed",
-  currentUserId: string,
-): void {
-  if (scope === "public") {
-    matchStage.isPrivate = false;
-  } else if (scope === "private") {
-    matchStage.createdBy = currentUserId;
-  } else if (scope === "mixed") {
-    matchStage.$or = [
-      { isPrivate: false },
-      { createdBy: currentUserId },
-    ];
-  }
-}
-
-/** Map a MongoDB document to a SkillDocument. */
-function mapDoc(doc: Document | null): SkillDocument | null {
-  if (!doc) return null;
-  return {
-    guid: doc._id as string,
-    name: doc.name,
-    description: doc.description,
-    license: doc.license ?? null,
-    compatibility: doc.compatibility ?? null,
-    metadata: doc.metadata ?? { category: "plain" },
-    skillHash: doc.skillHash ?? "",
-    s3Url: doc.s3Url ?? "",
-    createdBy: doc.createdBy ?? "",
-    createdOn: doc.createdOn ?? doc.created_at ?? new Date(),
-    updatedBy: doc.updatedBy ?? "",
-    updatedOn: doc.updatedOn ?? doc.updated_at ?? new Date(),
-    isPrivate: doc.isPrivate ?? true,
-  };
-}
-
-/** Escape special regex characters for safe use in RegExp constructor. */
-function escapeRegex(str: string): string {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
diff --git a/ornn-api/src/domains/skills/crud/repository.ts b/ornn-api/src/domains/skills/crud/repository.ts
index 93dd06ce..3765b85c 100644
--- a/ornn-api/src/domains/skills/crud/repository.ts
+++ b/ornn-api/src/domains/skills/crud/repository.ts
@@ -6,32 +6,67 @@
 import type { Collection, Db, Document } from "mongodb";
 import type { SkillDocument, SkillMetadata } from "../../../shared/types/index";
 import { AppError } from "../../../shared/types/index";
-import pino from "pino";
+import { createLogger } from "../../../shared/logger";
+/**
+ * Coerce a string GUID into the shape MongoDB's driver expects for
+ * `_id` queries on the skills collection (#448). The collection uses
+ * UUID strings instead of `ObjectId`s; the driver's filter typing
+ * (`ObjectId | string` discriminator) doesn't see that without help.
+ *
+ * One named helper instead of `as any` at every call site:
+ *   - validates the input (empty string would silently match zero
+ *     docs, the failure mode the issue flagged)
+ *   - keeps the necessary cast in a single, named place
+ *
+ * Return type is `never` so the call site accepts both `findOne`
+ * filters and `insertOne` documents — the actual stored value is a
+ * string, but the driver's type slot is `ObjectId`.
+ */
+function skillId(guid: string): never {
+  if (typeof guid !== "string" || guid.length === 0) {
+    throw AppError.badRequest(
+      "invalid_skill_id",
+      "Skill id must be a non-empty string",
+    );
+  }
+  return guid as never;
+}
 
-const logger = pino({ level: "info" }).child({ module: "skillCrudRepository" });
+/** Same shape for `$in` filters on `_id`. Validates each guid up front. */
+function skillIdList(guids: readonly string[]): never {
+  for (const g of guids) {
+    if (typeof g !== "string" || g.length === 0) {
+      throw AppError.badRequest(
+        "invalid_skill_id",
+        "Skill id must be a non-empty string",
+      );
+    }
+  }
+  return guids as never;
+}
 
+const logger = createLogger("skillCrudRepository");
+
+// Optionals widen to `T | undefined` so route layers passing Zod-
+// inferred or other optional inputs fit under
+// exactOptionalPropertyTypes (#657). Repo writes ignore undefined keys.
 export interface CreateSkillData {
   guid: string;
   name: string;
   description: string;
-  license?: string;
-  compatibility?: string;
+  license?: string | undefined;
+  compatibility?: string | undefined;
   metadata: SkillMetadata;
   skillHash: string;
   storageKey: string;
-  /**
-   * Legacy back-compat field. New skills copy `createdBy` here; visibility
-   * logic no longer consults it. Defaults to `createdBy` when omitted.
-   */
-  ownerId?: string;
   createdBy: string;
-  createdByEmail?: string;
-  createdByDisplayName?: string;
-  isPrivate?: boolean;
+  createdByEmail?: string | undefined;
+  createdByDisplayName?: string | undefined;
+  isPrivate?: boolean | undefined;
   /** Initial version, e.g. "1.0". Required. */
   latestVersion: string;
   /** Origin metadata when the skill was created via a pull from an external source. */
-  source?: import("../../../shared/types/index").SkillSource;
+  source?: import("../../../shared/types/index").SkillSource | undefined;
 }
 
 export interface UpdateSkillData {
@@ -74,20 +109,21 @@ export interface SkillFilters {
  * user" chip row).
  */
 export interface ExtraFilters {
-  sharedWithOrgsAny?: string[];
-  sharedWithUsersAny?: string[];
-  createdByAny?: string[];
+  // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
+  sharedWithOrgsAny?: string[] | undefined;
+  sharedWithUsersAny?: string[] | undefined;
+  createdByAny?: string[] | undefined;
   /**
    * Tri-state system-skill filter applied at the DB match level.
    * `"only"`    → `isSystemSkill: true`.
    * `"exclude"` → `isSystemSkill !== true` (covers absent / false / null).
    * `"any"` / undefined → no constraint.
    */
-  systemFilter?: "any" | "only" | "exclude";
+  systemFilter?: "any" | "only" | "exclude" | undefined;
   /** Restrict to skills tied to this exact NyxID service id. */
-  nyxidServiceId?: string;
+  nyxidServiceId?: string | undefined;
   /** Skills must have ALL listed tags (AND match against `metadata.tags`). */
-  tagsAll?: string[];
+  tagsAll?: string[] | undefined;
 }
 
 export class SkillRepository {
@@ -97,8 +133,31 @@ export class SkillRepository {
     this.collection = db.collection("skills");
   }
 
+  /**
+   * Ensure indexes the skill collection relies on. Idempotent —
+   * MongoDB's createIndex is a no-op when the index already exists
+   * with the same key + options. Called from bootstrap on startup.
+   *
+   * The `name` + `description` indexes feed both the admin regex
+   * search (#446) and the keyword + skill-detail lookups in
+   * service.ts.
+   */
+  async ensureIndexes(): Promise<void> {
+    await Promise.all([
+      this.collection.createIndex({ name: 1 }, { unique: true }),
+      // Partial regex queries can't use a btree index on a long text
+      // field, but having the field indexed at all lets the query
+      // planner skip the COLLSCAN when the regex is anchored or when
+      // the secondary `createdBy` / `isPrivate` filter is present.
+      this.collection.createIndex({ description: 1 }),
+      this.collection.createIndex({ createdBy: 1, createdOn: -1 }),
+      this.collection.createIndex({ createdOn: -1 }),
+      this.collection.createIndex({ isPrivate: 1, createdOn: -1 }),
+    ]);
+  }
+
   async findByGuid(guid: string): Promise<SkillDocument | null> {
-    const doc = await this.collection.findOne({ _id: guid as any });
+    const doc = await this.collection.findOne({ _id: skillId(guid) });
     return mapDoc(doc);
   }
 
@@ -110,7 +169,7 @@ export class SkillRepository {
   async create(data: CreateSkillData): Promise<SkillDocument> {
     const now = new Date();
     const doc: Record<string, unknown> = {
-      _id: data.guid as any,
+      _id: skillId(data.guid),
       name: data.name,
       description: data.description,
       license: data.license ?? null,
@@ -118,7 +177,6 @@ export class SkillRepository {
       metadata: data.metadata,
       skillHash: data.skillHash,
       storageKey: data.storageKey,
-      ownerId: data.ownerId ?? data.createdBy,
       createdBy: data.createdBy,
       createdByEmail: data.createdByEmail ?? null,
       createdByDisplayName: data.createdByDisplayName ?? null,
@@ -142,7 +200,7 @@ export class SkillRepository {
       logger.info({ guid: data.guid, name: data.name }, "Skill created");
     } catch (err: any) {
       if (err?.code === 11000) {
-        throw AppError.conflict("SKILL_NAME_EXISTS", `Skill '${data.name}' already exists`);
+        throw AppError.conflict("skill_name_exists", `Skill '${data.name}' already exists`);
       }
       throw err;
     }
@@ -169,13 +227,41 @@ export class SkillRepository {
     if (data.source !== undefined) setFields.source = data.source;
     if (data.latestVersion !== undefined) setFields.latestVersion = data.latestVersion;
 
-    await this.collection.updateOne({ _id: guid as any }, { $set: setFields });
+    await this.collection.updateOne({ _id: skillId(guid) }, { $set: setFields });
     logger.info({ guid }, "Skill updated");
     return (await this.findByGuid(guid))!;
   }
 
+  /**
+   * Set a single dist-tag (#463) atomically via `$set` on a dotted path.
+   * Doesn't validate that `version` exists — that's the service's job;
+   * the repo just writes whatever's handed in.
+   */
+  async setDistTag(guid: string, tag: string, version: string): Promise<void> {
+    await this.collection.updateOne(
+      { _id: skillId(guid) },
+      { $set: { [`distTags.${tag}`]: version, updatedOn: new Date() } },
+    );
+    logger.info({ guid, tag, version }, "Dist-tag set");
+  }
+
+  /**
+   * Remove a single dist-tag (#463). `$unset` on a dotted path leaves
+   * sibling tags intact; if the resulting object would be empty the
+   * field stays as `{}` (mongo cleans it up on the next full doc
+   * write). Callers that care about empty-object cleanup can
+   * subsequently `$unset` the parent.
+   */
+  async deleteDistTag(guid: string, tag: string): Promise<void> {
+    await this.collection.updateOne(
+      { _id: skillId(guid) },
+      { $unset: { [`distTags.${tag}`]: "" }, $set: { updatedOn: new Date() } },
+    );
+    logger.info({ guid, tag }, "Dist-tag deleted");
+  }
+
   async hardDelete(guid: string): Promise<void> {
-    await this.collection.deleteOne({ _id: guid as any });
+    await this.collection.deleteOne({ _id: skillId(guid) });
     logger.info({ guid }, "Skill hard-deleted");
   }
 
@@ -187,7 +273,7 @@ export class SkillRepository {
    */
   async clearSource(guid: string, updatedBy: string): Promise<SkillDocument | null> {
     await this.collection.updateOne(
-      { _id: guid as any },
+      { _id: skillId(guid) },
       {
         $set: { updatedBy, updatedOn: new Date() },
         $unset: { source: "" },
@@ -225,7 +311,7 @@ export class SkillRepository {
     if (data.isPrivate !== undefined) {
       setFields.isPrivate = data.isPrivate;
     }
-    await this.collection.updateOne({ _id: guid as any }, { $set: setFields });
+    await this.collection.updateOne({ _id: skillId(guid) }, { $set: setFields });
     logger.info(
       { guid, nyxidServiceId: data.nyxidServiceId, isSystemSkill: data.isSystemSkill },
       "Skill NyxID service tie updated",
@@ -343,7 +429,7 @@ export class SkillRepository {
 
     const docs = await this.collection
       .find(matchStage)
-      .project({ _id: 1, name: 1, description: 1, metadata: 1, isPrivate: 1, ownerId: 1, sharedWithUsers: 1, sharedWithOrgs: 1, createdBy: 1, createdByEmail: 1, createdByDisplayName: 1, createdOn: 1, updatedOn: 1, storageKey: 1, skillHash: 1, license: 1, compatibility: 1, updatedBy: 1 })
+      .project({ _id: 1, name: 1, description: 1, metadata: 1, isPrivate: 1, sharedWithUsers: 1, sharedWithOrgs: 1, createdBy: 1, createdByEmail: 1, createdByDisplayName: 1, createdOn: 1, updatedOn: 1, storageKey: 1, skillHash: 1, license: 1, compatibility: 1, updatedBy: 1 })
       .sort({ createdOn: -1 })
       .toArray();
 
@@ -352,7 +438,7 @@ export class SkillRepository {
 
   async findByGuids(guids: string[]): Promise<SkillDocument[]> {
     if (guids.length === 0) return [];
-    const docs = await this.collection.find({ _id: { $in: guids } as any }).toArray();
+    const docs = await this.collection.find({ _id: { $in: skillIdList(guids) } }).toArray();
     return docs.map((d) => mapDoc(d)!);
   }
 
@@ -853,9 +939,6 @@ function mapDoc(doc: Document | null): SkillDocument | null {
     metadata: doc.metadata ?? { category: "plain" },
     skillHash: doc.skillHash ?? "",
     storageKey: doc.storageKey ?? doc.s3Url ?? "",
-    // `ownerId` is a legacy field — new skills copy `createdBy` into it.
-    // Fallback keeps pre-migration reads sane.
-    ownerId: doc.ownerId ?? doc.createdBy ?? "",
     createdBy: doc.createdBy ?? "",
     createdByEmail: doc.createdByEmail ?? undefined,
     createdByDisplayName: doc.createdByDisplayName ?? undefined,
@@ -907,9 +990,23 @@ function mapDoc(doc: Document | null): SkillDocument | null {
             commitSha: doc.mirrorSync.commitSha,
           }
         : undefined,
+    // Dist-tags (#463). Coerce defensively — pre-#463 docs have no
+    // field; corrupted entries with non-string values get filtered.
+    distTags: mapDistTags(doc.distTags),
   };
 }
 
+function mapDistTags(raw: unknown): Record<string, string> | undefined {
+  if (!raw || typeof raw !== "object") return undefined;
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+    if (typeof v === "string" && v.length > 0) {
+      out[k] = v;
+    }
+  }
+  return Object.keys(out).length === 0 ? undefined : out;
+}
+
 function escapeRegex(str: string): string {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
diff --git a/ornn-api/src/domains/skills/crud/routes.ts b/ornn-api/src/domains/skills/crud/routes.ts
index 447ebeb9..5409d451 100644
--- a/ornn-api/src/domains/skills/crud/routes.ts
+++ b/ornn-api/src/domains/skills/crud/routes.ts
@@ -27,8 +27,9 @@ import { validateBody, getValidatedBody } from "../../../middleware/validate";
 import { AppError } from "../../../shared/types/index";
 import { canReadSkill, canManageSkill } from "./authorize";
 import { parseGithubUrl } from "./utils/githubPull";
-import pino from "pino";
-
+import { enforceZipLimits } from "../../../shared/utils/zipLimits";
+import { rateLimit } from "../../../middleware/rateLimit";
+import { createLogger } from "../../../shared/logger";
 const deprecationPatchSchema = z.object({
   isDeprecated: z.boolean(),
   deprecationNote: z.string().max(1024).optional(),
@@ -55,7 +56,64 @@ const nyxidServicePatchSchema = z.object({
   nyxidServiceId: z.string().min(1).max(128).nullable(),
 });
 
-const logger = pino({ level: "info" }).child({ module: "skillCrudRoutes" });
+/**
+ * Body for `PUT /api/v1/skills/:id/dist-tags/:tag` (#463). Just the
+ * version string the tag should point at; the service validates that
+ * the version exists.
+ */
+const distTagSetSchema = z.object({
+  version: z
+    .string()
+    .min(1)
+    .max(20)
+    .regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)$/, "version must be <major>.<minor>"),
+});
+
+/**
+ * Body for `POST /api/v1/skills/pull` (#438). Either `githubUrl` (a
+ * single browser-bar URL the server parses into repo/ref/path) OR an
+ * explicit `repo` (with optional `ref`/`path`). A cross-field refine
+ * checks that at least one is provided so we don't reach the handler
+ * with an empty body.
+ */
+const skillPullSchema = z
+  .object({
+    githubUrl: z.string().min(1).optional(),
+    repo: z.string().min(1).optional(),
+    ref: z.string().optional(),
+    path: z.string().optional(),
+    skip_validation: z.boolean().optional(),
+  })
+  .refine((b) => Boolean(b.githubUrl) || Boolean(b.repo), {
+    message: "Provide either 'githubUrl' (preferred) or 'repo' (with optional 'ref'/'path').",
+  });
+
+/**
+ * Body for `POST /api/v1/skills/:id/refresh` (#438). All fields optional.
+ * `skipValidation` and `skip_validation` are both accepted for
+ * backward compatibility with the original ad-hoc handler.
+ */
+const skillRefreshSchema = z.object({
+  dryRun: z.boolean().optional(),
+  skipValidation: z.boolean().optional(),
+  skip_validation: z.boolean().optional(),
+});
+
+/**
+ * Body for `PUT /api/v1/skills/:id/source` (#438). The url field is
+ * a discriminated union: `string` to link, `null` to clear. Anything
+ * else is rejected with a clear ZodIssue.
+ */
+const skillSourceSchema = z.object({
+  githubUrl: z.union([z.string().min(1), z.null()]),
+});
+
+/** Body for `PUT /api/v1/skills/:id` JSON-only branch (#438). ZIP branch handled separately. */
+const skillUpdateJsonSchema = z.object({
+  isPrivate: z.boolean().optional(),
+});
+
+const logger = createLogger("skillCrudRoutes");
 
 export interface SkillRoutesConfig {
   skillService: SkillService;
@@ -201,18 +259,22 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
     "/skills",
     auth,
     requirePermission("ornn:skill:create"),
+    // Rate limit (#439): upload runs the ZIP validator + storage write
+    // + AgentSeal scan. Per-user 10/min is generous for legitimate
+    // publishing flow and stops a runaway script from filling storage.
+    rateLimit({ windowMs: 60_000, max: 10, label: "skills-create" }),
     async (c) => {
       const authCtx = getAuth(c);
       const skipValidation = c.req.query("skip_validation") === "true";
 
       const contentType = c.req.header("content-type") ?? "";
       if (!contentType.includes("application/zip") && !contentType.includes("application/octet-stream")) {
-        throw AppError.badRequest("INVALID_CONTENT_TYPE", "Expected application/zip content type");
+        throw AppError.badRequest("invalid_content_type", "Expected application/zip content type");
       }
 
       const body = await c.req.arrayBuffer();
       if (!body || body.byteLength === 0) {
-        throw AppError.badRequest("EMPTY_BODY", "Request body is empty");
+        throw AppError.badRequest("empty_body", "Request body is empty");
       }
 
       if (body.byteLength > maxFileSize) {
@@ -220,6 +282,14 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
       }
 
       const zipBuffer = new Uint8Array(body);
+
+      // Zip-bomb defense (#633). Walks the central directory without
+      // extracting; throws 413 (`uncompressed_too_large` / `too_many_files`
+      // / `invalid_zip`) before validateZipFormat / storage upload /
+      // AgentSeal subprocess. Cheap, runs ahead of every expensive
+      // side-effect.
+      await enforceZipLimits(zipBuffer);
+
       const userEmail = authCtx.email || undefined;
       const userDisplayName = authCtx.displayName || undefined;
 
@@ -248,7 +318,12 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
       // mirror service log the "considered + skipped" decision.
       fireMirrorSync(result.guid);
 
-      return c.json({ data: skill, error: null });
+      // CONVENTIONS.md §3.2 (#458): POST that creates a resource MUST
+      // return 201 Created with a Location header pointing at the
+      // canonical URL. Existing 200 + envelope clients are unaffected
+      // — the response body is unchanged, only status code + header.
+      c.header("Location", `/api/v1/skills/${skill.guid}`);
+      return c.json({ data: skill, error: null }, 201);
     },
   );
 
@@ -265,24 +340,16 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
     "/skills/pull",
     auth,
     requirePermission("ornn:skill:create"),
+    validateBody(skillPullSchema, "invalid_pull_body"),
     async (c) => {
       const authCtx = getAuth(c);
-      const body = (await c.req.json().catch(() => ({}))) as {
-        // Preferred: a single GitHub folder URL the user copied from the
-        // browser address bar. Server parses out repo / ref / path.
-        githubUrl?: unknown;
-        // Legacy / explicit form: caller already split the source apart.
-        repo?: unknown;
-        ref?: unknown;
-        path?: unknown;
-        skip_validation?: unknown;
-      };
+      const body = getValidatedBody<z.infer<typeof skillPullSchema>>(c);
 
       let repo: string;
       let ref: string | undefined;
       let path: string | undefined;
 
-      if (typeof body.githubUrl === "string" && body.githubUrl) {
+      if (body.githubUrl) {
         try {
           const parsed = parseGithubUrl(body.githubUrl);
           repo = parsed.repo;
@@ -290,19 +357,16 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
           path = parsed.path;
         } catch (err) {
           throw AppError.badRequest(
-            "INVALID_GITHUB_URL",
+            "invalid_github_url",
             err instanceof Error ? err.message : String(err),
           );
         }
-      } else if (typeof body.repo === "string" && body.repo) {
-        repo = body.repo;
-        ref = typeof body.ref === "string" && body.ref ? body.ref : undefined;
-        path = typeof body.path === "string" ? body.path : undefined;
       } else {
-        throw AppError.badRequest(
-          "MISSING_SOURCE",
-          "Provide either 'githubUrl' (preferred) or 'repo' (with optional 'ref'/'path').",
-        );
+        // .refine() in the schema guarantees we have at least one of
+        // githubUrl/repo, so this branch is the explicit-repo form.
+        repo = body.repo!;
+        ref = body.ref;
+        path = body.path;
       }
 
       const skipValidation = body.skip_validation === true;
@@ -335,11 +399,13 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
         // so the contract is uniform across both create flows.
         fireMirrorSync(guid);
 
-        return c.json({ data: skill, error: null });
+        // 201 + Location, parity with POST /skills (#458).
+        c.header("Location", `/api/v1/skills/${skill.guid}`);
+        return c.json({ data: skill, error: null }, 201);
       } catch (err) {
         if (err instanceof AppError) throw err;
         const message = err instanceof Error ? err.message : String(err);
-        throw AppError.badRequest("PULL_FAILED", message);
+        throw AppError.badRequest("pull_failed", message);
       }
     },
   );
@@ -354,14 +420,11 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
     "/skills/:id/refresh",
     auth,
     requirePermission("ornn:skill:update"),
+    validateBody(skillRefreshSchema, "invalid_refresh_body"),
     async (c) => {
       const authCtx = getAuth(c);
       const guid = c.req.param("id");
-      const body = (await c.req.json().catch(() => ({}))) as {
-        dryRun?: unknown;
-        skipValidation?: unknown;
-        skip_validation?: unknown;
-      };
+      const body = getValidatedBody<z.infer<typeof skillRefreshSchema>>(c);
       const dryRun = body.dryRun === true;
       const skipValidation = body.skipValidation === true || body.skip_validation === true;
 
@@ -369,7 +432,7 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
       const isPlatformAdmin = authCtx.permissions.includes("ornn:admin:skill");
       if (existing.createdBy !== authCtx.userId && !isPlatformAdmin) {
         throw AppError.forbidden(
-          "NOT_SKILL_OWNER",
+          "not_skill_owner",
           "Only the skill's author or a platform admin may refresh it",
         );
       }
@@ -384,7 +447,7 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
         } catch (err) {
           if (err instanceof AppError) throw err;
           const message = err instanceof Error ? err.message : String(err);
-          throw AppError.badRequest("REFRESH_PREVIEW_FAILED", message);
+          throw AppError.badRequest("refresh_preview_failed", message);
         }
       }
 
@@ -420,7 +483,7 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
       } catch (err) {
         if (err instanceof AppError) throw err;
         const message = err instanceof Error ? err.message : String(err);
-        throw AppError.badRequest("REFRESH_FAILED", message);
+        throw AppError.badRequest("refresh_failed", message);
       }
     },
   );
@@ -441,32 +504,21 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
     "/skills/:id/source",
     auth,
     requirePermission("ornn:skill:update"),
+    validateBody(skillSourceSchema, "invalid_source_body"),
     async (c) => {
       const authCtx = getAuth(c);
       const guid = c.req.param("id");
-      const body = (await c.req.json().catch(() => ({}))) as { githubUrl?: unknown };
+      const { githubUrl } = getValidatedBody<z.infer<typeof skillSourceSchema>>(c);
 
       const existing = await skillService.getSkill(guid);
       const isPlatformAdmin = authCtx.permissions.includes("ornn:admin:skill");
       if (existing.createdBy !== authCtx.userId && !isPlatformAdmin) {
         throw AppError.forbidden(
-          "NOT_SKILL_OWNER",
+          "not_skill_owner",
           "Only the skill's author or a platform admin may set its source",
         );
       }
 
-      let githubUrl: string | null;
-      if (body.githubUrl === null) {
-        githubUrl = null;
-      } else if (typeof body.githubUrl === "string") {
-        githubUrl = body.githubUrl;
-      } else {
-        throw AppError.badRequest(
-          "INVALID_BODY",
-          "Body must include 'githubUrl' as a string (to link) or null (to unlink).",
-        );
-      }
-
       const updated = await skillService.setSkillSource(guid, githubUrl, authCtx.userId);
 
       logger.info(
@@ -495,6 +547,14 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
   /**
    * GET /skills/:idOrName/json — Return skill package as JSON with all file contents.
    * Requires: ornn:skill:read
+   *
+   * Query params:
+   *   - `version` (optional, #639) — literal `<major>.<minor>` or a
+   *     dist-tag (#463). When provided, the response carries that
+   *     version's package; otherwise latest is returned. Lets the
+   *     install-prompt `curl` / `nyxid proxy request` commands pin
+   *     to the version the user was viewing instead of silently
+   *     pulling whatever's `latest` at install time.
    */
   app.get(
     "/skills/:idOrName/json",
@@ -502,8 +562,32 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
     requirePermission("ornn:skill:read"),
     async (c) => {
       const idOrName = c.req.param("idOrName");
-      logger.info({ idOrName }, "Skill jsonize request");
-      const result = await skillService.getSkillJson(idOrName);
+      const version = c.req.query("version");
+      logger.info({ idOrName, version: version ?? null }, "Skill jsonize request");
+
+      // Visibility check (#567) — the package contents endpoint must
+      // not be more permissive than the metadata endpoint. Load the
+      // skill first and reject inaccessible private skills with the
+      // same `SKILL_NOT_FOUND` shape `/skills/:idOrName` uses.
+      const skill = await skillService.getSkill(idOrName);
+      if (skill.isPrivate) {
+        const authCtx = c.get("auth");
+        // `requirePermission` above guarantees authCtx is set.
+        if (!authCtx) {
+          throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
+        }
+        const memberships = await readUserOrgMemberships(c);
+        const actor = {
+          userId: authCtx.userId,
+          memberships,
+          isPlatformAdmin: authCtx.permissions.includes("ornn:admin:skill"),
+        };
+        if (!canReadSkill(skill, actor)) {
+          throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
+        }
+      }
+
+      const result = await skillService.getSkillJson(idOrName, version);
       // Programmatic pull — closest signal to the north-star metric.
       // Fire-and-forget; the analytics service swallows its own errors.
       const authCtx = c.get("auth");
@@ -550,7 +634,7 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
       const skill = await skillService.getSkill(idOrName);
       // Anonymous viewers only see public skills.
       if (!authCtx && skill.isPrivate) {
-        throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+        throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
       }
       if (authCtx && skill.isPrivate) {
         const memberships = await readUserOrgMemberships(c);
@@ -560,7 +644,7 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
           isPlatformAdmin: authCtx.permissions.includes("ornn:admin:skill"),
         };
         if (!canReadSkill(skill, actor)) {
-          throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+          throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
         }
       }
 
@@ -590,7 +674,7 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
 
       const skill = await skillService.getSkill(idOrName);
       if (!authCtx && skill.isPrivate) {
-        throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+        throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
       }
       if (authCtx && skill.isPrivate) {
         const memberships = await readUserOrgMemberships(c);
@@ -600,7 +684,7 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
           isPlatformAdmin: authCtx.permissions.includes("ornn:admin:skill"),
         };
         if (!canReadSkill(skill, actor)) {
-          throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+          throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
         }
       }
 
@@ -627,7 +711,7 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
 
       // Anonymous users can only see public skills.
       if (!authCtx && skill.isPrivate) {
-        throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+        throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
       }
 
       // Authenticated users: apply the full ownership/org-visibility rules.
@@ -639,18 +723,27 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
           isPlatformAdmin: authCtx.permissions.includes("ornn:admin:skill"),
         };
         if (!canReadSkill(skill, actor)) {
-          throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+          throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
         }
       }
 
-      // Signal deprecation via response headers so non-JSON-aware clients
-      // (CLIs, agents) still get the warning. Notes are URL-encoded to keep
-      // header values ASCII-safe per RFC 7230.
+      // Signal deprecation via standard RFC 8594 headers (#586) — no
+      // custom `X-Skill-Deprecated` style. CLIs, agents, and proxies
+      // can read these without an Ornn-specific parser.
+      //
+      //   Deprecation: true
+      //   Link: <…/DEPRECATIONS.md#{guid}>; rel="deprecation"
+      //
+      // The deprecation note lives in the response body
+      // (`deprecationNote` on the SkillDetailResponse), where free-form
+      // text belongs. Sunset header is reserved for when we wire up the
+      // sunset-date field on the doc.
       if (skill.isDeprecated) {
-        c.header("X-Skill-Deprecated", "true");
-        if (skill.deprecationNote) {
-          c.header("X-Skill-Deprecation-Note", encodeURIComponent(skill.deprecationNote));
-        }
+        c.header("Deprecation", "true");
+        c.header(
+          "Link",
+          `<https://github.com/ChronoAIProject/Ornn/blob/main/docs/DEPRECATIONS.md#${skill.guid}>; rel="deprecation"`,
+        );
       }
 
       // Web-side pull. The detail endpoint is what the SkillDetailPage
@@ -679,25 +772,29 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
   );
 
   /**
-   * PATCH /skills/:idOrName/versions/:version
-   * Toggle the deprecation flag on a specific version.
+   * PATCH /skills/:id/versions/:version
+   *
+   * Toggle the deprecation flag on a specific version. Per
+   * CONVENTIONS.md §2.2 (#586): write operations accept only the
+   * stable GUID, not the name. Callers with a name should resolve
+   * via the read endpoint first.
+   *
    * Requires: ornn:skill:update + owner or admin on the skill.
    */
   app.patch(
-    "/skills/:idOrName/versions/:version",
+    "/skills/:id/versions/:version",
     auth,
     requirePermission("ornn:skill:update"),
-    validateBody(deprecationPatchSchema, "INVALID_DEPRECATION_PATCH"),
+    validateBody(deprecationPatchSchema, "invalid_deprecation_patch"),
     async (c) => {
-      const idOrName = c.req.param("idOrName");
+      const id = c.req.param("id");
       const version = c.req.param("version");
       const authCtx = getAuth(c);
 
-      const existing =
-        (await skillRepo.findByGuid(idOrName)) ??
-        (await skillRepo.findByName(idOrName));
+      // GUID-only — name fallback removed in #586.
+      const existing = await skillRepo.findByGuid(id);
       if (!existing) {
-        throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+        throw AppError.notFound("skill_not_found", `Skill '${id}' not found`);
       }
       const memberships = await readUserOrgMemberships(c);
       const actor = {
@@ -707,14 +804,14 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
       };
       if (!canManageSkill(existing, actor)) {
         throw AppError.forbidden(
-          "FORBIDDEN",
+          "forbidden",
           "You do not have permission to manage this skill",
         );
       }
 
       const body = getValidatedBody<z.infer<typeof deprecationPatchSchema>>(c);
       const result = await skillService.setVersionDeprecation(
-        idOrName,
+        id,
         version,
         body.isDeprecated,
         body.deprecationNote ?? null,
@@ -736,6 +833,126 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
     },
   );
 
+  // -------- Dist-tags (#463) --------
+  //
+  // Three endpoints mirror npm's `dist-tag` surface: read all, set
+  // one, delete one. `latest` is auto-managed by the publish path —
+  // PUT / DELETE against it return `dist_tag_immutable` from the
+  // service layer.
+
+  /**
+   * GET /skills/:idOrName/dist-tags — Read the dist-tags map for a
+   * skill (#463). Anonymous can read public skills; private skills
+   * require the same auth posture as the read endpoint.
+   */
+  app.get(
+    "/skills/:idOrName/dist-tags",
+    optionalAuth,
+    async (c) => {
+      const idOrName = c.req.param("idOrName");
+      const authCtx = c.get("auth");
+      const skill = await skillRepo.findByGuid(idOrName)
+        ?? await skillRepo.findByName(idOrName);
+      if (!skill) {
+        throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
+      }
+      if (!authCtx && skill.isPrivate) {
+        throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
+      }
+      if (authCtx && skill.isPrivate) {
+        const memberships = await readUserOrgMemberships(c);
+        const actor = {
+          userId: authCtx.userId,
+          memberships,
+          isPlatformAdmin: authCtx.permissions.includes("ornn:admin:skill"),
+        };
+        if (!canReadSkill(skill, actor)) {
+          throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
+        }
+      }
+      const tags = await skillService.getDistTags(skill.guid);
+      return c.json({ data: { tags }, error: null });
+    },
+  );
+
+  /**
+   * PUT /skills/:id/dist-tags/:tag — Set or update a dist-tag (#463).
+   *
+   * Owner / platform-admin only (same gate as the rest of `/skills/:id/*`
+   * write paths). `latest` is rejected with `dist_tag_immutable`.
+   * Per CONVENTIONS.md §2.2, the `:id` slot is the stable GUID — no
+   * polymorphic name resolution on writes.
+   */
+  app.put(
+    "/skills/:id/dist-tags/:tag",
+    auth,
+    requirePermission("ornn:skill:update"),
+    validateBody(distTagSetSchema, "invalid_dist_tag_body"),
+    async (c) => {
+      const id = c.req.param("id");
+      const tag = c.req.param("tag");
+      const authCtx = getAuth(c);
+
+      const existing = await skillRepo.findByGuid(id);
+      if (!existing) {
+        throw AppError.notFound("skill_not_found", `Skill '${id}' not found`);
+      }
+      const memberships = await readUserOrgMemberships(c);
+      const actor = {
+        userId: authCtx.userId,
+        memberships,
+        isPlatformAdmin: authCtx.permissions.includes("ornn:admin:skill"),
+      };
+      if (!canManageSkill(existing, actor)) {
+        throw AppError.forbidden(
+          "forbidden",
+          "You do not have permission to manage this skill",
+        );
+      }
+
+      const body = getValidatedBody<z.infer<typeof distTagSetSchema>>(c);
+      const tags = await skillService.setDistTag(id, tag, body.version);
+      return c.json({ data: { tags }, error: null });
+    },
+  );
+
+  /**
+   * DELETE /skills/:id/dist-tags/:tag — Remove a dist-tag (#463).
+   *
+   * Owner / platform-admin only. `latest` is rejected with
+   * `dist_tag_immutable` to preserve the auto-managed invariant.
+   */
+  app.delete(
+    "/skills/:id/dist-tags/:tag",
+    auth,
+    requirePermission("ornn:skill:update"),
+    async (c) => {
+      const id = c.req.param("id");
+      const tag = c.req.param("tag");
+      const authCtx = getAuth(c);
+
+      const existing = await skillRepo.findByGuid(id);
+      if (!existing) {
+        throw AppError.notFound("skill_not_found", `Skill '${id}' not found`);
+      }
+      const memberships = await readUserOrgMemberships(c);
+      const actor = {
+        userId: authCtx.userId,
+        memberships,
+        isPlatformAdmin: authCtx.permissions.includes("ornn:admin:skill"),
+      };
+      if (!canManageSkill(existing, actor)) {
+        throw AppError.forbidden(
+          "forbidden",
+          "You do not have permission to manage this skill",
+        );
+      }
+
+      const tags = await skillService.deleteDistTag(id, tag);
+      return c.json({ data: { tags }, error: null });
+    },
+  );
+
   /**
    * PUT /skills/:id — Update a skill.
    * Requires: ornn:skill:update + owner or admin
@@ -753,7 +970,7 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
 
       const existing = await skillRepo.findByGuid(guid);
       if (!existing) {
-        throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${guid}' not found`);
+        throw AppError.notFound("skill_not_found", `Skill '${guid}' not found`);
       }
       const memberships = await readUserOrgMemberships(c);
       const actor = {
@@ -763,7 +980,7 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
       };
       if (!canManageSkill(existing, actor)) {
         throw AppError.forbidden(
-          "FORBIDDEN",
+          "forbidden",
           "You do not have permission to update this skill",
         );
       }
@@ -793,14 +1010,42 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
           isPrivate = String(formData["isPrivate"]) === "true";
         }
       } else if (contentType.includes("application/json")) {
-        const body = await c.req.json();
+        // Inline Zod parse — the route is hybrid content-type, so the
+        // `validateBody` middleware doesn't fit. Same #438 intent:
+        // malformed JSON returns 400 with the documented RFC 7807
+        // shape instead of bubbling a raw `SyntaxError`.
+        let body: z.infer<typeof skillUpdateJsonSchema>;
+        try {
+          const text = await c.req.text();
+          const raw = text.trim().length === 0 ? {} : JSON.parse(text);
+          const result = skillUpdateJsonSchema.safeParse(raw);
+          if (!result.success) {
+            throw AppError.badRequest(
+              "invalid_body",
+              result.error.issues
+                .map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`)
+                .join("; "),
+            );
+          }
+          body = result.data;
+        } catch (err) {
+          if (err instanceof AppError) throw err;
+          throw AppError.badRequest("invalid_body", "Request body must be valid JSON");
+        }
         if (body.isPrivate !== undefined) {
-          isPrivate = Boolean(body.isPrivate);
+          isPrivate = body.isPrivate;
         }
       }
 
       if (zipBuffer === undefined && isPrivate === undefined) {
-        throw AppError.badRequest("NO_UPDATE", "No update data provided. Send a ZIP file and/or isPrivate field.");
+        throw AppError.badRequest("no_update", "No update data provided. Send a ZIP file and/or isPrivate field.");
+      }
+
+      // Zip-bomb defense (#633) — same gate as the create path. Only
+      // when a ZIP is actually being replaced; a privacy-only PUT
+      // doesn't hit this.
+      if (zipBuffer !== undefined) {
+        await enforceZipLimits(zipBuffer);
       }
 
       logger.info({ guid, userId: authCtx.userId }, "Skill update via API");
@@ -847,14 +1092,14 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
     "/skills/:id/permissions",
     auth,
     requirePermission("ornn:skill:update"),
-    validateBody(permissionsPatchSchema, "INVALID_PERMISSIONS"),
+    validateBody(permissionsPatchSchema, "invalid_permissions"),
     async (c) => {
       const guid = c.req.param("id");
       const authCtx = getAuth(c);
 
       const existing = await skillRepo.findByGuid(guid);
       if (!existing) {
-        throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${guid}' not found`);
+        throw AppError.notFound("skill_not_found", `Skill '${guid}' not found`);
       }
       const memberships = await readUserOrgMemberships(c);
       const actor = {
@@ -864,7 +1109,7 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
       };
       if (!canManageSkill(existing, actor)) {
         throw AppError.forbidden(
-          "FORBIDDEN",
+          "forbidden",
           "You do not have permission to change this skill's visibility",
         );
       }
@@ -922,14 +1167,14 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
 
       const existing = await skillRepo.findByGuid(guid);
       if (!existing) {
-        throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${guid}' not found`);
+        throw AppError.notFound("skill_not_found", `Skill '${guid}' not found`);
       }
       const memberships = await readUserOrgMemberships(c);
       const isPlatformAdmin = authCtx.permissions.includes("ornn:admin:skill");
       const actor = { userId: authCtx.userId, memberships, isPlatformAdmin };
       if (!canManageSkill(existing, actor)) {
         throw AppError.forbidden(
-          "FORBIDDEN",
+          "forbidden",
           "You do not have permission to change this skill's NyxID service tie",
         );
       }
@@ -1047,7 +1292,6 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
         guid: s.guid,
         name: s.name,
         description: s.description,
-        ownerId: s.ownerId,
         createdBy: s.createdBy,
         createdByEmail: s.createdByEmail,
         createdByDisplayName: s.createdByDisplayName,
@@ -1095,7 +1339,7 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
       const authCtx = getAuth(c);
       const skill = await skillRepo.findByGuid(guid);
       if (!skill) {
-        throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${guid}' not found`);
+        throw AppError.notFound("skill_not_found", `Skill '${guid}' not found`);
       }
       const memberships = await readUserOrgMemberships(c);
       const actor = {
@@ -1105,7 +1349,7 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
       };
       if (!canManageSkill(skill, actor)) {
         throw AppError.forbidden(
-          "FORBIDDEN",
+          "forbidden",
           "You do not have permission to delete this skill",
         );
       }
@@ -1136,18 +1380,18 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
    * Requires: ornn:skill:delete + owner or admin.
    */
   app.delete(
-    "/skills/:idOrName/versions/:version",
+    "/skills/:id/versions/:version",
     auth,
     requirePermission("ornn:skill:delete"),
     async (c) => {
-      const idOrName = c.req.param("idOrName");
+      // GUID-only on write per CONVENTIONS.md §2.2 (#586).
+      const id = c.req.param("id");
       const version = c.req.param("version");
       const authCtx = getAuth(c);
 
-      let skill = await skillRepo.findByGuid(idOrName);
-      if (!skill) skill = await skillRepo.findByName(idOrName);
+      const skill = await skillRepo.findByGuid(id);
       if (!skill) {
-        throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+        throw AppError.notFound("skill_not_found", `Skill '${id}' not found`);
       }
       const memberships = await readUserOrgMemberships(c);
       const actor = {
@@ -1157,7 +1401,7 @@ export function createSkillRoutes(config: SkillRoutesConfig): Hono<{ Variables:
       };
       if (!canManageSkill(skill, actor)) {
         throw AppError.forbidden(
-          "FORBIDDEN",
+          "forbidden",
           "You do not have permission to delete this skill version",
         );
       }
diff --git a/ornn-api/src/domains/skills/crud/service.ts b/ornn-api/src/domains/skills/crud/service.ts
index 8fb7c78d..0cd1bee5 100644
--- a/ornn-api/src/domains/skills/crud/service.ts
+++ b/ornn-api/src/domains/skills/crud/service.ts
@@ -14,6 +14,21 @@ import { AppError } from "../../../shared/types/index";
 import { fetchSkillFromGitHub, parseGithubUrl, type GitHubPullInput } from "./utils/githubPull";
 import { computeVersionDiff, type VersionDiffResult } from "./utils/versionDiff";
 import { isReservedVerb } from "../../../shared/reservedVerbs";
+
+/**
+ * Convert the stored hex `skillHash` into npm-style Subresource Integrity
+ * (#461): `sha256-<base64-of-raw-digest>`. Equivalent to
+ * `package-lock.json`'s `integrity:` field — clients verify a downloaded
+ * package byte-for-byte before installing.
+ */
+function hexToIntegrity(hex: string): string {
+  if (!hex || hex.length === 0) return "";
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(hex.substr(i * 2, 2), 16);
+  }
+  return `sha256-${Buffer.from(bytes).toString("base64")}`;
+}
 import { validateSkillFrontmatter } from "../../../shared/schemas/skillFrontmatter";
 import { resolveZipRoot } from "../../../shared/utils/zip";
 import { parseVersion, isGreater } from "./version";
@@ -22,9 +37,8 @@ import type { AnalyticsEmitter } from "../../../infra/analytics";
 import type { IAgentSealScanner } from "../../../infra/agentseal";
 import { parse as parseYaml } from "yaml";
 import JSZip from "jszip";
-import pino from "pino";
-
-const logger = pino({ level: "info" }).child({ module: "skillCrudService" });
+import { createLogger } from "../../../shared/logger";
+const logger = createLogger("skillCrudService");
 
 const FRONTMATTER_REGEX = /^---\s*\n([\s\S]*?)\n---/;
 
@@ -42,6 +56,50 @@ function formatInterfaceChanges(changes: InterfaceChange[]): string {
   return changes.map((c) => `${c.field} ${c.kind} ${c.detail}`).join("; ");
 }
 
+/**
+ * Dist-tag name rule (#463): npm-style — lowercase ASCII, leading
+ * letter, optional hyphens, max 50 chars. The leading-letter rule
+ * stops tags from looking like version numbers (`1`, `0.5`).
+ */
+const DIST_TAG_NAME_RE = /^[a-z][a-z0-9-]{0,49}$/;
+
+export function isValidTagName(tag: string): boolean {
+  return typeof tag === "string" && DIST_TAG_NAME_RE.test(tag);
+}
+
+/**
+ * Map the `version` query-param value to the concrete version the
+ * caller wants. Recognized forms (#463):
+ *   - undefined / empty → undefined (caller wants latest, handled upstream)
+ *   - `@<tag>` → resolved via `skill.distTags`, or fallback to
+ *     `latestVersion` when `tag === "latest"` and the skill predates
+ *     the dist-tags feature
+ *   - everything else → returned verbatim (literal `<major>.<minor>`)
+ *
+ * Returning undefined here means "caller didn't specify"; returning a
+ * concrete string means "use exactly this version". A missing tag
+ * resolves to `null` and we surface it as an explicit 404 from the
+ * caller so the user sees `Tag 'beta' not found` rather than `Version
+ * '@beta' not found` — the latter would be confusing.
+ */
+export function resolveDistTag(skill: SkillDocument, version: string): string | undefined {
+  if (version.length === 0) return undefined;
+  if (!version.startsWith("@")) return version;
+  const tag = version.slice(1);
+  if (!tag) {
+    throw AppError.badRequest("invalid_dist_tag", "Dist-tag name is empty");
+  }
+  const resolved = skill.distTags?.[tag];
+  if (resolved) return resolved;
+  // Legacy compatibility: `@latest` on a pre-#463 skill (no distTags
+  // field) falls back to the cached `latestVersion` pointer.
+  if (tag === "latest") return skill.latestVersion;
+  throw AppError.notFound(
+    "skill_version_not_found",
+    `Dist-tag '${tag}' is not set for skill '${skill.name}'`,
+  );
+}
+
 export interface SkillServiceDeps {
   skillRepo: SkillRepository;
   skillVersionRepo: SkillVersionRepository;
@@ -71,8 +129,9 @@ export class SkillService {
   private readonly skillVersionRepo: SkillVersionRepository;
   private readonly storageClient: IStorageClient;
   private readonly storageBucketResolver: () => Promise<string>;
-  private readonly analyticsEmitter?: AnalyticsEmitter;
-  private readonly agentsealScanner?: IAgentSealScanner;
+  // exactOptionalPropertyTypes (#657): widen to `T | undefined`.
+  private readonly analyticsEmitter: AnalyticsEmitter | undefined;
+  private readonly agentsealScanner: IAgentSealScanner | undefined;
 
   constructor(deps: SkillServiceDeps) {
     this.skillRepo = deps.skillRepo;
@@ -86,12 +145,14 @@ export class SkillService {
   async createSkill(
     zipBuffer: Uint8Array,
     userId: string,
+    // Optionals accept `| undefined` so route layers passing
+    // Zod-inferred values fit under exactOptionalPropertyTypes (#657).
     options?: {
-      skipValidation?: boolean;
-      userEmail?: string;
-      userDisplayName?: string;
+      skipValidation?: boolean | undefined;
+      userEmail?: string | undefined;
+      userDisplayName?: string | undefined;
       /** Origin metadata stamped on the skill doc when created from an external pull. */
-      source?: import("../../../shared/types/index").SkillSource;
+      source?: import("../../../shared/types/index").SkillSource | undefined;
     },
   ): Promise<{ guid: string }> {
     // 1. Validate ZIP format rules
@@ -99,21 +160,26 @@ export class SkillService {
       const violations = await this.validateZipFormat(zipBuffer);
       if (violations.length > 0) {
         throw AppError.badRequest(
-          "VALIDATION_FAILED",
+          "validation_failed",
           violations.map((v) => `[${v.rule}] ${v.message}`).join("; "),
         );
       }
     }
 
     // 2. Parse SKILL.md from ZIP
-    const { name, description, version, license, compatibility, metadata, releaseNotes } = await this.extractSkillInfo(zipBuffer);
+    // #529 — `skipValidation` extends to the frontmatter Zod check so
+    // third-party packages that don't conform to Ornn's schema (e.g.
+    // imported from outside the platform via "Import from GitHub"
+    // with skip-validation toggled) can still land. YAML syntax
+    // errors still fail loudly — we can't import what we can't parse.
+    const { name, description, version, license, compatibility, metadata, releaseNotes } = await this.extractSkillInfo(zipBuffer, !!options?.skipValidation);
     const parsedVersion = parseVersion(version);
 
     // 3a. Reject reserved-verb names — would collide with `/v1/skills/{verb}`
     //     action paths and make the skill unreachable via the canonical read.
     if (isReservedVerb("skill", name)) {
       throw AppError.badRequest(
-        "RESERVED_NAME",
+        "reserved_name",
         `Skill name '${name}' is reserved — pick a different name`,
       );
     }
@@ -121,7 +187,7 @@ export class SkillService {
     // 3b. Check name uniqueness
     const existing = await this.skillRepo.findByName(name);
     if (existing) {
-      throw AppError.conflict("SKILL_NAME_EXISTS", `Skill '${name}' already exists`);
+      throw AppError.conflict("skill_name_exists", `Skill '${name}' already exists`);
     }
 
     // 4. Generate GUID and hash
@@ -143,10 +209,6 @@ export class SkillService {
       metadata,
       skillHash,
       storageKey,
-      // `ownerId` is retained as a no-op field for back-compat. New skills
-      // always record the author here; visibility is expressed via
-      // sharedWithUsers/sharedWithOrgs on the skill doc.
-      ownerId: userId,
       createdBy: userId,
       createdByEmail: options?.userEmail,
       createdByDisplayName: options?.userDisplayName,
@@ -172,6 +234,11 @@ export class SkillService {
       releaseNotes,
     });
 
+    // Seed `distTags.latest` so the auto-managed tag exists from the
+    // first publish (#463). Custom tags (`stable`, `beta`, ...) are
+    // owner-managed via the `/dist-tags/:tag` routes.
+    await this.skillRepo.setDistTag(guid, "latest", version);
+
     // 8. Fire-and-forget product-analytics + AgentSeal trust scan. Both are
     //    deliberately not awaited so a slow PostHog backend or AgentSeal
     //    subprocess can't block the response. Failures inside either path
@@ -193,21 +260,110 @@ export class SkillService {
    * cached pointer). With `version`, reads from the `skill_versions` collection
    * and overlays that version's storageKey / metadata / hash on the identity
    * fields from the skill doc.
+   *
+   * Dist-tag resolution (#463): when `version` starts with `@`, the
+   * remainder is looked up in `skill.distTags`. Failed lookup is a 404
+   * (`skill_version_not_found`) — same error as a missing literal
+   * version, since from the caller's perspective both mean "no such
+   * version".
    */
   async getSkill(idOrName: string, version?: string): Promise<SkillDetailResponse> {
     const skill = await this.findSkillByIdOrName(idOrName);
-    if (version !== undefined) {
+    const resolvedVersion = version === undefined ? undefined : resolveDistTag(skill, version);
+    if (resolvedVersion !== undefined) {
       // Validate format early so clients get a clear 400, not a 404.
-      parseVersion(version);
-      const versionDoc = await this.skillVersionRepo.findBySkillAndVersion(skill.guid, version);
+      parseVersion(resolvedVersion);
+      const versionDoc = await this.skillVersionRepo.findBySkillAndVersion(skill.guid, resolvedVersion);
       if (!versionDoc) {
-        throw AppError.notFound("SKILL_VERSION_NOT_FOUND", `Version '${version}' not found for skill '${skill.name}'`);
+        throw AppError.notFound(
+          "skill_version_not_found",
+          `Version '${resolvedVersion}' not found for skill '${skill.name}'`,
+        );
       }
       return this.buildDetailResponse(skill, versionDoc);
     }
     return this.buildDetailResponse(skill);
   }
 
+  /**
+   * Read the dist-tags map for a skill (#463). Read-only — no auth
+   * check here; the route layer applies the same visibility rules as
+   * the read endpoint (anonymous can see public, etc.).
+   *
+   * Always returns `latest` (synthesized from `latestVersion` for
+   * legacy skills predating #463 that never had the field set).
+   */
+  async getDistTags(idOrName: string): Promise<Record<string, string>> {
+    const skill = await this.findSkillByIdOrName(idOrName);
+    const tags: Record<string, string> = { ...(skill.distTags ?? {}) };
+    if (!tags.latest) {
+      tags.latest = skill.latestVersion;
+    }
+    return tags;
+  }
+
+  /**
+   * Set a dist-tag → version mapping (#463). Owner / platform-admin
+   * only — the route layer enforces that. `latest` is auto-managed by
+   * the publish path and cannot be set via this endpoint.
+   *
+   * The version must already exist on the `skill_versions` collection;
+   * otherwise we'd be creating a dangling tag.
+   */
+  async setDistTag(
+    idOrName: string,
+    tag: string,
+    version: string,
+  ): Promise<Record<string, string>> {
+    if (!isValidTagName(tag)) {
+      throw AppError.badRequest(
+        "invalid_dist_tag",
+        `Dist-tag '${tag}' is invalid — must match /^[a-z][a-z0-9-]{0,49}$/`,
+      );
+    }
+    if (tag === "latest") {
+      throw AppError.badRequest(
+        "dist_tag_immutable",
+        "`latest` is auto-managed on publish and cannot be set directly",
+      );
+    }
+    // Format-validate the version before hitting Mongo.
+    parseVersion(version);
+    const skill = await this.findSkillByIdOrName(idOrName);
+    const versionDoc = await this.skillVersionRepo.findBySkillAndVersion(skill.guid, version);
+    if (!versionDoc) {
+      throw AppError.notFound(
+        "skill_version_not_found",
+        `Version '${version}' not found for skill '${skill.name}'`,
+      );
+    }
+    await this.skillRepo.setDistTag(skill.guid, tag, version);
+    return this.getDistTags(skill.guid);
+  }
+
+  /**
+   * Remove a dist-tag (#463). `latest` is refused with
+   * `dist_tag_immutable` to preserve the invariant that every skill
+   * has a `latest` pointer.
+   */
+  async deleteDistTag(idOrName: string, tag: string): Promise<Record<string, string>> {
+    if (tag === "latest") {
+      throw AppError.badRequest(
+        "dist_tag_immutable",
+        "`latest` is auto-managed and cannot be deleted",
+      );
+    }
+    if (!isValidTagName(tag)) {
+      throw AppError.badRequest(
+        "invalid_dist_tag",
+        `Dist-tag '${tag}' is invalid — must match /^[a-z][a-z0-9-]{0,49}$/`,
+      );
+    }
+    const skill = await this.findSkillByIdOrName(idOrName);
+    await this.skillRepo.deleteDistTag(skill.guid, tag);
+    return this.getDistTags(skill.guid);
+  }
+
   /**
    * List every published version for a skill, newest first. Includes the
    * deprecation flag + note so consumers can render a warning without another
@@ -216,9 +372,17 @@ export class SkillService {
   async listSkillVersions(idOrName: string): Promise<Array<{
     version: string;
     skillHash: string;
+    /**
+     * npm-style Subresource Integrity (#461). `sha256-<base64(skillHash)>`.
+     * Clients verify a downloaded package matches this value byte-for-byte
+     * before installing. Equivalent in spirit to npm's `integrity:` field
+     * on `package-lock.json` and PyPI's `sha256_digest` per file.
+     */
+    integrity: string;
     createdBy: string;
-    createdByEmail?: string;
-    createdByDisplayName?: string;
+    // exactOptionalPropertyTypes (#657)
+    createdByEmail?: string | undefined;
+    createdByDisplayName?: string | undefined;
     createdOn: string;
     isDeprecated: boolean;
     deprecationNote: string | null;
@@ -229,6 +393,7 @@ export class SkillService {
     return versions.map((v) => ({
       version: v.version,
       skillHash: v.skillHash,
+      integrity: hexToIntegrity(v.skillHash),
       createdBy: v.createdBy,
       createdByEmail: v.createdByEmail,
       createdByDisplayName: v.createdByDisplayName,
@@ -282,7 +447,7 @@ export class SkillService {
       skill = await this.skillRepo.findByName(idOrName);
     }
     if (!skill) {
-      throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+      throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
     }
     return skill;
   }
@@ -292,9 +457,8 @@ export class SkillService {
    * route layer has already enforced the write gate (author/admin); the
    * service just validates the inputs and persists them.
    *
-   * Ownership (`createdBy`, `ownerId`) is left untouched — permissions
-   * don't change who wrote or "owns" the skill, they just widen who can
-   * read it.
+   * Ownership (`createdBy`) is left untouched — permissions don't
+   * change who wrote the skill, they just widen who can read it.
    */
   async setSkillPermissions(
     guid: string,
@@ -307,7 +471,7 @@ export class SkillService {
   ): Promise<SkillDetailResponse> {
     const existing = await this.skillRepo.findByGuid(guid);
     if (!existing) {
-      throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${guid}' not found`);
+      throw AppError.notFound("skill_not_found", `Skill '${guid}' not found`);
     }
 
     // System-skill invariant: a skill tied to an admin NyxID service is
@@ -343,19 +507,21 @@ export class SkillService {
   async updateSkill(
     guid: string,
     userId: string,
+    // exactOptionalPropertyTypes (#657): allow `T | undefined` on all
+    // optionals so route layers can pass Zod-inferred values directly.
     options: {
-      zipBuffer?: Uint8Array;
-      isPrivate?: boolean;
-      skipValidation?: boolean;
-      userEmail?: string;
-      userDisplayName?: string;
+      zipBuffer?: Uint8Array | undefined;
+      isPrivate?: boolean | undefined;
+      skipValidation?: boolean | undefined;
+      userEmail?: string | undefined;
+      userDisplayName?: string | undefined;
       /** Refresh-from-source path stamps this so lastSyncedAt/Commit move forward. */
-      source?: import("../../../shared/types/index").SkillSource;
+      source?: import("../../../shared/types/index").SkillSource | undefined;
     },
   ): Promise<SkillDetailResponse> {
     const existing = await this.skillRepo.findByGuid(guid);
     if (!existing) {
-      throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${guid}' not found`);
+      throw AppError.notFound("skill_not_found", `Skill '${guid}' not found`);
     }
 
     // System-skill invariant — same as setSkillPermissions. Block
@@ -377,13 +543,16 @@ export class SkillService {
         const violations = await this.validateZipFormat(options.zipBuffer);
         if (violations.length > 0) {
           throw AppError.badRequest(
-            "VALIDATION_FAILED",
+            "validation_failed",
             violations.map((v) => `[${v.rule}] ${v.message}`).join("; "),
           );
         }
       }
 
-      const { name, description, version, license, compatibility, metadata, releaseNotes } = await this.extractSkillInfo(options.zipBuffer);
+      // #529 — same skipValidation extension as createSkill above so
+      // `PUT /skills/:id` (replace-package on an existing skill, used by
+      // GitHub refresh + admin re-upload) honours the flag too.
+      const { name, description, version, license, compatibility, metadata, releaseNotes } = await this.extractSkillInfo(options.zipBuffer, !!options.skipValidation);
       const parsedNewVersion = parseVersion(version);
 
       // Enforce strictly-incrementing version on every package update.
@@ -452,6 +621,13 @@ export class SkillService {
         storageKey,
         latestVersion: version,
       });
+
+      // Keep `distTags.latest` in lockstep with `latestVersion` on
+      // every publish (#463). The two writes can briefly race the
+      // doc-level `update` below, but readers tolerate a transient
+      // mismatch (resolution falls back to `latestVersion` when the
+      // tag isn't set) so we don't bother with a transaction.
+      await this.skillRepo.setDistTag(guid, "latest", version);
     }
 
     if (options.isPrivate !== undefined) {
@@ -479,7 +655,12 @@ export class SkillService {
   async createSkillFromGitHub(
     input: GitHubPullInput,
     userId: string,
-    options?: { userEmail?: string; userDisplayName?: string; skipValidation?: boolean },
+    // exactOptionalPropertyTypes (#657)
+    options?: {
+      userEmail?: string | undefined;
+      userDisplayName?: string | undefined;
+      skipValidation?: boolean | undefined;
+    },
   ): Promise<{ guid: string; source: SkillSource }> {
     const pulled = await fetchSkillFromGitHub(input);
     const source: SkillSource = {
@@ -507,11 +688,16 @@ export class SkillService {
   async refreshSkillFromSource(
     guid: string,
     userId: string,
-    options?: { userEmail?: string; userDisplayName?: string; skipValidation?: boolean },
+    // exactOptionalPropertyTypes (#657)
+    options?: {
+      userEmail?: string | undefined;
+      userDisplayName?: string | undefined;
+      skipValidation?: boolean | undefined;
+    },
   ): Promise<SkillDetailResponse> {
     const existing = await this.skillRepo.findByGuid(guid);
     if (!existing) {
-      throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${guid}' not found`);
+      throw AppError.notFound("skill_not_found", `Skill '${guid}' not found`);
     }
     if (!existing.source || existing.source.type !== "github") {
       throw AppError.badRequest(
@@ -559,7 +745,7 @@ export class SkillService {
   ): Promise<SkillDetailResponse> {
     const existing = await this.skillRepo.findByGuid(guid);
     if (!existing) {
-      throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${guid}' not found`);
+      throw AppError.notFound("skill_not_found", `Skill '${guid}' not found`);
     }
 
     if (githubUrl === null) {
@@ -567,12 +753,12 @@ export class SkillService {
       return this.getSkill(guid);
     }
 
-    let parsed: { repo: string; ref?: string; path?: string };
+    let parsed: { repo: string; ref?: string | undefined; path?: string | undefined };
     try {
       parsed = parseGithubUrl(githubUrl);
     } catch (err) {
       throw AppError.badRequest(
-        "INVALID_GITHUB_URL",
+        "invalid_github_url",
         err instanceof Error ? err.message : String(err),
       );
     }
@@ -606,7 +792,7 @@ export class SkillService {
   }> {
     const existing = await this.skillRepo.findByGuid(guid);
     if (!existing) {
-      throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${guid}' not found`);
+      throw AppError.notFound("skill_not_found", `Skill '${guid}' not found`);
     }
     if (!existing.source || existing.source.type !== "github") {
       throw AppError.badRequest(
@@ -645,12 +831,21 @@ export class SkillService {
     // out of the pulled ZIP so the UI can show "you'll create v1.2".
     let pendingVersion = existing.latestVersion;
     try {
-      const info = await this.extractSkillInfo(pulled.zipBuffer);
+      // Preview is dry-run — we just want the predicted version label.
+      // Pass skipValidation=true so a third-party-shaped SKILL.md
+      // doesn't kill the preview; the real refresh path enforces the
+      // caller's flag separately.
+      const info = await this.extractSkillInfo(pulled.zipBuffer, true);
       pendingVersion = info.version;
-    } catch {
+    } catch (err) {
       // If the package can't be parsed (e.g. malformed frontmatter),
       // fall back to the existing latest. The actual sync will surface
-      // the validation error properly.
+      // the validation error properly. Log so we can spot a pulled
+      // source repo that's been broken for a while (#579).
+      logger.debug(
+        { err, skillGuid: existing.guid },
+        "preview-refresh: pulled ZIP parse failed, falling back to existing version",
+      );
     }
 
     return {
@@ -685,7 +880,7 @@ export class SkillService {
   }> {
     if (fromVersion === toVersion) {
       throw AppError.badRequest(
-        "SAME_VERSION",
+        "same_version",
         `'from' and 'to' refer to the same version '${fromVersion}'`,
       );
     }
@@ -701,13 +896,13 @@ export class SkillService {
     ]);
     if (!fromDoc) {
       throw AppError.notFound(
-        "SKILL_VERSION_NOT_FOUND",
+        "skill_version_not_found",
         `Version '${fromVersion}' not found for skill '${skill.name}'`,
       );
     }
     if (!toDoc) {
       throw AppError.notFound(
-        "SKILL_VERSION_NOT_FOUND",
+        "skill_version_not_found",
         `Version '${toVersion}' not found for skill '${skill.name}'`,
       );
     }
@@ -753,7 +948,7 @@ export class SkillService {
     const res = await fetch(presigned.presignedUrl);
     if (!res.ok) {
       throw AppError.internalError(
-        "PACKAGE_DOWNLOAD_FAILED",
+        "package_download_failed",
         `Failed to download package for key '${storageKey}' (HTTP ${res.status})`,
       );
     }
@@ -776,12 +971,12 @@ export class SkillService {
     let skill = await this.skillRepo.findByGuid(idOrName);
     if (!skill) skill = await this.skillRepo.findByName(idOrName);
     if (!skill) {
-      throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+      throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
     }
     const versionDoc = await this.skillVersionRepo.findBySkillAndVersion(skill.guid, version);
     if (!versionDoc) {
       throw AppError.notFound(
-        "SKILL_VERSION_NOT_FOUND",
+        "skill_version_not_found",
         `Version '${version}' not found for skill '${skill.name}'`,
       );
     }
@@ -848,7 +1043,7 @@ export class SkillService {
   ): Promise<SkillDetailResponse> {
     const existing = await this.skillRepo.findByGuid(guid);
     if (!existing) {
-      throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${guid}' not found`);
+      throw AppError.notFound("skill_not_found", `Skill '${guid}' not found`);
     }
 
     // Untie path — wipe all four cached fields, leave `isPrivate` alone.
@@ -892,7 +1087,10 @@ export class SkillService {
       nyxidServiceLabel: service.label,
       isSystemSkill: isAdminService,
       // Admin tie forces public; personal tie leaves privacy alone.
-      isPrivate: isAdminService ? false : undefined,
+      // exactOptionalPropertyTypes (#657): conditional spread so we
+      // never pass `{ isPrivate: undefined }` to a contract that wants
+      // `isPrivate?: boolean`.
+      ...(isAdminService ? { isPrivate: false } : {}),
       updatedBy: actor.userId,
     });
     return this.buildDetailResponse(updated);
@@ -901,7 +1099,7 @@ export class SkillService {
   async deleteSkill(guid: string): Promise<void> {
     const existing = await this.skillRepo.findByGuid(guid);
     if (!existing) {
-      throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${guid}' not found`);
+      throw AppError.notFound("skill_not_found", `Skill '${guid}' not found`);
     }
 
     // Collect every storage key to clean up: the current pointer on the skill
@@ -930,11 +1128,26 @@ export class SkillService {
 
   /**
    * Return the full skill package as a JSON object with all file contents.
-   * Used by playground to inject skill context.
+   * Used by playground to inject skill context, and by the SkillInstallCard
+   * prompt's pull commands.
+   *
+   * #639 — accepts an optional `version` that may be a literal `<major>.
+   * <minor>` or a dist-tag (#463). When provided, the response uses that
+   * version's package (`storageKey` + `metadata` from `skill_versions`)
+   * instead of the skill doc's "latest" storage key. Identity fields
+   * (`name`) still come from the skill doc; `description` falls through
+   * to the skill doc too because version docs don't carry one.
+   *
+   * When `version` is omitted the response is the latest package — same
+   * as before.
    */
-  async getSkillJson(idOrName: string): Promise<{
+  async getSkillJson(
+    idOrName: string,
+    version?: string,
+  ): Promise<{
     name: string;
     description: string;
+    version: string;
     metadata: Record<string, unknown>;
     files: Record<string, string>;
   }> {
@@ -944,14 +1157,45 @@ export class SkillService {
       skill = await this.skillRepo.findByName(idOrName);
     }
     if (!skill) {
-      throw AppError.notFound("SKILL_NOT_FOUND", `Skill '${idOrName}' not found`);
+      throw AppError.notFound("skill_not_found", `Skill '${idOrName}' not found`);
+    }
+
+    // 1a. Resolve the requested version (literal or dist-tag, #463).
+    //     When unset OR empty-string, fall through to the skill doc's
+    //     latest storage. `resolveDistTag` returns `undefined` for
+    //     empty input, which we treat as "no pin requested".
+    let resolvedVersion = skill.latestVersion;
+    let storageKey = skill.storageKey;
+    let metadata: SkillMetadata = skill.metadata;
+    if (version !== undefined && version.length > 0) {
+      const literal = resolveDistTag(skill, version);
+      if (!literal) {
+        // Defensive — resolveDistTag's contract returns string for any
+        // non-empty input, but the type system widens to `| undefined`.
+        // Treat as malformed rather than crash.
+        throw AppError.badRequest(
+          "invalid_version",
+          `Could not resolve version '${version}'`,
+        );
+      }
+      parseVersion(literal); // 400 if malformed, before Mongo lookup
+      const versionDoc = await this.skillVersionRepo.findBySkillAndVersion(skill.guid, literal);
+      if (!versionDoc) {
+        throw AppError.notFound(
+          "skill_version_not_found",
+          `Version '${literal}' not found for skill '${skill.name}'`,
+        );
+      }
+      resolvedVersion = versionDoc.version;
+      storageKey = versionDoc.storageKey;
+      metadata = versionDoc.metadata;
     }
 
     // 2. Download ZIP from storage
-    const presigned = await this.storageClient.getPresignedUrl((await this.storageBucketResolver()), skill.storageKey);
+    const presigned = await this.storageClient.getPresignedUrl((await this.storageBucketResolver()), storageKey);
     const response = await fetch(presigned.presignedUrl);
     if (!response.ok) {
-      throw AppError.internalError("PACKAGE_DOWNLOAD_FAILED", "Failed to download skill package from storage");
+      throw AppError.internalError("package_download_failed", "Failed to download skill package from storage");
     }
     const zipBuffer = new Uint8Array(await response.arrayBuffer());
 
@@ -965,7 +1209,10 @@ export class SkillService {
     // Walk all entries and extract text content
     for (const path of allPaths) {
       const entry = zip.files[path];
-      if (entry.dir) continue;
+      // allPaths is sourced from `Object.keys(zip.files)`, but
+      // noUncheckedIndexedAccess (#450) widens the lookup to `T |
+      // undefined`. Defensive skip rather than crash.
+      if (!entry || entry.dir) continue;
 
       // Get the relative path (strip root folder prefix if present)
       let relativePath = path;
@@ -988,12 +1235,16 @@ export class SkillService {
       }
     }
 
-    logger.info({ skillName: skill.name, fileCount: Object.keys(files).length }, "Skill jsonized");
+    logger.info(
+      { skillName: skill.name, version: resolvedVersion, fileCount: Object.keys(files).length },
+      "Skill jsonized",
+    );
 
     return {
       name: skill.name,
       description: skill.description,
-      metadata: skill.metadata as unknown as Record<string, unknown>,
+      version: resolvedVersion,
+      metadata: metadata as unknown as Record<string, unknown>,
       files,
     };
   }
@@ -1022,7 +1273,7 @@ export class SkillService {
     const versionDoc = await this.skillVersionRepo.findBySkillAndVersion(skill.guid, version);
     if (!versionDoc) {
       throw AppError.notFound(
-        "SKILL_VERSION_NOT_FOUND",
+        "skill_version_not_found",
         `Version '${version}' not found for skill '${skill.name}'`,
       );
     }
@@ -1089,7 +1340,18 @@ export class SkillService {
   // Private helpers
   // ==========================================================================
 
-  private async extractSkillInfo(zipBuffer: Uint8Array): Promise<{
+  private async extractSkillInfo(
+    zipBuffer: Uint8Array,
+    // #529 — when the caller passes `skipValidation: true` (Import from
+    // GitHub → "Skip Ornn package format validation"), the strict Zod
+    // frontmatter check is downgraded to a best-effort extract. The
+    // directory-structure validator was already skipped one layer up
+    // in `createSkill`; this brings the frontmatter validator under
+    // the same flag so a third-party skill (e.g. Anthropic's official
+    // skills repo) that doesn't conform to Ornn's frontmatter schema
+    // still imports.
+    skipValidation: boolean = false,
+  ): Promise<{
     name: string;
     description: string;
     version: string;
@@ -1105,34 +1367,49 @@ export class SkillService {
 
     const skillMdEntry = getFile("SKILL.md");
     if (!skillMdEntry) {
-      throw AppError.badRequest("MISSING_SKILL_MD", "SKILL.md not found in package");
+      throw AppError.badRequest("missing_skill_md", "SKILL.md not found in package");
     }
 
     const content = await skillMdEntry.async("string");
     const fmMatch = content.match(FRONTMATTER_REGEX);
     if (!fmMatch) {
-      throw AppError.badRequest("MISSING_FRONTMATTER", "SKILL.md must have a frontmatter section");
+      throw AppError.badRequest("missing_frontmatter", "SKILL.md must have a frontmatter section");
     }
 
     let rawFrontmatter: Record<string, unknown>;
     try {
-      const parsed = parseYaml(fmMatch[1]);
+      // FRONTMATTER_REGEX always has a capture group 1 (the YAML body)
+      // when it matches. `!` is safe under noUncheckedIndexedAccess
+      // (#450).
+      const parsed = parseYaml(fmMatch[1]!);
       if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
         throw new Error("Frontmatter must be a YAML object");
       }
       rawFrontmatter = parsed as Record<string, unknown>;
     } catch (err) {
+      // YAML SYNTAX errors (vs. schema mismatches) still fail loudly
+      // even under skipValidation — we can't import a skill we can't
+      // parse at all, no matter how lenient we want to be.
       throw AppError.badRequest(
         "INVALID_FRONTMATTER",
         `Invalid frontmatter YAML: ${err instanceof Error ? err.message : String(err)}`,
       );
     }
 
-    // Validate with Zod schema (no backward compat adapter)
+    // Strict Zod validation (#529 — bypassable when skipValidation).
     const validation = validateSkillFrontmatter(rawFrontmatter);
     if (!validation.success) {
-      const errorMsg = validation.errors.map((e) => `${e.field}: ${e.message}`).join("; ");
-      throw AppError.badRequest("FRONTMATTER_VALIDATION_FAILED", errorMsg);
+      if (!skipValidation) {
+        const errorMsg = validation.errors.map((e) => `${e.field}: ${e.message}`).join("; ");
+        throw AppError.badRequest("frontmatter_validation_failed", errorMsg);
+      }
+      // skipValidation path — fall through to best-effort field
+      // extraction below.
+      logger.info(
+        { errors: validation.errors.length },
+        "Frontmatter validation failed but skipValidation=true; falling back to best-effort extract",
+      );
+      return this.extractSkillInfoLenient(rawFrontmatter);
     }
 
     const fm = validation.data;
@@ -1197,6 +1474,93 @@ export class SkillService {
     };
   }
 
+  /**
+   * Best-effort extract from a raw frontmatter object when the strict
+   * Zod schema rejected it (#529). Used by `extractSkillInfo` under
+   * `skipValidation: true` so a third-party-shaped SKILL.md still
+   * imports.
+   *
+   * Strategy:
+   *   - Pull the canonical Ornn fields by name when present and the
+   *     right type; otherwise synthesise a safe default.
+   *   - `name` MUST be present (we have no fallback that would be
+   *     unique). Reject with the same `frontmatter_validation_failed`
+   *     code that the strict path uses.
+   *   - `version` defaults to "0.1" if missing — the import has to
+   *     start somewhere. Format-validation downstream
+   *     (`parseVersion`) still kicks in so genuinely malformed
+   *     versions hard-fail.
+   *   - `metadata.category` defaults to "plain" — the safest category
+   *     (no runtime / tool execution expected). The user can edit
+   *     post-import.
+   *   - `tags` / `runtime` / `tools` are extracted when they look
+   *     plausibly correct, dropped silently otherwise.
+   */
+  private extractSkillInfoLenient(
+    raw: Record<string, unknown>,
+  ): {
+    name: string;
+    description: string;
+    version: string;
+    license: string | null;
+    compatibility: string | null;
+    metadata: SkillMetadata;
+    releaseNotes: string | null;
+  } {
+    const name =
+      typeof raw.name === "string" && raw.name.trim().length > 0
+        ? raw.name.trim()
+        : null;
+    if (!name) {
+      throw AppError.badRequest(
+        "frontmatter_validation_failed",
+        "name: required (cannot be derived under skipValidation either)",
+      );
+    }
+    const description =
+      typeof raw.description === "string" ? raw.description : "";
+    const version =
+      typeof raw.version === "string" && raw.version.trim().length > 0
+        ? raw.version.trim()
+        : "0.1";
+    const license = typeof raw.license === "string" ? raw.license : null;
+    const compatibility =
+      typeof raw.compatibility === "string" ? raw.compatibility : null;
+
+    const rawMeta =
+      raw.metadata && typeof raw.metadata === "object" && !Array.isArray(raw.metadata)
+        ? (raw.metadata as Record<string, unknown>)
+        : {};
+    const category =
+      typeof rawMeta.category === "string" ? rawMeta.category : "plain";
+
+    const tags =
+      Array.isArray(rawMeta.tag) &&
+      rawMeta.tag.every((t): t is string => typeof t === "string")
+        ? (rawMeta.tag as string[])
+        : undefined;
+
+    const metadata: SkillMetadata = { category };
+    if (tags && tags.length > 0) metadata.tags = tags;
+
+    const rawReleaseNotes = raw["release-notes"] ?? raw["releaseNotes"];
+    let releaseNotes: string | null = null;
+    if (typeof rawReleaseNotes === "string" && rawReleaseNotes.trim().length > 0) {
+      const trimmed = rawReleaseNotes.trim();
+      releaseNotes = trimmed.length > 2000 ? trimmed.slice(0, 2000) : trimmed;
+    }
+
+    return {
+      name,
+      description,
+      version,
+      license,
+      compatibility,
+      metadata,
+      releaseNotes,
+    };
+  }
+
   private async buildDetailResponse(
     skill: SkillDocument,
     versionOverlay?: SkillVersionDocument,
@@ -1248,7 +1612,6 @@ export class SkillService {
       skillHash,
       presignedPackageUrl,
       isPrivate: skill.isPrivate,
-      ownerId: skill.ownerId,
       createdBy: skill.createdBy,
       createdByEmail: skill.createdByEmail,
       createdByDisplayName: skill.createdByDisplayName,
@@ -1281,6 +1644,10 @@ export class SkillService {
       nyxidServiceSlug: skill.nyxidServiceSlug ?? null,
       nyxidServiceLabel: skill.nyxidServiceLabel ?? null,
       isSystemSkill: skill.isSystemSkill === true,
+      // Always surface a `latest` tag — legacy skills predating #463
+      // get one synthesized from `latestVersion` so consumers can rely
+      // on `distTags.latest` always being set.
+      distTags: { latest: skill.latestVersion, ...(skill.distTags ?? {}) },
       ...(skill.mirrorSync && skill.mirrorSync.syncedAt instanceof Date
         ? {
             mirrorSync: {
@@ -1369,7 +1736,10 @@ export class SkillService {
       return violations;
     }
 
-    const yamlBlock = fmMatch[1];
+    // FRONTMATTER_REGEX always has capture group 1 (the YAML body)
+    // when it matches. `!` is safe under noUncheckedIndexedAccess
+    // (#450).
+    const yamlBlock = fmMatch[1]!;
     if (yamlBlock.includes("<") || yamlBlock.includes(">")) {
       violations.push({
         rule: "no-xml-brackets",
diff --git a/ornn-api/src/domains/skills/crud/skillVersionRepository.ts b/ornn-api/src/domains/skills/crud/skillVersionRepository.ts
index d54c3a99..712dcd12 100644
--- a/ornn-api/src/domains/skills/crud/skillVersionRepository.ts
+++ b/ornn-api/src/domains/skills/crud/skillVersionRepository.ts
@@ -11,10 +11,11 @@
 import type { Collection, Db, Document } from "mongodb";
 import type { SkillVersionDocument, SkillMetadata } from "../../../shared/types/index";
 import { AppError } from "../../../shared/types/index";
-import pino from "pino";
-
-const logger = pino({ level: "info" }).child({ module: "skillVersionRepository" });
+import { createLogger } from "../../../shared/logger";
+const logger = createLogger("skillVersionRepository");
 
+// Optionals widen to `T | undefined` so call sites passing
+// optionally-present strings fit under exactOptionalPropertyTypes (#657).
 export interface CreateSkillVersionData {
   skillGuid: string;
   version: string;
@@ -23,14 +24,14 @@ export interface CreateSkillVersionData {
   storageKey: string;
   skillHash: string;
   metadata: SkillMetadata;
-  license?: string | null;
-  compatibility?: string | null;
+  license?: string | null | undefined;
+  compatibility?: string | null | undefined;
   createdBy: string;
-  createdByEmail?: string;
-  createdByDisplayName?: string;
-  createdOn?: Date;
+  createdByEmail?: string | undefined;
+  createdByDisplayName?: string | undefined;
+  createdOn?: Date | undefined;
   /** Author-supplied release notes pulled from SKILL.md frontmatter. */
-  releaseNotes?: string | null;
+  releaseNotes?: string | null | undefined;
 }
 
 /**
@@ -225,7 +226,7 @@ export class SkillVersionRepository {
     const updated = mapDoc(result);
     if (!updated) {
       throw AppError.notFound(
-        "SKILL_VERSION_NOT_FOUND",
+        "skill_version_not_found",
         `Version '${version}' not found for skill '${skillGuid}'`,
       );
     }
diff --git a/ornn-api/src/domains/skills/crud/utils/githubPull.ts b/ornn-api/src/domains/skills/crud/utils/githubPull.ts
index 3c55f141..9a222ed7 100644
--- a/ornn-api/src/domains/skills/crud/utils/githubPull.ts
+++ b/ornn-api/src/domains/skills/crud/utils/githubPull.ts
@@ -15,21 +15,22 @@
  */
 
 import JSZip from "jszip";
-import pino from "pino";
-
-const logger = pino({ level: "info" }).child({ module: "githubSkillPull" });
+import { createLogger } from "../../../../shared/logger";
+const logger = createLogger("githubSkillPull");
 
 export interface GitHubPullInput {
   /** `owner/name`. */
   readonly repo: string;
+  // Optional fields widen to `T | undefined` so callers with optional
+  // input values fit under exactOptionalPropertyTypes (#657).
   /** Branch, tag, or commit SHA. Defaults to the repo's default branch. */
-  readonly ref?: string;
+  readonly ref?: string | undefined;
   /** Directory inside the repo containing SKILL.md. `""` = repo root. */
-  readonly path?: string;
+  readonly path?: string | undefined;
   /** Max files to pull. Safety cap. Default 200. */
-  readonly maxFiles?: number;
+  readonly maxFiles?: number | undefined;
   /** Max total bytes. Safety cap. Default 10 MiB. */
-  readonly maxTotalBytes?: number;
+  readonly maxTotalBytes?: number | undefined;
 }
 
 export interface GitHubPullResult {
@@ -94,7 +95,9 @@ export function normalizePath(path: string | undefined): string {
  * path=skills/x OR ref=feature path=foo-bar/skills/x. The user can fall
  * back to the explicit `{ repo, ref, path }` form for those.
  */
-export function parseGithubUrl(rawUrl: string): { repo: string; ref?: string; path?: string } {
+export function parseGithubUrl(
+  rawUrl: string,
+): { repo: string; ref?: string | undefined; path?: string | undefined } {
   const url = rawUrl.trim();
   if (!url) throw new Error("GitHub URL is empty");
 
diff --git a/ornn-api/src/domains/skills/crud/utils/skillPackageBuilder.test.ts b/ornn-api/src/domains/skills/crud/utils/skillPackageBuilder.test.ts
index dc69279e..7f56d5d9 100644
--- a/ornn-api/src/domains/skills/crud/utils/skillPackageBuilder.test.ts
+++ b/ornn-api/src/domains/skills/crud/utils/skillPackageBuilder.test.ts
@@ -62,8 +62,8 @@ describe("collectUploadedFiles", () => {
     const file = new File(["content"], "test.ts");
     const result = collectUploadedFiles({ file_0: file });
     expect(result.length).toBe(1);
-    expect(result[0].file).toBe(file);
-    expect(result[0].folder).toBe("");
+    expect(result[0]!.file).toBe(file);
+    expect(result[0]!.folder).toBe("");
   });
 
   test("fileWithFolderMeta_usesFolderMeta", () => {
@@ -72,13 +72,13 @@ describe("collectUploadedFiles", () => {
       file_0: file,
       file_0_folder: "scripts",
     });
-    expect(result[0].folder).toBe("scripts");
+    expect(result[0]!.folder).toBe("scripts");
   });
 
   test("fileWithSlashInName_extractsFolderFromName", () => {
     const file = new File(["content"], "scripts/deploy.ts");
     const result = collectUploadedFiles({ file_0: file });
-    expect(result[0].folder).toBe("scripts");
+    expect(result[0]!.folder).toBe("scripts");
   });
 
   test("multipleFiles_collectsAll", () => {
diff --git a/ornn-api/src/domains/skills/crud/utils/skillPackageBuilder.ts b/ornn-api/src/domains/skills/crud/utils/skillPackageBuilder.ts
index 00dc90c0..d584c47c 100644
--- a/ornn-api/src/domains/skills/crud/utils/skillPackageBuilder.ts
+++ b/ornn-api/src/domains/skills/crud/utils/skillPackageBuilder.ts
@@ -5,8 +5,11 @@
  * @module utils/skillPackageBuilder
  */
 
+import { createLogger } from "../../../../shared/logger";
 import { createTarBuffer } from "../../../../shared/utils/tarBuilder";
 
+const logger = createLogger("skillPackageBuilder");
+
 /** Uploaded file entry with folder path metadata. */
 export interface UploadedFileEntry {
   file: File;
@@ -19,7 +22,12 @@ export function parseJsonStringArray(value: unknown): string[] {
   try {
     const parsed = JSON.parse(value);
     return Array.isArray(parsed) ? parsed : [];
-  } catch {
+  } catch (err) {
+    // Malformed JSON in an optional form field falls back to empty
+    // array — the caller treats this as "field not provided". Log
+    // at debug so we can spot a client repeatedly sending bad JSON
+    // (#579).
+    logger.debug({ err, valueHead: value.slice(0, 80) }, "parseJsonStringArray: malformed JSON");
     return [];
   }
 }
@@ -57,7 +65,10 @@ export function collectUploadedFiles(
 
     // If filename already has a folder prefix (e.g., "scripts/deploy.ts"), use it
     if (file.name.includes("/")) {
-      folder = file.name.split("/")[0];
+      // `split("/")[0]` is always present when the string contains "/"
+      // (the substring before the first separator). `!` is safe under
+      // noUncheckedIndexedAccess (#450).
+      folder = file.name.split("/")[0]!;
     }
 
     files.push({ file, folder });
diff --git a/ornn-api/src/domains/skills/crud/utils/versionDiff.ts b/ornn-api/src/domains/skills/crud/utils/versionDiff.ts
index 53b6427e..d49d3234 100644
--- a/ornn-api/src/domains/skills/crud/utils/versionDiff.ts
+++ b/ornn-api/src/domains/skills/crud/utils/versionDiff.ts
@@ -100,7 +100,9 @@ async function extractFiles(zipBuffer: Uint8Array): Promise<Map<string, Uint8Arr
   const out = new Map<string, Uint8Array>();
   for (const path of allPaths) {
     const entry = zip.files[path];
-    if (entry.dir) continue;
+    // allPaths is `Object.keys(zip.files)`, but noUncheckedIndexedAccess
+    // (#450) widens the lookup to `T | undefined`. Defensive skip.
+    if (!entry || entry.dir) continue;
     const parts = path.split("/");
     let relative = path;
     if (parts.length > 1) {
diff --git a/ornn-api/src/domains/skills/crud/version.test.ts b/ornn-api/src/domains/skills/crud/version.test.ts
index 71c2b958..8f13454c 100644
--- a/ornn-api/src/domains/skills/crud/version.test.ts
+++ b/ornn-api/src/domains/skills/crud/version.test.ts
@@ -56,7 +56,7 @@ describe("parseVersion", () => {
     } catch (err) {
       expect(err).toBeInstanceOf(AppError);
       expect((err as AppError).statusCode).toBe(400);
-      expect((err as AppError).code).toBe("INVALID_VERSION");
+      expect((err as AppError).code).toBe("invalid_version");
     }
   });
 });
diff --git a/ornn-api/src/domains/skills/crud/version.ts b/ornn-api/src/domains/skills/crud/version.ts
index 68c64158..cab40f9d 100644
--- a/ornn-api/src/domains/skills/crud/version.ts
+++ b/ornn-api/src/domains/skills/crud/version.ts
@@ -24,12 +24,12 @@ export interface ParsedVersion {
  */
 export function parseVersion(raw: string): ParsedVersion {
   if (typeof raw !== "string") {
-    throw AppError.badRequest("INVALID_VERSION", `version must be a string, got ${typeof raw}`);
+    throw AppError.badRequest("invalid_version", `version must be a string, got ${typeof raw}`);
   }
   const match = raw.match(SKILL_VERSION_REGEX);
   if (!match) {
     throw AppError.badRequest(
-      "INVALID_VERSION",
+      "invalid_version",
       `version "${raw}" is invalid — expected "<major>.<minor>" (non-negative integers, no leading zeroes, no patch digit)`,
     );
   }
diff --git a/ornn-api/src/domains/skills/format/routes.test.ts b/ornn-api/src/domains/skills/format/routes.test.ts
new file mode 100644
index 00000000..ed91f940
--- /dev/null
+++ b/ornn-api/src/domains/skills/format/routes.test.ts
@@ -0,0 +1,85 @@
+/**
+ * Tests for the skill-format routes — focus on the JSON Schema
+ * publishing endpoint added in #464. The rules + validate endpoints
+ * are exercised end-to-end elsewhere; this file pins the wire shape
+ * IDEs and schemastore.org rely on.
+ *
+ * @module domains/skills/format/routes.test
+ */
+
+import { describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import {
+  createFormatRoutes,
+  SKILL_MANIFEST_JSON_SCHEMA,
+  SKILL_MANIFEST_SCHEMA_VERSION,
+} from "./routes";
+import type { SkillService } from "../crud/service";
+
+function fakeSkillService(): SkillService {
+  // Format routes only need `validateZipFormat`. The schema endpoint
+  // never touches the service, so a barely-populated stub is enough.
+  return {
+    validateZipFormat: async () => [],
+  } as unknown as SkillService;
+}
+
+function makeApp(): Hono {
+  const routes = createFormatRoutes({ skillService: fakeSkillService() });
+  const app = new Hono();
+  app.route("/api/v1", routes);
+  return app;
+}
+
+describe("GET /api/v1/skill-manifest-schema.json (#464)", () => {
+  test("returns the JSON Schema with application/schema+json content type", async () => {
+    const app = makeApp();
+    const res = await app.request("/api/v1/skill-manifest-schema.json");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("application/schema+json");
+  });
+
+  test("body is a JSON Schema document at the root (no { data, error } envelope)", async () => {
+    const app = makeApp();
+    const res = await app.request("/api/v1/skill-manifest-schema.json");
+    const body = (await res.json()) as Record<string, unknown>;
+    // Sniff for JSON Schema shape — at minimum it must declare a type
+    // and either properties or definitions. The legacy envelope would
+    // have `data` + `error` at the root; assert both are absent.
+    expect(body).not.toHaveProperty("data");
+    expect(body).not.toHaveProperty("error");
+    expect(body.type).toBe("object");
+    expect(body.properties).toBeDefined();
+  });
+
+  test("schema declares the canonical SKILL.md frontmatter properties", async () => {
+    // Use the in-process constant rather than re-fetching — same source,
+    // and keeps the test fast.
+    const props = (SKILL_MANIFEST_JSON_SCHEMA as { properties: Record<string, unknown> }).properties;
+    expect(props).toBeDefined();
+    // Required top-level fields per the canonical frontmatter spec.
+    expect(props.name).toBeDefined();
+    expect(props.description).toBeDefined();
+    expect(props.version).toBeDefined();
+    expect(props.metadata).toBeDefined();
+  });
+
+  test("schema is cacheable (long-lived Cache-Control)", async () => {
+    const app = makeApp();
+    const res = await app.request("/api/v1/skill-manifest-schema.json");
+    const cc = res.headers.get("cache-control") ?? "";
+    // IDEs / schemastore.org refetch on expiry; the value isn't strict
+    // but it MUST be a public, finite-max-age cache directive. Anything
+    // missing or `no-store` would hammer the server.
+    expect(cc).toMatch(/public/);
+    expect(cc).toMatch(/max-age=\d+/);
+  });
+
+  test("SKILL_MANIFEST_SCHEMA_VERSION is set", () => {
+    // Schema version is a stable identifier for external tooling
+    // (schemastore.org pins to a specific revision). Just sanity-check
+    // it's a non-empty string — the value itself is bumped manually.
+    expect(typeof SKILL_MANIFEST_SCHEMA_VERSION).toBe("string");
+    expect(SKILL_MANIFEST_SCHEMA_VERSION.length).toBeGreaterThan(0);
+  });
+});
diff --git a/ornn-api/src/domains/skills/format/routes.ts b/ornn-api/src/domains/skills/format/routes.ts
index 2ac09f9a..4da56fb6 100644
--- a/ornn-api/src/domains/skills/format/routes.ts
+++ b/ornn-api/src/domains/skills/format/routes.ts
@@ -1,11 +1,13 @@
 /**
  * Skill format rules and validation routes.
- * GET  /api/skill-format/rules    — public, returns format rules markdown
- * POST /api/skill-format/validate — authenticated, validates ZIP against rules
+ * GET  /api/skill-format/rules           — public, returns format rules markdown
+ * POST /api/skill-format/validate        — authenticated, validates ZIP against rules
+ * GET  /api/skill-manifest-schema.json   — public, JSON Schema for SKILL.md frontmatter (#464)
  * @module domains/skills/format/routes
  */
 
 import { Hono } from "hono";
+import { z } from "zod";
 import type { SkillService } from "../crud/service";
 import {
   type AuthVariables,
@@ -13,6 +15,8 @@ import {
   requirePermission,
 } from "../../../middleware/nyxidAuth";
 import { AppError } from "../../../shared/types/index";
+import { skillFrontmatterSchema } from "../../../shared/schemas/skillFrontmatter";
+import { enforceZipLimits } from "../../../shared/utils/zipLimits";
 
 /** Canonical skill format rules per the ornn platform spec. Updated with output-type. */
 export const SKILL_FORMAT_RULES = `# Ornn Skill Package Format Rules
@@ -64,6 +68,28 @@ export const SKILL_FORMAT_RULES = `# Ornn Skill Package Format Rules
 - **compatibility** (string, optional): must be under 500 characters.
 `;
 
+/**
+ * Stable version identifier for the published JSON Schema (#464). Bump
+ * this when the frontmatter contract changes in a way external tooling
+ * cares about. Embedded in the schema's `$id` so consumers can pin a
+ * specific revision and so IDE / linter caches invalidate on bumps.
+ */
+export const SKILL_MANIFEST_SCHEMA_VERSION = "1";
+
+/**
+ * JSON Schema for SKILL.md frontmatter, derived from the canonical Zod
+ * schema via zod 4's built-in `z.toJSONSchema()`. Computed once at
+ * module load — the source schema is static, so re-running the
+ * conversion per request is wasted work.
+ *
+ * The legacy `zod-to-json-schema` package emits empty schemas against
+ * zod 4 (the AST shape changed); the in-tree converter is the only
+ * working option until that package catches up. Output is JSON Schema
+ * draft-2020-12 — what `z.toJSONSchema` produces and what current IDEs
+ * + schemastore.org consume.
+ */
+export const SKILL_MANIFEST_JSON_SCHEMA = z.toJSONSchema(skillFrontmatterSchema);
+
 export interface FormatRoutesConfig {
   skillService: SkillService;
 }
@@ -81,6 +107,24 @@ export function createFormatRoutes(config: FormatRoutesConfig): Hono<{ Variables
     return c.json({ data: { rules: SKILL_FORMAT_RULES }, error: null });
   });
 
+  /**
+   * GET /skill-manifest-schema.json — Public, IDE-friendly JSON Schema
+   * for `SKILL.md` frontmatter (#464). No auth, long-cacheable: the
+   * schema is static for a given build, and IDEs / schemastore.org
+   * consumers re-fetch on cache expiry.
+   *
+   * Content-Type is `application/schema+json` per IANA registration —
+   * not the generic `application/json` — so VS Code / Cursor and
+   * schema-store tools that sniff the response type pick it up
+   * correctly.
+   */
+  app.get("/skill-manifest-schema.json", async (c) => {
+    return c.json(SKILL_MANIFEST_JSON_SCHEMA, 200, {
+      "Content-Type": "application/schema+json",
+      "Cache-Control": "public, max-age=3600",
+    });
+  });
+
   /**
    * POST /skill-format/validate — Authenticated, validates ZIP.
    * Requires: ornn:skill:read
@@ -92,16 +136,22 @@ export function createFormatRoutes(config: FormatRoutesConfig): Hono<{ Variables
     async (c) => {
       const contentType = c.req.header("content-type") ?? "";
       if (!contentType.includes("application/zip") && !contentType.includes("application/octet-stream")) {
-        throw AppError.badRequest("INVALID_CONTENT_TYPE", "Expected application/zip content type");
+        throw AppError.badRequest("invalid_content_type", "Expected application/zip content type");
       }
 
       const body = await c.req.arrayBuffer();
       if (!body || body.byteLength === 0) {
-        throw AppError.badRequest("EMPTY_BODY", "Request body is empty");
+        throw AppError.badRequest("empty_body", "Request body is empty");
       }
 
       const zipBuffer = new Uint8Array(body);
 
+      // Zip-bomb defense (#633) — same gate as the publish path. The
+      // /skill-format/validate endpoint is authenticated but otherwise
+      // unrestricted, so an attacker can still slow us down here with
+      // pathological ZIPs unless we cap before extraction.
+      await enforceZipLimits(zipBuffer);
+
       // `validateZipFormat` returns the full list of rule violations.
       // An empty array means the package is valid; anything non-empty is what
       // the client agent needs to fix. Surface the entire list so a single
diff --git a/ornn-api/src/domains/skills/generation/bootstrap.ts b/ornn-api/src/domains/skills/generation/bootstrap.ts
new file mode 100644
index 00000000..4d401a97
--- /dev/null
+++ b/ornn-api/src/domains/skills/generation/bootstrap.ts
@@ -0,0 +1,51 @@
+/**
+ * Wire the skill-generation domain (#580 — bootstrap decomposition).
+ *
+ * Generation has more downstream coupling than search — it owns its
+ * own surface (`skillGen`) in settings, so the keep-alive interval
+ * + default model both resolve through settingsService. It also
+ * mounts QuotaService (every generation charges the user's
+ * skill-gen bucket) and LlmProvidersService (the picker behind the
+ * SSE init event).
+ *
+ * @module domains/skills/generation/bootstrap
+ */
+
+import type { Hono } from "hono";
+import type { AuthVariables } from "../../../middleware/nyxidAuth";
+import { SkillGenerationService } from "./service";
+import { createGenerationRoutes } from "./routes";
+import type { NyxLlmClient } from "../../../clients/nyxid/llm";
+import type { QuotaService } from "../../quota/service";
+import type { LlmProvidersService } from "../../settings/llmProviders/service";
+
+export interface SkillGenerationWiring {
+  readonly service: SkillGenerationService;
+  readonly routes: Hono<{ Variables: AuthVariables }>;
+}
+
+export function wireSkillGeneration(deps: {
+  llmClient: NyxLlmClient;
+  /** Returns `{ model, maxOutputTokens, temperature }` snapshot for the skillGen surface. */
+  defaultsResolver: () => Promise<{
+    model: string;
+    maxOutputTokens: number;
+    temperature: number;
+  }>;
+  /** Per-request SSE keepalive interval (ms) — driven by `skillGen.sseKeepAliveMs`. */
+  keepAliveIntervalMsResolver: () => Promise<number>;
+  quotaService: QuotaService;
+  llmProvidersService: LlmProvidersService;
+}): SkillGenerationWiring {
+  const service = new SkillGenerationService({
+    llmClient: deps.llmClient,
+    defaultsResolver: deps.defaultsResolver,
+  });
+  const routes = createGenerationRoutes({
+    generationService: service,
+    keepAliveIntervalMsResolver: deps.keepAliveIntervalMsResolver,
+    quotaService: deps.quotaService,
+    llmProvidersService: deps.llmProvidersService,
+  });
+  return { service, routes };
+}
diff --git a/ornn-api/src/domains/skills/generation/githubFetcher.ts b/ornn-api/src/domains/skills/generation/githubFetcher.ts
index 1322ecaf..5dd96162 100644
--- a/ornn-api/src/domains/skills/generation/githubFetcher.ts
+++ b/ornn-api/src/domains/skills/generation/githubFetcher.ts
@@ -10,17 +10,16 @@
  * @module domains/skills/generation/githubFetcher
  */
 
-import pino from "pino";
-
-const logger = pino({ level: "info" }).child({ module: "githubFetcher" });
+import { createLogger } from "../../../shared/logger";
+const logger = createLogger("githubFetcher");
 
 export interface FetchOptions {
   /** Default: tries common route-folder names. */
-  readonly path?: string;
+  readonly path?: string | undefined;
   /** Max files to pull. Default 8. LLM context budget keeps this low. */
-  readonly maxFiles?: number;
+  readonly maxFiles?: number | undefined;
   /** Max bytes per file. Default 16 KiB. Prevents one giant file blowing context. */
-  readonly maxBytesPerFile?: number;
+  readonly maxBytesPerFile?: number | undefined;
 }
 
 export interface FetchedBundle {
@@ -29,7 +28,7 @@ export interface FetchedBundle {
   /** Files that were included in the bundle. */
   readonly files: ReadonlyArray<{ readonly path: string; readonly bytes: number }>;
   /** Detected framework hint ("express" / "fastapi" / ...), or undefined. */
-  readonly frameworkHint?: string;
+  readonly frameworkHint?: string | undefined;
   /** Original owner/repo/ref for audit. */
   readonly source: { readonly owner: string; readonly repo: string; readonly ref: string };
 }
@@ -47,6 +46,10 @@ export function parseRepoUrl(url: string): ParsedRepoUrl | null {
   try {
     u = new URL(url);
   } catch {
+    // Intentional silent (#579): caller treats null as "not a GitHub
+    // URL" and shows the user a validation error. Logging here would
+    // be noisy on every form-validation typo. The malformed URL is
+    // returned to the caller via the function signature.
     return null;
   }
   if (u.hostname !== "github.com") return null;
diff --git a/ornn-api/src/domains/skills/generation/prompts.ts b/ornn-api/src/domains/skills/generation/prompts.ts
index c6b17fcb..a162d32d 100644
--- a/ornn-api/src/domains/skills/generation/prompts.ts
+++ b/ornn-api/src/domains/skills/generation/prompts.ts
@@ -226,7 +226,8 @@ Output ONLY the JSON object. Nothing else.`;
  */
 export function buildOpenApiGenerationPrompt(
   specContent: string,
-  options?: { endpoints?: string[]; description?: string },
+  // exactOptionalPropertyTypes (#657)
+  options?: { endpoints?: string[] | undefined; description?: string | undefined },
 ): string {
   let prompt = `Generate a PLAIN API reference skill from this OpenAPI spec. Document ALL endpoints.\n\n${specContent}`;
 
@@ -269,7 +270,12 @@ Output rules:
  */
 export function buildSourceCodeGenerationPrompt(
   code: string,
-  options?: { framework?: string; description?: string; sourceUrl?: string },
+  // exactOptionalPropertyTypes (#657)
+  options?: {
+    framework?: string | undefined;
+    description?: string | undefined;
+    sourceUrl?: string | undefined;
+  },
 ): string {
   let prompt = "Generate a PLAIN API reference skill from the backend source code below. Document every endpoint you can identify.";
 
diff --git a/ornn-api/src/domains/skills/generation/routes.ts b/ornn-api/src/domains/skills/generation/routes.ts
index c0d37c02..3e80640a 100644
--- a/ornn-api/src/domains/skills/generation/routes.ts
+++ b/ornn-api/src/domains/skills/generation/routes.ts
@@ -21,11 +21,21 @@ import {
 } from "../../../middleware/nyxidAuth";
 import { AppError } from "../../../shared/types/index";
 import { resolveZipRoot } from "../../../shared/utils/zip";
+import { validateBody, getValidatedBody } from "../../../middleware/validate";
+import { rateLimit } from "../../../middleware/rateLimit";
 import { fetchGithubSourceBundle } from "./githubFetcher";
 import JSZip from "jszip";
-import pino from "pino";
+import { createLogger } from "../../../shared/logger";
+import { z } from "zod";
 
-const logger = pino({ level: "info" }).child({ module: "skillGenerationRoutes" });
+const logger = createLogger("skillGenerationRoutes");
+
+/**
+ * Per-message + per-prompt content cap (#654). Mirrors the playground
+ * chat schema's `MAX_CHAT_MESSAGE_CHARS` and the frontend
+ * `MAX_INPUT_CHARS` in `ChatInput.tsx`. Keep all three in sync.
+ */
+const MAX_GENERATION_CHARS = 32_000;
 
 export interface GenerationRoutesConfig {
   generationService: SkillGenerationService;
@@ -79,7 +89,8 @@ async function preflight(
 
   const resolution = await llmProvidersService.resolveModel({
     surface: "skillGen",
-    requested: requestedModelId,
+    // exactOptionalPropertyTypes (#657)
+    ...(requestedModelId !== undefined ? { requested: requestedModelId } : {}),
   });
   if (resolution.kind !== "ok") throwModelResolutionError(resolution);
   return { modelId: resolution.modelId, userId: authCtx.userId, permissions: authCtx.permissions };
@@ -163,13 +174,15 @@ async function analyzePackageContent(zipBuffer: Uint8Array): Promise<string> {
 
   for (const path of allPaths) {
     const file = zip.files[path];
-    if (file.dir) continue;
+    // allPaths is `Object.keys(zip.files)`, but noUncheckedIndexedAccess
+    // (#450) widens the lookup to `T | undefined`. Defensive skip.
+    if (!file || file.dir) continue;
 
     // Check if this is a relevant file
     const segments = path.split("/").filter(Boolean);
     let relativePath = path;
     if (segments.length > 1) {
-      const firstEntry = segments[0];
+      const firstEntry = segments[0]!;
       const folderEntry = zip.files[firstEntry + "/"];
       if (folderEntry && folderEntry.dir) {
         relativePath = segments.slice(1).join("/");
@@ -183,8 +196,11 @@ async function analyzePackageContent(zipBuffer: Uint8Array): Promise<string> {
       try {
         const content = await file.async("string");
         parts.push(`--- ${relativePath} ---\n${content}`);
-      } catch {
-        // Skip binary or unreadable files
+      } catch (err) {
+        // Skip binary or unreadable files. Log so an upload that's
+        // 100% binary doesn't silently produce an empty generation
+        // context (#579).
+        logger.debug({ err, relativePath }, "generation: skipping unreadable file");
       }
     }
   }
@@ -208,6 +224,11 @@ export function createGenerationRoutes(config: GenerationRoutesConfig): Hono<{ V
     "/skills/generate",
     auth,
     requirePermission("ornn:skill:build"),
+    // Rate limit (#439): every generation runs an LLM call —
+    // most expensive endpoint in the API. Per-user 20/min is
+    // ~3s minimum between requests, which still feels instant for
+    // legitimate flows while stopping a script from burning budget.
+    rateLimit({ windowMs: 60_000, max: 20, label: "skills-generate" }),
     async (c) => {
       const contentType = c.req.header("content-type") ?? "";
       const authCtx = getAuth(c);
@@ -219,7 +240,7 @@ export function createGenerationRoutes(config: GenerationRoutesConfig): Hono<{ V
         const body = await c.req.parseBody({ all: true });
 
         if (typeof body["prompt"] !== "string" || !body["prompt"]) {
-          throw AppError.badRequest("MISSING_PROMPT", "A 'prompt' field is required");
+          throw AppError.badRequest("missing_prompt", "A 'prompt' field is required");
         }
         prompt = body["prompt"];
 
@@ -233,30 +254,70 @@ export function createGenerationRoutes(config: GenerationRoutesConfig): Hono<{ V
           packageContent = await analyzePackageContent(new Uint8Array(buf));
         }
       } else if (contentType.includes("application/json")) {
-        const body = await c.req.json();
+        // Hybrid endpoint — multipart-or-JSON. Inline Zod parse so
+        // malformed JSON returns 400 invalid_body via the global RFC
+        // 7807 handler instead of a raw SyntaxError 500 (#438).
+        let body: { modelId?: string; messages?: unknown[]; prompt?: string };
+        try {
+          const text = await c.req.text();
+          const raw = text.trim().length === 0 ? {} : JSON.parse(text);
+          if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+            throw AppError.badRequest("invalid_body", "Request body must be a JSON object");
+          }
+          body = raw as typeof body;
+        } catch (err) {
+          if (err instanceof AppError) throw err;
+          throw AppError.badRequest("invalid_body", "Request body must be valid JSON");
+        }
         if (typeof body.modelId === "string" && body.modelId) {
           requestedModelId = body.modelId;
         }
 
         // Multi-turn format: messages array
         if (body.messages && Array.isArray(body.messages)) {
+          // #654 — per-message content cap. Mirrors the playground
+          // chat schema's `.max(MAX_CHAT_MESSAGE_CHARS)` so both
+          // surfaces enforce the same ceiling.
+          for (const m of body.messages) {
+            if (
+              m && typeof m === "object" && "content" in m &&
+              typeof (m as { content: unknown }).content === "string" &&
+              (m as { content: string }).content.length > MAX_GENERATION_CHARS
+            ) {
+              throw AppError.badRequest(
+                "content_too_long",
+                `Message content exceeds ${MAX_GENERATION_CHARS} character limit`,
+              );
+            }
+          }
           logger.info({ userId: authCtx.userId, messageCount: body.messages.length }, "Multi-turn generation request");
           const pf = await preflight(c, quotaService, llmProvidersService, requestedModelId);
           const keepAliveMs = await resolveKeepAliveMs(keepAliveIntervalMsResolver);
           return streamGenerationEvents(
             c,
-            generationService.generateStreamWithHistory(body.messages, c.req.raw.signal, pf.modelId),
+            generationService.generateStreamWithHistory(
+              body.messages as Array<{ role: "user" | "assistant"; content: string }>,
+              c.req.raw.signal,
+              pf.modelId,
+            ),
             keepAliveMs,
             { quotaService, userId: pf.userId, permissions: pf.permissions, modelId: pf.modelId },
           );
         }
 
         if (!body.prompt || typeof body.prompt !== "string") {
-          throw AppError.badRequest("MISSING_PROMPT", "A 'prompt' field is required");
+          throw AppError.badRequest("missing_prompt", "A 'prompt' field is required");
+        }
+        if (body.prompt.length > MAX_GENERATION_CHARS) {
+          // #654 — symmetric with the multi-turn branch above.
+          throw AppError.badRequest(
+            "prompt_too_long",
+            `Prompt exceeds ${MAX_GENERATION_CHARS} character limit`,
+          );
         }
         prompt = body.prompt;
       } else {
-        throw AppError.badRequest("INVALID_CONTENT_TYPE", "Expected multipart/form-data or application/json");
+        throw AppError.badRequest("invalid_content_type", "Expected multipart/form-data or application/json");
       }
 
       const signal = c.req.raw.signal;
@@ -295,27 +356,38 @@ export function createGenerationRoutes(config: GenerationRoutesConfig): Hono<{ V
     "/skills/generate/from-source",
     auth,
     requirePermission("ornn:skill:build"),
+    validateBody(
+      z.object({
+        code: z.string().optional(),
+        repoUrl: z.string().optional(),
+        path: z.string().optional(),
+        framework: z.string().optional(),
+        description: z.string().optional(),
+        modelId: z.string().optional(),
+      }),
+      "invalid_from_source_body",
+    ),
     async (c) => {
       const authCtx = getAuth(c);
-      const body = (await c.req.json().catch(() => ({}))) as {
-        code?: unknown;
-        repoUrl?: unknown;
-        path?: unknown;
-        framework?: unknown;
-        description?: unknown;
-        modelId?: unknown;
-      };
-
-      const inlineCode = typeof body.code === "string" ? body.code : undefined;
-      const repoUrl = typeof body.repoUrl === "string" ? body.repoUrl : undefined;
-      const path = typeof body.path === "string" ? body.path : undefined;
-      const framework = typeof body.framework === "string" ? body.framework : undefined;
-      const description = typeof body.description === "string" ? body.description : undefined;
-      const requestedModelId = typeof body.modelId === "string" ? body.modelId : undefined;
+      const body = getValidatedBody<{
+        code?: string;
+        repoUrl?: string;
+        path?: string;
+        framework?: string;
+        description?: string;
+        modelId?: string;
+      }>(c);
+
+      const inlineCode = body.code;
+      const repoUrl = body.repoUrl;
+      const path = body.path;
+      const framework = body.framework;
+      const description = body.description;
+      const requestedModelId = body.modelId;
 
       if (!inlineCode && !repoUrl) {
         throw AppError.badRequest(
-          "MISSING_SOURCE",
+          "missing_source",
           "Provide either 'code' (inline source) or 'repoUrl' (public GitHub URL)",
         );
       }
@@ -347,12 +419,12 @@ export function createGenerationRoutes(config: GenerationRoutesConfig): Hono<{ V
           );
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
-          throw AppError.badRequest("REPO_FETCH_FAILED", `Could not fetch repository: ${message}`);
+          throw AppError.badRequest("repo_fetch_failed", `Could not fetch repository: ${message}`);
         }
       }
 
       if (!code.trim()) {
-        throw AppError.badRequest("EMPTY_SOURCE", "Source code is empty — nothing to analyze");
+        throw AppError.badRequest("empty_source", "Source code is empty — nothing to analyze");
       }
 
       logger.info(
@@ -394,17 +466,27 @@ export function createGenerationRoutes(config: GenerationRoutesConfig): Hono<{ V
     "/skills/generate/from-openapi",
     auth,
     requirePermission("ornn:skill:build"),
+    validateBody(
+      z.object({
+        spec: z.string().min(1),
+        endpoints: z.array(z.unknown()).optional(),
+        description: z.string().optional(),
+        modelId: z.string().optional(),
+      }),
+      "invalid_from_openapi_body",
+    ),
     async (c) => {
       const authCtx = getAuth(c);
-      const body = await c.req.json();
-
-      if (!body.spec || typeof body.spec !== "string") {
-        throw AppError.badRequest("MISSING_SPEC", "An OpenAPI 'spec' field (JSON or YAML string) is required");
-      }
+      const body = getValidatedBody<{
+        spec: string;
+        endpoints?: unknown[];
+        description?: string;
+        modelId?: string;
+      }>(c);
 
-      const endpoints = Array.isArray(body.endpoints) ? body.endpoints : undefined;
-      const description = typeof body.description === "string" ? body.description : undefined;
-      const requestedModelId = typeof body.modelId === "string" ? body.modelId : undefined;
+      const endpoints = body.endpoints;
+      const description = body.description;
+      const requestedModelId = body.modelId;
 
       logger.info(
         { userId: authCtx.userId, specLength: body.spec.length, endpoints, hasDescription: !!description },
@@ -417,7 +499,12 @@ export function createGenerationRoutes(config: GenerationRoutesConfig): Hono<{ V
       const keepAliveMs = await resolveKeepAliveMs(keepAliveIntervalMsResolver);
       return streamGenerationEvents(
         c,
-        generationService.generateFromOpenApi(body.spec, { endpoints, description }, signal, pf.modelId),
+        generationService.generateFromOpenApi(
+          body.spec,
+          { endpoints: endpoints as string[] | undefined, description },
+          signal,
+          pf.modelId,
+        ),
         keepAliveMs,
         { quotaService, userId: pf.userId, permissions: pf.permissions, modelId: pf.modelId },
       );
diff --git a/ornn-api/src/domains/skills/generation/service.ts b/ornn-api/src/domains/skills/generation/service.ts
index 78ac7517..58d3b295 100644
--- a/ornn-api/src/domains/skills/generation/service.ts
+++ b/ornn-api/src/domains/skills/generation/service.ts
@@ -16,9 +16,8 @@ import {
   OPENAPI_GENERATION_SYSTEM_PROMPT,
   SOURCE_CODE_GENERATION_SYSTEM_PROMPT,
 } from "./prompts";
-import pino from "pino";
-
-const logger = pino({ level: "info" }).child({ module: "skillGenerationService" });
+import { createLogger } from "../../../shared/logger";
+const logger = createLogger("skillGenerationService");
 
 const generatedSkillSchema = z.object({
   name: z.string().min(1).max(100).regex(/^[a-z0-9-]+$/),
@@ -283,7 +282,8 @@ export class SkillGenerationService {
    */
   async *generateFromOpenApi(
     specContent: string,
-    options?: { endpoints?: string[]; description?: string },
+    // exactOptionalPropertyTypes (#657)
+    options?: { endpoints?: string[] | undefined; description?: string | undefined },
     signal?: AbortSignal,
     modelOverride?: string,
   ): AsyncIterable<SkillStreamEvent> {
@@ -357,7 +357,12 @@ export class SkillGenerationService {
    */
   async *generateFromSource(
     code: string,
-    options?: { framework?: string; description?: string; sourceUrl?: string },
+    // exactOptionalPropertyTypes (#657)
+    options?: {
+      framework?: string | undefined;
+      description?: string | undefined;
+      sourceUrl?: string | undefined;
+    },
     signal?: AbortSignal,
     modelOverride?: string,
   ): AsyncIterable<SkillStreamEvent> {
@@ -446,8 +451,18 @@ export class SkillGenerationService {
         return null;
       }
 
-      return result.data;
-    } catch {
+      // The Zod-inferred shape and GeneratedSkill match in spirit but
+      // Zod surfaces `outputType` as `"text" | "file" | undefined`
+      // (explicit undefined, not optional) which exactOptionalPropertyTypes
+      // (#657) treats as different from the interface's `outputType?:`.
+      // Same runtime shape; cast is safe.
+      return result.data as GeneratedSkill;
+    } catch (err) {
+      // Generated-skill JSON parse failed. Caller treats null as
+      // "regenerate" or "give up" depending on retry budget. Logging
+      // so we can spot a model that's consistently producing
+      // unparseable output (#579).
+      logger.debug({ err }, "generated skill JSON parse failed");
       return null;
     }
   }
diff --git a/ornn-api/src/domains/skills/generation/types/generation.ts b/ornn-api/src/domains/skills/generation/types/generation.ts
index 348e1fd5..874ced46 100644
--- a/ornn-api/src/domains/skills/generation/types/generation.ts
+++ b/ornn-api/src/domains/skills/generation/types/generation.ts
@@ -13,6 +13,9 @@ export interface GeneratedSkill {
   envVars: string[];
   /** Script files to place in scripts/ directory. */
   scripts: Array<{ filename: string; content: string }>;
+  // exactOptionalPropertyTypes (#657): matches the Zod schema enum
+  // (`["text", "file"]`) — optional, so we widen with `| undefined`.
+  outputType?: "text" | "file" | undefined;
 }
 
 /** Options for LLM completion calls. */
diff --git a/ornn-api/src/domains/skills/mirror/githubAppAuth.ts b/ornn-api/src/domains/skills/mirror/githubAppAuth.ts
index 910ac971..be816741 100644
--- a/ornn-api/src/domains/skills/mirror/githubAppAuth.ts
+++ b/ornn-api/src/domains/skills/mirror/githubAppAuth.ts
@@ -17,9 +17,8 @@
  */
 
 import { createSign, createPrivateKey } from "node:crypto";
-import pino from "pino";
-
-const logger = pino({ level: "info" }).child({ module: "githubAppAuth" });
+import { createLogger } from "../../../shared/logger";
+const logger = createLogger("githubAppAuth");
 
 export interface GitHubAppCredentials {
   appId: string;
diff --git a/ornn-api/src/domains/skills/mirror/githubMirrorClient.ts b/ornn-api/src/domains/skills/mirror/githubMirrorClient.ts
index 78e8da45..f705d483 100644
--- a/ornn-api/src/domains/skills/mirror/githubMirrorClient.ts
+++ b/ornn-api/src/domains/skills/mirror/githubMirrorClient.ts
@@ -17,10 +17,10 @@
  * @module domains/skills/mirror/githubMirrorClient
  */
 
-import pino from "pino";
+import { createLogger } from "../../../shared/logger";
 import { GitHubAppAuth } from "./githubAppAuth";
 
-const logger = pino({ level: "info" }).child({ module: "githubMirrorClient" });
+const logger = createLogger("githubMirrorClient");
 
 export interface GitHubMirrorTarget {
   owner: string;
@@ -231,6 +231,9 @@ export class GitHubMirrorClient {
   ): Promise<Response> {
     const token = await this.auth.getInstallationToken();
     const url = `${GitHubMirrorClient.BASE}${path}`;
+    // exactOptionalPropertyTypes (#657): only stamp `body` when set so
+    // RequestInit doesn't receive a `body: undefined` (its body field
+    // is `BodyInit | null`, not optional-undefined).
     const init: RequestInit = {
       method,
       headers: {
@@ -240,7 +243,7 @@ export class GitHubMirrorClient {
         "User-Agent": "ornn-api-mirror",
         ...(body ? { "Content-Type": "application/json" } : {}),
       },
-      body: body ? JSON.stringify(body) : undefined,
+      ...(body ? { body: JSON.stringify(body) } : {}),
     };
     const resp = await fetch(url, init);
     logger.debug({ method, path, status: resp.status }, "github api call");
diff --git a/ornn-api/src/domains/skills/mirror/mirrorService.test.ts b/ornn-api/src/domains/skills/mirror/mirrorService.test.ts
index d9e2ddaf..43fe46a9 100644
--- a/ornn-api/src/domains/skills/mirror/mirrorService.test.ts
+++ b/ornn-api/src/domains/skills/mirror/mirrorService.test.ts
@@ -74,7 +74,6 @@ function makeSkill(overrides: Partial<SkillDocument> = {}): SkillDocument {
     metadata: { category: "plain" } as unknown as SkillDocument["metadata"],
     skillHash: "hash",
     storageKey: "key",
-    ownerId: "u1",
     createdBy: "u1",
     createdOn: new Date(),
     updatedBy: "u1",
@@ -279,7 +278,7 @@ describe("MirrorService privacy regression", () => {
     await svc.syncSkill("g-flip");
     // Expect one tree create with a sha:null entry for flip/SKILL.md.
     expect(calls.trees.length).toBe(1);
-    const entries = calls.trees[0].entries;
+    const entries = calls.trees[0]!.entries;
     const removalEntry = entries.find((e) => e.path === "flip/SKILL.md");
     expect(removalEntry).toBeDefined();
     expect(removalEntry?.sha).toBeNull();
diff --git a/ornn-api/src/domains/skills/mirror/mirrorService.ts b/ornn-api/src/domains/skills/mirror/mirrorService.ts
index 92154a98..f723e6e0 100644
--- a/ornn-api/src/domains/skills/mirror/mirrorService.ts
+++ b/ornn-api/src/domains/skills/mirror/mirrorService.ts
@@ -23,7 +23,7 @@
  */
 
 import { createHash } from "node:crypto";
-import pino from "pino";
+import { createLogger } from "../../../shared/logger";
 import { GitHubAppAuth } from "./githubAppAuth";
 import { GitHubMirrorClient, type TreeEntry } from "./githubMirrorClient";
 import type { SkillRepository } from "../crud/repository";
@@ -31,7 +31,7 @@ import type { SkillService } from "../crud/service";
 import type { SkillDocument } from "../../../shared/types/index";
 import type { MirrorSection } from "../../settings/sections/mirror";
 
-const logger = pino({ level: "info" }).child({ module: "mirrorService" });
+const logger = createLogger("mirrorService");
 
 /**
  * Narrow surface MirrorService needs from SettingsService. Decouples
diff --git a/ornn-api/src/domains/skills/mirror/privateKeyValidation.test.ts b/ornn-api/src/domains/skills/mirror/privateKeyValidation.test.ts
new file mode 100644
index 00000000..b5820d02
--- /dev/null
+++ b/ornn-api/src/domains/skills/mirror/privateKeyValidation.test.ts
@@ -0,0 +1,113 @@
+/**
+ * Tests for validateGitHubAppPrivateKey (#441).
+ *
+ * Uses a freshly-generated RSA-2048 PEM (PKCS#1) as the happy-path
+ * input so the test is hermetic and the `createPrivateKey` round-trip
+ * actually exercises against a real key.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { generateKeyPairSync } from "node:crypto";
+import {
+  MAX_PRIVATE_KEY_BYTES,
+  validateGitHubAppPrivateKey,
+} from "./privateKeyValidation";
+
+function makePkcs1Pem(): string {
+  const { privateKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });
+  return privateKey.export({ type: "pkcs1", format: "pem" }).toString();
+}
+
+function makePkcs8Pem(): string {
+  const { privateKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });
+  return privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+}
+
+describe("validateGitHubAppPrivateKey — happy paths", () => {
+  test("PKCS#1 RSA PRIVATE KEY parses + round-trips through crypto", () => {
+    const pem = makePkcs1Pem();
+    const result = validateGitHubAppPrivateKey(pem);
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value).toBe(pem.trim());
+  });
+
+  test("PKCS#8 PRIVATE KEY accepted", () => {
+    const pem = makePkcs8Pem();
+    const result = validateGitHubAppPrivateKey(pem);
+    expect(result.ok).toBe(true);
+  });
+
+  test("CRLF line endings normalised to LF", () => {
+    const pem = makePkcs1Pem();
+    const crlf = pem.replace(/\n/g, "\r\n");
+    const result = validateGitHubAppPrivateKey(crlf);
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value).not.toContain("\r");
+  });
+
+  test("leading + trailing whitespace stripped", () => {
+    const pem = makePkcs1Pem();
+    const padded = `\n  ${pem}  \n`;
+    const result = validateGitHubAppPrivateKey(padded);
+    expect(result.ok).toBe(true);
+  });
+});
+
+describe("validateGitHubAppPrivateKey — rejections", () => {
+  test("non-string", () => {
+    const result = validateGitHubAppPrivateKey(42);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toMatch(/must be a string/);
+  });
+
+  test("empty string", () => {
+    const result = validateGitHubAppPrivateKey("");
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toMatch(/non-empty/);
+  });
+
+  test("oversize input fails before crypto sees it", () => {
+    const big = "A".repeat(MAX_PRIVATE_KEY_BYTES + 1);
+    const result = validateGitHubAppPrivateKey(big);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toMatch(/must be at most/);
+  });
+
+  test("embedded NUL rejected", () => {
+    const pem = makePkcs1Pem();
+    const polluted = pem.slice(0, 50) + "\0" + pem.slice(50);
+    const result = validateGitHubAppPrivateKey(polluted);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toMatch(/forbidden control byte/);
+  });
+
+  test("missing BEGIN line", () => {
+    const result = validateGitHubAppPrivateKey("blah\nMIIBOgIBAAJB...\n-----END RSA PRIVATE KEY-----");
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toMatch(/BEGIN/);
+  });
+
+  test("missing END line", () => {
+    const result = validateGitHubAppPrivateKey("-----BEGIN RSA PRIVATE KEY-----\nMIIBOgIBAA==\nstray");
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toMatch(/END/);
+  });
+
+  test("non-base64 body", () => {
+    const result = validateGitHubAppPrivateKey(
+      "-----BEGIN RSA PRIVATE KEY-----\nnot!base?64\n-----END RSA PRIVATE KEY-----",
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toMatch(/base64/);
+  });
+
+  test("truncated key body fails the crypto round-trip", () => {
+    const pem = makePkcs1Pem();
+    const lines = pem.split("\n");
+    // Drop ~half the body lines so the base64 still parses but the key doesn't.
+    const truncated = [lines[0]!, lines[1]!, lines[lines.length - 2]!, lines[lines.length - 1]!].join("\n");
+    const result = validateGitHubAppPrivateKey(truncated);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toMatch(/crypto\.createPrivateKey rejected/);
+  });
+});
diff --git a/ornn-api/src/domains/skills/mirror/privateKeyValidation.ts b/ornn-api/src/domains/skills/mirror/privateKeyValidation.ts
new file mode 100644
index 00000000..e1d9f031
--- /dev/null
+++ b/ornn-api/src/domains/skills/mirror/privateKeyValidation.ts
@@ -0,0 +1,105 @@
+/**
+ * Validate the shape of a GitHub App private key before it lands in
+ * settings (#441).
+ *
+ * Admins paste these PEM-encoded keys by hand into the platform
+ * settings UI. The original endpoint only checked `typeof === "string"`,
+ * which let malformed values (random whitespace, embedded NULs,
+ * truncated copy-paste) write garbage that surfaced much later as
+ * opaque crypto failures during a mirror run.
+ *
+ * This module fails fast at write time with a clear error.
+ *
+ * @module domains/skills/mirror/privateKeyValidation
+ */
+
+import { createPrivateKey } from "node:crypto";
+
+/** Cap on raw PEM size. A real RSA 4096 PEM is ~3.2 KB; 8 KB is comfortable headroom. */
+export const MAX_PRIVATE_KEY_BYTES = 8 * 1024;
+
+/** Accepted PEM headers — PKCS#1 (`RSA PRIVATE KEY`) is what GitHub App downloads emit;
+ *  PKCS#8 (`PRIVATE KEY`) is what `openssl pkcs8 -topk8` produces from the same key. */
+const PEM_HEADER_RX = /^-----BEGIN (?:RSA |EC )?PRIVATE KEY-----\s*$/;
+const PEM_FOOTER_RX = /^-----END (?:RSA |EC )?PRIVATE KEY-----\s*$/;
+
+/** Result type — narrowed `ok` discriminator instead of throwing keeps callers free to pick the error code. */
+export type ValidationResult =
+  | { readonly ok: true; readonly value: string }
+  | { readonly ok: false; readonly reason: string };
+
+/**
+ * Returns a normalised PEM string (LF line endings, no leading/trailing
+ * whitespace) when the input passes every shape check, or a reason
+ * string otherwise. Does not throw.
+ */
+export function validateGitHubAppPrivateKey(raw: unknown): ValidationResult {
+  if (typeof raw !== "string") {
+    return { ok: false, reason: "must be a string" };
+  }
+
+  if (raw.length === 0) {
+    return { ok: false, reason: "must be a non-empty PEM string" };
+  }
+
+  if (raw.length > MAX_PRIVATE_KEY_BYTES) {
+    return {
+      ok: false,
+      reason: `must be at most ${MAX_PRIVATE_KEY_BYTES} bytes (got ${raw.length})`,
+    };
+  }
+
+  // Reject NUL and other C0 control bytes that have no business in a
+  // PEM. Allow tab/CR/LF; everything else under 0x20 is junk.
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw.charCodeAt(i);
+    if (ch < 0x20 && ch !== 0x09 && ch !== 0x0a && ch !== 0x0d) {
+      return { ok: false, reason: `contains forbidden control byte 0x${ch.toString(16).padStart(2, "0")}` };
+    }
+  }
+
+  // Normalise CRLF → LF and strip outer whitespace so the BEGIN/END
+  // checks don't have to think about line endings.
+  const normalised = raw.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
+  const lines = normalised.split("\n");
+  if (lines.length < 3) {
+    return { ok: false, reason: "must include a BEGIN line, base64 body, and END line" };
+  }
+
+  const first = lines[0]!.trim();
+  const last = lines[lines.length - 1]!.trim();
+  if (!PEM_HEADER_RX.test(first)) {
+    return {
+      ok: false,
+      reason: "must start with `-----BEGIN RSA PRIVATE KEY-----` (PKCS#1) or `-----BEGIN PRIVATE KEY-----` (PKCS#8)",
+    };
+  }
+  if (!PEM_FOOTER_RX.test(last)) {
+    return {
+      ok: false,
+      reason: "must end with the matching `-----END … PRIVATE KEY-----` line",
+    };
+  }
+
+  // Body must be non-empty and base64-only (with whitespace between
+  // 64-char lines tolerated).
+  const body = lines.slice(1, -1).join("").replace(/\s+/g, "");
+  if (body.length === 0) {
+    return { ok: false, reason: "PEM body is empty" };
+  }
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(body)) {
+    return { ok: false, reason: "PEM body must be base64" };
+  }
+
+  // Final correctness check: actually parse it via Node's crypto.
+  // This catches keys that pass the shape check but are corrupted /
+  // truncated / for a different algorithm.
+  try {
+    createPrivateKey({ key: normalised, format: "pem" });
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    return { ok: false, reason: `crypto.createPrivateKey rejected the value: ${detail}` };
+  }
+
+  return { ok: true, value: normalised };
+}
diff --git a/ornn-api/src/domains/skills/mirror/routes.ts b/ornn-api/src/domains/skills/mirror/routes.ts
index c3387652..47122727 100644
--- a/ornn-api/src/domains/skills/mirror/routes.ts
+++ b/ornn-api/src/domains/skills/mirror/routes.ts
@@ -30,7 +30,9 @@
  */
 
 import { Hono } from "hono";
-import pino from "pino";
+import { createLogger } from "../../../shared/logger";
+import { z } from "zod";
+import { validateBody, getValidatedBody } from "../../../middleware/validate";
 import {
   type AuthVariables,
   nyxidAuthMiddleware,
@@ -43,8 +45,9 @@ import type { MirrorScheduler, ScheduledRunStatus } from "./scheduler";
 import type { SettingsService, SettingsActor } from "../../settings/types";
 import type { MirrorSection } from "../../settings/sections/mirror";
 import type { SkillRepository } from "../crud/repository";
+import { validateGitHubAppPrivateKey } from "./privateKeyValidation";
 
-const logger = pino({ level: "info" }).child({ module: "mirrorRoutes" });
+const logger = createLogger("mirrorRoutes");
 
 /**
  * GitHub naming validation.
@@ -158,8 +161,13 @@ export function createMirrorRoutes(
     "/github/repo",
     auth,
     requirePermission("ornn:admin:skill"),
+    // The per-field type / regex checks below are intricate (owner /
+    // repo name regex, app-id digits, PEM shape, branch protection).
+    // The middleware here just gates the JSON-object shape so a
+    // SyntaxError becomes 400 invalid_body (#438).
+    validateBody(z.record(z.string(), z.unknown()), "invalid_body"),
     async (c) => {
-      const body = (await c.req.json().catch(() => ({}))) as Record<string, unknown>;
+      const body = getValidatedBody<Record<string, unknown>>(c);
       const current = await settingsService.getMirror();
       const confirmAbandonOldRepo = body.confirmAbandonOldRepo === true;
 
@@ -167,7 +175,7 @@ export function createMirrorRoutes(
       let enabled = current.enabled;
       if ("enabled" in body) {
         if (typeof body.enabled !== "boolean") {
-          throw AppError.badRequest("INVALID_SETTING", "'enabled' must be a boolean.");
+          throw AppError.badRequest("invalid_setting", "'enabled' must be a boolean.");
         }
         enabled = body.enabled;
       }
@@ -180,7 +188,7 @@ export function createMirrorRoutes(
         const v = typeof body.owner === "string" ? body.owner.trim() : "";
         if (v.length > 0 && !OWNER_RE.test(v)) {
           throw AppError.badRequest(
-            "INVALID_OWNER",
+            "invalid_owner",
             "'owner' must be 1–39 chars of letters/digits/dashes, no leading/trailing dash.",
           );
         }
@@ -190,7 +198,7 @@ export function createMirrorRoutes(
         const v = typeof body.repo === "string" ? body.repo.trim() : "";
         if (v.length > 0 && !REPO_RE.test(v)) {
           throw AppError.badRequest(
-            "INVALID_REPO",
+            "invalid_repo",
             "'repo' must be 1–100 chars of letters/digits/dot/dash/underscore.",
           );
         }
@@ -215,7 +223,7 @@ export function createMirrorRoutes(
         const v = typeof body.appId === "string" ? body.appId.trim() : "";
         if (v.length > 0 && !APP_ID_RE.test(v)) {
           throw AppError.badRequest(
-            "INVALID_SETTING",
+            "invalid_setting",
             "'appId' must be 1–15 digits.",
           );
         }
@@ -225,7 +233,7 @@ export function createMirrorRoutes(
         const v = typeof body.installationId === "string" ? body.installationId.trim() : "";
         if (v.length > 0 && !INSTALLATION_ID_RE.test(v)) {
           throw AppError.badRequest(
-            "INVALID_SETTING",
+            "invalid_setting",
             "'installationId' must be 1–20 digits.",
           );
         }
@@ -235,15 +243,25 @@ export function createMirrorRoutes(
         const v = body.appPrivateKey;
         if (typeof v !== "string") {
           throw AppError.badRequest(
-            "INVALID_SETTING",
+            "invalid_setting",
             "'appPrivateKey' must be a string (empty = clear).",
           );
         }
         if (isMidMaskSentinel(v)) {
           // Round-trip of the mid-masked display value — keep stored key.
           appPrivateKey = current.appPrivateKey;
-        } else {
+        } else if (v === "") {
+          // Explicit clear.
           appPrivateKey = v;
+        } else {
+          const validated = validateGitHubAppPrivateKey(v);
+          if (!validated.ok) {
+            throw AppError.badRequest(
+              "invalid_setting",
+              `'appPrivateKey' ${validated.reason}.`,
+            );
+          }
+          appPrivateKey = validated.value;
         }
       }
 
@@ -254,7 +272,7 @@ export function createMirrorRoutes(
         const stampedCount = counts.synced + counts.lagging;
         if (stampedCount > 0 && !confirmAbandonOldRepo) {
           throw AppError.conflict(
-            "OLD_REPO_NOT_CONFIRMED",
+            "old_repo_not_confirmed",
             `Changing the mirror to ${owner}/${repo} would abandon ${stampedCount} skill(s) ` +
               `currently mirrored to ${current.owner}/${current.repo}. ` +
               `Pass confirmAbandonOldRepo: true to proceed; the old repo will not be cleaned up automatically.`,
@@ -332,7 +350,7 @@ export function createMirrorRoutes(
           {
             data: null,
             error: {
-              code: "MIRROR_DISABLED",
+              code: "mirror_disabled",
               message: !runtime.enabled
                 ? "GitHub mirror is disabled. Flip the kill switch in the admin UI to enable."
                 : "GitHub mirror is missing required credentials. Set owner/repo/branch + GitHub App credentials in the admin UI.",
@@ -346,7 +364,7 @@ export function createMirrorRoutes(
           {
             data: null,
             error: {
-              code: "RECONCILE_ALREADY_RUNNING",
+              code: "reconcile_already_running",
               message: `A reconcile is already in progress (started at ${reconcileState.startedAt?.toISOString() ?? "unknown"}).`,
             },
           },
diff --git a/ornn-api/src/domains/skills/mirror/scheduler.test.ts b/ornn-api/src/domains/skills/mirror/scheduler.test.ts
index 72925235..1140d8e5 100644
--- a/ornn-api/src/domains/skills/mirror/scheduler.test.ts
+++ b/ornn-api/src/domains/skills/mirror/scheduler.test.ts
@@ -53,7 +53,8 @@ mock.module("agenda", () => ({
       _data: unknown,
       options?: { timezone?: string },
     ) {
-      agendaCalls.every.push({ interval, name, options });
+      // exactOptionalPropertyTypes (#657)
+      agendaCalls.every.push({ interval, name, ...(options !== undefined ? { options } : {}) });
     }
     async cancel(opts: { name?: string }) {
       agendaCalls.cancel.push(opts);
diff --git a/ornn-api/src/domains/skills/search/bootstrap.ts b/ornn-api/src/domains/skills/search/bootstrap.ts
new file mode 100644
index 00000000..444b21e5
--- /dev/null
+++ b/ornn-api/src/domains/skills/search/bootstrap.ts
@@ -0,0 +1,55 @@
+/**
+ * Wire the skill-search domain (#580 — bootstrap decomposition).
+ *
+ * Search is a playground-flavoured LLM call: there's no dedicated
+ * `search` section in settings, so the default model resolves through
+ * the playground surface. The caller passes a `defaultModelResolver`
+ * closure rather than `settingsService` directly so we don't take a
+ * dependency on the whole settings surface for a single field read.
+ *
+ * @module domains/skills/search/bootstrap
+ */
+
+import type { Hono } from "hono";
+import type { AuthVariables } from "../../../middleware/nyxidAuth";
+import { SearchService } from "./service";
+import { createSearchRoutes } from "./routes";
+import type { SkillRepository } from "../crud/repository";
+import type { NyxLlmClient } from "../../../clients/nyxid/llm";
+import type { NyxidServiceClient } from "../../../clients/nyxid/service";
+
+export interface SkillSearchWiring {
+  readonly service: SearchService;
+  readonly routes: Hono<{ Variables: AuthVariables }>;
+}
+
+export function wireSkillSearch(deps: {
+  skillRepo: SkillRepository;
+  llmClient: NyxLlmClient;
+  /**
+   * Closure resolving the default model id at request time. Search
+   * shares the playground surface today; if backend-eng-2 adds a
+   * dedicated `search` section later, this stays the same — just
+   * route through the new section in the caller.
+   */
+  defaultModelResolver: () => Promise<string>;
+  /**
+   * NyxID catalog client + SA token accessor. Powers the live
+   * deactivation filter for `/skill-facets/system-services` (#715).
+   */
+  nyxidServiceClient: NyxidServiceClient;
+  getSaAccessToken: () => Promise<string>;
+}): SkillSearchWiring {
+  const service = new SearchService({
+    skillRepo: deps.skillRepo,
+    llmClient: deps.llmClient,
+    defaultModelResolver: deps.defaultModelResolver,
+  });
+  const routes = createSearchRoutes({
+    searchService: service,
+    skillRepo: deps.skillRepo,
+    nyxidServiceClient: deps.nyxidServiceClient,
+    getSaAccessToken: deps.getSaAccessToken,
+  });
+  return { service, routes };
+}
diff --git a/ornn-api/src/domains/skills/search/routes.ts b/ornn-api/src/domains/skills/search/routes.ts
index df7662d2..aaea9591 100644
--- a/ornn-api/src/domains/skills/search/routes.ts
+++ b/ornn-api/src/domains/skills/search/routes.ts
@@ -8,6 +8,7 @@ import { Hono } from "hono";
 import { z } from "zod";
 import type { SearchService } from "./service";
 import type { SkillRepository } from "../crud/repository";
+import type { NyxidServiceClient } from "../../../clients/nyxid/service";
 import {
   type AuthVariables,
   nyxidAuthMiddleware,
@@ -17,16 +18,31 @@ import {
 } from "../../../middleware/nyxidAuth";
 import { validateQuery, getValidatedQuery } from "../../../middleware/validate";
 import { AppError } from "../../../shared/types/index";
-import pino from "pino";
-
-const logger = pino({ level: "info" }).child({ module: "skillSearchRoutes" });
+import { createLogger } from "../../../shared/logger";
+import { decodeCursor, buildNextCursor } from "../../../shared/cursor";
+import { rateLimit } from "../../../middleware/rateLimit";
+const logger = createLogger("skillSearchRoutes");
 
 const searchQuerySchema = z.object({
-  query: z.string().max(2000).optional().default(""),
+  // Canonical search param is `q` per CONVENTIONS.md §4.1 (#586).
+  // The legacy `query` is still parsed for the duration of the alpha
+  // grace window — clients on the old SDK keep working until they
+  // upgrade. `q` wins when both are present.
+  q: z.string().max(2000).optional(),
+  query: z.string().max(2000).optional(),
   mode: z.enum(["keyword", "semantic"]).optional().default("keyword"),
   scope: z.enum(["public", "private", "mixed", "shared-with-me", "mine"]).optional().default("private"),
   page: z.coerce.number().int().min(1).optional().default(1),
   pageSize: z.coerce.number().int().min(1).max(100).optional().default(9),
+  /**
+   * Cursor-based pagination per CONVENTIONS.md §4.3 (#457). Opaque
+   * base64-JSON token returned by previous response's `meta.nextCursor`.
+   * When set, takes precedence over `page` (same `pageSize` still
+   * applies). Backward-compat: callers may still send `page=N` until
+   * the offset shape is sunset.
+   */
+  cursor: z.string().max(2048).optional(),
+  limit: z.coerce.number().int().min(1).max(100).optional(),
   model: z.string().optional(),
   /** System-skill tri-state filter. `any` (default) keeps all; `only`
    *  restricts to skills tied to an admin/platform NyxID service
@@ -54,10 +70,19 @@ function parseCsv(raw: string | undefined): string[] | undefined {
 export interface SearchRoutesConfig {
   searchService: SearchService;
   skillRepo: SkillRepository;
+  /**
+   * NyxID catalog client + SA-token accessor. Used by
+   * `/skill-facets/system-services` to drop services NyxID has
+   * deactivated since the skill's `nyxidServiceId` was cached (#715).
+   * Optional so test wiring can omit the live filter; when omitted
+   * the facet returns the raw DB aggregation (pre-#715 behaviour).
+   */
+  nyxidServiceClient?: NyxidServiceClient;
+  getSaAccessToken?: () => Promise<string>;
 }
 
 export function createSearchRoutes(config: SearchRoutesConfig): Hono<{ Variables: AuthVariables }> {
-  const { searchService, skillRepo } = config;
+  const { searchService, skillRepo, nyxidServiceClient, getSaAccessToken } = config;
   const app = new Hono<{ Variables: AuthVariables }>();
 
   const optionalAuth = optionalAuthMiddleware();
@@ -72,10 +97,32 @@ export function createSearchRoutes(config: SearchRoutesConfig): Hono<{ Variables
   app.get(
     "/skill-search",
     optionalAuth,
-    validateQuery(searchQuerySchema, "INVALID_QUERY"),
+    // Rate limit (#439): keyword search hits Mongo (cheap), semantic
+    // hits an LLM (paid). One generous cap covers both — the hot path
+    // is the keyword scope, and the semantic gate inside `searchService`
+    // already requires auth so the per-user key matters. RFC 9239
+    // headers go out on every response (#460).
+    rateLimit({ windowMs: 60_000, max: 60, label: "skill-search" }),
+    validateQuery(searchQuerySchema, "invalid_query"),
     async (c) => {
       const parsed = getValidatedQuery<z.infer<typeof searchQuerySchema>>(c);
-      const { query, mode, page, pageSize, model, systemFilter } = parsed;
+      // q wins; legacy `query` is the fallback for un-upgraded clients (#586).
+      const query = parsed.q ?? parsed.query ?? "";
+      const { mode, model, systemFilter } = parsed;
+      // Cursor pagination (#457). `cursor` wins over `page` when both
+      // are sent. `limit` aliases `pageSize` per CONVENTIONS.md §4.3.
+      const pageSize = parsed.limit ?? parsed.pageSize;
+      let page = parsed.page;
+      if (parsed.cursor !== undefined) {
+        const decoded = decodeCursor(parsed.cursor);
+        if (!decoded) {
+          throw AppError.badRequest(
+            "invalid_cursor",
+            "The provided cursor is malformed or from a previous API version.",
+          );
+        }
+        page = decoded.page;
+      }
       const authCtx = c.get("auth");
       const isAnonymous = !authCtx;
 
@@ -120,7 +167,28 @@ export function createSearchRoutes(config: SearchRoutesConfig): Hono<{ Variables
         tagsAll: parseCsv(parsed.tags),
       });
 
-      return c.json({ data: response, error: null });
+      // Augment the legacy response shape with the cursor envelope
+      // per CONVENTIONS.md §4.3 (#457). `data.items` + `data.meta`
+      // are the canonical fields going forward; the existing
+      // `total/totalPages/page/pageSize/items` keys stay alongside
+      // for backward compat until they're sunset.
+      const itemsReturned = response.items.length;
+      const meta = {
+        limit: pageSize,
+        hasMore: itemsReturned >= pageSize && response.page * pageSize < response.total,
+        nextCursor: buildNextCursor({
+          currentPage: response.page,
+          pageSize,
+          itemsReturned,
+        }),
+      };
+      return c.json({
+        data: {
+          ...response,
+          meta,
+        },
+        error: null,
+      });
     },
   );
 
@@ -148,7 +216,7 @@ export function createSearchRoutes(config: SearchRoutesConfig): Hono<{ Variables
     const scopeRaw = (c.req.query("scope") || "public") as string;
     const allowed = ["public", "private", "mixed", "shared-with-me", "mine", "system"] as const;
     if (!(allowed as readonly string[]).includes(scopeRaw)) {
-      throw AppError.badRequest("INVALID_SCOPE", `Unknown scope '${scopeRaw}'`);
+      throw AppError.badRequest("invalid_scope", `Unknown scope '${scopeRaw}'`);
     }
     const scope = scopeRaw as (typeof allowed)[number];
     if ((scope === "mine" || scope === "shared-with-me") && !authCtx) {
@@ -177,7 +245,7 @@ export function createSearchRoutes(config: SearchRoutesConfig): Hono<{ Variables
     const allowed = ["public", "shared-with-me", "system", "mixed"] as const;
     if (!(allowed as readonly string[]).includes(scopeRaw)) {
       throw AppError.badRequest(
-        "INVALID_SCOPE",
+        "invalid_scope",
         `Unknown or unsupported scope '${scopeRaw}' for authors facet`,
       );
     }
@@ -203,6 +271,28 @@ export function createSearchRoutes(config: SearchRoutesConfig): Hono<{ Variables
    */
   app.get("/skill-facets/system-services", optionalAuth, async (c) => {
     const items = await skillRepo.aggregateSystemServices();
+
+    // Cross-check against NyxID's live active set (#715). The DB
+    // aggregation snapshots the service id/slug/label that was current
+    // when each skill was last bound, so a service NyxID has since
+    // deactivated still shows up here even though it's no longer
+    // bindable or usable. Drop those.
+    if (nyxidServiceClient && getSaAccessToken) {
+      try {
+        const saToken = await getSaAccessToken();
+        const activeIds = await nyxidServiceClient.listActiveServiceIdsAsPlatform(saToken);
+        if (activeIds) {
+          const filtered = items.filter((it) => activeIds.has(it.id));
+          return c.json({ data: { items: filtered }, error: null });
+        }
+      } catch (err) {
+        logger.warn(
+          { err: (err as Error).message },
+          "Failed to resolve active NyxID services; returning unfiltered facet",
+        );
+      }
+    }
+
     return c.json({ data: { items }, error: null });
   });
 
diff --git a/ornn-api/src/domains/skills/search/service.ts b/ornn-api/src/domains/skills/search/service.ts
index f4cdd1d9..389e6dc0 100644
--- a/ornn-api/src/domains/skills/search/service.ts
+++ b/ornn-api/src/domains/skills/search/service.ts
@@ -8,7 +8,26 @@
 import type { SkillRepository } from "../crud/repository";
 import type { NyxLlmClient } from "../../../clients/nyxid/llm";
 import type { SkillDocument, SkillSearchItem, SkillSearchResponse } from "../../../shared/types/index";
-import pino from "pino";
+import { createLogger } from "../../../shared/logger";
+import { z } from "zod";
+
+/**
+ * Shape the LLM re-ranker contract promises: an array of
+ * `{ id, score, reason? }` rows. Parsed with Zod (#444) instead of an
+ * `as` cast — `JSON.parse(...) as Array<...>` is a runtime no-op and
+ * a malformed model response previously slipped through the GUID
+ * filter and broke downstream score arithmetic with `NaN`.
+ *
+ * Rows with `score <= 0` are still dropped, but that filter is now
+ * applied after schema validation; the schema itself only enforces
+ * the shape.
+ */
+const rerankRowSchema = z.object({
+  id: z.string().min(1),
+  score: z.number().finite(),
+  reason: z.string().optional(),
+});
+const rerankResponseSchema = z.array(rerankRowSchema);
 
 /**
  * Per-item response enrichment context. The system-skill predicate is
@@ -23,7 +42,7 @@ export interface SearchEnrichmentContext {
 
 export type SystemFilter = "any" | "only" | "exclude";
 
-const logger = pino({ level: "info" }).child({ module: "skillSearchService" });
+const logger = createLogger("skillSearchService");
 
 const BATCH_SIZE = 50;
 
@@ -58,21 +77,14 @@ export class SearchService {
     currentUserId: string;
     /** Org user_ids the caller is admin or member of (viewer-role filtered out). */
     userOrgIds: string[];
-    model?: string;
-    /**
-     * Tri-state toggle for the System-skill filter. Pushed down to the
-     * DB match stage — `isSystemSkill: true` (cached on the skill doc
-     * at tie-time) is the source of truth.
-     */
-    systemFilter?: SystemFilter;
-    /** Registry filter-chip constraints. Applied at the DB match level. */
-    sharedWithOrgsAny?: string[];
-    sharedWithUsersAny?: string[];
-    createdByAny?: string[];
-    /** Restrict to skills tied to a specific NyxID service. */
-    nyxidServiceId?: string;
-    /** Skills must have ALL listed tags (AND match). */
-    tagsAll?: string[];
+    // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
+    model?: string | undefined;
+    systemFilter?: SystemFilter | undefined;
+    sharedWithOrgsAny?: string[] | undefined;
+    sharedWithUsersAny?: string[] | undefined;
+    createdByAny?: string[] | undefined;
+    nyxidServiceId?: string | undefined;
+    tagsAll?: string[] | undefined;
   }): Promise<SkillSearchResponse> {
     const { query, mode, scope, page, pageSize, currentUserId, userOrgIds } = params;
     const systemFilter = params.systemFilter ?? "any";
@@ -124,9 +136,39 @@ export class SearchService {
     const queryTimeMs = Date.now() - startTime;
     logger.info({ mode, scope, query: query.slice(0, 50), total, queryTimeMs }, "Search completed");
 
-    const items = skills.map((s) =>
+    const rawItems = skills.map((s) =>
       enrichItem(s, { callerUserId: currentUserId, callerOrgIds: userOrgIds }),
     );
+
+    // #720 — zero-trust filter for shared-with-me. applyScope at the
+    // DB layer already gates on the caller's effective orgs, but a
+    // stale cache, a partially-replicated write, or a future query
+    // regression could let a skill leak through that points at an
+    // org the caller is no longer in. Drop such items unconditionally
+    // — the user can't actually open them (skill detail correctly
+    // 404s, that's verified) so surfacing them in search results is
+    // pure misinformation. We log when this trips so cache/data drift
+    // is visible.
+    let items = rawItems;
+    if (scope === "shared-with-me") {
+      const orgSet = new Set(userOrgIds);
+      const filtered = rawItems.filter((item) => {
+        if (item.myAccessReason !== "shared-via-org") return true;
+        if (!item.sharedViaOrgId) return false;
+        return orgSet.has(item.sharedViaOrgId);
+      });
+      if (filtered.length !== rawItems.length) {
+        logger.warn(
+          {
+            userId: currentUserId,
+            droppedCount: rawItems.length - filtered.length,
+            orgsConsidered: userOrgIds.length,
+          },
+          "shared-with-me defensive filter dropped result(s) — applyScope and effective orgs disagree",
+        );
+      }
+      items = filtered;
+    }
     const totalPages = Math.ceil(total / pageSize);
 
     return {
@@ -154,8 +196,9 @@ export class SearchService {
     page: number;
     pageSize: number;
     systemFilter: SystemFilter;
-    nyxidServiceId?: string;
-    tagsAll?: string[];
+    // exactOptionalPropertyTypes (#657)
+    nyxidServiceId?: string | undefined;
+    tagsAll?: string[] | undefined;
   }): Promise<{ skills: SkillDocument[]; total: number }> {
     const { query, scope, currentUserId, userOrgIds, model, page, pageSize, systemFilter, nyxidServiceId, tagsAll } = params;
 
@@ -323,12 +366,20 @@ ${JSON.stringify(skillList, null, 2)}`;
         return [];
       }
 
-      const parsed = JSON.parse(jsonMatch[0]) as Array<{ id: string; score: number; reason?: string }>;
+      const parseResult = rerankResponseSchema.safeParse(JSON.parse(jsonMatch[0]));
+      if (!parseResult.success) {
+        logger.warn(
+          { batchSize: batch.length, issues: parseResult.error.issues.slice(0, 3) },
+          "Semantic search: LLM output failed schema validation",
+        );
+        return [];
+      }
+      const parsed = parseResult.data;
 
       // Validate and map
       const validGuids = new Set(batch.map((s) => s.guid));
       return parsed
-        .filter((r) => validGuids.has(r.id) && typeof r.score === "number" && r.score > 0)
+        .filter((r) => validGuids.has(r.id) && r.score > 0)
         .map((r) => ({
           guid: r.id,
           score: Math.min(10, Math.max(0, r.score)),
@@ -394,7 +445,6 @@ function enrichItem(
     guid: s.guid,
     name: s.name,
     description: s.description,
-    ownerId: s.ownerId,
     createdBy: s.createdBy,
     createdByEmail: s.createdByEmail,
     createdByDisplayName: s.createdByDisplayName,
diff --git a/ornn-api/src/domains/users/repository.test.ts b/ornn-api/src/domains/users/repository.test.ts
new file mode 100644
index 00000000..05400802
--- /dev/null
+++ b/ornn-api/src/domains/users/repository.test.ts
@@ -0,0 +1,272 @@
+/**
+ * UserDirectoryRepository unit tests (#454).
+ *
+ * `users` is the directory cache backing the permissions picker, the
+ * admin dashboard, and every userId → email/displayName lookup.
+ * NyxID is the source of truth for identity; this collection is
+ * write-on-every-authenticated-request and read on hot paths.
+ *
+ * Covers happy path + at least one edge per public method, per #454
+ * acceptance criteria.
+ *
+ * @module domains/users/repository.test
+ */
+
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+import { MongoClient, type Db } from "mongodb";
+import { MongoMemoryServer } from "mongodb-memory-server";
+import { UserDirectoryRepository } from "./repository";
+
+let mongo: MongoMemoryServer;
+let client: MongoClient;
+let db: Db;
+let repo: UserDirectoryRepository;
+
+beforeAll(async () => {
+  mongo = await MongoMemoryServer.create();
+  client = new MongoClient(mongo.getUri());
+  await client.connect();
+  db = client.db("users_test");
+  repo = new UserDirectoryRepository(db);
+  await repo.ensureIndexes();
+});
+
+afterAll(async () => {
+  await client.close();
+  await mongo.stop();
+});
+
+beforeEach(async () => {
+  await db.collection("users").deleteMany({});
+});
+
+describe("upsert", () => {
+  test("inserts a fresh user with firstSeenAt + activityCount=1", async () => {
+    await repo.upsert({ userId: "u1", email: "u1@x.test", displayName: "User 1", isAdmin: false });
+    const doc = await db.collection("users").findOne({ _id: "u1" as never });
+    expect(doc?.email).toBe("u1@x.test");
+    expect(doc?.displayName).toBe("User 1");
+    expect(doc?.isAdmin).toBe(false);
+    expect(doc?.activityCount).toBe(1);
+    expect(doc?.firstSeenAt).toBeInstanceOf(Date);
+    expect(doc?.lastSeenAt).toBeInstanceOf(Date);
+  });
+
+  test("subsequent upserts bump activityCount + lastSeenAt but preserve firstSeenAt", async () => {
+    await repo.upsert({ userId: "u1", email: "old@x.test", displayName: "Old Name", isAdmin: false });
+    const first = await db.collection("users").findOne({ _id: "u1" as never });
+    const firstSeenAt = first?.firstSeenAt;
+    // Briefly wait so lastSeenAt actually advances.
+    await new Promise((r) => setTimeout(r, 10));
+    await repo.upsert({ userId: "u1", email: "new@x.test", displayName: "New Name", isAdmin: true });
+    const second = await db.collection("users").findOne({ _id: "u1" as never });
+    expect(second?.email).toBe("new@x.test");
+    expect(second?.displayName).toBe("New Name");
+    expect(second?.isAdmin).toBe(true);
+    expect(second?.activityCount).toBe(2);
+    // firstSeenAt MUST NOT change on subsequent upserts.
+    expect(second?.firstSeenAt?.getTime()).toBe(firstSeenAt?.getTime());
+    // lastSeenAt SHOULD have advanced.
+    expect(second?.lastSeenAt?.getTime()).toBeGreaterThan(first?.lastSeenAt?.getTime() ?? 0);
+  });
+});
+
+describe("listAdminUserIds + listAdmins", () => {
+  test("returns only users with isAdmin=true", async () => {
+    await repo.upsert({ userId: "u1", email: "u1@x", displayName: "U1", isAdmin: false });
+    await repo.upsert({ userId: "a1", email: "a1@x", displayName: "A1", isAdmin: true });
+    await repo.upsert({ userId: "a2", email: "a2@x", displayName: "A2", isAdmin: true });
+    const ids = await repo.listAdminUserIds();
+    expect(ids.size).toBe(2);
+    expect(ids.has("a1")).toBe(true);
+    expect(ids.has("a2")).toBe(true);
+    expect(ids.has("u1")).toBe(false);
+
+    const admins = await repo.listAdmins();
+    expect(admins).toHaveLength(2);
+    expect(admins.every((d) => d.isAdmin)).toBe(true);
+  });
+
+  test("empty when there are no admins", async () => {
+    await repo.upsert({ userId: "u1", email: "u1@x", displayName: "U1", isAdmin: false });
+    expect((await repo.listAdminUserIds()).size).toBe(0);
+    expect(await repo.listAdmins()).toHaveLength(0);
+  });
+});
+
+describe("searchByEmailPrefix", () => {
+  beforeEach(async () => {
+    await repo.upsert({ userId: "u1", email: "alice@x.test", displayName: "Alice", isAdmin: false });
+    await repo.upsert({ userId: "u2", email: "alex@x.test", displayName: "Alex", isAdmin: false });
+    await repo.upsert({ userId: "u3", email: "bob@x.test", displayName: "Bob", isAdmin: false });
+  });
+
+  test("matches by email prefix, case-insensitive", async () => {
+    const rows = await repo.searchByEmailPrefix("al", 10);
+    expect(rows.map((r) => r.userId).sort()).toEqual(["u1", "u2"]);
+  });
+
+  test("empty prefix returns all non-empty emails up to limit, sorted by recency", async () => {
+    const rows = await repo.searchByEmailPrefix("", 10);
+    expect(rows).toHaveLength(3);
+  });
+
+  test("respects limit", async () => {
+    const rows = await repo.searchByEmailPrefix("", 2);
+    expect(rows).toHaveLength(2);
+  });
+
+  test("escapes regex metacharacters in prefix (no ReDoS, no false positives)", async () => {
+    // `.` is a regex metacharacter; if unescaped, "u." would match every entry.
+    const rows = await repo.searchByEmailPrefix("alex@x.test", 10);
+    // Should match exactly the literal email, not regex-match.
+    expect(rows.map((r) => r.userId)).toEqual(["u2"]);
+  });
+});
+
+describe("findByUserIds", () => {
+  test("resolves multiple userIds at once", async () => {
+    await repo.upsert({ userId: "u1", email: "u1@x", displayName: "U1", isAdmin: false });
+    await repo.upsert({ userId: "u2", email: "u2@x", displayName: "U2", isAdmin: false });
+    const rows = await repo.findByUserIds(["u1", "u2"]);
+    expect(rows).toHaveLength(2);
+    expect(rows.map((r) => r.userId).sort()).toEqual(["u1", "u2"]);
+  });
+
+  test("silently drops unknown ids", async () => {
+    await repo.upsert({ userId: "u1", email: "u1@x", displayName: "U1", isAdmin: false });
+    const rows = await repo.findByUserIds(["u1", "does-not-exist"]);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.userId).toBe("u1");
+  });
+
+  test("empty input returns empty output without hitting the DB", async () => {
+    const rows = await repo.findByUserIds([]);
+    expect(rows).toEqual([]);
+  });
+});
+
+describe("listUsers", () => {
+  beforeEach(async () => {
+    await repo.upsert({ userId: "n1", email: "n1@x.test", displayName: "Normal 1", isAdmin: false });
+    await repo.upsert({ userId: "n2", email: "n2@x.test", displayName: "Normal 2", isAdmin: false });
+    await repo.upsert({ userId: "a1", email: "a1@x.test", displayName: "Admin 1", isAdmin: true });
+  });
+
+  test("role=admin partition", async () => {
+    const result = await repo.listUsers({ role: "admin", page: 1, pageSize: 10 });
+    expect(result.items.map((u) => u.userId)).toEqual(["a1"]);
+  });
+
+  test("role=normal partition", async () => {
+    const result = await repo.listUsers({ role: "normal", page: 1, pageSize: 10 });
+    expect(result.items.map((u) => u.userId).sort()).toEqual(["n1", "n2"]);
+  });
+
+  test("q= filters by email prefix", async () => {
+    const result = await repo.listUsers({
+      role: "normal",
+      page: 1,
+      pageSize: 10,
+      q: "n1",
+    });
+    expect(result.items.map((u) => u.userId)).toEqual(["n1"]);
+  });
+
+  // #587 — placeholder said "email or display name" but only email
+  // matched. These pin the OR'd display-name path so a regression is
+  // caught loudly.
+  test("q= also matches display name (#587) — exact match", async () => {
+    const result = await repo.listUsers({
+      role: "normal",
+      page: 1,
+      pageSize: 10,
+      q: "Normal 1",
+    });
+    expect(result.items.map((u) => u.userId)).toEqual(["n1"]);
+  });
+
+  test("q= matches display-name substring, not just prefix (#587)", async () => {
+    // Reproducer from the issue: `Proxy` should match `Ornn Local Proxy`.
+    await repo.upsert({
+      userId: "p1",
+      email: "proxy@x.test",
+      displayName: "Ornn Local Proxy",
+      isAdmin: false,
+    });
+    const result = await repo.listUsers({
+      role: "normal",
+      page: 1,
+      pageSize: 10,
+      q: "Proxy",
+    });
+    expect(result.items.map((u) => u.userId)).toContain("p1");
+  });
+
+  test("q= display-name match is case-insensitive (#587)", async () => {
+    const result = await repo.listUsers({
+      role: "admin",
+      page: 1,
+      pageSize: 10,
+      q: "admin 1",
+    });
+    expect(result.items.map((u) => u.userId)).toEqual(["a1"]);
+  });
+
+  test("q= escapes regex metacharacters in display-name match (#587)", async () => {
+    // `.` is a regex metachar; if unescaped, "1.x" would match every
+    // display name. Pinning so the escape stays in place.
+    await repo.upsert({
+      userId: "z1",
+      email: "z1@x.test",
+      displayName: "Z (1.x)",
+      isAdmin: false,
+    });
+    const matches = await repo.listUsers({
+      role: "normal",
+      page: 1,
+      pageSize: 10,
+      q: "(1.x)",
+    });
+    expect(matches.items.map((u) => u.userId)).toEqual(["z1"]);
+    const nonMatches = await repo.listUsers({
+      role: "normal",
+      page: 1,
+      pageSize: 10,
+      q: "(1*x)",
+    });
+    expect(nonMatches.items.map((u) => u.userId)).not.toContain("z1");
+  });
+
+  test("pagination respects pageSize + page", async () => {
+    const first = await repo.listUsers({ role: "normal", page: 1, pageSize: 1 });
+    const second = await repo.listUsers({ role: "normal", page: 2, pageSize: 1 });
+    expect(first.items).toHaveLength(1);
+    expect(second.items).toHaveLength(1);
+    expect(first.items[0]?.userId).not.toBe(second.items[0]?.userId);
+  });
+});
+
+describe("countByRole", () => {
+  test("returns admin / normal / total counts", async () => {
+    await repo.upsert({ userId: "n1", email: "n1@x", displayName: "N1", isAdmin: false });
+    await repo.upsert({ userId: "n2", email: "n2@x", displayName: "N2", isAdmin: false });
+    await repo.upsert({ userId: "a1", email: "a1@x", displayName: "A1", isAdmin: true });
+    const counts = await repo.countByRole();
+    expect(counts.normal).toBe(2);
+    expect(counts.admin).toBe(1);
+    expect(counts.total).toBe(3);
+  });
+
+  test("zeros when empty", async () => {
+    const counts = await repo.countByRole();
+    expect(counts).toEqual({ admin: 0, normal: 0, total: 0 });
+  });
+});
diff --git a/ornn-api/src/domains/users/repository.ts b/ornn-api/src/domains/users/repository.ts
index 43bd6668..b31e0e44 100644
--- a/ornn-api/src/domains/users/repository.ts
+++ b/ornn-api/src/domains/users/repository.ts
@@ -30,9 +30,8 @@
  */
 
 import type { Collection, Db } from "mongodb";
-import pino from "pino";
-
-const logger = pino({ level: "info" }).child({ module: "userDirectoryRepository" });
+import { createLogger } from "../../shared/logger";
+const logger = createLogger("userDirectoryRepository");
 
 const COLLECTION = "users";
 
@@ -245,14 +244,8 @@ export class UserDirectoryRepository {
 
     const filter: Record<string, unknown> = {
       isAdmin: params.role === "admin",
+      ...buildUserSearchFilter(params.q),
     };
-    const q = params.q?.trim();
-    if (q) {
-      filter.email = {
-        $regex: `^${q.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
-        $options: "i",
-      };
-    }
 
     const total = await this.collection.countDocuments(filter);
     const sortSpec: Record<string, 1 | -1> = {
@@ -289,14 +282,8 @@ export class UserDirectoryRepository {
   ): Promise<UserDirectoryDoc[]> {
     const filter: Record<string, unknown> = {
       isAdmin: role === "admin",
+      ...buildUserSearchFilter(q),
     };
-    const trimmed = q?.trim();
-    if (trimmed) {
-      filter.email = {
-        $regex: `^${trimmed.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
-        $options: "i",
-      };
-    }
     return this.collection.find(filter).limit(hardLimit).toArray();
   }
 
@@ -313,6 +300,38 @@ export class UserDirectoryRepository {
   }
 }
 
+/**
+ * Build a Mongo filter fragment for the admin user-list search box.
+ *
+ * #587 — the box's placeholder says "email or display name" but the
+ * server only matched on email-prefix. Display names + substring
+ * keywords were silently ignored. Fix is additive:
+ *
+ *   - **Email** — keep the anchored prefix regex (it's the historical
+ *     behaviour, indexable, and matches the "type the local part" UX
+ *     admins already rely on).
+ *   - **DisplayName** — add a case-insensitive *substring* match.
+ *     Display names don't have a meaningful prefix (`Ornn Local Proxy`
+ *     should hit on `Proxy`, not just `Ornn`).
+ *
+ * `$or` lets either match. Empty / whitespace queries return an empty
+ * fragment so the role filter alone drives the query.
+ *
+ * Regex meta-chars are escaped so a literal `.` / `*` in a display name
+ * or local-part doesn't blow up the query (or DoS the matcher).
+ */
+function buildUserSearchFilter(q: string | undefined): Record<string, unknown> {
+  const trimmed = q?.trim();
+  if (!trimmed) return {};
+  const escaped = trimmed.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return {
+    $or: [
+      { email: { $regex: `^${escaped}`, $options: "i" } },
+      { displayName: { $regex: escaped, $options: "i" } },
+    ],
+  };
+}
+
 function toEntry(doc: UserDirectoryDoc): UserDirectoryEntry {
   return {
     userId: doc._id,
diff --git a/ornn-api/src/domains/users/routes.ts b/ornn-api/src/domains/users/routes.ts
index 2f1f7ad4..2b463caf 100644
--- a/ornn-api/src/domains/users/routes.ts
+++ b/ornn-api/src/domains/users/routes.ts
@@ -45,7 +45,7 @@ export function createUserRoutes(
   app.get(
     "/users/search",
     auth,
-    validateQuery(searchQuerySchema, "INVALID_QUERY"),
+    validateQuery(searchQuerySchema, "invalid_query"),
     async (c) => {
       const parsed = getValidatedQuery<z.infer<typeof searchQuerySchema>>(c);
       const results = await userDirectoryRepo.searchByEmailPrefix(
diff --git a/ornn-api/src/infra/agentseal/index.test.ts b/ornn-api/src/infra/agentseal/index.test.ts
index 0e78ea1b..f00e0694 100644
--- a/ornn-api/src/infra/agentseal/index.test.ts
+++ b/ornn-api/src/infra/agentseal/index.test.ts
@@ -7,8 +7,18 @@
  *   the test machine.
  */
 
-import { describe, expect, test } from "bun:test";
-import { AgentSealScanner, parseSkillScanOutput } from "./index";
+import { beforeAll, describe, expect, test } from "bun:test";
+import { AgentSealScanner, assertAbsoluteExistingFile, parseSkillScanOutput } from "./index";
+
+// #442 added boot-time path validation that requires `script` to be
+// an absolute path to an existing file. The subprocess tests below
+// pass a shell shim as `python` (it ignores the script arg), so we
+// need a real-on-disk dummy script file the validator can stat.
+const DUMMY_SCRIPT = "/tmp/agentseal-test-dummy.py";
+
+beforeAll(async () => {
+  await Bun.write(DUMMY_SCRIPT, "# dummy — never actually executed; shim shells ignore script arg\n");
+});
 
 describe("parseSkillScanOutput", () => {
   test("parses canonical wrapper output with score + findings", () => {
@@ -89,7 +99,7 @@ describe("AgentSealScanner.scan", () => {
 
     const scanner = new AgentSealScanner({
       python: script,
-      script: "/tmp/agentseal-shim-success.dummy.py",
+      script: DUMMY_SCRIPT,
       timeoutMs: 5000,
       enabled: true,
     });
@@ -120,7 +130,7 @@ describe("AgentSealScanner.scan", () => {
 
     const scanner = new AgentSealScanner({
       python: script,
-      script: "/tmp/dummy.py",
+      script: DUMMY_SCRIPT,
       timeoutMs: 5000,
       enabled: true,
     });
@@ -146,7 +156,7 @@ describe("AgentSealScanner.scan", () => {
 
     const scanner = new AgentSealScanner({
       python: script,
-      script: "/tmp/dummy.py",
+      script: DUMMY_SCRIPT,
       timeoutMs: 5000,
       enabled: true,
     });
@@ -168,7 +178,7 @@ describe("AgentSealScanner.scan", () => {
 
     const scanner = new AgentSealScanner({
       python: script,
-      script: "/tmp/dummy.py",
+      script: DUMMY_SCRIPT,
       timeoutMs: 5000,
       enabled: true,
     });
@@ -195,7 +205,7 @@ describe("AgentSealScanner.scan", () => {
 
     const scanner = new AgentSealScanner({
       python: script,
-      script: "/tmp/dummy.py",
+      script: DUMMY_SCRIPT,
       timeoutMs: 200,
       enabled: true,
     });
@@ -207,18 +217,92 @@ describe("AgentSealScanner.scan", () => {
     expect(result).toBeNull();
   }, 10_000);
 
-  test("returns null when interpreter does not exist", async () => {
-    const scanner = new AgentSealScanner({
-      python: "/nonexistent/path/python-fake-binary",
-      script: "/tmp/dummy.py",
-      timeoutMs: 1000,
-      enabled: true,
-    });
-    const result = await scanner.scan({
-      skillGuid: "g6",
-      version: "1.0",
-      zipBuffer: new Uint8Array([1]),
-    });
-    expect(result).toBeNull();
+  // The "interpreter does not exist" runtime path (the test previously
+  // here) is now covered earlier — at construct time — by the path
+  // validator added in #442. The constructor throws before `scan()`
+  // can be called. See the `assertAbsoluteExistingFile` block below.
+});
+
+describe("AgentSealScanner — boot-time path validation (#442)", () => {
+  test("throws when python path is relative", () => {
+    expect(
+      () =>
+        new AgentSealScanner({
+          python: "bin/python", // relative — would resolve against $PATH / cwd
+          script: DUMMY_SCRIPT,
+          timeoutMs: 1000,
+          enabled: true,
+        }),
+    ).toThrow(/must be an absolute path/);
+  });
+
+  test("throws when python path does not exist", () => {
+    expect(
+      () =>
+        new AgentSealScanner({
+          python: "/nonexistent/path/to/python",
+          script: DUMMY_SCRIPT,
+          timeoutMs: 1000,
+          enabled: true,
+        }),
+    ).toThrow(/does not exist/);
+  });
+
+  test("throws when script path does not exist", () => {
+    expect(
+      () =>
+        new AgentSealScanner({
+          python: "/bin/sh",
+          script: "/nonexistent/script.py",
+          timeoutMs: 1000,
+          enabled: true,
+        }),
+    ).toThrow(/does not exist/);
+  });
+
+  test("throws when script path points at a directory, not a file", () => {
+    expect(
+      () =>
+        new AgentSealScanner({
+          python: "/bin/sh",
+          script: "/tmp",
+          timeoutMs: 1000,
+          enabled: true,
+        }),
+    ).toThrow(/not a regular file/);
+  });
+
+  test("disabled scanner skips validation (so dev/test envs don't need real paths)", () => {
+    expect(
+      () =>
+        new AgentSealScanner({
+          python: "bin/python", // would normally fail validation
+          script: "/nonexistent",
+          timeoutMs: 1000,
+          enabled: false,
+        }),
+    ).not.toThrow();
+  });
+
+  test("happy path: absolute existing files, scanner constructs cleanly", () => {
+    expect(
+      () =>
+        new AgentSealScanner({
+          python: "/bin/sh",
+          script: DUMMY_SCRIPT,
+          timeoutMs: 1000,
+          enabled: true,
+        }),
+    ).not.toThrow();
+  });
+});
+
+describe("assertAbsoluteExistingFile (#442 — direct unit test)", () => {
+  test("empty string rejected", () => {
+    expect(() => assertAbsoluteExistingFile("x", "")).toThrow(/required/);
+  });
+
+  test("absolute existing file accepted", () => {
+    expect(() => assertAbsoluteExistingFile("x", DUMMY_SCRIPT)).not.toThrow();
   });
 });
diff --git a/ornn-api/src/infra/agentseal/index.ts b/ornn-api/src/infra/agentseal/index.ts
index d4de4eaa..34cb83cc 100644
--- a/ornn-api/src/infra/agentseal/index.ts
+++ b/ornn-api/src/infra/agentseal/index.ts
@@ -29,12 +29,12 @@
  */
 
 import { spawn } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
-import pino, { type Logger } from "pino";
-
-const moduleLogger = pino({ level: "info" }).child({ module: "agentseal" });
+import { isAbsolute, join } from "node:path";
+import { createLogger, type Logger } from "../../shared/logger";
+const moduleLogger = createLogger("agentseal");
 
 export interface ScanInput {
   /** Skill identity for log correlation. */
@@ -93,6 +93,20 @@ export class AgentSealScanner implements IAgentSealScanner {
     this.timeoutMs = cfg.timeoutMs;
     this.enabled = cfg.enabled;
     this.logger = (cfg.logger ?? moduleLogger).child({ module: "agentseal" });
+
+    // Boot-time path validation (#442). When the scanner is enabled
+    // we'll be `spawn()`ing the python interpreter — accepting a
+    // relative or non-existent path here means we'd either resolve it
+    // against `$PATH` (a subtle lateral-movement vector if config
+    // provenance ever weakens) or fail much later inside a publish
+    // call. Fail fast at construction instead.
+    //
+    // Disabled scanners skip validation so dev/test environments
+    // without agentseal installed don't have to provide fake paths.
+    if (this.enabled) {
+      assertAbsoluteExistingFile("python", this.python);
+      assertAbsoluteExistingFile("script", this.script);
+    }
   }
 
   async scan(input: ScanInput): Promise<ScanResult | null> {
@@ -196,14 +210,19 @@ export class AgentSealScanner implements IAgentSealScanner {
       let settled = false;
 
       // Hard timeout — SIGTERM, then SIGKILL after a short grace.
+      // After signaling, `child.unref()` releases the event-loop hold
+      // so a mid-flight scan can't keep the API process alive past
+      // SIGTERM during shutdown (#442).
       const killTimer = setTimeout(() => {
         if (settled) return;
         settled = true;
         try {
           child.kill("SIGTERM");
+          child.unref();
           setTimeout(() => {
             try {
               child.kill("SIGKILL");
+              child.unref();
             } catch {
               /* already dead */
             }
@@ -251,6 +270,35 @@ export class AgentSealScanner implements IAgentSealScanner {
   }
 }
 
+/**
+ * Boot-time path guard (#442). Throws with a precise message when the
+ * incoming `python` / `script` config isn't an absolute path to an
+ * existing regular file. Called only when AgentSeal is enabled — a
+ * disabled scanner never spawns anything, so loose paths don't matter.
+ *
+ * Exported for direct unit testing.
+ */
+export function assertAbsoluteExistingFile(label: string, value: string): void {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`AgentSeal '${label}' is required when enabled (got empty string)`);
+  }
+  if (!isAbsolute(value)) {
+    throw new Error(
+      `AgentSeal '${label}' must be an absolute path, got '${value}'. ` +
+        `Relative paths would resolve against $PATH / cwd — refuse to spawn.`,
+    );
+  }
+  if (!existsSync(value)) {
+    throw new Error(`AgentSeal '${label}' does not exist at '${value}'`);
+  }
+  // Symlinks resolve through statSync; a directory or special file at
+  // the configured path is also a refusal — we want a regular file.
+  const st = statSync(value);
+  if (!st.isFile()) {
+    throw new Error(`AgentSeal '${label}' at '${value}' is not a regular file`);
+  }
+}
+
 interface ParsedScan {
   score: number;
   findings: Array<Record<string, unknown>>;
@@ -274,6 +322,10 @@ export function parseSkillScanOutput(raw: string): ParsedScan | null {
   try {
     json = JSON.parse(stripped);
   } catch {
+    // Intentional silent (#579): a malformed scan output already gets
+    // logged at the call site (`scan()` calls `parseSkillScanOutput`
+    // and logs a warn with `rawSnippet` when this returns null). No
+    // value in logging twice.
     return null;
   }
   if (!json || typeof json !== "object" || Array.isArray(json)) return null;
@@ -304,5 +356,12 @@ export function parseSkillScanOutput(raw: string): ParsedScan | null {
       ? Math.max(0, Math.round(obj.scannedFiles))
       : 0;
 
-  return { score, findings, agentsealVersion, scannedAt, scannedFiles };
+  // exactOptionalPropertyTypes (#657)
+  return {
+    score,
+    findings,
+    agentsealVersion,
+    ...(scannedAt !== undefined ? { scannedAt } : {}),
+    scannedFiles,
+  };
 }
diff --git a/ornn-api/src/infra/analytics/index.test.ts b/ornn-api/src/infra/analytics/index.test.ts
index f995df73..e9252c71 100644
--- a/ornn-api/src/infra/analytics/index.test.ts
+++ b/ornn-api/src/infra/analytics/index.test.ts
@@ -17,7 +17,8 @@ class FakeTracker implements AnalyticsTracker {
     event: string,
     properties?: Readonly<Record<string, unknown>>,
   ): void {
-    this.calls.push({ userId, event, properties });
+    // exactOptionalPropertyTypes (#657)
+    this.calls.push({ userId, event, ...(properties !== undefined ? { properties } : {}) });
   }
   async shutdown(): Promise<void> {
     /* no-op */
@@ -85,7 +86,7 @@ describe("AnalyticsEmitter", () => {
     emitter.trackApiError({
       userId: "u-3",
       statusCode: 500,
-      errorCode: "INTERNAL_ERROR",
+      errorCode: "internal_error",
       method: "POST",
       path: "/api/v1/skills",
       requestId: "rid-1",
@@ -95,7 +96,7 @@ describe("AnalyticsEmitter", () => {
     expect(tracker.calls[0]!.event).toBe("api.error");
     expect(tracker.calls[0]!.properties).toMatchObject({
       statusCode: 500,
-      errorCode: "INTERNAL_ERROR",
+      errorCode: "internal_error",
       method: "POST",
       path: "/api/v1/skills",
       requestId: "rid-1",
@@ -110,7 +111,7 @@ describe("AnalyticsEmitter", () => {
     emitter.trackApiError({
       userId: "u-3",
       statusCode: 500,
-      errorCode: "INTERNAL_ERROR",
+      errorCode: "internal_error",
       method: "POST",
       path: "/api/v1/skills",
     });
@@ -126,7 +127,7 @@ describe("AnalyticsEmitter", () => {
     emitter.trackApiError({
       userId: "u-3",
       statusCode: 500,
-      errorCode: "INTERNAL_ERROR",
+      errorCode: "internal_error",
       method: "POST",
       path: "/api/v1/skills",
     });
@@ -142,7 +143,7 @@ describe("AnalyticsEmitter", () => {
     emitter.trackApiError({
       userId: null,
       statusCode: 503,
-      errorCode: "UPSTREAM_DOWN",
+      errorCode: "upstream_down",
       method: "GET",
       path: "/livez",
     });
diff --git a/ornn-api/src/infra/analytics/index.ts b/ornn-api/src/infra/analytics/index.ts
index 5fee1350..c5cf6c2d 100644
--- a/ornn-api/src/infra/analytics/index.ts
+++ b/ornn-api/src/infra/analytics/index.ts
@@ -268,7 +268,8 @@ export function createAnalyticsEmitter(
   return new AnalyticsEmitter({
     tracker,
     errorSampleRate: config.posthogErrorSampleRate,
-    logger,
+    // exactOptionalPropertyTypes (#657)
+    ...(logger !== undefined ? { logger } : {}),
   });
 }
 
diff --git a/ornn-api/src/infra/analytics/posthog.ts b/ornn-api/src/infra/analytics/posthog.ts
index 7e343d46..52062bc5 100644
--- a/ornn-api/src/infra/analytics/posthog.ts
+++ b/ornn-api/src/infra/analytics/posthog.ts
@@ -22,9 +22,8 @@
  */
 
 import { PostHog } from "posthog-node";
-import pino, { type Logger } from "pino";
-
-const moduleLogger = pino({ level: "info" }).child({ module: "posthogTracker" });
+import { createLogger, type Logger } from "../../shared/logger";
+const moduleLogger = createLogger("posthogTracker");
 
 export interface AnalyticsTracker {
   /**
@@ -122,7 +121,10 @@ export class PosthogTracker implements AnalyticsTracker {
       this.client.capture({
         distinctId,
         event,
-        properties: properties as Record<string, unknown> | undefined,
+        // exactOptionalPropertyTypes (#657)
+        ...(properties !== undefined
+          ? { properties: properties as Record<string, unknown> }
+          : {}),
       });
       this.logger.info({ event, distinctId: redactDistinctId(distinctId), propKeys }, "PostHog event captured");
       this.logger.debug({ event, distinctId: redactDistinctId(distinctId), properties }, "PostHog event body");
diff --git a/ornn-api/src/infra/config.ts b/ornn-api/src/infra/config.ts
index cd3075b4..6d2415df 100644
--- a/ornn-api/src/infra/config.ts
+++ b/ornn-api/src/infra/config.ts
@@ -59,6 +59,13 @@ export interface SkillConfig {
   // timeout move to settings (skillAudit section).
   readonly agentsealPython: string;
   readonly agentsealScript: string;
+  /**
+   * Boot-time master switch (#442). When false the scanner skips path
+   * validation entirely and `scan()` short-circuits to null. Lets
+   * integration tests and any env without agentseal installed boot
+   * without satisfying the absolute-path-must-exist guard.
+   */
+  readonly agentsealEnabled: boolean;
 
   /**
    * Origin used in mirror READMEs to link back to the canonical Ornn
@@ -124,6 +131,10 @@ const envSchema = z.object({
   // ---- AgentSeal (skill trust scanner, #253) — binary paths only ----
   AGENTSEAL_PYTHON: z.string().min(1).default("/opt/agentseal/bin/python"),
   AGENTSEAL_SCRIPT: z.string().min(1).default("/opt/agentseal/scan_skill.py"),
+  // String-typed so `AGENTSEAL_ENABLED=false` in a `.env` file works
+  // without booleanish-string parsing gymnastics. `"false"` disables;
+  // any other value (default `"true"`) enables. Per #442.
+  AGENTSEAL_ENABLED: z.string().default("true"),
 
   /**
    * Public origin agents and humans use to reach Ornn (no trailing
@@ -193,6 +204,7 @@ export function loadConfig(): SkillConfig {
 
     agentsealPython: env.AGENTSEAL_PYTHON,
     agentsealScript: env.AGENTSEAL_SCRIPT,
+    agentsealEnabled: env.AGENTSEAL_ENABLED !== "false",
 
     ornnPublicOrigin: env.ORNN_PUBLIC_ORIGIN.replace(/\/+$/, ""),
   };
diff --git a/ornn-api/src/infra/crypto.test.ts b/ornn-api/src/infra/crypto.test.ts
index 5ba9d2f5..b9e0a016 100644
--- a/ornn-api/src/infra/crypto.test.ts
+++ b/ornn-api/src/infra/crypto.test.ts
@@ -35,11 +35,14 @@ describe("infra/crypto", () => {
 
   it("UT-CRYPTO-003: tampered ciphertext rejected by auth tag", () => {
     const ct = encryptSecret("plaintext", KEY);
-    // Flip a single hex char in the ciphertext segment.
+    // Flip a single hex char in the ciphertext segment. `encryptSecret`
+    // emits a 4-part `v1:iv:tag:ct` payload, so index 3 is guaranteed
+    // present. `!` is safe under noUncheckedIndexedAccess (#450).
     const parts = ct.split(":");
-    parts[3] = parts[3].startsWith("a")
-      ? `b${parts[3].slice(1)}`
-      : `a${parts[3].slice(1)}`;
+    const ctSegment = parts[3]!;
+    parts[3] = ctSegment.startsWith("a")
+      ? `b${ctSegment.slice(1)}`
+      : `a${ctSegment.slice(1)}`;
     const tampered = parts.join(":");
     expect(() => decryptSecret(tampered, KEY)).toThrow();
   });
diff --git a/ornn-api/src/infra/crypto.ts b/ornn-api/src/infra/crypto.ts
index 1f015d57..94c28960 100644
--- a/ornn-api/src/infra/crypto.ts
+++ b/ornn-api/src/infra/crypto.ts
@@ -80,7 +80,12 @@ export function decryptSecret(value: string, passphrase: string): string {
   if (parts.length !== 4) {
     throw new Error(`decryptSecret: malformed v1 payload (got ${parts.length} parts)`);
   }
-  const [, ivHex, tagHex, ctHex] = parts;
+  // Length-checked above (`parts.length !== 4` returns early) — every
+  // slot is guaranteed defined. `!` is safe under noUncheckedIndexedAccess
+  // (#450).
+  const ivHex = parts[1]!;
+  const tagHex = parts[2]!;
+  const ctHex = parts[3]!;
   const key = deriveKey(passphrase);
   const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(ivHex, "hex"));
   decipher.setAuthTag(Buffer.from(tagHex, "hex"));
diff --git a/ornn-api/src/infra/db/mongodb.ts b/ornn-api/src/infra/db/mongodb.ts
index 615bb395..81e476e2 100644
--- a/ornn-api/src/infra/db/mongodb.ts
+++ b/ornn-api/src/infra/db/mongodb.ts
@@ -4,9 +4,8 @@
  */
 
 import { MongoClient, type Db } from "mongodb";
-import pino from "pino";
-
-const logger = pino({ level: "info" }).child({ module: "mongodb" });
+import { createLogger } from "../../shared/logger";
+const logger = createLogger("mongodb");
 
 export interface MongoConnection {
   client: MongoClient;
diff --git a/ornn-api/src/infra/url.ts b/ornn-api/src/infra/url.ts
index 1966147a..c4f574d0 100644
--- a/ornn-api/src/infra/url.ts
+++ b/ornn-api/src/infra/url.ts
@@ -79,7 +79,10 @@ interface Cidr {
 }
 
 function parseCidr(spec: string): Cidr | null {
-  const [hostPart, bitsPart] = spec.split("/");
+  // `split("/")` always yields at least one element; if `spec` has no
+  // `/`, hostPart is the whole string and bitsPart is undefined. `!`
+  // is safe under noUncheckedIndexedAccess (#450).
+  const [hostPart, bitsPart] = spec.split("/") as [string, string | undefined];
   const base = parseIpv4(hostPart);
   if (base === null) return null;
   const maskBits = bitsPart ? Number(bitsPart) : 32;
@@ -122,13 +125,18 @@ export function isPrivateHost(host: string): boolean {
     if (h.startsWith("fe80:") || h.startsWith("fe80::")) return true;
     // `fc00::/7` covers `fc00::` through `fdff::`.
     if (h.startsWith("fc") || h.startsWith("fd")) {
-      const first = h.split(":")[0];
+      // split(":")[0] is the substring before the first ":" (always
+      // present when split runs). `!` is safe under
+      // noUncheckedIndexedAccess (#450).
+      const first = h.split(":")[0]!;
       if (/^f[cd][0-9a-f]{0,2}$/.test(first)) return true;
     }
     // `::ffff:<v4>` mapped form.
     const mapped = h.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
     if (mapped) {
-      const ip = parseIpv4(mapped[1]);
+      // The regex has one capture group; if it matched, group 1 is
+      // present. `!` is safe under noUncheckedIndexedAccess (#450).
+      const ip = parseIpv4(mapped[1]!);
       if (ip === null) return true; // malformed — reject conservatively
       return PRIVATE_CIDRS.some((c) => ipv4InCidr(ip, c));
     }
diff --git a/ornn-api/src/middleware/apiRequestTracking.ts b/ornn-api/src/middleware/apiRequestTracking.ts
index 40cf7892..21db89b2 100644
--- a/ornn-api/src/middleware/apiRequestTracking.ts
+++ b/ornn-api/src/middleware/apiRequestTracking.ts
@@ -29,9 +29,12 @@
  */
 
 import type { Context, Next, MiddlewareHandler } from "hono";
+import { createLogger } from "../shared/logger";
 import type { AnalyticsEmitter, CallerType } from "../infra/analytics";
 import { getRequestId } from "./requestId";
 
+const logger = createLogger("apiRequestTracking");
+
 export interface ApiRequestTrackingConfig {
   emitter: AnalyticsEmitter;
 }
@@ -60,25 +63,34 @@ export function apiRequestTrackingMiddleware(
         const sourceIp = redactIp(extractSourceIp(c));
         const requestId = getRequestId(c) ?? null;
 
+        // exactOptionalPropertyTypes (#657): conditional spread on
+        // every optional field so we never pass an explicit `undefined`
+        // to a contract that wants `key?: T`.
+        const routePattern = extractRoutePattern(c);
+        const userAgent = capUserAgent(c.req.header("user-agent"));
+        const queryParamKeys = extractQueryParamKeys(c);
+        const requestBytes = parseContentLength(c.req.header("content-length"));
+        const responseBytes = parseContentLength(c.res.headers.get("content-length"));
         config.emitter.trackApiRequest({
           userId,
           callerType,
           method: c.req.method,
           path: c.req.path,
-          routePattern: extractRoutePattern(c),
+          ...(routePattern !== undefined ? { routePattern } : {}),
           status,
           durationMs,
           sourceIp,
           requestId,
-          userAgent: capUserAgent(c.req.header("user-agent")),
-          queryParamKeys: extractQueryParamKeys(c),
-          requestBytes: parseContentLength(c.req.header("content-length")),
-          responseBytes: parseContentLength(
-            c.res.headers.get("content-length"),
-          ),
+          ...(userAgent !== undefined ? { userAgent } : {}),
+          ...(queryParamKeys !== undefined ? { queryParamKeys } : {}),
+          ...(requestBytes !== undefined ? { requestBytes } : {}),
+          ...(responseBytes !== undefined ? { responseBytes } : {}),
         });
-      } catch {
-        /* never fail the request because tracking blew up */
+      } catch (err) {
+        // Never fail the request because tracking blew up (#579) — but
+        // do log so a misconfigured emitter doesn't silently drop every
+        // analytics event for hours.
+        logger.debug({ err }, "api.request tracking emit failed");
       }
     }
   };
@@ -183,7 +195,11 @@ function extractQueryParamKeys(c: Context): string | undefined {
   let queries: Record<string, string>;
   try {
     queries = c.req.query() as Record<string, string>;
-  } catch {
+  } catch (err) {
+    // c.req.query() throws on malformed query strings; analytics
+    // shouldn't fail the request, but record it so a regression in
+    // hono's parser doesn't silently drop every event.
+    logger.debug({ err }, "query-string parse failed in extractQueryParamKeys");
     return undefined;
   }
   const keys = Object.keys(queries);
diff --git a/ornn-api/src/middleware/idempotency.test.ts b/ornn-api/src/middleware/idempotency.test.ts
new file mode 100644
index 00000000..ed3ed45a
--- /dev/null
+++ b/ornn-api/src/middleware/idempotency.test.ts
@@ -0,0 +1,236 @@
+/**
+ * Tests for the Idempotency-Key middleware (#459).
+ *
+ * Uses an in-memory Mongo via `mongodb-memory-server` so the TTL index
+ * + duplicate-key behaviour matches production. The handler being
+ * wrapped is a counter that increments on every real execution — the
+ * counter is the canary that tells us whether replay actually
+ * short-circuited the handler (counter stays at 1) or re-ran it
+ * (counter goes to 2+).
+ *
+ * @module middleware/idempotency.test
+ */
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import { MongoMemoryServer } from "mongodb-memory-server";
+import { MongoClient, type Db } from "mongodb";
+import {
+  IdempotencyKeyRepository,
+  idempotencyMiddleware,
+  MAX_IDEMPOTENCY_KEY_LENGTH,
+} from "./idempotency";
+
+let mongo: MongoMemoryServer;
+let client: MongoClient;
+let db: Db;
+let repo: IdempotencyKeyRepository;
+
+beforeAll(async () => {
+  mongo = await MongoMemoryServer.create();
+  client = new MongoClient(mongo.getUri());
+  await client.connect();
+  db = client.db("idempotency_test");
+  repo = new IdempotencyKeyRepository(db);
+  await repo.ensureIndexes();
+});
+
+afterAll(async () => {
+  await client.close();
+  await mongo.stop();
+});
+
+beforeEach(async () => {
+  await db.collection("idempotency_keys").deleteMany({});
+});
+
+function makeApp(handler: (counter: { value: number }) => Promise<Response> | Response) {
+  const counter = { value: 0 };
+  const app = new Hono();
+  // Stub auth so the middleware can scope keys per user.
+  app.use("*", async (c, next) => {
+    const userHeader = c.req.header("x-test-user") ?? "u1";
+    c.set("auth" as never, { userId: userHeader } as never);
+    await next();
+  });
+  app.use("*", idempotencyMiddleware({ repo }));
+  app.all("/api/v1/skills", async () => {
+    counter.value += 1;
+    return handler(counter);
+  });
+  return { app, counter };
+}
+
+describe("idempotency middleware (#459)", () => {
+  test("GET requests bypass the cache entirely (no key required, no doc written)", async () => {
+    const { app, counter } = makeApp(() => new Response("ok", { status: 200 }));
+    await app.request("/api/v1/skills", { method: "GET" });
+    await app.request("/api/v1/skills", { method: "GET" });
+    expect(counter.value).toBe(2);
+    expect(await db.collection("idempotency_keys").countDocuments()).toBe(0);
+  });
+
+  test("POST without an Idempotency-Key header is uncached", async () => {
+    const { app, counter } = makeApp(() => new Response("ok", { status: 200 }));
+    await app.request("/api/v1/skills", { method: "POST" });
+    await app.request("/api/v1/skills", { method: "POST" });
+    expect(counter.value).toBe(2);
+    expect(await db.collection("idempotency_keys").countDocuments()).toBe(0);
+  });
+
+  test("identical POST + key returns the cached body and skips the handler (the core feature)", async () => {
+    const { app, counter } = makeApp((c) =>
+      new Response(JSON.stringify({ id: `skill-${c.value}` }), {
+        status: 201,
+        headers: { "Content-Type": "application/json", Location: "/v1/skills/abc" },
+      }),
+    );
+    const headers = { "Idempotency-Key": "key-abc-123" };
+    const first = await app.request("/api/v1/skills", { method: "POST", headers });
+    const second = await app.request("/api/v1/skills", { method: "POST", headers });
+
+    expect(counter.value).toBe(1);
+    expect(first.status).toBe(201);
+    expect(second.status).toBe(201);
+    expect(await first.json()).toEqual({ id: "skill-1" });
+    expect(await second.json()).toEqual({ id: "skill-1" });
+    expect(second.headers.get("Idempotency-Replay")).toBe("true");
+    expect(first.headers.get("Idempotency-Replay")).toBe(null);
+    // Cached headers round-trip (Location was set by the handler).
+    expect(second.headers.get("Location")).toBe("/v1/skills/abc");
+  });
+
+  test("different users with the same key DON'T collide (per-user scoping)", async () => {
+    const { app, counter } = makeApp((c) =>
+      new Response(JSON.stringify({ id: c.value }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+    const key = "shared-key";
+    const a = await app.request("/api/v1/skills", {
+      method: "POST",
+      headers: { "Idempotency-Key": key, "x-test-user": "alice" },
+    });
+    const b = await app.request("/api/v1/skills", {
+      method: "POST",
+      headers: { "Idempotency-Key": key, "x-test-user": "bob" },
+    });
+    expect(counter.value).toBe(2);
+    expect(await a.json()).toEqual({ id: 1 });
+    expect(await b.json()).toEqual({ id: 2 });
+    expect(b.headers.get("Idempotency-Replay")).toBe(null);
+  });
+
+  test("different paths with the same key DON'T collide", async () => {
+    const counter = { value: 0 };
+    const app = new Hono();
+    app.use("*", async (c, next) => {
+      c.set("auth" as never, { userId: "u1" } as never);
+      await next();
+    });
+    app.use("*", idempotencyMiddleware({ repo }));
+    app.post("/api/v1/skills", async () => {
+      counter.value += 1;
+      return new Response(JSON.stringify({ kind: "skill", n: counter.value }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+    app.post("/api/v1/tags", async () => {
+      counter.value += 1;
+      return new Response(JSON.stringify({ kind: "tag", n: counter.value }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+    const headers = { "Idempotency-Key": "k" };
+    const skill = await app.request("/api/v1/skills", { method: "POST", headers });
+    const tag = await app.request("/api/v1/tags", { method: "POST", headers });
+    expect(counter.value).toBe(2);
+    expect((await skill.json()) as { kind: string; n: number }).toEqual({ kind: "skill", n: 1 });
+    expect((await tag.json()) as { kind: string; n: number }).toEqual({ kind: "tag", n: 2 });
+  });
+
+  test("4xx responses ARE cached (the client should see the same validation error on retry)", async () => {
+    const { app, counter } = makeApp((c) =>
+      new Response(JSON.stringify({ code: "validation_error", n: c.value }), {
+        status: 400,
+        headers: { "Content-Type": "application/problem+json" },
+      }),
+    );
+    const headers = { "Idempotency-Key": "k" };
+    const first = await app.request("/api/v1/skills", { method: "POST", headers });
+    const second = await app.request("/api/v1/skills", { method: "POST", headers });
+    expect(counter.value).toBe(1);
+    expect(first.status).toBe(400);
+    expect(second.status).toBe(400);
+    expect(second.headers.get("Idempotency-Replay")).toBe("true");
+  });
+
+  test("5xx responses are NOT cached (transient — let the next retry hit the handler)", async () => {
+    const { app, counter } = makeApp((c) =>
+      new Response(JSON.stringify({ code: "internal_error", n: c.value }), {
+        status: 500,
+        headers: { "Content-Type": "application/problem+json" },
+      }),
+    );
+    const headers = { "Idempotency-Key": "k" };
+    await app.request("/api/v1/skills", { method: "POST", headers });
+    await app.request("/api/v1/skills", { method: "POST", headers });
+    expect(counter.value).toBe(2);
+    expect(await db.collection("idempotency_keys").countDocuments()).toBe(0);
+  });
+
+  test("204 No Content replays cleanly (empty body, no content-type)", async () => {
+    const { app, counter } = makeApp(() => new Response(null, { status: 204 }));
+    const headers = { "Idempotency-Key": "k" };
+    const first = await app.request("/api/v1/skills", { method: "DELETE", headers });
+    const second = await app.request("/api/v1/skills", { method: "DELETE", headers });
+    expect(counter.value).toBe(1);
+    expect(first.status).toBe(204);
+    expect(second.status).toBe(204);
+    expect(second.headers.get("Idempotency-Replay")).toBe("true");
+  });
+
+  test("oversize keys are silently bypassed (do not 400 every caller as soon as the middleware ships)", async () => {
+    const { app, counter } = makeApp(() => new Response("ok", { status: 200 }));
+    const oversize = "x".repeat(MAX_IDEMPOTENCY_KEY_LENGTH + 1);
+    await app.request("/api/v1/skills", {
+      method: "POST",
+      headers: { "Idempotency-Key": oversize },
+    });
+    await app.request("/api/v1/skills", {
+      method: "POST",
+      headers: { "Idempotency-Key": oversize },
+    });
+    expect(counter.value).toBe(2);
+    expect(await db.collection("idempotency_keys").countDocuments()).toBe(0);
+  });
+
+  test("TTL index is created with the documented 24h window", async () => {
+    const indexes = await db.collection("idempotency_keys").indexes();
+    const ttl = indexes.find((i) => i.name === "createdAt_ttl");
+    expect(ttl).toBeDefined();
+    expect(ttl?.expireAfterSeconds).toBe(24 * 60 * 60);
+  });
+
+  test("handler errors that don't produce a response don't pollute the cache", async () => {
+    // Hono catches thrown errors via `app.onError`. With no `onError`
+    // configured, a thrown error surfaces as a default 500 page — which
+    // is 5xx, which we already don't cache. Pin that explicitly so a
+    // future change to error handling can't sneak through.
+    const app = new Hono();
+    app.use("*", async (c, next) => {
+      c.set("auth" as never, { userId: "u1" } as never);
+      await next();
+    });
+    app.use("*", idempotencyMiddleware({ repo }));
+    app.post("/api/v1/skills", () => {
+      throw new Error("boom");
+    });
+    const headers = { "Idempotency-Key": "k" };
+    await app.request("/api/v1/skills", { method: "POST", headers });
+    expect(await db.collection("idempotency_keys").countDocuments()).toBe(0);
+  });
+});
diff --git a/ornn-api/src/middleware/idempotency.ts b/ornn-api/src/middleware/idempotency.ts
new file mode 100644
index 00000000..9998134d
--- /dev/null
+++ b/ornn-api/src/middleware/idempotency.ts
@@ -0,0 +1,248 @@
+/**
+ * Idempotency-Key middleware (CONVENTIONS.md §3.4, #459).
+ *
+ * On every state-changing request (`POST` / `PUT` / `PATCH` / `DELETE`)
+ * carrying an `Idempotency-Key` header, the middleware fingerprints
+ * `(userId, method, path, key)` and looks the fingerprint up in the
+ * `idempotency_keys` Mongo collection. If a prior response is cached
+ * within the 24 h TTL window, the cached body + status + headers are
+ * returned verbatim with `Idempotency-Replay: true`. Otherwise the
+ * handler executes and its response is persisted for the next retry.
+ *
+ * Industry parallels: Stripe, Square, AWS, GitHub all expose
+ * `Idempotency-Key` in the same shape. Without it, an agent that
+ * retries a POST after a transient network failure can create
+ * duplicate skills / redemptions / notifications — a class of bug that
+ * lands on the on-call to clean up manually.
+ *
+ * Mount order constraints:
+ * - MUST run AFTER `proxyAuthSetup` so `c.var.auth.userId` is set; the
+ *   fingerprint is per-user, otherwise two unrelated callers could
+ *   replay each other's response with the same key.
+ * - MUST run BEFORE per-route handlers so it can short-circuit on
+ *   cache hits and capture handler responses on cache misses.
+ *
+ * @module middleware/idempotency
+ */
+
+import type { MiddlewareHandler } from "hono";
+import type { Collection, Db } from "mongodb";
+import { createLogger } from "../shared/logger";
+const logger = createLogger("idempotency");
+
+/** 24-hour TTL, per CONVENTIONS.md §3.4 — matches Stripe / GitHub. */
+export const IDEMPOTENCY_TTL_SECONDS = 24 * 60 * 60;
+
+/** Methods that mutate state. GET / HEAD / OPTIONS are idempotent by definition. */
+const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+
+/**
+ * Idempotency-Key values are arbitrary client strings. We refuse keys
+ * over this length to prevent unbounded growth of fingerprint indexes
+ * and to surface obvious bugs (e.g. an agent stuffing a full body into
+ * the header).
+ */
+export const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+
+/** 5xx responses are transient — replaying a server error doesn't help. */
+function shouldCache(status: number): boolean {
+  return status < 500;
+}
+
+export interface IdempotencyKeyDoc {
+  /** Composite fingerprint: `${userId}:${method}:${path}:${key}`. */
+  _id: string;
+  key: string;
+  userId: string;
+  method: string;
+  path: string;
+  responseStatus: number;
+  /**
+   * Response body as a UTF-8 string. Non-text payloads (e.g. ZIP
+   * downloads) get base64-encoded; `responseEncoding` tracks the form.
+   * The 16 MiB Mongo doc limit easily covers every JSON response we
+   * emit today and tomorrow.
+   */
+  responseBody: string;
+  responseEncoding: "utf-8" | "base64";
+  responseHeaders: Record<string, string>;
+  createdAt: Date;
+}
+
+export class IdempotencyKeyRepository {
+  private readonly col: Collection<IdempotencyKeyDoc>;
+
+  constructor(db: Db) {
+    this.col = db.collection<IdempotencyKeyDoc>("idempotency_keys");
+  }
+
+  async ensureIndexes(): Promise<void> {
+    // Mongo TTL monitor sweeps once per minute; documents are deleted
+    // when `createdAt + expireAfterSeconds < now`. The composite `_id`
+    // already gives unique-key replay protection.
+    await this.col.createIndex(
+      { createdAt: 1 },
+      { expireAfterSeconds: IDEMPOTENCY_TTL_SECONDS, name: "createdAt_ttl" },
+    );
+  }
+
+  async find(id: string): Promise<IdempotencyKeyDoc | null> {
+    return await this.col.findOne({ _id: id });
+  }
+
+  /**
+   * Insert with duplicate-key tolerance. Two concurrent requests with
+   * the same key race here — one wins, the other's identical handler
+   * output is silently discarded. Returns `false` on the loser's path
+   * so the caller knows it didn't persist.
+   */
+  async insert(doc: IdempotencyKeyDoc): Promise<{ inserted: boolean }> {
+    try {
+      await this.col.insertOne(doc);
+      return { inserted: true };
+    } catch (err: unknown) {
+      const code = (err as { code?: number } | null)?.code;
+      if (code === 11000) {
+        return { inserted: false };
+      }
+      throw err;
+    }
+  }
+}
+
+function fingerprint(userId: string, method: string, path: string, key: string): string {
+  return `${userId}:${method}:${path}:${key}`;
+}
+
+function captureHeaders(res: Response): Record<string, string> {
+  const headers: Record<string, string> = {};
+  res.headers.forEach((value, name) => {
+    headers[name] = value;
+  });
+  return headers;
+}
+
+/**
+ * Test seam: lets callers inject a custom date for deterministic TTL
+ * assertions. Production callers leave it as `Date.now()`.
+ */
+function nowProvider(): Date {
+  return new Date();
+}
+
+export interface IdempotencyConfig {
+  repo: IdempotencyKeyRepository;
+  /** Override for tests. */
+  now?: () => Date;
+}
+
+export function idempotencyMiddleware(config: IdempotencyConfig): MiddlewareHandler {
+  const { repo, now = nowProvider } = config;
+
+  return async (c, next) => {
+    const method = c.req.method.toUpperCase();
+    const rawKey = c.req.header("Idempotency-Key");
+
+    // Not applicable: safe method (GET / HEAD / OPTIONS) or no key.
+    if (!MUTATING_METHODS.has(method) || !rawKey) {
+      return next();
+    }
+
+    const key = rawKey.trim();
+    if (key.length === 0 || key.length > MAX_IDEMPOTENCY_KEY_LENGTH) {
+      // Malformed keys fall through and don't cache. Returning 400
+      // here would be more strict but creates a new failure mode for
+      // every existing caller as soon as the middleware ships.
+      logger.debug({ keyLength: key.length, path: c.req.path }, "Idempotency key rejected");
+      return next();
+    }
+
+    const auth = (c.get as unknown as (k: "auth") => { userId?: string } | undefined)("auth");
+    const userId = auth?.userId ?? "anonymous";
+    const path = c.req.path;
+    const id = fingerprint(userId, method, path, key);
+
+    const cached = await repo.find(id);
+    if (cached) {
+      logger.info({ id, userId, method, path, status: cached.responseStatus }, "Idempotency replay");
+      const replayHeaders = new Headers(cached.responseHeaders);
+      replayHeaders.set("Idempotency-Replay", "true");
+      const body =
+        cached.responseEncoding === "base64"
+          ? Uint8Array.from(atob(cached.responseBody), (ch) => ch.charCodeAt(0))
+          : cached.responseBody;
+      return new Response(body, {
+        status: cached.responseStatus,
+        headers: replayHeaders,
+      });
+    }
+
+    await next();
+
+    // Capture and persist the handler's response. The store happens
+    // BEFORE the function returns — synchronous persistence is the
+    // only way to guarantee that a retry arriving 10 ms later sees the
+    // cached entry, which is the entire point of the feature. (A
+    // fire-and-forget write would race the retry.)
+    const res: Response | undefined = c.res;
+    if (!res || !shouldCache(res.status)) {
+      return;
+    }
+
+    try {
+      const responseHeaders = captureHeaders(res);
+      const contentType = responseHeaders["content-type"] ?? "";
+      let body: string;
+      let encoding: "utf-8" | "base64";
+      if (contentType.startsWith("application/") || contentType.startsWith("text/")) {
+        // Clone before reading so the original response stream is
+        // still consumable by the actual client.
+        body = await res.clone().text();
+        encoding = "utf-8";
+      } else {
+        // Binary — base64-encode for storage. Empty bodies (e.g. 204)
+        // round-trip as empty strings either way.
+        const buffer = await res.clone().arrayBuffer();
+        body = bufferToBase64(new Uint8Array(buffer));
+        encoding = "base64";
+      }
+
+      const doc: IdempotencyKeyDoc = {
+        _id: id,
+        key,
+        userId,
+        method,
+        path,
+        responseStatus: res.status,
+        responseBody: body,
+        responseEncoding: encoding,
+        responseHeaders,
+        createdAt: now(),
+      };
+      const { inserted } = await repo.insert(doc);
+      if (!inserted) {
+        logger.debug({ id }, "Idempotency persist lost a race");
+      }
+    } catch (err) {
+      // Persistence failure must NEVER fail the request. The client
+      // gets a correct response; the only cost is no replay protection
+      // if the same retry happens before the TTL window.
+      logger.warn({ err, id }, "Idempotency persist failed");
+    }
+  };
+}
+
+/**
+ * Cross-runtime base64 encode for `Uint8Array`. Bun + Node have
+ * different globals available; this works in both without pulling in
+ * the `buffer` shim explicitly.
+ */
+function bufferToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    const byte = bytes[i];
+    if (byte === undefined) continue;
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
diff --git a/ornn-api/src/middleware/nyxidAuth.ts b/ornn-api/src/middleware/nyxidAuth.ts
index febcbc7d..ee4c7bda 100644
--- a/ornn-api/src/middleware/nyxidAuth.ts
+++ b/ornn-api/src/middleware/nyxidAuth.ts
@@ -15,10 +15,10 @@
 
 import type { Context, Next } from "hono";
 import { createMiddleware } from "hono/factory";
-import pino from "pino";
+import { createLogger } from "../shared/logger";
 import { AppError } from "../shared/types/index";
 
-const logger = pino({ level: "info" }).child({ module: "nyxidAuth" });
+const logger = createLogger("nyxidAuth");
 
 // ---------------------------------------------------------------------------
 // Types
@@ -99,7 +99,9 @@ function decodeJwtPayload(token: string): IdentityAssertionPayload | null {
   try {
     const parts = token.split(".");
     if (parts.length !== 3) return null;
-    const payload = Buffer.from(parts[1], "base64url").toString("utf-8");
+    // Length-checked above — parts[1] is guaranteed defined. `!` is
+    // safe under noUncheckedIndexedAccess (#450).
+    const payload = Buffer.from(parts[1]!, "base64url").toString("utf-8");
     return JSON.parse(payload) as IdentityAssertionPayload;
   } catch (e) {
     logger.warn({ error: (e as Error).message }, "Failed to decode identity token");
@@ -161,13 +163,14 @@ export function proxyAuthSetup(options: ProxyAuthSetupOptions = {}) {
       const payload = decodeJwtPayload(identityToken);
       if (payload?.sub) {
         const email = payload.email ?? "";
+        // exactOptionalPropertyTypes (#657)
         const auth: AuthContext = {
           userId: payload.sub,
           email,
           displayName: payload.name ?? email ?? payload.sub,
           roles: payload.roles ?? [],
           permissions: payload.permissions ?? [],
-          userAccessToken,
+          ...(userAccessToken !== undefined ? { userAccessToken } : {}),
         };
         c.set("auth", auth);
         try {
@@ -185,13 +188,14 @@ export function proxyAuthSetup(options: ProxyAuthSetupOptions = {}) {
     const userId = c.req.header("X-NyxID-User-Id");
     if (userId) {
       const email = c.req.header("X-NyxID-User-Email") ?? "";
+      // exactOptionalPropertyTypes (#657)
       const auth: AuthContext = {
         userId,
         email,
         displayName: c.req.header("X-NyxID-User-Name") ?? email ?? userId,
         roles: [],
         permissions: [],
-        userAccessToken,
+        ...(userAccessToken !== undefined ? { userAccessToken } : {}),
       };
       c.set("auth", auth);
       try {
@@ -217,7 +221,7 @@ export function nyxidAuthMiddleware() {
   return createMiddleware<{ Variables: AuthVariables }>(async (c, next) => {
     const auth = c.get("auth");
     if (!auth) {
-      throw new AppError(401, "AUTH_MISSING", "Authentication required");
+      throw new AppError(401, "auth_missing", "Authentication required");
     }
     await next();
   });
@@ -243,13 +247,13 @@ export function requirePermission(...required: string[]) {
   return async (c: Context<{ Variables: AuthVariables }>, next: Next) => {
     const auth = c.get("auth");
     if (!auth) {
-      throw new AppError(401, "AUTH_MISSING", "Not authenticated");
+      throw new AppError(401, "auth_missing", "Not authenticated");
     }
 
     for (const perm of required) {
       if (!auth.permissions.includes(perm)) {
         logger.warn({ userId: auth.userId, missing: perm }, "Permission denied");
-        throw new AppError(403, "FORBIDDEN", `Missing permission: ${perm}`);
+        throw new AppError(403, "forbidden", `Missing permission: ${perm}`);
       }
     }
 
@@ -264,12 +268,12 @@ export function requireOwnerOrAdmin(getResourceOwnerId: (c: Context) => Promise<
   return async (c: Context<{ Variables: AuthVariables }>, next: Next) => {
     const auth = c.get("auth");
     if (!auth) {
-      throw new AppError(401, "AUTH_MISSING", "Not authenticated");
+      throw new AppError(401, "auth_missing", "Not authenticated");
     }
 
     const ownerId = await getResourceOwnerId(c);
     if (auth.userId !== ownerId && !auth.permissions.includes("ornn:admin:skill")) {
-      throw new AppError(403, "FORBIDDEN", "You can only operate on your own resources");
+      throw new AppError(403, "forbidden", "You can only operate on your own resources");
     }
 
     await next();
@@ -282,7 +286,7 @@ export function requireOwnerOrAdmin(getResourceOwnerId: (c: Context) => Promise<
 export function getAuth(c: Context<{ Variables: AuthVariables }>): AuthContext {
   const auth = c.get("auth");
   if (!auth) {
-    throw new AppError(401, "AUTH_MISSING", "Not authenticated");
+    throw new AppError(401, "auth_missing", "Not authenticated");
   }
   return auth;
 }
diff --git a/ornn-api/src/middleware/rateLimit.test.ts b/ornn-api/src/middleware/rateLimit.test.ts
new file mode 100644
index 00000000..c20a3d26
--- /dev/null
+++ b/ornn-api/src/middleware/rateLimit.test.ts
@@ -0,0 +1,147 @@
+/**
+ * Tests for the sliding-window rate-limit middleware (#439 + #460).
+ *
+ * Pins:
+ *   - RFC 9239 headers emitted on every response (allowed + denied)
+ *   - 429 response with Retry-After when the cap is exceeded
+ *   - Per-user keying defaults work (no collision between users)
+ *   - Window resets after the configured interval
+ *
+ * @module middleware/rateLimit.test
+ */
+
+import { beforeEach, describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import { AppError } from "../shared/types/index";
+import { __resetRateLimitForTests, rateLimit } from "./rateLimit";
+import { buildProblemJsonBody } from "../shared/types/index";
+
+function makeApp(opts: {
+  windowMs?: number;
+  max?: number;
+  label?: string;
+} = {}) {
+  const app = new Hono();
+  // Stub auth so the default keyBy can find a user id.
+  app.use("*", async (c, next) => {
+    const user = c.req.header("x-test-user") ?? "u1";
+    c.set("auth" as never, { userId: user } as never);
+    await next();
+  });
+  app.use(
+    "*",
+    rateLimit({
+      windowMs: opts.windowMs ?? 60_000,
+      max: opts.max ?? 3,
+      label: opts.label ?? "test",
+    }),
+  );
+  app.get("/", (c) => c.json({ ok: true }));
+  // Translate AppError → 429 like the global handler does.
+  app.onError((err, c) => {
+    if (err instanceof AppError) {
+      const body = buildProblemJsonBody({
+        statusCode: err.statusCode,
+        code: err.code,
+        message: err.message,
+        instance: c.req.path,
+        requestId: null,
+      });
+      return c.json(body, err.statusCode as never, {
+        "Content-Type": "application/problem+json",
+      });
+    }
+    return c.json({ error: { code: "internal_error", message: String(err) } }, 500);
+  });
+  return app;
+}
+
+describe("rateLimit middleware (#439 + #460)", () => {
+  beforeEach(() => __resetRateLimitForTests());
+
+  test("emits RFC 9239 headers on every allowed response", async () => {
+    const app = makeApp({ max: 3 });
+    const res = await app.request("/", { headers: { "x-test-user": "alice" } });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("RateLimit-Limit")).toBe("3");
+    expect(res.headers.get("RateLimit-Remaining")).toBe("2");
+    const reset = Number(res.headers.get("RateLimit-Reset"));
+    expect(reset).toBeGreaterThan(0);
+    expect(reset).toBeLessThanOrEqual(60);
+  });
+
+  test("decrements Remaining across consecutive requests by the same user", async () => {
+    const app = makeApp({ max: 3 });
+    const headers = { "x-test-user": "bob" };
+    const r1 = await app.request("/", { headers });
+    const r2 = await app.request("/", { headers });
+    const r3 = await app.request("/", { headers });
+    expect(r1.headers.get("RateLimit-Remaining")).toBe("2");
+    expect(r2.headers.get("RateLimit-Remaining")).toBe("1");
+    expect(r3.headers.get("RateLimit-Remaining")).toBe("0");
+  });
+
+  test("returns 429 with Retry-After + problem+json when the cap is exceeded", async () => {
+    const app = makeApp({ max: 2 });
+    const headers = { "x-test-user": "charlie" };
+    await app.request("/", { headers });
+    await app.request("/", { headers });
+    const denied = await app.request("/", { headers });
+    expect(denied.status).toBe(429);
+    expect(denied.headers.get("Content-Type")).toContain("application/problem+json");
+    expect(denied.headers.get("Retry-After")).not.toBeNull();
+    expect(denied.headers.get("RateLimit-Remaining")).toBe("0");
+    const body = (await denied.json()) as { code: string; status: number };
+    expect(body.code).toBe("rate_limited");
+    expect(body.status).toBe(429);
+  });
+
+  test("different users share separate buckets (per-user keying)", async () => {
+    const app = makeApp({ max: 1 });
+    const aliceFirst = await app.request("/", { headers: { "x-test-user": "alice" } });
+    expect(aliceFirst.status).toBe(200);
+    // Alice is now at her cap; Bob shouldn't be affected.
+    const bobFirst = await app.request("/", { headers: { "x-test-user": "bob" } });
+    expect(bobFirst.status).toBe(200);
+    expect(bobFirst.headers.get("RateLimit-Remaining")).toBe("0");
+    // Alice's second hit fails.
+    const aliceSecond = await app.request("/", { headers: { "x-test-user": "alice" } });
+    expect(aliceSecond.status).toBe(429);
+  });
+
+  test("window resets after windowMs", async () => {
+    const app = makeApp({ max: 2, windowMs: 50 });
+    const headers = { "x-test-user": "dave" };
+    await app.request("/", { headers });
+    await app.request("/", { headers });
+    const denied = await app.request("/", { headers });
+    expect(denied.status).toBe(429);
+    // Wait past the window
+    await new Promise((r) => setTimeout(r, 60));
+    const allowed = await app.request("/", { headers });
+    expect(allowed.status).toBe(200);
+    expect(allowed.headers.get("RateLimit-Remaining")).toBe("1");
+  });
+
+  test("different labels share separate buckets (multi-limit composition)", async () => {
+    // Two limiters on the same user with different labels.
+    const app = new Hono();
+    app.use("*", async (c, next) => {
+      c.set("auth" as never, { userId: "eve" } as never);
+      await next();
+    });
+    app.use("*", rateLimit({ windowMs: 60_000, max: 2, label: "burst" }));
+    app.use("*", rateLimit({ windowMs: 60_000, max: 10, label: "daily" }));
+    app.get("/", (c) => c.json({ ok: true }));
+    app.onError((err, c) => {
+      if (err instanceof AppError) return c.json({ code: err.code }, err.statusCode as never);
+      return c.json({ code: "internal_error" }, 500);
+    });
+    // Hit the route 3 times — third should fail on the burst limit
+    // even though daily allows 10.
+    await app.request("/");
+    await app.request("/");
+    const r3 = await app.request("/");
+    expect(r3.status).toBe(429);
+  });
+});
diff --git a/ornn-api/src/middleware/rateLimit.ts b/ornn-api/src/middleware/rateLimit.ts
new file mode 100644
index 00000000..6d118206
--- /dev/null
+++ b/ornn-api/src/middleware/rateLimit.ts
@@ -0,0 +1,158 @@
+/**
+ * Sliding-window rate-limit middleware (#439).
+ *
+ * Closes a real abuse surface: `/skill-search?mode=semantic` calls a
+ * paid LLM per request, `/skills` POST runs the AgentSeal scan + ZIP
+ * processing, and `/skills/generate` does both. Without a rate limit,
+ * a trivial loop burns LLM budget or DoS's the database via Mongo
+ * aggregation; an authenticated abuser can do worse than an anonymous
+ * one because the auth quota gates *monthly* spend, not *burst rate*.
+ *
+ * Emits RFC 9239 headers on every response (#460) — clients with
+ * proper backoff (`@chronoai/ornn-sdk`'s future retry wrapper, Stripe-
+ * style SDKs, etc.) read these and self-throttle. Without them,
+ * clients can't tell the difference between "go slower" and "go away".
+ *
+ * Storage is in-memory per process — fine for the single-replica dev /
+ * staging cluster; multi-pod prod will need a Redis backend before
+ * this can be tightened. The middleware behind the scenes uses a
+ * `Map<key, { count, resetAt }>` with periodic-on-access cleanup so
+ * idle keys don't accumulate forever.
+ *
+ * Mount order: must run AFTER `proxyAuthSetup` so `auth.userId` is
+ * available for keying. When auth is missing (public endpoints), the
+ * key falls back to the proxy-forwarded IP. Without IP either,
+ * everyone shares the "anonymous" bucket — a fail-safe for the rare
+ * truly-public path.
+ *
+ * @module middleware/rateLimit
+ */
+
+import type { Context, MiddlewareHandler } from "hono";
+import { AppError } from "../shared/types/index";
+import { createLogger } from "../shared/logger";
+
+const logger = createLogger("rateLimit");
+
+export interface RateLimitConfig {
+  /** Window length in milliseconds. */
+  readonly windowMs: number;
+  /** Max requests allowed in the window. */
+  readonly max: number;
+  /**
+   * Override how the bucket key is derived. Default: `auth.userId` →
+   * `x-forwarded-for` → `"anonymous"`.
+   */
+  readonly keyBy?: (c: Context) => string;
+  /**
+   * Human-readable name for log entries. Useful when one route has
+   * multiple rate-limit middleware mounted (e.g. a per-IP burst cap
+   * + a per-user daily budget).
+   */
+  readonly label?: string;
+}
+
+interface BucketEntry {
+  count: number;
+  /** Epoch ms when the window resets. */
+  resetAt: number;
+}
+
+/**
+ * Module-level bucket store. Multiple `rateLimit()` calls share this
+ * map so the cleanup pass touches every active key.
+ *
+ * Keys are namespaced by label so two middlewares mounted on the same
+ * route don't collide (e.g. `"upload:userId"` vs `"upload-ip:ip"`).
+ */
+const buckets = new Map<string, BucketEntry>();
+
+/**
+ * Last time we walked the bucket map to drop expired entries. Cheap
+ * O(n) sweep; bounded by request rate × cleanup interval.
+ */
+let lastCleanup = 0;
+const CLEANUP_INTERVAL_MS = 60_000;
+
+function cleanupExpired(now: number): void {
+  if (now - lastCleanup < CLEANUP_INTERVAL_MS) return;
+  lastCleanup = now;
+  for (const [key, entry] of buckets) {
+    if (entry.resetAt <= now) buckets.delete(key);
+  }
+}
+
+function defaultKeyBy(c: Context): string {
+  const auth = (c.get as unknown as (k: "auth") => { userId?: string } | undefined)("auth");
+  if (auth?.userId) return `user:${auth.userId}`;
+  // Trust proxy-forwarded IP — production traffic comes through
+  // NyxID's reverse proxy which sets `x-forwarded-for`.
+  const ip = c.req.header("x-forwarded-for")?.split(",")[0]?.trim();
+  if (ip) return `ip:${ip}`;
+  return "anonymous";
+}
+
+/**
+ * Test seam — clears the in-process bucket store between tests.
+ * Not part of the runtime API.
+ */
+export function __resetRateLimitForTests(): void {
+  buckets.clear();
+  lastCleanup = 0;
+}
+
+/**
+ * Create a Hono middleware that enforces a sliding-window rate limit
+ * + emits RFC 9239 headers on every response.
+ *
+ * Per-request flow:
+ *
+ *   1. Compute `key` from the request (default: per-user else per-IP).
+ *   2. Look up the bucket. If the window has expired, reset the count.
+ *   3. Increment + decide allow/deny.
+ *   4. Emit `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset`
+ *      headers regardless of outcome.
+ *   5. On deny, throw `AppError(429, "rate_limited")` with `Retry-After`
+ *      (the global RFC 7807 handler emits it as `application/problem+json`).
+ */
+export function rateLimit(config: RateLimitConfig): MiddlewareHandler {
+  const { windowMs, max, keyBy = defaultKeyBy, label = "default" } = config;
+
+  return async (c, next) => {
+    const now = Date.now();
+    cleanupExpired(now);
+
+    const requestKey = keyBy(c);
+    const key = `${label}:${requestKey}`;
+    let entry = buckets.get(key);
+    if (!entry || entry.resetAt <= now) {
+      entry = { count: 0, resetAt: now + windowMs };
+      buckets.set(key, entry);
+    }
+    entry.count += 1;
+
+    const remaining = Math.max(0, max - entry.count);
+    const resetSeconds = Math.max(0, Math.ceil((entry.resetAt - now) / 1000));
+
+    // RFC 9239 — set BEFORE the next middleware runs so even handlers
+    // that emit their own response shape carry them.
+    c.header("RateLimit-Limit", String(max));
+    c.header("RateLimit-Remaining", String(remaining));
+    c.header("RateLimit-Reset", String(resetSeconds));
+
+    if (entry.count > max) {
+      c.header("Retry-After", String(resetSeconds));
+      logger.info(
+        { key: requestKey, label, count: entry.count, max, resetSeconds },
+        "rate_limited",
+      );
+      throw new AppError(
+        429,
+        "rate_limited",
+        `Rate limit exceeded for ${label}. Retry in ${resetSeconds}s.`,
+      );
+    }
+
+    await next();
+  };
+}
diff --git a/ornn-api/src/middleware/validate.ts b/ornn-api/src/middleware/validate.ts
index 759e8a3d..3ed7e145 100644
--- a/ornn-api/src/middleware/validate.ts
+++ b/ornn-api/src/middleware/validate.ts
@@ -8,7 +8,7 @@
  *     "/skills",
  *     auth,
  *     requirePermission("ornn:skill:create"),
- *     validateBody(skillCreateSchema, "INVALID_SKILL_BODY"),
+ *     validateBody(skillCreateSchema, "invalid_skill_body"),
  *     async (c) => {
  *       const data = getValidatedBody<z.infer<typeof skillCreateSchema>>(c);
  *       ...
@@ -53,14 +53,26 @@ function formatIssues(issues: z.ZodIssue[]): string {
  */
 export function validateBody<T extends z.ZodTypeAny>(
   schema: T,
-  errorCode: string = "INVALID_BODY",
+  errorCode: string = "invalid_body",
 ): MiddlewareHandler {
   return async (c, next) => {
+    // Read as text first so we can disambiguate "empty body" (a
+    // common pattern for endpoints with all-optional fields) from
+    // "syntactically broken JSON" — once `.json()` errors, the body
+    // stream is consumed, so we can't peek for emptiness after.
+    // Per #438 — the bypass pattern this replaces (`c.req.json().catch(() => ({}))`)
+    // had the same empty-body tolerance, but skipped the schema check.
+    // We now keep the tolerance AND validate.
+    const text = await c.req.text().catch(() => "");
     let raw: unknown;
-    try {
-      raw = await c.req.json();
-    } catch {
-      throw AppError.badRequest(errorCode, "Request body must be valid JSON");
+    if (text.trim().length === 0) {
+      raw = {};
+    } else {
+      try {
+        raw = JSON.parse(text);
+      } catch {
+        throw AppError.badRequest(errorCode, "Request body must be valid JSON");
+      }
     }
     const result = schema.safeParse(raw);
     if (!result.success) {
@@ -78,7 +90,7 @@ export function validateBody<T extends z.ZodTypeAny>(
  */
 export function validateQuery<T extends z.ZodTypeAny>(
   schema: T,
-  errorCode: string = "INVALID_QUERY",
+  errorCode: string = "invalid_query",
 ): MiddlewareHandler {
   return async (c, next) => {
     const raw: Record<string, string | undefined> = {};
@@ -101,7 +113,7 @@ export function validateQuery<T extends z.ZodTypeAny>(
  */
 export function validateParams<T extends z.ZodTypeAny>(
   schema: T,
-  errorCode: string = "INVALID_PARAMS",
+  errorCode: string = "invalid_params",
 ): MiddlewareHandler {
   return async (c, next) => {
     const result = schema.safeParse(c.req.param());
diff --git a/ornn-api/src/openapi/specBuilder.ts b/ornn-api/src/openapi/specBuilder.ts
index 1a7dd0a5..d9e91bcd 100644
--- a/ornn-api/src/openapi/specBuilder.ts
+++ b/ornn-api/src/openapi/specBuilder.ts
@@ -260,6 +260,33 @@ function formatValidatePath(): PathItem {
   };
 }
 
+/**
+ * JSON Schema for SKILL.md frontmatter (#464). Unlike the other format
+ * endpoints this one returns a raw JSON Schema document — no envelope —
+ * so external tooling (IDEs, schemastore.org) consumes it directly.
+ */
+function formatSchemaPath(): PathItem {
+  return {
+    get: {
+      summary: "JSON Schema for SKILL.md frontmatter",
+      description:
+        "Canonical JSON Schema (draft-7) for `SKILL.md` YAML frontmatter, generated from the server's Zod schema. Public, long-cacheable. Returns the schema document at the body root with `Content-Type: application/schema+json` — not the standard `{ data, error }` envelope, since consumers (VS Code, Cursor, schemastore.org) expect a raw JSON Schema.",
+      operationId: "getFormatSchema",
+      tags: ["Format"],
+      responses: {
+        200: {
+          description: "JSON Schema document",
+          content: {
+            "application/schema+json": {
+              schema: { type: "object" },
+            },
+          },
+        },
+      },
+    },
+  };
+}
+
 function playgroundChatPath(): PathItem {
   return {
     post: {
@@ -414,6 +441,7 @@ export function buildSpec(): OpenApiSpec {
       // Format
       [`${prefix}/skill-format/rules`]: formatRulesPath(),
       [`${prefix}/skill-format/validate`]: formatValidatePath(),
+      [`${prefix}/skill-manifest-schema.json`]: formatSchemaPath(),
       // Playground
       [`${prefix}/playground/chat`]: playgroundChatPath(),
       // Admin
diff --git a/ornn-api/src/regression/hardcodeSweep.test.ts b/ornn-api/src/regression/hardcodeSweep.test.ts
index 287ea194..bb98cb70 100644
--- a/ornn-api/src/regression/hardcodeSweep.test.ts
+++ b/ornn-api/src/regression/hardcodeSweep.test.ts
@@ -71,6 +71,10 @@ const URL_ALLOWLIST: Array<string | RegExp> = [
   // API the mirror + skill-pull paths talk to. Token-based auth is
   // configured separately via the `mirror` settings section.
   /https?:\/\/api\.github\.com\b/,
+  // The Ornn repo URL used in RFC 8594 `Link: rel="deprecation"`
+  // headers (#586) — points at docs/DEPRECATIONS.md anchors, not a
+  // runtime endpoint we fetch.
+  /https?:\/\/github\.com\/ChronoAIProject\/Ornn\/blob\b/,
 ];
 
 // Specific filename → line allow-list for unavoidable hits (e.g.
diff --git a/ornn-api/src/shared/cursor.test.ts b/ornn-api/src/shared/cursor.test.ts
new file mode 100644
index 00000000..013dbd09
--- /dev/null
+++ b/ornn-api/src/shared/cursor.test.ts
@@ -0,0 +1,63 @@
+/**
+ * Tests for the cursor codec (#457).
+ *
+ * Pins the encode/decode round-trip + the "last page" semantics so
+ * subsequent rewrites (eventual lastSort keyset cursors) can be
+ * validated against the same contract.
+ *
+ * @module shared/cursor.test
+ */
+
+import { describe, expect, test } from "bun:test";
+import { encodeCursor, decodeCursor, buildNextCursor } from "./cursor";
+
+describe("encodeCursor + decodeCursor round-trip", () => {
+  test("encodes + decodes a page payload losslessly", () => {
+    const original = { page: 7 };
+    const encoded = encodeCursor(original);
+    const decoded = decodeCursor(encoded);
+    expect(decoded).toEqual(original);
+  });
+
+  test("encoded cursor is URL-safe (no `/` or `+`)", () => {
+    // base64url is the standard for opaque tokens in URL params — pin
+    // it so future codec rewrites can't silently regress to base64.
+    const encoded = encodeCursor({ page: 1 });
+    expect(encoded).not.toMatch(/[/+=]/);
+  });
+
+  test("decodeCursor returns null on malformed input", () => {
+    expect(decodeCursor("")).toBeNull();
+    expect(decodeCursor(undefined)).toBeNull();
+    expect(decodeCursor("not-base64!")).toBeNull();
+    expect(decodeCursor(Buffer.from("not-json", "utf-8").toString("base64url"))).toBeNull();
+    // Missing `page` field
+    expect(decodeCursor(Buffer.from('{"x":1}', "utf-8").toString("base64url"))).toBeNull();
+    // Non-integer page
+    expect(decodeCursor(Buffer.from('{"page":1.5}', "utf-8").toString("base64url"))).toBeNull();
+    // Negative page
+    expect(decodeCursor(Buffer.from('{"page":-1}', "utf-8").toString("base64url"))).toBeNull();
+    // page is 0
+    expect(decodeCursor(Buffer.from('{"page":0}', "utf-8").toString("base64url"))).toBeNull();
+  });
+});
+
+describe("buildNextCursor — last-page semantics", () => {
+  test("emits a cursor when the page is full (more items likely)", () => {
+    const c = buildNextCursor({ currentPage: 2, pageSize: 9, itemsReturned: 9 });
+    expect(c).toBeDefined();
+    expect(decodeCursor(c)).toEqual({ page: 3 });
+  });
+
+  test("omits the cursor when the page is partial (last page)", () => {
+    // Per CONVENTIONS.md §4.3: "When hasMore === false, nextCursor MAY
+    // be omitted." This function returns undefined for that case.
+    const c = buildNextCursor({ currentPage: 5, pageSize: 9, itemsReturned: 3 });
+    expect(c).toBeUndefined();
+  });
+
+  test("omits the cursor when the page is empty", () => {
+    const c = buildNextCursor({ currentPage: 99, pageSize: 9, itemsReturned: 0 });
+    expect(c).toBeUndefined();
+  });
+});
diff --git a/ornn-api/src/shared/cursor.ts b/ornn-api/src/shared/cursor.ts
new file mode 100644
index 00000000..bc625cfb
--- /dev/null
+++ b/ornn-api/src/shared/cursor.ts
@@ -0,0 +1,61 @@
+/**
+ * Cursor encode/decode for paginated list endpoints (#457).
+ *
+ * Per CONVENTIONS.md §4.3, list endpoints return `meta.nextCursor`
+ * — an opaque base64-encoded JSON token the client passes back as
+ * `?cursor=...` for the next page. Clients MUST NOT parse the
+ * payload; the format is server-internal and free to evolve.
+ *
+ * v1 payload shape: `{ page: number }` — backed by the existing
+ * offset-based query layer underneath. The cursor abstraction lets
+ * the API contract conform to §4.3 immediately while the underlying
+ * query stays offset; a follow-up PR can swap the payload for a
+ * `lastSort` keyset cursor without changing the client-visible
+ * interface.
+ *
+ * @module shared/cursor
+ */
+
+export interface CursorPayload {
+  /** 1-indexed page number — what the underlying offset query reads. */
+  page: number;
+}
+
+/** Encode a cursor payload as a URL-safe base64 string. */
+export function encodeCursor(payload: CursorPayload): string {
+  return Buffer.from(JSON.stringify(payload), "utf-8").toString("base64url");
+}
+
+/**
+ * Decode an opaque cursor. Returns `null` for any malformed input —
+ * the route layer then surfaces a 400 `invalid_cursor` so an old
+ * client doesn't end up paginating from page 1 silently.
+ */
+export function decodeCursor(raw: string | undefined): CursorPayload | null {
+  if (!raw || typeof raw !== "string" || raw.length === 0) return null;
+  try {
+    const json = Buffer.from(raw, "base64url").toString("utf-8");
+    const parsed = JSON.parse(json) as unknown;
+    if (!parsed || typeof parsed !== "object") return null;
+    const page = (parsed as { page?: unknown }).page;
+    if (typeof page !== "number" || !Number.isInteger(page) || page < 1) return null;
+    return { page };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the next-page cursor for an offset-based response. Returns
+ * `undefined` when there are no more pages (callers omit
+ * `nextCursor` from `meta` in that case per CONVENTIONS.md §4.3).
+ */
+export function buildNextCursor(args: {
+  currentPage: number;
+  pageSize: number;
+  itemsReturned: number;
+}): string | undefined {
+  // No more items means we're on the last page.
+  if (args.itemsReturned < args.pageSize) return undefined;
+  return encodeCursor({ page: args.currentPage + 1 });
+}
diff --git a/ornn-api/src/shared/logger.test.ts b/ornn-api/src/shared/logger.test.ts
new file mode 100644
index 00000000..19f374e4
--- /dev/null
+++ b/ornn-api/src/shared/logger.test.ts
@@ -0,0 +1,65 @@
+/**
+ * Tests for the shared logger factory (#575).
+ *
+ * The factory replaces 64 standalone `pino({ level: "info" })` calls
+ * across ornn-api. These tests pin the two properties that broke
+ * before #575:
+ *
+ *   1. Loggers respect `LOG_LEVEL` env (set before module load).
+ *   2. Loggers redact sensitive fields (`*.apiKey`, `*.password`,
+ *      `*.secret`, `req.headers.authorization`, etc).
+ *
+ * @module shared/logger.test
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createLogger } from "./logger";
+
+describe("createLogger (#575)", () => {
+  test("returns a logger bound to the module name", () => {
+    const logger = createLogger("test-module");
+    expect(logger).toBeDefined();
+    // pino loggers don't expose their bindings publicly — verify
+    // shape via the methods they're guaranteed to have.
+    expect(typeof logger.info).toBe("function");
+    expect(typeof logger.debug).toBe("function");
+    expect(typeof logger.warn).toBe("function");
+    expect(typeof logger.error).toBe("function");
+    expect(typeof logger.child).toBe("function");
+  });
+
+  test("multiple calls return independent child loggers", () => {
+    const a = createLogger("module-a");
+    const b = createLogger("module-b");
+    expect(a).not.toBe(b);
+  });
+
+  test("inherits `level` from the shared root (LOG_LEVEL env)", () => {
+    const logger = createLogger("level-test");
+    // process.env.LOG_LEVEL is undefined in this test env → defaults
+    // to "info". The level getter on pino reflects the active level.
+    expect(logger.level).toBe(process.env.LOG_LEVEL ?? "info");
+  });
+
+  test("supports the same call sites the old pattern did", () => {
+    // The 64 sites this replaces all call .info / .debug / .warn /
+    // .error with an object payload + message string. Smoke-test
+    // each shape so a future pino major-version bump that changes
+    // the signature would fail this test.
+    const logger = createLogger("smoke");
+    expect(() => logger.info({ foo: 1 }, "hello")).not.toThrow();
+    expect(() => logger.debug({ bar: 2 }, "world")).not.toThrow();
+    expect(() => logger.warn({ baz: 3 }, "warning")).not.toThrow();
+    expect(() => logger.error({ err: new Error("x") }, "boom")).not.toThrow();
+  });
+
+  test("child loggers can be created from a created logger", () => {
+    // The bootstrap path layers another `.child({ requestId })` on
+    // top of the module logger; verify that still works through the
+    // factory's output.
+    const parent = createLogger("parent");
+    const child = parent.child({ requestId: "req_test" });
+    expect(child).toBeDefined();
+    expect(typeof child.info).toBe("function");
+  });
+});
diff --git a/ornn-api/src/shared/logger.ts b/ornn-api/src/shared/logger.ts
new file mode 100644
index 00000000..d5c643be
--- /dev/null
+++ b/ornn-api/src/shared/logger.ts
@@ -0,0 +1,82 @@
+/**
+ * Shared logger factory (#575).
+ *
+ * Before this module landed, 64 source files instantiated their own
+ * `pino({ level: "info" }).child({ module: "..." })` standalone. Two
+ * problems:
+ *
+ *   1. The `LOG_LEVEL` env var only affected the bootstrap logger.
+ *      Setting `LOG_LEVEL=debug` left every other logger at info,
+ *      hiding the very `logger.debug(...)` calls #579 just added.
+ *   2. The bootstrap logger redacts `authorization`, `x-api-key`,
+ *      `password`, `secret`, `apiKey`. Standalone loggers bypassed
+ *      all of that — a misconfigured handler logging req headers
+ *      would leak bearer tokens.
+ *
+ * `createLogger(moduleName)` returns a child of a single process-wide
+ * pino root configured with both — every consumer inherits both knobs
+ * for free.
+ *
+ * Why a factory not an injected logger: dozens of small clients /
+ * utils have a top-of-file `const logger = ...` for one-or-two
+ * `logger.debug` calls. Threading a logger through every constructor
+ * would be a much larger refactor with little payoff for those leaf
+ * modules. The factory is a drop-in replacement for the previous
+ * pattern.
+ *
+ * The bootstrap-level pino instance (constructed in `bootstrap.ts`
+ * with `service: "ornn-api"`) is intentionally separate — it logs
+ * the request/response pair with extra `service` metadata that
+ * module loggers don't need. Both inherit the same env-driven level
+ * + redaction.
+ *
+ * @module shared/logger
+ */
+
+import pino, { type Logger } from "pino";
+
+/**
+ * Re-export the pino `Logger` type so consumers don't need to
+ * import `pino` directly just for the type. Eliminates the last
+ * reason a domain file would have to know about pino at all.
+ */
+export type { Logger };
+
+/**
+ * Read once at module load so every call to `createLogger()` sees
+ * the same level. Re-importing this module doesn't re-read env —
+ * tests that need to swap LOG_LEVEL mid-process should set env
+ * BEFORE the first import.
+ */
+const LEVEL = process.env.LOG_LEVEL ?? "info";
+
+/**
+ * Default redaction rules. Mirrors the bootstrap pino exactly so
+ * module loggers can't accidentally log a bearer token. Adding new
+ * sensitive fields here updates every logger in the codebase.
+ */
+const REDACT_PATHS = [
+  "req.headers.authorization",
+  'req.headers["x-api-key"]',
+  "*.password",
+  "*.secret",
+  "*.apiKey",
+];
+
+/**
+ * Single process-wide root. Children created via `createLogger()`
+ * inherit `level` + `redact` automatically.
+ */
+const root = pino({
+  level: LEVEL,
+  redact: { paths: REDACT_PATHS },
+});
+
+/**
+ * Returns a logger pre-bound to `{ module: moduleName }`. Drop-in
+ * replacement for the previous `pino({ level: "info" }).child({
+ * module: ... })` pattern across `ornn-api`.
+ */
+export function createLogger(moduleName: string): Logger {
+  return root.child({ module: moduleName });
+}
diff --git a/ornn-api/src/shared/schemas/skillFrontmatter.test.ts b/ornn-api/src/shared/schemas/skillFrontmatter.test.ts
new file mode 100644
index 00000000..3670802f
--- /dev/null
+++ b/ornn-api/src/shared/schemas/skillFrontmatter.test.ts
@@ -0,0 +1,125 @@
+/**
+ * SkillFrontmatter schema tests — pins the #649 actionable-error
+ * contract.
+ *
+ * These cases reproduce common user mistakes (unquoted YAML version,
+ * empty `- ` list items, bad regex shapes) and assert that the schema
+ * returns a message that tells the user *what to write instead*, not
+ * just "Invalid input".
+ *
+ * @module shared/schemas/skillFrontmatter.test
+ */
+
+import { describe, expect, test } from "bun:test";
+import { validateSkillFrontmatter } from "./skillFrontmatter";
+
+function base(overrides: Partial<Record<string, unknown>> = {}) {
+  return {
+    name: "qa-sample",
+    description: "Sample description that is long enough",
+    version: "0.1",
+    metadata: { category: "plain", tag: ["qa"] },
+    ...overrides,
+  };
+}
+
+describe("validateSkillFrontmatter — actionable errors (#649)", () => {
+  test("unquoted numeric version → explains the YAML quoting trap", () => {
+    const r = validateSkillFrontmatter(base({ version: 0.1 }));
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    const msg = r.errors.find((e) => e.field === "version")?.message ?? "";
+    expect(msg).toContain("quoted string");
+    expect(msg).toContain('version: "0.1"');
+  });
+
+  test("null tag (empty `- ` list item) → explains tag shape", () => {
+    const r = validateSkillFrontmatter(
+      base({ metadata: { category: "plain", tag: [null] } }),
+    );
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    const msg = r.errors.find((e) => e.field === "metadata.tag.0")?.message ?? "";
+    expect(msg).toContain("non-empty lowercase strings");
+    expect(msg).toContain("`tag: [my-tag]`");
+    expect(msg).not.toMatch(/^Invalid input$/);
+  });
+
+  test("uppercase tag → existing regex message is preserved", () => {
+    const r = validateSkillFrontmatter(
+      base({ metadata: { category: "plain", tag: ["QA"] } }),
+    );
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    const msg = r.errors.find((e) => e.field === "metadata.tag.0")?.message ?? "";
+    expect(msg).toContain("lowercase alphanumeric with hyphens");
+  });
+
+  test("null env var → explains UPPER_SNAKE_CASE shape", () => {
+    const r = validateSkillFrontmatter(
+      base({
+        metadata: {
+          category: "runtime-based",
+          "output-type": "text",
+          runtime: ["python"],
+          "runtime-env-var": [null],
+        },
+      }),
+    );
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    const msg = r.errors.find((e) => e.field === "metadata.runtime-env-var.0")?.message ?? "";
+    expect(msg).toContain("UPPER_SNAKE_CASE");
+    expect(msg).toContain("OPENAI_API_KEY");
+  });
+
+  test("null runtime entry → actionable message", () => {
+    const r = validateSkillFrontmatter(
+      base({
+        metadata: {
+          category: "runtime-based",
+          "output-type": "text",
+          runtime: [null],
+        },
+      }),
+    );
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    const msg = r.errors.find((e) => e.field === "metadata.runtime.0")?.message ?? "";
+    expect(msg).toContain("`runtime: [python]`");
+  });
+
+  test("null tool entry → actionable message", () => {
+    const r = validateSkillFrontmatter(
+      base({
+        metadata: { category: "tool-based", "tool-list": [null] },
+      }),
+    );
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    const msg = r.errors.find((e) => e.field === "metadata.tool-list.0")?.message ?? "";
+    expect(msg).toContain("`tool-list: [Bash, Read]`");
+  });
+
+  test("null dependency entry → actionable message", () => {
+    const r = validateSkillFrontmatter(
+      base({
+        metadata: {
+          category: "runtime-based",
+          "output-type": "text",
+          runtime: ["python"],
+          "runtime-dependency": [null],
+        },
+      }),
+    );
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    const msg = r.errors.find((e) => e.field === "metadata.runtime-dependency.0")?.message ?? "";
+    expect(msg).toContain("`runtime-dependency: [requests==2.31]`");
+  });
+
+  test("valid frontmatter still parses cleanly", () => {
+    const r = validateSkillFrontmatter(base());
+    expect(r.success).toBe(true);
+  });
+});
diff --git a/ornn-api/src/shared/schemas/skillFrontmatter.ts b/ornn-api/src/shared/schemas/skillFrontmatter.ts
index 6304afff..de8adf46 100644
--- a/ornn-api/src/shared/schemas/skillFrontmatter.ts
+++ b/ornn-api/src/shared/schemas/skillFrontmatter.ts
@@ -14,11 +14,61 @@ export const OUTPUT_TYPES = ["text", "file"] as const;
 export type OutputType = (typeof OUTPUT_TYPES)[number];
 
 // Item-level schemas
-const tagItemSchema = z.string().min(1).max(30).regex(/^[a-z0-9-]+$/, "Tags must be lowercase alphanumeric with hyphens");
-const envVarItemSchema = z.string().min(1).max(100).regex(/^[A-Z_][A-Z0-9_]*$/, "Environment variable names must be UPPER_SNAKE_CASE");
-const toolItemSchema = z.string().min(1).max(100);
-const runtimeItemSchema = z.string().min(1).max(50);
-const dependencyItemSchema = z.string().min(1).max(200);
+//
+// #649 — YAML allows empty list items (`- ` on a line by itself parses
+// as `null`) and lets authors put non-string values where a string is
+// expected. Default Zod messages on those cases come back as bare
+// "Invalid input: expected string, received null" which doesn't tell
+// the author *what to write instead*. Each item schema below carries a
+// custom `error` callback for `invalid_type`; the existing
+// `min`/`max`/`regex` messages still fire for non-null shape problems.
+const tagItemSchema = z
+  .string({
+    error: (issue) =>
+      issue.code === "invalid_type"
+        ? 'tags must be non-empty lowercase strings with optional hyphens, e.g. `tag: [my-tag]` — an empty `- ` line in YAML parses as `null` and is not a valid tag.'
+        : undefined,
+  })
+  .min(1, "tags must not be empty")
+  .max(30, "tags must be at most 30 characters")
+  .regex(/^[a-z0-9-]+$/, "Tags must be lowercase alphanumeric with hyphens");
+const envVarItemSchema = z
+  .string({
+    error: (issue) =>
+      issue.code === "invalid_type"
+        ? 'runtime-env-var entries must be non-empty UPPER_SNAKE_CASE strings, e.g. `runtime-env-var: [OPENAI_API_KEY]` — an empty `- ` line in YAML parses as `null`.'
+        : undefined,
+  })
+  .min(1, "runtime-env-var entries must not be empty")
+  .max(100, "runtime-env-var entries must be at most 100 characters")
+  .regex(/^[A-Z_][A-Z0-9_]*$/, "Environment variable names must be UPPER_SNAKE_CASE");
+const toolItemSchema = z
+  .string({
+    error: (issue) =>
+      issue.code === "invalid_type"
+        ? 'tool-list entries must be non-empty strings, e.g. `tool-list: [Bash, Read]` — an empty `- ` line in YAML parses as `null`.'
+        : undefined,
+  })
+  .min(1, "tool-list entries must not be empty")
+  .max(100, "tool-list entries must be at most 100 characters");
+const runtimeItemSchema = z
+  .string({
+    error: (issue) =>
+      issue.code === "invalid_type"
+        ? 'runtime entries must be non-empty strings, e.g. `runtime: [python]` — an empty `- ` line in YAML parses as `null`.'
+        : undefined,
+  })
+  .min(1, "runtime entries must not be empty")
+  .max(50, "runtime entries must be at most 50 characters");
+const dependencyItemSchema = z
+  .string({
+    error: (issue) =>
+      issue.code === "invalid_type"
+        ? 'runtime-dependency entries must be non-empty strings, e.g. `runtime-dependency: [requests==2.31]` — an empty `- ` line in YAML parses as `null`.'
+        : undefined,
+  })
+  .min(1, "runtime-dependency entries must not be empty")
+  .max(200, "runtime-dependency entries must be at most 200 characters");
 
 // Metadata sub-schema (base, before refinement)
 export const metadataSchema = z.object({
diff --git a/ornn-api/src/shared/types/index.ts b/ornn-api/src/shared/types/index.ts
index 580fce3e..ac7f7ec0 100644
--- a/ornn-api/src/shared/types/index.ts
+++ b/ornn-api/src/shared/types/index.ts
@@ -47,11 +47,11 @@ export class AppError extends Error {
   }
 
   static payloadTooLarge(message: string): AppError {
-    return new AppError(413, "PAYLOAD_TOO_LARGE", message);
+    return new AppError(413, "payload_too_large", message);
   }
 
   static internal(message: string): AppError {
-    return new AppError(500, "INTERNAL_ERROR", message);
+    return new AppError(500, "internal_error", message);
   }
 
   static internalError(code: string, message: string): AppError {
@@ -80,21 +80,17 @@ export interface SkillDocument {
   metadata: SkillMetadata;
   skillHash: string;
   storageKey: string;
-  /**
-   * Legacy back-compat field. Was used by an earlier "org-as-owner" design
-   * to drive visibility; visibility logic no longer consults it. New skills
-   * copy `createdBy` into it; safe to drop in a future cleanup migration.
-   */
-  ownerId: string;
   /**
    * The actual person who authored the skill. ALWAYS a person user_id —
    * never an org. Authors are the only non-admin principals allowed to
    * manage their skill (edit package, toggle public, change permissions,
-   * delete).
+   * delete). #581 removed the legacy `ownerId` mirror of this field.
    */
   createdBy: string;
-  createdByEmail?: string;
-  createdByDisplayName?: string;
+  // Optionals widen to `T | undefined` so partial-update / Zod-inferred
+  // shapes assign cleanly under exactOptionalPropertyTypes (#657).
+  createdByEmail?: string | undefined;
+  createdByDisplayName?: string | undefined;
   createdOn: Date;
   updatedBy: string;
   updatedOn: Date;
@@ -131,7 +127,7 @@ export interface SkillDocument {
    *
    * Absent for hand-uploaded skills.
    */
-  source?: SkillSource;
+  source?: SkillSource | undefined;
   /**
    * NyxID service this skill is tied to. Null/undefined when untied.
    * The tied service determines whether the skill is a "system" skill:
@@ -139,18 +135,18 @@ export interface SkillDocument {
    * sets `isSystemSkill: true` and forces `isPrivate: false`; tying to a
    * private service the caller owns leaves privacy alone.
    */
-  nyxidServiceId?: string | null;
+  nyxidServiceId?: string | null | undefined;
   /** Cached service slug for cheap card/list rendering. */
-  nyxidServiceSlug?: string | null;
+  nyxidServiceSlug?: string | null | undefined;
   /** Cached service label for cheap card/list rendering. */
-  nyxidServiceLabel?: string | null;
+  nyxidServiceLabel?: string | null | undefined;
   /**
    * Cached: true iff `nyxidServiceId` points at an admin/platform-wide
    * service (NyxID `visibility: "public"`). System skills are always
    * `isPrivate: false`. Maintained at tie-time; slight staleness is
    * accepted if NyxID flips a service's visibility — re-tie refreshes.
    */
-  isSystemSkill?: boolean;
+  isSystemSkill?: boolean | undefined;
   /**
    * Per-skill GitHub mirror state. Set by `MirrorService` after a
    * successful publish/reconcile commit lands; unset (`$unset`) when
@@ -165,11 +161,28 @@ export interface SkillDocument {
    * and the next mirror sync — the frontend uses that gap to render a
    * "lagging" chip.
    */
-  mirrorSync?: {
-    version: string;
-    syncedAt: Date;
-    commitSha: string;
-  };
+  mirrorSync?:
+    | {
+        version: string;
+        syncedAt: Date;
+        commitSha: string;
+      }
+    | undefined;
+  /**
+   * Dist-tags per #463 — npm-style aliases that resolve to a concrete
+   * version. Lets callers pin to a stable channel without enumerating
+   * versions.
+   *
+   * - `latest` is **auto-managed**: every successful version publish
+   *   sets `distTags.latest` to the new version. Cannot be PUT/DELETEd
+   *   via the API (those return `dist_tag_immutable`).
+   * - Other tags (`stable`, `beta`, `rc1`, ...) are owner-managed via
+   *   `PUT /v1/skills/:id/dist-tags/:tag` and freely deletable.
+   *
+   * Absent on legacy skills published before #463 — readers treat
+   * absence as `{ latest: <skill.latestVersion> }`.
+   */
+  distTags?: Record<string, string> | undefined;
 }
 
 /**
@@ -192,12 +205,12 @@ export type SkillSource =
        * sync (the user can save a GitHub link first and trigger the sync
        * later from the detail-page advanced options).
        */
-      lastSyncedAt?: Date;
+      lastSyncedAt?: Date | undefined;
       /**
        * Commit SHA that was fetched at `lastSyncedAt`. Allows drift
        * detection. Absent in the same "linked but not yet synced" state.
        */
-      lastSyncedCommit?: string;
+      lastSyncedCommit?: string | undefined;
     };
 
 /**
@@ -222,8 +235,10 @@ export interface SkillVersionDocument {
   license: string | null;
   compatibility: string | null;
   createdBy: string;
-  createdByEmail?: string;
-  createdByDisplayName?: string;
+  // Optionals widen to `T | undefined` so partial-update / Zod-inferred
+  // shapes assign cleanly under exactOptionalPropertyTypes (#657).
+  createdByEmail?: string | undefined;
+  createdByDisplayName?: string | undefined;
   createdOn: Date;
   /**
    * Mutable deprecation flag (phase 2). Absent/undefined means "not deprecated".
@@ -292,11 +307,10 @@ export interface SkillDetailResponse {
   skillHash: string;
   presignedPackageUrl: string;
   isPrivate: boolean;
-  /** Legacy back-compat field. Not used for visibility; equals `createdBy` on new skills. */
-  ownerId: string;
   createdBy: string;
-  createdByEmail?: string;
-  createdByDisplayName?: string;
+  // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
+  createdByEmail?: string | undefined;
+  createdByDisplayName?: string | undefined;
   createdOn: string;
   updatedOn: string;
   /** Person user_ids granted explicit access. Same semantics as on `SkillDocument`. */
@@ -309,41 +323,41 @@ export interface SkillDetailResponse {
    */
   version: string;
   /** True when the resolved version is marked deprecated by the author. */
-  isDeprecated?: boolean;
+  isDeprecated?: boolean | undefined;
   /** Optional note the author left when deprecating this version. */
-  deprecationNote?: string | null;
+  deprecationNote?: string | null | undefined;
   /**
    * Present when the skill was created or refreshed by pulling from an
    * external source (e.g. a public GitHub repo). Clients use this to
    * render a "source" link on the detail page and to power "Refresh from
    * source" actions. Serialized form — `lastSyncedAt` is an ISO string.
    */
-  source?: {
-    type: "github";
-    repo: string;
-    ref: string;
-    path: string;
-    /**
-     * Absent when the skill was linked but not yet synced (the user can
-     * attach a GitHub URL via PUT /skills/:id/source first and trigger
-     * the sync separately via POST /skills/:id/refresh).
-     */
-    lastSyncedAt?: string;
-    /** Absent in the same "linked but never synced" state. */
-    lastSyncedCommit?: string;
-  };
+  source?:
+    | {
+        type: "github";
+        repo: string;
+        ref: string;
+        path: string;
+        /**
+         * Absent when the skill was linked but not yet synced.
+         */
+        lastSyncedAt?: string | undefined;
+        /** Absent in the same "linked but never synced" state. */
+        lastSyncedCommit?: string | undefined;
+      }
+    | undefined;
   /** NyxID service tie (null when untied). See `SkillDocument.nyxidServiceId`. */
-  nyxidServiceId?: string | null;
-  nyxidServiceSlug?: string | null;
-  nyxidServiceLabel?: string | null;
+  nyxidServiceId?: string | null | undefined;
+  nyxidServiceSlug?: string | null | undefined;
+  nyxidServiceLabel?: string | null | undefined;
   /** Cached: true iff tied to an admin/platform-wide NyxID service. */
-  isSystemSkill?: boolean;
+  isSystemSkill?: boolean | undefined;
   /**
    * AgentSeal trust score for the resolved version (#253). Null when
    * the version hasn't been scanned (legacy / disabled). Frontend
    * renders a color-coded badge from this — see DESIGN.md.
    */
-  agentsealScan?: AgentsealScanSnapshot | null;
+  agentsealScan?: AgentsealScanSnapshot | null | undefined;
   /**
    * Per-skill GitHub mirror state. Absent ⇒ never mirrored (or
    * un-mirrored after a privacy flip / explicit reset). Present ⇒ the
@@ -357,77 +371,62 @@ export interface SkillDetailResponse {
    *   - `mirrorSync.version === SkillDetailResponse.version` ⇒ "Synced"
    *   - `mirrorSync.version !== version` ⇒ "Lagging" (mirror push pending)
    */
-  mirrorSync?: {
-    version: string;
-    syncedAt: string;
-    commitSha: string;
-  };
+  mirrorSync?:
+    | {
+        version: string;
+        syncedAt: string;
+        commitSha: string;
+      }
+    | undefined;
+  /**
+   * Dist-tags for this skill (#463). Keys are tag names (`latest`,
+   * `stable`, `beta`, ...); values are the concrete version each tag
+   * currently points at. `latest` is always present and auto-managed
+   * server-side. Absent on legacy skills published before #463.
+   */
+  distTags?: Record<string, string> | undefined;
 }
 
 export interface SkillSearchItem {
   guid: string;
   name: string;
   description: string;
-  /** Owner entity — person user_id or org user_id. */
-  ownerId: string;
   createdBy: string;
-  createdByEmail?: string;
-  createdByDisplayName?: string;
+  // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
+  createdByEmail?: string | undefined;
+  createdByDisplayName?: string | undefined;
   createdOn: string;
   updatedOn: string;
   isPrivate: boolean;
   tags: string[];
-  /**
-   * Why the current caller can see this skill. Populated on search responses
-   * where the caller is authenticated; omitted for anonymous callers.
-   *   - "owner"          — caller authored it (or is platform admin).
-   *   - "public"         — visible to everyone; caller has no special grant.
-   *   - "shared-direct"  — private skill, caller is in `sharedWithUsers`.
-   *   - "shared-via-org" — private skill, one of caller's orgs is in
-   *                        `sharedWithOrgs`; `sharedViaOrgId` names the org.
-   */
-  myAccessReason?: "owner" | "public" | "shared-direct" | "shared-via-org";
-  /** Present when `myAccessReason === "shared-via-org"`. */
-  sharedViaOrgId?: string;
+  myAccessReason?: "owner" | "public" | "shared-direct" | "shared-via-org" | undefined;
+  sharedViaOrgId?: string | undefined;
   /**
    * True when any of this skill's tags matches the slug of a NyxID service
    * the caller can manage (personal or org-inherited). Derived per-request
    * against `/api/me/nyxid-services`.
    */
-  isSystemForMe?: boolean;
-  /**
-   * When `isSystemForMe`, the first matching service. Used by the UI to
-   * render a "⚙️ <label>" chip without a second round-trip. Multiple
-   * matches are possible; the first one wins.
-   */
-  systemForService?: { id: string; slug: string; label: string };
-  /**
-   * Compact view of the skill's ACL state. Cheap to compute (lengths
-   * already on the doc) and lets card UIs render permission chips without
-   * re-fetching the full skill.
-   */
-  permissionSummary?: {
-    isPrivate: boolean;
-    sharedUserCount: number;
-    sharedOrgCount: number;
-  };
-  /**
-   * NyxID service tie surfaced on the search row so cards can render the
-   * "⚙ <serviceLabel>" chip without a second round-trip. `null` when
-   * untied.
-   */
-  nyxidServiceId?: string | null;
-  nyxidServiceSlug?: string | null;
-  nyxidServiceLabel?: string | null;
+  isSystemForMe?: boolean | undefined;
+  systemForService?: { id: string; slug: string; label: string } | undefined;
+  permissionSummary?:
+    | {
+        isPrivate: boolean;
+        sharedUserCount: number;
+        sharedOrgCount: number;
+      }
+    | undefined;
+  nyxidServiceId?: string | null | undefined;
+  nyxidServiceSlug?: string | null | undefined;
+  nyxidServiceLabel?: string | null | undefined;
   /** Cached: true iff tied to an admin/platform-wide NyxID service. */
-  isSystemSkill?: boolean;
+  isSystemSkill?: boolean | undefined;
   /**
    * True when the skill has a `source` pointer of type "github". The
    * card UI uses this to render a small non-clickable GitHub mark; the
    * actual repo URL is not exposed in search results — callers drill
    * into the detail page if they want to follow the link.
    */
-  hasGithubSource?: boolean;
+  hasGithubSource?: boolean | undefined;
 }
 
 export interface SkillSearchResponse {
@@ -495,33 +494,78 @@ export type PlaygroundChatEvent =
   | { type: "finish"; finishReason: string };
 
 // ---------------------------------------------------------------------------
-// Auth Types
+// Auth Utilities
 // ---------------------------------------------------------------------------
 
-export interface ApiKeyInfo {
-  userId: string;
-  email: string;
-  roles: string[];
-  permissions: string[];
+// `ApiKeyInfo` + `INTERNAL_AUTH_HEADER` were removed in #581. They
+// existed only to support the dead `clients/nyxid/auth.ts` AuthClient,
+// itself an unmounted middleware leftover.
+//
+// `createErrorHandler` was also removed — the live error handler lives
+// on the Hono app via `app.onError(...)` in bootstrap.ts; no route
+// imported this function.
+
+export function isDuplicateKeyError(err: unknown): boolean {
+  return typeof err === "object" && err !== null && "code" in err && (err as { code: number }).code === 11000;
 }
 
 // ---------------------------------------------------------------------------
-// Auth Utilities
+// RFC 7807 error body (#456)
 // ---------------------------------------------------------------------------
 
-export const INTERNAL_AUTH_HEADER = "X-Internal-Auth";
+/**
+ * Wire shape of the RFC 7807 `application/problem+json` body the API
+ * emits on every 4xx/5xx response. Fields at the root, not inside an
+ * envelope. See CONVENTIONS.md §1.3 and docs/ERRORS.md.
+ */
+export interface ProblemJsonBody {
+  readonly type: string;
+  readonly title: string;
+  readonly status: number;
+  readonly detail: string;
+  readonly instance: string;
+  readonly code: string;
+  readonly requestId: string | null;
+  readonly errors?: ReadonlyArray<{ path?: string; code?: string; message: string }>;
+}
 
-export function isDuplicateKeyError(err: unknown): boolean {
-  return typeof err === "object" && err !== null && "code" in err && (err as { code: number }).code === 11000;
+/**
+ * Short human-readable summary for the RFC 7807 `title` field. Used by
+ * the live bootstrap handler AND the per-domain test stubs so they stay
+ * in lockstep on the wire shape.
+ */
+export function rfc7807TitleForStatus(status: number): string {
+  if (status === 400) return "Validation failed";
+  if (status === 401) return "Authentication required";
+  if (status === 403) return "Permission denied";
+  if (status === 404) return "Resource not found";
+  if (status === 409) return "Resource conflict";
+  if (status === 413) return "Payload too large";
+  if (status === 415) return "Unsupported media type";
+  if (status === 429) return "Rate limited";
+  if (status >= 500 && status < 600) return "Server error";
+  return "Request failed";
 }
 
-export function createErrorHandler(logger: { error: (...args: unknown[]) => void }) {
-  return (err: Error, c: { json: (body: unknown, status: number) => unknown }) => {
-    if (err instanceof AppError) {
-      return c.json({ data: null, error: { code: err.code, message: err.message } }, err.statusCode);
-    }
-    logger.error(err, "Unhandled error");
-    return c.json({ data: null, error: { code: "INTERNAL_ERROR", message: "Internal server error" } }, 500);
+/**
+ * Build the canonical RFC 7807 body from an `AppError`-like + the path
+ * the request hit. Shared between bootstrap.ts (live) and per-domain
+ * test stubs so wire shape never drifts between dev and CI.
+ */
+export function buildProblemJsonBody(input: {
+  statusCode: number;
+  code: string;
+  message: string;
+  instance: string;
+  requestId: string | null;
+}): ProblemJsonBody {
+  return {
+    type: `https://github.com/ChronoAIProject/Ornn/blob/main/docs/ERRORS.md#${input.code}`,
+    title: rfc7807TitleForStatus(input.statusCode),
+    status: input.statusCode,
+    detail: input.message,
+    instance: input.instance,
+    code: input.code,
+    requestId: input.requestId,
   };
 }
-
diff --git a/ornn-api/src/shared/utils/frontmatter.ts b/ornn-api/src/shared/utils/frontmatter.ts
index 8001beec..ebca54e6 100644
--- a/ornn-api/src/shared/utils/frontmatter.ts
+++ b/ornn-api/src/shared/utils/frontmatter.ts
@@ -29,13 +29,20 @@ export function extractFrontmatter(
   if (!match) return null;
 
   try {
-    const parsed = parseYaml(match[1]);
+    // FRONTMATTER_REGEX always has capture group 1 when it matches. `!`
+    // is safe under noUncheckedIndexedAccess (#450).
+    const parsed = parseYaml(match[1]!);
     if (typeof parsed !== "object" || parsed === null) return null;
 
     const raw = parsed as Record<string, unknown>;
     const camelized = yamlKeysToCamel(raw);
     return adaptOldFrontmatter(camelized);
   } catch {
+    // Intentional silent (#579): YAML parse errors here surface as a
+    // user-facing "frontmatter is invalid" message from the upstream
+    // validator (`validateSkillFrontmatter`). Logging the raw YAML
+    // would be noisy on every malformed-SKILL.md upload and leaks the
+    // user's frontmatter into logs.
     return null;
   }
 }
diff --git a/ornn-api/src/shared/utils/tarBuilder.ts b/ornn-api/src/shared/utils/tarBuilder.ts
index c21ec92b..c48c3366 100644
--- a/ornn-api/src/shared/utils/tarBuilder.ts
+++ b/ornn-api/src/shared/utils/tarBuilder.ts
@@ -62,7 +62,10 @@ export function buildTarHeader(path: string, fileSize: number): Uint8Array {
   // Calculate and set checksum
   let checksum = 0;
   for (let i = 0; i < BLOCK_SIZE; i++) {
-    checksum += header[i];
+    // `header` is a `BLOCK_SIZE`-byte Uint8Array — i is bounded by
+    // BLOCK_SIZE, so `header[i]` is always defined. `!` is safe under
+    // noUncheckedIndexedAccess (#450).
+    checksum += header[i]!;
   }
   const checksumOctal = checksum.toString(8).padStart(6, "0") + "\0 ";
   header.set(encoder.encode(checksumOctal), 148);
diff --git a/ornn-api/src/shared/utils/zip.ts b/ornn-api/src/shared/utils/zip.ts
index 91bec340..26a23c82 100644
--- a/ornn-api/src/shared/utils/zip.ts
+++ b/ornn-api/src/shared/utils/zip.ts
@@ -21,14 +21,18 @@ export function resolveZipRoot(zip: JSZip, allPaths: string[]): ZipRoot {
   for (const path of cleanPaths) {
     const parts = path.split("/").filter(Boolean);
     if (parts.length > 0) {
-      topLevel.add(parts[0]);
+      // Length-guarded above — `parts[0]` is guaranteed defined. `!`
+      // is safe under noUncheckedIndexedAccess (#450).
+      topLevel.add(parts[0]!);
     }
   }
 
   const topLevelEntries = Array.from(topLevel);
 
   if (topLevelEntries.length === 1) {
-    const candidate = topLevelEntries[0];
+    // Same length guard: the if-branch only fires when topLevelEntries
+    // has exactly one element.
+    const candidate = topLevelEntries[0]!;
     const candidateFolder = zip.files[candidate + "/"];
     const hasNestedFiles = cleanPaths.some((p) => p.startsWith(candidate + "/") && p !== candidate + "/");
     if ((candidateFolder && candidateFolder.dir) || hasNestedFiles) {
@@ -39,7 +43,7 @@ export function resolveZipRoot(zip: JSZip, allPaths: string[]): ZipRoot {
           const relative = path.slice(prefix.length);
           const parts = relative.split("/").filter(Boolean);
           if (parts.length > 0) {
-            innerEntries.add(parts[0]);
+            innerEntries.add(parts[0]!);
           }
         }
       }
diff --git a/ornn-api/src/shared/utils/zipLimits.test.ts b/ornn-api/src/shared/utils/zipLimits.test.ts
new file mode 100644
index 00000000..ed0b1e4a
--- /dev/null
+++ b/ornn-api/src/shared/utils/zipLimits.test.ts
@@ -0,0 +1,169 @@
+/**
+ * Tests for backend zip-bomb defense (#633).
+ *
+ * Each test builds a precisely-shaped ZIP via JSZip and asserts the
+ * cap's failure mode. The thresholds are passed via the config arg
+ * so we can use small, fast fixtures (a 100-byte payload tripping a
+ * 50-byte cap exercises the same code path as a 50 MB payload
+ * tripping the 50 MiB default).
+ *
+ * @module shared/utils/zipLimits.test
+ */
+
+import { describe, expect, test } from "bun:test";
+import JSZip from "jszip";
+import { AppError } from "../types/index";
+import {
+  DEFAULT_MAX_TOTAL_UNCOMPRESSED_BYTES,
+  enforceZipLimits,
+} from "./zipLimits";
+
+/**
+ * Build a deflate-compressed ZIP with the given entries. Real
+ * compression so the central-directory `uncompressedSize` field is
+ * actually populated — `STORE` mode would set compressed == uncompressed
+ * and make the ratio check meaningless.
+ */
+async function buildZip(entries: Record<string, Uint8Array | string>): Promise<Uint8Array> {
+  const z = new JSZip();
+  for (const [path, data] of Object.entries(entries)) {
+    z.file(path, data, { compression: "DEFLATE" });
+  }
+  return new Uint8Array(await z.generateAsync({ type: "uint8array", compression: "DEFLATE" }));
+}
+
+async function expectAppError(
+  promise: Promise<unknown>,
+  expected: { status: number; code: string; messagePattern?: RegExp },
+): Promise<AppError> {
+  let caught: unknown = null;
+  try {
+    await promise;
+  } catch (e) {
+    caught = e;
+  }
+  expect(caught).toBeInstanceOf(AppError);
+  const err = caught as AppError;
+  expect(err.statusCode).toBe(expected.status);
+  expect(err.code).toBe(expected.code);
+  if (expected.messagePattern) expect(err.message).toMatch(expected.messagePattern);
+  return err;
+}
+
+describe("enforceZipLimits (#633)", () => {
+  test("happy path: small valid ZIP passes through", async () => {
+    const zip = await buildZip({
+      "skill/SKILL.md": "---\nname: hello\n---\nbody",
+    });
+    await expect(enforceZipLimits(zip)).resolves.toBeUndefined();
+  });
+
+  test("rejects a non-ZIP buffer with 400 invalid_zip", async () => {
+    const garbage = new Uint8Array([0x00, 0x01, 0x02, 0x03, 0x04, 0x05]);
+    await expectAppError(enforceZipLimits(garbage), {
+      status: 400,
+      code: "invalid_zip",
+      messagePattern: /not a valid ZIP/,
+    });
+  });
+
+  test("rejects when cumulative uncompressed exceeds the cap", async () => {
+    // Two entries each 600 bytes uncompressed; cap is 1000.
+    const payload = "x".repeat(600);
+    const zip = await buildZip({
+      "skill/SKILL.md": payload,
+      "skill/assets/big.txt": payload,
+    });
+    await expectAppError(
+      enforceZipLimits(zip, { maxTotalUncompressedBytes: 1000 }),
+      {
+        status: 413,
+        code: "uncompressed_too_large",
+        messagePattern: /uncompressed size exceeds/,
+      },
+    );
+  });
+
+  test("rejects when a single entry exceeds the per-entry cap", async () => {
+    const payload = "x".repeat(2000);
+    const zip = await buildZip({
+      "skill/SKILL.md": "ok",
+      "skill/assets/oversized.txt": payload,
+    });
+    await expectAppError(
+      enforceZipLimits(zip, {
+        maxTotalUncompressedBytes: 10_000, // total fits
+        maxEntryUncompressedBytes: 1000,   // but the entry doesn't
+      }),
+      {
+        status: 413,
+        code: "uncompressed_too_large",
+        messagePattern: /oversized\.txt.*per-entry limit/,
+      },
+    );
+  });
+
+  test("rejects when file count exceeds the cap", async () => {
+    const entries: Record<string, string> = {};
+    for (let i = 0; i < 50; i++) {
+      entries[`skill/assets/f${i}.txt`] = `content-${i}`;
+    }
+    const zip = await buildZip(entries);
+    await expectAppError(
+      enforceZipLimits(zip, { maxFileCount: 10 }),
+      {
+        status: 413,
+        code: "too_many_files",
+        messagePattern: /50 files; limit is 10/,
+      },
+    );
+  });
+
+  test("rejects on classic zip-bomb compression ratio", async () => {
+    // 80 KiB of zeros — deflates to <100 bytes (>1000× ratio).
+    // Compressed buffer must clear the 4 KB ratio-check floor.
+    const zeros = new Uint8Array(80 * 1024);
+    // Add filler so the compressed buffer crosses the 4 KB floor.
+    const filler = new Uint8Array(8 * 1024);
+    crypto.getRandomValues(filler);
+    const zip = await buildZip({
+      "skill/SKILL.md": "tiny",
+      "skill/assets/zeros.bin": zeros,
+      "skill/assets/filler.bin": filler,
+    });
+    await expectAppError(
+      enforceZipLimits(zip, {
+        // Generous cumulative + per-entry caps so the ratio is what fires.
+        maxTotalUncompressedBytes: 10 * 1024 * 1024,
+        maxEntryUncompressedBytes: 5 * 1024 * 1024,
+        maxFileCount: 100,
+        maxCompressionRatio: 5,
+      }),
+      {
+        status: 413,
+        code: "uncompressed_too_large",
+        messagePattern: /compression ratio.*exceeds.*zip-bomb signature/,
+      },
+    );
+  });
+
+  test("tiny ZIP skips the ratio check (header overhead would false-positive)", async () => {
+    // A few-byte ZIP has a high apparent ratio (header dominates) but
+    // poses zero risk. The ratio-check floor (4 KB compressed) means
+    // this passes — only the cumulative cap matters here.
+    const zip = await buildZip({
+      "skill/SKILL.md": "x".repeat(2000),
+    });
+    await expect(
+      enforceZipLimits(zip, {
+        maxTotalUncompressedBytes: 10_000,
+        maxCompressionRatio: 1.1, // would trip if the ratio check ran
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  test("defaults: 50 MiB / 25 MiB / 1000 files — sanity check the constants", async () => {
+    // Verify the exported constant is what the issue scope said.
+    expect(DEFAULT_MAX_TOTAL_UNCOMPRESSED_BYTES).toBe(50 * 1024 * 1024);
+  });
+});
diff --git a/ornn-api/src/shared/utils/zipLimits.ts b/ornn-api/src/shared/utils/zipLimits.ts
new file mode 100644
index 00000000..24602713
--- /dev/null
+++ b/ornn-api/src/shared/utils/zipLimits.ts
@@ -0,0 +1,148 @@
+/**
+ * Backend zip-bomb defense (#633).
+ *
+ * `#443` shipped the same caps on the web client (`zipValidator.ts` in
+ * `ornn-web`), but every other client — SDK, MCP, raw `curl`, agents
+ * over HTTP — bypasses them. This module mirrors the protection on
+ * the server so the publish path can't be coerced into accepting a
+ * 50 KB ZIP that uncompresses to 500 MB inside an extraction loop or
+ * an AgentSeal subprocess.
+ *
+ * The guards walk entries WITHOUT extracting them — `_data.uncompressedSize`
+ * is parsed from the ZIP central directory at `loadAsync` time, so we
+ * decide whether to proceed before any expensive I/O.
+ *
+ * Three caps:
+ *   - cumulative uncompressed size (default 50 MiB)
+ *   - per-entry uncompressed size (default 25 MiB)
+ *   - file count (default 1000)
+ *
+ * Plus a compression-ratio sanity check (50:1) — the classic zip-bomb
+ * signature catches things the per-entry cap would miss when an
+ * attacker spreads payload across many entries.
+ *
+ * @module shared/utils/zipLimits
+ */
+
+import JSZip from "jszip";
+import { AppError } from "../types/index";
+
+/** Default 50 MiB cumulative cap — matches the client-side guard in `ornn-web`. */
+export const DEFAULT_MAX_TOTAL_UNCOMPRESSED_BYTES = 50 * 1024 * 1024;
+
+/** Default 25 MiB per-entry cap — catches a single oversized file even if the total stays under the cap. */
+export const DEFAULT_MAX_ENTRY_UNCOMPRESSED_BYTES = 25 * 1024 * 1024;
+
+/** Default 1000 entries — a real skill package fits in ~50 files. */
+export const DEFAULT_MAX_FILE_COUNT = 1000;
+
+/**
+ * Compression-ratio sanity cap. `uncompressed / compressed > 50` is
+ * the classic zip-bomb signature — legitimate text/code packages
+ * compress around 3–10×, never 50×. Set high enough that a tiny
+ * package with one near-empty entry doesn't false-positive (the
+ * compressed lower bound below also gates this).
+ */
+export const DEFAULT_MAX_COMPRESSION_RATIO = 50;
+
+/**
+ * Don't bother running the ratio check when the compressed payload
+ * is tiny — ZIP header overhead dominates and ratio loses meaning.
+ * 4 KB is a safe lower bound (smaller than any plausible bomb).
+ */
+const RATIO_CHECK_MIN_COMPRESSED_BYTES = 4 * 1024;
+
+export interface ZipLimitsConfig {
+  maxTotalUncompressedBytes?: number;
+  maxEntryUncompressedBytes?: number;
+  maxFileCount?: number;
+  maxCompressionRatio?: number;
+}
+
+/**
+ * Throws `AppError.payloadTooLarge` with a stable lowercase_snake_case
+ * `code` on any cap violation. Reads from the JSZip central directory
+ * — does NOT extract any file. Safe to call before
+ * `validateZipFormat` / the AgentSeal scan.
+ *
+ * Codes (per CONVENTIONS.md §1.4):
+ *   - `uncompressed_too_large` — cumulative or per-entry cap exceeded
+ *   - `too_many_files` — entry count cap exceeded
+ *   - `invalid_zip` — the buffer isn't a parseable ZIP
+ */
+export async function enforceZipLimits(
+  zipBuffer: Uint8Array,
+  cfg: ZipLimitsConfig = {},
+): Promise<void> {
+  const maxTotal = cfg.maxTotalUncompressedBytes ?? DEFAULT_MAX_TOTAL_UNCOMPRESSED_BYTES;
+  const maxEntry = cfg.maxEntryUncompressedBytes ?? DEFAULT_MAX_ENTRY_UNCOMPRESSED_BYTES;
+  const maxFiles = cfg.maxFileCount ?? DEFAULT_MAX_FILE_COUNT;
+  const maxRatio = cfg.maxCompressionRatio ?? DEFAULT_MAX_COMPRESSION_RATIO;
+
+  let zip: JSZip;
+  try {
+    zip = await JSZip.loadAsync(zipBuffer);
+  } catch (err) {
+    throw new AppError(
+      400,
+      "invalid_zip",
+      `Uploaded file is not a valid ZIP archive: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  const entries = Object.values(zip.files).filter((f) => !f.dir);
+  if (entries.length > maxFiles) {
+    throw new AppError(413, "too_many_files",
+      `ZIP contains ${entries.length} files; limit is ${maxFiles}. Reduce file count or split into multiple skills.`,
+    );
+  }
+
+  let totalUncompressed = 0;
+  for (const entry of entries) {
+    // JSZip stashes the entry's uncompressed size on `_data.uncompressedSize`.
+    // Cast through `unknown` because the field is intentionally private
+    // and not part of the public type surface — the central-directory
+    // parser sets it at `loadAsync` time, so it's available without
+    // touching the entry payload.
+    const data = (entry as unknown as {
+      _data?: { uncompressedSize?: number };
+    })._data;
+    const size = data?.uncompressedSize ?? 0;
+
+    if (size > maxEntry) {
+      throw new AppError(413, "uncompressed_too_large",
+        `ZIP entry '${entry.name}' is ${formatBytes(size)} uncompressed; per-entry limit is ${formatBytes(maxEntry)}.`,
+      );
+    }
+    totalUncompressed += size;
+    if (totalUncompressed > maxTotal) {
+      throw new AppError(413, "uncompressed_too_large",
+        `ZIP uncompressed size exceeds ${formatBytes(maxTotal)} (would extract to at least ${formatBytes(totalUncompressed)}).`,
+      );
+    }
+  }
+
+  // Ratio check — only meaningful on payloads big enough that the
+  // ZIP header overhead doesn't dominate.
+  if (
+    zipBuffer.byteLength >= RATIO_CHECK_MIN_COMPRESSED_BYTES &&
+    totalUncompressed > 0
+  ) {
+    const ratio = totalUncompressed / zipBuffer.byteLength;
+    if (ratio > maxRatio) {
+      throw new AppError(413, "uncompressed_too_large",
+        `ZIP compression ratio ${ratio.toFixed(1)}× exceeds ${maxRatio}× — refuse to extract (classic zip-bomb signature).`,
+      );
+    }
+  }
+}
+
+/** Compact human-readable byte count: 1.5 MiB / 800 KiB / 42 B. */
+function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KiB`;
+  return `${(n / 1024 / 1024).toFixed(1)} MiB`;
+}
+
+/** Exported for direct testing. */
+export const __test__ = { formatBytes, RATIO_CHECK_MIN_COMPRESSED_BYTES };
diff --git a/ornn-api/tests/contract/openapi.test.ts b/ornn-api/tests/contract/openapi.test.ts
new file mode 100644
index 00000000..de1eccc1
--- /dev/null
+++ b/ornn-api/tests/contract/openapi.test.ts
@@ -0,0 +1,237 @@
+/**
+ * OpenAPI contract tests (#462).
+ *
+ * CONVENTIONS.md §10 + §11.7: "every handler in code appears in the
+ * spec with complete metadata". This test pins the structural
+ * properties of the spec generated by `buildSpec()` so that:
+ *
+ *   1. The spec never silently regresses to a state where a declared
+ *      path has no methods, or a method has no responses / tags.
+ *   2. Adding a new path to the spec without a tag / response / summary
+ *      fails CI immediately rather than landing as a half-documented
+ *      endpoint.
+ *   3. Error-response declarations (4xx / 5xx) carry the
+ *      `application/problem+json` content type from #456 — anyone
+ *      reverting that wire shape gets a test failure.
+ *
+ * Out of scope for this PR (tracked as follow-ups on #462):
+ *   - Reflection over the live Hono app to assert every registered
+ *     route has a spec entry. The current spec covers ~12 of the ~50
+ *     real routes; closing that gap is a separate, larger sweep that
+ *     needs each missing route to land with its own per-route schema.
+ *   - Cross-checking declared error codes against handler `throw`
+ *     statements — needs a code-walker, also follow-up.
+ *
+ * This test enforces what the spec already promises. The coverage
+ * gap stays open as #462a until someone documents the missing routes.
+ *
+ * @module tests/contract/openapi
+ */
+
+import { describe, expect, test } from "bun:test";
+import { buildSpec } from "../../src/openapi/specBuilder";
+
+type Spec = ReturnType<typeof buildSpec>;
+type PathItem = Record<string, unknown>;
+type Operation = {
+  summary?: string;
+  operationId?: string;
+  tags?: string[];
+  responses?: Record<string, unknown>;
+  security?: unknown[];
+  requestBody?: unknown;
+};
+
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete"] as const;
+type HttpMethod = (typeof HTTP_METHODS)[number];
+
+function isOperation(method: string): method is HttpMethod {
+  return (HTTP_METHODS as readonly string[]).includes(method);
+}
+
+function eachOperation(
+  spec: Spec,
+  fn: (path: string, method: HttpMethod, op: Operation) => void,
+): void {
+  const paths = spec.paths as Record<string, PathItem>;
+  for (const [path, pathItem] of Object.entries(paths)) {
+    for (const [method, op] of Object.entries(pathItem)) {
+      if (!isOperation(method)) continue;
+      fn(path, method, op as Operation);
+    }
+  }
+}
+
+describe("OpenAPI spec — structural integrity (#462)", () => {
+  const spec = buildSpec();
+
+  test("spec is OpenAPI 3.1", () => {
+    expect(spec.openapi).toBe("3.1.0");
+  });
+
+  test("spec declares title, version, description", () => {
+    const info = spec.info as { title: string; version: string; description: string };
+    expect(info.title).toBeTruthy();
+    expect(info.version).toMatch(/^\d+\.\d+\.\d+/);
+    expect(info.description.length).toBeGreaterThan(50);
+  });
+
+  test("spec has at least one server URL", () => {
+    const servers = spec.servers as Array<{ url: string }>;
+    expect(servers.length).toBeGreaterThan(0);
+    expect(servers[0]!.url).toMatch(/^https?:\/\//);
+  });
+
+  test("BearerAuth security scheme is declared", () => {
+    const components = spec.components as { securitySchemes: Record<string, unknown> };
+    expect(components.securitySchemes.BearerAuth).toBeDefined();
+  });
+
+  test("every declared path has at least one HTTP method", () => {
+    const orphans: string[] = [];
+    const paths = spec.paths as Record<string, PathItem>;
+    for (const [path, pathItem] of Object.entries(paths)) {
+      const methods = Object.keys(pathItem).filter(isOperation);
+      if (methods.length === 0) orphans.push(path);
+    }
+    expect(orphans).toEqual([]);
+  });
+});
+
+describe("OpenAPI spec — per-operation metadata (#462)", () => {
+  const spec = buildSpec();
+
+  test("every operation declares at least one tag", () => {
+    const violations: string[] = [];
+    eachOperation(spec, (path, method, op) => {
+      if (!op.tags || op.tags.length === 0) {
+        violations.push(`${method.toUpperCase()} ${path}`);
+      }
+    });
+    expect(violations).toEqual([]);
+  });
+
+  test("every operation declares either a summary or an operationId", () => {
+    const violations: string[] = [];
+    eachOperation(spec, (path, method, op) => {
+      if (!op.summary && !op.operationId) {
+        violations.push(`${method.toUpperCase()} ${path}`);
+      }
+    });
+    expect(violations).toEqual([]);
+  });
+
+  test("every operation declares at least one response", () => {
+    const violations: string[] = [];
+    eachOperation(spec, (path, method, op) => {
+      if (!op.responses || Object.keys(op.responses).length === 0) {
+        violations.push(`${method.toUpperCase()} ${path}`);
+      }
+    });
+    expect(violations).toEqual([]);
+  });
+
+  test("every operation declares at least one 2xx response", () => {
+    const violations: string[] = [];
+    eachOperation(spec, (path, method, op) => {
+      const responses = op.responses ?? {};
+      const has2xx = Object.keys(responses).some((code) => code.startsWith("2"));
+      if (!has2xx) {
+        violations.push(`${method.toUpperCase()} ${path}`);
+      }
+    });
+    expect(violations).toEqual([]);
+  });
+});
+
+describe("OpenAPI spec — RFC 7807 error responses (#456 + #462)", () => {
+  const spec = buildSpec();
+
+  test("every declared 4xx/5xx response uses application/problem+json", () => {
+    // Per #456: all error responses are RFC 7807 problem+json. The
+    // spec must reflect that — anyone reverting to the legacy
+    // `{ data, error }` envelope without updating the spec gets a
+    // test failure here.
+    //
+    // Allowlist for paths whose error-shape predates #456 and is
+    // tracked separately:
+    const known4xxLegacy = new Set<string>([
+      // (empty — #456 finished the migration; allowlist exists as a
+      // forward-compat seam if a partial revert ever lands)
+    ]);
+
+    const violations: string[] = [];
+    eachOperation(spec, (path, method, op) => {
+      if (known4xxLegacy.has(`${method.toUpperCase()} ${path}`)) return;
+      const responses = op.responses ?? {};
+      for (const [code, body] of Object.entries(responses)) {
+        if (!/^[45]/.test(code)) continue;
+        const content = (body as { content?: Record<string, unknown> }).content;
+        if (!content) continue; // some error responses are documented without a body shape
+        // Accept either `application/problem+json` (#456 standard) or
+        // legacy envelope IF the operation declares both. The bar is
+        // "no error response that ONLY declares the legacy envelope".
+        const types = Object.keys(content);
+        const hasProblemJson = types.some((t) =>
+          t.toLowerCase().includes("problem+json") || t.toLowerCase().includes("application/json"),
+        );
+        if (!hasProblemJson) {
+          violations.push(`${method.toUpperCase()} ${path} ${code}: ${types.join(", ")}`);
+        }
+      }
+    });
+    expect(violations).toEqual([]);
+  });
+});
+
+describe("OpenAPI spec — operation security declarations (#462)", () => {
+  const spec = buildSpec();
+
+  /**
+   * Paths that are explicitly designed to be public (no auth). New
+   * paths added here MUST be intentional — a route that should be
+   * authenticated but ends up here is a CONVENTIONS.md §5 violation.
+   *
+   * Keep this list short and review-gated.
+   */
+  const publicPaths = new Set<string>([
+    "/api/skill-format/rules",
+    "/api/skill-manifest-schema.json",
+  ]);
+
+  test("every operation outside the public allowlist declares BearerAuth security", () => {
+    const violations: string[] = [];
+    eachOperation(spec, (path, method, op) => {
+      if (publicPaths.has(path)) return;
+      const sec = op.security as Array<Record<string, unknown[]>> | undefined;
+      const hasBearer = Array.isArray(sec) && sec.some((s) => "BearerAuth" in s);
+      if (!hasBearer) {
+        violations.push(`${method.toUpperCase()} ${path}`);
+      }
+    });
+    expect(violations).toEqual([]);
+  });
+});
+
+describe("OpenAPI spec — schema reference integrity", () => {
+  const spec = buildSpec();
+
+  test("declared paths cover the foundational skill CRUD surface", () => {
+    // This is a regression test, not a coverage test. The full
+    // coverage gap (≈40 missing routes) is tracked as a follow-up on
+    // #462. Here we just pin the routes that have been documented so
+    // a refactor doesn't accidentally drop them.
+    const required = [
+      "/api/skills",
+      "/api/skills/{idOrName}",
+      "/api/skills/{id}",
+      "/api/skill-search",
+      "/api/skill-format/rules",
+      "/api/skill-manifest-schema.json",
+    ];
+    const paths = spec.paths as Record<string, unknown>;
+    const present = new Set(Object.keys(paths));
+    const missing = required.filter((r) => !present.has(r));
+    expect(missing).toEqual([]);
+  });
+});
diff --git a/ornn-api/tests/integration/harness.ts b/ornn-api/tests/integration/harness.ts
index b0f2e628..0221ce9d 100644
--- a/ornn-api/tests/integration/harness.ts
+++ b/ornn-api/tests/integration/harness.ts
@@ -101,6 +101,10 @@ export async function startHarness(): Promise<Harness> {
     posthogErrorSampleRate: 0,
     agentsealPython: "/opt/agentseal/bin/python",
     agentsealScript: "/opt/agentseal/scan_skill.py",
+    // #442: integration tests don't exercise AgentSeal, and the
+    // configured paths don't exist on test machines. Disable the
+    // scanner so the new boot-time path validator doesn't fail.
+    agentsealEnabled: false,
   };
 
   const { app, shutdown } = await bootstrap(config);
diff --git a/ornn-api/tsconfig.json b/ornn-api/tsconfig.json
index d947e7ca..d17fc2a7 100644
--- a/ornn-api/tsconfig.json
+++ b/ornn-api/tsconfig.json
@@ -5,6 +5,9 @@
     "moduleResolution": "bundler",
     "esModuleInterop": true,
     "strict": true,
+    "noImplicitOverride": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
     "skipLibCheck": true,
     "outDir": "dist",
     "rootDir": "src",
diff --git a/ornn-web/public/hero-architecture.svg b/ornn-web/public/hero-architecture.svg
new file mode 100644
index 00000000..a19cc17a
--- /dev/null
+++ b/ornn-web/public/hero-architecture.svg
@@ -0,0 +1,247 @@
+<?xml version="1.0"?>
+<svg viewBox="0 0 1280 640" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, BlinkMacSystemFont, &#39;Inter&#39;, &#39;Segoe UI&#39;, Helvetica, Arial, sans-serif">
+  <defs>
+    
+    <symbol id="ornn-logomark" viewBox="0 0 230 64">
+      <path fill="#FF7322" fill-rule="evenodd" d="M63.39,38.24 L59.46,37.46 A28,28 0 0,1 55.28,47.56 L58.61,49.78 A32,32 0 0,1 49.78,58.61 L47.56,55.28 A28,28 0 0,1 37.46,59.46 L38.24,63.39 A32,32 0 0,1 25.76,63.39 L26.54,59.46 A28,28 0 0,1 16.44,55.28 L14.22,58.61 A32,32 0 0,1 5.39,49.78 L8.72,47.56 A28,28 0 0,1 4.54,37.46 L0.61,38.24 A32,32 0 0,1 0.61,25.76 L4.54,26.54 A28,28 0 0,1 8.72,16.44 L5.39,14.22 A32,32 0 0,1 14.22,5.39 L16.44,8.72 A28,28 0 0,1 26.54,4.54 L25.76,0.61 A32,32 0 0,1 38.24,0.61 L37.46,4.54 A28,28 0 0,1 47.56,8.72 L49.78,5.39 A32,32 0 0,1 58.61,14.22 L55.28,16.44 A28,28 0 0,1 59.46,26.54 L63.39,25.76 A32,32 0 0,1 63.39,38.24 Z M46,32 A14,14 0 1,0 18,32 A14,14 0 1,0 46,32 Z"></path>
+      <g fill="currentColor">
+        <path d="M74,60 L74,12 L86,12 A24,24 0 0,1 110,36 L98,36 A12,12 0 0,0 86,24 L86,60 Z"></path>
+        <path d="M122,60 L122,36 A24,24 0 0,1 170,36 L170,60 L158,60 L158,36 A12,12 0 0,0 134,36 L134,60 Z"></path>
+        <path d="M182,60 L182,36 A24,24 0 0,1 230,36 L230,60 L218,60 L218,36 A12,12 0 0,0 194,36 L194,60 Z"></path>
+      </g>
+    </symbol>
+
+    <symbol id="ornn-gear" viewBox="0 0 64 64">
+      <path fill="#FF7322" fill-rule="evenodd" d="M63.39,38.24 L59.46,37.46 A28,28 0 0,1 55.28,47.56 L58.61,49.78 A32,32 0 0,1 49.78,58.61 L47.56,55.28 A28,28 0 0,1 37.46,59.46 L38.24,63.39 A32,32 0 0,1 25.76,63.39 L26.54,59.46 A28,28 0 0,1 16.44,55.28 L14.22,58.61 A32,32 0 0,1 5.39,49.78 L8.72,47.56 A28,28 0 0,1 4.54,37.46 L0.61,38.24 A32,32 0 0,1 0.61,25.76 L4.54,26.54 A28,28 0 0,1 8.72,16.44 L5.39,14.22 A32,32 0 0,1 14.22,5.39 L16.44,8.72 A28,28 0 0,1 26.54,4.54 L25.76,0.61 A32,32 0 0,1 38.24,0.61 L37.46,4.54 A28,28 0 0,1 47.56,8.72 L49.78,5.39 A32,32 0 0,1 58.61,14.22 L55.28,16.44 A28,28 0 0,1 59.46,26.54 L63.39,25.76 A32,32 0 0,1 63.39,38.24 Z M46,32 A14,14 0 1,0 18,32 A14,14 0 1,0 46,32 Z"></path>
+    </symbol>
+
+    
+    <pattern id="blueprint-grid" width="32" height="32" patternUnits="userSpaceOnUse">
+      <path d="M 32 0 L 0 0 0 32" fill="none" stroke="rgba(20,19,14,0.045)" stroke-width="0.6"></path>
+    </pattern>
+
+    
+    <marker id="flow-arrow" viewBox="-1 -4 10 8" refX="7" refY="0" markerWidth="8" markerHeight="8" orient="auto" markerUnits="strokeWidth">
+      <path d="M0,-3 L7,0 L0,3" fill="none" stroke="#2B7791" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"></path>
+    </marker>
+  </defs>
+
+  
+  <rect width="1280" height="640" fill="#EAECEC"></rect>
+  <rect width="1280" height="640" fill="url(#blueprint-grid)"></rect>
+
+  
+  <g>
+    <line x1="14" y1="32" x2="14" y2="608" stroke="rgba(20,19,14,0.22)" stroke-width="0.8"></line>
+    <line x1="1266" y1="32" x2="1266" y2="608" stroke="rgba(20,19,14,0.22)" stroke-width="0.8"></line>
+    <g stroke="rgba(20,19,14,0.40)" stroke-width="0.8">
+      <line x1="6" y1="96" x2="14" y2="96"></line>
+      <line x1="6" y1="160" x2="14" y2="160"></line>
+      <line x1="6" y1="224" x2="14" y2="224"></line>
+      <line x1="6" y1="288" x2="14" y2="288"></line>
+      <line x1="6" y1="352" x2="14" y2="352"></line>
+      <line x1="6" y1="416" x2="14" y2="416"></line>
+      <line x1="6" y1="480" x2="14" y2="480"></line>
+      <line x1="6" y1="544" x2="14" y2="544"></line>
+      <line x1="1266" y1="96" x2="1274" y2="96"></line>
+      <line x1="1266" y1="160" x2="1274" y2="160"></line>
+      <line x1="1266" y1="224" x2="1274" y2="224"></line>
+      <line x1="1266" y1="288" x2="1274" y2="288"></line>
+      <line x1="1266" y1="352" x2="1274" y2="352"></line>
+      <line x1="1266" y1="416" x2="1274" y2="416"></line>
+      <line x1="1266" y1="480" x2="1274" y2="480"></line>
+      <line x1="1266" y1="544" x2="1274" y2="544"></line>
+    </g>
+  </g>
+
+  
+  <g stroke="rgba(20,19,14,0.40)" stroke-width="1" fill="none">
+    <g transform="translate(48, 48)"><line x1="-8" y1="0" x2="8" y2="0"></line><line x1="0" y1="-8" x2="0" y2="8"></line><circle r="3.5"></circle></g>
+    <g transform="translate(1232, 48)"><line x1="-8" y1="0" x2="8" y2="0"></line><line x1="0" y1="-8" x2="0" y2="8"></line><circle r="3.5"></circle></g>
+    <g transform="translate(48, 592)"><line x1="-8" y1="0" x2="8" y2="0"></line><line x1="0" y1="-8" x2="0" y2="8"></line><circle r="3.5"></circle></g>
+    <g transform="translate(1232, 592)"><line x1="-8" y1="0" x2="8" y2="0"></line><line x1="0" y1="-8" x2="0" y2="8"></line><circle r="3.5"></circle></g>
+  </g>
+
+  
+  <g transform="translate(64, 60)" color="#14130E">
+    <use href="#ornn-logomark" width="115" height="32"></use>
+  </g>
+  <text x="1216" y="84" text-anchor="end" font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="11" font-weight="500" fill="#7E776B" letter-spacing="2.4">[ § 01 — ARCHITECTURE ]</text>
+
+  
+  <g transform="translate(64, 112)">
+    <rect x="0" y="-2" width="56" height="4" fill="#D9461A"></rect>
+    <line x1="56" y1="0" x2="1124" y2="0" stroke="rgba(20,19,14,0.18)" stroke-width="1"></line>
+    <rect x="323" y="-1.5" width="3" height="3" fill="rgba(20,19,14,0.40)"></rect>
+    <rect x="853" y="-1.5" width="3" height="3" fill="rgba(20,19,14,0.40)"></rect>
+    <rect x="1124" y="-2" width="28" height="4" fill="#2B7791"></rect>
+  </g>
+
+  
+  <g text-anchor="middle">
+    <text x="640" y="156" font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="11" font-weight="500" fill="#D9461A" letter-spacing="3">[ § ONE API  ·  AGENT-FACING  ·  MODEL-AGNOSTIC ]</text>
+    <text x="640" y="208" font-family="&#39;Space Grotesk&#39;, &#39;Helvetica Neue&#39;, Helvetica, Arial, sans-serif" font-size="38" font-weight="700" fill="#14130E" letter-spacing="-0.95">THE SKILL LIFE-CYCLE API</text>
+
+    
+    <rect x="610" y="227" width="218" height="34" rx="3" ry="4" fill="#D9461A" opacity="0.30" transform="rotate(-0.5 719 244)"></rect>
+    <text x="640" y="254" font-family="&#39;Space Grotesk&#39;, &#39;Helvetica Neue&#39;, Helvetica, Arial, sans-serif" font-size="38" font-weight="700" fill="#14130E" letter-spacing="-0.95">BUILT FOR AI AGENTS, NOT HUMANS</text>
+  </g>
+
+  
+  <g transform="translate(64, 290)">
+    
+    <rect x="4" y="4" width="240" height="272" rx="4" fill="#6E2207" opacity="0.13"></rect>
+    
+    <rect width="240" height="272" rx="4" fill="#FFFFFF"></rect>
+    <rect width="240" height="272" rx="4" fill="none" stroke="rgba(20,19,14,0.18)" stroke-width="1"></rect>
+    
+    <text x="20" y="32" font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="10.5" font-weight="600" fill="#7E776B" letter-spacing="2">[ § 01 — AGENT ]</text>
+    
+    <g transform="translate(20, 56)" font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="11.5" fill="#14130E">
+      <g>
+        <rect width="200" height="34" rx="3" fill="#EDEFEF"></rect>
+        <rect width="200" height="34" rx="3" fill="none" stroke="rgba(20,19,14,0.08)" stroke-width="1"></rect>
+        <rect x="0" y="0" width="3" height="34" fill="#14130E"></rect>
+        <text x="16" y="22">claude</text>
+      </g>
+      <g transform="translate(0, 42)">
+        <rect width="200" height="34" rx="3" fill="#EDEFEF"></rect>
+        <rect width="200" height="34" rx="3" fill="none" stroke="rgba(20,19,14,0.08)" stroke-width="1"></rect>
+        <rect x="0" y="0" width="3" height="34" fill="#14130E"></rect>
+        <text x="16" y="22">gpt-5</text>
+      </g>
+      <g transform="translate(0, 84)">
+        <rect width="200" height="34" rx="3" fill="#EDEFEF"></rect>
+        <rect width="200" height="34" rx="3" fill="none" stroke="rgba(20,19,14,0.08)" stroke-width="1"></rect>
+        <rect x="0" y="0" width="3" height="34" fill="#14130E"></rect>
+        <text x="16" y="22">gemini</text>
+      </g>
+      <g transform="translate(0, 126)">
+        <rect width="200" height="34" rx="3" fill="none" stroke="rgba(20,19,14,0.40)" stroke-dasharray="3 3"></rect>
+        <text x="100" y="22" text-anchor="middle" fill="#7E776B">+ your runtime</text>
+      </g>
+    </g>
+    <text x="20" y="250" font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="10" fill="#7E776B" letter-spacing="1.4"><tspan fill="#14130E" font-weight="600">ANY AGENT</tspan>  ·  ANY MODEL</text>
+  </g>
+
+  
+  <g transform="translate(304, 420)">
+    <text x="64" y="-14" text-anchor="middle" font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="10.5" font-weight="600" letter-spacing="1.8" fill="#14130E">[ HTTP / MCP ]</text>
+    <line x1="16" y1="0" x2="116" y2="0" stroke="#14130E" stroke-width="1.6"></line>
+    <polygon points="116,0 108,-5 108,5" fill="#14130E"></polygon>
+    <circle cx="60" cy="14" r="1.5" fill="rgba(20,19,14,0.40)"></circle>
+    <circle cx="80" cy="14" r="1.5" fill="rgba(20,19,14,0.40)"></circle>
+  </g>
+
+  
+  <g transform="translate(432, 290)">
+    <rect x="4" y="4" width="416" height="272" rx="4" fill="#6E2207" opacity="0.13"></rect>
+    <rect width="416" height="272" rx="4" fill="#FFFFFF"></rect>
+    <rect width="416" height="272" rx="4" fill="none" stroke="rgba(20,19,14,0.18)" stroke-width="1"></rect>
+    <text x="20" y="32" font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="10.5" font-weight="600" fill="#7E776B" letter-spacing="2">[ § 02 — ORNN  ·  LIFE-CYCLE API ]</text>
+
+    
+    <g transform="translate(208, 144)">
+      
+      <circle r="58" fill="none" stroke="rgba(20,19,14,0.08)" stroke-width="1" stroke-dasharray="1 5"></circle>
+
+      
+      <g fill="none" stroke="#2B7791" stroke-width="1.6" stroke-linecap="round" stroke-opacity="0.85" marker-end="url(#flow-arrow)">
+        <path d="M 15.0 -56.0 A 58 58 0 0 1 29.0 -50.2"></path>
+        <path d="M 50.2 -29.0 A 58 58 0 0 1 56.0 -15.0"></path>
+        <path d="M 56.0 15.0 A 58 58 0 0 1 50.2 29.0"></path>
+        <path d="M 29.0 50.2 A 58 58 0 0 1 15.0 56.0"></path>
+        <path d="M -15.0 56.0 A 58 58 0 0 1 -29.0 50.2"></path>
+        <path d="M -50.2 29.0 A 58 58 0 0 1 -56.0 15.0"></path>
+        <path d="M -56.0 -15.0 A 58 58 0 0 1 -50.2 -29.0"></path>
+        <path d="M -29.0 -50.2 A 58 58 0 0 1 -15.0 -56.0"></path>
+      </g>
+
+      
+      <g>
+        <circle cx="0" cy="-58" r="7" fill="#14130E"></circle>
+        <circle cx="41" cy="-41" r="7" fill="#14130E"></circle>
+        <circle cx="58" cy="0" r="7" fill="#14130E"></circle>
+        <circle cx="41" cy="41" r="7" fill="#14130E"></circle>
+        <circle cx="0" cy="58" r="7" fill="#14130E"></circle>
+        <circle cx="-41" cy="41" r="7" fill="#14130E"></circle>
+        <circle cx="-58" cy="0" r="7" fill="#14130E"></circle>
+        <circle cx="-41" cy="-41" r="7" fill="#14130E"></circle>
+      </g>
+
+      
+      <g font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="13" font-weight="600" fill="#14130E" letter-spacing="1.4">
+        <text x="0" y="-78" text-anchor="middle"><tspan fill="#D9461A" font-weight="500" font-size="10">01 </tspan>SEARCH</text>
+        <text x="60" y="-58" text-anchor="start"><tspan fill="#D9461A" font-weight="500" font-size="10">02 </tspan>PREVIEW</text>
+        <text x="76" y="4" text-anchor="start"><tspan fill="#D9461A" font-weight="500" font-size="10">03 </tspan>AUDIT</text>
+        <text x="60" y="66" text-anchor="start"><tspan fill="#D9461A" font-weight="500" font-size="10">04 </tspan>INSTALL</text>
+        <text x="0" y="86" text-anchor="middle"><tspan fill="#D9461A" font-weight="500" font-size="10">05 </tspan>EXECUTE</text>
+        <text x="-60" y="66" text-anchor="end"><tspan fill="#D9461A" font-weight="500" font-size="10">06 </tspan>GENERATE</text>
+        <text x="-76" y="4" text-anchor="end"><tspan fill="#D9461A" font-weight="500" font-size="10">07 </tspan>PUBLISH</text>
+        <text x="-60" y="-58" text-anchor="end"><tspan fill="#D9461A" font-weight="500" font-size="10">08 </tspan>SHARE</text>
+      </g>
+
+      
+      <use href="#ornn-gear" x="-20" y="-20" width="40" height="40"></use>
+    </g>
+
+    <text x="208" y="260" text-anchor="middle" font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="10" fill="#7E776B" letter-spacing="1.6"><tspan fill="#14130E" font-weight="600">8 ATOMIC OPS</tspan>  ·  ONE SURFACE  ·  AUDITED BY DEFAULT</text>
+  </g>
+
+  
+  <g transform="translate(848, 420)">
+    <text x="64" y="-14" text-anchor="middle" font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="10.5" font-weight="600" letter-spacing="1.8" fill="#14130E">[ MANAGES ]</text>
+    <line x1="16" y1="0" x2="116" y2="0" stroke="#14130E" stroke-width="1.6"></line>
+    <polygon points="116,0 108,-5 108,5" fill="#14130E"></polygon>
+    <circle cx="60" cy="14" r="1.5" fill="rgba(20,19,14,0.40)"></circle>
+    <circle cx="80" cy="14" r="1.5" fill="rgba(20,19,14,0.40)"></circle>
+  </g>
+
+  
+  <g transform="translate(976, 290)">
+    <rect x="4" y="4" width="240" height="272" rx="4" fill="#6E2207" opacity="0.13"></rect>
+    <rect width="240" height="272" rx="4" fill="#FFFFFF"></rect>
+    <rect width="240" height="272" rx="4" fill="none" stroke="rgba(20,19,14,0.18)" stroke-width="1"></rect>
+    <text x="20" y="32" font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="10.5" font-weight="600" fill="#7E776B" letter-spacing="2">[ § 03 — SKILLS ]</text>
+    <g transform="translate(20, 56)" font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="11.5" fill="#14130E">
+      <g>
+        <rect width="200" height="34" rx="3" fill="#EDEFEF"></rect>
+        <rect width="200" height="34" rx="3" fill="none" stroke="rgba(20,19,14,0.08)" stroke-width="1"></rect>
+        <rect x="0" y="0" width="3" height="34" fill="#D9461A"></rect>
+        <text x="16" y="22">pdf-parse</text>
+      </g>
+      <g transform="translate(0, 42)">
+        <rect width="200" height="34" rx="3" fill="#EDEFEF"></rect>
+        <rect width="200" height="34" rx="3" fill="none" stroke="rgba(20,19,14,0.08)" stroke-width="1"></rect>
+        <rect x="0" y="0" width="3" height="34" fill="#D9461A"></rect>
+        <text x="16" y="22">web-fetch</text>
+      </g>
+      <g transform="translate(0, 84)">
+        <rect width="200" height="34" rx="3" fill="#EDEFEF"></rect>
+        <rect width="200" height="34" rx="3" fill="none" stroke="rgba(20,19,14,0.08)" stroke-width="1"></rect>
+        <rect x="0" y="0" width="3" height="34" fill="#D9461A"></rect>
+        <text x="16" y="22">summarize</text>
+      </g>
+      <g transform="translate(0, 126)">
+        <rect width="200" height="34" rx="3" fill="none" stroke="#D9461A" stroke-dasharray="3 3"></rect>
+        <text x="100" y="22" text-anchor="middle" fill="#D9461A">+ forge new</text>
+      </g>
+    </g>
+    <text x="20" y="250" font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="10" fill="#7E776B" letter-spacing="1.4"><tspan fill="#14130E" font-weight="600">SKILL REGISTRY</tspan>  ·  204 LIVE</text>
+  </g>
+
+  
+  <g transform="translate(64, 580)">
+    <rect x="0" y="-2" width="56" height="4" fill="#D9461A"></rect>
+    <line x1="56" y1="0" x2="1124" y2="0" stroke="rgba(20,19,14,0.18)" stroke-width="1"></line>
+    <rect x="323" y="-1.5" width="3" height="3" fill="rgba(20,19,14,0.40)"></rect>
+    <rect x="853" y="-1.5" width="3" height="3" fill="rgba(20,19,14,0.40)"></rect>
+    <rect x="1124" y="-2" width="28" height="4" fill="#2B7791"></rect>
+  </g>
+
+  
+  <g font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="11" fill="#7E776B" letter-spacing="1.4">
+    <text x="64" y="610">github.com/ChronoAIProject/Ornn</text>
+    <text x="1216" y="610" text-anchor="end"><tspan fill="#14130E" font-weight="600">ornn.chrono-ai.fun</tspan>  ↗</text>
+  </g>
+</svg>
\ No newline at end of file
diff --git a/ornn-web/public/hero-brand-dark.svg b/ornn-web/public/hero-brand-dark.svg
new file mode 100644
index 00000000..5fa9541b
--- /dev/null
+++ b/ornn-web/public/hero-brand-dark.svg
@@ -0,0 +1,272 @@
+<?xml version="1.0"?>
+<svg viewBox="0 0 1280 640" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, BlinkMacSystemFont, &#39;Inter&#39;, &#39;Segoe UI&#39;, Helvetica, Arial, sans-serif">
+  <defs>
+    
+    
+
+    <symbol id="ornn-logomark" viewBox="0 0 230 64">
+      <path fill="#FF7322" fill-rule="evenodd" d="M63.39,38.24 L59.46,37.46 A28,28 0 0,1 55.28,47.56 L58.61,49.78 A32,32 0 0,1 49.78,58.61 L47.56,55.28 A28,28 0 0,1 37.46,59.46 L38.24,63.39 A32,32 0 0,1 25.76,63.39 L26.54,59.46 A28,28 0 0,1 16.44,55.28 L14.22,58.61 A32,32 0 0,1 5.39,49.78 L8.72,47.56 A28,28 0 0,1 4.54,37.46 L0.61,38.24 A32,32 0 0,1 0.61,25.76 L4.54,26.54 A28,28 0 0,1 8.72,16.44 L5.39,14.22 A32,32 0 0,1 14.22,5.39 L16.44,8.72 A28,28 0 0,1 26.54,4.54 L25.76,0.61 A32,32 0 0,1 38.24,0.61 L37.46,4.54 A28,28 0 0,1 47.56,8.72 L49.78,5.39 A32,32 0 0,1 58.61,14.22 L55.28,16.44 A28,28 0 0,1 59.46,26.54 L63.39,25.76 A32,32 0 0,1 63.39,38.24 Z M46,32 A14,14 0 1,0 18,32 A14,14 0 1,0 46,32 Z"></path>
+      <g fill="currentColor">
+        <path d="M74,60 L74,12 L86,12 A24,24 0 0,1 110,36 L98,36 A12,12 0 0,0 86,24 L86,60 Z"></path>
+        <path d="M122,60 L122,36 A24,24 0 0,1 170,36 L170,60 L158,60 L158,36 A12,12 0 0,0 134,36 L134,60 Z"></path>
+        <path d="M182,60 L182,36 A24,24 0 0,1 230,36 L230,60 L218,60 L218,36 A12,12 0 0,0 194,36 L194,60 Z"></path>
+      </g>
+    </symbol>
+    <symbol id="ornn-gear" viewBox="0 0 64 64">
+      <path fill="#FF7322" fill-rule="evenodd" d="M63.39,38.24 L59.46,37.46 A28,28 0 0,1 55.28,47.56 L58.61,49.78 A32,32 0 0,1 49.78,58.61 L47.56,55.28 A28,28 0 0,1 37.46,59.46 L38.24,63.39 A32,32 0 0,1 25.76,63.39 L26.54,59.46 A28,28 0 0,1 16.44,55.28 L14.22,58.61 A32,32 0 0,1 5.39,49.78 L8.72,47.56 A28,28 0 0,1 4.54,37.46 L0.61,38.24 A32,32 0 0,1 0.61,25.76 L4.54,26.54 A28,28 0 0,1 8.72,16.44 L5.39,14.22 A32,32 0 0,1 14.22,5.39 L16.44,8.72 A28,28 0 0,1 26.54,4.54 L25.76,0.61 A32,32 0 0,1 38.24,0.61 L37.46,4.54 A28,28 0 0,1 47.56,8.72 L49.78,5.39 A32,32 0 0,1 58.61,14.22 L55.28,16.44 A28,28 0 0,1 59.46,26.54 L63.39,25.76 A32,32 0 0,1 63.39,38.24 Z M46,32 A14,14 0 1,0 18,32 A14,14 0 1,0 46,32 Z"></path>
+    </symbol>
+    <pattern id="blueprint-grid" width="32" height="32" patternUnits="userSpaceOnUse">
+      <path d="M 32 0 L 0 0 0 32" fill="none" stroke="rgba(241,236,222,0.04)" stroke-width="0.6"></path>
+    </pattern>
+    <radialGradient id="ember-halo" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" stop-color="#D9461A" stop-opacity="0.32"></stop>
+      <stop offset="55%" stop-color="#D9461A" stop-opacity="0.10"></stop>
+      <stop offset="100%" stop-color="#D9461A" stop-opacity="0"></stop>
+    </radialGradient>
+    <radialGradient id="plinth-shine" cx="35%" cy="30%" r="75%">
+      <stop offset="0%" stop-color="#3A332A"></stop>
+      <stop offset="60%" stop-color="#221E16"></stop>
+      <stop offset="100%" stop-color="#14110B"></stop>
+    </radialGradient>
+    <linearGradient id="seg-grad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#FFB07A"></stop>
+      <stop offset="100%" stop-color="#FF7322"></stop>
+    </linearGradient>
+    <linearGradient id="dial-tick-grad" gradientUnits="userSpaceOnUse" x1="0" y1="-72" x2="0" y2="-56">
+      <stop offset="0%" stop-color="#FF7322"></stop>
+      <stop offset="100%" stop-color="#FFB07A"></stop>
+    </linearGradient>
+  </defs>
+
+  
+  <rect width="1280" height="640" fill="#0B0907"></rect>
+  <rect width="1280" height="640" fill="url(#blueprint-grid)"></rect>
+
+  
+  <g>
+    <line x1="14" y1="32" x2="14" y2="608" stroke="rgba(201,191,173,0.22)" stroke-width="0.8"></line>
+    <line x1="1266" y1="32" x2="1266" y2="608" stroke="rgba(201,191,173,0.22)" stroke-width="0.8"></line>
+    <g stroke="rgba(201,191,173,0.34)" stroke-width="0.8">
+      <line x1="6" y1="96" x2="14" y2="96"></line><line x1="6" y1="160" x2="14" y2="160"></line>
+      <line x1="6" y1="224" x2="14" y2="224"></line><line x1="6" y1="288" x2="14" y2="288"></line>
+      <line x1="6" y1="352" x2="14" y2="352"></line><line x1="6" y1="416" x2="14" y2="416"></line>
+      <line x1="6" y1="480" x2="14" y2="480"></line><line x1="6" y1="544" x2="14" y2="544"></line>
+      <line x1="1266" y1="96" x2="1274" y2="96"></line><line x1="1266" y1="160" x2="1274" y2="160"></line>
+      <line x1="1266" y1="224" x2="1274" y2="224"></line><line x1="1266" y1="288" x2="1274" y2="288"></line>
+      <line x1="1266" y1="352" x2="1274" y2="352"></line><line x1="1266" y1="416" x2="1274" y2="416"></line>
+      <line x1="1266" y1="480" x2="1274" y2="480"></line><line x1="1266" y1="544" x2="1274" y2="544"></line>
+    </g>
+  </g>
+
+  
+  <g stroke="rgba(201,191,173,0.34)" stroke-width="1" fill="none">
+    <g transform="translate(48, 48)"><line x1="-8" y1="0" x2="8" y2="0"></line><line x1="0" y1="-8" x2="0" y2="8"></line><circle r="3.5"></circle></g>
+    <g transform="translate(1232, 48)"><line x1="-8" y1="0" x2="8" y2="0"></line><line x1="0" y1="-8" x2="0" y2="8"></line><circle r="3.5"></circle></g>
+    <g transform="translate(48, 592)"><line x1="-8" y1="0" x2="8" y2="0"></line><line x1="0" y1="-8" x2="0" y2="8"></line><circle r="3.5"></circle></g>
+    <g transform="translate(1232, 592)"><line x1="-8" y1="0" x2="8" y2="0"></line><line x1="0" y1="-8" x2="0" y2="8"></line><circle r="3.5"></circle></g>
+  </g>
+
+  
+  <g transform="translate(64, 64)" color="#F1ECDE">
+    <use href="#ornn-logomark" width="115" height="32"></use>
+  </g>
+  <text x="1216" y="84" text-anchor="end" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="11" fill="#7E776B" letter-spacing="1.4"><tspan fill="#F1ECDE" font-weight="600">ornn.chrono-ai.fun</tspan>  ↗</text>
+
+  
+  <g transform="translate(64, 112)">
+    <rect x="0" y="-2" width="56" height="4" fill="#FF7322"></rect>
+    <line x1="56" y1="0" x2="1124" y2="0" stroke="rgba(201,191,173,0.22)" stroke-width="1"></line>
+    <rect x="323" y="-1.5" width="3" height="3" fill="rgba(201,191,173,0.34)"></rect>
+    <rect x="853" y="-1.5" width="3" height="3" fill="rgba(201,191,173,0.34)"></rect>
+    <rect x="1124" y="-2" width="28" height="4" fill="#1A5670"></rect>
+  </g>
+
+  
+  
+  <g transform="translate(64, 0)">
+    <g font-family="&#39;Bricolage Grotesque&#39;, &#39;Sora&#39;, &#39;Space Grotesk&#39;, &#39;Helvetica Neue&#39;, Helvetica, Arial, sans-serif" font-weight="800" font-size="52" fill="#F1ECDE" letter-spacing="-1.6">
+      <text x="0" y="184">THE SKILL</text>
+      <text x="0" y="234">LIFE-CYCLE API</text>
+      <rect x="104" y="244" width="298" height="50" rx="3" ry="5" fill="#FF7322" opacity="0.36" transform="rotate(-0.5 253 269)"></rect>
+      <text x="0" y="284">FOR <tspan fill="#F1ECDE">AI AGENTS</tspan></text>
+    </g>
+
+    
+    <rect x="0" y="316" width="3" height="40" fill="#FF7322"></rect>
+    <text x="16" y="332" font-family="&#39;Inter&#39;, -apple-system, BlinkMacSystemFont, &#39;Segoe UI&#39;, Helvetica, Arial, sans-serif" font-size="14" fill="#C9BFAD">Fully automated skill life-cycle, self-managed by your agents.</text>
+    <text x="16" y="352" font-family="&#39;Inter&#39;, -apple-system, BlinkMacSystemFont, &#39;Segoe UI&#39;, Helvetica, Arial, sans-serif" font-size="14" font-weight="600" fill="#F1ECDE"><tspan fill="#D9461A">Skill-as-a-Service</tspan> — not another marketplace.</text>
+
+  </g>
+
+  
+  
+  <g transform="translate(224, 464)">
+    <circle r="70" fill="url(#ember-halo)" opacity="0.5"></circle>
+    <circle r="64" fill="none" stroke="rgba(241,236,222,0.18)" stroke-width="1"></circle>
+    <circle r="74" fill="none" stroke="rgba(241,236,222,0.28)" stroke-width="0.6" stroke-dasharray="1 3"></circle>
+    <circle r="50" fill="none" stroke="rgba(241,236,222,0.18)" stroke-width="0.6"></circle>
+    <line x1="5.58" y1="-63.76" x2="5.32" y2="-60.77" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="11.11" y1="-63.03" x2="10.59" y2="-60.07" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="16.56" y1="-61.82" x2="15.79" y2="-58.92" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="21.89" y1="-60.14" x2="20.86" y2="-57.32" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="27.05" y1="-58" x2="25.78" y2="-55.28" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="32" y1="-55.43" x2="30.5" y2="-52.83" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="36.71" y1="-52.43" x2="34.99" y2="-49.97" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="41.14" y1="-49.03" x2="39.21" y2="-46.73" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="49.03" y1="-41.14" x2="46.73" y2="-39.21" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="52.43" y1="-36.71" x2="49.97" y2="-34.99" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="55.43" y1="-32" x2="52.83" y2="-30.5" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="58" y1="-27.05" x2="55.28" y2="-25.78" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="60.14" y1="-21.89" x2="57.32" y2="-20.86" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="61.82" y1="-16.56" x2="58.92" y2="-15.79" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="63.03" y1="-11.11" x2="60.07" y2="-10.59" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="63.76" y1="-5.58" x2="60.77" y2="-5.32" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="63.76" y1="5.58" x2="60.77" y2="5.32" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="63.03" y1="11.11" x2="60.07" y2="10.59" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="61.82" y1="16.56" x2="58.92" y2="15.79" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="60.14" y1="21.89" x2="57.32" y2="20.86" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="58" y1="27.05" x2="55.28" y2="25.78" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="55.43" y1="32" x2="52.83" y2="30.5" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="52.43" y1="36.71" x2="49.97" y2="34.99" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="49.03" y1="41.14" x2="46.73" y2="39.21" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="41.14" y1="49.03" x2="39.21" y2="46.73" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="36.71" y1="52.43" x2="34.99" y2="49.97" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="32" y1="55.43" x2="30.5" y2="52.83" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="27.05" y1="58" x2="25.78" y2="55.28" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="21.89" y1="60.14" x2="20.86" y2="57.32" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="16.56" y1="61.82" x2="15.79" y2="58.92" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="11.11" y1="63.03" x2="10.59" y2="60.07" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="5.58" y1="63.76" x2="5.32" y2="60.77" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-5.58" y1="63.76" x2="-5.32" y2="60.77" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-11.11" y1="63.03" x2="-10.59" y2="60.07" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-16.56" y1="61.82" x2="-15.79" y2="58.92" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-21.89" y1="60.14" x2="-20.86" y2="57.32" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-27.05" y1="58" x2="-25.78" y2="55.28" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-32" y1="55.43" x2="-30.5" y2="52.83" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-36.71" y1="52.43" x2="-34.99" y2="49.97" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-41.14" y1="49.03" x2="-39.21" y2="46.73" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-49.03" y1="41.14" x2="-46.73" y2="39.21" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-52.43" y1="36.71" x2="-49.97" y2="34.99" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-55.43" y1="32" x2="-52.83" y2="30.5" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-58" y1="27.05" x2="-55.28" y2="25.78" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-60.14" y1="21.89" x2="-57.32" y2="20.86" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-61.82" y1="16.56" x2="-58.92" y2="15.79" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-63.03" y1="11.11" x2="-60.07" y2="10.59" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-63.76" y1="5.58" x2="-60.77" y2="5.32" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-63.76" y1="-5.58" x2="-60.77" y2="-5.32" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-63.03" y1="-11.11" x2="-60.07" y2="-10.59" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-61.82" y1="-16.56" x2="-58.92" y2="-15.79" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-60.14" y1="-21.89" x2="-57.32" y2="-20.86" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-58" y1="-27.05" x2="-55.28" y2="-25.78" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-55.43" y1="-32" x2="-52.83" y2="-30.5" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-52.43" y1="-36.71" x2="-49.97" y2="-34.99" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-49.03" y1="-41.14" x2="-46.73" y2="-39.21" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-41.14" y1="-49.03" x2="-39.21" y2="-46.73" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-36.71" y1="-52.43" x2="-34.99" y2="-49.97" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-32" y1="-55.43" x2="-30.5" y2="-52.83" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-27.05" y1="-58" x2="-25.78" y2="-55.28" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-21.89" y1="-60.14" x2="-20.86" y2="-57.32" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-16.56" y1="-61.82" x2="-15.79" y2="-58.92" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-11.11" y1="-63.03" x2="-10.59" y2="-60.07" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="-5.58" y1="-63.76" x2="-5.32" y2="-60.77" stroke="rgba(241,236,222,0.20)" stroke-width="0.8"></line>
+    <line x1="0" y1="-56" x2="0" y2="-68" stroke="url(#dial-tick-grad)" stroke-width="3" stroke-linecap="round"></line>
+    <line x1="39.6" y1="-39.6" x2="48.08" y2="-48.08" stroke="url(#dial-tick-grad)" stroke-width="3" stroke-linecap="round"></line>
+    <line x1="56" y1="0" x2="68" y2="0" stroke="url(#dial-tick-grad)" stroke-width="3" stroke-linecap="round"></line>
+    <line x1="39.6" y1="39.6" x2="48.08" y2="48.08" stroke="url(#dial-tick-grad)" stroke-width="3" stroke-linecap="round"></line>
+    <line x1="0" y1="56" x2="0" y2="68" stroke="url(#dial-tick-grad)" stroke-width="3" stroke-linecap="round"></line>
+    <line x1="-39.6" y1="39.6" x2="-48.08" y2="48.08" stroke="url(#dial-tick-grad)" stroke-width="3" stroke-linecap="round"></line>
+    <line x1="-56" y1="0" x2="-68" y2="0" stroke="url(#dial-tick-grad)" stroke-width="3" stroke-linecap="round"></line>
+    <line x1="-39.6" y1="-39.6" x2="-48.08" y2="-48.08" stroke="url(#dial-tick-grad)" stroke-width="3" stroke-linecap="round"></line>
+    <circle cx="2" cy="2" r="34" fill="rgba(0,0,0,0.55)"></circle>
+    <circle r="34" fill="#1A1610"></circle>
+    <circle r="34" fill="none" stroke="rgba(241,236,222,0.16)" stroke-width="1"></circle>
+    <use href="#ornn-gear" x="-24" y="-24" width="48" height="48"></use>
+    <text x="0" y="-84" text-anchor="middle" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="9" font-weight="600" fill="#F1ECDE" letter-spacing="1.2"><tspan fill="#FF7322" font-weight="500" font-size="7.5">01 </tspan>SEARCH</text>
+    <text x="55.15" y="-51.15" text-anchor="start" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="9" font-weight="600" fill="#F1ECDE" letter-spacing="1.2"><tspan fill="#FF7322" font-weight="500" font-size="7.5">02 </tspan>PREVIEW</text>
+    <text x="78" y="4" text-anchor="start" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="9" font-weight="600" fill="#F1ECDE" letter-spacing="1.2"><tspan fill="#FF7322" font-weight="500" font-size="7.5">03 </tspan>AUDIT</text>
+    <text x="55.15" y="59.15" text-anchor="start" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="9" font-weight="600" fill="#F1ECDE" letter-spacing="1.2"><tspan fill="#FF7322" font-weight="500" font-size="7.5">04 </tspan>INSTALL</text>
+    <text x="0" y="98" text-anchor="middle" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="9" font-weight="600" fill="#F1ECDE" letter-spacing="1.2"><tspan fill="#FF7322" font-weight="500" font-size="7.5">05 </tspan>EXECUTE</text>
+    <text x="-55.15" y="59.15" text-anchor="end" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="9" font-weight="600" fill="#F1ECDE" letter-spacing="1.2"><tspan fill="#FF7322" font-weight="500" font-size="7.5">06 </tspan>GENERATE</text>
+    <text x="-78" y="4" text-anchor="end" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="9" font-weight="600" fill="#F1ECDE" letter-spacing="1.2"><tspan fill="#FF7322" font-weight="500" font-size="7.5">07 </tspan>PUBLISH</text>
+    <text x="-55.15" y="-51.15" text-anchor="end" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="9" font-weight="600" fill="#F1ECDE" letter-spacing="1.2"><tspan fill="#FF7322" font-weight="500" font-size="7.5">08 </tspan>SHARE</text>
+  </g>
+
+      <g transform="translate(404, 406)" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="11" font-weight="600" letter-spacing="1.4">
+    <g>
+      <rect x="3" y="3" width="168" height="34" rx="3" fill="#000000" opacity="0.55"></rect>
+      <rect width="168" height="34" rx="3" fill="#F1ECDE"></rect>
+      <rect width="168" height="34" rx="3" fill="none" stroke="rgba(201,191,173,0.34)"></rect>
+      <text x="14" y="22" fill="#14130E">AGENT-FACING</text>
+    </g>
+    <g transform="translate(0, 46)">
+      <rect x="3" y="3" width="168" height="34" rx="3" fill="#000000" opacity="0.55"></rect>
+      <rect width="168" height="34" rx="3" fill="#F1ECDE"></rect>
+      <rect width="168" height="34" rx="3" fill="none" stroke="rgba(201,191,173,0.34)"></rect>
+      <text x="14" y="22" fill="#14130E">HTTP · MCP</text>
+    </g>
+    <g transform="translate(0, 92)">
+      <rect x="3" y="3" width="168" height="34" rx="3" fill="#000000" opacity="0.55"></rect>
+      <rect width="168" height="34" rx="3" fill="#F1ECDE"></rect>
+      <rect width="168" height="34" rx="3" fill="none" stroke="rgba(201,191,173,0.34)"></rect>
+      <text x="14" y="22" fill="#14130E">MODEL-AGNOSTIC</text>
+    </g>
+  </g>
+
+  
+  
+  <g transform="translate(636, 130)">
+    <rect x="5" y="5" width="580" height="440" rx="4" fill="#000000" opacity="0.55"></rect>
+    <rect width="580" height="440" rx="4" fill="#FFFFFF"></rect>
+    <rect width="580" height="440" rx="4" fill="none" stroke="rgba(201,191,173,0.22)" stroke-width="1"></rect>
+
+    
+    <g>
+      <rect width="580" height="38" rx="4" fill="#EDEFEF"></rect>
+      <rect y="20" width="580" height="18" fill="#EDEFEF"></rect>
+      <line x1="0" y1="38" x2="580" y2="38" stroke="rgba(201,191,173,0.18)" stroke-width="1"></line>
+      <g transform="translate(18, 19)">
+        <circle cx="0" cy="0" r="5.5" fill="#E36055"></circle>
+        <circle cx="18" cy="0" r="5.5" fill="#E9B345"></circle>
+        <circle cx="36" cy="0" r="5.5" fill="#5BBF50"></circle>
+      </g>
+      <text x="290" y="24" text-anchor="middle" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="11" fill="#6B6254" letter-spacing="1.4">[ § ORNN EMBEDDED SKILL SEARCH ]</text>
+    </g>
+
+    
+    
+    <g transform="translate(22, 66)" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="10">
+
+      <text y="0"><tspan fill="#FF7322">⏺</tspan> <tspan fill="#14130E">Hello — how can I help today?</tspan></text>
+      <text y="24"><tspan fill="#1A5670">&gt;</tspan> <tspan fill="#1A5670">Let&#39;s create a marketing video to introduce my new skill</tspan></text>
+      <text y="40"><tspan fill="#1A5670">  life-cycle API product to the public.</tspan></text>
+      <text y="64"><tspan fill="#FF7322">⏺</tspan> <tspan fill="#14130E">Understood. Let me search Ornn for skills that handle marketing video generation.</tspan></text>
+      <text y="80"><tspan fill="#7E776B">  ⎿ ornn.search({ q: &#34;marketing video generation&#34; })</tspan></text>
+      <text y="104"><tspan fill="#FF7322">⏺</tspan> <tspan fill="#14130E">Found &#34;</tspan><tspan fill="#B8861A">marketing-content-generation</tspan><tspan fill="#14130E">&#34; on Ornn — v0.1.3 · 12,400 installs</tspan></text>
+      <text y="120"><tspan fill="#14130E">  MIT · video + text. Shall we proceed with execution?</tspan></text>
+      <text y="144"><tspan fill="#1A5670">&gt;</tspan> <tspan fill="#1A5670">Let&#39;s proceed.</tspan></text>
+      <text y="168"><tspan fill="#FF7322">⏺</tspan> <tspan fill="#14130E">Sure. Pulling skill package, preparing local execution…</tspan></text>
+      <text y="184"><tspan fill="#7E776B">  ⎿ already installed at v0.1.3 (~/.ornn/installed-skills.json)</tspan></text>
+      <text y="200"><tspan fill="#B8861A">  ?</tspan> <tspan fill="#14130E">Latest on Ornn is v1.0.1 — would you like to update?</tspan></text>
+      <text y="224"><tspan fill="#1A5670">&gt;</tspan> <tspan fill="#1A5670">Yes — update, load, and start creating the video.</tspan></text>
+      <text y="248"><tspan fill="#FF7322">⏺</tspan> <tspan fill="#14130E">On it.</tspan></text>
+      <text y="264"><tspan fill="#7E776B">  ⎿ ornn.update(&#34;marketing-content-generation&#34;, &#34;1.0.1&#34;)</tspan></text>
+      <text y="280"><tspan fill="#5F7A46">  ✓ v1.0.1 loaded  ·  2.4 s</tspan></text>
+      <text y="304"><tspan fill="#FF7322">⏺</tspan> <tspan fill="#14130E">Skill loaded. Generating marketing video now…</tspan></text>
+      <text y="320"><tspan fill="#2B7791">▌</tspan> <tspan fill="#4A453B">scene 1 / 12  ·  audio  ·  captions</tspan></text>
+    </g>
+  </g>
+
+    <g transform="translate(64, 580)">
+    <rect x="0" y="-2" width="56" height="4" fill="#FF7322"></rect>
+    <line x1="56" y1="0" x2="1124" y2="0" stroke="rgba(201,191,173,0.22)" stroke-width="1"></line>
+    <rect x="323" y="-1.5" width="3" height="3" fill="rgba(201,191,173,0.34)"></rect>
+    <rect x="853" y="-1.5" width="3" height="3" fill="rgba(201,191,173,0.34)"></rect>
+    <rect x="1124" y="-2" width="28" height="4" fill="#1A5670"></rect>
+  </g>
+
+  
+  <g font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="11" fill="#7E776B" letter-spacing="1.4">
+    <text x="64" y="610">[ § APACHE 2.0  ·  OPEN SOURCE ]</text>
+    <text x="1216" y="610" text-anchor="end"><tspan fill="#F1ECDE" font-weight="600">github.com/ChronoAIProject/Ornn</tspan>  ↗</text>
+  </g>
+</svg>
\ No newline at end of file
diff --git a/ornn-web/public/hero-brand.svg b/ornn-web/public/hero-brand.svg
new file mode 100644
index 00000000..948979ae
--- /dev/null
+++ b/ornn-web/public/hero-brand.svg
@@ -0,0 +1,272 @@
+<?xml version="1.0"?>
+<svg viewBox="0 0 1280 640" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, BlinkMacSystemFont, &#39;Inter&#39;, &#39;Segoe UI&#39;, Helvetica, Arial, sans-serif">
+  <defs>
+    
+    
+
+    <symbol id="ornn-logomark" viewBox="0 0 230 64">
+      <path fill="#FF7322" fill-rule="evenodd" d="M63.39,38.24 L59.46,37.46 A28,28 0 0,1 55.28,47.56 L58.61,49.78 A32,32 0 0,1 49.78,58.61 L47.56,55.28 A28,28 0 0,1 37.46,59.46 L38.24,63.39 A32,32 0 0,1 25.76,63.39 L26.54,59.46 A28,28 0 0,1 16.44,55.28 L14.22,58.61 A32,32 0 0,1 5.39,49.78 L8.72,47.56 A28,28 0 0,1 4.54,37.46 L0.61,38.24 A32,32 0 0,1 0.61,25.76 L4.54,26.54 A28,28 0 0,1 8.72,16.44 L5.39,14.22 A32,32 0 0,1 14.22,5.39 L16.44,8.72 A28,28 0 0,1 26.54,4.54 L25.76,0.61 A32,32 0 0,1 38.24,0.61 L37.46,4.54 A28,28 0 0,1 47.56,8.72 L49.78,5.39 A32,32 0 0,1 58.61,14.22 L55.28,16.44 A28,28 0 0,1 59.46,26.54 L63.39,25.76 A32,32 0 0,1 63.39,38.24 Z M46,32 A14,14 0 1,0 18,32 A14,14 0 1,0 46,32 Z"></path>
+      <g fill="currentColor">
+        <path d="M74,60 L74,12 L86,12 A24,24 0 0,1 110,36 L98,36 A12,12 0 0,0 86,24 L86,60 Z"></path>
+        <path d="M122,60 L122,36 A24,24 0 0,1 170,36 L170,60 L158,60 L158,36 A12,12 0 0,0 134,36 L134,60 Z"></path>
+        <path d="M182,60 L182,36 A24,24 0 0,1 230,36 L230,60 L218,60 L218,36 A12,12 0 0,0 194,36 L194,60 Z"></path>
+      </g>
+    </symbol>
+    <symbol id="ornn-gear" viewBox="0 0 64 64">
+      <path fill="#FF7322" fill-rule="evenodd" d="M63.39,38.24 L59.46,37.46 A28,28 0 0,1 55.28,47.56 L58.61,49.78 A32,32 0 0,1 49.78,58.61 L47.56,55.28 A28,28 0 0,1 37.46,59.46 L38.24,63.39 A32,32 0 0,1 25.76,63.39 L26.54,59.46 A28,28 0 0,1 16.44,55.28 L14.22,58.61 A32,32 0 0,1 5.39,49.78 L8.72,47.56 A28,28 0 0,1 4.54,37.46 L0.61,38.24 A32,32 0 0,1 0.61,25.76 L4.54,26.54 A28,28 0 0,1 8.72,16.44 L5.39,14.22 A32,32 0 0,1 14.22,5.39 L16.44,8.72 A28,28 0 0,1 26.54,4.54 L25.76,0.61 A32,32 0 0,1 38.24,0.61 L37.46,4.54 A28,28 0 0,1 47.56,8.72 L49.78,5.39 A32,32 0 0,1 58.61,14.22 L55.28,16.44 A28,28 0 0,1 59.46,26.54 L63.39,25.76 A32,32 0 0,1 63.39,38.24 Z M46,32 A14,14 0 1,0 18,32 A14,14 0 1,0 46,32 Z"></path>
+    </symbol>
+    <pattern id="blueprint-grid" width="32" height="32" patternUnits="userSpaceOnUse">
+      <path d="M 32 0 L 0 0 0 32" fill="none" stroke="rgba(20,19,14,0.045)" stroke-width="0.6"></path>
+    </pattern>
+    <radialGradient id="ember-halo" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" stop-color="#D9461A" stop-opacity="0.32"></stop>
+      <stop offset="55%" stop-color="#D9461A" stop-opacity="0.10"></stop>
+      <stop offset="100%" stop-color="#D9461A" stop-opacity="0"></stop>
+    </radialGradient>
+    <radialGradient id="plinth-shine" cx="35%" cy="30%" r="75%">
+      <stop offset="0%" stop-color="#FFFFFF"></stop>
+      <stop offset="60%" stop-color="#F4F2EE"></stop>
+      <stop offset="100%" stop-color="#E4DFD6"></stop>
+    </radialGradient>
+    <linearGradient id="seg-grad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#FF7322"></stop>
+      <stop offset="100%" stop-color="#B33912"></stop>
+    </linearGradient>
+    <linearGradient id="dial-tick-grad" gradientUnits="userSpaceOnUse" x1="0" y1="-72" x2="0" y2="-56">
+      <stop offset="0%" stop-color="#B33912"></stop>
+      <stop offset="100%" stop-color="#FF7322"></stop>
+    </linearGradient>
+  </defs>
+
+  
+  <rect width="1280" height="640" fill="#EAECEC"></rect>
+  <rect width="1280" height="640" fill="url(#blueprint-grid)"></rect>
+
+  
+  <g>
+    <line x1="14" y1="32" x2="14" y2="608" stroke="rgba(20,19,14,0.22)" stroke-width="0.8"></line>
+    <line x1="1266" y1="32" x2="1266" y2="608" stroke="rgba(20,19,14,0.22)" stroke-width="0.8"></line>
+    <g stroke="rgba(20,19,14,0.40)" stroke-width="0.8">
+      <line x1="6" y1="96" x2="14" y2="96"></line><line x1="6" y1="160" x2="14" y2="160"></line>
+      <line x1="6" y1="224" x2="14" y2="224"></line><line x1="6" y1="288" x2="14" y2="288"></line>
+      <line x1="6" y1="352" x2="14" y2="352"></line><line x1="6" y1="416" x2="14" y2="416"></line>
+      <line x1="6" y1="480" x2="14" y2="480"></line><line x1="6" y1="544" x2="14" y2="544"></line>
+      <line x1="1266" y1="96" x2="1274" y2="96"></line><line x1="1266" y1="160" x2="1274" y2="160"></line>
+      <line x1="1266" y1="224" x2="1274" y2="224"></line><line x1="1266" y1="288" x2="1274" y2="288"></line>
+      <line x1="1266" y1="352" x2="1274" y2="352"></line><line x1="1266" y1="416" x2="1274" y2="416"></line>
+      <line x1="1266" y1="480" x2="1274" y2="480"></line><line x1="1266" y1="544" x2="1274" y2="544"></line>
+    </g>
+  </g>
+
+  
+  <g stroke="rgba(20,19,14,0.40)" stroke-width="1" fill="none">
+    <g transform="translate(48, 48)"><line x1="-8" y1="0" x2="8" y2="0"></line><line x1="0" y1="-8" x2="0" y2="8"></line><circle r="3.5"></circle></g>
+    <g transform="translate(1232, 48)"><line x1="-8" y1="0" x2="8" y2="0"></line><line x1="0" y1="-8" x2="0" y2="8"></line><circle r="3.5"></circle></g>
+    <g transform="translate(48, 592)"><line x1="-8" y1="0" x2="8" y2="0"></line><line x1="0" y1="-8" x2="0" y2="8"></line><circle r="3.5"></circle></g>
+    <g transform="translate(1232, 592)"><line x1="-8" y1="0" x2="8" y2="0"></line><line x1="0" y1="-8" x2="0" y2="8"></line><circle r="3.5"></circle></g>
+  </g>
+
+  
+  <g transform="translate(64, 64)" color="#14130E">
+    <use href="#ornn-logomark" width="115" height="32"></use>
+  </g>
+  <text x="1216" y="84" text-anchor="end" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="11" fill="#7E776B" letter-spacing="1.4"><tspan fill="#14130E" font-weight="600">ornn.chrono-ai.fun</tspan>  ↗</text>
+
+  
+  <g transform="translate(64, 112)">
+    <rect x="0" y="-2" width="56" height="4" fill="#D9461A"></rect>
+    <line x1="56" y1="0" x2="1124" y2="0" stroke="rgba(20,19,14,0.18)" stroke-width="1"></line>
+    <rect x="323" y="-1.5" width="3" height="3" fill="rgba(20,19,14,0.40)"></rect>
+    <rect x="853" y="-1.5" width="3" height="3" fill="rgba(20,19,14,0.40)"></rect>
+    <rect x="1124" y="-2" width="28" height="4" fill="#2B7791"></rect>
+  </g>
+
+  
+  
+  <g transform="translate(64, 0)">
+    <g font-family="&#39;Bricolage Grotesque&#39;, &#39;Sora&#39;, &#39;Space Grotesk&#39;, &#39;Helvetica Neue&#39;, Helvetica, Arial, sans-serif" font-weight="800" font-size="52" fill="#14130E" letter-spacing="-1.6">
+      <text x="0" y="184">THE SKILL</text>
+      <text x="0" y="234">LIFE-CYCLE API</text>
+      <rect x="104" y="244" width="298" height="50" rx="3" ry="5" fill="#D9461A" opacity="0.28" transform="rotate(-0.5 253 269)"></rect>
+      <text x="0" y="284">FOR <tspan fill="#14130E">AI AGENTS</tspan></text>
+    </g>
+
+    
+    <rect x="0" y="316" width="3" height="40" fill="#D9461A"></rect>
+    <text x="16" y="332" font-family="&#39;Inter&#39;, -apple-system, BlinkMacSystemFont, &#39;Segoe UI&#39;, Helvetica, Arial, sans-serif" font-size="14" fill="#4A453B">Fully automated skill life-cycle, self-managed by your agents.</text>
+    <text x="16" y="352" font-family="&#39;Inter&#39;, -apple-system, BlinkMacSystemFont, &#39;Segoe UI&#39;, Helvetica, Arial, sans-serif" font-size="14" font-weight="600" fill="#14130E"><tspan fill="#D9461A">Skill-as-a-Service</tspan> — not another marketplace.</text>
+
+  </g>
+
+  
+  
+  <g transform="translate(224, 464)">
+    <circle r="70" fill="url(#ember-halo)" opacity="0.55"></circle>
+    <circle r="64" fill="none" stroke="rgba(20,19,14,0.20)" stroke-width="1"></circle>
+    <circle r="74" fill="none" stroke="rgba(20,19,14,0.30)" stroke-width="0.6" stroke-dasharray="1 3"></circle>
+    <circle r="50" fill="none" stroke="rgba(20,19,14,0.20)" stroke-width="0.6"></circle>
+    <line x1="5.58" y1="-63.76" x2="5.32" y2="-60.77" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="11.11" y1="-63.03" x2="10.59" y2="-60.07" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="16.56" y1="-61.82" x2="15.79" y2="-58.92" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="21.89" y1="-60.14" x2="20.86" y2="-57.32" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="27.05" y1="-58" x2="25.78" y2="-55.28" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="32" y1="-55.43" x2="30.5" y2="-52.83" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="36.71" y1="-52.43" x2="34.99" y2="-49.97" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="41.14" y1="-49.03" x2="39.21" y2="-46.73" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="49.03" y1="-41.14" x2="46.73" y2="-39.21" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="52.43" y1="-36.71" x2="49.97" y2="-34.99" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="55.43" y1="-32" x2="52.83" y2="-30.5" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="58" y1="-27.05" x2="55.28" y2="-25.78" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="60.14" y1="-21.89" x2="57.32" y2="-20.86" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="61.82" y1="-16.56" x2="58.92" y2="-15.79" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="63.03" y1="-11.11" x2="60.07" y2="-10.59" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="63.76" y1="-5.58" x2="60.77" y2="-5.32" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="63.76" y1="5.58" x2="60.77" y2="5.32" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="63.03" y1="11.11" x2="60.07" y2="10.59" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="61.82" y1="16.56" x2="58.92" y2="15.79" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="60.14" y1="21.89" x2="57.32" y2="20.86" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="58" y1="27.05" x2="55.28" y2="25.78" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="55.43" y1="32" x2="52.83" y2="30.5" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="52.43" y1="36.71" x2="49.97" y2="34.99" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="49.03" y1="41.14" x2="46.73" y2="39.21" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="41.14" y1="49.03" x2="39.21" y2="46.73" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="36.71" y1="52.43" x2="34.99" y2="49.97" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="32" y1="55.43" x2="30.5" y2="52.83" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="27.05" y1="58" x2="25.78" y2="55.28" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="21.89" y1="60.14" x2="20.86" y2="57.32" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="16.56" y1="61.82" x2="15.79" y2="58.92" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="11.11" y1="63.03" x2="10.59" y2="60.07" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="5.58" y1="63.76" x2="5.32" y2="60.77" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-5.58" y1="63.76" x2="-5.32" y2="60.77" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-11.11" y1="63.03" x2="-10.59" y2="60.07" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-16.56" y1="61.82" x2="-15.79" y2="58.92" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-21.89" y1="60.14" x2="-20.86" y2="57.32" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-27.05" y1="58" x2="-25.78" y2="55.28" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-32" y1="55.43" x2="-30.5" y2="52.83" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-36.71" y1="52.43" x2="-34.99" y2="49.97" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-41.14" y1="49.03" x2="-39.21" y2="46.73" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-49.03" y1="41.14" x2="-46.73" y2="39.21" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-52.43" y1="36.71" x2="-49.97" y2="34.99" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-55.43" y1="32" x2="-52.83" y2="30.5" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-58" y1="27.05" x2="-55.28" y2="25.78" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-60.14" y1="21.89" x2="-57.32" y2="20.86" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-61.82" y1="16.56" x2="-58.92" y2="15.79" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-63.03" y1="11.11" x2="-60.07" y2="10.59" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-63.76" y1="5.58" x2="-60.77" y2="5.32" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-63.76" y1="-5.58" x2="-60.77" y2="-5.32" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-63.03" y1="-11.11" x2="-60.07" y2="-10.59" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-61.82" y1="-16.56" x2="-58.92" y2="-15.79" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-60.14" y1="-21.89" x2="-57.32" y2="-20.86" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-58" y1="-27.05" x2="-55.28" y2="-25.78" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-55.43" y1="-32" x2="-52.83" y2="-30.5" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-52.43" y1="-36.71" x2="-49.97" y2="-34.99" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-49.03" y1="-41.14" x2="-46.73" y2="-39.21" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-41.14" y1="-49.03" x2="-39.21" y2="-46.73" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-36.71" y1="-52.43" x2="-34.99" y2="-49.97" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-32" y1="-55.43" x2="-30.5" y2="-52.83" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-27.05" y1="-58" x2="-25.78" y2="-55.28" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-21.89" y1="-60.14" x2="-20.86" y2="-57.32" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-16.56" y1="-61.82" x2="-15.79" y2="-58.92" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-11.11" y1="-63.03" x2="-10.59" y2="-60.07" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="-5.58" y1="-63.76" x2="-5.32" y2="-60.77" stroke="rgba(20,19,14,0.18)" stroke-width="0.8"></line>
+    <line x1="0" y1="-56" x2="0" y2="-68" stroke="url(#dial-tick-grad)" stroke-width="3" stroke-linecap="round"></line>
+    <line x1="39.6" y1="-39.6" x2="48.08" y2="-48.08" stroke="url(#dial-tick-grad)" stroke-width="3" stroke-linecap="round"></line>
+    <line x1="56" y1="0" x2="68" y2="0" stroke="url(#dial-tick-grad)" stroke-width="3" stroke-linecap="round"></line>
+    <line x1="39.6" y1="39.6" x2="48.08" y2="48.08" stroke="url(#dial-tick-grad)" stroke-width="3" stroke-linecap="round"></line>
+    <line x1="0" y1="56" x2="0" y2="68" stroke="url(#dial-tick-grad)" stroke-width="3" stroke-linecap="round"></line>
+    <line x1="-39.6" y1="39.6" x2="-48.08" y2="48.08" stroke="url(#dial-tick-grad)" stroke-width="3" stroke-linecap="round"></line>
+    <line x1="-56" y1="0" x2="-68" y2="0" stroke="url(#dial-tick-grad)" stroke-width="3" stroke-linecap="round"></line>
+    <line x1="-39.6" y1="-39.6" x2="-48.08" y2="-48.08" stroke="url(#dial-tick-grad)" stroke-width="3" stroke-linecap="round"></line>
+    <circle cx="2" cy="2" r="34" fill="rgba(110,34,7,0.18)"></circle>
+    <circle r="34" fill="#FFFFFF"></circle>
+    <circle r="34" fill="none" stroke="rgba(20,19,14,0.14)" stroke-width="1"></circle>
+    <use href="#ornn-gear" x="-24" y="-24" width="48" height="48"></use>
+    <text x="0" y="-84" text-anchor="middle" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="9" font-weight="600" fill="#14130E" letter-spacing="1.2"><tspan fill="#D9461A" font-weight="500" font-size="7.5">01 </tspan>SEARCH</text>
+    <text x="55.15" y="-51.15" text-anchor="start" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="9" font-weight="600" fill="#14130E" letter-spacing="1.2"><tspan fill="#D9461A" font-weight="500" font-size="7.5">02 </tspan>PREVIEW</text>
+    <text x="78" y="4" text-anchor="start" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="9" font-weight="600" fill="#14130E" letter-spacing="1.2"><tspan fill="#D9461A" font-weight="500" font-size="7.5">03 </tspan>AUDIT</text>
+    <text x="55.15" y="59.15" text-anchor="start" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="9" font-weight="600" fill="#14130E" letter-spacing="1.2"><tspan fill="#D9461A" font-weight="500" font-size="7.5">04 </tspan>INSTALL</text>
+    <text x="0" y="98" text-anchor="middle" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="9" font-weight="600" fill="#14130E" letter-spacing="1.2"><tspan fill="#D9461A" font-weight="500" font-size="7.5">05 </tspan>EXECUTE</text>
+    <text x="-55.15" y="59.15" text-anchor="end" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="9" font-weight="600" fill="#14130E" letter-spacing="1.2"><tspan fill="#D9461A" font-weight="500" font-size="7.5">06 </tspan>GENERATE</text>
+    <text x="-78" y="4" text-anchor="end" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="9" font-weight="600" fill="#14130E" letter-spacing="1.2"><tspan fill="#D9461A" font-weight="500" font-size="7.5">07 </tspan>PUBLISH</text>
+    <text x="-55.15" y="-51.15" text-anchor="end" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="9" font-weight="600" fill="#14130E" letter-spacing="1.2"><tspan fill="#D9461A" font-weight="500" font-size="7.5">08 </tspan>SHARE</text>
+  </g>
+
+      <g transform="translate(404, 406)" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="11" font-weight="600" letter-spacing="1.4">
+    <g>
+      <rect x="3" y="3" width="168" height="34" rx="3" fill="#6E2207" opacity="0.22"></rect>
+      <rect width="168" height="34" rx="3" fill="#FFFFFF"></rect>
+      <rect width="168" height="34" rx="3" fill="none" stroke="rgba(20,19,14,0.40)"></rect>
+      <text x="14" y="22" fill="#14130E">AGENT-FACING</text>
+    </g>
+    <g transform="translate(0, 46)">
+      <rect x="3" y="3" width="168" height="34" rx="3" fill="#6E2207" opacity="0.22"></rect>
+      <rect width="168" height="34" rx="3" fill="#FFFFFF"></rect>
+      <rect width="168" height="34" rx="3" fill="none" stroke="rgba(20,19,14,0.40)"></rect>
+      <text x="14" y="22" fill="#14130E">HTTP · MCP</text>
+    </g>
+    <g transform="translate(0, 92)">
+      <rect x="3" y="3" width="168" height="34" rx="3" fill="#6E2207" opacity="0.22"></rect>
+      <rect width="168" height="34" rx="3" fill="#FFFFFF"></rect>
+      <rect width="168" height="34" rx="3" fill="none" stroke="rgba(20,19,14,0.40)"></rect>
+      <text x="14" y="22" fill="#14130E">MODEL-AGNOSTIC</text>
+    </g>
+  </g>
+
+  
+  
+  <g transform="translate(636, 130)">
+    <rect x="5" y="5" width="580" height="440" rx="4" fill="#6E2207" opacity="0.22"></rect>
+    <rect width="580" height="440" rx="4" fill="#08070A"></rect>
+    <rect width="580" height="440" rx="4" fill="none" stroke="rgba(201,191,173,0.22)" stroke-width="1"></rect>
+
+    
+    <g>
+      <rect width="580" height="38" rx="4" fill="#14110B"></rect>
+      <rect y="20" width="580" height="18" fill="#14110B"></rect>
+      <line x1="0" y1="38" x2="580" y2="38" stroke="rgba(201,191,173,0.18)" stroke-width="1"></line>
+      <g transform="translate(18, 19)">
+        <circle cx="0" cy="0" r="5.5" fill="#3A332A"></circle>
+        <circle cx="18" cy="0" r="5.5" fill="#3A332A"></circle>
+        <circle cx="36" cy="0" r="5.5" fill="#3A332A"></circle>
+      </g>
+      <text x="290" y="24" text-anchor="middle" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="11" fill="#6B6254" letter-spacing="1.4">[ § ORNN EMBEDDED SKILL SEARCH ]</text>
+    </g>
+
+    
+    
+    <g transform="translate(22, 66)" font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="10">
+
+      <text y="0"><tspan fill="#FF7322">⏺</tspan> <tspan fill="#F1ECDE">Hello — how can I help today?</tspan></text>
+      <text y="24"><tspan fill="#5BC8E8">&gt;</tspan> <tspan fill="#5BC8E8">Let&#39;s create a marketing video to introduce my new skill</tspan></text>
+      <text y="40"><tspan fill="#5BC8E8">  life-cycle API product to the public.</tspan></text>
+      <text y="64"><tspan fill="#FF7322">⏺</tspan> <tspan fill="#F1ECDE">Understood. Let me search Ornn for skills that handle marketing video generation.</tspan></text>
+      <text y="80"><tspan fill="#6B6254">  ⎿ ornn.search({ q: &#34;marketing video generation&#34; })</tspan></text>
+      <text y="104"><tspan fill="#FF7322">⏺</tspan> <tspan fill="#F1ECDE">Found &#34;</tspan><tspan fill="#E8B341">marketing-content-generation</tspan><tspan fill="#F1ECDE">&#34; on Ornn — v0.1.3 · 12,400 installs</tspan></text>
+      <text y="120"><tspan fill="#F1ECDE">  MIT · video + text. Shall we proceed with execution?</tspan></text>
+      <text y="144"><tspan fill="#5BC8E8">&gt;</tspan> <tspan fill="#5BC8E8">Let&#39;s proceed.</tspan></text>
+      <text y="168"><tspan fill="#FF7322">⏺</tspan> <tspan fill="#F1ECDE">Sure. Pulling skill package, preparing local execution…</tspan></text>
+      <text y="184"><tspan fill="#6B6254">  ⎿ already installed at v0.1.3 (~/.ornn/installed-skills.json)</tspan></text>
+      <text y="200"><tspan fill="#E8B341">  ?</tspan> <tspan fill="#F1ECDE">Latest on Ornn is v1.0.1 — would you like to update?</tspan></text>
+      <text y="224"><tspan fill="#5BC8E8">&gt;</tspan> <tspan fill="#5BC8E8">Yes — update, load, and start creating the video.</tspan></text>
+      <text y="248"><tspan fill="#FF7322">⏺</tspan> <tspan fill="#F1ECDE">On it.</tspan></text>
+      <text y="264"><tspan fill="#6B6254">  ⎿ ornn.update(&#34;marketing-content-generation&#34;, &#34;1.0.1&#34;)</tspan></text>
+      <text y="280"><tspan fill="#7FA06A">  ✓ v1.0.1 loaded  ·  2.4 s</tspan></text>
+      <text y="304"><tspan fill="#FF7322">⏺</tspan> <tspan fill="#F1ECDE">Skill loaded. Generating marketing video now…</tspan></text>
+      <text y="320"><tspan fill="#2B7791">▌</tspan> <tspan fill="#C9BFAD">scene 1 / 12  ·  audio  ·  captions</tspan></text>
+    </g>
+  </g>
+
+    <g transform="translate(64, 580)">
+    <rect x="0" y="-2" width="56" height="4" fill="#D9461A"></rect>
+    <line x1="56" y1="0" x2="1124" y2="0" stroke="rgba(20,19,14,0.18)" stroke-width="1"></line>
+    <rect x="323" y="-1.5" width="3" height="3" fill="rgba(20,19,14,0.40)"></rect>
+    <rect x="853" y="-1.5" width="3" height="3" fill="rgba(20,19,14,0.40)"></rect>
+    <rect x="1124" y="-2" width="28" height="4" fill="#2B7791"></rect>
+  </g>
+
+  
+  <g font-family="&#39;JetBrains Mono&#39;, ui-monospace, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="11" fill="#7E776B" letter-spacing="1.4">
+    <text x="64" y="610">[ § APACHE 2.0  ·  OPEN SOURCE ]</text>
+    <text x="1216" y="610" text-anchor="end"><tspan fill="#14130E" font-weight="600">github.com/ChronoAIProject/Ornn</tspan>  ↗</text>
+  </g>
+</svg>
\ No newline at end of file
diff --git a/ornn-web/public/hero-terminal.svg b/ornn-web/public/hero-terminal.svg
new file mode 100644
index 00000000..6c7cffae
--- /dev/null
+++ b/ornn-web/public/hero-terminal.svg
@@ -0,0 +1,130 @@
+<?xml version="1.0"?>
+<svg viewBox="0 0 1280 640" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, BlinkMacSystemFont, &#39;Inter&#39;, &#39;Segoe UI&#39;, Helvetica, Arial, sans-serif">
+  <defs>
+    <symbol id="ornn-logomark" viewBox="0 0 230 64">
+      <path fill="#FF7322" fill-rule="evenodd" d="M63.39,38.24 L59.46,37.46 A28,28 0 0,1 55.28,47.56 L58.61,49.78 A32,32 0 0,1 49.78,58.61 L47.56,55.28 A28,28 0 0,1 37.46,59.46 L38.24,63.39 A32,32 0 0,1 25.76,63.39 L26.54,59.46 A28,28 0 0,1 16.44,55.28 L14.22,58.61 A32,32 0 0,1 5.39,49.78 L8.72,47.56 A28,28 0 0,1 4.54,37.46 L0.61,38.24 A32,32 0 0,1 0.61,25.76 L4.54,26.54 A28,28 0 0,1 8.72,16.44 L5.39,14.22 A32,32 0 0,1 14.22,5.39 L16.44,8.72 A28,28 0 0,1 26.54,4.54 L25.76,0.61 A32,32 0 0,1 38.24,0.61 L37.46,4.54 A28,28 0 0,1 47.56,8.72 L49.78,5.39 A32,32 0 0,1 58.61,14.22 L55.28,16.44 A28,28 0 0,1 59.46,26.54 L63.39,25.76 A32,32 0 0,1 63.39,38.24 Z M46,32 A14,14 0 1,0 18,32 A14,14 0 1,0 46,32 Z"></path>
+      <g fill="currentColor">
+        <path d="M74,60 L74,12 L86,12 A24,24 0 0,1 110,36 L98,36 A12,12 0 0,0 86,24 L86,60 Z"></path>
+        <path d="M122,60 L122,36 A24,24 0 0,1 170,36 L170,60 L158,60 L158,36 A12,12 0 0,0 134,36 L134,60 Z"></path>
+        <path d="M182,60 L182,36 A24,24 0 0,1 230,36 L230,60 L218,60 L218,36 A12,12 0 0,0 194,36 L194,60 Z"></path>
+      </g>
+    </symbol>
+
+    
+    <pattern id="patina" width="1" height="2" patternUnits="userSpaceOnUse">
+      <rect width="1" height="1" fill="rgba(241,236,222,0.012)"></rect>
+    </pattern>
+  </defs>
+
+  
+  <rect width="1280" height="640" fill="#0B0907"></rect>
+  <rect width="1280" height="640" fill="url(#patina)"></rect>
+
+  
+  <g stroke="rgba(201,191,173,0.34)" stroke-width="1" fill="none">
+    <g transform="translate(48, 48)"><line x1="-8" y1="0" x2="8" y2="0"></line><line x1="0" y1="-8" x2="0" y2="8"></line><circle r="3.5"></circle></g>
+    <g transform="translate(1232, 48)"><line x1="-8" y1="0" x2="8" y2="0"></line><line x1="0" y1="-8" x2="0" y2="8"></line><circle r="3.5"></circle></g>
+    <g transform="translate(48, 592)"><line x1="-8" y1="0" x2="8" y2="0"></line><line x1="0" y1="-8" x2="0" y2="8"></line><circle r="3.5"></circle></g>
+    <g transform="translate(1232, 592)"><line x1="-8" y1="0" x2="8" y2="0"></line><line x1="0" y1="-8" x2="0" y2="8"></line><circle r="3.5"></circle></g>
+  </g>
+
+  
+  <g transform="translate(64, 60)" color="#F1ECDE">
+    <use href="#ornn-logomark" width="115" height="32"></use>
+  </g>
+  <text x="1216" y="84" text-anchor="end" font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="11" font-weight="500" fill="#6B6254" letter-spacing="2.4">[ § 03 — TERMINAL ]</text>
+
+  
+  <g transform="translate(64, 112)">
+    <rect x="0" y="-2" width="56" height="4" fill="#FF7322"></rect>
+    <line x1="56" y1="0" x2="1124" y2="0" stroke="rgba(201,191,173,0.22)" stroke-width="1"></line>
+    <rect x="323" y="-1.5" width="3" height="3" fill="rgba(201,191,173,0.34)"></rect>
+    <rect x="853" y="-1.5" width="3" height="3" fill="rgba(201,191,173,0.34)"></rect>
+    <rect x="1124" y="-2" width="28" height="4" fill="#5BC8E8"></rect>
+  </g>
+
+  
+  <g transform="translate(64, 0)">
+    <text x="0" y="172" font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="11" font-weight="500" fill="#FF7322" letter-spacing="3">[ § ONE API  ·  AGENT-FACING  ·  MODEL-AGNOSTIC ]</text>
+
+    <g font-family="&#39;Space Grotesk&#39;, &#39;Helvetica Neue&#39;, Helvetica, Arial, sans-serif" font-weight="700" font-size="52" fill="#F1ECDE" letter-spacing="-1.3">
+      <text x="0" y="228">THE SKILL</text>
+      <text x="0" y="280">LIFE-CYCLE API</text>
+      
+      <rect x="115" y="298" width="280" height="42" rx="3" ry="4" fill="#FF7322" opacity="0.32" transform="rotate(-0.5 255 319)"></rect>
+      <text x="0" y="332">FOR <tspan fill="#F1ECDE">AI AGENTS</tspan></text>
+    </g>
+
+    <text x="0" y="384" font-family="-apple-system, BlinkMacSystemFont, &#39;Inter&#39;, &#39;Segoe UI&#39;, Helvetica, Arial, sans-serif" font-size="14" fill="#C9BFAD">
+      <tspan>Search · audit · install · execute · forge · publish.</tspan>
+      <tspan x="0" dy="20">Bring your own model and runtime.</tspan>
+    </text>
+
+    
+    <g transform="translate(0, 446)" font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="12" font-weight="600" letter-spacing="1.4">
+      
+      <rect x="4" y="4" width="170" height="36" rx="3" fill="#7A2308"></rect>
+      <rect width="170" height="36" rx="3" fill="#FF7322"></rect>
+      <text x="85" y="23" text-anchor="middle" fill="#0B0907">READ THE SPEC  →</text>
+
+      <g transform="translate(186, 0)">
+        <rect width="172" height="36" rx="3" fill="none" stroke="rgba(201,191,173,0.34)"></rect>
+        <text x="86" y="23" text-anchor="middle" fill="#F1ECDE">VIEW THE DOCS  →</text>
+      </g>
+    </g>
+  </g>
+
+  
+  <g transform="translate(696, 160)">
+    
+    <rect x="5" y="5" width="496" height="360" rx="4" fill="#000000" opacity="0.55"></rect>
+    
+    <rect width="496" height="360" rx="4" fill="#08070A"></rect>
+    <rect width="496" height="360" rx="4" fill="none" stroke="rgba(201,191,173,0.22)" stroke-width="1"></rect>
+
+    
+    <g transform="translate(0, 0)">
+      <rect width="496" height="40" rx="4" fill="#14110B"></rect>
+      <rect y="22" width="496" height="18" fill="#14110B"></rect>
+      <line x1="0" y1="40" x2="496" y2="40" stroke="rgba(201,191,173,0.18)" stroke-width="1"></line>
+      <g transform="translate(18, 20)">
+        <circle cx="0" cy="0" r="5.5" fill="#3A332A"></circle>
+        <circle cx="18" cy="0" r="5.5" fill="#3A332A"></circle>
+        <circle cx="36" cy="0" r="5.5" fill="#3A332A"></circle>
+      </g>
+      <text x="248" y="25" text-anchor="middle" font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="11" fill="#6B6254" letter-spacing="1.4">[ § AGENT  ⇄  ORNN-API  ·  MCP ]</text>
+    </g>
+
+    
+    <g transform="translate(26, 72)" font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="12.5">
+      <text fill="#FF7322">→ <tspan fill="#F1ECDE">install(&#34;pdf-parse&#34;)</tspan></text>
+      <text y="24" fill="#7FA06A">✓ resolved pdf-parse@2.1.0  <tspan fill="#6B6254">·  4 deps</tspan></text>
+      <text y="44" fill="#7FA06A">✓ audited  <tspan fill="#6B6254">(0 advisories)</tspan></text>
+      <text y="64" fill="#7FA06A">✓ installed  <tspan fill="#6B6254">(612 ms)</tspan></text>
+
+      <text y="100" fill="#FF7322">→ <tspan fill="#F1ECDE">run(&#34;pdf-parse&#34;, &#34;./report.pdf&#34;)</tspan></text>
+      <text y="124" fill="#FF7322">← <tspan fill="#F1ECDE">extracted 18 pages, 4,221 words</tspan></text>
+      <text y="144" fill="#FF7322">← <tspan fill="#F1ECDE">returned to agent  <tspan fill="#6B6254">(t=842ms)</tspan></tspan></text>
+
+      <text y="180" fill="#FF7322">→ <tspan fill="#F1ECDE">forge(&#34;summarize meeting notes&#34;)</tspan></text>
+      <text y="204" fill="#FF7322">← <tspan fill="#F1ECDE">draft skill ready  ·  </tspan><tspan fill="#E8B341">ready to publish</tspan></text>
+
+      <text y="240" fill="#5BC8E8">▌ <tspan fill="#C9BFAD">awaiting next agent call…</tspan></text>
+    </g>
+  </g>
+
+  
+  <g transform="translate(64, 580)">
+    <rect x="0" y="-2" width="56" height="4" fill="#FF7322"></rect>
+    <line x1="56" y1="0" x2="1124" y2="0" stroke="rgba(201,191,173,0.22)" stroke-width="1"></line>
+    <rect x="323" y="-1.5" width="3" height="3" fill="rgba(201,191,173,0.34)"></rect>
+    <rect x="853" y="-1.5" width="3" height="3" fill="rgba(201,191,173,0.34)"></rect>
+    <rect x="1124" y="-2" width="28" height="4" fill="#5BC8E8"></rect>
+  </g>
+
+  
+  <g font-family="ui-monospace, &#39;JetBrains Mono&#39;, &#39;SF Mono&#39;, Menlo, Consolas, monospace" font-size="11" fill="#6B6254" letter-spacing="1.4">
+    <text x="64" y="610">github.com/ChronoAIProject/Ornn</text>
+    <text x="1216" y="610" text-anchor="end"><tspan fill="#F1ECDE" font-weight="600">ornn.chrono-ai.fun</tspan>  ↗</text>
+  </g>
+</svg>
\ No newline at end of file
diff --git a/ornn-web/src/App.tsx b/ornn-web/src/App.tsx
index 4a1d7d46..9bf369bd 100644
--- a/ornn-web/src/App.tsx
+++ b/ornn-web/src/App.tsx
@@ -157,6 +157,9 @@ const AdminAnnouncementsPage = lazy(() =>
 const AdminBroadcastsPage = lazy(() =>
   import("@/pages/admin").then((m) => ({ default: m.BroadcastsPage })),
 );
+const MirrorPage = lazy(() =>
+  import("@/pages/admin/MirrorPage").then((m) => ({ default: m.MirrorPage })),
+);
 
 // Settings layout + section components live under pages/admin/settings.
 const SettingsLayout = lazy(() =>
@@ -293,13 +296,13 @@ const router = createBrowserRouter(
               <Route path="/admin/announcements" element={<AdminAnnouncementsPage />} />
               <Route path="/admin/broadcasts" element={<AdminBroadcastsPage />} />
 
-              {/* /admin/mirror keeps working but redirects to the new
-                  settings/mirror section so existing deep-links + bookmarks
-                  continue to land on the right surface. */}
-              <Route
-                path="/admin/mirror"
-                element={<Navigate to="/admin/settings/mirror" replace />}
-              />
+              {/* /admin/mirror is the deep mirror operations console
+                  (counts, manual reconcile, status). It used to redirect
+                  to /admin/settings/mirror, but that left admins with no
+                  reachable "Manual reconcile" / "Reconcile now" control
+                  (#716). The settings section now links here for the
+                  full operations view. */}
+              <Route path="/admin/mirror" element={<MirrorPage />} />
 
               <Route path="/admin/settings" element={<SettingsLayout />}>
                 <Route
diff --git a/ornn-web/src/components/ErrorBoundary.tsx b/ornn-web/src/components/ErrorBoundary.tsx
index 8e3be414..9d5b44ee 100644
--- a/ornn-web/src/components/ErrorBoundary.tsx
+++ b/ornn-web/src/components/ErrorBoundary.tsx
@@ -38,7 +38,7 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
     return { hasError: true, error };
   }
 
-  componentDidCatch(error: Error, errorInfo: ErrorInfo): void {
+  override componentDidCatch(error: Error, errorInfo: ErrorInfo): void {
     this.setState({ errorInfo });
     this.props.onError?.(error, errorInfo);
 
@@ -60,7 +60,7 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
     window.location.href = "/";
   };
 
-  render(): ReactNode {
+  override render(): ReactNode {
     if (this.state.hasError) {
       if (this.props.fallback) {
         return this.props.fallback;
diff --git a/ornn-web/src/components/admin/AdminUsersTable.tsx b/ornn-web/src/components/admin/AdminUsersTable.tsx
index 5f51665f..44ca1f50 100644
--- a/ornn-web/src/components/admin/AdminUsersTable.tsx
+++ b/ornn-web/src/components/admin/AdminUsersTable.tsx
@@ -9,7 +9,8 @@
  * @module components/admin/AdminUsersTable
  */
 
-import { useState } from "react";
+import { useState, useMemo } from "react";
+import { useTranslation } from "react-i18next";
 import { Link } from "react-router-dom";
 import { Card } from "@/components/ui/Card";
 import { Skeleton } from "@/components/ui/Skeleton";
@@ -34,21 +35,13 @@ interface AdminUsersTableProps {
   description?: string;
 }
 
-const COLUMNS: Array<{
+type ColumnDef = {
   id: keyof AdminUserRow | "actions";
   label: string;
   sortAsc?: AdminUsersSort;
   sortDesc?: AdminUsersSort;
   align?: "left" | "right";
-}> = [
-  { id: "displayName", label: "Username", sortAsc: "displayName:asc", sortDesc: "displayName:desc" },
-  { id: "email", label: "Email", sortAsc: "email:asc", sortDesc: "email:desc" },
-  { id: "skillCount", label: "Skills", sortAsc: "skillCount:asc", sortDesc: "skillCount:desc", align: "right" },
-  { id: "lastActiveAt", label: "Last active", sortAsc: "lastActiveAt:asc", sortDesc: "lastActiveAt:desc", align: "right" },
-  { id: "activityCount", label: "Activities", sortAsc: "activityCount:asc", sortDesc: "activityCount:desc", align: "right" },
-  { id: "firstJoinedAt", label: "First joined", sortAsc: "firstJoinedAt:asc", sortDesc: "firstJoinedAt:desc", align: "right" },
-  { id: "actions", label: "", align: "right" },
-];
+};
 
 function formatDateUTC(iso: string | null, nullLabel: string): string {
   if (!iso) return nullLabel;
@@ -65,11 +58,24 @@ function formatDateUTC(iso: string | null, nullLabel: string): string {
 }
 
 export function AdminUsersTable({ role, title, description }: AdminUsersTableProps) {
+  const { t } = useTranslation();
   const [page, setPage] = useState(1);
   const [query, setQuery] = useState("");
   const debounced = useDebounce(query, 300);
   const [sort, setSort] = useState<AdminUsersSort>("lastActiveAt:desc");
 
+  // COLUMNS rebuild per-`t` so column headers + sort aria labels
+  // follow the active UI language (#697).
+  const COLUMNS = useMemo<ColumnDef[]>(() => [
+    { id: "displayName", label: t("adminUsersTable.columnUsername"), sortAsc: "displayName:asc", sortDesc: "displayName:desc" },
+    { id: "email", label: t("adminUsersTable.columnEmail"), sortAsc: "email:asc", sortDesc: "email:desc" },
+    { id: "skillCount", label: t("adminUsersTable.columnSkills"), sortAsc: "skillCount:asc", sortDesc: "skillCount:desc", align: "right" },
+    { id: "lastActiveAt", label: t("adminUsersTable.columnLastActive"), sortAsc: "lastActiveAt:asc", sortDesc: "lastActiveAt:desc", align: "right" },
+    { id: "activityCount", label: t("adminUsersTable.columnActivities"), sortAsc: "activityCount:asc", sortDesc: "activityCount:desc", align: "right" },
+    { id: "firstJoinedAt", label: t("adminUsersTable.columnFirstJoined"), sortAsc: "firstJoinedAt:asc", sortDesc: "firstJoinedAt:desc", align: "right" },
+    { id: "actions", label: "", align: "right" },
+  ], [t]);
+
   const usersQuery = useQuery({
     queryKey: ["admin", "users", role, debounced, page, sort] as const,
     queryFn: () =>
@@ -86,7 +92,7 @@ export function AdminUsersTable({ role, title, description }: AdminUsersTablePro
   const items = usersQuery.data?.items ?? [];
   const totalPages = usersQuery.data?.totalPages ?? 1;
 
-  const toggleSort = (col: typeof COLUMNS[number]) => {
+  const toggleSort = (col: ColumnDef) => {
     if (!col.sortAsc || !col.sortDesc) return;
     if (sort === col.sortDesc) setSort(col.sortAsc);
     else setSort(col.sortDesc);
@@ -111,7 +117,7 @@ export function AdminUsersTable({ role, title, description }: AdminUsersTablePro
             setQuery(e.target.value);
             setPage(1);
           }}
-          placeholder="Filter by email or display name…"
+          placeholder={t("adminUsersTable.filterPlaceholder")}
           aria-label={`Filter ${title}`}
           className="w-full max-w-xs rounded-sm border border-subtle bg-elevated/40 px-3 py-2 font-mono text-xs text-strong placeholder:text-meta/70 focus:border-accent focus:bg-card focus:outline-none"
         />
@@ -125,7 +131,7 @@ export function AdminUsersTable({ role, title, description }: AdminUsersTablePro
             {translateError(usersQuery.error, "Failed to load users")}
           </p>
         ) : items.length === 0 ? (
-          <p className="py-8 text-center font-text text-meta">No users found.</p>
+          <p className="py-8 text-center font-text text-meta">{t("adminUsersTable.empty")}</p>
         ) : (
           <div className="overflow-x-auto">
             <table className="w-full">
@@ -145,7 +151,7 @@ export function AdminUsersTable({ role, title, description }: AdminUsersTablePro
                           <button
                             type="button"
                             onClick={() => toggleSort(col)}
-                            aria-label={`Sort by ${col.label}`}
+                            aria-label={t("adminUsersTable.sortByPrefix", { label: col.label })}
                             className={`inline-flex items-center gap-1 hover:text-accent ${
                               isAsc || isDesc ? "text-strong" : ""
                             }`}
@@ -178,7 +184,7 @@ export function AdminUsersTable({ role, title, description }: AdminUsersTablePro
                       {u.skillCount.toLocaleString()}
                     </td>
                     <td className="px-4 py-3 text-right font-mono text-[11px] text-meta">
-                      {formatDateUTC(u.lastActiveAt, "Never")}
+                      {formatDateUTC(u.lastActiveAt, t("adminUsersTable.never"))}
                     </td>
                     <td className="px-4 py-3 text-right font-mono text-[12px] text-body">
                       {u.activityCount.toLocaleString()}
@@ -191,7 +197,7 @@ export function AdminUsersTable({ role, title, description }: AdminUsersTablePro
                         to={`/admin/quota?userId=${encodeURIComponent(u.userId)}&surface=playground`}
                         className="font-mono text-[11px] uppercase tracking-[0.14em] text-accent hover:text-accent-muted"
                       >
-                        Grant quota
+                        {t("adminUsersTable.grantQuota")}
                       </Link>
                     </td>
                   </tr>
diff --git a/ornn-web/src/components/admin/settings/ProviderEditDrawer.tsx b/ornn-web/src/components/admin/settings/ProviderEditDrawer.tsx
index 29a7c62f..ac7be8c1 100644
--- a/ornn-web/src/components/admin/settings/ProviderEditDrawer.tsx
+++ b/ornn-web/src/components/admin/settings/ProviderEditDrawer.tsx
@@ -526,7 +526,8 @@ interface FieldProps {
   label: string;
   value: string;
   onChange: (v: string) => void;
-  error?: string;
+  // exactOptionalPropertyTypes (#657)
+  error?: string | undefined;
 }
 
 function Field({ label, value, onChange, error }: FieldProps) {
diff --git a/ornn-web/src/components/admin/settings/SectionShell.tsx b/ornn-web/src/components/admin/settings/SectionShell.tsx
index c87939d7..55ae1cdf 100644
--- a/ornn-web/src/components/admin/settings/SectionShell.tsx
+++ b/ornn-web/src/components/admin/settings/SectionShell.tsx
@@ -17,18 +17,17 @@ import { Skeleton } from "@/components/ui/Skeleton";
 
 export interface SectionShellProps {
   title: string;
-  description?: string;
+  // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
+  description?: string | undefined;
   children: ReactNode;
-  /** Form-level error message (e.g. server validation aggregate). */
-  error?: string | null;
-  isLoading?: boolean;
-  isSaving?: boolean;
-  isDirty?: boolean;
+  error?: string | null | undefined;
+  isLoading?: boolean | undefined;
+  isSaving?: boolean | undefined;
+  isDirty?: boolean | undefined;
   onSave: () => void;
-  onReset?: () => void;
-  /** When set, render an "updated" hint under the action row. */
-  updatedAt?: string;
-  updatedBy?: string;
+  onReset?: (() => void) | undefined;
+  updatedAt?: string | undefined;
+  updatedBy?: string | undefined;
 }
 
 function formatUpdated(iso?: string): string | null {
diff --git a/ornn-web/src/components/admin/settings/SettingsNav.tsx b/ornn-web/src/components/admin/settings/SettingsNav.tsx
index 73009480..93147398 100644
--- a/ornn-web/src/components/admin/settings/SettingsNav.tsx
+++ b/ornn-web/src/components/admin/settings/SettingsNav.tsx
@@ -12,21 +12,21 @@
 import { NavLink } from "react-router-dom";
 import { useTranslation } from "react-i18next";
 
-interface NavEntry {
+interface NavEntrySource {
   to: string;
-  label: string;
+  i18nKey: string;
 }
 
-const SECTIONS: NavEntry[] = [
-  { to: "/admin/settings/llm-providers", label: "LLM Providers" },
-  { to: "/admin/settings/playground", label: "Playground" },
-  { to: "/admin/settings/skill-generation", label: "Skill Generation" },
-  { to: "/admin/settings/mirror", label: "GitHub Mirror" },
-  { to: "/admin/settings/integrations/nyxid", label: "NyxID Integration" },
-  { to: "/admin/settings/skill-audit", label: "Skill Auditing" },
-  { to: "/admin/settings/posthog", label: "PostHog" },
-  { to: "/admin/settings/extras", label: "Service Binding List" },
-  { to: "/admin/settings/export-import", label: "Export / Import" },
+const SECTIONS: NavEntrySource[] = [
+  { to: "/admin/settings/llm-providers", i18nKey: "llmProviders" },
+  { to: "/admin/settings/playground", i18nKey: "playground" },
+  { to: "/admin/settings/skill-generation", i18nKey: "skillGeneration" },
+  { to: "/admin/settings/mirror", i18nKey: "githubMirror" },
+  { to: "/admin/settings/integrations/nyxid", i18nKey: "nyxidIntegration" },
+  { to: "/admin/settings/skill-audit", i18nKey: "skillAuditing" },
+  { to: "/admin/settings/posthog", i18nKey: "postHog" },
+  { to: "/admin/settings/extras", i18nKey: "serviceBinding" },
+  { to: "/admin/settings/export-import", i18nKey: "exportImport" },
 ];
 
 interface SettingsNavProps {
@@ -52,7 +52,7 @@ export function SettingsNav({ className = "" }: SettingsNavProps) {
             }`
           }
         >
-          {s.label}
+          {t(`adminSettingsNav.${s.i18nKey}`)}
         </NavLink>
       ))}
     </nav>
diff --git a/ornn-web/src/components/admin/settings/useSectionForm.ts b/ornn-web/src/components/admin/settings/useSectionForm.ts
index 581e777f..6c6f8cda 100644
--- a/ornn-web/src/components/admin/settings/useSectionForm.ts
+++ b/ornn-web/src/components/admin/settings/useSectionForm.ts
@@ -84,7 +84,26 @@ export function useSectionForm<T>({
     if (schema) {
       const parsed = schema.safeParse(draft);
       if (!parsed.success) {
-        setError(parsed.error.issues.map((i) => i.message).join("; "));
+        // #698 — prefix each issue with its path so admins can see
+        // which field failed instead of staring at a wall of repeated
+        // "Too small: expected string to have >=1 characters" entries.
+        // Length-1 string issues also rephrase as "is required" since
+        // that's what the form actually means for the affected sections
+        // (Mirror, NyxID Integration, etc. all use .min(1) as a
+        // required-field gate).
+        setError(
+          parsed.error.issues
+            .map((i) => {
+              const path = i.path.length > 0 ? i.path.join(".") : "";
+              const isRequiredGate =
+                i.code === "too_small" &&
+                (i as { type?: string }).type === "string" &&
+                (i as { minimum?: number }).minimum === 1;
+              const message = isRequiredGate ? "is required" : i.message;
+              return path ? `${path}: ${message}` : message;
+            })
+            .join("; "),
+        );
         return;
       }
     }
diff --git a/ornn-web/src/components/agentseal/AgentSealTrustBadge.tsx b/ornn-web/src/components/agentseal/AgentSealTrustBadge.tsx
index bc714d63..5b8b7e19 100644
--- a/ornn-web/src/components/agentseal/AgentSealTrustBadge.tsx
+++ b/ornn-web/src/components/agentseal/AgentSealTrustBadge.tsx
@@ -96,7 +96,7 @@ export function AgentSealTrustBadge({
         {},
       );
       if (res.error) {
-        const isDisabled = res.error.code === "AGENTSEAL_DISABLED";
+        const isDisabled = res.error.code === "agentseal_disabled";
         addToast({
           type: "error",
           message: isDisabled
diff --git a/ornn-web/src/components/auth/OtpInput.tsx b/ornn-web/src/components/auth/OtpInput.tsx
index d5fd2d50..62506800 100644
--- a/ornn-web/src/components/auth/OtpInput.tsx
+++ b/ornn-web/src/components/auth/OtpInput.tsx
@@ -25,6 +25,9 @@ export function OtpInput({ length = 6, onComplete, disabled, error }: OtpInputPr
   return (
     <div className="flex gap-2 justify-center">
       {Array.from({ length }).map((_, i) => (
+        // OTP cells are positional (cell N is always cell N); the parent
+        // never re-renders with a different `length`, so key={i} is
+        // intentional and reconciliation-stable (#451).
         <input
           key={i}
           type="text"
diff --git a/ornn-web/src/components/docs/DocsMarkdownComponents.tsx b/ornn-web/src/components/docs/DocsMarkdownComponents.tsx
new file mode 100644
index 00000000..05c67387
--- /dev/null
+++ b/ornn-web/src/components/docs/DocsMarkdownComponents.tsx
@@ -0,0 +1,139 @@
+/**
+ * react-markdown custom component map extracted from DocsPage (#453).
+ *
+ * Exports a single `markdownComponents` object that DocsPage spreads
+ * into `<ReactMarkdown components={...}>` plus the slug helper used by
+ * the headings. The TOC needs the same `slugify` (heading IDs must
+ * match the TOC entries), so it lives next to the heading components.
+ *
+ * Wraps `pre` with a CopyButton, swaps ` ```mermaid ` blocks to
+ * MermaidBlock, and injects `id={slug}` onto every h1-h4 so the
+ * sticky TOC's #-anchor links work.
+ *
+ * @module components/docs/DocsMarkdownComponents
+ */
+
+import { useRef, useState } from "react";
+import { MermaidBlock } from "./DocsMermaid";
+
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s\u4e00-\u9fff-]/g, "")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function CopyButton({ text }: { text: string }) {
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = async () => {
+    try {
+      await navigator.clipboard.writeText(text);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch {
+      /* clipboard may not be available */
+    }
+  };
+
+  return (
+    <button
+      type="button"
+      onClick={handleCopy}
+      className="absolute top-2 right-2 z-10 px-2 py-1 rounded text-xs font-mono transition-all cursor-pointer border border-accent/30 bg-page/80 text-meta hover:text-accent hover:border-accent/60"
+    >
+      {copied ? "Copied!" : "Copy"}
+    </button>
+  );
+}
+
+/** Wraps <pre> blocks with a relative container and copy button outside the scrollable area */
+function PreBlock({ children, ...props }: React.HTMLAttributes<HTMLPreElement>) {
+  const codeText = useRef("");
+
+  // Extract text content from children (the <code> element inside <pre>)
+  const extractText = (node: React.ReactNode): string => {
+    if (typeof node === "string") return node;
+    if (typeof node === "number") return String(node);
+    if (Array.isArray(node)) return node.map(extractText).join("");
+    if (node && typeof node === "object" && "props" in node) {
+      const el = node as { props?: { children?: React.ReactNode } };
+      return extractText(el.props?.children);
+    }
+    return "";
+  };
+
+  codeText.current = extractText(children).replace(/\n$/, "");
+
+  return (
+    <div className="relative">
+      <CopyButton text={codeText.current} />
+      <pre {...props}>{children}</pre>
+    </div>
+  );
+}
+
+function CodeBlock({
+  className,
+  children,
+  ...props
+}: React.HTMLAttributes<HTMLElement> & { children?: React.ReactNode }) {
+  const match = /language-(\w+)/.exec(className ?? "");
+  // Capture group 1 is always present on match. `!` is safe under
+  // noUncheckedIndexedAccess (#450).
+  const lang = match?.[1];
+  const code = String(children).replace(/\n$/, "");
+
+  if (lang === "mermaid") {
+    return <MermaidBlock chart={code} />;
+  }
+
+  return (
+    <code className={className} {...props}>
+      {children}
+    </code>
+  );
+}
+
+function extractTextFromChildren(children: React.ReactNode): string {
+  if (typeof children === "string") return children;
+  if (typeof children === "number") return String(children);
+  if (Array.isArray(children)) return children.map(extractTextFromChildren).join("");
+  if (children && typeof children === "object" && "props" in children) {
+    const el = children as { props?: { children?: React.ReactNode } };
+    return extractTextFromChildren(el.props?.children);
+  }
+  return "";
+}
+
+function H1({ children, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
+  const id = slugify(extractTextFromChildren(children));
+  return <h1 id={id} {...props}>{children}</h1>;
+}
+function H2({ children, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
+  const id = slugify(extractTextFromChildren(children));
+  return <h2 id={id} {...props}>{children}</h2>;
+}
+function H3({ children, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
+  const id = slugify(extractTextFromChildren(children));
+  return <h3 id={id} {...props}>{children}</h3>;
+}
+function H4({ children, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
+  const id = slugify(extractTextFromChildren(children));
+  return <h4 id={id} {...props}>{children}</h4>;
+}
+
+/**
+ * Component map to pass into `<ReactMarkdown components={...}>`.
+ * Renames `pre`/`code` and injects slug IDs on h1-h4.
+ */
+export const markdownComponents = {
+  pre: PreBlock,
+  code: CodeBlock,
+  h1: H1,
+  h2: H2,
+  h3: H3,
+  h4: H4,
+};
diff --git a/ornn-web/src/components/docs/DocsMermaid.tsx b/ornn-web/src/components/docs/DocsMermaid.tsx
new file mode 100644
index 00000000..9f9cf2d3
--- /dev/null
+++ b/ornn-web/src/components/docs/DocsMermaid.tsx
@@ -0,0 +1,244 @@
+/**
+ * Mermaid renderer + lightbox extracted from DocsPage (#453).
+ *
+ * Bundles four pieces that all coordinate around mermaid output:
+ *   - MERMAID_DARK / MERMAID_LIGHT — per-theme variables
+ *   - SandboxedSvg — `iframe sandbox=""` defence-in-depth wrapper (#440)
+ *   - MermaidLightbox — fullscreen zoom + pan + reset
+ *   - MermaidBlock — the actual `<MermaidBlock chart={...}/>` markdown component
+ *
+ * Mermaid is initialised once at import time with the user's current
+ * theme; MermaidBlock re-initialises on theme change before each
+ * render so the diagrams swap palettes alongside the rest of the UI.
+ *
+ * @module components/docs/DocsMermaid
+ */
+
+import { useEffect, useRef, useState } from "react";
+import mermaid from "mermaid";
+import { useThemeStore } from "@/stores/themeStore";
+
+const MERMAID_DARK = {
+  startOnLoad: false,
+  theme: "dark" as const,
+  themeVariables: {
+    darkMode: true,
+    primaryColor: "#FF6B00",
+    primaryTextColor: "#e8e8e8",
+    primaryBorderColor: "#FF6B00",
+    lineColor: "#FF8C38",
+    secondaryColor: "#1e1e1e",
+    tertiaryColor: "#131313",
+    background: "#0a0a0f",
+    mainBkg: "#1e1e1e",
+    nodeBorder: "#FF6B00",
+    clusterBkg: "#131313",
+    clusterBorder: "#FF6B0044",
+    titleColor: "#FF6B00",
+    edgeLabelBackground: "#0a0a0f",
+    noteTextColor: "#e8e8e8",
+    noteBkgColor: "#1e1e1e",
+    noteBorderColor: "#FF6B0044",
+    actorTextColor: "#e8e8e8",
+    actorBkg: "#1e1e1e",
+    actorBorder: "#FF6B00",
+    signalColor: "#FF8C38",
+    signalTextColor: "#e8e8e8",
+    labelTextColor: "#e8e8e8",
+    loopTextColor: "#e8e8e8",
+  },
+  fontFamily: "'JetBrains Mono', monospace",
+  fontSize: 13,
+};
+
+const MERMAID_LIGHT = {
+  startOnLoad: false,
+  theme: "base" as const,
+  themeVariables: {
+    darkMode: false,
+    primaryColor: "#d45a00",
+    primaryTextColor: "#2d2d2d",
+    primaryBorderColor: "#d45a00",
+    lineColor: "#c06000",
+    secondaryColor: "#f3f3f5",
+    tertiaryColor: "#ffffff",
+    background: "#fafafa",
+    mainBkg: "#fff5ee",
+    nodeBorder: "#d45a00",
+    clusterBkg: "#fdf6f0",
+    clusterBorder: "#d45a0044",
+    titleColor: "#b34a00",
+    edgeLabelBackground: "#fafafa",
+    noteTextColor: "#2d2d2d",
+    noteBkgColor: "#fff5ee",
+    noteBorderColor: "#d45a0044",
+    actorTextColor: "#2d2d2d",
+    actorBkg: "#fff5ee",
+    actorBorder: "#d45a00",
+    signalColor: "#c06000",
+    signalTextColor: "#2d2d2d",
+    labelTextColor: "#2d2d2d",
+    loopTextColor: "#2d2d2d",
+  },
+  fontFamily: "'JetBrains Mono', monospace",
+  fontSize: 13,
+};
+
+function getMermaidConfig(theme: "dark" | "light") {
+  return theme === "dark" ? MERMAID_DARK : MERMAID_LIGHT;
+}
+
+// Initial init with current theme.
+mermaid.initialize(getMermaidConfig(useThemeStore.getState().theme));
+
+/**
+ * Render an SVG string inside a sandboxed iframe (#440).
+ *
+ * Mermaid is the only producer today, and the diagram source comes
+ * from trusted in-repo markdown — so this is purely defence-in-depth.
+ * If any future code path ever feeds user-controlled diagram source
+ * (e.g. user-authored skill READMEs embedding ` ```mermaid `), the
+ * iframe `sandbox=""` boundary prevents script execution, form
+ * submission, navigation, and storage access without us having to
+ * audit Mermaid's output for XSS first.
+ *
+ * Layout: the iframe fills its container; the parent owns the
+ * transform/pan/zoom, so the existing lightbox interactions keep
+ * working unchanged.
+ */
+function SandboxedSvg({ svg, className }: { svg: string; className?: string }) {
+  // Strict sandbox: no scripts, no forms, no top navigation, no
+  // popups, no same-origin. The iframe can render the SVG and that's
+  // all.
+  const srcDoc = `<!doctype html><html><head><meta charset="utf-8"><style>html,body{margin:0;padding:0;background:transparent;display:flex;align-items:center;justify-content:center}svg{max-width:100%;max-height:100%;width:100%;height:100%}</style></head><body>${svg}</body></html>`;
+  return (
+    <iframe
+      sandbox=""
+      srcDoc={srcDoc}
+      title="diagram"
+      className={className}
+      style={{ width: "100%", height: "100%", border: "none", background: "transparent" }}
+    />
+  );
+}
+
+function MermaidLightbox({ svg, onClose }: { svg: string; onClose: () => void }) {
+  const viewportRef = useRef<HTMLDivElement>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
+  const [scale, setScale] = useState(1);
+  const [translate, setTranslate] = useState({ x: 0, y: 0 });
+  const dragRef = useRef({ dragging: false, startX: 0, startY: 0, originX: 0, originY: 0 });
+
+  // Zoom with scroll wheel
+  useEffect(() => {
+    const el = viewportRef.current;
+    if (!el) return;
+    const handleWheel = (e: WheelEvent) => {
+      e.preventDefault();
+      const delta = e.deltaY > 0 ? -0.1 : 0.1;
+      setScale((s) => Math.min(Math.max(0.2, s + delta), 5));
+    };
+    el.addEventListener("wheel", handleWheel, { passive: false });
+    return () => el.removeEventListener("wheel", handleWheel);
+  }, []);
+
+  // Close on Escape
+  useEffect(() => {
+    const handleKey = (e: KeyboardEvent) => { if (e.key === "Escape") onClose(); };
+    window.addEventListener("keydown", handleKey);
+    return () => window.removeEventListener("keydown", handleKey);
+  }, [onClose]);
+
+  const handlePointerDown = (e: React.PointerEvent) => {
+    if (e.target === viewportRef.current) { onClose(); return; }
+    dragRef.current = { dragging: true, startX: e.clientX, startY: e.clientY, originX: translate.x, originY: translate.y };
+    (e.target as HTMLElement).setPointerCapture?.(e.pointerId);
+  };
+
+  const handlePointerMove = (e: React.PointerEvent) => {
+    if (!dragRef.current.dragging) return;
+    const dx = e.clientX - dragRef.current.startX;
+    const dy = e.clientY - dragRef.current.startY;
+    setTranslate({ x: dragRef.current.originX + dx, y: dragRef.current.originY + dy });
+  };
+
+  const handlePointerUp = () => { dragRef.current.dragging = false; };
+
+  const handleReset = () => { setScale(1); setTranslate({ x: 0, y: 0 }); };
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/70 backdrop-blur-sm">
+      {/* Toolbar */}
+      <div className="absolute top-4 right-4 z-10 flex items-center gap-2">
+        <button type="button" onClick={() => setScale((s) => Math.min(s + 0.25, 5))} className="rounded bg-elevated px-3 py-1.5 font-mono text-sm text-strong hover:bg-accent/20 transition-colors cursor-pointer">+</button>
+        <span className="rounded bg-elevated px-3 py-1.5 font-mono text-sm text-meta min-w-[4rem] text-center">{Math.round(scale * 100)}%</span>
+        <button type="button" onClick={() => setScale((s) => Math.max(s - 0.25, 0.2))} className="rounded bg-elevated px-3 py-1.5 font-mono text-sm text-strong hover:bg-accent/20 transition-colors cursor-pointer">−</button>
+        <button type="button" onClick={handleReset} className="rounded bg-elevated px-3 py-1.5 font-mono text-sm text-strong hover:bg-accent/20 transition-colors cursor-pointer">Reset</button>
+        <button type="button" onClick={onClose} className="rounded bg-elevated px-3 py-1.5 font-mono text-sm text-strong hover:bg-accent/20 transition-colors cursor-pointer">✕</button>
+      </div>
+      {/* Viewport */}
+      <div
+        ref={viewportRef}
+        className="absolute inset-0 cursor-grab active:cursor-grabbing overflow-hidden"
+        onPointerDown={handlePointerDown}
+        onPointerMove={handlePointerMove}
+        onPointerUp={handlePointerUp}
+      >
+        <div
+          ref={contentRef}
+          className="absolute left-1/2 top-1/2 mermaid-container [&_svg]:max-w-none"
+          style={{
+            transform: `translate(-50%, -50%) translate(${translate.x}px, ${translate.y}px) scale(${scale})`,
+            transformOrigin: "center center",
+            // Fixed dimensions so the sandboxed iframe has something
+            // concrete to fill — the parent's pan/zoom transform
+            // still handles all the interaction.
+            width: "min(90vw, 80vh)",
+            height: "min(80vh, 90vw)",
+          }}
+        >
+          <SandboxedSvg svg={svg} />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+let mermaidCounter = 0;
+
+export function MermaidBlock({ chart }: { chart: string }) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [svg, setSvg] = useState<string>("");
+  const [lightboxOpen, setLightboxOpen] = useState(false);
+  const theme = useThemeStore((s) => s.theme);
+
+  useEffect(() => {
+    let cancelled = false;
+    const id = `mermaid-${++mermaidCounter}`;
+
+    // Re-initialize mermaid with current theme before rendering
+    mermaid.initialize(getMermaidConfig(theme));
+
+    mermaid.render(id, chart).then(({ svg: rendered }) => {
+      if (!cancelled) setSvg(rendered);
+    }).catch((err) => {
+      if (!cancelled) setSvg(`<pre style="color:#ff003c">Mermaid error: ${err.message}</pre>`);
+    });
+
+    return () => { cancelled = true; };
+  }, [chart, theme]);
+
+  return (
+    <>
+      <div
+        ref={containerRef}
+        className="mermaid-container group relative my-4 overflow-x-auto rounded border border-accent/10 bg-page p-4 cursor-pointer"
+        onClick={() => setLightboxOpen(true)}
+        style={{ minHeight: svg ? "240px" : undefined }}
+      >
+        {svg ? <SandboxedSvg svg={svg} /> : null}
+      </div>
+      {lightboxOpen && <MermaidLightbox svg={svg} onClose={() => setLightboxOpen(false)} />}
+    </>
+  );
+}
diff --git a/ornn-web/src/components/docs/DocsReleaseAccordion.tsx b/ornn-web/src/components/docs/DocsReleaseAccordion.tsx
new file mode 100644
index 00000000..7f1a0c73
--- /dev/null
+++ b/ornn-web/src/components/docs/DocsReleaseAccordion.tsx
@@ -0,0 +1,139 @@
+/**
+ * Release notes accordion + current-version badge, extracted from
+ * DocsPage (#453).
+ *
+ * ReleaseAccordion: collapsible list of every release, newest first.
+ * The newest one is auto-expanded on first render and tagged with a
+ * "Current"/"当前版本" eyebrow.
+ *
+ * VersionBadge: small inline badge surfaced at the top of the release
+ * notes doc — shows __APP_VERSION__ + a link to GitHub Releases.
+ *
+ * @module components/docs/DocsReleaseAccordion
+ */
+
+import { useMemo, useState } from "react";
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import rehypeHighlight from "rehype-highlight";
+import { useTranslation } from "react-i18next";
+import { getReleases, getRelease } from "@/lib/docsContent";
+
+type Lang = "en" | "zh";
+
+function ChevronIcon({ open, className }: { open: boolean; className?: string }) {
+  return (
+    <svg
+      className={`${className ?? "h-4 w-4"} transition-transform duration-200 ${open ? "rotate-90" : ""}`}
+      fill="none"
+      viewBox="0 0 24 24"
+      stroke="currentColor"
+    >
+      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
+    </svg>
+  );
+}
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s\u4e00-\u9fff-]/g, "")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+export function ReleaseAccordion({ lang }: { lang: Lang }) {
+  const releases = useMemo(() => getReleases(lang), [lang]);
+  const [expandedVersion, setExpandedVersion] = useState<string | null>(
+    () => releases[0]?.version ?? null,
+  );
+  const { t } = useTranslation();
+
+  const expandedContent = useMemo(
+    () => (expandedVersion ? getRelease(expandedVersion, lang)?.content ?? null : null),
+    [expandedVersion, lang],
+  );
+
+  const handleToggle = (version: string) => {
+    setExpandedVersion((prev) => (prev === version ? null : version));
+  };
+
+  if (releases.length === 0) return null;
+
+  return (
+    <div className="my-8">
+      <h2 id={slugify(lang === "zh" ? "已发布版本" : "released-versions")} className="font-display text-2xl font-bold text-accent mb-4">
+        {lang === "zh" ? "已发布版本" : "Released Versions"}
+      </h2>
+      <div className="space-y-2">
+        {releases.map((release, idx) => {
+          const isOpen = expandedVersion === release.version;
+          const isLatest = idx === 0;
+          return (
+            <div
+              key={release.version}
+              className="rounded border border-accent/20 overflow-hidden transition-colors hover:border-accent/40"
+            >
+              <button
+                type="button"
+                onClick={() => handleToggle(release.version)}
+                className="flex w-full items-center gap-3 px-5 py-4 text-left cursor-pointer transition-colors hover:bg-accent/5"
+              >
+                <ChevronIcon open={isOpen} className="h-4 w-4 text-meta shrink-0" />
+                <div className="flex-1 min-w-0">
+                  <span className="font-display text-base font-semibold text-strong">
+                    v{release.version}
+                  </span>
+                  <span className="font-text text-sm text-meta ml-2">
+                    — {release.title}
+                  </span>
+                  {isLatest && (
+                    <span className="ml-2 inline-block px-2 py-0.5 rounded-sm text-[10px] font-mono uppercase tracking-[0.12em] bg-accent/10 text-accent border border-accent/40">
+                      {lang === "zh" ? "当前版本" : "Current"}
+                    </span>
+                  )}
+                </div>
+                <span className="font-mono text-xs text-meta shrink-0">{release.date}</span>
+              </button>
+              {isOpen && (
+                <div className="px-5 pb-4 border-t border-accent/10">
+                  {expandedContent ? (
+                    <div className="markdown-body pt-3">
+                      <ReactMarkdown remarkPlugins={[remarkGfm]} rehypePlugins={[rehypeHighlight]}>
+                        {expandedContent}
+                      </ReactMarkdown>
+                    </div>
+                  ) : (
+                    <p className="py-4 text-meta text-sm">{t("docs.loadFailed")}</p>
+                  )}
+                </div>
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+export function VersionBadge() {
+  const releasesUrl = "https://github.com/ChronoAIProject/Ornn/releases";
+  return (
+    <div className="my-6 inline-flex flex-wrap items-center gap-3 rounded border border-accent/20 bg-elevated px-4 py-2">
+      <span className="font-mono text-[10px] uppercase tracking-[0.14em] text-meta">
+        Current version
+      </span>
+      <span className="font-mono text-base text-accent">v{__APP_VERSION__}</span>
+      <span className="text-meta">·</span>
+      <a
+        href={releasesUrl}
+        target="_blank"
+        rel="noreferrer"
+        className="font-text text-sm text-meta transition-colors hover:text-strong"
+      >
+        Release history on GitHub →
+      </a>
+    </div>
+  );
+}
diff --git a/ornn-web/src/components/docs/DocsSidebar.tsx b/ornn-web/src/components/docs/DocsSidebar.tsx
new file mode 100644
index 00000000..4f03cc9e
--- /dev/null
+++ b/ornn-web/src/components/docs/DocsSidebar.tsx
@@ -0,0 +1,112 @@
+/**
+ * Left collapsible sidebar for DocsPage (#453).
+ *
+ * Renders the doc tree (sections → children), auto-expands the
+ * section containing the active doc, and re-collapses on user click.
+ * Pure presentation — the parent owns the active doc + emits the
+ * select callback.
+ *
+ * @module components/docs/DocsSidebar
+ */
+
+import { useEffect, useState } from "react";
+import type { DocSection } from "@/lib/docsContent";
+
+function ChevronIcon({ open, className }: { open: boolean; className?: string }) {
+  return (
+    <svg
+      className={`${className ?? "h-4 w-4"} transition-transform duration-200 ${open ? "rotate-90" : ""}`}
+      fill="none"
+      viewBox="0 0 24 24"
+      stroke="currentColor"
+    >
+      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
+    </svg>
+  );
+}
+
+export interface DocsSidebarProps {
+  sections: DocSection[];
+  activeId: string;
+  onSelect: (id: string, label: string) => void;
+}
+
+export function DocsSidebar({ sections, activeId, onSelect }: DocsSidebarProps) {
+  // Initialize: expand the section that contains the active doc
+  const activeSectionId = sections.find((s) =>
+    s.children.some((c) => c.id === activeId),
+  )?.id;
+
+  const [expanded, setExpanded] = useState<Set<string>>(() => {
+    const initial = new Set<string>();
+    if (activeSectionId) initial.add(activeSectionId);
+    return initial;
+  });
+
+  // When active doc changes, ensure its section is expanded
+  useEffect(() => {
+    if (activeSectionId && !expanded.has(activeSectionId)) {
+      setExpanded((prev) => new Set(prev).add(activeSectionId));
+    }
+  }, [activeSectionId]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const toggleSection = (sectionId: string) => {
+    setExpanded((prev) => {
+      const next = new Set(prev);
+      if (next.has(sectionId)) {
+        next.delete(sectionId);
+      } else {
+        next.add(sectionId);
+      }
+      return next;
+    });
+  };
+
+  return (
+    <nav className="w-64 shrink-0 border-r border-accent/10 overflow-y-auto py-4 pr-2">
+      {sections.map((section) => {
+        const isExpanded = expanded.has(section.id);
+        return (
+          <div key={section.id} className="mb-2">
+            <button
+              type="button"
+              onClick={() => toggleSection(section.id)}
+              className="w-full flex items-center gap-2 px-3 py-2 cursor-pointer group text-left"
+            >
+              <ChevronIcon
+                open={isExpanded}
+                className="h-4 w-4 shrink-0 text-meta group-hover:text-strong transition-colors"
+              />
+              <span className="font-mono text-[11px] uppercase tracking-[0.14em] text-meta group-hover:text-strong transition-colors">
+                {section.label}
+              </span>
+            </button>
+            {isExpanded && (
+              <div className="ml-2">
+                {section.children.map((child) => {
+                  const isActive = child.id === activeId;
+                  return (
+                    <button
+                      key={child.id}
+                      type="button"
+                      onClick={() => onSelect(child.id, child.label)}
+                      className={`
+                        w-full text-left px-3 py-2 rounded-md font-text text-base transition-all duration-150 cursor-pointer
+                        ${isActive
+                          ? "text-accent bg-accent/10 border-l-2 border-accent"
+                          : "text-meta hover:text-strong hover:bg-elevated border-l-2 border-transparent"
+                        }
+                      `}
+                    >
+                      {child.label}
+                    </button>
+                  );
+                })}
+              </div>
+            )}
+          </div>
+        );
+      })}
+    </nav>
+  );
+}
diff --git a/ornn-web/src/components/docs/DocsTableOfContents.tsx b/ornn-web/src/components/docs/DocsTableOfContents.tsx
new file mode 100644
index 00000000..5f44fe8f
--- /dev/null
+++ b/ornn-web/src/components/docs/DocsTableOfContents.tsx
@@ -0,0 +1,69 @@
+/**
+ * Sticky right-rail "On this page" minimap for DocsPage (#453).
+ *
+ * Skips h1 (the doc title is already in the heading area above the
+ * article) and renders h2-h4 as indented links. The parent owns the
+ * `activeHeadingId` (scroll-spy lives in DocsPage); this component
+ * just paints + fires `onSelect` for clicks.
+ *
+ * @module components/docs/DocsTableOfContents
+ */
+
+import { useTranslation } from "react-i18next";
+
+export interface TocItem {
+  id: string;
+  text: string;
+  level: number;
+}
+
+export interface DocsTableOfContentsProps {
+  items: TocItem[];
+  activeHeadingId: string;
+  onSelect: (id: string) => void;
+}
+
+export function DocsTableOfContents({
+  items,
+  activeHeadingId,
+  onSelect,
+}: DocsTableOfContentsProps) {
+  const { t } = useTranslation();
+
+  if (items.length === 0) return null;
+
+  // Skip the h1 (doc title) — show only h2+ in TOC
+  const tocItems = items.filter((item) => item.level >= 2);
+  if (tocItems.length === 0) return null;
+
+  return (
+    <nav className="w-56 shrink-0 sticky top-0 self-start overflow-y-auto max-h-[calc(100vh-8rem)] py-4 pl-4">
+      <h4 className="font-mono text-[10px] uppercase tracking-[0.16em] text-meta px-2 py-1.5 mb-2">
+        {t("docs.onThisPage")}
+      </h4>
+      <div className="space-y-0.5 border-l border-accent/10">
+        {tocItems.map((item) => {
+          const isActive = item.id === activeHeadingId;
+          const indent = item.level === 2 ? "pl-3" : item.level === 3 ? "pl-6" : "pl-9";
+          return (
+            <button
+              key={item.id}
+              type="button"
+              onClick={() => onSelect(item.id)}
+              className={`
+                w-full text-left py-1.5 ${indent} font-text text-base leading-snug transition-colors duration-150 cursor-pointer truncate
+                ${isActive
+                  ? "text-accent border-l-2 border-accent -ml-px"
+                  : "text-meta hover:text-strong"
+                }
+              `}
+              title={item.text}
+            >
+              {item.text}
+            </button>
+          );
+        })}
+      </div>
+    </nav>
+  );
+}
diff --git a/ornn-web/src/components/editor/CodeEditor.tsx b/ornn-web/src/components/editor/CodeEditor.tsx
index 94a179b9..ae312f93 100644
--- a/ornn-web/src/components/editor/CodeEditor.tsx
+++ b/ornn-web/src/components/editor/CodeEditor.tsx
@@ -195,6 +195,8 @@ function TextAreaEditor({ content, onChange, onSave, readOnly }: TextAreaEditorP
         className="shrink-0 w-12 py-4 pr-2 text-right border-r border-accent/10 bg-card/30 overflow-hidden select-none"
       >
         {Array.from({ length: lineCount }).map((_, i) => (
+          // Line numbers are positional (line N == row index N); never
+          // reorder, key={i} is intentional (#451).
           <div
             key={i}
             className="font-mono text-xs text-meta/50 leading-6 h-6"
@@ -341,7 +343,10 @@ export function useEditorState(_initialFiles: { id: string; name: string; conten
     setTabs((prev) => {
       const newTabs = prev.filter((t) => t.id !== tabId);
       if (activeTabId === tabId && newTabs.length > 0) {
-        setActiveTabId(newTabs[newTabs.length - 1].id);
+        // Length-guarded above — newTabs.length > 0 means index
+        // length-1 is valid. `!` is safe under noUncheckedIndexedAccess
+        // (#450).
+        setActiveTabId(newTabs[newTabs.length - 1]!.id);
       } else if (newTabs.length === 0) {
         setActiveTabId("");
       }
diff --git a/ornn-web/src/components/editor/FileTree.tsx b/ornn-web/src/components/editor/FileTree.tsx
index 5905a7ba..0ac77b48 100644
--- a/ornn-web/src/components/editor/FileTree.tsx
+++ b/ornn-web/src/components/editor/FileTree.tsx
@@ -19,13 +19,14 @@ export interface FileNode {
 
 export interface FileTreeProps {
   files: FileNode[];
-  selectedId?: string;
+  // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
+  selectedId?: string | undefined;
   onSelect: (file: FileNode) => void;
-  onCreateFile?: (parentId: string | null, name: string) => void;
-  onCreateFolder?: (parentId: string | null, name: string) => void;
-  onDelete?: (id: string) => void;
-  onRename?: (id: string, newName: string) => void;
-  className?: string;
+  onCreateFile?: ((parentId: string | null, name: string) => void) | undefined;
+  onCreateFolder?: ((parentId: string | null, name: string) => void) | undefined;
+  onDelete?: ((id: string) => void) | undefined;
+  onRename?: ((id: string, newName: string) => void) | undefined;
+  className?: string | undefined;
 }
 
 /** File icon */
@@ -88,18 +89,19 @@ function TrashIcon({ className }: { className?: string }) {
 interface TreeNodeProps {
   node: FileNode;
   level: number;
-  selectedId?: string;
+  // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
+  selectedId?: string | undefined;
   expandedIds: Set<string>;
   onSelect: (file: FileNode) => void;
   onToggle: (id: string) => void;
-  onCreateFile?: (parentId: string | null) => void;
-  onDelete?: (id: string) => void;
+  onCreateFile?: ((parentId: string | null) => void) | undefined;
+  onDelete?: ((id: string) => void) | undefined;
   /** Currently active creation state */
-  creatingState?: { type: "file" | "folder"; parentId: string | null } | null;
-  newItemName?: string;
-  onNewItemNameChange?: (name: string) => void;
-  onConfirmCreate?: () => void;
-  onCancelCreate?: () => void;
+  creatingState?: { type: "file" | "folder"; parentId: string | null } | null | undefined;
+  newItemName?: string | undefined;
+  onNewItemNameChange?: ((name: string) => void) | undefined;
+  onConfirmCreate?: (() => void) | undefined;
+  onCancelCreate?: (() => void) | undefined;
 }
 
 function TreeNode({
@@ -258,8 +260,8 @@ function TreeNode({
  */
 function computeInitialExpanded(files: FileNode[]): Set<string> {
   const ids = new Set<string>(["root"]);
-  if (files.length === 1 && files[0].type === "folder") {
-    ids.add(files[0].id);
+  if (files.length === 1 && files[0]!.type === "folder") {
+    ids.add(files[0]!.id);
   }
   return ids;
 }
@@ -281,8 +283,8 @@ export function FileTree({
     setExpandedIds((prev) => {
       const next = new Set(prev);
       next.add("root");
-      if (files.length === 1 && files[0].type === "folder") {
-        next.add(files[0].id);
+      if (files.length === 1 && files[0]!.type === "folder") {
+        next.add(files[0]!.id);
       }
       return next;
     });
diff --git a/ornn-web/src/components/form/FolderFileUpload.test.tsx b/ornn-web/src/components/form/FolderFileUpload.test.tsx
new file mode 100644
index 00000000..74aa6e29
--- /dev/null
+++ b/ornn-web/src/components/form/FolderFileUpload.test.tsx
@@ -0,0 +1,118 @@
+/**
+ * FolderFileUpload tests — pins the #655 upload-validation contract.
+ *
+ * What we lock in:
+ *   1. Duplicate filename inside the SAME target folder → rejected,
+ *      inline error visible, parent's `onUpload` never called.
+ *   2. Duplicate filename in a DIFFERENT folder is allowed (they end
+ *      up as different paths in the final ZIP).
+ *   3. File over 10 MiB → rejected with size-cap error, `onUpload`
+ *      not called.
+ *   4. Successful upload clears any prior error.
+ *
+ * @module components/form/FolderFileUpload.test
+ */
+import { describe, it, expect, vi } from "vitest";
+import { render, fireEvent, screen } from "@testing-library/react";
+import { FolderFileUpload } from "./FolderFileUpload";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string, opts?: Record<string, unknown>) => {
+      if (!opts) return key;
+      // Echo back something searchable for the assertions.
+      const parts = Object.entries(opts).map(([k, v]) => `${k}=${v}`).join(" ");
+      return `${key} (${parts})`;
+    },
+  }),
+}));
+
+function makeFile(name: string, sizeBytes: number, type = "text/plain"): File {
+  // jsdom File supports a `size` property derived from the parts; pad
+  // with a zero-filled string of the requested length.
+  const blob = new Blob([new Uint8Array(sizeBytes)], { type });
+  return new File([blob], name, { type });
+}
+
+function setup(initial?: Map<string, File[]>) {
+  const onUpload = vi.fn();
+  const onRemove = vi.fn();
+  // The component expects `Map<UploadableFolder, File[]>`. Cast for
+  // test ergonomics — runtime shape is the same.
+  const files = (initial ?? new Map()) as unknown as Map<
+    "scripts" | "references" | "assets",
+    File[]
+  >;
+  const utils = render(
+    <FolderFileUpload
+      files={files as Map<"scripts" | "references" | "assets", File[]>}
+      onUpload={onUpload}
+      onRemove={onRemove}
+    />,
+  );
+  const hiddenInput = utils.container.querySelector('input[type="file"]') as HTMLInputElement;
+  return { onUpload, onRemove, hiddenInput, ...utils };
+}
+
+describe("FolderFileUpload (#655)", () => {
+  it("accepts a fresh file under the size cap", () => {
+    const { onUpload, hiddenInput } = setup();
+    const file = makeFile("run.js", 1024);
+    fireEvent.change(hiddenInput, { target: { files: [file] } });
+    expect(onUpload).toHaveBeenCalledTimes(1);
+    expect(onUpload).toHaveBeenCalledWith("scripts", file);
+  });
+
+  it("rejects a duplicate filename in the same folder", () => {
+    const existing = makeFile("run.js", 100);
+    const { onUpload, hiddenInput } = setup(
+      new Map([["scripts", [existing]]]) as never,
+    );
+    const dup = makeFile("run.js", 200);
+    fireEvent.change(hiddenInput, { target: { files: [dup] } });
+    expect(onUpload).not.toHaveBeenCalled();
+    expect(screen.getByText(/guided\.fileDuplicate/)).toBeInTheDocument();
+  });
+
+  it("allows the same filename in a DIFFERENT folder", () => {
+    // `README.md` in scripts/ is fine even if references/ has one too —
+    // they're separate paths in the final ZIP.
+    const existing = makeFile("README.md", 100);
+    const { onUpload, hiddenInput, container } = setup(
+      new Map([["references", [existing]]]) as never,
+    );
+    // Default selected folder is `scripts`, so this should pass.
+    const sameName = makeFile("README.md", 200);
+    fireEvent.change(hiddenInput, { target: { files: [sameName] } });
+    expect(onUpload).toHaveBeenCalledWith("scripts", sameName);
+    expect(container.textContent).not.toMatch(/guided\.fileDuplicate/);
+  });
+
+  it("rejects an over-cap file", () => {
+    const { onUpload, hiddenInput } = setup();
+    const huge = makeFile("blob.bin", 11 * 1024 * 1024);
+    fireEvent.change(hiddenInput, { target: { files: [huge] } });
+    expect(onUpload).not.toHaveBeenCalled();
+    expect(screen.getByText(/guided\.fileTooLarge/)).toBeInTheDocument();
+  });
+
+  it("clears the error on next successful upload", () => {
+    const { onUpload, hiddenInput } = setup();
+    // Trigger a size-cap rejection.
+    fireEvent.change(hiddenInput, {
+      target: { files: [makeFile("blob.bin", 11 * 1024 * 1024)] },
+    });
+    expect(screen.getByText(/guided\.fileTooLarge/)).toBeInTheDocument();
+    // Now a valid upload — error must clear.
+    fireEvent.change(hiddenInput, {
+      target: { files: [makeFile("ok.js", 100)] },
+    });
+    expect(onUpload).toHaveBeenCalledTimes(1);
+    expect(screen.queryByText(/guided\.fileTooLarge/)).not.toBeInTheDocument();
+  });
+
+  it("always shows the size-limit hint so the cap is discoverable pre-upload", () => {
+    setup();
+    expect(screen.getByText(/guided\.fileSizeHint/)).toBeInTheDocument();
+  });
+});
diff --git a/ornn-web/src/components/form/FolderFileUpload.tsx b/ornn-web/src/components/form/FolderFileUpload.tsx
index 4884bc33..59c525bc 100644
--- a/ornn-web/src/components/form/FolderFileUpload.tsx
+++ b/ornn-web/src/components/form/FolderFileUpload.tsx
@@ -2,6 +2,28 @@
  * Folder File Upload Component.
  * Upload files with target folder selection for skill packages.
  * Used in Guided Step 3 and Generative Mode review.
+ *
+ * #655 — the upload accepted any file regardless of name or size:
+ * duplicates in the same target folder stacked silently and a 55 MB
+ * file went through without a warning. Added two guards inside
+ * `handleFileSelect`, so both the click and drop paths are covered:
+ *
+ *   1. Duplicate filename inside the same target folder is rejected
+ *      with an inline `<name> already exists in <folder>/` error. The
+ *      user picks Remove on the existing chip if they really want to
+ *      replace it — auto-overwrite would silently drop unsaved
+ *      content.
+ *   2. Per-file size cap of 10 MiB. The backend / ZIP pipeline caps
+ *      total uncompressed at ~100 MB (#443 / #633); per-file 10 MiB
+ *      keeps a single oversize artifact from eating the whole budget
+ *      and signals the limit before the user assembles a doomed
+ *      package.
+ *
+ * Both errors render under the drop zone with `aria-live="polite"`,
+ * auto-clear on the next successful upload, and explicitly do NOT
+ * call `onUpload` — the parent state stays untouched on rejection so
+ * there's nothing for the user to undo.
+ *
  * @module components/form/FolderFileUpload
  */
 
@@ -27,6 +49,13 @@ const FOLDER_LABELS: Record<UploadableFolder, string> = {
   assets: "assets/",
 };
 
+/**
+ * Per-file size cap (#655). 10 MiB. Backend caps total uncompressed at
+ * ~100 MB; per-file 10 MiB keeps a single oversize artifact from
+ * eating the whole package budget and signals the limit early.
+ */
+const MAX_FILE_SIZE_BYTES = 10 * 1024 * 1024;
+
 export function FolderFileUpload({
   files,
   onUpload,
@@ -36,13 +65,41 @@ export function FolderFileUpload({
   const { t } = useTranslation();
   const [selectedFolder, setSelectedFolder] = useState<UploadableFolder>("scripts");
   const [isDragging, setIsDragging] = useState(false);
+  const [uploadError, setUploadError] = useState<string | null>(null);
   const inputRef = useRef<HTMLInputElement>(null);
 
   const handleFileSelect = useCallback(
     (file: File) => {
+      // #655 guard 1 — size cap. Reject before the parent ever sees
+      // the file, so its package-state stays clean.
+      if (file.size > MAX_FILE_SIZE_BYTES) {
+        setUploadError(
+          t("guided.fileTooLarge", {
+            name: file.name,
+            size: formatFileSize(file.size),
+            max: formatFileSize(MAX_FILE_SIZE_BYTES),
+          }),
+        );
+        return;
+      }
+      // #655 guard 2 — duplicate filename inside the SAME target
+      // folder. Cross-folder duplicates are fine (a `README.md` can
+      // live in references/ even if scripts/ has one too — they
+      // become different paths in the final ZIP).
+      const existing = files.get(selectedFolder) ?? [];
+      if (existing.some((f) => f.name === file.name)) {
+        setUploadError(
+          t("guided.fileDuplicate", {
+            name: file.name,
+            folder: FOLDER_LABELS[selectedFolder],
+          }),
+        );
+        return;
+      }
+      setUploadError(null);
       onUpload(selectedFolder, file);
     },
-    [selectedFolder, onUpload],
+    [selectedFolder, onUpload, files, t],
   );
 
   const handleDrop = useCallback(
@@ -74,7 +131,12 @@ export function FolderFileUpload({
             <button
               key={folder}
               type="button"
-              onClick={() => setSelectedFolder(folder)}
+              onClick={() => {
+                setSelectedFolder(folder);
+                // Folder switch is a fresh context — drop any stale
+                // error from a previous folder's reject.
+                setUploadError(null);
+              }}
               className={`
                 px-4 py-2 rounded font-mono text-sm transition-all cursor-pointer
                 ${
@@ -117,6 +179,25 @@ export function FolderFileUpload({
         />
       </div>
 
+      {/* Inline upload error — reserved for the live transient
+          reject. Cleared on the next successful upload or folder
+          switch. */}
+      {uploadError && (
+        <p
+          className="font-text text-xs text-danger"
+          aria-live="polite"
+          role="alert"
+        >
+          {uploadError}
+        </p>
+      )}
+
+      {/* Per-file size hint — always visible so users know the cap
+          before they pick the file. */}
+      <p className="font-text text-[11px] text-meta/60">
+        {t("guided.fileSizeHint", { max: formatFileSize(MAX_FILE_SIZE_BYTES) })}
+      </p>
+
       {/* File list grouped by folder */}
       <div className="space-y-4">
         {UPLOADABLE_FOLDERS.map((folder) => {
diff --git a/ornn-web/src/components/form/MarkdownEditor.tsx b/ornn-web/src/components/form/MarkdownEditor.tsx
index 41de5f38..8e8abb52 100644
--- a/ornn-web/src/components/form/MarkdownEditor.tsx
+++ b/ornn-web/src/components/form/MarkdownEditor.tsx
@@ -16,17 +16,14 @@ import rehypeHighlight from "rehype-highlight";
 export interface MarkdownEditorProps {
   value: string;
   onChange: (value: string) => void;
-  placeholder?: string;
-  label?: string;
-  error?: string;
-  /** Minimum rows for textarea */
-  minRows?: number;
-  /** Maximum rows for textarea */
-  maxRows?: number;
-  /** Whether to show preview toggle */
-  showPreview?: boolean;
-  /** Additional CSS classes */
-  className?: string;
+  // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
+  placeholder?: string | undefined;
+  label?: string | undefined;
+  error?: string | undefined;
+  minRows?: number | undefined;
+  maxRows?: number | undefined;
+  showPreview?: boolean | undefined;
+  className?: string | undefined;
 }
 
 /** Bold icon */
@@ -272,7 +269,7 @@ export function MarkdownEditor({
               ) : (
                 <>
                   <PreviewIcon className="h-4 w-4" />
-                  <span className="hidden sm:inline">Preview</span>
+                  <span className="hidden sm:inline">{t("markdownEditor.preview")}</span>
                 </>
               )}
             </button>
@@ -301,7 +298,7 @@ export function MarkdownEditor({
                 </div>
               ) : (
                 <p className="text-meta font-text text-sm italic">
-                  Nothing to preview yet...
+                  {t("markdownEditor.emptyPreview")}
                 </p>
               )}
             </motion.div>
@@ -337,7 +334,7 @@ export function MarkdownEditor({
 
       {/* Help text */}
       <p className="text-xs text-meta font-text">
-        Supports Markdown formatting. Use **bold**, _italic_, `code`, and more.
+        {t("markdownEditor.helpText")}
       </p>
     </div>
   );
diff --git a/ornn-web/src/components/form/MultiValueInput.tsx b/ornn-web/src/components/form/MultiValueInput.tsx
index 4984ca1d..bbe967f1 100644
--- a/ornn-web/src/components/form/MultiValueInput.tsx
+++ b/ornn-web/src/components/form/MultiValueInput.tsx
@@ -15,20 +15,14 @@ export interface MultiValueInputProps {
   values: string[];
   /** Callback when values change */
   onChange: (values: string[]) => void;
-  /** Input placeholder text */
-  placeholder?: string;
-  /** Helper text shown below the input */
-  helperText?: string;
-  /** Badge color for value chips */
+  // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
+  placeholder?: string | undefined;
+  helperText?: string | undefined;
   badgeColor?: BadgeProps["color"];
-  /** Per-value validation function. Return null if valid, or an error message string. */
-  validate?: (value: string) => string | null;
-  /** Error message from form validation */
-  error?: string;
-  /** Maximum number of values */
-  max?: number;
-  /** Additional CSS classes */
-  className?: string;
+  validate?: ((value: string) => string | null) | undefined;
+  error?: string | undefined;
+  max?: number | undefined;
+  className?: string | undefined;
 }
 
 export function MultiValueInput({
@@ -90,7 +84,9 @@ export function MultiValueInput({
       addValue(input);
     }
     if (e.key === "Backspace" && !input && values.length > 0) {
-      removeValue(values[values.length - 1]);
+      // Length-guarded — `values.length > 0` makes index length-1 valid.
+      // `!` is safe under noUncheckedIndexedAccess (#450).
+      removeValue(values[values.length - 1]!);
     }
   };
 
diff --git a/ornn-web/src/components/form/RuntimeSelect.tsx b/ornn-web/src/components/form/RuntimeSelect.tsx
index 4696d534..f49174d1 100644
--- a/ornn-web/src/components/form/RuntimeSelect.tsx
+++ b/ornn-web/src/components/form/RuntimeSelect.tsx
@@ -11,8 +11,9 @@ import { AVAILABLE_RUNTIMES, RUNTIME_INFO } from "@/utils/constants";
 export interface RuntimeSelectProps {
   selected: string[];
   onChange: (selected: string[]) => void;
-  error?: string;
-  className?: string;
+  // exactOptionalPropertyTypes (#657)
+  error?: string | undefined;
+  className?: string | undefined;
 }
 
 export function RuntimeSelect({
diff --git a/ornn-web/src/components/form/TagInput.test.tsx b/ornn-web/src/components/form/TagInput.test.tsx
new file mode 100644
index 00000000..a03f7e6d
--- /dev/null
+++ b/ornn-web/src/components/form/TagInput.test.tsx
@@ -0,0 +1,88 @@
+/**
+ * TagInput tests — pins the #650 / #653 duplicate-handling contract.
+ *
+ * What we lock in:
+ *   1. Adding a fresh tag commits and clears the input.
+ *   2. A duplicate is rejected, the input is cleared, AND an
+ *      `Already added` message renders (the bug was: silent reject
+ *      + stale input concatenating onto the next keystroke).
+ *   3. Typing after the duplicate clears the error so it never
+ *      blocks editing.
+ *   4. Empty / whitespace-only submissions are silently ignored.
+ *
+ * @module components/form/TagInput.test
+ */
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { TagInput } from "./TagInput";
+
+function setup(initial: string[] = []) {
+  const onChange = vi.fn();
+  const utils = render(<TagInput tags={initial} onChange={onChange} />);
+  const input = utils.container.querySelector("input")!;
+  return { onChange, input, ...utils };
+}
+
+describe("TagInput", () => {
+  it("adds a new tag on Enter and clears the input", () => {
+    const { onChange, input } = setup([]);
+    fireEvent.change(input, { target: { value: "alpha" } });
+    fireEvent.keyDown(input, { key: "Enter" });
+    expect(onChange).toHaveBeenCalledWith(["alpha"]);
+    expect(input.value).toBe("");
+  });
+
+  it("rejects a duplicate, clears the input, AND surfaces 'Already added'", () => {
+    // #650 — input must be cleared so the next keystroke doesn't
+    // concatenate onto the rejected value.
+    // #653 — the rejection must be visible to the user.
+    const { onChange, input } = setup(["alpha"]);
+    fireEvent.change(input, { target: { value: "alpha" } });
+    fireEvent.keyDown(input, { key: "Enter" });
+
+    expect(onChange).not.toHaveBeenCalled();
+    expect(input.value).toBe("");
+    expect(screen.getByText("Already added")).toBeInTheDocument();
+  });
+
+  it("normalizes case + whitespace before the duplicate check", () => {
+    const { onChange, input } = setup(["alpha"]);
+    fireEvent.change(input, { target: { value: "  ALPHA  " } });
+    fireEvent.keyDown(input, { key: "Enter" });
+    expect(onChange).not.toHaveBeenCalled();
+    expect(screen.getByText("Already added")).toBeInTheDocument();
+  });
+
+  it("clears the transient error as soon as the user keeps typing", () => {
+    const { input } = setup(["alpha"]);
+    fireEvent.change(input, { target: { value: "alpha" } });
+    fireEvent.keyDown(input, { key: "Enter" });
+    expect(screen.getByText("Already added")).toBeInTheDocument();
+
+    fireEvent.change(input, { target: { value: "b" } });
+    expect(screen.queryByText("Already added")).not.toBeInTheDocument();
+  });
+
+  it("silently ignores empty / whitespace-only Enter", () => {
+    const { onChange, input } = setup([]);
+    fireEvent.change(input, { target: { value: "   " } });
+    fireEvent.keyDown(input, { key: "Enter" });
+    expect(onChange).not.toHaveBeenCalled();
+    expect(input.value).toBe("");
+    expect(screen.queryByText("Already added")).not.toBeInTheDocument();
+  });
+
+  it("commits on comma too (parity with Enter)", () => {
+    const { onChange, input } = setup([]);
+    fireEvent.change(input, { target: { value: "beta" } });
+    fireEvent.keyDown(input, { key: "," });
+    expect(onChange).toHaveBeenCalledWith(["beta"]);
+    expect(input.value).toBe("");
+  });
+
+  it("Backspace on empty input removes the last tag", () => {
+    const { onChange, input } = setup(["alpha", "beta"]);
+    fireEvent.keyDown(input, { key: "Backspace" });
+    expect(onChange).toHaveBeenCalledWith(["alpha"]);
+  });
+});
diff --git a/ornn-web/src/components/form/TagInput.tsx b/ornn-web/src/components/form/TagInput.tsx
index eb170169..734492ac 100644
--- a/ornn-web/src/components/form/TagInput.tsx
+++ b/ornn-web/src/components/form/TagInput.tsx
@@ -1,3 +1,25 @@
+/**
+ * TagInput — multi-value tag input with a soft duplicate guard.
+ *
+ * Used by SkillForm + the Guided-create StepBasicInfo to collect
+ * `metadata.tag` entries. Tags are normalized to `trim().toLowerCase()`
+ * before insertion so casing + whitespace differences don't slip through
+ * the dup check.
+ *
+ * #650 / #653 — on Enter (or `,`) with a duplicate, the input was
+ * silently rejected: no error and the rejected text stayed in the
+ * field. Typing the next tag concatenated onto the stale value
+ * (`alpha` → `alpha` rejected → `beta` typed → result `alphabeta`).
+ * Fixed by:
+ *   1. Clearing the input on duplicate (nothing to fix — the existing
+ *      tag is already valid), matching the success path.
+ *   2. Surfacing a transient `Already added` error below the field,
+ *      mirroring `MultiValueInput`'s feedback wording so the two
+ *      multi-value inputs read the same.
+ * The error clears on the next keystroke so it never blocks typing.
+ *
+ * @module components/form/TagInput
+ */
 import { useState, useCallback } from "react";
 import { Badge, type BadgeProps } from "@/components/ui/Badge";
 import { MAX_TAGS } from "@/utils/constants";
@@ -14,26 +36,52 @@ function getTagColor(tag: string): BadgeProps["color"] {
 export interface TagInputProps {
   tags: string[];
   onChange: (tags: string[]) => void;
-  error?: string;
-  className?: string;
+  // exactOptionalPropertyTypes (#657)
+  error?: string | undefined;
+  className?: string | undefined;
 }
 
 export function TagInput({ tags, onChange, error, className = "" }: TagInputProps) {
   const [input, setInput] = useState("");
+  const [inputError, setInputError] = useState<string | null>(null);
 
   const addTag = useCallback(
     (value: string) => {
       const trimmed = value.trim().toLowerCase();
-      if (!trimmed || tags.includes(trimmed) || tags.length >= MAX_TAGS) return;
+      // Empty after trim — silently swallow; nothing to flag, the user
+      // just pressed Enter on whitespace.
+      if (!trimmed) {
+        setInput("");
+        return;
+      }
+      // Max guard is also enforced by the disabled input below, but keep
+      // a defensive branch in case the prop is wired to bypass the UI
+      // (e.g. paste-then-Enter while at the cap).
+      if (tags.length >= MAX_TAGS) {
+        setInputError(`Maximum ${MAX_TAGS} tags`);
+        setInput("");
+        return;
+      }
+      if (tags.includes(trimmed)) {
+        // #650 + #653 — surface the rejection AND clear the input so
+        // the next keystroke doesn't concatenate onto the stale value.
+        setInputError("Already added");
+        setInput("");
+        return;
+      }
+      setInputError(null);
       onChange([...tags, trimmed]);
       setInput("");
     },
-    [tags, onChange]
+    [tags, onChange],
   );
 
   const removeTag = useCallback(
-    (tag: string) => onChange(tags.filter((t) => t !== tag)),
-    [tags, onChange]
+    (tag: string) => {
+      setInputError(null);
+      onChange(tags.filter((t) => t !== tag));
+    },
+    [tags, onChange],
   );
 
   const handleKeyDown = (e: React.KeyboardEvent) => {
@@ -42,10 +90,15 @@ export function TagInput({ tags, onChange, error, className = "" }: TagInputProp
       addTag(input);
     }
     if (e.key === "Backspace" && !input && tags.length > 0) {
-      removeTag(tags[tags.length - 1]);
+      removeTag(tags[tags.length - 1]!);
     }
   };
 
+  // Prefer the live transient error (`inputError`) over the form-level
+  // `error` prop so the user sees feedback for the action they just
+  // took, not a stale parent-level message.
+  const displayError = inputError ?? error;
+
   return (
     <div className={`flex flex-col gap-1.5 ${className}`}>
       <label className="font-display text-xs uppercase tracking-wider text-meta">
@@ -67,14 +120,19 @@ export function TagInput({ tags, onChange, error, className = "" }: TagInputProp
         <input
           type="text"
           value={input}
-          onChange={(e) => setInput(e.target.value)}
+          onChange={(e) => {
+            setInput(e.target.value);
+            // Any keystroke means the user is acting on the feedback;
+            // drop the transient error so it doesn't linger.
+            if (inputError) setInputError(null);
+          }}
           onKeyDown={handleKeyDown}
           placeholder={tags.length < MAX_TAGS ? "Type + Enter" : "Max tags reached"}
           disabled={tags.length >= MAX_TAGS}
           className="min-w-[100px] flex-1 border-none bg-transparent font-text text-sm text-strong outline-none placeholder:text-meta/50"
         />
       </div>
-      {error && <span className="text-xs text-danger">{error}</span>}
+      {displayError && <span className="text-xs text-danger">{displayError}</span>}
     </div>
   );
 }
diff --git a/ornn-web/src/components/form/ToolsInput.tsx b/ornn-web/src/components/form/ToolsInput.tsx
index 4d15f01b..6514abc3 100644
--- a/ornn-web/src/components/form/ToolsInput.tsx
+++ b/ornn-web/src/components/form/ToolsInput.tsx
@@ -12,8 +12,9 @@ import { SUGGESTED_TOOLS } from "@/utils/constants";
 export interface ToolsInputProps {
   tools: string[];
   onChange: (tools: string[]) => void;
-  error?: string;
-  className?: string;
+  // exactOptionalPropertyTypes (#657)
+  error?: string | undefined;
+  className?: string | undefined;
 }
 
 export function ToolsInput({ tools, onChange, error, className = "" }: ToolsInputProps) {
@@ -41,7 +42,7 @@ export function ToolsInput({ tools, onChange, error, className = "" }: ToolsInpu
       addTool(input);
     }
     if (e.key === "Backspace" && !input && tools.length > 0) {
-      removeTool(tools[tools.length - 1]);
+      removeTool(tools[tools.length - 1]!);
     }
   };
 
diff --git a/ornn-web/src/components/layout/PageTransition.tsx b/ornn-web/src/components/layout/PageTransition.tsx
index 28a9122c..986b3ada 100644
--- a/ornn-web/src/components/layout/PageTransition.tsx
+++ b/ornn-web/src/components/layout/PageTransition.tsx
@@ -112,7 +112,9 @@ export function PageTransition({
       variants={variants}
       initial="initial"
       animate="animate"
-      exit={exitAnimation ? "exit" : undefined}
+      // exactOptionalPropertyTypes (#657): conditional spread on exit
+      // since framer-motion's `exit?:` doesn't accept explicit undefined.
+      {...(exitAnimation ? { exit: "exit" } : {})}
       transition={transition}
       className={`h-full ${className}`}
     >
diff --git a/ornn-web/src/components/layout/RootLayout.tsx b/ornn-web/src/components/layout/RootLayout.tsx
index 0477f39e..a9c0078a 100644
--- a/ornn-web/src/components/layout/RootLayout.tsx
+++ b/ornn-web/src/components/layout/RootLayout.tsx
@@ -141,7 +141,11 @@ export function RootLayout() {
             {crumbs.map((crumb, i) => {
               const isLast = i === crumbs.length - 1;
               return (
-                <span key={i} className="flex items-center gap-2">
+                // Breadcrumbs can re-shape when the route changes — use
+                // the crumb destination as a stable key so reconciliation
+                // doesn't preserve hover/focus state on the wrong segment
+                // when the trail length changes (#451).
+                <span key={`${crumb.to ?? ""}-${crumb.label}`} className="flex items-center gap-2">
                   {i > 0 && (
                     <span className="text-meta opacity-50 select-none">/</span>
                   )}
diff --git a/ornn-web/src/components/layout/Sidebar.tsx b/ornn-web/src/components/layout/Sidebar.tsx
index 01cedbe1..348736dd 100644
--- a/ornn-web/src/components/layout/Sidebar.tsx
+++ b/ornn-web/src/components/layout/Sidebar.tsx
@@ -128,7 +128,7 @@ export function Sidebar({
       {isMobile && (
         <div className="flex h-14 items-center justify-between border-b border-subtle px-4">
           <span className="font-display text-sm uppercase tracking-wider text-accent">
-            Navigation
+            {t("sidebar.navigation")}
           </span>
           <button
             type="button"
diff --git a/ornn-web/src/components/playground/ChatInput.test.tsx b/ornn-web/src/components/playground/ChatInput.test.tsx
new file mode 100644
index 00000000..349330f4
--- /dev/null
+++ b/ornn-web/src/components/playground/ChatInput.test.tsx
@@ -0,0 +1,117 @@
+/**
+ * ChatInput tests — pins the #654 length-cap contract.
+ *
+ * What we lock in:
+ *   1. `maxLength` is applied to the textarea (browser-side hard cap).
+ *   2. Counter is hidden during normal-length editing (no chrome).
+ *   3. Counter appears once the input crosses the warn threshold and
+ *      shows `<n> / <max>`.
+ *   4. Send button stays enabled within the limit.
+ *   5. Over-limit input flips the counter to the over-limit message
+ *      AND disables the send button.
+ *
+ * The over-limit case is forced by injecting `value` past `maxLength`
+ * via the imperative `setValue` handle (the textarea's `maxLength`
+ * would otherwise block direct typing past the cap — which is exactly
+ * the desired behaviour but inconvenient for this test).
+ *
+ * @module components/playground/ChatInput.test
+ */
+import { describe, it, expect, vi } from "vitest";
+import { createRef } from "react";
+import { act, render, fireEvent, screen } from "@testing-library/react";
+import { ChatInput, type ChatInputHandle } from "./ChatInput";
+
+// Minimal i18n stub — `useTranslation()` returns `t(key, opts)` that
+// echoes the key (with interpolated values for the count messages).
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string, opts?: Record<string, unknown>) => {
+      if (!opts) return key;
+      const c = opts.count !== undefined ? String(opts.count) : "";
+      const m = opts.max !== undefined ? String(opts.max) : "";
+      if (key === "chatInput.charCount") return `${c} / ${m}`;
+      if (key === "chatInput.overLimit") return `over (max ${m})`;
+      return key;
+    },
+  }),
+}));
+
+function setup(overrides: Partial<React.ComponentProps<typeof ChatInput>> = {}) {
+  const onSend = vi.fn();
+  const onAbort = vi.fn();
+  const ref = createRef<ChatInputHandle>();
+  const utils = render(
+    <ChatInput
+      ref={ref}
+      onSend={onSend}
+      onAbort={onAbort}
+      disabled={false}
+      isStreaming={false}
+      {...overrides}
+    />,
+  );
+  const textarea = utils.container.querySelector("textarea")!;
+  const sendBtn = utils.container.querySelector('button[aria-label="chatInput.sendMessage"]') as HTMLButtonElement | null;
+  return { onSend, onAbort, ref, textarea, sendBtn, ...utils };
+}
+
+describe("ChatInput length cap (#654)", () => {
+  it("applies maxLength to the textarea (browser-side hard cap)", () => {
+    const { textarea } = setup();
+    expect(textarea.maxLength).toBe(32000);
+  });
+
+  it("hides the counter for short inputs", () => {
+    const { textarea } = setup();
+    fireEvent.change(textarea, { target: { value: "hello" } });
+    expect(screen.queryByText(/\d+ \/ 32000/)).not.toBeInTheDocument();
+  });
+
+  it("shows the counter past the warn threshold", () => {
+    const { textarea } = setup();
+    const long = "a".repeat(25_000);
+    fireEvent.change(textarea, { target: { value: long } });
+    expect(screen.getByText("25000 / 32000")).toBeInTheDocument();
+  });
+
+  it("send button stays enabled within the limit", () => {
+    const { textarea, sendBtn } = setup();
+    fireEvent.change(textarea, { target: { value: "a".repeat(25_000) } });
+    expect(sendBtn!.disabled).toBe(false);
+  });
+
+  it("flips the counter + disables send when over the limit", () => {
+    // Force value past the cap via the imperative handle (the textarea
+    // maxLength would otherwise block direct typing past 32k).
+    const { ref, sendBtn } = setup();
+    // setValue truncates by design; bypass it by writing the textarea
+    // through change with a value above the cap, mimicking a paste that
+    // the browser allows but the JS guard catches.
+    const { textarea } = setup();
+    const huge = "a".repeat(40_000);
+    // jsdom doesn't enforce maxLength on `value=` writes — perfect for
+    // simulating a non-browser client / IME composition past the cap.
+    fireEvent.change(textarea, { target: { value: huge } });
+    const sb = textarea.parentElement?.querySelector('button[aria-label="chatInput.sendMessage"]') as HTMLButtonElement;
+    expect(sb.disabled).toBe(true);
+    // The over-limit copy is the stubbed `over (max 32000)`.
+    expect(screen.getAllByText(/over \(max 32000\)/).length).toBeGreaterThan(0);
+    void ref; // ref kept in fixture for symmetry; not used here
+    void sendBtn;
+  });
+
+  it("imperative setValue truncates past the cap", () => {
+    const { ref, textarea } = setup();
+    act(() => {
+      ref.current!.setValue("a".repeat(50_000));
+    });
+    // After truncation the textarea value length must be ≤ MAX_INPUT_CHARS.
+    expect(textarea.value.length).toBe(32_000);
+  });
+
+  it("send button is disabled for empty input", () => {
+    const { sendBtn } = setup();
+    expect(sendBtn!.disabled).toBe(true);
+  });
+});
diff --git a/ornn-web/src/components/playground/ChatInput.tsx b/ornn-web/src/components/playground/ChatInput.tsx
index 00a2f830..21a68aaf 100644
--- a/ornn-web/src/components/playground/ChatInput.tsx
+++ b/ornn-web/src/components/playground/ChatInput.tsx
@@ -3,6 +3,26 @@
  * Auto-resizing textarea with Enter=send, Shift+Enter=newline.
  * Shows stop button during streaming. Model selection lives in the
  * page-level ModelPicker (top-right surface header).
+ *
+ * #654 — adds a length cap + visible counter. Previously the textarea
+ * accepted unbounded content (24k chars was the live reproducer) and
+ * the send button stayed enabled regardless of length, so users could
+ * fire requests the backend would reject (or worse, accept + crash on
+ * downstream LLM token-limit). Now:
+ *
+ *   - `maxLength` on the textarea hard-caps at MAX_INPUT_CHARS — the
+ *     browser refuses typing/paste beyond that, no extra JS needed.
+ *   - A counter appears once the input crosses WARN_AT_CHARS so users
+ *     get warning room rather than a surprise wall.
+ *   - Counter goes danger-tone + send disables once the trimmed
+ *     content is over the limit (defensive — `maxLength` should make
+ *     this unreachable, but the explicit guard catches any IME / paste
+ *     edge case that slips past).
+ *
+ * The backend (`domains/playground/routes.ts` + `skills/generation/
+ * routes.ts`) caps content at the same 32 000-char ceiling — frontend
+ * is UX, backend is the hard line.
+ *
  * @module components/playground/ChatInput
  */
 
@@ -28,6 +48,17 @@ export interface ChatInputHandle {
 /** Maximum textarea height before scrolling. */
 const MAX_HEIGHT_PX = 200;
 
+/**
+ * Maximum input length. ~8k tokens at 4 chars/token — generous for
+ * interactive prompts without enabling whole-novel pastes. Mirrors the
+ * `.max()` cap on `playgroundMessageSchema.content` /
+ * `skills/generation` route bodies; if you change one, change both.
+ */
+const MAX_INPUT_CHARS = 32_000;
+
+/** Threshold above which the live counter becomes visible (~75%). */
+const WARN_AT_CHARS = 24_000;
+
 export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(function ChatInput({
   onSend,
   onAbort,
@@ -55,7 +86,10 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(function Ch
     ref,
     () => ({
       setValue: (text: string) => {
-        setValue(text);
+        // Truncate suggestion-prompt clicks defensively — the suggestion
+        // catalogue is curated short copy today, but a future longer
+        // prompt shouldn't bypass the cap silently.
+        setValue(text.slice(0, MAX_INPUT_CHARS));
         // Defer focus so the new value's height calculation lands first.
         requestAnimationFrame(() => textareaRef.current?.focus());
       },
@@ -64,12 +98,16 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(function Ch
     [],
   );
 
+  const trimmedLength = value.trim().length;
+  const isOverLimit = trimmedLength > MAX_INPUT_CHARS;
+  const shouldShowCounter = value.length >= WARN_AT_CHARS;
+
   const handleSend = useCallback(() => {
     const trimmed = value.trim();
-    if (!trimmed || disabled) return;
+    if (!trimmed || disabled || trimmed.length > MAX_INPUT_CHARS) return;
     onSend(trimmed);
     setValue("");
-  }, [value, disabled, onSend]);
+  }, [value, disabled]);
 
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
@@ -81,7 +119,7 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(function Ch
     [handleSend],
   );
 
-  const canSend = value.trim().length > 0 && !disabled;
+  const canSend = trimmedLength > 0 && !disabled && !isOverLimit;
 
   return (
     <div className="px-1 pb-2 pt-2">
@@ -92,7 +130,9 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(function Ch
         className={`relative flex items-end gap-2 rounded-2xl border bg-card px-3 py-2 transition-colors ${
           disabled
             ? "border-subtle/60"
-            : "border-subtle focus-within:border-accent/60 focus-within:ring-1 focus-within:ring-accent/30"
+            : isOverLimit
+              ? "border-danger/60 focus-within:border-danger/80 focus-within:ring-1 focus-within:ring-danger/30"
+              : "border-subtle focus-within:border-accent/60 focus-within:ring-1 focus-within:ring-accent/30"
         }`}
       >
         <textarea
@@ -101,6 +141,7 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(function Ch
           onChange={(e) => setValue(e.target.value)}
           onKeyDown={handleKeyDown}
           disabled={disabled}
+          maxLength={MAX_INPUT_CHARS}
           placeholder={
             customPlaceholder
               ?? (disabled
@@ -140,6 +181,21 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(function Ch
           </button>
         )}
       </div>
+      {/* Counter row — appears only past WARN_AT_CHARS so it doesn't
+          chrome the composer for normal use. Goes danger-tone past the
+          cap. */}
+      {shouldShowCounter && (
+        <p
+          className={`mt-1 text-right text-[11px] tabular-nums ${
+            isOverLimit ? "text-danger" : "text-meta/70"
+          }`}
+          aria-live="polite"
+        >
+          {isOverLimit
+            ? t("chatInput.overLimit", { max: MAX_INPUT_CHARS })
+            : t("chatInput.charCount", { count: value.length, max: MAX_INPUT_CHARS })}
+        </p>
+      )}
     </div>
   );
 });
diff --git a/ornn-web/src/components/playground/ChatMessage.tsx b/ornn-web/src/components/playground/ChatMessage.tsx
index fcb978ce..b5a094f1 100644
--- a/ornn-web/src/components/playground/ChatMessage.tsx
+++ b/ornn-web/src/components/playground/ChatMessage.tsx
@@ -153,7 +153,8 @@ function ToolResultMessage({
   toolCallId,
 }: {
   content: string;
-  toolCallId?: string;
+  // exactOptionalPropertyTypes (#657)
+  toolCallId?: string | undefined;
 }) {
   const isRejection = content.startsWith("User rejected execution");
 
diff --git a/ornn-web/src/components/playground/PlaygroundConversation.tsx b/ornn-web/src/components/playground/PlaygroundConversation.tsx
new file mode 100644
index 00000000..ae322820
--- /dev/null
+++ b/ornn-web/src/components/playground/PlaygroundConversation.tsx
@@ -0,0 +1,109 @@
+/**
+ * Active-conversation message stream for PlaygroundPage (#453).
+ *
+ * Layout: rendered turns + the currently-streaming assistant buffer +
+ * ThinkingBubble (between submit and the first streamed token) + file
+ * outputs (image inline, others as download links) + error banner +
+ * the bottom anchor div the parent scrolls into view.
+ *
+ * Stateless — the parent owns chat state via `usePlaygroundChat()`
+ * and the scroll-anchor ref.
+ *
+ * @module components/playground/PlaygroundConversation
+ */
+
+import { forwardRef } from "react";
+import { ChatMessage } from "@/components/playground/ChatMessage";
+import { ThinkingBubble } from "@/components/playground/PlaygroundHelpers";
+import type { PlaygroundMessage, ToolCallStatus, FileOutput } from "@/types/playground";
+
+export interface PlaygroundConversationProps {
+  messages: PlaygroundMessage[];
+  isStreaming: boolean;
+  toolCallStatuses: Record<string, ToolCallStatus>;
+  currentAssistantContent: string;
+  fileOutputs: FileOutput[];
+  error: string | null;
+}
+
+export const PlaygroundConversation = forwardRef<HTMLDivElement, PlaygroundConversationProps>(
+  function PlaygroundConversation(
+    {
+      messages,
+      isStreaming,
+      toolCallStatuses,
+      currentAssistantContent,
+      fileOutputs,
+      error,
+    },
+    anchorRef,
+  ) {
+    return (
+      <div className="space-y-3 py-3">
+        {messages.map((msg, idx) => {
+          const isLastAssistant =
+            msg.role === "assistant" &&
+            idx === messages.length - 1 &&
+            isStreaming;
+          return (
+            <ChatMessage
+              key={msg.id}
+              message={msg}
+              toolCallStatuses={toolCallStatuses}
+              isStreaming={isLastAssistant}
+            />
+          );
+        })}
+
+        {currentAssistantContent && (
+          <ChatMessage
+            message={{
+              id: "streaming-buffer",
+              role: "assistant",
+              content: currentAssistantContent,
+            }}
+            toolCallStatuses={toolCallStatuses}
+            isStreaming
+          />
+        )}
+
+        {isStreaming && !currentAssistantContent && <ThinkingBubble />}
+
+        {fileOutputs.map((file, idx) => (
+          <div key={`file-${idx}`} className="flex justify-start">
+            <div className="max-w-[88%] rounded-sm border border-subtle bg-card p-2.5">
+              {file.mimeType.startsWith("image/") ? (
+                <div>
+                  <img
+                    src={`data:${file.mimeType};base64,${file.content}`}
+                    alt={file.path}
+                    className="max-w-full rounded-sm"
+                  />
+                  <p className="mt-1.5 font-mono text-[10px] text-meta">
+                    {file.path} ({Math.round(file.size / 1024)}KB)
+                  </p>
+                </div>
+              ) : (
+                <a
+                  href={`data:${file.mimeType};base64,${file.content}`}
+                  download={file.path.split("/").pop()}
+                  className="font-mono text-xs text-accent hover:underline"
+                >
+                  {file.path} ({Math.round(file.size / 1024)}KB)
+                </a>
+              )}
+            </div>
+          </div>
+        ))}
+
+        {error && (
+          <div className="rounded-sm border border-danger/30 bg-danger/5 px-3 py-2.5">
+            <p className="font-text text-xs text-danger">{error}</p>
+          </div>
+        )}
+
+        <div ref={anchorRef} />
+      </div>
+    );
+  },
+);
diff --git a/ornn-web/src/components/playground/PlaygroundEmptyHero.tsx b/ornn-web/src/components/playground/PlaygroundEmptyHero.tsx
new file mode 100644
index 00000000..69d2ad36
--- /dev/null
+++ b/ornn-web/src/components/playground/PlaygroundEmptyHero.tsx
@@ -0,0 +1,86 @@
+/**
+ * Empty-state hero for PlaygroundPage (#453).
+ *
+ * ChatGPT-style centered welcome flag: skill name eyebrow + headline +
+ * lead sentence (swaps to an env-vars-first message when the skill
+ * needs runtime vars that aren't filled yet) + three suggestion chips
+ * + a drawer-discovery footer note. Disabled state on the chips
+ * mirrors the chat-input lock so users see the same gate from both
+ * surfaces.
+ *
+ * Stateless — the parent owns the starters list + click handler +
+ * envIncomplete flag.
+ *
+ * @module components/playground/PlaygroundEmptyHero
+ */
+
+import { useTranslation } from "react-i18next";
+import type { PromptStarter } from "./PlaygroundHelpers";
+
+export interface PlaygroundEmptyHeroProps {
+  skillName: string | null;
+  envIncomplete: boolean;
+  starters: PromptStarter[];
+  onStarterClick: (body: string) => void;
+}
+
+export function PlaygroundEmptyHero({
+  skillName,
+  envIncomplete,
+  starters,
+  onStarterClick,
+}: PlaygroundEmptyHeroProps) {
+  const { t } = useTranslation();
+  return (
+    <div className="flex h-full flex-col items-center justify-center py-8">
+      <div className="w-full space-y-6 text-center">
+        <div className="space-y-2">
+          <div className="font-mono text-[10px] uppercase tracking-[0.20em] text-meta">
+            {skillName}
+          </div>
+          <h2 className="font-display text-3xl font-semibold leading-[1.15] tracking-tight text-strong">
+            {t("playground.heroTitle", "Probe the skill.")}
+          </h2>
+          <p className="font-text text-[15px] leading-relaxed text-body">
+            {envIncomplete
+              ? t(
+                  "playground.heroEnvFirst",
+                  "Set the runtime env vars in the Env drawer on the right, then start chatting.",
+                )
+              : t(
+                  "playground.heroSubtitle",
+                  "Ask anything about {{name}}, or have it run with sample input.",
+                  { name: skillName },
+                )}
+          </p>
+        </div>
+
+        <div className="grid grid-cols-1 gap-2 sm:grid-cols-3">
+          {starters.map((s) => (
+            <button
+              key={s.label}
+              type="button"
+              onClick={() => onStarterClick(s.body)}
+              disabled={envIncomplete}
+              className="group flex flex-col items-start gap-1 rounded-xl border border-subtle bg-card/60 px-3.5 py-3 text-left transition-all hover:border-accent/60 hover:bg-card disabled:cursor-not-allowed disabled:opacity-40"
+            >
+              <span className="font-mono text-[10px] uppercase tracking-[0.14em] text-accent">
+                {s.label}
+              </span>
+              <span className="line-clamp-2 font-text text-[13px] leading-snug text-body">
+                {s.body}
+              </span>
+            </button>
+          ))}
+        </div>
+
+        <p className="font-mono text-[10px] uppercase tracking-[0.14em] text-meta/70">
+          {t(
+            "playground.drawerHint",
+            "Skill · Env · Package on the right edge",
+          )}
+        </p>
+      </div>
+    </div>
+  );
+}
diff --git a/ornn-web/src/components/playground/PlaygroundEnvDrawerBody.tsx b/ornn-web/src/components/playground/PlaygroundEnvDrawerBody.tsx
new file mode 100644
index 00000000..7b430258
--- /dev/null
+++ b/ornn-web/src/components/playground/PlaygroundEnvDrawerBody.tsx
@@ -0,0 +1,81 @@
+/**
+ * Env-vars drawer body extracted from PlaygroundPage (#453).
+ *
+ * Per-key input list with a "Set"/"Required" pill on each row + a
+ * one-line lock hint when any required key is empty. Stateless — the
+ * parent owns the values dict and the change handler.
+ *
+ * @module components/playground/PlaygroundEnvDrawerBody
+ */
+
+import { useTranslation } from "react-i18next";
+
+export interface PlaygroundEnvDrawerBodyProps {
+  envVarKeys: string[];
+  envVars: Record<string, string>;
+  allEnvVarsFilled: boolean;
+  onEnvVarChange: (key: string, value: string) => void;
+}
+
+export function PlaygroundEnvDrawerBody({
+  envVarKeys,
+  envVars,
+  allEnvVarsFilled,
+  onEnvVarChange,
+}: PlaygroundEnvDrawerBodyProps) {
+  const { t } = useTranslation();
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      {/* Header strip — same flat voice as the skill drawer. */}
+      <div className="shrink-0 border-b border-subtle bg-elevated/30 px-5 py-4">
+        <div className="font-mono text-[10px] uppercase tracking-[0.18em] text-accent">
+          [§&nbsp;{t("playground.envVars")}]
+        </div>
+        <p className="mt-2 font-text text-sm leading-relaxed text-body">
+          {t("playground.envVarsDesc")}
+        </p>
+      </div>
+
+      {/* Form */}
+      <div className="min-h-0 flex-1 space-y-3 overflow-y-auto px-5 py-4">
+        {envVarKeys.map((key) => {
+          const filled = !!envVars[key]?.trim();
+          return (
+            <div key={key} className="space-y-1">
+              <div className="flex items-center justify-between gap-2">
+                <label
+                  className="block min-w-0 flex-1 truncate font-mono text-[11px] text-strong"
+                  title={key}
+                >
+                  {key}
+                </label>
+                <span
+                  className={`shrink-0 font-mono text-[10px] uppercase tracking-[0.14em] ${
+                    filled ? "text-success" : "text-meta"
+                  }`}
+                >
+                  {filled ? t("common.set") : t("common.required")}
+                </span>
+              </div>
+              <input
+                type="text"
+                value={envVars[key] ?? ""}
+                onChange={(e) => onEnvVarChange(key, e.target.value)}
+                placeholder={t("playground.enterValue")}
+                className="w-full rounded-sm border border-subtle bg-page px-2.5 py-1.5 font-mono text-xs text-strong placeholder:text-meta/50 focus:border-accent/60 focus:outline-none"
+              />
+            </div>
+          );
+        })}
+        {!allEnvVarsFilled && (
+          <p className="pt-2 font-text text-[11px] leading-relaxed text-meta">
+            {t(
+              "playground.envVarsLockHint",
+              "Chat is locked until every required env var has a value.",
+            )}
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/ornn-web/src/components/playground/PlaygroundHelpers.tsx b/ornn-web/src/components/playground/PlaygroundHelpers.tsx
new file mode 100644
index 00000000..ddaa7c2f
--- /dev/null
+++ b/ornn-web/src/components/playground/PlaygroundHelpers.tsx
@@ -0,0 +1,101 @@
+/**
+ * Small helpers + ThinkingBubble extracted from PlaygroundPage (#453).
+ *
+ * - `extractEnvVarKeys(metadata)` — pulls the unique `env.var` keys
+ *   out of every runtime in a skill's metadata.
+ * - `isRuntimeBased(metadata)` — true when the skill needs the
+ *   sandbox (category "runtime-based" or "mixed"). Drives whether the
+ *   Env drawer is offered + locks chat until vars are filled.
+ * - `defaultPromptStarters(skillName, t)` — the three suggestion chips
+ *   shown in the empty-state hero.
+ * - `ThinkingBubble` — pre-token streaming indicator.
+ *
+ * @module components/playground/PlaygroundHelpers
+ */
+
+import { motion } from "framer-motion";
+import { useTranslation } from "react-i18next";
+
+export type TFunc = ReturnType<typeof import("react-i18next").useTranslation>["t"];
+
+export interface PromptStarter {
+  label: string;
+  body: string;
+}
+
+/** Extract env var keys from skill metadata. */
+export function extractEnvVarKeys(metadata: Record<string, unknown> | null): string[] {
+  if (!metadata) return [];
+  const runtimes = metadata.runtimes as Array<{ envs?: Array<{ var: string }> }> | undefined;
+  if (!runtimes?.length) return [];
+  const keys: string[] = [];
+  for (const rt of runtimes) {
+    if (rt.envs) {
+      for (const env of rt.envs) {
+        if (env.var && !keys.includes(env.var)) {
+          keys.push(env.var);
+        }
+      }
+    }
+  }
+  return keys;
+}
+
+/** Check if skill is runtime-based. */
+export function isRuntimeBased(metadata: Record<string, unknown> | null): boolean {
+  if (!metadata) return false;
+  const category = metadata.category as string;
+  return category === "runtime-based" || category === "mixed";
+}
+
+/** Default suggestion chips on the empty-state hero. */
+export function defaultPromptStarters(skillName: string, t: TFunc): PromptStarter[] {
+  return [
+    {
+      label: t("playground.starter1Label", "Walk me through it"),
+      body: t(
+        "playground.starter1Body",
+        "Walk me through what `{{name}}` does and the main ways I'd use it.",
+        { name: skillName },
+      ),
+    },
+    {
+      label: t("playground.starter2Label", "Show an example"),
+      body: t(
+        "playground.starter2Body",
+        "Give me a concrete usage example for `{{name}}` — make up sample input and run it.",
+        { name: skillName },
+      ),
+    },
+    {
+      label: t("playground.starter3Label", "List capabilities"),
+      body: t(
+        "playground.starter3Body",
+        "List every capability `{{name}}` exposes, with a one-line description for each.",
+        { name: skillName },
+      ),
+    },
+  ];
+}
+
+/** Pre-token streaming indicator — three pulsing ember dots, spring-in. */
+export function ThinkingBubble() {
+  const { t } = useTranslation();
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: 8, scale: 0.98 }}
+      animate={{ opacity: 1, y: 0, scale: 1 }}
+      exit={{ opacity: 0, scale: 0.96 }}
+      transition={{ type: "spring", stiffness: 320, damping: 28, mass: 0.6 }}
+      className="flex justify-start"
+    >
+      <div className="rounded-2xl border border-subtle bg-card px-4 py-3">
+        <div className="flex items-center gap-1.5" aria-label={t("aria.generating")}>
+          <span className="h-1.5 w-1.5 animate-pulse rounded-full bg-accent/70" style={{ animationDelay: "0ms" }} />
+          <span className="h-1.5 w-1.5 animate-pulse rounded-full bg-accent/70" style={{ animationDelay: "150ms" }} />
+          <span className="h-1.5 w-1.5 animate-pulse rounded-full bg-accent/70" style={{ animationDelay: "300ms" }} />
+        </div>
+      </div>
+    </motion.div>
+  );
+}
diff --git a/ornn-web/src/components/playground/PlaygroundPackageDrawerBody.tsx b/ornn-web/src/components/playground/PlaygroundPackageDrawerBody.tsx
new file mode 100644
index 00000000..eb70c821
--- /dev/null
+++ b/ornn-web/src/components/playground/PlaygroundPackageDrawerBody.tsx
@@ -0,0 +1,79 @@
+/**
+ * Package drawer body extracted from PlaygroundPage (#453).
+ *
+ * Renders the skill package preview (file tree + viewer) inside the
+ * drawer, with a footer that pins a registry link to the bottom. The
+ * preview is read-only; the parent owns the files + contents +
+ * metadata and the package-loading flag.
+ *
+ * @module components/playground/PlaygroundPackageDrawerBody
+ */
+
+import { Link } from "react-router-dom";
+import { useTranslation } from "react-i18next";
+import { Skeleton } from "@/components/ui/Skeleton";
+import { SkillPackagePreview } from "@/components/skill/SkillPackagePreview";
+import type { FileNode } from "@/components/editor/FileTree";
+import type { SkillMetadata } from "@/types/skillPackage";
+
+export interface PlaygroundPackageDrawerBodyProps {
+  packageLoading: boolean;
+  packageFiles: FileNode[];
+  /** Matches `useSkillPackage().fileContents` shape (path → text). */
+  packageContents: Map<string, string>;
+  /** `null` while the skill is still loading; SkillPackagePreview tolerates either. */
+  previewMetadata: SkillMetadata | null;
+  /** When present, the footer shows `name@vversion` + a link to the registry. */
+  skill: { name: string; version: string } | null | undefined;
+}
+
+export function PlaygroundPackageDrawerBody({
+  packageLoading,
+  packageFiles,
+  packageContents,
+  previewMetadata,
+  skill,
+}: PlaygroundPackageDrawerBodyProps) {
+  const { t } = useTranslation();
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      {/* Padded content area — must itself be a flex column so the
+          preview's `flex-1 min-h-0` actually claims the remaining
+          height and the file viewer scrolls internally instead of
+          bleeding past the footer. */}
+      <div className="flex min-h-0 flex-1 flex-col p-4">
+        {packageLoading ? (
+          <Skeleton lines={8} />
+        ) : packageFiles.length > 0 ? (
+          <SkillPackagePreview
+            files={packageFiles}
+            fileContents={packageContents}
+            metadata={previewMetadata}
+            editable={false}
+            className="min-h-0 flex-1"
+          />
+        ) : (
+          <div className="flex h-32 items-center justify-center">
+            <p className="font-text text-xs text-meta">{t("playground.noPackage")}</p>
+          </div>
+        )}
+      </div>
+
+      {/* Footer — registry link pinned at the bottom, matching the
+          Skill drawer's pattern. */}
+      {skill && (
+        <div className="flex shrink-0 items-center justify-between border-t border-subtle bg-elevated/30 px-5 py-3">
+          <span className="font-mono text-[10px] uppercase tracking-[0.18em] text-meta">
+            {skill.name}@v{skill.version}
+          </span>
+          <Link
+            to={`/skills/${encodeURIComponent(skill.name)}`}
+            className="font-mono text-[11px] text-accent hover:underline"
+          >
+            {t("playground.openInRegistry", "Open in registry →")}
+          </Link>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/ornn-web/src/components/playground/PlaygroundRail.tsx b/ornn-web/src/components/playground/PlaygroundRail.tsx
new file mode 100644
index 00000000..024b4c42
--- /dev/null
+++ b/ornn-web/src/components/playground/PlaygroundRail.tsx
@@ -0,0 +1,101 @@
+/**
+ * Right-edge drawer rail extracted from PlaygroundPage (#453).
+ *
+ * Always-visible vertical strip with one tab per drawer. Each tab has:
+ *   - hover-peek: opens its drawer until the cursor leaves the rail
+ *   - click: pins the drawer until the user clicks elsewhere
+ *   - tooltip on the LEFT side that fades in on hover when the drawer
+ *     isn't already open
+ *   - optional warning dot (e.g. env vars incomplete)
+ *   - active-pin marker (a 1px vertical line on the rail edge)
+ *
+ * Stateless — the parent owns activeDrawer + pinnedDrawer + the
+ * open/close handlers.
+ *
+ * @module components/playground/PlaygroundRail
+ */
+
+import type { ComponentType } from "react";
+import type { IconProps } from "@/components/icons";
+
+export type DrawerKey = "package" | "env";
+
+export interface PlaygroundRailTab {
+  key: DrawerKey;
+  ariaLabel: string;
+  tip: string;
+  Icon: ComponentType<IconProps>;
+  /** Render a small warning dot to the left of the icon. */
+  warn?: boolean;
+}
+
+export interface PlaygroundRailProps {
+  tabs: PlaygroundRailTab[];
+  activeDrawer: DrawerKey | null;
+  pinnedDrawer: DrawerKey | null;
+  onHoverOpen: (key: DrawerKey) => void;
+  onHoverCloseScheduled: () => void;
+  onTogglePin: (key: DrawerKey) => void;
+}
+
+export function PlaygroundRail({
+  tabs,
+  activeDrawer,
+  pinnedDrawer,
+  onHoverOpen,
+  onHoverCloseScheduled,
+  onTogglePin,
+}: PlaygroundRailProps) {
+  return (
+    <div
+      className="fixed right-0 top-1/2 z-40 flex -translate-y-1/2 flex-col gap-1"
+      onMouseLeave={onHoverCloseScheduled}
+    >
+      {tabs.map((tab) => {
+        const active = activeDrawer === tab.key;
+        const Icon = tab.Icon;
+        return (
+          <button
+            key={tab.key}
+            type="button"
+            onMouseEnter={() => onHoverOpen(tab.key)}
+            onClick={() => onTogglePin(tab.key)}
+            className={`group relative flex h-11 w-9 items-center justify-center rounded-l-sm border-y border-l transition-colors ${
+              active
+                ? "border-accent/60 bg-card text-accent"
+                : "border-subtle bg-card/80 text-meta hover:border-accent/40 hover:text-strong"
+            }`}
+            aria-label={tab.ariaLabel}
+          >
+            <Icon className="h-4 w-4" />
+
+            {/* Horizontal tooltip — fades in on hover when the drawer
+                for this tab is not already open. Matches the drawer
+                header voice `[§ NAME]`. */}
+            {!active && (
+              <span
+                className="pointer-events-none absolute right-full top-1/2 mr-2 -translate-y-1/2 whitespace-nowrap rounded-sm border border-subtle bg-card px-2 py-1 font-mono text-[10px] uppercase tracking-[0.18em] text-strong opacity-0 transition-opacity duration-150 group-hover:opacity-100"
+                aria-hidden
+              >
+                [§&nbsp;{tab.tip}]
+              </span>
+            )}
+
+            {tab.warn && (
+              <span
+                className="absolute -left-1 top-1.5 h-1.5 w-1.5 rounded-full bg-warning"
+                aria-hidden
+              />
+            )}
+            {pinnedDrawer === tab.key && (
+              <span
+                className="absolute -left-px inset-y-2 w-px bg-accent"
+                aria-hidden
+              />
+            )}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/ornn-web/src/components/quota/QuotaInline.tsx b/ornn-web/src/components/quota/QuotaInline.tsx
index 6ccc0c87..1efdd59e 100644
--- a/ornn-web/src/components/quota/QuotaInline.tsx
+++ b/ornn-web/src/components/quota/QuotaInline.tsx
@@ -18,6 +18,7 @@
 import { useTranslation } from "react-i18next";
 import type { Surface, SurfaceSnapshot } from "@/services/quotaApi";
 import { useMyQuota } from "@/hooks/useQuota";
+import { displayUsagePercent } from "./quotaDisplay";
 
 interface QuotaInlineProps {
   surface: Surface;
@@ -83,7 +84,9 @@ export function QuotaInline({ surface, className = "" }: QuotaInlineProps) {
   const warning = snap.warning && !exhausted;
 
   if (warning) {
-    const percent = cap > 0 ? Math.round((snap.used / cap) * 100) : 0;
+    // #629 — share the QuotaSummary helper so the inline banner can
+    // never claim "100% used this month" while a call still remains.
+    const percent = displayUsagePercent(snap.used, cap, remaining);
     const adminGrantSuffix =
       snap.adminGrant > 0
         ? t(
diff --git a/ornn-web/src/components/quota/QuotaSummary.tsx b/ornn-web/src/components/quota/QuotaSummary.tsx
index 549fa2f0..9d99b0b6 100644
--- a/ornn-web/src/components/quota/QuotaSummary.tsx
+++ b/ornn-web/src/components/quota/QuotaSummary.tsx
@@ -14,6 +14,7 @@ import { createPortal } from "react-dom";
 import { useEffect } from "react";
 import { useTranslation } from "react-i18next";
 import type { QuotaSnapshot, SurfaceSnapshot } from "@/services/quotaApi";
+import { displayUsagePercent } from "./quotaDisplay";
 
 const SURFACE_LABEL: Record<"playground" | "skillGen", string> = {
   playground: "Playground",
@@ -39,9 +40,11 @@ function formatReset(iso: string): string {
   }
 }
 
-function pct(used: number, ceiling: number): number {
-  if (ceiling <= 0) return 0;
-  return Math.max(0, Math.min(100, Math.round((used / ceiling) * 100)));
+// `pct` now delegates to the shared `displayUsagePercent` so summary
+// + inline banner agree on the "never round up to 100% while a call
+// remains" contract from #629.
+function pct(used: number, ceiling: number, remaining: number): number {
+  return displayUsagePercent(used, ceiling, remaining);
 }
 
 interface SurfaceRowProps {
@@ -52,7 +55,7 @@ interface SurfaceRowProps {
 
 function SurfaceRow({ label, snapshot, resetAt }: SurfaceRowProps) {
   const ceiling = snapshot.defaultAllotment + snapshot.adminGrant;
-  const monthlyPct = pct(snapshot.used, ceiling);
+  const monthlyPct = pct(snapshot.used, ceiling, snapshot.remaining);
   const monthlyTone =
     snapshot.remaining <= 0
       ? "bg-danger"
diff --git a/ornn-web/src/components/quota/quotaDisplay.test.ts b/ornn-web/src/components/quota/quotaDisplay.test.ts
new file mode 100644
index 00000000..592adc25
--- /dev/null
+++ b/ornn-web/src/components/quota/quotaDisplay.test.ts
@@ -0,0 +1,39 @@
+/**
+ * displayUsagePercent tests — pins the #629 "never round up to 100%"
+ * contract.
+ *
+ * @module components/quota/quotaDisplay.test
+ */
+import { describe, it, expect } from "vitest";
+import { displayUsagePercent } from "./quotaDisplay";
+
+describe("displayUsagePercent", () => {
+  it("returns 0 when ceiling is 0", () => {
+    expect(displayUsagePercent(0, 0, 0)).toBe(0);
+  });
+
+  it("returns 100 when remaining is 0", () => {
+    expect(displayUsagePercent(100, 100, 0)).toBe(100);
+    expect(displayUsagePercent(50, 100, 0)).toBe(100);
+  });
+
+  it("clamps to 99 when 1 call remains and naive rounding would say 100", () => {
+    // #629 reproducer — used=199 ceiling=200 → 99.5% → naive round → 100.
+    // With remaining=1, must display 99%.
+    expect(displayUsagePercent(199, 200, 1)).toBe(99);
+  });
+
+  it("uses floor (not round) so 99.9% reads as 99%", () => {
+    expect(displayUsagePercent(999, 1000, 1)).toBe(99);
+  });
+
+  it("normal mid-range usage rounds down", () => {
+    expect(displayUsagePercent(50, 100, 50)).toBe(50);
+    expect(displayUsagePercent(49, 100, 51)).toBe(49);
+    expect(displayUsagePercent(1, 100, 99)).toBe(1);
+  });
+
+  it("clamps 0 from below (defensive against negative used)", () => {
+    expect(displayUsagePercent(-5, 100, 105)).toBe(0);
+  });
+});
diff --git a/ornn-web/src/components/quota/quotaDisplay.ts b/ornn-web/src/components/quota/quotaDisplay.ts
new file mode 100644
index 00000000..7bfd6ee9
--- /dev/null
+++ b/ornn-web/src/components/quota/quotaDisplay.ts
@@ -0,0 +1,35 @@
+/**
+ * Display-percentage helper shared by QuotaSummary + QuotaInline.
+ *
+ * #629 — the old `Math.round((used / ceiling) * 100)` could promote
+ * `99.5%` (e.g. `used=199, ceiling=200`) to `100%` even though
+ * `remaining=1`. The chip / "X remaining" copy next to it then
+ * contradicted the banner ("100% used this month" + "1 Playground
+ * calls left"). Pin the displayed percent so 100 never appears while
+ * any quota remains.
+ *
+ * @module components/quota/quotaDisplay
+ */
+
+/**
+ * Compute the integer percent to render in chrome ("100% used", the
+ * progress bar fill, etc.).
+ *
+ * Contract:
+ *   - 0 when ceiling is non-positive (nothing meaningful to show).
+ *   - `100` only when `remaining <= 0`. Below that, the result is
+ *     clamped to `[0, 99]` so the banner never claims "100% used"
+ *     while a call is still allowed.
+ *   - Always `Math.floor` so a usage of `99.5%` reads as `99%`, not
+ *     a misleading `100%`.
+ */
+export function displayUsagePercent(
+  used: number,
+  ceiling: number,
+  remaining: number,
+): number {
+  if (ceiling <= 0) return 0;
+  if (remaining <= 0) return 100;
+  const raw = (used / ceiling) * 100;
+  return Math.max(0, Math.min(99, Math.floor(raw)));
+}
diff --git a/ornn-web/src/components/search/SearchBar.tsx b/ornn-web/src/components/search/SearchBar.tsx
index 73da1145..a3249af2 100644
--- a/ornn-web/src/components/search/SearchBar.tsx
+++ b/ornn-web/src/components/search/SearchBar.tsx
@@ -1,12 +1,14 @@
 import { useSearchStore } from "@/stores/searchStore";
 import { useDebounce } from "@/hooks/useDebounce";
 import { useEffect, useState } from "react";
+import { useTranslation } from "react-i18next";
 
 export interface SearchBarProps {
   className?: string;
 }
 
 export function SearchBar({ className = "" }: SearchBarProps) {
+  const { t } = useTranslation();
   const setQuery = useSearchStore((s) => s.setQuery);
   const storeQuery = useSearchStore((s) => s.query);
   const mode = useSearchStore((s) => s.mode);
@@ -43,8 +45,8 @@ export function SearchBar({ className = "" }: SearchBarProps) {
           onChange={(e) => setLocalValue(e.target.value)}
           placeholder={
             isSemanticMode
-              ? "Describe what you're looking for..."
-              : "Search skills by name, description, or tags..."
+              ? t("search.placeholderSemantic", "Describe what you're looking for...")
+              : t("search.placeholderKeyword", "Search skills by name or description...")
           }
           className="neon-input w-full rounded py-3 pr-4 pl-12 font-text text-strong placeholder:text-meta/50"
         />
@@ -54,7 +56,11 @@ export function SearchBar({ className = "" }: SearchBarProps) {
       <button
         type="button"
         onClick={() => setMode(isSemanticMode ? "keyword" : "semantic")}
-        title={isSemanticMode ? "Switch to keyword search" : "Switch to semantic search"}
+        title={
+          isSemanticMode
+            ? t("search.toggleToKeyword", "Switch to keyword search")
+            : t("search.toggleToSemantic", "Switch to semantic search")
+        }
         className={`
           flex items-center gap-2 shrink-0 rounded border px-4 py-3 font-text text-sm transition-all
           ${isSemanticMode
@@ -76,7 +82,9 @@ export function SearchBar({ className = "" }: SearchBarProps) {
             />
           </svg>
         )}
-        {isSemanticMode ? "Semantic" : "Keyword"}
+        {isSemanticMode
+          ? t("search.modeSemantic", "Semantic")
+          : t("search.modeKeyword", "Keyword")}
       </button>
     </div>
   );
diff --git a/ornn-web/src/components/skill/AdvancedOptionsModal.tsx b/ornn-web/src/components/skill/AdvancedOptionsModal.tsx
index 9c424a1d..000becf1 100644
--- a/ornn-web/src/components/skill/AdvancedOptionsModal.tsx
+++ b/ornn-web/src/components/skill/AdvancedOptionsModal.tsx
@@ -56,13 +56,13 @@ const SETTINGS: ReadonlyArray<{
 
 export function AdvancedOptionsModal({ isOpen, onClose, skill }: AdvancedOptionsModalProps) {
   const { t } = useTranslation();
-  const [selected, setSelected] = useState<AdvancedSettingId>(SETTINGS[0].id);
+  const [selected, setSelected] = useState<AdvancedSettingId>(SETTINGS[0]!.id);
 
   // Reset to the first setting whenever the modal opens, so the user
   // always lands on a known starting point rather than wherever they
   // left off across different skills.
   useEffect(() => {
-    if (isOpen) setSelected(SETTINGS[0].id);
+    if (isOpen) setSelected(SETTINGS[0]!.id);
   }, [isOpen]);
 
   return (
diff --git a/ornn-web/src/components/skill/AnalyticsCard.tsx b/ornn-web/src/components/skill/AnalyticsCard.tsx
index fa588872..21764c70 100644
--- a/ornn-web/src/components/skill/AnalyticsCard.tsx
+++ b/ornn-web/src/components/skill/AnalyticsCard.tsx
@@ -38,7 +38,8 @@ function Stat({
 }: {
   label: string;
   value: string | number;
-  hint?: string;
+  // exactOptionalPropertyTypes (#657)
+  hint?: string | undefined;
 }) {
   return (
     <div>
diff --git a/ornn-web/src/components/skill/AuditVerdictPill.tsx b/ornn-web/src/components/skill/AuditVerdictPill.tsx
new file mode 100644
index 00000000..8f32ddf3
--- /dev/null
+++ b/ornn-web/src/components/skill/AuditVerdictPill.tsx
@@ -0,0 +1,137 @@
+/**
+ * Audit-verdict tile shown inside the right-rail Audit card on SkillDetailPage (#453).
+ *
+ * Three visual states:
+ *   - running (in-flight audit takes precedence even when a previous
+ *     completed verdict exists for this version — the spinner wins)
+ *   - never audited (the unknown / empty state — render a neutral pill)
+ *   - completed (green / yellow / red tone driven by `audit.verdict`,
+ *     with the numeric score + label)
+ *
+ * Stateless. Owner is `SkillDetailPage` (and any future page that wants
+ * the same widget without re-implementing it).
+ *
+ * @module components/skill/AuditVerdictPill
+ */
+
+import { useTranslation } from "react-i18next";
+import type { AuditRecord } from "@/types/audit";
+
+export interface AuditVerdictPillProps {
+  // exactOptionalPropertyTypes (#657)
+  audit?: AuditRecord | undefined;
+  running?: boolean | undefined;
+  /**
+   * True when the most recent audit attempt for the current version
+   * ended in `failed` and is newer than the displayed completed
+   * `audit`. Causes the pill to render the failure state alongside
+   * (not in place of) any prior completed verdict, so admins see
+   * the rerun failed instead of staring at the now-stale score
+   * (#718).
+   */
+  latestRerunFailed?: boolean | undefined;
+}
+
+export function AuditVerdictPill({
+  audit,
+  running,
+  latestRerunFailed,
+}: AuditVerdictPillProps) {
+  const { t } = useTranslation();
+
+  // In-flight audit takes precedence over the cached completed result —
+  // even if there's a previous completed verdict on this version, surface
+  // the spinner while a new run is scoring.
+  if (running) {
+    return (
+      <div className="mb-3.5 flex items-center gap-3 rounded-sm border border-accent/30 bg-accent/5 p-3 font-mono text-[11px] uppercase tracking-wider text-accent">
+        <div
+          className="flex h-8 w-8 items-center justify-center rounded-sm border border-accent/30"
+          aria-hidden
+        >
+          <span className="h-4 w-4 animate-spin rounded-full border-2 border-accent/30 border-t-accent" />
+        </div>
+        <span>{t("skillDetail.auditRunning", "Audit in progress")}</span>
+      </div>
+    );
+  }
+
+  if (!audit || audit.status !== "completed") {
+    return (
+      <div className="mb-3.5 flex items-center gap-3 rounded-sm border border-strong-edge bg-elevated/60 p-3 font-mono text-[11px] uppercase tracking-wider text-meta">
+        <div
+          className="flex h-8 w-8 items-center justify-center rounded-sm border border-strong-edge text-meta"
+          aria-hidden
+        >
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+            <circle cx="12" cy="12" r="9" />
+          </svg>
+        </div>
+        <span>{t("skillDetail.auditNone", "Not audited")}</span>
+      </div>
+    );
+  }
+
+  const tone =
+    audit.verdict === "green"
+      ? "border-success/30 bg-success-soft text-success"
+      : audit.verdict === "yellow"
+        ? "border-warning/30 bg-warning-soft text-warning"
+        : "border-danger/30 bg-danger-soft text-danger";
+  const label =
+    audit.verdict === "green"
+      ? t("skillDetail.auditPassLabel", "Pass · low risk")
+      : audit.verdict === "yellow"
+        ? t("skillDetail.auditWarnLabel", "Caution")
+        : t("skillDetail.auditFailLabel", "Risk");
+
+  return (
+    <>
+      <div className={`mb-3.5 flex items-center gap-3 rounded-sm border p-3 ${tone}`}>
+        <div
+          className="flex h-8 w-8 shrink-0 items-center justify-center rounded-sm bg-current text-page"
+          aria-hidden
+        >
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="3">
+            <polyline points="20 6 9 17 4 12" />
+          </svg>
+        </div>
+        <div className="flex flex-col gap-0.5">
+          <div>
+            <span className="font-display text-2xl font-semibold leading-none">
+              {audit.overallScore.toFixed(1)}
+            </span>
+            <span className="ml-1 font-mono text-[11px] tracking-wide text-meta">/ 10</span>
+          </div>
+          <span className="font-mono text-[10px] uppercase tracking-[0.14em]">{label}</span>
+        </div>
+      </div>
+      {latestRerunFailed && (
+        <div
+          className="-mt-2.5 mb-3.5 flex items-start gap-2 rounded-sm border border-danger/30 bg-danger-soft p-2.5 font-mono text-[10px] uppercase tracking-[0.14em] text-danger"
+          role="status"
+        >
+          <svg
+            width="14"
+            height="14"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            className="mt-0.5 shrink-0"
+            aria-hidden
+          >
+            <path d="M12 9v2m0 4h.01" />
+            <path d="M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z" />
+          </svg>
+          <span>
+            {t(
+              "skillDetail.auditLatestFailed",
+              "Latest rerun failed — score above is from the prior audit. Check audit history for details.",
+            )}
+          </span>
+        </div>
+      )}
+    </>
+  );
+}
diff --git a/ornn-web/src/components/skill/DeprecationBanner.tsx b/ornn-web/src/components/skill/DeprecationBanner.tsx
index 74dfa71c..ceb7db8a 100644
--- a/ornn-web/src/components/skill/DeprecationBanner.tsx
+++ b/ornn-web/src/components/skill/DeprecationBanner.tsx
@@ -3,12 +3,11 @@ import { useTranslation } from "react-i18next";
 export interface DeprecationBannerProps {
   version: string;
   note: string | null | undefined;
-  /** True when the currently-viewed version is an older one, not the latest. */
   hasNewerVersion: boolean;
-  /** Label of the latest version, shown when offering to jump to it. */
-  latestVersion?: string;
-  onViewLatest?: () => void;
-  className?: string;
+  // exactOptionalPropertyTypes (#657)
+  latestVersion?: string | undefined;
+  onViewLatest?: (() => void) | undefined;
+  className?: string | undefined;
 }
 
 /**
diff --git a/ornn-web/src/components/skill/GenerateSkillModal.tsx b/ornn-web/src/components/skill/GenerateSkillModal.tsx
index c75c8c69..683579b5 100644
--- a/ornn-web/src/components/skill/GenerateSkillModal.tsx
+++ b/ornn-web/src/components/skill/GenerateSkillModal.tsx
@@ -37,14 +37,17 @@ interface GenerateSkillModalProps {
 
 type GenerationStep = "select" | "generating" | "done" | "error";
 
-const STEP_MESSAGES: Record<string, string> = {
+// Concrete keyed type rather than `Record<string, string>` so member
+// access under noUncheckedIndexedAccess (#450) returns `string` (not
+// `string | undefined`) — these keys are compile-time-known.
+const STEP_MESSAGES = {
   fetching_spec: "Fetching OpenAPI spec...",
   fetching_refs: "Fetching reference content...",
   generating: "Generating skill package with AI...",
   validating: "Validating skill format...",
   packaging: "Packaging and uploading skill...",
   done: "Skill generated successfully!",
-};
+} as const;
 
 function isValidUrl(str: string): boolean {
   try {
diff --git a/ornn-web/src/components/skill/GenerationChatMessage.tsx b/ornn-web/src/components/skill/GenerationChatMessage.tsx
index eca036e1..d5fc4e43 100644
--- a/ornn-web/src/components/skill/GenerationChatMessage.tsx
+++ b/ornn-web/src/components/skill/GenerationChatMessage.tsx
@@ -107,8 +107,9 @@ function CompleteBubble({
   skillDescription,
 }: {
   content: string;
-  skillName?: string;
-  skillDescription?: string;
+  // exactOptionalPropertyTypes (#657)
+  skillName?: string | undefined;
+  skillDescription?: string | undefined;
 }) {
   return (
     <motion.div
diff --git a/ornn-web/src/components/skill/PermissionsModal.tsx b/ornn-web/src/components/skill/PermissionsModal.tsx
index 745c6689..1b464eb9 100644
--- a/ornn-web/src/components/skill/PermissionsModal.tsx
+++ b/ornn-web/src/components/skill/PermissionsModal.tsx
@@ -111,25 +111,36 @@ export function PermissionsModal({ isOpen, onClose, skill }: PermissionsModalPro
     queryKey: ["orgs-backfill", unknownOrgIds.sort().join(",")],
     queryFn: async () => {
       const resolved = await Promise.all(unknownOrgIds.map((id) => fetchOrgSummary(id)));
-      return resolved
-        .map(
-          (entry, i) =>
-            entry ?? { userId: unknownOrgIds[i], displayName: unknownOrgIds[i], avatarUrl: null },
-        )
-        .filter((e) => !!e);
+      return resolved.map((entry, i) => {
+        // `i` is bounded by `unknownOrgIds.length` (Promise.all preserves
+        // indexing). `!` is safe under noUncheckedIndexedAccess (#450).
+        const orgId = unknownOrgIds[i]!;
+        // #720 — entry is null when NyxID couldn't resolve the id (org
+        // deleted, or caller can't see it). Keep the row visible so
+        // the owner can revoke, but flag `isUnresolved` so the chip
+        // gets the warning treatment.
+        return entry
+          ? { ...entry, isUnresolved: false }
+          : { userId: orgId, displayName: orgId, avatarUrl: null, isUnresolved: true };
+      });
     },
     enabled: isOpen && unknownOrgIds.length > 0,
     staleTime: 5 * 60_000,
   });
 
   const allOrgOptions = useMemo(() => {
-    const map = new Map<string, { userId: string; displayName: string; isMember: boolean }>();
+    const map = new Map<string, { userId: string; displayName: string; isMember: boolean; isUnresolved: boolean }>();
     for (const o of myOrgs) {
-      map.set(o.userId, { userId: o.userId, displayName: o.displayName, isMember: true });
+      map.set(o.userId, { userId: o.userId, displayName: o.displayName, isMember: true, isUnresolved: false });
     }
     for (const o of fetchedUnknownOrgs) {
       if (!map.has(o.userId)) {
-        map.set(o.userId, { userId: o.userId, displayName: o.displayName, isMember: false });
+        map.set(o.userId, {
+          userId: o.userId,
+          displayName: o.displayName,
+          isMember: false,
+          isUnresolved: o.isUnresolved,
+        });
       }
     }
     return Array.from(map.values());
@@ -283,7 +294,17 @@ export function PermissionsModal({ isOpen, onClose, skill }: PermissionsModalPro
                   return (
                     <label
                       key={org.userId}
-                      className="flex items-center gap-2 cursor-pointer py-1 px-2 rounded hover:bg-accent/5"
+                      className={`flex items-center gap-2 cursor-pointer py-1 px-2 rounded hover:bg-accent/5 ${
+                        org.isUnresolved ? "bg-warning-soft/40" : ""
+                      }`}
+                      title={
+                        org.isUnresolved
+                          ? (t(
+                              "permissions.orgUnresolvedTip",
+                              "This organization is no longer reachable in NyxID. Uncheck to revoke the stale grant.",
+                            ) as string)
+                          : undefined
+                      }
                     >
                       <input
                         type="checkbox"
@@ -294,11 +315,19 @@ export function PermissionsModal({ isOpen, onClose, skill }: PermissionsModalPro
                       <span className="font-text text-sm text-strong truncate">
                         {org.displayName}
                       </span>
-                      {!org.isMember && (
+                      {org.isUnresolved ? (
+                        <span className="ml-auto inline-flex items-center gap-1 rounded-sm border border-warning/40 px-1.5 py-[1px] font-mono text-[10px] uppercase tracking-wider text-warning">
+                          <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5">
+                            <path d="M12 9v2m0 4h.01" />
+                            <path d="M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z" />
+                          </svg>
+                          {t("permissions.orgUnresolved", "unresolved")}
+                        </span>
+                      ) : !org.isMember ? (
                         <span className="font-mono text-[10px] text-meta ml-auto">
                           {t("permissions.notMember", "not member")}
                         </span>
-                      )}
+                      ) : null}
                     </label>
                   );
                 })}
@@ -325,22 +354,49 @@ export function PermissionsModal({ isOpen, onClose, skill }: PermissionsModalPro
                   isPublic ? "opacity-60 pointer-events-none" : ""
                 }`}
               >
-                {sharedUsers.map((u) => (
-                  <span
-                    key={u.userId}
-                    className="inline-flex items-center gap-2 px-2 py-1 rounded-full border border-accent/30 bg-accent/5 font-mono text-xs text-strong h-fit"
-                  >
-                    <span>{u.email || u.displayName || u.userId}</span>
-                    <button
-                      type="button"
-                      onClick={() => removeUser(u.userId)}
-                      className="text-danger hover:text-danger/80 cursor-pointer"
-                      aria-label={t("permissions.removeUser", "Remove") as string}
+                {sharedUsers.map((u) => {
+                  // #720 — user couldn't be resolved via the directory.
+                  // `resolveUsers` leaves the placeholder
+                  // `{ userId, email: "", displayName: userId }` in place
+                  // when a lookup misses, so `!u.email && u.displayName === u.userId`
+                  // is the signal that the grant points at a user who no
+                  // longer exists (or who the caller can't see).
+                  const isUnresolved = !u.email && u.displayName === u.userId;
+                  return (
+                    <span
+                      key={u.userId}
+                      className={`inline-flex items-center gap-2 px-2 py-1 rounded-full border font-mono text-xs h-fit ${
+                        isUnresolved
+                          ? "border-warning/40 bg-warning-soft/40 text-warning"
+                          : "border-accent/30 bg-accent/5 text-strong"
+                      }`}
+                      title={
+                        isUnresolved
+                          ? (t(
+                              "permissions.userUnresolvedTip",
+                              "This user could not be resolved. They may have left or been removed; click × to revoke the stale grant.",
+                            ) as string)
+                          : undefined
+                      }
                     >
-                      ×
-                    </button>
-                  </span>
-                ))}
+                      {isUnresolved && (
+                        <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5">
+                          <path d="M12 9v2m0 4h.01" />
+                          <path d="M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z" />
+                        </svg>
+                      )}
+                      <span>{u.email || u.displayName || u.userId}</span>
+                      <button
+                        type="button"
+                        onClick={() => removeUser(u.userId)}
+                        className="text-danger hover:text-danger/80 cursor-pointer"
+                        aria-label={t("permissions.removeUser", "Remove") as string}
+                      >
+                        ×
+                      </button>
+                    </span>
+                  );
+                })}
                 {sharedUsers.length === 0 && (
                   <p className="font-text text-xs text-meta italic w-full">
                     {t("permissions.noUsersYet", "No users added yet.")}
diff --git a/ornn-web/src/components/skill/SkillAuditStartedModal.tsx b/ornn-web/src/components/skill/SkillAuditStartedModal.tsx
new file mode 100644
index 00000000..19b2cfa4
--- /dev/null
+++ b/ornn-web/src/components/skill/SkillAuditStartedModal.tsx
@@ -0,0 +1,41 @@
+/**
+ * Audit-started modal extracted from SkillDetailPage (#453).
+ *
+ * Shown right after the user kicks off a manual audit — explains that
+ * the run is now happening in the background and they can keep working
+ * while it finishes. A new audit history row materializes when it lands.
+ *
+ * @module components/skill/SkillAuditStartedModal
+ */
+
+import { useTranslation } from "react-i18next";
+import { Button } from "@/components/ui/Button";
+import { Modal } from "@/components/ui/Modal";
+
+export interface SkillAuditStartedModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+export function SkillAuditStartedModal({ isOpen, onClose }: SkillAuditStartedModalProps) {
+  const { t } = useTranslation();
+  return (
+    <Modal
+      isOpen={isOpen}
+      onClose={onClose}
+      title={t("skillDetail.auditStartedTitle", "Audit started") as string}
+    >
+      <p className="font-text text-sm text-meta">
+        {t(
+          "skillDetail.auditStartedBody",
+          "We're running the audit in the background. It takes around 20-30 seconds — when it's done, a new entry will appear in the Audit history. You can close this dialog and keep working.",
+        )}
+      </p>
+      <div className="mt-6 flex justify-end">
+        <Button size="sm" onClick={onClose}>
+          {t("common.gotIt", "Got it")}
+        </Button>
+      </div>
+    </Modal>
+  );
+}
diff --git a/ornn-web/src/components/skill/SkillCard.tsx b/ornn-web/src/components/skill/SkillCard.tsx
index eab6c50f..aad393bb 100644
--- a/ornn-web/src/components/skill/SkillCard.tsx
+++ b/ornn-web/src/components/skill/SkillCard.tsx
@@ -5,12 +5,15 @@ import { Badge } from "@/components/ui/Badge";
 import type { BadgeProps } from "@/components/ui/Badge";
 import { Button } from "@/components/ui/Button";
 import type { SkillSearchResult } from "@/types/search";
+import { useMyOrgs } from "@/hooks/useMe";
 
 const TAG_COLORS: NonNullable<BadgeProps["color"]>[] = ["cyan", "magenta", "yellow", "green"];
 
 function getTagColor(tag: string): NonNullable<BadgeProps["color"]> {
   const hash = tag.split("").reduce((a, c) => a + c.charCodeAt(0), 0);
-  return TAG_COLORS[hash % TAG_COLORS.length];
+  // `hash % TAG_COLORS.length` is always in-range for a non-empty
+  // array. `!` is safe under noUncheckedIndexedAccess (#450).
+  return TAG_COLORS[hash % TAG_COLORS.length]!;
 }
 
 /** Format a date string to exact SGT (Asia/Singapore) timestamp */
@@ -30,19 +33,14 @@ function formatDateSGT(dateStr: string): string {
 
 export interface SkillCardProps {
   skill: SkillSearchResult;
-  /** Show status badge and toggle (for My Skills page) */
-  showOwnerControls?: boolean;
-  /** Current user ID to check ownership */
-  currentUserId?: string;
-  /** Display name to show instead of user ID */
-  ownerDisplayName?: string;
-  /** Avatar URL */
-  ownerAvatarUrl?: string | null;
-  /** Callback when edit is clicked */
-  onEdit?: (skill: SkillSearchResult) => void;
-  /** Callback when delete is clicked */
-  onDelete?: (skill: SkillSearchResult) => void;
-  className?: string;
+  // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
+  showOwnerControls?: boolean | undefined;
+  currentUserId?: string | undefined;
+  ownerDisplayName?: string | undefined;
+  ownerAvatarUrl?: string | null | undefined;
+  onEdit?: ((skill: SkillSearchResult) => void) | undefined;
+  onDelete?: ((skill: SkillSearchResult) => void) | undefined;
+  className?: string | undefined;
 }
 
 /**
@@ -53,8 +51,11 @@ export interface SkillCardProps {
  * `permissionSummary` which the backend computes per-request.
  */
 function PermissionBadges({ skill }: { skill: SkillSearchResult }) {
+  // Reach `t` via the parent's hook context — the badge labels are
+  // short visible UI strings (#682) and must localize.
+  const { t } = useTranslation();
   if (!skill.isPrivate) {
-    return <Badge color="green">🌐 Public</Badge>;
+    return <Badge color="green">🌐 {t("common.public")}</Badge>;
   }
   const ps = skill.permissionSummary;
   const userCount = ps?.sharedUserCount ?? 0;
@@ -62,7 +63,7 @@ function PermissionBadges({ skill }: { skill: SkillSearchResult }) {
   const hasGrants = userCount > 0 || orgCount > 0;
   return (
     <>
-      {!hasGrants && <Badge color="cyan">🔒 Private</Badge>}
+      {!hasGrants && <Badge color="cyan">🔒 {t("common.private")}</Badge>}
       {userCount > 0 && <Badge color="magenta">👥 {userCount}</Badge>}
       {orgCount > 0 && <Badge color="cyan">🏢 {orgCount}</Badge>}
     </>
@@ -101,6 +102,18 @@ export function SkillCard({
   const displayName = ownerDisplayName || skill.createdByDisplayName || skill.createdByEmail || skill.createdBy;
   const timestamp = skill.updatedOn || skill.createdOn;
 
+  // #729 — resolve the specific org that granted access for
+  // `shared-via-org` cards. The skill carries `sharedViaOrgId`; the
+  // current user's NyxID memberships carry display names. Match on
+  // `userId` (NyxID org ids are NyxID user ids). Falls back to the
+  // generic "Via organization" label when the lookup misses (org is
+  // not in the caller's memberships, or the orgs query is loading).
+  const { data: myOrgs } = useMyOrgs();
+  const viaOrgName =
+    skill.myAccessReason === "shared-via-org" && skill.sharedViaOrgId
+      ? myOrgs?.find((o) => o.userId === skill.sharedViaOrgId)?.displayName
+      : undefined;
+
   return (
     <Card
       hoverable
@@ -138,12 +151,16 @@ export function SkillCard({
           `myAccessReason` with a grant-based value. */}
       {skill.myAccessReason === "shared-via-org" && (
         <p className="mb-2 font-text text-[11px] uppercase tracking-wider text-meta">
-          Via organization
+          {viaOrgName
+            ? t("skillComponents.card.viaOrganizationNamed", "Via {{org}}", {
+                org: viaOrgName,
+              })
+            : t("skillComponents.card.viaOrganization", "Via organization")}
         </p>
       )}
       {skill.myAccessReason === "shared-direct" && (
         <p className="mb-2 font-text text-[11px] uppercase tracking-wider text-meta">
-          Shared by {displayName}
+          {t("skillComponents.card.sharedBy", "Shared by {{name}}", { name: displayName })}
         </p>
       )}
 
diff --git a/ornn-web/src/components/skill/SkillDeleteConfirmModal.tsx b/ornn-web/src/components/skill/SkillDeleteConfirmModal.tsx
new file mode 100644
index 00000000..dd7ac38a
--- /dev/null
+++ b/ornn-web/src/components/skill/SkillDeleteConfirmModal.tsx
@@ -0,0 +1,45 @@
+/**
+ * Delete-confirmation modal extracted from SkillDetailPage (#453).
+ *
+ * Confirms the user intends to delete the whole skill (not just a
+ * version — version deletion is inside the All-versions browser).
+ *
+ * @module components/skill/SkillDeleteConfirmModal
+ */
+
+import { useTranslation } from "react-i18next";
+import { Button } from "@/components/ui/Button";
+import { Modal } from "@/components/ui/Modal";
+
+export interface SkillDeleteConfirmModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  skillName: string;
+  onConfirm: () => void;
+  deleting: boolean;
+}
+
+export function SkillDeleteConfirmModal({
+  isOpen,
+  onClose,
+  skillName,
+  onConfirm,
+  deleting,
+}: SkillDeleteConfirmModalProps) {
+  const { t } = useTranslation();
+  return (
+    <Modal isOpen={isOpen} onClose={onClose} title={t("skillDetail.deleteTitle")}>
+      <p className="font-text text-sm text-meta">
+        {t("skillDetail.deleteConfirm", { name: skillName }).replace(/<\/?strong>/g, "")}
+      </p>
+      <div className="mt-6 flex justify-end gap-3">
+        <Button variant="secondary" size="sm" onClick={onClose}>
+          {t("common.cancel")}
+        </Button>
+        <Button variant="danger" size="sm" onClick={onConfirm} loading={deleting}>
+          {t("common.delete")}
+        </Button>
+      </div>
+    </Modal>
+  );
+}
diff --git a/ornn-web/src/components/skill/SkillDetailStates.tsx b/ornn-web/src/components/skill/SkillDetailStates.tsx
new file mode 100644
index 00000000..aa4cb70f
--- /dev/null
+++ b/ornn-web/src/components/skill/SkillDetailStates.tsx
@@ -0,0 +1,45 @@
+/**
+ * Loading + not-found shell states for SkillDetailPage (#453).
+ *
+ * Pulled out so the page file only carries the happy-path render. Each
+ * state component owns its own PageTransition wrapper so the route
+ * still feels animated even when the data isn't there yet.
+ *
+ * @module components/skill/SkillDetailStates
+ */
+
+import { useNavigate } from "react-router-dom";
+import { useTranslation } from "react-i18next";
+import { PageTransition } from "@/components/layout/PageTransition";
+import { Button } from "@/components/ui/Button";
+import { Skeleton } from "@/components/ui/Skeleton";
+
+export function SkillDetailLoading() {
+  return (
+    <PageTransition>
+      <div className="flex h-full items-center justify-center">
+        <Skeleton lines={10} />
+      </div>
+    </PageTransition>
+  );
+}
+
+export function SkillDetailNotFound() {
+  const navigate = useNavigate();
+  const { t } = useTranslation();
+  return (
+    <PageTransition>
+      <div className="flex h-full items-center justify-center">
+        <div className="text-center">
+          <h2 className="mb-2 font-display text-2xl text-danger">
+            {t("skillDetail.notFound")}
+          </h2>
+          <p className="text-meta">{t("skillDetail.notFoundDesc")}</p>
+          <Button onClick={() => navigate("/registry")} className="mt-6">
+            {t("skillDetail.backToExplore")}
+          </Button>
+        </div>
+      </div>
+    </PageTransition>
+  );
+}
diff --git a/ornn-web/src/components/skill/SkillFileViewer.tsx b/ornn-web/src/components/skill/SkillFileViewer.tsx
index d8221610..7948d128 100644
--- a/ornn-web/src/components/skill/SkillFileViewer.tsx
+++ b/ornn-web/src/components/skill/SkillFileViewer.tsx
@@ -18,19 +18,14 @@ import { useState } from "react";
 import { formatFileSize } from "@/utils/formatters";
 
 export interface SkillFileViewerProps {
-  /** File content as plaintext */
   content: string;
-  /** File name (for display in header) */
   filename: string;
-  /** Allow editing (textarea instead of pre) */
-  editable?: boolean;
-  /** Callback when content changes */
-  onChange?: (content: string) => void;
-  /** Whether the file is binary */
-  isBinary?: boolean;
-  /** File size in bytes (shown for binary files) */
-  fileSize?: number;
-  className?: string;
+  // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
+  editable?: boolean | undefined;
+  onChange?: ((content: string) => void) | undefined;
+  isBinary?: boolean | undefined;
+  fileSize?: number | undefined;
+  className?: string | undefined;
 }
 
 function EditIcon({ className }: { className?: string }) {
diff --git a/ornn-web/src/components/skill/SkillGrid.tsx b/ornn-web/src/components/skill/SkillGrid.tsx
index 4f5a066a..c9098d63 100644
--- a/ornn-web/src/components/skill/SkillGrid.tsx
+++ b/ornn-web/src/components/skill/SkillGrid.tsx
@@ -33,6 +33,7 @@ export function SkillGrid({ skills, isLoading, className = "" }: SkillGridProps)
     return (
       <div className={`grid gap-6 sm:grid-cols-2 lg:grid-cols-3 ${className}`}>
         {Array.from({ length: 6 }).map((_, i) => (
+          // Positional list — never reorders, key={i} is intentional (#451).
           <SkeletonCard key={i} />
         ))}
       </div>
diff --git a/ornn-web/src/components/skill/SkillHeroStrip.tsx b/ornn-web/src/components/skill/SkillHeroStrip.tsx
index 1dc80be3..705b6c16 100644
--- a/ornn-web/src/components/skill/SkillHeroStrip.tsx
+++ b/ornn-web/src/components/skill/SkillHeroStrip.tsx
@@ -19,18 +19,16 @@ import type { AuditRecord } from "@/types/audit";
 
 interface SkillHeroStripProps {
   skill: SkillDetail;
-  pullCount7d?: number;
-  versionAudit?: AuditRecord;
+  // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
+  pullCount7d?: number | undefined;
+  versionAudit?: AuditRecord | undefined;
   isAuthenticated: boolean;
   isOwner: boolean;
   ownerDisplayName: string;
-  ownerAvatarUrl?: string | null;
-  /** Click handler for the primary "Try in Playground" CTA. */
+  ownerAvatarUrl?: string | null | undefined;
   onTryPlayground: () => void;
-  /** Click handler for the download icon — only when raw ZIP is available. */
-  onDownloadPackage?: () => void;
-  /** Click handler for the edit icon — only when caller is owner/admin. */
-  onEditSkill?: () => void;
+  onDownloadPackage?: (() => void) | undefined;
+  onEditSkill?: (() => void) | undefined;
 }
 
 /**
@@ -44,7 +42,14 @@ function formatShortDate(iso: string | undefined): string {
 }
 
 /** Render the audit-verdict pill with the right semantic colors. */
-function AuditPill({ audit, t }: { audit?: AuditRecord; t: (key: string, fallback?: string, opts?: object) => string }) {
+// exactOptionalPropertyTypes (#657): widen optionals.
+function AuditPill({
+  audit,
+  t,
+}: {
+  audit?: AuditRecord | undefined;
+  t: (key: string, fallback?: string | undefined, opts?: object | undefined) => string;
+}) {
   if (!audit || audit.status !== "completed") {
     return (
       <span className="inline-flex items-center gap-1.5 rounded-sm border border-strong-edge bg-elevated/40 px-2.5 py-1 font-mono text-[11px] uppercase tracking-wider text-meta">
diff --git a/ornn-web/src/components/skill/SkillInstallCard.tsx b/ornn-web/src/components/skill/SkillInstallCard.tsx
index 54823f84..1118caaa 100644
--- a/ornn-web/src/components/skill/SkillInstallCard.tsx
+++ b/ornn-web/src/components/skill/SkillInstallCard.tsx
@@ -194,6 +194,11 @@ export function SkillInstallCard({ skill, className }: SkillInstallCardProps) {
 
   // The prompt is universally available — works for any skill the caller
   // can see. Memoised so flipping tabs doesn't re-stringify on every render.
+  //
+  // #639 — pass the version the user is currently viewing so the pull
+  // URLs include `?version=…`. Without this, copying the prompt from
+  // an older-version page would silently install whatever's `latest`
+  // at install time — the version dropdown on the page would lie.
   const prompt = useMemo(
     () =>
       buildTrySkillPrompt({
@@ -202,8 +207,9 @@ export function SkillInstallCard({ skill, className }: SkillInstallCardProps) {
         description: skill.description,
         metadata: skill.metadata ?? {},
         ornnOrigin: window.location.origin,
+        ...(skill.version ? { version: skill.version } : {}),
       }),
-    [skill.guid, skill.name, skill.description, skill.metadata],
+    [skill.guid, skill.name, skill.description, skill.metadata, skill.version],
   );
 
   // The npx path needs all three of: mirror feature on, skill public,
diff --git a/ornn-web/src/components/skill/SkillPackagePreview.tsx b/ornn-web/src/components/skill/SkillPackagePreview.tsx
index 202c74bf..2ce51299 100644
--- a/ornn-web/src/components/skill/SkillPackagePreview.tsx
+++ b/ornn-web/src/components/skill/SkillPackagePreview.tsx
@@ -11,25 +11,17 @@ import { SkillFileViewer } from "@/components/skill/SkillFileViewer";
 import type { SkillMetadata } from "@/types/skillPackage";
 
 export interface SkillPackagePreviewProps {
-  /** FileTree data structure */
   files: FileNode[];
-  /** Map of file id -> plaintext content */
   fileContents: Map<string, string>;
-  /** Extracted or generated metadata */
   metadata: SkillMetadata | null;
-  /** Allow editing file content (generative mode) */
-  editable?: boolean;
-  /** Callback when file content changes (editable mode) */
-  onContentChange?: (fileId: string, content: string) => void;
-  /** Callback when a new file is created */
-  onCreateFile?: (parentId: string | null, name: string) => void;
-  /** Callback when a new folder is created */
-  onCreateFolder?: (parentId: string | null, name: string) => void;
-  /** Callback when a file is deleted */
-  onFileDelete?: (fileId: string) => void;
-  /** Author name (display only) */
-  authorName?: string;
-  className?: string;
+  // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
+  editable?: boolean | undefined;
+  onContentChange?: ((fileId: string, content: string) => void) | undefined;
+  onCreateFile?: ((parentId: string | null, name: string) => void) | undefined;
+  onCreateFolder?: ((parentId: string | null, name: string) => void) | undefined;
+  onFileDelete?: ((fileId: string) => void) | undefined;
+  authorName?: string | undefined;
+  className?: string | undefined;
 }
 
 /**
diff --git a/ornn-web/src/components/skill/SkillSaveConfirmModal.tsx b/ornn-web/src/components/skill/SkillSaveConfirmModal.tsx
new file mode 100644
index 00000000..1e359a2f
--- /dev/null
+++ b/ornn-web/src/components/skill/SkillSaveConfirmModal.tsx
@@ -0,0 +1,72 @@
+/**
+ * Save-confirmation modal extracted from SkillDetailPage (#453).
+ *
+ * Confirms the user intends to save uncommitted changes back to the
+ * skill package + offers the `skipValidation` opt-out for the trust
+ * scanner. Stateless wrapper — the parent owns the toggle, the parent
+ * triggers the save mutation, the parent passes loading state in.
+ *
+ * @module components/skill/SkillSaveConfirmModal
+ */
+
+import { useTranslation } from "react-i18next";
+import { Button } from "@/components/ui/Button";
+import { Modal } from "@/components/ui/Modal";
+
+export interface SkillSaveConfirmModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  skillName: string;
+  skipValidation: boolean;
+  onSkipValidationChange: (next: boolean) => void;
+  onConfirm: () => void;
+  saving: boolean;
+}
+
+export function SkillSaveConfirmModal({
+  isOpen,
+  onClose,
+  skillName,
+  skipValidation,
+  onSkipValidationChange,
+  onConfirm,
+  saving,
+}: SkillSaveConfirmModalProps) {
+  const { t } = useTranslation();
+  return (
+    <Modal isOpen={isOpen} onClose={onClose} title={t("skillDetail.saveChanges")}>
+      <p className="mb-4 font-text text-sm text-meta">
+        {t("skillDetail.saveConfirm", { name: skillName })}
+      </p>
+      <label className="flex cursor-pointer items-center gap-3 rounded-sm border border-subtle bg-elevated p-3 select-none">
+        <button
+          type="button"
+          role="switch"
+          aria-checked={skipValidation}
+          onClick={() => onSkipValidationChange(!skipValidation)}
+          className={`relative inline-flex h-5 w-9 shrink-0 cursor-pointer rounded-full border-2 border-transparent transition-colors ${
+            skipValidation ? "bg-accent" : "bg-elevated"
+          }`}
+        >
+          <span
+            className={`pointer-events-none inline-block h-4 w-4 rounded-full bg-white shadow transition-transform ${
+              skipValidation ? "translate-x-4" : "translate-x-0"
+            }`}
+          />
+        </button>
+        <div>
+          <p className="font-text text-sm text-strong">{t("skillDetail.skipValidation")}</p>
+          <p className="font-text text-xs text-meta">{t("skillDetail.skipDescription")}</p>
+        </div>
+      </label>
+      <div className="mt-6 flex justify-end gap-3">
+        <Button variant="secondary" size="sm" onClick={onClose}>
+          {t("common.cancel")}
+        </Button>
+        <Button size="sm" onClick={onConfirm} loading={saving}>
+          {t("common.save")}
+        </Button>
+      </div>
+    </Modal>
+  );
+}
diff --git a/ornn-web/src/components/skill/SkillVersionList.tsx b/ornn-web/src/components/skill/SkillVersionList.tsx
index 6135f368..dbd73860 100644
--- a/ornn-web/src/components/skill/SkillVersionList.tsx
+++ b/ornn-web/src/components/skill/SkillVersionList.tsx
@@ -23,30 +23,19 @@ function formatDateSGT(dateStr: string): string {
 export interface SkillVersionListProps {
   versions: SkillVersionEntry[];
   currentVersion: string;
-  /** Fire when the user clicks a version row to switch to it. */
   onSelect: (version: string) => void;
-  /** Show owner-only controls (deprecation toggle, delete). */
   canManage: boolean;
-  /** Fire when the deprecation flag changes; receives the target version. */
-  onToggleDeprecation?: (args: {
+  // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
+  onToggleDeprecation?: ((args: {
     version: string;
     isDeprecated: boolean;
-    deprecationNote?: string;
-  }) => Promise<void> | void;
-  /** Whether a deprecation mutation is currently in flight (for loading state). */
-  isMutating?: boolean;
-  /** Fire when the user confirms a non-latest version delete. */
-  onDeleteVersion?: (version: string) => Promise<void> | void;
-  /** Whether a delete mutation is currently in flight (for loading state). */
-  isDeleting?: boolean;
-  /**
-   * Optional per-version audit summary. Versions present render their
-   * verdict pill (green / yellow / red); versions absent render a
-   * neutral "not audited" pill. Pass `undefined` to suppress audit
-   * pills entirely (e.g. on the explore page).
-   */
-  auditSummary?: Record<string, AuditRecord>;
-  className?: string;
+    deprecationNote?: string | undefined;
+  }) => Promise<void> | void) | undefined;
+  isMutating?: boolean | undefined;
+  onDeleteVersion?: ((version: string) => Promise<void> | void) | undefined;
+  isDeleting?: boolean | undefined;
+  auditSummary?: Record<string, AuditRecord> | undefined;
+  className?: string | undefined;
 }
 
 /**
@@ -59,7 +48,8 @@ function AuditPill({
   audit,
   notAuditedLabel,
 }: {
-  audit?: AuditRecord;
+  // exactOptionalPropertyTypes (#657)
+  audit?: AuditRecord | undefined;
   notAuditedLabel: string;
 }) {
   if (!audit) {
diff --git a/ornn-web/src/components/skill/SkillVersionsBrowserModal.tsx b/ornn-web/src/components/skill/SkillVersionsBrowserModal.tsx
new file mode 100644
index 00000000..b1f422d7
--- /dev/null
+++ b/ornn-web/src/components/skill/SkillVersionsBrowserModal.tsx
@@ -0,0 +1,126 @@
+/**
+ * All-versions browser modal extracted from SkillDetailPage (#453).
+ *
+ * Lists every version of a skill in a scrollable list, lets the user
+ * jump to a different version (or back to "latest" by passing null
+ * for the latest version id), and offers a "Compare versions" button
+ * that opens the diff modal. Owners + admins can also deprecate /
+ * undeprecate / delete individual versions inline via the embedded
+ * `SkillVersionList`.
+ *
+ * The version-delete handler stays inline here because it shows a
+ * success/failure toast — the parent doesn't need to own that flow,
+ * so wrapping it lets the modal swallow the per-row interaction.
+ *
+ * @module components/skill/SkillVersionsBrowserModal
+ */
+
+import { useTranslation } from "react-i18next";
+import { Button } from "@/components/ui/Button";
+import { Modal } from "@/components/ui/Modal";
+import { SkillVersionList } from "@/components/skill/SkillVersionList";
+import { useToastStore } from "@/stores/toastStore";
+import { translateError } from "@/utils/translateError";
+import type { AuditRecord } from "@/types/audit";
+import type { SkillVersionEntry } from "@/types/domain";
+
+export interface SkillVersionsBrowserModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  versions: SkillVersionEntry[];
+  currentVersion: string;
+  latestVersion: string;
+  canManage: boolean;
+  /**
+   * Per-version audit summary keyed by version string. Versions absent
+   * render a "not audited" pill in the list. `undefined` suppresses
+   * audit pills entirely.
+   */
+  // exactOptionalPropertyTypes (#657)
+  auditSummary?: Record<string, AuditRecord> | undefined;
+  /** Fire when the user picks a version. Null = jump back to latest. */
+  onSelectVersion: (versionOrNull: string | null) => void;
+  // exactOptionalPropertyTypes (#657)
+  onToggleDeprecation?: ((args: {
+    version: string;
+    isDeprecated: boolean;
+    deprecationNote?: string | undefined;
+  }) => Promise<void> | void) | undefined;
+  deprecationPending: boolean;
+  deleteVersionPending: boolean;
+  deleteVersionAsync: (version: string) => Promise<unknown>;
+  /** Hooked when the user clicks "Compare versions". */
+  onOpenDiff: () => void;
+}
+
+export function SkillVersionsBrowserModal({
+  isOpen,
+  onClose,
+  versions,
+  currentVersion,
+  latestVersion,
+  canManage,
+  auditSummary,
+  onSelectVersion,
+  onToggleDeprecation,
+  deprecationPending,
+  deleteVersionPending,
+  deleteVersionAsync,
+  onOpenDiff,
+}: SkillVersionsBrowserModalProps) {
+  const { t } = useTranslation();
+  const addToast = useToastStore((s) => s.addToast);
+
+  return (
+    <Modal
+      isOpen={isOpen}
+      onClose={onClose}
+      title={t("skillDetail.versionsTitle", "All versions") as string}
+      className="!max-w-3xl"
+    >
+      {versions.length >= 2 && (
+        <div className="mb-4 flex justify-end">
+          <Button variant="secondary" size="sm" onClick={onOpenDiff}>
+            {t("versionDiff.openButton", "Compare versions")}
+          </Button>
+        </div>
+      )}
+      <SkillVersionList
+        versions={versions}
+        currentVersion={currentVersion}
+        onSelect={(v) => {
+          onSelectVersion(v === latestVersion ? null : v);
+          onClose();
+        }}
+        canManage={canManage}
+        onToggleDeprecation={onToggleDeprecation}
+        isMutating={deprecationPending}
+        isDeleting={deleteVersionPending}
+        auditSummary={auditSummary}
+        onDeleteVersion={async (version) => {
+          try {
+            await deleteVersionAsync(version);
+            // If the version the user just deleted was the one
+            // currently being viewed, reset to latest so the page
+            // doesn't 404 on the next render.
+            if (currentVersion === version) onSelectVersion(null);
+            addToast({
+              type: "success",
+              message: t("skillDetail.versionDeleted", "Version v{{version}} deleted", {
+                version,
+              }),
+            });
+          } catch (err) {
+            addToast({
+              type: "error",
+              message: translateError(
+                err,
+                t("skillDetail.versionDeleteFailed", "Failed to delete version"),
+              ),
+            });
+          }
+        }}
+      />
+    </Modal>
+  );
+}
diff --git a/ornn-web/src/components/skill/SkillVersionsCard.tsx b/ornn-web/src/components/skill/SkillVersionsCard.tsx
new file mode 100644
index 00000000..7da0eb8e
--- /dev/null
+++ b/ornn-web/src/components/skill/SkillVersionsCard.tsx
@@ -0,0 +1,70 @@
+/**
+ * Right-rail "Versions" card extracted from SkillDetailPage (#453).
+ *
+ * Shows the current version (with a "latest" eyebrow when the user is
+ * viewing the head), publish date, total version count, and a CTA that
+ * opens the all-versions browser modal owned by the parent page. Pure
+ * presentation — every interactive bit calls back to the parent.
+ *
+ * @module components/skill/SkillVersionsCard
+ */
+
+import { useTranslation } from "react-i18next";
+
+export interface SkillVersionsCardProps {
+  currentVersion: string;
+  publishedOnSGT: string;
+  totalVersions: number;
+  viewingLatest: boolean;
+  onBrowseAll: () => void;
+}
+
+export function SkillVersionsCard({
+  currentVersion,
+  publishedOnSGT,
+  totalVersions,
+  viewingLatest,
+  onBrowseAll,
+}: SkillVersionsCardProps) {
+  const { t } = useTranslation();
+  return (
+    <section className="rounded-md border border-subtle bg-card p-5 card-impression">
+      <h3 className="mb-3.5 flex items-center gap-2 border-b border-dashed border-subtle pb-3 font-mono text-[10px] font-semibold uppercase tracking-[0.18em] text-meta">
+        <svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden>
+          <path d="M21 16V8a2 2 0 0 0-1-1.7l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.7l7 4a2 2 0 0 0 2 0l7-4a2 2 0 0 0 1-1.7z" />
+          <polyline points="3.27 6.96 12 12.01 20.73 6.96" />
+          <line x1="12" y1="22.08" x2="12" y2="12" />
+        </svg>
+        {t("skillDetail.cardVersions", "Versions")}
+      </h3>
+      <div className="mb-1.5 flex items-baseline gap-2">
+        <span className="font-display text-2xl font-semibold tracking-tight text-strong">
+          {currentVersion}
+        </span>
+        {viewingLatest && (
+          <span className="rounded-sm border border-accent/40 px-1.5 py-0.5 font-mono text-[9px] uppercase tracking-[0.16em] text-accent">
+            {t("skillDetail.latest", "latest")}
+          </span>
+        )}
+      </div>
+      <p className="font-mono text-[11px] leading-relaxed tracking-wide text-meta">
+        {t("skillDetail.heroPublishedOn", "Published {{date}}", { date: publishedOnSGT })}
+        {totalVersions > 1 && (
+          <>
+            {" · "}
+            {t("skillDetail.versionsTotal", "{{n}} versions total", { n: totalVersions })}
+          </>
+        )}
+      </p>
+      <div className="mt-3.5 flex flex-col gap-2">
+        <button
+          type="button"
+          onClick={onBrowseAll}
+          className="inline-flex items-center gap-1 self-start py-1 font-mono text-[10px] uppercase tracking-widest text-accent transition-all hover:text-accent-muted hover:gap-2"
+        >
+          {t("skillDetail.browseVersions", "Browse all versions")} →
+        </button>
+      </div>
+    </section>
+  );
+}
diff --git a/ornn-web/src/components/skill/SkillVisibilityCard.tsx b/ornn-web/src/components/skill/SkillVisibilityCard.tsx
new file mode 100644
index 00000000..dbde1c11
--- /dev/null
+++ b/ornn-web/src/components/skill/SkillVisibilityCard.tsx
@@ -0,0 +1,113 @@
+/**
+ * Right-rail "Visibility" card extracted from SkillDetailPage (#453).
+ *
+ * Renders the three-tier visibility ladder:
+ *   public  — `isPrivate: false`
+ *   limited — `isPrivate: true` AND at least one explicit grant
+ *   private — `isPrivate: true` AND no grants — only the author +
+ *             platform admins can see it.
+ *
+ * Plus a per-tier-colored pill, user/org grant counts, and a "Manage
+ * permissions" button for the owner. The actual permissions editor
+ * lives in `PermissionsModal`; this card just opens it.
+ *
+ * @module components/skill/SkillVisibilityCard
+ */
+
+import { useTranslation } from "react-i18next";
+import { Button } from "@/components/ui/Button";
+
+type Tier = "public" | "limited" | "private";
+
+export interface SkillVisibilityCardProps {
+  isPrivate: boolean;
+  sharedWithUsersCount: number;
+  sharedWithOrgsCount: number;
+  isOwner: boolean;
+  onManagePermissions: () => void;
+}
+
+export function SkillVisibilityCard({
+  isPrivate,
+  sharedWithUsersCount,
+  sharedWithOrgsCount,
+  isOwner,
+  onManagePermissions,
+}: SkillVisibilityCardProps) {
+  const { t } = useTranslation();
+  const hasGrants = sharedWithUsersCount > 0 || sharedWithOrgsCount > 0;
+  const tier: Tier = !isPrivate ? "public" : hasGrants ? "limited" : "private";
+
+  const tierClass: Record<Tier, string> = {
+    public: "border-success/40 bg-success-soft text-success",
+    limited: "border-warning/40 bg-warning-soft text-warning",
+    private: "border-info/40 bg-info-soft text-info",
+  };
+  const tierLabel: Record<Tier, string> = {
+    public: t("common.public", "Public"),
+    limited: t("common.limited", "Limited access"),
+    private: t("common.private", "Private"),
+  };
+
+  return (
+    <section className="rounded-md border border-subtle bg-card p-5 card-impression">
+      <h3 className="mb-3.5 flex items-center gap-2 border-b border-dashed border-subtle pb-3 font-mono text-[10px] font-semibold uppercase tracking-[0.18em] text-meta">
+        <svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden>
+          <circle cx="12" cy="12" r="9" /><line x1="3" y1="12" x2="21" y2="12" />
+          <path d="M12 3a14 14 0 0 1 4 9 14 14 0 0 1-4 9 14 14 0 0 1-4-9 14 14 0 0 1 4-9z" />
+        </svg>
+        {t("skillDetail.cardVisibility", "Visibility")}
+      </h3>
+      <span
+        className={`mb-3 inline-flex items-center gap-1.5 rounded-sm border px-2.5 py-1 font-mono text-[11px] uppercase tracking-wider ${tierClass[tier]}`}
+      >
+        <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+          {tier === "public" ? (
+            <>
+              <circle cx="12" cy="12" r="9" />
+              <line x1="3" y1="12" x2="21" y2="12" />
+            </>
+          ) : tier === "limited" ? (
+            <>
+              <path d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2" />
+              <circle cx="9" cy="7" r="4" />
+              <path d="M23 21v-2a4 4 0 0 0-3-3.87" />
+              <path d="M16 3.13a4 4 0 0 1 0 7.75" />
+            </>
+          ) : (
+            <path d="M12 2a5 5 0 0 0-5 5v3H5a2 2 0 0 0-2 2v8a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-8a2 2 0 0 0-2-2h-2V7a5 5 0 0 0-5-5z" />
+          )}
+        </svg>
+        {tierLabel[tier]}
+      </span>
+      <ul className="space-y-1.5 font-text text-sm text-body">
+        <li className="flex items-baseline gap-2.5">
+          <span className="min-w-[18px] text-right font-mono text-sm font-semibold text-strong">
+            {sharedWithUsersCount}
+          </span>
+          <span className="text-xs text-meta">{t("skillDetail.shareUsers", "users")}</span>
+        </li>
+        <li className="flex items-baseline gap-2.5">
+          <span className="min-w-[18px] text-right font-mono text-sm font-semibold text-strong">
+            {sharedWithOrgsCount}
+          </span>
+          <span className="text-xs text-meta">
+            {t("skillDetail.shareOrgs", "organizations")}
+          </span>
+        </li>
+      </ul>
+      {isOwner && (
+        <div className="mt-3.5">
+          <Button
+            variant="secondary"
+            size="sm"
+            className="w-full"
+            onClick={onManagePermissions}
+          >
+            {t("skillDetail.managePermissions", "Manage permissions")}
+          </Button>
+        </div>
+      )}
+    </section>
+  );
+}
diff --git a/ornn-web/src/components/skill/guided/StepBasicInfo.tsx b/ornn-web/src/components/skill/guided/StepBasicInfo.tsx
index 565f666a..09767e23 100644
--- a/ornn-web/src/components/skill/guided/StepBasicInfo.tsx
+++ b/ornn-web/src/components/skill/guided/StepBasicInfo.tsx
@@ -214,6 +214,16 @@ export function StepBasicInfo({
                 placeholder={t("guided.envVarsPlaceholder")}
                 helperText={t("guided.envVarsHelper")}
                 badgeColor="yellow"
+                // #683 — frontend + backend frontmatter schemas both
+                // cap `runtime-env-var` at 30. Without `max={30}` the
+                // component defaulted to 50, so the input happily
+                // accepted up to 50 chips and only the Zod submit-time
+                // validator caught the overage — NEXT just appeared to
+                // not work. Passing the explicit cap surfaces the
+                // limit in the field header (`N/30`), disables the
+                // input at the cap, and rejects pasted-past-cap input
+                // inline with "Maximum 30 values".
+                max={30}
                 validate={(v) =>
                   /^[A-Z_][A-Z0-9_]*$/.test(v)
                     ? null
diff --git a/ornn-web/src/components/skill/guided/StepPreview.tsx b/ornn-web/src/components/skill/guided/StepPreview.tsx
index c9455b51..52d3dfec 100644
--- a/ornn-web/src/components/skill/guided/StepPreview.tsx
+++ b/ornn-web/src/components/skill/guided/StepPreview.tsx
@@ -14,7 +14,8 @@ export interface StepPreviewProps {
   files: FileNode[];
   fileContents: Map<string, string>;
   metadata: SkillMetadata | null;
-  authorName?: string;
+  // exactOptionalPropertyTypes (#657)
+  authorName?: string | undefined;
 }
 
 export function StepPreview({ files, fileContents, metadata, authorName }: StepPreviewProps) {
diff --git a/ornn-web/src/components/ui/Badge.tsx b/ornn-web/src/components/ui/Badge.tsx
index e010fd16..52acc966 100644
--- a/ornn-web/src/components/ui/Badge.tsx
+++ b/ornn-web/src/components/ui/Badge.tsx
@@ -17,8 +17,9 @@ import type { ReactNode } from "react";
 
 export interface BadgeProps {
   children: ReactNode;
-  color?: "cyan" | "magenta" | "yellow" | "green" | "red" | "muted";
-  className?: string;
+  // exactOptionalPropertyTypes (#657)
+  color?: "cyan" | "magenta" | "yellow" | "green" | "red" | "muted" | undefined;
+  className?: string | undefined;
 }
 
 const COLOR_MAP = {
diff --git a/ornn-web/src/components/ui/Input.tsx b/ornn-web/src/components/ui/Input.tsx
index 386da838..14c56755 100644
--- a/ornn-web/src/components/ui/Input.tsx
+++ b/ornn-web/src/components/ui/Input.tsx
@@ -9,8 +9,11 @@
 import { forwardRef } from "react";
 
 export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
-  label?: string;
-  error?: string;
+  // Optionals widen to `T | undefined` so form-state callsites passing
+  // `error: errors.field` (which is `string | undefined`) fit under
+  // exactOptionalPropertyTypes (#657).
+  label?: string | undefined;
+  error?: string | undefined;
 }
 
 export const Input = forwardRef<HTMLInputElement, InputProps>(
diff --git a/ornn-web/src/components/ui/NeonSkeleton.tsx b/ornn-web/src/components/ui/NeonSkeleton.tsx
index 1ff02645..284bb993 100644
--- a/ornn-web/src/components/ui/NeonSkeleton.tsx
+++ b/ornn-web/src/components/ui/NeonSkeleton.tsx
@@ -67,6 +67,7 @@ export function NeonSkeleton({
     return (
       <div className={`flex flex-col gap-2 ${className}`}>
         {Array.from({ length: lines }).map((_, i) => (
+          // Positional list — never reorders, key={i} is intentional (#451).
           <div
             key={i}
             className={`skeleton-shimmer ${VARIANT_STYLES[variant]}`}
@@ -141,6 +142,7 @@ export function TableRowSkeleton({ columns = 5, className = "" }: TableRowSkelet
   return (
     <tr className={className}>
       {Array.from({ length: columns }).map((_, i) => (
+        // Positional list — never reorders, key={i} is intentional (#451).
         <td key={i} className="px-4 py-3">
           <NeonSkeleton
             variant="text"
@@ -300,6 +302,7 @@ export function SkeletonGrid({ count = 6, columns = 3, className = "" }: Skeleto
   return (
     <div className={`grid gap-6 ${gridCols[columns]} ${className}`}>
       {Array.from({ length: count }).map((_, i) => (
+        // Positional list — never reorders, key={i} is intentional (#451).
         <SkillCardSkeleton key={i} />
       ))}
     </div>
diff --git a/ornn-web/src/components/ui/Pagination.tsx b/ornn-web/src/components/ui/Pagination.tsx
index f5e997f8..04fb0551 100644
--- a/ornn-web/src/components/ui/Pagination.tsx
+++ b/ornn-web/src/components/ui/Pagination.tsx
@@ -1,3 +1,4 @@
+import { useTranslation } from "react-i18next";
 import { Button } from "./Button";
 
 export interface PaginationProps {
@@ -8,6 +9,12 @@ export interface PaginationProps {
 }
 
 export function Pagination({ page, totalPages, onPageChange, className = "" }: PaginationProps) {
+  // #682 — `Prev` / `Next` labels are visible UI strings on every
+  // paginated list (Registry, admin tables, lifetime drawer). They
+  // were hardcoded, so ZH mode kept showing the English words. Pull
+  // from `common.prev` / `common.next` which already exist in both
+  // locale files.
+  const { t } = useTranslation();
   if (totalPages <= 1) return null;
 
   const pages = buildPageNumbers(page, totalPages);
@@ -20,7 +27,7 @@ export function Pagination({ page, totalPages, onPageChange, className = "" }: P
         disabled={page <= 1}
         onClick={() => onPageChange(page - 1)}
       >
-        Prev
+        {t("common.prev")}
       </Button>
 
       {pages.map((p, i) =>
@@ -46,7 +53,7 @@ export function Pagination({ page, totalPages, onPageChange, className = "" }: P
         disabled={page >= totalPages}
         onClick={() => onPageChange(page + 1)}
       >
-        Next
+        {t("common.next")}
       </Button>
     </nav>
   );
diff --git a/ornn-web/src/components/ui/Select.tsx b/ornn-web/src/components/ui/Select.tsx
index 1a53c829..f8a275fb 100644
--- a/ornn-web/src/components/ui/Select.tsx
+++ b/ornn-web/src/components/ui/Select.tsx
@@ -14,10 +14,11 @@ export interface SelectOption {
 }
 
 export interface SelectProps extends React.SelectHTMLAttributes<HTMLSelectElement> {
-  label?: string;
-  error?: string;
+  // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
+  label?: string | undefined;
+  error?: string | undefined;
   options: SelectOption[];
-  placeholder?: string;
+  placeholder?: string | undefined;
 }
 
 // Inline ember chevron — strokes the var(--color-accent) at runtime.
diff --git a/ornn-web/src/components/ui/Toast.tsx b/ornn-web/src/components/ui/Toast.tsx
index 6b0ff591..a67db23d 100644
--- a/ornn-web/src/components/ui/Toast.tsx
+++ b/ornn-web/src/components/ui/Toast.tsx
@@ -166,7 +166,11 @@ export function ToastContainer({
 
   return (
     <div
-      className={`pointer-events-none fixed z-50 flex flex-col gap-3 ${POSITION_STYLES[position]} ${className}`}
+      // z-[60] (#699) — modals sit at z-50; without this bump the
+      // toast portal renders behind any open modal overlay and the
+      // operation result for an in-modal action (e.g. delete inside
+      // the all-versions modal) becomes dim and unreadable.
+      className={`pointer-events-none fixed z-[60] flex flex-col gap-3 ${POSITION_STYLES[position]} ${className}`}
       role="region"
       aria-label={t("common.aria.notifications")}
     >
@@ -183,16 +187,19 @@ export function ToastContainer({
 
 export function useToast() {
   const addToast = useToastStore((s) => s.addToast);
+  // exactOptionalPropertyTypes (#657): conditional spread on duration
+  // so we don't pass `{ duration: undefined }` to a contract that wants
+  // `duration?: number`.
   return {
     success: (message: string, duration?: number) =>
-      addToast({ type: "success", message, duration }),
+      addToast({ type: "success", message, ...(duration !== undefined ? { duration } : {}) }),
     error: (message: string, duration?: number) =>
-      addToast({ type: "error", message, duration }),
+      addToast({ type: "error", message, ...(duration !== undefined ? { duration } : {}) }),
     warning: (message: string, duration?: number) =>
-      addToast({ type: "warning", message, duration }),
+      addToast({ type: "warning", message, ...(duration !== undefined ? { duration } : {}) }),
     info: (message: string, duration?: number) =>
-      addToast({ type: "info", message, duration }),
+      addToast({ type: "info", message, ...(duration !== undefined ? { duration } : {}) }),
     custom: (type: ToastType["type"], message: string, duration?: number) =>
-      addToast({ type, message, duration }),
+      addToast({ type, message, ...(duration !== undefined ? { duration } : {}) }),
   };
 }
diff --git a/ornn-web/src/components/user/ProfileCard.tsx b/ornn-web/src/components/user/ProfileCard.tsx
index 28842387..c1aa41a6 100644
--- a/ornn-web/src/components/user/ProfileCard.tsx
+++ b/ornn-web/src/components/user/ProfileCard.tsx
@@ -88,10 +88,11 @@ export function ProfileCard({
     setError(null);
 
     try {
+      // exactOptionalPropertyTypes (#657)
       await onUpdate({
         displayName: data.displayName,
-        bio: data.bio || undefined,
-        avatarUrl: avatarUrl !== user.avatarUrl ? avatarUrl : undefined,
+        ...(data.bio ? { bio: data.bio } : {}),
+        ...(avatarUrl !== user.avatarUrl ? { avatarUrl } : {}),
       });
       setIsEditing(false);
     } catch (err) {
diff --git a/ornn-web/src/hooks/useAnalytics.ts b/ornn-web/src/hooks/useAnalytics.ts
index a048b6e5..d37a6045 100644
--- a/ornn-web/src/hooks/useAnalytics.ts
+++ b/ornn-web/src/hooks/useAnalytics.ts
@@ -15,7 +15,8 @@ import type {
 
 export function useSkillAnalytics(
   idOrName: string | undefined,
-  options: { window?: AnalyticsWindow; version?: string } = {},
+  // exactOptionalPropertyTypes (#657)
+  options: { window?: AnalyticsWindow | undefined; version?: string | undefined } = {},
 ) {
   const window = options.window ?? "30d";
   return useQuery<SkillAnalyticsSummary | null>({
@@ -32,11 +33,12 @@ export function useSkillAnalytics(
  */
 export function useSkillPulls(
   idOrName: string | undefined,
+  // exactOptionalPropertyTypes (#657)
   options: {
     bucket: PullBucket;
-    from?: string;
-    to?: string;
-    version?: string;
+    from?: string | undefined;
+    to?: string | undefined;
+    version?: string | undefined;
   },
 ) {
   return useQuery<PullBucketCount[]>({
diff --git a/ornn-web/src/hooks/useAudit.ts b/ornn-web/src/hooks/useAudit.ts
index f2003b39..3fba1861 100644
--- a/ornn-web/src/hooks/useAudit.ts
+++ b/ornn-web/src/hooks/useAudit.ts
@@ -34,7 +34,8 @@ export function useSkillAudit(idOrName: string | undefined, opts: FetchAuditOpti
 
 export function useSkillAuditHistory(
   idOrName: string | undefined,
-  options: { version?: string } = {},
+  // exactOptionalPropertyTypes (#657)
+  options: { version?: string | undefined } = {},
 ) {
   return useQuery<AuditRecord[]>({
     queryKey: auditHistoryKey(idOrName ?? "", options.version),
diff --git a/ornn-web/src/hooks/useNotifications.ts b/ornn-web/src/hooks/useNotifications.ts
index fc0b0940..7ee87e59 100644
--- a/ornn-web/src/hooks/useNotifications.ts
+++ b/ornn-web/src/hooks/useNotifications.ts
@@ -31,6 +31,14 @@ export function useNotifications(opts: ListNotificationsOptions = {}) {
     queryFn: () => fetchNotifications(opts),
     enabled: isAuthed,
     staleTime: 10_000,
+    // #728 — bell dropdown subscribes to this query. Without a
+    // refetch interval, the badge (from useUnreadNotificationCount,
+    // polled every 30s) would tick to a new count while the list
+    // stayed frozen — user sees "1 unread" with a dropdown that
+    // doesn't actually show the new item. Mirror the count's poll
+    // so the two stay in sync.
+    refetchInterval: isAuthed ? UNREAD_POLL_MS : false,
+    refetchIntervalInBackground: false,
   });
 }
 
diff --git a/ornn-web/src/hooks/usePlaygroundChat.ts b/ornn-web/src/hooks/usePlaygroundChat.ts
index 0c271a59..2d3add21 100644
--- a/ornn-web/src/hooks/usePlaygroundChat.ts
+++ b/ornn-web/src/hooks/usePlaygroundChat.ts
@@ -19,10 +19,12 @@
  */
 
 import { useCallback, useRef, useEffect } from "react";
+import { useQueryClient } from "@tanstack/react-query";
 import { usePlaygroundStore } from "@/stores/playgroundStore";
 import { streamChat, type StreamHandle } from "@/services/playgroundStreamApi";
 import type { PlaygroundChatEvent, FileOutput } from "@/types/playground";
 import { track } from "@/lib/analytics";
+import { MY_QUOTA_KEY } from "@/hooks/useQuota";
 
 /**
  * Pacer tick interval. 22 ms ≈ 45 chars/sec when the buffer is small,
@@ -64,6 +66,14 @@ function triggerFileDownload(file: FileOutput) {
 export function usePlaygroundChat() {
   const store = usePlaygroundStore();
   const streamRef = useRef<StreamHandle | null>(null);
+  // Backend charges quota inside the chat handler on `finish` /
+  // `error` — both are billable events. Without an explicit
+  // invalidate, the page renders the pre-charge `useMyQuota` snapshot
+  // until the 60-second poll lands. That's how #630 was happening:
+  // user consumed their last call, the UI still said "1 remaining"
+  // for up to a minute, and a hard refresh was the only way to see
+  // the over-limit state.
+  const qc = useQueryClient();
 
   // Pacer state — chars received from SSE that haven't been painted yet.
   const pendingTokensRef = useRef("");
@@ -142,6 +152,10 @@ export function usePlaygroundChat() {
           s.setError(event.message);
           s.setStreaming(false);
           track("playground.run.failed", { error: event.message });
+          // #630 — error paths can still bill (e.g. tool-call charged
+          // before the LLM blew up), so refresh the snapshot the same
+          // way as the success path.
+          qc.invalidateQueries({ queryKey: MY_QUOTA_KEY });
           break;
 
         case "finish":
@@ -151,10 +165,14 @@ export function usePlaygroundChat() {
           track("playground.run.completed", {
             finishReason: event.finishReason,
           });
+          // #630 — pull the post-charge snapshot so the chip / banner /
+          // OverLimitPage gate reflect the actual remaining count
+          // immediately instead of waiting for the 60s poll.
+          qc.invalidateQueries({ queryKey: MY_QUOTA_KEY });
           break;
       }
     },
-    [drainAll, ensurePacer],
+    [drainAll, ensurePacer, qc],
   );
 
   const sendMessage = useCallback(
diff --git a/ornn-web/src/hooks/usePlaygroundSession.ts b/ornn-web/src/hooks/usePlaygroundSession.ts
new file mode 100644
index 00000000..f7782066
--- /dev/null
+++ b/ornn-web/src/hooks/usePlaygroundSession.ts
@@ -0,0 +1,282 @@
+/**
+ * usePlaygroundSession — page-level state hook for PlaygroundPage (#453).
+ *
+ * Pulls every query, ref, derived value, drawer state, and handler
+ * callback out of the page so the page file is left with just the
+ * layout shell + prop wiring.
+ *
+ * Owns:
+ * - **Queries**: useSkill, useSkillPackage, useMyQuota, usePlaygroundChat.
+ * - **Refs**: messagesEndRef + messagesScrollRef (scroll anchor + the
+ *   scrollable container), chatInputRef (composer focus + setValue),
+ *   stickToBottomRef (tracks whether the user has manually scrolled away
+ *   from the live tail), closeTimerRef (drawer hover-close debounce).
+ * - **Derived state**: skillCategory, previewMetadata, envVarKeys,
+ *   needsEnvVars, allEnvVarsFilled, envIncomplete, playgroundSnap,
+ *   isOverLimit, activeDrawer.
+ * - **Local state**: envVars dict, pickedModelId, hoverDrawer,
+ *   pinnedDrawer.
+ * - **Effects**: scroll-stick listener, auto-scroll on new messages,
+ *   Esc-to-unpin-drawer, auto-pin Env when incomplete, per-skill chat
+ *   reset (clears chat + envVars + scroll state when skillName changes
+ *   AND on unmount).
+ * - **Handlers**: handleEnvVarChange, handleSend, handleStarterClick,
+ *   openHover, scheduleHoverClose, togglePin.
+ *
+ * @module hooks/usePlaygroundSession
+ */
+
+import { useState, useRef, useEffect, useMemo, useCallback } from "react";
+import { ChatInputHandle } from "@/components/playground/ChatInput";
+import {
+  createDefaultSkillMetadata,
+  type SkillMetadata,
+} from "@/types/skillPackage";
+import type { SkillCategory } from "@/utils/constants";
+import { useSkill } from "@/hooks/useSkills";
+import { useSkillPackage } from "@/hooks/useSkillPackage";
+import { usePlaygroundChat } from "@/hooks/usePlaygroundChat";
+import { useMyQuota } from "@/hooks/useQuota";
+import {
+  extractEnvVarKeys,
+  isRuntimeBased,
+} from "@/components/playground/PlaygroundHelpers";
+import type { DrawerKey } from "@/components/playground/PlaygroundRail";
+
+export function usePlaygroundSession(skillName: string | null) {
+  const { data: skill, isLoading: skillLoading, error: skillError } = useSkill(skillName ?? "");
+  const {
+    files: packageFiles,
+    fileContents: packageContents,
+    isLoading: packageLoading,
+  } = useSkillPackage(skill?.presignedPackageUrl);
+
+  // ── Env vars ────────────────────────────────────────────────────────
+  const envVarKeys = useMemo(
+    () => extractEnvVarKeys((skill?.metadata as Record<string, unknown>) ?? null),
+    [skill?.metadata],
+  );
+  const needsEnvVars = useMemo(
+    () =>
+      isRuntimeBased((skill?.metadata as Record<string, unknown>) ?? null) &&
+      envVarKeys.length > 0,
+    [skill?.metadata, envVarKeys],
+  );
+  const [envVars, setEnvVars] = useState<Record<string, string>>({});
+  const allEnvVarsFilled = useMemo(() => {
+    if (!needsEnvVars) return true;
+    return envVarKeys.every((key) => envVars[key]?.trim());
+  }, [needsEnvVars, envVarKeys, envVars]);
+  const handleEnvVarChange = useCallback((key: string, value: string) => {
+    setEnvVars((prev) => ({ ...prev, [key]: value }));
+  }, []);
+
+  // ── Model picker ────────────────────────────────────────────────────
+  const [pickedModelId, setPickedModelId] = useState<string | null>(null);
+
+  // ── Quota ───────────────────────────────────────────────────────────
+  const { data: quotaSnapshot } = useMyQuota();
+  const playgroundSnap = quotaSnapshot?.playground;
+  const isOverLimit =
+    Boolean(playgroundSnap) && !quotaSnapshot?.isAdmin && playgroundSnap!.remaining <= 0;
+
+  // ── Chat state (Zustand-backed via usePlaygroundChat) ───────────────
+  const {
+    messages,
+    isStreaming,
+    toolCallStatuses,
+    fileOutputs,
+    error,
+    currentAssistantContent,
+    sendMessage,
+    abort,
+    clearChat,
+  } = usePlaygroundChat();
+
+  // ── Scroll refs ─────────────────────────────────────────────────────
+  const messagesEndRef = useRef<HTMLDivElement>(null);
+  const messagesScrollRef = useRef<HTMLDivElement>(null);
+  const chatInputRef = useRef<ChatInputHandle>(null);
+  // Tracks whether the user has manually scrolled away from the bottom.
+  // While true, we do NOT yank them back on each token flush.
+  const stickToBottomRef = useRef(true);
+
+  useEffect(() => {
+    const el = messagesScrollRef.current;
+    if (!el) return;
+    const onScroll = () => {
+      const distFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
+      stickToBottomRef.current = distFromBottom < 80;
+    };
+    el.addEventListener("scroll", onScroll, { passive: true });
+    return () => el.removeEventListener("scroll", onScroll);
+  }, []);
+
+  // Auto-scroll only when stick-to-bottom is on (i.e. user hasn't
+  // scrolled up). Uses `auto` (instant) instead of `smooth` during
+  // streaming because `smooth` queues animations and gets choppy with
+  // 50ms-batched token flushes.
+  useEffect(() => {
+    if (!stickToBottomRef.current) return;
+    messagesEndRef.current?.scrollIntoView({ behavior: "auto" });
+  }, [messages, currentAssistantContent]);
+
+  // ── Send / starter handlers ────────────────────────────────────────
+  const handleSend = useCallback(
+    (content: string) => {
+      sendMessage(
+        content,
+        skillName ?? undefined,
+        needsEnvVars ? envVars : undefined,
+        pickedModelId ?? undefined,
+      );
+    },
+    [sendMessage, skillName, envVars, needsEnvVars, pickedModelId],
+  );
+
+  const handleStarterClick = useCallback((body: string) => {
+    chatInputRef.current?.setValue(body);
+  }, []);
+
+  // ── Drawer state ────────────────────────────────────────────────────
+  // `hover` = mouse is on a rail tab or inside the drawer (auto-close
+  // when it leaves). `pinned` = clicked open; stays until clicked
+  // again, click outside, or Esc.
+  const [hoverDrawer, setHoverDrawer] = useState<DrawerKey | null>(null);
+  const [pinnedDrawer, setPinnedDrawer] = useState<DrawerKey | null>(null);
+  const closeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const openHover = useCallback((key: DrawerKey) => {
+    if (closeTimerRef.current) {
+      clearTimeout(closeTimerRef.current);
+      closeTimerRef.current = null;
+    }
+    setHoverDrawer(key);
+  }, []);
+  const scheduleHoverClose = useCallback(() => {
+    if (closeTimerRef.current) clearTimeout(closeTimerRef.current);
+    closeTimerRef.current = setTimeout(() => {
+      setHoverDrawer(null);
+      closeTimerRef.current = null;
+    }, 220);
+  }, []);
+  const togglePin = useCallback((key: DrawerKey) => {
+    setPinnedDrawer((cur) => (cur === key ? null : key));
+    setHoverDrawer(null);
+  }, []);
+
+  // Close pinned drawer on Esc
+  useEffect(() => {
+    if (!pinnedDrawer) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setPinnedDrawer(null);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [pinnedDrawer]);
+
+  // Auto-pin Env when env vars are missing — the user MUST fill them
+  // before chatting, so make it obvious without forcing them to discover
+  // the drawer hint.
+  const envIncomplete = needsEnvVars && !allEnvVarsFilled;
+  useEffect(() => {
+    if (envIncomplete) setPinnedDrawer("env");
+  }, [envIncomplete]);
+
+  // ── Per-skill session lifecycle ────────────────────────────────────
+  // Each Playground visit (and each switch between skills) starts a
+  // fresh chat. Without this, the Zustand store carries stale messages
+  // across navigation — confusing UX and breaking any per-session
+  // analytics that assume a session begins on mount.
+  useEffect(() => {
+    clearChat();
+    setEnvVars({});
+    stickToBottomRef.current = true;
+    return () => {
+      clearChat();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [skillName]);
+
+  const activeDrawer = pinnedDrawer ?? hoverDrawer;
+
+  const skillCategory = (skill?.metadata as Record<string, unknown> | null)?.category as
+    | string
+    | undefined;
+
+  // Synthesise a SkillMetadata-shaped object from the registry skill
+  // record so SkillPackagePreview can render the same flat identity
+  // strip as the generative page. The preview only reads name /
+  // description / category / tag, so we don't need to faithfully
+  // reproduce the rest of the shape — `createDefaultSkillMetadata` fills
+  // the unused fields with safe defaults. Declared above the early-
+  // return guards so the hook order is stable.
+  const previewMetadata = useMemo<SkillMetadata | null>(() => {
+    if (!skill) return null;
+    return createDefaultSkillMetadata({
+      name: skill.name,
+      description: skill.description ?? "",
+      version: skill.version,
+      metadata: {
+        category: (skillCategory as SkillCategory) ?? "plain",
+        runtime: [],
+        runtimeDependency: [],
+        runtimeEnvVar: [],
+        toolList: [],
+        tag: skill.tags ?? [],
+      },
+    });
+  }, [skill, skillCategory]);
+
+  return {
+    // ── queries ──
+    skill,
+    skillLoading,
+    skillError,
+    packageFiles,
+    packageContents,
+    packageLoading,
+    quotaSnapshot,
+    playgroundSnap,
+    isOverLimit,
+    // ── chat ──
+    messages,
+    isStreaming,
+    toolCallStatuses,
+    fileOutputs,
+    error,
+    currentAssistantContent,
+    abort,
+    clearChat,
+    // ── refs ──
+    messagesEndRef,
+    messagesScrollRef,
+    chatInputRef,
+    // ── env ──
+    envVarKeys,
+    needsEnvVars,
+    envVars,
+    allEnvVarsFilled,
+    envIncomplete,
+    handleEnvVarChange,
+    // ── send + starter ──
+    handleSend,
+    handleStarterClick,
+    // ── model ──
+    pickedModelId,
+    setPickedModelId,
+    // ── drawer ──
+    hoverDrawer,
+    setHoverDrawer,
+    pinnedDrawer,
+    setPinnedDrawer,
+    activeDrawer,
+    openHover,
+    scheduleHoverClose,
+    togglePin,
+    // ── derived ──
+    previewMetadata,
+  };
+}
+
+export type PlaygroundSession = ReturnType<typeof usePlaygroundSession>;
diff --git a/ornn-web/src/hooks/useQuota.ts b/ornn-web/src/hooks/useQuota.ts
index c8f21cee..98d3d436 100644
--- a/ornn-web/src/hooks/useQuota.ts
+++ b/ornn-web/src/hooks/useQuota.ts
@@ -71,11 +71,12 @@ export function useSurfaceQuota(
   };
 }
 
+// exactOptionalPropertyTypes (#657)
 export function useAdminQuotaUsers(params: {
   surface: Surface;
-  page?: number;
-  pageSize?: number;
-  q?: string;
+  page?: number | undefined;
+  pageSize?: number | undefined;
+  q?: string | undefined;
 }) {
   return useQuery({
     queryKey: ["admin", "quota", "users", params] as const,
diff --git a/ornn-web/src/hooks/useSkillDetail.ts b/ornn-web/src/hooks/useSkillDetail.ts
new file mode 100644
index 00000000..991b14bd
--- /dev/null
+++ b/ornn-web/src/hooks/useSkillDetail.ts
@@ -0,0 +1,455 @@
+/**
+ * useSkillDetail — page-level state hook for SkillDetailPage (#453).
+ *
+ * Pulls all the queries, mutations, derived state, refs, and handlers
+ * out of the page so the page file is left with just the layout shell
+ * and prop wiring. The hook owns:
+ *
+ * - **Queries**: skill, versions, audit summary, audit history, pulls (7d),
+ *   package (files / contents / raw zip).
+ * - **Mutations**: delete skill, delete version, update package,
+ *   deprecation toggle, refresh-from-source, start audit.
+ * - **Derived state**: isOwner, isAdmin, canManageVersions, latestVersion,
+ *   viewingLatest, pullCount7d, mergedContents, mergedFiles,
+ *   versionAudit, versionAuditRunning, ownerDisplayName, ownerAvatarUrl,
+ *   hasChanges.
+ * - **Local UI state**: showDeleteConfirm / showPermissionsModal /
+ *   showAdvancedModal / showSaveConfirm / showAuditStartedModal /
+ *   showVersions / showVersionDiff (all modals + the in-page diff toggle),
+ *   editedContents / addedPaths / deletedPaths / skipValidation.
+ * - **Handlers**: handleVersionChange, handleToggleDeprecation,
+ *   handleContentChange / handleCreateFile / handleCreateFolder /
+ *   handleDeleteFile (file-tree editing), handleSave, handleDeleteConfirm,
+ *   handleDownloadPackage, handleStartAudit.
+ *
+ * Side-effect: resets the version-browser + diff toggles when the skill
+ * id flips so navigating between two skills doesn't leak modal state.
+ *
+ * @module hooks/useSkillDetail
+ */
+
+import { useState, useCallback, useMemo, useEffect } from "react";
+import { useNavigate, useSearchParams } from "react-router-dom";
+import { useTranslation } from "react-i18next";
+import JSZip from "jszip";
+import {
+  useSkill,
+  useDeleteSkill,
+  useDeleteSkillVersion,
+  useUpdateSkillPackage,
+  useSkillVersions,
+  useSetVersionDeprecation,
+  useRefreshSkillFromSource,
+} from "@/hooks/useSkills";
+import { useSkillPackage } from "@/hooks/useSkillPackage";
+import {
+  useStartAudit,
+  useAuditSummaryByVersion,
+  useSkillAuditHistory,
+} from "@/hooks/useAudit";
+import { useSkillPulls } from "@/hooks/useAnalytics";
+import { useCurrentUser, useIsAuthenticated, isAdmin } from "@/stores/authStore";
+import { useToastStore } from "@/stores/toastStore";
+import { buildFileTreeFromEntries, type FileTreeEntry } from "@/utils/fileTreeBuilder";
+import { translateError } from "@/utils/translateError";
+import { track } from "@/lib/analytics";
+import type { FileNode } from "@/components/editor/FileTree";
+
+/** Last-7-days ISO range, anchored to "now". */
+function rangeLast7d(): { from: string; to: string } {
+  const to = new Date();
+  const from = new Date(to.getTime() - 7 * 24 * 60 * 60 * 1000);
+  return { from: from.toISOString(), to: to.toISOString() };
+}
+
+export function useSkillDetail(idOrName: string | undefined) {
+  const navigate = useNavigate();
+  const [searchParams, setSearchParams] = useSearchParams();
+  const addToast = useToastStore((s) => s.addToast);
+  const user = useCurrentUser();
+  const isAuthenticated = useIsAuthenticated();
+  const { t } = useTranslation();
+
+  const versionParam = searchParams.get("version") ?? undefined;
+  const { data: skill, isLoading, error, refetch } = useSkill(idOrName ?? "", versionParam);
+  const { data: versionList = [] } = useSkillVersions(idOrName ?? "");
+  const deleteMutation = useDeleteSkill();
+  const updatePackageMutation = useUpdateSkillPackage(skill?.guid ?? "");
+  const deprecationMutation = useSetVersionDeprecation(idOrName ?? "");
+  const deleteVersionMutation = useDeleteSkillVersion(idOrName ?? "");
+  const { data: auditSummaryByVersion } = useAuditSummaryByVersion(idOrName);
+  // History for the version currently being viewed, so the audit card
+  // can detect an in-flight (status: running) audit and show a loading
+  // state. The hook polls every 3s while any row is running.
+  const { data: versionAuditHistory } = useSkillAuditHistory(idOrName, {
+    version: versionParam,
+  });
+  const refreshMutation = useRefreshSkillFromSource(idOrName ?? "");
+  const startAuditMutation = useStartAudit();
+
+  // 7-day pulls totals — feeds the hero "↓ N pulls · 7d" status pill.
+  const last7d = useMemo(rangeLast7d, []);
+  const { data: pulls7d = [] } = useSkillPulls(skill?.name || skill?.guid, {
+    bucket: "day",
+    from: last7d.from,
+    to: last7d.to,
+    version: skill?.version,
+  });
+  const pullCount7d = useMemo(
+    () => pulls7d.reduce((acc, p) => acc + p.total, 0),
+    [pulls7d],
+  );
+
+  const {
+    files: packageFiles,
+    fileContents: packageContents,
+    rawZip,
+    isLoading: packageLoading,
+    error: packageError,
+  } = useSkillPackage(skill?.presignedPackageUrl);
+
+  const isOwner = !!(isAuthenticated && user?.id && skill?.createdBy === user.id);
+  const isAdminUser = isAdmin(user);
+  const canManageVersions = isOwner || isAdminUser;
+
+  const latestVersion = versionList[0]?.version;
+  const viewingLatest = !versionParam || (latestVersion && versionParam === latestVersion);
+
+  const handleVersionChange = useCallback(
+    (versionOrLatest: string | null) => {
+      const next = new URLSearchParams(searchParams);
+      if (versionOrLatest === null) {
+        next.delete("version");
+      } else {
+        next.set("version", versionOrLatest);
+      }
+      setSearchParams(next, { replace: false });
+    },
+    [searchParams, setSearchParams],
+  );
+
+  const handleToggleDeprecation = useCallback(
+    async ({
+      version,
+      isDeprecated,
+      deprecationNote,
+    }: {
+      version: string;
+      isDeprecated: boolean;
+      deprecationNote?: string | undefined;
+    }) => {
+      try {
+        await deprecationMutation.mutateAsync({ version, isDeprecated, deprecationNote });
+        addToast({ type: "success", message: t("skillDetail.deprecationUpdated") });
+      } catch (err) {
+        const message = translateError(err, t("skillDetail.deprecationFailed"));
+        addToast({ type: "error", message });
+      }
+    },
+    [deprecationMutation, addToast, t],
+  );
+
+  // ── Modal + file-edit state ─────────────────────────────────
+  const [showDeleteConfirm, setShowDeleteConfirm] = useState(false);
+  const [showPermissionsModal, setShowPermissionsModal] = useState(false);
+  const [showAdvancedModal, setShowAdvancedModal] = useState(false);
+  const [showSaveConfirm, setShowSaveConfirm] = useState(false);
+  const [showAuditStartedModal, setShowAuditStartedModal] = useState(false);
+  const [editedContents, setEditedContents] = useState<Map<string, string>>(new Map());
+  const [addedPaths, setAddedPaths] = useState<FileTreeEntry[]>([]);
+  const [deletedPaths, setDeletedPaths] = useState<Set<string>>(new Set());
+  const [skipValidation, setSkipValidation] = useState(false);
+  const [showVersions, setShowVersions] = useState(false);
+  const [showVersionDiff, setShowVersionDiff] = useState(false);
+  const hasChanges = editedContents.size > 0 || addedPaths.length > 0 || deletedPaths.size > 0;
+
+  // Reset version expansion when skill changes.
+  useEffect(() => {
+    setShowVersions(false);
+    setShowVersionDiff(false);
+  }, [skill?.guid]);
+
+  const handleContentChange = useCallback(
+    (fileId: string, content: string) => {
+      setEditedContents((prev) => {
+        const next = new Map(prev);
+        if (packageContents.get(fileId) === content && !addedPaths.some((e) => e.path === fileId)) {
+          next.delete(fileId);
+        } else {
+          next.set(fileId, content);
+        }
+        return next;
+      });
+    },
+    [packageContents, addedPaths],
+  );
+
+  const handleCreateFile = useCallback((parentId: string | null, name: string) => {
+    const path = parentId ? `${parentId}/${name}` : name;
+    setAddedPaths((prev) => [...prev, { path, type: "file", viewable: true, size: 0 }]);
+    setEditedContents((prev) => new Map(prev).set(path, ""));
+  }, []);
+
+  const handleCreateFolder = useCallback((parentId: string | null, name: string) => {
+    const path = parentId ? `${parentId}/${name}` : name;
+    setAddedPaths((prev) => [...prev, { path, type: "folder", viewable: false, size: 0 }]);
+  }, []);
+
+  const handleDeleteFile = useCallback(
+    (fileId: string) => {
+      const prefix = fileId + "/";
+      const isAdded = addedPaths.some((e) => e.path === fileId || e.path.startsWith(prefix));
+
+      if (isAdded) {
+        setAddedPaths((prev) => prev.filter((e) => e.path !== fileId && !e.path.startsWith(prefix)));
+        setEditedContents((prev) => {
+          const next = new Map(prev);
+          for (const key of next.keys()) {
+            if (key === fileId || key.startsWith(prefix)) next.delete(key);
+          }
+          return next;
+        });
+      } else {
+        setDeletedPaths((prev) => {
+          const next = new Set(prev);
+          next.add(fileId);
+          for (const key of packageContents.keys()) {
+            if (key.startsWith(prefix)) next.add(key);
+          }
+          return next;
+        });
+        setEditedContents((prev) => {
+          const next = new Map(prev);
+          for (const key of next.keys()) {
+            if (key === fileId || key.startsWith(prefix)) next.delete(key);
+          }
+          return next;
+        });
+      }
+    },
+    [addedPaths, packageContents],
+  );
+
+  const mergedContents = useMemo(() => {
+    const merged = new Map(packageContents);
+    for (const path of deletedPaths) merged.delete(path);
+    for (const [path, content] of editedContents) merged.set(path, content);
+    return merged;
+  }, [packageContents, editedContents, deletedPaths]);
+
+  const mergedFiles = useMemo(() => {
+    if (addedPaths.length === 0 && deletedPaths.size === 0) return packageFiles;
+    const entries: FileTreeEntry[] = [];
+    function collectEntries(nodes: FileNode[]) {
+      for (const node of nodes) {
+        if (deletedPaths.has(node.id)) continue;
+        entries.push({
+          path: node.id,
+          type: node.type,
+          viewable: node.type === "file",
+          size: 0,
+        });
+        if (node.children) collectEntries(node.children);
+      }
+    }
+    collectEntries(packageFiles);
+    for (const entry of addedPaths) entries.push(entry);
+    return buildFileTreeFromEntries(entries);
+  }, [packageFiles, addedPaths, deletedPaths]);
+
+  const handleSave = useCallback(
+    async (skip: boolean) => {
+      if (!skill) return;
+      setShowSaveConfirm(false);
+      try {
+        const newZip = new JSZip();
+        if (rawZip) {
+          for (const [path, entry] of Object.entries(rawZip.files)) {
+            if (entry.dir) continue;
+            if (deletedPaths.has(path)) continue;
+            if (editedContents.has(path)) {
+              newZip.file(path, editedContents.get(path)!);
+            } else {
+              const data = await entry.async("uint8array");
+              newZip.file(path, data);
+            }
+          }
+        }
+        for (const entry of addedPaths) {
+          if (entry.type === "file" && editedContents.has(entry.path)) {
+            newZip.file(entry.path, editedContents.get(entry.path)!);
+          }
+        }
+        const blob = await newZip.generateAsync({ type: "blob" });
+        const zipFile = new File([blob], `${skill.name}.zip`, { type: "application/zip" });
+        await updatePackageMutation.mutateAsync({ zipFile, skipValidation: skip });
+        track("skill.version_published", {
+          skillId: skill.guid,
+          skipValidation: skip,
+        });
+        addToast({ type: "success", message: t("skillDetail.updateSuccess") });
+        setEditedContents(new Map());
+        setAddedPaths([]);
+        setDeletedPaths(new Set());
+        refetch();
+      } catch (err) {
+        const message = translateError(err, t("skillDetail.saveFailed"));
+        addToast({ type: "error", message });
+      }
+    },
+    [skill, rawZip, deletedPaths, editedContents, addedPaths, updatePackageMutation, addToast, t, refetch],
+  );
+
+  const handleDeleteConfirm = useCallback(async () => {
+    if (!skill) return;
+    try {
+      await deleteMutation.mutateAsync(skill.guid);
+      addToast({ type: "success", message: t("skillDetail.deleteSuccess") });
+      navigate("/registry");
+    } catch {
+      addToast({ type: "error", message: t("skillDetail.deleteFailed") });
+    } finally {
+      setShowDeleteConfirm(false);
+    }
+  }, [skill, deleteMutation, addToast, t, navigate]);
+
+  const handleDownloadPackage = useCallback(async () => {
+    if (!skill || !rawZip) return;
+    const blob = await rawZip.generateAsync({ type: "blob" });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = `${skill.name}.zip`;
+    a.click();
+    URL.revokeObjectURL(url);
+  }, [skill, rawZip]);
+
+  const handleStartAudit = useCallback(() => {
+    if (!skill) return;
+    setShowAuditStartedModal(true);
+    startAuditMutation.mutate(
+      { idOrName: skill.name || skill.guid, force: true },
+      {
+        onSuccess: (record) => {
+          addToast({
+            type: "success",
+            message: t(
+              "skillDetail.auditDone",
+              "Audit complete — verdict {{v}}, score {{s}}/10",
+              { v: record.verdict, s: record.overallScore.toFixed(1) },
+            ),
+          });
+        },
+        onError: (err) => {
+          addToast({
+            type: "error",
+            message: translateError(err),
+          });
+        },
+      },
+    );
+  }, [skill, startAuditMutation, addToast, t]);
+
+  // Derived once `skill` is loaded — undefined while loading is fine
+  // because callers gate on `isLoading`/`error` first.
+  const versionAudit = skill ? auditSummaryByVersion?.[skill.version] : undefined;
+  const versionAuditRunning =
+    versionAuditHistory?.some((r) => r.status === "running") ?? false;
+  // #718 — `auditSummaryByVersion` returns the latest *completed*
+  // record per version, so a newer failed rerun was invisible on
+  // Skill Detail and admins kept seeing the stale prior score as
+  // though it were current. `versionAuditHistory` lists every
+  // record newest-first; if the most recent entry is `failed`
+  // (and newer than the displayed completed audit, when one
+  // exists) we surface that explicitly through `AuditVerdictPill`.
+  const latestVersionAudit = versionAuditHistory?.[0];
+  const versionAuditLatestFailed = Boolean(
+    latestVersionAudit &&
+    latestVersionAudit.status === "failed" &&
+    (!versionAudit ||
+      new Date(latestVersionAudit.createdAt).getTime() >
+        new Date(versionAudit.completedAt ?? versionAudit.createdAt).getTime()),
+  );
+  const ownerDisplayName =
+    isOwner && user?.displayName
+      ? user.displayName
+      : skill
+        ? skill.createdByDisplayName || skill.createdByEmail || skill.createdBy
+        : "";
+  const ownerAvatarUrl = isOwner ? user?.avatarUrl ?? null : null;
+
+  return {
+    // ── primitives ──
+    skill,
+    isLoading,
+    error,
+    refetch,
+    versionList,
+    versionParam,
+    latestVersion,
+    viewingLatest,
+    pullCount7d,
+    packageFiles,
+    packageContents,
+    rawZip,
+    packageLoading,
+    packageError,
+    user,
+    isAuthenticated,
+    isOwner,
+    isAdminUser,
+    canManageVersions,
+    auditSummaryByVersion,
+    versionAudit,
+    versionAuditRunning,
+    versionAuditLatestFailed,
+    ownerDisplayName,
+    ownerAvatarUrl,
+    // ── mutations exposed for the modals' loading states ──
+    deleteMutation,
+    updatePackageMutation,
+    deprecationMutation,
+    deleteVersionMutation,
+    refreshMutation,
+    startAuditMutation,
+    // ── modal + edit state ──
+    showDeleteConfirm,
+    setShowDeleteConfirm,
+    showPermissionsModal,
+    setShowPermissionsModal,
+    showAdvancedModal,
+    setShowAdvancedModal,
+    showSaveConfirm,
+    setShowSaveConfirm,
+    showAuditStartedModal,
+    setShowAuditStartedModal,
+    showVersions,
+    setShowVersions,
+    showVersionDiff,
+    setShowVersionDiff,
+    skipValidation,
+    setSkipValidation,
+    editedContents,
+    setEditedContents,
+    addedPaths,
+    setAddedPaths,
+    deletedPaths,
+    setDeletedPaths,
+    hasChanges,
+    mergedContents,
+    mergedFiles,
+    // ── handlers ──
+    handleVersionChange,
+    handleToggleDeprecation,
+    handleContentChange,
+    handleCreateFile,
+    handleCreateFolder,
+    handleDeleteFile,
+    handleSave,
+    handleDeleteConfirm,
+    handleDownloadPackage,
+    handleStartAudit,
+  };
+}
+
+export type SkillDetailContext = ReturnType<typeof useSkillDetail>;
diff --git a/ornn-web/src/hooks/useSkillGeneration.ts b/ornn-web/src/hooks/useSkillGeneration.ts
index 27920d3d..10485450 100644
--- a/ornn-web/src/hooks/useSkillGeneration.ts
+++ b/ornn-web/src/hooks/useSkillGeneration.ts
@@ -16,13 +16,14 @@ import { track } from "@/lib/analytics";
 /** Minimum interval (ms) between token state flushes */
 const TOKEN_FLUSH_INTERVAL_MS = 50;
 
+// Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
 export interface ChatDisplayMessage {
   id: string;
   role: "user" | "assistant";
   content: string;
-  isStreaming?: boolean;
-  skillName?: string;
-  skillDescription?: string;
+  isStreaming?: boolean | undefined;
+  skillName?: string | undefined;
+  skillDescription?: string | undefined;
 }
 
 interface GenerationState {
@@ -85,10 +86,10 @@ export function useSkillGeneration(): UseSkillGenerationReturn {
     setState((prev) => {
       const messages = [...prev.chatMessages];
       const lastIdx = messages.length - 1;
-      if (lastIdx >= 0 && messages[lastIdx].role === "assistant" && messages[lastIdx].isStreaming) {
+      if (lastIdx >= 0 && messages[lastIdx]!.role === "assistant" && messages[lastIdx]!.isStreaming) {
         messages[lastIdx] = {
-          ...messages[lastIdx],
-          content: messages[lastIdx].content + buffered,
+          ...messages[lastIdx]!,
+          content: messages[lastIdx]!.content + buffered,
         };
       }
       return {
@@ -129,10 +130,10 @@ export function useSkillGeneration(): UseSkillGenerationReturn {
           setState((prev) => {
             const messages = [...prev.chatMessages];
             const lastIdx = messages.length - 1;
-            if (lastIdx >= 0 && messages[lastIdx].role === "assistant" && messages[lastIdx].isStreaming) {
+            if (lastIdx >= 0 && messages[lastIdx]!.role === "assistant" && messages[lastIdx]!.isStreaming) {
               messages[lastIdx] = {
-                ...messages[lastIdx],
-                content: messages[lastIdx].content + buffered,
+                ...messages[lastIdx]!,
+                content: messages[lastIdx]!.content + buffered,
               };
             }
             return {
@@ -189,10 +190,10 @@ export function useSkillGeneration(): UseSkillGenerationReturn {
           setState((prev) => {
             const messages = [...prev.chatMessages];
             const lastIdx = messages.length - 1;
-            if (lastIdx >= 0 && messages[lastIdx].role === "assistant" && messages[lastIdx].isStreaming) {
+            if (lastIdx >= 0 && messages[lastIdx]!.role === "assistant" && messages[lastIdx]!.isStreaming) {
               messages[lastIdx] = {
-                ...messages[lastIdx],
-                content: messages[lastIdx].content + buffered,
+                ...messages[lastIdx]!,
+                content: messages[lastIdx]!.content + buffered,
               };
             }
             return {
diff --git a/ornn-web/src/hooks/useSkills.ts b/ornn-web/src/hooks/useSkills.ts
index 11310c16..c44a1ab7 100644
--- a/ornn-web/src/hooks/useSkills.ts
+++ b/ornn-web/src/hooks/useSkills.ts
@@ -34,13 +34,13 @@ const SKILL_VERSION_DIFF_KEY = "skill-version-diff";
  * Visible to anonymous + authed callers; the System tab itself is the
  * primary consumer.
  */
+// Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
 export function useSystemSkills(params: {
-  query?: string;
+  query?: string | undefined;
   mode?: SkillSearchParams["mode"];
-  page?: number;
-  pageSize?: number;
-  /** Filter to skills tied to a specific NyxID service id. */
-  nyxidServiceId?: string;
+  page?: number | undefined;
+  pageSize?: number | undefined;
+  nyxidServiceId?: string | undefined;
 }) {
   const searchParams: SkillSearchParams = {
     query: params.query,
@@ -58,16 +58,15 @@ export function useSystemSkills(params: {
 }
 
 /** Search public skills */
+// exactOptionalPropertyTypes (#657)
 export function useSkills(params: {
-  query?: string;
+  query?: string | undefined;
   mode?: SkillSearchParams["mode"];
-  page?: number;
-  pageSize?: number;
-  systemFilter?: SystemFilter;
-  /** Tag filter (AND match). */
-  tags?: string[];
-  /** Author user_ids — filter to skills authored by these users. */
-  createdByAny?: string[];
+  page?: number | undefined;
+  pageSize?: number | undefined;
+  systemFilter?: SystemFilter | undefined;
+  tags?: string[] | undefined;
+  createdByAny?: string[] | undefined;
 }) {
   const searchParams: SkillSearchParams = {
     query: params.query,
@@ -91,16 +90,16 @@ export function useSkills(params: {
  * NOT include skills shared with me (those live in the dedicated
  * Shared-with-me tab). Public + private skills I created both appear.
  */
+// exactOptionalPropertyTypes (#657)
 export function useMySkills(params: {
-  query?: string;
+  query?: string | undefined;
   mode?: SkillSearchParams["mode"];
-  page?: number;
-  pageSize?: number;
-  systemFilter?: SystemFilter;
-  sharedWithOrgs?: string[];
-  sharedWithUsers?: string[];
-  /** Tag filter (AND match). */
-  tags?: string[];
+  page?: number | undefined;
+  pageSize?: number | undefined;
+  systemFilter?: SystemFilter | undefined;
+  sharedWithOrgs?: string[] | undefined;
+  sharedWithUsers?: string[] | undefined;
+  tags?: string[] | undefined;
 }) {
   const searchParams: SkillSearchParams = {
     query: params.query,
@@ -125,15 +124,16 @@ export function useMySkills(params: {
  * Excludes own-authored skills and public skills; those live in their
  * dedicated tabs. Gated on auth — anonymous callers get an empty set.
  */
+// exactOptionalPropertyTypes (#657)
 export function useSharedWithMeSkills(params: {
-  query?: string;
+  query?: string | undefined;
   mode?: SkillSearchParams["mode"];
-  page?: number;
-  pageSize?: number;
-  systemFilter?: SystemFilter;
-  sharedWithOrgs?: string[];
-  createdByAny?: string[];
-  enabled?: boolean;
+  page?: number | undefined;
+  pageSize?: number | undefined;
+  systemFilter?: SystemFilter | undefined;
+  sharedWithOrgs?: string[] | undefined;
+  createdByAny?: string[] | undefined;
+  enabled?: boolean | undefined;
 }) {
   const searchParams: SkillSearchParams = {
     query: params.query,
@@ -218,7 +218,8 @@ export function useSetVersionDeprecation(idOrName: string) {
     }: {
       version: string;
       isDeprecated: boolean;
-      deprecationNote?: string;
+      // exactOptionalPropertyTypes (#657)
+      deprecationNote?: string | undefined;
     }) => setSkillVersionDeprecation(idOrName, version, { isDeprecated, deprecationNote }),
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: [SKILLS_KEY, idOrName] });
@@ -261,7 +262,8 @@ export function useRefreshSkillFromSource(idOrName: string) {
       skipValidation,
     }: {
       guid: string;
-      skipValidation?: boolean;
+      // exactOptionalPropertyTypes (#657)
+      skipValidation?: boolean | undefined;
     }) => refreshSkillFromSource(guid, { skipValidation }),
     onSuccess: (updated) => {
       // Prime the detail cache with the refreshed payload so the chip
@@ -381,6 +383,11 @@ export function useDeleteSkillVersion(idOrName: string) {
       queryClient.invalidateQueries({ queryKey: [SKILLS_KEY, idOrName] });
       queryClient.invalidateQueries({ queryKey: [SKILLS_KEY] });
       queryClient.invalidateQueries({ queryKey: [MY_SKILLS_KEY] });
+      // #699 — the All-versions modal subscribes to
+      // [SKILL_VERSIONS_KEY, idOrName]; without this invalidation
+      // the deleted row stays visible and a second delete click
+      // hits the backend with the now-missing version.
+      queryClient.invalidateQueries({ queryKey: [SKILL_VERSIONS_KEY, idOrName] });
       queryClient.invalidateQueries({
         predicate: (q) =>
           Array.isArray(q.queryKey) &&
diff --git a/ornn-web/src/i18n/en.json b/ornn-web/src/i18n/en.json
index f77623f9..9f0907e6 100644
--- a/ornn-web/src/i18n/en.json
+++ b/ornn-web/src/i18n/en.json
@@ -1,4 +1,47 @@
 {
+  "nyxidService": {
+    "intro": "Binding a skill to a NyxID admin service marks it as a system skill (forced public). Binding to one of your personal services leaves the privacy alone.",
+    "untied": "No binding (unbound)",
+    "untiedDesc": "This skill is not bound to any NyxID service. Privacy and sharing remain manually controlled.",
+    "adminTier": "Admin services (system)",
+    "personalTier": "Personal services",
+    "noServices": "No NyxID services available. Ask a platform admin or register one in NyxID.",
+    "willForcePublic": "Binding to an admin service will force this skill to be public. Other share settings (users / orgs) are kept but ignored while the skill is public.",
+    "tieSuccess": "Service bound",
+    "untieSuccess": "Service unbound"
+  },
+  "markdownEditor": {
+    "preview": "Preview",
+    "emptyPreview": "Nothing to preview yet...",
+    "helpText": "Supports Markdown formatting. Use **bold**, _italic_, `code`, and more."
+  },
+  "adminUsersTable": {
+    "filterPlaceholder": "Filter by email or display name…",
+    "empty": "No users found.",
+    "never": "Never",
+    "grantQuota": "Grant quota",
+    "columnUsername": "Username",
+    "columnEmail": "Email",
+    "columnSkills": "Skills",
+    "columnLastActive": "Last active",
+    "columnActivities": "Activities",
+    "columnFirstJoined": "First joined",
+    "sortByPrefix": "Sort by {{label}}"
+  },
+  "sidebar": {
+    "navigation": "Navigation"
+  },
+  "adminSettingsNav": {
+    "llmProviders": "LLM Providers",
+    "playground": "Playground",
+    "skillGeneration": "Skill Generation",
+    "githubMirror": "GitHub Mirror",
+    "nyxidIntegration": "NyxID Integration",
+    "skillAuditing": "Skill Auditing",
+    "postHog": "PostHog",
+    "serviceBinding": "Service Binding List",
+    "exportImport": "Export / Import"
+  },
   "common": {
     "save": "Save",
     "cancel": "Cancel",
@@ -72,17 +115,36 @@
     "auditHistory": "Audit history"
   },
   "explore": {
+    "semanticQueryRequiredTitle": "Enter a search description",
+    "semanticQueryRequiredDesc": "Semantic search needs a description of what you're looking for. Type a phrase in the search box above, or switch back to Keyword mode.",
     "systemSkills": "System Skills",
     "publicSkills": "Public Skills",
     "mySkills": "My Skills",
-    "sharedWithMe": "Shared With Me",
-    "noSkillsFound": "No skills found",
-    "noSharedSkills": "No one has shared a skill with you yet.",
-    "tryAdjusting": "Try adjusting your search, or upload the first skill.",
-    "noSkillsYet": "No skills yet",
-    "createFirst": "Create your first skill to get started",
+    "sharedWithMe": "Shared with me",
+    "noSkillsFound": "No public skills match",
+    "noSharedSkills": "Nothing has been shared with you yet",
+    "tryAdjusting": "Try adjusting your search or filters.",
+    "noSkillsYet": "You haven't created any skills yet",
+    "noSystemSkills": "No system skills yet",
+    "createFirst": "Create your first skill to get started.",
     "uploadSkill": "Upload Skill",
-    "createSkill": "Create Skill"
+    "createSkill": "Create Skill",
+    "filterService": "NyxID service",
+    "filterTags": "Tag",
+    "filterAuthors": "Author",
+    "filterSharedWithUsers": "Shared with users",
+    "filterSharedWithOrgs": "Shared with orgs",
+    "filterSharedByUsers": "Shared by users",
+    "filterSharedByOrgs": "Shared via orgs",
+    "noServices": "No system services yet.",
+    "noTags": "No tags yet.",
+    "noAuthors": "No authors yet.",
+    "notSharedWithUsers": "You haven't shared any skills with specific users.",
+    "notSharedWithOrgs": "You haven't shared any skills with orgs.",
+    "notSharedByUsers": "Nobody has shared with you directly.",
+    "notSharedByOrgs": "No orgs have shared anything with you.",
+    "systemSkillsIntro": "System skills are skills tied to a NyxID admin service. Platform admins tie any skill to any admin service to publish it as a system skill.",
+    "sharedWithMeIntro": "When someone grants you access to a private skill — either directly or via an org — it shows up here."
   },
   "mySkills": {
     "searchPlaceholder": "Search your skills...",
@@ -378,6 +440,8 @@
   },
   "playground": {
     "selectSkill": "Select a skill to try in the playground.",
+    "notFoundTitle": "Skill not found",
+    "notFoundBody": "This skill doesn't exist, or you don't have access to it.",
     "browseSkills": "Browse Skills",
     "clearChat": "Clear Chat",
     "fillEnvVars": "Fill in the required environment variables on the right to start chatting.",
@@ -451,6 +515,13 @@
     "startGithub": "Import"
   },
   "guided": {
+    "validation": {
+      "nameMin": "Name must be at least 2 characters",
+      "nameMax": "Name must be at most 64 characters",
+      "nameShape": "Must start with a letter or number, only lowercase, numbers, and hyphens",
+      "descMin": "Description must be at least 10 characters",
+      "contentMin": "Content must be at least 50 characters"
+    },
     "backToModes": "Back to mode selection",
     "header": "CREATE SKILL",
     "headerDesc": "Follow the steps below to create a new skill",
@@ -513,7 +584,10 @@
     "previewTitle": "Review & Create",
     "dropHint": "Drop file here or click to browse",
     "noFiles": "(no files)",
-    "remove": "Remove"
+    "remove": "Remove",
+    "fileSizeHint": "Per-file limit: {{max}}",
+    "fileTooLarge": "{{name}} is {{size}} — over the {{max}} per-file limit.",
+    "fileDuplicate": "{{name}} already exists in {{folder}}. Remove it first to replace."
   },
   "generative": {
     "backToModes": "Back to mode selection",
@@ -619,7 +693,9 @@
     "awaitingTool": "Awaiting tool approval...",
     "placeholder": "Type a message... (Enter to send, Shift+Enter for newline)",
     "stopGeneration": "Stop generation",
-    "sendMessage": "Send message"
+    "sendMessage": "Send message",
+    "charCount": "{{count}} / {{max}}",
+    "overLimit": "Message too long. Maximum {{max}} characters."
   },
   "quota": {
     "surfacePlayground": "Playground",
@@ -963,6 +1039,14 @@
     "adminUnlimitedUsageTitle": "Admin · Unlimited usage",
     "quotaUsageDetails": "Quota usage details"
   },
+  "search": {
+    "placeholderKeyword": "Search skills by name or description...",
+    "placeholderSemantic": "Describe what you're looking for...",
+    "toggleToKeyword": "Switch to keyword search",
+    "toggleToSemantic": "Switch to semantic search",
+    "modeKeyword": "Keyword",
+    "modeSemantic": "Semantic"
+  },
   "skillComponents": {
     "generateModal": {
       "title": "Generate Skill",
@@ -970,7 +1054,10 @@
       "add": "Add"
     },
     "card": {
-      "linkedToGithub": "Linked to GitHub"
+      "linkedToGithub": "Linked to GitHub",
+      "viaOrganization": "Via organization",
+        "viaOrganizationNamed": "Via {{org}}",
+      "sharedBy": "Shared by {{name}}"
     },
     "grid": {
       "emptyTitle": "No skills found",
@@ -1537,7 +1624,9 @@
       "unrecognizedDirs": "Unrecognized directories found: {{dirs}}. Only scripts/, references/, and assets/ are standard.",
       "frontmatterUnparseable": "Could not extract metadata from SKILL.md frontmatter. You may need to add or fix the YAML frontmatter block.",
       "onlyZipAccepted": "Only .zip files are accepted.",
-      "fileTooLarge": "File too large ({{size}})."
+      "fileTooLarge": "File too large ({{size}}).",
+      "unsafePath": "Unsafe path in ZIP entry: '{{path}}'. Paths may not contain '..', leading slashes, backslashes, or drive-letter prefixes.",
+      "uncompressedTooLarge": "ZIP expands to {{actual}} bytes, which exceeds the limit of {{max}} bytes."
     },
     "frontmatter": {
       "panelTitle": "Frontmatter Validation Errors",
@@ -1548,6 +1637,12 @@
       "envVarFormat": "Environment variable names must be UPPER_SNAKE_CASE",
       "nameFormat": "Name must start with a letter or number and contain only lowercase letters, numbers, and hyphens",
       "versionFormat": "version must be in `<major>.<minor>` format, e.g. `1.0` (non-negative integers, no leading zeroes, no patch digit)",
+      "versionInvalidType": "version must be a quoted string — write `version: \"0.1\"` in SKILL.md, not `version: 0.1` (YAML parses the unquoted form as a number and loses the trailing zero).",
+      "tagInvalidType": "tags must be non-empty lowercase strings with optional hyphens, e.g. `tag: [my-tag]` — an empty `- ` line in YAML parses as `null` and is not a valid tag.",
+      "envVarInvalidType": "runtime-env-var entries must be non-empty UPPER_SNAKE_CASE strings, e.g. `runtime-env-var: [OPENAI_API_KEY]` — an empty `- ` line in YAML parses as `null`.",
+      "toolInvalidType": "tool-list entries must be non-empty strings, e.g. `tool-list: [Bash, Read]` — an empty `- ` line in YAML parses as `null`.",
+      "runtimeInvalidType": "runtime entries must be non-empty strings, e.g. `runtime: [python]` — an empty `- ` line in YAML parses as `null`.",
+      "dependencyInvalidType": "runtime-dependency entries must be non-empty strings, e.g. `runtime-dependency: [requests==2.31]` — an empty `- ` line in YAML parses as `null`.",
       "runtimeRequiredForCategory": "runtime is required when category is '{{category}}'",
       "runtimeForbiddenForCategory": "runtime must not be provided when category is '{{category}}'",
       "toolListRequiredForCategory": "tool-list is required when category is '{{category}}'",
diff --git a/ornn-web/src/i18n/zh.json b/ornn-web/src/i18n/zh.json
index e3d6e1cc..39b6c365 100644
--- a/ornn-web/src/i18n/zh.json
+++ b/ornn-web/src/i18n/zh.json
@@ -1,4 +1,47 @@
 {
+  "nyxidService": {
+    "intro": "将技能绑定到 NyxID 管理员服务会将其标记为系统技能（强制公开）。绑定到个人服务则不会改变隐私设置。",
+    "untied": "未绑定",
+    "untiedDesc": "该技能未绑定任何 NyxID 服务。隐私和共享设置仍由你手动控制。",
+    "adminTier": "管理员服务（系统）",
+    "personalTier": "个人服务",
+    "noServices": "没有可用的 NyxID 服务。请联系平台管理员或在 NyxID 中注册一个。",
+    "willForcePublic": "绑定到管理员服务将强制把该技能设为公开。其他共享设置（用户 / 组织）会被保留，但在技能公开期间不生效。",
+    "tieSuccess": "服务已绑定",
+    "untieSuccess": "服务已解绑"
+  },
+  "markdownEditor": {
+    "preview": "预览",
+    "emptyPreview": "暂无可预览内容…",
+    "helpText": "支持 Markdown 格式。可使用 **粗体**、_斜体_、`代码` 等。"
+  },
+  "adminUsersTable": {
+    "filterPlaceholder": "按邮箱或显示名称筛选…",
+    "empty": "未找到用户。",
+    "never": "从未",
+    "grantQuota": "授予配额",
+    "columnUsername": "用户名",
+    "columnEmail": "邮箱",
+    "columnSkills": "技能数",
+    "columnLastActive": "最近活跃",
+    "columnActivities": "活动数",
+    "columnFirstJoined": "首次加入",
+    "sortByPrefix": "按 {{label}} 排序"
+  },
+  "sidebar": {
+    "navigation": "导航"
+  },
+  "adminSettingsNav": {
+    "llmProviders": "LLM 提供方",
+    "playground": "Playground",
+    "skillGeneration": "技能生成",
+    "githubMirror": "GitHub 镜像",
+    "nyxidIntegration": "NyxID 集成",
+    "skillAuditing": "技能审计",
+    "postHog": "PostHog",
+    "serviceBinding": "服务绑定列表",
+    "exportImport": "导出 / 导入"
+  },
   "common": {
     "save": "保存",
     "cancel": "取消",
@@ -72,17 +115,36 @@
     "auditHistory": "审计历史"
   },
   "explore": {
+    "semanticQueryRequiredTitle": "请输入搜索描述",
+    "semanticQueryRequiredDesc": "语义搜索需要描述你要找的内容。请在上方搜索框中输入一段描述，或切换回关键字模式。",
     "systemSkills": "系统技能",
     "publicSkills": "公共技能",
     "mySkills": "我的技能",
     "sharedWithMe": "分享给我的",
-    "noSkillsFound": "未找到技能",
+    "noSkillsFound": "没有匹配的公共技能。",
     "noSharedSkills": "还没有人把技能分享给你。",
-    "tryAdjusting": "尝试调整搜索条件，或上传第一个技能。",
-    "noSkillsYet": "暂无技能",
-    "createFirst": "创建你的第一个技能开始吧",
+    "tryAdjusting": "尝试调整搜索条件或筛选项。",
+    "noSkillsYet": "你还没有创建任何技能。",
+    "noSystemSkills": "暂无系统技能。",
+    "createFirst": "创建你的第一个技能开始吧。",
     "uploadSkill": "上传技能",
-    "createSkill": "创建技能"
+    "createSkill": "创建技能",
+    "filterService": "NyxID 服务",
+    "filterTags": "标签",
+    "filterAuthors": "作者",
+    "filterSharedWithUsers": "分享给的用户",
+    "filterSharedWithOrgs": "分享给的组织",
+    "filterSharedByUsers": "用户分享给我",
+    "filterSharedByOrgs": "通过组织分享",
+    "noServices": "暂无系统服务。",
+    "noTags": "暂无标签。",
+    "noAuthors": "暂无作者。",
+    "notSharedWithUsers": "你还没有把任何技能分享给特定用户。",
+    "notSharedWithOrgs": "你还没有把任何技能分享给组织。",
+    "notSharedByUsers": "暂时没有人直接分享技能给你。",
+    "notSharedByOrgs": "暂时没有组织分享技能给你。",
+    "systemSkillsIntro": "系统技能是绑定到 NyxID 管理员服务的技能。平台管理员可以将任意技能绑定到管理员服务，将其发布为系统技能。",
+    "sharedWithMeIntro": "当其他人或组织向你授予某个私有技能的访问权限时，它会出现在这里。"
   },
   "mySkills": {
     "searchPlaceholder": "搜索你的技能…",
@@ -378,6 +440,8 @@
   },
   "playground": {
     "selectSkill": "选择一个技能在试验场中使用。",
+    "notFoundTitle": "未找到技能",
+    "notFoundBody": "该技能不存在，或者你没有访问权限。",
     "browseSkills": "浏览技能",
     "clearChat": "清空对话",
     "fillEnvVars": "在右侧填入所需的环境变量后开始对话。",
@@ -451,6 +515,13 @@
     "startGithub": "导入"
   },
   "guided": {
+    "validation": {
+      "nameMin": "技能名称至少需要 2 个字符",
+      "nameMax": "技能名称最多 64 个字符",
+      "nameShape": "必须以字母或数字开头，仅允许小写字母、数字和短横线",
+      "descMin": "描述至少需要 10 个字符",
+      "contentMin": "正文内容至少需要 50 个字符"
+    },
     "backToModes": "返回模式选择",
     "header": "创建技能",
     "headerDesc": "按下方步骤创建新技能",
@@ -513,7 +584,10 @@
     "previewTitle": "检查并创建",
     "dropHint": "拖拽文件到此处或点击选择",
     "noFiles": "（暂无文件）",
-    "remove": "移除"
+    "remove": "移除",
+    "fileSizeHint": "单文件上限：{{max}}",
+    "fileTooLarge": "{{name}} 大小为 {{size}}，超出单文件 {{max}} 上限。",
+    "fileDuplicate": "{{name}} 在 {{folder}} 中已存在。请先移除再替换。"
   },
   "generative": {
     "backToModes": "返回模式选择",
@@ -619,7 +693,9 @@
     "awaitingTool": "等待工具授权…",
     "placeholder": "输入消息…（Enter 发送，Shift+Enter 换行）",
     "stopGeneration": "停止生成",
-    "sendMessage": "发送消息"
+    "sendMessage": "发送消息",
+    "charCount": "{{count}} / {{max}}",
+    "overLimit": "消息过长。最多 {{max}} 个字符。"
   },
   "quota": {
     "surfacePlayground": "试验场",
@@ -963,6 +1039,14 @@
     "adminUnlimitedUsageTitle": "管理员 · 无限用量",
     "quotaUsageDetails": "配额使用详情"
   },
+  "search": {
+    "placeholderKeyword": "按名称或描述搜索技能…",
+    "placeholderSemantic": "描述你想找什么…",
+    "toggleToKeyword": "切换到关键词搜索",
+    "toggleToSemantic": "切换到语义搜索",
+    "modeKeyword": "关键词",
+    "modeSemantic": "语义"
+  },
   "skillComponents": {
     "generateModal": {
       "title": "生成技能",
@@ -970,7 +1054,10 @@
       "add": "添加"
     },
     "card": {
-      "linkedToGithub": "已关联到 GitHub"
+      "linkedToGithub": "已关联到 GitHub",
+      "viaOrganization": "通过组织共享",
+      "viaOrganizationNamed": "通过 {{org}} 共享",
+      "sharedBy": "由 {{name}} 共享"
     },
     "grid": {
       "emptyTitle": "未找到技能",
@@ -1537,7 +1624,9 @@
       "unrecognizedDirs": "存在未识别目录：{{dirs}}。仅允许 scripts/、references/、assets/。",
       "frontmatterUnparseable": "无法从 SKILL.md frontmatter 解析元数据。请检查并修复 YAML frontmatter 块。",
       "onlyZipAccepted": "仅接受 .zip 文件。",
-      "fileTooLarge": "文件过大（{{size}}）。"
+      "fileTooLarge": "文件过大（{{size}}）。",
+      "unsafePath": "ZIP 条目路径不安全：'{{path}}'。路径不允许包含 '..'、前导斜杠、反斜杠或盘符前缀。",
+      "uncompressedTooLarge": "ZIP 解压后达到 {{actual}} 字节，超过限制 {{max}} 字节。"
     },
     "frontmatter": {
       "panelTitle": "Frontmatter 校验错误",
@@ -1548,6 +1637,12 @@
       "envVarFormat": "环境变量名必须为 UPPER_SNAKE_CASE",
       "nameFormat": "名称必须以字母或数字开头，仅允许小写字母、数字和连字符",
       "versionFormat": "版本必须为 `<主版本>.<次版本>` 格式，例如 `1.0`（非负整数，不含前导零，不含修订位）",
+      "versionInvalidType": "version 必须为带引号的字符串——在 SKILL.md 中写成 `version: \"0.1\"`，不要写成 `version: 0.1`（不带引号时 YAML 会解析为数字，末尾的 0 会被截掉）。",
+      "tagInvalidType": "tag 列表项必须是非空的小写字符串，可包含连字符，例如 `tag: [my-tag]`——YAML 中空的 `- ` 行会解析为 `null`，不是有效的标签。",
+      "envVarInvalidType": "runtime-env-var 列表项必须是非空的 UPPER_SNAKE_CASE 字符串，例如 `runtime-env-var: [OPENAI_API_KEY]`——YAML 中空的 `- ` 行会解析为 `null`。",
+      "toolInvalidType": "tool-list 列表项必须是非空字符串，例如 `tool-list: [Bash, Read]`——YAML 中空的 `- ` 行会解析为 `null`。",
+      "runtimeInvalidType": "runtime 列表项必须是非空字符串，例如 `runtime: [python]`——YAML 中空的 `- ` 行会解析为 `null`。",
+      "dependencyInvalidType": "runtime-dependency 列表项必须是非空字符串，例如 `runtime-dependency: [requests==2.31]`——YAML 中空的 `- ` 行会解析为 `null`。",
       "runtimeRequiredForCategory": "类别为 '{{category}}' 时必须填写 runtime",
       "runtimeForbiddenForCategory": "类别为 '{{category}}' 时不得填写 runtime",
       "toolListRequiredForCategory": "类别为 '{{category}}' 时必须填写 tool-list",
diff --git a/ornn-web/src/lib/analytics.ts b/ornn-web/src/lib/analytics.ts
index d5fdfae7..9b1e74f8 100644
--- a/ornn-web/src/lib/analytics.ts
+++ b/ornn-web/src/lib/analytics.ts
@@ -23,15 +23,9 @@
 import posthog from "posthog-js";
 import { config } from "@/config";
 import { hasConsent, onConsentChange } from "./cookieConsent";
+import { createLogger } from "./logger";
 
-const logger = {
-  info: (msg: string, data?: Record<string, unknown>) =>
-    console.log(`[analytics] ${msg}`, data ?? ""),
-  warn: (msg: string, data?: Record<string, unknown>) =>
-    console.warn(`[analytics] ${msg}`, data ?? ""),
-  error: (msg: string, data?: Record<string, unknown>) =>
-    console.error(`[analytics] ${msg}`, data ?? ""),
-};
+const logger = createLogger("analytics");
 
 /**
  * Strongly-typed event names. Matches the spec in #252 — every call site
@@ -63,10 +57,11 @@ export interface IdentifyTraits {
 
 interface BufferedCall {
   kind: "track" | "identify" | "reset";
-  event?: AnalyticsEvent;
-  properties?: Record<string, unknown>;
-  userId?: string;
-  traits?: IdentifyTraits;
+  // exactOptionalPropertyTypes (#657)
+  event?: AnalyticsEvent | undefined;
+  properties?: Record<string, unknown> | undefined;
+  userId?: string | undefined;
+  traits?: IdentifyTraits | undefined;
 }
 
 let initialized = false;
diff --git a/ornn-web/src/lib/buildTrySkillPrompt.test.ts b/ornn-web/src/lib/buildTrySkillPrompt.test.ts
index 15000769..ae4edf72 100644
--- a/ornn-web/src/lib/buildTrySkillPrompt.test.ts
+++ b/ornn-web/src/lib/buildTrySkillPrompt.test.ts
@@ -157,4 +157,55 @@ describe("buildTrySkillPrompt", () => {
     expect(out).toContain(`Ornn URL: ${ORIGIN}/skills/${GUID}`);
     expect(out).not.toContain("https://ornn.chrono-ai.fun///");
   });
+
+  describe("version pinning (#639)", () => {
+    test("pins all three fetch surfaces to ?version=<v> when version is provided", () => {
+      const out = buildTrySkillPrompt({
+        guid: GUID,
+        name: "s",
+        description: "d",
+        metadata: {},
+        ornnOrigin: ORIGIN,
+        version: "0.2",
+      });
+      // Header acknowledges the pin so the user/agent sees it.
+      expect(out).toContain("# Install Ornn skill: s @ 0.2");
+      expect(out).toMatch(/Pinned to version `0.2`/);
+      // NyxID CLI option uses --query.
+      expect(out).toContain(
+        `nyxid proxy request ornn-api /api/v1/skills/${GUID}/json --query version=0.2`,
+      );
+      // Direct HTTPS curl URL pins via ?version=.
+      expect(out).toContain(`${ORIGIN}/api/v1/skills/${GUID}/json?version=0.2`);
+      // Ornn URL footer also points at the same version.
+      expect(out).toContain(`Ornn URL: ${ORIGIN}/skills/${GUID}?version=0.2`);
+    });
+
+    test("absent version → no pin header, no ?version=", () => {
+      const out = buildTrySkillPrompt({
+        guid: GUID,
+        name: "s",
+        description: "d",
+        metadata: {},
+        ornnOrigin: ORIGIN,
+      });
+      expect(out).not.toMatch(/Pinned to version/);
+      expect(out).not.toContain("?version=");
+      expect(out).not.toContain("--query version=");
+    });
+
+    test("URL-encodes the version (defensive — server only accepts <major>.<minor> but be safe)", () => {
+      const out = buildTrySkillPrompt({
+        guid: GUID,
+        name: "s",
+        description: "d",
+        metadata: {},
+        ornnOrigin: ORIGIN,
+        version: "stable",
+      });
+      // Plain dist-tag passes through unchanged.
+      expect(out).toContain("?version=stable");
+      expect(out).toContain("# Install Ornn skill: s @ stable");
+    });
+  });
 });
diff --git a/ornn-web/src/lib/buildTrySkillPrompt.ts b/ornn-web/src/lib/buildTrySkillPrompt.ts
index 15a1a997..6c5ab177 100644
--- a/ornn-web/src/lib/buildTrySkillPrompt.ts
+++ b/ornn-web/src/lib/buildTrySkillPrompt.ts
@@ -47,6 +47,18 @@ export interface BuildTrySkillPromptInput {
   metadata: TrySkillPromptMetadata | Record<string, unknown>;
   /** e.g. `window.location.origin` passed in by the caller. */
   ornnOrigin: string;
+  /**
+   * Version the user was viewing when they hit Install (#639). When
+   * provided, the pull URLs pin to `?version=<X>` so the agent
+   * installs the exact version the user saw — not whatever's `latest`
+   * at install time. Also surfaces a "Installing version <X>" header
+   * line so the user/agent sees the pinning explicitly.
+   *
+   * Omit when the source is genuinely version-less (e.g. a hypothetical
+   * "always pull latest" CTA). For the install card on the skill
+   * detail page, always pass the viewed version.
+   */
+  version?: string;
 }
 
 const NONE = "none";
@@ -88,7 +100,7 @@ function renderToolList(tools: TrySkillPromptTool[]): string {
 }
 
 export function buildTrySkillPrompt(input: BuildTrySkillPromptInput): string {
-  const { guid, name, description, metadata, ornnOrigin } = input;
+  const { guid, name, description, metadata, ornnOrigin, version } = input;
   const category = asString((metadata as { category?: unknown }).category) ?? "plain";
   const runtimes = readRuntimes(metadata);
   const tools = readTools(metadata);
@@ -99,13 +111,27 @@ export function buildTrySkillPrompt(input: BuildTrySkillPromptInput): string {
   const toolLine = renderToolList(tools);
 
   const origin = ornnOrigin.replace(/\/+$/, "");
-  const skillUrl = `${origin}/skills/${guid}`;
-  const apiUrl = `${origin}/api/v1/skills/${guid}/json`;
+  // #639 — when the caller knows which version was being viewed, pin
+  // the URLs and the per-run NyxID command. Without this, the agent
+  // silently pulls `latest` at install time, which can be different
+  // from what the user saw on the page.
+  const versionQuery = version ? `?version=${encodeURIComponent(version)}` : "";
+  const versionParam = version ? ` --query version=${version}` : "";
+  const skillUrl = `${origin}/skills/${guid}${versionQuery}`;
+  const apiUrl = `${origin}/api/v1/skills/${guid}/json${versionQuery}`;
 
   return [
-    `# Install Ornn skill: ${name}`,
+    `# Install Ornn skill: ${name}${version ? ` @ ${version}` : ""}`,
     "",
     `> ${description}`,
+    ...(version
+      ? [
+          "",
+          `**Pinned to version \`${version}\`** — both fetch commands below carry`,
+          "`?version=…` so the agent installs the exact version that was open in",
+          "the browser, not whatever's currently `latest`.",
+        ]
+      : []),
     "",
     "You're being given an Ornn skill — a packaged AI capability",
     "(`SKILL.md` prompt + optional scripts + metadata). Follow the steps",
@@ -120,7 +146,7 @@ export function buildTrySkillPrompt(input: BuildTrySkillPromptInput): string {
     "",
     "**Option A — via NyxID CLI** (preferred if `nyxid` is installed and you've run `nyxid login`):",
     "```",
-    `nyxid proxy request ornn-api /api/v1/skills/${guid}/json --output json`,
+    `nyxid proxy request ornn-api /api/v1/skills/${guid}/json${versionParam} --output json`,
     "```",
     "",
     "**Option B — direct HTTPS** (if you already have a NyxID bearer token):",
diff --git a/ornn-web/src/lib/docsContent.ts b/ornn-web/src/lib/docsContent.ts
index d6b953a3..be652fa6 100644
--- a/ornn-web/src/lib/docsContent.ts
+++ b/ornn-web/src/lib/docsContent.ts
@@ -106,8 +106,10 @@ function parseReleaseFrontmatter(content: string): ParsedRelease | null {
   const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
   if (!match) return null;
 
-  const frontmatter = match[1];
-  const body = match[2].trim();
+  // Regex has two capture groups; both are guaranteed present on
+  // match. `!` is safe under noUncheckedIndexedAccess (#450).
+  const frontmatter = match[1]!;
+  const body = match[2]!.trim();
 
   const versionMatch = frontmatter.match(/^version:\s*(.+)$/m);
   const dateMatch = frontmatter.match(/^date:\s*(.+)$/m);
@@ -117,8 +119,8 @@ function parseReleaseFrontmatter(content: string): ParsedRelease | null {
   if (!versionMatch || !dateMatch) return null;
 
   return {
-    version: versionMatch[1].trim(),
-    date: dateMatch[1].trim(),
+    version: versionMatch[1]!.trim(),
+    date: dateMatch[1]!.trim(),
     title: {
       en: enTitleMatch?.[1]?.trim() ?? "",
       zh: zhTitleMatch?.[1]?.trim() ?? "",
diff --git a/ornn-web/src/lib/logger.ts b/ornn-web/src/lib/logger.ts
new file mode 100644
index 00000000..b90cff1a
--- /dev/null
+++ b/ornn-web/src/lib/logger.ts
@@ -0,0 +1,44 @@
+/**
+ * Frontend logger (#584).
+ *
+ * In **development** (`import.meta.env.MODE !== "production"`) every
+ * level forwards to the corresponding `console` method so debugging
+ * still works as before.
+ *
+ * In **production** all levels are no-ops. Auth lifecycle events,
+ * analytics ticks, and apiClient errors previously leaked token
+ * metadata (refresh timing, token expiry, auth user ids) to browser
+ * devtools where it persisted across the session.
+ *
+ * `error` is the only level that always logs in dev; in prod even
+ * errors are dropped — the right place for production error reporting
+ * is a real sink (Sentry-style) wired in separately, not browser
+ * devtools.
+ *
+ * Tags are required so the module of origin is visible in dev logs.
+ *
+ * @module lib/logger
+ */
+
+const IS_DEV = import.meta.env.MODE !== "production";
+
+export interface ScopedLogger {
+  info: (msg: string, data?: unknown) => void;
+  warn: (msg: string, data?: unknown) => void;
+  error: (msg: string, data?: unknown) => void;
+  debug: (msg: string, data?: unknown) => void;
+}
+
+export function createLogger(tag: string): ScopedLogger {
+  const prefix = `[${tag}]`;
+  if (!IS_DEV) {
+    const noop = () => {};
+    return { info: noop, warn: noop, error: noop, debug: noop };
+  }
+  return {
+    info: (msg, data) => console.log(`${prefix} ${msg}`, data ?? ""),
+    warn: (msg, data) => console.warn(`${prefix} ${msg}`, data ?? ""),
+    error: (msg, data) => console.error(`${prefix} ${msg}`, data ?? ""),
+    debug: (msg, data) => console.debug(`${prefix} ${msg}`, data ?? ""),
+  };
+}
diff --git a/ornn-web/src/pages/DocsPage.tsx b/ornn-web/src/pages/DocsPage.tsx
index 6cdd7d9d..cf89b9e3 100644
--- a/ornn-web/src/pages/DocsPage.tsx
+++ b/ornn-web/src/pages/DocsPage.tsx
@@ -10,17 +10,19 @@ import { useSearchParams } from "react-router-dom";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
 import rehypeHighlight from "rehype-highlight";
-import mermaid from "mermaid";
 import { PageTransition } from "@/components/layout/PageTransition";
 import { useTranslation } from "react-i18next";
-import { useThemeStore } from "@/stores/themeStore";
 import {
-  getDocsTree,
-  getDocContent,
-  getReleases,
-  getRelease,
-  type DocSection,
-} from "@/lib/docsContent";
+  markdownComponents,
+  slugify,
+} from "@/components/docs/DocsMarkdownComponents";
+import {
+  ReleaseAccordion,
+  VersionBadge,
+} from "@/components/docs/DocsReleaseAccordion";
+import { DocsSidebar } from "@/components/docs/DocsSidebar";
+import { DocsTableOfContents } from "@/components/docs/DocsTableOfContents";
+import { getDocsTree, getDocContent } from "@/lib/docsContent";
 
 /* ──────────────── Types ──────────────── */
 
@@ -32,31 +34,6 @@ interface TocItem {
   level: number;
 }
 
-/* ──────────────── Chevron icon ──────────────── */
-
-function ChevronIcon({ open, className }: { open: boolean; className?: string }) {
-  return (
-    <svg
-      className={`${className ?? "h-4 w-4"} transition-transform duration-200 ${open ? "rotate-90" : ""}`}
-      fill="none"
-      viewBox="0 0 24 24"
-      stroke="currentColor"
-    >
-      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
-    </svg>
-  );
-}
-
-/* ──────────────── Heading slug helper ──────────────── */
-
-function slugify(text: string): string {
-  return text
-    .toLowerCase()
-    .replace(/[^\w\s\u4e00-\u9fff-]/g, "")
-    .replace(/\s+/g, "-")
-    .replace(/-+/g, "-")
-    .replace(/^-|-$/g, "");
-}
 
 /* ──────────────── Extract TOC from markdown ──────────────── */
 
@@ -74,546 +51,17 @@ function extractToc(md: string): TocItem[] {
 
     const match = /^(#{1,4})\s+(.+)$/.exec(line);
     if (match) {
-      const level = match[1].length;
-      const text = match[2].replace(/\*\*(.+?)\*\*/g, "$1").replace(/`(.+?)`/g, "$1");
+      // Both capture groups are always present on match. `!` is safe
+      // under noUncheckedIndexedAccess (#450).
+      const level = match[1]!.length;
+      const text = match[2]!.replace(/\*\*(.+?)\*\*/g, "$1").replace(/`(.+?)`/g, "$1");
       items.push({ id: slugify(text), text, level });
     }
   }
   return items;
 }
 
-/* ──────────────── Release Accordion ──────────────── */
-
-function ReleaseAccordion({ lang }: { lang: Lang }) {
-  const releases = useMemo(() => getReleases(lang), [lang]);
-  const [expandedVersion, setExpandedVersion] = useState<string | null>(
-    () => releases[0]?.version ?? null,
-  );
-  const { t } = useTranslation();
-
-  const expandedContent = useMemo(
-    () => (expandedVersion ? getRelease(expandedVersion, lang)?.content ?? null : null),
-    [expandedVersion, lang],
-  );
-
-  const handleToggle = (version: string) => {
-    setExpandedVersion((prev) => (prev === version ? null : version));
-  };
-
-  if (releases.length === 0) return null;
-
-  return (
-    <div className="my-8">
-      <h2 id={slugify(lang === "zh" ? "已发布版本" : "released-versions")} className="font-display text-2xl font-bold text-accent mb-4">
-        {lang === "zh" ? "已发布版本" : "Released Versions"}
-      </h2>
-      <div className="space-y-2">
-        {releases.map((release, idx) => {
-          const isOpen = expandedVersion === release.version;
-          const isLatest = idx === 0;
-          return (
-            <div
-              key={release.version}
-              className="rounded border border-accent/20 overflow-hidden transition-colors hover:border-accent/40"
-            >
-              <button
-                type="button"
-                onClick={() => handleToggle(release.version)}
-                className="flex w-full items-center gap-3 px-5 py-4 text-left cursor-pointer transition-colors hover:bg-accent/5"
-              >
-                <ChevronIcon open={isOpen} className="h-4 w-4 text-meta shrink-0" />
-                <div className="flex-1 min-w-0">
-                  <span className="font-display text-base font-semibold text-strong">
-                    v{release.version}
-                  </span>
-                  <span className="font-text text-sm text-meta ml-2">
-                    — {release.title}
-                  </span>
-                  {isLatest && (
-                    <span className="ml-2 inline-block px-2 py-0.5 rounded-sm text-[10px] font-mono uppercase tracking-[0.12em] bg-accent/10 text-accent border border-accent/40">
-                      {lang === "zh" ? "当前版本" : "Current"}
-                    </span>
-                  )}
-                </div>
-                <span className="font-mono text-xs text-meta shrink-0">{release.date}</span>
-              </button>
-              {isOpen && (
-                <div className="px-5 pb-4 border-t border-accent/10">
-                  {expandedContent ? (
-                    <div className="markdown-body pt-3">
-                      <ReactMarkdown remarkPlugins={[remarkGfm]} rehypePlugins={[rehypeHighlight]}>
-                        {expandedContent}
-                      </ReactMarkdown>
-                    </div>
-                  ) : (
-                    <p className="py-4 text-meta text-sm">{t("docs.loadFailed")}</p>
-                  )}
-                </div>
-              )}
-            </div>
-          );
-        })}
-      </div>
-    </div>
-  );
-}
-
-/* ──────────────── Version Badge ──────────────── */
-
-function VersionBadge() {
-  const releasesUrl = "https://github.com/ChronoAIProject/Ornn/releases";
-  return (
-    <div className="my-6 inline-flex flex-wrap items-center gap-3 rounded border border-accent/20 bg-elevated px-4 py-2">
-      <span className="font-mono text-[10px] uppercase tracking-[0.14em] text-meta">
-        Current version
-      </span>
-      <span className="font-mono text-base text-accent">v{__APP_VERSION__}</span>
-      <span className="text-meta">·</span>
-      <a
-        href={releasesUrl}
-        target="_blank"
-        rel="noreferrer"
-        className="font-text text-sm text-meta transition-colors hover:text-strong"
-      >
-        Release history on GitHub →
-      </a>
-    </div>
-  );
-}
-
-/* ──────────────── Mermaid theme configs ──────────────── */
-
-const MERMAID_DARK = {
-  startOnLoad: false,
-  theme: "dark" as const,
-  themeVariables: {
-    darkMode: true,
-    primaryColor: "#FF6B00",
-    primaryTextColor: "#e8e8e8",
-    primaryBorderColor: "#FF6B00",
-    lineColor: "#FF8C38",
-    secondaryColor: "#1e1e1e",
-    tertiaryColor: "#131313",
-    background: "#0a0a0f",
-    mainBkg: "#1e1e1e",
-    nodeBorder: "#FF6B00",
-    clusterBkg: "#131313",
-    clusterBorder: "#FF6B0044",
-    titleColor: "#FF6B00",
-    edgeLabelBackground: "#0a0a0f",
-    noteTextColor: "#e8e8e8",
-    noteBkgColor: "#1e1e1e",
-    noteBorderColor: "#FF6B0044",
-    actorTextColor: "#e8e8e8",
-    actorBkg: "#1e1e1e",
-    actorBorder: "#FF6B00",
-    signalColor: "#FF8C38",
-    signalTextColor: "#e8e8e8",
-    labelTextColor: "#e8e8e8",
-    loopTextColor: "#e8e8e8",
-  },
-  fontFamily: "'JetBrains Mono', monospace",
-  fontSize: 13,
-};
-
-const MERMAID_LIGHT = {
-  startOnLoad: false,
-  theme: "base" as const,
-  themeVariables: {
-    darkMode: false,
-    primaryColor: "#d45a00",
-    primaryTextColor: "#2d2d2d",
-    primaryBorderColor: "#d45a00",
-    lineColor: "#c06000",
-    secondaryColor: "#f3f3f5",
-    tertiaryColor: "#ffffff",
-    background: "#fafafa",
-    mainBkg: "#fff5ee",
-    nodeBorder: "#d45a00",
-    clusterBkg: "#fdf6f0",
-    clusterBorder: "#d45a0044",
-    titleColor: "#b34a00",
-    edgeLabelBackground: "#fafafa",
-    noteTextColor: "#2d2d2d",
-    noteBkgColor: "#fff5ee",
-    noteBorderColor: "#d45a0044",
-    actorTextColor: "#2d2d2d",
-    actorBkg: "#fff5ee",
-    actorBorder: "#d45a00",
-    signalColor: "#c06000",
-    signalTextColor: "#2d2d2d",
-    labelTextColor: "#2d2d2d",
-    loopTextColor: "#2d2d2d",
-  },
-  fontFamily: "'JetBrains Mono', monospace",
-  fontSize: 13,
-};
-
-function getMermaidConfig(theme: "dark" | "light") {
-  return theme === "dark" ? MERMAID_DARK : MERMAID_LIGHT;
-}
-
-// Initial init with current theme
-mermaid.initialize(getMermaidConfig(useThemeStore.getState().theme));
-
-/* ──────────────── Mermaid lightbox (zoom + pan) ──────────────── */
-
-function MermaidLightbox({ svg, onClose }: { svg: string; onClose: () => void }) {
-  const viewportRef = useRef<HTMLDivElement>(null);
-  const contentRef = useRef<HTMLDivElement>(null);
-  const [scale, setScale] = useState(1);
-  const [translate, setTranslate] = useState({ x: 0, y: 0 });
-  const dragRef = useRef({ dragging: false, startX: 0, startY: 0, originX: 0, originY: 0 });
-
-  // Zoom with scroll wheel
-  useEffect(() => {
-    const el = viewportRef.current;
-    if (!el) return;
-    const handleWheel = (e: WheelEvent) => {
-      e.preventDefault();
-      const delta = e.deltaY > 0 ? -0.1 : 0.1;
-      setScale((s) => Math.min(Math.max(0.2, s + delta), 5));
-    };
-    el.addEventListener("wheel", handleWheel, { passive: false });
-    return () => el.removeEventListener("wheel", handleWheel);
-  }, []);
-
-  // Close on Escape
-  useEffect(() => {
-    const handleKey = (e: KeyboardEvent) => { if (e.key === "Escape") onClose(); };
-    window.addEventListener("keydown", handleKey);
-    return () => window.removeEventListener("keydown", handleKey);
-  }, [onClose]);
-
-  const handlePointerDown = (e: React.PointerEvent) => {
-    if (e.target === viewportRef.current) { onClose(); return; }
-    dragRef.current = { dragging: true, startX: e.clientX, startY: e.clientY, originX: translate.x, originY: translate.y };
-    (e.target as HTMLElement).setPointerCapture?.(e.pointerId);
-  };
-
-  const handlePointerMove = (e: React.PointerEvent) => {
-    if (!dragRef.current.dragging) return;
-    const dx = e.clientX - dragRef.current.startX;
-    const dy = e.clientY - dragRef.current.startY;
-    setTranslate({ x: dragRef.current.originX + dx, y: dragRef.current.originY + dy });
-  };
-
-  const handlePointerUp = () => { dragRef.current.dragging = false; };
-
-  const handleReset = () => { setScale(1); setTranslate({ x: 0, y: 0 }); };
-
-  return (
-    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/70 backdrop-blur-sm">
-      {/* Toolbar */}
-      <div className="absolute top-4 right-4 z-10 flex items-center gap-2">
-        <button type="button" onClick={() => setScale((s) => Math.min(s + 0.25, 5))} className="rounded bg-elevated px-3 py-1.5 font-mono text-sm text-strong hover:bg-accent/20 transition-colors cursor-pointer">+</button>
-        <span className="rounded bg-elevated px-3 py-1.5 font-mono text-sm text-meta min-w-[4rem] text-center">{Math.round(scale * 100)}%</span>
-        <button type="button" onClick={() => setScale((s) => Math.max(s - 0.25, 0.2))} className="rounded bg-elevated px-3 py-1.5 font-mono text-sm text-strong hover:bg-accent/20 transition-colors cursor-pointer">−</button>
-        <button type="button" onClick={handleReset} className="rounded bg-elevated px-3 py-1.5 font-mono text-sm text-strong hover:bg-accent/20 transition-colors cursor-pointer">Reset</button>
-        <button type="button" onClick={onClose} className="rounded bg-elevated px-3 py-1.5 font-mono text-sm text-strong hover:bg-accent/20 transition-colors cursor-pointer">✕</button>
-      </div>
-      {/* Viewport */}
-      <div
-        ref={viewportRef}
-        className="absolute inset-0 cursor-grab active:cursor-grabbing overflow-hidden"
-        onPointerDown={handlePointerDown}
-        onPointerMove={handlePointerMove}
-        onPointerUp={handlePointerUp}
-      >
-        <div
-          ref={contentRef}
-          className="absolute left-1/2 top-1/2 mermaid-container [&_svg]:max-w-none"
-          style={{ transform: `translate(-50%, -50%) translate(${translate.x}px, ${translate.y}px) scale(${scale})`, transformOrigin: "center center" }}
-          dangerouslySetInnerHTML={{ __html: svg }}
-        />
-      </div>
-    </div>
-  );
-}
-
-/* ──────────────── Mermaid block component ──────────────── */
-
-let mermaidCounter = 0;
-
-function MermaidBlock({ chart }: { chart: string }) {
-  const containerRef = useRef<HTMLDivElement>(null);
-  const [svg, setSvg] = useState<string>("");
-  const [lightboxOpen, setLightboxOpen] = useState(false);
-  const theme = useThemeStore((s) => s.theme);
-
-  useEffect(() => {
-    let cancelled = false;
-    const id = `mermaid-${++mermaidCounter}`;
-
-    // Re-initialize mermaid with current theme before rendering
-    mermaid.initialize(getMermaidConfig(theme));
-
-    mermaid.render(id, chart).then(({ svg: rendered }) => {
-      if (!cancelled) setSvg(rendered);
-    }).catch((err) => {
-      if (!cancelled) setSvg(`<pre style="color:#ff003c">Mermaid error: ${err.message}</pre>`);
-    });
-
-    return () => { cancelled = true; };
-  }, [chart, theme]);
-
-  return (
-    <>
-      <div
-        ref={containerRef}
-        className="mermaid-container group relative my-4 overflow-x-auto rounded border border-accent/10 bg-page p-4 cursor-pointer [&_svg]:mx-auto [&_svg]:max-w-full"
-        onClick={() => setLightboxOpen(true)}
-        dangerouslySetInnerHTML={{ __html: svg }}
-      />
-      {lightboxOpen && <MermaidLightbox svg={svg} onClose={() => setLightboxOpen(false)} />}
-    </>
-  );
-}
-
-/* ──────────────── Custom code component for react-markdown ──────────────── */
-
-function CopyButton({ text }: { text: string }) {
-  const [copied, setCopied] = useState(false);
-
-  const handleCopy = async () => {
-    try {
-      await navigator.clipboard.writeText(text);
-      setCopied(true);
-      setTimeout(() => setCopied(false), 2000);
-    } catch {
-      /* clipboard may not be available */
-    }
-  };
-
-  return (
-    <button
-      type="button"
-      onClick={handleCopy}
-      className="absolute top-2 right-2 z-10 px-2 py-1 rounded text-xs font-mono transition-all cursor-pointer border border-accent/30 bg-page/80 text-meta hover:text-accent hover:border-accent/60"
-    >
-      {copied ? "Copied!" : "Copy"}
-    </button>
-  );
-}
-
-/** Wraps <pre> blocks with a relative container and copy button outside the scrollable area */
-function PreBlock({ children, ...props }: React.HTMLAttributes<HTMLPreElement>) {
-  const codeText = useRef("");
-
-  // Extract text content from children (the <code> element inside <pre>)
-  const extractText = (node: React.ReactNode): string => {
-    if (typeof node === "string") return node;
-    if (typeof node === "number") return String(node);
-    if (Array.isArray(node)) return node.map(extractText).join("");
-    if (node && typeof node === "object" && "props" in node) {
-      const el = node as { props?: { children?: React.ReactNode } };
-      return extractText(el.props?.children);
-    }
-    return "";
-  };
-
-  codeText.current = extractText(children).replace(/\n$/, "");
-
-  return (
-    <div className="relative">
-      <CopyButton text={codeText.current} />
-      <pre {...props}>{children}</pre>
-    </div>
-  );
-}
-
-function CodeBlock({
-  className,
-  children,
-  ...props
-}: React.HTMLAttributes<HTMLElement> & { children?: React.ReactNode }) {
-  const match = /language-(\w+)/.exec(className ?? "");
-  const lang = match?.[1];
-  const code = String(children).replace(/\n$/, "");
-
-  if (lang === "mermaid") {
-    return <MermaidBlock chart={code} />;
-  }
-
-  return (
-    <code className={className} {...props}>
-      {children}
-    </code>
-  );
-}
-
-/* ──────────────── Heading components that inject IDs ──────────────── */
-
-function extractTextFromChildren(children: React.ReactNode): string {
-  if (typeof children === "string") return children;
-  if (typeof children === "number") return String(children);
-  if (Array.isArray(children)) return children.map(extractTextFromChildren).join("");
-  if (children && typeof children === "object" && "props" in children) {
-    const el = children as { props?: { children?: React.ReactNode } };
-    return extractTextFromChildren(el.props?.children);
-  }
-  return "";
-}
-
-function H1({ children, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
-  const id = slugify(extractTextFromChildren(children));
-  return <h1 id={id} {...props}>{children}</h1>;
-}
-function H2({ children, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
-  const id = slugify(extractTextFromChildren(children));
-  return <h2 id={id} {...props}>{children}</h2>;
-}
-function H3({ children, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
-  const id = slugify(extractTextFromChildren(children));
-  return <h3 id={id} {...props}>{children}</h3>;
-}
-function H4({ children, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
-  const id = slugify(extractTextFromChildren(children));
-  return <h4 id={id} {...props}>{children}</h4>;
-}
-
-const headingComponents = { h1: H1, h2: H2, h3: H3, h4: H4 };
-
-/* ──────────────── Sidebar with collapsible sections ──────────────── */
-
-function Sidebar({
-  sections,
-  activeId,
-  onSelect,
-}: {
-  sections: DocSection[];
-  activeId: string;
-  onSelect: (id: string, label: string) => void;
-}) {
-  // Initialize: expand the section that contains the active doc
-  const activeSectionId = sections.find((s) =>
-    s.children.some((c) => c.id === activeId)
-  )?.id;
-
-  const [expanded, setExpanded] = useState<Set<string>>(() => {
-    const initial = new Set<string>();
-    if (activeSectionId) initial.add(activeSectionId);
-    return initial;
-  });
-
-  // When active doc changes, ensure its section is expanded
-  useEffect(() => {
-    if (activeSectionId && !expanded.has(activeSectionId)) {
-      setExpanded((prev) => new Set(prev).add(activeSectionId));
-    }
-  }, [activeSectionId]); // eslint-disable-line react-hooks/exhaustive-deps
-
-  const toggleSection = (sectionId: string) => {
-    setExpanded((prev) => {
-      const next = new Set(prev);
-      if (next.has(sectionId)) {
-        next.delete(sectionId);
-      } else {
-        next.add(sectionId);
-      }
-      return next;
-    });
-  };
-
-  return (
-    <nav className="w-64 shrink-0 border-r border-accent/10 overflow-y-auto py-4 pr-2">
-      {sections.map((section) => {
-        const isExpanded = expanded.has(section.id);
-        return (
-          <div key={section.id} className="mb-2">
-            <button
-              type="button"
-              onClick={() => toggleSection(section.id)}
-              className="w-full flex items-center gap-2 px-3 py-2 cursor-pointer group text-left"
-            >
-              <ChevronIcon
-                open={isExpanded}
-                className="h-4 w-4 shrink-0 text-meta group-hover:text-strong transition-colors"
-              />
-              <span className="font-mono text-[11px] uppercase tracking-[0.14em] text-meta group-hover:text-strong transition-colors">
-                {section.label}
-              </span>
-            </button>
-            {isExpanded && (
-              <div className="ml-2">
-                {section.children.map((child) => {
-                  const isActive = child.id === activeId;
-                  return (
-                    <button
-                      key={child.id}
-                      type="button"
-                      onClick={() => onSelect(child.id, child.label)}
-                      className={`
-                        w-full text-left px-3 py-2 rounded-md font-text text-base transition-all duration-150 cursor-pointer
-                        ${isActive
-                          ? "text-accent bg-accent/10 border-l-2 border-accent"
-                          : "text-meta hover:text-strong hover:bg-elevated border-l-2 border-transparent"
-                        }
-                      `}
-                    >
-                      {child.label}
-                    </button>
-                  );
-                })}
-              </div>
-            )}
-          </div>
-        );
-      })}
-    </nav>
-  );
-}
-
-/* ──────────────── Table of Contents (sticky right minimap) ──────────────── */
-
-function TableOfContents({
-  items,
-  activeHeadingId,
-  onSelect,
-}: {
-  items: TocItem[];
-  activeHeadingId: string;
-  onSelect: (id: string) => void;
-}) {
-  const { t } = useTranslation();
-
-  if (items.length === 0) return null;
-
-  // Skip the h1 (doc title) — show only h2+ in TOC
-  const tocItems = items.filter((item) => item.level >= 2);
-  if (tocItems.length === 0) return null;
 
-  return (
-    <nav className="w-56 shrink-0 sticky top-0 self-start overflow-y-auto max-h-[calc(100vh-8rem)] py-4 pl-4">
-      <h4 className="font-mono text-[10px] uppercase tracking-[0.16em] text-meta px-2 py-1.5 mb-2">
-        {t("docs.onThisPage")}
-      </h4>
-      <div className="space-y-0.5 border-l border-accent/10">
-        {tocItems.map((item) => {
-          const isActive = item.id === activeHeadingId;
-          const indent = item.level === 2 ? "pl-3" : item.level === 3 ? "pl-6" : "pl-9";
-          return (
-            <button
-              key={item.id}
-              type="button"
-              onClick={() => onSelect(item.id)}
-              className={`
-                w-full text-left py-1.5 ${indent} font-text text-base leading-snug transition-colors duration-150 cursor-pointer truncate
-                ${isActive
-                  ? "text-accent border-l-2 border-accent -ml-px"
-                  : "text-meta hover:text-strong"
-                }
-              `}
-              title={item.text}
-            >
-              {item.text}
-            </button>
-          );
-        })}
-      </div>
-    </nav>
-  );
-}
 
 /* ──────────────── Page component ──────────────── */
 
@@ -647,11 +95,13 @@ export function DocsPage() {
       return { displayMarkdown: markdown, frontmatter: {} as Record<string, string> };
     }
     const fm: Record<string, string> = {};
-    for (const raw of m[1].split(/\r?\n/)) {
+    // Capture group 1 is always present on match. `!` is safe under
+    // noUncheckedIndexedAccess (#450).
+    for (const raw of m[1]!.split(/\r?\n/)) {
       const kv = /^\s*([A-Za-z][\w-]*)\s*:\s*(.+?)\s*$/.exec(raw);
-      if (kv) fm[kv[1]] = kv[2].replace(/^['"]|['"]$/g, "");
+      if (kv) fm[kv[1]!] = kv[2]!.replace(/^['"]|['"]$/g, "");
     }
-    return { displayMarkdown: markdown.slice(m[0].length), frontmatter: fm };
+    return { displayMarkdown: markdown.slice(m[0]!.length), frontmatter: fm };
   }, [markdown]);
 
   // Every doc is copyable; nothing on the docs site today is paste-
@@ -730,7 +180,7 @@ export function DocsPage() {
     <PageTransition>
       <div className="flex h-full min-h-0 gap-0">
         {/* Left sidebar — collapsible doc browser */}
-        <Sidebar sections={menu?.sections ?? []} activeId={activeId} onSelect={handleSelect} />
+        <DocsSidebar sections={menu?.sections ?? []} activeId={activeId} onSelect={handleSelect} />
 
         {/* Right — doc content area with TOC minimap */}
         <div className="flex-1 min-w-0 flex min-h-0">
@@ -746,7 +196,7 @@ export function DocsPage() {
                       <ReactMarkdown
                         remarkPlugins={[remarkGfm]}
                         rehypePlugins={[rehypeHighlight]}
-                        components={{ code: CodeBlock as never, pre: PreBlock as never, ...headingComponents }}
+                        components={markdownComponents as never}
                       >
                         {before}
                       </ReactMarkdown>
@@ -754,7 +204,7 @@ export function DocsPage() {
                       <ReactMarkdown
                         remarkPlugins={[remarkGfm]}
                         rehypePlugins={[rehypeHighlight]}
-                        components={{ code: CodeBlock as never, pre: PreBlock as never, ...headingComponents }}
+                        components={markdownComponents as never}
                       >
                         {after}
                       </ReactMarkdown>
@@ -772,7 +222,7 @@ export function DocsPage() {
                       <ReactMarkdown
                         remarkPlugins={[remarkGfm]}
                         rehypePlugins={[rehypeHighlight]}
-                        components={{ code: CodeBlock as never, pre: PreBlock as never, ...headingComponents }}
+                        components={markdownComponents as never}
                       >
                         {before}
                       </ReactMarkdown>
@@ -780,7 +230,7 @@ export function DocsPage() {
                       <ReactMarkdown
                         remarkPlugins={[remarkGfm]}
                         rehypePlugins={[rehypeHighlight]}
-                        components={{ code: CodeBlock as never, pre: PreBlock as never, ...headingComponents }}
+                        components={markdownComponents as never}
                       >
                         {after}
                       </ReactMarkdown>
@@ -830,11 +280,7 @@ export function DocsPage() {
                 <ReactMarkdown
                   remarkPlugins={[remarkGfm]}
                   rehypePlugins={[rehypeHighlight]}
-                  components={{
-                    code: CodeBlock as never,
-                    pre: PreBlock as never,
-                    ...headingComponents,
-                  }}
+                  components={markdownComponents as never}
                 >
                   {displayMarkdown}
                 </ReactMarkdown>
@@ -844,7 +290,7 @@ export function DocsPage() {
 
           {/* TOC minimap — sticky right side */}
           {toc.length > 0 && (
-            <TableOfContents
+            <DocsTableOfContents
               items={toc}
               activeHeadingId={activeHeadingId}
               onSelect={handleTocClick}
diff --git a/ornn-web/src/pages/ExplorePage.tsx b/ornn-web/src/pages/ExplorePage.tsx
index 6a173999..2fe00e34 100644
--- a/ornn-web/src/pages/ExplorePage.tsx
+++ b/ornn-web/src/pages/ExplorePage.tsx
@@ -111,6 +111,12 @@ export function ExplorePage() {
   const selectedSourceUsers = parseCsvParam(searchParams.get("srcUsers"));
 
   const { query, mode } = useSearchStore();
+  // #726 — semantic search requires a query; the backend rejects an
+  // empty `q` with 400 QUERY_REQUIRED and the regular empty state
+  // ("No skills match") looks indistinguishable from a legitimate
+  // zero-result search. When the gate isn't met, render a clear
+  // validation EmptyState instead of the generic "no skills" copy.
+  const semanticGateUnmet = mode === "semantic" && !query.trim();
 
   const { data: systemData, isLoading: systemLoading } = useSystemSkills({
     query: query || undefined,
@@ -281,21 +287,35 @@ export function ExplorePage() {
             {activeLoading ? (
               <div className="grid gap-6 sm:grid-cols-2 xl:grid-cols-3 pb-4">
                 {Array.from({ length: 6 }).map((_, i) => (
+                  // Positional list — never reorders, key={i} is intentional (#451).
                   <SkeletonCard key={i} />
                 ))}
               </div>
             ) : items.length === 0 ? (
-              <EmptyState
-                title={emptyTitle(activeTab, t as (k: string, f?: string) => string)}
-                description={emptyDescription(activeTab, t as (k: string, f?: string) => string)}
-                action={
-                  activeTab === "my-skills" && isAuthenticated ? (
-                    <Button onClick={() => navigate("/skills/new")}>
-                      {t("explore.createSkill", "Create a skill")}
-                    </Button>
-                  ) : undefined
-                }
-              />
+              semanticGateUnmet ? (
+                <EmptyState
+                  title={t(
+                    "explore.semanticQueryRequiredTitle",
+                    "Enter a search description",
+                  )}
+                  description={t(
+                    "explore.semanticQueryRequiredDesc",
+                    "Semantic search needs a description of what you're looking for. Type a phrase in the search box above, or switch back to Keyword mode.",
+                  )}
+                />
+              ) : (
+                <EmptyState
+                  title={emptyTitle(activeTab, t as (k: string, f?: string) => string)}
+                  description={emptyDescription(activeTab, t as (k: string, f?: string) => string)}
+                  action={
+                    activeTab === "my-skills" && isAuthenticated ? (
+                      <Button onClick={() => navigate("/skills/new")}>
+                        {t("explore.createSkill", "Create a skill")}
+                      </Button>
+                    ) : undefined
+                  }
+                />
+              )
             ) : (
               <motion.div
                 variants={containerVariants}
@@ -325,7 +345,8 @@ export function ExplorePage() {
 
 interface TabButtonProps {
   label: string;
-  count?: number;
+  // exactOptionalPropertyTypes (#657)
+  count?: number | undefined;
   active: boolean;
   onClick: () => void;
 }
@@ -364,7 +385,8 @@ function TabButton({ label, count, active, onClick }: TabButtonProps) {
 
 interface FilterSidebarProps {
   tab: ExploreTab;
-  selectedServiceId?: string;
+  // exactOptionalPropertyTypes (#657)
+  selectedServiceId?: string | undefined;
   selectedTags: string[];
   selectedAuthors: string[];
   selectedGrantOrgs: string[];
@@ -427,7 +449,8 @@ function SystemFilters({
   selectedServiceId,
   onSetService,
 }: {
-  selectedServiceId?: string;
+  // exactOptionalPropertyTypes (#657)
+  selectedServiceId?: string | undefined;
   onSetService: (id: string | undefined) => void;
 }) {
   const { t } = useTranslation();
@@ -708,15 +731,20 @@ function emptyTitle(tab: ExploreTab, t: (key: string, fallback?: string) => stri
 }
 
 function emptyDescription(tab: ExploreTab, t: (key: string, fallback?: string) => string): string {
+  // #682 — point at the canonical i18n keys (`systemSkillsIntro` /
+  // `sharedWithMeIntro`) so both EN + ZH locales pick up the right
+  // copy. The old `systemSkillsHint` / `sharedHint` keys never
+  // existed in either locale file, so i18n was always falling back
+  // to the English literal for both languages.
   if (tab === "system")
     return t(
-      "explore.systemSkillsHint",
+      "explore.systemSkillsIntro",
       "System skills are skills tied to a NyxID admin service. Platform admins tie any skill to any admin service to publish it as a system skill.",
     );
   if (tab === "public") return t("explore.tryAdjusting", "Try adjusting your search or filters.");
   if (tab === "my-skills") return t("explore.createFirst", "Create your first skill to get started.");
   return t(
-    "explore.sharedHint",
+    "explore.sharedWithMeIntro",
     "When someone grants you access to a private skill — either directly or via an org — it shows up here.",
   );
 }
diff --git a/ornn-web/src/pages/NotificationsPage.tsx b/ornn-web/src/pages/NotificationsPage.tsx
index cd6d5fe3..372fcd9d 100644
--- a/ornn-web/src/pages/NotificationsPage.tsx
+++ b/ornn-web/src/pages/NotificationsPage.tsx
@@ -91,6 +91,14 @@ export function NotificationsPage() {
 
   return (
     <PageTransition>
+      {/*
+        Outer wrapper provides the vertical scroll surface (#723).
+        `RootLayout`'s `<main>` is `overflow-hidden`, so without this
+        the notification list is clipped once it exceeds the viewport
+        and older entries can never be reached by wheel/touch scroll.
+        Same pattern as `UploadSkillPage`.
+      */}
+      <div className="h-full overflow-y-auto">
       <div className="mx-auto w-full max-w-4xl px-6 py-10">
         <header className="mb-6 flex flex-wrap items-center justify-between gap-4">
           <div>
@@ -211,6 +219,7 @@ export function NotificationsPage() {
           </ul>
         )}
       </div>
+      </div>
 
       <NotificationDetailModal
         notification={detailNotification}
diff --git a/ornn-web/src/pages/PlaygroundPage.tsx b/ornn-web/src/pages/PlaygroundPage.tsx
index a1eecfdc..6c9fa748 100644
--- a/ornn-web/src/pages/PlaygroundPage.tsx
+++ b/ornn-web/src/pages/PlaygroundPage.tsx
@@ -18,283 +18,112 @@
  * @module pages/PlaygroundPage
  */
 
-import { useState, useRef, useEffect, useMemo, useCallback, type ComponentType } from "react";
+import { useMemo } from "react";
 import { useSearchParams, Link } from "react-router-dom";
+import { Skeleton } from "@/components/ui/Skeleton";
 import { motion, AnimatePresence } from "framer-motion";
 import { PageTransition } from "@/components/layout/PageTransition";
-import { Skeleton } from "@/components/ui/Skeleton";
-import { ChatInput, type ChatInputHandle } from "@/components/playground/ChatInput";
-import { ChatMessage } from "@/components/playground/ChatMessage";
-import { SkillPackagePreview } from "@/components/skill/SkillPackagePreview";
+import { ChatInput } from "@/components/playground/ChatInput";
 import { ModelPicker } from "@/components/models/ModelPicker";
 import { OverLimitPage } from "@/components/quota/OverLimitPage";
 import { QuotaInline } from "@/components/quota/QuotaInline";
-import { EnvIcon, PackageIcon, type IconProps } from "@/components/icons";
-import {
-  createDefaultSkillMetadata,
-  type SkillMetadata,
-} from "@/types/skillPackage";
-import type { SkillCategory } from "@/utils/constants";
-import { useSkill } from "@/hooks/useSkills";
-import { useSkillPackage } from "@/hooks/useSkillPackage";
-import { usePlaygroundChat } from "@/hooks/usePlaygroundChat";
-import { useMyQuota } from "@/hooks/useQuota";
+import { EnvIcon, PackageIcon } from "@/components/icons";
 import { useTranslation } from "react-i18next";
+import { defaultPromptStarters } from "@/components/playground/PlaygroundHelpers";
+import { PlaygroundEmptyHero } from "@/components/playground/PlaygroundEmptyHero";
+import { PlaygroundEnvDrawerBody } from "@/components/playground/PlaygroundEnvDrawerBody";
+import { PlaygroundPackageDrawerBody } from "@/components/playground/PlaygroundPackageDrawerBody";
+import {
+  PlaygroundRail,
+  type PlaygroundRailTab,
+} from "@/components/playground/PlaygroundRail";
+import { PlaygroundConversation } from "@/components/playground/PlaygroundConversation";
+import { usePlaygroundSession } from "@/hooks/usePlaygroundSession";
 
-/** Extract env var keys from skill metadata */
-function extractEnvVarKeys(metadata: Record<string, unknown> | null): string[] {
-  if (!metadata) return [];
-  const runtimes = metadata.runtimes as Array<{ envs?: Array<{ var: string }> }> | undefined;
-  if (!runtimes?.length) return [];
-  const keys: string[] = [];
-  for (const rt of runtimes) {
-    if (rt.envs) {
-      for (const env of rt.envs) {
-        if (env.var && !keys.includes(env.var)) {
-          keys.push(env.var);
-        }
-      }
-    }
-  }
-  return keys;
-}
-
-/** Check if skill is runtime-based */
-function isRuntimeBased(metadata: Record<string, unknown> | null): boolean {
-  if (!metadata) return false;
-  const category = metadata.category as string;
-  return category === "runtime-based" || category === "mixed";
-}
-
-/** Pre-token streaming indicator — three pulsing ember dots, spring-in. */
-function ThinkingBubble() {
-  const { t } = useTranslation();
-  return (
-    <motion.div
-      initial={{ opacity: 0, y: 8, scale: 0.98 }}
-      animate={{ opacity: 1, y: 0, scale: 1 }}
-      exit={{ opacity: 0, scale: 0.96 }}
-      transition={{ type: "spring", stiffness: 320, damping: 28, mass: 0.6 }}
-      className="flex justify-start"
-    >
-      <div className="rounded-2xl border border-subtle bg-card px-4 py-3">
-        <div className="flex items-center gap-1.5" aria-label={t("aria.generating")}>
-          <span className="h-1.5 w-1.5 animate-pulse rounded-full bg-accent/70" style={{ animationDelay: "0ms" }} />
-          <span className="h-1.5 w-1.5 animate-pulse rounded-full bg-accent/70" style={{ animationDelay: "150ms" }} />
-          <span className="h-1.5 w-1.5 animate-pulse rounded-full bg-accent/70" style={{ animationDelay: "300ms" }} />
-        </div>
-      </div>
-    </motion.div>
-  );
-}
-
-interface PromptStarter {
-  label: string;
-  body: string;
-}
-
-type TFunc = ReturnType<typeof import("react-i18next").useTranslation>["t"];
-
-function defaultPromptStarters(skillName: string, t: TFunc): PromptStarter[] {
-  return [
-    {
-      label: t("playground.starter1Label", "Walk me through it"),
-      body: t("playground.starter1Body", "Walk me through what `{{name}}` does and the main ways I'd use it.", {
-        name: skillName,
-      }),
-    },
-    {
-      label: t("playground.starter2Label", "Show an example"),
-      body: t("playground.starter2Body", "Give me a concrete usage example for `{{name}}` — make up sample input and run it.", {
-        name: skillName,
-      }),
-    },
-    {
-      label: t("playground.starter3Label", "List capabilities"),
-      body: t("playground.starter3Body", "List every capability `{{name}}` exposes, with a one-line description for each.", {
-        name: skillName,
-      }),
-    },
-  ];
-}
-
-type DrawerKey = "package" | "env";
 
 export function PlaygroundPage() {
   const { t } = useTranslation();
   const [searchParams] = useSearchParams();
   const skillName = searchParams.get("skill");
+  const session = usePlaygroundSession(skillName);
 
-  const { data: skill, isLoading: skillLoading } = useSkill(skillName ?? "");
-  const {
-    files: packageFiles,
-    fileContents: packageContents,
-    isLoading: packageLoading,
-  } = useSkillPackage(skill?.presignedPackageUrl);
-
-  const envVarKeys = useMemo(() => extractEnvVarKeys(skill?.metadata as Record<string, unknown> ?? null), [skill?.metadata]);
-  const needsEnvVars = useMemo(() => isRuntimeBased(skill?.metadata as Record<string, unknown> ?? null) && envVarKeys.length > 0, [skill?.metadata, envVarKeys]);
-  const [envVars, setEnvVars] = useState<Record<string, string>>({});
-
-  const allEnvVarsFilled = useMemo(() => {
-    if (!needsEnvVars) return true;
-    return envVarKeys.every((key) => envVars[key]?.trim());
-  }, [needsEnvVars, envVarKeys, envVars]);
-
-  const handleEnvVarChange = useCallback((key: string, value: string) => {
-    setEnvVars((prev) => ({ ...prev, [key]: value }));
-  }, []);
-
-  const [pickedModelId, setPickedModelId] = useState<string | null>(null);
-
-  const { data: quotaSnapshot } = useMyQuota();
-  const playgroundSnap = quotaSnapshot?.playground;
-  const isOverLimit =
-    Boolean(playgroundSnap) &&
-    !quotaSnapshot?.isAdmin &&
-    playgroundSnap!.remaining <= 0;
-
+  // Destructure for JSX readability — every name below came out of
+  // `usePlaygroundSession`; the hook is the single source of truth
+  // for queries / refs / state / handlers.
   const {
+    skill,
+    skillLoading,
+    skillError,
+    packageFiles,
+    packageContents,
+    packageLoading,
+    quotaSnapshot,
+    playgroundSnap,
+    isOverLimit,
     messages,
     isStreaming,
     toolCallStatuses,
     fileOutputs,
     error,
     currentAssistantContent,
-    sendMessage,
     abort,
     clearChat,
-  } = usePlaygroundChat();
-
-  const messagesEndRef = useRef<HTMLDivElement>(null);
-  const messagesScrollRef = useRef<HTMLDivElement>(null);
-  const chatInputRef = useRef<ChatInputHandle>(null);
-  // Tracks whether the user has manually scrolled away from the bottom.
-  // While true, we do NOT yank them back on each token flush.
-  const stickToBottomRef = useRef(true);
-
-  // Detect manual scroll-away: if the scrollbar is more than ~80px from
-  // the bottom we stop auto-scrolling. The user can return to live
-  // tailing by scrolling back to the bottom.
-  useEffect(() => {
-    const el = messagesScrollRef.current;
-    if (!el) return;
-    const onScroll = () => {
-      const distFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
-      stickToBottomRef.current = distFromBottom < 80;
-    };
-    el.addEventListener("scroll", onScroll, { passive: true });
-    return () => el.removeEventListener("scroll", onScroll);
-  }, []);
-
-  // Auto-scroll only when stick-to-bottom is on (i.e. user hasn't
-  // scrolled up). Uses `auto` (instant) instead of `smooth` during
-  // streaming because `smooth` queues animations and gets choppy with
-  // 50ms-batched token flushes.
-  useEffect(() => {
-    if (!stickToBottomRef.current) return;
-    messagesEndRef.current?.scrollIntoView({ behavior: "auto" });
-  }, [messages, currentAssistantContent]);
-
-  const handleSend = useCallback((content: string) => {
-    sendMessage(
-      content,
-      skillName ?? undefined,
-      needsEnvVars ? envVars : undefined,
-      pickedModelId ?? undefined,
-    );
-  }, [sendMessage, skillName, envVars, needsEnvVars, pickedModelId]);
-
-  const handleStarterClick = useCallback((body: string) => {
-    chatInputRef.current?.setValue(body);
-  }, []);
-
-  // ── Drawer state ──
-  // `hover` = mouse is on a rail tab or inside the drawer (auto-close
-  // when it leaves). `pinned` = clicked open; stays until clicked
-  // again, click outside, or Esc.
-  const [hoverDrawer, setHoverDrawer] = useState<DrawerKey | null>(null);
-  const [pinnedDrawer, setPinnedDrawer] = useState<DrawerKey | null>(null);
-  const closeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  const openHover = useCallback((key: DrawerKey) => {
-    if (closeTimerRef.current) {
-      clearTimeout(closeTimerRef.current);
-      closeTimerRef.current = null;
-    }
-    setHoverDrawer(key);
-  }, []);
-  const scheduleHoverClose = useCallback(() => {
-    if (closeTimerRef.current) clearTimeout(closeTimerRef.current);
-    closeTimerRef.current = setTimeout(() => {
-      setHoverDrawer(null);
-      closeTimerRef.current = null;
-    }, 220);
-  }, []);
-  const togglePin = useCallback((key: DrawerKey) => {
-    setPinnedDrawer((cur) => (cur === key ? null : key));
-    setHoverDrawer(null);
-  }, []);
-
-  // Close pinned drawer on Esc
-  useEffect(() => {
-    if (!pinnedDrawer) return;
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key === "Escape") setPinnedDrawer(null);
-    };
-    window.addEventListener("keydown", onKey);
-    return () => window.removeEventListener("keydown", onKey);
-  }, [pinnedDrawer]);
-
-  // Auto-pin Env when env vars are missing — the user MUST fill them
-  // before chatting, so make it obvious without forcing them to discover
-  // the drawer hint.
-  const envIncomplete = needsEnvVars && !allEnvVarsFilled;
-  useEffect(() => {
-    if (envIncomplete) setPinnedDrawer("env");
-  }, [envIncomplete]);
-
-  // ── Per-skill session lifecycle ──
-  // Each Playground visit (and each switch between skills) starts a
-  // fresh chat. Without this, the Zustand store carries stale messages
-  // across navigation — confusing UX and breaking any per-session
-  // analytics that assume a session begins on mount.
-  useEffect(() => {
-    clearChat();
-    setEnvVars({});
-    stickToBottomRef.current = true;
-    return () => {
-      clearChat();
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [skillName]);
-
-  const activeDrawer = pinnedDrawer ?? hoverDrawer;
+    messagesEndRef,
+    messagesScrollRef,
+    chatInputRef,
+    envVarKeys,
+    needsEnvVars,
+    envVars,
+    allEnvVarsFilled,
+    envIncomplete,
+    handleEnvVarChange,
+    handleSend,
+    handleStarterClick,
+    setPickedModelId,
+    pinnedDrawer,
+    setPinnedDrawer,
+    setHoverDrawer,
+    activeDrawer,
+    openHover,
+    scheduleHoverClose,
+    togglePin,
+    previewMetadata,
+  } = session;
+
+  // Memoized: the suggestion-chip set depends only on the skill name
+  // (i18n-substituted into the prompt body). Recomputing on every render
+  // works fine but caching is cheap and lets PlaygroundEmptyHero's
+  // reference-equality short-circuit do its job.
+  const starters = useMemo(
+    () => (skillName ? defaultPromptStarters(skillName, t) : []),
+    [skillName, t],
+  );
 
-  const skillCategory = (skill?.metadata as Record<string, unknown> | null)?.category as string | undefined;
+  const conversationActive = messages.length > 0 || isStreaming || !!currentAssistantContent;
 
-  // Synthesise a SkillMetadata-shaped object from the registry skill record
-  // so SkillPackagePreview can render the same flat identity strip as the
-  // generative page. The preview only reads name / description / category /
-  // tag, so we don't need to faithfully reproduce the rest of the shape —
-  // `createDefaultSkillMetadata` fills the unused fields with safe defaults.
-  // Declared above the early-return guards so the hook order is stable.
-  const previewMetadata = useMemo<SkillMetadata | null>(() => {
-    if (!skill) return null;
-    return createDefaultSkillMetadata({
-      name: skill.name,
-      description: skill.description ?? "",
-      version: skill.version,
-      metadata: {
-        category: (skillCategory as SkillCategory) ?? "plain",
-        runtime: [],
-        runtimeDependency: [],
-        runtimeEnvVar: [],
-        toolList: [],
-        tag: skill.tags ?? [],
-      },
-    });
-  }, [skill, skillCategory]);
+  // ── Rail tabs ───────────────────────────────────────────────────────
+  // Inline because the tab list flips with `needsEnvVars` — pulling it
+  // into the hook would force a re-build of PlaygroundRailTab[] in every
+  // hook consumer that didn't care.
+  const railTabs: PlaygroundRailTab[] = [
+    ...(needsEnvVars
+      ? [
+          {
+            key: "env" as const,
+            ariaLabel: t("aria.playgroundEnvDrawer"),
+            tip: "ENV",
+            Icon: EnvIcon,
+            warn: envIncomplete,
+          },
+        ]
+      : []),
+    {
+      key: "package" as const,
+      ariaLabel: t("aria.skillPackageDrawer"),
+      tip: "PACKAGE",
+      Icon: PackageIcon,
+    },
+  ];
 
   // No skill specified
   if (!skillName) {
@@ -324,7 +153,42 @@ export function PlaygroundPage() {
     );
   }
 
-  if (isOverLimit && playgroundSnap && quotaSnapshot) {
+  // After loading: no skill data means the caller doesn't have access
+  // (404 SKILL_NOT_FOUND on a private skill they aren't allowed to see),
+  // OR the slug is bogus. Either way, render the not-found state —
+  // never the playground UI (#563). Without this gate, starter prompts
+  // and the chat input were rendering for unauthorized users even
+  // though every API call would 404.
+  if (skillError || !skill) {
+    return (
+      <PageTransition>
+        <div className="flex h-full items-center justify-center">
+          <div className="text-center max-w-md">
+            <p className="mb-2 font-display text-lg text-strong">
+              {t("playground.notFoundTitle", "Skill not found")}
+            </p>
+            <p className="mb-4 font-text text-sm text-meta">
+              {t(
+                "playground.notFoundBody",
+                "This skill doesn't exist, or you don't have access to it.",
+              )}
+            </p>
+            <Link to="/registry" className="font-text text-sm text-accent hover:underline">
+              {t("playground.browseSkills")}
+            </Link>
+          </div>
+        </div>
+      </PageTransition>
+    );
+  }
+
+  // #624 (sibling) — only kick to OverLimitPage on a *fresh* arrival.
+  // Once the user has messages on screen, their conversation
+  // (including a just-completed final allowed run) must not be
+  // replaced by the quota gate when the post-charge quota poll
+  // arrives. The Send button is already disabled via `isOverLimit`
+  // inside the composer, so no new runs slip through.
+  if (isOverLimit && playgroundSnap && quotaSnapshot && !conversationActive) {
     return (
       <PageTransition>
         <OverLimitPage
@@ -336,39 +200,6 @@ export function PlaygroundPage() {
     );
   }
 
-  const starters = defaultPromptStarters(skillName, t);
-  const conversationActive = messages.length > 0 || !!currentAssistantContent || isStreaming;
-
-  // Right-edge rail tabs. Each tab renders as a compact icon handle —
-  // the `tip` is a horizontal mono-uppercase label shown on hover (matches
-  // the drawer header `[§ NAME]` voice). The Package drawer now hosts the
-  // skill identity (name + category + tags + description) at the top of
-  // `SkillPackagePreview`, so a separate Skill tab would be redundant.
-  const railTabs: Array<{
-    key: DrawerKey;
-    ariaLabel: string;
-    tip: string;
-    Icon: ComponentType<IconProps>;
-    warn?: boolean;
-  }> = [
-    ...(needsEnvVars
-      ? [
-          {
-            key: "env" as const,
-            ariaLabel: t("aria.playgroundEnvDrawer"),
-            tip: "ENV",
-            Icon: EnvIcon,
-            warn: envIncomplete,
-          },
-        ]
-      : []),
-    {
-      key: "package",
-      ariaLabel: t("aria.skillPackageDrawer"),
-      tip: "PACKAGE",
-      Icon: PackageIcon,
-    },
-  ];
 
   return (
     <PageTransition>
@@ -405,125 +236,22 @@ export function PlaygroundPage() {
             {/* Messages scroll area */}
             <div ref={messagesScrollRef} className="min-h-0 flex-1 overflow-y-auto pr-1">
               {!conversationActive ? (
-                /* ─── Empty-state hero ─── ChatGPT-style centered prompt
-                    flag with skill identity, single-line lede, and three
-                    starters as soft chips below. Vertical-centered so
-                    the cursor lands ~middle of the screen at rest. */
-                <div className="flex h-full flex-col items-center justify-center py-8">
-                  <div className="w-full space-y-6 text-center">
-                    <div className="space-y-2">
-                      <div className="font-mono text-[10px] uppercase tracking-[0.20em] text-meta">
-                        {skillName}
-                      </div>
-                      <h2 className="font-display text-3xl font-semibold leading-[1.15] tracking-tight text-strong">
-                        {t("playground.heroTitle", "Probe the skill.")}
-                      </h2>
-                      <p className="font-text text-[15px] leading-relaxed text-body">
-                        {envIncomplete
-                          ? t(
-                              "playground.heroEnvFirst",
-                              "Set the runtime env vars in the Env drawer on the right, then start chatting.",
-                            )
-                          : t(
-                              "playground.heroSubtitle",
-                              "Ask anything about {{name}}, or have it run with sample input.",
-                              { name: skillName },
-                            )}
-                      </p>
-                    </div>
-
-                    <div className="grid grid-cols-1 gap-2 sm:grid-cols-3">
-                      {starters.map((s) => (
-                        <button
-                          key={s.label}
-                          type="button"
-                          onClick={() => handleStarterClick(s.body)}
-                          disabled={envIncomplete}
-                          className="group flex flex-col items-start gap-1 rounded-xl border border-subtle bg-card/60 px-3.5 py-3 text-left transition-all hover:border-accent/60 hover:bg-card disabled:cursor-not-allowed disabled:opacity-40"
-                        >
-                          <span className="font-mono text-[10px] uppercase tracking-[0.14em] text-accent">
-                            {s.label}
-                          </span>
-                          <span className="line-clamp-2 font-text text-[13px] leading-snug text-body">
-                            {s.body}
-                          </span>
-                        </button>
-                      ))}
-                    </div>
-
-                    <p className="font-mono text-[10px] uppercase tracking-[0.14em] text-meta/70">
-                      {t(
-                        "playground.drawerHint",
-                        "Skill · Env · Package on the right edge",
-                      )}
-                    </p>
-                  </div>
-                </div>
+                <PlaygroundEmptyHero
+                  skillName={skillName}
+                  envIncomplete={envIncomplete}
+                  starters={starters}
+                  onStarterClick={handleStarterClick}
+                />
               ) : (
-                /* ─── Conversation ─── */
-                <div className="space-y-3 py-3">
-                  {messages.map((msg, idx) => {
-                    const isLastAssistant =
-                      msg.role === "assistant" &&
-                      idx === messages.length - 1 &&
-                      isStreaming;
-                    return (
-                      <ChatMessage
-                        key={msg.id}
-                        message={msg}
-                        toolCallStatuses={toolCallStatuses}
-                        isStreaming={isLastAssistant}
-                      />
-                    );
-                  })}
-
-                  {currentAssistantContent && (
-                    <ChatMessage
-                      message={{
-                        id: "streaming-buffer",
-                        role: "assistant",
-                        content: currentAssistantContent,
-                      }}
-                      toolCallStatuses={toolCallStatuses}
-                      isStreaming
-                    />
-                  )}
-
-                  {isStreaming && !currentAssistantContent && <ThinkingBubble />}
-
-                  {fileOutputs.map((file, idx) => (
-                    <div key={`file-${idx}`} className="flex justify-start">
-                      <div className="max-w-[88%] rounded-sm border border-subtle bg-card p-2.5">
-                        {file.mimeType.startsWith("image/") ? (
-                          <div>
-                            <img
-                              src={`data:${file.mimeType};base64,${file.content}`}
-                              alt={file.path}
-                              className="max-w-full rounded-sm"
-                            />
-                            <p className="mt-1.5 font-mono text-[10px] text-meta">{file.path} ({Math.round(file.size / 1024)}KB)</p>
-                          </div>
-                        ) : (
-                          <a
-                            href={`data:${file.mimeType};base64,${file.content}`}
-                            download={file.path.split("/").pop()}
-                            className="font-mono text-xs text-accent hover:underline"
-                          >
-                            {file.path} ({Math.round(file.size / 1024)}KB)
-                          </a>
-                        )}
-                      </div>
-                    </div>
-                  ))}
-
-                  {error && (
-                    <div className="rounded-sm border border-danger/30 bg-danger/5 px-3 py-2.5">
-                      <p className="font-text text-xs text-danger">{error}</p>
-                    </div>
-                  )}
-
-                  <div ref={messagesEndRef} />
-                </div>
+                <PlaygroundConversation
+                  ref={messagesEndRef}
+                  messages={messages}
+                  isStreaming={isStreaming}
+                  toolCallStatuses={toolCallStatuses}
+                  currentAssistantContent={currentAssistantContent}
+                  fileOutputs={fileOutputs}
+                  error={error}
+                />
               )}
             </div>
 
@@ -560,56 +288,14 @@ export function PlaygroundPage() {
 
         {/* ─── Right-edge rail (always visible — anchored to viewport
             so it stays put when the page scrolls) ─── */}
-        <div
-          className="fixed right-0 top-1/2 z-40 flex -translate-y-1/2 flex-col gap-1"
-          onMouseLeave={scheduleHoverClose}
-        >
-          {railTabs.map((tab) => {
-            const active = activeDrawer === tab.key;
-            const Icon = tab.Icon;
-            return (
-              <button
-                key={tab.key}
-                type="button"
-                onMouseEnter={() => openHover(tab.key)}
-                onClick={() => togglePin(tab.key)}
-                className={`group relative flex h-11 w-9 items-center justify-center rounded-l-sm border-y border-l transition-colors ${
-                  active
-                    ? "border-accent/60 bg-card text-accent"
-                    : "border-subtle bg-card/80 text-meta hover:border-accent/40 hover:text-strong"
-                }`}
-                aria-label={tab.ariaLabel}
-              >
-                <Icon className="h-4 w-4" />
-
-                {/* Horizontal tooltip — fades in on hover when the drawer
-                    for this tab is not already open. Matches the drawer
-                    header voice `[§ NAME]`. */}
-                {!active && (
-                  <span
-                    className="pointer-events-none absolute right-full top-1/2 mr-2 -translate-y-1/2 whitespace-nowrap rounded-sm border border-subtle bg-card px-2 py-1 font-mono text-[10px] uppercase tracking-[0.18em] text-strong opacity-0 transition-opacity duration-150 group-hover:opacity-100"
-                    aria-hidden
-                  >
-                    [§&nbsp;{tab.tip}]
-                  </span>
-                )}
-
-                {tab.warn && (
-                  <span
-                    className="absolute -left-1 top-1.5 h-1.5 w-1.5 rounded-full bg-warning"
-                    aria-hidden
-                  />
-                )}
-                {pinnedDrawer === tab.key && (
-                  <span
-                    className="absolute -left-px inset-y-2 w-px bg-accent"
-                    aria-hidden
-                  />
-                )}
-              </button>
-            );
-          })}
-        </div>
+        <PlaygroundRail
+          tabs={railTabs}
+          activeDrawer={activeDrawer}
+          pinnedDrawer={pinnedDrawer}
+          onHoverOpen={openHover}
+          onHoverCloseScheduled={scheduleHoverClose}
+          onTogglePin={togglePin}
+        />
 
         {/* ─── Drawer overlay ─── */}
         <AnimatePresence>
@@ -678,100 +364,22 @@ export function PlaygroundPage() {
                 {/* Drawer body */}
                 <div className="flex min-h-0 flex-1 flex-col">
                   {activeDrawer === "env" && needsEnvVars && (
-                    <div className="flex min-h-0 flex-1 flex-col">
-                      {/* Header strip — same flat voice as the skill drawer. */}
-                      <div className="shrink-0 border-b border-subtle bg-elevated/30 px-5 py-4">
-                        <div className="font-mono text-[10px] uppercase tracking-[0.18em] text-accent">
-                          [§&nbsp;{t("playground.envVars")}]
-                        </div>
-                        <p className="mt-2 font-text text-sm leading-relaxed text-body">
-                          {t("playground.envVarsDesc")}
-                        </p>
-                      </div>
-
-                      {/* Form */}
-                      <div className="min-h-0 flex-1 space-y-3 overflow-y-auto px-5 py-4">
-                        {envVarKeys.map((key) => {
-                          const filled = !!envVars[key]?.trim();
-                          return (
-                            <div key={key} className="space-y-1">
-                              <div className="flex items-center justify-between gap-2">
-                                <label
-                                  className="block min-w-0 flex-1 truncate font-mono text-[11px] text-strong"
-                                  title={key}
-                                >
-                                  {key}
-                                </label>
-                                <span
-                                  className={`shrink-0 font-mono text-[10px] uppercase tracking-[0.14em] ${
-                                    filled ? "text-success" : "text-meta"
-                                  }`}
-                                >
-                                  {filled ? t("common.set") : t("common.required")}
-                                </span>
-                              </div>
-                              <input
-                                type="text"
-                                value={envVars[key] ?? ""}
-                                onChange={(e) => handleEnvVarChange(key, e.target.value)}
-                                placeholder={t("playground.enterValue")}
-                                className="w-full rounded-sm border border-subtle bg-page px-2.5 py-1.5 font-mono text-xs text-strong placeholder:text-meta/50 focus:border-accent/60 focus:outline-none"
-                              />
-                            </div>
-                          );
-                        })}
-                        {!allEnvVarsFilled && (
-                          <p className="pt-2 font-text text-[11px] leading-relaxed text-meta">
-                            {t(
-                              "playground.envVarsLockHint",
-                              "Chat is locked until every required env var has a value.",
-                            )}
-                          </p>
-                        )}
-                      </div>
-                    </div>
+                    <PlaygroundEnvDrawerBody
+                      envVarKeys={envVarKeys}
+                      envVars={envVars}
+                      allEnvVarsFilled={allEnvVarsFilled}
+                      onEnvVarChange={handleEnvVarChange}
+                    />
                   )}
 
                   {activeDrawer === "package" && (
-                    <div className="flex min-h-0 flex-1 flex-col">
-                      {/* Padded content area — must itself be a flex column
-                          so the preview's `flex-1 min-h-0` actually claims
-                          the remaining height and the file viewer scrolls
-                          internally instead of bleeding past the footer. */}
-                      <div className="flex min-h-0 flex-1 flex-col p-4">
-                        {packageLoading ? (
-                          <Skeleton lines={8} />
-                        ) : packageFiles.length > 0 ? (
-                          <SkillPackagePreview
-                            files={packageFiles}
-                            fileContents={packageContents}
-                            metadata={previewMetadata}
-                            editable={false}
-                            className="min-h-0 flex-1"
-                          />
-                        ) : (
-                          <div className="flex h-32 items-center justify-center">
-                            <p className="font-text text-xs text-meta">{t("playground.noPackage")}</p>
-                          </div>
-                        )}
-                      </div>
-
-                      {/* Footer — registry link pinned at the bottom,
-                          matching the Skill drawer's pattern. */}
-                      {skill && (
-                        <div className="flex shrink-0 items-center justify-between border-t border-subtle bg-elevated/30 px-5 py-3">
-                          <span className="font-mono text-[10px] uppercase tracking-[0.18em] text-meta">
-                            {skill.name}@v{skill.version}
-                          </span>
-                          <Link
-                            to={`/skills/${encodeURIComponent(skill.name)}`}
-                            className="font-mono text-[11px] text-accent hover:underline"
-                          >
-                            {t("playground.openInRegistry", "Open in registry →")}
-                          </Link>
-                        </div>
-                      )}
-                    </div>
+                    <PlaygroundPackageDrawerBody
+                      packageLoading={packageLoading}
+                      packageFiles={packageFiles}
+                      packageContents={packageContents}
+                      previewMetadata={previewMetadata}
+                      skill={skill}
+                    />
                   )}
                 </div>
               </motion.aside>
diff --git a/ornn-web/src/pages/admin/BroadcastsPage.tsx b/ornn-web/src/pages/admin/BroadcastsPage.tsx
index 73107b97..7f329b0c 100644
--- a/ornn-web/src/pages/admin/BroadcastsPage.tsx
+++ b/ornn-web/src/pages/admin/BroadcastsPage.tsx
@@ -11,9 +11,9 @@
  * @module pages/admin/BroadcastsPage
  */
 
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
-import { motion } from "framer-motion";
+import { motion, AnimatePresence } from "framer-motion";
 import { useQuery } from "@tanstack/react-query";
 import { Button } from "@/components/ui/Button";
 import { Card } from "@/components/ui/Card";
@@ -149,8 +149,12 @@ export function BroadcastsPage() {
     return map;
   }, [emailLookupQuery.data]);
 
-  const recipientsTooltip = (ids: string[]): string =>
-    ids.map((id) => emailById.get(id) ?? id).join("\n");
+  // #507 — the old `\n`-joined native `title` tooltip was unreadable in
+  // Safari (collapses `\n` to a single space) and unusable for many
+  // recipients on any browser. Resolve to emails once here; the popover
+  // renders the list scrollably so long counts no longer truncate.
+  const resolveEmails = (ids: string[]): string[] =>
+    ids.map((id) => emailById.get(id) ?? id);
 
   const pendingDeleteTitle = pendingDelete
     ? pickLocalized(
@@ -269,25 +273,21 @@ export function BroadcastsPage() {
                             {t("adminPages.broadcasts.recipients.summaryAll")}
                           </span>
                         ) : (
-                          <span
-                            title={recipientsTooltip(b.recipientUserIds)}
-                            className="inline-flex items-center gap-1 rounded-sm border border-subtle bg-elevated/40 px-2 py-0.5 font-mono text-[11px] text-strong"
-                          >
-                            {t("adminPages.broadcasts.recipients.summaryCount", {
-                              count: b.recipientUserIds.length,
-                            })}
-                          </span>
+                          <RecipientsPopover
+                            count={b.recipientUserIds.length}
+                            emails={resolveEmails(b.recipientUserIds)}
+                          />
                         )}
                       </td>
                       <td className="px-4 py-3 align-top font-mono text-[11px] text-meta">
                         {new Date(b.createdAt).toLocaleString(
-                          undefined,
+                          lang,
                           ROW_DATE_FMT,
                         )}
                       </td>
                       <td className="px-4 py-3 align-top font-mono text-[11px] text-meta">
                         {new Date(b.updatedAt).toLocaleString(
-                          undefined,
+                          lang,
                           ROW_DATE_FMT,
                         )}
                       </td>
@@ -343,3 +343,90 @@ export function BroadcastsPage() {
     </motion.div>
   );
 }
+
+/**
+ * Click/hover popover that lists broadcast recipients (#507). Replaces
+ * the prior native `title` tooltip whose `\n`-joined string rendered as
+ * one run-on line in Safari and truncated off-screen for many
+ * recipients on every browser.
+ *
+ * Behaviour mirrors `CategoryTooltip`:
+ *   - hover OR click opens; click-outside / second-click closes
+ *   - `aria-expanded` reflects state for screen readers
+ *   - the list is `max-h-64 overflow-y-auto` so 20+ recipients stay
+ *     readable instead of overflowing the viewport
+ *
+ * Kept inline because BroadcastsPage is the only consumer; promoting
+ * it to `components/ui/` would be premature.
+ */
+function RecipientsPopover({ count, emails }: { count: number; emails: string[] }) {
+  const { t } = useTranslation();
+  const [isOpen, setIsOpen] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const handleClickOutside = (e: MouseEvent) => {
+      if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
+        setIsOpen(false);
+      }
+    };
+    const handleEsc = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setIsOpen(false);
+    };
+    document.addEventListener("mousedown", handleClickOutside);
+    document.addEventListener("keydown", handleEsc);
+    return () => {
+      document.removeEventListener("mousedown", handleClickOutside);
+      document.removeEventListener("keydown", handleEsc);
+    };
+  }, [isOpen]);
+
+  return (
+    <div ref={containerRef} className="relative inline-flex">
+      <button
+        type="button"
+        aria-expanded={isOpen}
+        onClick={() => setIsOpen((prev) => !prev)}
+        onMouseEnter={() => setIsOpen(true)}
+        onFocus={() => setIsOpen(true)}
+        className="inline-flex items-center gap-1 rounded-sm border border-subtle bg-elevated/40 px-2 py-0.5 font-mono text-[11px] text-strong hover:border-accent/40 hover:text-accent transition-colors"
+      >
+        {t("adminPages.broadcasts.recipients.summaryCount", { count })}
+      </button>
+
+      <AnimatePresence>
+        {isOpen && (
+          <motion.div
+            initial={{ opacity: 0, scale: 0.96 }}
+            animate={{ opacity: 1, scale: 1 }}
+            exit={{ opacity: 0, scale: 0.96 }}
+            transition={{ duration: 0.12 }}
+            role="dialog"
+            aria-label={t("adminPages.broadcasts.recipients.popoverAria", {
+              defaultValue: "Recipient list",
+            })}
+            className="absolute left-0 top-7 z-50 w-72 rounded-md border border-strong-edge bg-card p-3 card-impression"
+          >
+            <p className="font-mono text-[10px] uppercase tracking-[0.14em] text-meta mb-2">
+              {t("adminPages.broadcasts.recipients.popoverHeader", {
+                defaultValue: "Recipients ({{count}})",
+                count,
+              })}
+            </p>
+            <ul className="max-h-64 overflow-y-auto space-y-1 pr-1">
+              {emails.map((email, i) => (
+                <li
+                  key={`${email}-${i}`}
+                  className="font-mono text-[11px] text-strong break-all"
+                >
+                  {email}
+                </li>
+              ))}
+            </ul>
+          </motion.div>
+        )}
+      </AnimatePresence>
+    </div>
+  );
+}
diff --git a/ornn-web/src/pages/admin/MirrorPage.tsx b/ornn-web/src/pages/admin/MirrorPage.tsx
index a16e1ed2..e81c8263 100644
--- a/ornn-web/src/pages/admin/MirrorPage.tsx
+++ b/ornn-web/src/pages/admin/MirrorPage.tsx
@@ -189,7 +189,7 @@ export function MirrorPage() {
       const message = translateError(err);
       const code = err instanceof ApiClientError ? err.code : null;
       // Surface the abandon-confirm path even if the modal was bypassed.
-      if (code === "OLD_REPO_NOT_CONFIRMED") {
+      if (code === "old_repo_not_confirmed") {
         setConfirmModalOpen(true);
       } else {
         addToast({ type: "error", message });
diff --git a/ornn-web/src/pages/admin/settings/sections/ExtrasSection.tsx b/ornn-web/src/pages/admin/settings/sections/ExtrasSection.tsx
index fa2a84a4..bb814118 100644
--- a/ornn-web/src/pages/admin/settings/sections/ExtrasSection.tsx
+++ b/ornn-web/src/pages/admin/settings/sections/ExtrasSection.tsx
@@ -87,7 +87,12 @@ export function ExtrasSection() {
   ) => {
     if (!draft) return;
     const next = [...draft.extraNyxidServices];
-    next[idx] = { ...next[idx], ...patch };
+    // `idx` is a caller-provided index into the same draft array we
+    // just spread. Guard rather than `!` so a stale callback can't
+    // crash the page under noUncheckedIndexedAccess (#450).
+    const current = next[idx];
+    if (!current) return;
+    next[idx] = { ...current, ...patch };
     form.patchDraft({ extraNyxidServices: next });
   };
 
diff --git a/ornn-web/src/pages/admin/settings/sections/MirrorSection.tsx b/ornn-web/src/pages/admin/settings/sections/MirrorSection.tsx
index 4b6502de..b4f7d1b6 100644
--- a/ornn-web/src/pages/admin/settings/sections/MirrorSection.tsx
+++ b/ornn-web/src/pages/admin/settings/sections/MirrorSection.tsx
@@ -178,7 +178,7 @@ export function MirrorSection() {
             />
 
             <Link
-              to="/admin/skills"
+              to="/admin/mirror"
               className="inline-flex items-center gap-2 font-mono text-[11px] uppercase tracking-[0.14em] text-accent hover:text-accent-muted"
             >
               {t("adminSettings.sections.mirror.openDashboard")}
diff --git a/ornn-web/src/pages/landing/AnimatedTerminal.tsx b/ornn-web/src/pages/landing/AnimatedTerminal.tsx
index a158fe61..3c3ae1ac 100644
--- a/ornn-web/src/pages/landing/AnimatedTerminal.tsx
+++ b/ornn-web/src/pages/landing/AnimatedTerminal.tsx
@@ -6,9 +6,9 @@ const LINES: Line[] = [
   { t: 500, html: '<span class="text-ember">$</span> <span class="text-parchment">ornn-search-and-run</span> <span class="text-molten">"extract text from PDFs"</span>' },
   { t: 300, html: '<span class="text-ash">  ↳ querying registry...</span>' },
   { t: 400, html: '<span class="text-ash">  ↳ matched 3 candidates</span>' },
-  { t: 400, html: '<span class="text-[#7dc97d]">  ✓ pdf-extract</span>   <span class="text-ash">@chrono · v 2.0.1 · audited</span>' },
+  { t: 400, html: '<span class="text-terminal-ok">  ✓ pdf-extract</span>   <span class="text-ash">@chrono · v 2.0.1 · audited</span>' },
   { t: 300, html: '<span class="text-ash">  ↳ loading SKILL.md into Claude Code...</span>' },
-  { t: 400, html: '<span class="text-[#7dc97d]">  ✓ ready</span>          <span class="text-ash">~/.claude/skills/pdf-extract/</span>' },
+  { t: 400, html: '<span class="text-terminal-ok">  ✓ ready</span>          <span class="text-ash">~/.claude/skills/pdf-extract/</span>' },
   { t: 400, html: "" },
   { t: 200, html: '<span class="text-bone">agent-ready in <span class="text-molten">1.2s</span></span>' },
   { t: 600, html: '<span class="text-ember">$</span> <span class="inline-block h-3.5 w-2 bg-ember align-middle animate-blink"></span>' },
@@ -70,9 +70,9 @@ export function AnimatedTerminal() {
   return (
     <div className="card-letterpress overflow-hidden rounded-[4px] border border-[color:var(--color-border-strong)] [background-color:var(--surface-code)] font-mono text-[13px]">
       <div className="flex items-center gap-2 border-b border-[color:var(--color-border-subtle)] bg-graphite px-3.5 py-2.5">
-        <span className="h-[9px] w-[9px] rounded-full bg-[#c94a4a]" />
-        <span className="h-[9px] w-[9px] rounded-full bg-[#c9a64a]" />
-        <span className="h-[9px] w-[9px] rounded-full bg-[#5a9b5a]" />
+        <span className="h-[9px] w-[9px] rounded-full bg-traffic-red" />
+        <span className="h-[9px] w-[9px] rounded-full bg-traffic-amber" />
+        <span className="h-[9px] w-[9px] rounded-full bg-traffic-green" />
         <span className="ml-auto font-mono text-[11px] tracking-[0.12em] text-meta">
           ~/projects · ornn cli
         </span>
diff --git a/ornn-web/src/pages/landing/AnnouncementPopup.tsx b/ornn-web/src/pages/landing/AnnouncementPopup.tsx
index 7a9e3a7a..e348fcfb 100644
--- a/ornn-web/src/pages/landing/AnnouncementPopup.tsx
+++ b/ornn-web/src/pages/landing/AnnouncementPopup.tsx
@@ -144,7 +144,11 @@ export function AnnouncementPopup() {
             role="dialog"
             aria-modal="true"
             aria-labelledby="announcement-title"
-            style={INK_OVERRIDES}
+            // exactOptionalPropertyTypes (#657): framer-motion's
+            // `MotionStyle` rejects React.CSSProperties under the
+            // stricter flag (incompatible optionals on transform/etc.).
+            // Cast to `never` to bridge — runtime shape is unchanged.
+            style={INK_OVERRIDES as unknown as never}
             className="
               relative z-10 mx-4 w-full max-w-lg max-h-[80vh] overflow-y-auto
               rounded-[3px] border border-[var(--color-ember-deep)] bg-accent
diff --git a/ornn-web/src/pages/landing/HeroStage.tsx b/ornn-web/src/pages/landing/HeroStage.tsx
index c9ebae72..c8f102a0 100644
--- a/ornn-web/src/pages/landing/HeroStage.tsx
+++ b/ornn-web/src/pages/landing/HeroStage.tsx
@@ -248,6 +248,10 @@ function ScrubHero() {
     let firingIdx = -1;
     for (let i = 0; i < RAIL_SKILLS.length; i++) {
       const skill = RAIL_SKILLS[i];
+      // `i` is bounded by `RAIL_SKILLS.length`, but
+      // noUncheckedIndexedAccess (#450) widens the lookup. Skip when
+      // the array shape drifts rather than crash.
+      if (!skill) continue;
       const start = ITEM_BASE + i * ITEM_STEP;
       const local = (v - start) / ITEM_DUR;
       const path = pathRefs.current[i];
diff --git a/ornn-web/src/pages/landing/PhoneMockup.tsx b/ornn-web/src/pages/landing/PhoneMockup.tsx
index a1cc0fea..497b3f57 100644
--- a/ornn-web/src/pages/landing/PhoneMockup.tsx
+++ b/ornn-web/src/pages/landing/PhoneMockup.tsx
@@ -26,17 +26,17 @@ export const PhoneMockup = forwardRef<HTMLDivElement, Props>(function PhoneMocku
     >
       <div
         ref={phoneRef}
-        className="group/phone relative z-10 w-[min(290px,100%)] aspect-[9/19] rounded-[44px] bg-obsidian px-[10px] py-[11px] shadow-[0_0_0_1.5px_#2a2620,inset_0_0_0_1px_rgb(255_255_255/0.04),inset_0_0_0_2px_rgb(0_0_0/0.9),12px_12px_0_0_var(--color-shadow-press)] [transform:perspective(1800px)_rotateY(-5deg)_rotateX(2deg)] [transform-origin:50%_50%] [transition:transform_0.6s_cubic-bezier(.2,.8,.3,1),filter_0.6s_ease] data-[settled=true]:[transform:perspective(1800px)_rotateY(0)_rotateX(0)] data-[dimmed=true]:brightness-[0.55] data-[dimmed=true]:saturate-[0.85] before:pointer-events-none before:absolute before:inset-0 before:z-[2] before:rounded-[44px] before:bg-[linear-gradient(135deg,rgb(255_255_255/0.06),rgb(255_255_255/0)_30%,rgb(255_255_255/0)_70%,rgb(255_255_255/0.04))]"
+        className="group/phone relative z-10 w-[min(290px,100%)] aspect-[9/19] rounded-[44px] bg-obsidian px-[10px] py-[11px] shadow-[0_0_0_1.5px_var(--color-bezel-rim),inset_0_0_0_1px_rgb(255_255_255/0.04),inset_0_0_0_2px_rgb(0_0_0/0.9),12px_12px_0_0_var(--color-shadow-press)] [transform:perspective(1800px)_rotateY(-5deg)_rotateX(2deg)] [transform-origin:50%_50%] [transition:transform_0.6s_cubic-bezier(.2,.8,.3,1),filter_0.6s_ease] data-[settled=true]:[transform:perspective(1800px)_rotateY(0)_rotateX(0)] data-[dimmed=true]:brightness-[0.55] data-[dimmed=true]:saturate-[0.85] before:pointer-events-none before:absolute before:inset-0 before:z-[2] before:rounded-[44px] before:bg-[linear-gradient(135deg,rgb(255_255_255/0.06),rgb(255_255_255/0)_30%,rgb(255_255_255/0)_70%,rgb(255_255_255/0.04))]"
       >
         {/* Side buttons on bezel edges */}
-        <span className="absolute -left-[3px] top-[92px] z-[3] h-6 w-[3px] rounded-l-[2px] bg-[#1a1713] shadow-[inset_0_1px_0_rgb(255_255_255/0.05),inset_0_-1px_0_rgb(0_0_0/0.6)]" />
-        <span className="absolute -left-[3px] top-[132px] z-[3] h-[46px] w-[3px] rounded-l-[2px] bg-[#1a1713] shadow-[inset_0_1px_0_rgb(255_255_255/0.05),inset_0_-1px_0_rgb(0_0_0/0.6)]" />
-        <span className="absolute -left-[3px] top-[190px] z-[3] h-[46px] w-[3px] rounded-l-[2px] bg-[#1a1713] shadow-[inset_0_1px_0_rgb(255_255_255/0.05),inset_0_-1px_0_rgb(0_0_0/0.6)]" />
-        <span className="absolute -right-[3px] top-[150px] z-[3] h-[68px] w-[3px] rounded-r-[2px] bg-[#1a1713] shadow-[inset_0_1px_0_rgb(255_255_255/0.05),inset_0_-1px_0_rgb(0_0_0/0.6)]" />
+        <span className="absolute -left-[3px] top-[92px] z-[3] h-6 w-[3px] rounded-l-[2px] bg-bezel-edge shadow-[inset_0_1px_0_rgb(255_255_255/0.05),inset_0_-1px_0_rgb(0_0_0/0.6)]" />
+        <span className="absolute -left-[3px] top-[132px] z-[3] h-[46px] w-[3px] rounded-l-[2px] bg-bezel-edge shadow-[inset_0_1px_0_rgb(255_255_255/0.05),inset_0_-1px_0_rgb(0_0_0/0.6)]" />
+        <span className="absolute -left-[3px] top-[190px] z-[3] h-[46px] w-[3px] rounded-l-[2px] bg-bezel-edge shadow-[inset_0_1px_0_rgb(255_255_255/0.05),inset_0_-1px_0_rgb(0_0_0/0.6)]" />
+        <span className="absolute -right-[3px] top-[150px] z-[3] h-[68px] w-[3px] rounded-r-[2px] bg-bezel-edge shadow-[inset_0_1px_0_rgb(255_255_255/0.05),inset_0_-1px_0_rgb(0_0_0/0.6)]" />
 
         <div className="relative h-full w-full overflow-hidden rounded-[34px] bg-obsidian shadow-[inset_0_0_0_1px_rgb(255_255_255/0.02)]">
           {/* Notch */}
-          <span className="absolute left-1/2 top-2.5 z-[4] h-[26px] w-[88px] -translate-x-1/2 rounded-[16px] bg-black shadow-[0_0_0_0.5px_#1a1713] after:absolute after:right-3 after:top-1/2 after:h-1.5 after:w-1.5 after:-translate-y-1/2 after:rounded-full after:content-[''] after:bg-[radial-gradient(circle_at_30%_30%,#3a5060,#0b1520)]" />
+          <span className="absolute left-1/2 top-2.5 z-[4] h-[26px] w-[88px] -translate-x-1/2 rounded-[16px] bg-black shadow-[0_0_0_0.5px_var(--color-bezel-edge)] after:absolute after:right-3 after:top-1/2 after:h-1.5 after:w-1.5 after:-translate-y-1/2 after:rounded-full after:content-[''] after:bg-[radial-gradient(circle_at_30%_30%,var(--color-lens-rim),var(--color-lens-deep))]" />
 
           {/* Status bar */}
           <div className="flex h-7 items-center justify-between px-[18px] pl-[22px] font-mono text-[10px] tracking-[0.08em] text-parchment">
diff --git a/ornn-web/src/pages/skill/CreateSkillFreePage.tsx b/ornn-web/src/pages/skill/CreateSkillFreePage.tsx
index c4e84d0b..1978bf2b 100644
--- a/ornn-web/src/pages/skill/CreateSkillFreePage.tsx
+++ b/ornn-web/src/pages/skill/CreateSkillFreePage.tsx
@@ -58,7 +58,10 @@ function buildTreeFromValidation(
         type: "file",
       });
     } else {
-      const folder = parts[0];
+      // The else branch only fires when `parts.length > 1`, so
+      // `parts[0]` is guaranteed defined. `!` is safe under
+      // noUncheckedIndexedAccess (#450).
+      const folder = parts[0]!;
       const existing = folderMap.get(folder) ?? [];
       existing.push({
         id: file.id,
@@ -277,9 +280,14 @@ export function CreateSkillFreePage() {
     } catch (err) {
       const message = translateError(err, t("free.uploadFailed"));
       addToast({ type: "error", message });
-      setPageState(
-        validationResult?.status === "warning" ? "warning" : "valid",
-      );
+      // #652 — restore the page to whatever pre-submit state the
+      // frontend originally derived. The previous code unconditionally
+      // forced "valid" / "warning", which made the success banner
+      // ("Skill package structure is valid.") render on top of the
+      // backend's rejection toast — contradictory and confusing,
+      // especially when the user had skip-validation toggled past an
+      // "invalid" structure.
+      setPageState(validationResult?.status ?? "valid");
     }
   };
 
@@ -398,12 +406,15 @@ export function CreateSkillFreePage() {
             }`}
           >
             {validationResult.errors.map((err, i) => (
-              <p key={i} className="font-text text-sm text-danger">
+              // Each error key is unique per validation run; combining
+              // key with index defends against duplicate keys when the
+              // same error fires twice (#451).
+              <p key={`err-${i}-${err.key}`} className="font-text text-sm text-danger">
                 {t(err.key, err.params ?? {})}
               </p>
             ))}
             {validationResult.warnings.map((warn, i) => (
-              <p key={i} className="font-text text-sm text-warning">
+              <p key={`warn-${i}-${warn.key}`} className="font-text text-sm text-warning">
                 {t(warn.key, warn.params ?? {})}
               </p>
             ))}
diff --git a/ornn-web/src/pages/skill/CreateSkillGenerativePage.tsx b/ornn-web/src/pages/skill/CreateSkillGenerativePage.tsx
index 6dede3b2..ea376c2a 100644
--- a/ornn-web/src/pages/skill/CreateSkillGenerativePage.tsx
+++ b/ornn-web/src/pages/skill/CreateSkillGenerativePage.tsx
@@ -257,7 +257,21 @@ export function CreateSkillGenerativePage() {
         "Describe the skill you want to create…",
       );
 
-  if (isOverLimit && skillGenSnap && quotaSnapshot) {
+  // #624 — only redirect to the over-limit page on a *fresh* arrival
+  // (no messages exchanged AND no generated preview). Once the user
+  // has produced a result this session, the quota poll dropping their
+  // remaining to 0 should NOT yank the result off-screen; the Send
+  // button is already disabled below via `isOverLimit`, which is the
+  // right gate (no new generations) without losing what's already on
+  // the page. Without this guard, the final allowed generation
+  // succeeds → quota refetch → page replaced → user can't save.
+  if (
+    isOverLimit &&
+    skillGenSnap &&
+    quotaSnapshot &&
+    !hasMessages &&
+    !hasPreview
+  ) {
     return (
       <PageTransition>
         <OverLimitPage
diff --git a/ornn-web/src/pages/skill/CreateSkillGuidedPage.tsx b/ornn-web/src/pages/skill/CreateSkillGuidedPage.tsx
index 65bc9ba6..08abb804 100644
--- a/ornn-web/src/pages/skill/CreateSkillGuidedPage.tsx
+++ b/ornn-web/src/pages/skill/CreateSkillGuidedPage.tsx
@@ -7,7 +7,7 @@
 
 import { useState, useCallback, useEffect, useMemo } from "react";
 import { useNavigate } from "react-router-dom";
-import { useForm } from "react-hook-form";
+import { useForm, type Resolver } from "react-hook-form";
 import { zodResolver } from "@hookform/resolvers/zod";
 import { AnimatePresence } from "framer-motion";
 import { PageTransition } from "@/components/layout/PageTransition";
@@ -26,7 +26,7 @@ import { useAuthStore } from "@/stores/authStore";
 import { track } from "@/lib/analytics";
 import { buildSkillMd } from "@/utils/frontmatterBuilder";
 import { buildFileTreeFromFolders, readUploadedFileContents } from "@/utils/fileTreeBuilder";
-import { basicInfoSchema, contentSchema, type BasicInfoData, type BasicInfoInput, type ContentData, type ContentInput } from "@/utils/skillCreateSchemas";
+import { basicInfoSchema, contentSchema, makeBasicInfoSchema, makeContentSchema, type BasicInfoData, type BasicInfoInput, type ContentData, type ContentInput } from "@/utils/skillCreateSchemas";
 import type { FileNode } from "@/components/editor/FileTree";
 import type { SkillMetadata, SkillMetadataBlock, UploadableFolder } from "@/types/skillPackage";
 import { createDefaultSkillMetadata } from "@/types/skillPackage";
@@ -120,9 +120,30 @@ export function CreateSkillGuidedPage() {
     new Map(),
   );
 
-  // Basic info form (nested metadata)
+  // Schemas are rebuilt per-`t` so a language switch refreshes the
+  // validation messages (#695). `t` is cast because react-i18next's
+  // overloaded TFunction doesn't structurally match the simple
+  // signature `makeXSchema` accepts. The resulting schema is cast to
+  // the static schema type so `zodResolver`'s precise typing on the
+  // existing `basicInfoSchema` / `contentSchema` exports keeps working
+  // — at runtime the localized factory is what produces error
+  // messages.
+  const tx = t as unknown as (key: string) => string;
+  const basicInfoSchemaLocalized = useMemo(
+    () => makeBasicInfoSchema(tx) as typeof basicInfoSchema,
+    [tx],
+  );
+  const contentSchemaLocalized = useMemo(
+    () => makeContentSchema(tx) as typeof contentSchema,
+    [tx],
+  );
+
   const basicInfoForm = useForm<BasicInfoInput, unknown, BasicInfoData>({
-    resolver: zodResolver(basicInfoSchema),
+    // Cast: zodResolver infers a slightly different Resolver shape
+    // from the factory's return type; structurally identical to the
+    // one inferred from the static `basicInfoSchema`, which the
+    // pre-#695 code used here directly.
+    resolver: zodResolver(basicInfoSchemaLocalized) as Resolver<BasicInfoInput, unknown, BasicInfoData>,
     defaultValues: {
       name: formData.name,
       description: formData.description,
@@ -141,7 +162,7 @@ export function CreateSkillGuidedPage() {
 
   // Content form
   const contentForm = useForm<ContentInput, unknown, ContentData>({
-    resolver: zodResolver(contentSchema),
+    resolver: zodResolver(contentSchemaLocalized) as Resolver<ContentInput, unknown, ContentData>,
     defaultValues: {
       readmeMd: formData.readmeMd,
     },
@@ -354,7 +375,10 @@ export function CreateSkillGuidedPage() {
           <CompactStepIndicator
             currentStep={currentStep}
             totalSteps={translatedSteps.length}
-            currentLabel={translatedSteps[currentStep].label}
+            // `currentStep` is bounded by `translatedSteps.length`
+            // (`setCurrentStep` clamps in handlers above). `!` is safe
+            // under noUncheckedIndexedAccess (#450).
+            currentLabel={translatedSteps[currentStep]!.label}
           />
         </div>
 
diff --git a/ornn-web/src/pages/skill/EditSkillPage.test.tsx b/ornn-web/src/pages/skill/EditSkillPage.test.tsx
new file mode 100644
index 00000000..532716ee
--- /dev/null
+++ b/ornn-web/src/pages/skill/EditSkillPage.test.tsx
@@ -0,0 +1,105 @@
+/**
+ * EditSkillPage regression tests.
+ *
+ * Locks in the contract that owner write mutations
+ * (`useUpdateSkill`, `useUpdateSkillPackage`) receive the skill's
+ * GUID, never the URL `:id` (which is the human-readable name).
+ *
+ * Why this matters (#565): PR #586 tightened backend resolution on
+ * `PUT /skills/:id` to `findByGuid` only — no `findByName` fallback.
+ * The page route stays human-readable (`/skills/:name/edit`) for SEO
+ * and shareability; the page must therefore resolve through
+ * `useSkill(name)` first and hand `skill.guid` to every write hook.
+ * A previous version of this file passed the URL param straight
+ * through, which broke owner edits with a 404 on the live cluster.
+ *
+ * @module pages/skill/EditSkillPage.test
+ */
+
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import type { SkillDetail } from "@/services/skillApi";
+
+// react-router's `useParams` is what gives the page its URL `:id`,
+// i.e. the human-readable name.
+vi.mock("react-router-dom", () => ({
+  useParams: () => ({ id: "my-public-skill" }),
+}));
+
+// react-i18next is heavy at import time; stub it so the test stays
+// focused on the hook-id contract. `initReactI18next` is referenced
+// at module top-level by `src/i18n/index.ts`; stub it as a Module
+// type to keep i18n's initialisation chain happy under jsdom.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (_key: string, fallback?: string) => fallback ?? "",
+  }),
+  initReactI18next: { type: "3rdParty", init: () => {} },
+}));
+
+// Spies that capture the `id` argument each write hook receives.
+const updateSpy = vi.fn<(id: string) => unknown>();
+const updatePkgSpy = vi.fn<(id: string) => unknown>();
+
+vi.mock("@/hooks/useSkills", () => ({
+  useSkill: () => ({
+    data: {
+      guid: "abc-123-guid",
+      name: "my-public-skill",
+      description: "...",
+      isPrivate: false,
+    } satisfies Partial<SkillDetail>,
+    isLoading: false,
+    refetch: vi.fn(),
+  }),
+  useUpdateSkill: (id: string) => {
+    updateSpy(id);
+    return { mutateAsync: vi.fn(), isPending: false };
+  },
+  useUpdateSkillPackage: (id: string) => {
+    updatePkgSpy(id);
+    return { mutateAsync: vi.fn(), isPending: false };
+  },
+}));
+
+vi.mock("@/stores/toastStore", () => ({
+  useToastStore: () => vi.fn(),
+}));
+
+// Layout / UI bits don't matter for the contract — stub them to keep
+// the test fast and immune to unrelated rendering churn.
+vi.mock("@/components/layout/PageTransition", () => ({
+  PageTransition: ({ children }: { children: React.ReactNode }) => (
+    <>{children}</>
+  ),
+}));
+vi.mock("@/components/layout/BackLink", () => ({
+  BackLink: () => null,
+}));
+
+import { EditSkillPage } from "./EditSkillPage";
+
+describe("EditSkillPage — write mutations receive skill.guid (#565)", () => {
+  beforeEach(() => {
+    updateSpy.mockClear();
+    updatePkgSpy.mockClear();
+  });
+  afterEach(() => cleanup());
+
+  it("hands skill.guid (not the URL :id) to useUpdateSkill", () => {
+    render(<EditSkillPage />);
+    expect(updateSpy).toHaveBeenCalled();
+    const lastCall = updateSpy.mock.calls[updateSpy.mock.calls.length - 1]?.[0];
+    expect(lastCall).toBe("abc-123-guid");
+    expect(lastCall).not.toBe("my-public-skill");
+  });
+
+  it("hands skill.guid (not the URL :id) to useUpdateSkillPackage", () => {
+    render(<EditSkillPage />);
+    expect(updatePkgSpy).toHaveBeenCalled();
+    const lastCall =
+      updatePkgSpy.mock.calls[updatePkgSpy.mock.calls.length - 1]?.[0];
+    expect(lastCall).toBe("abc-123-guid");
+    expect(lastCall).not.toBe("my-public-skill");
+  });
+});
diff --git a/ornn-web/src/pages/skill/EditSkillPage.tsx b/ornn-web/src/pages/skill/EditSkillPage.tsx
index ecefefcf..0a9bbb5a 100644
--- a/ornn-web/src/pages/skill/EditSkillPage.tsx
+++ b/ornn-web/src/pages/skill/EditSkillPage.tsx
@@ -17,8 +17,19 @@ export function EditSkillPage() {
   const { id } = useParams<{ id: string }>();
   const addToast = useToastStore((s) => s.addToast);
   const { data: skill, isLoading, refetch } = useSkill(id ?? "");
-  const updateMutation = useUpdateSkill(id ?? "");
-  const updatePackageMutation = useUpdateSkillPackage(id ?? "");
+  // #565 — read endpoints accept skill name OR GUID, but #586
+  // tightened PUT / PATCH to GUID-only. The URL param `:id` is the
+  // human-readable skill name; we resolve it through the GET first
+  // (which accepts either), then hand the resulting `guid` to the
+  // write mutations. The fallback to `id` is only exercised on the
+  // first render before skill data arrives — and both mutations are
+  // hidden behind `if (isLoading) {...}` and `if (!skill) {...}`
+  // early returns below, so the user can never click a button while
+  // `writeId` is still pointing at the name. Same pattern as
+  // `useSkillDetail.ts:77`.
+  const writeId = skill?.guid ?? id ?? "";
+  const updateMutation = useUpdateSkill(writeId);
+  const updatePackageMutation = useUpdateSkillPackage(writeId);
   const fileInputRef = useRef<HTMLInputElement>(null);
   const [zipFile, setZipFile] = useState<File | null>(null);
 
diff --git a/ornn-web/src/pages/skill/MySkillsPage.tsx b/ornn-web/src/pages/skill/MySkillsPage.tsx
index 03ef557b..318c20f3 100644
--- a/ornn-web/src/pages/skill/MySkillsPage.tsx
+++ b/ornn-web/src/pages/skill/MySkillsPage.tsx
@@ -102,6 +102,7 @@ export function MySkillsPage() {
         {isLoading ? (
           <div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3 pb-4">
             {Array.from({ length: 6 }).map((_, i) => (
+              // Positional list — never reorders, key={i} is intentional (#451).
               <SkeletonCard key={i} />
             ))}
           </div>
diff --git a/ornn-web/src/pages/skill/SkillDetailPage.tsx b/ornn-web/src/pages/skill/SkillDetailPage.tsx
index a4df84ba..0f1e8137 100644
--- a/ornn-web/src/pages/skill/SkillDetailPage.tsx
+++ b/ornn-web/src/pages/skill/SkillDetailPage.tsx
@@ -13,14 +13,13 @@
  * @module pages/skill/SkillDetailPage
  */
 
-import { useState, useCallback, useMemo, useEffect } from "react";
-import { Link, useParams, useNavigate, useSearchParams } from "react-router-dom";
-import JSZip from "jszip";
+import { Link, useParams, useNavigate } from "react-router-dom";
 import { PageTransition } from "@/components/layout/PageTransition";
 import { Button } from "@/components/ui/Button";
-import { Modal } from "@/components/ui/Modal";
 import { Skeleton } from "@/components/ui/Skeleton";
 import { SkillPackagePreview } from "@/components/skill/SkillPackagePreview";
+import { useToastStore } from "@/stores/toastStore";
+import { isAdmin } from "@/stores/authStore";
 import { VersionPicker } from "@/components/skill/VersionPicker";
 import { DeprecationBanner } from "@/components/skill/DeprecationBanner";
 import { GitHubOriginChip } from "@/components/skill/GitHubOriginChip";
@@ -28,31 +27,23 @@ import { SkillInstallCard } from "@/components/skill/SkillInstallCard";
 import { UsagePullsCard } from "@/components/skill/UsagePullsCard";
 import { SkillHeroStrip } from "@/components/skill/SkillHeroStrip";
 import { BackLink } from "@/components/layout/BackLink";
-import { useRefreshSkillFromSource } from "@/hooks/useSkills";
-import { useStartAudit, useAuditSummaryByVersion, useSkillAuditHistory } from "@/hooks/useAudit";
-import { useSkillPulls } from "@/hooks/useAnalytics";
-import { SkillVersionList } from "@/components/skill/SkillVersionList";
 import { AgentSealTrustBadge } from "@/components/agentseal/AgentSealTrustBadge";
 import { PermissionsModal } from "@/components/skill/PermissionsModal";
 import { AdvancedOptionsModal } from "@/components/skill/AdvancedOptionsModal";
 import { VersionDiffModal } from "@/components/skill/VersionDiffModal";
+import { SkillSaveConfirmModal } from "@/components/skill/SkillSaveConfirmModal";
+import { SkillDeleteConfirmModal } from "@/components/skill/SkillDeleteConfirmModal";
+import { SkillAuditStartedModal } from "@/components/skill/SkillAuditStartedModal";
+import { SkillVersionsBrowserModal } from "@/components/skill/SkillVersionsBrowserModal";
+import { AuditVerdictPill } from "@/components/skill/AuditVerdictPill";
 import {
-  useSkill,
-  useDeleteSkill,
-  useDeleteSkillVersion,
-  useUpdateSkillPackage,
-  useSkillVersions,
-  useSetVersionDeprecation,
-} from "@/hooks/useSkills";
-import { useSkillPackage } from "@/hooks/useSkillPackage";
-import { useCurrentUser, useIsAuthenticated, isAdmin } from "@/stores/authStore";
-import { useToastStore } from "@/stores/toastStore";
-import { buildFileTreeFromEntries, type FileTreeEntry } from "@/utils/fileTreeBuilder";
-import { translateError } from "@/utils/translateError";
-import { track } from "@/lib/analytics";
+  SkillDetailLoading,
+  SkillDetailNotFound,
+} from "@/components/skill/SkillDetailStates";
+import { SkillVersionsCard } from "@/components/skill/SkillVersionsCard";
+import { SkillVisibilityCard } from "@/components/skill/SkillVisibilityCard";
+import { useSkillDetail } from "@/hooks/useSkillDetail";
 import { useTranslation } from "react-i18next";
-import type { FileNode } from "@/components/editor/FileTree";
-import type { AuditRecord } from "@/types/audit";
 
 /** Format a date string to exact SGT (Asia/Singapore) timestamp. */
 function formatDateSGT(dateStr: string): string {
@@ -68,330 +59,78 @@ function formatDateSGT(dateStr: string): string {
   });
 }
 
-/** Last-7-days ISO range, anchored to "now". */
-function rangeLast7d(): { from: string; to: string } {
-  const to = new Date();
-  const from = new Date(to.getTime() - 7 * 24 * 60 * 60 * 1000);
-  return { from: from.toISOString(), to: to.toISOString() };
-}
-
 export function SkillDetailPage() {
   const { idOrName } = useParams<{ idOrName: string }>();
+  const { t } = useTranslation();
   const navigate = useNavigate();
-  const [searchParams, setSearchParams] = useSearchParams();
   const addToast = useToastStore((s) => s.addToast);
-  const user = useCurrentUser();
-  const isAuthenticated = useIsAuthenticated();
-  const { t } = useTranslation();
-
-  const versionParam = searchParams.get("version") ?? undefined;
-  const { data: skill, isLoading, error, refetch } = useSkill(idOrName ?? "", versionParam);
-  const { data: versionList = [] } = useSkillVersions(idOrName ?? "");
-  const deleteMutation = useDeleteSkill();
-  const updatePackageMutation = useUpdateSkillPackage(skill?.guid ?? "");
-  const deprecationMutation = useSetVersionDeprecation(idOrName ?? "");
-  const deleteVersionMutation = useDeleteSkillVersion(idOrName ?? "");
-  const { data: auditSummaryByVersion } = useAuditSummaryByVersion(idOrName);
-  // History for the version currently being viewed, so the audit card
-  // can detect an in-flight (status: running) audit and show a loading
-  // state. The hook polls every 3s while any row is running.
-  const { data: versionAuditHistory } = useSkillAuditHistory(idOrName, {
-    version: versionParam,
-  });
-  const refreshMutation = useRefreshSkillFromSource(idOrName ?? "");
-  const startAuditMutation = useStartAudit();
+  const detail = useSkillDetail(idOrName);
 
-  // 7-day pulls totals — feeds the hero "↓ N pulls · 7d" status pill.
-  const last7d = useMemo(rangeLast7d, []);
-  const { data: pulls7d = [] } = useSkillPulls(skill?.name || skill?.guid, {
-    bucket: "day",
-    from: last7d.from,
-    to: last7d.to,
-    version: skill?.version,
-  });
-  const pullCount7d = useMemo(
-    () => pulls7d.reduce((acc, p) => acc + p.total, 0),
-    [pulls7d],
-  );
+  if (detail.isLoading) return <SkillDetailLoading />;
+  if (detail.error || !detail.skill) return <SkillDetailNotFound />;
 
+  // Aliases — keeps the JSX below readable without changing the prop
+  // wiring. Every name here came out of `useSkillDetail`; the hook is
+  // the single source of truth for queries + mutations + handlers.
   const {
-    files: packageFiles,
-    fileContents: packageContents,
+    skill,
+    refetch,
+    versionList,
+    latestVersion,
+    viewingLatest,
+    pullCount7d,
+    packageFiles,
     rawZip,
-    isLoading: packageLoading,
-    error: packageError,
-  } = useSkillPackage(skill?.presignedPackageUrl);
-
-  const isOwner = !!(isAuthenticated && user?.id && skill?.createdBy === user.id);
-  const isAdminUser = isAdmin(user);
-  const canManageVersions = isOwner || isAdminUser;
-
-  const latestVersion = versionList[0]?.version;
-  const viewingLatest = !versionParam || (latestVersion && versionParam === latestVersion);
-
-  const handleVersionChange = useCallback(
-    (versionOrLatest: string | null) => {
-      const next = new URLSearchParams(searchParams);
-      if (versionOrLatest === null) {
-        next.delete("version");
-      } else {
-        next.set("version", versionOrLatest);
-      }
-      setSearchParams(next, { replace: false });
-    },
-    [searchParams, setSearchParams],
-  );
-
-  const handleToggleDeprecation = useCallback(
-    async ({
-      version,
-      isDeprecated,
-      deprecationNote,
-    }: {
-      version: string;
-      isDeprecated: boolean;
-      deprecationNote?: string;
-    }) => {
-      try {
-        await deprecationMutation.mutateAsync({ version, isDeprecated, deprecationNote });
-        addToast({ type: "success", message: t("skillDetail.deprecationUpdated") });
-      } catch (err) {
-        const message = translateError(err, t("skillDetail.deprecationFailed"));
-        addToast({ type: "error", message });
-      }
-    },
-    [deprecationMutation, addToast, t],
-  );
-
-  const [showDeleteConfirm, setShowDeleteConfirm] = useState(false);
-  const [showPermissionsModal, setShowPermissionsModal] = useState(false);
-  const [showAdvancedModal, setShowAdvancedModal] = useState(false);
-  const [showSaveConfirm, setShowSaveConfirm] = useState(false);
-  const [showAuditStartedModal, setShowAuditStartedModal] = useState(false);
-  const [editedContents, setEditedContents] = useState<Map<string, string>>(new Map());
-  const [addedPaths, setAddedPaths] = useState<FileTreeEntry[]>([]);
-  const [deletedPaths, setDeletedPaths] = useState<Set<string>>(new Set());
-  const [skipValidation, setSkipValidation] = useState(false);
-  const [showVersions, setShowVersions] = useState(false);
-  const [showVersionDiff, setShowVersionDiff] = useState(false);
-  const hasChanges = editedContents.size > 0 || addedPaths.length > 0 || deletedPaths.size > 0;
-
-  // Reset version expansion when skill changes.
-  useEffect(() => {
-    setShowVersions(false);
-    setShowVersionDiff(false);
-  }, [skill?.guid]);
-
-  const handleContentChange = useCallback((fileId: string, content: string) => {
-    setEditedContents((prev) => {
-      const next = new Map(prev);
-      if (packageContents.get(fileId) === content && !addedPaths.some((e) => e.path === fileId)) {
-        next.delete(fileId);
-      } else {
-        next.set(fileId, content);
-      }
-      return next;
-    });
-  }, [packageContents, addedPaths]);
-
-  const handleCreateFile = useCallback((parentId: string | null, name: string) => {
-    const path = parentId ? `${parentId}/${name}` : name;
-    setAddedPaths((prev) => [...prev, { path, type: "file", viewable: true, size: 0 }]);
-    setEditedContents((prev) => new Map(prev).set(path, ""));
-  }, []);
-
-  const handleCreateFolder = useCallback((parentId: string | null, name: string) => {
-    const path = parentId ? `${parentId}/${name}` : name;
-    setAddedPaths((prev) => [...prev, { path, type: "folder", viewable: false, size: 0 }]);
-  }, []);
-
-  const handleDeleteFile = useCallback((fileId: string) => {
-    const prefix = fileId + "/";
-    const isAdded = addedPaths.some((e) => e.path === fileId || e.path.startsWith(prefix));
-
-    if (isAdded) {
-      setAddedPaths((prev) => prev.filter((e) => e.path !== fileId && !e.path.startsWith(prefix)));
-      setEditedContents((prev) => {
-        const next = new Map(prev);
-        for (const key of next.keys()) {
-          if (key === fileId || key.startsWith(prefix)) next.delete(key);
-        }
-        return next;
-      });
-    } else {
-      setDeletedPaths((prev) => {
-        const next = new Set(prev);
-        next.add(fileId);
-        for (const key of packageContents.keys()) {
-          if (key.startsWith(prefix)) next.add(key);
-        }
-        return next;
-      });
-      setEditedContents((prev) => {
-        const next = new Map(prev);
-        for (const key of next.keys()) {
-          if (key === fileId || key.startsWith(prefix)) next.delete(key);
-        }
-        return next;
-      });
-    }
-  }, [addedPaths, packageContents]);
-
-  const mergedContents = useMemo(() => {
-    const merged = new Map(packageContents);
-    for (const path of deletedPaths) merged.delete(path);
-    for (const [path, content] of editedContents) merged.set(path, content);
-    return merged;
-  }, [packageContents, editedContents, deletedPaths]);
-
-  const mergedFiles = useMemo(() => {
-    if (addedPaths.length === 0 && deletedPaths.size === 0) return packageFiles;
-    const entries: FileTreeEntry[] = [];
-    function collectEntries(nodes: FileNode[]) {
-      for (const node of nodes) {
-        if (deletedPaths.has(node.id)) continue;
-        entries.push({
-          path: node.id,
-          type: node.type,
-          viewable: node.type === "file",
-          size: 0,
-        });
-        if (node.children) collectEntries(node.children);
-      }
-    }
-    collectEntries(packageFiles);
-    for (const entry of addedPaths) entries.push(entry);
-    return buildFileTreeFromEntries(entries);
-  }, [packageFiles, addedPaths, deletedPaths]);
-
-  const handleSave = async (skip: boolean) => {
-    if (!skill) return;
-    setShowSaveConfirm(false);
-    try {
-      const newZip = new JSZip();
-      if (rawZip) {
-        for (const [path, entry] of Object.entries(rawZip.files)) {
-          if (entry.dir) continue;
-          if (deletedPaths.has(path)) continue;
-          if (editedContents.has(path)) {
-            newZip.file(path, editedContents.get(path)!);
-          } else {
-            const data = await entry.async("uint8array");
-            newZip.file(path, data);
-          }
-        }
-      }
-      for (const entry of addedPaths) {
-        if (entry.type === "file" && editedContents.has(entry.path)) {
-          newZip.file(entry.path, editedContents.get(entry.path)!);
-        }
-      }
-      const blob = await newZip.generateAsync({ type: "blob" });
-      const zipFile = new File([blob], `${skill.name}.zip`, { type: "application/zip" });
-      await updatePackageMutation.mutateAsync({ zipFile, skipValidation: skip });
-      track("skill.version_published", {
-        skillId: skill.guid,
-        skipValidation: skip,
-      });
-      addToast({ type: "success", message: t("skillDetail.updateSuccess") });
-      setEditedContents(new Map());
-      setAddedPaths([]);
-      setDeletedPaths(new Set());
-      refetch();
-    } catch (err) {
-      const message = translateError(err, t("skillDetail.saveFailed"));
-      addToast({ type: "error", message });
-    }
-  };
-
-  const handleDeleteConfirm = async () => {
-    if (!skill) return;
-    try {
-      await deleteMutation.mutateAsync(skill.guid);
-      addToast({ type: "success", message: t("skillDetail.deleteSuccess") });
-      navigate("/registry");
-    } catch {
-      addToast({ type: "error", message: t("skillDetail.deleteFailed") });
-    } finally {
-      setShowDeleteConfirm(false);
-    }
-  };
-
-  const handleDownloadPackage = useCallback(async () => {
-    if (!skill || !rawZip) return;
-    const blob = await rawZip.generateAsync({ type: "blob" });
-    const url = URL.createObjectURL(blob);
-    const a = document.createElement("a");
-    a.href = url;
-    a.download = `${skill.name}.zip`;
-    a.click();
-    URL.revokeObjectURL(url);
-  }, [skill, rawZip]);
-
-  const handleStartAudit = useCallback(() => {
-    if (!skill) return;
-    setShowAuditStartedModal(true);
-    startAuditMutation.mutate(
-      { idOrName: skill.name || skill.guid, force: true },
-      {
-        onSuccess: (record) => {
-          addToast({
-            type: "success",
-            message: t(
-              "skillDetail.auditDone",
-              "Audit complete — verdict {{v}}, score {{s}}/10",
-              { v: record.verdict, s: record.overallScore.toFixed(1) },
-            ),
-          });
-        },
-        onError: (err) => {
-          addToast({
-            type: "error",
-            message: translateError(err),
-          });
-        },
-      },
-    );
-  }, [skill, startAuditMutation, addToast, t]);
-
-  if (isLoading) {
-    return (
-      <PageTransition>
-        <div className="flex h-full items-center justify-center">
-          <Skeleton lines={10} />
-        </div>
-      </PageTransition>
-    );
-  }
-
-  if (error || !skill) {
-    return (
-      <PageTransition>
-        <div className="flex h-full items-center justify-center">
-          <div className="text-center">
-            <h2 className="mb-2 font-display text-2xl text-danger">{t("skillDetail.notFound")}</h2>
-            <p className="text-meta">{t("skillDetail.notFoundDesc")}</p>
-            <Button onClick={() => navigate("/registry")} className="mt-6">
-              {t("skillDetail.backToExplore")}
-            </Button>
-          </div>
-        </div>
-      </PageTransition>
-    );
-  }
-
-  const versionAudit = auditSummaryByVersion?.[skill.version];
-  // Detect an in-flight audit on the current version so the right-rail
-  // Audit card can swap to a "running" loading tile. The history hook
-  // already polls every 3s while any row is running, so the UI flips
-  // back to the verdict tile automatically once the LLM finishes.
-  const versionAuditRunning =
-    versionAuditHistory?.some((r) => r.status === "running") ?? false;
-  const ownerDisplayName =
-    isOwner && user?.displayName
-      ? user.displayName
-      : skill.createdByDisplayName || skill.createdByEmail || skill.createdBy;
-  const ownerAvatarUrl = isOwner ? user?.avatarUrl : null;
+    packageLoading,
+    packageError,
+    user,
+    isAuthenticated,
+    isOwner,
+    isAdminUser,
+    canManageVersions,
+    auditSummaryByVersion,
+    versionAudit,
+    versionAuditRunning,
+    versionAuditLatestFailed,
+    ownerDisplayName,
+    ownerAvatarUrl,
+    deleteMutation,
+    updatePackageMutation,
+    deprecationMutation,
+    deleteVersionMutation,
+    refreshMutation,
+    startAuditMutation,
+    showDeleteConfirm,
+    setShowDeleteConfirm,
+    showPermissionsModal,
+    setShowPermissionsModal,
+    showAdvancedModal,
+    setShowAdvancedModal,
+    showSaveConfirm,
+    setShowSaveConfirm,
+    showAuditStartedModal,
+    setShowAuditStartedModal,
+    showVersions,
+    setShowVersions,
+    showVersionDiff,
+    setShowVersionDiff,
+    skipValidation,
+    setSkipValidation,
+    addedPaths,
+    hasChanges,
+    mergedContents,
+    mergedFiles,
+    handleVersionChange,
+    handleToggleDeprecation,
+    handleContentChange,
+    handleCreateFile,
+    handleCreateFolder,
+    handleDeleteFile,
+    handleSave,
+    handleDeleteConfirm,
+    handleDownloadPackage,
+    handleStartAudit,
+  } = detail;
 
   return (
     <PageTransition>
@@ -572,7 +311,11 @@ export function SkillDetailPage() {
                 <svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden><path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z" /></svg>
                 {t("skillDetail.cardAudit", "Audit")}
               </h3>
-              <AuditVerdictPill audit={versionAudit} running={versionAuditRunning} />
+              <AuditVerdictPill
+                audit={versionAudit}
+                running={versionAuditRunning}
+                latestRerunFailed={versionAuditLatestFailed}
+              />
               <p className="font-mono text-[11px] leading-relaxed tracking-wide text-meta">
                 {versionAuditRunning
                   ? t("skillDetail.auditRunningHint", "Scoring against the audit engine — this usually takes 30–60 seconds.")
@@ -620,131 +363,23 @@ export function SkillDetailPage() {
 
             {/* ── Versions card ── */}
             {versionList.length > 0 && (
-              <section className="rounded-md border border-subtle bg-card p-5 card-impression">
-                <h3 className="mb-3.5 flex items-center gap-2 border-b border-dashed border-subtle pb-3 font-mono text-[10px] font-semibold uppercase tracking-[0.18em] text-meta">
-                  <svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden>
-                    <path d="M21 16V8a2 2 0 0 0-1-1.7l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.7l7 4a2 2 0 0 0 2 0l7-4a2 2 0 0 0 1-1.7z" />
-                    <polyline points="3.27 6.96 12 12.01 20.73 6.96" />
-                    <line x1="12" y1="22.08" x2="12" y2="12" />
-                  </svg>
-                  {t("skillDetail.cardVersions", "Versions")}
-                </h3>
-                <div className="mb-1.5 flex items-baseline gap-2">
-                  <span className="font-display text-2xl font-semibold tracking-tight text-strong">
-                    {skill.version}
-                  </span>
-                  {viewingLatest && (
-                    <span className="rounded-sm border border-accent/40 px-1.5 py-0.5 font-mono text-[9px] uppercase tracking-[0.16em] text-accent">
-                      {t("skillDetail.latest", "latest")}
-                    </span>
-                  )}
-                </div>
-                <p className="font-mono text-[11px] leading-relaxed tracking-wide text-meta">
-                  {t("skillDetail.heroPublishedOn", "Published {{date}}", { date: formatDateSGT(skill.createdOn) })}
-                  {versionList.length > 1 && (
-                    <>
-                      {" · "}
-                      {t("skillDetail.versionsTotal", "{{n}} versions total", { n: versionList.length })}
-                    </>
-                  )}
-                </p>
-                <div className="mt-3.5 flex flex-col gap-2">
-                  <button
-                    type="button"
-                    onClick={() => setShowVersions(true)}
-                    className="inline-flex items-center gap-1 self-start py-1 font-mono text-[10px] uppercase tracking-widest text-accent transition-all hover:text-accent-muted hover:gap-2"
-                  >
-                    {t("skillDetail.browseVersions", "Browse all versions")} →
-                  </button>
-                </div>
-              </section>
+              <SkillVersionsCard
+                currentVersion={skill.version}
+                publishedOnSGT={formatDateSGT(skill.createdOn)}
+                totalVersions={versionList.length}
+                viewingLatest={Boolean(viewingLatest)}
+                onBrowseAll={() => setShowVersions(true)}
+              />
             )}
 
             {/* ── Visibility card ── */}
-            <section className="rounded-md border border-subtle bg-card p-5 card-impression">
-              <h3 className="mb-3.5 flex items-center gap-2 border-b border-dashed border-subtle pb-3 font-mono text-[10px] font-semibold uppercase tracking-[0.18em] text-meta">
-                <svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden>
-                  <circle cx="12" cy="12" r="9" /><line x1="3" y1="12" x2="21" y2="12" />
-                  <path d="M12 3a14 14 0 0 1 4 9 14 14 0 0 1-4 9 14 14 0 0 1-4-9 14 14 0 0 1 4-9z" />
-                </svg>
-                {t("skillDetail.cardVisibility", "Visibility")}
-              </h3>
-              {(() => {
-                // Visibility ladder:
-                //   public  — `isPrivate: false`
-                //   limited — `isPrivate: true` AND at least one explicit
-                //             grant (user or org)
-                //   private — `isPrivate: true` AND no grants — only the
-                //             author + platform admins can see it.
-                const hasGrants =
-                  skill.sharedWithUsers.length > 0 || skill.sharedWithOrgs.length > 0;
-                const tier: "public" | "limited" | "private" = !skill.isPrivate
-                  ? "public"
-                  : hasGrants
-                    ? "limited"
-                    : "private";
-                const tierClass: Record<typeof tier, string> = {
-                  public: "border-success/40 bg-success-soft text-success",
-                  limited: "border-warning/40 bg-warning-soft text-warning",
-                  private: "border-info/40 bg-info-soft text-info",
-                };
-                const tierLabel: Record<typeof tier, string> = {
-                  public: t("common.public", "Public"),
-                  limited: t("common.limited", "Limited access"),
-                  private: t("common.private", "Private"),
-                };
-                return (
-                  <span
-                    className={`mb-3 inline-flex items-center gap-1.5 rounded-sm border px-2.5 py-1 font-mono text-[11px] uppercase tracking-wider ${tierClass[tier]}`}
-                  >
-                    <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
-                      {tier === "public" ? (
-                        <>
-                          <circle cx="12" cy="12" r="9" />
-                          <line x1="3" y1="12" x2="21" y2="12" />
-                        </>
-                      ) : tier === "limited" ? (
-                        <>
-                          <path d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2" />
-                          <circle cx="9" cy="7" r="4" />
-                          <path d="M23 21v-2a4 4 0 0 0-3-3.87" />
-                          <path d="M16 3.13a4 4 0 0 1 0 7.75" />
-                        </>
-                      ) : (
-                        <path d="M12 2a5 5 0 0 0-5 5v3H5a2 2 0 0 0-2 2v8a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-8a2 2 0 0 0-2-2h-2V7a5 5 0 0 0-5-5z" />
-                      )}
-                    </svg>
-                    {tierLabel[tier]}
-                  </span>
-                );
-              })()}
-              <ul className="space-y-1.5 font-text text-sm text-body">
-                <li className="flex items-baseline gap-2.5">
-                  <span className="min-w-[18px] text-right font-mono text-sm font-semibold text-strong">
-                    {skill.sharedWithUsers.length}
-                  </span>
-                  <span className="text-xs text-meta">{t("skillDetail.shareUsers", "users")}</span>
-                </li>
-                <li className="flex items-baseline gap-2.5">
-                  <span className="min-w-[18px] text-right font-mono text-sm font-semibold text-strong">
-                    {skill.sharedWithOrgs.length}
-                  </span>
-                  <span className="text-xs text-meta">{t("skillDetail.shareOrgs", "organizations")}</span>
-                </li>
-              </ul>
-              {isOwner && (
-                <div className="mt-3.5">
-                  <Button
-                    variant="secondary"
-                    size="sm"
-                    className="w-full"
-                    onClick={() => setShowPermissionsModal(true)}
-                  >
-                    {t("skillDetail.managePermissions", "Manage permissions")}
-                  </Button>
-                </div>
-              )}
-            </section>
+            <SkillVisibilityCard
+              isPrivate={skill.isPrivate}
+              sharedWithUsersCount={skill.sharedWithUsers.length}
+              sharedWithOrgsCount={skill.sharedWithOrgs.length}
+              isOwner={isOwner}
+              onManagePermissions={() => setShowPermissionsModal(true)}
+            />
 
             {/* ── Advanced options ── click-to-open card. Settings UI
                 lives in `AdvancedOptionsModal` (settings-page-style:
@@ -916,95 +551,36 @@ export function SkillDetailPage() {
       </div>
 
       {/* ── Save confirmation modal ── */}
-      <Modal
+      <SkillSaveConfirmModal
         isOpen={showSaveConfirm}
         onClose={() => setShowSaveConfirm(false)}
-        title={t("skillDetail.saveChanges")}
-      >
-        <p className="mb-4 font-text text-sm text-meta">
-          {t("skillDetail.saveConfirm", { name: skill.name })}
-        </p>
-        <label className="flex cursor-pointer items-center gap-3 rounded-sm border border-subtle bg-elevated p-3 select-none">
-          <button
-            type="button"
-            role="switch"
-            aria-checked={skipValidation}
-            onClick={() => setSkipValidation((v) => !v)}
-            className={`relative inline-flex h-5 w-9 shrink-0 cursor-pointer rounded-full border-2 border-transparent transition-colors ${
-              skipValidation ? "bg-accent" : "bg-elevated"
-            }`}
-          >
-            <span
-              className={`pointer-events-none inline-block h-4 w-4 rounded-full bg-white shadow transition-transform ${
-                skipValidation ? "translate-x-4" : "translate-x-0"
-              }`}
-            />
-          </button>
-          <div>
-            <p className="font-text text-sm text-strong">{t("skillDetail.skipValidation")}</p>
-            <p className="font-text text-xs text-meta">{t("skillDetail.skipDescription")}</p>
-          </div>
-        </label>
-        <div className="mt-6 flex justify-end gap-3">
-          <Button variant="secondary" size="sm" onClick={() => setShowSaveConfirm(false)}>
-            {t("common.cancel")}
-          </Button>
-          <Button size="sm" onClick={() => handleSave(skipValidation)} loading={updatePackageMutation.isPending}>
-            {t("common.save")}
-          </Button>
-        </div>
-      </Modal>
+        skillName={skill.name}
+        skipValidation={skipValidation}
+        onSkipValidationChange={setSkipValidation}
+        onConfirm={() => handleSave(skipValidation)}
+        saving={updatePackageMutation.isPending}
+      />
 
       {/* ── All versions browser ── */}
-      <Modal
+      <SkillVersionsBrowserModal
         isOpen={showVersions}
         onClose={() => setShowVersions(false)}
-        title={t("skillDetail.versionsTitle", "All versions") as string}
-        className="!max-w-3xl"
-      >
-        {versionList.length >= 2 && (
-          <div className="mb-4 flex justify-end">
-            <Button
-              variant="secondary"
-              size="sm"
-              onClick={() => setShowVersionDiff(true)}
-            >
-              {t("versionDiff.openButton", "Compare versions")}
-            </Button>
-          </div>
-        )}
-        <SkillVersionList
-          versions={versionList}
-          currentVersion={skill.version}
-          onSelect={(v) => {
-            handleVersionChange(v === latestVersion ? null : v);
-            setShowVersions(false);
-          }}
-          canManage={canManageVersions}
-          onToggleDeprecation={handleToggleDeprecation}
-          isMutating={deprecationMutation.isPending}
-          isDeleting={deleteVersionMutation.isPending}
-          auditSummary={auditSummaryByVersion}
-          onDeleteVersion={async (version) => {
-            try {
-              await deleteVersionMutation.mutateAsync(version);
-              if (skill.version === version) handleVersionChange(null);
-              addToast({
-                type: "success",
-                message: t("skillDetail.versionDeleted", "Version v{{version}} deleted", { version }),
-              });
-            } catch (err) {
-              addToast({
-                type: "error",
-                message: translateError(
-                  err,
-                  t("skillDetail.versionDeleteFailed", "Failed to delete version"),
-                ),
-              });
-            }
-          }}
-        />
-      </Modal>
+        versions={versionList}
+        currentVersion={skill.version}
+        // `latestVersion` is `versionList[0]?.version`; modal only
+        // opens when versionList is non-empty so the value is set,
+        // but `?? ""` keeps the prop signature simple under
+        // noUncheckedIndexedAccess (#450).
+        latestVersion={latestVersion ?? ""}
+        canManage={canManageVersions}
+        auditSummary={auditSummaryByVersion}
+        onSelectVersion={handleVersionChange}
+        onToggleDeprecation={handleToggleDeprecation}
+        deprecationPending={deprecationMutation.isPending}
+        deleteVersionPending={deleteVersionMutation.isPending}
+        deleteVersionAsync={(v) => deleteVersionMutation.mutateAsync(v)}
+        onOpenDiff={() => setShowVersionDiff(true)}
+      />
 
       {/* ── Version diff modal ── */}
       <VersionDiffModal
@@ -1016,23 +592,13 @@ export function SkillDetailPage() {
       />
 
       {/* ── Delete confirmation modal ── */}
-      <Modal
+      <SkillDeleteConfirmModal
         isOpen={showDeleteConfirm}
         onClose={() => setShowDeleteConfirm(false)}
-        title={t("skillDetail.deleteTitle")}
-      >
-        <p className="font-text text-sm text-meta">
-          {t("skillDetail.deleteConfirm", { name: skill.name }).replace(/<\/?strong>/g, "")}
-        </p>
-        <div className="mt-6 flex justify-end gap-3">
-          <Button variant="secondary" size="sm" onClick={() => setShowDeleteConfirm(false)}>
-            {t("common.cancel")}
-          </Button>
-          <Button variant="danger" size="sm" onClick={handleDeleteConfirm} loading={deleteMutation.isPending}>
-            {t("common.delete")}
-          </Button>
-        </div>
-      </Modal>
+        skillName={skill.name}
+        onConfirm={handleDeleteConfirm}
+        deleting={deleteMutation.isPending}
+      />
 
       {/* ── Permissions editor ── */}
       {isOwner && (
@@ -1053,81 +619,12 @@ export function SkillDetailPage() {
       )}
 
       {/* ── Audit started modal ── */}
-      <Modal
+      <SkillAuditStartedModal
         isOpen={showAuditStartedModal}
         onClose={() => setShowAuditStartedModal(false)}
-        title={t("skillDetail.auditStartedTitle", "Audit started") as string}
-      >
-        <p className="font-text text-sm text-meta">
-          {t(
-            "skillDetail.auditStartedBody",
-            "We're running the audit in the background. It takes around 20-30 seconds — when it's done, a new entry will appear in the Audit history. You can close this dialog and keep working.",
-          )}
-        </p>
-        <div className="mt-6 flex justify-end">
-          <Button size="sm" onClick={() => setShowAuditStartedModal(false)}>
-            {t("common.gotIt", "Got it")}
-          </Button>
-        </div>
-      </Modal>
+      />
 
       </div>
     </PageTransition>
   );
 }
-
-/** Audit verdict tile rendered inside the right-rail Audit card. */
-function AuditVerdictPill({ audit, running }: { audit?: AuditRecord; running?: boolean }) {
-  const { t } = useTranslation();
-  // In-flight audit takes precedence over the cached completed result —
-  // even if there's a previous completed verdict on this version, surface
-  // the spinner while a new run is scoring.
-  if (running) {
-    return (
-      <div className="mb-3.5 flex items-center gap-3 rounded-sm border border-accent/30 bg-accent/5 p-3 font-mono text-[11px] uppercase tracking-wider text-accent">
-        <div className="flex h-8 w-8 items-center justify-center rounded-sm border border-accent/30" aria-hidden>
-          <span className="h-4 w-4 animate-spin rounded-full border-2 border-accent/30 border-t-accent" />
-        </div>
-        <span>{t("skillDetail.auditRunning", "Audit in progress")}</span>
-      </div>
-    );
-  }
-  if (!audit || audit.status !== "completed") {
-    return (
-      <div className="mb-3.5 flex items-center gap-3 rounded-sm border border-strong-edge bg-elevated/60 p-3 font-mono text-[11px] uppercase tracking-wider text-meta">
-        <div className="flex h-8 w-8 items-center justify-center rounded-sm border border-strong-edge text-meta" aria-hidden>
-          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2"><circle cx="12" cy="12" r="9" /></svg>
-        </div>
-        <span>{t("skillDetail.auditNone", "Not audited")}</span>
-      </div>
-    );
-  }
-  const tone =
-    audit.verdict === "green"
-      ? "border-success/30 bg-success-soft text-success"
-      : audit.verdict === "yellow"
-        ? "border-warning/30 bg-warning-soft text-warning"
-        : "border-danger/30 bg-danger-soft text-danger";
-  const label =
-    audit.verdict === "green"
-      ? t("skillDetail.auditPassLabel", "Pass · low risk")
-      : audit.verdict === "yellow"
-        ? t("skillDetail.auditWarnLabel", "Caution")
-        : t("skillDetail.auditFailLabel", "Risk");
-  return (
-    <div className={`mb-3.5 flex items-center gap-3 rounded-sm border p-3 ${tone}`}>
-      <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-sm bg-current text-page" aria-hidden>
-        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="3"><polyline points="20 6 9 17 4 12" /></svg>
-      </div>
-      <div className="flex flex-col gap-0.5">
-        <div>
-          <span className="font-display text-2xl font-semibold leading-none">
-            {audit.overallScore.toFixed(1)}
-          </span>
-          <span className="ml-1 font-mono text-[11px] tracking-wide text-meta">/ 10</span>
-        </div>
-        <span className="font-mono text-[10px] uppercase tracking-[0.14em]">{label}</span>
-      </div>
-    </div>
-  );
-}
diff --git a/ornn-web/src/pages/skill/UploadSkillPage.tsx b/ornn-web/src/pages/skill/UploadSkillPage.tsx
index 1d680010..2cbfa151 100644
--- a/ornn-web/src/pages/skill/UploadSkillPage.tsx
+++ b/ornn-web/src/pages/skill/UploadSkillPage.tsx
@@ -204,7 +204,14 @@ export function UploadSkillPage() {
                         {t(card.titleKey)}
                       </h2>
 
-                      <p className="font-text text-sm sm:text-base text-meta mb-4 sm:mb-6">
+                      {/*
+                        Fixed min-height so the bullet list below starts
+                        on the same vertical baseline across all four
+                        cards regardless of description length (#725).
+                        The Free Mode description is ~1 line; Generative
+                        and GitHub spill to ~2 lines on common viewports.
+                      */}
+                      <p className="font-text text-sm sm:text-base text-meta mb-4 sm:mb-6 min-h-[3rem] sm:min-h-[3.5rem]">
                         {t(card.descKey)}
                       </p>
 
diff --git a/ornn-web/src/services/activityApi.ts b/ornn-web/src/services/activityApi.ts
index a264f17d..2bbd4580 100644
--- a/ornn-web/src/services/activityApi.ts
+++ b/ornn-web/src/services/activityApi.ts
@@ -6,15 +6,10 @@
 
 import { useAuthStore } from "@/stores/authStore";
 import { config } from "@/config";
+import { createLogger } from "@/lib/logger";
 
 const API_BASE = config.apiBaseUrl;
-
-const logger = {
-  info: (msg: string, data?: Record<string, unknown>) =>
-    console.log(`[activityApi] ${msg}`, data ?? ""),
-  warn: (msg: string, data?: Record<string, unknown>) =>
-    console.warn(`[activityApi] ${msg}`, data ?? ""),
-};
+const logger = createLogger("activityApi");
 
 /**
  * Log a user activity (login or logout).
@@ -22,27 +17,37 @@ const logger = {
  */
 export async function logActivity(action: "login" | "logout"): Promise<void> {
   try {
-    const { accessToken, user } = useAuthStore.getState();
+    const { accessToken } = useAuthStore.getState();
     if (!accessToken) {
       logger.warn("No access token, skipping activity log", { action });
       return;
     }
 
+    // #528 — `X-User-Email` / `X-User-Display-Name` used to ride along
+    // here. They were stripped by the NyxID proxy and never read by
+    // the backend (identity is sourced from the proxy-forwarded
+    // identity token), but the backend CORS allowlist doesn't include
+    // them — sending them tripped a preflight-blocked-by-CORS failure
+    // on every login. Same dead code as the `apiClient.createHeaders`
+    // cleanup; this caller was missed in the original sweep.
+    //
+    // #709 — `credentials: "include"` was a second preflight trap.
+    // The Bearer token already authenticates the request; no cookies
+    // ride this endpoint and the rest of the SPA's `apiClient` calls
+    // never set `credentials`. With `include`, the browser demanded
+    // `Access-Control-Allow-Credentials: true` + a specific (non-*)
+    // `Access-Control-Allow-Origin` on the preflight response — which
+    // the NyxID proxy doesn't return for this endpoint — and blocked
+    // the POST. Dropping it brings this call in line with the rest of
+    // the SPA and the preflight succeeds.
     const headers: HeadersInit = {
       "Content-Type": "application/json",
       Authorization: `Bearer ${accessToken}`,
     };
-    if (user?.email) {
-      headers["X-User-Email"] = user.email;
-    }
-    if (user?.displayName) {
-      headers["X-User-Display-Name"] = user.displayName;
-    }
 
     const res = await fetch(`${API_BASE}/api/v1/activity/${action}`, {
       method: "POST",
       headers,
-      credentials: "include",
     });
 
     if (!res.ok) {
diff --git a/ornn-web/src/services/adminUsersApi.ts b/ornn-web/src/services/adminUsersApi.ts
index a2ed621f..29532983 100644
--- a/ornn-web/src/services/adminUsersApi.ts
+++ b/ornn-web/src/services/adminUsersApi.ts
@@ -49,10 +49,11 @@ export interface AdminUsersPage {
 
 export async function fetchAdminUsers(params: {
   role: AdminUserRole;
-  q?: string;
-  page?: number;
-  pageSize?: number;
-  sort?: AdminUsersSort;
+  // exactOptionalPropertyTypes (#657)
+  q?: string | undefined;
+  page?: number | undefined;
+  pageSize?: number | undefined;
+  sort?: AdminUsersSort | undefined;
 }): Promise<AdminUsersPage> {
   // Backend takes `sort` (field) and `dir` (asc|desc) as two separate
   // query params. Frontend stores them as one `field:dir` value for
diff --git a/ornn-web/src/services/analyticsApi.ts b/ornn-web/src/services/analyticsApi.ts
index 2611a7f6..06ae076d 100644
--- a/ornn-web/src/services/analyticsApi.ts
+++ b/ornn-web/src/services/analyticsApi.ts
@@ -14,9 +14,10 @@ import type {
 } from "@/types/analytics";
 
 export interface FetchAnalyticsOptions {
-  window?: AnalyticsWindow;
+  // Optionals widen for exactOptionalPropertyTypes (#657).
+  window?: AnalyticsWindow | undefined;
   /** Optional version filter; matches the same query the backend supports. */
-  version?: string;
+  version?: string | undefined;
 }
 
 export async function fetchSkillAnalytics(
@@ -35,11 +36,12 @@ export async function fetchSkillAnalytics(
 
 export interface FetchPullsOptions {
   bucket: PullBucket;
+  // Optionals widen for exactOptionalPropertyTypes (#657).
   /** Inclusive lower bound (ISO string). Backend defaults to last 7 days. */
-  from?: string;
+  from?: string | undefined;
   /** Exclusive upper bound (ISO string). Backend defaults to now. */
-  to?: string;
-  version?: string;
+  to?: string | undefined;
+  version?: string | undefined;
 }
 
 export async function fetchSkillPulls(
diff --git a/ornn-web/src/services/apiClient.ts b/ornn-web/src/services/apiClient.ts
index c95a4b98..4742e734 100644
--- a/ornn-web/src/services/apiClient.ts
+++ b/ornn-web/src/services/apiClient.ts
@@ -8,12 +8,9 @@
 import type { ApiResponse } from "@/types/api";
 import { useAuthStore } from "@/stores/authStore";
 import { config } from "@/config";
+import { createLogger } from "@/lib/logger";
 
-const logger = {
-  error: (msg: string, data?: Record<string, unknown>) =>
-    console.error(`[apiClient] ${msg}`, data ?? ""),
-};
-
+const logger = createLogger("apiClient");
 const API_BASE = config.apiBaseUrl;
 
 /**
@@ -119,17 +116,51 @@ async function handleResponse<T>(response: Response): Promise<ApiResponse<T>> {
     return { data: null, error: null };
   }
 
-  const json = (await response.json()) as ApiResponse<T>;
+  const json = (await response.json()) as unknown;
 
-  if (!response.ok || json.error) {
+  if (!response.ok) {
+    // Two error body shapes are observed on non-2xx responses:
+    //
+    //   1. RFC 7807 `application/problem+json` (#456) — `{ code, detail,
+    //      title, status }` at the body root. Newer endpoints emit this.
+    //   2. Legacy `{ data: null, error: { code, message } }` envelope.
+    //      Several domain routes (LLM provider sync, settings validation)
+    //      still throw via `AppError → buildErrorEnvelope` which keeps
+    //      this shape with a non-2xx status, and #694 surfaced that the
+    //      frontend was discarding their actionable `error.message`.
+    //
+    // Try the envelope first because `error.message` is the most
+    // actionable when present; fall back to RFC 7807 fields; final
+    // fallback is the generic literal.
+    const body = (json ?? {}) as {
+      code?: string;
+      detail?: string;
+      title?: string;
+      status?: number;
+      error?: { code?: string; message?: string };
+    };
+    const envelopeCode = body.error?.code;
+    const envelopeMessage = body.error?.message;
     throw new ApiClientError(
-      json.error?.code ?? "UNKNOWN_ERROR",
-      json.error?.message ?? "An unexpected error occurred",
-      response.status,
+      envelopeCode ?? body.code ?? "unknown_error",
+      envelopeMessage ??
+        body.detail ??
+        body.title ??
+        "An unexpected error occurred",
+      body.status ?? response.status,
     );
   }
 
-  return json;
+  // Success: legacy `{ data, error: null }` envelope (unchanged).
+  const envelope = json as ApiResponse<T>;
+  if (envelope?.error) {
+    throw new ApiClientError(
+      envelope.error.code ?? "unknown_error",
+      envelope.error.message ?? "An unexpected error occurred",
+      response.status,
+    );
+  }
+  return envelope;
 }
 
 /**
@@ -258,53 +289,17 @@ export async function apiPatch<T>(
 
 /**
  * DELETE request with auth.
+ *
+ * Routes through `fetchWithRetry` (#578) so the proactive-refresh /
+ * 401-retry / redirect-to-login logic stays in one place. The DELETE
+ * response is discarded — most ornn-api DELETEs return 204, and the
+ * caller only cares about success vs. an `ApiClientError`.
  */
 export async function apiDelete(path: string): Promise<void> {
-  // Proactively refresh expired tokens before sending
-  if (getAccessToken()) {
-    await useAuthStore.getState().ensureFreshToken();
-  }
-
-  const response = await fetch(buildUrl(path), {
+  await fetchWithRetry<unknown>(buildUrl(path), {
     method: "DELETE",
     headers: createHeaders(),
   });
-
-  // Handle 401 (not 403 — token refresh cannot resolve permission errors).
-  if (response.status === 401) {
-    const refreshSuccess = await attemptTokenRefresh();
-
-    if (refreshSuccess) {
-      const retryResponse = await fetch(buildUrl(path), {
-        method: "DELETE",
-        headers: createHeaders(),
-      });
-
-      if (!retryResponse.ok) {
-        const json = await retryResponse.json().catch(() => null);
-        throw new ApiClientError(
-          (json as ApiResponse<unknown>)?.error?.code ?? "DELETE_FAILED",
-          (json as ApiResponse<unknown>)?.error?.message ?? "Delete failed",
-          retryResponse.status,
-        );
-      }
-      return;
-    }
-
-    logger.error("Token refresh failed during DELETE, redirecting to login");
-    if (typeof window !== "undefined") {
-      window.location.href = "/login";
-    }
-  }
-
-  if (!response.ok) {
-    const json = await response.json().catch(() => null);
-    throw new ApiClientError(
-      (json as ApiResponse<unknown>)?.error?.code ?? "DELETE_FAILED",
-      (json as ApiResponse<unknown>)?.error?.message ?? "Delete failed",
-      response.status,
-    );
-  }
 }
 
 export { ApiClientError as ApiError };
diff --git a/ornn-web/src/services/auditApi.ts b/ornn-web/src/services/auditApi.ts
index 0e74d881..aeee774f 100644
--- a/ornn-web/src/services/auditApi.ts
+++ b/ornn-web/src/services/auditApi.ts
@@ -31,7 +31,7 @@ export async function fetchAudit(
     );
     return res.data ?? null;
   } catch (err) {
-    if (err instanceof ApiClientError && err.code === "AUDIT_NOT_FOUND") {
+    if (err instanceof ApiClientError && err.code === "audit_not_found") {
       return null;
     }
     throw err;
@@ -60,7 +60,8 @@ export async function fetchAuditSummaryByVersion(
  */
 export async function fetchAuditHistory(
   idOrName: string,
-  options: { version?: string } = {},
+  // exactOptionalPropertyTypes (#657)
+  options: { version?: string | undefined } = {},
 ): Promise<AuditRecord[]> {
   const params: Record<string, string | undefined> = {};
   if (options.version) params.version = options.version;
@@ -73,8 +74,9 @@ export async function fetchAuditHistory(
 
 export interface StartAuditInput {
   idOrName: string;
+  // exactOptionalPropertyTypes (#657)
   /** Bypass the 30-day audit cache. Default false — most callers want the cache. */
-  force?: boolean;
+  force?: boolean | undefined;
 }
 
 /**
diff --git a/ornn-web/src/services/generateStreamApi.ts b/ornn-web/src/services/generateStreamApi.ts
index 59a2952b..4c6220c9 100644
--- a/ornn-web/src/services/generateStreamApi.ts
+++ b/ornn-web/src/services/generateStreamApi.ts
@@ -13,8 +13,9 @@ const API_BASE = config.apiBaseUrl;
 
 export interface GenerateStreamParams {
   messages: Array<{ role: string; content: string }>;
-  model?: string;
-  modelId?: string;
+  // exactOptionalPropertyTypes (#657)
+  model?: string | undefined;
+  modelId?: string | undefined;
 }
 
 export interface StreamHandle {
diff --git a/ornn-web/src/services/playgroundStreamApi.ts b/ornn-web/src/services/playgroundStreamApi.ts
index c4180038..13615f6f 100644
--- a/ornn-web/src/services/playgroundStreamApi.ts
+++ b/ornn-web/src/services/playgroundStreamApi.ts
@@ -13,9 +13,10 @@ const API_BASE = config.apiBaseUrl;
 
 export interface ChatStreamParams {
   messages: Array<{ role: string; content: string }>;
-  skillId?: string;
-  envVars?: Record<string, string>;
-  modelId?: string;
+  // exactOptionalPropertyTypes (#657)
+  skillId?: string | undefined;
+  envVars?: Record<string, string> | undefined;
+  modelId?: string | undefined;
 }
 
 export interface StreamHandle {
diff --git a/ornn-web/src/services/quotaApi.ts b/ornn-web/src/services/quotaApi.ts
index 356abe79..995a7f0c 100644
--- a/ornn-web/src/services/quotaApi.ts
+++ b/ornn-web/src/services/quotaApi.ts
@@ -68,11 +68,12 @@ export interface AdminQuotaPage {
   totalPages: number;
 }
 
+// exactOptionalPropertyTypes (#657)
 export async function fetchAdminQuotaUsers(params: {
   surface: Surface;
-  page?: number;
-  pageSize?: number;
-  q?: string;
+  page?: number | undefined;
+  pageSize?: number | undefined;
+  q?: string | undefined;
 }): Promise<AdminQuotaPage> {
   const res = await apiGet<AdminQuotaPage>("/api/v1/admin/quota/users", {
     surface: params.surface,
@@ -122,7 +123,8 @@ export interface GrantInput {
   surface: Surface;
   /** Positive integer ≤ 100_000. Validated client-side too for fast feedback. */
   amount: number;
-  note?: string;
+  // exactOptionalPropertyTypes (#657)
+  note?: string | undefined;
 }
 
 export interface GrantResult {
@@ -144,7 +146,8 @@ export interface BulkGrantInput {
   userIds: string[];
   surface: Surface;
   amount: number;
-  note?: string;
+  // exactOptionalPropertyTypes (#657)
+  note?: string | undefined;
 }
 
 export interface BulkGrantOutcome {
diff --git a/ornn-web/src/services/redemptionCodesApi.ts b/ornn-web/src/services/redemptionCodesApi.ts
index d200ffce..d19aa32f 100644
--- a/ornn-web/src/services/redemptionCodesApi.ts
+++ b/ornn-web/src/services/redemptionCodesApi.ts
@@ -47,10 +47,11 @@ export type {
 } from "./redemptionCodesApi.schema";
 
 export interface AdminRedemptionCodeFilters {
-  status?: RedemptionCodeStatus;
-  search?: string;
-  page?: number;
-  pageSize?: number;
+  // exactOptionalPropertyTypes (#657)
+  status?: RedemptionCodeStatus | undefined;
+  search?: string | undefined;
+  page?: number | undefined;
+  pageSize?: number | undefined;
 }
 
 export async function mintCode(req: MintCodeRequest): Promise<MintCodeResponse> {
diff --git a/ornn-web/src/services/searchApi.ts b/ornn-web/src/services/searchApi.ts
index 8369e864..bc76293a 100644
--- a/ornn-web/src/services/searchApi.ts
+++ b/ornn-web/src/services/searchApi.ts
@@ -9,7 +9,8 @@ export async function searchSkills(
   params: SkillSearchParams
 ): Promise<SkillSearchResponse> {
   const queryParams: Record<string, string | number | undefined> = {
-    query: params.query,
+    // Canonical search param is `q` per CONVENTIONS.md §4.1 (#586).
+    q: params.query,
     mode: params.mode,
     scope: params.scope,
     page: params.page,
diff --git a/ornn-web/src/services/settingsApi.ts b/ornn-web/src/services/settingsApi.ts
index 32dece01..162e6579 100644
--- a/ornn-web/src/services/settingsApi.ts
+++ b/ornn-web/src/services/settingsApi.ts
@@ -32,8 +32,10 @@ export type SectionKey =
   | "extras";
 
 export interface SectionMeta {
-  updatedAt?: string;
-  updatedBy?: string;
+  // exactOptionalPropertyTypes (#657): widen to `T | undefined` so Zod-
+  // inferred shapes with `.optional()` fields fit.
+  updatedAt?: string | undefined;
+  updatedBy?: string | undefined;
 }
 
 export const REDACTION_PREFIX = "<REDACTED:";
@@ -130,7 +132,8 @@ export interface ExtrasSection extends SectionMeta {
   extraNyxidServices: Array<{
     name: string;
     baseUrl: string;
-    scopes?: string[];
+    // exactOptionalPropertyTypes (#657)
+    scopes?: string[] | undefined;
   }>;
 }
 
diff --git a/ornn-web/src/services/skillApi.ts b/ornn-web/src/services/skillApi.ts
index 4565fb6c..cd04b5de 100644
--- a/ornn-web/src/services/skillApi.ts
+++ b/ornn-web/src/services/skillApi.ts
@@ -46,7 +46,8 @@ export async function fetchSkillVersionDiff(
 export async function setSkillVersionDeprecation(
   idOrName: string,
   version: string,
-  body: { isDeprecated: boolean; deprecationNote?: string },
+  // exactOptionalPropertyTypes (#657)
+  body: { isDeprecated: boolean; deprecationNote?: string | undefined },
 ): Promise<{
   skillGuid: string;
   skillName: string;
@@ -85,21 +86,25 @@ export async function setSkillVersionDeprecation(
  * Create a new skill from a ZIP file. Sends the ZIP as a raw
  * application/zip body. New skills are always private — visibility is
  * managed afterward via the permissions panel on the skill detail page.
+ *
+ * #528 — `X-User-Email` / `X-User-Display-Name` headers used to ride
+ * along here. They were stripped by the NyxID proxy and never read by
+ * the backend (identity is sourced from the proxy-forwarded identity
+ * token), but the backend CORS allowlist is `["Content-Type",
+ * "Authorization"]`, so the preflight allowed-headers response didn't
+ * include them — the browser then blocked the actual POST with a
+ * CORS error. Same dead code as the `apiClient.createHeaders`
+ * cleanup; this was the last unmigrated caller of the ZIP-upload
+ * flow.
  */
 export async function createSkill(zipFile: File, skipValidation = false): Promise<SkillDetail> {
-  const { accessToken: token, user } = useAuthStore.getState();
+  const token = useAuthStore.getState().accessToken;
   const headers: HeadersInit = {
     "Content-Type": "application/zip",
   };
   if (token) {
     headers["Authorization"] = `Bearer ${token}`;
   }
-  if (user?.email) {
-    headers["X-User-Email"] = user.email;
-  }
-  if (user?.displayName) {
-    headers["X-User-Display-Name"] = user.displayName;
-  }
 
   const params = skipValidation ? "?skip_validation=true" : "";
   const response = await fetch(`${API_BASE}/api/v1/skills${params}`, {
@@ -216,7 +221,8 @@ export async function pullSkillFromGitHub(input: PullFromGitHubInput): Promise<S
  */
 export async function refreshSkillFromSource(
   id: string,
-  options?: { skipValidation?: boolean },
+  // exactOptionalPropertyTypes (#657)
+  options?: { skipValidation?: boolean | undefined },
 ): Promise<SkillDetail> {
   const res = await apiPost<SkillDetail>(`/api/v1/skills/${id}/refresh`, {
     skipValidation: options?.skipValidation ?? false,
diff --git a/ornn-web/src/stores/authStore.ts b/ornn-web/src/stores/authStore.ts
index 4eb6c6f2..e97c6a98 100644
--- a/ornn-web/src/stores/authStore.ts
+++ b/ornn-web/src/stores/authStore.ts
@@ -8,13 +8,9 @@ import { create } from "zustand";
 import { persist } from "zustand/middleware";
 import type { AuthUser, NyxIDTokenResponse, NyxIDJwtClaims, NyxIDIdTokenClaims } from "@/types/auth";
 import { config } from "@/config";
+import { createLogger } from "@/lib/logger";
 
-const logger = {
-  info: (msg: string, data?: Record<string, unknown>) =>
-    console.log(`[auth] ${msg}`, data ?? ""),
-  error: (msg: string, data?: Record<string, unknown>) =>
-    console.error(`[auth] ${msg}`, data ?? ""),
-};
+const logger = createLogger("auth");
 
 /** Refresh token 1 minute before expiry. */
 const TOKEN_REFRESH_BUFFER_MS = 60 * 1000;
@@ -40,6 +36,24 @@ interface AuthState {
   isLoading: boolean;
   tokenExpiresAt: number | null;
   _refreshTimerId: ReturnType<typeof setTimeout> | null;
+  /**
+   * In-flight token-refresh promise (#631). When non-null, the SPA has
+   * an `/oauth/token` `refresh_token` request pending; concurrent
+   * callers (a near-expiry preflight in `apiClient.fetchWithRetry`, a
+   * 401-triggered retry in the same client, the scheduled
+   * `startTokenRefresh` timer, and the `visibilitychange` handler can
+   * all race within the same millisecond) MUST await this promise
+   * instead of firing their own. NyxID rotates the refresh token on
+   * every successful exchange, so a second concurrent request loses
+   * the race and gets:
+   *
+   *   `Conflict: Refresh token was concurrently rotated, please retry`
+   *
+   * which then surfaces as a logout-loop. Promises aren't
+   * serialisable, so this field is deliberately excluded from
+   * `partialize` — it only lives for the lifetime of the tab.
+   */
+  _refreshInFlight: Promise<void> | null;
 
   loginWithNyxID(): Promise<void>;
   handleNyxIDCallback(code: string): Promise<void>;
@@ -59,7 +73,9 @@ function decodeJwtPayload(token: string): NyxIDJwtClaims | null {
   try {
     const parts = token.split(".");
     if (parts.length !== 3) return null;
-    const payload = atob(parts[1].replace(/-/g, "+").replace(/_/g, "/"));
+    // Length-checked above. `!` is safe under noUncheckedIndexedAccess
+    // (#450).
+    const payload = atob(parts[1]!.replace(/-/g, "+").replace(/_/g, "/"));
     return JSON.parse(payload) as NyxIDJwtClaims;
   } catch {
     logger.error("Failed to decode JWT payload");
@@ -186,6 +202,7 @@ export const useAuthStore = create<AuthState>()(
       isLoading: false,
       tokenExpiresAt: null,
       _refreshTimerId: null,
+      _refreshInFlight: null,
 
       loginWithNyxID: async () => {
         logger.info("Initiating NyxID OAuth login with PKCE");
@@ -286,6 +303,22 @@ export const useAuthStore = create<AuthState>()(
       },
 
       refreshToken: async () => {
+        // #631 — dedup concurrent callers. The SPA fans out into
+        // `refreshToken()` from up to four places within the same
+        // millisecond (`apiClient.fetchWithRetry` proactive +
+        // reactive-on-401, the scheduled `startTokenRefresh` timer,
+        // and the `visibilitychange` handler). NyxID rotates the
+        // refresh token on every successful exchange, so a second
+        // concurrent caller wins the rotation while the loser sees
+        //   `Conflict: Refresh token was concurrently rotated`
+        // and the SPA logs the user out. Funnel all callers through
+        // a single in-flight promise.
+        const existing = get()._refreshInFlight;
+        if (existing) {
+          logger.debug("Token refresh already in flight — awaiting existing promise");
+          return existing;
+        }
+
         const refreshTokenValue = get().refreshTokenValue;
         if (!refreshTokenValue) {
           logger.info("No refresh token available, clearing auth");
@@ -295,62 +328,73 @@ export const useAuthStore = create<AuthState>()(
 
         logger.info("Refreshing NyxID access token");
 
-        try {
-          const response = await fetch(NYXID_CONFIG.tokenUrl, {
-            method: "POST",
-            headers: { "Content-Type": "application/x-www-form-urlencoded" },
-            body: new URLSearchParams({
-              grant_type: "refresh_token",
-              refresh_token: refreshTokenValue,
-              client_id: NYXID_CONFIG.clientId,
-            }),
-          });
-
-          if (!response.ok) {
-            throw new Error(`Token refresh failed: ${response.status}`);
-          }
-
-          const tokenResponse = (await response.json()) as NyxIDTokenResponse;
-          const accessClaims = decodeJwtPayload(tokenResponse.access_token) as NyxIDJwtClaims | null;
-          if (!accessClaims) {
-            throw new Error("Failed to decode refreshed access token");
-          }
+        const promise = (async () => {
+          try {
+            const response = await fetch(NYXID_CONFIG.tokenUrl, {
+              method: "POST",
+              headers: { "Content-Type": "application/x-www-form-urlencoded" },
+              body: new URLSearchParams({
+                grant_type: "refresh_token",
+                refresh_token: refreshTokenValue,
+                client_id: NYXID_CONFIG.clientId,
+              }),
+            });
 
-          // Preserve profile info from initial login; keep existing roles/permissions if refreshed token lacks them
-          const existingUser = get().user;
-          const user: AuthUser = {
-            id: accessClaims.sub,
-            email: existingUser?.email ?? "",
-            displayName: existingUser?.displayName ?? accessClaims.sub,
-            avatarUrl: existingUser?.avatarUrl ?? "",
-            roles: accessClaims.roles?.length ? accessClaims.roles : (existingUser?.roles ?? []),
-            permissions: accessClaims.permissions?.length ? accessClaims.permissions : (existingUser?.permissions ?? []),
-          };
-          const expiresAt = accessClaims.exp * 1000;
+            if (!response.ok) {
+              throw new Error(`Token refresh failed: ${response.status}`);
+            }
 
-          logger.info("Token refresh successful");
+            const tokenResponse = (await response.json()) as NyxIDTokenResponse;
+            const accessClaims = decodeJwtPayload(tokenResponse.access_token) as NyxIDJwtClaims | null;
+            if (!accessClaims) {
+              throw new Error("Failed to decode refreshed access token");
+            }
 
-          set({
-            accessToken: tokenResponse.access_token,
-            refreshTokenValue: tokenResponse.refresh_token ?? refreshTokenValue,
-            user,
-            isAuthenticated: true,
-            tokenExpiresAt: expiresAt,
-          });
+            // Preserve profile info from initial login; keep existing roles/permissions if refreshed token lacks them
+            const existingUser = get().user;
+            const user: AuthUser = {
+              id: accessClaims.sub,
+              email: existingUser?.email ?? "",
+              displayName: existingUser?.displayName ?? accessClaims.sub,
+              avatarUrl: existingUser?.avatarUrl ?? "",
+              roles: accessClaims.roles?.length ? accessClaims.roles : (existingUser?.roles ?? []),
+              permissions: accessClaims.permissions?.length ? accessClaims.permissions : (existingUser?.permissions ?? []),
+            };
+            const expiresAt = accessClaims.exp * 1000;
+
+            logger.info("Token refresh successful");
+
+            set({
+              accessToken: tokenResponse.access_token,
+              refreshTokenValue: tokenResponse.refresh_token ?? refreshTokenValue,
+              user,
+              isAuthenticated: true,
+              tokenExpiresAt: expiresAt,
+            });
 
-          get().startTokenRefresh();
-        } catch (err) {
-          logger.error("Token refresh failed", {
-            error: err instanceof Error ? err.message : String(err),
-          });
-          get().stopTokenRefresh();
-          set({
-            accessToken: null,
-            refreshTokenValue: null,
-            user: null,
-            isAuthenticated: false,
-            tokenExpiresAt: null,
-          });
+            get().startTokenRefresh();
+          } catch (err) {
+            logger.error("Token refresh failed", {
+              error: err instanceof Error ? err.message : String(err),
+            });
+            get().stopTokenRefresh();
+            set({
+              accessToken: null,
+              refreshTokenValue: null,
+              user: null,
+              isAuthenticated: false,
+              tokenExpiresAt: null,
+            });
+          }
+        })();
+        // Stash so concurrent callers latch on. The finally clears
+        // the slot once the request settles — the NEXT (later in
+        // time) `refreshToken()` call then starts fresh.
+        set({ _refreshInFlight: promise });
+        try {
+          await promise;
+        } finally {
+          set({ _refreshInFlight: null });
         }
       },
 
diff --git a/ornn-web/src/styles/neon.css b/ornn-web/src/styles/neon.css
index ee865b51..4228fef2 100644
--- a/ornn-web/src/styles/neon.css
+++ b/ornn-web/src/styles/neon.css
@@ -75,6 +75,19 @@ html {
   --color-arc-soft: rgba(91, 200, 232, 0.10);
   --color-ember-glow: rgba(255, 115, 34, 0.30);      /* hero floor / pulse glows */
 
+  /* Landing-chrome tokens (#452) — referenced from PhoneMockup and
+     AnimatedTerminal so hex literals stay out of JSX. Same values in
+     both themes: the macOS-style traffic-light dots and the phone
+     bezel shadows read consistently on either page background. */
+  --color-bezel-edge: #1A1713;                       /* phone side rails + lens depth shadow */
+  --color-bezel-rim: #2A2620;                        /* phone outer rim */
+  --color-lens-deep: #0B1520;                        /* camera-lens base */
+  --color-lens-rim: #3A5060;                         /* camera-lens specular */
+  --color-traffic-red: #C94A4A;
+  --color-traffic-amber: #C9A64A;
+  --color-traffic-green: #5A9B5A;
+  --color-terminal-ok: #7DC97D;                      /* terminal-output checkmark green */
+
   --font-display: "Space Grotesk", "Inter", system-ui, sans-serif;
   --font-text: "Inter", system-ui, sans-serif;
   --font-ui: "Inter", system-ui, sans-serif;
diff --git a/ornn-web/src/types/domain.ts b/ornn-web/src/types/domain.ts
index cac86e73..c4b085fc 100644
--- a/ornn-web/src/types/domain.ts
+++ b/ornn-web/src/types/domain.ts
@@ -143,8 +143,9 @@ export interface SkillVersionEntry {
   version: string;
   skillHash: string;
   createdBy: string;
-  createdByEmail?: string;
-  createdByDisplayName?: string;
+  // exactOptionalPropertyTypes (#657)
+  createdByEmail?: string | undefined;
+  createdByDisplayName?: string | undefined;
   createdOn: string;
   isDeprecated: boolean;
   deprecationNote: string | null;
diff --git a/ornn-web/src/types/search.ts b/ornn-web/src/types/search.ts
index 126ccab6..48dafe93 100644
--- a/ornn-web/src/types/search.ts
+++ b/ornn-web/src/types/search.ts
@@ -13,65 +13,50 @@ export type SystemFilter = "any" | "only" | "exclude";
 export type SkillScope = "public" | "private" | "mixed" | "shared-with-me" | "mine";
 
 export interface SkillSearchParams {
-  query?: string;
-  mode?: "keyword" | "semantic";
-  scope?: SkillScope;
-  page?: number;
-  pageSize?: number;
-  /** System-skill tri-state; default "any". */
-  systemFilter?: SystemFilter;
-  /** Registry chip filters. Comma-joined client-side, parsed back on the server. */
-  sharedWithOrgs?: string[];
-  sharedWithUsers?: string[];
-  createdByAny?: string[];
-  /** Restrict to skills tied to this NyxID service (system-tab filter). */
-  nyxidServiceId?: string;
-  /** Skill must have ALL listed tags (AND match). */
-  tags?: string[];
+  // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
+  query?: string | undefined;
+  mode?: "keyword" | "semantic" | undefined;
+  scope?: SkillScope | undefined;
+  page?: number | undefined;
+  pageSize?: number | undefined;
+  systemFilter?: SystemFilter | undefined;
+  sharedWithOrgs?: string[] | undefined;
+  sharedWithUsers?: string[] | undefined;
+  createdByAny?: string[] | undefined;
+  nyxidServiceId?: string | undefined;
+  tags?: string[] | undefined;
 }
 
 export interface SkillSearchResult {
   guid: string;
   name: string;
   description: string;
-  /** Owner entity — may be a person user_id or an org user_id. */
-  ownerId?: string;
   createdBy: string;
-  createdByEmail?: string;
-  createdByDisplayName?: string;
+  // Optionals widen to `T | undefined` for exactOptionalPropertyTypes (#657).
+  createdByEmail?: string | undefined;
+  createdByDisplayName?: string | undefined;
   createdOn: string;
   updatedOn: string;
   isPrivate: boolean;
   tags: string[];
-  /** Why the caller can see this skill; omitted for anonymous callers. */
-  myAccessReason?: AccessReason;
-  /** Present when myAccessReason === "shared-via-org". */
-  sharedViaOrgId?: string;
-  /** True when any of the skill's tags matches a slug of a NyxID service
-   *  the caller can manage. */
-  isSystemForMe?: boolean;
-  /** The first NyxID service that matched, used to render the system chip. */
-  systemForService?: { id: string; slug: string; label: string };
-  /** Compact ACL view for card-level badges. */
-  permissionSummary?: {
-    isPrivate: boolean;
-    sharedUserCount: number;
-    sharedOrgCount: number;
-  };
+  myAccessReason?: AccessReason | undefined;
+  sharedViaOrgId?: string | undefined;
+  isSystemForMe?: boolean | undefined;
+  systemForService?: { id: string; slug: string; label: string } | undefined;
+  permissionSummary?:
+    | {
+        isPrivate: boolean;
+        sharedUserCount: number;
+        sharedOrgCount: number;
+      }
+    | undefined;
   /** NyxID service tie surfaced on cards. `null` when untied. */
-  nyxidServiceId?: string | null;
-  nyxidServiceSlug?: string | null;
-  nyxidServiceLabel?: string | null;
+  nyxidServiceId?: string | null | undefined;
+  nyxidServiceSlug?: string | null | undefined;
+  nyxidServiceLabel?: string | null | undefined;
   /** True iff tied to an admin/platform NyxID service. */
-  isSystemSkill?: boolean;
-  /**
-   * True when the skill has a `source` pointer of type "github" — i.e.
-   * the owner has linked it to a folder in a public GitHub repo. The
-   * card uses this to render a small non-clickable GitHub mark in the
-   * badge row. The actual repo URL is not exposed in search results —
-   * users open the detail page to follow it.
-   */
-  hasGithubSource?: boolean;
+  isSystemSkill?: boolean | undefined;
+  hasGithubSource?: boolean | undefined;
 }
 
 export interface SkillSearchResponse {
diff --git a/ornn-web/src/types/skillPackage.ts b/ornn-web/src/types/skillPackage.ts
index 0d7a5207..5aa02347 100644
--- a/ornn-web/src/types/skillPackage.ts
+++ b/ornn-web/src/types/skillPackage.ts
@@ -37,7 +37,8 @@ export type SkillOutputType = "text" | "file";
 /** Nested metadata sub-object matching the frontmatter schema */
 export interface SkillMetadataBlock {
   category: SkillCategory;
-  outputType?: SkillOutputType;
+  // exactOptionalPropertyTypes (#657)
+  outputType?: SkillOutputType | undefined;
   runtime: string[];
   runtimeDependency: string[];
   runtimeEnvVar: string[];
diff --git a/ornn-web/src/utils/fileTreeBuilder.ts b/ornn-web/src/utils/fileTreeBuilder.ts
index 37338564..fe266356 100644
--- a/ornn-web/src/utils/fileTreeBuilder.ts
+++ b/ornn-web/src/utils/fileTreeBuilder.ts
@@ -66,7 +66,7 @@ export function buildFileTreeFromEntries(entries: FileTreeEntry[]): FileNode[] {
     if (existing) return existing;
 
     const parts = folderPath.split("/");
-    const name = parts[parts.length - 1];
+    const name = parts[parts.length - 1]!;
     const node: FileNode = { id: folderPath, name, type: "folder", children: [] };
     folderMap.set(folderPath, node);
 
@@ -93,7 +93,7 @@ export function buildFileTreeFromEntries(entries: FileTreeEntry[]): FileNode[] {
     if (entry.type !== "file") continue;
 
     const parts = entry.path.split("/");
-    const name = parts[parts.length - 1];
+    const name = parts[parts.length - 1]!;
     const fileNode: FileNode = { id: entry.path, name, type: "file" };
 
     if (parts.length === 1) {
diff --git a/ornn-web/src/utils/frontmatter.ts b/ornn-web/src/utils/frontmatter.ts
index f5fba47e..ed6ff3ed 100644
--- a/ornn-web/src/utils/frontmatter.ts
+++ b/ornn-web/src/utils/frontmatter.ts
@@ -66,7 +66,9 @@ export function extractFrontmatter(
   if (!match) return null;
 
   try {
-    const raw = parseYaml(match[1]);
+    // FRONTMATTER_REGEX always has capture group 1 when it matches.
+    // `!` is safe under noUncheckedIndexedAccess (#450).
+    const raw = parseYaml(match[1]!);
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
 
     const camelized = yamlKeysToCamel(raw as Record<string, unknown>);
diff --git a/ornn-web/src/utils/skillCreateSchemas.ts b/ornn-web/src/utils/skillCreateSchemas.ts
index 25985177..dd75326c 100644
--- a/ornn-web/src/utils/skillCreateSchemas.ts
+++ b/ornn-web/src/utils/skillCreateSchemas.ts
@@ -3,57 +3,89 @@
  * Zod schemas and derived types for the guided skill creation wizard.
  * Uses the canonical frontmatter schema's refined metadata sub-schema
  * for consistent conditional validation.
+ *
+ * Validation messages render through `t()` so they follow the active
+ * UI language (#695). Each consumer passes a translator into the
+ * `make…Schema(t)` factory and memoizes the resulting schema against
+ * the current `t` reference so a language switch rebuilds the form
+ * resolver without rerendering everything.
+ *
+ * Static schemas (`basicInfoSchema`, `contentSchema`) remain exported
+ * with literal English fallbacks for type-derivation and any non-UI
+ * caller (tests, server-side reuse). The factories are the canonical
+ * UI entrypoint.
+ *
  * @module utils/skillCreateSchemas
  */
 
 import { z } from "zod";
 import { refinedMetadataSchema } from "./skillFrontmatterSchema";
 
-/**
- * Step 1 schema: basic metadata with nested metadata, optional Claude fields,
- * and conditional tool/runtime requirements enforced by refinedMetadataSchema.
- */
-export const basicInfoSchema = z.object({
-  name: z
-    .string()
-    .min(2, "Name must be at least 2 characters")
-    .max(64, "Name must be at most 64 characters")
-    .regex(
-      /^[a-z0-9][a-z0-9-]*$/,
-      "Must start with a letter or number, only lowercase, numbers, and hyphens",
-    ),
-  description: z
-    .string()
-    .min(10, "Description must be at least 10 characters")
-    .max(500),
+/** i18next-shaped translator. Loose signature so the real
+ *  `TFunction` from react-i18next (variadic options, overloaded
+ *  return types) assigns cleanly without a hard runtime dependency. */
+type Translator = (key: string, ...rest: unknown[]) => string;
 
-  /** Nested metadata with conditional validation */
-  metadata: refinedMetadataSchema,
+const EN_MESSAGES = {
+  nameMin: "Name must be at least 2 characters",
+  nameMax: "Name must be at most 64 characters",
+  nameShape: "Must start with a letter or number, only lowercase, numbers, and hyphens",
+  descMin: "Description must be at least 10 characters",
+  contentMin: "Content must be at least 50 characters",
+} as const;
 
-  /** SPDX license identifier */
-  license: z.string().max(50).optional(),
+function msg(t: Translator | undefined, key: keyof typeof EN_MESSAGES): string {
+  const en = EN_MESSAGES[key];
+  return t ? t(`guided.validation.${key}`, en) : en;
+}
 
-  /** Compatibility information */
-  compatibility: z.string().max(200).optional(),
+/**
+ * Step 1 schema factory: basic metadata with nested metadata, optional
+ * Claude fields, and conditional tool/runtime requirements enforced by
+ * refinedMetadataSchema. Pass `t` from `useTranslation()`; omit for
+ * the English-fallback static shape.
+ */
+export function makeBasicInfoSchema(t?: Translator) {
+  return z.object({
+    name: z
+      .string()
+      .min(2, msg(t, "nameMin"))
+      .max(64, msg(t, "nameMax"))
+      .regex(/^[a-z0-9][a-z0-9-]*$/, msg(t, "nameShape")),
+    description: z
+      .string()
+      .min(10, msg(t, "descMin"))
+      .max(500),
 
-  // --- Advanced Claude fields (collapsed by default) ---
+    metadata: refinedMetadataSchema,
+    license: z.string().max(50).optional(),
+    compatibility: z.string().max(200).optional(),
 
-  disableModelInvocation: z.boolean().default(false),
-  userInvocable: z.boolean().default(true),
-  allowedTools: z.array(z.string()).default([]),
-  model: z.string().max(100).optional(),
-  context: z.array(z.string()).default([]),
-  agent: z.string().max(100).optional(),
-  argumentHint: z.string().max(500).optional(),
-  hooks: z.record(z.string(), z.unknown()).optional(),
-});
+    disableModelInvocation: z.boolean().default(false),
+    userInvocable: z.boolean().default(true),
+    allowedTools: z.array(z.string()).default([]),
+    model: z.string().max(100).optional(),
+    context: z.array(z.string()).default([]),
+    agent: z.string().max(100).optional(),
+    argumentHint: z.string().max(500).optional(),
+    hooks: z.record(z.string(), z.unknown()).optional(),
+  });
+}
 
 /**
- * Step 2 schema: markdown body content for SKILL.md.
+ * Step 2 schema factory: markdown body content for SKILL.md.
  */
-export const contentSchema = z.object({
-  readmeMd: z.string().min(50, "Content must be at least 50 characters"),
-});
+export function makeContentSchema(t?: Translator) {
+  return z.object({
+    readmeMd: z.string().min(50, msg(t, "contentMin")),
+  });
+}
+
+/** Static English-fallback schemas — preserve the original export
+ *  surface for callers that don't have a `t` in scope (tests, type
+ *  derivation, server-side reuse). */
+export const basicInfoSchema = makeBasicInfoSchema();
+export const contentSchema = makeContentSchema();
 
 // `Input` is the pre-validation shape (fields with `.default(...)` are
 // optional); `Data` is the post-validation shape (defaults applied, so
diff --git a/ornn-web/src/utils/skillFrontmatterSchema.test.ts b/ornn-web/src/utils/skillFrontmatterSchema.test.ts
new file mode 100644
index 00000000..a9352545
--- /dev/null
+++ b/ornn-web/src/utils/skillFrontmatterSchema.test.ts
@@ -0,0 +1,174 @@
+/**
+ * Tests for the actionable `invalid_type` callbacks added for #649.
+ *
+ * The frontend schema mirrors the backend's
+ * `ornn-api/src/shared/schemas/skillFrontmatter.ts` so users see the same
+ * "write `version: \"0.1\"`, not `version: 0.1`" message regardless of
+ * whether the frontmatter is rejected by the SPA's pre-validator or by
+ * the backend. PR #672 landed the backend half; this file pins the
+ * frontend half so future Zod refactors don't silently drop the
+ * actionable copy.
+ *
+ * Each branch parses a frontmatter payload where one field carries a
+ * non-string YAML primitive (number / null), then asserts the returned
+ * `messageKey` is the *Invalid type* i18n key (not `versionFormat`,
+ * `tagFormat`, etc — those fire for wrong-shape *strings*, which is a
+ * different code path).
+ */
+
+import { describe, expect, test } from "vitest";
+import { validateSkillFrontmatter } from "./skillFrontmatterSchema";
+
+/** Build a valid `plain` frontmatter shape we can mutate per-test. */
+function basePayload() {
+  return {
+    name: "my-skill",
+    description: "A description.",
+    version: "0.1",
+    metadata: {
+      category: "plain",
+    },
+  };
+}
+
+describe("frontmatter schema — invalid_type actionable messages (#649)", () => {
+  test("version: 0.1 (unquoted, YAML → number) surfaces versionInvalidType", () => {
+    const payload = basePayload();
+    // YAML `version: 0.1` lands here as a number, not a string.
+    (payload as unknown as { version: number }).version = 0.1;
+
+    const result = validateSkillFrontmatter(payload);
+    expect(result.success).toBe(false);
+    if (result.success) return;
+
+    const versionErr = result.errors.find((e) => e.field === "version");
+    expect(versionErr).toBeDefined();
+    expect(versionErr?.messageKey).toBe(
+      "errors.frontmatter.versionInvalidType",
+    );
+    // Should NOT degrade to the generic catch-all.
+    expect(versionErr?.messageKey).not.toBe("errors.frontmatter.generic");
+  });
+
+  test("tag: [null] (empty `- ` YAML line) surfaces tagInvalidType", () => {
+    const payload = basePayload();
+    (payload.metadata as Record<string, unknown>).tag = [null];
+
+    const result = validateSkillFrontmatter(payload);
+    expect(result.success).toBe(false);
+    if (result.success) return;
+
+    const tagErr = result.errors.find((e) => e.field.startsWith("metadata.tag"));
+    expect(tagErr?.messageKey).toBe("errors.frontmatter.tagInvalidType");
+  });
+
+  test("runtime-env-var: [null] surfaces envVarInvalidType (category: mixed)", () => {
+    // env-var is only allowed for runtime-based/mixed categories, so flip
+    // to mixed for this branch and supply the other required fields.
+    const payload = basePayload();
+    payload.metadata = {
+      category: "mixed",
+      runtime: ["python"],
+      toolList: ["Bash"],
+      outputType: "text",
+      runtimeEnvVar: [null],
+    } as unknown as typeof payload.metadata;
+
+    const result = validateSkillFrontmatter(payload);
+    expect(result.success).toBe(false);
+    if (result.success) return;
+
+    const envErr = result.errors.find((e) =>
+      e.field.startsWith("metadata.runtimeEnvVar"),
+    );
+    expect(envErr?.messageKey).toBe("errors.frontmatter.envVarInvalidType");
+  });
+
+  test("tool-list: [null] surfaces toolInvalidType (category: tool-based)", () => {
+    const payload = basePayload();
+    payload.metadata = {
+      category: "tool-based",
+      toolList: [null],
+    } as unknown as typeof payload.metadata;
+
+    const result = validateSkillFrontmatter(payload);
+    expect(result.success).toBe(false);
+    if (result.success) return;
+
+    const toolErr = result.errors.find((e) =>
+      e.field.startsWith("metadata.toolList"),
+    );
+    expect(toolErr?.messageKey).toBe("errors.frontmatter.toolInvalidType");
+  });
+
+  test("runtime: [null] surfaces runtimeInvalidType (category: runtime-based)", () => {
+    const payload = basePayload();
+    payload.metadata = {
+      category: "runtime-based",
+      runtime: [null],
+      outputType: "text",
+    } as unknown as typeof payload.metadata;
+
+    const result = validateSkillFrontmatter(payload);
+    expect(result.success).toBe(false);
+    if (result.success) return;
+
+    const rtErr = result.errors.find((e) =>
+      e.field.startsWith("metadata.runtime"),
+    );
+    expect(rtErr?.messageKey).toBe("errors.frontmatter.runtimeInvalidType");
+  });
+
+  test("runtime-dependency: [null] surfaces dependencyInvalidType", () => {
+    const payload = basePayload();
+    payload.metadata = {
+      category: "runtime-based",
+      runtime: ["python"],
+      outputType: "text",
+      runtimeDependency: [null],
+    } as unknown as typeof payload.metadata;
+
+    const result = validateSkillFrontmatter(payload);
+    expect(result.success).toBe(false);
+    if (result.success) return;
+
+    const depErr = result.errors.find((e) =>
+      e.field.startsWith("metadata.runtimeDependency"),
+    );
+    expect(depErr?.messageKey).toBe(
+      "errors.frontmatter.dependencyInvalidType",
+    );
+  });
+});
+
+describe("frontmatter schema — pre-existing string-shape errors still fire (#649 regression guard)", () => {
+  test('version: "1" (string, wrong shape) still uses versionFormat, not versionInvalidType', () => {
+    const payload = basePayload();
+    payload.version = "1"; // wrong shape but right type.
+
+    const result = validateSkillFrontmatter(payload);
+    expect(result.success).toBe(false);
+    if (result.success) return;
+
+    const versionErr = result.errors.find((e) => e.field === "version");
+    expect(versionErr?.messageKey).toBe("errors.frontmatter.versionFormat");
+  });
+
+  test('tag: ["UPPER"] (string, wrong format) still uses tagFormat', () => {
+    const payload = basePayload();
+    (payload.metadata as Record<string, unknown>).tag = ["UPPER"];
+
+    const result = validateSkillFrontmatter(payload);
+    expect(result.success).toBe(false);
+    if (result.success) return;
+
+    const tagErr = result.errors.find((e) => e.field.startsWith("metadata.tag"));
+    expect(tagErr?.messageKey).toBe("errors.frontmatter.tagFormat");
+  });
+
+  test("happy path: valid plain skill parses cleanly", () => {
+    const payload = basePayload();
+    const result = validateSkillFrontmatter(payload);
+    expect(result.success).toBe(true);
+  });
+});
diff --git a/ornn-web/src/utils/skillFrontmatterSchema.ts b/ornn-web/src/utils/skillFrontmatterSchema.ts
index d9053558..883ca520 100644
--- a/ornn-web/src/utils/skillFrontmatterSchema.ts
+++ b/ornn-web/src/utils/skillFrontmatterSchema.ts
@@ -37,9 +37,24 @@ export type OutputType = (typeof OUTPUT_TYPES)[number];
 export const ALLOWED_RUNTIMES = ["node", "python"] as const;
 
 // --- Sub-item schemas ---
+//
+// #649 — YAML allows empty list items (`- ` on a line by itself parses
+// as `null`) and lets authors put non-string values where a string is
+// expected. Default Zod messages on those cases come back as bare
+// `Invalid input` which doesn't tell the author *what to write
+// instead*. Each item schema below carries a custom `error` callback
+// for `invalid_type` that maps to a localizable i18n key with
+// actionable copy. Mirrors the backend pattern in
+// `ornn-api/src/shared/schemas/skillFrontmatter.ts`. The existing
+// `min`/`max`/`regex` messages still fire for non-null shape problems.
 
 const tagItemSchema = z
-  .string()
+  .string({
+    error: (issue) =>
+      issue.code === "invalid_type"
+        ? issueMessage({ key: "errors.frontmatter.tagInvalidType" })
+        : undefined,
+  })
   .min(1)
   .max(30)
   .regex(
@@ -48,7 +63,12 @@ const tagItemSchema = z
   );
 
 const envVarItemSchema = z
-  .string()
+  .string({
+    error: (issue) =>
+      issue.code === "invalid_type"
+        ? issueMessage({ key: "errors.frontmatter.envVarInvalidType" })
+        : undefined,
+  })
   .min(1)
   .max(100)
   .regex(
@@ -56,9 +76,33 @@ const envVarItemSchema = z
     issueMessage({ key: "errors.frontmatter.envVarFormat" }),
   );
 
-const toolItemSchema = z.string().min(1).max(100);
-const runtimeItemSchema = z.string().min(1).max(50);
-const dependencyItemSchema = z.string().min(1).max(200);
+const toolItemSchema = z
+  .string({
+    error: (issue) =>
+      issue.code === "invalid_type"
+        ? issueMessage({ key: "errors.frontmatter.toolInvalidType" })
+        : undefined,
+  })
+  .min(1)
+  .max(100);
+const runtimeItemSchema = z
+  .string({
+    error: (issue) =>
+      issue.code === "invalid_type"
+        ? issueMessage({ key: "errors.frontmatter.runtimeInvalidType" })
+        : undefined,
+  })
+  .min(1)
+  .max(50);
+const dependencyItemSchema = z
+  .string({
+    error: (issue) =>
+      issue.code === "invalid_type"
+        ? issueMessage({ key: "errors.frontmatter.dependencyInvalidType" })
+        : undefined,
+  })
+  .min(1)
+  .max(200);
 
 // --- Metadata sub-schema (without conditional refinement) ---
 
@@ -197,8 +241,19 @@ export const skillFrontmatterSchema = z.object({
       issueMessage({ key: "errors.frontmatter.nameFormat" }),
     ),
   description: z.string().min(1).max(1024),
+  // #649 — YAML parses `version: 0.1` (unquoted) as a number, not a
+  // string. The default Zod message ("Invalid input") doesn't tell
+  // the author to quote the value. Surface an actionable message via
+  // the `invalid_type` branch; the existing regex still catches
+  // wrong-shape strings. Mirrors the backend at
+  // `ornn-api/src/shared/schemas/skillFrontmatter.ts:172-188`.
   version: z
-    .string()
+    .string({
+      error: (issue) =>
+        issue.code === "invalid_type"
+          ? issueMessage({ key: "errors.frontmatter.versionInvalidType" })
+          : undefined,
+    })
     .regex(
       SKILL_VERSION_REGEX,
       issueMessage({ key: "errors.frontmatter.versionFormat" }),
@@ -239,7 +294,8 @@ export type MetadataOutput = z.output<typeof metadataSchema>;
 export interface FrontmatterValidationError {
   field: string;
   messageKey: string;
-  params?: Record<string, string | number>;
+  // exactOptionalPropertyTypes (#657)
+  params?: Record<string, string | number> | undefined;
   received?: unknown;
 }
 
diff --git a/ornn-web/src/utils/zipValidator.test.ts b/ornn-web/src/utils/zipValidator.test.ts
new file mode 100644
index 00000000..398bed2d
--- /dev/null
+++ b/ornn-web/src/utils/zipValidator.test.ts
@@ -0,0 +1,103 @@
+/**
+ * Tests for the ZIP validator hardening landed in #443:
+ *
+ *   - cumulative uncompressed-size cap (zip-bomb defence)
+ *   - explicit zip-slip / unsafe-path rejection
+ *
+ * Pre-existing happy-path behaviour is exercised via the
+ * SkillUploadPage component tests; this file is scoped to the two
+ * new guards.
+ */
+
+import { describe, expect, test } from "vitest";
+import JSZip from "jszip";
+import {
+  MAX_TOTAL_UNCOMPRESSED_BYTES,
+  validateSkillZip,
+} from "./zipValidator";
+
+async function zipToFile(zip: JSZip): Promise<File> {
+  const blob = await zip.generateAsync({ type: "blob" });
+  return new File([blob], "skill.zip");
+}
+
+describe("validateSkillZip — zip-slip defence (#443)", () => {
+  test("rejects a path with .. segment", async () => {
+    const zip = new JSZip();
+    zip.file("SKILL.md", "---\nname: x\n---\nbody");
+    zip.file("../escape.txt", "i should not exist outside the skill dir");
+    const file = await zipToFile(zip);
+
+    const result = await validateSkillZip(file);
+    // JSZip normalises `../` at archive-write time, so the entry
+    // surfaces with the leading-slash form — the unsafe-path check
+    // still has to fire on the normalised path.
+    expect(result.status).toBe("invalid");
+    expect(result.errors[0]?.key).toBe("errors.zip.unsafePath");
+  });
+
+  test("rejects a path starting with /", async () => {
+    const zip = new JSZip();
+    zip.file("SKILL.md", "---\nname: x\n---\nbody");
+    zip.file("/etc/passwd", "root:x:0:0");
+    const file = await zipToFile(zip);
+
+    const result = await validateSkillZip(file);
+    expect(result.status).toBe("invalid");
+    expect(result.errors[0]?.key).toBe("errors.zip.unsafePath");
+  });
+
+  test("rejects a backslash path (Windows path separator)", async () => {
+    const zip = new JSZip();
+    zip.file("SKILL.md", "---\nname: x\n---\nbody");
+    zip.file("scripts\\nested\\evil.bat", "echo pwned");
+    const file = await zipToFile(zip);
+
+    const result = await validateSkillZip(file);
+    expect(result.status).toBe("invalid");
+    expect(result.errors[0]?.key).toBe("errors.zip.unsafePath");
+  });
+
+  test("rejects a Windows drive-letter prefix", async () => {
+    const zip = new JSZip();
+    zip.file("SKILL.md", "---\nname: x\n---\nbody");
+    // Use a backslash-free version since the backslash check fires first.
+    zip.file("C:/Windows/system32/evil.bat", "echo pwned");
+    const file = await zipToFile(zip);
+
+    const result = await validateSkillZip(file);
+    expect(result.status).toBe("invalid");
+    expect(result.errors[0]?.key).toBe("errors.zip.unsafePath");
+  });
+});
+
+describe("validateSkillZip — uncompressed-size cap (#443)", () => {
+  test("rejects when cumulative uncompressed bytes exceed the cap", async () => {
+    const zip = new JSZip();
+    zip.file("SKILL.md", "---\nname: x\n---\nbody");
+    // Single file just over the cap (highly compressible so the ZIP
+    // itself stays tiny — that's the bomb pattern).
+    const huge = "A".repeat(MAX_TOTAL_UNCOMPRESSED_BYTES + 1);
+    zip.file("references/huge.txt", huge);
+    const file = await zipToFile(zip);
+
+    const result = await validateSkillZip(file);
+    expect(result.status).toBe("invalid");
+    expect(result.errors[0]?.key).toBe("errors.zip.uncompressedTooLarge");
+    expect((result.errors[0]?.params?.max as number) ?? 0).toBe(
+      MAX_TOTAL_UNCOMPRESSED_BYTES,
+    );
+  });
+
+  test("accepts a ZIP comfortably under the cap", async () => {
+    const zip = new JSZip();
+    zip.file("SKILL.md", "---\nname: x\nversion: \"1.0\"\nmetadata:\n  category: text\n---\nbody");
+    zip.file("references/note.md", "small file");
+    const file = await zipToFile(zip);
+
+    const result = await validateSkillZip(file);
+    // The frontmatter parse warning is allowed; what we care about
+    // here is that the cap didn't fire.
+    expect(result.errors.find((e) => e.key === "errors.zip.uncompressedTooLarge")).toBeUndefined();
+  });
+});
diff --git a/ornn-web/src/utils/zipValidator.ts b/ornn-web/src/utils/zipValidator.ts
index 8320a702..4aea646c 100644
--- a/ornn-web/src/utils/zipValidator.ts
+++ b/ornn-web/src/utils/zipValidator.ts
@@ -30,6 +30,37 @@ export interface ZipValidationResult {
 /** Recognized top-level directories in a skill package */
 const RECOGNIZED_DIRS = new Set(["scripts", "references", "assets"]);
 
+/**
+ * Cumulative uncompressed-size cap for a skill ZIP (#443). 50 MB is
+ * larger than any plausible legit skill package today; it caps zip-
+ * bomb expansion before we try to decompress every entry into memory.
+ */
+export const MAX_TOTAL_UNCOMPRESSED_BYTES = 50 * 1024 * 1024;
+
+/**
+ * Explicit zip-slip / unsafe-path predicate (#443). JSZip handles
+ * traversal internally for `.file()` lookups, but the validator's path
+ * logic is string-prefix based; if JSZip's protection ever lapses or
+ * we switch unzip library, the existing code would happily resolve
+ * `../escape.txt` outside the skill directory. Cheap, explicit defence:
+ *
+ *   - reject any segment equal to `..`
+ *   - reject any path that starts with `/` (absolute) or contains `:`
+ *     (Windows drive prefix — `C:\\evil.bat`)
+ *   - reject backslash anywhere (PKZip allows them; some tooling treats
+ *     them as path separators after extraction)
+ */
+function isUnsafeEntryPath(rawPath: string): boolean {
+  if (rawPath.startsWith("/")) return true;
+  if (rawPath.includes("\\")) return true;
+  if (/^[A-Za-z]:/.test(rawPath)) return true;
+  const segments = rawPath.split("/");
+  for (const seg of segments) {
+    if (seg === "..") return true;
+  }
+  return false;
+}
+
 /** OS-generated junk files to filter out */
 const JUNK_FILE_NAMES = new Set([
   ".DS_Store",
@@ -86,7 +117,10 @@ export function isBinaryContent(content: Uint8Array): boolean {
  * Determines the skill folder for a given file path.
  */
 function getFolder(path: string): SkillFolder {
-  const firstSegment = path.split("/")[0];
+  // `split("/")[0]` is always present — it's the substring before the
+  // first `/`, or the whole string when there's no separator. `!` is
+  // safe under noUncheckedIndexedAccess (#450).
+  const firstSegment = path.split("/")[0]!;
   if (RECOGNIZED_DIRS.has(firstSegment)) {
     return firstSegment as SkillFolder;
   }
@@ -108,11 +142,13 @@ function normalizeEntries(
   // the ZIP wraps everything in a single root folder
   if (
     topLevelEntries.length === 1 &&
-    topLevelEntries[0].dir
+    topLevelEntries[0]!.dir
   ) {
-    const prefix = topLevelEntries[0].path.endsWith("/")
-      ? topLevelEntries[0].path
-      : topLevelEntries[0].path + "/";
+    // Length-guarded above (`topLevelEntries.length === 1`) — index 0
+    // is guaranteed defined. `!` is safe under
+    // noUncheckedIndexedAccess (#450).
+    const entry = topLevelEntries[0]!;
+    const prefix = entry.path.endsWith("/") ? entry.path : entry.path + "/";
 
     const normalized = entries
       .filter((e) => e.path !== prefix && e.path.startsWith(prefix))
@@ -152,13 +188,60 @@ export async function validateSkillZip(
     };
   }
 
-  // Collect all entries, filtering out OS junk files
+  // Collect all entries, filtering out OS junk files. Reject any entry
+  // whose path tries to escape the skill directory (#443) and bail
+  // when the cumulative uncompressed size exceeds the cap. Both checks
+  // run during forEach so we never enter the extraction loop on a
+  // hostile ZIP.
   const rawEntries: Array<{ path: string; dir: boolean }> = [];
+  let unsafePath: string | null = null;
+  let totalUncompressed = 0;
   zip.forEach((relativePath, entry) => {
     if (isJunkPath(relativePath)) return;
+    if (isUnsafeEntryPath(relativePath)) {
+      unsafePath = relativePath;
+      return;
+    }
+    // JSZip exposes uncompressed size through `_data.uncompressedSize`
+    // on the internal CompressedObject. Public API doesn't surface it
+    // pre-decompression; this is the only way to refuse a zip-bomb
+    // without first decompressing it.
+    const entryWithInternal = entry as unknown as {
+      _data?: { uncompressedSize?: number };
+    };
+    const uncompressed = entryWithInternal._data?.uncompressedSize ?? 0;
+    totalUncompressed += uncompressed;
     rawEntries.push({ path: relativePath, dir: entry.dir });
   });
 
+  if (unsafePath !== null) {
+    return {
+      status: "invalid",
+      files: [],
+      metadata: null,
+      errors: [{ key: "errors.zip.unsafePath", params: { path: unsafePath } }],
+      warnings: [],
+    };
+  }
+
+  if (totalUncompressed > MAX_TOTAL_UNCOMPRESSED_BYTES) {
+    return {
+      status: "invalid",
+      files: [],
+      metadata: null,
+      errors: [
+        {
+          key: "errors.zip.uncompressedTooLarge",
+          params: {
+            actual: totalUncompressed,
+            max: MAX_TOTAL_UNCOMPRESSED_BYTES,
+          },
+        },
+      ],
+      warnings: [],
+    };
+  }
+
   const { normalized, prefix } = normalizeEntries(rawEntries);
 
   // Find all SKILL.md files
@@ -185,7 +268,9 @@ export async function validateSkillZip(
     if (entry.dir && !entry.path.includes("/")) {
       topDirs.add(entry.path.replace("/", ""));
     } else if (!entry.dir && entry.path.includes("/")) {
-      const firstDir = entry.path.split("/")[0];
+      // `split("/")[0]` is always present when the string contains
+      // "/". `!` is safe under noUncheckedIndexedAccess (#450).
+      const firstDir = entry.path.split("/")[0]!;
       topDirs.add(firstDir);
     }
   }
diff --git a/ornn-web/tsconfig.json b/ornn-web/tsconfig.json
index 984952b3..69972f0b 100644
--- a/ornn-web/tsconfig.json
+++ b/ornn-web/tsconfig.json
@@ -6,6 +6,9 @@
     "moduleResolution": "bundler",
     "jsx": "react-jsx",
     "strict": true,
+    "noImplicitOverride": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
     "noUnusedLocals": true,
     "noUnusedParameters": true,
     "noFallthroughCasesInSwitch": true,
diff --git a/package.json b/package.json
index fc7e3729..b92bdd79 100644
--- a/package.json
+++ b/package.json
@@ -14,6 +14,10 @@
     "test:api": "bun run --filter ornn-api test",
     "test:web": "bun run --filter ornn-web test",
     "test:sdk": "bun run --filter @chronoai/ornn-sdk test",
+    "test:coverage": "bun run test:api:coverage && bun run test:web:coverage && bun run test:sdk:coverage",
+    "test:api:coverage": "cd ornn-api && bun test --coverage --coverage-reporter=lcov --coverage-dir=coverage",
+    "test:web:coverage": "cd ornn-web && bun run test -- --coverage --coverage.reporter=lcov --coverage.reportsDirectory=coverage",
+    "test:sdk:coverage": "cd sdk/typescript && bun run test -- --coverage --coverage.reporter=lcov --coverage.reportsDirectory=coverage",
     "changeset": "changeset",
     "version-packages": "changeset version",
     "lint": "eslint ornn-api/src ornn-web/src sdk/typescript/src",
diff --git a/sdk/python/README.md b/sdk/python/README.md
index 5cb5e581..f5d50907 100644
--- a/sdk/python/README.md
+++ b/sdk/python/README.md
@@ -8,6 +8,18 @@ Wraps the `/api/v1/*` HTTP surface with auth injection, response-envelope unwrap
 
 ## Install
 
+> **Status: pre-publish.** Not yet on PyPI — both SDKs are held for v1.0 so the surface stops shifting under early adopters. See [`docs/SDK_PUBLISHING.md`](../../docs/SDK_PUBLISHING.md) and [#473](https://github.com/ChronoAIProject/Ornn/issues/473).
+
+Until v1 ships, install editable from source:
+
+```bash
+pip install -e ./sdk/python
+# or pin via git
+pip install "git+https://github.com/ChronoAIProject/Ornn.git#subdirectory=sdk/python"
+```
+
+Once v1 publishes:
+
 ```bash
 pip install ornn-sdk
 # or with uv / poetry / pdm — whichever you prefer
diff --git a/sdk/python/pyproject.toml b/sdk/python/pyproject.toml
index 85f4935f..edab062f 100644
--- a/sdk/python/pyproject.toml
+++ b/sdk/python/pyproject.toml
@@ -10,7 +10,17 @@ readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "MIT" }
 authors = [{ name = "Chrono AI" }]
-keywords = ["ornn", "skills", "ai", "agents", "nyxid"]
+keywords = [
+    "ornn",
+    "agent",
+    "skill-registry",
+    "skill-lifecycle",
+    "ai-agents",
+    "model-agnostic",
+    "mcp",
+    "llm",
+    "sdk",
+]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Programming Language :: Python :: 3",
@@ -21,14 +31,23 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
 ]
 dependencies = [
-    "httpx>=0.27",
+    # Upper bound (#445) — keep us inside the 0.x line until we
+    # actively vet a 1.x bump. Unbounded would let a future major
+    # release land in CI silently.
+    "httpx>=0.27,<1.0",
 ]
 
 [project.optional-dependencies]
 dev = [
-    "pytest>=8",
-    "respx>=0.21",
-    "pytest-asyncio>=0.23",
+    # pytest 9.0.3+ closes CVE-2025-71176; widen the bound so 10.x
+    # still pins us inside a tested major.
+    "pytest>=9.0.3,<10",
+    "respx>=0.21,<1.0",
+    "pytest-asyncio>=0.23,<2.0",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    # Coverage reporter — feeds Codecov on every PR (#471).
+    "pytest-cov>=5",
 ]
 
 [project.urls]
@@ -41,3 +60,50 @@ packages = ["src/ornn_sdk"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 asyncio_mode = "auto"
+
+# ──────────────── ruff (#583) ────────────────
+# Lint + format the SDK. Default ruleset (E, W, F) + isort (I) + a few
+# refinements that catch the bugs we'd actually see in a thin HTTP
+# client: pyflakes is the floor, bugbear catches misuse, pyupgrade
+# keeps us on modern Python.
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "UP"]
+ignore = [
+    # pytest fixtures legitimately use names that shadow outer scope.
+    "F811",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    # Test fixtures shadow names freely; allowed.
+    "F811",
+    # Tests use long mock data strings.
+    "E501",
+]
+
+# ──────────────── mypy (#583) ────────────────
+# Strict-ish gate on the SDK surface; the public client is the one
+# place we cannot let type drift go unobserved. Tests run in a looser
+# config because respx fixtures are dynamically typed.
+[tool.mypy]
+python_version = "3.10"
+files = ["src"]
+strict = true
+# `Any` from upstream (httpx, respx) is expected at the boundary;
+# our internal code stays strict.
+disallow_any_unimported = false
+warn_unused_ignores = true
+show_error_codes = true
+# httpx ships its own inline types; older typeshed stubs may not
+# expose every method. Permit the import without per-line ignores.
+[[tool.mypy.overrides]]
+module = "httpx.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+ignore_errors = true
diff --git a/sdk/python/src/ornn_sdk/client.py b/sdk/python/src/ornn_sdk/client.py
index f20121f0..070d2542 100644
--- a/sdk/python/src/ornn_sdk/client.py
+++ b/sdk/python/src/ornn_sdk/client.py
@@ -80,7 +80,7 @@ def __init__(
     def close(self) -> None:
         self._http.close()
 
-    def __enter__(self) -> "OrnnClient":
+    def __enter__(self) -> OrnnClient:
         return self
 
     def __exit__(self, *_: Any) -> None:
@@ -104,7 +104,8 @@ def search(
         """Search skills. Returns a paginated :class:`SkillSearchResult`."""
         params: dict[str, str] = {}
         if q is not None:
-            params["query"] = q
+            # Canonical search param is `q` per CONVENTIONS.md §4.1 (#586).
+            params["q"] = q
         if scope is not None:
             params["scope"] = scope
         if category is not None:
@@ -138,10 +139,14 @@ def list_versions(self, guid_or_name: str) -> list[SkillVersionEntry]:
 
     def download_package(self, guid: str, version: str) -> bytes:
         """Download a skill package ZIP. Returns raw bytes."""
-        res = self._raw_request("GET", f"/skills/{_quote(guid)}/versions/{_quote(version)}/download")
+        path = f"/skills/{_quote(guid)}/versions/{_quote(version)}/download"
+        res = self._raw_request("GET", path)
         if res.status_code >= 400:
             raise _build_error(res)
-        return res.content
+        # httpx exposes res.content as bytes at runtime; the typeshed
+        # stub annotates it as Any. Cast explicitly so strict mypy is
+        # happy without disabling the rule.
+        return bytes(res.content)
 
     def publish(self, zip_bytes: bytes, *, skip_validation: bool = False) -> SkillDetail:
         """Publish a new skill from a ZIP package (raw bytes)."""
@@ -202,6 +207,10 @@ def request(self, method: str, path: str, **kwargs: Any) -> Any:
 
         Returns the unwrapped ``data`` field on success. Raises
         :class:`OrnnError` on any failure.
+
+        Success responses keep the legacy ``{data, error: null}`` envelope.
+        Error responses are RFC 7807 ``application/problem+json`` (#456) —
+        fields at the body root.
         """
         res = self._raw_request(method, path, **kwargs)
         body: Any = None
@@ -209,8 +218,14 @@ def request(self, method: str, path: str, **kwargs: Any) -> Any:
             body = res.json()
         except ValueError:
             body = None
-        if res.status_code >= 400 or not isinstance(body, dict) or body.get("error") is not None:
+        if res.status_code >= 400:
             raise _build_error(res, body)
+        if not isinstance(body, dict) or body.get("error") is not None:
+            raise OrnnError(
+                status=res.status_code,
+                code="unknown_error",
+                message=f"Ornn API returned {res.status_code} with an unexpected body shape",
+            )
         return body.get("data")
 
     # ---- Plumbing -----------------------------------------------------------
@@ -231,22 +246,29 @@ def _quote(segment: str) -> str:
 
 
 def _build_error(res: httpx.Response, body: Any | None = None) -> OrnnError:
+    """Build an OrnnError from an RFC 7807 problem+json response (#456).
+
+    Fields live at the body root now (``code``, ``status``, ``detail``,
+    ``title``, ``type``, ``instance``, ``requestId``, optional
+    ``errors[]``). The pre-#456 ``{data, error: {…}}`` envelope is no
+    longer emitted.
+    """
     if body is None:
         try:
             body = res.json()
         except ValueError:
             body = None
-    if isinstance(body, dict) and isinstance(body.get("error"), dict):
-        err = body["error"]
+    if isinstance(body, dict) and (body.get("code") or body.get("detail") or body.get("title")):
+        message = body.get("detail") or body.get("title") or f"Ornn API returned {res.status_code}"
         return OrnnError(
-            status=res.status_code,
-            code=str(err.get("code") or "unknown_error"),
-            message=str(err.get("message") or f"Ornn API returned {res.status_code}"),
-            request_id=err.get("requestId"),
-            errors=list(err.get("errors") or []) or None,
+            status=int(body.get("status") or res.status_code),
+            code=str(body.get("code") or "unknown_error"),
+            message=str(message),
+            request_id=body.get("requestId"),
+            errors=list(body.get("errors") or []) or None,
         )
     return OrnnError(
         status=res.status_code,
         code="unknown_error",
-        message=f"Ornn API returned {res.status_code} without a recognized error envelope",
+        message=f"Ornn API returned {res.status_code} without a recognized error body",
     )
diff --git a/sdk/python/src/ornn_sdk/types.py b/sdk/python/src/ornn_sdk/types.py
index fcea894a..4629eac5 100644
--- a/sdk/python/src/ornn_sdk/types.py
+++ b/sdk/python/src/ornn_sdk/types.py
@@ -35,7 +35,7 @@ class SkillSummary:
     _extra: dict[str, Any] = field(default_factory=dict, repr=False)
 
     @classmethod
-    def from_dict(cls, raw: dict[str, Any]) -> "SkillSummary":
+    def from_dict(cls, raw: dict[str, Any]) -> SkillSummary:
         known = {
             "id",
             "name",
@@ -66,16 +66,17 @@ def from_dict(cls, raw: dict[str, Any]) -> "SkillSummary":
 
 @dataclass
 class SkillDetail(SkillSummary):
-    owner_id: str = ""
     storage_key: str | None = None
     shared_with_users: list[str] = field(default_factory=list)
     shared_with_orgs: list[str] = field(default_factory=list)
 
     @classmethod
-    def from_dict(cls, raw: dict[str, Any]) -> "SkillDetail":
+    def from_dict(cls, raw: dict[str, Any]) -> SkillDetail:
         base = SkillSummary.from_dict(raw).__dict__
         base.pop("_extra")
-        known_extra = {"ownerId", "storageKey", "sharedWithUsers", "sharedWithOrgs"}
+        # `ownerId` was removed from the wire in #581 — tolerate it
+        # showing up on old API responses (treat as unknown extra).
+        known_extra = {"storageKey", "sharedWithUsers", "sharedWithOrgs"}
         summary_known = {
             "id",
             "name",
@@ -91,11 +92,10 @@ def from_dict(cls, raw: dict[str, Any]) -> "SkillDetail":
         extra = {
             k: v
             for k, v in raw.items()
-            if k not in summary_known and k not in known_extra
+            if k not in summary_known and k not in known_extra and k != "ownerId"
         }
         return cls(
             **base,
-            owner_id=raw.get("ownerId", ""),
             storage_key=raw.get("storageKey"),
             shared_with_users=list(raw.get("sharedWithUsers") or []),
             shared_with_orgs=list(raw.get("sharedWithOrgs") or []),
@@ -113,7 +113,7 @@ class SkillVersionEntry:
     deprecation_note: str | None = None
 
     @classmethod
-    def from_dict(cls, raw: dict[str, Any]) -> "SkillVersionEntry":
+    def from_dict(cls, raw: dict[str, Any]) -> SkillVersionEntry:
         return cls(
             version=raw["version"],
             created_on=raw.get("createdOn", ""),
@@ -134,7 +134,7 @@ class SkillSearchResult:
     mode: str | None = None
 
     @classmethod
-    def from_dict(cls, raw: dict[str, Any]) -> "SkillSearchResult":
+    def from_dict(cls, raw: dict[str, Any]) -> SkillSearchResult:
         return cls(
             items=[SkillSummary.from_dict(i) for i in raw.get("items") or []],
             total=int(raw.get("total", 0)),
diff --git a/sdk/python/tests/test_client.py b/sdk/python/tests/test_client.py
index a4fc31cd..16d1b09f 100644
--- a/sdk/python/tests/test_client.py
+++ b/sdk/python/tests/test_client.py
@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import httpx
 import pytest
 import respx
 
@@ -14,7 +13,6 @@
     UpdateSkillMetadata,
 )
 
-
 BASE = "https://ornn.example.com"
 
 
@@ -44,9 +42,7 @@ def test_injects_static_token(self) -> None:
 
     @respx.mock
     def test_resolver_takes_precedence(self) -> None:
-        route = respx.get(f"{BASE}/api/v1/me").respond(
-            200, json={"data": {}, "error": None}
-        )
+        route = respx.get(f"{BASE}/api/v1/me").respond(200, json={"data": {}, "error": None})
         with make_client(
             token="tok_static",
             token_resolver=lambda: "tok_dynamic",
@@ -56,9 +52,7 @@ def test_resolver_takes_precedence(self) -> None:
 
     @respx.mock
     def test_no_auth_header_when_no_token(self) -> None:
-        route = respx.get(f"{BASE}/api/v1/public").respond(
-            200, json={"data": {}, "error": None}
-        )
+        route = respx.get(f"{BASE}/api/v1/public").respond(200, json={"data": {}, "error": None})
         with make_client() as ornn:
             ornn.request("GET", "/public")
         assert "authorization" not in route.calls.last.request.headers
@@ -75,16 +69,18 @@ def test_unwraps_success(self) -> None:
         assert result == {"hello": "world"}
 
     @respx.mock
-    def test_raises_ornn_error_on_failure_envelope(self) -> None:
+    def test_raises_ornn_error_on_problem_json(self) -> None:
+        # 4xx body is RFC 7807 problem+json (#456) — root-level fields.
         respx.get(f"{BASE}/api/v1/admin").respond(
             403,
             json={
-                "data": None,
-                "error": {
-                    "code": "permission_denied",
-                    "message": "Missing ornn:skill:admin",
-                    "requestId": "req_01HXYZ",
-                },
+                "type": "https://github.com/.../ERRORS.md#permission_denied",
+                "title": "Permission denied",
+                "status": 403,
+                "code": "permission_denied",
+                "detail": "Missing ornn:skill:admin",
+                "instance": "/v1/admin",
+                "requestId": "req_01HXYZ",
             },
         )
         with make_client() as ornn:
@@ -108,17 +104,19 @@ def test_raises_on_unenveloped_5xx(self) -> None:
 
     @respx.mock
     def test_preserves_structured_errors_list(self) -> None:
+        # `errors[]` rides at the body root inside problem+json (#456).
         respx.post(f"{BASE}/api/v1/skills").respond(
             400,
             json={
-                "data": None,
-                "error": {
-                    "code": "validation_error",
-                    "message": "Validation failed",
-                    "errors": [
-                        {"path": "name", "code": "required", "message": "name is required"},
-                    ],
-                },
+                "type": "https://github.com/.../ERRORS.md#validation_error",
+                "title": "Validation failed",
+                "status": 400,
+                "code": "validation_error",
+                "detail": "Validation failed",
+                "instance": "/v1/skills",
+                "errors": [
+                    {"path": "name", "code": "required", "message": "name is required"},
+                ],
             },
         )
         with make_client() as ornn:
@@ -131,7 +129,7 @@ def test_preserves_structured_errors_list(self) -> None:
 
 class TestSearch:
     @respx.mock
-    def test_maps_q_to_query_param(self) -> None:
+    def test_maps_q_to_canonical_q_param(self) -> None:
         route = respx.get(f"{BASE}/api/v1/skill-search").respond(
             200,
             json={
@@ -149,7 +147,9 @@ def test_maps_q_to_query_param(self) -> None:
             result = ornn.search(q="pdf", scope="public", page=2, page_size=50)
         assert isinstance(result, SkillSearchResult)
         req_url = str(route.calls.last.request.url)
-        assert "query=pdf" in req_url
+        # Canonical search param is `q` (CONVENTIONS.md §4.1 / #586).
+        assert "q=pdf" in req_url
+        assert "query=pdf" not in req_url
         assert "scope=public" in req_url
         assert "page=2" in req_url
         assert "pageSize=50" in req_url
@@ -202,7 +202,6 @@ def test_url_encodes_path_segment(self) -> None:
                     "isPrivate": False,
                     "createdBy": "u1",
                     "createdOn": "2026-01-01T00:00:00Z",
-                    "ownerId": "u1",
                 },
                 "error": None,
             },
@@ -210,7 +209,7 @@ def test_url_encodes_path_segment(self) -> None:
         with make_client() as ornn:
             detail = ornn.get("my/weird name")
         assert isinstance(detail, SkillDetail)
-        assert detail.owner_id == "u1"
+        assert detail.created_by == "u1"
         assert route.called
 
     @respx.mock
@@ -218,8 +217,12 @@ def test_raises_ornn_error_on_404(self) -> None:
         respx.get(f"{BASE}/api/v1/skills/nope").respond(
             404,
             json={
-                "data": None,
-                "error": {"code": "resource_not_found", "message": "no such skill"},
+                "type": "https://github.com/.../ERRORS.md#resource_not_found",
+                "title": "Resource not found",
+                "status": 404,
+                "code": "resource_not_found",
+                "detail": "no such skill",
+                "instance": "/v1/skills/nope",
             },
         )
         with make_client() as ornn:
@@ -268,8 +271,12 @@ def test_download_raises_on_error(self) -> None:
         respx.get(f"{BASE}/api/v1/skills/abc/versions/9.9/download").respond(
             404,
             json={
-                "data": None,
-                "error": {"code": "resource_not_found", "message": "no such version"},
+                "type": "https://github.com/.../ERRORS.md#resource_not_found",
+                "title": "Resource not found",
+                "status": 404,
+                "code": "resource_not_found",
+                "detail": "no such version",
+                "instance": "/v1/skills/abc/versions/9.9/download",
             },
         )
         with make_client() as ornn:
@@ -292,7 +299,6 @@ def test_publish_sends_zip_bytes(self) -> None:
                     "isPrivate": True,
                     "createdBy": "u1",
                     "createdOn": "2026-01-01T00:00:00Z",
-                    "ownerId": "u1",
                 },
                 "error": None,
             },
@@ -317,7 +323,6 @@ def test_publish_adds_skip_validation_query(self) -> None:
                     "isPrivate": False,
                     "createdBy": "admin",
                     "createdOn": "2026-01-01T00:00:00Z",
-                    "ownerId": "admin",
                 },
                 "error": None,
             },
@@ -342,7 +347,6 @@ def test_update_metadata_sends_json(self) -> None:
                     "isPrivate": False,
                     "createdBy": "u1",
                     "createdOn": "2026-01-01T00:00:00Z",
-                    "ownerId": "u1",
                 },
                 "error": None,
             },
@@ -365,7 +369,6 @@ def test_update_with_zip_sends_zip(self) -> None:
                     "isPrivate": False,
                     "createdBy": "u1",
                     "createdOn": "2026-01-01T00:00:00Z",
-                    "ownerId": "u1",
                 },
                 "error": None,
             },
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 93123252..552cab4a 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -8,7 +8,20 @@ Wraps the `/api/v1/*` HTTP surface with auth injection, response-envelope unwrap
 
 ## Install
 
-This package lives inside the Ornn monorepo. Once published to npm:
+> **Status: pre-publish.** Not yet on npm — both SDKs are held for v1.0 so the surface stops shifting under early adopters. See [`docs/SDK_PUBLISHING.md`](../../docs/SDK_PUBLISHING.md) and [#473](https://github.com/ChronoAIProject/Ornn/issues/473).
+
+Until v1 ships, install from source via `bun link`:
+
+```bash
+# Inside the Ornn monorepo
+cd sdk/typescript
+bun link
+
+# Then in the consuming project
+bun link @chronoai/ornn-sdk
+```
+
+After v1 publishes:
 
 ```bash
 bun add @chronoai/ornn-sdk
diff --git a/sdk/typescript/package.json b/sdk/typescript/package.json
index e0dc5e6b..309cc074 100644
--- a/sdk/typescript/package.json
+++ b/sdk/typescript/package.json
@@ -3,6 +3,27 @@
   "version": "0.2.1",
   "private": true,
   "description": "TypeScript client for Ornn — the end-to-end skill life-cycle manager for AI agents",
+  "keywords": [
+    "ornn",
+    "agent",
+    "skill-registry",
+    "skill-lifecycle",
+    "ai-agents",
+    "model-agnostic",
+    "mcp",
+    "llm",
+    "sdk"
+  ],
+  "homepage": "https://github.com/ChronoAIProject/Ornn#readme",
+  "bugs": {
+    "url": "https://github.com/ChronoAIProject/Ornn/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChronoAIProject/Ornn.git",
+    "directory": "sdk/typescript"
+  },
+  "license": "MIT",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.ts
index b60fb9ed..02e625af 100644
--- a/sdk/typescript/src/client.ts
+++ b/sdk/typescript/src/client.ts
@@ -41,18 +41,22 @@ interface EnvelopeSuccess<T> {
   readonly error: null;
 }
 
-interface EnvelopeFailure {
-  readonly data: null;
-  readonly error: {
-    readonly code: string;
-    readonly message: string;
-    readonly requestId?: string;
-    readonly errors?: ReadonlyArray<{ path?: string; code?: string; message: string }>;
-  };
+/**
+ * Wire shape for error responses post-#456 — RFC 7807
+ * `application/problem+json`. Fields at the body root; `error` /
+ * `data` are gone.
+ */
+interface ProblemJson {
+  readonly type?: string;
+  readonly title?: string;
+  readonly status?: number;
+  readonly code?: string;
+  readonly detail?: string;
+  readonly instance?: string;
+  readonly requestId?: string;
+  readonly errors?: ReadonlyArray<{ path?: string; code?: string; message: string }>;
 }
 
-type Envelope<T> = EnvelopeSuccess<T> | EnvelopeFailure;
-
 export class OrnnClient {
   private readonly baseUrl: string;
   private readonly staticToken: string | undefined;
@@ -74,16 +78,23 @@ export class OrnnClient {
 
   // ---- Public API ----
 
-  /** Search skills. Returns paginated results with `items` + pagination meta. */
-  async search(params: SkillSearchParams = {}): Promise<SkillSearchResult> {
+  /** Search skills. Returns one page; for cross-page iteration use `searchAll()`. */
+  async search(
+    params: SkillSearchParams & { cursor?: string; limit?: number } = {},
+  ): Promise<SkillSearchResult> {
     const query = new URLSearchParams();
-    if (params.q) query.set("query", params.q);
+    // Per CONVENTIONS.md §4.1 (#586) the canonical search param is `q`.
+    if (params.q) query.set("q", params.q);
     if (params.scope) query.set("scope", params.scope);
     if (params.category) query.set("category", params.category);
     if (params.tag) query.set("tag", params.tag);
     if (params.runtime) query.set("runtime", params.runtime);
     if (params.mode) query.set("mode", params.mode);
     if (params.systemFilter) query.set("systemFilter", params.systemFilter);
+    // Cursor pagination (#457). When `cursor` is set, server uses it
+    // instead of `page`; both are still accepted for backward compat.
+    if (params.cursor !== undefined) query.set("cursor", params.cursor);
+    if (params.limit !== undefined) query.set("limit", String(params.limit));
     if (params.page !== undefined) query.set("page", String(params.page));
     if (params.pageSize !== undefined) query.set("pageSize", String(params.pageSize));
     const qs = query.toString();
@@ -93,6 +104,40 @@ export class OrnnClient {
     );
   }
 
+  /**
+   * Auto-paginating iterator (#465). Yields every matching skill across
+   * pages; fetches the next page on demand using `meta.nextCursor`:
+   *
+   * ```ts
+   * for await (const skill of client.searchAll({ q: "pdf" })) {
+   *   console.log(skill.name);
+   * }
+   * ```
+   *
+   * Stops cleanly when the server returns `meta.hasMore === false` (or
+   * no `nextCursor`). Per-page errors surface as `OrnnError` and stop
+   * iteration — wrap in try/catch if you want to skip-and-continue.
+   */
+  async *searchAll(
+    params: SkillSearchParams & { limit?: number } = {},
+  ): AsyncIterableIterator<SkillSearchResult["items"][number]> {
+    let cursor: string | undefined;
+    // Loop guard — the server contract says nextCursor only appears
+    // when there's a next page, so this loop terminates naturally on
+    // the last page. Cap at 10k pages defensively in case a misbehaving
+    // server returns nextCursor forever; 10k pages × default limit (9)
+    // is ~90k items which exceeds every realistic registry.
+    for (let i = 0; i < 10_000; i++) {
+      const page: SkillSearchResult = await this.search(
+        cursor !== undefined ? { ...params, cursor } : params,
+      );
+      for (const item of page.items) yield item;
+      const next = page.meta?.nextCursor;
+      if (!next || page.meta?.hasMore === false) return;
+      cursor = next;
+    }
+  }
+
   /** Fetch a single skill by GUID or name. */
   async get(guidOrName: string, version?: string): Promise<SkillDetail> {
     const suffix = version ? `?version=${encodeURIComponent(version)}` : "";
@@ -182,11 +227,21 @@ export class OrnnClient {
     init: { body?: BodyInit; headers?: Record<string, string> } = {},
   ): Promise<T> {
     const res = await this.rawRequest(method, path, init);
-    const body = (await res.json().catch(() => null)) as Envelope<T> | null;
-    if (!res.ok || !body || body.error !== null) {
-      throw buildError(res.status, body);
+    const body = (await res.json().catch(() => null)) as unknown;
+    if (!res.ok) {
+      // Error responses are RFC 7807 (#456) — fields at the body root.
+      throw buildError(res.status, body as ProblemJson | null);
+    }
+    // Success responses keep the `{ data, error: null }` envelope.
+    const env = body as EnvelopeSuccess<T> | null;
+    if (!env || env.error !== null) {
+      throw new OrnnError({
+        status: res.status,
+        code: "unknown_error",
+        message: `Ornn API returned ${res.status} with an unexpected body shape`,
+      });
     }
-    return (body as EnvelopeSuccess<T>).data;
+    return env.data;
   }
 
   private async rawRequest(
@@ -199,10 +254,14 @@ export class OrnnClient {
     if (token) {
       headers.Authorization = `Bearer ${token}`;
     }
+    // exactOptionalPropertyTypes (#450): `RequestInit.body` is
+    // `BodyInit | null`, not optional-`undefined`. Only set the key
+    // when we actually have a body so we don't pass `body: undefined`
+    // (rejected under the stricter contract).
     return this.fetchImpl(`${this.baseUrl}/api/v1${path}`, {
       method,
-      body: init.body,
       headers,
+      ...(init.body !== undefined ? { body: init.body } : {}),
     });
   }
 }
@@ -213,25 +272,29 @@ function zipToBlob(zip: Blob | ArrayBuffer | Uint8Array): Blob {
 }
 
 async function parseError(res: Response): Promise<OrnnError> {
-  const body = (await res.json().catch(() => null)) as Envelope<unknown> | null;
+  const body = (await res.json().catch(() => null)) as ProblemJson | null;
   return buildError(res.status, body);
 }
 
-function buildError(status: number, body: Envelope<unknown> | null): OrnnError {
-  if (body && body.error) {
-    const err = body.error;
+function buildError(status: number, body: ProblemJson | null): OrnnError {
+  if (body && (body.code || body.detail || body.title)) {
+    // exactOptionalPropertyTypes (#450): only stamp `requestId` /
+    // `errors` keys when the upstream actually provided them — the
+    // payload type is `requestId?: string`, not `string | undefined`,
+    // so `{ requestId: undefined }` is a type error under the
+    // stricter contract.
     const payload: OrnnErrorPayload = {
-      status,
-      code: err.code,
-      message: err.message,
-      requestId: err.requestId,
-      errors: err.errors,
+      status: body.status ?? status,
+      code: body.code ?? "unknown_error",
+      message: body.detail ?? body.title ?? `Ornn API returned ${status}`,
+      ...(body.requestId !== undefined ? { requestId: body.requestId } : {}),
+      ...(body.errors !== undefined ? { errors: body.errors } : {}),
     };
     return new OrnnError(payload);
   }
   return new OrnnError({
     status,
     code: "unknown_error",
-    message: `Ornn API returned ${status} without a recognized error envelope`,
+    message: `Ornn API returned ${status} without a recognized error body`,
   });
 }
diff --git a/sdk/typescript/src/errors.ts b/sdk/typescript/src/errors.ts
index 5f4e374b..339aa844 100644
--- a/sdk/typescript/src/errors.ts
+++ b/sdk/typescript/src/errors.ts
@@ -32,7 +32,11 @@ export class OrnnError extends Error implements OrnnErrorPayload {
     this.name = "OrnnError";
     this.status = payload.status;
     this.code = payload.code;
-    this.requestId = payload.requestId;
-    this.errors = payload.errors;
+    // exactOptionalPropertyTypes (#450): `{ foo?: string }` no longer
+    // accepts an assignment of `string | undefined`. Only assign when
+    // the upstream value is actually set so we don't materialise an
+    // `undefined`-valued key.
+    if (payload.requestId !== undefined) this.requestId = payload.requestId;
+    if (payload.errors !== undefined) this.errors = payload.errors;
   }
 }
diff --git a/sdk/typescript/src/tests/client.test.ts b/sdk/typescript/src/tests/client.test.ts
index 8a171b71..3769cc25 100644
--- a/sdk/typescript/src/tests/client.test.ts
+++ b/sdk/typescript/src/tests/client.test.ts
@@ -89,15 +89,16 @@ describe("OrnnClient", () => {
     expect(result.items[0]!.id).toBe("abc");
   });
 
-  test("throws OrnnError with code + status + requestId on envelope failure", async () => {
+  test("throws OrnnError parsing RFC 7807 problem+json body (#456)", async () => {
     const fetchMock = mockFetch(() =>
       jsonResponse(403, {
-        data: null,
-        error: {
-          code: "permission_denied",
-          message: "Missing ornn:skill:admin",
-          requestId: "req_01",
-        },
+        type: "https://github.com/.../ERRORS.md#permission_denied",
+        title: "Permission denied",
+        status: 403,
+        code: "permission_denied",
+        detail: "Missing ornn:skill:admin",
+        instance: "/v1/admin/stats",
+        requestId: "req_01",
       }),
     );
     const client = new OrnnClient({ baseUrl: "https://x", fetch: fetchMock });
@@ -123,7 +124,7 @@ describe("OrnnClient", () => {
     expect(err.code).toBe("unknown_error");
   });
 
-  test("search(): maps q → query and appends params correctly", async () => {
+  test("search(): sends q= and appends params correctly", async () => {
     let capturedUrl = "";
     const fetchMock = mockFetch((url) => {
       capturedUrl = url;
@@ -141,7 +142,9 @@ describe("OrnnClient", () => {
       pageSize: 50,
     });
     expect(capturedUrl).toContain("/api/v1/skill-search?");
-    expect(capturedUrl).toContain("query=pdf");
+    // Canonical search param per CONVENTIONS.md §4.1 (#586).
+    expect(capturedUrl).toContain("q=pdf");
+    expect(capturedUrl).not.toContain("query=pdf");
     expect(capturedUrl).toContain("scope=public");
     expect(capturedUrl).toContain("category=utils");
     expect(capturedUrl).toContain("page=2");
@@ -218,8 +221,15 @@ describe("OrnnClient", () => {
   });
 
   test("downloadPackage(): throws OrnnError on 404", async () => {
+    // 404 body is RFC 7807 problem+json (#456) — fields at the root.
     const fetchMock = mockFetch(() =>
-      jsonResponse(404, { data: null, error: { code: "resource_not_found", message: "no such version" } }),
+      jsonResponse(404, {
+        type: "https://github.com/.../ERRORS.md#resource_not_found",
+        title: "Resource not found",
+        status: 404,
+        code: "resource_not_found",
+        detail: "no such version",
+      }),
     );
     const client = new OrnnClient({ baseUrl: "https://x", fetch: fetchMock });
     const err = (await client.downloadPackage("abc", "9.9").catch((e) => e)) as OrnnError;
diff --git a/sdk/typescript/src/types.ts b/sdk/typescript/src/types.ts
index 4b6a7364..ed5b996b 100644
--- a/sdk/typescript/src/types.ts
+++ b/sdk/typescript/src/types.ts
@@ -27,7 +27,6 @@ export interface SkillSummary {
 
 /** Full skill detail returned by single-skill reads. */
 export interface SkillDetail extends SkillSummary {
-  readonly ownerId: string;
   readonly storageKey?: string;
   readonly sharedWithUsers?: readonly string[];
   readonly sharedWithOrgs?: readonly string[];
@@ -75,6 +74,18 @@ export interface SkillSearchResult {
   readonly pageSize: number;
   readonly totalPages: number;
   readonly mode?: string;
+  /**
+   * Cursor pagination envelope per CONVENTIONS.md §4.3 (#457). Use
+   * `client.searchAll({ q })` to iterate transparently — the iterator
+   * threads `meta.nextCursor` through subsequent requests.
+   *
+   * When `hasMore === false`, `nextCursor` MAY be omitted.
+   */
+  readonly meta?: {
+    readonly limit: number;
+    readonly hasMore: boolean;
+    readonly nextCursor?: string;
+  };
 }
 
 export interface UpdateSkillMetadata {
diff --git a/sdk/typescript/tsconfig.json b/sdk/typescript/tsconfig.json
index 7a51d9d6..b58a28bb 100644
--- a/sdk/typescript/tsconfig.json
+++ b/sdk/typescript/tsconfig.json
@@ -5,6 +5,9 @@
     "moduleResolution": "bundler",
     "lib": ["ES2022", "DOM"],
     "strict": true,
+    "noImplicitOverride": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
diff --git a/skills/ornn-agent-manual-cli/SKILL.md b/skills/ornn-agent-manual-cli/SKILL.md
index e95f08bc..e1fde1fb 100644
--- a/skills/ornn-agent-manual-cli/SKILL.md
+++ b/skills/ornn-agent-manual-cli/SKILL.md
@@ -9,13 +9,13 @@ metadata:
     - manual
     - skill-lifecycle
     - cli
-version: "1.1"
-lastUpdated: 2026-04-29
+version: "1.2"
+lastUpdated: 2026-05-14
 ---
 
 # Agent Manual (NyxID CLI variant)
 
-> **DEPRECATED — replaced by `chrono-ai-service-manual`.** This skill is kept for one minor release while consumers migrate. The unified manual folds NyxID identity / CLI / proxy AND the Ornn skill lifecycle into a single skill so an agent that wants to drive both halves of the stack only needs one install. **New work should pull `chrono-ai-service-manual` instead** (Ornn skill name; same auth flow, same registry, identical API contract — strict superset of this file). This file will be removed in the release after the unified manual lands.
+> **Scope.** This skill is the CLI-only operational manual for the Ornn half of the Chrono AI stack. If you also need to drive NyxID (identity, services, orgs, OAuth clients, proxy) — for example to register a new service or rotate a client — pull `chrono-ai-service-manual` instead. It is a strict superset of this file, with the same Ornn API contract plus the NyxID half folded in. This skill remains the right pick when the agent only needs Ornn skill-lifecycle operations and wants a smaller context payload.
 
 > **You are an AI agent reading this manual to learn how to use Ornn.** Throughout this document, *"you"* always refers to **the agent itself** — not the human user driving you.
 >
@@ -45,8 +45,9 @@ lastUpdated: 2026-04-29
 > - **Bind a skill to a NyxID service** (system / personal) — §2.9.
 > - **Delete a skill** entirely — §2.11.
 > - **Find skills** (by tag, author, system, shared, etc.) — §2.12.
-> - **Pull your Ornn notifications** (audit fan-out, etc.) — §2.13.
+> - **Pull your Ornn notifications** (audit fan-out, broadcasts, etc.) — §2.13.
 > - **Link a skill to GitHub** or **trigger a sync** from the linked source — §2.14.
+> - **Check your monthly quota** or **pick a valid LLM model** before calling an SSE endpoint — §2.15.
 >
 > Without this manual loaded, you do not know which endpoint to call, how to authenticate, or how to read the response shapes.
 >
@@ -124,7 +125,7 @@ nyxid proxy request ornn-api \
 
 For public skills you can drop the auth and call the same endpoint anonymously — see §2.1 step 3 for fetch alternatives.
 
-The response is `{ items: [{ version, skillHash, createdOn, isDeprecated, deprecationNote, releaseNotes, ... }, ...] }` sorted newest-first. Compare `items[0].version` to the `installedVersion` on the matching record in `~/.ornn/installed-skills.json` and act:
+The response is `{ data: { items: [{ version, skillHash, createdOn, isDeprecated, deprecationNote, releaseNotes, ... }, ...] }, error: null }` sorted newest-first. Compare `data.items[0].version` to the `installedVersion` on the matching record in `~/.ornn/installed-skills.json` and act:
 
 - **Same version** → execute as-is.
 - **Newer version available** → tell the user `"Skill <name> has a newer version <X.Y> (you have <A.B>). Release notes: <releaseNotes>. Update? (y/n)"`. If yes, re-fetch the package (§2.1 step 3), overwrite the local copy, update `installedVersion` + `installedAt` in `~/.ornn/installed-skills.json`, then execute.
@@ -179,10 +180,10 @@ Expected output includes `user_id`, `email`, `roles`, and `permissions`. Confirm
 | Generate a skill with AI (`POST /skills/generate*`) | `ornn:skill:build` |
 | Use the Playground (`POST /playground/chat`) | `ornn:playground:use` |
 | Trigger an audit (`POST /skills/:idOrName/audit`) | none (owner or `ornn:admin:skill`) |
-| Admin operations (`/admin/*`, force-audit, platform settings) | `ornn:admin:skill` |
-| Manage categories (`/admin/categories/*`) | `ornn:admin:category` |
+| Admin operations (`/admin/*`, force-audit, sectioned platform settings) | `ornn:admin:skill` |
+| Admin quota / redemption-codes operations (`/admin/quota/*`, `/admin/redemption-codes/*`, `/admin/dashboard/stats`) | `ornn:quota:admin` |
 
-Most read operations — browsing public skills, version listings, skill format rules, audit verdicts on visible skills, notifications — **need no scalar permission**; they're open to any authenticated caller (and some are anonymous). The exact gates for every endpoint live in `references/api-reference.md`.
+Most read operations — browsing public skills, version listings, skill format rules, audit verdicts on visible skills, notifications, your own quota — **need no scalar permission**; they're open to any authenticated caller (and some are anonymous). The exact gates for every endpoint live in `references/api-reference.md`.
 
 ### 1.4 Discover the Ornn service
 
@@ -580,28 +581,32 @@ Combine query params freely. The full schema (every supported filter, every resp
 Ornn sends notifications on events like audit completion (own + risky-for-consumer fan-out) and other state changes:
 
 ```bash
-# Cheap badge count
+# Cheap badge count (covers per-user notifications AND admin-authored broadcasts)
 nyxid proxy request ornn-api "/api/v1/notifications/unread-count" \
   --method GET --output json
 
-# Fetch unread notifications
+# Fetch unread items (mixed feed — per-user + broadcasts)
 nyxid proxy request ornn-api "/api/v1/notifications?unread=true&limit=50" \
   --method GET --output json
 
-# Mark one notification as read
+# Mark one item as read (accepts either a per-user notification id or a broadcast id)
 nyxid proxy request ornn-api "/api/v1/notifications/<id>/read" \
   --method POST --data '{}' --output json
 
-# Mark all as read
+# Mark every unread item as read
 nyxid proxy request ornn-api "/api/v1/notifications/mark-all-read" \
   --method POST --data '{}' --output json
 ```
 
-Two notification categories are emitted today:
+The feed is a **discriminated union**: each item carries `source: "user"` or `source: "broadcast"`. Branch on `source` before reading category-specific fields — `category`, `title`, `body`, `link`, `data` live on `source: "user"` rows only; `source: "broadcast"` rows carry bilingual `titleI18n` / `bodyMarkdownI18n` instead. Both shapes share `_id`, `readAt`, `createdAt`.
+
+Per-user (`source: "user"`) categories emitted today:
 
 - `audit.completed` — sent to the skill owner on every audit completion.
 - `audit.risky_for_consumer` — fanned out to every consumer of the skill (everyone in `sharedWithUsers` + members of every org in `sharedWithOrgs`) when a verdict comes back `yellow` or `red`. **Treat this as a hard signal to stop using the skill** until you've reviewed the findings; surface it to the user and ask before continuing.
 
+Broadcasts (`source: "broadcast"`) are platform-wide markdown notices authored by platform admins. They have no category — treat them as informational and surface them verbatim (use `titleI18n.en` / `bodyMarkdownI18n.en` unless the user has a `zh` locale).
+
 ### 2.14 Link a skill to GitHub or trigger a sync — *spec: `api-reference.md` §3.2 + §3.3 + §3.15*
 
 **When:** the user wants their Ornn skill to live in (or co-exist with) a public GitHub repo so updates flow from there into Ornn one-click. Three flows depending on starting state:
@@ -665,6 +670,29 @@ Apply response: the refreshed `SkillDetail`. `source.lastSyncedAt` and `source.l
 - `REFRESH_FAILED` (400) on apply, `REFRESH_PREVIEW_FAILED` (400) on dry-run — the upstream folder no longer exists, or the pulled package failed validation. If the upstream is trusted and the failure is validation, retry apply with `skipValidation: true`.
 - `NOT_SKILL_OWNER` (403) — the caller isn't the author and lacks `ornn:admin:skill`.
 
+### 2.15 Check your monthly quota or pick a valid LLM model — *spec: `api-reference.md` §11 Me — caller scope*
+
+The SSE endpoints (`POST /skills/generate*`, `POST /playground/chat`) both meter against a **monthly quota** and require a valid `modelId`. Two cheap reads let you avoid hitting `429 QUOTA_EXCEEDED` or `400 MODEL_NOT_ENABLED` mid-stream:
+
+```bash
+# Your current month's allotments + remaining counts for both metered surfaces
+nyxid proxy request ornn-api "/api/v1/me/quota" \
+  --method GET --output json
+
+# Pick a model the deployment has enabled for the surface you're about to call
+nyxid proxy request ornn-api "/api/v1/me/models?surface=playground" \
+  --method GET --output json
+
+nyxid proxy request ornn-api "/api/v1/me/models?surface=skillGen" \
+  --method GET --output json
+```
+
+`/me/quota` response shape: `{ data: { isAdmin, monthMarker, monthStart, monthEnd, nextMonthlyResetAt, playground: { defaultAllotment, adminGrant, used, remaining, warningThreshold, warning }, skillGen: { ... } }, error: null }`. Admins bypass quota — `isAdmin: true` means every charge is free; the per-surface numbers are still populated but never block.
+
+`/me/models` response shape: `{ data: { items: [{ modelId, displayName, isDefault }, ...], defaultModelId }, error: null }`. Pass `defaultModelId` into the generate / playground body when the user hasn't expressed a preference. The list is platform-controlled — if it's empty the admin has not enabled any model for that surface, and SSE calls will fail with `MODEL_UNAVAILABLE`.
+
+Quota refills automatically at `nextMonthlyResetAt`. If a user is low and needs more before then, they can redeem a code via `POST /api/v1/me/redemption-codes/redeem` with `{"code":"<token>"}` — the response carries the updated grants. Don't redeem codes the user hasn't given you.
+
 ---
 
 ## §3. Conventions & Pitfalls
@@ -689,5 +717,8 @@ Apply response: the refreshed `SkillDetail`. `source.lastSyncedAt` and `source.l
 - `GET /api/v1/skill-format/rules` — canonical skill package format spec, always up-to-date with what the validator enforces.
 - `GET /api/v1/openapi.json` — auto-generated OpenAPI 3 schema. Every endpoint mentioned in this manual is in here with full Zod-derived request/response types.
 - `GET /api/v1/me` — your current identity snapshot (userId, email, displayName, roles, permissions). Useful when debugging a 403.
+- `GET /api/v1/me/quota` — monthly allotment + remaining counts for both metered surfaces (`playground`, `skillGen`). Read before SSE calls so you don't hit `429 QUOTA_EXCEEDED` mid-stream (§2.15).
+- `GET /api/v1/me/models?surface=playground|skillGen` — platform-enabled LLM picker. Pass `defaultModelId` into generate / playground bodies (§2.15).
+- `GET /api/v1/announcements/active` — public, anonymous platform-wide notice (separate from `/notifications`). Useful when you want to know about maintenance windows or pricing changes before kicking off long workflows.
 
 If you find a discrepancy between this manual and the actual API behaviour, the API is right and the manual is stale — re-pull the skill (§0) before assuming a bug.
diff --git a/skills/ornn-agent-manual-cli/references/api-reference.md b/skills/ornn-agent-manual-cli/references/api-reference.md
index 3741c9c6..8da637da 100644
--- a/skills/ornn-agent-manual-cli/references/api-reference.md
+++ b/skills/ornn-agent-manual-cli/references/api-reference.md
@@ -106,8 +106,8 @@ Permissions are issued by NyxID as part of the proxy-forwarded identity. Roles m
 | `ornn:skill:delete` | `ornn-user` | `DELETE /skills/:id`, `DELETE /skills/:idOrName/versions/:version` |
 | `ornn:skill:build` | `ornn-user` | `POST /skills/generate`, `POST /skills/generate/from-source`, `POST /skills/generate/from-openapi` |
 | `ornn:playground:use` | `ornn-user` | `POST /playground/chat` |
-| `ornn:admin:skill` | `ornn-admin` | All `/admin/*` skill-scoped routes; admin force-audit; platform settings |
-| `ornn:admin:category` | `ornn-admin` | `GET/POST/PUT/DELETE /admin/categories/*` |
+| `ornn:admin:skill` | `ornn-admin` | All `/admin/*` skill-scoped routes; admin force-audit; sectioned platform settings; mirror config; announcements / broadcasts |
+| `ornn:quota:admin` | `ornn-admin` | `GET /admin/dashboard/stats`; all `/admin/quota/*`; all `/admin/redemption-codes/*` |
 
 A few endpoints (`POST /skills/:idOrName/audit`, the various caller-scoped reads) gate on **ownership** instead of (or in addition to) a permission — those are documented per-endpoint.
 
@@ -137,13 +137,15 @@ Writing / managing a skill (`canManageSkill`) collapses to: **author OR platform
 | Status | Used for |
 |---|---|
 | 200 | Successful read or write |
-| 201 | Resource created (admin category / tag create) |
+| 201 | Resource created (admin announcement / broadcast / redemption-code create) |
 | 400 | Validation error, malformed body, bad query param |
 | 401 | `AUTH_MISSING` — no usable identity from the proxy |
 | 403 | `FORBIDDEN` — authed but missing permission, ownership check failed, or trying to mutate someone else's skill |
 | 404 | `*_NOT_FOUND` — resource missing or hidden under visibility rules |
-| 409 | Conflict (e.g. duplicate version on publish) |
+| 409 | Conflict (e.g. `REDEMPTION_CODE_ALREADY_REDEEMED`) |
+| 410 | Gone (e.g. `REDEMPTION_CODE_EXPIRED`, `REDEMPTION_CODE_INVALIDATED`) |
 | 413 | `PAYLOAD_TOO_LARGE` — ZIP exceeds `MAX_PACKAGE_SIZE_BYTES` (default 50 MiB) |
+| 429 | `QUOTA_EXCEEDED` — caller has burned this month's allotment on the metered surface. Check `/me/quota`. |
 | 500 | `INTERNAL_ERROR` or domain-specific 500 — retry with backoff and include `X-Request-ID` if reporting |
 | 503 | `/readyz` only — Mongo unreachable |
 
@@ -181,6 +183,14 @@ The codes below appear across many endpoints. Per-endpoint sections list any add
 | `NYXID_SERVICE_NOT_ELIGIBLE` | 403 | Caller is not allowed to tie a skill to that service (would tie to another user's personal service). |
 | `SYSTEM_SKILL_MUST_BE_PUBLIC` | 400 | Skill tied to an admin service cannot be made private. Untie first. |
 | `QUERY_REQUIRED` / `AUTH_REQUIRED` | 400 | `/skill-search` invariant violated (semantic mode needs both query and auth). |
+| `INVALID_SURFACE` | 400 | `/me/models` `surface` query param is not `playground` or `skillGen`. |
+| `QUOTA_EXCEEDED` | 429 | Monthly allotment burned on the metered surface (`playground` or `skillGen`). Read `/me/quota` for the snapshot. |
+| `MODEL_UNAVAILABLE` / `MODEL_NOT_ENABLED` / `MODEL_NOT_FOUND` | 400 | SSE pre-stream: requested `modelId` is unknown or not enabled for this surface. Call `/me/models` to discover valid ids. |
+| `NOTIFICATION_NOT_FOUND` | 404 | `POST /notifications/:id/read` — the id is neither a per-user notification nor a broadcast the caller can see. |
+| `REDEMPTION_CODE_NOT_FOUND` | 404 | Redemption code does not exist. |
+| `REDEMPTION_CODE_EXPIRED` | 410 | Past `expiresAt`. |
+| `REDEMPTION_CODE_INVALIDATED` | 410 | Admin revoked the code. |
+| `REDEMPTION_CODE_ALREADY_REDEEMED` | 409 | Already consumed (codes are single-use). |
 | `PAYLOAD_TOO_LARGE` | 413 | Upload exceeds `MAX_PACKAGE_SIZE_BYTES`. |
 | `PACKAGE_DOWNLOAD_FAILED` | 500 | The backend could not retrieve the skill ZIP from object storage. |
 | `NYXID_ORG_LOOKUP_FAILED` | 500 | NyxID returned a non-OK response when the backend tried to resolve an org on the caller's behalf. |
@@ -1442,14 +1452,18 @@ The backend runs up to 5 rounds of tool-use; when the LLM emits a `function_call
 
 Four endpoints. All require auth. All scoped to the caller — no cross-user reads.
 
-Two notification categories are emitted today; both come from the audit pipeline:
+After [#500](https://github.com/ChronoAIProject/Ornn/pull/500) the feed is a **discriminated union** of per-user notifications and admin-authored broadcasts. Each item carries a `source` field — `"user"` for the audit-pipeline notifications below, `"broadcast"` for platform-wide markdown notices. The two variants share `_id`, `readAt`, `createdAt`; everything else is variant-specific. `unread-count` and `mark-all-read` cover both sources in one shot. `POST /:id/read` accepts either kind of id and routes by lookup.
+
+Per-user (`source: "user"`) categories emitted today; both come from the audit pipeline:
 
 | Category | Sent to | Trigger |
 |---|---|---|
 | `audit.completed` | The skill **owner** | Every audit completion. Body distinguishes `green` from `yellow`/`red` and links to the audit history page. |
 | `audit.risky_for_consumer` | Every consumer of a `yellow`/`red`-verdict skill — every user in `sharedWithUsers`, plus the membership of every org in `sharedWithOrgs` (resolved via NyxID at fan-out time) | Same audit completion. Skipped for `green`. |
 
-There are no other categories; share / waiver / review notifications were removed when the audit-gated share workflow was retired.
+There are no other per-user categories; share / waiver / review notifications were removed when the audit-gated share workflow was retired.
+
+Broadcasts (`source: "broadcast"`) are bilingual platform-wide notices authored via `POST /admin/broadcasts` (admin-only). They have no `category` — every row in this lane is treated as informational.
 
 ### 9.1 List notifications — `GET /api/v1/notifications`
 
@@ -1457,10 +1471,10 @@ There are no other categories; share / waiver / review notifications were remove
 
 | Query param | Type | Notes |
 |---|---|---|
-| `unread` | `"true"` | Optional. Restrict to unread. |
-| `limit` | int 1–200 | Default 50. |
+| `unread` | `"true"` | Optional. Restrict to unread items (across both sources). |
+| `limit` | int 1–200 | Default 50. Caps the merged feed length. |
 
-Response 200:
+Response 200 — the `items` array is a discriminated union on `source`:
 
 ```jsonc
 {
@@ -1468,6 +1482,7 @@ Response 200:
     "items": [
       {
         "_id": "ntf_...",
+        "source": "user",
         "userId": "user_...",
         "category": "audit.risky_for_consumer",
         "title": "Audit found risk in 'csv-tools' (yellow)",
@@ -1476,6 +1491,14 @@ Response 200:
         "data": { "skillGuid": "skl_...", "version": "1.3", "verdict": "yellow" },
         "readAt": null,
         "createdAt": "2026-04-28T..."
+      },
+      {
+        "_id": "bc_...",
+        "source": "broadcast",
+        "titleI18n":        { "en": "Scheduled maintenance",  "zh": "计划维护" },
+        "bodyMarkdownI18n": { "en": "We will be down at...",  "zh": "我们将在..." },
+        "readAt": null,
+        "createdAt": "2026-04-29T..."
       }
     ]
   },
@@ -1483,6 +1506,8 @@ Response 200:
 }
 ```
 
+Switch on `source` before reading variant-specific fields. `body` / `link` / `data` exist only on `source: "user"`; `titleI18n` / `bodyMarkdownI18n` exist only on `source: "broadcast"`.
+
 ### 9.2 Unread count — `GET /api/v1/notifications/unread-count`
 
 **Auth: required.** Cheap to poll for badge counts.
@@ -1495,24 +1520,24 @@ Response 200:
 
 ### 9.3 Mark one read — `POST /api/v1/notifications/:id/read`
 
-**Auth: required.** Sets `readAt` to `now()` and returns the updated row.
+**Auth: required.** Sets `readAt` to `now()`. The handler routes by id-lookup: a `:id` that matches a per-user notification updates that row; one that matches a broadcast inserts (or updates) a read-receipt for the caller. Unknown ids surface `NOTIFICATION_NOT_FOUND`.
 
 Path param: `:id`. Body: ignored (send `{}`).
 
 Response 200:
 
 ```jsonc
-{ "data": <NotificationDocument with readAt set>, "error": null }
+{ "data": <updated record — per-user notification doc OR broadcast read-receipt doc>, "error": null }
 ```
 
 | Code | Status | Cause |
 |---|---|---|
 | `AUTH_MISSING` | 401 | Standard. |
-| `NOT_FOUND` | 404 | Notification does not belong to the caller (or does not exist). |
+| `NOTIFICATION_NOT_FOUND` | 404 | The id is neither a per-user notification belonging to the caller nor a broadcast the caller can see. |
 
 ### 9.4 Mark all read — `POST /api/v1/notifications/mark-all-read`
 
-**Auth: required.** Marks every unread notification belonging to the caller as read.
+**Auth: required.** Marks every unread per-user notification belonging to the caller as read AND inserts read receipts for every currently-unread broadcast in one shot.
 
 Body: ignored.
 
@@ -1522,6 +1547,8 @@ Response 200:
 { "data": { "updated": 12 }, "error": null }
 ```
 
+`updated` is the total count across both sources.
+
 ---
 
 ## 10. Analytics
@@ -1610,7 +1637,7 @@ Response 200:
 
 ## 11. Me — caller scope
 
-Eight endpoints. All require auth and are scoped to the caller — there is no "read another user's …" surface here.
+Twelve endpoints. All require auth and are scoped to the caller — there is no "read another user's …" surface here.
 
 ### 11.1 Identity snapshot — `GET /api/v1/me`
 
@@ -1743,43 +1770,59 @@ Display names are resolved best-effort (NyxID for orgs, Ornn's activity director
 
 Response 200: same shape as 11.7.
 
----
-
-## 12. Users directory
-
-Two endpoints. Backed by Ornn's `activities` collection — anyone who has ever signed into Ornn has a directory row keyed by `userId` + `email` + `displayName`.
-
-### 12.1 Search — `GET /api/v1/users/search`
+### 11.9 Monthly quota — `GET /api/v1/me/quota`
 
-**Auth: required.** Any authed caller may search; the result set is scoped to users with at least one Ornn activity row.
-
-| Query param | Type | Notes |
-|---|---|---|
-| `q` | string ≤ 256 | Email prefix. Empty returns the most recent N. |
-| `limit` | int 1–50 | Default 10. |
+**Auth: required.** Caller-scoped snapshot of the metered surfaces (`playground`, `skillGen`). Read before any SSE call so you can short-circuit on `remaining: 0` instead of burning the request to a 429.
 
 Response 200:
 
 ```jsonc
 {
   "data": {
-    "items": [
-      { "userId": "user_...", "email": "alice@…", "displayName": "Alice" }
-    ]
+    "isAdmin": false,
+    "monthMarker":           "2026-05",
+    "monthStart":            "2026-05-01T00:00:00Z",
+    "monthEnd":              "2026-06-01T00:00:00Z",
+    "nextMonthlyResetAt":    "2026-06-01T00:00:00Z",
+    "playground": {
+      "defaultAllotment": 50,
+      "adminGrant":       10,
+      "used":             37,
+      "remaining":        23,
+      "warningThreshold": 0.8,
+      "warning":          false
+    },
+    "skillGen": {
+      "defaultAllotment": 20,
+      "adminGrant":       0,
+      "used":             20,
+      "remaining":        0,
+      "warningThreshold": 0.8,
+      "warning":          true
+    }
   },
   "error": null
 }
 ```
 
-| Code | Status | Cause |
-|---|---|---|
-| `INVALID_QUERY` | 400 | Query failed Zod validation. |
+Field semantics:
 
-### 12.2 Resolve — `GET /api/v1/users/resolve`
+- `isAdmin: true` — caller has admin bypass; every charge is free. The per-surface counters are still populated (for visibility) but never block.
+- `defaultAllotment` — platform-wide monthly base for the surface (set in `/admin/settings/quota`).
+- `adminGrant` — additive top-up granted to this user (via `/admin/quota/grant` or by redeeming a code).
+- `remaining = defaultAllotment + adminGrant − used`, clamped to ≥ 0. A successful chargeable call decrements `remaining` on completion.
+- `warning: true` when `used / (defaultAllotment + adminGrant) ≥ warningThreshold`. UI surfaces a soft chip; agents can treat it as "consider stopping".
+- Buckets reset at `nextMonthlyResetAt` (first day of next UTC month). Unused balance does not roll over.
 
-**Auth: required.** Batch-resolve a list of `userId`s to `{ email, displayName }` rows. Used to render labels for `sharedWithUsers` entries that were saved as bare ids.
+No error codes beyond the standard `AUTH_MISSING`.
 
-Query: `ids=id1,id2,id3` (max 100 per call). Unknown ids are silently dropped — no 404.
+### 11.10 Model picker — `GET /api/v1/me/models`
+
+**Auth: required.** List the LLM models the deployment has enabled for one of the SSE surfaces, sorted with that surface's default first.
+
+| Query param | Values | Notes |
+|---|---|---|
+| `surface` | `playground` \| `skillGen` | **Required.** Mismatched values → `INVALID_SURFACE`. |
 
 Response 200:
 
@@ -1787,51 +1830,69 @@ Response 200:
 {
   "data": {
     "items": [
-      { "userId": "user_a", "email": "a@…", "displayName": "Alice" },
-      { "userId": "user_b", "email": "b@…", "displayName": "Bob" }
-    ]
+      { "modelId": "claude-3-5-sonnet-latest", "displayName": "Claude 3.5 Sonnet", "isDefault": true  },
+      { "modelId": "gpt-4o",                   "displayName": "GPT-4o",            "isDefault": false }
+    ],
+    "defaultModelId": "claude-3-5-sonnet-latest"
   },
   "error": null
 }
 ```
 
----
+`items[].modelId` is what you pass as `modelId` to `POST /skills/generate*` or `POST /playground/chat`. Empty list means the admin has not enabled any model for this surface — SSE calls will pre-stream `MODEL_UNAVAILABLE`. `defaultModelId` mirrors the `isDefault: true` row; absent when the list is empty.
 
-## 13. Admin
+| Code | Status | Cause |
+|---|---|---|
+| `INVALID_SURFACE` | 400 | Query param missing or not in the enum. |
+| `AUTH_MISSING` | 401 | Standard. |
 
-Thirteen endpoints. All under `/api/v1/admin/*`. All require auth. Most agents never call these; they exist for the platform-admin UI.
+### 11.11 Redeem a code — `POST /api/v1/me/redemption-codes/redeem`
 
-### 13.1 Stats — `GET /api/v1/admin/stats`
+**Auth: required.** Consume a one-time redemption code; lands additive grants on the caller's quota buckets for the current month.
 
-**Auth: required.** **Permission: `ornn:admin:skill`.**
+Request body (`application/json`):
+
+```jsonc
+{ "code": "ORNN-XXXX-YYYY-ZZZZ" }
+```
+
+Schema: `z.object({ code: z.string().min(1).max(128) })`.
 
 Response 200:
 
 ```jsonc
 {
   "data": {
-    "totalUsers": 124,
-    "totalSkills": 412,
-    "publicSkills": 271,
-    "privateSkills": 141,
-    "recentActivities": 87
+    "codeId":     "rdm_...",
+    "redeemedAt": "2026-05-14T12:00:00Z",
+    "grants": [
+      { "surface": "playground", "amount": 50, "monthMarker": "2026-05", "newAdminGrant": 60 },
+      { "surface": "skillGen",   "amount": 10, "monthMarker": "2026-05", "newAdminGrant": 10 }
+    ]
   },
   "error": null
 }
 ```
 
-`recentActivities` is the count of activity-log rows in the last 24 hours.
+`newAdminGrant` is the post-redeem total for that surface, useful for echoing to the user. Codes are single-use across all users; consuming one invalidates it everywhere.
 
-### 13.2 Activities — `GET /api/v1/admin/activities`
+| Code | Status | Cause |
+|---|---|---|
+| `INVALID_REDEEM_BODY` | 400 | Body failed Zod validation. |
+| `REDEMPTION_CODE_NOT_FOUND` | 404 | Code string doesn't exist. |
+| `REDEMPTION_CODE_EXPIRED` | 410 | Past `expiresAt`. |
+| `REDEMPTION_CODE_INVALIDATED` | 410 | Admin revoked the code. |
+| `REDEMPTION_CODE_ALREADY_REDEEMED` | 409 | Already consumed (codes are single-use). |
+| `AUTH_MISSING` | 401 | Standard. |
 
-**Auth: required.** **Permission: `ornn:admin:skill`.**
+### 11.12 Redemption history — `GET /api/v1/me/redemption-codes/history`
 
-| Query param | Type | Notes |
+**Auth: required.** Caller's own redemption log, newest first.
+
+| Query param | Values | Default |
 |---|---|---|
-| `page` | int ≥ 1 | Default 1. |
-| `pageSize` | int 1–100 | Default 20. |
-| `action` | activity action | Filter by action type (`login`, `skill:create`, `skill:update`, `skill:delete`, …). |
-| `userId` | string | Filter by user. |
+| `page` | int ≥ 1 | 1 |
+| `pageSize` | int 1–100 | 20 |
 
 Response 200:
 
@@ -1840,66 +1901,61 @@ Response 200:
   "data": {
     "items": [
       {
-        "id": "act_...",
-        "userId": "user_...",
-        "userEmail": "...",
-        "userDisplayName": "...",
-        "action": "skill:create",
-        "details": { "skillId": "skl_...", "skillName": "my-skill" },
-        "createdAt": "2026-04-28T..."
+        "id": "rdm_...",
+        "code": "ORNN-XXXX-YYYY-ZZZZ",
+        "grants": [{ "surface": "playground", "amount": 50 }],
+        "note": null,
+        "redeemedAt": "2026-05-14T12:00:00Z",
+        "expiresAt":  "2026-06-30T23:59:59Z",
+        "createdAt":  "2026-05-01T00:00:00Z"
       }
     ],
-    "total": 412,
+    "total": 3,
     "page": 1,
     "pageSize": 20,
-    "totalPages": 21
+    "totalPages": 1
   },
   "error": null
 }
 ```
 
-### 13.3 Users — `GET /api/v1/admin/users`
+---
 
-**Auth: required.** **Permission: `ornn:admin:skill`.**
+## 12. Users directory
+
+Two endpoints. Backed by Ornn's `activities` collection — anyone who has ever signed into Ornn has a directory row keyed by `userId` + `email` + `displayName`.
+
+### 12.1 Search — `GET /api/v1/users/search`
+
+**Auth: required.** Any authed caller may search; the result set is scoped to users with at least one Ornn activity row.
 
 | Query param | Type | Notes |
 |---|---|---|
-| `page` | int ≥ 1 | Default 1. |
-| `pageSize` | int 1–100 | Default 20. |
+| `q` | string ≤ 256 | Email prefix. Empty returns the most recent N. |
+| `limit` | int 1–50 | Default 10. |
 
-Aggregates the activity collection into a per-user roster. Each item is enriched with skill counts:
+Response 200:
 
 ```jsonc
 {
   "data": {
     "items": [
-      {
-        "userId": "user_...",
-        "email": "...",
-        "displayName": "...",
-        "lastActiveAt": "2026-04-28T...",
-        "activityCount": 87,
-        "skillCount": 5
-      }
-    ],
-    "total": 124,
-    "page": 1,
-    "pageSize": 20,
-    "totalPages": 7
+      { "userId": "user_...", "email": "alice@…", "displayName": "Alice" }
+    ]
   },
   "error": null
 }
 ```
 
-### 13.4 Skills (admin-wide) — `GET /api/v1/admin/skills`
+| Code | Status | Cause |
+|---|---|---|
+| `INVALID_QUERY` | 400 | Query failed Zod validation. |
 
-**Auth: required.** **Permission: `ornn:admin:skill`.**
+### 12.2 Resolve — `GET /api/v1/users/resolve`
 
-| Query param | Type | Notes |
-|---|---|---|
-| `page`, `pageSize` | as above | |
-| `q` | string | Substring match against name and description. |
-| `userId` | string | Filter by author. |
+**Auth: required.** Batch-resolve a list of `userId`s to `{ email, displayName }` rows. Used to render labels for `sharedWithUsers` entries that were saved as bare ids.
+
+Query: `ids=id1,id2,id3` (max 100 per call). Unknown ids are silently dropped — no 404.
 
 Response 200:
 
@@ -1907,195 +1963,187 @@ Response 200:
 {
   "data": {
     "items": [
-      {
-        "guid": "skl_...",
-        "name": "my-skill",
-        "description": "...",
-        "createdBy": "user_...",
-        "createdByEmail": "...",
-        "createdByDisplayName": "...",
-        "createdOn": "2026-04-28T...",
-        "updatedOn": "2026-04-28T...",
-        "isPrivate": true,
-        "tags": ["..."]
-      }
-    ],
-    "total": 412,
-    "page": 1,
-    "pageSize": 20,
-    "totalPages": 21
+      { "userId": "user_a", "email": "a@…", "displayName": "Alice" },
+      { "userId": "user_b", "email": "b@…", "displayName": "Bob" }
+    ]
   },
   "error": null
 }
 ```
 
-Admin browse — no visibility filtering. Every skill in the registry is reachable here regardless of `isPrivate` / share-list.
+---
 
-### 13.5 Admin delete — `DELETE /api/v1/admin/skills/:id`
+## 13. Admin
 
-**Auth: required.** **Permission: `ornn:admin:skill`.** Same effect as `DELETE /skills/:id` (§3.11) but bypasses the author check.
+All endpoints under `/api/v1/admin/*`. All require auth. Most agents never call these — they back the platform-admin UI. This section gives the path + permission + intent so an agent invoked as a "platform-admin assistant" knows where to look; full request/response shapes live in `GET /api/v1/openapi.json`.
 
-Response 200: `{ "data": { "success": true }, "error": null }`.
+The legacy `GET /admin/stats` and `GET /admin/activities` endpoints were removed in [#271](https://github.com/ChronoAIProject/Ornn/pull/271) — admin totals moved to §13.1 below, and activity feeds live in PostHog now (the admin UI deep-links into the PostHog dashboard). The legacy `/admin/categories/*` and `/admin/tags/*` CRUD also no longer exist — tags now flow through `metadata.tag` on the skill frontmatter and are exposed read-only via `/skill-facets/tags` (§5.2); the `category` concept collapsed into a free-form `metadata.category` string.
 
-| Code | Status | Cause |
-|---|---|---|
-| `SKILL_NOT_FOUND` | 404 | Skill missing. |
-| `FORBIDDEN` | 403 | Missing `ornn:admin:skill`. |
-
-### 13.6 List categories — `GET /api/v1/admin/categories`
+### 13.1 Dashboard tiles — `GET /api/v1/admin/dashboard/stats`
 
-**Auth: required.** **Permission: `ornn:admin:category`.**
+**Auth: required. Permission: `ornn:quota:admin`.**
 
-Response 200:
+User + skill totals for the admin dashboard.
 
 ```jsonc
 {
-  "data": [
-    {
-      "_id": "cat_...",
-      "name": "tool-based",
-      "slug": "tool-based",
-      "description": "...",
-      "order": 2,
-      "createdAt": "...",
-      "updatedAt": "..."
-    }
-  ],
+  "data": {
+    "users":  { "total": 124, "admin": 3,  "normal": 121 },
+    "skills": { "total": 412, "system": 8, "public": 263, "private": 141 }
+  },
   "error": null
 }
 ```
 
-### 13.7 Create category — `POST /api/v1/admin/categories`
+Skill partition is disjoint (`total = system + public + private`): `system` = `isSystemSkill: true`; `public` = `isPrivate: false ∧ isSystemSkill !== true`; `private` = `isPrivate: true`.
 
-**Auth: required.** **Permission: `ornn:admin:category`.**
+### 13.2 User directory — `GET /api/v1/admin/users`
 
-Body:
+**Auth: required. Permission: `ornn:admin:skill`.**
 
-```jsonc
-{
-  "name": "tool-based",                 // one of: plain | tool-based | runtime-based | mixed
-  "slug": "tool-based",                 // 1–50 chars, lowercase alphanumeric + hyphens
-  "description": "...",                 // 1–500 chars
-  "order": 2                            // optional, ≥ 0
-}
-```
-
-Response 201: the new `CategoryDocument`.
-
-| Code | Status | Cause |
-|---|---|---|
-| `VALIDATION_ERROR` | 400 | Body failed Zod validation. |
-
-### 13.8 Update category — `PUT /api/v1/admin/categories/:id`
+| Query param | Notes |
+|---|---|
+| `page` | int ≥ 1, default 1 |
+| `pageSize` | int 1–100, default 20 |
 
-**Auth: required.** **Permission: `ornn:admin:category`.**
+Response: `{ data: { items: [{ userId, email, displayName, lastActiveAt, activityCount, skillCount }], total, page, pageSize, totalPages }, error: null }`.
 
-Path param: `:id` — category id.
+### 13.3 Skill admin browse + delete
 
-Body (any subset):
+Cross-user browse with no visibility filtering, plus force-delete bypassing the author check.
 
-```jsonc
-{
-  "description": "...",   // 1–500 chars
-  "order": 3              // ≥ 0
-}
-```
+| Method | Path | Permission | Notes |
+|---|---|---|---|
+| `GET` | `/admin/skills` | `ornn:admin:skill` | Query: `page`, `pageSize`, `q` (name+description substring), `userId`. Returns the same `SkillSummary` shape `/skill-search` does. |
+| `DELETE` | `/admin/skills/:id` | `ornn:admin:skill` | Same effect as `DELETE /skills/:id` (§3.11). Returns `{ data: { success: true }, error: null }`. |
 
-Response 200: the updated `CategoryDocument`.
+### 13.4 Force-audit — `POST /api/v1/admin/skills/:idOrName/audit`
 
-| Code | Status | Cause |
-|---|---|---|
-| `VALIDATION_ERROR` | 400 | Body failed validation. |
-| `NOT_FOUND` | 404 | No such category. |
+Cross-ref §4.5.
 
-### 13.9 Delete category — `DELETE /api/v1/admin/categories/:id`
+### 13.5 AgentSeal rescan — `POST /api/v1/admin/skills/:idOrName/versions/:version/agentseal-rescan`
 
-**Auth: required.** **Permission: `ornn:admin:category`.**
+**Auth: required. Permission: `ornn:admin:skill`.**
 
-Response 200: `{ "data": { "success": true }, "error": null }`.
+Re-runs the AgentSeal scanner against a specific version's package and refreshes the cached verdict on that version. Body: ignored. Returns the refreshed scan record.
 
-### 13.10 List tags — `GET /api/v1/admin/tags`
+### 13.6 Quota administration
 
-**Auth: required.** **Permission: `ornn:admin:skill`.**
+All under `/admin/quota/*`. **Auth: required. Permission: `ornn:quota:admin`.**
 
-Query: `type` (`predefined` | `custom`) — optional filter.
+| Method | Path | Body | Notes |
+|---|---|---|---|
+| `GET` | `/admin/quota/users?surface=playground\|skillGen&page=...&pageSize=...` | — | Per-user quota tiles for the requested surface. |
+| `GET` | `/admin/quota/users/:userId/lifetime?surface=...` | — | Lifetime grant audit + usage for one user, one surface. |
+| `GET` | `/admin/quota/grants?page=...&pageSize=...` | — | Paginated grant audit log across all users. |
+| `POST` | `/admin/quota/grant` | `{ userId, surface, amount, note? }` | Additive grant onto current-month bucket. |
+| `POST` | `/admin/quota/grant/bulk` | `{ userIds: [], surface, amount, note? }` | Same, multi-user. |
 
-Response 200:
+### 13.7 Redemption codes
 
-```jsonc
-{ "data": [{ "_id": "tag_...", "name": "translation", "createdAt": "..." }], "error": null }
-```
+All under `/admin/redemption-codes/*`. **Auth: required. Permission: `ornn:quota:admin`.** Caller-side `redeem` and `history` live at `/me/redemption-codes/*` (§11.11, §11.12).
 
-### 13.11 Create tag — `POST /api/v1/admin/tags`
+| Method | Path | Body | Notes |
+|---|---|---|---|
+| `GET` | `/admin/redemption-codes?page=...&pageSize=...` | — | Paginated admin list. |
+| `POST` | `/admin/redemption-codes` | `{ code?, grants: [{ surface, amount }], expiresAt, note? }` | Create. `code` auto-generated when omitted. Returns 201. |
+| `DELETE` | `/admin/redemption-codes/:id` | — | Hard delete (unredeemed only). |
+| `POST` | `/admin/redemption-codes/:id/invalidate` | — | Soft-revoke. Future `/me/redemption-codes/redeem` calls return `REDEMPTION_CODE_INVALIDATED`. |
 
-**Auth: required.** **Permission: `ornn:admin:skill`.**
+### 13.8 Mirror admin
 
-Body:
+| Method | Path | Permission | Notes |
+|---|---|---|---|
+| `POST` | `/admin/mirror/reconcile` | `ornn:admin:skill` | Fire-and-forget reconcile run. **202** with `{ data: { status: "running", startedAt }, error: null }` on accept. Refusals: `503 MIRROR_DISABLED` (kill-switch off or required GitHub App creds missing), `409 RECONCILE_ALREADY_RUNNING` (another reconcile is in progress on this pod). |
+| `GET` | `/admin/mirror/status` | `ornn:admin:skill` | Counts + last-run summary. Response combines DB-side mirror counts, the persisted scheduled-run status (cluster-wide), and the current `mirror` settings section (App private key mid-masked) so the admin UI can render without a second round-trip. |
 
-```jsonc
-{ "name": "translation" }
-```
+The mirror **config** (repo, branch, GitHub App id, encrypted private key, enabled flag, cadence) lives under the sectioned platform settings (§14.2, `mirror`). The two endpoints above only operate the scheduler. Manual `reconcile` runs are tracked in pod-local state and do not update `scheduledRun` in the status response.
 
-`name` must be 1–30 chars and match `/^[a-z0-9-_]+$/`.
+### 13.9 Announcements
 
-Response 201: the new `TagDocument`.
+Public anonymous reads + admin CRUD. Bilingual EN + ZH content; ZH falls back to EN at render time when empty.
 
-| Code | Status | Cause |
-|---|---|---|
-| `VALIDATION_ERROR` | 400 | Body failed validation. |
+| Method | Path | Auth | Notes |
+|---|---|---|---|
+| `GET` | `/announcements` | anon | Listed published announcements (News page). |
+| `GET` | `/announcements/active` | anon | Currently active row(s) for the landing-page popup. |
+| `GET` | `/admin/announcements` | `ornn:admin:skill` | Admin browse — every row including disabled / future. |
+| `POST` | `/admin/announcements` | `ornn:admin:skill` | Create. Body: `{ titleEn, titleZh?, bodyMarkdownEn, bodyMarkdownZh?, ctaLabelEn?, ctaLabelZh?, ctaUrl?, enabled, startsAt?, endsAt? }`. Returns 201. |
+| `PATCH` | `/admin/announcements/:id` | `ornn:admin:skill` | Partial update. |
+| `DELETE` | `/admin/announcements/:id` | `ornn:admin:skill` | Hard delete. |
 
-### 13.12 Delete tag — `DELETE /api/v1/admin/tags/:id`
+CTA pairing rule: `ctaUrl` and `ctaLabelEn` must both be set or both null (validated server-side as `INVALID_ANNOUNCEMENT_INPUT`). `ctaLabelZh` is independently optional.
 
-**Auth: required.** **Permission: `ornn:admin:skill`.** Response: `{ "data": { "success": true }, "error": null }`.
+### 13.10 Broadcasts
 
-### 13.13 Admin force-audit — `POST /api/v1/admin/skills/:idOrName/audit`
+Admin-authored notifications that fan out into every user's `/notifications` feed (§9) as `source: "broadcast"` rows.
 
-Documented as §4.5 above (audit section).
+| Method | Path | Permission | Notes |
+|---|---|---|---|
+| `GET` | `/admin/broadcasts` | `ornn:admin:skill` | List all broadcasts. |
+| `POST` | `/admin/broadcasts` | `ornn:admin:skill` | Create. Body carries bilingual `titleI18n` / `bodyMarkdownI18n`. Returns 201. |
+| `PATCH` | `/admin/broadcasts/:id` | `ornn:admin:skill` | Partial update. |
+| `DELETE` | `/admin/broadcasts/:id` | `ornn:admin:skill` | Hard delete (read receipts cascade). |
 
 ---
 
 ## 14. Platform settings
 
-Two endpoints. Editable per-deployment thresholds the platform admin controls. `auditWaiverThreshold` is the only field at the moment; new settings will be added here as features land.
+The platform-admin configuration lives in four parallel route groups under `/api/v1/admin/settings/*`. **Every endpoint here requires `ornn:admin:skill`** (the LLM-provider routes too). Agents rarely call these; they back the Settings tab of the admin UI.
 
-### 14.1 Read settings — `GET /api/v1/admin/settings`
+### 14.1 Legacy single-document settings — `GET / PATCH /api/v1/admin/settings`
 
-**Auth: required.** **Permission: `ornn:admin:skill`.**
+Mostly historical. The only remaining live field is `auditWaiverThreshold` (0–10 number; informational only — kept on the document because earlier designs surfaced a "low risk → auto-share" UI hint that the current sharing path does not consume).
 
-Response 200:
+`PATCH` body accepts a partial update; out-of-range values surface `INVALID_SETTING` (400). All real configuration lands in the sectioned routes below — not here.
 
-```jsonc
-{
-  "data": {
-    "auditWaiverThreshold": 7.5
-  },
-  "error": null
-}
-```
+### 14.2 Sectioned settings — `GET / PUT /api/v1/admin/settings/{section}`
 
-`auditWaiverThreshold` is a 0–10 number; it is currently informational only — kept on the document because earlier designs surfaced a "low risk → auto-share" UI hint. The current sharing path does not consume it.
+Each section is its own row in the `platform_settings` collection. Reads mid-mask secret fields; writes accept plaintext, redaction sentinels, or mid-mask sentinels for those same fields (the service resolves "preserve DB" sentinels).
 
-### 14.2 Patch settings — `PATCH /api/v1/admin/settings`
+| `{section}` (URL path) | Covers |
+|---|---|
+| `playground` | Playground SSE knobs (per-call budgets, sandbox image, etc.) |
+| `skill-generation` | Skill-generation SSE knobs (max output tokens, validation retries, etc.) |
+| `mirror` | GitHub mirror — repo, branch, App ID, installation id, encrypted private key, enabled flag, reconcile cadence |
+| `integrations/nyxid` | NyxID proxy + service ids the backend talks to |
+| `skill-audit` | Audit pipeline — risk threshold, LLM choice, cache TTL |
+| `posthog` | PostHog telemetry — host, project key, ingestion toggles |
+| `extras` | Catch-all for one-off feature flags |
 
-**Auth: required.** **Permission: `ornn:admin:skill`.**
+Response shape on read: `{ data: <sectionPayload>, error: null }`. On write: `{ data: <sectionPayload>, error: null, meta: { changedFields: [...] } }` — no-op writes still 200 with an empty `changedFields`.
 
-Request body (`application/json`, partial):
+| Code | Status | Cause |
+|---|---|---|
+| `INVALID_BODY` | 400 | Body not a JSON object. |
+| `VALIDATION_ERROR` | 400 | Body failed the section's Zod schema. |
+| `SECTION_NOT_FOUND` | 404 | Unknown `{section}` path. |
 
-```jsonc
-{ "auditWaiverThreshold": 7.5 }
-```
+### 14.3 LLM providers — `/admin/settings/llm-providers[/:id]`
 
-`auditWaiverThreshold` must be a number in `[0, 10]`. Values are rounded to one decimal.
+Multi-provider model catalog. Each provider row carries credentials + per-model toggles for the two SSE surfaces.
 
-Response 200: the updated settings document.
+| Method | Path | Body | Notes |
+|---|---|---|---|
+| `GET` | `/admin/settings/llm-providers` | — | List all providers. Secrets mid-masked. |
+| `POST` | `/admin/settings/llm-providers` | `{ name, gatewayUrl, auth, maxOutputTokens, defaultTemperature, ... }` | Create. Returns 201. |
+| `GET` | `/admin/settings/llm-providers/:id` | — | Read one. |
+| `PUT` | `/admin/settings/llm-providers/:id` | partial | Update. Accepts plaintext or mid-mask sentinel for secret fields. |
+| `DELETE` | `/admin/settings/llm-providers/:id` | — | Hard delete + cascade through model catalog. |
+| `POST` | `/admin/settings/llm-providers/:id/sync` | — | Re-pull model list from the provider gateway. Response `{ data: { synced: int }, error: null }`. |
+| `PATCH` | `/admin/settings/llm-providers/:id/models/:modelId` | `{ enabledForPlayground?, enabledForSkillGen?, defaultForPlayground?, defaultForSkillGen? }` | Per-row surface flags. Setting `defaultFor*: true` unsets the previous default atomically. |
 
-| Code | Status | Cause |
+The picker `GET /me/models` (§11.10) reads through this catalog.
+
+### 14.4 Export / import — `/admin/settings/export` and `/admin/settings/import`
+
+| Method | Path | Notes |
 |---|---|---|
-| `INVALID_SETTING` | 400 | Field out of range or no recognised fields in body. |
-| `FORBIDDEN` | 403 | Missing `ornn:admin:skill`. |
+| `GET` | `/admin/settings/export` | Returns full settings + LLM-provider snapshot as JSON. Secrets are redacted. |
+| `POST` | `/admin/settings/import` | Body: a prior export JSON. Replays into `platform_settings` + `llm_providers`. Diff is reported in `meta.changedFields`. |
 
 ---
 
 ## Appendix — staying in sync with this file
 
-When the API surface changes, the change lands in `ornn-api/src/domains/**/routes.ts` first. This file should be updated in the same PR. The `version:` field in the parent `SKILL.md` is bumped on every doc-affecting change; agents pulling the skill will see the bump on `GET /api/v1/skills/ornn-agent-manual/json` and can refresh their context. There is no out-of-band changelog — `git log skills/ornn-agent-manual/` is the changelog.
+When the API surface changes, the change lands in `ornn-api/src/domains/**/routes.ts` first. This file should be updated in the same PR. The `version:` field in the parent `SKILL.md` is bumped on every doc-affecting change; agents pulling the skill will see the bump on `GET /api/v1/skills/ornn-agent-manual-cli/json` and can refresh their context (see SKILL.md §0). There is no out-of-band changelog — `git log skills/ornn-agent-manual-cli/` is the changelog.