Documentation Layout

Most product and operational documentation lives under docs/. A small set of root guides still exists for onboarding, repo contracts, and tooling stability.

Structure

• docs/Domains/ - lớp điều hướng theo domain ở cấp repo; là cửa vào chính khi tư duy theo DOL English, DOL Academy, DOL Kid.
• docs/Shared/ - lớp điều hướng cho các workspace dùng chung toàn hệ.
• docs/Command/ - Design principles, glossary, templates, tracking.
• docs/Meta/ - home gọn cho meta index docs ở cấp repo; không phải product canon.
• docs/Domains/DOL English/Product Discovery/ - workspace discovery body docs cho English/platform baseline hiện tại.
• docs/Domains/DOL English/Feature Package/ - workspace feature framing body docs cho English/platform baseline hiện tại.
• docs/Shared/Shared Capabilities/Ecosystem Experience/ - ecosystem UX canon và north-star của toàn hệ.
• docs/Shared/Design System/ - design system canon, guideline, và assessment docs dùng chung toàn hệ.
• docs/Shared/Knowledge Base/ - academic and product knowledge notes plus imported mirror content.
• docs/Shared/Operations/ - operational runbooks, setup references, and workflow body docs.
• docs/context/ - Context routing cards for AI/tools (kept in sync with the paths above).

Root Priority Source Of Truth

• Không rename docs/Domains/, docs/Shared/, hoặc top-level docs folders chỉ để đổi thứ tự hiển thị.
• Nguồn cấu hình duy nhất cho root priority là config/docs-root-preferences.json.
• wikiAreaOrder điều khiển thứ tự area trong wiki/sidebar.
• wikiHiddenRootDirs ẩn các root chỉ dành cho meta/tooling khỏi wiki area discovery.
• authoringWorkspaceRoots điều khiển thứ tự root trong workspace authoring.
• Khi cần đổi ưu tiên:
  • sửa config/docs-root-preferences.json
  • chạy npm run authoring:workspace:gen
  • mở DOL Docs Authoring.code-workspace

Pathing & linking

• Use root-relative links with the docs/ prefix (e.g., docs/Domains/DOL English/UX Design/Payment/PAY_00_Overview.md).
• Frontmatter related_docs should also include the docs/ prefix.
• Context cards (docs/context/*.mdc) must reference the new paths; run npm run context:lint to validate coverage.

Default placement

• map placement chuẩn cấp repo -> docs/Domains/DOM_Docs_Content_Placement_Map.md
• tài liệu entry theo domain ở cấp repo -> docs/Domains/<domain>/**
• tài liệu dùng chung toàn hệ -> docs/Shared/**
• meta index docs ở cấp repo -> docs/Meta/**
• logic UX chi tiết theo domain -> docs/Domains/<domain>/UX Design/**
• UX north-star của cả ecosystem -> docs/Shared/Shared Capabilities/Ecosystem Experience/**
• discovery và feature framing theo domain -> docs/Domains/<domain>/Product Discovery/** hoặc docs/Domains/<domain>/Feature Package/**
• design system, knowledge, operations dùng chung -> docs/Shared/Design System/**, docs/Shared/Knowledge Base/**, docs/Shared/Operations/**
• runbook/reference vận hành -> docs/Shared/Operations/**
• AI/internal material -> .agent/**

Folder role rules

• docs/Domains/<domain>/Product Discovery/**
  • dùng khi cần ghi lại change log, decision log, workshop flow, constraint, open question, hoặc UX docs nào bị ảnh hưởng
  • là supporting lane cho UX authoring, không phải nơi giữ logic UX canonical của feature
  • không dùng làm bước bắt buộc trước khi sửa một screen/flow/feature user đã nói cụ thể
• docs/Domains/<domain>/Feature Package/**
  • dùng khi feature đã có shape tương đối rõ và cần package scope, dependency, rollout, acceptance, implementation framing
  • không dùng cho raw discovery dài hạn hoặc canonical UX surface docs
• docs/Domains/<domain>/UX Design/**
  • dùng khi tài liệu trả lời user sẽ thấy gì, đi flow nào, màn hình/state/interaction/copy ra sao
  • là canonical home của UX logic theo domain
  • là điểm vào mặc định khi prompt đã nêu feature, flow, screen, behavior, hoặc update cụ thể
  • không dùng để giữ discovery log dài hạn hoặc rule shared toàn hệ
• docs/Shared/Shared Capabilities/**
  • dùng cho capability, contract, north-star, policy, pattern được tái sử dụng bởi nhiều domain
  • nếu rule chỉ đúng cho một domain, giữ ở domain đó trước
• docs/Shared/Design System/**
  • dùng cho token, component, style rule, design-system governance
  • không dùng cho business logic hoặc narrative trải nghiệm của một feature
• docs/Shared/Knowledge Base/**
  • dùng cho tri thức nền, imported references, glossary, source material cần tham chiếu lại
  • không dùng làm nơi giữ decision active hoặc UX canon chính
• docs/Shared/Operations/**
  • dùng cho runbook, workflow, QA/audit, authoring operations, tool contracts
  • không dùng làm nơi giữ product truth
• docs/Command/**
  • dùng cho template, design principle, command/reference cấp repo
  • không dùng cho narrative của một domain cụ thể
• docs/Meta/**
  • dùng cho meta index, knowledge map, và repo-level retrieval note
  • không dùng để giữ product canon, UX canon, hoặc rule active của một domain
• docs/adr/, docs/generated/, docs/product-specs/, docs/quality/, docs/runbooks/
  • hiện được giữ như compatibility stub cho workflow/audit
  • giữ thật mỏng và route về docs/Meta/**; không mở rộng thành nơi viết canon mặc định
• docs/context/**
  • chỉ dành cho AI router cards, coverage, drill-down graph
  • không viết canonical narrative ở đây
• docs/tmp/**
  • chỉ dành cho artifact tạm, migration output, debug logs, generated snapshots
  • không để lại tài liệu muốn wiki đọc như nguồn chuẩn
• .agent/**
  • chỉ dành cho rule/workflow/prompt/skill nội bộ cho AI
  • không phải nơi đặt docs cho user đọc hằng ngày

Quick placement test

• Nếu user đã nêu feature / update / flow / screen cụ thể -> UX Design trước
• Nếu câu đầu tiên là ship feature này với scope nào, dependency nào, acceptance nào -> Feature Package
• Nếu câu đầu tiên vẫn là tại sao, cái gì đã đổi, còn đang workshop branch nào, và chưa có target UX rõ -> Product Discovery
• Nếu câu đầu tiên là nhiều domain cùng dùng -> docs/Shared/**
• Nếu câu đầu tiên là AI sẽ route thế nào -> docs/context/**
• Nếu chỉ là log, temp output, hoặc artifact -> docs/tmp/**

Trước khi tạo file guide mới

• Ưu tiên cập nhật một trong 4 file entry hiện có:
  • README.md
  • QUICK_GUIDES.md
  • START_HERE.md
  • GUIDELINES_MASTER.md
• Chỉ tạo guide mới khi nó có vai trò thật sự khác và không thể gộp gọn vào 4 file trên.

Guide shape defaults

• Với guide cho người đọc hoặc contributor, cố gắng trả lời đủ 5 câu:
  • tài liệu này dùng để làm gì
  • khi nào nên mở tài liệu này
  • nếu chưa phải đúng tài liệu để bắt đầu thì nên quay về đâu (QUICK_GUIDES.md hoặc START_HERE.md)
  • sau khi đọc xong nên làm gì tiếp
  • nếu có command, command tối thiểu là gì
• Ưu tiên section ngắn, heading rõ, và ngôn ngữ hành động thay vì prose dài.
• Không lặp lại full repo model nếu README.md, QUICK_GUIDES.md, START_HERE.md, hoặc GUIDELINES_MASTER.md đã nói rồi; link về các file đó là đủ.
• Nếu một guide nằm ở root nhưng là specialist doc, mở đầu nên nói rõ nó không phải onboarding chung và route người đọc quay lại QUICK_GUIDES.md.
• Nếu dùng thuật ngữ nội bộ như lane, full contract, canonical, sync-back, PR-first, scope owner, risk level, AI Assisted, runbook, web-only, Draft PR, Ready for review, auto-spec, hãy giải thích ngắn ngay lần đầu xuất hiện.
• Viết theo cách AI dễ đọc:
  • gọi tên file đích rõ ràng
  • dùng thuật ngữ nhất quán
  • tách phần khi nào dùng và khi nào không cần dùng

Domain-first navigation

• Khi user hoặc contributor nghĩ theo domain, ưu tiên bắt đầu ở docs/Domains/**.
• Chỉ khi cần tài sản dùng chung, mới mở docs/Shared/**.
• Khi cần north-star toàn ecosystem, mở docs/Shared/Shared Capabilities/Ecosystem Experience/**.

Domain workspace defaults

• Mỗi domain nên có 1 root overview và tối thiểu 3 workspace overview:
  • Product Discovery
  • Feature Package
  • UX Design
• Trong workspace UX Design, mỗi domain tiếp tục có 3-6 surface overview để chứa logic UX cụ thể.
• docs/Shared/** chỉ giữ workspace dùng chung; không phải nơi đặt nội dung chính của một domain.
• Các body docs của Product Discovery, Feature Package, Design System, Knowledge Base, và Operations hiện đã sống trực tiếp trong workspace mới; không cần duy trì thêm một lane song song ở root.

UX doc role stack

• Mục tiêu là giữ cả traceability lẫn feature readability, thay vì tối ưu một phía rồi làm vỡ phía còn lại.
• Đây là default routing model, không phải bureaucracy cứng cho mọi trường hợp.
• Ưu tiên luôn là chọn cấu trúc nhẹ nhất vẫn đủ rõ để người đọc và AI không hiểu sai.
• Thứ tự đọc/ghi chuẩn trong docs/Domains/<domain>/UX Design/**:
  • workspace-entry
    • entry cấp domain UX workspace.
    • ví dụ: ENG_UX_00_Overview.md.
  • feature-master
    • file owner chính cho một feature lớn hoặc cross-surface.
    • giữ current truth, reading path, owner map, và những rule đủ để hiểu feature trong 1 hop.
  • feature-rule (optional)
    • chỉ tách riêng khi feature quá lớn hoặc cần matrices/boundary chi tiết.
    • không phải file bắt buộc cho mọi feature.
  • surface-entry hoặc surface-overview
    • overview cho một surface hoặc module owner.
  • page/spec/flow/concept docs
    • owner detail, screen logic, and screen-level concept output.
• Product Discovery (EVT / DEC / STATE / VIEWS) không thay thế feature-master.
• Idea Flow Lite không thay thế feature-master; nó chỉ thuộc lớp screen/concept artifact.
• Với UX logic của một feature, source of truth nằm trong UX Design, không nằm trong Product Discovery.
• Nếu feature còn nhỏ, local, hoặc mới ở mức sketch, có thể đi thẳng bằng surface/page docs hoặc idea-flow trước; chỉ nâng lên feature-master khi logic bắt đầu chạm nhiều surface hoặc dễ bị hiểu sai.

Conflict-avoidance rules

• 1 concern = 1 owner layer.
  • current UX logic / current behavior -> feature-master
  • detailed UX rule when needed -> feature-rule
  • owner-surface behavior -> surface/page docs
  • change log / rationale / decision trail / workshop record -> Product Discovery
  • screen concept / reminder-first artifact -> idea-flow docs
• Lower layer không được silently redefine upper layer.
  • page docs không tự chốt lại cross-surface rule nếu feature-master hoặc feature-rule đã giữ rule đó.
  • Product Discovery không được trở thành owner doc song song với UX Design cho cùng một logic feature.
  • idea-flow docs không được trở thành source-of-truth cho feature logic.
• Với feature lớn hoặc cross-surface, mặc định chỉ nên có 1 feature-master active trong một domain tại một thời điểm.
• Nếu hai file cùng trả lời cùng một câu hỏi ở cùng một layer, phải hợp nhất hoặc đánh dấu rõ file owner và file supporting.

Recommended update order

• Nếu thay đổi chỉ ở mức screen/presentation và không chạm feature logic:
  • update surface/page/concept docs trước là hợp lệ.
• Nếu thay đổi chạm feature logic hoặc cross-surface behavior:
  1. update feature-master,
  2. update feature-rule nếu feature đó có file rule riêng,
  3. update surface/page docs,
  4. sync-back Product Discovery ở mức gọn nếu thay đổi đó cần lịch sử/quyết định/workshop record,
  5. update screen/concept docs chỉ khi có concept artifact thật sự cần giữ.
• Nếu thay đổi vẫn còn ở mức local hoặc exploratory, có thể bắt đầu trực tiếp từ surface/page docs rồi mới nâng lên feature-master khi cần.
• Với prompt đã nêu rõ feature nhưng chưa xuống screen cụ thể, ưu tiên mở feature-master trước.
• Với prompt chỉ nêu screen hoặc screen flow cụ thể, idea-flow/screen docs có thể đi trước, miễn là không vô tình đổi canon feature-level.

AI-assisted refinement loop

• Khi agent chạm một feature đang active trong UX Design, agent nên chạy một lightweight completeness sweep.
• Sweep này không phải hard gate; mục tiêu là phát hiện sớm phần còn thiếu mà không làm nặng flow.
• Ưu tiên rà 5 góc:
  • entry / trigger / return path
  • state / edge cases / failure mode
  • ownership / boundary / canonical home
  • cross-surface impact / shared dependency
  • open validation / assumption / measurement
• Nếu gap là non-blocking:
  • ghi ngắn vào open validation,
  • hoặc thêm một follow-up note,
  • hoặc nêu gợi ý ngắn cho user.
• Chỉ block khi gap đó đủ lớn để đổi branch UX chính hoặc có nguy cơ làm logic active sai.

Idea-flow boundary

• Idea Flow Lite là reminder-first, not a full spec, và tối ưu cho one screen, one file.
• Vì vậy nó rất hợp cho:
  • screen concepts,
  • flow checkpoints,
  • lightweight UI reminders,
  • ghi lại idea mới hoặc concept delta trong lúc xây tài liệu UX.
• Nó không phù hợp để làm:
  • canonical feature overview,
  • cross-surface rule owner,
  • domain-level current truth.
• Khi một feature bắt đầu bị đọc như nhiều screen rời rạc, bổ sung feature-master trước khi mở rộng thêm concept docs.

Context Card Schema (AI Router)

• Mỗi card trong docs/context/*.mdc dùng schema chuẩn:
  • Required: id, title, description, max_files
  • Recommended: scope_tags, keywords
  • Coverage sources: files (explicit) hoặc folder_roots (auto-expand)
  • Drill-down: next_cards hoặc domain_file
• Với context card dành cho AI router, description nên trả lời ngắn:
  • card này dùng khi câu hỏi thuộc nhóm nào
  • nếu là router card thì nó sẽ chuyển sang đâu
  • nếu là specialist card thì nó có phải onboarding chung hay không
• Tránh description quá abstract kiểu proxy, core, staging contract nếu không giải thích; ưu tiên ngôn ngữ trực tiếp như roadmap feature, glossary, template viết logic, mirror sync tự động.
• Lint report mode: npm run context:lint
• Lint report mở rộng (schema health + graph diagnostics): npm run context:audit
• Lint strict mode (CI/local gate): npm run context:guard
• Routing benchmark (query -> expected cards): npm run context:benchmark
• Stale-card detector (non-blocking): npm run context:stale
• Combined quality report: npm run context:quality
• context:guard hiện chặn các lỗi:
  • missing files/folder_roots refs
  • uncovered docs
  • broken context graph (domain_file, next_cards, duplicate card IDs)
  • agent-readability gates: oversized max_files, branch factor quá lớn, router card quá rộng, card thiếu signal tags/keywords, duplicate explicit file-set giữa cards
• context:guard mặc định loại trừ artifacts vận hành:
  • docs/tmp/
  • docs/Shared/Operations/IdeaFlowHandoff/records/runs/
• Benchmark cases nằm tại config/context-routing-benchmark.json
• Context authoring rule cho AI/team: .agent/rules/rule-context-routing-standards.md

Coverage policy (lean)

• Mục tiêu chính: coverage cao cho docs canonical (overview/logic/flow/contracts/concepts).
• docs/tmp/ và run logs trong docs/Shared/Operations/IdeaFlowHandoff/records/runs/ là artifacts vận hành, không phải nguồn context ưu tiên.
• Khi review coverage, ưu tiên đánh giá:
  • raw coverage (toàn repo docs), và
  • canonical coverage (loại trừ artifacts vận hành nêu trên).

Artifact retention (long-term)

• Preview dọn artifacts runtime: npm run artifacts:prune:dry
• Apply dọn artifacts runtime: npm run artifacts:prune
• Mục tiêu: giữ lại history gần nhất phục vụ debug, loại bớt artifacts cũ để repo gọn và giảm nhiễu cho AI.
• Mặc định đang để retention nới lỏng (không siết chặt) để hỗ trợ giai đoạn khám phá/sáng tạo.
• Chỉ chạy artifacts:prune khi chủ động dọn dẹp; không phải gate bắt buộc cho mọi vòng phát triển.

Migration notes

• Domain-first đã được nâng từ mức UX-only lên mức repo-level qua docs/Domains/** và docs/Shared/**.
• Các body folders Product Discovery, Feature Package, Knowledge Base, Operations, và Design System đã được đưa vào home mới trong docs/Domains/** hoặc docs/Shared/**.
• Root docs/UX Design/ đã được retire; ecosystem UX canon nằm tại docs/Shared/Shared Capabilities/Ecosystem Experience/**.
• Placement canon cho toàn repo được chốt tại docs/Domains/DOM_Docs_Content_Placement_Map.md.
• Scripts scripts/context_lint.py và scripts/update-recents.mjs đã được đồng bộ với layout mới.
• If you find old links without docs/, please update them; Markdown preview and the wiki ingestion expect the docs/ prefix.