nibula 2.0.2 → 2.1.0

package/docs/Deploy.md

@@ -1,221 +1,279 @@
 # Deploy
 
-Nibula builds a static site into `out`. Publishing means uploading that folder to
-a web server. What you need depends on **where** you publish and **which
-backend** you chose (see `docs/Backend.md`).
+Nibula builds your finished site into a folder called `out`. Publishing means
+copying that folder onto a web server so people can reach it.
 
-## The one constraint that decides everything
+How you do that depends on two things: **where** you are publishing, and **which
+backend** you picked when you created the project (see `docs/Backend.md`).
 
-The two backends run in fundamentally different ways:
+## Start here
 
-- **PHP** is executed **per request** by the web server through PHP-FPM. There is
-  no process to keep alive — the server starts it, it answers, it exits.
-- **Node** **is** the server: a long-running process listening on
-  `127.0.0.1:3000`, which the web server reverse-proxies `/api` to. Something has
-  to start it and keep it alive across reboots and crashes.
+If you don't know which case you are in, answer this first:
 
-This is why **shared hosting cannot run the Node backend**. On Aruba, cPanel and
-similar, you upload files into a web root — you have no shell to start a daemon,
-no systemd, and any process you did manage to launch would be killed. If your
-host is shared hosting, choose PHP. It is not a limitation of Nibula.
+**Did you choose the PHP backend or the Node backend?**
+
+- **PHP** → almost anywhere works, including cheap hosting plans. Jump to
+  *Shared hosting* or *Windows hosting*.
+- **Node** → you need a server you control. Jump to *Your own server*.
+- **No `/api` endpoints at all?** Your site is fully static. Anything works,
+  including free hosting like Netlify or GitHub Pages.
+
+## Why the backend decides everything
+
+The two backends run in completely different ways, and this is the one thing
+worth understanding before you pick a host.
+
+**PHP** runs **once per visit**. A request arrives, the web server starts PHP,
+PHP answers, PHP exits. Nothing stays running, so there is nothing to look after.
+
+**Node is itself a server**. It is a program that must stay running all the time,
+listening in the background, while the web server forwards `/api` requests to it.
+Somebody has to start that program and restart it if the machine reboots or the
+program crashes.
+
+That is why **cheap shared hosting cannot run the Node backend**. On plans like
+Aruba or cPanel you upload files into a folder and that's all you can do — there
+is no way to start a program and keep it alive. If that's your host, choose PHP.
+It isn't a limitation of Nibula.
+
+> **Shared hosting** means a plan where you share a server with other customers
+> and only get a folder to upload into. **A VPS** is a whole machine that is
+> yours, where you can install and run whatever you want.
 
 ## Where you can publish
 
 | Target | Frontend | PHP backend | Node backend |
 |---|---|---|---|
-| Shared hosting (Apache — Aruba, cPanel) | ✅ | ✅ | ❌ no persistent process |
-| Windows hosting (IIS) | ✅ | ✅ FastCGI | ⚠️ needs ARR reverse proxy |
+| Shared hosting (Apache — Aruba, cPanel) | ✅ | ✅ | ❌ no program can stay running |
+| Windows hosting (IIS) | ✅ | ✅ | ⚠️ only with the ARR module |
 | Your own VPS (Nginx on Ubuntu) | ✅ | ✅ | ✅ |
 | Static hosting (Netlify, Vercel, GitHub Pages) | ✅ | ❌ | ❌ |
 
-Static hosting serves files and nothing else — fine if your site has no `/api`
-endpoints, unusable otherwise.
+Static hosting serves files and nothing else. Perfect if your site has no `/api`
+endpoints, unusable if it does.
 
-## Requirements
+## What you need
 
-**PHP backend:** a server with PHP support and Composer for the backend
+**PHP backend:** a host with PHP support, and Composer to install the backend's
 dependencies.
 
-**Node backend:** Node.js 18+ and shell access to run a persistent process — a
-VPS you control.
+**Node backend:** Node.js 18 or newer, and command-line access to the server so
+you can start the backend program.
 
 ## Editing the server config
 
-`.htaccess` and `web.config` are in the root of `out`, ready to upload. To change
-a rule, edit the source in `src/frontend/hosting/` — a change made directly in
-`out` is lost on the next build.
+Every server needs a configuration file telling it how to behave — which page to
+show on a 404, which files to keep private, where to send `/api` requests. Nibula
+writes these for you.
+
+`.htaccess` (Apache) and `web.config` (IIS) are already inside `out`, ready to
+upload. To change a rule, edit the original in `src/frontend/hosting/` — anything
+you change directly inside `out` is erased the next time you build.
 
-`nginx.conf` works differently: it sits in the project root and is **not** part
-of `out`, because nginx reads no per-directory config. You install it on the
-server by hand, as described below.
+`nginx.conf` is different. It sits in your project root and is **not** copied into
+`out`, because Nginx does not read config files from the site folder. You install
+it on the server yourself, as described below.
 
 ---
 
 ## Shared hosting (Apache)
 
-Upload the **contents of `out`** to the web root (often `htdocs`, `public_html`
-or `www`). Done — `.htaccess` is already inside `out` and Apache reads it
-automatically: directory listing off, 403/404 → `/404.html`, sensitive files
-blocked, backend source sealed, `/api/*` routed.
+Upload **the contents of `out`** — not the folder itself — into your web root.
+Depending on the host it is called `htdocs`, `public_html` or `www`.
 
-**Backend routing:** if `mod_proxy` is available, `/api` is proxied to Node on
-`127.0.0.1:3000`; if not — the usual case on shared hosting — `/api` is
-rewritten to the PHP front controller. To force PHP on a proxy-enabled server,
-comment the `mod_proxy` block in `.htaccess`.
+That's it. `.htaccess` is already in there and Apache reads it automatically:
+folder listings are off, errors show your `/404.html`, sensitive files are
+blocked, the backend source is sealed off, and `/api/*` is routed.
+
+**How `/api` gets routed:** if the server has a module called `mod_proxy`, `/api`
+is forwarded to Node. If it doesn't — the usual case on shared hosting — `/api`
+goes to PHP instead. To force PHP on a server that does have `mod_proxy`, comment
+out the `mod_proxy` block in `.htaccess`.
 
 ## Windows hosting (IIS)
 
-Same idea: upload the contents of `out`, `web.config` is already there and read
-automatically.
+Same as above: upload the contents of `out`. `web.config` is already there and
+read automatically.
 
-**Backend routing:** `/api` is rewritten to the PHP front controller. To use the
-Node backend instead, uncomment the `ApiToNode` rule in `web.config` and delete
-`ApiToPhp` — this needs the ARR and URL Rewrite modules with proxying enabled,
-so a server you control, not shared hosting.
+**How `/api` gets routed:** to PHP, by default. To use Node instead, uncomment
+the `ApiToNode` rule in `web.config` and delete `ApiToPhp`. This only works if
+the server has the ARR and URL Rewrite modules with proxying turned on — which
+means a server you control, not shared hosting.
 
-> ⚠️ **If you chose the Node backend and your host has no ARR** (Aruba and other
-> Windows shared hosting), don't upload the `backend` folder at all. The static
-> site works, and `/api/*` answers with your `404.html`. Upload it and every
-> `/api` request returns an empty 404 instead: IIS rewrites it onto the PHP
-> front controller, which a Node project doesn't contain.
+> ⚠️ **If you chose Node and your host has no ARR** (Aruba and most Windows
+> shared hosting), do **not** upload the `backend` folder. Without it the static
+> site works fine and `/api/*` simply shows your `404.html`. Upload it and every
+> `/api` request returns an empty 404 instead, because IIS sends the request to
+> the PHP front controller — a file a Node project doesn't have.
 
 ---
 
 ## Your own server (Nginx on a VPS)
 
-Nginx doesn't read per-directory config files — the whole site lives in one file.
-Nibula ships `nginx.conf` in the project root as a ready-to-use site file that
-**covers both backends without edits**: `/api` goes to Node, and if Node is
-unreachable the request falls through to PHP automatically.
+Nginx doesn't read config files from the site folder: the whole site is described
+in one file kept elsewhere on the machine. Nibula ships that file, ready to use,
+as `nginx.conf` in your project root.
+
+It **handles both backends with no edits**: `/api` goes to Node, and if Node
+isn't running the request falls through to PHP automatically.
+
+Upload the contents of `out` to `/var/www/SITE_FOLDER`, then work through the
+steps below.
 
-Upload the contents of `out` to `/var/www/SITE_FOLDER`, then follow the steps
-below.
+### 1. Fill in the placeholders
 
-### 1. Replace
+Open `nginx.conf` on your computer and replace these four words with your own
+values:
 
-| Placeholder | Where |
+| Placeholder | What to put there |
 |---|---|
-| `YOUR_DOMAIN` | `server_name`, twice (port 80 and 443) |
-| `SITE_FOLDER` | document root under `/var/www/` |
-| `YOUR_CERTIFICATE` | dir under `/etc/letsencrypt/live/` |
-| `SITE_NAME` | file name in the commands below |
+| `YOUR_DOMAIN` | your domain — appears twice, once for port 80 and once for 443 |
+| `SITE_FOLDER` | the folder name you used under `/var/www/` |
+| `YOUR_CERTIFICATE` | the folder name under `/etc/letsencrypt/live/` |
+| `SITE_NAME` | the file name you'll use in the commands below — pick anything |
 
-### 2. Install (skip if already present)
+### 2. Install what's missing
+
+Skip anything already installed.
 
 ```bash
 sudo apt update
 sudo apt install -y nginx certbot python3-certbot-nginx
 ```
 
-If you are using PHP as backend:
+With the PHP backend, also:
 
 ```bash
 sudo apt install -y php-fpm
 ```
 
-### 3. Certificate
+### 3. Get an HTTPS certificate
+
+This is what makes your site load over `https://` instead of `http://`.
+Certificates are free and last 90 days; the second command renews them
+automatically.
 
 ```bash
 sudo certbot certonly --nginx --cert-name SITE_NAME -d YOUR_DOMAIN
-sudo systemctl enable --now certbot.timer      # auto-renew every 90 days
+sudo systemctl enable --now certbot.timer
 ```
 
-### 4. Install the site
+### 4. Install the site file
 
 ```bash
-# Move to nginx folders
+# Go to the folder where Nginx keeps site files
 cd /etc/nginx/sites-available
 
-# Create and write a new file
+# Create the file and paste in the contents of your edited nginx.conf
 sudo nano SITE_NAME
-# CTRL + O, ENTER, CTRL + X
+# Paste, then: CTRL + O, ENTER, CTRL + X
 
-# Copy the config to sites-enabled
+# Switch the site on by copying it into sites-enabled
 sudo cp SITE_NAME ../sites-enabled/
 
-# Test and reload the nginx configuration
+# Check the config for mistakes, then apply it
 sudo nginx -t && sudo systemctl reload nginx
 ```
 
-### If it fails
+If `nginx -t` reports an error, fix it before reloading — Nginx keeps running on
+the old config until the reload succeeds, so your site stays up.
 
-| Symptom | Cause |
+### If something goes wrong
+
+| What you see | What it usually means |
 |---|---|
-| `cannot load certificate ... Permission denied` | `nginx -t` needs sudo |
+| `cannot load certificate ... Permission denied` | you ran `nginx -t` without `sudo` |
 | `cannot load certificate ... No such file` | wrong certificate name |
-| `no alternative certificate subject name` | certificate doesn't cover domain |
-| `unknown directive "http2"` | nginx < 1.25, check with `nginx -v` |
-| NXDOMAIN / timeout during certbot | DNS not pointing here |
-| 500 instead of the 404 page | `404.html` missing |
-| 502 on `/api`, Node deployed | Node process not running |
-| 502 on `/api`, PHP deployed | wrong php-fpm socket path |
+| `no alternative certificate subject name` | the certificate doesn't cover this domain |
+| `unknown directive "http2"` | Nginx older than 1.25 — check with `nginx -v` |
+| NXDOMAIN or a timeout during certbot | your domain's DNS isn't pointing at this server yet |
+| A blank 500 instead of your 404 page | `404.html` is missing from the upload |
+| 502 on `/api`, Node backend | the Node program isn't running |
+| 502 on `/api`, PHP backend | wrong php-fpm socket path in the config |
 
 ---
 
 ## Starting the Node backend on the server
 
-After uploading `out`:
+Only for the Node backend. After uploading `out`:
+
+**1. Install its dependencies**
+
+```bash
+cd /var/www/SITE_FOLDER/backend
+npm install
+```
+
+**2. Create its config file**
 
-1. Install the backend's runtime deps:
-   ```bash
-   cd /var/www/SITE_FOLDER/backend
-   npm install
-   ```
+Make sure `config.js` exists in `out/backend/`. If it doesn't, copy
+`example.config.js` to `config.js` and fill in your values.
 
-2. Make sure `config.js` exists in `out/backend/` (copy `example.config.js` if
-   missing) and fill in your values.
+**3. Try it out first**
 
-3. Start it in a new screen:
-   ```bash
-   screen -S node-backend
-   # In the new screen terminal:
-   sudo node /var/www/SITE_FOLDER/backend/_core/index.js
-   curl http://127.0.0.1:3000/api/example-public
-   ```
+`screen` lets you start a program, walk away, and come back to it later. Use it
+to check the backend actually works before setting it up properly.
 
-4. Exit the screen without closing the process with `CTRL + A`, `D`. To resume
-   the screen type `screen -r node-backend`.
+```bash
+screen -S node-backend
+# Inside the new screen:
+sudo node /var/www/SITE_FOLDER/backend/_core/index.js
+curl http://127.0.0.1:3000/api/example-public
+```
 
-5. For production use **systemd**, which also restarts on crash and reboot.
-   Create `/etc/systemd/system/backend-node.service`:
+If `curl` prints a JSON response, the backend is alive. Press `CTRL + A` then `D`
+to leave the screen without stopping the program; `screen -r node-backend` brings
+you back.
 
-   ```ini
-   [Unit]
-   Description=Nibula Node backend
-   After=network.target
+**4. Then set it up for real**
 
-   [Service]
-   Type=simple
-   User=www-data
-   WorkingDirectory=/var/www/SITE_FOLDER/backend
-   ExecStart=/usr/bin/node /var/www/SITE_FOLDER/backend/_core/index.js
-   Restart=always
-   RestartSec=5
+`screen` is for testing — the program dies if the server reboots. For a live site
+use **systemd**, the part of Linux that manages background programs. It starts
+your backend at boot and restarts it if it crashes.
 
-   [Install]
-   WantedBy=multi-user.target
-   ```
+Create `/etc/systemd/system/backend-node.service`:
 
-   Adjust `WorkingDirectory` and the `node` path (`which node`), then:
+```ini
+[Unit]
+Description=Nibula Node backend
+After=network.target
+
+[Service]
+Type=simple
+User=www-data
+WorkingDirectory=/var/www/SITE_FOLDER/backend
+ExecStart=/usr/bin/node /var/www/SITE_FOLDER/backend/_core/index.js
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Adjust `WorkingDirectory`, and check the path to `node` with `which node`. Then:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now backend-node
+sudo systemctl status backend-node
+```
 
-   ```bash
-   sudo systemctl daemon-reload
-   sudo systemctl enable --now backend-node
-   sudo systemctl status backend-node
-   ```
+The last command should say `active (running)`.
 
-   (`pm2` works too: `pm2 start _core/index.js --name backend-node`.)
+(If you already use `pm2`, that works too:
+`pm2 start _core/index.js --name backend-node`.)
 
-### Environment variables
+### Settings the Node backend reads at startup
 
-Read by the Node backend at startup. Set them in the systemd unit with
-`Environment=KEY=value`.
+These are set in the systemd file, on their own lines, as
+`Environment=KEY=value`. All three have sensible defaults — you usually don't
+need to touch them.
 
-| Variable | Default | Purpose |
+| Setting | Default | What it does |
 |---|---|---|
-| `PORT` | `3000` | Port Node listens on (must match the proxy target in `nginx.conf`) |
-| `HOST` | `127.0.0.1` | Bind address — keep it local; the web server is the public face |
-| `DOCUMENT_ROOT` | auto (`SITE_FOLDER/`) | Where `404.html` lives; detected as the folder above `backend/` |
+| `PORT` | `3000` | the port Node listens on — must match the one in `nginx.conf` |
+| `HOST` | `127.0.0.1` | keep this as-is: it means "local only", so Node is reachable through the web server and not directly from the internet |
+| `DOCUMENT_ROOT` | detected automatically | where `404.html` lives — the folder above `backend/` |
 
-Error verbosity is **not** an environment variable: it is the `APP_ENV` key in
-`config.js` / `config.php`. See `docs/Backend.md`.
+> Error detail is **not** set here. That's the `APP_ENV` key inside `config.js` /
+> `config.php` — see `docs/Backend.md`.

package/docs/Head and SEO.md

@@ -1,8 +1,22 @@
 # Head & SEO
 
-Global settings live in `src/frontend/data/site.json` and are available everywhere via `{{ site.* }}`.
+The `<head>` of an HTML page holds the information *about* the page rather than
+its content: the title shown in the browser tab, the description search engines
+display, the image that appears when someone shares the link. Nibula writes all
+of it for you — you just fill in the values.
 
-## Global fields
+There are two files to fill in:
+
+- **`src/frontend/data/site.json`** — settings for the whole site
+- **`src/frontend/data/pages.json`** — settings for one page at a time
+
+A page uses its own value when it has one, and falls back to the site-wide value
+when it doesn't. So filling in `site.json` well means most pages need nothing.
+
+## Site-wide settings
+
+Everything in `site.json` is available anywhere in your templates as
+`{{ site.something }}`.
 
 ```json
 {
@@ -29,24 +43,26 @@ Global settings live in `src/frontend/data/site.json` and are available everywhe
 }
 ```
 
-| Field | Purpose |
+| Field | What it's for |
 |---|---|
-| `site_name` | Brand name (used in meta tags and JSON-LD) |
-| `title` | Default page title — fallback when a page has no `seo.title` |
-| `description` | Default meta description — fallback for pages |
-| `keywords` | Default meta keywords — fallback for pages |
-| `domain` / `url` | Canonical URLs, `og:url`, JSON-LD |
-| `lang` | HTML `lang` attribute |
-| `author` | Meta author and JSON-LD author |
-| `theme` | Site color scheme (`light` / `dark`) — sets `data-theme`, `data-bs-theme` and `color-scheme` |
-| `theme_color` | Browser UI / PWA bar color — should match the chosen `theme` |
-| `logo` | Path to the logo, also used as social image |
-| `legal.privacy` / `cookie` / `terms` | Legal page URLs |
-| `legal.copyright.year` / `text` | Footer copyright |
-
-## Per-page SEO and CDN
-
-Per-page settings live in `src/frontend/data/pages.json`, available via `{{ pages.* }}`. Each page is keyed by its camelCase `title` from the front matter, at the root of the file:
+| `site_name` | Your brand or project name |
+| `title` | Default page title — used by any page that doesn't set its own |
+| `description` | Default description — same idea |
+| `keywords` | Default keywords — same idea |
+| `domain` / `url` | Used to build full page addresses for search engines and social previews |
+| `lang` | The language of your site (`en`, `it`, ...) |
+| `author` | Your name |
+| `theme` | Colour scheme of the site: `light` or `dark` |
+| `theme_color` | Colour of the browser bar on phones — should match your theme |
+| `logo` | Path to your logo, also used as the image in social previews |
+| `legal.privacy` / `cookie` / `terms` | Addresses of your legal pages — the footer links to them |
+| `legal.copyright.year` / `text` | The copyright line in the footer |
+
+## Per-page settings
+
+`pages.json` holds one entry per page, and the assistant creates it for you when
+you add a page. Each entry is keyed by the page's `title` from its front matter —
+the camelCase one.
 
 ```json
 {
@@ -66,20 +82,23 @@ Per-page settings live in `src/frontend/data/pages.json`, available via `{{ page
 }
 ```
 
-| Field | Purpose | If empty / absent |
+| Field | What it's for | If you leave it empty |
 |---|---|---|
-| `seo.title` | Page title, and the page's label in `llms.txt` | Falls back to global `title` |
-| `seo.description` | Meta description, and the page's summary in `llms.txt` | Falls back to global `description` |
-| `seo.keywords` | Meta keywords | Falls back to global `keywords` |
-| `seo.noindex` | If `true`, emits `<meta name="robots" content="noindex, follow">` and drops the page from both the sitemap and `llms.txt` | Page is indexable |
-| `seo.canonical` | Absolute canonical URL override | Computed as `url + page.url` |
-| `cdn.css` / `cdn.js` | Extra per-page CDN links | No extra links loaded |
+| `seo.title` | The page's title, shown in the browser tab and in search results | Uses the site-wide `title` |
+| `seo.description` | The short summary search engines show under the title | Uses the site-wide `description` |
+| `seo.keywords` | Keywords for this page | Uses the site-wide `keywords` |
+| `seo.noindex` | Set to `true` to ask search engines **not** to list this page | The page can be found normally |
+| `seo.canonical` | The one official address of this page, if the same content is reachable at more than one URL | Worked out automatically |
+| `cdn.css` / `cdn.js` | Extra stylesheets or scripts loaded from the internet, on this page only | Nothing extra is loaded |
 
-The assistant creates the stub entry when you add a page; a page left with the placeholder description will advertise itself that way to AI crawlers.
+> ⚠️ The assistant fills new entries with placeholder text like `"Description"`.
+> Replace it — a page left that way tells search engines and AI crawlers that its
+> description is literally "Description".
 
-## Fallback logic
+### How the fallback works
 
-Global values are defaults, not duplicates. A page value is used when present; otherwise the global one applies:
+Site-wide values are defaults, not duplicates. You don't need to repeat them per
+page. This is what the template actually does:
 
 ```njk
 {{ pageData.seo.title or title or site.title }}
@@ -87,11 +106,15 @@ Global values are defaults, not duplicates. A page value is used when present; o
 {{ pageData.seo.keywords or site.keywords }}
 ```
 
-`noindex` and `canonical` have no global default: `noindex` defaults to indexable behavior, `canonical` is computed from the URL. They exist per-page only.
+Read it as: use the page's value; if there isn't one, use the site's.
+
+`noindex` and `canonical` work per-page only — there's no site-wide version,
+because "hide the whole site from search" and "one address for the whole site"
+aren't things you'd want.
 
 ## Theme
 
-`theme` is a single fixed value that drives the whole site:
+One value in `site.json` controls the colour scheme everywhere:
 
 ```njk
 <html data-theme="{{ site.theme }}" data-bs-theme="{{ site.theme }}">
@@ -99,20 +122,24 @@ Global values are defaults, not duplicates. A page value is used when present; o
 <meta name="theme-color" content="{{ site.theme_color }}">
 ```
 
-| Attribute | Purpose |
+| What it sets | Why it's there |
 |---|---|
-| `data-theme` | Your own hook — target it in SCSS to define theme variables |
-| `data-bs-theme` | Bootstrap's color mode. Ignored (harmless) if you use another framework |
-| `color-scheme` | Standard CSS — makes scrollbars, form controls and autofill follow the theme |
-| `theme-color` | Color of the browser UI bar on mobile |
+| `data-theme` | Your own hook — target it in your SCSS to define theme colours |
+| `data-bs-theme` | Bootstrap's dark mode switch. Harmlessly ignored with other frameworks |
+| `color-scheme` | Standard CSS — makes scrollbars, form fields and autofill match your theme |
+| `theme-color` | The colour of the browser bar on phones |
 
-Keep `theme` and `theme_color` consistent: a `dark` theme with a white `theme_color` gives a white browser bar over a dark page.
+Keep `theme` and `theme_color` in agreement: a dark theme with a white
+`theme_color` gives a white browser bar sitting on top of a dark page.
 
-See the SCSS docs for how to hook your variables to `data-theme`.
+See the **Styling with SCSS** DOC file for how to hook your own colours to
+`data-theme`.
 
 ## Favicon
 
-The three favicon tags are hardcoded in `base.njk`. To change the icons, replace the files in `src/frontend/assets/brand/` keeping the same names:
+The favicon is the small icon in the browser tab. The three tags are written
+directly in `base.njk`. To change the icons, replace the files in
+`src/frontend/assets/brand/` **keeping the same names**:
 
 ```html
 <link rel="icon" type="image/svg+xml" href="{{ '/assets/brand/favicon.svg' | url }}">
@@ -120,37 +147,52 @@ The three favicon tags are hardcoded in `base.njk`. To change the icons, replace
 <link rel="apple-touch-icon" sizes="180x180" href="{{ '/assets/brand/apple-touch-icon.png' | url }}">
 ```
 
-| File | Purpose |
+| File | What uses it |
 |---|---|
-| `favicon.svg` | Modern browsers, scales to any size |
-| `favicon-32.png` | Fallback for older browsers and some crawlers |
-| `apple-touch-icon.png` | iOS home screen icon — 180×180, must be opaque (iOS renders transparency as black) |
+| `favicon.svg` | Modern browsers — scales to any size |
+| `favicon-32.png` | Older browsers and some crawlers |
+| `apple-touch-icon.png` | The icon iOS uses when someone saves your site to their home screen. Must be 180×180 and **not** transparent — iOS turns transparency into black |
 
-> ⚠️ Without `apple-touch-icon.png`, iOS uses a screenshot of the page as the home screen icon.
+> ⚠️ Without `apple-touch-icon.png`, iOS uses a screenshot of your page as the
+> home screen icon instead.
 
-## Where the tags are written
+## Where all this is written
 
-All of the above is rendered by `src/frontend/layouts/base.njk`, which reads the page's record with:
+Everything above is produced by `src/frontend/layouts/base.njk`, which looks up
+the current page's entry like this:
 
 ```njk
 {% set pageKey = title %}
 {% set pageData = pages[pageKey] %}
 ```
 
-Edit the template when you need a tag the boilerplate doesn't cover — a font `<link>`, an analytics snippet. For everything listed here, change the values in `site.json` and `pages.json` instead.
+You only need to edit `base.njk` for something the boilerplate doesn't cover — a
+web font, an analytics snippet. For everything documented here, change the values
+in `site.json` and `pages.json` instead.
 
-> ⚠️ Asset paths in `base.njk` go through the `url` filter. It makes them work when the site is published under a subpath — GitHub Pages being the usual case. Removing it 404s every stylesheet and script there.
+> ⚠️ Paths in `base.njk` go through `| url`. That filter makes them work when the
+> site is published in a subfolder rather than at the root of a domain — GitHub
+> Pages being the common case. Remove it and every stylesheet and script breaks
+> there.
 
-## AI & SEO bots
+## Files for search engines and AI
 
-`llms.txt`, `robots.txt` and `sitemap.xml` are generated from `.njk` templates in `src/frontend/indexing/` and are publicly reachable (they must not be blocked by the server config).
+Three files are generated automatically and published with your site:
 
-| File | Purpose | Reachable at |
+| File | What it's for | Reachable at |
 |---|---|---|
-| `llms.njk` | Describes the site and lists its pages for AI models | `yoursite.com/llms.txt` |
-| `robots.njk` | Controls search-engine crawling | `yoursite.com/robots.txt` |
-| `sitemap.njk` | Lists indexable pages | `yoursite.com/sitemap.xml` |
+| `llms.txt` | Describes your site and lists its pages, for AI models | `yoursite.com/llms.txt` |
+| `robots.txt` | Tells search engines what they may and may not crawl | `yoursite.com/robots.txt` |
+| `sitemap.xml` | Lists your pages so search engines find them all | `yoursite.com/sitemap.xml` |
+
+They are built from templates in `src/frontend/indexing/`. `llms.txt` and
+`sitemap.xml` build their page lists the same way: they go through every page and
+leave out drafts, the 404 page, and anything marked `noindex`. Creating a page
+with the assistant is enough for it to appear in both — there is no list to keep
+up to date by hand.
 
-`llms.njk` and `sitemap.njk` build their lists the same way: they walk every page, then skip drafts, the 404 page, and anything with `seo.noindex` set to `true`. Creating a page with the assistant is enough to have it appear in both — there is no separate list to maintain.
+To change the wording or the fixed parts, edit
+`src/frontend/indexing/llms.njk` or `src/frontend/indexing/robots.njk`.
 
-To customize the wording or the fixed sections, edit `src/frontend/indexing/llms.njk` or `src/frontend/indexing/robots.njk` directly.
+> These three files must stay publicly reachable. If you block them in your server
+> config, search engines and AI models can't read them.