Seven specialised roles that describe what agentic software is actually being asked to do: read the sources, work inside the repository, audit the search surface, plan the coverage, interrogate the data, run the workflow and probe it for weaknesses. Together they are the map of what this publication covers.
One of them is not a description. The SEO Agent is implemented in this codebase and runs against these articles. Its full pipeline is set out further down the page, human-review gate included.
Analyzing technical knowledge
Reads primary sources — specifications, changelogs, papers and repositories — then reduces them to the handful of claims that actually matter, each traceable back to where it came from.
Reading and writing software
Works inside a repository rather than a chat window: reads the surrounding code, proposes a change, runs the test suite, and iterates on the failure output until the change actually holds.
Auditing search visibility
Audits metadata, heading hierarchy, structured data and internal links against a published scoring model, then returns ranked recommendations for a human to approve — it never rewrites content on its own.
Planning editorial coverage
Maps a topic into an outline, finds the gaps a subject already covered elsewhere leaves open, and proposes structure — the writing and the judgement stay with the author.
Interrogating structured data
Turns a question into a query, runs it, and reports both the answer and the shape of the data behind it — including the rows that do not fit the story.
Orchestrating workflows
Chains tools, APIs and human approval steps into a durable workflow, with retries and checkpoints so a failure halfway through does not mean starting over.
Probing for weaknesses
Threat-models a change before it ships: which inputs are untrusted, which tools an agent can reach, what a compromised step could do, and what the blast radius looks like.
Not a diagram of an idea. Every stage below maps to a function in lib/seo, and the run ends at a person — the agent produces a report and stops.
A writer commits an MDX file with its frontmatter — title, description, category, tags, keywords, type. Nothing runs until that file exists. The agent audits published work; it never drafts it.
content/articles/*.mdx
The article and the rest of the corpus go in, one report comes out. The run is deterministic — no clock, no randomness, no network call in the default configuration — so two runs over the same input produce byte-identical output that can be committed and diffed.
runSeoAgent()
Measures what is actually on the page: word count, reading time, title and description lengths, sentence and syllable averages, and a readability band. Every figure in the report is a measurement rather than an estimate.
readabilityScore()
Code blocks are stripped, the prose is tokenised against a 241-word stopword list, and position-weighted unigrams and bigrams are scored. The result is what the piece is demonstrably about, which can then be held against the keywords its frontmatter claims.
extractKeywords()
Classifies the article as informational, navigational, commercial or transactional, with a confidence value and the specific signals that produced it — so the format can be checked against the intent it is written for.
detectSearchIntent()
Matches the text against a curated lexicon of named technologies, models, protocols and platforms and reports which of them the piece genuinely covers. Those entities are the raw material for both the linking and the schema stages.
extractEntities()
Scores every other article on shared entities, tags, keywords and category adjacency, skips anything already linked, and returns ranked suggestions with anchor text. A companion pass builds the whole link graph to surface orphan pages and broken internal links.
suggestInternalLinks()
Resolves the right schema type — Article, TechArticle or NewsArticle — from the article’s own type and date, then emits JSON-LD describing only what the page shows. No rating, review or price is ever generated, because the site publishes none.
articleSchema()
Builds the canonical URL, Open Graph and X card blocks, robots directives and the publication timeline from the same frontmatter, so what sits in the document head can never drift from what sits in the body.
buildArticleMetadata()
A fixed set of boolean checks across eight areas whose weights sum to exactly 100, returning a score, a grade and a per-check breakdown. A check that cannot be measured fails and states why, rather than being quietly skipped to protect the total.
auditArticle()
The report comes back with review required and status pending. Nothing has been applied. An editor reads the recommendations, accepts the ones that are right for the piece and rejects the rest. The agent has no write access to the article and cannot advance past this point on its own.
humanReview: { required: true, status: 'pending' }
The editor makes the changes they agreed with, and the article ships. The report is kept alongside it, so the next run diffs against a known state instead of starting from scratch.
content/articles/*.mdx
Agent architecture, tool-calling contracts, evaluation and the security surface that opens up the moment a model can act — covered in depth across the publication.