@manhquy/flow-skill 0.1.0-rc.1

package/skills/flow/playbooks/README.md

@@ -0,0 +1,28 @@
+# Playbooks — paid-for stack knowledge
+
+One playbook = one stack/integration, written AFTER it worked in a real project
+(manual-first: the playbook wraps a successful run, never speculation). They exist so
+the next card touching that stack starts from the gotchas instead of rediscovering them.
+
+## Rules
+
+1. **Read before build.** Any card whose scope touches a stack with a playbook here —
+   the builder reads the playbook FIRST. In auto runs, the planner includes the relevant
+   playbook in the subagent's brief (alongside the card + contract + CLAUDE.md).
+2. **Harvest after build.** When a card pays for a non-obvious lesson (a gotcha, a quirk,
+   a smoke test that saved the architecture), capture it: update the existing playbook or
+   add a new one. The card's review isn't done until the lesson is filed.
+3. **Shape:** name `<stack>-<thing>.md`; start with "When to use this"; put the critical
+   gotcha at the TOP (the thing that breaks people first); include runnable smoke tests;
+   end with provenance (which project, when).
+4. **Smoke test before architecture.** If a playbook ships smoke tests, run them BEFORE
+   committing to a design that depends on that stack behaving (see the Qwen tool-calling
+   gotcha — caught live, before the agent framework was built on sand).
+
+## Index
+
+| Playbook | When to use |
+|---|---|
+| [cloudflare-ai-gateway-qwen.md](cloudflare-ai-gateway-qwen.md) | LLM feature in a Python/FastAPI backend via CF AI Gateway → Workers AI Qwen. CRITICAL: Qwen returns no real tool_calls — single structured-JSON calls, not agent frameworks. |
+| [docker-deploy-stale-cache.md](docker-deploy-stale-cache.md) | Deployed route 404s though merged+deployed: layer cache served a stale image. Check live `/openapi.json` BEFORE debugging code; fix Dockerfile layer order. |
+| [windows-gitbash-jsonl-telemetry.md](windows-gitbash-jsonl-telemetry.md) | Shell-writes / Python-reads a JSONL log on Git Bash for Windows. CRITICAL: bash `$HOME` != Python `expanduser` (USERPROFILE); `$TEMP` is `C:\` but `$ROOT` is `/c/`; no atomic append for files; flock absent. |

package/skills/flow/playbooks/cloudflare-ai-gateway-qwen.md

@@ -0,0 +1,346 @@
+# Playbook: LLM agent in a Python/FastAPI backend via Cloudflare AI Gateway → Qwen (Workers AI)
+
+Replicate in ~15 min. Copy-paste the skeleton, run the smoke tests, ship.
+
+## When to use this
+You want an LLM feature (classification, structured extraction, draft generation, summarization) in a backend, routed through **Cloudflare AI Gateway** for cost observability + a single seam, hitting **Workers AI** models (e.g. Qwen). No Anthropic/OpenAI key — just a **Cloudflare API token**.
+
+---
+
+## DECISION RULE — single call vs. deepagents agent (read first)
+**Use a single structured-JSON call** (cheap model like `@cf/qwen/qwen2.5-coder-32b-instruct`) for **classify / extract / draft / summarize** — any one-shot transform. This is the common case; most "AI features" in a CRUD app are single calls.
+
+**Use deepagents** (`@cf/qwen/qwen3-30b-a3b-fp8` + the content shim, see "deepagents" sections below) ONLY when the task needs **multi-step planning + tool use + sub-agents** — investigate-then-act, multi-source recap, retrieval-augmented chat.
+
+**Don't pay the agent tax for a one-shot transform.** The ab-tickets triage feature is a single call, and that was the right call.
+
+---
+
+## ⚠️ THE CRITICAL GOTCHA — read first
+**Qwen on Workers AI does NOT return OpenAI-style `tool_calls`.**
+
+When you pass `tools` + `tool_choice`, the response has `tool_calls: null` and the model emits the "function call" as TEXT in `content`:
+
+```
+<function-name>triage</function-name>
+<args-json-object>{"category":"repair","sentiment":"angry"}</args-json-object>
+```
+
+This **breaks any agentic framework that depends on real tool-calling** (deepagents / LangGraph tool loops, OpenAI-tool-calling clients). We caught this with a live smoke test *before* committing to the architecture.
+
+**LESSON:** If your task is really "get structured output from ONE call" (classify / extract / draft / summarize), do NOT use a multi-step tool-calling agent framework with Qwen. Use a **single structured-JSON prompt** instead. Same user value, no non-determinism, no broken-tool-calling dependency. (This is the "re-architect C→B" move.)
+
+**Always run the tool-calling smoke test (below) BEFORE building on any model you haven't used through this gateway.**
+
+---
+
+## The endpoint
+CF AI Gateway exposes an **OpenAI-compatible** endpoint.
+
+Base URL shape:
+```
+https://gateway.ai.cloudflare.com/v1/<ACCOUNT_ID>/<GATEWAY_NAME>/workers-ai/v1
+```
+then POST to `/chat/completions`.
+
+- **Auth:** header `Authorization: Bearer <CLOUDFLARE_API_TOKEN>` — a CF API token with **Workers AI** permission.
+- **Gateways:** an account can have multiple AI Gateways. Use a gateway with `authentication: false` for the simplest setup (no extra gateway key). List them:
+  `GET /accounts/<ACCOUNT_ID>/ai-gateway/gateways`
+- **Model ids on Workers AI:** see the model-selection table below. Defaults:
+  - single structured-JSON call → `@cf/qwen/qwen2.5-coder-32b-instruct`
+  - agentic / deepagents → `@cf/qwen/qwen3-30b-a3b-fp8`
+
+---
+
+## The working approach: single structured-JSON call
+- System prompt: instruct the model to **"return ONLY valid JSON, no explanation, no markdown."** Put the exact JSON shape in the user prompt.
+- **Quirk:** Workers AI may return `content` as an **already-parsed JSON object (dict)**, NOT a JSON string. Your parser MUST handle both — see `_coerce_content`.
+- `response_format: {"type":"json_object"}` was **unreliable/errored** in our test. Rely on prompt instructions + the coerce helper instead.
+- **Always normalize/validate** model output against your enums server-side; fall back to safe defaults (`"other"` / `"neutral"`) for off-enum values. Never trust raw output to match your schema.
+- Qwen handles **Vietnamese** well (we generate Vietnamese draft replies).
+
+---
+
+## Which Workers AI model for tool-calling / agentic frameworks (deepagents)
+Tested live through the CF AI Gateway OpenAI-compatible endpoint for REAL tool-calling support (does the model populate `tool_calls`, and does it survive a full deepagents loop):
+
+| Model | Price (in/out per M tokens) | Raw `tool_calls` | Full deepagents loop | Verdict |
+|---|---|---|---|---|
+| `@cf/qwen/qwen2.5-coder-32b-instruct` | ~0.30 / (n/a) | ❌ emits call as TEXT `<tools>{...}</tools>`, `tool_calls=null` | ❌ breaks | DO NOT use for agents (fine for single structured-JSON calls) |
+| `@cf/ibm-granite/granite-4.0-h-micro` | $0.017 / $0.112 | ✅ | ❌ returns malformed tool args (string not dict) → ValidationError | cheapest but too flaky for agent loops |
+| `@cf/qwen/qwen3-30b-a3b-fp8` | $0.051 / $0.335 | ✅ | ✅ **WORKS** — valid args, completes graph | ✅ **RECOMMENDED** cheapest that actually works |
+| `@cf/zai-org/glm-4.7-flash` | $0.061 / $0.40 | ✅ | ✅ works | ✅ runner-up |
+| `@cf/openai/gpt-oss-20b` | $0.20 / $0.30 | ✅ | ❌ 400 (sends extra array content) | avoid via gateway |
+| `@cf/meta/llama-3.3-70b-instruct-fp8-fast` | $0.293 / $2.253 | ✅ (advertised) | untested | pricey |
+
+**KEY LESSON:** "supports function calling" in the model catalog does NOT mean it works through the gateway. Always smoke-test the FULL loop. The cheapest model that genuinely works with deepagents end-to-end is **`@cf/qwen/qwen3-30b-a3b-fp8`**. Use a cheap non-agentic model (`qwen2.5-coder`) for high-volume single-call triage, and `qwen3-30b` only for the agentic steps.
+
+---
+
+## deepagents + Workers AI: the content-blocks 400 gotcha + the fix
+deepagents (via langchain `ChatOpenAI`) sends the SYSTEM message `content` as an ARRAY of content blocks: `[{"type":"text","text":"..."}]`. Workers AI's OpenAI-compat endpoint ONLY accepts `content` as a plain string, so it 400s:
+
+```
+AiError: Bad input: ... Type mismatch of '/messages/0/content', 'string' not in 'array'
+```
+
+**FIX** — a shim that flattens array content to a string before the request hits Workers AI. Monkeypatch the OpenAI client's `create` (import once, before constructing the agent):
+
+```python
+import openai
+_orig = openai.resources.chat.completions.Completions.create
+def _flatten(content):
+    if isinstance(content, list):
+        return "".join(b.get("text","") for b in content if isinstance(b, dict) and b.get("type")=="text")
+    return content
+def _patched(self, *a, **k):
+    for msg in k.get("messages", []):
+        if "content" in msg:
+            msg["content"] = _flatten(msg["content"])
+    return _orig(self, *a, **k)
+openai.resources.chat.completions.Completions.create = _patched
+```
+
+With this shim + `qwen3-30b-a3b-fp8`, deepagents runs end-to-end on Cloudflare (tool executed, valid args, coherent Vietnamese answer).
+
+> Note: a plain langchain `.invoke("string")` already sends string content fine — only deepagents' structured system prompt triggers the array. You only need the shim when running deepagents (or anything that builds multi-block content).
+
+### deepagents setup that works
+```python
+from langchain_openai import ChatOpenAI
+from deepagents import create_deep_agent
+model = ChatOpenAI(model="@cf/qwen/qwen3-30b-a3b-fp8",
+    base_url=f"https://gateway.ai.cloudflare.com/v1/{ACCT}/{GATEWAY}/workers-ai/v1",
+    api_key=CF_API_TOKEN, temperature=0)
+agent = create_deep_agent(model=model, tools=[...], system_prompt="...")
+result = agent.invoke({"messages":[{"role":"user","content":"..."}]})
+```
+Versions tested: **deepagents 0.6.8, langchain-openai 1.3.0.**
+
+### Tool-loop smoke test (before trusting a model for agents)
+Run a real `agent.invoke(...)` with one trivial tool and assert: (a) the model populates `tool_calls`, (b) the args parse as a dict, (c) the graph completes. If any fail, the model is not agent-ready through the gateway regardless of the catalog claim.
+
+---
+
+## Architecture patterns that worked
+- **Async after the write.** Run the LLM call in a FastAPI `BackgroundTasks` task AFTER the main DB write, so the user-facing request (e.g. ticket creation) NEVER blocks on the LLM. Create the record first with a stubbed `pending` AI block; the background task flips it to `done` or `failed`.
+- **Store result as JSONB** (`ai` column) on the row:
+  `{category, sentiment, draft_reply, faq_used, status: pending|done|failed, generated_at}`
+- **Failure handling.** Wrap the whole triage in `try/except`; on ANY exception set `status="failed"` and **never raise to the caller**. The agent must never crash the main flow. Bad token → 401 → `status=failed`, record still intact.
+- **Grounding without a vector DB (RAG-lite).** v1: pass a small FIXED set of hand-curated FAQ snippets in the prompt; have the model return which ids it used (`faq_used`). v2 (when the board can upload docs): store `@cf/baai/bge-m3` embeddings as a **JSONB float array** next to each snippet in Postgres and compute **cosine in-app** — no vector DB needed for a few hundred snippets. See the RAG-lite section below.
+- **Safety: draft only.** The agent DRAFTS; a human approves before anything is sent to an end user. Never auto-send LLM output.
+
+---
+
+## RAG-lite: bge-m3 embeddings in Postgres + in-app cosine (no vector DB)
+For a small corpus (building docs, FAQ, a few hundred snippets) you do NOT need a vector DB. Store embeddings as JSONB next to the text and compute cosine in Python. Fall back to the hardcoded FAQ when no docs are uploaded.
+
+**Embeddings endpoint (same gateway, `/embeddings`):**
+```python
+import httpx
+EMBED_MODEL = "@cf/baai/bge-m3"   # multilingual — handles Vietnamese
+async def embed(texts: list[str]) -> list[list[float]]:
+    url = settings.cf_ai_gateway_url.rstrip("/") + "/embeddings"
+    async with httpx.AsyncClient(timeout=settings.agent_timeout_seconds) as client:
+        resp = await client.post(url,
+            headers={"Authorization": f"Bearer {settings.cf_ai_token}"},
+            json={"model": EMBED_MODEL, "input": texts})
+        resp.raise_for_status()
+        data = resp.json()
+    return [row["embedding"] for row in data["data"]]
+```
+
+**Storage:** SQLAlchemy `embedding: Mapped[list] = mapped_column(JSONB, default=list)`.
+
+**In-app cosine top-K:**
+```python
+import math
+def _cosine(a, b):
+    if not a or not b: return 0.0
+    dot = sum(x*y for x, y in zip(a, b))
+    na = math.sqrt(sum(x*x for x in a)); nb = math.sqrt(sum(y*y for y in b))
+    return dot/(na*nb) if na and nb else 0.0
+
+TOP_K, MIN_SIM = 3, 0.30   # below MIN_SIM a snippet is too unrelated to inject
+async def build_grounding(session, query_text):
+    docs = (await session.execute(select(DocSnippet))).scalars().all()
+    if not docs:
+        return faq_block(), [], FAQ_IDS                      # fall back to hardcoded FAQ
+    qv = await embed_one(query_text)
+    scored = sorted(((_cosine(qv, d.embedding or []), d) for d in docs),
+                    key=lambda t: t[0], reverse=True)
+    top = [(s, d) for s, d in scored[:TOP_K] if s >= MIN_SIM]
+    if not top:
+        return faq_block(), [], FAQ_IDS | {d.id for d in docs}  # nothing relevant: FAQ not noise
+    block = "\n".join(f"- [{d.id}] {d.title}: {d.content}" for _, d in top)
+    return block, [d.id for _, d in top], {d.id for d in docs} | FAQ_IDS
+```
+
+Feed `block` into the user prompt as grounding; validate the model's `faq_used` against the returned valid-id set. When the corpus grows past a few thousand rows, swap the in-app cosine for `pgvector` — same shape, just move the math to SQL.
+
+---
+
+## Code skeleton (httpx async)
+
+```python
+# config.py
+class Settings:
+    cf_ai_gateway_url: str  # CF_AI_GATEWAY_URL = https://gateway.ai.cloudflare.com/v1/<acct>/<gw>/workers-ai/v1
+    cf_ai_token: str        # CF_AI_TOKEN = Cloudflare API token (Workers AI perm)
+    agent_model: str        # AGENT_MODEL = @cf/qwen/qwen2.5-coder-32b-instruct
+    agent_timeout_seconds: float = 30.0
+
+# agent.py
+import json
+import httpx
+from datetime import datetime, timezone
+
+CATEGORIES = {"repair", "billing", "complaint", "request", "other"}
+SENTIMENTS = {"angry", "neutral", "happy"}
+
+async def _call_qwen(system: str, user: str, max_tokens: int = 800) -> object:
+    url = f"{settings.cf_ai_gateway_url}/chat/completions"
+    payload = {
+        "model": settings.agent_model,
+        "messages": [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ],
+        "max_tokens": max_tokens,
+    }
+    headers = {"Authorization": f"Bearer {settings.cf_ai_token}"}
+    async with httpx.AsyncClient(timeout=settings.agent_timeout_seconds) as client:
+        r = await client.post(url, json=payload, headers=headers)
+        r.raise_for_status()
+        content = r.json()["choices"][0]["message"]["content"]
+        return _coerce_content(content)
+
+def _coerce_content(content) -> dict:
+    # Workers AI may return content as a dict OR a string.
+    if isinstance(content, dict):
+        return content
+    s = content.strip()
+    if s.startswith("```"):
+        s = s.strip("`")
+        if s.lower().startswith("json"):
+            s = s[4:]
+    return json.loads(s.strip())
+
+def _normalize(raw: dict) -> dict:
+    cat = raw.get("category")
+    sent = raw.get("sentiment")
+    return {
+        "category": cat if cat in CATEGORIES else "other",
+        "sentiment": sent if sent in SENTIMENTS else "neutral",
+        "draft_reply": str(raw.get("draft_reply", "")),
+        "faq_used": [x for x in raw.get("faq_used", []) if isinstance(x, str)],
+    }
+
+FAQ = [
+    {"id": "faq-water", "topic": "Nước", "text": "Sự cố nước báo BQL tầng 1..."},
+    # ... small hand-curated set
+]
+
+SYSTEM = (
+    "Bạn là trợ lý phân loại ticket chung cư. "
+    "Chỉ trả về JSON hợp lệ, không giải thích, không markdown."
+)
+
+def _user_prompt(ticket_text: str) -> str:
+    faq = "\n".join(f'{f["id"]}: {f["topic"]} - {f["text"]}' for f in FAQ)
+    return (
+        f"FAQ:\n{faq}\n\n"
+        f"Ticket: {ticket_text}\n\n"
+        'Trả về JSON theo shape: '
+        '{"category":"repair|billing|complaint|request|other",'
+        '"sentiment":"angry|neutral|happy",'
+        '"draft_reply":"<tiếng Việt>",'
+        '"faq_used":["<faq id>"]}'
+    )
+
+async def triage_ticket(ticket_id: int):
+    row = await load_ticket(ticket_id)          # your DB load
+    try:
+        raw = await _call_qwen(SYSTEM, _user_prompt(row.body))
+        result = _normalize(raw)
+        row.ai = {**result, "status": "done",
+                  "generated_at": datetime.now(timezone.utc).isoformat()}
+    except Exception:
+        row.ai = {"category": None, "sentiment": None, "draft_reply": None,
+                  "faq_used": [], "status": "failed",
+                  "generated_at": datetime.now(timezone.utc).isoformat()}
+    await commit(row)                           # never re-raise
+
+# routes.py
+@router.post("/tickets")
+async def create_ticket(payload: TicketIn, background_tasks: BackgroundTasks):
+    ticket = await db_create(payload, ai={"status": "pending"})  # stub first
+    background_tasks.add_task(triage_ticket, ticket.id)          # async after write
+    return ticket
+```
+
+---
+
+## Deployment notes
+- **Env vars:** `CF_AI_GATEWAY_URL`, `CF_AI_TOKEN` (the Cloudflare API token), `AGENT_MODEL`.
+- **Confirm routing via gateway logs:**
+  ```
+  GET /accounts/<ACCOUNT_ID>/ai-gateway/gateways/<GW>/logs?per_page=5&order_by=created_at&order_by_direction=desc
+  ```
+  Shows `model`, `success`, `status_code`, `tokens_out` per request. Both 200 successes AND 401 failures appear here — good for confirming the request actually went through the gateway.
+
+---
+
+## Smoke tests (run these first)
+
+```bash
+BASE="https://gateway.ai.cloudflare.com/v1/<ACCOUNT_ID>/<GATEWAY_NAME>/workers-ai/v1"
+TOKEN="<CLOUDFLARE_API_TOKEN>"
+```
+
+**1. Plain chat — confirms model + gateway + auth:**
+```bash
+curl -s "$BASE/chat/completions" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"@cf/qwen/qwen2.5-coder-32b-instruct",
+       "messages":[{"role":"user","content":"Say hello in Vietnamese."}],
+       "max_tokens":50}'
+```
+
+**2. Tool-calling — confirms THE GOTCHA. Expect `tool_calls: null` + the function call as TEXT in `content`:**
+```bash
+curl -s "$BASE/chat/completions" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"@cf/qwen/qwen2.5-coder-32b-instruct",
+       "messages":[{"role":"user","content":"Triage: the elevator is broken and I am furious."}],
+       "tools":[{"type":"function","function":{
+         "name":"triage",
+         "parameters":{"type":"object","properties":{
+           "category":{"type":"string"},"sentiment":{"type":"string"}},
+           "required":["category","sentiment"]}}}],
+       "tool_choice":"auto",
+       "max_tokens":200}'
+```
+Look at `choices[0].message`: `tool_calls` will be `null`, and `content` will hold
+`<function-name>triage</function-name><args-json-object>{...}</args-json-object>`.
+→ Do NOT build a tool-calling agent on this. Use approach #3.
+
+**3. JSON output — the approach that works:**
+```bash
+curl -s "$BASE/chat/completions" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"@cf/qwen/qwen2.5-coder-32b-instruct",
+       "messages":[
+         {"role":"system","content":"Return ONLY valid JSON, no explanation, no markdown."},
+         {"role":"user","content":"Ticket: elevator broken, I am furious. Return {\"category\":\"...\",\"sentiment\":\"...\"}"}
+       ],
+       "max_tokens":200}'
+```
+Expect a clean JSON object in `content` (may already be parsed as a dict — handle both).
+
+---
+
+*Provenance: ab-tickets project, updated 2026-06 with deepagents model testing.*

package/skills/flow/playbooks/docker-deploy-stale-cache.md

@@ -0,0 +1,32 @@
+# Playbook: Docker layer cache serving stale backend builds on deploy
+
+## When to use this
+Any Dockerized backend with auto-deploy where a newly added route/endpoint returns 404
+on the deployed URL even though the code is merged and the deploy reported success.
+
+## ⚠️ THE GOTCHA
+The deploy "succeeds" but runs a STALE image: the layer cache reuses the old source
+layer, so your new endpoint never registers. Symptom: merged + deployed + green, yet the
+live `/docs` (or a curl) shows the route MISSING. Each occurrence reads like a code bug
+and costs a false debugging detour.
+
+**Diagnosis in one step:** check the live `/openapi.json` (or `/docs`) for the new route
+BEFORE debugging code. Route absent from the spec = stale image, not your code.
+(This is the swagger-lands-with-the-API rule earning its keep.)
+
+## Fixes (pick one, in order of preference)
+1. **Structure the Dockerfile so source COPY busts the cache**: dependencies layer first
+   (`COPY requirements.txt` + install), then `COPY . .` for source — source changes then
+   always rebuild the final layer while deps stay cached (fast AND fresh).
+2. **Dev phase: bind-mount the source** into the container instead of baking it, so
+   deploys don't depend on image rebuilds at all.
+3. **Last resort: force `--no-cache`** on the rebuild (slow; treats the symptom).
+
+## Smoke test
+After any deploy that adds a route:
+```bash
+curl -s https://<live-url>/openapi.json | grep '<new-route-path>' || echo "STALE IMAGE"
+```
+
+---
+*Provenance: ab-tickets, 2026-06 — cost ~4 false detours before the pattern was named.*

package/skills/flow/playbooks/rag-lite-postgres-cloudflare.md

@@ -0,0 +1,192 @@
+# RAG-lite — grounded LLM answers without a vector DB (Postgres + Cloudflare embeddings)
+
+How to add Retrieval-Augmented Generation to a backend feature **without** Vectorize / pgvector
+/ chunking pipelines / a doc-ingestion service. For a single tenant's handful-to-hundreds of
+documents this is 80% of the value at ~5% of the infra. Verified in the ab-tickets project.
+
+Pairs with: `cloudflare-ai-gateway-qwen.md` (the LLM-call side).
+
+---
+
+## Decision rule — do you even need a vector DB?
+
+| Situation | Use |
+|---|---|
+| One tenant, ≤ a few hundred short docs/snippets, retrieve top-3 to ground one answer | **RAG-lite (this playbook)** — embeddings in Postgres JSONB, cosine in app |
+| Thousands+ of docs, long documents needing chunking, multi-tenant at scale, sub-100ms retrieval | Real vector DB (Cloudflare Vectorize / pgvector / a managed RAG) |
+
+Don't reach for a vector DB by reflex. Computing cosine over a few hundred 1024-float vectors in
+Python is sub-millisecond. The vector DB earns its keep at scale, not at "ground this reply in
+the building's rules."
+
+---
+
+## The shape
+
+```
+doc text ──embed(bge-m3 via CF gateway)──> 1024-float vector ──store──> Postgres JSONB column
+query text ──embed──> qvec ──cosine vs every stored vec (in app)──> top-K ──inject into prompt
+```
+
+Two ways to consume the retrieved snippets:
+1. **RAG-lite grounding (single call)** — fetch top-K, paste into ONE structured LLM call. Cheap,
+   deterministic, no agent. Best for classify/draft/answer-this-one-thing. (C-011)
+2. **RAG as an agent tool** — expose `search_docs(query)` as a tool a deepagents agent calls when
+   *it* decides it needs policy context. Multi-step. Best for recap/investigate/chat. (C-013)
+
+---
+
+## Embeddings via Cloudflare AI Gateway (same seam as the chat model)
+
+Model: `@cf/baai/bge-m3` — 1024-dim, multilingual (handles Vietnamese well), batch input.
+OpenAI-compatible `/embeddings` endpoint on the same gateway base URL as chat.
+
+```python
+import httpx
+EMBED_MODEL = "@cf/baai/bge-m3"
+
+async def embed(texts: list[str]) -> list[list[float]]:
+    url = settings.cf_ai_gateway_url.rstrip("/") + "/embeddings"
+    async with httpx.AsyncClient(timeout=45) as client:
+        r = await client.post(url,
+            headers={"Authorization": f"Bearer {settings.cf_ai_token}"},
+            json={"model": EMBED_MODEL, "input": texts})
+        r.raise_for_status()
+    return [row["embedding"] for row in r.json()["data"]]
+```
+
+Smoke test (confirm dim + that it works through YOUR gateway):
+```bash
+curl "$BASE/embeddings" -H "Authorization: Bearer $CF_TOKEN" \
+  -d '{"model":"@cf/baai/bge-m3","input":["test một","test hai"]}' \
+  | python3 -c "import sys,json;d=json.load(sys.stdin);print('dim',len(d['data'][0]['embedding']))"
+# -> dim 1024
+```
+
+---
+
+## Storage — Postgres JSONB, no extension
+
+```python
+class DocSnippet(Base):
+    __tablename__ = "doc_snippets"
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=_uuid)
+    title: Mapped[str] = mapped_column(String(300))
+    content: Mapped[str] = mapped_column(Text)
+    embedding: Mapped[list] = mapped_column(JSONB, default=list)   # the 1024-float vector
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_now)
+```
+
+Embed on insert (so retrieval is read-only):
+```python
+@router.post("/docs")
+async def add_doc(payload: DocCreate, session = Depends(get_session)):
+    vector = (await embed([f"{payload.title}\n{payload.content}"]))[0]   # embed title+content
+    doc = DocSnippet(title=payload.title, content=payload.content, embedding=vector)
+    session.add(doc); await session.commit(); await session.refresh(doc)
+    return doc   # NOTE: response schema must NOT include `embedding` — don't leak the vector
+```
+
+GOTCHA: define a `DocOut` schema WITHOUT the `embedding` field, or the API leaks a 1024-number
+array on every list call. Embed `title + content` together so a query matches on either.
+
+---
+
+## Retrieval — cosine top-K in app, with a fallback
+
+```python
+import math
+TOP_K = 3
+MIN_SIM = 0.30   # below this, a snippet is too unrelated to inject — skip it
+
+def _cosine(a, b):
+    if not a or not b: return 0.0
+    dot = sum(x*y for x, y in zip(a, b))
+    na = math.sqrt(sum(x*x for x in a)); nb = math.sqrt(sum(y*y for y in b))
+    return dot/(na*nb) if na and nb else 0.0
+
+async def build_grounding(session, query_text):
+    docs = (await session.execute(select(DocSnippet))).scalars().all()
+    if not docs:
+        return faq_block(), [], FAQ_IDS                 # fallback A: no docs yet -> static FAQ
+    qv = (await embed([query_text]))[0]
+    scored = sorted(((_cosine(qv, d.embedding or []), d) for d in docs),
+                    key=lambda t: t[0], reverse=True)
+    top = [(s, d) for s, d in scored[:TOP_K] if s >= MIN_SIM]
+    if not top:
+        return faq_block(), [], FAQ_IDS                 # fallback B: nothing relevant -> FAQ
+    block = "\n".join(f"- [{d.id}] {d.title}: {d.content}" for _, d in top)
+    return block, [d.id for _, d in top], {d.id for d in docs} | FAQ_IDS
+```
+
+Three design points that matter:
+- **MIN_SIM threshold.** Without it, you always inject the 3 "least bad" docs even when none are
+  relevant — the model then hallucinates a connection. Below threshold, fall back to a generic
+  FAQ (or nothing) instead of forcing irrelevant context.
+- **Graceful fallback chain.** No docs uploaded → static FAQ. Docs exist but none match → FAQ.
+  Only inject docs when genuinely similar. The feature must work from day-zero (empty corpus).
+- **Return the matched ids.** Ask the LLM to echo which snippet ids it used (`faq_used`), then
+  validate that echo against the real id set server-side. Gives you "grounded in: [doc X]"
+  provenance for free, and catches the model inventing citations.
+
+---
+
+## Pattern 1 — RAG-lite grounding in a single structured call (C-011)
+
+Inject the retrieved block into the SAME single-call prompt (see the gateway playbook for the
+single-call + `_coerce_content` + enum-normalize approach). System prompt: *"Chỉ dùng thông tin
+trong tài liệu được cung cấp; nếu không chắc, đề nghị chờ xác minh."* (Only use the provided docs;
+if unsure, ask to wait for verification.)
+
+Real result: pasted a building rule "không nuôi chó trên 20kg" → resident asks about a 25kg dog →
+the grounded reply correctly said it exceeds the 20kg limit. That rule existed ONLY in the pasted
+doc, nowhere in code. Same query with no matching doc fell back to the generic FAQ, no crash.
+
+---
+
+## Pattern 2 — RAG as a deepagents tool (C-013)
+
+When the feature is agentic (the agent decides what it needs), expose retrieval as a tool instead
+of pre-injecting. The agent calls `search_docs(query)` with its OWN query, possibly multiple times.
+
+```python
+def search_docs(query: str) -> str:
+    """Tìm trong tài liệu/nội quy các đoạn liên quan tới truy vấn (RAG)."""
+    # deepagents tools run SYNC -> use a short-lived sync psycopg connection + sync embed,
+    # separate from the app's async engine. (asyncpg URL -> postgresql:// for psycopg.)
+    docs = _fetch_docs_sync()
+    qv = _embed_sync(query)
+    top = sorted(((_cosine(qv, emb), t, c) for t, c, emb in docs), reverse=True)[:3]
+    return "\n".join(f"[{t}] {c}" for s, t, c in top if s >= 0.25) or "Không tìm thấy."
+```
+
+Observed live: the recap agent called `list_open_tickets()`, saw fire + water complaints, then
+**on its own** called `search_docs('fire safety')` AND `search_docs('water supply')` — two distinct
+retrievals it chose based on what it found. That autonomy is the whole point of pattern 2; pattern 1
+can't do it because the query is fixed before the call.
+
+Sync-tool gotchas:
+- deepagents tools are sync functions. Don't await inside them. Use `psycopg` (sync) + sync `httpx`
+  for the embed, with a DSN derived from the async URL (`postgresql+asyncpg://` → `postgresql://`).
+- Run the whole agent in `run_in_threadpool(...)` from the async endpoint so it doesn't block the
+  event loop.
+- JSONB vectors may come back as a Python list (SQLAlchemy) or a JSON string (raw psycopg) —
+  `json.loads(emb) if isinstance(emb, str) else emb`.
+
+---
+
+## When to graduate to a real vector DB
+
+Move off RAG-lite when any of these hits:
+- Linear cosine scan gets slow (rule of thumb: > ~1–2k snippets per query).
+- Documents are long and need **chunking** (RAG-lite assumes each row is one already-small snippet).
+- You need filtered/metadata search, hybrid keyword+vector, or multi-tenant isolation at scale.
+Then: Cloudflare Vectorize (stays on CF), or pgvector (stays in Postgres, adds an index). The
+embed step (bge-m3 via the gateway) and the prompt-injection step are unchanged — only storage +
+the top-K query move.
+
+---
+
+Provenance: ab-tickets project (Vietnamese apartment-ticket app), 2026-06. RAG-lite = card C-011;
+RAG-as-agent-tool = card C-013. Stack: FastAPI + Postgres + Cloudflare Workers AI (bge-m3) via AI
+Gateway. No Vectorize, no pgvector, no chunking.

package/skills/flow/playbooks/windows-gitbash-jsonl-telemetry.md

@@ -0,0 +1,57 @@
+# Playbook: JSONL telemetry + tests on Windows Git Bash (shell writer / Python reader)
+
+## When to use this
+Any card that writes a JSONL/log file from POSIX shell (`flow.sh`) and reads or rolls it up
+from Python (`flow_harness.py`), OR any test that seeds a home-relative / temp-relative path
+and must run on Git Bash for Windows as well as macOS/Linux. The whole usage-log subsystem.
+
+## ⚠️ THE GOTCHA (this breaks first)
+**Bash `$HOME` and Python `os.path.expanduser("~")` resolve to DIFFERENT directories on
+Windows.** Git Bash honors `$HOME`; Python on Windows uses `USERPROFILE` (then `HOMEDRIVE`+
+`HOMEPATH`). So a test that does `export HOME="$SB/home"` and writes the device-global log
+with the shell, then reads it with `python ... usage --global`, silently reads the REAL
+`C:\Users\<you>\.claude\flow\usage.jsonl` instead of the sandbox — the test passes against
+production data or "finds nothing," and you chase a ghost.
+
+**Fix in tests:** set BOTH for any home-relative Python path:
+```sh
+export HOME="$SB/home"; export USERPROFILE="$SB/home"
+```
+
+## Second gotcha — temp-dir path forms don't match
+`$ROOT`/`$PWD` in Git Bash are POSIX (`/c/Users/.../Temp/proj`) but `$TEMP`/`$TMP` are
+Windows native (`C:\Users\...\Temp`). A naive `case "$ROOT" in "$TEMP"/*)` NEVER matches on
+Windows. Normalize both sides before comparing: backslash→slash, lowercase (Windows is
+case-insensitive), and `C:/`→`/c/`:
+```sh
+_norm_path() { printf '%s' "${1:-}" | tr 'A-Z\\' 'a-z/' | sed -E 's#^([a-z]):/#/\1/#'; }
+```
+Belt-and-suspenders: also match an mktemp-style basename (`tmp.*`) and a read-time SQL
+`project LIKE 'tmp.%'` — the name convention catches what path math misses.
+
+## Third gotcha — there is NO atomic append for regular files
+POSIX guarantees atomic writes only for **pipes** ≤ `PIPE_BUF`, NOT regular files. "Keep the
+line small so the append is atomic" is folklore for files. And **`flock` is absent in Git
+Bash for Windows** (verified) — don't reach for it. For a single-session-per-project tool the
+de-facto small-write append is fine; if you ever need real device-wide concurrency, shard the
+sink per-process/day and merge at read time (no lock needed). Keep JSON lines small and
+strip control chars (`tr -d '\000-\037'`) so one bad field can't corrupt a line the reader
+then skips.
+
+## Smoke tests (run before trusting telemetry on Windows)
+```sh
+# 1) shell writer and python reader agree on the global path
+export HOME="$PWD/sb/home"; export USERPROFILE="$PWD/sb/home"; mkdir -p "$PWD/sb/home/.claude/flow"
+python -c "import os;print(os.path.join(os.path.expanduser('~'),'.claude','flow','usage.jsonl'))"
+#   -> must print a path UNDER $PWD/sb/home, not C:\Users\<you>\...
+
+# 2) a project under $TEMP is detected ephemeral (path branch, non-tmp.* name)
+P="${TEMP}/realbuild_$$"; mkdir -p "$P"
+FLOW_PROJECT_ROOT="$P" bash runner/flow.sh status >/dev/null 2>&1
+grep -o '"ephemeral":[01]' "$P/.flow/events.jsonl" | tail -1   # -> "ephemeral":1
+```
+
+## Provenance
+flow-skill v0.11.0 usage-log telemetry correctness (2026-06-20). Gotchas 1+2 cost real test
+debugging in cards C-001/C-004; gotcha 3 corrected a wrong code comment about PIPE_BUF and
+killed the flock approach after verifying flock is missing on this Git Bash.