stack/docs/scratchpads/B2-skills-sync-path.md

B2 — Fresh-install skills sync path

Problem

Greenfield wizard on next reported:

Skills sync script not found at ~/.config/mosaic/bin/mosaic-sync-skills
Skills: install failed

Diagnosis

The framework install migration removed the legacy ~/.config/mosaic/bin/ directory and now installs framework helper scripts under:

~/.config/mosaic/tools/_scripts/

packages/mosaic/src/stages/finalize.ts still resolved wizard helper scripts from mosaicHome/bin, so wizard-selected skills failed even though mosaic-sync-skills was present in the current framework layout.

Fix

• Resolve framework helper scripts through tools/_scripts/<name> first.
• Keep a legacy bin/<name> fallback for pre-migration installs.
• Point missing-script warnings at the current tools/_scripts layout.
• Update the finalize skills test fixture to model the fresh framework layout.
• Update framework README examples from legacy bin/ helper paths to tools/_scripts/.

Verification

• Unit: pnpm --filter @mosaicstack/mosaic test -- finalize-skills
• Gates: pnpm typecheck, pnpm lint, pnpm format:check, pnpm build
• Fresh path: ran packages/mosaic/framework/install.sh with a temp MOSAIC_HOME and MOSAIC_SYNC_ONLY=1; verified tools/_scripts/mosaic-sync-skills exists, legacy bin/mosaic-sync-skills does not, and the script installs a selected fake lint skill into Mosaic + Pi runtime skill directories.