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

# Builds, Files & Artifacts

> Understand the Starfire Developer Platform resource model for FORGE builds, files, packaged artifacts, and downloads.

# Builds, files & artifacts

FORGE-related developer resources are designed around asynchronous jobs and durable outputs rather than returning an entire generated project inside one oversized response.

## Builds

A build represents a FORGE software job. The v1 architecture is designed so a client can submit a build request, receive a build identifier, follow status or events, and retrieve resulting artifacts.

A build request can conceptually include:

* project goal or prompt
* model or routing preference
* project/repository context
* output requirements
* validation expectations
* packaging options

## Build status

A build can expose stages such as queued, planning, generating/modifying files, validating, repairing, packaging, completed, failed, or cancelled.

The final API status vocabulary is part of the active Alpha contract.

## Files

Files are developer-addressable inputs or stored objects used by other Starfire resources.

A file resource can be associated with:

* uploads
* projects
* knowledge ingestion
* build inputs
* research inputs
* artifacts or generated outputs

Uploading a file does not automatically mean it has been indexed into Knowledge.

## Artifacts

Artifacts are durable outputs produced by a build or other workflow.

A developer can use artifact metadata to discover what a build produced without requiring the build response to embed the entire output.

Conceptual operations include listing artifacts, reading artifact metadata, downloading an authorized artifact, and deleting an artifact when permitted.

## Checksums and integrity

When a build output includes a checksum, clients can use it to confirm that the downloaded bytes match the packaged artifact.

## Retention

Artifact and file retention can depend on plan, organization policy, storage limits, and platform configuration. A developer integration should not assume indefinite storage unless the applicable product contract says so.

## Ownership

Builds, files, and artifacts must remain attached to the correct personal or organization context so authorization and billing stay consistent.

<Warning>
  Do not design an integration around undocumented storage paths or internal object-store URLs. Use the documented Starfire resource and download contracts when those endpoints are enabled.
</Warning>

<Card title="FORGE architecture" icon="hammer" href="/forge/overview">
  Learn the human-facing build lifecycle behind these developer resources.
</Card>
