Sitesmith Session Report

How sitesmith makes a site

The factory line

Every client site comes from the same few parts. Most of today's faults sit at the joins between these steps.

InputClient JSONName, phone, plan, starter

Commandsitesmith newCopies the parts together

PartsTemplate + starter + kitSkeleton, sample layout, building blocks

EditReal contentText, logo, colours, photos

Checkverify + auditTests, Lighthouse, launch blockers

Part 1

What we built

NGDC client site

Natural Gas Distribution Company, Riyadh. Pro plan, 8 pages.

Client file written from ngdc.com.sa.
All sample text replaced with NGDC's real content in English and Arabic: profile, vision, CEO message, quality policy, operations, safety, 8 FAQs.
Real logo, brand colours taken from it, new social-share image.
14 of 15 launch blockers cleared. Only the Turnstile key is left.
Recreated on kit 0.7.0 after the upgrade broke it.

branch feat/ngdc-client · 1 commit · adds NGDC to CI

Scrolling logo carousel

A new marquee option for the client logo strip.

CSS only: an endless loop that pauses on hover.
Runs the other way in Arabic. Stays still for "reduce motion".
Turned on for Saudi EMAR.
Default for new sites in the starter and template.

branch feat/client-logos-marquee · 4 commits

Ironcrest template

Your Ironcrest HTML turned into a design any site can pick.

design: "ironcrest" or "classic" in site.config.ts. Existing sites stay classic.
Four new blocks: hero badges, process steps, testimonials, team.
An energy starter with Ironcrest's layout and sample text in both languages.
Starters made pluggable, which fixed fault 1.
Demo site "Najm Energy" passed the full test run. The demo caught a phone-width bug, now fixed.

branch feat/ironcrest-design · 9 commits

Setup and orientation

Getting the tools working on this machine.

Read the handoff's "Start here" rules: no deploys, no client contact, no prices, no AI mentions in commits.
Installed the sitesmith command as a link in ~/.local/bin.
Pull requests blocked: Tatsumi-03 can only read the repo, and Kae-ser can't see it.

no branch · environment only

Part 2

Faults found in sitesmith

Twelve problems, sorted by how much they matter. The coloured edge on each row shows impact: red is high, amber medium, grey low.

1 fixed 4 partly fixed or worked around 7 open

#	Fault	How we found it	Impact	Status
1	The CLI ignored the profile's starter.`sitesmith new` and `audit` always used the contractor starter.	Building the energy starter	A second starter would silently get electrical sample text, and the audit would miss its leftovers.	Fixed
2	`sync-kit` doesn't update template files.Server code, build scripts, sitemap, robots and tests stay at the version the site was made from.	NGDC failed type checks after kit 0.6 → 0.7	Every kit upgrade can break older sites. The only fix is recreating the site by hand. There's no upgrade command.	Open
3	CI's client list is hardcoded.A new client isn't tested until someone edits `ci.yml`.	Preparing the NGDC pull request	New sites could merge untested.	Fixed for NGDC
4	Only one look and one starter.Every site looked alike, and the sample text only fits electrical contractors.	NGDC needed a full rewrite	Slow for any other industry.	Partly fixed
5	`bun link` doesn't install the command, though the README says it does.	Install attempt	New team members can't run `sitesmith`.	Worked around
6	The share-image script overflows.`make-og.ts` prints the name at one fixed size, so long names run off the image.	Making NGDC's share image	Broken link previews on WhatsApp and LinkedIn.	Worked around
7	One test is timing-sensitive."Every page in both languages" took 33.5 s against a 30 s limit on a busy machine.	Saudi EMAR test run	Random failures, possibly in CI.	Open
8	One kit test fails on newer Bun.It passes on CI's Bun 1.3.4 and fails on 1.4.3. Nothing pins the version locally.	Kit test runs	Red tests locally that aren't real problems.	Open
9	No `--help`.`sitesmith --help` crashes with a stack trace.	Trying the command	Confusing for new users.	Open
10	The audit flags ordinary phrases.Exact-sentence matching treats "Frequently asked questions" or "ISO 9001:2015" as sample text.	NGDC audit	Correct text has to be reworded to pass.	Open
11	A block takes only one variant."Grey" and "scrolling" can't be combined.	Building the carousel	The carousel had to build grey in.	Open
12	Each site carries about 1.1 GB of packages, because there's no shared workspace, by design.	The temp folder filled up	Disk use grows fast with many sites.	Open

Biggest risk: fault 2It hits every existing site at every kit upgrade. Fix it before the next kit release.

Closest call: fault 1It would have shipped the wrong sample text the moment a second starter existed. Fixed today.

Part 3

Mistakes I made

Listed so nothing is hidden. None of them reached GitHub.

Wrote a helper file outside the temp folder (~/dev/websites/txt.py). Moved it the same minute.
Committed the Ironcrest styles before checking the lint result. Fixed it and amended the local commit.
A stop-server command matched its own command line and ended its own step.
My Ironcrest styling made form fields too wide on 375 px phones. The tests caught it, and it's fixed.
Said sitesmith provision sets up hosting. It only writes a plan and a script. I corrected that.

Part 4

Where things stand

Branch	Commits	Tested	Pushed
`feat/client-logos-marquee`	4	Kit, CLI, template and Saudi EMAR pass	No
`feat/ngdc-client`	1	Full NGDC test run passes	No
`feat/ironcrest-design`	9	Kit and demo site pass. Template and CLI runs were stopped.	No

Get write access to dexaminds/sitesmith, then push the three branches and open the pull requests.
Finish the template and CLI test runs for the Ironcrest branch.
Create NGDC's Turnstile anti-spam key in Cloudflare.
Decide whether Saudi EMAR moves to the Ironcrest design.
Fix fault 2 with an upgrade path for template files, before the next kit release.

One session, three branches, twelve faults