@relipa/ai-flow-kit 0.1.7 → 0.1.8

package/docs/common/Project-Structure.md

@@ -0,0 +1,133 @@
+# Project Folder Structure
+
+> Cấu trúc thư mục chuẩn cho toàn dự án PILOT — áp dụng cho tất cả role: BA, Dev, Tester, PM/BrSE.
+
+---
+
+## Tổng quan
+
+```
+{Root}/                                 ← Thư mục mở bằng VSCode, có thể chứa nhiều source repo
+├── {Source-Repo}/                      ← Source code (GitLab repo)
+│
+├── AK-Docs/                            ← Tài liệu dự án (GitLab repo riêng)
+│   ├── 00.Project-Overview/
+│   ├── 01.QnA/
+│   ├── 02.BA-Specs/
+│   ├── 03.Testing/
+│   └── 04.Coding/
+│
+└── Shared-Docs/                        ← Template dùng chung cho TẤT CẢ dự án (GitLab repo riêng)
+    ├── Spec-Templates/
+    ├── QA-Templates/
+    ├── Testcase-Templates/
+    └── Test-Report-Templates/
+```
+
+> **Tự động đồng bộ:** Mỗi lần chạy `ak init` hoặc `ak update`, tool sẽ tự kiểm tra `AK-Docs/` và `Shared-Docs/` cạnh source repo — nếu đã tồn tại (và là git repo) sẽ tự `git pull` để lấy bản mới nhất, nếu chưa có sẽ cảnh báo (warning) để bạn clone thủ công.
+
+---
+
+## Chi tiết — `AK-Docs/`
+
+```
+AK-Docs/
+│
+├── 00.Project-Overview/                ← PM / BrSE quản lý
+│   ├── Project-Summary.md              # Goals, scope, background, stack
+│   ├── Function-List.md                # F-ID | Feature | BA | Dev | Tester | Status
+│   └── Team.md                         # Member, role, contact
+│
+├── 01.QnA/                             ← Trao đổi với khách hàng (có comtor)
+│   └── QnA-Log.md                      # 1 file duy nhất cho toàn dự án
+│
+├── 02.BA-Specs/                        ← BA quản lý
+│   ├── 00.Requirements/                # Requirements Gathering
+│   ├── 01.Analysis/                    # Gate 1: Business Analysis
+│   ├── 02.QnA/                         # Gate 2: Q&A nội bộ với stakeholder
+│   ├── 03.UI-Prototypes/               # Gate 3: UI/UX Design
+│   └── 04.UC-Specs/                    # Gate 4: Final UC Specification
+│
+├── 03.Testing/                         ← Tester quản lý
+│   ├── 00.Strategies/                  # Test strategy & approach
+│   ├── 01.Testcases/                   # Gate 2: Test cases per feature
+│   ├── 02.Reports/                     # Gate 4: Execution & regression reports
+│   ├── 03.Test-Data/                   # Test data: CSV, JSON, SQL fixtures
+│   ├── 04.Evidence/                    # Gate 3: Screenshots, videos, logs
+│   ├── 05.Scripts/                     # Playwright automation scripts
+│   ├── 06.Bugs/                        # Gate 3: Bug reports
+│   └── 07.AI-Artifacts/               # AI working docs: Gate 1-2 outputs
+│
+└── 04.Coding/                          ← Dev quản lý
+    ├── 00.Overview/                    # Tracker tổng: F-ID | Ticket | Dev | Gate | PR
+    ├── 01.Requirements/                # Gate 1: AI phân tích ticket + source code
+    ├── 02.Plans/                       # Gate 2: TDD implementation plan
+    ├── 03.TDD-Notes/                   # Gate 3: Test list viết trước + notes
+    ├── 04.Reviews/                     # Gate 4: Self-review + impact analysis
+    └── 05.Pull-Requests/               # Gate 5: PR content + review checklist
+```
+
+---
+
+## Chi tiết — `Shared-Docs/`
+
+> Repo dùng chung cho **TẤT CẢ dự án** — chỉ chứa template gốc, không chứa tài liệu của riêng dự án nào. Chỉ AI Testing Team mới có quyền chỉnh sửa.
+
+| Thư mục | Nội dung |
+|---|---|
+| `Spec-Templates/` | Template UC Spec cho BA (Gate 1→4 của `create-spec` workflow) |
+| `QA-Templates/` | Template chiến lược test, checklist review cho Tester |
+| `Testcase-Templates/` | Template bộ Test Case (Gate 1→4 của `create-testcase` workflow) |
+| `Test-Report-Templates/` | Template báo cáo thực thi test (execution report, regression report) |
+
+Mỗi dự án khi cần tạo tài liệu mới (UC Spec, Test Case, Test Report...) sẽ copy template tương ứng từ `Shared-Docs/` về đúng thư mục trong `AK-Docs/` của dự án đó rồi điền nội dung.
+
+---
+
+## Quy tắc đặt tên
+
+| Element | Convention | Ví dụ |
+|---|---|---|
+| Section folder | `{N}.{Pascal-Case}/` | `00.Requirements/`, `03.TDD-Notes/` |
+| Feature folder | `F-{3-digit}_{Pascal-Case}/` | `F-001_User-Login/` |
+| File có version | `{Pascal-Name}_v{N}.md` | `UC-Spec_v2.md` |
+| File theo ticket | `TICKET-{ID}.md` | `TICKET-100.md` |
+| File archive | `_archive/` subfolder | `04.UC-Specs/F-001/_archive/` |
+
+---
+
+## Ai lưu tài liệu ở đâu, khi nào
+
+| Vai trò | Lưu vào | Thời điểm |
+|---|---|---|
+| PM / BrSE | `00.Project-Overview/` | Đầu dự án + mỗi sprint |
+| BA / PM / Comtor | `01.QnA/QnA-Log.md` | Khi có câu hỏi từ khách hàng |
+| BA | `02.BA-Specs/` | Sau khi Gate 4 APPROVED |
+| Tester | `03.Testing/` | Sau khi Gate 4 APPROVED |
+| Dev | `04.Coding/` | Trước khi tạo Pull Request |
+
+---
+
+## Luồng tài liệu qua từng vai trò
+
+```
+PM tạo ticket (Backlog/Jira)
+      │
+      ▼
+[BA] ak use TICKET-123
+  → 02.BA-Specs/ (Gate 1→4)
+  → Thông báo Dev + Tester sau Gate 4 APPROVED
+      │
+      ├──────────────────────────────────┐
+      ▼                                  ▼
+[Tester] Extension sidebar           [Dev] ak use TICKET-123
+  → 03.Testing/ (Gate 1→4)             → 04.Coding/ (Gate 1→5)
+      │                                  │
+      └──────────────┬───────────────────┘
+                     ▼
+              Pull Request
+              link: UC Spec + Test Case + Dev Plan
+                     │
+                     ▼
+              [PM] Gate 4 Tester → Go / No-Go
+```

package/docs/common/Testing-Structure.md

@@ -0,0 +1,124 @@
+# Testing — Folder Structure
+
+> **Managed by:** Tester  
+> **Organized by:** Output Type → Function-ID (Scripts: Repo → Function-ID)  
+> **Naming:** Function-ID format `F-001_User-Login`, Evidence by `TICKET-ID_Date`  
+> **Note:** Templates are managed in a separate shared repo.
+
+---
+
+## Folder Tree
+
+```
+03.Testing/
+│
+├── 00.Strategies/                          # Test strategy & approach (project-level)
+│   ├── Overview.md
+│   ├── Regression-Strategy.md
+│   └── Execution-Strategy.md
+│
+├── 01.Testcases/                           # Gate 2: Test cases per feature
+│   └── F-001_User-Login/
+│       ├── Testcase_v2.md                  # Current version
+│       └── _archive/
+│           └── Testcase_v1.md
+│
+├── 02.Reports/                             # Gate 4: Execution & regression reports
+│   ├── F-001_User-Login/
+│   │   ├── TICKET-100/
+│   │   │   ├── Execution-Report.md
+│   │   │   └── Bug-Summary.md
+│   │   └── TICKET-100_Retest/
+│   │       └── Execution-Report.md
+│   └── Regression/                         # Regression runs per sprint
+│       └── Sprint-01_Regression.md
+│
+├── 03.Test-Data/                           # Test data: CSV, JSON, SQL fixtures
+│   └── F-001_User-Login/
+│       ├── Users.csv
+│       └── Fixtures.sql
+│
+├── 04.Evidence/                            # Gate 3: Screenshots, videos, logs per execution
+│   └── F-001_User-Login/
+│       ├── TICKET-100_2026-06-15/          # Ticket + date to identify execution round
+│       │   ├── TC_001_PASS/
+│       │   │   └── Screenshot.png
+│       │   └── TC_002_FAIL/
+│       │       ├── Screenshot.png
+│       │       └── Video.mp4
+│       └── TICKET-100_Retest_2026-06-18/
+│           └── TC_002_PASS/
+│               └── Screenshot.png
+│
+├── 05.Scripts/                             # Playwright automation (by Repo → Feature)
+│   ├── Repo1/                              # e.g. frontend app
+│   │   ├── playwright.config.ts            # baseURL, browser config for this repo
+│   │   └── F-001_User-Login/
+│   │       └── Login.spec.ts
+│   ├── Repo2/                              # e.g. admin app
+│   │   ├── playwright.config.ts
+│   │   └── F-003_Admin-Panel/
+│   │       └── Admin.spec.ts
+│   └── Shared/                             # Fixtures, helpers used across repos
+│       ├── Fixtures.ts
+│       └── Helpers.ts
+│
+├── 06.Bugs/                                # Gate 3: Bug reports (AI draft on TC fail)
+│   └── F-001_User-Login/
+│       └── BUG-001_Login-Timeout.md
+│
+└── 07.AI-Artifacts/                        # AI working docs: Gate 1-2 outputs
+    └── F-001_User-Login/
+        ├── Gate1_Test-Analysis.md          # Gate 1: scope, flows, risks
+        ├── Gate2_QnA.md                    # Gate 2: Q&A clarification (internal)
+        └── Gate2_Coverage-Matrix.md        # Gate 2: coverage matrix
+```
+
+---
+
+## File Naming Convention
+
+| Element | Convention | Example |
+|---|---|---|
+| Section folder | `{N}.{Pascal-Case}/` | `00.Strategies/`, `04.Evidence/` |
+| Feature folder | `F-{3-digit}_{Pascal-Case}/` | `F-001_User-Login/` |
+| Testcase file | `Testcase_v{N}.md` | `Testcase_v2.md` |
+| Evidence folder | `TICKET-{ID}_{YYYY-MM-DD}/` | `TICKET-100_2026-06-15/` |
+| Retest folder | `TICKET-{ID}_Retest_{YYYY-MM-DD}/` | `TICKET-100_Retest_2026-06-18/` |
+| TC result folder | `TC_{ID}_{PASS\|FAIL}/` | `TC_001_PASS/` |
+| Bug file | `BUG-{ID}_{Pascal-Description}.md` | `BUG-001_Login-Timeout.md` |
+| Script config | `playwright.config.ts` | per Repo folder |
+| Script file | `{Feature}.spec.ts` | `Login.spec.ts` |
+| Archive folder | `_archive/` | inside feature folder |
+
+---
+
+## Gate → Folder Mapping
+
+### 1. Quy trình Tạo Test Case (`create-testcase`)
+
+| Gate | Output | Folder |
+|---|---|---|
+| Gate 1 | Phân tích yêu cầu & Đánh giá rủi ro | `07.AI-Artifacts/[functionId]_01_Requirement_Analysis_Result.md` |
+| Gate 2 | Xây dựng kịch bản (Scenarios) | `07.AI-Artifacts/[functionId]_02_Test_Scenarios_Result.md` |
+| Gate 3 | Thiết kế Test Case chi tiết (Draft) | `07.AI-Artifacts/[functionId]_03_Test_Cases_Draft_Result.md` |
+| Gate 4 | Review & Tối ưu hóa (TestCase chính thức) | `01.Testcases/[Feature]/[functionId]_TestCase.md` & `07.AI-Artifacts/[functionId]_04_Test_Cases_Final_Result.md` |
+
+### 2. Quy trình Thực thi Test (`execute-test`)
+
+| Gate | Output | Folder |
+|---|---|---|
+| Gate 1 | Chuẩn bị & Lập kế hoạch thực thi | (Console output / Work Plan) |
+| Gate 2 | Đồng bộ kịch bản kiểm thử (Script Sync) | `05.Scripts/[Repo]/[Feature]/[Feature].spec.ts` |
+| Gate 3 | Thực thi test & Thu thập evidence | `04.Evidence/[Feature]/[Ticket]_[Date]/` & `06.Bugs/[Feature]/` |
+| Gate 4 | Báo cáo test & Log bug | `02.Reports/[Feature]/[Ticket]/Execution-Report.md` |
+
+---
+
+## Rules
+
+- Không tự sửa template — template nằm trong shared repo riêng
+- Lưu testcase và kết quả lên GitLab **sau khi Gate 4 được APPROVED**
+- Khi retest: tạo subfolder `TICKET-XXX_Retest_Date/` mới trong Evidence — không ghi đè cũ
+- `05.Scripts/` chỉ chứa `.spec.ts` và `playwright.config.ts` — không chứa testcase `.md`
+- `07.AI-Artifacts/` là working docs của AI — không phải tài liệu chính thức

package/docs/common/cli-reference.md

@@ -24,15 +24,16 @@ ak <alias> --help                # Also works with aliases
 | `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` |
+| `ak ask` | `ak ask` | | |
 
 | `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 status` | `ak t st` | `ak mem draft` | `ak mem d` |
+| `ak t list` | `ak t ls` | `ak mem list` | `ak mem ls` |
+| `ak t pause` | `ak t p` | `ak mem submit` | `ak mem sb` |
+| `ak t switch` | `ak t sw` | `ak mem remove` | `ak mem rm` |
+| `ak t resume` | `ak t r` | | |
+| `ak t reset` | `ak t rst` | | |
 | `ak t remove` | `ak t rm` | | |
 | `ak t next` | `ak t n` | | |
 
@@ -588,39 +589,53 @@ ak tel flush                                 # force-send buffered events now
 
 ## memory (alias: `mem`)
 
-Manage team knowledge and context memory.
+Manage the `99.Memory/` Project Brain — a git-based, human-approved team knowledge base living inside `AK-Docs/99.Memory/`. AI (or you) drafts a memory locally, then submits it as a Merge Request for a teammate/PM to approve. See `docs/common/Memory-Architecture-v1.0.md` for the full design.
+
+> **Note:** This replaces the older `.aiflow/memory/` JSON store (`save/get/search/delete/clear`) retired in v0.1.7 — that command set no longer exists.
 
 ```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)
+ak mem d -c 01.Lessons/dev -s prevent-429-error --content "Retry with backoff on 429 from payment gateway" -t payment,retry
+ak mem ls                                    # list local pending drafts  (memory list)
+ak mem ls -a                                 # list team-approved memories  (--approved)
+ak mem sb 01.Lessons/dev/prevent-429-error.md -t "Add memory: prevent-429-error"   # submit a draft (memory submit)
+ak mem rm 01.Lessons/dev/prevent-429-error.md -t "Remove stale memory" --reason "no longer applies"   # (memory remove)
 ```
 
 **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
+- `draft|d --category <cat> --slug <slug> --content <text> [options]` — Create a local memory draft in `_pending/` (not yet shared with the team)
+  - `-c, --category <cat>` — e.g. `00.Shared/architecture`, `01.Lessons/dev`, `02.Instincts/approved`
+  - `-s, --slug <slug>` — short kebab-case name, e.g. `prevent-429-error`
+  - `--content <text>` — memory body (≤150 words, 1 fact)
+  - `-f, --function-id <id>` — functionId this memory is scoped to (omit for a global/cross-project fact)
+  - `--scope <scope>` — alternative to `--function-id` for flat categories (glossary/decisions)
+  - `-t, --tags <list>` — comma-separated tags the scorer matches on
+  - `-w, --workflows <list>` — comma-separated workflows (coding, create-spec, create-testcase, gen-doc, all)
+  - `--source <text>` — ticket/Gate this was learned from
+  - `--confidence <n>` — AI self-rated 0.3–0.7 (default 0.5)
+- `list|ls [-a, --approved]` — List local pending drafts, or team-approved memories with `--approved`
+- `submit|sb <path> --title <title> [-d <desc>] [-y]` — Move a pending draft (path from `ak mem list`) to its destination in `AK-Docs/99.Memory/` and open a Merge Request
+- `remove|rm <path> --title <title> [--reason <text>] [--hard] [-y]` — Propose removing an approved memory (path from `ak mem list --approved`); soft-remove moves it to `_deprecated/`, `--hard` deletes it outright
 
 **What it does:**
-1. Stores team knowledge in `.aiflow/memory/`
-2. Makes knowledge discoverable across the team
+1. `draft` writes a frontmatter'd Markdown file to `AK-Docs/99.Memory/_pending/` on your machine only — recallable locally, but not yet shared with the team
+2. `submit` creates a branch in `AK-Docs`, moves the file out of `_pending/` to its real category path, commits, pushes, and opens a Merge Request (same branch+MR flow as `ak docs branch`/`ak docs submit`)
+3. A teammate (PM by convention) reviews and merges the MR — that's the point it becomes recallable for everyone else
+4. `session-start` hook auto-injects the `MEMORY.md` index plus top-N relevant approved memories into every new session — no manual recall needed once merged
 
 **Example:**
 ```bash
-$ aiflow memory save "payment-flow" "Process: 1. Validate amount, 2. Call Stripe API, 3. Update DB"
-✓ Saved: payment-flow
+$ ak mem d -c 01.Lessons/dev -s prevent-429-error --content "Retry with backoff on 429 from payment gateway" -t payment,retry
+✓ Draft đã tạo: _pending/01.Lessons/dev/prevent-429-error.md
+  id: mem-payment-prevent-429-error (local — chỉ máy này recall được cho tới khi submit)
+
+$ ak mem ls
+Pending drafts (local):
+  mem-payment-prevent-429-error  _pending/01.Lessons/dev/prevent-429-error.md
+    type=lesson scope=payment workflows=all
 
-$ aiflow memory search "payment"
-Found 3 memories matching "payment":
-  1. payment-flow
-  2. payment-error-handling
-  3. payment-tests
+$ ak mem sb 01.Lessons/dev/prevent-429-error.md -t "Add memory: prevent-429-error"
+✓ Branch memory/prevent-429-error created in AK-Docs
+✓ Merge Request opened — waiting for approval
 ```
 
 ## guide (alias: `g`)
@@ -639,6 +654,45 @@ ak g -c                                      # command reference only  (--comman
 
 ---
 
+## ask
+
+Search ai-flow-kit's own docs for an answer about the kit itself — install, roles, folder structure, CLI commands, memory draft/submit, troubleshooting. This is the deterministic fallback the `aiflow-help` skill uses (and that works with no LLM at all): local keyword search over `docs/common/*.md`, no network call.
+
+```bash
+ak ask "how do I install ai-flow-kit"
+ak ask "submit memory"
+ak ask "switch between cursor and claude code"
+ak ask "some obscure question" -n 5          # show up to 5 results  (--limit)
+```
+
+**Arguments:**
+- `<question>` — Free-text question (English or Vietnamese)
+
+**Options:**
+- `-n, --limit <n>` — Max number of results to show (default 3)
+
+**What it does:**
+1. Scans every `docs/common/*.md` file (including `workflows/`)
+2. Scores each file by how many query terms it contains, weighting heading matches higher
+3. Prints the top matches with the nearest heading and a snippet, ranked by score
+
+See also `docs/common/INDEX.md` for the curated topic map this search complements, and the `/ak-ask "<question>"` slash command for asking the same kind of question directly inside a Claude Code chat (explicit trigger for the `aiflow-help` skill, no terminal needed).
+
+**Example:**
+```bash
+$ ak ask "submit memory"
+
+Results for "submit memory":
+
+  docs/common/cli-reference.md  (score 14)
+  → memory (alias: `mem`)
+    ...`submit|sb <path> --title <title> [-d <desc>] [-y]` — Move a pending draft...
+
+See docs/common/INDEX.md for the full topic map.
+```
+
+---
+
 ## gate (AI workflow logging)
 
 Called automatically by AI during gate workflow — not intended for manual use.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Example Team",
   "publishConfig": {

package/scripts/ask.js

@@ -0,0 +1,141 @@
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+
+// Local, deterministic fallback for "how do I use ai-flow-kit" questions —
+// works without any LLM, and gives the aiflow-help skill a ground-truth
+// search path instead of guessing. Scores docs/common/*.md by simple
+// keyword overlap; no stemming/diacritics-folding (see upgrade-plan #45).
+
+const PKG_DIR = path.join(__dirname, '..');
+const DOCS_DIR = path.join(PKG_DIR, 'docs', 'common');
+const SNIPPET_RADIUS = 160;
+
+module.exports = function ask(query, options = {}) {
+    if (!query || !query.trim()) {
+        console.log(chalk.yellow('Usage: ak ask "<question>"'));
+        console.log(chalk.gray('  ak ask "how do I install ai-flow-kit"'));
+        console.log(chalk.gray('  ak ask "submit memory"'));
+        return;
+    }
+
+    const limit = options.limit ? parseInt(options.limit, 10) : 3;
+    const files = walk(DOCS_DIR);
+    const terms = tokenize(query);
+
+    const scored = files
+        .map((file) => scoreFile(file, terms))
+        .filter((r) => r.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+
+    if (scored.length === 0) {
+        console.log(chalk.yellow(`No local match for "${query}" in docs/common/.`));
+        console.log(chalk.gray('  Try `ak guide` for the quickstart, or check docs/common/INDEX.md for the full topic map.'));
+        return scored;
+    }
+
+    console.log(chalk.cyan(`\nResults for "${query}":\n`));
+    for (const r of scored) {
+        console.log(chalk.bold.white(`  ${r.relPath}`) + chalk.gray(`  (score ${r.score})`));
+        if (r.heading) console.log(chalk.gray(`  → ${r.heading}`));
+        console.log(`    ${r.snippet}\n`);
+    }
+    console.log(chalk.gray(`See docs/common/INDEX.md for the full topic map.`));
+    return scored;
+};
+
+function walk(dir) {
+    let results = [];
+    if (!fs.existsSync(dir)) return results;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results = results.concat(walk(full));
+        } else if (entry.isFile() && entry.name.endsWith('.md')) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+
+// Generic connector words — kept out of scoring so a short common word (esp. "ai",
+// which appears in almost every doc via "ai-flow-kit") doesn't drown out real topic terms.
+const STOPWORDS = new Set([
+    'a', 'an', 'the', 'this', 'that', 'these', 'those', 'is', 'are', 'was', 'were', 'be', 'been',
+    'do', 'does', 'did', 'to', 'of', 'in', 'on', 'at', 'for', 'and', 'or', 'with', 'how', 'what',
+    'why', 'when', 'where', 'who', 'which', 'it', 'its', 'my', 'me', 'i', 'you', 'your', 'can',
+    'ai',
+    'la', 'va', 'cua', 'the', 'nay', 'de', 'thi', 'toi', 'la gi', 'nhu', 'the nao',
+]);
+
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9à-ỹ]+/i)
+        .filter((t) => t.length > 1 && !STOPWORDS.has(t));
+}
+
+// Two failure modes to guard against: (1) a raw hit count biases toward the longest
+// file regardless of relevance (CHANGELOG.md is 5x getting-started.md) — fixed by
+// normalizing body hits by document length; (2) substring matching false-positives on
+// short queries (query term "flow" matching inside "Workflow") — fixed by comparing
+// whole tokens instead of doing lower.includes(term).
+function scoreFile(file, terms) {
+    const content = fs.readFileSync(file, 'utf-8');
+    const relPath = path.relative(PKG_DIR, file).replace(/\\/g, '/');
+
+    const docTokens = tokenizeRaw(content);
+    const wordCount = Math.max(1, docTokens.length);
+    const freq = {};
+    for (const t of docTokens) freq[t] = (freq[t] || 0) + 1;
+
+    let bodyHits = 0;
+    for (const term of terms) bodyHits += freq[term] || 0;
+
+    let headingHits = 0;
+    const headingLines = content.split('\n').filter((l) => l.trim().startsWith('#'));
+    for (const line of headingLines) {
+        const lineTokens = new Set(tokenizeRaw(line));
+        for (const term of terms) {
+            if (lineTokens.has(term)) headingHits += 1;
+        }
+    }
+
+    const score = Math.round((bodyHits / wordCount) * 1000 + headingHits * 5);
+
+    // Snippet position is cosmetic only (not used for scoring), so a plain substring
+    // search is fine here even though it may land inside a larger word.
+    const lower = content.toLowerCase();
+    let firstMatchIndex = -1;
+    for (const term of terms) {
+        const idx = lower.indexOf(term);
+        if (idx !== -1 && (firstMatchIndex === -1 || idx < firstMatchIndex)) firstMatchIndex = idx;
+    }
+
+    const heading = nearestHeading(content, firstMatchIndex);
+    const snippet = firstMatchIndex === -1
+        ? content.trim().slice(0, SNIPPET_RADIUS).replace(/\n+/g, ' ')
+        : buildSnippet(content, firstMatchIndex);
+
+    return { file, relPath, score, heading, snippet };
+}
+
+// Same splitting rule as tokenize(), but without stopword filtering — used to index
+// document content, where we want an accurate word count and per-word frequency map.
+function tokenizeRaw(text) {
+    return text.toLowerCase().split(/[^a-z0-9à-ỹ]+/i).filter((t) => t.length > 1);
+}
+
+function nearestHeading(content, index) {
+    if (index === -1) return null;
+    const before = content.slice(0, index).split('\n').filter((l) => l.trim().startsWith('#'));
+    return before.length ? before[before.length - 1].replace(/^#+\s*/, '').trim() : null;
+}
+
+function buildSnippet(content, index) {
+    const start = Math.max(0, index - SNIPPET_RADIUS / 2);
+    const end = Math.min(content.length, index + SNIPPET_RADIUS / 2);
+    const raw = content.slice(start, end).replace(/\n+/g, ' ').trim();
+    return (start > 0 ? '…' : '') + raw + (end < content.length ? '…' : '');
+}

package/scripts/create-score-excel.js

@@ -25,7 +25,7 @@ function norm(cmd) {
 }
 
 // ── Version helpers ─────────────────────────────────────────────────────────
-const CURRENT_VERSION = '0.1.5';
+const CURRENT_VERSION = '0.1.6';
 
 function parseVersion(v) {
   if (!v || v === '-' || v === '' || v.toLowerCase() === 'unknown') return null;
@@ -407,13 +407,10 @@ async function writeExcelFile(rows, outputPath, sheetLabel, fromLabel, toLabel)
 
 // ── Canonical user list (fixed order) ─────────────────────────────────────
 const CANONICAL_USERS = [
-  'hoangdv@relipasoft.com',
   'chinhtt@relipasoft.com',
   'phongnx@relipasoft.com',
   'dungha@relipasoft.com',
-  'thangnv@relipasoft.com',
   'nguyenlt@relipasoft.com',
-  'thuongvv@relipasoft.com',
   'yenvtb@relipasoft.com',
   'thainq@relipasoft.com',
   'tuoittx@relipasoft.com',
@@ -431,6 +428,7 @@ const CANONICAL_USERS = [
   'khanhnv@relipasoft.com',
   'namhh@relipasoft.com',
   'tannt@relipasoft.com',
+  'khangnv@relipasoft.com',
 ];
 
 // Log email → canonical email (for slight mismatches)

package/scripts/docs-branch.js

@@ -5,7 +5,7 @@ const { execSync } = require('child_process');
 const { confirm } = require('@inquirer/prompts');
 const { resolveDocsRepoPath, DOC_REPOS } = require('./docs-repo');
 
-// Implements the branch + Merge Request half of docs/internal/Docs-Management-Flow.md:
+// Implements the branch + Merge Request half of docs/common/Docs-Management-Flow.md:
 // PM reviews & merges into `main`; every other role updates docs on a
 // `feature/<functionId>/<taskId>` branch created from `main`, then submits a MR.
 //

package/scripts/docs-repo.js

@@ -7,7 +7,7 @@ const { execSync } = require('child_process');
 // fixed-name folders living directly under the workspace root — the folder
 // opened in the editor, which contains one or more source repos plus these
 // two docs repos as siblings. `ak` is run from that root, so projectDir
-// (process.cwd()) already IS the root — see docs/internal/Project-Structure.md.
+// (process.cwd()) already IS the root — see docs/common/Project-Structure.md.
 const DOC_REPOS = [
     { name: 'AK-Docs', purpose: 'tài liệu dự án (Requirements, Specs, Test Cases, Coding docs...)' },
     { name: 'Shared-Docs', purpose: 'template dùng chung cho tất cả dự án (Spec, QA, Test Case, Test Report...)' },

package/scripts/hooks/session-start.js

@@ -100,7 +100,7 @@ process.stdin.on('end', async () => {
     } catch (_) { }
 
     // ── 3.5 Load relevant memory (99.Memory/ Project Brain) ────────
-    // See docs/internal/Memory-Architecture-v1.0.md — Luồng 3 (Nạp/Sử dụng).
+    // See docs/common/Memory-Architecture-v1.0.md — Luồng 3 (Nạp/Sử dụng).
     let memoryBlock = '';
     try {
         const workspaceRoot = resolveWorkspaceRoot(projectRoot);

package/scripts/init.js

@@ -350,6 +350,11 @@ async function setupClaudeCommands(projectDir) {
             dest: 'coding.md',
             description: 'Manual trigger for the DEV 5-Gate Coding Workflow (bug-fix / feature / refactor / investigation / documentation). Use this when the SessionStart auto-start message was missed — e.g. a ticket was loaded with `ak use` while this chat session was already open.',
         },
+        {
+            src: path.join(PKG_DIR, 'custom', 'templates', 'shared', 'ak-ask-workflow.md'),
+            dest: 'ak-ask.md',
+            description: 'Ask a question about ai-flow-kit itself (install, roles, folder structure, CLI, memory workflow) — explicit trigger for the aiflow-help self-help skill, for when the question might otherwise be mistaken for ticket work. Usage: /ak-ask "how do I submit a memory".',
+        },
     ];
 
     for (const cmd of commands) {
@@ -1092,7 +1097,7 @@ async function init(options) {
 
         // ── Bootstrap 99.Memory/ skeleton (Luồng 1 — Khởi tạo) ────────
         // Free: no reads, no token cost — just an empty folder skeleton if AK-Docs
-        // exists and doesn't have one yet (docs/internal/Memory-Architecture-v1.0.md §4).
+        // exists and doesn't have one yet (docs/common/Memory-Architecture-v1.0.md §4).
         const memorySkeleton = await memoryStore.ensureSkeleton(projectDir);
         if (memorySkeleton.created) {
             console.log(chalk.green('✓ Đã tạo khung 99.Memory/ trong AK-Docs (chưa có ghi nhớ nào).'));
@@ -1210,6 +1215,7 @@ module.exports.detectRtk = detectRtk;
 module.exports.isRtkHookConfigured = isRtkHookConfigured;
 module.exports.isGitNexusConfigured = isGitNexusConfigured;
 module.exports.setupClaudeCommands = setupClaudeCommands;
+module.exports.copyDocsToProject = copyDocsToProject;
 module.exports.setupFramework = setupFramework;
 module.exports.ensureAiflowGitignored = ensureAiflowGitignored;
 module.exports.resolveWorkflowFile = resolveWorkflowFile;

package/scripts/memory-store.js

@@ -9,7 +9,7 @@ function resolveDocsRepoPath(projectDir, repoName) {
     return path.join(projectDir, repoName);
 }
 
-// Engine for the "99.Memory/" Project Brain — see docs/internal/Memory-Architecture-v1.0.md.
+// Engine for the "99.Memory/" Project Brain — see docs/common/Memory-Architecture-v1.0.md.
 // Pure functions only (no chalk/console output, no CLI parsing) — scripts/memory.js and
 // scripts/hooks/session-start.js are the callers.
 //