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

# Support policy (draft)

> Draft compatibility and support policy for a future stable line. Not yet in force.

**Draft, not yet in force.** Levelrail is pre-1.0 and nothing on this page is promised today. It states what the project intends to commit to when a stable line is cut, so the terms can be reviewed first. Until then, read [Feature status](https://docs.levelrail.com/feature-status.md) for what is proven and [Roadmap](https://docs.levelrail.com/roadmap.md) for what is open.

## What would be covered

Within one stable line (for example 1.x), these do not change in a breaking way:

| Surface | Covered | Where it is documented |
| - | - | - |
| REST API v1 | Routes, request fields, response fields and status codes | [API reference](https://docs.levelrail.com/api-reference.md) |
| REST API v2 | Resource shape, resource version and list and watch | [API v2](https://docs.levelrail.com/api-v2.md) |
| CLI | Command names, flag names, exit codes and `--json` output fields | [CLI reference](https://docs.levelrail.com/cli-reference.md), [CLI output](https://docs.levelrail.com/cli-output.md) |
| App spec | Documented fields and their meaning | [App spec reference](https://docs.levelrail.com/app-spec-reference.md) |
| Environment variables | Names and meaning of documented `APP_*` variables | [Environment variables](https://docs.levelrail.com/environment-variables.md) |
| On-disk upgrade path | Upgrading from the previous minor's latest patch, keeping data | [Upgrade compatibility](https://docs.levelrail.com/upgrade-compatibility.md), [Upgrade safely](https://docs.levelrail.com/upgrade-safely.md) |

Adding a field, route, flag or variable is not a breaking change. Removing or renaming one, or changing its meaning, is.

## What would not be covered

* Experimental and beta features, including everything behind `APP_EXPERIMENTAL`. See [Experimental features](https://docs.levelrail.com/experimental-features.md). They can change or be removed in any release, with a note in the changelog.
* Fields whose name starts with `x-`. They are for tooling and may change at any time.
* Undocumented routes, flags, variables and database tables. The SQLite schema is internal. Use the API.
* Multi-node and WireGuard mesh behavior while they are labelled beta in [Feature status](https://docs.levelrail.com/feature-status.md).
* Dashboard layout, copy and keyboard shortcuts.
* Generated pages such as the template catalog. Templates can be added, changed or retired.

## Deprecation window

A covered item that is deprecated stays for at least two minor releases after the release that deprecates it. During that time:

1. The item still works as before.
2. Using it produces a visible warning: a response header for the API, a line on stderr for the CLI, a log line at start for a variable or spec field.
3. The docs page for the item carries a deprecation note naming the replacement and the first release that may remove it.
4. The changelog lists it under the deprecating release.

A removal ships only in a minor release after the window, never in a patch.

## Security fixes

Proposed, to be confirmed before this policy takes effect:

* The latest stable minor gets security fixes as patch releases.
* The previous minor gets fixes for high and critical issues while it is inside its two-minor deprecation window.
* Older lines get no fixes. Upgrade.
* Fixes are announced in the changelog and the [advisory feed](https://docs.levelrail.com/advisory-feed.md). Releases stay signed.

Reporting a vulnerability is covered in the repository security policy.

## Upgrade path guarantee

These behaviors already exist and are tested by the upgrade harness described in [Upgrade safely](https://docs.levelrail.com/upgrade-safely.md#upgrading-real-releases-with-real-data). The policy would make them a promise:

* Migrations only go forward. After the baseline release, new migrations are additive (`go test ./internal/store` enforces it).
* A binary older than the database schema refuses to start, exits with status 78 and leaves the database unchanged. A downgrade through `self-upgrade --to` is refused too.
* Every upgrade takes a restore point first (database copy, binary, unit file). A failed health check puts the old binary and, when the schema changed, the old database back automatically.
* Upgrading is supported from the previous minor's latest patch. Skipping minors is best effort.

Not yet proven, so not promised: systemd and agent reconnection after an upgrade, and an upgrade on a live production host.

## Open questions

* Which release becomes the first stable line, and what evidence is required first (see the graduation criteria in [Experimental features](https://docs.levelrail.com/experimental-features.md#graduation-criteria-proposed)).
* Whether multi-node joins the covered surface at 1.0 or later.
* The exact warning mechanism for each surface.


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