Source Index
這頁承接原本 docs/README.md 的 taxonomy：Markdown 仍是 source of truth，Dev Portal 只把入口整理得更容易掃描。
Directory taxonomy
| 位置 | 用途 | 命名 |
|---|---|---|
docs/ | 目前仍有效的架構、API、政策、設計文件，或仍在進行中的 plan/proposal | <topic>.md |
docs/dev-portal/ | Dev Portal 導覽頁：onboarding、domain map、flow、source index、graph explorer | <topic>.md |
docs/history/ | 已完成的一次性遷移、盤點、整理或決策紀錄 | YYYY-MM-DD-<topic>.md |
docs/ai/ | 既有 AI 協作指南與 agent-facing 文件 | <topic>.md |
docs/superpowers/specs/ | 已確認或待確認的設計規格；proposal 不得自動視為 implementation source of truth | YYYY-MM-DD-<topic>-design.md |
docs/superpowers/plans/ | 實作前計畫與完成後的執行紀錄 | YYYY-MM-DD-<feature>.md |
plans/ | repo 既有工作計畫或執行紀錄 | <feature-slug>.md |
Root source of truth
| 文件 | 定位 |
|---|---|
| architecture.md | 系統整體架構與主要資料流 |
| auth-architecture.md | Auth 現況與 migration guardrails |
| backend-permissions.md | Backend role / permission 現況與變更 guardrails |
| auto-merge-policy.md | Auto-merge 與 approve 語義 |
| dependabot-update-policy.md | Dependabot 更新政策 |
| draft-pr-auto-ready.md | Draft PR auto-ready 現行流程 |
| pr-scope-policy.md | PR scope 與 required checks policy |
| sequence-diagram.md | Watch / points / dashboard 主要時序圖 |
| tokenomics.md | $TACHI 平台幣經濟模型 |
| uuid-v7.md | UUID 版本策略 |
| watch-to-points-design.md | Watch-to-points 已完成設計 |
Active plans / proposals
| 文件 | 定位 |
|---|---|
| atlas-migration-plan.md | #463 Atlas migration 拆分實作計畫；不得單獨視為已完成狀態 |
| atlas-schema-reconciliation.md | #463 baseline 前 schema reconciliation evidence / procedure |
| non-web3-launch-readiness.md | 暫時捨棄 Web3 上鏈部分後的上線距離、Codex 自動化能力與真人介入層級 snapshot |
| openapi-codegen-flow.md | #401 OpenAPI → TypeScript contracts / codegen rollout 計畫 |
| tachigo Dev Portal spec | #674 Dev Portal 設計規格；命名已避開 atlasgo tooling 混淆 |
Root reference / discussion notes
| 文件 | 定位 |
|---|---|
| extension-ui-prompts.md | Tachimint UI prompt reference，不是產品 runtime source of truth |
| feature-discussion.md | 早期產品討論紀錄；仍保留供背景參考，不得單獨視為 implementation source of truth |
| tachimint-loyalty-claim-boundary.md | Tachimint / claim flow 邊界討論短文件，不是正式 architecture source of truth |
Dev Portal operations
| 文件 | 定位 |
|---|---|
| deployment.md | Cloudflare Pages 手動連 repo、branch deploy / PR preview、公開 URL 驗證與 rollback/readback checklist |
Code source map
| Area | Source |
|---|---|
| API bootstrap / router | cmd/server, internal/router/router.go |
| API handlers | services/api/internal/handlers |
| API services | services/api/internal/services |
| API models / migrations | services/api/internal/models, services/api/migrations |
| Extension app | apps/extension/src |
| Dashboard app | apps/dashboard/src |
| Shared generated types | packages/shared-types |
| API client package | packages/api-client |
| Docs portal | apps/docs, docs/dev-portal |
Naming rules
- 目前仍是 source of truth 的文件不加日期，例如
architecture.md、tokenomics.md。 - 歷史紀錄與決策紀錄使用日期開頭，例如
2026-04-30-monorepo-directory-refactor.md。 - Proposal 不能在未採納前寫成完成狀態；Dev Portal 只連到它，並標註狀態。
- 可見名稱、sidebar label、slug 與目錄使用
tachigo Dev Portal/Dev Portal，不要把導覽網站命名成 Atlas，以免和 atlasgo migration tooling 混淆。