Docs migrations

This is the kind of file your coding agent writes when it documents a new feature, updates a related page and adds the new page to the navigation:

<?php

use LaRecipe\Migrations\DocsMigration;

return new class extends DocsMigration
{
    protected string $set = 'handbook';

    protected string $author = 'claude-code';

    protected string $ref = '';

    protected string $summary = 'Document CSV exports';

    public function up(): void
    {
        $this->createPage('3.x/billing/exports', frontmatter: [
            'title' => 'CSV exports',
            'description' => 'Export invoices as a CSV file from the billing page.',
            'sources' => ['app/Billing/Exports/**'],
        ], body: <<<'MD'
            # CSV exports

            Open **Billing**, then choose **Export as CSV**.
            MD);

        $this->updatePage('3.x/billing/invoices', basedOn: 'sha256:9f3a2c…', frontmatter: [
            'title' => 'Invoices',
            'description' => 'Find, download and export your invoices.',
            'sources' => ['app/Billing/**'],
        ], body: <<<'MD'
            # Invoices

            Every invoice is on the billing page. To get them all at once, export them as CSV.
            MD);

        $this->updateNavigation('3.x', basedOn: 'sha256:51be07…', patch: [
            [
                'add' => 'billing/exports',
                'group' => 'Billing',
                'after' => 'billing/invoices',
            ],
        ]);
    }
};

The hashes are shortened here; a real one is sha256: followed by 64 hexadecimal characters. Page bodies are nowdoc strings indented with the code, so the pull request diff reads as Markdown. PHP removes the closing marker's indentation from every line, so the page gets exactly the Markdown you see.

LaRecipe\Migrations\DocsMigration extends Laravel's Migration. Four properties describe the change:

Inside up(), you call the operations. Each takes a page address: 3.x/billing/exports on a versioned set, 3.x/ar/billing/exports for a page in another language, billing/exports on an unversioned set.

Each operation goes through the same write path as every other change to a database set, as a migration with your $author and $ref. It is validated: content with validation errors, or an address that is not in the set, fails the migration, so CI catches a broken one before a deploy does. It publishes at once: the pull request was the review, in both review modes.

Docs migrations live in database/migrations/docs/, inside your app's migrations folder but apart from schema migrations, so a pull request shows the two kinds separately. Change the folder with migrations.path:

'migrations' => [
    'path' => database_path('migrations/docs'),
    'skip_in_tests' => false,
],

When any set uses the database source, LaRecipe registers this folder with Laravel's migrator. Every deploy already runs php artisan migrate, so there is no new step: migrate:status, migrate:rollback and migrate --path=database/migrations/docs work as for any migration. A docs migration for a set that no longer uses the database source is skipped and left pending.

There is one file per branch, named after it: on feature/csv-exports, database/migrations/docs/2026_10_17_141502_docs_feature_csv_exports.php. A set other than the default one adds its key: ..._docs_handbook_feature_csv_exports.php. Outside a git branch, the name ends in local. Each author tool's result names the file in docs_migration.

The file is rewritten as the session goes on, so the pull request carries one readable file instead of dozens. Changes to the same page fold together: a create then an update is one createPage, two updates are one updatePage that keeps the first basedOn, and a create then a delete leaves nothing (the file goes away when it is empty). The author is named after the MCP client, and the summary collects each call's one-line summary.

The file is logged in your local migrations table as already run, so a local php artisan migrate does not apply it twice, and a local php artisan migrate:rollback undoes the session. The larecipe-write-docs and larecipe-update-docs skills tell agents to commit it with the code.

basedOn is the content hash a change was written against. Your agent's tools fill it from your local database (the agent reads a page with read_page, which returns its content_hash, and passes it as based_on), and larecipe:make:docs-migration fills it from the set. On deploy, before each update, move, delete, navigation or manifest change, LaRecipe compares it with what is live. If production changed in between:

• The change is kept as a revision with the status conflict, holding the migration's version next to production's, at the top of the admin UI's review queue, where a person keeps production, takes the migration or edits a merge.
• DocsMigrationConflicted is dispatched.
• php artisan migrate prints a warning and carries on:

WARN LaRecipe docs conflict: [3.x/billing/invoices] The page [billing/invoices] changed since this change was written (expected sha256:9f3a2c…, found sha256:e41b07…). Kept as a conflict draft for review.

A createPage on a path that already has a page is a conflict too. An operation without basedOn skips the check and overwrites, so leave it in place.

php artisan migrate:rollback runs the built-in down(). It walks the migration's operations backwards and puts each one back as a new revision: a replaced page gets its earlier version back, a created page is removed, and a deleted page returns.

A rollback never clobbers a later edit either. If someone changed a page after the migration ran, the page keeps that edit, the rollback's version waits as a conflict draft, and the rollback reports it. A conflict the migration raised that nobody resolved is rejected.

In your app's test suite, docs migrations run like any other migration; they are small inserts. To skip them, set migrations.skip_in_tests to true: while tests run, docs migrations are then skipped and left pending.