E2E scaffold + port-band convention (30xx dev / 31xx e2e)

[denkasyanov]

Bake the Playwright E2E setup + the devsite port-band convention into the template, so new projects inherit it with zero per-project design.

Port-band convention (from devsite)

• 30xx = dev servers — one per project via package.json#devSite.port (3000–3099).
• 31xx = e2e web server — derived, never stored: devSite.port + 100 (3100–3199).

Properties: dev + e2e coexist (different bands); no cross-project collision (uniqueness inherited from dev port); nothing beyond the dev port is ever tracked. Optional devSite.e2ePort override for a rare clash. 100 project slots.

E2E harness shape (proven in muxa-io)

• Convex preview deployment per run (convex deploy --preview-create, seeded via reset) — no separate project, fresh DB per CI run.
• Public _testing.reset mutation hard-guarded by E2E_TEST_MODE=true (a default preview env var) — fails closed on dev/prod.
• Real WorkOS sign-in in globalSetup → saved storageState; authenticated + unauthenticated Playwright projects.
• Web server: CLOUDFLARE_ENV=e2e loads .dev.vars.e2e (localhost redirect at dev+100), VITE_CONVEX_URL from the preview URL file.
• WorkOS requires the exact callback port allowlisted (no port wildcards), so the derived port is registered once per project: http://localhost:<devPort+100>/api/auth/callback.

Reference implementation

Landing in the muxa-io repo — copy apps/web/e2e/, the _testing.ts mutation, the docs/e2e-testing.md convention doc, and the devsite README port-band section. (Once @dendotai/devsite is extracted, the +100 derivation belongs in it.)

Capture-only issue — do the actual template port in the template repo, not from muxa-io.

[denkasyanov]

Setup runbook is a first-class template deliverable

Per-project provisioning is the biggest friction when spinning up a new project, so the template must ship an ordered, automation-first runbook — not just a list of secrets. Shape it exactly like the reference implementation in muxa-io's docs/e2e-testing.md → "One-time setup":

1. Password manager = source of truth. List the exact secrets to store first; every later step reads from here, piped in (op read / equivalent) so a raw value never hits a file or clipboard.
2. Dashboard-only steps, explicitly flagged — only the things with no CLI/API:
   • Convex: Generate Preview Deploy Key (deploy keys can't be minted via CLI) → store in the vault.
   • WorkOS: add the two localhost redirect entries (Redirect URIs + Sign-out redirects).
3. Automate everything else from the vault with copy-pasteable commands:
   • convex env default set --type preview … for the default preview env vars.
   • op read … | gh secret set … for each CI secret.
4. Local gitignored files (.dev.vars.e2e, e2e/.env.test) filled from the vault.

Key principle to carry into the template: state what to add, where, and in what order — and automate the maximum via CLI, leaving only genuinely dashboard-only steps manual. Use generic op://<vault>/<item>/<field> placeholders (no real vault/item names) so it's copy-ready for any project.

[denkasyanov]

Password-manager adapter — opinionated on "secure storage," agnostic on which tool

The template should be opinionated that secrets come from a secure store, but not assume 1Password specifically — users may run Vault, Doppler, AWS/GCP secret managers, an enterprise store, or (god forbid) LastPass. Optimize so swapping providers is trivial.

Borrow the shape of a code adapter/interface, but keep it prose/spec-level — LLM-optimized, not enforced types. An agent should be able to read the contract and generate a new adapter for an unlisted provider.

The contract (what any provider must supply):

Capability	Meaning	Example (1Password)
read(ref) -> value	resolve one secret by reference, print to stdout, never persist	op read 'op://<vault>/<item>/<field>'
ref format	a stable, copy-pasteable pointer to one secret	op://<vault>/<item>/<field>
auth	how the CLI authenticates (out of band)	1Password app / op signin

The runbook is written against the abstract read(ref) op; each provider is an adapter implementing it. Ship 1Password as the default adapter, plus a "swap your provider" table:

Provider	read(ref)
1Password (default)	op read 'op://vault/item/field'
HashiCorp Vault	vault kv get -field=<field> <path>
Doppler	doppler secrets get <NAME> --plain
AWS Secrets Manager	aws secretsmanager get-secret-value --secret-id <id> --query SecretString --output text
env / CI	printenv <NAME>

Every runbook command then reads "$(read <ref>)" and pipes into convex env default set / gh secret set — so switching providers = swapping one adapter line, nothing else. Keep the LLM angle explicit: a one-paragraph "to add a provider, implement read(ref) and add a row" note so an agent can extend it without touching the rest.