---
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)

> This procedure generates navigation seeds following SmartStack.app patterns.
> Reference: `templates-seed.md` for code templates.
>
> **Branch by Project Type:**
> - If `{seeding_strategy}` = "hasdata" (core project): Follow F1-F8 below (existing pattern)
> - If `{seeding_strategy}` = "provider" (client project): Follow **CLIENT PROJECT HANDLING** above (create SeedData classes only, no HasData)

### F1. Read Existing Configuration Files

**CRITICAL:** Before generating any code, read existing files to determine state:

1. **Find the Navigation Configuration directory:**
   ```
   Glob: **/Persistence/Configurations/Navigation/Navigation*Configuration.cs
   ```

2. **Read NavigationTranslationConfiguration.cs** - Find the last GUID index:
   ```
   Search for: the last call to GenerateGuid(index++)
   The index variable starts at 1 and increments per translation entry.
   Your new translations MUST continue from the next index value.
   ```

3. **Read Navigation{Level}Configuration.cs** - Check existing entities:
   ```
   Read the Configuration for the target level (Context, Application, Module, Section).
   Check if it already references a SeedData class: builder.HasData(Navigation{Level}SeedData.GetSeedData())
   If yes: Read the corresponding SeedData class to find existing entries.
   If no: You will need to add HasData() call.
   ```

4. **Read existing SeedData files** (if they exist):
   ```
   Glob: **/Seeding/Data/Navigation/Navigation{Level}SeedData.cs
   Check for existing entity IDs to avoid collisions.
   ```

### F2. Determine Parent GUID

For non-context levels, find the parent entity GUID:

| Level | Parent | Where to Find Parent GUID |
|-------|--------|---------------------------|
| application | context | `NavigationContextSeedData.cs` → e.g. `PlatformContextId` |
| module | application | `NavigationApplicationSeedData.cs` → e.g. `AdministrationAppId` |
| section | module | `NavigationModuleSeedData.cs` → e.g. `UsersModuleId` |

Read the parent SeedData class and find the GUID matching `{parent_path}`.

### F3. Generate Navigation Entity GUID

Generate a deterministic GUID for the new navigation entity:

```csharp
// Use SHA256 hash of the full_path for deterministic generation
using var sha256 = System.Security.Cryptography.SHA256.Create();
var hash = sha256.ComputeHash(Encoding.UTF8.GetBytes("navigation-{level}-{full_path}"));
var guid = new Guid(hash.Take(16).ToArray());
```

**Rules:**
- NEVER use `Guid.NewGuid()`
- Read existing SeedData GUIDs to verify no collision
- Store result as `{navigation_guid}`

### F4. Write Navigation Entity Seed

Based on `{level}`, write the seed entry.

**Option A: Project uses SeedData classes (SmartStack.app pattern)**

If `Navigation{Level}SeedData.cs` exists, add the new entity:

```csharp
// In Infrastructure/Persistence/Seeding/Data/Navigation/Navigation{Level}SeedData.cs

// Add static GUID field
public static readonly Guid {PascalCode}Id = Guid.Parse("{navigation_guid}");

// Add to GetSeedData() return array
new {
    Id = {PascalCode}Id,
    ParentFk = Navigation{ParentLevel}SeedData.{ParentPascalCode}Id,  // FK varies by level
    Code = "{code}",
    Label = "{labels.en}",
    Description = "{descriptions.en}",
    Icon = "{icon}",
    IconType = IconType.Lucide,
    Route = "/{full_path_with_slashes}",
    DisplayOrder = {display_order},
    IsActive = true,
    CreatedAt = SeedConstants.SeedDate
}
```

**FK property by level:**

| Level | FK Property | References |
|-------|-------------|------------|
| context | (none) | - |
| application | `ContextId` | NavigationContextSeedData.{Parent}Id |
| module | `ApplicationId` | NavigationApplicationSeedData.{Parent}Id |
| section | `ModuleId` | NavigationModuleSeedData.{Parent}Id |

**Option B: Project uses inline HasData**

If no SeedData class exists, add directly to `Navigation{Level}Configuration.cs`:

```csharp
// In Configure method, add:
builder.HasData(new {
    Id = Guid.Parse("{navigation_guid}"),
    // ... same properties as Option A
});
```

### F5. Write Translation Entries

Add 4 translation entries to `NavigationTranslationConfiguration.cs`:

1. Read the file to find the current highest `index` value
2. Continue from `index + 1`
3. Use the SAME `GenerateGuid` method already defined in the file:

```csharp
// In GetSeedData() method, add at the end before return:

// {level}: {code} translations
translations.Add(new {
    Id = GenerateGuid(index++),
    EntityType = NavigationEntityType.{Level},
    EntityId = Navigation{Level}SeedData.{PascalCode}Id,  // or Guid.Parse("{navigation_guid}")
    LanguageCode = "fr",
    Label = "{labels.fr}",
    Description = "{descriptions.fr}",
    CreatedAt = seedDate
});
translations.Add(new {
    Id = GenerateGuid(index++),
    EntityType = NavigationEntityType.{Level},
    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
    LanguageCode = "en",
    Label = "{labels.en}",
    Description = "{descriptions.en}",
    CreatedAt = seedDate
});
translations.Add(new {
    Id = GenerateGuid(index++),
    EntityType = NavigationEntityType.{Level},
    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
    LanguageCode = "it",
    Label = "{labels.it}",
    Description = "{descriptions.it}",
    CreatedAt = seedDate
});
translations.Add(new {
    Id = GenerateGuid(index++),
    EntityType = NavigationEntityType.{Level},
    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
    LanguageCode = "de",
    Label = "{labels.de}",
    Description = "{descriptions.de}",
    CreatedAt = seedDate
});
```

### F6. Store Result

```
{navigation_guid} = [generated GUID]
{seed_method} = "fallback"  // Indicates MCP was not used
```

### F7. Validation Checklist

Before proceeding, verify:
- [ ] Deterministic GUID generated (not NewGuid())
- [ ] 4 languages present (fr, en, it, de)
- [ ] Translation index continues existing sequence (no gaps, no collisions)
- [ ] Parent GUID correctly references existing entity
- [ ] Route path matches `/{context}/{app}/{module}` pattern
- [ ] DisplayOrder is consistent with existing entities
- [ ] Code is WRITTEN to files, not just displayed

### F8. Present Summary

```markdown
## Navigation Seeds Generated (Fallback)

**Entity:** {level} - {code}
**GUID:** {navigation_guid}
**Path:** {full_path}

### Files Updated

1. **Navigation{Level}SeedData.cs** (or Configuration.cs) - New entity entry
2. **NavigationTranslationConfiguration.cs** - 4 translation entries added
```

---

## 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`
