# Changelog

All notable changes to `@stackbone/cli` are documented in this file.

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.1.0-alpha.7] - 2026-05-26

### Added

- The Claude Code skill bundle that `stackbone init` / `stackbone link`
  writes is now maintained as a standalone file at
  `apps/wiki/public/content/skills/claude-code/SKILL.md` — the same file
  the CLI installs at `.claude/skills/stackbone/SKILL.md`, modulo the
  `{{cliVersion}}`, `{{controlPlaneUrl}}` and `{{organizationSlug}}`
  placeholders. The wiki page at `/docs/coding-agents/claude-code`
  auto-embeds it between `<!-- skill-embed-start: ... -->` markers.
  A new `cli:sync-skills` Nx target (chained from `cli:build`, and a
  dependency of `wiki:manifest`) regenerates both
  `apps/cli/src/skills/templates.generated.ts` and the wiki embed from
  the source SKILL.md. `pnpm cli:sync-skills --check` fails CI if a
  placeholder is missing or if either output drifts from the source, so
  the SKILL.md a human reviews in the wiki is byte-equal to the one the
  CLI bundle ships.

### Fixed

- `renderClaudeSkill` no longer interprets `$` in interpolated values as
  a `String.replace` substitution pattern (`$&`, `$'`, `$$`, …). Slugs or
  URLs containing a literal `$` were previously silently corrupted in the
  installed `SKILL.md`. Covered by a new unit test in
  `assembler.spec.ts`.

## [0.1.0-alpha.6] - 2026-05-18

### Fixed

- Git Bash / MSYS / MinGW on Windows are no longer caught by the native
  Windows guard. `isWindowsNative` now also inspects
  `process.env.MSYSTEM` (`MINGW64`, `MINGW32`, `MSYS`), which Git for
  Windows sets in every Git Bash session — including the one VS Code's
  integrated terminal spawns. The banner and `unsupported_platform`
  envelope still steer PowerShell / CMD users to WSL2, with Git Bash now
  listed alongside as a supported alternative.

## [0.1.0-alpha.5] - 2026-05-18

### Added

- `stackbone docs <section>` content is now generated from the wiki
  (`apps/wiki/public/content/docs/<section>/*.md`). A new
  `cli:sync-docs` Nx target reads every markdown page, strips the
  frontmatter, prepends the title as an H1 and emits
  `apps/cli/src/docs/topics.generated.ts`; `cli:build` depends on it so
  the bundled CLI can never drift from the wiki again. `docs <section>`
  prints an auto-generated table of contents; `docs <section>/<slug>`
  prints the page body. The inline `starters` / `connections`
  placeholders are gone — once the corresponding wiki pages land they
  surface automatically.
- Branded interactive surface. Clack's prompt glyphs (`◆`, `│`, `┌`,
  `└`, spinner) are repainted to brand orange via a pnpm patch on
  `@clack/prompts`, the boot banner picks up the same truecolor
  accent, and every interactive command (`init`, `link`, `dev`,
  `login`) now opens with a `◆◆◆  stackbone  v<version> · <command>`
  header. The `login` flow uses `note()` for the device code + URL,
  `log.step()` for the browser hint and a `spinner()` for the polling
  wait — replacing the raw `process.stdout` writes that read flat
  against the rest of the clack session.

### Changed

- **Breaking — `--api-url` flag removed.** Control-plane URL resolution
  collapses to `STACKBONE_API_URL` → project config → global config.
  The env var keeps working internally so the team can still point at
  staging/prod, but it is no longer advertised in the wiki, the
  embedded skill template or the README — external developers should
  not need to think about it. HTTP, device-flow and dev-tunnel error
  suggestions are updated to match.
- Native Windows shells (PowerShell, CMD, Git Bash) are now blocked at
  startup. `process.platform === 'win32'` triggers a branded `◆◆◆`
  banner pointing at issue #70 for the long-term Windows-support work,
  routed through the canonical `StackboneCliError` envelope so
  `--json` consumers see the same `{schema_version, error, exit_code}`
  shape they get from every other failure. WSL is unaffected because
  Node there reports `linux`.
- The truecolor ANSI palette is centralised in `core/ansi.ts` and
  reused from the boot-banner, brand-header and platform-guard
  formatters instead of three hand-copied `{ reset, bold, dim, accent }`
  objects drifting in parallel.
- Internal cleanup: `parseResponse(schema, raw, context)` extracted to
  `infra/http.ts` so every control-plane service shares one error
  envelope for unexpected response shapes; `resolveDrizzleKitBin`
  consolidated in `dev/drizzle-bin.ts`; UUID validation centralised in
  `dev/uuid.ts`. `stackbone dev` only fetches the active organization
  when the project is missing `localDevInstallationId` /
  `organizationSlug`, and SIGINT teardown runs the tunnel-PATCH and
  `session.stop()` via `Promise.allSettled` so a hung control-plane
  call cannot block docker teardown. Independent filesystem writes in
  `project.service` and `dev/compose.ts` now run in parallel.

### Fixed

- `stackbone init` on a clean directory no longer errors with "Refusing
  to overwrite agent.yaml". Every starter ships a placeholder manifest
  that `writeStarterFiles` would write first, then
  `writeAgentManifest` would refuse to overwrite. The new
  `writeStarterProject` helper drops the placeholder, writes the rest
  of the starter, and regenerates the manifest with the user-chosen
  name; a flow-level test pins the contract so the two helpers cannot
  re-diverge.

## [0.1.0-alpha.4] - 2026-05-18

### Changed

- **Breaking — `--template` renamed to `--starter`.** The `stackbone init`
  command now reads `--starter <slug>` and scaffolds from `starters/<slug>/`,
  a directory subtreed from one of the public
  `github.com/stackbone/starter-<slug>` repos (10 slugs: `hello-world`, `ai`,
  `rag`, `db`, `storage`, `queues`, `hitl`, `secrets`, `prompts`, `config`).
  The legacy `--template` flag is recognised solely to emit the migration
  message `--template was renamed to --starter; rerun with --starter <slug>`
  and exit non-zero. The interactive picker now groups starters by
  `stackbone.category` (`Core` first, then `Capabilities`) and lists ten
  entries (the three bundled `hello-world` / `workflow` / `autonomous`
  templates are gone — `workflow` and `autonomous` were mocks).
  `.stackbone/project.json` writes `starter: <slug>`; the field is read-compat
  with the legacy `template:` key (one release) and rewritten on next
  `init`/`link`. The bundled `apps/cli/src/templates/` directory is deleted
  in favour of the subtreed `starters/` layout. Public exports of
  `services/scaffolding.ts` were renamed: `TEMPLATES` → `STARTERS`,
  `TemplateChoice` → `StarterChoice`, `parseTemplateId` → `parseStarterId`,
  `renderTemplate` → `renderStarter`.

## [0.1.0-alpha.3] - 2026-05-15

### Added

- `stackbone dev` sessions are now first-class `installation` rows
  (`kind='local'`). The CLI registers the row via
  `POST /api/v1/installations/local-dev` during `init`/`link`, `PATCH`es
  `local_tunnel_url` on dev start, and nulls it on Ctrl-C. The dev
  boot banner emits a path-aware deeplink
  (`app.stackbone.ai/app/<orgSlug>/installations/<id>?stackbone-dev=<tunnel>`)
  consumed in one shot by the `stackboneDevBootstrapGuard` so Studio
  opens straight on the local installation. Local-dev rows skip the
  provisioning saga and the tier-quota gate by construction and are
  garbage-collected after 7 days of inactivity.

### Changed

- Unified agent runtime env contract under `STACKBONE_*`. The dev
  emulator now injects `STACKBONE_AGENT_ID` (the agent slug) plus
  `STACKBONE_S3_ACCESS_KEY` / `STACKBONE_S3_SECRET_KEY` /
  `STACKBONE_S3_ENDPOINT` / `STACKBONE_S3_BUCKET` /
  `STACKBONE_S3_REGION` / `STACKBONE_POSTGRES_URL` into the agent
  process, replacing the previous mix of `AWS_*` / `S3_*` /
  `DATABASE_URL` names. Agents that still read the legacy names must
  migrate.
- Emulator `/api/schema` now returns `{ input: null, output: null }`
  (200) when the manifest declares neither schema or the agent is
  unreachable — was 502 before. Mirrors the cloud `/studio/schema`
  shape so the Studio Playground UI can boot before the agent is
  healthy.
- `dev/fixtures-store.ts` persists JSONL records using the canonical
  `Fixture` wire schema (camelCase `createdAt`, typed as `Fixture`) so
  list/create return the wire type directly.

### Fixed

- `protectedCommand` no longer triggers the device-code flow on the
  user's behalf. When no valid session exists it fails fast with
  `code: 'auth'` and the standard "Run stackbone login" hint, and it
  no longer retries on a mid-flight 401. Reason: the HTTP adapter
  caches `tokenStore.activeSession()` once per process, so the
  pre-login `POST /api/auth/device/code` poisoned the cache with
  `null` and every subsequent request from the same process went out
  without an Authorization header.

## [0.1.0-alpha.2] - 2026-05-12

### Added

- Per-stage spinners during `stackbone dev` (docker, platform/creator/rag
  migrations, agent, emulator, tunnel) and a redesigned rounded-box Studio
  banner that surfaces the actionable deeplink first. New global flag
  `--verbose` (also `STACKBONE_VERBOSE=1`) restores the raw firehose of
  docker compose stdout and pino logs for debugging.

### Changed

- `stackbone dev` Studio banner now prints
  `app.stackbone.ai/app?stackbone-dev=<tunnel>` instead of the retired
  `/studio?baseUrl=…` deeplink. The new URL is consumed in one shot by the
  `stackboneDevBootstrapGuard` mounted on `/app`, which flips Studio to
  local mode against the tunnel and opens the panel on Runs.

### Fixed

- `stackbone dev` boot banner no longer emits a leading newline or
  duplicate `│` rail rows around the inlined Studio banner when running
  under clack's left rail in human mode.

## [0.1.0-alpha.1] - 2026-05-12

### Changed

- Default control plane URL updated to `https://api.stackbone.ai` (was `https://api.stackbone.dev`).
- Agent manifest `apiVersion` updated to `stackbone.ai/v1` (was `stackbone.dev/v1`).

## [0.1.0-alpha.0] - 2026-05-12

### Added

- Initial public alpha release of the Stackbone CLI on npm under the `alpha` dist-tag.
