docs(env): document multi-tenant overlay envs (EVO-1631 NEST-3)

[marcelogorutuba]

Summary

• Documents EVO_EXTENSIONS_BOOTSTRAP, MULTI_TENANT_ENABLED, DEFAULT_TENANT_ID in .env.example — the surface operators need to wire evo-enterprise-licensing-nestjs against an evo-flow deployment.
• Adds a comment on POSTGRES_DB_USERNAME flagging the NOBYPASSRLS-role requirement for multi-tenant deployments (evo_app, EVO-1620).
• Keeps the OSS default (postgres) intact so a fresh cp .env.example .env still works out of the box.

Why this PR is docs-only

NEST-3's other ACs (boot order, DataSource user swap, tenant_id on entities, migration run) were already covered by upstream work and don't need community changes:

AC	Status	Where
EVO_EXTENSIONS_BOOTSTRAP resolved before NestFactory.create	✅ already correct	src/main.ts:136 runs loadExternalExtensions() before NestFactory.create(...) on line 142
DataSource user swap to evo_app	✅ env-driven	src/database/ormconfig.ts reads POSTGRES_DB_USERNAME; only docs change required
tenant_id column carved into community entities	✅ unnecessary	Overlay migration 1763100000000-AddTenantIdDefaultFromGuc adds DEFAULT current_setting('app.current_tenant_id', true)::uuid server-side. RLS filters reads, GUC stamps writes — community entities stay tenant-unaware. (Also, only User extends a local abstract entity; the 15 other tenant-scoped entities declare columns directly, so a single BaseEntity edit wouldn't have propagated anyway.)
Migration 1763000000000-AddTenantIdAndRLSToAllEntities applies cleanly	✅ owned by overlay	Lives in @evoapi/enterprise-licensing-nestjs and is run via the overlay's own migration:run. evo-flow's data-source.ts doesn't need to know about it.

TenantStampSubscriber: dropped from scope

The original spec called for a TypeORM EntitySubscriberInterface global subscriber to stamp tenantId on beforeInsert. With migration 1763100000000-AddTenantIdDefaultFromGuc already merged, the Postgres DEFAULT carves the column server-side from the app.current_tenant_id GUC — making the subscriber dead code with the same failure mode (no GUC ⇒ NULL ⇒ RLS rejects ≡ no CLS ⇒ subscriber no-ops ⇒ RLS rejects). Kept the work cut.

Test plan

• cp .env.example .env still produces a runnable OSS config (POSTGRES_DB_USERNAME=postgres, EVO_EXTENSIONS_BOOTSTRAP= unset → no overlay attempted).
• When operator follows the new comments and sets EVO_EXTENSIONS_BOOTSTRAP=@evoapi/enterprise-licensing-nestjs + POSTGRES_DB_USERNAME=evo_app, the overlay's register() wires the real enricher and the connection respects RLS — covered end-to-end by SMOKE-1 (EVO-1633).

Linked issue

• EVO-1631

🤖 Generated with Claude Code

Summary by Sourcery

Document multi-tenant overlay environment variables and requirements in the example env file to support wiring the enterprise licensing overlay while keeping the default OSS setup unchanged.

Documentation:

• Describe EVO_EXTENSIONS_BOOTSTRAP, MULTI_TENANT_ENABLED, and DEFAULT_TENANT_ID usage for multi-tenant deployments in .env.example.
• Clarify POSTGRES_DB_USERNAME expectations for multi-tenant setups, including the requirement to use the NOBYPASSRLS database role while preserving the postgres default for OSS setups.

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Updates .env.example documentation to describe how to configure multi-tenant overlay environments while preserving the current OSS single-tenant defaults and behavior.

File-Level Changes

Change	Details	Files
Document multi-tenant overlay env vars and clarify Postgres username requirements while keeping OSS defaults working out of the box.	Add documentation for EVO_EXTENSIONS_BOOTSTRAP, MULTI_TENANT_ENABLED, and DEFAULT_TENANT_ID explaining how to wire the enterprise licensing overlay into an evo-flow deployment. Add or update a comment for POSTGRES_DB_USERNAME to call out that multi-tenant setups must use a role with NOBYPASSRLS (e.g., evo_app) while leaving postgres as the default value for OSS. Ensure that copying .env.example to .env continues to produce a runnable default configuration that does not attempt to load the overlay unless explicitly configured.	.env.example

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}