### Pest Dataset Example

Source: https://github.com/trypostit/trypost/blob/main/GEMINI.md

Demonstrates using a dataset to test multiple inputs with the `with` method. Useful for reducing duplication when testing validation rules.

```php
it('has emails', function (string $email) {
    expect($email)->not->toBeEmpty();
})->with([
    'james' => 'james@laravel.com',
    'taylor' => 'taylor@laravel.com',
]);
```

--------------------------------

### Create a Pest test with plain name

Source: https://github.com/trypostit/trypost/blob/main/AGENTS.md

Example of creating a Pest test without the test suite directory prefix.

```bash
php artisan make:test --pest SomeFeatureTest
```

--------------------------------

### PHP Constructor Property Promotion

Source: https://github.com/trypostit/trypost/blob/main/GEMINI.md

Use PHP 8 constructor property promotion in __construct(). Example shows a public GitHub parameter promoted to a property.

```php
public function __construct(public GitHub $github) { }
```

--------------------------------

### Inertia Render Example (PHP)

Source: https://github.com/trypostit/trypost/blob/main/GEMINI.md

Use Inertia::render() for server-side routing instead of traditional Blade views. Place Inertia components in resources/js/Pages unless specified otherwise in vite.config.js.

```php
// routes/web.php example
Route::get('/users', function () {
    return Inertia::render('Users/Index', [
        'users' => User::all()
    ]);
});
```

--------------------------------

### Valid Flex Gap Spacing Example

Source: https://github.com/trypostit/trypost/blob/main/GEMINI.md

Use gap utilities for spacing when listing items, not margins. This example shows a flex container with gap-8 to space its children.

```html
<div class="flex gap-8">
    <div>Superior</div>
    <div>Michigan</div>
    <div>Erie</div>
</div>
```

--------------------------------

### Commit finalized workspace analytics rollout

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Stages and commits the configuration, environment example, application code, resources, specs, and tests after verifying the analytics backfill rollout. Run after confirming provider gates and before dispatching production rollout.

```bash
git add config .env.example app resources/js docs/superpowers/specs tests
git commit -m "chore: finalize workspace analytics rollout"
```

--------------------------------

### Use named routes in browser tests

Source: https://github.com/trypostit/trypost/blob/main/AGENTS.md

Always use the route() helper instead of hardcoded URLs in browser tests. Example: visit(route('login')).

```php
visit(route('login'))
```

--------------------------------

### Basic Pest Test Example

Source: https://github.com/trypostit/trypost/blob/main/GEMINI.md

A minimal Pest test using the `it` function and `expect` assertion. Use this as a template for writing unit or feature tests.

```php
it('is true', function () {
    expect(true)->toBeTrue();
});
```

--------------------------------

### Inertia v2 Vue Form Component Example

Source: https://github.com/trypostit/trypost/blob/main/GEMINI.md

Example of the <Form> component from Inertia v2 for Vue, showing how to handle form submission, errors, processing state, and success feedback. The component exposes several slots and props for managing form state.

```vue
<Form
    action="/users"
    method="post"
    #default="{
        errors,
        hasErrors,
        processing,
        progress,
        wasSuccessful,
        recentlySuccessful,
        setError,
        clearErrors,
        resetAndClearErrors,
        defaults,
        isDirty,
        reset,
        submit,
  }"
>
    <input type="text" name="name" />

    <div v-if="errors.name">
        {{ errors.name }}
    </div>

    <button type="submit" :disabled="processing">
        {{ processing ? 'Creating...' : 'Create User' }}
    </button>

    <div v-if="wasSuccessful">User created successfully!</div>
</Form>
```

--------------------------------

### Explicit Return Types and Method Params

Source: https://github.com/trypostit/trypost/blob/main/GEMINI.md

Always use explicit return type declarations and appropriate PHP type hints. Example shows a protected method with a User parameter, nullable string, and bool return type.

```php
protected function isAccessible(User $user, ?string $path = null): bool
{
    ...
}
```

--------------------------------

### Vue template event handler with argument

Source: https://github.com/trypostit/trypost/blob/main/AGENTS.md

Example of passing an argument to a named event handler function.

```html
@click="openEditDialog(label)"
```

--------------------------------

### GET /posts/{post}

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/specs/2026-09-24-independent-social-posts-design.md

Retrieves a single post. Operates on one post and rejects attempts to switch the destination.

```APIDOC
## [GET] /posts/{post}

### Description
Retrieves a single post. Operates on one post and rejects attempts to switch the destination.

### Method
GET

### Endpoint
/posts/{post}

### Parameters
#### Path Parameters
- **post** (string) - Required - The ID of the post to retrieve.

### Response
#### Success Response (200)
- **post** (object) - The requested post resource.

```

--------------------------------

### Use named routes in feature tests

Source: https://github.com/trypostit/trypost/blob/main/AGENTS.md

Always use the route() helper instead of hardcoded URLs in feature tests. Example with parameters: route('app.posts.ai.create.finalize', $creationId).

```php
$this->postJson(route('app.posts.store'))
```

--------------------------------

### Run browser tests in parallel with shards

Source: https://github.com/trypostit/trypost/blob/main/AGENTS.md

CI runs browser tests in three shards, each with three processes. Use ./vendor/bin/pest, not php artisan test --parallel, because the latter does not start the Playwright server.

```bash
./vendor/bin/pest tests/Browser --compact --parallel --processes=3 --shard=N/3
```

--------------------------------

### Pest Example Asserting postJson Response

Source: https://github.com/trypostit/trypost/blob/main/GEMINI.md

Shows how to assert a successful response from a POST request using `assertSuccessful` instead of `assertStatus`. Use specific assertion methods like `assertForbidden` and `assertNotFound` for status codes.

```php
it('returns all', function () {
    $response = $this->postJson('/api/docs', []);

    $response->assertSuccessful();
});
```

--------------------------------

### Pest Smoke Testing Example: Visit Multiple Pages

Source: https://github.com/trypostit/trypost/blob/main/GEMINI.md

A Pest 5 smoke test that visits multiple pages (home, about, contact) and asserts no JavaScript errors or console logs. Useful for quick sanity checks across routes.

```php
$pages = visit(['/', '/about', '/contact']);

$pages->assertNoJavascriptErrors()->assertNoConsoleLogs();
```

--------------------------------

### Pest Browser Test Example: Reset Password

Source: https://github.com/trypostit/trypost/blob/main/GEMINI.md

A Pest 5 browser test that visits the sign-in page, interacts with the UI to reset a password, and asserts the expected behavior. Uses Notification::fake() and model factories. The test clicks 'Forgot Password?', fills the email field, and asserts the success message.

```php
it('may reset the password', function () {
    Notification::fake();

    $this->actingAs(User::factory()->create());

    $page = visit('/sign-in'); // Visit on a real browser...

    $page->assertSee('Sign In')
        ->assertNoJavascriptErrors() // or ->assertNoConsoleLogs()
        ->click('Forgot Password?')
        ->fill('email', 'nuno@laravel.com')
        ->click('Send Reset Link')
        ->assertSee('We have emailed your password reset link!')

    Notification::assertSent(ResetPassword::class);
});
```

--------------------------------

### MetricValue typed DTO

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Defines the MetricValue DTO as a JSON boundary. It holds a key, value, unit, time basis, precision, availability, and optional provider metric, period start, and period end.

```php
final readonly class MetricValue
{
    public function __construct(
        public MetricKey $key,
        public int|float|null $value,
        public MetricUnit $unit,
        public MetricTimeBasis $timeBasis,
        public MetricPrecision $precision,
        public MetricAvailability $availability,
        public ?string $providerMetric = null,
        public ?CarbonImmutable $periodStart = null,
        public ?CarbonImmutable $periodEnd = null,
    ) {}
}
```

--------------------------------

### Create a new Maizzle project with create-maizzle

Source: https://github.com/trypostit/trypost/blob/main/maizzle/README.md

Run this command and follow the prompts to scaffold a new Maizzle project. Requires Node.js and npm.

```bash
npx create-maizzle
```

--------------------------------

### Run all tests compactly

Source: https://github.com/trypostit/trypost/blob/main/AGENTS.md

Run the full test suite with compact output.

```bash
php artisan test --compact
```

--------------------------------

### Run browser test and frontend checks

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Commands to run the browser test, lint, type-check, and build the frontend. Expected to pass after implementation.

```bash
php artisan test --compact tests/Browser/WorkspaceAnalyticsTest.php
npm run lint
npx vue-tsc --noEmit
npm run build
```

--------------------------------

### Run job and schedule tests (Step 5)

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Runs both the publication metrics job tests and the analytics schedule tests. Expected to pass after implementation.

```bash
php artisan test --compact tests/Feature/Analytics/PublicationMetricsJobsTest.php tests/Feature/Analytics/AnalyticsScheduleTest.php
```

--------------------------------

### Format and commit changes (Step 6)

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Formats the code with Pint and commits the new and modified analytics files.

```bash
vendor/bin/pint --dirty --format agent
git add app/Jobs/Analytics app/Console/Commands/Analytics routes/console.php tests/Feature/Analytics
git commit -m "feat: schedule persisted publication metrics"
```

--------------------------------

### Run tests and frontend checks (Task 15 Step 5)

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Runs the analytics controller, browser, and post content type tests, then lints and type-checks the frontend. Expected to pass after implementing the controller and shared presentation component.

```bash
php artisan test --compact tests/Feature/Analytics/AnalyticsPublicationControllerTest.php tests/Browser/PublicationAnalyticsTest.php tests/Browser/PostShowContentTypeTest.php
npm run lint
npx vue-tsc --noEmit
```

--------------------------------

### Run targeted and full verification commands

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Run linting, tests, typecheck, and build to verify the analytics changes. Expected: all pass.

```bash
vendor/bin/pint --dirty --format agent
php artisan test --compact tests/Feature/Analytics tests/Feature/Services/Social tests/Feature/Observers tests/Feature/Mcp tests/Browser/WorkspaceAnalyticsTest.php tests/Browser/PublicationAnalyticsTest.php tests/Feature/LocalizationParityTest.php
npm run lint
npx vue-tsc --noEmit
npm run build
php artisan test --compact
```

--------------------------------

### Run Pint to fix formatting

Source: https://github.com/trypostit/trypost/blob/main/AGENTS.md

Run Pint without `--test` to automatically fix formatting issues in the project.

```bash
vendor/bin/pint --format agent
```

--------------------------------

### Run schema tests on the configured database

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Executes the AnalyticsSchemaTest to verify the database schema. Expected to pass.

```bash
php artisan test --compact tests/Feature/Analytics/AnalyticsSchemaTest.php
```

--------------------------------

### Run reconciliation tests

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Runs the reconciliation and observer tests with compact output. Expected to fail in Step 2 because catalog actions/jobs are absent, and pass in Step 5 after implementation.

```bash
php artisan test --compact tests/Feature/Analytics/PublicationReconciliationTest.php tests/Feature/Observers/PostPlatformObserverTest.php
```

--------------------------------

### Run the writer test and verify it fails

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Executes the AnalyticsObservationWriterTest. Expected to fail because the models and writers do not exist yet.

```bash
php artisan test --compact tests/Feature/Analytics/AnalyticsObservationWriterTest.php
```

--------------------------------

### Format and commit backfill changes

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Formats the code with Pint and commits the changed files with a descriptive message.

```bash
vendor/bin/pint --dirty --format agent
git add app/Jobs/Analytics app/Console/Commands/Analytics app/Actions/Analytics app/Observers/SocialAccountObserver.php routes/console.php tests/Feature/Analytics tests/Feature/Observers/SocialAccountObserverTest.php
git commit -m "feat: backfill native analytics through jobs"
```

--------------------------------

### Test: CreatePosts returns four posts with one enabled platform each

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-24-independent-social-posts.md

Failing test for Task 2 Step 1: verifies CreatePosts::execute returns four posts, each with exactly one post platform and one enabled platform. Used to validate atomic creation across four accounts/posts/enabled targets.

```php
$posts = CreatePosts::execute($workspace, $user, $composition);
expect($posts)->toHaveCount(4);
foreach ($posts as $post) {
    expect($post->postPlatforms()->count())->toBe(1);
    expect($post->postPlatforms()->enabled()->count())->toBe(1);
}
```

--------------------------------

### Create a Pest test

Source: https://github.com/trypostit/trypost/blob/main/AGENTS.md

Create a new Pest test file. The `{name}` argument should not include the test suite directory; use a plain name like `SomeFeatureTest`.

```bash
php artisan make:test --pest {name}
```

--------------------------------

### Run backfill tests

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Executes the PHPUnit tests for the backfill jobs, command, and observer. Expected output is PASS.

```bash
php artisan test --compact tests/Feature/Analytics/PublicationBackfillJobsTest.php tests/Feature/Analytics/BackfillExistingAnalyticsCommandTest.php tests/Feature/Observers/SocialAccountObserverTest.php
```

--------------------------------

### Generate models, factories, actions, and the failing writer test

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Runs artisan commands to create the necessary models, factories, DTOs, actions, and a test. The test is expected to fail initially because the models and writers do not exist yet.

```bash
php artisan make:model AnalyticsAccountDailySnapshot --factory --no-interaction
php artisan make:model AnalyticsPublication --factory --no-interaction
php artisan make:model AnalyticsPublicationDailySnapshot --factory --no-interaction
php artisan make:model AnalyticsSyncState --factory --no-interaction
php artisan make:class Dto/Analytics/AccountDailyObservation --no-interaction
php artisan make:class Dto/Analytics/MetricValue --no-interaction
php artisan make:class Dto/Analytics/PublicationMetricObservation --no-interaction
php artisan make:class Actions/Analytics/ResolveAnalyticsAccountKey --no-interaction
php artisan make:class Actions/Analytics/WriteAccountDailySnapshot --no-interaction
php artisan make:class Actions/Analytics/WritePublicationDailySnapshot --no-interaction
php artisan make:test --pest Analytics/AnalyticsObservationWriterTest --no-interaction
```

--------------------------------

### Format and commit commands for analytics backfill

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Runs Pint on dirty files and commits the new analytics DTO, actions, support classes, and test file with a descriptive commit message.

```bash
vendor/bin/pint --dirty --format agent
git add app/Dto/Analytics/DateRange.php app/Actions/Analytics app/Support/Analytics tests/Feature/Analytics/WorkspaceAnalyticsReportTest.php
git commit -m "feat: query workspace analytics reports"
```

--------------------------------

### Run analytics read tests

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Run the controller and read tests to verify they fail because current controllers call provider services and Redis-backed PostMetricsFetcher.

```bash
php artisan test --compact tests/Feature/Analytics/AnalyticsControllerTest.php tests/Feature/Analytics/PersistedPostMetricsReadTest.php tests/Feature/AnalyticsResilienceTest.php
```

--------------------------------

### Format and commit analytics changes

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Format the dirty files with Pint and commit the analytics read path changes.

```bash
vendor/bin/pint --dirty --format agent
```

```bash
git add app/Http/Controllers app/Services/Post/PostMetricsFetcher.php app/Mcp routes/app.php tests/Feature/Analytics tests/Feature/AnalyticsResilienceTest.php tests/Feature/Mcp
```

```bash
git commit -m "feat: read analytics exclusively from database"
```

--------------------------------

### Run failing job tests (Step 2)

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Runs the feature tests for publication metrics jobs. Expected to fail because the jobs are not yet implemented.

```bash
php artisan test --compact tests/Feature/Analytics/PublicationMetricsJobsTest.php
```

--------------------------------

### Run Meta collector tests (expect failure)

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Runs the MetaPublicationCollectorsTest suite. Expected to fail because the collectors are not yet implemented.

```bash
php artisan test --compact tests/Feature/Analytics/Collectors/MetaPublicationCollectorsTest.php
```

--------------------------------

### Format and commit (Task 15 Step 6)

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Formats changed files with Pint and commits the persisted individual publication analytics feature. Includes the controller, routes, Vue components, locale files, and tests.

```bash
vendor/bin/pint --dirty --format agent
git add app/Http/Controllers/App/AnalyticsPublicationController.php routes/app.php resources/js/components/posts resources/js/components/analytics/workspace/PublicationMetrics.vue resources/js/pages/analytics/Publications lang tests/Feature/Analytics tests/Browser
git commit -m "feat: persist individual publication analytics"
```

--------------------------------

### Run backfill tests

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Executes the feature tests for publication backfill jobs and the backfill-existing command. Expected to fail because the jobs and command are not yet implemented.

```bash
php artisan test --compact tests/Feature/Analytics/PublicationBackfillJobsTest.php tests/Feature/Analytics/BackfillExistingAnalyticsCommandTest.php
```

--------------------------------

### Controller entry pattern for CreatePosts

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-24-independent-social-posts.md

Used in Task 6 Step 3 to implement the web store route. It executes the CreatePosts action with validated request data and redirects to the posts index, flashing the created post IDs.

```php
$posts = CreatePosts::execute($workspace, $request->user(), $request->validated());
return redirect()->route('app.posts.index')->with('created_post_ids', $posts->pluck('id')->all());
```

--------------------------------

### Format and commit Task 8

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Runs Pint on dirty files and commits the new open network publication collectors and tests.

```bash
vendor/bin/pint --dirty --format agent
git add app/Services/Analytics/Collectors/Publications app/Http/Controllers/Auth/MastodonController.php tests/Feature/Analytics/Collectors/OpenPublicationCollectorsTest.php tests/Feature/Auth/MastodonOAuthTest.php
git commit -m "feat: discover open network publications"
```

--------------------------------

### Run Pint on dirty files

Source: https://github.com/trypostit/trypost/blob/main/AGENTS.md

Run the Laravel Pint code formatter on modified PHP files before finalizing changes. Use `--dirty` to only format changed files and `--format agent` to output results in agent format.

```bash
vendor/bin/pint --dirty --format agent
```

--------------------------------

### Generate analytics migrations and schema test

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Run these artisan commands to create the four analytics tables and the Pest schema test. The test file is created at tests/Feature/Analytics/AnalyticsSchemaTest.php.

```bash
php artisan make:migration create_analytics_account_daily_snapshots_table --no-interaction
php artisan make:migration create_analytics_publications_table --no-interaction
php artisan make:migration create_analytics_publication_daily_snapshots_table --no-interaction
php artisan make:migration create_analytics_sync_states_table --no-interaction
php artisan make:test --pest Analytics/AnalyticsSchemaTest --no-interaction
```

--------------------------------

### Format and commit changes

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Runs Pint on dirty files and commits the new collector implementations and tests.

```bash
vendor/bin/pint --dirty --format agent
git add app/Contracts/Analytics app/Services/Analytics/Collectors/Metrics app/Services/Social tests/Feature/Analytics/Collectors/PublicationMetricsCollectorsTest.php tests/Feature/Services/Social
git commit -m "feat: normalize publication analytics metrics"
```

--------------------------------

### Format and commit Task 7

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Runs Pint on dirty files and commits the new publication collectors and tests.

```bash
vendor/bin/pint --dirty --format agent
git add app/Services/Analytics/Collectors/Publications tests/Feature/Analytics/Collectors/MediaPublicationCollectorsTest.php
git commit -m "feat: discover media network publications"
```

--------------------------------

### Run collector test and verify it fails

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Runs the FollowerCollectorsTest with compact output. Expected to fail because the collector factory is missing.

```bash
php artisan test --compact tests/Feature/Analytics/Collectors/FollowerCollectorsTest.php
```

--------------------------------

### Resolve content and media overrides with key presence

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-24-independent-social-posts.md

Implementation snippet from Task 1 Step 3: uses array_key_exists to detect explicit per-destination overrides, falling back to composition-level defaults. Preserves empty string and empty array overrides.

```php
$content = array_key_exists('content', $destination) ? $destination['content'] : ($composition['content'] ?? '');
$media = array_key_exists('media', $destination) ? $destination['media'] : ($composition['media'] ?? []);
```

--------------------------------

### Run analytics queue and schedule tests

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Runs the feature tests for account daily jobs, analytics schedule, and social account observer to verify dispatch and scheduling behavior. Expected to fail before implementation and pass after.

```bash
php artisan test --compact tests/Feature/Analytics/AccountDailyJobsTest.php tests/Feature/Analytics/AnalyticsScheduleTest.php tests/Feature/Observers/SocialAccountObserverTest.php
```

--------------------------------

### Bash: Format and commit analytics changes

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Formats dirty files with Pint and commits the analytics models, DTOs, actions, factories, and test file.

```bash
vendor/bin/pint --dirty --format agent
git add app/Models app/Dto/Analytics app/Actions/Analytics database/factories tests/Feature/Analytics/AnalyticsObservationWriterTest.php
git commit -m "feat: persist analytics observations"
```

--------------------------------

### Implement: UpdatePost rejects destination replacement

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-24-independent-social-posts.md

Implementation for Task 3 Step 3: throws ValidationException if social_account_id or platforms keys are present, then fetches the sole enabled target. Used to enforce that only one destination can be edited and destination replacement is rejected.

```php
if (array_key_exists('social_account_id', $data) || array_key_exists('platforms', $data)) {
    throw ValidationException::withMessages(['social_account_id' => __('posts.errors.target_fixed')]);
}
$target = $post->postPlatforms()->enabled()->sole();
```

--------------------------------

### Wayfinder Basic Usage (TypeScript)

Source: https://github.com/trypostit/trypost/blob/main/GEMINI.md

Import controller methods and named routes to generate typed route objects and URLs. Functions return { url, method } objects; use .url() for just the URL, and specific HTTP methods like .get() or .head().

```typescript
// Import controller methods (tree-shakable)...
import { show, store, update } from '@/actions/App/Http/Controllers/PostController'

// Get route object with URL and method...
show(1) // { url: "/posts/1", method: "get" }

// Get just the URL...
show.url(1) // "/posts/1"

// Use specific HTTP methods...
show.get(1) // { url: "/posts/1", method: "get" }
show.head(1) // { url: "/posts/1", method: "head" }

// Import named routes...
import { show as postShow } from '@/routes/post' // For route name 'post.show'
postShow(1) // { url: "/posts/1", method: "get" }
```

--------------------------------

### Run metric collector and provider tests

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Executes the metric collector tests along with existing provider tests. Expected to pass after implementing the collectors.

```bash
php artisan test --compact tests/Feature/Analytics/Collectors/PublicationMetricsCollectorsTest.php tests/Feature/Services/Social tests/Feature/XAnalyticsTest.php tests/Feature/YouTubeAnalyticsTest.php
```

--------------------------------

### PHP: Upsert analytics account daily snapshot

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Uses updateOrCreate with unique business keys (workspace_id, social_account_key, snapshot_date) to atomically merge metric catalog and scalar projections. Missing or unsupported values never blank prior successful same-day values.

```php
return AnalyticsAccountDailySnapshot::query()->updateOrCreate(
    [
        'workspace_id' => $account->workspace_id,
        'social_account_key' => $this->accountKeys->for($account),
        'snapshot_date' => $observation->date->toDateString(),
    ],
    $this->attributes($account, $observation),
);
```

--------------------------------

### Implement: CreatePosts atomic transaction with validation

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-24-independent-social-posts.md

Implementation for Task 2 Step 3: validates composition before transaction, then creates each post via CreateChannelPost inside a DB::transaction. Note: actual labels/status/schedule and PublishPost::dispatch($post)->afterCommit() are added inside the transaction mapping, not shown here.

```php
$resolved = PostCompositionValidator::validate($workspace, $composition);
return DB::transaction(fn (): Collection => collect($resolved['destinations'])->map(
    fn (array $destination): Post => CreateChannelPost::execute($workspace, $user, $destination)
));
```

--------------------------------

### Run all analytics read tests

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Run all analytics read tests including MCP tests, expecting PASS and no provider HTTP requests.

```bash
php artisan test --compact tests/Feature/Analytics/AnalyticsControllerTest.php tests/Feature/Analytics/PersistedPostMetricsReadTest.php tests/Feature/AnalyticsResilienceTest.php tests/Feature/Mcp
```

--------------------------------

### Assert backfill job dispatch and sync state checkpoint

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Verifies that BackfillAccountPublications is dispatched for the expected social account and that the sync state checkpoint and status are updated after processing.

```php
Bus::assertDispatched(BackfillAccountPublications::class,
    fn ($job) => $job->socialAccountId === $account->id);
expect($state->fresh()->checkpoint['cursor'])->toBe('provider-next-page')
    ->and($state->fresh()->status)->toBe(SyncStatus::Running);
```

--------------------------------

### Format and commit follower collectors

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Formats code with Pint and commits the new contract, exception, services, and test files.

```bash
vendor/bin/pint --dirty --format agent
git add app/Contracts/Analytics app/Exceptions/Analytics app/Services/Analytics/Collectors/Followers tests/Feature/Analytics/Collectors/FollowerCollectorsTest.php
git commit -m "feat: collect normalized follower snapshots"
```

--------------------------------

### Format and commit analytics changes

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Formats the modified files with Pint and commits the analytics job, command, schedule, observer, and test changes with a descriptive commit message.

```bash
vendor/bin/pint --dirty --format agent
git add app/Jobs/Analytics app/Console/Commands/Analytics routes/console.php app/Observers/SocialAccountObserver.php tests/Feature/Analytics tests/Feature/Observers/SocialAccountObserverTest.php
git commit -m "feat: schedule resilient follower analytics"
```

--------------------------------

### POST /posts/batch

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/specs/2026-09-24-independent-social-posts-design.md

Creates multiple social post destinations in a single request. Returns an ordered array of created posts.

```APIDOC
## [POST] /posts/batch

### Description
Creates multiple social post destinations in a single request. Returns an ordered array of created posts.

### Method
POST

### Endpoint
/posts/batch

### Parameters
#### Request Body
- **destinations[]** (array) - Required - List of destinations to create. Each destination follows the composition shape.

### Response
#### Success Response (200)
- **posts** (array) - Ordered array of created post resources.

```

--------------------------------

### Format and commit analytics schema changes

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Formats the code with Pint and commits the schema-related files. The commit message indicates the addition of workspace analytics schema.

```bash
vendor/bin/pint --dirty --format agent
git add app/Enums/Analytics database/migrations tests/Feature/Analytics/AnalyticsSchemaTest.php
git commit -m "feat: add workspace analytics schema"
```

--------------------------------

### Search for production callers of old grouped writers

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-24-independent-social-posts.md

Used in Task 7 Step 3 to find all production call sites of CreatePost::execute and SyncPostPlatforms::execute before retiring them.

```bash
rg -n 'CreatePost::execute|SyncPostPlatforms::execute' app routes
```

--------------------------------

### Format and commit Meta collectors

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Formats the changed files with Pint and commits the new contracts, DTO, collectors, and tests.

```bash
vendor/bin/pint --dirty --format agent
```

```bash
git add app/Contracts/Analytics app/Dto/Analytics/PublicationPage.php app/Services/Analytics/Collectors/Publications tests/Feature/Analytics/Collectors/MetaPublicationCollectorsTest.php
```

```bash
git commit -m "feat: discover Meta analytics publications"
```

--------------------------------

### Wait helpers in tests/Pest.php

Source: https://github.com/trypostit/trypost/blob/main/AGENTS.md

All waits go through shared helpers in tests/Pest.php. Each helper takes a CSS selector where @name stands for [data-testid="name"]. Prefer @ test ids; use role or data-slot only when no test id exists.

```php
waitFor($page, '@id')
```

```php
waitForGone($page, '@id')
```

```php
waitForState($page, '@id', "element.getAttribute('aria-checked') === 'true'")
```

```php
waitForText($page, '[role="option"]', 'general')
```

```php
waitForGoneOrShown($page, gone: '@post-composer-dialog', shown: '@unsaved-changes-dialog')
```

```php
waitForPath($page, $path)
```

```php
waitForCondition($page, $js)
```

--------------------------------

### Format and commit reconciliation changes

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Formats the dirty files with Pint and commits the new DTOs, actions, job, observer, and tests. The commit message is 'feat: reconcile analytics publications'.

```bash
vendor/bin/pint --dirty --format agent
git add app/Dto/Analytics app/Actions/Analytics app/Jobs/Analytics/SyncTryPostPublication.php app/Observers/PostPlatformObserver.php tests/Feature/Analytics/PublicationReconciliationTest.php tests/Feature/Observers/PostPlatformObserverTest.php
git commit -m "feat: reconcile analytics publications"
```

--------------------------------

### Button loading prop

Source: https://github.com/trypostit/trypost/blob/main/AGENTS.md

Use the Button component's `loading` prop to show request progress; it disables the button and swaps the label for a spinner.

```html
<Button :loading="form.processing">
```

--------------------------------

### POST /posts

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/specs/2026-09-24-independent-social-posts-design.md

Creates a single social post destination. Returns a single-resource response. Rejects requests with multiple platforms with a 422 error.

```APIDOC
## [POST] /posts

### Description
Creates a single social post destination. Returns a single-resource response. Rejects requests with multiple platforms with a 422 error.

### Method
POST

### Endpoint
/posts

### Parameters
#### Request Body
- **platforms** (array) - Required - Must contain exactly one platform. If multiple platforms are provided, the request is rejected with a 422 error.

### Response
#### Success Response (200)
- **post** (object) - The created post resource.

#### Error Response (422)
- **error** (string) - Message directing the caller to use the batch endpoint.

```

--------------------------------

### Inertia Client Navigation with Link

Source: https://github.com/trypostit/trypost/blob/main/GEMINI.md

Use the Link component from @inertiajs/vue3 for client-side navigation instead of traditional links. The component must have a single root element.

```vue
import { Link } from '@inertiajs/vue3'
<Link href="/">Home</Link>
```

--------------------------------

### Test same-day writes update one row

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

PHP test that verifies the writer behavior: same-day writes update one row, next-day writes create history, null stays null, numeric zero stays zero, deleting the social account preserves snapshots through the immutable key, and reconnecting the same workspace + network + platform_user_id reuses that key. The test expects the count to be 1 and the followers_count to be 0.

```php
$writer->handle($account, new AccountDailyObservation(
    date: CarbonImmutable::parse('2026-09-23', 'UTC'),
    followers: 0,
    provenance: ObservationProvenance::Actual,
    precision: MetricPrecision::Exact,
    providerObservedAt: null,
));

expect(AnalyticsAccountDailySnapshot::count())->toBe(1)
    ->and(AnalyticsAccountDailySnapshot::first()->followers_count)->toBe(0);
```

--------------------------------

### Run tests filtered by name

Source: https://github.com/trypostit/trypost/blob/main/AGENTS.md

Run tests filtered by a specific test name using the `--filter` option.

```bash
php artisan test --compact --filter=testName
```

--------------------------------

### PUT /posts/{post}

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/specs/2026-09-24-independent-social-posts-design.md

Updates a single post. Operates on one post and rejects attempts to switch the destination.

```APIDOC
## [PUT] /posts/{post}

### Description
Updates a single post. Operates on one post and rejects attempts to switch the destination.

### Method
PUT

### Endpoint
/posts/{post}

### Parameters
#### Path Parameters
- **post** (string) - Required - The ID of the post to update.

#### Request Body
- **fields** (object) - Required - The fields to update on the post.

### Response
#### Success Response (200)
- **post** (object) - The updated post resource.

```

--------------------------------

### Register batch route before parameterized route in api.php

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-24-independent-social-posts.md

Registers the batch endpoint before the single-post route so the parameterized route does not capture 'batch'. Both routes call the PostController and are named for API post store actions.

```php
Route::post('/posts/batch', [PostController::class, 'storeBatch'])->name('api.posts.batch.store');
Route::post('/posts', [PostController::class, 'store'])->name('api.posts.store');
```

--------------------------------

### Stable response shape for workspace analytics report

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Defines the expected structure returned by BuildWorkspaceAnalyticsReport::execute(). Includes bounds, range, summary, followers, posts, top_posts, performance, and coverage keys.

```php
[
    'bounds' => ['min' => '2025-09-23', 'max' => '2026-09-23'],
    'range' => ['start' => '2026-08-25', 'end' => '2026-09-23'],
    'summary' => [...],
    'followers' => ['total' => 15200, 'accounts' => [...], 'series' => [...]],
    'posts' => ['resolution' => 'weekly', 'accounts' => [...], 'buckets' => [...]],
    'top_posts' => ['reactions' => [...], 'comments' => [...]],
    'performance' => [...],
    'coverage' => [...],
];
```

--------------------------------

### Wayfinder Form Component (Vue)

Source: https://github.com/trypostit/trypost/blob/main/GEMINI.md

Use Wayfinder's .form() method with Inertia's <Form> component to automatically generate the action and method attributes for HTML forms.

```vue
<Form v-bind="store.form()"><input name="title" /></Form>
```

--------------------------------

### Browser test for workspace analytics dashboard

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Failing browser test that visits the analytics page and asserts summary cards, account labels, chart toggles, performance rows, and absence of JavaScript errors or console logs.

```php
$page = visit(route('app.analytics'));
$page->assertSee('Total Followers')
    ->assertSee('@first · Instagram')
    ->assertSee('@second · Instagram')
    ->click('Growth')
    ->assertSee('-20')
    ->assertNoJavaScriptErrors()
    ->assertNoConsoleLogs();
```

--------------------------------

### Commit workspace analytics dashboard

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Git commands to stage and commit the new analytics dashboard files and translations.

```bash
git add resources/js/pages/analytics resources/js/components/analytics/workspace lang tests/Browser/WorkspaceAnalyticsTest.php
git commit -m "feat: add workspace analytics dashboard"
```

--------------------------------

### Query indexes for analytics tables

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Adds the required query indexes to the analytics tables. These indexes support efficient queries on workspace, snapshot date, publication date, and sync state. The exact index definitions must be used as shown.

```php
$table->index(['workspace_id', 'snapshot_date']);
$table->index(['workspace_id', 'social_account_key', 'snapshot_date']);
$table->index(['workspace_id', 'provider_published_at']);
$table->index(['workspace_id', 'social_account_key', 'provider_published_at']);
$table->index(['analytics_publication_id', 'collected_at']);
$table->index(['collector', 'status']);
```

--------------------------------

### Tailwind v4 Import Tailwind Diff

Source: https://github.com/trypostit/trypost/blob/main/GEMINI.md

Shows the migration from Tailwind v3's @tailwind directives to v4's CSS @import statement. Use @import "tailwindcss" instead of the deprecated @tailwind base, components, and utilities.

```diff
   - @tailwind base;
   - @tailwind components;
   - @tailwind utilities;
   + @import "tailwindcss";
```

--------------------------------

### PublicationMetricsCollector interface

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Defines the contract for collecting normalized publication metrics. Implementations must return a PublicationMetricObservation for a given publication and date.

```php
interface PublicationMetricsCollector
{
    public function collect(
        AnalyticsPublication $publication,
        CarbonImmutable $date,
    ): PublicationMetricObservation;
}
```

--------------------------------

### Assert analytics schema columns

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Pest assertion verifying that the analytics_account_daily_snapshots table has the expected columns. Used in the schema test to confirm the table structure.

```php
expect(Schema::hasColumns('analytics_account_daily_snapshots', [
    'workspace_id', 'social_account_id', 'social_account_key', 'platform',
    'network', 'platform_user_id',
    'snapshot_date', 'followers_count', 'metrics', 'provenance', 'precision',
    'provider_observed_at', 'collected_at',
]))->toBeTrue();
```

--------------------------------

### Split active legacy posts: clone and move additional targets

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-24-independent-social-posts.md

Used in Task 8 Step 3 to split draft/scheduled rows with more than one enabled target. Locks enabled targets in ID order, returns if one or fewer, then clones the post and its relations quietly and moves each additional target to the clone. Excludes disabled placeholders and avoids asset duplication and event emission.

```php
$targets = $post->postPlatforms()->enabled()->orderBy('id')->lockForUpdate()->get();
if ($targets->count() <= 1) {
    return;
}
foreach ($targets->skip(1) as $target) {
    $clone = $this->clonePostAndRelationsQuietly($post);
    $target->updateQuietly(['post_id' => $clone->id]);
}
```

--------------------------------

### Assertion for reconciliation test

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Verifies that a single AnalyticsPublication exists for the provider post id, with origin TryPost and the expected post_platform_id. Used in the failing reconciliation tests for both arrival orders.

```php
expect(AnalyticsPublication::query()->where('provider_post_id', 'remote-1')->count())->toBe(1)
    ->and(AnalyticsPublication::first()->origin)->toBe(PublicationOrigin::TryPost)
    ->and(AnalyticsPublication::first()->post_platform_id)->toBe($postPlatform->id);
```

--------------------------------

### DELETE /posts/{post}

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/specs/2026-09-24-independent-social-posts-design.md

Deletes a single post. Operates on one post and rejects attempts to switch the destination.

```APIDOC
## [DELETE] /posts/{post}

### Description
Deletes a single post. Operates on one post and rejects attempts to switch the destination.

### Method
DELETE

### Endpoint
/posts/{post}

### Parameters
#### Path Parameters
- **post** (string) - Required - The ID of the post to delete.

### Response
#### Success Response (200)
- **status** (string) - Confirmation of deletion.

```

--------------------------------

### Strict audit fails on zero-target scheduled row

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-24-independent-social-posts.md

Regression test from Task 9 Step 1. Asserts that the strict audit command fails when a scheduled row has zero enabled targets, enforcing the audit gate before cutover.

```php
$this->artisan('posts:audit-legacy', ['--strict' => true])->assertFailed();
```

--------------------------------

### Target elements by data-testid in browser tests

Source: https://github.com/trypostit/trypost/blob/main/AGENTS.md

Use @my-element to resolve to [data-testid="my-element"]. Add data-testid in the Vue component and use $page->click('@my-element'). For repeated elements, bind the testid dynamically.

```php
$page->click('@my-element')
```

```html
:data-testid="`connect-${platform.value}`"
```

--------------------------------

### Materialize per-account override inheritance in usePostComposition.ts

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-24-independent-social-posts.md

Uses hasOwnProperty to check whether an override explicitly sets content or media, falling back to the composition's values. This preserves explicit empty/other overrides while inheriting unspecified fields.

```ts
const content = Object.prototype.hasOwnProperty.call(override, 'content') ? override.content! : composition.content;
const media = Object.prototype.hasOwnProperty.call(override, 'media') ? override.media! : composition.media;
```

--------------------------------

### Assert dispatch of CollectAccountDailySnapshot for included account

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Verifies that the CollectAccountDailySnapshot job is dispatched for an included account (Instagram) with the correct socialAccountId and observationDate, and is not dispatched for an excluded account (LinkedIn). Use in feature tests for dispatch logic.

```php
Bus::assertDispatched(CollectAccountDailySnapshot::class,
    fn ($job) => $job->socialAccountId === $instagram->id
        && $job->observationDate === '2026-09-23');
Bus::assertNotDispatched(CollectAccountDailySnapshot::class,
    fn ($job) => $job->socialAccountId === $linkedin->id);
```

--------------------------------

### Extending Theme in CSS with @theme

Source: https://github.com/trypostit/trypost/blob/main/GEMINI.md

Use the @theme directive in CSS to define custom design tokens, such as colors, in Tailwind v4. This replaces the need for a separate tailwind.config.js file.

```css
@theme {
  --color-brand: oklch(0.72 0.11 178);
}
```

--------------------------------

### Persisted enum definitions for analytics schema

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Defines the exact persisted enum vocabulary using backed string enums. These enums are used for provenance, precision, publication origin/availability, exposure kind, metric unit/time basis/availability, sync collector, and sync status. The cases and values must match exactly for the schema to work.

```php
enum ObservationProvenance: string { case Actual = 'actual'; case CarriedForward = 'carried_forward'; }
enum MetricPrecision: string { case Exact = 'exact'; case Approximate = 'approximate'; case Estimated = 'estimated'; case Experimental = 'experimental'; }
enum PublicationOrigin: string { case TryPost = 'trypost'; case External = 'external'; }
enum PublicationAvailability: string { case Available = 'available'; case Deleted = 'deleted'; case Unavailable = 'unavailable'; }
enum ExposureKind: string { case Reach = 'reach'; case Impressions = 'impressions'; case Views = 'views'; }
enum MetricUnit: string { case Count = 'count'; case Milliseconds = 'milliseconds'; case Percent = 'percent'; }
enum MetricTimeBasis: string { case Lifetime = 'lifetime'; case Range = 'range'; case Rolling90Days = 'rolling_90_days'; case Snapshot = 'snapshot'; }
enum MetricAvailability: string { case Available = 'available'; case Unsupported = 'unsupported'; case Unavailable = 'unavailable'; case Delayed = 'delayed'; case PrivacyLimited = 'privacy_limited'; }
enum SyncCollector: string { case PublicationBackfill = 'publication_backfill'; case PublicationDiscovery = 'publication_discovery'; }
enum SyncStatus: string { case Pending = 'pending'; case Running = 'running'; case Complete = 'complete'; case Partial = 'partial'; case ProviderLimited = 'provider_limited'; case Failed = 'failed'; }
```

--------------------------------

### PostCompositionValidator test assertion for inheritance and explicit empty override

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-24-independent-social-posts.md

Core assertion from Task 1 Step 1: validates that the first destination inherits 'Shared' content while the second destination's explicit empty string override is preserved. Used in tests/Unit/Support/PostCompositionValidatorTest.php.

```php
$resolved = PostCompositionValidator::validate($workspace, $composition);
expect($resolved['destinations'][0]['content'])->toBe('Shared');
expect($resolved['destinations'][1]['content'])->toBe('');
```

--------------------------------

### FollowerCollector contract interface

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Defines the contract for platform-specific follower collectors. The collect method takes a SocialAccount and a CarbonImmutable date, returning an AccountDailyObservation.

```php
interface FollowerCollector
{
    public function collect(SocialAccount $account, CarbonImmutable $date): AccountDailyObservation;
}
```

--------------------------------

### Vue template event handler calling named function

Source: https://github.com/trypostit/trypost/blob/main/AGENTS.md

Template event handlers must call a named function, not inline state mutations. Passing arguments is allowed.

```html
@click="openCreateDialog"
```

--------------------------------

### Define PublicationPage DTO contract

Source: https://github.com/trypostit/trypost/blob/main/docs/superpowers/plans/2026-09-23-workspace-analytics-backfill.md

Defines the immutable PublicationPage value object returned by PublicationHistoryCollector::page(). Holds a list of DiscoveredPublication objects, the next cursor, and flags for provider exhaustion and rate limiting.

```php
final readonly class PublicationPage
{
    /** @param list<DiscoveredPublication> $publications */
    public function __construct(
        public array $publications,
        public ?string $nextCursor,
        public bool $providerExhausted,
        public bool $providerLimited = false,
    ) {}
}
```