# SaC Authoring

`univer sac migration create` writes a draft `pack.ts` with `files: []`. The draft is intentionally empty. Before `apply`, add one or more `*.sheet.ts` files, list them in `pack.files`, and export the migration module.

## Migration Module Shape

`pack.ts` owns pack metadata and sheet execution order:

```typescript
import { defineFacadeMigrationPack } from "univer:sac/facade-migration-pack";
import type { FacadeMigrationModule } from "univer:sac/facade-migration-pack";
import revenue from "./revenue.sheet";

const pack = defineFacadeMigrationPack({
  id: "20260523090000-add-revenue-model",
  title: "Add Revenue Model",
  appliesAfter: null,
  files: ["revenue.sheet.ts"]
});

export default {
  pack,
  sheetMigrations: [revenue]
} satisfies FacadeMigrationModule;
```

The `files` list is authoritative. Every `*.sheet.ts` file in the pack directory must be listed, and files execute in that order.

## Sheet Migration Shape

Each sheet migration declares one primary sheet. `create: true` allows the CLI to create the sheet when it does not exist.

```typescript
import { defineSheetMigration } from "univer:sac/facade-migration-pack";
import rowsText from "./revenue.tsv";

const rows = rowsText
  .trim()
  .split("\n")
  .map((line) => line.split("\t"));

export default defineSheetMigration({
  sheet: { id: "revenue", name: "Revenue", create: true },
  apply({ sheet }) {
    sheet.getRange("A1:C4").setValues(rows);
  }
});
```

Put tabular seed data in CSV or TSV files when that keeps the migration easier to review. Referenced data assets are part of the source hash.

## Authoring Rules

- Keep one durable workbook intent per migration.
- Use stable sheet ids in `sheet.id`; use human-visible sheet names in `sheet.name`.
- Prefer one primary sheet per `*.sheet.ts` file.
- Use `univer:sac/facade-migration-pack` for helper types and definitions.
- Check `univer help sac facade-api` before using unfamiliar Facade APIs.
