Agent quickstart

Agent quickstart

A brief for an AI coding agent asked to install Atelier on a project and verify it works. Written to be pasted into a fresh session.

If you are that agent: read this whole page before running anything. Two steps fail silently, and you will waste time debugging a symptom whose cause is three steps back.

---

The brief

Install safi/filament-atelier into this Laravel app and verify it works end to end. The wiki page "Agent quickstart" at https://github.com/Abdulkader-Safi/filament-atelier/wiki/Agent-quickstart has the steps and the traps. Report what you verified, and anything you had to work around.

---

What this package is

A page builder for Laravel, shipped as a Filament plugin.

• A page is a JSON tree of typed blocks, stored in atelier_pages.
• A block type is one PHP class plus one Blade view. The class returns a Filament schema, which becomes its settings form.
• Blocks render through Blade at request time. The public site is server-rendered.
• Editing writes draft_content. Publishing copies it to published_content. The public route reads published only.
• Bilingual: translatable fields hold a per-locale map inside the same tree.

Prerequisites

Check these before installing. If any is missing, say so rather than working around it.

• PHP 8.3+
• Laravel 12 or 13
• Filament 5 installed with a panel. If there's no panel, composer require filament/filament:"^5.0" then php artisan filament:install --panels creates one
• Tailwind 4 with Vite. Without it, blocks render unstyled and step 4 below has nothing to do
• A database that's migrated and reachable

Install

Read this first: the package is not on Packagist yet. composer require safi/filament-atelier on its own will fail with "could not be found". Add the repository to the app's composer.json before requiring anything:

"repositories": [
    { "type": "vcs", "url": "https://github.com/Abdulkader-Safi/filament-atelier" }
]

Or do it from the command line:

composer config repositories.atelier vcs https://github.com/Abdulkader-Safi/filament-atelier

Then:

composer require safi/filament-atelier:^0.1
php artisan vendor:publish --tag=filament-atelier-config
php artisan vendor:publish --tag=filament-atelier-migrations
php artisan migrate
php artisan storage:link

Register in the panel provider:

use Safi\Atelier\AtelierPlugin;
use Safi\Atelier\Blocks\DefaultBlocks;

->plugins([
    AtelierPlugin::make()->blocks(DefaultBlocks::all()),
])

Add to resources/css/app.css, then npm run build:

@source '../../vendor/safi/filament-atelier/resources/views/**/*.blade.php';

Remove the welcome route from routes/web.php if the CMS should own /.

Seed something to look at:

php artisan tinker --execute='(new Safi\Atelier\Database\Seeders\AtelierDemoSeeder)->run();'

If the app has no User that can reach the panel, Filament denies access outside a local environment unless the model implements FilamentUser. See trap 5.

The traps, in the order they'll catch you

1. The Tailwind @source line. Skip it and every block renders unstyled. There is no error, in the console, the log, or anywhere. If blocks look like unstyled HTML, this is why. Verify by grepping the built CSS for a class only the package uses:

grep -c 'text-pretty' public/build/assets/app-*.css

2. storage:link. Skip it and every uploaded image is broken, again with no error. Check public/storage is a symlink.

3. A stale public/hot. If Vite was started and killed, public/hot survives and @vite points the page at a dev server that isn't running, so the preview loads unstyled. Delete public/hot or start Vite.

4. Signed preview URLs and hostnames. The preview uses relative signatures, so browsing 127.0.0.1 while APP_URL says localhost is fine. If you see a 403 on /atelier/preview/..., it's not this; check the signature is intact.

5. Panel access in non-local environments. Filament denies panel access outside local unless your User implements FilamentUser. In a testing environment you'll get a 403 that looks like a routing problem.

Verify it, in this order

Each step depends on the one before, so stop at the first failure rather than pressing on.

# 1. Routes exist
php artisan route:list | grep -E 'atelier|pages'

Expect the preview route, the editor page, the Pages resource and the public page routes.

# 2. The public page renders, server-side
curl -s http://localhost:8000/ | grep -c 'data-atelier-block'

Expect the number of sections, not 0. If it's 0, either no page is published or the welcome route is still winning.

# 3. Content is in the initial HTML, with no JavaScript
curl -s http://localhost:8000/ | grep -oE '<h1[^>]*>[^<]*'

The heading must be in the source, not injected later. This is the whole SEO argument.

# 4. A draft does not leak
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/contact

Expect 404. The demo seeder leaves Contact as a draft on purpose.

# 5. The other locale, with RTL and hreflang
curl -s http://localhost:8000/ar/home | grep -oE '<html[^>]*|hreflang="[a-z]+"'

Expect dir="rtl", lang="ar", and hreflang for both locales.

# 6. SEO tags
curl -s http://localhost:8000/ | grep -oE '<title>[^<]*|<link rel="canonical"[^>]*|og:title[^>]*'

7. The editor, in a browser. Log into /admin, open Pages, click a page, then Edit page content. Check that:

• The builder is full screen with no Filament sidebar
• The preview shows the real page, styled
• Typing in a field updates the preview within about a second, without saving
• The width switcher changes the iframe width
• Adding, hiding, duplicating and reordering a section all work

8. Image upload. Add an Image block, upload a file, and confirm it appears in the preview. Then check it actually landed:

ls -la storage/app/public/atelier/

An empty folder with a field that said "upload complete" means the upload never dehydrated. That was a real bug, fixed in v0.1.0.

Writing a block, to prove extensibility

The strongest check is that you can add a block without touching the package. One class in app/Blocks, one view in resources/views/blocks, register the class. See Usage for a complete example.

Two things to get right: every field needs ->live(debounce: 400) or the preview won't update as you type, and images use Media::upload() in the schema and Media::url() in the view.

Then confirm nothing inside vendor/safi/filament-atelier was edited:

git status vendor/ 2>/dev/null; grep -r 'YourBlock' vendor/safi/ | wc -l   # expect 0

What to report back

• Which of the eight verification steps passed
• Anything you worked around, and why
• Whether the preview felt live while typing, which is the one thing a command can't tell you

Where things live once installed

Path	What
config/atelier.php	Locales, layout, preview debounce and widths, media disk
database/migrations/*_create_atelier_tables.php	atelier_pages, atelier_page_slugs
/admin/pages	Page list and settings
/admin/atelier/{id}	The builder
/atelier/preview/{page}/{locale}	Signed preview, always noindex
/{slug} and /{locale}/{slug}	Public pages

Known limits in v0.1.0

Don't report these as bugs.

• Reordering is arrow buttons, not drag
• Block types are code only, by design
• Arabic shares the section order with English, by design
• No revisions UI; publishing overwrites
• No sitemap, no JSON-LD
• The contact form is presentational