feat: reference an out-of-repo module into the run graph (#467)

[antoinetoussaint-byte]

Closes#467.

Summary

• Spike outcome: the core model already resolves path-referenced modules — ModuleReference.PathOverride (path: in workspace.codefly.yaml) flows through Workspace.ModulePath → LoadModuleFromReference → LoadServices, so codefly run already boots a referenced module alongside local ones. The gap was purely CLI surface: no way to declare a reference, and doctor never reported one.
• Adds codefly add module <name> --source <path>: registers a module by reference (records a path: override, absolute for out-of-repo sources, workspace-relative when the source lives in-tree) instead of vendoring a copy under modules/<name>/. The source is loaded and its manifest name checked, so a dangling or mislabelled reference fails before anything is written. Mutually exclusive with --agent (scaffold mode).
• Adds a codefly doctor workspace check that names each referenced module and its resolved path, flagging an unresolved reference with the new stable diagnostic code module_reference_unresolved — instead of the opaque "cannot load workspace services" that surfaced before.
• This is the lighter composition mode for multi-repo solutions (a solution repo referencing host + runtime modules it does not own); it does not replace sync module, which still vendors a hash-pinned base.

Known constraint — out-of-repo references are stored as absolute paths (interim)

This CLI is pinned to core v0.3.8, whose module-reference validation confines relative overrides to the workspace subtree. So an out-of-repo source (a sibling checkout) can only be stored as an absolutepath: — which is machine-specific and not portable across checkouts/CI. Committing such a reference and cloning the repo elsewhere will surface as module_reference_unresolved in codefly doctor until the path is fixed locally.

The portable form (path: ../host, a relative sibling path) is unblocked by codefly-dev/core#351 (merged), which permits upward-traversing relative overrides for module references specifically. A follow-up will bump this CLI's core pin to a release containing #351 and switch add module --source to store the relative form when possible. Shipping the absolute-path interim now keeps the surface flexible while that lands.

Test plan

• go test ./cmd/add/ ./cmd/ — new tests: reference registers a path: entry without vendoring and resolves back to the source; name mismatch is rejected without registering; doctor reports a resolved reference and flags an unresolved one as module_reference_unresolved.
• gofmt / go vet clean on changed files; go build ./cmd/....
• docs/commands.md updated with the --source example and the composition-vs-vendoring note.

🤖 Generated with Claude Code