name	LAYER_10_NAVIGATION
description	Expert knowledge for Navigation Layer modeling in Documentation Robotics
triggers	["navigation","routing","route","flow","navigation guard","redirect","navigation flow"]
version	0.8.3

Navigation Layer Skill

Layer Number: 10 Specification: Metadata Model Spec v0.8.3 Purpose: Defines multi-modal navigation flows, routes, guards, and transitions between views.

Layer Overview

The Navigation Layer captures navigation and routing:

GRAPH - Top-level container for the entire navigation model (navigationgraph)
ROUTES - URL paths to views; types include public, protected, redirect, alias, lazy (route)
ROUTE METADATA - Auth requirements, layout, keepAlive metadata per route (routemeta)
BREADCRUMBS - Breadcrumb trail configuration per route (breadcrumbconfig)
GUARDS - Pre-navigation authorization/validation checks (navigationguard)
GUARD CONDITIONS - Boolean expressions evaluated by guards (guardcondition)
GUARD ACTIONS - Actions on guard failure: redirect, block, notify, prompt (guardaction)
FLOWS - Multi-step navigation sequences (navigationflow)
FLOW STEPS - Individual steps within a flow (flowstep)
TRANSITIONS - Directed transitions between routes with triggers (navigationtransition)
CONTEXT - Navigation-scoped context variables (contextvariable)

This layer uses Multi-Modal Navigation supporting web, mobile, voice, and other modalities.

Central Entity: The Route (URL path to view) is the core modeling unit.

Entity Types

CLI Introspection: Run dr schema types navigation for the authoritative, always-current list of node types. Run dr schema node <type-id> for full attribute details on any type.

Core Navigation Entities (11 entities)

Entity Type	Description
NavigationGraph	Top-level container representing the complete navigation model
Route	URL path mapped to a view; the core modeling unit
RouteMeta	Auth, layout, and lifecycle metadata attached to a route
NavigationGuard	Authorization/validation check executed before navigation
GuardCondition	Boolean expression evaluated by a navigation guard
GuardAction	Action taken when a guard fails (redirect, block, notify, prompt)
NavigationFlow	Multi-step navigation sequence
FlowStep	A single step within a navigation flow
NavigationTransition	Directed transition between two routes
ContextVariable	Navigation-scoped context data passed between routes
BreadcrumbConfig	Breadcrumb trail configuration for a route

Type Decision Tree

Use this decision tree before assigning a type to any navigation element.

Is this the top-level navigation model for an application?
  → navigation.navigationgraph.*

Is this a URL path/route that maps to a view?
  → navigation.route.*

Is this metadata about a route (auth requirements, layout, keepAlive)?
  → navigation.routemeta.*

Is this a breadcrumb configuration for a route?
  → navigation.breadcrumbconfig.*

Is this a guard that checks conditions before allowing navigation?
  → navigation.navigationguard.*

Is this a boolean expression/predicate evaluated inside a guard?
  → navigation.guardcondition.*

Is this the action to take when a guard fails (redirect, block, notify, prompt)?
  → navigation.guardaction.*

Is this a named multi-step navigation sequence (wizard, checkout, onboarding)?
  → navigation.navigationflow.*

Is this a single step within a navigation flow?
  → navigation.flowstep.*

Is this a directed transition between two specific routes with a trigger?
  → navigation.navigationtransition.*

Is this a context variable scoped to the navigation session?
  → navigation.contextvariable.*

When to Use This Skill

Activate when the user:

Mentions "navigation", "routing", "routes", "flows"
Wants to define URL paths or route guards
Asks about multi-step flows or navigation transitions
Needs to model navigation between screens
Wants to link navigation to UX views or business processes

Cross-Layer Relationships

Outgoing (Navigation → Other Layers):

view-ref → UX Layer (which view does this route show?)
business.realizes-process → Business Layer (what process does this flow realize?)
security.required-roles → Security Layer (authorization requirements)
apm.flow-metrics → APM Layer (navigation analytics)

Incoming (Other Layers → Navigation):

UX Layer → Navigation (views reference routes)
Business Layer → Navigation (processes trigger flows)

Design Best Practices

Guards - Add navigation guards for protected routes
Context - Pass necessary context between routes
Analytics - Track navigation flows for insights
Error handling - Define fallback routes for errors
Deep linking - Support deep linking for all routes
SEO - Consider SEO requirements for public routes
Performance - Lazy-load routes when appropriate

Common Commands

# Add navigation graph (one per application)
dr add navigation navigationgraph "My App Navigation"

# Add route (types: public | protected | redirect | alias | lazy)
dr add navigation route "User Profile Route" --description "User profile page route"

# Add route metadata
dr add navigation routemeta "Profile Route Meta"

# Add breadcrumb configuration
dr add navigation breadcrumbconfig "Profile Breadcrumb"

# Add navigation guard
dr add navigation navigationguard "Auth Guard"

# Add guard condition
dr add navigation guardcondition "Is Authenticated"

# Add guard action (on failure)
dr add navigation guardaction "Redirect To Login"

# Add navigation flow
dr add navigation navigationflow "Checkout Flow"

# Add flow step
dr add navigation flowstep "Cart Review Step"

# Add transition between routes
dr add navigation navigationtransition "Cart To Shipping"

# Add context variable
dr add navigation contextvariable "Cart ID"

# List by type
dr list navigation --type route
dr list navigation --type navigationguard

# Validate navigation layer
dr validate --layers navigation

# Export navigation map
dr export plantuml --layers navigation

Example: Protected Profile Route

id: navigation.route.user-profile
name: "User Profile Route"
type: route
properties:
  path: /profile/:userId
  view-ref: ux.view.user-profile
  guards:
    - navigation.navigationguard.authentication
    - navigation.navigationguard.profile-ownership
  parameters:
    - name: userId
      type: string
      format: uuid
      required: true
  meta:
    title: "User Profile"
    requiresAuth: true
    allowedRoles:
      - user
      - admin
  contextVariables:
    - name: currentUserId
      source: auth.user.id
  dataMapping:
    - source: route.params.userId
      target: view.data.userId
  security:
    required-roles:
      - security.role.authenticated-user
  business:
    realizes-process: business.process.profile-management
  apm:
    flow-metrics:
      - apm.metric.profile-view-count
      - apm.metric.profile-load-time

Example: Multi-Step Checkout Flow

id: navigation.navigationflow.checkout
name: "Checkout Flow"
type: navigationflow
properties:
  steps:
    - id: cart-review
      route: /checkout/cart
      view: ux.view.cart-review
      onNext: validate-cart
    - id: shipping-address
      route: /checkout/shipping
      view: ux.view.shipping-form
      onNext: validate-address
    - id: payment
      route: /checkout/payment
      view: ux.view.payment-form
      onNext: validate-payment
    - id: confirmation
      route: /checkout/confirm
      view: ux.view.order-confirmation
      final: true
  transitions:
    - from: cart-review
      to: shipping-address
      trigger: next-button
      guard: navigation.navigationguard.cart-not-empty
    - from: shipping-address
      to: payment
      trigger: next-button
      guard: navigation.navigationguard.valid-address
    - from: payment
      to: confirmation
      trigger: submit
      guard: navigation.navigationguard.payment-successful
  context:
    - cartId
    - selectedAddress
    - paymentMethod
  business:
    realizes-process: business.process.checkout

Coverage Completeness Checklist

Before declaring navigation layer extraction complete, verify each type was considered:

If any type has ZERO elements, explicitly decide: "This type doesn't apply to this codebase" with reasoning.

Pitfalls to Avoid

❌ Missing authentication guards on protected routes — use navigationguard + guardcondition + guardaction together
❌ Using navigation.guard.* or navigation.flow.* as element IDs — correct types are navigationguard and navigationflow
❌ Not decomposing guards into conditions (guardcondition) and actions (guardaction) — model these as separate elements
❌ Complex flows without explicit flowstep elements — each step in a flow should be a distinct flowstep
❌ Missing routemeta for protected routes — auth requirements belong in routemeta, not embedded in route properties
❌ Missing cross-layer links to UX views (view-ref) and business processes (realizes-process)
❌ No error/fallback routes defined — model these as route with type: redirect