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

# SDK upgrade notes

> Compatibility boundaries when adopting the split-package release.

These notes cover `1.4.0` relative to `1.3.0`. The stable release uses the npm
`latest` dist-tag. Use an exact version when testing an upgrade.

## Claude provider correction

The Claude Agent SDK provider now isolates generation and extraction from
personal/project filesystem settings and `CLAUDE.md` instructions. Existing
Claude login remains available. Use llmwiki environment variables for provider
configuration and `compile --instructions <path>` for explicit writing guidance.
Prompt provenance advances to `v6`. Upgrading alone does not recompile unchanged
sources: existing pages retain their recorded prompt version. A subsequent source
edit or explicit compile-instruction change can trigger regeneration; newly
generated concept pages then record `v6`. Use `compile --review` to inspect those
updates before approval.

## What stays the same

Continue importing `createWiki` from `llm-wiki-compiler` for the standard SDK.
The standard CLI, workflow facade, builtin profile templates and legacy viewer
experiment input remain available. Scoped supporting packages are implementation
dependencies, not separately supported consumer entry points. Node 24 remains
the minimum, not a new requirement.

The extraction does not require migrating local workflows to an external
coordinator; the local engine retains run state between local invocations. See
[SDK packages and ownership](/guides/sdk-packages) before changing dependencies.

## Experimental source changes

Artifact and local workflow APIs were already marked experimental, with shapes
permitted to change in minor releases. This release includes changes that can
require updates even though existing single-body calls and workflow entry points
remain available:

* `SdkWriteArtifactInput` is now a body-or-members union. An interface cannot
  extend that union. For existing body-specific extensions, narrow the input:

  ```ts theme={null}
  import type { SdkWriteArtifactInput } from "llm-wiki-compiler";

  type BodyArtifactInput = Extract<SdkWriteArtifactInput, { body: string }>;
  type AnnotatedBodyInput = BodyArtifactInput & { localLabel: string };
  ```

* Workflow statuses and events include new cases, including terminal refusal.
  Update exhaustive switches deliberately. Do not treat refusal as cancellation,
  success or a resumable state.

* Workflow starts capture their durable JSON inputs synchronously. Returned and
  reopened inputs agree: dates become strings, hidden fields are omitted and
  sparse arrays/function fields follow JSON normalization. JSON hooks remain
  supported. Typed action inputs still validate their declared schema; this is
  not permission to coerce invalid action fields.

* The `Wiki` interface has additional required members. Hand-written full
  implementations or test doubles may need to implement them. For a consumer
  that needs only a few methods, type its dependency and its test double as
  `Pick<Wiki, "status" | "getPage">` (using the methods it actually consumes),
  rather than casting an incomplete object to the full interface.

Do not describe this release as fully source-compatible with every experimental
consumer. Stable public contract changes require a separate compatibility decision.

## Safety and failure behavior

Pending mutation journals are recovered before further writes. Archive overwrite,
selected filename/record-ID mismatch and detected confined-path drift are refused.
Legacy relation compaction refuses operation-bound history rather than discarding
recovery provenance. These refusals may expose unsafe assumptions in callers;
they are not reasons to bypass compiler checks.

A write error after rename does not establish that no write happened. Observe and
reconcile uncertain outcomes before retrying. Retained artifacts are verified
against current bytes, not merely their recorded digests.

Composition with a duplicate core module instance is rejected before I/O, including
at standard package import or CLI load, not only when starting a workflow.
If startup fails after changing
dependencies, check that the standard package and local engine resolve the same
exact core installation; do not suppress the identity check.

## Adoption checklist

1. Retain the standard package unless you deliberately want an engine-free SDK.
2. Install matching release packages; avoid mixing versions or duplicate core copies.
3. Type-check your application's artifact extensions and exhaustive workflow switches.
4. Reopen an existing project and exercise your actual CLI or SDK integration.
5. Keep operator approval separate from embedder preparation authority.

The optional package architecture alone does not justify a major version bump.
Any newly discovered incompatibility in a stable contract must be resolved or
explicitly approved and announced before release.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.