One place for a secret (Settings → App → Secrets this app uses)
Put a secret where it matches who may use it: on the new-app page or the
app's Environment (this app), an organization's page, or Settings →
Secrets (the whole forge). An app lists the names it needs in forge.json
("env": ["SIMPLEFIN_TOKEN"]); at start each arrives from the nearest place
that has it — the app, then the organization, then the forge — the last two
only after a forge admin grants that name to that repository (Settings →
App → Secrets this app uses, one click, revocable; the grant is the
repository's, so a repository with no app holds one too and its crew's runs
read through the same row; the table says
needs / has / missing). A guest's preview nobody approved receives none of
it. Setting a wider secret again restarts every app it was granted to, and
its row on the Secrets page lists them and whether each started with the
current value. A secret typed on the new-app page is the app's own at once
and the first issue names it, never its value. Every open is a secret.read
event (the app and environment, the name, never the value).
Replacing a secret
A secret's value is never shown back: not on the page, not in the API's
app/env answer, not in the MCP app_env list. Its row under Settings →
App → Environment shows the name, its scope and when it last changed, with
a password field and Replace beside it; type the new value and press
Replace (a same-origin POST to settings/app/env). The change is an
app.env_set event holding who and when, never the value. Replace is offered
on secrets only: a plain variable's value is printed in its row, so it is set
again with the form under the list.
In the terminal
From a repository that is an app, the palette offers Variables (src/tui/screens/appenv.ts: a sets one, choosing its scope and whether it is a secret or a variable, and setting an existing name again replaces its value; the list shows each kind and a variable's value, never a secret's) and Secrets this app uses (src/tui/screens/appsecrets.ts: needs, has, missing; a grants, x revokes, a forge admin only).
Code: src/core/app_secrets.ts, src/actions/secrets.ts (grantToRepo, revokeFromRepo), src/web/pages/app_secrets.ts. Tests: test/app-secrets.test.ts, test/app-secrets-value.test.ts, test/app-secrets-web.test.ts, test/guest-pull.test.ts.