# Higgsfield pack: design

Date: 2026-09-30. Contract: `.claude/tasks/contracts/2026-09-30-higgsfield-pack-1412.md`
(binding: request, clarifications, 14 acceptance criteria).

## Goal

Generate images, video, audio and brand media from Claude Code through the
Higgsfield CLI, and have `make plugin` reproduce the setup on any machine.
The pack costs nothing when unused: it is installed on disk, linked on demand.

## Decisions (validated by the user)

- Two toggles in `lib/toggle-external.sh`, both off by default, additive on
  any profile: `higgsfield` (7 media skills) and `higgsfield-websites` (one
  skill).
- `higgsfield-websites` is an aid for landing pages inside the existing
  Design work stack and site rules: assets and references. Never
  `higgsfield website create|deploy|publish`.
- Skills come from a git clone of `higgsfield-ai/skills` (tracks `main`),
  not from `npx skills add`, which re-links all 8 skills on every refresh.
- CLI `@higgsfield/cli` at `latest` (21st precedent).
- Routing lines in `CLAUDE.global.md`: explicit ask → enable the toggle →
  follow the skill.
- The two dead login offers already in `install-plugins.sh` (ctx7, 21st) are
  fixed here: they test stdout, which is the `tee` pipe.
- `settings.json` denies the `npm i -g` aliases (done by hand, outside the
  installer).

## Units

### `lib/higgsfield-skills.sh` (new, sourced)

Owns everything both installers share.

- `HIGGSFIELD_SKILLS_URL`: defaults to
  `https://github.com/higgsfield-ai/skills.git`; an env value wins (tests
  point it at a local fixture repo).
- `higgsfield_sync_skills <repo>`: `git clone --depth 1` into a `mktemp -d`
  stage. Every `higgsfield-*/` directory of the stage that holds a
  `SKILL.md` replaces `<repo>/skills-external/<name>` (rm, then mv). Prints
  the number of skills synced. Returns non-zero, leaving the existing copies
  untouched, when the clone fails or yields no skill. Always removes the
  stage. Nothing else from upstream is kept (`setup`, `scripts/`, plugin
  manifests, `.git`).
- `higgsfield_signed_in`: `timeout 15 higgsfield auth token </dev/null
  >/dev/null 2>&1`. The CLI is closed source, so the call is bounded and its
  output never reaches a terminal or a log.

Depends on: `git`, `mktemp`, `timeout`. No dependency on the repo's other
libs.

### `install-plugins.sh`: Step 8.6, between 8.5 and 8.7

1. CLI: present → `ok`. Absent → `npm install -g @higgsfield/cli` (or the
   pinned version from `plugins.lock.json`), then `higgsfield version` as
   the proof; failure prints the manual command, including the
   `--allow-scripts=@higgsfield/cli` form, since the package vendors its
   binary in a postinstall script that newer npm versions may hold back.
2. Skills: only when the CLI is present, `higgsfield_sync_skills "$REPO"`.
   A failed refresh with an existing copy is an `ok` (copy kept); with no
   copy, a `warn` naming the manual command.
3. Sign-in: signed in → `ok`. Otherwise, stdin is a terminal → offer
   `higgsfield auth login` (default no). Else an `info` line with the
   command.
4. Nothing is linked. The summary block lists the pack and both toggles.

Step 8.6 runs before the `apply_effort_pins` call of Step 8.7, so the
"pins after the last vendoring step" order holds (BDR-108).

The ctx7 (Step 6) and 21st (Step 8.7) login offers change from
`[ -t 0 ] && [ -t 1 ]` to `[ -t 0 ]`.

### `update-all.sh`: block before 7.4

CLI absent → `info`, skip. Else `npm install -g` the lock version, then
`higgsfield_sync_skills "$REPO"`. A parked skill is a symlink in
`skills-disabled/` pointing at `skills-external/<name>`: replacing the
source keeps the parked state.

### `lib/toggle-external.sh`

- `MANAGED_TOOLS` gains `higgsfield` and `higgsfield-websites`.
- `higgsfield_skills()`: the `skills-external/higgsfield-*/` directories
  holding a `SKILL.md`, minus `higgsfield-websites`.
- The three pack arms (status, disable, enable) serve `21st|higgsfield`
  through `pack_skills <tool>`, which dispatches to the right enumerator.
  Messages use the tool name. Status is `enabled` when any member is linked.
- After enabling a pack, a per-tool hint warns (never blocks) when the CLI
  is missing or signed out. For Higgsfield the probe is inlined: this script
  takes no new `source` (four fixture suites copy it).
- `higgsfield-websites` joins the single-symlink arm, source
  `skills-external/higgsfield-websites`.
- Header: two tool lines after `21st`; `usage()` prints two more lines.

### `doctor.sh`: section 4

CLI present → `pass` with its version; absent → `info` with the install
command. When present: signed in → `pass`, else `info` naming
`higgsfield auth login`. Never `warn`, never `fail`.

### Config and docs

- `plugins.lock.json`: `higgsfield` entry (source, version, note naming the
  skills repo and the toggles; no `managed_by`).
- `.gitignore`: `skills/higgsfield-*` and `skills-external/higgsfield-*/`.
- `CLAUDE.global.md`, Skill routing, 8 lines (306 → 314, guard 320):

  ```
  - Media generation (image, video, audio, brand kit), explicit ask →
    Higgsfield pack, off by default: `bash ~/.claude/lib/toggle-external.sh
    enable higgsfield`, then its skill (not listed yet → Read its SKILL.md
    under `~/.claude/skills/`). Metered: `higgsfield generate cost` before
    a paid run. Landing page "with Higgsfield", named ask only → `enable
    higgsfield-websites` as an aid (assets, references) inside the Design
    work stack and the site rules above; never `higgsfield website
    create|deploy|publish`.
  ```
- `README.md`: `### Higgsfield CLI` after the 21st section.
- `CHANGELOG.md`: one `### Added` bullet under `[Unreleased]`.

## Not changed, on purpose

`link.sh`, `lib/profile.sh`, every `lib/profiles/*.profile`,
`lib/effort-pins.txt`, hooks. Listing the pack in any of them would either
re-enable it on every `make link` or pull it into the profile census.

## Error handling

| Case | Behaviour |
|---|---|
| npm install fails or the binary is not vendored | `err` with the manual command; the step goes on, skills skipped |
| clone fails, copy exists | copy kept, `ok` |
| clone fails, no copy | `warn` with the manual command |
| upstream layout changes (no `higgsfield-*/SKILL.md`) | sync returns non-zero, copies kept, `warn` |
| toggle enabled, CLI missing or signed out | links created, `warn` |
| `enable` with no source | `err` naming the path checked, rc 1 |

## Tests: `lib/tests/higgsfield.test.sh`

Hermetic: a mktemp repo holding copies of `toggle-external.sh`,
`gstack-removed.sh` and `higgsfield-skills.sh`; a local git repo as the
skills source; a fake `higgsfield` first on PATH, switchable between signed
in and signed out.

Named cases (the contract's oracle greps them): `SYNC_MOVES_PACK_ONLY`,
`SYNC_REFRESH_DROPS_STALE`, `SYNC_KEEPS_PARKED`, `SYNC_FAIL_KEEPS_COPY`,
`ENABLE_PACK_EXCLUDES_WEBSITES`, `ENABLE_WEBSITES_ALONE`, `DISABLE_PARKS`,
`STATUS_STATES`, `SIGNED_OUT_WARNS`. Plus static locks on the two installers:
the sync call sits before the last `apply_effort_pins`, and no `-t 1` test
remains in `install-plugins.sh`.

## Known limits

- Upstream prompts change with no diff to review (same trade-off as 21st).
- Each upstream skill reinstalls the CLI through `curl | sh` when
  `higgsfield` is off PATH. With the CLI installed by npm this never fires.
- `higgsfield auth token` locality is unverified.