# AI Flow Kit — Self-Help Index

> **Purpose:** This file is the entry point for answering questions *about ai-flow-kit itself* — "how do I install this", "how does a PM use this", "how do I submit a memory", etc. — as opposed to questions about the ticket/feature the developer is currently working on.
>
> **For the AI:** Match the user's question against the "Ask about" column below, then read the linked file(s) before answering. Don't guess — if nothing below covers the question, say so plainly (see "Unanswered topics" at the bottom) instead of inventing behavior. Prefer citing the file path you read from so the user can verify.
>
> **For humans:** every file here also exists as a plain Markdown file — read it directly if you don't have an AI assistant handy.

## Topic map

| Ask about | Read | Notes |
|---|---|---|
| Install / setup, global vs local, first run | [getting-started.md](./getting-started.md), [QUICK_START.md](./QUICK_START.md) | |
| What is the Gate Workflow, how do Gates 1–5 fit together | [AIFLOW.md](./AIFLOW.md) (§ Workflow Overview) | |
| Roles — PM / DEV / AI responsibilities | [AIFLOW.md](./AIFLOW.md) (§ Roles) | Table is intentionally brief — see "Unanswered topics" for a fuller PM-specific guide |
| All CLI commands (`ak ...`), options, examples | [cli-reference.md](./cli-reference.md) | |
| Switching between Claude Code / Codex / Cursor / Gemini CLI mid-task | [ai-integration.md](./ai-integration.md) | |
| Using Codex — VS Code extension, ChatGPT desktop app, or CLI | [ai-integration.md](./ai-integration.md) (§ 4 Codex) | `ak init --env codex` → `AGENTS.md` + `.codex/`; no session-start hook, so start a new session after `ak use` |
| Config levels (global / project / local state) | [configuration.md](./configuration.md) | |
| Something isn't working (`command not found`, permission denied, etc.) | [troubleshooting.md](./troubleshooting.md) | |
| Bug-fix / feature / refactor / investigation / impact-analysis / Figma workflows | [workflows/](./workflows/) | one file per task type |
| What changed in the latest version | [CHANGELOG.md](./CHANGELOG.md) | check here before assuming a command still behaves like an older doc describes |
| Manually create + submit a memory (`ak memory ...`) | [cli-reference.md](./cli-reference.md) (§ memory) | `99.Memory/` Project Brain — draft locally, `submit` opens a Merge Request, a teammate approves |
| How AI recalls memories automatically in a new session | [CHANGELOG.md](./CHANGELOG.md) ([0.1.7] entry) | Layer 1 (`MEMORY.md` index) + Layer 2 (top-N scored, relevant to active ticket) injected by the session-start hook |
| `AK-Docs/` folder structure — overview (all roles) | [Project-Structure.md](./Project-Structure.md) | top-level map: `AK-Docs/` sections + `Shared-Docs/` |
| `AK-Docs/02.BA-Specs/` folder structure (BA) | [BA-Specs-Structure.md](./BA-Specs-Structure.md) | Requirements → Analysis → QnA → UC Specs, by Function-ID |
| `AK-Docs/04.Coding/` folder structure (Dev) | [Coding-Structure.md](./Coding-Structure.md) | Requirements → Plans → TDD-Notes → Reviews → Pull-Requests, by Function-ID/Ticket-ID |
| `AK-Docs/03.Testing/` folder structure (Tester) | [Testing-Structure.md](./Testing-Structure.md) | Strategies → Testcases → evidence, by Function-ID |
| `99.Memory/` Project Brain — full design, scoring model, mem-id scheme, role/PM permissions | [Memory-Architecture-v1.0.md](./Memory-Architecture-v1.0.md) | v1.1 — Phase 1 (`draft/list/submit/remove`) is what's implemented today; later phases in this doc are roadmap, not shipped yet |
| How updates to `AK-Docs`/`Shared-Docs` get reviewed — branch/Merge Request flow, who can merge to `main` | [Docs-Management-Flow.md](./Docs-Management-Flow.md) | Doc's own header says `Trạng thái: Draft — chờ PM review` — flag that when answering, don't present it as final policy |
| PM/BrSE/Comtor — ingest a Backlog/Jira/SharePoint link or pasted text into `AK-Docs/01.QnA/` | [Project-Structure.md](./Project-Structure.md) (§ `01.QnA/`), `.claude/skills/ingest-data/SKILL.md` | `ak use` → taskType `ingest-data`, 2-gate flow (fetch/classify/draft → branch+MR). SharePoint link fetch is **not connected yet** — falls back to pasted text |
| Any role — how to read `System-Requirement_v{N}.md` (who reads which field, Classification/Implementation Reference/Tech Reference meaning), why it's separate from UC Spec, and how to review/approve it without reading code | [System-Requirement-Read-Guide.md](./System-Requirement-Read-Guide.md) | Field glossary + Classification state machine (Gap/Assumption/Decision/Deviation) + FAQ (why not merge with UC Spec, who writes it, when to update) + 6-step review checklist |

## Unanswered topics (do not invent — say so and stop here)

These are real questions ai-flow-kit users ask that **don't have a public doc yet**. If asked about one of these, say the topic isn't documented yet and point to the closest thing above instead of guessing:

- A dedicated "PM day-1 guide" (today PM guidance is folded into `AIFLOW.md` § Roles + `getting-started.md`, not a standalone walkthrough)

> Maintaining this file: when you write a new `docs/common/*.md` (or curate one down from `docs/internal/`), add a row above and remove it from "Unanswered topics".