# Deprecation Plan

_Last reviewed 2026-09-09._

This document defines the deprecation path from the original `videoclaw` (v0.11.x)
and the intermediate `vclaw-video-core` rebuild to **`videoclaw-v3`** — the
merged successor (npm package: `videoclaw`).

## Goal

Make `videoclaw-v3` the primary execution surface without pretending the
predecessor repos never existed.

## Current decision

Primary:

1. `videoclaw-v3` (npm: `videoclaw`)

Reference/fallback only:

1. `videoclaw` v0.11.x (the original repo) — legacy reference / migration source
2. `vclaw-video-core` — intermediate clean-room rebuild whose foundation was merged into videoclaw-v3

## Deprecation boundaries

What should stop growing in the old repo:

1. new user-facing workflow surfaces
2. new canonical artifact contracts
3. new reporting layers
4. new migration-target state models

What can still be consulted in the old repo:

1. legacy scripts
2. older provider behaviors
3. reference patterns not yet ported

## Cutover criteria

The clean repo is considered the primary product surface once these are true:

1. provider status works
2. produce / execute-status works
3. clone-execute works
4. template and prompt-library surfaces exist
5. migration docs exist
6. core tests are green

Those conditions are now satisfied.

## Remaining non-blocking work

1. richer provider-specific options
2. better automatic prompt guidance during execution
3. user education and release communication

## Operational policy

When a user asks to create or run video work:

1. prefer `videoclaw-v3` (`vclaw` CLI)
2. fall back to the legacy `videoclaw` v0.11.x runtime only when the missing feature is clearly identified
3. track every such fallback as a porting task

## Suggested release language

Use this internal framing:

1. `videoclaw-v3` (npm: `videoclaw`) is now the recommended runtime
2. `videoclaw` v0.11.x and `vclaw-video-core` remain available as migration/reference sources
3. old workflows should not be expanded further unless they are being ported

## Command lifecycle

Individual `vclaw video` commands and spellings follow a three-step ladder
that is encoded in the schema, not remembered:

1. **Declared alias.** A second spelling of a command is an `aliases` entry on
   the canonical `CommandSpec` in `src/video/cli-schema.ts` — one schema entry,
   one handler, and `src/tests/cli-dispatch-table.test.ts` fails on a dispatch
   key that shares a handler but is declared nowhere. Supported aliases
   (`execute`, `execution-plan`) print nothing and stay.
2. **Deprecated.** A whole command carries `deprecated: { since, replacement?, note? }`;
   one spelling carries `deprecatedAliases: [{ name, since, replacement?, note? }]`
   (an alias's replacement defaults to the canonical name). From that release,
   every invocation prints exactly one line to `stderr` —
   `vclaw: 'video X' is deprecated since <version>; use 'video Y'` when a
   command replaces it, `vclaw: 'video X' is deprecated since <version> and
   will be removed; <note>` when nothing does — and then runs unchanged — same stdout, same exit code — so agents reading JSON are
   never broken and `vclaw schema --json` shows the mark.
3. **Removed.** After at least one minor release with the notice, the dispatch
   key and the schema mark go together. A historical-only command (one that
   reads data an older release wrote — the legacy batch queue, `import-legacy`,
   `cinema-migrate`, `cinema-history-import`) needs a documented data-migration
   exit before step 3, not just the notice.

### Marked as of 3.0.0-alpha.13

Notice-only spellings (the canonical command is unchanged):
`template-create` → `template-save`, `clone-ad` → `clone-execute`,
`analyze-template` → `analyze`, `preflight` → `director-preflight`,
`library find` → `find-library`.

Deprecated commands (still run; removal needs the data-migration exit above
for the historical ones): `approve` → `produce --approve` (it forwards to the
one produce handler, adding `--mode director` when no mode is typed);
`batch-monitor` → `cinema-sync` and `batch-status` →
`cinema-status` (they only read a legacy `batch-queue.json`);
`candidates-migrate-from-assets` and `migrate-home` (one-shot consolidations,
honoured while there is still something to move); `import-legacy`,
`cinema-migrate`, `cinema-history-import` (historical-only imports with no
successor — they read what older releases wrote; `docs/MIGRATION.md` is the
path). `execute` and `execution-plan` are NOT deprecated: the product emits
them.

## Sunset rule

Do not archive or delete the old repo until:

1. migration of active users is complete
2. no critical workflow depends exclusively on the old runtime
3. the clean repo has been stable through multiple real runs