> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xanhcard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AGENTS

> For Mintlify product knowledge (components, configuration, writing standards),
> install the Mintlify skill: `npx skills add https://mintlify.com/docs`

# Documentation project instructions

## About this project

* Documentation site for **XanhCard** — a digital wallet pass platform (Apple Wallet & Google Wallet)
* Built on [Mintlify](https://mintlify.com). Pages are MDX with YAML frontmatter.
* Configuration: `docs.json`
* Content language: **Vietnamese**, written in second person ("bạn")
* No `package.json` — this is a pure content repo. The `mint` CLI must be installed globally:

```bash theme={null}
npm i -g mint
```

## Commands

```bash theme={null}
mint dev           # Preview locally at http://localhost:3000
mint broken-links  # Check broken links
mint update        # Update to latest CLI version
```

## Navigation wiring (critical)

**Page navigation is driven by `docs.json`, not the filesystem.** When you add, rename, or move a page:

1. Create/edit the MDX file in the appropriate directory
2. Update the `navigation.tabs[].groups[].pages` array in `docs.json` to include the new path (omit the `.mdx` extension)
3. If creating a new section directory, also add a matching group in `docs.json`

The filesystem directory structure and the `docs.json` navigation structure are independent — consistency is manual.

## Image conventions

* All images live under `images/`, grouped by section: `images/templates/`, `images/scanners/`, `images/events/`
* File naming: numbered prefix + descriptive name (e.g., `images/templates/01-dashboard-home.png`, `images/templates/02-click-templates.png`)
* Reference in MDX: `/images/templates/01-dashboard-home.png`
* Follow sequential numbering within each section when adding new images

## Terminology

* **Pass / Thẻ**: Thẻ kỹ thuật số hiển thị trong Apple Wallet hoặc Google Wallet
* **Template / Mẫu thẻ**: Bản thiết kế cho thẻ
* **Project / Dự án**: Không gian làm việc chứa tất cả nội dung
* **Scanner / Máy quét**: Ứng dụng quét mã thẻ
* **Data Model / Mô hình dữ liệu**: Cấu trúc trường dữ liệu cho thẻ
* **Branch / Chi nhánh**: Địa điểm kinh doanh trong dự án. Dùng cho `project/branches.mdx`, `guides/branch-tracking.mdx` và phần lọc chi nhánh của Dashboard

## Wiki sync point

Nguồn sự thật kỹ thuật: `~/Codes/passeditor/droid-wiki` — wiki sinh từ working tree của sáu module repo. Lần rà soát gần nhất: **`generatedAt 2026-09-24T19:50:00Z`** (66 trang).

Quy tắc đồng bộ: khi `droid-wiki/.wiki-meta.json` có `generatedAt` **mới hơn** mốc trên, rà lại các trang docs bị ảnh hưởng trước khi viết nội dung mới. Bảng ánh xạ trang docs → trang wiki nằm trong `openspec/changes/docs-product-parity/design.md` §"page → wiki review map".

Wiki là nguồn để **tra tính chính xác**, không phải nguồn để sao chép. Wiki viết cho người bảo trì: các trang có mục "Key source files", "Entry points for modification", và mô tả chi tiết nội bộ như tên hàm, collection, handler. Docs chỉ được mô tả những gì người dùng quan sát được — xem mục "Content boundaries" bên dưới.

## Marketing context sync (required)

Nguồn chân lý về sản phẩm, gói giá và claim: `.agents/product-marketing-context.md` (workspace root). Đọc trước khi viết hoặc sửa trang tính năng/gói giá; khi context cập nhật, soát lại các trang liên quan.

* **Gói & hạn mức**: mọi bảng/định mức phải khớp `getting-started/plans.mdx` và mục Business model trong context. Docs hiện có 4 gói (Free/Starter/Growth/Pro); Enterprise chưa có trang riêng.
* **Ranh giới claim — không viết như sự thật**:
  * Tên connector POS (KiotViet/Sapo/iPOS/Haravan/Pancake) — chỉ "kết nối qua API/webhook"
  * "Kết nối POS" / "Đồng bộ POS" trong **thông tin gói** (bảng gói, danh sách tính năng theo gói, bảng so sánh) — đã gỡ 25/09/2026
  * "SOC 2", "mã hoá đầu-cuối", "check-in ngoại tuyến", "QR xoay vòng"
  * Zalo/SMS cho thông báo — kênh thật: APNs (Apple Wallet), messages (Google Wallet), Web Push, email vòng đời gói
  * Thanh toán năm: giảm 10% (đã chốt 25/09/2026) — docs và website đã đồng bộ
  * Gói Miễn phí không có máy quét QR (`EnableQRScanner = false`) — không viết Free có máy quét
* **Thuật ngữ**: glossary ở mục Terminology là canonical cho docs (Pass/Thẻ, Template/Mẫu thẻ, Data Model/Mô hình dữ liệu...). Khi mượn câu chữ từ marketing ("Thẻ Wallet", "Ví"), map về thuật ngữ docs; tránh cột "Không dùng" trong `.agents/content-guideline.md`.
* **Số liệu**: mọi số liệu phải kèm nguồn + năm, lấy từ bảng Claims & nguồn; không tự bịa.
* **Tính năng**: mô tả đúng những gì docs hiện có — máy quét 9 hành động (`scanners/actions.mdx`: Validate Pass, Increment, Decrement, Update Data, Void, Sync, Notify, Webhooks, Scan Once); mẫu thẻ **6 style** (`templates/overview.mdx`: Event Ticket, Generic, Store Card, Business Card, Voucher, Stamp Card — lấy từ `CreateTemplateModal.svelte` §`listStyle`; luật "3 style" trước đó đã bị bác bỏ ngày 25/09/2026 vì trái với UI đang chạy); ngôn ngữ theo template (Default Language + Supported Languages, **danh sách cố định 7 mã** `en`, `vi`, `fr`, `de`, `jp`, `kr`, `zh` — từ `GeneralTab.svelte` §`languageList`, KHÔNG phải mã nhập tự do).
* **Đối chiếu website**: các claim chưa khớp docs (POS theo tên, QR xoay vòng, check-in ngoại tuyến, SOC 2) đã được gỡ khỏi `website/src` ngày 25/09/2026. Docs vẫn là nguồn tính năng canonical — không lấy câu chữ marketing làm nguồn cho docs.
* **Khoảng trống docs**: năng lực **chặn chụp màn hình** đã được mô tả trong `templates/general.mdx` §"Screenshot Suppression" (toggle trong General → Extends). Năng lực **chi nhánh** đã có trang riêng: `project/branches.mdx` và `guides/branch-tracking.mdx`.

## Writing style

* Nội dung chính bằng tiếng Việt
* Use active voice and second person ("bạn")
* Keep sentences concise — one idea per sentence
* **Sentence case** for headings
* **Bold** for UI elements: Nhấn **Save**
* `Code formatting` for file names, commands, paths, and data variables (`{{$data.fieldName}}`)
* Common Mintlify components: `Steps`, `Step`, `Accordion`, `AccordionGroup`, `Card`, `CardGroup`, `Note`, `Tip`, `Warning`, `Info`, `Tabs`, `Columns`

## Content boundaries

* Document all user-facing features and workflows
* Do not document internal admin features
* Do not document development setup unless relevant to end users

## Notes

* `api-reference/` contains a Mintlify **starter template** (`openapi.json` with sample Plant Store API). Real XanhCard API docs haven't been built here yet — verify before editing.
* `.mintignore` auto-excludes: `.git`, `.github`, `.claude`, `.agents`, `.idea`, `node_modules`, `README.md`, `LICENSE.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, and any `drafts/` or `*.draft.mdx` files.
* Contextual options in `docs.json` enable AI tool integrations (ChatGPT, Claude, Perplexity, MCP, Cursor, VS Code) — these affect the rendered docs UI, not the repo itself.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.