@dreamtree-org/landing-kit 0.7.2 → 0.9.0

package/MIGRATION.md

@@ -118,3 +118,58 @@ Nothing changes unless you opt in:
 - `fillPage(template, page)` from `/server`: the template fill `prerenderPages` does, as a string.
   Keep a copy of the template (prerenderPages overwrites `landing.html`) and an SSR bundle to
   re-render pages with live data, e.g. CMS-driven pricing.
+
+## 0.8.0 — Platform admin console contract (additive)
+
+Six products hand-roll a separate Platform console: procurementpro, firepro, venturepro, MerchantPro, PracticePro and fitweavepro. TaskPro and billpro bolt one onto the app instead. 0.8.0 starts replacing these copies with one console:
+
+- **[PLATFORM-API.md](./PLATFORM-API.md)**: the HTTP contract, taken from procurementpro's `app/api/platform/**` (the reference console). Rows marked *shipped* are what procurementpro serves today. Rows marked *v1.1* are new (TOTP login, `GET /me`, audit, plans and subscriptions, settings, support access, domains); the console shows each one only when `GET /me` advertises it.
+- **`@dreamtree-org/landing-kit/platform`**: `createPlatformClient` replaces procurementpro `components/platform/api.ts` (`pfetch`, `ApiError`) and the platform half of `components/csrf-fetch.tsx`. `createStepUp` replaces the retry logic in `components/platform/step-up.tsx`.
+
+| Before (per product) | After |
+|---|---|
+| `components/platform/api.ts` `pfetch(url, { json })` | `api.request(path, { json })` / `api.get/post/patch/put/del` |
+| `ApiError` | `PlatformApiError` (same `status`, `code`) |
+| hard-coded `/api/platform/...` and `/platform/login` | `createPlatformClient({ basePath, loginPath })` |
+| global `fetch` patch adding `x-csrf-token` from `pp_platform_csrf` | built into the client (`csrfCookie`, or any `*_platform_csrf`) |
+| `StepUpProvider` retry loop | `createStepUp(api, ask)`; the provider keeps only the dialog |
+
+Nothing changes for products that don't use it. The server half, `createPlatformApi` with the `./next` and `./express` adapters, ships in `@dreamtree-org/tenancy` 0.4.0. The React console (`PlatformConsole`, `PlatformShell`, `PlatformLogin`, views) ships next, on top of this client.
+
+### 0.8.0: the React console
+
+`PlatformConsole` replaces procurementpro `components/platform/*`: shell, overview, companies, the new-company wizard, company detail, admins, step-up and login. firepro's copy is replaced the same way, including its security page.
+
+| Before | After |
+|---|---|
+| `platform-shell.tsx` (hard-coded "Dreamtree" brand and nav) | `PlatformShell` on twreact `AppShell`. Brand comes from `dreamtree.brand.json`; nav comes from features and role. |
+| `overview-view.tsx`, `companies-view.tsx`, `new-company-wizard.tsx`, `company-detail.tsx`, `platform-admins-view.tsx` | built-in views (same API calls, same flows) |
+| `step-up.tsx` | `StepUpProvider` / `useSensitive` (password, or TOTP once enrolled) |
+| `platform-login.tsx` | `PlatformLogin` (password, then the authenticator code) |
+| `ui.tsx` (`StatusPill`, `OneTimeSecret`, `InspectResult`, ...) | exported from `./platform` |
+| `jobs-view.tsx` | stays in the product for now, mounted with `pages={[{ path: 'jobs', feature: 'jobs', render }]}` and as a `companyTabs` entry |
+| procurementpro's `@/components/common` (`PageHeader`, `DataTable`, `Pill`) | twreact `PageHeader`, `Table`, `StatusPill`, `EmptyState`, `ErrorState`, `LoadingState` |
+| `/platform/companies/new`, `/platform/companies/[id]`, ... (one Next page each) | one `app/platform/(console)/[[...path]]/page.tsx` |
+
+**New in the console:**
+
+- Audit log page with CSV export.
+- Security page for setting up an authenticator, plus the enrollment gate in front of the rest of the console.
+- Role selection when adding an admin; reset an admin's authenticator.
+- Credential-custodian "Reveal URL" with a reason, audited.
+
+**Not in the console yet:** plans and subscriptions, platform settings, support access and domains. Their server endpoints come first (tenancy). The nav shows them only when `GET /me` advertises them.
+
+## 0.9.0 — store documents (additive)
+
+A store's landing, listing and product pages, its header and footer, and its product card are now one
+version-2 document (`validateStore` from `/schema`). Nothing changes for apps that keep version-1 tenant pages.
+
+- To adopt it, run each stored v1 page through `migrateStore(page)`. It becomes `pages.home`, and the listing
+  and product pages get their default templates. `validateStore` migrates a v1 page itself, so an app can
+  switch over on its next save.
+- Listing and product pages are templates whose blocks are either app **slots** (`filters`, `results`,
+  `gallery`, `buy_box`…, rendered by the app through `TemplateRegion`'s `slots`) or ordinary content sections.
+  Required slots cannot be hidden or removed.
+- `safeHref` now rejects links containing a backslash, and registry lookups (`blockDef`, `templatePage`) ignore
+  inherited keys, so `__proto__` or `constructor` is an unknown type.

package/PLATFORM-API.md

@@ -0,0 +1,213 @@
+# Platform console HTTP contract (v1)
+
+The shared Platform (super-administrator) console in `@dreamtree-org/landing-kit/platform` talks to the
+server only through this contract. The server side is `createPlatformApi` in `@dreamtree-org/tenancy`,
+mounted with `./next` (`app/api/platform/[...path]/route.ts`) or `./express` (`app.use('/api/platform', …)`).
+A product that implements these endpoints itself gets the same console.
+
+**Server status.** `@dreamtree-org/tenancy` 0.4.0 implements everything marked shipped, plus these v1.1 items: TOTP, throttle, rotation, `/me`, roles and audit. Plans, settings, support access and domains come next.
+
+The contract was taken from procurementpro's `app/api/platform/**`, the reference console. Paths are
+relative to the base path, `/api/platform` by default (`createPlatformClient({ basePath })`).
+
+**Status column:**
+- **shipped**: procurementpro serves it today, and the console depends on it.
+- **v1.1**: new in this contract. The console hides the feature until the server reports it in `GET /me`.
+
+## Conventions
+
+- **Body.** JSON in and out (`Content-Type: application/json`). The one exception is the CSV export.
+- **Errors.** Any non-2xx response has the body `{ "error": string, "code"?: string }`. `error` is safe to
+  show to the user.
+  - It never contains a database URL. The server scrubs `mysql://…` and similar.
+  - It never contains a secret, a key or a password hash.
+- **401** means there is no platform session. The console then goes to the login page.
+- **403 with `code: "STEP_UP_REQUIRED"`** means the action needs a fresh confirmation.
+  1. The console asks the admin to confirm: their password, or a TOTP code once TOTP is enrolled.
+  2. It sends `POST /auth/confirm`.
+  3. It retries the original request once.
+
+  Rows marked **step-up** below require this.
+- **403 with `code: "FORBIDDEN"`** means the admin's role doesn't allow the action (v1.1 role map).
+- **403 with `code: "TOTP_ENROLLMENT_REQUIRED"`** means the session hasn't been verified with an authenticator yet (v1.1).
+  - Until it is, only `GET /me`, `POST /me/totp`, `POST /auth/confirm` and `POST /auth/logout` work.
+  - The console shows the enrolment screen.
+- **403 with `code: "CSRF_INVALID"`** means the CSRF header is missing or stale. Reload the page.
+- **429 with `code: "RATE_LIMITED"`** means too many failed sign-in, code or step-up attempts.
+- **501 with `code: "NOT_IMPLEMENTED"`** means this server has no implementation for that action. The console shows it as unavailable.
+- **CSRF.** Every non-GET request carries the `x-csrf-token` header. Its value is the platform CSRF cookie
+  `<prefix>_platform_csrf`, which the server sets at login. The cookie prefix is per product, e.g. `pp`
+  for procurementpro.
+- **Sessions are a separate identity realm from tenant users.**
+  - The session cookie is httpOnly: `<prefix>_platform_session`.
+  - Idle timeout is 15 minutes; the absolute limit is 8 hours.
+  - **v1.1:** the idle window slides only inside the privileged 15-minute tier and never past the absolute limit. The token is new at every login and rotates on step-up and TOTP enrollment.
+- **Secrets.** One-time secrets (new passwords, a revealed DB URL) are returned exactly once, with
+  `Cache-Control: no-store`.
+- **IDs.** All ids are opaque strings.
+- **Timestamps.** ISO-8601 strings, or `null`.
+
+## Session and identity
+
+| Method | Path | Body / query | 200 response | Notes | Status |
+|---|---|---|---|---|---|
+| POST | `/auth/login` | `{ email, password }` | `{ ok: true, mfa: "none" \| "required" \| "enroll", ticket?: string, needsFactorEnrollment: boolean }` | Sets the session and CSRF cookies when `mfa` is `"none"` or `"enroll"`. 401 for wrong credentials (same message whether or not the email exists). 429 when throttled. | shipped (`mfa`, `ticket`, 429: v1.1) |
+| POST | `/auth/totp` | `{ ticket, code }` | `{ ok: true }` | Second factor after `mfa: "required"`. Sets the cookies. | v1.1 |
+| POST | `/auth/logout` | — | `{ ok: true }` | Revokes the session and clears both cookies. | shipped |
+| POST | `/auth/confirm` | `{ password }`, or `{ code }` once TOTP is enrolled | `{ ok: true }` + rotated cookies | Step-up, valid 5 minutes. A wrong secret answers 401 `STEP_UP_FAILED` (audited as `platform.stepup.failed`). | shipped (`code`, rotation: v1.1) |
+| GET | `/me` | — | `PlatformMe` | Who is signed in, their permissions, and which optional features this server has. Open to enrollment-only sessions. | v1.1 |
+| POST | `/me/totp` | `{ action: "begin" }` → `{ secret, otpauthUrl }`; `{ action: "verify", code }` → `{ ok: true, enrolled: true }` + rotated cookies | — | Enrol one's own authenticator. A lost device is reset by another admin (`admins/:id` `reset-totp`). **step-up**; the login itself counts for 5 minutes. | v1.1 |
+
+`PlatformMe` has this shape:
+
+```json
+{
+  "admin": { "id": "…", "email": "…", "roles": ["superadmin"], "totpEnrolled": true },
+  "permissions": ["companies.read", "companies.write", "admins.write", "jobs.write", "db.reveal", "plans.write", "settings.write", "support.grant"],
+  "access": { "console": true, "stepUpFresh": false },
+  "features": { "jobs": true, "plans": true, "settings": true, "support": true, "domains": true, "audit": true },
+  "app": { "key": "procurementpro", "name": "ProcurementPro", "companyLoginPath": "/c/:slug/login" }
+}
+```
+
+**Roles.** `superadmin` holds every permission. `support` holds `companies.read`, `admins.read`, `jobs.read`, `audit.read`, `plans.read` and `support.request`.
+
+Until `/me` exists, the console falls back to the shipped feature set (overview, companies, admins, and
+jobs when `GET /jobs` answers `enabled: true`).
+
+## Overview
+
+| Method | Path | Response | Status |
+|---|---|---|---|
+| GET | `/overview` | `{ counts: { total, active, setup, suspended, archived, failedJobs, dbFailures }, attention: CompanyRow[], recent: AuditEvent[], provisioner: { ok, configured, principal?, error? } }` | shipped |
+
+## Platform admins
+
+| Method | Path | Body | Response | Notes | Status |
+|---|---|---|---|---|---|
+| GET | `/admins` | — | `{ admins: PlatformAdmin[], me: string }` | `me` is the caller's admin id | shipped |
+| POST | `/admins` | `{ email, roles? }` | `{ ok, email, password }` | One-time password. **step-up** | shipped (`roles`: v1.1) |
+| POST | `/admins/:id` | `{ action: "reset-password" \| "disable" \| "enable" \| "reset-totp" }` or `{ action: "set-roles", roles }` | `{ ok, password? }` | You can't disable yourself, reset your own TOTP or change your own roles. The last active admin and the last superadmin are kept. **step-up** | shipped (`reset-totp`, `set-roles`: v1.1) |
+
+## Companies
+
+| Method | Path | Body / query | Response | Notes | Status |
+|---|---|---|---|---|---|
+| GET | `/companies` | `?q=&status=` | `{ companies: CompanyRow[] }` | Newest first, at most 500 | shipped |
+| POST | `/companies` | `{ displayName, slug, branch: { code, name }, database: { mode: "managed" } \| { mode: "external", url }, admin?: { fullName, email, phone? } }` | `{ company, job, admin? }` | Provisions the company. `admin.password` is one-time. | shipped |
+| GET | `/companies/slug-available` | `?slug=` or `?name=` | `{ slug, available, reason? }` | | shipped |
+| GET | `/companies/:id` | — | `{ company: CompanyDetail, users: CompanyUser[] }` | | shipped |
+| PATCH | `/companies/:id` | `{ displayName?, slug?, status? }` | `{ ok, company }` | Changing `slug` or `status` needs **step-up** | shipped |
+| GET | `/companies/:id/activity` | — | `{ jobs: ProvisioningJob[], events: AuditEvent[] }` | | shipped |
+| POST | `/companies/:id/provision` | `{ database?, admin? }` | `{ mode, job, admin?, adminError? }` | Finishes a draft or failed setup | shipped |
+| GET | `/companies/:id/admins` | — | `{ admins: CompanyUser[] }` | Read from the company's own database | shipped |
+| POST | `/companies/:id/admins` | `{ fullName, email, phone? }` | `{ ok, email, password }` | One-time password | shipped |
+| POST | `/companies/:id/admins/:userId` | `{ action: "reset-password" \| "disable" \| "enable" }` | `{ ok, password? }` | **step-up** | shipped |
+| POST | `/companies/:id/branches` | `{ code, name }` | `{ ok, branch }` | Mirrored into the company database | shipped |
+| PATCH | `/companies/:id/branches/:branchId` | `{ name?, status? }` | `{ ok }` | | shipped |
+| GET | `/companies/:id/database` | — | `DatabaseSummary` (redacted: host and db name only) | | shipped |
+| POST | `/companies/:id/database` | `{ action: "test" \| "sync" }` or `{ action: "replace", url }` | `{ ok, … }` | `replace` needs **step-up** | shipped |
+| PUT | `/companies/:id/database` | `{ action: "reveal", reason }` | `{ url }` | Needs credential custodian + **step-up** + a reason of 8+ characters. The audit event is written before the URL is read. `no-store`. | shipped |
+| POST | `/databases/inspect` | `{ url, companyId? }` | `InspectResult` | Checks a candidate database. Never echoes the URL. | shipped |
+| GET | `/provisioning/:jobId` | — | `{ job }` | | shipped |
+| POST | `/provisioning/:jobId` | — | `{ ok, job }` | Retry. 409 if the job can't be retried. **step-up** | shipped |
+
+**Company statuses:** `draft`, `provisioning`, `provisioning_failed`, `active`, `maintenance`, `suspended`,
+`archived`.
+
+## Background jobs
+
+This whole section is optional. Without Redis or `@dreamtree-org/jobs`, `GET /jobs` answers
+`{ enabled: false }` and the console hides **Jobs**.
+
+| Method | Path | Body / query | Notes | Status |
+|---|---|---|---|---|
+| GET | `/jobs` | — | `{ enabled, definitions, queueNames, defaultTimezone, staleAfterSeconds, queues, queuesError, workers, stats24h }` | shipped |
+| GET | `/jobs/stats` | `?days&company&schedule&tz` | Daily series | shipped |
+| GET | `/jobs/runs` | `?status&job&company&schedule&from&to&cursor` | `{ runs, nextCursor }` | shipped |
+| POST | `/jobs/runs` | `{ jobName, companyId?, branchId?, payload? }` | Run now. **step-up** | shipped |
+| GET | `/jobs/runs/:id` | — | `{ run }` | shipped |
+| POST | `/jobs/runs/:id` | `{ action: "retry" \| "cancel" }` | **step-up** | shipped |
+| GET | `/jobs/runs/export` | same filters | `text/csv` (formula-injection safe). `X-Truncated: 1` when cut off. | shipped |
+| GET | `/jobs/schedules` | `?company` | `{ schedules }` | shipped |
+| POST | `/jobs/schedules` | `{ jobName, cron, timezone?, companyId?, branchId?, payload?, enabled? }` | **step-up** | shipped |
+| GET / PATCH / DELETE | `/jobs/schedules/:id` | PATCH: any POST field | PATCH and DELETE need **step-up** | shipped |
+| POST | `/jobs/schedules/:id` | `{ action: "run" }` | **step-up** | shipped |
+| GET | `/jobs/schedules/preview` | `?cron&tz` | `{ next: string[] }` or 400 | shipped |
+| POST | `/jobs/queues/:name` | `{ action: "pause" \| "resume" }` | **step-up** | shipped |
+| POST | `/jobs/workers/:id` | `{ action: "pause" \| "resume" \| "shutdown" }` | **step-up** | shipped |
+
+## New in v1.1
+
+Each feature here is advertised in `GET /me` → `features`. The console shows a feature only when it is
+advertised.
+
+### Audit
+
+| Method | Path | Body / query | Response / notes | Status |
+|---|---|---|---|---|
+| GET | `/audit` | `?q&action&actor&company&from&to&cursor` | `{ events: AuditEvent[], nextCursor }` | v1.1 |
+| GET | `/audit/export` | same filters | `text/csv` | v1.1 |
+
+### Plans and subscriptions
+
+| Method | Path | Body | Response / notes | Status |
+|---|---|---|---|---|
+| GET | `/plans` | — | `{ plans: Plan[] }` | v1.1 |
+| POST | `/plans` | `Plan` without `id` | **step-up** | v1.1 |
+| PATCH | `/plans/:id` | any `Plan` field | Archive with `{ status: "archived" }`; plans are never deleted. **step-up** | v1.1 |
+| GET | `/companies/:id/subscription` | — | `{ subscription: Subscription \| null, history: Subscription[] }` | v1.1 |
+| PUT | `/companies/:id/subscription` | `{ planId, status, startsAt?, endsAt?, seats?, notes? }` | **step-up** | v1.1 |
+
+### Platform settings
+
+| Method | Path | Body | Response / notes | Status |
+|---|---|---|---|---|
+| GET | `/settings` | `?company=` (omit for platform defaults) | `{ families: SettingsFamily[] }`, with secret values masked | v1.1 |
+| PUT | `/settings/:family` | `{ companyId?, values }` | Secret fields are write-only. **step-up** | v1.1 |
+
+### Support access
+
+Support access goes through expiring grants, so being a superadmin gives no standing access to company
+data (knowledge doc §5.8).
+
+| Method | Path | Body | Response / notes | Status |
+|---|---|---|---|---|
+| GET | `/support-access` | `?company&status` | `{ grants: SupportGrant[] }` | v1.1 |
+| POST | `/support-access` | `{ companyId, reason, minutes }` | Request a grant | v1.1 |
+| POST | `/support-access/:id` | `{ action: "approve" \| "revoke" }` | **step-up** | v1.1 |
+
+### Domains
+
+| Method | Path | Body | Response / notes | Status |
+|---|---|---|---|---|
+| GET | `/companies/:id/domains` | — | `{ domains: CompanyDomain[] }` | v1.1 |
+| POST | `/companies/:id/domains` | `{ host }` | `{ domain, verification: { type: "TXT", name, value } }` | v1.1 |
+| POST | `/companies/:id/domains/:domainId` | `{ action: "verify" \| "make-primary" \| "remove" }` | `remove` needs **step-up** | v1.1 |
+
+## Shapes
+
+The TypeScript definitions are in `platform.d.ts`. The main ones:
+
+```ts
+type CompanyRow = { id; slug; displayName; status; createdAt; branchCount; dbMode: 'managed'|'external'|null;
+  dbStatus; schemaVersion; lastCheckAt; lastCheckOk: 0|1|null };
+type PlatformAdmin = { id; email; status: 'active'|'disabled'; roles: string[]; totpEnrolled; lastLoginAt; createdAt };
+type AuditEvent = { id; at; actorEmail; action; companyId; companyName?; target; diff? };
+```
+
+## Audit actions
+
+The server writes one `platform_audit_events` row per mutating call. Action names are dotted:
+
+- `platform.login`, `platform.login.failed`, `platform.stepup`, `platform.stepup.failed`
+- `platform.admin.create`, `platform.admin.reset-password`, `platform.admin.disable`
+- `company.create`, `company.update`, `company.status`
+- `company.admin.create`, `branch.create`
+- `database.test`, `database.replace`, `database.credentials.reveal`
+- `job.run`, `job.retry`, `schedule.create`
+- `plan.update`, `subscription.update`, `settings.update`
+- `support.grant.request`, `support.grant.approve`
+- `domain.add`
+
+Products may add their own actions under their app key.

package/README.md

@@ -54,6 +54,7 @@ Every star ⭐, share, and contribution helps more than you know. Thank you for
   - `<LandingPage brand={brand} content={content} />` — a product's landing page is a content file.
   - `<AuthShell brand={brand} title="Welcome back">…</AuthShell>` (also available at `@dreamtree-org/landing-kit/auth` + `@dreamtree-org/landing-kit/auth.css`).
   - The built-in `brands` / `getBrand(id)` registry is **deprecated** (warns once, removed in 0.5.0).
+- **Platform admin console** (`@dreamtree-org/landing-kit/platform`, 0.8.0+): one HTTP contract ([PLATFORM-API.md](./PLATFORM-API.md)) that every product's super-administrator console speaks, and its browser client (`createPlatformClient`, `createStepUp`). The server half is `createPlatformApi` in `@dreamtree-org/tenancy`. The shared React shell and views (overview, companies, jobs, admins, audit, plans, settings, support access) build on this client.
 - Plain CSS (`--dt-*` custom properties). It looks the same under Tailwind 3, Tailwind 4 (preflight or not) or no Tailwind. Dark mode via `[data-theme="dark"]` or `.dark`.
 - Built for prerendered, **un-hydrated** pages (fast and crawlable): `enhanceLanding()` wires the menu and the demo button in a few hundred bytes. It also works hydrated in an SPA or Next.js (`'use client'`, `onBookDemo`, `linkComponent`).
 - Responsive from 320px up. The nav folds into a menu below 1024px. Checked with Playwright at 320/375/768/1024/1440, light and dark.
@@ -201,6 +202,32 @@ import '@dreamtree-org/landing-kit/styles.css';
 - `newSection(type)` / `sectionDefaults(type)` start a section with valid defaults; `defaultPage({ name, tagline })`
   is a neutral starting page.
 
+### Store documents (0.9.0): landing, listing and product pages as one document
+
+A store's whole storefront design is one version-2 document, validated with `validateStore` from `/schema`:
+
+```js
+{ version: 2,
+  pages: { home: PageDoc /* the landing page above */,
+           listing: { template: 'classic' | 'topbar' | 'editorial', settings, blocks },
+           product: { template: 'classic' | 'immersive' | 'compact', settings, blocks } },
+  chrome: { announcement, header, footer },   // CHROME_FIELDS
+  card: { image_ratio, badges, spec_line, compare, quick_add, mrp, hover } }  // CARD_FIELDS
+```
+
+- `STORE_PAGES[page]` lists each page's `settings` (field defs, so a builder generates the form), `templates`
+  (setting values + default block order) and `slots`: the commerce blocks the app renders (results, filters,
+  gallery, buy box…). `required` slots can be moved, never removed or hidden, so a page always sells.
+- Between the slots a page may place content sections from `CONTENT_BLOCKS` (promo banner, FAQ, USP strip…),
+  validated with the same rules as landing-page sections. At most `MAX_BLOCKS` (12) blocks per page.
+- A version-1 landing page passed to `validateStore` is migrated (`migrateStore`): it becomes `pages.home`
+  and everything else takes its defaults. `isLegacyPage(doc)` tells them apart.
+- Render a template page with `<TemplateRegion blocks slots theme resolveMedia />`: `slots[type]` is the app's
+  component for a commerce block (`{ block, props }`; return null to place it yourself), content sections render
+  like `TenantPage`.
+- Helpers: `templatePage(page, template)`, `newBlock(page, type)`, `blockDef(page, type)`, `defaultStore`,
+  `defaultChrome`, `defaultCard`, `storeMediaRefs(doc)` (every `{ media_id }` to check before storing), `validateFields`.
+
 ### `<AuthShell>` & `@dreamtree-org/landing-kit/auth`
 
 The shared auth frame for login, signup, password reset, consent and platform-admin sign-in (`desktop [ brand panel 40% | form card ]`, `mobile [ logo · form card · footer · legal links ]`). Import from `@dreamtree-org/landing-kit` or the lightweight `@dreamtree-org/landing-kit/auth` subpath (with `@dreamtree-org/landing-kit/auth.css` or `styles.css`).
@@ -381,6 +408,75 @@ and render `<DemoDialog open={open} onClose={…} onSubmit={…} brand={brand} /
 `<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: jsonLdScript(buildJsonLd({ site: origin, … })) }} />`,
 and in `app/robots.ts` / `app/sitemap.ts` use `buildRobots` / `buildSitemap` with `site: origin`, or return Next's metadata objects from the same data.
 
+**Platform admin console (`./platform`).** The console speaks only [PLATFORM-API.md](./PLATFORM-API.md), mounted at `/api/platform` by default:
+
+```js
+import { createPlatformClient, createStepUp } from '@dreamtree-org/landing-kit/platform';
+
+const api = createPlatformClient({ basePath: '/api/platform', loginPath: '/platform/login' }); // CSRF header from *_platform_csrf
+const sensitive = createStepUp(api, () => askPasswordDialog()); // resolves { password } | { code } | null
+const { companies } = await api.get('companies', { q: 'acme' });
+const { password } = await sensitive(() => api.post(`admins/${id}`, { action: 'reset-password' }));
+```
+
+A 401 sends the browser to `loginPath`.
+
+**The React console (`PlatformConsole`, `PlatformLogin`).**
+
+It's built on `@dreamtree-org/twreact-ui` ^2, an optional peer that only `./platform` needs. Your Tailwind setup has to scan the console too.
+
+Tailwind 3 (`tailwind.config.js`):
+
+```js
+content: [
+  './node_modules/@dreamtree-org/twreact-ui/dist/**/*.{js,mjs}',
+  './node_modules/@dreamtree-org/landing-kit/dist/platform.{js,cjs}',
+]
+```
+
+Tailwind 4: add `@source "../node_modules/@dreamtree-org/landing-kit/dist/platform.js";` instead.
+
+Next.js App Router:
+
+```tsx
+// app/platform/(console)/[[...path]]/console.tsx  ('use client')
+'use client';
+import Link from 'next/link';
+import { usePathname, useRouter } from 'next/navigation';
+import { PlatformConsole } from '@dreamtree-org/landing-kit/platform';
+
+export default function Console({ me }) {
+  const router = useRouter();
+  return (
+    <PlatformConsole
+      brand={brand}
+      initialMe={me}
+      pathname={usePathname()}
+      navigate={router.push}
+      linkAs={Link}
+      pages={[{ path: 'jobs', label: 'Background jobs', feature: 'jobs', render: () => <JobsView /> }]}
+      companyTabs={[{ id: 'settings', label: 'Settings', render: ({ company }) => <CompanySettings id={company.id} /> }]}
+    />
+  );
+}
+
+// app/platform/login/page.tsx
+<PlatformLogin brand={brand} redirectTo="/platform" />  // plus '@dreamtree-org/landing-kit/auth.css'
+```
+
+A Vite or Express SPA can render `<PlatformConsole brand={brand} />` with no router props; it uses `window.location` and `history`. Serve `index.html` for `/platform/*`.
+
+Built-in pages:
+
+- Overview
+- Companies (list, 4-step wizard, detail with Overview / Branches / Database / Admins / Activity)
+- Audit log
+- Platform admins
+- Security (authenticator setup)
+
+Product pages come in through `pages`; procurementpro's jobs console is one. A session without a verified authenticator only sees the setup screen.
+ A 403 `STEP_UP_REQUIRED` is retried once after `auth/confirm`. Other failures throw `PlatformApiError` (`status`, `code`, and a message that is safe to show).
+
 ## What it deliberately does NOT do
 
 - No product copy, prices, ratings or customer counts. Every word comes from your content file.

package/ai-skills/landing-kit.md

@@ -0,0 +1,97 @@
+# landing-kit — AI assistant reference
+
+`@dreamtree-org/landing-kit` is the shared public face and admin entry point of every Dreamtree Pro product:
+
+- the marketing site
+- the sign-in frame
+- the Platform (super-administrator) console contract
+
+Read this before writing any landing page, login screen or platform admin code in a Pro app. Don't hand-roll any of the three.
+
+## Entry points
+
+| Import | What | Runs in |
+|---|---|---|
+| `@dreamtree-org/landing-kit` | `LandingPage`, `MarketingLayout`, `Header`, `Hero`, `FeatureSection`, `Faq`, `DemoCta`, `DemoDialog`, `AuthShell`, `toLandingBrand`, `TenantPage` | React (`'use client'`) |
+| `@dreamtree-org/landing-kit/auth` | `AuthShell`, `toLandingBrand`, `DemoAccounts` only (a small bundle for login pages) | React |
+| `@dreamtree-org/landing-kit/platform` | `createPlatformClient`, `createStepUp`, `PlatformApiError`, `enabledFeatures`, `formatDate`, `timeAgo` | Browser, any framework |
+| `@dreamtree-org/landing-kit/server` | `landingRoutes`, `prerenderPages`, `sessionCheck`, `fillPage` | Express, Node (CJS-safe) |
+| `@dreamtree-org/landing-kit/seo` | JSON-LD, robots, sitemap, `llms.txt` builders | Anywhere |
+| `@dreamtree-org/landing-kit/schema` | `validatePage`, `validateTheme`, `themeVars` for tenant pages | Anywhere |
+| `@dreamtree-org/landing-kit/enhance` | `enhanceLanding()` for prerendered pages | Browser |
+| `@dreamtree-org/landing-kit/styles.css`, `/auth.css` | Plain CSS on `--dt-*` variables | |
+
+## Hard rules
+
+1. **Brand comes from the product repo.** Use `toLandingBrand(require('./dreamtree.brand.json'), copy)`. `getBrand(id)` is deprecated, so don't add new calls to it.
+2. **No product copy, prices or icons inside the package.** Words live in the product's `content.js`. Icons are props.
+3. **Sign-in screens use `AuthShell`.** Tenant users get `variant="tenant"` (the default). Super-administrators get `variant="platform"`.
+4. **Platform admin is a separate identity realm.**
+   - It has its own cookie (`<prefix>_platform_session`), its own CSRF cookie (`<prefix>_platform_csrf`) and its own login at `/platform/login`.
+   - Never reuse the tenant session, and never give a tenant role platform powers.
+5. **Platform console code talks only through the contract.**
+   - The contract is `PLATFORM-API.md`, shipped in this package.
+   - Never call `fetch('/api/platform/...')` by hand. Use `createPlatformClient()`.
+   - Never hand-roll a step-up retry. Use `createStepUp()`.
+   - The server side is `createPlatformApi` from `@dreamtree-org/tenancy` (`./next` or `./express`). Don't write `app/api/platform/**` routes per product.
+
+## Platform console client
+
+```js
+import { createPlatformClient, createStepUp, isStepUpRequired, PlatformApiError } from '@dreamtree-org/landing-kit/platform';
+
+const api = createPlatformClient({
+  basePath: '/api/platform',     // where the contract is mounted
+  loginPath: '/platform/login',  // where a 401 sends the browser
+  // csrfCookie: 'pp_platform_csrf' // default: any *_platform_csrf cookie
+});
+
+const { counts, attention } = await api.get('overview');
+const { companies } = await api.get('companies', { q: 'acme', status: 'active' });
+
+// Sensitive actions (rows marked step-up in PLATFORM-API.md):
+const sensitive = createStepUp(api, async (reason) => openConfirmDialog(reason.message)); // → { password } | { code } | null
+const { password } = await sensitive(() => api.post(`admins/${id}`, { action: 'reset-password' }));
+```
+
+- **Paths are relative to `basePath`.** Write `'companies'`, not `'/api/platform/companies'`.
+- **Errors.** Failures throw `PlatformApiError` with `status`, `code` and a `message` that is safe to show. Show the message as it is. Never show a raw response body.
+- **Cancelled step-up.** A step-up the admin cancels rejects with `code: 'CANCELLED'`. Treat it as a no-op, not an error toast.
+- **Enrollment gate.** A 403 `TOTP_ENROLLMENT_REQUIRED`, or `me.access.console === false`, means show the authenticator enrolment screen (`POST me/totp` with `begin`, then `verify`), not an error.
+- **One-time secrets.** New passwords and revealed DB URLs come back exactly once. Show them in a copy-once panel, and never log them or put them in state that persists.
+- **Feature gating.** Call `GET me` (v1.1 servers) and pass the result to `enabledFeatures(PLATFORM_FEATURES, me)`. That decides which nav items to show: jobs, plans, audit, support, settings. Older servers fall back to overview, companies, jobs and admins.
+
+## React console
+
+- **Mounting.** Mount `<PlatformConsole brand pathname navigate linkAs pages companyTabs initialMe />` once, under `/platform`. Don't write per-route console pages in a product.
+- **Sign-in.** `<PlatformLogin brand redirectTo="/platform" />` is the sign-in page.
+- **Tailwind.** Tailwind must scan `node_modules/@dreamtree-org/landing-kit/dist/platform.*` and twreact-ui's dist. If it doesn't, the console renders unstyled.
+- **Product additions.** Product-only screens (background jobs, company settings families) go in `pages` and `companyTabs`. Gate them with `feature` or `permission`; don't fork the console.
+- **Inside a page or tab.** Use `usePlatform()` (client, `can`, `href`, `Link`) and `useSensitive()` for anything that needs step-up.
+
+## Console features (PLATFORM-API.md)
+
+- **Shipped** (procurementpro is the reference):
+  - Overview: counts, needs attention, recent audit
+  - Companies: list, 4-step new-company wizard, detail with overview, branches, database (test, sync, replace, reveal), admins, jobs and activity
+  - Background jobs: runs, schedules, workers and queues
+  - Platform admins
+- **v1.1:**
+  - TOTP sign-in and enrolment, login throttle, `GET /me` with a role-based permission list
+  - Global audit viewer and CSV export
+  - Plans and per-company subscriptions
+  - Platform and company settings (secret fields are write-only)
+  - Support-access grants
+  - Company domains
+
+## Security invariants (do not weaken)
+
+- **What the browser never sees:** database credentials, encryption keys or password hashes. The one exception is the audited, custodian-only `PUT companies/:id/database {action:"reveal"}`.
+- **Server-side authorization on every endpoint.** Hiding a button is not access control.
+- **Step-up is required for:**
+  - status and slug changes
+  - DB replace and reveal
+  - every admin action
+  - every job mutation
+  - plan, settings and grant approval changes
+- **Superadmin is not standing access to company business data.** Support access goes through expiring grants that the company approves.