v6: namespace discoverability — friendly wrong-family errors + curated cf-level shortcuts

[Pandys]

Background

Users shouldn't need to memorise which API family (data/client/auth/notifier) an operation lives in. Flattening the whole surface onto cf was investigated and rejected: names are only unique at the gRPC-path level, not at the Python-attribute level a flattened cf.<name> would use.

Evidence from the generated code (54 services, 114 distinct method names):

• Method names collide heavily — create/delete/get/update/get_all each appear on ~18–19 services, so cf.create(...) can't resolve to one RPC.
• Service names collide three ways — general (all four families), process (client + data, different hosts, same 7 methods), version (auth + client, same 6 methods). A flattened cf.process would silently route to the wrong cluster host.

So the two-level cf.data.insert structure stays; this ticket delivers the ergonomics the flattening was reaching for, without the misrouting hazard. Design: §3.2 Why the family segment stays

Scope

1. Wrong-family / typo errors. Accessing a plausible-but-wrong attribute on cf (or on a family sub-client) raises a helpful error naming the correct home, e.g. cf.insert → "insert lives on cf.data, not on the client directly". Build a static name→family index from the generated API_FAMILIES at import time; no per-service hand maintenance.
2. Discoverability. dir(cf) lists the four families; the error text and __repr__ make the split obvious. Optionally a cf.help() / lookup that answers "which family has <service>?".
3. Curated top-level shortcuts. Hoist a small, hand-picked set of unambiguous high-traffic entry points onto cf (beyond the already-planned cf.collection() / cf.query() from §6). Candidates only where the name is globally unambiguous; everything else stays namespaced. List the chosen set in the PR for review — do not auto-hoist.

Acceptance criteria

• Accessing a known service/method name on the wrong object raises a ClappformError (or AttributeError subclass) naming the correct cf.<family>.<service> path
• The name→family index is derived from API_FAMILIES, not hand-maintained; colliding names (general, process, version) list all owning families in the hint rather than guessing one
• dir(cf) returns the four families plus any curated shortcuts
• Curated cf-level shortcuts are an explicit allowlist; ambiguous names are never hoisted
• Unit tests: wrong-family hint for a unique name, multi-family hint for a colliding name, dir() contents, each curated shortcut resolves to the same object as its namespaced path
• Docs note: the two-level structure is intentional; shortcuts are conveniences, not the canonical path

Notes

• Depends on the client core (v6: Clappform client class — constructor, sub-client wiring, lifecycle #39) being merged (PR feat: client core — transport, auth, errors, and the Clappform class #55).
• Keep it additive: the namespaced cf.data.insert... path remains the canonical, documented form; nothing here removes or renames it.