feat(mosaic): add secure skill registration CLI (#826 )

fix: reject unknown installer arguments (#825 )
fix(#792 ): fleet roster ENOENT actionable exit + installer heading printf (#818 )
2026-07-17 23:45:35 +00:00 · 2026-07-17 22:16:51 +00:00 · 2026-07-17 21:36:36 +00:00 · 2026-07-17 19:44:56 +00:00
28 changed files with 1664 additions and 38 deletions
--- a/README.md
+++ b/README.md
@@ -97,7 +97,10 @@ mosaic config path           # Print config file path
 ```bash
 mosaic doctor                # Health audit — detect drift and missing files
 mosaic sync                  # Sync skills from canonical source
-mosaic update                # Check for and install CLI updates
+mosaic skill list            # Audit Claude skill registrations and conflicts
+mosaic skill register <name> # Register one canonical skill with Claude Code
+mosaic skill unregister <name> # Remove one Mosaic-owned Claude link
+mosaic update                # Update CLI/framework and auto-register canonical skills
 mosaic wizard                # Full guided setup wizard
 mosaic bootstrap <path>      # Bootstrap a repo with Mosaic standards
 mosaic coord init            # Initialize a new orchestration mission
@@ -349,6 +352,8 @@ bash tools/install.sh --yes             # Non-interactive, accept all defaults
 bash tools/install.sh --no-auto-launch  # Skip auto-launch of wizard
 ```

+The installer rejects unrecognized flags or positional arguments before making changes and prints the supported-option usage.
+
 ## Contributing

 ```bash
--- a/docs/SITEMAP.md
+++ b/docs/SITEMAP.md
@@ -1,5 +1,10 @@
 # Documentation Sitemap

+## CLI and skill management
+
+- [Skill registration user guide](guides/user-guide.md#claude-code-skill-registration) — register, unregister, list statuses, automatic install/update reconciliation, and Claude reload behavior.
+- [Skill bridge developer guide](guides/dev-guide.md#claude-code-skill-bridge) — path-validation, ownership, clobber-protection, install/update wiring, tests, and Pi/Codex scope notes.
+
 ## Fleet configuration management

 - [Generated environment boundary](fleet/reference/generated-env-boundary.md) — roster-derived launch projection, strict local data, legacy quarantine, and downstream interface evidence.
--- a/docs/guides/dev-guide.md
+++ b/docs/guides/dev-guide.md
@@ -8,8 +8,9 @@
 4. [Adding New Agent Tools](#adding-new-agent-tools)
 5. [Adding New MCP Tools](#adding-new-mcp-tools)
 6. [Database Schema and Migrations](#database-schema-and-migrations)
-7. [API Endpoint Reference](#api-endpoint-reference)
-8. [Local Fleet Canary](./fleet-local-canary.md)
+7. [Claude Code Skill Bridge](#claude-code-skill-bridge)
+8. [API Endpoint Reference](#api-endpoint-reference)
+9. [Local Fleet Canary](./fleet-local-canary.md)

 ---

@@ -353,6 +354,37 @@ defined there.

 ---

+## Claude Code Skill Bridge
+
+The framework's canonical skill root is `~/.config/mosaic/skills/`; Claude Code
+requires registrations under `~/.claude/skills/`. The implementation in
+`packages/mosaic/src/commands/skill.ts` owns only direct-child symlinks whose
+resolved target remains inside the canonical root.
+
+Security invariants:
+
+1. Validate the user-supplied name before filesystem access against
+   `[A-Za-z0-9][A-Za-z0-9._-]*`. Separators, control characters, whitespace,
+   `..`, absolute paths, and leading `-` are invalid; filesystem-derived invalid
+   names are escaped before terminal output.
+2. Never replace a real file, directory, foreign symlink, or live misdirected
+   symlink in the Claude skill directory.
+3. Repair a dangling link only when its lexical target is inside the canonical
+   Mosaic skills root.
+4. Unregister only a symlink pointing inside that root.
+5. Enumerate canonical directories at runtime; never hardcode framework skill
+   names.
+
+`finalizeStage` reconciles after wizard/framework synchronization, and
+`runFrameworkReseed` reconciles after the sync-only `mosaic update` path. A
+foreign conflict is reported but does not prevent unrelated canonical skills
+from registering. Filesystem tests use injected temporary roots in
+`skill.spec.ts`, `finalize-skills.spec.ts`, and `update-checker.reseed.spec.ts`.
+
+M1 intentionally manages Claude Code only. Pi's Mosaic launcher can discover the
+canonical root directly. Codex still relies on the existing full skill-sync
+linker and needs separate parity analysis before this lifecycle API is extended.
+
 ## API Endpoint Reference

 All endpoints are served by the gateway at `http://localhost:14242` by default.
--- a/docs/guides/user-guide.md
+++ b/docs/guides/user-guide.md
@@ -183,6 +183,8 @@ non-interactive use:
 --no-auto-launch    # Skip auto-launch of wizard after install
 ```

+Unrecognized flags or positional arguments fail before installation starts and print the supported-option usage.
+
 Or if installed globally:

 ```bash
@@ -307,6 +309,39 @@ mosaic quality-rails

 ---

+### Claude Code Skill Registration
+
+Mosaic stores canonical skills under `~/.config/mosaic/skills/`. Claude Code scans
+`~/.claude/skills/`, so Mosaic maintains one symlink per skill between those
+directories.
+
+```bash
+mosaic skill list
+mosaic skill register <name>
+mosaic skill unregister <name>
+```
+
+- `register` is idempotent and repairs a dangling Mosaic-owned link. Names use
+  the safe grammar `[A-Za-z0-9][A-Za-z0-9._-]*`; files, directories, foreign
+  symlinks, path traversal, absolute paths, and names beginning with `-` are
+  refused.
+- `unregister` is idempotent when no entry exists. It removes only symlinks that
+  point inside `~/.config/mosaic/skills/`; foreign entries are never removed.
+- `list` reports `registered`, `unregistered`, `dangling`, `foreign`,
+  `foreign-dangling`, or `misdirected` for each canonical or Claude entry.
+
+Install, wizard finalization, and `mosaic update` framework re-seeding reconcile
+every canonical skill automatically. A skill directory added after initial
+setup therefore receives its Claude bridge without a per-skill code change or
+manual `ln -s`. If Claude Code is already running, use `/reload-skills` or start
+a new session after registration so its in-process skill registry rescans.
+
+This command group is Claude-only in M1. Pi can consume Mosaic's canonical skill
+root through its Mosaic launcher configuration and does not need this Claude
+bridge. Codex has a separate link path managed by the legacy full skill-sync
+script; equivalent lifecycle management remains follow-up scope and is not
+changed here.
+
 ## Sub-package Commands

 Each Mosaic sub-package exposes its full API surface through the `mosaic` CLI.
--- a/docs/scratchpads/804-install-unknown-flags.md
+++ b/docs/scratchpads/804-install-unknown-flags.md
@@ -0,0 +1,86 @@
+# Issue #804 — fail closed on unknown installer arguments
+
+## Objective
+
+Implement Part 1 of Gitea issue #804 only: `tools/install.sh` must reject every unrecognized flag or argument with an actionable STDERR error and nonzero exit before installation starts.
+
+## Scope and constraints
+
+- Preserve all currently recognized options and behavior, including `-y` and `--ref <branch>`.
+- No positional arguments are currently accepted by the parser.
+- Do not add `--next`, `MOSAIC_NEXT`, prerelease routing, or any Part 2 behavior.
+- TDD is mandatory: add and observe a failing process-level regression test before changing `tools/install.sh`.
+- Worker lifecycle ends after branch push, PR creation, and coordinator notification; do not merge or close #804.
+- Existing launcher-owned changes in `.mosaic/orchestrator/mission.json` and `.mosaic/orchestrator/session.lock` are out of scope and must not be committed.
+
+## Requirements and acceptance criteria
+
+- Unknown input names the offending argument on STDERR.
+- STDERR includes a short installer usage hint.
+- Exit status is nonzero.
+- The installer does not invoke npm or otherwise proceed into installation.
+- Existing recognized flags remain unchanged.
+
+## Plan
+
+1. Add a process-level Vitest regression using the installer test location under `packages/mosaic/src/commands/`.
+2. Run the focused test and record the expected RED failure.
+3. Commit the RED test as `test(#804): ...`.
+4. Replace the parser catch-all with a fail-closed STDERR error and usage hint.
+5. Update concise installer-facing documentation without introducing prerelease behavior.
+6. Run focused tests, shell syntax validation, package tests, lint, typecheck, and format checks.
+7. Run independent review tooling and remediate findings.
+8. Commit as `fix(#804): ...`, queue-guard, push, open a PR containing `Closes #804.`, notify the coordinator, and exit.
+
+## Budget
+
+- No explicit token cap supplied.
+- Working estimate: 8K tokens; narrow two-file behavior/test change plus concise docs and delivery gates.
+
+## Progress
+
+- 2026-07-17: Loaded mission state, issue #804, delivery/QA/documentation rails, and relevant TDD/Vitest/pnpm/Gitea skills.
+- 2026-07-17: Confirmed the parser has no legitimate positional arguments and currently drops all unmatched input via `*) shift ;;`.
+- 2026-07-17: Installed locked workspace dependencies with a worktree-local pnpm store; no lockfile changes.
+- 2026-07-17: Added the process-level unknown-argument regression with an isolated `$HOME` and npm shim.
+- 2026-07-17: Replaced the silent catch-all with STDERR error + usage output and exit 2 before preflight or installation.
+- 2026-07-17: Initial Codex code review found an unknown option could still be consumed as the `--ref` value. Added a second RED reproducer, then rejected option-shaped/missing `--ref` values without changing valid `--ref <branch>` behavior. The review's launcher-state note is handled by excluding both `.mosaic/orchestrator/` files from commits.
+- 2026-07-17: Updated README, user guide, and packaged framework README with the fail-closed argument contract. No API, auth, admin, sitemap/navigation, or publishing surface changed.
+
+## Verification
+
+- RED: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/install-arguments.spec.ts` — expected failure: installer exited `0` instead of nonzero at the exit-status assertion; confirms the test reproduces the silent-drop defect before production changes.
+- Remediation RED: the added `--cli --ref --bogus` case exited `0`, proving `--ref` could swallow an unknown option before the guard was added.
+- GREEN: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/install-arguments.spec.ts src/commands/install-heading.spec.ts` — 2 files, 3 tests passed.
+- Situational process check: unknown positional input exited 2, named the input on STDERR, printed usage, and did not call the npm shim.
+- `bash -n tools/install.sh` — passed.
+- Bare `--ref` process check — exited 2 with `Missing value for --ref` and usage.
+- `pnpm --filter @mosaicstack/mosaic test` — 69 files, 1,287 tests passed; framework shell checks passed. The first attempt lacked generated `dist/cli.js`; `pnpm --filter @mosaicstack/mosaic build` restored the required test precondition and the full rerun passed.
+- `pnpm lint` — 23/23 tasks passed.
+- `pnpm typecheck` — 42/42 tasks passed.
+- `pnpm format:check` — passed.
+- Codex code re-review against `origin/main` — `approve`, 0 blockers/should-fix/suggestions.
+- Codex security re-review against `origin/main` — risk `none`, 0 findings.
+
+## Acceptance evidence
+
+| Criterion | Evidence |
+| --- | --- |
+| Unknown input is named on STDERR | Process-level Vitest assertions for `--bogus`, including after `--ref` |
+| Short usage hint is printed on STDERR | Vitest usage regex + manual process output |
+| Exit is nonzero | Vitest status assertions and manual exit 2 |
+| Installation does not proceed | Isolated npm shim marker remains absent |
+| Recognized behavior is preserved | Parser cases are unchanged except validation of malformed `--ref`; full Mosaic package suite passed |
+| Part 2 is excluded | No `--next`, `MOSAIC_NEXT`, dist-tag, or prerelease routing changes |
+
+## Documentation checklist
+
+- Current canonical `docs/PRD.md` remains unchanged; issue #804 and the coordinator brief supply this bounded defect's acceptance contract.
+- Updated installer behavior in root README, user guide, and packaged framework README in the same logical change set.
+- API/OpenAPI, auth/permissions, admin operations, developer architecture, sitemap/navigation, and external publishing are not affected.
+- Scratchpad remains under `docs/scratchpads/`; no root-hygiene changes.
+
+## Risks and blockers
+
+- Part 2 remains owner-gated under #805 and is intentionally excluded.
+- No implementation blocker remains. Independent coordinator RoR, CI, merge, and issue closure remain pending after worker handoff.
--- a/docs/scratchpads/824-mosaic-skill-cli.md
+++ b/docs/scratchpads/824-mosaic-skill-cli.md
@@ -0,0 +1,112 @@
+# Issue #824 — Mosaic skill CLI and Claude bridge auto-sync
+
+## Objective
+
+Deliver `mosaic skill register|unregister|list` plus install/upgrade reconciliation of every canonical `~/.config/mosaic/skills/*` entry into `~/.claude/skills/`, without clobbering runtime-owned files or directories.
+
+## Scope and constraints
+
+- Issue: mosaicstack/stack#824
+- Branch: `feat/824-mosaic-skill-cli`
+- M1 runtime: Claude Code only.
+- Pi/Codex parity is documentation-only; no non-Claude bridge implementation.
+- Do not author the downstream `mosaic-context-refresh` skill.
+- Workers do not modify `docs/TASKS.md`, merge, close #824, or touch `main`.
+- TDD is mandatory and red-first; filesystem tests use temporary directories only.
+- Budget: no explicit token cap supplied; use a focused single-worker implementation with no new dependencies.
+
+## Requirements mapping
+
+1. Register creates the canonical Claude symlink and is idempotent.
+2. Names are untrusted: reject empty/escaping/absolute/separator/`..`/leading-dash names before filesystem mutation, with clear CLI stderr and nonzero status.
+3. Register repairs only Mosaic-owned dangling symlinks and refuses foreign files, directories, and symlinks.
+4. Unregister removes only symlinks pointing inside the canonical Mosaic skills root and is idempotent when absent.
+5. List reports registered, dangling, foreign, and canonical-but-unregistered skills.
+6. Install and upgrade generically reconcile all canonical skills after framework sync/re-seed, continuing past foreign conflicts without clobbering them.
+7. User/developer documentation describes commands, status meanings, security boundaries, and Claude-only M1 scope.
+
+## Plan
+
+1. Add co-located failing Vitest coverage for all filesystem behaviors and auto-sync.
+2. Run the focused spec and record the expected RED failure.
+3. Commit the red contract as `test(#824): ...`.
+4. Implement the skill bridge and Commander command registration.
+5. Wire reconciliation into wizard finalize and `mosaic update` re-seed, preserving non-clobber behavior.
+6. Update canonical docs and sitemap if navigation changes.
+7. Run focused tests, package tests, typecheck, lint, and formatting.
+8. Commit implementation/docs as `feat(#824): ...`, queue-guard, push, open PR with `Closes #824.`, fire completion event, and notify the coordinator.
+
+## Progress
+
+- 2026-07-17: Loaded mission/delivery/TDD/documentation rails, issue #824, active mission state, and relevant installer/update paths.
+- 2026-07-17: Confirmed `mosaic update` invokes `framework/install.sh` with `MOSAIC_SYNC_ONLY=1`; that path exits before existing post-install skill linking, leaving newly present canonical skills unregistered.
+- 2026-07-17: Coordinator addendum classified the user-supplied skill name and runtime symlink target as a path-traversal/symlink-injection surface. Expanded the initial red contract to reject traversal before mutation, preserve every foreign entry, and unregister Mosaic-owned links only.
+- 2026-07-17: Implemented the Commander command group and secure generic bridge; wired wizard finalize and successful framework re-seed reconciliation; updated user/developer/installed/root docs and sitemap.
+- 2026-07-17: Focused, package-wide, repository baseline, temp-home situational, and independent review gates completed. Ready for scoped feature commit, queue guard, push, and PR handoff.
+
+## Tests and evidence
+
+### TDD evidence
+
+- RED environment attempt: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/skill.spec.ts` initially could not locate Vitest because this fresh worktree had no dependencies.
+- Dependency setup: `pnpm install --frozen-lockfile --store-dir /home/hermes/.local/share/pnpm/store` succeeded. The explicit store was required because machine pnpm config incorrectly resolves the default store under `/root`.
+- RED behavior: focused Vitest failed with `Failed to load url ./skill.js ... Does the file exist?`, proving the bridge API was absent.
+- RED integration: finalize/update specs failed because no Claude links or `skillSync` result existed.
+- RED symlink injection: symlinked Claude/canonical root tests failed because the initial implementation followed ancestor links.
+- GREEN after review remediation: `skill.spec.ts` 36/36, `finalize-skills.spec.ts` 6/6, and `update-checker.reseed.spec.ts` 30/30.
+
+### Baseline gates
+
+- `pnpm --filter '@mosaicstack/mosaic...' run build` — pass (fresh-worktree dependency outputs built).
+- `pnpm --filter @mosaicstack/mosaic run typecheck` — pass.
+- `pnpm --filter @mosaicstack/mosaic run lint` — pass.
+- `pnpm --filter @mosaicstack/mosaic test` — pass: 69 files, 1,325 Vitest tests plus framework shell suite.
+- `pnpm typecheck` — pass: 42/42 Turbo tasks.
+- `pnpm lint` — pass: 23/23 Turbo tasks.
+- `pnpm format:check` — pass.
+
+### Situational evidence
+
+A built-CLI temp-home smoke test (no real `~/.claude` or Mosaic config touched) proved:
+
+- register creates the exact link and a second run reports `already registered`;
+- list reports registered and unregistered canonical skills;
+- `../../etc` exits 1 with `Invalid skill name` and creates no escaped path;
+- unregister removes the managed link and a second run reports `already unregistered`;
+- a fake successful framework re-seed generically registered both `added-after-setup` and `second-skill` from runtime directory enumeration.
+
+### Review evidence
+
+- Initial uncommitted Codex code/security review described name validation/clobber protection as strong; its only finding was the harness-owned, unrelated `.mosaic/orchestrator/session.lock`, which is excluded from all commits and the PR.
+- Exact branch review then identified two remediations: preserve successful framework re-seed status when bridge-wide reconciliation fails, and reject/escape control-character names to prevent terminal/log injection.
+- Both findings were reproduced red-first and remediated. A subsequent exact review identified one finalize failure-isolation blocker; a root-wide bridge error now warns and allows wizard doctor/summary/next-steps completion, with a red-first regression.
+- All remediations passed the full package and repository gates. Final exact-head review is rerun after amending the feature commit.
+
+### Acceptance mapping
+
+| Acceptance criterion | Evidence |
+| --- | --- |
+| register/unregister/list, idempotent | `skill.spec.ts` and built-CLI temp-home smoke |
+| traversal/symlink-injection protection | invalid-name matrix, foreign file/dir/link tests, symlinked-root tests |
+| list flags dangling and foreign entries | deterministic list status test |
+| install and upgrade auto-sync every canonical directory | finalize + framework re-seed integration specs; two-skill built-module smoke |
+| newly added skill becomes discoverable without manual link | `added-after-setup` auto-sync creates exact Claude link; Claude can rescan with `/reload-skills` or a new session |
+| Pi/Codex parity captured as scope note | user guide, developer guide, installed framework README |
+| documentation gate | root README, user guide, developer guide, framework README, sitemap |
+
+## Risks
+
+- Symlink replacement uses `lstat` semantics so dangling links are detectable without following them.
+- Link ownership is determined lexically against the canonical skills root, and existing symlink ancestors in either managed root are rejected before mutation.
+- Auto-sync continues across per-skill conflicts while never deleting real files/directories or foreign symlinks.
+- Claude Code discovers filesystem skills at session launch/reload boundaries; bridge creation makes a later `/reload-skills` or new session able to discover the skill, but cannot mutate an already-cached in-process registry by itself.
+- Pi does not need this Claude bridge because its Mosaic launcher can consume the canonical root. Codex lifecycle parity remains explicitly deferred.
+- No deployment surface is affected.
+
+## PR #826 review remediation
+
+- 2026-07-17: Exact-head RoR requested changes for two ownership bugs: installer pruning deleted foreign-name links under `MOSAIC_HOME` outside canonical skills, and unregister deleted a same-root link targeting a different skill. It also requested trailing-dot rejection and executable coverage support.
+- RED evidence: focused regression run failed 4 tests: register/unregister accepted `safe.`, misdirected unregister did not throw, and the install linker deleted the foreign-name link.
+- GREEN evidence: `skill.spec.ts` passes 43/43, including live and dangling foreign-name links in a temp HOME/MOSAIC_HOME and the misdirected unregister invariant.
+- Coverage: `vitest run src/commands/skill.spec.ts --coverage` passes configured 85% thresholds for `skill.ts`: 91.05% statements/lines, 86.27% branches, 95.23% functions.
+- Full gates: package build passed; package tests passed 69 files / 1,332 tests plus framework shell suite; repository typecheck 42/42, lint 23/23, and format check passed.
--- a/docs/scratchpads/ms-792-fleet-enoent-installer.md
+++ b/docs/scratchpads/ms-792-fleet-enoent-installer.md
@@ -0,0 +1,38 @@
+# ms-792 — Fleet roster error handling and installer heading
+
+## Objective
+
+Make expected missing or malformed fleet roster configuration fail with an actionable message and nonzero exit instead of a raw Node stack trace. Ensure the installer preserves the `@mosaicstack/mosaic` heading.
+
+## Plan
+
+1. Add failing coverage for missing and malformed roster input.
+2. Centralize roster-file read and parse error translation; add the CLI async error boundary.
+3. Sweep fleet command read paths that bypass the roster loader.
+4. Replace the installer heading output with format-safe rendering and test it.
+5. Run focused and repository quality checks; request independent review.
+
+## Progress
+
+- 2026-07-16: Confirmed issue #792 and branch base `9745bc3f`.
+- 2026-07-16: Installed locked workspace dependencies using a worktree-local pnpm store; no `.mosaic/` files were changed intentionally.
+- 2026-07-16: Added a shared roster read/parse guard and routed v1 fleet commands plus v1/v2 selection through Commander’s actionable nonzero error path. V2 command modules already return structured nonzero JSON errors for their guarded reads.
+- 2026-07-16: Replaced installer heading `echo` with format-safe `printf`; added a regression check for the scoped package heading.
+- 2026-07-16: Rebuilt CLI and manually verified `fleet ps` with no roster prints the initialization hint, exits 1, and has no stack trace.
+- 2026-07-17: Rebased #818 onto `origin/main` at `9ddc6fbd` (#791 PR3). The added `fleet regen` command had a canonical roster read in its sibling module; it now uses the same missing-roster guard and Commander exit path. Internal NORTH_STAR, preset, and post-write invariant reads remain intentionally unguarded.
+- 2026-07-17: RoR found that semantically invalid v1 documents still escaped as plain `Error` values. `normalizeFleetRosterV1` now preserves each validation message while converting it to `FleetRosterConfigurationError`, so its command callers use the actionable nonzero Commander path.
+
+## Verification
+
+- `pnpm --filter @mosaicstack/mosaic test` — PASS (61 files, 1,046 tests; executed outside sandbox because CLI smoke tests spawn Node)
+- `pnpm typecheck` — PASS
+- `pnpm lint` — PASS
+- `pnpm format:check` — PASS
+- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts src/commands/install-heading.spec.ts` — PASS (209 tests)
+- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet-regen-command.spec.ts` — PASS (27 tests, including missing canonical roster)
+- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts -t "semantically invalid v1 roster"` — RED then PASS; verifies duplicate agent names are reported as `fleet.roster` exit 1 without a stack trace.
+- Instrumented Vitest coverage is unavailable because `@vitest/coverage-v8` is not declared in this repository. Each branch added in the roster guard has direct unit coverage.
+
+## Risks / blockers
+
+- Dependency installation is required before executing Vitest, TypeScript, lint, and formatting gates.
--- a/packages/mosaic/framework/defaults/README.md
+++ b/packages/mosaic/framework/defaults/README.md
@@ -177,15 +177,23 @@ bash tools/install.sh --cli         # npm CLI only (skip framework)
 bash tools/install.sh --ref v1.0    # Install from a specific git ref
 ```

+The installer rejects unrecognized flags or positional arguments before making changes and prints the supported-option usage.
+
 ## Universal Skills

-The installer syncs skills from `mosaic/agent-skills` into `~/.config/mosaic/skills/`, then links each skill into runtime directories.
+The installer syncs skills from `mosaic/agent-skills` into `~/.config/mosaic/skills/`. Install, wizard finalization, and `mosaic update` automatically reconcile every canonical skill into Claude Code's `~/.claude/skills/` directory.

 ```bash
-mosaic sync                                    # Full sync (clone + link)
-~/.config/mosaic/bin/mosaic-sync-skills --link-only   # Re-link only
+mosaic sync                         # Full canonical catalog sync
+mosaic skill list                   # Show registered, missing, dangling, and foreign entries
+mosaic skill register <name>        # Register or repair one canonical Claude link
+mosaic skill unregister <name>      # Remove one Mosaic-owned Claude link
 ```

+Skill names are direct children using `[A-Za-z0-9][A-Za-z0-9._-]*`, not paths. Registration rejects traversal/control characters and never replaces foreign files, directories, or symlinks; unregister removes only links that point inside the canonical Mosaic skill root. After registering during a running Claude Code session, use `/reload-skills` or start a new session.
+
+M1 lifecycle management targets Claude Code. Pi can discover the canonical Mosaic root through its launcher configuration. Codex parity remains follow-up scope and continues to use the existing full skill-sync linker.
+
 ## Health Audit

 ```bash
--- a/packages/mosaic/framework/tools/_scripts/mosaic-sync-skills
+++ b/packages/mosaic/framework/tools/_scripts/mosaic-sync-skills
@@ -161,6 +161,7 @@ link_targets=(
 )

 canonical_real="$(readlink -f "$MOSAIC_SKILLS_DIR")"
+local_real="$(readlink -f "$MOSAIC_LOCAL_SKILLS_DIR")"

 # Build an associative array from the colon-separated whitelist for O(1) lookup.
 # When MOSAIC_INSTALL_SKILLS is empty, all skills are allowed.
@@ -203,7 +204,14 @@ link_skill_into_target() {
  link_path="$target_dir/$name"

  if [[ -L "$link_path" ]]; then
+    local raw_target resolved_target
+    raw_target="$(readlink "$link_path")"
+    resolved_target="$(node -e 'const p=require("node:path"); process.stdout.write(p.resolve(p.dirname(process.argv[1]), process.argv[2]));' "$link_path" "$raw_target")"
+    if [[ "$resolved_target" == "$canonical_real/"* || "$resolved_target" == "$local_real/"* ]]; then
      ln -sfn "$skill_path" "$link_path"
+    else
+      echo "[mosaic-skills] Preserve foreign runtime symlink: $link_path"
+    fi
    return
  fi

@@ -234,14 +242,10 @@ prune_stale_links_in_target() {
      continue
    fi

-    resolved="$(readlink -f "$link_path" 2>/dev/null || true)"
-    if [[ -z "$resolved" ]]; then
-      rm -f "$link_path"
-      echo "[mosaic-skills] Removed stale broken skill link: $link_path"
-      continue
-    fi
-
-    if [[ "$resolved" == "$MOSAIC_HOME/"* ]]; then
+    # -m resolves lexical dangling targets too. If resolution fails, ownership
+    # is unproven and the link must be preserved.
+    resolved="$(readlink -m "$link_path" 2>/dev/null || true)"
+    if [[ -n "$resolved" && "$resolved" == "$canonical_real/"* ]]; then
      rm -f "$link_path"
      echo "[mosaic-skills] Removed stale retired skill link: $link_path"
    fi
--- a/packages/mosaic/framework/tools/_scripts/mosaic-sync-skills.ps1
+++ b/packages/mosaic/framework/tools/_scripts/mosaic-sync-skills.ps1
@@ -79,9 +79,26 @@ function Link-SkillIntoTarget {

    $linkPath = Join-Path $TargetDir $name

-    # Already a junction/symlink — recreate
+    # Recreate only Mosaic-owned junctions/symlinks. Foreign reparse points are
+    # runtime-owned and must never be clobbered by install/upgrade auto-sync.
    $existing = Get-Item $linkPath -Force -ErrorAction SilentlyContinue
    if ($existing -and ($existing.Attributes -band [System.IO.FileAttributes]::ReparsePoint)) {
+        $rawTarget = @($existing.Target)[0]
+        $candidate = if ([System.IO.Path]::IsPathRooted($rawTarget)) {
+            $rawTarget
+        }
+        else {
+            Join-Path (Split-Path $linkPath -Parent) $rawTarget
+        }
+        $resolvedTarget = [System.IO.Path]::GetFullPath($candidate)
+        $canonicalRoot = [System.IO.Path]::GetFullPath($MosaicSkillsDir).TrimEnd('\') + '\'
+        $localRoot = [System.IO.Path]::GetFullPath($MosaicLocalSkillsDir).TrimEnd('\') + '\'
+        $owned = $resolvedTarget.StartsWith($canonicalRoot, [System.StringComparison]::OrdinalIgnoreCase) -or
+            $resolvedTarget.StartsWith($localRoot, [System.StringComparison]::OrdinalIgnoreCase)
+        if (-not $owned) {
+            Write-Host "[mosaic-skills] Preserve foreign runtime symlink: $linkPath"
+            return
+        }
        Remove-Item $linkPath -Force
    }
    elseif ($existing) {
--- a/packages/mosaic/package.json
+++ b/packages/mosaic/package.json
@@ -53,6 +53,7 @@
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
    "@types/react": "^18.3.0",
    "tsx": "^4.0.0",
    "typescript": "^5.8.0",
--- a/packages/mosaic/src/cli.ts
+++ b/packages/mosaic/src/cli.ts
@@ -18,6 +18,7 @@ import { registerFleetCommand } from './commands/fleet.js';
 import { registerMissionCommand } from './commands/mission.js';
 import { registerUninstallCommand } from './commands/uninstall.js';
 import { registerRestoreCommand } from './commands/restore.js';
+import { registerSkillCommand } from './commands/skill.js';
 // prdy is registered via launch.ts
 import { registerLaunchCommands } from './commands/launch.js';
 import { registerAuthCommand } from './commands/auth.js';
@@ -67,7 +68,7 @@ Command Groups:

  Runtime:    tui, login, sessions
  Gateway:    gateway
-  Framework:  agent, bootstrap, coord, doctor, fleet, init, launch, mission, prdy, seq, sync, upgrade, wizard, yolo
+  Framework:  agent, bootstrap, coord, doctor, fleet, init, launch, mission, prdy, seq, skill, sync, upgrade, wizard, yolo
  Platform:   update
  Runtimes:   claude, codex, opencode, pi
 `,
@@ -411,6 +412,10 @@ registerUninstallCommand(program);

 registerRestoreCommand(program);

+// ─── skill ───────────────────────────────────────────────────────────────────
+
+registerSkillCommand(program);
+
 // ─── telemetry ───────────────────────────────────────────────────────────────

 registerTelemetryCommand(program);
@@ -471,6 +476,18 @@ program
          return;
        }
        console.log('✔ Framework re-seeded.');
+        if (reseed.skillSyncError) {
+          console.error(`  ⚠ Claude skill reconciliation skipped: ${reseed.skillSyncError}`);
+        }
+        const skillConflicts = reseed.skillSync?.conflicts ?? [];
+        const skillChanges =
+          (reseed.skillSync?.registered.length ?? 0) + (reseed.skillSync?.repaired.length ?? 0);
+        if (skillChanges > 0) {
+          console.log(`✔ Registered ${skillChanges.toString()} Mosaic skill(s) with Claude Code.`);
+        }
+        for (const conflict of skillConflicts) {
+          console.error(`  ⚠ Skill registration skipped for ${conflict.name}: ${conflict.reason}`);
+        }
        // Propagate shipped systemd unit fixes to the ACTIVE units (re-seed only
        // touches ~/.config/mosaic/systemd/user; systemd runs ~/.config/systemd/user).
        const units = refreshActiveFleetUnits();
--- a/packages/mosaic/src/commands/fleet-regen-command.spec.ts
+++ b/packages/mosaic/src/commands/fleet-regen-command.spec.ts
@@ -150,6 +150,17 @@ describe('projectRosterV2AgentGeneratedEnv', (): void => {
 });

 describe('mosaic fleet regen', (): void => {
+  it('reports a missing canonical roster with the shared initialization hint', async (): Promise<void> => {
+    const home = await mkdtemp(join(tmpdir(), 'mosaic-fleet-regen-missing-roster-'));
+    cleanup = home;
+
+    await expect(
+      program(home, recordingRunner([])).parseAsync(['node', 'mosaic', 'fleet', 'regen', '--json']),
+    ).rejects.toThrow(
+      `No fleet roster found at ${join(home, 'fleet', 'roster.yaml')}. Run \`mosaic fleet init\``,
+    );
+  });
+
  it('is dry-run by default: reports the plan and writes nothing', async (): Promise<void> => {
    const home = await fleetHome();
    const calls: string[][] = [];
--- a/packages/mosaic/src/commands/fleet-regen-command.ts
+++ b/packages/mosaic/src/commands/fleet-regen-command.ts
@@ -1,4 +1,4 @@
-import { readFile, stat } from 'node:fs/promises';
+import { stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, relative, resolve } from 'node:path';
 import type { Command } from 'commander';
@@ -18,6 +18,7 @@ import {
  validateRosterV2Semantics,
  type FleetRosterV2,
 } from '../fleet/roster-v2.js';
+import { FleetRosterConfigurationError, readFleetRosterText } from '../fleet/fleet-roster-v1.js';

 /**
 * `mosaic fleet regen` — recovery-framed regeneration of the roster-derived
@@ -303,7 +304,7 @@ function defaultReadRoster(
  mosaicHome: string,
 ): (rosterPath: string) => Promise<FleetRosterV2> {
  return async (rosterPath: string): Promise<FleetRosterV2> => {
-    const roster = parseRosterV2(await readFile(rosterPath, 'utf8'), 'yaml');
+    const roster = parseRosterV2(await readFleetRosterText(rosterPath), 'yaml');
    // Enforce the SAME semantic gate as reconcile/plan/verify (persona resolution
    // + protected-class tool-policy match) so regen cannot project a roster the
    // rest of the fleet surface would reject.
@@ -433,6 +434,10 @@ export function registerFleetRegenCommand(fleetCommand: Command, deps: FleetRege
        // the operator must finish/verify (and clear the lock) before restarting.
        if (result.incomplete || result.cleanup) process.exitCode = 1;
      } catch (error: unknown) {
+        if (error instanceof FleetRosterConfigurationError) {
+          fleetCommand.error(error.message, { code: 'fleet.roster', exitCode: 1 });
+          return;
+        }
        process.exitCode = 1;
        const message = error instanceof Error ? error.message : String(error);
        process.stderr.write(`mosaic fleet regen failed: ${message}\n`);
--- a/packages/mosaic/src/commands/fleet.spec.ts
+++ b/packages/mosaic/src/commands/fleet.spec.ts
@@ -60,6 +60,7 @@ import {
  type SleepFn,
 } from './fleet.js';
 import { registerAgentCommand } from './agent.js';
+import { parseFleetRosterDocument, readFleetRosterText } from '../fleet/fleet-roster-v1.js';

 function buildProgram(): Command {
  const program = new Command();
@@ -166,6 +167,91 @@ describe('registerFleetCommand', () => {
  });
 });

+describe('fleet roster configuration failures', () => {
+  it('reports a missing roster with an actionable initialization hint', async () => {
+    const home = await tempDir();
+    try {
+      const program = buildProgram();
+
+      await expect(
+        program.parseAsync(['node', 'mosaic', 'fleet', '--mosaic-home', home, 'ps']),
+      ).rejects.toThrow(
+        `No fleet roster found at ${join(home, 'fleet', 'roster.json')}. Run \`mosaic fleet init\``,
+      );
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
+  it('reports a malformed roster with the path and repair hint', async () => {
+    const home = await tempDir();
+    const rosterPath = join(home, 'fleet', 'roster.json');
+    try {
+      await mkdir(dirname(rosterPath), { recursive: true });
+      await writeFile(rosterPath, '{not valid json');
+
+      await expect(loadFleetRoster(rosterPath)).rejects.toThrow(
+        `Fleet roster at ${rosterPath} is invalid. Fix the file or run \`mosaic fleet init --force\``,
+      );
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
+  it('reports an unreadable roster without exposing the filesystem error', async () => {
+    const home = await tempDir();
+    try {
+      await expect(readFleetRosterText(home)).rejects.toThrow(
+        `Could not read fleet roster at ${home}. Check the file exists and is readable.`,
+      );
+    } finally {
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
+  it('reports a malformed roster while selecting the v1/v2 command path', () => {
+    expect(() => parseFleetRosterDocument('version: [', '/srv/mosaic/fleet/roster.yaml')).toThrow(
+      'Fleet roster at /srv/mosaic/fleet/roster.yaml is invalid. Fix the file or run `mosaic fleet init --force`.',
+    );
+  });
+
+  it('reports a semantically invalid v1 roster as an actionable nonzero command error', async () => {
+    const home = await tempDir();
+    const rosterPath = join(home, 'fleet', 'roster.yaml');
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    try {
+      await mkdir(dirname(rosterPath), { recursive: true });
+      await writeFile(
+        rosterPath,
+        [
+          'version: 1',
+          'transport: tmux',
+          'agents:',
+          '  - name: canary-pi',
+          '    runtime: pi',
+          '  - name: canary-pi',
+          '    runtime: codex',
+        ].join('\n'),
+      );
+
+      await expect(
+        buildProgram().parseAsync(['node', 'mosaic', 'fleet', '--mosaic-home', home, 'ps']),
+      ).rejects.toMatchObject({
+        code: 'fleet.roster',
+        exitCode: 1,
+        message: 'Fleet roster has duplicate agent name: canary-pi.',
+      });
+      expect(stderrSpy.mock.calls.flat().join('')).toContain(
+        'Fleet roster has duplicate agent name: canary-pi.',
+      );
+      expect(stderrSpy.mock.calls.flat().join('')).not.toMatch(/\n\s+at\s/);
+    } finally {
+      stderrSpy.mockRestore();
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+});
+
 describe('fleet roster parsing', () => {
  let cleanup: string | undefined;

--- a/packages/mosaic/src/commands/fleet.ts
+++ b/packages/mosaic/src/commands/fleet.ts
@@ -19,8 +19,11 @@ import * as readline from 'node:readline';
 import type { Command } from 'commander';
 import YAML from 'yaml';
 import {
+  FleetRosterConfigurationError,
  getRosterAgent,
  loadFleetRoster,
+  parseFleetRosterDocument,
+  readFleetRosterText,
  resolveInstalledFleetRosterPath,
  type FleetAgent,
  type FleetRoster,
@@ -1913,7 +1916,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
        const commandOpts = cmd.opts<{ mosaicHome: string; roster?: string }>();
        const activePaths = resolveFleetPaths(commandOpts.mosaicHome);
        const rosterPath = await resolveRosterPath(commandOpts.mosaicHome, commandOpts.roster);
-        const roster = await loadFleetRoster(rosterPath);
+        const roster = await loadRosterAtPath(cmd, rosterPath);

        const newAgent: FleetAgent = {
          name,
@@ -1973,7 +1976,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
      const commandOpts = cmd.opts<{ mosaicHome: string; roster?: string }>();
      const activePaths = resolveFleetPaths(commandOpts.mosaicHome);
      const rosterPath = await resolveRosterPath(commandOpts.mosaicHome, commandOpts.roster);
-      const roster = await loadFleetRoster(rosterPath);
+      const roster = await loadRosterAtPath(cmd, rosterPath);

      // Guard: throws if removing leaves 0 orchestrators or agent not in roster
      const updatedRoster = removeAgentFromRoster(roster, name);
@@ -2402,14 +2405,19 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>

 async function loadRosterForCommand(cmd: Command): Promise<FleetRoster> {
  const opts = cmd.opts<{ mosaicHome: string; roster?: string }>();
-  return loadFleetRoster(await resolveRosterPath(opts.mosaicHome, opts.roster));
+  return loadRosterAtPath(cmd, await resolveRosterPath(opts.mosaicHome, opts.roster));
 }

 /** Routes only a v2 roster to the M3 desired-state control plane; v1 aliases stay compatible. */
 async function usesRosterV2ControlPlane(cmd: Command): Promise<boolean> {
  const opts = cmd.opts<{ mosaicHome: string; roster?: string }>();
  const path = await resolveRosterPath(opts.mosaicHome, opts.roster);
-  const parsed: unknown = YAML.parse(await readFile(path, 'utf8'));
+  let parsed: unknown;
+  try {
+    parsed = parseFleetRosterDocument(await readFleetRosterText(path), path);
+  } catch (error) {
+    reportFleetRosterConfigurationError(cmd, error);
+  }
  return (
    typeof parsed === 'object' &&
    parsed !== null &&
@@ -2425,7 +2433,22 @@ async function loadRosterFromAgentCommand(
 ): Promise<FleetRoster> {
  const opts = command.optsWithGlobals<{ mosaicHome?: string; roster?: string }>();
  const mosaicHome = opts.mosaicHome ?? mosaicHomeOverride ?? defaultMosaicHome();
-  return loadFleetRoster(await resolveRosterPath(mosaicHome, opts.roster));
+  return loadRosterAtPath(command, await resolveRosterPath(mosaicHome, opts.roster));
+}
+
+async function loadRosterAtPath(command: Command, path: string): Promise<FleetRoster> {
+  try {
+    return await loadFleetRoster(path);
+  } catch (error) {
+    reportFleetRosterConfigurationError(command, error);
+  }
+}
+
+function reportFleetRosterConfigurationError(command: Command, error: unknown): never {
+  if (error instanceof FleetRosterConfigurationError) {
+    command.error(error.message, { code: 'fleet.roster', exitCode: 1 });
+  }
+  throw error;
 }

 function resolveMosaicHomeFromCommand(command: Command, override?: string): string {
--- a/packages/mosaic/src/commands/install-arguments.spec.ts
+++ b/packages/mosaic/src/commands/install-arguments.spec.ts
@@ -0,0 +1,61 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { chmod, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const INSTALLER_PATH = fileURLToPath(new URL('../../../../tools/install.sh', import.meta.url));
+
+async function runInstaller(args: string[]): Promise<{
+  status: number | null;
+  stderr: string;
+  npmCalled: boolean;
+}> {
+  const home = await mkdtemp(join(tmpdir(), 'mosaic-installer-args-'));
+  const bin = join(home, 'bin');
+  const npmMarker = join(home, 'npm-called');
+
+  try {
+    await mkdir(bin);
+    const npmShim = join(bin, 'npm');
+    await writeFile(npmShim, `#!/bin/sh\n: > "${npmMarker}"\n`);
+    await chmod(npmShim, 0o755);
+
+    const result = spawnSync('bash', [INSTALLER_PATH, ...args], {
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        HOME: home,
+        MOSAIC_NO_COLOR: '1',
+        PATH: `${bin}:${process.env.PATH ?? ''}`,
+      },
+    });
+
+    return {
+      status: result.status,
+      stderr: result.stderr,
+      npmCalled: existsSync(npmMarker),
+    };
+  } finally {
+    await rm(home, { recursive: true, force: true });
+  }
+}
+
+function expectUnknownArgument(result: Awaited<ReturnType<typeof runInstaller>>): void {
+  expect(result.status).not.toBe(0);
+  expect(result.stderr).toContain('Unknown argument: --bogus');
+  expect(result.stderr).toMatch(/Usage: .*install\.sh/);
+  expect(result.npmCalled).toBe(false);
+}
+
+describe('installer arguments', () => {
+  it('rejects an unknown argument before installation starts', async () => {
+    expectUnknownArgument(await runInstaller(['--cli', '--bogus']));
+  });
+
+  it('does not let --ref consume an unknown option', async () => {
+    expectUnknownArgument(await runInstaller(['--cli', '--ref', '--bogus']));
+  });
+});
--- a/packages/mosaic/src/commands/install-heading.spec.ts
+++ b/packages/mosaic/src/commands/install-heading.spec.ts
@@ -0,0 +1,17 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const INSTALLER_PATH = fileURLToPath(new URL('../../../../tools/install.sh', import.meta.url));
+
+describe('installer CLI package heading', () => {
+  it('renders the scoped package name intact', async () => {
+    const installer = await readFile(INSTALLER_PATH, 'utf8');
+    const step = installer.match(/^step\(\)\s*\{.*\}$/m)?.[0];
+
+    expect(step).toBeDefined();
+
+    expect(step).toContain('printf \'\\n%s%s%s\\n\' "$BOLD" "$*" "$RESET"');
+    expect(installer).toContain('step "@mosaicstack/mosaic (npm package)"');
+  });
+});
--- a/packages/mosaic/src/commands/skill.spec.ts
+++ b/packages/mosaic/src/commands/skill.spec.ts
@@ -0,0 +1,421 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { Command } from 'commander';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readlinkSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  listSkills,
+  registerSkill,
+  registerSkillCommand,
+  syncClaudeSkills,
+  unregisterSkill,
+  type SkillPaths,
+} from './skill.js';
+
+const LEGACY_SYNC_SCRIPT = fileURLToPath(
+  new URL('../../framework/tools/_scripts/mosaic-sync-skills', import.meta.url),
+);
+
+describe('Claude skill bridge', () => {
+  let root: string;
+  let paths: SkillPaths;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'mosaic-skill-cli-'));
+    paths = {
+      mosaicSkillsDir: join(root, '.config', 'mosaic', 'skills'),
+      claudeSkillsDir: join(root, '.claude', 'skills'),
+    };
+    mkdirSync(paths.mosaicSkillsDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  function createSkill(name: string): string {
+    const skillDir = join(paths.mosaicSkillsDir, name);
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(join(skillDir, 'SKILL.md'), `# ${name}\n`);
+    return skillDir;
+  }
+
+  function expectCorrectLink(name: string): void {
+    const linkPath = join(paths.claudeSkillsDir, name);
+    expect(lstatSync(linkPath).isSymbolicLink()).toBe(true);
+    expect(readlinkSync(linkPath)).toBe(join(paths.mosaicSkillsDir, name));
+  }
+
+  describe('name validation', () => {
+    const invalidNames = [
+      '../../etc',
+      '/abs/path',
+      'a/b',
+      String.raw`a\b`,
+      '-rf',
+      '..',
+      'safe.',
+      'space name',
+      'line\nbreak',
+      'escape\u001B[31m',
+    ];
+
+    for (const name of invalidNames) {
+      it(`rejects ${JSON.stringify(name)} before register can escape its roots`, () => {
+        expect(() => registerSkill(name, paths)).toThrow(/invalid skill name/i);
+        expect(existsSync(paths.claudeSkillsDir)).toBe(false);
+      });
+
+      it(`rejects ${JSON.stringify(name)} before unregister can escape its roots`, () => {
+        expect(() => unregisterSkill(name, paths)).toThrow(/invalid skill name/i);
+        expect(existsSync(paths.claudeSkillsDir)).toBe(false);
+      });
+    }
+  });
+
+  describe('CLI validation errors', () => {
+    let previousExitCode: number | string | null | undefined;
+
+    beforeEach(() => {
+      previousExitCode = process.exitCode;
+      process.exitCode = undefined;
+    });
+
+    afterEach(() => {
+      process.exitCode = previousExitCode;
+    });
+
+    it.each(['register', 'unregister'])(
+      'reports invalid %s names on stderr and sets a nonzero exit status',
+      async (subcommand) => {
+        const error = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        const program = new Command().exitOverride();
+        registerSkillCommand(program, paths);
+
+        await program.parseAsync(['node', 'mosaic', 'skill', subcommand, '../../etc']);
+
+        expect(error).toHaveBeenCalledWith(expect.stringMatching(/invalid skill name/i));
+        expect(process.exitCode).toBe(1);
+        expect(existsSync(paths.claudeSkillsDir)).toBe(false);
+        error.mockRestore();
+      },
+    );
+  });
+
+  describe('CLI status output', () => {
+    let previousExitCode: number | string | null | undefined;
+
+    beforeEach(() => {
+      previousExitCode = process.exitCode;
+      process.exitCode = undefined;
+    });
+
+    afterEach(() => {
+      process.exitCode = previousExitCode;
+    });
+
+    async function run(...args: string[]): Promise<void> {
+      const program = new Command().exitOverride();
+      registerSkillCommand(program, paths);
+      await program.parseAsync(['node', 'mosaic', 'skill', ...args]);
+    }
+
+    it('reports register repair/idempotency and unregister idempotency statuses', async () => {
+      const log = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+      createSkill('status-skill');
+
+      await run('register', 'status-skill');
+      await run('register', 'status-skill');
+      rmSync(join(paths.claudeSkillsDir, 'status-skill'));
+      symlinkSync(
+        join(paths.mosaicSkillsDir, 'retired'),
+        join(paths.claudeSkillsDir, 'status-skill'),
+      );
+      await run('register', 'status-skill');
+      await run('unregister', 'status-skill');
+      await run('unregister', 'status-skill');
+
+      expect(log.mock.calls.flat()).toEqual([
+        'status-skill: registered',
+        'status-skill: already registered',
+        'status-skill: repaired dangling registration',
+        'status-skill: unregistered',
+        'status-skill: already unregistered',
+      ]);
+      log.mockRestore();
+    });
+
+    it('reports empty and populated skill lists', async () => {
+      const log = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+
+      await run('list');
+      createSkill('listed');
+      await run('list');
+
+      expect(log).toHaveBeenCalledWith('No Mosaic or Claude Code skills found.');
+      expect(log).toHaveBeenCalledWith(expect.stringMatching(/^unregistered\s+listed$/));
+      log.mockRestore();
+    });
+  });
+
+  describe('registerSkill', () => {
+    it('creates the exact canonical symlink and is idempotent', () => {
+      createSkill('new-skill');
+
+      expect(registerSkill('new-skill', paths).status).toBe('registered');
+      expectCorrectLink('new-skill');
+
+      expect(registerSkill('new-skill', paths).status).toBe('already-registered');
+      expectCorrectLink('new-skill');
+    });
+
+    it('repairs a dangling Mosaic-owned symlink', () => {
+      createSkill('new-skill');
+      mkdirSync(paths.claudeSkillsDir, { recursive: true });
+      symlinkSync(
+        join(paths.mosaicSkillsDir, 'retired-skill'),
+        join(paths.claudeSkillsDir, 'new-skill'),
+      );
+
+      expect(registerSkill('new-skill', paths).status).toBe('repaired');
+      expectCorrectLink('new-skill');
+    });
+
+    it.each(['file', 'directory', 'symlink'] as const)(
+      'refuses to clobber a foreign %s at the target',
+      (kind) => {
+        createSkill('protected');
+        mkdirSync(paths.claudeSkillsDir, { recursive: true });
+        const target = join(paths.claudeSkillsDir, 'protected');
+        const foreign = join(root, 'foreign');
+
+        if (kind === 'file') writeFileSync(target, 'keep me\n');
+        if (kind === 'directory') mkdirSync(target);
+        if (kind === 'symlink') {
+          writeFileSync(foreign, 'keep me\n');
+          symlinkSync(foreign, target);
+        }
+
+        expect(() => registerSkill('protected', paths)).toThrow(/foreign|refus/i);
+        if (kind === 'file') expect(lstatSync(target).isFile()).toBe(true);
+        if (kind === 'directory') expect(lstatSync(target).isDirectory()).toBe(true);
+        if (kind === 'symlink') expect(readlinkSync(target)).toBe(foreign);
+      },
+    );
+
+    it('refuses a symlinked Claude skills ancestor instead of writing outside the bridge root', () => {
+      createSkill('protected');
+      const externalClaude = join(root, 'external-claude');
+      mkdirSync(externalClaude);
+      symlinkSync(externalClaude, join(root, '.claude'));
+
+      expect(() => registerSkill('protected', paths)).toThrow(
+        /symlink.*ancestor|ancestor.*symlink/i,
+      );
+      expect(existsSync(join(externalClaude, 'skills', 'protected'))).toBe(false);
+    });
+
+    it('refuses a symlinked canonical skills root instead of registering an external source', () => {
+      rmSync(paths.mosaicSkillsDir, { recursive: true });
+      const externalSkills = join(root, 'external-skills');
+      mkdirSync(join(externalSkills, 'protected'), { recursive: true });
+      symlinkSync(externalSkills, paths.mosaicSkillsDir);
+
+      expect(() => registerSkill('protected', paths)).toThrow(
+        /symlink.*ancestor|ancestor.*symlink/i,
+      );
+      expect(existsSync(paths.claudeSkillsDir)).toBe(false);
+    });
+
+    it('refuses a dangling foreign symlink rather than treating it as repairable', () => {
+      createSkill('protected');
+      mkdirSync(paths.claudeSkillsDir, { recursive: true });
+      const foreignMissing = join(root, 'foreign-missing');
+      const target = join(paths.claudeSkillsDir, 'protected');
+      symlinkSync(foreignMissing, target);
+
+      expect(() => registerSkill('protected', paths)).toThrow(/foreign|refus/i);
+      expect(readlinkSync(target)).toBe(foreignMissing);
+    });
+  });
+
+  describe('unregisterSkill', () => {
+    it('removes a Mosaic-owned symlink and is idempotent when absent', () => {
+      createSkill('removable');
+      registerSkill('removable', paths);
+
+      expect(unregisterSkill('removable', paths).status).toBe('unregistered');
+      expect(existsSync(join(paths.claudeSkillsDir, 'removable'))).toBe(false);
+
+      expect(unregisterSkill('removable', paths).status).toBe('already-unregistered');
+    });
+
+    it('refuses to remove a misdirected Mosaic-root symlink', () => {
+      createSkill('other');
+      mkdirSync(paths.claudeSkillsDir, { recursive: true });
+      const requested = join(paths.claudeSkillsDir, 'requested');
+      symlinkSync(join(paths.mosaicSkillsDir, 'other'), requested);
+
+      expect(() => unregisterSkill('requested', paths)).toThrow(/misdirected/i);
+      expect(readlinkSync(requested)).toBe(join(paths.mosaicSkillsDir, 'other'));
+    });
+
+    it.each(['file', 'directory', 'symlink'] as const)('refuses to remove a foreign %s', (kind) => {
+      mkdirSync(paths.claudeSkillsDir, { recursive: true });
+      const target = join(paths.claudeSkillsDir, 'protected');
+      const foreign = join(root, 'foreign');
+
+      if (kind === 'file') writeFileSync(target, 'keep me\n');
+      if (kind === 'directory') mkdirSync(target);
+      if (kind === 'symlink') {
+        writeFileSync(foreign, 'keep me\n');
+        symlinkSync(foreign, target);
+      }
+
+      expect(() => unregisterSkill('protected', paths)).toThrow(/foreign|refus/i);
+      expect(lstatSync(target)).toBeDefined();
+      if (kind === 'symlink') expect(readlinkSync(target)).toBe(foreign);
+    });
+  });
+
+  describe('listSkills', () => {
+    it('flags registered, unregistered, Mosaic-owned dangling, and foreign entries', () => {
+      createSkill('registered');
+      createSkill('unregistered');
+      registerSkill('registered', paths);
+      symlinkSync(join(paths.mosaicSkillsDir, 'retired'), join(paths.claudeSkillsDir, 'dangling'));
+      writeFileSync(join(paths.claudeSkillsDir, 'foreign-file'), 'keep me\n');
+      symlinkSync(join(root, 'missing-foreign'), join(paths.claudeSkillsDir, 'foreign-link'));
+
+      expect(listSkills(paths)).toEqual([
+        expect.objectContaining({ name: 'dangling', status: 'dangling' }),
+        expect.objectContaining({ name: 'foreign-file', status: 'foreign' }),
+        expect.objectContaining({ name: 'foreign-link', status: 'foreign-dangling' }),
+        expect.objectContaining({ name: 'registered', status: 'registered' }),
+        expect.objectContaining({ name: 'unregistered', status: 'unregistered' }),
+      ]);
+    });
+  });
+
+  describe('install linker compatibility', () => {
+    it('preserves foreign-name links into Mosaic home but outside canonical skills', () => {
+      createSkill('missing');
+      mkdirSync(paths.claudeSkillsDir, { recursive: true });
+      const mosaicHome = join(root, '.config', 'mosaic');
+      const liveForeignTarget = join(mosaicHome, 'foreign-non-skill-target');
+      mkdirSync(liveForeignTarget);
+      const liveForeignLink = join(paths.claudeSkillsDir, 'foreign-tool');
+      const danglingForeignLink = join(paths.claudeSkillsDir, 'unresolvable-foreign');
+      symlinkSync(liveForeignTarget, liveForeignLink);
+      symlinkSync(join(mosaicHome, 'foreign-missing'), danglingForeignLink);
+
+      const result = spawnSync('bash', [LEGACY_SYNC_SCRIPT, '--link-only'], {
+        encoding: 'utf8',
+        env: { ...process.env, HOME: root, MOSAIC_HOME: mosaicHome },
+      });
+
+      expect(result.status, result.stderr).toBe(0);
+      expect(readlinkSync(liveForeignLink)).toBe(liveForeignTarget);
+      expect(readlinkSync(danglingForeignLink)).toBe(join(mosaicHome, 'foreign-missing'));
+      expect(readlinkSync(join(paths.claudeSkillsDir, 'missing'))).toBe(
+        join(paths.mosaicSkillsDir, 'missing'),
+      );
+    });
+
+    it('preserves live and dangling foreign Claude symlinks while linking missing skills', () => {
+      createSkill('dangling-foreign');
+      createSkill('live-foreign');
+      createSkill('missing');
+      mkdirSync(paths.claudeSkillsDir, { recursive: true });
+      const external = join(root, 'external');
+      mkdirSync(external);
+      const liveLink = join(paths.claudeSkillsDir, 'live-foreign');
+      const danglingLink = join(paths.claudeSkillsDir, 'dangling-foreign');
+      symlinkSync(external, liveLink);
+      symlinkSync(join(root, 'external-missing'), danglingLink);
+
+      const result = spawnSync('bash', [LEGACY_SYNC_SCRIPT, '--link-only'], {
+        encoding: 'utf8',
+        env: { ...process.env, HOME: root, MOSAIC_HOME: join(root, '.config', 'mosaic') },
+      });
+
+      expect(result.status, result.stderr).toBe(0);
+      expect(readlinkSync(liveLink)).toBe(external);
+      expect(readlinkSync(danglingLink)).toBe(join(root, 'external-missing'));
+      expect(readlinkSync(join(paths.claudeSkillsDir, 'missing'))).toBe(
+        join(paths.mosaicSkillsDir, 'missing'),
+      );
+    });
+  });
+
+  describe('syncClaudeSkills', () => {
+    it('generically creates every missing canonical link and repairs managed broken links', () => {
+      createSkill('added-after-setup');
+      createSkill('another-new-skill');
+      mkdirSync(paths.claudeSkillsDir, { recursive: true });
+      symlinkSync(
+        join(paths.mosaicSkillsDir, 'retired'),
+        join(paths.claudeSkillsDir, 'added-after-setup'),
+      );
+
+      const result = syncClaudeSkills(paths);
+
+      expect(result).toEqual({
+        registered: ['another-new-skill'],
+        repaired: ['added-after-setup'],
+        unchanged: [],
+        conflicts: [],
+      });
+      expectCorrectLink('added-after-setup');
+      expectCorrectLink('another-new-skill');
+    });
+
+    it('escapes an invalid filesystem-derived name in conflict output', () => {
+      createSkill('line\nbreak');
+
+      const result = syncClaudeSkills(paths);
+
+      expect(result.registered).toEqual([]);
+      expect(result.conflicts).toEqual([
+        expect.objectContaining({
+          name: '"line\\nbreak"',
+          reason: expect.stringMatching(/invalid/i),
+        }),
+      ]);
+      expect(existsSync(paths.claudeSkillsDir)).toBe(false);
+    });
+
+    it('continues syncing other skills without clobbering foreign entries', () => {
+      createSkill('blocked');
+      createSkill('link-me');
+      mkdirSync(paths.claudeSkillsDir, { recursive: true });
+      const blocked = join(paths.claudeSkillsDir, 'blocked');
+      writeFileSync(blocked, 'keep me\n');
+
+      const result = syncClaudeSkills(paths);
+
+      expect(result.registered).toEqual(['link-me']);
+      expect(result.conflicts).toEqual([
+        expect.objectContaining({
+          name: 'blocked',
+          reason: expect.stringMatching(/foreign|refus/i),
+        }),
+      ]);
+      expect(readlinkSync(join(paths.claudeSkillsDir, 'link-me'))).toBe(
+        join(paths.mosaicSkillsDir, 'link-me'),
+      );
+      expect(lstatSync(blocked).isFile()).toBe(true);
+    });
+  });
+});
--- a/packages/mosaic/src/commands/skill.ts
+++ b/packages/mosaic/src/commands/skill.ts
@@ -0,0 +1,419 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readlinkSync,
+  symlinkSync,
+  unlinkSync,
+  type Stats,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
+import type { Command } from 'commander';
+import { DEFAULT_MOSAIC_HOME } from '../constants.js';
+
+export interface SkillPaths {
+  mosaicSkillsDir: string;
+  claudeSkillsDir: string;
+}
+
+export type SkillRegistrationStatus = 'registered' | 'already-registered' | 'repaired';
+export type SkillUnregistrationStatus = 'unregistered' | 'already-unregistered';
+export type SkillListStatus =
+  | 'registered'
+  | 'unregistered'
+  | 'dangling'
+  | 'foreign'
+  | 'foreign-dangling'
+  | 'misdirected';
+
+export interface SkillRegistrationResult {
+  name: string;
+  status: SkillRegistrationStatus;
+  sourcePath: string;
+  linkPath: string;
+}
+
+export interface SkillUnregistrationResult {
+  name: string;
+  status: SkillUnregistrationStatus;
+  linkPath: string;
+}
+
+export interface SkillListEntry {
+  name: string;
+  status: SkillListStatus;
+  sourcePath?: string;
+  linkPath: string;
+  targetPath?: string;
+}
+
+export interface SkillSyncConflict {
+  name: string;
+  reason: string;
+}
+
+export interface SkillSyncResult {
+  registered: string[];
+  repaired: string[];
+  unchanged: string[];
+  conflicts: SkillSyncConflict[];
+}
+
+const SAFE_SKILL_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export class SkillBridgeError extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = 'SkillBridgeError';
+  }
+}
+
+/** Resolve the production bridge paths while keeping tests injectable. */
+export function getDefaultSkillPaths(): SkillPaths {
+  const mosaicHome = process.env['MOSAIC_HOME'] ?? DEFAULT_MOSAIC_HOME;
+  const claudeHome = process.env['CLAUDE_HOME'] ?? join(homedir(), '.claude');
+  return {
+    mosaicSkillsDir: join(mosaicHome, 'skills'),
+    claudeSkillsDir: join(claudeHome, 'skills'),
+  };
+}
+
+/**
+ * Reject a user-supplied name before any filesystem operation.
+ * A skill name must identify one direct child in both managed roots.
+ */
+export function validateSkillName(name: string): void {
+  if (
+    name.length === 0 ||
+    name.startsWith('-') ||
+    name.endsWith('.') ||
+    name.includes('..') ||
+    name.includes('/') ||
+    name.includes('\\') ||
+    isAbsolute(name) ||
+    !SAFE_SKILL_NAME.test(name)
+  ) {
+    throw new SkillBridgeError(
+      `Invalid skill name ${JSON.stringify(name)}: use letters, numbers, dots, underscores, or hyphens; start with a letter or number; and do not use paths, "..", or a leading "-".`,
+    );
+  }
+}
+
+function displaySkillName(name: string): string {
+  return SAFE_SKILL_NAME.test(name) ? name : JSON.stringify(name);
+}
+
+function lstatIfPresent(path: string): Stats | undefined {
+  try {
+    return lstatSync(path);
+  } catch (error: unknown) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+function assertNoSymlinkAncestors(path: string): void {
+  const absolute = resolve(path);
+  const pathRoot = parse(absolute).root;
+  let current = pathRoot;
+
+  for (const segment of relative(pathRoot, absolute).split(sep)) {
+    if (segment.length === 0) continue;
+    current = join(current, segment);
+    const entry = lstatIfPresent(current);
+    if (!entry) break;
+    if (entry.isSymbolicLink()) {
+      throw new SkillBridgeError(
+        `Refusing symlink ancestor at ${current}; managed skill roots must resolve without symlink traversal.`,
+      );
+    }
+  }
+}
+
+function assertManagedRoots(paths: SkillPaths): void {
+  assertNoSymlinkAncestors(paths.mosaicSkillsDir);
+  assertNoSymlinkAncestors(paths.claudeSkillsDir);
+}
+
+function directChild(root: string, name: string): string {
+  const resolvedRoot = resolve(root);
+  const child = resolve(resolvedRoot, name);
+  if (dirname(child) !== resolvedRoot) {
+    throw new SkillBridgeError(`Invalid skill name "${name}": resolved path escapes its root.`);
+  }
+  return child;
+}
+
+function resolveLinkTarget(linkPath: string): string {
+  return resolve(dirname(linkPath), readlinkSync(linkPath));
+}
+
+function isInsideSkillsRoot(targetPath: string, skillsRoot: string): boolean {
+  const rel = relative(resolve(skillsRoot), resolve(targetPath));
+  return rel.length > 0 && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+function isDangling(linkPath: string): boolean {
+  return !existsSync(linkPath);
+}
+
+function assertSourceSkill(name: string, paths: SkillPaths): string {
+  const sourcePath = directChild(paths.mosaicSkillsDir, name);
+  const source = lstatIfPresent(sourcePath);
+  if (!source?.isDirectory()) {
+    throw new SkillBridgeError(
+      `Canonical skill directory not found: ${sourcePath}. Add the skill under the Mosaic skills directory before registering it.`,
+    );
+  }
+  return sourcePath;
+}
+
+function foreignTargetError(linkPath: string): SkillBridgeError {
+  return new SkillBridgeError(
+    `Refusing to modify foreign entry at ${linkPath}; only symlinks pointing inside the Mosaic skills directory are managed.`,
+  );
+}
+
+/** Register one canonical skill with Claude Code without clobbering foreign entries. */
+export function registerSkill(
+  name: string,
+  paths: SkillPaths = getDefaultSkillPaths(),
+): SkillRegistrationResult {
+  validateSkillName(name);
+  assertManagedRoots(paths);
+  const sourcePath = assertSourceSkill(name, paths);
+  const linkPath = directChild(paths.claudeSkillsDir, name);
+  const existing = lstatIfPresent(linkPath);
+
+  if (!existing) {
+    mkdirSync(paths.claudeSkillsDir, { recursive: true });
+    symlinkSync(sourcePath, linkPath);
+    return { name, status: 'registered', sourcePath, linkPath };
+  }
+
+  if (!existing.isSymbolicLink()) throw foreignTargetError(linkPath);
+
+  const existingTarget = resolveLinkTarget(linkPath);
+  if (!isInsideSkillsRoot(existingTarget, paths.mosaicSkillsDir)) {
+    throw foreignTargetError(linkPath);
+  }
+
+  if (existingTarget === resolve(sourcePath) && !isDangling(linkPath)) {
+    return { name, status: 'already-registered', sourcePath, linkPath };
+  }
+
+  if (!isDangling(linkPath)) {
+    throw new SkillBridgeError(
+      `Refusing to replace live Mosaic skill symlink at ${linkPath}; it points to ${existingTarget}, not ${sourcePath}.`,
+    );
+  }
+
+  unlinkSync(linkPath);
+  symlinkSync(sourcePath, linkPath);
+  return { name, status: 'repaired', sourcePath, linkPath };
+}
+
+/** Unregister only a symlink owned by the canonical Mosaic skills root. */
+export function unregisterSkill(
+  name: string,
+  paths: SkillPaths = getDefaultSkillPaths(),
+): SkillUnregistrationResult {
+  validateSkillName(name);
+  assertManagedRoots(paths);
+  const linkPath = directChild(paths.claudeSkillsDir, name);
+  const existing = lstatIfPresent(linkPath);
+
+  if (!existing) return { name, status: 'already-unregistered', linkPath };
+  if (!existing.isSymbolicLink()) throw foreignTargetError(linkPath);
+
+  const targetPath = resolveLinkTarget(linkPath);
+  if (!isInsideSkillsRoot(targetPath, paths.mosaicSkillsDir)) throw foreignTargetError(linkPath);
+
+  const expectedTarget = resolve(directChild(paths.mosaicSkillsDir, name));
+  if (targetPath !== expectedTarget) {
+    throw new SkillBridgeError(
+      `Refusing to unregister misdirected Mosaic skill symlink at ${linkPath}; it points to ${targetPath}, not ${expectedTarget}.`,
+    );
+  }
+
+  unlinkSync(linkPath);
+  return { name, status: 'unregistered', linkPath };
+}
+
+function canonicalSkillNames(paths: SkillPaths): string[] {
+  assertNoSymlinkAncestors(paths.mosaicSkillsDir);
+  const root = lstatIfPresent(paths.mosaicSkillsDir);
+  if (!root) return [];
+  if (!root.isDirectory()) {
+    throw new SkillBridgeError(
+      `Canonical skills path is not a directory: ${paths.mosaicSkillsDir}`,
+    );
+  }
+  return readdirSync(paths.mosaicSkillsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function claudeEntryNames(paths: SkillPaths): string[] {
+  assertNoSymlinkAncestors(paths.claudeSkillsDir);
+  const root = lstatIfPresent(paths.claudeSkillsDir);
+  if (!root) return [];
+  if (!root.isDirectory()) {
+    throw new SkillBridgeError(`Claude skills path is not a directory: ${paths.claudeSkillsDir}`);
+  }
+  return readdirSync(paths.claudeSkillsDir)
+    .filter((name) => name.length > 0)
+    .sort();
+}
+
+/** Return a deterministic union of canonical skills and Claude bridge entries. */
+export function listSkills(paths: SkillPaths = getDefaultSkillPaths()): SkillListEntry[] {
+  const canonicalNames = new Set(canonicalSkillNames(paths));
+  const names = new Set([...canonicalNames, ...claudeEntryNames(paths)]);
+  const entries: SkillListEntry[] = [];
+
+  for (const name of [...names].sort()) {
+    const sourcePath = canonicalNames.has(name)
+      ? directChild(paths.mosaicSkillsDir, name)
+      : undefined;
+    const linkPath = directChild(paths.claudeSkillsDir, name);
+    const installed = lstatIfPresent(linkPath);
+
+    if (!installed) {
+      if (sourcePath) entries.push({ name, status: 'unregistered', sourcePath, linkPath });
+      continue;
+    }
+
+    if (!installed.isSymbolicLink()) {
+      entries.push({ name, status: 'foreign', sourcePath, linkPath });
+      continue;
+    }
+
+    const targetPath = resolveLinkTarget(linkPath);
+    const owned = isInsideSkillsRoot(targetPath, paths.mosaicSkillsDir);
+    const dangling = isDangling(linkPath);
+
+    if (!owned) {
+      entries.push({
+        name,
+        status: dangling ? 'foreign-dangling' : 'foreign',
+        sourcePath,
+        linkPath,
+        targetPath,
+      });
+      continue;
+    }
+
+    if (dangling) {
+      entries.push({ name, status: 'dangling', sourcePath, linkPath, targetPath });
+      continue;
+    }
+
+    entries.push({
+      name,
+      status: sourcePath && targetPath === resolve(sourcePath) ? 'registered' : 'misdirected',
+      sourcePath,
+      linkPath,
+      targetPath,
+    });
+  }
+
+  return entries;
+}
+
+/** Reconcile every canonical skill directory while preserving all foreign entries. */
+export function syncClaudeSkills(paths: SkillPaths = getDefaultSkillPaths()): SkillSyncResult {
+  const result: SkillSyncResult = {
+    registered: [],
+    repaired: [],
+    unchanged: [],
+    conflicts: [],
+  };
+
+  for (const name of canonicalSkillNames(paths)) {
+    try {
+      const registration = registerSkill(name, paths);
+      if (registration.status === 'registered') result.registered.push(name);
+      if (registration.status === 'repaired') result.repaired.push(name);
+      if (registration.status === 'already-registered') result.unchanged.push(name);
+    } catch (error: unknown) {
+      result.conflicts.push({
+        name: displaySkillName(name),
+        reason: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return result;
+}
+
+function reportCommandError(error: unknown): void {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}
+
+/** Register the `mosaic skill` command group. */
+export function registerSkillCommand(
+  program: Command,
+  paths: SkillPaths = getDefaultSkillPaths(),
+): void {
+  const skill = program
+    .command('skill')
+    .description('Manage Claude Code skill registrations')
+    .configureHelp({ sortSubcommands: true });
+
+  skill
+    .command('register <name>')
+    .description('Register a Mosaic skill with Claude Code')
+    .action((name: string) => {
+      try {
+        const result = registerSkill(name, paths);
+        if (result.status === 'already-registered') {
+          console.log(`${name}: already registered`);
+        } else if (result.status === 'repaired') {
+          console.log(`${name}: repaired dangling registration`);
+        } else {
+          console.log(`${name}: registered`);
+        }
+      } catch (error: unknown) {
+        reportCommandError(error);
+      }
+    });
+
+  skill
+    .command('unregister <name>')
+    .description('Unregister a Mosaic skill from Claude Code')
+    .action((name: string) => {
+      try {
+        const result = unregisterSkill(name, paths);
+        console.log(
+          result.status === 'already-unregistered'
+            ? `${name}: already unregistered`
+            : `${name}: unregistered`,
+        );
+      } catch (error: unknown) {
+        reportCommandError(error);
+      }
+    });
+
+  skill
+    .command('list')
+    .description('List registered, dangling, foreign, and unregistered skills')
+    .action(() => {
+      try {
+        const entries = listSkills(paths);
+        if (entries.length === 0) {
+          console.log('No Mosaic or Claude Code skills found.');
+          return;
+        }
+        for (const entry of entries) {
+          console.log(`${entry.status.padEnd(17)} ${displaySkillName(entry.name)}`);
+        }
+      } catch (error: unknown) {
+        reportCommandError(error);
+      }
+    });
+}
--- a/packages/mosaic/src/fleet/fleet-roster-v1.ts
+++ b/packages/mosaic/src/fleet/fleet-roster-v1.ts
@@ -104,6 +104,10 @@ export interface FleetRoster {

 export type FleetRosterInputFormat = 'yaml' | 'json';

+export class FleetRosterConfigurationError extends Error {
+  override name = 'FleetRosterConfigurationError';
+}
+
 export function resolveInstalledFleetRosterPath(mosaicHome: string): string {
  const yamlPath = join(mosaicHome, 'fleet', 'roster.yaml');
  try {
@@ -138,8 +142,52 @@ export function parseFleetRosterV1(
 }

 export async function loadFleetRoster(path: string): Promise<FleetRoster> {
-  const source = await readFile(path, 'utf8');
+  const source = await readFleetRosterText(path);
+  try {
    return parseFleetRosterV1(source, path.endsWith('.json') ? 'json' : 'yaml');
+  } catch (error) {
+    if (isRosterParserError(error)) throw invalidFleetRosterError(path);
+    throw error;
+  }
+}
+
+/** Read an operator-owned roster with errors that say how to recover. */
+export async function readFleetRosterText(path: string): Promise<string> {
+  try {
+    return await readFile(path, 'utf8');
+  } catch (error) {
+    if (isNodeErrorCode(error, 'ENOENT')) {
+      throw new FleetRosterConfigurationError(
+        `No fleet roster found at ${path}. Run \`mosaic fleet init\` to create one.`,
+      );
+    }
+    throw new FleetRosterConfigurationError(
+      `Could not read fleet roster at ${path}. Check the file exists and is readable.`,
+    );
+  }
+}
+
+/** Parse a roster document needed only to select the v1/v2 command path. */
+export function parseFleetRosterDocument(source: string, path: string): unknown {
+  try {
+    return YAML.parse(source);
+  } catch (error) {
+    if (isRosterParserError(error)) throw invalidFleetRosterError(path);
+    throw error;
+  }
+}
+
+function invalidFleetRosterError(path: string): FleetRosterConfigurationError {
+  return new FleetRosterConfigurationError(
+    `Fleet roster at ${path} is invalid. Fix the file or run \`mosaic fleet init --force\`.`,
+  );
+}
+
+function isRosterParserError(error: unknown): boolean {
+  return (
+    error instanceof SyntaxError ||
+    (error instanceof Error && (error.name === 'YAMLParseError' || error.name === 'YAMLWarning'))
+  );
 }

 export function getRosterAgent(roster: FleetRoster, name: string): FleetAgent {
@@ -149,6 +197,16 @@ export function getRosterAgent(roster: FleetRoster, name: string): FleetAgent {
 }

 export function normalizeFleetRosterV1(raw: RawFleetRoster): FleetRoster {
+  try {
+    return normalizeFleetRosterV1Unchecked(raw);
+  } catch (error) {
+    if (error instanceof FleetRosterConfigurationError) throw error;
+    if (error instanceof Error) throw new FleetRosterConfigurationError(error.message);
+    throw error;
+  }
+}
+
+function normalizeFleetRosterV1Unchecked(raw: RawFleetRoster): FleetRoster {
  assertObject(raw, 'Fleet roster');
  assertKnownKeys(raw, 'Fleet roster', [
    'version',
--- a/packages/mosaic/src/runtime/update-checker.reseed.spec.ts
+++ b/packages/mosaic/src/runtime/update-checker.reseed.spec.ts
@@ -7,6 +7,7 @@ import {
  mkdirSync,
  readdirSync,
  readFileSync,
+  readlinkSync,
  rmSync,
  statSync,
  symlinkSync,
@@ -300,6 +301,50 @@ describe('repairFleetCommsTools', () => {
 });

 describe('runFrameworkReseed', () => {
+  it('auto-registers every canonical skill after a successful upgrade re-seed', () => {
+    const root = mkdtempSync(join(tmpdir(), 'mosaic-reseed-skills-'));
+    const framework = join(root, 'framework');
+    const home = join(root, 'mosaic');
+    const claudeSkills = join(root, '.claude', 'skills');
+    mkdirSync(framework, { recursive: true });
+    mkdirSync(join(home, 'skills', 'added-after-setup'), { recursive: true });
+    mkdirSync(join(home, 'skills', 'another-new-skill'), { recursive: true });
+    writeFileSync(join(framework, 'install.sh'), '#!/usr/bin/env bash\nexit 0\n', { mode: 0o755 });
+
+    const res = runFrameworkReseed(framework, home, claudeSkills);
+
+    expect(res.ok).toBe(true);
+    expect(res.skillSync).toMatchObject({
+      registered: ['added-after-setup', 'another-new-skill'],
+      conflicts: [],
+    });
+    expect(readlinkSync(join(claudeSkills, 'added-after-setup'))).toBe(
+      join(home, 'skills', 'added-after-setup'),
+    );
+    expect(readlinkSync(join(claudeSkills, 'another-new-skill'))).toBe(
+      join(home, 'skills', 'another-new-skill'),
+    );
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('keeps a successful framework re-seed successful when bridge reconciliation fails', () => {
+    const root = mkdtempSync(join(tmpdir(), 'mosaic-reseed-bridge-failure-'));
+    const framework = join(root, 'framework');
+    const home = join(root, 'mosaic');
+    const claudeSkills = join(root, '.claude', 'skills');
+    mkdirSync(framework, { recursive: true });
+    mkdirSync(home, { recursive: true });
+    writeFileSync(join(home, 'skills'), 'invalid canonical root\n');
+    writeFileSync(join(framework, 'install.sh'), '#!/usr/bin/env bash\nexit 0\n', { mode: 0o755 });
+
+    const res = runFrameworkReseed(framework, home, claudeSkills);
+
+    expect(res.ok).toBe(true);
+    expect(res.skillSync).toBeUndefined();
+    expect(res.skillSyncError).toMatch(/not a directory/i);
+    rmSync(root, { recursive: true, force: true });
+  });
+
  it('reports not-ok (not throw) when the installer is absent', () => {
    const missing = mkdtempSync(join(tmpdir(), 'mosaic-noinstaller-'));
    const res = runFrameworkReseed(missing, join(missing, 'home'));
--- a/packages/mosaic/src/runtime/update-checker.ts
+++ b/packages/mosaic/src/runtime/update-checker.ts
@@ -43,6 +43,7 @@ import {
  ensureManagedDirectory,
  readRegularFileSecure,
 } from '../fleet/secure-file.js';
+import { getDefaultSkillPaths, syncClaudeSkills, type SkillSyncResult } from '../commands/skill.js';

 // ─── Types ──────────────────────────────────────────────────────────────────

@@ -871,19 +872,39 @@ export function repairFleetCommsTools(
 * describing what happened (so callers can message + decide on relaunch).
 * Best-effort: a missing installer or a non-zero exit is reported, not thrown.
 */
+export interface FrameworkReseedResult {
+  ok: boolean;
+  reason?: string;
+  skillSync?: SkillSyncResult;
+  skillSyncError?: string;
+}
+
 export function runFrameworkReseed(
  frameworkRoot = resolveBundledFrameworkRoot(),
  mosaicHome = join(homedir(), '.config', 'mosaic'),
-): { ok: boolean; reason?: string } {
+  claudeSkillsDir = getDefaultSkillPaths().claudeSkillsDir,
+): FrameworkReseedResult {
  const { installer, command, env } = buildReseedCommand(frameworkRoot, mosaicHome);
  if (!existsSync(installer)) {
    return { ok: false, reason: `installer not found: ${installer}` };
  }
  try {
    execSync(command, { stdio: 'inherit', env: { ...process.env, ...env }, timeout: 120_000 });
-    return { ok: true };
-  } catch (err) {
-    return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+  } catch (error: unknown) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+
+  try {
+    const skillSync = syncClaudeSkills({
+      mosaicSkillsDir: join(mosaicHome, 'skills'),
+      claudeSkillsDir,
+    });
+    return { ok: true, skillSync };
+  } catch (error: unknown) {
+    return {
+      ok: true,
+      skillSyncError: error instanceof Error ? error.message : String(error),
+    };
  }
 }

--- a/packages/mosaic/src/stages/finalize-skills.spec.ts
+++ b/packages/mosaic/src/stages/finalize-skills.spec.ts
@@ -9,7 +9,7 @@
 */

 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, readlinkSync, writeFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import type { WizardState } from '../types.js';
@@ -113,6 +113,40 @@ describe('finalizeStage — skill installer', () => {
    );
  }

+  it('auto-registers every canonical skill even when it was added after initial setup', async () => {
+    const claudeHome = join(tmp, '.claude');
+    const previousClaudeHome = process.env['CLAUDE_HOME'];
+    process.env['CLAUDE_HOME'] = claudeHome;
+    mkdirSync(join(tmp, 'skills', 'added-after-setup'), { recursive: true });
+    mkdirSync(join(tmp, 'skills', 'another-new-skill'), { recursive: true });
+
+    try {
+      await finalizeStage(buildPrompter(), makeState(tmp, []), makeConfigService());
+
+      expect(readlinkSync(join(claudeHome, 'skills', 'added-after-setup'))).toBe(
+        join(tmp, 'skills', 'added-after-setup'),
+      );
+      expect(readlinkSync(join(claudeHome, 'skills', 'another-new-skill'))).toBe(
+        join(tmp, 'skills', 'another-new-skill'),
+      );
+    } finally {
+      if (previousClaudeHome === undefined) delete process.env['CLAUDE_HOME'];
+      else process.env['CLAUDE_HOME'] = previousClaudeHome;
+    }
+  });
+
+  it('warns and completes finalization when bridge-wide reconciliation fails', async () => {
+    writeFileSync(join(tmp, 'skills'), 'invalid canonical root\n');
+    const p = buildPrompter();
+
+    await finalizeStage(p, makeState(tmp, []), makeConfigService());
+
+    expect(p.warn).toHaveBeenCalledWith(
+      expect.stringMatching(/Claude skill reconciliation skipped.*not a directory/i),
+    );
+    expect(p.outro).toHaveBeenCalledWith('Mosaic is ready.');
+  });
+
  it('passes MOSAIC_INSTALL_SKILLS with the selected skill list', async () => {
    const state = makeState(tmp, ['brainstorming', 'lint', 'systematic-debugging']);
    const p = buildPrompter();
--- a/packages/mosaic/src/stages/finalize.ts
+++ b/packages/mosaic/src/stages/finalize.ts
@@ -7,6 +7,11 @@ import type { ConfigService } from '../config/config-service.js';
 import type { WizardState } from '../types.js';
 import { getShellProfilePath } from '../platform/detect.js';
 import { ManifestError } from '../framework/manifest.js';
+import {
+  getDefaultSkillPaths,
+  syncClaudeSkills,
+  type SkillSyncResult as ClaudeSkillSyncResult,
+} from '../commands/skill.js';

 function linkRuntimeAssets(mosaicHome: string, skipClaudeHooks: boolean): void {
  const script = join(mosaicHome, 'bin', 'mosaic-link-runtime-assets');
@@ -205,7 +210,27 @@ export async function finalizeStage(
    skillsResult = syncSkills(state.mosaicHome, state.selectedSkills);
  }

-  // 5. Run doctor
+  // 5. Reconcile every canonical Mosaic skill into Claude Code. This is
+  // intentionally independent of the first-run selected-skill fetch above:
+  // framework installs/upgrades must also register skills added after setup.
+  spin.update('Registering Mosaic skills with Claude Code...');
+  let bridgeResult: ClaudeSkillSyncResult = {
+    registered: [],
+    repaired: [],
+    unchanged: [],
+    conflicts: [],
+  };
+  let bridgeFailure: string | undefined;
+  try {
+    bridgeResult = syncClaudeSkills({
+      mosaicSkillsDir: join(state.mosaicHome, 'skills'),
+      claudeSkillsDir: getDefaultSkillPaths().claudeSkillsDir,
+    });
+  } catch (error: unknown) {
+    bridgeFailure = error instanceof Error ? error.message : String(error);
+  }
+
+  // 6. Run doctor
  spin.update('Running health audit...');
  const doctorResult = runDoctor(state.mosaicHome);

@@ -217,10 +242,15 @@ export async function finalizeStage(
    p.warn("Run 'mosaic sync' manually after installation to install skills.");
  }

-  // 6. PATH setup
+  if (bridgeFailure) p.warn(`Claude skill reconciliation skipped: ${bridgeFailure}`);
+  for (const conflict of bridgeResult.conflicts) {
+    p.warn(`Skill registration skipped for ${conflict.name}: ${conflict.reason}`);
+  }
+
+  // 7. PATH setup
  const pathAction = setupPath(state.mosaicHome, p);

-  // 7. Summary
+  // 8. Summary
  const skillsSummary = skillsResult.success
    ? skillsResult.installedCount > 0
      ? `${skillsResult.installedCount.toString()} installed`
@@ -245,7 +275,7 @@ export async function finalizeStage(

  p.note(summary.join('\n'), 'Installation Summary');

-  // 8. Next steps
+  // 9. Next steps
  const nextSteps: string[] = [];
  if (pathAction === 'added') {
    const profilePath = getShellProfilePath();
--- a/packages/mosaic/vitest.config.ts
+++ b/packages/mosaic/vitest.config.ts
@@ -5,5 +5,16 @@ export default defineConfig({
    globals: true,
    environment: 'node',
    testTimeout: 30_000,
+    coverage: {
+      provider: 'v8',
+      include: ['src/commands/skill.ts'],
+      reporter: ['text', 'json-summary'],
+      thresholds: {
+        statements: 85,
+        branches: 85,
+        functions: 85,
+        lines: 85,
+      },
+    },
  },
 });
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -607,6 +607,9 @@ importers:
      '@types/react':
        specifier: ^18.3.0
        version: 18.3.28
+      '@vitest/coverage-v8':
+        specifier: ^2.0.0
+        version: 2.1.9(vitest@2.1.9(@types/node@22.19.15)(jsdom@29.0.0(@noble/hashes@2.0.1))(lightningcss@1.31.1))
      tsx:
        specifier: ^4.0.0
        version: 4.21.0
--- a/tools/install.sh
+++ b/tools/install.sh
@@ -61,17 +61,38 @@ if [[ "${MOSAIC_DEV:-0}" == "1" ]]; then
  FLAG_DEV=true
 fi

+installer_usage() {
+  printf 'Usage: install.sh [--check] [--framework] [--cli] [--ref <branch>] [--dev] [--yes|-y] [--no-auto-launch] [--uninstall]\n' >&2
+}
+
 while [[ $# -gt 0 ]]; do
  case "$1" in
    --check)          FLAG_CHECK=true; shift ;;
    --framework)      FLAG_CLI=false; shift ;;
    --cli)            FLAG_FRAMEWORK=false; shift ;;
-    --ref)            GIT_REF="${2:-main}"; shift 2 ;;
+    --ref)
+      if [[ $# -lt 2 ]] || [[ -z "$2" ]]; then
+        printf 'Error: Missing value for --ref\n' >&2
+        installer_usage
+        exit 2
+      fi
+      if [[ "$2" == -* ]]; then
+        printf 'Error: Unknown argument: %s\n' "$2" >&2
+        installer_usage
+        exit 2
+      fi
+      GIT_REF="$2"
+      shift 2
+      ;;
    --dev)            FLAG_DEV=true; shift ;;
    --yes|-y)         FLAG_YES=true; shift ;;
    --no-auto-launch) FLAG_NO_AUTO_LAUNCH=true; shift ;;
    --uninstall)      FLAG_UNINSTALL=true; shift ;;
-    *)                shift ;;
+    *)
+      printf 'Error: Unknown argument: %s\n' "$1" >&2
+      installer_usage
+      exit 2
+      ;;
  esac
 done

@@ -212,7 +233,7 @@ ok()    { echo "${G}✔${RESET}  $*"; }
 warn()  { echo "${Y}⚠${RESET}  $*"; }
 fail()  { echo "${R}✖${RESET}  $*" >&2; }
 dim()   { echo "${DIM}$*${RESET}"; }
-step()  { echo ""; echo "${BOLD}$*${RESET}"; }
+step()  { printf '\n%s%s%s\n' "$BOLD" "$*" "$RESET"; }

 # ─── helpers ──────────────────────────────────────────────────────────────────
Author	SHA1	Message	Date
jason.woltje	d801d6c4c8	feat(mosaic): add secure skill registration CLI (#826 ) All checks were successful ci/woodpecker/push/ci-image Pipeline was successful Details ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-07-17 23:45:35 +00:00
jason.woltje	d3bf52898b	fix: reject unknown installer arguments (#825 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-07-17 22:16:51 +00:00
jason.woltje	3f77229e88	fix(#792 ): fleet roster ENOENT actionable exit + installer heading printf (#818 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-07-17 21:36:36 +00:00
jason.woltje	686c881fe4	fix: fetch actual Gitea PR head for Codex reviews (#815 ) All checks were successful ci/woodpecker/push/publish Pipeline was successful Details ci/woodpecker/push/ci Pipeline was successful Details	2026-07-17 19:44:56 +00:00