@relipa/ai-flow-kit 0.0.4-beta.3 → 0.0.5-beta.0

package/docs/cli-reference.md

@@ -30,6 +30,7 @@ aiflow init --framework laravel --adapter jira
 **Options:**
 - `-f, --framework <type>` — Framework template (laravel, nextjs, vue-nuxt)
 - `-a, --adapter <type>` — MCP adapter (jira, backlog, google-sheets)
+- `-e, --env <types>` — AI tools to configure (cursor, gemini, copilot)
 
 **What it does:**
 1. Creates `.claude/skills/` with all available skills
@@ -76,6 +77,9 @@ aiflow use 1.0.0
 - `-m, --manual` — Manual context entry
 - `-f, --file <path>` — Load from JSON file
 - `-s, --save <name>` — Save as named context
+- `--with-comments` — Include all ticket comments
+- `--comments-last <n>` — Only fetch last N comments
+- `--comments-from <n>` — Fetch comments starting from comment N
 
 **What it does:**
 1. Fetches context from MCP adapter (if applicable)
@@ -123,7 +127,6 @@ aiflow prompt --list
 - `<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
-- `-c, --copy` — Copy to clipboard
 - `--lang <lang>` — Language (english, vietnamese)
 - `--detail <level>` — Detail level (minimal, standard, comprehensive)
 
@@ -258,12 +261,11 @@ Update to the latest version.
 # Update to latest
 aiflow update
 
-# Keep old version
-aiflow update --keep-old
+# Force update even if already latest
+aiflow update --force
 ```
 
 **Options:**
-- `--keep-old` — Don't delete previous version
 - `--force` — Force update even if already latest
 
 **What it does:**
@@ -296,12 +298,11 @@ Health check for your setup.
 # Run health check
 aiflow doctor
 
-# Fix issues automatically
-aiflow doctor --fix
+# Run with verbose output
+aiflow doctor --verbose
 ```
 
 **Options:**
-- `--fix` — Attempt to fix found issues
 - `-v, --verbose` — Show detailed checks
 
 **What it does:**
@@ -367,61 +368,130 @@ Issues found: 2 warnings, 1 error
 Suggestions: Add test case, rename variable
 ```
 
+## telemetry
+
+Manage usage telemetry.
+
+```bash
+# View current status, buffer size, last flush
+aiflow telemetry status
+
+# Interactive setup (URL, secret, email)
+aiflow telemetry enable
+
+# Disable tracking (config retained)
+aiflow telemetry disable
+
+# Force-send buffered events now
+aiflow telemetry flush
+```
+
+**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
 
 Manage team knowledge and context memory.
 
 ```bash
 # Save knowledge
-aiflow memory --save "Laravel validation pattern" "Use FormRequest..."
+aiflow memory save "payment-flow" "Process: 1. Validate amount, 2. Call Stripe API, 3. Update DB"
 
 # Retrieve knowledge
-aiflow memory --get "Laravel validation pattern"
+aiflow memory get "payment-flow"
 
 # List all memories
-aiflow memory --list
+aiflow memory list
 
 # Delete memory
-aiflow memory --delete "old-memory"
+aiflow memory delete "old-memory"
 
 # Search memories
-aiflow memory --search "validation"
+aiflow memory search "validation"
+
+# Clear all memories
+aiflow memory clear
 ```
 
-**Options:**
-- `-s, --save <key> <value>` — Save memory
-- `-g, --get <key>` — Retrieve memory
-- `-l, --list` — List all memories
-- `-d, --delete <key>` — Delete memory
-- `--search <query>` — Search memories
-- `--auto-load` — Auto-load relevant memories
+**Sub-commands:**
+- `save <key> <value>` — Save a note
+- `get <key>` — Read a note
+- `list` — List all notes
+- `search <query>` — Search notes
+- `delete <key>` — Delete a note
+- `clear` — Clear all notes
 
 **What it does:**
 1. Stores team knowledge in `.aiflow/memory/`
-2. Auto-loads relevant memory for current task
-3. Makes knowledge discoverable across team
+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"
+$ aiflow memory save "payment-flow" "Process: 1. Validate amount, 2. Call Stripe API, 3. Update DB"
 ✓ Saved: payment-flow
 
-$ aiflow memory --search "payment"
+$ aiflow memory search "payment"
 Found 3 memories matching "payment":
   1. payment-flow
   2. payment-error-handling
   3. payment-tests
 ```
 
+## guide
+
+Show quickstart guide.
+
+```bash
+# Full guide
+aiflow guide
+
+# Architecture & flow only
+aiflow guide --flow
+
+# Command reference only
+aiflow guide --commands
+```
+
+**Options:**
+- `--flow` — Show architecture & flow diagram only
+- `--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)
+
+---
+
 ## Global Options
 
 These work with any command:
 
 ```bash
-aiflow <command> --version       # Show version
-aiflow <command> --verbose       # Verbose output
-aiflow <command> --debug         # Debug mode
-aiflow <command> --config <file> # Use custom config file
+aiflow --version                 # Show installed version
+aiflow <command> --help          # Show help for a command
 ```
 
 ## Exit Codes

package/docs/developer-overview.md

@@ -1,126 +1,126 @@
-# AI Flow Kit — Developer Rollout Guide
-
-Welcome to the **AI Flow Kit**! This guide is designed to get you up and running with our standardized AI development workflow.
-
-## 1. What is AI Flow Kit?
-
-It's a "Zero-Config" framework for AI-assisted development. It automatically:
-- Pulls ticket context (requirements, comments) from Backlog/Jira.
-- Orchestrates a **5-Gate Workflow** (Analyze → Plan → Code → Review → PR).
-- Enforces team coding standards and architecture rules.
-- Synchronizes state across different AI tools (Claude, Cursor, Gemini).
-
----
-
-## 2. Prerequisites
-
-Before starting, ensure you have:
-1. **Node.js** (v18 or higher).
-2. **AI Tool(s)**:
-   - **Claude Code CLI** (Recommended for analysis and heavy tasks).
-   - **Cursor AI** (Recommended for coding and UI work).
-   - **Gemini CLI** or **GitHub Copilot** (Alternative options).
-
----
-
-## 3. Installation
-
-Run this command to install the CLI tool globally:
-
-```bash
-# Stable version
-npm install -g @relipa/ai-flow-kit
-
-# Beta version (recommend for newest features)
-npm install -g @relipa/ai-flow-kit@beta
-
-# Verification
-aiflow --version
-
-# Uninstall
-npm uninstall -g @relipa/ai-flow-kit
-
----
-
-## 4. First-time Setup
-
-In your project root, run:
-
-```bash
-aiflow init --framework [your-framework] --adapter [backlog/jira]
-```
-*Example: `aiflow init --framework nestjs --adapter backlog`*
-
-**What this does:**
-1. Verifies your API keys.
-2. Creates instruction files: `CLAUDE.md`, `.cursorrules`, `GEMINI.md`.
-3. Installs "Superpowers" skills.
-
----
-
-## 5. Daily Task Workflow (The 5 Gates)
-
-### Step 1: Start a Task
-Load the ticket context from your issue tracker:
-```bash
-aiflow use PROJ-33
-```
-
-### Step 2: Open your AI Tool
-- **Claude Code**: Type `claude`. The AI will automatically start **Gate 1**.
-- **Cursor**: Just start chatting with Cursor. It will detect the active ticket and start analyzing.
-
-### Step 3: Follow the Gates
-The AI *must* pass each gate in order. You act as the **Reviewer**.
-
-1. **⛩️ Gate 1: Requirement Analysis**
-   - AI reads code + ticket.
-   - AI outputs `plan/PROJ-33/requirement.md`.
-   - **Your Action**: Read the doc. If OK, type `APPROVED`.
-
-2. **⛩️ Gate 2: Implementation Plan**
-   - AI creates a step-by-step TDD plan.
-   - **Your Action**: Type `APPROVED` to start coding.
-
-3. **⛩️ Gate 3: Coding (TDD)**
-   - AI writes tests first, then code.
-   - **Your Action**: Monitor.
-
-4. **⛩️ Gate 4: Self-Review**
-   - AI verifies tests and checks a review-checklist.
-   - **Your Action**: Review the final diff. If OK, type `APPROVED`.
-
-5. **⛩️ Gate 5: Pull Request**
-   - AI helps you write a detailed PR description.
-   - **Your Action**: Create the PR and ask for a peer review.
-
----
-
-## 6. Switching AI Tools Mid-Task
-
-You can switch tools at any time because the "brain" (the State) is stored in your project files.
-
-**Example Scenario:**
-1. Use **Claude Code CLI** for **Gate 1** (Analysis) because it's great at exploring many files.
-2. Once you type `APPROVED`, close Claude.
-3. Open **Cursor** for **Gate 3** (Coding) to take advantage of its excellent editor integration. Cursor will see you've already finished the analysis and will continue from the plan.
-
----
-
-## 7. Best Practices
-
-- **One question at a time**: If the AI asks 5 questions, answer them one by one or ignore the irrelevant ones.
-- **Small commits**: Let the AI commit frequently (default behavior).
-- **Be the Pilot**: The AI is your co-pilot. If its solution looks over-engineered, tell it: *"Simplify this by using [X] pattern"*.
-
----
-
-## 8. Troubleshooting
-
-- **AI is stuck**: Type `reset context` or use `aiflow doctor` to check setup.
-- **Credentials fail**: Re-run `aiflow init --adapter backlog` to update keys.
-- **Rules not followed**: Remind the AI: *"Follow the rules in CLAUDE.md"*.
-
----
-
-**Happy Coding!** สำหรับรายละเอียดเชิงลึก โปรดดู [AIFLOW.md](../AIFLOW.md).
+# AI Flow Kit — Developer Rollout Guide
+
+Welcome to the **AI Flow Kit**! This guide is designed to get you up and running with our standardized AI development workflow.
+
+## 1. What is AI Flow Kit?
+
+It's a "Zero-Config" framework for AI-assisted development. It automatically:
+- Pulls ticket context (requirements, comments) from Backlog/Jira.
+- Orchestrates a **5-Gate Workflow** (Analyze → Plan → Code → Review → PR).
+- Enforces team coding standards and architecture rules.
+- Synchronizes state across different AI tools (Claude, Cursor, Gemini).
+
+---
+
+## 2. Prerequisites
+
+Before starting, ensure you have:
+1. **Node.js** (v18 or higher).
+2. **AI Tool(s)**:
+   - **Claude Code CLI** (Recommended for analysis and heavy tasks).
+   - **Cursor AI** (Recommended for coding and UI work).
+   - **Gemini CLI** or **GitHub Copilot** (Alternative options).
+
+---
+
+## 3. Installation
+
+Run this command to install the CLI tool globally:
+
+```bash
+# Stable version
+npm install -g @relipa/ai-flow-kit
+
+# Beta version (recommend for newest features)
+npm install -g @relipa/ai-flow-kit@beta
+
+# Verification
+aiflow --version
+
+# Uninstall
+npm uninstall -g @relipa/ai-flow-kit
+
+---
+
+## 4. First-time Setup
+
+In your project root, run:
+
+```bash
+aiflow init --framework [your-framework] --adapter [backlog/jira]
+```
+*Example: `aiflow init --framework nestjs --adapter backlog`*
+
+**What this does:**
+1. Verifies your API keys.
+2. Creates instruction files: `CLAUDE.md`, `.cursorrules`, `GEMINI.md`.
+3. Installs "Superpowers" skills.
+
+---
+
+## 5. Daily Task Workflow (The 5 Gates)
+
+### Step 1: Start a Task
+Load the ticket context from your issue tracker:
+```bash
+aiflow use PROJ-33
+```
+
+### Step 2: Open your AI Tool
+- **Claude Code**: Type `claude`. The AI will automatically start **Gate 1**.
+- **Cursor**: Just start chatting with Cursor. It will detect the active ticket and start analyzing.
+
+### Step 3: Follow the Gates
+The AI *must* pass each gate in order. You act as the **Reviewer**.
+
+1. **⛩️ Gate 1: Requirement Analysis**
+   - AI reads code + ticket.
+   - AI outputs `plan/PROJ-33/requirement.md`.
+   - **Your Action**: Read the doc. If OK, type `APPROVED`.
+
+2. **⛩️ Gate 2: Implementation Plan**
+   - AI creates a step-by-step TDD plan.
+   - **Your Action**: Type `APPROVED` to start coding.
+
+3. **⛩️ Gate 3: Coding (TDD)**
+   - AI writes tests first, then code.
+   - **Your Action**: Monitor.
+
+4. **⛩️ Gate 4: Self-Review**
+   - AI verifies tests and checks a review-checklist.
+   - **Your Action**: Review the final diff. If OK, type `APPROVED`.
+
+5. **⛩️ Gate 5: Pull Request**
+   - AI helps you write a detailed PR description.
+   - **Your Action**: Create the PR and ask for a peer review.
+
+---
+
+## 6. Switching AI Tools Mid-Task
+
+You can switch tools at any time because the "brain" (the State) is stored in your project files.
+
+**Example Scenario:**
+1. Use **Claude Code CLI** for **Gate 1** (Analysis) because it's great at exploring many files.
+2. Once you type `APPROVED`, close Claude.
+3. Open **Cursor** for **Gate 3** (Coding) to take advantage of its excellent editor integration. Cursor will see you've already finished the analysis and will continue from the plan.
+
+---
+
+## 7. Best Practices
+
+- **One question at a time**: If the AI asks 5 questions, answer them one by one or ignore the irrelevant ones.
+- **Small commits**: Let the AI commit frequently (default behavior).
+- **Be the Pilot**: The AI is your co-pilot. If its solution looks over-engineered, tell it: *"Simplify this by using [X] pattern"*.
+
+---
+
+## 8. Troubleshooting
+
+- **AI is stuck**: Type `reset context` or use `aiflow doctor` to check setup.
+- **Credentials fail**: Re-run `aiflow init --adapter backlog` to update keys.
+- **Rules not followed**: Remind the AI: *"Follow the rules in CLAUDE.md"*.
+
+---
+
+**Happy Coding!** สำหรับรายละเอียดเชิงลึก โปรดดู [AIFLOW.md](../AIFLOW.md).

package/docs/troubleshooting.md

@@ -545,6 +545,21 @@ cat CLAUDE.md | grep -i "rule"
 - Close and reopen
 - Run `aiflow doctor` to verify setup
 
+## Telemetry Tracking
+
+### "Telemetry connection test failed"
+
+**Verify Apps Script settings:**
+- Ensure the Apps Script Web App is deployed and accessible.
+- Ensure the `TEAM_SECRET` is exactly correct without trailing spaces.
+
+**Bypass / Opt-out locally:**
+If you don't want telemetry tracked on a specific repo, or the upload is failing constantly:
+```bash
+touch .aiflow/no-telemetry
+# CLI will automatically ignore logging for this repo.
+```
+
 ---
 
 ## Getting More Help

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.0.4-beta.3",
+  "version": "0.0.5-beta.0",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Relipa AI Team",
   "publishConfig": {
@@ -14,19 +14,14 @@
     "aiflow": "./bin/aiflow.js"
   },
   "files": [
+    "README.md",
     "bin",
     "custom",
     "scripts",
     "upstream",
     "docs",
     "package.json",
-    "index.js",
-    "README.md",
-    "QUICK_START.md",
-    "AIFLOW.md",
-    "CONTRIBUTING.md",
-    "IMPLEMENTATION_SUMMARY.md",
-    "CHANGELOG.md"
+    "index.js"
   ],
   "keywords": [
     "ai",
@@ -39,7 +34,7 @@
     "productivity"
   ],
   "engines": {
-    "node": ">=14.0.0",
+    "node": ">=16.0.0",
     "npm": ">=6.0.0"
   },
   "scripts": {
@@ -51,9 +46,9 @@
     "publish:stable": "npm publish"
   },
   "dependencies": {
-    "@inquirer/prompts": "^8.3.2",
+    "@inquirer/prompts": "^3.0.0",
     "chalk": "^4.1.2",
-    "commander": "^14.0.3",
+    "commander": "^11.0.0",
     "fs-extra": "^11.3.4",
     "semver": "^7.7.4"
   },

package/scripts/guide.js

@@ -210,6 +210,22 @@ function showCommands() {
                 ['aiflow validate <file>', '-r strict', 'Report all warnings'],
             ]
         },
+        {
+            group: 'Telemetry',
+            items: [
+                ['aiflow telemetry status', '', 'View telemetry status'],
+                ['aiflow telemetry enable', '', 'Enable usage tracking'],
+                ['aiflow telemetry disable', '', 'Disable usage tracking'],
+                ['aiflow telemetry flush', '', 'Force-send buffered events now'],
+            ]
+        },
+        {
+            group: 'AI Workflow Integration',
+            items: [
+                ['aiflow gate <n> start', '--ticket <id>', 'Log gate N started (AI calls this)'],
+                ['aiflow gate <n> approved', '--ticket <id>', 'Log gate N approved (AI calls this)'],
+            ]
+        },
         {
             group: 'Help',
             items: [

package/scripts/hooks/session-start.js

@@ -9,6 +9,10 @@
 
 const fs = require('fs');
 const path = require('path');
+const { record } = require('../telemetry/record');
+
+// Record session start telemetry
+record('session.start');
 
 // This script lives at .claude/hooks/session-start.js
 // Project root is 3 levels up
@@ -138,4 +142,4 @@ function buildContextPrompt(ctx) {
     lines.push('</ACTIVE_TASK>');
 
     return lines.join('\n');
-}
+}