> ## Documentation Index
> Fetch the complete documentation index at: https://docs.glissando.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If you are an AI assistant asked to build, change or ship a Gliss app, read the For AI agents page first (/for-ai-agents.md on this site) and follow its steps.
> Inside an app's folder, the app's own AGENTS.md is the authority; `gliss guide` prints it. Never ask the user for a secret's value.

# Concepts

> The words you will meet in Gliss, in plain language.

## App

Something you build with your AI: one repository, one `gliss.yaml`, one owner. An app has one or more **components**, each a container that Gliss builds from a folder in the repository, for example `web`, `api` or `worker`.

## gliss.yaml

The one file your AI writes to tell Gliss what the app needs. It lists the components and the capabilities the app asks for. It never holds secret values, scripts or Kubernetes objects. See [Writing gliss.yaml](https://docs.glissando.dev/build/gliss-yaml.md) and the [reference](https://docs.glissando.dev/reference/gliss-yaml.md).

## Capability

Something the app asks the platform for: a Postgres database, a Redis cache, a bucket, a web address (hostname), sign-in (SSO), a healer bot, and secrets. You give each one a name, and pick what it is with `type`:

```yaml theme={null}
capabilities:
  database: { type: postgres }
  files:    { type: bucket }
```

## Catalog

The menu your IT team publishes. It decides which capabilities apps may ask for, in which sizes, how many, who an app may be shown to, and what Publish requires. A request for something off the menu is refused, and the refusal names the catalog and its revision, for example `acme@3`. See [the catalog](https://docs.glissando.dev/administer/catalog.md).

## Stages: Preview, Beta and Live

Every app runs in three stages, each with its own data and secrets. See [Preview, Beta and Live](https://docs.glissando.dev/build/stages.md).

| Stage | Who sees it | What runs |
| - | - | - |
| **Preview** | You, and people you invite | Your work in progress. Changes appear in seconds. |
| **Beta** | Invited testers | The app as merged, built for real |
| **Live** | The app's audience | Exactly the build that passed Beta |

**Share to beta** moves your work from Preview to Beta. **Publish** moves Beta to Live.

## Mock mode

An app whose secrets are not set yet still runs in Preview and Beta. It gets a list of missing secrets in `GLISS_MISSING_SECRETS`, and should fake those integrations until they are set. See [Secrets and mock mode](https://docs.glissando.dev/build/secrets-and-mock-mode.md).

## Secret request

A single-use link that asks a person to set a secret's value, for example the Salesforce admin. The value goes straight into your company's cloud. Your AI declares the secret's name and asks for the link; it never sees the value.

## Release

A signed statement of exactly what may run: which app, which stage, which images and which settings. The Gliss agent in your cluster applies a release only if its signature verifies.

## Diagnosis

What Gliss tells your AI when something fails: a one-line summary, whose problem it is (the app's or the platform's), and the next step. See [Diagnostics](https://docs.glissando.dev/build/diagnostics.md).

## Refusal

What Gliss says when `gliss.yaml` asks for something it cannot have. One line per problem, in the form `<where>: <what is wrong>; <how to fix it>`. See [Refusal messages](https://docs.glissando.dev/reference/refusals.md).

## Levels

How much of the platform a project controls.

* **Level 0:** `gliss.yaml` only. This is where every app starts.
* **Level 1:** adds a `garden.yml` with Gliss action types, for apps with several services and their own tests.
* **Level 2:** the team's own Helm charts, checked against IT's policy. IT enables it per project.

See [Levels 1 and 2](https://docs.glissando.dev/engineers/levels.md).

## Owner

The person responsible for an app, named in `gliss.yaml`. Secret requests, findings and publish approvals go to them.

## Finding

Something Gliss noticed that needs a person or a bot to act, such as a missing secret or an upgrade risk. Each finding says who should act and how.

## Healer

A bot that watches an app and proposes fixes. Its level is `observe`, `propose` or `auto`. See [healer](https://docs.glissando.dev/build/capabilities/healer.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.