release: develop → main (v0.9.0 — API-conventions overhaul + agent-API features)

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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.

.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).

.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`).