@relipa/ai-flow-kit 0.1.0 → 0.1.1-beta.0

package/docs/common/cli-reference.md

@@ -1,657 +1,657 @@
-# CLI Reference
-
-Complete reference for all `ak` / `aiflow` commands.
-
-> **Short alias:** `ak` is the preferred short form of `aiflow`. Every command also has a short alias shown in the format `command|alias`.
-
-## Commands Overview
-
-```bash
-ak --help                        # Show all commands
-ak <command> --help              # Show command help
-ak <alias> --help                # Also works with aliases
-```
-
-### Quick Alias Reference
-
-| Full command | Short | Full command | Short |
-|---|---|---|---|
-| `ak init` | `ak i` | `ak use` | `ak u` |
-| `ak prompt` | `ak p` | `ak detect` | `ak d` |
-| `ak task` | `ak t` | `ak context` | `ak ctx` |
-| `ak checkpoint` | `ak cp` | `ak validate` | `ak vl` |
-| `ak memory` | `ak mem` | `ak guide` | `ak g` |
-| `ak remove` | `ak rm` | `ak update` | `ak up` |
-| `ak sync-skills` | `ak sync` | `ak doctor` | `ak dr` |
-| `ak telemetry` | `ak tel` | | |
-
-| `task` sub-command | Short | `memory` sub-command | Short |
-|---|---|---|---|
-| `ak t status` | `ak t st` | `ak mem save` | `ak mem s` |
-| `ak t list` | `ak t ls` | `ak mem get` | `ak mem g` |
-| `ak t pause` | `ak t p` | `ak mem list` | `ak mem ls` |
-| `ak t switch` | `ak t sw` | `ak mem search` | `ak mem sr` |
-| `ak t resume` | `ak t r` | `ak mem delete` | `ak mem d` |
-| `ak t reset` | `ak t rst` | `ak mem clear` | `ak mem cl` |
-| `ak t remove` | `ak t rm` | | |
-| `ak t next` | `ak t n` | | |
-
-## init
-
-Initialize AI Flow Kit in your project.
-
-```bash
-ak init                                      # basic initialization
-ak init -f laravel                           # with framework  (--framework)
-ak init -a jira                              # with adapter  (--adapter)
-ak init -f laravel -a jira                   # full setup
-ak init -f spring-boot --with-rtk            # enable RTK compression
-ak init --no-rtk                             # skip RTK setup
-```
-
-**Options:**
-- `-f, --framework <types>` (alias: `--fw`) — Framework templates, comma-separated (e.g. `spring-boot,reactjs`)
-- `-a, --adapter <types>` — MCP adapters (jira, backlog, google-sheets)
-- `-e, --env <types>` — AI tools to configure (cursor, gemini, copilot, generic). Default excludes `generic`.
-- `--with-rtk` — Force enable RTK token compression hook
-- `--no-rtk` — Skip RTK setup even if RTK is detected
-
-**What it does:**
-1. Creates `.claude/skills/` with all available skills
-2. Creates `.rules/` with team rules (including `java/spring-boot-examples.md` for Spring Boot projects)
-3. Creates `.aiflow/` with version tracking
-4. Sets up framework instruction file (`CLAUDE.md`, `.cursorrules`, etc.):
-   - **File already exists** → saves aiflow template to `.aiflow/reference/<file>` for comparison. Your existing file is untouched — you own it.
-   - **File does not exist** → creates it in the project root.
-5. Optionally configures MCP adapter
-
-> **Note:** `CLAUDE.md` and other AI instruction files are project files — commit them to your repo. Run `aiflow init` once to generate them, then maintain them yourself. On subsequent `aiflow init` runs they will not be overwritten.
-
-**Example:**
-```bash
-$ aiflow init --framework laravel --adapter jira
-Initializing ai-flow-kit (v1.0.0)...
-✓ Copied skills to .claude/skills
-✓ Copied rules to .rules
-✓ Set up CLAUDE.md for framework: laravel
-✓ Updated MCP configuration for jira
-
-✨ Initialized AI Flow Kit successfully!
-```
-
-## use
-
-Load context from one or more tickets, files, or manual entry. **Accepts variadic targets** (v0.1.0+) — the first target is the primary context (drives Gate 1); any additional targets are appended as `supplementaryContext[]`.
-
-```bash
-ak use JIRA-123                              # single target — load from Jira
-ak use BACKLOG-456                           # single target — load from Backlog
-ak use PROJ-33 PROJ-10 docs/arch.md          # multi-target — primary + supplementary (v0.1.0+)
-ak use BACKLOG-456 -F                        # fast mode  (--fast)
-ak use BACKLOG-456 -U                        # full mode  (--full)
-ak use -m                                    # manual entry  (--manual)
-ak use -f path/to/context.json               # load from file  (--file)
-ak use BACKLOG-456 -c                        # load with all comments  (--coms)
-ak use BACKLOG-456 --clast 5                 # last 5 comments
-ak use BACKLOG-456 --cid 42                  # specific comment
-ak use 1.0.0                                 # switch between versions
-```
-
-**Arguments:**
-- `[targets...]` — One or more targets. Each target can be a ticket ID (`PROJ-33`), a Backlog/Jira URL, or a local file path. First target = primary; rest = supplementary.
-
-**Options:**
-- `-m, --manual` — Manual context entry
-- `-f, --file <path>` — Load from file (JSON or plain text)
-- `-s, --save <name>` — Save as named context
-- `-c, --coms` — Load all comments (alias for `--with-comments`)
-- `--with-comments` — Include all ticket comments
-- `--cid <id>` — Load a specific comment by ID
-- `--clast <n>` — Only fetch last N comments
-- `--cfrom <id>` — Fetch comments from ID N onward
-- `--cto <id>` — Fetch comments up to ID N
-- `-F, --fast` — Fast mode: AI skips Q&A, lite 3-section requirement doc (< 5 min Gate 1)
-- `-U, --full` — Full mode: force complete Gate 1 analysis with Q&A
-
-**Auto link resolution (v0.1.0+):** When the primary ticket description contains Backlog/Jira URLs, `ak use` auto-fetches them and appends to `supplementaryContext[]`. Comment URLs (`#comment-456` or `?focusedCommentId=456`) resolve to **that single comment only**. Capped at 5 auto-resolved links per `use`; per-link errors are logged without aborting the command.
-
-**`supplementaryContext[]` schema** (persisted in `.aiflow/context/current.json`):
-
-```json
-{
-  "sourceType": "ticket | comment | file | text",
-  "sourceUrl": "https://...",
-  "sourcePath": "docs/arch.md",
-  "ticketId": "PROJ-10",
-  "commentId": "456",
-  "title": "...",
-  "description": "...",
-  "content": "...",
-  "author": "...",
-  "date": "..."
-}
-```
-
-**What it does:**
-1. Loads the first target as primary context (fetches from MCP adapter / file / manual entry)
-2. Loads each remaining target as a supplementary item
-3. Scans the primary description for Backlog/Jira URLs and auto-resolves them
-4. Saves the merged context (including `mode` and `supplementaryContext[]`) to `.aiflow/context/current.json`
-5. Updates state tracking
-
-**Example:**
-```bash
-$ aiflow use JIRA-123
-Fetching context from Jira...
-✓ Title: Fix payment processing error
-✓ Description: 2000+ words pulled
-✓ Acceptance criteria: 3 items
-✓ Saved to .aiflow/context/current.json
-
-Ready to prompt! Run: aiflow prompt bug-fix
-
-$ aiflow use PROJ-33 PROJ-10 docs/arch.md
-✓ Loaded primary: PROJ-33
-✓ Supplementary: PROJ-10 (ticket), docs/arch.md (file)
-✓ Auto-resolved 2 link(s) from description
-```
-
-## fetch-links
-
-Fetch a single Backlog/Jira URL and print a `SupplementaryContext` JSON object to stdout. Intended for AI runtime use inside the `read-study-requirement` skill — when AI encounters a link in the ticket description that wasn't already resolved by `ak use`, it can call this command and integrate the JSON output.
-
-```bash
-ak fetch-links "https://company.backlog.com/view/PROJ-10"                   # full ticket
-ak fetch-links "https://company.backlog.com/view/PROJ-10#comment-456"        # single comment
-ak fetch-links "https://company.atlassian.net/browse/PROJ-10"                # Jira ticket
-ak fetch-links "https://company.atlassian.net/browse/PROJ-10?focusedCommentId=789"  # Jira comment
-```
-
-**Arguments:**
-- `<url>` — Backlog or Jira URL (ticket or comment)
-
-**What it does:**
-1. Loads stored credentials from `.aiflow/credentials.json`
-2. Classifies the URL (Backlog vs Jira, ticket vs comment)
-3. Fetches via the appropriate adapter API
-4. Prints the resulting `SupplementaryContext` JSON to stdout
-
-**Exit codes:**
-- `0` — Success, JSON written to stdout
-- `1` — URL not recognised as Backlog/Jira, or fetch failed (error message on stderr)
-
-## task (alias: `t`)
-
-Manage multiple tasks — pause, switch, and resume while preserving gate progress.
-
-```bash
-ak t st                                      # show active + pending  (task status)
-ak t ls                                      # list all saved tasks  (task list)
-ak t p                                       # pause current task  (task pause)
-ak t p -n "waiting for API spec from PM"     # pause with note  (--note)
-ak t sw PROJ-99                              # switch to another task  (task switch)
-ak t r PROJ-33                               # resume a paused task  (task resume)
-ak t rst PROJ-33                             # reset to Gate 1  (task reset)
-ak t rm PROJ-33                              # delete all task data  (task remove)
-ak t n                                       # approve gate & prep next session  (task next)
-ak t n -t PROJ-33                            # specify ticket  (--ticket)
-```
-
-**Sub-commands (with aliases):**
-- `status|st` — Show active task and all pending tasks
-- `list|ls` — List all saved tasks with gate state
-- `pause|p [-n <text>]` — Save current progress and clear active task
-- `switch|sw <ticket-id>` — Pause current task + load/switch to another
-- `resume|r <ticket-id>` — Restore a paused task as active
-- `reset|rst <ticket-id>` — Reset gate progress to Gate 1; prompts to optionally delete `plan/<id>/` files
-- `remove|rm <ticket-id>` — Permanently delete all saved data for the task
-- `next|n [-t <id>]` — Approve current gate and prepare next session
-
-**What it does:**
-1. Saves a snapshot of the current context (`current.json`) to `.aiflow/tasks/<taskId>/context.json`
-2. Detects current gate from `plan/` artifacts (`requirement.md`, `plan.md`, `summary.md`)
-3. Writes `.aiflow/tasks/<taskId>/task-state.json` with status, gate, and approvals
-4. On resume: restores context as `current.json` and sets status back to `active`
-5. The **SessionStart hook** reads `task-state.json` on next `claude` launch and injects gate-aware instructions — Claude resumes from the correct gate instead of restarting Gate 1
-
-**Gate detection from `plan/` files:**
-| File present | Inferred gate |
-|---|---|
-| (none) | Gate 1 |
-| `plan/<id>/requirement.md` | Gate 2 |
-| `plan/<id>/plan.md` | Gate 3 |
-| `plan/<id>/summary.md` | Gate 5 |
-
-**Example workflow:**
-```bash
-# Mid-task on PROJ-33 (Gate 2 in progress)...
-aiflow task pause --note "waiting for DB schema confirmation"
-# ✓ Task PROJ-33 paused at Gate 2.
-
-aiflow use PROJ-99        # load urgent task
-claude                    # AI auto-starts Gate 1 for PROJ-99
-
-# Back to PROJ-33
-aiflow task resume PROJ-33
-# ✓ Resumed task: PROJ-33
-#   Gate:  2 (Implementation Plan)
-
-claude                    # AI resumes from Gate 2 — no restart
-```
-
-**Reset workflow** — run a task from scratch after deleting generated code:
-```bash
-aiflow task reset PROJ-33
-# Reset task: PROJ-33
-#   • .aiflow/tasks/PROJ-33/task-state.json  (Gate 3 → 1, approvals cleared)
-# ? Also delete 2 plan file(s) in plan/PROJ-33/? › No
-# ? Proceed with reset? › Yes
-# ✓ Task PROJ-33 reset to Gate 1.
-
-claude   # AI auto-starts Gate 1 as if the task is brand new
-```
-
-**Remove workflow** — permanently clean up a cancelled task:
-```bash
-aiflow task remove PROJ-33
-# Remove task: PROJ-33
-#   • .aiflow/tasks/PROJ-33/  (context snapshot + gate state)
-#   • .aiflow/context/current.json  (this is the active task)
-#   • plan/PROJ-33/  (2 files):
-#       - plan/PROJ-33/requirement.md
-#       - plan/PROJ-33/plan.md
-# ? This cannot be undone. Proceed? › No
-```
-
----
-
-## prompt (alias: `p`)
-
-Generate an AI prompt with context, rules, and template.
-
-```bash
-ak p bug-fix                                 # generate bug fix prompt
-ak p feature                                 # generate feature prompt
-ak p investigation                           # generate investigation prompt
-ak p refactor                                # generate refactor prompt
-ak p impact                                  # generate impact analysis prompt
-ak p -l                                      # list all prompt types  (--list)
-ak p bug-fix -o p.md                         # save to file  (--output)
-ak p bug-fix -L vietnamese                   # Vietnamese language  (--lang)
-ak p bug-fix -d comprehensive                # comprehensive detail  (--detail)
-```
-
-**Options:**
-- `<type>` — Prompt type (bug-fix, feature, investigation, refactor, impact, docs)
-- `-l, --list` — List available prompt types
-- `-o, --output <file>` — Save to file instead of printing
-- `-L, --lang <lang>` — Language (english, vietnamese)
-- `-d, --detail <level>` — Detail level (minimal, standard, comprehensive)
-
-**What it does:**
-1. Loads current context (from `aiflow use`)
-2. Loads prompt template for the type
-3. Loads framework rules
-4. Loads team rules and best practices
-5. Merges everything into a complete prompt
-6. Prints to console (or saves/copies)
-
-**Example:**
-```bash
-$ aiflow prompt bug-fix
-═══════════════════════════════════════════════════════════════
-BUG FIX INVESTIGATION PROMPT
-═══════════════════════════════════════════════════════════════
-
-## Context
-Title: Payment processing fails on checkout
-Description: Users report seeing payment error when... [2000+ words]
-
-## Framework Rules (Laravel)
-- Use Laravel's built-in tools...
-- Keep Controllers thin...
-
-## Team Rules
-- Use strict typing...
-- Follow PSR-12 styling...
-
-## Task
-Investigate the bug following this process:
-1. Understand the error context...
-[Complete prompt ready to copy to Claude]
-```
-
-## detect (alias: `d`)
-
-Auto-detect task type from a description.
-
-```bash
-ak d "Payment integration is broken"         # detect from description
-ak d                                         # detect from current context
-ak d "Add new feature" -v                    # show confidence  (--verbose)
-ak d "description" -t 90                     # set threshold  (--threshold)
-```
-
-**Options:**
-- `<description>` — Description to analyze
-- `-v, --verbose` — Show detection reasoning
-- `-t, --threshold <number>` — Confidence threshold (0-100)
-
-**What it does:**
-1. Analyzes description for keywords
-2. Classifies as bug-fix, feature, refactor, investigation, etc
-3. Shows confidence score
-4. Suggests appropriate skill
-
-**Example:**
-```bash
-$ aiflow detect "Users can't save their orders"
-🐛 Bug Fix (98% confidence)
-
-Detected keywords:
-- "can't save" → bug pattern
-- Specific area → likely regression
-
-Suggested skill: investigate-bug
-
-Next: aiflow prompt bug-fix
-```
-
-## context (alias: `ctx`)
-
-Manage task contexts (save, load, list, delete).
-
-```bash
-ak ctx list                                  # list saved contexts
-ak ctx -s "checkout-fix"                     # save current context  (--save)
-ak ctx -l "checkout-fix"                     # load saved context  (--load)
-ak ctx -d "checkout-fix"                     # delete saved context  (--delete)
-ak ctx clear                                 # clear all contexts
-ak ctx show                                  # show current context
-```
-
-**Options:**
-- `-s, --save <name>` — Save current context
-- `-l, --load <name>` — Load saved context
-- `-d, --delete <name>` — Delete saved context
-- `--clear` — Clear all contexts
-- `--show` — Show current context details
-
-**What it does:**
-1. Lists, saves, loads, or deletes contexts
-2. Manages context history in `.aiflow/context/history/`
-3. Makes it easy to switch between tasks
-
-**Example:**
-```bash
-$ aiflow context --list
-Saved contexts:
-  1. checkout-fix (saved 2 hours ago)
-  2. payment-integration (saved yesterday)
-  3. user-auth-bug (saved 3 days ago)
-
-$ aiflow context --load checkout-fix
-✓ Loaded: checkout-fix
-✓ Ready to prompt!
-```
-
-## update (alias: `up`)
-
-Update to the latest version.
-
-```bash
-ak up                                        # update to latest
-ak up -f                                     # force update  (--force)
-```
-
-**Options:**
-- `-f, --force` — Force update even if already latest
-
-**What it does:**
-1. Checks for newer version
-2. Downloads assets (skills, rules, templates)
-3. Updates `.claude/` and `.rules/`
-4. Optionally deletes old version
-5. Updates state tracking
-
-**Example:**
-```bash
-$ aiflow update
-Updating from v1.0.0 to v1.1.0...
-✓ Downloaded skills for v1.1.0
-✓ Downloaded rules for v1.1.0
-
-Keep old version (v1.0.0)? (y/n) y
-✓ Kept v1.0.0
-
-You can switch back with: aiflow use 1.0.0
-
-✨ Update completed!
-```
-
-## sync-skills (alias: `sync`)
-
-Manually synchronize AI Instruction files with local custom skills.
-
-```bash
-ak sync                                      # sync AI Instruction files
-```
-
-**What it does:**
-1. Reads all active local skills and upstream skills
-2. Generates the updated AI Skill Registry table
-3. Safely updates the AI Instruction blocks (`<!-- aiflow-kit-start -->`) in your project's `CLAUDE.md`, `GEMINI.md`, or `.cursorrules` without wiping your custom rules
-4. If no marker blocks are found, it asks for confirmation to overwrite with the correct structure
-
-**Example:**
-```bash
-$ aiflow sync-skills
-⟳ Syncing AI Instruction files...
-  ✓ Updated AI Flow block in CLAUDE.md
-✨ Sync completed!
-```
-
-## doctor (alias: `dr`)
-
-Health check for your setup.
-
-```bash
-ak dr                                        # run health check
-ak dr -v                                     # verbose output  (--verbose)
-ak dr -t PROJ-33                             # token breakdown for ticket  (--ticket)
-```
-
-**Options:**
-- `-t, --ticket <id>` — Show token breakdown for specific ticket
-- `-v, --verbose` — Show detailed checks
-
-**What it does:**
-1. Checks for required directories
-2. Validates configuration files
-3. Checks MCP adapter setup
-4. Verifies framework template
-5. Reports issues and fixes
-
-**Example:**
-```bash
-$ aiflow doctor
-Running health check for AI Flow Kit...
-
-✓ .claude/skills exists
-✓ .rules exists
-✓ CLAUDE.md exists
-✓ Version tracking active (v1.0.0)
-✓ Jira adapter configured
-✓ Laravel framework template loaded
-
-✨ Everything looks healthy! You are ready to fly.
-```
-
-## validate (alias: `vl`)
-
-Validate AI output against team rules and quality standards.
-
-```bash
-ak vl output.php                             # validate a file
-ak vl output.php -r strict                   # strict rule set  (--ruleset)
-ak vl output.php -v                          # detailed report  (--verbose)
-ak vl output.php -x                          # auto-fix trailing whitespace  (--fix)
-```
-
-**Options:**
-- `<file>` — File to validate
-- `-r, --ruleset <set>` — Rule set (default, strict, lenient)
-- `-v, --verbose` — Detailed report
-- `-x, --fix` — Auto-fix trailing whitespace
-
-**What it does:**
-1. Loads validation rules from `custom/rules/`
-2. Checks code style, naming, security, etc
-3. Reports violations
-4. Optionally suggests fixes
-
-**Example:**
-```bash
-$ aiflow validate src/Payment.php
-Validating against ruleset: default
-
-✓ Code style: OK
-⚠ Naming: Variable $p should be $payment
-✓ Security: OK
-✗ Testing: Missing test file
-
-Issues found: 2 warnings, 1 error
-Suggestions: Add test case, rename variable
-```
-
-## telemetry (alias: `tel`)
-
-Manage usage telemetry.
-
-```bash
-ak tel status                                # view status, buffer size, last flush
-ak tel enable                                # interactive setup (URL, secret, email)
-ak tel disable                               # disable tracking (config retained)
-ak tel flush                                 # force-send buffered events now
-```
-
-**Sub-commands:**
-- `status` — View current status, buffer size, last flush time
-- `enable` — Interactive setup (Apps Script URL, team secret, email)
-- `disable` — Disable tracking; configuration is retained
-- `flush` — Force-send all buffered events immediately
-
----
-
-## memory (alias: `mem`)
-
-Manage team knowledge and context memory.
-
-```bash
-ak mem s "payment-flow" "Process: 1. Validate, 2. Call Stripe, 3. Update DB"   # save
-ak mem g "payment-flow"                      # retrieve  (memory get)
-ak mem ls                                    # list all  (memory list)
-ak mem sr "validation"                       # search  (memory search)
-ak mem d "old-memory"                        # delete  (memory delete)
-ak mem cl                                    # clear all  (memory clear)
-```
-
-**Sub-commands (with aliases):**
-- `save|s <key> <value>` — Save a note
-- `get|g <key>` — Read a note
-- `list|ls` — List all notes
-- `search|sr <query>` — Search notes
-- `delete|d <key>` — Delete a note
-- `clear|cl` — Clear all notes
-
-**What it does:**
-1. Stores team knowledge in `.aiflow/memory/`
-2. Makes knowledge discoverable across the team
-
-**Example:**
-```bash
-$ aiflow memory save "payment-flow" "Process: 1. Validate amount, 2. Call Stripe API, 3. Update DB"
-✓ Saved: payment-flow
-
-$ aiflow memory search "payment"
-Found 3 memories matching "payment":
-  1. payment-flow
-  2. payment-error-handling
-  3. payment-tests
-```
-
-## guide (alias: `g`)
-
-Show quickstart guide.
-
-```bash
-ak g                                         # full guide
-ak g -f                                      # architecture & flow only  (--flow)
-ak g -c                                      # command reference only  (--commands)
-```
-
-**Options:**
-- `-f, --flow` — Show architecture & flow diagram only
-- `-c, --commands` — Show command reference only
-
----
-
-## gate (AI workflow logging)
-
-Called automatically by AI during gate workflow — not intended for manual use.
-
-```bash
-# Log gate N started
-aiflow gate <n> start --ticket <id>
-
-# Log gate N approved
-aiflow gate <n> approved --ticket <id>
-```
-
-**Arguments:**
-- `<n>` — Gate number (1-5)
-- `<action>` — `start` or `approved`
-
-**Options:**
-- `--ticket <id>` — Ticket ID associated with the gate transition
-- `--ai-tool <tool>` — AI tool that triggered the gate (e.g. claude, cursor, gemini)
-
----
-
-## remove (alias: `rm`)
-
-Remove ai-flow-kit from project, a cached version, or uninstall globally.
-
-```bash
-ak rm                                        # remove from project
-ak rm -g                                     # uninstall globally  (--global)
-ak rm --version 1.0.0                        # remove cached version from .aiflow/
-```
-
-**Options:**
-- `--version <ver>` — Remove a specific cached version from `.aiflow/versions/`
-- `-g, --global` — Uninstall the global npm package (removes `aiflow` command)
-
----
-
-## Global Options
-
-These work with any command:
-
-```bash
-ak --version                     # Show installed version  (-v, -V)
-ak <command> --help              # Show help for a command  (-h)
-```
-
-## Exit Codes
-
-- `0` — Success
-- `1` — General error
-- `2` — Command not found
-- `3` — Invalid arguments
-- `4` — Configuration error
-- `5` — MCP adapter error
-
----
-
-See [Getting Started](./getting-started.md) for tutorials and [Configuration](./configuration.md) for detailed options.
+# CLI Reference
+
+Complete reference for all `ak` / `aiflow` commands.
+
+> **Short alias:** `ak` is the preferred short form of `aiflow`. Every command also has a short alias shown in the format `command|alias`.
+
+## Commands Overview
+
+```bash
+ak --help                        # Show all commands
+ak <command> --help              # Show command help
+ak <alias> --help                # Also works with aliases
+```
+
+### Quick Alias Reference
+
+| Full command | Short | Full command | Short |
+|---|---|---|---|
+| `ak init` | `ak i` | `ak use` | `ak u` |
+| `ak prompt` | `ak p` | `ak detect` | `ak d` |
+| `ak task` | `ak t` | `ak context` | `ak ctx` |
+| `ak checkpoint` | `ak cp` | `ak validate` | `ak vl` |
+| `ak memory` | `ak mem` | `ak guide` | `ak g` |
+| `ak remove` | `ak rm` | `ak update` | `ak up` |
+| `ak sync-skills` | `ak sync` | `ak doctor` | `ak dr` |
+| `ak telemetry` | `ak tel` | | |
+
+| `task` sub-command | Short | `memory` sub-command | Short |
+|---|---|---|---|
+| `ak t status` | `ak t st` | `ak mem save` | `ak mem s` |
+| `ak t list` | `ak t ls` | `ak mem get` | `ak mem g` |
+| `ak t pause` | `ak t p` | `ak mem list` | `ak mem ls` |
+| `ak t switch` | `ak t sw` | `ak mem search` | `ak mem sr` |
+| `ak t resume` | `ak t r` | `ak mem delete` | `ak mem d` |
+| `ak t reset` | `ak t rst` | `ak mem clear` | `ak mem cl` |
+| `ak t remove` | `ak t rm` | | |
+| `ak t next` | `ak t n` | | |
+
+## init
+
+Initialize AI Flow Kit in your project.
+
+```bash
+ak init                                      # basic initialization
+ak init -f laravel                           # with framework  (--framework)
+ak init -a jira                              # with adapter  (--adapter)
+ak init -f laravel -a jira                   # full setup
+ak init -f spring-boot --with-rtk            # enable RTK compression
+ak init --no-rtk                             # skip RTK setup
+```
+
+**Options:**
+- `-f, --framework <types>` (alias: `--fw`) — Framework templates, comma-separated (e.g. `spring-boot,reactjs`)
+- `-a, --adapter <types>` — MCP adapters (jira, backlog, google-sheets)
+- `-e, --env <types>` — AI tools to configure (cursor, gemini, copilot, generic). Default excludes `generic`.
+- `--with-rtk` — Force enable RTK token compression hook
+- `--no-rtk` — Skip RTK setup even if RTK is detected
+
+**What it does:**
+1. Creates `.claude/skills/` with all available skills
+2. Creates `.rules/` with team rules (including `java/spring-boot-examples.md` for Spring Boot projects)
+3. Creates `.aiflow/` with version tracking
+4. Sets up framework instruction file (`CLAUDE.md`, `.cursorrules`, etc.):
+   - **File already exists** → saves aiflow template to `.aiflow/reference/<file>` for comparison. Your existing file is untouched — you own it.
+   - **File does not exist** → creates it in the project root.
+5. Optionally configures MCP adapter
+
+> **Note:** `CLAUDE.md` and other AI instruction files are project files — commit them to your repo. Run `aiflow init` once to generate them, then maintain them yourself. On subsequent `aiflow init` runs they will not be overwritten.
+
+**Example:**
+```bash
+$ aiflow init --framework laravel --adapter jira
+Initializing ai-flow-kit (v1.0.0)...
+✓ Copied skills to .claude/skills
+✓ Copied rules to .rules
+✓ Set up CLAUDE.md for framework: laravel
+✓ Updated MCP configuration for jira
+
+✨ Initialized AI Flow Kit successfully!
+```
+
+## use
+
+Load context from one or more tickets, files, or manual entry. **Accepts variadic targets** (v0.1.0+) — the first target is the primary context (drives Gate 1); any additional targets are appended as `supplementaryContext[]`.
+
+```bash
+ak use JIRA-123                              # single target — load from Jira
+ak use BACKLOG-456                           # single target — load from Backlog
+ak use PROJ-33 PROJ-10 docs/arch.md          # multi-target — primary + supplementary (v0.1.0+)
+ak use BACKLOG-456 -F                        # fast mode  (--fast)
+ak use BACKLOG-456 -U                        # full mode  (--full)
+ak use -m                                    # manual entry  (--manual)
+ak use -f path/to/context.json               # load from file  (--file)
+ak use BACKLOG-456 -c                        # load with all comments  (--coms)
+ak use BACKLOG-456 --clast 5                 # last 5 comments
+ak use BACKLOG-456 --cid 42                  # specific comment
+ak use 1.0.0                                 # switch between versions
+```
+
+**Arguments:**
+- `[targets...]` — One or more targets. Each target can be a ticket ID (`PROJ-33`), a Backlog/Jira URL, or a local file path. First target = primary; rest = supplementary.
+
+**Options:**
+- `-m, --manual` — Manual context entry
+- `-f, --file <path>` — Load from file (JSON or plain text)
+- `-s, --save <name>` — Save as named context
+- `-c, --coms` — Load all comments (alias for `--with-comments`)
+- `--with-comments` — Include all ticket comments
+- `--cid <id>` — Load a specific comment by ID
+- `--clast <n>` — Only fetch last N comments
+- `--cfrom <id>` — Fetch comments from ID N onward
+- `--cto <id>` — Fetch comments up to ID N
+- `-F, --fast` — Fast mode: AI skips Q&A, lite 3-section requirement doc (< 5 min Gate 1)
+- `-U, --full` — Full mode: force complete Gate 1 analysis with Q&A
+
+**Auto link resolution (v0.1.0+):** When the primary ticket description contains Backlog/Jira URLs, `ak use` auto-fetches them and appends to `supplementaryContext[]`. Comment URLs (`#comment-456` or `?focusedCommentId=456`) resolve to **that single comment only**. Capped at 5 auto-resolved links per `use`; per-link errors are logged without aborting the command.
+
+**`supplementaryContext[]` schema** (persisted in `.aiflow/context/current.json`):
+
+```json
+{
+  "sourceType": "ticket | comment | file | text",
+  "sourceUrl": "https://...",
+  "sourcePath": "docs/arch.md",
+  "ticketId": "PROJ-10",
+  "commentId": "456",
+  "title": "...",
+  "description": "...",
+  "content": "...",
+  "author": "...",
+  "date": "..."
+}
+```
+
+**What it does:**
+1. Loads the first target as primary context (fetches from MCP adapter / file / manual entry)
+2. Loads each remaining target as a supplementary item
+3. Scans the primary description for Backlog/Jira URLs and auto-resolves them
+4. Saves the merged context (including `mode` and `supplementaryContext[]`) to `.aiflow/context/current.json`
+5. Updates state tracking
+
+**Example:**
+```bash
+$ aiflow use JIRA-123
+Fetching context from Jira...
+✓ Title: Fix payment processing error
+✓ Description: 2000+ words pulled
+✓ Acceptance criteria: 3 items
+✓ Saved to .aiflow/context/current.json
+
+Ready to prompt! Run: aiflow prompt bug-fix
+
+$ aiflow use PROJ-33 PROJ-10 docs/arch.md
+✓ Loaded primary: PROJ-33
+✓ Supplementary: PROJ-10 (ticket), docs/arch.md (file)
+✓ Auto-resolved 2 link(s) from description
+```
+
+## fetch-links
+
+Fetch a single Backlog/Jira URL and print a `SupplementaryContext` JSON object to stdout. Intended for AI runtime use inside the `read-study-requirement` skill — when AI encounters a link in the ticket description that wasn't already resolved by `ak use`, it can call this command and integrate the JSON output.
+
+```bash
+ak fetch-links "https://company.backlog.com/view/PROJ-10"                   # full ticket
+ak fetch-links "https://company.backlog.com/view/PROJ-10#comment-456"        # single comment
+ak fetch-links "https://company.atlassian.net/browse/PROJ-10"                # Jira ticket
+ak fetch-links "https://company.atlassian.net/browse/PROJ-10?focusedCommentId=789"  # Jira comment
+```
+
+**Arguments:**
+- `<url>` — Backlog or Jira URL (ticket or comment)
+
+**What it does:**
+1. Loads stored credentials from `.aiflow/credentials.json`
+2. Classifies the URL (Backlog vs Jira, ticket vs comment)
+3. Fetches via the appropriate adapter API
+4. Prints the resulting `SupplementaryContext` JSON to stdout
+
+**Exit codes:**
+- `0` — Success, JSON written to stdout
+- `1` — URL not recognised as Backlog/Jira, or fetch failed (error message on stderr)
+
+## task (alias: `t`)
+
+Manage multiple tasks — pause, switch, and resume while preserving gate progress.
+
+```bash
+ak t st                                      # show active + pending  (task status)
+ak t ls                                      # list all saved tasks  (task list)
+ak t p                                       # pause current task  (task pause)
+ak t p -n "waiting for API spec from PM"     # pause with note  (--note)
+ak t sw PROJ-99                              # switch to another task  (task switch)
+ak t r PROJ-33                               # resume a paused task  (task resume)
+ak t rst PROJ-33                             # reset to Gate 1  (task reset)
+ak t rm PROJ-33                              # delete all task data  (task remove)
+ak t n                                       # approve gate & prep next session  (task next)
+ak t n -t PROJ-33                            # specify ticket  (--ticket)
+```
+
+**Sub-commands (with aliases):**
+- `status|st` — Show active task and all pending tasks
+- `list|ls` — List all saved tasks with gate state
+- `pause|p [-n <text>]` — Save current progress and clear active task
+- `switch|sw <ticket-id>` — Pause current task + load/switch to another
+- `resume|r <ticket-id>` — Restore a paused task as active
+- `reset|rst <ticket-id>` — Reset gate progress to Gate 1; prompts to optionally delete `plan/<id>/` files
+- `remove|rm <ticket-id>` — Permanently delete all saved data for the task
+- `next|n [-t <id>]` — Approve current gate and prepare next session
+
+**What it does:**
+1. Saves a snapshot of the current context (`current.json`) to `.aiflow/tasks/<taskId>/context.json`
+2. Detects current gate from `plan/` artifacts (`requirement.md`, `plan.md`, `summary.md`)
+3. Writes `.aiflow/tasks/<taskId>/task-state.json` with status, gate, and approvals
+4. On resume: restores context as `current.json` and sets status back to `active`
+5. The **SessionStart hook** reads `task-state.json` on next `claude` launch and injects gate-aware instructions — Claude resumes from the correct gate instead of restarting Gate 1
+
+**Gate detection from `plan/` files:**
+| File present | Inferred gate |
+|---|---|
+| (none) | Gate 1 |
+| `plan/<id>/requirement.md` | Gate 2 |
+| `plan/<id>/plan.md` | Gate 3 |
+| `plan/<id>/summary.md` | Gate 5 |
+
+**Example workflow:**
+```bash
+# Mid-task on PROJ-33 (Gate 2 in progress)...
+aiflow task pause --note "waiting for DB schema confirmation"
+# ✓ Task PROJ-33 paused at Gate 2.
+
+aiflow use PROJ-99        # load urgent task
+claude                    # AI auto-starts Gate 1 for PROJ-99
+
+# Back to PROJ-33
+aiflow task resume PROJ-33
+# ✓ Resumed task: PROJ-33
+#   Gate:  2 (Implementation Plan)
+
+claude                    # AI resumes from Gate 2 — no restart
+```
+
+**Reset workflow** — run a task from scratch after deleting generated code:
+```bash
+aiflow task reset PROJ-33
+# Reset task: PROJ-33
+#   • .aiflow/tasks/PROJ-33/task-state.json  (Gate 3 → 1, approvals cleared)
+# ? Also delete 2 plan file(s) in plan/PROJ-33/? › No
+# ? Proceed with reset? › Yes
+# ✓ Task PROJ-33 reset to Gate 1.
+
+claude   # AI auto-starts Gate 1 as if the task is brand new
+```
+
+**Remove workflow** — permanently clean up a cancelled task:
+```bash
+aiflow task remove PROJ-33
+# Remove task: PROJ-33
+#   • .aiflow/tasks/PROJ-33/  (context snapshot + gate state)
+#   • .aiflow/context/current.json  (this is the active task)
+#   • plan/PROJ-33/  (2 files):
+#       - plan/PROJ-33/requirement.md
+#       - plan/PROJ-33/plan.md
+# ? This cannot be undone. Proceed? › No
+```
+
+---
+
+## prompt (alias: `p`)
+
+Generate an AI prompt with context, rules, and template.
+
+```bash
+ak p bug-fix                                 # generate bug fix prompt
+ak p feature                                 # generate feature prompt
+ak p investigation                           # generate investigation prompt
+ak p refactor                                # generate refactor prompt
+ak p impact                                  # generate impact analysis prompt
+ak p -l                                      # list all prompt types  (--list)
+ak p bug-fix -o p.md                         # save to file  (--output)
+ak p bug-fix -L vietnamese                   # Vietnamese language  (--lang)
+ak p bug-fix -d comprehensive                # comprehensive detail  (--detail)
+```
+
+**Options:**
+- `<type>` — Prompt type (bug-fix, feature, investigation, refactor, impact, docs)
+- `-l, --list` — List available prompt types
+- `-o, --output <file>` — Save to file instead of printing
+- `-L, --lang <lang>` — Language (english, vietnamese)
+- `-d, --detail <level>` — Detail level (minimal, standard, comprehensive)
+
+**What it does:**
+1. Loads current context (from `aiflow use`)
+2. Loads prompt template for the type
+3. Loads framework rules
+4. Loads team rules and best practices
+5. Merges everything into a complete prompt
+6. Prints to console (or saves/copies)
+
+**Example:**
+```bash
+$ aiflow prompt bug-fix
+═══════════════════════════════════════════════════════════════
+BUG FIX INVESTIGATION PROMPT
+═══════════════════════════════════════════════════════════════
+
+## Context
+Title: Payment processing fails on checkout
+Description: Users report seeing payment error when... [2000+ words]
+
+## Framework Rules (Laravel)
+- Use Laravel's built-in tools...
+- Keep Controllers thin...
+
+## Team Rules
+- Use strict typing...
+- Follow PSR-12 styling...
+
+## Task
+Investigate the bug following this process:
+1. Understand the error context...
+[Complete prompt ready to copy to Claude]
+```
+
+## detect (alias: `d`)
+
+Auto-detect task type from a description.
+
+```bash
+ak d "Payment integration is broken"         # detect from description
+ak d                                         # detect from current context
+ak d "Add new feature" -v                    # show confidence  (--verbose)
+ak d "description" -t 90                     # set threshold  (--threshold)
+```
+
+**Options:**
+- `<description>` — Description to analyze
+- `-v, --verbose` — Show detection reasoning
+- `-t, --threshold <number>` — Confidence threshold (0-100)
+
+**What it does:**
+1. Analyzes description for keywords
+2. Classifies as bug-fix, feature, refactor, investigation, etc
+3. Shows confidence score
+4. Suggests appropriate skill
+
+**Example:**
+```bash
+$ aiflow detect "Users can't save their orders"
+🐛 Bug Fix (98% confidence)
+
+Detected keywords:
+- "can't save" → bug pattern
+- Specific area → likely regression
+
+Suggested skill: investigate-bug
+
+Next: aiflow prompt bug-fix
+```
+
+## context (alias: `ctx`)
+
+Manage task contexts (save, load, list, delete).
+
+```bash
+ak ctx list                                  # list saved contexts
+ak ctx -s "checkout-fix"                     # save current context  (--save)
+ak ctx -l "checkout-fix"                     # load saved context  (--load)
+ak ctx -d "checkout-fix"                     # delete saved context  (--delete)
+ak ctx clear                                 # clear all contexts
+ak ctx show                                  # show current context
+```
+
+**Options:**
+- `-s, --save <name>` — Save current context
+- `-l, --load <name>` — Load saved context
+- `-d, --delete <name>` — Delete saved context
+- `--clear` — Clear all contexts
+- `--show` — Show current context details
+
+**What it does:**
+1. Lists, saves, loads, or deletes contexts
+2. Manages context history in `.aiflow/context/history/`
+3. Makes it easy to switch between tasks
+
+**Example:**
+```bash
+$ aiflow context --list
+Saved contexts:
+  1. checkout-fix (saved 2 hours ago)
+  2. payment-integration (saved yesterday)
+  3. user-auth-bug (saved 3 days ago)
+
+$ aiflow context --load checkout-fix
+✓ Loaded: checkout-fix
+✓ Ready to prompt!
+```
+
+## update (alias: `up`)
+
+Update to the latest version.
+
+```bash
+ak up                                        # update to latest
+ak up -f                                     # force update  (--force)
+```
+
+**Options:**
+- `-f, --force` — Force update even if already latest
+
+**What it does:**
+1. Checks for newer version
+2. Downloads assets (skills, rules, templates)
+3. Updates `.claude/` and `.rules/`
+4. Optionally deletes old version
+5. Updates state tracking
+
+**Example:**
+```bash
+$ aiflow update
+Updating from v1.0.0 to v1.1.0...
+✓ Downloaded skills for v1.1.0
+✓ Downloaded rules for v1.1.0
+
+Keep old version (v1.0.0)? (y/n) y
+✓ Kept v1.0.0
+
+You can switch back with: aiflow use 1.0.0
+
+✨ Update completed!
+```
+
+## sync-skills (alias: `sync`)
+
+Manually synchronize AI Instruction files with local custom skills.
+
+```bash
+ak sync                                      # sync AI Instruction files
+```
+
+**What it does:**
+1. Reads all active local skills and upstream skills
+2. Generates the updated AI Skill Registry table
+3. Safely updates the AI Instruction blocks (`<!-- aiflow-kit-start -->`) in your project's `CLAUDE.md`, `GEMINI.md`, or `.cursorrules` without wiping your custom rules
+4. If no marker blocks are found, it asks for confirmation to overwrite with the correct structure
+
+**Example:**
+```bash
+$ aiflow sync-skills
+⟳ Syncing AI Instruction files...
+  ✓ Updated AI Flow block in CLAUDE.md
+✨ Sync completed!
+```
+
+## doctor (alias: `dr`)
+
+Health check for your setup.
+
+```bash
+ak dr                                        # run health check
+ak dr -v                                     # verbose output  (--verbose)
+ak dr -t PROJ-33                             # token breakdown for ticket  (--ticket)
+```
+
+**Options:**
+- `-t, --ticket <id>` — Show token breakdown for specific ticket
+- `-v, --verbose` — Show detailed checks
+
+**What it does:**
+1. Checks for required directories
+2. Validates configuration files
+3. Checks MCP adapter setup
+4. Verifies framework template
+5. Reports issues and fixes
+
+**Example:**
+```bash
+$ aiflow doctor
+Running health check for AI Flow Kit...
+
+✓ .claude/skills exists
+✓ .rules exists
+✓ CLAUDE.md exists
+✓ Version tracking active (v1.0.0)
+✓ Jira adapter configured
+✓ Laravel framework template loaded
+
+✨ Everything looks healthy! You are ready to fly.
+```
+
+## validate (alias: `vl`)
+
+Validate AI output against team rules and quality standards.
+
+```bash
+ak vl output.php                             # validate a file
+ak vl output.php -r strict                   # strict rule set  (--ruleset)
+ak vl output.php -v                          # detailed report  (--verbose)
+ak vl output.php -x                          # auto-fix trailing whitespace  (--fix)
+```
+
+**Options:**
+- `<file>` — File to validate
+- `-r, --ruleset <set>` — Rule set (default, strict, lenient)
+- `-v, --verbose` — Detailed report
+- `-x, --fix` — Auto-fix trailing whitespace
+
+**What it does:**
+1. Loads validation rules from `custom/rules/`
+2. Checks code style, naming, security, etc
+3. Reports violations
+4. Optionally suggests fixes
+
+**Example:**
+```bash
+$ aiflow validate src/Payment.php
+Validating against ruleset: default
+
+✓ Code style: OK
+⚠ Naming: Variable $p should be $payment
+✓ Security: OK
+✗ Testing: Missing test file
+
+Issues found: 2 warnings, 1 error
+Suggestions: Add test case, rename variable
+```
+
+## telemetry (alias: `tel`)
+
+Manage usage telemetry.
+
+```bash
+ak tel status                                # view status, buffer size, last flush
+ak tel enable                                # interactive setup (URL, secret, email)
+ak tel disable                               # disable tracking (config retained)
+ak tel flush                                 # force-send buffered events now
+```
+
+**Sub-commands:**
+- `status` — View current status, buffer size, last flush time
+- `enable` — Interactive setup (Apps Script URL, team secret, email)
+- `disable` — Disable tracking; configuration is retained
+- `flush` — Force-send all buffered events immediately
+
+---
+
+## memory (alias: `mem`)
+
+Manage team knowledge and context memory.
+
+```bash
+ak mem s "payment-flow" "Process: 1. Validate, 2. Call Stripe, 3. Update DB"   # save
+ak mem g "payment-flow"                      # retrieve  (memory get)
+ak mem ls                                    # list all  (memory list)
+ak mem sr "validation"                       # search  (memory search)
+ak mem d "old-memory"                        # delete  (memory delete)
+ak mem cl                                    # clear all  (memory clear)
+```
+
+**Sub-commands (with aliases):**
+- `save|s <key> <value>` — Save a note
+- `get|g <key>` — Read a note
+- `list|ls` — List all notes
+- `search|sr <query>` — Search notes
+- `delete|d <key>` — Delete a note
+- `clear|cl` — Clear all notes
+
+**What it does:**
+1. Stores team knowledge in `.aiflow/memory/`
+2. Makes knowledge discoverable across the team
+
+**Example:**
+```bash
+$ aiflow memory save "payment-flow" "Process: 1. Validate amount, 2. Call Stripe API, 3. Update DB"
+✓ Saved: payment-flow
+
+$ aiflow memory search "payment"
+Found 3 memories matching "payment":
+  1. payment-flow
+  2. payment-error-handling
+  3. payment-tests
+```
+
+## guide (alias: `g`)
+
+Show quickstart guide.
+
+```bash
+ak g                                         # full guide
+ak g -f                                      # architecture & flow only  (--flow)
+ak g -c                                      # command reference only  (--commands)
+```
+
+**Options:**
+- `-f, --flow` — Show architecture & flow diagram only
+- `-c, --commands` — Show command reference only
+
+---
+
+## gate (AI workflow logging)
+
+Called automatically by AI during gate workflow — not intended for manual use.
+
+```bash
+# Log gate N started
+aiflow gate <n> start --ticket <id>
+
+# Log gate N approved
+aiflow gate <n> approved --ticket <id>
+```
+
+**Arguments:**
+- `<n>` — Gate number (1-5)
+- `<action>` — `start` or `approved`
+
+**Options:**
+- `--ticket <id>` — Ticket ID associated with the gate transition
+- `--ai-tool <tool>` — AI tool that triggered the gate (e.g. claude, cursor, gemini)
+
+---
+
+## remove (alias: `rm`)
+
+Remove ai-flow-kit from project, a cached version, or uninstall globally.
+
+```bash
+ak rm                                        # remove from project
+ak rm -g                                     # uninstall globally  (--global)
+ak rm --version 1.0.0                        # remove cached version from .aiflow/
+```
+
+**Options:**
+- `--version <ver>` — Remove a specific cached version from `.aiflow/versions/`
+- `-g, --global` — Uninstall the global npm package (removes `aiflow` command)
+
+---
+
+## Global Options
+
+These work with any command:
+
+```bash
+ak --version                     # Show installed version  (-v, -V)
+ak <command> --help              # Show help for a command  (-h)
+```
+
+## Exit Codes
+
+- `0` — Success
+- `1` — General error
+- `2` — Command not found
+- `3` — Invalid arguments
+- `4` — Configuration error
+- `5` — MCP adapter error
+
+---
+
+See [Getting Started](./getting-started.md) for tutorials and [Configuration](./configuration.md) for detailed options.