---
name: step-01-navigation
description: Generate navigation entity seeds using MCP scaffold_navigation (with fallback)
prev_step: steps/step-00-init.md
next_step: steps/step-02-permissions.md
---

# Step 1: Navigation Generation

## MANDATORY EXECUTION RULES

- PREFER MCP `scaffold_navigation` tool as the primary method
- If MCP is unavailable (`{mcp_available}` = false) or the call fails, use the FALLBACK PROCEDURE below
- ALWAYS verify the output includes translations for 4 languages (fr, en, it, de)
- ALWAYS WRITE generated code to the actual Configuration files (not just display)
- Store navigation GUID for use in subsequent steps

## YOUR TASK

Generate navigation entity seeds:
1. Navigation entity HasData() code in the appropriate Configuration.cs
2. NavigationTranslation entries (4 languages) in NavigationTranslationConfiguration.cs

---

## AVAILABLE STATE

From step-00-init:

| Variable | Description |
|----------|-------------|
| `{level}` | context, application, module, or section |
| `{code}` | kebab-case identifier |
| `{full_path}` | Complete navigation path |
| `{parent_path}` | Parent path (null for context) |
| `{labels}` | Object with fr, en, it, de |
| `{descriptions}` | Object with fr, en, it, de |
| `{icon}` | Lucide icon name |
| `{display_order}` | Numeric display order |
| `{mcp_available}` | Boolean - MCP connectivity status |
| `{project_type}` | "core" or "client" |
| `{seeding_strategy}` | "hasdata" or "provider" |

---

## EXECUTION SEQUENCE (MCP Primary)

> **Branch:** If `{seeding_strategy}` = "provider", jump to **CLIENT PROJECT HANDLING** section below.
> The MCP and FALLBACK sections apply only when `{seeding_strategy}` = "hasdata" (core projects).

### 1. Call MCP scaffold_navigation

```
Tool: mcp__smartstack__scaffold_navigation
Args:
  level: "{level}"
  code: "{code}"
  parentPath: "{parent_path}"  # Omit if level is "context"
  labels:
    fr: "{labels.fr}"
    en: "{labels.en}"
    it: "{labels.it}"
    de: "{labels.de}"
  descriptions:
    fr: "{descriptions.fr}"
    en: "{descriptions.en}"
    it: "{descriptions.it}"
    de: "{descriptions.de}"
  icon: "{icon}"
  displayOrder: {display_order}
```

### 2. Parse MCP Response

The tool returns:
- Navigation entity GUID (deterministic)
- HasData() code for NavigationXxxConfiguration.cs
- HasData() code for NavigationTranslationConfiguration.cs
- SeedData class template (optional)

### 3. Write Code to Files

**CRITICAL:** WRITE the generated code to the actual Configuration files.

1. Update `Navigation{Level}Configuration.cs` with the new HasData entry
2. Update `NavigationTranslationConfiguration.cs` with the 4 translation entries

### 4. Store Generated GUID

```
{navigation_guid} = [GUID from MCP response]
```

---

## MCP RESPONSE HANDLING

### Success Case

If MCP returns successfully:
- Write HasData code to Configuration files
- Store `{navigation_guid}` for next step
- Proceed to step-02-permissions.md

### Error Case

If MCP call fails or `{mcp_available}` = false:
- Log the error for reference
- Proceed to FALLBACK PROCEDURE below
- Do NOT stop the workflow

---

## CLIENT PROJECT HANDLING

> **Condition:** `{seeding_strategy}` = "provider"

For client projects, navigation is NOT seeded via HasData() in Configuration files.
It will be seeded at runtime via `IClientSeedDataProvider` generated at step 03b.

### Actions for a client project:

1. **Generate the navigation GUID** (deterministic, same method as core)
2. **Create the SeedData file** (same pattern as existing)
   - `Infrastructure/Persistence/Seeding/Data/{Domain}/{Module}NavigationSeedData.cs`
   - Contains static GUIDs and `GetNavigationEntries()`
3. **Create the translations file**
   - `Infrastructure/Persistence/Seeding/Data/{Domain}/{Module}NavigationTranslationSeedData.cs`
4. **DO NOT search for** `NavigationModuleConfiguration.cs` (does not exist in client projects)
5. **DO NOT write** HasData() in Configuration files
6. **Store** `{navigation_guid}` for subsequent steps

The SeedData files will be consumed by the `IClientSeedDataProvider` generated at step 03b.

**After creating SeedData files:** Store `{navigation_guid}` and proceed to step-02-permissions.md.

---

## FALLBACK PROCEDURE (When MCP Unavailable)

See [references/nav-fallback-procedure.md](../references/nav-fallback-procedure.md) for the complete 8-step fallback:
- **F1:** Read existing Configuration/SeedData files to determine state
- **F2:** Determine parent GUID by level
- **F3:** Generate deterministic GUID (SHA256, never NewGuid())
- **F4:** Write navigation entity seed (SeedData class or inline HasData)
- **F5:** Write 4 translation entries (continue existing index sequence)
- **F6-F8:** Store result, validation checklist, summary

---

## SUCCESS METRICS

- Navigation entity GUID obtained (via MCP or fallback)
- HasData code WRITTEN to Configuration files
- Translation code WRITTEN (4 languages)
- `{navigation_guid}` stored for step-02
- Proceeded to step-02-permissions.md

## FAILURE MODES

- Missing parent path for non-context level (return to step-00)
- Invalid level (return to step-00)
- Parent entity not found in existing seeds (ask user for parent GUID)

---

## NEXT STEP

After navigation seeds are generated (via MCP or fallback) and written to files,
proceed to `./step-02-permissions.md`
