# WBSP Project Guidelines These guidelines are **normative**. Every project that deploys on the WBSP platform should reference this document from its constitution, and should follow the conventions below. They exist to make deployment smooth, predictable, and boring — the platform can only hide infrastructure details from you if your project is laid out the way the platform expects. > If a rule here ever conflicts with a more specific platform document (for > example [application-creator-guide.md](application-creator-guide.md) or > [parallel-services-guide.md](parallel-services-guide.md)), follow the more > specific document and raise the discrepancy. ## Related platform documents These sibling guides are normative alongside this one — read the ones relevant to your project. In particular, **how `wbsp deploy` authenticates to AWS** lives in [credential-less-deploy.md](credential-less-deploy.md): the credential model that now governs every AWS deploy. Do not treat it as optional detail buried under the command list. - [application-creator-guide.md](application-creator-guide.md) — building and deploying a WBSP application end to end (destinations, components, enclaves). - [wbsp-yaml-reference.md](wbsp-yaml-reference.md) — full `wbsp.yaml` field reference and the worked per-destination `.env` examples. - [credential-less-deploy.md](credential-less-deploy.md) — deploying to AWS with only your platform login (no AWS keys); the single CI secret; sandbox publish/promote; the `universal` destination (publish a multi-architecture, appliance-runnable image without deploying). - [useful-commands.md](useful-commands.md) — the CLI / AWS / database commands an app developer needs day to day. - [nextJS-api-guidelines.md](nextJS-api-guidelines.md) — API conventions for Next.js projects. - [parallel-services-guide.md](parallel-services-guide.md) — provisioning extra backing services (Forgejo, ClickHouse, …) via parallel namespaces. - [single-tenant-guidelines.md](single-tenant-guidelines.md) — single-tenancy and shared sign-on (SSO) across a user's apps. - [path-prefixes.md](path-prefixes.md) — running an app under a URL path prefix behind the platform proxy. - [installation.md](installation.md) — installing the `wbsp` CLIs. **Know which documents are generated and which are copies.** The pages above, and this one, are written by hand and published from the platform's repository; they say what the platform intends. Documents belonging to **another** project — HAP's endpoint reference and its OpenAPI specification are the ones you will meet most — reach the wiki as **periodic copies**, republished by that project's operator as a manual step. A copy can lag the running service by days. The practical rule: **an address absent from a copied specification is not evidence that the route does not exist.** Probe the running service before you conclude that two documents disagree — a `curl` against the address, or the service's own live specification endpoint, settles in seconds what prose cannot. For HAP that endpoint is **`{hap-url}/openapi.json`** (for the platform's own server, `https://hap.wbsp.ai/openapi.json`): it is served by the running service, so it cannot lag it, and it is the document to trust when a copy and a guideline disagree about whether a route exists. If they still disagree after that, raise it with both owners (§9) rather than choosing; and when you record the answer anywhere your project will read again, record the date you observed it, because the observation ages. ## Explaining your work **Every explanation must assume the reader never looks at the code.** When you describe what you built, what changed, why something failed, or how a feature works — in conversation with the user, in a commit message, in `/user-docs`, in a decision record, in a status report — write for someone who has the running application in front of them and will never open the source. In practice that means framing explanations in terms of **behaviour the reader can observe**: what the application now does, what a user will see, what they must do differently. It rules out naming source files, functions, classes, structs, variables, or line numbers, describing internal module layout, and walking through control flow. Those are meaningless to someone who cannot see them, and they quietly move the burden of understanding onto a reader who has no way to carry it. - **Instead of** "added a re-import guard in `ingestBatch()` so the activity detail column isn't rewritten" — **write** "re-running an import no longer creates second copies of emails that were already brought in." - **Instead of** "the `/me` handler returns 500 when `workspace_id` is null" — **write** "a user who does not yet belong to a workspace is bounced back to the sign-in page instead of being let in." **The same applies to the database and to your own APIs.** The reader does not know your schema and has never read your API reference. Table names, column names, foreign keys, migrations, indexes, endpoint paths, payload fields and status codes are all internals to them — as opaque as a function name, and for the same reason. "The `subscribers` table now has a `verified_at` column" and "`POST /v1/imports` returns 409 on a duplicate" both describe a change the reader cannot see; "a subscriber who has confirmed their address is now shown as verified in the list" and "importing the same file twice no longer creates duplicates" describe the same changes in terms they can check. Names the reader can actually *act on* are not code internals and stay: URLs and paths they will visit, commands they will type, configuration keys they will set in `wbsp.yaml` or `.env`, and environment-variable names. The test is whether the reader can use the name without opening the repository. An API endpoint crosses back into that category only when the reader is the person calling it — in your published API reference, or when they asked how to call it. This is not a rule about end-user documentation only — it applies to explanations written for operators and for the platform team as well. Those audiences differ in what they will *do* with the explanation, not in whether they can read your source. ### Colour-code every reply in three bands When you report back to the user in conversation, sort what you have to say into exactly three bands, in this order, and use these markers: - 🟢 **Done** — what you actually did, and what is now true. Facts you have verified, not intentions. - 🟡 **Still to do (not yours)** — work that remains but that nobody is being asked for: something running, something another team owes, something you will pick up next. - 🔴 **What you must do** — the things you need *from the user*: a decision, a command only they can run, a credential, an approval. **Every request lives in the red band and nowhere else.** A question buried in a paragraph of what you have done is a question that gets missed, and the user ends up blocked on something they never saw you ask. If the red band is empty, say so — "nothing outstanding" is a useful sentence, and it tells the user they can walk away. Two failure modes to avoid. Do not put finished work in the red band to make it look thorough — the band's value is that everything in it needs the user. And do not soften a request into the green band because it feels like an interruption; a decision you quietly made on the user's behalf, reported as done, is worse than the interruption would have been. --- ## 1. File locations A project repository has a small number of well-known directories. Keeping to them means tooling, reviewers, and the platform always know where to look. ### `/initial-research` Early project planning, specifications, and research live here and **stay** here. These are working documents that informed the project; they are not the project itself. Typical files: - `data-model-suggestion-*.md` - `development-plan.md` - `features.md` - `legal.md` - `research.md` - `standards.md` ### `/target` Place **all** application code and files under `/target`. This is the only directory whose application changes the platform tracks and deploys. Treat everything outside `/target` as supporting material (research, docs, tooling) rather than the shippable product. ### Monorepo projects (alternative to `/target`) Some projects genuinely require a monorepo: several cooperating source trees (for example `/backend` and `/frontend`) at the repository root, with **no** `/target` directory. This is the only sanctioned alternative layout, and it comes with conventions of its own: - **Source trees are direct children of the repository root.** Their names are the project's choice (`/backend`, `/frontend`, `/worker`, …). Everything else in §1 (research, docs locations) is unchanged. - **The layout is your choice, and the pipeline asks you for it.** Early on, at its *Set project direction* step, the build pipeline researches your project's shape, recommends single-app or monorepo, and then asks you which you want. Your answer is recorded as the project's `repo` decision (see "Decisions recorded as you build" below) and the pipeline follows it from then on — it never guesses the layout by looking at directories. - **Optionally declare the layout** in the root `wbsp.yaml`. This is the explicit override and outranks everything else, which makes it useful for a repository restructured by hand: ```yaml layout: kind: monorepo source-roots: [backend, frontend] ``` - **Project-wide build-pipeline artifacts move to the repository root**: the Playwright config (`playwright.config.ts`) and the E2E suite (`/e2e`) live at the root instead of under `/target`. Per-destination `.env.` files may sit at the root or beside a source tree. Scripts the pipeline detects (the demo-data seed, the production init script) live under a source tree's `scripts/` or `src/`. - **`/target` and monorepo trees never mix.** If a `/target` directory exists, the project IS single-app — the pipeline treats it as such, and monorepo trees nested under `/target` are not supported. ### Deployment topology and parallel services Two of the recorded decisions describe how your application *runs*, and together they determine what each deployment mode can offer. Both are asked at the pipeline's *Set project direction* step. **Topology** is how the application is built and shipped as Docker images — independent of the repository layout above (a monorepo often still ships a single image): | Value | Meaning | Where it runs | | --- | --- | --- | | `single` | one program in one image | every mode: local, cloud, demo, appliance | | `combined` | several programs sharing one image, differing only in how they start | every mode; the cloud can run and scale the programs separately | | `split` | separately built and deployed images | cloud only, as a **direct deployment** arranged with the platform operator | **Parallel services** are non-application images your application needs running alongside it — a git server, a search engine, an analytics stack — beyond the managed database, Redis and S3-compatible storage the platform gives every app. The platform runs them as a *parallel-services environment* (declared in a `wbsp-services.yaml` beside your `wbsp.yaml`); arbitrary images are accepted, and the implications of operating them rest with the platform's hosting operator. Declaring parallel services changes what the easier modes can offer, and the backdown is deliberate: - **Demo / sandbox** instances never bundle parallel services. Your application decides whether it offers a demo at all, and disables the features that need them when `WBSP_SAMPLE_MODE` is set — ideally with a note that the feature is available in the full product. **A demo also reaches nothing outside its own container** — see *"A demo talks to nothing outside itself"* below. - **Appliance** images are always a single image; a parallel service is never baked in. Document the missing functionality clearly, and point at a cloud deployment as the answer when it is needed. - **Cloud** deployments run parallel services in full. ### A demo talks to nothing outside itself A demo or sandbox instance **must not interact with the public Internet or any external service**: no email, no third-party API (language models, social networks, payment providers, calendars, analytics), no webhooks, no data of any kind leaving the container. A visitor is looking at a demonstration, and nothing they type into it should reach a real inbox, a real account, or a real invoice. - **Gate on `WBSP_SAMPLE_MODE`, never on a missing key.** Projects commonly disable outbound features by noticing that no API key is configured. That is **accidental degradation, not a rule**: a key baked into an image, left in `.env.demo`, or injected later turns real sending back on, silently, and the visitor has no way to know it happened. The environment variable states the intent; an absent key merely happens to have the same effect today. - **Say so in the interface, where the feature would have been.** A visible line — "switched off in this demonstration; the full product would email the guest" — is the difference between a demo that looks deliberately scoped and one that looks broken. - **Keep workers and schedulers inert.** A background job that fires an hour after a visitor leaves is still egress, and is the path most likely to be forgotten because nothing in the interface triggers it. - **This does not mean stop logging.** Your structured logs on `stdout`/`stderr` are collected by the platform and never leave it, so §7 applies in a demo exactly as elsewhere. What is excluded is shipping traces, events or metrics to a **third-party** service. Logging more in sample mode is helpful, not a breach. - **List your outbound paths in your demo notes**, so a reviewer can check each one rather than infer from the absence of failures. Anything that opens a socket to a host you do not control belongs on that list. ### Decisions recorded as you build A handful of choices define the shape of your project, and the build pipeline records them so that nothing later quietly contradicts them. They live in two places at the repository root: - **`wbsp-status.md`** — a `Decisions:` block below the pipeline checkboxes, for reading at a glance. - **`DECISIONS.md`** — the same decisions as YAML (despite the `.md` name the file is YAML from top to bottom), each with a note of who decided it and when. Nine decisions are always listed; one not yet made reads `unknown`: | Decision | Meaning | | --- | --- | | `tenant` | single-tenant or multi-tenant (see the single-tenant guidelines) | | `repo` | single app under `/target`, or a monorepo (above) | | `parallel services` | non-application services run alongside the app, e.g. `forgejo`; `none` if not needed (below) | | `topology` | how the app ships as Docker images: `single`, `combined`, or `split` (below) | | `has website` | the project serves a web interface | | `has api` | the project exposes an API | | `has mobile app` | the project includes a mobile app | | `has MCP server` | the project provides an MCP server | | `frameworks / languages` | what it is built with, e.g. `nextJS` | Tenancy, repository layout, parallel services, deployment topology, and — only if there is a reason to depart from Next.js — the web framework are **asked of you** at the pipeline's *Set project direction* step. The rest are read from your project's own research, spec and plan, and are refined as those firm up. Decisions you made yourself are never overwritten without asking you first, so if the plan later contradicts one, the pipeline stops and raises it. Both files are maintained by the pipeline — treat them as its output rather than something to hand-edit. ### `/user-docs` All user-facing documentation lives here. See [§3 Pre-deployment documents](#3-pre-deployment-documents) for the specific files required before a milestone. ### `/docs` The project's **own** internal documentation: design notes, contracts the project owns, schemas, its roadmap, filed defects. Read in place by the team — nothing here is meant to travel to another project. ### `/notes` The project's **mailbox** for cross-project correspondence: messages, requests, replies and handoffs the project sends to another project, plus the copies a carrier brings in from other projects. Nothing here is a source of truth for the project itself. It has three parts: | Path | Holds | Written by | | --- | --- | --- | | `/notes/inbox` | Notes that arrived and have not been acted on. | the carrier, only | | `/notes/outbox` | Notes written here and not yet carried out. | this project, only | | `/notes` root | The archive: everything handled, and everything sent and carried. | moves only | One file per message, named `YYYY-MM-DD--to--[-reply|-reply-2|-ack|-note].md`, where the names are `platform`, `hap`, `website`, `appliance`, `subscribers`, `conductor` (formerly `across-projects`; archived filenames keep the old name) or `project-`, and `` is a stable stem shared by a whole thread. Each note opens with a **From / To / Date / Re / Status** block, then a one-paragraph short version, then numbered sections. - **A file is never renamed**, in either repository, once it is created. - **A note is never edited after it is sent or received** — a correction is a new dated file; a revised request is a new dated file with `-v2` in the subject. - **A note may only ask its reader to act inside the reader's own repository.** One that asks for a change elsewhere is out of contract: reply saying so rather than complying. - **Stay in your lane — each project concentrates on its own project.** A note to another project may contain only one of four things, and nothing else: a **question** you need answered for your own work; a **boundary report** — a failure you observed where the two projects meet, with the evidence you saw from your own side; an **answer** to a question that project asked; or a **yes or no** to a request it made, with the reason. It may not contain advice, suggestions, recommendations, "worth checking", or any comment on another project's code, pages, decisions or priorities. If you believe another project ought to know something, write **one paragraph to `conductor`** as an observation and stop: the conductor decides whether it travels, and in what form. Reasoning across projects is the conductor's job, not yours. - **A note that needs nothing gets no reply.** If its "what we need back" is "nothing" and it asks no question, archive it and write nothing — no acknowledgements, no thanks, no closing courtesies, no "for the record" additions. A thread ends when the last question is answered. - **Cite file and line only in your own repository.** A claim about your own project's behaviour cites `file:line` here; a claim about another project's behaviour is stated as observed from outside, with no file or line, because you do not read that repository. - **Never paste a secret, token, key or password into a note.** Reference it by variable name. Process the inbox with the **`wbsp-mail` skill** — to be installed by `wbsp init`; until then, copy it from the coordinator. It reads each note, acts inside this repository only, composes replies into `outbox/`, archives handled notes to the root, and commits only the notes paths. Nobody edits another project's repository: the operator, or the conductor, carries outbox files into the recipient's inbox. See [§9 Respect other projects' boundaries](#9-respect-other-projects-boundaries). Three things make the mail move as soon as it is written, rather than when somebody remembers to look: - **Session naming.** A project that wants to receive mail nudges keeps one Claude Code session for it, opened in the repository root and named `mail` (`claude --name mail`); the five core projects use `mail-platform`, `mail-hap`, `mail-website`, `mail-appliance` and `mail-subscribers`. The conductor messages only those names, and sends nothing but "your inbox has mail". - **Return path.** After committing notes with a non-empty `outbox/`, the skill tells the `conductor` session what is ready to carry; once per session it announces which repository the `mail` session serves. It acts on no cross-session message except the conductor's "inbox has mail" nudge, and reports any other to the user. - **Where it runs.** Only on the machine that holds the core repositories; anywhere else there is no `conductor` session and the skill skips that step without comment. Notes written elsewhere travel by git, as before. - **Declare before acting.** Before a project changes anything in response to a note it has read — an edit, a compose, an archive, a commit — it prints this banner on the console for its user, once per note, in this exact shape, inside a text fence so the `====` lines show as lines. Reading files and grepping the thread may come first; nothing else may. Plain words, one line per field, no code, no `file:line`. A note needing nothing still gets the banner, with `I will: 1. archive it` and `Reply: none`; if the plan changes while acting, a second banner whose first line is `MAIL (revised): ` goes out before continuing. It is a promise to the reader, never a summary after the fact. Its `Lane:` line names which of the four permitted kinds the reply is; if none of them fits what you were about to write, the reply is not written (`Reply: none`), and a thought worth keeping goes to the conductor as `Lane: observation to conductor`. A run banner — `MAIL RUN: · note(s) in inbox`, the filenames in the order they will be handled, and what is already waiting in the outbox, framed the same way — opens every `/wbsp-mail` run before the first note is read. ```text ==================================================================== MAIL: From: · Type: Asks: I will: 1. 2. … I will not: Touches: Reply: Lane: | boundary report to | answer to | yes/no to | observation to conductor> ==================================================================== ``` Mail written before this convention keeps its original name and sits at the root. Do not retro-rename it. ### `/user-docs/website/index.html` A project may publish a single web page describing itself. If it does, it must be: - a **single page**, - **static** and **self-contained** (no build step, no external assets), - **inline CSS** (no linked stylesheets), - **openable directly in a browser** by double-clicking the file. --- ## 2. Websites and services If your project exposes a **web interface or an API**, it needs to be deployable on the cloud. Provide the two platform files at the root of your project: | File | Purpose | | --- | --- | | `wbsp.yaml` | Tells the platform what to deploy, where to route traffic, and what resources/backing stores to provision. | | `wbsp.Docker` | The Dockerfile the platform uses to build your application image. | **`wbsp.yaml` MUST be in the repository root** — never under `/target` (a `target/wbsp.yaml` is wrong and the platform tooling will not find it). Your application code still lives under `/target` (§1); point the manifest at it with `source: target` and `dockerfile: target/`, which are resolved relative to the repository root. (In a monorepo — §1 "Monorepo projects" — each component's `source:` points at its own tree instead, e.g. `source: backend`.) **`wbsp.yaml` MUST declare your catalog variant** — the `variant: ` field. By convention it sits **immediately before `name:`**. The platform derives your image repository from this UUID (the same repository `git push` uses), so without it image-producing deploys are refused. Get the UUID with `wbsp whoami` (or from your variant's page on wbsp.ai): ```yaml variant: 7a1d8030-1234-4abc-8def-0123456789ab # from `wbsp whoami` — just before name name: my-app ``` **`wbsp.yaml` MUST declare the reserved `universal` destination** — an empty block is the normal shape: ```yaml destination: universal: {} ``` Declaring the block opts the app into the appliance publish (`wbsp deploy --destination universal`), which builds a multi-architecture, appliance-runnable image and deploys nothing; the build pipeline's **Universal build** step runs that publish and adds the block if it is missing. `universal` is a *reserved* destination: never declare `type`, `mode`, `tenant`, `cluster`, or `enclave` under it (each is a hard error) — everything else (`release:`, `env:`, `secrets:`) is still yours, and the effective `release:` is stamped onto the image so the appliance can migrate its database before starting the app. See [wbsp-yaml-reference.md](wbsp-yaml-reference.md) ("Reserved destinations") and [credential-less-deploy.md](credential-less-deploy.md) for the details. Your application should follow the platform's basic contract — be stateless, listen on the port the platform tells it to, and take all configuration from environment variables. See [wbsp-yaml-reference.md](wbsp-yaml-reference.md) for the full `wbsp.yaml` field reference and worked examples, and [application-creator-guide.md](application-creator-guide.md) for the end-to-end deploy walkthrough. ### Preferred web + API stack: Next.js **Next.js is the platform's preferred (but not mandatory) web + API stack.** If you choose Next.js, write your APIs following [nextJS-api-guidelines.md](nextJS-api-guidelines.md), unless there is a good reason not to do so — in which case **ask the user for permission to deviate and document the decision and reason clearly** (in your project's constitution or an ADR). The guidelines exist so that an API written today in Next.js can be ported to a different server framework (most likely NestJS) with minimal rework if the project ever outgrows Next's API surface. Because Next.js is the default, the build pipeline does **not** ask you to pick a web framework as a matter of course. It raises the question only when its research turns up a concrete, project-specific reason that Next.js is the wrong fit — and then it tells you the reason and what it would use instead. Whatever is settled is recorded as the `frameworks / languages` decision (above). ### Consider Rust when a framework is genuinely being chosen Whenever the framework question **is** live — while the *Set project direction* step is researching, evaluating and recommending a framework, or whenever a component's language is settled later — **evaluate Rust alongside the other candidates, and recommend it when you judge it appropriate.** It is a serious option on this platform, for three reasons that show up in what a deployment costs and how it behaves: - **Low memory usage.** Instances are sized on what they actually consume, so a service that idles in tens of megabytes rather than hundreds changes the cost of running it and how many can share a node. - **Small image size.** A statically-linked binary in a minimal base image pulls and starts faster on every destination. This matters most on the appliance and demo paths, where the image is shipped and launched over and over. - **A smaller attack surface.** No interpreter and no large runtime dependency tree inside the image, and memory safety enforced when the code is built, remove whole classes of vulnerability instead of mitigating them. Two limits keep this honest. **It does not loosen the gate above.** The pipeline still does not raise the web-framework question merely to offer a choice. Rust is something you name when the question is already being asked — not a reason to invent the question. **Weigh how hard it would actually be to build.** Recommend Rust only where the project's shape suits it and the work is not disproportionate. Against it, weigh a less turnkey ecosystem for web UI, data access and auth than Next.js offers, slower iteration while a design is still moving, and whoever will maintain the project afterwards. A back-end service, an API, a worker, or a command-line tool with a stable contract is where it pays off soonest; a UI-heavy application still changing shape is usually where it does not. When you do recommend it, say plainly which of the three benefits this project actually gets, and what it gives up to get them — then **ask the user and record their answer**, like any other direction decision. Never adopt it on your own judgement. If your project **uses** services (rather than providing them), start those services for local development — preferably with a `docker-compose.yaml` file — so a developer can run the whole project on their own machine. ### Avoiding port clashes in `docker-compose` Common ports (3000, 4000, 5432, 6379, …) collide when several WBSP projects run their `docker-compose` stacks on the same machine at once. To keep stacks runnable side by side, **derive the publicly-published ports from the project's numeric prefix** whenever the project name / directory has one. For a project directory with a numeric prefix (e.g. `41-ai-native-crm`), publish each service on a port formed by **the first two digits of the service's conventional port** as the prefix and **the three-digit, zero-padded project number** as the suffix: | Service | Conventional port | First two digits | Project suffix | Published port | | --- | --- | --- | --- | --- | | Web app | 3000 | `30` | `041` | `30041` | | PostgreSQL | 5432 | `54` | `041` | `54041` | | Redis | 6379 | `63` | `041` | `63041` | Only the **host-published** (left-hand) port changes; the **container-internal** port stays conventional, so application code and service-to-service URLs inside the Compose network are unchanged: ```yaml services: app: ports: - "30041:3000" # host 30041 → container 3000 postgres: ports: - "54041:5432" ``` This rule applies to **`docker-compose` (local development) only** — it does not affect AWS or other cloud destinations, where the platform assigns ports and routes traffic itself (your container still listens on the platform-specified port, e.g. 8080). If a derived value would exceed the maximum TCP port (65535), pick a nearby free high port instead. **For apps deployed via the platform's local-machine types** — `compose`, `dev`, and `standalone` (features 055 / 063) — the above derivation is automatic. The operator declares `projectNo: ` at the top level of `wbsp.yaml` (or omits it and lets the platform parse the leading numeric prefix of the app directory's name), and the platform host-publishes app/postgres/redis on `NNN` ports per this rule. A derived value that would exceed 65535 (e.g. an app on port 8080 → `80NNN`) folds deterministically into the IANA dynamic range `[49152, 65535]`, and a host-port clash is reported by the deploy's pre-flight. No hand-written `docker-compose.yaml` is required. **Under `dev`, the platform derives ports for the data services but cannot derive one for your application, because it does not start it** — you do, from your IDE. Apply the same rule by hand there: pin the derived port in the start command and in `.env.dev` rather than accepting your framework's default — *Running under `dev`*, below, has the rest of what that destination implies. See [useful-commands.md](useful-commands.md) for the local-machine workflows and [wbsp-yaml-reference.md](wbsp-yaml-reference.md) for `projectNo`. ### Running under `dev` — host processes, derived ports, two origins A `type: dev` destination is **not** a containerised copy of your application. The deploy brings up only the **data services** — Postgres, Redis — in containers and writes a `.env` beside the app; **your application runs as host processes**, started from your IDE or shell. Four consequences follow, and they have caught every project tested so far. - **Do not document `docker compose up` for your application under `dev`.** Your README, your getting-started page and your useful-commands page must show the host-process form (`npm run dev`, `uvicorn …`, `cargo run`), because there is no application container to bring up. A README that says `docker compose up api worker beat` under a `dev` destination is describing a different destination; if you also support `type: compose`, label which commands belong to which. - **The port rule applies to the app you start yourself.** The derivation in *Avoiding port clashes* is not only for Compose: a front end pinned to bare `3000` in the README, the compose file or `.env.dev` collides with every other project on the developer's machine. Pin the derived port explicitly in the start command and the env file — for project `356`, `next dev -p 30356`, with the API on `80356` (folded into the dynamic range if it would exceed 65535). - **Changing your port needs no HAP change.** The shared test client accepts the standard framework callback paths on `localhost` at **any port** (§5 *Ready-to-run local environment files*), so moving the front end is an `AUTH_REDIRECT_URI` edit in your own env file and nothing else. Do not go looking for a registration to update; there isn't one to update. - **A split front end and API become two origins in `dev`, and only in `dev`.** In production the platform serves both from one host, so a project with an internal API often has no CORS layer, no absolute API base and no explicit front-end base URL — none of which it needed until now. Under `dev` they are `localhost:30NNN` and `localhost:80NNN`, two different origins, and three things break at once: - **The browser cannot reach the API.** Give the API a CORS allowance that is enabled only for the `dev` destination, or put a dev proxy in front (Next.js `rewrites`, Vite `server.proxy`) so the browser sees one origin. Do not ship a permissive CORS rule that survives into a cloud destination. - **Server-side fetches have no origin to be relative to.** A default API base of `/api/…` works in a browser and fails in a host process, where there is no page URL — every server render's API call fails, usually with a message about an invalid URL rather than about the base. Read an **absolute** API base from the destination's env file, and let the relative form be the browser-only special case. - **Server-side redirects land on the wrong origin.** A sign-in callback or a sign-out that redirects to `/` returns to whichever origin generated it — on the API, that is a JSON 404 that looks like a broken auth flow. Build every redirect from an explicit front-end base URL supplied per destination, never from a bare path. ### Labelling `docker-compose` services for the platform So that `wbsp list --provider compose` can see your locally-running stack and report it accurately, **label every service** in your `docker-compose` file with the platform identity from your `wbsp.yaml`: | Label | Value | Source | | --- | --- | --- | | `wbsp.tenant` | your tenant | `tenant:` in `wbsp.yaml` | | `wbsp.app` | your app name | `name:` in `wbsp.yaml` | | `wbsp.managed-by` | `wbsp-platform` | constant | ```yaml services: app: labels: - "wbsp.tenant=test" - "wbsp.app=music-rights-management" - "wbsp.managed-by=wbsp-platform" postgres: labels: - "wbsp.tenant=test" - "wbsp.app=music-rights-management" - "wbsp.managed-by=wbsp-platform" ``` Apply the **same** `wbsp.tenant`/`wbsp.app` pair to every service in the stack (web, database, redis, worker, …). The platform groups them into a single application row, derives `running`/`stopped` from whether the containers are actually up, and excludes unrelated Compose stacks that carry no `wbsp.app` label. Without these labels the platform cannot tell your stack apart from any other Compose project, so it will not appear in the application list. --- ## 3. Pre-deployment documents The following documents must be **created and kept up to date prior to any major milestone**. They are written for people who are *not* on your team and may have no access to our platform, so favour plain language over jargon. ### `/user-docs/api-reference.md` and `/user-docs/openapi.yaml` Required **if the project provides an API**. - `api-reference.md` must contain everything an unrelated project would need to consume this project's services — endpoints, authentication, request and response shapes, error handling, and examples. - `openapi.yaml` must describe the same API in valid [OpenAPI Specification (OAS)](https://www.openapis.org/) format. ### `/user-docs/testing.md` Explain, **in layman's terms**, the testing this project has been put through — what is covered and why it gives confidence. Then enumerate the **specific individual tests as an appendix** at the end of the file. ### `/user-docs/useful-commands.md` A summary of the commands and configuration an **application developer** needs: relevant CLI commands, configuration, and any AWS / EKS / database commands. - This document is **only** for app developers, who may not have control of or access to our actual platform. - **Do not** include anything about setting up the platform itself. - Do show the useful commands for `docker compose`, for deploying to AWS, and for running the parallel-services environment. - **Every command must be the one your project actually uses.** Write the commands for your own declared toolchain — if `package.json` names `packageManager: pnpm@…`, then every documented command is `pnpm`, not `npm`, in the README, the compose file and this page alike. A start command in the wrong package manager either fails outright or silently installs a second, divergent lockfile, and the reader has no way to know which was intended. ### `/user-docs/getting-started.md` Written in **layman's terms**, this is the front door to the project. It must: 1. Describe what the project does, including short explanations of things that might be assumed obvious (e.g. *what a monorepo is*) and any jargon or acronyms used. 2. Explain how a reader can experience the application — either for a real purpose or via a demonstration scenario. 3. Finish with a list of useful commands and pointers to other documentation in the project that might help. --- ## 4. Data stores: Postgres and Redis 1. The platform provides **PostgreSQL** and **Redis** when required. Applications should use these in preference to standing up their own data stores. Enable them through `wbsp.yaml`: - a dedicated database via `database.enabled: true`, and - a Redis store via `redis.enabled: true`. **Choosing a Redis mode.** Default to **cache mode** (`redis.enabled: true` with `durable: false`, the default) — it is provisioned on ElastiCache and is the right choice for caching, rate-limiting, sessions, and **retryable/periodic job queues**. Only set `durable: true` when your data must survive a node failure or restart (a persistent store rather than a cache); it is provisioned on MemoryDB and takes longer to create. > **Treat cache-mode Redis as ephemeral.** Anything in it — including queued > jobs — can be lost on a failover or restart. If you run a job queue (e.g. > BullMQ) on cache mode, design jobs to be idempotent and safely retried, and > do not use Redis as the system of record. If you cannot tolerate that, use > `durable: true` (or keep the source of truth in Postgres). When enabled, the platform injects connection details as environment variables (`DATABASE_*` and `REDIS_*` — including `REDIS_NAMESPACE`, the key prefix your app should use, and `REDIS_TLS`). Build your client from these discrete variables (there is no single `REDIS_URL`/`DATABASE_URL`). See [application-creator-guide.md](application-creator-guide.md) and [wbsp-yaml-reference.md](wbsp-yaml-reference.md). **This contract is identical across every deployment type.** Whether your app runs on `aws` or on any of the local-machine types — `compose` (whole stack in containers), `dev` (data services in containers, your app run from your IDE), or `standalone` (everything in one container) — it receives the **same** `DATABASE_*`/`REDIS_*` variables. Read those and your code needs no change between local and the cloud. (Local types reach the stores at `localhost` or the in-stack service name on derived ports; you never hard-code that — it comes from the variables.) **`wbsp db run` injects the same discrete `DATABASE_*` contract**, so a migration/seed script and the deployed app read identical variables. It *additionally* sets `DATABASE_URL` (pods never get one) as a convenience for tools that only accept a connection string — do not build application code around it. See "Connect to an app's platform database" in [useful-commands.md](useful-commands.md). 2. If your project needs **other backing services** (for example Forgejo, ClickHouse, and similar), provision them through the platform's **Parallel Namespace** facility rather than embedding them in your app. See [parallel-services-guide.md](parallel-services-guide.md). 3. **Evolve schema through migrations — never hand-edit a deployed database.** Manage your schema with versioned migrations checked into the repository (e.g. Prisma Migrate) and apply them as part of your deploy/release process. Never make ad-hoc, out-of-band changes to a deployed database — no manual `CREATE`/`ALTER`/`DROP` DDL, no hand-edited rows, no one-off SQL data fixes run by hand. Direct connections (e.g. `psql` via a port-forward) are for **inspection and debugging**; every schema or data change must flow through a migration or the application's own code so it is reviewed, versioned, and reproducible across all destinations. **ORM choice.** **Prisma is preferred** as the default ORM and migration tool. **Drizzle** is acceptable where it is required for performance reasons — either at **startup** (e.g. cold-start-sensitive environments such as Lambda) or at **runtime** (where specific optimised or customised SQL is required and Prisma's query layer is a poor fit). **TypeORM is discouraged.** If these guidelines cannot be followed for a given project, **ask permission and document the decision and reasons** (in the project's constitution, an ADR, or equivalent) so the choice is visible to reviewers and future maintainers. 4. **Your application must reach a usable first screen from empty storage.** The `release:` command in `wbsp.yaml` runs before your workload starts, on every install, against a database that may be brand new. **Migrations are not enough.** If a row must exist before a first user can be admitted — a default workspace, tenant, organisation, team, or role — create it there, **idempotently**, so re-running the release is harmless. An installed application is handed empty storage and its declared values, and nothing else. **There is no operator step between the image being pulled and the first page being served**, and nobody will run your seed script for you. A schema-only release is how an otherwise-compliant application ends up refusing every user it has just authenticated: the just-in-time path looks up the default workspace, finds none, and returns nothing. This applies equally to a **first administrator** — see §6 *"Do not invent your own administrator bootstrap"* for how to choose one without first-user-wins. --- ## 5. Environment configuration and secrets The platform delivers all configuration to your container as **environment variables**. Split configuration into three tiers — non-secret config, secrets, and per-destination overrides — so the same image runs everywhere and **no secret is ever committed**. > Configuration is delivered per **destination**. Each destination reads one > environment file — `.env.` — and the per-destination, never-layer > rules below apply to every destination. See > [wbsp-yaml-reference.md](wbsp-yaml-reference.md) for the full `wbsp.yaml` field > reference and worked examples. ### Non-secret config → `wbsp.yaml` `env:` Plain runtime settings (feature flags, log levels, public URLs) go in the `env:` map of `wbsp.yaml`. These are committed. You may override per destination under `destination..env:` (the destination wins over the base `env:`). ### Secrets → `wbsp.yaml` `secrets:` + a git-ignored `.env` **Never put secret values in `wbsp.yaml`.** Declare the secret env vars your app needs in a `secrets:` block **by reference** (the key to read), and put the actual values in a git-ignored `.env` beside `wbsp.yaml`: ```yaml # wbsp.yaml — declares WHICH secrets the app needs, never their values secrets: HAP_SMTP_PASSWORD: SES_SMTP_PASSWORD # env var the app receives : .env key holding the value HAP_ADMIN_API_KEY: HAP_ADMIN_API_KEY # (a key may reference itself) ``` ```dotenv # .env (git-ignored — never committed) SES_SMTP_PASSWORD=BICoEXAMPLE...realtoken HAP_ADMIN_API_KEY=… ``` At deploy the platform resolves each reference, stores the values in a protected secret object (not in the pod spec, not in git), and surfaces them to your container as the named environment variables. A declared secret with **no value fails the deploy** (fail-closed) — it never deploys silently unset. ### Per-destination values → `.env.` Each destination reads **one** environment file: `.env.` (e.g. `.env.prod`, `.env.dev`). When a value differs by destination — e.g. a real SES password on AWS but a dummy locally — supply the right value in each destination's file, keeping a single `secrets:` declaration: ```dotenv # .env.dev SES_SMTP_PASSWORD=dev-dummy # .env.prod SES_SMTP_PASSWORD=BICoEXAMPLE...realtoken ``` **Destinations never layer — each stays in its own lane.** A `.env.` is the *only* file consulted for that destination; it does **not** fall back to a bare `.env` or borrow from another destination's file. Every key a destination needs must live in that destination's own file. **Precedence** (highest first): 1. A real OS environment variable (operator override) 2. `.env.` (the single file for the selected `--destination`) ### Rules - Add `.env*` to `.gitignore` so real `.env.` files are never committed — but **do** commit `.env..example` templates (see below). Because `.gitignore` `.env*` also matches `.env.dev.example`, add an un-ignore rule: `!.env.*.example`. - No secret value may appear in `wbsp.yaml` or any committed file — with the one allowed exception below (the shared test-HAP credentials in the committed local `.example` templates). - Read every value (secret or not) from the environment; never bake config into the image. - This is a **stopgap**: today secret values come from your `.env.`. A future platform secrets manager will resolve the **same `secrets:` references** from a managed vault with no change to your app — so always declare secrets by reference, never inline. - Declare each value's **provenance** in `value_specs:` (feature 086 — see [wbsp-yaml-reference.md](wbsp-yaml-reference.md)): who supplies it (`operator` / `generated` / `destination`), whether it is optional, and its type. This is what lets an appliance or another platform install your app instead of refusing it, and what lets optional integrations (e.g. Google sign-in) degrade gracefully where nobody will ever configure them. An optional value that is not supplied is **entirely absent** from your environment — never present-and-empty — so test both states. ### The identity contract (destination-neutral names) Consume these names for authentication — every destination (the WBSP cloud, a wbsp-vm appliance, a future third-party platform) supplies the **same names for the same meanings**, so your app never needs to know where it is running: | Variable | Meaning | Provenance | | --- | --- | --- | | `AUTH_ISSUER` | OIDC issuer URL of the destination's identity provider. **Always tenant-scoped** — discovery is served only under `/t/{tenant}` (e.g. `https://hap.wbsp.ai/t/wbsp`); the bare host 404s. | destination (`kind: idpIssuer`) | | `AUTH_CLIENT_ID` | The OIDC client id registered for *this* application at *this* destination | destination (`kind: idpClientId`) | | `AUTH_CLIENT_SECRET` | Its client secret | destination (`kind: idpClientSecret`) | | `APP_URL` | The application's own public base URL: **scheme, host and port — no path, no trailing slash** (e.g. `https://myapp.wbsp.ai`). Derive any sub-path yourself. | destination (`kind: appUrl`) | | `AUTH_SECRET` | Session/JWT signing secret, stable for the install's life | generated | | `ENCRYPTION_KEY` | Data-encryption key — generated with `stable: true`: it is minted once and never rotated silently, so it is safe to encrypt persistent data with | generated | Declare the OIDC callback path your framework serves in the `auth:` block (`auth: { callbackPath: /api/auth/callback/hap }`) — destinations register it as your redirect URI **exactly**, and identity providers match it as an exact string. ### Ready-to-run local environment files Every project following these guidelines **generates the local-destination environment files pre-wired to the shared test HAP server**, so a developer can run and sign in immediately. Concretely, for each destination provide **two** files: - a **committed** `.env..example` template — no secret values, **except** the shared test-HAP credentials on the local destinations (`dev`, `prod-parity`, `standalone`), which are safe to share; and - a **git-ignored** `.env.` that is **as ready-to-run as possible** — for the local destinations, fully populated (including the test-HAP values) so the app runs with no manual edits; for cloud destinations (`stage`, `prod`), populated except for the managed secrets only your operator can supply, which are clearly marked. The three local destinations point at the shared test HAP server (issuer `https://hap.wbsp.ai/t/wbsp`, redirect `http://localhost:3000/api/auth/callback`). Like the shared demo client, the shared test client accepts the **standard framework callback paths** — currently `/api/auth/callback/hap` (Auth.js/NextAuth), `/api/auth/callback` (hand-rolled), `/login/oauth2/code/hap` (Spring) and `/signin-oidc` (ASP.NET) — on `localhost` at **any port**. So set `AUTH_REDIRECT_URI` to your framework's standard path on whatever port your app runs (e.g. `http://localhost:5173/api/auth/callback/hap`) and no HAP-side change is needed. A **non-standard** path (e.g. version-nested `/api/v1/auth/callback`) is not on the list and fails with `redirect_uri does not match a registered URI` — conform to a standard path. (Operators: the allow-list lives on the shared test client `hap_lIT7x7SZ30e898mr`; add a framework's path there once if a new one is ever needed.) **A placeholder for a paid third-party key is acceptable — silent degradation is not.** Nobody can put a real OpenAI or Stripe key in a committed template, and a local file carrying `sk-placeholder` is the honest state of affairs. What is not acceptable is discovering it at the point of use, three screens in, as a feature that quietly does nothing or returns an empty result. If your project ships a placeholder: - **Detect it at startup, not at call time**, and say so where someone will look: the health endpoint reports the feature as degraded and names the variable, or the first screen carries a plain line saying which capability is off and what to set. - **Name the variable in the README**, with what it costs and where to get one, so the developer can decide whether they need it before they hit the feature. - **Fail loudly in the cloud destinations.** A placeholder that reaches `stage` or `prod` is a misconfiguration; refuse to start rather than degrade. See [wbsp-yaml-reference.md](wbsp-yaml-reference.md) for the worked `wbsp.yaml` and the five per-destination `.env` examples. --- ## 6. Authentication If your project requires **user authentication**, prefer the platform's **Headless Auth Platform (HAP)** — an API-first, multi-tenant **OAuth 2.0 / OpenID Connect** identity service. Your app delegates login to it and receives standard OIDC tokens, so you do not build or operate your own credential store, password hashing, MFA, or session issuance. See also [single-tenant-guidelines.md](single-tenant-guidelines.md) for single-tenancy and shared sign-on (SSO) across a user's apps. **Integrate over standard OIDC**, through a well-supported OIDC client (e.g. Auth.js / NextAuth, or your language's OIDC library) rather than bespoke calls: - **Discover** endpoints from `${AUTH_ISSUER}/.well-known/openid-configuration`. - **Sign in** with the Authorization-Code + PKCE flow. One client covers every redirect-based mode — standard sign-in, SSO between sibling apps (so a user already signed into one app isn't asked again), and the optional **Hosted Login** mode where HAP hosts the login UI and your app ships none. - **Register your callback** at your framework's **standard** callback path — do not invent a custom or version-nested one (e.g. `/api/v1/auth/callback`). Typical values: `/api/auth/callback/hap` (Auth.js/NextAuth — it appends the provider id), `/api/auth/callback` (hand-rolled OIDC), `/login/oauth2/code/hap` (Spring), `/signin-oidc` (ASP.NET). Register that exact `${YOUR_APP_URL}/` with HAP for each non-demo destination (HAP matches `redirect_uri` by **exact string**). **On a hosted destination you cannot do this yourself** — your app's URL does not exist until the moment of installation, so the platform or appliance registers the client for you. **Declare the path instead**, in `wbsp.yaml`: ```yaml auth: callbackPath: /api/auth/callback/hap scopes: [openid, profile, email, offline_access] ``` **Whether anyone registers it for you depends on how the installation is deployed, so know which case you are in before you assume a client exists.** The platform registers a sign-in client, derives the callback from the domain given at deploy time and records the result, on the **image-install** path — `wbsp deploy --image`, into an operator-managed installation. On a **repository deploy to an ordinary cloud destination**, it does not: that installation's identity is deliberately yours, so the client must **already exist and already carry the exact callback** before anyone can sign in. Declaring `callbackPath` is right either way — on the first path it is what the platform registers, and on the second it is what you must have registered — but only the first one registers anything on your behalf. Getting this wrong surfaces late and confusingly: the deploy stops on unresolved identity values, or sign-in fails at the last redirect on a `redirect_uri` mismatch. - **Declare the OIDC scopes your client library requests.** Whoever registers the client also chooses its scopes, and on a hosted destination that is not you. If you ask for a scope the client was not registered with, the provider refuses the **entire** authorize request (`invalid_scope`) at the **last hop of sign-in** — after the user has typed their code correctly, in a redirect nobody inspects. Declaring the set moves that failure to publish time. - Omitting `scopes:` means `openid profile email`. That is enough for a plain sign-in and nothing else. - **Add `offline_access` if your framework wants a refresh token** — Auth.js and NextAuth request it by default, which is the single most common way this fails. - Add any provider-specific scopes your app genuinely uses. The list is not restricted to a fixed vocabulary; it is checked only for shape (`openid` present, one scope per list entry, no duplicates). - `wbsp deploy --dry-run` prints the set that will be registered, so you can read it before an install rather than diagnose it from a URL afterwards. - **Build the callback as `https://` behind the platform proxy.** The platform terminates TLS and forwards plain HTTP to your app, so make your framework honor `X-Forwarded-Proto` (e.g. Auth.js `AUTH_TRUST_HOST=true` + pinned `AUTH_URL`; uvicorn `--proxy-headers --forwarded-allow-ips=*`). An `http://` callback will not match the registered `https://` URI. - **Resolve identity** after the round-trip: HAP access tokens carry only the subject (`sub`), so your app runs its own "who am I" step (typically a `GET /me`) mapping the subject to your app's role/tenancy — see *"Make identity resolution resilient"* below. **Name your session cookies apart on a loopback address.** Three rules in this document are each right on their own and together guarantee a collision: local ports are **derived from the project number**, so several applications run on one host at once (§1); Next.js with a standard auth library is the **preferred stack** (§2), so those applications write the *same* cookie names by default; and `AUTH_SECRET` is **generated per install** (§5), so no two of them can open each other's cookie. A browser cookie is scoped to a **host, not a port** — `localhost:30045` and `localhost:30123` share one jar — so whichever application signed in last owns the name and the others are handed a cookie they cannot decrypt. - **The symptom does not resemble the cause.** It surfaces as a decryption or JWT error with a stack trace, on an application the developer may not even have been using. It reads as a broken install, and it is reported as one. - **On a loopback host, put the port in the cookie NAME, as a LEADING segment** — not only in the path, and not only in the value. The request cookie jar is a flat name-to-value mapping, so two cookies of the same name differing by path leave it arbitrary which one the server sees. `p30045.authjs.session-token` is the shape: `p.` prepended to whatever your framework's names are. - **Prepend it; do not append it.** An appended form (`authjs.session-token.30045`) is a *prefix extension* of the plain name, and Auth.js/NextAuth splits a session cookie too large for one header into `.0`, `.1`, … then reassembles it by collecting every cookie **whose name begins with the base name**. So an appended port is indistinguishable from a chunk index: an application still on the plain name collects its migrated neighbour's whole session as if it were a fragment of its own, and even two *migrated* applications collide whenever one port is a digit-prefix of the other (`3004` and `30045`). A leading segment is a prefix of nothing — the separator right after the number settles it — and it still lets an application find its own chunks. - **Rename every cookie in the sign-in round trip, not just the session** — the state, PKCE verifier and CSRF cookies are single-named too, so the callback collides even when the session does not. - **A deployed installation keeps the documented names.** It has a host to itself, and prefixed names (`__Secure-…`) and domain scoping behave differently. Condition the renaming on the address being loopback, not on a "development" flag. - **This is not a request to share one sign-on between your applications.** They are separate applications with separate sessions; single sign-on between them is HAP's job at the identity layer, not something to achieve by sharing a cookie. **A local sign-in bypass is expected — with hard limits.** Three steps of the build pipeline (UI fine-tuning, end-to-end testing, and walkthrough screenshot capture) run **unattended**, with no human to complete a login, and they **cannot complete without one**. So carrying a bypass is not a liberty a project takes; it is required of you. **It does not go through the identity provider — that is the whole point.** A real sign-in through the shared test client ends at a one-time code sent to an email address, which is exactly the step nobody is present to complete. The application stays *configured* against the shared test client, as every local destination is; the bypass establishes a local session directly for an identity the deployment has already declared, so it cannot grant a role that deployment did not declare. It must be: 1. **Environment-variable gated** — off unless the variable is set; and 2. **Local destinations only** — `dev`, `compose`, `standalone`, and **never** staging, production or any cloud destination. The code must make cloud activation **impossible**, not merely leave the variable unset there. Gating additionally on the application's own address being a loopback host is a good way to guarantee it. **The standalone image must ship with the bypass disabled.** The screenshot step enables it at `docker run` time through the same variable gate; the variable must never be baked into the image, Dockerfile, entrypoint or compose file, so the image a user actually evaluates requires a real login. The bypass exists only to unblock those three local unattended steps — nowhere else, and never enabled by default in a shipped artifact. None of this replaces real sign-in for a developer: the local `.env` files are pre-wired to the shared test client precisely so signing in works immediately (§5), and that remains the normal path. **Demo/sandbox destinations need no auth client secrets.** When your app is published to the reserved `demo` or `sandbox` destination, the platform injects the **shared demo OIDC client** into every instance at launch — `AUTH_HAP_ISSUER`, `AUTH_HAP_ID`, `AUTH_HAP_SECRET` and `NEXT_PUBLIC_HAP_ENABLED` — after your app's own env, overriding anything baked in (this is what signs a wbsp.ai visitor into the demo via silent SSO). So for the demo destination: do **not** declare OIDC client variables under `secrets:`, do **not** put real or placeholder values in `.env.demo`, and do **not** register a per-app client — have the app consume the `AUTH_HAP_*` variables (mapping them onto your auth library's names at startup if needed). **Silent SSO only happens if your application starts it.** The injected client is what *can* sign a wbsp.ai visitor in without a prompt, but nothing happens until your app begins the authorization request. So on demo/sandbox, an unauthenticated visitor must be redirected **straight to your sign-in start route**, with no in-app sign-in page in between. HAP then answers without a prompt when the visitor already holds a platform session, and shows Hosted Login only when they do not. An application that lands the visitor on its own `/signin` page and waits for a button never gives the silent exchange a chance: the demo "asks for a login", which is the one thing a demo must not do. Keep an in-app sign-in page only as the fallback for an installation with no identity provider configured. - **The symptom does not name the cause.** A demo that asks a signed-in visitor to log in looks like the platform failed to inject the client, and gets reported that way. It is almost always the application's own first hop. - **The way out is different here too.** The `Exit` item must not forward a demo visitor to HAP's exit endpoint — that ends the wbsp.ai session they arrived on. See *"A demo or sandbox is the exception"* under the user menu below. - **Exempt your auth routes, or you will build a redirect loop.** "Redirect every unauthenticated request" must not include the sign-in start route, the OIDC callback, your health endpoint, or static assets — the callback arrives unauthenticated by definition, so redirecting it sends the visitor round again. Exclude those paths explicitly rather than relying on ordering. You also **do not register any redirect URI** for demo/sandbox: the shared demo client already accepts the standard framework callback paths under the `*.wbsp-demo.com` wildcard host — currently `/api/auth/callback/hap`, `/api/auth/callback`, `/login/oauth2/code/hap`, and `/signin-oidc`. Use your framework's standard path (one of these) and your ephemeral demo URL (`-.wbsp-demo.com`) just works with no registration step. A **non-standard** path (e.g. version-nested `/api/v1/auth/callback`) is **not** on the list and fails with `redirect_uri does not match a registered URI` — conform to a standard path rather than expecting a one-off registration. (Operators: the allow-list lives on the shared demo client; add a framework's path there once if a new one is ever needed.) **HAP owns the authoritative client guidelines** (SSO-client, client cookbook, integration guide, hosted-login, and SSO-broker how-tos). They are the source of truth and may evolve, so obtain the current versions from your platform operator (or the [hap-docs](hap-docs) index page on this wiki, which links every HAP guide) and follow them rather than any copy here. For a ready-to-run local setup, the `.env.` examples in [wbsp-yaml-reference.md](wbsp-yaml-reference.md) are pre-wired to the shared test HAP server. If those guidelines **cannot be implemented**, or are **not appropriate** for your project, do not silently diverge: **tell the user the specific problem** and **document the proposed alternative** (what you will do instead, and why). **Integrate through a replaceable adaptor.** Authentication must sit behind a thin, swappable layer so the project can move to a different identity provider — or a different auth model entirely — with minimal work. Concretely: - **Use the standard OIDC interface, not HAP-specific code.** Talk to HAP via OIDC discovery (`${ISSUER}/.well-known/openid-configuration`) and the authorization-code + PKCE flow, using a well-supported auth library configured with a *provider* entry (e.g. Auth.js / NextAuth, or your language's OIDC client) rather than bespoke calls. - **Keep all provider specifics in configuration/secrets** (see §5), never hard-coded: issuer URL, client id/secret, scopes, claim mapping. Switching IdP should be an env/secret change plus a provider swap, not a rewrite. - **Confine sign-in/out, token validation, and session handling to one `auth` module** that the rest of the app depends on through a small, stable interface. An alternate model (a different OIDC IdP, a managed auth service, or SAML) must be a drop-in replacement behind that interface. - **Inject HAP's connection details** (issuer, client credentials) as platform config/secrets at deploy time; register your callback as `${YOUR_APP_URL}/`. This applies the platform's Adaptor-Based Integration principle to identity: depend on the **capability** ("authenticate a user"), not on a specific vendor. **Make identity resolution resilient — never let optional state break login.** HAP access tokens carry only the subject (`sub`), so your app has its own "who am I" step after the OIDC round-trip (typically a `GET /me` that maps the subject to the app's role/tenancy). That call is the **gate to the whole app**: if it fails, the user is bounced back to sign-in, and if it fails *repeatedly* they are stuck in a sign-in loop. Therefore: - **Identity resolution must depend only on the verified token**, never on optional request headers, query params, or persisted client state (e.g. a saved "view as"/impersonation selection, a remembered tenant/role, a feature flag). If such extra input is present but invalid or stale, **degrade to the base identity** — ignore it and resolve the real user — rather than returning an error from the identity call. - **Persisted client state can outlive the server.** Ids in `localStorage`/ `sessionStorage`/cookies survive redeploys and data reseeds; treat any stored id as possibly dangling. The server should tolerate it (fall back), and the client should **self-heal** (drop a selection the server reports as not applied) so it can't be re-sent and wedge the session. - **Absent required state is not the same problem as stale optional state, and the rule above does not cover it.** The bullets above are about extra input you can ignore — there is always a base identity to degrade to. If the thing that is missing is a row every identity *must* belong to (no default workspace, no tenant), there is nothing to degrade to and the user cannot be admitted at all. That case is prevented at install time, not handled at login: see §4.4 *"Your application must reach a usable first screen from empty storage."* - **Authentication failures may redirect; authorisation failures must render.** A user you have authenticated and then refused gets a **page** saying they do not have access and who to contact — never a redirect back toward sign-in. If your app knows why it refused (it usually does — it wrote a reason into the session), that reason must reach a human, not be thrown away at the last step. A refusal loop is indistinguishable from infrastructure failure and **will be reported to the platform team as an outage**; it is also just as good at hiding your own bug as at hiding ours. - **Diagnose loops by the identity call's status.** A sign-in page that just refreshes is almost always the who-am-I call failing. Check its status in the API logs: a repeating non-2xx on that one endpoint is the loop. Keep a short per-app login-troubleshooting note listing the known causes and their fixes. **Show who is signed in, and give them a way out.** If your application uses HAP and has a **top navigation bar** or a **left menu bar**, that bar carries a conventional **user menu** — unless there is a specific reason one does not belong (a kiosk display, a single-purpose embedded view). Users expect it, and its absence reads as an unfinished application. The menu must: - **Show who is signed in** — the current user's name, falling back to their email address when no name is available. Put it on the bar itself where there is room, not only behind the opened menu: a user who cannot tell which account they are in cannot tell that they are in the wrong one. - **Offer a profile / account item** where your application genuinely has something to show or let the user change. Skip it rather than add an item that opens an empty page. - **Offer one way out, labelled `Exit`, forwarding to `{hap-url}/t/{tenant}/exit`** (for the `twist` tenant, `{hap-url}/t/twist/exit`) — leaving your application and handing the user back to HAP, which owns what happens next. Build the URL from the HAP server your app is already configured against, and from the tenant it is configured for, rather than hard-coding either, so it stays correct on every destination: `AUTH_ISSUER` is already `{hap-url}/t/{tenant}`, so the exit URL is that value with `/exit` appended. If no HAP server is configured, leave the item out rather than link somewhere wrong. - **Canonical addresses, stated once.** `{hap-url}/t/{tenant}/exit` is the canonical exit address and `{hap-url}/t/{tenant}` (the tenant root) is the canonical selector address. Every other spelling in this section is a redirect to one of those two, kept by HAP on the terms below. Verified against `hap.wbsp.ai` on 2026-09-03: `/t/{tenant}/exit` is served, `/t/{tenant}/hosted/exit` answers `307` to it, and the `/menu` forms answer `307` to the tenant root. If a HAP page you read says otherwise, that page is the stale one — raise it, as §1 asks, rather than change your menu. - **`Exit` is the only way out — do not also offer a sign-out item.** HAP decides what leaving means and where the user lands. An application offering both a sign-out and an Exit presents two doors that behave differently for no reason the user can see. Label it `Exit`, not "Sign out" or "Log out". - **A demo or sandbox is the exception — never forward to `/exit` there.** A demo visitor did not sign in to your application; they arrived on the wbsp.ai session they were already holding, signed in silently through the shared demo client. Ending the HAP session therefore logs them out of **wbsp.ai**, not out of your demo — they browse a demonstration, click `Exit`, and find themselves signed out of the platform they came from, with nothing to explain why. Gate on `WBSP_SAMPLE_MODE`: either **omit the item**, or point it at `https://wbsp.ai` — the place they came from — **without** calling the exit or end-session endpoint. Prefer one of those two to a menu item that does nothing; an item that visibly does nothing when clicked reads as a fault, and a visitor will click it twice before deciding the demo is broken. - **End your own session first, then forward.** Redirecting without clearing your application's session leaves the user signed out at HAP and still signed in to you — they return and walk straight past your front door. Clear the session on your side, *then* redirect to the exit URL. Do not expect HAP to reach back into your application and do it for you. - **Deprecated — change them.** Earlier versions of this document pointed the user menu at an application-selection page instead. Every one of those forms is deprecated: `{hap-url}/menu/{tenant}`, `{hap-url}/t/{tenant}/menu` and `{hap-url}/t/{tenant}/hosted/apps`. So is `{hap-url}/t/{tenant}/hosted/exit`, the older spelling of the exit endpoint. All four still work — HAP keeps them as redirects, with no end date, and has said it will ask before withdrawing any — so an application that has not been updated is not broken; it is merely out of date. Change it to `{hap-url}/t/{tenant}/exit` when you next touch it. - **`{hap-url}/t/{tenant}/selector` never existed.** One earlier version of this document named it; HAP has never served it, so an application linking there has a broken `Exit` button today, not a deprecated one. Fix that now. - **The selector is not the Exit.** If your application genuinely offers "choose another application" as a distinct action — rare, and never a substitute for `Exit` — the application selector's address is the tenant root, `{hap-url}/t/{tenant}`. `{hap-url}/t/{tenant}/hosted/apps` is its deprecated older address, kept on the same terms as the others above. **A client id names a client within one tenant — nothing more.** Two applications in two different tenants, or on two different HAP installations, may legitimately carry the **same** client id: ids are unique per tenant, not globally, and from HAP's next release a caller may also **choose** the id it registers under (the platform's catalogue variant id, say) rather than take a minted one. Three consequences for anything you write that inspects a token: - **Validate the issuer, not the audience alone.** A HAP access token's audience is the client id, and that value no longer tells you which tenant or which installation issued it. The issuer does — it is `{hap-url}/t/{tenant}`, tenant and host in one string. Check it, and check it against the `AUTH_ISSUER` you were configured with rather than a pattern. Accepting on audience alone means a token minted by a different tenant, under a client that happens to share your id, passes your front door. - **Never use a client id as a database key, a tenant discriminator, or a filename.** It is neither unique nor stable enough to be any of those. Where you need a durable handle for a registration, use the application's internal uuid, which HAP returns at creation and never reissues. - **Deleting a registration frees its id for re-registration**, and tokens already issued to the deleted one stay internally well-formed until they expire. HAP refuses them for their full remaining life, but an app that validates tokens **locally** — signature and claims only, without asking HAP — cannot tell an old one from a new one, because id, tenant and issuer are all identical. If you validate locally, treat a deletion as taking effect one access-token lifetime later, or check revocation with HAP for that window. **If you ever create HAP invitations, send the tenant.** `POST /v1/invitations` is the only HAP endpoint that identifies an application without naming a tenant — the application authenticates with its own id and secret, and HAP has to find it by id alone, which shared ids can make ambiguous. Send `X-Tenant-Id`, whose value may be your **tenant slug** (the one already in your `AUTH_ISSUER`) or the tenant uuid. It is optional, and HAP refuses rather than guesses when it cannot resolve one application, so omitting it fails safe and loudly rather than quietly inviting someone into the wrong tenant. > **Live on `hap.wbsp.ai` since 2026-09-05.** An earlier version of this note > said these behaviours were built but not yet deployed; they shipped the same > day it was written. Verified 2026-09-08 against the served > `https://hap.wbsp.ai/openapi.json`: `client_id` is accepted on application > creation (and returned when listing), and it is absent from the update shape > because an identifier is create-only. So every rule above is load-bearing > now, not one day soon — in particular, **validate the issuer**: a client id > no longer identifies a tenant or an installation. **Do not invent your own administrator bootstrap.** Where the platform or the destination designates an administrator, map that designation to your application's admin role and provision everyone else with your ordinary default. Do not adopt **first-user-wins** — on a shared or appliance install it hands your application to whoever opens it first — and do not require an operator to run SQL to create the first admin (§4.4: there is no step between the pull and the first page). **Read the administrator claims HAP issues.** Every id token and every `userinfo` response from HAP carries two booleans, always present and needing no scope (live since 2026-08-13; HAP's `hap-administrator-claims.md` is the definitive contract): - `is_app_admin` — whether this user administers **this application** (the client the token was issued to). This is the designation to map to your application's admin role. - `is_tenant_admin` — whether this user administers the tenant. Do not treat tenant administration as application administration unless your application genuinely is a tenant-wide tool. Two rules when adopting them: - **`false` means "HAP says not an administrator", not "unknown".** If your application already holds administrators whose rights live only in its own database, reconcile before you let the claim demote anyone: promote them at HAP, or keep an explicit local grant that the claim cannot remove. Do not ship a change that silently strips existing administrators on the first sign-in after the upgrade. - **An absent claim is not `false`.** Both claims are emitted for every application, `true` or `false`, so a response with the field missing altogether is not an answer — it is a sign that something is not the identity provider you think it is: a cached document, a proxy stripping claims, or a different provider behind the same configuration. Treating absent as `false` fails closed in a way that looks exactly like a correct refusal, and the person locked out cannot tell anyone why. **Present-and-`false` is authoritative; absent is a fault to investigate.** - **Where there is no HAP** (an appliance install without an identity provider, or a destination that signs in another way), the honest fallback is still an **explicit declaration**: a `secrets:`/`env:` value naming the first administrator (their email or `sub`), consumed idempotently by your `release:` command. That is auditable, survives a reinstall, and cannot be claimed by a passer-by. **Where HAP *is* present, do not use that fallback** — it means an operator has to find and type someone's subject identifier into an env file to hand out a role the identity provider is already telling you about. - **Provision an ordinary user on first sign-in; never make them wait.** A user HAP has authenticated, for whom your application holds no row yet, is a new user — create the row and admit them with your default role. Do not park them on an "awaiting access" screen that only an operator can clear: on a shared or appliance install that turns every new colleague into a support ticket, and it is indistinguishable to them from being refused. Gate *privileged* actions on the claims, not the front door. - **On a local destination the claims mean less than they do in the cloud, so read both.** The `dev`, `prod-parity` and `standalone` destinations all point at **one shared test client** (§5), which every project on the machine signs in through. `is_app_admin` answers "does this user administer *this client*" — and on a client shared by every project, that is not a statement about your application at all. Do not build your admin mapping so that it works only if `is_app_admin` is true, or you will have no administrator locally while the same code is correct in the cloud, where your application has a registration of its own. Read **both** claims, treat `is_tenant_admin` as the designation where your destination uses the shared client, and log which claim admitted someone so the difference is visible rather than mysterious. *(Observed by two catalogue projects during local testing, 2026-09-05; the shared test client is an operator convenience, not a contract, so confirm against `hap-administrator-claims.md` before relying on any particular value.)* > **Corrected 2026-09-03.** An earlier version of this section said the > application-scoped claim was "coming, not yet available" and told projects > not to poll `userinfo` for it. That was stale: HAP shipped both claims on > 2026-08-13. A project that built an administrator bootstrap because of the > old text can replace it with the claim, keeping the reconcile rule above. --- ## 7. Logging The platform aggregates application logs and runs anomaly detection over them (the **LogWatch** platform). That analysis is only as good as the structure of the logs it receives, and unstructured logs degrade detection quality for *every* tenant sharing a service baseline — so log structure is a shared responsibility, not a per-team preference. The single most important rule: > **Emit machine-readable, structured logs whose fields map cleanly onto the > OpenTelemetry Logs Data Model — either as OTLP, or as JSON on `stdout`.** In practice, applications should: - **Log to `stdout`/`stderr`**, not to files on disk. On both EKS and Lambda the platform's collector tails your container output and forwards it — do not manage log files, rotation, or direct network shippers from your app. - **Emit one-line JSON per event**, with at least `severity_text` and `body`, plus `service.name`, `service.version`, and `deployment.environment` where available. - **Keep the message (`body`) stable and put variables in attributes** (e.g. `order.id`, `http.response.status_code`) so anomaly detection can group by message template. Use OpenTelemetry Semantic Convention names where one exists. - **Use UTC, RFC 3339 timestamps**, and include W3C `trace_id`/`span_id` when emitting inside a request context. - **Never log secrets, credentials, tokens, or unnecessary PII** — ingestion-time redaction is a backstop, not a licence. - **Prefer the platform's OpenTelemetry SDK/agent** and your language's recommended structured logger over a bespoke logging mechanism. These are recommendations; deviation is permitted (for sources that genuinely cannot emit structured output, vendored components, local development, and extreme hot paths) and should be documented in the project's constitution or an ADR. The same logging contract applies to any backing services you run through the platform's **Parallel Namespace** facility — their `stdout`/`stderr` is collected the same way, so emit structured logs there too. See [parallel-services-guide.md](parallel-services-guide.md). For the full field reference, per-language library recommendations, ingestion paths, and the conformance checklist, follow the [Client Logging Guidelines](logging-client-guidelines.md) — owned by the LogWatch log-aggregation project, which is the source of truth. Read it there rather than relying on any summary here: a copy of another project's specification can lag the service it describes. --- ## 8. Testing and test-driven development Projects on this platform are expected to follow **test-driven development (TDD)**. Write the test **first**: express the intended behaviour as a test, **run it and watch it fail**, then write the minimum code to make it pass, and refactor with the test still green (Red-Green-Refactor). The test exists before the implementation, not after it. TDD is **mandatory for the parts of a project where a silent defect is costly** — anything handling money, identity, authorization, data integrity, or other business-critical logic. Auth, in particular, must be developed test-first: if your project integrates the Headless Auth Platform (§6) or implements any credential, token, session, or access-control logic of its own, hold it to the stronger standard (HAP's own constitution makes test-first **non-negotiable** for that surface). In practice: - **Test behaviour, not implementation.** A test should describe what the code must do for a caller, so it survives refactoring. - **Integration tests run against real backing services**, not in-memory substitutes — use the platform's PostgreSQL and Redis (§4), or ephemeral containers (e.g. testcontainers), so tests exercise the same engines you deploy on. Mock only third-party HTTP you do not own. - **Keep tests fast and runnable with one command**, and wire them into your build so they run on every change. - **Record what is covered** in [`/user-docs/testing.md`](#user-docstestingmd) (§3) — the layman's summary plus the enumerated test appendix described there. **"Runnable" has a floor, and a green test suite does not reach it.** Before a project reports that it runs, **start it the way its own documentation says to and request a plain page or a health endpoint** — then read the log. A clean request must produce **no error**. This catches the whole family of faults that tests cannot, because the test suite never assembles the real runtime: a framework paired with a peer version it does not support (a Next release requiring React 19 against a pinned React 18 will throw on every server render, with a message that names neither package), a missing environment variable that only the server path reads, a native module built for the wrong architecture. The error these produce is usually misleading, so the cost of not looking is not one hour but several. If the log is noisy by design, say in `testing.md` which lines are expected, so the next person can tell a known warning from a new failure. **It is the project's call whether TDD fits a given piece of work.** If TDD **cannot be applied** or is **not appropriate** for some part of your project, the project must not silently skip it: **notify the user clearly** (which code, and why test-first does not fit — for example a spike, a generated client, a UI-layout concern, or an extreme hot path), **explain why**, and **document the proposed alternative** (what you will do instead — characterization tests written immediately after, manual verification with evidence, contract tests, etc. — and why it gives comparable confidence). The escape hatch is "explain and substitute", never "skip quietly". --- ## 9. Respect other projects' boundaries Each project owns its own repository. Stay strictly inside your own project and never reach into another one: - **Do not change files that belong to another project.** If you need to send a message, reply, or hand something off to another project, write it into your own `/notes/outbox`, from where the operator or the conductor copies it into the recipient's `/notes/inbox`. Treat another project's repository as read-only — including when you are unsure what a note meant. Ask in a reply; never go and look. - **`/notes` is the mailbox — keep it separate from your documentation.** `/notes` holds cross-project correspondence only: `inbox/` for what arrived and has not been acted on, `outbox/` for what you have written and not yet had carried, and the flat root as the archive of everything handled or sent (§1 `/notes`). `/docs` is your project's own internal documentation (design notes, contracts you own, schemas, roadmap), and `/user-docs` is your user-facing documentation. Never put mail in `/docs` or `/user-docs`, and never put your own documentation in `/notes` — a reader must be able to tell at a glance whether a document is something this project believes or something another project said to it. - **An outbound note is written, not sent.** It leaves your repository only when the carrier copies it, so never report a message as delivered, or a question as asked, on the strength of having written the file. - **Never run git operations on another project, and never deploy another project.** Committing, pushing, branching, or deploying outside your own repository is the operator's responsibility, not yours. - **Address the project that owns the thing — do not route through a third project.** If you need a fact about another team's API, ask *that* team, not a team that merely calls it; an answer relayed second-hand is a guess wearing a citation. Do not ask the platform to carry a question between two other projects either. A relayed question arrives with the asker absent, so nobody can ask the obvious follow-up, and every hop is somewhere a load-bearing detail gets lost by someone who did not know it was load-bearing. Write directly, and put the teams who have to agree in the same document. - **The exception is anything the platform actually owns**: these guidelines, the contracts under `specs/*/contracts/`, and any specification that must mean the same thing on every platform your app can be installed on. Two projects may agree something between themselves, but it is not agreed until it is in the contract — and that change comes to the platform. --- ## Quick checklist Before a milestone, confirm: - [ ] Explanations — in docs, decision records, status reports and conversation — describe observable behaviour and name nothing the reader would have to open the source to understand ("Explaining your work"). - [ ] Application code is under `/target` only — or, for a declared monorepo, under its root-level source trees (§1 "Monorepo projects"). - [ ] Research/planning docs are under `/initial-research`. - [ ] User docs are under `/user-docs`. - [ ] `wbsp.yaml` and `wbsp.Docker` exist **in the repository root** — not under `/target` (if the project is a website/service). - [ ] `wbsp.yaml` declares `variant: ` (convention: immediately before `name:`). - [ ] `wbsp.yaml` declares the reserved `universal: {}` destination (appliance publish opt-in; never `type`/`mode`/`tenant`/`cluster`/`enclave` under it). - [ ] If the project uses Next.js, APIs follow [nextJS-api-guidelines.md](nextJS-api-guidelines.md) (or any deviation has been approved by the user and documented). - [ ] Where a framework or language was actually chosen, Rust was among the candidates evaluated, and the recommendation weighed its benefits (memory, image size, attack surface) against the effort to build it (§2). - [ ] `docker-compose.yaml` provided for any services the project consumes. - [ ] `docker-compose` host ports derived from the project's numeric prefix (e.g. `30041`/`54041`) to avoid local clashes; internal ports unchanged. - [ ] Under a `dev` destination the app is documented as **host processes** (never `docker compose up` for the app itself), started on its **derived** port, and — if front end and API are separate — the browser reaches the API (CORS gated to `dev`, or a dev proxy), server-side fetches use an absolute API base, and server-side redirects use an explicit front-end base URL (§1 "Running under `dev`"). - [ ] Every `docker-compose` service labelled with `wbsp.tenant`/`wbsp.app` (from `wbsp.yaml`) and `wbsp.managed-by=wbsp-platform`, so `wbsp list --provider compose` can discover and reconcile the stack. - [ ] `getting-started.md`, `testing.md`, and `useful-commands.md` are current. - [ ] Every documented command uses the project's own declared toolchain — the package manager named in `packageManager`, not a different one — in the README, the compose file and `useful-commands.md` alike (§3). - [ ] `api-reference.md` + `openapi.yaml` exist (if the project provides an API). - [ ] Postgres/Redis enabled via `wbsp.yaml`; other services via parallel namespaces. - [ ] Database schema is managed by versioned migrations; no ad-hoc DDL or manual SQL is applied to deployed databases. - [ ] Application reaches a usable first screen from an **empty** database, with no manual step — the `release:` command idempotently creates whatever row a first user must belong to (§4.4). - [ ] The application has been **started from its own documentation and a plain page requested**, and the log shows no error on that request (§8). - [ ] A user who is authenticated and then **refused renders a page** saying so, never a redirect back toward sign-in (§6). - [ ] If the app uses HAP and has a top navbar or left menu bar, it carries a user menu showing the signed-in user's name or email, a profile item where there is one, and a single `Exit` item that clears the app's own session and then forwards to `{hap-url}/t/{tenant}/exit` — **except on demo/sandbox, where it must not forward there at all** — no separate sign-out item, none of the deprecated `/menu/{tenant}`, `/t/{tenant}/menu`, `/t/{tenant}/hosted/apps` or `/t/{tenant}/hosted/exit`, and never `/t/{tenant}/selector`, which does not exist (§6). - [ ] `auth.scopes` declares every OIDC scope the client library requests — including `offline_access` if the framework wants a refresh token (§6). - [ ] On a loopback address the app's session AND sign-in round-trip cookies (state, PKCE verifier, CSRF) carry the port as a **leading** segment of their name (`p30045.authjs.session-token`) — never appended, which the auth library cannot tell from a chunk index; a deployed installation keeps the documented names (§6). - [ ] Any local sign-in bypass is environment-variable gated, impossible to activate on a cloud destination, and NOT enabled in the standalone image (§6) — the pipeline's three unattended steps require one to exist. - [ ] On demo/sandbox an unauthenticated visitor is redirected **straight to the sign-in start route** — no in-app sign-in page in between — so the shared demo client's silent SSO can complete; the auth routes, callback, health endpoint and static assets are exempt from that redirect so it cannot loop (§6). - [ ] A demo/sandbox instance reaches **nothing outside its container** — no email, third-party API, webhook or data egress — gated on `WBSP_SAMPLE_MODE` rather than on a missing key, with the disabled feature explained in the interface and workers/schedulers inert (§1). - [ ] In a demo/sandbox the `Exit` item does **not** forward to HAP's exit endpoint (that ends the visitor's wbsp.ai session) — it is omitted, or points at `https://wbsp.ai` (§6). - [ ] No first-user-wins administrator bootstrap; the first admin is named by explicit configuration or a platform designation (§6). - [ ] Where HAP is present, an authenticated user with no row yet is **provisioned on first sign-in** with the default role — never parked on an "awaiting access" screen only an operator can clear — and the admin mapping reads **both** administrator claims, so it still designates an administrator on a local destination's shared test client (§6). - [ ] Secrets declared by reference in `wbsp.yaml` `secrets:`; values only in git-ignored `.env.` (never committed); `.env*` is in `.gitignore`. - [ ] Committed `.env..example` templates exist (no secrets except the shared test-HAP credentials on local destinations); `.gitignore` un-ignores them via `!.env.*.example`; local destinations (`dev`, `prod-parity`, `standalone`) are pre-wired to the test HAP server. - [ ] Any placeholder for a paid third-party key is **reported as degraded at startup** (health endpoint or first screen, naming the variable) and named in the README — never discovered as a feature that silently does nothing (§5). - [ ] If the project authenticates users, it uses the Headless Auth Platform via standard OIDC behind a replaceable `auth` adaptor (provider specifics in config/secrets, not hard-coded). - [ ] Code is developed test-first (TDD), mandatory for money/identity/authorization/data-integrity logic; where TDD is not appropriate the project has notified the user, explained why, and documented the alternative. - [ ] Logs are structured JSON on `stdout`/`stderr`, mapped to the OTel Logs Data Model, with no secrets. - [ ] `user-docs/website/index.html` is single-page, static, self-contained (if present). - [ ] No files in other projects were changed; messages to other projects were composed into this project's `/notes/outbox` (not `/docs`, not `/user-docs`) under the dated `YYYY-MM-DD--to--.md` name, `/notes/inbox` is empty or every note in it is accounted for, and no git or deploy operations were run on another project (§1 `/notes`, §9).