---
name: wire-host
description: Bond an admin-modules workspace to a fiddle by writing wsconfig.json and regenerating tsconfig.federation.json + cross-workspace federation symlinks. Wraps the `ws-wire-host` bin.
when_to_use: Activates when bonding a workspace to a fiddle for the first time, switching a workspace's fiddle target, after a fresh clone of a workspace repo, or when the user types `npx ws-wire-host <fiddle>`. Also when `wsconfig.json` is missing or points at the wrong fiddle.
paths:
  - "**/wsconfig.json"
allowed-tools:
  - Read
  - Edit
  - Write
  - Bash
---

Language: English only.

This skill is used to bond an admin-modules workspace to a target fiddle via `ws-wire-host`. The bind is recorded in `wsconfig.json` at the workspace root. The bin also regenerates `tsconfig.federation.json` (sibling-project path aliases) and creates `node_modules/<dep>` symlinks for every cross-workspace federation sibling currently published in the fiddle's `<fiddle>/admin/.federation/`.

## When this skill applies

- "bond this workspace to the fiddle at `<path>`"
- "wire host"
- "wsconfig.json missing — what fiddle does this belong to?"
- After a fresh clone of an admin-modules workspace (wsconfig.json is in `.gitignore` and not committed)
- User runs `npx ws-wire-host <fiddle-root>`
- Workspace was previously bonded to a different fiddle and needs re-bonding

## How it works

Entry point: `/Users/ph/projects/ws-admin-aux/admin-kit/bin/ws-wire-host.js`. Implementation: `/Users/ph/projects/ws-admin-aux/admin-kit/lib/wire-host.js`.

Steps the bin performs:

1. Validates the workspace context (`angular.json` present in PWD).
2. Validates the target — `<fiddle>` must exist and have `modules.json`.
3. Writes `<workspace>/wsconfig.json`:
   ```json
   {
     "wpmRoot": "<absolute path to fiddle>",
     "hostId": "admin"
   }
   ```
4. Calls `rebuildFederationTsconfig(workspaceDir)` — regenerates `tsconfig.federation.json` from `angular.json` sibling projects (workspace-local dist paths).
5. Calls `syncFederationSymlinks(workspaceDir)` — walks `<fiddle>/admin/.federation/*`, creates/updates `<workspace>/node_modules/<name>` → `<fiddle>/admin/.federation/<name>/` for every cross-workspace federation sibling currently published. Skips names that are workspace-local angular.json projects (npm-workspaces already owns those).

Usage:

```
npx ws-wire-host <fiddle-root>                 # bond to fiddle
npx ws-wire-host <fiddle-root> --host-id admin # explicit host (default: admin)
```

Idempotent: re-running with the same fiddle is a no-op aside from refreshing symlinks. Running with a NEW fiddle overwrites wsconfig.json (swap targets).

## Behavior contract (the agent MUST follow this when this skill is active)

- **Announce on load (MUST).** The first time this skill informs a response in a session, begin that response with the line `🧩 skill: wire-host` (combine as `🧩 skills: a, b` when several load together). Once per skill per session — it's a load marker, not a summary; do not repeat it on later turns.
- MUST resolve the fiddle path to an absolute path before invocation (relative paths are accepted but resolved internally).
- MUST verify the fiddle has `modules.json` at its root before invoking — the bin aborts otherwise but a pre-check spares the round trip.
- MUST surface the wsconfig.json that was written so the user can verify (`cat <workspace>/wsconfig.json`).
- MUST run [ws-sync-paths](#cross-links) (or re-invoke wire-host) if the agent later sees `Cannot find module '<dep>'` lib-build errors — the symlinks may need a refresh.
- MUST NOT bond a workspace to multiple fiddles simultaneously — the wsconfig is single-target.

## Common pitfalls

- **wsconfig.json in `.gitignore`.** By design — every dev/CI bonds to their own fiddle. Fresh clones always need a wire-host. Don't commit it.
- **`<fiddle>/admin/.federation/` empty at bond time.** The symlinks step creates nothing if no remotes are deployed yet. Later remotes that get deployed won't have their symlinks created by the initial wire-host. [wire-setup-modules](../wire-setup-modules/SKILL.md) re-syncs before each project's build to compensate; for manual `npm run ship` from a single workspace, run `npx ws-sync-paths` after fresh deps land in the fiddle.
- **Wrong `hostId`.** Default is `admin`; almost always correct. Only change for non-admin federation hosts.
- **Cross-workspace cycle.** `ws-wire-host` doesn't detect cycles; cycles surface as build failures + bounce warnings in [wire-setup-modules](../wire-setup-modules/SKILL.md). See the `federation-error-catalogue` skill.

## Out of scope

- This skill does NOT scaffold a workspace — see [workspace-init](../workspace-init/SKILL.md) (which can ALSO wire on init via `--wpm-root`).
- Does NOT ship modules — see [ship-workflow](../ship-workflow/SKILL.md) or [wire-setup-modules](../wire-setup-modules/SKILL.md).
- Does NOT clean stale wirings if the previous fiddle's `.federation/` had stale symlinks — those linger in `<workspace>/node_modules/` until manually cleaned.
- Does NOT touch the fiddle — only writes to the workspace.

## Cross-links

- [workspace-init/SKILL.md](../workspace-init/SKILL.md) — `--wpm-root` flag wires on init
- [ship-workflow/SKILL.md](../ship-workflow/SKILL.md) — needs wsconfig.json present
- [wire-setup-modules/SKILL.md](../wire-setup-modules/SKILL.md) — fiddle-level alternative for multi-workspace
- `ws-sync-paths` bin (`/Users/ph/projects/ws-admin-aux/admin-kit/bin/ws-sync-paths.js`) — re-runs the sync step standalone
- the `federation-error-catalogue` skill — symlink + cycle pitfalls