# Building a page with embedded LightPane panes

The snippets below are the ones the LightPane console generates. If you
produce anything else, it will not work.

## First: three things only the person can get

You almost certainly cannot reach their LightPane console, so **ask them for
these and tell them where to find them**. Play the following back:

> **1. An access key.** In LightPane, go to https://app.lightpane.cloud → **Access keys** → *Create key*.
> Give it a name, and set its **allowed origin** to the exact site the page
> will be served from — scheme and host, e.g. `https://wiki.example.com`.
> Copy the key when it is shown.
>
> **2. An account handle.** Go to **Cloud accounts**. Each connected account
> has a short handle such as `sage-bluff`. Copy the handle for the account
> the page should show. A handle is deliberately not your cloud account
> number, so it is safe to put in a page.
>
> **3. A region** — the one your workload mostly runs in, e.g. `eu-west-2`.

Keep all three out of this conversation — see the warning at the end. Write
`YOUR_ACCESS_KEY`, `YOUR_ACCOUNT_HANDLE` and `YOUR_REGION` in anything you
produce and have them substitute the real values in their own editor. Use
those exact spellings — they are what the person will be told to search for.

## 1. The page header — once per page, at the TOP

Every page starts with this block, in `<head>`. It holds the only three
values that make the page live, so the person edits ONE place, never the
panes. Reproduce it exactly, comment included — the comment is how the
person learns to point a pane at another account or region later:

```html
<!-- ===== LightPane: the three values that make this page live ===== -->
<script>
  window.lpEmbed = {
    accessKey: "YOUR_ACCESS_KEY",      // LightPane console -> Access keys
    account:   "YOUR_ACCOUNT_HANDLE",  // LightPane console -> Cloud accounts, e.g. sage-bluff
    region:    "YOUR_REGION"           // e.g. eu-west-2
  };
</script>
<script src="https://lightpane.cloud/embed/lp.js"></script>
<!--
  These are the DEFAULTS for every pane on this page: one account
  (or subscription, or project) in one region.

  If your access key links to several accounts, subscriptions or
  projects, point an individual pane at one of them with that account's
  handle, from Cloud accounts in the LightPane console:
      data-lp-account="sage-bluff"

  Regional panes can also show different regions side by side - for
  example two EC2 panes, one with data-lp-region="eu-west-2" and one
  with data-lp-region="us-east-1".

  A pane whose data-lp-account or data-lp-region is empty ("") uses the
  default above.

  "region" is for AWS panes. On a page with GCP or Azure panes, add
  one default per cloud inside window.lpEmbed, e.g.
      regions: { gcp: "europe-west2", azure: "uksouth" }
  A GCP or Azure pane never uses an AWS region name. The full form of a pane:

    <div data-lp-service="ec2"
         data-lp-account="sage-bluff"
         data-lp-region="eu-west-2"
         data-lp-attributes="name,instance_type,state,availability_zone,launch_time"></div>
-->
```

- `accessKey`, `account` and `region` go in `window.lpEmbed`, **not** on the
  pane elements. `lp.js` waits for the page to finish loading before it
  looks for panes, so this block belongs at the top.
- `account` and `region` are **page defaults**. A pane whose
  `data-lp-account` / `data-lp-region` is absent or EMPTY uses them; a pane
  with its own non-empty value uses that instead.
- **Always set `account`.** Leave it out and every pane falls back to the
  access key's own default account, which changes if the key's grants
  change — the page would then show a different account with nothing on
  screen to say so.
- `region` is the page's region for **AWS** panes. Each cloud names its
  regions differently (AWS `eu-west-2`, GCP `europe-west2`, Azure
  `uksouth`), and a GCP or Azure pane never uses an AWS name. On a page with
  GCP or Azure panes, also set `regions`, one default per cloud:

  ```js
  window.lpEmbed = {
    accessKey: "YOUR_ACCESS_KEY",
    account:   "YOUR_ACCOUNT_HANDLE",
    region:    "eu-west-2",                                // AWS panes
    regions:   { gcp: "europe-west2", azure: "uksouth" }   // GCP, Azure panes
  };
  ```

  If `regions` is left out, a GCP pane uses its project's own region. A
  pane's own non-empty `data-lp-region` still wins, as long as it is a
  region of that pane's cloud.
- An older name for `account`, `accountAlias`, still works. Write `account`.

## 2. One container per pane — and there are TWO shapes

Pick by the pane's `kind` in [panes.json](https://lightpane.cloud/llms/panes.json). Give
every pane an EMPTY `data-lp-account=""`, and an empty `data-lp-region=""`
when its `region_scope` is `"regional"`. Empty means "use the page
default", so the page works as written — and the attribute is already
there when the person wants to point one pane somewhere else.

**`kind: "compound"`** — a composed pane. It needs its **`mount` class**:

```html
<div class="lp-cost-summary-panel"
     data-lp-pane="aws/cost-summary"
     data-lp-account=""
     data-lp-region=""></div>
```

**A compound pane without its mount class renders nothing at all.** The
class is the pane's `mount` field; `data-lp-pane` is `provider/slug`.

**`kind: "service"`** — one discovered service, addressed by `service_id`,
not by slug:

```html
<div data-lp-service="access_analyzers"
     data-lp-account=""
     data-lp-region=""></div>
```

Optionally add `data-lp-attributes="name,type,status"` to choose columns,
using values from that pane's `attributes` list. Service panes only.

Leave both attributes empty unless the person has asked for a specific
account or region on that pane. **Never put `YOUR_ACCOUNT_HANDLE` or
`YOUR_REGION` on a pane** — they belong in the header only.

## 3. Hand over a replacement table

Whatever you produce, finish with a table of every placeholder you used, what
it should be replaced with, and how many places it appears. Someone editing a
file you wrote cannot see which values you invented and which came from them.
With the header above, every placeholder is in ONE place:

| Placeholder | Replace with | Where |
|---|---|---|
| `YOUR_ACCESS_KEY` | their LightPane access key | 1 place, the page header |
| `YOUR_ACCOUNT_HANDLE` | their account handle, e.g. `sage-bluff` | 1 place, the page header |
| `YOUR_REGION` | the region their workload runs in, e.g. `eu-west-2` | 1 place, the page header |

## 4. Several accounts, or several regions, on one page

This is the thing LightPane is for, and it needs no special syntax — fill in
a pane's own attribute. The header's `account` stays the default for every
pane left empty:

```html
<h2>Production</h2>
<div class="lp-cost-summary-panel" data-lp-pane="aws/cost-summary"
     data-lp-account="swift-harbor" data-lp-region=""></div>

<h2>Staging</h2>
<div class="lp-cost-summary-panel" data-lp-pane="aws/cost-summary"
     data-lp-account="teal-summit" data-lp-region=""></div>

<h2>Microsoft Azure</h2>
<div class="lp-azure-cost-summary-panel" data-lp-pane="azure/cost-summary"
     data-lp-account="jade-brook"></div>
```

Note the third block: it is the **same pane on a different provider and its
mount class is different** (`lp-azure-cost-summary-panel`, not `lp-cost-summary-panel`). Always read
`mount` from the catalogue for the exact provider and slug — never assume it
follows from the slug.

Regions work the same way. The same regional pane twice, side by side:

```html
<div data-lp-service="ec2" data-lp-account="" data-lp-region="eu-west-2"></div>
<div data-lp-service="ec2" data-lp-account="" data-lp-region="us-east-1"></div>
```

One access key can cover several accounts if its grants allow. Handles in
these examples are illustrative; the real ones come from the person's
console, so only write one on a pane when they have given it to you.

## Four things that fail silently

**1. A compound pane with no mount class.** Nothing renders, no error.

**2. The allowed origin is matched exactly.** A key scoped to
`https://example.com` will not work on `https://www.example.com`, nor with a
trailing slash. This is the most common cause of "it worked locally".

**3. Pinned pane asset versions.** Pane scripts carry a cache token the
loader manages. Copy a versioned URL into the page and it is pinned to the
pane as it was that day — a hard refresh will not fix it. Always go through
the loader.

**4. Two panes sharing a target.** Panes are not singletons. The same pane
for two accounts needs two containers, each with its own handle.

## Tell the person how to OPEN the page you just wrote

The file you produce cannot be opened by double-clicking it. A page loaded
from disk has no web address — the browser sends `Origin: null` — and the
API returns no CORS headers for that, so every request dies in the browser
before it leaves. **This applies to mock data too**, so a correct page with
no key in it still looks broken when opened from disk. Any real address
works, localhost included; `null` is the only one that does not.

Say this unprompted — the person has no reason to expect it, and the failure
looks like something you got wrong. What to say depends on what you can
actually do, so take the first of these three that applies to you:

**If you can run commands in the environment the page will be opened from**,
do not give instructions. Start the server yourself and hand over the
address: `python3 -m http.server 8000` from the file's directory, then tell
them to open `http://localhost:8000/` plus the filename. Mention they can
stop it with Ctrl-C.

**If you can run commands, but somewhere else than where their browser is**
— a container, a remote host, WSL — say so and fall back to the next case.
Do not assume the two are the same machine.

**If you cannot run commands**, give both forms and let them pick. Do NOT
try to infer their operating system from the conversation and give only one:
a confidently wrong command is worse than two correct ones, and this costs
two lines.

```
cd <the folder containing the file>
python3 -m http.server 8000      # macOS and Linux
py -m http.server 8000           # Windows
```

Then open `http://localhost:8000/` (plus the filename, if it is not
`index.html`).

In every case: if their access key restricts allowed origins,
`http://localhost:8000` has to be one of them, exactly as written. Full
guide, for a person to read — Windows and Linux in detail, serving without a
terminal, checking it on a phone, and hosting options:
https://lightpane.cloud/build/viewing/

## These identifiers are stable

`provider`, `slug`, the `mount` class and `service_id` do not change once
published, and are never reused for a different pane. A page built today
will keep working, so it is safe to commit into a wiki, a docs repository or
a runbook that nobody revisits for a year.

Two caveats worth passing on:

- A pane can be **withdrawn**. Its container then stops rendering; the rest
  of the page carries on. Nothing breaks around it.
- The **access key** is the part that expires or gets revoked, not the
  markup. If a long-lived page stops showing data, check the key and its
  allowed origin before suspecting the panes.

## Never paste an access key into a chat assistant

An access key is a credential. Pasting one into an LLM session discloses it
to a third party and it may be retained. Build the page with the
`YOUR_ACCESS_KEY` placeholder and substitute it locally.

If a key is ever exposed, revoke it at https://app.lightpane.cloud → Access keys and issue a new one.

## If the page cannot run scripts

Confluence, Notion, SharePoint, wikis and ticket systems strip
`<script>`. There, embed ONE pane per URL as a frame instead:

```html
<iframe src="https://lightpane.cloud/embed/v1/?service=ec2&provider=aws&account=HANDLE#k=lp_ak_KEY"
        title="EC2 instances"
        style="width:100%;height:460px;border:0"></iframe>
```

- `service=<service_id>` for a service pane, `p=<slug>` for a compound
  pane. These are the ONLY two names the frame reads; anything else
  renders "Missing pane".
- The key goes after the `#`, never after the `?`. Browsers do not send a
  fragment to the server, so it stays out of server and CDN logs. It is
  NOT hidden — anyone who can see the page can read the URL, so scope the
  key to what that audience may see.
- Give the frame a height: an iframe cannot grow with its content.
  460px suits an inventory pane, 600px+ a compound pane.
- Prefer the script embed wherever scripts are allowed. One frame per
  pane means one runtime load per pane.

## What a pane will and will not do

Panes are **read-only**: they display cloud state and never change it.
LightPane is a visibility tool, not a monitoring or alerting system, and
should not be relied on as the sole means of detecting an incident.

Data freshness depends on the plan — see [pricing](https://lightpane.cloud/pricing.html).
