@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/templates/business-service/config/biz-docs-lint.tree.json

@@ -0,0 +1,10 @@
+{
+  "_note": "Tree-bound overlay for linting api_biz/__SERVICE_NAME__/docs with api/scripts/ci/lint-biz-docs.mjs. Run from api/: node scripts/ci/lint-biz-docs.mjs --root ../api_biz/__SERVICE_NAME__/docs --tree-config ../api_biz/__SERVICE_NAME__/config/biz-docs-lint.tree.json --skip-code-rules --format text. Only the tree-bound keys belong here; every other rule is a platform rule inherited from api/config/biz-docs-lint.json. Manifest row C-LINT requires the file: without it the lint refuses to run over the tree, and a tree nothing lints is a tree nothing checks.",
+  "canonical_facts": [],
+  "_canonical_facts_note": "Empty on purpose, and it stays empty until this service owns a cross-cutting fact of its own. canonical_facts names the node that OWNS such a fact; everything a new service says is owned by the platform tree api/docs/biz/** and this tree only links to it.",
+  "default_max_words": 3687,
+  "_default_max_words_note": "The platform per-node norm (api/config/biz-docs-lint.json). A service tree does not get a laxer node cap than the platform tree it hangs off.",
+  "tree_max_words": 4000,
+  "_tree_max_words_note": "The scaffolded tree measures 1666 words in five nodes (INSTALL 544, VALIDATION 524, PLATFORM_MATRIX 412, 80-setup/README 94, README 92), counted with node api/scripts/ci/lib/countWords.js on 2026-09-14 \u2014 the two maps joined with D-LINT, which reports the orphan nodes a tree without them leaves behind. The budget is deliberately larger than that measurement, because a new service writes its own nodes into an otherwise empty tree; RAISE IT WITH A MEASUREMENT once the tree is real, the way api_biz/converter and api_biz/pdfgen state theirs, and never to make a failing run pass.",
+  "max_words_overrides": {}
+}

package/templates/business-service/config/env-templates/__SERVICE_NAME__.env

@@ -0,0 +1,22 @@
+# __SERVICE_NAME__ environment
+# Copy to config/env-active/__SERVICE_NAME__.env and adjust values.
+
+SERVICE_NAME=__SERVICE_NAME__
+
+# Schema migrations at deploy time. The deploy job (block `oa-ci v1` of
+# .gitlab-ci.yml) runs api/scripts/lib/mariadb-migrations.sh between `compose
+# pull` and `compose up`, and that runner REQUIRES both names - fail-fast, no
+# default value (owner decision
+# api/docs/governance/confirmations/db-migrations-first-deploy.md 001, phase 2).
+# The account is the SAME one DB_USER names: its grants cover this service's
+# schema and nothing else, so a migration that reached into a neighbouring
+# database is refused by the server instead of quietly applied
+# (db-accounts-per-service 001). Pattern: api/config/env-templates/auth.env.
+#
+# Commented out because this scaffold has no database: its
+# config/service/integration-contract.json declares no `database` block, the
+# deploy step prints NOT APPLICABLE and reads neither name. A service that
+# declares that block uncomments both here and fills the values in
+# config/env-active/ only - per machine, never in git.
+# MARIADB_MIGRATION_USER=
+# MARIADB_MIGRATION_PASSWORD=

package/templates/business-service/config/env-templates/shared.env

@@ -0,0 +1,65 @@
+# GENERATED FILE - do not edit. Edit the manifest instead:
+# api/config/shared-env.json, then run `npx oa-sync-template shared-env --target <dir>`.
+
+# The runtime environment name every platform library resolves through its own runtime-config schema; without it a library cannot say which environment it is reporting from.
+NODE_ENV=development
+
+# The log level an infra service's config/logging.json resolves through ${LOG_LEVEL}; one platform value so a stack does not log at four different levels.
+LOG_LEVEL=info
+
+# The HMAC-SHA256 secret the gateway and auth sign and verify access tokens with; it is shared because both ends of one token must hold the same value (docs/standards/JWT_AUTH.md).
+JWT_SECRET=CHANGE_ME
+
+# The ordered list of SecretBox master keys every process that resolves a secret reference decrypts with - entries of <key_id>:<base64 32-byte key> separated by commas, newest FIRST: the first entry seals every new write, every entry opens what it sealed (selected by the blob's own key_id), and a blob naming a key outside the list is refused rather than guessed at (owner decision docs/governance/confirmations/secretbox-master-keys.md 001). It is shared because one keyring has to reach every bearer at once - a rotation is a switch of this one list, and a service left on yesterday's list stops reading what its neighbour has already re-encrypted; the measured cost of the single key it replaces is six of ten rows of oagen_meta.secret unreadable for two weeks after the August 2026 rotation. The value is per-machine and lives only in config/env-active/shared.env. @onlineapps/conn-infra-secrets owns the name and the format and never reads the environment itself (principle 1): the bearer reads this key and hands the string to the connector.
+SECRETS_MASTER_KEYS=CHANGE_ME
+
+# The address of the platform cache on the docker network; declared once because every service reaches the same instance. The instance demands a password (server-topology 004: Redis publishes on wg0 with authentication), so the URL carries it: the value is per-machine and lives only in config/env-active/shared.env, and it is the same password as NODE_CACHE_PASSWORD in config/env-active/compose-infra.env - one fact reaching the container that enforces it and the services that authenticate to it, the same two-delivery split MINIO_ACCESS_KEY and MINIO_SECRET_KEY already have.
+REDIS_URL=redis://:CHANGE_ME@api_node_cache:6379
+
+# The broker every service opens its MQ connection with; the credentials are per-machine and live only in config/env-active/shared.env - the platform account is oa_dev, declared by infra/api_services_queuer/definitions.json.
+RABBITMQ_URL=amqp://CHANGE_ME:CHANGE_ME@api_services_queuer:5672
+
+# HTTP address of the registry for administrative operations from the host - scripts/bump-infra-version.sh announces an infrastructure version bump through it. No service reads it: registration travels over MQ to registry.register and discovery reads the Redis projection (confirmation biz-discovery-redis 002).
+REGISTRY_URL=http://api_services_registry:33100
+
+# The host AWS SigV4 signatures are computed against - deliberately the loopback name, not the reachable one, because MinIO validates the Host header (infra/api_minio_proxy/README.md).
+MINIO_ENDPOINT=127.0.0.1
+
+# Where the bytes actually go once the signature is computed against MINIO_ENDPOINT; the other half of the host-header split (infra/api_minio_proxy/README.md).
+MINIO_ACTUAL_HOST=api_minio_proxy
+
+# The S3 API port of the object store, shared with the endpoint it belongs to.
+MINIO_PORT=9000
+
+# Whether the object-store client opens its connection with TLS. It is declared here because until d.411 it was declared nowhere and every reader carried its own default, so one platform value had as many owners as it had readers (.claude/rules/change-discipline.md - One rail per concern). The platform value is false: MinIO publishes its S3 port on the private wg0 overlay only and never on a public interface (docs/governance/confirmations/server-topology.md 002 and 004), so the hop that would carry TLS is an encrypted one already; a deployment that puts TLS in front of the object store changes this key, and no library.
+MINIO_USE_SSL=false
+
+# The object-store account every service reads and writes under; the same pair is also interpolated into compose for the MinIO container itself (config/env-templates/compose-infra.env), two delivery mechanisms that must carry one value.
+MINIO_ACCESS_KEY=CHANGE_ME
+
+# The secret of that same object-store account; shares the compose-interpolation note of MINIO_ACCESS_KEY.
+MINIO_SECRET_KEY=CHANGE_ME
+
+# How often (ms) a business service publishes its MQ heartbeat, and the ONE source of truth for how fresh that signal has to be: every staleness threshold is a multiple of this cadence (BIZ_HEARTBEAT_STALE_FACTOR), never a second duration set by hand - owner decision docs/governance/confirmations/biz-health-freshness.md 001, which supersedes the absolute INFRASTRUCTURE_HEALTH_BUSINESS_STALE_AFTER of batch 111a. It is shared because the publisher and the judge are different processes: the registry derives its monitor and janitor thresholds from it today, and @onlineapps/service-wrapper reads it as the only cadence there is (the wrapper.registry.heartbeatInterval config key is retired and refused by name), so a cadence change cannot reach one side only.
+BIZ_HEARTBEAT_INTERVAL_MS=30000
+
+# How many heartbeat cadences a business service may stay silent before it is judged stale; the only knob on top of BIZ_HEARTBEAT_INTERVAL_MS, and the reason no threshold is written as a duration anywhere (owner decision docs/governance/confirmations/biz-health-freshness.md 001: the factor is config, not doctrine - changing it is an ordinary config change). May be fractional; the derived threshold is whole milliseconds.
+BIZ_HEARTBEAT_STALE_FACTOR=2.5
+
+# The tenant a validation or test run writes into; it is platform-wide and never overridden per service, because a service that picks its own namespace can pick a live one. The classes and their meaning are owned by docs/standards/tenant-allocation.md.
+TESTING_TENANT_ID=99
+
+# The workspace half of that same namespace; it travels with TESTING_TENANT_ID because a run that knows one without the other addresses a namespace it cannot name.
+TESTING_WORKSPACE_ID=200
+
+# Process locale. No code in the platform reads it; the same three values are also baked into every infra Dockerfile as ENV, so this declaration has no measured consumer of its own.
+LANG=en_US.UTF-8
+
+# Process locale. No code in the platform reads it; the same three values are also baked into every infra Dockerfile as ENV, so this declaration has no measured consumer of its own.
+LC_ALL=en_US.UTF-8
+
+# Process locale. No code in the platform reads it; the same three values are also baked into every infra Dockerfile as ENV, so this declaration has no measured consumer of its own.
+LANGUAGE=en_US.UTF-8
+
+# The timezone every container renders local time in, declared ONCE here and inherited by every bearer of shared.env rather than as a per-service key (owner decision docs/governance/confirmations/container-timezone.md 001, on the BIZ-invoicing finding of 2026-08-29 that a document issued after local midnight carried the PREVIOUS day's date, because every container ran UTC). Timestamps stored in databases and in message envelopes stay UTC; this key changes only what local-time rendering resolves to - an invoice date, a log line a human reads - and code that derives a business date must still say which zone it means. Node honours it from its own ICU data, so a container needs no tzdata package for Date/Intl; libc tools (date, shell) follow it only where the image ships tzdata.
+TZ=Europe/Prague

package/templates/business-service/config/service/config.json

@@ -0,0 +1,14 @@
+{
+  "service": {
+    "name": "__REGISTRY_NAME__",
+    "description": "__SERVICE_DESCRIPTION__",
+    "specificationEndpoint": "/specification",
+    "workspaceScoped": false
+  },
+  "wrapper": {
+    "mq": {
+      "url": "${RABBITMQ_URL}",
+      "prefetch": 10
+    }
+  }
+}

package/templates/business-service/config/service/integration-contract.json

@@ -0,0 +1,12 @@
+{
+  "serviceName": "__REGISTRY_NAME__",
+  "requiredConnectors": {
+    "db": false,
+    "redis": false,
+    "mq": true,
+    "minio": false
+  },
+  "integrationMinimum": {
+    "minTestFiles": 1
+  }
+}

package/templates/business-service/config/service/operations.json

@@ -0,0 +1,41 @@
+{
+  "schema_version": "3.0",
+  "operations": {
+    "echo": {
+      "description": "Return the submitted text unchanged. The example operation a new service replaces with its own.",
+      "handler": "handlers/v3/echo#echo",
+      "mutates": false,
+      "resource_type": null,
+      "bundle_scope": "platform",
+      "minRole": "EDITOR",
+      "input": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["text"],
+        "properties": {
+          "text": {
+            "type": "string",
+            "description": "Text to return unchanged",
+            "minLength": 1,
+            "maxLength": 1000,
+            "examples": ["cookbook"]
+          }
+        }
+      },
+      "output": {
+        "type": "object",
+        "required": ["text", "length"],
+        "properties": {
+          "text": {
+            "type": "string",
+            "description": "The submitted text, byte for byte"
+          },
+          "length": {
+            "type": "integer",
+            "description": "Number of UTF-16 code units in the submitted text"
+          }
+        }
+      }
+    }
+  }
+}

package/templates/business-service/docker-compose.production.yml

@@ -0,0 +1,60 @@
+# Production compose for __SERVICE_NAME__
+#
+# The image is the one CI built and pushed, pinned by its DIGEST (requirement R1,
+# api/docs/operations/biz-rework-deployment-requirements.md). The build job
+# publishes BIZ_IMAGE_DIGEST as a dotenv artifact and the deploy job exports it;
+# with the value missing, the ${VAR:?…} marker fails the run by name instead of
+# resolving to a nameless image. A mutable tag is refused because two concurrent
+# pipelines make it nondeterministic between the push and the pull, and a
+# rollback then has no target to roll back to.
+#
+# HOST CONTRACT OF THE BIZ BOX — owner decision
+# api/docs/governance/confirmations/server-topology.md 004:
+#   * ../shared.env is the ONE host-level env file, at
+#     /var/www/html/oadrive/api_biz/shared.env. Its values are the infra box's
+#     property, so it is RENDERED there from that box's own env-active by
+#     api/scripts/provision/render-biz-shared-env.sh and carried to the biz box by
+#     the operator (server-topology 004 and 005) — role-biz writes no env file.
+#     This compose REFERENCES it and never copies it: one file per box, not one
+#     copy per repository.
+#   * ./config/env-active/__SERVICE_NAME__.env carries only this service's own
+#     keys.
+#   * biz_network is external and created by role-biz. It is the ONLY network
+#     that box has: the infra box's networks do not exist there, so naming one
+#     of them here would make the service undeployable — which is why the gate
+#     and tests assert that no other network name appears in this file at all.
+#
+# Usage: BIZ_IMAGE_DIGEST=sha256:… docker compose -f docker-compose.production.yml up -d
+
+services:
+  __CONTAINER_NAME__:
+    image: "registry.gitlab.com/onlineapps/oadrive/__REPO_NAME__@${BIZ_IMAGE_DIGEST:?BIZ_IMAGE_DIGEST is required - the CI deploy job must export the digest of the pushed image}"
+    # There is no build section on purpose: docker refuses a build tag that
+    # carries a digest, and an image built here would in any case not be the one
+    # CI proved. Build locally through docker-compose.yml instead.
+    container_name: __CONTAINER_NAME__
+    deploy:
+      resources:
+        limits:
+          # Same norm as the dev compose, and deliberately the same number —
+          # owner decision api/docs/governance/confirmations/biz-memory-limits.md
+          # 001 names dev and production together, so production is not the
+          # place to discover a different limit.
+          #
+          # WHAT IT COVERS: the resident service process. There is no test
+          # runner here — suites do not run in production — so nothing else
+          # shares this cgroup by construction.
+          #
+          # This file used to declare no limit at all, which meant a new service
+          # reached production unbounded while its dev container was capped.
+          memory: 512M
+    env_file:
+      - ../shared.env
+      - ./config/env-active/__SERVICE_NAME__.env
+    restart: unless-stopped
+    networks:
+      - biz_network
+
+networks:
+  biz_network:
+    external: true

package/templates/business-service/docker-compose.yml

@@ -0,0 +1,93 @@
+services:
+  __CONTAINER_NAME__:
+    build:
+      context: .
+    container_name: __CONTAINER_NAME__
+    user: "1000:1000"
+    # No `ports:`. A biz service binds nothing — work arrives over MQ and is
+    # dispatched in-process (ADR 0005), and
+    # docs/biz/00-model/service-shape.md § No-HTTP tests states the rule for the
+    # compose file directly. The scaffold used to publish a port here, so every
+    # new service broke the shape at the moment it was created.
+    deploy:
+      resources:
+        limits:
+          # The platform norm for a biz service in operation — owner decision
+          # api/docs/governance/confirmations/biz-memory-limits.md 001, which
+          # holds in dev AND in production. It is a prescribed value, not one
+          # measured on this service or on any other.
+          #
+          # WHAT IT COVERS: the resident service process, and nothing else. No
+          # test suite may share this cgroup — that is why the runner below has
+          # a budget of its own, and why raising this number is never the fix
+          # for a suite that runs out of memory.
+          #
+          # Revise it when this service exceeds 60% of the limit in operation,
+          # measured the way the norm was: cgroup memory.stat:anon, sampled
+          # inside the running container.
+          memory: 512M
+    volumes:
+      - .:/app
+    env_file:
+      - ./config/env-active/shared.env
+      - ./config/env-active/__SERVICE_NAME__.env
+    networks:
+      - api_network
+    restart: unless-stopped
+    entrypoint: ["/bin/sh", "init.sh"]
+    # PID 1 is node, never npm: init.sh execs what it is given, and npm does
+    # not forward SIGTERM - a stop would be ten seconds of waiting and then a
+    # SIGKILL through a service that never closed a channel. Row R-PID1,
+    # confirmation biz-compose-pid1 001/002.
+    command: ["node", "index.js"]
+
+  # --- oa-test-runner v1
+  # One-shot test runner — part of the unified biz service shape
+  # (owner decision 2026-09-07, docs/governance/confirmations/biz-test-container.md 001).
+  #
+  # Same build, same env_file, same networks as the service above, so
+  # "tests run in a container" stays true — but its OWN memory budget.
+  #
+  # WHY: two loads were sharing one budget, not one load being too big. Measured
+  # by the BIZ-META thread on 2026-09-06/07 inside the containers, from
+  # /sys/fs/cgroup/memory.peak (api_biz/meta/docker-compose.yml carries the full
+  # numbers): the unit suite peaked at 343 MiB and the service's own peak was
+  # 132 MiB, against a shared 384 MiB limit — so a `docker exec` test run was
+  # killed by the kernel AND took the service down with it, while the
+  # integration suite failed intermittently on a different file each time.
+  #
+  # The 1g below is the platform NORM for the runner — owner decision
+  # api/docs/governance/confirmations/biz-memory-limits.md 001, the same
+  # decision that sets the service's 512M above. It applies in dev and CI only,
+  # and it assumes one suite at a time (`--maxWorkers=1`). It is no longer
+  # "meta's number carried over": measurement is what produced the norm, the
+  # norm is what this file now states.
+  #
+  # `mem_limit`, not the `deploy.resources.limits` form: both were measured to
+  # apply on `docker compose run` with Compose v5.1.3, and this is the plain
+  # Compose one rather than the swarm section Compose honours in part.
+  #
+  # NOT started by a plain `docker compose up` — the `test` profile keeps it
+  # out. No `restart`, no healthcheck: it runs once and exits. The one
+  # documented way to run it is the npm scripts in package.json, which wrap:
+  #   docker compose run --rm __CONTAINER_NAME___tests npm run test:unit
+  __CONTAINER_NAME___tests:
+    build:
+      context: .
+    profiles:
+      - test
+    user: "1000:1000"
+    mem_limit: 1g
+    volumes:
+      - .:/app
+    env_file:
+      - ./config/env-active/shared.env
+      - ./config/env-active/__SERVICE_NAME__.env
+    networks:
+      - api_network
+    entrypoint: ["/bin/sh", "init.sh"]
+  # --- end oa-test-runner v1
+
+networks:
+  api_network:
+    external: true

package/templates/business-service/docs/80-setup/INSTALL.md

@@ -0,0 +1,123 @@
+Parent: [../../README.md](../../README.md)
+Owns: the installation flow for a new __REPO_NAME__ instance — prerequisites, environment preparation, the bootstrap sequence, and what this service does NOT need.
+
+# INSTALL
+
+## Scope
+
+Bootstraps `__REPO_NAME__` — a business service with no database and no object
+storage. It binds no port: work arrives over MQ and is dispatched in-process
+(ADR 0005, `api/docs/biz/80-decisions/0005-no-http-in-biz-containers.md`), so
+there is no HTTP endpoint to install or to call afterwards.
+
+What the service needs is declared once, in
+`config/service/integration-contract.json` → `requiredConnectors`: `mq` only.
+`db`, `redis` and `minio` are `false`, which is why this document has no SQL
+step — the installation contract derives the SQL half from the contract's
+`database` block, and this service declares none.
+
+## Prerequisites
+
+- Docker and Docker Compose v2.
+- Node.js — the major this repository declares in `package.json` `engines.node`.
+  The same major is in the `Dockerfile` base image and in `.gitlab-ci.yml`;
+  requirement R3 of the deploy contract fails the gate if the three disagree, so
+  read the major there rather than from a number written here.
+- A reachable RabbitMQ and service registry. Their URLs arrive as
+  `${RABBITMQ_URL}` and `${REGISTRY_URL}`, the two placeholders
+  `config/service/config.json` carries; ConfigLoader substitutes them at boot and
+  fails by name if either is unset.
+- The external Docker network the compose file names (`api_network` in dev), and
+  on the production biz box `biz_network` — both are created outside this
+  repository.
+
+## Environment preparation
+
+```bash
+mkdir -p config/env-active
+cp config/env-templates/shared.env  config/env-active/shared.env
+cp config/env-templates/__SERVICE_NAME__.env config/env-active/__SERVICE_NAME__.env
+```
+
+Then edit both files: `shared.env` carries the infrastructure URLs and the
+testing namespace (`TESTING_TENANT_ID`, `TESTING_WORKSPACE_ID`), the service file
+carries what belongs to this service alone. `config/env-active/` is gitignored —
+the templates are the versioned half, the active files are per-instance.
+
+Every variable a handler reads must additionally be declared in
+`config/service/integration-contract.json` → `env`, with a reason per name. The
+scaffold declares no `env` block because it reads none: the only two names it
+needs are the `${…}` placeholders above, and the contract must not repeat what a
+config placeholder already covers. The first handler that reads an environment
+variable adds the block.
+
+On the production biz box the second env file is a host-level `../shared.env`,
+written once per box and referenced rather than copied (owner decision
+`api/docs/governance/confirmations/server-topology.md` 004).
+
+## Bootstrap sequence
+
+1. Prepare the env files (above).
+2. Start the dependencies this service declares required — MQ and the registry.
+   They are not part of this repository.
+3. Start the service:
+
+   ```bash
+   docker compose up -d --build
+   ```
+
+   `init.sh` installs dependencies on first start and skips the install when
+   neither `package.json` nor `package-lock.json` changed.
+
+   That command builds the SERVICE only. The one-shot test runner carries
+   `profiles: [test]`, so it is outside a plain build as well as outside a plain
+   `up` — measured 2026-09-14: `docker compose build --dry-run` builds one image,
+   `docker compose --profile test build --dry-run` builds two. Build it when the
+   suites are to run against this checkout:
+
+   ```bash
+   docker compose --profile test build
+   ```
+4. Verify the install — [VALIDATION.md](VALIDATION.md) states the checks and what
+   each one must print.
+
+## Production
+
+The production compose pins the image by digest, so it is pulled, never built:
+
+```bash
+BIZ_IMAGE_DIGEST=sha256:… docker compose -f docker-compose.production.yml pull
+BIZ_IMAGE_DIGEST=sha256:… docker compose -f docker-compose.production.yml up -d
+```
+
+CI publishes that digest from the build stage and the deploy job refuses to run
+without it (requirement R1). A first deploy also clones the checkout on the box
+if it is missing, so onboarding a new service needs no manual step there.
+
+### Migrations at deploy time
+
+Between that `pull` and that `up` the deploy job applies this service's pending
+MariaDB migrations — the ordering is the safety: the new image is already on the
+box, the previous container is still serving, and a migration that fails stops
+the deploy before the switch. Two facts decide what happens:
+
+- `config/service/integration-contract.json` → `database`. This scaffold declares
+  no such block, so the step prints `NOT APPLICABLE (no database block)` and the
+  deploy carries on. A service that declares one has its `database.schema`
+  migrated from the directory `database.migrations` names.
+- `config/env-active/__SERVICE_NAME__.env` → `MARIADB_MIGRATION_USER` and
+  `MARIADB_MIGRATION_PASSWORD`, the service's own account. The step creates
+  neither the schema nor the account and refuses the deploy when that account
+  cannot open the schema, naming the runbook instead.
+
+Who creates them, with which grants and which collation, is the runbook's step
+and is not repeated here: `api/docs/setup/INSTALL.md`, the business-schema step.
+The decision behind both halves — two phases, the service account as the
+isolation guard, one runner and one tracker across them — is owner confirmation
+`api/docs/governance/confirmations/db-migrations-first-deploy.md` 001.
+
+## Status
+
+Current. One of the three files the installation contract requires by name —
+`biz-ci-gate verify-install-contract` (and `verify-contract`, which folds it in)
+fails when it is missing.

package/templates/business-service/docs/80-setup/PLATFORM_MATRIX.md

@@ -0,0 +1,65 @@
+Parent: [../../README.md](../../README.md)
+Owns: the execution differences between Linux, macOS and a CI/cloud runner when installing or validating __REPO_NAME__.
+
+# PLATFORM MATRIX
+
+Every command in this document runs from the repository root
+(`api_biz/__SERVICE_NAME__/`). Relative paths in prose and in links resolve from
+this document's own directory (`docs/80-setup/`) instead — the two bases differ,
+so a path copied from one into the other does not resolve.
+
+The service itself runs inside the image the `Dockerfile` builds, so the host
+platform decides how the containers are reached, never what runs in them. That
+is why the differences below are about the shell around the container, not about
+the service.
+
+## Linux
+
+- Reference environment.
+- The compose file runs the service as `user: "1000:1000"`. On a host whose own
+  uid is not 1000, files the container writes into the bind mount (`node_modules`,
+  `conn-runtime/`) belong to that uid — run the container as your own uid, or
+  accept the ownership.
+- Start and validate:
+
+  ```bash
+  docker compose up -d --build
+  npm run test:container
+  npm run test:cookbooks:container
+  ```
+
+## macOS
+
+- Same commands; Docker Desktop maps the bind mount, so the `user: "1000:1000"`
+  line above has no visible effect on file ownership.
+- Run the suites through the container scripts above rather than on the host: the
+  runner has the env files and the same image the service uses. A bare `npm test`
+  on the host runs against whatever Node and environment the shell happens to
+  carry.
+- The dependency guard in `init.sh` uses `md5sum`, which runs inside the Alpine
+  container, not on the host — macOS shipping `md5` instead is irrelevant here.
+
+## CI / cloud runner
+
+- Non-interactive: no prompts, and nothing may depend on a developer's shell.
+  `.gitlab-ci.yml` installs with `npm ci` and runs `npm run test:ci`.
+- The contract gates run from the installed validator, not from a checkout of the
+  platform repository:
+
+  ```bash
+  node node_modules/@onlineapps/conn-orch-validator/src/cli/biz-ci-gate.js verify-contract
+  ```
+
+  `verify-contract` needs `LIBRARIES_SSOT_URL` (requirement R6 compares the
+  `@onlineapps/*` pins against the platform library set) and the service's
+  dependencies installed — the test-coverage half asks the service's own jest
+  which files it would run.
+- The build stage publishes the image digest as a dotenv artifact and the deploy
+  stage refuses to run without it; both stages are declared in `.gitlab-ci.yml`.
+- Windows is outside the supported matrix.
+
+## Status
+
+Current. One of the three files the installation contract requires by name —
+`biz-ci-gate verify-install-contract` (and `verify-contract`, which folds it in)
+fails when it is missing.

package/templates/business-service/docs/80-setup/README.md

@@ -0,0 +1,18 @@
+Parent: [../README.md](../README.md)
+Owns: the map of the installation branch — which of the three installation documents answers which question
+
+# Setup
+
+An operator installs this repository from these three documents, in this order.
+
+- [INSTALL](INSTALL.md) — prerequisites, environment preparation and the bootstrap sequence
+- [PLATFORM_MATRIX](PLATFORM_MATRIX.md) — what differs between Linux, macOS and a CI runner
+- [VALIDATION](VALIDATION.md) — the checks that prove the install, and what each failure means
+
+The three are the platform installation contract (`SETUP_DOCS`), so the set is
+fixed: a repository carries all three or it does not satisfy the contract.
+
+## Status
+
+Current. The map of this branch: `M001` of the documentation lint reports a leaf
+this file does not link, and `S008` reports a branch that carries no map at all.

package/templates/business-service/docs/80-setup/VALIDATION.md

@@ -0,0 +1,78 @@
+Parent: [../../README.md](../../README.md)
+Owns: the mandatory checks after installing __REPO_NAME__, the output each one must produce, and the failure signature that says which check did not hold.
+
+# VALIDATION
+
+## Required checks after install
+
+1. The repository satisfies the platform contract — deploy, installation,
+   environment and test coverage.
+2. The unit suite passes in the test runner container.
+3. The cookbook run dispatches the example operation and asserts its output by
+   value.
+4. The container reaches the end of boot and registers. **There is no health
+   endpoint to call** — a biz container serves no HTTP (ADR 0005), so the
+   container log and the registry are the only readiness evidence.
+
+## Command sequence
+
+Every command runs from the repository root (`api_biz/__SERVICE_NAME__/`).
+
+```bash
+# 1 — contract gates (deploy R1-R5/R7-R8, installation docs, env, test coverage, R6)
+node node_modules/@onlineapps/conn-orch-validator/src/cli/biz-ci-gate.js verify-contract
+
+# 2 — unit suite, in the one-shot runner beside the service
+npm run test:container
+
+# 3 — cookbooks, in the same runner (it has the env files)
+npm run test:cookbooks:container
+
+# 4 — boot evidence
+docker compose logs --tail=50 __CONTAINER_NAME__
+```
+
+## Expected outcome
+
+| Check | Passes when |
+|---|---|
+| 1 contract gates | the run ends with `[BizCiGate] OK verify-contract` and exits `0`; each half prints its own `OK` line first |
+| 2 unit suite | jest reports no failing test and the command exits `0` |
+| 3 cookbooks | the run prints `Failed: 0`, ends with `=== Pre-Validation Completed Successfully ===` and writes `conn-runtime/validation-proof.json` |
+| 4 boot | the log shows registration and handler validation, and the container stays up (`docker compose ps` reports it running, not restarting) |
+
+The cookbook check asserts a VALUE, not that something came back: the shipped
+cookbook requires the echoed text to equal what it sent and its length to equal
+`8`. Keep that property when the example operation is replaced — an assertion of
+truthiness proves the dispatch worked and nothing about the result
+(`.claude/rules/architecture-principles.md` §10a).
+
+## Failure signatures
+
+- `[BizCiGate] Missing file - …/config/service/integration-contract.json` — the
+  contract is gone; every gate reads it first.
+- `[BizCiGate] FAIL … SETUP_DOCS — Missing required file - docs/80-setup/…` — one
+  of these three documents was deleted or renamed.
+- `[BizCiGate] FAIL … ENV_COMPLETENESS — "X" is read in … but is neither declared
+  … nor covered` — a handler started reading an environment variable; declare it
+  in the contract's `env` block with the reason, or delete the read.
+- `[BizCiGate] FAIL … TEST_RUNS_NOWHERE — Test file runs nowhere - …` — a test
+  file exists that the `test:all` chain does not run; put it in the chain, or
+  declare its script in `stackTiers` with the reason it cannot be there.
+- `[BizCiGate] Missing package script - test:all …` — the chain the coverage gate
+  measures against was removed.
+- `[SetupDatabase] Missing database.collation - the schema is created with the
+  collation the service declares, and there is no default.` — `setup-db` was asked
+  to build a schema for a service whose contract carries a `database` block
+  without `collation`. Add the key with the collation this service's tables
+  already use; the same key the production runbook reads, and the one uniform row
+  `D-DB-COLLATION` asks for.
+- `[ConfigLoader] Missing environment variable - X is required (config placeholder
+  ${X})` at boot — the env-active files were not prepared, or that name is missing
+  from them.
+
+## Status
+
+Current. One of the three files the installation contract requires by name —
+`biz-ci-gate verify-install-contract` (and `verify-contract`, which folds it in)
+fails when it is missing.

package/templates/business-service/docs/README.md

@@ -0,0 +1,18 @@
+Parent: [../README.md](../README.md)
+Owns: the map of this repository's documentation tree — which branch answers which question
+
+# __REPO_NAME__ — documentation
+
+Every document in this tree is reached from here by clicking down; a node no map
+links to is a node nobody finds (DOC-STANDARD rule 1).
+
+- [Setup](80-setup/README.md) — installing this repository and proving the install
+
+The platform-wide concepts this service is built on — the service shape, the
+tenancy model, the contracts it speaks — live in the platform tree
+`api/docs/biz/`, and this tree links to them rather than restating them.
+
+## Status
+
+Current. The map of this tree: `L006` of the documentation lint reports every node
+this file does not reach by clicking down.