@brucewaynedecoy/make-docs 1.0.0-rc.1 → 2.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (187) hide show
  1. package/LICENSE +21 -201
  2. package/README.md +36 -27
  3. package/dist/backup-73HQNKMC.js +20 -0
  4. package/dist/backup-73HQNKMC.js.map +1 -0
  5. package/dist/chunk-3BAJQXGH.js +1575 -0
  6. package/dist/chunk-3BAJQXGH.js.map +1 -0
  7. package/dist/chunk-64CTKJO7.js +4136 -0
  8. package/dist/chunk-64CTKJO7.js.map +1 -0
  9. package/dist/chunk-BENO4IH5.js +875 -0
  10. package/dist/chunk-BENO4IH5.js.map +1 -0
  11. package/dist/chunk-D4HDZEJT.js +37 -0
  12. package/dist/chunk-D4HDZEJT.js.map +1 -0
  13. package/dist/chunk-G5EF63GG.js +1291 -0
  14. package/dist/chunk-G5EF63GG.js.map +1 -0
  15. package/dist/chunk-GNP6HRVP.js +523 -0
  16. package/dist/chunk-GNP6HRVP.js.map +1 -0
  17. package/dist/chunk-HJYIQTMD.js +204 -0
  18. package/dist/chunk-HJYIQTMD.js.map +1 -0
  19. package/dist/chunk-LQ5NSWCJ.js +39 -0
  20. package/dist/chunk-LQ5NSWCJ.js.map +1 -0
  21. package/dist/chunk-LRVV7UDD.js +2340 -0
  22. package/dist/chunk-LRVV7UDD.js.map +1 -0
  23. package/dist/chunk-LVQSJF63.js +24674 -0
  24. package/dist/chunk-LVQSJF63.js.map +1 -0
  25. package/dist/chunk-MXBHCHSM.js +13995 -0
  26. package/dist/chunk-MXBHCHSM.js.map +1 -0
  27. package/dist/chunk-Z5K4FHYP.js +922 -0
  28. package/dist/chunk-Z5K4FHYP.js.map +1 -0
  29. package/dist/index.js +3798 -250
  30. package/dist/index.js.map +1 -1
  31. package/dist/self-YYXOLDKU.js +653 -0
  32. package/dist/self-YYXOLDKU.js.map +1 -0
  33. package/dist/server-O2ZELIMX.js +512 -0
  34. package/dist/server-O2ZELIMX.js.map +1 -0
  35. package/dist/setup-system-HZROFNMP.js +544 -0
  36. package/dist/setup-system-HZROFNMP.js.map +1 -0
  37. package/dist/{skills-command-3ESCZ75U.js → skills-command-MGGHY7HU.js} +190 -32
  38. package/dist/skills-command-MGGHY7HU.js.map +1 -0
  39. package/dist/uninstall-3UXXXNFO.js +223 -0
  40. package/dist/uninstall-3UXXXNFO.js.map +1 -0
  41. package/dist/virtual_make-docs-first-party-skills-ZII74YOB.js +11 -0
  42. package/dist/virtual_make-docs-first-party-skills-ZII74YOB.js.map +1 -0
  43. package/package.json +9 -6
  44. package/skill-registry.json +328 -125
  45. package/skill-registry.schema.json +221 -45
  46. package/template/.make-docs/AGENTS.md +18 -0
  47. package/template/.make-docs/CLAUDE.md +18 -0
  48. package/template/.make-docs/archive/AGENTS.md +11 -0
  49. package/template/.make-docs/archive/CLAUDE.md +11 -0
  50. package/template/.make-docs/system/AGENTS.md +12 -0
  51. package/template/.make-docs/system/CLAUDE.md +12 -0
  52. package/template/.make-docs/system/contracts/AGENTS.md +13 -0
  53. package/template/.make-docs/system/contracts/CLAUDE.md +13 -0
  54. package/template/{docs/assets/references → .make-docs/system/contracts}/commit-message-convention.md +4 -4
  55. package/template/.make-docs/system/contracts/coverage-pass-contract.md +198 -0
  56. package/template/.make-docs/system/contracts/deferred-obligation-contract.md +128 -0
  57. package/template/{docs/assets/references → .make-docs/system/contracts}/design-contract.md +7 -2
  58. package/template/{docs/assets/references → .make-docs/system/contracts}/guide-contract.md +21 -19
  59. package/template/{docs/assets/references → .make-docs/system/contracts}/history-record-contract.md +17 -11
  60. package/template/.make-docs/system/contracts/human-experience-contract.md +134 -0
  61. package/template/.make-docs/system/contracts/naive-uat-contract.md +231 -0
  62. package/template/.make-docs/system/contracts/output-contract.md +277 -0
  63. package/template/.make-docs/system/contracts/performance-evidence-governance.md +257 -0
  64. package/template/.make-docs/system/contracts/system-resource-contract.md +93 -0
  65. package/template/.make-docs/system/prompts/AGENTS.md +12 -0
  66. package/template/.make-docs/system/prompts/CLAUDE.md +12 -0
  67. package/template/.make-docs/system/prompts/coverage-pass-maintainer-guide.prompt.md +20 -0
  68. package/template/.make-docs/system/prompts/coverage-pass-prd-reconciliation.prompt.md +18 -0
  69. package/template/.make-docs/system/prompts/coverage-pass-testing-uat.prompt.md +46 -0
  70. package/template/.make-docs/system/prompts/coverage-pass-user-guide.prompt.md +20 -0
  71. package/template/.make-docs/system/prompts/designs-to-plan-change.prompt.md +18 -0
  72. package/template/.make-docs/system/prompts/designs-to-plan.prompt.md +14 -0
  73. package/template/.make-docs/system/prompts/docs-path-hygiene-cleanup.prompt.md +29 -0
  74. package/template/.make-docs/system/prompts/naive-uat-facilitator.prompt.md +28 -0
  75. package/template/.make-docs/system/prompts/naive-uat-tester.prompt.md +20 -0
  76. package/template/.make-docs/system/prompts/performance-coverage.prompt.md +63 -0
  77. package/template/.make-docs/system/prompts/plan-to-prd-change.prompt.md +12 -0
  78. package/template/.make-docs/system/prompts/plan-to-prd-green-field.prompt.md +10 -0
  79. package/template/.make-docs/system/prompts/prd-change-to-work.prompt.md +14 -0
  80. package/template/.make-docs/system/prompts/prd-to-work-full-prd.prompt.md +10 -0
  81. package/template/.make-docs/system/prompts/prd-to-work-prd-feature.prompt.md +10 -0
  82. package/template/.make-docs/system/prompts/request-to-design.prompt.md +20 -0
  83. package/template/.make-docs/system/prompts/session-to-history-record.prompt.md +23 -0
  84. package/template/{docs/assets → .make-docs/system}/prompts/work-to-commit-message.prompt.md +2 -2
  85. package/template/.make-docs/system/prompts/work-to-guides.prompt.md +22 -0
  86. package/template/.make-docs/system/references/AGENTS.md +14 -0
  87. package/template/.make-docs/system/references/CLAUDE.md +14 -0
  88. package/template/{docs/assets → .make-docs/system}/references/design-workflow.md +15 -2
  89. package/template/.make-docs/system/references/execution-workflow.md +189 -0
  90. package/template/.make-docs/system/references/human-experience.md +138 -0
  91. package/template/.make-docs/system/references/lifecycle.md +153 -0
  92. package/template/.make-docs/system/references/naive-uat-validation.md +65 -0
  93. package/template/.make-docs/system/references/naive-uat-workflow.md +64 -0
  94. package/template/.make-docs/system/references/path-and-link-hygiene.md +101 -0
  95. package/template/.make-docs/system/references/performance-evidence.md +114 -0
  96. package/template/.make-docs/system/references/planning-workflow.md +209 -0
  97. package/template/.make-docs/system/references/prd-change-management.md +165 -0
  98. package/template/{docs/assets → .make-docs/system}/references/wave-model.md +10 -8
  99. package/template/.make-docs/system/templates/AGENTS.md +12 -0
  100. package/template/.make-docs/system/templates/CLAUDE.md +12 -0
  101. package/template/.make-docs/system/templates/design.md +79 -0
  102. package/template/{docs/assets/templates/guide-developer.md → .make-docs/system/templates/guide-maintainer.md} +7 -3
  103. package/template/{docs/assets → .make-docs/system}/templates/guide-user.md +6 -2
  104. package/template/{docs/assets → .make-docs/system}/templates/history-record.md +6 -3
  105. package/template/.make-docs/system/templates/naive-uat-scenario.md +91 -0
  106. package/template/.make-docs/system/templates/performance-evidence-profile.md +252 -0
  107. package/template/.make-docs/system/templates/plan-overview.md +76 -0
  108. package/template/.make-docs/system/templates/plan-prd-change.md +155 -0
  109. package/template/{docs/assets → .make-docs/system}/templates/plan-prd-decompose.md +10 -0
  110. package/template/{docs/assets → .make-docs/system}/templates/plan-prd.md +28 -2
  111. package/template/{docs/assets → .make-docs/system}/templates/prd-architecture.md +13 -0
  112. package/template/.make-docs/system/templates/prd-glossary.md +28 -0
  113. package/template/.make-docs/system/templates/prd-index.md +70 -0
  114. package/template/{docs/assets → .make-docs/system}/templates/prd-overview.md +13 -0
  115. package/template/.make-docs/system/templates/prd-reference.md +30 -0
  116. package/template/{docs/assets → .make-docs/system}/templates/prd-risk-register.md +16 -1
  117. package/template/{docs/assets → .make-docs/system}/templates/prd-subsystem.md +15 -0
  118. package/template/.make-docs/system/templates/work-index.md +58 -0
  119. package/template/.make-docs/system/templates/work-phase.md +107 -0
  120. package/template/.make-docs/system-resources.catalog.json +91 -0
  121. package/template/.make-docs/system-resources.schema.json +204 -0
  122. package/template/AGENTS.md +8 -1
  123. package/template/CLAUDE.md +8 -1
  124. package/template/docs/AGENTS.codex-only.md +22 -0
  125. package/template/docs/AGENTS.md +21 -13
  126. package/template/docs/CLAUDE.claude-only.md +22 -0
  127. package/template/docs/CLAUDE.md +21 -13
  128. package/template/docs/assets/AGENTS.md +11 -7
  129. package/template/docs/assets/CLAUDE.md +11 -7
  130. package/template/docs/designs/AGENTS.md +8 -3
  131. package/template/docs/designs/CLAUDE.md +8 -3
  132. package/template/docs/plans/AGENTS.md +10 -3
  133. package/template/docs/plans/CLAUDE.md +10 -3
  134. package/template/docs/prd/AGENTS.md +14 -4
  135. package/template/docs/prd/CLAUDE.md +14 -4
  136. package/template/docs/work/AGENTS.md +10 -3
  137. package/template/docs/work/CLAUDE.md +10 -3
  138. package/dist/chunk-HP3HBG7F.js +0 -626
  139. package/dist/chunk-HP3HBG7F.js.map +0 -1
  140. package/dist/chunk-QRFH4J6H.js +0 -1194
  141. package/dist/chunk-QRFH4J6H.js.map +0 -1
  142. package/dist/chunk-WM3OXYTW.js +0 -2630
  143. package/dist/chunk-WM3OXYTW.js.map +0 -1
  144. package/dist/skills-command-3ESCZ75U.js.map +0 -1
  145. package/dist/uninstall-GQE4SJF2.js +0 -150
  146. package/dist/uninstall-GQE4SJF2.js.map +0 -1
  147. package/template/.make-docs/scripts/check_path_hygiene.py +0 -435
  148. package/template/docs/assets/archive/AGENTS.md +0 -20
  149. package/template/docs/assets/archive/CLAUDE.md +0 -20
  150. package/template/docs/assets/history/AGENTS.md +0 -12
  151. package/template/docs/assets/history/CLAUDE.md +0 -12
  152. package/template/docs/assets/prompts/AGENTS.md +0 -8
  153. package/template/docs/assets/prompts/CLAUDE.md +0 -8
  154. package/template/docs/assets/prompts/designs-to-plan-change.prompt.md +0 -14
  155. package/template/docs/assets/prompts/designs-to-plan.prompt.md +0 -10
  156. package/template/docs/assets/prompts/docs-path-hygiene-cleanup.prompt.md +0 -27
  157. package/template/docs/assets/prompts/plan-to-prd-change.prompt.md +0 -8
  158. package/template/docs/assets/prompts/plan-to-prd-green-field.prompt.md +0 -6
  159. package/template/docs/assets/prompts/prd-change-to-work.prompt.md +0 -10
  160. package/template/docs/assets/prompts/prd-to-work-full-prd.prompt.md +0 -6
  161. package/template/docs/assets/prompts/prd-to-work-prd-feature.prompt.md +0 -6
  162. package/template/docs/assets/prompts/request-to-design.prompt.md +0 -16
  163. package/template/docs/assets/prompts/session-to-history-record.prompt.md +0 -19
  164. package/template/docs/assets/prompts/work-to-guides.prompt.md +0 -18
  165. package/template/docs/assets/references/AGENTS.md +0 -9
  166. package/template/docs/assets/references/CLAUDE.md +0 -9
  167. package/template/docs/assets/references/execution-workflow.md +0 -157
  168. package/template/docs/assets/references/output-contract.md +0 -221
  169. package/template/docs/assets/references/path-and-link-hygiene.md +0 -49
  170. package/template/docs/assets/references/planning-workflow.md +0 -160
  171. package/template/docs/assets/references/prd-change-management.md +0 -129
  172. package/template/docs/assets/templates/AGENTS.md +0 -8
  173. package/template/docs/assets/templates/CLAUDE.md +0 -8
  174. package/template/docs/assets/templates/design.md +0 -30
  175. package/template/docs/assets/templates/plan-overview.md +0 -32
  176. package/template/docs/assets/templates/plan-prd-change.md +0 -99
  177. package/template/docs/assets/templates/prd-change-addition.md +0 -45
  178. package/template/docs/assets/templates/prd-change-revision.md +0 -45
  179. package/template/docs/assets/templates/prd-glossary.md +0 -15
  180. package/template/docs/assets/templates/prd-index.md +0 -45
  181. package/template/docs/assets/templates/prd-reference.md +0 -17
  182. package/template/docs/assets/templates/work-index.md +0 -21
  183. package/template/docs/assets/templates/work-phase.md +0 -34
  184. package/template/docs/guides/AGENTS.md +0 -15
  185. package/template/docs/guides/CLAUDE.md +0 -15
  186. /package/template/{docs/assets → .make-docs/system}/prompts/update-readme-green-field.prompt.md +0 -0
  187. /package/template/{docs/assets → .make-docs/system}/references/harness-capability-matrix.md +0 -0
@@ -0,0 +1,91 @@
1
+ {
2
+ "$schema": "./system-resources.schema.json",
3
+ "schemaVersion": 1,
4
+ "pathBase": "template-root",
5
+ "identityTemplate": "make-docs://system/{type}/{path}",
6
+ "defaultMediaType": "text/markdown; charset=utf-8",
7
+ "resourceTypes": [
8
+ {
9
+ "type": "contract",
10
+ "sourceRoot": ".make-docs/system/contracts",
11
+ "include": [
12
+ "*.md"
13
+ ],
14
+ "exclude": [
15
+ "AGENTS.md",
16
+ "CLAUDE.md",
17
+ "playbook-contract.md"
18
+ ]
19
+ },
20
+ {
21
+ "type": "prompt",
22
+ "sourceRoot": ".make-docs/system/prompts",
23
+ "include": [
24
+ "*.md"
25
+ ],
26
+ "exclude": [
27
+ "AGENTS.md",
28
+ "CLAUDE.md"
29
+ ]
30
+ },
31
+ {
32
+ "type": "reference",
33
+ "sourceRoot": ".make-docs/system/references",
34
+ "include": [
35
+ "*.md"
36
+ ],
37
+ "exclude": [
38
+ "AGENTS.md",
39
+ "CLAUDE.md"
40
+ ]
41
+ },
42
+ {
43
+ "type": "template",
44
+ "sourceRoot": ".make-docs/system/templates",
45
+ "include": [
46
+ "*.md"
47
+ ],
48
+ "exclude": [
49
+ "AGENTS.md",
50
+ "CLAUDE.md"
51
+ ]
52
+ }
53
+ ],
54
+ "systemWorkflows": [
55
+ {
56
+ "id": "naive-uat",
57
+ "contracts": [
58
+ "make-docs://system/contract/naive-uat-contract.md"
59
+ ],
60
+ "prompts": [
61
+ "make-docs://system/prompt/naive-uat-facilitator.prompt.md",
62
+ "make-docs://system/prompt/naive-uat-tester.prompt.md"
63
+ ],
64
+ "references": [
65
+ "make-docs://system/reference/naive-uat-workflow.md"
66
+ ],
67
+ "templates": [
68
+ "make-docs://system/template/naive-uat-scenario.md"
69
+ ]
70
+ },
71
+ {
72
+ "id": "performance-evidence",
73
+ "contracts": [
74
+ "make-docs://system/contract/performance-evidence-governance.md"
75
+ ],
76
+ "prompts": [
77
+ "make-docs://system/prompt/performance-coverage.prompt.md"
78
+ ],
79
+ "references": [
80
+ "make-docs://system/reference/performance-evidence.md"
81
+ ],
82
+ "templates": [
83
+ "make-docs://system/template/performance-evidence-profile.md"
84
+ ]
85
+ }
86
+ ],
87
+ "preservedLegacyPaths": [
88
+ ".make-docs/contracts/system/playbook-contract.md",
89
+ "docs/assets/playbooks/**"
90
+ ]
91
+ }
@@ -0,0 +1,204 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://make-docs.local/schema/system-resources.schema.json",
4
+ "title": "Make Docs System Resource Catalog",
5
+ "type": "object",
6
+ "additionalProperties": false,
7
+ "required": [
8
+ "schemaVersion",
9
+ "pathBase",
10
+ "identityTemplate",
11
+ "defaultMediaType",
12
+ "resourceTypes",
13
+ "systemWorkflows",
14
+ "preservedLegacyPaths"
15
+ ],
16
+ "properties": {
17
+ "$schema": {
18
+ "type": "string"
19
+ },
20
+ "schemaVersion": {
21
+ "const": 1
22
+ },
23
+ "pathBase": {
24
+ "const": "template-root"
25
+ },
26
+ "identityTemplate": {
27
+ "const": "make-docs://system/{type}/{path}"
28
+ },
29
+ "defaultMediaType": {
30
+ "const": "text/markdown; charset=utf-8"
31
+ },
32
+ "resourceTypes": {
33
+ "type": "array",
34
+ "minItems": 4,
35
+ "maxItems": 4,
36
+ "allOf": [
37
+ {
38
+ "contains": {
39
+ "type": "object",
40
+ "properties": {
41
+ "type": {
42
+ "const": "contract"
43
+ }
44
+ },
45
+ "required": [
46
+ "type"
47
+ ]
48
+ },
49
+ "minContains": 1,
50
+ "maxContains": 1
51
+ },
52
+ {
53
+ "contains": {
54
+ "type": "object",
55
+ "properties": {
56
+ "type": {
57
+ "const": "prompt"
58
+ }
59
+ },
60
+ "required": [
61
+ "type"
62
+ ]
63
+ },
64
+ "minContains": 1,
65
+ "maxContains": 1
66
+ },
67
+ {
68
+ "contains": {
69
+ "type": "object",
70
+ "properties": {
71
+ "type": {
72
+ "const": "reference"
73
+ }
74
+ },
75
+ "required": [
76
+ "type"
77
+ ]
78
+ },
79
+ "minContains": 1,
80
+ "maxContains": 1
81
+ },
82
+ {
83
+ "contains": {
84
+ "type": "object",
85
+ "properties": {
86
+ "type": {
87
+ "const": "template"
88
+ }
89
+ },
90
+ "required": [
91
+ "type"
92
+ ]
93
+ },
94
+ "minContains": 1,
95
+ "maxContains": 1
96
+ }
97
+ ],
98
+ "items": {
99
+ "$ref": "#/$defs/resourceType"
100
+ }
101
+ },
102
+ "systemWorkflows": {
103
+ "type": "array",
104
+ "items": {
105
+ "$ref": "#/$defs/systemWorkflow"
106
+ }
107
+ },
108
+ "preservedLegacyPaths": {
109
+ "type": "array",
110
+ "uniqueItems": true,
111
+ "items": {
112
+ "$ref": "#/$defs/templatePath"
113
+ }
114
+ }
115
+ },
116
+ "$defs": {
117
+ "templatePath": {
118
+ "type": "string",
119
+ "minLength": 1,
120
+ "pattern": "^(?!/)(?!.*\\\\)(?!.*(?:^|/)\\.{1,2}(?:/|$)).+$"
121
+ },
122
+ "resourceUri": {
123
+ "type": "string",
124
+ "pattern": "^make-docs://system/(contract|prompt|reference|template)/(?!/)(?!.*\\\\)(?!\\.{1,2}(?:/|$))(?!.*\\/\\.{1,2}(?:/|$))[^#?]+$"
125
+ },
126
+ "resourceType": {
127
+ "type": "object",
128
+ "additionalProperties": false,
129
+ "required": [
130
+ "type",
131
+ "sourceRoot",
132
+ "include",
133
+ "exclude"
134
+ ],
135
+ "properties": {
136
+ "type": {
137
+ "enum": [
138
+ "contract",
139
+ "prompt",
140
+ "reference",
141
+ "template"
142
+ ]
143
+ },
144
+ "sourceRoot": {
145
+ "$ref": "#/$defs/templatePath"
146
+ },
147
+ "include": {
148
+ "type": "array",
149
+ "minItems": 1,
150
+ "uniqueItems": true,
151
+ "items": {
152
+ "type": "string",
153
+ "minLength": 1
154
+ }
155
+ },
156
+ "exclude": {
157
+ "type": "array",
158
+ "uniqueItems": true,
159
+ "items": {
160
+ "type": "string",
161
+ "minLength": 1
162
+ }
163
+ }
164
+ }
165
+ },
166
+ "systemWorkflow": {
167
+ "type": "object",
168
+ "additionalProperties": false,
169
+ "required": [
170
+ "id",
171
+ "contracts",
172
+ "prompts",
173
+ "references",
174
+ "templates"
175
+ ],
176
+ "properties": {
177
+ "id": {
178
+ "type": "string",
179
+ "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
180
+ },
181
+ "contracts": {
182
+ "$ref": "#/$defs/resourceUriList"
183
+ },
184
+ "prompts": {
185
+ "$ref": "#/$defs/resourceUriList"
186
+ },
187
+ "references": {
188
+ "$ref": "#/$defs/resourceUriList"
189
+ },
190
+ "templates": {
191
+ "$ref": "#/$defs/resourceUriList"
192
+ }
193
+ }
194
+ },
195
+ "resourceUriList": {
196
+ "type": "array",
197
+ "minItems": 1,
198
+ "uniqueItems": true,
199
+ "items": {
200
+ "$ref": "#/$defs/resourceUri"
201
+ }
202
+ }
203
+ }
204
+ }
@@ -1,3 +1,10 @@
1
+ <!-- make-docs:begin -->
1
2
  # Agent Instructions
2
3
 
3
- When asked to create documentation for this project that is not `README.md`, read the same-named instruction file in `docs/` before writing.
4
+ - When asked to create documentation for this project that is not `README.md`, read the same-named instruction file in `docs/` before writing.
5
+ - For documentation lifecycle order or skip/reorder/revisit decisions, use a valid local `.make-docs/system/references/lifecycle.md` first. If that body is absent, read `make-docs://system/reference/lifecycle.md` with `make-docs resource read`, and surface departures from the default arc.
6
+ - For governed work and material task updates, decisions, recommendations, error or limit reports, and completion replies, use the applicable lifecycle guidance plus valid local bodies for `.make-docs/system/contracts/human-experience-contract.md` and `.make-docs/system/references/human-experience.md`. If a body is absent, read its matching `make-docs://system/contract/human-experience-contract.md` or `make-docs://system/reference/human-experience.md` resource with `make-docs resource read`.
7
+ - A project can use Make Docs without Store access. If a Store-backed operation reports `store-not-configured`, `store-unavailable`, `store-unsafe`, or `store-denied`, stop only that operation, report its exact action, and continue independent Store-free work. Refresh access and retry only that operation after setup or repair. When the task repairs Make Docs setup, MCP, or Store access, missing Store or MCP access is evidence and must not block the repair.
8
+ - Before staging or committing changes, use a valid local `.make-docs/system/contracts/commit-message-convention.md` first. If that body is absent, read `make-docs://system/contract/commit-message-convention.md` with `make-docs resource read`.
9
+ - Do not infer optional Skills, plugins, Playbooks, Protocols, or unavailable policy from this router.
10
+ <!-- make-docs:end -->
@@ -1,3 +1,10 @@
1
+ <!-- make-docs:begin -->
1
2
  # Agent Instructions
2
3
 
3
- When asked to create documentation for this project that is not `README.md`, read the same-named instruction file in `docs/` before writing.
4
+ - When asked to create documentation for this project that is not `README.md`, read the same-named instruction file in `docs/` before writing.
5
+ - For documentation lifecycle order or skip/reorder/revisit decisions, use a valid local `.make-docs/system/references/lifecycle.md` first. If that body is absent, read `make-docs://system/reference/lifecycle.md` with `make-docs resource read`, and surface departures from the default arc.
6
+ - For governed work and material task updates, decisions, recommendations, error or limit reports, and completion replies, use the applicable lifecycle guidance plus valid local bodies for `.make-docs/system/contracts/human-experience-contract.md` and `.make-docs/system/references/human-experience.md`. If a body is absent, read its matching `make-docs://system/contract/human-experience-contract.md` or `make-docs://system/reference/human-experience.md` resource with `make-docs resource read`.
7
+ - A project can use Make Docs without Store access. If a Store-backed operation reports `store-not-configured`, `store-unavailable`, `store-unsafe`, or `store-denied`, stop only that operation, report its exact action, and continue independent Store-free work. Refresh access and retry only that operation after setup or repair. When the task repairs Make Docs setup, MCP, or Store access, missing Store or MCP access is evidence and must not block the repair.
8
+ - Before staging or committing changes, use a valid local `.make-docs/system/contracts/commit-message-convention.md` first. If that body is absent, read `make-docs://system/contract/commit-message-convention.md` with `make-docs resource read`.
9
+ - Do not infer optional Skills, plugins, Playbooks, Protocols, or unavailable policy from this router.
10
+ <!-- make-docs:end -->
@@ -0,0 +1,22 @@
1
+ <!-- make-docs:begin -->
2
+ # Documentation Router
3
+
4
+ Use `docs/` only as a router. Do not create generated files directly in this directory. Use a valid local resource body below `.make-docs/system/<type>/` first. When a required local body is absent, read its stable `make-docs://system/<type>/<posix-relative-path>` URI with `make-docs resource read`.
5
+ - For lifecycle order or skip/reorder/revisit decisions, read `.make-docs/system/references/lifecycle.md` or `make-docs://system/reference/lifecycle.md` and surface departures from the default arc.
6
+ - Source Markdown NEVER uses semantic line breaks; for path and link hygiene, use project-relative paths and relative Markdown links, and read `.make-docs/system/references/path-and-link-hygiene.md` or `make-docs://system/reference/path-and-link-hygiene.md`.
7
+ - For design docs, read `.make-docs/system/references/design-workflow.md` or `make-docs://system/reference/design-workflow.md`, `.make-docs/system/contracts/design-contract.md` or `make-docs://system/contract/design-contract.md`, and `.make-docs/system/templates/design.md` or `make-docs://system/template/design.md`, then continue in `docs/designs/`; for plans, read `.make-docs/system/references/planning-workflow.md` or `make-docs://system/reference/planning-workflow.md` and the selected local plan template below `.make-docs/system/templates/` or its `make-docs://system/template/<posix-relative-path>` URI, then continue in `docs/plans/`.
8
+ - For PRD or work generation, read `.make-docs/system/references/execution-workflow.md` or `make-docs://system/reference/execution-workflow.md`, `.make-docs/system/contracts/output-contract.md` or `make-docs://system/contract/output-contract.md`, and the selected local template below `.make-docs/system/templates/` or its `make-docs://system/template/<posix-relative-path>` URI, then continue in `docs/prd/` or `docs/work/`; work phase tasks use `- [ ] t1: ...` checkbox items and acceptance criteria use plain bullets.
9
+ - For requirement changes, read `.make-docs/system/references/prd-change-management.md` or `make-docs://system/reference/prd-change-management.md`; for gaps, drift, questions, risks, decisions, or closeout findings, first update `docs/prd/03-open-questions-and-risk-register.md` when it exists.
10
+ - Shared project material belongs in `docs/assets/project/`; audience assets belong in `docs/assets/<persona-slug>/`. Archives and history belong in `.make-docs/archive/`. Create asset directories only for needed content; keep routers at the assets root only.
11
+ - Built-in Personas have `slug`, `label`, `description`, and `primitive`: `user`, `User`, `People or agents that use the project.`, `user`; and `maintainer`, `Maintainer`, `People or agents that build, operate, maintain, or extend the project.`, `maintainer`. Either role can be human or agent. Merge `.make-docs/config.yaml` Personas by slug with both defaults; omitted built-in display fields inherit, and their primitives stay fixed. Custom entries need all four fields and a `user` or `maintainer` primitive. Missing/empty/comment-only config or an absent/empty list keeps defaults. Explicit null, malformed values, duplicates, unsafe slugs, or invalid primitives are errors. Reserve `project`, `archive`, `artifacts`, `library`, and `playbooks`; never silently remap a custom name. `make-docs project persona list` shows the effective set when the CLI is present.
12
+ - Asset router files: AGENTS.md
13
+ - Without the CLI, use these defaults/config and create only the declared assets-root instruction files with the shared/audience paths, on-demand rule, and Store-only state rule. Do not infer filenames from your actor identity. If the declaration is absent or invalid, ask for an explicit project choice before router creation; content work can continue. Ordinary work may continue without optional CLI capture, with no local operational fallback or false capture claim.
14
+ - Before guide or system-resource coverage work, read `.make-docs/system/contracts/coverage-pass-contract.md` or `make-docs://system/contract/coverage-pass-contract.md`. Before guide writing, also read `.make-docs/system/contracts/guide-contract.md` or `make-docs://system/contract/guide-contract.md`, inspect existing guides for overlap, choose the verdict and target Persona, and use the matching local guide template below `.make-docs/system/templates/` or its `make-docs://system/template/<posix-relative-path>` URI.
15
+ - When work changes deferred obligations or Naive UAT, read `.make-docs/system/contracts/deferred-obligation-contract.md` or `make-docs://system/contract/deferred-obligation-contract.md`, `.make-docs/system/contracts/naive-uat-contract.md` or `make-docs://system/contract/naive-uat-contract.md`, and `.make-docs/system/references/naive-uat-workflow.md` or `make-docs://system/reference/naive-uat-workflow.md`. Each activated Naive-UAT run selects one eligible configured Persona and keeps tester qualification separate.
16
+ - Playbooks and Protocols are not current Make Docs product capabilities. Treat existing Playbook- or Protocol-shaped paths as legacy migration inputs.
17
+ - After guide work, reconcile overlapping guides when useful; use `## Future Coverage` inside guides for downstream-dependent guide updates instead of creating design docs, architecture decisions, or PRD risks only to remember future guide work.
18
+ - For closeout history records, read `.make-docs/system/contracts/history-record-contract.md` or `make-docs://system/contract/history-record-contract.md` and `.make-docs/system/templates/history-record.md` or `make-docs://system/template/history-record.md`, then use the current archive path owned by project authority.
19
+ - Prompts are first-class system resources. Read them by stable `make-docs://system/prompt/<posix-relative-path>` URI with `make-docs resource read` when a valid local body is absent. Their governing contracts own reusable rules.
20
+ - Do not infer optional Skills, plugins, Playbooks, Protocols, or unavailable policy from this router.
21
+ - **NEVER** add YAML front matter to `README.md` files.
22
+ <!-- make-docs:end -->
@@ -1,15 +1,23 @@
1
+ <!-- make-docs:begin -->
1
2
  # Documentation Router
2
3
 
3
- Use `docs/` only as a router. Do not create generated files directly in this directory.
4
-
5
- - Source Markdown uses semantic line breaks; for path and link hygiene, use project-relative paths and relative Markdown links, and read `docs/assets/references/path-and-link-hygiene.md` when auditing or deciding whether an absolute path is warranted.
6
- - For design docs, read `docs/assets/references/design-workflow.md`, `docs/assets/references/design-contract.md`, and `docs/assets/templates/design.md`, then continue in `docs/designs/`.
7
- - For plans, read `docs/assets/references/planning-workflow.md` and the selected plan template in `docs/assets/templates/`, then continue in `docs/plans/`.
8
- - For PRD or work generation, read `docs/assets/references/execution-workflow.md`, `docs/assets/references/output-contract.md`, and the selected template in `docs/assets/templates/`, then continue in `docs/prd/` or `docs/work/`; work phase tasks use `- [ ] t1: ...` checkbox items and acceptance criteria use plain bullets.
9
- - For requirement changes, also read `docs/assets/references/prd-change-management.md` before choosing change templates or delta outputs.
10
- - For gaps, drift, unresolved questions, risks, decisions, or closeout findings, first update `docs/prd/03-open-questions-and-risk-register.md` when it exists; do not create separate questions, decisions, risks, gaps, or architecture-decision files unless the user explicitly asks.
11
- - For guides, continue in `docs/guides/`. Before writing, read `docs/assets/references/guide-contract.md`, inspect existing guides for overlap, choose `developer`, `user`, `both`, `update-existing`, `link-only`, or `none`, and use the matching template (`docs/assets/templates/guide-developer.md` or `docs/assets/templates/guide-user.md`).
12
- - After guide work, reconcile overlapping existing guides with reciprocal links, `related` frontmatter, or concise supplemental context when it improves discoverability.
13
- - Use `## Future Coverage` inside guides for downstream-dependent guide updates. Do not create design docs, architecture decisions, or PRD risk-register items solely to remember future guide work.
14
- - For history records, continue in `docs/assets/history/` — read `docs/assets/references/history-record-contract.md` and `docs/assets/templates/history-record.md` before writing.
15
- - For reusable prompt starters, use `docs/assets/prompts/`; prompts are optional starters, not authority.
4
+ Use `docs/` only as a router. Do not create generated files directly in this directory. Use a valid local resource body below `.make-docs/system/<type>/` first. When a required local body is absent, read its stable `make-docs://system/<type>/<posix-relative-path>` URI with `make-docs resource read`.
5
+ - For lifecycle order or skip/reorder/revisit decisions, read `.make-docs/system/references/lifecycle.md` or `make-docs://system/reference/lifecycle.md` and surface departures from the default arc.
6
+ - When creating or materially updating governed work, read `.make-docs/system/contracts/human-experience-contract.md` or `make-docs://system/contract/human-experience-contract.md` and `.make-docs/system/references/human-experience.md` or `make-docs://system/reference/human-experience.md`. Use them with the lifecycle reference to carry the local human outcome without copying the standard into each artifact.
7
+ - Source Markdown NEVER uses semantic line breaks; for path and link hygiene, use project-relative paths and relative Markdown links, and read `.make-docs/system/references/path-and-link-hygiene.md` or `make-docs://system/reference/path-and-link-hygiene.md`.
8
+ - For design docs, read `.make-docs/system/references/design-workflow.md` or `make-docs://system/reference/design-workflow.md`, `.make-docs/system/contracts/design-contract.md` or `make-docs://system/contract/design-contract.md`, and `.make-docs/system/templates/design.md` or `make-docs://system/template/design.md`, then continue in `docs/designs/`; for plans, read `.make-docs/system/references/planning-workflow.md` or `make-docs://system/reference/planning-workflow.md` and the selected local plan template below `.make-docs/system/templates/` or its `make-docs://system/template/<posix-relative-path>` URI, then continue in `docs/plans/`.
9
+ - For PRD or work generation, read `.make-docs/system/references/execution-workflow.md` or `make-docs://system/reference/execution-workflow.md`, `.make-docs/system/contracts/output-contract.md` or `make-docs://system/contract/output-contract.md`, and the selected local template below `.make-docs/system/templates/` or its `make-docs://system/template/<posix-relative-path>` URI, then continue in `docs/prd/` or `docs/work/`; work phase tasks use `- [ ] t1: ...` checkbox items and acceptance criteria use plain bullets.
10
+ - For requirement changes, read `.make-docs/system/references/prd-change-management.md` or `make-docs://system/reference/prd-change-management.md`; for gaps, drift, questions, risks, decisions, or closeout findings, first update `docs/prd/03-open-questions-and-risk-register.md` when it exists.
11
+ - Shared project material belongs in `docs/assets/project/`; audience assets belong in `docs/assets/<persona-slug>/`. Archives and history belong in `.make-docs/archive/`. Create asset directories only for needed content; keep routers at the assets root only.
12
+ - Built-in Personas have `slug`, `label`, `description`, and `primitive`: `user`, `User`, `People or agents that use the project.`, `user`; and `maintainer`, `Maintainer`, `People or agents that build, operate, maintain, or extend the project.`, `maintainer`. Either role can be human or agent. Merge `.make-docs/config.yaml` Personas by slug with both defaults; omitted built-in display fields inherit, and their primitives stay fixed. Custom entries need all four fields and a `user` or `maintainer` primitive. Missing/empty/comment-only config or an absent/empty list keeps defaults. Explicit null, malformed values, duplicates, unsafe slugs, or invalid primitives are errors. Reserve `project`, `archive`, `artifacts`, `library`, and `playbooks`; never silently remap a custom name. `make-docs project persona list` shows the effective set when the CLI is present.
13
+ - Asset router files: AGENTS.md, CLAUDE.md
14
+ - Without the CLI, use these defaults/config and create only the declared assets-root instruction files with the shared/audience paths, on-demand rule, and Store-only state rule. Do not infer filenames from your actor identity. If the declaration is absent or invalid, ask for an explicit project choice before router creation; content work can continue. Ordinary work may continue without optional CLI capture, with no local operational fallback or false capture claim.
15
+ - Before guide or system-resource coverage work, read `.make-docs/system/contracts/coverage-pass-contract.md` or `make-docs://system/contract/coverage-pass-contract.md`. Before guide writing, also read `.make-docs/system/contracts/guide-contract.md` or `make-docs://system/contract/guide-contract.md`, inspect existing guides for overlap, choose the verdict and target Persona, and use the matching local guide template below `.make-docs/system/templates/` or its `make-docs://system/template/<posix-relative-path>` URI.
16
+ - When work changes deferred obligations or Naive UAT, read `.make-docs/system/contracts/deferred-obligation-contract.md` or `make-docs://system/contract/deferred-obligation-contract.md`, `.make-docs/system/contracts/naive-uat-contract.md` or `make-docs://system/contract/naive-uat-contract.md`, and `.make-docs/system/references/naive-uat-workflow.md` or `make-docs://system/reference/naive-uat-workflow.md`. Each activated Naive-UAT run selects one eligible configured Persona and keeps tester qualification separate.
17
+ - Playbooks and Protocols are not current Make Docs product capabilities. Treat existing Playbook- or Protocol-shaped paths as legacy migration inputs.
18
+ - After guide work, reconcile overlapping guides when useful; use `## Future Coverage` inside guides for downstream-dependent guide updates instead of creating design docs, architecture decisions, or PRD risks only to remember future guide work.
19
+ - For closeout history records, read `.make-docs/system/contracts/history-record-contract.md` or `make-docs://system/contract/history-record-contract.md` and `.make-docs/system/templates/history-record.md` or `make-docs://system/template/history-record.md`, then use the current archive path owned by project authority.
20
+ - Prompts are first-class system resources. Read them by stable `make-docs://system/prompt/<posix-relative-path>` URI with `make-docs resource read` when a valid local body is absent. Their governing contracts own reusable rules.
21
+ - Do not infer optional Skills, plugins, Playbooks, Protocols, or unavailable policy from this router.
22
+ - **NEVER** add YAML front matter to `README.md` files.
23
+ <!-- make-docs:end -->
@@ -0,0 +1,22 @@
1
+ <!-- make-docs:begin -->
2
+ # Documentation Router
3
+
4
+ Use `docs/` only as a router. Do not create generated files directly in this directory. Use a valid local resource body below `.make-docs/system/<type>/` first. When a required local body is absent, read its stable `make-docs://system/<type>/<posix-relative-path>` URI with `make-docs resource read`.
5
+ - For lifecycle order or skip/reorder/revisit decisions, read `.make-docs/system/references/lifecycle.md` or `make-docs://system/reference/lifecycle.md` and surface departures from the default arc.
6
+ - Source Markdown NEVER uses semantic line breaks; for path and link hygiene, use project-relative paths and relative Markdown links, and read `.make-docs/system/references/path-and-link-hygiene.md` or `make-docs://system/reference/path-and-link-hygiene.md`.
7
+ - For design docs, read `.make-docs/system/references/design-workflow.md` or `make-docs://system/reference/design-workflow.md`, `.make-docs/system/contracts/design-contract.md` or `make-docs://system/contract/design-contract.md`, and `.make-docs/system/templates/design.md` or `make-docs://system/template/design.md`, then continue in `docs/designs/`; for plans, read `.make-docs/system/references/planning-workflow.md` or `make-docs://system/reference/planning-workflow.md` and the selected local plan template below `.make-docs/system/templates/` or its `make-docs://system/template/<posix-relative-path>` URI, then continue in `docs/plans/`.
8
+ - For PRD or work generation, read `.make-docs/system/references/execution-workflow.md` or `make-docs://system/reference/execution-workflow.md`, `.make-docs/system/contracts/output-contract.md` or `make-docs://system/contract/output-contract.md`, and the selected local template below `.make-docs/system/templates/` or its `make-docs://system/template/<posix-relative-path>` URI, then continue in `docs/prd/` or `docs/work/`; work phase tasks use `- [ ] t1: ...` checkbox items and acceptance criteria use plain bullets.
9
+ - For requirement changes, read `.make-docs/system/references/prd-change-management.md` or `make-docs://system/reference/prd-change-management.md`; for gaps, drift, questions, risks, decisions, or closeout findings, first update `docs/prd/03-open-questions-and-risk-register.md` when it exists.
10
+ - Shared project material belongs in `docs/assets/project/`; audience assets belong in `docs/assets/<persona-slug>/`. Archives and history belong in `.make-docs/archive/`. Create asset directories only for needed content; keep routers at the assets root only.
11
+ - Built-in Personas have `slug`, `label`, `description`, and `primitive`: `user`, `User`, `People or agents that use the project.`, `user`; and `maintainer`, `Maintainer`, `People or agents that build, operate, maintain, or extend the project.`, `maintainer`. Either role can be human or agent. Merge `.make-docs/config.yaml` Personas by slug with both defaults; omitted built-in display fields inherit, and their primitives stay fixed. Custom entries need all four fields and a `user` or `maintainer` primitive. Missing/empty/comment-only config or an absent/empty list keeps defaults. Explicit null, malformed values, duplicates, unsafe slugs, or invalid primitives are errors. Reserve `project`, `archive`, `artifacts`, `library`, and `playbooks`; never silently remap a custom name. `make-docs project persona list` shows the effective set when the CLI is present.
12
+ - Asset router files: CLAUDE.md
13
+ - Without the CLI, use these defaults/config and create only the declared assets-root instruction files with the shared/audience paths, on-demand rule, and Store-only state rule. Do not infer filenames from your actor identity. If the declaration is absent or invalid, ask for an explicit project choice before router creation; content work can continue. Ordinary work may continue without optional CLI capture, with no local operational fallback or false capture claim.
14
+ - Before guide or system-resource coverage work, read `.make-docs/system/contracts/coverage-pass-contract.md` or `make-docs://system/contract/coverage-pass-contract.md`. Before guide writing, also read `.make-docs/system/contracts/guide-contract.md` or `make-docs://system/contract/guide-contract.md`, inspect existing guides for overlap, choose the verdict and target Persona, and use the matching local guide template below `.make-docs/system/templates/` or its `make-docs://system/template/<posix-relative-path>` URI.
15
+ - When work changes deferred obligations or Naive UAT, read `.make-docs/system/contracts/deferred-obligation-contract.md` or `make-docs://system/contract/deferred-obligation-contract.md`, `.make-docs/system/contracts/naive-uat-contract.md` or `make-docs://system/contract/naive-uat-contract.md`, and `.make-docs/system/references/naive-uat-workflow.md` or `make-docs://system/reference/naive-uat-workflow.md`. Each activated Naive-UAT run selects one eligible configured Persona and keeps tester qualification separate.
16
+ - Playbooks and Protocols are not current Make Docs product capabilities. Treat existing Playbook- or Protocol-shaped paths as legacy migration inputs.
17
+ - After guide work, reconcile overlapping guides when useful; use `## Future Coverage` inside guides for downstream-dependent guide updates instead of creating design docs, architecture decisions, or PRD risks only to remember future guide work.
18
+ - For closeout history records, read `.make-docs/system/contracts/history-record-contract.md` or `make-docs://system/contract/history-record-contract.md` and `.make-docs/system/templates/history-record.md` or `make-docs://system/template/history-record.md`, then use the current archive path owned by project authority.
19
+ - Prompts are first-class system resources. Read them by stable `make-docs://system/prompt/<posix-relative-path>` URI with `make-docs resource read` when a valid local body is absent. Their governing contracts own reusable rules.
20
+ - Do not infer optional Skills, plugins, Playbooks, Protocols, or unavailable policy from this router.
21
+ - **NEVER** add YAML front matter to `README.md` files.
22
+ <!-- make-docs:end -->
@@ -1,15 +1,23 @@
1
+ <!-- make-docs:begin -->
1
2
  # Documentation Router
2
3
 
3
- Use `docs/` only as a router. Do not create generated files directly in this directory.
4
-
5
- - Source Markdown uses semantic line breaks; for path and link hygiene, use project-relative paths and relative Markdown links, and read `docs/assets/references/path-and-link-hygiene.md` when auditing or deciding whether an absolute path is warranted.
6
- - For design docs, read `docs/assets/references/design-workflow.md`, `docs/assets/references/design-contract.md`, and `docs/assets/templates/design.md`, then continue in `docs/designs/`.
7
- - For plans, read `docs/assets/references/planning-workflow.md` and the selected plan template in `docs/assets/templates/`, then continue in `docs/plans/`.
8
- - For PRD or work generation, read `docs/assets/references/execution-workflow.md`, `docs/assets/references/output-contract.md`, and the selected template in `docs/assets/templates/`, then continue in `docs/prd/` or `docs/work/`; work phase tasks use `- [ ] t1: ...` checkbox items and acceptance criteria use plain bullets.
9
- - For requirement changes, also read `docs/assets/references/prd-change-management.md` before choosing change templates or delta outputs.
10
- - For gaps, drift, unresolved questions, risks, decisions, or closeout findings, first update `docs/prd/03-open-questions-and-risk-register.md` when it exists; do not create separate questions, decisions, risks, gaps, or architecture-decision files unless the user explicitly asks.
11
- - For guides, continue in `docs/guides/`. Before writing, read `docs/assets/references/guide-contract.md`, inspect existing guides for overlap, choose `developer`, `user`, `both`, `update-existing`, `link-only`, or `none`, and use the matching template (`docs/assets/templates/guide-developer.md` or `docs/assets/templates/guide-user.md`).
12
- - After guide work, reconcile overlapping existing guides with reciprocal links, `related` frontmatter, or concise supplemental context when it improves discoverability.
13
- - Use `## Future Coverage` inside guides for downstream-dependent guide updates. Do not create design docs, architecture decisions, or PRD risk-register items solely to remember future guide work.
14
- - For history records, continue in `docs/assets/history/` — read `docs/assets/references/history-record-contract.md` and `docs/assets/templates/history-record.md` before writing.
15
- - For reusable prompt starters, use `docs/assets/prompts/`; prompts are optional starters, not authority.
4
+ Use `docs/` only as a router. Do not create generated files directly in this directory. Use a valid local resource body below `.make-docs/system/<type>/` first. When a required local body is absent, read its stable `make-docs://system/<type>/<posix-relative-path>` URI with `make-docs resource read`.
5
+ - For lifecycle order or skip/reorder/revisit decisions, read `.make-docs/system/references/lifecycle.md` or `make-docs://system/reference/lifecycle.md` and surface departures from the default arc.
6
+ - When creating or materially updating governed work, read `.make-docs/system/contracts/human-experience-contract.md` or `make-docs://system/contract/human-experience-contract.md` and `.make-docs/system/references/human-experience.md` or `make-docs://system/reference/human-experience.md`. Use them with the lifecycle reference to carry the local human outcome without copying the standard into each artifact.
7
+ - Source Markdown NEVER uses semantic line breaks; for path and link hygiene, use project-relative paths and relative Markdown links, and read `.make-docs/system/references/path-and-link-hygiene.md` or `make-docs://system/reference/path-and-link-hygiene.md`.
8
+ - For design docs, read `.make-docs/system/references/design-workflow.md` or `make-docs://system/reference/design-workflow.md`, `.make-docs/system/contracts/design-contract.md` or `make-docs://system/contract/design-contract.md`, and `.make-docs/system/templates/design.md` or `make-docs://system/template/design.md`, then continue in `docs/designs/`; for plans, read `.make-docs/system/references/planning-workflow.md` or `make-docs://system/reference/planning-workflow.md` and the selected local plan template below `.make-docs/system/templates/` or its `make-docs://system/template/<posix-relative-path>` URI, then continue in `docs/plans/`.
9
+ - For PRD or work generation, read `.make-docs/system/references/execution-workflow.md` or `make-docs://system/reference/execution-workflow.md`, `.make-docs/system/contracts/output-contract.md` or `make-docs://system/contract/output-contract.md`, and the selected local template below `.make-docs/system/templates/` or its `make-docs://system/template/<posix-relative-path>` URI, then continue in `docs/prd/` or `docs/work/`; work phase tasks use `- [ ] t1: ...` checkbox items and acceptance criteria use plain bullets.
10
+ - For requirement changes, read `.make-docs/system/references/prd-change-management.md` or `make-docs://system/reference/prd-change-management.md`; for gaps, drift, questions, risks, decisions, or closeout findings, first update `docs/prd/03-open-questions-and-risk-register.md` when it exists.
11
+ - Shared project material belongs in `docs/assets/project/`; audience assets belong in `docs/assets/<persona-slug>/`. Archives and history belong in `.make-docs/archive/`. Create asset directories only for needed content; keep routers at the assets root only.
12
+ - Built-in Personas have `slug`, `label`, `description`, and `primitive`: `user`, `User`, `People or agents that use the project.`, `user`; and `maintainer`, `Maintainer`, `People or agents that build, operate, maintain, or extend the project.`, `maintainer`. Either role can be human or agent. Merge `.make-docs/config.yaml` Personas by slug with both defaults; omitted built-in display fields inherit, and their primitives stay fixed. Custom entries need all four fields and a `user` or `maintainer` primitive. Missing/empty/comment-only config or an absent/empty list keeps defaults. Explicit null, malformed values, duplicates, unsafe slugs, or invalid primitives are errors. Reserve `project`, `archive`, `artifacts`, `library`, and `playbooks`; never silently remap a custom name. `make-docs project persona list` shows the effective set when the CLI is present.
13
+ - Asset router files: AGENTS.md, CLAUDE.md
14
+ - Without the CLI, use these defaults/config and create only the declared assets-root instruction files with the shared/audience paths, on-demand rule, and Store-only state rule. Do not infer filenames from your actor identity. If the declaration is absent or invalid, ask for an explicit project choice before router creation; content work can continue. Ordinary work may continue without optional CLI capture, with no local operational fallback or false capture claim.
15
+ - Before guide or system-resource coverage work, read `.make-docs/system/contracts/coverage-pass-contract.md` or `make-docs://system/contract/coverage-pass-contract.md`. Before guide writing, also read `.make-docs/system/contracts/guide-contract.md` or `make-docs://system/contract/guide-contract.md`, inspect existing guides for overlap, choose the verdict and target Persona, and use the matching local guide template below `.make-docs/system/templates/` or its `make-docs://system/template/<posix-relative-path>` URI.
16
+ - When work changes deferred obligations or Naive UAT, read `.make-docs/system/contracts/deferred-obligation-contract.md` or `make-docs://system/contract/deferred-obligation-contract.md`, `.make-docs/system/contracts/naive-uat-contract.md` or `make-docs://system/contract/naive-uat-contract.md`, and `.make-docs/system/references/naive-uat-workflow.md` or `make-docs://system/reference/naive-uat-workflow.md`. Each activated Naive-UAT run selects one eligible configured Persona and keeps tester qualification separate.
17
+ - Playbooks and Protocols are not current Make Docs product capabilities. Treat existing Playbook- or Protocol-shaped paths as legacy migration inputs.
18
+ - After guide work, reconcile overlapping guides when useful; use `## Future Coverage` inside guides for downstream-dependent guide updates instead of creating design docs, architecture decisions, or PRD risks only to remember future guide work.
19
+ - For closeout history records, read `.make-docs/system/contracts/history-record-contract.md` or `make-docs://system/contract/history-record-contract.md` and `.make-docs/system/templates/history-record.md` or `make-docs://system/template/history-record.md`, then use the current archive path owned by project authority.
20
+ - Prompts are first-class system resources. Read them by stable `make-docs://system/prompt/<posix-relative-path>` URI with `make-docs resource read` when a valid local body is absent. Their governing contracts own reusable rules.
21
+ - Do not infer optional Skills, plugins, Playbooks, Protocols, or unavailable policy from this router.
22
+ - **NEVER** add YAML front matter to `README.md` files.
23
+ <!-- make-docs:end -->
@@ -1,9 +1,13 @@
1
+ <!-- make-docs:begin -->
1
2
  # Document Assets Router
2
3
 
3
- This router describes the target `docs/assets/` document-resource namespace.
4
-
5
- - Archive records belong in `docs/assets/archive/`.
6
- - History records belong in `docs/assets/history/`; read `docs/assets/references/history-record-contract.md` and `docs/assets/templates/history-record.md` before writing.
7
- - Reusable prompts, references, and templates belong in `docs/assets/prompts/`, `docs/assets/references/`, and `docs/assets/templates/`.
8
- - make-docs runtime state does not belong under `docs/assets/`; canonical state lives at `.make-docs/manifest.json` and `.make-docs/conflicts/<run-id>/`.
9
- - Do not create `docs/assets/config/`, `docs/assets/state/`, `docs/assets/manifest.json`, or `docs/assets/conflicts/`.
4
+ - Shared, non-authoritative material uses `docs/assets/project/`. Audience assets use `docs/assets/<persona-slug>/`; audience testing uses its `testing/` child.
5
+ - Defaults are `user` and `maintainer`. Either role can be human or agent. Merge valid `.make-docs/config.yaml` Personas with those defaults; `project` is reserved shared material. Do not infer an audience from the executor.
6
+ - Create only paths needed by actual content. Managed instruction files belong at this root only, for the harness files declared in the `docs/` router.
7
+ - Archives and history use `.make-docs/archive/`. Old Library, artifact, archive, and Playbook families require reviewed migration; no new Playbook or Protocol assets are supported.
8
+ - For guide work, use valid local `.make-docs/system/contracts/guide-contract.md` and `.make-docs/system/contracts/coverage-pass-contract.md`; read absent bodies with `make-docs resource read make-docs://system/contract/guide-contract.md` or `make-docs://system/contract/coverage-pass-contract.md`.
9
+ - For testing, use valid local `.make-docs/system/contracts/naive-uat-contract.md` and `.make-docs/system/references/naive-uat-workflow.md`; read absent bodies by `make-docs://system/contract/naive-uat-contract.md` or `make-docs://system/reference/naive-uat-workflow.md` with `make-docs resource read`.
10
+ - For configuration and layout migration, use `.make-docs/system/references/path-and-link-hygiene.md` or `make-docs://system/reference/path-and-link-hygiene.md` with `make-docs resource read`.
11
+ - All Make Docs installation, operation, and recovery state belongs in the global Make Docs Store through the CLI. Project knowledge, work status, and backup copies remain local content.
12
+ - Missing CLI or failed optional capture does not block ordinary content work. Report unavailable capture without direct Store writes, queued writes, local operational fallback, or false success. Required CLI operation records remain mandatory.
13
+ <!-- make-docs:end -->
@@ -1,9 +1,13 @@
1
+ <!-- make-docs:begin -->
1
2
  # Document Assets Router
2
3
 
3
- This router describes the target `docs/assets/` document-resource namespace.
4
-
5
- - Archive records belong in `docs/assets/archive/`.
6
- - History records belong in `docs/assets/history/`; read `docs/assets/references/history-record-contract.md` and `docs/assets/templates/history-record.md` before writing.
7
- - Reusable prompts, references, and templates belong in `docs/assets/prompts/`, `docs/assets/references/`, and `docs/assets/templates/`.
8
- - make-docs runtime state does not belong under `docs/assets/`; canonical state lives at `.make-docs/manifest.json` and `.make-docs/conflicts/<run-id>/`.
9
- - Do not create `docs/assets/config/`, `docs/assets/state/`, `docs/assets/manifest.json`, or `docs/assets/conflicts/`.
4
+ - Shared, non-authoritative material uses `docs/assets/project/`. Audience assets use `docs/assets/<persona-slug>/`; audience testing uses its `testing/` child.
5
+ - Defaults are `user` and `maintainer`. Either role can be human or agent. Merge valid `.make-docs/config.yaml` Personas with those defaults; `project` is reserved shared material. Do not infer an audience from the executor.
6
+ - Create only paths needed by actual content. Managed instruction files belong at this root only, for the harness files declared in the `docs/` router.
7
+ - Archives and history use `.make-docs/archive/`. Old Library, artifact, archive, and Playbook families require reviewed migration; no new Playbook or Protocol assets are supported.
8
+ - For guide work, use valid local `.make-docs/system/contracts/guide-contract.md` and `.make-docs/system/contracts/coverage-pass-contract.md`; read absent bodies with `make-docs resource read make-docs://system/contract/guide-contract.md` or `make-docs://system/contract/coverage-pass-contract.md`.
9
+ - For testing, use valid local `.make-docs/system/contracts/naive-uat-contract.md` and `.make-docs/system/references/naive-uat-workflow.md`; read absent bodies by `make-docs://system/contract/naive-uat-contract.md` or `make-docs://system/reference/naive-uat-workflow.md` with `make-docs resource read`.
10
+ - For configuration and layout migration, use `.make-docs/system/references/path-and-link-hygiene.md` or `make-docs://system/reference/path-and-link-hygiene.md` with `make-docs resource read`.
11
+ - All Make Docs installation, operation, and recovery state belongs in the global Make Docs Store through the CLI. Project knowledge, work status, and backup copies remain local content.
12
+ - Missing CLI or failed optional capture does not block ordinary content work. Report unavailable capture without direct Store writes, queued writes, local operational fallback, or false success. Required CLI operation records remain mandatory.
13
+ <!-- make-docs:end -->
@@ -1,3 +1,4 @@
1
+ <!-- make-docs:begin -->
1
2
  # Designs Router
2
3
 
3
4
  This directory is an output target for design docs.
@@ -12,10 +13,14 @@ Pattern: `YYYY-MM-DD-<slug>.md`
12
13
 
13
14
  ## Agent Instructions
14
15
 
15
- - Before writing, read `docs/assets/references/design-workflow.md`, `docs/assets/references/design-contract.md`, and `docs/assets/templates/design.md`.
16
- - Use `docs/assets/references/design-contract.md` as the authority for lineage, required headings, and follow-on links.
16
+ - Before writing, use a valid local `.make-docs/system/references/design-workflow.md` body or, when it is absent, run `make-docs resource read make-docs://system/reference/design-workflow.md`; use a valid local `.make-docs/system/contracts/design-contract.md` body or run `make-docs resource read make-docs://system/contract/design-contract.md`; and use a valid local `.make-docs/system/templates/design.md` body or run `make-docs resource read make-docs://system/template/design.md`.
17
+ - For a new or materially updated governed design, also read `.make-docs/system/contracts/human-experience-contract.md`, `.make-docs/system/references/human-experience.md`, and `.make-docs/system/references/lifecycle.md`. When a valid local body is absent, use its matching `make-docs://system/contract/human-experience-contract.md`, `make-docs://system/reference/human-experience.md`, or `make-docs://system/reference/lifecycle.md` URI.
18
+ - When a performance candidate exists, use the `performance-evidence` catalog workflow. Load `.make-docs/system/contracts/performance-evidence-governance.md`, or read `make-docs://system/contract/performance-evidence-governance.md` when the local body is absent. Under the same condition, load `.make-docs/system/prompts/performance-coverage.prompt.md` and `.make-docs/system/templates/performance-evidence-profile.md`, or read `make-docs://system/prompt/performance-coverage.prompt.md` and `make-docs://system/template/performance-evidence-profile.md` when a local body is absent. Do not load the prompt or template otherwise.
19
+ - Use `.make-docs/system/contracts/design-contract.md` or its `make-docs://system/contract/design-contract.md` fallback as the authority for lineage, required headings, and follow-on links.
17
20
  - Always apply date-slug naming.
18
21
  - Do not backdate designs — use today's date.
19
22
  - Designs are living documents — update them when decisions change.
23
+ - Use `docs/designs/2026-06-25-v2-documentation-asset-ia-hard-move.md` as the superseding authority for v2 asset-IA path assumptions in earlier designs. Preserve old path text only when it is explicitly historical lineage.
20
24
  - Link to related plans, PRD docs, or work items where relevant.
21
- - Archived designs live in `docs/assets/archive/designs/`; never archive unless the user explicitly asks. See `docs/assets/archive/AGENTS.md`.
25
+ - Archived designs live in `.make-docs/archive/designs/`. Before first use, run `make-docs project surface ensure archive`. Never archive unless the user explicitly asks.
26
+ <!-- make-docs:end -->
@@ -1,3 +1,4 @@
1
+ <!-- make-docs:begin -->
1
2
  # Designs Router
2
3
 
3
4
  This directory is an output target for design docs.
@@ -12,10 +13,14 @@ Pattern: `YYYY-MM-DD-<slug>.md`
12
13
 
13
14
  ## Agent Instructions
14
15
 
15
- - Before writing, read `docs/assets/references/design-workflow.md`, `docs/assets/references/design-contract.md`, and `docs/assets/templates/design.md`.
16
- - Use `docs/assets/references/design-contract.md` as the authority for lineage, required headings, and follow-on links.
16
+ - Before writing, use a valid local `.make-docs/system/references/design-workflow.md` body or, when it is absent, run `make-docs resource read make-docs://system/reference/design-workflow.md`; use a valid local `.make-docs/system/contracts/design-contract.md` body or run `make-docs resource read make-docs://system/contract/design-contract.md`; and use a valid local `.make-docs/system/templates/design.md` body or run `make-docs resource read make-docs://system/template/design.md`.
17
+ - For a new or materially updated governed design, also read `.make-docs/system/contracts/human-experience-contract.md`, `.make-docs/system/references/human-experience.md`, and `.make-docs/system/references/lifecycle.md`. When a valid local body is absent, use its matching `make-docs://system/contract/human-experience-contract.md`, `make-docs://system/reference/human-experience.md`, or `make-docs://system/reference/lifecycle.md` URI.
18
+ - When a performance candidate exists, use the `performance-evidence` catalog workflow. Load `.make-docs/system/contracts/performance-evidence-governance.md`, or read `make-docs://system/contract/performance-evidence-governance.md` when the local body is absent. Under the same condition, load `.make-docs/system/prompts/performance-coverage.prompt.md` and `.make-docs/system/templates/performance-evidence-profile.md`, or read `make-docs://system/prompt/performance-coverage.prompt.md` and `make-docs://system/template/performance-evidence-profile.md` when a local body is absent. Do not load the prompt or template otherwise.
19
+ - Use `.make-docs/system/contracts/design-contract.md` or its `make-docs://system/contract/design-contract.md` fallback as the authority for lineage, required headings, and follow-on links.
17
20
  - Always apply date-slug naming.
18
21
  - Do not backdate designs — use today's date.
19
22
  - Designs are living documents — update them when decisions change.
23
+ - Use `docs/designs/2026-06-25-v2-documentation-asset-ia-hard-move.md` as the superseding authority for v2 asset-IA path assumptions in earlier designs. Preserve old path text only when it is explicitly historical lineage.
20
24
  - Link to related plans, PRD docs, or work items where relevant.
21
- - Archived designs live in `docs/assets/archive/designs/`; never archive unless the user explicitly asks. See `docs/assets/archive/AGENTS.md`.
25
+ - Archived designs live in `.make-docs/archive/designs/`. Before first use, run `make-docs project surface ensure archive`. Never archive unless the user explicitly asks.
26
+ <!-- make-docs:end -->