# Sneferu agent kit

> Instructions for an AI coding agent (Claude Code, Codex, Cursor, Copilot and others) building a theme for a Hekana store with Sneferu. Paste this whole file into the agent, or save it next to `theme.json` as `AGENTS.md`.

Source: https://hekana.dev/sneferu-agent-kit.md, generated from the Sneferu SDK's AGENTS.md and the docs at https://hekana.dev.

## What Sneferu is

Sneferu is the theme language and SDK for Hekana stores, an Egyptian commerce platform. A theme is a folder: `.snf` templates (HTML with `hk-*` tags, `{{ }}` output
and `{% if %}` / `{% for %}` / `{% render %}`), a `theme.json` manifest, locale
files and CSS. Hekana compiles the source on its servers and renders every page
of the store through it. A theme cannot run JavaScript.

Checkout is Hekana's own: a theme never renders the checkout or payment pages, and only brands them through the `checkout` settings block in `theme.json`. It styles every other page of the store.

## Commands

Node.js 20 or newer.

| Command | What it does |
| - | - |
| `npm create sneferu <id>` | Scaffold a complete theme (the same as `npx sneferu init <id>`) |
| `npx sneferu init <id> --template <name>` | Start from an example design; `npx sneferu init --list` lists them |
| `npx sneferu dev` | Preview at http://127.0.0.1:4100 with sample data; reloads on save (`--port <n>`, `--data <file>`) |
| `npx sneferu format` | Format `.snf`, `theme.json` and locales (`--check` in CI) |
| `npx sneferu validate` | Check the theme; prints `✔ theme <id>@<version> is valid` when clean |
| `npx sneferu build` | Compile locally to `dist/` (Hekana compiles the source again on push) |
| `npx sneferu login` | Sign in through the browser. The user runs this, never the agent |
| `npx sneferu push . --package <id> --dev-store` | Upload a new version and publish it on the private dev store. Only when the user asks |

## Workflow

1. **Start from a design.** A mockup image or a written brief. Follow the
   project's brand (its colours, type and tone); if there is none, ask.
2. **Scaffold.** `npm create sneferu <id>` or `npx sneferu init <id>` (Node.js 20+;
   `sneferu` is the short name of `@hekana/sneferu`). It writes a
   complete store: layout, header/footer/announcement groups, a template for
   every page type, sections, blocks, snippets, `ar` and `en` locales, tokens
   and an `AGENTS.md` for the folder. To start from a finished design instead,
   `npx sneferu init <id> --template <name>` (`init --list` shows
   `starter`, `arcade`, `console`, `esports`, `creator`, `license`, `bento`).
   The `id` is the folder name: lower-case letters, digits and `-`.
3. **Build it out.** Edit `theme.json` (name, description, `defaultLocale`,
   `locales`, `tokens.colors`, `tokens.fonts`, `money.format`), then sections
   in `sections/`, repeatable items in `blocks/`, partials in `snippets/`, the
   default sections of each page in `templates/<type>.snf`, the shared header
   and footer in `groups/*.json`, the stylesheet in `assets/*.css`, interface
   words in `locales/<lang>.json`. Replace every default text the scaffold
   came with (hero, footer, product notes, menus) with the store's own.
4. **Preview.** `npx sneferu dev` serves http://127.0.0.1:4100 with sample
   data and reloads on save. Check `/`, `/products/<handle>`, `/products`,
   `/category/<handle>`, `/search?q=a`, `/cart`, `/pages/about` and a missing
   path (404), each in every locale (`/en/...`, `/ar/...`, or `?locale=`), at a
   desktop width (1440 px) and a phone width (390 px). If port 4100 is taken use
   `--port <n>`, and confirm the page carries `data-hk-theme="<id>"` (another
   theme may be answering). `--data <file>` or `.sneferu-dev/data.json` adds your
   own `store`, `collections`, `products` (by handle; a product only has a page
   when it is listed here) and `menus`.
5. **Format and check.** `npx sneferu format`, then
   `npx sneferu validate` until it prints `✔ theme <id>@<version> is valid`.
   Each problem is `file:line:col severity CODE message`; the code's fix is in
   the [diagnostics reference](https://hekana.dev/reference/diagnostics).
6. **Compare with the design.** Screenshot the dev preview at both widths and
   both directions and compare it with the mockup, section by section.
7. **Push, only when the user asks.** The user signs in once with
   `npx sneferu login` (a browser step). Then bump `version` in
   `theme.json` and run `npx sneferu push . --package <id> --dev-store`:
   it uploads the source, and publishes it on the developer's private dev
   store. Never print, log or commit a key (`HEKANA_TOKEN`, `hk_dev_…`).

## Rules

The compiler enforces most of these, and `validate` names the one you broke.

1. **Only allowed markup.** Plain HTML from the
   [allow-list](https://hekana.dev/guide/security-and-limits) and the `hk-*`
   tags of the [tag reference](https://hekana.dev/reference/tags), with only
   the props listed there (machine-readable:
   [docs/reference/tags.json](https://github.com/hekanahq/sneferu/blob/main/docs/reference/tags.json)). No `<script>`,
   `<style>`, `<link>`, `<iframe>`, `<form>`, no `on*` attributes, no `{{ }}`
   inside `style="…"`, no `style` on `hk-*` tags.
2. **No JavaScript, no form controls.** Behaviour comes from tags:
   `hk-search-form` (the only form), `hk-variant-picker`, `hk-add-to-cart`,
   `hk-cart-count`, `hk-cart-items`, `hk-cart-summary`, `hk-cart-drawer`,
   `hk-product-gallery`, `hk-pagination`, `hk-locale-switch`. Menus and
   questions open with `<details>`; carousels are CSS scroll-snap.
3. **Every page type.** A shippable theme has `templates/index`, `product`,
   `collection`, `search`, `cart`, `page` and `404`, and places the
   `announcement`, `header` and `footer` groups in `layout/theme.snf`. A
   missing type falls back to the SDK's default store, which will not match
   your design.
   Checkout and payment pages are never theme-rendered: checkout is Hekana's
   own, with no template or tag. Brand it only with the `checkout` block in
   `theme.json` (see [Checkout branding](https://hekana.dev/guide/checkout-branding)).
4. **Everything merchant-editable.** Nothing visible is written into a
   template. Headings, paragraphs and button labels are `text`/`textarea`
   settings with `"localized": true` and `{ "ar": …, "en": … }` defaults; links
   and images are `link`/`image` settings; repeated items (menu links, plans,
   questions, slides) are blocks, seeded in the template's `<hk-schema>` and
   offered as `presets`; small interface words are locale keys read with
   `t('key')`; colours and fonts are tokens. Every setting has a label in both
   languages, a sensible default and a limit (`maxLength`, `min`, `max`). See
   [Make everything editable](https://hekana.dev/guide/make-everything-editable).
5. **Arabic and English, both directions.** Hekana stores are Arabic-first:
   list `ar` and `en` in `locales` with a file for each holding the same keys.
   Write CSS with logical properties (`margin-inline-start`, `padding-inline`,
   `text-align: start`). `hk-icon` arrows and chevrons mirror themselves on
   Arabic pages; flip only your own inline SVG arrows, under `[dir="rtl"]`. Give Arabic
   body text a line height of 1.6 or more and no letter-spacing. Wrap store
   links in `url()` so an English page stays English.
6. **Money.** Prices are minor units (piastres). Print them with `| money` or
   `<hk-price>`; never compute a total. `"money": { "format": "whole" }` in
   `theme.json` prints `EGP 1,290` instead of `EGP 1,290.00`.
7. **Fonts and assets.** Fonts come from `tokens.fonts`, from the
   [catalogue](https://hekana.dev/guide/styling-and-responsive#fonts) (Cairo,
   IBM Plex Sans Arabic, Tajawal, Almarai, Readex Pro and others cover Arabic).
   Font and script files in `assets/` are not served. Bundled images go through
   `asset_url('file.webp')`, at most 2 MB each, compressed (WebP or AVIF).
8. **Images.** Product images through `hk-image`, `hk-product-card`,
   `hk-product-gallery` or `| img: <width>`, which carry `srcset`. Every image
   has `alt` (empty only when decorative), and a plain `<img>` has `width` and
   `height`.
9. **CSS.** In `assets/*.css`, using the token variables
   (`var(--hk-color-accent)`, `var(--hk-radius)`, `var(--hk-space-3)`). Style
   your own classes and the stable `sn-*` hooks (`sn-btn`, `sn-product-card`,
   `sn-price`), never the numbered ones (`sn-c3`). Wrap broad resets in
   `:where()`: `[data-hk-theme='x'] a { … }` outranks every single-class rule.
10. **Accessibility.** Touch targets at least 44 px tall on phones, text
    contrast at least 4.5:1, a `label` on icon-only buttons and icons, headings
    in order, a skip link to `#main`.
11. **Budgets.** Every `{% for %}` has a small `limit:`; avoid loops inside
    loops; prefer `hk-product-grid` to hand-built grids.
12. **Names and versions.** Section, block and snippet names never start with
    `hk-` (SN3043). A name exists in one form per folder, never `hero.snf` next
    to `hero.sneferu` (SN3044). A pushed version is immutable: bump `version`
    before every push.
13. **Content.** No real brand logos or trademarks you do not own, no
    invented claims, plain and specific copy. Follow the project's brand
    guidelines for colour and tone.

## Done means

- `npx sneferu validate` is clean and `npx sneferu format --check` passes.
- Every page type renders in `dev` in every listed locale at 1440 px and 390 px,
  with no horizontal scroll, and matches the design.
- Every visible word, link, image and colour can be changed by the merchant.
- An empty collection and a section with no blocks still look intentional.

## Copy from

The [example themes](https://github.com/hekanahq/sneferu/tree/main/examples/themes) are complete stores with every page type,
groups, locales and settings: arcade,
console, esports (gaming),
creator, license,
bento (digital products),
torque, odda (hardware),
dawa, aafia (health),
ivory, asphalt (fashion),
sage, henna (beauty),
volt, bazaar (electronics),
konafa, tabkha (food),
oak, mashrabiya (home),
cloud, blocks (kids),
velvet, halo (jewelry),
onyx, cashmere (luxury),
pulse, stride (sports),
hekaya, qalam (books, stationery),
bunn, fetar, ghalla, tawfir (food and grocery),
loom, khayamiya (crafts),
wekala, dukkan, ink, sukoon (general). The SDK's own default store
is [packages/templates-default/theme](https://github.com/hekanahq/sneferu/tree/main/packages/templates-default/theme).

## Read next

- [Every docs page in one file](https://hekana.dev/llms-full.txt) (index: [llms.txt](https://hekana.dev/llms.txt))
- [Tags reference](https://hekana.dev/reference/tags.md): every `hk-*` tag and its props
- [Language reference](https://hekana.dev/reference/language.md): grammar, directives, filters, field types
- [Diagnostics](https://hekana.dev/reference/diagnostics.md): every SN code and its fix
- [Page types](https://hekana.dev/guide/page-types.md), [Make everything editable](https://hekana.dev/guide/make-everything-editable.md) and [Checkout branding](https://hekana.dev/guide/checkout-branding.md)
- [Example themes on GitHub](https://github.com/hekanahq/sneferu/tree/main/examples/themes): complete stores to copy from

## Prompt template

Fill in the angle brackets and send it with this kit:

```text
Build a Sneferu theme for <store type, e.g. a specialty coffee shop> called <theme-id>.
Design: <attach a mockup, or describe colours, fonts and mood>.
Languages: Arabic and English, Arabic first.
Home page: <sections, e.g. hero, featured products, how it works, FAQ, footer>.
Follow the Sneferu agent kit (https://hekana.dev/sneferu-agent-kit.md) and the docs at https://hekana.dev/llms-full.txt.
Start with `npx sneferu init <theme-id>`, design every page type, keep every visible word, link, image and colour editable by the merchant,
and finish when `npx sneferu validate` and `npx sneferu format --check` are clean. Show me the dev preview at 1440 and 390 px in both languages. Do not push.
```