@atlashub/smartstack-cli 3.33.0 → 3.34.0

package/templates/skills/documentation/SKILL.md

@@ -88,10 +88,11 @@ Follow the data-driven workflow from [templates.md](templates.md):
 ```
 1. Read source data (feature.json, code patterns)
 2. Generate doc-data.ts (data file, ~50 lines)
-3. Generate index.tsx (page wrapper, ~10 lines)
+3. Generate index.tsx (page wrapper, ~10 lines) with i18nNamespace prop
 4. Generate i18n FR file (source language only)
 5. Update docs-manifest.json
 6. Update App.tsx routing and parent indexes
+7. Update DocPanelContext.tsx mapping (contextual doc panel)
 ```
 
 **For UPDATE documentation (type = update):**
@@ -118,16 +119,20 @@ Follow the data-driven workflow from [templates.md](templates.md):
 4. **ALWAYS** confirm before creating
 5. **ALWAYS** update App.tsx and parent indexes
 6. **ALWAYS** add module in `UserIndexPage.tsx` (IF type == `user`)
+7. **ALWAYS** update `DocPanelContext.tsx` mapping (IF type == `user`)
+8. **ALWAYS** pass `i18nNamespace` prop to DocRenderer in index.tsx
 </execution_rules>
 
 ---
 
 <success_criteria>
 - Documentation page renders correctly in React app
-- i18n files created for all 4 languages (FR, EN, IT, DE)
+- i18n FR file created (EN/IT/DE deferred to translation pipeline)
 - Route registered in App.tsx
 - docs-manifest.json updated
 - Module appears in UserIndexPage (if type = user)
+- DocPanelContext.tsx mapping updated (if type = user)
+- BookOpen edge button opens correct doc for the module's routes
 </success_criteria>
 
 ---
@@ -151,6 +156,87 @@ Follow the data-driven workflow from [templates.md](templates.md):
 
 ---
 
+## DocPanelContext Integration (TYPE: user)
+
+**MANDATORY** for `user` modules: Update the contextual documentation panel mapping.
+
+### How it works
+
+When a user clicks the BookOpen icon (edge button) on any application page, the `DocPanelContext` resolves the current route to the matching documentation URL and opens it in an iframe panel.
+
+### File to update
+
+`web/smartstack-web/src/contexts/DocPanelContext.tsx`
+
+### What to add
+
+For each module, add entries in the `docMapping` object for ALL the module's routes:
+
+```typescript
+const docMapping: Record<string, string> = {
+  // Platform > Administration > {Module}
+  '{module}': '/docs/business/platform/administration/{module}',
+  '{module}/list': '/docs/business/platform/administration/{module}',
+  '{module}/create': '/docs/business/platform/administration/{module}',
+  '{module}/dashboard': '/docs/business/platform/administration/{module}',
+  // ... add ALL sub-routes that exist for the module
+};
+```
+
+### Key resolution logic
+
+The `getDocUrlForPath()` function extracts segments from the pathname:
+- `/platform/administration/users/list` → tries `users/list`, then `users`
+- `/platform/support/tickets/123` → tries `tickets/123`, then `tickets`
+
+**Also update `appDocMapping`** if the module is the "default" for its application:
+
+```typescript
+const appDocMapping: Record<string, string> = {
+  'administration': '/docs/business/platform/administration/users',  // default for admin
+};
+```
+
+### index.tsx must pass i18nNamespace
+
+Each doc page wrapper MUST pass the correct i18n namespace to DocRenderer:
+
+```tsx
+import { DocRenderer } from '@/components/docs';
+import { docData } from './doc-data';
+
+export default function {Module}DocPage() {
+  return (
+    <DocRenderer
+      data={docData}
+      backPath="/docs/business/platform"
+      backLabel="nav.backToAdministration"
+      i18nNamespace="docsAdministration{Module}"
+    />
+  );
+}
+```
+
+### i18n namespace naming convention
+
+| Module | Namespace | File |
+|--------|-----------|------|
+| users | `docsAdministrationUsers` | `docs-administration-users.json` |
+| permissions | `docsAdministrationPermissions` | `docs-administration-permissions.json` |
+| tenants | `docsAdministrationTenants` | `docs-administration-tenants.json` |
+
+The JSON file root key MUST match the namespace: `{ "docsAdministration{Module}": { ... } }`
+
+### i18n config update
+
+Add the new namespace to `web/smartstack-web/src/i18n/config.ts`:
+1. Add to the destructured imports in `loadLanguageResources`
+2. Add the dynamic import with `.catch(() => ({ default: {} }))`
+3. Add to the return object
+4. Add to the `ns` array in `i18n.init()`
+
+---
+
 ## DATA SOURCES
 
 | Data | Source |
@@ -168,5 +254,9 @@ Follow the data-driven workflow from [templates.md](templates.md):
 - **Data Schema:** [data-schema.md](data-schema.md)
 - **DocRenderer:** `web/smartstack-web/src/components/docs/DocRenderer.tsx`
 - **Types:** `web/smartstack-web/src/components/docs/types.ts`
+- **DocPanelContext:** `web/smartstack-web/src/contexts/DocPanelContext.tsx`
+- **DocEdgeButton:** `web/smartstack-web/src/components/ui/DocEdgeButton.tsx`
+- **DocPanel:** `web/smartstack-web/src/components/ui/DocPanel.tsx`
+- **i18n Config:** `web/smartstack-web/src/i18n/config.ts`
 - **Manifest Schema:** `_resources/docs-manifest-schema.md`
 - **Complete Command:** `.claude/commands/documentation-module.md`

package/templates/skills/ralph-loop/SKILL.md

@@ -5,7 +5,9 @@ argument-hint: "[-m N] [-c TEXT] [-v] <task description>"
 ---
 
 <objective>
-Execute the Ralph Weegund technique — iterative development where the same prompt is fed repeatedly until completion. Uses progressive step loading with MCP validation, progress persistence, and Agent Teams for multi-module parallelization.
+Execute the Ralph Weegund technique — iterative module orchestration. Ralph reads PRDs from `/business-analyse`, resolves task dependencies, and delegates all code generation to `/apex -d`. Uses progress persistence and Agent Teams for multi-module parallelization.
+
+**Key principle:** Ralph ORCHESTRATES (task selection, module sequencing, PRD state, reporting). All code generation is delegated to `/apex`.
 </objective>
 
 <quick_start>
@@ -63,8 +65,7 @@ Execute the Ralph Weegund technique — iterative development where the same pro
 
 **Task execution cycle:**
 ```
-LOAD → GENERATE → COMPILE → TEST → [FAIL?] → FIX → RE-TEST → [PASS!] → COMMIT → NEXT
-                                       ↑___________________________|
+LOAD → DELEGATE TO /apex -d → VERIFY PRD STATE → COMMIT PRD → NEXT MODULE
 ```
 
 </workflow>
@@ -85,14 +86,7 @@ LOAD → GENERATE → COMPILE → TEST → [FAIL?] → FIX → RE-TEST → [PASS
 1. `mcp__smartstack__validate_conventions` — verify connectivity
 2. `mcp__context7__resolve-library-id` — verify connectivity
 
-**During work:**
-- `validate_conventions` — before commits
-- `check_migrations` — before EF Core changes
-- `suggest_migration` — migration naming
-- `generate_permissions` — RBAC seed data
-- `scaffold_api_client` — frontend API client
-- `scaffold_routes` — frontend routing
-- `scaffold_tests` — test generation
+**During work:** All MCP tool calls are handled by `/apex` during delegation. Ralph only uses `validate_conventions` for initial connectivity check.
 </mcp_requirements>
 
 <execution_guarantee>
@@ -116,7 +110,7 @@ When the user invokes `/ralph-loop`, they are giving you the instruction to:
 - Ask the user to choose between supervised/autonomous mode
 - Ask the user to choose a completion promise
 - Wait for user input between iterations
-- Delegate the loop to sub-agents (except team mode)
+- Delegate the loop to sub-agents (except team mode and /apex delegation)
 
 **The ONLY valid stop conditions are:**
 - ALL tasks completed (→ step-05 report)
@@ -137,7 +131,7 @@ When the user invokes `/ralph-loop`, they are giving you the instruction to:
 |------|------|---------|-------------|
 | 00 | `steps/step-00-init.md` | Parse args, verify MCP, init state, team setup | ~150 |
 | 01 | `steps/step-01-task.md` | Load/create tasks from prd.json | ~365 |
-| 02 | `steps/step-02-execute.md` | Execute ONE task (first iteration) | ~140 |
+| 02 | `steps/step-02-execute.md` | Delegate module to /apex -d | ~120 |
 | 03 | `steps/step-03-commit.md` | Commit, update prd.json/progress.txt | ~135 |
 | 04 | `steps/step-04-check.md` | Check completion, compact loop entry | ~185 |
 | 05 | `steps/step-05-report.md` | Generate final report | ~150 |
@@ -145,10 +139,8 @@ When the user invokes `/ralph-loop`, they are giving you the instruction to:
 **Reference files (loaded conditionally):**
 | File | Loaded when |
 |------|-------------|
-| `references/category-rules.md` | Step-02 and compact loop (execution rules per category) |
-| `references/compact-loop.md` | Step-04 section 5 (inline execution after first iteration) |
-| `references/core-seed-data.md` | Infrastructure task with seed data keywords |
-| `references/error-classification.md` | Build failure in compact loop or validation (error diagnosis) |
+| `references/category-rules.md` | Step-01 and compact loop (category ordering and dependency rules) |
+| `references/compact-loop.md` | Step-04 section 5 (module loop with /apex delegation) |
 | `references/team-orchestration.md` | Step-00 when multi-module detected (2+ PRDs) |
 </step_files>