CUST-WP-0058: T04 approved, T05 client-hub scoping, T06 fin-hub gap done

Service contract v0.1 accepted (Bernd 2026-07-10). Client-hub scoped as
core-hub extension (client/engagement/app_instance/support_state, CLNT-WP
skeleton). fin-hub gap assessment: 5 gaps, FIN-WP-0002 skeleton posted to
fin-hub lane (msg 9c8e8ed4); recommendation fin-hub stays reporting-only.
Remaining: T07 delivery-lane pilot, T08 closeout.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/client-hub-scoping.md

@@ -0,0 +1,83 @@
+# Client-Hub Scoping — the Client/Commercial Management Plane
+
+**Created:** 2026-07-10
+**Workplan:** `CUST-WP-0058-T05`
+**Decisions applied:** DR-1 C (instance-per-client, consolidation-aware),
+DR-2 B (Binky Hedgehog GmbH as client #1), DR-3 A (app-local identity)
+**Contract:** `canon/standards/business-app-service-contract_v0.1.md` (§7)
+
+## Why a fourth plane
+
+The hub ecosystem manages dev (state-hub), ops (ops-hub), and fin (fin-hub)
+concerns. Commercial operation of business apps adds concerns none of those
+own: who the clients are, what they are entitled to, which instances serve
+them, and what support/SLA state applies. Encoding any of this in the apps
+themselves is prohibited by the service contract (§7.2).
+
+## Shape decision: core-hub extension
+
+**Client-hub is a Core Hub extension (ops-hub pattern), not a standalone
+runtime.** Justification against the alternatives:
+
+- *Standalone service*: adds an operational surface (deploy, backup, monitor)
+  for what is initially a small registry; contradicts the "don't spawn a
+  runtime per aspect" guard from the hub-ecosystem review.
+- *fin-hub extension*: client identity is not a financial concern; billing
+  *references* clients but does not own them.
+- *state-hub tables*: state-hub is the internal dev plane and must stay out
+  of anything client-related (dev plane never in the client dependency graph).
+
+Core Hub is the production framework (`hub.coulomb.social`), already runs the
+ops-hub extension, and hub-core primitives (domains/repos/messages/progress
+router factories, JSON context seams) are available for reuse where they fit.
+
+## Entity model (v1)
+
+| Entity | Purpose | Key fields (sketch) |
+| --- | --- | --- |
+| `client` | Business client registry; **Binky Hedgehog GmbH is client #1** | name, legal form, contacts, status (prospect/active/offboarding/closed) |
+| `engagement` | Contract/entitlement envelope per client×app | client_id, app slug, entitlements (JSON), contract refs (pointer, no documents), start/end |
+| `app_instance` | Client↔instance mapping (1..n per client, DR-1) | client_id, engagement_id, app slug, environment ref (ops-hub), cost attribution key (fin-hub §5.1), consolidation state (dedicated/consolidated) |
+| `support_state` | SLA/support posture per engagement | tier, contacts, escalation path, open-issue pointer (issue-core) |
+
+Relations to other planes are **references, not ownership**: `app_instance`
+points at ops-hub environment/service records and carries the fin-hub cost
+key; documents/contracts stay in their own custody (no file storage here).
+
+## Boundaries (out of scope)
+
+- Payment, invoicing, dunning — fin-hub boundary question (T06)
+- Contract document storage or legal authority — human/Binky Hedgehog custody
+- Client *user* accounts — app-local per DR-3; client-hub tracks the client
+  organization, never its end users
+- Task/issue lifecycle — issue-core owns; support_state only points
+
+## Consolidation-awareness (DR-1 C)
+
+`app_instance.consolidation_state` plus the tenant key make the early
+cost-optimization move a data operation: consolidating N instances updates N
+rows (dedicated→consolidated onto shared infra) without model changes.
+Consolidation events must emit a signal that the DR-3 identity trigger can
+observe.
+
+## Proposed workplan skeleton (for `/home/worsch/core-hub` or a `client-hub` extension repo)
+
+```
+CLNT-WP-0001 — client-hub extension bootstrap
+  T01  Extension scaffold following ops-hub repo pattern (todo, high)
+  T02  client + engagement models, migrations, /api/v2 routes (todo, high)
+  T03  app_instance model with ops-hub env ref + fin-hub cost key (todo, high)
+  T04  support_state model + issue-core pointer (todo, medium)
+  T05  Seed client #1 (Binky Hedgehog GmbH) + vergabe-teilnahme pilot
+       engagement/instance rows (todo, medium)
+  T06  Operator console views (clients, engagements, instances) (todo, low)
+```
+
+Ownership question for Bernd at pickup: separate `client-hub` repo (like
+`ops-hub`) or a module inside `core-hub`? Recommendation: **separate repo**,
+consistent with the established extension pattern and repo-boundary rules.
+
+## Pickup
+
+Registered as an ecosystem todo when CUST-WP-0058-T08 closes; implementation
+does not start inside the-custodian (repo-boundary).