# TwG CLI Changelog

## 1.0.1

### Highlights

- Adds `twg api` to every build profile, so signed-in users can make
  authenticated Atlassian REST and GraphQL calls with the CLI's saved
  credentials, product shortcuts, and structured JSON/JSONL output.
- Makes `twg admin` available in the external CLI with Admin API key onboarding,
  org switching, user lifecycle commands, and lifecycle capability checks.
- Improves command discoverability across Jira, Confluence, JSM, Bitbucket,
  Trello, Loom, Talent, Atlas Goals, and Atlas Projects with clearer help,
  examples, guards, synonyms, and safety guidance.
- Adds `twg confluence ... --help-body-format` so rich-body commands can show
  supported plain text, Markdown, and HTML input formats directly from the CLI.
- Hardens day-to-day workflows, including JSM service search, Confluence tiny
  URL reads, Jira goal/project links, Ctrl+C cancellation during long fetches,
  OAuth refresh timing, and final analytics delivery before exit.

## 1.0.0

TWG CLI 1.0.0 brings the 0.9.x release line together as a stable baseline for
agent-oriented Atlassian workflows, with broader Jira and Confluence coverage,
more reliable installs and updates, improved authentication, and better command
discoverability.

### Highlights

- Establishes the agent-friendly command model as the stable 1.0 baseline, with
  richer Jira, Confluence, Bitbucket, Loom, and Feedback workflows.
- Adds a large Confluence `content` surface that lets agents work with pages,
  blog posts, whiteboards, databases, folders, comments, labels, permissions,
  tasks, versions, history, attachments, and reactions through a more uniform
  command shape.
- Expands Jira REST parity across work items, attachments, worklogs, comments,
  properties, changelog, votes, filters, dashboards, boards, sprints, project
  components, versions, and bulk operations.
- Improves install, update, and OAuth behaviour so the binary is safer to
  distribute and easier for agents to diagnose.

### Breaking changes

- No intentional command removals are included in this release. Some Confluence
  and install flows now prefer normalized command shapes and clearer guarded
  behaviours, while compatibility aliases remain where required.

### Confluence

- Adds the new `twg confluence content` surface as the preferred agent-friendly
  entry point for content lifecycle operations.
- Wires page, blog post, whiteboard, database, and folder lifecycle parity where
  underlying services exist, including page create/update/archive/restore/delete
  and move, blog post create/update/delete, whiteboard/database list/get/create/delete,
  and folder get/create/delete.
- Adds content subresources for:
  - `attachments` upload/download.
  - `comments` list/get/create/reply/update/resolve/reopen/delete.
  - `labels` list/add/remove.
  - `permissions` list/add/remove.
  - `tasks` list/get/complete/reopen.
  - `versions` and `history` list/get/restore.
  - `reactions` get/add/remove.
- Makes `--type` optional for many ID-only `confluence content` commands by
  adding dispatcher probes and structured unsupported-operation errors.
- Adds `confluence content create` over the agentic content API for pages,
  live docs, blog posts, whiteboards, databases, embeds, smart links, folders,
  and slides.
- Normalizes `twg confluence space` verbs to align with the new content surface,
  while preserving compatibility aliases where needed.

### Jira

- Adds REST-backed Jira work item subresource commands for attachments,
  comments, watchers, issue links, properties, changelog, votes, and worklogs.
- Adds `twg jira workitem bulk-get` and `twg jira workitem bulk-transition`,
  including a safe dry-run default for bulk transitions.
- Speeds up repeated `twg jira workitem get` reads by using REST search batching
  when possible and falling back to per-issue reads when needed.
- Adds rich description/comment/worklog input formats for plain text, Markdown,
  HTML, and ADF, with HTML as the safer default for rich-text authoring.
- Adds REST-backed Jira filter and dashboard commands, including saved filter
  lifecycle, sharing/subscriptions, dashboard lifecycle, and gadget administration.
- Adds Jira Agile board and sprint parity commands, sprint snapshots, board and
  sprint discovery from project URLs or issue keys, and project component/version
  lifecycle commands under `jira space`.

### Bitbucket, Loom, and Feedback

- Adds `twg bitbucket inbox` for a bounded current-user PR inbox with reviewer
  and author filters plus compact task, comment, and check signals.
- Adds `twg bitbucket pipeline latest-failure` to locate the newest failed
  pipeline and hydrate failed step log tails in one bounded flow.
- Normalizes Bitbucket PR descriptions that contain escaped newlines so
  agent-generated Markdown renders correctly.
- Adds Loom transcript preview and file-backed full transcript support to
  `twg loom get`.
- Routes `twg feedback` Jira issue creation through the Jira REST gateway with
  clearer authentication and timeout guidance.

### Agent and workflow experience

- Adds agent-friendly command repairs and aliases for common lookups, including
  positional user search, pull-request status aliases, project/goal shortcuts,
  Confluence page positional get, and Loom/video/meeting URL hydration.
- Splits bundled TWG workflow guidance into outcome-specific skills for better
  agent discovery.
- Restores and refreshes generated CLI catalog discoverability for the new
  Confluence content and space surfaces.

### Auth, install, and update hardening

- Ships and fixes the OAuth device-code login path, including refresh behaviour
  and a corrected scope allowlist for the TWG CLI OAuth client.
- Adds low-frequency update checks from `doctor`/version commands and reports
  installed TWG skill freshness with repair guidance.
- Fixes Windows `twg update` replacement flows, records install metadata, and
  preserves logs when background replacement fails.
- Warns about duplicate Homebrew/direct installs and prevents accidental direct
  installs over active Homebrew-managed installs.
- Simplifies direct installers by requiring setup finalization and sharing the
  POSIX installer template across shell installs.
- Fixes shell installer checksum parsing for CRLF `SHA256SUMS` manifests.
- Improves command compatibility coverage so supported aliases resolve more
  reliably.

## 0.9.8

### Minor Changes

- b48bdbd: Add `twg access` for product, site, org, test-like, configured-site, Bitbucket, and Rovo access inventory checks.
- 91c25e2: Add a `BUILD_ENABLE_CONFLUENCE_CONTENT_TOOLS` build flag so release-style setups
  can opt into the agentic Confluence content tools bundle. The bundle currently
  exposes a `confluence content get` preview backed by Confluence's
  `/wiki/api/v2/agentic/content/{id}` (and `?content_url=`) endpoint, with
  summary, outline, and full detail levels; future agentic create/update/delete
  commands will land behind the same flag so the surface graduates as a unit.

  The flag defaults to on in dev/internal builds and off in release/external
  builds; invalid values warn and fall back to the build-profile default. Set
  `BUILD_ENABLE_CONFLUENCE_CONTENT_TOOLS=1` at build time (e.g.
  `BUILD_ENABLE_CONFLUENCE_CONTENT_TOOLS=1 npm run setup`) to opt a release-style
  build into the surface.

  Coordinate the default flip with the monolith's `agentic_content_tools` Statsig
  gate so client-side availability tracks server-side availability.

- 2f94fe9: Help discovery: typed `Guards:` and `Synonyms:` sections, plus ranking fixes

  Adds a `Guards:` heading and an inline `Synonyms:` line that authors can drop into any
  command's `addHelpText("after", …)` block. The catalog parses both into typed
  `HelpCommandRecord.guards` and `HelpCommandRecord.synonyms` fields, the index persists
  them, and flexsearch slots them into the existing weight ladder
  (`path: 12, cmd: 10, synonyms: 9, alias: 8, meta: 5, desc: 3, guards: 2, args: 2, opts: 2, input: 2`):
  - `synonyms` — weight 9, just **above** `alias: 8`, so curated semantic neighbours such
    as `cmdb` → `assets` or `calendar` → `meetings` win against incidental description
    prose and even against legacy aliases when the alias is the wrong target.
  - `guards` — weight 2, low enough to act as a tie-breaker for sibling-overlap commands
    without inventing matches on unrelated commands.

  As part of the content rollout, `pr-tree` and `workitem-tree` had their existing
  free-form prose footers converted to typed `Guards:` blocks. Those footers were
  previously not indexed at all (the catalog only captured `Examples:` blocks), so the
  conversion is also a strict gain in search coverage for those two commands.

  Two complementary ranking fixes ship in the same change so existing commands benefit even
  without authored content:
  - Drop single-character query tokens (`a`, `i`, `o`, …) at the tokenize boundary so
    noise tokens stop prefix-matching every `assets *` / `auth *` path.
  - Damp the path-prefix bonus by the ratio of query-token length to path-token length so
    short prefixes no longer dominate ranking against full-word matches.

  `guards` and `synonyms` are additive optional fields, so the help-record and help-index
  schema versions stay at `1`. Cache invalidation on upgrade is carried by
  `programSignature()`, which now hashes per-command rendered help-text length and so
  changes whenever a Guards/Synonyms block is added or removed.

  Authored content covers the full multi-surface ambiguity surface: `meetings`, `docs`,
  `videos`, `spaces`, `org-tree`, `pr-tree` (existing prose footer converted),
  `workitem-tree` (converted), `assets`, `collaborators`, `recently-viewed`,
  `notifications`, `pull-requests`, `context jira workitem`, `context user`,
  `context confluence` (page/space/blogpost/whiteboard), `goals`, `projects`,
  `focus-areas`, `talent`, `teams`, `jsm incident query`, `jsm alert query`,
  `jsm post-incident-review query`, `confluence blog`, `confluence database`,
  `confluence whiteboard`, `bitbucket search prs`, and `bitbucket default-reviewer`.

  Examples of fixed rankings (`twg help <freeform>` → top result):
  - `find a persons meetings` → `meetings` (was assets subtree)
  - `okr` → `goals`
  - `postmortem` → `jsm post-incident-review query`
  - `outage incident` → `jsm incident query`
  - `monitoring page alert` → `jsm alert query`
  - `issue context` → `context jira workitem`
  - `user perimeter` → `context user`
  - `team membership` → `teams`
  - `open positions` → `talent`
  - `blog post announcement` → `confluence blog`
  - `whiteboard diagram` → `confluence whiteboard`
  - `default reviewer` → `bitbucket pull-requests default-reviewer`
  - `find pr by text` → `bitbucket search prs`
  - `atlas project` → `projects`
  - `focus area initiative` → `focus-areas`
  - `cmdb` → `assets`
  - `who reports to whom` → `org-tree`

- 15a40ce: Make `twg work query` count-first by default, add distinct entity counts for
  validated sections, require `--fetch items` when callers need hydrated work item
  rows, and guard unbounded item fetches with a 2000-relationship preflight limit.

### Patch Changes

- 3b0a2d7: Add a `--body-output-file` option to Confluence page reads so body content can be saved to a file while JSON output stays metadata-focused.
- e3c4f17: Stop user search from calling the admin users GraphQL lookup.
- ab03591: Document agent-facing help search behavior changes that de-rank advanced raw graph/debug commands unless the query names them directly, and tighten high-fanout agent output contracts for org, goal, and project hydration commands.
- 7f69e9e: Add project-aware Jira field discovery and generic custom field support for workitem create and update.
- ba5649a: Stop publishing the duplicate Windows `setup.ps1` installer; `install.ps1` is now the canonical PowerShell installer URL for both public Bifrost and internal Statlas releases.
- 7f2d4f9: Skip the optional Bitbucket token prompt during login when accessible product discovery confirms the account has no Bitbucket access.
- b437a97: Add `twg workitem-tree` with an `issue-tree` alias to summarize Jira work item activity by reporting tree with fast GraphStore Cypher-backed counts by default and guarded `--full-fetch` issue sample fetching.

## 0.9.7

### Patch Changes

- 5087758: context: gracefully handle partial GraphQL responses; search snippet formatting

  `twg context user`, `twg context confluence <type>`, and `twg context jira workitem`
  now return whatever data the graph store _did_ manage to fetch when one or
  more relationship branches fail to load. The dropped branches are surfaced as
  a brief warning on the v2 envelope's `warnings` field (and to stderr in text
  mode) instead of throwing a hard
  `Unable to retrieve data: cannot route the request` error.

  `twg search` results no longer show multi-line raw content in snippet previews —
  descriptions are now collapsed to a single readable line and dimmed for visual
  consistency with other result metadata.

- 7f0e519: test(coverage): use real fixtures for `confluence labels attachment` and `confluence labels custom-content`

  The static read coverage harness was passing a Confluence page ID to `confluence labels attachment` and a placeholder `0` to `confluence labels custom-content`. Both produced HTTP 404s, which the harness mis-classified as "token lacks Confluence scope" — masking the fact that both commands work correctly. The harness now discovers a real attachment and custom-content ID via CQL on each run, and the Confluence skip-matchers are reordered so genuine 404s can no longer be reported as scope failures.

- 142758c: fix(search): recover full results when AGG returns partial success with downstream errors

  `twg search query --assignee <user>` (and other filtered searches) previously showed a warning that results were limited to Confluence and Jira. This was caused by two issues:
  1. **Partial AGG responses were discarded**: When AGG fanout to a downstream connector returned a 403, AGG still returned HTTP 200 with valid search results alongside a `DOWNSTREAM_ERROR` GraphQL error. `graphql-request`'s default error policy treated this as a failure and threw away the usable data, triggering the Confluence/Jira-only fallback. Fixed by catching the `ClientError` directly in `runAggSearch` and recovering the data when `response.data.search.results.edges` is non-null, scoped strictly to the Rovo search path so other GraphQL callers are unaffected.
  2. **Default search fanned out to all connected apps implicitly**: Searches without `--app` were fetching entity types from all 55+ connected third-party apps and including them in the search, causing AGG to fan out to connectors that may fail. Third-party entities are now only included when explicitly requested via `--app`.

- 5f2273e: Remove `jsm conversation by-container query`, `jsm conversation workspace experience-config get`, `jsm conversation workspace related-experience-config get`, and `jsm automation task-agent query` from the public CLI surface at the request of the upstream `jsmChannels` owners. Also hide `jsm incident get` from `--help`, the generated catalog, and the command-policy schema until the required `read:incident:jira-service-management` scope is available in the `twg login` granular-scope flow; the runner remains wired so existing scripts continue to work.
- e189268: Add `twg pr-tree` with a `pull-requests-tree` alias to summarize pull request activity by reporting tree with fast GraphStore Cypher-backed counts, guarded full-fetch samples, and per-person direct examples.

## Earlier Releases

This public changelog starts at 0.9.7. Earlier internal and pre-stable entries
are omitted to keep release notes focused on currently relevant TWG CLI
behavior.

Please use the latest stable installer for supported setup and update flows.