Skip to content

Commit a2e8e82

Browse files
xiaojiou176xiaojiou176
committed
docs: public docs surface
Public-facing documentation, ledgers, and proof surfaces. File groups in this commit: - docs/
1 parent eead3f6 commit a2e8e82

38 files changed

Lines changed: 2988 additions & 299 deletions

‎.gitignore‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,3 +73,13 @@ docs/_archive/我和ChatGPT的完整对话.md
7373
*.dylib
7474
*.dll
7575
*.pyd
76+
77+
# Codex / Kiro / Claude rollout JSONL — 这类文件会包含 token / secret，永远不能 commit
78+
.archive/sessions/
79+
.archive/**/sessions/
80+
.archive/**/*.jsonl
81+
.codex/sessions/
82+
.kiro/sessions/
83+
.claude/sessions/
84+
**/rollout-*.jsonl
85+
**/session-*.jsonl

‎.gitleaks.toml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
title = "repo gitleaks config"
2+
3+
[extend]
4+
useDefault = true
5+
6+
[allowlist]
7+
description = "Don't trip on rendered hash files or repo-internal lockfiles"
8+
paths = [
9+
'''docs/_generated/render_state\.json''',
10+
'''.*\.lock$''',
11+
'''package-lock\.json$''',
12+
'''pnpm-lock\.yaml$''',
13+
'''uv\.lock$''',
14+
'''Cargo\.lock$''',
15+
'''.*\.snap$''',
16+
]

‎README.md‎

Lines changed: 83 additions & 299 deletions
Large diffs are not rendered by default.

‎docs/AGENTS.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# AGENTS.md (docs)
2+
3+
Local policy for `docs/`.
4+
5+
## Goal
6+
7+
Keep repository documentation executable, minimal, and aligned with current behavior.
8+
9+
## Rules
10+
11+
- Documentation must stay in sync with code and gates.
12+
- Prefer updating existing sections over adding parallel narratives.
13+
- Keep the public docs surface thin.
14+
- Do not reintroduce heavy internal-only documentation into the public route.
15+
16+
## Navigation
17+
18+
- Architecture: `architecture.md`
19+
- Usage: `usage.md`
20+
- Open-source boundary: `open_source_runbook.md`
21+
- Logging policy: `logging_observability.md`
22+
- Generated references: `reference/*.generated.md`
23+
24+
## Verification
25+
26+
```bash
27+
python3 tooling/docs/render_docs.py --check
28+
bash tooling/docs/docs_smoke.sh --install-smoke
29+
```

‎docs/CLAUDE.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# CLAUDE.md (docs)
2+
3+
Quick execution memory for `docs/`.
4+
5+
## Focus
6+
7+
- Keep docs aligned with executable truth
8+
- Preserve a thin public route
9+
- Regenerate render-managed surfaces after doc contract changes
10+
11+
## Main files
12+
13+
- `docs/usage.md`
14+
- `docs/architecture.md`
15+
- `docs/open_source_runbook.md`
16+
- `docs/logging_observability.md`
17+
18+
## Main checks
19+
20+
```bash
21+
python3 tooling/docs/render_docs.py --check
22+
bash tooling/docs/docs_smoke.sh --install-smoke
23+
```

‎docs/_config.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
title: Fileyard | Review-first file organization docs
2+
description: See how Fileyard turns messy folders into reviewed manifests, dry-run plans, and rollback-ready file actions.

‎docs/_generated/render_state.json‎

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
{
2+
"generator": "tooling/docs/render_docs.py@1",
3+
"renders": [
4+
{
5+
"id": "env-contract-reference",
6+
"kind": "file",
7+
"renderer": "env-contract-reference",
8+
"output_path": "docs/reference/env_contract.generated.md",
9+
"block_id": null,
10+
"source_hashes": {
11+
"contracts/runtime/env_contract_registry.yaml": "c2cc78fda018fed4f7e7bdda4aff42634e19e2f54ab6f9d4abd8334d413b89e3"
12+
},
13+
"output_hash": "bb34dd6f5edb4abe14ada1fcfc414a26c10c6ee7a24a9cb7bf5b96df019f9e16"
14+
},
15+
{
16+
"id": "required-checks-matrix",
17+
"kind": "file",
18+
"renderer": "required-checks-matrix",
19+
"output_path": "docs/required_checks_matrix.md",
20+
"block_id": null,
21+
"source_hashes": {
22+
".github/workflows/ci.yml": "ca9aba257f6ca2e4e38feef96767e43f47198ad00e09e7e65b637fda95faa6f5",
23+
"contracts/governance/required_checks_policy.yaml": "51f9e8cb17df93c3912ae719a6ba95b74f2c666b6b11c79e1728f7002fb3e3b3"
24+
},
25+
"output_hash": "76db4927da6c20357d86b7b0d5f9efbcd12120beeb75a5bfc5c18468624f1e49"
26+
},
27+
{
28+
"id": "web-api-reference",
29+
"kind": "file",
30+
"renderer": "web-api-reference",
31+
"output_path": "docs/reference/web_api_routes.generated.md",
32+
"block_id": null,
33+
"source_hashes": {
34+
"contracts/api/web_api.openapi.yaml": "c97830844b65fd8f76cd23688187ca8648835d787d1819045882dea01e1d7b64"
35+
},
36+
"output_hash": "2bba2f20891f2bdb3b03c33f824ceba8afd2973c3a8a5946b8cc5c4533809b0c"
37+
},
38+
{
39+
"id": "runtime-topology-reference",
40+
"kind": "file",
41+
"renderer": "runtime-topology-reference",
42+
"output_path": "docs/reference/runtime_topology.generated.md",
43+
"block_id": null,
44+
"source_hashes": {
45+
"ops/compose/docker-compose.yml": "9f3f0a6047c30cc93374b41a2b0acbf5563b5b461812efac90e4e6e9da9a693c",
46+
"contracts/governance/governance.defaults.env": "cddb6b33f746b32509f8a49af1f11bef945d0eeaf060028da41c726127d68660",
47+
"pyproject.toml": "d12c2c415c3900d81c888e91d3a8ec1af88af96a701c6de801c37a1e52b4a495",
48+
"package.json": "4b9bfb8aac66c5c9101b56af866932d5a27a2b1b912b01439905155a09cd6827",
49+
".env.example": "32a60792624cd36eb5992b34d9c67c6e6e2a0971a45f3a48370f3b0b720b0aa8"
50+
},
51+
"output_hash": "35f928f34d5157b2764465e28ea00c4e234354342d4d26cc1164f9231eebf20d"
52+
},
53+
{
54+
"id": "governance-truth-reference",
55+
"kind": "file",
56+
"renderer": "governance-truth-reference",
57+
"output_path": "docs/reference/governance_truth.generated.md",
58+
"block_id": null,
59+
"source_hashes": {
60+
"contracts/governance/done_signal_policy.yaml": "16e2fc2add45a68406d6a6077ed7b912fe2406905bf1ff68e967bceeda4bd83c",
61+
"contracts/governance/public_readiness_policy.yaml": "fc5821ecc62249926ee5e282d114b63eb844d39e4ec408f8673a7bc162d5ad39",
62+
"contracts/governance/required_checks_policy.yaml": "51f9e8cb17df93c3912ae719a6ba95b74f2c666b6b11c79e1728f7002fb3e3b3",
63+
".github/workflows/ci.yml": "ca9aba257f6ca2e4e38feef96767e43f47198ad00e09e7e65b637fda95faa6f5",
64+
".github/workflows/pre-commit.yml": "ed0082256d36108f1bdb3d6c66f6f9805295a4f7f738465b0092d0b3fe0199ed",
65+
".github/workflows/live-integration.yml": "87a1d413bc8d92d2103b5d4a6e19cfcb85fdb30e9e753b88a3267607a41d2b92",
66+
".github/workflows/mutation-manual.yml": "c892aa745b913f37a4662e51ecf0c2013dc32faecd1c97d4a59f2d1e808fb101"
67+
},
68+
"output_hash": "fa8b6fe93898b373d52e412d172e93daf7ff7ed50e4b3f29c0c89bb65b6de0c4"
69+
},
70+
{
71+
"id": "root-web-api-routes",
72+
"kind": "fragment",
73+
"renderer": "readme-web-api-summary",
74+
"output_path": "README.md",
75+
"block_id": "root-web-api-routes",
76+
"source_hashes": {
77+
"contracts/api/web_api.openapi.yaml": "c97830844b65fd8f76cd23688187ca8648835d787d1819045882dea01e1d7b64"
78+
},
79+
"output_hash": "52a2f027fcd3223d465bdebc88a4dbe70231040cf05ade1c9d53a0f45caedfde"
80+
},
81+
{
82+
"id": "root-runtime-topology",
83+
"kind": "fragment",
84+
"renderer": "root-runtime-topology-summary",
85+
"output_path": "README.md",
86+
"block_id": "root-runtime-topology",
87+
"source_hashes": {
88+
"ops/compose/docker-compose.yml": "9f3f0a6047c30cc93374b41a2b0acbf5563b5b461812efac90e4e6e9da9a693c",
89+
"contracts/governance/governance.defaults.env": "cddb6b33f746b32509f8a49af1f11bef945d0eeaf060028da41c726127d68660",
90+
"pyproject.toml": "d12c2c415c3900d81c888e91d3a8ec1af88af96a701c6de801c37a1e52b4a495",
91+
"package.json": "4b9bfb8aac66c5c9101b56af866932d5a27a2b1b912b01439905155a09cd6827",
92+
".env.example": "32a60792624cd36eb5992b34d9c67c6e6e2a0971a45f3a48370f3b0b720b0aa8"
93+
},
94+
"output_hash": "52a2f027fcd3223d465bdebc88a4dbe70231040cf05ade1c9d53a0f45caedfde"
95+
},
96+
{
97+
"id": "root-ci-governance-summary",
98+
"kind": "fragment",
99+
"renderer": "root-ci-governance-summary",
100+
"output_path": "README.md",
101+
"block_id": "root-ci-governance-summary",
102+
"source_hashes": {
103+
".github/workflows/ci.yml": "ca9aba257f6ca2e4e38feef96767e43f47198ad00e09e7e65b637fda95faa6f5",
104+
".github/workflows/reusable-build-runtime-image.yml": "0b79722ad922ec45ce8eb62c2466834855aebb9915f86a8ff65a25b71ebf5793",
105+
".github/workflows/nightly-drift-audit.yml": "485f3ee338c8c951e92047ff1bf600379eebb8a3265c1ded542bd95caad7770c",
106+
"contracts/governance/required_checks_policy.yaml": "51f9e8cb17df93c3912ae719a6ba95b74f2c666b6b11c79e1728f7002fb3e3b3",
107+
"package.json": "4b9bfb8aac66c5c9101b56af866932d5a27a2b1b912b01439905155a09cd6827"
108+
},
109+
"output_hash": "52a2f027fcd3223d465bdebc88a4dbe70231040cf05ade1c9d53a0f45caedfde"
110+
},
111+
{
112+
"id": "root-release-identity",
113+
"kind": "fragment",
114+
"renderer": "root-release-identity-summary",
115+
"output_path": "README.md",
116+
"block_id": "root-release-identity",
117+
"source_hashes": {
118+
"pyproject.toml": "d12c2c415c3900d81c888e91d3a8ec1af88af96a701c6de801c37a1e52b4a495"
119+
},
120+
"output_hash": "52a2f027fcd3223d465bdebc88a4dbe70231040cf05ade1c9d53a0f45caedfde"
121+
},
122+
{
123+
"id": "script-readme-web-api-routes",
124+
"kind": "fragment",
125+
"renderer": "script-readme-web-api-summary",
126+
"output_path": "docs/usage.md",
127+
"block_id": "script-readme-web-api-routes",
128+
"source_hashes": {
129+
"contracts/api/web_api.openapi.yaml": "c97830844b65fd8f76cd23688187ca8648835d787d1819045882dea01e1d7b64"
130+
},
131+
"output_hash": "4203a15a1ce623a972a6ba31f6a28f55eaa4520db960e7529b165e1bb550e2b3"
132+
},
133+
{
134+
"id": "script-readme-runtime-topology",
135+
"kind": "fragment",
136+
"renderer": "script-readme-runtime-topology-summary",
137+
"output_path": "docs/usage.md",
138+
"block_id": "script-readme-runtime-topology",
139+
"source_hashes": {
140+
"ops/compose/docker-compose.yml": "9f3f0a6047c30cc93374b41a2b0acbf5563b5b461812efac90e4e6e9da9a693c",
141+
"contracts/governance/governance.defaults.env": "cddb6b33f746b32509f8a49af1f11bef945d0eeaf060028da41c726127d68660",
142+
"pyproject.toml": "d12c2c415c3900d81c888e91d3a8ec1af88af96a701c6de801c37a1e52b4a495",
143+
"package.json": "4b9bfb8aac66c5c9101b56af866932d5a27a2b1b912b01439905155a09cd6827",
144+
".env.example": "32a60792624cd36eb5992b34d9c67c6e6e2a0971a45f3a48370f3b0b720b0aa8"
145+
},
146+
"output_hash": "4203a15a1ce623a972a6ba31f6a28f55eaa4520db960e7529b165e1bb550e2b3"
147+
},
148+
{
149+
"id": "script-readme-ci-governance-summary",
150+
"kind": "fragment",
151+
"renderer": "script-readme-ci-governance-summary",
152+
"output_path": "docs/usage.md",
153+
"block_id": "script-readme-ci-governance-summary",
154+
"source_hashes": {
155+
".github/workflows/ci.yml": "ca9aba257f6ca2e4e38feef96767e43f47198ad00e09e7e65b637fda95faa6f5",
156+
".github/workflows/reusable-build-runtime-image.yml": "0b79722ad922ec45ce8eb62c2466834855aebb9915f86a8ff65a25b71ebf5793",
157+
".github/workflows/nightly-drift-audit.yml": "485f3ee338c8c951e92047ff1bf600379eebb8a3265c1ded542bd95caad7770c",
158+
"contracts/governance/required_checks_policy.yaml": "51f9e8cb17df93c3912ae719a6ba95b74f2c666b6b11c79e1728f7002fb3e3b3",
159+
"package.json": "4b9bfb8aac66c5c9101b56af866932d5a27a2b1b912b01439905155a09cd6827"
160+
},
161+
"output_hash": "4203a15a1ce623a972a6ba31f6a28f55eaa4520db960e7529b165e1bb550e2b3"
162+
},
163+
{
164+
"id": "script-readme-release-identity",
165+
"kind": "fragment",
166+
"renderer": "script-readme-release-identity-summary",
167+
"output_path": "docs/usage.md",
168+
"block_id": "script-readme-release-identity",
169+
"source_hashes": {
170+
"pyproject.toml": "d12c2c415c3900d81c888e91d3a8ec1af88af96a701c6de801c37a1e52b4a495"
171+
},
172+
"output_hash": "4203a15a1ce623a972a6ba31f6a28f55eaa4520db960e7529b165e1bb550e2b3"
173+
},
174+
{
175+
"id": "script-readme-governance-truth",
176+
"kind": "fragment",
177+
"renderer": "script-readme-governance-truth-summary",
178+
"output_path": "docs/usage.md",
179+
"block_id": "script-readme-governance-truth",
180+
"source_hashes": {
181+
"contracts/governance/done_signal_policy.yaml": "16e2fc2add45a68406d6a6077ed7b912fe2406905bf1ff68e967bceeda4bd83c",
182+
"contracts/governance/public_readiness_policy.yaml": "fc5821ecc62249926ee5e282d114b63eb844d39e4ec408f8673a7bc162d5ad39",
183+
"contracts/governance/required_checks_policy.yaml": "51f9e8cb17df93c3912ae719a6ba95b74f2c666b6b11c79e1728f7002fb3e3b3",
184+
".github/workflows/ci.yml": "ca9aba257f6ca2e4e38feef96767e43f47198ad00e09e7e65b637fda95faa6f5",
185+
".github/workflows/pre-commit.yml": "ed0082256d36108f1bdb3d6c66f6f9805295a4f7f738465b0092d0b3fe0199ed",
186+
".github/workflows/live-integration.yml": "87a1d413bc8d92d2103b5d4a6e19cfcb85fdb30e9e753b88a3267607a41d2b92",
187+
".github/workflows/mutation-manual.yml": "c892aa745b913f37a4662e51ecf0c2013dc32faecd1c97d4a59f2d1e808fb101"
188+
},
189+
"output_hash": "4203a15a1ce623a972a6ba31f6a28f55eaa4520db960e7529b165e1bb550e2b3"
190+
},
191+
{
192+
"id": "architecture-web-api-summary",
193+
"kind": "fragment",
194+
"renderer": "architecture-web-api-summary",
195+
"output_path": "docs/architecture.md",
196+
"block_id": "architecture-web-api-summary",
197+
"source_hashes": {
198+
"contracts/api/web_api.openapi.yaml": "c97830844b65fd8f76cd23688187ca8648835d787d1819045882dea01e1d7b64"
199+
},
200+
"output_hash": "c0cb776be4feeaa4d6517d934e2d4f541ae1a04d66350c7bd82da6b009f710b4"
201+
},
202+
{
203+
"id": "architecture-runtime-topology",
204+
"kind": "fragment",
205+
"renderer": "architecture-runtime-topology-summary",
206+
"output_path": "docs/architecture.md",
207+
"block_id": "architecture-runtime-topology",
208+
"source_hashes": {
209+
"ops/compose/docker-compose.yml": "9f3f0a6047c30cc93374b41a2b0acbf5563b5b461812efac90e4e6e9da9a693c",
210+
"contracts/governance/governance.defaults.env": "cddb6b33f746b32509f8a49af1f11bef945d0eeaf060028da41c726127d68660",
211+
"pyproject.toml": "d12c2c415c3900d81c888e91d3a8ec1af88af96a701c6de801c37a1e52b4a495",
212+
"package.json": "4b9bfb8aac66c5c9101b56af866932d5a27a2b1b912b01439905155a09cd6827",
213+
".env.example": "32a60792624cd36eb5992b34d9c67c6e6e2a0971a45f3a48370f3b0b720b0aa8"
214+
},
215+
"output_hash": "c0cb776be4feeaa4d6517d934e2d4f541ae1a04d66350c7bd82da6b009f710b4"
216+
},
217+
{
218+
"id": "architecture-governance-truth",
219+
"kind": "fragment",
220+
"renderer": "architecture-governance-truth-summary",
221+
"output_path": "docs/architecture.md",
222+
"block_id": "architecture-governance-truth",
223+
"source_hashes": {
224+
"contracts/governance/done_signal_policy.yaml": "16e2fc2add45a68406d6a6077ed7b912fe2406905bf1ff68e967bceeda4bd83c",
225+
"contracts/governance/public_readiness_policy.yaml": "fc5821ecc62249926ee5e282d114b63eb844d39e4ec408f8673a7bc162d5ad39",
226+
"contracts/governance/required_checks_policy.yaml": "51f9e8cb17df93c3912ae719a6ba95b74f2c666b6b11c79e1728f7002fb3e3b3",
227+
".github/workflows/ci.yml": "ca9aba257f6ca2e4e38feef96767e43f47198ad00e09e7e65b637fda95faa6f5",
228+
".github/workflows/pre-commit.yml": "ed0082256d36108f1bdb3d6c66f6f9805295a4f7f738465b0092d0b3fe0199ed",
229+
".github/workflows/live-integration.yml": "87a1d413bc8d92d2103b5d4a6e19cfcb85fdb30e9e753b88a3267607a41d2b92",
230+
".github/workflows/mutation-manual.yml": "c892aa745b913f37a4662e51ecf0c2013dc32faecd1c97d4a59f2d1e808fb101"
231+
},
232+
"output_hash": "c0cb776be4feeaa4d6517d934e2d4f541ae1a04d66350c7bd82da6b009f710b4"
233+
},
234+
{
235+
"id": "open-source-platform-truth",
236+
"kind": "fragment",
237+
"renderer": "open-source-platform-truth-summary",
238+
"output_path": "docs/open_source_runbook.md",
239+
"block_id": "open-source-platform-truth",
240+
"source_hashes": {
241+
"contracts/governance/done_signal_policy.yaml": "16e2fc2add45a68406d6a6077ed7b912fe2406905bf1ff68e967bceeda4bd83c",
242+
"contracts/governance/public_readiness_policy.yaml": "fc5821ecc62249926ee5e282d114b63eb844d39e4ec408f8673a7bc162d5ad39",
243+
"contracts/governance/required_checks_policy.yaml": "51f9e8cb17df93c3912ae719a6ba95b74f2c666b6b11c79e1728f7002fb3e3b3",
244+
".github/workflows/ci.yml": "ca9aba257f6ca2e4e38feef96767e43f47198ad00e09e7e65b637fda95faa6f5",
245+
".github/workflows/pre-commit.yml": "ed0082256d36108f1bdb3d6c66f6f9805295a4f7f738465b0092d0b3fe0199ed",
246+
".github/workflows/live-integration.yml": "87a1d413bc8d92d2103b5d4a6e19cfcb85fdb30e9e753b88a3267607a41d2b92",
247+
".github/workflows/mutation-manual.yml": "c892aa745b913f37a4662e51ecf0c2013dc32faecd1c97d4a59f2d1e808fb101"
248+
},
249+
"output_hash": "590a2ddf45c93e4e0639c4c4a077e725da6fb8c107a7567d7edb484e714a5b2b"
250+
},
251+
{
252+
"id": "runner-contract-governance-truth",
253+
"kind": "fragment",
254+
"renderer": "runner-contract-governance-truth-summary",
255+
"output_path": "docs/runner_contract.md",
256+
"block_id": "runner-contract-governance-truth",
257+
"source_hashes": {
258+
"contracts/governance/required_checks_policy.yaml": "51f9e8cb17df93c3912ae719a6ba95b74f2c666b6b11c79e1728f7002fb3e3b3",
259+
".github/workflows/ci.yml": "ca9aba257f6ca2e4e38feef96767e43f47198ad00e09e7e65b637fda95faa6f5",
260+
".github/workflows/pre-commit.yml": "ed0082256d36108f1bdb3d6c66f6f9805295a4f7f738465b0092d0b3fe0199ed",
261+
".github/workflows/live-integration.yml": "87a1d413bc8d92d2103b5d4a6e19cfcb85fdb30e9e753b88a3267607a41d2b92",
262+
".github/workflows/mutation-manual.yml": "c892aa745b913f37a4662e51ecf0c2013dc32faecd1c97d4a59f2d1e808fb101"
263+
},
264+
"output_hash": "633b230e1dba7628f622a01d8a4ed273844a38bd15e88124a914ea2e500d2edc"
265+
},
266+
{
267+
"id": "webui-api-contract",
268+
"kind": "fragment",
269+
"renderer": "webui-api-contract",
270+
"output_path": "apps/webui/README.md",
271+
"block_id": "webui-api-contract",
272+
"source_hashes": {
273+
"contracts/api/web_api.openapi.yaml": "c97830844b65fd8f76cd23688187ca8648835d787d1819045882dea01e1d7b64"
274+
},
275+
"output_hash": "8bab781114a7fb0369ed066a739c365d7ba307491ca98c6aaeb95b16c0cf657a"
276+
}
277+
]
278+
}

0 commit comments

Comments
 (0)