# Data scope and permissions

A connected AI app sees exactly what your FranchiseSEE login sees, and nothing more. The address
you connect to never grants extra access: connecting the admin server doesn't let you make changes
your account can't make, and the admin server is for HQ accounts only.

## What the app can see

### HQ (franchisor) accounts

An HQ account sees the **whole brand**: every location, with named rankings, network averages and
every store's figures.

### Franchisee accounts

A franchisee sees **their own stores in full**: every metric, trend and report, for each store
assigned to them. When a tool says "network", it means *your* stores.

For the rest of the brand, a franchisee sees **group figures only, never another store**:

- **Where you stand.** `get-network-leaderboard-summary` gives your store's rank ("14th of 115"),
  percentile, the network mean and median, and how many stores improved or declined.
- **One peer group at a time.** The `compare_to` option on `get-network-leaderboard-summary`,
  `get-network-metric-summary` and `get-metric-trendline` compares you with one group: the whole
  brand, a district, a state or a store format, even one your stores aren't in. You get the
  group's count, mean, median and quartiles, and where your store sits among them.
- **Whole districts.** `whole_districts` on `compare-districts` values each district over all of
  its stores, not just yours.
- **Menu benchmarks.** The item tools give the network's average check penetration and attach
  rates, naming no store.

A group figure is shown only when **at least five stores you don't run** have data in it, and is
withheld when it could be subtracted from other figures to reveal a smaller group. A withheld
answer says so; choose a larger group.

No tool ever gives a franchisee another store's name or numbers. Named, store-by-store rankings
live on the FranchiseSEE leaderboard in the web app.

### How tools differ by account

Every reporting tool works for both kinds of account. These answer differently:

| Tool | HQ account | Franchisee account |
|------|------------|--------------------|
| `get-leaderboard` | The whole brand, ranked | Only your stores. For network standing use `get-network-leaderboard-summary` |
| `get-network-metric-summary` | Whole-brand total, mean and median | Your stores' aggregate, plus one peer group with `compare_to` |
| `get-network-leaderboard-summary` | Standing for one named store | Your stores' standing against the network, anonymized |
| `get-metric-snapshot`, `get-location-performance` | Value and benchmark, plus rank and network mean/median | Value and benchmark only |
| `compare-locations` | Any stores | Only your stores |
| `compare-districts` | Every district | Districts with your stores, or whole districts with `whole_districts` |
| `get-competition-standings` | Every competing store | Your stores' standings |
| `get-insights` | Store and network insights | Insights for your stores |
| `get-risk-findings` | Every flag, with tiers | Your stores' flags, without tiers |
| `get-goal-progress` | Every goal | Your stores, with anonymized network context |

Everything else returns the same shape for everyone, computed over the stores you can see.

## What the app can do

- **Signed in:** always **read-only**, and the reporting server only, whatever your account can do
  in the web app. See [Connect by signing in](https://franchisesee.com/docs/ai/sign-in.md#what-a-signed-in-app-can-do).
- **With an API token:** what your account can do, limited further by the token's permissions.
  Changes go through the admin server, which is for HQ accounts only, and need the matching account
  permission. Franchisee tokens are always read-only and reach the reporting server and the REST
  API. Through the API, a franchisee's user list shows the same people the web app does: the users
  at their own location, or only themselves if they reach their stores through location groups.
  See [Connect with an API token](https://franchisesee.com/docs/ai/api-tokens.md).

Apart from changes made through the admin server, the one thing a connection may write is a
`report-tool-issue` note: when a tool can't answer,
your AI app can tell FranchiseSEE what was missing. It holds no store data and changes nothing you
can see.

## Brand switches for HQ admins

AI connections are turned on per brand. Once they are on, HQ admins control franchisee access on
the **Connect your AI** page, under *For HQ admins*:

| Switch | When it's on | Turning it off |
|--------|--------------|----------------|
| Let franchisees connect AI apps | Franchisees can connect by signing in; their apps see only their own stores, read-only | Disconnects every app a franchisee connected by signing in. Personal tokens aren't affected |
| Let franchisees create personal tokens | Franchisees can create read-only, expiring tokens for scripts and token clients | Deletes every token a franchisee made; scripts using them stop working |

HQ accounts' own tokens keep working whatever these switches say.

## Staying in control

- **See your connected apps.** Under the profile menu, **User settings**, then **Connected apps**,
  you see every app connected to your account and the latest reports each one pulled.
- **Disconnect any app at any time** from the same page.
- **What FranchiseSEE keeps.** For each lookup, FranchiseSEE keeps which report, stores and dates
  were read, for 90 days, not your question. The exception is a `report-tool-issue` note: when
  your AI app files one, it describes what it was trying to do, and FranchiseSEE keeps that note
  so the team can close the gap.
- **Your chats stay in your AI app.** FranchiseSEE never sees your conversations with Claude or
  ChatGPT. The AI provider's own privacy terms cover them.