clientdocs/ -- client-facing document package (INTERNAL README)

This directory holds everything we hand to a client, separated from internal docs/runbooks by operator ruling (2026-07-06). RELEASED for handover as of 2026-07-07 (polish sweep + banner ruling): living documents, kept accurate by the sweep-on-change rule below; the three (TEMPLATE) docs are instantiated per client.

Rules for this directory:

• No internal identifiers. Decision numbers, fix numbers, ticket ids, internal hostnames/IPs, and runbook names never appear in client documents. (This also keeps these files out of the internal numbering scans.)
• Client language. Second person, no charm/Juju/deployment internals. Internal mechanics live in docs/tenant-onboarding-contract.md, which is the authoritative source these documents are derived from -- when the contract changes, sweep this directory.
• Packaging. A client receives a copy (or export) of the relevant files, never a repo link. Which file goes when:
  • intake-form.md -- BEFORE onboarding (their homework).
  • welcome.md + self-service-guide.md -- AT credential handoff.
  • handover-pack.md + acceptance-checklist.md -- AT credential handoff, instantiated per client (fill every {{PLACEHOLDER}}, remove the TEMPLATE NOTE banner).
  • ci-integration-guide.md -- with the handover pack for any client that connects CI/automation (Jenkins etc.); same instantiation rule.
  • scripts/ (the tenant starter kit) -- WITH the handover pack: tenancy-audit.sh, smoke-test.sh, acceptance-run.sh, and ci-cleanup-sweep.sh go to every client; clouds.yaml.template and Jenkinsfile.example go only to clients that connect CI/automation (with the CI guide). The .sh files are generic (auth via the client's own OS_* environment, nothing to instantiate); clouds.yaml.template follows the {{PLACEHOLDER}} instantiation rule below.
  • tenant-skill/ + ai-assistant-guide.md -- AT handover, with the pack, for any client whose team uses an AI assistant (Claude Code / claude.ai). tenant-skill/ is a Claude Agent Skill (SKILL.md + references/): instantiate every {{PLACEHOLDER}} across all its files, remove the TEMPLATE NOTE banner, deliver the directory as a copy. ai-assistant-guide.md is the client-facing install/usage page for it (no placeholders). Install on the client side: copy the directory into their project as .claude/skills/omega-cloud-tenant/ (Claude Code), or add the files to their claude.ai project; the installed directory name must match the skill name omega-cloud-tenant. The skill's routing table references the starter-kit scripts by name; keep them in sync.
• Templates. handover-pack.md, ci-integration-guide.md, acceptance-checklist.md, scripts/clouds.yaml.template, and every file under tenant-skill/ are reusable templates: {{PLACEHOLDER}} fields are operator-filled at instantiation; a delivered copy contains none. Instantiation values: {{DASHBOARD_URL}} is the FULL client-facing URL INCLUDING the webroot path (measure juju config openstack-dashboard webroot; a bare VIP root does not reach the dashboard); {{AUTH_URL}} and {{REGION}} are measured from the live catalog at instantiation, never recalled. The tenant-skill placeholder set is exactly: {{TENANT_SHORT_NAME}}, {{AUTH_URL}}, {{DASHBOARD_URL}}, {{REGION}}, {{ACCOUNT_CONTACT}} -- enforced by tests/clientdocs-skill/run-tests.sh, which also gates internal-term leakage and routing-table reachability for the skill.
• ASCII + LF, like everything committed.
• Sweep-on-change is enforced. sweep-receipt.txt (INTERNAL, never shipped) pins the reviewed state of every tenant-facing file (including everything under scripts/, which is auto-covered like the *.md files); repo lint fails when any of them drifts, until this directory has been reviewed for staleness and the receipt is re-recorded: bash scripts/repo-lint.sh --record-clientdocs-sweep.
• Starter-kit scripts are tested offline. Any change to scripts/*.sh ships with tests/clientdocs-scripts/run-tests.sh green (mock CLI, no cloud access).

Contents: intake-form.md, welcome.md, self-service-guide.md, handover-pack.md, ci-integration-guide.md, acceptance-checklist.md, ai-assistant-guide.md, tenant-skill/ (SKILL.md + references/), scripts/ (starter kit: tenancy-audit.sh, smoke-test.sh, acceptance-run.sh, ci-cleanup-sweep.sh, clouds.yaml.template, Jenkinsfile.example); internal-only: sweep-receipt.txt.