AI agents

biagiojs ships first-class material for LLMs and coding agents: a curated index, a full operational guide in the npm package, and documentation structured for retrieval.

Quick links

Resource	URL
llms.txt (site index)	/llms.txt
AI-GUIDE.md (full reference)	GitHub
Documentation	/docs/

Point your agent at https://biagio.danilosprovieri.com/llms.txt for a compact map of every guide. For implementation detail, read AI-GUIDE.md in the biagiojs npm package (also on GitHub).

Mental model

biagiojs is SSG-first + islands, business-aware. Components declare business weights (conversion, seo, interaction, 0–1) and costs (cpu, network). The build decides:

HTML source order (what hits the wire first)
hydration plan (eager / lazy / static)
preload by value/KB
SEO, consent, i18n

Golden rule: static is the desired default. Pages without islands ship zero JavaScript in production.

Agent workflow

npx create-biagiojs my-site
cd my-site && npm install

Set site.baseUrl to the real production URL (canonical, sitemap, OG depend on it).
Prefer pages/*.page.biagio for declarative pages.
Use weight tables from Business weights — do not invent random numbers.
Run npx biagio build . and read the render order + hydration log.
Run npx biagio doctor . before deploy.

Weight reference (do not guess)

Component type	conversion	seo	interaction
Hero / main CTA	0.8–1.0	0.7–1.0	0.5–0.9
Product card	0.6–0.9	0.5–0.8	0.3–0.6
Navigation	0.1–0.3	0.2–0.5	0.4–0.7
Footer / legal	0.05–0.1	0.3–0.5	0.01–0.05
Chat widget	0.03–0.1	0.1	0.1–0.3

Low conversion + high network cost → stays static (no JS).

Files agents should read first

Getting started — config and first page
Syntax (.biagio) — weights and hydration attributes
Automatic SEO — page meta, sitemap, hreflang, llms.txt
Consent — never load trackers without gating
AI-GUIDE.md — exhaustive reference

SEO for agents

site.baseUrl must be the live domain.
page.hideBreadcrumb: true when you render your own breadcrumb in the layout (JSON-LD breadcrumbs still work).
robots.txt and sitemap.xml are generated at build; submit https://yoursite.com/sitemap.xml in Google Search Console.
Add /llms.txt at the site root for LLM discovery (copy from this docs site's public/llms.txt pattern).

Common mistakes

Hydrating everything — defeats the framework; use weights.
Skipping baseUrl — breaks canonical and sitemap.
Loading analytics without data-cvw-consent or island consent=.
Using fonts.googleapis.com in production instead of site.fonts self-host.