Modes: preview/apply or execute.
Use execute for routine changes.
Use preview/apply when learning a mutation command or inspecting a large multi-step request before writing files.

If a name is ambiguous, use selectors.
Run help selectors to refresh selector syntax.

modulePlan is for splitting large files into smaller modules.
Use it when a large file should be refactored into several target files.

modulePlan orchestrates semantic moves and updates affected references/imports.

Use expectEmpty when your modulePlan intent is to move all declarations out of the source file.
It does not change the move behavior; it only asks output to report remaining source declarations if any remain.
Use it only when remaining declarations would mean the split did not match your intent.
Do not use it for partial extractions.

Plan:
modulePlan preview --stdin
modulePlan execute --stdin
modulePlan apply <planId>

Use preview/apply when you want to inspect the plan before writing files.
Use execute when you want to preview and apply immediately.
Use --from with captured input handles when rerunning edited large plans.

Split one large source file into several targets:
Run:
aib modulePlan execute --stdin

Input:
{
  "sourceFile": "src/large-service.ts",
  "expectEmpty": true,
  "modules": [
    {
      "target": "src/large-service.types.ts",
      "entities": ["ServiceOptions", "ServiceMode"]
    },
    {
      "target": "src/large-service.core.ts",
      "entities": ["LargeService", "createLargeService"]
    }
  ]
}

If a large or partial modulePlan request fails, edit the captured input file and rerun with --from.
For small one-off modulePlan requests, write a corrected request instead.

Latest modulePlan input:
<session-dir>/inputs/modulePlan/_last.json

Handle:
aib:input:modulePlan:last

Example:
modulePlan preview --from aib:input:modulePlan:last
