@imfusion/web-ui 0.5.1-dev.5.gb4de52d7 → 0.5.1-dev.51.gad24cd6e

package/README.md

@@ -2,6 +2,11 @@
 
 `@imfusion/web-ui` — the official shared Web UI library for ImFusion web apps, built on Base UI.
 
+- [Usage](#usage) — install, wire up, and keep the version current
+- [Documentation](#documentation) — Storybook and the developer docs
+- [Development](#development) — working on the library itself, including the Agent Skills
+- [Releasing](#releasing) — how versions are derived and how to cut one
+
 ## Usage
 
 The packages are private on npmjs.com.
@@ -33,19 +38,63 @@ import "@imfusion/web-ui/styles.css";
 import { WebUIProvider } from "@imfusion/web-ui";
 ```
 
-**There is also an AI skill to help you set up the Web UI library in your project:
-[`/imf-web-ui-setup`](./src/llms/skills/imf-web-ui-setup/SKILL.md). **
+### LLM integration
 
-## Development
+The `web-ui` package does offer first-class support for LLMs, but it's not wired up by default.
 
-Install the deps and configure git:
+To install the skills, run this command after the package is installed:
 
 ```bash
-npm install
-npm run git:config   # hooks path + rebase-only pull/merge
+npx web-ui-install
 ```
 
-**Try out **`/web-ui-dev-getting-started`** for an ai assisted start.**
+The binary asks which LLM client you use and installs everything it needs. Run it again after a version bump and it refreshes
+the directories it already installed into, without asking again — `--reconfigure` re-opens that choice.
+
+The optional `--hooks` flag also installs the agent lifecycle hooks and registers them for both hosts, in
+`.claude/settings.json` (Claude Code) and `.codex/hooks.json` (Codex). Three hooks inject one fixed line each: `SessionStart`
+and `SubagentStart` point the agent at the `imf-web-ui` skills router, and `UserPromptSubmit` names the companion skills to
+consult per task. A fourth, the `Stop` gate, blocks a turn that edited source files once, until the agent has addressed the
+project's verification. Re-running the installer refreshes the scripts and prunes retired ones along with their
+registrations. Without `--hooks`, the skills are still available but no lifecycle hook runs. The full flow is documented in
+the shipped [`agent-tooling` topic](./src/llms/skills/imf-web-ui-conventions/topics/agent-tooling.md) of the conventions
+skill.
+
+**Available consumer skills - `/imf-web-ui-*`**
+
+| Skill                     | What it does                                                                   |
+| ------------------------- | ------------------------------------------------------------------------------ |
+| `/imf-web-ui`             | The router: decides whether guidance is needed, then which companion to open.  |
+| `/imf-web-ui-setup`       | Plan and, after approval, bootstrap a consumer project by topic.               |
+| `/imf-web-ui-components`  | Component reference — what exists and how it's meant to be used.               |
+| `/imf-web-ui-ux`          | UX guidance for building interfaces with the library.                          |
+| `/imf-web-ui-conventions` | The frontend conventions baseline, including the sanctioned styling seams.     |
+| `/imf-web-ui-audit`       | Read-only health check for a consumer project, ending in a plan you approve.   |
+| `/imf-web-ui-update`      | Update the library, skills, and optional hooks, then verify before committing. |
+
+Start at `/imf-web-ui` — it routes to the rest. Storybook's **User Guide → AI Agents** page covers the whole family.
+
+### Versions and updates
+
+Every merge to master publishes a new build under the `dev` dist-tag. Which spec you install decides how you pick those up:
+
+| Spec in `package.json`             | Gets                       | Update with                    |
+| ---------------------------------- | -------------------------- | ------------------------------ |
+| `"@imfusion/web-ui": "^0.5.0"`     | matching releases          | `npm update @imfusion/web-ui`  |
+| `"@imfusion/web-ui": "latest"`     | the newest release         | `npm update @imfusion/web-ui`  |
+| `"@imfusion/web-ui": "dev"`        | the newest build of master | `npm update @imfusion/web-ui`  |
+| `"@imfusion/web-ui": "file:….tgz"` | a packed tarball, frozen   | re-pack and re-install by hand |
+
+- **Two dist-tags.** `latest` moves when a release is tagged, `dev` on every build of master (and onto the release when one
+  is cut).
+- **A range like `^0.5.0` is the usual choice.** It tracks releases and states which major you expect; bare `latest` follows
+  releases across majors, breaking changes included.
+- **Dist-tag specs stay literal.** npm keeps `dev` or `latest` as-is in `package.json` and re-resolves on every `npm update`.
+  The concrete version lands in `package-lock.json`, so builds stay reproducible until you update.
+- **Track `dev` while building against the library**, to get new components as they land. Use a release spec for anything you
+  cut a production release from, since `dev` moves whenever someone merges.
+- **A `file:` tarball never updates.** npm copies the archive into `node_modules` and re-copies the same one on every
+  install. Switch to `dev` or a version range to get updates.
 
 ## Documentation
 
@@ -58,51 +107,103 @@ npm run dev   # builds the library, then Storybook + a rebuild watcher
 
 See the [Developer Docs](./docs/README.md).
 
-## AI agents
-
-Two families of Agent Skills, told apart by their prefix:
-
-| Prefix         | For                           | Lives in                   | How to get it               |
-| -------------- | ----------------------------- | -------------------------- | --------------------------- |
-| `imf-web-ui-*` | Apps consuming the library    | shipped in the npm package | `npx web-ui-install-skills` |
-| `web-ui-dev-*` | Developing the library itself | `.agents/skills/`          | already there after cloning |
-
-### Development skills — `web-ui-dev-*`
-
-**`web-ui-dev-*`** never ships; it's the workflow for working on this repo — scaffolding a component, authoring a story,
-committing. Start with `/web-ui-dev-getting-started`, which routes you the same way.
-
-| Skill                                     | What it does                                                                          |
-| ----------------------------------------- | ------------------------------------------------------------------------------------- |
-| `/web-ui-dev-getting-started`             | Interactive intro — gauges your experience, works out your goal, routes you.          |
-| `/web-ui-dev-start`                       | Starting ritual for any task: Jira context, `master` vs. a worktree, context summary. |
-| `/web-ui-dev-new-component`               | Scaffolds an architecture-compliant primitive (adapted or absorbed).                  |
-| `/web-ui-dev-update-component`            | Pointers to every file a prop, variant, or sub-component change touches.              |
-| `/web-ui-dev-design-component`            | Brand design pass for a component that works but isn't styled yet.                    |
-| `/web-ui-dev-story`                       | Author or update a Storybook story.                                                   |
-| `/web-ui-dev-commit`                      | Commit workflow: staged docs audit, CI-parity checks, house commit format.            |
-| `/web-ui-dev-audit-docs`                  | Audit docs against staged or recent changes for staleness, gaps, and drift.           |
-| `/web-ui-dev-audit-pass-through-defaults` | Check `@default` annotations on pass-through props against Base UI upstream.          |
-| `/web-ui-dev-manage-worktrees`            | Create, close, or discard a worktree in `.workspaces/`.                               |
-| `/web-ui-dev-refresh-design-reference`    | Refresh the committed brand snapshots in `design/` from the Figma styleguide.         |
-| `/web-ui-dev-mcp`                         | Set up or recover Storybook, DevTools, Atlassian, or Figma MCP access.                |
-
-### Consumer skills — `imf-web-ui-*`
-
-**`imf-web-ui-*`** travels with the package, so an agent in a consumer app gets library guidance without reading this
-library's source. ` imf-web-ui` — the bare name, no suffix — is the router: it costs little to load and decides which
-companion applies, or that none does.
-
-The companions cover library wiring (`-setup`), the component reference (`-components`), UX guidance (`-ux`), frontend
-patterns (`-frontend-patterns`), and ImFusion project tooling (`-imfusion-frontend-setup`).
-
-| Skill                                 | What it does                                                                         |
-| ------------------------------------- | ------------------------------------------------------------------------------------ |
-| `/imf-web-ui`                         | The router: decides whether guidance is needed, then which companion to open.        |
-| `/imf-web-ui-setup`                   | One-time wiring in a consumer project — the styles import and the provider.          |
-| `/imf-web-ui-components`              | Component reference — what exists and how it's meant to be used.                     |
-| `/imf-web-ui-ux`                      | UX guidance for building interfaces with the library.                                |
-| `/imf-web-ui-frontend-patterns`       | Frontend patterns, including the sanctioned styling seams (tokens, data attributes). |
-| `/imf-web-ui-imfusion-frontend-setup` | Set up or audit an ImFusion frontend's tooling against the house baseline.           |
-
-Keep these tables current when a skill is added, renamed, or removed — `/web-ui-dev-audit-docs` checks them.
+## Development
+
+Install the deps and configure git:
+
+```bash
+npm install
+npm run git:config   # hooks path + rebase-only pull/merge
+```
+
+**Try out **`/web-ui-dev-getting-started`** for an ai assisted start.**
+
+### LLM integration
+
+These skills are shipped with a `/web-ui-dev-*` prefix, so to make their names identifiable and not pollute the skill
+namespace.
+
+| Skill                                     | What it does                                                                                                            |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `/web-ui-dev-getting-started`             | Interactive intro — gauges your experience, works out your goal, routes you.                                            |
+| `/web-ui-dev-start`                       | Starting ritual for any task: Jira context, `master` vs. a worktree, context summary.                                   |
+| `/web-ui-dev-new-component`               | Scaffolds an architecture-compliant primitive (adapted or absorbed).                                                    |
+| `/web-ui-dev-update-component`            | Pointers to every file a prop, variant, or sub-component change touches.                                                |
+| `/web-ui-dev-design-component`            | Brand design pass for a component that works but isn't styled yet.                                                      |
+| `/web-ui-dev-story`                       | Author or update a Storybook story.                                                                                     |
+| `/web-ui-dev-commit`                      | Commit workflow: changelog skill, staged docs audit, CI-parity checks, house commit format.                             |
+| `/web-ui-dev-changelog`                   | Generate and validate the required one-line CHANGELOG.md entry for a web-ui change, including direct commits to master. |
+| `/web-ui-dev-audit-docs`                  | Audit docs against staged or recent changes for staleness, gaps, and drift.                                             |
+| `/web-ui-dev-audit-pass-through-defaults` | Check `@default` annotations on pass-through props against Base UI upstream.                                            |
+| `/web-ui-dev-teardown-worktree`           | Tear down a worktree, wherever it lives — merging its branch first or dropping it.                                      |
+| `/web-ui-dev-refresh-design-reference`    | Refresh the committed brand snapshots in `design/` from the Figma styleguide.                                           |
+| `/web-ui-dev-mcp`                         | Set up or recover Storybook, DevTools, Atlassian, or Figma MCP access.                                                  |
+
+## Releasing
+
+Release-facing changes are recorded as one-line entries in [`CHANGELOG.md`](./CHANGELOG.md) under `## [Unreleased]`. The
+commit workflow requires an entry for pull-request commits and direct commits to `master`, with only narrow mechanical
+exceptions. Each entry ends with its author as ` — Name <email>`, taken from the committer's git config.
+
+The published version is derived from git tags, not from `package.json`.
+
+The `version` field stays at `0.0.0` in the repository and he CI computes the real number with
+[`scripts/version.ts`](./scripts/version.ts) and writes it into `package.json` on the build agent just before publishing.
+
+That working copy is thrown away, so nothing is committed back.
+
+`scripts/version.ts` reads `git describe` and applies two rules:
+
+Given the tag `web-ui/v0.5.0`:
+
+| Where HEAD sits            | Published version       | dist-tag |
+| -------------------------- | ----------------------- | -------- |
+| Exactly on `web-ui/v0.5.0` | `0.5.0`                 | `latest` |
+| 5 commits after that tag   | `0.5.1-dev.5.gb4de52d7` | `dev`    |
+
+The off-tag string breaks down as:
+
+```
+0.5.1-dev.5.gb4de52d7
+└─┬─┘ └┬┘ │ └───┬────┘
+  │    │  │     └── commit hash, abbreviated; the leading g means "git"
+  │    │  └──────── commits since the tag
+  │    └─────────── pre-release marker, which is what puts it on the dev tag
+  └──────────────── the tag's version, patch bumped
+```
+
+Bumping the patch is what makes a dev build sort above the release it follows and below the next one.
+
+Every build of `master` publishes a `dev` version automatically. To check what the current checkout would publish:
+
+```bash
+npx tsx scripts/version.ts        # prints, changes nothing
+```
+
+### Cutting a release
+
+Tag the commit you want to ship and push the tag:
+
+```bash
+git tag -a web-ui/v0.5.1 -m "web-ui 0.5.1"
+git push origin web-ui/v0.5.1
+```
+
+The tag triggers a build that publishes `0.5.1` as `latest` and repoints the `dev` dist-tag at the same version.
+
+**The tag must be annotated (`-a`).** `git describe` ignores lightweight tags, so a tag pushed without `-a` is invisible to
+the version script — the build reads through it to the previous release tag and publishes another `dev` version instead of
+the release.
+
+The tag name must match `web-ui/vX.Y.Z` exactly. Both the version script's `--match` and the TeamCity branch filter in
+[`.teamcity/settings.kts`](./.teamcity/settings.kts) key off that shape; a tag in any other form publishes nothing.
+
+### Building locally with a real version
+
+A local `npm run build` stamps `dist` with `0.0.0`. When you need the true version in a local artifact:
+
+```bash
+npx tsx scripts/version.ts --write   # writes it into package.json
+npm run build
+git checkout package.json            # discard the write
+```