@mindbricks/genesis-set 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/LICENSE +202 -0
  3. package/README.md +147 -2
  4. package/bin/genesis-set.mjs +153 -0
  5. package/corpus/README.md +25 -0
  6. package/corpus/genesis/compile-results.md +246 -0
  7. package/corpus/genesis/compiler-api.md +265 -0
  8. package/corpus/genesis/custom-code.md +519 -0
  9. package/corpus/genesis/deploy.md +190 -0
  10. package/corpus/genesis/pitfalls.md +231 -0
  11. package/corpus/genesis/procedures/README.md +17 -0
  12. package/corpus/genesis/procedures/agent-hub-blueprint.md +13 -0
  13. package/corpus/genesis/procedures/auth-blueprint.md +14 -0
  14. package/corpus/genesis/procedures/bff-blueprint.md +16 -0
  15. package/corpus/genesis/procedures/blueprint-authoring.md +16 -0
  16. package/corpus/genesis/procedures/howto-mail-to-tasks.md +26 -0
  17. package/corpus/genesis/procedures/howto-payment-flow.md +112 -0
  18. package/corpus/genesis/procedures/howto-subscription.md +33 -0
  19. package/corpus/genesis/procedures/notifications-blueprint.md +13 -0
  20. package/corpus/genesis/procedures/patterns-catalog.md +12 -0
  21. package/corpus/genesis/procedures/project-lifecycle.md +27 -0
  22. package/corpus/genesis/run-locally.md +310 -0
  23. package/corpus/genesis/testing.md +532 -0
  24. package/lib/config-cli.mjs +179 -0
  25. package/lib/install.mjs +639 -0
  26. package/lib/mcp-config.mjs +220 -0
  27. package/lib/semver.mjs +94 -0
  28. package/mcp/blueprint.mjs +64 -0
  29. package/mcp/client.mjs +141 -0
  30. package/mcp/config.mjs +166 -0
  31. package/mcp/key-page-html.mjs +275 -0
  32. package/mcp/key-page.mjs +217 -0
  33. package/mcp/key-store.mjs +204 -0
  34. package/mcp/key-tools.mjs +225 -0
  35. package/mcp/server.mjs +164 -0
  36. package/mcp/tools.mjs +270 -0
  37. package/package.json +43 -4
  38. package/skills/genesis-compiler-api/SKILL.md +56 -0
  39. package/skills/genesis-deploy/SKILL.md +36 -0
  40. package/skills/genesis-generated-code/SKILL.md +48 -0
  41. package/skills/genesis-run-and-test/SKILL.md +43 -0
@@ -0,0 +1,190 @@
1
+ # Deploying the generated services yourself
2
+
3
+ **Genesis never deploys.** It writes the files a deploy needs into each service repository; the
4
+ deploy itself is run by the user, or by you on the user's behalf, with the user's own login on
5
+ the target. No deploy credential ever goes to Genesis, into the blueprint or into a project file.
6
+ This page lists, per target, what Genesis writes and the commands that deploy it.
7
+
8
+ > **Not deployable yet.** Builds are dry runs for now: the deploy files are generated and
9
+ > counted (the job's `deployArtifacts`), but nothing is pushed to the user's repositories, so
10
+ > there is nothing to deploy yet. Until pushing opens, say so, and do not write a target's files
11
+ > by hand as if Genesis had generated them.
12
+
13
+ ## 1. Asking for the deploy files
14
+
15
+ Name the targets in the build: `genesis_buildService` with, for example,
16
+ `deployTargets: ["docker-compose", "fly"]`. Each target writes `deploy/<target>/` into the
17
+ service. These are generated files: they are in the manifest, counted in the build's added lines,
18
+ and rewritten by every build that names the target (do not edit them; keep your own deploy
19
+ files outside `deploy/<target>/`). The job's `deployArtifacts` lists per target
20
+ `{ target, status: "emitted" | "skipped", path, files, reason? }`; a part without a container
21
+ image (`document`, `frontend`) is `skipped`.
22
+
23
+ | Target | Status | Folder |
24
+ |---|---|---|
25
+ | `docker-compose` | available | `deploy/docker-compose/`: `docker-compose.yml`, `.env.example`, `.providers.secrets.env.example`, `README.md` |
26
+ | `railway` | available | `deploy/railway/`: `railway.json`, `variables.env`, `README.md` |
27
+ | `fly` | available | `deploy/fly/`: `fly.toml`, `secrets.env`, `README.md` |
28
+ | `render` | available | `deploy/render/`: `render.yaml`, `README.md` |
29
+
30
+ An unknown target answers `400 GENESIS_UNKNOWN_DEPLOY_TARGET` with `details.allowed`: that list,
31
+ not this page, is the truth for the API you call. There is no frontend target: the user places
32
+ the frontend themselves.
33
+
34
+ The generated `README.md` of each target is written for that service and that build (its service
35
+ names, ports and variables). Read it before you run anything; where it and this page differ,
36
+ it wins.
37
+
38
+ ## 2. What every target needs
39
+
40
+ - **The secrets are references, never values.** Every password and key in the generated files is
41
+ a `${VAR}` / `${VAR:?}` / `${{...}}` reference or a blank line. The user fills them on the
42
+ target (or in a gitignored local file), never in a committed file.
43
+ - **A signing key per service.** Each service signs its tokens with its own Ed25519 key. Without
44
+ one the service starts degraded (the login service cannot issue sessions). Per service:
45
+
46
+ ```sh
47
+ openssl genpkey -algorithm ed25519 -out <service>.pem # PKCS#8 PEM
48
+ uuidgen # its key id
49
+ ```
50
+
51
+ Set them as secret variables on the target (`SERVICE_PRIVATE_KEY_PEM` / `SERVICE_KID` per
52
+ service on Railway, `<SERVICE>_SERVICE_PRIVATE_KEY_PEM` / `<SERVICE>_SERVICE_KID` in the
53
+ compose `.env`). Never commit a key file.
54
+ - **Peer addresses.** In the test, stage and prod slot files the addresses of the other services
55
+ (`AUTH_SERVICE_URL`, `SERVICE_<NAME>_URL`, ...) are blank on purpose: the deploy sets them.
56
+ The compose file and the Railway variables already wire the services of the same build.
57
+ - **Provider credentials** (payment, mail, storage, AI): the keys each service reads are listed
58
+ in its `.providers.secrets.env.example` (compose) or as shared variables (Railway). Missing ones
59
+ do not stop the service from starting; it answers errors where they are needed (see
60
+ [pitfalls.md](pitfalls.md)).
61
+ - **For a local file** (`.env`, `*.secrets.env`): ask for each key on the local key page
62
+ (`genesis_requestKey`, then `genesis_writeKeyToEnvFile`), never in the chat.
63
+ - **On a hosting target:** the user enters the key in the target's own secret settings.
64
+ - **The test transport.** Every generated nodejs service mounts super-admin-only test routes
65
+ (`/<service>-api/admin/test-transport`, [testing.md](testing.md)) on any explicit non-production
66
+ slot: the `dev`, `test` and `stage` images. The Railway, Fly.io and Render files run the PROD
67
+ slot, where they are closed. On
68
+ any other shared deploy that is not prod, set `MB_TEST_TRANSPORT=off` unless the user wants the
69
+ surface reachable there.
70
+ - **Health:** every service answers `/health`. A deploy is done when `/health` reports ready,
71
+ not when the container runs ([run-locally.md](run-locally.md)).
72
+
73
+ ## 3. docker-compose: the whole stack on one machine
74
+
75
+ The compose file holds every deployable service of the build, each built from its own repository
76
+ with its DEV slot image, plus the infrastructure they read: PostgreSQL or MongoDB (by each
77
+ service's database type), Redis and Elasticsearch for the backend services, and Kafka. Every
78
+ service repository carries the same stack.
79
+
80
+ 1. Check the service repositories out side by side (the generated README lists the folder names,
81
+ `<codename>-<service>-service/`).
82
+ 2. Then, in any one of them:
83
+
84
+ ```sh
85
+ cd deploy/docker-compose
86
+ cp .env.example .env
87
+ cp .providers.secrets.env.example .providers.secrets.env
88
+ # fill in .env (passwords, signing keys) and the provider credentials you use
89
+ docker compose up --build
90
+ ```
91
+
92
+ 3. `docker compose ps` shows the health of each container; `docker compose logs -f <service>`
93
+ follows one service.
94
+
95
+ Notes:
96
+ - Docker Compose 2.24 or newer is needed (the provider file is an optional `env_file`).
97
+ - Neither `.env` nor `.providers.secrets.env` is committed: the generated `.gitignore` ignores
98
+ both. Use URL-safe passwords (the MongoDB password goes into a connection URL). Put a PEM into
99
+ `.env` in double quotes.
100
+ - The infrastructure is reachable only inside the compose network.
101
+
102
+ ## 4. Railway
103
+
104
+ Per service, `deploy/railway/` holds the config-as-code file (the PROD slot Dockerfile, health
105
+ check `/health`, restart on failure), `variables.env` (the variables in Railway's Raw Editor
106
+ format, with Railway references for the databases and the other services) and a README naming
107
+ what the references expect.
108
+
109
+ The user logs in with their own Railway account; the login stays in the Railway CLI or their
110
+ browser, never in the project. In one Railway project:
111
+
112
+ 1. Add the databases the README names: a PostgreSQL service named `Postgres` (for PostgreSQL
113
+ services), a MongoDB service named `MongoDB` (for MongoDB services) and a Redis service named
114
+ `Redis` (for backend services). The variable references use exactly these names.
115
+ 2. For each service of the build, create a Railway service from its repository, named as its
116
+ README says (the other services' references use those names).
117
+ 3. In that service's settings, set the config-as-code path to `deploy/railway/railway.json`.
118
+ 4. In its Variables, open the Raw Editor and paste `deploy/railway/variables.env`. Fill the
119
+ shared variables the README lists (a missing one resolves to empty) and set
120
+ `SERVICE_PRIVATE_KEY_PEM` / `SERVICE_KID` as sealed variables.
121
+ 5. Generate a public domain for each service that serves the outside world.
122
+
123
+ With the Railway CLI the same steps are `railway login`, `railway link` (or `railway init` for a
124
+ new project) and, per service, `railway up` from the service repository; check
125
+ `railway --help` for the version the user has instead of guessing flags. In CI the token is a
126
+ secret of the CI system (`RAILWAY_TOKEN`), never a file of the repository.
127
+
128
+ ## 5. Fly.io
129
+
130
+ One Fly app per service, named after its repository (`<codename>-<service>-service`).
131
+ `deploy/fly/` holds `fly.toml` (the PROD slot Dockerfile, `http_service` on the slot's port,
132
+ the `/health` check, an explicit VM size), `secrets.env` (every value the user gives, as blank
133
+ lines, in the form `fly secrets import` reads) and a README with the app names, the
134
+ infrastructure and the sizing.
135
+
136
+ - **Peers** talk over Fly's private network: `[env]` already holds each peer's
137
+ `http://<app>.flycast` address. Every app needs a private IP for that (Flycast).
138
+ - **Machines:** a service with a Kafka consumer or an in-process cron job is always on
139
+ (`auto_stop_machines = "off"`, `min_machines_running = 1`); only a service the tree proves
140
+ request-only scales to zero. A service whose README says ONE Machine runs in-process cron jobs
141
+ without a cross-Machine lock: deploy it with `--ha=false`.
142
+ - **Infrastructure:** PostgreSQL can be Fly Postgres and Redis Upstash for Redis; Kafka,
143
+ Elasticsearch and MongoDB come from outside Fly (a hosted provider) or the user's own Machines
144
+ with volumes. Their addresses and credentials go into `secrets.env`.
145
+ - No volume is mounted: the root filesystem is lost on every restart.
146
+
147
+ The user logs in with their own Fly account (`fly auth login`). Per service, from the service
148
+ repository root (the build context; `fly.toml` names the Dockerfile relative to itself):
149
+
150
+ ```sh
151
+ fly apps create <app> # the app name from the README
152
+ fly ips allocate-v6 --private -a <app> # the Flycast address the peers use
153
+ # fill deploy/fly/secrets.env locally (never commit the filled file), then:
154
+ fly secrets import -a <app> < deploy/fly/secrets.env
155
+ fly deploy --config deploy/fly/fly.toml # add --ha=false where the README says ONE Machine
156
+ ```
157
+
158
+ Check `fly --help` for the version the user has instead of guessing flags. In CI the token is a
159
+ secret of the CI system (`FLY_API_TOKEN`), never a file of the repository.
160
+
161
+ ## 6. Render
162
+
163
+ `deploy/render/render.yaml` is a Render Blueprint: one Docker `web` service built from the PROD
164
+ slot Dockerfile, with `/health` and an explicit size. The ONE repository that owns the project's
165
+ shared infrastructure (the login service, or the first backend service) also declares a Render
166
+ Postgres instance (every PostgreSQL service creates its own database on it) and a Key Value
167
+ (Redis) instance every service shares. The README of each service says which repository that is.
168
+
169
+ 1. Apply the owner repository's Blueprint first: in the Render dashboard, New Blueprint from that
170
+ repository, Blueprint Path `deploy/render/render.yaml`.
171
+ 2. Then the Blueprint of every other service repository, the same way.
172
+ 3. When a Blueprint is first applied, Render asks for the `sync: false` values: the README lists
173
+ them. Peer addresses are among them: Render publishes a peer's private address as `host:port`,
174
+ so give it as `http://<host:port>`. Set `SERVICE_PRIVATE_KEY_PEM` / `SERVICE_KID` there too.
175
+ 4. Kafka, Elasticsearch and MongoDB come from outside Render; give their addresses and
176
+ credentials the same way.
177
+
178
+ A service that runs continuously (a Kafka consumer, in-process cron jobs) must stay off Render's
179
+ Free plan, whose instances spin down after 15 minutes without traffic. Keep ONE instance where
180
+ the README says so. The user signs in to Render with their own account; nothing about it goes to
181
+ Genesis or into the repository.
182
+
183
+ ## 7. What you never do
184
+
185
+ - Ask the user for a deploy token to send to Genesis, or store one in the project, the blueprint
186
+ or a commit.
187
+ - Report a deploy as done without the target's own evidence: the platform's deploy log and
188
+ `/health` ready on the public address.
189
+ - Edit `deploy/<target>/` files to make a deploy work: the next build rewrites them. Fix the
190
+ blueprint and compile again, or report the generated file as a compiler fault with the job id.
@@ -0,0 +1,231 @@
1
+ # Genesis pitfalls: compiler facts
2
+
3
+ Behaviours of the code Genesis generates that surprise people who run it themselves. Each
4
+ entry: symptom, cause, what to do. Entries marked **nodejs** are verified for the nodejs
5
+ runtime only; other languages follow in their own time. Facts about HTTP shapes, seeding and
6
+ stale reads are in `procedures/pitfalls.md` (mind-set); this page adds what changes because
7
+ you run the service on your own machine or servers. Run steps are in
8
+ [run-locally.md](run-locally.md), failed builds in [compile-results.md](compile-results.md).
9
+
10
+ ## 1. The slot decides everything: `CONFIG_ENV`
11
+
12
+ The generated service learns which environment it is in from `CONFIG_ENV`, written into each
13
+ slot file (`.dev.env` has `dev`, `.test.env` `test`, `.stage.env` `stage`, `.prod.env`
14
+ `prod`). Several behaviours below depend on it.
15
+
16
+ - **Unset or empty `CONFIG_ENV` resolves to `prod`**, with a loud console error. The service
17
+ keeps running, with the strictest behaviour (no verification codes in answers, no SMS sink).
18
+ A local run must load `.dev.env` or set `CONFIG_ENV=dev`.
19
+ - **A value it does not know throws** at start (a typo such as `prd`). Fix the deployment;
20
+ the service does not guess. Accepted: `dev`, `test`, `stage`, `prod` and the older
21
+ aliases `development`, `local`, `staging`, `production`.
22
+ - The slot is the only input. No header, body field or blueprint setting changes it, and the
23
+ blueprint's `verificationMode` is retired (a value other than the default only draws the
24
+ warning `VERIFICATION_MODE_INERT`).
25
+
26
+ ## 2. Verification codes in the start answer (nodejs)
27
+
28
+ **Symptom:** a flow answers `emailVerificationNeeded` and no code reaches you, or the
29
+ `secretCode` is missing from the start answer.
30
+
31
+ **Cause:** the code is echoed in the `start` answer (with the `userId`, for an existing
32
+ account) only when the slot is `dev` or `test`. In `stage` and `prod` it is never in the
33
+ answer, whatever the blueprint says: it travels only through the real mail or SMS provider,
34
+ or lands in a sink (sections 3 and 4).
35
+
36
+ **Do:**
37
+
38
+ - Locally (`dev`), chain the two calls as `procedures/pitfalls.md` shows: `start`, then
39
+ `complete` with the returned `secretCode` as a string.
40
+ - On a `stage` or `prod` slot, read the code from the real inbox or handset when the
41
+ provider has credentials, otherwise from the mail sink. Do not set the slot to `dev` on a
42
+ reachable deployment to get codes: that is the one switch that turns the echo on.
43
+ - A missing `secretCode` on a `dev` or `test` slot for an existing account is worth
44
+ checking against `CONFIG_ENV` first (section 1), then reporting with the request and answer.
45
+ - A `start` answered 403 "too frequent" means a recent code exists. Wait or use another
46
+ account.
47
+
48
+ ## 3. Mail falls to a sink, and a green send is not delivery (nodejs)
49
+
50
+ **Symptom:** verification and notification mails "send" and nobody receives them; or every
51
+ send fails with an SMTP connect error to `mail-sink`.
52
+
53
+ **Cause, in four parts:**
54
+
55
+ 1. An email provider declared only under `mailAccounts` is NOT a send channel. A project with
56
+ no complete email provider (declared with all credential keys) has no real channel at all.
57
+ Validation warns once with `MAIL_FLOWS_GO_TO_SINK`.
58
+ 2. With no complete email provider the framework routes every notification and every
59
+ verification mail to its built-in mock SMTP sink (the delivery rows name the provider
60
+ `__mailsink__`). It does so in every slot, `prod` included.
61
+ 3. The sink is an SMTP host the environment must provide. The default address is
62
+ `mail-sink` port `465`; `MAILSINK_HOST` and `MAILSINK_PORT` point the service at another
63
+ one, `MAILSINK_REJECT_UNAUTHORIZED` is for a sink with a certificate the service does not
64
+ trust.
65
+ 4. The generated `deploy/docker-compose/` stack does not list a mail-sink service. In that
66
+ stack the send fails after retries, one `failed` delivery row per message. It looks like an
67
+ outage; it is the same missing channel seen from the other side.
68
+
69
+ **Do:**
70
+
71
+ - For development, run any SMTP capture server your stack can reach, and set `MAILSINK_HOST`
72
+ / `MAILSINK_PORT` for the service. Then a send is captured and reports success.
73
+ - Judge mail by the channel, never by the send status: success against the sink means
74
+ "stored in the sink", not "reached a recipient".
75
+ - For stage and production, declare a real email provider in the blueprint and give it its
76
+ credentials (`$ENV:` references in the blueprint, values in the service's secrets file).
77
+ - Reserved demo recipients can force the sink even with complete credentials. If a real
78
+ address gets nothing, check the recipient.
79
+
80
+ ## 4. SMS: sink rules differ from mail (nodejs)
81
+
82
+ - An SMS provider that is declared but has incomplete credentials sends to the **SMS sink**
83
+ when `CONFIG_ENV` is set and is not `prod`. In `prod` it never falls back: the send fails at
84
+ the provider and the boot report names it.
85
+ - The SMS sink stores each message in the same mail sink as section 3: one mail per SMS to
86
+ `sms-<digits>@sms-sink.invalid` (digits of the number only), subject `SMS to <number>`,
87
+ provider name `__smssink__`. Search the inbox by the number. It needs the same sink host.
88
+ - A project with **no SMS provider declared at all** still builds the mobile flows, and every
89
+ SMS goes to the sink in every slot, `prod` included (validation warns once with
90
+ `SMS_FLOWS_GO_TO_SINK`). Name the real SMS provider before production.
91
+ - A sunk SMS was not delivered to a handset.
92
+
93
+ ## 5. Credential fallbacks, and what each one proves (nodejs)
94
+
95
+ Missing credentials never stop the service. The runtime falls back, per family:
96
+
97
+ | Family | With credentials missing or incomplete |
98
+ |---|---|
99
+ | mail | the mail sink (section 3), every slot |
100
+ | SMS | the SMS sink on non-prod slots (section 4) |
101
+ | bucket | the service's own native store |
102
+ | payment | the provider's mock, for `stripe`, `iyzico` and `adyen`; other brands have no mock and REFUSE at payment start |
103
+ | AI | no fallback: the call fails |
104
+
105
+ Use the four evidence outcomes when you report a provider. Never put key values in the
106
+ report.
107
+
108
+ | Outcome | Evidence | What it proves |
109
+ |---|---|---|
110
+ | Configured test provider | a declared test brand or transport and an observed operation | only that test path |
111
+ | Selected fallback | the runtime's own status names the sink / native / mock mode and the reason | the fallback, not vendor delivery |
112
+ | Placeholder-only | a required secret is still `ENTER_CREDENTIAL` or absent | the provider is bound; the real operation is unverified |
113
+ | Measured delivery | the real operation plus a receipt or captured artifact | that operation in that slot; a sink capture is not a recipient's delivery |
114
+
115
+ Rules:
116
+
117
+ - `ENTER_CREDENTIAL` is the placeholder for a secret that is not provided. It passes
118
+ authoring and counts as "not configured" at runtime; it is no proof of anything. A
119
+ realistic fake value is worse than the placeholder: it looks configured.
120
+ - A required key that is NOT a secret (a sender address on your own domain) takes the real
121
+ value, never the placeholder: a placeholder there reads as a value and the provider fails at
122
+ send time with nothing warning first.
123
+ - `<PREFIX>_CREDENTIAL_MODE` in a slot's environment (`auto`, `sandbox`, `live`, `mock`) is
124
+ read BEFORE the credential check: `mock` engages the mock or sink whatever credentials are
125
+ present; `live` lifts the payment live-key guard on a non-prod slot. Unrecognised or blank
126
+ means `auto`.
127
+ - A payment live key in a non-prod slot is refused by a guard unless the mode is `live`.
128
+ Keep live keys in the `prod` slot's secrets file only.
129
+ - Check what the service decided, not what you configured: `GET /health` carries a
130
+ `providerCredentials` block (`status` `ok` / `incomplete` / `error`, `deploymentEnv`,
131
+ `providerCount`, `findings`), and the payment service serves
132
+ `GET /<order-service>-api/v1/payments/mock-status` (one row per provider with `mock`,
133
+ `reason`, `transport`, `blocking`; plus `anyMock`, `blocking`, `health`). Read your
134
+ provider's row. `transport: "absent"` means the brand has no mock and payment start
135
+ refuses.
136
+ - Never call a live provider from a test. The runtime ladders for payments and
137
+ subscriptions are in `procedures/howto-payment-flow.md`, with the Genesis additions in
138
+ `genesis/procedures/howto-payment-flow.md` of this corpus.
139
+
140
+ ## 6. Payment tables need auth compiled after the provider is bound
141
+
142
+ **Symptom:** starting a payment answers 500 through a missing `/auth-api/paymentcustomers`.
143
+
144
+ **Cause:** the auth service's payment tables (`sys_paymentCustomer`, `sys_paymentMethod`) and
145
+ their routes are generated only when a payment provider is bound in the blueprint. An auth
146
+ service compiled before the provider was bound does not have them.
147
+
148
+ **Do:** bind the provider, validate, compile `auth` again, re-run the service from the new
149
+ code (and rebuild its image if you deploy images). Then retry the payment start.
150
+
151
+ ## 7. `column "x" does not exist` is schema drift
152
+
153
+ **Symptom:** a 500 whose message says `column "x" does not exist` or `relation "x" does not
154
+ exist`.
155
+
156
+ **Cause:** the database schema is behind the generated models: the code was regenerated and
157
+ the running service or its database was not brought forward.
158
+
159
+ **Do:** run the newly generated code and let it start: boot re-syncs the schema. Check
160
+ `GET /health` `readiness` afterwards (see [compile-results.md](compile-results.md) section 9).
161
+ Never hand-write `ALTER`, `DROP` or `TRUNCATE` to fix drift. If a restart on fresh code does
162
+ not clear it, report the exact message. A 500 with `Cannot read properties of undefined` or an
163
+ MScript error is NOT drift: the cause is in the code path.
164
+
165
+ ## 8. Each service needs its own signing key
166
+
167
+ **Symptom:** the login service starts but issues no session; other services reject tokens.
168
+
169
+ **Cause:** every service signs its tokens with its own Ed25519 key. Without
170
+ `SERVICE_PRIVATE_KEY_PEM` and `SERVICE_KID` (in compose: `<SVC>_SERVICE_PRIVATE_KEY_PEM`,
171
+ `<SVC>_SERVICE_KID`) the service starts degraded.
172
+
173
+ **Do:** generate one per service (`openssl genpkey -algorithm ed25519`), pick any UUID as the
174
+ key id, keep both in the service's gitignored secrets file or the deployer's secret store.
175
+ Every other service reads the public key from the auth service at `AUTH_SERVICE_URL` +
176
+ `/publickey`.
177
+
178
+ ## 9. Empty peer addresses in test, stage and prod
179
+
180
+ **Symptom:** a service starts and `/health` is fine, but calls to another service, token
181
+ checks or links fail; documents show `<codename>-stage.example`.
182
+
183
+ **Cause:** in the `test`, `stage` and `prod` slot files, `SERVICE_URL`, `AUTH_SERVICE_URL`,
184
+ `SERVICE_<NAME>_URL` and `SERVICE_MCPBFF_URL` are empty lines on purpose. The `dev` slot keeps
185
+ local addresses. Document hosts use the reserved `.example` names.
186
+
187
+ **Do:** pass the real addresses as container environment variables (they override the file).
188
+ `GEOIP_SERVICE_URL` stays empty (lookup off) until you provide one. Buckets with a virus scan
189
+ get `CLAMAV_ENABLED=false` unless the blueprint gave its own host or url: turn it on only
190
+ with a scanner you run.
191
+
192
+ ## 10. The service never exits at boot
193
+
194
+ **Symptom:** the process is up, the port answers, every request returns a generic error.
195
+
196
+ **Cause:** a missing dependency or credential does not stop a generated service. A "critical"
197
+ problem makes every request fail with a generic error. Silence at boot is not health.
198
+
199
+ **Do:** read the service log first, then `GET /health` (liveness, `readiness`, the dependency
200
+ checks for the database, Redis and Elasticsearch where the service uses them, and
201
+ `providerCredentials`). Fix the named cause, restart.
202
+
203
+ ## 11. Scheduled work (nodejs unless noted)
204
+
205
+ - A cron controller or service cron job runs on **one replica per tick** by default: each tick
206
+ is claimed in the `sys_cronJobRun` table. With `"singleReplica": false`, and for every
207
+ non-nodejs language, the job runs on EVERY replica. Three replicas then run three times
208
+ per tick. One local container hides this.
209
+ - An edge controller's `edgeCronSettings` schedules nothing (warning `EDGE_CRON_NOT_SCHEDULED`).
210
+ Use a cron job.
211
+ - A `onceEver` job that has succeeded never runs again, even after a redeploy: its manual
212
+ run route answers 409, and `{ "force": true }` works only for a superAdmin session.
213
+ Renaming the job starts a new history and runs it again.
214
+ - A run-once data move must be safe to repeat: a failed or timed out run leaves part of the
215
+ data moved and the next tick retries, nothing is rolled back. Back up first and check
216
+ `GET /cron-jobs/<name>/runs`.
217
+ - `timeoutSeconds` does not kill the function: the run is recorded `timed_out` and
218
+ `ctx.signal` fires. A function that ignores the signal keeps running; check
219
+ `ctx.signal.aborted` between batches.
220
+ - Edge REST paths are served below `/edge` (or `EDGE_MOUNT_PATH` when the deployment sets it):
221
+ do not repeat `/edge` in the declared path.
222
+
223
+ ## 12. Build-side facts that look like runtime faults
224
+
225
+ - Files you add to a generated repo survive every rebuild; edits to generated files do not
226
+ (the build counts them in `manifest.editedFilesOverwritten`). A "fix" in generated code
227
+ that vanishes after the next build is this, not a regression.
228
+ - A rebuilt service needs a restart of the running copy; a blueprint edit is not live until
229
+ it was compiled, pulled into the repo, and the service restarted on it.
230
+ - Compiling `auth` first matters when other services read its user, tenant and role shapes;
231
+ after a change to those, compile the dependants again.
@@ -0,0 +1,17 @@
1
+ # Genesis additions to the mind-set procedures
2
+
3
+ One file per mind-set procedure that has Genesis-specific steps. Read the mind-set
4
+ procedure (`~/.mind-set/current/procedures/<name>.md`) and, next to it, its file here.
5
+
6
+ | Additions | mind-set procedure | Places |
7
+ |---|---|---|
8
+ | [agent-hub-blueprint.md](agent-hub-blueprint.md) | `procedures/agent-hub-blueprint.md` | 1 |
9
+ | [auth-blueprint.md](auth-blueprint.md) | `procedures/auth-blueprint.md` | 1 |
10
+ | [bff-blueprint.md](bff-blueprint.md) | `procedures/bff-blueprint.md` | 1 |
11
+ | [blueprint-authoring.md](blueprint-authoring.md) | `procedures/blueprint-authoring.md` | 1 |
12
+ | [howto-mail-to-tasks.md](howto-mail-to-tasks.md) | `procedures/howto-mail-to-tasks.md` | 1 |
13
+ | [howto-payment-flow.md](howto-payment-flow.md) | `procedures/howto-payment-flow.md` | 2 |
14
+ | [howto-subscription.md](howto-subscription.md) | `procedures/howto-subscription.md` | 1 |
15
+ | [notifications-blueprint.md](notifications-blueprint.md) | `procedures/notifications-blueprint.md` | 1 |
16
+ | [patterns-catalog.md](patterns-catalog.md) | `procedures/patterns-catalog.md` | 1 |
17
+ | [project-lifecycle.md](project-lifecycle.md) | `procedures/project-lifecycle.md` | 2 |
@@ -0,0 +1,13 @@
1
+ # Genesis additions: AgentHub module authoring
2
+
3
+ These notes add to the mind-set procedure `procedures/agent-hub-blueprint.md` (installed at
4
+ `~/.mind-set/current/procedures/agent-hub-blueprint.md`). Follow that procedure; at each place below,
5
+ do what this file says. They hold what is true of the Genesis compiler and the code it
6
+ generates, and the Genesis Compiler API steps.
7
+
8
+ ## 1. In "6. Validate, build, gate"
9
+
10
+ Instead of the mind-set step that starts "2. Building the system service **`agentHub`** and checking its health ...":
11
+
12
+ 2. Compile the system service **`agentHub`** with the Genesis Compiler API
13
+ (the genesis-compiler-api skill) and check its health where you run it.
@@ -0,0 +1,14 @@
1
+ # Genesis additions: Auth module authoring
2
+
3
+ These notes add to the mind-set procedure `procedures/auth-blueprint.md` (installed at
4
+ `~/.mind-set/current/procedures/auth-blueprint.md`). Follow that procedure; at each place below,
5
+ do what this file says. They hold what is true of the Genesis compiler and the code it
6
+ generates, and the Genesis Compiler API steps.
7
+
8
+ ## 1. In "5. Validate, build, gate"
9
+
10
+ Instead of the mind-set step that starts "2. Phase 3 must not start before the `authentication` module validates ...":
11
+
12
+ 2. Compile the system service **`auth`** with the Genesis Compiler API (the
13
+ genesis-compiler-api skill) and check its health where you run it — Phase 3
14
+ must not start before the `auth` service is compiled and healthy.
@@ -0,0 +1,16 @@
1
+ # Genesis additions: BFF module authoring
2
+
3
+ These notes add to the mind-set procedure `procedures/bff-blueprint.md` (installed at
4
+ `~/.mind-set/current/procedures/bff-blueprint.md`). Follow that procedure; at each place below,
5
+ do what this file says. They hold what is true of the Genesis compiler and the code it
6
+ generates, and the Genesis Compiler API steps.
7
+
8
+ ## 1. In "5. Validate, build, gate"
9
+
10
+ Instead of the mind-set step that starts "2. The notifications module authoring starts only after":
11
+
12
+ 2. Compile the system service **`bff`** with the Genesis Compiler API (the
13
+ genesis-compiler-api skill) and check its health; the notifications module
14
+ authoring starts only after
15
+ the DataViews exist (its `dataViewName` references are checked against
16
+ them).
@@ -0,0 +1,16 @@
1
+ # Genesis additions: Blueprint authoring
2
+
3
+ These notes add to the mind-set procedure `procedures/blueprint-authoring.md` (installed at
4
+ `~/.mind-set/current/procedures/blueprint-authoring.md`). Follow that procedure; at each place below,
5
+ do what this file says. They hold what is true of the Genesis compiler and the code it
6
+ generates, and the Genesis Compiler API steps.
7
+
8
+ ## 1. In "9. The authoring loop and the completeness gate"
9
+
10
+ Instead of the mind-set step that starts "Keep portable `js` by default and use optional native sources ...":
11
+
12
+ Keep portable `js` by default, use optional native sources deliberately,
13
+ and read a failed slot's provenance in the compile result's build log
14
+ (the .NET translator gates are a Genesis compiler step). Supported direct awaited
15
+ Internal API forms from #6546 work on the current generator; do not
16
+ prescribe blanket C# rewrites or warning suppression.
@@ -0,0 +1,26 @@
1
+ # Genesis additions: How-to: incoming mail opens tasks and meetings, answered from the owner's mailbox
2
+
3
+ These notes add to the mind-set procedure `procedures/howto-mail-to-tasks.md` (installed at
4
+ `~/.mind-set/current/procedures/howto-mail-to-tasks.md`). Follow that procedure; at each place below,
5
+ do what this file says. They hold what is true of the Genesis compiler and the code it
6
+ generates, and the Genesis Compiler API steps.
7
+
8
+ ## 1. In "4. Who is admitted (do not fight it, design with it)"
9
+
10
+ Instead of the mind-set step that starts "## 5. Validate the blueprint 1. `mind-set validate blueprint.json` is ...":
11
+
12
+ #### 5. Verify the running service
13
+
14
+ 1. Compile; the Genesis Compiler API's validation is green (the template
15
+ has no address and its own listen topic; every mail action on it
16
+ carries `mailbox`).
17
+ 2. As a user, connect a mailbox: `GET /my-mailboxes` lists `workMail`
18
+ with `connect: oauth`; the consent lands back with `?mailbox=<address>`.
19
+ 3. `GET /health/details` (operator) on the mcpbff shows the
20
+ `connectedMailboxes` block with `listening: 1`.
21
+ 4. Send a mail to that address. Within the poll interval the Kafka api
22
+ runs: a `task` / `meeting` row stamped with the owner, and, when
23
+ `acknowledge` fired, a reply in the sender's inbox FROM the owner's
24
+ address, threaded.
25
+ 5. Negative: call `POST /mail/workMail/read` with another user's session
26
+ and the first user's address: `404 MAILBOX_NOT_FOUND`.