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.
- The manifest lists the stack, the source ownership, the roles, the tasks, and the gates in one place.
- Each task names its allowed paths, its commands, and the conditions that stop the run.
- A check validates the manifest, the roles, the tasks, and the brand rules before any work begins.
npm run agent:checknpm run agent:context
agents architecture diagram. Nodes: ingress, router, planner, executor, state, audit. Flow: ingress to router (primary); router to executor (primary); executor to state (primary); router to planner (supporting); planner to state (supporting); executor to audit (feedback).
02
Copy and tone of voice
Deterministic linting keeps the writing in my voice; an optional model pass humanizes drafts, and the gates decide what stays.
- The copy check runs one-pattern rules plus a density-weighted anti-slop audit across English and Italian.
- A fix step applies the safe, deterministic replacements without touching meaning.
- 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
tools architecture diagram. Nodes: agent, policy, MCP, adapter, tool, audit. Flow: agent to MCP (primary); MCP to adapter (primary); adapter to tool (primary); agent to policy (supporting); policy to adapter (supporting); tool to audit (feedback).
03
Full automation loops
Scheduled GitHub Actions jobs refresh content, draft articles, and propose SEO changes. They open pull requests — never direct commits to main.
- The weekly refresh translates missing articles, fills Italian UI keys, generates grounded FAQ and takeaways, humanizes drafts, rebuilds feeds, and runs content health on the built site.
- Monthly loops draft one grounded article behind originality gates and an advisory judge, and turn Search Console demand into SEO meta proposals plus topic-gap briefs.
- A showcase loop proposes case studies from public repositories, and merges one only with every gate green; CI rescue attempts fixes on ci-failure issues with Codex and never merges its own work.
- Automation pushes through a GitHub App token so Flash CI runs on the PR; dirty runs get needs-human, and every automation PR carries needs-translation-review.
npm run content:mapnpm run copy:ai-review:full -- --writenpm run article:judge
workflow architecture diagram. Nodes: start, branch, retry, gate, commit, checkpoint. Flow: start to branch (primary); branch to gate (primary); gate to commit (primary); branch to retry (supporting); retry to branch (loop); gate to checkpoint (feedback).
04
Publication pipeline
Archived software releases live in a separate repository. The site consumes Zenodo concept DOIs through a registry, sync script, and drift gate — never auto-updated in build.
- The software repo publishes a GitHub release, reserves a new Zenodo version DOI, and syncs CITATION.cff from release.toml.
- publications.json is the site registry: concept DOI for public copy, version DOI and publishedVersion for drift checks.
- publication:sync refreshes the registry from Zenodo and GitHub, propagates concept DOIs into catalog and project copy, and regenerates landing JSON-LD.
- publication:check fails CI when github-stats, consumer files, or Zenodo metadata drift; a human reviews the PR before merge.
npm run publication:syncnpm run publication:check
memory architecture diagram. Nodes: event, encode, episodic, semantic, recall, compress. Flow: event to encode (primary); encode to semantic (primary); semantic to recall (primary); encode to episodic (supporting); episodic to recall (supporting); recall to compress (feedback).
05
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.
- Static routes live in a single shared list that feeds both the sitemap and the llms.txt index.
- Every page carries JSON-LD: a person, the breadcrumb trail, and a type that fits the page.
- A Search Console loop and a topic-gap report point me at what to write next; a manual GEO baseline tracks mentions and citations in AI answers.
npm run seo:checknpm run topic:gap
retrieval architecture diagram. Nodes: docs, chunks, vector, lexical, rerank, eval. Flow: docs to chunks (primary); chunks to vector (primary); vector to rerank (primary); chunks to lexical (supporting); lexical to rerank (supporting); rerank to eval (feedback).
06
Quality gates
One command runs the full pre-merge gate: types, lint, format, tests, content health, parity, and generated-output drift.
- The quality check is the local equivalent of the gate that CI runs on every change.
- Generated files are regenerated and compared, so stale output fails the build instead of slipping through.
- A governance check guards the public docs against claims I no longer make.
npm run quality:check
evals architecture diagram. Nodes: trace, cases, score, regress, report, fix. Flow: trace to cases (primary); cases to score (primary); score to report (primary); score to regress (feedback); regress to fix (supporting); fix to trace (loop).
07
Deterministic build
The production build is pure: it prerenders every route, writes markdown mirrors for readers and models, and calls no external model.
- Vite builds the app, then a prerender step writes static HTML for each localized route.
- Markdown mirrors of each article ship next to the HTML for machine readers.
- The container serves the result; nothing on this path depends on an API key.
npm run build
memory architecture diagram. Nodes: event, encode, episodic, semantic, recall, compress. Flow: event to encode (primary); encode to semantic (primary); semantic to recall (primary); encode to episodic (supporting); episodic to recall (supporting); recall to compress (feedback).
08
CI and deploy
Flash CI builds the site, scans rendered pages, and runs browser checks; a green main run triggers a supersede-safe deploy to production.
- After the pre-merge gates pass, CI runs a production build, content:scan on dist/, and a bundle-size budget check.
- A separate browser job downloads that build and runs contrast and visual-regression checks before merge is allowed.
- Deploy follows a successful Flash CI run on main, pushes arm64 images to GHCR, and verifies production serves the new commit.
npm run buildnpm run content:scannpm run perf:budget
evals architecture diagram. Nodes: trace, cases, score, regress, report, fix. Flow: trace to cases (primary); cases to score (primary); score to report (primary); score to regress (feedback); regress to fix (supporting); fix to trace (loop).