What the agent does
The agent reads how the site is built before it adds anything, because Zola does half of this job itself and the theme decides the other half. In a site on the Terminimal theme, as in pawroman/zola-theme-terminimal, config.toml sets compile_sass = true, generate_feeds = true with feed_filenames = ["rss.xml", "atom.xml"], a tags taxonomy and an [extra] table whose menu_items list drives the header: blog, tags, archive, about me and github, each with a $BASE_URL placeholder that templates/macros/menu.html replaces with config.base_url. There is no build_search_index key, so Zola writes no index. The README advertises Absolutely no JavaScript, templates/index.html loads no script, and every other template extends it: page.html fills the content block, archive.html is reached through content/pages/archive.md, whose front matter sets path = "archive" and template = "archive.html", and content/pages/_index.md sets render = false so the pages section has no listing of its own.
Zola ships the index. The agent adds build_search_index = true to the top of config.toml and a [search] table with index_format = "elasticlunr_json", include_title = true and include_content = true, the keys the Zola configuration reference lists. With that, zola build writes search_index.en.json and elasticlunr.min.js into public/ next to the HTML, named for default_language, which the theme already reads to set the lang attribute on html. The JSON format is chosen over the default elasticlunr_javascript so the index is fetched only when someone types, instead of being parsed on every page load. Pages that should not be found get in_search_index = false in their front matter: the agent sets it on content/pages/about.md, content/pages/archive.md and the new search page, so the archive's list of titles does not outrank the posts themselves.
The page follows the archive pattern exactly. content/pages/search.md carries title = "Search", path = "search" and template = "search.html"; templates/search.html extends index.html, sets the title through title_macros::title like archive.html does, and fills the content block with a post div holding an input with id="search" and a search-results container. The script goes in the extra_body block that index.html already leaves empty at the end of body, so no other template changes: one script tag for elasticlunr.min.js through get_url and one for a new static/search.js. That file is a trimmed version of the one Zola's own documentation site uses, docs/static/search.js in getzola/zola: it loads the index with elasticlunr.Index.load on the first keystroke, searches with title boosted over body, renders at most ten results with a teaser built around the matched terms, and does nothing until the field has text. Styling reuses the theme's .post and .button classes from sass/post.scss and sass/buttons.scss, so the colour scheme chosen by accent_color applies without a new stylesheet. A sixth entry, {name = "search", url = "$BASE_URL/search"}, joins menu_items.
Then the agent builds and checks. The sandbox has no Zola, so it installs the Linux build from the v0.23.6 release on GitHub, the current one, and runs zola build in the theme's own directory, where config.toml and content/ make the theme its own demo site. It confirms public/search_index.en.json exists and contains the posts but not the about or archive pages, runs zola check for broken links, serves public/ on a local port and opens the search page in its own browser: it types javascript, a word that appears in the titles of learning-javascript.md and i-dont-like-javascript.md, and checks those two posts come back and Zola is nice does not. The theme's README says it was tested with Zola v0.19.2 and theme.toml sets min_version = "0.11.0"; the keys used here exist in that range, and the pull request says so.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add full-text search to this Zola site using Zola's built-in search index and elasticlunr. Read config.toml, templates/index.html, templates/archive.html, templates/macros/menu.html, the content directory and the README first. In config.toml set build_search_index = true and a [search] table with index_format = \"elasticlunr_json\", include_title = true and include_content = true, and add a search entry to extra.menu_items. Add content/pages/search.md with path = \"search\" and template = \"search.html\", a templates/search.html that extends index.html with an input#search and a results container in the content block, and load elasticlunr.min.js plus a new static/search.js in the extra_body block only on that page. Base search.js on the one Zola's documentation site uses: fetch search_index.en.json on the first keystroke, boost title over body, show at most ten results with a teaser. Set in_search_index = false on the about, archive and search pages. Install Zola, run zola build and zola check, confirm public/search_index.en.json lists the posts, open the built site in the browser and confirm a search for a word from one post title returns that post. Do not add scripts to any other template. Open a pull request with the commands you ran and their output.",
"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 changes config.toml, adds content/pages/search.md, templates/search.html and static/search.js, and adds one line of front matter to the about and archive pages. Its description quotes the zola build summary, the zola check result, the list of documents in search_index.en.json, and what the browser showed for the test query, with a screenshot from the run's record. No existing template other than the new one changes, and templates/index.html still loads nothing on the home page, posts, tags and archive, so the theme's promise holds everywhere except the page that needs the script.
A reviewer checks the menu position, whether they want include_description or a truncate_content_length for a site with hundreds of long posts, and whether any other page should carry in_search_index = false. Pulling the branch and running zola serve shows the search page working locally; zola serve writes the index like zola build does, so there is no separate step. For a site that keeps this theme in themes/terminimal rather than as its own repository, the same files go into the site's own templates/, content/ and static/ directories, where Zola lets them override the theme, and the pull request names that path.
Run it on every Zola site with no search
A team with several Zola sites sends this body once per repository from its own server, each POST /o/{org}/sessions naming one repository in resources and carrying a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started rather than a second one. Each run reads its own theme: a site whose theme already ships a search template gets a note in the pull request instead of a second search box, and a site with [languages] in its configuration gets one search page per language, because Zola writes one search_index.<lang>.json per language that has build_search_index on.
The key's webhook_url reports each run the key starts with the pull request URL in result, so a script that sent six requests collects six pull requests without polling.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Search on a Zola site is two decisions, the index and the page, and both need the real build to check: the index is only written by zola build, its contents depend on front matter across the whole content/ tree, and whether a query finds a post depends on the stemming Zola picked from default_language. The agent runs that build in its own sandbox, reads the index it produced, opens the result in a browser and keeps every command and screenshot in the run's record, so the pull request shows a search that works rather than a template that should.
The theme's own constraints shape the change, and the agent reads them from the files: a theme that promises no JavaScript gets the script in the one extra_body block on one page, the search page copies the path and template pattern the archive page already uses, and the menu entry follows the $BASE_URL convention of the five that exist. Ten sites on ten themes get ten pull requests, each fitted to its templates.
Frequently asked questions
Does this need a search service or a server?
No. Zola writes a static index into public/ during zola build, and the browser fetches it from the same host as the pages. Nothing else is deployed, and there is no account or key.
Why elasticlunr rather than Fuse?
Zola bundles elasticlunr.min.js with the index when index_format is one of the two elasticlunr formats, so the page needs no extra dependency, and Zola's own documentation site searches the same way. Setting index_format = "fuse_json" instead produces an index for Fuse or tinysearch, and the pull request notes that switch for a site that already loads Fuse.
Will the theme's no-JavaScript promise still hold?
On every page but one. The script tags live in the extra_body block of templates/search.html only, and templates/index.html, which every other template extends, is unchanged. A reader who wants a search box in the header instead would load the index on every page, and the pull request explains that trade-off without making it.
How do I keep a page out of the results?
Add in_search_index = false to its front matter, or to a section's _index.md to exclude everything under it. The pull request does this for the about and archive pages and the search page itself, so a list of every post title does not match every query.
What about a site in another language?
Zola builds the index for default_language and names the file after it, so a French site gets search_index.fr.json and the script's fetch path changes with it. The Zola documentation notes that a language other than English also needs the matching lunr stemmer script loaded next to elasticlunr.min.js, and the pull request adds that tag when it finds a non-English default_language.