Sitemap Configuration

The sitemap is a JSON structure that describes your application to the AI. It tells Navieo what routes exist and what interactive elements are on each page.

How the Sitemap Is Generated

When you click Scan Codebase in the Navieo dashboard, Navieo reads your source code via the GitHub API and automatically generates the sitemap. You don't need to write or maintain this file manually.

The scan produces a .navieo/sitemap.json file in your repository (via Pull Request) that looks like this:

{
  "appId": "my-app",
  "framework": "nextjs",
  "generatedAt": "2026-02-15T00:00:00Z",
  "routes": []
}

See GitHub Integration for the full scanning workflow.

Routes

Each route describes a page and the interactive elements on it:

{
  "routes": [
    {
      "path": "/dashboard",
      "title": "Dashboard",
      "description": "Main dashboard with project list and stats",
      "elements": [
        {
          "id": "create-project",
          "type": "button",
          "text": "Create Project",
          "selector": { "cssSelector": "#create-project" },
          "description": "Opens the new project creation dialog"
        },
        {
          "id": "nav-settings",
          "type": "link",
          "text": "Settings",
          "selector": { "cssSelector": "nav a[href='/settings']" },
          "description": "Navigation link to the settings page"
        }
      ]
    }
  ]
}

Element Types

Type	Description
`button`	Clickable button element
`link`	Navigation link (`<a>` tag)
`input`	Text input field
`select`	Dropdown select element
`text`	Informational text or section

Selector Strategies

Each element has a selector object describing possible DOM addresses. Dynamic guidance requires unambiguous correspondence and exact runtime-target revalidation; a broad selector's first match is not sufficient authority. Authored-tour selector resolution remains a separate reviewed playback path.

{
  "selector": {
    "cssSelector": "#create-project",
    "ariaLabel": "Create new project",
    "text": "Create Project"
  }
}

Field	Maps to	Runtime?	Notes
`cssSelector`	CSS selector lookup	Yes	Must resolve to the correct actionable control; ambiguity does not grant permission
`ariaLabel`	`[aria-label="value"]`	Yes	Maps to the HTML `aria-label` attribute
`text`	—	No	Metadata only — used by the AI for context, not for DOM lookup

Important: At least one of cssSelector or ariaLabel must be present for the SDK to find the element at runtime. The text field alone is not sufficient — it's metadata only.

Here are selector strategies ranked by reliability:

Strategy	Example	Stability
`id` attribute	`"#create-app-button"`	Best — unique, survives layout changes
Semantic selector	`"aside a[href='/docs']"`	Great — uses meaning, not position
`aria-label`	`"[aria-label='Create new project']"`	Good — accessible and stable
Structural selector	`"main > section:nth-of-type(2)"`	Fragile — breaks if layout changes
Class-based selector	`".bg-blue-600.text-white"`	Fragile — breaks with any styling change

Product-code boundary: Build ordinary accessible application markup, not Navieo-specific targeting hooks. The scanner uses IDs, links, roles, accessible labels and framework structure. Owner safety declarations are distinct: the supported data-navieo-navigation-intent="exclude" annotation becomes element-level guidancePolicy: "exclude" and prevents a dynamic executable edge. Live capture and revalidation also enforce denial. See Live Guidance & Privacy.

Destination names and live evidence

For live guidance, titleSource records page metadata, a proven native/component heading, layout metadata or path fallback. Page metadata wins, then a proven page-level h1. Section headings are not page identity. Layout-only title text can remain stored for context while display identity falls back to the route path. Missing provenance is unknown, not trusted page metadata. Description provenance is recorded separately.

The sitemap still indexes destinations, goals, access and owner policy. It is not the complete current-page inventory: the SDK observes supported controls live. An eligible visible same-origin link to an indexed destination can be guided without its own scanner edge. Google uses bounded approved context; neither a better label nor a high relevance score can override exclusions, freshness, identity or access checks. Rescans can change graph revisions and invalidate old navigation sessions. Use Scan Codebase after changing routes, then start a new guide rather than editing generated navigation records by hand. See release compatibility for SDK availability.

Route Visibility

Control which routes are included in the knowledge base and where the widget appears:

{
  "path": "/admin",
  "title": "Admin Panel",
  "description": "Internal admin panel",
  "elements": [],
  "visibility": {
    "indexed": false,
    "widgetVisible": false
  }
}

Field	Description
`indexed`	If `false`, route is excluded from the knowledge base
`widgetVisible`	If `false`, the chat widget is hidden on this route

You can also configure visibility from the Navieo dashboard.

Docs

Contextual documentation that helps the AI understand your application. Place markdown files in .navieo/docs/ in your repository:

.navieo/
  docs/
    getting-started.md
    billing.md
    team-management.md

These are synced automatically when you push to GitHub (if the GitHub integration is connected). You can also create and edit docs from the dashboard's Docs editor.

Tips

Keep product code independent — treat a missing safe selector as a scanner limitation; Navieo never inserts product instrumentation
Re-scan after major UI changes — click "Scan Codebase" in the dashboard to refresh your sitemap
Enrich with AI — click "Enrich with AI" after scanning for richer element descriptions
Build authored tours — create and review saved steps manually or with visual authoring
Include docs — contextual documentation helps the AI answer "why" questions, not just "how"