# 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. 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`.