# Gravity Node — full documentation

Generated from https://www.edmecosystem.com/docs. Each section below corresponds to one page there.

---

<!-- https://www.edmecosystem.com/docs -->

Gravity Node is a boilerplate for going from **zero to a deployed, editable website in
minutes**. Clone it, run one command, and you get a themed, server-rendered site (Astro,
SSR) with a working blog, events, forms, a customer portal, an e-commerce storefront, a
media gallery, an admin dashboard, and **two** visual editors for page content — all wired
up already.

It's the Node/Astro sibling of [Gravity](https://thegravityframework.com), the original
Python/Flask framework — same architecture, same content model, same "local JSON ↔ Adhara"
story, ported to a stack most platforms support natively.

## The core idea

Everything in this project follows one rule: **content is stored as local JSON files by
default, and switches to a real headless CMS ([Adhara](https://adharaweb.com)) when you
connect one — feature by feature, not all-or-nothing.**

- **Out of the box**: blog posts, events, page content, links, shop items — all plain JSON
  under `data/content/`. No database, no account, no API key. Clone it and it works.
- **Connect Adhara** by setting a couple of env vars, and individual features switch over
  independently. Run events on Adhara while the portal stays local. See
  [Adhara Integration](/docs/overview) for exactly how this works per feature.
- **Deploy anywhere** — Vercel, Cloudflare, Google Cloud Run, or Netlify, with one command
  each. See [Deploying](/docs/deploying).

## Who this is for

- **A site owner** who wants a real website with a blog, events, a shop, and a client
  portal, without committing to a specific CMS on day one.
- **A developer** extending the template — every architectural rule that keeps the two
  visual editors working is documented in [Architecture](/docs/content-model), not just
  implied by the code.
- **An AI coding agent** building on top of this template. This documentation is written to
  be exactly as useful read raw as it is rendered — see the machine-readable index at
  [`/llms.txt`](/llms.txt) and the full corpus at [`/llms-full.txt`](/llms-full.txt).

## Where to start

| I want to... | Go to |
|---|---|
| Get a copy running locally | [Quick Start](/docs/quick-start) |
| Understand how content editing works | [The Content Model](/docs/content-model) |
| Add a new block type, or a new page section | [The Content Model](/docs/content-model) |
| Understand the pluggable storage backends | [Storage](/docs/storage) |
| Connect a real CMS backend | [Adhara Integration](/docs/overview) |
| See what's built already | [Features](/docs/features) |
| Ship it | [Deploying](/docs/deploying) |
| Look up an env var or CLI command | [Environment Variables](/docs/environment-variables), [CLI Reference](/docs/cli-reference) |

## How this differs from the Python original

This is a **core-first v1**, not a 1:1 port of every feature in the Python repo — see the
comparison table in the [README](https://gitlab.com/eim_opensource/gravity-node#readme) for
the full breakdown. The short version: everything content-related (blog, events, portal,
scheduling, links, forms) is ported; a handful of things new to this port didn't exist in
Python at all (a real e-commerce storefront via the Adhara Commerce SDK, a podcast page, a
media gallery, Netlify as a fifth deploy target, an idempotent "install your tools" script);
and a couple of things (paid event/membership checkout, real Adhara-backed admin login) are
deliberately deferred — see [FAQ & Roadmap](/docs/faq).

---

<!-- https://www.edmecosystem.com/docs/quick-start -->

## Prerequisites

Node.js **18.20+** and npm. That's it — unlike the Python original, there's no separate
Python/pip toolchain to install.

Starting from a completely bare machine? [Install Your Tools](/install-your-tools) covers
Git, the GitHub CLI, Node.js, a text editor, and an AI coding agent with one idempotent
command per OS.

## Clone, install, configure, run

```bash
# 1. Clone and install
git clone https://gitlab.com/eim_opensource/gravity-node.git
cd gravity-node
npm install

# 2. Configure
cp .env.example .env
# generate a SECRET_KEY:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# paste the result into SECRET_KEY= in .env

# 3. Run it
npm run dev
```

Open `http://localhost:3001`. That's a fully working site — home, about, features, blog,
events, forms, links, podcast page (unconfigured), shop, gallery, and a customer portal —
all reading from `data/content/`, no external services required.

## Prefer an AI coding agent to do this for you?

Open [`/get-started`](/get-started) in the running app (or read it as plain source at
`src/pages/get-started.astro`) — it's a copy-pasteable prompt for Claude Code, Claude
Desktop, or Codex that clones the repo, installs it, runs it locally, and — once you
confirm it looks right — deploys it to Vercel and hands you back a live URL.

## Unlock the admin dashboard and editors

Local admin auth normally requires a real Adhara-backed session (not yet implemented — see
[FAQ & Roadmap](/docs/faq)). For local development, set the dev bypass:

```bash
# in .env
GRAVITY_DEV_ADMIN=1
```

Restart the dev server, then:

- Visit `/admin` — the dashboard, with a live "Feature backends" panel showing which
  features are local vs. Adhara right now.
- Look for the **✏️ floating button** in the bottom-right corner of the home, about, or
  features pages — that's the inline click-to-edit editor.
- Visit `/admin/editor/build/home` for the full drag-and-drop **builder canvas** (built on
  GrapesJS).

**Never set `GRAVITY_DEV_ADMIN=1` in production** — it bypasses login entirely.

## Seed sample content

```bash
npm run content -- import docs/gravity/examples/content.sample.json
npm run blog -- import docs/gravity/examples/blog.sample.json
npm run events -- import docs/gravity/examples/events.sample.json
npm run links -- import docs/gravity/examples/links.sample.json
npm run shop -- import docs/gravity/examples/shop.sample.json
npm run courses -- import docs/gravity/examples/portal/courses/building-with-ai.json
```

Or, if you're running the Docker path: `make editor` builds the container, seeds all of the
above, and starts with the admin/portal dev bypass on — see the printed URLs when it's done.

## Your first edit

1. Open `/admin` (with the dev bypass on).
2. Click **Inline edit** on the Home page, or **Open in Builder**.
3. Change some text, save/publish.
4. Refresh the live page — the change is there. It's now sitting in
   `data/content/pages/home.json` (or wherever `GRAVITY_STORE_BACKEND` points), not in a
   database.

That's the whole content loop: every editor — inline, builder canvas, or the `npm run
content` CLI — reads and writes the exact same `Section[]` data through
`src/content/content.ts`. See [The Content Model](/docs/content-model) for how that works
under the hood, and why it matters if you're extending the template rather than just using
it.

## What's next

- [The Content Model](/docs/content-model) — how the block/schema system works, and the one
  rule that keeps both visual editors working.
- [Adhara Integration](/docs/overview) — connect a real CMS backend, feature by feature.
- [Deploying](/docs/deploying) — ship it to Vercel, Cloudflare, Google Cloud Run, or
  Netlify.

---

<!-- https://www.edmecosystem.com/docs/content-model -->

## The rule that matters most

**Anything a site owner should be able to edit after launch — without a developer and
without touching code — must be a content block, not hand-written HTML on a page.**

This site has three interchangeable editing surfaces that all operate on the exact same
data:

1. A **floating inline click-to-edit button** on the live page.
2. A **full drag-and-drop builder canvas** (`/admin/editor/build/<page>`), built on
   [GrapesJS](https://grapesjs.com).
3. A **JSON/CLI path** (`npm run content`).

All three work by reading and writing `Section[]` — `{ id, type, fields }` objects — through
one module, `src/content/content.ts`. A block type only exists to those editors if it has a
schema under `src/content/blocks/*.json`.

If you write a new marketing section directly into `index.astro` as literal markup instead
of as a block, it renders correctly on the live site and is then **completely invisible** to
both editors — not broken-looking, just silently unreachable. That's the failure mode this
page exists to prevent.

**Heuristic:** if a human product owner would plausibly want to change this text, image, or
list themselves later without asking a developer, it belongs in a block's `fields`. If it's
structural (page layout, nav, footer, deploy config, an entire new route) or truly one-off,
it's just code — edit it directly, no block needed. See
[hand-written pages](#hand-written-pages-not-part-of-the-block-system) below for the list of
pages that are deliberately exempt.

## Adding a new block type

This is a fixed, mechanical checklist — the builder canvas is schema-driven, so you do
**not** need to write any GrapesJS-specific registration code:

1. **`src/content/blocks/<type>.json`** — the schema: `type`, `label`, `description`, and a
   `fields` array, each `{ key, type, label, default }`. A `list` field also needs an `item`
   array of the same shape, describing one row.
2. **`src/components/blocks/<Type>.astro`** — the Astro render component. Read every field
   via the `blockField(section, key)` helper from `src/content/content.ts` (it falls back to
   the schema default automatically). Reuse existing theme classes — every theme's `main.css`
   (`public/themes/gravity/main.css`, `public/themes/clarity/main.css`) shares the same class
   vocabulary — see [Hard rules](#hard-rules) below.
3. **Register it** in `src/components/blocks/Sections.astro`'s `BLOCK_COMPONENTS` map (one
   line).
4. **`src/builder/render.ts`** — add a `render<Type>(fields)` function that mirrors step 2's
   markup as a plain HTML string. This is the builder canvas's live-preview renderer — a
   deliberate small duplication of the Astro component, not a shared abstraction, because
   GrapesJS renders HTML strings, not Astro components. Add the block's outer `<section>`
   tag/class to the `BLOCK_WRAPPER` map in the same file.

That's the whole checklist. `src/builder/componentTypes.ts` fetches every schema from
`/api/admin/editor/block-schemas` at runtime and generates the GrapesJS block, component
type, and trait panel from it automatically — don't hand-write a new
`editor.Components.addType(...)` call for a new block type; if you find yourself doing that,
the schema-driven factory is missing something, and *that's* the bug to fix.

## Modifying an existing block type

A block type's field list exists in three places that must all agree, or the builder
canvas's preview will silently diverge from the real site (and saved data may not
round-trip):

- `src/content/blocks/<type>.json` — the schema, source of truth for field keys/types/defaults.
- `src/components/blocks/<Type>.astro` — the live-site renderer.
- `src/builder/render.ts`'s matching `render<Type>()` — the canvas-preview renderer.

Add, rename, or remove a field in the schema and update the other two in the same change.
Trait UI (the settings panel) needs no separate update — it's generated from the schema.

## Field types

Only six exist, and each maps to exactly one editor UI (see `src/builder/traits.ts`):

| Type | Editor UI | Notes |
|---|---|---|
| `text` | Plain input | Single-line string |
| `textarea` | Multi-line input | Plain string, no formatting |
| `richtext` | RTE (inline editor) / textarea (builder) | Stored as raw HTML — no markdown |
| `link` | URL input | A URL string |
| `image` | Upload button | Wired to `/api/admin/editor/upload`, goes through the pluggable `ContentStore` — see [Storage](/docs/storage) |
| `list` | Repeater | Needs an `item` sub-schema describing one row |

If you think you need a seventh type, you also need to: add a case to `traitTypeFor()` in
`src/builder/componentTypes.ts`, and a matching custom trait type in `src/builder/traits.ts`
(follow the pattern of `gv-textarea`/`gv-image`/`gv-list` — read that file's own docstring
first, it explains why every custom trait manages its own DOM instead of GrapesJS's default
input-value wiring). Don't invent a new field `type` string without doing both, or it'll
silently fall through to a plain text input.

## Hand-written pages, not part of the block system

These pages are ordinary code, not editor-managed content — neither visual editor touches
them: theme CSS, site chrome (nav/footer in `BaseLayout.astro`), and standalone pages —
`/get-started`, `/install-your-tools`, `/forms`, `/blog`, `/events`, `/scheduling`,
`/schedule/*`, `/links`, `/podcast`, `/shop/*`, `/gallery`, `/contact`, `/admin/*`,
`/portal/*`, and this documentation site itself. When in doubt, ask: "does this text/image
currently come from a `Section`'s `fields`?" If not, it's just code — edit it directly.

Three pages are **dual-mode**: `index.astro`, `about.astro`, and `features.astro` render
`<Sections sections={content.sections} />` when block content has been published for that
page, and fall back to a hardcoded default layout only when it hasn't. Once a page has
published blocks, add a new block/section instead of editing the fallback markup — the
fallback branch is dead once real content exists.

## Hard rules

- **Don't hand-write new sections into `index.astro`/`about.astro`/`features.astro`'s
  markup** once real content exists there — see dual-mode pages above.
- **Don't add inline `style=` attributes or one-off CSS classes inside block markup.** Use
  only the existing utility classes and CSS custom properties already defined in every
  theme's `main.css` (`.card`, `.grid-3`, `var(--space-*)`, etc. — see
  `public/themes/gravity/main.css`). The builder canvas deliberately has no style manager —
  block markup is the *only* thing that determines how a block looks, precisely so a site
  owner can never drag it off-theme.
- **A new shared class goes into every theme's `main.css`, not just one.** Each theme is a
  self-contained design system with the full class vocabulary, not a shared base plus
  per-theme diffs — a class added to only one theme breaks under the other.
- **Before adding a class to a hand-written page's scoped `<style>`, check whether it (or
  something close to it) already exists on another page.** A class reused across two or more
  pages belongs in `main.css` instead — a Python-script-based dedup audit (grep every
  `<style>` block, flag cross-file duplicates) is a standard verification step after any
  page-heavy change. See [Theming](/docs/project-structure#theming) for the full design-token system.
- **Don't write directly to `data/content/*.json`** in a shape that doesn't match
  `Section`/`BlockSchema` from `src/content/content.ts`. Go through that module's
  `load`/`save`/`publish`, or the `npm run content`/`blog`/`events`/etc. CLI scripts — they
  preserve draft/publish semantics and `GRAVITY_SITE_PREFIX` scoping that hand-edited JSON
  can silently violate.
- **Don't build a second, competing content-storage mechanism.** Every content type already
  goes through the pluggable `ContentStore` in `src/stores/` — see [Storage](/docs/storage).
  A new content type gets a new `src/services/*Store.ts`, not a bespoke file-read/write path.
- **Don't vendor the Adhara SDK into this repo.** See
  [Adhara Integration](/docs/overview).

## See also

- [Project Structure](/docs/project-structure) — the directory tour and request flow.
- [Storage](/docs/storage) — the pluggable `ContentStore` abstraction every feature's data
  goes through.
- [Adhara Integration](/docs/overview) — how individual features switch from local JSON to a
  real CMS backend.
- [SEO & Metadata](/docs/seo) — how every page's title/description/OG image and
  sitemap.xml/robots.txt are generated.

---

<!-- https://www.edmecosystem.com/docs/storage -->

Every content type in this project — pages, blog posts, events, links, shop items, contact
submissions, uploaded media, and now media galleries — goes through one pluggable interface:
`ContentStore` (`src/stores/types.ts`). Seven backends implement it, all interchangeable
without touching any calling code.

## The interface

```ts
export interface ContentStore {
  read<T = unknown>(name: string): Promise<T | null>;
  write(name: string, document: unknown): Promise<boolean>;
  describe(): string;
  writeMedia(filename: string, data: Uint8Array, contentType?: string): Promise<string | null>;
  listMedia(prefix: string): Promise<{ name: string; url: string }[]>;
  list(prefix: string): Promise<string[]>;
  delete(name: string): Promise<boolean>;
}
```

Every method degrades gracefully — "not found" is never an exception. `read`/`write`/`list`/
`delete` operate on JSON **documents** (e.g. `"blog/welcome.json"`); `writeMedia`/`listMedia`
operate on real **media files** under an `upload/` key namespace, returning a browser-viewable
URL. `list()` is hardcoded to `.json` files — it's a content-document lister, not a general
file browser; that's why the media gallery (see [Features](/docs/features)) needed
`listMedia()` added rather than reusing `list()`.

## The seven backends

| Backend | Selected by | Notes |
|---|---|---|
| `local` | Default — no cloud env var set | JSON files under `data/content/`; media under `public/upload/`, served directly by Astro |
| `gcs` | `GRAVITY_SITE_BUCKET` | Google Cloud Storage. Credentials via Application Default Credentials |
| `s3` | `GRAVITY_S3_BUCKET` | AWS S3. Standard AWS credential chain (env vars or IAM role) |
| `azure` | `GRAVITY_AZURE_CONTAINER` | Azure Blob Storage. Needs `AZURE_STORAGE_CONNECTION_STRING` too |
| `r2` | `GRAVITY_R2_BUCKET` | Cloudflare R2 — speaks the S3 API via `@aws-sdk/client-s3`. Needs `CLOUDFLARE_ACCOUNT_ID` + `R2_ACCESS_KEY_ID` + `R2_SECRET_ACCESS_KEY`, and `GRAVITY_R2_PUBLIC_URL` for `writeMedia()`/`listMedia()` to return real URLs (R2 has no client-derivable public URL) |
| `vercel_blob` | `BLOB_READ_WRITE_TOKEN` (auto-injected once a Blob store is linked) | No bucket name to configure |
| `netlify_blob` | `NETLIFY` (auto-set by Netlify's runtime) | Media served back via `src/pages/upload/[...path].ts`, since Netlify Blobs has no public URL of its own |

`GRAVITY_STORE_BACKEND=local|gcs|s3|azure|r2|vercel_blob|netlify_blob` forces one explicitly.
`getStore()` (`src/stores/index.ts`) is a process-wide singleton — the backend choice is
resolved once per process, from whichever env vars are present, in that priority order.

`GRAVITY_SITE_PREFIX` scopes every read/write/list to a subdirectory (or key prefix), so one
bucket/root can be shared by multiple site instances without colliding. Leave it blank for a
single site.

## Local disk in detail

`LocalContentStore` (`src/stores/local.ts`) keeps two separate directories:

- `data/content/` (or `GRAVITY_CONTENT_DIR`) — JSON documents. **Not web-servable.**
- `public/upload/` (or `GRAVITY_UPLOAD_DIR`) — uploaded media, hash-prefixed filenames.
  **Is** web-servable, at `/upload/<name>` — this is Astro's static directory, served for
  free, no route code needed.

This distinction matters for anything that needs to serve real files: `data/content/` is
where the block editor's own content lives (never served directly), while `public/upload/`
is where anything a site owner uploads through the admin UI or block image fields ends up,
and is genuinely reachable by a browser.

## Media galleries: the one feature with a three-way local split

The media gallery (`/gallery`) is the one feature whose "local" mode isn't a single thing —
see its own section in [Features](/docs/features) for the full local-disk vs. cloud-bucket
vs. Adhara breakdown. The short version: a **local-disk** gallery scans `public/gallery/<slug>/`
directly with `fs.readdir`, bypassing `ContentStore` entirely (it's raw static files a site
owner drops in, not a JSON document); a **cloud-bucket** gallery uses the newer
`listMedia()` method instead, reusing the exact same pluggable backend already proven by
`writeMedia()`.

## Extending storage

Adding a genuinely new *content type* (not a new backend) gets a new `src/services/*Store.ts`
that calls `getStore()` — never a second, parallel storage mechanism. Every existing feature
follows this pattern: `blogStore.ts`, `eventStore.ts`, `linkStore.ts`, `shopStore.ts`,
`galleryStore.ts`, `contactFormStore.ts`, `contactStore.ts`.

If you need a genuinely new **backend** (an eighth cloud provider), implement the full
`ContentStore` interface in a new `src/stores/<name>.ts`, register it in the `BUILDERS` map
in `src/stores/index.ts`, and add its auto-detect env var to `detectBackend()`'s priority
list.

---

<!-- https://www.edmecosystem.com/docs/project-structure -->

## Directory tour

```
gravity-node/
├── src/
│   ├── content/
│   │   ├── content.ts             # Page/section content API — load/save/publish, block schemas
│   │   └── blocks/*.json          # Block-type schemas (hero, feature-grid, rich-text, cta, ...)
│   ├── docs-content/*.md          # This documentation site's markdown source (astro:content)
│   ├── components/blocks/         # Astro block components + the Sections list-renderer
│   ├── components/shared/         # EditFab.astro — the floating ✏️ button
│   ├── layouts/
│   │   ├── BaseLayout.astro       # Theme chrome: nav, footer, meta tags
│   │   └── DocsLayout.astro       # Sidebar + prose layout for /docs
│   ├── builder/                   # GrapesJS builder canvas client bundle
│   │   ├── main.ts                # GrapesJS init, load/save/publish wiring
│   │   ├── componentTypes.ts      # Schema-driven block/trait registration + JSON (de)serialization
│   │   ├── traits.ts              # Custom trait types: textarea, image upload, list repeater
│   │   └── render.ts              # Canvas-preview HTML, mirrors components/blocks/*.astro
│   ├── lib/
│   │   ├── theme.ts                # GRAVITY_TEMPLATE resolution
│   │   ├── auth.ts                 # Admin auth guard (dev bypass + Adhara token)
│   │   ├── portal.ts               # Customer-portal backend resolution
│   │   ├── adhara.ts               # Adhara HTTP API + the (optional, external) SDK client
│   │   ├── adharaCommerce.ts       # Commerce-specific SDK layer (shop)
│   │   ├── adharaMedia.ts          # Media-gallery-specific SDK layer (gallery)
│   │   ├── adharaForms.ts          # Form-provisioning SDK layer (contact)
│   │   ├── featureBackend.ts       # Shared local/adhara toggle resolver, reused by every feature
│   │   ├── sanitize.ts             # HTML allowlist sanitizer
│   │   └── editbar.ts              # Floating-button routing logic
│   ├── stores/                    # Pluggable ContentStore: local/GCS/S3/Azure/R2/Vercel Blob/Netlify Blobs
│   ├── services/
│   │   ├── blogStore.ts, eventStore.ts, linkStore.ts, shopStore.ts,
│   │   │   galleryStore.ts, scheduleStore.ts, podcastStore.ts,
│   │   │   contactFormStore.ts, contactStore.ts   # One store per feature — local ↔ Adhara
│   │   └── registrationStore.ts   # Free-event registration + attendee list, via Adhara
│   └── pages/                     # Astro routes — public pages, /docs, /admin/*, /api/*
│
├── public/
│   ├── themes/clarity/main.css    # The theme's entire CSS design system
│   ├── js/main.js                 # Nav scroll, mobile menu, scroll-reveal, tab switcher
│   ├── js/inline.js               # Inline editor client
│   └── js/shop-cart.js            # Client-side cart (localStorage)
│
├── data/content/                  # Local JSON content — pages, blog posts, events, ...
├── scripts/
│   ├── gravity-*.ts                # Seed/import CLIs (content, blog, events, courses, links, shop, contact)
│   ├── setup.sh / deploy_*.sh      # Deploy wizards (gcp/vercel/cloudflare/netlify)
│   ├── push_repo.sh                # Create + push to a GitHub/GitLab repo
│   ├── install_tools_*.sh/.ps1     # Idempotent per-OS dev-environment installer
│   └── lib/                        # Shared shell helpers + the storage-provisioning wizard
├── astro.config.mjs                # DEPLOY_TARGET-driven adapter selection
├── Dockerfile / docker-compose.yml / wrangler.jsonc / netlify.toml
└── .env.example
```

## Request flow

1. A request hits the Astro SSR server (Node, or the platform-native equivalent — a Vercel
   Function, a Cloudflare Worker, or a Netlify Function/edge function, depending on
   `DEPLOY_TARGET`).
2. Public pages load content via `src/content/content.ts` (block-driven pages) or a
   feature-specific `*Store.ts` (blog/events/shop/etc.), which in turn resolves local vs.
   Adhara per [the toggle rules](/docs/overview) and reads through `getStore()` for local
   data.
3. `BaseLayout.astro` renders the shared nav/footer/theme chrome around whatever the page
   returns.
4. Admin routes (`/admin/*`) check `isAdmin()` (`src/lib/auth.ts`) — either a real Adhara
   session or the `GRAVITY_DEV_ADMIN=1` local bypass — before rendering.

## Deploy targets

`DEPLOY_TARGET` picks the Astro adapter (and the edge-cache provider — see
[Deploying](/docs/deploying#edge-caching)) at build time (`astro.config.mjs`):

| Target | Adapter | Runtime |
|---|---|---|
| `node` (default) | `@astrojs/node` | Plain Node process — Docker, Google Cloud Run, self-host |
| `vercel` | `@astrojs/vercel` | A real Vercel Function |
| `cloudflare` | `@astrojs/cloudflare` | A real Cloudflare Worker — no Docker, no proxy layer |
| `netlify` | `@astrojs/netlify` | Netlify Functions + edge middleware |

`npm run build:<target>` sets this explicitly, and an explicit value always wins. If it's
unset, `astro.config.mjs` auto-detects from the platform's own build-environment signal
(`VERCEL`, `NETLIFY`/`NETLIFY_LOCAL`, `CF_PAGES` — each platform's own documented system env
var) instead of just assuming `node`. This is what makes connecting this repo straight to
Vercel's or Netlify's git integration (Import Project / "Deploy this repo," no
`make deploy-*` script involved, no env vars configured at all) build correctly out of the
box — before this existed, that path silently built with the `node` adapter on whatever
platform triggered it, which doesn't produce output that platform can actually serve.

See [Deploying](/docs/deploying) for the full per-platform guide.

## Theming

Design tokens are CSS custom properties — swap `GRAVITY_TEMPLATE` and every page's fonts,
colors, spacing, and components change without touching markup.

```
public/themes/<theme>/main.css   ← the whole design system for that theme
src/layouts/BaseLayout.astro     ← nav/footer chrome, links the active theme's CSS
src/components/blocks/*.astro    ← content-block components (hero, feature-grid, rich-text, cta)
src/lib/theme.ts                 ← GRAVITY_TEMPLATE → theme resolution, KNOWN_THEMES registry
```

**Two themes ship.** `gravity` — dark navy + gold, Playfair Display + Inter + JetBrains Mono —
is the flagship theme and the default, matching the Python original. `clarity` — light,
Notion-inspired, DM Serif Display + DM Sans + IBM Plex Mono — is the alternate. Both themes
share the exact same class vocabulary (`.hero`, `.card`, `.terminal`, `.feat-card`, ...), so
every page and block component renders correctly under either without a fork — only the
`:root {}` tokens and the Google Fonts link (`themeFontsHref()` in `src/lib/theme.ts`) differ
per theme. Adding a third theme means:

1. Copy `public/themes/gravity/main.css` to `public/themes/<name>/main.css` and edit its
   `:root {}` tokens (and its Google Fonts if the typefaces change).
2. Add `<name>` to `KNOWN_THEMES`, and a matching entry in `THEME_FONTS`, in `src/lib/theme.ts`.
3. Fork whichever layout/block components you want to look meaningfully different under the
   new theme — most themes won't need this, since (1) already reskins everything that reads
   the shared tokens/classes.

There's no per-theme template *fallback* mechanism — a theme is a CSS reskin of the same
markup, not a different page structure. `src/pages/index.astro`'s dual-mode fallback content
(the demo homepage shown before any block content is published) is theme-agnostic for the
same reason: it only uses classes already in every theme's `main.css`.

### The CSS-dedup rule

Every reusable class lives in `main.css`, not copy-pasted across page-scoped `<style>`
blocks — this is a hard rule, not a suggestion, for two concrete reasons: (1) copies drift
(a hardcoded color in one duplicate silently overrode the theme-var version everywhere that
didn't have the same local copy); (2) a second theme's `main.css` can only reskin what's
actually *in* `main.css` — a class baked into one page's scoped `<style>` never sees a theme
swap. See [The Content Model](/docs/content-model#hard-rules) for the full rule and how a
page-scoped *override* on top of a shared base is still fine.

---

<!-- https://www.edmecosystem.com/docs/seo -->

Every page renders through `BaseLayout.astro`, which owns `<title>`, the meta description,
the canonical link, every `og:*`/`twitter:*` tag, and the favicon links — a new page sets a
few props and gets the rest for free:

```astro
<BaseLayout
  title="Blog"
  description="News, updates, and stories."
  ogImage={post.image}
  ogType="article"
>
```

## The brand suffix — one editable place, not thirty hardcoded ones

`title` is the **page-specific part only** — `BaseLayout` appends `" — {header.brand}"`
automatically, where `header.brand` is the same editable value that already drives the nav
logo and `og:site_name` ([The Content Model](/docs/content-model)'s `DEFAULT_HEADER`, or
whatever a site owner has published through the CMS). Every page used to hardcode its own
`" — Gravity Node"` suffix; rebranding meant editing ~30 files by hand. Now the brand lives
in exactly one place, and every page's title, `og:title`, and `twitter:title` follow it
automatically.

The one deliberate exception is this documentation site itself (`DocsLayout.astro`'s
`rawTitle` prop) — `/docs` documents the Gravity Node framework, not whatever a deployed
site is branded as, so it always says "Gravity Node" regardless of `header.brand`.

## OG images — real content images first, one static default otherwise

`ogImage` is converted to an absolute URL automatically (`src/lib/seo.ts`'s `toAbsoluteUrl()`)
— `og:image`/`twitter:image` **must** be absolute for Facebook/Twitter/LinkedIn/Slack to
render a preview at all; a relative path silently fails on all of them.

Pages with real content pull their own image automatically instead of the generic default:

| Page | Image source |
|---|---|
| Blog post | `post.image` (optional field) |
| Event | `event.image` |
| Shop item | `item.images[0]` |
| Podcast | the feed's own artwork |
| Home / About / Features | the published hero block's `image` field, when one exists (`content.ts`'s `heroSeoFrom()`) |
| Everything else | `public/img/og-image.png` (the site default) |

**No dynamic per-page image compositing** (rendering the page title onto a template image at
request time) is built — that needs a raster renderer (satori + resvg or similar) that
behaves differently across this project's four deploy targets (Node has no constraint,
Cloudflare Workers has real WASM/binary-size limits). A real cross-runtime risk for a
template whose whole point is deploying cleanly everywhere, so it was deliberately left as a
documented extension point rather than guessed at. Replacing the default assets for a
rebrand: `public/img/og-image.png` (1200×630), `public/favicon.svg`, `public/favicon.ico`,
`public/img/apple-touch-icon.png` (180×180) — same filenames, so nothing in `BaseLayout`
needs to change.

## sitemap.xml & robots.txt — generated per request, not at build time

Both (`src/pages/sitemap.xml.ts`, `src/pages/robots.txt.ts`) are generated **at request
time**, not via `@astrojs/sitemap` or a static file in `public/`. Two reasons that's the
right call for this project specifically, not just a style choice:

1. **The deployed domain isn't known at build time.** This is a template deployed to a
   different domain per install — a fixed `site:` URL baked in at build time would be wrong
   for everyone except whoever built it. Both endpoints derive absolute URLs from the actual
   request's `url.origin` instead.
2. **The content is dynamic.** Blog posts, events, and shop items can change without a
   rebuild — especially once Adhara is connected, where content can change on Adhara's side
   with no deploy at all. A sitemap generated once at build time would silently go stale.

If you add a new public, indexable route — a new top-level page, or a new dynamic content
type with its own listing — add it to `sitemap.xml.ts`'s `STATIC_ROUTES` array or its
dynamic-content loop (matching the existing blog/events/shop/docs pattern); it does not
appear automatically. If you add a new private, internal, or transactional route (anything
under `/admin`, `/portal`, `/api`, or a checkout/booking flow), add it to `robots.txt.ts`'s
`DISALLOW` list — that's the real signal search engines respect; simply omitting a route from
the sitemap isn't enough on its own.

---

<!-- https://www.edmecosystem.com/docs/overview -->

[Adhara](https://adharaweb.com) is a real, hosted headless CMS/CRM/commerce platform. This
project never requires it — every feature works against local JSON files out of the box —
but almost every feature can switch to reading (and sometimes writing) real Adhara data once
you connect one, without touching any calling code.

## Why per-feature, not all-or-nothing

A site owner might want events managed by a real content team in Adhara while the customer
portal stays local, or might want the shop on Adhara Commerce but the blog still local. So
instead of one global "use Adhara" flag, **each feature has its own independent env var**:

```bash
GRAVITY_BLOG_BACKEND=local|adhara
GRAVITY_EVENTS_BACKEND=local|adhara
GRAVITY_PORTAL_BACKEND=local|adhara
GRAVITY_SCHEDULING_BACKEND=local|adhara
GRAVITY_LINKS_BACKEND=local|adhara
GRAVITY_SHOP_BACKEND=local|adhara
GRAVITY_GALLERY_BACKEND=local|adhara
```

Leave any of them unset and it **auto-detects** — once the Adhara config that specific
feature actually needs is present (a workspace slug for public reads, an API key for
authenticated ones, the SDK installed for writes), it switches over automatically. Set it
explicitly to force one way or the other. `/admin` shows a live "Feature backends" panel
with the current resolution for every feature.

All seven go through one shared resolver — `resolveFeatureBackend()` /
`resolveFeatureBackendDetailed()` in `src/lib/featureBackend.ts`:

```ts
export function resolveFeatureBackendDetailed(envVar: string, autoDetect: () => boolean) {
  const raw = (process.env[envVar] || '').trim().toLowerCase();
  if (raw === 'local') return { backend: 'local', forced: true };
  if (raw === 'adhara') return { backend: 'adhara', forced: true };
  return { backend: autoDetect() ? 'adhara' : 'local', forced: false };
}
```

If you're wiring up a new switchable feature, reuse this resolver — don't hand-roll another
`(process.env.X || '').trim().toLowerCase()` check.

## Every feature resolves and behaves differently — by design

The resolver only answers "local or adhara, forced or auto." What each feature *does* with
that answer is deliberately different, matching what's actually possible on the real
backend:

| Feature | Auto-detects on | Local ↔ Adhara relationship |
|---|---|---|
| **Blog** (writes) | SDK installed + API key + workspace ID | Reads always **merge** local ∪ Adhara regardless of this var — only *writes* (create/update/publish) switch |
| **Events** | Workspace slug (public endpoint, no key needed) | Hard switch: `local` never calls Adhara; `adhara` **merges** local ∪ Adhara (local wins on a collision) |
| **Portal** | API key + workspace | Hard switch, one provider active at a time — see [Customer Portal](/docs/customer-portal) |
| **Scheduling** | API key + workspace ID + workspace slug | **No local content store at all** — `local` is a fixed, labeled demo (booking refused); real booking needs Adhara's availability engine |
| **Links** | Workspace slug | Hard switch, but a **whole-page swap**, not a merge — bio/socials/links all come from one backend at once |
| **Shop** | SDK installed + workspace slug | Content split like blog/events; checkout has **three real paths** — see [Commerce](/docs/commerce) |
| **Gallery** | API key + workspace ID (workspace slug alone isn't enough) | Content split; `local` itself has **two sub-sources** (disk vs. cloud bucket) — see [Media Gallery](/docs/media-gallery) |

Three features are **not** part of this toggle family at all, because their real shape
doesn't fit a local/Adhara switch:

- **Podcast** (`/podcast`) — episode data always comes from parsing a real RSS/Atom feed;
  there's no local content to switch away from. Only the *feed URL* is resolved (env var,
  or an Adhara `/links` entry tagged `category: "podcast"`).
- **Contact & newsletter** — "always local, additively synced": every submission saves
  locally first, unconditionally, and Adhara sync (a real form / a CRM lead) activates
  automatically once configured, but never gates the local save. There's deliberately no
  `GRAVITY_CONTACT_BACKEND` var — that would imply local is skippable, which it isn't.

See [Features](/docs/features) for what each feature actually does, and
[the SDK section](/docs/sdk) for how the Adhara SDK itself is treated.

---

<!-- https://www.edmecosystem.com/docs/sdk -->

## Two tiers, both optional

Adhara integration happens at two levels, and most features only need the first:

1. **Raw HTTP** (`src/lib/adhara.ts`) — public endpoints need no auth; authenticated ones
   need `ADHARA_API_KEY`. Used for blog/event reads, form/newsletter submission, and
   scheduling/links reads. These are plain `fetch()` calls against confirmed Adhara REST
   endpoints — no SDK required.
2. **The real SDK** (`@eimglobalsolutions/adhara-sdk`) — optional, and only for authenticated
   operations: multi-item commerce checkout, media gallery browsing, and form provisioning.
   The public storefront (catalog + single-item checkout) is raw HTTP too, so a site needs
   no SDK to sell.

## Never vendored

`@eimglobalsolutions/adhara-sdk` is a private-registry package. It is **never** added to
`package.json` — every call site imports it dynamically and degrades to the local JSON path
when it isn't installed:

```ts
export function getSdkClient(): Promise<AdharaSdkClient | null> {
  if (!sdkClientPromise) {
    sdkClientPromise = (async () => {
      try {
        // @ts-expect-error — optional external package, not a workspace dependency.
        const mod = await import('@eimglobalsolutions/adhara-sdk');
        const AdharaClient = mod.AdharaClient ?? mod.default;
        return new AdharaClient({ apiKey: process.env.ADHARA_API_KEY || '', baseUrl: baseUrl() });
      } catch {
        return null;
      }
    })();
  }
  return sdkClientPromise;
}
```

Install it yourself (from the private registry) when you're ready to go live with an
SDK-backed feature — the app runs and degrades correctly with or without it, on every deploy
target, including edge runtimes like Cloudflare Workers.

## "Layer on top of the SDK, don't reimplement it"

When a feature needs the SDK and the SDK is missing a method, or has one with the wrong
shape, the fix goes **at the SDK's own source** (a sibling repo), not as a workaround here.
This repo is a thin consumer layer, never a second implementation of Adhara's API surface.

That discipline has found and fixed real, confirmed gaps in the SDK — not guessed at
unconfirmed ones. Every one of these was found by reading the real backend route/schema
files directly and cross-checking against what the SDK claimed, then verified with a real
build + test run after the fix:

| Area | What was wrong | Fix |
|---|---|---|
| Commerce | `getPublicService()` was missing entirely, even though the backend route existed | Added, mirroring `getPublicProduct()`'s pattern |
| Commerce | Checkout request types claimed a multi-item `items: CartItem[]` shape that matches neither real checkout endpoint | Replaced with the two real, distinct shapes — public single-item and authenticated multi-item |
| Forms | `SubmitFormRequest` claimed a `{ data: ... }` body | Real backend requires `response_data`, keyed by each field's id |
| Leads | `LeadsResource.capture()` posted to `/public/leads/{workspaceSlug}` | Real endpoint is a bare `POST /public/leads`, workspace resolved from `workspace_id` in the body — a genuine backend inconsistency vs. every other `public/*` route, not a bug to route around |
| Media Gallery | No `MediaResource` existed at all — a fully missing resource, not a wrong-shaped method | Added `MediaResource` (folder/file listing), matching the real backend and the real frontend's own working consumer code |

## Real, confirmed extension points (found, not built)

A few real capabilities were discovered on the backend during this work that aren't wired up
yet — documented as genuine next steps, not guesses at maybe-existing features:

- **A full session-based public shopping cart API** (`POST/GET/DELETE /public/cart/{workspace_slug}`,
  `.../items`, `.../validate`, `.../checkout`) that would remove the public checkout path's
  current "exactly one distinct cart line" limit. The SDK doesn't wrap it yet; adopting it
  means moving the cart from this repo's client-side `localStorage` to an Adhara-hosted
  server session — a real architectural change, not a small patch.
- **A confirmed authenticated workspace-links REST API** (create/update/delete/reorder) with
  no SDK resource and no in-app admin UI calling it yet — this port only wires the public
  read side of `/links`.

## Extending it yourself

If you're adding a new Adhara-backed feature:

1. Check whether the SDK already has a resource for it (`client.<resource>`).
2. If it's missing or wrong, read the real backend's route + schema files directly — don't
   trust the SDK's types as ground truth without cross-checking.
3. Fix or add it at the SDK source, rebuild, and run its test suite.
4. Write a thin wrapper in `src/lib/adhara<Feature>.ts` here that degrades to `null`/empty
   when the SDK isn't installed or the call fails — follow `adharaCommerce.ts` or
   `adharaMedia.ts` as the pattern.
5. Wire it into a `src/services/*Store.ts` that resolves local vs. Adhara via
   `resolveFeatureBackend()` — see [Overview](/docs/overview).

---

<!-- https://www.edmecosystem.com/docs/features -->

Deep dives on the bigger features live on their own pages — [Customer Portal](/docs/customer-portal),
[Commerce](/docs/commerce), [Media Gallery](/docs/media-gallery), and
[Visual Editors](/docs/visual-editors). Everything else is here.

## Content & pages

| Feature | Route(s) | Backend story |
|---|---|---|
| **Block-driven pages** | `/`, `/about`, `/features` | Local JSON ↔ Adhara-mergeable per block; edited via inline click-to-edit or the builder canvas — see [The Content Model](/docs/content-model) |
| **Blog** | `/blog`, `/blog/[slug]` | Reads always merge local ∪ Adhara; writes (`npm run blog`) switch via `GRAVITY_BLOG_BACKEND` |
| **Events** | `/events`, `/event/[slug]`, `/portal/events` | Local ∪ Adhara merge once connected. The listing and every detail page are driven by the event's own Adhara settings: pinned/featured order, hero image, schedule, hosts and speakers, ticket tiers, capacity. Sign-up follows the event's registration mode and pricing — free/lead-capture registration, paid ticket checkout and donation checkout (Stripe, via Adhara's public event-checkout endpoint; needs the workspace's payment connection), a waitlist once full, and a link-out for listing-only events. `/event/[slug]` isn't edge-cached (live capacity + post-checkout state) |
| **Forms** | `/forms` | Contact + multi-step wizard demos, proxied to a real Adhara form. Includes a honeypot anti-spam field (`_hp` — the real field name the Adhara backend itself expects) |

## Site features

| Feature | Route(s) | Backend story |
|---|---|---|
| **Scheduling & booking** | `/scheduling`, `/schedule/[slug]` | No local content store — `local` is a clearly-labeled demo (sample meeting types, booking refused). Real availability/conflict checking only exists in Adhara |
| **Links (link-in-bio)** | `/links` | Whole-page swap, not a merge, once connected. Public read only — the authenticated write API exists on Adhara but has no in-app admin UI here yet |
| **Podcast** | `/podcast` | Not part of the toggle family — episode data always comes from parsing a real RSS/Atom feed via `rss-parser`, cached ~15 min. Feed URL: `GRAVITY_PODCAST_RSS_URL`, or an Adhara `/links` entry tagged `category: "podcast"` |
| **Contact & newsletter** | `/contact`, footer signup | Always saves locally first (`data/content/contact-submissions/`, `data/content/contacts.json`), then additively syncs to a real Adhara form / CRM lead once configured. Never gated on Adhara succeeding |
| **Media gallery** | `/gallery` | See [Media Gallery](/docs/media-gallery) |

## Platform

| Feature | Route(s) | Notes |
|---|---|---|
| **Admin dashboard** | `/admin` | Live "Feature backends" panel for every toggle-family feature, editable-page shortcuts, dev/Adhara auth status |
| **Customer portal** | `/portal/*` | See [Customer Portal](/docs/customer-portal) |
| **Shop / commerce** | `/shop/*` | See [Commerce](/docs/commerce) |
| **Visual editors** | Inline (floating button), builder canvas (`/admin/editor/build/<page>`) | See [Visual Editors](/docs/visual-editors) |

## Authentication

Real Adhara-backed admin login isn't implemented yet — the JS SDK's documented surface has
no confirmed user-auth (`client.auth.login`) resource for it. `GRAVITY_DEV_ADMIN=1` is the
supported local admin path until that endpoint is confirmed; **never set it in production**.
The customer portal has its own separate `GRAVITY_DEV_PORTAL=1` bypass — see
[Customer Portal](/docs/customer-portal).

## Deploy targets & storage

Vercel, Cloudflare, Google Cloud Run, and Netlify, each deploying to a real platform-native
runtime (a real Vercel Function, a real Cloudflare Worker — no Docker/proxy layer) — see
[Deploying](/docs/deploying). Content storage is pluggable across seven backends — see
[Storage](/docs/storage).

---

<!-- https://www.edmecosystem.com/docs/customer-portal -->

`/portal/*` is a full customer-facing area — authentication, onboarding, a course/lesson
system, community, events, meetings, certificates, downloadable resources, and memberships.
It isn't block-driven content, but it follows its own consistency rule worth knowing before
you touch it.

## The provider-interface pattern

Every portal capability is defined once, in the `PortalProvider` interface
(`src/services/portal/types.ts`), and implemented **twice**:

- `src/services/portal/local*.ts` — local JSON.
- `src/lib/adharaPortal.ts` — real Adhara, raw HTTP, confirmed endpoints, no SDK.

A page or API route calls `getPortalProvider()` from `src/lib/portal.ts` and never imports
either implementation directly, so it works unmodified against both.

**If you add a portal capability, add it to the interface first, then implement it in both
places.** An interface method with only one implementation type-checks fine and then throws
at runtime for whichever backend happens to be active — that's the one sharp edge in this
otherwise-clean pattern.

## Backend resolution

`GRAVITY_PORTAL_BACKEND=local|adhara` forces it; unset auto-detects `adhara` once **both**
`ADHARA_API_KEY` and `ADHARA_WORKSPACE` are set — see [Overview](/docs/overview) for how this
fits the shared toggle resolver.

## Session/auth guard

`verifyPortalSession` (`src/lib/portalAuth.ts`) is the one piece of portal logic that isn't
per-provider — it handles the auth precedence order across both backends. Read its docstring
before changing how a session is resolved or invalidated.

## Local dev bypass

`GRAVITY_DEV_PORTAL=1` opens `/portal` without a real customer login — it auto-provisions a
fixed local dev customer (`dev@local.test`). This is separate from `GRAVITY_DEV_ADMIN` (which
bypasses the *admin* dashboard, not the customer portal). **Never set it in production.**

## The sample course

A full 10-lesson "Building With AI" course ships as sample data — the exact same content
that's referenced from `/get-started`'s "Prefer a guided walkthrough?" section. It covers
installing an AI coding agent, cloning the repo, enough Git to be dangerous, running it
locally, making a first AI-assisted change, both visual editors, and shipping it live. Seed
it with:

```bash
npm run courses -- import docs/gravity/examples/portal/courses/building-with-ai.json
```

It's sample data, not part of the live site by default — import it once and it's there for
good, on your own machine or anyone else's copy of this repo. Working through it doubles as
a tour of the portal itself.

## Meetings (`/portal/meetings`)

Read-only: a list + detail view of meetings (calls, sessions, seminars, master classes) the
customer is on the attendee roster for, or that their membership tier has tier-gated access
to (e.g. a master class recording published to a whole tier) — visibility is entirely
server-side, nothing to filter again here. Detail view shows notes, highlights (key
takeaways / action items / goals), a linked transcript, and a recording link when present.
No registration/RSVP concept, unlike events — meetings are host-scheduled, not something a
customer opts into from the portal.

**Not SDK-wrapped, by design, matching every other portal capability** — Adhara's real Node
SDK does have a `MeetingsResource` (`client.meetings`), but it only covers the *admin* API
(`/api/v1/meetings/*`, API-key authenticated). The portal-facing API this page needs
(`/api/v1/portal/{workspace}/meetings/*`) is customer-session-scoped (a Bearer token from
`verifyPortalSession`, not an API key) — a different auth model the SDK's `HttpClient` isn't
built around, which is exactly why `adharaPortal.ts` uses raw `fetch()` for every portal
capability already (see "The provider-interface pattern" above). `local*.ts`'s
implementation is always empty, not fake demo data — same "capability split, not a content
split" reasoning as [Scheduling](/docs/overview): a meeting is inherently host-scheduled with
a real attendee roster, not something a site owner would plausibly hand-author as local JSON.

## Not built yet

Portal OAuth/social login isn't implemented in this port — see
[FAQ & Roadmap](/docs/faq).

---

<!-- https://www.edmecosystem.com/docs/commerce -->

`/shop` is new in this port — not in the Python original. A real storefront: products and
services, a client-side cart (`localStorage` — no server session needed for anonymous
shoppers), and checkout — local JSON by default, real **Adhara Commerce** when configured.

## A real SDK layer, not raw HTTP

Unlike blog/events/scheduling/links, the shop goes through the real Adhara SDK's `commerce`
resource (`src/lib/adharaCommerce.ts`), not `fetch()` against raw endpoints — checkout is
genuinely complex (payment sessions, line-item pricing), and the SDK already has that logic.
See [The Adhara SDK](/docs/sdk) for the two real gaps found and fixed there while building
this feature.

## Backend

- **Local** (default) — one JSON file per catalog item under `data/content/shop/items/*.json`
  (ships pre-seeded with 4 sample items spanning all 5 product types), edited via
  `npm run shop -- import <file>`.
- **Adhara** (`GRAVITY_SHOP_BACKEND=adhara`, or auto-detected once the SDK is installed +
  `ADHARA_WORKSPACE` is set) — real Products and Services, fetched via the SDK's
  `listPublicProducts`/`getPublicProduct`/`listPublicServices`/`getPublicService` (no API
  key needed for browsing).

## Three real checkout paths, tried in order

`shopStore.checkout()` tries these in order — which path is even reachable depends on what's
configured:

1. **Authenticated multi-item** (`ADHARA_API_KEY` set) — real cart checkout via the SDK's
   `createCheckoutSession`, Products only, priced by a specific `ProductPrice.id`. Whether
   Services can go through this endpoint isn't confirmed.
2. **Public single-item** (`ADHARA_WORKSPACE` only, no API key) — real checkout via
   `createPublicCheckout`, but only for a cart that resolves to exactly one distinct line
   item — Adhara has no public multi-item checkout endpoint yet.
3. **Local pending order** (always available) — `data/content/shop/orders/<id>.json`, status
   `pending`, no payment taken — for manual follow-up. Same honesty principle as
   scheduling's local demo mode: never claim something happened that didn't.

## Payment-provider agnostic

The checkout layer doesn't name a specific payment processor anywhere in this repo's code or
docs — Adhara's backend may support more than one in the future, and nothing here should
assume it's locked to one.

## A known, confirmed extension point

Adhara's backend also has a full session-based **public shopping cart API**
(`/public/cart/{workspace_slug}` — create/read/clear a cart, add/update/remove items,
validate, checkout) that would remove path 2's one-item limit for public storefronts. The
SDK doesn't wrap it yet, and adopting it means moving the cart from this repo's client-side
`localStorage` (`public/js/shop-cart.js`) to an Adhara-hosted server session — a real
architectural change, not a small patch. See [The Adhara SDK](/docs/sdk) for the full list of
confirmed-but-unbuilt extension points.

## Architecture

`src/lib/adharaCommerce.ts` (SDK calls) → `src/services/shopStore.ts` (catalog merge,
backend/checkout-path resolution) →
`src/pages/shop/{index,[slug],cart,checkout,checkout/confirmed,checkout/cancelled}.astro` +
`src/pages/api/shop/{catalog,checkout}.ts` + `public/js/shop-cart.js`.

---

<!-- https://www.edmecosystem.com/docs/media-gallery -->

`/gallery` is new in this port — not in the Python original. Photo galleries, one page with
client-side category tabs. It's the one feature whose "local" mode has two genuinely
different sub-sources, chosen automatically rather than by a second env var.

## Three sources

- **Local disk** (the zero-config default) — drop image files into `public/gallery/<name>/`;
  each subfolder becomes a gallery, named from its folder name. No database, no upload step,
  no CLI command — Astro serves the files directly as static assets. This is build-time
  content like theme CSS, not runtime-written storage: commit the images (or add them before
  `npm run build`) so they end up in the deployed build.
- **Cloud bucket** (automatic once this site's `ContentStore` backend is a cloud one rather
  than local disk — see [Storage](/docs/storage)) — galleries are read from
  `upload/gallery/<name>/` in that same bucket instead, reusing the exact pluggable storage
  mechanism already proven by the block editor's image uploads.
- **Adhara** (`GRAVITY_GALLERY_BACKEND=adhara`, or auto-detected once **both**
  `ADHARA_API_KEY` and `ADHARA_WORKSPACE_ID` are set — unlike events/links/shop, a workspace
  slug alone isn't enough) — every root-level folder in the workspace's real Media Gallery
  becomes a gallery, auto-discovered via a `listFolders()` call. No per-folder env var to
  hand-maintain.

## Why Adhara mode needs the API key

Confirmed against the real backend: there is no public, no-API-key, multi-folder
gallery-browsing endpoint. The one anonymous route that exists
(`/public/gallery/{share_token}`) is scoped to a single admin-shared folder for one-off
client delivery — a different feature entirely, not general marketing-page gallery browsing.
Real, site-wide gallery browsing always needs `ADHARA_API_KEY` server-side. Recommend scoping
the key to the `media:public` permission — the backend then silently restricts results to
files explicitly marked public, the safe default for anything embedded on a public page.

## A resource the SDK didn't have

The SDK had zero coverage of Adhara's Media Gallery system before this feature — not a
wrong-shaped method, a fully missing resource (its pre-existing `AssetsResource`/
`DigitalAsset` is a different system: gated downloadable files like PDFs/ebooks, zero
overlap). A `MediaResource` was added at the SDK's source — see
[The Adhara SDK](/docs/sdk) for the full "layer on top, fix at the source" pattern this
followed.

## Architecture

`sdk/node/src/resources/media.ts` (SDK) → `src/lib/adharaMedia.ts` (thin wrapper) →
`src/services/galleryStore.ts` (three-source resolution) → `src/pages/gallery.astro`. The
cloud-bucket path adds a `listMedia(prefix)` method to every `ContentStore` backend
(`src/stores/*.ts`) — the read-back counterpart to the `writeMedia()` every backend already
had.

---

<!-- https://www.edmecosystem.com/docs/visual-editors -->

Two visual editors, both operating on the exact same `Section[]` data described in
[The Content Model](/docs/content-model). Neither is a separate content system — a schema in
`src/content/blocks/*.json` is all either editor needs to know about a block type.

## Inline click-to-edit

A floating **✏️ button** appears in the bottom-right corner of any page rendering
block-driven content (home, about, features, once real content is published for them). Click
it to edit that page's sections directly, with a draft/publish flow. Client logic lives in
`public/js/inline.js`; the routing that decides which button appears where is
`src/lib/editbar.ts`.

Rich-text fields use a proper RTE in this editor; the builder canvas edits the same
`richtext` field as a plain textarea of raw HTML instead — both write the identical HTML
string back to the same field, just with different input UI.

## The builder canvas

`/admin/editor/build/<page>` — a full drag-and-drop canvas built on
[GrapesJS](https://grapesjs.com): reorder blocks, add/remove them, edit every field type
through a generated trait (settings) panel.

**This is schema-driven, not hand-registered.** `src/builder/componentTypes.ts` fetches
every block schema from `/api/admin/editor/block-schemas` at runtime and generates the
GrapesJS block, component type, and trait panel from it automatically. Adding a new block
type never requires writing a new `editor.Components.addType(...)` call — if you find
yourself doing that, the schema-driven factory is missing something, and that's the bug to
fix, not a reason to special-case a block.

Key files:

- `src/builder/main.ts` — GrapesJS init, load/save/publish wiring.
- `src/builder/componentTypes.ts` — schema → block/component-type/trait generation, JSON
  (de)serialization.
- `src/builder/traits.ts` — the custom trait types (`gv-textarea`, `gv-image`, `gv-list`)
  that back the non-trivial field types. Each manages its own DOM instead of relying on
  GrapesJS's default input-value wiring — read the file's own docstring for why, before
  adding a seventh field type.
- `src/builder/render.ts` — the canvas's live-preview HTML renderer. This is a **deliberate
  small duplication** of each block's real Astro component, not a shared abstraction —
  GrapesJS renders HTML strings, not Astro components, so there's no way around having both.
  Keeping them in sync is exactly what [Modifying an existing block type](/docs/content-model#modifying-an-existing-block-type)
  describes.

## Deliberately out of scope

The builder canvas has **no style manager** — block markup is the only thing that determines
how a block looks, precisely so a site owner can never drag a block off-theme by fiddling
with inline styles. A "Theme Tweaks" UI (the Python original's in-browser CSS-token override
panel) isn't built in this port either — see [FAQ & Roadmap](/docs/faq).

---

<!-- https://www.edmecosystem.com/docs/deploying -->

```bash
make setup                    # interactive menu
make deploy PLATFORM=vercel   # or gcp | cloudflare | netlify
```

Each `make deploy-*` prompts for anything missing (`SECRET_KEY`, persistent storage if none
is configured yet — defaulting to that platform's own storage option), saves answers to
`.env`, and prints the live URL.

## Vercel

```bash
make deploy-vercel
```

`@astrojs/vercel` builds a real Vercel Function — no config file needed for the default
case. Storage default: Vercel Blob.

**Connecting the repo straight to Vercel's own git integration also works** — Import Project
from the Vercel dashboard (or GitLab), no `make deploy-vercel` and no env vars configured at
all. `astro.config.mjs` auto-detects it's building on Vercel from Vercel's own `VERCEL`
system env var and picks the right adapter automatically — see
[Project Structure](/docs/project-structure#deploy-targets). `make deploy-vercel` still adds
real value on top of that (persistent storage provisioning, an actual `SECRET_KEY`, syncing
Adhara config) — it's just no longer *required* for the site to build and serve correctly.
`SECRET_KEY` specifically isn't read anywhere in this Node port today (no local session
signing exists yet — admin auth validates a real Adhara token instead), so a deploy with it
unset works fine; it's asked for as forward-looking best practice, carried over from the
Python original where it's load-bearing, not because anything here currently depends on it.

## Google Cloud Run

```bash
make deploy-gcp
```

Builds and deploys this repo's `Dockerfile` via Artifact Registry + Cloud Run. Requires
`gcloud` + Docker. Storage default: Google Cloud Storage.

## Cloudflare

```bash
make deploy-cloudflare
```

Deploys a **real Cloudflare Worker** via `@astrojs/cloudflare` — no Docker, no container, no
proxy layer. (The Python original has to run Flask/Gunicorn behind a Cloudflare *Container* +
Durable Object, since Workers' V8-isolate runtime can't run Python; Astro compiles straight
to a Worker, a genuine simplification this port gets for free.) Storage default: Cloudflare
R2.

## Netlify

*(new — not in the Python original)*

```bash
make deploy-netlify
```

`@astrojs/netlify` builds Netlify Functions + edge middleware automatically. Storage
default: Netlify Blobs (zero-provisioning — auto-available once deployed on Netlify).

## Persistent storage

Every target above has an ephemeral filesystem by default — locally-stored content and
uploaded media need one of the storage backends in [Storage](/docs/storage) to survive across
deploys/restarts. `make deploy-*` prompts you through provisioning it; set the relevant env
vars yourself beforehand to skip that prompt, or set `GRAVITY_STORAGE_SKIP=1` to opt out of
the storage wizard entirely and stay on ephemeral local files.

## Edge caching

Public, non-personalized pages are cached at the edge, configurable via `GRAVITY_EDGE_CACHE_TTL`
(default `60` seconds) and `GRAVITY_EDGE_CACHE_SWR` (stale-while-revalidate window, default
`300` seconds) — set to `0` to disable entirely. This is the real fix for the concern behind
it: several cached routes (blog, events, links, shop, scheduling's index, podcast, gallery)
read from Adhara on every render — without caching, that's a live Adhara round trip on *every
single visit*. A first request renders normally and gets cached; every request after that,
until the TTL expires, is served without touching Adhara at all.

This uses **Astro's own built-in cache system** (`cache`/`routeRules` in `astro.config.mjs`,
stable in this Astro version, not something hand-rolled for this project) — not a bespoke
mechanism, and not just HTTP headers hoping a CDN respects them. Each deploy target gets its
own **real** cache provider, resolved automatically at build time from `DEPLOY_TARGET`, the
same pattern as adapter selection:

| Target | Provider | What it actually is |
|---|---|---|
| `vercel` | `@astrojs/vercel/cache` | Vercel's real CDN (`Vercel-CDN-Cache-Control` / `Vercel-Cache-Tag`) |
| `netlify` | `@astrojs/netlify/cache` | Netlify's durable cache (`Netlify-CDN-Cache-Control` / `-Cache-Tag`) |
| `cloudflare` | `@astrojs/cloudflare/cache` | Cloudflare Workers' built-in cache API, auto-tagged by path — **no Cloudflare dashboard Cache Rule needed**, unlike a plain Cache-Control-header-only approach |
| `node` | `astro/cache/memory` | An in-process memory cache — there's no CDN in front of a bare Node/Docker/Cloud Run deploy by default, so this is what actually avoids the Adhara round trip there. Still emits standard cache headers too, so a real CDN placed in front (Cloud CDN, etc.) benefits as well |

Verified directly, not assumed: a first `GET` to a cached route returns `X-Astro-Cache: MISS`;
a second one within the TTL returns `X-Astro-Cache: HIT` (in-process provider) with no
re-render. `/admin`, `/portal`, `/api/*`, cart/checkout, and `/schedule/[slug]` (which shows
live booking availability — caching it would show stale open slots, a real correctness bug,
not just a staleness inconvenience) are deliberately never cached. `/docs/*` isn't in the
cache config at all — those pages are prerendered at build time, not server-rendered per
request, so route-level caching doesn't apply to them.

**Caching is always fully disabled under `npm run dev`** regardless of the env vars — this is
Astro's own built-in behavior, not something this project added, so local development never
shows stale content. Route patterns and per-route tags live in `astro.config.mjs`'s
`CACHEABLE_ROUTES`/`ROUTE_TAGS` — add a new public, non-personalized route there if you add
one, following the existing pattern.

**A known, deliberate gap**: routes are tagged by content type (`blog`, `events`, `shop`, ...)
specifically so a future write path could call `cache.invalidate({ tags: ['blog'] })` right
when a post is published, purging the cache immediately instead of waiting out the TTL — the
tags are wired up and ready for this, but nothing calls `invalidate()` yet. That needs request
context (`cache.invalidate()` lives on the Astro request/middleware context) threaded into
`blogStore.ts`/`eventStore.ts`/etc.'s write paths, which today are also called from plain CLI
scripts with no request context at all — a real design question, not a small patch, so it's
left as a documented next step rather than guessed at.

## Deploying from a prompt (agent shells)

All four `deploy_*.sh` scripts, and the storage-provisioning wizard they share
(`scripts/lib/storage_setup.sh`), are safe to run with stdin **not** a TTY — the shape an
agent shell (Claude Code, Codex, CI) runs commands in. Every interactive prompt degrades to a
sensible default instead of hanging or hard-failing:

- **`SECRET_KEY`** auto-generates instead of failing with "SECRET_KEY is required."
- **Storage** auto-provisions the platform's recommended backend (Vercel Blob / GCS / R2 /
  Netlify Blobs) instead of skipping with just a warning. Set `GRAVITY_STORAGE_SKIP=1` to
  opt out instead. A backend that needs real credentials it can't invent (Cloudflare R2's
  access key/secret) fails cleanly with the exact env vars to set, rather than hanging on a
  `read` that will never get input — and that failure degrades to the local-storage fallback
  rather than aborting the whole deploy.

## Git integration

```bash
make push-repo                                    # PROVIDER=github|gitlab, default github
make deploy PLATFORM=vercel VERCEL_LINK_GIT=1      # connect the pushed repo to Vercel
```

`make push-repo` (`scripts/push_repo.sh`) creates a GitHub or GitLab repository via the
`gh`/`glab` CLI (needs one of them already authenticated — see
[Install Your Tools](/install-your-tools)) and pushes this code to it — safe to re-run any
time to push the latest commit. If this repo's `origin` still points at the shared
open-source template (a fresh `git clone` of it does), it's renamed to `upstream` first so
you keep the ability to pull template updates, and a new repo of your own is created instead
of pushing into the shared template.

Not run automatically by anything else here — it's opt-in, paired with `VERCEL_LINK_GIT=1`
on `deploy_vercel.sh` (Vercel only, for now) to connect the pushed repo to the Vercel
project, so a future `git push` triggers an automatic rebuild there instead of needing to
re-run the deploy script by hand.

## Reference

Full env var and CLI command tables live in [Environment Variables](/docs/environment-variables)
and [CLI Reference](/docs/cli-reference).

---

<!-- https://www.edmecosystem.com/docs/environment-variables -->

`.env.example` in the repo root is the canonical, always-current list — this page mirrors it
in table form for quick lookup. Copy it to `.env` and fill in what you need; everything has a
sensible default or degrades gracefully when unset.

## Core

| Variable | Default | Description |
|---|---|---|
| `SECRET_KEY` | `change-me` | Session secret — change in production |
| `GRAVITY_ROOT` | cwd | Base path for local content/uploads. Docker/Cloud Run set this to `/app` automatically |
| `GRAVITY_TEMPLATE` | `gravity` | Active theme — `gravity` (dark, default) or `clarity` (light) |
| `GRAVITY_HOST_PORT` | `3001` | Host-side port for `make dev`/`make up`/`make editor` |
| `GRAVITY_DEV_ADMIN` | unset | `1` bypasses admin auth for local editing. **Never set in production** |
| `GRAVITY_DEV_PORTAL` | unset | `1` opens `/portal` without a real customer login. **Never set in production** |

## Content store

See [Storage](/docs/storage) for the full backend explanation.

| Variable | Backend it selects |
|---|---|
| `GRAVITY_STORE_BACKEND` | Force one explicitly: `local`, `gcs`, `s3`, `azure`, `r2`, `vercel_blob`, `netlify_blob` |
| `GRAVITY_SITE_BUCKET` | Google Cloud Storage |
| `GRAVITY_S3_BUCKET` + `AWS_REGION` | AWS S3 (standard AWS credential chain otherwise) |
| `GRAVITY_AZURE_CONTAINER` + `AZURE_STORAGE_CONNECTION_STRING` | Azure Blob Storage |
| `GRAVITY_R2_BUCKET` + `CLOUDFLARE_ACCOUNT_ID` + `R2_ACCESS_KEY_ID` + `R2_SECRET_ACCESS_KEY` + `GRAVITY_R2_PUBLIC_URL` | Cloudflare R2 |
| `BLOB_READ_WRITE_TOKEN` | Vercel Blob (auto-injected once a store is linked) |
| `NETLIFY` (auto-set) / `NETLIFY_BLOBS_SITE_ID` + `NETLIFY_BLOBS_TOKEN` | Netlify Blobs |
| `GRAVITY_SITE_PREFIX` | Scopes every read/write/list to a subdirectory, for sharing one bucket/root across multiple site instances |

## Adhara connection

| Variable | Used for |
|---|---|
| `ADHARA_API_URL` | Base API URL (defaults to Adhara's hosted API) |
| `ADHARA_API_KEY` | Authenticated requests (writes, admin-scoped reads) |
| `ADHARA_WORKSPACE` | Workspace **slug** — public reads (events, links, scheduling, shop browsing) |
| `ADHARA_WORKSPACE_ID` | Workspace **UUID** — required alongside the API key for authenticated calls (scheduling, gallery, form provisioning) |

## Per-feature backend toggles

All seven auto-detect from whatever Adhara config is present when left unset. See
[Overview](/docs/overview) for exactly what each one needs and how local/Adhara relate for
that feature.

| Variable | Feature |
|---|---|
| `GRAVITY_BLOG_BACKEND` | Blog writes (reads always merge local ∪ Adhara regardless) |
| `GRAVITY_EVENTS_BACKEND` | Events |
| `GRAVITY_PORTAL_BACKEND` | Customer portal |
| `GRAVITY_SCHEDULING_BACKEND` | Scheduling & booking |
| `GRAVITY_LINKS_BACKEND` | Links (link-in-bio) |
| `GRAVITY_SHOP_BACKEND` | Shop / commerce |
| `GRAVITY_GALLERY_BACKEND` | Media gallery |

## Not toggles — always-local or no-local-content features

| Variable | Feature |
|---|---|
| `GRAVITY_PODCAST_RSS_URL` | Podcast feed URL — see [Features](/docs/features) |

Contact and the newsletter signup have no env vars of their own beyond the shared `ADHARA_*`
ones above — see [Overview](/docs/overview#every-feature-resolves-and-behaves-differently--by-design).

## Edge caching (read at build time, in `astro.config.mjs`)

| Variable | Default | Description |
|---|---|---|
| `GRAVITY_EDGE_CACHE_TTL` | `60` | Seconds a cached public page is served fully fresh. `0` disables edge caching entirely |
| `GRAVITY_EDGE_CACHE_SWR` | `300` | Extra seconds a stale cached response is served while a fresh one renders in the background |

Unlike everything else on this page, these are read in `astro.config.mjs`, not by the running
app — changing them needs a rebuild + redeploy to take effect. Always fully disabled under
`npm run dev`. See [Deploying](/docs/deploying#edge-caching) for what's actually cached and why.

## Deploy-script-only (not read by the app)

These only matter when running `scripts/deploy_*.sh` / `scripts/push_repo.sh` — see
[Deploying](/docs/deploying).

| Variable | Effect |
|---|---|
| `GRAVITY_STORAGE_SKIP=1` | Skip the storage-provisioning wizard during a deploy, stay on ephemeral local files |
| `VERCEL_LINK_GIT=1` | Connect this repo's git remote to the Vercel project during `deploy_vercel.sh` |
| `PROVIDER=github\|gitlab`, `REPO_NAME`, `REPO_VISIBILITY` | `scripts/push_repo.sh` — which provider/name/visibility to create |

---

<!-- https://www.edmecosystem.com/docs/cli-reference -->

## npm scripts

| Command | What it does |
|---|---|
| `npm run dev` | Astro dev server on `$GRAVITY_HOST_PORT` (default `3001`), hot reload |
| `npm run build` | `astro build` with the default (`node`) adapter |
| `npm run build:node` / `:vercel` / `:cloudflare` / `:netlify` | Build with a specific deploy adapter — see [Deploying](/docs/deploying) |
| `npm run preview` | Preview a production build locally |
| `npm run start` | Run a built server directly (`node ./dist/server/entry.mjs`) — no dev server |
| `npm run content -- <cmd>` | Import/manage block-driven page content |
| `npm run blog -- <cmd>` | Import/manage blog posts |
| `npm run events -- <cmd>` | Import/manage events |
| `npm run courses -- <cmd>` | Import/manage portal courses |
| `npm run links -- <cmd>` | Import/manage the `/links` page |
| `npm run shop -- <cmd>` | Import/manage shop catalog items |
| `npm run contact -- <cmd>` | Manage contact form provisioning — see below |

Every `<feature> -- import <file>` command reads a JSON file and writes it through that
feature's `*Store.ts`, which goes through `getStore()` — see [Storage](/docs/storage). Sample
files for all of them live under `docs/gravity/examples/`.

### `npm run contact -- create-adhara-form`

Provisions and publishes the real Adhara "Contact" form (name/email/message, each field
mapped to a CRM lead field, `create_lead: true`) via the real Adhara SDK. Needs
`ADHARA_API_KEY` + `ADHARA_WORKSPACE_ID` + the SDK installed. A one-time setup step — checks
first and no-ops if the form already exists. Submitting `/contact` before running it just
means the Adhara sync silently no-ops; the local copy always still saves. See
[Overview](/docs/overview) for the "always local, additively synced" pattern this is part of.

## make targets

### Local development

| Target | What it does |
|---|---|
| `make dev-native` | `npm run dev` — fast hot-reload inner loop, no Docker (recommended) |
| `make dev` | `docker compose up` — foreground, matches the prod container |
| `make up` | `docker compose up -d` |
| `make down` | `docker compose down` |
| `make logs` | `docker compose logs -f` |
| `make run-local` | `npm run build:node`, then run the built server directly (no Docker) |
| `make build` | `docker compose build` |

### Editor / content

| Target | What it does |
|---|---|
| `make editor` | Build + run with admin/portal bypass ON, seed sample pages/blog/events/courses/links/shop |
| `make editor-off` | Admin bypass OFF |
| `make seed [SEED=f] [SEED_BLOG=f] [SEED_EVENTS=f] [SEED_COURSES=f] [SEED_LINKS=f] [SEED_SHOP=f]` | Import content into the running container (defaults: sample files under `docs/gravity/examples/`) |

### Themes

| Target | What it does |
|---|---|
| `make theme-list` | List themes under `public/themes/` |
| `make theme-create THEME=<name>` | Not yet implemented — prints guidance, see [Theming](/docs/project-structure#theming) |
| `make theme-extract ZIP=<file>` | Not yet implemented — prints guidance |

### Deploy

| Target | What it does |
|---|---|
| `make setup` | Interactive menu: run locally, or deploy anywhere |
| `make deploy PLATFORM=<name>` | `gcp \| vercel \| cloudflare \| netlify` (default: vercel) |
| `make deploy-gcp` / `deploy-vercel` / `deploy-cloudflare` / `deploy-netlify` | Run one platform's deploy script directly |

### Git (optional)

| Target | What it does |
|---|---|
| `make push-repo` | Create a GitHub/GitLab repo and push this code (`PROVIDER=github\|gitlab`) |

Pair with `make deploy PLATFORM=vercel VERCEL_LINK_GIT=1` to connect the repo in Vercel too
— see [Deploying](/docs/deploying#git-integration).

### Docker image / misc

| Target | What it does |
|---|---|
| `make push` / `pull` / `tag` | Docker image ops against `$(IMAGE_NAME)` |
| `make generate-key` | openssl self-signed cert under `./security/` |

Run `make help` any time for the same reference, printed from the terminal.

---

<!-- https://www.edmecosystem.com/docs/faq -->

## Do I need Adhara to use this?

No. Every feature works against local JSON files with zero external services, zero API
keys, zero account. Adhara is an optional upgrade path, connected feature by feature — see
[Overview](/docs/overview).

## Is this a 1:1 port of the Python original?

No — this is a **core-first v1**. Everything content-related (blog, events, portal,
scheduling, links, forms) is ported. A few things are new to this port and didn't exist in
Python at all: a real e-commerce storefront via the Adhara Commerce SDK, a podcast page, a
media gallery, Netlify as a fifth deploy target, and an idempotent "install your tools"
script. A handful of things are deliberately deferred — see the roadmap below.

## Why does `/admin` need `GRAVITY_DEV_ADMIN=1` locally?

Real Adhara-backed admin login isn't implemented yet — the documented SDK surface has no
confirmed user-auth (`client.auth.login`) resource. `GRAVITY_DEV_ADMIN=1` is the supported
local admin path until that's confirmed. **Never set it in production.**

## Can I add an eighth cloud storage backend?

Yes — implement the `ContentStore` interface in a new `src/stores/<name>.ts`, register it in
`src/stores/index.ts`'s `BUILDERS` map, and add its auto-detect env var. See
[Storage](/docs/storage).

## The SDK is missing something I need. What do I do?

Don't work around it here — fix it at the SDK's source (a sibling repo), the same way six
real gaps were found and fixed while building this project's Adhara-backed features. See
[The Adhara SDK](/docs/sdk).

## Roadmap / known gaps

Deliberately out of scope for this v1, roughly in the order they'd be worth adding:

1. **Real Adhara admin login** — see above.
2. **Portal OAuth/social login** — see [Customer Portal](/docs/customer-portal).
3. **Theme Tweaks UI** — the Python original's in-browser CSS-token override panel; not
   built here (the builder canvas covers block content/layout, not theme-wide styling).
4. **Paid event ticket checkout** — free-event registration is real (see
   [Features](/docs/features#events)); Adhara's own public registration endpoint refuses
   paid-tier events, and this port doesn't attempt ticket checkout on top of it (needs Adhara
   Commerce, same gap as paid membership tiers below).
5. **Paid membership tiers** — present in the Python original, not attempted here (needs
   Adhara Commerce).
6. **Links-page admin write API** — Adhara's authenticated create/update/delete/reorder
   endpoints for links are confirmed but not wired up (no in-app admin UI calls them yet).
7. **A public, session-based multi-item shopping cart** on Adhara's real backend — confirmed
   to exist, not yet wrapped by the SDK. See [Commerce](/docs/commerce).

## Where do I report a bug or ask something not covered here?

Open an issue against this repo, or — if you're an AI coding agent reading this — check
[`/llms-full.txt`](/llms-full.txt) for the complete documentation corpus in one file before
guessing at an answer.

---