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

# Projects, versions, and environments

> Publish reviewable source and select an immutable version for future sessions.

A project is the access and history boundary for one agent system. It owns source drafts, builds, environments, sessions, runs, and explicit member grants.

Create a project from the header's **Project → New project** menu and an environment from **Environment → New environment**. A new environment needs a promoted version before it can start a world.

## Source publication

Use either supported path:

* **Catalog draft:** select Tools and starting data, review **World and permissions** and **Files**, then **Publish version**.
* **CLI publication:** compile and package reviewed project source with the authenticated [publish command](/cli/reference#publish-source), then upload the bounded archive.

CLI publication does not upload the complete working tree, `.env` files, reports, or runtime data. Review the selected source and dependencies before publishing.

Publication queues a build. It does not create a session, launch your agent, or silently select a version for an environment.

## Immutable versions

A successful build has a content-addressed `sha256:` identity and exact Tool artifacts. The application calls these **Versions**. Change source to produce a new version.

New private executable Tool artifacts require explicit project approval. Review them in **Settings → Tool approvals**. Deprecation prevents new selection; revocation blocks affected execution paths.

## Promote an environment

Open **Versions**, select the version and destination environment, choose **Promote**, and confirm the environment name. This requires project-manager access.

Promotion changes the version used by future sessions. Existing sessions and sealed results retain their original build identity. Failed builds do not replace the selected version.

<Warning>
  A successful build means the source was accepted. It does not prove Tool fidelity, approve an artifact, execute the agent, or pass a drill.
</Warning>

## Repository source

Keep the source in your own repository. When repository integration is enabled, a connected repository supplies source identity for CI and authoring. Connecting a repository does not automatically publish or promote every push.

See [source organization](/guides/project-files) and [pull-request drills](/guides/pull-request-ci).