# 文档与配置索引

遇到问题时的查阅顺序：先近后远——子项目本地文档优先于工作空间根文档。

## 事实来源（随代码更新）

| 主题 | 位置 |
|---|---|
| 工作空间总览 / agent 规则 | `AGENTS.md`（工作空间根） |
| site-deploy 硬性规则 | `site-deploy/AGENTS.md` |
| 部署操作手册 | `site-deploy/docs/runbook.md` |
| AI 辅助部署工作流 | `site-deploy/docs/ai-workflow.md` |
| **OIDC/PKCE 统一接入指南** | `site-deploy/docs/oauth-integration.md` |
| 各服务部署指令 | `site-deploy/playbooks/<service>.md`（`casdoor`、`auth-proxy`） |
| 鸿蒙应用 portfolio | `oh/README.md` |
| instandhalterin 用法 | `instandhalterin/README.md` |
| Casdoor 部署与 bootstrap | `repos/yaogal/docker-images/casdoor/`（compose + `init/init.sh`） |
| SPA 接 Casdoor 参考 | `repos/yaogal/account-site/README.md` + `scripts/inject-config.mjs` |

## 配置文件（真实值不入库）

| 文件 | 说明 |
|---|---|
| `site-deploy/config/hosts.env` | 部署主机（gitignored；从 `.example` 复制） |
| `site-deploy/config/services.yaml` | 服务定义（从 `.example` 复制） |
| `instandhalterin/ubuntu/config.sh` | 引导配置（gitignored；`configstrap.sh` 生成） |
| `docker-images/casdoor/.env` | Casdoor 生产变量（从 `.env.example` 复制） |

## 本文档站自身

- 源文件：`project-docs/docs/source/`（MyST Markdown；章节编号 00/10/20 步进）
- 写作与构建指南：[](../editing/index)
- 构建脚本：`bin/live-docs.sh`（预览）、`bin/build-docs.sh <name> [user@host]`
  （构建 + 归档 + 可选部署到 `/opt/www/docs/`）