seedproject-web/.claude/skills/changelog/SKILL.md

---
name: changelog
description: Update the public changelog for the Carlos Arias site (carlosarias.co, the /changelog page). Use whenever asked to "update the changelog", "log a change", "add a changelog entry", or to record that something was added, updated, fixed, or found broken. The changelog is a curated narrative seeded from api/cli/seed-changelog.php into the cja_changelog table and read at build time — this skill covers the exact entry format, the valid types, the voice, and the reseed + rebuild steps.
---

# Skill: update the changelog

The public changelog (`/changelog`) is a **curated narrative**, not an accreting log. Its
single source of truth is the `$entries` array in **`api/cli/seed-changelog.php`**. That
script **TRUNCATEs and reloads** the `cja_changelog` table every run, and the static site
reads that table **at build time** (`app/src/lib/changelog.js`). So the process is always:

1. **Edit** `api/cli/seed-changelog.php` — append (or amend) entries in the `$entries` array.
2. **Reseed** the table: `php api/cli/seed-changelog.php`
3. **Rebuild** the site so `/changelog` reflects it.

Editing the file alone changes nothing live — steps 2 and 3 are required.

## Entry format

Each entry is an array of `[type, summary, detail, 'YYYY-MM-DD HH:MM', by?]` — the 5th
element (**by**, the actor) is optional:

```php
['added', 'Contact form wired up', 'Real submissions stored in the database, with validation and spam protection.', '2026-07-23 12:14'],
['updated', 'Hero spacing tightened', 'Trimmed the vertical rhythm on the homepage hero.', '2026-07-24 09:00', 'Website Designer Agent'],
```

- **type** — one of: `added`, `updated`, `fixed`, `bug`, `removed`, `note`.
  Use `bug` to record that something broke, and a paired `fixed` for the repair (see the
  existing bug→fixed pairs for the pattern).
- **summary** — the headline (≤ 255 chars). Sentence case, no trailing period.
- **detail** — one sentence of context (≤ 500 chars), or `null` for none. Ends with a period.
- **timestamp** — `'YYYY-MM-DD HH:MM'` (seconds are appended automatically). **This is what
  orders the timeline** — the page shows entries newest-first by this value, not by array
  position — so a new entry can go anywhere in the array as long as its timestamp is right.
  Use the real date/time the change happened; if unknown, use now.
- **by** (optional, 5th element) — **who made the change.** The changelog shows it as
  "Added · 09:00 · by …". Attribute it to whoever actually did the work:
  - An **agent** attributes the entry to **itself** — the Web Designer agent uses
    `'Website Designer Agent'`.
  - A change made by the site owner (e.g. directed through the Claude CLI) is
    `'Carlos Arias'`, which is also the **default** when the 5th element is omitted.
  - Only name an agent when that agent genuinely made the change. If the Web Designer didn't
    do it, it's `'Carlos Arias'`.

## Voice

Match the existing entries: **write for a visitor, not for the repo.** Describe what changed
on the site from a reader's point of view, in plain past tense. Concise, understated, no hype,
no exclamation marks, British-leaning spelling ("optimised", "colour") to match the set.

- Good: `['added', 'Project galleries and social rail', 'A photo gallery with a lightbox, and a sticky Instagram rail beside each case study.', '...']`
- Avoid internal mechanics: not "Added a getStaticPaths loop over cja_projects" but "Per-project case-study pages generated from the database."
- One change = one entry. A bug and its fix are two entries (a `bug` then a `fixed`).

## Steps in full

```bash
# 1. edit api/cli/seed-changelog.php — add your entry to the $entries array

# 2. reseed the table (truncate + reload the curated set)
php api/cli/seed-changelog.php          # prints "seeded N changelog entries"

# 3. rebuild so /changelog is live
#    - preferred: the console runner rebuilds (POST /devconsole/rebuild), OR
#    - direct (never as root — build as the site owner):
cd app && npm run build
```

## Constraints & gotchas

- **Don't INSERT rows directly** into `cja_changelog` — the next reseed would wipe them. The
  seed file is the source of truth; always edit it.
- **Never build as root** — it leaves root-owned files that break later builds. Build via the
  runner or as the site's agent user (see `agents/console/SETUP.md`).
- **No shell? (confined headless agent)** — you can still do step 1 (edit the seed file with
  Write/Edit), but you cannot run steps 2–3. In that case, make the edit and clearly report
  that `php api/cli/seed-changelog.php` + a rebuild are still needed for it to go live.
- The `detail` column is capped at 500 chars and `summary` at 255 — keep both tight.