Ghostwriter Statamic Laravel Package

Getting Started

Ghostwriter is a Statamic 6 addon (running on Laravel) that drafts, reviews and links content through AI, so most of your day-to-day work happens in the Control Panel and in config/ghostwriter.php rather than in application code.

1. Check the floor before anything else. v1.3.0 requires 1994/ghostwriter-core ^1.10, Statamic 6.30+ and PHP 8.3+. On older Statamic 6.x you cannot install this release — plan the Statamic upgrade first, since the Preview tab and Layouts lean on template-rendering behaviour from 6.30.
2. Install and publish config. Require the addon, then publish config/ghostwriter.php so suggest.*, revisit.* and preview.* are version-controlled alongside your other config.
3. Let it learn your collections. Ghostwriter writes for collections it has been pointed at; the more published entries it can see, the better "Model it on" and Layouts behave. Point it at real content, not fixtures.
4. First use case — triage the backlog, free of charge. Open Ghostwriter → Content to revisit. Every check on that page (past years written as current, passed closing dates, broken links, missing alt text, thin SEO, orphan pages) is deterministic and costs nothing. It is the fastest way to prove value before anyone approves an AI budget.
5. Second use case — one edit. Open any existing entry, choose Suggest edits from the menu beside Edit with Ghostwriter, and run it on a single page. You will see the confirm-with-cost step and the accept/dismiss loop that the rest of the feature set is built around.

Where to look first as a developer: config/ghostwriter.php for the three new toggles, your Bard blueprints (they bound what Extras and headings can do), and your Antlers/Blade layouts for the live_preview:ghostwriter guard.

Implementation Patterns

Treat the config file as the source of truth for rollout. The three new settings — suggest.claims (on), revisit.external_links (off) and revisit.age_in_full (none) — exist both in the CP and in config. Set them per environment: keep revisit.external_links off in local and CI so test runs never make outbound requests, and enable it only in production where the weekly Sunday 04:00 job is meaningful. Remember php artisan config:cache after changes; a CP toggle and a cached config can disagree, so pick one owner per environment.

Drive the revisit index from the scheduler, not from a controller. php please ghostwriter:revisit runs daily at 03:00 through Laravel's scheduler with a full pass weekly. In any real deployment that means the system cron entry for schedule:run must exist — otherwise Content to revisit silently goes stale and the Overview tile lies to editors. Add a health check or a monitor on the command's exit code, and run it manually after large imports or bulk deletions so the ranking reflects reality.

Compose the review loop as a pipeline rather than a single button. A realistic editorial workflow: Content to revisit → Review (opens the page with Suggest edits ready) → accept wording fixes in bulk with Accept all wording fixes → handle the structural steps in Finish this page (counts to check, short headings, missing internal links, missing SEO description) → publish. Because decisions are shared and remembered per piece, two editors can work the same page without re-litigating the same suggestions.

Lean on the free/premium split for cost control. Free checks run constantly and cost nothing; AI calls are always gated behind a confirm that states the price. In practice, let the free layer do the triage and reserve the paid calls for pages that already failed a free check. The two-pass design (a candidate survives only if it is a real problem in its paragraph, then a second call re-checks every suggestion) is what keeps editors trusting the output — resist the temptation to skip straight to "Accept all".

Make blueprints do the constraining. Extras only prepare stats, FAQs, pull quotes and the like for block types your blueprint actually has, and headings only use levels each Bard field allows. A tight, well-labelled blueprint gives noticeably better drafts than a permissive one; conversely, adding a block type is how you unlock a new Extra without any code.

Use the Preview tab as the integration seam. Preview renders the unsaved draft through your own templates at Desktop and Phone widths, without saving anything. Two developer-facing consequences:

• Wrap anything that must not appear in a Ghostwriter preview — analytics, A/B scripts, gated CTAs, "related posts" queries that assume a saved entry — in {{ if !live_preview:ghostwriter }}…{{ /if }}.
• Preview responses carry headers that keep them private, out of search engines, and block third-party scripts. If your layout depends on a script to look right (fonts, embeds), allow-list the host via preview.script_hosts rather than disabling the protection.

Tune preview.timeout to your slowest layout. This is the one config value that will bite you on a content-heavy site; a template that renders in 400 ms in dev can exceed a tight default under a cold cache. Give it headroom and fix slow partials rather than raising it indefinitely.

Wire SEO into whatever you already use. The Search section produces a title (only when the page title is too long), a description and a slug, with a live character count and Try again. Use this draft writes into SEO Pro or your plain SEO fields, never overwriting human-written text, and fills the slug on new or unpublished entries. That non-destructive rule is the integration contract — if you have a custom SEO fieldset, map it to the same field handles so the addon recognises it as "already written".

Treat alt text as the one write-back path. Of everything in Suggest edits, only alt text is persisted — and only after a confirm telling you how many pages use the image. Do not assume accepted wording is saved anywhere; it lands in the form and a human still saves the entry. Build any bulk-content tooling around that assumption.

Adopt the suggestion actions as first-class UI states. Accept / Edit / Another version / It's still right / Dismiss, plus Undo and category filters, mean an editor can decline a suggestion permanently. If you are instrumenting adoption, "It's still right" is a different signal from dismissal and should not be collapsed into an accept/reject boolean.

Keep comments client-side until applied. Comments live in the browser until Apply, which issues one call that revises only the commented blocks and reports per-comment outcomes: Changed (with before/after and Put it back), Replied, Not applied, or Skipped because someone else changed the block. That last state is optimistic concurrency — design review sessions so two editors are not applying comments to the same draft simultaneously, or expect skips.

Use Layouts as a cheap editorial A/B. Up to two alternative layouts are ranked against your collection's own pages, with the closest marked Suggested, and each states what it changes ("Quote moved up · Text blocks joined"). The choice is shared across the piece, so it is a content decision, not a per-user preference — decide it before the review round, not during.

Let it link, then prune. First drafts now arrive with two to five internal links (roughly one per 250 words), each verified by a second call, and every routed collection and taxonomy term page is a valid target while drafts, noindex pages and utility pages are excluded. Added links are marked in the Text and Blocks tabs with Remove link. Link to your other pages in Finish this page handles the reverse case: a page of 300+ words with no internal links gets a step-by-step "Link '…' to Contact us?" prompt. If your routing or noindex conventions are inconsistent, fix them — the linking engine reads those signals directly.

Handle gaps in place. Facts to add, counts to check and links to choose render as chips in Preview and the Text tab, and as a row under plain-text publish fields. The saved entry keeps its markers until each chip is resolved, and an unresolved fact or count blocks publishing. Make sure your content migration and import scripts tolerate those markers in stored values — do not strip them as junk.

Questions, and when to skip them. Ghostwriter asks at most four short questions, each with its own box or choices, flagged (optional) where applicable, with Skip and Just draft it with what you have. For automated or bulk drafting, take the "just draft it" path and let the chips surface what is missing; for high-value pages, answer them — the extras are drawn only from what you supply, so unanswered questions produce a thinner draft.

Model it on picks as a soft default. In a collection with no learned kind, the brief arrives with up to six published entries ticked, closest in purpose and shape. Your own ticks always win. Seed a new collection with good exemplars and the auto-picks stay sane; seed it with legacy junk and every subsequent draft inherits that shape.

Keep a template heading audit. Drafts start at H2 under the page's H1, never skip a level and respect per-field allowed levels; the Preview reads how your template prints headings. Super users see an Overview note when a template prints no H1 or several. Fix those layouts — it is a cheap, permanent quality win for every future draft.

Gotchas and Tips

• Version pinning is the first failure mode. Statamic 6.30 and PHP 8.3 are hard requirements. ghostwriter-core ^1.10 must be allowed to resolve; a stray composer.lock constraint will produce a confusing install failure rather than a clear message.
• Nothing is saved except alt text. Accepted wording goes into the form and the human still saves. If you are scripting against the addon, do not expect an API that persists accepted suggestions.
• Alt-text writes are shared and confirmed. One acceptance can touch many pages using the same image; the confirm states the count before sending. There is no obvious per-page undo for that write, so check shared hero and logo images before accepting.
• Cost confirms are the safety rail — do not bypass them. Every paid operation announces its price first. If you build automation, preserve that gate; an accidental loop of Another version or Try again is the realistic way to burn budget.
• Try again is a paid call, not a free reroll. This applies to the SEO description and to Shorten a heading ("Write it for me", one small call). Editors will treat both as free; brief them.
• A failing preview template degrades, it does not break. You get the reason, plus Show blocks instead and Try again. Raise preview.timeout for slow layouts, and remember previews block third-party scripts — a page that looks broken in Preview may be fine on the front end.
• Third-party scripts are blocked in Preview by design. Do not disable it; allow-list known hosts through preview.script_hosts and guard environment-specific markup with {{ live_preview:ghostwriter }}.
• External link checking is off by default and deliberately slow. When enabled it runs Sundays at 04:00, hits each address at most once a week, throttles to one request per second per site, and marks a link broken only after two consecutive failures. That means a genuinely dead link can take two weeks to appear — do not "fix" the checker to be faster, and warn editors that the first run after enabling is not a complete picture.
• Stale revisit data looks like a bug. If entries are created, renamed or deleted outside normal saves (imports, direct DB work, queue jobs), the index only catches up on the daily 03:00 run or the weekly full pass. Run php please ghostwriter:revisit by hand after bulk operations.
• revisit.age_in_full expects collection handles. An empty value means "none"; a typo in a handle silently excludes the collection from age weighting, so copy handles from the blueprint rather than typing them.
• Revisit respects permissions. Only collections the user can view are listed, so an editor reporting "pages are missing" is usually a role problem, not an indexing problem.
• Age and claims checks are heuristics. "New for 2024" and "our team of 6" are pattern matches; suggest.claims can be turned off per environment if false positives drown the real ones. Expect a tuning period after enabling.
• Shared decisions persist. Dismissals and "It's still right" verdicts are remembered across users. A single early dismissal can suppress a valid suggestion for everyone — audit dismissals when output quality is questioned rather than re-running blindly.
• Concurrent comment applies are skipped, not merged. "Skipped because someone else changed the block" is the expected outcome of two people applying comments at once; resolve it by re-reading and re-applying, not by retrying in a loop.
• Comment state is browser-local until applied. Clearing site data loses unapplied comments. Comment mode is toggled with Alt+Shift+C above the Preview.
• Gap markers persist in stored content. Fact, count and link markers remain in the entry until resolved, and unresolved facts and counts block publishing. Make sure front-end rendering tolerates them so a half-finished draft in a staging environment does not leak markers publicly.
• Layout comparison is shared state. Choosing a layout changes what everyone sees on that piece; there is no personal override, so treat it as a publish-adjacent decision.
• Heading output is bounded by your blueprints. If a draft "will not use H3", the Bard field probably does not allow it. Check the fieldset before filing a bug.
• Extension point for your own templates is narrow on purpose. The supported hook is the live_preview:ghostwriter conditional plus preview.* config. Do not patch the addon to alter preview headers; the privacy and noindex guarantees are the reason they exist.