clientdocs workflow review + consolidation proposal (2026-07-08)

STATUS: PROPOSAL for operator ruling. Read-only analysis; nothing implemented. Options are presented per finding; the operator rules before any change. No identifier numbers are consumed here -- they are assigned at implementation.

Why this exists

Operator's stated problem (2026-07-08): the information a client needs is spread throughout the handover documentation with no clear flow. A client has to switch between multiple documents to accomplish one task, and some workflows have holes that cause errors (the flannel network-driver gap being the live example: a self-created flannel cluster never converges, and devteam lost a night to it). The goal for the client-facing set: an easy-to-follow, workflow-shaped path that makes finding and using their data simple, minimizes document-switching, and carries enough component detail that the client understands what each piece does.

DOCFIX-123 (the new jenkins-kubernetes-guide.md) is the first instance of the target shape -- a single self-contained workflow that cross-links to detail rather than scattering it. This review proposes applying the same principle across the rest of the set.

Method

Read-only inventory of all 20 client-facing files under clientdocs/ (the six top-level guides, the tenant-skill SKILL.md + four references, and the six starter-kit scripts), mapping every workflow topic to the file(s) that cover it, plus duplication, cross-file conflicts, and gaps. Evidence is file:line throughout the source inventory; the summary below carries representative cites.

The client journey (what a client actually does, in order)

Pre-onboarding homework (intake-form.md).
Receive credentials + first orientation (welcome.md, handover-pack.md).
Prove the tenancy works (acceptance-checklist.md).
Run day-to-day (self-service-guide.md; tenant-skill references).
Connect automation / CI (ci-integration-guide.md).
Stand up a Kubernetes + Jenkins workflow (jenkins-kubernetes-guide.md, new).

The docs exist for every stage, but stages 2-6 repeat each other's content and none of them states "you are here, read these in this order."

Findings

F1 -- Heavy duplication (maintenance-drift + reader confusion)

The same facts are authored independently in many files. Representative:

The three-account model table: 4 renderings (handover-pack.md:28-32, self-service-guide.md:10-14, tenant-skill/SKILL.md:32-36, and prose in welcome.md).
The clouds.yaml auth block: 3 byte-identical copies (ci-integration-guide.md, tenant-skill/SKILL.md, scripts/clouds.yaml.template).
"Cluster create cannot use an application credential": stated in 8 places.
The worked CI sequence: duplicated at length in ci-integration-guide.md and references/ci-automation.md.
Floating-IPs-count-when-detached: repeated in 5 files.
(Full list: 15 duplication clusters in the source inventory.)

Risk: any change (an endpoint, an account name, a rule) must be made in N places or the copies drift. It also makes each document longer than it needs to be, which is itself part of the "hard to follow" problem.

F2 -- No single entry point or reading order

No file tells the client which document to open first, or the order for a given goal. A client wanting "deploy my app to Kubernetes from Jenkins" previously had to assemble it from kubernetes.md + ci-integration-guide.md + day2-operations.md

troubleshooting.md. (DOCFIX-123 now owns that one journey; the other journeys still lack a spine.)

F3 -- Workflow holes that cause errors

Network-driver choice: the self-service path (self-service-guide.md:89-99) never mentioned calico, so a client building a template via the dashboard got no steer away from flannel. CLOSED 2026-07-08 in kubernetes.md + the Jenkins guide; self-service-guide.md still only carries the Public/Hidden rule, not the driver rule.
Right-sizing to host capacity: every doc presents quota as the only ceiling on node_count (self-service-guide.md:91, kubernetes.md:49, welcome.md, intake). None warned that an under-quota-but-oversized request fails with "No valid host" -- the exact failure devteam hit. CLOSED in the Jenkins guide; NOT yet in the general docs.

F4 -- Partial component detail / no glossary

Component terms (application credential, the -cluster account, cluster template, kubeconfig, LoadBalancer Service, floating IP, ingress) are defined inline where first used but there is no single glossary a client can consult. The operator specifically asked for "enough detail so they understand what all the components do." The Jenkins guide added a scoped glossary (section 10); the set has no shared one.

F5 -- Cross-file inconsistencies

Jenkinsfile.example calls scripts at clientdocs-starter-kit/... while the kit is delivered as scripts/ (README.md:27-33). The file admits paths need adjusting, but it is a stumble.
Jenkinsfile.example's "Worked sequence" stage runs an infrastructure smoke build, not an app deploy -- misleading under that name for a k8s reader.

Proposed information architecture

Principle: each fact has ONE owner; every other mention is a one-line pointer, not a copy. Each guide owns a JOURNEY (a workflow) and cross-links to the owners for reference detail. This is the shape DOCFIX-123 already demonstrates.

Proposed owners (single source of truth):

Identifiers, endpoints, CA bundle, the full account model: handover-pack.md (already the most complete; make it canonical).
clouds.yaml / OS_* auth setup: scripts/clouds.yaml.template (the delivery-ready copy) + one reference section; others point to it.
Day-2 resource operations (networks, servers, load balancers, secrets): references/day2-operations.md.
Troubleshooting signatures: references/troubleshooting.md (the single triage ladder; other docs link symptoms to it).
Journeys (own the flow, link the detail): welcome (orientation), self-service-guide (day-to-day), acceptance-checklist (proof), ci-integration-guide (automation), jenkins-kubernetes-guide (k8s+Jenkins).

Add:

A top-of-set "Start here / reading order" -- either a short new index doc or a section in welcome.md -- mapping goal -> ordered doc list.
A shared glossary -- a new small reference, or a section in handover-pack.md -- that every guide links to (retire the per-guide inline definitions in favor of one, keeping only a one-line gloss at first use + a link).

Consolidation moves (OPTIONS for operator ruling)

Each move is independent; rule per-move. Effort/risk are rough.

M1 -- De-duplicate the account model. Own it in handover-pack.md; replace the other 3 renderings with a 1-line summary + pointer. Options: (a) do it; (b) keep the self-service copy (first-read convenience) but retire the SKILL.md + welcome copies; (c) leave as-is. Effort: low. Risk: low. Recommend (b) -- one convenience copy, not four.
M2 -- De-duplicate clouds.yaml/auth. Own in clouds.yaml.template; the CI guide and SKILL.md point to it. Options: (a) do it; (b) leave. Effort: low. Risk: low. Recommend (a).
M3 -- Add a "Start here / reading order" entry point. Options: (a) new short index doc; (b) a section in welcome.md; (c) none. Effort: low. Risk: low. Recommend (b) -- no new file to package.
M4 -- Shared glossary. Options: (a) new reference file linked from all guides; (b) a section in handover-pack.md; (c) leave per-guide inline. Effort: medium (touches many files if links are added). Risk: low. Recommend (a).
M5 -- Close the remaining F3 holes in the general docs: add the driver rule and the host-capacity/right-size caveat to self-service-guide.md (and anywhere node_count is discussed). Options: (a) do it; (b) rely on the Jenkins guide + kubernetes.md only. Effort: low. Risk: low. Recommend (a) -- these are the error-causing holes the operator called out.
M6 -- Fix F5: correct Jenkinsfile.example's script paths to scripts/ and either rename or re-scope its misleading stage; consider adding a second Jenkinsfile.example for the kubeconfig-deploy pattern (or point at the Jenkins guide's inline pipeline). Effort: low-medium. Risk: low (starter asset). Recommend: fix paths now; the deploy-pipeline example already lives in the Jenkins guide, so just cross-link.
M7 -- Reconcile the quota-vs-capacity expectation cloud-side (separate from docs): the addendum-40 finding that testcloud tenant quotas over-promise schedulable capacity. Doc side is M5; the cloud side (trim quotas to reality) is an operator decision logged in addendum 40.

Recommended sequencing

M5 first (closes the active error-causing holes; low effort).
M3 + M1(b) (entry point + de-dup the worst offender; makes the set navigable).
M2, M6 (mechanical de-dup + the starter-asset fix).
M4 (glossary; larger touch, do once the owners above are settled).

Each move ships under the standard clientdocs discipline (ASCII/LF, no internal-term leakage, L7 receipt re-record, harness green, changelog + revert) and, where a delivered client already has the affected file, a package re-instantiation. Numbers are assigned at implementation, not here.

Not in this proposal

The broad rewrite into a single mega-document. The operator's goal is minimize doc-switching PER TASK, which the journey-owns-flow + cross-link model achieves without collapsing the set into one unnavigable file. If the operator prefers fewer, larger documents, that is a different architecture to rule on.
Any client-specific content. This is about the template set; per-client instantiation is unchanged.