Every page describes itself in data, so the nav and the assistant read the same words, and a page without a description doesn’t build.

The problem

An assistant that can take you somewhere, or tell you where you are, needs a sentence per page: what it shows and what you do there. In most apps that sentence lives nowhere. Titles are scattered across breadcrumbs, nav config and document titles. Route components are code, so nothing can read them without running the app.

You can write the sentences into a prompt instead. They rot there, because nothing makes anyone update them.

What I concluded

Make the description part of the page, and make it required.

A view file per route

Each route gets a sibling file that holds nothing but literal data:

// routes/orders/index.view.ts
export const view = defineView({
  kind: "page",
  title: "Orders",
  description: "Every order as a table, filterable by status, "
    + "customer and date. Open an order to refund it.",
  makes: ["report"],
  asks: ["Which orders are late?"],
});

A build plugin parses these files without running them and generates two maps: the structure, which ships with the app, and the text, which only the assistant needs and loads lazily.

  routes/**/*.view.ts ──parse──▶ nav titles, breadcrumbs, gates
                            ├──▶ the assistant's list of places
                            ├──▶ "you're on Orders: every order…"
                            └──▶ starters: [Generate report]

One sentence, written next to the route, feeds four things. The assistant’s sense of “where you are” and “where I can take you” comes from the words the person reads in the nav, so the two can’t disagree.

Required, not optional

Optional documentation goes stale. So the description is enforced at the one door everything passes through. The build fails if a route has no view file, if a view file has no route, or if a page has no title and description. The same rule applies to data: every query must say what it fetches, or it doesn’t compile.

  required view file on routes  ──▶ every place, and what it's for
  required description on query ──▶ what's on screen, in plain words
  required schema on search     ──▶ what can change on each page

Those three lists are what the assistant knows about the app, and nobody maintains them. They fall out of writing the feature.

Rules

  • Literal data only. No variables, calls or spreads in a view file. That restriction is what lets the build read it without running the app.
  • Enforce at the door. A lint rule can be disabled on one line. A required argument or a failing build can’t.
  • One door. There’s exactly one way to fetch and one way to register a route. A second way is a way to be invisible.
  • Write it for a reader. “Open orders for this customer”, not a function name.
  • Starters only show what’s real. A page’s makes becomes a button only if the app can render that kind right now.

What you get

The cheapest moment to describe something is the moment you write it, and this makes that the only moment there is. The nav, the assistant and a new teammate all read the same sentence.

Related: Screen context, Navigation, Layers.