nurosys-agents 2.0.0 → 2.1.0

package/.agent/frontend/skills/create-blueprint/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: create-blueprint
-description: Create or update project-memory artifacts (constitution, auth-model, repo-map, core-memory, models, architecture, quality-playbook) to keep them in sync with current codebase. Uses code-review-graph for efficient codebase analysis. Trigger with "create-blueprint all" to set up everything, or "create-blueprint <artifact_type>" for a specific artifact.
-disable-model-invocation: true
+description: Bootstrap or refresh `project-memory/` artifacts (constitution, auth-model, repo-map, architecture, design-system, models, quality-playbook, core-memory) from the current React/Next.js codebase. The canonical onboarding skill — run this FIRST when installing nurosys-agents in a new project. Uses Serena for symbolic codebase analysis. Trigger with `/create-blueprint all` to bootstrap everything, or `/create-blueprint <artifact_type>` for a single artifact.
+disable-model-invocation: false
 ---
 
 # Skill: create-blueprint
@@ -14,7 +14,7 @@ Use this skill to generate or refresh project-memory documentation artifacts bas
 
 - User asks `create-blueprint all` — runs all artifact types in sequence (full project-memory setup).
 - User asks `create-blueprint <artifact_type>` or `update-blueprint <artifact_type>` — creates or refreshes a single artifact.
-- Artifact types: `constitution`, `auth-model`, `repo-map`, `core-memory`, `models`, `architecture`, `quality-playbook`.
+- Artifact types: `constitution`, `auth-model`, `repo-map`, `core-memory`, `models`, `architecture`, `design-system`, `quality-playbook`.
 - When codebase has evolved significantly and project-memory docs are stale or missing.
 - After completing a major feature or architectural refactor to capture new patterns.
 
@@ -22,13 +22,14 @@ Use this skill to generate or refresh project-memory documentation artifacts bas
 
 When the user passes `all`, run each artifact **in this order** (dependencies first):
 
-1. `architecture` — establish system topology before anything else
-2. `models` — domain entities inform the repo map and constitution
-3. `repo-map` — module layout needed by all other docs
-4. `constitution` — rules derived from observed patterns in the codebase
-5. `auth-model` — auth flow and guards (depends on repo-map for file locations)
-6. `quality-playbook` — patterns and anti-patterns (derived from real code)
-7. `core-memory` — last, as it captures decisions made above
+1. `architecture` — establish app-router structure, server/client boundary rules, state-management approach
+2. `models` — shared types/interfaces inform repo map and constitution
+3. `repo-map` — module layout (pages/views/hooks/services/components) needed by all other docs
+4. `design-system` — design tokens, custom-wrapper inventory, form patterns (frontend-only artifact)
+5. `constitution` — rules derived from observed patterns in the codebase
+6. `auth-model` — client-side auth: context, useAuth, route gating, permission keys
+7. `quality-playbook` — patterns and anti-patterns (derived from real code)
+8. `core-memory` — last, as it captures decisions made above
 
 After each artifact is generated and approved, continue to the next without stopping for further user input unless a blocking question arises (e.g., ambiguous auth pattern). At the end, report a summary table of all artifacts created.
 
@@ -38,13 +39,14 @@ After each artifact is generated and approved, continue to the next without stop
 
 | Artifact | Purpose | When to create/update |
 |----------|---------|----------------------|
-| `constitution` | Non-negotiable rules (security, validation, DI, auth, SQL, error handling) | After major security decisions or framework upgrades |
-| `auth-model` | Complete JWT flow, guard chain, RBAC entities, identity propagation, tenant/resource scoping | After auth system changes or new permission patterns |
-| `repo-map` | Module layout, naming conventions, reusable components, key entry points, file registry | After adding new module categories or changing structure |
-| `core-memory` | Historical implementation decisions, completed modules, design lessons, known patterns | End of each completed feature or milestone |
-| `models` | Domain model inventory (ORM entities, associations, field contracts, constraints) | After new model additions or significant schema changes |
-| `architecture` | System-level architecture decisions, module topology, data flow, integration points | After architectural refactors or major coupling changes |
-| `quality-playbook` | High-signal check patterns with symptoms, root causes, preferred fixes | After discovering recurring bugs or anti-patterns |
+| `constitution` | Non-negotiable rules (React rules, a11y minimums, no-secret-in-client, performance budgets) | After major framework upgrades or quality decisions |
+| `auth-model` | Client-side auth: context provider, useAuth hook, route gating mechanism, permission keys, cookie helpers, login/logout flows | After auth system changes or new permission patterns |
+| `repo-map` | Pages/views/hooks/services/components layout, naming conventions, reusable components registry | After adding new module categories or changing structure |
+| `core-memory` | Historical implementation decisions, completed features, design lessons, known patterns | End of each completed feature or milestone |
+| `models` | Shared TypeScript types / interfaces / valibot schemas for domain entities | After new entity additions or significant type changes |
+| `architecture` | App-router structure, server/client boundaries, state-management approach, data-fetching patterns, integration points | After architectural refactors |
+| `design-system` | **Frontend-only.** Design tokens (color/spacing/typography), breakpoints, custom-wrapper inventory, Vuexy customization summary, form pattern, theme approach | After design-system changes, new wrappers, new tokens |
+| `quality-playbook` | High-signal React anti-patterns with symptoms, root causes, preferred fixes (rerender, hooks, derivation, effects vs events) | After discovering recurring bugs or anti-patterns |
 
 ---
 
@@ -68,70 +70,86 @@ If absent: → proceed to Phase 2 with a blank slate.
 
 ---
 
-## Phase 2 — Analyze codebase with graph tools
+## Phase 2 — Analyze codebase with Serena
 
-Use code-review-graph to extract structured information about the codebase **first** — avoid large file reads until you have a focused direction.
+Use Serena's symbolic tools to extract structured information **first** — avoid large file reads until you have a focused direction.
 
-### 2.1 Always call this first
+### 2.1 Orient yourself
+
+Start with the project layout:
+
+```bash
+ls -la                    # see top-level layout
+cat package.json          # detect framework (Next.js / Vite / CRA / Remix) and key deps
+ls src/app 2>/dev/null || ls src/pages 2>/dev/null  # detect router (app vs pages)
+```
+
+Then check Serena memories from prior sessions (if any):
 
 ```
-get_minimal_context(task="Analyzing codebase for <artifact-type> blueprint")
+list_memories
 ```
 
-This gives you:
-- Graph stats (total nodes, languages, communities, flows).
-- Risk score.
-- Key communities and flows.
+If memories exist with names like `project_overview`, `tech_stack`, `project_structure`, read them — they may already contain bootstrap context.
 
-### 2.2 Artifact-specific graph queries
+### 2.2 Artifact-specific Serena queries
 
-Call the appropriate sequence based on what you're building:
+Call the appropriate sequence based on what you're building. **Target: ≤8 Serena calls per artifact.**
 
 #### For `repo-map` (module layout, conventions):
-1. `list_communities(detail_level="minimal", sort_by="size")`
-2. `query_graph(pattern="file_summary", target="src/")`  (if src/ exists; adjust to your layout)
-3. `semantic_search_nodes(query="module entry point", kind="Function", limit=20)`
-
-#### For `architecture` (topology, coupling):
-1. `get_architecture_overview()`
-2. `get_bridge_nodes_tool(top_n=15)` — identify chokepoints
-3. `get_surprising_connections_tool(top_n=15)` — find unexpected coupling
-
-#### For `auth-model` (JWT, guards, RBAC):
-1. `semantic_search_nodes(query="auth guard middleware", kind="Class", limit=10)`
-2. `semantic_search_nodes(query="jwt token verify", limit=10)`
-3. `semantic_search_nodes(query="permission check", limit=10)`
-4. `query_graph(pattern="callees_of", target="<auth entry point>")`
-
-#### For `models` (entities, associations, constraints):
-1. `semantic_search_nodes(query="database model entity", kind="Class", limit=30)`
-2. `semantic_search_nodes(query="association foreign key", limit=10)`
-3. `query_graph(pattern="file_summary", target="src/path/to/models/")`
-
-#### For `quality-playbook` (patterns, anti-patterns):
-1. `list_graph_stats` — check for large functions
-2. `find_large_functions(min_lines=100, limit=20)` — identify complexity hotspots
-3. `get_knowledge_gaps_tool()` — find untested/undocumented areas
-4. `detect_changes(base="HEAD~20")` — analyze recent patterns in recent commits
-
-#### For `constitution` (security, validation, DI, error handling):
-1. `semantic_search_nodes(query="validation input dto", limit=10)`
-2. `semantic_search_nodes(query="auth guard decorator", limit=10)`
-3. `semantic_search_nodes(query="error exception handler", limit=10)`
-4. `semantic_search_nodes(query="dependency injection provider", limit=10)`
-
-#### For `core-memory` (decisions, completed modules):
-- If updating: read the existing file first (it's a manual record, not auto-derived).
-- Use graph to identify:
-  1. `list_communities(sort_by="name")` — enumerate all modules/communities.
-  2. `query_graph(pattern="file_summary", target="src/")` — understand what modules exist.
-- Cross-reference with existing core-memory to identify what's new or changed.
-
-### 2.3 Token efficiency
-
-- Use `detail_level="minimal"` on all queries.
-- Target ≤8 graph calls total for Phase 2.
-- Only escalate to `"standard"` if a query returns no results.
+1. `get_symbols_overview(relative_path="src")` — top-level structure
+2. For app-router: `get_symbols_overview(relative_path="src/app")` — see route tree. For pages-router: `get_symbols_overview(relative_path="src/pages")`.
+3. `get_symbols_overview(relative_path="src/components")` and `src/views/` and `src/hooks/` — drill into each top-level folder
+4. `find_symbol(name_path="...Page", substring_matching=true)` and `...Layout` to enumerate route entry points
+
+#### For `architecture` (app-router topology, server/client boundaries, state):
+1. `Read` `src/app/layout.tsx` (or `src/pages/_app.tsx`) to see top-level providers
+2. `find_symbol(name_path="...", substring_matching=true)` on `Provider` to enumerate context providers
+3. `find_symbol(name_path="...", substring_matching=true)` on `useQuery` / `useSWR` / `useMutation` to detect data-fetching approach
+4. `Read` `next.config.js` / `vite.config.ts` for build-time config
+
+#### For `auth-model` (client-side auth):
+1. `find_symbol(name_path="useAuth", substring_matching=true)` and `useSession` — locate the auth hook
+2. `find_symbol(include_body=true)` on that hook to read its mechanism
+3. `find_symbol(name_path="AuthProvider", substring_matching=true)` and `AuthContext` to find the context
+4. `find_referencing_symbols` on `useAuth` to enumerate consumers (route guards, gated UI)
+5. `Read` cookie / token helper files directly (typically `src/utils/auth.ts`, `src/configs/authConfig.ts` — per project conventions)
+6. Identify private-route convention by listing `src/app/` route-group directories (e.g. `(dashboard)`, `(private)`)
+
+#### For `design-system` (NEW — tokens, wrappers, patterns):
+1. `Read` `src/@core/theme/` or `src/themes/` to extract design tokens (colors, spacing, typography, breakpoints)
+2. `find_symbol(name_path="Custom", substring_matching=true)` — enumerate custom MUI wrappers (CustomTextField, CustomDialog, etc.)
+3. For each wrapper, `find_symbol(include_body=true)` to read its API surface
+4. `Read` an example form file to extract the project's form pattern (react-hook-form + valibot/zod, formik, etc.)
+5. Check the package.json for the UI library version and any Vuexy/template lineage
+
+#### For `models` (shared types, schemas):
+1. `get_symbols_overview(relative_path="src/types")` (or `src/models/` per convention)
+2. `find_symbol(name_path="...", substring_matching=true)` on `type ` patterns or specific entity names
+3. Sample 3-5 representative types/interfaces — don't enumerate all
+
+#### For `quality-playbook` (React anti-patterns):
+1. `git log --grep="fix:" --oneline | head -20` to spot recurring bug types
+2. `git log --grep="perf:" --oneline | head -20` for rerender/performance fixes
+3. Sample 1-2 representative component files to extract baseline patterns
+4. Reference `.agent/frontend/skills/code-reviewer/rules/` — the 23 rule files already encode known React anti-patterns; this artifact captures any project-specific patterns layered on top
+
+#### For `constitution` (React rules, a11y, performance, no-secrets):
+1. `find_symbol(name_path="...", substring_matching=true)` on patterns: `'use client'`, `Provider`, `Layout`
+2. Read 1-2 example client components to extract conventions (state, hooks, fetching)
+3. Read root layout for provider hierarchy
+4. Read `next.config.js` for CSP / headers / strict-mode settings
+
+#### For `core-memory` (history):
+1. Read existing `project-memory/core-memory.md` if present (this is a manual record, not auto-derived)
+2. `git log --oneline | head -30` to see recent work
+3. Cross-reference with existing core-memory to identify what's new or changed
+
+### 2.3 Efficiency
+
+- Always prefer `get_symbols_overview` + targeted `find_symbol` over raw `Read`
+- Target ≤8 Serena calls total for Phase 2
+- For files that aren't code (configs, migrations, json), use `Read` with `offset`/`limit` to read only relevant sections
 
 ---
 
@@ -143,13 +161,14 @@ Based on the graph results, perform targeted reads **only** for files the graph
 
 | Artifact | What to extract | How | Sources |
 |----------|-----------------|-----|---------|
-| `repo-map` | Module directories, naming conventions, required files per module type, reusable components, entry points | Read 1–3 representative module files per community; extract patterns | Graph: list_communities results; File reads: module index files, example modules |
-| `architecture` | Layer structure, communication flows, module boundaries, coupling points | Read architecture-touching files (root module wiring, main controller/handler patterns) | Graph: get_architecture_overview, bridge/hub nodes; Spot-check: root module, integration points |
-| `auth-model` | Guard types, token structure, permission check flow, tenant/resource scoping patterns | Read auth entry points and example auth-gated endpoints | Graph: semantic_search results for "auth guard", "jwt", "permission"; Spot-check: auth.module, sample protected endpoints |
-| `models` | ORM conventions, association patterns, field naming, timestamps/soft deletes | Read 3–5 representative model files | Graph: semantic_search for "model entity"; Read: models from different domains |
-| `constitution` | Validation rules, error envelope, DI patterns, SQL safety, logging, secret handling | Read representative implementations of each concern | Graph: semantic_search for "validation", "error", "provider", "query"; Spot-check: sample service, controller, query file |
-| `quality-playbook` | Recurring bugs, anti-patterns, preferred fixes | Analyze graph results for hotspots; read examples of fixes in git history or test files | Graph: find_large_functions, get_knowledge_gaps; Bash: `git log --grep="fix:" --oneline \| head -20` |
-| `core-memory` | Completed modules, design decisions, patterns to reuse/avoid | Existing file + graph enumeration | Existing core-memory.md; Graph: list_communities |
+| `repo-map` | Folder layout (pages/views/hooks/services/components), naming conventions, reusable components, entry points | Read 1–3 representative pages/views/hooks; extract patterns | Serena `get_symbols_overview` results; Read: example pages, layout files |
+| `architecture` | Server vs client boundary rules, state management approach, data fetching patterns, provider hierarchy, integration points | Read root layout/`_app.tsx`, top-level providers, example pages | Serena results for `Provider`, data-fetching hooks; Read: root layout, next.config |
+| `auth-model` | Context provider, useAuth hook signature, route gating mechanism, permission keys, cookie helpers, login/logout flow | Read auth context, hook, cookie helpers, and a representative private page | Serena results for `useAuth`, `AuthContext`; Read: cookie helpers, route-group directories |
+| `design-system` | Theme tokens (color/spacing/typography/breakpoints), custom-wrapper inventory, form pattern, Vuexy/template lineage | Read theme files + each Custom* wrapper body + 1 example form | Serena results for `Custom*` symbols; Read: theme, example form file |
+| `models` | TypeScript types/interfaces/schemas, shared shapes | Read 3–5 representative type/schema files | Serena `find_symbol` results; Read: types from different domains |
+| `constitution` | React rules in use, a11y conventions, performance guards, no-secrets rules, server/client boundary rules | Read representative client/server components, root layout, next.config | Serena results for `'use client'`, providers; Read: examples |
+| `quality-playbook` | Recurring React anti-patterns, preferred fixes (project-specific, layered on top of the 23 rule files) | Analyze git fix-commit history; read 1–2 example components | Bash: `git log --grep="fix:" --oneline`; Read: examples |
+| `core-memory` | Completed features, design decisions, patterns to reuse/avoid | Existing file + git enumeration | Existing core-memory.md; Bash: `git log --oneline` |
 
 ### 3.2 Read targeted files
 
@@ -220,42 +239,65 @@ Non-negotiable rules for this codebase.
 - [Rule about framework usage, anti-patterns]
 ```
 
-#### auth-model.md
+#### auth-model.md (frontend / client-side)
 
 ```markdown
-# Auth Model
-
-Complete JWT flow, guard chain, RBAC entities, identity propagation.
-
-## Token issuance
-- [How JWT is created: algorithm, claims, expiry]
-- [Where token issuance happens: auth controller/service endpoint]
-- [Token refresh strategy if applicable]
-
-## Guard chain
-- [List of guards in order: auth guard, permission guard, custom guards]
-- [How each guard is applied: decorators, middleware, imports]
-- [Example endpoint with guard chain]
-
-## Request context propagation
-- [How authenticated user context flows into services]
-- [How to access current user in controller/service: decorator, injection]
-- [How tenant/ownership context is passed]
-
-## RBAC entities
-- [User role structure: built-in roles, custom roles]
-- [Permission structure: what permissions exist, how they're grouped]
-- [Role-permission associations: how roles get permissions]
-
-## Tenant/resource scoping
-- [How tenant is determined: from JWT claim, request context, or other]
-- [How resources are filtered by tenant: query predicates, service-level checks]
-- [How ownership is enforced: user ID checks, team ID checks]
-
-## Identity propagation patterns
-- [Example: controller accepting CurrentUser decorator → passing to service]
-- [Example: service using authenticated context for filtering]
-- [Example: cross-service calls preserving identity]
+# Auth Model (Frontend / Client-Side)
+
+Client-side auth: context provider, useAuth hook, route gating, permission keys, cookie/session handling, login/logout flows. The backend is the security boundary; this document describes what the **UI** does to reflect the auth state and gate visible UI.
+
+## Context provider
+- **Name and file**: [e.g. `<AuthProvider>` in `src/contexts/authContext.tsx`]
+- **Scope**: where it wraps in the app tree (root layout, dashboard-only, etc.)
+- **State it exposes**: user, isLoading, isAuthenticated, permissions, login(), logout(), refresh()
+
+## useAuth (or equivalent) hook
+- **Name and file**: [e.g. `useAuth()` in `src/contexts/authContext.tsx`]
+- **Return shape** (TypeScript):
+  ```ts
+  { user: User | null; isLoading: boolean; permissions: Permission[]; login(...): Promise<void>; logout(): Promise<void>; hasPermission(key: PermissionKey): boolean }
+  ```
+- **Where to use**: in client components only (not server components — for server components, document the server-side data-fetching pattern)
+
+## Private vs public route convention
+- **How a route is marked private**: [e.g. file convention `src/app/[lang]/(private)/...`, HOC, middleware, server-side check]
+- **How a route is marked public**: [e.g. `(public)` route group, explicit allowlist]
+- **Gate enforcement point**: [middleware? layout-level? per-page server-side check? client-side redirect?]
+- **Behavior on unauthorized**: [redirect to /login with returnTo, render 403 page, etc.]
+
+## Permission keys
+- **Enum / type location**: [e.g. `src/types/permissions.ts`]
+- **Key naming convention**: [e.g. `<resource>:<action>` — `users:read`, `users:update`]
+- **Where keys are checked**:
+  - Page-level access (in the documented gate)
+  - UI element gating (button disable/hide via `useAuth().hasPermission(...)`)
+
+## Cookie / token / storage handling
+- **Helper file**: [e.g. `src/utils/auth.ts`]
+- **Token storage**: [httpOnly cookies (server-set, recommended), localStorage (only if documented), etc.]
+- **Cookie attributes (when client controls them)**: Secure, SameSite, httpOnly
+- **Token refresh strategy**: [silent refresh, refresh on 401, etc.]
+
+## Login flow
+1. User visits `/login`
+2. Form submits to [endpoint]
+3. On success: [cookie set / token stored / context updated]
+4. Redirect to `returnTo` or default landing
+
+## Logout flow
+1. User clicks logout
+2. [API call to invalidate session / clear cookies]
+3. Context cleared, sensitive cached data invalidated (SWR / React Query / store)
+4. Redirect to `/login` (or public landing)
+
+## Server-side counterpart
+- **What the backend enforces** (so UI checks are not the security boundary): [e.g. every authenticated route on the backend validates the session cookie + checks permission server-side]
+- **Source of truth for permissions**: [server endpoint that returns user + permissions, called on session start]
+
+## Patterns
+- **Identity propagation to API calls**: [how the fetcher injects the session — cookies sent automatically, Authorization header, etc.]
+- **Loading state**: components must guard against `user === null` while `isLoading` is true
+- **Logout side effects**: enumerate caches / stores cleared on logout
 ```
 
 #### repo-map.md
@@ -427,6 +469,101 @@ Example:
 - **Monolithic API backend**: Simple to deploy and reason about. Tradeoff: harder to scale individual features independently (mitigated with feature flags and service extraction when needed).
 ```
 
+#### design-system.md (frontend-only)
+
+```markdown
+# Design System
+
+Design tokens, custom-wrapper inventory, form patterns, theming approach. The single source of truth for "what does the UI look like and what building blocks compose it."
+
+## Template lineage
+- **Base**: [e.g. Vuexy Admin Template v9.x, ShadCN, custom]
+- **UI library**: [e.g. MUI v7, Tailwind, Chakra]
+- **Version**: [exact version in package.json]
+
+## Theme tokens
+
+### Colors
+- **Primary palette**: [token names, hex values]
+- **Semantic colors**: error, warning, info, success
+- **Skin variants**: [filled / light / light-static, per Vuexy convention]
+
+### Typography
+- **Font families**: [primary, mono]
+- **Type scale**: [body, heading levels]
+
+### Spacing
+- **Scale**: [0, 1, 2, 4, 8, 16, 24, 32 — in units matching theme]
+- **Layout grid**: [breakpoints, container widths]
+
+### Breakpoints
+- xs / sm / md / lg / xl with their pixel values
+
+### Other tokens
+- Border radius, shadows, transitions
+
+## Custom wrapper inventory
+
+| Wrapper | Wraps | When to use | Key props |
+|---------|-------|-------------|-----------|
+| `CustomTextField` | `TextField` | Every text input | size, variant, error, helperText |
+| `CustomDialog` | `Dialog` | Modal dialogs (forms, confirmations) | maxWidth, scroll, fullWidth |
+| `CustomAvatar` | `Avatar` | User avatars, icon avatars | skin, color, src |
+| `CustomChip` | `Chip` | Tags, status indicators | skin, color, variant |
+| `CustomBadge` | `Badge` | Counts, dots | skin, color, max |
+| `CustomTabList` | `TabList` | Tabs | indicator color |
+| `CustomIconButton` | `IconButton` | Icon-only buttons | requires aria-label |
+| `CustomAutocomplete` | `Autocomplete` | Combobox inputs | options, getOptionLabel |
+
+For each wrapper: file path, common props, what NOT to use it for.
+
+## Form pattern
+
+- **Library**: [react-hook-form + valibot / formik + yup / etc.]
+- **Standard template**:
+  ```tsx
+  // (pseudo-code — actual project uses real types)
+  const form = useForm({ resolver: valibotResolver(schema), defaultValues })
+  // Field via Controller<...> + CustomTextField
+  // Submit with form.handleSubmit(onSubmit)
+  ```
+- **Validation conventions**: where schemas live, how server errors map to field errors
+
+## Layout / page-shell
+
+- **App-shell composition**: nav + sidebar + main + footer (per template)
+- **Page-content max-width**: [per breakpoint]
+- **Container component**: [e.g. `<PageContent>`]
+
+## Patterns
+
+### Dialog pattern
+- Standard composition: header (title + close) → body (scrollable) → footer (cancel + primary action)
+- Reference: `examples.md#form-dialogs`
+
+### Drawer pattern
+- When to use vs dialog: drawer for navigation/long content, dialog for focused actions
+- Reference: ...
+
+### Data grid
+- Wrapper: [project's DataGrid wrapper if any]
+- Pagination strategy: client-side / server-side
+
+### Empty / loading / error states
+- Standard components: `<EmptyState>`, `<LoadingState>`, `<ErrorState>` — files and props
+
+## Accessibility defaults
+- Theme color contrast meets WCAG AA (per Vuexy)
+- All Custom* wrappers are keyboard-accessible by default
+- `CustomIconButton` REQUIRES `aria-label` — enforced by linter
+- Focus management: dialogs trap focus and return it on close
+
+## When to extend the design system
+- **Yes**: a new pattern reused 3+ times, a new token needed across multiple features
+- **No (use existing instead)**: one-off styling, slight variants of an existing wrapper
+- **Process**: file an addition under `src/@core/components/` (or template's equivalent) + update this artifact via `/create-blueprint design-system`
+```
+
 #### quality-playbook.md
 
 ```markdown
@@ -578,35 +715,48 @@ ls -la .claude/docs/<artifact-type>.md .cursor/docs/<artifact-type>.md
 
 If either symlink already exists, skip (do not overwrite).
 
-#### 7.3.2 Script symlink (always check)
+#### 7.3.2 Module execution
+
+Feature execution is now handled entirely by the `/module-runner` skill (no shell script needed). `/module-runner` is wired during `npm exec nurosys-agent-setup` for the user's chosen IDE. No additional setup required here.
 
-Ensure `scripts/run-feature-modules.sh` is symlinked to `.agent/scripts/run-feature-modules.sh`:
+### 7.4 Wire artifact as a Cursor rule
+
+After writing the artifact, run the cursor rules setup script to create (or refresh) the `.cursor/rules/<artifact-type>.mdc` symlink pointing to the new file:
 
 ```bash
-# Check if symlink exists
-if [ ! -L scripts/run-feature-modules.sh ]; then
-  # Remove the file if it exists as a regular file
-  rm -f scripts/run-feature-modules.sh
-  # Create the symlink
-  ln -sf ../.agent/scripts/run-feature-modules.sh scripts/run-feature-modules.sh
-  echo "✅ Created symlink: scripts/run-feature-modules.sh"
-else
-  echo "✅ Symlink already exists: scripts/run-feature-modules.sh"
-fi
+node scripts/setup-cursor-rules.js
 ```
 
-**Verify**:
+Or if installed as a package bin:
 ```bash
-ls -la scripts/run-feature-modules.sh
+npm exec nurosys-setup-rules
 ```
 
-This ensures the script is maintained in a single location (`.agent/scripts/`) and referenced from the root `scripts/` folder.
+This script:
+- Creates `.cursor/rules/` if it does not exist
+- Adds a `.mdc` symlink for every `project-memory/*.md` that exists
+- Skips files that already have a symlink
+- Reports which files were linked, skipped, or missing
+
+The `.cursor/rules/<artifact>.mdc` files are written by `nurosys-setup-rules` with the correct MDC frontmatter automatically — you do not need to embed frontmatter in the `project-memory/` source files. For reference, the frontmatter applied per artifact is:
+
+| Artifact | `description` | `globs` | `alwaysApply` |
+|----------|--------------|---------|---------------|
+| `constitution.md` | "Non-negotiable project rules and coding standards" | — | `true` |
+| `architecture.md` | "System architecture, module topology, and data flow" | — | `true` |
+| `repo-map.md` | "Repository module layout, naming conventions, and reusable components" | — | `true` |
+| `auth-model.md` | "Auth model, JWT flow, guard chain, RBAC, and tenant scoping" | `["src/auth/**", "src/core/auth/**"]` | `false` |
+| `models.md` | "Domain model inventory and entity definitions" | `["src/**/*.model.ts", "src/**/*.entity.ts"]` | `false` |
+| `quality-playbook.md` | "Code quality patterns, anti-patterns, and preferred fixes for this project" | — | `false` |
+| `core-memory.md` | "Project history, design decisions, and completed modules" | — | `false` |
+
+When `create-blueprint all` runs, call the script once at the end after all artifacts are written.
 
-### 7.4 Confirm with user
+### 7.5 Confirm with user
 
 Report:
 - The artifact file path: `project-memory/<artifact-type>.md`
-- Symlink paths created (if new): `.claude/docs/<artifact-type>.md`, `.cursor/docs/<artifact-type>.md`
+- Whether `.cursor/rules/<artifact-type>.mdc` symlink was created or already existed
 - Whether this was a creation or update
 - Number of sections/changes
 
@@ -630,6 +780,6 @@ Before finalizing the artifact:
 - **Single source of truth**: project-memory artifacts are the authoritative reference stored in `project-memory/<artifact-type>.md`. If they conflict with code, the code is wrong — update the code, not the artifact.
 - **Symlink architecture**: Artifacts in `project-memory/` are symlinked from `.claude/docs/` and `.cursor/docs/` to avoid duplication. Symlinks are created automatically when a new artifact is generated. **Always edit the artifact in `project-memory/`, never in the symlink copies.**
 - **Regular refresh cadence**: After each completed feature module (or every 2–3 weeks), run `create-blueprint` on `core-memory` and `repo-map` to keep them current.
-- **Graph-first approach**: Always use code-review-graph tools before reading files. The graph is faster and gives you structural context.
+- **Serena-first approach**: Always use Serena's symbolic tools (`get_symbols_overview`, `find_symbol`, `find_referencing_symbols`) before reading whole files. Symbolic navigation is faster and uses far fewer tokens.
 - **Curation, not exhaustion**: Artifact sections describe the most important patterns and decisions, not every detail. If a pattern is used once, it probably doesn't need to be in the playbook.
 - **Portable artifacts**: These skill generates artifacts that are project-specific in content but portable in structure. You can copy the `project-memory/` folder to another project and run the skill again to regenerate them with that project's codebase.

package/.agent/frontend/skills/debug-issue/SKILL.md

@@ -1,28 +1,86 @@
 ---
 name: debug-issue
-description: Systematically debug issues using graph-powered code navigation
-disable-model-invocation: true
+description: Systematically trace and diagnose React/Next.js issues using Serena's symbolic tools. Trigger on "debug", "why is X failing", "trace this error", or any user-reported bug — runtime errors, rerender loops, stale data, hook warnings, hydration mismatches, prod-only bugs. Symbol-level, not full-file reads.
 ---
 
-## Debug Issue
+# Skill: debug-issue (frontend)
 
-Use the knowledge graph to systematically trace and debug issues.
+Trace bugs through the codebase using symbolic navigation. The rule: **follow the symptom, don't grep the world**.
 
-### Steps
+## Steps
 
-1. Use `semantic_search_nodes` to find code related to the issue.
-2. Use `query_graph` with `callers_of` and `callees_of` to trace call chains.
-3. Use `get_flow` to see full execution paths through suspected areas.
-4. Run `detect_changes` to check if recent changes caused the issue.
-5. Use `get_impact_radius` on suspected files to see what else is affected.
+1. **Capture the symptom precisely**
+   - Error message, stack trace, console warnings, reproduction steps, expected vs actual.
+   - For hydration errors: server-rendered HTML mismatch and the offending component path from the warning.
+   - For rerender loops: which component or hook the React DevTools profiler identifies.
+   - If the user gave a stack trace, the top app-code frame is your starting symbol.
 
-### Tips
+2. **Locate the suspected entry point**
+   - `find_symbol(name_path="<name from stack/trace>", include_body=true)` — read the function/component/hook where the symptom surfaces.
 
-- Check both callers and callees to understand the full context.
-- Look at affected flows to find the entry point that triggers the bug.
-- Recent changes are the most common source of new issues.
+3. **Check Recent changes**
+   - `git log -p --follow <suspect-file>` — what changed recently?
+   - If the bug landed since the last release, the suspect file's recent commits are the most likely cause.
 
-## Token Efficiency Rules
-- ALWAYS start with `get_minimal_context(task="<your task>")` before any other graph tool.
-- Use `detail_level="minimal"` on all calls. Only escalate to "standard" when minimal is insufficient.
-- Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens.
+4. **For each bug class, apply the right lens:**
+
+   ### Rerender loops / infinite updates
+   - Read the suspect's body. Look for:
+     - State updates in render
+     - Effects with state in deps that update that same state without a stable trigger
+     - Inline object/array/function in dependency arrays
+     - Inline component definitions inside the parent
+   - Reference rule files: `rules/rerender-derived-state-no-effect.md`, `rules/rerender-dependencies.md`, `rules/rerender-no-inline-components.md`, `rules/rerender-functional-setstate.md`
+
+   ### Stale data / closure bugs
+   - Reference: `rules/rerender-defer-reads.md`, `rules/rerender-use-ref-transient-values.md`, `rules/advanced-event-handler-refs.md`
+   - Check: stale closure over state inside a callback registered once (event listener, timer, websocket handler)
+
+   ### Hook dependency warnings (`react-hooks/exhaustive-deps`)
+   - Reference: `rules/react-rules-hooks.md`
+   - Don't silence with eslint-disable. The warning is usually right.
+
+   ### Hydration mismatch
+   - Look for: `Date.now()`, `Math.random()`, browser-only APIs (`window`, `document`) in components rendered on the server
+   - Check: client-only state initialized differently on server vs client
+   - Reference: `rules/rerender-lazy-state-init.md` for safe deferred init
+
+   ### "Works in dev, breaks in production"
+   - Check: `process.env.NODE_ENV` branches
+   - Check: missing keys in lists (silent in dev, surfaces in prod)
+   - Check: `console.*` statements stripped in prod that hid an actual error
+   - Check: source-map mismatch (use the unminified stack via DevTools)
+
+   ### Data not appearing / fetch failing
+   - Trace upstream: who calls this hook/component? `find_referencing_symbols`
+   - Trace downstream: what API does the hook hit? Check the fetch URL.
+   - Empty/loading/error states present per `architecture.md`?
+
+5. **Read targeted memories**
+   - `list_memories` then `read_memory` if any look relevant (e.g. prior bug in the same area).
+
+6. **Form a hypothesis and confirm**
+   - State the suspected cause concisely.
+   - Confirm by running the repro, adding a temporary log, or reading one more symbol.
+   - Don't write a fix until you can explain the root cause in one sentence.
+
+## Tips
+
+- **Stack trace is the map.** Walk app-code frames from top down, reading symbol bodies along the way. Don't try to understand the whole module first.
+- **Recent changes are the most common cause** of a newly-reported bug. Check `git log` early.
+- **Consumers AND callees.** A hook can fail because of bad props (consumer's fault) or bad logic (its own fault) — check both.
+- **React DevTools profiler** for rerender bugs — note the path from the user's screenshot/description; that path is your starting symbol.
+- **Hydration errors include the component path** in the warning — use it as your entry point.
+- **Avoid speculative grepping.** If you find yourself searching for "this might be related", you've lost the trail — go back to the symptom.
+
+## Token Efficiency
+
+- Target ≤6 Serena calls: locate entry (1) + read body (1) + consumers (1) + key callees (1-2) + verify (1).
+- If you need more, you're either solving the wrong problem or the bug is genuinely cross-cutting — pause and tell the user what you've found.
+
+## Do not
+
+- Fix the bug in this skill. This skill diagnoses; fixes go through `/quick-execute` (small) or `/architect` → `/module-runner` (large).
+- Read whole files when a symbol body suffices.
+- Silence lint warnings to make the symptom go away. Investigate first.
+- Add temporary `console.log` to production code paths without flagging it to the user.