# New Website

> Orchestrates building a NEW website end-to-end, from insights to launch-ready and handoff-ready. Self-contained: it runs the stack decision interview, sequences the website-* skills + existing marketing skills in order, and scaffolds the project from its own templates/ (Astro starter overlay + full QA test suite + GDPR privacy draft + owner docs + permission allowlist), copying the bundled skill set into the project's skills dir (full copy list in §3) so the repo is self-contained for a third party. Default stack Astro → GitHub → Cloudflare Workers. Use at the very start of any new site. Trigger phrases: "new website", "start a new site", "scaffold a website", "spin up a site", "build a new website", "set up a new web project", "website starter", "which stack for this site".

- Skill: `karero/new-website` (Agent Skill, multi-file: 265 files)
- Install (CLI): `npx get-skill add karero/new-website`
- Raw SKILL.md: https://api.skillmd.com/api/skills/karero/new-website/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: karero (https://skillmd.com/u/karero)
- Updated: 2026-11-17
- Page: https://skillmd.com/skills/karero/new-website

---


# New website — orchestrator

The entry point for every new site you build. It **decides the stack**,
**sequences the work**, and **scaffolds a self-contained, handoff-ready repo** from
this skill's `templates/`. Concrete content/SEO/design/QA work is delegated to seven
sibling skills + existing global skills.

Everything needed is bundled here:
- `templates/astro/` — the Astro starter overlay (Base.astro SEO+theme spine,
  `config.ts`, theme tokens, `astro.config`, `tests/` suite, CI, preview-noindex
  function, headers, llms.txt, GDPR privacy page draft). Its `README.md` is the
  assembly manual.
- `templates/SETUP.md` — accounts (GitHub + Cloudflare) + tools + the bootstrap.
- `templates/PUBLISHING.md` — plain-English "how to publish" for the owner
  (`commit`/`push`/`branch` explained + step-by-step per publish model), plus the
  assistant-facing **deploy-time guardrails** (§4).
- `templates/AGENTS.md` + `templates/CLAUDE.md` — the working rules every assistant
  (Codex, Claude Code) follows in the repo: fetch the latest state first, pull request
  instead of a direct push, when a merge is allowed, never invent facts, the new-page
  checklist. `CLAUDE.md` is one line (`@AGENTS.md`), so both tools read the same rules.
- `templates/.gitignore`, `templates/claude/settings.json`, `templates/claude/hooks/git-stand.mjs`
  — git ignore, the permission allowlist, and the Claude Code hook that fetches from
  GitHub at session start (and again after 2 hours) and reports what is new, so
  `AGENTS.md` §1 happens even when the assistant skips it. The settings register the
  hook: copy both, or every session start fails to find the script.
- `templates/positioning.md`, `templates/content-guide.md`, `templates/brand.md` — the per-site docs.
- `references/WEBSITE_ARCHITECTURE.md` (bundled with this skill) — the Cloudflare
  **tier 1/2/3** decision tree + limits (the tiers are also summarized in §1, question 2).
- `docs/MOVE-TO-WORKERS.md` (in the Croftweaver folder) — the owner's guide to moving a live Pages site to a
  Worker; `references/CLOUDFLARE_MOVE.md` is your own page for it. Start with the guide when asked to "move my site to Workers".

Sibling skills (run in order, each usable on its own):
`website-positioning` · `website-content-guide` · `website-seo-geo` ·
`website-design-system` · `website-testimonials` · `website-qa` ·
`website-review`. `website-positioning-check` is an optional, read-only one-screen
diagnostic for a site that already has pages — run it after the build, or whenever the
offer starts to feel blurred; it is not a pipeline gate. `website-launch-check` is the launch
readiness check: it runs the site's tests first, checks only what they cannot, and writes a
dated report with a verdict to `docs/launch/` (a baseline at step 5a, the verdict at 10c, the
live re-check at 12a). Plus `outgoing-link-audit` — the
pre-launch / monthly external-link
liveness sweep (only relevant once the site links out); `internal-link-audit` — the
internal-linking sweep that finds orphaned + thin pages and suggests where to cross-link
(run after adding a batch of pages); `website-permissions` — install + safely extend the
repo's permission allowlist (fewer prompts, same guardrails); `search-console-setup`
— post-launch GSC + Bing registration + IndexNow; and `website-motion` — an OPTIONAL
polish layer (stat count-up + section-heading reveal) for sites with a long scrolling
homepage, plus the reduced-motion contract and the a11y-gate change that keep motion
from silently hiding content. `website-motion` is never run by default: ask for it.
`website-story` is an OPTIONAL story layer (the home page told as the customer's story:
`STORY.md` + a seven-section home page map); it is offered once at §2a, right after
positioning, and never runs unasked. `website-scorecard` is an OPTIONAL public scorecard
(a section that shows what the site's own test gate checked, dated, plus the owner's
Lighthouse scores); it runs only when the owner asks for it. `website-tagline` is an
OPTIONAL skill for the short line under the logo (it starts from the purpose in
`POSITIONING.md`, shows the owner six to eight lines and lets them pick one →
`TAGLINE.md` + `SITE.tagline`); it too runs only when the owner asks for it.
`website-brand-kit` is OPTIONAL help with colours and a logo for an owner who is not a
designer (three prompts for the design tool she likes, then a checked install of the
palette and the seven icon files); the owner is asked once at §2b, right after
positioning and the story, and it never runs unasked.
`website-team-setup` is the other on-demand skill — run it once when a **second person**
joins the repo (invite collaborators, repo settings, prove CI triggers, block direct
pushes to `main`, connect Cloudflare (a Worker with Workers Builds) without the known traps, set the rights level
in `AGENTS.md`); a single owner needs none of it, though one who works alone but runs several assistant
sessions at once, or lets the assistant merge, may choose its §4 and §5 (CI starts, then the
`main` ruleset); its opening note says what to set first. An option, not a step.
A private repo gets 2 000 free CI minutes a month on GitHub Free (about 400 runs of the kit's
`ci.yml`); past that, jobs stop with a message that reads like a failed payment. Tell the
owner to check **Budgets and alerts** for an Actions budget (`website-team-setup` §3b has
the steps).

## 1. Decision interview (answer before any code)

**Conduct the interview — and ALL user-facing guidance throughout this pipeline
(explanations, the §3a link-sweep question, the §4 preview-vs-live announcements,
error walk-throughs) — in the language the user writes in.** A German owner gets
the whole journey in German; the skill files themselves stay English. The
verbatim message templates below are content specs, not required English wording.

**The folder check, this interview and the §2a and §2b questions: read and list, don't
run commands of your own.** A command this interview names, such as the analytics check,
runs once the site exists. To see what a folder holds, list it with your file tools; to
read a section of another skill, open that skill's `SKILL.md` and read it. A shell command
can show the owner a red error for an ordinary answer: `ls astro.config.*` fails in an
empty folder because nothing matches, and `grep` or `awk` can end with a failure when they
find nothing. Where reading a file or listing a folder is possible only through a shell
command, use one that succeeds on every ordinary answer: `ls -A` for the folder (never a
pattern such as `astro.config.*`), and `cat` on the whole `SKILL.md`. Ask your questions
as plain chat messages, not in a pick-list box, which a new owner may not see. The
owner's first minutes should show no red and no frozen screen.

Default house stack: **Astro (static) → GitHub → Cloudflare Workers**. Six questions
decide everything downstream — ask them in order, offer the examples so a
non-expert can answer, and record the answers in the project `README.md`.

1. **Pages + content types — what does the sitemap look like?**
   *Decides: plain pages vs Content Collections.*
   - A handful of fixed pages (home, services, about, contact, imprint — ≤ ~15)
     → plain `.astro` pages. Example: a small-business brochure site.
   - Anything that repeats with the same shape — blog posts, events, case
     studies, team members → Astro **Content Collections** (one schema, one
     template, n entries) + the `Base` layout. Example: an event archive where
     every event has date/speaker/location.
   - Mixing both is normal: flat pages + one collection.

2. **Any dynamic/backend behaviour — what must a server actually do?**
   *Decides: the Cloudflare tier. Pick the LOWEST tier that fits — going higher
   is the classic mistake. Tier tree + limits: `references/WEBSITE_ARCHITECTURE.md`.*
   - Visitors only read; contact is an email link, or a contact form that
     opens the visitor's own mail program → **Tier 1 static** (~90% of sites).
     A contact form: run **`website-contact-form`**, our suggestion (no server,
     no account, no setting). Photos that rotate by themselves, with dots: run
     **`website-hero-carousel`** (optional, on request; one strong photo is often better).
   - Exactly one small server task — site search, hiding a third-party API
     key, one live widget (e.g. a next-event box fed by an API), a form that
     must send through a server → **Tier 2** (one Worker script or server
     island). No skill builds such a form.
   - State per user — accounts/login, a database, checkout, user-generated
     content → **Tier 3** (SSR + D1). Rare; challenge the requirement first.

3. **Who edits content after launch?**
   *Decides: CMS or not.*
   - The owner/Claude editing files in git → **no CMS** (default; markdown +
     redeploy is the workflow).
   - A non-technical person (client, co-organizer writing posts) →
     **Keystatic** (git-based, no separate backend). Can be added later —
     don't install it speculatively. When chosen, run **`keystatic-setup`**
     (local mode; the GitHub cloud-mode upgrade is documented there).

4. **One language or several?**
   *Decides: i18n routing from day 1 or never.*
   - One language (German-only counts) → skip i18n entirely.
   - Two+ **at launch** (e.g. a DE+EN consultancy site) → run
     **`astro-i18n-setup`** (Astro i18n: clean default locale + prefixed others,
     self-referencing hreflang + `x-default`, sitemap alternates, language switcher,
     per-locale test harness).
   - **Multilingual, but building one language first?** Fine — keep the default locale
     **unprefixed** from day 1, ship/test the primary language, then run
     **`astro-i18n-setup`** to add the second locale when translations are ready. Because
     the default stays at `/`, that's additive, not a breaking retrofit (skill →
     *Phased rollout*).
   - "Maybe English someday" → treat as one language now; the unprefixed default keeps a
     future second locale additive. **The only costly change is later moving the default
     off `/`** (e.g. `/` → `/en/`).

4a. **What language should the content actually be written in?**
    *Decides: the copy language — a separate decision from Q4's routing question above.*
    Answering "one language" in Q4 does **not** mean English. The starter defaults to
    English (`templates/astro/src/config.ts` ships `locale: 'en'`, and the placeholder
    homepage copy is English prose) — say so explicitly if you want German, or another
    language, instead. **German-only is a completely valid, common answer** here, not
    just "English, obviously, unless multilingual."

5. **Analytics — will anyone act on the numbers? (optional)**
   - Just "is anyone visiting?" → **Google Search Console** (free, no script, no consent
     banner) is enough for traffic from Google search; it does not show which other
     sites send visitors, and Cloudflare's docs list no referrer view for the Free plan.
     Cloudflare also counts the domain's traffic at its own servers, with nothing added
     to the pages: https://dash.cloudflare.com → your domain → **Analytics** →
     **Traffic**. On the Free plan that is requests, bandwidth, unique visitors and up
     to five top countries for at least the last 30 days, bots included; page views, and
     filtering by referrer, need a paid plan
     (https://developers.cloudflare.com/analytics/account-and-zone-analytics/zone-analytics/,
     checked October 2026). It counts requests and visitors, not events such as an
     enquiry, so it cannot give the enquiry count. Cloudflare's separate "Web Analytics"
     cannot either: its FAQ answers custom events with "Not yet"
     (https://developers.cloudflare.com/web-analytics/faq/, checked October 2026). It is
     also a script in the visitor's browser, so keep it off
     (`docs/CLOUDFLARE-CHECKLIST.md`, section 3, "Cloudflare Web Analytics: Off").
     The starter ships with its own analytics off
     (`USE_ANALYTICS = false` in `src/config.ts`, no analytics host in
     `public/_headers`), so leave both as they are and delete the analytics paragraphs
     of section 3 of the privacy page.
   - "Which sources bring enquiries?" or other real decisions from traffic data
     (campaigns, content strategy) → **Plausible** (cookieless; whether it needs a
     consent banner: the last point of this question). In its installer, untick the
     optional measurements (outbound links, file downloads, form submissions)
     unless you keep the privacy page's slot sentence for each one you leave ticked.
     Plausible's menus hide the pages the owner needs, so give each one as a link,
     with `scriptHost` and the site's domain (as added in Plausible) filled in: the
     installer and the script id at `<scriptHost>/<domain>/installation`, the goals at
     `<scriptHost>/<domain>/settings/goals`, a new site at `<scriptHost>/sites/new`.
     Seen on a self-hosted Community Edition instance on 2026-10-16: the owner added
     the goal on that goals page; the other two sent a signed-out visitor to the
     login page, where an unknown path gives 404. On Plausible Cloud (`scriptHost`
     `https://plausible.io`) the same paths are expected, not checked. If a link
     gives 404, say so, and find the page in Plausible's own menus with the owner.
     Ask whether the owner already runs a Plausible server. If not, the usual case,
     recommend the **paid cloud version** (from **€9/mo** —
     https://plausible.io/#pricing), so the owner runs no server; point at a
     **self-hosted** instance only if one already exists. The enquiry count (the
     "Email Tap" paragraph below) needs Plausible: Cloudflare's counts have no events.
     **Switch it on**, since the starter ships with analytics off: in `src/config.ts`
     set `USE_ANALYTICS = true` and fill in `scriptHost` and `scriptId`, then add the
     same host to `script-src` and `connect-src` in `public/_headers` (the comments in
     both files say how). Keep the privacy page's analytics paragraphs and fill their
     slots. Run `bash tests/check_analytics_gate.sh` once to check the builds and the
     headers (a site's CI does not run it). Without the switch the live site counts
     nothing, and nothing says so.
     **The enquiry count comes with it.** Each click on an email address, and each
     press of the contact form's button that passes its checks, sends one "Email Tap"
     event (with the page and the referrer, as every event; no address, nothing typed).
     On the site's goals page in Plausible (`<scriptHost>/<domain>/settings/goals`,
     under Settings > Goals; open the address directly, owners find the page hard to reach from the dashboard), add a goal of type "Custom event"
     named exactly `Email Tap` **before launch**: Plausible's documentation says an
     event shows only once its goal exists and earlier ones are not counted. Once a
     test tap has reached Plausible, the goals page offers `Email Tap` to add in one
     click. That rules out a typo in the name (seen on a self-hosted instance).
     To see a test tap, choose Today or Realtime: Plausible's "Last 7, 28, 30 and 91 days" views
     end yesterday (checked on self-hosted version 3.2.1; the cloud version may differ).
     On a site just added to Plausible, a tap in its first
     minute or so may not be kept; tap again a few minutes later. Filtered
     by that goal, the dashboard shows which sources and pages bring enquiries. It
     counts visitors who asked to write an email; whether their mail program opened,
     and whether they sent the mail, the site never learns.
     **Script only.** Plausible runs as a script in the browser. Server mode, where the
     site's own Function sent each page view and email tap to Plausible, is no longer offered:
     a Worker with no script of its own cannot run one. A site made before 0.35 in server
     mode keeps its own copy of that code.
   - Prefer cookieless tools over Google Analytics, which would pull in a
     cookie-consent banner — for German-market sites the statute behind that
     banner is § 25 TDDDG (formerly TTDSG). Third-party additions put the
     banner-free position at risk by different routes: a YouTube iframe triggers § 25
     itself (device storage/readout), while remote Google Fonts change the
     answer via the GDPR instead (unconsented IP disclosure — LG München I,
     3 O 17493/20; self-host fonts, as this starter does). Any analytics script is gated to the production branch only.
     The
     privacy page must match whatever is chosen here.
   - **When the site needs no consent banner.** Tell the owner plainly: a site built
     with this kit needs no consent banner in the EU, Germany, Switzerland or California
     as long as it runs no analytics script: nothing reaches the visitor's browser that
     the page itself does not need. For the starter's own
     analytics that means leaving `USE_ANALYTICS = false` in `src/config.ts`, as it ships
     (the first point of this question; the other things that break the no-banner case
     are listed below); run `bash tests/check_analytics_gate.sh` once to check that no
     build writes the script (a site's CI does not run it). Plausible runs as a small script in the visitor's
     browser. With it, running without a banner is a defensible position in the EU,
     Germany, Switzerland and California, not a settled one; to be sure, ask a lawyer.
     For the EU and Germany, the headers of `privacy.astro` and `_datenschutz.astro` set
     out the sources on both sides and ask you to record who accepted the position. In
     Switzerland and California the position rests on the privacy page informing
     visitors. Switzerland (Art. 45c FMG) asks that visitors are told about the
     processing and its purpose, and that they may refuse it; California's CalOPPA asks
     the page to say whether third parties may collect personal information across
     websites through the site, and how the site answers "Do Not Track" if it collects
     such information itself. Section 3 of `privacy.astro` says both;
     `_datenschutz.astro` says the Swiss part. California's CCPA applies only above its
     thresholds (USD 26,625,000 annual gross revenue from 1 January 2025, adjusted every
     two years; or buying, selling or sharing the personal information of 100,000 or
     more California consumers or households; or half the revenue from selling or
     sharing it). A site without a banner still needs its privacy page, an imprint in
     Germany and Austria, and a processing contract with Cloudflare, and with Plausible
     if it runs on Plausible Cloud. What breaks the no-banner case: any Cloudflare
     feature that section 3 of `docs/CLOUDFLARE-CHECKLIST.md` (in the Croftweaver
     folder) asks you to switch off, the script monitor among them; a YouTube embed;
     remote Google Fonts; another analytics tool. A theme toggle that stores the
     visitor's choice needs a look too (the same headers say why). Not legal advice.

6. **Domain + how do changes go live? (publish model)**
   *Decides: the publish workflow — a safety-vs-simplicity trade-off. **Offer both, explain
   them, let the owner choose**; recommend two-stage. Record the choice in the README.*
   - New domain or subdomain of an existing site? (Affects canonical URLs and whether
     existing SEO authority carries over.) DNS moves to Cloudflare.
   - **Two-stage — recommended (default).** `main` is an **unlisted, noindexed preview**
     (a Worker's Preview link, which Cloudflare noindexes: public-by-URL, not access-controlled); `production` is
     the **live** site. The owner pushes to `main`, checks
     the preview link, then runs **`npm run ship`** to publish. A mistake never reaches the
     live domain. *Scaffold adds:* the `production` branch and the `ship` script (Cloudflare
     adds `noindex` to Preview links itself).
   - **Single-stage — simplest.** One branch — `main` is live, so every push goes straight
     to the public site. Fewer moving parts, no safety net. Pick this only for a low-stakes
     site whose owner is fine with "save = instantly public." **Note:** a new site's
     live `workers.dev` address is off and its Preview links are noindexed, so a single-stage site is invisible
     to Google until a **custom domain** is attached — say this when recommending it.
   - **Don't assume git fluency.** Whichever they choose, hand them
     `templates/PUBLISHING.md` (plain-English `commit` / `push` / `branch` + the exact
     step-by-step to publish) and walk the **first** publish through with them.

Plain hand-written HTML (static `.html` files, no build step) is a legacy anti-pattern — use Astro.

## 2. The pipeline (the order to use the skills)

| # | Step | Skill / source |
|---|---|---|
| 1 | Insights: ICP, voice-of-customer, competitor scan | `customer-research` |
| 2 | Positioning: what you offer, for whom, market category → `POSITIONING.md` (Dunford) | **`website-positioning`** |
| 2a | Optional: the home page as the customer's story → `STORY.md` (offered once, §2a; positioning stays the source of truth) | `website-story` |
| 2b | Optional: colours and a logo (asked once, §2b; her choices are made here, the install waits for the green baseline of §3 step 5) | `website-brand-kit` |
| 3 | Tone of Voice, EEAT, page inventory → `CONTENT_GUIDE.md` + `BRAND.md` (its palette and logo come from step 2b, where the owner brought or chose them) | **`website-content-guide`** |
| 4 | Pages, clean URLs, nav, internal links | `site-architecture` |
| 5 | Decision interview + scaffold the repo | **this skill** §1, §3 |
| 5a | Baseline launch check on the green scaffold (after the brand-kit intake, where there is one): the settings in `docs/launch/config.json` and the first punch list, "Baseline, not a launch verdict" | **`website-launch-check`** |
| 6 | Build: mobile graphics, dark mode, theme tokens | **`website-design-system`** |
| 6 | Build: head metadata within limits, schema, llms.txt | **`website-seo-geo`** (+ `schema-markup`, `ai-seo`) |
| 6 | Build: per-page OG share cards (`npm run og` → 1200×630 ≤300 KB, tested) | **`og-images`** |
| 6 | Build: testimonials / Review schema from one data file (if the site has quotes) | **`website-testimonials`** |
| 7 | QA: the starter's test suite (a11y light+dark, seo, navigation, images, tone, positioning, placeholders, email, links and more) | **`website-qa`** |
| 8 | Performance: Lighthouse / PageSpeed for FCP & LCP | **`website-qa`** perf section (+ `seo-audit`) |
| 9 | **Double-Knuth review** (correctness + cross-file consistency) | **`website-review`** |
| 10 | Outgoing-link liveness sweep — **only if the site links out** (see §3a) | **`outgoing-link-audit`** |
| 10b | Internal-link sweep — orphaned + thin pages (run if the site grew past a handful of pages) | **`internal-link-audit`** |
| 10c | Launch check: the verdict before launch (🟢 / 🟡 / 🔴), and for a site that replaces an older one the current-vs-new comparison with its redirect map; §4 starts after 🟢, or a 🟡 the owner accepts | **`website-launch-check`** |
| 11 | Launch & handoff: schema/sitemap/robots, deploy, hand over | **this skill** §4 |
| 12 | Post-launch: register with Google Search Console + Bing, submit sitemap, enable IndexNow | **`search-console-setup`** |
| 12a | Once launch day's work is done: the live re-check (HTTPS, the 404 status, the Cloudflare zone settings and setup tokens read in the dashboard; optionally speed on the live domain as `website-qa` §2 measures it and the new site's row of the comparison) | **`website-launch-check`** |
| 13 | Post-launch: claim Google Business Profile + Bing Places, verify `sameAs` profiles resolve — **only if the site is a claimable entity** (see §4a) | **`business-listings-setup`** |
| 14 | Post-launch: ask once for a "Built with Croftweaver" credit in the footer — a request, never a condition (see §4b) | **this skill** §4b |

Work out **positioning** (step 2) *before* any content or SEO — it decides what the
copy is even trying to say. Build the Content Guide (step 3) *before* writing page
copy; positioning and voice are inputs to everything downstream, not an afterthought.

The build is **test-driven, not test-after**: the suite is green from commit 1,
and steps 6–7 run as a loop per page (red → green → commit, see §3 step 5 and
`website-qa` §1b). Step 7 in the table is the *final full-suite gate*, not the
first time tests run.

## 2a. Story layer — offer once, right after positioning

`website-story` is optional and the owner has usually never heard of it, so explain
before asking. Once `POSITIONING.md` is filled (step 2) and before the content guide
(step 3):

1. Open `website-story/SKILL.md` (in the folder next to this skill's folder) with your
   file tools (§1), read **"The offer"** and say it in the language the
   owner writes in (it explains the idea in plain words: the visitor as the hero, the
   brand as the guide, a one-liner, a three-step plan, one repeated call to action,
   positioning unchanged). Do not paraphrase it into jargon.
2. Ask once, as a plain message in the chat (not a pick-list box: on a first run the owner
   may not see one and think you have stopped), with the two answers written out: **Yes,
   build the home page as a story** / **No, standard home page (default)**. Wait for the
   reply.
3. **Yes** → run `website-story` now, before step 3, so `CONTENT_GUIDE.md`'s home row
   and `copywriting` read `STORY.md`.
4. **No, or no answer** → say nothing more about it. The skill still travels with the
   repo (§3 step 3), so it can be run later whenever the owner asks.
5. **Record the answer either way** ("home page: story-led, see STORY.md" or "home page:
   standard, story layer declined") with the decision-interview answers when §3 writes
   the project README, so a later session knows the offer was made and does not ask
   again.

Ask exactly once per build. Never run it unasked.

## 2b. Colours and logo — ask once, after positioning and the story

`website-brand-kit` is optional. It is a plain question, not a pitch. Once
`POSITIONING.md` is filled (and §2a is answered) and before the content guide (step 3):

1. Open `website-brand-kit/SKILL.md` (in the folder next to this skill's folder) with your file tools
   (§1), read **"The question"** and ask it, as it stands
   there, in the language the owner writes in, as a plain message in the chat (not a
   pick-list box, as in §2a), and wait for the reply.
2. **She has a part and wants it used** → note the path of her logo file, which must
   be an SVG, or her colours as hex values. No prompt is written for that part. Her own
   colours still go through the skill's check (its §3 step 3) now.
3. **She wants help with a part** → run now, before step 3, the steps before §6 that
   `website-brand-kit` §0's table names for her answer, and only those (help with
   colours alone does not start the logo steps, and the other way round), so the
   palette exists when `BRAND.md`'s "Brand in one line" is written. These steps are a
   conversation: nothing is written into a project yet (there is none).
4. **She lacks a part and wants no help with it** → say nothing more about it. The site
   keeps the starter's colours and the scaffold's placeholder icons for that part. The
   skill still travels with the repo (§3 step 3).
5. **Record the answers either way** with the decision-interview answers (what she has,
   what she wanted help with, the path of her own logo file or of her package, and,
   where she took the help, the palette and the variation she picked), so a later
   session knows the question was asked and does not ask again. Until §3 step 4 writes
   them into the project they live in this conversation: do that step in the same
   session, or write them into a note in the folder you are working in.
6. **The install comes later:** §3 step 5, on the green baseline.

Ask exactly once per build. Never run it unasked.

## 3. Scaffold the project (handoff-ready)

**Prerequisites (one-time).** Walk the user through `templates/SETUP.md` if needed —
Node/git/gh/wrangler + image tools, a **private GitHub** account, a **Cloudflare**
account. The accounts are a human action the agent cannot do. When the owner sets up
GitHub, tell them plainly that the account and the website in it are theirs, and recommend
two-factor sign-in with a passkey to keep others out (`SETUP.md` §1 has the link); for
Cloudflare, which decides whether the site is online, the same with a security key or the
device's fingerprint or face unlock. Recommend, never require: GitHub makes it mandatory only
for some accounts, and Cloudflare leaves it optional unless an account's administrator
enforces it for members.

Assemble the project at `<site>/` so it travels without any global setup. `<site>` is a new
folder inside the owner's websites folder, which is the folder this session was opened in
(never that folder itself). Before step 0, unless the owner has already confirmed it in this
session, look at the folder you are in. If it is hidden (a part of its path starts with a
dot, such as `~/.gemini/…`) or is a tool's own scratch or temp folder, don't ask about it:
the owner could not find the site there. Ask them to make a folder they can see, for
example `Websites` in their Documents folder, and to tell you its name. Otherwise say which
folder you are in and ask whether it is their websites folder. If it is not, or it already
holds a site (an `astro.config.*` or `index.html` file) or is the toolkit folder (it has
`skills/new-website/SKILL.md`), ask which folder is their websites folder instead. A folder
the owner names themselves counts as their websites folder; if it is hidden or a tool's
scratch or temp folder, say they may not find the site there again, and ask once whether to
use it anyway. Find this out
by listing the folder with your file tools (§1). Start step 0 from the websites folder,
and once `<site>` exists, tell the owner its full path (the output of `pwd` inside it):

0. **Git first, before any code:**
   ```bash
   # Resolve where the suite is installed (the cp SOURCE). Per tool:
   #   ~/.claude/skills = Claude Code · ~/.agents/skills = Codex · ~/.gemini/config/skills = Antigravity
   # Honour an explicit $SKILLS_ROOT; else auto-detect. First the folder this very skill was
   # loaded from: in the first candidate of the loop below, Claude Code puts this skill's
   # own folder where the name in braces stands, which also finds the suite when it is
   # installed as a plugin and so sits in none of the three folders above. Claude Code
   # replaces the name only where nothing follows it inside the braces, so the line before
   # the loop reaches every assistant as written: where the name was left alone, it gives
   # the shell an empty value for it instead of an unset variable, the candidate reads
   # "/..", and the loop passes over it. Then Claude Code → Antigravity → Codex
   # (Claude is the default/primary), and last the suite installed as a Codex plugin, in
   # Codex's folder (CODEX_HOME or ~/.codex, written as the shell names it after cd, as
   # SKILLS_ROOT is, so the two compare). An update leaves one version there; should there
   # be more, the last in name order is taken (0.9.0 sorts after 0.33.0). It is found with
   # `find`, because a pattern that matches nothing stops zsh with an error, and a failed
   # search leaves it empty, so the candidate reads "/.." as well. On a machine with
   # more than one installed, set it yourself — e.g. `export SKILLS_ROOT=~/.agents/skills` (Codex) or
   # `~/.gemini/config/skills` (Antigravity); Antigravity workspace installs use
   # `export SKILLS_ROOT="$PWD/.agents/skills"`.
   codex_home="$(CDPATH= cd -- "${CODEX_HOME:-$HOME/.codex}" 2>/dev/null && pwd)" || codex_home="${CODEX_HOME:-$HOME/.codex}"
   if [ -z "${SKILLS_ROOT:-}" ]; then
     SKILLS_ROOT="$HOME/.claude/skills"
     : "${CLAUDE_SKILL_DIR:=}"
     codex_plugin="$(find "$codex_home/plugins/cache/croftweaver/croftweaver" -mindepth 2 -maxdepth 2 -type d -name skills 2>/dev/null | sort | tail -n 1)" || codex_plugin=
     for d in "${CLAUDE_SKILL_DIR}/.." "$HOME/.claude/skills" "$HOME/.gemini/config/skills" "$HOME/.agents/skills" "${codex_plugin:-/..}"; do
       [ "$d" != /.. ] && [ -d "$d/new-website" ] && SKILLS_ROOT="$(cd "$d" && pwd)" && break
     done
   fi
   # Where bundled skills go IN the generated project (the cp DESTINATION). Claude default
   # (.claude/skills). Codex and Antigravity read repo-scoped skills from .agents/skills, so
   # derive that when the suite was installed through either of them. Force it with:
   # export PROJECT_SKILLS_DIR=.agents/skills
   if [ -z "${PROJECT_SKILLS_DIR:-}" ]; then
     case "$SKILLS_ROOT" in
       "$HOME/.agents/skills"*|"$HOME/.gemini/config/skills"*|*/.agents/skills*|"$codex_home"/plugins/*) PROJECT_SKILLS_DIR=".agents/skills" ;;
       *) PROJECT_SKILLS_DIR=".claude/skills" ;;
     esac
   fi
   mkdir <site> && cd <site> && git init
   cp "$SKILLS_ROOT"/new-website/templates/.gitignore .
   git add .gitignore && git commit -m "chore: init repo with .gitignore"
   ```
1. **Scaffold + overlay:** run the scaffold without questions, so it never waits for a key,
   then put back step 0's `.gitignore`, which the scaffold replaces with its own (that one
   lacks the lines keeping `.env.*`, `.dev.vars` and sign-in files out of git):
   ```bash
   npm create --yes astro@latest . -- --template minimal --no-install --no-git --yes --skip-houston
   cp "$SKILLS_ROOT"/new-website/templates/.gitignore .
   ```
   (The first `--yes` answers npm's own "Ok to proceed?", the second create-astro's
   questions; checked with npm 11.20.0 and create-astro 5.3.1, run fresh with no keyboard input. `minimal` is Empty, with TypeScript strict.
   The `cp` copies step 0's file again, with no git command, so it works where an assistant's
   `git checkout` is refused. Nothing is installed yet:
   `templates/astro/README.md` step 3 runs `npm install` after the overlay.) Then copy
   the `templates/astro/` overlay (`src/`, `tests/`, `public/`, `wrangler.jsonc`,
   `scripts/`, `.github/`, `.nvmrc`, `.gitattributes`, `CROFTWEAVER-LICENSE.md` (the licence of
   these copied files; it stays in the site's top folder), root configs — see `templates/astro/README.md`
   for exact steps and npm deps). **Do not copy the starter's `README.md`:** it is the kit's
   assembly manual, and the site's own `README.md` holds the owner's answers, the
   `legal pages:` line included. A copy of the whole folder replaces it. Run `git add README.md`
   before the copy; after it, `git diff --quiet -- README.md` must succeed. Set the real domain in `astro.config.mjs` (`site:`),
   `src/config.ts` (`url`), `public/robots.txt` (the `Sitemap:` line) and `public/llms.txt`
   (every `https://example.com` link); the first `npm test` fails while `robots.txt` or
   `llms.txt` still names `example.com`. **Set `SITE.name` there too, then run `node scripts/make-icons.mjs --setup`
   after `npm install`:** it draws the site's first letter on its `--brand` colour into the seven icon files the
   starter links, and the first `npm test` fails without them. A name that starts with no letter A–Z or digit
   needs a letter from the owner: add `--letter X`. **Set `SITE.locale` in `src/config.ts` to match the interview's
   Q4a content-language answer** (and `lang` in `Base.astro` too, if not running
   `astro-i18n-setup`). **`'de'` flips the footer's links to `/datenschutz` and `/impressum`** —
   do both swaps in the SAME step (rename the in-repo drafts
   `src/pages/_datenschutz.astro` and `src/pages/_impressum.astro` per their headers: page file,
   `tests/_helpers.ts` PAGES, `public/llms.txt`, `OWN_CARD_EXEMPT`,
   `POSITIONING_EXEMPT` + `UNFILLED_UNTIL_LAUNCH` in the specs; the Impressum replaces
   `legal-notice.astro`) or every intermediate `npm test` fails navigation on a footer link.
   The overlay ships `locale: 'en'`, and leaving that default in
   place for a German-content (or other non-English) site is exactly the silent-default
   bug Q4a exists to catch.
   **This starter needs Node ≥22.23.5**, and Node's current security fixes are in 22.23.5, 24.22.3 and 26.13.1 (one per line).
   The overlay's `.nvmrc` pins 26 for local + Cloudflare's builds. If `npm install` prints
   `EBADENGINE` for the site's own package (the `name@version` in the site's `package.json`, whatever the
   owner named it) and `node`, stop and have the owner update Node (SETUP.md) before going on; a warning
   for another package is not this.
2. **Permissions + working rules.** Copy the setup guide into the project (all tools), then — **Claude Code
   only** — copy the allowlist so routine `npm`/`astro`/`playwright`/`git status` calls don't
   prompt (a commit still asks; it blocks `rm -rf`, force pushes, `wrangler … delete`, `gh repo delete`: Claude Code
   refuses them, and the owner runs one by hand if needed):
   ```bash
   cp "$SKILLS_ROOT"/new-website/templates/SETUP.md .          # all tools — receiving party can set up too
   cp "$SKILLS_ROOT"/new-website/templates/PUBLISHING.md .     # owner "how to publish" + assistant deploy guardrails
   cp "$SKILLS_ROOT"/new-website/templates/AGENTS.md .         # working rules for every assistant (Codex + Claude)
   cp "$SKILLS_ROOT"/new-website/templates/CLAUDE.md .         # one line: @AGENTS.md
   # Claude Code only:
   mkdir -p .claude/hooks
   cp "$SKILLS_ROOT"/new-website/templates/claude/settings.json .claude/settings.json
   cp "$SKILLS_ROOT"/new-website/templates/claude/hooks/git-stand.mjs .claude/hooks/   # sync hook the settings register
   ```
   *Codex / Antigravity: skip the `.claude/settings.json` copy — it's Claude Code-specific.
   Use their own approval systems instead (Codex: `AGENTS.md` + Codex rules/config;
   Antigravity: its sandbox approval model).* For Claude's allow/deny model and how to extend
   it safely when a prompt keeps recurring, use **`website-permissions`**.
   **Fill `AGENTS.md` now**, per the scaffold note at its top: site name, live URL, the
   preview URL (a Worker: the Preview link of the form `https://<prefix>-<worker>.<account>.workers.dev`,
   which Cloudflare shows on the build, so update it once the first build exists; single-stage:
   "pull-request previews only" — `main` is live there; a site on Pages: `main.<project>.pages.dev`,
   or "pull-request previews only, `<branch>.<project>.pages.dev`", using the address on the
   project's page where Cloudflare gave it one other than its name), `[TITLE_SUFFIX]` = the
   ` | {SITE.name}` string `Base.astro` appends, `[SUFFIX_LENGTH]` = its length, and
   `[TITLE_MAX]` = 60 minus that length; keep ONE publish-model block in its §2 (the
   interview's Q6 answer) and delete the other. §5 (collaborators, rights level, merge
   rule, who publishes) ships with single-owner defaults, not slots; `website-team-setup`
   rewrites it when a team forms. `AGENTS.md` stays English for every owner, like the
   skills: agents read it, and its Language rule has them reply in the person's
   language. Only the human-facing `PUBLISHING.md` gets translated (see §4).
3. **Skills travel with the repo** — copy the twenty-nine always-on skills in, plus any
   conditional setup skills selected by the interview, so the handoffs resolve for the
   receiving party. "Always-on" here means always **copied** into the project, not
   necessarily always **run**: `business-listings-setup` travels with every repo but
   only executes when §4a's gate says the site is a claimable entity — it still needs
   to be in the repo so a later session can run it once that's true. The always-on set is the
   seven core `website-*` siblings, `website-positioning-check` (always copied, optional to run),
   the three SEO-depth skills they delegate to — `ai-seo`, `schema-mark

…(truncated)
