@gemboss/website-ui 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,174 @@
+# @gemboss/website-ui: read this before you build or change a page
+
+You are building a public website for a GemCommerce brand (GemBoss, GemPages, Gemians…) with this kit. The people
+asking you are often not designers. The kit is how their site ends up looking like it was made by a careful design
+team: **use the kit, follow the rules below, and when the kit is missing something, report it instead of inventing
+it.** Everything here applies to every page, in every language.
+
+Files you will use, all inside `node_modules/@gemboss/website-ui/`:
+
+| file | what it is |
+|---|---|
+| `website.css` | the whole kit, one file (tokens, base, layout, components, sections) |
+| `js/website.js` | header, mega menu, mobile menu, theme toggle, scroll reveal; no dependencies |
+| `system.json` | every value of the system: colours, spacing, type, radii, shadows, widths |
+| `templates/page.html` | the page skeleton: start every new page from it |
+| `templates/sections/*.html` | ready sections: hero, features, split, showcase, logos, stats, steps, pricing, FAQ, CTA… |
+| `demo/index.html` | every component on one page: open it to see what exists before you build anything |
+| `docs/components.md` | every class, what it is for, its variants |
+| `docs/theming.md` | how a brand other than GemBoss sets its accent and logo, and what it must not change |
+
+## 1. The ten rules
+
+1. **Compose, do not invent.** A page is the page skeleton plus kit sections plus your words. Look in `demo/` and
+   `docs/components.md` first. A new class is a last resort (section 9).
+2. **White canvas, ink actions, one accent.** The background is white (`--gw-bg`). The thing you click is near-black
+   (`.gw-btn`). The accent colour is for links, focus, the active item, the 8px label square and a chart line. **The
+   accent is never a button fill and never body text.**
+3. **Actions are rectangles, chips are pills.** Buttons: radius 8px, 40px tall, sentence case, 14px/600. Chips,
+   toggles, badges: fully rounded. Cards: radius 12px (16px for a large panel). No other radii.
+4. **A card sits.** A card (`.gw-card`, a plan) is a white box with a 1px `--gw-line` border and the resting shadow
+   `--gw-shadow`, the same as the GemBoss dashboard. It never lifts on hover. To separate anything else, use space or a
+   hairline before a shadow. The only shadows are `--gw-shadow` (rest), `--gw-shadow-sm` and `--gw-shadow-raised`
+   (popovers: the mega menu, menus).
+5. **Only the scales.** Spacing: 0 2 4 6 8 12 16 20 24 32 40 48 64 80 96 120 (px). Type: 11 12 13 14 16 18 20 22 24 30,
+   plus the two display sizes for h1/h2. No half pixels, no "just 15px", no colour outside the tokens.
+6. **Sentence case everywhere.** Headings, buttons, labels, menu items. No uppercase with letter spacing.
+7. **One idea per section, one primary action per view.** A section has a short label, a headline, at most two
+   lines under it, then the content. One `.gw-btn` per section; the second action is `.gw-btn--secondary` or a link.
+8. **Real words, real facts.** No lorem ipsum, no invented numbers, customers, logos, reviews or quotes. Missing
+   facts become a visible placeholder like `[PRICE]` and a question to the person (section 6).
+9. **It must work at 320px.** Check every page at 320, 390, 768 and 1366px wide. Nothing scrolls sideways, no text
+   is clipped, every tap target is at least 44px.
+10. **Run the check before you say "done".** `npx gemboss-website check` (section 10).
+
+## 2. Build a page
+
+1. Copy `templates/page.html` into the site. It links `website.css` and `website.js`, has the skip link, the
+   header, the `<main>` and the footer. Fill the header and footer once (they are the same on every page).
+2. Pick sections from `templates/sections/` in the order the page needs. A typical page: hero → proof (logos or
+   stats) → 2 to 4 feature sections → one showcase or split → FAQ → final CTA. Not every page needs every section;
+   fewer, clearer sections beat more.
+3. Write the copy (section 6), then delete what you did not use. Do not leave empty slots or sample text.
+4. Images: real product screens or photos the brand owns. Give every `<img>` a real `alt` (or `alt=""` when it is
+   decoration), `width`, `height`, and `loading="lazy"` below the first screen.
+5. Run the check, open the page at 320px and 1366px, fix, then hand it over.
+
+## 3. The system in short (values: `system.json`)
+
+- **Colour roles** (CSS variables, light and dark): `--gw-bg`, `--gw-bg-soft` (the neutral raised fill),
+  `--gw-surface`, `--gw-ink`, `--gw-ink-2`, `--gw-muted`, `--gw-line`, `--gw-line-strong`, `--gw-action`,
+  `--gw-on-action`, `--gw-accent`, `--gw-accent-strong`, `--gw-accent-soft`, `--gw-success`, `--gw-warning`,
+  `--gw-night` (the dark band). Wash hues `--gw-wash-pink|violet|sky|mint` exist for the hero wash and illustrations only.
+- **Dark mode** follows the visitor's system and the theme toggle (`data-theme` on `<html>`). Use the variables and
+  it works; a hard-coded colour breaks it.
+- **Accent as text** (links, the active menu item, step numbers) is `--gw-accent-strong`; the plain accent is for
+  the label square, the focus ring, check marks and borders. Night bands switch to the dark palette by themselves.
+- **Controls** are 40px tall on desktop and at least 44px on touch screens; `.gw-btn--sm` is 36px with a 46px hit area on desktop and 44px tall on touch screens.
+- **Type**: Inter. Headings weight 650, tracking −0.022em; display h1/h2 weight 600, tracking −0.03em. Body 18px,
+  line height 1.6. The house headline shape: a muted first sentence, an ink second one
+  (`<h2><span class="gw-dim">Two builders.</span> One engine underneath.</h2>`).
+- **Layout**: content sits in `.gw-wrap` (1120px max, 22px gutters) or `.gw-wrap--narrow` (780px). Sections use
+  `.gw-section` and get their vertical rhythm from `--gw-space-section`. Grids: `.gw-grid--2|3|4` collapse to one
+  column on phones.
+- **Night bands** (`.gw-band--night`): at most three on a page plus the closing CTA, never two in a row; everything
+  else on white or `--gw-bg-soft`.
+- **Motion**: only `transform` and `opacity`, the kit's ease, nothing moves under `prefers-reduced-motion`. Scroll
+  reveal is `.gw-reveal` (the JS adds `.is-in`, and a failsafe shows it anyway).
+
+## 4. Don't (each of these has happened, and each one made a page look cheap or broke it)
+
+- Don't fill a button with the accent colour, a gradient or a wash hue.
+- Don't use uppercase labels with letter spacing ("FEATURES").
+- Don't add shadows beyond the three tokens, and don't lift cards on hover.
+- Don't round a button into a pill, and don't square a chip.
+- Don't use cream, beige or grey page backgrounds; white or `--gw-bg-soft` only.
+- Don't use colours, sizes, spacings or radii outside the tokens and scales.
+- Don't put a floating, blurred, rounded "pill" header on the page; the header is a flat bar with one hairline.
+- Don't tuck the hero under the header with a negative margin.
+- Don't use emoji as icons; use inline stroke SVG (1.7–2px stroke, `currentColor`, `aria-hidden="true"`).
+- Don't use gradient washes behind body text, glassmorphism on chrome, or neon glows.
+- Don't put two primary buttons side by side.
+- Don't write "Click here", "Learn more" as the only words of a link; say where it goes.
+- Don't use the em dash (—) in visible text. Use a comma, a colon or a full stop.
+- Don't invent numbers, customer names, logos, testimonials, ratings, awards or certifications.
+- Don't animate layout properties (width, height, top, margin), and don't autoplay motion that cannot be stopped.
+- Don't ship a page you have not seen at 320px.
+- Don't write CSS that overrides a `.gw-*` class to change how it looks. If the kit's version is wrong for you,
+  that is a gap (section 9).
+
+## 5. Accessibility
+
+- Text contrast at least 4.5:1 (3:1 for 24px and above). The tokens pass; a custom colour may not.
+- Every interactive thing is a real `<a href>` or `<button>`. Never a clickable `<div>`.
+- Focus stays visible (the kit draws it with the accent). Do not remove outlines.
+- Tap targets at least 44×44px, with at least 8px between neighbours.
+- One `<h1>` per page, headings in order, landmarks (`header`, `nav`, `main`, `footer`), and the skip link kept.
+- Icon-only buttons get `aria-label`. Decorative SVG gets `aria-hidden="true"`.
+
+## 6. Words
+
+- Write for the reader of the page: what it does for them, in their words, short sentences. Lead with the outcome,
+  then how.
+- **Claims**: say only what the product does today. Every number needs a source the person can point to. If you do
+  not know a fact (a price, a count, a date, a customer), write a visible placeholder (`[PRICE]`) and ask.
+- Product names, plan names and prices are written exactly as the brand writes them.
+- Domains in the text are the brand's own; never a made-up example brand that looks real.
+- Do not name or quote internal tools or internal data on a public page.
+- Image sources: record where each image comes from (the brand's own screen, a licensed photo). No photos of real
+  people or other brands' logos without permission.
+- Other languages: rewrite each page for its reader (transcreation), do not translate sentence by sentence. Facts
+  (prices, numbers, names, links, claims) stay identical. Labels inside buttons, chips and pills must not grow much
+  longer than the English, or they overflow on phones.
+
+## 7. Theming for another brand
+
+A brand other than GemBoss changes **only**: the accent family, the wash hues, the logo in the header and footer, and
+the favicon. The accent family is eight variables set in one `:root {}` block after the kit:
+`--gw-accent-light`, `--gw-accent-strong-light`, `--gw-accent-soft-light`, `--gw-on-accent-light` and the same four
+ending in `-dark`. Do not set `--gw-accent` itself: the kit points it at those per theme, and a direct override loses
+as soon as the theme toggle is pressed. Accent text (links, the active menu item) uses `--gw-accent-strong`, so a new
+accent-strong must reach 4.5:1 on both `--gw-bg` and `--gw-bg-soft`. A brand does not change the shapes, the scales,
+the ink action, the white canvas or the type. Recipe and checks: `docs/theming.md`; a working example:
+`demo/theme-example.html`.
+
+## 8. Where things go in a consuming site
+
+- Link the kit, then the site's own CSS after it: `website.css` → `site.css`.
+- The site's own CSS is for content the kit cannot know (an illustration, a product mock-up) and uses only the
+  tokens. Its classes start with the site's prefix (for example `gp-` on GemPages), never `gw-`.
+- Shared header and footer markup lives in one place in the site (a partial or component), not copied per page.
+
+## 9. When the kit is missing something
+
+The kit is young; it will not have everything. When a page needs something it does not have:
+
+1. **Is it really missing?** Look in `demo/index.html` and `docs/components.md`. Can two existing pieces together do
+   it (a grid of cards, a split with a list)? Can a variant do it? If yes, use that.
+2. **Is it a kit thing or a page thing?** A kit thing is reusable by other pages and other brands: a section shape,
+   a component, a token, a behaviour. A one-off illustration or a product mock-up is a page thing: build it in the
+   site's own CSS with the tokens, and stop here.
+3. **Build a stopgap in the site, not in the kit.** Put it in one file, `kit-gaps.css` (and `kit-gaps.js` if it needs
+   behaviour), with classes prefixed `kitgap-`, using only the kit's tokens and scales, and a comment naming the gap.
+   Never edit files inside `node_modules`, and never override `.gw-*` classes.
+4. **Report it.** Run `npx gemboss-website gap` and answer its questions (or pass `--title`, `--need`, `--page`,
+   `--kind`, `--stopgap kit-gaps.css`). It opens an issue in the kit's repository with everything the kit team needs,
+   or, when GitHub is not available, writes `kit-gaps/<name>.md` for the person to send. Tell the person you did it.
+5. **When the kit ships it**, `npx gemboss-website upgrade` lists the gaps that are now in the kit: replace your
+   stopgap with the kit's class and delete the `kitgap-` code.
+
+## 10. Check before you hand it over
+
+```sh
+npx gemboss-website check            # every .html and .css in the site against the rules above
+npx gemboss-website check --fix-list # the same, as a to-do list
+```
+
+It reports colours, radii, spacing and type outside the system, shadows on chrome, accent-filled buttons, uppercase
+labels, em dashes in visible text, images without `alt`, overrides of `.gw-*` classes, and patterns that repeat
+across pages (likely gaps). It does not replace looking at the page at 320px and 1366px.
+
+## 11. Upgrading the kit
+
+`npx gemboss-website upgrade` shows what changed since the version the site has (from `CHANGELOG.md`), the gaps that
+were closed, and the exact command to install the new version. Read it, upgrade, run the check, look at the pages.

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+Every release lists what changed for a site that uses the kit. A release that adds what a site reported as missing
+says so with `Closes gap #N` (the GitHub issue number), so `npx gemboss-website upgrade` can tell that site which
+stopgap (`kitgap-*`) it can now delete.
+
+## 0.1.0 (2026-10-24)
+
+The foundation.
+
+- `website.css`: tokens (light and dark, from `system.json`), base type, layout, buttons, links, labels, chips,
+  badges, cards, window frame, tables, FAQ, header with mega menu and mobile menu, footer, and the sections hero,
+  logos, stats, features, split, showcase, steps, quote, pricing and CTA.
+- Cards and plans carry the dashboard's resting shadow; the mega menu is a floating card under the bar (as on
+  gemboss.ai); night bands: at most three per page plus the closing CTA.
+- `website.js`: mega menu, mobile menu, theme toggle, scroll reveal, current-page marking.
+- `AGENTS.md`: the rules every page follows (what to use, what never to do, words, accessibility, theming, gaps).
+- `templates/`: the page skeleton and one snippet per section. `demo/`: every component on one page.
+- CLI `gemboss-website`: `init` (CLAUDE.md block + Claude Code skill), `check`, `gap`, `upgrade`.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# @gemboss/website-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The website kit of GemCommerce.** Tokens, header with mega menu, footer, sections and the design rules that public
+websites built by GemCommerce teams share, plus a CLI that checks a site, reports what the kit is missing and upgrades
+it. Made so that a team working with Claude Code, even without a designer, ships pages that look like one family.
+
+> Bộ kit website của GemCommerce: token, header kèm mega menu, footer, các section và luật thiết kế mà mọi website
+> công khai của các team GemCommerce (GemBoss, GemPages, Gemians…) dùng chung, kèm một CLI kiểm site, báo chỗ kit còn
+> thiếu và nâng cấp. Viết để một team làm việc với Claude Code, kể cả không có designer, vẫn ra trang đúng một họ.
+
+## Có gì trong gói
+
+| | |
+|---|---|
+| `website.css`, `website.min.css` | toàn bộ kit trong một tệp (khoảng 39 KB, 31 KB bản min): token sáng và tối, chữ, bố cục, nút, link, nhãn, chip, badge, card, khung cửa sổ, bảng, FAQ, header + mega menu + menu điện thoại, footer, 11 section |
+| `js/website.js` | mega menu, menu điện thoại, đổi giao diện sáng/tối, hiện dần khi cuộn, đánh dấu trang hiện tại; không phụ thuộc thư viện nào, khoảng 7 KB |
+| `AGENTS.md` | luật mà Claude Code (và người) phải theo: 10 luật, cách dựng trang, điều cấm, chữ, khả năng truy cập, đổi thương hiệu, khi kit thiếu |
+| `templates/` | khung một trang và 11 section (hero, logos, stats, features, split, showcase, steps, quote, pricing, faq, cta) |
+| `demo/` | mọi thành phần trên một trang; `theme-example.html` cho thấy một thương hiệu khác đổi màu nhấn |
+| `docs/` | danh mục class (`components.md`), đổi thương hiệu (`theming.md`), triết lý (`philosophy.md`), hợp đồng markup |
+| `system.json` | mọi giá trị của hệ thống (màu, khoảng cách, chữ, bo góc, bóng, khung): nguồn duy nhất |
+| CLI `gemboss-website` | `init`, `check`, `gap`, `upgrade` |
+
+Cần Node 18 trở lên cho CLI. CSS và JS chạy trên mọi trình duyệt hiện đại, không cần bước build.
+
+## Cài đặt
+
+```sh
+npm install @gemboss/website-ui        # hoặc: pnpm add @gemboss/website-ui / yarn add @gemboss/website-ui
+npx gemboss-website init               # nối luật của kit vào Claude Code của dự án (xem bên dưới)
+```
+
+`init` thêm một khối vào `CLAUDE.md` của dự án (giữa hai dấu `<!-- @gemboss/website-ui:start/end -->`, không đụng chữ
+khác) và cài skill `.claude/skills/gemboss-website-ui/SKILL.md`. Từ đó, mỗi lần bạn nhờ Claude Code làm một trang,
+nó đọc `AGENTS.md` của kit trước, dựng từ mẫu, và chạy `check` trước khi báo xong. Claude Code không tự đọc tệp trong
+`node_modules`, nên bước này là cần thiết.
+
+## Dùng trên trang
+
+**Site HTML tĩnh hoặc không có bước build:** dùng CDN của npm, ghim đúng phiên bản.
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@gemboss/website-ui@0.1.0/website.min.css">
+<link rel="stylesheet" href="/site.css">   <!-- CSS riêng của site, luôn SAU kit -->
+<script src="https://cdn.jsdelivr.net/npm/@gemboss/website-ui@0.1.0/js/website.js" defer></script>
+```
+
+**Next.js (App Router):** nạp CSS trong layout gốc, nạp script bằng `next/script`.
+
+```js
+// app/layout.js
+import "@gemboss/website-ui/website.css";
+import "./site.css";
+import Script from "next/script";
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="vi">
+      <body className="gw-page">
+        {children}
+        <Script src="/kit/website.js" strategy="afterInteractive" />
+      </body>
+    </html>
+  );
+}
+```
+
+Chép `node_modules/@gemboss/website-ui/js/website.js` vào `public/kit/` (hoặc phục vụ nó bằng một route). Font Inter
+nạp từ Google Fonts như trong `templates/page.html`.
+
+**Bắt đầu một trang:** chép `templates/page.html`, điền header và footer một lần (chung cho mọi trang), ghép các
+section trong `templates/sections/` theo thứ tự trang cần, thay mọi chỗ `[trong ngoặc]`, xoá phần không dùng. Mở
+`demo/index.html` để xem kit có gì trước khi tự viết bất cứ thứ gì.
+
+## Thương hiệu khác GemBoss
+
+Một thương hiệu chỉ đổi màu nhấn (8 biến cho sáng và tối), màu wash, logo và favicon, trong một khối `:root {}` đặt
+sau kit. Hình dạng, thang, nút màu mực, nền trắng và kiểu chữ giữ nguyên. Công thức và các phép kiểm tương phản:
+`docs/theming.md`; ví dụ chạy được: `demo/theme-example.html`.
+
+## Lệnh
+
+| lệnh | làm gì |
+|---|---|
+| `npx gemboss-website init` | nối luật của kit vào Claude Code của dự án (CLAUDE.md + skill) |
+| `npx gemboss-website check` | kiểm mọi `.html` và `.css` của site: màu, khoảng cách, chữ, bo góc ngoài thang, bóng, nút tô màu nhấn, nhãn viết hoa giãn chữ, đè class `gw-`, dấu gạch dài, ảnh thiếu `alt`, link mơ hồ… và gợi ý chỗ kit có thể đang thiếu |
+| `npx gemboss-website gap` | báo một chỗ kit còn thiếu: mở GitHub Issue ở repo của kit (nếu `gh` đã đăng nhập và có quyền), không thì ghi `kit-gaps/<tên>.md` để gửi |
+| `npx gemboss-website upgrade` | so bản đang dùng với bản mới nhất, in thay đổi, gap đã có trong kit, và lệnh nâng cấp |
+
+`check` thoát mã 1 khi có lỗi, nên chạy được trong CI của site:
+`npx gemboss-website check --ignore vendor/`.
+
+## Khi kit thiếu thứ bạn cần
+
+Đừng đè class `gw-` hay sửa tệp trong `node_modules`. Làm tạm trong site (`kit-gaps.css`, class `kitgap-`, chỉ dùng
+token và thang), rồi `npx gemboss-website gap`. Khi một bản kit mới có thứ đó, CHANGELOG ghi `Closes gap #N` và
+`upgrade` nhắc bạn xoá phần làm tạm. Quy trình đầy đủ: `AGENTS.md` mục 9.
+
+## Phiên bản
+
+Semver. Ở 0.x, bản minor có thể đổi markup (đọc CHANGELOG trước khi nâng), bản patch thì an toàn. Ghim đúng phiên bản
+khi dùng CDN.
+
+## Dành cho team GemCommerce
+
+Tài liệu GemBoss Design System đầy đủ (triết lý, nền tảng, thành phần, mẫu trang, thương hiệu, quản trị) nằm ở cổng
+tài liệu nội bộ docs.gemboss.ai (đăng nhập bằng GemBoss). Mã nguồn của kit: `packages/website-ui` trong repo
+gemboss-www; mọi thay đổi đi qua PR, giá trị của hệ thống chỉ sửa ở `system.json`.
+
+```sh
+cd packages/website-ui
+node scripts/build.mjs        # sinh css/tokens.css từ system.json, ghép website.css và website.min.css
+node test/run.mjs             # tự kiểm CLI
+node scripts/gate-demo.mjs    # cổng thị giác và khoảng thở của gemboss.ai trên demo (cần .ci của repo)
+```
+
+Phát hành: tăng `version`, thêm mục CHANGELOG (kèm `Closes gap #N`), rồi gắn tag `website-ui-vX.Y.Z` (Trusted
+Publishing), hoặc `npm publish` từ thư mục này.

package/bin/gemboss-website.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// gemboss-website: the CLI of @gemboss/website-ui. How a site's Claude Code follows the kit's rules (init, check),
+// reports what the kit is missing (gap) and upgrades (upgrade). Node >= 18, no dependencies.
+import { PKG, UsageError } from "./lib/util.mjs";
+
+export const USAGE = `gemboss-website (${PKG.name} ${PKG.version})
+
+Usage: npx gemboss-website <command> [options]   (run it in the site's root folder)
+
+Commands
+  init [--force]
+      Add or refresh the kit's block in CLAUDE.md (between <!-- ${PKG.name}:start/end --> markers;
+      text outside them is never touched) and install the Claude Code skill
+      .claude/skills/gemboss-website-ui/SKILL.md (replaced only if init wrote it, or with --force).
+
+  check [paths...] [--json] [--fix-list] [--ignore <path>]... [--include-kit]
+      Check every .html/.htm/.css (and <style>, style="") under the paths (default: here) against
+      the kit's rules: colours, radii, type and spacing outside the scales, half pixels, shadows,
+      uppercase labels, accent-filled buttons, overrides of .gw-* classes, em dashes, images without
+      alt, vague links, h1 count, <html lang>, clickable divs. Notes list likely gaps (a site class on
+      3+ pages) and open kitgap-* stopgaps. Skips node_modules, dist, build, out, coverage, dot-folders
+      and the kit's own files. Exit 1 when there is an error, 0 otherwise.
+        --json        machine-readable findings
+        --fix-list    the findings as a markdown to-do list
+        --ignore      skip a file or folder (repeatable), e.g. third-party CSS
+        --include-kit also check the kit's own HTML (templates, demo): for the kit's own CI
+
+  gap [--title ...] [--need ...] [--kind token|component|section|behavior|doc|other]
+      [--page <url>] [--site ...] [--why ...] [--shape ...] [--stopgap <file>]
+      [--screenshot <path-or-url>] [--dry-run]
+      Report something the kit is missing. Asks for missing answers in a terminal; without one,
+      --title and --need are required. With gh signed in, opens an issue in ${(PKG.gemboss && PKG.gemboss.gapRepo) || "the kit's repo"};
+      otherwise (or with --dry-run, which never touches the network) writes kit-gaps/<slug>.md
+      and prints how to send it.
+
+  upgrade
+      Installed vs latest version, the CHANGELOG sections in between, the gaps they close, the
+      project's kitgap-* stopgaps that name those gaps, and the install command.
+
+  help
+      This text.
+
+Environment (tests and offline use)
+  GEMBOSS_WEBSITE_CHANGELOG=<file>   upgrade reads this changelog instead of the kit's CHANGELOG.md
+  GEMBOSS_WEBSITE_LATEST=<version>   upgrade uses this as the latest version instead of asking npm
+  GEMBOSS_WEBSITE_OFFLINE=1          upgrade does not ask npm
+  GEMBOSS_WEBSITE_GH=<path>          gap runs this instead of gh
+  NO_COLOR=1                         no colours in the output
+
+Rules: node_modules/${PKG.name}/AGENTS.md`;
+
+async function main(argv) {
+  const [cmd, ...rest] = argv;
+  switch (cmd) {
+    case undefined: case "help": case "--help": case "-h":
+      console.log(USAGE);
+      return 0;
+    case "--version": case "-v": case "version":
+      console.log(PKG.version);
+      return 0;
+    case "init": return (await import("./lib/init.mjs")).cmdInit(rest);
+    case "check": return (await import("./lib/check.mjs")).cmdCheck(rest);
+    case "gap": return (await import("./lib/gap.mjs")).cmdGap(rest);
+    case "upgrade": return (await import("./lib/upgrade.mjs")).cmdUpgrade(rest);
+    default:
+      throw new UsageError(`unknown command "${cmd}"`);
+  }
+}
+
+main(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (err) => {
+  if (err instanceof UsageError) {
+    console.error(`gemboss-website: ${err.message}\nRun "npx gemboss-website help" for usage.`);
+    process.exitCode = 2;
+  } else {
+    console.error(err && err.stack ? err.stack : err);
+    process.exitCode = 3;
+  }
+});