@voltro/cli 0.1.0

package/templates/apps/frontend-contact/src/components/ContactForm.island.tsx

@@ -0,0 +1,104 @@
+// The contact form — an ISLAND inside an otherwise-static page. The page is
+// `interactive: 'islands'`, so only THIS component hydrates; the surrounding
+// marketing copy stays inert HTML.
+//
+// `hydrate: 'visible'` defers hydration until the form scrolls into view —
+// it's below the fold, so there's no reason to spend JS on it at first paint.
+//
+// i18n note: islands hydrate INDEPENDENTLY of the layout's URL <I18nProvider>,
+// so this component must NOT import @voltro/i18n (`<T>`/useT would crash / show
+// raw keys at hydration). Instead the PAGE resolves every UI string per-locale
+// (inside the provider) and passes them in as `labels` — the framework
+// serialises those props into the island's HTML, so it hydrates already
+// translated. Dynamic runtime data (the server's error detail) stays as-is.
+//
+// On submit it POSTs JSON to the serverless function (CONTACT_ENDPOINT). The
+// function lives on a different origin, but the framework's node runner +
+// the edge hosts both send CORS headers, so the cross-origin call works.
+
+import type { FormEvent, ReactNode } from 'react'
+import { useState } from 'react'
+import { island } from '@voltro/web'
+import { CONTACT_ENDPOINT } from '../config'
+
+// Every user-facing string the island shows, resolved per-locale by the page.
+export interface ContactFormLabels {
+  readonly name: string
+  readonly email: string
+  readonly message: string
+  readonly send: string
+  readonly sending: string
+  readonly sentNotice: string
+  readonly errorPrefix: string
+  readonly networkError: string
+}
+
+// Object-literal type (not an interface) so it satisfies the island()
+// generic's `Record<string, unknown>` constraint.
+type ContactFormProps = { readonly labels: ContactFormLabels }
+
+type Status =
+  | { readonly kind: 'idle' }
+  | { readonly kind: 'sending' }
+  | { readonly kind: 'sent' }
+  | { readonly kind: 'error'; readonly message: string }
+
+function ContactForm({ labels }: ContactFormProps): ReactNode {
+  const [name, setName] = useState('')
+  const [email, setEmail] = useState('')
+  const [message, setMessage] = useState('')
+  const [status, setStatus] = useState<Status>({ kind: 'idle' })
+
+  const onSubmit = async (e: FormEvent): Promise<void> => {
+    e.preventDefault()
+    setStatus({ kind: 'sending' })
+    try {
+      const res = await fetch(CONTACT_ENDPOINT, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ name, email, message }),
+      })
+      const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string }
+      if (!res.ok) {
+        setStatus({ kind: 'error', message: body.detail ?? body.error ?? `HTTP ${res.status}` })
+        return
+      }
+      setStatus({ kind: 'sent' })
+      setName('')
+      setEmail('')
+      setMessage('')
+    } catch (err) {
+      setStatus({ kind: 'error', message: err instanceof Error ? err.message : labels.networkError })
+    }
+  }
+
+  if (status.kind === 'sent') {
+    return <p className="notice ok">{labels.sentNotice}</p>
+  }
+
+  const sending = status.kind === 'sending'
+  return (
+    <form onSubmit={onSubmit} className="contact-form">
+      <label htmlFor="name">{labels.name}</label>
+      <input id="name" required value={name} onChange={(e) => setName(e.target.value)} />
+
+      <label htmlFor="email">{labels.email}</label>
+      <input id="email" type="email" required value={email} onChange={(e) => setEmail(e.target.value)} />
+
+      <label htmlFor="message">{labels.message}</label>
+      <textarea id="message" required rows={5} value={message} onChange={(e) => setMessage(e.target.value)} />
+
+      {status.kind === 'error' && (
+        <p className="notice err">
+          {labels.errorPrefix} {status.message}
+        </p>
+      )}
+
+      <button type="submit" disabled={sending}>
+        {sending ? labels.sending : labels.send}
+      </button>
+    </form>
+  )
+}
+
+export default island(ContactForm, { name: 'ContactForm', hydrate: 'visible' })

package/templates/apps/frontend-contact/src/config.ts

@@ -0,0 +1,12 @@
+// Where the contact form POSTs.
+//
+// Default = the local `voltro serverless dev` port (8910), so the form works
+// the moment you run `pnpm fn:dev` in another terminal. For production, set
+// this to the URL `voltro serverless deploy` printed for your function (the
+// Cloudflare / Scaleway endpoint, or your self-hosted node sidecar).
+//
+// A plain constant — not `publicEnv` — so the template typechecks BEFORE
+// `voltro dev` generates the env types. To switch to typed env: declare
+// `VOLTRO_PUBLIC_CONTACT_FN_URL` in app.config.ts and, after one `voltro dev`,
+// read `publicEnv.VOLTRO_PUBLIC_CONTACT_FN_URL` from '@voltro/env/public'.
+export const CONTACT_ENDPOINT = 'http://localhost:8910'

package/templates/apps/frontend-contact/src/globals.css

@@ -0,0 +1,84 @@
+/* Self-contained styles — plain CSS, no Tailwind / kit dependency. */
+
+:root {
+  --bg: #ffffff;
+  --fg: #18181b;
+  --muted: #71717a;
+  --accent: #2563eb;
+  --ok: #16a34a;
+  --err: #dc2626;
+  --border: #e4e4e7;
+  --field: #f9fafb;
+}
+
+:root.dark {
+  --bg: #0a0a0a;
+  --fg: #fafafa;
+  --muted: #a1a1aa;
+  --accent: #60a5fa;
+  --ok: #4ade80;
+  --err: #f87171;
+  --border: #27272a;
+  --field: #18181b;
+}
+
+* { box-sizing: border-box; }
+html, body { margin: 0; min-height: 100vh; }
+
+body {
+  background: var(--bg);
+  color: var(--fg);
+  font: 16px/1.6 ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+}
+
+main { max-width: 38rem; margin: 0 auto; padding: 4rem 1.25rem 6rem; }
+
+/* Language switcher (Strategy B: each locale is its own URL). */
+.langswitch {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 0.5rem;
+  max-width: 38rem;
+  margin: 0 auto;
+  padding: 1rem 1.25rem 0;
+  font-size: 0.85rem;
+}
+.langswitch .label { color: var(--muted); }
+.langswitch a { color: var(--muted); text-decoration: none; }
+.langswitch a[aria-current='true'] { color: var(--accent); font-weight: 600; }
+
+.hero h1 { font-size: 2.25rem; margin: 0 0 0.5rem; }
+.lead { color: var(--muted); font-size: 1.05rem; margin: 0; }
+
+.contact { margin-top: 3rem; padding-top: 2rem; border-top: 1px solid var(--border); }
+.contact h2 { font-size: 1.25rem; margin: 0 0 1.25rem; }
+
+.contact-form { display: flex; flex-direction: column; gap: 0.4rem; }
+.contact-form label { font-size: 0.85rem; color: var(--muted); margin-top: 0.75rem; }
+.contact-form input,
+.contact-form textarea {
+  font: inherit;
+  color: var(--fg);
+  background: var(--field);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 0.6rem 0.75rem;
+  resize: vertical;
+}
+.contact-form button {
+  margin-top: 1.25rem;
+  padding: 0.7rem 1rem;
+  font: inherit;
+  font-weight: 600;
+  color: #fff;
+  background: var(--accent);
+  border: none;
+  border-radius: 8px;
+  cursor: pointer;
+}
+.contact-form button:disabled { opacity: 0.6; cursor: progress; }
+
+.notice { margin: 1rem 0 0; padding: 0.6rem 0.75rem; border-radius: 8px; font-size: 0.95rem; }
+.notice.ok { color: var(--ok); border: 1px solid var(--ok); }
+.notice.err { color: var(--err); border: 1px solid var(--err); }

package/templates/apps/frontend-contact/src/lib/locale.ts

@@ -0,0 +1,55 @@
+// The single source of truth for this app's locales + the URL-prefix
+// helpers. `app.config.ts` lists the same codes for the build pipeline;
+// the [locale] mirror page + the layout's <I18nProvider> read THIS file.
+//
+// Keep SUPPORTED_LOCALES / DEFAULT_LOCALE in sync with `locales` /
+// `defaultLocale` in app.config.ts.
+
+import { useLocation } from '@voltro/web'
+import en from '../locales/en'
+import de from '../locales/de'
+
+export const SUPPORTED_LOCALES = ['en', 'de'] as const
+export const DEFAULT_LOCALE = 'en'
+
+export type Locale = (typeof SUPPORTED_LOCALES)[number]
+
+// The catalogs, keyed by code. The layout picks one to feed the inner
+// <I18nProvider>; `meta` (build-time, per locale) reads one via getCatalog.
+export const CATALOGS = { en, de } as const
+
+// Every catalog mirrors `en`'s keys (defineLocale enforces it), so a
+// plain string-record over en's keys is the common type both satisfy —
+// what `meta` reads at build time (`c['meta.home.title']` → string).
+export type Messages = Record<keyof typeof en, string>
+
+const isSupported = (v: string): v is Locale =>
+  (SUPPORTED_LOCALES as ReadonlyArray<string>).includes(v)
+
+export const getCatalog = (locale: string): Messages =>
+  isSupported(locale) ? CATALOGS[locale] : CATALOGS[DEFAULT_LOCALE]
+
+// `/de` → 'de'; `/` → 'en' (default lives at the bare path).
+export const localeFromPathname = (pathname: string): Locale => {
+  const match = /^\/([a-z]{2})(?:\/|$)/.exec(pathname)
+  return match && isSupported(match[1]!) ? (match[1] as Locale) : DEFAULT_LOCALE
+}
+
+// Reactive: useLocation re-renders on client-side nav, so the layout's
+// provider swaps catalogs when you move between / and /de without a full
+// reload.
+export const useUrlLocale = (): Locale => localeFromPathname(useLocation())
+
+// '/' + 'de' → '/de'; the default locale stays bare ('/').
+export const withLocalePrefix = (path: string, locale: string): string => {
+  if (locale === DEFAULT_LOCALE) return path
+  const p = path.startsWith('/') ? path : `/${path}`
+  return p === '/' ? `/${locale}` : `/${locale}${p}`
+}
+
+// '/de' → '/'; '/' → '/'. The inverse of the above, used to keep the
+// active path when switching language.
+export const stripLocalePrefix = (pathname: string): string => {
+  const match = /^\/([a-z]{2})(\/.*|$)/.exec(pathname)
+  return match && isSupported(match[1]!) ? match[2] || '/' : pathname
+}

package/templates/apps/frontend-contact/src/locales/de.ts

@@ -0,0 +1,26 @@
+// German catalog. MUST mirror en.ts key-for-key — `defineLocale<typeof en>()`
+// returns a curried function that fails `tsc --noEmit` on a missing or extra
+// key, so translations can never silently drift out of sync.
+import { defineLocale } from '@voltro/i18n'
+import en from './en'
+
+export default defineLocale<typeof en>()({
+  'nav.language': 'Sprache',
+
+  'hero.lead':
+    'Diese Seite wird vorgerendert und von einem CDN ausgeliefert. Das Formular unten spricht mit einer Serverless-Funktion, die auf null skaliert — kein ständig laufender Server in Sicht.',
+  'contact.heading': 'Schreib uns eine Nachricht',
+
+  // Kontaktformular-Island-Beschriftungen (als `labels` durchgereicht).
+  'form.name':         'Name',
+  'form.email':        'E-Mail',
+  'form.message':      'Nachricht',
+  'form.send':         'Nachricht senden',
+  'form.sending':      'Wird gesendet…',
+  'form.sent':         'Danke — deine Nachricht ist unterwegs. ✓',
+  'form.errorPrefix':  'Senden fehlgeschlagen:',
+  'form.networkError': 'Netzwerkfehler',
+
+  'meta.home.title':       '{{capProjectName}} — Kontakt',
+  'meta.home.description': 'Statische Seite, Serverless-Kontaktformular.',
+})

package/templates/apps/frontend-contact/src/locales/en.ts

@@ -0,0 +1,29 @@
+// Base catalog — the source of truth. Every other locale (de.ts) mirrors
+// these keys EXACTLY; `defineLocale<typeof en>()` enforces that at `tsc`.
+//
+// Keep ICU placeholders identical across locales — react-intl validates
+// them at render time. Note: the island's copy lives here too (form.*) —
+// it is resolved on the page (inside the URL provider) and passed to the
+// island as a `labels` prop, because islands hydrate WITHOUT the provider.
+import { defineCatalog } from '@voltro/i18n'
+
+export default defineCatalog({
+  'nav.language': 'Language',
+
+  'hero.lead':
+    'This page is pre-rendered and ships from a CDN. The form below talks to a serverless function that scales to zero — no always-on server in sight.',
+  'contact.heading': 'Send us a message',
+
+  // Contact-form island labels (passed down as `labels`, not read via <T>).
+  'form.name':         'Name',
+  'form.email':        'Email',
+  'form.message':      'Message',
+  'form.send':         'Send message',
+  'form.sending':      'Sending…',
+  'form.sent':         'Thanks — your message is on its way. ✓',
+  'form.errorPrefix':  'Could not send:',
+  'form.networkError': 'network error',
+
+  'meta.home.title':       '{{capProjectName}} — Get in touch',
+  'meta.home.description': 'Static page, serverless contact form.',
+} as const)

package/templates/apps/frontend-contact/src/pages/[locale]/index.tsx

@@ -0,0 +1,14 @@
+// Locale mirror of `/` → renders `/de`. Re-exports the bare page verbatim
+// (the component reads its locale from the URL via the layout's provider,
+// and resolves the island's `labels` per-locale there); `getStaticPaths`
+// tells `voltro build` which locale-prefixed paths to emit. The default
+// locale is NOT listed here — it lives at the bare `/`.
+import { SUPPORTED_LOCALES, DEFAULT_LOCALE } from '../../lib/locale'
+
+export { default } from '../index'
+export { renderMode, interactive, meta } from '../index'
+
+export const getStaticPaths = async (): Promise<Array<{ params: { locale: string } }>> =>
+  SUPPORTED_LOCALES
+    .filter((l) => l !== DEFAULT_LOCALE)
+    .map((locale) => ({ params: { locale } }))

package/templates/apps/frontend-contact/src/pages/index.test.tsx

@@ -0,0 +1,70 @@
+// @vitest-environment jsdom
+//
+// `/` — the static, bilingual contact page. `renderMode='static'` +
+// `interactive='islands'` (only the <ContactForm> island hydrates). We assert
+// those config exports, the LOCALISED meta export (via getCatalog), and that
+// the hero + contact sections render their translated copy. The page resolves
+// its copy through @voltro/i18n, so we render it inside a real <I18nProvider>
+// with the English catalog. The <ContactForm> island is mocked to a sentinel
+// so this test covers the page shell in isolation; the island's own behavior
+// (and its `labels` prop) is tested in ContactForm.island.test.tsx.
+
+import { afterEach, describe, expect, test, vi } from 'vitest'
+import { act, createElement, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { I18nProvider } from '@voltro/i18n'
+import en from '../locales/en'
+
+vi.mock('../components/ContactForm.island', () => ({
+  default: () => createElement('div', { 'data-testid': 'contact-form' }, 'form'),
+}))
+
+const { default: Index, meta, renderMode, interactive } = await import('./index')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(
+      createElement(I18nProvider, { locale: 'en', messages: en, defaultLocale: 'en', children: node }),
+    )
+  })
+}
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('index — config + meta exports', () => {
+  test('is a static, islands-hydrated page', () => {
+    expect(renderMode).toBe('static')
+    expect(interactive).toBe('islands')
+  })
+
+  test('declares a localised document title + description', () => {
+    expect(meta({ locale: 'en' }).title).toContain('Get in touch')
+    expect(meta({ locale: 'en' }).description).toBe('Static page, serverless contact form.')
+    expect(meta({ locale: 'de' }).title).toContain('Kontakt')
+    expect(meta({ locale: 'de' }).description).toBe('Statische Seite, Serverless-Kontaktformular.')
+  })
+})
+
+describe('index — render', () => {
+  test('renders the hero heading + copy and the contact section with the form island', () => {
+    render(createElement(Index))
+    expect(container.querySelector('.hero h1')).toBeTruthy()
+    expect(container.textContent).toContain('pre-rendered')
+    const contact = container.querySelector('.contact')
+    expect(contact).toBeTruthy()
+    expect(contact!.querySelector('h2')!.textContent).toBe('Send us a message')
+    expect(container.querySelector('[data-testid="contact-form"]')).toBeTruthy()
+  })
+})

package/templates/apps/frontend-contact/src/pages/index.tsx

@@ -0,0 +1,63 @@
+// Static marketing page with a serverless contact form.
+//
+// `renderMode = 'static'` → pre-rendered HTML, servable from a CDN.
+// `interactive = 'islands'` → only the <ContactForm> island hydrates; the
+// headline + copy ship as plain HTML with no React lifecycle.
+//
+// Bilingual (Strategy B): mounted at `/` (default locale) and mirrored at
+// `/de` by src/pages/[locale]/index.tsx. `meta` is a FUNCTION of `{ locale }`
+// so each pre-rendered variant gets a localised <title>/<description>.
+//
+// The island can't read <T>/useT (it hydrates WITHOUT the layout's URL
+// provider). This page IS inside that provider, so it resolves the island's
+// strings here (useTFn) and hands them down as a fully-translated `labels`
+// prop — the framework serialises them into the island's HTML.
+
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { T, useTFn } from '@voltro/i18n'
+import { getCatalog } from '../lib/locale'
+import ContactForm from '../components/ContactForm.island'
+
+export const renderMode = 'static' as const
+export const interactive = 'islands' as const
+
+export const meta = ({ locale }: { locale: string }): PageMeta => {
+  const c = getCatalog(locale)
+  return {
+    title: c['meta.home.title'],
+    description: c['meta.home.description'],
+  }
+}
+
+export default function Index(): ReactNode {
+  const t = useTFn()
+  return (
+    <main>
+      <section className="hero">
+        <h1>{{capProjectName}}</h1>
+        <p className="lead">
+          <T id="hero.lead" />
+        </p>
+      </section>
+
+      <section className="contact">
+        <h2>
+          <T id="contact.heading" />
+        </h2>
+        <ContactForm
+          labels={{
+            name: t('form.name'),
+            email: t('form.email'),
+            message: t('form.message'),
+            send: t('form.send'),
+            sending: t('form.sending'),
+            sentNotice: t('form.sent'),
+            errorPrefix: t('form.errorPrefix'),
+            networkError: t('form.networkError'),
+          }}
+        />
+      </section>
+    </main>
+  )
+}

package/templates/apps/frontend-contact/src/pages/layout.tsx

@@ -0,0 +1,65 @@
+// Root layout. The framework's auto-wired <I18nProvider> is COOKIE-driven
+// (Strategy A). For URL-prefix routing (Strategy B) we add an INNER provider
+// that reads the locale FROM THE URL, so client-side navigation between / and
+// /de swaps the catalog without a full reload. At build time it resolves to
+// the same locale the SSG pipeline pre-rendered.
+//
+// NOTE: the <ContactForm> island hydrates INDEPENDENTLY of this provider, so
+// it can't read <T>/useT. The page resolves its strings here (inside this
+// provider) and passes them down as a `labels` prop — see src/pages/index.tsx.
+//
+// `<html>`/`<head>`/`<body>` are owned by the framework shell — don't render
+// them here. Page <title> + meta come from each page's `meta` export.
+
+import type { ReactNode } from 'react'
+import { I18nProvider, T } from '@voltro/i18n'
+import { useLocation } from '@voltro/web'
+import {
+  CATALOGS,
+  DEFAULT_LOCALE,
+  SUPPORTED_LOCALES,
+  stripLocalePrefix,
+  useUrlLocale,
+  withLocalePrefix,
+} from '../lib/locale'
+import '../globals.css'
+
+function LangSwitcher(): ReactNode {
+  const locale = useUrlLocale()
+  // The path WITHOUT its locale prefix — so the language switch keeps you
+  // on the same page (e.g. /de → /, then re-prefix per locale).
+  const barePath = stripLocalePrefix(useLocation())
+
+  // Plain <a> (not <Link>): these hrefs are COMPUTED per locale, and
+  // <Link to> wants a statically-known `VoltroUrl` literal. The Router's
+  // global click interceptor SPA-navigates internal <a> anyway, so the
+  // inner provider still swaps catalogs without a full reload.
+  return (
+    <nav className="langswitch">
+      <span className="label">
+        <T id="nav.language" />:
+      </span>
+      {SUPPORTED_LOCALES.map((code) => (
+        <a
+          key={code}
+          href={withLocalePrefix(barePath, code)}
+          aria-current={code === locale ? 'true' : undefined}
+        >
+          {code.toUpperCase()}
+        </a>
+      ))}
+    </nav>
+  )
+}
+
+export default function Layout({ children }: { readonly children: ReactNode }): ReactNode {
+  const locale = useUrlLocale()
+  return (
+    <I18nProvider locale={locale} messages={CATALOGS[locale]} defaultLocale={DEFAULT_LOCALE}>
+      <div className="shell">
+        <LangSwitcher />
+        {children}
+      </div>
+    </I18nProvider>
+  )
+}

package/templates/apps/frontend-contact/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "frontend-contact",
+  "kind": "web",
+  "summary": "Static site + a serverless email contact form — the headline 'static frontend, serverless backend' combo. A static page hosts an island form that POSTs to functions/sendMessage.serverless.ts, which sends mail via Resend over HttpClient. The function deploys SEPARATELY with `voltro serverless` (scales to zero) while the page goes to any CDN.",
+  "tags": ["web", "frontend", "static", "serverless", "contact", "email", "form", "islands", "resend"]
+}

package/templates/apps/frontend-contact/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler"
+  },
+  "include": ["src/**/*", "functions/**/*"],
+  "exclude": ["node_modules", "dist", ".framework"]
+}

package/templates/apps/frontend-dashboard/README.md

@@ -0,0 +1,54 @@
+# {{projectName}} / {{appName}}
+
+Voltro web app scaffold (template: **frontend-dashboard**) — an
+authenticated dashboard shell with a public marketing area.
+
+## Boot
+
+```bash
+pnpm install
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:{{port}}
+```
+
+Open `/dashboard` while signed out → you're redirected to `/login`. Click
+**Continue as Demo User** → the gate lets you in.
+
+## What this shows
+
+- **Route groups** — `src/pages/(marketing)/` is a *silent* route group:
+  the parens organise files + scope a layout WITHOUT adding a URL segment,
+  so its pages are `/` and `/login`. The `/dashboard` area is a real dir
+  (real prefix) by contrast.
+- **A nested layout loader as an auth gate** — `dashboard/layout.tsx`
+  exports a `loader` that runs once for every page beneath it, server-side,
+  before render. It checks the session and `throw`s `RedirectError('/login')`
+  when there's none. On SSR that's a `303`; on client navigation it's a
+  `replace` redirect.
+- **`renderMode: 'ssr'`** on the dashboard pages — required so the gate runs
+  per request. A `static` page can't redirect per-visitor, and the build
+  rejects a `RedirectError` there.
+- **Scoped special files** — `dashboard/error.tsx` (error boundary),
+  `dashboard/loading.tsx` (opt-in skeleton), `dashboard/not-found.tsx`
+  (scoped 404). Each applies to every page under `/dashboard`.
+
+## The demo gate
+
+`src/lib/auth.ts` is a cookie-only stand-in so the template boots with **no
+backend**: `login` writes a `demo_session` cookie, the dashboard loader
+reads it (from the request `Cookie` header on SSR, or `document.cookie` on
+client nav). Swap `isSignedIn` for a real check — verify a signed session,
+or call an api — when you wire auth for real. See AGENTS.md › *Auth*.
+
+## Wire a backend
+
+Add an api and an `apis:` entry in `app.config.ts`, then read live data in
+the dashboard pages with `useSubscription`. The gate stays the same — only
+its session check moves from a demo cookie to your real session.
+
+## Build + serve
+
+```bash
+voltro build .     # static marketing pages + an SSR bundle for /dashboard
+voltro start .     # serve: / + /login are static; /dashboard renders per request
+```

package/templates/apps/frontend-dashboard/app.config.ts

@@ -0,0 +1,39 @@
+// Web app for the {{projectName}} project — an authenticated DASHBOARD shell.
+//
+// Two areas, two shapes:
+//   - Public pages live in a SILENT route group `src/pages/(marketing)/`
+//     (the parens organise files + scope a layout WITHOUT adding a URL
+//     segment — `/` and `/login`, not `/(marketing)/...`).
+//   - The authed area lives under `src/pages/dashboard/` (a real `/dashboard`
+//     prefix). Its `layout.tsx` exports a `loader` that gates the session and
+//     throws RedirectError to `/login` when there's none. Those pages are
+//     `renderMode: 'ssr'` so the gate runs per request (a `static` page can't
+//     redirect per-visitor — the build would reject it).
+//
+// No api wired — the auth gate reads a demo cookie, so this is a pure
+// frontend you can `voltro build` + `voltro start` as-is. Swap the cookie
+// check for a real session (add an api + `apis:`) when you have one.
+import { defineEnv, envVar } from '@voltro/env'
+
+// Public, build-time env (baked into the bundle; read via `publicEnv`).
+// Never a secret here. A secret belongs on the api, not the browser bundle.
+export const env = defineEnv({
+  VOLTRO_PUBLIC_APP_NAME: envVar.string({ access: 'public', default: '{{capProjectName}}' }),
+})
+
+export default {
+  type: 'web' as const,
+  name: '{{capProjectName}}{{capAppName}}',
+  port: {{port}},
+  // Follow the visitor's OS theme, set before first paint (no flash).
+  theme: 'system' as const,
+  env,
+  // Bilingual by default. The framework auto-wires a cookie-driven
+  // <I18nProvider> from these codes and loads the matching
+  // `src/locales/<code>.ts` catalog — so `<T id="…" />` / `useT()` /
+  // `useLocale()` work app-wide with no manual setup. The <LocaleSwitcher>
+  // in the layout writes the `voltro:lang` cookie + reloads. Grow the app to
+  // more languages by adding a code here + a `src/locales/<code>.ts`.
+  locales:       ['en', 'de'] as const,
+  defaultLocale: 'en'         as const,
+}