xh

Authoritative reference for the io.xh:hoist-core Grails/Groovy framework -- use when writing, modifying, debugging, or explaining Groovy/Java backend code that touches hoist-core, or installing/refreshing the hoist-core MCP/CLI tooling. Why this matters: hoist-core's base classes and infrastructure types have conventions that differ from plain Spring/Grails for injection, clustering, and config. Guessing produces code that compiles and runs single-node, then misbehaves under cluster failover -- invalidations that don't propagate, timers that double-fire, scheduled tasks that miss their slot. TRIGGER when the user mentions a hoist-core symbol (`BaseService`, `BaseController`, `Cache`, `Timer`, `ConfigService`, `ClusterService`, `MonitorService`, `JSONClient`); a hoist-core concept (caching, cluster-aware, distributed cache, config-driven, monitoring, scheduled task, conventions); a service/controller under `grails-app/`/`src/`; doing a backend task the framework way or using our conventions; installing/upgradi

Authoritative reference for the @xh/hoist React framework -- use when writing, modifying, debugging, or explaining TypeScript/React code that touches Hoist, or when answering how Hoist works. Why this matters: Hoist's API evolves; decorator names shift between versions, `*Config` interfaces look like plain React props but aren't, and `loadAsync`/`addAutorun`/`addReaction` differ from plain MobX. Guessing produces code that type-checks but fails at runtime: silent persistence no-ops, leaked autoruns, ignored props, observable state that never re-renders. TRIGGER when the user mentions a Hoist symbol (`hoistCmp`, `HoistModel`, `HoistService`, `XH`, `Grid`, `Panel`, `TabContainer`, `Store`, `*Config`); a Hoist decorator (`@bindable`, `@managed`, `@persist`, etc.); a Hoist concept (persistence, autorun, reaction, `loadAsync`, refresh, element factory, MobX integration, grid columns); a `*Model.ts`/`*Panel.tsx` file with state/refresh/persistence/grid questions; a change under `client-app/` that introduces or modi

Configure and verify AI setup for a Hoist project. Detects project type, generates CLAUDE.md, configures the hoist-react MCP server, optionally installs the hoist-core MCP+CLI tools, and verifies the surfaces in the current environment.

Upgrade a Hoist app's `@xh/hoist` dependency across one or more major versions. Reads per-version upgrade guides, auto-applies mechanical code migrations, flags judgment calls, bumps `hoistCoreVersion` (and refreshes the hoist-core MCP+CLI launchers if previously installed), and produces a comprehensive upgrade report.

Verify, finalize, and write upgrade documentation for a major Hoist React release. Use when preparing a release, verifying or finalizing the changelog, writing upgrade notes, or any task involving release readiness for a major version (e.g. "prepare for release", "verify the changelog", "write upgrade notes for v84", "we're releasing today"). Produces a finalized CHANGELOG entry, a detailed upgrade-notes document with before/after code examples, and updates all doc indexes.

Pre-commit documentation consistency check. Ensures docs/README.md index, docs/planning/docs-roadmap.md, and the MCP server's document registry (docs/doc-registry.json) stay in sync with documentation files on disk. Validates inter-doc links and enhances cross-references when new docs are added. Use this skill whenever adding, renaming, moving, or deleting any README or concept doc — and before committing documentation changes. Also use when asked to "update the docs index", "check doc links", or "sync the doc registry".

Update hoist-react documentation after adding new components or features. Use when a developer has made changes to hoist-react and wants to update README files, AGENTS.md, and the documentation roadmap (docs/planning/docs-roadmap.md) to reflect those changes. Invoke with a commit hash or PR number. Also use when you detect that recent commits or PRs have added new components, models, or services that are not yet reflected in the documentation. Use whenever asked to "document recent changes", "update the docs for this PR", or "write a README for this package". This skill writes and updates documentation content — for syncing indexes, links, and the doc registry without writing new content, see `xh-update-doc-links`.

Verify, finalize, and write upgrade documentation for a major Hoist Core release. Use when preparing a release, verifying or finalizing the changelog, writing upgrade notes, or any task involving release readiness for a major version (e.g. "prepare for release", "verify the changelog", "write upgrade notes for v38", "we're releasing today"). Produces a finalized CHANGELOG entry, a detailed upgrade-notes document with before/after code examples, and updates all doc indexes.

Pre-commit documentation consistency check. Ensures docs/README.md index, docs/planning/docs-roadmap.md, and the MCP server's document registry (docs/doc-registry.json) stay in sync with documentation files on disk. Validates inter-doc links and enhances cross-references when new docs are added. Invoke after editing feature-area docs, before committing.

Cut a versioned production release of Toolbox - swap Hoist libraries from their working SNAPSHOTs to the latest official releases (hoist-core + @xh/hoist), finalize the CHANGELOG, commit on develop, ff-merge develop into master, trigger and watch the Build Release + Deploy Release GitHub Actions through to a successful prod deploy, then restore develop to its working-SNAPSHOT state. Use this skill whenever the developer wants to release Toolbox, cut a new Toolbox version, do a Toolbox prod release, ship a versioned build, or asks "let's release" / "release a new version" in this repo - even if they don't name every step. This is the authoritative runbook for the Toolbox release process; do not improvise the steps from memory.

Refresh the npm dependencies of @xh/hoist-dev-utils — bumping package.json semver specs, revving yarn.lock, and documenting the changes in CHANGELOG.md following project convention. Use this whenever the user wants to update, refresh, upgrade, or bump dependencies / libraries in this repo, run `yarn upgrade`, pull in newer minor/major versions, or prepare a batch of dependency updates ahead of a release — even if they don't name this skill explicitly. This is a recurring maintenance task; reach for the skill rather than improvising the steps.