First Success Validation

First success means the custom server.ts / Next app serves pages, Auth.js v5 can establish a session, DatabaseService reads/writes without adapter crashes, and core marketplace routes load. It does not require WayForPay, Stripe, PayPal, FCM, or wallet connectivity on day one.

Recommended path

Use LegioX MCP legiox-env-validator (or ask the agent with the prompt below) before chasing UI failures. It reports missing env — it does not mutate .env, restart processes, or call PSPs until you approve.

Starter prompt:

Validate this clone for first-success smoke: AUTH_SECRET, DB_BACKEND_MODE / Postgres DB_*, and optional WAYFORPAY_* / STRIPE_* / PAYPAL_*. List missing vars and the Core vs Optional-payment checklist from /docs/getting-started/first-success. Do not write secrets or restart the server until I approve.

Inputs checklist

• Working tree after install + migrations
• .env.local from env.local.template (or k8s secret mount)
• Browser on http://localhost:3000 (or your configured site URL)
• Optional: WayForPay / Stripe / PayPal sandbox credentials

Manual path

Checklist summary

Frequently asked questions

Impact

Will my clone work without payments?

Yes. Core first success is auth + data path. PaymentConductor is optional until you demo paid membership or store checkout.

Does tunnel ready mean SSE is live?

No. /api/tunnel/test confirms config/provider detection. Live streams need a signed-in client hitting /api/tunnel/sse (or your configured provider).

Migration

Do I need 004_payment_transactions for Core?

No. Apply it before Optional payment smoke so the ledger can record membership / store intents.

Firebase-only prototype?

firebase-full can pass homepage + auth for a prototype, but PaymentConductor depth and ERP/news features expect Postgres-primary (k8s-postgres-fcm / supabase-fcm). See Database selection.

Ops

Health returns 503 with degraded — is the app down?

Process is up; missing AUTH_SECRET (Postgres path) or Firebase critical vars degrade status. Set secrets, restart, re-curl.

Wallet balance 404?

GET /api/wallet/balance returns 404 when no wallet row exists yet — not a Core failure. Create/top-up via wallet flows after auth.

Related documentation

First Success Validation

First success means the custom server.ts / Next app serves pages, Auth.js v5 can establish a session, DatabaseService reads/writes without adapter crashes, and core marketplace routes load. It does not require WayForPay, Stripe, PayPal, FCM, or wallet connectivity on day one.

Recommended path

Use LegioX MCP legiox-env-validator (or ask the agent with the prompt below) before chasing UI failures. It reports missing env — it does not mutate .env, restart processes, or call PSPs until you approve.

Starter prompt:

Validate this clone for first-success smoke: AUTH_SECRET, DB_BACKEND_MODE / Postgres DB_*, and optional WAYFORPAY_* / STRIPE_* / PAYPAL_*. List missing vars and the Core vs Optional-payment checklist from /docs/getting-started/first-success. Do not write secrets or restart the server until I approve.

Inputs checklist

• Working tree after install + migrations
• .env.local from env.local.template (or k8s secret mount)
• Browser on http://localhost:3000 (or your configured site URL)
• Optional: WayForPay / Stripe / PayPal sandbox credentials

Manual path

Checklist summary

Frequently asked questions

Impact

Will my clone work without payments?

Yes. Core first success is auth + data path. PaymentConductor is optional until you demo paid membership or store checkout.

Does tunnel ready mean SSE is live?

No. /api/tunnel/test confirms config/provider detection. Live streams need a signed-in client hitting /api/tunnel/sse (or your configured provider).

Migration

Do I need 004_payment_transactions for Core?

No. Apply it before Optional payment smoke so the ledger can record membership / store intents.

Firebase-only prototype?

firebase-full can pass homepage + auth for a prototype, but PaymentConductor depth and ERP/news features expect Postgres-primary (k8s-postgres-fcm / supabase-fcm). See Database selection.

Ops

Health returns 503 with degraded — is the app down?

Process is up; missing AUTH_SECRET (Postgres path) or Firebase critical vars degrade status. Set secrets, restart, re-curl.

Wallet balance 404?

GET /api/wallet/balance returns 404 when no wallet row exists yet — not a Core failure. Create/top-up via wallet flows after auth.

Related documentation

First Success Validation

First success means the custom server.ts / Next app serves pages, Auth.js v5 can establish a session, DatabaseService reads/writes without adapter crashes, and core marketplace routes load. It does not require WayForPay, Stripe, PayPal, FCM, or wallet connectivity on day one.

Recommended path

Use LegioX MCP legiox-env-validator (or ask the agent with the prompt below) before chasing UI failures. It reports missing env — it does not mutate .env, restart processes, or call PSPs until you approve.

Starter prompt:

Validate this clone for first-success smoke: AUTH_SECRET, DB_BACKEND_MODE / Postgres DB_*, and optional WAYFORPAY_* / STRIPE_* / PAYPAL_*. List missing vars and the Core vs Optional-payment checklist from /docs/getting-started/first-success. Do not write secrets or restart the server until I approve.

Inputs checklist

• Working tree after install + migrations
• .env.local from env.local.template (or k8s secret mount)
• Browser on http://localhost:3000 (or your configured site URL)
• Optional: WayForPay / Stripe / PayPal sandbox credentials

Manual path

Checklist summary

Frequently asked questions

Impact

Will my clone work without payments?

Yes. Core first success is auth + data path. PaymentConductor is optional until you demo paid membership or store checkout.

Does tunnel ready mean SSE is live?

No. /api/tunnel/test confirms config/provider detection. Live streams need a signed-in client hitting /api/tunnel/sse (or your configured provider).

Migration

Do I need 004_payment_transactions for Core?

No. Apply it before Optional payment smoke so the ledger can record membership / store intents.

Firebase-only prototype?

firebase-full can pass homepage + auth for a prototype, but PaymentConductor depth and ERP/news features expect Postgres-primary (k8s-postgres-fcm / supabase-fcm). See Database selection.

Ops

Health returns 503 with degraded — is the app down?

Process is up; missing AUTH_SECRET (Postgres path) or Firebase critical vars degrade status. Set secrets, restart, re-curl.

Wallet balance 404?

GET /api/wallet/balance returns 404 when no wallet row exists yet — not a Core failure. Create/top-up via wallet flows after auth.

Related documentation

1. 1

   1 — Dev server

   Expect Next.js ready on http://localhost:3000. Package script runs node --import tsx server.ts. With RING_DEPLOY_TARGET=self-hosted, custom server may log native WSS.

2. 2

   2 — Health

   Verified shape (app/api/health/route.ts): status is healthy | degraded | unhealthy (not "ok"). services.database is postgresql or firebase. Missing AUTH_SECRET → degraded and HTTP 503. HEAD returns 200 when the process is up.

3. 3

   3 — Homepage + sign-in

   1. Open / — expect HTTP 200; no blank screen or adapter crash in the terminal.
   2. Visit /login (locale prefix may apply: /en/login).
   3. Complete one provider from auth.ts: Google OAuth, Apple, Ring Mailer (OTP / magic link / email+password), Google One Tap, or crypto-wallet credentials. Default tree does not ship GitHub/Discord.
   4. Confirm session: /profile shows user data; refresh persists. Optional: GET /api/auth/session with browser cookies returns { user: { id, email, role, … } }.
4. 4

   4 — Authenticated CRUD

   /api/entities and /api/opportunities require a session — 401 without cookies is expected.

   After browser login:

   1. /entities — list + create form submits (visitor may 403 on write — use member/admin test account).
   2. /opportunities — list loads for your role.

   Optional Postgres check:

   Expect count ≥ 1 after first sign-in. There is no /api/test-db route — use psql or authenticated APIs.

5. 5

   5 — Tunnel readiness (extended)

   Expect "ready" and a provider list from lib/tunnel/config. Live SSE: Network tab → /api/tunnel/sse after sign-in. See Tunnel protocol.

6. 6

   6 — PaymentConductor membership smoke (optional)

   Only after Migrations applied 004_payment_transactions.sql and you set processor env from env.local.template (WAYFORPAY_*, and/or STRIPE_*, and/or PAYPAL_*).

   1. Sign in as a non-admin user who can upgrade (UPGRADEABLE_ROLES — not platform-admin purchase).
   2. Open /membership → choose a higher tier and a configured rail (card → WayForPay/Stripe via PaymentConductor, paypal, or credit_balance if the wallet has balance).
   3. Server Action initiateMembershipPayment (app/_actions/membership-payment.ts) calls PaymentConductor.createCheckout({ purpose: 'membership_upgrade', … }) (or SubscriptionConductor first for some rails).
   4. Expect a redirect URL / form-post fields to the PSP, or an immediate success path for internal credit.
   5. Canonical webhooks (production/sandbox callback URLs): /api/payments/wayforpay/webhook, /api/payments/stripe/webhook, /api/payments/paypal/webhook (getWebhookUrl in lib/payments/payment.config.ts).
   6. After Approved / checkout.session.completed / PayPal capture handling, UI lands on /membership/success or /membership/failure.

   Do not claim production checkout until HMAC/signature verification and return URLs match your public site URL. Deep dive: PaymentConductor.

When to stop and fix

• Repeated Postgres connection failures → Prerequisites DB_* / DB_BACKEND_MODE.
• Login redirect loop → AUTH_SECRET and OAuth redirect URIs (http://localhost:3000/api/auth/callback/google).
• Entity save 403 → expected for visitor; sign in as member or raise the test account role.
• Membership initiate errors with missing merchant keys → set WAYFORPAY_* / Stripe / PayPal before retrying.

Troubleshooting

Same-workflow: auth and database fixes when a checklist row stays red.

1. 1

   1 — Dev server

   Expect Next.js ready on http://localhost:3000. Package script runs node --import tsx server.ts. With RING_DEPLOY_TARGET=self-hosted, custom server may log native WSS.

2. 2

   2 — Health

   Verified shape (app/api/health/route.ts): status is healthy | degraded | unhealthy (not "ok"). services.database is postgresql or firebase. Missing AUTH_SECRET → degraded and HTTP 503. HEAD returns 200 when the process is up.

3. 3

   3 — Homepage + sign-in

   1. Open / — expect HTTP 200; no blank screen or adapter crash in the terminal.
   2. Visit /login (locale prefix may apply: /en/login).
   3. Complete one provider from auth.ts: Google OAuth, Apple, Ring Mailer (OTP / magic link / email+password), Google One Tap, or crypto-wallet credentials. Default tree does not ship GitHub/Discord.
   4. Confirm session: /profile shows user data; refresh persists. Optional: GET /api/auth/session with browser cookies returns { user: { id, email, role, … } }.
4. 4

   4 — Authenticated CRUD

   /api/entities and /api/opportunities require a session — 401 without cookies is expected.

   After browser login:

   1. /entities — list + create form submits (visitor may 403 on write — use member/admin test account).
   2. /opportunities — list loads for your role.

   Optional Postgres check:

   Expect count ≥ 1 after first sign-in. There is no /api/test-db route — use psql or authenticated APIs.

5. 5

   5 — Tunnel readiness (extended)

   Expect "ready" and a provider list from lib/tunnel/config. Live SSE: Network tab → /api/tunnel/sse after sign-in. See Tunnel protocol.

6. 6

   6 — PaymentConductor membership smoke (optional)

   Only after Migrations applied 004_payment_transactions.sql and you set processor env from env.local.template (WAYFORPAY_*, and/or STRIPE_*, and/or PAYPAL_*).

   1. Sign in as a non-admin user who can upgrade (UPGRADEABLE_ROLES — not platform-admin purchase).
   2. Open /membership → choose a higher tier and a configured rail (card → WayForPay/Stripe via PaymentConductor, paypal, or credit_balance if the wallet has balance).
   3. Server Action initiateMembershipPayment (app/_actions/membership-payment.ts) calls PaymentConductor.createCheckout({ purpose: 'membership_upgrade', … }) (or SubscriptionConductor first for some rails).
   4. Expect a redirect URL / form-post fields to the PSP, or an immediate success path for internal credit.
   5. Canonical webhooks (production/sandbox callback URLs): /api/payments/wayforpay/webhook, /api/payments/stripe/webhook, /api/payments/paypal/webhook (getWebhookUrl in lib/payments/payment.config.ts).
   6. After Approved / checkout.session.completed / PayPal capture handling, UI lands on /membership/success or /membership/failure.

   Do not claim production checkout until HMAC/signature verification and return URLs match your public site URL. Deep dive: PaymentConductor.

When to stop and fix

• Repeated Postgres connection failures → Prerequisites DB_* / DB_BACKEND_MODE.
• Login redirect loop → AUTH_SECRET and OAuth redirect URIs (http://localhost:3000/api/auth/callback/google).
• Entity save 403 → expected for visitor; sign in as member or raise the test account role.
• Membership initiate errors with missing merchant keys → set WAYFORPAY_* / Stripe / PayPal before retrying.

Troubleshooting

Same-workflow: auth and database fixes when a checklist row stays red.

1. 1

   1 — Dev server

   Expect Next.js ready on http://localhost:3000. Package script runs node --import tsx server.ts. With RING_DEPLOY_TARGET=self-hosted, custom server may log native WSS.

2. 2

   2 — Health

   Verified shape (app/api/health/route.ts): status is healthy | degraded | unhealthy (not "ok"). services.database is postgresql or firebase. Missing AUTH_SECRET → degraded and HTTP 503. HEAD returns 200 when the process is up.

3. 3

   3 — Homepage + sign-in

   1. Open / — expect HTTP 200; no blank screen or adapter crash in the terminal.
   2. Visit /login (locale prefix may apply: /en/login).
   3. Complete one provider from auth.ts: Google OAuth, Apple, Ring Mailer (OTP / magic link / email+password), Google One Tap, or crypto-wallet credentials. Default tree does not ship GitHub/Discord.
   4. Confirm session: /profile shows user data; refresh persists. Optional: GET /api/auth/session with browser cookies returns { user: { id, email, role, … } }.
4. 4

   4 — Authenticated CRUD

   /api/entities and /api/opportunities require a session — 401 without cookies is expected.

   After browser login:

   1. /entities — list + create form submits (visitor may 403 on write — use member/admin test account).
   2. /opportunities — list loads for your role.

   Optional Postgres check:

   Expect count ≥ 1 after first sign-in. There is no /api/test-db route — use psql or authenticated APIs.

5. 5

   5 — Tunnel readiness (extended)

   Expect "ready" and a provider list from lib/tunnel/config. Live SSE: Network tab → /api/tunnel/sse after sign-in. See Tunnel protocol.

6. 6

   6 — PaymentConductor membership smoke (optional)

   Only after Migrations applied 004_payment_transactions.sql and you set processor env from env.local.template (WAYFORPAY_*, and/or STRIPE_*, and/or PAYPAL_*).

   1. Sign in as a non-admin user who can upgrade (UPGRADEABLE_ROLES — not platform-admin purchase).
   2. Open /membership → choose a higher tier and a configured rail (card → WayForPay/Stripe via PaymentConductor, paypal, or credit_balance if the wallet has balance).
   3. Server Action initiateMembershipPayment (app/_actions/membership-payment.ts) calls PaymentConductor.createCheckout({ purpose: 'membership_upgrade', … }) (or SubscriptionConductor first for some rails).
   4. Expect a redirect URL / form-post fields to the PSP, or an immediate success path for internal credit.
   5. Canonical webhooks (production/sandbox callback URLs): /api/payments/wayforpay/webhook, /api/payments/stripe/webhook, /api/payments/paypal/webhook (getWebhookUrl in lib/payments/payment.config.ts).
   6. After Approved / checkout.session.completed / PayPal capture handling, UI lands on /membership/success or /membership/failure.

   Do not claim production checkout until HMAC/signature verification and return URLs match your public site URL. Deep dive: PaymentConductor.

When to stop and fix

• Repeated Postgres connection failures → Prerequisites DB_* / DB_BACKEND_MODE.
• Login redirect loop → AUTH_SECRET and OAuth redirect URIs (http://localhost:3000/api/auth/callback/google).
• Entity save 403 → expected for visitor; sign in as member or raise the test account role.
• Membership initiate errors with missing merchant keys → set WAYFORPAY_* / Stripe / PayPal before retrying.

Troubleshooting

Same-workflow: auth and database fixes when a checklist row stays red.