Guidance Center

Why the Guidance Center is different

Most metadata surfaces describe data or structure. The Guidance Center describes how to operate the interface — and the interface is exactly the thing this platform refuses to fix in place. Guidance content is dense with UI instruction: “open the App Launcher (the waffle icon at the leading edge of the global header), choose the app, then the object’s tab, then New.” Every clause of that sentence depends on decisions an org makes: which shell/core is installed, which page template a surface uses, what icons and labels the org chose, and which packages are present.

Hand-authoring that content is therefore a trap. Written once against the CAOS Core shell, it is wrong the moment a customer installs a different core, swaps a page template, rebrands an icon, or removes a package. Guidance maintained in parallel with the UI drifts from the UI by construction — the same class of mistake the whole platform is built to avoid.

The principle: guidance is a projection of UI metadata

The engine already interprets an org’s metadata to render the interface. The proposal is to interpret the same metadata to describe how to operate it. Guidance stops being an authored copy of the UI and becomes a generated view of it, from the same source of truth, resolved at the moment it is shown.

To make that work, guidance content must be written against intent, never against pixels — and the platform must be able to resolve intent into the concrete, org-specific “where and what it looks like” on demand.

Deterministic-first, and the existing center is only inspiration

The design mandate is deterministic-first: if a piece of guidance cannot be generated by resolving metadata, it does not belong in the Guidance Center. The current, hand-authored guidance center is treated as inspiration for what topics matter and how they read — not as content to port. Anything in it that cannot be produced deterministically from the org’s own metadata is discarded rather than carried forward as a hand-maintained exception. This keeps the entire surface on one footing: everything the Guidance Center shows is a resolution of metadata, so nothing in it can drift from the UI.

The resolved output is best understood as a script written from the self-describing metadata — a single, machine-produced account of how this org’s UI actually works. That script is what gets rendered as the browsable Guidance Center, and it is the same script the AI reads when a user asks instead of browses (see the AI-first dimension, below). One script, two readers.

Separate the intent from its realization

A guidance topic is a sequence of semantic steps describing an intent — create a record of this object, find something, change a field on a record, reach setup for a feature — where each step references a UI anchor by capability role, not by position or appearance.

Intent (portable): “Open the list for object X, then use its New action.”
Anchors referenced: object-nav:X, record-action:new.
Realization (resolved at view time): the real label, the real icon the org uses, and a location phrased from the current template’s regions — “in the left navigation rail” or “along the top tab strip,” whichever the installed template actually renders.

The recipe never changes when the UI changes; only the resolved realization does.

The anchor model

An anchor is a stable, role-named handle onto a piece of the interface. Whatever package provides a surface registers its anchors, each carrying:

Field	Purpose
`role`	Stable capability id — `app-launcher`, `global-search`, `avatar-menu`, `app-nav-tab`, `record-tab`, `record-action:new`, `object-nav:<object>`, `setup-entry`, …
`label`	The human name the org shows (“App Launcher”).
`icon`	A reference to the same icon metadata the UI renders, so guidance shows the icon the user actually sees.
`region`	Which named layout region the anchor lives in (see templates, below) — the basis for the generated location phrase.
`selector`	Optional live target, so guidance can highlight or walk the real element on screen.

Anchors are the vocabulary guidance is written against. Because a customer’s own core registers the same roles (with their own labels and icons), guidance written against roles resolves correctly against any conforming core.

This is the shell contract, viewed from guidance

The Shell contract already requires a conforming shell to provide a known set of surfaces — app launcher, global search, avatar menu, navigation, record tabs, and so on. The guidance manifest asks that same shell to also describe those surfaces: their roles, labels, icons, and regions. The required-surfaces list and the required-anchors list are the same list. So a third party shipping its own core does not take on a separate guidance burden — satisfying the shell contract is registering the anchors guidance needs. If a core omits an anchor, guidance degrades gracefully for the steps that referenced it (see below), exactly as the UI would degrade if a required surface were missing.

Page templates declare named regions

The location half of every instruction — “top,” “left rail,” “record header” — must not be free text, or it cannot follow a template change. Instead, a page template declares its named regions (global-header, primary-nav, record-tabs, content, secondary-rail, …) and which anchors bind to which region. Guidance generates its location phrases from the region an anchor resolves into.

The consequence is the correct behavior when someone overrides the core template or picks a different one:

Move the record tabs from a top strip to a left rail → every guidance step that references record-tab:* regenerates its location phrase from the new region, with no change to any recipe.
Choose a single-page record template that has no record tabs → steps that reference record-tab:* resolve to “not applicable” and the engine omits or rewrites them (“this org shows the whole record on one page”), rather than instructing the user to click something that isn’t there.

The template is the source of truth for where; guidance reads it, never hard-codes it.

Two content layers

The Guidance Specification (kernel-level contract). The stable vocabulary every piece of guidance plugs into: the set of anchor roles, the set of region names, the step types (navigate, open, click, input, select, wait, explain), and the top-level intent taxonomy — getting around, working with records, AI assistance, setup & administration. This lives in the kernel because it is the contract; it changes rarely and everything else references it.
Package-contributed recipes (metadata). Each package ships guidance for its own features as recipes written against the vocabulary — never against pixels. Sales Atlas ships “create a quote” as semantic steps referencing object-nav:quote and record-action:new; Setup ships “grant a permission set” against its own registered anchors. The kernel resolves these against the installed shell, the active templates, and the org’s icons and labels at the moment the Guidance Center is viewed.

The resolution engine

At view time the engine composes: the requested recipes + the resolved anchors (label, icon, region) + the active template’s region layout + the org’s branding tokens → a rendered set of instructions specific to this org’s UI. It also reads the read-only describe layer to enumerate what actually exists — which apps, which objects, which packages — so structural guidance (“here are your apps and what each contains,” “to open any record type…”) is generated purely from metadata with no authoring at all. Missing-anchor and missing-region cases are first-class: the engine falls back, rewrites, or omits rather than producing a wrong instruction.

The AI-first dimension

There are three layers, increasing in intelligence:

Deterministic projection. The structural, navigational guidance — “how to get around,” “how to open or create a record of any object,” “where each app lives” — is a pure walk of the metadata graph (apps → objects → surfaces → anchors → regions). This is generated on view, needs no authoring, and is always correct because it is the same metadata the UI renders. For the “how to get around” content, this deterministic projection alone reproduces what a hand-authored guidance center provides.
AI-assisted authoring. For richer prose and task explanation, an AI layer takes the resolved anchors + recipes + org context and produces natural, org-specific instructions (correct icon names, correct locations). Authors write thin recipes; the AI renders them into fluent guidance per org.
Conversational unification. The Guidance Center and the AI assistant are the same knowledge in two presentations — one rendered as a browsable center, one answered conversationally. Both read the same deterministic script (above): the AI does not improvise a UI tour, it narrates the same resolution, then adds prose and dialogue on top. “How do I create a quote here?” is answered by resolving the same recipes and anchors against the live org. This is why the guidance, AI-chat, and report-a-bug surfaces share components: they are windows onto one resolved model of “how this org’s UI works.”

Interactive walkthroughs

Because anchors can carry a live selector, guidance can move from describing to doing: coach-marks and highlights that point at the real element on screen and step the user through a task. These stay correct across shell and template changes for the same reason the prose does — they resolve the anchor live rather than targeting a fixed position.

Feasibility

Structural / navigational guidance: highly feasible, and the strongest part. It is a deterministic projection of metadata the kernel already holds. This is buildable and delivers most of the day-one value.
Conceptual / domain guidance (“how should I price this?”): not derivable from UI metadata alone. It needs authored recipes or AI plus domain knowledge — but even these reference anchors, so their UI directions stay accurate.
What it requires building: (1) the guidance manifest contract as an extension of the shell contract; (2) named regions on page templates; (3) the guidance resolution engine in the kernel; (4) the Guidance Specification vocabulary (anchor roles, regions, step types, intent taxonomy).
Primary risk: a third-party core that registers poor or missing anchors yields poor guidance. Mitigation: the anchors guidance needs are the surfaces the shell contract already requires — so a conforming core registers them by definition, and non-conformance degrades guidance exactly where it degrades the UI.

Relationship to the rest of the platform

This design sits on three existing pillars rather than inventing a fourth: the Kernel hosts the Guidance Specification and the resolution engine; the Shell contract is the anchor registration; the Object Model describe layer supplies the “what exists” that structural guidance enumerates. Guidance is not a special-cased subsystem — it is what the platform’s own metadata looks like when projected as instruction.