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

# Keeping the Toolchain Current

> Updating the CLI and SDK packages to coherent versions with safety guarantees.

The Ekanos toolchain is five packages: `@ekanos/cli`, `@ekanos/sdk`, `@ekanos/ui`, `@ekanos/integration-schema`, and `@ekanos/harness`. Three independent defenses keep it in sync:

## 1. Schema-version skew gate

`validate` and `publish` bundle an exact `@ekanos/integration-schema` version. If the project resolves a **newer** one (checked against both a direct install and what `@ekanos/sdk` declares), both verbs fail fast with `precondition_failed` (exit 9) — before loading the definition at all.

### Why this matters

```
$ ekanos validate
Error: The project's @ekanos/integration-schema@0.4.1 is newer than 0.4.0, the version this @ekanos/cli build validates with. Findings from "ekanos validate" are UNRELIABLE in this state: a field the newer schema added parses here as an unrecognized key, and the usual hint for that tells you to delete code that is actually correct.
Hint: Upgrade the CLI: run "ekanos upgrade" (it resolves a coherent target version set), or pin it explicitly by hand with "npm i -D @ekanos/cli@latest". Then re-run "ekanos validate" or "ekanos publish".
```

In that state, a field the newer schema added would parse as an `unrecognized_keys` issue, and the usual hint would tell you to delete correct code. So the CLI fails loudly instead.

### Older project schema (warning only)

If the project's schema is **older**, the verb continues and warns on stderr:

```
ekanos: the installed @ekanos/integration-schema@0.3.0 is older than 0.4.0, the version this CLI validates with — some fields this CLI recognizes may not be usable yet. Run "ekanos upgrade" to bring the toolchain in sync.
```

Validation is still correct; you just can't use fields the older schema doesn't know about. The JSON envelope carries `data.schemaSkew` in this case.

## 2. `ekanos upgrade`

The primary way to keep the toolchain coherent.

```bash theme={null}
# Check current vs. target (read-only)
ekanos upgrade --check

# Upgrade with verification
ekanos upgrade

# Skip the post-install validate + test
ekanos upgrade --no-verify
```

### Coherence guarantee

`upgrade` resolves a **coherent** target version set — from `GET /api/partner/toolchain` on your logged-in host when available, else the npm registry. `@ekanos/sdk`, `@ekanos/ui`, and `@ekanos/integration-schema` must share one version, and the SDK release at that version must pin exactly that schema.

An incoherent set (for example, mid-way through a multi-package publish) is refused with `precondition_failed` (exit 9) rather than turned into an uninstallable tree:

```
Error: The resolved toolchain versions do not form an installable set: …
Hint: Retry in a moment — this is almost always a multi-package publish still in flight, and it self-resolves once every package finishes publishing.
```

### Install and verify

1. **Snapshot** — `package.json` and the lockfile are saved
2. **Install** — Target versions of the toolchain packages that are **direct** dependencies are installed; transitive ones follow from whatever pins them and are listed in `data.skippedTransitive`
3. **Verify** — `ekanos validate` and your test script run
4. **Rollback** — On any failure, `package.json` and the lockfile are restored and a reinstall restores `node_modules`

In a terminal, `upgrade` prints the plan and asks `Upgrade now? [y/N]`. Outside a real TTY it requires `--yes`; without it, it fails with `validation` (exit 3) and changes nothing. If the project is already at the target, it reports so and exits 0.

A failed step is reported with an `error.code` naming it and the step's output in `data.output`:

| `error.code` | Exit code |
| - | - |
| `upgrade_install_failed` | `9` |
| `upgrade_validate_failed` | `3` |
| `upgrade_test_failed` | Your test script's |

The hint confirms the project has been restored to its pre-upgrade state.

### Agent-context file regeneration

After a successful upgrade, `ekanos upgrade` regenerates:

* `AGENTS.md`
* `CLAUDE.md`
* `.claude/skills/ekanos/SKILL.md`

Each is byte-compared against what the pre-upgrade CLI's templates would have rendered. Files you haven't modified are refreshed; ones you've edited are left alone and reported as needing manual attention. `docs/api-notes.md` and `.mcp.json` are created if missing, never overwritten.

A stale `AGENTS.md` teaches an agent yesterday's contract, which is as harmful as a stale binary.

### Flags

<ParamField body="check" type="boolean">
  Read-only. Report current vs. target versions and exit 0. Changes nothing.
  Safe for CI and scripts.
</ParamField>

<ParamField body="yes" type="boolean">
  Skip the interactive confirm. Required outside a real TTY (scripts, cron,
  containers).
</ParamField>

<ParamField body="no-verify" type="boolean">
  Skip the post-install verification step. Not recommended.
</ParamField>

<ParamField body="host" type="string">
  Ekanos host to fetch the target version set from. Falls back to host
  resolution (see [Authentication](/cli/authentication#host-resolution)). With
  no stored session for the host, the npm registry is used.
</ParamField>

<ParamField body="dir" type="string">
  Project directory (contains `ekanos.json`). Defaults to the current working
  directory.
</ParamField>

## 3. Proactive update notice

`validate`, `dev`, `publish`, and `status` check in the background whether a newer `@ekanos/cli` exists.

### How it works

* **Cached** — 24-hour cache
* **Bounded** — 1.5 second ceiling on network time
* **Non-fatal** — never changes the command's exit code
* **Silent when current** — no notice if you're up to date

Human mode prints one line to stderr:

```
ekanos: a newer @ekanos/cli is available (0.3.2 → 0.3.3). Run "ekanos upgrade".
```

JSON mode carries the notice in `data.toolchain`:

```json theme={null}
{
  "ok": true,
  "data": {
    "toolchain": {
      "status": "behind",
      "current": { "cli": "0.3.2" },
      "target": {
        "cli": "0.3.3",
        "sdk": "…",
        "ui": "…",
        "integrationSchema": "…",
        "harness": "…"
      },
      "upgradeCommand": "ekanos upgrade"
    }
  }
}
```

The same object appears on a stderr `claude-code-hint` line so agents can parse it without reading prose.

### Unsupported version

If you're below the host's declared minimum CLI version, the notice's `status` is `unsupported` and human mode prints:

```
ekanos: @ekanos/cli 0.2.0 is below the version this host requires (0.3.2). Run "ekanos upgrade".
```

`publish` then fails fast with `precondition_failed` (exit 9), because the host would refuse the submission anyway:

```
Error: @ekanos/cli 0.2.0 is below https://your-ekanos-host's minimum supported version (needs at least 0.3.2).
Hint: Run "ekanos upgrade" before publishing — the host will refuse this submission from an unsupported CLI regardless.
```

### Disable update checks

```bash theme={null}
export EKANOS_NO_UPDATE_CHECK=1
ekanos validate  # No update check
```

***

## Workflow examples

### Before you publish

```bash theme={null}
ekanos upgrade --check    # See if anything needs updating
ekanos upgrade            # Install, verify, roll back on failure
ekanos publish
```

### Team with a shared lockfile

Commit `package.json` and the lockfile so everyone runs the same toolchain. One person upgrades for the team:

```bash theme={null}
ekanos upgrade
git add package.json pnpm-lock.yaml
git commit -m "chore: bump ekanos toolchain"

# Everyone else
git pull
pnpm install
ekanos validate
```

### CI/CD pipeline

```yaml theme={null}
- name: Validate and test
  run: |
    pnpm install
    npx ekanos validate
    npx ekanos test

- name: Publish (on main)
  if: github.ref == 'refs/heads/main'
  run: |
    npx ekanos publish --source my-source
    npx ekanos status --watch
```

CI installs the locked versions; the team decides when to upgrade.

### Agent-driven updates

```bash theme={null}
ekanos upgrade --check --json   # Read data.deltas to see what would change
ekanos upgrade --yes            # Installs, verifies, rolls back on any failure
```

A non-zero exit from `ekanos upgrade --yes` means the project was restored; read `error.code` and `data.output` for the failing step.

***

## Troubleshooting

### CLI too old for the installed harness

```
Error: @ekanos/cli 0.1.0 is too old for @ekanos/harness 0.2.0: that harness needs shell contract 2, and this CLI generates 1.
```

`dev` refuses (exit 9) before writing anything. The hint gives the install command to upgrade the CLI. The reverse case, `@ekanos/harness <version> is too old for @ekanos/cli <version>`, gives the command to upgrade the harness.

**Fix:** Run `ekanos upgrade`, or follow the hint.

### Project schema newer than the CLI

See the schema-version skew gate section at the top of this page.

**Fix:** Run `ekanos upgrade --check` to see the target, then `ekanos upgrade`.

### Upgrade rolled back

The install, validate, or test step failed and the project was restored. `error.code` names the step and `data.output` holds its output.

**Fix:** Fix the underlying issue (often a test failure against the new versions) and re-run `ekanos upgrade`.

### No target available

```
Error: Could not resolve a toolchain target from the Ekanos host or the npm registry.
```

Exit 8. Neither the host nor the npm registry answered.

**Fix:** Check connectivity and retry.

### Edited agent-context files

`upgrade` leaves an `AGENTS.md`, `CLAUDE.md`, or skill file you've edited untouched and reports it as needing manual attention.

**Fix:** Compare it against the new template and merge by hand.


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