# 🤖 AGENTS.md

The canonical agent-instructions file for this repo — keep it current here,
not in a tool-specific file. (Claude Code reads it via the `CLAUDE.md`
pointer.)

The marketing site for **Carloku** — the hosted CARLOS platform
(console.carloku.com). Brand boundary: Carloku is the *hosted platform*
brand; CARLOS is the framework/CLI/console name. Never rename CARLOS things
to Carloku here.

**Voice lives in PRODUCT.md** — the one feeling is lightness ("finally,
simple"); the landing page appeals to the heart, /get-started carries the
tech. Read it before touching copy.

Rules inherited from the `website` repo, which governs the sibling site:

- **Small site, nothing fetched.** `/` and `/get-started/` are hand-written
  and share one `site.css`. No frameworks, no analytics, and nothing pulled
  from another origin — the two Geist faces in `fonts/` are self-hosted. The
  only script is `site.js`: 2KB, hand-written, and pure enhancement (the hero
  terminal types itself, the header grows a hairline on scroll). The pages
  read fine with it blocked; keep it that way, and don't add a second one.
- **`/docs` is built; the rest of the site is not.** Docs pages come from the
  markdown in `src/docs/` through Eleventy, the same pipeline rastrillo.org
  uses, run here before you ship. `_site/` is gitignored and never committed;
  Eleventy and markdown-it are devDependencies that no visitor ever meets.
  See "Building the docs" below.
- **Light and dark** via `prefers-color-scheme` — keep both working.
- **AI authorship is always marked** with a visible 🤖 (cascades from a
  heading); person-emoji (👨/👤/🧑) blocks are certified human and
  off-limits to LLM edits. Baseline: everything here is AI-written unless
  marked otherwise.
- **Don't overclaim.** The console requires Keymail sign-in; pricing does
  not exist yet, so the site says nothing about it.

## Building the docs

`/docs` is ten pages of markdown under `src/docs/`, rendered by Eleventy into
`_site/` before you ship. **The corpus is authored here, by hand.** That is the
opposite of carlosframework.com, whose `/docs` corpus is vendored out of the
platform repo by a sync script: there is no sync step in this repo, nothing
under `src/docs/` or `src/_data/docsnav.json` is generated, and nothing will
overwrite an edit you make. The markdown IS the source — edit it here.

```
npm install
npm run check          # builds, then gates the rendered output
npm run serve          # localhost:8080, live reload
```

`npm run check` is `eleventy` followed by `hack/check-docs.mjs`, which reads
`_site/` after the build: the hand-written pages and shared assets were
emitted at all; every nav entry has a built page and a built `.md` twin; every
internal `/docs` href resolves to a built file, and to a real `id="…"` when it
carries a fragment; and `slugify` in `eleventy.config.js` agrees with Go's
`internal/docsite.Anchor` on every case in `src/_data/docsanchors.json`. That
last one is why the anchor fixture is vendored rather than retyped: a heading
whose fragment the platform's Go gate accepts cannot 404 in a browser here
because the two slug rules drifted.

**Eleventy does not clean stale output.** Delete or rename a page and its old
built HTML stays in `_site/` until you remove it — and the gate will *not*
notice, because every check it runs is satisfied by a file that should no
longer exist. `_site/` is gitignored, so a stale page never shows up in a diff
either. **Build clean whenever you are verifying anything:**

```
rm -rf _site && npm run check
```

The deploy sequence below gets this for free: it builds inside a fresh
`git archive` export, which has no `_site/` in it at all.

`index.html` and `get-started/index.html` are hand-written and pass through the
build byte-identical — `templateFormats` excludes `html` on purpose, so
Eleventy copies them instead of rendering them as templates. If either changes
in `_site/` without you editing its source, something is wrong.

## Deploying

Merging does **not** publish. The live site is stale until someone deploys.

**Since 2026-10-04 the site is an ordinary console app** (platform #209):

| | |
| --- | --- |
| console | `https://console.carloku.com` |
| account / app | `bes` (named `carloku`) / `website` |
| channel | `edge`, the app's only channel |
| kind | `static` |
| platform URL | `https://website.bes.oncarlos.com` |
| custom domains | `carloku.com`, `www.carloku.com` |

carloku.com and www.carloku.com are **platform claims** on that app. They are
in the flagship's own zone, which `carlos domains attach` refuses to members,
so the operator attached them with `carlos domains attach --platform`. Only an
ops account owner or a `CARLOS_SYSTEM_OPERATORS` address can change or detach
them. A deploy never touches them: deploy the app and both hostnames follow.

**There is a build step, so what ships is `_site/`, never the repo tree.** A
tree ship has no `_site/` in it: it would publish `index.html` buried under
`src/`, no built pages, and no `/docs` at all.

```
SHA=$(git rev-parse --short HEAD)      # the sha you are shipping

# 1. Clean export. Never deploy a working checkout: the packer takes every
#    regular file it sees, including .git, node_modules/ and .claude/.
rm -rf "$TMPDIR/carloku-ship" && mkdir -p "$TMPDIR/carloku-ship"
git archive "$SHA" --prefix=export/ | tar -x -C "$TMPDIR/carloku-ship"
cd "$TMPDIR/carloku-ship/export"

# 2. Build, and gate the rendered output. `check` runs eleventy, then
#    hack/check-docs.mjs over what it produced.
npm ci
npm run check

# 3. Cache-bust BOTH stylesheets across every built page — see Caching
#    below; this is not optional.
find _site -name '*.html' -exec sed -i \
  -e "s/\.css\"/.css?v=$SHA\"/g" \
  -e "s/\.css?v=[^\"]*\"/.css?v=$SHA\"/g" {} +

grep -rho '\.css?v=[^"]*"' _site --include='*.html' | sort -u   # ONE line: your sha
grep -rn '\.css"' _site --include='*.html' \
  && echo "UNBUSTED LINK — do not ship" || echo "cache-bust ok"

# 4. Deploy the BUILT OUTPUT through the console. --version is required:
#    the export has no .git, so the default (git rev-parse) has nothing to
#    read.
carlos deploy --console https://console.carloku.com \
  --account bes --app website --kind static \
  --version "$SHA" --label "<one line about the change>" --no-prompt _site
```

`carlos deploy` ships, promotes onto `edge` and watches the platform URL until
`X-Carlos-Version` reports the new sha. It runs as whoever is signed in
(`carlos auth login --console https://console.carloku.com`) and needs that
address to be a member of `bes`. Use a current `carlos` binary. An old one on
your `PATH` may not know this console's API.

**Step 3 explained, because both halves are load-bearing.** The links in `src/`
are plain (`href="/site.css"`), so the first expression stamps a token onto a
bare link and the second re-stamps a link that already carries one. Both end at
the closing quote on purpose, and so does the verification grep. A sha
beginning with `0` — this app has already shipped `01b5365` — makes
`?v=01b5365` contain the literal substring `?v=0`, so an unanchored grep for
`?v=0` calls every freshly bumped file stale (13 of 13, measured), and an
unanchored `sed` run twice yields `?v=01b536501b5365`. Anchoring on `"` fixes
both and makes step 3 idempotent: run it again and again, the answer is the
same. Don't hard-code link or page counts anywhere; the corpus grows, which is
also why the `find` walks `_site` instead of naming files.

**Caching: the edge sends no `Cache-Control` and no `ETag` on static routes,
only `Last-Modified`** (confirmed live on carloku.com 2026-08-27). Browsers
therefore apply HEURISTIC caching, roughly 10% of the age since
`Last-Modified`, so a returning visitor can hold a stale page for days. This
bit the sibling site the day its redesign shipped: one browser served the whole
old page, another served the NEW html against the OLD stylesheet. The real fix
is server-side `Cache-Control` on static routes — platform issue
**carlosframework/platform#234**. Until that lands, **step 3 is a required part
of deploying this site**, and it is required for `docs.css` exactly as much as
for `site.css`: the docs pages link both, and a docs page rendered against a
stale `docs.css` loses its whole layout.

**Verify** by header and by content, and verify `/docs` **specifically**: the
landing page looks right whether or not the built docs made it into the
artifact.

```
carlos channels --console https://console.carloku.com --account bes --app website
carlos releases --console https://console.carloku.com --account bes --app website

curl -sI https://carloku.com/docs/ | grep -i x-carlos-version      # your sha
curl -s https://carloku.com/ | grep -i "<something from the change>"
curl -s https://carloku.com/docs/ | grep -o 'docs\.css?v=[^"]*'    # your sha
```

Every edge serves the site, so to check one directly add
`--resolve carloku.com:443:<edge-ip>`. The four flagship edges are
99.81.104.219 (Ireland), 16.60.78.128 (London), 44.210.206.26 (Virginia) and
54.252.186.195 (Sydney). `-I` sends a HEAD, and HEAD is excluded from edge
compression, so anything about `Content-Encoding` needs a GET.

**Rollback** is a pointer move. Every release stays in the bucket, cache-busted
as it was shipped, so a rollback restores a self-consistent page-plus-stylesheet
pair:

```
carlos rollback --console https://console.carloku.com --account bes --app website edge
# or, to a named release:
carlos promote --console https://console.carloku.com --account bes --app website <sha> edge
```

**DNS** is in Route53, in the carloku-infrastructure tofu (`dns-carloku.tf`),
since 2026-10-05. The apex carries one latency-routed A record per edge, each
behind a health check that asks that edge for carloku.com, so every visitor
gets their nearest healthy edge. `www` is a CNAME to `website.bes.oncarlos.com`,
which the platform steers the same way. `dashboard` and `console` are CNAMEs to
the console and are not this site's. A new flagship region needs a line in that
file, or the apex never sends anyone there. The domain is still registered at
DNSimple; only the delegation moved.

**History.** Until 2026-10-04 the site was `bab/carloku`, a direct-bucket app
shipped with the pinfra `ship-app.sh` onto `canary/rehearsal`, with box-local
routes on the Ireland box. Those routes were removed when the hostnames moved
to `bes/website`. The old app's releases are still in the bucket, but nothing
routes to it: **never ship to `bab/carloku` again.**