@gears-frontx/react 0.1.0 → 0.2.0-alpha.0

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # @gears-frontx/react
 
-React bindings and hooks for HAI3 applications. Provides the React integration layer with MFE (Microfrontend) support.
+React bindings and hooks for FrontX applications. Provides the React integration layer with MFE (Microfrontend) support.
 
 ## React Layer
 
@@ -8,44 +8,146 @@ This package is part of the **React Layer (L3)** - it depends only on @gears-fro
 
 ## Core Concepts
 
-### HAI3Provider
+### Gears FrontXProvider
 
-Wrap your app with HAI3Provider to enable all hooks:
+Wrap your app with Gears FrontXProvider to enable all hooks:
 
 ```tsx
-import { HAI3Provider } from '@gears-frontx/react';
+import { Gears FrontXProvider } from '@gears-frontx/react';
 
 function App() {
   return (
-    <HAI3Provider>
+    <Gears FrontXProvider>
       <YourApp />
-    </HAI3Provider>
+    </Gears FrontXProvider>
   );
 }
 
 // With configuration
-<HAI3Provider config={{ devMode: true }}>
+<Gears FrontXProvider config={{ devMode: true }}>
   <YourApp />
-</HAI3Provider>
+</Gears FrontXProvider>
 
-// With pre-built app
-const app = createHAI3().use(screensets()).build();
-<HAI3Provider app={app}>
+// With pre-built app (host-style shell; host typically also uses queryCache() — see REACT.md)
+const app = createGears FrontX().use(screensets()).build();
+<Gears FrontXProvider app={app}>
   <YourApp />
-</HAI3Provider>
+</Gears FrontXProvider>
+
+// Child MFE app — canonical bootstrap matches src/mfe_packages/*/init.ts and .ai/targets/SCREENSETS.md:
+// apiRegistry.register / initialize before .build; createGears FrontX().use(effects()).use(queryCacheShared()).use(mock()).build();
+// registerSlice after .build when slices exist.
+const mfeApp = createGears FrontX().use(effects()).use(queryCacheShared()).use(mock()).build();
+<Gears FrontXProvider app={mfeApp}>
+  <YourApp />
+</Gears FrontXProvider>
+```
+
+The shared `QueryClient` is created and owned by the `queryCache()` framework plugin at L2.
+`Gears FrontXProvider` resolves that client from the app instance — it does not create its own `QueryClient`.
+
+When the host uses `queryCache()` and the child MFE app uses `queryCacheShared()` (with `effects()` and `mock()` on the same chain as in repo MFE inits), both roots join the same shared `QueryClient` while keeping separate React trees. `ThemeAwareReactLifecycle` relies on that shared plugin-owned client through the app instance. If the shared client is missing for a mounted MFE, the lifecycle now fails explicitly instead of silently falling back.
+
+For separate roots, build each app with the appropriate query-cache plugin (`queryCache()` for the host, `queryCacheShared()` for child MFE shells) so every tree joins the same cache through plugin composition. MFE package ordering and forbidden bootstrap pieces are defined in SCREENSETS.md. Host apps should register domains/extensions during bootstrap; **`ExtensionDomainSlot`** is the preferred host-side renderer for screen slots while the framework wires `mount_ext`.
+
+### Data Fetching with Endpoint Descriptors
+
+Services define endpoints as descriptors. Components consume them via `useApiQuery` and `useApiMutation`. No manual query keys, no `queryOptions()` calls.
+
+```tsx
+import { useApiQuery, useApiMutation, apiRegistry } from '@gears-frontx/react';
+import { AccountsApiService } from '../api/AccountsApiService';
+
+function ProfileScreen() {
+  const service = apiRegistry.getService(AccountsApiService);
+
+  // Read — pass descriptor directly
+  const { data, isLoading, error } = useApiQuery(service.getCurrentUser);
+
+  // Read with params
+  const { data: user } = useApiQuery(service.getUser({ id: '123' }));
+
+  // Write with optimistic update
+  const { mutateAsync, isPending } = useApiMutation({
+    endpoint: service.updateProfile,
+    onMutate: async (variables, { queryCache }) => {
+      await queryCache.cancel(service.getCurrentUser);
+      const snapshot = queryCache.get(service.getCurrentUser);
+      queryCache.set(service.getCurrentUser, (old) => ({
+        ...old, user: { ...old.user, ...variables }
+      }));
+      return { snapshot };
+    },
+    onError: (_err, _vars, context, { queryCache }) => {
+      if (context?.snapshot) {
+        queryCache.set(service.getCurrentUser, context.snapshot);
+      }
+    },
+    onSettled: async (_data, _err, _vars, _ctx, { queryCache }) => {
+      await queryCache.invalidate(service.getCurrentUser);
+    },
+  });
+
+  // Per-endpoint cache override (rare)
+  const { data: config } = useApiQuery(service.getConfig, { staleTime: 0 });
+}
+```
+
+Cache keys are derived automatically by the service — `QueryCache` methods accept
+endpoint descriptors directly (e.g., `queryCache.get(service.getCurrentUser)`).
+
+### SSE Streaming with Stream Descriptors
+
+Services declare SSE endpoints as stream descriptors. Components consume them via `useApiStream`, which manages the EventSource lifecycle automatically (connect on mount, disconnect on unmount).
+
+```tsx
+import { useApiStream, apiRegistry } from '@gears-frontx/react';
+import { ChatApiService } from '../api/ChatApiService';
+
+function ChatStream() {
+  const service = apiRegistry.getService(ChatApiService);
+
+  // Latest event only (default mode)
+  const { data, status, error } = useApiStream(service.messageStream);
+
+  // Accumulate all events
+  const { events, status: streamStatus } = useApiStream(
+    service.messageStream,
+    { mode: 'accumulate' }
+  );
+
+  // Deferred connection (enabled: false)
+  const [active, setActive] = useState(false);
+  const { data: msg, disconnect } = useApiStream(
+    service.messageStream,
+    { enabled: active }
+  );
+
+  if (status === 'connecting') return <Loading />;
+  if (error) return <Error error={error} />;
+
+  return <div>{data?.text}</div>;
+}
 ```
 
+`useApiStream` returns `{ data, events, status, error, disconnect }`:
+- `data` — latest event payload (always set in both modes)
+- `events` — all received events when `mode: 'accumulate'`; empty array in `'latest'` mode
+- `status` — `'idle' | 'connecting' | 'connected' | 'disconnected' | 'error'`
+- `error` — connection error if any
+- `disconnect()` — manually close the connection
+
 ### Available Hooks
 
-#### useHAI3
+#### useFrontX
 
-Access the HAI3 app instance:
+Access the FrontX app instance:
 
 ```tsx
-import { useHAI3 } from '@gears-frontx/react';
+import { useFrontX } from '@gears-frontx/react';
 
 function MyComponent() {
-  const app = useHAI3();
+  const app = useFrontX();
 
   // Access MFE-enabled registry
   const extensions = app.screensetsRegistry.getRegisteredExtensions();
@@ -138,18 +240,18 @@ Access the MFE bridge for child MFEs:
 
 ```tsx
 import { useMfeBridge } from '@gears-frontx/react';
-import { HAI3_ACTION_LOAD_EXT, HAI3_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
+import { Gears FrontX_ACTION_LOAD_EXT, Gears FrontX_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
 
 function MyExtension() {
   const bridge = useMfeBridge();
 
   // Execute actions chain on parent
   await bridge.executeActionsChain({
-    action: { type: HAI3_ACTION_LOAD_EXT, target: 'screen', payload: { extensionId: 'other' } }
+    action: { type: Gears FrontX_ACTION_LOAD_EXT, target: 'screen', payload: { extensionId: 'other' } }
   });
 
   // Get shared property
-  const theme = bridge.getProperty(HAI3_SHARED_PROPERTY_THEME);
+  const theme = bridge.getProperty(Gears FrontX_SHARED_PROPERTY_THEME);
 }
 ```
 
@@ -158,10 +260,10 @@ function MyExtension() {
 Subscribe to shared property changes:
 
 ```tsx
-import { useSharedProperty, HAI3_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
+import { useSharedProperty, Gears FrontX_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
 
 function ThemedComponent() {
-  const theme = useSharedProperty(HAI3_SHARED_PROPERTY_THEME);
+  const theme = useSharedProperty(Gears FrontX_SHARED_PROPERTY_THEME);
 
   return <div style={{ backgroundColor: theme?.primaryColor }}>...</div>;
 }
@@ -172,10 +274,10 @@ function ThemedComponent() {
 Invoke actions on the host application:
 
 ```tsx
-import { useHostAction, HAI3_ACTION_LOAD_EXT } from '@gears-frontx/react';
+import { useHostAction, Gears FrontX_ACTION_LOAD_EXT } from '@gears-frontx/react';
 
 function MyExtension() {
-  const loadExtension = useHostAction(HAI3_ACTION_LOAD_EXT);
+  const loadExtension = useHostAction(Gears FrontX_ACTION_LOAD_EXT);
 
   const handleClick = () => {
     loadExtension({ extensionId: 'other' });
@@ -254,7 +356,7 @@ import { MfeProvider } from '@gears-frontx/react';
 
 function MfeHost() {
   return (
-    <MfeProvider bridge={parentBridge}>
+    <MfeProvider value={{ bridge: parentBridge, extensionId: 'home', domainId: 'screen' }}>
       <ExtensionContainer />
     </MfeProvider>
   );
@@ -270,17 +372,27 @@ import { ExtensionDomainSlot } from '@gears-frontx/react';
 
 function LayoutScreen() {
   return (
-    <div>
-      <ExtensionDomainSlot
-        domainId="screen"
-        containerRef={screenContainerRef}
-        fallback={<Loading />}
-      />
-    </div>
+    <ExtensionDomainSlot
+      registry={registry}
+      domainId="screen"
+      extensionId="home"
+      loadingComponent={<Loading />}
+    />
   );
 }
 ```
 
+`ExtensionDomainSlot` is the preferred host-side renderer for screen MFEs. It
+owns mount/unmount and loading/error UI while host bootstrap handles domain
+registration and shared property setup before slot-driven `mount_ext`.
+The host `QueryClient` is reused by MFE React trees through
+`queryCacheShared()`, not by embedding a `QueryClient` on `MfeMountContext`
+or expecting host React context inside Shadow DOM.
+
+When the domain's `ContainerProvider` must point at the same DOM node rendered
+by the slot, pass `containerRef` to `ExtensionDomainSlot` and share that ref
+with `RefContainerProvider`.
+
 #### RefContainerProvider
 
 Provide container references for MFE mounting:
@@ -302,11 +414,14 @@ function Layout() {
 
 ## Key Rules
 
-1. **Wrap with HAI3Provider** - Required for all hooks to work
+1. **Wrap with Gears FrontXProvider** - Required for all hooks to work
 2. **Use hooks for state access** - Don't import selectors directly from @gears-frontx/framework
-3. **Lazy load translations** - Use `useScreenTranslations` for screen-level i18n
-4. **Use MFE hooks for extensions** - `useMfeBridge`, `useSharedProperty`, `useHostAction`, `useDomainExtensions`
-5. **NO Layout components here** - Layout and UI components belong in L4 (user's project via CLI scaffolding)
+3. **Use endpoint descriptors for data** - `useApiQuery(service.endpoint)` for REST, `useApiStream(service.stream)` for SSE — not `queryOptions()` or manual key factories
+4. **Service is the cache contract** - The service IS the data layer; cache keys are derived automatically
+5. **QueryCache uses descriptors** - `queryCache.get(service.endpoint)`, not raw key arrays
+6. **Lazy load translations** - Use `useScreenTranslations` for screen-level i18n
+7. **Use MFE hooks for extensions** - `useMfeBridge`, `useSharedProperty`, `useHostAction`, `useDomainExtensions`
+8. **NO Layout components here** - Layout and UI components belong in L4 (user's project via CLI scaffolding)
 
 ## Re-exports
 
@@ -323,15 +438,19 @@ This allows users to import everything from `@gears-frontx/react` without needin
 ## Exports
 
 ### Components
-- `HAI3Provider` - Main context provider
+- `Gears FrontXProvider` - Main context provider
 - `MfeProvider` - MFE context provider
 - `ExtensionDomainSlot` - Domain slot renderer
 - `RefContainerProvider` - Container reference provider
 
 ### Hooks
-- `useHAI3` - Access app instance
+- `useFrontX` - Access app instance
 - `useAppDispatch` - Typed dispatch
 - `useAppSelector` - Typed selector
+- `useApiQuery` - Declarative data fetch from endpoint descriptor; returns `ApiQueryResult<TData>`
+- `useApiMutation` - Declarative mutation with endpoint descriptor and optimistic update support; returns `ApiMutationResult<TData>`
+- `useApiStream` - Declarative SSE streaming from stream descriptor; returns `ApiStreamResult<TEvent>`
+- `useQueryCache` - Restricted query cache access (accepts descriptors or raw keys)
 - `useTranslation` - Translation utilities
 - `useScreenTranslations` - Screen translation loading
 - `useTheme` - Theme utilities
@@ -343,14 +462,20 @@ This allows users to import everything from `@gears-frontx/react` without needin
 - `useActivePackage` - Subscribe to active GTS package
 
 ### Context
-- `HAI3Context` - React context (for advanced use)
+- `Gears FrontXContext` - React context (for advanced use)
 - `MfeContext` - MFE context (for advanced use)
 
 ### Types
-- `HAI3ProviderProps`
+- `Gears FrontXProviderProps`
+- `ApiQueryResult<TData>` - Gears FrontX-owned query result type (data, error, isLoading, refetch, etc.)
+- `ApiMutationResult<TData>` - Gears FrontX-owned mutation result type (mutateAsync, isPending, error, reset, etc.)
+- `ApiStreamResult<TEvent>` - Gears FrontX-owned stream result type (data, events, status, error, disconnect)
+- `ApiStreamOptions` - Stream hook options (mode, enabled)
+- `QueryCache` - Restricted cache interface (accepts descriptors or raw keys)
+- `MutationCallbackContext` - Context with queryCache injected into mutation callbacks
 - `MfeProviderProps`, `ExtensionDomainSlotProps`
 - `UseTranslationReturn`, `UseThemeReturn`
-- All types from @gears-frontx/framework
+- All types from @gears-frontx/framework (including `EndpointDescriptor`, `MutationDescriptor`, `StreamDescriptor`, `StreamStatus`)
 
 ## Migration from Legacy API
 
@@ -378,10 +503,10 @@ function MyComponent() {
 
 **NEW**: Mount extension using app actions
 ```tsx
-import { useHAI3 } from '@gears-frontx/react';
+import { useFrontX } from '@gears-frontx/react';
 
 function MyComponent() {
-  const app = useHAI3();
+  const app = useFrontX();
   const containerRef = useRef<HTMLDivElement>(null);
 
   const handleNavigate = async () => {
@@ -403,16 +528,17 @@ function MyComponent() {
 }
 ```
 
-**NEW (Alternative)**: Use ExtensionDomainSlot
+**NEW (Preferred for host screen slots)**: Use ExtensionDomainSlot
 ```tsx
 import { ExtensionDomainSlot } from '@gears-frontx/react';
 
 function MyComponent() {
   return (
     <ExtensionDomainSlot
+      registry={app.screensetsRegistry}
       domainId="screen"
-      containerRef={screenContainerRef}
-      fallback={<Loading />}
+      extensionId="home"
+      loadingComponent={<Loading />}
     />
   );
 }

package/commands/{hai3-duplicate-screenset.md → frontx-duplicate-screenset.md}

@@ -1,5 +1,5 @@
 <!-- @standalone -->
-# hai3:duplicate-screenset - Duplicate Screenset
+# frontx:duplicate-screenset - Duplicate Screenset
 
 ## AI WORKFLOW (REQUIRED)
 1) Read .ai/targets/SCREENSETS.md before starting.
@@ -18,7 +18,7 @@ Ask user for:
 
 ## STEP 1: Copy Screenset via CLI
 ```bash
-hai3 screenset copy SOURCE TARGET --category={category}
+frontx screenset copy SOURCE TARGET --category={category}
 ```
 The CLI automatically:
 - Copies all files (screens, slices, actions, events, effects, API, icons, i18n).
@@ -50,7 +50,7 @@ STOP: If MCP connection is broken, fix it first. NEVER skip testing.
 
 ## CHECKLIST
 - [ ] Gather requirements (source, target name, category).
-- [ ] Run `hai3 screenset copy SOURCE TARGET --category={category}`.
+- [ ] Run `frontx screenset copy SOURCE TARGET --category={category}`.
 - [ ] Run type-check (MUST pass).
 - [ ] Run arch:check (MUST pass).
 - [ ] Run lint (MUST pass).

package/commands/{hai3-new-component.md → frontx-new-component.md}

@@ -1,10 +1,11 @@
 <!-- @standalone -->
-# hai3:new-component - Add New UI Component
+# frontx:new-component - Add New UI Component
 
 ## AI WORKFLOW (REQUIRED)
-1) Check for existing equivalent in project (e.g. components/ui/) and configured UI library first.
-2) Gather requirements from user.
-3) Implement.
+1) Read `.ai/project/GUIDELINES.md` and `.ai/project/targets/UNIT_TESTING.md` when they exist **before** any unit-test, validation, or testing steps in this command (project-owned overrides take precedence over defaults here).
+2) Check for existing equivalent in project (e.g. components/ui/) and configured UI library first.
+3) Gather requirements from user.
+4) Implement.
 
 ## CHECK EXISTING COMPONENTS FIRST
 - REQUIRED: Read `frontx.config.json` to find the `uikit` value.
@@ -38,11 +39,19 @@ File: src/components/ui/{ComponentName}.tsx (base primitives)
 Export from local index if needed.
 
 #### 1.3 Validation
-Run: npm run arch:check && npm run dev
+<!-- @cpt-begin:cpt-frontx-flow-unit-test-generation-and-agent-verification-agent-verify:p1:inst-agent-implement-and-test -->
+If creating a shared composite in `src/components/`, add or update a component test for its stable behavior.
+Run `npm run test:unit`, `npm run type-check`, `npm run arch:check`, and `npm run dev` (or the equivalent commands for this project's configured package manager) and apply any stricter triggers or conventions from `.ai/project/targets/UNIT_TESTING.md`. Apply constraints from workflow step 1.
+<!-- @cpt-end:cpt-frontx-flow-unit-test-generation-and-agent-verification-agent-verify:p1:inst-agent-implement-and-test -->
 Test component in UI.
 
+## TESTING
+- REQUIRED: Load `.ai/project/GUIDELINES.md` and `.ai/project/targets/UNIT_TESTING.md` when they exist **before** interpreting unit-test requirements elsewhere in this command.
+- REQUIRED: Follow `.ai/project/targets/UNIT_TESTING.md` for `__test-utils__/` placement and durable, non-placeholder assertions when adding or updating tests.
+
 ## RULES
 - REQUIRED: Check existing project UI components first; create new only if missing.
 - FORBIDDEN: Redux, business logic, side effects in components.
 - FORBIDDEN: Inline styles outside components/ui/.
 - REQUIRED: Accept value/onChange pattern for state.
+- REQUIRED: New shared composite components in `src/components/` include a colocated or nearby unit test when the behavior is stable.

package/commands/{hai3-new-mfe.md → frontx-new-mfe.md}

@@ -1,10 +1,10 @@
 <!-- @standalone -->
-# hai3:new-mfe - Create New Microfrontend Package
+# frontx:new-mfe - Create New Microfrontend Package
 
 ## PREREQUISITES (CRITICAL - STOP IF FAILED)
 
 1. MFE must be associated with a screenset
-2. Screenset must exist (run `hai3-new-screenset` first if needed)
+2. Screenset must exist (run `frontx-new-screenset` first if needed)
 3. Vite and Module Federation must be configured
 
 ## QUICK START
@@ -61,30 +61,17 @@ Create `src/lifecycle.tsx`:
 ```typescript
 import React from 'react';
 import type { ChildMfeBridge } from '@gears-frontx/react';
-import { ThemeAwareReactLifecycle } from '@gears-frontx/screensets/mfe/handler';
+import { ThemeAwareReactLifecycle } from '@gears-frontx/react';
+import { mfeApp } from './init';
 import { YourScreen } from './screens/YourScreen';
 
 class Lifecycle extends ThemeAwareReactLifecycle {
   constructor() {
-    super({
-      name: '{screensetName}',
-      version: '1.0.0',
-    });
+    super(mfeApp);
   }
 
-  async mount(shadowRoot: ShadowRoot, bridge: ChildMfeBridge) {
-    const div = document.createElement('div');
-    shadowRoot.appendChild(div);
-
-    const style = document.createElement('style');
-    style.textContent = tailwindStyles;
-    shadowRoot.appendChild(style);
-
-    // Render component
-    const root = ReactDOM.createRoot(div);
-    root.render(<YourScreen bridge={bridge} />);
-
-    return { root, div };
+  protected renderContent(bridge: ChildMfeBridge): React.ReactNode {
+    return <YourScreen bridge={bridge} />;
   }
 }
 
@@ -163,4 +150,4 @@ npm run dev:all
 
 See also:
 - `/packages/cli/template-sources/mfe-package/` for templates
-- `hai3-new-screenset.md` for screenset creation
+- `frontx-new-screenset.md` for screenset creation

package/commands/{hai3-new-screen.md → frontx-new-screen.md}

@@ -1,10 +1,11 @@
 <!-- @standalone -->
-# hai3:new-screen - Add New Screen
+# frontx:new-screen - Add New Screen
 
 ## AI WORKFLOW (REQUIRED)
 1) Read .ai/targets/SCREENSETS.md and .ai/targets/EVENTS.md before starting.
-2) Gather requirements from user (including UI sections).
-3) Implement.
+2) Read `.ai/project/GUIDELINES.md` and `.ai/project/targets/UNIT_TESTING.md` when they exist **before** planning unit tests, validation, or any test-related tasks in this command (project-owned overrides take precedence over defaults here).
+3) Gather requirements from user (including UI sections).
+4) Implement.
 
 ## GATHER REQUIREMENTS
 Ask user for:
@@ -20,15 +21,20 @@ Ask user for:
    - Use actions to trigger state changes
    - FORBIDDEN: Direct slice dispatch from screen
 4) Add i18n with useScreenTranslations(). Export default.
-5) Add to menu if requested.
-6) Validate: `npm run type-check && npm run lint`.
-7) Test via Chrome DevTools MCP (REQUIRED):
+5) Add or update a screen test that covers stable render or behavior for the new screen and place any test-only helpers in a sibling `__test-utils__/` folder.
+6) Add to menu if requested.
+7) Validate: run `test:unit`, `type-check`, and `arch:check` via this project's package manager per `.ai/project/targets/UNIT_TESTING.md` (which defines the exact commands). Apply constraints from workflow step 2.
+8) Test via Chrome DevTools MCP (REQUIRED):
    - Navigate to new screen
    - Verify screen renders without console errors
    - Test UI interactions and data flow
    - Verify translations load correctly
    - STOP if MCP connection fails
 
+## TESTING
+- REQUIRED: Load `.ai/project/GUIDELINES.md` and `.ai/project/targets/UNIT_TESTING.md` when they exist **before** interpreting unit-test requirements elsewhere in this command.
+- REQUIRED: Use neutral fixtures, translation mocks, and stable keys, roles, or IDs instead of placeholder-derived copy when adding or updating generated screen tests.
+
 ## COMPONENT PLAN
 - REQUIRED: Use local components (e.g. `components/ui/`) — no shared UI kit package.
 - components/ui/: base UI primitives (shadcn components or custom)

package/commands/frontx-new-screenset.md

@@ -0,0 +1,57 @@
+<!-- @standalone -->
+# frontx:new-screenset - Create New Screenset
+
+## PREREQUISITES (CRITICAL - STOP IF FAILED)
+Run `frontx --version`.
+STOP: If fails, tell user to install.
+FORBIDDEN: Creating screenset manually or by copying peers.
+
+## AI WORKFLOW (REQUIRED)
+1) Check prerequisites above.
+2) Read .ai/targets/SCREENSETS.md and .ai/targets/EVENTS.md before starting.
+3) Read `.ai/project/GUIDELINES.md` and `.ai/project/targets/UNIT_TESTING.md` when they exist **before** planning unit tests, validation, or any test-related tasks in this command (project-owned overrides take precedence over defaults here).
+4) Gather requirements from user (including UI sections).
+5) Implement.
+
+## GATHER REQUIREMENTS
+Ask user for:
+- Screenset name (camelCase).
+- Category: Drafts | Mockups | Production.
+- Initial screens.
+- UI sections per screen (e.g., "stats cards, charts, activity feed").
+
+## STEP 1: Implementation
+1) Create screenset via `frontx screenset create` (REQUIRED).
+2) Create components BEFORE screen file per Component Plan.
+3) Implement data flow per .ai/targets/EVENTS.md:
+   - Actions emit events via eventBus.emit()
+   - Effects subscribe and update slices
+   - FORBIDDEN: Direct slice dispatch from components
+4) Add API service with mocks and endpoint descriptors:
+   - Read endpoints: `readonly prop = this.protocol(RestEndpointProtocol).query<T>('/path')`
+   - Write endpoints: `readonly prop = this.protocol(RestEndpointProtocol).mutation<T, V>('PUT', '/path')`
+   - NO queryOptions, NO manual query key factories outside the service
+   - Screens use `useApiQuery(service.prop)` and `useApiMutation({ endpoint: service.prop })`
+5) Add or update starter unit tests for stable generated behavior.
+6) Validate: run `test:unit`, `type-check`, `arch:check`, and `lint` via this project's package manager per `.ai/project/targets/UNIT_TESTING.md` (which defines the exact commands). Apply constraints from workflow step 3.
+7) Test via Chrome DevTools MCP (REQUIRED):
+   - Navigate to new screenset
+   - Verify screen renders without console errors
+   - Test user interactions trigger correct events
+   - Verify state updates via Redux DevTools
+   - STOP if MCP connection fails
+
+## COMPONENT PLAN
+- REQUIRED: Use local components (e.g. `components/ui/`) — no shared UI kit package.
+- components/ui/: base UI primitives (shadcn components or custom)
+- components/: multi-screen shared components
+- screens/{screen}/components/: screen-specific components
+
+## DATA FLOW
+- Events: {domain events per EVENTS.md}
+- State: slices/, events/, effects/, actions/
+- API: api/{Name}ApiService.ts with mocks and endpoint descriptors
+
+## TESTING
+- REQUIRED: Load `.ai/project/GUIDELINES.md` and `.ai/project/targets/UNIT_TESTING.md` when they exist **before** interpreting unit-test requirements elsewhere in this command.
+- REQUIRED: Preserve the generated API-contract test and `HomeScreen` smoke test unless the new behavior replaces that baseline intentionally.