# Changelog

All notable changes to `@dreamtree-org/ai-builder` are documented here.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.7.0] - 2026-08-07

**Agent session continuity + version-accurate layer knowledge.** A session that
ended mid-task used to lose everything it had worked out, and an agent asking
"what props does `<Button>` take?" had to guess. Both are closed here.

### Added

- **`project_state` MCP tool — call it first.** One call returns the app on disk
  (modules, models, tables), installed layer versions, the state of
  `tracking/plan.md` including its Resume block, git branch/commit, and a computed
  **`nextAction`**. Supports `dir`, `include[]` to trim the response, and `refresh`
  to bypass the 6h cache.
- **`plan_template` MCP tool** — returns the `plan` / `big-picture` / `backlog`
  skeleton pre-filled from the real project (app name, layer versions, module keys,
  model count), plus where to write it. The server still writes nothing, ever.
- **`layer_docs` MCP tool** — serves korm-js `ai-skills/*.md` and twreact-ui
  `dist/ai-schema.json` read out of **your own `node_modules`**, so component props
  are true for the version you actually installed. Modes: `toc | section | full |
  components | component`, with `offset` paging. ai-builder deliberately keeps no
  snapshot of another package's API — a snapshot is stale the moment they publish.
- **Generated apps ship agent memory.** Scaffold now emits `CLAUDE.md` (a pointer
  map, not a rulebook) and a `tracking/` trio: `plan.md` (with an HTML-marker
  `Resume here` block rewritten at *every task transition*, not at session end),
  `big-picture.md` (seeded from the app's real module registry and schema), and
  `backlog.md`.
- **`--ai <provider|none>` on the scaffold path.** A new app gets the skill pack +
  MCP wiring installed in-process (default `claude`). The value is validated
  *before* any file is written, and nothing on this path touches the network.
- **Family-wide drift reporting in `ai-builder update`** — declared vs installed vs
  latest for every `@dreamtree-org` package in the project, with the exact
  `npm i <pkg>@latest` to run.
- **`CHANGELOG.md`** (this file), shipped in the published tarball. GitHub release
  notes are now the matching section rather than auto-generated commit titles.

### Changed

- **`check_version` widened** from ai-builder-only to the whole `@dreamtree-org`
  family. The MCP server now exposes **11 tools** (was 8), all still read-only.
- **Shared provider files are block-merged, never overwritten.** `AGENTS.md`,
  `GEMINI.md` and `.github/copilot-instructions.md` are conventions you write in
  too, so only the span between `<!-- ai-builder:start -->` and
  `<!-- ai-builder:end -->` belongs to us; a file with no markers gets the block
  appended. Files that are wholly ours (`.claude/skills/…`, `.cursor/rules/…`)
  still need `--force`.
- **`init` no longer creates `tracking/`.** Installing a skill pack shouldn't add
  documents to someone's repo. Scaffolded apps get it; elsewhere the assistant
  writes it from `plan_template` when it first plans.
- **The skill body is generated from `src/knowledge.js`** instead of a duplicated
  string constant, so the installed skill and the MCP server can no longer
  disagree about the build rules.
- **One npm-lookup path** (`src/registry.js`): https → `npm view` → built-in
  version floor, a single 6h cache, and `AI_BUILDER_NO_UPDATE_CHECK` now gates
  **both** transports (previously only the https one).
- **`src/substitute.js`** extracted — `__TOKEN__` substitution is shared by the
  generator, `init`, and the MCP server.
- The skill pack is restructured around **ORIENT → PLAN → BUILD → VERIFY → RECORD**.
- Releases are now gated on the full e2e workflow (scaffold → install → build →
  boot), not just the smoke test.

### Fixed

- **Layer resolution reaches the app's `client/` project.** A generated app is two
  npm projects, and `twreact-ui` is declared and installed only in `client/`.
  Resolution searched the root then walked *up*, never *down* — so from the app
  root (where `layer_docs` normalizes every `dir`) twreact-ui read as **not
  installed**. `layer_docs`, `project_state.layers` and `ai-builder update` were
  blind to the front-end layer in every generated app. Resolution order is now
  root → nested app project → upward; a nested hit reports `workspace: "client"`
  and stays `hoisted: false`.
- **`outdated()` no longer reports "up to date" when it can't tell.** `compareSemver`
  returned 0 for unparseable input, so a declared range of `"latest"` or
  `"file:../korm-js"` came back as `isOutdated: false`. It now returns `null` for
  unknown unless both sides parse, and range prefixes (`^ ~ >= <`) are stripped.
- **`project_state` could be confidently wrong** in three ways, all now fixed and
  pinned by assertions: a partial `include` read reporting "no plan, start one"
  over live work; a project root silently resolved from a nested path (now reports
  `evidence` and `levelsUp`); and an ancestor `node_modules` claimed as the
  installed layer (now flagged `hoisted` with a warning).

### Docs

- README: the `update` flag table, what `--no-design-skill` actually opts out of
  (`init` shells out to the third-party `ui-ux-pro-max-cli` over the network), the
  two-npm-project layer resolution note, `src/substitute.js`, an accurate build
  pipeline diagram, and a new **Releasing** section.

### Upgrading

Nothing to do beyond `npm i @dreamtree-org/ai-builder@latest`. On the first
`ai-builder update` after this release, provider files installed by an older
version as whole-file writes are detected and **migrated in place** to managed
blocks — your own content in `AGENTS.md` / `GEMINI.md` /
`.github/copilot-instructions.md` is preserved, not replaced.

## [0.6.0] and earlier

See the [GitHub releases](https://github.com/DreamtreeTech/ai-builder/releases)
for versions published before this changelog was introduced.

[Unreleased]: https://github.com/DreamtreeTech/ai-builder/compare/v0.7.0...HEAD
[0.7.0]: https://github.com/DreamtreeTech/ai-builder/compare/v0.6.0...v0.7.0