Charlotte

A headless website-builder agent kit for Laravel. Charlotte lets your app host an agent that builds and edits fancy-cms pages, live, beside a person. It runs on prism-harness, so any Prism provider works.

It is headless on purpose: Charlotte writes an ordered event log, and any chat UI you build reads it. A plain fetch loop is enough (docs/fetch-chat.html).

Pre-1.0. Breaking changes land in minor releases; read the CHANGELOG before upgrading.

What you get

• Page tools over a draft. The agent edits a fancy-cms page through nine closed tools: charlotte_brief, cms_describe, cms_icons, cms_assets, cms_get, cms_apply, cms_changes_since, cms_check and cms_finish. Writes are pinned to a revision, so a person editing at the same time is never overwritten.
• Drafts only. Charlotte edits a draft. Nothing it does publishes. Publishing is one explicit host call, $session->publish($revision, $by).
• Autonomy is your setting. full applies each edit to the draft at once. approve_on_save collects edits in a change set a person approves or rejects.
• A structured brief with code-derived fact checks. Required facts must appear on the page (missing_required_fact), and prices, percentages, counts, phone numbers, emails, dates, years and quotes that no fact supports are flagged (unsupported_claim). No model is involved.
• Page checks. Heading outline, alt text, contrast where it can be computed, link safety, placeholder copy and meta, lifted from the Fancy lab that measured them.
• Finish gates and a responsive starter. cms_finish refuses (not_ready, with the defects) a page whose stacks and grids have no layout, whose links run together, that never changes at tablet or desktop width, that lacks an image the brief requires or a meta description, or that states a figure or date the brief does not give. Each defect names its node and rule; after charlotte.finish.max_not_ready refusals in a row (3) the agent stops and hands the defects back. An agent cannot write a stack or grid without a layout. The builder prompt carries a responsive skeleton, type scale and spacing scale to start from, as fancy-cms data.
• A versioned, overridable guide. fancy-cms's authoring guide plus Charlotte's own (drafts, autonomy, content truth, the webmaster lessons). Layer your house style on top; every session records the guide hash it ran.
• An event log any client can long-poll. Envelope v1, gap-free per-session cursors, short requests that work behind Cloudflare. See docs/events.md.
• A thin, optional controller kit. Routes behind your authorization hook and your tenant resolver. With no hook, every route is refused.
• Optional usage telemetry. If you turn on Prism's telemetry, Charlotte reports token usage, and cost when you give prices. It is never required and never refuses anything.

Quick look

use Charlotte\Brief\Brief;
use Charlotte\Facades\Charlotte;

// Once, in a service provider:
Charlotte::resolveTenantUsing(fn ($request) => (string) $request->user()->current_team_id);
Charlotte::authorizeUsing(fn ($user, string $ability, array $subject): bool => $user->can('charlotte.'.$ability));
Charlotte::routes();

// In your controller:
$session = Charlotte::for($request->user())
    ->tenant((string) $team->getKey())
    ->page('home')
    ->brief(Brief::fromArray($validated['brief']))
    ->autonomy('approve_on_save')
    ->open();

$cursor = $session->send('Build the landing page from the brief.', (string) $request->user()->getKey());
// A queue worker runs the turn; clients poll GET /charlotte/sessions/{id}/events?after=<cursor>&wait=20

Full setup: docs/laravel-quickstart.md.

A whole site

Open with site() instead of page() and the agent builds several pages: it creates and routes pages, edits a shared @header and @footer once for every page, sets the nav, and makes a 404 page. Routes your app serves itself are refused, so list them:

// config/charlotte.php
'site' => ['reserved_routes' => ['/login', '/register', '/forgot-password', '/reset-password/*', '/dashboard']],

$session = Charlotte::for($request->user())->tenant((string) $team->getKey())->site('marketing')
    ->brief(Brief::fromArray($validated['brief']))->open();

$session->siteExport();                       // {pages[{route, title, description, doc}], header, footer, notFound, islands}
$session->publish($session->site()['revision'], (string) $request->user()->getKey()); // every page and region at once

cms_check adds site-wide checks: broken internal links, orphan pages, a missing 404 or home page, and nav consistency.

Component nodes and islands. By default Charlotte reads fancy-cms's own island catalogue ({$schema, $defs, types}). That gives the agent the built-in nodes chart, kpi, table, leaderboard and input, placed under those bare names; island: true is implied. To add your own islands beside them, use namespace:Name types, which are placed with island: true:

app()->instance(\Charlotte\Islands\IslandCatalogue::class,
    \Charlotte\Islands\CmsDescribeIslands::withHost([['type' => 'kit:Tabs', 'description' => 'Tabbed panels', 'props' => $schema]]));

Every node of a catalogue type is checked against its JSON Schema, with the catalogue's $defs, for every actor. An unknown type, richtext, and island: true on a native element are refused.

Rendered contrast. Charlotte::renderedUsing() hands Charlotte a browser's measurements (Checks\RenderedEvidence::fromAxe() reads axe-core results), so contrast is judged on the rendered page, islands included. Without one it is judged on the document, and every check result says which ran.

This is the beginning of the README. Read the rest at the original. Read the full README ↗