refactor(help): colocate fold guidance and extract workflows

[thymikee]

Summary

Keep fold command guidance beside its system-family declaration and reuse three small wording fragments across metadata/help. Extract related workflow help and their existing tests so cli-help.ts drops from 1,280 to 987 lines.

5 files, 854 gross lines. Existing overview files stay untouched. No new policy registry, compatibility path, or routing traits. Independent review approved the ownership and decomposition.

Validation

Tested commit 521e0f06e8c44172ad028cf3ba615d87030d41a1:

• pnpm check:affected --run: passed, 171 files / 1,385 tests, including provider integration.
• Exact before/after comparison of all 19 topic texts and order, root help, fold help, and fold metadata: identical.
• CLI/client eager closures stay 295 / 261; MCP goes 292 → 293 for the new import-free workflow text module. No external runtime dependency.
• Moved test blocks match their original assertions; repo-wide formatting and layering/fallow checks passed.

This changes help authorship only; device behavior is unchanged and does not require a live fold run. Remote CI is pending; publication does not claim merge readiness.

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	4.91 MB	4.91 MB	+79 B
Package (unpacked)	4.91 MB	4.91 MB	+79 B
Package (download)	1.47 MB	1.47 MB	-89 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	22.5 ms	22.2 ms	-0.3 ms
CLI --help	65.4 ms	64.2 ms	-1.1 ms

[cubic-dev-ai]

1 issue found across 5 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/commands/schema/cli-help-workflows.ts">

<violation number="1" location="src/commands/schema/cli-help-workflows.ts:7">
P2: This wait contract omits `wait_readiness_exhausted` and `wait_runner_restart_exhausted`, even though the runtime emits them for retriable timeout paths. Agents following this help cannot interpret those `details.reason` values; document both reasons here.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

P2: This wait contract omits wait_readiness_exhausted and wait_runner_restart_exhausted, even though the runtime emits them for retriable timeout paths. Agents following this help cannot interpret those details.reason values; document both reasons here.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At src/commands/schema/cli-help-workflows.ts, line 7:

<comment>This wait contract omits `wait_readiness_exhausted` and `wait_runner_restart_exhausted`, even though the runtime emits them for retriable timeout paths. Agents following this help cannot interpret those `details.reason` values; document both reasons here.</comment>

<file context>
@@ -0,0 +1,292 @@
+  wait_target_present: wait absent timed out with matches; details include matches and firstMatch.
+  predicate_failed: wait absent had no valid capture; final observation/diagnostic is preserved.
+  wait_capture_stalled: no readable capture finished before the deadline -- retriable.
+  wait_deadline_exceeded: a later capture used the remaining budget after an earlier readable one.
+  wait_landmark_identity_mismatch: a replay destination guard found the selector but not the recorded identity.
+  wait_stable_timeout: wait stable never saw a stable UI -- not an absence verdict.
</file context>

[thymikee]

Reviewed 521e0f0. The extracted help text matches the old text and order, and the moved tests come along unchanged. All checks pass and there are no conflicts.

One non-blocking note: foldGuidance in system/index.ts#L233 pulls out three short fragments that are each used twice in the same file, so a grep for the full sentence no longer finds it. Inlining them again is fine too.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-01 11:49 UTC