Skip to content

How this site is built

This site runs on explicit agent contracts. Every change to copy, content, or code moves through a small named task with its own context, its allowed paths, and its gates. Language models help inside the automation, never inside the production build, and their output reaches the site only after a reviewed pull request. What follows is the real machinery, in the order a change travels through it.

Principles

Smallest sufficient context

I give each task the least context it needs, generated from the manifest, so a run reasons over a few files instead of the whole repository.

A deterministic build

The production build never calls a model. The same input always produces the same output, so a deploy is reproducible and free of surprises.

Generation is a proposal

Model-written copy is a draft, not a commit. The deterministic gates decide whether it ships, and a human reviews it in a pull request first.

One voice, two languages

Everything I publish stays in the first person, and English and Italian ship together. A parity check fails the build when one language falls behind.

Workflows

The six workflows a change can travel through, from contract to deploy.

01

Agent contracts

A manifest, a set of roles, and one file per task define who does what, where they may write, and when they must stop.

  1. The manifest lists the stack, the source ownership, the roles, the tasks, and the gates in one place.
  2. Each task names its allowed paths, its commands, and the conditions that stop the run.
  3. A check validates the manifest, the roles, the tasks, and the brand rules before any work begins.
npm run agent:checknpm run agent:context

02

Copy and brand voice

Deterministic linting keeps the writing in my voice; an optional model pass humanizes drafts, and the gates decide what stays.

  1. The copy check runs one-pattern rules plus a density-weighted anti-slop audit across English and Italian.
  2. A fix step applies the safe, deterministic replacements without touching meaning.
  3. An AI review lets a model propose rewrites; copy-lint, frontmatter, and parity choose whether to keep them.
npm run copy:checknpm run copy:ai-review -- --changed --write

03

Content automation

A weekly job refreshes the site and drafts articles; a judge gates anything generated before it can merge.

  1. A content map builds a deterministic inventory of articles, projects, locales, and feeds.
  2. A health step turns that map into pass or fail findings, never into silent drift.
  3. The weekly refresh and article generation run the model, then open a pull request for review.
npm run content:check

04

SEO and GEO

The sitemap, the llms.txt index, and the structured data all derive from one route table, so the machine-readable surface never drifts from the site.

  1. Static routes live in a single shared list that feeds both the sitemap and the llms.txt index.
  2. Every page carries JSON-LD: a person, the breadcrumb trail, and a type that fits the page.
  3. A Search Console loop and a topic-gap report point me at what to write next.
npm run seo:checknpm run topic:gap

05

Quality gates

One command runs the full pre-merge gate: types, lint, format, tests, content health, parity, and generated-output drift.

  1. The quality check is the local equivalent of the gate that CI runs on every change.
  2. Generated files are regenerated and compared, so stale output fails the build instead of slipping through.
  3. A governance check guards the public docs against claims I no longer make.
npm run quality:check

06

Deterministic build

The production build is pure: it prerenders every route, writes markdown mirrors for readers and models, and calls no external model.

  1. Vite builds the app, then a prerender step writes static HTML for each localized route.
  2. Markdown mirrors of each article ship next to the HTML for machine readers.
  3. The container serves the result; nothing on this path depends on an API key.
npm run build

Quality gates

Every change clears this full gate before merge. The same set of checks runs in CI.

Agent contractsagent:checkFrontmattervalidateEN/IT parityi18n:check:strictBrand voicecopy:checkContent healthcontent:healthGenerated driftgenerated:checkSEOseo:checkGovernancegovernance:checkTypestypecheckLintlintFormatformat:checkTeststest:run