> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Change Log

> Release notes and platform updates for the Kodexa AI Platform, including new features, breaking changes, fixes, and migration guidance for each release.

<Update label="2026-07-02" tags={["Release", "2026.6", "Platform", "Workflow", "Manage", "Data Forms", "Task Groups", "Analytics", "Performance", "Document", "Orchestrator"]}>
  ### Release 2026.6

  Rollup of every customer-facing change in the 2026.6 GA release. The headline items: a new top-level **Manage** administration area that gathers every org-admin surface in one place, and a **Kodexa Workflow MCP connector** that exposes activities, tasks, and task-groups to claude.ai as a remote OAuth connector. Alongside those, this release brings a wave of review-experience performance work, a broad set of Data Forms V2 shortcut and grid fixes, task-group polish, opt-in user presence & activity tracking, and analytics and orchestration fixes.

  **Manage:**

  * **Manage — a new top-level administration area** — Organization administration now lives in its own top-level **Manage** context (`/m`), alongside Studio, Workflow, and Knowledge, and is visible only to users with the `MANAGE` or `PLATFORM_ADMIN` role. Its **Access, Controls and Reporting** grid gathers the organization admin surfaces in one place: Organization Profile, Teams, Document Tags, Secrets, Intakes, Custom Modules, Subscriptions, Model Library, and Concurrency. These moved out of Studio's Organization Home, which no longer carries the admin/operations cards.
  * **Organization Profile gains a Features tab** — Organization Profile (Manage → Organization Profile) now has a **Features** tab exposing two org-level toggles: **Strict team matching**, which sets `features.teamMatchingMode` to `strict` so take-next only assigns team-matched candidates (default is soft matching, which falls back to team-null candidates when there is no match), and **Presence tracking** (`features.presenceTrackingEnabled`), an opt-in switch for per-user presence and activity telemetry that is off by default.

  **Workflow:**

  * **Kodexa Workflow MCP connector** (ENGG-5316) — kodexa-api now exposes its workflow surface — activities, tasks, and task-groups — as an [MCP connector](/guides/mcp-connector/index) over Streamable HTTP at `<basePath>/mcp`, designed to be added to claude.ai as a remote OAuth connector. The connector registers 19 tools (12 reads: `whoami`, `list_organizations`, `list_projects`, `list_teams`, `list_organization_members`, `list_activities`, `get_activity`, `list_tasks`, `get_task`, `list_task_groups`, `get_task_group`, `list_task_statuses`; 7 writes: `assign_task`, `unassign_task`, `assign_task_group`, `unassign_task_group`, `update_task_status`, `add_tasks_to_group`, `remove_task_from_group`). Enable it with `mcp.enabled` and set `mcp.publicUrl` to the Auth0 API identifier; claude.ai discovers the authorization server via RFC 9728 protected-resource metadata and runs DCR + PKCE against Auth0 directly. An `X-API-Key` fallback covers programmatic and local clients. Every tool runs through the same FGAC, optimistic-locking, group-cascade, audit, and domain-event path as the REST API — reads reuse the registry handlers, writes replay through the existing REST handlers — so results are scoped to the calling user and behavior is identical to REST. Activities are read-only over MCP, and a grouped task's assignee is managed through its task-group (assignment cascades), not per-task.

  **Performance:**

  * **Review pages and task groups load faster** (ENGG-5341) — The project cache now holds for 30 minutes instead of 5, so a kiosk reviewer no longer re-fetches the full project bundle every few minutes on each new task. `GET /api/tasks` and `GET /api/activity-plans` gained an opt-in `?view=summary` projection that omits the heavy embedded plan detail (steps, schemas, metadata, prompts, document-family groups) — the task-group queue that drives it dropped from \~4.2MB to \~520KB. Task-group review also prefetches the next task's document content in the background so it opens instantly when you advance, and the per-task metadata resolves against the service bridge now run in parallel rather than one after another. Unprojected list calls and `GET`-by-id responses are unchanged.

  **Data Forms:**

  * **Full document-viewer keyboard shortcut set on the liability form** (ENGG-5311) — The liability form now ships page-step and viewer-scroll shortcuts alongside rotate, all declared through the [declarative form-shortcuts](/guides/data-forms/shortcuts) system with nothing hard-coded in the viewer. Backing this are new Bridge methods: `navigation.previousPage(documentFamilyId?)` / `navigation.nextPage(documentFamilyId?)` step the spatial viewer one page and clamp at the document edges (no-op at first/last page), and a new `viewer.scroll(direction, documentFamilyId?)` surface nudges the viewport `up`/`down`/`left`/`right` by \~¼ of the visible area (vertical scrolls the page wrapper, horizontal pans the zoom transform; an invalid direction is a no-op). `viewer.scroll` is gated by a new `viewer` bridge permission — add `"viewer"` to `bridge.permissions` to use it; `previousPage` / `nextPage` require the existing `navigation` permission.
  * **Keyboard shortcuts fire reliably on Mac + Chrome 134+** (ENGG-5310) — Declarative form shortcuts had stopped firing on Mac under recent Chrome. On Mac, a `control+X` binding is now rewritten to `⌘⌥X` (meta+alt) to match the keystroke Chrome actually delivers — replacing the old meta+option rewrite that never matched — and `alt+X` / `⌘⌥X` chords auto-register their macOS character-substituted form (`⌥R`→®, `⌥6`→§, `⌥⇧R`→‰) so a plain `⌥`+key still triggers (option dead-key letters — e, i, n, u — produce no standalone character and need an explicit `altKey`). Each variant is tracked in its own scope entry so bindings no longer leak across data-form re-mounts. A capture-phase handler reclaims registered chords (e.g. `Ctrl+PageDown`, `Ctrl+5`–`8`) before the browser's tab switching consumes them — but only when focus is outside an input, textarea, select, or contentEditable element. This restores the intended behaviour of the [declarative form-shortcuts](/guides/data-forms/shortcuts) framework on Mac; no form changes are required.
  * **`v2:grid` sort is now an initial-only lock that persists row order** (ENGG-5353) — A grid's declared `sort` is applied once, when it first loads a fresh task, and then locks. The grid no longer actively re-sorts as operators type into cells, so a new row appends in its `sourceOrdering` slot instead of jumping mid-entry (e.g. freight-class rows stop reordering under the cursor). Manual column-header sorting still overrides the default. The resulting row order is persisted per task on `task.properties` — but only on operator-initiated add/remove, never on mount or cell edits — and is restored on refresh and for other operators viewing the same task.
  * **Promote/Copy now mark the target as user-edited** (ENGG-5320) — The V2 `attributeCopyButton`, `attributeCopyAction`, and `attributeRowPromote` writes now stamp the target with `ownerUri = user://<reviewer email>`, exactly as a manual edit does, so the edited-value indicator renders on a promoted or copied field (blue when the source carried a `tagId`/document anchor, yellow when it did not). The source `tagId` still carries over, so click-to-source navigation is unaffected.
  * **Service bridge lookups skip redundant refetches** (ENGG-5318) — `v2:serviceBridgeView` and the form bridge-call composables previously fired the bridge twice on any reactive attribute write under the form (e.g. a radio click in `v2:attributeEditor`), because the auto-watcher re-ran on unrelated `ctx.dataObjects` mutations even when the resolved bridge params were unchanged. Each call now compares the JSON-serialized params against the last call it fired and skips the fetch (both the HTTP and WASM paths) when they're identical; genuine param changes still re-call the bridge as before.
  * **Large service-bridge responses no longer hang a document on open** (ENGG-5345) — A selection-formula service-bridge response larger than 64 KiB used to overflow the WASM worker's fixed SharedArrayBuffer channel and throw, killing the bridge loop so every later bridge call in the document stalled on an `Atomics.wait` timeout. The channel buffer now grows on demand up to 16 MiB to fit an oversized response, and if a write still can't be completed the worker returns a small error envelope and keeps the loop running instead of bricking the channel.

  **Document:**

  * **Detached viewer no longer freezes on focus, and form shortcuts reach the pop-out** (ENGG-5344) — With the document viewer popped out into its own window, focusing an attribute or tag in the main workspace no longer locks up the page. The main tab was echoing its own focus event back into itself while detached, driving an unbounded focus loop; that self-echo is now short-circuited while a viewer is detached (inline focus navigation is unchanged). Declarative [form shortcuts](/guides/data-forms/shortcuts) are also now forwarded to the detached window, so a form's rotate-page (`alt+R` / `alt+shift+R`) and viewer-scroll actions still take effect when triggered from the main workspace with the viewer popped out.

  **Task Groups:**

  * **Task group assignee dropdown populates again** (ENGG-5334) — The assignee picker on a task group showed "No assignees found." because the task-group endpoint preloads `project` only one level deep (no nested `organization`), leaving the org-member lookup with no organization id to resolve. It now falls back to the scalar `project.organizationId` when the nested `organization.id` is absent — matching the team dropdown and the task-group status loader — so the list of organization members loads. The filter also now matches on the member's email in addition to first/last name.
  * **Task-group search matches partial terms** (ENGG-5314) — Typing into the search box on the organization and project **Task Groups** lists used to compile to an exact match, so a partial term returned nothing. The two lists now build the filter as a contains query (`searchText~~'*<term>*'`), matching the Knowledge Sets convention, so partial terms match anywhere in the name.

  **Analytics:**

  * **Nested line-item data reaches the data lake** (ENGG-5315) — The KDDB-to-content-object projection only ever populated top-level data objects; nested child groups (for freight Shipments: `stops`, `accessorials`, `freight_classes`, `additional_document_numbers`, `backup_docs`, `address`) projected as empty arrays because a freshly-loaded KDDB sets `ParentID` / `SourceOrdering` but never wires the `Children` relation. The projector now indexes children by `ParentID` up front and resolves nested groups from that index, ordered by `SourceOrdering` (nulls-first, then natural order, ID as tiebreak — matching the document engine), so child detail now populates in `content-objects/` at arbitrary depth. Top-level projection is unchanged.

  **Platform:**

  * **User presence & activity tracking (opt-in, off by default)** (ENGG-5328) — Organizations can now opt into per-user presence and activity telemetry from **Manage → Organization Profile → Features → Presence tracking**. The toggle sets `organization.features.presenceTrackingEnabled` and ships **off by default**; a legal/privacy callout is always shown so an administrator understands the workforce-monitoring implications before enabling it.
    * **What is collected when enabled** — a `ui.presence.heartbeat` roughly every 120s carrying only derived signals (`active` — recent mouse/keyboard/touch/scroll input vs. idle — plus tab visibility and the interval), throttled to \~1-in-5 while the tab is hidden, and `ui.task.opened` / `ui.task_group.opened` events with task-open load timing. **No raw input is ever captured** — no keystrokes, no mouse coordinates, no scroll positions — only the derived booleans. The server hashes the client IP on receipt (it stamps a `clientIpHash` tag) and never stores the raw address; the client never sends an IP field.
    * **Server-side enforcement (fail-closed)** — `POST /api/events/ui/batch` drops `ui.presence.*`, `ui.task.*`, and `ui.task_group.*` events for any org that has not set the flag, regardless of what the client sends; the flag is read from `kdxa_organizations.features` and cached for 60s. An empty org id or a lookup failure resolves to *disabled*, so monitoring events are dropped rather than collected without an explicit opt-in. Other `ui.*` events (errors, etc.) are unaffected. Batches are capped at 100 events and each accepted event is stamped server-side with the authenticated user's email.

  **Orchestrator:**

  * **Orchestrator-initiated Activity starts now authenticate in every environment** (ENGG-5338) — `nextActivity` spawns from SCRIPT steps and orchestrator trigger fires reach the platform over an internal, server-trusted service-token route (`POST /api/v2/internal/activities`), so orchestrated Activity hand-offs actually launch outside integration tests. The orchestrator's start-activity client is now enabled whenever `KODEXA_API_INTERNAL_URL` is set (previously it also required a service token that was unset in normal deployments, silently leaving spawns and trigger-initiated starts disabled). The internal route derives the owning org server-side from the target project and never trusts a caller-supplied org; its only authorization gate is the activity-plan → project binding (the same-project check), so it deliberately does not run the caller-facing FGAC `activity:start` permission.
</Update>

<Update label="2026-06-11" tags={["Platform", "Performance", "Document", "Data Forms", "Studio", "Formulas", "Knowledge", "Orchestrator"]}>
  ### Faster document loads, correct totals on open, and reliable saves

  This release focuses on speed and dependability across the review experience. Documents open and recalculate dramatically faster, conditional-format highlights and formula totals are now correct the moment a document opens — not only after a reviewer's first edit — and reviewer edits are reliably captured on **Approve**. It also adds a wave of new **Data Forms V2** components alongside a broad set of grid, formula, knowledge, and orchestration improvements.

  **Faster document loads and edits:**

  * **Editing large documents is dramatically faster** — Recalculating a document used to issue a separate database query for each attribute, which multiplied quickly — a single edit could cascade into thousands of queries. The same work now takes a handful (one measured edit dropped from roughly 12,800 queries to 2), so edits and their downstream recalculations stay snappy even on large documents.
  * **Documents recalculate up to \~88× faster** — Documents now refresh incrementally by default — 4.4s down to 46ms in one measured case — with an automatic fallback for unusually complex dependency graphs.
  * **Tasks open progressively** — The first data form appears as soon as its own document is ready, rather than waiting for every document on the task. Off-screen views defer presentation work — text indexing, summaries, page tags — until you open them, and redundant loading and artificial delays were removed from the open path.
  * **Switching tasks keeps sessions light** — Moving to a new task releases the documents the new task no longer needs, so long review sessions stay responsive, while a short history cache keeps back-navigation instant. Cleanup is always held off while a save, edit, or popped-out sidecar is still active.
  * **Rollup totals always match their formulas** — Rollup cards now compute through the same engine — with the same `sum()` semantics — as the formulas they summarize, and refresh together with them, so a rollup and its underlying formula can no longer disagree.
  * **Leaner edit updates** — Editing an attribute now sends just that attribute to the browser instead of its entire containing group, cutting overhead on documents with large tables.
  * **Faster, more reliable startup** — The document engine now loads entirely from Kodexa with no third-party CDN dependency at startup, and moves document data across the browser more efficiently.

  **Correct the moment a document opens:**

  * **Conditional formatting shows on open — no edit required** (ENGG-5296) — A mismatch highlight (for example, a billed total that doesn't match the summed line items) used to stay hidden until a reviewer touched the document. Highlights now render correctly on first paint, against the stored values as they are.
  * **Formula totals are correct on open** — Formula values (sums, weights, charge totals) now show their correct computed value the instant a document opens, instead of a stale zero that only corrected itself after the first edit. Documents that are already correct open clean — with no false "unsaved changes" — and any missing formula values are computed and filled in automatically.
  * **Conditional formatting updates when you delete a row** (ENGG-5265) — Deleting a line item now re-checks any total that depends on it, so a balance that moves into or out of tolerance on a delete reflects immediately.

  **Reliable saves:**

  * **Approve always captures your last edit** (ENGG-5291) — Selecting a value and immediately clicking Approve could previously miss that value if its write hadn't finished landing. Save and Approve now wait for in-flight edits to settle first — and show a clear error rather than silently continuing if an edit is stuck.
  * **Form values no longer revert after Approve** (ENGG-5269) — Editing a form and approving could take two clicks and briefly appear to revert. Edits are now applied to the document before any follow-up step runs, so the first Approve takes effect.
  * **No edits lost during a save** (ENGG-5292) — An edit made while a save is already in progress is now included in the next save instead of being dropped or needlessly re-sent.

  **Data Forms V2:**

  * **`v2:routeTimeline`** (new) — Renders a group taxon's rows as a vertical timeline of numbered stop cards for ordered lists such as a multi-stop shipment route. Stops drag-reorder (the sequence attribute is rewritten to the new position on drop), each card has an inline-editable detail panel, and per-row delete is built in. Additional props: **+ Add stop** and **AI extract stop** (single-record extraction anchored on highlighted document text, with one level of nested sub-object such as an address), a **find-in-document** button that scrolls the viewer to a stop's source span, `show: 'firstLast'` to collapse the middle of a long route behind a "…+N" toggle, `readonly` and `orientation` (vertical/horizontal) props, and an optional location-code badge. The group taxon, sequence tag, type tag, and sub-object path are all configurable.
  * **`v2:attributeCopyAction`** (new) — A scalar sibling-copy button for form layouts (distinct from the grid-cell copy components): it evaluates the source value through the formula engine and writes it to a sibling target. Like the other copy components it now writes `decimalValue`, so number-typed targets re-render immediately.
  * **`v2:attributeRowPromote`** (new) — Replaces the per-target chevron columns on candidate grids with a single **Promote to…** dropdown per row, with an optional per-target source-tag override. Promotes are idempotent and now write `decimalValue` so number targets update without tabbing away (ENGG-5217).
  * **`v2:grid` pagination, sort, and sortable custom columns** (ENGG-5267) — `v2:grid` gained opt-in `pagination` and `sort` props (reviewer grids still default to showing all rows), and custom columns can opt into sorting with a header-matched sort spec. `SELECTION` cells now close their popover on pick instead of staying open until Tab/Escape.
  * **Form Completeness Gate** (new) — A per-form primitive that lets a task action stay disabled until reviewers have actually looked at the data they should. `v2:tabs` gains `mustView` (flags unvisited tabs with an amber dot and a "N tabs to review" banner), `v2:panel` gains `mustExpand` / `mustScroll`, and outstanding workspace exceptions fold into the same list. Actions opt in with `gatedByCompleteness: true` and surface an info-popover listing what's left; existing forms and actions are unchanged.
  * **`v2:panel` polish** — New `description` subtitle prop and an `iconColor` tile palette (avatar-style tinted icon) matching the rest of the app, plus header icons on tabs and panels.
  * **Rotate-page keyboard shortcut** (ENGG-5217) — `alt+R` / `alt+shift+R` (⌥R / ⌥⇧R on Mac) rotate the current page in the document viewer right / left, wired through the [declarative form-shortcuts](/guides/data-forms/shortcuts) system. The server-side `DataForm` schema gained the `shortcuts` field, so forms declaring a `shortcuts:` block now round-trip correctly (the block was previously dropped on save).
  * **Vertical radio layout** — Attribute editors accept `radioOrientation: 'vertical'` so a `displayAsRadio` field can stack one option per line instead of wrapping across the row (default stays horizontal).

  **Document formulas & extraction:**

  * **`sumifs` / `countifs` accept single-row groups** — A formula like `sumifs({Group/Value}, {Group/Use}, true)` previously errored ("first argument must be an array") whenever the source group resolved to exactly one row, surfacing as a transient "Formula calculation failed" toast that vanished once a second row was added. Scalar range / criteria arguments are now coerced to a one-element range, so one-row and many-row groups take the same path.
  * **String cleaning patterns applied on attribute create** — Taxon `stringExtract` / `stringReplace` cleaning patterns were only applied when an attribute was updated, not when it was first created — so extraction tagging, programmatic adds, the API, and script-driven `setAttribute` all bypassed the cleaning that the same attribute would get on a later edit. The patterns now apply at create as well, and the redundant UI-side normalizer was removed.
  * **Direct copy/extract value appears immediately** — Adding a value via direct copy now patches the cache optimistically and emits the change event, so the value shows at once instead of only after tabbing out of the field (which used to trigger an expensive full-cache refresh).
  * **Preprocessor keeps rotation-corrected images** — When auto-orientation rotated a page, the rebuilt processed PDF was falling back to the original (un-rotated) source page and silently discarding the corrected image. The rebuild now embeds the rotated image bytes while preserving the viewer's "already corrected, don't CSS-rotate" signal.

  **Studio grids & activities:**

  * **Column-header clicks no longer steal focus into the first cell** (ENGG-5268) — Clicking a column header in an editable data-object grid was moving focus into row 0's first cell and opening its editor. A real user header click now suppresses that redirect while still preserving focus-from-outside and post-add-row refocus behaviour.
  * **Activities filter inputs persist across remount** (ENGG-5215) — The Activities grid's toolbar inputs (document-family filter, feature facets, quick filter, date range) and the applied filter could fall out of sync on tab switches, breadcrumb navigation, or reload — the inputs looked empty while the list stayed filtered. The toolbar state now persists and is realigned on remount.
  * **Bulk "remove by source" count stays accurate** (ENGG-5264) — The grid's per-source remove buttons could show a stale row after a bulk delete when overlapping async recounts resolved out of order; a sequence token now discards superseded runs.
  * **Grid search hydrates from the saved query** — The grid search input now repopulates from the persisted query on load, so a saved search shows its text instead of an empty box over a filtered list.

  **Knowledge:**

  * **Escaped image markdown normalized on write** — Image references pasted from Word or HTML into the rich-text editor were serialized as escaped literal text (`!\[\](attachment://…)`) and rendered as plain text instead of the image. The editor now normalizes on edit, and the API normalizes on every create/update — scoped to markdown-typed fields so intentional text escapes (e.g. `\[see codes below\]`) are preserved.
  * **Readonly-taxon panel shows the extracted value** (ENGG-5253) — The knowledge readonly-taxon panel rendered "—" instead of the extracted value when the stored dependency used the taxon's external-name chain while extraction keys attributes by taxon path — two different namespaces that never matched. The taxon picker now persists the taxon path so the reader matches directly. (Existing knowledge sets need the dependency re-selected and saved to migrate.)

  **Orchestrator:**

  * **Activity SCRIPT steps can read `inputs`** — A SCRIPT step body can now read the activity's materialized inputs via the `inputs` JS global (previously only reachable inside `BRIDGE_CALL` request templates — referencing `inputs.X` in a SCRIPT threw a ReferenceError). It always defaults to `{}`, so no `typeof` guard is needed.
  * **Script-step timeout raised to 60s; failed-step logs retained** — Long enrichment scripts on multi-document inputs were being interrupted at the old 15s limit; the `SCRIPT` step timeout is now 60s. A failed step's log pointer is also no longer discarded by the per-item rollback, so the step-logs view keeps showing the logs for a step that failed — covering `SCRIPT`, `BRIDGE_CALL`, and `AI_PROMPT` steps, which share the log path.
</Update>

<Update label="2026-05-30" tags={["Platform", "Studio", "Data Forms", "Scripting", "Formulas", "Knowledge"]}>
  ### Post-2026.4.1 patches — copy rules, source badges, multi-instance attribute paths

  The week after the 2026.4.1 cut shipped a batch of reviewer-workflow polish, new V2 data-form components for promoting candidate values into canonical slots, and the under-the-hood refactor that finally derives `DataAttribute.path` from `parent + tag` everywhere (closing out ENGG-5214). A handful of script-API and formula fixes ride along.

  **Studio reviewer workflow:**

  * **Open Task is a primary button that opens a new tab** — The activity-status dialog's "Open Task" affordance was a small text link that closed the dialog on click. It's now a primary `open-in-new` button, opens the task route in a new browser tab via `window.open`, and leaves the activity dialog mounted so reviewers keep their context.
  * **Activity dialog auto-zooms to the active step** — Opening the plan tab no longer fits the whole graph; it focuses the running step (or the last terminal step on completed plans), falling back to `fitView` only when there's no anchor. A one-shot watcher covers the race where the dialog mounts before the layout finishes.
  * **Attribute source badge: per-document-type instance numbering** — The badge now shows "Bill of Lading #1, #2, #3..." independent of how many Invoices or other classified pages interleave between them, instead of the preprocessor's global group sequence (which made every BoL in a doc read as the same number). Also fixes an off-by-one between `node.getPage()` (0-based) and the resolver's 1-based classification map that was making attributes anchored to page 2 read as page 1.
  * **Filter in ag-grid column kebab menu** — Column header menus on all ag-grid surfaces now expose ag-grid's `columnFilter` item alongside sort/pin/etc, gated on `column.isFilterAllowed()`.
  * **Page-size selector no longer steals focus into row 0** (ENGG-5252) — Clicking the grid's page-size selector previously opened the first row's first-column dropdown on top of the page-size popup. The grid's focus-redirect logic now ignores clicks landing in the pagination chrome.

  **Data Forms V2 — promotion and provenance:**

  Several new components and form-level features that work together to support the "promote a candidate value into a canonical scalar/grid slot, with provenance" workflow:

  * **`v2:attributeCopyButton.relatedCopies`** (new) — The copy button now accepts an optional `relatedCopies: [{sourceTagPath, targetTagPath}, ...]` prop. After the primary copy lands, each related pair runs through the same copy logic, so promoting a weight from a candidate-weights grid into `shipments/shipweight` can carry the matching UOM into `shipments/shipweightuom` in the same click.
  * **`v2:attributeRowDeleteButton`** + **`v2:gridDeleteBySource`** (new) — Per-row inline delete cell + a sibling toolbar component that surfaces "Remove all `<source>` rows" buttons (one per detected source document) with a confirm dialog before bulk delete. Both share the same `(document_type, group)` resolver the source badge uses.
  * **`v2:attributeSourceBadge` on `v2:grid`** (new) — `v2:grid` gained a `columns` prop that mounts arbitrary V2 components as per-row cell renderers, alongside the existing taxon-driven columns. The new `v2:attributeSourceBadge` renderer shows one colored pill per distinct `(document_type, group)` tuple of source attributes; click dispatches `workspace.focusTag` for in-viewer navigation.
  * **`v2:grid` `height` prop honored even with parent data object** — Previously `v2:grid`'s `height` was silently dropped on any grid running under a parent scope (i.e. every form grid), forcing a row-count-based auto-calculation. An explicit `height` now always wins.
  * **Form-level `copyRules` on DataFormV2** — `DataFormV2` now accepts a top-level `copyRules?: TaxonCopyRule[]`. Cards merge form-level rules with their own per-card rules (card-level wins on `sourceTaxon` conflict). Replaces having to repeat the same copy block on every source panel in forms with many source-document instances.
  * **Formula-driven `stampAttributes` on copy rules** — `CopyBehaviorOptions` gained `stampAttributes?: Record<string, string>` for stamping derived audit/provenance attributes onto the copy destination. Values can be literal strings or `${source.idString}` / `${source.parent.blnumber}` / `${source.parent.uuid}` templates. Distinct from `copyAttributes` (which clones existing source attributes with content-tag preservation), `stampAttributes` injects new derived fields with no content backing — useful for stamping `sourceDocumentRef`, `sourceBolNumber`, `sourceDocumentType` onto rows promoted into a canonical grid.

  **Scripting:**

  * **`setAttribute` routes numeric taxon types to `DecimalValue`** — `setAttribute` was only matching `DECIMAL`, so writes against `NUMBER`, `INTEGER`, `CURRENCY`, and `PERCENTAGE` taxons fell through and stored the value in `StringValue`. The form's numeric editor then read the typed slot and rendered empty even though `.value` showed the right string. The switch now covers every numeric taxon type the data model acknowledges, and routes `SELECTION` / `URL` / `EMAIL` / `PHONE` / `SECTION` / `DERIVED` into the `STRING` case explicitly.
  * **`addAttribute` auto-resolves type from the taxon** — `addAttribute`'s `TypeAtCreation` resolution now follows the same precedence as `setAttribute`: `opts.type` wins, then runtime `TaxonResolver`, then the document's cached taxonomies, then inference from the supplied typed-value field. Previously scripts calling `addAttribute({tag:"chargecode", stringValue:"DSC"})` logged "filled" but the resulting attribute couldn't bind to form `SELECTION` dropdowns, the formula evaluator, or conditional-format rules. Choice between `addAttribute` and `setAttribute` is now about find-or-create semantics, not type safety.
  * **`path` opt on `addAttribute` is ignored with a warning** — Paths have been derived from `parent + tag` since ENGG-5214; the `path` opt was silently dropped before, now `log.warn`s so callers can see they should drop it. `SPEC.go` no longer lists `path` as a valid option.
  * **Script dirty tracking across nested data objects** — `ScriptDataObject` traversal now propagates `parentDoc` so attribute changes made on a nested object correctly mark the document dirty for downstream persistence.

  **Document formulas & extraction:**

  * **Empty group refs return an empty list** (ENGG-5227) — Formulas like `sum({Accessorials/ChargeAmount})` evaluated against a parent whose child group had no instances (e.g. all accessorial rows deleted) previously returned a `"reference could not be found"` error, and the recalculator skipped the write — leaving the previously computed Sum of Line Items on screen instead of zeroing it. The path resolver now returns `[]` for the empty-group case (matching the sibling branch's existing semantics that `sum/min/max/avg` rely on), and the formula explain panel stops surfacing "Reference X/Y could not be found" for empty groups.
  * **Missing-reference errors null out the stored value** (ENGG-5227) — When `EvaluateFormula` returns a new `MissingReferenceError` (distinct from syntax/runtime errors), the recalculator now nulls the attribute's stored value fields and persists. Transient evaluation failures still preserve the previous value so they don't blank legitimate output.
  * **`DataAttribute.path` is derived everywhere** (ENGG-5214 close-out) — The `path` column has been dropped from `kddb_data_attributes`; every read now routes through `GetPath()` which composes `parent.path + "/" + tag` on the fly. Extraction, move, copy, formula reactivity, and the WASM serializer have all been migrated. External consumers reading attribute path from the JSON envelope are unaffected — the field is still emitted with the same value, just computed instead of stored. (The Go `DataAttribute.Path` field and `pathOverride` argument on `CopyDataAttribute` have been removed.)

  **Knowledge:**

  * **Knowledge feature search hits `extendedProperties` and numeric values** — The "Filter by feature" popup's `?query=` search runs against the `search_text` column, which previously only indexed slug + string-valued `Properties`. Human-readable labels stored in `ExtendedProperties.name` were never matched, and numeric scalars (e.g. `shipperCode: 1540`) were silently dropped — typing "JSP" returned zero matches even though chips render the full "JSP International - Legacy" name. `BuildSearchText` now walks both `Properties` and `ExtendedProperties` recursively, stringifying every string/number/bool scalar; a companion migration rebuilds `search_text` for every existing row so environments don't have to re-save each feature.

  **Orchestrator:**

  * **`loadTaxonomy` reads structured metadata, not stale `yaml_source`** — The script-engine adapter was reading `kdxa_taxonomies.yaml_source` and re-parsing YAML. `yaml_source` is a round-trip snapshot that drifts behind the structured `metadata` column whenever a client (`kdx sync push`, platform PUT) updates the taxonomy without rewriting the YAML. Scripts then validated taxon paths against the stale text, surfacing as `"taxon path X does not exist in taxonomy Y"` in plans that referenced recently added taxons. The adapter now reads `metadata::text` and parses the JSON via `yaml.v3` (which handles JSON as YAML 1.2).
</Update>

<Update label="2026-05-27" tags={["Release", "Platform", "Data Forms", "Studio", "Analytics", "API"]}>
  ### Release 2026.4.1

  Rollup of every customer-facing change between 2026.4 and 2026.4.1. The largest items: a new **CDC Data Lake** that mirrors every metadata change and document delta into S3, a **Page Groups** picker in the document viewer that lets reviewers jump straight to each classified section of a multi-document PDF, **declarative keyboard shortcuts** in V2 data forms, and a reshaped **Take Next** API that finally distinguishes "nothing to do" from "filtered out by team" from "lost the race." A long tail of validation, formula, and extraction fixes ride along.

  Already documented separately: [activity-plan scripts can spawn follow-up Activities](#activity-plan-scripts-can-spawn-follow-up-activities) (the 2026-05-26 entry — it's also part of this release).

  **Studio reviewer workflow:**

  * **Page Groups picker on the document viewer** — A new `file-multiple-outline` button in the spatial toolbar opens a popover listing each classified physical document on the open file (e.g. `Invoice — Pages 1–3`, `Delivery Receipt — Pages 4–6`), with a taxon-colored swatch and click-to-navigate to the start of each group. Built on top of the preprocessor's per-page classifications + group UUIDs (below) and the existing `tagMetadataMap` so the labels and colors match what the rest of the UI shows.
  * **Spatial toolbar cleanup** — The Show Advanced (`wrench`), Developer Info (`i`), and Page Groups buttons now sit before the find-text input so narrow document panels don't wrap them onto a second line.
  * **Kiosk: step-out confirm before fetching next work** — Reviewers leaving a kiosk task now get a confirm prompt before the next task is auto-claimed, preventing the accidental "I just finished but the next one already opened" race.
  * **Require a comment on task-template actions** (new) — Task-template actions can now declare `requireComment: true` (with an optional `commentPrompt` string). When the reviewer clicks the action, a shadcn dialog opens for a mandatory comment **before** the action runs; cancelling aborts the action with no partial state. The comment rides the existing `/api/batch-update` payload as `task.completedActionComment` and is persisted server-side as a `COMMENT` task activity tagged with the action's UUID so the timeline can link the comment back to the action that produced it. See [Requiring comments on actions](/guides/task-templates/requiring-comments-on-actions) for the full recipe.
  * **Take Next API: EMPTY envelope replaces 204** (ENGG-5208) — `POST /api/tasks/assign-next` previously returned a bare 204 in three distinct situations: nothing queued, filtered out by team, or claim race. The endpoint now always returns 200 with a typed envelope and a reason code (`EMPTY`, `FILTERED_OUT`, `CLAIM_LOST`) so the UI and external integrations can react appropriately. The `projectId` parameter is also now required and the team filter is enforced for platform admins (ENGG-5209). **Integrators that relied on the old 204 will need to update.**
  * **Task lock decoupled from document family lock** — A task's lock no longer takes out the entire document family. Multiple reviewers can now work different tasks against the same document concurrently when the task-status policy permits. Existing locking behaviour is preserved for status types that explicitly opt into `lockDocumentFamily`.
  * **Faceted filtering across grids** — Tasks, Task Groups, Activities, and other primary grids now support faceted filtering by document-family feature + the family itself, surfaced through a shared `KodexaGridFacetBar` component. Saved filter state survives navigation.
  * **Activities grid: file-name filter clears on task completion** — Completing a task no longer leaves a stale file-name filter on the activities grid.
  * **Team slug surfaced in grids and forms** (ENGG-5185) — Team slugs are now visible in team listings and editable in create/edit forms, matching the slug-everywhere convention used by other resources.

  **Data Forms V2:**

  * **Declarative keyboard shortcuts** (ENGG-5244, new) — V2 forms can now declare a `shortcuts:` array at the top level. Each entry binds a key combination to a named script and is registered under a per-form scope, so a form **resets all of its shortcuts every time it mounts** with no manual cleanup. See [Keyboard Shortcuts](/guides/data-forms/shortcuts) for the schema, lifecycle semantics, and worked examples.

    ```yaml theme={null}
    shortcuts:
      - key: "control+1"
        description: "Jump to Invoice"
        scriptRef: gotoInvoice
      - key: "control+t"
        description: "Focus invoice total"
        scriptRef: focusTotal
    ```

  * **Bridge navigation actions** (ENGG-5244) — `kodexa.navigation` (the bridge namespace shortcut scripts call) now has real `setPage(page, documentFamilyId?)`, `getCurrentPage(...)`, and `getPageCount(...)` methods alongside the existing `focusAttribute(...)`. Spatial methods are 1-based externally and route to the document viewer for the form's first document family by default. See [Bridge API & External Services → kodexa.navigation](/guides/data-forms/bridge-api#kodexa-navigation).

  * **Markdown editor scroll restored** — Internal scroll is back on the markdown editor, capped at 1.5× `--editor-height` so the editor no longer takes over the page on long content.

  **Document preprocessing & extraction:**

  * **Preprocessor: canonical taxon-path tagging** (ENGG-5240) — When the preprocessor is configured with a `taxonomy:` option, the LLM-returned `document_type` labels (e.g. "Bill of Lading") are translated to canonical taxon paths (`billoflading`) before pages are tagged. This makes the preprocessor's page tags match what downstream `kodexa/llm-taxonomy-model` writes, eliminating the duplicate `Invoice` + `invoice` tag instances that were appearing in reviewer-facing UI. The original LLM-returned label is still kept as a `preprocessor.document_type` feature. Existing plans without `taxonomy:` set are unchanged.
  * **Preprocessor: multi-page group on the tag** — Page tags now carry `groupUUID` (deterministic per `source_page.group`) and `value` (the sequence within the group), so consumers reading tags alone can reconstruct which pages belong to the same physical document. The existing `preprocessor.group` and `preprocessor.sequence` features are kept for backward compatibility.
  * **Spatial copy: cluster by line before sort** (ENGG-5205) — Multi-line copies from the spatial viewer were occasionally returning words in the wrong order when lines overlapped on the Y axis. The spatial sort now clusters by line first so copied text reads in natural order.
  * **Default copied attribute path** (ENGG-5214) — Copying an attribute to a different parent now defaults the new path / tag to the destination object's own path, instead of carrying the source's path forward.
  * **Formula reactivity scoped to lineage owners** (ENGG-5195) — Conditional-format and formula reactivity now routes to the lineage-scoped owner instead of fanning out across the document, which removes the perceived "everything recomputes" lag on edits in deep tag hierarchies.
  * **Conditional formats batched per owner** — `EvaluateAllConditionalFormatsBatch` is now gated on the conditional-format owner set, fixing intermittent integration-test timeouts and reducing wasted work in kodexa-ui.
  * **Reactive validation group rules + auto-derived exception path** — Group-level validation rules now re-evaluate reactively when their inputs change, and exception paths are derived automatically so authors don't have to maintain them by hand.
  * **Knowledge-feature taxon refs use canonical ExternalName chain** (ENGG-5221, ENGG-5222, ENGG-5223) — Several long-standing inconsistencies between the path used to look up a taxon and the path stored on dependency graphs / init-paths / refresh validation have been aligned to the canonical `ExternalName` chain. Symptoms that should now stop: stale validation results after a tag refresh, formulas resolving to the wrong taxon when org slugs were nested, init paths failing to find selection options after an external-name change. The WASM attribute-value bridge also now returns type-aware values (numeric, boolean, date) instead of always-string.
  * **Absolute formula refs require leading slash** (ENGG-5221) — Formula references intended as absolute (across taxonomies) must now start with `/`. Existing absolute refs that already had the leading slash are unchanged; ambiguous refs that worked accidentally before will now be treated as relative.

  **CDC Data Lake (new service):**

  Kodexa now mirrors every metadata change and document delta into an S3-backed data lake, structured for direct query by analytics tools. The lake is on by default for new deployments; existing deployments can opt in via the standard `STORAGE_LAKE_BUCKET` configuration.

  * **Envelopes** under `entities/` mirror every `kdxa_metadata_audit` write (an audit row is created for every create/update/delete of AbstractMetadata-managed resources — task templates, knowledge sets, activity plans, etc.).
  * **Activity envelopes** under `activities/` mirror every activity status transition, with rolled-up step errors and deferred publish until the originating database transaction commits (ENGG-5231) so no half-applied state leaks to the lake.
  * **Step / step-document envelopes** carry full `errorDetails` (ENGG-5235), so analytics dashboards can surface the actual exception message and stack from a failed step without re-querying the source database.
  * **Content-objects** under `content-objects/` are populated from the KDDB projection on `CONTENT_CREATED`, giving the lake the post-Apply view of every data object the orchestrator persisted.
  * **Batch context** ships task-template ref + work-session context on every batch envelope (ENGG-5202 phases 1–3), so audit / analytics consumers can correlate every change back to the user session that produced it.
  * The schema is intentionally append-only; rebuild scripts and a `CHANGELOG.md` under `kodexa-cdc-lake/` document the supported event shapes and projection logic.

  **Audit log + metadata refactor:**

  * **AbstractMetadata audit log** (ENGG-5150) — A `kdxa_metadata_audit` table now records every create/update/delete on AbstractMetadata-managed resources (task templates, knowledge sets, knowledge items, knowledge item types, knowledge feature types, knowledge features, activity plans, prompts, data forms, data definitions). Each row carries the actor, source IP, work-session ID, and a JSON snapshot of the change. Append-only enforced at the DB level.
  * **Generic slug auto-generation + uniqueness** — Any AbstractMetadata resource created without a slug now gets one auto-generated from its name, and a `UNIQUE (organization_id, slug)` index is enforced on ten audited tables. Nested org refs are resolved on every create/update so manifests can reference an org by ID, slug, or full URI.
  * **Knowledge create/update polish** — Knowledge Item creates now populate `slug` and `knowledge_set_slug` correctly. Duplicate-key responses now return a clear 409 with the conflicting field instead of a 500 (PX-10). `name` ↔ `set_name` and `type` ↔ `set_type` are mirrored in `BeforeCreate` / `BeforeUpdate` so legacy clients writing one form see consistent reads on the other.

  **Analytics datasets:**

  * **Document-family features in tasks / groups / links datasets** — The `tasks`, `task_groups`, and `task_group_links` datasets exposed via the analytics view now include each row's owning document family features (knowledge features attached to the family), so reports can group / pivot by feature without joining a separate feed.

  **Auth & user sessions:**

  * **Email extraction from non-standard claims** (ENGG-5203 phase A / A.1) — Login no longer fails for users whose ID token lacks a standard `email` claim. We now check standard OIDC claims, namespaced Auth0 claims, and finally fall back to `kdxa_users` lookup by sub.
  * **Work-session start time on /api/batch-update** (ENGG-5203 phase B) — The UI now sends `userWorkSession.startedAt` (the actual session start) instead of the dead `transactionStart` field that defaulted to the current time. Audit rows that previously showed every change as starting "now" now carry the correct session boundary.

  **kodexa-ui platform polish:**

  * **Pop-out keeps main tab as WASM owner** — Opening a document in a pop-out window no longer transfers WASM ownership; the main tab stays authoritative and the pop-out reads through.
  * **Sidecar heartbeat tightened** — Heartbeat now counts only actual ping responses, not noise from other event types, so disconnect detection is more reliable on slow networks.
</Update>

<Update label="2026-05-26" tags={["Platform", "Activities", "Scripting"]}>
  ### Activity-plan scripts can spawn follow-up Activities

  A SCRIPT step's return value can now include a `nextActivity` block that asks the platform to start another Activity Plan when the **current Activity** completes. Use this to chain related workflows — intake → extraction, classification → enrichment, validation → posting — without an external orchestrator.

  * **Return shape**: alongside `action` and the existing `features` array, scripts can now return:

    ```javascript theme={null}
    return {
      action: "approve",
      nextActivity: {
        activityPlanRef: "activity-plan://acme-finance/billing-extraction",
        inputs: { reviewedBy: org.userEmail },
        documentFamilyIds: [families[0].id],
        features: [
          { documentFamilyId: families[0].id, featureId: "fc_billing_ready" }
        ]
      }
    };
    ```

  * **Deferred spawn**: the new Activity starts when the current Activity reaches `COMPLETED`, not at the moment the script returns. Multiple SCRIPT steps in one plan may each emit their own `nextActivity` and they fan out at completion in step insertion order.

  * **Same-project only** for v1. The target plan must already be bound to the current project via `project_resources`. Cross-project spawns are rejected.

  * **Inheritance**: when `documentFamilyIds` is omitted, the spawned Activity inherits the source Activity's document families. Server-controlled `triggerMetadata` (`sourceActivityId`, `sourceStepId`, `sourceActionUuid`, `sourceProjectId`) is always merged in last so the audit trail can't be spoofed; the spawned Activity's `triggerKind` is `ACTIVITY_COMPLETED`.

  * **Soft failure**: spawn errors (missing plan, FGAC denial, input validation failure) leave the source Activity completed and record the reason in `script_result.nextActivityError`. On success, `script_result.nextActivityId` points back to the new Activity.

  * **Feature attachments**: `nextActivity.features` is applied to the named document families immediately, before the spawn fires, so the new plan's templates and scripts see them via the existing template context.

  See [Spawning a Follow-Up Activity](/guides/activity-plans/script-steps#spawning-a-follow-up-activity) for the full reference and the [Script Steps deep API reference](/guides/script-steps) for the runtime contract.
</Update>

<Update label="2026-05-13" tags={["Platform", "Activities", "Task Groups", "Knowledge", "Scripting", "API"]}>
  ### Task Groups, the New Activity experience, and knowledge in scripts

  This release rounds out the Activity-centered workflow model. Reviewers can now batch related work into Task Groups; the New Activity surface replaces the old New Task entry points; activity plans get a richer editor; and activity-plan scripts gain a first-class `knowledge` global.

  **Task Groups (new):**

  * **Bundle tasks into a single assignment unit** — Select related tasks from any Tasks tab and use **Create task group** to wrap them under one name, description, priority, status, assignee, and team. Members work the group as a unit instead of picking off individual tasks.
  * **Groups tab and kiosk Take-Next** — Each project and organization now has an always-on **Groups** tab. Reviewers can claim the next eligible group from the kiosk widget without manual selection, and the workspace opens a guided drawer with auto-advance between member tasks and a completion summary.
  * **Slide-over detail panel** — Clicking a row opens a side panel that manages status, assignee, member tasks, history, and delete in one place. The Tasks grid now shows a clickable group chip on grouped rows so you can jump straight to the panel.
  * **Permission-gated** — The Groups tab and Take-Next kiosk action appear only when the viewer's role permits them.

  **New Activity experience:**

  * **New Activity is the primary CTA** — Workflow org-home and project-home Activities tabs now lead with **New Activity** (replacing the old "New Task" button). Project Home adds a split-button so you can start an Activity or kick off a Job Run from the same control.
  * **Two-step Activity wizard** — Pick a project, pick an activity plan, then fill in title, description, priority, and documents on the same form. Document upload is inline; AI naming proposes a title from document content when enabled.
  * **Activity Plan editor** — Visual editor with tabs, schema-driven properties panel, manual layout with persisted positions, slug shown under each step's name, action-qualified edges, badges auto-generated from module refs, and per-step **Cancel** and **Reprocess** actions. Plans get a delete action consistent with task templates.
  * **Document Families on Activities** — Activities own their document families directly. The new `GET /api/activities/{id}/steps/{stepId}/document-families` endpoint returns the documents touched by a step. CREATE\_TASK steps automatically copy the activity's document families onto the task they materialize, so review surfaces always have the right context. `PATCH /api/activities/{id}/steps/{stepId}` is also available for step updates.
  * **Activity steps in the API** — `GET /api/activities/{id}` now embeds the full step list in the response.

  **Knowledge in activity-plan scripts:**

  * **`knowledge` global in script runtime** — Activity-plan SCRIPT steps and routing scripts now expose a `knowledge` object scoped to the script's permitted document families:
    * `knowledge.getFeatures(familyId)` and `knowledge.getItems(familyId)` return the raw feature and item instances on a family
    * `knowledge.featuresByType(familyId, featureTypeRef)` and `knowledge.itemsByType(familyId, itemTypeRef)` filter by type
    * When the script operates on a single family, `knowledge.features` / `knowledge.items` return that family's data directly
    * Features and items are enriched with their full type definitions and frozen, so scripts can read everything they need without separate lookups and can't accidentally mutate the source data
  * See the [Scripting — Knowledge bindings](/guides/scripting/index) guide for usage patterns.

  **Knowledge resolution by org slug:**

  * Knowledge Sets, Knowledge Items, Knowledge Item Types, Knowledge Feature Types, and Knowledge Features can now be created, updated, and referenced by `orgSlug` + `slug` (or `itemTypeRef` / `featureTypeRef`) on every create and PUT path. Manifests no longer need internal UUIDs to round-trip.
  * The resource resolver supports a new `knowledge-item://` URI scheme.
  * `/api/knowledge-features?query=` now actually searches feature name, type name, and description (previously narrowed the result set incorrectly).

  **Document family activities:**

  * **Step dots on document family cards** — Document family cards now show a row of dots indicating each activity step's state for that document. Hover for the step name and status; click an activity to open it. The same display appears in document grids via the activity cell renderer.
  * Per-document activity data is batch-fetched, so even large document lists open without per-row API churn.

  **Studio and workflow navigation:**

  * **Workstreams tab removed** — Project navigation no longer shows the legacy Workstreams tab.
  * **Resources panel** — The Studio resources panel now surfaces task templates and activity plans alongside other project metadata.
  * **Org-level activities** — Activities filter by `lifecycleState` instead of the removed `status` field; the old org-home Activities tab variant has been retired in favor of the unified grid.

  **Knowledge UI improvements:**

  * Feature palette includes a search box and caps at 30 visible items at a time, so palettes with many feature types stay usable.
  * The Applications tab shows a document family + content object inspector so you can drill into the source content behind a knowledge feature.
  * Knowledge Features get a reworked card layout and detail overview, with feature properties and `extendedProperties` exposed to AI naming templates.

  **Data form and document grid polish:**

  * **Clearing a SELECT now nulls the value** — Clearing a selection-type attribute properly clears its underlying value (not just the display string), so dependent formulas, conditional formats, and validators react correctly.
  * **"Edited Value" indicator on clears** — When you clear an AI-extracted value, the form now marks the cell as user-edited so the next extraction pass won't silently overwrite it.
  * **Better grid editing feedback** — Invalid Number cells show a focus ring while focused; grid Add no longer freezes the row gate; autocomplete dropdowns match by substring (not just prefix); SELECT popovers stay open across ag-grid cell destroy/recreate.
  * Formulas re-evaluate when the data-object cache refreshes, so derived values follow upstream edits without a manual refresh.

  **Performance:**

  * **Faster project load** — Project resources are now fetched in bulk with deduplicated module wiring, and a no-op assistant-connections endpoint has been removed from the load path.

  **Agent runtimes:**

  * Channel-scoped workspace blob store keeps chat attachments and drafts per channel.
  * Conversations continue across sessions via SessionStore continuation, so picking a chat back up doesn't reset context.
  * Task-scoped chats now see the task's document store refs.
  * Module refs can use a `{org}` placeholder so plans are portable across organizations.

  **Notes for API consumers:**

  * Activity lifecycle now lives on `Activity.lifecycleState` (`DRAFT`, `RUNNING`, `PAUSED`, `COMPLETED`, `CANCELLED`, `FAILED`). The previous `Activity.Status` field has been retired; existing data is migrated automatically. Update integrations that read the old field.
  * Activity step `kind` is now `type` across the database, API, and UI (`EXECUTION`, `SCRIPT`, `BRIDGE_CALL`, `CREATE_TASK`, `APPROVAL`, `LLM`, `AGENT`). Existing rows are migrated; new activity-plan YAML should use `type`.
  * `/api/plans` has been retired now that the UI runs entirely on `/api/activities`. The OpenAPI spec has been regenerated with 20 previously-undocumented routes added — point external integrations at `/api/activities` and refresh generated SDKs.
</Update>

<Update label="2026-05-11" tags={["Platform", "Breaking", "API"]}>
  ### Assistant connections removed

  **Breaking change.** Assistant connections and the connection-driven event router in the orchestrator have been removed across the platform.

  * `/api/assistant-connections` REST endpoints (GET, POST, PUT, DELETE) have been removed. Clients calling these endpoints will receive 404.
  * The `AssistantConnection` and `ProjectAssistantConnection` types are gone from the Python SDK and the generated TypeScript models.
  * Domain events (document family, channel, batch, content) are still emitted by producers, but the orchestrator no longer routes them to assistants via connections — those events are now drained from the SQS queue without action.
  * Activity-related events (`PLAN_CREATED`, `TASK_UPDATED`, `REPROCESS`) continue to flow through the orchestrator's plan advancer, trigger evaluator, and reprocess handler unchanged.
  * The `kdxa_assistant_connections` database table is retained but emptied by migration; nothing reads or writes it.
  * In the CLI, `kodexa-cli pull` no longer writes `assistant-connections/` directories, and `kodexa-cli apply` warns and ignores any legacy on-disk `assistant-connections/` content.
  * The Studio data-flow editor has been removed; without connections the editor had no edges to render.

  The triggers model (introduced as part of the Activity refactor) is the planned replacement for event-driven assistant invocation. The trigger evaluator is already wired into the orchestrator for `task_status_changed`; broader trigger-based routing will follow in a subsequent release.
</Update>

<Update label="2026-05-02" tags={["Platform", "Activities", "Data Definitions", "Data Forms", "CLI"]}>
  ### Activity-centered workflows, reactive validation, and richer operations tooling

  This release continues Kodexa's move to an Activity-centered model for document-heavy business processes. Activities represent the business process run. Tasks represent the human review, correction, approval, or exception work that happens inside that run.

  **New Features and Improvements:**

  * **Activities as first-class workflow runs** — Activity Plans, Activity runs, and Activity steps are now the primary model for orchestrating automated work, human review, integrations, and audit history. Activity detail APIs now include step data so user interfaces and integrations can show the run and its materialized work together.
  * **First-class Service Bridge steps** — Activity Plans can call configured Service Bridges as workflow steps. Request method, URL, body, response body, and result details are captured with the step so teams can review and troubleshoot external system calls without leaving the workflow.
  * **Activity authoring improvements** — The flow editor now supports manual layout, persisted node positions, connection labels, context menus, compact step palettes, Service Bridge nodes, schema-driven configuration, and project/intake bindings.
  * **Per-document execution visibility** — Execution details now surface at the document-family and step level, including active or failed steps, logs, execution IDs, and error details for faster operational review.
  * **Reactive Data Definition validation** — Changes to data definitions, selection options, conditional formats, validation rules, and document data now trigger scoped revalidation. Matching exceptions are created, closed, or reopened as the document moves in and out of compliance.
  * **Richer exception review in Data Forms** — Review surfaces now show more complete exception detail, filter open exceptions consistently, support override metadata and support article references, and can scope actions to specific exception paths.
  * **Knowledge snapshot review** — Knowledge Sets now include snapshot panels, feature chips, and visual diffs so teams can review knowledge changes before and after updates.
  * **CLI and GitOps improvements** — `kdx sync` now preserves project-resource links more reliably, records sync state for task templates, annotates manifest project keys with readable names, sorts legacy associations deterministically, and supports pre-package `metadata.build` hooks. A new `kdx secret` command adds organization secret management from the CLI.
  * **Document handling improvements** — Preprocessing can correct document rotation and summarize documents. The document viewer now handles processed PDFs and rotated spatial overlays more consistently.
  * **Operational observability** — Platform errors, upload failures, subscription failures, and Activity/execution status changes now emit sanitized structured events for better monitoring without exposing sensitive request data.

  **Configuration Note:**

  Module runtime configuration is now standardized on `metadata.moduleRuntimeParameters`. Update any module YAML still using `modelRuntimeParameters`.
</Update>

<Update label="2026-04-26" tags={["Platform", "Scripting", "CLI", "Breaking"]}>
  ### Script API consolidation, document-resident taxonomies, and shared script helpers

  Three related changes ship together. The first is breaking; the rest are additive and unlock smaller, more maintainable scripts.

  **1. Script API consolidation (breaking change)**

  The JavaScript API for intake scripts, planner script steps, taxonomy event subscriptions (browser and Python contexts), and module scripts has been modernized onto a single canonical surface. **Scripts written against the legacy API need updating.**

  * **Method names are now camelCase.** `currentObject.GetFirstAttributeValue("foo")` → `currentObject.getFirstAttributeValue("foo")`. Same rule for every method on `currentObject`, `document`, attributes, and content nodes. Scripts using PascalCase fail with `TypeError: Object has no member 'GetFirstAttributeValue'`.
  * **`bridge.data.*` is removed.** `bridge.data.setAttribute(currentObject.GetID(), name, value)` collapses to `currentObject.setAttribute(name, value)`. `bridge.data.getAttribute(...)` collapses to `currentObject.getFirstAttributeValue(name)`. Calling the removed surface throws `bridge.data is undefined`.
  * **`log()` is now structured.** Replace `log("info", "msg: " + x)` with `log.info("msg:", x)`. `log.warn`, `log.error`, and `log.debug` follow the same variadic shape (args joined with spaces, like `console.log`). Calling `log()` positionally throws `log is not a function`.
  * **`getType()` on content nodes is renamed to `getNodeType()`.** Scripts iterating selector results and reading the node type need a one-word find/replace.
  * **`serviceBridge.list()` is removed.** Discovery now lives in the platform admin surface; scripts reference bridges by known `"orgSlug/bridgeSlug"` refs.

  New helpers that reduce boilerplate:

  * **`doc.getOrCreate(path)` / `obj.getOrCreateChild(path)`** — find-or-create idempotent. Replaces the `findFirst → if null create` pattern.
  * **`obj.setAttribute(name, value)`** — find-or-create on an attribute and write a typed value in one call.
  * **`obj.payload({ key: "attrName", ... })`** — extract a JS object suitable for `serviceBridge.call` payloads. Missing attributes default to `""`.
  * **`taxon.optionLabel("taxonName", value)`** — look up the human label for a selection-option value. Replaces hardcoded label maps in event scripts.
  * **Default `path` and `ownerUri`** — write methods (`addAttribute`, `copyAttributeFrom`, etc.) derive `path` from `parent.path + "/" + tag` and `ownerUri` from the runtime's script context. Specify only when overriding.

  Migration: every change is a mechanical find/replace. The full reference is in the [Scripting guide](/guides/scripting/index). Tenants with custom scripts stored in the platform (intake scripts, planner scripts, taxonomy event subscriptions edited via the UI) should update those scripts before upgrading. The browser WASM bundle is bumped to API version 2; the existing reload prompt detects mismatched bundles and asks users to reload.

  **2. Document-resident taxonomy resolution**

  `setAttribute(name, value)` now resolves the attribute's type from the document's cached taxonomies — scripts no longer need to declare `type: "SELECTION"` (or any other type) on writes. The resolution chain is: VM-supplied resolver → document's cached taxonomies (loaded by extraction) → fallback inferred from the JS value's runtime type.

  ```javascript theme={null}
  // Before — explicit type declaration needed
  shipment.addAttribute({ tag: "shippercode", value: "142600", stringValue: "142600", type: "SELECTION" });

  // After — type resolved from the document's taxonomies
  shipment.setAttribute("shippercode", "142600");
  ```

  Scripts can also extend the document's in-scope taxonomies at runtime:

  ```javascript theme={null}
  document.addTaxonomy(myTaxonomy);  // subsequent setAttribute calls see it
  ```

  **3. Script sidecars on task templates**

  Task-template SCRIPT items can declare a list of module refs whose JS scripts are pre-loaded into the runtime before the main script body runs. This lets multiple templates share helper functions instead of inlining the same code in every block.

  ```yaml theme={null}
  - type: SCRIPT
    name: Initial Enrichment
    scriptSidecars:
    - acme-finance/invoice-helpers
    script: |
      // copyNewAttributes is provided by the sidecar — no inline definition needed
      copyNewAttributes(target, source, [{src: "amount"}, {src: "date"}]);
  ```

  Refs use the standard `"orgSlug/moduleSlug"` form. Module declarations (loaded as functions/vars) land on the global scope and behave like any other helper in the main script.

  **4. CLI: `metadata.scriptPath` for module YAML**

  Module YAML can now reference an external `.js` file via `metadata.scriptPath`; `kdx sync push` reads the file and inlines it into `metadata.script` at deploy time:

  ```yaml theme={null}
  # models/invoice-helpers.yml
  orgSlug: acme-finance
  slug: invoice-helpers
  type: store
  storeType: MODEL
  metadata:
    scriptLanguage: javascript
    scriptPath: ../scripts/invoice-helpers.js   # editor-friendly source of truth
  ```

  Inline-script-only modules (the sidecar shape) don't need a `contents:` block — `kdx` skips the implementation zip-and-upload path entirely and logs `📜 Module {slug} is inline-script only — skipping implementation upload`.

  Existing modules with inline `metadata.script` or a populated `contents:` block are unaffected.
</Update>

<Update label="2026-04-14" tags={["Platform", "CLI", "SDK"]}>
  ### Platform Updates — Mid April 2026

  **New Features:**

  * **Markdown Image Paste** — Markdown editors now support Cmd/Ctrl+V image pasting and drag-and-drop. When editing knowledge items, pasted images are automatically uploaded as knowledge set attachments and referenced via portable `attachment://` URLs. In standalone contexts, images are base64-encoded inline.
  * **Selection Option Formulas** — Data definitions now support formula-driven selection options with a formula mode toggle and extended fields, enabling dynamic dropdown values computed from other attribute values in the document.
  * **Exception Override** — Data forms now support overriding validation exceptions directly from the workspace with WASM persistence and a form-scoped exception details panel.
  * **Tab Key Grid Navigation** — Tab key now navigates between input fields in grid cells for faster data entry.
  * **Filterable Knowledge Tables** — Markdown tables rendered in knowledge sections now include a search bar for filtering rows.
  * **Service Bridge Status Override** — `postReplyScript` can now override the HTTP response status code returned by a service bridge endpoint.
  * **Intake and Label URI Schemes** — The API resolver now supports `intake://` and `label://` URI schemes for resource resolution.

  **CLI Improvements:**

  * **YAML Round-Trip Preservation** — `kdx sync pull` now preserves YAML comments and formatting using a new `yamlpatch` engine. Pushed resources include the original YAML source for lossless round-trips.
  * **Smart Discover Merge** — `kdx sync pull --discover` intelligently merges newly discovered resources into existing YAML files, preserving comments and manual edits.
  * **Attachment Download** — `kdx sync pull` now downloads knowledge set attachments alongside metadata.
  * **Discover Directory Flag** — New `--discover-dir` flag sets the `metadata_dir` in the generated manifest during discovery.
  * **Conflict Detection** — Sync state tracking detects when remote resources have changed since the last pull, with a `--force` flag to override conflicts.
  * **Cross-Org Push** — `kdx sync push` rewrites organization slug references in YAML values when pushing to a different organization.
  * **Dependency-Aware Push** — Resources are pushed in dependency order to avoid reference errors during deployment.
  * **Parallel Pull/Push** — Sync operations now run in parallel for faster execution.
  * **Legacy Server Compatibility** — Improved compatibility with older Kodexa servers including paginated API responses, case-insensitive slug matching, and fallback resource fetching.

  **Platform Improvements:**

  * **Optimistic Locking** — Tasks, document families, and batch updates now use change-sequence-based optimistic locking to prevent concurrent modification conflicts.
  * **Service Bridge Observability** — Service bridge proxy calls now emit Datadog events with request and response body details.
  * **Selection Formula Scoping** — Selection formula evaluation is now scoped to ancestor data objects for more predictable results.
  * **Auto-Select Single Option** — Dropdown fields with a single available option are automatically selected when the field is empty.
  * **Attribute Editor Consistency** — Attribute editors now emit updates on blur rather than on every keystroke, reducing unnecessary saves.
  * **Readonly Field Styling** — Readonly form fields are now visually distinguished with a border and muted background.
  * **WASM Binary Size** — The WASM binary has been reduced by 20.8% by removing unused expression engine dependencies.
  * **Detached Sidecar Toolbar** — The detached sidecar window now includes the full document toolbar and page navigation.

  **Bug Fixes:**

  * Fixed service bridge calls not re-firing when dependency values changed.
  * Fixed selection options formula toggle not responding to clicks.
  * Fixed missing formula attribute references causing errors instead of resolving to nil.
  * Fixed document store table view checkbox selection and row click behavior.
  * Fixed chat session loading failing when reopening an existing conversation.
  * Fixed LLM JSON response preprocessing to handle truncated or malformed responses.
  * Fixed task locking and auto-lock behavior in plan advancement.
  * Fixed form freeze, dropdown UX glitches, and validation timing issues in data forms.
  * Fixed inline grid editing focus loss when attribute data updates arrived.
  * Fixed extracted selection values being accepted even when not in the dropdown options list.
  * Fixed GoJA script runtime not persisting `AddChild`, `SetTaxonomy`, `SetPath`, and attribute mutations to the document.
</Update>

<Update label="2026-04-05" tags={["Platform", "CLI", "SDK"]}>
  ### Platform Updates — Early April 2026

  **Improvements:**

  * **Scoped Document Reprocessing** — `POST /api/document-families/{id}/reprocess` now accepts an optional `assistantIds` request body. When omitted, the platform auto-detects prior assistant contributions and reprocesses the family asynchronously.
  * **Document Family Feature Filters** — Document families can now be filtered through attached knowledge-feature relationships such as `features.id=='...'` and `features.slug=='...'`.
  * **Module Package Selection** — Python runtimes now honor `metadata.moduleRuntimeParameters.module` when a module archive contains multiple packages, ensuring the intended package is imported before execution.
  * **Completion Event Chaining** — Applying an execution's `completeLabel` now emits a follow-up `CONTENT_CREATED` event so downstream subscriptions can react to the finalized content.
</Update>

<Update label="2026-03-24" tags={["Platform"]}>
  ### Platform Updates — Late March 2026

  **New Features:**

  * **Intake API Tokens** — Intakes now support scoped API tokens for machine-to-machine authentication. Create tokens on the new API Tokens tab; each token authenticates directly against a specific intake endpoint without requiring user credentials. Tokens are hashed at rest with SHA-256.
  * **Detachable Sidecar** — Pop out the sidecar document viewer into a separate browser window using the detach button. The inline sidecar collapses while the external window is open and automatically restores when the external tab is closed.
  * **Smart Grid Filters** — All grid views (tasks, projects, document families, etc.) now include a unified search bar with recent query history, structured filter mode with metadata-aware autocomplete, and AI-powered natural language filter generation.
  * **Script Step Log Viewer** — Script step logs are now captured in CloudWatch and viewable directly from Activity step details. Each script execution automatically records start/end entries and all `log()` calls. See [Script Steps](/guides/script-steps/index#viewing-script-logs).
  * **Knowledge Expression Trees** — Knowledge sets now support expression-based feature matching using AND, OR, and NOT operators, replacing the previous clause-based system. This enables more flexible conditional logic for knowledge assessment. See [Knowledge System](/concepts/knowledge_system#expression-based-matching).
  * **UNO Document Converter** — New module runtime for converting Office documents (Word, Excel, PowerPoint) via LibreOffice/UNO. Available as `kodexa/uno-runtime`. See [Module Runtimes](/concepts/module_runtimes#available-runtimes).
  * **LLM Model Manager** — New Python SDK `ModelManager` class provides unified access to all LLM models through the Kodexa AI Gateway. Supports text completion, function calling, streaming, thinking mode, and multimodal input. Replaces direct provider SDKs with a single gateway client. See [LLM & Model Manager](/sdk/python/llm).
  * **AI Grid Extraction** — Data forms using `v2:grid` layout now support AI-powered grid extraction with word-level node tagging for more accurate table data capture. See [Data Forms Extraction](/guides/data-forms/extraction#ai-extraction-on-grids).
  * **Direct Extract** — New `allowDirectExtract` option on data form attribute editors lets users copy values directly from the document text without an AI call. See [Data Forms Extraction](/guides/data-forms/extraction#direct-extract).

  **Improvements:**

  * **CLI Re-Authentication** — The CLI now automatically prompts for re-authentication when it encounters a 401 response, instead of failing. See [CLI Authentication](/guides/kdx-cli/authentication#automatic-re-authentication).
  * **Access Token Security** — API access tokens are now hashed at rest using SHA-256. The profile access tokens UI has been redesigned with confirmation dialogs before deletion and tokens scoped to the current user.
  * **Module Ref Rename** — The bridge script parameters `model_store` and `model_options` have been renamed to `module_ref` and `module_options` for consistency. See [Module Runtimes](/concepts/module_runtimes#magic-parameter-injection).
  * **Datadog Observability** — New instrumentation events for agent runtimes, agent instances, and LLM calls in the AI Gateway for Datadog monitoring.
  * **Execution Cancel** — The execution cancel button in the UI is now wired to the API endpoint.
  * **Taxonomy → Data Definition** — The UI label "Taxonomy" has been renamed to "Data Definition" across resource badges and labels for consistency with the platform terminology.
</Update>

<Update label="2026-03-16" tags={["Platform"]}>
  ### Platform Updates — March 2026

  **New Features:**

  * **Agentic Assistants** — A new assistant role that delegates processing to AI agents. Configure an agent runtime, module references, and a natural language prompt to let the agent autonomously decide how to process documents. See [Assistants](/concepts/assistants#agentic-assistant).
  * **Intake Enhancements** — Intakes now support JavaScript scripting for file validation and metadata enrichment, task template integration for auto-creating tasks on upload, multi-file uploads, knowledge feature assignment, and processing metadata.
  * **Activity Workflow Enhancements** — New SCRIPT and AGENT step types. SCRIPT steps run inline JavaScript for conditional routing. AGENT steps spawn AI agents in workflow execution. Action-qualified dependencies enable conditional branching (e.g., proceed only on "Approve"). Activity runs display as interactive DAG flow visualizations with automatic deadlock detection.
  * **AI Task Naming** — Task templates can configure LLM-powered naming so tasks receive descriptive titles based on document content.
  * **Notification Sounds** — Toggle audio notifications for error/warning toasts and new channel messages from your profile preferences.
  * **Document Native Download** — New `GET /api/document-families/{id}/native` endpoint returns the original uploaded file. See [Download original native file](/api-reference/documentfamilies/get-document-families-id-native).
  * **Execution Log Viewer** — Restyled with syntax highlighting, auto-scroll, copy and download buttons, and dark theme enforcement.
  * **Progress Toasts** — Consolidated progress notifications for document uploads and batch reprocessing operations.

  **Improvements:**

  * **Secrets API** — Secrets are now managed through organization-scoped endpoints (`/api/organizations/{orgId}/secrets`) with secure encrypted storage.
  * **Resource Resolver** — Three new project-scoped schemes: `task-status`, `task-template`, and `assistant`. See [Components and Structure](/concepts/components_and_structure#project-scoped-resources).
  * **CLI Resource Resolution** — `kdx apply` now resolves project-scoped resources (task statuses, task templates, assistants) with the `scheme://org/project/slug` URI format.
  * **AI Gateway** — Extended model metadata with pricing, description, and classification fields. Cloud models now proxy through the AI gateway.
  * **Store Reprocessing** — Reprocess documents within a store with assistant selection and filtering.
  * **Document Groups** — New `hardMaxPages` field to enforce a hard page count limit at upload time.
</Update>

<Update label="2026-03-07" tags={["CLI", "Pre-release"]}>
  ### KDX CLI v2026.3.0 (Pre-release)

  <Note>
    This version is currently available as a pre-release. Install via `brew install kodexa-ai/tap/kdx-dev` to try it out.
  </Note>

  Bug fixes, deployment reliability, and E2E test coverage:

  **Bug Fixes:**

  * **Apply Ordering Fix**: Fixed an issue where `kdx apply` for modules would overwrite metadata changes. Implementation uploads now happen before metadata PUT, ensuring inference options and other metadata updates are preserved.
  * **OpenAPI Resource Discovery**: Manual resource definitions now properly override OpenAPI-discovered resources, preventing bogus CRUD paths from being generated for document-stores and other hyphenated resource types.
  * **Hyphenated Resource Types**: Fixed resource discovery for `data-store`, `data-definition`, and `document-store` by normalizing hyphens and underscores in resource lookup.
  * **Deploy Failure Reporting**: Deployment failures are now properly surfaced with error counts and non-zero exit codes, instead of silently reporting success.
  * **ID Stripping on Create**: The CLI now strips `id` and `_id` fields from CREATE payloads since IDs are server-generated, preventing conflicts during resource creation.

  **Improvements:**

  * **E2E Test Suite**: Added comprehensive end-to-end tests covering document family reprocessing, knowledge-set CRUD and resolution, module upload/download, and CLI-to-API integration.
  * **Filter Syntax**: Updated to SpringFilter DSL syntax for resource filtering, with syntax reference added to `kdx get --help`.
  * **Sort Parameters**: Standardized sort parameter format across all commands.

  **Impact:**

  * Module metadata (inference options, configuration) is now reliably preserved during `kdx apply` operations
  * `kdx sync deploy` now correctly reports failures and returns non-zero exit codes for CI/CD pipelines
  * Resource operations for hyphenated types (data-store, document-store, data-definition) work reliably

  **Breaking Changes:** None - fully backward compatible with v2026.2.1

  Available as pre-release via Homebrew: `brew install kodexa-ai/tap/kdx-dev`
</Update>

<Update label="2026-02-09" tags={["CLI"]}>
  ### KDX CLI v2026.2.1

  Bug fixes for project-scoped resource syncing and OpenAPI spec parsing:

  **Bug Fixes:**

  * **Project-Scoped Resource Sync**: Fixed an issue where syncing project-scoped resources (e.g., task templates) would fail with "TaskTemplate must have a project" errors. The PUT payload now correctly includes the project reference for project-scoped resources, mirroring the existing pattern for organization-scoped resources.
  * **OpenAPI Schema Parsing**: The CLI now gracefully handles missing `$ref` schema references in the server's OpenAPI specification. When broken references are encountered (e.g., a missing `ValidationFailedResponse`), the CLI patches in empty object stubs and retries parsing instead of failing.

  **Impact:**

  * Task template and other project-scoped resource syncing now works correctly with `kdx sync push` and `kdx sync deploy`
  * CLI operations no longer fail when the platform's OpenAPI spec contains missing schema definitions

  **Breaking Changes:** None - fully backward compatible with v2026.2.0

  Available via Homebrew: `brew upgrade kdx`
</Update>

<Update label="2026-02-06" tags={["CLI"]}>
  ### KDX CLI v2026.2.0

  Document Command Overhaul, Knowledge Management & Module Downloads:

  **Version Scheme Change:**
  The CLI version now aligns with the platform release cycle (2026.2.x), replacing the previous 0.x/8.x numbering.

  **Document Command Rewrite:**
  All `kdx document` commands have been rewritten to use the native kodexa-document Go library via a new DocumentAdapter, providing significantly improved performance and richer output including node IDs and type information.

  **New Document Subcommands:**

  * **`kdx document stats`** - Document statistics summary
  * **`kdx document schema`** - Display document schema
  * **`kdx document tags`** - List and inspect tags
  * **`kdx document features`** - List and inspect features
  * **`kdx document node`** - Inspect individual nodes
  * **`kdx document text`** - Extract text content
  * **`kdx document page`** - Page-level operations
  * **`kdx document find`** - Multi-criteria search across nodes
  * **`kdx document spatial find`** - Spatial search by coordinates
  * **`kdx document spatial bbox`** - Bounding box queries
  * **`kdx document data objects`** - List data objects
  * **`kdx document data attributes`** - List data attributes
  * **`kdx document data exceptions`** - List data exceptions
  * **`kdx document audit`** - View audit trail entries

  **Knowledge Management:**

  * **`kdx knowledge attach`** - Attach files to knowledge sets
  * **`kdx knowledge download`** - Download knowledge set items
  * **`attachmentPath` support** in `kdx sync` for knowledge items

  **Module Downloads:**

  * **`kdx get module <slug> --download`** - Download module implementation packages directly

  **Sync Improvements:**

  * **Project-scoped resources** with auto-pull for task templates
  * Graceful handling of missing files in pull operations

  ```bash theme={null}
  # Document inspection with enriched output
  kdx document stats invoice.kddb
  kdx document find invoice.kddb --type paragraph --content "total"
  kdx document spatial bbox invoice.kddb --page 1 --x1 0 --y1 0 --x2 500 --y2 200
  kdx document audit invoice.kddb

  # Knowledge management
  kdx knowledge attach my-org/knowledge-set:1.0.0 ./data.csv
  kdx knowledge download my-org/knowledge-set:1.0.0 item-id -o output.csv

  # Module download
  kdx get module my-org/my-model:1.0.0 --download
  ```

  **Breaking Changes:** None - fully backward compatible with v8.0.0

  Available via Homebrew: `brew upgrade kdx`
</Update>

<Update label="2026-01-28" tags={["CLI"]}>
  ### KDX CLI v0.6.0

  Content Object Access & Extended Store Commands:

  **New Features:**

  * **Document Family Content Commands**: New `kdx document-family content` subcommand for direct access to content objects (kddb files) within document families:
    * **`kdx document-family content list`** - List all content objects with IDs, timestamps, and labels
    * **`kdx document-family content download`** - Download kddb files directly, bypassing DFM export timeouts
    * **`--latest` flag** - Automatically select the most recent content object
    * **`--output` flag** - Specify custom output filename

  * **Store Upload & Watch Commands**: New commands for document upload and processing workflows:
    * **`kdx store upload`** - Upload files (PDF, images, documents) to document stores
    * **`kdx store watch`** - Monitor document processing progress with real-time status updates
    * **`--label` flag** - Wait for specific processing labels (PREPARED, FIRST-PASS, LABELED, PROCESSED)
    * **`--timeout` flag** - Configure wait timeout for long-running processing

  **Improvements:**

  * **Project Create Organization Lookup**: Fixed organization resolution when creating projects from templates
  * **Dynamic API Flags**: Improved handling of dynamic flags for `kdx run` operations
  * **Document Family Data Export**: Fixed data export to always use latest content object

  **Usage Examples:**

  ```bash theme={null}
  # List content objects in a document family
  kdx document-family content list 70b894f5-8d32-4584-b780-89f89210e078

  # Download the latest kddb file
  kdx document-family content download 70b894f5-8d32-4584-b780-89f89210e078 --latest -o document.kddb

  # Upload and monitor processing
  kdx store upload satori/project-processing:1.0.0 ./report.pdf
  kdx store watch abc123 --label PROCESSED --timeout 600
  ```

  **Documentation:**

  * [Document Family Commands](/guides/kdx-cli/document-family-commands)
  * [Store Commands](/guides/kdx-cli/store-commands)

  **Breaking Changes:** None - fully backward compatible with v0.5.x

  Available via Homebrew: `brew upgrade kdx`
</Update>

<Update label="2026-01-07" tags={["CLI", "SDK", "Documentation"]}>
  ### v8 Documentation Preview

  Pre-release documentation for upcoming v8 CLI and SDK releases:

  **CLI v8 - Document Commands (Preview):**

  New `kdx document` command suite for working with local KDDB files without requiring a platform connection:

  * **`kdx document info`** - Display document summary with metadata and statistics
  * **`kdx document print`** - Pretty print document structure as an ASCII tree with depth limiting and feature display
  * **`kdx document select`** - Query nodes by type using selector syntax
  * **`kdx document natives list/extract`** - List and extract embedded files (PDFs, images, etc.)
  * **`kdx document external list/get/set/delete`** - Manage key-value external data store
  * **`kdx document metadata get/set`** - View and modify document metadata

  ```bash theme={null}
  # Quick document inspection
  kdx document info invoice.kddb
  kdx document print invoice.kddb --depth 3
  kdx document select invoice.kddb "//paragraph"

  # Extract embedded PDF
  kdx document natives extract invoice.kddb original.pdf -o extracted.pdf
  ```

  **SDK Documentation Updates:**

  * **Native Documents**: Store and retrieve binary files within KDDB documents
  * **External Data**: Flexible key-value store for custom data and processing results
  * **Metadata**: Document properties including UUID, version, and custom fields
  * **Content Nodes**: Hierarchical document structure with types and content
  * **Selectors**: XPath-like query syntax for finding nodes

  **Documentation Links:**

  * [CLI Document Commands](/guides/kdx-cli/document/overview)
  * [SDK Native Documents](/sdk/native-documents)
  * [SDK External Data](/sdk/external-data)
  * [SDK Metadata](/sdk/metadata)

  <Note>
    These features are in preview and will be included in the upcoming v8 release of the KDX CLI and Kodexa Document SDKs.
  </Note>
</Update>

<Update label="2026-01-03" tags={["SDK", "Documentation"]}>
  ### Kodexa Document SDK v8.0.0

  New SDK Documentation & Version 8 Libraries:

  **New Documentation:**

  * **SDK Documentation Tab**: Added a dedicated SDK section to the developer portal with comprehensive guides for Python and TypeScript
  * **Python Getting Started**: Complete guide covering installation, document creation, node manipulation, selectors, features, tags, and saving
  * **TypeScript Getting Started**: Full guide including WASM initialization, async patterns, memory management, and browser/Node.js setup

  **Python SDK - kodexa-document v8.0.0:**

  * High-performance document processing via Go backend with CFFI bindings
  * \~100x faster in-memory mode for processing pipelines
  * Full support for KDDB format, hierarchical nodes, features, tags, and XPath-like selectors
  * Context manager support for automatic resource cleanup

  ```bash theme={null}
  pip install kodexa-document
  ```

  **TypeScript SDK - @kodexa-ai/document-wasm-ts v8.0.0:**

  * WebAssembly-powered SDK for Node.js and modern browsers
  * \~5x faster than pure JavaScript implementations
  * Full async API with TypeScript type safety
  * Works with both file-based and in-browser SQLite

  ```bash theme={null}
  npm install @kodexa-ai/document-wasm-ts
  ```

  **Key Features (Both SDKs):**

  * Create, load, and save KDDB documents
  * Hierarchical ContentNode tree structure
  * XPath-like selector queries
  * Features (key-value metadata) and Tags (annotations with confidence)
  * JSON and binary export formats

  **Links:**

  * [Python SDK Documentation](/sdk/python)
  * [TypeScript SDK Documentation](/sdk/typescript)
  * [PyPI - kodexa-document](https://pypi.org/project/kodexa-document)
  * [npm - @kodexa-ai/document-wasm-ts](https://www.npmjs.com/package/@kodexa-ai/document-wasm-ts)
</Update>

<Update label="2025-12-04" tags={["CLI"]}>
  ### KDX CLI v0.5.2

  Stability & User Experience Improvements:

  **Bug Fixes:**

  * **Increased Client Timeout**: Extended HTTP client timeout from 60 seconds to 10 minutes (600s) to prevent premature failures during long-running deployment operations, particularly beneficial for large manifest deployments, multiple resource/module deployments, and deployments to slow or distant environments
  * **Improved Branch Mapping Error Handling**: Changed behavior when no branch mapping is found - now displays informational message and exits gracefully instead of returning error, providing better UX when working on unmapped branches

  **Improvements:**

  * **Better CI/CD Integration**: Non-disruptive behavior when working on unmapped branches doesn't fail pipelines unnecessarily
  * **Clearer User Feedback**: Informational messages clearly distinguish between configuration issues and actual errors
  * **Enhanced Reliability**: Deployments that previously failed due to timeout will now complete successfully

  **Impact:**

  * Prevents deployment timeouts for operations with large manifests or multiple resources
  * Better user experience when working with selective branch mapping configurations
  * More reliable long-running deployment operations

  **Breaking Changes:** None - fully backward compatible with v0.5.0 and v0.5.1

  **Download Links:**

  * [macOS (Intel)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.5.2/kdx_0.5.2_darwin_x86_64.tar.gz)
  * [macOS (Apple Silicon)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.5.2/kdx_0.5.2_darwin_arm64.tar.gz)
  * [Linux (x86\_64)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.5.2/kdx_0.5.2_linux_x86_64.tar.gz)
  * [Linux (ARM64)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.5.2/kdx_0.5.2_linux_arm64.tar.gz)
  * [Windows (x86\_64)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.5.2/kdx_0.5.2_windows_x86_64.zip)

  Available in [kdx-cli v0.5.2](https://github.com/kodexa-ai/kdx-cli-releases/releases/tag/v0.5.2)
</Update>

<Update label="2025-12-03" tags={["GitHub Action"]}>
  ### Kodexa Sync Action v2.2.0

  Built-in Slack Notifications & GitHub Job Summary:

  **New Features:**

  * **Slack Notifications**: Send rich deployment summaries to Slack automatically with `slack-channel-id` and `slack-token` inputs
  * **GitHub Job Summary**: Add deployment summary to workflow run with `annotate-summary: true`
  * **Renamed Input**: `workers` → `threads` to match kdx-cli flag naming

  **Slack Message Includes:**

  * 🚀 Deployment status (or 🔍 for dry runs)
  * Repository and branch information
  * Resource counts (created, updated, unchanged)
  * Direct link to the GitHub Actions run

  **Usage Example:**

  ```yaml theme={null}
  - uses: kodexa-ai/kdx-sync-action@v2
    with:
      threads: 8
      annotate-summary: true
      slack-channel-id: $\{{ secrets.SLACK_CHANNEL_ID }}
      slack-token: $\{{ secrets.SLACK_BOT_TOKEN }}
    env:
      KODEXA_PROD_API_KEY: $\{{ secrets.KODEXA_PROD_API_KEY }}
  ```

  Available in [kdx-sync-action v2.2.0](https://github.com/kodexa-ai/kdx-sync-action/releases/tag/v2.2.0)
</Update>

<Update label="2025-12-03" tags={["CLI"]}>
  ### KDX CLI v0.5.0

  Tag-Based Deployments & Enhanced GitOps:

  **Major Features:**

  * **Tag-Based Deployment Mappings**: Deploy using git tags in addition to branches, enabling release-driven workflows with `tag_mappings` configuration supporting semantic versions, release candidates, and preview tags
  * **Manual Deployment Overrides**: New `--branch` and `--tag` flags provide explicit control over deployment routing without requiring git operations, perfect for CI/CD, testing, and rollback scenarios
  * **JSON Deployment Reports**: Generate structured JSON reports of deployment actions with `--json-report <path>` for CI/CD integration
  * **Parallel Resource Deployment**: New `--threads <n>` flag for configuring parallel threads during resource deployment - significantly faster for large deployments
  * **Resource Filtering**: Filter resources during deployment with `--filter <pattern>` for selective deployments

  **Improvements:**

  * **Enhanced Error Messages**: Clear, actionable error messages with hints when mappings are not found
  * **Better User Feedback**: Deployment mode indicators showing whether using branch detection, tag detection, or manual override
  * **Improved Mapping Resolution**: Support for multiple overlapping mappings, enabling sophisticated multi-environment deployment strategies

  **Usage Examples:**

  ```bash theme={null}
  # Deploy with JSON report
  kdx sync deploy --json-report ./deploy-report.json

  # Deploy with parallel threads (8)
  kdx sync deploy --threads 8

  # Deploy specific tag mapping
  kdx sync deploy --tag v1.0.0

  # Filter resources during deployment
  kdx sync deploy --filter "invoice-*"
  ```

  **Configuration - Tag Mappings:**

  ```yaml theme={null}
  branch_mappings:
    - pattern: "main"
      target: production
      environment: prod

  tag_mappings:
    - pattern: "v*"
      target: production
      environment: prod
    - pattern: "rc-*"
      target: staging
      environment: staging
  ```

  **Download Links:**

  * [macOS (Intel)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.5.0/kdx_0.5.0_darwin_x86_64.tar.gz)
  * [macOS (Apple Silicon)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.5.0/kdx_0.5.0_darwin_arm64.tar.gz)
  * [Linux (x86\_64)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.5.0/kdx_0.5.0_linux_x86_64.tar.gz)
  * [Linux (ARM64)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.5.0/kdx_0.5.0_linux_arm64.tar.gz)
  * [Windows (x86\_64)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.5.0/kdx_0.5.0_windows_x86_64.zip)

  Available in [kdx-cli v0.5.0](https://github.com/kodexa-ai/kdx-cli-releases/releases/tag/v0.5.0)
</Update>

<Update label="2025-12-02" tags={["CLI"]}>
  ### KDX CLI v0.4.1

  Enhanced Debugging, Error Handling & Sync Improvements:

  **New Features:**

  * **Enhanced Client Debugging**: Added detailed API request/response logging when debug mode is enabled, providing comprehensive information for troubleshooting
  * **Improved Module Syncing**: Updated module syncing to build and display full slugs with organization prefixes, improving clarity in logs and progress reporting
  * **Enhanced Deployment Output**: Deployment command now includes the environment URL in planned deployment messages, providing clearer context for users
  * **Alternate Extension Support**: Added support for both `.yaml` and `.yml` extensions when reading resource files, with improved error hints showing all attempted file paths

  **Improvements:**

  * **Better Error Messages**: Error messages now reference full slugs with organization prefixes, making it easier to identify and debug issues
  * **Improved Error Handling**: Enhanced deployment error handling to capture and report errors without terminating the process immediately
  * **Robust Payload Handling**: New utility function to safely extract string values from interface types
  * **Debug Mode Formatting**: Conditionally display full response bodies based on debug mode for cleaner output in normal operation

  **Code Quality:**

  * Fixed gofmt formatting in `resource_types_test.go`

  **Download Links:**

  * [macOS (Intel)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.4.1/kdx_0.4.1_darwin_x86_64.tar.gz)
  * [macOS (Apple Silicon)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.4.1/kdx_0.4.1_darwin_arm64.tar.gz)
  * [Linux (x86\_64)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.4.1/kdx_0.4.1_linux_x86_64.tar.gz)
  * [Linux (ARM64)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.4.1/kdx_0.4.1_linux_arm64.tar.gz)
  * [Windows (x86\_64)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.4.1/kdx_0.4.1_windows_x86_64.zip)

  Available in [kdx-cli v0.4.1](https://github.com/kodexa-ai/kdx-cli-releases/releases/tag/v0.4.1)
</Update>

<Update label="2025-11-27" tags={["CLI"]}>
  ### KDX CLI v0.3.0

  Knowledge Sets & Immutable Resources:

  **New Features:**

  * **Knowledge Set Support**: New `knowledgeset` resource type with full CRUD operations, including example configurations for financial knowledge sets and full support in metadata API and sync operations
  * **Immutable Resource Types**: Added support for immutable resources (`featuretype` and `featureinstance`) that cannot be modified once created, maintaining database integrity. Sync operations automatically skip updates for immutable resources with appropriate warnings

  **Download Links:**

  * [macOS (Intel)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.3.0/kdx_0.3.0_darwin_x86_64.tar.gz)
  * [macOS (Apple Silicon)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.3.0/kdx_0.3.0_darwin_arm64.tar.gz)
  * [Linux (x86\_64)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.3.0/kdx_0.3.0_linux_x86_64.tar.gz)
  * [Linux (ARM64)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.3.0/kdx_0.3.0_linux_arm64.tar.gz)
  * [Windows (x86\_64)](https://github.com/kodexa-ai/kdx-cli-releases/releases/download/v0.3.0/kdx_0.3.0_windows_x86_64.zip)

  Available in [kdx-cli v0.3.0](https://github.com/kodexa-ai/kdx-cli-releases/releases/tag/v0.3.0)
</Update>