# Module Plan

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.

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

Input:
@source src/large-service.ts +expectEmpty
module src/large-service.types.ts: ServiceOptions ServiceMode
module src/large-service.core.ts: LargeService createLargeService

How inheritance works above:
@source sets the source file once.
+expectEmpty says no declarations should remain in the source after the plan.
Each module line declares one target and the entities that should move there.

modulePlan is better than many separate move requests when one large source file should be split into several target files.

Preferred DSL fields:
@source     file being split
module      target group
target      output file after module
entities    symbols listed after the colon

Target files are created when needed.
The order in the request describes intent; rely on TS/IDE refactors for reference and import updates.
