paulca / paulca.com Public

FAQ: one Markdown file per question, plus an AGENTS.md recipe

src/faq/NN-slug.md files are assembled into /faq/ in filename order by
an Eleventy collection; the five existing questions became the first
five files. Agents add a question by adding a file, same as the ledger.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Paul Campbell 3 weeks ago 24c105e34ed1101efb66848063b1a90cafb34408 parent ed7c9de

15 files changed, +130 −49

AGENTS.md +28 −1
README.md +1 −1
docs/ai.html +16 −3
docs/faq/index.html +9 −2
eleventy.config.js +7 −0
src/_data/ledger.json +1 −1
src/faq.md +0 −41
src/faq.njk +15 −0
src/faq/01-who-writes-this-site.md +9 −0
src/faq/02-why-so-plain.md +6 −0
src/faq/03-prompt-carbon-ledger.md +7 −0
src/faq/04-microblog.md +6 −0
src/faq/05-how-published.md +8 −0
src/faq/faq.11tydata.json +3 −0
src/ledger/2026-07-25-11-faq-files.md +14 −0

diff --git a/AGENTS.md b/AGENTS.md

index dad209a..af06b36 100644

--- a/AGENTS.md

+++ b/AGENTS.md

@@ -23,7 +23,9 @@ Follow the recipes below exactly.

- `src/ai.njk` — the ledger page template. The table and running total are

generated from the files in `src/ledger/`; you never edit this file to add

an entry.

-- `src/faq.md` — the FAQ.

+- `src/faq/*.md` — the FAQ at `/faq/`, one Markdown file per question.

+ `src/faq.njk` is the page template that assembles them in filename order;

+ you never edit it to add a question.

- `src/posts/`, `src/microblog/`, `src/assets/`, `src/activity_pub/` — frozen

archives of the old site, copied into `docs/` unchanged. Never edit these.

@@ -122,6 +124,31 @@ Then rebuild and confirm your entry made it into the page:

npm run build

grep "the comparison text from your new entry" docs/ai.html

+## Recipe: add an FAQ entry

+Each question is one Markdown file in `src/faq/`, and the page at `/faq/`

+assembles them in filename order. Create a new file — never renumber or edit

+existing ones unless Paul asks — named `NN-slug.md`: `NN` is a two-digit

+number one higher than the highest already in `src/faq/` (run `ls src/faq/`

+to check), and the slug is two or three words from the question. Example:

+`06-what-model-runs-this.md`.

+ ---

+ question: >-

+ The question, phrased the way a reader would ask it?

+ ---

+ The answer, in Markdown. Keep it short and factual, write about Paul in

+ the third person, and only state things that are true of this site.

+The `question` text must stay indented under `question: >-` exactly as in

+the example. Then rebuild and confirm the question shows up:

+ npm run build

+ grep "the question text" docs/faq/index.html

+An FAQ change is a site change like any other: add a ledger entry, then

+commit and push as usual.

## Recipe: commit and push

Work directly on `main` — no branches, no pull requests. Paul is the only

diff --git a/README.md b/README.md

index 23090e8..a7bfd67 100644

--- a/README.md

+++ b/README.md

@@ -2,7 +2,7 @@

Static personal site for [paulca.com](https://paulca.com), built with [Eleventy](https://www.11ty.dev/), hosted on GitHub Pages. Browser default styles only.

-- `src/` — the source: blog posts in Markdown (`src/blog/`), the two HTML templates, the FAQ, and the prompt & carbon ledger entries (`src/ledger/`, one Markdown file each).

+- `src/` — the source: blog posts in Markdown (`src/blog/`), the two HTML templates, the FAQ entries (`src/faq/`, one Markdown file per question), and the prompt & carbon ledger entries (`src/ledger/`, one Markdown file each).

- `docs/` — the built site, committed to git; GitHub Pages serves this directory from `main`. Built locally with `npm run build` — there is no build on push.

- `src/microblog/` — static archive of the Pterodon microblog that previously ran at paulca.com (captured July 2026).

- `src/posts/` — individual archived posts, kept at their original `/posts/N` URLs so old links still resolve.

diff --git a/docs/ai.html b/docs/ai.html

index a9eb1c8..d14d084 100644

--- a/docs/ai.html

+++ b/docs/ai.html

@@ -40,6 +40,19 @@ leaves home and energy per prompt is roughly 2 Wh.</p>

</tr>

+<tr>

+ <td>July 25, 2026</td>

+ <td>Claude Fable 5</td>

+ <td>“One more: Add an FAQ section, and instructions for adding to the FAQ, then I'll ask pi/gptoss or opencode/qwen-coder to add some FAQ entries, which should also be Markdown files.”</td>

+ <td><p>The FAQ now works like the ledger: one Markdown file per question in

+<code>src/faq/</code>, assembled into <a href="/faq/">/faq/</a> in filename order by Eleventy.

+The five existing questions became the first five files, and <code>AGENTS.md</code>

+gained a recipe for adding a question.</p>

+</td>

+ <td>~8 Wh</td>

+ <td>~3.2 g</td>

+ <td>Twenty minutes of an idle games console</td>

+</tr>

<tr>

<td>Claude Fable 5</td>

@@ -246,9 +259,9 @@ Pages. About 40 model invocations.</p>

</tr>

</table>

-<p><b>Running total:</b> ~180 Wh,

-~72 g CO₂e —

-about the energy it takes to boil a litre and three-quarters of water, or the emissions of driving a petrol car about 400 metres.</p>

+<p><b>Running total:</b> ~188 Wh,

+~75 g CO₂e —

+just shy of the energy it takes to boil two litres of water, or the emissions of driving a petrol car about 450 metres.</p>

<h2>Method</h2>

diff --git a/docs/faq/index.html b/docs/faq/index.html

index 7b62cc4..3fd31aa 100644

--- a/docs/faq/index.html

+++ b/docs/faq/index.html

@@ -16,22 +16,29 @@ typing. The initial version of the site was set up by

<a href="https://claude.com/claude-code">Claude Code</a>; the plan for ongoing

maintenance is to use open-source models running on private hardware in a home

office in South Dublin.</p>

<h2>Why does it look so plain?</h2>

<p>On purpose. Default browser styles and semantic HTML, like the personal pages

college professors used to have. No CSS, no JavaScript, nothing to load.</p>

<h2>What is the prompt & carbon ledger?</h2>

<p>Every instruction given to an agent working on this site is recorded verbatim

-in the <a href="/ai.html">prompt & carbon ledger</a>, along with a rough estimate of the

-energy and carbon the AI work cost.</p>

+in the <a href="/ai.html">prompt & carbon ledger</a>, along with which model did the work

+and a rough estimate of the energy and carbon the AI work cost.</p>

<h2>What happened to the microblog?</h2>

<p>A microblog ran at paulca.com until July 2026. It's preserved as a

<a href="/microblog/">static archive</a>, and the old <code>/posts/N</code> URLs still resolve.</p>

<h2>How does a blog post get published?</h2>

<p>Paul writes a post in a text editor and hands it to a local model, which saves

it as a Markdown file, builds the site with <a href="https://www.11ty.dev/">Eleventy</a>,

adds a row to the ledger, and pushes the result to GitHub, where GitHub Pages

serves it.</p>

<hr>

diff --git a/eleventy.config.js b/eleventy.config.js

index 7bd8447..4a3ac32 100644

--- a/eleventy.config.js

+++ b/eleventy.config.js

@@ -39,6 +39,13 @@ module.exports = function (eleventyConfig) {

entries.reduce((sum, e) => sum + (e.data[key] ?? 0), 0)

);

+ // FAQ entries, ordered by their two-digit filename prefix.

+ eleventyConfig.addCollection("faq", (api) =>

+ api

+ .getFilteredByGlob("src/faq/*.md")

+ .sort((a, b) => a.inputPath.localeCompare(b.inputPath))

+ );

eleventyConfig.addGlobalData("buildDate", () => new Date());

return {

diff --git a/src/_data/ledger.json b/src/_data/ledger.json

index 6f1d6a1..9be4b8f 100644

--- a/src/_data/ledger.json

+++ b/src/_data/ledger.json

@@ -1,3 +1,3 @@

{

- "totals_comparison": "about the energy it takes to boil a litre and three-quarters of water, or the emissions of driving a petrol car about 400 metres"

+ "totals_comparison": "just shy of the energy it takes to boil two litres of water, or the emissions of driving a petrol car about 450 metres"

}

diff --git a/src/faq.md b/src/faq.md

deleted file mode 100644

index f4cb437..0000000

--- a/src/faq.md

+++ /dev/null

@@ -1,41 +0,0 @@

----

-layout: base.njk

-title: FAQ

-permalink: /faq/

----

-# Frequently asked questions

-## Who writes this site?

-Paul writes the words: the blog posts and the prompts. AI agents do the

-typing. The initial version of the site was set up by

-[Claude Code](https://claude.com/claude-code); the plan for ongoing

-maintenance is to use open-source models running on private hardware in a home

-office in South Dublin.

-## Why does it look so plain?

-On purpose. Default browser styles and semantic HTML, like the personal pages

-college professors used to have. No CSS, no JavaScript, nothing to load.

-## What is the prompt & carbon ledger?

-Every instruction given to an agent working on this site is recorded verbatim

-in the [prompt & carbon ledger](/ai.html), along with a rough estimate of the

-energy and carbon the AI work cost.

-## What happened to the microblog?

-A microblog ran at paulca.com until July 2026. It's preserved as a

-[static archive](/microblog/), and the old `/posts/N` URLs still resolve.

-## How does a blog post get published?

-Paul writes a post in a text editor and hands it to a local model, which saves

-it as a Markdown file, builds the site with [Eleventy](https://www.11ty.dev/),

-adds a row to the ledger, and pushes the result to GitHub, where GitHub Pages

-serves it.

----

-[← Home](/)

diff --git a/src/faq.njk b/src/faq.njk

new file mode 100644

index 0000000..f0b4106

--- /dev/null

+++ b/src/faq.njk

@@ -0,0 +1,15 @@

+---

+layout: base.njk

+title: FAQ

+permalink: /faq/

+---

+<h1>Frequently asked questions</h1>

+{%- for e in collections.faq %}

+<h2>{{ e.data.question }}</h2>

+{{ e.templateContent | safe }}

+{%- endfor %}

+<hr>

+<p><a href="/">← Home</a></p>

diff --git a/src/faq/01-who-writes-this-site.md b/src/faq/01-who-writes-this-site.md

new file mode 100644

index 0000000..c7fa37a

--- /dev/null

+++ b/src/faq/01-who-writes-this-site.md

@@ -0,0 +1,9 @@

+---

+question: >-

+ Who writes this site?

+---

+Paul writes the words: the blog posts and the prompts. AI agents do the

+typing. The initial version of the site was set up by

+[Claude Code](https://claude.com/claude-code); the plan for ongoing

+maintenance is to use open-source models running on private hardware in a home

+office in South Dublin.

diff --git a/src/faq/02-why-so-plain.md b/src/faq/02-why-so-plain.md

new file mode 100644

index 0000000..3a2b656

--- /dev/null

+++ b/src/faq/02-why-so-plain.md

@@ -0,0 +1,6 @@

+---

+question: >-

+ Why does it look so plain?

+---

+On purpose. Default browser styles and semantic HTML, like the personal pages

+college professors used to have. No CSS, no JavaScript, nothing to load.

diff --git a/src/faq/03-prompt-carbon-ledger.md b/src/faq/03-prompt-carbon-ledger.md

new file mode 100644

index 0000000..22e76cb

--- /dev/null

+++ b/src/faq/03-prompt-carbon-ledger.md

@@ -0,0 +1,7 @@

+---

+question: >-

+ What is the prompt & carbon ledger?

+---

+Every instruction given to an agent working on this site is recorded verbatim

+in the [prompt & carbon ledger](/ai.html), along with which model did the work

+and a rough estimate of the energy and carbon the AI work cost.

diff --git a/src/faq/04-microblog.md b/src/faq/04-microblog.md

new file mode 100644

index 0000000..9f96d3f

--- /dev/null

+++ b/src/faq/04-microblog.md

@@ -0,0 +1,6 @@

+---

+question: >-

+ What happened to the microblog?

+---

+A microblog ran at paulca.com until July 2026. It's preserved as a

+[static archive](/microblog/), and the old `/posts/N` URLs still resolve.

diff --git a/src/faq/05-how-published.md b/src/faq/05-how-published.md

new file mode 100644

index 0000000..8c89f1d

--- /dev/null

+++ b/src/faq/05-how-published.md

@@ -0,0 +1,8 @@

+---

+question: >-

+ How does a blog post get published?

+---

+Paul writes a post in a text editor and hands it to a local model, which saves

+it as a Markdown file, builds the site with [Eleventy](https://www.11ty.dev/),

+adds a row to the ledger, and pushes the result to GitHub, where GitHub Pages

+serves it.

diff --git a/src/faq/faq.11tydata.json b/src/faq/faq.11tydata.json

new file mode 100644

index 0000000..5df2e98

--- /dev/null

+++ b/src/faq/faq.11tydata.json

@@ -0,0 +1,3 @@

+ "permalink": false

diff --git a/src/ledger/2026-07-25-11-faq-files.md b/src/ledger/2026-07-25-11-faq-files.md

new file mode 100644

index 0000000..8993b58

--- /dev/null

+++ b/src/ledger/2026-07-25-11-faq-files.md

@@ -0,0 +1,14 @@

+---

+model: Claude Fable 5

+wh: 8

+co2_g: 3.2

+comparison: Twenty minutes of an idle games console

+prompt: >-

+ “One more: Add an FAQ section, and instructions for adding to the FAQ, then

+ I'll ask pi/gptoss or opencode/qwen-coder to add some FAQ entries, which

+ should also be Markdown files.”

+---

+The FAQ now works like the ledger: one Markdown file per question in

+`src/faq/`, assembled into [/faq/](/faq/) in filename order by Eleventy.

+The five existing questions became the first five files, and `AGENTS.md`

+gained a recipe for adding a question.