@relipa/ai-flow-kit 0.1.0 → 0.1.1

package/docs/common/CHANGELOG.md

@@ -1,334 +1,350 @@
-# Changelog
-
-All notable changes to **ai-flow-kit** will be documented in this file.
-
-Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
-Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
----
-
-## [0.1.0] - 2026-05-28
-
-### Added
-
-- **Multi-target `ak use`** — `ak use` now accepts variadic targets so multiple sources can be loaded in a single call. The first target becomes the primary context (drives Gate 1); the rest are appended to `current.json` as `supplementaryContext[]`. Targets can be ticket IDs, Backlog/Jira URLs, or local files.
-  ```bash
-  ak use PROJ-33 PROJ-10 docs/arch.md
-  # PROJ-33 = primary, PROJ-10 + docs/arch.md = supplementary
-  ```
-  Backward compatible: `ak use PROJ-33` (single target) behaves exactly as before.
-- **Auto link resolution** — When the primary ticket's description contains Backlog/Jira URLs, `ak use` now auto-fetches them and appends to `supplementaryContext[]`. AI no longer misses linked context. Capped at **5 auto-resolved links per `use`** to keep loads fast; per-link errors are caught and logged without aborting the command.
-- **Comment-aware link resolution** — Comment URLs are resolved to that **single comment** instead of fetching the whole ticket. Recognised patterns:
-  - Backlog: `https://*.backlog.com/view/PROJ-10#comment-456`
-  - Jira: `https://*.atlassian.net/browse/PROJ-10?focusedCommentId=456`
-- **`ak fetch-links <url>` command** — Standalone command that fetches a single Backlog/Jira URL and prints a `SupplementaryContext` JSON object to stdout. Used by the `read-study-requirement` skill at runtime when AI encounters a link in the ticket description that wasn't already resolved at `use` time.
-  ```bash
-  ak fetch-links "https://company.backlog.com/view/PROJ-10#comment-456"
-  ```
-- **`supplementaryContext[]` schema in `current.json`** — New top-level array; each item has shape `{ sourceType: 'ticket'|'comment'|'file'|'text', sourceUrl?, sourcePath?, ticketId?, commentId?, title?, description?, content?, author?, date? }`. Persisted across sessions and consumed by the SessionStart hook.
-- **SessionStart hook renders supplementary block** — `scripts/hooks/session-start.js` now emits a `**Supplementary Context (N source(s)):**` section in the AI context prompt, one line per item, content truncated at 1000 chars to keep token cost bounded.
-- **`read-study-requirement` skill integrates supplementary context** — Gate 1 instruction file (custom + installed `.claude/skills/`) now has an explicit step to read `supplementaryContext[]` and use `ak fetch-links` for any unresolved links found while analysing the ticket.
-- **`scripts/link-resolver.js` module** — New CommonJS module that owns all URL classification and HTTPS fetching for Backlog/Jira. Exports: `classifyLink`, `scanLinks`, `fetchBacklogTicket`, `fetchBacklogComment`, `fetchJiraTicket`, `fetchJiraComment`, `fetchLink`, `resolveLinks`. Accepts credentials as parameters to keep `use.js` free of circular imports.
-- **Jest test suite** — Added Jest 30 as a dev dependency with `testMatch: ["<rootDir>/tests/**/*.test.js"]` to scope discovery to project tests (skips `upstream/tests/`). Suite includes `tests/smoke.test.js` and 20 unit tests in `tests/link-resolver.test.js` covering URL classification, scan, dedup, per-adapter fetch paths, and `resolveLinks` error isolation.
-
-### Changed
-
-- **`use.js` exports as named const** — `module.exports` shifted from anonymous function to `useCommand` with a `loadCredentials` property attached, so other modules (CLI `fetch-links` handler) can reuse credential loading without re-implementing it. External call shape (`useCommand(targets, options)`) unchanged for backward compatibility.
-
----
-
-## [0.0.9] - 2026-05-25
-
-### Added
-
-- **`figma-desktop` adapter** — New MCP preset using the official `@figma/mcp-server` package (Figma Inc.). Requires Figma Desktop app installed and open. No API token needed — authenticates via Desktop session. Run `ak init -a figma-desktop` to set up. See [`custom/mcp-presets/figma-desktop.json`](../../custom/mcp-presets/figma-desktop.json).
-- **Next.js App Router support in `figma-to-component` skill** — Detects App Router projects (via `nextjs-app-router` in `CLAUDE.md` or presence of `app/` directory). Defaults to Server Component (`export default async function`); adds `'use client'` directive only when the design has interactive states (hover, click handlers, form inputs).
-- **Angular support in `figma-to-component` skill** — Detects Angular projects (via `angular` in `CLAUDE.md` or presence of `angular.json`). Generates standalone `@Component` class with `@Input() className` and computed `hostClasses` getter. Uses Tailwind if `tailwind.config.*` exists, otherwise CSS-in-component.
-- **4-tier framework detection in `figma-to-component` skill** — Detection order: (1) `CLAUDE.md` identifier → (2) project file scan (`app/` dir, `angular.json`, `nuxt.config.*`) → (3) fallback to Next.js/React. Previously only supported React and Vue.
-- **Figma workflow guide** — New developer guide at [`docs/common/workflows/figma.md`](figma.md) covering prerequisites (REST API vs Desktop), how to get node URLs, trigger commands, expected output format, review checklist, and troubleshooting table.
-- **MCP presets documentation** — Added full Figma REST API and Figma Desktop sections to [`custom/mcp-presets/README.md`](../../custom/mcp-presets/README.md), including a side-by-side comparison table.
-- **`ak gate N start|approved` auto-syncs task state** — Calling `ak gate 1 start --ticket PROJ-33` now automatically advances `currentGate` in `task-state.json`, removing the need to always call `ak task next` for gate tracking. `approved` records the approval timestamp and advances to the next gate. Uses `Math.max()` guard to never regress gate progress.
-- **Session telemetry enrichment** — `session.start` now captures the active AI model name and user email from config. `session.stop` records model, input/output token counts, and a prompt summary extracted from the session transcript (`transcript_path` in hookData).
-- **`project-conventions.md`** — New mandatory override file at `custom/rules/project-conventions.md`. Enforces that Gate 2 plans are always saved to `plan/[ticket-id]/plan.md` (overriding the skill default `docs/superpowers/plans/`). Includes a checklist and path table for all Gate outputs.
-- **Gate workflow: explicit plan output path** — Gate 2 instruction in `gate-workflow.md` now explicitly states that the plan must be saved to `plan/[ticket-id]/plan.md`, with a note that the `writing-plans` skill default path is overridden.
-- **WSL clipboard support in `ak prompt`** — `ak prompt` now correctly copies output to the Windows clipboard when running inside WSL using `powershell.exe Set-Clipboard`. Previously fell through to `xclip`/`xsel` which are unavailable on WSL without extra setup.
-- **`appscript.js`** — Google Apps Script source for the self-hosted telemetry backend. Receives HMAC-signed events from the `ak` CLI, validates them, and appends rows to Google Sheets.
-- **Telemetry `record()` returns result object** — `record()` now returns `{ok: true}` on success or `{ok: false, reason, error}` on failure, enabling `ak gate` and `ak telemetry log` to display ✓ / ⚠ feedback per event.
-- **`ak init` remembers previous framework selection** — Re-running `ak init` in an already-configured project now pre-selects the previously chosen frameworks (read from `.aiflow/state.json`) instead of falling back to auto-detection. A "Previously selected: ..." hint is shown above the checkbox list.
-
-### Fixed
-
-- **Critical: `figma-to-component` skill used non-existent tool names** — The skill referenced `figma_get_file_nodes`, `figma_get_file_styles`, `figma_get_file_components`, and `figma_get_image` — none of which exist in `figma-developer-mcp` or any other MCP package, causing the skill to silently fail on every run. Replaced with the correct tools: `get_figma_data(fileKey, nodeId, depth=2)` and `download_figma_images(fileKey, nodes, localPath)`.
-- **Figma API token verification using wrong auth header** — `verifyFigma()` in `scripts/init.js` was sending `Authorization: Bearer <token>`, which is only valid for OAuth tokens. Figma Personal Access Tokens (`figd_...`) require `X-Figma-Token: <token>`. This caused every PAT to be rejected as invalid during `ak init -a figma` even when the token was correct.
-- **Critical: `currentGate` not advancing after gate transitions** — `task-state.json` was not updating `currentGate` when the AI called `ak gate N start`, so resuming a task always restarted from the wrong gate. Added dedicated `updateTaskGateState()` and fixed `createOrActivateTaskState()` to use `Math.max()`.
-- **Duplicate `session.start` telemetry event** — `session-start.js` was calling `record()` before reading stdin, causing the event to fire twice in some hook configurations. Fixed by moving `record()` inside the `stdin.on('end')` handler.
-- **Short command aliases not resolving for telemetry** — `task` and `memory` subcommand short aliases (`t st`, `t ls`, `mem s`, etc.) were not being resolved before telemetry pre-processing, causing `unknown` in the command column. Fixed alias resolution in the pre-hook telemetry mapping.
-- **`ak telemetry log` silent on failure** — `ak telemetry log --event X` previously swallowed all errors silently (no output). Now shows ✓ on success and ⚠ with reason (`disabled`, `opted-out`, `no-url`) on skip/failure.
-- **Gate telemetry blocked by bash redirect error** — AI was appending `2>$null` (PowerShell syntax) to `ak gate` commands when following "run silently" instructions, causing bash to fail with `/usr/bin/bash: $null: ambiguous redirect`. Added explicit "do NOT append shell redirects" instruction to `gate-workflow.md` for all gate telemetry commands.
-
----
-
-## [0.0.8-beta.1] - 2026-05-14
-
-### Fixed
-
-- **Auto-commit bug — actually fixed this time.** v0.0.7 claimed to remove "all automatic `git commit` and `git add` instructions from key AI skills" but the commit (`d490dab`) only added documentation/warning lines and left the active instructions in place. This release does the real work:
-  - Removed `4. Commit your work` from [.claude/skills/subagent-driven-development/implementer-prompt.md](.claude/skills/subagent-driven-development/implementer-prompt.md) (synced from upstream which had already been fixed).
-  - Removed the `### Commit Strategy` section, `Estimated commits: [N]` line, and `MUST plan small, focused commits` rule from [custom/skills/generate-spec/SKILL.md](custom/skills/generate-spec/SKILL.md) — these were active in Gate 2 every run.
-  - Removed `Commit the design document to git` and "and commit"/"committed to" wording from [upstream/skills/brainstorming/SKILL.md](upstream/skills/brainstorming/SKILL.md).
-- **Hard guarantee via PreToolUse hook.** Added [scripts/hooks/block-git-write.js](scripts/hooks/block-git-write.js) that intercepts every Bash tool call and blocks `git commit`, `git add`, `git push`, `git tag`, `git reset`, `git rebase`, `git revert`, `git cherry-pick`, `git am`, and `git merge`. Read operations (`git status`, `git rev-parse`, `git log`, `git diff`) and worktree operations (`git worktree add/list/remove`) remain allowed. `aiflow init`/`update` auto-installs the hook into `.claude/settings.json`. Override with `AIFLOW_ALLOW_GIT_WRITE=1` for kit maintenance scripts. Defense-in-depth: even if a future skill smuggles a commit instruction, the harness blocks it before it reaches git.
-
-## [0.0.8] - 2026-05-14
-
-### Added
-
-- **Short-hand CLI Command `ak`** — Added `ak` as an ultra-short alias for `aiflow` for faster developer workflow.
-- **Command Aliases** — All major commands now have short aliases to reduce keystrokes:
-  - `init` → `i` · `use` → `u` · `prompt` → `p` · `detect` → `d` · `task` → `t` · `context` → `ctx`
-  - `checkpoint` → `cp` · `validate` → `vl` · `memory` → `mem` · `guide` → `g`
-  - `remove` → `rm` · `update` → `up` · `sync-skills` → `sync` · `doctor` → `dr` · `telemetry` → `tel`
-- **`task` sub-command aliases**: `status` → `st` · `list` → `ls` · `pause` → `p` · `switch` → `sw` · `resume` → `r` · `reset` → `rst` · `remove` → `rm` · `next` → `n`
-- **`memory` sub-command aliases**: `save` → `s` · `get` → `g` · `list` → `ls` · `search` → `sr` · `delete` → `d` · `clear` → `cl`
-- **New short options**:
-  - `-v` short flag for `--version` at root (works alongside legacy `-V`)
-  - `init --fw <types>` — long alias for `--framework`
-  - `use -F/--fast`, `-U/--full`
-  - `prompt -L/--lang`, `-d/--detail`
-  - `validate -x/--fix`
-  - `context -l/--load`
-  - `checkpoint -g/--gate`, `-s/--step`, `-n/--tokens`
-  - `guide -f/--flow`, `-c/--commands`
-  - `remove -g/--global`
-  - `update -f/--force`
-- **Enhanced Comment Loading Options** — Added granular control for fetching ticket comments in `ak use`:
-  - `-c` or `--coms` — Quick alias to load all comments.
-  - `--cid <id>` — Load a specific comment by its ID.
-  - `--clast <n>` — Load only the last N comments.
-  - `--cfrom <id>` — Load comments starting from a specific ID.
-  - `--cto <id>` — Load comments up to a specific ID.
-- **Deprecation Warning** — Added a friendly suggestion to use `ak` when the legacy `aiflow` command is invoked, preparing for future deprecation.
-
-### Fixed
-
-- **Backlog Comment Pagination** — Fixed a critical bug where comments were not loading due to an invalid `offset` parameter in the Backlog API. Switched to `minId`-based pagination to ensure reliable and complete comment fetching.
-- **Robust Comment Filtering** — Centralized comment filtering logic to effectively exclude metadata-only comments (changelogs) and focus on actual discussions.
-
-### Changed
-
-- **CLI Consistency** — Updated all command-line help descriptions and internal mappings to support the new shortened flags while maintaining backward compatibility with legacy long-form options.
-- **Documentation Alignment** — Updated all guides (QUICK_START, cli-reference) to reflect `ak` command and new short aliases.
-
----
-
-## [0.0.7] - 2026-05-08
-
-### Added
-
-- **`aiflow use --file` enhancements**:
-  - Automatic `taskId` generation from filename (up to 5 words).
-  - Full filename used as task `title`.
-  - Interactive `taskType` selection prompt during file loading for better context.
-- **`documentation` task type** — Added support for documentation-specific tasks in `aiflow use` and task detection.
-- **Automatic `task-summary.md` generation** — `aiflow task next` now generates a cumulative progress report in `plan/[ticket-id]/task-summary.md` at each gate finish.
-- **Session Continuity Instructions** — Added explicit instructions on how to switch to a fresh chat session and resume tasks (including Gate 3 sub-tasks) to both CLI output and AI skill prompts.
-- **NestJS framework support** — Added `nestjs` to the framework selector (`aiflow init`), language rule mapping (`javascript`), and AI instruction template (`custom/templates/nestjs.md`).
-- **PHP Plain (no framework) support** — Added `php-plain` as a new framework option with a dedicated AI system prompt template covering strict types, PSR-12, PDO prepared statements, security best practices, Repository/Service/Controller layering, and PHPUnit testing.
-- **`investigate-bug` skill: NestJS and PHP plain data flows** — Added framework-specific data flow traces for NestJS (`Controller → Service → Repository → DB`) and PHP Plain (`index.php → Controller → Service → Repository/PDO → DB`).
-- **Intelligent AI Instruction Synchronization** — Marker-based (`<!-- aiflow-kit-start -->`) block updates for `CLAUDE.md`, `GEMINI.md`, and `.cursorrules`.
-- **Interactive Instruction Safety** — Granular confirmation prompts for all instruction file modifications (update block, overwrite, or create new).
-- **Automated Repository Hygiene** — Generated files and folders (`.aiflow/`, `plan/`, `.claude/`, `.rules/`, `.mcp.json`, and instruction files) are now automatically managed in `.gitignore`.
-- **`aiflow sync-skills` command** — Lightweight command to synchronize Skill Registry and Instruction files without a full version upgrade.
-- **Enhanced `aiflow guide --flow`** — Now dynamically displays the `## Workflow Overview` section directly from `AIFLOW.md` for up-to-date documentation.
-- **Token savings dashboard in `aiflow doctor`** — new "Token savings" section shows RTK status and estimated 60–90% reduction on bash outputs.
-
-### Changed
-
-- **Robust Gate Detection** — Refactored `detectCurrentGate` to prioritize `task-state.json` as the source of truth for task progress.
-- **`aiflow gate approved` CLI output** — Now prints a session-refresh tip to help users maintain clean AI contexts.
-- **`aiflow update` efficiency** — Now automatically performs skill and instruction synchronization even if the version is unchanged (removes the need for `--force`).
-- **Safety First Development** — Removed all automatic `git commit` and `git add` instructions from key AI skills (`subagent-driven-development`, `using-git-worktrees`, `writing-plans`, `generate-spec`) to ensure developer-led commit management.
-- **Localized CLI** — All interactive prompts and confirmation messages translated to English for consistency.
-- **`aiflow init` RTK entry** — flag description updated to clarify RTK saves bash output tokens (60–90%).
-- **`aiflow doctor`** — RTK section merged into new "Token savings" section.
-- **README.md / QUICK_START.md / AIFLOW.md** — Updated to reflect session continuity workflow, `sync-skills` command, and improved update flow.
-
-### Fixed
-
-- **Automatic Git Commits Removed** — Fully disabled automated version control actions across the entire Skill Registry. Developers now have full manual control over staging and commits, preventing unintended history pollution during AI implementation.
-- **NestJS auto-detection** — `@nestjs/core` in `package.json` was incorrectly detected as `nodejs-express`; now correctly resolves to `nestjs`.
-- **PHP project auto-detection** — Projects with `composer.json` but no Laravel dependency now correctly auto-detect as `php-plain` instead of being skipped.
-- **Instruction Safety** — Fixed `.github/copilot-instructions.md` not being included in automated `.gitignore` rules.
-
----
-
-## [0.0.6] - 2026-04-29
-
-### Added
-
-- **Global Fast Mode (Default)** — Optimize AI efficiency by prioritizing speed and minimizing token usage.
-  - Gate 1: Fast track scan with max 1 clarifying question.
-  - Gate 3: Disable subagents by default; implement all tasks in a single session.
-  - Gate 4: Quick scan impact analysis based on git diffs; simplified review checklist.
-- **Improved `--file` loader** — `aiflow use --file` now supports plain-text files (JSON no longer required).
-  - Auto-detects Ticket ID and Title from the text content.
-- **Gate-aware Injection** — Enhanced `session-start.js` hook to inject gate-appropriate "Fast Track" instructions during task resumption.
-- **Full Mode flag** — Added `--full` flag to bypass Fast mode optimizations for complex tasks.
-- **`aiflow task` command group** — Manage multiple tasks in the same repository without losing progress.
-  - `aiflow task status`, `list`, `pause`, `switch`, `resume`.
-- **RTK token compression integration** — `aiflow init` automatically configures the RTK hook for 60–90% token savings on shell commands.
-- **`aiflow use --fast` / `--full` flags** — Control Gate 1 analysis depth per ticket.
-- **Spring Boot code examples extracted** — Java code examples moved to separate files to reduce `CLAUDE.md` size.
-
-### Changed
-
-- **Default mode** for all new tasks is now `fast` instead of `auto`.
-- **`aiflow init` improvements** — Supports multi-select framework and protects existing instruction files from being overwritten.
-- **CLAUDE.md Optimization** — Reduced Spring Boot template size by ~70%, saving ~3-5k tokens per session.
-- **Documentation Synchronization** — Fixed all documentation links on npmjs.com and updated Overview Flow in README.
-- **Automatic Task Pausing** — When loading a new ticket, the current task is automatically paused and its state is saved.
-
-### Fixed
-
-- Broken 404 documentation links on the npmjs.com page.
-
----
-
-## [0.0.4-beta.5] - 2026-04-21
-
-### Added
-
-- Created a dedicated `docs/` folder to house all developer-facing documentation.
-- Integrated AI Skill Registry into all tool templates (Claude, Cursor, Gemini, Copilot) for better skill discovery.
-
-### Changed
-
-- Moved `README.md`, `QUICK_START.md`, `AIFLOW.md`, `CHANGELOG.md`, and `IMPLEMENTATION_SUMMARY.md` into the `docs/` directory.
-- Updated `package.json` to exclude internal-only files (`CONTRIBUTING.md`, `plan.md`) from the NPM package distribution.
-- Updated `scripts/init.js` to source documentation from the new `docs/` location.
-- Updated all internal documentation links to reflect the new directory structure.
-
----
-
-## [0.0.5-beta.0] - 2026-04-23
-
-### Added
-
-- **`aiflow gate <n> <action>` command** — Called automatically by AI during gate transitions. Supports `start` and `approved` actions for gates 1-5. Options: `--ticket <id>`, `--ai-tool <tool>`.
-- **Telemetry gate logging** — Gate workflow templates now emit `aiflow gate N start/approved --ticket [id]` telemetry calls at each gate transition for usage metrics.
-- **`aiflow telemetry flush` command** — Force-sends buffered telemetry events immediately.
-
-### Changed
-
-- **`aiflow init` safe overwrite flow** — When a project already has `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, etc., `aiflow init` now prompts before overwriting:
-  - **No (default):** keeps existing file untouched; saves the aiflow template to `.aiflow/reference/<file>` for manual comparison/merge.
-  - **Yes:** backs up the existing file to `.aiflow/backup/<file>` before overwriting — nothing is permanently lost.
-- **`aiflow use --manual` pre-fill (Edit mode)** — Re-running `aiflow use --manual` when context already exists now pre-fills all fields (Ticket ID, Title, Description, Task type) with the current values; press Enter on any field to keep it unchanged.
-- **Fix TEAM_SECRET input** — Replaced `password()` prompt with `input()` using a masked hint `[Reli***!@#]`; pressing Enter retains the existing value.
-- **Fix Apps Script URL input** — Same pattern as TEAM_SECRET: masked hint `[https://script.google.com/macros/s/AKfy***xxxx/exec]`; pressing Enter retains the existing value.
-- **Downgrade dependencies for Node >=16 compatibility** — `@inquirer/prompts` downgraded from `^8.3.2` to `^3.0.0`; `commander` downgraded from `^14.0.3` to `^11.0.0`.
-- **`engines.node`** updated from `>=14.0.0` to `>=16.0.0`.
-
----
-
-## [0.0.5] - 2026-04-23
-
-### Added
-
-- **Telemetry System (MVP)**: Added anonymous usage tracking to measure command metrics and user adoption.
-  - `aiflow telemetry enable/disable/status` commands to easily opt-in or opt-out.
-  - Automatically captures environment metadata and Git email via `git config --global user.email`.
-  - Secure payload signing natively using Node `crypto` HMAC-SHA256 to ensure data authenticity.
-  - Asynchronous payload flusher to ensure zero impact on command execution time (`< 5ms` overhead).
-- Support tracking for multiple AI platforms including Cursor and Gemini via Command Execution events and the new Telemetry SDK.
-
-### Security
-
-- **Strict Privacy**: Explicitly removed all prompt content and chat history tracking to ensure 100% confidentiality of company code and PII.
-
----
-
-## [Unreleased]
-
-## [0.0.3-beta.0] - 2026-04-13
-
-### Security
-
-- Removed internal GitLab repository links and tracking information.
-- Cleaned `.npmrc` configuration.
-- Added helper scripts for beta and stable releases.
-
-## [0.0.2] - 2026-04-13
-
-### Changed
-
-- Updated package name in documentation and configuration.
-- Fixed installation guides in README and QUICK_START.
-
-## [0.0.1] - 2026-04-13 — Initial Release
-
-### Added
-
-#### CLI (`aiflow`)
-
-- `aiflow init` — scaffold AI workflow config into any project
-  (supports `--framework` spring-boot/reactjs, `--adapter` jira/backlog)
-- `aiflow use <skill>` — activate a custom skill in the current project
-- `aiflow remove` — cleanly remove `ai-flow-kit` scaffolding from a project
-- `aiflow guide` — interactive onboarding guide
-- `aiflow update` — sync upstream skill/hook updates
-- `aiflow doctor` — validate config, detect missing keys, report issues
-- `aiflow --version` — print installed version
-
-#### 5-Gate AI Workflow
-
-- **Gate 1 — AI Analyze Requirement**: Auto-starts when a ticket context exists
-  in `.aiflow/context/current.json`; outputs `plan/[ticket-id]/requirement.md`
-- **Gate 2 — Implementation Plan**: TDD plan generation, gated by `APPROVED`
-- **Gate 3 — Code Generation**: TDD-only, test-first discipline enforced
-- **Gate 4 — AI Self-Review**: Verification + impact analysis + checklist, gated by `APPROVED`
-- **Gate 5 — Peer Review & PR**: Guided PR creation via `requesting-code-review` skill
-
-#### Custom Skills (7 skills)
-
-- `read-study-requirement` — Gate 1 requirement analysis with clarifying Q&A loop
-- `generate-spec` — Gate 2 TDD implementation spec generator
-- `impact-analysis` — breaking-change and dependency impact assessment
-- `investigate-bug` — systematic bug investigation (reproduce → root cause → fix)
-- `report-customer` — customer-facing incident report generator
-- `review-plan` — Gate 4 self-review orchestrator
-- `figma-to-component` — Figma design → UI component code generator
-
-#### Multi-AI Support
-
-- **Claude Code** integration via `CLAUDE.md` + `.claude/` directory structure
-- **Gemini CLI** integration via `GEMINI.md`
-- **GitHub Copilot** integration via agents config
-- Superpowers skill library bundled as `upstream/` (pinned to v5.0.5)
-
-#### Project Templates
-
-- `AIFLOW.md` — team workflow reference document
-- `QUICK_START.md` — 5-minute setup guide
-- `.aiflowrc.json.example` — configuration file reference
-
-### Architecture Notes
-
-- Stateless per-ticket design — no persistent memory across sessions (planned: v0.1.x)
-- Manual skill sync model via `aiflow use` (managed `aiflow skill` CLI planned: v0.1.x)
-- Spring Boot (Java 17+) used as the reference framework in `CLAUDE.md` coding rules
-
----
-
-## How to upgrade
-
-```bash
-npm install -g @relipa/ai-flow-kit@latest
-aiflow --version
-```
-
-After upgrading, run `aiflow update` inside your project to sync the latest skills and hooks:
-
-```bash
-cd your-project
-aiflow update
-```
+# Changelog
+
+All notable changes to **ai-flow-kit** will be documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.1] - 2026-06-08
+
+### Added
+
+- **Ubuntu / Linux clipboard support in `ak prompt`** — `ak prompt` now copies to the clipboard on native Linux. It auto-detects the display server (Wayland → `wl-copy`, X11 → `xclip` → `xsel`) and the package manager (`apt-get` / `dnf` / `pacman` / `zypper`). When no clipboard tool is installed it prints a clear warning (`⚠ Clipboard tool not found (need: xclip)`), shows the exact install command, and offers to install it via `sudo` then retries the copy. If the user declines or no package manager is found, it falls back to printing the full prompt for manual copy. Previously the command silently failed on Ubuntu when neither `xclip` nor `xsel` was present.
+- **`figma-to-component`: image detection & export** — The skill now scans the Figma node tree for image nodes (`fills[].type === "IMAGE"`, `VECTOR`/`BOOLEAN_OPERATION`, complex non-CSS groups), exports them via `download_figma_images` into `public/assets/figma/`, and records an `imageMap`. Generated components render those nodes with `<Image>` (Next.js) / `<img>` (React/Vue) instead of CSS `background-image`.
+- **`figma-to-component`: MCP availability pre-check (Step 0)** — The skill now verifies `mcp__figma__get_figma_data` / `mcp__figma__download_figma_images` are connected before running, and stops with setup instructions (`aiflow init -a figma` / `-a figma-desktop`) instead of guessing design values from the URL.
+- **`figma-to-component`: CSS tooling detection + design tokens** — Detection now branches on the project's styling approach (Tailwind / CSS Modules / styled-components / vanilla CSS) instead of hardcoding Tailwind, and prefers mapping Figma Styles/Variables to existing project tokens (Tailwind theme keys or CSS custom properties), falling back to arbitrary values only when no token matches.
+- **`figma-to-component`: troubleshooting table** — Added a troubleshooting section covering MCP-not-connected, `403`/token rejected, request timeout (lower `depth`), `404` node-id, empty fills, and unsupported `download_figma_images`.
+
+### Fixed
+
+- **Critical: `figma-to-component` source/installed divergence** — The source skill (`custom/skills/figma-to-component/SKILL.md`) still referenced the non-existent tool names `figma_get_file_nodes` / `figma_get_file_styles` / `figma_get_image` and only had 2-tier framework detection, while the installed `.claude/` copy had been fixed in 0.0.9. The next `aiflow init` / `sync-skills` would have overwritten the working copy with the broken source — re-introducing the 0.0.9 bug. Both copies are now synced to a single canonical version: correct tool names (`get_figma_data` / `download_figma_images`), 4-tier framework detection (App Router / React / Vue / Angular), and the image-export step.
+
+---
+
+## [0.1.0] - 2026-05-28
+
+### Added
+
+- **Multi-target `ak use`** — `ak use` now accepts variadic targets so multiple sources can be loaded in a single call. The first target becomes the primary context (drives Gate 1); the rest are appended to `current.json` as `supplementaryContext[]`. Targets can be ticket IDs, Backlog/Jira URLs, or local files.
+  ```bash
+  ak use PROJ-33 PROJ-10 docs/arch.md
+  # PROJ-33 = primary, PROJ-10 + docs/arch.md = supplementary
+  ```
+  Backward compatible: `ak use PROJ-33` (single target) behaves exactly as before.
+- **Auto link resolution** — When the primary ticket's description contains Backlog/Jira URLs, `ak use` now auto-fetches them and appends to `supplementaryContext[]`. AI no longer misses linked context. Capped at **5 auto-resolved links per `use`** to keep loads fast; per-link errors are caught and logged without aborting the command.
+- **Comment-aware link resolution** — Comment URLs are resolved to that **single comment** instead of fetching the whole ticket. Recognised patterns:
+  - Backlog: `https://*.backlog.com/view/PROJ-10#comment-456`
+  - Jira: `https://*.atlassian.net/browse/PROJ-10?focusedCommentId=456`
+- **`ak fetch-links <url>` command** — Standalone command that fetches a single Backlog/Jira URL and prints a `SupplementaryContext` JSON object to stdout. Used by the `read-study-requirement` skill at runtime when AI encounters a link in the ticket description that wasn't already resolved at `use` time.
+  ```bash
+  ak fetch-links "https://company.backlog.com/view/PROJ-10#comment-456"
+  ```
+- **`supplementaryContext[]` schema in `current.json`** — New top-level array; each item has shape `{ sourceType: 'ticket'|'comment'|'file'|'text', sourceUrl?, sourcePath?, ticketId?, commentId?, title?, description?, content?, author?, date? }`. Persisted across sessions and consumed by the SessionStart hook.
+- **SessionStart hook renders supplementary block** — `scripts/hooks/session-start.js` now emits a `**Supplementary Context (N source(s)):**` section in the AI context prompt, one line per item, content truncated at 1000 chars to keep token cost bounded.
+- **`read-study-requirement` skill integrates supplementary context** — Gate 1 instruction file (custom + installed `.claude/skills/`) now has an explicit step to read `supplementaryContext[]` and use `ak fetch-links` for any unresolved links found while analysing the ticket.
+- **`scripts/link-resolver.js` module** — New CommonJS module that owns all URL classification and HTTPS fetching for Backlog/Jira. Exports: `classifyLink`, `scanLinks`, `fetchBacklogTicket`, `fetchBacklogComment`, `fetchJiraTicket`, `fetchJiraComment`, `fetchLink`, `resolveLinks`. Accepts credentials as parameters to keep `use.js` free of circular imports.
+- **Jest test suite** — Added Jest 30 as a dev dependency with `testMatch: ["<rootDir>/tests/**/*.test.js"]` to scope discovery to project tests (skips `upstream/tests/`). Suite includes `tests/smoke.test.js` and 20 unit tests in `tests/link-resolver.test.js` covering URL classification, scan, dedup, per-adapter fetch paths, and `resolveLinks` error isolation.
+
+### Changed
+
+- **`use.js` exports as named const** — `module.exports` shifted from anonymous function to `useCommand` with a `loadCredentials` property attached, so other modules (CLI `fetch-links` handler) can reuse credential loading without re-implementing it. External call shape (`useCommand(targets, options)`) unchanged for backward compatibility.
+
+---
+
+## [0.0.9] - 2026-05-25
+
+### Added
+
+- **`figma-desktop` adapter** — New MCP preset using the official `@figma/mcp-server` package (Figma Inc.). Requires Figma Desktop app installed and open. No API token needed — authenticates via Desktop session. Run `ak init -a figma-desktop` to set up. See [`custom/mcp-presets/figma-desktop.json`](../../custom/mcp-presets/figma-desktop.json).
+- **Next.js App Router support in `figma-to-component` skill** — Detects App Router projects (via `nextjs-app-router` in `CLAUDE.md` or presence of `app/` directory). Defaults to Server Component (`export default async function`); adds `'use client'` directive only when the design has interactive states (hover, click handlers, form inputs).
+- **Angular support in `figma-to-component` skill** — Detects Angular projects (via `angular` in `CLAUDE.md` or presence of `angular.json`). Generates standalone `@Component` class with `@Input() className` and computed `hostClasses` getter. Uses Tailwind if `tailwind.config.*` exists, otherwise CSS-in-component.
+- **4-tier framework detection in `figma-to-component` skill** — Detection order: (1) `CLAUDE.md` identifier → (2) project file scan (`app/` dir, `angular.json`, `nuxt.config.*`) → (3) fallback to Next.js/React. Previously only supported React and Vue.
+- **Figma workflow guide** — New developer guide at [`docs/common/workflows/figma.md`](figma.md) covering prerequisites (REST API vs Desktop), how to get node URLs, trigger commands, expected output format, review checklist, and troubleshooting table.
+- **MCP presets documentation** — Added full Figma REST API and Figma Desktop sections to [`custom/mcp-presets/README.md`](../../custom/mcp-presets/README.md), including a side-by-side comparison table.
+- **`ak gate N start|approved` auto-syncs task state** — Calling `ak gate 1 start --ticket PROJ-33` now automatically advances `currentGate` in `task-state.json`, removing the need to always call `ak task next` for gate tracking. `approved` records the approval timestamp and advances to the next gate. Uses `Math.max()` guard to never regress gate progress.
+- **Session telemetry enrichment** — `session.start` now captures the active AI model name and user email from config. `session.stop` records model, input/output token counts, and a prompt summary extracted from the session transcript (`transcript_path` in hookData).
+- **`project-conventions.md`** — New mandatory override file at `custom/rules/project-conventions.md`. Enforces that Gate 2 plans are always saved to `plan/[ticket-id]/plan.md` (overriding the skill default `docs/superpowers/plans/`). Includes a checklist and path table for all Gate outputs.
+- **Gate workflow: explicit plan output path** — Gate 2 instruction in `gate-workflow.md` now explicitly states that the plan must be saved to `plan/[ticket-id]/plan.md`, with a note that the `writing-plans` skill default path is overridden.
+- **WSL clipboard support in `ak prompt`** — `ak prompt` now correctly copies output to the Windows clipboard when running inside WSL using `powershell.exe Set-Clipboard`. Previously fell through to `xclip`/`xsel` which are unavailable on WSL without extra setup.
+- **`appscript.js`** — Google Apps Script source for the self-hosted telemetry backend. Receives HMAC-signed events from the `ak` CLI, validates them, and appends rows to Google Sheets.
+- **Telemetry `record()` returns result object** — `record()` now returns `{ok: true}` on success or `{ok: false, reason, error}` on failure, enabling `ak gate` and `ak telemetry log` to display ✓ / ⚠ feedback per event.
+- **`ak init` remembers previous framework selection** — Re-running `ak init` in an already-configured project now pre-selects the previously chosen frameworks (read from `.aiflow/state.json`) instead of falling back to auto-detection. A "Previously selected: ..." hint is shown above the checkbox list.
+
+### Fixed
+
+- **Critical: `figma-to-component` skill used non-existent tool names** — The skill referenced `figma_get_file_nodes`, `figma_get_file_styles`, `figma_get_file_components`, and `figma_get_image` — none of which exist in `figma-developer-mcp` or any other MCP package, causing the skill to silently fail on every run. Replaced with the correct tools: `get_figma_data(fileKey, nodeId, depth=2)` and `download_figma_images(fileKey, nodes, localPath)`.
+- **Figma API token verification using wrong auth header** — `verifyFigma()` in `scripts/init.js` was sending `Authorization: Bearer <token>`, which is only valid for OAuth tokens. Figma Personal Access Tokens (`figd_...`) require `X-Figma-Token: <token>`. This caused every PAT to be rejected as invalid during `ak init -a figma` even when the token was correct.
+- **Critical: `currentGate` not advancing after gate transitions** — `task-state.json` was not updating `currentGate` when the AI called `ak gate N start`, so resuming a task always restarted from the wrong gate. Added dedicated `updateTaskGateState()` and fixed `createOrActivateTaskState()` to use `Math.max()`.
+- **Duplicate `session.start` telemetry event** — `session-start.js` was calling `record()` before reading stdin, causing the event to fire twice in some hook configurations. Fixed by moving `record()` inside the `stdin.on('end')` handler.
+- **Short command aliases not resolving for telemetry** — `task` and `memory` subcommand short aliases (`t st`, `t ls`, `mem s`, etc.) were not being resolved before telemetry pre-processing, causing `unknown` in the command column. Fixed alias resolution in the pre-hook telemetry mapping.
+- **`ak telemetry log` silent on failure** — `ak telemetry log --event X` previously swallowed all errors silently (no output). Now shows ✓ on success and ⚠ with reason (`disabled`, `opted-out`, `no-url`) on skip/failure.
+- **Gate telemetry blocked by bash redirect error** — AI was appending `2>$null` (PowerShell syntax) to `ak gate` commands when following "run silently" instructions, causing bash to fail with `/usr/bin/bash: $null: ambiguous redirect`. Added explicit "do NOT append shell redirects" instruction to `gate-workflow.md` for all gate telemetry commands.
+
+---
+
+## [0.0.8-beta.1] - 2026-05-14
+
+### Fixed
+
+- **Auto-commit bug — actually fixed this time.** v0.0.7 claimed to remove "all automatic `git commit` and `git add` instructions from key AI skills" but the commit (`d490dab`) only added documentation/warning lines and left the active instructions in place. This release does the real work:
+  - Removed `4. Commit your work` from [.claude/skills/subagent-driven-development/implementer-prompt.md](.claude/skills/subagent-driven-development/implementer-prompt.md) (synced from upstream which had already been fixed).
+  - Removed the `### Commit Strategy` section, `Estimated commits: [N]` line, and `MUST plan small, focused commits` rule from [custom/skills/generate-spec/SKILL.md](custom/skills/generate-spec/SKILL.md) — these were active in Gate 2 every run.
+  - Removed `Commit the design document to git` and "and commit"/"committed to" wording from [upstream/skills/brainstorming/SKILL.md](upstream/skills/brainstorming/SKILL.md).
+- **Hard guarantee via PreToolUse hook.** Added [scripts/hooks/block-git-write.js](scripts/hooks/block-git-write.js) that intercepts every Bash tool call and blocks `git commit`, `git add`, `git push`, `git tag`, `git reset`, `git rebase`, `git revert`, `git cherry-pick`, `git am`, and `git merge`. Read operations (`git status`, `git rev-parse`, `git log`, `git diff`) and worktree operations (`git worktree add/list/remove`) remain allowed. `aiflow init`/`update` auto-installs the hook into `.claude/settings.json`. Override with `AIFLOW_ALLOW_GIT_WRITE=1` for kit maintenance scripts. Defense-in-depth: even if a future skill smuggles a commit instruction, the harness blocks it before it reaches git.
+
+## [0.0.8] - 2026-05-14
+
+### Added
+
+- **Short-hand CLI Command `ak`** — Added `ak` as an ultra-short alias for `aiflow` for faster developer workflow.
+- **Command Aliases** — All major commands now have short aliases to reduce keystrokes:
+  - `init` → `i` · `use` → `u` · `prompt` → `p` · `detect` → `d` · `task` → `t` · `context` → `ctx`
+  - `checkpoint` → `cp` · `validate` → `vl` · `memory` → `mem` · `guide` → `g`
+  - `remove` → `rm` · `update` → `up` · `sync-skills` → `sync` · `doctor` → `dr` · `telemetry` → `tel`
+- **`task` sub-command aliases**: `status` → `st` · `list` → `ls` · `pause` → `p` · `switch` → `sw` · `resume` → `r` · `reset` → `rst` · `remove` → `rm` · `next` → `n`
+- **`memory` sub-command aliases**: `save` → `s` · `get` → `g` · `list` → `ls` · `search` → `sr` · `delete` → `d` · `clear` → `cl`
+- **New short options**:
+  - `-v` short flag for `--version` at root (works alongside legacy `-V`)
+  - `init --fw <types>` — long alias for `--framework`
+  - `use -F/--fast`, `-U/--full`
+  - `prompt -L/--lang`, `-d/--detail`
+  - `validate -x/--fix`
+  - `context -l/--load`
+  - `checkpoint -g/--gate`, `-s/--step`, `-n/--tokens`
+  - `guide -f/--flow`, `-c/--commands`
+  - `remove -g/--global`
+  - `update -f/--force`
+- **Enhanced Comment Loading Options** — Added granular control for fetching ticket comments in `ak use`:
+  - `-c` or `--coms` — Quick alias to load all comments.
+  - `--cid <id>` — Load a specific comment by its ID.
+  - `--clast <n>` — Load only the last N comments.
+  - `--cfrom <id>` — Load comments starting from a specific ID.
+  - `--cto <id>` — Load comments up to a specific ID.
+- **Deprecation Warning** — Added a friendly suggestion to use `ak` when the legacy `aiflow` command is invoked, preparing for future deprecation.
+
+### Fixed
+
+- **Backlog Comment Pagination** — Fixed a critical bug where comments were not loading due to an invalid `offset` parameter in the Backlog API. Switched to `minId`-based pagination to ensure reliable and complete comment fetching.
+- **Robust Comment Filtering** — Centralized comment filtering logic to effectively exclude metadata-only comments (changelogs) and focus on actual discussions.
+
+### Changed
+
+- **CLI Consistency** — Updated all command-line help descriptions and internal mappings to support the new shortened flags while maintaining backward compatibility with legacy long-form options.
+- **Documentation Alignment** — Updated all guides (QUICK_START, cli-reference) to reflect `ak` command and new short aliases.
+
+---
+
+## [0.0.7] - 2026-05-08
+
+### Added
+
+- **`aiflow use --file` enhancements**:
+  - Automatic `taskId` generation from filename (up to 5 words).
+  - Full filename used as task `title`.
+  - Interactive `taskType` selection prompt during file loading for better context.
+- **`documentation` task type** — Added support for documentation-specific tasks in `aiflow use` and task detection.
+- **Automatic `task-summary.md` generation** — `aiflow task next` now generates a cumulative progress report in `plan/[ticket-id]/task-summary.md` at each gate finish.
+- **Session Continuity Instructions** — Added explicit instructions on how to switch to a fresh chat session and resume tasks (including Gate 3 sub-tasks) to both CLI output and AI skill prompts.
+- **NestJS framework support** — Added `nestjs` to the framework selector (`aiflow init`), language rule mapping (`javascript`), and AI instruction template (`custom/templates/nestjs.md`).
+- **PHP Plain (no framework) support** — Added `php-plain` as a new framework option with a dedicated AI system prompt template covering strict types, PSR-12, PDO prepared statements, security best practices, Repository/Service/Controller layering, and PHPUnit testing.
+- **`investigate-bug` skill: NestJS and PHP plain data flows** — Added framework-specific data flow traces for NestJS (`Controller → Service → Repository → DB`) and PHP Plain (`index.php → Controller → Service → Repository/PDO → DB`).
+- **Intelligent AI Instruction Synchronization** — Marker-based (`<!-- aiflow-kit-start -->`) block updates for `CLAUDE.md`, `GEMINI.md`, and `.cursorrules`.
+- **Interactive Instruction Safety** — Granular confirmation prompts for all instruction file modifications (update block, overwrite, or create new).
+- **Automated Repository Hygiene** — Generated files and folders (`.aiflow/`, `plan/`, `.claude/`, `.rules/`, `.mcp.json`, and instruction files) are now automatically managed in `.gitignore`.
+- **`aiflow sync-skills` command** — Lightweight command to synchronize Skill Registry and Instruction files without a full version upgrade.
+- **Enhanced `aiflow guide --flow`** — Now dynamically displays the `## Workflow Overview` section directly from `AIFLOW.md` for up-to-date documentation.
+- **Token savings dashboard in `aiflow doctor`** — new "Token savings" section shows RTK status and estimated 60–90% reduction on bash outputs.
+
+### Changed
+
+- **Robust Gate Detection** — Refactored `detectCurrentGate` to prioritize `task-state.json` as the source of truth for task progress.
+- **`aiflow gate approved` CLI output** — Now prints a session-refresh tip to help users maintain clean AI contexts.
+- **`aiflow update` efficiency** — Now automatically performs skill and instruction synchronization even if the version is unchanged (removes the need for `--force`).
+- **Safety First Development** — Removed all automatic `git commit` and `git add` instructions from key AI skills (`subagent-driven-development`, `using-git-worktrees`, `writing-plans`, `generate-spec`) to ensure developer-led commit management.
+- **Localized CLI** — All interactive prompts and confirmation messages translated to English for consistency.
+- **`aiflow init` RTK entry** — flag description updated to clarify RTK saves bash output tokens (60–90%).
+- **`aiflow doctor`** — RTK section merged into new "Token savings" section.
+- **README.md / QUICK_START.md / AIFLOW.md** — Updated to reflect session continuity workflow, `sync-skills` command, and improved update flow.
+
+### Fixed
+
+- **Automatic Git Commits Removed** — Fully disabled automated version control actions across the entire Skill Registry. Developers now have full manual control over staging and commits, preventing unintended history pollution during AI implementation.
+- **NestJS auto-detection** — `@nestjs/core` in `package.json` was incorrectly detected as `nodejs-express`; now correctly resolves to `nestjs`.
+- **PHP project auto-detection** — Projects with `composer.json` but no Laravel dependency now correctly auto-detect as `php-plain` instead of being skipped.
+- **Instruction Safety** — Fixed `.github/copilot-instructions.md` not being included in automated `.gitignore` rules.
+
+---
+
+## [0.0.6] - 2026-04-29
+
+### Added
+
+- **Global Fast Mode (Default)** — Optimize AI efficiency by prioritizing speed and minimizing token usage.
+  - Gate 1: Fast track scan with max 1 clarifying question.
+  - Gate 3: Disable subagents by default; implement all tasks in a single session.
+  - Gate 4: Quick scan impact analysis based on git diffs; simplified review checklist.
+- **Improved `--file` loader** — `aiflow use --file` now supports plain-text files (JSON no longer required).
+  - Auto-detects Ticket ID and Title from the text content.
+- **Gate-aware Injection** — Enhanced `session-start.js` hook to inject gate-appropriate "Fast Track" instructions during task resumption.
+- **Full Mode flag** — Added `--full` flag to bypass Fast mode optimizations for complex tasks.
+- **`aiflow task` command group** — Manage multiple tasks in the same repository without losing progress.
+  - `aiflow task status`, `list`, `pause`, `switch`, `resume`.
+- **RTK token compression integration** — `aiflow init` automatically configures the RTK hook for 60–90% token savings on shell commands.
+- **`aiflow use --fast` / `--full` flags** — Control Gate 1 analysis depth per ticket.
+- **Spring Boot code examples extracted** — Java code examples moved to separate files to reduce `CLAUDE.md` size.
+
+### Changed
+
+- **Default mode** for all new tasks is now `fast` instead of `auto`.
+- **`aiflow init` improvements** — Supports multi-select framework and protects existing instruction files from being overwritten.
+- **CLAUDE.md Optimization** — Reduced Spring Boot template size by ~70%, saving ~3-5k tokens per session.
+- **Documentation Synchronization** — Fixed all documentation links on npmjs.com and updated Overview Flow in README.
+- **Automatic Task Pausing** — When loading a new ticket, the current task is automatically paused and its state is saved.
+
+### Fixed
+
+- Broken 404 documentation links on the npmjs.com page.
+
+---
+
+## [0.0.4-beta.5] - 2026-04-21
+
+### Added
+
+- Created a dedicated `docs/` folder to house all developer-facing documentation.
+- Integrated AI Skill Registry into all tool templates (Claude, Cursor, Gemini, Copilot) for better skill discovery.
+
+### Changed
+
+- Moved `README.md`, `QUICK_START.md`, `AIFLOW.md`, `CHANGELOG.md`, and `IMPLEMENTATION_SUMMARY.md` into the `docs/` directory.
+- Updated `package.json` to exclude internal-only files (`CONTRIBUTING.md`, `plan.md`) from the NPM package distribution.
+- Updated `scripts/init.js` to source documentation from the new `docs/` location.
+- Updated all internal documentation links to reflect the new directory structure.
+
+---
+
+## [0.0.5-beta.0] - 2026-04-23
+
+### Added
+
+- **`aiflow gate <n> <action>` command** — Called automatically by AI during gate transitions. Supports `start` and `approved` actions for gates 1-5. Options: `--ticket <id>`, `--ai-tool <tool>`.
+- **Telemetry gate logging** — Gate workflow templates now emit `aiflow gate N start/approved --ticket [id]` telemetry calls at each gate transition for usage metrics.
+- **`aiflow telemetry flush` command** — Force-sends buffered telemetry events immediately.
+
+### Changed
+
+- **`aiflow init` safe overwrite flow** — When a project already has `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, etc., `aiflow init` now prompts before overwriting:
+  - **No (default):** keeps existing file untouched; saves the aiflow template to `.aiflow/reference/<file>` for manual comparison/merge.
+  - **Yes:** backs up the existing file to `.aiflow/backup/<file>` before overwriting — nothing is permanently lost.
+- **`aiflow use --manual` pre-fill (Edit mode)** — Re-running `aiflow use --manual` when context already exists now pre-fills all fields (Ticket ID, Title, Description, Task type) with the current values; press Enter on any field to keep it unchanged.
+- **Fix TEAM_SECRET input** — Replaced `password()` prompt with `input()` using a masked hint `[Reli***!@#]`; pressing Enter retains the existing value.
+- **Fix Apps Script URL input** — Same pattern as TEAM_SECRET: masked hint `[https://script.google.com/macros/s/AKfy***xxxx/exec]`; pressing Enter retains the existing value.
+- **Downgrade dependencies for Node >=16 compatibility** — `@inquirer/prompts` downgraded from `^8.3.2` to `^3.0.0`; `commander` downgraded from `^14.0.3` to `^11.0.0`.
+- **`engines.node`** updated from `>=14.0.0` to `>=16.0.0`.
+
+---
+
+## [0.0.5] - 2026-04-23
+
+### Added
+
+- **Telemetry System (MVP)**: Added anonymous usage tracking to measure command metrics and user adoption.
+  - `aiflow telemetry enable/disable/status` commands to easily opt-in or opt-out.
+  - Automatically captures environment metadata and Git email via `git config --global user.email`.
+  - Secure payload signing natively using Node `crypto` HMAC-SHA256 to ensure data authenticity.
+  - Asynchronous payload flusher to ensure zero impact on command execution time (`< 5ms` overhead).
+- Support tracking for multiple AI platforms including Cursor and Gemini via Command Execution events and the new Telemetry SDK.
+
+### Security
+
+- **Strict Privacy**: Explicitly removed all prompt content and chat history tracking to ensure 100% confidentiality of company code and PII.
+
+---
+
+## [Unreleased]
+
+## [0.0.3-beta.0] - 2026-04-13
+
+### Security
+
+- Removed internal GitLab repository links and tracking information.
+- Cleaned `.npmrc` configuration.
+- Added helper scripts for beta and stable releases.
+
+## [0.0.2] - 2026-04-13
+
+### Changed
+
+- Updated package name in documentation and configuration.
+- Fixed installation guides in README and QUICK_START.
+
+## [0.0.1] - 2026-04-13 — Initial Release
+
+### Added
+
+#### CLI (`aiflow`)
+
+- `aiflow init` — scaffold AI workflow config into any project
+  (supports `--framework` spring-boot/reactjs, `--adapter` jira/backlog)
+- `aiflow use <skill>` — activate a custom skill in the current project
+- `aiflow remove` — cleanly remove `ai-flow-kit` scaffolding from a project
+- `aiflow guide` — interactive onboarding guide
+- `aiflow update` — sync upstream skill/hook updates
+- `aiflow doctor` — validate config, detect missing keys, report issues
+- `aiflow --version` — print installed version
+
+#### 5-Gate AI Workflow
+
+- **Gate 1 — AI Analyze Requirement**: Auto-starts when a ticket context exists
+  in `.aiflow/context/current.json`; outputs `plan/[ticket-id]/requirement.md`
+- **Gate 2 — Implementation Plan**: TDD plan generation, gated by `APPROVED`
+- **Gate 3 — Code Generation**: TDD-only, test-first discipline enforced
+- **Gate 4 — AI Self-Review**: Verification + impact analysis + checklist, gated by `APPROVED`
+- **Gate 5 — Peer Review & PR**: Guided PR creation via `requesting-code-review` skill
+
+#### Custom Skills (7 skills)
+
+- `read-study-requirement` — Gate 1 requirement analysis with clarifying Q&A loop
+- `generate-spec` — Gate 2 TDD implementation spec generator
+- `impact-analysis` — breaking-change and dependency impact assessment
+- `investigate-bug` — systematic bug investigation (reproduce → root cause → fix)
+- `report-customer` — customer-facing incident report generator
+- `review-plan` — Gate 4 self-review orchestrator
+- `figma-to-component` — Figma design → UI component code generator
+
+#### Multi-AI Support
+
+- **Claude Code** integration via `CLAUDE.md` + `.claude/` directory structure
+- **Gemini CLI** integration via `GEMINI.md`
+- **GitHub Copilot** integration via agents config
+- Superpowers skill library bundled as `upstream/` (pinned to v5.0.5)
+
+#### Project Templates
+
+- `AIFLOW.md` — team workflow reference document
+- `QUICK_START.md` — 5-minute setup guide
+- `.aiflowrc.json.example` — configuration file reference
+
+### Architecture Notes
+
+- Stateless per-ticket design — no persistent memory across sessions (planned: v0.1.x)
+- Manual skill sync model via `aiflow use` (managed `aiflow skill` CLI planned: v0.1.x)
+- Spring Boot (Java 17+) used as the reference framework in `CLAUDE.md` coding rules
+
+---
+
+## How to upgrade
+
+```bash
+npm install -g @relipa/ai-flow-kit@latest
+aiflow --version
+```
+
+After upgrading, run `aiflow update` inside your project to sync the latest skills and hooks:
+
+```bash
+cd your-project
+aiflow update
+```