# G-089 Scriptlib in kits + packagemode-aware lib: resolution

Status: proposed
Scope: src/make.tcl, src/vfs/ (kit vfs payloads), src/modules/punk/path-999999.0a1.0.tm, src/vfs/_config/punk_main.tcl, scriptlib/
Goal: built kits carry an internal scriptlib (baked by make.tcl into the kit vfs at app/scriptlib, curated - test fixtures/logs excluded) so a standalone punk binary has working lib: scripts, and scriptlib precedence follows the same mental model as the module path blocks: kit-internal-wins applies to the default 'internal' launch only, src/dev package modes put the project's live scriptlib first (un-masking edits during development), and a proj:-prefixed launch (G-033) additionally resolves lib: against the visited project's scriptlib.
Acceptance: a kit built with the baked scriptlib, relocated outside any source tree, runs '<exe> script lib:<name>' for a baked script; from <projectroot>/bin the default launch runs the kit copy while 'src' mode runs an edited live <projectroot>/scriptlib copy of the same name (proven by differing markers); cookfs kits either resolve their internal scriptlib too or are explicitly documented as excluded; the packagemode reaches scriptlib_resolve via a boot-provided hint rather than being re-derived; with G-033 implemented, 'proj:' adds the cwd-project's scriptlib to the search (deferred to G-033 if that lands later, recorded here).

## Context

Findings from the 2026-07-18 lib: extensionless work (punk::path 0.3.0):

- The kit-internal branch of `punk::path::scriptlib_resolve`
  (`<zipfs-root>/app/scriptlib`, or `<exepath>/scriptlib` for a mounted
  tclkit) has never been exercised: no `.vfs` layout contains a `scriptlib/`
  folder and `src/make.tcl` never references scriptlib. `lib:` works today
  only because the repo's executables sit in `<projectroot>/bin`, making
  `<exedir-parent>/scriptlib` the repo's `scriptlib/`. A standalone installed
  binary currently has NO working `lib:` source at all.
- The documented "internal scripts are deliberately NOT overridable"
  policy was intended for the default launch behaviour only (user direction
  2026-07-18), not as an absolute - once kits carry a baked scriptlib, an
  unconditional kit-first rule would mask live `scriptlib/` edits in the dev
  workflow (exe in `<projectroot>/bin`) until the next rebuild. The
  packagemode dash-list is already the user's precedence dial for module
  paths; scriptlib should ride the same mental model.
- Nothing currently records the chosen packagemode anywhere
  `punk::path` can see - punk_main consumes arg0 and rearranges paths but
  exposes no mode hint to the runtime layer. A small boot-interface addition
  is needed (candidate: a `::punkboot::` or `punk::config` "running" value
  seeded at boot).
- `scriptlib_resolve` checks only the zipfs root and the
  exepath-as-directory (tclkit) cases for the kit-internal dir; cookfs kits
  (e.g punk9cook) mount elsewhere (`//cookfstemp:/...` style roots tracked by
  punk_main's `internal_paths`) and would miss a baked scriptlib.
- The bake itself: a punkcheck-managed copy of `scriptlib/` into the
  target vfs during make, curated - `_punktest/` fixtures, `*.log`, and other
  non-shippable content excluded. Baking policy per kit class (dev-built vs
  release/standalone) is an open decision within this goal.
- Visitor semantics follow G-033's decisions: `proj:` is an explicit
  opt-in (no silent cwd rebind), and kit-first remains the canonical robust
  default for ties in visitor mode - the visited project's scriptlib joins
  the search *after* kit-internal under `proj:internal-...`, with block order
  controlling precedence as for module paths.
- Out of scope: app-shellspy's `do_script_process` keeps its own simpler
  `lib:` mapping (external-interpreter semantics, any extension); the
  `script`/`shell` subcommands are the surfaces this goal covers.

## Notes

- Related goals: G-033 (proj: scope prefix - the visitor root discovery this
  goal's proj: scriptlib clause rides on; its notes already flag that
  `proj:... script` benefits), G-018/G-019 (installable/trimmed kits),
  G-015 (achieved - script subcommand, goals/archive/G-015-script-subcommand-piped-stdin.md).
- `lib:<name>.kit` dispatch (restored in punkshell 0.14.0 via punk::path
  0.3.0's known-extensions fix) has no committed test fixture - a `.kit`
  archive would violate the no-new-binaries rule (G-004); if kit-dispatch
  coverage is wanted, generate a throwaway kit at test time or defer until
  G-005/G-006 tooling exists.