Knowledge layer
Everything the pages, the assistant and the crawlers say about Francesco comes from one compiled file, kb.json, built from Markdown and YAML kept in a private repository and published as /kb.json.
One file is the contract. Content is written once, as Markdown and YAML in the repository's content/ folder. A compiler checks it and emits kb.json, with the images it references beside it, and nothing else is read by anyone. The pages are built from it, the assistant is grounded in it, the structured data and the CV are views of it, and it is published at a stable URL for anything that wants the whole thing. If two surfaces ever disagreed, one of them would have to be reading something else, and there is nothing else to read.
One artefact, many readers
The source is CommonMark with GitHub's extensions and YAML front matter, or plain YAML for structured entities. No MDX and no CMS: files in git, reviewed like code. The compiler runs four stages, load, validate, rules and emit, and reads content/ and nothing else (ADR-0002).
Its output is deterministic: sorted keys, stable order, no wall-clock value anywhere, and a build_id that is a hash of the content. The same content always builds the same bytes, which is what lets the site and the assistant prove they are on the same version. Section bodies ship as the original Markdown slice plus plain text, never as HTML, because rendering is the site's job. The artefact holds text I wrote and nothing else: external sources are cited, never ingested.
The compiler is my own, in TypeScript on unified/remark, with Zod 4 as the schema that also emits the JSON Schema published beside the artefact (ADR-0003). Velite, Astro's content collections and Contentlayer were read first. The hard parts here are sections, anchors, inverted relations and determinism, and none of them does those.
Facts in fields, prose in sections
Each entity is one file. Facts that something has to compare, check or map to structured data live in front matter. Reasoning lives in prose under a heading skeleton the compiler lints (ADR-0004).
A project comes in two depths. A case study must have context, problem, role, decisions and results, and each decision is its own anchored section with the alternatives it beat. An entry carries only the common fields, because forcing that skeleton onto a small utility produces padding.
Relations are written once, on the newer or more specific entity, and the compiler inverts them. A new project names its skills, and nothing on the skill changes. The artefact can still answer "what proves this skill", and a skill that nothing proves fails the build. There are no self-rated levels.
A result is a structured claim with its evidence, and its verifiability has three values: independent (someone else wrote the source), checkable (anyone can inspect the thing itself, such as a published package), or self-reported. A claim that cites my own profile is self-reported however public the profile is. Pages say which one applies in a sentence next to the claim, never as a badge (ADR-0014).
Ids that do not move
Every entity has a typed id, <type>:<key>, separate from its URL slug, and every addressable section has an anchor built on it, <entity-id>#<fragment> (ADR-0006). One string serves four uses: it is the citation an answer carries, the unit the assistant reads, the id of the element on the page, and the target of a suggested question. This section is site:knowledge-layer#section-ids-that-do-not-move.
Every id and anchor is recorded in ids.lock, a committed file. Renaming a slug or a heading without recording an alias fails the check. Once production has served an id or anchor, CI rejects deleting its line, so from launch on the file only grows; before launch, a deletion is reported and passes. A citation stored in an old conversation or a test set keeps resolving after the prose around it is rewritten.
What ages and what is held back
Most facts do not expire, and the few that do carry a date. Availability, offerings, the profile and anything ongoing must record as_of, the day the statement was last confirmed, and each type has a review window (ADR-0007). Past it, nothing breaks. The page says "Last confirmed {month}; not reconfirmed since.", and the assistant gives the date with the fact. The compiler reads no clock, so the artefact is the same on any day, and each reader works out staleness against its own date. A retired entity becomes a tombstone that redirects or answers 410.
Drafts and anything confidential live in a second private repository, and the compiler has no way to read it. Confidential terms are turned into a scan that runs before every commit and again in CI, because pushed history is permanent and the only control that works is the one that runs before the push (ADR-0005). The scan is a tripwire, not a guarantee: it cannot catch a paraphrase, so review before publishing stays my job. A public entity can also mark a topic as withheld, so "that part is not public" is a different answer from "that is not recorded".
Everything is written in English, because a second language is a second copy to keep in step (ADR-0008). The assistant can still answer in Italian, from the English source.
Designed before it was built
The design came before the code. The brief was split into fourteen logical components in five layers, and each open question was closed by an architecture decision record before anything was built (ADR-0001). The brief, the deep-dives and every ADR are kept with the content, in the same private repository.
These How it works pages are summaries of that design, written by hand for a reader rather than copied from it. Each one records the documents it was written from and the commit at which they were read. A drift check lists every page whose sources have changed since, and for the pages that carry a privacy, security, cost or quality claim it blocks the merge (ADR-0009). A reader gets two depths, the summary and the topic page; the design documents behind them stay private.