diff --git a/clientdocs/README.md b/clientdocs/README.md index 50a163e..3273470 100644 --- a/clientdocs/README.md +++ b/clientdocs/README.md @@ -1,8 +1,10 @@ # 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). Everything here is a DRAFT / -living document: accurate, but without final client polish. +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: diff --git a/clientdocs/acceptance-checklist.md b/clientdocs/acceptance-checklist.md index 35d8938..0dac88d 100644 --- a/clientdocs/acceptance-checklist.md +++ b/clientdocs/acceptance-checklist.md @@ -1,4 +1,4 @@ -# Omega Cloud -- Acceptance Checklist (DRAFT TEMPLATE) +# Omega Cloud -- Acceptance Checklist (TEMPLATE) TEMPLATE NOTE (removed before delivery): fields written as {{THIS}} are filled in by us per client at handover. @@ -13,7 +13,10 @@ Unless a row says otherwise, run the checks as your automation credential (`OS_CLOUD={{TENANT_SHORT_NAME}}`, per the CI/Automation Integration Guide). Substitute any small shared machine size and base image from `openstack -flavor list` / `openstack image list`. +flavor list` / `openstack image list`. The starter-kit script +`scripts/acceptance-run.sh` automates every fully self-service row below +(and tears its resources down again); the rows that need a password login +or a human are listed in its output. ## A. Sign-in and discovery @@ -24,13 +27,13 @@ | A3 | Admin account sign-in (password, dashboard) | log in to {{DASHBOARD_URL}} as `{{TENANT_SHORT_NAME}}-domain-admin` with domain `{{TENANT_SHORT_NAME}}` | dashboard opens in your domain | You | | A4 | Endpoint discovery | `openstack catalog list` | every service used in sections B-H appears with an endpoint | You | | A5 | Quota envelope visible | `openstack limits show --absolute` | limits match your agreed quota | You | -| A6 | Identity boundary (expected refusal) | with the application credential: `openstack user create ci-probe` | permission DENIED -- identity work belongs to `-domain-admin` only | You | +| A6 | Identity boundary (expected refusal) | with the application credential: `openstack user create ci-accept-probe` | permission DENIED -- identity work belongs to `-domain-admin` only | You | ## B. Identity self-service (as `{{TENANT_SHORT_NAME}}-domain-admin`) | # | Proves | Minimal check | Expected result | Who | |---|---|---|---|---| -| B1 | You can manage your own team | create user `ci-probe-user` in your domain, grant `member` on `{{TENANT_SHORT_NAME}}-prod`, then delete the user | create, grant, and delete all succeed | You | +| B1 | You can manage your own team | create user `ci-accept-user` in your domain, grant `member` on `{{TENANT_SHORT_NAME}}-prod`, then delete the user | create, grant, and delete all succeed | You | | B2 | Escalation is blocked (expected refusal) | try to grant `admin` on your project to any of your users | grant refused / does not appear in `openstack role assignment list` | You | ## C. Networking @@ -50,6 +53,13 @@ | D2 | Server lifecycle | boot `ci-accept-vm` on `{{TENANT_SHORT_NAME}}-net` with keypair `{{TENANT_SHORT_NAME}}-key`; wait; delete | status reaches ACTIVE; delete completes | You | | D3 | End-to-end reachability | attach a floating IP to `ci-accept-vm` and SSH in with your keypair (allow TCP/22 in its security group first) | SSH login succeeds | You | +Note on D2: keypairs are per-account and `{{TENANT_SHORT_NAME}}-key` is +owned by the `-cluster` account, so when running D2 as the automation +credential, boot with a keypair of your own instead -- the automated runner +`scripts/acceptance-run.sh` creates (and deletes) a throwaway +`ci-accept-key` for exactly this reason. Row H2 proves the handover keypair +itself. + ## E. Block storage | # | Proves | Minimal check | Expected result | Who | @@ -115,6 +125,6 @@ Leftover check: after sign-off, run `openstack server list`, `openstack volume list`, `openstack loadbalancer list`, `openstack floating ip list`, -and `openstack coe cluster list` -- nothing named `ci-accept-*` should -remain, and your quota consumption should be back to its pre-checklist -level. +`openstack network list`, `openstack security group list`, and `openstack +coe cluster list` -- nothing named `ci-accept-*` should remain, and your +quota consumption should be back to its pre-checklist level. diff --git a/clientdocs/ai-assistant-guide.md b/clientdocs/ai-assistant-guide.md index 67e6a5d..7272278 100644 --- a/clientdocs/ai-assistant-guide.md +++ b/clientdocs/ai-assistant-guide.md @@ -1,4 +1,4 @@ -# Omega Cloud -- Using Your AI Assistant Skill (DRAFT) +# Omega Cloud -- Using Your AI Assistant Skill With your handover pack you received `tenant-skill/`, a skill package for Claude (Anthropic's AI assistant). Installed into your own project, it diff --git a/clientdocs/ci-integration-guide.md b/clientdocs/ci-integration-guide.md index a7f61e3..78d1e46 100644 --- a/clientdocs/ci-integration-guide.md +++ b/clientdocs/ci-integration-guide.md @@ -1,4 +1,4 @@ -# Omega Cloud -- CI/Automation Integration Guide (DRAFT TEMPLATE) +# Omega Cloud -- CI/Automation Integration Guide (TEMPLATE) TEMPLATE NOTE (removed before delivery): fields written as {{THIS}} are filled in by us per client; fields marked "you fill" come from the credential files @@ -45,10 +45,11 @@ ## 3. clouds.yaml for pipelines -The OpenStack CLI and SDKs read `clouds.yaml`. A working template -- values -in angle brackets are yours to fill from the delivered credential file, and -the secret should be injected at job runtime, not written to disk in a -repository: +The OpenStack CLI and SDKs read `clouds.yaml`. A working template -- also +delivered ready to copy as `scripts/clouds.yaml.template` in your starter +kit -- values in angle brackets are yours to fill from the delivered +credential file, and the secret should be injected at job runtime, not +written to disk in a repository: clouds: {{TENANT_SHORT_NAME}}: @@ -66,7 +67,10 @@ export OS_CLOUD={{TENANT_SHORT_NAME}} openstack token issue -A token comes back scoped to your project; that is your smoke test. +A token comes back scoped to your project; that is your smoke test. The +starter-kit script `scripts/smoke-test.sh` wraps this (token, catalog, +quota) as one pipeline-ready step, and `scripts/Jenkinsfile.example` shows +a full Jenkins pipeline built this way. Equivalent environment-variable form (no clouds.yaml file needed): export OS_AUTH_TYPE=v3applicationcredential @@ -141,7 +145,9 @@ and make teardown a step that runs on failure too. A periodic sweep job that deletes resources older than your longest pipeline is the cheapest way to keep quota headroom. Floating IPs count against quota even when - detached -- release them. + detached -- release them. The starter-kit script + `scripts/ci-cleanup-sweep.sh` implements exactly this sweep (dry-run by + default; it deletes nothing without `--apply`). ## 7. The worked sequence your pipelines should exercise @@ -152,9 +158,9 @@ 1. **Authenticate + discover** -- `openstack token issue`, then `openstack catalog list`. Proves credential and endpoint discovery. -2. **Network build-out** -- create network, subnet (a range inside your - allocation that does not collide with `{{TENANT_SHORT_NAME}}-subnet`), - router with gateway to `provider-ext`, attach subnet. Or reuse the +2. **Network build-out** -- create network, subnet (any private range that + does not collide with `{{TENANT_SHORT_NAME}}-subnet` or your other + networks), router with gateway to `provider-ext`, attach subnet. Or reuse the handover network for simple runs. Proves networking self-service. 3. **Security group** -- create a group and rules for exactly the ports the deployment needs. Proves firewall self-service. @@ -178,8 +184,10 @@ commands that nothing is left. Proves your cleanup discipline and returns your quota. -Run the full sequence once at onboarding (that is the Acceptance Checklist) -and keep a trimmed version as your pipeline's recurring smoke test. +Run the full sequence once at onboarding (that is the Acceptance Checklist; +the starter-kit script `scripts/acceptance-run.sh` automates its +self-service rows) and keep a trimmed version as your pipeline's recurring +smoke test. ## 8. When a pipeline call fails diff --git a/clientdocs/handover-pack.md b/clientdocs/handover-pack.md index 96cae29..413f902 100644 --- a/clientdocs/handover-pack.md +++ b/clientdocs/handover-pack.md @@ -1,4 +1,4 @@ -# Omega Cloud -- Client Handover Pack (DRAFT TEMPLATE) +# Omega Cloud -- Client Handover Pack (TEMPLATE) TEMPLATE NOTE (removed before delivery): fields written as {{THIS}} are filled in by us for each client at handover. Everything else is standard. @@ -8,7 +8,8 @@ must be handled, and the small set of platform rules you are asked to acknowledge. Keep it with your operational documentation; the companions are the Welcome letter, the Self-Service Guide, the CI/Automation Integration -Guide, and the Acceptance Checklist. +Guide, the Acceptance Checklist, and the `scripts/` starter kit (plus, for +teams using an AI assistant, the AI assistant guide and its skill package). ## 1. Your identifiers diff --git a/clientdocs/intake-form.md b/clientdocs/intake-form.md index a671232..cbeac2b 100644 --- a/clientdocs/intake-form.md +++ b/clientdocs/intake-form.md @@ -1,6 +1,7 @@ -# Omega Cloud -- Client Intake Form (DRAFT) +# Omega Cloud -- Client Intake Form -Please complete every section and return it through your account contact. +Please complete every section and return it through your account contact +before onboarding begins. We use these answers to build your environment right the first time; missing answers are the most common cause of onboarding delay. diff --git a/clientdocs/self-service-guide.md b/clientdocs/self-service-guide.md index 22ce701..159fb23 100644 --- a/clientdocs/self-service-guide.md +++ b/clientdocs/self-service-guide.md @@ -1,7 +1,9 @@ -# Omega Cloud -- Self-Service Guide (DRAFT) +# Omega Cloud -- Self-Service Guide How to run your environment day to day. You can do everything here yourself, -through the web dashboard or the OpenStack command-line client. +through the web dashboard or the OpenStack command-line client. For a +read-only snapshot of everything described here, run the starter-kit script +`scripts/tenancy-audit.sh` delivered with your Handover Pack. ## Your three accounts, and what each is for @@ -37,7 +39,9 @@ ## Building your network (first-time order) -1. Network, then a subnet on it (use the address range from your intake form). +1. Network, then a subnet on it. Pick any private (RFC1918) range that does + not overlap your existing subnets (your handover range is recorded in + your Handover Pack) or any on-premises/VPN network you plan to connect. 2. Router; set its gateway to the shared external network (`provider-ext`). 3. Attach your subnet to the router. 4. Security groups: open only what you need (SSH from your ranges, your app diff --git a/clientdocs/sweep-receipt.txt b/clientdocs/sweep-receipt.txt index c470f00..15d3985 100644 --- a/clientdocs/sweep-receipt.txt +++ b/clientdocs/sweep-receipt.txt @@ -9,25 +9,25 @@ # Repo lint fails when any pinned file drifts, until clientdocs/ has been # reviewed for staleness and this receipt is re-recorded with: # bash scripts/repo-lint.sh --record-clientdocs-sweep -91860cb337bd8a807f73418ede2365425e8f73ea4704f64e25146d3f0acba244 clientdocs/README.md -d8595b7a1bb339af0a05ea547a814d63d906dc17e5a51609aa041bb56d637fd8 clientdocs/acceptance-checklist.md -c94cb2de99c84e0cc649ecef40a81860537c7209ae5a6bea339daedac0767a05 clientdocs/ai-assistant-guide.md -a7dcdd137fcf8f38fb32716a70c1d988c5365d379d6a450722e29fff99effb1c clientdocs/ci-integration-guide.md -5d3cc5597b550fdcadb3f084062479ddd4f1b22576a154c855bcb64f5cecc727 clientdocs/handover-pack.md -307967ca80a0daf168e295b3a4fba0ff71b08e208932070bdb83b81a0f4b0ef9 clientdocs/intake-form.md +b6bedcf304a571be8e5246b210537db3007b271476f694e26601f32812e4559f clientdocs/README.md +9db7eddf7a63dd1855639bbe6657f56d2064316bcc26a229dd43489a1a2c7e9d clientdocs/acceptance-checklist.md +30c46fd7644637c0a929bfdd195c451dff8cd0df6785cccf3a304a8422b82711 clientdocs/ai-assistant-guide.md +ae51da963d4d3704e6a1bd8613a243616ac22c0b973833b31f1bd22a40f3c66e clientdocs/ci-integration-guide.md +60c890b551e0a16d8d249fc809e2b561d44c6ec6121bf8a20f21e5fe6e2e9c60 clientdocs/handover-pack.md +3f08eb458bcbb36172a5ca2785a6ec72a69a4f8cd440fec53ed604f074b1b8c6 clientdocs/intake-form.md 96a077bb2e5732a0443683755bcefa044a603fe323024ca887165177e05c390b clientdocs/scripts/Jenkinsfile.example 4d63def4b32566507e5bc1da21670fcfe7622f0927d4886b179e17cbaac5690a clientdocs/scripts/acceptance-run.sh c2a2ff7ad719cb5866b1b58f5ca2cac930ccc99b96efaf8a3f12301d645727d3 clientdocs/scripts/ci-cleanup-sweep.sh d45eb3738d7fb2742ea1a3abb5af464df8a96bfd4e6c2f56b7182b42f997b289 clientdocs/scripts/clouds.yaml.template 3dd17ab9e95d99bea0c9f36a2662e77d25ea9d691f8c60d1d314f237c7c3f655 clientdocs/scripts/smoke-test.sh 7667bb1d2ff1e315f8ecaa2b4f680d04978a79ceeeb8cc3f5e16de2b295b2205 clientdocs/scripts/tenancy-audit.sh -c084b45c2dbe3d3430f0428b1aa55e4563787a88f59598938b024fdcd3f12a47 clientdocs/self-service-guide.md -e7dbe2aeb654463522cf1050470bf99a0a443f6c5813519fde63021da4c376bb clientdocs/tenant-skill/SKILL.md -6bd33aa16d0bfd140a7fd6d2efe2bf84b3a46c8f1bba7b33814a25554bf81063 clientdocs/tenant-skill/references/ci-automation.md -5858a30c2cd70e9c25f7f435271a04863e5a1ca257ff1e07a3b05021a80382cd clientdocs/tenant-skill/references/day2-operations.md +092dde4720e81aab0aa7e3fdc4f8523799bd5395f3964afa1022b343e068ebd3 clientdocs/self-service-guide.md +7644e527b6ce66804fa9e08315e51e06159a8feb525a8b7d1b8c9edf23e4a86a clientdocs/tenant-skill/SKILL.md +c7708c35d1d5fceab763268f6a10ed214e23e9458018b115cb944b6a3168f182 clientdocs/tenant-skill/references/ci-automation.md +a92e77ea77b572104831a39d83e85f2dfad10293f159f1930bb548e3f1cecee3 clientdocs/tenant-skill/references/day2-operations.md 69bd29f8c20d6a57cc5240e0fed6e8f5022683bf3ea687e74c761552993468a4 clientdocs/tenant-skill/references/kubernetes.md d1a01b19650efb0caf14a992590b7606da3ddf76820a613096a296c6a5e2fd6d clientdocs/tenant-skill/references/troubleshooting.md -488bda3e51ca1ddd6adb51bb317fccd5ee04731687fa7975e41a4043efe87adb clientdocs/welcome.md +2135f05ccdd411ce707bc6ec54c61040284259142b4b388c0c94cae5f6e7efcb clientdocs/welcome.md 04c0a08df9168448740514ae9763968eb7ea706cef58533c51c7448a5b0329c3 docs/tenant-onboarding-contract.md 64f99b638a1855b02180e907c9535db8bddc5847a502759a9e0d63c513b63077 policies/domain-manager-policy.yaml 02fe1fd7fcf07bfc6088622d4aa8430da53e435d60006d0b81f6b9c2e720a011 policies/overrides.zip diff --git a/clientdocs/tenant-skill/SKILL.md b/clientdocs/tenant-skill/SKILL.md index 97aa693..42f804f 100644 --- a/clientdocs/tenant-skill/SKILL.md +++ b/clientdocs/tenant-skill/SKILL.md @@ -136,8 +136,8 @@ ## Starter scripts (delivered with your document pack) -Your document pack includes a `scripts/` directory of READ-ONLY -helpers; run them with `bash` from wherever your team keeps the pack: +Your document pack includes a `scripts/` directory of helpers; run +them with `bash` from wherever your team keeps the pack: - `bash scripts/tenancy-audit.sh` -- full read-only snapshot of the tenancy plus the quota envelope. The recommended first command of @@ -153,7 +153,9 @@ checklist rows (self-service ones); also your recurring deep smoke test. -All three change nothing. If your copy of the pack does not include +The audit, the smoke test, and the sweep's default dry-run change +nothing; the acceptance run creates only `ci-accept-*` resources and +tears them down again. If your copy of the pack does not include them, the inline commands in the reference files cover the same ground. diff --git a/clientdocs/tenant-skill/references/ci-automation.md b/clientdocs/tenant-skill/references/ci-automation.md index 87bde0b..eabce61 100644 --- a/clientdocs/tenant-skill/references/ci-automation.md +++ b/clientdocs/tenant-skill/references/ci-automation.md @@ -79,9 +79,9 @@ 1. Authenticate + discover: `openstack token issue`, then `openstack catalog list`. -2. Network build-out: network, subnet (non-overlapping range), router - gatewayed to `provider-ext`, attach subnet -- or reuse the - handover network for simple runs. +2. Network build-out: network, subnet (any private range that does + not overlap your own subnets), router gatewayed to `provider-ext`, + attach subnet -- or reuse the handover network for simple runs. 3. Security group with exactly the ports the deployment needs. 4. Compute: boot a server from a shared base image with the keypair; wait for ACTIVE. diff --git a/clientdocs/tenant-skill/references/day2-operations.md b/clientdocs/tenant-skill/references/day2-operations.md index c740ff0..cca2405 100644 --- a/clientdocs/tenant-skill/references/day2-operations.md +++ b/clientdocs/tenant-skill/references/day2-operations.md @@ -29,10 +29,10 @@ ## Building a new network (first-time order matters) -1. Network, then a subnet on it. Choose a range inside your recorded - allocation (see your Handover Pack) that does NOT overlap - `{{TENANT_SHORT_NAME}}-subnet` or any on-premises/VPN range you may - later interconnect. +1. Network, then a subnet on it. Choose any private (RFC1918) range + that does NOT overlap `{{TENANT_SHORT_NAME}}-subnet` (recorded in + the Handover Pack), your other subnets, or any on-premises/VPN + range you may later interconnect. openstack network create -net openstack subnet create --network -net \ diff --git a/clientdocs/welcome.md b/clientdocs/welcome.md index 901a6db..c2e2fee 100644 --- a/clientdocs/welcome.md +++ b/clientdocs/welcome.md @@ -1,4 +1,4 @@ -# Welcome to Omega Cloud (DRAFT) +# Welcome to Omega Cloud You now have a private, isolated environment ("domain") on Omega Cloud. This document explains what we manage, what you manage, and how we work together. @@ -7,7 +7,7 @@ - Your **domain**: a hard isolation boundary. Nothing you create inside it is visible to any other client, and no other client's activity is visible to you. -- Your **administrator account** (`-domain-admin`): manages your +- Your **administrator account** (`-domain-admin`): manages your team's users and projects inside your domain. This account and its scope are described in the Self-Service Guide. - Two **workload accounts** (`-cluster` and `-svc`) preconfigured the way the @@ -42,6 +42,21 @@ - Incidents/outages: your account contact, marked urgent. - Everything else self-service: see the Self-Service Guide. +## Your document pack (read in this order) + +1. This welcome letter -- the split of responsibilities. +2. The Self-Service Guide -- how to run your environment day to day. +3. The Handover Pack -- your identifiers, accounts, endpoints, and the + platform rules you acknowledge. +4. The CI/Automation Integration Guide -- if you connect pipelines or + other automation. +5. The Acceptance Checklist -- run it once at onboarding to prove your + environment works. + +The pack also includes a `scripts/` starter kit (referenced throughout +the guides) and, if your team uses an AI assistant, an AI assistant +guide with its skill package. + ## House rules (the short version) 1. Never share account passwords between people; your administrator creates diff --git a/docs/session-ledger.md b/docs/session-ledger.md index d5998ec..500d62e 100644 --- a/docs/session-ledger.md +++ b/docs/session-ledger.md @@ -31,8 +31,8 @@ - **OPEN security rows:** SEC-001 (rotate at v1 close, re-ruled 2026-07-06), SEC-003 (custodians + second-person unseal -- DEFERRED; keeps d011-06 MANUAL), SEC-004 (flip repo to private at v1 close -- deferral reaffirmed). -- **Next-free numbers:** D = 075, DOCFIX = 110, BUNDLEFIX = 012. - (Scan and the addendum-30 changelog next-free pointer agree.) +- **Next-free numbers:** D = 075, DOCFIX = 111, BUNDLEFIX = 012. + (Scan and the addendum-31 changelog next-free pointer agree.) --- @@ -271,6 +271,12 @@ - **Open (small):** Horizon manual checks on foil1 (operator, browser, non-blocking); capi-test-1 CREATE_FAILED leftover (orphan-sweep candidate); beta-cluster lbtest leftover; repo-lint worktree-exclusion DOCFIX candidate. +- **CLIENT PACKAGE RELEASED (addendum 31, 2026-07-07):** operator-requested + polish sweep integrated (DOCFIX-110) + banner ruling applied (DRAFT + removed; the three per-client templates keep TEMPLATE; README says + RELEASED-for-handover). Package is handover-ready pending only per-client + instantiation. In flight: repo-wide script quality sweep (report-only + agent; findings to operator triage next). - **CLIENT PACKAGE COMPLETE (addendum 30):** starter kit (DOCFIX-108, 6 deliverables incl. tenancy-audit from the skill delivery; pipeline-smoke + leftover-check deduped away) + tenant AI skill omega-cloud-tenant diff --git a/docs/v1-redeploy-changelog.md b/docs/v1-redeploy-changelog.md index 64eef9d..2f60c5c 100644 --- a/docs/v1-redeploy-changelog.md +++ b/docs/v1-redeploy-changelog.md @@ -2553,3 +2553,32 @@ 10.100.0.0/24 fallback) with handover-pack instantiation. Next-free after this push (per scan, keep this line unwrapped): D-075, DOCFIX-110, BUNDLEFIX-012. + +### 2026-07-07 (addendum 31, jumphost stream) -- DOCFIX-110: clientdocs pre-handover polish + RELEASED banner ruling + +- **DOCFIX-110 -- clientdocs polish sweep (operator-requested) + banner + ruling.** Coherence pass over the complete client package (worktree + polish/clientdocs-sweep, integrated): reading-order section in welcome; + starter-kit scripts cross-referenced from the CI guide / checklist / + self-service guide / handover pack; CIDR wording in self-service guide, + CI guide, and skill references aligned with D-074 (tenant-chosen, + overlap-allowed); acceptance-checklist probe names aligned to ci-accept-* + and a D2 note recording the throwaway-keypair adaptation (script + unchanged); SKILL.md read-only claim corrected per-script; account-prefix + and audience-sentence consistency. Leakage scan across ALL clientdocs + files: zero hits. OPERATOR RULING (2026-07-07): DRAFT banners removed + from welcome/intake/self-service/ai-assistant-guide; the three + instantiated templates keep (TEMPLATE), drop DRAFT; README status line + updated to RELEASED-for-handover. Receipt re-recorded (29 files). + Verified-correct non-changes logged by the pass: -svc-appcred.txt + filename vs -svc-cred credential name is real (onboard stage 3); + Jenkinsfile client-side path placeholder deliberate. Gates: clientdocs + harnesses 8/8 + 47/47; gauntlet ALL GREEN (37); lint 0 fail / 1 legacy + warn. NOTE: the polish agent was killed mid-run by a session limit and + resumed; its original worktree had NOT survived (coordinator assumption + wrong -- flagged per divergence rule) but no edits were lost (pre-crash + it had only read); it re-based onto main and verified its reads against + HEAD before editing. REVERT: git checkout HEAD~ -- clientdocs/ then + bash scripts/repo-lint.sh --record-clientdocs-sweep. + +Next-free after this push (per scan, keep this line unwrapped): D-075, DOCFIX-111, BUNDLEFIX-012.