This is the full developer documentation for Brand Portal # Portal Docs > A GitHub-backed WYSIWYG site builder for brand guides and asset libraries. [Editor Guide ](/editor/getting-started/your-brand-portal/)Edit your brand portal: text, sections, media, audiences, and publishing — no code. [Developer Docs ](/developer/overview/what-the-portal-is/)Provision and run a client site, or work on the framework packages and internals. # For AI agents > Orientation for a coding agent doing development on the portal framework or a client site. This page orients a coding agent that has been pointed at a Brand Portal codebase. If you are a human, [What the portal is](/developer/overview/what-the-portal-is/) and [Architecture](/developer/overview/architecture/) are a better start. ## Ingest the whole docs in one request [Section titled “Ingest the whole docs in one request”](#ingest-the-whole-docs-in-one-request) This site publishes the [llms.txt](https://llmstxt.org/) standard: * [**`/llms.txt`**](/llms.txt) — a structured index of every page, with links and one-line summaries. * [**`/llms-full.txt`**](/llms-full.txt) — the entire documentation set concatenated as one Markdown file. Fetch this to load all developer and editor docs into context at once. ## Which codebase are you in? [Section titled “Which codebase are you in?”](#which-codebase-are-you-in) Two very different contexts share these docs — identify yours first: 1. **A client site repo** (e.g. `acme-portal`) — content and configuration only; the framework comes from the published `@drawnagency/*` packages. Most “build or run a site” tasks live here. Start with [Building a client site](/developer/building-a-client-site/provisioning/). 2. **The framework monorepo** (`Drawn-Agency/portal`) — the six published packages (plus the private `@drawnagency/platform`) and the dev, admin, docs, and MCP-connector apps. Start with [Monorepo & dev workflow](/developer/framework-internals/monorepo-and-dev-workflow/). ## Rules that will bite you if you ignore them [Section titled “Rules that will bite you if you ignore them”](#rules-that-will-bite-you-if-you-ignore-them) * **Use pnpm.** The monorepo enforces it with a `preinstall` `only-allow pnpm` hook; client repos are pnpm-based too (`.npmrc` + committed lockfile) but without that hook. Either way `npm`/`yarn` break the setup — always use pnpm. * **The editor import chain must be browser-safe.** `portal.config.mjs` and `src/sections.ts` are bundled into the hydrated editor island. No `node:*`, `Buffer`, server adapters, or unguarded `process.env`. See [Building custom sections](/developer/framework-internals/building-custom-sections/) and [SSR / Netlify gotchas](/developer/framework-internals/ssr-netlify-gotchas/). * **Publish packages via `scripts/publish.sh` (which uses `pnpm publish`), never `npm publish`.** npm publishes `workspace:*` dependencies literally and silently breaks every consumer install. See [Publishing packages](/developer/framework-internals/publishing-packages/). * **The docs site (`apps/docs`) must not import `@drawnagency/*`** — not even as types — so it builds independently of package `dist`. Reference the packages in prose and code fences only, never as a real `import`. * **Custom section types register via root `src/sections.ts`**, not the `sections` config field. See [Building custom sections](/developer/framework-internals/building-custom-sections/). * **Never write `nav.json` (or a `nav` key) unless you mean to change the page grouping.** Sidebar order and grouping live in `src/content/nav.json`, and a write replaces it wholesale — so `{"entries": []}` silently deletes every group on the site, with a clean parse and no error. Leaving the file (or the `nav` key on an MCP `save_sections` index) alone preserves it. See the [nav.json reference](/developer/reference/nav-json-reference/). * **A `documentId` is not an `imageId`, and documents are a third sidecar.** File metadata for `document` sections lives in `src/content/document-manifest.json`, never in `image-manifest.json` or the index — so a document can’t be referenced until it exists there. Upload it first (MCP `upload_document`, or the media library’s documents tab), then put the returned id in `content.doc.documentId`. An id with no manifest entry renders a dead row and is only a validator *warning*, so nothing stops you shipping it. See the [`document` section reference](/developer/reference/section-schema-reference/#document). * **A read that reports `missing` is INCOMPLETE — don’t write from it.** MCP content reads return a `missing` array when an indexed section file isn’t valid JSON: those ids are absent from `sections`, but their files are still on the branch. Never post back an index that drops them, and never `pruneOrphans` off such a read — fix the file (re-save that section) first. See [Using the MCP connector](/developer/using-the-mcp-connector/). ## Common tasks → start here [Section titled “Common tasks → start here”](#common-tasks--start-here) | You want to… | Page | | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Stand up a new client site | [Provisioning a new site](/developer/building-a-client-site/provisioning/) | | Create, edit, or populate a site from chat (no checkout) | [Using the MCP connector](/developer/using-the-mcp-connector/) | | Configure a site | [Configuration](/developer/building-a-client-site/configuration/) · [Config reference](/developer/reference/config-reference/) | | Add a custom section type | [Building custom sections](/developer/framework-internals/building-custom-sections/) | | Understand how rendering works | [Architecture](/developer/overview/architecture/) | | Run the monorepo locally | [Monorepo & dev workflow](/developer/framework-internals/monorepo-and-dev-workflow/) | | Publish a package release | [Publishing packages](/developer/framework-internals/publishing-packages/) | | Wire auth & audiences | [Auth & audiences setup](/developer/building-a-client-site/auth-audiences-setup/) | | Set environment variables | [Environment variables](/developer/building-a-client-site/environment-variables/) · [reference](/developer/reference/environment-variable-reference/) | # Auth & audiences setup > Wire up Supabase auth and configure viewer audiences. The portal supports two authentication modes: `supabase` (OAuth and email/password, with in-app audience management) and `password` (bcrypt-hashed secrets in environment variables, a developer fallback). Use `supabase` for all real deployments. ## Choosing a mode [Section titled “Choosing a mode”](#choosing-a-mode) Set `AUTH_PROVIDER` in your `.env` (or in the Netlify environment variables): ```plaintext AUTH_PROVIDER=supabase ``` Omit `AUTH_PROVIDER` or set it to `password` to use password-only auth. In password mode, audiences are defined entirely by the `VIEWER__PASSWORD` environment variables — they cannot be managed in the editor UI. ## Supabase mode [Section titled “Supabase mode”](#supabase-mode) ### Shared Supabase project [Section titled “Shared Supabase project”](#shared-supabase-project) All client sites share **one** Supabase project. Every `*.drawn.guide` site does OAuth, invite, and password-reset flows against the same Auth instance. The three required env vars are the same across all client sites: ```plaintext SUPABASE_URL=https://your-project.supabase.co SUPABASE_ANON_KEY=your-anon-key SUPABASE_SERVICE_ROLE_KEY=your-service-role-key ``` ### Default audience [Section titled “Default audience”](#default-audience) Each site has a default viewer audience seeded at site creation. The `isDefault` flag is a Supabase-only concept — it marks the audience that viewers fall into when they authenticate without being assigned to a named audience. This is set in the database at provisioning time and does not appear in password-mode sites. The flag now also grants access: a viewer whose sign-in belongs to the default audience can reach `/audiences` and reveal every sign-in password there, so the client can hand a new partner access without an editor login. Treat a default-audience sign-in accordingly. See [Auth architecture](/developer/framework-internals/auth-architecture/#viewer-credentials-named-sign-ins). A newly provisioned site gets one credential automatically — username `client` on the default audience, with a generated passphrase returned in the provisioning result. Hand that over; it is not stored in readable form, so if it is lost an editor must set a new password (which then becomes revealable in-portal). ### Named sign-ins replace the audience password [Section titled “Named sign-ins replace the audience password”](#named-sign-ins-replace-the-audience-password) Viewers log in with a username and password. Each credential row points at exactly one audience and inherits its access, so `agency1`/`agency2`/`agency3` can all sit on **External Agencies** and be revoked independently. Audiences themselves carry no password at all — the column was dropped once every portal had been redeployed (`20260805154537`). A new audience has no way in until you add a sign-in to it. The credentials migration back-fills one credential per existing audience password, named after the audience slug. Existing viewers therefore keep their password and simply type e.g. `external-agencies` as the username — no lockout and no coordination needed. ### Making existing passwords revealable [Section titled “Making existing passwords revealable”](#making-existing-passwords-revealable) `/audiences` can only show a password stored with a reversible copy alongside its bcrypt hash. Anything created before that shipped — including every back-filled credential and the provisioner’s initial sign-in — reads as “can’t be shown” until its password is next changed in **Site Settings → Viewer Access**. bcrypt cannot be reversed, so there is no backfill. Expect to reset each carried-over sign-in once per site if the client wants to look them up. ### Critical Supabase dashboard configuration [Section titled “Critical Supabase dashboard configuration”](#critical-supabase-dashboard-configuration) The following rules apply to the **Supabase dashboard** (the production source of truth). Do not apply them via `supabase config push` — the monorepo’s `supabase/config.toml` has `site_url` set to localhost and would clobber production settings. **Site URL — set to a single concrete origin:** ```plaintext https://acme.drawn.guide ``` Wildcards are rejected in the Site URL field and a wildcard entry silently breaks the fallback path for every site. Pick one concrete domain as the Site URL (typically the main client site or the first site created). **Redirect URL allow-list — restrict to platform-controlled paths:** ```plaintext https://*.drawn.guide/edit/login https://*.drawn.guide/edit/login/callback ``` These are the only two paths any auth flow redirects to: OAuth and invite/reset flows use `/edit/login/callback`; the existing-user invite login link uses `/edit/login`. Path-restricting the allow-list means a wildcard subdomain entry cannot be abused to redirect to an arbitrary page on any `drawn.guide` subdomain. **Never add a bare `*.netlify.app` entry.** `netlify.app` is a shared hosting domain — any Netlify tenant could register a subdomain and become a valid redirect target in your allow-list, enabling an open-redirect attack that could steal auth codes. ### OAuth redirect\_to [Section titled “OAuth redirect\_to”](#oauth-redirect_to) The portal builds the OAuth `redirect_to` parameter from the **live request origin**, not from the build-time `SITE` environment variable. This is required because Netlify’s `URL` environment variable (which Astro bakes into `import.meta.env.SITE`) can resolve to the `*.netlify.app` host instead of the custom domain — making `redirect_to` unmatched in the allow-list and landing the PKCE callback on a different origin from where the verifier cookie was set. Any custom auth flow you add must derive its redirect origin from the incoming request, not from `import.meta.env.SITE`. ## Password mode [Section titled “Password mode”](#password-mode) In password mode, audiences are defined by environment variables. Each audience needs a name (the `` suffix), a bcrypt password hash, and optionally a display color: ```plaintext VIEWER_INTERNAL_PASSWORD=\$2b\$10\$... VIEWER_INTERNAL_COLOR=#10b981 VIEWER_EXTERNAL_PASSWORD=\$2b\$10\$... VIEWER_EXTERNAL_COLOR=#3b82f6 ``` See [Environment variables](/developer/building-a-client-site/environment-variables/) for the bcrypt hash generation command and the `\$`-escaping requirement. Audience settings are read-only in the editor UI when running in password mode. To add or remove an audience, edit the environment variables and redeploy. Password mode also cannot reveal passwords on `/audiences` — the env vars hold only bcrypt hashes, so `createPasswordAuth()` omits the `reveal` capability and the page masks them. # Brand onboarding > Scaffold and evolve the Brand Foundation page during client onboarding. The `brand-onboarding` skill (shipped in `@drawnagency/authoring`, linked into every client repo as `.claude/skills/brand-onboarding/`) scaffolds the **Brand Foundation page** — Drawn’s working document for the client onboarding phase of an engagement — and describes how to evolve it as new material arrives. ## The three-page model [Section titled “The three-page model”](#the-three-page-model) * **Brand Foundation** (slug `brand-foundation`) — the onboarding working document: info-gathering, alignment observations, and personality drafting. A companion scratch pad. It does not evolve into the other pages; it is archived once its job is done. * **Brand Atlas** — the polished foundation narrative (story, values, personality). * **Brand Guide** — the standards (logo, color, type, voice). The pages evolve in tandem from day one — the Foundation is a working document, not a staging area. The Atlas and Guide grow as narrative and standards land; material only occasionally moves between pages, at the operator’s direction, through ordinary editing. There is no finalization step, and the Foundation page is archived whenever its job is done. Git history is the record — every published state is preserved automatically, so never simulate history inside page content (no “as of \” framing, no timestamps-as-content). ## Scaffold vs evolve [Section titled “Scaffold vs evolve”](#scaffold-vs-evolve) * **Scaffold** — first build from intake materials: settles the page plan (which of Foundation/Guide/Atlas to create), shapes the page from the four-group armature (Getting Started, Brand Alignment, Brand Personality, Round 1). * **Evolve** — every later update is an ordinary editing session (connector or /edit) with the new material as context: fill blanks in the client’s language, add observations-as-questions, rewrite or remove settled items, iterate the personality, add rounds. No special tooling. ## Conventions [Section titled “Conventions”](#conventions) * **Brand Foundation page settings** — slug `brand-foundation` (display title bespoke per client), `showInNav: true`, default audience access. Do not add special audiences or per-section access restrictions. * **Edit settled content in place** — when new material answers a blank or closes an observation, just rewrite or remove it. Git preserves every prior published state, so there is no archive-on-resolve step. * **`archived` means dormant-but-resurrectable** — a campaign page that ended, or a Foundation page whose job is done. Never use it to mean “resolved”. * **Blanks are the agenda** — prompts the client cannot yet answer (success criteria, good-to-knows, decision makers, additional partners) stay visibly blank; they are the next call’s agenda. Never invent an answer to fill one. * **Observations are questions** — alignment findings are framed for discussion (“you describe the brand as X; the materials lean Y — which is it?”), never as verdicts. Drawn holds the pen; clients are read-only viewers. * **Drawn-internal material stays in operator notes** — candid observations live in the operator’s own intake notes, out of the portal. If something must travel with the page for editors’ eyes only, a `draft` section is the escape hatch (drafts never render for viewers) — use sparingly. ## Via the MCP connector [Section titled “Via the MCP connector”](#via-the-mcp-connector) Use the `brand_onboarding` prompt (args: `siteId`, `context`) or call `get_onboarding_guide` before scaffolding or editing a Brand Foundation page. The guidance is embedded at connector build time from `packages/authoring/skills/brand-onboarding/guidance/onboarding-core.md` — edit the process there. # Configuration > portal.config.mjs and site-config.json. Client site configuration lives in two files: `portal.config.mjs` wires up the runtime providers, and `src/content/site-config.json` controls the brand presentation. ## portal.config.mjs [Section titled “portal.config.mjs”](#portalconfigmjs) `portal.config.mjs` is the entry point for the portal framework. It must import `defineConfig` from `@drawnagency/core/config` — **not** the root `@drawnagency/core` export, which includes Node-only integration code and will break in the browser during editor hydration. ```js import { defineConfig, supabaseDeployStatus } from "@drawnagency/core/config"; import { supabaseAuth } from "@drawnagency/auth-supabase"; import { githubStorage } from "@drawnagency/github"; export default defineConfig({ auth: supabaseAuth(), storage: githubStorage(), deployStatus: supabaseDeployStatus(), site: { name: "Acme Brand Portal" }, }); ``` To add your own section types, create a `src/sections.ts` file at the repo root — see [Building custom sections](/developer/framework-internals/building-custom-sections/). You can optionally also pass that array to `defineConfig`’s `sections` field for a type-check, but registration happens through `src/sections.ts` regardless of the config field. ### Top-level keys [Section titled “Top-level keys”](#top-level-keys) | Key | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `auth` | Authentication provider. `supabaseAuth()` for OAuth + email/password; see [Auth & audiences setup](/developer/building-a-client-site/auth-audiences-setup/). | | `storage` | Content storage backend. `githubStorage()` saves edits back to the GitHub repository. | | `deployStatus` | Deploy status provider. `supabaseDeployStatus()` exposes Netlify build state in the editor UI. | | `sections` | Optional, **type-only**. Custom section types register from a root `src/sections.ts` file, not this field — see [Building custom sections](/developer/framework-internals/building-custom-sections/). Passing the array here only adds a type-check. | | `assets` | Optional. Bucket storage for self-hosted video over the git cap. `r2Assets()` from `@drawnagency/assets-r2` — the template’s default. Omit and video falls back to small git-backed loops plus YouTube/Vimeo embeds. | | `documents` | Optional. Private-bucket storage for the files behind `document` sections over the 2.5 MB git cap. `r2Documents()` from `@drawnagency/assets-r2` — the template’s default. | | `collab` | Optional. Live multi-editor presence and section locks. `supabaseCollab()` from `@drawnagency/auth-supabase`. Absent, the editor degrades cleanly to solo. | | `media` | Optional. The media provider (image resolution/upload). Defaults to the GitHub-backed one; this is where the adapter is chosen, **not** in `site-config.json`. | | `builtins` | Optional, `"core"` \| `"all"`. A typed seam that is **not yet wired** — both built-in groups always register today, so setting it has no effect. | | `site.name` | The site’s display name, shown in the editor header and page `