chore: Update skills with the new skill-creator version (#561)

Author: patricklafrance

.claude/hooks/pre-commit.sh

@@ -12,6 +12,12 @@ if ! echo "$INPUT" | grep -q 'git commit'; then
     exit 0
 fi
 
+# Skip lint in CI environments where pnpm may not be installed (e.g., claude-code-action).
+if ! command -v pnpm &>/dev/null; then
+    echo "pnpm not found — skipping lint (CI environment)"
+    exit 0
+fi
+
 echo "--- pnpm lint ---"
 if ! pnpm lint; then
     echo "Lint failed. Fix errors before committing." >&2

.github/prompts/sync-agent-skill.md

@@ -15,7 +15,7 @@ When updating the skill:
 - Do NOT create or modify any files outside `agent-skills/workleap-squide/`.
 - Do NOT use TodoWrite, TaskCreate, or any task tracking tools.
 - Never update a versioned skill. You can identify a versioned skill with its folder name pattern, e.g. `workleap-squide-v*`.
-- Never change skill content unless you can point to a specific line in `./docs` that contradicts the current skill text. If you cannot identify the exact discrepancy, do not touch the content.
+- Never change skill content unless you can point to a specific line in `./docs` that either contradicts the current skill text or documents an API/pattern the skill is missing. If you cannot identify the exact discrepancy or omission, do not touch the content.
 - The SKILL.md body must stay under ~250 lines. New API content goes in the appropriate `references/` file, not in the body. Only add to the body if the content is a critical multi-file pattern that agents need in nearly every conversation.
 
 ## Excluded docs
@@ -165,4 +165,30 @@ The following issues could not be resolved after 3 retries:
 <List the failed coverage questions and/or accuracy discrepancies>"
 ```
 
-Then STOP. You are done.
+## If you cannot complete the workflow
+
+If anything prevents you from completing the steps above — hook failures, permission errors, tool errors, validation loops that exhaust retries, or any other unrecoverable problem — do NOT stop silently. Create a GitHub issue so the team knows the sync failed and what was lost:
+
+```bash
+gh issue create \
+  --title "Sync agent skill: workflow failed to complete" \
+  --label "bug" \
+  --body "## Problem
+
+The sync-agent-skill workflow could not complete successfully.
+
+## What failed
+
+<Describe the step that failed and the exact error message>
+
+## Work completed before failure
+
+<List any skill files you modified and a brief summary of each change, or 'None' if failure occurred before any changes>
+
+## Next steps
+
+1. Check the workflow run logs for details
+2. Fix the blocker and re-run the workflow, or apply the changes manually"
+```
+
+Then STOP.

.github/prompts/update-agent-docs.md

@@ -159,4 +159,30 @@ The PR body must follow this structure:
 
 If there are no staged changes after `git add`, output "No agent-docs update needed." and STOP.
 
-Then STOP. You are done.
+## If you cannot complete the workflow
+
+If anything prevents you from completing the steps above — hook failures, permission errors, tool errors, validation loops, or any other unrecoverable problem — do NOT stop silently. Create a GitHub issue so the team knows the update failed and what was lost:
+
+```bash
+gh issue create \
+  --title "Update agent docs: workflow failed to complete" \
+  --label "bug" \
+  --body "## Problem
+
+The update-agent-docs workflow could not complete successfully.
+
+## What failed
+
+<Describe the step that failed and the exact error message>
+
+## Work completed before failure
+
+<List any files you modified and a brief summary of each change, or 'None' if failure occurred before any changes>
+
+## Next steps
+
+1. Check the workflow run logs for details
+2. Fix the blocker and re-run the workflow, or apply the changes manually"
+```
+
+Then STOP.

.github/workflows/sync-agent-skill.yml

@@ -56,7 +56,21 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Install Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: ">=24.0.0"
+          check-latest: true
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
       - name: Sync agent skill with docs
+        id: claude
         uses: anthropics/claude-code-action@v1
         with:
           prompt: |

.github/workflows/update-agent-docs.yml

@@ -80,13 +80,21 @@ jobs:
           # Need 2 commits so the agent can diff against HEAD~1.
           fetch-depth: 2
 
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
       - name: Install Node.js
         uses: actions/setup-node@v6
         with:
           node-version: ">=24.0.0"
           check-latest: true
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
 
       - name: Update agent documentation
+        id: claude
         uses: anthropics/claude-code-action@v1
         with:
           prompt: |

agent-skills/workleap-squide/SKILL.md

@@ -11,7 +11,7 @@ description: |
   (7) Squide hooks for event bus, environment variables, feature flags, logging, or bootstrapping state
   (8) Error boundaries or modular architecture in Squide applications
 metadata:
-  version: 1.5
+  version: 1.6
 ---
 
 # Squide Framework
@@ -20,23 +20,12 @@ Squide is a React modular application shell. Use only documented APIs.
 
 ## Core Concepts
 
-### Runtime
-The `FireflyRuntime` instance is the backbone of a Squide application. Never instantiate directly - use `initializeFirefly()`.
+- **Runtime**: The `FireflyRuntime` instance is the backbone of a Squide application. Never instantiate directly — use `initializeFirefly()`, which wires up plugins, logging, and the module lifecycle.
+- **Modular Registration**: Modules register routes, navigation items, and MSW handlers via a registration function, assembled by the host at bootstrapping.
+- **Public vs Protected Routes**: Routes default to `protected` (rendered under `ProtectedRoutes`). Use `registerPublicRoute()` for public routes. Protected routes fetch both public and protected global data.
+- **Deferred Registrations**: Navigation items dependent on remote data or feature flags use two-phase registration — return a function from the registration to defer items to a second phase.
 
-### Modular Registration
-Modules register routes, navigation items, and MSW handlers via a registration function. Each module contributes its own configuration, assembled by the host at bootstrapping.
-
-### Public vs Protected Routes
-- Routes default to `protected` (rendered under `ProtectedRoutes` placeholder)
-- Use `registerPublicRoute()` for public routes (rendered under `PublicRoutes` placeholder)
-- Public routes only fetch public global data; protected routes fetch both public and protected data
-
-### Deferred Registrations
-Navigation items dependent on remote data or feature flags use two-phase registration:
-1. First phase: Register static routes and navigation items
-2. Second phase: Return a function from registration to defer navigation items
-
-## Quick Reference
+## Key Patterns
 
 ### Host Application Setup
 
@@ -80,15 +69,15 @@ function BootstrappingRoute() {
 export function App() {
     return (
         <AppRouter>
-            {({ rootRoute, registeredRoutes, routerProviderProps }) => (
+            {({ rootRoute, registeredRoutes, routerProps, routerProviderProps }) => (
                 <RouterProvider
                     router={createBrowserRouter([{
                         element: rootRoute,
                         children: [{
                             element: <BootstrappingRoute />,
                             children: registeredRoutes
                         }]
-                    }])}
+                    }], routerProps)}
                     {...routerProviderProps}
                 />
             )}
@@ -108,6 +97,7 @@ export const registerHost: ModuleRegisterFunction<FireflyRuntime> = runtime => {
         children: [PublicRoutes, ProtectedRoutes]
     }, { hoist: true });
 
+    // HomePage and NotFoundPage are local page components
     runtime.registerRoute({ index: true, element: <HomePage /> });
     runtime.registerPublicRoute({ path: "*", element: <NotFoundPage /> });
 };
@@ -158,6 +148,7 @@ export function RootLayout() {
 // Protected data
 import { useProtectedDataQueries, useIsBootstrapping, AppRouter } from "@squide/firefly";
 
+// ApiError and isApiError are app-specific; define them to match your API's error shape
 function BootstrappingRoute() {
     const [session] = useProtectedDataQueries([{
         queryKey: ["/api/session"],
@@ -208,11 +199,14 @@ export const register: ModuleRegisterFunction<FireflyRuntime, unknown, DeferredR
 ```
 
 ```tsx
-// Execute deferred registrations in BootstrappingRoute
+// Execute deferred registrations in BootstrappingRoute.
+// Wrap in useMemo — without it, a new object reference each render re-triggers all deferred registrations.
 const data = useMemo(() => ({ userData }), [userData]);
 useDeferredRegistrations(data);
 ```
 
+**See also:** For error boundaries, testing patterns, and advanced navigation (multi-level, dynamic segments, active state), see `references/patterns.md`. For MSW setup, LaunchDarkly, Honeycomb, i18next, and Storybook integrations, see `references/integrations.md`. For plugin authoring and the full runtime API, see `references/runtime-api.md`.
+
 ## Reference Guide
 
 For detailed API documentation beyond the patterns above, consult the reference files:
@@ -223,11 +217,11 @@ For detailed API documentation beyond the patterns above, consult the reference
 - **`references/patterns.md`** — Local module setup, error boundaries, MSW request handlers, and other common patterns
 - **`references/integrations.md`** — LaunchDarkly (plugin, utilities, testing clients), Honeycomb, i18next, and Storybook integration details
 
-## Skill Maintenance Notes
+## Common Pitfalls
 
-Before updating this skill, read [ODR-0008](../../agent-docs/odr/0008-skill-body-reference-split.md) which explains the body/reference split. The SKILL.md body must stay under ~250 lines. New API content goes in the appropriate `references/` file — only add to the body if it is a critical multi-file pattern needed in nearly every conversation.
+> **Skill maintainers:** Before updating this skill, read [ODR-0008](../../agent-docs/odr/0008-skill-body-reference-split.md). The body must stay under ~250 lines; new API content goes in the appropriate `references/` file.
 
-When updating this skill from the official documentation, verify these common pitfalls:
+When working with Squide APIs, watch for these common mistakes:
 
 1. **`useRenderedNavigationItems` function signatures**: Must always be `(item, key, index, level)` and `(elements, key, index, level)`. These do NOT accept custom context parameters. If external values are needed (route params, location, etc.), use closures or React hooks - never suggest adding parameters to these functions.
 

agent-skills/workleap-squide/references/components.md

@@ -1,5 +1,14 @@
 # Squide Components Reference
 
+## Table of Contents
+- [AppRouter](#approuter)
+- [FireflyProvider](#fireflyprovider)
+- [PublicRoutes](#publicroutes)
+- [ProtectedRoutes](#protectedroutes)
+- [I18nextNavigationItemLabel](#i18nextnavigationitemlabel-from-squidei18next)
+- [Storybook Components](#storybook-components-from-squidefirefly-rsbuild-storybook)
+- [Helper Functions](#helper-functions)
+
 ## AppRouter
 
 The main router component that sets up Squide's primitives with React Router.
@@ -16,9 +25,10 @@ The main router component that sets up Squide's primitives with React Router.
 
 ```ts
 {
-    rootRoute: ReactElement;      // Root route element (must wrap registeredRoutes)
-    registeredRoutes: Route[];    // All registered routes
-    routerProviderProps: object;  // Props for RouterProvider
+    rootRoute: ReactElement;           // Root route element (must wrap registeredRoutes)
+    registeredRoutes: Route[];         // All registered routes
+    routerProps: DOMRouterOpts;        // Options for createBrowserRouter (e.g., dataStrategy for MSW)
+    routerProviderProps: object;       // Props for RouterProvider
 }
 ```
 
@@ -32,12 +42,12 @@ import { RouterProvider } from "react-router/dom";
 export function App() {
     return (
         <AppRouter>
-            {({ rootRoute, registeredRoutes, routerProviderProps }) => (
+            {({ rootRoute, registeredRoutes, routerProps, routerProviderProps }) => (
                 <RouterProvider
                     router={createBrowserRouter([{
                         element: rootRoute,
                         children: registeredRoutes
-                    }])}
+                    }], routerProps)}
                     {...routerProviderProps}
                 />
             )}
@@ -59,15 +69,15 @@ function BootstrappingRoute() {
 export function App() {
     return (
         <AppRouter>
-            {({ rootRoute, registeredRoutes, routerProviderProps }) => (
+            {({ rootRoute, registeredRoutes, routerProps, routerProviderProps }) => (
                 <RouterProvider
                     router={createBrowserRouter([{
                         element: rootRoute,
                         children: [{
                             element: <BootstrappingRoute />,
                             children: registeredRoutes
                         }]
-                    }])}
+                    }], routerProps)}
                     {...routerProviderProps}
                 />
             )}
@@ -96,15 +106,15 @@ function BootstrappingRoute() {
 export function App() {
     return (
         <AppRouter waitForProtectedData>
-            {({ rootRoute, registeredRoutes, routerProviderProps }) => (
+            {({ rootRoute, registeredRoutes, routerProps, routerProviderProps }) => (
                 <RouterProvider
                     router={createBrowserRouter([{
                         element: rootRoute,
                         children: [{
                             element: <BootstrappingRoute />,
                             children: registeredRoutes
                         }]
-                    }])}
+                    }], routerProps)}
                     {...routerProviderProps}
                 />
             )}
@@ -354,3 +364,27 @@ const runtime = await initializeFireflyForStorybook({
     useMsw: true  // Default is true
 });
 ```
+
+### mergeDeferredRegistrations
+
+Merge multiple deferred registration functions into a single function. Useful when a module's registration function is split across multiple files or needs to combine results from several setup steps.
+
+```tsx
+import { mergeDeferredRegistrations } from "@squide/firefly";
+
+export const register: ModuleRegisterFunction<FireflyRuntime> = runtime => {
+    runtime.registerRoute({ path: "/page-a", element: <PageA /> });
+    runtime.registerRoute({ path: "/page-b", element: <PageB /> });
+
+    // Merge multiple deferred registration functions into one
+    return mergeDeferredRegistrations([
+        registerPageANavigation(runtime),
+        registerPageBNavigation(runtime)
+    ]);
+};
+```
+
+**Parameters:**
+- `candidates`: Array of deferred registration functions (or `void`). Non-function entries are filtered out.
+
+**Returns:** A single merged `DeferredRegistrationFunction`, or `undefined` if no valid functions were provided.

agent-skills/workleap-squide/references/hooks-api.md

@@ -1,5 +1,16 @@
 # Squide Hooks API Reference
 
+## Table of Contents
+- [Routing Hooks](#routing-hooks) — useNavigationItems, useRenderedNavigationItems, useRoutes, useIsBootstrapping, useIsRouteProtected, useRouteMatch
+- [Data Fetching Hooks](#data-fetching-hooks) — usePublicDataQueries, useProtectedDataQueries, usePublicDataHandler, useProtectedDataHandler
+- [Registration Hooks](#registration-hooks) — useDeferredRegistrations
+- [Messaging Hooks](#messaging-hooks) — useEventBusListener, useEventBusDispatcher
+- [Environment & Configuration Hooks](#environment--configuration-hooks) — useEnvironmentVariable, useEnvironmentVariables, useFeatureFlag, useFeatureFlags, useLaunchDarklyClient
+- [Logging Hooks](#logging-hooks) — useLogger
+- [Runtime Hooks](#runtime-hooks) — useRuntime, useRuntimeMode
+- [Plugin Hooks](#plugin-hooks) — usePlugin
+- [i18next Hooks](#i18next-hooks-from-squidei18next) — useI18nextInstance, useCurrentLanguage, useChangeLanguage
+
 ## Routing Hooks
 
 ### useNavigationItems(options?)

agent-skills/workleap-squide/references/integrations.md

@@ -118,6 +118,8 @@ export const requestHandlers: HttpHandler[] = [
 ];
 ```
 
+> For more module registration patterns including higher-order registration and deferred registration with MSW, see `references/patterns.md`.
+
 ## LaunchDarkly
 
 ### Initialize Client
@@ -447,6 +449,8 @@ runtime.registerNavigationItem({
 
 ## Storybook
 
+> For component API signatures (`FireflyDecorator`, `withFireflyDecorator`, `withFeatureFlagsOverrideDecorator`, `initializeFireflyForStorybook`), see `references/components.md`.
+
 ### Setup Decorator
 
 ```tsx