# Pages — Hosted HTML

A **Page** is a single-file HTML document that Briefs hosts at a stable URL, with the same sharing and permission model as a Brief. Where a Brief is markdown knowledge for an AI agent to read, a Page is rendered, interactive HTML for a person to look at — a dashboard, a styled report, a chart, a visual explainer, a one-pager.

Pages and Briefs are siblings: same owners (`username/name` or `org/name`), same visibility levels, same collaborators — just a different content type. If you already know Briefs, you already know how Pages are shared and permissioned.

## When to create a Page instead of a Brief

Decide by the medium:

- **Page** — the user wants something **visual or interactive** that an agent produced as a single HTML file: a data dashboard, a styled report, an interactive chart, a landing/one-pager.
- **Brief** — the value is **knowledge or context** in markdown for an agent to consume.

Rule of thumb: if you find yourself putting a whole HTML document inside a Brief, it should be a Page.

## Single-file only

A Page is exactly one HTML document. Inline everything — CSS in `<style>`, JavaScript in `<script>`, images as `data:` URIs. External CDN references work but are the author's choice (nothing but the one HTML file is hosted by us). There are no companion files: this is single-file hosting, not a multi-file website.

## URLs — one link to share

**The link to a Page — the one you share and hand to users — is its web URL:**

```
https://sharebriefs.com/{owner}/pages/{name}
```

That URL works for everyone and every visibility: a public Page renders for anyone; a private or internal Page prompts sign-in and renders only for people with access. Viewers get the live page with light controls (copy link, a distraction-free full view, and fullscreen), and owners reach settings from there. Always share this URL — never construct links on the raw `pages.sharebriefs.com` host (that origin is an internal serving detail: it only serves public Pages and 404s everything else).

The rest of the URL scheme, GitHub-style:

```
https://sharebriefs.com/pages                    → the signed-in user's own Pages
https://sharebriefs.com/orgs/{orgname}/pages     → an organization's Pages
https://sharebriefs.com/{owner}/pages/{name}/settings → visibility, collaborators, delete
```

Note the three-segment item path: `sharebriefs.com/{owner}/pages/{name}` is a Page, while two-segment `sharebriefs.com/{owner}/{name}` is always a Brief (this very document is the Brief `briefs/pages`).

## How rendering stays safe (background)

A Page runs arbitrary scripts, so the HTML itself executes only on an isolated origin (`pages.sharebriefs.com`) and the app embeds it in a sandboxed frame — a Page can never read a signed-in user's session. Private and internal Pages are delivered through short-lived signed URLs after an access check. None of this changes what you share: the `sharebriefs.com/{owner}/pages/{name}` URL handles all of it.

## Permissions (same as Briefs)

- `public` — anyone with the link can view.
- `private` — owner, org admins, and collaborators only.
- `internal` — any member of the owning org.

Collaborators, permission levels (`read`/`write`/`admin`), and invitations work exactly as for Briefs — see https://sharebriefs.com/brief/sharing.

## Creating and managing Pages

Over the MCP (snake_case tools, parallel to the brief tools): `create_page`, `get_page`, `update_page`, `delete_page`, `list_pages`. `create_page` takes the HTML as `content`, an optional `name` (generated from the `<title>` or `<h1>` if omitted), an optional `owner` (org namespace, else the user's own), and `visibility`.

Over REST, the endpoints mirror Briefs under `/pages/...` (create, get, update, delete, list, plus a `render-url` for private delivery) — see https://sharebriefs.com/brief/api.

API and MCP responses return the shareable web URL as `url` — hand that field to users as-is. The raw public render origin is returned separately as `renderUrl` (public Pages only; you rarely need it).

An account needs a username before it can create Pages (same onboarding as Briefs; until then, create tools return an error pointing to https://sharebriefs.com/onboarding).

## Limits

A Page's HTML is capped at 5 MB. Full limits: https://sharebriefs.com/brief/limits.

## Agent workflow

1. Decide Page vs Brief by the medium: rendered visual → Page; markdown knowledge → Brief.
2. `list_pages` for the target owner before creating, to avoid duplicates.
3. Create the Page with a clear, URL-friendly name; hand the user **`https://sharebriefs.com/{owner}/pages/{name}`** — the same link works whether the Page is public, private, or internal.
4. Update in place over time — the URL is the stable contract, so prefer `update_page` over making a new Page.

## Related

- Concept overview: https://sharebriefs.com/brief/intro
- Sharing & permissions: https://sharebriefs.com/brief/sharing
- REST API: https://sharebriefs.com/brief/api
- MCP server: https://sharebriefs.com/brief/mcp
- Limits: https://sharebriefs.com/brief/limits
- Docs index: https://sharebriefs.com/brief/index