feat(numbering): publish canonical numbering API

Add a public numbering module and route fragmenting, validation,
and scaffold preparation through the canonical numbering entry.

Rewrite the repository entry docs around the fixed numbering
contract, add MkDocs landing pages, and document the mirror
mapping used for medicinal-chemistry comparisons.

Also refresh the validation analysis reports to explain the
canonical-versus-mirrored numbering relationship.

docs/user-guide/index.md

@@ -0,0 +1,17 @@
+# 用户指南
+
+这里收的是稳定规则，不放临时笔记。
+
+## 你最可能要看的内容
+
+- [环编号系统](ring-numbering.md)
+
+## 这个目录的边界
+
+- 这里只描述公开、可复用、会长期维持的行为。
+- 所有编号说明都以 canonical numbering 为准。
+- 如果文献图里用的是反向标注，先把它转换成镜像映射，再和代码结果对照。
+
+## 一句话约定
+
+这套工具没有 `clockwise` / `anticlockwise` 开关，编号方向不靠参数切换。

docs/user-guide/ring-numbering.md

@@ -0,0 +1,55 @@
+# 环编号系统
+
+本项目只采用一套 canonical numbering。它是确定性的，不依赖 `clockwise` / `anticlockwise` 参数，也不是视觉上的方向切换。
+
+## 规则
+
+- `1 = 内酯羰基碳`
+- `2 = 相邻酯氧`
+- `3..N = 从 2 位出发沿环唯一图遍历顺序继续编号`
+
+这条规则在代码、文档、测试和验证输出中都保持一致。
+
+## 16 元环镜像映射
+
+当你需要把代码里的 canonical numbering 转成文献里常见的反向标注时，使用：
+
+```text
+p_mirror = ring_size - p + 3
+```
+
+对 16 元环，这会得到：
+
+- `3 → 16`
+- `4 → 15`
+- `5 → 14`
+- `6 → 13`
+- `7 → 12`
+- `8 → 11`
+- `9 → 10`
+- `10 → 9`
+- `11 → 8`
+- `12 → 7`
+- `13 → 6`
+- `14 → 5`
+- `15 → 4`
+- `16 → 3`
+
+常见对照点：
+
+- `6 → 13`
+- `7 → 12`
+- `15 → 4`
+- `16 → 3`
+
+## 使用建议
+
+- 先在代码和数据库里保留 canonical numbering。
+- 只在图注、论文、汇报里按需要加镜像标签。
+- 不要把方向差异实现成 API 参数。
+- 如果分子是 bridge / fused multi-anchor，先把结构语义说明清楚，再讨论编号可视化。
+
+## 最短结论
+
+如果你在看代码，记 canonical numbering。
+如果你在对照文献，记 `p_mirror = ring_size - p + 3`。