capire · ecklie · Jul 10, 2026
@@ -316,7 +316,7 @@ In a first terminal, start the MTX sidecar process:
    [cds] - serving cds.xt.JobsService { path: '/-/cds/jobs' }
    ```
 
-   In addition, we can see a `t0` tenant being deployed, which is used by the MTX services for book-keeping tasks.
+   In addition, we can see a [`t0` tenant](#about-technical-tenant-t0) being deployed, which is used by the MTX services for book-keeping tasks.
 
    ```log
    [cds] - loaded model from 1 file(s):
@@ -894,7 +894,7 @@ To help ensure that the generated SAP HANA tenant UUID is unique within a region
 like `prefix-${org}-${space}` in Cloud Foundry.
 
 :::warning Prefix is mandatory
-The <Config label="hana_tenant_prefix" keyDelim="/" keyOnly>cds/requires/cds.xt.DeploymentService/hdi/create/hana_tenant_prefix</Config> configuration is mandatory to ensure that the internal tenant `t0` is created with its own SAP HANA tenant.
+The <Config label="hana_tenant_prefix" keyDelim="/" keyOnly>cds/requires/cds.xt.DeploymentService/hdi/create/hana_tenant_prefix</Config> configuration is mandatory to ensure that the internal tenant [`t0`](#about-technical-tenant-t0) is created with its own SAP HANA tenant.
 :::
 
 :::warning Length restriction
@@ -925,7 +925,7 @@ To group the tenant containers of many applications or microservices in a common
 **Option 2: Pass the SAP HANA Tenant ID with a Subscription**
 
 : **... in CAP Node.js**
-  
+
    If you want to control the ID of the SAP HANA tenant ID on your own, you can pass it as subscription payload as parameters, for example, using a handler for the [`SaasRegistryService`](./mtxs#put-tenant):
    ```jsonc
    {
@@ -943,22 +943,22 @@ To group the tenant containers of many applications or microservices in a common
    }
    ```
   The `hana_tenant_id` must be a valid UUID and must be unique per subscriber tenant. Specifying `hana_tenant_id` overrides    the prefix settings mentioned earlier,
-  except for the internal tenant `t0`. Also ensure that the ID is unique within a region.   
-  
+  except for [the internal tenant `t0`](#about-technical-tenant-t0). Also ensure that the ID is unique within a region.
+
 :  **... in CAP Java**
 
   To specify the ID of the SAP HANA tenant in **CAP Java** applications you can register a custom handler for the `before`    phase of the `SUBSCRIBE` event that sets the `hana_tenant_id` within the provisioning parameters:
-  
+
   ```java
   @Before
   public void beforeSubscription(SubscribeEventContext context) {
       context.getOptions().put("provisioningParameters",
           Collections.singletonMap("hana_tenant_id", "<ID>"));
   }
   ```
-  
+
   This will affect every new [tenant subscription](../../java/multitenancy.md#subscribe-tenant) and will set the specified SAP HANA tenant ID.
-  
+
 <div id="tmscmk" />
 
 
@@ -1276,3 +1276,50 @@ In these MTX sidecar setups, a subproject is added in _./mtx/sidecar_, which ser
 The main task for the MTX sidecar is to serve `subscribe` and `upgrade` requests.
 
 The CAP services runtime requests models from the sidecar only when you apply tenant-specific extensions. For Node.js projects, you have the option to run the MTX services embedded in the main app, instead of in a sidecar.
+
+## About technical Tenant `t0``
+
+`t0` is ta technical tenant used by `@sap/cds-mtxs`. It is a dedicated database container that stores operational metadata. The application's domain model is **not** deployed to `t0`.
+
+#### What `t0` stores
+
+| Entity | Purpose |
+|--------|---------|
+| `cds.xt.Tenants` | Registry of all subscribed tenants with their metadata, schema info, and version |
+| `cds.xt.Jobs` | Async job state for operations like subscribe, upgrade, extend |
+| `cds.xt.Tasks` | Individual tasks within a job (one per tenant per operation) |
+
+
+#### Lifecycle of `t0`
+
+The `t0` tenant is automatically created or updated at startup of the MTX Sidecar.
+
+##### Schema evolution
+
+Each startup checks if `t0` needs redeployment. If the schema is up-to-date, no action is taken.
+
+##### Special constraints for `t0`
+
+- Never uses `hana_tenant_id` from subscription parameters for [SAP HANA TMS v2](#sap-hana-tms-v2)
+- Never applies `dataEncryption`
+- Never applies the application's `cdsc` compiler options (always uses `assertIntegrity: false`)
+
+
+#### Configuring a different Tenant Name for `t0`
+
+The default tenant name is `'t0'`. It can be customized via configuration <Config label="cds.env.requires.multitenancy.t0" keyDelim="/">cds/requires/multitenancy/t0</Config> or environment variable `CDS_REQUIRES_MULTITENANCY_T0=my-custom-t0`.
+
+This is useful for scenarios where the t0 name must vary per deployment (e.g., when multiple apps share the same Service Manager instance and need distinct t0 containers).
+
+#### Default `database_id` and `lazyT0`
+
+By default, `t0` is created on server startup without an explicit `database_id`. This means it uses the Service Manager's default (primary) HANA database associated with the service instance or the database that is configured for the <Config label="DeploymentService" keyDelim="/" keyOnly>cds/requires/cds.xt.DeploymentService/hdi/create/database_id</Config>
+
+[Learn more about DeploymentService configuration.](./mtxs.md#deployment-config){.learn-more}
+
+##### `lazyT0` configuration
+
+The creation of the `t0` tenant can be deferred using configuration <Config label="lazyT0" keyDelim="/" keyOnly>cds/requires/cds.xt.DeploymentService/lazyT0</Config>.
+
+With that, the `t0` Tenant is only created together with the first subscription. Before the first tenant is subscribed, `t0` is created with the same onboarding parameters (including `database_id`) as the subscribing tenant. This can be useful if the `database_id` is not known when deploying the MTX Sidecar.
+