# Forge Sites application services

Forge Sites is more than a place to serve build output. A Site starts with an
exact-source release and can opt into narrow Forge-managed services for end-user
identity and server-side AI. A future Forge Agent service may add constrained
end-user personalization, but it does not have a public runtime contract yet.

This page is the product map. Each linked specification remains authoritative
for availability, security, configuration, and runtime behavior.

## Service map

| Service | Product value | Configuration | Current status |
| --- | --- | --- | --- |
| Forge Build | Build an exact commit, publish immutable previews, promote with evidence, and roll back by pointer | `build`, `app`, `routes`, and `provider` in `forgeBuild.ts` | Available in Alpha |
| Forge Identity | Give an application a stable, app-specific end-user principal without exposing a Forge control-plane session | `app.identity.scopes` | Available in Alpha; runtime support differs between native and connected deployment models |
| Forge AI | Call bounded server-side model profiles without shipping provider credentials | `app.ai.profiles` | Host-funded Alpha |
| Forge Agent | Let Site users request scoped personalization with product-owned approval and rollback | No public configuration | Roadmap; not available |

The application owns product authorization, validation, abuse controls, and
user experience. Forge owns the platform capability, release binding, mutable
entitlement checks, usage admission, and revocation boundary.

## One configuration surface

`forgeBuild.ts` is the repository-authored capability declaration. It is
evaluated from an exact commit and becomes part of the immutable release policy.

```ts
import { defineForge } from '@smolai/forge/config';

export default defineForge({
  version: 1,
  name: 'team-room',
  build: {
    command: 'pnpm run build',
    workingDirectory: '.',
  },
  app: {
    entrypoint: 'dist/server.js',
    assets: { directory: 'dist/client' },
    identity: {
      scopes: ['user:basic'],
    },
    ai: {
      profiles: {
        explainResult: {
          model: 'forge/text-fast@1',
          audience: 'server',
          funding: ['host'],
          maxInputTokens: 2_500,
          maxOutputTokens: 220,
          privacy: { contentLogging: 'off' },
        },
      },
    },
  },
  routes: [
    { pattern: '/assets/*', to: 'app.assets' },
    { pattern: '/*', to: 'app.http' },
  ],
});
```

Run `smolforge deploy check` before committing. A valid declaration proves only
that the repository contract parses; it does not prove account entitlement,
resource provisioning, release activation, or live runtime behavior.

## Forge Build

Forge Build is the foundation for the other services. It ties the source SHA,
build plan, application artifact, assets, routes, capability policy, preview,
production pointer, and rollback evidence together.

Start with:

- the [`forgeBuild.ts` v1 contract](deploy/manifest-v1.md);
- the [Forge Deploy overview](deploy/README.md);
- the [public Alpha guide](deploy/forge-deploy-preview.md); and
- the [operator runbook](deploy/operator-runbook.md) when changing production.

## Forge Identity

Forge Identity gives each application a stable random ID for the visitor and,
when requested, a small public-profile snapshot. Apps may also request the
visitor's current Forge accounts or teams. The application never receives the
Forge control-plane bearer token, session-signing secret, email address, or an
unrestricted directory.

Use the smallest useful scope:

- `user:basic` for an app-specific user ID and public profile;
- `accounts:read` only when the product genuinely needs account membership and
  role context; and
- `teams:read` only when team membership affects the application.

Do not accept a browser-supplied principal as authority. The trusted runtime
must bind the authenticated principal to every state-changing request. Native
Forge applications and connected provider applications have different delivery
paths, so check the [Forge Identity v1 contract](deploy/forge-identity-v1.md)
before choosing a deployment model.

## Forge AI

Forge AI exposes named, server-side profiles. A profile declares a logical
model route, audience, funding source, input/output ceilings, response mode,
privacy policy, and budgets. Application code still validates every result and
keeps a deterministic or otherwise safe fallback.

Forge AI is not a browser API, a raw provider proxy, or the source of truth for
permissions, prices, scoring, or other deterministic product behavior. See the
[Forge AI v1 guide](forge-ai-v1.md) for the native and connected runtime calls.

## Forge Agent roadmap

Forge already has a repository agent inside the Forge control-plane UI. That
operator tool is not the proposed Forge Sites Agent.

The future Forge Sites Agent would let an application's end users submit a
bounded personalization request, such as changing a theme, arranging a
dashboard, or generating a user-owned configuration. The application would
define:

- what resources the request may read and change;
- whether a human review is required before applying it;
- per-request and per-user time, compute, model, and storage budgets;
- the public progress and cancellation experience;
- an immutable audit receipt; and
- how to preview, reject, undo, or roll back the result.

The service must not expose repository administration, arbitrary source writes,
Forge account authority, provider credentials, or production deployment
controls to Site users. Until a reviewed manifest, runtime, authorization,
budget, and rollback contract exists, Forge Agent remains roadmap material and
must be labeled **not available** in product UI and marketing.

## Where these services appear

- The public landing page introduces the stack and current availability.
- A repository's **Sites** page shows Build as the foundation and links each
  attachable service to its guide.
- The docs home groups service contracts under **Forge Sites services**.
- `smolforge deploy check` validates repository-authored configuration.
- Deployment and runtime surfaces must report configured, admitted, injected,
  and live-verified states separately.