Whole-Asset Overview

The problem this solves

Ask a document-retrieval system "what does this machine do?" and it does the wrong thing. It retrieves chunks, ranks them, and answers from whichever subsystem happened to score highest. You ask about the generator set and get a paragraph about the fuel filter, because the fuel filter section matched best.

The question was asked at whole-asset altitude. The answer came back at subsystem altitude. That mismatch is invisible in retrieval metrics — the chunk was relevant, the citation is real, the answer is grounded — and obvious to any technician reading it.

Planara handles altitude explicitly.

The asset overview

During onboarding, Planara generates a short, page-cited description of the whole asset and its major subsystems, and stores it on the tenant configuration.

It is not marketing copy and it is not model recall — it is generated from the ingested corpus and carries page citations, the same as any other answer. For a diesel generator set, it reads roughly like:

The Onan HDKA-series is a diesel generator set — an engine-driven AC power
source for mobile and stationary use. Its major systems are: (1) ENGINE — a
3-cylinder, water-cooled, indirect-injection, 4-stroke diesel; (2) GENERATOR /
ALTERNATOR — a permanent-magnet alternator that produces the AC output;
(3) CONTROL-INVERTER — an integrated microprocessor-based unit managing
control, monitoring, and diagnostics; (4) COOLING; (5) FUEL — with electronic
governor; (6) STARTING / ELECTRICAL — 12 V DC battery-started. It produces
60 Hz output and runs at roughly 1600-3300 RPM depending on model
(TABLE 1, Diesel Model Specifications, p.19).

This is injected on conceptual and overview turns, so the model leads from a whole-asset frame instead of fixating on whichever chunk ranked first.

It also fixes assistant identity

The same overview drives the assistant's self-description. Planara derives a short noun phrase for the tenant's equipment from the overview's subject, so the assistant says "service assistant for the Onan diesel generator set" — never a hardcoded or wrong vertical. A marine tenant is never told it is talking to a marine assistant because someone forgot to change a config value; the description comes from the corpus.

Scaling to a facility

A single asset is the simple case. The hard case is a site with many machines: a plant, a vessel with several systems, a facility with multiple production areas.

The naive approach — inject a description of everything — fails immediately. Context grows linearly with the number of machines, and a large facility overruns the window.

Planara models the site as a tree:

facility ── area ── machine ── (subsystem chunks = normal retrieval)

The whole tree is never injected. Exactly one node is — the node at the altitude of the question. Injected context is O(1) per turn regardless of how many machines the facility has. A facility with 3 machines and a facility with 300 inject the same amount of context, because the facility is never loaded; one node is.

Altitude routing

A router picks the node before retrieval runs. It is pure functions — regex and set membership, no model call — so it is cheap and unit-testable, and it does not sit on the critical path.

It returns one of three modes:

The distinction between clarify and fan_out is the one that matters. Both involve more than one candidate machine, but they are different questions:

• "What does it do?" with three machines present is ambiguous. The technician means one specific machine and the system does not know which. Fanning out and describing all three is a worse answer than asking which one.
• "Which of these run on diesel?" with three machines present is plural. The technician means all three. Asking "which machine do you mean?" would be obtuse.

Guessing on the first case produces a confident answer about the wrong unit — which, on a live site, is a safety problem, not a UX problem. See Honest limits for how clarifications are typed in the API.

Resolving "it"

The router resolves referential questions against the conversation's active node — the machine or area the technician is currently working on, which the engine already tracks as equipment scope. If the technician has been asking about the starboard engine for four turns and then asks "what does it do", that resolves without a clarification. Only a genuinely unanchored reference triggers one.

How this shows up in the API

Clarifications produced by the altitude router are typed like any other clarification — response_type: "needs_clarification" with the candidate machines in the clarification.options array, labelled with clean machine names so the technician can pick the right unit at a glance. See Widget API.

Fan-out answers run asynchronously and off the interactive path.

Setup

The overview and hierarchy are generated during onboarding — no manual authoring required. For an existing tenant, they can be regenerated from the current corpus at any time, which is worth doing after ingesting a document that adds a machine or a major subsystem.

Because the overview is corpus-derived and page-cited, it inherits the corpus's limits: if the documentation does not describe a subsystem, the overview will not invent one.

Related

• Platform Overview — where the overview sits in the pipeline
• Equipment Scoping — how retrieval is scoped to a specific model
• Conversation Intelligence — active-equipment tracking that resolves "it"
• Customer Onboarding — the stage that generates it