amadan
🤖 AGENTS.md is canonical, and /docs gets a build step
Groundwork for the customer docs landing on this branch. AGENTS.md replaces CLAUDE.md as the agent-instructions file, matching the sibling repos; CLAUDE.md stays as a pointer for Claude Code. The conventions rule is also corrected where it had drifted from the repo: it claimed no fetched fonts and no JavaScript, while the site self-hosts two Geist faces and ships a 2KB hand-written site.js for the hero terminal and the sticky header. It now says what is actually true — nothing is fetched from another origin, and the one script is pure enhancement — and carves out the /docs build, which runs here before a ship and never reaches a visitor.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
4 files changed,
+57
−38
AGENTS.md+48 −0CLAUDE.md+5 −35PRODUCT.md+1 −1README.md+3 −2
diff --git a/AGENTS.md b/AGENTS.md| new file mode 100644 |
| index 0000000..5dfe272 |
| --- /dev/null |
| +++ b/AGENTS.md |
| @@ -0,0 +1,48 @@ |
| +# 🤖 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. |
| + |
| +Deploys: bucket-mode CARLOS app `carloku` on flagship — ship a clean |
| +`git archive` export via the pinfra `scripts/ship-app.sh` / `promote-app.sh` |
| +(see the platform repo's AGENTS.md "Deploy reality"). Merging does NOT |
| +publish; the site is stale until someone ships. Since platform PR #108 |
| +(2026-08-08), the fleet converges within seconds of ship+promote — no |
| +need to wait for the next adoption pass. Verify by content, e.g. |
| +`curl -s https://carloku.com/ | grep -i "<something from the change>"`, |
| +or with `carlos channels -app carloku` showing the new sha promoted — |
| +static routes carry `X-Carlos-Version` too (since the platform#112 |
| +roll — verified live 2026-08-23: the header reports the promoted sha), |
| +so `curl -sI` is also proof. The pinfra ship+promote scripts remain the |
| +operator default, and for this app that pair IS the deploy. |
diff --git a/CLAUDE.md b/CLAUDE.md| index 2e7dd85..270f5c9 100644 |
| --- a/CLAUDE.md |
| +++ b/CLAUDE.md |
| @@ -1,36 +1,6 @@ |
| -# 🤖 CLAUDE.md |
| +# CLAUDE.md |
| -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, zero dependencies.** Two pages (`/`, `/get-started/`) and |
| - one shared `site.css`. No frameworks, no fetched fonts, no analytics, no |
| - JavaScript, no build step. |
| -- **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. |
| - |
| -Deploys: bucket-mode CARLOS app `carloku` on flagship — ship a clean |
| -`git archive` export via the pinfra `scripts/ship-app.sh` / `promote-app.sh` |
| -(see the platform repo's CLAUDE.md "Deploy reality"). Merging does NOT |
| -publish; the site is stale until someone ships. Since platform PR #108 |
| -(2026-08-08), the fleet converges within seconds of ship+promote — no |
| -need to wait for the next adoption pass. Verify by content, e.g. |
| -`curl -s https://carloku.com/ | grep -i "<something from the change>"`, |
| -or with `carlos channels -app carloku` showing the new sha promoted — |
| -static routes carry `X-Carlos-Version` too (since the platform#112 |
| -roll — verified live 2026-08-23: the header reports the promoted sha), |
| -so `curl -sI` is also proof. The pinfra ship+promote scripts remain the |
| -operator default, and for this app that pair IS the deploy. |
| +Guidance for AI coding agents working in this repository lives in |
| +**AGENTS.md**. Claude Code: read AGENTS.md. Update AGENTS.md — not this |
| +file — going forward; this file is only a pointer so Claude Code finds |
| +it. |
diff --git a/PRODUCT.md b/PRODUCT.md| index 0183a33..bb4603c 100644 |
| --- a/PRODUCT.md |
| +++ b/PRODUCT.md |
| @@ -46,7 +46,7 @@ division of labor between the pages. |
| - Never on the landing page: immutable, content-addressed, canary, |
| signature/signed, provision, TLS, converge, infra, artifact, registry. |
| All of it lives happily on /get-started ("Under the hood") or in docs. |
| -- No pricing language until billing exists (CLAUDE.md rule). Describe |
| +- No pricing language until billing exists (AGENTS.md rule). Describe |
| hibernation by behavior, never by cost. |
| - No claims we can't cash today. Where the product is young, say young — |
| honesty reads as confidence. |
diff --git a/README.md b/README.md| index 74d15ab..26fe728 100644 |
| --- a/README.md |
| +++ b/README.md |
| @@ -1,5 +1,6 @@ |
| # carloku.com |
| -🤖 Marketing site for Carloku, the hosted CARLOS platform. One static page, |
| -no build step. See CLAUDE.md for the rules; see |
| +🤖 Marketing site for Carloku, the hosted CARLOS platform, plus the |
| +customer docs at /docs. The marketing pages are hand-written static HTML; the |
| +docs are built from markdown before shipping. See AGENTS.md for the rules; see |
| https://carlosframework.com for the framework itself. |