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

package/{docs/README.md → README.md}

@@ -23,11 +23,11 @@ Developers only need a single command to load ticket context → AI automaticall
 > [!TIP]
 > After running `aiflow init`, all documentation files are automatically copied to your project root and `.aiflow/docs/` for easy access.
 
-- **[Quick Start Guide](./QUICK_START.md)** — Step-by-step instructions for developers.
-- **[Full Workflow (5 Gates)](./AIFLOW.md)** — In-depth look at the Gate process.
-- **[Developer Onboarding](./developer-overview.md)** — Presentation-ready guide for new team members.
-- **[Troubleshooting](./troubleshooting.md)** — Common issues and fixes.
-- **[Integration Guide](./ai-integration.md)** — Advanced tool setup (Claude, Cursor, Gemini).
+- **[Quick Start Guide](./docs/QUICK_START.md)** — Step-by-step instructions for developers.
+- **[Full Workflow (5 Gates)](./docs/AIFLOW.md)** — In-depth look at the Gate process.
+- **[Developer Onboarding](./docs/developer-overview.md)** — Presentation-ready guide for new team members.
+- **[Troubleshooting](./docs/troubleshooting.md)** — Common issues and fixes.
+- **[Integration Guide](./docs/ai-integration.md)** — Advanced tool setup (Claude, Cursor, Gemini).
 
 ---
 
@@ -122,6 +122,7 @@ npm uninstall -g @relipa/ai-flow-kit
 | `aiflow init` | Setup framework, adapters, and multi-AI rules. |
 | `aiflow use <ticket>` | Load ticket context (Backlog/Jira). |
 | `aiflow prompt` | Generate tool-optimized prompts (`--env cursor`). |
+| `aiflow telemetry` | Manage telemetry tracking (enable/disable/status). |
 | `aiflow guide` | View integrated multi-AI integration guide. |
 
 ### `aiflow init`
@@ -280,9 +281,9 @@ aiflow memory --list
 
 ```
 ai-flow-kit/
+├── README.md                        # Main documentation
 ├── bin/aiflow.js                    # CLI entry
 ├── docs/                            # Documentation and Guides
-│   ├── README.md                    # Main documentation
 │   ├── QUICK_START.md               # Quick start guide
 │   ├── AIFLOW.md                    # Workflow (5 Gates) detail
 │   ├── CHANGELOG.md                 # Version history
@@ -352,4 +353,4 @@ aiflow init --adapter backlog
 aiflow doctor
 ```
 
-See more: [docs/troubleshooting.md](./troubleshooting.md)
+See more: [docs/troubleshooting.md](./docs/troubleshooting.md)

package/bin/aiflow.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const { program } = require('commander');
 const chalk = require('chalk');
@@ -14,11 +14,45 @@ const contextCommand  = require('../scripts/context');
 const promptCommand   = require('../scripts/prompt');
 const removeCommand   = require('../scripts/remove');
 const guideCommand    = require('../scripts/guide');
+const telemetryCommand= require('../scripts/telemetry/cli');
+const { record }      = require('../scripts/telemetry/record');
 
 program
     .version(packageJson.version)
     .description('AI Flow Kit CLI - AI-powered development workflows for teams');
 
+// ── GLOBAL TELEMETRY HOOK ────────────────────────────────────
+// We intercept raw argv here so we can catch --version, --help, 
+// and invalid commands *before* Commander exits the process.
+(() => {
+    const args = process.argv.slice(2);
+    let cmd = 'help';
+    if (args.length > 0) {
+        const first = args[0];
+        if (['-V', '-v', '--version'].includes(first)) {
+            cmd = 'version';
+        } else if (['-h', '--help'].includes(first)) {
+            cmd = 'help';
+        } else if (first.startsWith('-')) {
+            cmd = 'unknown_flag';
+            if (args.includes('--help') || args.includes('-h')) cmd = 'help';
+        } else if (first === 'memory') {
+            const sec = args[1];
+            cmd = (sec && !sec.startsWith('-')) ? `memory.${sec}` : 'memory';
+        } else {
+            cmd = first;
+            if (args.includes('--help') || args.includes('-h')) {
+                cmd = `${first}.help`;
+            }
+        }
+    }
+    // Record everything except telemetry and gate actions (gate records its own rich event)
+    if (cmd !== 'telemetry' && !cmd.startsWith('telemetry.') && cmd !== 'gate') {
+        record('command.invoked', { command: cmd });
+    }
+})();
+
+
 // ── init ──────────────────────────────────────────────────────
 program
     .command('init')
@@ -37,6 +71,7 @@ program
             ? options.env.split(',').map(s => s.trim()).filter(Boolean)
             : Object.keys(require('../scripts/init').AI_TOOL_FILES || {});
 
+        record('command.invoked', { command: 'init' });
         initCommand(options);
     });
 
@@ -51,6 +86,7 @@ program
     .option('--comments-last <n>', 'load only the last N comments', parseInt)
     .option('--comments-from <n>', 'load comments from index N onward (0-based)', parseInt)
     .action((target, options) => {
+        record('command.invoked', { command: 'use' });
         useCommand(target, options);
     });
 
@@ -63,6 +99,7 @@ program
     .option('--lang <lang>', 'language: english (default) or vietnamese')
     .option('--detail <level>', 'detail level: minimal | standard (default) | comprehensive')
     .action((type, options) => {
+        record('command.invoked', { command: 'prompt' });
         promptCommand(type, options);
     });
 
@@ -73,6 +110,7 @@ program
     .option('-v, --verbose', 'show detection details')
     .option('-t, --threshold <number>', 'confidence threshold (0-100)')
     .action((description, options) => {
+        record('command.invoked', { command: 'detect' });
         const detector = new TaskDetector();
         const threshold = options.threshold ? parseInt(options.threshold) / 100 : 0.8;
         const result = detector.detect(description, threshold);
@@ -90,6 +128,7 @@ program
     .option('--clear', 'clear all saved contexts')
     .option('--show', 'show current context')
     .action((action, options) => {
+        record('command.invoked', { command: 'context' });
         contextCommand(action, options);
     });
 
@@ -101,6 +140,7 @@ program
     .option('-v, --verbose', 'detailed report')
     .option('--fix', 'auto-fix trailing whitespace')
     .action((file, options) => {
+        record('command.invoked', { command: 'validate' });
         validateCommand(file, {
             ruleset: options.ruleset,
             verbose: options.verbose,
@@ -115,32 +155,32 @@ const memCmd = program.command('memory').description('Manage team knowledge and
 memCmd
     .command('save <key> <value>')
     .description('Save a memory entry')
-    .action((key, value) => memoryCommand('save', { key, value }));
+    .action((key, value) => { record('command.invoked', { command: 'memory.save' }); memoryCommand('save', { key, value }); });
 
 memCmd
     .command('get <key>')
     .description('Retrieve a memory entry')
-    .action((key) => memoryCommand('get', { key }));
+    .action((key) => { record('command.invoked', { command: 'memory.get' }); memoryCommand('get', { key }); });
 
 memCmd
     .command('list')
     .description('List all memories')
-    .action(() => memoryCommand('list'));
+    .action(() => { record('command.invoked', { command: 'memory.list' }); memoryCommand('list'); });
 
 memCmd
     .command('search <query>')
     .description('Search memories by keyword')
-    .action((query) => memoryCommand('search', { query }));
+    .action((query) => { record('command.invoked', { command: 'memory.search' }); memoryCommand('search', { query }); });
 
 memCmd
     .command('delete <key>')
     .description('Delete a memory entry')
-    .action((key) => memoryCommand('delete', { key }));
+    .action((key) => { record('command.invoked', { command: 'memory.delete' }); memoryCommand('delete', { key }); });
 
 memCmd
     .command('clear')
     .description('Clear all memories')
-    .action(() => memoryCommand('clear'));
+    .action(() => { record('command.invoked', { command: 'memory.clear' }); memoryCommand('clear'); });
 
 // ── guide ─────────────────────────────────────────────────────
 program
@@ -149,9 +189,28 @@ program
     .option('--flow', 'show architecture & flow diagram only')
     .option('--commands', 'show command reference only')
     .action((options) => {
+        record('command.invoked', { command: 'guide' });
         guideCommand(options);
     });
 
+// ── gate (telemetry for gate workflow events) ─────────────────
+program
+    .command('gate <number> <action>')
+    .description('Log a gate workflow event (start|approved) — called by AI during gate workflow')
+    .option('--ticket <id>', 'ticket ID')
+    .option('--ai-tool <tool>', 'AI tool name')
+    .action((number, action, options) => {
+        const gateNum = parseInt(number);
+        if (isNaN(gateNum) || gateNum < 1 || gateNum > 5) return;
+        if (!['start', 'approved'].includes(action)) return;
+        record(`gate.${action}`, {
+            gate: gateNum,
+            ticket_id: options.ticket || '',
+            command: `gate${gateNum}.${action}`,
+            ai_tool: options.aiTool || ''
+        });
+    });
+
 // ── remove ────────────────────────────────────────────────────
 program
     .command('remove')
@@ -159,6 +218,7 @@ program
     .option('--version <ver>', 'remove a specific cached version from .aiflow/versions/')
     .option('--global', 'uninstall the global npm package (removes `aiflow` command)')
     .action((options) => {
+        record('command.invoked', { command: 'remove' });
         removeCommand(options);
     });
 
@@ -168,6 +228,7 @@ program
     .description('Update to latest version')
     .option('--force', 'force update even if already on latest')
     .action((options) => {
+        record('command.invoked', { command: 'update' });
         updateCommand(options);
     });
 
@@ -177,7 +238,16 @@ program
     .description('Health check of AI Flow Kit setup')
     .option('-v, --verbose', 'detailed output')
     .action(() => {
+        record('command.invoked', { command: 'doctor' });
         doctorCommand();
     });
 
+// ── telemetry ──────────────────────────────────────────────────
+program
+    .command('telemetry [action]')
+    .description('Manage telemetry logging (enable|disable|status)')
+    .action((action) => {
+        telemetryCommand(action || 'status');
+    });
+
 program.parse(process.argv);

package/custom/templates/shared/gate-workflow.md

@@ -28,6 +28,9 @@ AI actively reads ticket + source code to understand the requirement:
 
 DO NOT just check format — **understand the content and propose solutions**.
 
+> **Telemetry:** Run `aiflow gate 1 start --ticket [ticket-id]` when starting this gate (auto-start or when developer types "start"/"Gate 1").
+> Run `aiflow gate 1 approved --ticket [ticket-id]` immediately when APPROVED is received.
+
 ---
 
 ### GATE 2 — Implementation Plan (wait for APPROVED)
@@ -38,6 +41,9 @@ DO NOT just check format — **understand the content and propose solutions**.
 - Display: "GATE 2 PAUSED: type APPROVED to start coding".
 - CODE WILL NOT BE GENERATED until "APPROVED" is received.
 
+> **Telemetry:** Run `aiflow gate 2 start --ticket [ticket-id]` when starting this gate.
+> Run `aiflow gate 2 approved --ticket [ticket-id]` immediately when APPROVED is received.
+
 ---
 
 ### GATE 3 — Code Generation (TDD only)
@@ -49,6 +55,8 @@ Only runs after Gate 2 has been APPROVED.
 - Write tests FIRST — run to confirm FAIL -> implement -> PASS.
 - Bug fix EXTRA: `superpowers:systematic-debugging` + `investigate-bug` skill first.
 
+> **Telemetry:** Run `aiflow gate 3 start --ticket [ticket-id]` when starting this gate.
+
 ---
 
 ### GATE 4 — AI Self-Review (wait for APPROVED)
@@ -65,6 +73,9 @@ Then: "GATE 4 PAUSED: type APPROVED or BUG: [description]"
 - Coding bug -> fix -> repeat Gate 4.
 - Requirement bug -> return to Gate 1.
 
+> **Telemetry:** Run `aiflow gate 4 start --ticket [ticket-id]` when starting this gate.
+> Run `aiflow gate 4 approved --ticket [ticket-id]` immediately when APPROVED is received.
+
 ---
 
 ### GATE 5 — Peer Review and Done
@@ -73,3 +84,5 @@ Only runs after Gate 4 has been APPROVED.
 
 **INVOKE:** `superpowers:requesting-code-review`
 Guide on creating a Pull Request with the ticket link.
+
+> **Telemetry:** Run `aiflow gate 5 start --ticket [ticket-id]` when starting this gate.

package/docs/AIFLOW.md

@@ -409,6 +409,11 @@ aiflow context show                   # view active context
 aiflow memory save "key" "value"      # save team knowledge
 aiflow doctor                         # health check
 aiflow guide                          # view quickstart guide
+
+# Telemetry (team leads)
+aiflow telemetry status               # view status
+aiflow telemetry enable               # setup tracking
+aiflow telemetry disable              # disable tracking
 ```
 
 ---

package/docs/CHANGELOG.md

@@ -21,10 +21,38 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
-## [Unreleased]
+## [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
+- **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.

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/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",
+  "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,6 +14,7 @@
     "aiflow": "./bin/aiflow.js"
   },
   "files": [
+    "README.md",
     "bin",
     "custom",
     "scripts",
@@ -33,7 +34,7 @@
     "productivity"
   ],
   "engines": {
-    "node": ">=14.0.0",
+    "node": ">=16.0.0",
     "npm": ">=6.0.0"
   },
   "scripts": {
@@ -45,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