@bluealba/platform-cli 1.2.0-alpha.0 → 1.2.0-alpha.2

package/dist/index.js

@@ -2439,7 +2439,7 @@ async function removePlatformAdmin(ruleId, logger) {
 var baPlatformPlugin = {
   name: "ba-platform-plugin",
   description: "Blue Alba Platform knowledge and CLI skills for AI assistants",
-  version: "1.0.0",
+  version: "1.1.0",
   skills: [
     {
       name: "platform",
@@ -2452,6 +2452,48 @@ var baPlatformPlugin = {
       description: "Blue Alba Platform CLI commands and usage knowledge",
       type: "skill",
       sourceFile: "skills/ba-platform/platform-cli.skill.md"
+    },
+    {
+      name: "platform-add-operation",
+      description: "Defines a new authorization operation in the bootstrap service, assigns it to a role, and adds access guards in the React UI or NestJS backend",
+      type: "skill",
+      sourceFile: "skills/ba-platform/platform-add-operation.skill.md"
+    },
+    {
+      name: "platform-add-feature-flag",
+      description: "Declares a feature flag in the bootstrap service and adds its usage in a React UI component or NestJS service",
+      type: "skill",
+      sourceFile: "skills/ba-platform/platform-add-feature-flag.skill.md"
+    },
+    {
+      name: "platform-add-scheduled-job",
+      description: "Adds a scheduled job to a Blue Alba Platform bootstrap service",
+      type: "skill",
+      sourceFile: "skills/ba-platform/platform-add-scheduled-job.skill.md"
+    },
+    {
+      name: "platform-add-menu-item",
+      description: "Adds a new page and menu item to a Blue Alba Platform single-spa UI module",
+      type: "skill",
+      sourceFile: "skills/ba-platform/platform-add-menu-item.skill.md"
+    },
+    {
+      name: "platform-extend-shell",
+      description: "Injects a custom component into a Blue Alba Platform shell extension point",
+      type: "skill",
+      sourceFile: "skills/ba-platform/platform-extend-shell.skill.md"
+    },
+    {
+      name: "platform-add-presence",
+      description: "Adds real-time user presence via the Rooms API to a Blue Alba Platform app",
+      type: "skill",
+      sourceFile: "skills/ba-platform/platform-add-presence.skill.md"
+    },
+    {
+      name: "platform-scaffold-module",
+      description: "Scaffolds a new UI module or service module using the platform CLI",
+      type: "skill",
+      sourceFile: "skills/ba-platform/platform-scaffold-module.skill.md"
     }
   ]
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluealba/platform-cli",
-  "version": "1.2.0-alpha.0",
+  "version": "1.2.0-alpha.2",
   "description": "Blue Alba Platform CLI",
   "license": "PolyForm-Noncommercial-1.0.0",
   "type": "module",

package/skills/ba-platform/platform-add-feature-flag.skill.md

@@ -0,0 +1,110 @@
+---
+name: platform-add-feature-flag
+description: Declares a feature flag in the bootstrap service and adds its usage in a React UI component or NestJS service. Use when the user wants to gate a feature behind a flag on a Blue Alba Platform app.
+---
+
+You are adding a feature flag to a Blue Alba Platform application. The project is a monorepo: UI modules live under `ui/`, services and bootstrap under `services/`.
+
+## Related Documentation
+
+Read `{{docsPath}}/guides/using-feature-flags.mdx` for the complete feature flags guide including architecture, targeting rules, and API endpoints.
+
+## Step 1 — Discover the bootstrap service
+
+Find `services/<app>-bootstrap-service/src/bootstrap/feature-flags.json`. Read it to understand existing flags.
+
+## Step 2 — Ask for flag details
+
+Ask the user:
+
+1. **Flag name** — kebab-case identifier (e.g. `new-checkout-flow`)
+2. **Description** — short human-readable description
+3. **Default value** — `true` or `false` (or a typed value if not boolean)
+4. **Targeting rules** — should this flag be enabled for specific tenants or users? If yes, get the tenant IDs or usernames.
+5. **Rollout percentage** — optional, e.g. 20% of users matching the rule
+6. **Where to use it** — which component, page, or service should read this flag?
+
+Wait for the user's answer before continuing.
+
+## Step 3 — Declare the flag in bootstrap
+
+Add the flag to `feature-flags.json` following this structure:
+
+```json
+{
+  "name": "<flag-name>",
+  "description": "<description>",
+  "visible": true,
+  "defaultValue": <defaultValue>,
+  "applicationName": "<app-name>",
+  "valueRules": []
+}
+```
+
+If targeting rules were specified, populate `valueRules`:
+
+```json
+{
+  "name": "<rule-name>",
+  "condition": {
+    "operator": "AND",
+    "rules": [
+      { "attribute": "tenant", "operator": "in", "value": ["<tenant-id>"] }
+    ]
+  },
+  "value": true,
+  "rollout": { "percentage": <n>, "attribute": "username" }
+}
+```
+
+Only add `rollout` if a percentage was given. Omit `valueRules` entirely if no rules.
+
+## Step 4 — Add usage in code
+
+**React component** (in `ui/`):
+
+If the flag controls whether a whole section is shown:
+```tsx
+import { FeatureFlagGuard } from '@bluealba/pae-ui-react-core';
+
+<FeatureFlagGuard flag="<flag-name>" fallback={<OldComponent />}>
+  <NewComponent />
+</FeatureFlagGuard>
+```
+
+If the flag value is needed in logic:
+```tsx
+import { useFeatureFlag } from '@bluealba/pae-ui-react-core';
+
+const enabled = useFeatureFlag('<flag-name>');
+```
+
+**NestJS service** (in `services/`):
+
+For a one-off check in a service method:
+```ts
+import { FeatureFlagsClientService } from '@bluealba/pae-service-nestjs-sdk';
+
+constructor(private flags: FeatureFlagsClientService) {}
+
+const enabled = this.flags.get<boolean>(req, '<flag-name>') ?? false;
+```
+
+For a controller endpoint:
+```ts
+import { FeatureFlags } from '@bluealba/pae-service-nestjs-sdk';
+
+@Get()
+async myEndpoint(@FeatureFlags('<flag-name>') enabled: boolean) { ... }
+```
+
+Also add `FeatureFlagsClientModule` to the module's `imports` array if it isn't already there.
+
+> **Note:** Feature flags are evaluated by the gateway and forwarded to downstream services via the `x-forwarded-feature-flags` base64-encoded header. The `@FeatureFlags()` decorator and `FeatureFlagsClientService` read from this header — they do not evaluate flags themselves.
+
+## Rules
+
+- Flag names must be kebab-case
+- `defaultValue` type must match how the flag is consumed (boolean, number, string)
+- Do not add flags to the wrong application — check `applicationName` matches the bootstrap service's application
+- Follow the existing code style in the target file exactly

package/skills/ba-platform/platform-add-menu-item.skill.md

@@ -0,0 +1,80 @@
+---
+name: platform-add-menu-item
+description: Adds a new page and menu item to a Blue Alba Platform single-spa UI module. Creates the route component and wires it into menu.ts. Use when the user wants to add a new page, route, or section to a platform app.
+---
+
+You are adding a new page and menu entry to a Blue Alba Platform single-spa UI application. The project is a monorepo where UI modules live under `ui/` and services under `services/`.
+
+## Related Documentation
+
+Read `{{docsPath}}/architecture/shell.mdx` for the shell layout, menu structure, and application menu contract.
+
+## Step 1 — Discover the UI module
+
+Look for the `ui/` directory in the current working directory. List its subdirectories to find the UI module(s). Read the `src/menu.ts` file from the relevant module to understand the existing menu structure.
+
+Also read `src/main.tsx` (or `src/index.tsx`) to understand the entry point and how routes are set up, and any router file (e.g. `src/App.tsx`, `src/router.tsx`, or files importing `react-router-dom`). Menu files are always `.ts` (not `.tsx`).
+
+## Step 2 — Ask for details
+
+Ask the user for the following. Suggest sensible defaults based on the existing code:
+
+1. **Label** — the menu item display name (e.g. "Invoice History")
+2. **Route** — the URL path (e.g. `/invoices`)
+3. **Icon** — icon name or component (look at existing menu items for the pattern)
+4. **Parent menu item** — should this be a top-level item or nested under an existing one?
+5. **Operation** — does this page require an authorization operation to be visible? (e.g. `billing::invoices::read`). Leave blank if no restriction needed.
+
+Wait for the user's answer before continuing.
+
+## Step 3 — Create the page component
+
+Create a new React component file under `src/components/` or `src/pages/` (follow the existing folder convention). Use a minimal functional component:
+
+```tsx
+import React from 'react';
+
+const <PageName>: React.FC = () => {
+  return (
+    <div>
+      <h1><PageName></h1>
+    </div>
+  );
+};
+
+export default <PageName>;
+```
+
+## Step 4 — Register the route
+
+Find where routes are defined (likely in `src/App.tsx` or a dedicated router file using `react-router-dom`). Add the new route following the exact same pattern used for existing routes. Import the new page component.
+
+## Step 5 — Add the menu item
+
+Edit `src/menu.ts` to add the new menu entry. Follow the existing structure exactly:
+
+```ts
+{
+  id: '<kebab-case-id>',
+  label: '<Label>',
+  icon: '<icon>',
+  route: '<route>',
+  operations: ['<operation>'],   // omit this array if no operation was specified
+}
+```
+
+If the item is nested, add it to the `children` array of the appropriate parent.
+
+## Step 6 — Add the operation to bootstrap (if needed)
+
+If an operation was specified in Step 2:
+1. Find `services/<app>-bootstrap-service/src/bootstrap/operations.json`
+2. Add the operation name to the array if it doesn't exist yet
+3. Find `roles.json` in the same directory and assign the operation to the appropriate role(s), following existing patterns
+
+## Rules
+
+- Never invent icon names — use ones already present in the codebase
+- Follow the exact naming and folder conventions found in the existing code
+- Do not add extra boilerplate (tests, stories, etc.) unless asked
+- If the router or menu structure is non-standard, describe what you found and ask the user how to proceed

package/skills/ba-platform/platform-add-operation.skill.md

@@ -0,0 +1,103 @@
+---
+name: platform-add-operation
+description: Defines a new authorization operation in the bootstrap service, assigns it to a role, and adds access guards in the React UI or NestJS backend. Use when the user wants to restrict a feature, page, or action to specific roles on a Blue Alba Platform app.
+---
+
+You are adding an authorization operation to a Blue Alba Platform application. The project is a monorepo: UI modules under `ui/`, services and bootstrap under `services/`.
+
+## Related Documentation
+
+Read `{{docsPath}}/architecture/authorization-system.mdx` for the full RBAC model, operation naming conventions, and authorization flow.
+
+## Step 1 — Read existing authorization config
+
+Find and read:
+- `services/<app>-bootstrap-service/src/bootstrap/operations.json`
+- `services/<app>-bootstrap-service/src/bootstrap/roles.json`
+
+Understand the existing naming patterns and role structure.
+
+## Step 2 — Ask for details
+
+Ask the user:
+
+1. **Operation name** — follow the pattern `domain::resource::action` (e.g. `billing::invoices::delete`). Suggest a name based on context if possible.
+2. **Role(s)** — which existing roles should be granted this operation? List the roles found in `roles.json`.
+3. **Where to enforce it** — which component, button, menu item, or API endpoint should be gated?
+4. **UI or backend (or both)?** — where should the guard be applied?
+
+Wait for the user's answer before continuing.
+
+## Step 3 — Add the operation to bootstrap
+
+Add the operation name to `operations.json` (it is typically an array of strings):
+```json
+"billing::invoices::delete"
+```
+
+In `roles.json`, find each target role and add the operation to its operations list, following the existing format exactly.
+
+## Step 4 — Enforce in the UI (if applicable)
+
+**To hide/show a component declaratively:**
+```tsx
+import { Authorized } from '@bluealba/pae-ui-react-core';
+
+<Authorized operations={['billing::invoices::delete']}>
+  <DeleteButton />
+</Authorized>
+```
+
+**To check programmatically:**
+```tsx
+import { useAuth } from '@bluealba/pae-ui-react-core';
+
+const { hasAccess } = useAuth();
+if (hasAccess('billing::invoices::delete')) { ... }
+
+// Require ALL of multiple operations:
+if (hasAccess(['billing::invoices::read', 'billing::invoices::delete'])) { ... }
+```
+
+**To restrict a menu item**, add the operation to its `operations` array in `menu.ts`:
+```ts
+{
+  id: 'delete-invoice',
+  label: 'Delete',
+  route: '/invoices/delete',
+  operations: ['billing::invoices::delete']
+}
+```
+
+## Step 5 — Enforce in the backend (if applicable)
+
+Backend authorization is handled **centrally by the gateway**, not by individual microservices. The gateway's `AuthorizationGuard` checks operations before proxying requests. To gate a specific API route, add an `authorization` block to the module's entry in `modules.json`:
+
+```json
+{
+  "name": "@acme/billing-service",
+  "baseUrl": "/api/billing",
+  "authorization": {
+    "operations": ["billing::invoices::read"],
+    "routes": [
+      {
+        "pattern": "/api/billing/invoices",
+        "methods": ["DELETE"],
+        "operations": ["billing::invoices::delete"]
+      }
+    ]
+  }
+}
+```
+
+- `authorization.operations` — default operations required to access any route in this module
+- `authorization.routes` — override operations for specific route + method combinations
+
+Read the existing `modules.json` to check whether the module already has an `authorization` block and extend it rather than replacing it.
+
+## Rules
+
+- Operation names must follow `domain::resource::action` — never invent a new naming scheme
+- Always read `roles.json` before assigning; never create new roles unless explicitly asked
+- Do not remove or rename existing operations
+- If the same operation already exists, skip Step 3 and go straight to enforcement

package/skills/ba-platform/platform-add-presence.skill.md

@@ -0,0 +1,84 @@
+---
+name: platform-add-presence
+description: Adds real-time user presence (who is viewing this page/resource) to a component in a Blue Alba Platform app using the Rooms API. Use when the user wants to show live avatars or awareness of other users in a view.
+---
+
+You are adding real-time presence tracking to a Blue Alba Platform single-spa application using the Rooms API. The project is a monorepo: UI modules under `ui/`.
+
+## Related Documentation
+
+Read `{{docsPath}}/guides/working-with-rooms.mdx` for the complete Rooms guide including backend deployment, WebSocket architecture, and advanced usage patterns.
+
+## Step 1 — Understand the context
+
+Read the target component the user wants to add presence to. Also read `src/App.tsx` (or the app root) to check whether `RoomsProvider` is already present in the component tree.
+
+## Step 2 — Ask for details
+
+Ask the user:
+
+1. **Which component/page** should show presence? (if not already clear from context)
+2. **Room scope** — what does a "room" represent here? Options:
+   - The whole page (e.g. `dashboard`) — everyone viewing the page is in the same room
+   - A specific resource (e.g. `invoice-{id}`) — presence scoped to a record
+3. **Tenant isolation** — should the room be scoped per tenant? (almost always yes — default to yes)
+4. **Display style** — just the count, avatars, or both?
+5. **Manual control** — should the user explicitly join/leave, or is it automatic?
+
+Wait for the user's answer before continuing.
+
+## Step 3 — Add RoomsProvider (if not present)
+
+If `RoomsProvider` is not already wrapping the app, add it in `src/App.tsx` around the component tree:
+
+```tsx
+import { RoomsProvider } from '@bluealba/pae-ui-react-core';
+
+function App() {
+  return (
+    <RoomsProvider>
+      {/* existing tree */}
+    </RoomsProvider>
+  );
+}
+```
+
+## Step 4 — Add presence to the target component
+
+**Automatic join/leave (default):**
+```tsx
+import { useRoom, RoomAvatars } from '@bluealba/pae-ui-react-core';
+import { useAuth } from '@bluealba/pae-ui-react-core';
+
+const { authUser } = useAuth();
+// Scope room per tenant to maintain multi-tenant isolation
+const { users } = useRoom(`tenant-${authUser.tenantId}-<room-name>`);
+
+return <RoomAvatars users={users} size="md" maxVisible={5} />;
+```
+
+**Resource-scoped room (e.g. per record):**
+```tsx
+const { users } = useRoom(`tenant-${authUser.tenantId}-invoice-${invoiceId}`);
+```
+
+**Manual control:**
+```tsx
+const { users, hasJoined, joinRoom, leaveRoom } = useRoom(roomId, {
+  autoJoin: false,
+  autoLeave: false,
+});
+```
+
+## Step 5 — Get the tenantId
+
+Check how other components in the codebase obtain the tenant ID (it may come from `useAuth`, a context, or a route param). Use the same pattern.
+
+If tenant context is unavailable in this component, read `src/App.tsx` or context providers to find where it lives and either pass it as a prop or move the hook up the tree.
+
+## Rules
+
+- Always scope room names per tenant: `tenant-<tenantId>-<room>` — never use a bare room name
+- `RoomsProvider` must appear only once, high in the tree — do not nest multiple providers
+- Prefer automatic join/leave unless the user explicitly needs manual control
+- Do not add presence to components that unmount and remount frequently (e.g. items in a list) — use it at page/view level

package/skills/ba-platform/platform-add-scheduled-job.skill.md

@@ -0,0 +1,65 @@
+---
+name: platform-add-scheduled-job
+description: Adds a scheduled job to a Blue Alba Platform bootstrap service. Use when the user wants to run a backend endpoint on a cron schedule.
+---
+
+You are adding a scheduled job to a Blue Alba Platform application's bootstrap service. The project is a monorepo: bootstrap lives under `services/<app>-bootstrap-service/src/bootstrap/`.
+
+## Related Documentation
+
+Read `{{docsPath}}/architecture/scheduler.mdx` for the complete scheduler architecture including dynamic parameters, SSRF security, cron syntax, and API endpoints.
+
+## Step 1 — Read the existing jobs config
+
+Find `services/<app>-bootstrap-service/src/bootstrap/jobs.json`. If it doesn't exist, it will need to be created. Read the file if it exists to understand existing jobs.
+
+## Step 2 — Ask for details
+
+Ask the user:
+
+1. **Job name** — kebab-case identifier (e.g. `nightly-report-generation`)
+2. **Description** — short human-readable description
+3. **Schedule** — cron expression (e.g. `0 2 * * *` for 2am daily). If the user gives a natural language description, convert it to cron.
+4. **URL** — the backend endpoint to call (e.g. `http://billing-service/api/jobs/generate-reports`)
+5. **Auth method** — `bearer` token, `basic` auth, or none?
+6. **Payload** — any `taskConfig` key/value pairs to pass to the endpoint? (optional)
+
+Wait for the user's answer before continuing.
+
+## Step 3 — Add the job
+
+Add the job entry to `jobs.json`. If the file doesn't exist, create it with a `jobs` array.
+
+```json
+{
+  "jobs": [
+    {
+      "name": "<job-name>",
+      "description": "<description>",
+      "schedule": "<cron>",
+      "url": "<url>",
+      "taskConfig": { },
+      "auth": {
+        "authMethod": "bearer",
+        "token": "{{$ENV.JOB_TOKEN}}"
+      }
+    }
+  ]
+}
+```
+
+- Omit `taskConfig` if no payload was specified
+- Omit `auth` if no auth is needed
+- Use `{{$ENV.VAR_NAME}}` for any sensitive values (tokens, passwords) — never hardcode them
+- For optional env vars with a default: `{{$ENV.VAR_NAME?=default}}`
+
+## Step 4 — Remind about env vars
+
+If auth tokens or other secrets were used with `{{$ENV.*}}`, remind the user to add the corresponding variable to their environment configuration (e.g. `.env`, docker-compose, or the platform's env config for that service).
+
+## Rules
+
+- Job names must be kebab-case and unique within the file
+- Never hardcode secrets — always use `{{$ENV.*}}` interpolation
+- Cron expressions follow standard 5-field format: `minute hour day month weekday`
+- The URL should point to the internal service hostname, not the gateway

package/skills/ba-platform/platform-cli.skill.md

@@ -1,3 +1,8 @@
+---
+name: platform-cli
+description: Blue Alba Platform CLI commands and usage knowledge
+---
+
 # Blue Alba Platform CLI — Expert Knowledge
 
 You are an expert on the Blue Alba Platform CLI (`@bluealba/platform-cli`, command: `platform`). Use the documentation files referenced below to answer questions accurately.

package/skills/ba-platform/platform-extend-shell.skill.md

@@ -0,0 +1,78 @@
+---
+name: platform-extend-shell
+description: Injects a custom component into a Blue Alba Platform shell extension point (navbar, branding, user section, etc.). Use when the user wants to add a button, logo, or custom element to the platform shell from within their app.
+---
+
+You are extending a shell UI extension point from within a Blue Alba Platform single-spa application. The project is a monorepo: UI modules under `ui/`, services under `services/`.
+
+## Related Documentation
+
+- `{{docsPath}}/architecture/shell.mdx` — Shell layout, customization methods, and extension point list
+- `{{docsPath}}/architecture/ui-extension-points.mdx` — Detailed extension point mechanism, lifecycle, and prop passing
+
+## Available extension points
+
+The shell exposes these named extension points:
+
+| Area | Extension Point Names |
+|---|---|
+| Branding | `NavbarPortalLogo`, `ExpandedNavbarPortalLogo`, `SplashScreen`, `SplashLogo`, `VersionsLogo` |
+| Navigation | `ApplicationSelector`, `CurrentApplicationMenu`, `CurrentApplicationMenuContent`, `OpenMenuButton`, `CloseMenuButton` |
+| Navbar | `NavbarContent`, `NavbarTools`, `NavbarToggleStateButton`, `AdminApplication` |
+| User section | `LoggedInUserSection`, `LoggedInUserAvatar` |
+| Top-level | `ShellTopElements` |
+
+## Step 1 — Discover the UI module structure
+
+Find the UI module under `ui/`. Read `src/main.tsx` (or the app root) and `src/App.tsx` to understand the component tree.
+
+## Step 2 — Ask for details
+
+Ask the user:
+
+1. **Which extension point?** — refer to the table above or let the user describe what they want to inject and suggest the right one.
+2. **What component to inject?** — does it already exist, or does it need to be created?
+3. **Is this conditional?** — should the extension be toggled dynamically (e.g. based on a feature flag or state)?
+
+Wait for the user's answer before continuing.
+
+## Step 3 — Create the component (if needed)
+
+If the component doesn't exist yet, create it under `src/components/` following existing naming conventions. Keep it minimal — just what the user described.
+
+## Step 4 — Register the extension
+
+Find the best place to register the extension. It should be inside the mounted React tree (e.g. `App.tsx` or a dedicated `ShellExtensions.tsx` component rendered from `App.tsx`).
+
+**Static extension (declarative):**
+```tsx
+import { ExtendExtensionPoint } from '@bluealba/pae-ui-react-core';
+
+<ExtendExtensionPoint module="@bluealba/pae-shell-ui" point="NavbarTools">
+  <MyToolbarButton />
+</ExtendExtensionPoint>
+```
+
+**Dynamic/conditional extension (hook):**
+```tsx
+import { useExtendExtensionPoint } from '@bluealba/pae-ui-react-core';
+
+useExtendExtensionPoint(
+  '@bluealba/pae-shell-ui',
+  'NavbarTools',
+  enabled ? MyToolbarButton : null
+);
+```
+
+Use the hook form only when the extension must be toggled at runtime. Otherwise prefer the declarative form.
+
+## Step 5 — Verify placement
+
+Confirm that the component calling `ExtendExtensionPoint` / `useExtendExtensionPoint` is rendered within the app's mounted React tree. If it isn't, add it there.
+
+## Rules
+
+- The `module` prop must always be `"@bluealba/pae-shell-ui"` for shell extension points
+- The `point` name must exactly match one of the names in the table above (case-sensitive)
+- Do not wrap extension registrations in conditional renders — use the hook form with `null` for dynamic toggling instead
+- Do not create a new file just to hold the extension if there is a logical existing component that can host it

package/skills/ba-platform/platform-scaffold-module.skill.md

@@ -0,0 +1,70 @@
+---
+name: platform-scaffold-module
+description: Scaffolds a new UI module or service module in a Blue Alba Platform monorepo using the platform CLI. Use when the user wants to add a new micro-frontend or backend service to an existing platform application.
+---
+
+You are helping the user scaffold a new module in a Blue Alba Platform monorepo. The platform CLI handles all scaffolding, port allocation, modules.json registration, and docker-compose updates automatically. Your job is to gather the right inputs and then run the CLI.
+
+## Step 1 — Understand the existing structure
+
+List the contents of `ui/` and `services/` to understand the current modules, naming conventions, and org prefix (e.g. `@bluealba`).
+
+## Step 2 — Ask for details
+
+Ask the user:
+
+1. **Module type** — UI module (React micro-frontend) or service module (NestJS backend)?
+2. **Application name** — the platform application this belongs to (e.g. `billing`). Look at existing directory names to suggest the correct one.
+3. **Module name** — for UI: the display name (e.g. `"Billing"`). For service: the service name (e.g. `payments`) and display name (e.g. `"Payments Service"`).
+
+Wait for the user's answer before continuing.
+
+## Step 3 — Run the CLI command
+
+**For a UI module:**
+```bash
+platform create-ui-module \
+  applicationName=<applicationName> \
+  applicationDisplayName="<displayName>"
+```
+
+**For a service module:**
+```bash
+platform create-service-module \
+  applicationName=<applicationName> \
+  serviceName=<serviceName> \
+  serviceDisplayName="<serviceDisplayName>"
+```
+
+Run the command from the monorepo root. The CLI will automatically:
+- Scaffold all files from templates
+- Allocate the next available port
+- Register the module in `modules.json` (bootstrap service)
+- Update `docker-compose.yml`
+
+Report the CLI output to the user.
+
+## Step 4 — Verify and review
+
+After the CLI completes, verify that everything looks correct:
+
+1. **Check the scaffolded directory** — list files in the new `ui/<name>` or `services/<name>` directory
+2. **Check modules.json** — read `services/<app>-bootstrap-service/src/bootstrap/modules.json` and confirm the new entry was added with correct values
+3. **Check docker-compose** — confirm the new service block was appended
+
+If anything is missing or looks wrong, tell the user what failed and suggest running the CLI again or making a manual fix.
+
+## Step 5 — Show next steps
+
+Tell the user:
+- Where the new module was created (exact path)
+- How to install dependencies: `cd <module-dir> && npm install`
+- How to start locally: `npm start` from the module directory, or restart the full platform with `platform start`
+- That they may need to restart the standalone environment to pick up the new bootstrap config
+
+## Rules
+
+- **Never manually scaffold module files** — always use the CLI commands
+- **Never manually edit modules.json to register a module** — the CLI does this automatically via `addModuleEntry`
+- If the CLI is not available (command not found), tell the user to install it: `npm install -g @bluealba/platform-cli`
+- If the CLI fails, show the full error output and ask the user to verify they are in the monorepo root

package/skills/ba-platform/platform.skill.md

@@ -1,3 +1,8 @@
+---
+name: platform
+description: Comprehensive Blue Alba Platform architecture and concepts knowledge
+---
+
 # Blue Alba Platform — Expert Knowledge
 
 You are an expert on the Blue Alba Platform monorepo. Use the documentation files referenced below to answer questions accurately.
@@ -17,6 +22,9 @@ Read these files for comprehensive platform knowledge:
 - `{{docsPath}}/architecture/shell.mdx` — Shell UI architecture and extension points
 - `{{docsPath}}/architecture/scheduler.mdx` — Job scheduling system
 - `{{docsPath}}/development/workflow.mdx` — Development workflow, git branching, changesets, testing
+- `{{docsPath}}/guides/using-feature-flags.mdx` — Feature flags system: declaration, targeting rules, React and NestJS usage
+- `{{docsPath}}/guides/working-with-rooms.mdx` — Real-time presence with Rooms API: WebSocket architecture, hooks, components
+- `{{docsPath}}/architecture/ui-extension-points.mdx` — Shell extension point mechanism, lifecycle, and customization
 - `{{docsPath}}/platform-cli/overview.mdx` — Platform CLI tool: installation, interactive mode, headless mode
 - `{{docsPath}}/platform-cli/commands.mdx` — All CLI commands reference