Promote develop to main: the store complete (slices 4–6), Settings, Windows CI, Compare in the bundle

.env.example

@@ -27,6 +27,23 @@ OUTPUT=examples/production-live.pack.yaml
 # Per-request MCP timeout in milliseconds (default 30000, capped at 300000).
 # OBSERVOGRAM_MCP_TIMEOUT_MS=30000
 
+# Transport hook (docs/MCP_INTEGRATION.md "Transport hook"): a module whose
+# prepareRequest({ url, headers }) and/or fetchImpl(url, init) shape EVERY
+# MCP request — fetch-live, record-fixtures, the live probes, journeys and
+# the studio server. A path (absolute, or relative to the working
+# directory) or a file: URL. Loaded once per process; a hook that fails to
+# load or breaks its contract is a hard failure (exit 1, nothing written;
+# the server refuses to start). Unset: inert.
+# OBSERVOGRAM_TRANSPORT_HOOK=./hooks/gateway.mjs
+
+# The MCP origin allowlist (README "Fetch Live From MCP"): comma-separated
+# origins the studio server may send a credential to — an endpoint's
+# server-held token, a caller's mcpAuth (every deploy), a credential in a
+# typed URL, or anything while a transport hook is loaded. Loopback always
+# passes. Unset: no credential leaves for any other origin. Per org:
+# OBSERVOGRAM_ORG_<ORG>_MCP_ORIGINS (unioned with this one). `*` = any.
+# OBSERVOGRAM_MCP_ORIGINS=https://otel-mcp.example.com
+
 # ---------------------------------------------------------------------------
 # Identity (docs/PRODUCTIZATION_PLAN.md Stage 1). Three postures:
 #
@@ -82,6 +99,49 @@ OUTPUT=examples/production-live.pack.yaml
 # "confirm": true); it applies to IdP users created after the change.
 #OBSERVOGRAM_OIDC_JOIN_ROLE=
 
+# Identity from a reverse proxy (README "Behind a reverse proxy"). Opt-in:
+# the proxy in front of this port terminates SSO and sends who the caller is
+# in headers; no cookie, no login page. Safe ONLY when clients cannot reach
+# this port — the ACK is a sentence you type once the proxy strips these
+# headers from every client request. Beyond loopback the shared secret is
+# required (the proxy sends it in the secret header). Users are recorded as
+# proxy://<realm>#<user> (kind oidc): `npm run users -- owner proxy://proxy#alice`.
+# Groups → roles are authoritative in OBSERVOGRAM_PROXY_AUTH_ORG (default
+# the default org); owner is grant-only. Refuses to start beside OIDC.
+#OBSERVOGRAM_TRUST_PROXY_AUTH=1
+#OBSERVOGRAM_TRUST_PROXY_AUTH_ACK=only-the-proxy-reaches-this-port
+#OBSERVOGRAM_PROXY_AUTH_USER_HEADER=X-Forwarded-User
+#OBSERVOGRAM_PROXY_AUTH_EMAIL_HEADER=X-Forwarded-Email
+#OBSERVOGRAM_PROXY_AUTH_NAME_HEADER=
+#OBSERVOGRAM_PROXY_AUTH_GROUPS_HEADER=X-Forwarded-Groups
+#OBSERVOGRAM_PROXY_AUTH_GROUP_ROLES=sre=admin,dev=operator,*=viewer
+#OBSERVOGRAM_PROXY_AUTH_ORG=
+#OBSERVOGRAM_PROXY_AUTH_JOIN_ROLE=none        # first-sight role when no groups header is configured; refused beside one
+#OBSERVOGRAM_PROXY_AUTH_OWNERS=
+#OBSERVOGRAM_PROXY_AUTH_SHARED_SECRET=        # >=32 chars; required beyond loopback
+#OBSERVOGRAM_PROXY_AUTH_SECRET_HEADER=X-Proxy-Auth-Secret
+#OBSERVOGRAM_PROXY_AUTH_LOGOUT_URL=
+
+# Rebadging (README, "Rebadge The Studio (brand config)"). One brand object
+# feeds the studio shell, the chrome, the sign-in pages and the design
+# tokens; unset, everything is Observogram and the shell is served byte for
+# byte. A JSON file (name, shortName, wordmark, tagline, titleSuffix,
+# description, logo {url|svg}, favicon, docsUrl, footer {text, links},
+# about {changelogUrl}, hero {src, alt}, tokens {light, dark}) and/or the
+# scalars below, which win over the file. One name derives every other
+# string. An unreadable or invalid file refuses the start. Also honoured by
+# `npm run build:studio` when `--brand` is absent (the file and the scalars).
+#OBSERVOGRAM_BRAND_FILE=./brand.json
+#OBSERVOGRAM_BRAND_NAME=
+#OBSERVOGRAM_BRAND_SHORT_NAME=
+#OBSERVOGRAM_BRAND_TAGLINE=
+#OBSERVOGRAM_BRAND_LOGO_URL=
+#OBSERVOGRAM_BRAND_DOCS_URL=
+#OBSERVOGRAM_BRAND_FOOTER=
+#OBSERVOGRAM_BRAND_ACCENT=
+#OBSERVOGRAM_BRAND_ACCENT_DARK=
+#OBSERVOGRAM_PROXY_AUTH_REALM=proxy
+
 # Tenancy (Stage 2 — workspace-per-org). No env var and no file: always on.
 # Every /api request runs in an org; a flat workspace is the default org, at
 # the workspace root. A legacy <workspace>/orgs.json is imported once, at the
@@ -124,10 +184,71 @@ OUTPUT=examples/production-live.pack.yaml
 # Run records kept per journey (oldest pruned after every run; 0 = unlimited).
 #OBSERVOGRAM_JOURNEY_RUN_RETENTION=1000
 
+# MCP read tokens an org's endpoints may name: OBSERVOGRAM_ORG_<ORG>_<NAME>
+# (ORG = the org id, upper case, - → _; NAME of [A-Z0-9_]+). An admin of an
+# org may name only its own (POST /api/mcp-endpoints { readTokenEnv }); the
+# server reads the variable at request time when POST /api/refresh-live or
+# /api/draft-from-mcp picks the endpoint by mcpEndpointId and the request
+# sends no mcpAuth. The owning org is the one whose prefix is the longest
+# match (OBSERVOGRAM_ORG_ACME_EU_X is acme-eu's, not acme's), so pick a
+# NAME that is not another org's id followed by _, nor a notify hook's
+# (OBSERVOGRAM_ORG_<ORG>_NOTIFY_<HOOK>_URL or _TOKEN, below — refused). Never
+# a write token: deploys and rollbacks take theirs per request. Set on the
+# studio (the k8s Deployment's env, from a Secret), never on the CronJob.
+#OBSERVOGRAM_ORG_DEFAULT_MCP_TOKEN=
+
 # A journey's own env-var names — packB.mcp.authEnv, notify.urlEnv,
-# notify.authEnv — are read literally (process.env[<name>]), not through the
-# OBSERVOGRAM_/TOMOGRAPH_ fallback: set exactly the names the journey file
-# declares, e.g.
+# notify.authEnv — are read literally by the CLI (packc journey run reads
+# process.env[<name>], not through the OBSERVOGRAM_/TOMOGRAPH_ fallback): set
+# exactly the names the journey file declares, e.g.
 #MY_MCP_TOKEN=
-#MY_JOURNEY_WEBHOOK_URL=
-#MY_JOURNEY_WEBHOOK_TOKEN=
+#
+# The studio server reads only the journey's org's own notify hook (README,
+# "Saved Journeys"; docs/DOWNSTREAM.md §17): notify.urlEnv must be
+# OBSERVOGRAM_ORG_<ORG>_NOTIFY_<HOOK>_URL (HOOK: words of A-Z and 0-9 joined
+# by single _) and notify.authEnv that hook's _TOKEN, or absent; any other
+# name refuses the server's run before anything runs (400), and capture
+# refuses it. Name the hook in journeys the studio also runs; the CLI reads
+# the same names. Set the pair here and restart; GET
+# /api/journeys/notify-hooks lists the org's hooks (never a value). Below,
+# the default org's hook ONCALL when its id is `default` (npm run orgs --
+# list).
+#OBSERVOGRAM_ORG_DEFAULT_NOTIFY_ONCALL_URL=
+#OBSERVOGRAM_ORG_DEFAULT_NOTIFY_ONCALL_TOKEN=
+#
+# The notify origin allowlist: comma-separated webhook origins
+# (scheme://host[:port]; `*` = any) a server-run journey may post to.
+# Loopback always passes. Unset: only loopback — a webhook off this machine
+# needs its origin here. Per org: OBSERVOGRAM_ORG_<ORG>_NOTIFY_ORIGINS
+# (unioned with this one). A separate list from OBSERVOGRAM_MCP_ORIGINS. An
+# http: origin carries the URL and the token in clear.
+#OBSERVOGRAM_NOTIFY_ORIGINS=https://hooks.slack.com
+
+# Artefact taxonomy override (README, "Classify Typed Packs"): a JSON file
+# mapping foreign artefact type names and id patterns onto Observogram's
+# families, so a pack from another toolchain gets the grouped Discover board
+# and the full compare. Read once at start; an unreadable or invalid file
+# refuses the start. Unset = Observogram's own families only. Also honoured
+# by `npm run build:studio` when `--taxonomy` is absent. Schema version 2
+# adds a `glossary` (definitions the studio shows beside family labels and
+# spec terms); a version 1 file stays valid.
+#OBSERVOGRAM_TAXONOMY=./taxonomy.json
+
+# MCP server-settings policy (rebadge batch 4): a JSON file of rules that
+# add friction to the studio's Server settings modal — a warning on a field
+# value that matches a pattern, and an acknowledgement ticked before the
+# send — and an optional `generic` block prefilling the generic form's path
+# and field names. `{ "version": 1, "rules": [{ "when": { "field" | "type",
+# "pattern", "flags"? }, "warn", "require"?: { "ack" } }], "generic"?: {...} }`,
+# strict (an unknown key is refused). Read once at start; an unreadable or
+# invalid file refuses the start. Unset = no policy.
+#OBSERVOGRAM_MCP_SETTINGS_POLICY=./mcp-settings-policy.json
+
+# The MCP server-settings pass-through (rebadge batch 4): `1` lets the
+# studio's Server settings modal send through the studio server
+# (POST /api/mcp-settings/describe and /submit, admin only) when the browser
+# cannot reach the MCP server or it sends no CORS headers. The studio server
+# then holds the typed settings for one request — never logged, kept or
+# audited by value — and passes back only the outcome shape. Read per
+# request. Unset (the default): the browser talks to the MCP server directly.
+#OBSERVOGRAM_MCP_ADMIN_PROXY=1

.gitattributes

@@ -1,3 +1,7 @@
+# Every text file is LF so goldens, fixtures and the vendor manifest's sha256
+# verify under any core.autocrlf (the rules below stay as the explicit list).
+* text=auto eol=lf
+
 # Vendored upstream spec files MUST remain byte-identical to upstream so the
 # sha256 checksums in vendor/observability-pack-spec/VERSIONS.json verify on
 # every platform. Force LF regardless of core.autocrlf.

.github/copilot-instructions.md

@@ -24,6 +24,9 @@ is the condensed, agent-facing version — when in doubt, those docs win.
   render the affected view, check the console) before the work is called done.
 - Conventional commit messages (`feat(server): …`, `fix(studio): …`,
   `docs: …`) whose body says *why*, not just what.
+- A red CI leg on develop, Linux or Windows, is fixed forward or reverted
+  within a working day; the summary at the end of the job's log names the
+  failure.
 
 ## Pinned sources of truth — edit the source, run its gate
 
@@ -37,16 +40,27 @@ them; change them at the source and update the gate in the same commit.
   fails the build. Changing the registry requires updating
   `EXPECTED_TOOL_SURFACE` in that guard in the same commit; the diff is the
   wire-surface changelog.
-- **Compiler and crawler output is golden-gated.** Any change to what the
-  crawler or a compiler *emits* must pass `npm run test:golden` (crawl) and
-  `npm run test:golden:compile` (per target, per version band). For intended
+- **Compiler, crawler and board output is golden-gated.** Any change to what
+  the crawler or a compiler *emits* must pass `npm run test:golden` (crawl)
+  and `npm run test:golden:compile` (per target, per version band); any
+  change to how artefacts are classified or grouped must pass
+  `npm run test:golden:board` (the Discover board and the artefact families
+  of every catalogue pack). For intended
   output changes, regenerate with the matching `:update` script in the same
   commit and explain the golden diff in the commit/PR description. An
   unexplained golden diff is a blocker, not a formality.
 - **Product/protocol version facts** live in the data tables
   `tools/lib/profiles.mjs` and `tools/lib/protocols.mjs`, each fact with an
   upstream `evidence:` reference. Do not scatter version checks or feature
   knobs into compiler code.
+- **The vendorable module surface** is `VENDOR-MANIFEST.json`, generated by
+  `npm run vendor-manifest` (`tools/gen-vendor-manifest.mjs`) and never
+  hand-edited. Changing a listed `tools/lib` module regenerates it in the
+  same commit; changing a listed module's *exports* also names the module
+  under `## Unreleased` in `docs/CHANGELOG.md` (path or backticked
+  basename) — `tools/test-vendor-manifest.mjs` fails the build otherwise.
+  A new module under `tools/lib` is listed or added to `EXCLUDED` with a
+  reason; the guard refuses neither. `docs/DOWNSTREAM.md` is the workflow.
 - **The vendored spec** under `vendor/observability-pack-spec/` is synced,
   never hand-edited: use `npm run sync-spec`; `npm run sync-spec:check`
   verifies SHA256 integrity and runs in CI.
@@ -58,18 +72,42 @@ them; change them at the source and update the gate in the same commit.
   `server/test-authz.mjs` fails the build on an unclassified, unguarded or
   unprobed route (add its probe to `PROBES`); a class change updates
   `EXPECTED_CLASS` there in the same commit.
-- **Identity rules:** every user, org, membership and join-role rule lives
-  once in `server/identity-admin.mjs`, applied by the CLIs (`npm run users`,
-  `npm run orgs`) and by the identity API (`server/routes/identity.mjs`,
-  with `surface: 'api'`, which changes only the way out a refusal names).
-  A refusal's `kind` (invalid / missing / conflict → 400 / 404 / 409) and
-  both surfaces' texts are pinned in `server/test-store.mjs`; never fork a
-  rule into a route.
+- **Identity and service rules:** every user, org, membership and join-role
+  rule lives once in `server/identity-admin.mjs`, applied by the CLIs
+  (`npm run users`, `npm run orgs`) and by the identity API
+  (`server/routes/identity.mjs`, with `surface: 'api'`, which changes only
+  the way out a refusal names); every service, environment and MCP endpoint
+  rule — the tier enum, the MCP URL word rule and the per-org
+  `OBSERVOGRAM_ORG_<ORG>_*` token variable, an MCP target picked by
+  `mcpEndpointId` — lives once in `server/service-admin.mjs` (over
+  `server/store/mcp-endpoints.mjs`), applied by `server/routes/services.mjs`
+  and the refresh, draft and deploy routes; the audit reader's query rule
+  — the scope by principal, every filter, the 500-row cap — lives once in
+  `server/audit-admin.mjs` (`GET /api/audit` in `server/routes/audit.mjs`;
+  `packc store audit` in `tools/store-admin.mjs` — the `cli` surface of the
+  same rule),
+  and the file-first routes write their row through
+  `server/audit-after.mjs`, after the file, never inside the operation. A
+  refusal's `kind` (invalid / missing / conflict → 400 / 404 / 409) and the
+  texts are pinned in `server/test-store.mjs`,
+  `server/test-service-admin.mjs`, `server/test-services-api.mjs` and
+  `server/test-audit-api.mjs`; never fork a rule into a route.
 - **Browser-safety rule:** modules under `tools/lib/` (including
   `tools/lib/contracts/`) are imported by the studio in the browser — they
   must not import `node:*` APIs or read `process.env`. Node-only code lives
   in `tools/*.mjs`, `server/`, or `tools/lib/journey.mjs` (the known
   exception).
+- **Studio conventions** (`docs/UI_CONVENTIONS.md`): views import
+  `studio/host.mjs`, never `app.mjs`; a journey's actions ride
+  `host.<namespace>` (`host.build`, `host.services`, `host.settings`); the
+  services and Settings loaders go through `requestJson()` /
+  `servicesRefusal()` in `studio/services-api.mjs` (never a bare `fetch`,
+  never a raw body in a status line); a `.svc-*` rule lives under the
+  `==== Services` marker and a `.set-*` rule under the `==== Settings` marker
+  in `studio/app.css`, which the AA scan in `tools/test-build-model.mjs`
+  reads; a secret (an MCP token, a password) is never logged, stored or put
+  in a title or link — the token is a server variable's name, and a temporary
+  password is shown once, in its dialog, and nowhere else.
 
 ## Git hygiene