secrets/SKILL.md doesn't cover runtime-managed secrets that surface in gapp_secret_list

[krisrowe]

Problem

secrets/SKILL.md opens with this framing:

Secrets are declared in gapp.yaml's env section with a secret block

And the rest of the skill is built on that premise — the workflow ("Before Deploy", "After Deploy") assumes every secret a solution uses is declared in the operator's own gapp.yaml.

That premise is no longer complete. As of recent releases (3.0.5 / 3.0.6 land), gapp_secret_list and gapp_secret_get correctly surface secrets that the gapp deploy template wires up automatically when a solution falls into one of the runtime-managed code paths (e.g., the signing-key secret an mcp-app-style solution needs at runtime). These secrets:

• Are not declared in the operator's gapp.yaml
• Are created and managed by gapp itself during deploy
• Show up in gapp_secret_list / gapp secrets list exactly like operator-declared secrets do
• Are retrievable by short name with gapp_secret_get / gapp secrets get

The skill doesn't mention this class of secret at all. An operator reading the skill, or an agent following it, can come away believing a solution has no secrets when in fact runtime-managed ones exist. Even worse, an operator who needs the value of one of these secrets for an admin operation (e.g., retrieving a signing key to connect an admin client to a deployed instance) has no path through the skill that gets them there — they'd conclude they need to add a declaration to gapp.yaml, which would be wrong.

Proposed fix

Add a short subsection to secrets/SKILL.md covering runtime-managed (or runtime-injected — pick one term and stick with it) secrets. It should answer:

• What they are: secrets gapp creates and wires into the running container as part of deploying certain solution shapes, without operator declaration
• Where they come from: gapp's deploy template, based on the entrypoint mode the solution uses
• Why they don't appear in gapp.yaml: because the operator doesn't author them — the deploy machinery does
• How to interact with them: same MCP tools (gapp_secret_list, gapp_secret_get, etc.) and same CLI (gapp secrets list, gapp secrets get); same short names
• A pointer to the framework whose runtime needs the secret (mcp-app, etc.) so the operator knows what the value is for and where its lifecycle is governed

The subsection should be brief — operators encountering these secrets just need to know they're real, addressable, and not a bug. Detailed semantics belong in the framework's own docs (e.g., mcp-app), not in the gapp skill.

Context

Discovered while operating against a deployed solution from an agent session. The agent followed secrets/SKILL.md, called gapp_secret_list, and saw a signing-key entry it didn't expect. The skill gave no signal that this was normal — the agent had to read the deployed Cloud Run revision's env vars, then trace back through gapp's source (gapp/templates/Dockerfile, gapp/admin/sdk/core.py) to confirm that this is the deploy template wiring up a secret a framework-served entrypoint needs.

This investigation was avoidable. A two-paragraph note in the skill would have closed it in one read.

The skill does correctly cite both surfaces for retrieval (gapp_secret_get and gapp secrets get), so once an operator understands runtime-managed secrets exist, the rest of the skill works fine for them.

Work breakdown

• Add a "Runtime-managed secrets" subsection to secrets/SKILL.md (under "How Secrets Work in gapp" or as a peer section, whichever fits)
• Decide on terminology — "runtime-managed", "runtime-injected", or "deploy-template secrets" — and use it consistently
• Reference the framework whose runtime owns the value's semantics (mcp-app for the signing-key case), without duplicating that framework's docs here
• Update the "Before Deploy" / "After Deploy" workflow text where it implies all secrets come from gapp.yaml
• Add a short note in CONTRIBUTING.md so future skill edits remember runtime-managed secrets exist as a category
• If reasonable, add an integration or unit test that asserts gapp_secret_list includes runtime-managed entries for a representative solution shape — so a future regression that hides them again is caught immediately