@the-smithy/hearth 0.13.0 → 0.13.1

package/README.md

@@ -9,12 +9,15 @@ nothing without a Hearth account. Developer access is by invitation: request it
 
 ## Getting started
 
-Most sites start from the starter template, which has this package set up already:
+Most sites start from the starter template, which has this package set up already. For example, for a site
+whose address in Hearth is `acme` (the part after `/admin/sites/` in Hearth's address bar):
 
 ```sh
-pnpm create @the-smithy/hearth-site my-site --site <your-site>
+pnpm create @the-smithy/hearth-site@latest acme-website --site acme
 ```
 
+`acme-website` is the folder it creates. Keep `@latest`: pnpm otherwise skips a release in its first day.
+
 To add it to an existing project instead:
 
 ```sh
@@ -22,9 +25,9 @@ pnpm add @the-smithy/hearth
 ```
 
 ```dotenv
-# .env.local
-HEARTH_SITE=<your-site>
-HEARTH_API_KEY=<a key from the site's Settings → Developers in Hearth>
+# .env.local (never committed)
+HEARTH_SITE=acme
+HEARTH_API_KEY=hk_…   # Hearth → the site → Settings → Developers → API keys
 ```
 
 ```ts
@@ -37,6 +40,18 @@ export const hearth = createHearthClient({
 });
 ```
 
+## With an AI coding assistant
+
+The package ships `llms.md`, a short reference written for coding agents: point yours at
+`node_modules/@the-smithy/hearth/llms.md`. Once the key is in `.env.local`, the full API guide can be saved for
+the agent too (sites made from the starter have `pnpm hearth:docs` for this):
+
+```sh
+curl -H "Authorization: Bearer $HEARTH_API_KEY" https://hearth.thesmithy.io/admin/docs/api.md -o hearth-api.md
+```
+
+Keep `hearth-api.md` out of git, and the key out of chat: the agent only needs it in `.env.local`.
+
 ## Documentation
 
 Once you have developer access, the full documentation (every method, Next.js helpers, rendering blocks,

package/llms.md

@@ -11,6 +11,21 @@ client components: the API key is secret.
   `export const hearth = createHearthClient({ site: process.env.HEARTH_SITE!, apiKey: process.env.HEARTH_API_KEY! })`
   `export const hearthNext = createHearthNext(hearth)` (from `@the-smithy/hearth/next`)
 
+## Working with the developer (read first)
+- Start by confirming the setup, and say what you found. In a site made from the starter: `pnpm hearth:check`
+  (connection, published pages, block types in use and any without a component). Elsewhere: call
+  `hearth.site.get()` and `hearth.pages.list()` from a server-side script.
+- Full guide (every block's fields, events, forms, previews, SEO): `pnpm hearth:docs` in the starter, or
+  `GET https://hearth.thesmithy.io/admin/docs/api.md` with `Authorization: Bearer $HEARTH_API_KEY`. Save it to
+  a gitignored file and read the parts you need.
+- Never print, log or commit the API key, and don't ask the developer to paste it into chat. Read it only from
+  env. If it's missing or rejected (`HearthError` code `unauthorized`), ask them to create one in Hearth → the
+  site → Settings → Developers → API keys and put it in `.env.local`.
+- Only published content comes back. A new site whose pages are drafts returns no pages, so every route 404s:
+  that's expected. Tell the developer to publish in Hearth; never add placeholder content to the code.
+- Content (text, menus, contact details, SEO) is edited in Hearth. The code owns design: tokens, layout and one
+  component per block type.
+
 ## Client (`@the-smithy/hearth`)
 - `site.get(): Site`
 - `pages.list(): PageSummary[]`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-smithy/hearth",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Typed client for the Hearth Delivery API: content, SEO, forms and publish webhooks.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -45,7 +45,7 @@
     "llms.md"
   ],
   "dependencies": {
-    "@the-smithy/hearth-schema": "^0.13.0"
+    "@the-smithy/hearth-schema": "^0.13.1"
   },
   "peerDependencies": {
     "next": ">=15",