What the agent does
The agent starts from the one template every page passes through. In a Zola site on the even theme, like getzola/even, templates/index.html is the base: page.html, about.html and the taxonomy templates under tags/ and categories/ extend it, and its <head> holds a <meta name="description"> that falls back from page.description to config.description, a {% block title %} that page.html overrides as {{ config.title }} - {{ page.title }}, feed links driven by config.generate_feeds and config.feed_filenames, and an empty {% block extra_head %}. There is no application/ld+json block anywhere in templates/, so search engines see the page's text and nothing about what kind of page it is.
Then it reads what each page knows about itself. templates/post_macros.html prints page.date | date(format="%F") and page.category; page.html renders page.taxonomies.tags as links and page.lower and page.higher for navigation. config.toml sets base_url, title, description, generate_feed = true, two taxonomies categories and tags with feeds, and [extra] author = "Vincent" beside even_title and the menu. Every post under content/ carries +++ front matter with title, date and a [taxonomies] table with categories and tags, and a <!-- more --> marker that gives Zola a summary. theme.toml says min_version = "0.17.0", and .github/workflows/docs.yml builds the demo with shalzz/zola-deploy-action@v0.17.2 on every push to master.
The agent adds templates/structured_data.html and includes it in the base head. When page is defined it emits a BlogPosting with headline from page.title, datePublished from page.date formatted as %Y-%m-%d, dateModified from page.updated when set and page.date otherwise, url and mainEntityOfPage from page.permalink, description from page.description or the stripped page.summary, keywords joined from page.taxonomies.tags, articleSection from the first category, and author as a Person named from page.authors when the post sets them and config.extra.author otherwise. When section is defined instead it emits a WebSite with name, url and description from the config. Every value passes through Zola's json_encode filter, so a title with a quote or an apostrophe produces valid JSON instead of breaking the block, and the partial writes nothing on a taxonomy page with neither variable.
To prove it, the agent downloads the Zola release matching theme.toml's minimum or newer into its sandbox, runs zola check and zola build, and runs a short script over every HTML file under public/ that finds each <script type="application/ld+json">, parses it with a JSON parser and prints the @type, so the pull request shows one BlogPosting per post and one WebSite for the index with no parse error. It also pastes the block from one built post so a reviewer can paste it into a validator.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add JSON-LD structured data to this Zola site. Read config.toml, theme.toml, templates/index.html, templates/page.html, templates/post_macros.html, templates/about.html, the templates under tags/ and categories/, three files under content/ and .github/workflows/docs.yml first. Add templates/structured_data.html and include it in the base template's head: when page is defined emit a BlogPosting with headline, datePublished, dateModified falling back to the date, url, mainEntityOfPage, description from page.description or the stripped summary, keywords from the tags, articleSection from the first category and author as a Person from page.authors or config.extra.author; when section is defined emit a WebSite from the config; emit nothing otherwise. Pass every value through json_encode. Install a Zola release at or above the theme's min_version in your sandbox, run zola check and zola build, then run a script that parses every application/ld+json block under public/ and prints its @type, and paste that output and one built post's block into the pull request. Change no content file and no stylesheet.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request adds templates/structured_data.html and changes templates/index.html by one include line, with nothing under content/, sass/ or static/ touched. Its description shows the zola check and zola build output, the script's list of every page's @type with no parse failure, and the complete block from one built post.
Each post now describes itself as a BlogPosting with its real date, tags, category and author, and the index as a WebSite; taxonomy pages carry no block rather than a wrong one. The rendered pages are otherwise byte-for-byte what the theme produced, since the partial only adds a <script> to the head, and the demo deploy on master keeps working because the workflow and the build are unchanged.
Before merging, a reviewer decides whether config.extra.author is the right fallback or whether every post should name its authors, chooses whether to add a publisher with a logo for rich results, and pastes the quoted block into a validator to see what a search engine would read.
Run it on every Linear issue labelled seo
Add an automation to the Project with this prompt and a linear trigger on linear.issue.labeled with the label your search work uses in its labels. Each labelled issue starts one run with the issue as its context, on its own branch; the trigger adds the issue after the prompt and fills in no placeholder, and a change made by an app integration never fires it, so the agent's own comment on the issue starts nothing.
The automation's max_runs_per_hour holds a burst of labels to that many runs an hour: a fire past it is created queued and starts when the hour has room, and one past a second hour's worth is skipped as rate_limited until the issue is labelled again. From your own server, the same run starts with this request and the issue URL in resources, with a request_id that is a UUID v5 of the issue id so a retried start returns the run already begun.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
Structured data fails quietly: a template that renders fine can emit a block that no parser accepts, and nothing on the page shows it. The agent builds the whole site in its own sandbox and parses every block it produced, so the pull request proves the output rather than the template, and the one post it quotes is the real rendered block.
The transcript keeps the Zola install, the build and the parse script with their output, so a reviewer reads the evidence from one page without building locally. Several Zola sites on the same theme can be given the partial at once, each run in its own sandbox with its own Zola binary, and nothing merges until a person reads the diff.
Frequently asked questions
Why a separate partial instead of editing the head directly?
The base template's head is shared by every page type, and a partial keeps the JSON-LD logic in one file that page.html and the taxonomy templates never need to know about. It is also the only file a site that overrides the theme has to copy to adjust the markup.
What stops a title with a quote from breaking the JSON?
Every value goes through Zola's json_encode filter, which quotes and escapes the string, rather than being written between hand-typed quotes. The parse script the agent runs over public/ is the check that this held for every post in the site.
Does this change what the Open Graph tags say?
No. JSON-LD is a separate block read by search engines, and this change does not add or alter any og: or twitter: meta tag. A site that already has them keeps them; one that wants them is a separate change with its own page.
Will it work on an older Zola?
The partial uses date, json_encode, striptags and the page and section variables, all of which exist at the theme's declared minimum. The agent builds with a release at or above that minimum and names the exact version in the pull request, so a reviewer can match it to their deploy action.