phase-0: foundation, both apps boot end to end

Monorepo (pnpm workspaces) with two deployable apps and three pure packages.

apps/api (Hono on Node): Zod validated env that fails fast and names the problem,
Kysely factories for SQLite and Postgres chosen by DATABASE_URL scheme, portable
migrations covering the whole SPEC section 5 schema, Better Auth with the four
roles and seeded demo accounts, localized error envelope, /healthz and /readyz,
graceful SIGTERM drain. Dialect specific SQL is confined to the two factories.

apps/web (Next.js App Router): locale routed shell in es and en with a language
switcher, sign in screen, and a runtime /api proxy so the browser only ever sees
one origin and cookies stay first party.

packages/i18n ships both catalogs complete; es is generated from COPY.md and a
test re-derives it from the document on every run so it cannot drift.
packages/contracts holds the Zod schemas and the typed client the web app uses.

Verified: 43 vitest tests, 14 Playwright tests on mobile and desktop, typecheck
and lint clean, migrate and seed from a clean database, sign in through the proxy
with CSRF rejection of foreign origins.

Not verified here: docker compose. This user has no access to the docker socket.

RULES.md is absent from docs/, so packages/rules exports only RULES_VERSION and
no tax rule, check digit or deadline was invented. See DECISIONS.md.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

e2e/language.spec.ts

@@ -0,0 +1,42 @@
+import { es, en } from '@impuestos/i18n';
+import { expect, test } from '@playwright/test';
+
+test.describe('sign in screen', () => {
+  test('renders in Spanish by default', async ({ page }) => {
+    await page.goto('/es/login');
+    await expect(page.getByRole('heading', { name: es['auth.login.title'] })).toBeVisible();
+    await expect(page.getByLabel(es['auth.register.email'])).toBeVisible();
+    await expect(page.getByRole('button', { name: es['auth.login.submit'] })).toBeVisible();
+  });
+
+  test('the language switcher flips it to English and stays on the page', async ({ page }) => {
+    await page.goto('/es/login');
+    await page.getByLabel(es['common.language']).selectOption('en');
+
+    await expect(page).toHaveURL(/\/en\/login$/);
+    await expect(page.getByRole('heading', { name: en['auth.login.title'] })).toBeVisible();
+    await expect(page.getByRole('button', { name: en['auth.login.submit'] })).toBeVisible();
+  });
+
+  test('the choice survives a reload', async ({ page }) => {
+    await page.goto('/en/login');
+    await page.reload();
+    await expect(page.getByRole('heading', { name: en['auth.login.title'] })).toBeVisible();
+  });
+
+  // The en catalog exists for expats and international users (COPY.md section 0-EN),
+  // so the root honours the browser language and falls back to es, the default.
+  test('the root follows the browser language', async ({ browser }) => {
+    for (const [locale, expected] of [
+      ['es-PY', /\/es\/login$/],
+      ['en-US', /\/en\/login$/],
+      ['pt-BR', /\/es\/login$/],
+    ] as const) {
+      const context = await browser.newContext({ locale });
+      const page = await context.newPage();
+      await page.goto('/');
+      await expect(page, locale).toHaveURL(expected);
+      await context.close();
+    }
+  });
+});

e2e/sign-in.spec.ts

@@ -0,0 +1,35 @@
+import { es } from '@impuestos/i18n';
+import { expect, test } from '@playwright/test';
+
+/**
+ * The full first party chain in a real browser: the page posts to /api on the web
+ * origin, the proxy forwards it, better-auth sets the session cookie, and the next
+ * server render reads it back.
+ */
+test.describe('signing in', () => {
+  test('a seeded account reaches the app shell', async ({ page }) => {
+    await page.goto('/es/login');
+    await page.getByLabel(es['auth.register.email']).fill('maria@demo.local');
+    await page.getByLabel(es['auth.login.password']).fill('demo-maria-1');
+    await page.getByRole('button', { name: es['auth.login.submit'] }).click();
+
+    await expect(page).toHaveURL(/\/es\/inicio$/);
+    await expect(page.getByRole('heading', { name: es['home.title'] })).toBeVisible();
+  });
+
+  test('a wrong password says so without blaming the user', async ({ page }) => {
+    await page.goto('/es/login');
+    await page.getByLabel(es['auth.register.email']).fill('maria@demo.local');
+    await page.getByLabel(es['auth.login.password']).fill('not-the-password');
+    await page.getByRole('button', { name: es['auth.login.submit'] }).click();
+
+    // Scoped to the form: Next's route announcer is also role="alert".
+    await expect(page.locator('form').getByRole('alert')).toHaveText(es['auth.login.failed']);
+    await expect(page).toHaveURL(/\/es\/login$/);
+  });
+
+  test('the app shell is not reachable without a session', async ({ page }) => {
+    await page.goto('/es/inicio');
+    await expect(page).toHaveURL(/\/es\/login$/);
+  });
+});