# Changelog

All notable changes to `@getguru/cli` are documented here.

Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/).
Versioning: [SemVer](https://semver.org/).

Two CLI-specific section conventions on top of Keep a Changelog:

- **Breaking (output)** — JSON envelope or field-shape changes. These can break
  agents that parse the CLI's output.
- **Breaking (cli)** — command, argument, or flag changes. These break humans
  and scripts that invoke the CLI directly.

Keeping these distinct makes both failure modes visible at a glance.

## [Unreleased]

## [0.5.0] - 2026-07-17

### Added

- Surgical draft editing — revise a card draft's content node by node, with edits that merge cleanly alongside concurrent changes:
  - `cards read-draft-for-edit <draftId>` — read a draft's live content, with every node annotated by a stable `alias` you target in edit ops.
  - `cards edit-draft <draftId> --ops <json>` — apply alias-targeted ops to a draft: `insertNode`, `appendNode`, `replaceNodeContent`, `setNodeProps`, `deleteNode`. Returns the updated draft with fresh aliases, ready for the next edit.
- User-group draft collaborators: `cards add-draft-collaborator <draftId> --type user-group --group-id <id>` adds a group; `cards remove-draft-collaborator <draftId> <groupId>` removes it. The positional email form adds an individual user (`--type user`, the default).
- `guru schema <name>` covers 28 additional resource types: `tag`, `tag-write`, `tag-category-write`, `agent-skill`, `agent-skill-write`, `agent-skill-file`, `agent-skill-file-write`, `agent-skill-access`, `agent-skill-access-candidate`, `card-version`, `card-comment-reply`, `answer-feedback`, `answer-feedback-result`, `answer-activity`, `answer-review-item`, `answer-assignment`, `answer-assign-result`, `chat-ask`, `chat-answer`, `whoami`, `draft-card`, `draft-card-write`, `draft-context`, `draft-context-write`, `draft-collaborator`, `page-move`, `folder-entry`, `member-invite-result`.

## [0.4.0] - 2026-06-22

### Added

- Knowledge Agents command surface: `agents create`, `update`, `delete`, `add-file`, `remove-file`, `ask`, and `ask-result`.
- `agents feedback <answerId>` — submit thumbs up/down feedback on an answer (`--rating up|down`, `--clear`, `--comment`).
- `agents answer-activity <answerId>` — read an answer's activity log.
- `agents answer-review` — list answers from the review queue by `--status`, with `--agent`, `--days`, `--with-answer`, `--with-asker` filters.
- `agents assign <answerId>` / `agents unassign <answerId>` — route an answer to an expert (`--user`, `--group`, `--note`).
- Per-command `--help` epilogs for `agents ask`, `create-skill`, and `add-skill-access`.

### Fixed

- `agents` list endpoints no longer crash on an empty collection (empty `200` body now maps to `[]`).

## [0.3.1] - 2026-05-27

Folder management we assumed already worked didn't: folders nested below the
top level couldn't be resolved by title under `--collection`, and there was no
way to nest or move a folder. This release fixes folder resolution and fills in
the missing create/move surface.

### Fixed

- `folders` commands resolve folders nested below the collection root when
  matching by title. `resolveFolderInCollection` previously only saw top-level
  folders (via the home-folder items endpoint), so nested lookups by title
  failed; it now lists folders globally and scopes by `collection.id`. It also
  rejects a folder UUID that belongs to a different collection than the one
  named in `--collection`, instead of silently operating across collections.
- Folder input-validation failures surface as `INPUT_VALIDATION_ERROR`
  (exit 3) rather than `UNKNOWN_ERROR`.

### Added

- `folders create --parent-folder <idOrTitle>` — create a folder nested inside
  another, not only at the collection root.
- `folders move <idOrTitle> --parent-folder <idOrTitle> | --to-root` — relocate
  a folder within its collection. The two flags are mutually exclusive and one
  is required. Cross-collection moves are rejected at the command layer —
  Guru's model treats a folder as belonging to a single collection, so moving
  across collections isn't a real operation and the CLI doesn't expose it.

## [0.3.0] - 2026-05-05

### Added

- `cards versions`, `cards get-version`, `cards get-last-verified-version`
  — read access to a card's version history. Lets agents inspect prior
  revisions and the most recently verified version without leaving the
  CLI.
- `X-Guru-Application: guru-cli` header sent on every API request, so
  server-side telemetry can attribute traffic to the CLI.

### Changed

- `cards create` now routes through the draft → publish flow internally,
  matching the webapp's authoring path. Same args and output envelope;
  the change is implementation-only.

### Breaking (cli)

- Removed `cards update`. Direct updates to existing cards are not
  supported via the CLI; use `cards create-draft` for new content, or
  edit existing cards through the Guru webapp.

## [0.2.0] - 2026-04-20

### Added

- `cards create --draft` — routes the create path through `/drafts` so agents
  can start in a draft state; returns the draft object. Same args as
  `cards create-draft`.
- `--json-content` on `cards create`, `cards create-draft`, `cards update`,
  and `cards update-draft`, mirroring the pages CLI. Lets agents author
  canonical Slate JSON for high-fidelity blocks (callout, collapsible,
  code-block, markdown) that lose fidelity in the server's HTML→JSON
  conversion path.
- Per-command allowlist for destructive commands via `GURU_CLI_ALLOWLIST`
  env var or `guru config set allowlist "…"`. Permits a specific command
  (e.g. `cards archive`) without escalating the whole write tier to `all`.
  Merges env + global + local scopes; invalid entries warn and drop. Audit
  lines mark allowlisted runs with `"allowlist": true`.
- `guru-card-authoring` skill bundled with the CLI (distributed via `guru
  skills`).

### Changed

- `cards` help text now leads with "Prefer draft-first authoring." `cards
  create` opens with a ⚠ warning that it publishes immediately; `cards
  create-draft` is labeled the preferred path.
- `cards archive` description made soft-delete semantics explicit.
- `guru-card-authoring` skill documents the callout palette and the
  `customColor` field.
- README documents the `EACCES` workaround for `npm install -g` on macOS
  when the global prefix isn't user-owned.

### Breaking (cli)

- Removed `cards unpublish`. The command returned a 400 from the API and
  produced a published→draft state with no UI affordance in Guru. The
  underlying `drafts.create({ cardId })` path remains in the resource layer.
- Removed `cards delete`. It was an alias for `cards archive` and its name
  implied a hard-delete that Guru's API doesn't expose. Use `cards archive`.
- Removed `cards update-draft` and `pages update-draft`. The `/drafts` and
  `/pagedrafts` endpoints have no conflict detection with the webapp's
  multiplayer editor, so updates were silently overwritten when a draft was
  open in the browser. Delete-and-recreate, or use the webapp.
  `DraftResource.update` / `PageDraftResource.update` remain in the resource
  layer, ready to rewire once the multiplayer service exposes a sync
  primitive.

## [0.1.0] - 04/13/2026

### Added

- Initial public release of `@getguru/cli`.
- Command groups: `cards`, `collections`, `folders`, `pages`, `search`,
  `agents`, `announcements`, `groups`, `members`, `tags`, `sources`, `teams`,
  `schema`, `skills`, `auth`, `config`.
- Bundled skills: `guru-page-authoring`, `guru-source-facet-search`.