.env.example

# tools/fetch-live-pack.mjs — runtime config
#
# Copy to .env (local dev) or feed via your secret store / Kubernetes Secret
# in cluster.  Source with: `set -a; source .env; set +a; npm run fetch-live`.
#
# Every OBSERVOGRAM_* knob also honors its pre-rebrand TOMOGRAPH_* spelling
# (tools/lib/brand-env.mjs); the new name wins when both are set.

# MCP server endpoint (JSON-RPC 2.0 over Streamable HTTP).
#
# Local dev (in-process MCP from krystalinex-core):
#   MCP_URL=http://localhost:3100
# In-cluster authenticated MCP (recommended for production refreshes):
#   MCP_URL=http://krystalinex-otel-mcp-server:3001
# In-cluster public MCP (no auth; restricted tool set, expect sparser pack):
#   MCP_URL=http://krystalinex-mcp-public:3001
MCP_URL=http://localhost:3100

# Bearer token for the authenticated MCP. Leave empty for the public/local MCP.
# In krystalinex-core's Helm chart this is `.Values.otelMcpServer.auth.agentKey`
# rendered into the `<release>-mcp-auth` Secret as `auth-keys.json`.
MCP_AUTH=

# Output path (relative to repo root).
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:
#
#   STAND-ALONE USERS   — the DEFAULT: first boot with nothing configured
#                         seeds a default admin/admin (change asked at
#                         every sign-in until it lands, skippable per
#                         session; never valid beyond loopback).
#                         Manage accounts with:
#                           npm run users -- add alice --name "Alice"
#                         Users live in the store (OBSERVOGRAM_DB below);
#                         `remove` disables. The session secret
#                         auto-generates into <workspace>/session-secret.
#   OPEN                — OBSERVOGRAM_AUTH=off: loopback, no login, no
#                         seeding — the pre-0.5 posture for dev shells/CI.
#   OIDC                — SSO against any OIDC provider (wins over stand-alone
#                         users). Requires the issuer + client id + a shared
#                         session secret.

# 'off' disables identity entirely (open posture; beats OIDC and stand-alone users)
#OBSERVOGRAM_AUTH=off

# First-boot seed password for 'admin' — skips the forced change; for
# docker/k8s where the loopback first sign-in is impossible. Also
# replaces an admin record that still holds the seeded default (never a
# real password), so a loopback-seeded workspace can move to the network.
#OBSERVOGRAM_ADMIN_PASSWORD=

# Legacy users file — an IMPORT SOURCE only: read once, at the first start
# of a store build, then hashed and never read again (npm run users writes
# the store). Default: <workspace>/users.json. An in-place
# `packc store export` writes it back for a rollback to a pre-store build.
#OBSERVOGRAM_USERS_FILE=.observogram/users.json

# OIDC single sign-on
#OBSERVOGRAM_OIDC_ISSUER=https://login.example.com/realms/main
#OBSERVOGRAM_OIDC_CLIENT_ID=observogram
#OBSERVOGRAM_OIDC_CLIENT_SECRET=            # omit for a public PKCE client
#OBSERVOGRAM_OIDC_REDIRECT_URL=https://observogram.example.com/auth/callback
#OBSERVOGRAM_SESSION_SECRET=                # >=32 chars; same on every instance
#OBSERVOGRAM_SESSION_TTL_HOURS=8
#OBSERVOGRAM_OIDC_ALLOW_HTTP=               # '1' only for local test IdPs

# OIDC: the first owner. '<issuer>#<sub>', or an email that counts only when
# the ID token says email_verified: true. Or name one later with
# `npm run users -- owner <login>`.
#OBSERVOGRAM_BOOTSTRAP_ADMIN=

# OIDC: the role a new IdP user gets in the default org — read at the FIRST
# start only (the store records it). viewer | operator | admin | none.
# Default without orgs.json: operator (every IdP user keeps access); set
# 'none' before the first start to keep the deployment closed. An owner
# changes it later with `PUT /api/admin/join-role` (admin needs
# "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
# first start of a store build, and never read again. Manage orgs with
# `npm run orgs` (they live in the store); a created org's root is
# <workspace>/orgs/<orgId>/, fixed at creation. More than one org needs
# identity. Clients pick the org with the X-Observogram-Org header (default:
# the user's first membership); the response echoes it.

# Service-account / CI access (works alongside either identity posture)
#OBSERVOGRAM_API_TOKEN=
#OBSERVOGRAM_API_TOKEN_LABEL=ci-bot

# Workspace root (journeys/, runs/, deploys.jsonl, packs/, observogram.db;
# legacy users.json / orgs.json until the first start imports them).
# Default: an existing .observogram/ (or pre-rebrand .tomograph/), else a
# fresh .observogram/. A scheduled journey (cron, schtasks, the k8s
# CronJob) MUST use the same root as the studio or its runs are never shown.
#OBSERVOGRAM_WORKSPACE=

# The embedded store (docs/STORE_PLAN.md): users, orgs, memberships and the
# audit, in one SQLite file per deployment on Node's built-in node:sqlite.
# The server opens it at every start, and its first start imports the legacy
# users.json / orgs.json: set it before that first start. Default:
# <workspace>/observogram.db. It must sit on local disk: NFS, CIFS,
# SMB and CephFS are refused, FUSE is warned about (WAL needs shared memory
# between the processes on one host). ':memory:' is for in-process tests
# and throwaway demos only: it forgets everything at restart, and the
# `packc store` commands refuse it. To move a database, move the file (with
# nothing holding it open): it carries its store_id. Back it up live with
# `packc store backup <path>`, never by copying the file while anything has
# it open (README, "Back Up And Restore The Store").
# Never roll the image back to a pre-store build without first running
# `packc store export <workspace>` (in place, server stopped); to come back
# after a pre-store build changed users or orgs, run
# `packc store import --replace` before the store build starts (README,
# "Upgrade And Roll Back").
#OBSERVOGRAM_DB=.observogram/observogram.db

# 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 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=
#
# 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