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

# Page Context for the Assistant

> Let a page in your app tell Starcat what it's showing and how to help—so users get on-target answers without explaining the screen

<Warning>
  **Experimental.** Page context is new and still evolving. The hook and behavior described here
  work today, but details may change. If anything looks off, [contact
  us](mailto:support@stardeck.ai).
</Warning>

When someone opens your app inside Stardeck, [Starcat](/starcat) sits in a sidebar next to it and can already see the page's address and title. Page context lets a page hand Starcat more: a short label for what's on screen, structured details, and instructions for how to help on this page—so the user can ask "remind this customer about their overdue invoice" without first describing what they're looking at.

This is a developer feature. You add it in your app's code (or ask the agent to), and it only has an effect when your app runs inside the Stardeck shell. Outside the shell it does nothing, so the same code is safe to ship everywhere.

## What It's For

A few examples of context a page might declare:

* An invoice detail page sets the label to `Invoice #1042 (overdue)` and instructs Starcat to offer drafting a payment reminder.
* A customer record page shares `plan: pro, MRR: $240, 14 days overdue` as details, so answers reference the real numbers.
* A dashboard tells Starcat which metric the user is focused on and what actions make sense from here.

## Adding It

Page context is set with the `useStardeckPageContext` hook from `@stardeck-customer-apps/client-utils` (included in every app). Call it from any page or component and pass what you want Starcat to know:

```typescript theme={null}
import { useStardeckPageContext } from "@stardeck-customer-apps/client-utils";

function InvoicePage({ invoice }) {
  useStardeckPageContext({
    label: `Invoice #${invoice.number}${invoice.isOverdue ? " (overdue)" : ""}`,
    details: `amount: ${invoice.amountFormatted}; status: ${invoice.status}`,
    instructions:
      "This page is about a single invoice. If it's overdue, offer to draft a payment reminder email to the customer.",
    suggestedPrompts: [
      {
        label: "Draft a payment reminder",
        prompt: "Draft a friendly reminder email for this overdue invoice.",
      },
      { label: "Summarize this invoice", prompt: "Summarize this invoice and its payment status." },
    ],
  });

  return /* ...your page... */;
}
```

Every field is optional:

| Field              | What it's for                                                                                                                                      |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label`            | A short, human-readable name for what's on screen. Shown to the user in the indicator.                                                             |
| `details`          | Structured facts about the page (amounts, status, IDs) that answers can reference.                                                                 |
| `instructions`     | Guidance on how to help on this page.                                                                                                              |
| `suggestedPrompts` | Example questions shown as one-tap buttons. Each is `{ label, prompt }`—`label` is the button text, `prompt` is the message sent to the assistant. |

The context updates whenever the values change and clears automatically when the user navigates away from the page or the component unmounts. Pass `null` to clear it yourself.

## What the User Sees

Page context is visible, not hidden. Whenever a page is sharing context, an indicator appears—in the app shell header when your app is open, and in the sandbox preview toolbar while you build. The user can click it to see exactly what the page is sharing: the label, details, instructions, and any suggested prompts. Nothing is sent to the assistant that the user can't inspect.

In the app shell, the suggested prompts are **one-tap buttons**: tapping one opens Starcat and asks that question for the user. (In the sandbox preview they show as plain examples, since there's no assistant attached to the preview.) Use them to point people at the most useful things to ask on each page.

## How the Assistant Uses It

The context is attached to the user's next message and given to Starcat as background on what they're looking at. Instructions are treated as advice from your app, not as commands—Starcat considers them but won't follow page-supplied text that conflicts with its own rules. Use them to steer toward helpful actions, not to try to override how the assistant behaves.

## Common Questions

**Does this work when my app runs on its own domain, outside Stardeck?**
The hook only has an effect inside the Stardeck shell. On a standalone deployment it's a no-op, so you can leave the calls in place.

**Will old versions of my app break?**
No. Page context is additive. Apps that haven't been updated simply don't send it, and the indicator stays hidden.

**Can the user turn it off?**
The user always sees what's being shared via the indicator and can read it in full. The page decides what to share; the platform makes it transparent.

**Is the page's full text shared too?**
That's a separate, user-controlled feature: the **Include current page content** toggle in the Starcat sidebar. Page context is what your page declares on purpose; page content is the on-screen text the user opts to share per message. See [Starcat](/starcat).