create-ortha-app 0.4.0

package/templates/default/README.md.tmpl

@@ -0,0 +1,199 @@
+# __APP_TITLE__
+
+An [Ortha CMS](https://github.com/ortha-source/ortha-cms) app.
+
+## Getting started
+
+```sh
+docker compose up -d   # Postgres
+npm run migrate        # create the schema
+npm run dev            # API on :3000, admin on :4200
+```
+
+Sign in at <http://localhost:4200> with the admin credentials in `.env`
+(`ORTHA_ROOT_ADMIN_EMAIL` / `ORTHA_ROOT_ADMIN_PASSWORD`). That account is
+provisioned on boot, idempotently — clear those two variables once you have it.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `npm run dev` | `tsc --watch`, `node --watch`, and the Vite dev server together |
+| `npm run build` | Compiles the server and builds the admin bundle |
+| `npm start` | Runs the built server — API **and** admin, one process, one origin |
+| `npm run migrate` | Applies every plugin's pending migrations |
+| `npm run generate -- --name=<name>` | Generates a migration for your own content tables |
+| `npm run studio` | Opens Drizzle Studio on this app's database |
+| `npm test` | Unit tests — both halves |
+| `npm run e2e` | Both end-to-end suites |
+| `npm run e2e:server` | API tests against a real database |
+| `npm run e2e:admin` | Browser tests against a mocked API |
+| `npm run typecheck` | Both TypeScript projects |
+
+## Tests
+
+**Unit tests** run under two runners, one per half, each matching its own
+toolchain:
+
+- **`apps/server/**/*.spec.ts`** → Jest with `@swc/jest` (`apps/server/jest.config.js`).
+  Jest rather than Vitest because NestJS DI reads `emitDecoratorMetadata`, and
+  Vitest's esbuild transform does not emit it — providers resolve as
+  `undefined`, with no error naming the cause.
+- **`apps/admin/src/**/*.spec.tsx`** → Vitest with jsdom, configured inside
+  `apps/admin/vite.config.mts` so tests resolve modules exactly the way the app does.
+
+Neither touches a database: `jest.setup.js` supplies placeholder secrets so
+`npm test` runs anywhere, including CI with no `.env`.
+
+The two shipped specs assert the things that break quietly — the plugin lists
+and their order. Server-side that is migration order (a plugin whose tables
+reference another's must come after it, which fails only on a *fresh*
+database); admin-side it is that exactly one plugin contributes a `layout`, and
+that it is the shell's, because the host mounts the first one it finds and the
+shell's is what composes the auth gate.
+
+**End-to-end tests** come in two suites, split the way the app is:
+
+### `apps/server-e2e` — the API, for real
+
+Jest + supertest, booting **this app** through `createServer` with the real
+plugin list against a real Postgres. `apps/server-e2e/src/support/test-app.ts` gives you
+`createTestApp()` / `closeTestApp()`.
+
+It manages its own database. `<your database>_e2e` is created and migrated on
+first run, using the same `applyPluginMigrations` that `ortha migrate` calls —
+so the schema under test is the real one. It never touches the database
+`DATABASE_URL` names, because it **truncates every table** between suites;
+`E2E_DATABASE_URL` overrides the derivation, and pointing it at your
+development database is refused rather than obeyed.
+
+```sh
+docker compose up -d
+npm run e2e:server
+```
+
+### `apps/admin-e2e` — the UI, in a browser
+
+Playwright against the Vite dev server with `/api` mocked at the network layer
+(`apps/admin-e2e/src/support/seed.ts`). No backend, no database, no migration — a run is
+fast and hermetic, and when it fails it is the UI that is wrong. API behaviour
+belongs in `apps/server-e2e`, where a failure names the endpoint instead of blaming
+a page.
+
+```sh
+npx playwright install chromium   # once
+npm run e2e:admin
+```
+
+Anything the seed does not mock returns `404` on purpose: a silent empty `200`
+makes a page render its empty state and pass, which is the false green this
+exists to avoid.
+
+## What you own
+
+Almost nothing, on purpose — the CMS is the `@orthacms/*` packages, and this app
+is the composition of them.
+
+```
+apps/
+├── server/       the API — ortha.config.ts, src/{main,plugins}.ts
+├── admin/        the UI — index.html, vite.config.mts, src/
+├── server-e2e/   API tests against a real database
+└── admin-e2e/    browser tests against a mocked API
+```
+
+The same four apps Ortha CMS itself is built from, so anything you read in its
+source lands in the same place here.
+
+| File | Why you would open it |
+| --- | --- |
+| `apps/server/src/plugins.ts` | Which plugins the API runs, and **in what order** |
+| `apps/admin/src/plugins.ts` | Which plugins the admin UI runs |
+| `apps/server/ortha.config.ts` | Every setting, typed — the only reader of `process.env` |
+| `apps/admin/src/styles.css` | The theme tokens: this app's whole visual identity |
+
+Upgrading is a version bump. Keep the `@orthacms/*` versions **in step with each
+other** — they are released together, and a partial upgrade can leave two copies
+of a shared package in `node_modules`, which means two React context instances
+and UI that silently stops talking to itself.
+
+### Writing your own plugin
+
+A server plugin is a `ServerPlugin` from `@orthacms/bootstrap-server` — a name,
+a NestJS module, and optionally its own migrations — added to the array in
+`src/server/plugins.ts`. `@InjectDatabase()` from `@orthacms/database` gives it
+the shared connection. An admin plugin is an `AdminPlugin` from
+`@orthacms/bootstrap-admin`, added to `src/admin/plugins.ts`.
+
+`@orthacms/utils-server` and `@orthacms/utils-admin` hold the shared toolkit
+(filter parsing, `apiClient`, slots, table URL state), and
+`@orthacms/design-system` the UI primitives. All three are already declared here.
+
+The extension points are declared too, so you can import them directly:
+`@orthacms/content-domain` (the content kernel's types), `@orthacms/tools-server`
+(register an agent tool), `@orthacms/copilot-domain`,
+`@orthacms/query-builder-admin`.
+
+If you add an `@orthacms/*` package this app does not already list — a copilot
+backend, the GraphQL adapter — install it at **the same version as the rest**.
+Keeping them in step is what stops npm nesting a second copy of a shared
+package, which means two React context instances and UI that silently stops
+talking to itself.
+
+## What this app was scaffolded with
+
+### AI copilot
+
+Installed, and **off** until you turn it on: set `COPILOT_ENABLED=true` in
+`.env`. Enabling a hosted backend sends workspace content to a third party, so
+it is an explicit decision rather than a default.
+
+Backends are registered in `src/server/plugins.ts`, and **the order is the
+setting** — there is no `defaultProvider`. The first registered backend serves a
+run that names none, and it is what the admin's model picker opens on. A backend
+is only registered when its connection settings are present, so an unconfigured
+one never appears as an option that fails on the first message.
+
+The bundled `fake` provider needs no key and no network, and is registered last
+— so with nothing configured the chat still works, and it is the default only
+because it is the only one.
+<!-- ortha:if graphql -->
+### GraphQL
+
+`POST /api/v1/graphql`, alongside REST. It is a protocol adapter over the same
+services, not a second API: same bearer tokens, same scopes, same visibility
+rules. The schema is built per workspace content-grant set, so introspection
+cannot enumerate types a workspace was not granted.
+
+GraphiQL rides the same switch as the API reference (`API_DOCS`).
+<!-- ortha:end -->
+<!-- ortha:if mcp -->
+### MCP
+
+`POST /api/v1/mcp`, off until `MCP_ENABLED=true`. It lets an external agent do
+content CRUD with an API token — mint one on the API Tokens page, `read` scope
+for a retrieval-only agent, `full` for one that authors.
+<!-- ortha:end -->
+
+## Adding content types
+
+This app starts with none. To add some:
+
+1. Write them under `apps/server/src/content/` and export a `contentTypes` array.
+2. Pass them to `ContentPlugin({ types: contentTypes, migrations: … })` in
+   `apps/server/src/plugins.ts` — the comment there has the exact shape.
+3. Add `apps/server/drizzle.config.ts` pointing `schema` at your
+   `src/content/index.ts` and `out` at `../../migrations`.
+4. `npm run generate -- --name=add_content_types && npm run migrate`
+
+## Deploying
+
+`npm run build && npm start` is the whole thing: one process serving the API and
+the admin bundle on one origin. Set in the environment:
+
+- `DATABASE_URL` — required
+- `NODE_ENV=production` — spelled exactly; anything else drops `Secure` from the
+  session cookie and publishes the API reference
+- `TRUST_PROXY` — required behind a load balancer, or every client shares one
+  rate-limit bucket
+- `MEDIA_LOCAL_ROOT` — a persistent volume, or uploads vanish on each deploy

package/templates/default/_gitignore

@@ -0,0 +1,8 @@
+node_modules
+dist
+.env
+.storage
+*.tsbuildinfo
+test-output
+playwright-report
+test-results

package/templates/default/apps/admin/index.html

@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8" />
+        <title>__APP_TITLE__</title>
+        <base href="/" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <script>
+            /* Apply the persisted theme before first paint, so a dark-mode user
+               never sees a flash of the light canvas. Mirrors the design-system
+               AppearanceProvider, which takes over on mount. */
+            (function () {
+                try {
+                    var stored = localStorage.getItem('ortha.theme');
+                    var theme =
+                        stored === 'light' ||
+                        stored === 'dark' ||
+                        stored === 'system'
+                            ? stored
+                            : 'system';
+                    var dark =
+                        theme === 'dark' ||
+                        (theme === 'system' &&
+                            window.matchMedia('(prefers-color-scheme: dark)')
+                                .matches);
+                    document.documentElement.classList.toggle('dark', dark);
+                    document.documentElement.style.colorScheme = dark
+                        ? 'dark'
+                        : 'light';
+                } catch (e) {}
+            })();
+        </script>
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="/src/main.tsx"></script>
+    </body>
+</html>

package/templates/default/apps/admin/src/main.tsx

@@ -0,0 +1,5 @@
+import { createAdmin } from '@orthacms/bootstrap-admin';
+import { buildPlugins } from './plugins';
+import './styles.css';
+
+createAdmin({ plugins: buildPlugins() });

package/templates/default/apps/admin/src/plugins.spec.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { buildPlugins } from './plugins';
+
+/**
+ * The admin composition, asserted.
+ *
+ * A browser test proves the happy path assembles, and can say nothing about the
+ * two ways this list goes wrong while still rendering something plausible:
+ *
+ * 1. **A layout registered ahead of the shell's.** The host mounts the *first*
+ *    `layout` it finds, and the shell's is what composes identity's auth gate —
+ *    so a second contributor placed earlier renders every private route
+ *    **ungated** while signed out. It looks like a styling accident.
+ * 2. **A plugin quietly dropped.** Its routes and slot contributions stop
+ *    existing with no error; the sidebar is simply shorter, and every test that
+ *    does not open that page stays green.
+ *
+ * Both are decisions visible in `plugins.ts`, so they are pinned here rather
+ * than through a browser. Relative order between slot fillers is *not* asserted
+ * — slots are module-level singletons registered before the first render, so
+ * that order only decides the order of items within a slot.
+ */
+
+/** Every plugin the admin registers, in order. */
+const EXPECTED_PLUGINS = [
+    'identity',
+    'shell',
+    'workspaces',
+    'insights',
+    'content',
+    'i18n',
+    'wysiwyg',
+    'media',
+    'copilot',
+    'users',
+    'activity',
+    'api-tokens'
+];
+
+describe('buildPlugins()', () => {
+    it('registers exactly the plugins this admin ships', () => {
+        expect(buildPlugins().map((plugin) => plugin.name)).toEqual(
+            EXPECTED_PLUGINS
+        );
+    });
+
+    it('contributes exactly one layout, and it is the shell’s', () => {
+        const layouts = buildPlugins().filter((plugin) => plugin.layout);
+
+        expect(layouts.map((plugin) => plugin.name)).toEqual(['shell']);
+    });
+
+    it('puts identity first, so its public routes render outside the gate', () => {
+        // Sign-in and accept-invite must not be wrapped in the layout that
+        // requires a session — otherwise there is no way to get one.
+        expect(buildPlugins()[0]?.name).toBe('identity');
+    });
+});

package/templates/default/apps/admin/src/plugins.ts

@@ -0,0 +1,57 @@
+import type { AdminPlugin } from '@orthacms/bootstrap-admin';
+import { ActivityPlugin } from '@orthacms/activity-admin';
+import { ApiTokensPlugin } from '@orthacms/api-tokens-admin';
+import { ContentPlugin } from '@orthacms/content-admin';
+import { I18nPlugin } from '@orthacms/i18n-admin';
+import { IdentityPlugin } from '@orthacms/identity-admin';
+import { InsightsPlugin } from '@orthacms/insights-admin';
+import { MediaPlugin } from '@orthacms/media-admin';
+import { ShellPlugin } from '@orthacms/shell-admin';
+import { UsersPlugin } from '@orthacms/users-admin';
+import { WorkspacesPlugin } from '@orthacms/workspaces-admin';
+import { WysiwygPlugin } from '@orthacms/wysiwyg-admin';
+import { CopilotPlugin } from '@orthacms/copilot-admin';
+
+/**
+ * The admin's composition, mirroring `src/server/plugins.ts` on the UI side.
+ *
+ * **Two positions matter; the rest is legibility.**
+ *
+ * `IdentityPlugin` is first because it contributes the only *public* routes —
+ * sign-in and accept-invite — which must render outside the gated layout.
+ *
+ * `ShellPlugin` is the one plugin contributing a `layout`, and the host mounts
+ * the **first** layout it finds. The shell's layout is what composes
+ * identity's auth gate, so a plugin registering a layout ahead of it would
+ * render every private route *ungated* — losing the sidebar and the `<main>`
+ * landmark with it, which makes an authorization bug look like a styling
+ * accident. Keep it second.
+ *
+ * Everything else is order-independent: slots are module-level singletons and
+ * every plugin's contributions are registered before the first render, so a
+ * filler registered ahead of the plugin defining its slot still lands. Only
+ * two things follow from position — the order of items within a slot, and
+ * which plugin wins an id collision in a last-writer-wins merge.
+ */
+export function buildPlugins(): AdminPlugin[] {
+    return [
+        IdentityPlugin(),
+        ShellPlugin(),
+        WorkspacesPlugin(),
+        // Registers the dashboard's default sections, which merge by id with
+        // the last writer winning — so anything renaming a band comes after.
+        InsightsPlugin(),
+        ContentPlugin(),
+        // Content Library slot fillers, hence after ContentPlugin().
+        I18nPlugin(),
+        WysiwygPlugin(),
+        MediaPlugin(),
+        // The docked chat panel plus the full-page Agents view. Belongs with
+        // the workspace-interior features: the panel mounts into the workspace
+        // shell's sidebar footer.
+        CopilotPlugin(),
+        UsersPlugin(),
+        ActivityPlugin(),
+        ApiTokensPlugin()
+    ];
+}

package/templates/default/apps/admin/src/styles.css

@@ -0,0 +1,254 @@
+@import 'tailwindcss';
+@import '@orthacms/design-system/styles.css';
+/* The rich-text scope (`.ortha-wysiwyg`) shared by the WYSIWYG editor and its
+   previews. Reads the `--color-*` tokens below at runtime, so it follows
+   light/dark with the rest of the admin. */
+@import '@orthacms/wysiwyg-admin/styles.css';
+
+/* Tailwind excludes `node_modules` from its automatic content detection, so
+   without this line none of the classes inside the Ortha packages are seen and
+   the whole admin renders unstyled. The published packages ship compiled JS
+   with the class strings intact, which is what this scans. */
+@source "../../../node_modules/@orthacms/*/dist/**/*.js";
+
+@custom-variant dark (&:where(.dark, .dark *));
+
+/* ---------------------------------------------------------------------------
+   Theme. This file is yours — these tokens are the app's whole visual
+   identity, and every component in the design system resolves its colours
+   through them at runtime.
+
+   The contract to keep: every `*-foreground` must clear WCAG AA (4.5:1) on its
+   own surface. `@theme` rather than `@theme inline` is deliberate — it makes
+   utilities resolve to `var(--color-*)`, which is what lets the `.dark` block
+   below re-declare them and have the change take effect without rebuilding.
+--------------------------------------------------------------------------- */
+@theme {
+    --radius: 0.625rem;
+
+    --color-background: oklch(1 0 0);
+    --color-foreground: oklch(0.21 0.012 285);
+    --color-card: oklch(1 0 0);
+    --color-card-foreground: oklch(0.21 0.012 285);
+    --color-popover: oklch(1 0 0);
+    --color-popover-foreground: oklch(0.21 0.012 285);
+
+    --color-primary: oklch(0.25 0.015 285);
+    --color-primary-foreground: oklch(0.985 0 0);
+
+    /* The brand accent. `brand` is for icons and large accents (it clears 3:1,
+       not 4.5:1 — never put white text on it); `brand-text` is the link-grade
+       version that does clear AA as text. */
+    --color-brand: oklch(0.66 0.2 35);
+    --color-brand-foreground: oklch(0.21 0.012 285);
+    --color-brand-text: oklch(0.55 0.18 35);
+    --color-brand-soft: oklch(0.955 0.025 40);
+    --color-brand-soft-foreground: oklch(0.47 0.16 35);
+
+    --color-secondary: oklch(0.945 0.003 285);
+    --color-secondary-foreground: oklch(0.25 0.012 285);
+    --color-muted: oklch(0.975 0.003 285);
+    --color-muted-foreground: oklch(0.49 0.015 285);
+    --color-accent: oklch(0.975 0.003 285);
+    --color-accent-foreground: oklch(0.21 0.012 285);
+
+    --color-destructive: oklch(0.55 0.22 27);
+    --color-destructive-foreground: oklch(0.985 0 0);
+    --color-destructive-soft: oklch(0.95 0.025 20);
+    --color-destructive-soft-foreground: oklch(0.44 0.17 27);
+
+    --color-success: oklch(0.52 0.14 150);
+    --color-success-foreground: oklch(0.985 0 0);
+    --color-success-soft: oklch(0.95 0.045 150);
+    --color-success-soft-foreground: oklch(0.42 0.11 150);
+
+    --color-warning: oklch(0.55 0.12 66);
+    --color-warning-foreground: oklch(0.985 0 0);
+    --color-warning-soft: oklch(0.95 0.045 80);
+    --color-warning-soft-foreground: oklch(0.44 0.1 60);
+
+    --color-info: oklch(0.52 0.17 255);
+    --color-info-foreground: oklch(0.985 0 0);
+    --color-info-soft: oklch(0.945 0.03 255);
+    --color-info-soft-foreground: oklch(0.42 0.14 260);
+
+    --color-teal-soft: oklch(0.94 0.035 190);
+    --color-teal-soft-foreground: oklch(0.4 0.08 190);
+    --color-violet-soft: oklch(0.945 0.035 300);
+    --color-violet-soft-foreground: oklch(0.42 0.14 300);
+
+    --color-border: oklch(0.9 0.008 285);
+    /* Darker than `border` so form controls read as editable. */
+    --color-input: oklch(0.84 0.01 285);
+    --color-ring: oklch(0.55 0.01 285);
+
+    --color-status-active: oklch(0.63 0.17 149);
+    --color-status-invited: oklch(0.67 0.14 70);
+
+    /* Sidebar chrome. Authored dark in both themes; everything rendered inside
+       the sidebar must use these tokens rather than the light-surface ones. */
+    --color-sidebar: oklch(0.21 0.012 285);
+    --color-sidebar-foreground: oklch(0.93 0.005 285);
+    --color-sidebar-primary: oklch(0.66 0.2 35);
+    --color-sidebar-primary-foreground: oklch(0.21 0.012 285);
+    --color-sidebar-accent: oklch(0.3 0.018 285);
+    --color-sidebar-accent-foreground: oklch(0.985 0.002 285);
+    --color-sidebar-border: oklch(0.31 0.012 285);
+    --color-sidebar-ring: oklch(0.75 0.01 285);
+
+    /* Nav-icon accents, lightened so each clears 3:1 on the dark sidebar. */
+    --color-nav-orange: oklch(0.72 0.17 40);
+    --color-nav-blue: oklch(0.74 0.11 250);
+    --color-nav-green: oklch(0.74 0.13 150);
+    --color-nav-violet: oklch(0.76 0.11 300);
+    --color-nav-amber: oklch(0.78 0.13 80);
+    --color-nav-teal: oklch(0.75 0.1 190);
+
+    /* Data-visualisation palette (dashboard widgets). Hex rather than oklch
+       because these values are the output of a contrast validator — treat them
+       as fixed data. `chart-1`/`chart-2` are the categorical pair, the only one
+       that stays distinguishable under colourblind simulation on both the light
+       and the dark card; `chart-q0`..`q5` are the sequential ramp, low to high. */
+    --color-chart-1: #2a78d6;
+    --color-chart-2: #1baf7a;
+    --color-chart-q0: #eef2f7;
+    --color-chart-q1: #cde2fb;
+    --color-chart-q2: #9ec5f4;
+    --color-chart-q3: #5598e7;
+    --color-chart-q4: #2a78d6;
+    --color-chart-q5: #184f95;
+    --color-chart-on-deep: #ffffff;
+    --color-chart-grid: oklch(0.93 0.004 285);
+    --color-chart-axis: oklch(0.86 0.006 285);
+}
+
+/* Dark theme, toggled by the `.dark` class the design system's
+   AppearanceProvider puts on <html>. Only the light-surface tokens flip; the
+   sidebar chrome was already authored dark and carries over.
+
+   Note the semantic solids invert their *foreground* too: lightened enough to
+   read on a near-black canvas, they can no longer carry white text at AA. */
+.dark {
+    --color-background: oklch(0.175 0.012 285);
+    --color-foreground: oklch(0.95 0.004 285);
+    --color-card: oklch(0.215 0.012 285);
+    --color-card-foreground: oklch(0.95 0.004 285);
+    --color-popover: oklch(0.215 0.012 285);
+    --color-popover-foreground: oklch(0.95 0.004 285);
+
+    --color-primary: oklch(0.92 0.004 285);
+    --color-primary-foreground: oklch(0.21 0.012 285);
+
+    --color-brand: oklch(0.7 0.19 40);
+    --color-brand-foreground: oklch(0.21 0.012 285);
+    --color-brand-text: oklch(0.8 0.14 45);
+    --color-brand-soft: oklch(0.29 0.05 40);
+    --color-brand-soft-foreground: oklch(0.83 0.11 45);
+
+    --color-secondary: oklch(0.28 0.008 285);
+    --color-secondary-foreground: oklch(0.95 0.004 285);
+    --color-muted: oklch(0.25 0.006 285);
+    --color-muted-foreground: oklch(0.72 0.012 285);
+    --color-accent: oklch(0.27 0.008 285);
+    --color-accent-foreground: oklch(0.95 0.004 285);
+
+    --color-destructive: oklch(0.65 0.2 25);
+    --color-destructive-foreground: oklch(0.21 0.012 285);
+    --color-destructive-soft: oklch(0.3 0.08 20);
+    --color-destructive-soft-foreground: oklch(0.83 0.11 25);
+
+    --color-success: oklch(0.62 0.14 150);
+    --color-success-foreground: oklch(0.21 0.012 285);
+    --color-success-soft: oklch(0.3 0.06 150);
+    --color-success-soft-foreground: oklch(0.83 0.12 150);
+
+    --color-warning: oklch(0.7 0.13 70);
+    --color-warning-foreground: oklch(0.21 0.012 285);
+    --color-warning-soft: oklch(0.32 0.06 70);
+    --color-warning-soft-foreground: oklch(0.86 0.1 82);
+
+    --color-info: oklch(0.62 0.15 255);
+    --color-info-foreground: oklch(0.21 0.012 285);
+    --color-info-soft: oklch(0.3 0.07 255);
+    --color-info-soft-foreground: oklch(0.83 0.1 258);
+
+    --color-teal-soft: oklch(0.3 0.05 190);
+    --color-teal-soft-foreground: oklch(0.83 0.08 190);
+    --color-violet-soft: oklch(0.31 0.06 300);
+    --color-violet-soft-foreground: oklch(0.85 0.1 300);
+
+    --color-border: oklch(0.3 0.008 285);
+    --color-input: oklch(0.4 0.01 285);
+    --color-ring: oklch(0.62 0.01 285);
+
+    --color-status-active: oklch(0.7 0.16 149);
+    --color-status-invited: oklch(0.74 0.13 70);
+
+    --color-chart-1: #3987e5;
+    --color-chart-2: #199e70;
+    --color-chart-q0: #1b1b22;
+    --color-chart-q1: #1f3350;
+    --color-chart-q2: #184f95;
+    --color-chart-q3: #256abf;
+    --color-chart-q4: #3987e5;
+    --color-chart-q5: #86b6ef;
+    --color-chart-on-deep: #101016;
+    --color-chart-grid: oklch(0.27 0.006 285);
+    --color-chart-axis: oklch(0.35 0.008 285);
+}
+
+/* Avatar accents. Plain `:root` custom properties rather than `@theme`
+   because they are applied via inline `var(--color-avatar-…)` styles, and
+   Tailwind tree-shakes `@theme` tokens no generated utility references. */
+:root {
+    --color-avatar-slate: oklch(0.5 0.05 250);
+    --color-avatar-green: oklch(0.5 0.11 150);
+    --color-avatar-amber: oklch(0.5 0.1 70);
+    --color-avatar-violet: oklch(0.5 0.16 300);
+    --color-avatar-rose: oklch(0.5 0.15 15);
+    --color-avatar-teal: oklch(0.5 0.08 190);
+    --color-avatar-indigo: oklch(0.5 0.16 275);
+}
+
+@layer base {
+    * {
+        @apply border-border;
+    }
+    body {
+        @apply bg-background text-foreground;
+    }
+    #root {
+        /* `overflow-x-clip`, not `-hidden`: `hidden` would make #root a scroll
+           container and break the sticky chrome. Note `html` deliberately
+           carries no overflow of its own — a non-visible overflow there stops
+           `body`'s from reaching the viewport, which breaks the scrollbar
+           compensation Radix applies when a menu opens, and the whole layout
+           jumps sideways every time one does. */
+        @apply min-h-svh overflow-x-clip;
+    }
+
+    /* Thin, theme-following scrollbars. The admin is a stack of scrollports and
+       the platform default paints a heavy grey column in every one. */
+    * {
+        scrollbar-width: thin;
+        scrollbar-color: var(--color-border) transparent;
+    }
+    ::-webkit-scrollbar {
+        width: 8px;
+        height: 8px;
+    }
+    ::-webkit-scrollbar-track,
+    ::-webkit-scrollbar-corner {
+        background: transparent;
+    }
+    ::-webkit-scrollbar-thumb {
+        border-radius: 9999px;
+        background-color: var(--color-border);
+    }
+    ::-webkit-scrollbar-thumb:hover {
+        background-color: var(--color-muted-foreground);
+    }
+    ::selection {
+        @apply bg-foreground/15;
+    }
+}

package/templates/default/apps/admin/tsconfig.json

@@ -0,0 +1,29 @@
+{
+    "compilerOptions": {
+        "target": "es2022",
+        "lib": [
+            "es2023",
+            "dom",
+            "dom.iterable"
+        ],
+        "module": "esnext",
+        "moduleResolution": "bundler",
+        "jsx": "react-jsx",
+        "types": [
+            "node",
+            "vite/client"
+        ],
+        "strict": true,
+        "skipLibCheck": true,
+        "esModuleInterop": true,
+        "forceConsistentCasingInFileNames": true,
+        "resolveJsonModule": true,
+        "allowImportingTsExtensions": true,
+        "noEmit": true
+    },
+    "include": [
+        "src/**/*.ts",
+        "src/**/*.tsx",
+        "vite.config.mts"
+    ]
+}