fix(dev): make the local tenant-site fallback self-explanatory

[Asapteejo]

The report

npm run dev + http://localhost:3000 renders the platform marketing page instead of a tenant site, logging:

"fallbackSlug":"acme-realty","resolvedCompanyId":null,
"fallbackToPlatform":true,"fallbackReason":"no-tenant-host-match"

The natural reading is "my local database has no seeded company". That reading is wrong, and the README actively encouraged it.

What is actually happening

Verified against the local database before changing anything:

Check	Result
Database reachable	Yes — estateos_dev at localhost:5432
Schema applied	Yes — prisma migrate status: up to date, 51/51
acme-realty company exists	Yes — ?devTenant=acme-realty and acme-realty.localhost:3000 both render it
/api/readyz	configured: true, migrations.missing: []

The cause is in resolveTenantContext:

const resolvedCompany = area === "marketing"
  ? hintedCompany                                          // host or ?devTenant ONLY
  : selectAuthenticatedCompany({ ..., fallbackCompany });   // DEFAULT_COMPANY_SLUG lives here

DEFAULT_COMPANY_SLUG is deliberately not consulted for public pages, so a fallback can never serve one tenant's public site on another host in production. localhost therefore can never show a tenant site regardless of seeding — the log even shows the fallback slug being resolved and then discarded.

No production rule is changed here. Only the explanation is.

Changes

1. Actionable dev log — on fallback, development now logs the cause, both supported entry points, and the company slugs actually present, so an unseeded database is distinguishable from correct host-based behavior:

   No tenant site matched host "localhost:3000", so the platform marketing page is being rendered. Public pages resolve the tenant from the host; DEFAULT_COMPANY_SLUG applies to signed-in areas only… Companies in this database: acme-realty. To open a tenant site locally use http://localhost:3000/?devTenant=acme-realty (needs DEV_ACCESS_MODE=true) or http://acme-realty.localhost:3000.

   Once per host per process, never in production. When no companies exist it says to run npm run db:seed.

2. README — corrected the false claim that public pages use DEFAULT_COMPANY_SLUG in development (the line that caused this), and added "Opening A Tenant Site Locally" with both workflows and the create/migrate/seed commands.

3. CI — the E2E server now runs as NODE_ENV=development rather than test. Next skips .env.local under NODE_ENV=test, so running CI's own command locally started a server with no database and reported every migration missing. That false failure cost real debugging time in this session; development keeps the dev-session bypass available on a production build and loads .env.local locally, while CI supplies its database through the job env either way.

Verification

Command	Result
npm run check	535 tests, typecheck, lint, build — green
npm run migrations:check	manifest up to date (51 migrations)
E2E suite	63 passed, 3.0m

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
estate-os	Ready	Preview	Sep 17, 2026 9:09am UTC