v1.6.0

Atlas Capsule — a portable, token-budgeted AI handoff package. Kairo
already provides continuity artifacts (repo memory, checkpoints, briefs,
Atlas, graphs, telemetry), yet a fresh agent session still tends to re-scan
large parts of the repository to re-orient — wasting context before any new
work starts. Atlas Capsule is the missing bootstrap: a compact, trusted
continuation package generated from existing Kairo state that tells the next
agent what is known, what changed, what to read first, and what is safe
to skip initially. It is a projection only (ADR-0020): no new state store,
no schema changes, no mutation of .kairo/. Capsule reduces unnecessary
rescanning; it does not stop all rescanning or guarantee no rereads — it is
a trusted starting point, not a replacement for validation. Design:
ADR-0020.

Added

• Capsule engine (src/core/capsule/) — deterministic, replay-safe
  projection + renderer. Builds a neutral CapsuleProjection from the latest
  checkpoint, Atlas graph, repo intelligence, changed files, git
  branch/version, and optional memory recall, then renders target-framed,
  budget-bounded markdown.
• Three modes with character budgets (a tokeniser-agnostic proxy):
  tiny (~1,500), standard (~4,000, default), deep (~20,000). Capsules
  are bounded; exceeding the budget appends a visible truncation marker.
• Four targets: claude, codex, cursor, generic — framing only,
  never the underlying facts.
• kairo capsule CLI command — --mode, --target, --output/-o,
  --max-chars, --agents-md, --force, --json. Default
  standard/generic; deep is only printed when explicitly requested.
• kairo_capsule_create MCP tool (experimental) — inputs mode / target /
  maxChars / includeAgentsMd / force; output is a compact summary plus
  structured JSON (chars, truncation status, files to read first, safe-to-skip
  list). Token-efficient by default.
• AGENTS.md export (Codex) — kairo capsule --target codex --agents-md
  writes an AGENTS.md with a generated header, continuation instructions,
  read-first plan, safe-to-skip list, and do-not-touch warnings. Refuses to
  overwrite an existing file without --force.
• Capsules tab in the Inspect dashboard (/capsules) — read-only
  generated preview with mode/target selectors, char count, truncation
  status, files to read first, and safe-to-skip list. This view never writes
  a file; create/export is via the CLI or MCP tool.
• Docs: docs/CAPSULE.md (full guide) and
  docs/CAPSULE_DOGFOOD.md (measured sizes on Kairo
  itself + honest limits).

Security

• Capsules pass through Kairo's redaction boundary plus a final redaction pass
  in the renderer (secrets removed), and emit only repo-relative paths — no
  absolute local paths — so a capsule is safe to paste into another AI agent.

v1.5.0

Kairo Atlas — a local, read-only interactive architecture map. Kairo
already extracts precise structural signals (the collapsed module graph,
salience, risk, checkpoint/session activity) but only stores them as
.kairo/*.jsonl, Mermaid text, and markdown — formats a human cannot
scan to answer "what are the important modules, how is this connected,
what's risky, what did the AI change?". Atlas projects those existing
signals into a navigable picture so a person can see the architecture
instead of reading raw artifacts. It is a projection (ADR-0011): no new
analysis engine, no new MCP tools, no schema changes — a view in the
existing inspect surface at kairo inspect → /atlas. Design and
trade-offs: ADR-0019.

Added

• 2D architecture map (default view) — deterministic, self-authored
  canvas renderer over the cached module graph. Pan/zoom/click; nodes
  sized by salience (degree centrality), coloured by group, risk rings,
  changed-by-AI ticks. Seeded force layout (no third-party graph library).
• 3D architecture map — a hand-written perspective projection of the
  same payload (rotate / zoom / pan via Shift+drag / reset camera /
  depth-aware selection). No three.js, no WebGL library, no CDN.
• Search — / focuses the box; case-insensitive path/module matching
  with matched-node halos, neighbour highlighting, and a results list.
• Filters — hide docs/tests/examples/generated; focus source-only,
  high-salience, high-risk, changed, checkpoint-related, session-related.
  Filtering is layout-stable (no relayout) across 2D, 3D, and hit-testing.
• Node detail panel — salience, centrality, fan-in/out, group/risk and
  changed/checkpoint/session badges, plus clickable incoming/outgoing
  dependency lists to walk the graph. Built entirely client-side from the
  delivered payload (no new endpoint, no added fields, safe DOM APIs only).
• Deterministic graph payload at GET /atlas/graph.json?kind=&top=:
  schema-versioned, nodes sorted (−salience, id), edges (from, to),
  repo-relative ids only, top-N salience cap (default 50) with an explicit
  honest truncation block. No wall-clock time, no randomness, no absolute
  paths.
• Scoped CSP — only /atlas* responses carry
  default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; base-uri 'none'; form-action 'none'
  (no unsafe-inline, no unsafe-eval, no remote origins). The rest of the
  inspect surface keeps its stricter JS-free default-src 'none' policy.
• Documentation — docs/ATLAS.md usage guide and a
  README "Kairo Atlas" section. Screenshots are intentionally not
  committed (local-first; no binary assets, no remote/CDN images).
• Tests — Atlas projection, routes/CSP, 2D, 3D, search/filters, and
  detail-panel suites asserting payload shape, CSP equality, and the
  absence of eval/remote origins/innerHTML in the renderer.

Dogfooded on the Kairo repository itself during development.

Local-first, read-only, no remote assets. Atlas is served from the
loopback inspector, never writes .kairo/, and makes only a same-origin
fetch('/atlas/graph.json').

Honest limitations. The graph is built from statically-extracted
internal relative imports (JS/TS + Python — ADR-0005); dynamic imports and
external packages are excluded by design. Nodes are directory-collapsed for
readability, and large graphs are truncated to the top-N most salient nodes
(the truncation banner says so). Atlas visualizes Kairo's deterministic
signals; it does not claim to understand every codebase.

v1.4.2

Cross-language doctor/init correctness. Three honest defects in
v1.4.0 surfaced by continuing Python-repo dogfood. All three were
"the system works, but it lies about its state" — exactly the kind of
small inaccuracy that erodes trust. v1.4.2 closes them. Reliability
fix only — no MCP contract changes, no schema changes, no new tools,
no new behaviour at runtime.

Fixed

• Bug A: kairo init reported the chosen form even when it skipped.
  When .mcp.json already declared kairo, init said mcp form: global (kairo-mcp on PATH) while the file on disk still had the
  stale node ./node_modules/... local form. The kv row now reads
  the actual on-disk form via classifyInstalledSpec, matching
  what kairo doctor reports.

• Bug B: kairo doctor insisted on package.json at the project
  root. Python / Rust / Go / Java / Ruby repos legitimately don't
  have one. Doctor now accepts any of these markers:
  package.json, .git, pyproject.toml, requirements.txt,
  setup.py, go.mod, Cargo.toml, pom.xml, build.gradle,
  build.gradle.kts. The detail line names which marker matched so
  the user knows what was found. Truly empty directories still fail
  with an honest error listing what was expected.

• Bug C: kairo doctor ran the version-match check against
  node_modules/kairo-mcp/package.json even when no local install
  existed. Global and npx installs don't have a local
  package.json to compare to — and the absence of one was being
  reported as a failure (kairo-mcp not installed in this project)
  despite the kairo-mcp installed check having just confirmed the
  global PATH install was fine. Doctor now routes per install form:

  • local: compares node_modules/kairo-mcp/package.json ↔
    SERVER_VERSION (unchanged from v1.4.0).
  • global: reports OK + a hint to upgrade via npm install -g kairo-mcp@latest (the user's package manager owns the version,
    not doctor).
  • npx: reports OK + a hint that the version is resolved at
    launch by npx (not a local concern).
  • Inside the kairo-mcp dev repo: compares dist/index.js ↔ the
    repo's own package.json (unchanged).

Added

• 8 new regression tests in tests/doctorNonNode.test.ts
  (213/213 total, up from 205):
  • 5 project-marker tests: Python pyproject.toml, Python
    requirements.txt, Rust Cargo.toml, Go go.mod, .git-only
    git checkout. All recognised as valid project roots.
  • 1 negative test: truly empty directory fails project root with
    an honest error.
  • 1 version-match test: Python project with no node_modules does
    NOT fail version match.
  • 1 init-stale-mcp.json regression: Python repo with the v1.0.x-
    era broken local-form .mcp.json, after kairo init --force,
    must contain one of the v1.4.0 valid forms (never the broken
    node ./node_modules/...).

Notes

• 213/213 tests pass.
• Caught and fixed in real-time by a Python repo dogfood
  (ImageCompareSoftware) — the same project that found Bug A in
  v1.4.0. v1.4.2 ships the whole truthful version of what v1.4.0
  intended to be.
• The user-visible improvement is that running kairo init then
  kairo doctor in a Python / Rust / Go repo now reports
  all checks passed instead of 3 check(s) need attention when
  everything is in fact fine.

v1.4.1

Maintainer GitHub username changed from sandy001-kki to
sandeepbollavaram; swept stale repository links and ownership
metadata.

Fixed

• .github/CODEOWNERS — @sandy001-kki no longer resolves after
  the rename (GitHub mention resolution doesn't follow username
  redirects). Updated to @sandeepbollavaram so review requests route
  correctly.
• package.json — homepage, repository.url, bugs.url all
  swept. npm package page and IDE "view source" links resolve directly
  instead of through GitHub's redirect.

Changed

• README.md — CI badge URL, latest-release badge URL, and the
  bug-report link in the Troubleshooting section all point at the new
  username.
• CHANGELOG.md — every compare link (all prior version diffs) now
  points at the new namespace. Existing tags resolve identically; the
  URLs just no longer rely on GitHub's redirect.
• PUBLISHING.md — install commands and the scoped-name fallback
  example updated.
• .github/ISSUE_TEMPLATE/config.yml — the Discussions deflection
  link points at the new namespace.
• docs/adr/0017-ci-and-repo-policy.md — CODEOWNERS reference in
  the ADR text updated to match the file.

Not changed

• No MCP contract changes. No schema changes. No new tools. No
  behavioural changes. Pure docs / metadata.
• No published kairo-mcp tarball semantics change — the
  consumer-facing dist/ is identical to v1.4.0. A republish to npm
  is optional (the README badges and install commands work either
  way; the metadata fields in package.json affect only the next
  npm view output).
• The old sandy001-kki GitHub URLs keep working via GitHub's
  redirect as long as nobody claims the old username. This sweep is
  insurance against that day, not an emergency.

Notes

• 205/205 tests pass.
• Git history retains the old maintainer email — past commits are
  byte-identical, only the live URL metadata moved.

v1.4.0

Cross-language MCP bootstrap reliability. First non-Node-project
dogfood (a Python repo on Windows + Claude Code) caught a real bug:
kairo init always wrote .mcp.json referencing ./node_modules/ kairo-mcp/dist/index.js, which doesn't exist in Python / Rust / Go /
Java / Ruby / empty-directory projects — i.e. most projects an AI
coding agent works in. Claude Code spawned the MCP server, Node
returned MODULE_NOT_FOUND, the connection died with no useful
remediation hint.

v1.4.0 is purely a reliability fix. No new MCP tools, no new
schemas, no new persisted artefacts, no stability registry changes,
no new behaviour at runtime. The only change is the install-time
logic that picks the right .mcp.json shape. See
ADR-0018.

Fixed

• kairo init now detects the install environment and writes one
  of three valid .mcp.json forms, tried in order:

  1. local — command: "node", args: ["./node_modules/kairo-mcp/ dist/index.js"] when the local install exists (Node project
     that ran npm install kairo-mcp locally; old behaviour preserved).
  2. global — command: "kairo-mcp" when kairo-mcp resolves
     via PATH (i.e. npm install -g kairo-mcp is on the developer's
     machine — recommended).
  3. npx — command: "npx", args: ["-y", "kairo-mcp"] as a
     fallback. Works in any directory, any OS, regardless of prior
     install. npx fetches on first run; subsequent invocations use
     its cache.
     Detection is cross-platform: where on Windows, which on POSIX.

• kairo doctor recognises all three forms on the .mcp.json wires kairo check, and reports which form is in use (e.g.
  (global form)). The kairo-mcp installed check now passes when
  any of the three install paths is reachable, with a remediation
  hint specific to which one is missing.

Added

• src/cli/initSpec.ts — pure-data spec generator + detection
  helper. Two exported functions: detect(projectRoot) returns a
  DetectionResult (two booleans), chooseMcpSpec(detection) is a
  pure function from detection to MCP server spec.
  classifyInstalledSpec(entry) recognises any of the three v1.4.0
  forms in an existing .mcp.json (used by doctor).

• 12 new tests in tests/initSpec.test.ts: 5 pure-function tests
  on chooseMcpSpec, 3 integration tests on detect() against real
  temp directories (Node, Python, empty), 4 classification tests on
  classifyInstalledSpec for the doctor recognition path.

• kairo init output gains an mcp form row in the kv block —
  visible signal of which path was chosen. JSON output adds an
  mcpInstallForm field; existing fields keep their semantics
  (back-compat).

• README "Quick start" table documents the three forms and when
  each fires.

• README "Troubleshooting" section — four common installation
  symptoms with one-line fixes for each: /mcp failed,
  kairo: command not found, mcp host: not detected,
  MODULE_NOT_FOUND on pre-v1.4.0 builds.

Changed

• kairo init's end-to-end CLI test was relaxed to accept any of
  the three valid commands (node, kairo-mcp, npx). It was
  previously locked to node, which is now only one valid outcome.
  The 12 new initSpec tests cover the full matrix deterministically.

Notes

• 205/205 tests pass (up from 193 in v1.3.1: +12 new initSpec
  tests).
• No tarball semantics change. The published kairo-mcp@x package
  is unchanged at the file level; v1.4.0 only changes install-time
  logic.
• Found by the first non-Node-project dogfood (an
  image_editor_python repo on Windows + Claude Code). The fix loop
  — symptom → diagnosis → ADR → tests → release — closed within the
  same evening. This is the maintenance pattern v1.x is designed for.

v1.3.1

Docs-only patch. v1.3.0 published kairo-mcp to npm; v1.3.1 reflects
that in the README badge row so visitors see the published version
and download count at a glance.

Added

• README badge row gains two real, dynamic shields:
  • [![npm](.../npm/v/kairo-mcp)](npmjs.com/package/kairo-mcp) —
    latest published version, pulled live from the npm registry.
  • [![npm downloads](.../npm/dm/kairo-mcp)] — monthly download
    count.
    Both are dynamic; both will tick upward (or sideways) on their own
    as downstream users npm install the package.

Notes

• No code changes. No schema changes. No MCP contract changes. No
  CLI behaviour changes. No stability registry changes. Pure docs.
• Tag v1.3.1 is shipped to GitHub for completeness, but a re-
  publish to npm is NOT required — npm's badge endpoint serves the
  latest version regardless of repo tags, and the published tarball
  for kairo-mcp@1.3.0 is unchanged.
• A separate npm publish for 1.3.1 is optional. If desired, run
  npm publish per PUBLISHING.md — but the README badges work
  whether or not you do.

v1.3.0

npm distribution. Kairo becomes installable like a real developer
tool. No new architecture subsystems, no schema changes, no new MCP
tools — packaging, distribution, install smoke, docs.

Added

• PUBLISHING.md — single-file maintainer runbook covering npm
  account / 2FA prerequisites, the pre-publish gate (mirrors the
  install-smoke CI job), the actual npm publish flow, and the
  72-hour npm deprecate / npm unpublish discipline. Every
  npm publish is a human decision; this file is the reference.

• publishConfig.access: "public" in package.json — defensive
  (the package name is unscoped, so this is already npm's default,
  but explicit-over-implicit is cheaper to get right once).

• Expanded npm keywords (15 entries, up from 7) for npm search
  discoverability: adds claude, cursor, ai-coding, agent-memory,
  local-first, deterministic, cli, typescript. No behaviour
  change — npm metadata only.

• Install-smoke now exercises kairo init end-to-end. The CI
  job (1) installs the packed tarball into a fresh project, (2)
  runs kairo init --json and asserts mcpJson === 'written',
  (3) verifies .mcp.json exists and wires kairo, (4) re-runs
  kairo init --json and asserts the second run reports mcpJson === 'skipped' (idempotency contract). Catches every packaging
  regression that affects the documented Quick start path.

Changed

• README Quick start now leads with npm install -g kairo-mcp.
  The git-install path is preserved as a "dev tip" fallback for users
  who want main-branch builds. The npx -p kairo-mcp kairo init
  no-install path is documented honestly — including why -p kairo-mcp is needed (npm packages with multiple bins resolve
  npx <pkg> to the bin matching the package name, which here is the
  MCP server, not the CLI).

Not done in this release (deliberate)

• No actual npm publish from this commit. v1.3.0 is ready
  to publish, but the publish itself is a human action run from a
  clean local checkout with 2FA. See PUBLISHING.md.
• No MCP tool, schema, persisted artefact, or stability registry
  changes. The CLI surface remains experimental per ADR-0016.

Notes

• 193/193 tests pass.
• npm pack --dry-run confirms a clean 266 kB / 384-file tarball:
  no .kairo/, no tests, no fixtures, no .git, no .github. Only
  dist/, README.md, LICENSE, CHANGELOG.md ship.
• The three bins (kairo, kairo-mcp, kairo-inspect) all land on
  PATH after npm install -g kairo-mcp. After publish, the
  documented Quick start becomes npm install -g kairo-mcp; cd your-project; kairo init — three commands, ≤60 seconds.

v1.2.0

DevEx polish — CLI UX + README clarity. No new architecture
subsystems. No schema changes. No new MCP tools. Pure surface polish
across the developer-facing edges that were rough on first contact.

Changed

• Top-level kairo --help gains a 3-line Quick start callout
  above the command list so first-time users see action items
  (cd → init → doctor → status) instead of a flat command catalogue.
  The footer hint now points to kairo doctor when something looks
  off, not just kairo help <command>.

• kairo init now detects the MCP host on PATH (currently
  recognises Claude Code; structured to grow) and prints a concrete
  3-step Next steps block tailored to what was found:

  Initialised
    .mcp.json:   written
    .gitignore:  appended
    mcp host:    claude
  
  Next steps
    1. Open Claude Code in this project: claude
    2. Inside the session, run: /mcp
       → you should see  kairo · connected · 41 tools
    3. If anything looks off, run: kairo doctor
  

  The --json output gains a detectedHost field. Existing
  mcpJson / gitignore / projectRoot fields are unchanged.

• kairo doctor now correctly handles the case where it's run
  from inside the kairo-mcp dev repo itself (where dist/index.js
  lives at the repo root, not under node_modules/kairo-mcp/). The
  kairo-mcp installed and version match checks fall back to the
  self-install path when node_modules/kairo-mcp/ is absent but the
  current package.json says name: "kairo-mcp".

• README.md Quick start and Real workflow sections updated to
  the v1.2.0 output: realistic kairo init block with detected host

  • next-steps; install line no longer pins to a stale v1.1.0 tag.

Notes

• 193/193 tests still pass. CI matrix (6 cells + install-smoke) all
  green on v1.1.3 baseline; v1.2.0 changes don't touch any tested
  invariant.
• Stability registry unchanged. No new MCP tools. No new persisted
  artefacts. The CLI surface remains experimental per ADR-0016.
• Success condition for this slice (per the brief): "a new
  developer should understand Kairo and run it on a repo in under
  5 minutes." The init → doctor → status happy path now takes
  3 commands and reads honestly at every step.

v1.1.3

CI caught another real bug, this time on ubuntu-latest · node 20. The
v1.1.2 timeout fix unblocked Windows; v1.1.3 fixes the test-file ordering
race that was hidden until the matrix finally had room to expose it.

Fixed

• tests/cli.test.ts returned exit 1 instead of 2 on ubuntu-latest · node 20. Root cause: tests/cli.test.ts assumed dist/cli/cli.js
  was already built (it did spawnSync(node, [CLI, ...]) without first
  running the build), so it was racing against
  tests/integration.server.test.ts's beforeAll(execSync('npm run build')). On 5 of 6 matrix cells the Vitest parallel worker picked
  the integration file first; on ubuntu + node 20 it picked the CLI
  file first, the bin didn't exist, spawnSync returned 1 (Cannot
  find module), and the "unknown command exits 2" assertion failed.

  Fix: tests/cli.test.ts now has its own beforeAll that runs npm run build if dist/cli/cli.js is missing — same pattern
  integration.server.test.ts uses. Test-file order is now irrelevant.

Notes

• 193/193 tests still pass. No change to MCP tools, CLI behaviour,
  schemas, or any stable surface. Test infrastructure only — this
  bug was always there, just deterministically masked by parallel
  file order on every host except one.
• This is the second real bug the CI matrix has caught in 24h.
  ADR-0017's premise (cross-platform CI catches deterministic
  regressions that local dev can't) keeps holding.

v1.1.2

First downstream CI run caught a real Windows + Node 22 flake. Single-line
timeout fix; no code-layer change. Caught and fixed within an hour of
v1.1.1 going green — exactly the loop ADR-0017 promised.

Fixed

• tests/snapshot.test.ts "refuses to overwrite a non-empty .kairo/
  unless force" timed out at 5000ms on windows-latest · node 22. The
  test does ~2× the work of any other snapshot test (two full
  seedProject calls + one export + two imports — one rejected, one with
  force). Default Vitest 5s ceiling flaked on slow Windows + Node 22 CI
  runners where mkdtemp / rm -rf / spawn are slower. The other five
  matrix cells (ubuntu × 2, macos × 2, windows + node 20) all passed.

  Two-part fix:

  • Per-test timeout 20s on that specific test — deterministic ceiling
    for the proven-heavy case.
  • Global testTimeout: 15_000 in vitest.config.ts — safety net for
    other honest integration tests in this suite (snapshot round-trip,
    inspect-server boot, perf scenarios) that do real filesystem + spawn
    work. Fast tests are unaffected; the default 5s is just too tight as a
    cross-platform ceiling.

Notes

• 193/193 tests pass on the v1.1.2 commit on Windows × Node 20 + 22
  locally; the matrix gate ran across all six cells.
• No change to MCP tools, schemas, or any stable surface. Test infra only.