Overlay-aware activation for project-scoped Nushell packages

[tonythethompson]

Problem

Persistent vendor autoload is appropriate for global modules, but it is the wrong activation scope for packages that should be present only in a project or the current interactive session. Numan has no first-class overlay model, so users must manually locate an installed module and manage overlay use / overlay hide themselves.

Goal

Add an overlay activation mode for eligible Nu packages while preserving Numan's core rule: installation is inert and activation is explicit, owned, and reversible.

Proposed contract

• A package may declare itself overlay-eligible and identify an explicit overlay module entry point.
• Numan distinguishes persistent activation from session/project overlay activation. Neither is implied by installation.
• The integration surface must execute in the caller's Nushell process, so the design must use a Nu-native shim/module rather than pretending an external numan process can mutate its parent shell.
• numan inspect identifies overlay eligibility, exported surface, required environment changes, and any package conflicts before activation.
• Overlay names, exported commands, and environment variables have deterministic conflict rules; ambiguity fails closed.
• Hide/deactivate removes only Numan-owned overlay state and must not undo user-created overlays.
• Package payloads remain immutable and no arbitrary user config file is rewritten.

Project scope

• Define an opt-in project descriptor or explicit command path for activating a package overlay in the current shell.
• Support a predictable discovery order and a clear boundary between project-local state and globally installed package artifacts.
• Record provenance and active mode in status/lock state without treating an ephemeral session overlay as persistent activation.

Acceptance criteria

• Design note covers the same-process activation mechanism, package schema, project discovery/selection rules, precedence, conflict behavior, hide behavior, and cross-platform path handling.
• Real-Nu acceptance tests prove an overlay's commands/environment exist after enablement in the same shell and disappear after hide, without leaking to a new shell.
• Fixtures cover repeated use/hide, two overlay conflicts, persistent-module interactions, project-root changes, malformed entries, and interruption-safe generated state.
• Documentation gives a minimal project workflow and clearly distinguishes overlay mode from hooks and global activation.

Non-goals

• Automatically enabling overlays on directory change.
• Turning arbitrary packages into overlays without an explicit compatible entry point.
• Replacing Nushell's native overlay semantics.