@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
package/dist/index.js CHANGED
@@ -1,48 +1,1140 @@
1
1
  #!/usr/bin/env node
2
+ import {
3
+ classifyCompatibilityState,
4
+ formatCompatibilityClassification,
5
+ importLegacyInstallationState,
6
+ previewLegacyInstallationState,
7
+ scopeCompatibilityToInstallPlan
8
+ } from "./chunk-BENO4IH5.js";
9
+ import {
10
+ Checkpoint9ReceiptProjectionError,
11
+ MigrationSafetyError,
12
+ createExecutionContext,
13
+ executeInstallPlanMigration,
14
+ executeStoreCheckpoint9Migration,
15
+ getInstallPlanMigrationReviewBlock,
16
+ getOperation,
17
+ hasOperation,
18
+ invokeOperation,
19
+ listOperations,
20
+ operationCliPath,
21
+ operationCliProjection,
22
+ resolveCliOperationLaunch,
23
+ serializeOperationError
24
+ } from "./chunk-LVQSJF63.js";
2
25
  import {
3
26
  runBackupCommand
4
- } from "./chunk-QRFH4J6H.js";
27
+ } from "./chunk-GNP6HRVP.js";
28
+ import "./chunk-G5EF63GG.js";
29
+ import {
30
+ OperationError,
31
+ listLifecycleRuns,
32
+ loadGlobalConfig,
33
+ previewStoreCompatibilityBridge,
34
+ resolveProjectIdentity,
35
+ writeGlobalConfig
36
+ } from "./chunk-3BAJQXGH.js";
37
+ import {
38
+ COMPLETE_PROJECT_CAPABILITIES,
39
+ describeHarnessSupport,
40
+ resolveUnifiedSetupState
41
+ } from "./chunk-LQ5NSWCJ.js";
5
42
  import {
6
43
  applyInstallPlan,
44
+ createDefaultMakeDocsConfig,
7
45
  findReviewableManagedFileConflicts,
8
- planInstall
9
- } from "./chunk-HP3HBG7F.js";
46
+ getConfigRenderingLabels,
47
+ getDocumentKindLabel,
48
+ loadMakeDocsConfigOrThrow,
49
+ planInstall,
50
+ planProjectHarnessIntegrationWrite,
51
+ registerSkillAdoptionRecovery
52
+ } from "./chunk-64CTKJO7.js";
53
+ import "./chunk-HJYIQTMD.js";
10
54
  import {
11
55
  Bt,
12
- CAPABILITIES,
13
- CAPABILITY_DEPENDENCIES,
14
56
  Ct,
15
- HARNESSES,
16
57
  Jt,
17
58
  Lt,
18
59
  Lt2,
19
- MANIFEST_RELATIVE_PATH,
20
- PACKAGE_ROOT,
21
60
  Rt,
22
61
  U,
23
62
  Vt,
24
63
  W,
25
64
  Wt,
65
+ h,
66
+ q,
67
+ te,
68
+ x
69
+ } from "./chunk-Z5K4FHYP.js";
70
+ import {
71
+ HARNESS_CALLER_IDENTITY_ARG,
72
+ HARNESS_CALLER_IDENTITY_ENV,
73
+ HARNESS_CALLER_REFERENCE_ARG,
74
+ encodeHarnessCallerIdentity,
75
+ parseHarnessCallerIdentity,
76
+ parseHarnessCallerIdentityArgument,
77
+ parseHarnessCallerReference,
78
+ sha256,
79
+ verifyMakeDocsExecutable
80
+ } from "./chunk-LRVV7UDD.js";
81
+ import {
82
+ CAPABILITIES,
83
+ CAPABILITY_DEPENDENCIES,
84
+ HARNESSES,
85
+ PACKAGE_ROOT,
86
+ PROJECT_RESOURCE_TYPES,
87
+ applySkillRegistrySelectionMetadata,
88
+ classifyStoreCheckpoint9State,
26
89
  cloneSelections,
27
90
  defaultSelections,
91
+ ensureParentDir,
92
+ formatAgenticSkillFileRole,
28
93
  formatInlineList,
29
94
  getRecommendedSkillChoices,
30
95
  getSkillRegistryNames,
31
- h,
32
96
  hasEffectiveCapabilities,
97
+ loadEffectiveSkillRegistry,
33
98
  loadManifest,
34
- loadSkillRegistry,
35
- q,
99
+ loadSqliteDriver,
100
+ readInstallationStatus,
36
101
  readPackageMeta,
102
+ recoverInstallationOperation,
37
103
  resolveInstallProfile,
38
- te,
39
- x
40
- } from "./chunk-WM3OXYTW.js";
104
+ resolveStoreRoot,
105
+ reviewCompletedRemovalHandoff,
106
+ validateAndMigrateManifest,
107
+ withStoreDatabase,
108
+ writeTextFile
109
+ } from "./chunk-MXBHCHSM.js";
110
+ import "./chunk-D4HDZEJT.js";
41
111
 
42
112
  // src/cli.ts
43
- import path from "path";
113
+ import { existsSync as existsSync2, readdirSync, realpathSync } from "fs";
114
+ import path4 from "path";
44
115
  import { stdin as input, stdout as output } from "process";
45
116
 
117
+ // src/run/cli.ts
118
+ import { existsSync, readFileSync } from "fs";
119
+ import path from "path";
120
+
121
+ // src/operations/cli-options.ts
122
+ var BOOLEAN_FLAGS = [
123
+ "json",
124
+ "run",
125
+ "print-only",
126
+ "write",
127
+ "review-required",
128
+ "no-review-required",
129
+ "allow-unattended",
130
+ "non-interactive",
131
+ "symlink-available",
132
+ "no-symlink-available",
133
+ "reviewed-overwrite",
134
+ "backup-snapshot-reviewed",
135
+ "acknowledge",
136
+ "present",
137
+ "migrate",
138
+ "unattended",
139
+ "parallel-children-reviewed",
140
+ "overwrite",
141
+ "adopt-project",
142
+ // `--last` selects the project's most recent run at every `--run-id`
143
+ // acceptor (W18 R12 P3; PRD 39 R-RUNID-1).
144
+ "last"
145
+ ];
146
+ var ARRAY_FLAGS = [
147
+ "validation-command",
148
+ "changed",
149
+ "requires-capability",
150
+ "prefers-capability",
151
+ "output-surface",
152
+ "resume-hint",
153
+ "evidence-ref",
154
+ "output-ref",
155
+ "source",
156
+ "support-evidence-ref",
157
+ "precondition"
158
+ ];
159
+ function parseOperationOptions(argv) {
160
+ const positionals = [];
161
+ const values = {};
162
+ const arrays = {};
163
+ const booleans = /* @__PURE__ */ new Set();
164
+ for (let index = 0; index < argv.length; index += 1) {
165
+ const arg = argv[index];
166
+ if (!arg.startsWith("--")) {
167
+ positionals.push(arg);
168
+ continue;
169
+ }
170
+ const key = arg.slice(2);
171
+ if (BOOLEAN_FLAGS.includes(key)) {
172
+ booleans.add(key);
173
+ continue;
174
+ }
175
+ const next = argv[index + 1];
176
+ if (!next || next.startsWith("--")) {
177
+ throw new OperationError(`\`${arg}\` requires a value.`);
178
+ }
179
+ index += 1;
180
+ if (ARRAY_FLAGS.includes(key)) {
181
+ arrays[key] = [...arrays[key] ?? [], next];
182
+ } else {
183
+ values[key] = next;
184
+ }
185
+ }
186
+ return { positionals, values, arrays, booleans };
187
+ }
188
+ function printJson(value) {
189
+ process.stdout.write(`${JSON.stringify(value, null, 2)}
190
+ `);
191
+ }
192
+ function requiredPositionals(options, operation) {
193
+ if (options.positionals.length === 0) {
194
+ throw new OperationError(`\`${operation}\` requires a target argument.`);
195
+ }
196
+ return options.positionals;
197
+ }
198
+ function requiredValue(options, key, operation) {
199
+ const value = options.values[key];
200
+ if (!value) {
201
+ throw new OperationError(`\`${operation}\` requires --${key}.`);
202
+ }
203
+ return value;
204
+ }
205
+
206
+ // src/run/render.ts
207
+ function resolveRunRenderMode(input2) {
208
+ if (input2.jsonFlag || !input2.isTty) {
209
+ return "json";
210
+ }
211
+ return "text";
212
+ }
213
+ function renderRunOperationText(id, value) {
214
+ const renderer = TEXT_RENDERERS[id] ?? genericRenderer;
215
+ try {
216
+ return renderer(value);
217
+ } catch {
218
+ return null;
219
+ }
220
+ }
221
+ function asRecord(value) {
222
+ return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
223
+ }
224
+ function asArray(value) {
225
+ return Array.isArray(value) ? value : [];
226
+ }
227
+ function recordEntries(value) {
228
+ return asArray(value).flatMap((entry) => {
229
+ const record = asRecord(entry);
230
+ return record ? [record] : [];
231
+ });
232
+ }
233
+ function text(record, key) {
234
+ const value = record?.[key];
235
+ return typeof value === "string" ? value : null;
236
+ }
237
+ function stringList(record, key) {
238
+ return asArray(record?.[key]).filter((item) => typeof item === "string");
239
+ }
240
+ function renderPrdAuthorityValidation(value) {
241
+ const report = asRecord(value);
242
+ if (!report) {
243
+ return null;
244
+ }
245
+ const diagnostics = recordEntries(report.diagnostics);
246
+ const lines = [
247
+ `PRD authority validation: ${text(report, "status") ?? "unknown"} (${String(report.prdFilesScanned ?? "?")} PRD files, ${diagnostics.length} errors).`
248
+ ];
249
+ for (const diagnostic of diagnostics) {
250
+ lines.push(
251
+ `${text(diagnostic, "code") ?? "PRD-AUTH-?"} ${text(diagnostic, "path") ?? "?"}:${String(diagnostic.line ?? "?")} ${text(diagnostic, "message") ?? "Validation error."}`,
252
+ ` Fix: ${text(diagnostic, "remediation") ?? "Repair the active PRD authority."}`
253
+ );
254
+ }
255
+ return lines;
256
+ }
257
+ function renderPerformanceEvidenceValidation(value) {
258
+ const report = asRecord(value);
259
+ if (!report) return null;
260
+ const diagnostics = recordEntries(report.diagnostics);
261
+ const catalog = asRecord(report.catalog);
262
+ const lines = [
263
+ `Performance Evidence validation: ${text(report, "status") ?? "unknown"} (${String(report.profileCount ?? "?")} profiles, ${String(report.candidateCount ?? "?")} candidates, ${diagnostics.length} diagnostics).`,
264
+ `Rule catalog: ${text(catalog, "id") ?? "unknown"} (${String(catalog?.ruleCount ?? "?")} rules).`
265
+ ];
266
+ const proofState = text(report, "proofState");
267
+ if (proofState) lines.push(`Proof state: ${proofState}.`);
268
+ for (const entry of diagnostics) {
269
+ lines.push(
270
+ `${text(entry, "code") ?? "PERF-VAL-?"} ${text(entry, "path") ?? "?"}:${String(entry.line ?? "?")} ${text(entry, "message") ?? "Validation issue."}`,
271
+ ` Reason: ${text(entry, "reason") ?? "No reason was recorded."}`,
272
+ ` Next: ${text(entry, "remediation") ?? "Review the Performance Evidence authority."}`
273
+ );
274
+ }
275
+ lines.push("No benchmark ran. No project file changed. This result does not authorize a run or retry.");
276
+ return lines;
277
+ }
278
+ function renderBacklogSnapshot(value) {
279
+ const snapshot = asRecord(value);
280
+ const counts = asRecord(snapshot?.recordCounts);
281
+ const capabilities = asRecord(snapshot?.capabilities);
282
+ if (!snapshot || !counts || !capabilities) return null;
283
+ const records = recordEntries(snapshot.records);
284
+ const diagnostics = recordEntries(snapshot.diagnostics);
285
+ const partial = records.filter((record) => text(asRecord(record.sourceShape), "state") === "partial").length;
286
+ const unsupported = records.filter((record) => text(asRecord(record.sourceShape), "state") === "unsupported").length;
287
+ const git = asRecord(capabilities.git);
288
+ const lines = [
289
+ `Backlog snapshot: ${String(counts.found ?? "?")} records found (${String(counts.live ?? "?")} live, ${String(counts.archived ?? "?")} archived).`,
290
+ `Detail: ${records.length - partial - unsupported} supported, ${partial} partial, ${unsupported} inventory only.`
291
+ ];
292
+ const gitState = text(git, "state") ?? "unknown";
293
+ if (gitState !== "available") {
294
+ lines.push(`Limit: Git evidence is ${gitState}. Record facts remain available. Last-updated values use the stated fallback.`);
295
+ }
296
+ if (diagnostics.length > 0) {
297
+ lines.push(`${diagnostics.length} diagnostic${diagnostics.length === 1 ? "" : "s"} need review. Use --json for exact evidence and safe next actions.`);
298
+ } else {
299
+ lines.push("No snapshot diagnostics need review. Use --json for exact evidence.");
300
+ }
301
+ return lines;
302
+ }
303
+ var TEXT_RENDERERS = {
304
+ "prd.authority.validate": renderPrdAuthorityValidation,
305
+ "performance.evidence.validate": renderPerformanceEvidenceValidation,
306
+ "work.backlog.snapshot": renderBacklogSnapshot
307
+ };
308
+ function genericRenderer(value) {
309
+ const record = asRecord(value);
310
+ const lines = stringList(record, "lines");
311
+ return record && lines.length > 0 ? lines : null;
312
+ }
313
+
314
+ // src/run/cli.ts
315
+ var RUN_CLI_SPELLINGS = {};
316
+ var operationPath = operationCliPath;
317
+ function defaultRepoRoot() {
318
+ const start = path.resolve(".");
319
+ let current = start;
320
+ while (true) {
321
+ if (existsSync(path.join(current, ".make-docs", "config.yaml"))) {
322
+ return current;
323
+ }
324
+ const parent = path.dirname(current);
325
+ if (parent === current) {
326
+ return start;
327
+ }
328
+ current = parent;
329
+ }
330
+ }
331
+ function resolveRepoRoot(options) {
332
+ const explicit = options.values["repo-root"];
333
+ return explicit ? path.resolve(explicit) : defaultRepoRoot();
334
+ }
335
+ function optionalPathValue(options, key, inputKey) {
336
+ const value = options.values[key];
337
+ return value ? { [inputKey]: path.resolve(value) } : {};
338
+ }
339
+ function resolveLifecycleRunIdOption(options, operation) {
340
+ const last = options.booleans.has("last");
341
+ const runId = options.values["run-id"];
342
+ if (last && runId) {
343
+ throw new OperationError("`--last` cannot be combined with `--run-id`; pass one selector.");
344
+ }
345
+ if (!last && !runId) {
346
+ throw new OperationError(`\`${operation}\` requires --run-id (or --last).`);
347
+ }
348
+ const repoRoot = resolveRepoRoot(options);
349
+ const identity = resolveProjectIdentity(repoRoot);
350
+ if (identity.status !== "resolved") {
351
+ if (last) {
352
+ throw new OperationError("`--last` requires a repository with a configured project identifier.");
353
+ }
354
+ return runId;
355
+ }
356
+ let runs;
357
+ try {
358
+ runs = withStoreDatabase(
359
+ resolveStoreRoot(options.values["store-root"] ? { storeRoot: options.values["store-root"] } : {}),
360
+ (db) => listLifecycleRuns(db, identity.projectId)
361
+ );
362
+ } catch (error) {
363
+ if (!last) return runId;
364
+ throw error;
365
+ }
366
+ if (last) {
367
+ const latest = [...runs].sort(
368
+ (left, right) => left.startedAt === right.startedAt ? left.runId.localeCompare(right.runId) : left.startedAt.localeCompare(right.startedAt)
369
+ ).pop();
370
+ if (!latest) {
371
+ throw new OperationError(
372
+ "`--last` found no lifecycle runs for this project; start one with `make-docs run lifecycle start`."
373
+ );
374
+ }
375
+ return latest.runId;
376
+ }
377
+ if (runs.some((run) => run.runId === runId)) return runId;
378
+ const candidates = runs.map((run) => run.runId).filter((candidate) => candidate.startsWith(runId)).sort();
379
+ if (candidates.length === 1) return candidates[0];
380
+ if (candidates.length > 1) {
381
+ throw new OperationError(
382
+ `Run id prefix \`${runId}\` is ambiguous; candidates:
383
+ ${candidates.map((candidate) => ` ${candidate}`).join("\n")}`
384
+ );
385
+ }
386
+ return runId;
387
+ }
388
+ function requiredPositiveInteger(options, key, operation) {
389
+ const raw = requiredValue(options, key, operation);
390
+ if (!/^[1-9][0-9]*$/.test(raw)) {
391
+ throw new OperationError(`\`${operation}\` requires --${key} to be a positive integer.`);
392
+ }
393
+ return Number(raw);
394
+ }
395
+ function optionalMetadata(options) {
396
+ const raw = options.values["metadata-json"];
397
+ return raw === void 0 ? void 0 : parseJsonPayload(raw, "metadata-json");
398
+ }
399
+ function lifecycleVersionedInput(options, operationId) {
400
+ const operation = operationPath(operationId);
401
+ return {
402
+ input: {
403
+ repoRoot: resolveRepoRoot(options),
404
+ ...optionalPathValue(options, "store-root", "storeRoot"),
405
+ runId: resolveLifecycleRunIdOption(options, operation),
406
+ expectedVersion: requiredPositiveInteger(options, "expected-version", operation)
407
+ }
408
+ };
409
+ }
410
+ function parseJsonPayload(raw, flag) {
411
+ const candidatePath = path.resolve(raw);
412
+ const text2 = existsSync(candidatePath) ? readFileSync(candidatePath, "utf8") : raw;
413
+ try {
414
+ return JSON.parse(text2);
415
+ } catch {
416
+ throw new OperationError(`\`--${flag}\` must be a path to a JSON file or inline JSON.`);
417
+ }
418
+ }
419
+ var RUN_CLI_ADAPTERS = {
420
+ "prd.authority.validate": (options) => ({
421
+ input: {
422
+ targetRoot: path.resolve(options.values["target-root"] ?? ".")
423
+ }
424
+ }),
425
+ "performance.evidence.validate": (options) => ({
426
+ input: {
427
+ targetRoot: path.resolve(options.values["target-root"] ?? ".")
428
+ }
429
+ }),
430
+ "lifecycle.start": (options) => ({
431
+ input: {
432
+ repoRoot: resolveRepoRoot(options),
433
+ ...optionalPathValue(options, "store-root", "storeRoot"),
434
+ runId: options.values["run-id"],
435
+ lifecycleStage: requiredValue(options, "stage", operationPath("lifecycle.start")),
436
+ checkpoint: options.values.checkpoint,
437
+ metadata: optionalMetadata(options)
438
+ }
439
+ }),
440
+ "lifecycle.show": (options) => ({
441
+ input: {
442
+ repoRoot: resolveRepoRoot(options),
443
+ ...optionalPathValue(options, "store-root", "storeRoot"),
444
+ runId: resolveLifecycleRunIdOption(options, operationPath("lifecycle.show"))
445
+ }
446
+ }),
447
+ "lifecycle.list": (options) => ({
448
+ input: {
449
+ repoRoot: resolveRepoRoot(options),
450
+ ...optionalPathValue(options, "store-root", "storeRoot")
451
+ }
452
+ }),
453
+ "lifecycle.checkpoint": (options) => ({
454
+ input: {
455
+ repoRoot: resolveRepoRoot(options),
456
+ ...optionalPathValue(options, "store-root", "storeRoot"),
457
+ runId: resolveLifecycleRunIdOption(options, operationPath("lifecycle.checkpoint")),
458
+ expectedVersion: requiredPositiveInteger(
459
+ options,
460
+ "expected-version",
461
+ operationPath("lifecycle.checkpoint")
462
+ ),
463
+ checkpoint: requiredValue(options, "checkpoint", operationPath("lifecycle.checkpoint")),
464
+ lifecycleStage: options.values.stage,
465
+ metadata: optionalMetadata(options)
466
+ }
467
+ }),
468
+ "lifecycle.pause": (options) => lifecycleVersionedInput(options, "lifecycle.pause"),
469
+ "lifecycle.resume": (options) => lifecycleVersionedInput(options, "lifecycle.resume"),
470
+ "lifecycle.attach-evidence": (options) => ({
471
+ input: {
472
+ ...lifecycleVersionedInput(options, "lifecycle.attach-evidence").input,
473
+ evidenceId: requiredValue(
474
+ options,
475
+ "evidence-id",
476
+ operationPath("lifecycle.attach-evidence")
477
+ ),
478
+ evidenceKind: requiredValue(options, "kind", operationPath("lifecycle.attach-evidence")),
479
+ projectPath: options.values["project-path"],
480
+ externalReference: options.values["external-reference"],
481
+ digest: options.values.digest
482
+ }
483
+ }),
484
+ "lifecycle.complete": (options) => lifecycleVersionedInput(options, "lifecycle.complete"),
485
+ "lifecycle.fail": (options) => lifecycleVersionedInput(options, "lifecycle.fail"),
486
+ "lifecycle.abandon": (options) => lifecycleVersionedInput(options, "lifecycle.abandon"),
487
+ "work.item.resolve": (options) => ({
488
+ input: {
489
+ target: requiredPositionals(options, operationPath("work.item.resolve")).join(" "),
490
+ ...optionalPathValue(options, "repo-root", "repoRoot")
491
+ }
492
+ }),
493
+ "work.evidence.record": (options) => ({
494
+ input: {
495
+ target: requiredPositionals(options, operationPath("work.evidence.record")).join(" "),
496
+ evidenceKind: requiredValue(options, "kind", operationPath("work.evidence.record")),
497
+ payload: parseJsonPayload(
498
+ requiredValue(options, "payload-json", operationPath("work.evidence.record")),
499
+ "payload-json"
500
+ ),
501
+ ...optionalPathValue(options, "repo-root", "repoRoot"),
502
+ ...optionalPathValue(options, "store-root", "storeRoot")
503
+ }
504
+ }),
505
+ "work.evidence.read": (options) => ({
506
+ input: {
507
+ target: requiredPositionals(options, operationPath("work.evidence.read")).join(" "),
508
+ ...optionalPathValue(options, "repo-root", "repoRoot"),
509
+ ...optionalPathValue(options, "store-root", "storeRoot")
510
+ }
511
+ }),
512
+ "work.backlog.snapshot": (options) => ({
513
+ input: {
514
+ targetRoot: path.resolve(
515
+ requiredValue(options, "target-root", operationPath("work.backlog.snapshot"))
516
+ )
517
+ }
518
+ }),
519
+ "work.backlog-cache.lookup": (options) => ({
520
+ input: {
521
+ targetRoot: path.resolve(
522
+ requiredValue(options, "target-root", operationPath("work.backlog-cache.lookup"))
523
+ ),
524
+ snapshot: parseJsonPayload(
525
+ requiredValue(options, "snapshot-json", operationPath("work.backlog-cache.lookup")),
526
+ "snapshot-json"
527
+ )
528
+ }
529
+ }),
530
+ "work.backlog-cache.write": (options) => ({
531
+ input: {
532
+ targetRoot: path.resolve(
533
+ requiredValue(options, "target-root", operationPath("work.backlog-cache.write"))
534
+ ),
535
+ snapshot: parseJsonPayload(
536
+ requiredValue(options, "snapshot-json", operationPath("work.backlog-cache.write")),
537
+ "snapshot-json"
538
+ ),
539
+ records: parseJsonPayload(
540
+ requiredValue(options, "records-json", operationPath("work.backlog-cache.write")),
541
+ "records-json"
542
+ )
543
+ }
544
+ })
545
+ };
546
+ function parseUatPayload(raw) {
547
+ const value = parseJsonPayload(raw, "payload-json");
548
+ if (value === null || typeof value !== "object" || Array.isArray(value)) throw new OperationError("UAT --payload-json must contain an object.");
549
+ return value;
550
+ }
551
+ for (const operation of listOperations().filter((entry) => entry.domain === "uat")) {
552
+ RUN_CLI_ADAPTERS[operation.id] = (options) => ({
553
+ input: options.values["payload-json"] === void 0 ? { ...optionalPathValue(options, "target-root", "targetRoot"), ...options.values.persona === void 0 ? {} : { persona: options.values.persona } } : parseUatPayload(options.values["payload-json"])
554
+ });
555
+ }
556
+ for (const operation of listOperations()) {
557
+ if (operation.status === "pending" && operation.cli.root === "run" && RUN_CLI_ADAPTERS[operation.id] === void 0) {
558
+ RUN_CLI_ADAPTERS[operation.id] = () => ({ input: {} });
559
+ }
560
+ }
561
+ var MAX_IDENTIFIER_SEGMENTS = 3;
562
+ function isDispatchablePath(id) {
563
+ return hasOperation(id) && operationCliProjection(getOperation(id).id).root === "run" || id in RUN_CLI_SPELLINGS;
564
+ }
565
+ function resolveRunOperationPath(argv) {
566
+ const leading = [];
567
+ for (const arg of argv) {
568
+ if (arg.startsWith("--") || leading.length === MAX_IDENTIFIER_SEGMENTS) {
569
+ break;
570
+ }
571
+ leading.push(arg);
572
+ }
573
+ for (let length = Math.min(MAX_IDENTIFIER_SEGMENTS, leading.length); length >= 2; length -= 1) {
574
+ const id = leading.slice(0, length).join(".");
575
+ if (isDispatchablePath(id)) {
576
+ return { id, rest: argv.slice(length) };
577
+ }
578
+ }
579
+ const attempted = leading.join(" ") || argv.join(" ");
580
+ const known = [
581
+ ...listOperations().filter((operation) => operation.cli.root === "run").map((operation) => operationPath(operation.id)),
582
+ ...Object.keys(RUN_CLI_SPELLINGS).map((spelling) => operationPath(spelling))
583
+ ].sort().map((pathName) => ` ${pathName}`).join("\n");
584
+ throw new OperationError(
585
+ `Unknown make-docs run operation: \`${attempted}\`. Valid operations:
586
+ ${known}`
587
+ );
588
+ }
589
+ function summaryTail(summary) {
590
+ return summary.replace(/^Operation `[^`]+`:\s*/, "");
591
+ }
592
+ function printRunHelp() {
593
+ const byDomain = /* @__PURE__ */ new Map();
594
+ for (const operation of listOperations().filter((entry) => entry.cli.root === "run")) {
595
+ const group = byDomain.get(operation.domain) ?? [];
596
+ group.push(operation);
597
+ byDomain.set(operation.domain, group);
598
+ }
599
+ const lines = [
600
+ "Usage: make-docs run <operation...> [options]",
601
+ "",
602
+ "Operation paths are the registry identifier segments (e.g. `run work item resolve`",
603
+ "invokes `work.item.resolve`)."
604
+ ];
605
+ for (const [domain, operations] of byDomain) {
606
+ lines.push("", `${domain}:`);
607
+ for (const operation of operations) {
608
+ const markers = [
609
+ ...operation.mutates === "write" ? ["[write]"] : [],
610
+ ...operation.status === "pending" ? [`[pending: lands with ${operation.pendingLineage}]`] : []
611
+ ];
612
+ const marker = markers.length > 0 ? ` ${markers.join(" ")}` : "";
613
+ lines.push(` ${operationPath(operation.id)}${marker}`);
614
+ lines.push(` ${summaryTail(operation.summary)}`);
615
+ }
616
+ for (const [spelling, entry] of Object.entries(RUN_CLI_SPELLINGS)) {
617
+ if (spelling.split(".", 1)[0] !== domain) {
618
+ continue;
619
+ }
620
+ lines.push(` ${operationPath(spelling)}`);
621
+ lines.push(` ${entry.summary}`);
622
+ }
623
+ }
624
+ lines.push("");
625
+ process.stdout.write(lines.join("\n"));
626
+ }
627
+ function adaptRunCliArgv(argv) {
628
+ const { id, rest } = resolveRunOperationPath(argv);
629
+ const spelling = RUN_CLI_SPELLINGS[id];
630
+ const operationId = spelling?.operation ?? id;
631
+ const adapter = RUN_CLI_ADAPTERS[operationId];
632
+ if (!adapter) {
633
+ throw new OperationError(
634
+ `Operation \`${operationId}\` is registered but has no \`run\` CLI adapter; add one in src/run/cli.ts.`
635
+ );
636
+ }
637
+ const options = parseOperationOptions(rest);
638
+ return {
639
+ id,
640
+ operationId,
641
+ options,
642
+ invocation: adapter(options),
643
+ spellingDryRun: spelling?.dryRun
644
+ };
645
+ }
646
+ async function runRunCommand(argv, seams = {}, launch = resolveCliOperationLaunch()) {
647
+ if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
648
+ printRunHelp();
649
+ return;
650
+ }
651
+ const { id, operationId, options, invocation: adapted, spellingDryRun } = adaptRunCliArgv(argv);
652
+ const { input: input2, context, artifact } = adapted;
653
+ const invocation = await invokeOperation(
654
+ operationId,
655
+ input2,
656
+ createExecutionContext({
657
+ surface: "cli",
658
+ route: launch.route,
659
+ callerIdentityRaw: launch.callerIdentityRaw,
660
+ callerReference: launch.callerReference,
661
+ writesAllowed: true,
662
+ // A declared spelling may supply the dry-run overlay.
663
+ dryRun: spellingDryRun ?? context?.dryRun ?? false,
664
+ approvals: context?.approvals ?? []
665
+ })
666
+ );
667
+ if (artifact) {
668
+ ensureParentDir(artifact.path);
669
+ writeTextFile(artifact.path, `${JSON.stringify(artifact.select(invocation.value), null, 2)}
670
+ `);
671
+ }
672
+ const mode = resolveRunRenderMode({
673
+ jsonFlag: options.booleans.has("json"),
674
+ isTty: seams.isTty ?? process.stdout.isTTY === true
675
+ });
676
+ if (mode === "text") {
677
+ const lines = renderRunOperationText(id, invocation.value);
678
+ if (lines) {
679
+ process.stdout.write(`${lines.join("\n")}
680
+ `);
681
+ setValidationExitCode(operationId, invocation.value);
682
+ return;
683
+ }
684
+ }
685
+ printJson(invocation.value);
686
+ setValidationExitCode(operationId, invocation.value);
687
+ }
688
+ function setValidationExitCode(operationId, value) {
689
+ if ((operationId === "prd.authority.validate" || operationId === "performance.evidence.validate") && value !== null && typeof value === "object" && !Array.isArray(value) && value.status !== "passed") {
690
+ process.exitCode = 1;
691
+ }
692
+ }
693
+
694
+ // src/run/root-operations.ts
695
+ import path2 from "path";
696
+ import { Buffer as Buffer2 } from "buffer";
697
+ function parseOptions(argv) {
698
+ const options = {
699
+ allowWrite: false,
700
+ dryRun: false,
701
+ approvals: [],
702
+ positionals: [],
703
+ present: /* @__PURE__ */ new Set()
704
+ };
705
+ const args = [...argv];
706
+ while (args.length > 0) {
707
+ const arg = args.shift();
708
+ if (arg === "--target" || arg === "--target-root") {
709
+ markPresent(options, "target", arg);
710
+ const value = args.shift();
711
+ if (!value) throw new OperationError(`\`${arg}\` requires a path.`);
712
+ options.targetRoot = path2.resolve(value);
713
+ } else if (arg === "--type") {
714
+ markPresent(options, "type", arg);
715
+ const value = args.shift();
716
+ if (!value || !["contract", "prompt", "reference", "template"].includes(value)) {
717
+ throw new OperationError(
718
+ "`--type` requires contract, prompt, reference, or template."
719
+ );
720
+ }
721
+ options.type = value;
722
+ } else if (arg === "--prefix") {
723
+ markPresent(options, "prefix", arg);
724
+ const value = args.shift();
725
+ if (!value) throw new OperationError("`--prefix` requires a path.");
726
+ options.prefix = value;
727
+ } else if (arg === "--origin") {
728
+ markPresent(options, "origin", arg);
729
+ const value = args.shift();
730
+ if (!value || !["effective", "local", "installed"].includes(value)) {
731
+ throw new OperationError("`--origin` requires effective, local, or installed.");
732
+ }
733
+ options.origin = value;
734
+ } else if (arg === "--format") {
735
+ markPresent(options, "format", arg);
736
+ const value = args.shift();
737
+ if (!value || !["table", "json", "raw"].includes(value)) {
738
+ throw new OperationError("`--format` requires table, json, or raw.");
739
+ }
740
+ options.format = value;
741
+ } else if (arg === "--allow-write") {
742
+ markPresent(options, "allow-write", arg);
743
+ options.allowWrite = true;
744
+ } else if (arg === "--dry-run") {
745
+ markPresent(options, "dry-run", arg);
746
+ options.dryRun = true;
747
+ } else if (arg === "--approve") {
748
+ const value = args.shift();
749
+ if (!value) throw new OperationError("`--approve` requires an approval name.");
750
+ options.approvals.push(value);
751
+ options.present.add("approve");
752
+ } else if (arg.startsWith("--")) {
753
+ throw new OperationError(`Unknown option: ${arg}`);
754
+ } else {
755
+ options.positionals.push(arg);
756
+ }
757
+ }
758
+ return options;
759
+ }
760
+ function markPresent(options, name, flag) {
761
+ if (options.present.has(name)) {
762
+ throw new OperationError(`Option \`${flag}\` can be given only once.`);
763
+ }
764
+ options.present.add(name);
765
+ }
766
+ function printJson2(value) {
767
+ process.stdout.write(`${JSON.stringify(value, null, 2)}
768
+ `);
769
+ }
770
+ function printResourceTable(value) {
771
+ const rows = ["TYPE URI ORIGIN STATE"];
772
+ for (const entry of value.resources) {
773
+ if (entry.result.ok) {
774
+ rows.push(
775
+ [
776
+ entry.result.value.identity.type,
777
+ entry.uri,
778
+ entry.result.value.origin,
779
+ entry.result.value.state
780
+ ].join(" ")
781
+ );
782
+ } else {
783
+ rows.push(["-", entry.uri, "-", entry.result.error.code].join(" "));
784
+ }
785
+ }
786
+ process.stdout.write(`${rows.join("\n")}
787
+ `);
788
+ }
789
+ function assertOptions(verb, options) {
790
+ const allowed = new Set(
791
+ verb === "list" ? ["target", "type", "prefix", "origin", "format"] : verb === "read" ? ["target", "origin", "format"] : ["target", "allow-write", "dry-run", "approve"]
792
+ );
793
+ for (const name of options.present) {
794
+ if (!allowed.has(name)) {
795
+ throw new OperationError(`Option \`--${name}\` is not valid for resource ${verb}.`);
796
+ }
797
+ }
798
+ if (verb === "list" && options.format && !["table", "json"].includes(options.format)) {
799
+ throw new OperationError("Resource list format must be table or json.");
800
+ }
801
+ if (verb === "read" && options.format && !["raw", "json"].includes(options.format)) {
802
+ throw new OperationError("Resource read format must be raw or json.");
803
+ }
804
+ }
805
+ async function runResourceCommand(argv, launch = resolveCliOperationLaunch()) {
806
+ if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
807
+ process.stdout.write(
808
+ [
809
+ "Usage:",
810
+ " make-docs resource list [--type <contract|prompt|reference|template>] [--prefix <path>] [--origin <effective|local|installed>] [--format table|json] [--target <dir>]",
811
+ " make-docs resource read <uri> [--origin <effective|local|installed>] [--format raw|json] [--target <dir>]",
812
+ " make-docs resource ensure <uri> --allow-write --approve resource-projection-write [--dry-run] [--target <dir>]",
813
+ ""
814
+ ].join("\n")
815
+ );
816
+ return;
817
+ }
818
+ const verb = argv[0];
819
+ if (verb !== "list" && verb !== "read" && verb !== "ensure") {
820
+ throw new OperationError(`Unknown make-docs resource command: \`${verb}\`.`);
821
+ }
822
+ const options = parseOptions(argv.slice(1));
823
+ assertOptions(verb, options);
824
+ const uri = options.positionals[0];
825
+ if (verb === "list" && options.positionals.length !== 0) {
826
+ throw new OperationError("`make-docs resource list` accepts no positional arguments.");
827
+ }
828
+ if (verb !== "list" && (options.positionals.length !== 1 || !uri)) {
829
+ throw new OperationError(`\`make-docs resource ${verb}\` requires exactly one resource URI.`);
830
+ }
831
+ const operationId = `resource.${verb}`;
832
+ const invocation = await invokeOperation(
833
+ operationId,
834
+ {
835
+ ...uri ? { uri } : {},
836
+ ...options.targetRoot ? { targetRoot: options.targetRoot } : {},
837
+ ...verb === "list" && options.type ? { type: options.type } : {},
838
+ ...verb === "list" && options.prefix ? { prefix: options.prefix } : {},
839
+ ...verb !== "ensure" && options.origin ? { origin: options.origin } : {}
840
+ },
841
+ createExecutionContext({
842
+ surface: "cli",
843
+ route: launch.route,
844
+ callerIdentityRaw: launch.callerIdentityRaw,
845
+ callerReference: launch.callerReference,
846
+ cwd: options.targetRoot,
847
+ writesAllowed: options.allowWrite,
848
+ dryRun: options.dryRun,
849
+ approvals: options.approvals
850
+ })
851
+ );
852
+ if (verb === "list") {
853
+ if ((options.format ?? "table") === "json") {
854
+ printJson2(invocation.value);
855
+ } else {
856
+ printResourceTable(invocation.value);
857
+ }
858
+ return;
859
+ }
860
+ if (verb === "read") {
861
+ if ((options.format ?? "raw") === "json") {
862
+ printJson2(invocation.value);
863
+ } else {
864
+ const value = invocation.value;
865
+ process.stdout.write(Buffer2.from(value.resource.content.data, "base64"));
866
+ }
867
+ return;
868
+ }
869
+ printJson2(invocation.value);
870
+ }
871
+ async function runProjectCommand(argv, launch = resolveCliOperationLaunch()) {
872
+ if (argv[0] === "layout" || argv[0] === "persona") {
873
+ await runProjectLayoutCommand(argv, launch);
874
+ return;
875
+ }
876
+ if (argv[0] === "state") {
877
+ await runProjectStateCommand(argv.slice(1), launch);
878
+ return;
879
+ }
880
+ if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
881
+ process.stdout.write(
882
+ [
883
+ "Usage: make-docs project surface ensure <archive|artifacts|assets>",
884
+ " make-docs project persona list [--target-root <path>] [--json]",
885
+ " make-docs project layout preview [--map <source>=<destination>] [--json]",
886
+ " make-docs project layout prepare --review <digest> --mode cli|manual [--map <source>=<destination>] [--json]",
887
+ " make-docs project layout apply|verify <operation-id> [--target-root <path>] [--json]",
888
+ " make-docs project state status [--target-root <path>] [--json]",
889
+ " make-docs project state recover <operation-id> --resume|--rollback [--dry-run] [--target-root <path>] [--json]",
890
+ "",
891
+ "Installation state belongs to the global Make Docs Store.",
892
+ "The ensure command checks Store installation evidence and configured routers",
893
+ "before it creates the selected on-demand directory. It reports the applied or",
894
+ "unchanged state, plan dispositions, receipt, and next check.",
895
+ "",
896
+ "State status reads the Store and reports pending work without changing files.",
897
+ "State recover requires an operation ID and exactly one recovery mode.",
898
+ "Use --resume to apply the remaining verified steps of a complete saved plan.",
899
+ "Use --rollback to restore verified prior file state. Changed files block recovery.",
900
+ "Add --dry-run to inspect recovery without applying changes.",
901
+ ""
902
+ ].join("\n")
903
+ );
904
+ return;
905
+ }
906
+ const [noun, verb, surface, ...rest] = argv;
907
+ if (noun !== "surface" || verb !== "ensure" || !surface || !["archive", "artifacts", "assets"].includes(surface)) {
908
+ throw new OperationError(
909
+ "Use `make-docs project surface ensure <archive|artifacts|assets>`."
910
+ );
911
+ }
912
+ let targetRoot;
913
+ let json = false;
914
+ let dryRun = false;
915
+ const seen = /* @__PURE__ */ new Set();
916
+ while (rest.length) {
917
+ const flag = rest.shift();
918
+ if (seen.has(flag)) throw new OperationError(`Option ${flag} can be given only once.`);
919
+ seen.add(flag);
920
+ if (flag === "--json") json = true;
921
+ else if (flag === "--dry-run") dryRun = true;
922
+ else if (flag === "--target-root") {
923
+ const value2 = rest.shift();
924
+ if (!value2 || value2.startsWith("--")) throw new OperationError("--target-root requires a path.");
925
+ targetRoot = path2.resolve(value2);
926
+ } else throw new OperationError(`Unexpected surface option: ${flag}.`);
927
+ }
928
+ const invocation = await invokeOperation(
929
+ "project.surface.ensure",
930
+ { surface, ...targetRoot ? { targetRoot } : {} },
931
+ createExecutionContext({
932
+ surface: "cli",
933
+ route: launch.route,
934
+ callerIdentityRaw: launch.callerIdentityRaw,
935
+ callerReference: launch.callerReference,
936
+ cwd: targetRoot,
937
+ writesAllowed: true,
938
+ dryRun
939
+ })
940
+ );
941
+ const value = invocation.value;
942
+ if (json) {
943
+ printJson2(value);
944
+ return;
945
+ }
946
+ const planLines = value.plan.actions.map(
947
+ (action) => `- ${action.disposition ?? action.type}: ${action.relativePath}`
948
+ );
949
+ const state = value.dryRun ? "planned only" : value.receipt ? "applied" : "unchanged";
950
+ const receipt = value.receipt?.receiptId ?? (value.dryRun ? "none (dry run)" : "none (no write)");
951
+ process.stdout.write(
952
+ [
953
+ `Target: ${value.targetRoot}`,
954
+ `Project surface: ${value.surface}`,
955
+ `Ensured root: ${value.ensuredPath}`,
956
+ `Content destination: ${value.contentDestination} (${value.contentDestinationExists ? "exists" : "not created; create it when content needs it"})`,
957
+ `State: ${state}`,
958
+ "Plan dispositions:",
959
+ ...planLines,
960
+ `Receipt: ${receipt}`,
961
+ "Next: Run `make-docs setup --yes --dry-run` to confirm that managed project files remain current.",
962
+ ""
963
+ ].join("\n")
964
+ );
965
+ }
966
+ async function runProjectLayoutCommand(argv, launch) {
967
+ const [noun, verb, ...args] = argv;
968
+ if (!verb || verb === "--help" || verb === "-h") {
969
+ process.stdout.write((noun === "persona" ? [
970
+ "Usage: make-docs project persona list [--target-root <path>] [--json]",
971
+ "Read effective project audiences. This command needs no Store and writes no files."
972
+ ] : [
973
+ "Usage: make-docs project layout preview [--map <source>=<destination>]",
974
+ " make-docs project layout prepare --review <digest> --mode cli|manual [--map <source>=<destination>]",
975
+ " make-docs project layout apply <operation-id>",
976
+ " make-docs project layout verify <operation-id>",
977
+ "All commands accept --target-root <path> and --json. Repeat --map for each reviewed choice.",
978
+ "Preview reads only. Prepare saves required Store state before any file move.",
979
+ "Apply moves a prepared CLI plan. Verify checks a prepared manual plan after you move files.",
980
+ "A pending plan blocks conflicting managed writes. Use project state status or recover to inspect it.",
981
+ "Manual-mode recovery resume checks completion; it does not perform the manual file moves."
982
+ ]).concat("").join("\n"));
983
+ return;
984
+ }
985
+ if (noun === "persona" ? verb !== "list" : !["preview", "prepare", "apply", "verify"].includes(verb)) throw new OperationError(`Unknown project ${noun} command: ${verb}.`);
986
+ let targetRoot, review, mode, operationId;
987
+ let json = false;
988
+ const mappings = [], seen = /* @__PURE__ */ new Set();
989
+ while (args.length) {
990
+ const arg = args.shift();
991
+ if (arg.startsWith("--") && arg !== "--map") {
992
+ if (seen.has(arg)) throw new OperationError(`Option ${arg} can be given only once.`);
993
+ seen.add(arg);
994
+ }
995
+ const value = () => {
996
+ const next = args.shift();
997
+ if (!next || next.startsWith("--")) throw new OperationError(`${arg} requires a value.`);
998
+ return next;
999
+ };
1000
+ if (arg === "--json") json = true;
1001
+ else if (arg === "--target-root") targetRoot = path2.resolve(value());
1002
+ else if (arg === "--map" && noun === "layout" && ["preview", "prepare"].includes(verb)) mappings.push(value());
1003
+ else if (arg === "--review" && noun === "layout" && verb === "prepare") review = value();
1004
+ else if (arg === "--mode" && noun === "layout" && verb === "prepare") mode = value();
1005
+ else if (!arg.startsWith("-") && noun === "layout" && ["apply", "verify"].includes(verb) && !operationId) operationId = arg;
1006
+ else throw new OperationError(`Unexpected argument for project ${noun} ${verb}: ${arg}.`);
1007
+ }
1008
+ if (verb === "prepare" && (!review || !["cli", "manual"].includes(mode ?? ""))) throw new OperationError("Preparation requires --review <digest> and --mode cli|manual.");
1009
+ if (["apply", "verify"].includes(verb) && !operationId) throw new OperationError(`${verb} requires one prepared operation ID.`);
1010
+ const invocation = await invokeOperation(`project.${noun}.${verb}`, {
1011
+ ...targetRoot ? { targetRoot } : {},
1012
+ ...noun === "layout" && ["preview", "prepare"].includes(verb) ? { mappings } : {},
1013
+ ...verb === "prepare" ? { review, mode } : {},
1014
+ ...operationId ? { operationId } : {}
1015
+ }, createExecutionContext({
1016
+ surface: "cli",
1017
+ route: launch.route,
1018
+ callerIdentityRaw: launch.callerIdentityRaw,
1019
+ callerReference: launch.callerReference,
1020
+ cwd: targetRoot,
1021
+ writesAllowed: noun === "layout" && verb !== "preview"
1022
+ }));
1023
+ const result = invocation.value;
1024
+ if (result.status === "blocked") process.exitCode = 1;
1025
+ if (json) {
1026
+ printJson2(result);
1027
+ return;
1028
+ }
1029
+ if (noun === "persona") {
1030
+ process.stdout.write([`Project: ${result.targetRoot}`, ...result.personas.map((persona) => `${persona.slug}: ${persona.label} (${persona.primitive}) \u2014 ${persona.description}`), "Read only. No Store or project files changed.", ""].join("\n"));
1031
+ return;
1032
+ }
1033
+ process.stdout.write([
1034
+ `Layout: ${result.status}`,
1035
+ ...result.targetRoot ? [`Project: ${result.targetRoot}`] : [],
1036
+ ...result.reviewDigest ? [`Review digest: ${result.reviewDigest}`] : [],
1037
+ ...result.operationId ? [`Operation: ${result.operationId}`] : [],
1038
+ ...(result.entries ?? []).filter((entry) => entry.disposition !== "preserve").map((entry) => `- ${entry.disposition}: ${entry.path}${entry.destination ? ` -> ${entry.destination}` : ""}`),
1039
+ ...result.linkEdits ? [`Link text edits: ${result.linkEdits.length}`] : [],
1040
+ ...result.linkChecks ? [`Unchanged link target checks: ${result.linkChecks.length}`] : [],
1041
+ ...(result.linkEdits ?? []).map((edit) => `- Link text in ${edit.destination}: ${edit.before} -> ${edit.after}`),
1042
+ ...(result.metadataEdits ?? []).map((edit) => `- Persona metadata in ${edit.destination ?? edit.source}: ${JSON.stringify(edit.before)} -> ${JSON.stringify(edit.after)}`),
1043
+ ...(result.instructions ?? []).map((instruction) => `- ${instruction.action}: ${instruction.source ? `${instruction.source} -> ` : ""}${instruction.path}${instruction.after.digest ? ` (SHA-256 ${instruction.after.digest})` : ""}`),
1044
+ ...(result.blockers ?? result.conflicts ?? []).map((blocker) => `Review: ${blocker}`),
1045
+ ...result.notice ? [result.notice, "Use --json to obtain the exact saved file bytes for manual writes."] : [],
1046
+ ...result.nextAction ? [`Next: ${result.nextAction}`] : [],
1047
+ ""
1048
+ ].join("\n"));
1049
+ }
1050
+ async function runProjectStateCommand(argv, launch) {
1051
+ const [verb, ...args] = argv;
1052
+ if (!verb || verb === "--help" || verb === "-h" || (verb === "status" || verb === "recover") && args.some((arg) => arg === "--help" || arg === "-h")) {
1053
+ process.stdout.write([
1054
+ "Usage: make-docs project state status [--target-root <path>] [--json]",
1055
+ " make-docs project state recover <operation-id> --resume|--rollback [--dry-run] [--target-root <path>] [--json]",
1056
+ "",
1057
+ "Installation state belongs to the global Make Docs Store.",
1058
+ "Status reads the Store and reports pending work without changing files.",
1059
+ "Recovery requires an operation ID and exactly one recovery mode.",
1060
+ "Use --resume to apply the remaining verified steps of a complete saved plan.",
1061
+ "Use --rollback to restore verified prior file state. Changed files block recovery.",
1062
+ "Add --dry-run to inspect recovery without applying changes.",
1063
+ "Use --help or -h on status or recover to read help without reading the Store or changing files.",
1064
+ ""
1065
+ ].join("\n"));
1066
+ return;
1067
+ }
1068
+ if (verb !== "status" && verb !== "recover") throw new OperationError(`Unknown project state command: ${verb}.`);
1069
+ let targetRoot;
1070
+ let mode;
1071
+ let dryRun = false;
1072
+ let json = false;
1073
+ let operationId;
1074
+ const seen = /* @__PURE__ */ new Set();
1075
+ while (args.length) {
1076
+ const arg = args.shift();
1077
+ if (arg.startsWith("--")) {
1078
+ if (seen.has(arg)) throw new OperationError(`Option ${arg} can be given only once.`);
1079
+ seen.add(arg);
1080
+ }
1081
+ if (arg === "--target-root") {
1082
+ const value2 = args.shift();
1083
+ if (!value2 || value2.startsWith("--")) throw new OperationError("--target-root requires a path.");
1084
+ targetRoot = path2.resolve(value2);
1085
+ } else if (arg === "--json") json = true;
1086
+ else if (arg === "--dry-run" && verb === "recover") dryRun = true;
1087
+ else if ((arg === "--resume" || arg === "--rollback") && verb === "recover") {
1088
+ if (mode) throw new OperationError("Recovery requires exactly one of --resume or --rollback.");
1089
+ mode = arg === "--resume" ? "resume" : "rollback";
1090
+ } else if (!arg.startsWith("--") && verb === "recover" && !operationId) operationId = arg;
1091
+ else throw new OperationError(`Unexpected argument for project state ${verb}: ${arg}.`);
1092
+ }
1093
+ if (verb === "recover" && (!operationId || !mode)) throw new OperationError("Recovery requires one operation ID and exactly one of --resume or --rollback.");
1094
+ const invocation = await invokeOperation(`project.state.${verb}`, {
1095
+ ...targetRoot ? { targetRoot } : {},
1096
+ ...verb === "recover" ? { operationId, mode } : {}
1097
+ }, createExecutionContext({
1098
+ surface: "cli",
1099
+ route: launch.route,
1100
+ callerIdentityRaw: launch.callerIdentityRaw,
1101
+ callerReference: launch.callerReference,
1102
+ cwd: targetRoot,
1103
+ writesAllowed: verb === "recover",
1104
+ dryRun
1105
+ }));
1106
+ if (json) {
1107
+ printJson2(invocation.value);
1108
+ return;
1109
+ }
1110
+ const value = invocation.value;
1111
+ const labels = {
1112
+ "ready": verb === "recover" ? "Recovery is ready for review." : "Make Docs installation state is ready.",
1113
+ "unregistered": "This checkout has no registered installation.",
1114
+ "ownership-unverified": "Installation ownership needs review.",
1115
+ "recovery-required": "An unfinished operation needs recovery.",
1116
+ "writer-active": "Another Make Docs writer is active.",
1117
+ "store-unavailable": "The Make Docs Store is unavailable.",
1118
+ "completed": "Recovery completed.",
1119
+ "rolled-back": "Recovery restored the prior state.",
1120
+ "blocked": "Recovery stopped to preserve changed files."
1121
+ };
1122
+ const state = String(value.status ?? value.code ?? "unknown");
1123
+ process.stdout.write([
1124
+ labels[state] ?? `State: ${state}`,
1125
+ ...value.projectId ? [`Project ID: ${String(value.projectId)}`] : [],
1126
+ ...value.checkoutId ? [`Checkout: ${String(value.checkoutId)}`] : [],
1127
+ ...value.installationVersion ? [`Installed version: ${String(value.installationVersion)}`] : [],
1128
+ ...value.pendingOperation ? [`Pending operation: ${JSON.stringify(value.pendingOperation)}`] : [],
1129
+ ...value.operationId ? [`Operation: ${String(value.operationId)}`] : [],
1130
+ ...value.dryRun ? ["Preview only. No files or Store records changed."] : [],
1131
+ ...Array.isArray(value.changes) ? value.changes.map((change) => `- ${change.path}: ${change.to}`) : [],
1132
+ ...Array.isArray(value.conflicts) ? value.conflicts.map((conflict) => `Review: ${String(conflict)}`) : [],
1133
+ ...value.nextAction ? [`Next: ${String(value.nextAction)}`] : state === "blocked" ? ["Next: Review the listed conflicts. Preserve current files."] : value.dryRun && state === "ready" ? ["Next: Review this preview before running the same recovery command without --dry-run."] : [],
1134
+ ""
1135
+ ].join("\n"));
1136
+ }
1137
+
46
1138
  // src/wizard.ts
47
1139
  import { styleText } from "util";
48
1140
  var CAPABILITY_METADATA = {
@@ -110,6 +1202,12 @@ var MANAGED_FILE_CONFLICT_GROUP_LABELS = {
110
1202
  routers: "Router files",
111
1203
  other: "Other managed files"
112
1204
  };
1205
+ var CAPABILITY_DOCUMENT_KIND_LABELS = {
1206
+ designs: "design",
1207
+ plans: "plan",
1208
+ prd: "prd",
1209
+ work: "work"
1210
+ };
113
1211
  function normalizeWizardSelections(selections) {
114
1212
  const next = cloneSelections(selections);
115
1213
  for (const capability of CAPABILITIES) {
@@ -134,7 +1232,8 @@ function getWizardOptionSelections(selections) {
134
1232
  return {
135
1233
  skills: selections.skills,
136
1234
  skillScope: selections.skillScope,
137
- selectedSkills: [...selections.selectedSkills].sort()
1235
+ selectedSkills: [...selections.selectedSkills].sort(),
1236
+ resourceProjection: [...selections.resourceProjection ?? []].sort()
138
1237
  };
139
1238
  }
140
1239
  function buildSkillSelectionState(options, skillChoices) {
@@ -142,10 +1241,16 @@ function buildSkillSelectionState(options, skillChoices) {
142
1241
  const selectedSkillNames = skillChoices.filter((skill) => selectedSkillSet.has(skill.name)).map((skill) => skill.name);
143
1242
  const promptOptions = skillChoices.map((skill) => ({
144
1243
  value: skill.name,
145
- label: skill.name,
146
- hint: skill.description,
1244
+ label: toTitleCase(skill.displayName),
1245
+ hint: "",
147
1246
  disabled: false,
148
- rowKind: "skill"
1247
+ rowKind: "skill",
1248
+ detailLines: [
1249
+ skill.description,
1250
+ "",
1251
+ `Purpose: ${formatSkillPurposeLabels(skill)}`,
1252
+ `Support: ${formatInlineList(skill.supportedHarnesses)}`
1253
+ ]
149
1254
  }));
150
1255
  return {
151
1256
  skills: skillChoices,
@@ -167,13 +1272,14 @@ function applyHarnessSelections(selections, selectedHarnesses) {
167
1272
  }
168
1273
  return next;
169
1274
  }
170
- function buildOptionsStepState(selections) {
1275
+ function buildOptionsStepState(selections, skillRegistry, skillsLocked = false) {
171
1276
  const options = getWizardOptionSelections(selections);
172
- const skillChoices = getRecommendedSkillChoices();
1277
+ const skillChoices = getRecommendedSkillChoices(skillRegistry);
173
1278
  return {
174
1279
  selections,
175
1280
  options,
176
1281
  skillSelection: buildSkillSelectionState(options, skillChoices),
1282
+ skillsLocked,
177
1283
  skillScopeOptions: [
178
1284
  {
179
1285
  value: "project",
@@ -193,20 +1299,22 @@ function applyWizardOptionSelections(selections, options) {
193
1299
  next.skills = options.skills;
194
1300
  next.skillScope = options.skillScope;
195
1301
  next.selectedSkills = options.skills ? Array.from(new Set(options.selectedSkills)).sort() : [];
1302
+ next.resourceProjection = Array.from(new Set(options.resourceProjection ?? [])).sort();
196
1303
  return next;
197
1304
  }
198
- function buildCapabilityChecklistState(selections) {
1305
+ function buildCapabilityChecklistState(selections, config = createDefaultMakeDocsConfig()) {
199
1306
  const normalizedSelections = normalizeWizardSelections(selections);
200
1307
  const profile = resolveInstallProfile(normalizedSelections);
201
1308
  const options = CAPABILITIES.map((capability) => {
202
1309
  const metadata = CAPABILITY_METADATA[capability];
1310
+ const label = getCapabilityLabel(config, capability);
203
1311
  const state = profile.capabilityState[capability];
204
1312
  const disabled = state.missingPrerequisites.length > 0;
205
1313
  const dependencyText = CAPABILITY_DEPENDENCIES[capability].length === 0 ? "No prerequisites" : `Requires ${formatInlineList(CAPABILITY_DEPENDENCIES[capability])}`;
206
1314
  const statusText = state.effectiveSelection ? "Selected" : disabled ? state.disabledReason ?? "Unavailable" : "Available";
207
1315
  return {
208
1316
  value: capability,
209
- label: metadata.label,
1317
+ label,
210
1318
  hint: disabled ? state.disabledReason ?? metadata.hint : metadata.hint,
211
1319
  disabled,
212
1320
  description: metadata.description,
@@ -223,7 +1331,7 @@ function buildCapabilityChecklistState(selections) {
223
1331
  )
224
1332
  };
225
1333
  }
226
- function renderWizardReviewSummary(selections) {
1334
+ function renderWizardReviewSummary(selections, config = createDefaultMakeDocsConfig(), harnessSupport = []) {
227
1335
  const normalizedSelections = normalizeWizardSelections(selections);
228
1336
  const profile = resolveInstallProfile(normalizedSelections);
229
1337
  const selectedHarnesses = getSelectedHarnesses(normalizedSelections);
@@ -233,32 +1341,60 @@ function renderWizardReviewSummary(selections) {
233
1341
  const selectedSkillSummary = normalizedSelections.selectedSkills.length > 0 ? formatInlineList(normalizedSelections.selectedSkills) : "none";
234
1342
  const skillsSummary = normalizedSelections.skills ? `Yes (${normalizedSelections.skillScope})` : "No";
235
1343
  return [
236
- "Document types",
1344
+ "Selection preview. No file change is approved here.",
1345
+ "Continue to build the exact computer and project review.",
1346
+ "",
1347
+ "This computer",
1348
+ ...harnessSupport.length > 0 ? harnessSupport.map((state) => `- ${describeHarnessSupport(state)}`) : ["- No machine changes selected"],
1349
+ "- Store-backed connection methods need separate machine approval",
1350
+ "",
1351
+ "This project",
1352
+ "Project surface",
237
1353
  ...CAPABILITIES.map((capability) => {
238
1354
  const state = profile.capabilityState[capability];
239
- const label = CAPABILITY_METADATA[capability].label;
1355
+ const label = getCapabilityLabel(config, capability);
240
1356
  const value = state.effectiveSelection ? "selected" : state.disabledReason ? `locked (${state.disabledReason})` : "off";
241
1357
  return `- ${label}: ${value}`;
242
1358
  }),
243
1359
  "",
244
- "Options",
245
1360
  `- Harnesses: ${harnessSummary}`,
246
1361
  `- ${OPTION_METADATA.skills.label}: ${skillsSummary}`,
247
- `- Selected skills: ${normalizedSelections.skills ? selectedSkillSummary : "n/a"}`
1362
+ `- Selected skills: ${normalizedSelections.skills ? selectedSkillSummary : "n/a"}`,
1363
+ `- Local resource projection: ${(normalizedSelections.resourceProjection ?? []).join(", ") || "none"}`,
1364
+ "- Resource provider reads need no Store access",
1365
+ "- Local copies reduce CLI dependence. They do not grant harness or Store access"
248
1366
  ].join("\n");
249
1367
  }
250
1368
  async function runSelectionWizard(options) {
251
1369
  return runSelectionWizardWithRenderer(createClackWizardRenderer(), options);
252
1370
  }
253
1371
  async function runSelectionWizardWithRenderer(renderer, options) {
254
- let selections = normalizeWizardSelections(options.initialSelections);
255
- let step = options.startStep ?? "capabilities";
1372
+ const state = resolveUnifiedSetupState({
1373
+ entry: options.projectState === "fresh" ? "setup" : "reconfigure",
1374
+ projectState: options.projectState ?? "current",
1375
+ selections: options.initialSelections,
1376
+ harnesses: options.harnessSupport,
1377
+ allowCapabilityExpansion: options.allowCapabilityExpansion
1378
+ });
1379
+ let selections = normalizeWizardSelections(state.selections);
1380
+ let step = options.startStep ?? (options.projectState === void 0 ? "capabilities" : "harnesses");
1381
+ const config = options.config ?? createDefaultMakeDocsConfig();
256
1382
  await renderer.beginSession?.(options.introTitle);
1383
+ await renderer.showProjectState?.(options.projectState ?? "current");
257
1384
  while (true) {
258
1385
  if (step === "capabilities") {
1386
+ if (options.projectState === "fresh") {
1387
+ selections = applyCapabilitySelections(
1388
+ selections,
1389
+ COMPLETE_PROJECT_CAPABILITIES
1390
+ );
1391
+ step = "harnesses";
1392
+ continue;
1393
+ }
259
1394
  const selectedCapabilities = await renderer.editCapabilities({
260
1395
  selections,
261
- checklist: buildCapabilityChecklistState(selections)
1396
+ checklist: buildCapabilityChecklistState(selections, config),
1397
+ config
262
1398
  });
263
1399
  if (!selectedCapabilities) {
264
1400
  return null;
@@ -273,40 +1409,66 @@ async function runSelectionWizardWithRenderer(renderer, options) {
273
1409
  options: HARNESSES.map((harness) => ({
274
1410
  value: harness,
275
1411
  label: HARNESS_METADATA[harness].label,
276
- hint: HARNESS_METADATA[harness].hint
1412
+ hint: [
1413
+ HARNESS_METADATA[harness].hint,
1414
+ options.harnessSupport?.find((state2) => state2.harness === harness) ? describeHarnessSupport(
1415
+ options.harnessSupport.find((state2) => state2.harness === harness)
1416
+ ) : void 0
1417
+ ].filter(Boolean).join(" \u2014 "),
1418
+ ...options.harnessSupport?.find((state2) => state2.harness === harness) ? {
1419
+ status: options.harnessSupport.find(
1420
+ (state2) => state2.harness === harness
1421
+ ).state
1422
+ } : {}
277
1423
  })),
278
1424
  selectedHarnesses: getSelectedHarnesses(selections)
279
1425
  });
280
1426
  if (!selectedHarnesses) {
281
1427
  return null;
282
1428
  }
283
- if (selectedHarnesses.length === 0) {
284
- continue;
285
- }
286
1429
  selections = applyHarnessSelections(selections, selectedHarnesses);
1430
+ if (options.afterHarnessSelection && !await options.afterHarnessSelection(selections)) {
1431
+ return null;
1432
+ }
287
1433
  step = "options";
288
1434
  continue;
289
1435
  }
290
1436
  if (step === "options") {
291
1437
  const nextOptions = await renderer.editOptions(
292
- buildOptionsStepState(selections)
1438
+ buildOptionsStepState(selections, options.skillRegistry, options.lockSkills)
293
1439
  );
294
1440
  if (!nextOptions) {
295
1441
  return null;
296
1442
  }
297
- selections = applyWizardOptionSelections(selections, nextOptions);
298
- step = "review";
299
- continue;
1443
+ selections = applyWizardOptionSelections(
1444
+ selections,
1445
+ options.lockSkills ? {
1446
+ ...nextOptions,
1447
+ skills: selections.skills,
1448
+ skillScope: selections.skillScope,
1449
+ selectedSkills: [...selections.selectedSkills]
1450
+ } : nextOptions
1451
+ );
1452
+ return normalizeWizardSelections(selections);
300
1453
  }
301
1454
  const reviewAction = await renderer.review({
302
1455
  selections,
303
1456
  profile: resolveInstallProfile(selections),
304
- summary: renderWizardReviewSummary(selections)
1457
+ summary: renderWizardReviewSummary(
1458
+ selections,
1459
+ config,
1460
+ options.harnessSupport
1461
+ ),
1462
+ allowCapabilityExpansion: state.allowCapabilityExpansion
305
1463
  });
306
1464
  if (reviewAction === "apply") {
307
1465
  return normalizeWizardSelections(selections);
308
1466
  }
309
1467
  if (reviewAction === "edit-capabilities") {
1468
+ if (!state.allowCapabilityExpansion) {
1469
+ step = "review";
1470
+ continue;
1471
+ }
310
1472
  step = "capabilities";
311
1473
  continue;
312
1474
  }
@@ -384,15 +1546,15 @@ async function promptForManagedFileConflictResolutions(conflicts) {
384
1546
  const resolution = await Jt({
385
1547
  message: `How should make-docs handle ${conflict.relativePath}?`,
386
1548
  withGuide: true,
387
- initialValue: "skip",
1549
+ initialValue: conflict.scope === "managed-block" ? "overwrite" : "skip",
388
1550
  options: [
389
1551
  {
390
1552
  value: "overwrite",
391
- label: "Overwrite"
1553
+ label: conflict.scope === "managed-block" ? "Reassert managed block" : "Overwrite"
392
1554
  },
393
1555
  {
394
1556
  value: "skip",
395
- label: "Skip"
1557
+ label: conflict.scope === "managed-block" ? "Keep local block" : "Skip"
396
1558
  }
397
1559
  ]
398
1560
  });
@@ -468,6 +1630,9 @@ function getManagedFileConflictGroupOrder(group) {
468
1630
  function getManagedFileConflictGroupLabel(group) {
469
1631
  return MANAGED_FILE_CONFLICT_GROUP_LABELS[group] ?? toTitleCase(group);
470
1632
  }
1633
+ function getCapabilityLabel(config, capability) {
1634
+ return getDocumentKindLabel(config, CAPABILITY_DOCUMENT_KIND_LABELS[capability]);
1635
+ }
471
1636
  function toTitleCase(value) {
472
1637
  return value.split(/[-_\s]+/).filter(Boolean).map((word) => `${word.slice(0, 1).toUpperCase()}${word.slice(1)}`).join(" ");
473
1638
  }
@@ -476,8 +1641,11 @@ function createClackWizardRenderer() {
476
1641
  beginSession(title) {
477
1642
  Wt(title);
478
1643
  },
1644
+ showProjectState(state) {
1645
+ Vt(`Project state: ${state}.`, "Project state");
1646
+ },
479
1647
  async editCapabilities(state) {
480
- return promptForCapabilities(state.selections);
1648
+ return promptForCapabilities(state.selections, state.config);
481
1649
  },
482
1650
  async editHarnesses(state) {
483
1651
  return promptForHarnesses(state.selections);
@@ -491,12 +1659,18 @@ function createClackWizardRenderer() {
491
1659
  message: "What would you like to do next?",
492
1660
  withGuide: true,
493
1661
  options: [
494
- { value: "apply", label: "Apply", hint: "Use this configuration" },
495
1662
  {
496
- value: "edit-capabilities",
497
- label: "Edit document types",
498
- hint: "Adjust managed document types"
1663
+ value: "apply",
1664
+ label: "Continue",
1665
+ hint: "Build the exact computer and project review. No files change yet."
499
1666
  },
1667
+ ...state.allowCapabilityExpansion ? [
1668
+ {
1669
+ value: "edit-capabilities",
1670
+ label: "Review project expansion",
1671
+ hint: "Change the current project document surface"
1672
+ }
1673
+ ] : [],
500
1674
  {
501
1675
  value: "edit-harnesses",
502
1676
  label: "Edit harnesses",
@@ -521,13 +1695,13 @@ function createClackWizardRenderer() {
521
1695
  }
522
1696
  };
523
1697
  }
524
- async function promptForCapabilities(selections) {
1698
+ async function promptForCapabilities(selections, config = createDefaultMakeDocsConfig()) {
525
1699
  const promptState = {
526
1700
  selections: normalizeWizardSelections(selections)
527
1701
  };
528
1702
  const prompt = new Lt({
529
- options: buildCapabilityChecklistState(promptState.selections).options,
530
- initialValues: buildCapabilityChecklistState(promptState.selections).selectedCapabilities,
1703
+ options: buildCapabilityChecklistState(promptState.selections, config).options,
1704
+ initialValues: buildCapabilityChecklistState(promptState.selections, config).selectedCapabilities,
531
1705
  required: true,
532
1706
  render() {
533
1707
  return renderCapabilitiesFrame(this, promptState.selections);
@@ -543,7 +1717,7 @@ async function promptForCapabilities(selections) {
543
1717
  selections,
544
1718
  prompt.value ?? []
545
1719
  );
546
- const checklist = buildCapabilityChecklistState(promptState.selections);
1720
+ const checklist = buildCapabilityChecklistState(promptState.selections, config);
547
1721
  prompt.options = checklist.options;
548
1722
  prompt.value = checklist.selectedCapabilities;
549
1723
  if (prompt.options[prompt.cursor]?.disabled) {
@@ -558,7 +1732,7 @@ async function promptForCapabilities(selections) {
558
1732
  if (Ct(result)) {
559
1733
  return null;
560
1734
  }
561
- return buildCapabilityChecklistState(promptState.selections).selectedCapabilities;
1735
+ return buildCapabilityChecklistState(promptState.selections, config).selectedCapabilities;
562
1736
  }
563
1737
  async function promptForHarnesses(selections) {
564
1738
  const result = await Lt2({
@@ -579,19 +1753,26 @@ async function promptForHarnesses(selections) {
579
1753
  }
580
1754
  async function promptForOptions(state) {
581
1755
  const { options, skillSelection, skillScopeOptions } = state;
582
- const skillsResult = await Rt({
583
- message: "Install agent skills?",
1756
+ const harnessLabels = getSelectedHarnesses(state.selections).map(
1757
+ (harness) => HARNESS_METADATA[harness].label
1758
+ );
1759
+ if (state.skillsLocked) {
1760
+ Vt(
1761
+ "This setup keeps the saved Skill selection. Use `make-docs setup skills` to change the enabled state, scope, source, or selected names.",
1762
+ "Skills"
1763
+ );
1764
+ }
1765
+ const skillsResult = state.skillsLocked ? options.skills : await Rt({
1766
+ message: `Install optional Skills for ${formatInlineList(harnessLabels)}? Skills guide agents. They do not grant Store access.`,
584
1767
  withGuide: true,
585
1768
  initialValue: options.skills,
586
1769
  active: "Yes",
587
1770
  inactive: "No"
588
1771
  });
589
- if (Ct(skillsResult)) {
590
- return null;
591
- }
1772
+ if (Ct(skillsResult)) return null;
592
1773
  let skillScope = options.skillScope;
593
1774
  let selectedSkills = options.selectedSkills;
594
- if (skillsResult) {
1775
+ if (skillsResult && !state.skillsLocked) {
595
1776
  const scopeResult = await Jt({
596
1777
  message: "Where should skills be installed?",
597
1778
  withGuide: true,
@@ -620,13 +1801,28 @@ async function promptForOptions(state) {
620
1801
  } else {
621
1802
  selectedSkills = [];
622
1803
  }
623
- } else {
1804
+ } else if (!skillsResult) {
624
1805
  selectedSkills = [];
625
1806
  }
1807
+ const resourceProjection = await Lt2({
1808
+ message: "Which system resources should also be copied into this project? Provider reads need no Store access.",
1809
+ withGuide: true,
1810
+ initialValues: options.resourceProjection ?? [],
1811
+ required: false,
1812
+ options: PROJECT_RESOURCE_TYPES.map((resourceType) => ({
1813
+ value: resourceType,
1814
+ label: resourceType,
1815
+ hint: "Optional local copy for portability. It does not grant harness or Store access."
1816
+ }))
1817
+ });
1818
+ if (Ct(resourceProjection)) {
1819
+ return null;
1820
+ }
626
1821
  return {
627
1822
  skills: skillsResult,
628
1823
  skillScope,
629
- selectedSkills
1824
+ selectedSkills,
1825
+ resourceProjection
630
1826
  };
631
1827
  }
632
1828
  function renderSkillSelectionFrame(prompt, skillSelection) {
@@ -663,12 +1859,8 @@ ${styleText("gray", h)} ${styleText(
663
1859
  selectedSkillNames
664
1860
  );
665
1861
  const detailLines = renderDetailBox(
666
- focusedOption.label,
667
- [
668
- focusedOption.hint || "No additional description available.",
669
- "",
670
- `Status: ${selectedSkillNames.has(focusedOption.value) ? "Selected" : "Available"}`
671
- ],
1862
+ focusedOption.value,
1863
+ focusedOption.detailLines.length > 0 ? focusedOption.detailLines : [focusedOption.hint || "No additional description available."],
672
1864
  process.stdout.columns
673
1865
  );
674
1866
  const hintLines = [
@@ -738,6 +1930,9 @@ function renderSkillSelectionLines(options, activeIndex, selectedSkillNames) {
738
1930
  });
739
1931
  return lines;
740
1932
  }
1933
+ function formatSkillPurposeLabels(skill) {
1934
+ return skill.purposes.length > 0 ? skill.purposes.map((purpose) => purpose.label).join(", ") : "Uncategorized";
1935
+ }
741
1936
  function renderCapabilitiesFrame(prompt, selections) {
742
1937
  const checklist = buildCapabilityChecklistState(selections);
743
1938
  const lineColor = prompt.state === "error" ? "yellow" : "cyan";
@@ -851,8 +2046,8 @@ function renderDetailBox(title, lines, columns) {
851
2046
  );
852
2047
  return boxLines.map((line) => styleText("dim", line));
853
2048
  }
854
- function wrapPlainText(text, width) {
855
- const words = text.split(/\s+/).filter((word) => word.length > 0);
2049
+ function wrapPlainText(text2, width) {
2050
+ const words = text2.split(/\s+/).filter((word) => word.length > 0);
856
2051
  if (words.length === 0) {
857
2052
  return [""];
858
2053
  }
@@ -897,6 +2092,295 @@ function findNearestEnabledIndex(cursor, options) {
897
2092
  return enabledIndices.find((index) => index > cursor) ?? enabledIndices[0];
898
2093
  }
899
2094
 
2095
+ // src/setup-project-recovery.ts
2096
+ var SetupProjectRecoveryError = class extends Error {
2097
+ mutationState;
2098
+ constructor(message, mutationState) {
2099
+ super(message);
2100
+ this.name = "SetupProjectRecoveryError";
2101
+ this.mutationState = mutationState;
2102
+ }
2103
+ };
2104
+ function recoveryChoice(targetRoot, operationId, mode, storeRoot) {
2105
+ const engineMode = mode === "restore" ? "rollback" : "resume";
2106
+ const result = recoverInstallationOperation(
2107
+ targetRoot,
2108
+ operationId,
2109
+ engineMode,
2110
+ true,
2111
+ storeRoot
2112
+ );
2113
+ return {
2114
+ mode,
2115
+ label: mode === "resume" ? "Resume reviewed work" : "Restore the prior project state",
2116
+ available: result.status === "ready",
2117
+ status: result.status,
2118
+ changes: result.changes,
2119
+ conflicts: result.conflicts
2120
+ };
2121
+ }
2122
+ function prepareSetupProjectRecoveryReview(targetRoot, storeRoot) {
2123
+ registerSkillAdoptionRecovery();
2124
+ const installation = readInstallationStatus(targetRoot, storeRoot);
2125
+ if (installation.status !== "recovery-required" || !("pendingOperation" in installation) || !installation.pendingOperation) {
2126
+ return null;
2127
+ }
2128
+ const pending = installation.pendingOperation;
2129
+ const resume = recoveryChoice(
2130
+ targetRoot,
2131
+ pending.operation_id,
2132
+ "resume",
2133
+ storeRoot
2134
+ );
2135
+ const restore = recoveryChoice(
2136
+ targetRoot,
2137
+ pending.operation_id,
2138
+ "restore",
2139
+ storeRoot
2140
+ );
2141
+ const recommendation = pending.planComplete && resume.available ? "resume" : restore.available ? "restore" : resume.available ? "resume" : null;
2142
+ return {
2143
+ schemaVersion: 1,
2144
+ targetRoot,
2145
+ status: "review-required",
2146
+ operationId: pending.operation_id,
2147
+ operation: pending.operation,
2148
+ planComplete: pending.planComplete,
2149
+ choices: [resume, restore],
2150
+ recommendation,
2151
+ selectedMode: null,
2152
+ nextAction: recommendation ? "Choose the reviewed recovery action in setup. Setup will then reload the project and build a new plan." : "Preserve the project and review the listed conflicts. Setup cannot safely continue yet."
2153
+ };
2154
+ }
2155
+ function applySetupProjectRecovery(reviewed, mode, storeRoot) {
2156
+ const current = prepareSetupProjectRecoveryReview(reviewed.targetRoot, storeRoot);
2157
+ if (!current || current.operationId !== reviewed.operationId) {
2158
+ throw new SetupProjectRecoveryError(
2159
+ "The pending project operation changed after review. Run setup again for a new recovery review.",
2160
+ "none"
2161
+ );
2162
+ }
2163
+ const choice = current.choices.find((candidate) => candidate.mode === mode);
2164
+ if (!choice?.available) {
2165
+ const conflicts = choice?.conflicts.length ? ` ${choice.conflicts.join(" ")}` : "";
2166
+ throw new SetupProjectRecoveryError(
2167
+ `Setup cannot ${mode} this project operation safely.${conflicts}`,
2168
+ "none"
2169
+ );
2170
+ }
2171
+ let result;
2172
+ try {
2173
+ result = recoverInstallationOperation(
2174
+ current.targetRoot,
2175
+ current.operationId,
2176
+ mode === "restore" ? "rollback" : "resume",
2177
+ false,
2178
+ storeRoot
2179
+ );
2180
+ } catch (error) {
2181
+ throw new SetupProjectRecoveryError(
2182
+ error instanceof Error ? error.message : String(error),
2183
+ "partial"
2184
+ );
2185
+ }
2186
+ if (result.status !== "completed" && result.status !== "rolled-back") {
2187
+ throw new SetupProjectRecoveryError(
2188
+ `Project recovery did not finish. Recovery status: ${result.status}.`,
2189
+ "partial"
2190
+ );
2191
+ }
2192
+ return {
2193
+ ...current,
2194
+ status: result.status,
2195
+ selectedMode: mode,
2196
+ nextAction: "Project recovery finished. Setup will reload current state and build a new plan."
2197
+ };
2198
+ }
2199
+ function blockSetupProjectRecovery(review, mode, reason) {
2200
+ return {
2201
+ ...review,
2202
+ status: "blocked",
2203
+ selectedMode: mode,
2204
+ nextAction: reason
2205
+ };
2206
+ }
2207
+ function renderSetupProjectRecovery(review) {
2208
+ const lines = [
2209
+ review.status === "review-required" ? "Setup found unfinished project work." : review.status === "completed" ? "Setup resumed and completed the unfinished project work." : review.status === "rolled-back" ? "Setup restored the project state from before the unfinished work." : "Setup could not safely recover the unfinished project work.",
2210
+ `Operation: ${review.operation} (${review.operationId})`,
2211
+ `Saved plan: ${review.planComplete ? "complete" : "incomplete"}.`
2212
+ ];
2213
+ for (const choice of review.choices) {
2214
+ lines.push(
2215
+ `${choice.label}: ${choice.available ? "ready" : `unavailable (${choice.status})`}.`
2216
+ );
2217
+ for (const change of choice.changes) {
2218
+ lines.push(`- ${change.path}: ${change.to}`);
2219
+ }
2220
+ for (const conflict of choice.conflicts) {
2221
+ lines.push(`Review: ${conflict}`);
2222
+ }
2223
+ }
2224
+ if (review.recommendation) {
2225
+ const recommended = review.choices.find(
2226
+ (choice) => choice.mode === review.recommendation
2227
+ );
2228
+ lines.push(`Recommended: ${recommended?.label ?? review.recommendation}.`);
2229
+ }
2230
+ lines.push(`Next: ${review.nextAction}`, "");
2231
+ return lines.join("\n");
2232
+ }
2233
+
2234
+ // src/generic-mcp-setup.ts
2235
+ import { randomBytes } from "crypto";
2236
+ import os from "os";
2237
+ import path3 from "path";
2238
+ function validateGenericMcpClientLabel(label) {
2239
+ const normalized = label.trim().toLowerCase();
2240
+ if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(normalized) || normalized.length > 48) {
2241
+ throw new Error("`--generic-mcp-client` needs a stable lowercase label of 1 to 48 letters, numbers, or single hyphens.");
2242
+ }
2243
+ return normalized;
2244
+ }
2245
+ function prepareGenericMcpSetup(options) {
2246
+ const clientLabel = validateGenericMcpClientLabel(options.clientLabel);
2247
+ const harnessId = `generic-mcp-${clientLabel}`;
2248
+ const action = options.action ?? "configure";
2249
+ const storeRoot = options.storeRoot ?? resolveStoreRoot();
2250
+ const existing = loadGlobalConfig(storeRoot).config.settings.harnesses[harnessId];
2251
+ const active = isCurrentGenericIntent(existing, clientLabel);
2252
+ const accessCeiling = { store: "write", project: "write", hostConfig: "none" };
2253
+ if (action === "remove") {
2254
+ return {
2255
+ schemaVersion: 1,
2256
+ clientLabel,
2257
+ harnessId,
2258
+ action,
2259
+ changed: Boolean(existing),
2260
+ state: existing ? "planned" : "missing",
2261
+ accessCeiling,
2262
+ review: existing ? `Remove the Make Docs-owned generic MCP profile '${clientLabel}'. No client-owned file changes.` : `Generic MCP profile '${clientLabel}' is already absent. No client-owned file changes.`,
2263
+ nextAction: null,
2264
+ configuration: null,
2265
+ configurationDigest: null,
2266
+ intent: null,
2267
+ storeRoot
2268
+ };
2269
+ }
2270
+ if (action === "configure" && active) {
2271
+ return {
2272
+ schemaVersion: 1,
2273
+ clientLabel,
2274
+ harnessId,
2275
+ action,
2276
+ changed: false,
2277
+ state: "current",
2278
+ accessCeiling,
2279
+ review: `Generic MCP profile '${clientLabel}' is current. Make Docs cannot show the prior secret proof. Use --generic-mcp-action rotate to produce a new configuration object.`,
2280
+ nextAction: `Use the existing client configuration, or run setup again with --generic-mcp-action rotate.`,
2281
+ configuration: null,
2282
+ configurationDigest: typeof existing.configurationDigest === "string" ? existing.configurationDigest : null,
2283
+ intent: existing,
2284
+ storeRoot
2285
+ };
2286
+ }
2287
+ const executable = options.executable ?? verifyMakeDocsExecutable({
2288
+ executablePath: path3.resolve(process.argv[1] ?? "")
2289
+ });
2290
+ const proof = randomBytes(32).toString("base64url");
2291
+ const machineRoot = path3.resolve(options.machineRoot ?? os.homedir());
2292
+ const identity = {
2293
+ schemaVersion: 1,
2294
+ kind: "make-docs-generic-mcp-caller",
2295
+ adapterId: "generic-mcp",
2296
+ adapterVersion: 1,
2297
+ harnessId,
2298
+ connectionMethod: "mcp",
2299
+ scope: "machine",
2300
+ root: machineRoot,
2301
+ executable,
2302
+ proof
2303
+ };
2304
+ const configuration = {
2305
+ mcpServers: {
2306
+ "make-docs": {
2307
+ command: executable.path,
2308
+ args: ["mcp"],
2309
+ env: { MAKE_DOCS_HARNESS_CALLER_IDENTITY: encodeHarnessCallerIdentity(identity) }
2310
+ }
2311
+ }
2312
+ };
2313
+ const configurationDigest = sha256(JSON.stringify(configuration));
2314
+ const priorRevision = typeof existing?.identityRevision === "number" ? existing.identityRevision : 0;
2315
+ const intent = {
2316
+ selected: true,
2317
+ maximumMethod: "mcp",
2318
+ accessCeiling: { ...accessCeiling },
2319
+ profileKind: "generic-mcp",
2320
+ clientLabel,
2321
+ machineRoot,
2322
+ proofSha256: sha256(proof),
2323
+ identityRevision: priorRevision + 1,
2324
+ configurationDigest,
2325
+ lifecycleState: "active"
2326
+ };
2327
+ return {
2328
+ schemaVersion: 1,
2329
+ clientLabel,
2330
+ harnessId,
2331
+ action,
2332
+ changed: true,
2333
+ state: "planned",
2334
+ accessCeiling,
2335
+ review: `${action === "configure" ? "Create" : action === "rotate" ? "Rotate" : "Repair"} generic MCP profile '${clientLabel}'. Make Docs will write only its global intent and will not edit client-owned files.`,
2336
+ nextAction: `Copy the printed configuration object into the client's MCP server settings. Run \`make-docs setup --generic-mcp-client ${clientLabel} --target <project>\` to record separate project access.`,
2337
+ configuration,
2338
+ configurationDigest,
2339
+ intent,
2340
+ storeRoot
2341
+ };
2342
+ }
2343
+ function applyGenericMcpSetup(plan) {
2344
+ if (!plan.changed) return { ...plan, state: plan.state === "missing" ? "missing" : "current" };
2345
+ const loaded = loadGlobalConfig(plan.storeRoot);
2346
+ if (plan.action === "remove") {
2347
+ delete loaded.config.settings.harnesses[plan.harnessId];
2348
+ } else if (plan.intent) {
2349
+ loaded.config.settings.harnesses[plan.harnessId] = {
2350
+ ...plan.intent,
2351
+ accessCeiling: { ...plan.intent.accessCeiling }
2352
+ };
2353
+ }
2354
+ writeGlobalConfig(plan.storeRoot, loaded.config);
2355
+ return { ...plan, state: plan.action === "remove" ? "missing" : "current" };
2356
+ }
2357
+ function genericMcpProjectIntent(plan) {
2358
+ return plan.action === "remove" ? { harness: plan.harnessId, mode: "disable" } : {
2359
+ harness: plan.harnessId,
2360
+ mode: "narrow",
2361
+ method: "mcp",
2362
+ accessCeiling: { ...plan.accessCeiling }
2363
+ };
2364
+ }
2365
+ function renderGenericMcpSetupResult(plan) {
2366
+ const lines = [
2367
+ `Generic MCP client: ${plan.clientLabel}.`,
2368
+ `State: ${plan.state}.`,
2369
+ plan.review
2370
+ ];
2371
+ if (plan.configuration) {
2372
+ lines.push("Client-owned configuration object:", JSON.stringify(plan.configuration, null, 2));
2373
+ }
2374
+ if (plan.nextAction) lines.push(`Next: ${plan.nextAction}`);
2375
+ return `${lines.join("\n")}
2376
+ `;
2377
+ }
2378
+ function isCurrentGenericIntent(value, clientLabel) {
2379
+ return Boolean(
2380
+ value?.selected === true && value.maximumMethod === "mcp" && value.profileKind === "generic-mcp" && value.clientLabel === clientLabel && value.lifecycleState === "active" && typeof value.proofSha256 === "string" && /^[a-f0-9]{64}$/.test(value.proofSha256) && typeof value.configurationDigest === "string" && /^[a-f0-9]{64}$/.test(value.configurationDigest)
2381
+ );
2382
+ }
2383
+
900
2384
  // src/cli.ts
901
2385
  var RENDERED_ACTION_KIND_ORDER = {
902
2386
  generate: 0,
@@ -906,21 +2390,226 @@ var RENDERED_ACTION_KIND_ORDER = {
906
2390
  };
907
2391
  var uninstallCommandLoaderOverride = null;
908
2392
  var skillsCommandRunnerOverride = null;
909
- async function runCli(argv = process.argv.slice(2)) {
2393
+ function resolveCliLaunchArgv(argv, environmentCallerIdentityRaw = process.env[HARNESS_CALLER_IDENTITY_ENV]) {
2394
+ const identityPositions = argv.flatMap(
2395
+ (value, index) => value === HARNESS_CALLER_IDENTITY_ARG ? [index] : []
2396
+ );
2397
+ const referencePositions = argv.flatMap(
2398
+ (value, index) => value === HARNESS_CALLER_REFERENCE_ARG ? [index] : []
2399
+ );
2400
+ if (identityPositions.length > 1) {
2401
+ throw new OperationError(`\`${HARNESS_CALLER_IDENTITY_ARG}\` can be given only once.`);
2402
+ }
2403
+ if (referencePositions.length > 1) {
2404
+ throw new OperationError(`\`${HARNESS_CALLER_REFERENCE_ARG}\` can be given only once.`);
2405
+ }
2406
+ if (identityPositions.length && referencePositions.length) {
2407
+ throw new OperationError("The Make Docs harness caller identity and reference cannot be used together.");
2408
+ }
2409
+ if (identityPositions.length === 1 && identityPositions[0] !== 0) {
2410
+ throw new OperationError(`\`${HARNESS_CALLER_IDENTITY_ARG}\` must come before the public command.`);
2411
+ }
2412
+ if (referencePositions.length === 1 && referencePositions[0] !== 0) {
2413
+ throw new OperationError(`\`${HARNESS_CALLER_REFERENCE_ARG}\` must come before the public command.`);
2414
+ }
2415
+ let argumentCallerIdentityRaw;
2416
+ let callerReference;
2417
+ let commandArgv = [...argv];
2418
+ if (identityPositions[0] === 0) {
2419
+ const argument = argv[1];
2420
+ if (!argument) {
2421
+ throw new OperationError(`\`${HARNESS_CALLER_IDENTITY_ARG}\` requires one caller identity.`);
2422
+ }
2423
+ try {
2424
+ argumentCallerIdentityRaw = encodeHarnessCallerIdentity(
2425
+ parseHarnessCallerIdentityArgument(argument)
2426
+ );
2427
+ } catch (error) {
2428
+ const detail = error instanceof Error ? error.message : String(error);
2429
+ throw new OperationError(`The Make Docs harness caller identity is invalid: ${detail}`);
2430
+ }
2431
+ commandArgv = argv.slice(2);
2432
+ if (commandArgv.length === 0) {
2433
+ throw new OperationError(`\`${HARNESS_CALLER_IDENTITY_ARG}\` must be followed by a public command.`);
2434
+ }
2435
+ } else if (referencePositions[0] === 0) {
2436
+ const argument = argv[1];
2437
+ if (!argument) {
2438
+ throw new OperationError(`\`${HARNESS_CALLER_REFERENCE_ARG}\` requires one caller reference.`);
2439
+ }
2440
+ try {
2441
+ callerReference = parseHarnessCallerReference(argument);
2442
+ } catch (error) {
2443
+ const detail = error instanceof Error ? error.message : String(error);
2444
+ throw new OperationError(`The Make Docs harness caller reference is invalid: ${detail}`);
2445
+ }
2446
+ commandArgv = argv.slice(2);
2447
+ if (commandArgv.length === 0) {
2448
+ throw new OperationError(`\`${HARNESS_CALLER_REFERENCE_ARG}\` must be followed by a public command.`);
2449
+ }
2450
+ }
2451
+ if (callerReference && environmentCallerIdentityRaw) {
2452
+ throw new OperationError("The Make Docs harness caller reference and environment identity cannot be used together.");
2453
+ }
2454
+ if (argumentCallerIdentityRaw && environmentCallerIdentityRaw) {
2455
+ let canonicalEnvironmentCallerIdentityRaw;
2456
+ try {
2457
+ canonicalEnvironmentCallerIdentityRaw = encodeHarnessCallerIdentity(
2458
+ parseHarnessCallerIdentity(environmentCallerIdentityRaw)
2459
+ );
2460
+ } catch (error) {
2461
+ const detail = error instanceof Error ? error.message : String(error);
2462
+ throw new OperationError(`The Make Docs harness caller identity is invalid: ${detail}`);
2463
+ }
2464
+ if (argumentCallerIdentityRaw !== canonicalEnvironmentCallerIdentityRaw) {
2465
+ throw new OperationError("The command and environment harness caller identities do not match.");
2466
+ }
2467
+ }
2468
+ const callerIdentityRaw = argumentCallerIdentityRaw ?? environmentCallerIdentityRaw;
2469
+ return {
2470
+ argv: commandArgv,
2471
+ launch: resolveCliOperationLaunch(callerIdentityRaw, callerReference)
2472
+ };
2473
+ }
2474
+ function previewPostBridgeInstallationManifest(targetDir, storeRoot, bridge) {
2475
+ if ((bridge.sourceSchemaVersion ?? 0) < 3) return null;
2476
+ if (!existsSync2(targetDir)) return null;
2477
+ const classification = classifyStoreCheckpoint9State(storeRoot);
2478
+ if (classification.state !== "supported-legacy") return null;
2479
+ const driver = loadSqliteDriver();
2480
+ if (!driver.available) return null;
2481
+ const targetRoot = realpathSync(targetDir);
2482
+ const db = new driver.sqlite.DatabaseSync(classification.databasePath, { readOnly: true });
2483
+ try {
2484
+ const rows = db.prepare(
2485
+ `SELECT installation_checkouts.root_path, installation_ledgers.manifest_json
2486
+ FROM installation_checkouts
2487
+ JOIN installation_ledgers USING (checkout_id)`
2488
+ ).all();
2489
+ const row = rows.find((candidate) => path4.resolve(candidate.root_path) === targetRoot);
2490
+ if (!row) return null;
2491
+ return validateAndMigrateManifest(
2492
+ JSON.parse(row.manifest_json),
2493
+ `predicted post-bridge Store ledger for ${targetRoot}`
2494
+ );
2495
+ } finally {
2496
+ db.close();
2497
+ }
2498
+ }
2499
+ async function runCli(argv = process.argv.slice(2), priorProjectRecovery = null, priorProjectMutationApplied = false) {
2500
+ const resolvedLaunch = resolveCliLaunchArgv(argv);
2501
+ argv = resolvedLaunch.argv;
2502
+ if (argv[0] === "--version" || argv[0] === "-v") {
2503
+ output.write(`${readPackageMeta().version}
2504
+ `);
2505
+ return;
2506
+ }
910
2507
  const parsed = parseArgs(argv);
911
2508
  if (parsed.help) {
912
- printHelp(parsed.command);
2509
+ printHelp(parsed.command, parsed.setupSubcommand);
2510
+ return;
2511
+ }
2512
+ if (parsed.command === "run") {
2513
+ await runRunCommand(parsed.runArgs, {}, resolvedLaunch.launch);
2514
+ return;
2515
+ }
2516
+ if (parsed.command === "resource") {
2517
+ await runResourceCommand(parsed.runArgs, resolvedLaunch.launch);
2518
+ return;
2519
+ }
2520
+ if (parsed.command === "project") {
2521
+ if (parsed.runArgs[0] === "path-hygiene" && ["validate", "repair"].includes(parsed.runArgs[1] ?? "")) {
2522
+ await runProjectPathHygieneCommand(
2523
+ parsed.runArgs.slice(2),
2524
+ parsed.runArgs[1] === "repair",
2525
+ resolvedLaunch.launch
2526
+ );
2527
+ return;
2528
+ }
2529
+ await runProjectCommand(parsed.runArgs, resolvedLaunch.launch);
2530
+ return;
2531
+ }
2532
+ if (parsed.command === "mcp") {
2533
+ const { runMcpServer } = await import("./server-O2ZELIMX.js");
2534
+ await runMcpServer();
2535
+ return;
2536
+ }
2537
+ if (parsed.command === "update") {
2538
+ const { runToolUpdateCommand } = await import("./self-YYXOLDKU.js");
2539
+ await runToolUpdateCommand({
2540
+ yes: parsed.yes,
2541
+ ...parsed.targetDir ? { targetDir: path4.resolve(parsed.targetDir) } : {}
2542
+ });
2543
+ return;
2544
+ }
2545
+ if (parsed.command === "uninstall") {
2546
+ const { runToolUninstallCommand } = await import("./self-YYXOLDKU.js");
2547
+ await runToolUninstallCommand({ yes: parsed.yes, removeStore: parsed.removeStore });
2548
+ return;
2549
+ }
2550
+ validateParsedArgs(parsed);
2551
+ if (parsed.setupSubcommand === "system") {
2552
+ const { runSystemSetupCommand } = await import("./setup-system-HZROFNMP.js");
2553
+ const result = await runSystemSetupCommand({
2554
+ dryRun: parsed.dryRun,
2555
+ yes: parsed.yes,
2556
+ promptForMethods: !parsed.yes && !parsed.dryRun && !parsed.json && Boolean(input.isTTY && output.isTTY),
2557
+ targetRoot: path4.resolve(parsed.targetDir ?? process.cwd()),
2558
+ methods: {
2559
+ ...parsed.codexMethod !== void 0 ? { codex: parsed.codexMethod } : {},
2560
+ ...parsed.claudeCodeMethod !== void 0 ? { "claude-code": parsed.claudeCodeMethod } : {}
2561
+ },
2562
+ harnesses: {
2563
+ "claude-code": parsed.claudeCodeMethod !== void 0 || !parsed.noClaudeCode,
2564
+ codex: parsed.codexMethod !== void 0 || !parsed.noCodex
2565
+ },
2566
+ ...!parsed.json && output.isTTY ? { onReview: (review) => Vt(review, "This computer") } : {}
2567
+ });
2568
+ let genericPlan = null;
2569
+ if (parsed.genericMcpClient) {
2570
+ genericPlan = prepareGenericMcpSetup({
2571
+ clientLabel: parsed.genericMcpClient,
2572
+ action: parsed.genericMcpAction
2573
+ });
2574
+ if (!parsed.dryRun) {
2575
+ let approved = parsed.yes;
2576
+ if (!approved && input.isTTY && output.isTTY) {
2577
+ const answer = await Rt({
2578
+ message: `${genericPlan.review} Apply this Make Docs-owned profile?`,
2579
+ initialValue: false,
2580
+ active: "Yes",
2581
+ inactive: "No",
2582
+ withGuide: true
2583
+ });
2584
+ approved = !Ct(answer) && Boolean(answer);
2585
+ }
2586
+ if (approved || !genericPlan.changed) genericPlan = applyGenericMcpSetup(genericPlan);
2587
+ }
2588
+ }
2589
+ if (parsed.json || !output.isTTY) {
2590
+ output.write(`${JSON.stringify(genericPlan ? { ...result, genericMcp: genericPlan } : result)}
2591
+ `);
2592
+ } else {
2593
+ output.write(renderSystemSetupResult(result));
2594
+ if (genericPlan) output.write(renderGenericMcpSetupResult(genericPlan));
2595
+ }
913
2596
  return;
914
2597
  }
915
- const targetDir = path.resolve(parsed.targetDir ?? process.cwd());
916
- if (parsed.command === "backup") {
2598
+ const effectiveSkillRegistry = loadEffectiveSkillRegistry({
2599
+ packageRoot: PACKAGE_ROOT,
2600
+ manifestReference: parsed.skillsManifest
2601
+ });
2602
+ resolveParsedSelectedSkills(parsed, effectiveSkillRegistry.registry);
2603
+ validateParsedSelectedSkills(parsed, effectiveSkillRegistry.registry);
2604
+ const targetDir = path4.resolve(parsed.targetDir ?? process.cwd());
2605
+ if (parsed.setupSubcommand === "backup") {
917
2606
  await runBackupCommand({
918
2607
  targetDir,
919
2608
  permissions: parsed.yes ? "allow-all" : "confirm"
920
2609
  });
921
2610
  return;
922
2611
  }
923
- if (parsed.command === "uninstall") {
2612
+ if (parsed.setupSubcommand === "remove") {
924
2613
  const runUninstallCommand = await loadUninstallCommand();
925
2614
  await runUninstallCommand({
926
2615
  targetDir,
@@ -929,7 +2618,7 @@ async function runCli(argv = process.argv.slice(2)) {
929
2618
  });
930
2619
  return;
931
2620
  }
932
- if (parsed.command === "skills") {
2621
+ if (parsed.setupSubcommand === "skills") {
933
2622
  await runSkillsCommand({
934
2623
  targetDir,
935
2624
  dryRun: parsed.dryRun,
@@ -938,74 +2627,381 @@ async function runCli(argv = process.argv.slice(2)) {
938
2627
  noCodex: parsed.noCodex,
939
2628
  noClaudeCode: parsed.noClaudeCode,
940
2629
  skillScope: parsed.skillScope,
941
- selectedSkills: parsed.selectedSkills === void 0 ? void 0 : [...parsed.selectedSkills]
2630
+ selectedSkills: parsed.selectedSkills === void 0 ? void 0 : [...parsed.selectedSkills],
2631
+ skillsManifest: parsed.skillsManifest,
2632
+ ...parsed.adoptExisting ? { adoptExisting: [...parsed.adoptExisting] } : {},
2633
+ ...parsed.review ? { review: parsed.review } : {}
942
2634
  });
943
2635
  return;
944
2636
  }
945
- const existingManifest = loadManifest(targetDir);
2637
+ const jsonOutput = parsed.json || !output.isTTY;
2638
+ const interactive = !parsed.yes && !parsed.dryRun && !parsed.json && Boolean(input.isTTY && output.isTTY);
2639
+ const recoveredProjectChanged = priorProjectMutationApplied || priorProjectRecovery !== null;
2640
+ if (parsed.command === void 0) {
2641
+ const bareClassification = await classifyCompatibilityState({ targetDir });
2642
+ if (bareClassification.evidence.manifestTrust.present) {
2643
+ const bareManifest = bareClassification.evidence.manifestTrust.parseable ? loadManifest(targetDir) : null;
2644
+ printInstallStatus({
2645
+ targetDir,
2646
+ manifest: bareManifest,
2647
+ classification: bareClassification
2648
+ });
2649
+ return;
2650
+ }
2651
+ if (!input.isTTY || !output.isTTY) {
2652
+ output.write(
2653
+ [
2654
+ `No make-docs install was detected in ${targetDir}.`,
2655
+ "Bare `make-docs` starts a guided setup only in an interactive terminal.",
2656
+ "Run `make-docs setup` (interactive) or `make-docs setup --yes` (non-interactive) to install.",
2657
+ ""
2658
+ ].join("\n")
2659
+ );
2660
+ return;
2661
+ }
2662
+ }
2663
+ const storeRoot = resolveStoreRoot();
2664
+ const storeBridgePreview = previewStoreCompatibilityBridge(storeRoot);
2665
+ if (storeBridgePreview.blockers.length) {
2666
+ throw new Error(
2667
+ `Store compatibility preview stopped setup: ${storeBridgePreview.blockers.join("; ")} ${storeBridgePreview.nextAction}`
2668
+ );
2669
+ }
2670
+ const projectRecoveryReview = prepareSetupProjectRecoveryReview(targetDir, storeRoot);
2671
+ if (projectRecoveryReview) {
2672
+ if (!jsonOutput) output.write(renderSetupProjectRecovery(projectRecoveryReview));
2673
+ if (priorProjectRecovery) {
2674
+ const reason = "Setup found another unfinished project operation after one recovery. No second recovery was applied. Run setup again to review this operation.";
2675
+ const blocked = blockSetupProjectRecovery(projectRecoveryReview, null, reason);
2676
+ if (jsonOutput) {
2677
+ writeCanonicalSetupResult({
2678
+ status: "blocked",
2679
+ dryRun: false,
2680
+ targetRoot: targetDir,
2681
+ storeBridge: storeBridgePreview,
2682
+ projectRecovery: blocked,
2683
+ storeMutationState: "none",
2684
+ projectChanged: true,
2685
+ projectMutationState: "applied",
2686
+ projectActions: [],
2687
+ failedCondition: "A new recovery review is required.",
2688
+ nextAction: reason
2689
+ });
2690
+ } else {
2691
+ output.write(`Next: ${reason}
2692
+ `);
2693
+ }
2694
+ return;
2695
+ }
2696
+ let selectedMode = parsed.projectRecovery;
2697
+ const availableChoices = projectRecoveryReview.choices.filter((choice) => choice.available);
2698
+ if (!selectedMode && interactive && availableChoices.length > 0) {
2699
+ const selected = await Jt({
2700
+ message: "How should setup recover this unfinished project work?",
2701
+ options: projectRecoveryReview.choices.map((choice) => ({
2702
+ value: choice.mode,
2703
+ label: choice.label,
2704
+ hint: choice.available ? choice.mode === projectRecoveryReview.recommendation ? "Recommended" : void 0 : choice.conflicts[0] ?? "This action is not safe for the saved operation.",
2705
+ disabled: !choice.available
2706
+ })),
2707
+ initialValue: projectRecoveryReview.recommendation ?? void 0
2708
+ });
2709
+ if (Ct(selected)) {
2710
+ output.write("Setup cancelled. The unfinished project work was not changed.\n");
2711
+ return;
2712
+ }
2713
+ selectedMode = selected;
2714
+ }
2715
+ const selectedChoice = selectedMode ? projectRecoveryReview.choices.find((choice) => choice.mode === selectedMode) : null;
2716
+ const mayApply = Boolean(
2717
+ selectedMode && selectedChoice?.available && !parsed.dryRun && (interactive || parsed.yes)
2718
+ );
2719
+ if (!mayApply) {
2720
+ const reason = parsed.dryRun ? "Preview only. No project files or Store records changed." : selectedMode && !selectedChoice?.available ? `${selectedChoice?.label ?? selectedMode} is not safe for this operation. Review the listed conflicts.` : availableChoices.length === 0 ? projectRecoveryReview.nextAction : !interactive && !parsed.yes && selectedMode ? "Run setup with --yes after you review this recovery choice." : "Run make-docs setup in an interactive terminal and choose one available recovery action.";
2721
+ const blocked = blockSetupProjectRecovery(projectRecoveryReview, selectedMode ?? null, reason);
2722
+ if (jsonOutput) {
2723
+ writeCanonicalSetupResult({
2724
+ status: "blocked",
2725
+ dryRun: parsed.dryRun,
2726
+ targetRoot: targetDir,
2727
+ storeBridge: storeBridgePreview,
2728
+ projectRecovery: blocked,
2729
+ storeMutationState: "none",
2730
+ projectChanged: recoveredProjectChanged,
2731
+ projectMutationState: recoveredProjectChanged ? "applied" : "none",
2732
+ projectActions: [],
2733
+ failedCondition: parsed.dryRun ? null : "Unfinished project work requires a recovery choice.",
2734
+ nextAction: reason
2735
+ });
2736
+ } else {
2737
+ output.write(`Next: ${reason}
2738
+ `);
2739
+ }
2740
+ return;
2741
+ }
2742
+ try {
2743
+ const recovered = applySetupProjectRecovery(
2744
+ projectRecoveryReview,
2745
+ selectedMode,
2746
+ storeRoot
2747
+ );
2748
+ if (!jsonOutput) output.write(renderSetupProjectRecovery(recovered));
2749
+ return runCli(argv, recovered, true);
2750
+ } catch (error) {
2751
+ const reason = error instanceof Error ? error.message : String(error);
2752
+ const blocked = blockSetupProjectRecovery(projectRecoveryReview, selectedMode, reason);
2753
+ const recoveryMutationState = error instanceof SetupProjectRecoveryError ? error.mutationState : "partial";
2754
+ const combinedProjectMutationState = recoveryMutationState === "partial" ? "partial" : recoveredProjectChanged ? "applied" : "none";
2755
+ if (jsonOutput) {
2756
+ writeCanonicalSetupResult({
2757
+ status: "blocked",
2758
+ dryRun: false,
2759
+ targetRoot: targetDir,
2760
+ storeBridge: storeBridgePreview,
2761
+ projectRecovery: blocked,
2762
+ storeMutationState: "none",
2763
+ projectChanged: combinedProjectMutationState !== "none",
2764
+ projectMutationState: combinedProjectMutationState,
2765
+ projectActions: [],
2766
+ failedCondition: reason,
2767
+ nextAction: "Keep the current files. Run setup again to review the current recovery state."
2768
+ });
2769
+ } else {
2770
+ output.write(`${renderSetupProjectRecovery(blocked)}Keep the current files. Run setup again to review the current recovery state.
2771
+ `);
2772
+ }
2773
+ return;
2774
+ }
2775
+ }
2776
+ if (parsed.projectRecovery && !priorProjectRecovery) {
2777
+ throw new Error("No unfinished project operation is available for setup recovery.");
2778
+ }
2779
+ let legacyState = previewLegacyInstallationState(targetDir);
2780
+ if (legacyState.blockers.length) {
2781
+ throw new Error(`Legacy installation state requires review before setup: ${legacyState.blockers.join("; ")}`);
2782
+ }
2783
+ if (!jsonOutput && legacyState.sources.length) {
2784
+ output.write("Legacy installation state will move to the global Make Docs Store. These verified records will be removed after Store readback:\n");
2785
+ for (const source of legacyState.sources) output.write(`- ${source.relativePath}
2786
+ `);
2787
+ }
946
2788
  const installIntent = inferInstallIntent(parsed);
947
- if (installIntent === "reconfigure" && !existingManifest) {
2789
+ const loadedConfig = loadMakeDocsConfigOrThrow(targetDir);
2790
+ const makeDocsConfig = loadedConfig.config;
2791
+ let compatibilityClassification = await classifyCompatibilityState({
2792
+ targetDir
2793
+ });
2794
+ let completedRemovalHandoff = reviewCompletedRemovalHandoff(targetDir, storeRoot);
2795
+ assertCompletedRemovalHandoffUsable(completedRemovalHandoff);
2796
+ const predictedPostBridgeManifest = previewPostBridgeInstallationManifest(
2797
+ targetDir,
2798
+ storeRoot,
2799
+ storeBridgePreview
2800
+ );
2801
+ let existingManifest = predictedPostBridgeManifest ?? (compatibilityClassification.evidence.manifestTrust.parseable ? loadManifest(targetDir) ?? legacyState.manifest : null);
2802
+ let planningManifest = existingManifest ?? (completedRemovalHandoff.status === "ready" ? completedRemovalHandoff.beforeManifest : null);
2803
+ const completedRemovalResourceProjection = completedRemovalHandoff.status === "ready" && completedRemovalHandoff.beforeManifest.selections.resourceProjection === void 0 ? inferCompletedRemovalResourceProjection(completedRemovalHandoff.beforeManifest) : void 0;
2804
+ let freshInstallTarget = isFreshInstallTarget({
2805
+ targetDir,
2806
+ existingManifest: planningManifest,
2807
+ installIntent,
2808
+ classification: compatibilityClassification
2809
+ });
2810
+ if (installIntent === "reconfigure" && !existingManifest && !compatibilityClassification.evidence.manifestTrust.present) {
2811
+ throw new Error(
2812
+ "No make-docs manifest was found in the target directory. Run `make-docs setup` first."
2813
+ );
2814
+ }
2815
+ if (freshInstallTarget && (parsed.noDesigns || parsed.noPlans || parsed.noPrd || parsed.noWork)) {
2816
+ throw new Error(
2817
+ "Fresh setup always installs Designs, Plans, PRD, and Work. Remove the document-type flags. You can review a later change with `make-docs setup reconfigure`."
2818
+ );
2819
+ }
2820
+ if (!predictedPostBridgeManifest && completedRemovalHandoff.status !== "ready") {
2821
+ guardCompatibilityDisposition({
2822
+ classification: compatibilityClassification,
2823
+ interactive,
2824
+ freshInstallTarget
2825
+ });
2826
+ }
2827
+ if (!freshInstallTarget) {
2828
+ const { detectPreV2Install, promptPreV2Choice } = await import("./self-YYXOLDKU.js");
2829
+ const preV2 = detectPreV2Install({
2830
+ targetDir,
2831
+ classification: compatibilityClassification
2832
+ });
2833
+ if (preV2.preV2) {
2834
+ const choice = await promptPreV2Choice({
2835
+ detection: preV2,
2836
+ interactive,
2837
+ command: installIntent === "reconfigure" ? "setup reconfigure" : "setup"
2838
+ });
2839
+ if (choice === "cancel") {
2840
+ output.write("Setup cancelled. The existing pre-v2 install was left untouched.\n");
2841
+ return;
2842
+ }
2843
+ }
2844
+ }
2845
+ if (!interactive && installIntent === "reconfigure" && !hasSelectionOverrides(parsed)) {
948
2846
  throw new Error(
949
- "No make-docs manifest was found in the target directory. Run `make-docs` first."
2847
+ "`make-docs setup reconfigure --yes` requires at least one selection flag. Provide selection flags or run `make-docs setup reconfigure` interactively."
950
2848
  );
951
2849
  }
952
- const interactive = !parsed.yes;
953
- if (!interactive && installIntent === "reconfigure" && !hasSelectionOverrides(parsed)) {
2850
+ if (completedRemovalResourceProjection === null && !interactive && parsed.projectResources === void 0) {
954
2851
  throw new Error(
955
- "`make-docs reconfigure --yes` requires at least one selection flag. Provide selection flags or run `make-docs reconfigure` interactively."
2852
+ "The completed removal does not contain enough evidence to recover the prior local resource selection. Run `make-docs setup` interactively, or rerun with `--project-resources <csv|all|none>`."
956
2853
  );
957
2854
  }
958
- if (interactive && (!input.isTTY || !output.isTTY)) {
959
- throw new Error("Interactive prompts require a TTY. Use --yes for non-interactive runs.");
2855
+ const resolvedSelections = resolveSelections({ parsed, existingManifest: planningManifest });
2856
+ if (parsed.projectResources === void 0 && completedRemovalResourceProjection !== void 0 && completedRemovalResourceProjection !== null) {
2857
+ resolvedSelections.resourceProjection = [...completedRemovalResourceProjection];
960
2858
  }
961
- let selections = resolveSelections({
962
- parsed,
963
- existingManifest
964
- });
2859
+ let installationStatus = readInstallationStatus(targetDir, storeRoot);
2860
+ let projectState = freshInstallTarget ? "fresh" : installationStatus.status === "recovery-required" ? "recoverable" : compatibilityClassification.state === "modified-v1" ? "drifted" : completedRemovalResourceProjection === null || compatibilityClassification.state === "partial-install" || planningManifest?.effectiveCapabilities.length !== CAPABILITIES.length ? "partial" : "current";
2861
+ let selections = applySkillRegistrySelectionMetadata(
2862
+ resolveUnifiedSetupState({
2863
+ entry: installIntent === "reconfigure" ? "reconfigure" : "setup",
2864
+ projectState,
2865
+ selections: resolvedSelections,
2866
+ allowCapabilityExpansion: installIntent === "reconfigure"
2867
+ }).selections,
2868
+ effectiveSkillRegistry
2869
+ );
965
2870
  let selectionSource = describeSelectionSource({
966
2871
  parsed,
967
- existingManifest,
2872
+ existingManifest: planningManifest,
968
2873
  installIntent
969
2874
  });
970
- let skipApplyConfirm = false;
2875
+ if (parsed.projectResources === void 0 && completedRemovalResourceProjection !== void 0 && completedRemovalResourceProjection !== null) {
2876
+ selectionSource = "verified completed-removal resource records";
2877
+ }
2878
+ let interactiveMethodSelections = {};
971
2879
  if (interactive) {
972
- if (!existingManifest && installIntent === "apply") {
2880
+ const { inspectSystemHarnesses, promptForSystemSetupMethods } = await import("./setup-system-HZROFNMP.js");
2881
+ const harnessSupport = inspectSystemHarnesses();
2882
+ const afterHarnessSelection = async (wizardSelections) => {
2883
+ interactiveMethodSelections = await promptForSystemSetupMethods({
2884
+ dryRun: false,
2885
+ yes: false,
2886
+ promptForMethods: true,
2887
+ methods: {
2888
+ ...parsed.codexMethod !== void 0 ? { codex: parsed.codexMethod } : {},
2889
+ ...parsed.claudeCodeMethod !== void 0 ? { "claude-code": parsed.claudeCodeMethod } : {}
2890
+ },
2891
+ harnesses: {
2892
+ codex: wizardSelections.harnesses.codex,
2893
+ "claude-code": wizardSelections.harnesses["claude-code"]
2894
+ },
2895
+ projectHarnessIntegrations: makeDocsConfig.harnessIntegrations,
2896
+ targetRoot: targetDir,
2897
+ persistIntent: false
2898
+ });
2899
+ return true;
2900
+ };
2901
+ if (!planningManifest && installIntent === "apply") {
973
2902
  const wizardSelections = await runSelectionWizard({
974
2903
  initialSelections: selections,
975
- introTitle: "Let's configure your make-docs install"
2904
+ introTitle: "Let's configure your make-docs install",
2905
+ projectState: "fresh",
2906
+ harnessSupport,
2907
+ afterHarnessSelection,
2908
+ config: makeDocsConfig,
2909
+ ...parsed.skillsManifest ? { skillRegistry: effectiveSkillRegistry.registry } : {}
976
2910
  });
977
2911
  if (!wizardSelections) {
978
2912
  output.write("Installer cancelled.\n");
979
2913
  return;
980
2914
  }
981
- selections = wizardSelections;
2915
+ selections = applySkillRegistrySelectionMetadata(
2916
+ wizardSelections,
2917
+ effectiveSkillRegistry
2918
+ );
982
2919
  selectionSource = "interactive wizard selections";
983
- skipApplyConfirm = true;
984
- } else if (installIntent === "reconfigure") {
2920
+ } else if (installIntent === "reconfigure" || projectState === "partial" || projectState === "drifted" || projectState === "recoverable") {
985
2921
  const wizardSelections = await runSelectionWizard({
986
2922
  initialSelections: selections,
987
- introTitle: "Let's reconfigure your make-docs install"
2923
+ introTitle: "Let's reconfigure your make-docs install",
2924
+ projectState,
2925
+ allowCapabilityExpansion: installIntent === "reconfigure",
2926
+ harnessSupport,
2927
+ afterHarnessSelection,
2928
+ config: makeDocsConfig,
2929
+ lockSkills: true,
2930
+ ...parsed.skillsManifest ? { skillRegistry: effectiveSkillRegistry.registry } : {}
988
2931
  });
989
2932
  if (!wizardSelections) {
990
2933
  output.write("Installer cancelled.\n");
991
2934
  return;
992
2935
  }
993
- selections = wizardSelections;
994
- selectionSource = "interactive reconfigure wizard";
995
- skipApplyConfirm = true;
2936
+ selections = applySkillRegistrySelectionMetadata(
2937
+ wizardSelections,
2938
+ effectiveSkillRegistry
2939
+ );
2940
+ selectionSource = installIntent === "reconfigure" ? "interactive reconfigure wizard" : "interactive state review";
996
2941
  }
997
2942
  }
2943
+ const skillReconciliation = reconcileExistingInstallSkillSelection({
2944
+ existingManifest: planningManifest,
2945
+ selections
2946
+ });
2947
+ selections = skillReconciliation.selections;
2948
+ if (skillReconciliation.routed && !jsonOutput) {
2949
+ output.write(`${EXISTING_INSTALL_SKILL_SELECTION_CHANGE_ERROR}
2950
+ `);
2951
+ }
2952
+ const {
2953
+ applyPreparedSystemSetup,
2954
+ prepareSystemSetupCommand,
2955
+ resumePendingSystemSetupCommand
2956
+ } = await import("./setup-system-HZROFNMP.js");
2957
+ const systemOptions = {
2958
+ dryRun: parsed.dryRun,
2959
+ yes: parsed.yes,
2960
+ promptForMethods: interactive && Object.keys(interactiveMethodSelections).length === 0,
2961
+ methods: {
2962
+ ...interactiveMethodSelections,
2963
+ ...parsed.codexMethod !== void 0 ? { codex: parsed.codexMethod } : {},
2964
+ ...parsed.claudeCodeMethod !== void 0 ? { "claude-code": parsed.claudeCodeMethod } : {}
2965
+ },
2966
+ harnesses: {
2967
+ "claude-code": selections.harnesses["claude-code"],
2968
+ codex: selections.harnesses.codex
2969
+ },
2970
+ projectHarnessIntegrations: makeDocsConfig.harnessIntegrations,
2971
+ targetRoot: targetDir,
2972
+ persistIntent: true
2973
+ };
2974
+ const resumedSystemSetup = await resumePendingSystemSetupCommand(systemOptions);
2975
+ if (resumedSystemSetup) {
2976
+ if (jsonOutput) {
2977
+ writeCanonicalSetupResult({ status: resumedSystemSetup.status === "configured" ? "machine-recovered" : "blocked", dryRun: parsed.dryRun, targetRoot: targetDir, system: resumedSystemSetup, projectRecovery: priorProjectRecovery, projectChanged: recoveredProjectChanged, projectMutationState: recoveredProjectChanged ? "applied" : "none", projectActions: [], failedCondition: resumedSystemSetup.blocked[0]?.reason ?? null, nextAction: resumedSystemSetup.recoveryAction });
2978
+ } else output.write(
2979
+ resumedSystemSetup.status === "configured" ? "Pending machine setup is now verified. Run `make-docs setup` again for one current computer and project review.\n" : `Setup stopped at machine scope. ${resumedSystemSetup.recoveryAction ?? "Review the pending machine state."}
2980
+ `
2981
+ );
2982
+ return;
2983
+ }
2984
+ let preparedSystemSetup = await prepareSystemSetupCommand(systemOptions);
2985
+ const genericMcpPlan = parsed.genericMcpClient ? prepareGenericMcpSetup({
2986
+ clientLabel: parsed.genericMcpClient,
2987
+ action: parsed.genericMcpAction
2988
+ }) : null;
998
2989
  const packageMeta = readPackageMeta();
999
2990
  let plan = await planInstall({
1000
2991
  targetDir,
1001
2992
  selections,
1002
- existingManifest,
1003
- packageMeta
2993
+ existingManifest: planningManifest,
2994
+ completedRemovalHandoff: completedRemovalHandoff.status === "ready",
2995
+ packageMeta,
2996
+ skillRegistry: effectiveSkillRegistry.registry,
2997
+ preserveExistingSkills: skillReconciliation.routed,
2998
+ operation: installIntent === "reconfigure" ? "setup.reconfigure" : "setup"
1004
2999
  });
3000
+ let managedFileConflictResolutions;
1005
3001
  if (interactive) {
1006
3002
  const managedFileConflicts = findReviewableManagedFileConflicts(plan);
1007
3003
  if (managedFileConflicts.length > 0) {
1008
- const managedFileConflictResolutions = await promptForManagedFileConflictResolutions(managedFileConflicts);
3004
+ managedFileConflictResolutions = await promptForManagedFileConflictResolutions(managedFileConflicts) ?? void 0;
1009
3005
  if (!managedFileConflictResolutions) {
1010
3006
  output.write("Installer cancelled.\n");
1011
3007
  return;
@@ -1013,47 +3009,286 @@ async function runCli(argv = process.argv.slice(2)) {
1013
3009
  plan = await planInstall({
1014
3010
  targetDir,
1015
3011
  selections,
1016
- existingManifest,
3012
+ existingManifest: planningManifest,
3013
+ completedRemovalHandoff: completedRemovalHandoff.status === "ready",
1017
3014
  packageMeta,
1018
- managedFileConflictResolutions
3015
+ managedFileConflictResolutions,
3016
+ skillRegistry: effectiveSkillRegistry.registry,
3017
+ preserveExistingSkills: skillReconciliation.routed,
3018
+ operation: installIntent === "reconfigure" ? "setup.reconfigure" : "setup"
1019
3019
  });
1020
3020
  }
1021
3021
  }
3022
+ compatibilityClassification = scopeCompatibilityToInstallPlan({
3023
+ classification: compatibilityClassification,
3024
+ plan,
3025
+ completedRemovalHandoff: completedRemovalHandoff.status === "ready"
3026
+ });
3027
+ freshInstallTarget = isFreshInstallTarget({
3028
+ targetDir,
3029
+ existingManifest,
3030
+ installIntent,
3031
+ classification: compatibilityClassification
3032
+ });
3033
+ if (!predictedPostBridgeManifest) {
3034
+ guardCompatibilityDisposition({
3035
+ classification: compatibilityClassification,
3036
+ interactive,
3037
+ freshInstallTarget
3038
+ });
3039
+ }
1022
3040
  if (!hasEffectiveCapabilities(plan.profile)) {
1023
3041
  throw new Error("At least one capability must remain enabled.");
1024
3042
  }
1025
- const hasPlannedChanges = plan.actions.some((action) => action.type !== "noop");
1026
- printPlan({
3043
+ const buildReviewedHarnessIntegrations = () => {
3044
+ const reviewed = Object.keys(selections.harnesses).filter((harness) => selections.harnesses[harness]).filter((harness) => {
3045
+ const harnessPlan = preparedSystemSetup.plans.find((candidate) => candidate.harness === harness);
3046
+ return harnessPlan?.status !== "blocked" && harnessPlan?.status !== "unsupported";
3047
+ }).map((harness) => {
3048
+ const method = preparedSystemSetup.selections[harness];
3049
+ if (method === "none") return { harness, mode: "disable" };
3050
+ const accessCeiling = preparedSystemSetup.intent.config.settings.harnesses[harness]?.accessCeiling;
3051
+ if (!accessCeiling) throw new Error(`No reviewed access ceiling exists for ${harness}.`);
3052
+ return { harness, mode: "narrow", method, accessCeiling: { ...accessCeiling } };
3053
+ });
3054
+ if (genericMcpPlan) reviewed.push(genericMcpProjectIntent(genericMcpPlan));
3055
+ return reviewed;
3056
+ };
3057
+ let reviewedHarnessIntegrations = buildReviewedHarnessIntegrations();
3058
+ let plannedConfigValue = plan.actions.find(
3059
+ (action) => action.relativePath === ".make-docs/config.yaml" && action.content !== void 0
3060
+ )?.content ?? "{}\n";
3061
+ let plannedConfigContent = typeof plannedConfigValue === "string" ? plannedConfigValue : Buffer.from(plannedConfigValue).toString("utf8");
3062
+ let projectHarnessConfig = planProjectHarnessIntegrationWrite({
3063
+ targetDir,
3064
+ reviewed: reviewedHarnessIntegrations,
3065
+ contentWhenMissing: plannedConfigContent
3066
+ });
3067
+ let hasPlannedChanges = plan.actions.some((action) => action.type !== "noop") || projectHarnessConfig.changed;
3068
+ let requiresProjectIdMigration = Boolean(existingManifest && !existingManifest.projectId);
3069
+ let hasInstallMutation = hasPlannedChanges || requiresProjectIdMigration;
3070
+ let reviewedProjectFingerprint = setupProjectReviewFingerprint(
3071
+ plan,
3072
+ projectHarnessConfig
3073
+ );
3074
+ const reloadProjectReview = async () => {
3075
+ const previousFingerprint = reviewedProjectFingerprint;
3076
+ legacyState = previewLegacyInstallationState(targetDir);
3077
+ if (legacyState.blockers.length) {
3078
+ throw new Error(
3079
+ `Legacy installation state requires review before setup: ${legacyState.blockers.join("; ")}`
3080
+ );
3081
+ }
3082
+ compatibilityClassification = await classifyCompatibilityState({ targetDir });
3083
+ completedRemovalHandoff = reviewCompletedRemovalHandoff(targetDir, storeRoot);
3084
+ assertCompletedRemovalHandoffUsable(completedRemovalHandoff);
3085
+ existingManifest = compatibilityClassification.evidence.manifestTrust.parseable ? loadManifest(targetDir) ?? legacyState.manifest : null;
3086
+ planningManifest = existingManifest ?? (completedRemovalHandoff.status === "ready" ? completedRemovalHandoff.beforeManifest : null);
3087
+ freshInstallTarget = isFreshInstallTarget({
3088
+ targetDir,
3089
+ existingManifest: planningManifest,
3090
+ installIntent,
3091
+ classification: compatibilityClassification
3092
+ });
3093
+ if (completedRemovalHandoff.status !== "ready") {
3094
+ guardCompatibilityDisposition({
3095
+ classification: compatibilityClassification,
3096
+ interactive,
3097
+ freshInstallTarget
3098
+ });
3099
+ }
3100
+ installationStatus = readInstallationStatus(targetDir, storeRoot);
3101
+ projectState = freshInstallTarget ? "fresh" : installationStatus.status === "recovery-required" ? "recoverable" : compatibilityClassification.state === "modified-v1" ? "drifted" : completedRemovalResourceProjection === null || compatibilityClassification.state === "partial-install" || planningManifest?.effectiveCapabilities.length !== CAPABILITIES.length ? "partial" : "current";
3102
+ plan = await planInstall({
3103
+ targetDir,
3104
+ selections,
3105
+ existingManifest: planningManifest,
3106
+ completedRemovalHandoff: completedRemovalHandoff.status === "ready",
3107
+ packageMeta,
3108
+ ...managedFileConflictResolutions ? { managedFileConflictResolutions } : {},
3109
+ skillRegistry: effectiveSkillRegistry.registry,
3110
+ preserveExistingSkills: skillReconciliation.routed,
3111
+ operation: installIntent === "reconfigure" ? "setup.reconfigure" : "setup"
3112
+ });
3113
+ if (interactive) {
3114
+ const refreshedConflicts = findReviewableManagedFileConflicts(plan);
3115
+ if (refreshedConflicts.length > 0) {
3116
+ const refreshedResolutions = await promptForManagedFileConflictResolutions(refreshedConflicts);
3117
+ if (!refreshedResolutions) {
3118
+ output.write("Installer cancelled.\n");
3119
+ return "cancelled";
3120
+ }
3121
+ managedFileConflictResolutions = {
3122
+ ...managedFileConflictResolutions,
3123
+ ...refreshedResolutions
3124
+ };
3125
+ plan = await planInstall({
3126
+ targetDir,
3127
+ selections,
3128
+ existingManifest: planningManifest,
3129
+ completedRemovalHandoff: completedRemovalHandoff.status === "ready",
3130
+ packageMeta,
3131
+ managedFileConflictResolutions,
3132
+ skillRegistry: effectiveSkillRegistry.registry,
3133
+ preserveExistingSkills: skillReconciliation.routed,
3134
+ operation: installIntent === "reconfigure" ? "setup.reconfigure" : "setup"
3135
+ });
3136
+ }
3137
+ }
3138
+ compatibilityClassification = scopeCompatibilityToInstallPlan({
3139
+ classification: compatibilityClassification,
3140
+ plan,
3141
+ completedRemovalHandoff: completedRemovalHandoff.status === "ready"
3142
+ });
3143
+ freshInstallTarget = isFreshInstallTarget({
3144
+ targetDir,
3145
+ existingManifest,
3146
+ installIntent,
3147
+ classification: compatibilityClassification
3148
+ });
3149
+ guardCompatibilityDisposition({
3150
+ classification: compatibilityClassification,
3151
+ interactive,
3152
+ freshInstallTarget
3153
+ });
3154
+ if (!hasEffectiveCapabilities(plan.profile)) {
3155
+ throw new Error("At least one capability must remain enabled.");
3156
+ }
3157
+ plannedConfigValue = plan.actions.find(
3158
+ (action) => action.relativePath === ".make-docs/config.yaml" && action.content !== void 0
3159
+ )?.content ?? "{}\n";
3160
+ plannedConfigContent = typeof plannedConfigValue === "string" ? plannedConfigValue : Buffer.from(plannedConfigValue).toString("utf8");
3161
+ projectHarnessConfig = planProjectHarnessIntegrationWrite({
3162
+ targetDir,
3163
+ reviewed: reviewedHarnessIntegrations,
3164
+ contentWhenMissing: plannedConfigContent
3165
+ });
3166
+ hasPlannedChanges = plan.actions.some((action) => action.type !== "noop") || projectHarnessConfig.changed;
3167
+ requiresProjectIdMigration = Boolean(existingManifest && !existingManifest.projectId);
3168
+ hasInstallMutation = hasPlannedChanges || requiresProjectIdMigration;
3169
+ reviewedProjectFingerprint = setupProjectReviewFingerprint(
3170
+ plan,
3171
+ projectHarnessConfig
3172
+ );
3173
+ return reviewedProjectFingerprint !== previousFingerprint ? "changed" : "unchanged";
3174
+ };
3175
+ const hasMachineMutation = preparedSystemSetup.changed || Boolean(genericMcpPlan?.changed) || storeBridgePreview.changes.store.length > 0;
3176
+ if (!jsonOutput) Vt(preparedSystemSetup.review, "This computer");
3177
+ if (!jsonOutput && genericMcpPlan) Vt(renderGenericMcpSetupResult(genericMcpPlan), "Generic MCP client");
3178
+ if (!jsonOutput && storeBridgePreview.changes.store.length) {
3179
+ output.write("Store prerequisite for This computer:\n");
3180
+ for (const change of storeBridgePreview.changes.store) output.write(`- ${change}
3181
+ `);
3182
+ output.write("- Approval boundary: the This computer approval covers this prerequisite. It does not approve project files.\n");
3183
+ output.write(`Next: ${storeBridgePreview.nextAction}
3184
+ `);
3185
+ }
3186
+ if (!jsonOutput) printPlan({
1027
3187
  actions: plan.actions,
1028
3188
  dryRun: parsed.dryRun,
1029
- existingManifest,
3189
+ existingManifest: planningManifest,
1030
3190
  installIntent,
1031
3191
  packageName: plan.packageName,
1032
3192
  packageVersion: plan.packageVersion,
1033
3193
  selectionSource,
1034
- targetDir
3194
+ targetDir,
3195
+ compatibilityClassification: freshInstallTarget ? null : compatibilityClassification,
3196
+ config: makeDocsConfig,
3197
+ selectedResourceTypes: plan.profile.selections.resourceProjection,
3198
+ selectedCapabilities: plan.profile.effectiveCapabilities,
3199
+ stops: plan.stops ?? []
1035
3200
  });
3201
+ if (!jsonOutput && projectHarnessConfig.changed) {
3202
+ output.write("Project harness intent: update .make-docs/config.yaml after machine verification.\n");
3203
+ }
1036
3204
  if (parsed.dryRun) {
1037
- output.write("\nDry run complete.\n");
3205
+ if (jsonOutput) writeCanonicalSetupResult({ status: "planned", dryRun: true, targetRoot: targetDir, prepared: preparedSystemSetup, genericMcp: genericMcpPlan, storeBridge: storeBridgePreview, projectRecovery: priorProjectRecovery, projectChanged: hasInstallMutation, projectActions: plan.actions, failedCondition: null, nextAction: hasInstallMutation || hasMachineMutation ? "Run setup with the same choices and --yes to apply this plan." : null });
3206
+ else output.write("\nDry run complete.\n");
1038
3207
  return;
1039
3208
  }
1040
3209
  const unresolvedManagedFileConflicts = findReviewableManagedFileConflicts(plan);
1041
3210
  if (!interactive && unresolvedManagedFileConflicts.length > 0) {
1042
- throw new Error(
1043
- [
1044
- "Non-interactive make-docs runs cannot apply unresolved managed-file diffs.",
1045
- "Run `make-docs` without `--yes` to review the conflicts interactively.",
3211
+ const migrationReviewBlock = getInstallPlanMigrationReviewBlock(plan);
3212
+ const failedCondition = [
3213
+ "Non-interactive make-docs runs cannot apply unresolved managed-file diffs.",
3214
+ "",
3215
+ ...buildCompatibilitySummaryLines(compatibilityClassification),
3216
+ "",
3217
+ migrationReviewBlock?.failedCondition ?? [
1046
3218
  "Conflicting managed files:",
1047
3219
  ...unresolvedManagedFileConflicts.map(
1048
- (conflict) => `- ${conflict.relativePath}`
3220
+ (conflict) => `- ${conflict.relativePath}: ${conflict.reason}`
1049
3221
  )
1050
3222
  ].join("\n")
1051
- );
3223
+ ].join("\n");
3224
+ const nextAction = migrationReviewBlock?.nextAction ?? "Run `make-docs setup` without `--yes` to review the conflicts interactively.";
3225
+ if (jsonOutput) {
3226
+ writeCanonicalSetupResult({
3227
+ status: "blocked",
3228
+ dryRun: false,
3229
+ targetRoot: targetDir,
3230
+ prepared: preparedSystemSetup,
3231
+ genericMcp: genericMcpPlan,
3232
+ storeBridge: storeBridgePreview,
3233
+ projectRecovery: priorProjectRecovery,
3234
+ storeMutationState: "none",
3235
+ projectChanged: recoveredProjectChanged,
3236
+ projectMutationState: recoveredProjectChanged ? "applied" : "none",
3237
+ projectActions: plan.actions,
3238
+ failedCondition,
3239
+ nextAction
3240
+ });
3241
+ return;
3242
+ }
3243
+ throw new Error(`${failedCondition}
3244
+
3245
+ Next: ${nextAction}`);
3246
+ }
3247
+ if (!freshInstallTarget && hasInstallMutation && completedRemovalHandoff.status !== "ready") {
3248
+ const migrationReviewBlock = getInstallPlanMigrationReviewBlock(plan);
3249
+ if (migrationReviewBlock) {
3250
+ if (jsonOutput) {
3251
+ writeCanonicalSetupResult({
3252
+ status: "blocked",
3253
+ dryRun: false,
3254
+ targetRoot: targetDir,
3255
+ prepared: preparedSystemSetup,
3256
+ genericMcp: genericMcpPlan,
3257
+ storeBridge: storeBridgePreview,
3258
+ projectRecovery: priorProjectRecovery,
3259
+ storeMutationState: "none",
3260
+ projectChanged: recoveredProjectChanged,
3261
+ projectMutationState: recoveredProjectChanged ? "applied" : "none",
3262
+ projectActions: plan.actions,
3263
+ failedCondition: migrationReviewBlock.failedCondition,
3264
+ nextAction: migrationReviewBlock.nextAction
3265
+ });
3266
+ } else {
3267
+ output.write(
3268
+ `${migrationReviewBlock.failedCondition}
3269
+ Next: ${migrationReviewBlock.nextAction}
3270
+ `
3271
+ );
3272
+ }
3273
+ return;
3274
+ }
3275
+ }
3276
+ let systemApproved = parsed.yes || !hasMachineMutation;
3277
+ if (interactive && hasMachineMutation) {
3278
+ const proceed = await Rt({
3279
+ message: "Apply the reviewed changes to this computer?",
3280
+ initialValue: false,
3281
+ active: "Yes",
3282
+ inactive: "No",
3283
+ withGuide: true
3284
+ });
3285
+ systemApproved = !Ct(proceed) && Boolean(proceed);
1052
3286
  }
1053
- if (interactive && !skipApplyConfirm && hasPlannedChanges) {
3287
+ let projectApproved = parsed.yes || !hasInstallMutation;
3288
+ if (interactive && hasInstallMutation) {
1054
3289
  const proceed = await Rt({
1055
3290
  message: getApplyConfirmationMessage({
1056
- existingManifest,
3291
+ existingManifest: planningManifest,
1057
3292
  installIntent
1058
3293
  }),
1059
3294
  initialValue: true,
@@ -1061,34 +3296,499 @@ async function runCli(argv = process.argv.slice(2)) {
1061
3296
  inactive: "No",
1062
3297
  withGuide: true
1063
3298
  });
1064
- if (Ct(proceed) || !proceed) {
1065
- output.write("Installer cancelled.\n");
1066
- return;
3299
+ projectApproved = !Ct(proceed) && Boolean(proceed);
3300
+ }
3301
+ if (!systemApproved) {
3302
+ if (jsonOutput) writeCanonicalSetupResult({ status: "blocked", dryRun: false, targetRoot: targetDir, prepared: preparedSystemSetup, genericMcp: genericMcpPlan, storeBridge: storeBridgePreview, projectRecovery: priorProjectRecovery, storeMutationState: "none", projectChanged: recoveredProjectChanged, projectMutationState: recoveredProjectChanged ? "applied" : "none", projectActions: plan.actions, failedCondition: "Machine setup was not approved.", nextAction: "Run setup with --yes after you review the plan." });
3303
+ else output.write("Machine setup was not approved. No system or project files were changed.\n");
3304
+ return;
3305
+ }
3306
+ let appliedStoreBridge = storeBridgePreview;
3307
+ try {
3308
+ const checkpoint9 = executeStoreCheckpoint9Migration({
3309
+ projectRoot: targetDir,
3310
+ storeRoot
3311
+ });
3312
+ if (!checkpoint9.setupMayContinue) {
3313
+ throw new Checkpoint9ReceiptProjectionError(checkpoint9);
3314
+ }
3315
+ const observedStoreBridge = previewStoreCompatibilityBridge(storeRoot);
3316
+ appliedStoreBridge = {
3317
+ ...storeBridgePreview,
3318
+ storeState: observedStoreBridge.storeState,
3319
+ blockers: observedStoreBridge.blockers,
3320
+ nextAction: observedStoreBridge.nextAction
3321
+ };
3322
+ } catch (error) {
3323
+ const failedCondition = error instanceof Error ? error.message : String(error);
3324
+ let observedStoreBridge = storeBridgePreview;
3325
+ try {
3326
+ observedStoreBridge = previewStoreCompatibilityBridge(storeRoot);
3327
+ } catch {
3328
+ }
3329
+ const nextAction = storePrerequisiteFailureAction(error);
3330
+ const failedStoreBridge = {
3331
+ ...storeBridgePreview,
3332
+ storeState: observedStoreBridge.storeState,
3333
+ blockers: observedStoreBridge.blockers,
3334
+ nextAction
3335
+ };
3336
+ const storeMutationState = observedStoreBridge.storeState === "supported-current" ? "applied" : observedStoreBridge.storeState === storeBridgePreview.storeState && observedStoreBridge.sourceSchemaVersion === storeBridgePreview.sourceSchemaVersion ? "none" : "partial";
3337
+ if (jsonOutput) {
3338
+ writeCanonicalSetupResult({
3339
+ status: "blocked",
3340
+ dryRun: false,
3341
+ targetRoot: targetDir,
3342
+ prepared: preparedSystemSetup,
3343
+ genericMcp: genericMcpPlan,
3344
+ storeBridge: failedStoreBridge,
3345
+ projectRecovery: priorProjectRecovery,
3346
+ storeMutationState,
3347
+ projectChanged: recoveredProjectChanged,
3348
+ projectMutationState: recoveredProjectChanged ? "applied" : "none",
3349
+ projectActions: plan.actions,
3350
+ failedCondition,
3351
+ nextAction
3352
+ });
3353
+ } else {
3354
+ output.write(`Setup stopped at the Store prerequisite. ${failedCondition}
3355
+ Next: ${nextAction}
3356
+ `);
1067
3357
  }
3358
+ return;
1068
3359
  }
1069
- const applied = applyInstallPlan({
1070
- targetDir,
1071
- plan,
1072
- existingManifest
3360
+ const reviewedSystemFingerprint = setupSystemReviewFingerprint(preparedSystemSetup);
3361
+ const refreshedSystemSetup = await prepareSystemSetupCommand({
3362
+ ...systemOptions,
3363
+ promptForMethods: false,
3364
+ methods: { ...preparedSystemSetup.selections }
1073
3365
  });
1074
- if (hasPlannedChanges) {
1075
- writeApplyCompletionSummary({
3366
+ const systemReviewChanged = setupSystemReviewFingerprint(refreshedSystemSetup) !== reviewedSystemFingerprint;
3367
+ preparedSystemSetup = refreshedSystemSetup;
3368
+ reviewedHarnessIntegrations = buildReviewedHarnessIntegrations();
3369
+ if (systemReviewChanged) {
3370
+ if (!jsonOutput) {
3371
+ output.write(
3372
+ "The verified Store state changed the computer review. Review the current computer plan.\n"
3373
+ );
3374
+ Vt(preparedSystemSetup.review, "This computer");
3375
+ }
3376
+ systemApproved = parsed.yes || !preparedSystemSetup.changed;
3377
+ if (interactive && preparedSystemSetup.changed) {
3378
+ const proceed = await Rt({
3379
+ message: "Apply the reviewed changes to this computer?",
3380
+ initialValue: false,
3381
+ active: "Yes",
3382
+ inactive: "No",
3383
+ withGuide: true
3384
+ });
3385
+ systemApproved = !Ct(proceed) && Boolean(proceed);
3386
+ }
3387
+ if (!systemApproved) {
3388
+ const nextAction = "Run `make-docs setup` again to review the current computer and project plans.";
3389
+ if (jsonOutput) {
3390
+ writeCanonicalSetupResult({
3391
+ status: "blocked",
3392
+ dryRun: false,
3393
+ targetRoot: targetDir,
3394
+ prepared: preparedSystemSetup,
3395
+ genericMcp: genericMcpPlan,
3396
+ storeBridge: appliedStoreBridge,
3397
+ projectRecovery: priorProjectRecovery,
3398
+ storeMutationState: storeBridgePreview.changes.store.length > 0 ? "applied" : "none",
3399
+ projectChanged: recoveredProjectChanged,
3400
+ projectMutationState: recoveredProjectChanged ? "applied" : "none",
3401
+ projectActions: plan.actions,
3402
+ failedCondition: "The refreshed computer setup was not approved.",
3403
+ nextAction
3404
+ });
3405
+ } else {
3406
+ output.write(`The refreshed computer changes were not approved. Setup did not apply the refreshed computer or project plan. Next: ${nextAction}
3407
+ `);
3408
+ }
3409
+ return;
3410
+ }
3411
+ }
3412
+ const postStoreProjectReview = await reloadProjectReview();
3413
+ if (postStoreProjectReview === "cancelled") return;
3414
+ if (installationStatus.status === "recovery-required") {
3415
+ return runCli(argv, priorProjectRecovery, recoveredProjectChanged);
3416
+ }
3417
+ if (postStoreProjectReview === "changed") {
3418
+ if (!jsonOutput) {
3419
+ output.write(
3420
+ "The verified Store state changed the project review. Review the current project plan.\n"
3421
+ );
3422
+ printPlan({
3423
+ actions: plan.actions,
3424
+ dryRun: false,
3425
+ existingManifest: planningManifest,
3426
+ installIntent,
3427
+ packageName: plan.packageName,
3428
+ packageVersion: plan.packageVersion,
3429
+ selectionSource,
3430
+ targetDir,
3431
+ compatibilityClassification: freshInstallTarget ? null : compatibilityClassification,
3432
+ config: makeDocsConfig,
3433
+ selectedResourceTypes: plan.profile.selections.resourceProjection,
3434
+ selectedCapabilities: plan.profile.effectiveCapabilities,
3435
+ stops: plan.stops ?? []
3436
+ });
3437
+ if (projectHarnessConfig.changed) {
3438
+ output.write("Project harness intent: update .make-docs/config.yaml after machine verification.\n");
3439
+ }
3440
+ }
3441
+ const refreshedConflicts = findReviewableManagedFileConflicts(plan);
3442
+ if (!interactive && refreshedConflicts.length > 0) {
3443
+ throw new Error(
3444
+ [
3445
+ "The verified Store state changed the project plan and found unresolved managed-file diffs.",
3446
+ "Run `make-docs setup` without `--yes` to review the conflicts interactively.",
3447
+ "",
3448
+ ...buildCompatibilitySummaryLines(compatibilityClassification),
3449
+ "",
3450
+ "Conflicting managed files:",
3451
+ ...refreshedConflicts.map((conflict) => `- ${conflict.relativePath}`)
3452
+ ].join("\n")
3453
+ );
3454
+ }
3455
+ if (projectApproved) {
3456
+ projectApproved = parsed.yes || !hasInstallMutation;
3457
+ if (interactive && hasInstallMutation) {
3458
+ const proceed = await Rt({
3459
+ message: getApplyConfirmationMessage({ existingManifest: planningManifest, installIntent }),
3460
+ initialValue: true,
3461
+ active: "Yes",
3462
+ inactive: "No",
3463
+ withGuide: true
3464
+ });
3465
+ projectApproved = !Ct(proceed) && Boolean(proceed);
3466
+ }
3467
+ }
3468
+ }
3469
+ const systemSetup = await applyPreparedSystemSetup(preparedSystemSetup);
3470
+ const appliedGenericMcpPlan = genericMcpPlan ? applyGenericMcpSetup(genericMcpPlan) : null;
3471
+ if (!jsonOutput && appliedGenericMcpPlan?.configuration) {
3472
+ output.write(renderGenericMcpSetupResult(appliedGenericMcpPlan));
3473
+ }
3474
+ if (["blocked", "failed", "recovery"].includes(systemSetup.status)) {
3475
+ if (jsonOutput) writeCanonicalSetupResult({ status: "blocked", dryRun: false, targetRoot: targetDir, system: systemSetup, prepared: preparedSystemSetup, genericMcp: appliedGenericMcpPlan, storeBridge: appliedStoreBridge, projectRecovery: priorProjectRecovery, projectChanged: recoveredProjectChanged, projectMutationState: recoveredProjectChanged ? "applied" : "none", projectActions: plan.actions, failedCondition: systemSetup.blocked[0]?.reason ?? systemSetup.status, nextAction: systemSetup.recoveryAction });
3476
+ else output.write(`Setup stopped at machine scope. ${systemSetup.recoveryAction ?? "Review the machine state."}
3477
+ `);
3478
+ return;
3479
+ }
3480
+ if (!projectApproved) {
3481
+ if (jsonOutput) writeCanonicalSetupResult({ status: "blocked", dryRun: false, targetRoot: targetDir, system: systemSetup, prepared: preparedSystemSetup, genericMcp: appliedGenericMcpPlan, storeBridge: appliedStoreBridge, projectRecovery: priorProjectRecovery, projectChanged: recoveredProjectChanged, projectMutationState: recoveredProjectChanged ? "applied" : "none", projectActions: plan.actions, failedCondition: "Project setup was not approved.", nextAction: "Run setup with --yes after you review the project plan." });
3482
+ else output.write("This computer remains configured. Project setup was not approved. Run `make-docs setup` to review the project change.\n");
3483
+ return;
3484
+ }
3485
+ let projectPrerequisiteChanged = recoveredProjectChanged;
3486
+ if (legacyState.sources.length) {
3487
+ const imported = importLegacyInstallationState(targetDir, storeRoot);
3488
+ projectPrerequisiteChanged = true;
3489
+ if (imported.recoveryRequired) {
3490
+ return runCli(argv, priorProjectRecovery, true);
3491
+ }
3492
+ const postImportProjectReview = await reloadProjectReview();
3493
+ if (postImportProjectReview === "cancelled") return;
3494
+ if (installationStatus.status === "recovery-required") {
3495
+ return runCli(argv, priorProjectRecovery, true);
3496
+ }
3497
+ if (postImportProjectReview === "changed") {
3498
+ if (!jsonOutput) {
3499
+ output.write(
3500
+ "The legacy installation transfer changed the project review. Review the current project plan.\n"
3501
+ );
3502
+ printPlan({
3503
+ actions: plan.actions,
3504
+ dryRun: false,
3505
+ existingManifest: planningManifest,
3506
+ installIntent,
3507
+ packageName: plan.packageName,
3508
+ packageVersion: plan.packageVersion,
3509
+ selectionSource,
3510
+ targetDir,
3511
+ compatibilityClassification: freshInstallTarget ? null : compatibilityClassification,
3512
+ config: makeDocsConfig,
3513
+ selectedResourceTypes: plan.profile.selections.resourceProjection,
3514
+ selectedCapabilities: plan.profile.effectiveCapabilities,
3515
+ stops: plan.stops ?? []
3516
+ });
3517
+ if (projectHarnessConfig.changed) {
3518
+ output.write("Project harness intent: update .make-docs/config.yaml after machine verification.\n");
3519
+ }
3520
+ }
3521
+ const refreshedConflicts = findReviewableManagedFileConflicts(plan);
3522
+ if (!interactive && refreshedConflicts.length > 0) {
3523
+ throw new Error(
3524
+ [
3525
+ "The legacy installation transfer changed the project plan and found unresolved managed-file diffs.",
3526
+ "Run `make-docs setup` without `--yes` to review the conflicts interactively.",
3527
+ "",
3528
+ ...buildCompatibilitySummaryLines(compatibilityClassification),
3529
+ "",
3530
+ "Conflicting managed files:",
3531
+ ...refreshedConflicts.map((conflict) => `- ${conflict.relativePath}`)
3532
+ ].join("\n")
3533
+ );
3534
+ }
3535
+ projectApproved = parsed.yes || !hasInstallMutation;
3536
+ if (interactive && hasInstallMutation) {
3537
+ const proceed = await Rt({
3538
+ message: getApplyConfirmationMessage({ existingManifest: planningManifest, installIntent }),
3539
+ initialValue: true,
3540
+ active: "Yes",
3541
+ inactive: "No",
3542
+ withGuide: true
3543
+ });
3544
+ projectApproved = !Ct(proceed) && Boolean(proceed);
3545
+ }
3546
+ if (!projectApproved) {
3547
+ if (jsonOutput) {
3548
+ writeCanonicalSetupResult({
3549
+ status: "blocked",
3550
+ dryRun: false,
3551
+ targetRoot: targetDir,
3552
+ system: systemSetup,
3553
+ prepared: preparedSystemSetup,
3554
+ genericMcp: appliedGenericMcpPlan,
3555
+ storeBridge: appliedStoreBridge,
3556
+ projectRecovery: priorProjectRecovery,
3557
+ projectChanged: true,
3558
+ projectMutationState: "applied",
3559
+ projectActions: plan.actions,
3560
+ failedCondition: "The current project plan was not approved after legacy transfer.",
3561
+ nextAction: "Run setup again to review the current project plan."
3562
+ });
3563
+ } else {
3564
+ output.write(
3565
+ "This computer remains configured. Legacy state was transferred. The current project plan was not approved. Run `make-docs setup` to review it.\n"
3566
+ );
3567
+ }
3568
+ return;
3569
+ }
3570
+ }
3571
+ }
3572
+ let applied;
3573
+ try {
3574
+ applied = !freshInstallTarget && hasInstallMutation && completedRemovalHandoff.status !== "ready" ? executeInstallPlanMigration({
3575
+ projectRoot: targetDir,
3576
+ storeRoot,
3577
+ compatibility: compatibilityClassification,
3578
+ installPlan: plan,
3579
+ existingManifest,
3580
+ projectHarnessConfig
3581
+ }) : applyInstallPlan({
3582
+ targetDir,
3583
+ plan,
1076
3584
  existingManifest,
3585
+ projectHarnessConfig
3586
+ });
3587
+ } catch (error) {
3588
+ const failedCondition = error instanceof Error ? error.message : String(error);
3589
+ if (jsonOutput) {
3590
+ const failedProjectStatus = readInstallationStatus(targetDir, storeRoot);
3591
+ const projectMutationState = failedProjectStatus.status === "recovery-required" ? "partial" : projectPrerequisiteChanged ? "applied" : "none";
3592
+ writeCanonicalSetupResult({
3593
+ status: "blocked",
3594
+ dryRun: false,
3595
+ targetRoot: targetDir,
3596
+ system: systemSetup,
3597
+ prepared: preparedSystemSetup,
3598
+ genericMcp: appliedGenericMcpPlan,
3599
+ storeBridge: appliedStoreBridge,
3600
+ projectRecovery: priorProjectRecovery,
3601
+ projectChanged: projectMutationState !== "none",
3602
+ projectMutationState,
3603
+ projectActions: plan.actions,
3604
+ failedCondition,
3605
+ nextAction: "Run make-docs setup again to review and recover the project change."
3606
+ });
3607
+ return;
3608
+ }
3609
+ if (systemSetup.status === "configured" || systemSetup.status === "unchanged") {
3610
+ output.write(
3611
+ "This computer remains configured. Project scope failed. Run `make-docs setup` to review and resume the project change.\n"
3612
+ );
3613
+ }
3614
+ throw error;
3615
+ }
3616
+ if (existingManifest && !existingManifest.projectId && applied.manifest.projectId) {
3617
+ output.write(
3618
+ `Minted stable project identifier ${applied.manifest.projectId} in .make-docs/config.yaml (this install predated project identifiers; the identifier keys this project's operational state in the global store and never changes).
3619
+ `
3620
+ );
3621
+ }
3622
+ if (hasInstallMutation && !jsonOutput) {
3623
+ writeApplyCompletionSummary({
3624
+ existingManifest: planningManifest,
1077
3625
  installIntent,
1078
3626
  manifest: applied.manifest,
1079
3627
  targetDir
1080
3628
  });
1081
3629
  }
1082
- if (applied.conflictFiles.length > 0) {
3630
+ if (applied.conflictFiles.length > 0 && !jsonOutput) {
1083
3631
  output.write("Conflicts were staged for manual review:\n");
1084
3632
  for (const conflictFile of applied.conflictFiles) {
1085
3633
  output.write(`- ${conflictFile}
1086
3634
  `);
1087
3635
  }
1088
3636
  }
3637
+ if (jsonOutput) {
3638
+ writeCanonicalSetupResult({
3639
+ status: "complete",
3640
+ dryRun: false,
3641
+ targetRoot: targetDir,
3642
+ system: systemSetup,
3643
+ prepared: preparedSystemSetup,
3644
+ genericMcp: appliedGenericMcpPlan,
3645
+ storeBridge: appliedStoreBridge,
3646
+ projectRecovery: priorProjectRecovery,
3647
+ projectChanged: projectPrerequisiteChanged || applied.mutationApplied,
3648
+ projectMutationState: projectPrerequisiteChanged || applied.mutationApplied ? "applied" : "none",
3649
+ projectActions: applied.appliedActions,
3650
+ failedCondition: null,
3651
+ nextAction: null
3652
+ });
3653
+ }
3654
+ }
3655
+ async function runProjectPathHygieneCommand(argv, repair = false, launch = resolveCliOperationLaunch()) {
3656
+ try {
3657
+ let scope;
3658
+ const paths = [];
3659
+ let format = "json";
3660
+ let apply = false;
3661
+ let preview = false;
3662
+ let targetRoot;
3663
+ let manifest;
3664
+ let includeSkills = false;
3665
+ let allowCommentToken;
3666
+ const args = [...argv];
3667
+ while (args.length > 0) {
3668
+ const arg = args.shift();
3669
+ if (arg === "--target" || arg === "--target-root") {
3670
+ const value = args.shift();
3671
+ if (!value) throw new Error(`\`${arg}\` requires a path.`);
3672
+ targetRoot = path4.resolve(value);
3673
+ } else if (arg === "--manifest") {
3674
+ const value = args.shift();
3675
+ if (!value) throw new Error("`--manifest` requires a path.");
3676
+ manifest = value;
3677
+ } else if (arg === "--include-skills") {
3678
+ includeSkills = true;
3679
+ } else if (arg === "--allow-comment-token") {
3680
+ const value = args.shift();
3681
+ if (!value) throw new Error("`--allow-comment-token` requires text.");
3682
+ allowCommentToken = value;
3683
+ } else if (arg === "--scope") {
3684
+ const value = args.shift();
3685
+ if (value !== "content" && value !== "managed") throw new Error("--scope requires content or managed.");
3686
+ scope = value;
3687
+ } else if (arg === "--path") {
3688
+ const value = args.shift();
3689
+ if (!value) throw new Error("--path requires a path.");
3690
+ paths.push(value);
3691
+ } else if (arg === "--format") {
3692
+ const value = args.shift();
3693
+ if (value !== "text" && value !== "json") throw new Error("--format requires text or json.");
3694
+ format = value;
3695
+ } else if (repair && arg === "--apply") {
3696
+ apply = true;
3697
+ } else if (repair && arg === "--dry-run") {
3698
+ preview = true;
3699
+ } else {
3700
+ throw new Error(`Unknown project path-hygiene option: \`${arg}\`.`);
3701
+ }
3702
+ }
3703
+ if (apply && preview) throw new Error("--apply and --dry-run cannot be combined.");
3704
+ const invocation = await invokeOperation(
3705
+ repair ? "project.path-hygiene.repair" : "project.path-hygiene.validate",
3706
+ {
3707
+ ...targetRoot ? { targetRoot } : {},
3708
+ ...manifest ? { manifest } : {},
3709
+ ...includeSkills ? { includeSkills } : {},
3710
+ ...allowCommentToken ? { allowCommentToken } : {},
3711
+ ...scope ? { scope } : {},
3712
+ ...paths.length ? { paths } : {},
3713
+ ...repair ? { apply } : {}
3714
+ },
3715
+ createExecutionContext({
3716
+ surface: "cli",
3717
+ route: launch.route,
3718
+ callerIdentityRaw: launch.callerIdentityRaw,
3719
+ callerReference: launch.callerReference,
3720
+ cwd: targetRoot,
3721
+ writesAllowed: repair,
3722
+ dryRun: repair && !apply
3723
+ })
3724
+ );
3725
+ const result = invocation.value;
3726
+ if (format === "json") output.write(JSON.stringify(result, null, 2) + "\n");
3727
+ else {
3728
+ output.write("Scope: " + result.inventorySource + "; checked " + result.checkedFiles + " file(s).\n");
3729
+ for (const finding of result.findings) output.write(finding.file + ":" + finding.line + ":" + finding.column + " " + (finding.allowed ? "allowed " : "") + finding.kind + " " + finding.match + "\n");
3730
+ for (const error of result.ioErrors) output.write("ERROR: " + error + "\n");
3731
+ for (const change of result.proposedChanges ?? []) output.write((result.dryRun ? "Proposed: " : "Repair: ") + change.file + "\n" + change.after + "\n");
3732
+ output.write((result.valid ? "PASS" : "FAIL") + ": " + result.failingFindings + " finding(s), " + result.changedFiles.length + " file(s) changed.\n");
3733
+ }
3734
+ process.exitCode = result.ioErrors.length ? 2 : result.valid ? 0 : 1;
3735
+ } catch (error) {
3736
+ process.stderr.write("Path check error: " + (error instanceof Error ? error.message : String(error)) + "\n");
3737
+ process.exitCode = 2;
3738
+ }
3739
+ }
3740
+ function setupSystemReviewFingerprint(prepared) {
3741
+ return JSON.stringify([
3742
+ prepared.changed,
3743
+ prepared.review
3744
+ ]);
3745
+ }
3746
+ function setupProjectReviewFingerprint(plan, projectHarnessConfig) {
3747
+ const stablePlan = {
3748
+ packageName: plan.packageName,
3749
+ packageVersion: plan.packageVersion,
3750
+ profile: plan.profile,
3751
+ systemAssetMaterialization: plan.systemAssetMaterialization,
3752
+ actions: plan.actions,
3753
+ desiredFiles: plan.desiredFiles,
3754
+ desiredSkillFiles: plan.desiredSkillFiles,
3755
+ operation: plan.operation,
3756
+ stops: plan.stops,
3757
+ forceManifestWrite: plan.forceManifestWrite
3758
+ };
3759
+ return JSON.stringify([
3760
+ stablePlan,
3761
+ projectHarnessConfig
3762
+ ]);
1089
3763
  }
1090
3764
  function inferInstallIntent(parsed) {
1091
- return parsed.command === "reconfigure" ? "reconfigure" : "apply";
3765
+ return parsed.setupSubcommand === "reconfigure" ? "reconfigure" : "apply";
3766
+ }
3767
+ function printInstallStatus(options) {
3768
+ const { targetDir, manifest, classification } = options;
3769
+ const lines = [`make-docs install detected in ${targetDir}.`, ""];
3770
+ if (manifest) {
3771
+ const capabilities = Object.entries(manifest.selections.capabilities).filter(([, enabled]) => enabled).map(([name]) => name);
3772
+ const harnesses = Object.entries(manifest.selections.harnesses).filter(([, enabled]) => enabled).map(([name]) => name);
3773
+ lines.push(
3774
+ `Package: ${manifest.packageName}@${manifest.packageVersion}`,
3775
+ `Last applied: ${manifest.updatedAt}`,
3776
+ `Capabilities: ${capabilities.join(", ") || "none"}`,
3777
+ `Harnesses: ${harnesses.join(", ") || "none"}`,
3778
+ `Skills: ${manifest.selections.skills ? `${manifest.selections.selectedSkills.length} selected (${manifest.selections.skillScope} scope)` : "disabled"}`,
3779
+ `Local resource projection: ${(manifest.selections.resourceProjection ?? []).join(", ") || "none"}`
3780
+ );
3781
+ } else {
3782
+ lines.push("A manifest is present but could not be parsed.");
3783
+ }
3784
+ lines.push(...buildCompatibilitySummaryLines(classification));
3785
+ lines.push(
3786
+ "",
3787
+ "Bare `make-docs` never syncs an existing install.",
3788
+ "Use `make-docs setup` to sync, `make-docs setup reconfigure` to change project selections, or `make-docs setup skills` to change skill selections.",
3789
+ ""
3790
+ );
3791
+ output.write(lines.join("\n"));
1092
3792
  }
1093
3793
  function describeSelectionSource(options) {
1094
3794
  const { parsed, existingManifest, installIntent } = options;
@@ -1104,6 +3804,9 @@ function resolveSelections(options) {
1104
3804
  const { parsed, existingManifest } = options;
1105
3805
  const baseSelections = existingManifest ? existingManifest.selections : defaultSelections();
1106
3806
  const selections = cloneSelections(baseSelections);
3807
+ if (selections.resourceProjection === void 0 && (!existingManifest || parsed.setupSubcommand === "reconfigure")) {
3808
+ selections.resourceProjection = [];
3809
+ }
1107
3810
  if (parsed.noDesigns) {
1108
3811
  selections.capabilities.designs = false;
1109
3812
  }
@@ -1122,6 +3825,12 @@ function resolveSelections(options) {
1122
3825
  if (parsed.noClaudeCode) {
1123
3826
  selections.harnesses["claude-code"] = false;
1124
3827
  }
3828
+ if (parsed.codexMethod !== void 0) {
3829
+ selections.harnesses.codex = true;
3830
+ }
3831
+ if (parsed.claudeCodeMethod !== void 0) {
3832
+ selections.harnesses["claude-code"] = true;
3833
+ }
1125
3834
  if (parsed.noSkills) {
1126
3835
  selections.skills = false;
1127
3836
  selections.selectedSkills = [];
@@ -1136,21 +3845,73 @@ function resolveSelections(options) {
1136
3845
  selections.selectedSkills = [...parsed.selectedSkills];
1137
3846
  }
1138
3847
  }
3848
+ if (parsed.projectResources !== void 0) {
3849
+ selections.resourceProjection = [...parsed.projectResources];
3850
+ }
1139
3851
  return selections;
1140
3852
  }
3853
+ function inferCompletedRemovalResourceProjection(manifest) {
3854
+ const resourceUris = /* @__PURE__ */ new Set([
3855
+ ...Object.keys(manifest.resourceProjection?.resources ?? {}),
3856
+ ...Object.values(manifest.files).map((entry) => entry.sourceId).filter((sourceId) => sourceId.startsWith("resource:")).map((sourceId) => sourceId.slice("resource:".length))
3857
+ ]);
3858
+ if (resourceUris.size === 0) return null;
3859
+ const selected = /* @__PURE__ */ new Set();
3860
+ for (const uri of resourceUris) {
3861
+ const type = PROJECT_RESOURCE_TYPES.find(
3862
+ (candidate) => uri.startsWith(`make-docs://system/${candidate}/`)
3863
+ );
3864
+ if (!type) return null;
3865
+ selected.add(type);
3866
+ }
3867
+ return PROJECT_RESOURCE_TYPES.filter((type) => selected.has(type));
3868
+ }
3869
+ var EXISTING_INSTALL_SKILL_SELECTION_CHANGE_ERROR = "Existing installs cannot change skill selections with `make-docs setup` or `make-docs setup reconfigure`. Use `make-docs setup skills` to change the enabled state, scope, selected names, source, or provenance. This setup kept the saved Skill selection. Other reviewed setup parts can continue.";
3870
+ function reconcileExistingInstallSkillSelection(options) {
3871
+ const { existingManifest, selections } = options;
3872
+ if (!existingManifest) {
3873
+ return { selections, routed: false };
3874
+ }
3875
+ const existingSelections = existingManifest.selections;
3876
+ const existingSkillNames = [...existingSelections.selectedSkills].sort();
3877
+ const requestedSkillNames = [...selections.selectedSkills].sort();
3878
+ const selectedSkillNamesChanged = existingSkillNames.length !== requestedSkillNames.length || existingSkillNames.some((name, index) => name !== requestedSkillNames[index]);
3879
+ const existingSkillBinding = JSON.stringify({
3880
+ manifest: existingSelections.skillManifest ?? null,
3881
+ provenance: [...existingSelections.skillSelectionProvenance ?? []].sort(
3882
+ (left, right) => left.skillName.localeCompare(right.skillName)
3883
+ )
3884
+ });
3885
+ const requestedSkillBinding = JSON.stringify({
3886
+ manifest: selections.skillManifest ?? null,
3887
+ provenance: [...selections.skillSelectionProvenance ?? []].sort(
3888
+ (left, right) => left.skillName.localeCompare(right.skillName)
3889
+ )
3890
+ });
3891
+ if (existingSelections.skills !== selections.skills || existingSelections.skillScope !== selections.skillScope || selectedSkillNamesChanged || existingSkillBinding !== requestedSkillBinding) {
3892
+ const reconciled = cloneSelections(selections);
3893
+ reconciled.skills = existingSelections.skills;
3894
+ reconciled.skillScope = existingSelections.skillScope;
3895
+ reconciled.selectedSkills = [...existingSelections.selectedSkills];
3896
+ reconciled.skillManifest = existingSelections.skillManifest ? { ...existingSelections.skillManifest } : void 0;
3897
+ reconciled.skillSelectionProvenance = existingSelections.skillSelectionProvenance ? existingSelections.skillSelectionProvenance.map((record) => ({ ...record })) : void 0;
3898
+ return { selections: reconciled, routed: true };
3899
+ }
3900
+ return { selections, routed: false };
3901
+ }
1141
3902
  function hasSelectionOverrides(parsed) {
1142
3903
  return Boolean(
1143
- parsed.noDesigns || parsed.noPlans || parsed.noPrd || parsed.noWork || parsed.noCodex || parsed.noClaudeCode || parsed.noSkills || parsed.skillScope || parsed.selectedSkills !== void 0
3904
+ parsed.noDesigns || parsed.noPlans || parsed.noPrd || parsed.noWork || parsed.noCodex || parsed.noClaudeCode || parsed.codexMethod !== void 0 || parsed.claudeCodeMethod !== void 0 || parsed.noSkills || parsed.skillsManifest || parsed.skillScope || parsed.selectedSkills !== void 0 || parsed.projectResources !== void 0
1144
3905
  );
1145
3906
  }
1146
- function isLifecycleCommand(command) {
1147
- return command === "backup" || command === "uninstall";
3907
+ function isLifecycleCommand(parsed) {
3908
+ return parsed.setupSubcommand === "backup" || parsed.setupSubcommand === "remove";
1148
3909
  }
1149
3910
  async function loadUninstallCommand() {
1150
3911
  if (uninstallCommandLoaderOverride) {
1151
3912
  return uninstallCommandLoaderOverride();
1152
3913
  }
1153
- const uninstallModule = await import("./uninstall-GQE4SJF2.js");
3914
+ const uninstallModule = await import("./uninstall-3UXXXNFO.js");
1154
3915
  if (typeof uninstallModule.runUninstallCommand !== "function") {
1155
3916
  throw new Error(
1156
3917
  "The `uninstall` command module must export `runUninstallCommand(options)`."
@@ -1163,7 +3924,7 @@ async function runSkillsCommand(options) {
1163
3924
  await skillsCommandRunnerOverride(options);
1164
3925
  return;
1165
3926
  }
1166
- const skillsModule = await import("./skills-command-3ESCZ75U.js");
3927
+ const skillsModule = await import("./skills-command-MGGHY7HU.js");
1167
3928
  await skillsModule.runSkillsCommand(options);
1168
3929
  }
1169
3930
  function getSelectionOverrideFlags(parsed) {
@@ -1186,15 +3947,29 @@ function getSelectionOverrideFlags(parsed) {
1186
3947
  if (parsed.noClaudeCode) {
1187
3948
  flags.push("--no-claude-code");
1188
3949
  }
3950
+ if (parsed.codexMethod !== void 0) {
3951
+ flags.push("--codex-method");
3952
+ }
3953
+ if (parsed.claudeCodeMethod !== void 0) {
3954
+ flags.push("--claude-code-method");
3955
+ }
3956
+ if (parsed.genericMcpClient !== void 0) flags.push("--generic-mcp-client");
3957
+ if (parsed.genericMcpAction !== void 0) flags.push("--generic-mcp-action");
1189
3958
  if (parsed.noSkills) {
1190
3959
  flags.push("--no-skills");
1191
3960
  }
3961
+ if (parsed.skillsManifest) {
3962
+ flags.push("--skill-manifest");
3963
+ }
1192
3964
  if (parsed.skillScope) {
1193
3965
  flags.push("--skill-scope");
1194
3966
  }
1195
- if (parsed.selectedSkills !== void 0) {
3967
+ if (parsed.selectedSkillsValue !== void 0) {
1196
3968
  flags.push("--selected-skills");
1197
3969
  }
3970
+ if (parsed.projectResources !== void 0) {
3971
+ flags.push("--project-resources");
3972
+ }
1198
3973
  return flags;
1199
3974
  }
1200
3975
  function parseArgs(argv) {
@@ -1210,15 +3985,61 @@ function parseArgs(argv) {
1210
3985
  noWork: false,
1211
3986
  noCodex: false,
1212
3987
  noClaudeCode: false,
1213
- noSkills: false
3988
+ json: false,
3989
+ noSkills: false,
3990
+ runArgs: []
1214
3991
  };
1215
3992
  const args = [...argv];
1216
3993
  rejectRemovedUpdateReconfigure(args);
1217
3994
  rejectRemovedReconfigureFlag(args);
1218
3995
  rejectRemovedCommand(args);
1219
- if (args[0] === "reconfigure" || args[0] === "skills" || args[0] === "backup" || args[0] === "uninstall") {
3996
+ if (args[0] === "setup" || args[0] === "project" || args[0] === "resource" || args[0] === "run" || args[0] === "mcp" || args[0] === "update" || args[0] === "uninstall") {
1220
3997
  parsed.command = args.shift();
1221
3998
  }
3999
+ if (parsed.command === "setup" && (args[0] === "system" || args[0] === "reconfigure" || args[0] === "skills" || args[0] === "backup" || args[0] === "remove")) {
4000
+ parsed.setupSubcommand = args.shift();
4001
+ }
4002
+ if (parsed.command === "run" || parsed.command === "resource" || parsed.command === "project") {
4003
+ parsed.runArgs = args;
4004
+ return parsed;
4005
+ }
4006
+ if (parsed.command === "update" || parsed.command === "uninstall") {
4007
+ while (args.length > 0) {
4008
+ const arg = args.shift();
4009
+ switch (arg) {
4010
+ case "--help":
4011
+ case "-h":
4012
+ parsed.help = true;
4013
+ break;
4014
+ case "--yes":
4015
+ parsed.yes = true;
4016
+ break;
4017
+ case "--remove-store":
4018
+ if (parsed.command !== "uninstall") throw new Error("--remove-store is valid only with make-docs uninstall.");
4019
+ parsed.removeStore = true;
4020
+ break;
4021
+ case "--target":
4022
+ if (parsed.command !== "update") {
4023
+ throw new Error("`--target` is not valid with `make-docs uninstall`; it removes the machine-level footprint, not a project.");
4024
+ }
4025
+ parsed.targetDir = args.shift();
4026
+ break;
4027
+ default:
4028
+ throw new Error(`Unknown argument: ${arg}`);
4029
+ }
4030
+ }
4031
+ return parsed;
4032
+ }
4033
+ if (parsed.command === "mcp") {
4034
+ for (const arg of args) {
4035
+ if (arg === "--help" || arg === "-h") {
4036
+ parsed.help = true;
4037
+ continue;
4038
+ }
4039
+ throw new Error(`Unknown argument: ${arg}`);
4040
+ }
4041
+ return parsed;
4042
+ }
1222
4043
  while (args.length > 0) {
1223
4044
  const arg = args.shift();
1224
4045
  switch (arg) {
@@ -1231,6 +4052,17 @@ function parseArgs(argv) {
1231
4052
  case "--yes":
1232
4053
  parsed.yes = true;
1233
4054
  break;
4055
+ case "--json":
4056
+ parsed.json = true;
4057
+ break;
4058
+ case "--recover": {
4059
+ const value = args.shift();
4060
+ if (value !== "resume" && value !== "restore") {
4061
+ throw new Error("`--recover` must be either `resume` or `restore`.");
4062
+ }
4063
+ parsed.projectRecovery = value;
4064
+ break;
4065
+ }
1234
4066
  case "--help":
1235
4067
  case "-h":
1236
4068
  parsed.help = true;
@@ -1261,41 +4093,134 @@ function parseArgs(argv) {
1261
4093
  case "--no-claude":
1262
4094
  parsed.noClaudeCode = true;
1263
4095
  break;
4096
+ case "--codex-method": {
4097
+ const value = args.shift();
4098
+ if (value !== "none" && value !== "mcp" && value !== "command-rules") {
4099
+ throw new Error("`--codex-method` must be none, mcp, or command-rules.");
4100
+ }
4101
+ parsed.codexMethod = value;
4102
+ break;
4103
+ }
4104
+ case "--claude-code-method": {
4105
+ const value = args.shift();
4106
+ if (value !== "none" && value !== "mcp" && value !== "permission-rules") {
4107
+ throw new Error("`--claude-code-method` must be none, mcp, or permission-rules.");
4108
+ }
4109
+ parsed.claudeCodeMethod = value;
4110
+ break;
4111
+ }
4112
+ case "--generic-mcp-client": {
4113
+ const value = args.shift();
4114
+ if (!value) throw new Error("`--generic-mcp-client` requires a stable local client label.");
4115
+ parsed.genericMcpClient = value;
4116
+ break;
4117
+ }
4118
+ case "--generic-mcp-action": {
4119
+ const value = args.shift();
4120
+ if (value !== "configure" && value !== "rotate" && value !== "repair" && value !== "remove") {
4121
+ throw new Error("`--generic-mcp-action` must be configure, rotate, repair, or remove.");
4122
+ }
4123
+ parsed.genericMcpAction = value;
4124
+ break;
4125
+ }
1264
4126
  case "--no-skills":
1265
4127
  parsed.noSkills = true;
1266
4128
  break;
4129
+ case "--skill-manifest": {
4130
+ const value = args.shift();
4131
+ if (!value) {
4132
+ throw new Error("`--skill-manifest` requires a file path.");
4133
+ }
4134
+ parsed.skillsManifest = value;
4135
+ break;
4136
+ }
1267
4137
  case "--skill-scope": {
1268
4138
  const value = args.shift();
1269
- if (value !== "project" && value !== "global") {
1270
- throw new Error("`--skill-scope` must be either `project` or `global`.");
4139
+ if (value !== "project" && value !== "global") {
4140
+ throw new Error("`--skill-scope` must be either `project` or `global`.");
4141
+ }
4142
+ parsed.skillScope = value;
4143
+ break;
4144
+ }
4145
+ case "--selected-skills": {
4146
+ const value = args.shift();
4147
+ if (!value) {
4148
+ throw new Error("`--selected-skills` requires a comma-separated value, `all`, or `none`.");
4149
+ }
4150
+ parsed.selectedSkillsValue = value;
4151
+ break;
4152
+ }
4153
+ case "--adopt-existing": {
4154
+ if (parsed.command !== "setup" || parsed.setupSubcommand !== "skills") {
4155
+ throw new Error("`--adopt-existing` is valid only with `make-docs setup skills`.");
4156
+ }
4157
+ const value = args.shift();
4158
+ const names = value?.split(",").map((name) => name.trim());
4159
+ if (!names?.length || names.some((name) => !/^[a-z0-9][a-z0-9-]*$/.test(name) || name === "all" || name === "none")) {
4160
+ throw new Error("`--adopt-existing` requires comma-separated first-party Skill names, not `all` or `none`.");
1271
4161
  }
1272
- parsed.skillScope = value;
4162
+ parsed.adoptExisting = [...new Set(names)];
1273
4163
  break;
1274
4164
  }
1275
- case "--selected-skills": {
4165
+ case "--review": {
4166
+ if (parsed.command !== "setup" || parsed.setupSubcommand !== "skills") {
4167
+ throw new Error("This `--review` flag is valid only with `make-docs setup skills --adopt-existing`.");
4168
+ }
4169
+ const value = args.shift();
4170
+ if (!value || !/^[a-f0-9]{64}$/i.test(value)) throw new Error("`--review` requires the 64-character digest from the adoption preview.");
4171
+ parsed.review = value.toLowerCase();
4172
+ break;
4173
+ }
4174
+ case "--project-resources": {
1276
4175
  const value = args.shift();
1277
4176
  if (!value) {
1278
- throw new Error("`--selected-skills` requires a comma-separated value, `all`, or `none`.");
1279
- }
1280
- parsed.selectedSkills = parseSelectedSkillsValue(value);
1281
- if (value !== "none" && value !== "all" && parsed.selectedSkills.length === 0) {
1282
- throw new Error("`--selected-skills` requires at least one skill id, `all`, or `none`.");
4177
+ throw new Error("`--project-resources` requires a comma-separated value, `all`, or `none`.");
1283
4178
  }
4179
+ parsed.projectResources = parseProjectResourcesValue(value);
1284
4180
  break;
1285
4181
  }
1286
4182
  default:
1287
4183
  throw new Error(`Unknown argument: ${arg}`);
1288
4184
  }
1289
4185
  }
1290
- validateParsedArgs(parsed);
4186
+ if (parsed.review && !parsed.adoptExisting) throw new Error("`--review` requires `--adopt-existing`.");
4187
+ if (parsed.genericMcpAction && !parsed.genericMcpClient) throw new Error("`--generic-mcp-action` requires `--generic-mcp-client`.");
4188
+ if (parsed.adoptExisting && parsed.remove) throw new Error("`--adopt-existing` cannot be combined with `--remove`.");
4189
+ if (parsed.adoptExisting && parsed.yes && !parsed.dryRun && !parsed.review) {
4190
+ throw new Error("`--yes` alone cannot authorize adoption. Preview with `--dry-run`, then supply its matching `--review <digest>`.");
4191
+ }
1291
4192
  return parsed;
1292
4193
  }
1293
- function parseSelectedSkillsValue(value) {
4194
+ function parseProjectResourcesValue(value) {
4195
+ if (value === "none") return [];
4196
+ if (value === "all") return [...PROJECT_RESOURCE_TYPES];
4197
+ const values = Array.from(new Set(value.split(",").map((entry) => entry.trim()).filter(Boolean)));
4198
+ const invalid = values.filter((entry) => !PROJECT_RESOURCE_TYPES.includes(entry));
4199
+ if (invalid.length > 0 || values.length === 0) {
4200
+ throw new Error(`\`--project-resources\` accepts ${PROJECT_RESOURCE_TYPES.join(", ")}, \`all\`, or \`none\`.`);
4201
+ }
4202
+ return values.sort();
4203
+ }
4204
+ function resolveParsedSelectedSkills(parsed, registry) {
4205
+ if (parsed.selectedSkillsValue === void 0) {
4206
+ return;
4207
+ }
4208
+ parsed.selectedSkills = parseSelectedSkillsValue(
4209
+ parsed.selectedSkillsValue,
4210
+ registry
4211
+ );
4212
+ if (parsed.selectedSkillsValue !== "none" && parsed.selectedSkillsValue !== "all" && parsed.selectedSkills.length === 0) {
4213
+ throw new Error(
4214
+ "`--selected-skills` requires at least one skill id, `all`, or `none`."
4215
+ );
4216
+ }
4217
+ }
4218
+ function parseSelectedSkillsValue(value, registry) {
1294
4219
  if (value === "none") {
1295
4220
  return [];
1296
4221
  }
1297
4222
  if (value === "all") {
1298
- return getSkillRegistryNames(loadSkillRegistry(PACKAGE_ROOT));
4223
+ return getSkillRegistryNames(registry);
1299
4224
  }
1300
4225
  return Array.from(
1301
4226
  new Set(
@@ -1308,26 +4233,30 @@ function rejectRemovedUpdateReconfigure(args) {
1308
4233
  return;
1309
4234
  }
1310
4235
  throw new Error(
1311
- "The `update --reconfigure` command was removed. Use `make-docs reconfigure` instead."
4236
+ "The `update --reconfigure` command was removed. Use `make-docs setup reconfigure` instead."
1312
4237
  );
1313
4238
  }
1314
4239
  function rejectRemovedCommand(args) {
1315
4240
  const command = args[0];
1316
- if (command !== "init" && command !== "update") {
4241
+ const replacements = {
4242
+ init: "make-docs setup",
4243
+ reconfigure: "make-docs setup reconfigure",
4244
+ skills: "make-docs setup skills",
4245
+ backup: "make-docs setup backup",
4246
+ operations: "make-docs run <domain> <verb>"
4247
+ };
4248
+ const replacement = command ? replacements[command] : void 0;
4249
+ if (!replacement) {
1317
4250
  return;
1318
4251
  }
1319
- const suggestedArgs = args.slice(1).join(" ");
1320
- const suggestedCommand = suggestedArgs ? `make-docs ${suggestedArgs}` : "make-docs";
1321
- throw new Error(
1322
- `The \`${command}\` command was removed. Use \`${suggestedCommand}\` instead.`
1323
- );
4252
+ throw new Error(`The \`${command}\` command was removed. Use \`${replacement}\` instead.`);
1324
4253
  }
1325
4254
  function rejectRemovedReconfigureFlag(args) {
1326
4255
  if (!args.includes("--reconfigure")) {
1327
4256
  return;
1328
4257
  }
1329
4258
  throw new Error(
1330
- "`--reconfigure` was removed. Use `make-docs reconfigure` instead."
4259
+ "`--reconfigure` was removed. Use `make-docs setup reconfigure` instead."
1331
4260
  );
1332
4261
  }
1333
4262
  function getInvalidSkillsCommandFlags(parsed) {
@@ -1349,50 +4278,193 @@ function getInvalidSkillsCommandFlags(parsed) {
1349
4278
  }
1350
4279
  return flags;
1351
4280
  }
4281
+ function describeParsedCommand(parsed) {
4282
+ if (!parsed.command) {
4283
+ return "bare `make-docs`";
4284
+ }
4285
+ return parsed.setupSubcommand ? `\`make-docs ${parsed.command} ${parsed.setupSubcommand}\`` : `\`make-docs ${parsed.command}\``;
4286
+ }
4287
+ function renderSystemSetupResult(result) {
4288
+ const lines = [
4289
+ `Machine setup: ${result.status}.`,
4290
+ `Codex method: ${result.selections.codex}.`,
4291
+ `Claude Code method: ${result.selections["claude-code"]}.`
4292
+ ];
4293
+ for (const blocked of result.blocked) {
4294
+ lines.push(`${blocked.harness}: ${blocked.reason}`);
4295
+ lines.push(`Next: ${blocked.nextAction}`);
4296
+ }
4297
+ if (result.recoveryAction && result.blocked.length === 0) lines.push(`Next: ${result.recoveryAction}`);
4298
+ return `${lines.join("\n")}
4299
+ `;
4300
+ }
4301
+ function storePrerequisiteFailureAction(error) {
4302
+ if (error instanceof Checkpoint9ReceiptProjectionError) {
4303
+ return "Restore write access for the Store receipt projection, then run `make-docs setup` to verify and resume the recorded bridge.";
4304
+ }
4305
+ if (error instanceof MigrationSafetyError) {
4306
+ if (error.code === "active-writer" || error.code === "lock-active") {
4307
+ return "Let the named Store writer finish or recover its recorded operation, then run `make-docs setup` again.";
4308
+ }
4309
+ if (error.code === "permission-denied" || error.code === "backup-incomplete") {
4310
+ return "Restore Store and backup-path access, then run `make-docs setup` again.";
4311
+ }
4312
+ if (error.code === "snapshot-drift" || error.code === "lock-lost") {
4313
+ return "Keep the changed Store state, then run `make-docs setup` again to review a new exact bridge plan.";
4314
+ }
4315
+ }
4316
+ return "Correct the reported Store prerequisite, then run `make-docs setup` again to review a new exact bridge plan.";
4317
+ }
4318
+ function writeCanonicalSetupResult(input2) {
4319
+ const selections = input2.system?.selections ?? input2.prepared?.selections ?? { codex: "none", "claude-code": "none" };
4320
+ const plans = input2.prepared?.plans ?? [];
4321
+ output.write(`${JSON.stringify({
4322
+ schemaVersion: 2,
4323
+ operation: "setup",
4324
+ status: input2.status,
4325
+ dryRun: input2.dryRun,
4326
+ targetRoot: input2.targetRoot,
4327
+ machine: {
4328
+ selections,
4329
+ states: plans.map((plan) => ({
4330
+ harness: plan.harness,
4331
+ method: plan.method,
4332
+ state: plan.status,
4333
+ attemptedWork: [...plan.operations],
4334
+ mutationState: input2.system ? input2.system.mutationState === "partial" ? "partial" : input2.system.mutationState === "verified" && plan.changed && input2.system.configured.includes(plan.harness) ? "applied" : "none" : plan.changed ? input2.dryRun ? "planned" : "none" : "none",
4335
+ detail: plan.detail
4336
+ })),
4337
+ configured: input2.system?.configured ?? [],
4338
+ ...input2.genericMcp ? { genericMcp: input2.genericMcp } : {}
4339
+ },
4340
+ store: input2.storeBridge ? {
4341
+ state: input2.storeBridge.storeState,
4342
+ sourceSchemaVersion: input2.storeBridge.sourceSchemaVersion,
4343
+ targetSchemaVersion: input2.storeBridge.targetSchemaVersion,
4344
+ disposition: input2.storeBridge.disposition,
4345
+ mutationState: input2.storeMutationState ?? (input2.storeBridge.changes.store.length > 0 ? input2.dryRun ? "planned" : "applied" : "none"),
4346
+ changes: input2.storeBridge.changes.store,
4347
+ blockers: input2.storeBridge.blockers,
4348
+ nextAction: input2.storeBridge.nextAction
4349
+ } : null,
4350
+ projectRecovery: input2.projectRecovery ?? null,
4351
+ project: {
4352
+ changed: input2.projectChanged,
4353
+ mutationState: input2.projectMutationState ?? (input2.projectChanged ? input2.dryRun ? "planned" : "applied" : "none"),
4354
+ actions: [...input2.projectActions].sort((left, right) => left.relativePath.localeCompare(right.relativePath)).map((action) => ({ path: action.relativePath, action: action.type }))
4355
+ },
4356
+ failedCondition: input2.failedCondition,
4357
+ nextAction: input2.nextAction
4358
+ })}
4359
+ `);
4360
+ }
1352
4361
  function validateParsedArgs(parsed) {
1353
- if (parsed.backup && parsed.command !== "uninstall") {
4362
+ if (parsed.codexMethod !== void 0 && parsed.noCodex) {
4363
+ throw new Error("`--codex-method` cannot be combined with `--no-codex`.");
4364
+ }
4365
+ if (parsed.claudeCodeMethod !== void 0 && parsed.noClaudeCode) {
4366
+ throw new Error("`--claude-code-method` cannot be combined with `--no-claude-code`.");
4367
+ }
4368
+ if ((parsed.codexMethod !== void 0 || parsed.claudeCodeMethod !== void 0 || parsed.genericMcpClient !== void 0 || parsed.genericMcpAction !== void 0) && (parsed.command !== "setup" || ["skills", "backup", "remove"].includes(parsed.setupSubcommand ?? ""))) {
4369
+ throw new Error("Harness and generic MCP flags are valid only with setup, setup reconfigure, or setup system.");
4370
+ }
4371
+ if (parsed.json && (parsed.command !== "setup" || ["skills", "backup", "remove"].includes(parsed.setupSubcommand ?? ""))) {
4372
+ throw new Error("`--json` is valid only with setup, setup reconfigure, or setup system.");
4373
+ }
4374
+ if (parsed.projectRecovery && (parsed.command !== "setup" || parsed.setupSubcommand !== void 0)) {
4375
+ throw new Error("`--recover` is valid only with plain `make-docs setup`.");
4376
+ }
4377
+ if (parsed.command === void 0) {
4378
+ const bareFlags = [
4379
+ ...parsed.dryRun ? ["--dry-run"] : [],
4380
+ ...parsed.yes ? ["--yes"] : [],
4381
+ ...parsed.backup ? ["--backup"] : [],
4382
+ ...parsed.remove ? ["--remove"] : [],
4383
+ ...getSelectionOverrideFlags(parsed)
4384
+ ];
4385
+ if (bareFlags.length > 0) {
4386
+ throw new Error(
4387
+ `Bare \`make-docs\` shows status or starts a guided setup and accepts only \`--target\` and \`--help\`. Use \`make-docs setup ${bareFlags.join(" ")}\` for install and sync options.`
4388
+ );
4389
+ }
4390
+ }
4391
+ if (parsed.backup && parsed.setupSubcommand !== "remove") {
4392
+ throw new Error(
4393
+ `\`--backup\` is only valid with \`make-docs setup remove\`, not ${describeParsedCommand(parsed)}.`
4394
+ );
4395
+ }
4396
+ if (parsed.remove && parsed.setupSubcommand !== "skills") {
1354
4397
  throw new Error(
1355
- `\`--backup\` is only valid with \`uninstall\`, not \`${parsed.command ?? "no command"}\`.`
4398
+ `\`--remove\` is only valid with \`make-docs setup skills\`, not ${describeParsedCommand(parsed)}.`
1356
4399
  );
1357
4400
  }
1358
- if (parsed.remove && parsed.command !== "skills") {
4401
+ if (parsed.dryRun && isLifecycleCommand(parsed)) {
1359
4402
  throw new Error(
1360
- `\`--remove\` is only valid with \`make-docs skills\`, not \`${parsed.command ?? "no command"}\`.`
4403
+ `\`--dry-run\` is only valid with \`make-docs setup\`, \`make-docs setup reconfigure\`, or \`make-docs setup skills\`, not ${describeParsedCommand(parsed)}.`
1361
4404
  );
1362
4405
  }
1363
- if (parsed.command === "skills") {
4406
+ if (parsed.setupSubcommand === "skills") {
1364
4407
  const invalidSkillsFlags = getInvalidSkillsCommandFlags(parsed);
1365
4408
  if (invalidSkillsFlags.length > 0) {
1366
4409
  const label = invalidSkillsFlags.length === 1 ? "flag" : "flags";
1367
4410
  const verb = invalidSkillsFlags.length === 1 ? "is" : "are";
1368
4411
  throw new Error(
1369
- `Selection ${label} ${invalidSkillsFlags.join(", ")} ${verb} not valid with \`make-docs skills\`. Use skills command options such as \`--remove\`, \`--skill-scope\`, or \`--selected-skills\`.`
4412
+ `Selection ${label} ${invalidSkillsFlags.join(", ")} ${verb} not valid with \`make-docs setup skills\`. Use skills command options such as \`--remove\`, \`--skill-scope\`, or \`--selected-skills\`.`
4413
+ );
4414
+ }
4415
+ if (parsed.remove && parsed.selectedSkillsValue !== void 0) {
4416
+ throw new Error(
4417
+ "`--selected-skills` cannot be combined with `make-docs setup skills --remove`."
1370
4418
  );
1371
4419
  }
1372
- if (parsed.remove && parsed.selectedSkills !== void 0) {
4420
+ }
4421
+ if (parsed.setupSubcommand === "system") {
4422
+ const invalidSystemFlags = [
4423
+ ...parsed.noDesigns ? ["--no-designs"] : [],
4424
+ ...parsed.noPlans ? ["--no-plans"] : [],
4425
+ ...parsed.noPrd ? ["--no-prd"] : [],
4426
+ ...parsed.noWork ? ["--no-work"] : [],
4427
+ ...parsed.noSkills ? ["--no-skills"] : [],
4428
+ ...parsed.skillScope ? ["--skill-scope"] : [],
4429
+ ...parsed.selectedSkillsValue !== void 0 ? ["--selected-skills"] : [],
4430
+ ...parsed.projectResources !== void 0 ? ["--project-resources"] : []
4431
+ ];
4432
+ if (invalidSystemFlags.length > 0) {
1373
4433
  throw new Error(
1374
- "`--selected-skills` cannot be combined with `make-docs skills --remove`."
4434
+ `Project selection flags ${invalidSystemFlags.join(", ")} are not valid with \`make-docs setup system\`.`
1375
4435
  );
1376
4436
  }
1377
4437
  }
1378
4438
  const selectionOverrideFlags = getSelectionOverrideFlags(parsed);
1379
- if (isLifecycleCommand(parsed.command) && selectionOverrideFlags.length > 0) {
4439
+ if (isLifecycleCommand(parsed) && selectionOverrideFlags.length > 0) {
1380
4440
  const label = selectionOverrideFlags.length === 1 ? "flag" : "flags";
1381
4441
  const verb = selectionOverrideFlags.length === 1 ? "is" : "are";
1382
4442
  throw new Error(
1383
- `Selection ${label} ${selectionOverrideFlags.join(", ")} ${verb} only valid with \`make-docs\` or \`make-docs reconfigure\`, not \`${parsed.command}\`.`
4443
+ `Selection ${label} ${selectionOverrideFlags.join(", ")} ${verb} only valid with \`make-docs setup\` or \`make-docs setup reconfigure\`, not ${describeParsedCommand(parsed)}.`
4444
+ );
4445
+ }
4446
+ if (parsed.noSkills && parsed.skillsManifest) {
4447
+ throw new Error(
4448
+ "`--no-skills` cannot be combined with `--skill-manifest`."
1384
4449
  );
1385
4450
  }
1386
- if (parsed.noSkills && (parsed.skillScope || parsed.selectedSkills !== void 0)) {
4451
+ if (parsed.noSkills && (parsed.skillScope || parsed.selectedSkillsValue !== void 0)) {
1387
4452
  throw new Error(
1388
4453
  "`--no-skills` cannot be combined with `--skill-scope` or `--selected-skills`."
1389
4454
  );
1390
4455
  }
4456
+ }
4457
+ function validateParsedSelectedSkills(parsed, registry) {
4458
+ const registrySkills = new Set(getSkillRegistryNames(registry));
4459
+ for (const name of parsed.adoptExisting ?? []) {
4460
+ if (!registrySkills.has(name)) throw new Error(`Unknown adoption Skill \`${name}\`.`);
4461
+ if (parsed.selectedSkills && !parsed.selectedSkills.includes(name)) {
4462
+ throw new Error(`Adoption Skill \`${name}\` must be included in \`--selected-skills\`.`);
4463
+ }
4464
+ }
1391
4465
  if (parsed.selectedSkills === void 0) {
1392
4466
  return;
1393
4467
  }
1394
- const registry = loadSkillRegistry(PACKAGE_ROOT);
1395
- const registrySkills = new Set(getSkillRegistryNames(registry));
1396
4468
  for (const skillName of parsed.selectedSkills) {
1397
4469
  if (!registrySkills.has(skillName)) {
1398
4470
  const validList = Array.from(registrySkills).sort().join(", ");
@@ -1411,31 +4483,49 @@ function printPlan(options) {
1411
4483
  packageName,
1412
4484
  packageVersion,
1413
4485
  selectionSource,
1414
- targetDir
4486
+ targetDir,
4487
+ compatibilityClassification,
4488
+ config,
4489
+ selectedResourceTypes,
4490
+ selectedCapabilities,
4491
+ stops
1415
4492
  } = options;
1416
4493
  const nonNoop = actions.filter((action) => action.type !== "noop");
1417
4494
  const renderedActions = getRenderedActions(actions);
1418
4495
  const noopCount = actions.length - nonNoop.length;
1419
4496
  const counts = countActions(actions);
1420
- const manifestPath = path.join(targetDir, MANIFEST_RELATIVE_PATH);
1421
4497
  const mode = describeApplyMode({ existingManifest, installIntent });
4498
+ const labels = getConfigRenderingLabels(config);
1422
4499
  Vt(
1423
4500
  [
1424
4501
  `Target: ${targetDir}`,
1425
4502
  `Mode: ${mode}`,
1426
- existingManifest ? `Manifest: ${manifestPath} (found)` : `Manifest: ${manifestPath} (will be created)`,
4503
+ existingManifest ? "Installation record: global Make Docs Store (found or verified for transfer)" : "Installation record: global Make Docs Store (will be created)",
1427
4504
  existingManifest ? `Installed version: ${existingManifest.packageVersion}` : "Installed version: none detected",
1428
4505
  `Package version: ${packageName} ${packageVersion}`,
4506
+ ...compatibilityClassification ? [
4507
+ `Compatibility state: ${compatibilityClassification.state}`,
4508
+ `Disposition: ${compatibilityClassification.disposition}`
4509
+ ] : [],
1429
4510
  `Selection source: ${selectionSource}`,
4511
+ `Project surface: ${selectedCapabilities.join(", ") || "none"}`,
4512
+ `Local resource projection: ${selectedResourceTypes === void 0 ? "legacy install (not yet selected)" : selectedResourceTypes.join(", ") || "none"}`,
4513
+ "Resource provider reads need no Store access.",
4514
+ "Local copies reduce CLI dependence. They do not grant harness or Store access.",
4515
+ `Safety stops: ${stops.join(", ") || "none"}`,
4516
+ `Document kind labels: ${labels.documentKinds}`,
4517
+ `Lifecycle labels: ${labels.lifecycle}`,
4518
+ `Coordinate labels: ${labels.coordinates}`,
4519
+ `Persona labels: ${labels.personas}`,
1430
4520
  `Managed files evaluated: ${actions.length}`,
1431
4521
  `Already current: ${noopCount}`,
1432
4522
  `Changes planned: ${nonNoop.length}`,
1433
4523
  `Generate: ${counts.create + counts.generate}`,
1434
- `Update: ${counts.update + counts["update-conflict"]}`,
4524
+ `Update: ${counts.update + counts["update-conflict"] + counts["strip-managed-block"]}`,
1435
4525
  `Skip: ${counts.skip + counts["skip-conflict"]}`,
1436
4526
  `Remove: ${counts["remove-managed"]}`
1437
4527
  ].join("\n"),
1438
- "Information"
4528
+ "This project"
1439
4529
  );
1440
4530
  if (nonNoop.length === 0) {
1441
4531
  renderNoopExplanation({ dryRun, existingManifest });
@@ -1451,6 +4541,7 @@ function countActions(actions) {
1451
4541
  "remove-managed": actions.filter((action) => action.type === "remove-managed").length,
1452
4542
  skip: actions.filter((action) => action.type === "skip").length,
1453
4543
  "skip-conflict": actions.filter((action) => action.type === "skip-conflict").length,
4544
+ "strip-managed-block": actions.filter((action) => action.type === "strip-managed-block").length,
1454
4545
  update: actions.filter((action) => action.type === "update").length,
1455
4546
  "update-conflict": actions.filter((action) => action.type === "update-conflict").length
1456
4547
  };
@@ -1461,6 +4552,124 @@ function describeApplyMode(options) {
1461
4552
  }
1462
4553
  return options.existingManifest ? "existing install sync" : "first install";
1463
4554
  }
4555
+ function isFreshInstallTarget(options) {
4556
+ if (options.installIntent !== "apply" || options.existingManifest) {
4557
+ return false;
4558
+ }
4559
+ if (!existsSync2(options.targetDir)) {
4560
+ return true;
4561
+ }
4562
+ if (readdirSync(options.targetDir).length === 0) {
4563
+ return true;
4564
+ }
4565
+ const filesystemTrust = options.classification.evidence.filesystemTrust;
4566
+ return options.classification.state === "unknown-shape" && filesystemTrust.recognizableManagedPaths.length === 0 && filesystemTrust.ambiguousFallbackPaths.length === 0 && filesystemTrust.nonMakeDocsPathCollisions.length === 0;
4567
+ }
4568
+ function assertCompletedRemovalHandoffUsable(review) {
4569
+ if (review.status !== "blocked") {
4570
+ return;
4571
+ }
4572
+ throw new Error(
4573
+ [
4574
+ "The completed make-docs removal cannot be used for this reinstall.",
4575
+ `Operation: ${review.operationId}`,
4576
+ ...review.blockers.map((blocker) => `- ${blocker}`),
4577
+ `Next: ${review.nextAction}`
4578
+ ].join("\n")
4579
+ );
4580
+ }
4581
+ function guardCompatibilityDisposition(options) {
4582
+ const { classification, interactive, freshInstallTarget } = options;
4583
+ if (freshInstallTarget) {
4584
+ return;
4585
+ }
4586
+ if (hasUnreviewedOwnershipAmbiguity(classification)) {
4587
+ throw new Error(
4588
+ buildCompatibilityError(
4589
+ "make-docs cannot sync this target until ownership ambiguity is reviewed.",
4590
+ classification,
4591
+ [
4592
+ "Run `make-docs setup` interactively if the files are reviewable, or back up the target and reinstall into a clean tree."
4593
+ ]
4594
+ )
4595
+ );
4596
+ }
4597
+ switch (classification.disposition) {
4598
+ case "sync":
4599
+ return;
4600
+ case "migrate":
4601
+ if (classification.state === "clean-v1") {
4602
+ return;
4603
+ }
4604
+ break;
4605
+ case "migrate-with-review":
4606
+ if (interactive) {
4607
+ Vt(
4608
+ buildCompatibilitySummaryLines(classification).join("\n"),
4609
+ "Compatibility review required"
4610
+ );
4611
+ }
4612
+ return;
4613
+ case "backup-and-reinstall":
4614
+ throw new Error(
4615
+ buildCompatibilityError(
4616
+ "This target requires an explicit backup-and-reinstall migration flow before make-docs can write changes.",
4617
+ classification,
4618
+ [
4619
+ "`make-docs setup` and `make-docs setup reconfigure` will not perform destructive backup-and-reinstall implicitly."
4620
+ ]
4621
+ )
4622
+ );
4623
+ case "manual-review-required":
4624
+ throw new Error(
4625
+ buildCompatibilityError(
4626
+ "make-docs cannot classify this target safely enough to write changes.",
4627
+ classification,
4628
+ [
4629
+ "Review the failed evidence below, create a manual backup if needed, or install into a clean tree."
4630
+ ]
4631
+ )
4632
+ );
4633
+ default: {
4634
+ const exhaustiveCheck = classification.disposition;
4635
+ throw new Error(`Unhandled compatibility disposition: ${exhaustiveCheck}`);
4636
+ }
4637
+ }
4638
+ throw new Error(
4639
+ buildCompatibilityError(
4640
+ "make-docs cannot migrate this target because the classified state is not a clean trusted v1 install.",
4641
+ classification,
4642
+ ["Review the classification evidence before changing the target."]
4643
+ )
4644
+ );
4645
+ }
4646
+ function hasUnreviewedOwnershipAmbiguity(classification) {
4647
+ return classification.disposition === "sync" && (classification.evidence.filesystemTrust.ambiguousFallbackPaths.length > 0 || classification.evidence.filesystemTrust.nonMakeDocsPathCollisions.length > 0);
4648
+ }
4649
+ function buildCompatibilityError(headline, classification, nextSteps) {
4650
+ return [
4651
+ headline,
4652
+ "",
4653
+ ...buildCompatibilitySummaryLines(classification),
4654
+ "",
4655
+ "Next steps:",
4656
+ ...nextSteps.map((step) => `- ${step}`)
4657
+ ].join("\n");
4658
+ }
4659
+ function buildCompatibilitySummaryLines(classification) {
4660
+ const auditReport = classification.auditReport;
4661
+ return [
4662
+ `Compatibility state: ${classification.state}`,
4663
+ `Disposition: ${classification.disposition}`,
4664
+ ...auditReport ? [
4665
+ `Audit removable files: ${auditReport.removableFiles.length}`,
4666
+ `Audit preserved paths: ${auditReport.preservedPaths.length}`,
4667
+ `Audit skipped paths: ${auditReport.skippedPaths.length}`
4668
+ ] : ["Audit summary: unavailable"],
4669
+ "Evidence:",
4670
+ ...formatCompatibilityClassification(classification).map((line) => `- ${line}`)
4671
+ ];
4672
+ }
1464
4673
  function renderNoopExplanation(options) {
1465
4674
  const noChangeText = options.dryRun ? "No managed file changes would be made." : "No managed file changes are needed.";
1466
4675
  const lines = [noChangeText];
@@ -1479,7 +4688,8 @@ function renderNoopExplanation(options) {
1479
4688
  }
1480
4689
  lines.push(
1481
4690
  "Useful next steps:",
1482
- "- Run `make-docs reconfigure` to change which docs, harnesses, or skills are managed.",
4691
+ "- Run `make-docs setup reconfigure` to change which docs, harnesses, or project resources are managed.",
4692
+ "- Run `make-docs setup skills` to change managed skills.",
1483
4693
  "- Run `make-docs --dry-run` after upgrading make-docs to preview future changes."
1484
4694
  );
1485
4695
  Vt(lines.join("\n"), "Results");
@@ -1492,7 +4702,8 @@ function formatActionLine(action) {
1492
4702
  if (!kind) {
1493
4703
  throw new Error(`Cannot render no-op action for ${action.relativePath}.`);
1494
4704
  }
1495
- return `- ${kind}: ${action.relativePath}`;
4705
+ const agenticRole = formatAgenticSkillFileRole(action.agenticRole);
4706
+ return `- ${kind}: ${agenticRole ? `${agenticRole}: ` : ""}${action.relativePath}`;
1496
4707
  }
1497
4708
  function compareRenderedActions(left, right) {
1498
4709
  const leftKind = getRenderedActionKind(left);
@@ -1509,6 +4720,7 @@ function getRenderedActionKind(action) {
1509
4720
  return "generate";
1510
4721
  case "update":
1511
4722
  case "update-conflict":
4723
+ case "strip-managed-block":
1512
4724
  return "update";
1513
4725
  case "skip":
1514
4726
  case "skip-conflict":
@@ -1554,26 +4766,42 @@ Installed make-docs ${options.manifest.packageVersion} into ${options.targetDir}
1554
4766
  `
1555
4767
  );
1556
4768
  }
1557
- function printHelp(command) {
1558
- switch (command) {
1559
- case "reconfigure":
1560
- output.write(`make-docs reconfigure
1561
-
1562
- Change the configured make-docs footprint for an existing install.
1563
- Requires an existing ${MANIFEST_RELATIVE_PATH} in the target directory.
4769
+ var SETUP_SHARED_OPTIONS = `General options:
4770
+ --target <dir> Operate on a different make-docs install directory.
4771
+ --dry-run Show planned changes without writing files.
4772
+ --yes Approve a fully specified non-interactive plan.
4773
+ --recover <resume|restore> Choose recovery for unfinished project work.
4774
+ --json Emit only the canonical setup result JSON.
4775
+ --help, -h Show help for this command.
1564
4776
 
1565
- Interactive runs open the selection wizard using the saved manifest selections.
1566
- Non-interactive runs with --yes must include at least one selection flag.
4777
+ Harness options:
4778
+ --codex-method <none|mcp|command-rules>
4779
+ --claude-code-method <none|mcp|permission-rules>
4780
+ --generic-mcp-client <label> Add one bounded generic MCP client profile.
4781
+ --generic-mcp-action <configure|rotate|repair|remove>
4782
+ Choose its repeat-safe lifecycle action.
4783
+ --no-codex Skip the Codex harness.
4784
+ --no-claude-code Skip the Claude Code harness.
4785
+ Deprecated aliases: --no-agents, --no-claude
1567
4786
 
1568
- Usage:
1569
- make-docs reconfigure [options]
4787
+ Skill options:
4788
+ --no-skills Skip skill installation entirely.
4789
+ --skill-manifest <file> Use an explicit local skills manifest for this run.
4790
+ --skill-scope project|global Choose project or global agent locations.
4791
+ --selected-skills <csv|all|none>
4792
+ Replace the selected skill set.
1570
4793
 
1571
- Options:
4794
+ Resource options:
4795
+ --project-resources <csv|all|none>
4796
+ Copy only the selected system resource types into this project.
1572
4797
 
1573
- General options:
1574
- --target <dir> Reconfigure a different make-docs install directory.
4798
+ Fresh projects always include Designs, Plans, PRD, and Work. Use setup
4799
+ reconfigure to review a later project-surface change.`;
4800
+ var RECONFIGURE_SHARED_OPTIONS = `General options:
4801
+ --target <dir> Operate on a different make-docs install directory.
1575
4802
  --dry-run Show planned changes without writing files.
1576
- --yes Skip interactive prompts; requires a selection flag.
4803
+ --yes Approve a fully specified non-interactive plan.
4804
+ --json Emit only the canonical setup result JSON.
1577
4805
  --help, -h Show help for this command.
1578
4806
 
1579
4807
  Content options:
@@ -1583,30 +4811,82 @@ Content options:
1583
4811
  --no-work Skip docs/work scaffolding.
1584
4812
 
1585
4813
  Harness options:
4814
+ --codex-method <none|mcp|command-rules>
4815
+ --claude-code-method <none|mcp|permission-rules>
4816
+ --generic-mcp-client <label> Add one bounded generic MCP client profile.
4817
+ --generic-mcp-action <configure|rotate|repair|remove>
4818
+ Choose its repeat-safe lifecycle action.
1586
4819
  --no-codex Skip the Codex harness.
1587
4820
  --no-claude-code Skip the Claude Code harness.
1588
4821
  Deprecated aliases: --no-agents, --no-claude
1589
4822
 
1590
- Skill options:
1591
- --no-skills Skip skill installation entirely.
1592
- --skill-scope project|global Choose whether skills install in the repo or the global Codex home.
1593
- --selected-skills <csv|all|none>
1594
- Replace the selected skill set.
4823
+ Skill selections:
4824
+ Existing installs keep their saved skill enabled state, scope, and names.
4825
+ Use \`make-docs setup skills\` to change skill selections.
4826
+
4827
+ Resource options:
4828
+ --project-resources <csv|all|none>
4829
+ Copy only the selected system resource types into this project.`;
4830
+ function printHelp(command, setupSubcommand) {
4831
+ if (command === "setup") {
4832
+ switch (setupSubcommand) {
4833
+ case "system":
4834
+ output.write(`make-docs setup system
4835
+
4836
+ Review and configure machine-level support for Codex and Claude Code.
4837
+ Harness detection is a hint. It does not prove support and does not limit choice.
4838
+ Each planned method names the operations it enables and the machine files it changes.
4839
+
4840
+ Usage:
4841
+ make-docs setup system [options]
4842
+
4843
+ Options:
4844
+ --target <path> Bind Store recovery state to this project path.
4845
+ --dry-run Show This computer changes without writing files.
4846
+ --yes Approve the reviewed machine changes.
4847
+ --json Emit only the canonical setup result JSON.
4848
+ --codex-method <none|mcp|command-rules>
4849
+ --claude-code-method <none|mcp|permission-rules>
4850
+ --generic-mcp-client <label> Print a bounded client-owned MCP configuration.
4851
+ --generic-mcp-action <configure|rotate|repair|remove>
4852
+ --no-codex Skip Codex support.
4853
+ --no-claude-code Skip Claude Code support.
4854
+ --help, -h Show help for this command.
1595
4855
 
1596
4856
  Examples:
1597
- make-docs reconfigure
1598
- make-docs reconfigure --target ~/Projects/example --dry-run
1599
- make-docs reconfigure --yes --no-work
1600
- make-docs reconfigure --yes --no-codex --skill-scope global --selected-skills decompose-codebase
4857
+ make-docs setup system --codex-method mcp --claude-code-method none --dry-run
4858
+ make-docs setup system --codex-method command-rules --no-claude-code --yes
1601
4859
  `);
1602
- return;
1603
- case "skills":
1604
- output.write(`make-docs skills
4860
+ return;
4861
+ case "reconfigure":
4862
+ output.write(`make-docs setup reconfigure
4863
+
4864
+ Change the configured make-docs footprint for an existing install.
4865
+ Requires a verified installation record in the global Make Docs Store.
4866
+
4867
+ Interactive runs open the selection wizard using the saved manifest selections.
4868
+ Non-interactive runs with --yes must include at least one selection flag.
4869
+
4870
+ Usage:
4871
+ make-docs setup reconfigure [options]
4872
+
4873
+ ${RECONFIGURE_SHARED_OPTIONS}
4874
+
4875
+ Examples:
4876
+ make-docs setup reconfigure
4877
+ make-docs setup reconfigure --target ~/Projects/example --dry-run
4878
+ make-docs setup reconfigure --yes --no-work
4879
+ make-docs setup reconfigure --yes --no-codex --project-resources none
4880
+ `);
4881
+ return;
4882
+ case "skills":
4883
+ output.write(`make-docs setup skills
1605
4884
 
1606
4885
  Sync or remove managed make-docs skills without changing the docs scaffold.
4886
+ Adopt existing first-party copies only after reviewing their files and ownership.
1607
4887
 
1608
4888
  Usage:
1609
- make-docs skills [options]
4889
+ make-docs setup skills [options]
1610
4890
 
1611
4891
  General options:
1612
4892
  --target <dir> Sync skills for a different make-docs install directory.
@@ -1621,26 +4901,59 @@ Platform options:
1621
4901
 
1622
4902
  Skill options:
1623
4903
  --remove Remove managed skills owned by make-docs.
1624
- --skill-scope project|global Choose whether skills install in the repo or the global Codex home.
4904
+ --skill-manifest <file> Use an explicit local skills manifest for this run.
4905
+ --skill-scope project|global Use project paths or shared ~/.agents/skills with selected native tools.
1625
4906
  --selected-skills <csv|all|none>
1626
4907
  Replace the selected skill set.
4908
+ --adopt-existing <csv> Review named, selected first-party copies for adoption.
4909
+ --review <digest> Apply the exact reviewed adoption plan.
4910
+
4911
+ Adoption dry runs write no files or Store records. Review shows backups,
4912
+ file changes, ownership changes, and blockers. Non-interactive adoption requires
4913
+ the matching --review digest; --yes alone is insufficient. Interactive adoption
4914
+ shows the same plan before confirmation. Adoption cannot be combined with --remove.
4915
+
4916
+ Project Codex-only uses .agents/skills; Claude-only uses .claude/skills.
4917
+ Both use .agents/skills with Claude links or copies. Global payloads use
4918
+ ~/.agents/skills with the selected tools' native links or copies.
4919
+ Global Codex uses CODEX_HOME/skills (default ~/.codex/skills).
4920
+ Global Claude Code uses CLAUDE_CONFIG_DIR/skills (default ~/.claude/skills).
4921
+ Old .make-docs/agentics payloads require this same reviewed adoption flow.
4922
+ That layout cutover supports forward resume only. Recovery will not recreate
4923
+ the retired directory. The review shows this limit before any change.
4924
+
4925
+ If adoption stops:
4926
+ Unknown extra files, unsafe links, conflicting copies, or another owner block adoption.
4927
+ Preserve existing content. Review and relocate unknown extras, correct unsafe links,
4928
+ or resolve the listed copy or owner conflict before running a new dry run.
4929
+ Known unowned file differences and missing declared files can be reviewed for replacement.
4930
+ Edited managed files stay protected and block adoption.
4931
+ The plan backs up changed existing bytes before replacement.
4932
+ A stale review cannot be applied. Repeat the same target, scope, tools, and Skills
4933
+ with --dry-run; inspect the new plan and use its new --review digest.
4934
+ A required Store failure stops managed writes. Resolve the reported Store error,
4935
+ then use make-docs project state status to check for pending recovery.
4936
+ Installation state has no project-local fallback.
1627
4937
 
1628
4938
  Examples:
1629
- make-docs skills
1630
- make-docs skills --dry-run
1631
- make-docs skills --remove
1632
- make-docs skills --skill-scope global
1633
- make-docs skills --selected-skills all
4939
+ make-docs setup skills
4940
+ make-docs setup skills --dry-run
4941
+ make-docs setup skills --remove
4942
+ make-docs setup skills --skill-scope global
4943
+ make-docs setup skills --selected-skills all
4944
+ make-docs setup skills --selected-skills preflight --adopt-existing preflight --dry-run
4945
+ make-docs setup skills --selected-skills preflight --adopt-existing preflight --review <digest> --yes
1634
4946
  `);
1635
- return;
1636
- case "backup":
1637
- output.write(`make-docs backup
4947
+ return;
4948
+ case "backup":
4949
+ output.write(`make-docs setup backup
1638
4950
 
1639
4951
  Create a backup of the managed make-docs files in the target directory.
4952
+ New backups are written under .make-docs/backup/<date>.
1640
4953
  This command is non-destructive: source files remain in place.
1641
4954
 
1642
4955
  Usage:
1643
- make-docs backup [--target <dir>] [--yes] [--help]
4956
+ make-docs setup backup [--target <dir>] [--yes] [--help]
1644
4957
 
1645
4958
  Options:
1646
4959
  --target <dir> Back up a different make-docs install directory.
@@ -1648,73 +4961,308 @@ Options:
1648
4961
  --help, -h Show help for this command.
1649
4962
 
1650
4963
  Examples:
1651
- make-docs backup
1652
- make-docs backup --target ~/Projects/example
1653
- make-docs backup --yes
4964
+ make-docs setup backup
4965
+ make-docs setup backup --target ~/Projects/example
4966
+ make-docs setup backup --yes
1654
4967
  `);
1655
- return;
1656
- case "uninstall":
1657
- output.write(`make-docs uninstall
4968
+ return;
4969
+ case "remove":
4970
+ output.write(`make-docs setup remove
1658
4971
 
1659
4972
  Remove the managed make-docs files from the target directory.
1660
4973
  This command is destructive: audited managed files are removed after review.
4974
+ It removes this project's install only; \`make-docs uninstall\` is the
4975
+ machine-level tool removal.
1661
4976
 
1662
4977
  Usage:
1663
- make-docs uninstall [--target <dir>] [--backup] [--yes] [--help]
4978
+ make-docs setup remove [--target <dir>] [--backup] [--yes] [--help]
1664
4979
 
1665
4980
  Options:
1666
- --target <dir> Uninstall from a different make-docs install directory.
1667
- --backup Create a backup before removing files.
4981
+ --target <dir> Remove from a different make-docs install directory.
4982
+ --backup Create a .make-docs/backup/<date> backup before removing files.
1668
4983
  --yes Skip confirmation prompts after showing warnings and the audit summary.
1669
4984
  --help, -h Show help for this command.
1670
4985
 
1671
4986
  Examples:
1672
- make-docs uninstall
1673
- make-docs uninstall --backup
1674
- make-docs uninstall --target ~/Projects/example --yes
4987
+ make-docs setup remove
4988
+ make-docs setup remove --backup
4989
+ make-docs setup remove --target ~/Projects/example --yes
4990
+ `);
4991
+ return;
4992
+ default:
4993
+ output.write(`make-docs setup
4994
+
4995
+ Install make-docs into a new target or sync an existing install using saved selections.
4996
+ Interactive fresh installs open the selection wizard; syncs review planned changes first.
4997
+
4998
+ Usage:
4999
+ make-docs setup [options]
5000
+ make-docs setup system [options]
5001
+ make-docs setup reconfigure [options]
5002
+ make-docs setup skills [options]
5003
+ make-docs setup backup [options]
5004
+ make-docs setup remove [options]
5005
+
5006
+ Subcommands:
5007
+ system Configure reviewed machine-level harness support.
5008
+ reconfigure Change saved project selections for an existing install.
5009
+ skills Change, sync, or remove managed skills.
5010
+ backup Create a backup of managed files.
5011
+ remove Remove this project's managed files, with an optional backup first.
5012
+
5013
+ ${SETUP_SHARED_OPTIONS}
5014
+
5015
+ Examples:
5016
+ make-docs setup
5017
+ make-docs setup --yes
5018
+ make-docs setup --target ~/Projects/example --dry-run
5019
+ make-docs setup reconfigure --yes --no-work
5020
+ make-docs setup remove --backup
5021
+ `);
5022
+ return;
5023
+ }
5024
+ }
5025
+ switch (command) {
5026
+ case "project":
5027
+ output.write(`make-docs project
5028
+
5029
+ Manage project support surfaces and installation state in the global Make Docs Store.
5030
+
5031
+ Usage:
5032
+ make-docs project surface ensure <archive|artifacts|assets>
5033
+ make-docs project state status [--target-root <path>] [--json]
5034
+ make-docs project state recover <operation-id> --resume|--rollback [--dry-run] [--target-root <path>] [--json]
5035
+ make-docs project path-hygiene <validate|repair> [--target <dir>] [--scope content|managed] [--path <path> ...] [--manifest <path>] [--include-skills] [--allow-comment-token <text>] [--format text|json]
5036
+ Repair previews by default. Add --apply to write, or --dry-run to preview.
5037
+
5038
+ The ensure command checks Store installation evidence and configured routers
5039
+ before it creates the selected on-demand directory. It reports the applied or
5040
+ unchanged state, plan dispositions, receipt, and next check.
5041
+
5042
+ State status reads the Store and reports pending work without changing files.
5043
+ State recover requires an operation ID and exactly one recovery mode.
5044
+ Use --resume to apply the remaining verified steps of a complete saved plan.
5045
+ Use --rollback to restore verified prior file state. Changed files block recovery.
5046
+ Add --dry-run to inspect recovery without applying changes.
5047
+
5048
+ The path-hygiene command checks local docs by default through the same typed
5049
+ operation that the MCP tool and migration checkpoint use.
5050
+ `);
5051
+ return;
5052
+ case "resource":
5053
+ output.write(`make-docs resource
5054
+
5055
+ List, read, or explicitly ensure stable system resources.
5056
+
5057
+ Usage:
5058
+ make-docs resource list [--type <contract|prompt|reference|template>] [--prefix <path>] [--origin <effective|local|installed>] [--format table|json] [--target <dir>]
5059
+ make-docs resource read <uri> [--origin <effective|local|installed>] [--format raw|json] [--target <dir>]
5060
+ make-docs resource ensure <uri> --allow-write --approve resource-projection-write [--dry-run] [--target <dir>]
5061
+ `);
5062
+ return;
5063
+ case "run":
5064
+ output.write(`make-docs run
5065
+
5066
+ Run deterministic registry operations. The operation tree is derived from the
5067
+ operation registry; use \`make-docs run\` with no arguments to list operations.
5068
+
5069
+ Usage:
5070
+ make-docs run <domain> <verb> [options]
5071
+
5072
+ Examples:
5073
+ make-docs run lifecycle list --repo-root .
5074
+ make-docs run lifecycle show --run-id <run-id>
5075
+ make-docs run package plan --harness codex --output-kind plugin --surface native --scope project user/run-stack
5076
+ make-docs run work item resolve 'W18 R11 P2'
5077
+ `);
5078
+ return;
5079
+ case "mcp":
5080
+ output.write(`make-docs mcp
5081
+
5082
+ Run the TypeScript-owned make-docs MCP server over stdio.
5083
+
5084
+ Usage:
5085
+ make-docs mcp [--help]
5086
+
5087
+ Behavior:
5088
+ The MCP server exposes read-first and plan-first tools for installed-state inspection, manifest/config reads, compatibility classification, dry-run install planning, and deterministic registry operations.
5089
+ MCP tools delegate to the same operation registry and core used by \`make-docs run\`; write operations require allowWrite=true, enforced uniformly by the operation core.
5090
+
5091
+ Examples:
5092
+ make-docs mcp
5093
+ `);
5094
+ return;
5095
+ case "update":
5096
+ output.write(`make-docs update
5097
+
5098
+ Update the installed make-docs tool itself (machine-level self-management).
5099
+ Detects the install manager that owns a persistent global install and
5100
+ delegates to it; when detection is ambiguous it prints the exact command
5101
+ instead of acting. For remote execution (npx, pnpm dlx, bunx) there is
5102
+ nothing persistent to update, since the runner fetches the requested
5103
+ version. Every run applies any pending global-store schema migration, and a
5104
+ pre-v2 project install in the working directory triggers the
5105
+ warning-and-choice migration flow before delegation.
5106
+
5107
+ Usage:
5108
+ make-docs update [--target <dir>] [--yes] [--help]
5109
+
5110
+ Options:
5111
+ --target <dir> Check a different project directory for pre-v2 state.
5112
+ --yes Skip interactive prompts where confirmation is not safety-critical.
5113
+ --help, -h Show help for this command.
5114
+
5115
+ To change a project's install, use \`make-docs setup\` or \`make-docs setup reconfigure\`.
5116
+ `);
5117
+ return;
5118
+ case "uninstall":
5119
+ output.write(`make-docs uninstall
5120
+
5121
+ Remove make-docs' machine-level footprint: the global store at ~/.make-docs/
5122
+ and the installed binary when one is present. It confirms before removing,
5123
+ reports that no binary is installed for remote-execution users, and never
5124
+ touches repository content. When the install method is ambiguous it prints
5125
+ the exact removal command instead of acting.
5126
+
5127
+ Usage:
5128
+ make-docs uninstall [--yes] [--remove-store] [--help]
5129
+
5130
+ Options:
5131
+ --yes Confirm removal without an interactive prompt.
5132
+ --help, -h Show help for this command.
5133
+
5134
+ To remove make-docs from a project, use \`make-docs setup remove\`.
1675
5135
  `);
1676
5136
  return;
1677
5137
  default:
1678
5138
  output.write(`make-docs
1679
5139
 
1680
- Apply, sync, reconfigure, back up, and remove make-docs installs.
5140
+ Manage make-docs installs, run registry operations, and serve MCP.
1681
5141
 
1682
5142
  Usage:
1683
- make-docs [options]
1684
- make-docs reconfigure [options]
1685
- make-docs skills [options]
1686
- make-docs backup [options]
1687
- make-docs uninstall [options]
5143
+ make-docs
5144
+ make-docs setup [system|reconfigure|skills|backup|remove] [options]
5145
+ make-docs project surface ensure <archive|artifacts|assets>
5146
+ make-docs project state status [--target-root <path>] [--json]
5147
+ make-docs project state recover <operation-id> --resume|--rollback [--dry-run] [--target-root <path>] [--json]
5148
+ make-docs project path-hygiene validate [options]
5149
+ make-docs resource <list|read|ensure> [options]
5150
+ make-docs run <domain> <verb> [options]
5151
+ make-docs mcp
5152
+ make-docs update
5153
+ make-docs uninstall
1688
5154
 
1689
- Primary workflow:
1690
- Run make-docs with no command to install into a new target or sync an existing manifest using saved selections.
5155
+ Bare command:
5156
+ Run make-docs with no command to see install status (when installed) or start
5157
+ a guided setup (when not installed). Bare invocation never syncs.
5158
+
5159
+ Global flags:
5160
+ --version, -v Print the installed make-docs version and exit.
5161
+ --help, -h Show help for a command.
1691
5162
 
1692
5163
  Commands:
1693
- reconfigure Change saved selections for an existing install.
1694
- skills Sync or remove managed skills.
1695
- backup Create a backup of managed files.
1696
- uninstall Remove managed files, with an optional backup first.
5164
+ setup Install or sync this project; subcommands system, reconfigure, skills, backup, remove.
5165
+ project Manage canonical project support surfaces.
5166
+ resource List, read, or ensure stable system resources.
5167
+ run Run deterministic registry operations.
5168
+ mcp Run the TypeScript MCP server over stdio.
5169
+ update Update the installed make-docs tool itself.
5170
+ uninstall Remove make-docs' machine-level footprint.
1697
5171
 
1698
5172
  Examples:
1699
5173
  make-docs
1700
- make-docs --yes
1701
- make-docs --target ~/Projects/example --dry-run
1702
- make-docs reconfigure
1703
- make-docs reconfigure --yes --no-skills
1704
- make-docs skills --dry-run
1705
- make-docs backup --yes
1706
- make-docs uninstall --backup
5174
+ make-docs --version
5175
+ make-docs setup --yes
5176
+ make-docs setup system --dry-run
5177
+ make-docs setup reconfigure
5178
+ make-docs setup skills --dry-run
5179
+ make-docs setup remove --backup
5180
+ make-docs resource list
5181
+ make-docs run lifecycle list
5182
+ make-docs mcp
1707
5183
 
1708
5184
  Use --help or -h with any command for command-specific options and examples.
1709
5185
  `);
1710
5186
  }
1711
5187
  }
1712
5188
 
5189
+ // src/run/entry.ts
5190
+ function formatCliError(error, machineReadable) {
5191
+ const serialized = serializeOperationError(error);
5192
+ if (!machineReadable) return `${serialized.message}
5193
+ `;
5194
+ return `${JSON.stringify({ ok: false, ...serialized })}
5195
+ `;
5196
+ }
5197
+ async function runCliEntry(runCli2, argv = process.argv.slice(2), options = {}) {
5198
+ try {
5199
+ await runCli2(argv);
5200
+ return 0;
5201
+ } catch (error) {
5202
+ const machineReadable = options.machineReadable ?? requestsMachineOutput(argv);
5203
+ (options.writeError ?? ((value) => process.stderr.write(value)))(
5204
+ formatCliError(error, machineReadable)
5205
+ );
5206
+ return 1;
5207
+ }
5208
+ }
5209
+ function requestsMachineOutput(argv) {
5210
+ if (process.stdout.isTTY !== true) return true;
5211
+ if (argv.includes("--json")) return true;
5212
+ return argv.some(
5213
+ (value, index) => value === "--format" ? argv[index + 1] === "json" : value === "--format=json"
5214
+ );
5215
+ }
5216
+
5217
+ // src/run/warnings.ts
5218
+ var SUPPRESSED_WARNING_TYPE = "ExperimentalWarning";
5219
+ var SUPPRESSED_MESSAGE_PATTERN = /\bSQLite\b/;
5220
+ var installed = false;
5221
+ function warningType(warning, args) {
5222
+ if (warning instanceof Error) {
5223
+ return warning.name || null;
5224
+ }
5225
+ const [first] = args;
5226
+ if (typeof first === "string") {
5227
+ return first;
5228
+ }
5229
+ if (first && typeof first === "object" && "type" in first) {
5230
+ const type = first.type;
5231
+ return typeof type === "string" ? type : null;
5232
+ }
5233
+ return null;
5234
+ }
5235
+ function warningMessage(warning) {
5236
+ return warning instanceof Error ? warning.message : warning;
5237
+ }
5238
+ function isSqliteExperimentalWarning(warning, args = []) {
5239
+ return warningType(warning, args) === SUPPRESSED_WARNING_TYPE && SUPPRESSED_MESSAGE_PATTERN.test(warningMessage(warning));
5240
+ }
5241
+ function installSqliteExperimentalWarningFilter() {
5242
+ if (installed) {
5243
+ return () => {
5244
+ };
5245
+ }
5246
+ installed = true;
5247
+ const original = process.emitWarning.bind(process);
5248
+ const filtered = ((warning, ...args) => {
5249
+ if (isSqliteExperimentalWarning(warning, args)) {
5250
+ return;
5251
+ }
5252
+ original(warning, ...args);
5253
+ });
5254
+ process.emitWarning = filtered;
5255
+ return () => {
5256
+ if (process.emitWarning === filtered) {
5257
+ process.emitWarning = original;
5258
+ }
5259
+ installed = false;
5260
+ };
5261
+ }
5262
+
1713
5263
  // src/index.ts
1714
- runCli().catch((error) => {
1715
- const message = error instanceof Error ? error.message : String(error);
1716
- process.stderr.write(`${message}
1717
- `);
1718
- process.exitCode = 1;
5264
+ installSqliteExperimentalWarningFilter();
5265
+ runCliEntry(runCli).then((exitCode) => {
5266
+ process.exitCode = process.exitCode ?? exitCode;
1719
5267
  });
1720
5268
  //# sourceMappingURL=index.js.map