docs(tenants): document namespace layout and parent/child derivation (#479)

## What

Adds two new sections to the Tenant System guide
(`/docs/v1/guides/tenants/`) that document how tenant workload namespace
names are constructed and how downstream integrations should walk the
tenant tree without string-parsing namespace names.

## Why

Tenant workload namespaces follow two different rules depending on
depth: tenants created directly under `tenant-root` get a flat name
(`tenant-alpha`), while tenants created at any deeper level get a
hierarchical name (`tenant-alpha-beta`, `tenant-alpha-beta-gamma`). This
split is not documented anywhere in `content/en/docs/v1/`, so anyone
building dashboards, audit tooling, cost-allocation jobs, or policy
engines on top of Cozystack has to infer it from the chart templates.
The natural first attempt — `strings.Split(namespace, "-")` to derive a
parent — is wrong for one of the two cases regardless of which heuristic
you pick, and integrations that try it run into silent breakage on
root-level or deep-level tenants.

The new material:

- **Tenant Namespace Layout** — states the two rules plainly, shows a
four-row lookup table from `root` down to `root/alpha/beta/gamma`, and
links to the two source-of-truth files
(`packages/apps/tenant/templates/_helpers.tpl` and
`pkg/registry/apps/application/rest.go::computeTenantNamespace`) so a
reader can audit the claim against the implementation.
- **Deriving Parent and Child Relationships** — explains why
string-parsing the namespace is unreliable and documents the `Tenant` CR
fields that should be used instead: `metadata.namespace` always equals
the parent's workload namespace, `status.namespace` equals the tenant's
own workload namespace, and listing children of a tenant with workload
namespace `N` is `list Tenants where metadata.namespace == N`. This
pattern is stable regardless of whether the tenant is a direct child of
`tenant-root` or a deeper descendant.

No existing content is moved or rewritten; the sections are inserted
between *Tenant Naming Limitations* and *Reference*, where readers
looking for naming details will naturally land.

## Verification

- `hugo` builds cleanly; the tenants guide renders with both new
sections.
- Table entries cross-checked against
`packages/apps/tenant/templates/_helpers.tpl::tenant.name` in the
current cozystack tree (the helper fails the Helm release if the tenant
name itself contains a dash, which is why the "namespace fragments never
contain tenant-internal dashes" note is accurate).
- The "`metadata.namespace` equals the parent's workload namespace"
claim matches Kubernetes semantics — `Tenant` CRs are namespace-scoped
and stored in the parent's workload namespace by construction.
- The aggregated API code path
(`pkg/registry/apps/application/rest.go::computeTenantNamespace`)
implements the same flat/hierarchical split, so `status.namespace` on a
`Tenant` CR is a reliable mirror of the workload namespace.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Added a tenant namespace layout describing deterministic derivation
with an example table
* Guidance for integrations on determining parent vs tenant workload
namespaces, plus a kubectl example
* Documented RFC‑1123 naming constraints, a 63‑character limit for
deeper names, and the failure mode when derivation is rejected
  * Minor formatting and cleanup for clarity
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: lexfrei

content/en/docs/v1.2/guides/tenants/_index.md

@@ -97,6 +97,91 @@ For example:
 -   A user tenant is named `foo`, which results in `tenant-foo`.
 -   However, a tenant cannot be named `foo-bar`, because parsing names like `tenant-foo-bar` can be ambiguous.
 
+### Tenant Namespace Layout
+
+Each tenant corresponds to a Kubernetes workload namespace. The `root`
+tenant is a special case: its namespace is hardcoded to `tenant-root`.
+For every nested tenant, the namespace is derived from its parent's
+workload namespace and its own name using two rules:
+
+- A tenant created directly inside `tenant-root` gets the namespace
+  `tenant-<name>`. The parent's `tenant-root-` prefix is **not** included.
+- A tenant created at any deeper level gets the namespace
+  `<parent-workload-namespace>-<name>`, appending the child's name to the
+  parent's full namespace.
+
+For example, starting from `tenant-root`:
+
+| Tenant path             | Workload namespace         |
+| ---                     | ---                        |
+| `root`                  | `tenant-root`              |
+| `root/alpha`            | `tenant-alpha`             |
+| `root/alpha/beta`       | `tenant-alpha-beta`        |
+| `root/alpha/beta/gamma` | `tenant-alpha-beta-gamma`  |
+
+Both the `tenant` Helm chart and the aggregated API implement these rules
+when a new tenant is created:
+
+- the Helm chart helper in
+  [`packages/apps/tenant/templates/_helpers.tpl`](https://github.com/cozystack/cozystack/blob/main/packages/apps/tenant/templates/_helpers.tpl)
+  computes the namespace for the child release being installed,
+- the `computeTenantNamespace` function in
+  [`pkg/registry/apps/application/rest.go`](https://github.com/cozystack/cozystack/blob/main/pkg/registry/apps/application/rest.go)
+  publishes the same value as `status.namespace` on the `Tenant` CR.
+
+Because tenant names themselves are constrained to be alphanumeric (see
+*Tenant Naming Limitations* above), namespace fragments never contain
+tenant-internal dashes.
+
+{{% alert color="warning" %}}
+Kubernetes namespace names are RFC 1123 labels and cannot exceed **63
+characters**. Because deeper tenants accumulate the full ancestor chain
+into their workload namespace name (`tenant-alpha-beta-gamma`), long tenant
+names combined with deep nesting can bump into this limit. Plan the
+hierarchy accordingly: short tenant names at deeper levels, or shallower
+trees when long names are unavoidable. Kubernetes will reject the namespace
+creation if the computed name exceeds 63 characters, and the containing
+`tenant` Helm release will surface that rejection as a reconcile failure.
+{{% /alert %}}
+
+### Deriving Parent and Child Relationships
+
+Downstream integrations — custom dashboards, audit tooling, cost-allocation
+jobs, policy engines — sometimes need to walk the tenant tree to render
+breadcrumbs, compute inherited settings, or scope queries. A tempting
+shortcut is to derive the parent namespace by splitting the workload
+namespace on `-` and rebuilding it minus the last segment. That works
+today only because tenant names are constrained to be alphanumeric, so
+the `-` character unambiguously separates ancestor segments; it also
+assumes the current namespace-generation rules never change. Both
+assumptions are implementation details, not a stable contract.
+
+The stable contract is the `Tenant` custom resource itself. Cozystack
+stores every `Tenant` CR in its parent's workload namespace, so:
+
+- **`metadata.namespace`** of a `Tenant` CR equals the **parent's** workload
+  namespace. This is the reliable pointer to the parent — no string parsing
+  required.
+- **`status.namespace`** of a `Tenant` CR equals the tenant's **own** workload
+  namespace (the one where the tenant's applications, nested tenants, and
+  `HelmRelease`s live).
+- To list the direct children of a tenant with workload namespace `N`, list
+  `Tenant` CRs whose `metadata.namespace == N`. With `kubectl`, this is a
+  single command against the parent's workload namespace:
+
+  ```bash
+  kubectl get tenants --namespace <parent-workload-namespace>
+  ```
+
+  The `tenants` resource is served by the Cozystack aggregated API
+  (`apps.cozystack.io/v1alpha1`), so `cozystack-api` must be running and
+  reachable from the client. Run `kubectl api-resources --api-group apps.cozystack.io`
+  to confirm the resource is visible from your kubeconfig context.
+
+This approach is stable regardless of whether the tenant is a direct child of
+`tenant-root` or a deeper descendant, and it survives any future adjustments
+to the namespace layout because it does not depend on the layout at all.
+
 
 ### Reference