> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puntego.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hints, suggestions, release feeds, and progress badges

> Author lightweight Experience presentations without giving up server targeting, immutable releases, accessibility, or governed engagement analytics.

Puntego models hints, release feeds, and progress badges as presentations of
existing Experience behavior. They use the same audience, route, schedule,
frequency, revision, deployment, and engagement contracts as every other
Experience. They do not create parallel content stores or executable host
slots.

## User-opened hints

Choose **Nudge → User-opened hint** when a customer should discover help beside
one declared product control without entering an ordered Tour. A hint requires
a stable Target ID. CSS selectors, arbitrary URLs, HTML, and JavaScript are not
accepted.

The embed first renders a 44 px target-adjacent marker. The customer opens the
hint explicitly, can close the disclosure with its marker or `Escape`, and can
then run the one reviewed Nudge action. Closing the disclosure does not dismiss
the Experience; the separate dismiss control records a dismissal.

```ts theme={null}
const content = {
  kind: 'nudge',
  presentation: 'hint',
  targetId: 'billing_settings',
  placement: 'bottom_right',
  title: 'Billing settings',
  body: 'See what changes before updating your billing settings.',
  tone: 'info',
  dismissible: true,
  action: {
    type: 'open_widget',
    label: 'Show me',
    prompt: 'Explain these billing settings and point at the relevant control.',
  },
};
```

Each hint is independently targeted and revised; it is not a numbered Tour
step. Puntego still applies workspace priority and collision rules when
multiple Experiences are eligible.

## In-product release feeds

Choose **Announcement → Release feed** to show a short dated changelog inside
the customer's product. A feed contains 1–12 entries in the authored order.
Each entry has a stable ID, title, RFC 3339 publication timestamp, summary, and
an optional 40-character badge.

```ts theme={null}
const content = {
  kind: 'announcement',
  presentation: 'release_feed',
  title: 'What’s new',
  body: 'Review the latest improvements available in your workspace.',
  tone: 'brand',
  dismissible: true,
  releases: [
    {
      id: 'verified_receipts',
      badge: 'New',
      publishedAt: '2026-07-17T12:00:00.000Z',
      title: 'Verified action receipts',
      summary: 'Completed actions now finish with a durable receipt.',
    },
  ],
  action: { type: 'open_widget', label: 'Ask about these updates' },
};
```

The built-in runtime renders a semantic ordered list with `<time>` metadata,
bounded scrolling, long-copy wrapping, keyboard focus, reduced-motion support,
and host theme tokens. The optional Announcement action remains the only
interactive feed action, so it uses the existing proof-bound action policy.

## Resumable progress badges

Choose **Checklist → Progress badge** for durable progress that should remain
visible without occupying a full panel. The runtime initially shows a compact
badge with the checklist title and exact completed/eligible count. Activating
it opens the full Checklist; activating it again or pressing `Escape` collapses
it without losing progress.

Progress badges retain every Checklist capability:

* trusted host-event or explicit item completion;
* server-evaluated step audiences;
* visitor, signed-customer, or signed-account state;
* carried progress across compatible revisions;
* terminal completion reconciliation and retry;
* carousel-independent keyboard and screen-reader semantics.

## Launcher suggestions

Choose **Suggestion** to offer one question as a chip beside the guide
launcher. A suggestion has only a label (up to 60 characters) and a prompt (up
to 500): the label is what visitors see, and the prompt is what the guide is
asked when they pick it. The guide answers right away, in the answer card or
with a tour already on its first step; there is no "Start tour" step in
between. The answer card opens with the answer, and keyboard focus stays where
the visitor left it.

```ts theme={null}
const content = {
  kind: 'suggestion',
  title: 'Invite a teammate',
  prompt: 'Show me how to invite a teammate to this workspace.',
};
```

The prompt runs as the visitor's own question. It steers the answer and can
never authorize an action a visitor typing the same words could not.

Suggestions use the same route, audience, schedule, trigger, revision, and
translation contracts as every other Experience, with two limits of their own:

* **One at a time.** The Worker offers at most one suggestion per page view,
  the highest-ranked eligible one, and the runtime never replaces a dismissed
  chip with another on the same page.
* **Inside the annoyance budget.** A suggestion shows at most once per
  session, twice per day and ten times per visitor, with at least 60 minutes
  between showings; a definition outside these caps does not save. The chip
  also waits while the visitor is typing, reading an open panel, running a
  turn or tour, or has muted proactive help.

The chip never takes focus. Its × (or `Escape`) dismisses it and retires it for
that visitor; picking it retires it too. The guide editor previews a suggestion as the
real chip by the real launcher on a sample page.

## Engagements and analytics

These presentations do not invent presentation-specific counters. The Worker
records the same signed, idempotent events against the immutable deployment:

| Surface | Governed events |
| - | - |
| Hint | `impression`, `action`, `dismissed` |
| Release feed | `impression`, `action`, `dismissed` |
| Progress badge | `impression`, item `completed`, terminal `completed`, `dismissed` |
| Suggestion | `impression`, `action` (picked), `dismissed` |

Opening or collapsing a hint or progress badge is local disclosure state and
does not inflate engagement rates. Guide analytics continue to group accepted
events by Experience and immutable revision.

## Headless rendering

Headless snapshots expose the same typed presentation values and release entry
fields. A custom renderer owns visual disclosure state, but it must call the
existing headless engagement methods for impressions, actions, dismissals, and
Checklist completion. Match proofs and ineligible audience data remain private
inside the SDK.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.