create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/docs/superpowers/specs/2026-10-17-antd-look-tokens.md

@@ -0,0 +1,28 @@
+# Decision: design language = antd look (light default) — supersede direction B làm theme phụ
+
+Ngày: 2026-10-17 · Trạng thái: APPROVED (chat) · Supersede phần visual của direction B (VU-53)
+
+## Quyết định
+
+User chốt: "UI cần giống y như antd" + chọn phương án **Clone antd look trên components
+tự viết + Tailwind** (không install antd, không giữ dark-only).
+
+1. **tokens.css đổi GIÁ TRỊ sang visual language antd v5/v6 default (light)** — var names
+   GIỮ NGUYÊN (components/tests/tailwind @theme không đụng mã):
+   - accent `#1677ff` (antd colorPrimary), hover `#4096ff`
+   - canvas `#f5f5f5` (colorBgLayout), container `#ffffff`, hover-fill `#fafafa`
+   - ink `rgba(0,0,0,.88)` / `.65` / `.45`; line `#d9d9d9` / line2 `#f0f0f0`
+   - status: todo gray `#bfbfbf`, doing `#faad14`, done `#52c41a`, fail `#ff4d4f`
+   - font stack antd, base 14px; radius 4/6/8 giữ
+2. **Direction B hiện tại (dark) trở thành THEME PHỤ** — `styles/themes/dark.css` scoped
+   `[data-bp-theme='dark']` (giá trị = tokens direction B cũ y nguyên). Switching =
+   Phase theming (UiKitProvider theme='light'|'dark').
+3. Structural antd-ness (shadow popover/modal, hover lifts) đi kèm phase migrate
+   components/pages — token `--shadow-1` thêm khi phase đó cần.
+4. Token docs page + storybook preview chuyển light default, giữ story dark demo.
+
+## Hệ quả
+
+- Pixel của VU-53 evidence (screenshots dark) không còn là current look — archive giữ
+  nguyên trong docs/superpowers/evidence (lịch sử).
+- prefers-color-scheme / theme switching: Phase theming quyết (không auto-switch giờ).

package/stack-template/docs/superpowers/specs/2026-10-17-auth-real-design.md

@@ -0,0 +1,124 @@
+# Spec: Epic Auth thật thay auth-mock
+
+Ngày: 2026-10-17 · Trạng thái: **rev 2** — spec-critic + plan-critic FIX-P0 đã xử (PR #13) ·
+Archetype: **CC — Cross-cutting contract** (wakii-playbook §2) · Story epic đầu tiên áp dụng playbook.
+
+## Bối cảnh
+
+auth-mock là JWT HS256 NOT-FOR-PROD: password dev chung, không refresh, không register,
+không revoke. Là điểm yếu #1 khi scaffold boilerplate sang project thật (CLAUDE.md đánh giá
+2026-10-17). Epic này thay bằng service auth thật, giữ nguyên surface `/api/auth/*` :8090
+để gateway/port-table/FE-flow không đổi.
+
+## Quyết định đã chốt (user, chat 2026-10-17)
+
+| # | Quyết định | Chọn | Không chọn |
+|---|---|---|---|
+| 1 | Scope MVP | **Full MVP**: register + login + refresh (rotation) + RBAC demo + decommission auth-mock | login-only; không-refresh |
+| 2 | Port + path | **auth-svc đón :8090 `/api/auth/*`** — gateway/env/README không đổi, port 4-chỗ không kích hoạt | port mới :8091 song song |
+| 3 | Users schema | **auth-svc owns schema `auth` riêng** (users + refresh_tokens), seed từ users.json GIỮ UUID | spring owns; gộp vào spring |
+| 4 | Refresh mechanism | **Opaque + rotation + revoke** — CAS atomic, reuse → revoke **toàn bộ token của user** (strict) | JWT pair; chain-only revoke |
+| 5 | FE READ-LOCKED | **Wrapper `refresh-client.ts` file mới** — token-storage.ts API đã đủ | sửa token-storage.ts |
+| 6 | Ngôn ngữ | **Node Fastify + TS + Drizzle** (mirror node-svc) | Go + chi |
+| 7 | *(rev 2)* **`iss` claim** | **PIN `iss: "auth-mock"`** — 3 service + 2 CI workflows hardcode giá trị này; đổi tên = rework 3 vùng + rework CI. Follow-up nhỏ riêng (đổi 3 constant + workflows) khi có SF chạm cả 3 vùng | đổi thành "auth-svc"; env-ify ngay trong epic |
+| 8 | *(rev 2)* **Response shape v2** | `{user, accessToken, refreshToken}` — **drop `tokenType`/`expiresIn`** (e2e chỉ cần accessToken); FE SF-4 cập nhật theo | giữ tokenType/expiresIn |
+| 9 | *(rev 2)* **auth.yaml v1 paths** | **Giữ `GET /users`** (FE demo picker — auth-svc serve từ schema auth); **drop `/.well-known/openid-configuration`** (không ai consume; path OIDC ghi token-contract) | giữ cả 2 |
+| 10 | *(rev 2)* **Password compat** | `AUTH_DEV_PASSWORD` default **`demo-password`** (`${AUTH_DEV_PASSWORD:-demo-password}`) — e2e + svc-activity + fixture seed cùng một nguồn | default `change-me-auth` |
+
+Token claims `sub/email/roles` giữ nguyên shape; HS256 giữ nguyên. Access TTL **8h → 30m**;
+token cũ cùng `iss` vẫn verify trong chuyển tiếp. Refresh TTL **7d** (tầng contract).
+
+## Kiến trúc
+
+```
+auth-svc (mới, :8090 /api/auth/* — workspace member, standalone lockfile như node-svc)
+  schema auth (role auth_svc — schema-only, custom migrate runner như node-svc):
+    users          (id UUID PK ← fixture UUID GIỮ NGUYÊN, email UNIQUE lowercase-normalized,
+                    display_name, roles text[] NOT NULL DEFAULT '{"user"}',
+                    password_hash argon2id, created_at)
+    refresh_tokens (id uuid PK, user_id FK, token_hash sha256, expires_at,
+                    revoked_at NULL, replaced_by uuid NULL, created_at)
+```
+
+- **Seed**: từ `contracts/auth/users.json` — giữ nguyên UUID + displayName + roles;
+  password = `AUTH_DEV_PASSWORD` (default demo-password); **users.json KHÔNG thêm password**;
+  idempotent `ON CONFLICT (id) DO NOTHING`.
+- **Rotation atomic (CAS)**: `UPDATE auth.refresh_tokens SET revoked_at=now(), replaced_by=$new
+  WHERE id=$old AND revoked_at IS NULL RETURNING` — 0 rows = **reuse-detect** → revoke tất cả
+  refresh_tokens của user + 401. 2 tab refresh đồng thời: request thua CAS điReuse-detect
+  (chấp nhận strict — FE single-flight lock giảm xác suất; documented).
+- **spring-svc giữ users table của nó** cho demo @Transactional — cùng UUID từ fixture,
+  không sync runtime (roles source-of-truth = token claims).
+- **svc-activity** (go-svc) login đúng flow cũ, password = cùng `AUTH_DEV_PASSWORD`
+  (users.json $comment đã ghi pattern này).
+- **Register**: roles gán `["user"]`; email normalize lowercase trước lưu/lookup;
+  password 8–72 ký tự (argon2 input limit).
+
+## API (contracts/openapi/auth.yaml v2 — SF-1)
+
+| Endpoint | Body | Response / Note |
+|---|---|---|
+| `POST /api/auth/register` | {email, password(8–72), displayName} | 201 `{user, accessToken, refreshToken}`; 409 email trùng |
+| `POST /api/auth/login` | {email, password} | 200 same shape; 401 sai thông tin |
+| `POST /api/auth/refresh` | {refreshToken} | 200 cặp mới (CAS rotation); reuse → 401 + revoke-all |
+| `POST /api/auth/logout` | {refreshToken} | 204 — **idempotent** (token đã revoked vẫn 204) |
+| `POST /api/auth/logout-all` | (Bearer) | 204 revoke tất cả của `sub` |
+| `GET /api/auth/users` | — | **giữ v1** — danh sách user demo (auth-svc serve từ schema auth) |
+| `GET /healthz` + `/readyz` | — | mirror naked + prefix (conventions/02 rule 6) |
+| ~~`/.well-known/openid-configuration`~~ | — | **drop** (không ai consume; path OIDC ở token-contract.md) |
+
+**RBAC demo:** node-svc `DELETE /api/tasks/:id` yêu cầu roles chứa `admin` — alice admin
+(e2e hiện tại giữ pass), bob → 403 (assert thêm). Gateway vẫn chỉ presence-check.
+
+**FE (SF-4):** `app/shared/src/refresh-client.ts` (file MỚI): login/register lưu cặp
+(access → tokenStorage; refresh → `localStorage['bp.rt']` — key mới, rationale pin vào
+token-contract.md v2 để security-pass không mở lại); 401 → refresh single-flight đúng
+một lần → retry; logout gọi endpoint + clear 2 key. `token-storage.ts` READ-LOCKED không đổi.
+
+## CI ownership (rev 2 — P0 spec-critic + plan-critic)
+
+| File | SF sở hữu | Thay đổi |
+|---|---|---|
+| `.github/workflows/contracts.yml` | **SF-1** | schemathesis scope hẹp lại (chỉ paths auth-mock đã implement — mới thêm sẽ 404); **SF-5**: boot auth-svc thay auth-mock + bỏ assert `"iss"` nếu cần |
+| `.github/workflows/services-auth-svc.yml` | **SF-2 (tạo mới)** | từ workflow-templates: build + test + docker build + boot-smoke |
+| `.github/workflows/services-node-svc.yml` | — không đổi | test payload `iss: "auth-mock"` — vẫn đúng (iss pinned) |
+| `.github/workflows/services-go-svc.yml` + `services-spring-svc.yml` | **SF-5** | boot auth-svc thay auth-mock (tên container) |
+
+Chấp thuận gates: `iss` pinned → node workflow payload không đổi ✓.
+
+## SF tier bracket (story mode — 5 SF)
+
+| SF | Tier | Nội dung | Gate chính |
+|---|---|---|---|
+| SF-1 | 0 | auth.yaml v2 + token-contract.md v2 (iss pinned, TTLs, rotation/CAS/reuse, bp.rt rationale) + gap-answer ĐẦY ĐỦ (compose entry + depends_on key + nginx upstream + go-svc `AUTH_MOCK_URL` value + users.json mount + init role `auth_svc` + .env rename AUTH_MOCK_* + workspace line + **contracts.yml schemathesis scope**) | spectral + schemathesis scoped |
+| SF-2 | 1 | auth-svc: schema + seed + 5 endpoints + CAS rotation + reuse-detect + **services-auth-svc.yml workflow** | workflow mới xanh + tests |
+| SF-3 | 1 | node-svc RBAC DELETE admin-only + 403 tests | node suite |
+| SF-4 | 1 | FE refresh-client + LoginPage register tab + auto-refresh + a11y | shell suite + coverage gate (90/90/80/90) + a11y |
+| SF-5 | 2 | convergence: e2e mở rộng + decommission (thực thi gap-answer: compose/nginx/go-env/users-mount/init/.env renames) + **CI swap 3 workflows** + docs sync rộng (walkthrough, CLAUDE.md, orca.yaml, README, toolchain, gotcha `down -v`) + security pass | e2e + CI toàn main xanh + human walkthrough |
+
+## Điều kiện chấp nhận (epic DONE)
+
+1. `pnpm lint:contracts` xanh; schemathesis auth.yaml PASS (scoped SF-1, full SF-5).
+2. auth-svc: register→login→refresh→reuse-old→401+revoke-all; logout idempotent 204;
+   logout-all hết hiệu lực — integration test chứng minh từng bước.
+3. e2e 2 chiều hiện tại PASS không sửa (login đọc `accessToken` ✓; password default
+   demo-password ✓; iss pinned ✓).
+4. DELETE task bằng bob → 403 envelope; alice → 200 (unit SF-3 + e2e SF-5).
+5. FE: access hết hạn → auto-refresh đúng 1 lần không 401 UI; logout-all → **các tab khác
+   chết ở request kế tiếp (401 → refresh fail → về login)** — verify qua human walkthrough
+   2 tab (không claim cross-tab realtime).
+6. compose boot auth-svc healthcheck xanh; **volume postgres cũ cần `down -v` 1 lần
+   (gotcha mới vào orca.yaml + walkthrough)**.
+7. Security pass 0 P0/P1: argon2id, rotation CAS, reuse-detect, không log password/refresh,
+   **localStorage `bp.rt` = accepted-for-demo (rationale pin trong token-contract.md —
+   httpOnly-cookie là upgrade path ghi rõ)**.
+8. Docs sync rộng: walkthrough + CLAUDE.md + orca.yaml + README + toolchain + `.env.example`
+   (rename AUTH_MOCK_*) + grep `auth-mock` = rỗng trên docs + `.env.example` + workflows
+   (token-contract/users.json giữ histórico tên trong $comment nếu cần).
+9. *(rev 2)* **CI toàn main xanh sau SF-5 merge** (contracts/go/spring swap auth-svc boot).
+
+## Non-goals
+
+OAuth/OIDC (RS256/JWKS — path token-contract.md), password reset qua email, rate-limit
+distributed, multi-tenant, đổi claims shape, **đổi `iss` string (follow-up riêng)**,
+httpOnly-cookie storage (upgrade path ghi token-contract.md).

package/stack-template/docs/superpowers/specs/2026-10-17-tailwind-migration.md

@@ -0,0 +1,32 @@
+# Spec: Tailwind v4 migration — toàn bộ app styling
+
+Ngày: 2026-10-17 · Trạng thái: APPROVED (chat cùng ngày) · Bổ sung cho: ui-kit-split spec + 4-phase plan (vẫn đúng, styling cơ chế đổi)
+
+## Quyết định (user đã chọn)
+
+1. **Tailwind áp dụng TOÀN BỘ app** — primitives ui-kit + pages shell/remotes; xoá dần
+   scoped css `.tsk-*` / `.sh-*` / `.act-*` và section primitives `bp-*` của base.css.
+2. **tokens.css giữ làm NGUỒN DUY NHẤT** — Tailwind v4 `@theme inline` map thẳng
+   `var(--accent)`, `var(--ink2)`… → utilities (`bg-accent`, `text-ink2`) tự theo tokens;
+   accent-override runtime (Phase theming) hoạt động không đổi config.
+3. Tailwind **v4** (CSS-first, `@import "tailwindcss"`): PostCSS plugin cho 3 app Rspack
+   (`@tailwindcss/postcss` + postcss-loader), Vite plugin cho Storybook (`@tailwindcss/vite`).
+4. **Preflight KHÔNG bật** giai đoạn đầu — giữ reset hiện có của base.css để tránh visual
+   shift hàng loạt; cân nhắc đổi sau khi mọi trang đã Tailwind (story riêng).
+5. Phase 重排 (build Tailwind-first tránh double-styling):
+   - **P0 infra**: @theme + postcss/vite wiring + `@source` cho app/ui-kit sources + proof
+     1 primitive (Badge) end-to-end (test + storybook + app build)
+   - **P1**: 4 primitives còn lại + `BusyBox` + `className/classNames/style` props + a11y
+     addon gate; USAGE.md
+   - **P2**: `Tag.Checkable` thay chips Tasks; `Button`; `Input/Textarea` (born Tailwind)
+   - **P3**: refactor shell pages (styles.css → utilities, xoá sh-*)
+   - **P4**: refactor tasks + activity pages (xoá tsk-*/act-*), base.css chỉ còn reset/global
+   - **P5**: `UiKitProvider` accent-override + tokens docs page bản Tailwind
+6. Mỗi phase = 1 PR riêng (git-flow), evidence đối chiếu storybook/screenshot giữ pixel
+   direction B. Tests đang select theo class `bp-*`/`tsk-*` đổi sang role/structure/API props.
+
+## Non-goals
+
+- Không đổi design direction B (màu/spacing/radius/typography giữ tokens)
+- Không dùng tailwind.config.js (v4 CSS-first); không CSS-in-JS runtime
+- Không preflight trong phase đầu

package/stack-template/docs/superpowers/specs/2026-10-17-ui-kit-split.md

@@ -0,0 +1,44 @@
+# Spec: tách UI kit thành package riêng + Storybook Phase 1
+
+Ngày: 2026-10-17 · Trạng thái: APPROVED (design duyệt trong chat cùng ngày) · Nguồn: thảo luận "lib UI cần storybook?" + "base component cần tách thư viện riêng"
+
+## Bối cảnh
+
+Sau story VU-53, design system (tokens + base + 4 primitives) sống trong `app/shared`
+cùng 4 file logic READ-LOCKED (api-client/token-storage/error-envelope/mf-bootstrap).
+Boundary "design system ≠ logic" bị trộn — SF design-system sau này phải đụng package
+có vùng cấm. Đồng thời primitives chỉ được review qua screenshot ad-hoc, không có
+catalog sống.
+
+## Quyết định (đã duyệt)
+
+1. **Package mới `app/ui-kit` (`@wakii/ui-kit`)**: `src/ui/*` (Badge/EmptyState/Skeleton/
+   Spinner) + `src/styles/{tokens,base}.css`. `app/shared` giữ 4 file logic (READ-LOCKED
+   không đổi nội dung).
+2. **Consumption QUA SOURCE** — giống fe-shared: main/types → src/, không build, không
+   runtime dep (react types do consumer cung cấp; devDeps react chỉ cho test).
+3. **Consumers đổi thẳng import** — không re-export cầu: UI stuff từ `@wakii/ui-kit`,
+   logic từ `@wakii/fe-shared`. 3 consumers (shell, remote-tasks, remote-activity).
+4. **Storybook 9 + Vite builder trong ui-kit** (kèm luôn, không phase sau): stories cho
+   4 primitives (đủ variants/states) + trang docs tokens. KHÔNG: stories cho MF views,
+   visual-regression trả phí. Spike rút gọn: storybook dev-only, không đụng MF runtime
+   pin-matrix — evidence = build-storybook PASS + dev screenshot, ghi trong commit.
+5. Hạ tầng: Dockerfiles ×3 COPY ui-kit (lockfile importer cần package.json khi install
+   frozen trong container); convergence copy-dir typecheck standalone CẢ fe-shared LẪN
+   ui-kit (pattern @types/react + --jsx đã fix); CI workflow `ui-kit` mới (typecheck +
+   test + build-storybook gate); ADR-0009; descriptor sync (CLAUDE.md, orca.yaml,
+   agents/fe-dev, scaffold).
+
+## Điều kiện chấp nhận
+
+- `pnpm install --frozen-lockfile` PASS; 3 FE suites + typecheck + build xanh từ paths mới
+- `bash scripts/smoke/e2e.sh` PASS trên compose rebuild (shell render primitives từ ui-kit)
+- `pnpm --filter @wakii/ui-kit build-storybook` PASS trong CI; stories cover mọi variants
+- fe-shared standalone typecheck (copy-dir) vẫn PASS — không còn TS6142 sau khi ui/*
+  rời đi; ui-kit standalone typecheck PASS với pattern @types/react
+- Scaffold: project mới nhận ui-kit + storybook build được (CI scaffold-verify che build shell)
+
+## Non-goals
+
+- Build step/publish registry cho ui-kit; stories cho TasksPage/ActivityPage; Chromatic
+  hoặc visual-regression; đổi MF pin-matrix.

package/stack-template/docs/superpowers/specs/2026-10-18-0.3.0-release-notes.md

@@ -0,0 +1,77 @@
+# @wakii/ui-kit 0.3.0 — Release notes (NHÁP)
+
+> Draft 2026-10-18 — tổng hợp từ `CHANGELOG.md` `[Unreleased]` (story VU-53 UI redesign,
+> 2026-10-17/18). **Đối chiếu chéo lần 2 với CHANGELOG (changelog = chân lý): counts/story
+> liệu khớp từng bullet; hash ngoài changelog được verify bằng `git log` thật.**
+> PR: [#55](https://github.com/__STACK_ORG__/architecture-overview/pull/55)
+
+## Breaking changes
+
+**None.** 0.2.x consumers upgrade không phải đổi gì: mọi API mới là additive; đổi tên
+trong chu kỳ (`Collapse` transition → `CollapseTransition` barrel, precedent `UiImage`)
+xảyra TRƯỚC release nên không consumer nào ngoài đang dùng tên cũ; legacy prop
+`scrollHeight` của Table vẫn nhận (ưu tiên thấp hơn `scroll.y` mới).
+
+## Số liệu (đếm thật 2026-10-18)
+
+| Chỉ số | Giá trị | Nguồn |
+|---|---|---|
+| Titles Storybook | **129** | `index.json` unique titles (hôm nay) |
+| Story exports | **623** | `index.json` ids non-docs (750 ids gồm docs pages) |
+| Template stories | **18 entries / 4 templates live** | nhóm Templates (Dashboard · Kanban Project · CRUD Table · Auth) |
+| Test files | **136** (`*.test.ts*`) | `find src -name "*.test.ts*"` — README badge 540+ behavior tests |
+| Component mới chu kỳ 0.3.0 | **50+** | đếm từ CHANGELOG `[Unreleased]` + git log (liệt kê dưới) |
+| Storybook test-runner | 215/215 stories render-verified | README § Quality |
+
+## 1. Component mới (50+)
+
+**Data / grid / tree:** `List` + `AvatarGroup` + `TreeSelect` — 28 tests (`530a4a1`) · `VirtualScroll` + Table `virtual` (`b8fd380`) · `Table` `expandable` — 28 tests + 19 stories (Gap P0, worker W6; commit `6545bf8`) · `Table` advanced: `scroll.y` fixed header + `summary` tfoot + sorting 3-state — 12 tests + 4 stories (worker W6) · `TreeTable` đệ quy + `Layout` frame (`b73d2e6`) · `Timesheet` — 9 tests + 7 stories (`dd740e5`) · `KanbanBoard` + DragDrop primitives — 25 tests + 10 stories (`1782a5d`, `a8e6fd1`) · `OrgChart` — 8 tests + 4 stories (`7e3d0ec`) · `Accordion` single/multiple — 9 tests + 6 stories (`03e8ad2`)
+
+**Forms:** `useForm` + peer-dep zod ^4 — 9 tests (`375baae`) · `useFieldArray` (Form.List parity, `append/remove/move/swap/update/nameAt` + lỗi đi theo ROW) — 12 tests + 3 stories (`8c5f716`) · `Field` (`5615a9b`) · `DatePicker` range/showTime + `TimePicker` + locale vi/en — 25 tests (`f4d1883`) · `InputNumber` restyle stepper (`ab76cfe`) · `Checkbox` tri-state — 4 tests (bộ 7→11) (`4b85830`) · `Input.Search` (`6545bf8`)
+
+**Navigation / menu:** `Menu` đa cấp + `Sidebar` collapsible — 24 tests + 7 stories (`11bb127`) · `MegaMenu` + `SlideMenu` — 14 tests (8+6) + 9 stories (`7e3d0ec`) · `Pagination` antd redesign 32px (`ab76cfe`) · `ContextMenu` keyboard nav + `Dropdown` đồng bộ + `Tree/Steps/TabMenu/Menubar/Timeline` a11y pass (`1a086a8`)
+
+**Overlay / feedback:** `Popover` (`291ce0d`) · `Watermark` SVG data-URI (`291ce0d`) · `Alert` `filled` + tokenize `--alert-*-filled` (`ab76cfe` + `1a086a8`) · `FloatButton`(+/`Group`/BackTop) · `BottomNavigation` · `Fieldset` · `DeferredContent` — 26 tests + 16 stories (`70f1f36`)
+
+**Drag & drop / qr / tour:** `DragDropProvider`/`Draggable`/`DropZone` — tính trong bộ 25 tests trên (`1782a5d`) · `QRCode` vendored — 11 tests + 5 stories (worker W6, `6545bf8`) · `Tour` spotlight (`b0eb469`)
+
+**Motion (0 deps, transform/opacity only):** `Fade`/`Zoom`/`CollapseTransition`/`Backdrop` — 13 tests (10+3) + 7 stories (`157cfc2`) · `Parallax`/`Reveal`/`CountUp` — 23 tests (7+8+8) + 13 stories (`47e1f55`) — `prefers-reduced-motion` toàn bộ
+
+**Layout / grid:** `Row`/`Col` 24-col responsive · `Flex` · `Anchor` scroll-spy — 35 tests + stories EN (`4fd4323`)
+
+**Hạ tầng:** `Icon` 48 primeicons (`463cef4`) · hooks native ×16 — 60 behavior tests (`4baf52b`) · `Upload` + `UploadDropzone` — 14 tests + 5 stories (`55288b1`) · subpath exports nặng `carousel|chart|schedule|editor` (`5615a9b`, `463cef4`) · z-scale tokens `--z-*` (`5615a9b`) · tokens scrim/mask `--scrim-1..4` + `--mask` + `--fs-h3` (`1a086a8`)
+
+## 2. Templates (mới — điểm bán trực quan)
+
+4 trang ghép sống trong Storybook, controlled state thật — 18 story entries:
+
+| Template | Path | Nguồn |
+|---|---|---|
+| Dashboard admin | `templates-dashboard--dashboard` | (`3a55922`) |
+| Kanban Project (WIP + filter + Timesheet + toast) | `templates-kanban-project--project-board` | (`3a55922`) |
+| CRUD Table (sort/filter/bulk-delete/Drawer form/useForm focus-first) | `templates-crud-table--full-demo` | worker W6 (`src/templates/crud.stories.tsx`) |
+| Auth (Sign in / Sign up / split) | `templates-auth--sign-in` · `--sign-up` · `--split-layout` | (`417f089`) |
+
+Roadmap: Settings + Landing (recipe 9/10 sẵn). Showcase: `Kitchen Sink` full tour (`2f038c2`).
+
+## 3. A11y
+
+- WAI-ARIA sweep interactive (2026-10-18): **Tabs** roving tabindex + ←/→/Home/End + `aria-controls/labelledby` · **Modal/Drawer/Popconfirm/Popover** `role=dialog` + `aria-modal` + `aria-labelledby` (đủ cả title ReactNode) · **Dropdown/Menu** trigger `aria-haspopup=menu` + `aria-expanded` · **RadioGroup** name chung (arrow-key native) + accessible name · **Select** clear × operable bằng Enter/Space · **TreeTable** `role=treegrid` + `aria-level/expanded/selected`
+- Chuỗi `1a086a8`: Tooltip `aria-describedby` · Popconfirm `aria-haspopup=dialog` + `aria-expanded` · ContextMenu ArrowUp/Down/Home/End + `aria-disabled` · Tree `role=treeitem/group` · Steps `aria-current="step"` · TabMenu `aria-current="page"` · focus-ring sweep Pagination/Inplace/PanelMenu/Segmented/ToggleButton
+- `Checkbox` tri-state `aria-checked="mixed"` (`4b85830`) · keyboard DnD full (Tab→Space→arrows→Enter/Esc + aria-live, `1782a5d`) · icon-only buttons labeled · focus-ring chuẩn `ring-accent/40` toàn thư viện (`28a4f11`)
+
+## 4. Dark mode & visual
+
+- **Custom scrollbar** mảnh 8px pill token-driven (`8013033`) · dark cascade audit (Listbox hex → `bg-accent/10`, DarkTheme stories MegaMenu/SlideMenu — `4b85830`) · MegaMenu/SlideMenu dark screenshot-verified (`7e3d0ec`) · Alert filled WCAG AA (`ab76cfe`) · Schedule skin FullCalendar qua CSS vars (`1a086a8`) · DatePicker contrast polish + Select check accent + CascadeSelect panel + Table zebra dịu (`1a086a8`) · Carousel nav hoạt động thật swiper v14 + Calendar đồng bộ ngôn ngữ (`292b1a3`)
+
+## 5. Fixes
+
+- Dark theme không ăn (`@import` đứng sau rule bị drop) (`ab76cfe`) · 17 story file 0-export indexer drop — **fix batch đưa index 51 → 79 titles, 190 stories** (`6f4c9a0`; đo hôm nay 129 titles sau các batch tiếp theo) · stories Pagination TS2322/TS2353 sau merge (`a55b2fe`) · useFocusTrap dialog không focusable (`1a086a8`) · InputNumber stepper flush container (`e94b3e4`) · Storybook CSF render-only gotcha (meta `component:` + required props → TS2322) — quy ước ghi vào AGENTS Anti-patterns
+
+## 6. Storybook infra
+
+Toolbar dark-mode toggle `addon-themes` (body preview — `:root` light đè dark cùng specificity, body tránh) · trang Introduction docs + `storySort` · manager brand theo token · canvas padding 24px · bỏ `backgrounds` param (`8d8dad1`) · sống tại `:6006` + static build CI
+
+---
+
+**Việc còn mở trước release:** promote notes vào `CHANGELOG.md` đổi `[Unreleased]` → `[0.3.0]` · decide 2 issue design đang chờ (tooltip dark surface; white text trên `--st-doing/--st-done`) · Settings/Landing templates (roadmap 0.3.1) · badge README cập nhật số sau release · merge qua **PR [#55](https://github.com/__STACK_ORG__/architecture-overview/pull/55)**.

package/stack-template/docs/toolchain.md

@@ -0,0 +1,28 @@
+# Toolchain — cần gì ở đâu (boilerplate FI-62)
+
+Bảng đối chiếu tool × môi trường. Nguyên tắc: **máy dev không có Docker vẫn làm việc được 100%** (native per-service); Docker chỉ cần cho compose mode + một số bước verify (có thể đưa qua CI).
+
+| Tool | Version | Dev native | Dev compose | CI | Ai cần |
+|------|---------|-----------|-------------|-----|--------|
+| Node.js | 22 LTS (engines >=22) | ✓ | — | ✓ setup-node 22 | node-svc, auth-svc, toàn FE, scaffold output |
+| pnpm | 9 (corepack) | ✓ | — | ✓ corepack | cùng Node ở trên |
+| JDK | 21 (Temurin) | ✓ | — | ✓ setup-java 21 | spring-svc (mvnw tự tải deps — không cần Maven cài sẵn) |
+| Go | 1.24.x | ✓ (hoặc skip — CI build) | — | ✓ setup-go 1.24 | go-svc (`go.sum` không commit — `go mod tidy` sinh) |
+| Docker + Compose v2 | — | ✗ | ✓ | ✓ (ubuntu runner có sẵn) | chạy `platform/docker-compose.yml`; build image per service |
+| Postgres | 16 | ✓ (cài riêng/portable) | ✓ (container) | ✓ (container compose) | mọi service BE + e2e smoke |
+| bash + curl | — | ✓ (Git Bash trên Windows) | ✓ | ✓ | chạy `scripts/smoke/e2e.sh`, `scripts/scaffold/scaffold.sh` |
+| jq | — | không cần (script dùng grep thuần) | — | có sẵn | — |
+
+## Ma trận task × tool tối thiểu
+
+| Task cần làm | Tool cần ở máy |
+|--------------|----------------|
+| Sửa node-svc / auth-svc / FE | Node 22 + pnpm + Postgres 16 (test) |
+| Sửa spring-svc | JDK 21 (mvnw lo phần còn lại) |
+| Sửa go-svc | Go 1.24 (hoặc để CI build — dev chỉ đọc code) |
+| e2e smoke local | bash + curl + stack sống (compose HOẶC native — walkthrough.md) |
+| Scaffold project mới | bash + pnpm (Node 22) |
+| Build image / compose up | Docker (hoặc push → CI làm) |
+
+## Lưu ý portable (máy khoá admin)
+Mọi tool trên đều chạy được bản portable không cần admin (precedent: `~/Tools/sf6-e2e` — JDK 21 + Go 1.24 + Postgres 16 portable, xoá được). Extract là chạy, không installer.

package/stack-template/docs/wakii-playbook.md

@@ -0,0 +1,172 @@
+# Wakii Playbook — tổ chức story cho boilerplate
+
+Cách dùng story-workflow (Wakii) khi phát triển **chính repo này** và project scaffold từ nó
+(`scripts/scaffold/scaffold.sh` copy `docs/` — trừ `docs/superpowers/` — nên playbook ở `docs/`
+đi theo project mới).
+
+**Đọc khi nào:** sắp có việc lớn hơn 1 task, cần quyết chia story hay làm lẻ — và khi chia
+rồi, tra công thức slice theo loại epic. **Không lặp** nội dung skill (`story-workflow`,
+`orca-superpowers-workflow`) — ở đây chỉ có phần *riêng của boilerplate*: archetype chia SF,
+thứ tự đụng file theo conventions, gates nào đỏ vì gì. Quy tắc vàng ở [CLAUDE.md](../CLAUDE.md);
+kiến trúc ở [walkthrough.md](walkthrough.md); "vì sao" ở `docs/adr/`.
+
+> Bài học chung của 3 story đã qua (FI-62 micro-boilerplate · FI-76 kafka-outbox-saga ·
+> VU-53 ui-redesign):
+> chi phí lớn nhất không phải code — là **slice sai**: SF quá to (review không kịp), quá nhỏ
+> (overhead gate > giá trị), hoặc phụ thuộc ngầm (2 SF đụng cùng file → worker chặn nhau ở Phase 4).
+
+---
+
+## 1. Khi nào dùng gì (decision tree)
+
+| Việc | Dùng | Ví dụ thật trong repo |
+|---|---|---|
+| >3 sub-feature **hoặc** >10 tasks, nhiều người/agent làm song song | **Story mode** — epic Linear + mindmap `.wakii` + SF sub-issues, bracket theo tier | FI-62 (7 SF), FI-76 (5 SF), VU-53 (5 SF tier bracket) |
+| 1 sub-feature hoàn chỉnh, 3–10 tasks | **Single workflow** — `orca-superpowers-workflow` trên 1 Linear issue, đủ Phase 0–5 | từng SF FI-64..FI-75 chạy đơn lẻ giai đoạn đầu FI-62 |
+| Fix 1 điểm rõ gốc rễ, không đụng contract/port | Fix trực tiếp + test, không story | `fix(auth-mock): assert user count theo fixture` (ee0117c) |
+| Đổi behavior có MainPage động | 1 story nhỏ 2–3 SF vẫn ổn — đừng ép story mode chỉ vì "to" | — |
+
+Ngưỡng mờ: **2 SF mà có phụ thuộc tier (một cái Unblock hẳn cái kia) → story mode** — bracket
+tier là giá trị thật, không phải ceremony.
+
+---
+
+## 2. Bốn archetype epic — công thức chia SF
+
+Trước khi CREATE story, trả lời 5 câu (ghi vào epic summary):
+
+1. Đụng **contracts/** không? (OpenAPI / DDL / event / users.json) — đụng là SF-1 contracts, không ghép với impl.
+2. Đụng **port hoặc route gateway** không? — kích hoạt quy tắc 4 chỗ (conventions/05 + .env.example + compose + README cùng commit).
+3. Đụng **READ-LOCKED** không? (`app/shared/src/{api-client,token-storage,error-envelope,mf-bootstrap}.ts`, `package.json#mfToolkit`, catalog pins) — cần epic duyệt + re-spike qua `app/spike`.
+4. Cần **secret/env mới** không? — liệt kê vào `.env.example` ở SF-1, không để SF cuối mới discover.
+5. Chạy **song song được không?** — SF cùng tier KHÔNG được đụng cùng file; đụng → tách tier.
+
+Rồi tra archetype:
+
+### CC — Cross-cutting contract
+*Đổi thứ mọi thứ phụ thuộc: auth thật, error envelope v2, thêm field event, đổi envelope shape.*
+
+- **Slice theo tầng, không theo service:** SF-1 contracts + gateway route → tier 1 services thích ứng (song song) → tier 1 FE → tier 2 convergence + decommission cái cũ.
+- **SF-1 là hiệp ước:** code sau phải theo spec rev đó; đổi spec giữa chừng = rollback SF-1, không vá lẻ.
+- **Gates:** drift-guard CI (snapshot `activity.yaml` nhúng trong go-svc phải bit-identical `contracts/openapi/activity.yaml`), schemathesis contracts CI, human walkthrough ở convergence.
+- **Rủi ro đặc trưng:** CI convergence đỏ liên hồi trong giai đoạn chuyển (2 nửa đổi không cùng lúc) → SF-1 phải giữ **tương thích ngược có kiểm soát** (token cũ còn verify, event cũ còn consume) hoặc đổi đồng loạt trong 1 SF duy nhất — chọn một, ghi rõ trong epic summary.
+- Mẫu sống: chương 4 (epic auth thật).
+
+### NS — Service mới
+*Thêm service vào demo (vd notification-svc consume task-events).*
+
+- **Câu hỏi làm rõ TRƯỚC khi tính slice** (mỗi câu đổi hình dạng SF-1):
+  | Câu hỏi | Hệ quả kỹ thuật |
+  |---|---|
+  | Sync hay async? | Có Kafka → conventions/09 + topic tạo tường minh trước consumer |
+  | Ngôn ngữ nào? | Node ngoài workspace → standalone lockfile (variant conventions/01); Go → drift-guard snapshot + distroless không healthcheck shell (conventions/02) |
+  | Có DB riêng? | DDL vào `contracts/db/` + role schema-only trong postgres init + migration pattern (drizzle/Flyway/auto) |
+  | Port mấy? | Quy tắc 4 chỗ cùng commit (conventions/05 + .env.example + compose + README) |
+  | FE có hiển thị? | Có → tách SF riêng cho remote/page, không gộp vào SF impl |
+- **Công thức 4 SF:** SF-1 khung (contracts OpenAPI + DDL + entry compose + CI workflow — impl rỗng nhưng boot + healthcheck xanh) → SF-2 impl API → SF-3 consumer/producer + FE hiển thị → SF-4 convergence e2e mở rộng.
+- **Đừng đóng SF-1 trước khi** `docker compose up` riêng service boot được với role DB schema-only (bài học drizzle `CREATE SCHEMA` permission — improvements-log 2026-10-12).
+- **Gates:** boot-smoke CI + drift-guard snapshot; conventions mới (nếu có) phải thuộc SF-1, không nhét SF cuối.
+- **Rủi ro:** topic auto-create race → tạo topic tường minh TRƯỚC consumer subscribe (conventions/09; bug thật SF-3 kafka story: consumer kẹt im lặng, 0 fetch 0 error).
+
+### FE — FE/UX epic
+*Đổi UI đáng kể (mẫu: VU-53).*
+
+- **Design trước, code sau, tier tách bạch:** design gate front-load NGAY LÚC CREATE (mock-prototype 3 hướng, user chọn, hand-off `docs/superpowers/designs/`) → SF-1 tier 0 design-system nền móng (tokens + primitives, không phá hiện trạng) → tier 1 từng vùng UI song song → tier 2 convergence + human browser walkthrough.
+- **Quy tắc sống còn của tier 1:** mỗi SF một vùng file (`shell/` | `remotes/tasks` | `remotes/activity`); fe-shared chỉ tier 0 đụng; css scoped, không sửa style chung sau tier 0.
+- **Gates:** direction-approved record trước SF-1; a11y test; walkthrough 8-acceptance + responsive 375px ở convergence (VU-53 precedent).
+- **Rủi ro:** react/rspack/MF upgrade đụng catalog pins → **phải re-spike** qua `app/spike` trước, không nâng trong epic UI.
+
+### IN — Infra/platform
+*Observability, upgrade toolchain, đổi CI, compose.*
+
+- **Slice theo lớp infra, tách phần compose khỏi phần code:** entry compose + env là 1 SF (verify bằng boot-smoke), code service thích ứng là SF sau — đừng trộn.
+- **Quyền sửa compose:** `platform/docker-compose.yml` có lịch sử sở hữu ghi ở đầu file — SF nào cũng KHÔNG tự sửa nếu không được brief ủy quyền; muốn đổi → flag coordinator kèm gap-answer ghi lại vào comment compose (precedent SF-5/SF-6 FI-62).
+- **Gates:** convergence e2e trên compose 10 services là gate thật (dev machine không Docker → verify qua CI, `gh run watch`); down-scale heap kafka 512m giữ nguyên cho CI 7GB.
+- **Rủi ro:** secrets — thêm env mới = `:?set in .env` ép lỗi sớm; KHÔNG commit `.env`; story-guard-secrets chặn inline secret (export qua script file nếu cần override).
+
+---
+
+## 3. Checklist lifecycle (một dòng một pha)
+
+- [ ] **Phase 0** — impact analysis (phase0-impact-analyst): touch map + blast radius trước khi viết dòng spec nào.
+- [ ] **Spec** — brainstorm → `docs/superpowers/specs/YYYY-MM-DD-<topic>.md` → spec-critic GO trước khi plan.
+- [ ] **Plan + DAG** — writing-plans-linear (subtask lên Linear) → plan-critic nếu ≥5 tasks; SF cùng tier không đụng cùng file.
+- [ ] **CREATE story** — mindmap `.wakii` (tier + depends-on + Linear id từng SF) + context pack `contexts/<story>/sf-N.md` cho từng SF; FE epic: design gate xong TRƯỚC khi dispatch SF-1.
+- [ ] **Dispatch theo tier** — tier 0 xong mới tier 1; context pack trả lời HẾT câu epic-level ("Đã trả lời hết epic-level — KHÔNG hỏi lại"); SF hội tụ KHÔNG fix bug miền khác, REPORT coordinator.
+- [ ] **Execute mỗi SF** — contracts TRƯỚC code; TDD chỗ được, ghi `tdd: skipped-tdd: CI-only <lý do>` chỗ không (dev thiếu JDK/Docker); review ĐỘC LẬP verdict APPROVED materialize ra file.
+- [ ] **Evidence** — `docs/superpowers/evidence/<sf>/` + `test-run.txt` ghi HEAD **tại lúc code commit cuối** (docs commit sau làm B1 flip FAIL — loop nổi tiếng của SF-3).
+- [ ] **Gate SF** — `story-verify` B1–B3 sạch; executor KHÔNG merge, KHÔNG set Linear Done — coordinator làm cả hai.
+- [ ] **Convergence (tier 2)** — full suite xanh + e2e 2 chiều PASS + browser walkthrough human gate + docs sync (walkthrough/README/orca.yaml cùng commit).
+- [ ] **Merge + đóng** — coordinator merge SF về dest (story model); **dest → main qua PR** theo [git-flow.md](git-flow.md) (CI xanh + `--no-ff`, từ 2026-10-17 — không push thẳng main); epic Linear Done; xoá state run/task lệch (như case SF-5 `ready` còn treo sau khi main đã merge).
+- [ ] **Post-task-ritual** — improvements-log.md ghi bài học (flag, KHÔNG tự sửa skill); archetype mới → cập nhật playbook này **cùng commit merge**.
+
+---
+
+## 4. Worked example — epic "Auth thật thay auth-mock" (archetype CC)
+
+> ⚠️ Đây là **ví dụ minh hoạ công thức chia SF** — không phải spec auth. Khi epic được duyệt thật:
+> brainstorm + spec riêng (câu 1–5 chương 2 + quyết định mở bên dưới), rồi mới CREATE story.
+
+**Mục tiêu (draft):** thay auth-mock bằng service auth thật — register/login/refresh + enforcement
+RBAC. `roles` (`user|admin`) đã có sẵn trong users.json + token contract (claims `sub/email/roles`,
+Alice đã `admin`) — việc thật là **enforcement ở services + register/refresh**, không phải thêm
+roles. Non-goals: OAuth/social, multi-tenant, rate-limit distributed.
+
+**Decision points phải chốt ở Phase 0 (mỗi cái đổi hình dạng DAG):**
+
+| Quyết định | Phương án | Hệ quả DAG |
+|---|---|---|
+| Port + path | auth-svc thật **đón luôn :8090 + giữ `/api/auth/*`** | gateway, conventions/05, .env, README **không đổi** — quy tắc 4 chỗ không kích hoạt (khuyến nghị) |
+| Users schema | spring-svc đang owns users — auth-svc đọc qua API spring vs owns schema riêng | Nếu owns riêng: SF-2 thêm migration + role DB; nếu qua spring: SF-2/SF-3 ghép chặt → gộp 1 SF |
+| Token contract | giữ claims `sub/email/roles` + thêm refresh/rotation (token-contract.md dòng 69 đã chốt: nâng OIDC thì claims giữ nguyên) vs đổi cấu trúc | Giữ: node/go sửa riêng từng SF khả thi; Đổi: buộc đồng loạt 1 SF |
+| `token-storage.ts` READ-LOCKED | wrapper mới không đụng file locked vs epic duyệt sửa | Wrapper: SF FE gọn; Sửa: cần approval epic + re-spike |
+
+**Slice SF đề xuất (bracket tier):**
+
+- **SF-1 · tier 0 — Contracts + hiệp ước:** mở rộng `contracts/openapi/auth.yaml`
+  (register/refresh), `contracts/auth/token-contract.md` v2 (refresh/rotation — claims
+  `sub/email/roles` giữ nguyên), users.json **KHÔNG đổi** (UUID + roles đã chuẩn — saga fail-user
+  `svc-fail` và seed spring còn khớp), env mới vào `.env.example`. Gate: spectral + schemathesis
+  xanh; KHÔNG đụng code runtime.
+- **SF-2 · tier 1 — auth-svc:** impl register/login/refresh (+ quyết định users-schema ở trên),
+  auth-mock chuyển chế độ legacy-flag tạm. Gate: unit + integration token thật; compose boot xanh.
+- **SF-3 · tier 1 — Services thích ứng (song song SF-2 nếu token shape giữ):** node-svc + go-svc
+  middleware verify roles; go-svc service-token (`svc-activity`) đổi theo token contract; drift-guard
+  snapshot không đổi nếu API không đổi. Đụng file khác SF-2/SF-4 hoàn toàn.
+- **SF-4 · tier 1 — FE:** login giữ behavior + messages contract (test shell hiện có là reguação),
+  thêm refresh flow; test shell hiện có (login behavior + error messages) là ràng buộc giữ nguyên;
+  **`e2e.sh` hardcode `alice@demo.local`** → nếu password/flow đổi, SF này phải đồng bộ smoke script
+  (hoặc SF-5 sẽ đỏ). READ-LOCKED theo decision ở trên.
+- **SF-5 · tier 2 — Convergence + decommission:** e2e mở rộng login → refresh → RBAC 403 → saga
+  fail-user **vẫn xanh**; tắt auth-mock (hoặc giữ `AUTH_MOCK_MODE=legacy`); docs sync 4 chỗ; human
+  walkthrough cuối.
+
+**Gates đắt tiền nhất của epic này:** (1) drift-guard + schemathesis ở SF-1; (2) CI convergence
+đỏ trong window SF-2..4 nếu token shape đổi mà không giữ tương thích — đây là lý do decision
+"token shape" phải chốt TRƯỚC khi CREATE; (3) human walkthrough SF-5.
+
+---
+
+## 5. Anti-patterns — bài học đã trả giá (từ 3 story + improvements-log)
+
+| Anti-pattern | Hậu quả thấy thật | Quy tắc |
+|---|---|---|
+| Consumer subscribe khi topic chưa tồn tại (auto-create race) | Consumer kẹt im lặng — stable group, 0 fetch, 0 error (SF-3 kafka) | Tạo topic tường minh TRƯỚC boot consumer; không `depends_on kafka` |
+| Evidence `test-run.txt` ghi hash, sau đó commit docs mới | Gate B1 flip FAIL không do code (SF-3, lặp 2 lần) | Hash ghi tại code commit cuối; story-verify chấp nhận docs-only sau hash |
+| Bắt `orca run-create` trả top-level `id` | Lấy nhầm request-id → 9 task orphan ngoài run (FI-62) | Id thật ở `.result.run.id` / `.result.gate.id`; task-create validate run tồn tại |
+| Executor tự nghĩ mình merge được | `story-verify` B4 FAIL mãi ở handoff | B4 executor-view = PENDING-MERGE; merge là việc coordinator |
+| `sed -i` / `realpath -m` GNU-only trong script | Scaffold fail trên macOS (fix 2026-10-17) | Script dùng chung repo: detect BSD/GNU 1 lần, python3 thay `realpath -m` |
+| pnpm `catalog:` + standalone install `--ignore-workspace` | `ERR_PNPM_CATALOG_ENTRY_NOT_FOUND` (SF-7 copy-dir) | Mini workspace: sed catalog block từ root, install KHÔNG ignore-workspace |
+| Đổi spec giữa chừng SF đang chạy | Rollback cả SF, mất 1 vòng review | Spec sai giữa chừng = STOP + REPORT coordinator, không vá lẻ trong SF impl |
+| Test "ma" — tên có vẻ assert, thực chất không | Review APPROVED oan: phantom grep không assert gì (sf-5b phải rà lại) | Mỗi acceptance có 1 assert thật trỏ đúng behavior; reviewer đọc assert, không đọc tên test |
+
+---
+
+## 6. Cập nhật playbook
+
+Epic mới không khớp archetype nào ở chương 2 → **đừng ép** vào archetype cũ. Merge mọi nhánh story về main qua PR (git-flow.md) — quy tắc này đè model merge-thẳng-dest của các story trước 2026-10-17. Thêm archetype mới
+(định nghĩa + công thức slice + gates + rủi ro — cùng format) trong **cùng commit merge epic đó** —
+cùng nguyên tắc với orca.yaml: descriptor đi cùng thay đổi nó mô tả, drift = lỗi onboarding.
+
+Bài học một-lần-theo-epic cứ để improvements-log; bài học **lặp lại từ epic thứ hai** mới lên
+playbook (tiêu chí lọc — không biến playbook thành nhật ký).