@@ -36,6 +36,7 @@ Bundled copies of every page on the SQLBuild documentation site, matching the in
 - [Schemas](concepts/models/schemas.md) (`concepts/models/schemas`) - Declare model columns inline or reuse canonical inherited schemas.
 - [Type Enforcement](concepts/models/type-enforcement.md) (`concepts/models/type-enforcement`) - Understand declared model types, static checks, and runtime casting.
 - [Contracts](concepts/models/contracts.md) (`concepts/models/contracts`) - Validate required or exact model output schemas.
+- [Model migrations](concepts/models/migrations.md) (`concepts/models/migrations`) - Keep the history of an incremental or snapshot model when you rename it.
 - [Hooks](concepts/models/hooks.md) (`concepts/models/hooks`) - Run SQL or Python lifecycle hooks around model materialization.
 - [SQL Hooks](concepts/models/hooks/sql.md) (`concepts/models/hooks/sql`) - Define, parameterize, compile, and invoke reusable or inline SQL lifecycle hooks.
 - [Python Hooks](concepts/models/hooks/python.md) (`concepts/models/hooks/python`) - Define Python lifecycle hooks with runtime context, providers, SQL access, and skips.
@@ -137,7 +138,7 @@ Bundled copies of every page on the SQLBuild documentation site, matching the in
 - [dag](cli/dag.md) (`cli/dag`) - Generate the static DAG artifact for Dagster and other integrations.
 - [query](cli/query.md) (`cli/query`) - Run ad hoc SQL queries against the project database.
 - [debug](cli/debug.md) (`cli/debug`) - Validate project configuration and test the warehouse connection.
-- [janitor](cli/janitor.md) (`cli/janitor`) - Clean up stale warehouse relations.
+- [janitor](cli/janitor.md) (`cli/janitor`) - Archive and then delete stale warehouse relations.
 - [clean](cli/clean.md) (`cli/clean`) - Remove compiled artifacts from the target directory.
 - [dbt](cli/dbt.md) (`cli/dbt`) - Coordinate dbt and SQLBuild projects.
 - [state](cli/state.md) (`cli/state`) - Manage the virtual mode state store.
 
@@ -2,13 +2,27 @@
 
 # janitor
 
-> Clean up stale warehouse relations.
+> Archive and then delete stale warehouse relations.
 
 Online: https://docs.sqlbuild.com/cli/janitor
 
+## Contents
+
+- Usage
+- Flags
+- Direct-mode lifecycle
+- Relation age
+- Audit record
+- Restoring an archive
+- Configuration
+- Examples
+- State history pruning
+- Virtual environments
+- Safety
+
 # sqb janitor
 
-Identifies and removes stale warehouse relations that are no longer part of the project. Requires `janitor.enabled = true` in `sqlbuild_project.toml`.
+Finds stale warehouse relations that are no longer part of the project, archives them, and deletes archives once they expire. Requires `janitor.enabled = true` in `sqlbuild_project.toml`.
 
 ## Usage
 
@@ -20,8 +34,61 @@ sqb --project-dir <path> janitor [flags]
 
 | Flag | Description |
 |------|-------------|
-| `--auto-approve` | Skip the confirmation prompt and delete immediately |
-| `--retention-days` | Override the configured retention period (days) |
+| `--auto-approve` | Skip the confirmation prompt and run the planned actions immediately |
+| `--retention-days` | Override the configured retention period (days) before a stale relation is archived |
+| `--direct-state-history-versions` | Override how many state-history versions are kept per identity |
+
+## Direct-mode lifecycle
+
+In direct mode, the janitor never drops a live relation directly. Each stale relation goes through two stages:
+
+1. **Archive.** Once a relation has been stale for `retention_days`, the janitor renames it in place, in the same schema, to:
+
+   ```
+   _SQB_ARCHIVE__<UTC timestamp>__<original name>
+   ```
+
+   For example, `stg_orders` becomes `_SQB_ARCHIVE__20260924T101500Z__stg_orders`. A rename copies no data, and keeps the relation's table type, grants and time travel.
+2. **Delete.** Once an archive is older than `archive_retention_days`, the janitor drops it.
+
+Stale relations are identified exactly as before. A relation is a candidate only if it is in a schema the project writes to, it is not produced by the current complete project, it was tracked by SQLBuild (when `delete_tracked_only = true`), it matches no exclude pattern, and it is older than the retention period.
+
+The age of an archive comes from the timestamp in its name, so deletion needs no other state. The janitor only deletes relations whose names **strictly** match the archive format and that are in a schema the project writes to. Names that only look similar are reported and never touched. The janitor also only acts on relations whose names are plain lowercase identifiers (letters, digits and underscores), and that don't collide case-insensitively with another relation in the same schema. Anything else is reported and left alone.
+
+Archive names are written as unquoted lowercase identifiers, so warehouses that fold unquoted names show them in their own case. On Snowflake, for example, the archive appears as `_SQB_ARCHIVE__20260924T101500Z__STG_ORDERS`.
+
+Long names are shortened with a short hash so they fit the adapter's identifier limit. The prefix and timestamp are never shortened.
+
+Setting both `retention_days` and `archive_retention_days` to `0` archives and deletes stale relations in the same run.
+
+## Relation age
+
+`retention_days` is measured from the last time a relation was written, as reported by the warehouse. For a relation the project no longer builds, that is roughly when it stopped being built.
+
+| Adapter | Age source |
+|---------|------------|
+| Snowflake | `INFORMATION_SCHEMA.TABLES` `CREATED` and `LAST_ALTERED`, which change on every write |
+| Databricks | `DESCRIBE DETAIL` `lastModified` for tables, and `INFORMATION_SCHEMA.TABLES` for views |
+| BigQuery | `__TABLES__` `creation_time` and `last_modified_time` |
+| PostgreSQL, SQL Server, DuckDB, MotherDuck | Not available |
+
+When the warehouse can't report a relation's age, the janitor skips that relation whenever `retention_days` is greater than `0`. SQL Server is in this group because its modification date ignores inserts and updates, so a recently written table could look old.
+
+Ages are only looked up for relations that are otherwise candidates, and not at all when `retention_days` is `0`.
+
+## Audit record
+
+Every archive and every delete is recorded in an append-only `_sqlbuild_janitor_events` table in the affected schema. It records the original name, the archive name, the time and the invocation. The janitor never reads this table to decide what to do. It exists for auditing, and for restoring archives whose names were shortened.
+
+## Restoring an archive
+
+Rename the archive back to its original name before it expires, using your warehouse's rename statement. For example, on Snowflake:
+
+```sql
+ALTER TABLE analytics._SQB_ARCHIVE__20260924T101500Z__stg_orders RENAME TO analytics.stg_orders;
+```
+
+If the archive's name was shortened, look up the original name in `_sqlbuild_janitor_events`. After an archive has been deleted, your warehouse's own time travel or undrop feature may still be able to recover it within its retention window.
 
 ## Configuration
 
@@ -30,20 +97,21 @@ Configure janitor behavior in `sqlbuild_project.toml`:
 ```toml
 [janitor]
 enabled = true
-retention_days = 30
+retention_days = 14
+archive_retention_days = 14
 delete_tracked_only = true
 exclude_patterns = ["audit_*", "tmp_*"]
 ```
 
-See [Project Configuration](../concepts/project-configuration.md) for details on janitor settings.
+When `retention_days` is not set, direct mode uses `14` and virtual-environment mode uses `30`. See [Project Configuration](../concepts/project-configuration.md#janitor) for every janitor setting.
 
 ## Examples
 
 ```bash
-# Interactive mode (prompts for confirmation)
+# Interactive mode (shows the plan and prompts for confirmation)
 sqb janitor
 
-# Auto-approve deletion
+# Run the planned archives and deletes without prompting
 sqb janitor --auto-approve
 
 # Override retention to 7 days
@@ -52,8 +120,12 @@ sqb janitor --retention-days 7
 
 ## State history pruning
 
-In addition to cleaning up stale relations, the janitor prunes old rows from `_sqlbuild_fingerprints` and `_sqlbuild_source_freshness` tables, retaining only the latest record per identity. This keeps state tables compact without affecting change detection.
+In addition to archiving stale relations, the janitor prunes old rows from `_sqlbuild_fingerprints` and `_sqlbuild_source_freshness`, keeping the latest `direct_state_history_versions` rows per identity (default `20`). This is configured separately from relation retention.
+
+## Virtual environments
+
+In virtual-environment mode, the janitor also cleans up expired environments, old checkpoints and unreferenced physical versions. See [Virtual environments: janitor](../concepts/virtual-environments/janitor.md). Direct-mode archiving doesn't apply there. In both modes, relations whose names differ only by case from another relation in the same schema are reported and never dropped, and exclude patterns match regardless of case.
 
 ## Safety
 
-Janitor prompts for confirmation before deleting. The confirmation requires typing an exact string to prevent accidental deletion. Use `--auto-approve` only in CI or when you're certain.
+The janitor shows every planned archive and delete, with exact names, ages and expiry, then asks you to type an exact confirmation phrase. Use `--auto-approve` only in automation, or when you're certain.
@@ -25,6 +25,7 @@ sqb --project-dir <path> plan [flags]
 | `--changes-only` | Virtual mode only: show work not already bound to its expected VDE version |
 | `--no-python` | Exclude read-side Python tasks and assets from the plan |
 | `--defer-to` | Resolve unselected model references against another target |
+| `--as` | Compile for another target and show its plan, including [model migration](../concepts/models/migrations.md) decisions, using the current connection. Inspection only. |
 | `--json` | Output the plan as JSON |
 | `--full-refresh` | Plan a full rebuild for selected models unless a model sets `full_refresh false`; `full_refresh true` forces a model without this flag |
 | `--start-cursor-ts` | Override start cursor for timestamp incremental models (ISO format) |
 
@@ -81,6 +81,8 @@ Table promotion mode is a project setting rather than a `MODEL()` field. Staged
 | `full_refresh` | Optional model execution override: `false` always runs incrementally, `true` always full-refreshes, and omission follows the command |
 | `on_schema_change` | `append_new_columns`, `sync_all_columns`, `ignore`, or `fail` |
 | `replay_on_change` | `forward`, `full`, or `bounded-<duration>` |
+| `migrate_from` | Old model name (or `schema.name`) whose data this model takes over; see [Model migrations](migrations.md). Also valid on snapshot models |
+| `migrate_force` | `true` replaces a destination that already has its own build history during a migration |
 
 See [Incremental](../incremental.md) for full semantics.
 
 
@@ -0,0 +1,90 @@
+<!-- generated-by: sqlbuild skills -->
+
+# Model migrations
+
+> Keep the history of an incremental or snapshot model when you rename it.
+
+Online: https://docs.sqlbuild.com/concepts/models/migrations
+
+# Model migrations
+
+Renaming an incremental or snapshot model normally means rebuilding it from scratch under the new name, which loses any history the source data can no longer reproduce. A model migration moves the existing relation's data to the new name instead, then continues building incrementally.
+
+Migrations apply to incremental and snapshot models in direct mode. Virtual-environment builds reject `migrate_from`.
+
+## Declaring a migration
+
+Add `migrate_from` to the renamed model's header, naming the old model:
+
+```sql
+MODEL (
+  materialized incremental,
+  migrate_from stg_orders,
+  cursor order_date,
+  ...
+);
+```
+
+Use `schema.name` when the old relation is in a different schema of the same database.
+
+On the next build, SQLBuild copies the old relation's data to the new name through a staging table (see [How a move runs](#how-a-move-runs)), records the move, and builds the model incrementally from the migrated state. There is no first-run rebuild, and no `replay_on_change` replay caused by the rename. The old relation is never modified or dropped. Once it is no longer part of the project, [janitor](../../cli/janitor.md) archives it like any other stale relation.
+
+After the move is recorded, `migrate_from` has no further effect, and SQLBuild tells you it can be removed. Keep it until every target that needs the move has built.
+
+## Decisions
+
+`sqb plan` shows the decision for every migration:
+
+| Decision | Meaning |
+|----------|---------|
+| `migrate` | The new relation doesn't exist. Move the old one's data to it. |
+| `done` | The move is already recorded. Nothing to do. |
+| `redo` | The new relation exists but has no build history and no recorded move, which is what an interrupted migration leaves behind. Move it again. |
+| `superseded replace` | The new relation was itself the origin of the latest recorded move, for example after renaming a model back. Replace it with the newer data. |
+| `forced replace` | The new relation has its own build history and `migrate_force true` is set. Replace it. |
+| `conflict` | The new relation has its own build history. The build stops (`M103`) until you set `migrate_force true` or remove `migrate_from`. |
+| `origin missing` | The old relation doesn't exist and no move was recorded. The build stops (`M102`). |
+
+The origin and destination must be compatible under the model's normal `on_schema_change` rules; otherwise the build stops (`M104`).
+
+`migrate_force true` only affects the `conflict` case and is safe to leave in the header.
+
+## Automatic discovery
+
+If a selected model has never been built, SQLBuild compares it with models that were removed from the project but whose relations still exist. When exactly one removed model has equivalent logic, it is migrated automatically. Equivalent means the same query and configuration, ignoring the model's own name, CTE and table alias names, comments, formatting, and storage-only settings. Renamed upstream models are matched first, so a renamed chain of models is migrated together. Removed models whose data was already moved on by a recorded migration are not candidates, so a model renamed several times matches its latest table.
+
+Renamed tables and views are matched the same way. They are still rebuilt under the new name, since they hold no history, but they keep their identity for change detection, so incremental models downstream of a renamed view are not replayed or rebuilt. These renames are recorded as `renamed` events.
+
+Automatic discovery never guesses. If a match is ambiguous, SQLBuild warns (`M107`) and builds from scratch; declare `migrate_from` to choose. An explicit `migrate_from` always wins. Automatic discovery covers renames within the project's schemas; use `migrate_from` to move a model to another schema. Relations last built before this feature carry no stored fingerprint and aren't matched automatically.
+
+## How a move runs
+
+A move never overwrites the destination directly:
+
+1. The old relation is cloned or copied into a new staging table named `_sqb_archive__<UTC timestamp>__migration_stage__<name>`, with the destination's configured table type.
+2. The staging table is checked: it must exist, have the expected columns and table type, and, for a physical copy, the same row count as the old relation.
+3. The staging table is swapped in as the destination. If a destination already existed, for example after `superseded replace` or `forced replace`, it is kept as `_sqb_archive__<UTC timestamp>__migration_previous__<name>` rather than dropped.
+4. The move is recorded, then the model builds as usual.
+
+The old relation is never modified. Staging and replaced tables use the [janitor](../../cli/janitor.md) archive format, so an abandoned staging table or a replaced destination is deleted by janitor after `archive_retention_days`. A staging table left by an interrupted run is never reused; the next run stages again. Don't run janitor at the same time as a build in the same schema.
+
+`sqb plan` shows how each move will run, for example `physical copy, transient -> permanent, promote by swap`.
+
+## State
+
+Each move is recorded in an append-only `_sqlbuild_migrations` table in the destination schema. A missing record means completion is unrecorded; staging or promotion may already have happened. Re-running after an interruption recovers through the migration decisions above.
+
+## Adapter support
+
+| Adapter | Staging | Promotion |
+|---------|---------|-----------|
+| Snowflake | Zero-copy clone with `COPY GRANTS`. Transient → permanent is a physical copy, because Snowflake can't clone a transient table into a permanent one. | `ALTER TABLE … SWAP WITH` for an existing destination; rename for a missing destination |
+| BigQuery | `CREATE TABLE … CLONE`, or `CREATE TABLE … COPY` when BigQuery refuses the clone | Two renames; the destination is briefly missing between them, and an interrupted run recovers on retry |
+| Databricks | `DEEP CLONE` | Two renames, as for BigQuery |
+| PostgreSQL, SQL Server, DuckDB, MotherDuck | Physical copy | Renames and the migration record in one transaction |
+
+On PostgreSQL, views that depend on the destination are re-pointed to the new table in the same transaction, keeping their options, owner and grants. Materialized views are not re-pointed.
+
+## Previewing another target
+
+`sqb plan --as <target>` compiles the project for another target, for example production, and shows its migration decisions using your current connection. It only inspects; nothing is written.
@@ -372,22 +372,28 @@ See [Macros](macros.md) for details on variable substitution and how variables i
 
 ## Janitor
 
-Configuration for the `sqb janitor` command, which cleans up stale warehouse relations:
+Configuration for the `sqb janitor` command, which archives and then deletes stale warehouse relations:
 
 ```toml
 [janitor]
 enabled = false
-retention_days = 30
+retention_days = 14
+archive_retention_days = 14
 delete_tracked_only = true
 exclude_patterns = ["audit_*", "tmp_*"]
 ```
 
 | Field | Default | Description |
 |-------|---------|-------------|
 | `enabled` | `false` | Whether janitor is active |
-| `retention_days` | `30` | Only clean relations older than this many days |
+| `retention_days` | `14` in direct mode, `30` in virtual-environment mode | How many days a relation must be stale before it is archived (direct mode) or cleaned up (virtual-environment mode) |
+| `archive_retention_days` | `14` | Direct mode only: how many days an archive is kept before it is deleted. `0` deletes it in the same run. |
 | `delete_tracked_only` | `true` | Only clean relations that appear in fingerprint tracking |
 | `exclude_patterns` | `[]` | Glob patterns for relations to skip |
+| `direct_state_history_versions` | `20` | How many state-history rows to keep per identity in `_sqlbuild_fingerprints` and `_sqlbuild_source_freshness` |
+| `max_checkpoints` | `20` | Virtual-environment mode: how many checkpoints to keep |
+
+See [janitor](../cli/janitor.md) for the archive and delete lifecycle.
 
 ## Scenario