Agent guide

Use this page when an AI coding agent is installing, configuring, integrating, or modifying LaraPost. It is intentionally explicit about supported behavior so agents do not invent provider capabilities or unsafe defaults.

Runtime baseline

Deterministic installation

For interactive local setup:

composer require prateekbhujel/larapost
php artisan larapost:install
php artisan larapost:doctor

For an agent-controlled non-interactive setup, declare choices explicitly. Use --no-migrate when the agent is not authorized to change the database.

php artisan larapost:install \
  --platforms=facebook,linkedin \
  --no-dashboard \
  --no-env \
  --no-migrate

Verify before real publishing

php artisan larapost:doctor

The doctor checks database tables, enabled platforms, active accounts, queue mode, scheduler registration, dashboard protection, TikTok mode, and optional MCP requirements. Treat failures as configuration work, not something to bypass.

Canonical publishing API

Publish immediately

use SocialSync\Facades\SocialMedia;

$result = SocialMedia::post()
    ->content('We just shipped a new release.')
    ->platform('facebook')
    ->publish();

Queue immediate work

SocialMedia::post()
    ->content('Queued from Laravel.')
    ->platform('linkedin')
    ->queue();

Schedule for the future

SocialMedia::post()
    ->content('Publishing tomorrow.')
    ->platform('facebook')
    ->scheduleFor(now()->addDay())
    ->publish();

A future scheduleFor() call persists the post for LaraPost's scheduler. The Laravel scheduler must actually be running in production.

Target multiple platforms

SocialMedia::post()
    ->content('One message, selected networks.')
    ->platforms(['facebook', 'linkedin'])
    ->publish();

Target selected connected accounts

SocialMedia::post()
    ->content('Account-specific post.')
    ->platform('facebook')
    ->accounts([
        'facebook' => [12, 18],
    ])
    ->publish();

Configuration invariants

The enabled platform list is the runtime boundary. Disabled drivers should not be assumed to exist.

LARAPOST_PLATFORMS=facebook,twitter,linkedin,tiktok
LARAPOST_DEFAULT_PLATFORM=facebook

LARAPOST_QUEUE_ENABLED=true
LARAPOST_QUEUE_NAME=larapost

LARAPOST_SCHEDULER_ENABLED=true

LARAPOST_UI_ENABLED=true
LARAPOST_ROUTE_PREFIX=larapost

When queueing is enabled, ensure a worker consumes the configured LaraPost queue. When scheduling is enabled, ensure Laravel's scheduler runs continuously or every minute according to the host application's deployment model.

Provider rules agents must not invent

TikTok safety contract

TIKTOK_PUBLISH_MODE=upload

upload is the built-in safe default. LaraPost transfers media and the creator reviews and completes the post in TikTok.

direct is only for a host application that implements TikTok's required creator-facing flow. It must obtain current creator information, an explicit creator-selected privacy level, interaction choices, and consent. Switching modes changes OAuth scope, so reconnect affected accounts.

MCP and AI clients

MCP is optional and side-effecting tools must be treated like privileged application operations.

composer require laravel/mcp:^1.0

LARAPOST_MCP_ENABLED=true
LARAPOST_MCP_TOKEN=replace-with-a-long-random-secret

Available tools include business context, capabilities, account/history lookup, create post, schedule post, and cancellation. Never expose provider credentials or access tokens to an AI client.

When modifying LaraPost itself

• Keep public behavior compatible within the current major version.
• Do not weaken default dashboard authentication or OAuth state validation.
• Do not add silent provider defaults when the provider requires a user choice or consent.
• Add regression tests for publishing, OAuth, scheduler, retry, or provider behavior that changes.
• Update the relevant documentation page when configuration, commands, environment variables, or public APIs change.

composer validate --strict --no-check-lock
composer test

Source map

Machine-readable entry point

Agents that support documentation discovery can start with /larapost/llms.txt. Repository coding agents should also read the root AGENTS.md.