docs: update CLAUDE.md and HOWTO.md for all session changes

- Certificate management (provider interface, lifecycle, bootstrap, UI)
- Async tenant provisioning with polling UX
- Server restart capability (vendor + tenant)
- Audit log actor name resolution from Logto
- SSO connector management, vendor audit page
- Updated API reference with all current endpoints
- Fixed architecture table (per-tenant containers are dynamic)
- Updated migration list through V012

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -33,17 +33,27 @@ Agent-server protocol is defined in `cameleer3/cameleer3-common/PROTOCOL.md`. Th
 - `TenantEntity.java` — JPA entity (id, name, slug, tier, status, logto_org_id, stripe IDs, settings JSONB)
 
 **vendor/** — Vendor console (platform:admin only)
-- `VendorTenantService.java` — orchestrates tenant creation: DB record -> Logto org -> admin user -> license -> Docker provisioning -> OIDC config push -> redirect URI registration
+- `VendorTenantService.java` — orchestrates tenant creation (sync: DB + Logto + license, async: Docker provisioning + config push), suspend/activate, delete, restart server, license renewal
 - `VendorTenantController.java` — REST at `/api/vendor/tenants` (platform:admin required)
 
 **portal/** — Tenant admin portal (org-scoped)
-- `TenantPortalService.java` — customer-facing: dashboard (health from server), license, OIDC config, team, settings
+- `TenantPortalService.java` — customer-facing: dashboard (health from server), license, SSO connectors, team, settings, server restart
 - `TenantPortalController.java` — REST at `/api/tenant/*` (org-scoped)
 
 **provisioning/** — Pluggable tenant provisioning
 - `TenantProvisioner.java` — pluggable interface (like server's RuntimeOrchestrator)
 - `DockerTenantProvisioner.java` — Docker implementation, creates per-tenant server + UI containers
 - `TenantProvisionerAutoConfig.java` — auto-detects Docker socket
+- `DockerCertificateManager.java` — file-based cert management with atomic `.wip` swap (Docker volume)
+- `DisabledCertificateManager.java` — no-op when certs dir unavailable
+- `CertificateManagerAutoConfig.java` — auto-detects `/certs` directory
+
+**certificate/** — TLS certificate lifecycle management
+- `CertificateManager.java` — provider interface (Docker now, K8s later)
+- `CertificateService.java` — orchestrates stage/activate/restore/discard, DB metadata, tenant CA staleness
+- `CertificateController.java` — REST at `/api/vendor/certificates` (platform:admin required)
+- `CertificateEntity.java` — JPA entity (status: ACTIVE/STAGED/ARCHIVED, subject, fingerprint, etc.)
+- `CertificateStartupListener.java` — seeds DB from filesystem on boot (for bootstrap-generated certs)
 
 **license/** — License management
 - `LicenseEntity.java` — JPA entity (id, tenant_id, tier, features JSONB, limits JSONB, expires_at)
@@ -52,26 +62,26 @@ Agent-server protocol is defined in `cameleer3/cameleer3-common/PROTOCOL.md`. Th
 
 **identity/** — Logto & server integration
 - `LogtoConfig.java` — Logto endpoint, M2M credentials (reads from bootstrap file)
-- `LogtoManagementClient.java` — Logto Management API calls (create org, create user, add to org)
+- `LogtoManagementClient.java` — Logto Management API calls (create org, create user, add to org, get user, SSO connectors, JIT provisioning)
 - `ServerApiClient.java` — M2M client for cameleer3-server API (Logto M2M token, `X-Cameleer-Protocol-Version: 1` header)
 
 **audit/** — Audit logging
-- `AuditEntity.java` — JPA entity (actor_id, tenant_id, action, resource, status)
-- `AuditService.java` — log audit events (TENANT_CREATE, TENANT_UPDATE, etc.)
+- `AuditEntity.java` — JPA entity (actor_id, actor_email, tenant_id, action, resource, status)
+- `AuditService.java` — log audit events (TENANT_CREATE, TENANT_UPDATE, etc.); auto-resolves actor name from Logto when actorEmail is null (cached in-memory)
 
 ### React Frontend (`ui/src/`)
 
 - `main.tsx` — React 19 root
 - `router.tsx` — `/vendor/*` + `/tenant/*` with `RequireScope` guards and `LandingRedirect` that waits for scopes
-- `Layout.tsx` — persona-aware sidebar: vendor sees expandable "Vendor" section (Tenants + Logto link), tenant admin sees Dashboard/License/OIDC/Team/Settings
+- `Layout.tsx` — persona-aware sidebar: vendor sees expandable "Vendor" section (Tenants, Audit Log, Certificates, Identity/Logto), tenant admin sees Dashboard/License/SSO/Team/Audit/Settings
 - `OrgResolver.tsx` — merges global + org-scoped token scopes (vendor's platform:admin is global)
 - `config.ts` — fetch Logto config from /platform/api/config
 - `auth/useAuth.ts` — auth hook (isAuthenticated, logout, signIn)
 - `auth/useOrganization.ts` — Zustand store for current tenant
 - `auth/useScopes.ts` — decode JWT scopes, hasScope()
 - `auth/ProtectedRoute.tsx` — guard (redirects to /login)
-- **Vendor pages**: `VendorTenantsPage.tsx`, `CreateTenantPage.tsx`, `TenantDetailPage.tsx`
-- **Tenant pages**: `TenantDashboardPage.tsx`, `TenantLicensePage.tsx`, `OidcConfigPage.tsx`, `TeamPage.tsx`, `SettingsPage.tsx`
+- **Vendor pages**: `VendorTenantsPage.tsx`, `CreateTenantPage.tsx`, `TenantDetailPage.tsx`, `VendorAuditPage.tsx`, `CertificatesPage.tsx`
+- **Tenant pages**: `TenantDashboardPage.tsx`, `TenantLicensePage.tsx`, `SsoPage.tsx`, `TeamPage.tsx`, `TenantAuditPage.tsx`, `SettingsPage.tsx`
 
 ### Custom Sign-in UI (`ui/sign-in/src/`)
 
@@ -97,7 +107,7 @@ All services on one hostname. Two env vars control everything: `PUBLIC_HOST` + `
 
 - SPA assets at `/_app/` (Vite `assetsDir: '_app'`) to avoid conflict with Logto's `/assets/`
 - Logto `ENDPOINT` = `${PUBLIC_PROTOCOL}://${PUBLIC_HOST}` (same domain, same origin)
-- TLS: self-signed cert init container (`traefik-certs`) for dev, ACME for production
+- TLS: `traefik-certs` init container generates self-signed cert (dev) or copies user-supplied cert via `CERT_FILE`/`KEY_FILE`/`CA_FILE` env vars. Runtime cert replacement via vendor UI (stage/activate/restore). ACME for production (future).
 - Root `/` -> `/platform/` redirect via Traefik file provider (`docker/traefik-dynamic.yml`)
 - LoginPage auto-redirects to Logto OIDC (no intermediate button)
 - Per-tenant server containers get Traefik labels for `/t/{slug}/*` routing at provisioning time
@@ -163,7 +173,7 @@ These env vars are injected into provisioned per-tenant server containers:
 |---------|-------|---------|
 | `CAMELEER_OIDC_ISSUER_URI` | `${PUBLIC_PROTOCOL}://${PUBLIC_HOST}/oidc` | Token issuer claim validation |
 | `CAMELEER_OIDC_JWK_SET_URI` | `http://logto:3001/oidc/jwks` | Docker-internal JWK fetch |
-| `CAMELEER_OIDC_TLS_SKIP_VERIFY` | `true` | Skip cert verify for OIDC discovery (dev only) |
+| `CAMELEER_OIDC_TLS_SKIP_VERIFY` | `true` (conditional) | Skip cert verify for OIDC discovery; only set when no `/certs/ca.pem` exists |
 | `CAMELEER_CORS_ALLOWED_ORIGINS` | `${PUBLIC_PROTOCOL}://${PUBLIC_HOST}` | Allow browser requests through Traefik |
 | `CAMELEER_RUNTIME_ENABLED` | `true` | Enable Docker orchestration |
 | `CAMELEER_SERVER_URL` | `http://cameleer3-server-{slug}:8081` | Per-tenant server URL (DNS alias on tenant network) |
@@ -181,6 +191,7 @@ These env vars are injected into provisioned per-tenant server containers:
 |-------|---------------|---------|
 | `/var/run/docker.sock` | `/var/run/docker.sock` | Docker socket for app deployment orchestration |
 | `cameleer-jars-{slug}` (volume) | `/data/jars` | Shared JAR storage — server writes, deployed app containers read |
+| `cameleer-saas_certs` (volume, ro) | `/certs` | Platform TLS certs + CA bundle for OIDC trust |
 
 ### Server OIDC role extraction (two paths)
 
@@ -228,23 +239,32 @@ Idempotent script run via `logto-bootstrap` init container. **Clean slate** —
 
 12. (Optional) Vendor seed: create `saas-vendor` global role, vendor user, grant Logto console access (`VENDOR_SEED_ENABLED=true` in dev).
 
-The compose stack is: Traefik + PostgreSQL + ClickHouse + Logto + logto-bootstrap + cameleer-saas. The compose stack is: Traefik + PostgreSQL + ClickHouse + Logto + logto-bootstrap + cameleer-saas. No `cameleer3-server` or `cameleer3-server-ui` in compose — those are provisioned per-tenant by `DockerTenantProvisioner`.
+The compose stack is: Traefik + traefik-certs (init) + PostgreSQL + ClickHouse + Logto + logto-bootstrap (init) + cameleer-saas. No `cameleer3-server` or `cameleer3-server-ui` in compose — those are provisioned per-tenant by `DockerTenantProvisioner`.
 
 ### Tenant Provisioning Flow
 
 When vendor creates a tenant via `VendorTenantService`:
+
+**Synchronous (in `createAndProvision`):**
 1. Create `TenantEntity` (status=PROVISIONING) + Logto organization
 2. Create admin user in Logto with owner org role
 3. Add vendor user to new org for support access
 4. Register OIDC redirect URIs for `/t/{slug}/oidc/callback` on Logto Traditional Web App
 5. Generate license (tier-appropriate, 365 days)
-6. Create tenant-isolated Docker network (`cameleer-tenant-{slug}`)
-7. Create server container with env vars, Traefik labels (`traefik.docker.network`), health check, Docker socket bind, JAR volume (`cameleer-jars-{slug}:/data/jars`)
-8. Create UI container with `CAMELEER_API_URL`, `BASE_PATH`, Traefik strip-prefix labels
-9. Wait for health check (`/api/v1/health`, not `/actuator/health` which requires auth)
-10. Push license token to server via M2M API
-11. Push OIDC config (Traditional Web App credentials + `additionalScopes: [urn:logto:scope:organizations, urn:logto:scope:organization_roles]`) to server for SSO
-11. Update tenant status -> ACTIVE
+6. Return immediately — UI shows provisioning spinner, polls via `refetchInterval`
+
+**Asynchronous (in `provisionAsync`, `@Async`):**
+7. Create tenant-isolated Docker network (`cameleer-tenant-{slug}`)
+8. Create server container with env vars, Traefik labels (`traefik.docker.network`), health check, Docker socket bind, JAR volume, certs volume (ro)
+9. Create UI container with `CAMELEER_API_URL`, `BASE_PATH`, Traefik strip-prefix labels
+10. Wait for health check (`/api/v1/health`, not `/actuator/health` which requires auth)
+11. Push license token to server via M2M API
+12. Push OIDC config (Traditional Web App credentials + `additionalScopes: [urn:logto:scope:organizations, urn:logto:scope:organization_roles]`) to server for SSO
+13. Update tenant status -> ACTIVE (or set `provisionError` on failure)
+
+**Server restart** (available to vendor + tenant admin):
+- `POST /api/vendor/tenants/{id}/restart` (vendor) and `POST /api/tenant/server/restart` (tenant)
+- Calls `TenantProvisioner.stop(slug)` then `start(slug)` — restarts server + UI containers only
 
 ## Database Migrations
 
@@ -258,6 +278,8 @@ PostgreSQL (Flyway): `src/main/resources/db/migration/`
 - V007 — audit_log
 - V008 — app resource limits
 - V010 — cleanup of migrated tables
+- V011 — add provisioning fields (server_endpoint, provision_error)
+- V012 — certificates table + tenants.ca_applied_at
 
 ## Related Conventions
 
@@ -280,7 +302,7 @@ PostgreSQL (Flyway): `src/main/resources/db/migration/`
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **cameleer-saas** (1976 symbols, 3805 relationships, 165 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **cameleer-saas** (2057 symbols, 4069 relationships, 172 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.