@stack-mode/site-manager-kit 1.44.0 → 1.44.1

package/README.md

@@ -1,606 +1,606 @@
-# site-manager-kit
-
-Reads a website's content from Site Manager and gives a Next.js App Router site its metadata, sitemap, robots rules, redirects, form handling and content refreshes in a few lines. For sites hosted on Vercel. It ships TypeScript source with no build step, and its only runtime dependencies are `next`, `react` and `botid`.
-
-## Connect a website
-
-For a Next.js App Router website (Next 16) hosted on Vercel. Follow the steps in order. This is the same guide as `docs/CONNECT_A_SITE.md` in Site Manager; change both together.
-
-### Before you start
-
-In Site Manager, an agency admin sets up the site with **Sites > New Site** (the setup wizard). On its **Website Connection** step:
-
-1. Press **Create Key and Show Env Vars** and copy the block. The API key is shown once.
-2. Keep the page open. You'll come back to press **Check Connection**.
-
-The website needs Node 22 or later.
-
-### 1. Install the kit
-
-```bash
-npm i site-manager-kit@npm:@stack-mode/site-manager-kit botid --save-exact
-```
-
-The kit is published on npm as `@stack-mode/site-manager-kit` and installed under the name `site-manager-kit`, so imports, `transpilePackages` and the `npx site-manager-kit` command all use the short name. `--save-exact` pins the version, so a new kit release never changes a live site by itself. No token or GitHub access is needed, on your machine, on Vercel or in CI.
-
-`next.config.ts`:
-
-```ts
-import type { NextConfig } from "next";
-import { withBotId } from "botid/next/config";
-import { withSiteManager } from "site-manager-kit/config";
-
-const nextConfig: NextConfig = { transpilePackages: ["site-manager-kit"] };
-
-export default withBotId(withSiteManager(nextConfig));
-```
-
-The kit ships TypeScript source, so `transpilePackages` is required. To upgrade later, run the install line again (it pins the newest version), or change the version after `@stack-mode/site-manager-kit@` in `package.json` and run `npm install`.
-
-`withSiteManager` gives every page the same baseline security headers (`nosniff`, a strict referrer policy, `X-Frame-Options: SAMEORIGIN`, HSTS and a Permissions-Policy that turns off camera, microphone and USB), stops sending `X-Powered-By`, and lets `next/image` resize Site Manager's media. Payment and location stay on, so checkout buttons and "near me" maps keep working. Options: `withSiteManager(nextConfig, { disableFeatures: ["camera", "microphone", "usb", "geolocation"], hstsSubdomains: false, frameOptions: "DENY" })`. A Content-Security-Policy stays the site's own, because every site loads different services; if it sends one, allow `https://app.mystackos.com` in `script-src` and `connect-src` for visitor tracking.
-
-Cache Components can be on or off (new apps from `create-next-app` 16.4 turn it on). Either way, pages that only read Site Manager content are built once and refreshed when content changes, and a form page renders only its timing token per visit.
-
-### 2. Env vars
-
-Paste the block from the wizard into the website's Vercel project (Production and Preview) and into `.env.local` for local work. All five are server only; never prefix them with `NEXT_PUBLIC_`.
-
-| Name | What it is |
-|---|---|
-| `BLUEPRINT_URL` | Site Manager's address, for example `https://manager.example.com` |
-| `BLUEPRINT_API_KEY` | The site's API key |
-| `BLUEPRINT_SITE_ID` | The site's id |
-| `BLUEPRINT_REVALIDATE_SECRET` | The website connection secret |
-| `BLUEPRINT_FORM_SECRET` | A random secret for form timing tokens |
-
-Add `.env.local` to `.gitignore` if it isn't already.
-
-Working against a Site Manager running on your own machine? Set `BLUEPRINT_URL=http://localhost:3000`. Node can't resolve `*.localhost` names the way browsers do, and the key alone says which site it is.
-
-### 3. Refresh and health routes
-
-`app/api/blueprint/revalidate/route.ts`:
-
-```ts
-export { POST } from "site-manager-kit/revalidate-route";
-```
-
-`app/api/blueprint/health/route.ts`:
-
-```ts
-export { GET } from "site-manager-kit/health-route";
-```
-
-Then, in the wizard's **Branding** or **StackOS** step (or the site's Connection tab), set the **Website revalidate address** to `https://<the website>/api/blueprint/revalidate`.
-
-`app/api/blueprint/preview/route.ts`, so editors can see drafts and scheduled changes on the real site before they go live:
-
-```ts
-export { GET } from "site-manager-kit/preview-route";
-```
-
-And once inside `<body>` in `app/layout.tsx`, the bar that says a preview is open, with a way out:
-
-```tsx
-import { PreviewBanner } from "site-manager-kit/preview-banner";
-// ...
-<PreviewBanner />
-```
-
-Site Manager's **Preview on Website** button opens `/api/blueprint/preview?token=...`, signed with the same `BLUEPRINT_REVALIDATE_SECRET`, so there is nothing new to set up. The route turns on Next.js draft mode for that browser only and opens the page. While it's on, every read skips the cache and includes drafts; everyone else keeps seeing the published site. Links last an hour, and the preview ends when the browser closes or on **Exit preview**.
-
-#### Visual Editor
-
-Site Manager's **Visual Editor** shows a page of the website with its text outlined, so people can click a value and change it. Changes are saved as drafts in Site Manager; the website's code and layout never change. It needs the preview route above, plus two lines.
-
-Once inside `<body>` in `app/layout.tsx`, next to `PreviewBanner`:
-
-```tsx
-import { Suspense } from "react";
-import { VisualEditing } from "site-manager-kit/visual-editing";
-// ...
-<Suspense fallback={null}>
-  <VisualEditing />
-</Suspense>
-```
-
-In `src/proxy.ts`, so the page can be shown inside Site Manager while the editor is open (see step 4 for the rest of the file):
-
-```ts
-import { visualFrameHeaders } from "site-manager-kit/visual";
-
-export async function proxy(request: NextRequest) {
-  return visualFrameHeaders(request, (await handleRedirect(request)) ?? NextResponse.next());
-}
-```
-
-That's all a site needs. The editor finds the site's Site Copy on the page by its words: an element whose words are exactly one value is outlined, and so is a bare run of text beside other elements (a heading's words before its accent span). Only values for the page being shown (their page in Site Copy) and values with no page (header, footer) count. Words that two values on the same page share are left unmarked, since there is no telling which one they are, and so are values shorter than three characters. Those stay editable in Site Copy.
-
-A site's `next.config` Content-Security-Policy keeps working: `withSiteManager` sends it without its `frame-ancestors` only to a browser that opened the page from the Visual Editor, and `visualFrameHeaders` then allows that one Site Manager address. `X-Frame-Options` stays on every response. A site that builds its policy in the proxy instead uses `frameAncestors(request)` for its `frame-ancestors` value.
-
-To mark a value by hand (a value the words can't find, or to be exact), use `editMarks()`. A hand mark always wins over a found one:
-
-```tsx
-import { editMarks } from "site-manager-kit/visual";
-
-const mark = await editMarks();
-<h1 {...mark("copy/hero_title")}>{title}</h1>
-```
-
-A ref is `copy/<copy key>`. Marks, the editor script and the frame permission exist only for a browser that opened the page from the Visual Editor (a signed link that lasts an hour); visitors get none of them and the site keeps `X-Frame-Options: SAMEORIGIN`. An element with only text in it is edited in place; anything else, and a run of text beside other elements, opens a side panel in Site Manager. In visual mode, `getCopy()` (and the helpers built on it) adds an invisible tag to each text and rich value, which the editor reads and removes, so a value is found exactly wherever it shows. Code that compares or slices Site Copy text should use `getCopyUntagged()` for that, or compare after `stripTags()` from `site-manager-kit/visual-tags`. A site that marks every value itself can turn the word matching off with `<VisualEditing autoMark={false} />`. While a plain text value is open in the side panel, the page shows the words as they're typed (unsaved, only in that browser); rich text changes on save.
-
-A value that comes from another section of Site Manager (a floor plan's name, the phone number, an FAQ answer) is marked `link/<section key>`, for example `mark("link/floor_plans")`. Clicking it in the Visual Editor offers a link to that section instead of an edit.
-
-#### Copy keys
-
-Declare every piece of text and every photo the site is built with in `src/copy-keys.ts`, with its starting text, and read it through those names so a key is never typed twice:
-
-```ts
-import { defineCopyKeys } from "site-manager-kit/copy-keys";
-
-export const COPY = defineCopyKeys({
-  "home.hero.title": { label: "Home page headline", kind: "text", maxLength: 80, text: "Welcome home" },
-  "home.intro": { label: "Home page introduction", kind: "rich", text: "<p>Our story...</p>" },
-  "home.hero.photo": { label: "Home page photo", kind: "image", image: "/images/hero.jpg", alt: "The pool at dusk" },
-});
-```
-
-Keys are lowercase letters and numbers separated by dots, dashes or underscores; labels are written for the client, since they see them in Site Manager. An image is a path to a file in `public/`. A bad key fails the build.
-
-Serve them to Site Manager in `app/api/blueprint/copy-keys/route.ts`, signed like the health route:
-
-```ts
-import { copyKeysRoute } from "site-manager-kit/copy-keys-route";
-import { COPY } from "@/copy-keys";
-
-export const GET = copyKeysRoute(COPY);
-```
-
-Name keys by where they sit on the page, so Site Manager's Pages shows them in named sections and item cards: `<page>.<section>.<field>`, and `<page>.<section>.<list>.<n>.<field>` for repeating items, `n` counting from 1 (`home.process.steps.2.title`). Pages names a section from its own `label`, `eyebrow`, `title` or `heading` text and an item from its `title`, `label` or `name`, so give them one where it fits.
-
-A list whose items people may move, add or remove takes a rule in the second argument (1.26.0). `addRemove` also allows reordering, and works on the item slots you declare, so declare as many as the page has room for and show only items with something in them. Leave out any list where something about an item stays in code by position, like an icon:
-
-```ts
-export const COPY = defineCopyKeys(
-  {
-    "home.process.steps.1.title": { label: "Home page, process, step, title", kind: "text", text: "Call us" },
-    "home.process.steps.2.title": { label: "Home page, process, step, title", kind: "text", text: "" },
-  },
-  { lists: { "home.process.steps": { addRemove: true } } },
-);
-```
-
-In Site Manager, **Site Copy > Sync from Website** creates the declared keys with their starting text, updates labels and limits, and fills empty values. It never overwrites text someone changed and never deletes a key. After launch, the starting text is only used for new or empty keys.
-
-### 4. Sitemap, robots and redirects
-
-`app/sitemap.ts`:
-
-```ts
-import { sitemap } from "site-manager-kit";
-
-export default function Sitemap() {
-  return sitemap();
-}
-```
-
-`app/robots.ts`:
-
-```ts
-import { robots } from "site-manager-kit";
-
-export default function Robots() {
-  return robots();
-}
-```
-
-`src/proxy.ts` (or `proxy.ts` at the root when there's no `src` folder):
-
-```ts
-import { NextResponse, type NextRequest } from "next/server";
-import { handleRedirect } from "site-manager-kit/redirects";
-
-export async function proxy(request: NextRequest) {
-  return (await handleRedirect(request)) ?? NextResponse.next();
-}
-
-export const config = { matcher: ["/((?!_next|api|favicon.ico).*)"] };
-```
-
-Robots disallows everything until the site goes live in the wizard, so a site under construction never gets indexed.
-
-### 5. Metadata on every page
-
-```ts
-import { pageMetadata } from "site-manager-kit";
-
-export const generateMetadata = () => pageMetadata("/floor-plans");
-```
-
-For a detail page, build the path from the params:
-
-```ts
-export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
-  const { slug } = await params;
-  return pageMetadata(`/floor-plans/${slug}`);
-}
-```
-
-Each path must match the page's address on the live site, because that is the key Search Listings uses.
-
-### Missing pages and IndexNow
-
-Report visits to addresses the site doesn't have, so Site Manager can list them under Redirects, Not Found:
-
-```tsx
-// app/api/not-found/route.ts
-export { notFoundRoute as POST } from "site-manager-kit/not-found";
-
-// app/not-found.tsx, anywhere in the page
-import { NotFoundReporter } from "site-manager-kit/not-found-reporter";
-<NotFoundReporter />
-```
-
-Serve the IndexNow key from `src/proxy.ts`, before redirects: `const key = await handleIndexNow(request); if (key) return key;` (import from `site-manager-kit/indexnow`). It answers only `/{key}.txt` for Site Manager's key.
-
-### Structured data
-
-Search engines read a summary of the business from every page. Build it from the site you already fetched and write it with `<StructuredData />` in the root layout; record pages add their own type and breadcrumbs:
-
-```tsx
-import { StructuredData, businessJsonLd, breadcrumbJsonLd, breadcrumbsFor, eventJsonLd } from "site-manager-kit";
-
-// app/layout.tsx
-<StructuredData blocks={[businessJsonLd(site)]} />
-
-// app/events/[slug]/page.tsx
-const url = `${site.websiteUrl}/events/${event.slug}`;
-<StructuredData blocks={[eventJsonLd(event, site, url), breadcrumbJsonLd(breadcrumbsFor(`/events/${event.slug}`, site.websiteUrl!, { "/events": "Events", [`/events/${event.slug}`]: event.title }))]} />
-```
-
-`listingJsonLd` and `floorPlanJsonLd` work the same way. Empty facts are left out. Search Listings' structured data check reads the result.
-
-### 6. Content
-
-Replace hardcoded content with kit reads, one page at a time. Keep the design exactly as it is; only where the text and numbers come from changes.
-
-```tsx
-import { copyText, formatMoney, getFloorPlans, getSite } from "site-manager-kit";
-
-export default async function Home() {
-  const [site, plans] = await Promise.all([getSite(), getFloorPlans()]);
-  return (
-    <>
-      <h1>{await copyText("home.hero.title", site?.business.displayName)}</h1>
-      {plans.map((p) => (
-        <p key={p.slug}>
-          {p.name} from {formatMoney(p.startingRent) ?? "Call for pricing"}
-        </p>
-      ))}
-    </>
-  );
-}
-```
-
-Images from Site Manager come with their size and alt text. Show them with `next/image`, which serves resized, modern versions:
-
-```tsx
-import Image from "next/image";
-import { imageProps } from "site-manager-kit";
-
-const img = imageProps(plan.image);
-{img ? <Image {...img} sizes="(min-width: 768px) 50vw, 100vw" /> : null}
-```
-
-Without a known size, `imageProps` uses `fill`, so the image needs a sized box with `position: relative`.
-
-Visitor tracking: add `<SiteAnalytics />` once inside `<body>` in `app/layout.tsx`. It adds StackOS's tracking script with the key the agency sets on the site's Connection tab, and adds nothing while there's no key.
-
-```tsx
-import { SiteAnalytics } from "site-manager-kit/analytics";
-import { SiteAttribution } from "site-manager-kit/attribution";
-
-<body>
-  {children}
-  <SiteAnalytics />
-  <SiteAttribution />
-</body>
-```
-
-Where leads came from: `<SiteAttribution />` remembers the visitor's first `utm_` values, landing page and referring site for the browser tab (session storage, no cookie, so no consent banner), and `FormGuard` sends them with every form. Leads then show under their source in Site Manager (Leads > Leads by Source). Links made with Link Tools carry the `utm_` values.
-
-
-The full list of reads is in the kit README. Rules that matter:
-
-- Money is a decimal string like `"1450.00"`. Show it with `formatMoney`, never `Number()`.
-- Show availability with `availabilityText(plan)`, which follows the site's setting in Site Manager: "Available now" by default, the exact count only when the site chose it, and nothing when it's unknown. Don't print `availableCount` yourself; it's kept for older sites and is `null` when availability is unknown, never 0.
-- A plan with a running special has `concession.effectiveRent`. Show it next to the regular rent, never instead of it: `effectiveRentText(plan)` gives "$2,207.12 effective".
-- To compare plans side by side, `comparisonRows(plans)` gives one row per fact (bedrooms, size, rent, layout, availability) and per feature, ready for a table.
-- A section that is turned off for the site answers with `BlueprintError` code `module_off`. Only read sections the site has on.
-
-### 7. Forms
-
-A form is a small client component, so it can show the result, plus a server page that hands it `FormGuard` (the guard signs its render time on the server).
-
-`app/contact/ContactForm.tsx`:
-
-```tsx
-"use client";
-
-import { useActionState, type ReactNode } from "react";
-import { formAction } from "site-manager-kit/forms";
-
-export function ContactForm({ guard }: { guard: ReactNode }) {
-  const [state, action, pending] = useActionState(formAction.bind(null, "inquiry"), null);
-  if (state?.ok) return <p>{state.successMessage}</p>;
-  return (
-    <form action={action}>
-      <input name="name" required />
-      <input name="email" type="email" required />
-      <textarea name="message" />
-      {guard}
-      {state && !state.ok ? <p>{state.error === "invalid" ? "Check the highlighted fields." : "That didn't send. Try again in a moment."}</p> : null}
-      <button disabled={pending}>Send</button>
-    </form>
-  );
-}
-```
-
-`app/contact/page.tsx`:
-
-```tsx
-import { FormGuard } from "site-manager-kit/form-guard";
-import { ContactForm } from "./ContactForm";
-
-export default function Contact() {
-  return <ContactForm guard={<FormGuard />} />;
-}
-```
-
-The field names must match the form's fields in Site Manager (Forms > the form). For phone fields use `<PhoneInput name="phone" />` from `site-manager-kit/phone`: it formats as the visitor types, (555) 123-4567, the format Site Manager checks and stores. A field's `help` (from `getForm`) is a short line to show under it. `state.error` is `invalid` (with `state.fields` naming each field's problem), `rate_limited`, `slot_taken` (booking forms) or `unavailable`. Suspected spam answers like a normal submission and lands in Site Manager's spam folder. Don't pass `submitForm` straight to `<form action>`: it returns a result, which a plain form action can't. A form with its own signed timer, or a send with no form (a remembered visitor's one-click download), passes `submitForm(key, data, { timedBySite: true })` after the site's own checks: the FormGuard timer is skipped, the honeypot and BotID still apply.
-
-#### Booking forms
-
-A form whose kind is Booking (set by the agency in Site Manager) also needs one of the site's open times, set under Forms > Booking Times. Read them with `getBookingSlots` (never cached, since every booking changes them) and send the chosen `start` as the `bp_slot` field:
-
-```tsx
-// app/tour/page.tsx
-import { Suspense } from "react";
-import { connection } from "next/server";
-import { getBookingSlots } from "site-manager-kit";
-import { FormGuard } from "site-manager-kit/form-guard";
-import { TourForm } from "./TourForm";
-
-export default function Tour() {
-  // With Cache Components on, only the open times render per visit; the rest of the page stays static.
-  return (
-    <Suspense fallback={<p>Finding open times...</p>}>
-      <Times />
-    </Suspense>
-  );
-}
-
-async function Times() {
-  await connection();
-  const slots = await getBookingSlots("tour", { days: 14 });
-  return <TourForm days={slots?.days ?? []} guard={<FormGuard />} />;
-}
-```
-
-```tsx
-// app/tour/TourForm.tsx, inside the <form> from the contact example
-{days.map((d) => (
-  <fieldset key={d.date}>
-    <legend>{d.date}</legend>
-    {d.slots.map((s) => (
-      <label key={s.start}>
-        <input type="radio" name="bp_slot" value={s.start} required /> {s.label}
-      </label>
-    ))}
-  </fieldset>
-))}
-```
-
-`state.error` can also be `slot_taken` when someone booked that time a moment earlier: show the times again. Times are in the site's time zone (`slots.timezone`), and a day with no open times has an empty `slots` list.
-
-Protect each page that posts a form with BotID, in `instrumentation-client.ts`. It goes in `src/` when the app has a `src` folder, and at the project root otherwise; in the wrong place it's silently ignored and BotID warns about a misconfiguration:
-
-```ts
-import { initBotId } from "botid/client/core";
-
-initBotId({ protect: [{ path: "/contact", method: "POST" }] });
-```
-
-### Waitlist (apartment sites)
-
-With the Waitlist section on in Site Manager, visitors can ask to hear when a floor plan, or any plan with their bedroom count, has a home available. Site Manager emails them once when it opens, with a link to leave the list. The form uses `FormGuard` and the same spam checks as other forms.
-
-On a plan page, send the plan's slug in a hidden field. A general form can offer one picker from `waitlistChoices(await getWaitlistOptions())`, which lists each bedroom count and the plans with nothing open now.
-
-```tsx
-"use client";
-
-import { useActionState, type ReactNode } from "react";
-import { waitlistAction } from "site-manager-kit/waitlist";
-
-export function WaitlistForm({ plan, guard }: { plan: string; guard: ReactNode }) {
-  const [state, action, pending] = useActionState(waitlistAction, null);
-  if (state?.ok) return <p>You're on the list. We'll email you when one opens.</p>;
-  return (
-    <form action={action}>
-      <input type="hidden" name="floorPlan" value={plan} />
-      <input name="email" type="email" required />
-      <input name="moveIn" type="date" />
-      {guard}
-      <button disabled={pending}>Notify Me</button>
-    </form>
-  );
-}
-```
-
-Fields: `floorPlan` (a slug) or `bedrooms` (a number), or one `choice` (`plan:<slug>` or `beds:<n>`), plus `email`, and optionally `name`, `phone` and `moveIn` (`YYYY-MM-DD`). `state.error` is `invalid` with `fields`, `rate_limited` or `unavailable`. Add the page to BotID's `protect` list like any form page.
-
-### Website chat
-
-With Website Chat on and live in Site Manager (kit 1.25.0), a chat button shows on every page. It answers visitors only from the site's published content in Site Manager, says when it doesn't know and gives the contact details, and turns visitors who want a tour, a quote or a call back into leads with the conversation attached. It runs on the site's own AI key, set in Site Manager.
-
-Add the route the chat talks to. It keeps the API key on the server, sends Site Manager only a hash of the visitor's address, and refuses requests that don't come from the website's own pages:
-
-```ts
-// app/api/blueprint/chat/route.ts
-export { GET, POST } from "site-manager-kit/chat-route";
-```
-
-Then put the component once inside `<body>` in `app/layout.tsx`. It renders nothing until the chat is live, and nothing when Website Chat is off for the site:
-
-```tsx
-import { SiteChat } from "site-manager-kit/chat";
-
-<SiteChat />
-```
-
-It takes the site's accent from Site Manager and follows the visitor's light or dark setting. Props, all optional: `accent` (a CSS color), `theme` (`"auto"`, `"light"` or `"dark"`), `position` (`"right"` or `"left"`), `offset` (pixels to raise it above a cookie bar) and `endpoint` (when the route lives somewhere else). Text on the accent switches between dark and white so a light accent stays readable.
-
-- Replies stream in as they're written. The conversation follows the visitor from page to page in the same tab, and a random visitor id in the browser's storage is the only thing kept there; Site Manager stores only its hash.
-- When a visitor wants a person, the chat offers a short form (name, email or phone, message). With Booking Times on and a booking form chosen in Site Manager, it offers open times and books one. Leads arrive like form submissions, with the source "Website chat".
-- Add the route to BotID's `protect` list to check for bots before Site Manager is asked: `{ path: "/api/blueprint/chat", method: "POST" }`. Site Manager limits each visitor and the site either way.
-- `getChatConfig()` (from `site-manager-kit/chat`) reads the settings if the site builds its own chat. The route's answers are NDJSON lines: `start` with the conversation id, `delta` with text, and `done` saying whether it couldn't answer and whether to offer a hand-off (`parseChatLines` reads them).
-
-### 8. Caching
-
-- Every kit read is cached for an hour and refreshed the moment content changes in Site Manager, through the revalidate route. Don't add your own `revalidate` or `cache: "no-store"` around kit reads.
-- A refresh never makes a visitor wait: the first visit after a change gets the page as it was and rebuilds it in the background, and the next visit shows the change. Site Manager refreshes only the sections a change affects.
-- Pages that only use kit reads can stay static. Don't call `cookies()` or `headers()` on them unless the page needs it.
-- Redirects are cached for 5 minutes in the proxy and cleared when they change.
-- After a deploy, the first visit to each page fills the cache. Nothing needs warming.
-- Pages are prerendered from Site Manager at build time, so a build needs Site Manager to be reachable. If a build fails with `fetch failed`, check `BLUEPRINT_URL`.
-- A page with a form renders on each request (`FormGuard` does this), so its timing check always has a fresh render time.
-
-### 9. Check it
-
-1. `npm run build` passes.
-2. Deploy (or run `npm run dev` with the env vars) and open the site. Content shows, and `/sitemap.xml` and `/robots.txt` load.
-3. In the wizard, press **Check Connection**. Both "connected" and "bot protection, honeypot and timing checks are on" must show.
-4. Change a piece of site copy in Site Manager and reload the page: the new text shows within a few seconds.
-5. Send a test form from a Link Tools link and confirm it arrives in Leads under that link's source.
-
-### 10. Wiring audit
-
-Run it after a new build, after adding or changing a page or section, and before Go live:
-
-```bash
-npx site-manager-kit audit
-```
-
-It reads `BLUEPRINT_URL` and `BLUEPRINT_API_KEY` from `.env.local` (or `--env <file>`; use the production values, it only reads), loads `src/copy-keys.ts` (`--keys <file>` for another), and writes `.wiring/report.md`. Every item is one of:
-
-- **Wired**: the site reads it from Site Manager.
-- **Not wired**: Site Manager has it, but editing it changes nothing on the website (a key the site never asks for, a section that's on but never read, a Business Info field the code ignores). Fails the audit.
-- **Missing in Site Manager**: the site uses it, but Site Manager has no such field (a key not synced yet, a form key with no form). Fails the audit.
-- **Hard-coded**: the code keeps its own copy of a Site Manager value, with file and line. Reported, never failing, since a fallback can be on purpose.
-- **Unknown**: the audit couldn't tell (the copy keys file didn't load, a section it doesn't know yet).
-
-Exit codes: 0 wired, 1 something Not wired or missing, 2 it couldn't run. Folders it shouldn't scan (an old admin, scripts) go in `package.json`:
-
-```json
-"siteManagerAudit": { "ignore": ["src/admin"], "keysFile": "src/copy-keys.ts" }
-```
-
-**Upload the result** so Site Manager shows it (the site's Wiring tab, the wiring score on Overview, and the Portfolio column):
-
-```bash
-npx site-manager-kit audit --upload
-```
-
-It needs a **Wiring audit** key from the site's API Keys tab, in `BLUEPRINT_AUDIT_KEY` (beside the website's own key, never in place of it). An audit key reads content and uploads results, and can't send forms or anything else, so it's the one to keep on a developer's computer or as a CI secret. When it's set, the audit reads with it too. A failed upload exits 2.
-
-**Deploys**: the health route sends `deployId` (`VERCEL_DEPLOYMENT_ID`, else `VERCEL_GIT_COMMIT_SHA`), so Site Manager notices each deploy and runs its own website check the same day, flagging problems the deploy brought in.
-
-Site Manager's `docs/wiring.md` explains the whole process and how to fix each kind of gap.
-
-### Launch checklist
-
-- [ ] Every page reads its content and metadata from Site Manager, and the design is unchanged.
-- [ ] `sitemap.ts`, `robots.ts`, `proxy.ts`, and the revalidate and health routes are in place.
-- [ ] Every form uses `FormGuard`, and its page is protected in `instrumentation-client.ts`.
-- [ ] `<SiteAttribution />` is in the root layout, so leads record their source.
-- [ ] The five env vars are set in Vercel for Production and Preview.
-- [ ] System Status shows every check ok.
-- [ ] `npx site-manager-kit audit` reports nothing Not wired or missing in Site Manager.
-- [ ] Search Listings has every page with a target keyword, and the legal pages are published.
-- [ ] Go live in the wizard (this lets search engines in), then add the site to `docs/SITES.md`.
-
-### Blog
-
-With the Blog section on, a site reads posts, categories and tags. Set the Blog posts page pattern in Site Manager (Search Listings, page addresses) to match the site's route, for example `/blog/{slug}`, so each post gets its search listing, sitemap entry and `url`.
-
-```tsx
-import { blogPostingJsonLd, getPost, getPosts, pageMetadata } from "site-manager-kit";
-
-// app/blog/page.tsx
-const { posts, paging } = await getPosts({ page, perPage: 12 });
-
-// app/blog/[slug]/page.tsx
-export const generateMetadata = async ({ params }) => pageMetadata(`/blog/${(await params).slug}`);
-const post = await getPost(slug); // null: notFound()
-const ld = JSON.stringify(blogPostingJsonLd(post, { publisherName: site.business.displayName })).replace(/</g, "\\u003c");
-<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: ld }} />
-```
-
-RSS: `app/blog/rss.xml/route.ts` with
-
-```ts
-import { rssRoute } from "site-manager-kit/rss-route";
-export const GET = rssRoute();
-```
-
-Posts are in the sitemap already (Site Manager lists every published post's page). Category pages aren't pages in Site Manager; add them to `sitemap([...])` from `getBlogCategories()` if the site has them.
-
-## Reference: content reads
-
-Available: `getSite`, `getCopy`, `copyText`, `copyImage(key)` (a built-in photo from an image key), `getReviews({ featured, sort })`, `getFloorPlans`, `getFloorPlan(slug)` (with units), `getUnitMaps()` (site plan drawings with open units placed on them), `getAmenities({ category })`, `getFees` (with `requiredMonthlyTotal`), `getPetPolicy`, `getParking`, `getSpecials`, `getEvents({ from, limit })`, `getEvent(slug)`, `getServices({ category })`, `getService(slug)`, `getLocations`, `getNearbyPlaces({ category })` (with `walkMinutes`, `driveMinutes`, `transitMinutes` and `school`; `category: "commute"` for commute times), `getForm(key)`, `getBookingSlots(key, { from, days })` (never cached), `getLegal`, `getLegalDoc(slug)`, plus the real estate reads below. Each returns `null` (or an empty list) when there's nothing, and throws `BlueprintError` when Site Manager answers with an error, for example `module_off`.
-Available: `getSite`, `getCopy`, `copyText`, `getReviews({ featured, sort })`, `getFloorPlans`, `getFloorPlan(slug)` (with units), `getAmenities({ category })`, `getFees` (with `requiredMonthlyTotal`), `getPetPolicy`, `getParking`, `getPolicies` (leasing policies), `getResidentResources` (the residents page sections), `pickupText` and `leaseTermsText`, `getSpecials`, `getEvents({ from, limit })`, `getEvent(slug)`, `getLocations`, `getNearbyPlaces({ category })` (with `walkMinutes`, `driveMinutes`, `transitMinutes` and `school`; `category: "commute"` for commute times), `getForm(key)`, `getBookingSlots(key, { from, days })` (never cached), `getLegal`, `getLegalDoc(slug)`, plus the real estate reads below. Each returns `null` (or an empty list) when there's nothing, and throws `BlueprintError` when Site Manager answers with an error, for example `module_off`.
-Available: `getSite`, `getCopy`, `copyText`, `getReviews({ featured, sort })`, `getFloorPlans`, `getFloorPlan(slug)` (with units), `getAmenities({ category })`, `getFees` (with `requiredMonthlyTotal`), `getPetPolicy`, `getParking`, `getSpecials`, `getEvents({ from, limit })`, `getEvent(slug)`, `getLocations`, `getNearbyPlaces({ category })` (with `walkMinutes`, `driveMinutes`, `transitMinutes` and `school`; `category: "commute"` for commute times), `getForm(key)`, `getBookingSlots(key, { from, days })` (never cached), `getLegal`, `getLegalDoc(slug)`, `getFaq`, `getFaqSet(key)`, `getAnnouncements`, `getDownloads`, plus the real estate reads below. Each returns `null` (or an empty list) when there's nothing, and throws `BlueprintError` when Site Manager answers with an error, for example `module_off`.
-Available: `getSite`, `getCopy`, `copyText`, `getReviews({ featured })`, `getFloorPlans`, `getFloorPlan(slug)` (with units), `getAmenities({ category })`, `getFees` (with `requiredMonthlyTotal`), `getPetPolicy`, `getParking`, `getSpecials`, `getEvents({ from, limit })`, `getEvent(slug)`, `getLocations`, `getNearbyPlaces({ category })` (with `walkMinutes`, `driveMinutes` and `school`), `getForm(key)`, `getBookingSlots(key, { from, days })` (never cached), `getLegal`, `getLegalDoc(slug)`, `getPosts({ page, perPage, category, tag })`, `getPost(slug)`, `getBlogCategories`, `getBlogCategory(slug, { page, perPage })`, `getBlogTags`, `getBlogFeed({ limit })`. Each returns `null` (or an empty list) when there's nothing, and throws `BlueprintError` when Site Manager answers with an error, for example `module_off`.
-
-Money is always a decimal string like `"1450.00"`. Format it with `formatMoney`, never `Number()`.
-
-`availableCount` is `null` when a floor plan lists no units: availability is unknown, not zero. Prefer `availability` (`{ status, count }`, with `count` only when the site shows exact numbers) through `availabilityText`.
-
-Floor plan helpers: `availabilityText(plan, labels?)`, `effectiveRentText(plan)` and `comparisonRows(plans)`.
-
-Real estate reads (1.6.0; listing details and past sales from 1.8.0; open houses and the agent filter from 1.10.0): `getListings({ status, minPrice, maxPrice, beds, type, featured, agent, area, limit })` (active first, each with `featuredImage`, `imageCount`, `badge`, `pricePerSqft` and its `agent`), `getListing(slug)` (adds `images`, `features`, `schools`, `history` and `transactions`: past sales, newest first, with buyer and seller only when the agent shows them), `getTeam`, `getTeamMember(slug)` and `getPaymentDefaults`. `status` takes one status or a list (`coming_soon`, `active`, `pending`, `sold`); off market listings never come back. Prices filter on the sold price for sold listings. Listings also carry `daysOnMarket`, `interior`, `exterior`, `lotDetails`, `parking`, `utilities`, `hoaName`, `hoaIncludes`, `taxes` and `openHouses` (upcoming only, each with a ready `label`); empty lists and nulls mean not known. `agent` takes a team member's short name, for an agent page with their listings. `getSoldListings({ area, agent, limit })` lists sold homes (each with `soldPrice` and `soldOn`) for a sold portfolio.
-
-Area guides (1.17.0): `getAreas()` and `getArea(slug)` return each area's `descriptionHtml`, `photos`, `highlights`, `schools` and `listingCount`; `getListings({ area: slug })` gives the homes in it. A listing is in an area when its neighborhood matches the area's name or one of its `otherNames`, ignoring case.
-Waitlist (1.18.0): `getWaitlistOptions()` (the plans, with whether each has a home open, and the bedroom counts), `waitlistChoices(options)` and `readWaitlistForm(formData)`; the form action is `waitlistAction` from `site-manager-kit/waitlist`.
-
-Real estate reads (1.6.0; listing details and past sales from 1.8.0; open houses and the agent filter from 1.10.0): `getListings({ status, minPrice, maxPrice, beds, type, featured, agent, limit })` (active first, each with `featuredImage`, `imageCount`, `badge`, `pricePerSqft` and its `agent`), `getListing(slug)` (adds `images`, `features`, `schools`, `history` and `transactions`: past sales, newest first, with buyer and seller only when the agent shows them), `getTeam`, `getTeamMember(slug)` and `getPaymentDefaults`. `status` takes one status or a list (`coming_soon`, `active`, `pending`, `sold`); off market listings never come back. Prices filter on the sold price for sold listings. Listings also carry `daysOnMarket`, `interior`, `exterior`, `lotDetails`, `parking`, `utilities`, `hoaName`, `hoaIncludes`, `taxes` and `openHouses` (upcoming only, each with a ready `label`); empty lists and nulls mean not known. `agent` takes a team member's short name, for an agent page with their listings.
-
-Services (1.12.0): each has `price.kind` (`none`, `fixed`, `range`, `starting_at`, `call`), `price.from` and `price.to` as decimal strings, an optional `price.note` ("per hour") and `price.label`, ready-to-show text like "Starting at $150" (null when no price is shown). `serviceJsonLd(service, site, url)` returns schema.org `Service` structured data for the page; render it in a `<script type="application/ld+json">`.
-
-Listing helpers: `listingAddress(listing)`, `listingPrice(listing)` (the sold price once sold), `bathsText(baths)` ("3.0" becomes "3"), `lotText(lot)` ("1.02 acres"), `hoaText(hoa)` ("$85 per month") and `estimatePayment(price, defaults, hoa?)`. The estimate uses whole-cent integer math and returns `null` until the site sets a rate, down payment and term in Site Manager (Listings > Settings), so show nothing rather than a guess. Always label it as an estimate.
-
-```tsx
-const [listing, defaults] = await Promise.all([getListing(slug), getPaymentDefaults()]);
-const estimate = listing ? estimatePayment(listingPrice(listing), defaults, listing.hoa) : null;
-// estimate?.total is a decimal string: formatMoney(estimate.total)
-```
-
-FAQ, announcements and downloads (1.15.0), for any kind of site:
-
-- `getFaq({ category })` gives `{ categories, questions }`, questions in category order. `getFaqSet(key)` gives one named set a page asks for (like `"leasing-page"`), its questions in the set's order, or `null` when there's no such set. Each question has `answerHtml` and `answerText`. `faqJsonLd(questions)` builds FAQPage structured data; render it with `jsonLdScript`, and only for the questions the page shows:
-
-  ```tsx
-  <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: jsonLdScript(faqJsonLd(set.questions)) }} />
-  ```
-
-- `getAnnouncements()` gives the notices live now, urgent first. It is never served before a start or past an end: the cached copy is used only until Site Manager's next start or end, then read fresh. Call it at request time, inside a Suspense boundary after `await connection()`, not in a prerendered shell. `announcementsLiveAt(list, now)` is the filter it uses.
-- `getDownloads({ category })` gives published files (`brochure`, `menu`, `application`, `price_sheet`, `other`). Link to each one's `url`: it goes through Site Manager, which counts the download and sends the file. `fileSizeText(bytes)` gives "2.4 MB".
-
-## Development
-
-```bash
-npm install
-npm test
-npm run typecheck
-```
+# site-manager-kit
+
+Reads a website's content from Site Manager and gives a Next.js App Router site its metadata, sitemap, robots rules, redirects, form handling and content refreshes in a few lines. For sites hosted on Vercel. It ships TypeScript source with no build step, and its only runtime dependencies are `next`, `react` and `botid`.
+
+## Connect a website
+
+For a Next.js App Router website (Next 16) hosted on Vercel. Follow the steps in order. This is the same guide as `docs/CONNECT_A_SITE.md` in Site Manager; change both together.
+
+### Before you start
+
+In Site Manager, an agency admin sets up the site with **Sites > New Site** (the setup wizard). On its **Website Connection** step:
+
+1. Press **Create Key and Show Env Vars** and copy the block. The API key is shown once.
+2. Keep the page open. You'll come back to press **Check Connection**.
+
+The website needs Node 22 or later.
+
+### 1. Install the kit
+
+```bash
+npm i site-manager-kit@npm:@stack-mode/site-manager-kit botid --save-exact
+```
+
+The kit is published on npm as `@stack-mode/site-manager-kit` and installed under the name `site-manager-kit`, so imports, `transpilePackages` and the `npx site-manager-kit` command all use the short name. `--save-exact` pins the version, so a new kit release never changes a live site by itself. No token or GitHub access is needed, on your machine, on Vercel or in CI.
+
+`next.config.ts`:
+
+```ts
+import type { NextConfig } from "next";
+import { withBotId } from "botid/next/config";
+import { withSiteManager } from "site-manager-kit/config";
+
+const nextConfig: NextConfig = { transpilePackages: ["site-manager-kit"] };
+
+export default withBotId(withSiteManager(nextConfig));
+```
+
+The kit ships TypeScript source, so `transpilePackages` is required. To upgrade later, run the install line again (it pins the newest version), or change the version after `@stack-mode/site-manager-kit@` in `package.json` and run `npm install`.
+
+`withSiteManager` gives every page the same baseline security headers (`nosniff`, a strict referrer policy, `X-Frame-Options: SAMEORIGIN`, HSTS and a Permissions-Policy that turns off camera, microphone and USB), stops sending `X-Powered-By`, and lets `next/image` resize Site Manager's media. Payment and location stay on, so checkout buttons and "near me" maps keep working. Options: `withSiteManager(nextConfig, { disableFeatures: ["camera", "microphone", "usb", "geolocation"], hstsSubdomains: false, frameOptions: "DENY" })`. A Content-Security-Policy stays the site's own, because every site loads different services; if it sends one, allow `https://app.mystackos.com` in `script-src` and `connect-src` for visitor tracking.
+
+Cache Components can be on or off (new apps from `create-next-app` 16.4 turn it on). Either way, pages that only read Site Manager content are built once and refreshed when content changes, and a form page renders only its timing token per visit.
+
+### 2. Env vars
+
+Paste the block from the wizard into the website's Vercel project (Production and Preview) and into `.env.local` for local work. All five are server only; never prefix them with `NEXT_PUBLIC_`.
+
+| Name | What it is |
+|---|---|
+| `BLUEPRINT_URL` | Site Manager's address, for example `https://manager.example.com` |
+| `BLUEPRINT_API_KEY` | The site's API key |
+| `BLUEPRINT_SITE_ID` | The site's id |
+| `BLUEPRINT_REVALIDATE_SECRET` | The website connection secret |
+| `BLUEPRINT_FORM_SECRET` | A random secret for form timing tokens |
+
+Add `.env.local` to `.gitignore` if it isn't already.
+
+Working against a Site Manager running on your own machine? Set `BLUEPRINT_URL=http://localhost:3000`. Node can't resolve `*.localhost` names the way browsers do, and the key alone says which site it is.
+
+### 3. Refresh and health routes
+
+`app/api/blueprint/revalidate/route.ts`:
+
+```ts
+export { POST } from "site-manager-kit/revalidate-route";
+```
+
+`app/api/blueprint/health/route.ts`:
+
+```ts
+export { GET } from "site-manager-kit/health-route";
+```
+
+Then, in the wizard's **Branding** or **StackOS** step (or the site's Connection tab), set the **Website revalidate address** to `https://<the website>/api/blueprint/revalidate`.
+
+`app/api/blueprint/preview/route.ts`, so editors can see drafts and scheduled changes on the real site before they go live:
+
+```ts
+export { GET } from "site-manager-kit/preview-route";
+```
+
+And once inside `<body>` in `app/layout.tsx`, the bar that says a preview is open, with a way out:
+
+```tsx
+import { PreviewBanner } from "site-manager-kit/preview-banner";
+// ...
+<PreviewBanner />
+```
+
+Site Manager's **Preview on Website** button opens `/api/blueprint/preview?token=...`, signed with the same `BLUEPRINT_REVALIDATE_SECRET`, so there is nothing new to set up. The route turns on Next.js draft mode for that browser only and opens the page. While it's on, every read skips the cache and includes drafts; everyone else keeps seeing the published site. Links last an hour, and the preview ends when the browser closes or on **Exit preview**.
+
+#### Visual Editor
+
+Site Manager's **Visual Editor** shows a page of the website with its text outlined, so people can click a value and change it. Changes are saved as drafts in Site Manager; the website's code and layout never change. It needs the preview route above, plus two lines.
+
+Once inside `<body>` in `app/layout.tsx`, next to `PreviewBanner`:
+
+```tsx
+import { Suspense } from "react";
+import { VisualEditing } from "site-manager-kit/visual-editing";
+// ...
+<Suspense fallback={null}>
+  <VisualEditing />
+</Suspense>
+```
+
+In `src/proxy.ts`, so the page can be shown inside Site Manager while the editor is open (see step 4 for the rest of the file):
+
+```ts
+import { visualFrameHeaders } from "site-manager-kit/visual";
+
+export async function proxy(request: NextRequest) {
+  return visualFrameHeaders(request, (await handleRedirect(request)) ?? NextResponse.next());
+}
+```
+
+That's all a site needs. The editor finds the site's Site Copy on the page by its words: an element whose words are exactly one value is outlined, and so is a bare run of text beside other elements (a heading's words before its accent span). Only values for the page being shown (their page in Site Copy) and values with no page (header, footer) count. Words that two values on the same page share are left unmarked, since there is no telling which one they are, and so are values shorter than three characters. Those stay editable in Site Copy.
+
+A site's `next.config` Content-Security-Policy keeps working: `withSiteManager` sends it without its `frame-ancestors` only to a browser that opened the page from the Visual Editor, and `visualFrameHeaders` then allows that one Site Manager address. `X-Frame-Options` stays on every response. A site that builds its policy in the proxy instead uses `frameAncestors(request)` for its `frame-ancestors` value.
+
+To mark a value by hand (a value the words can't find, or to be exact), use `editMarks()`. A hand mark always wins over a found one:
+
+```tsx
+import { editMarks } from "site-manager-kit/visual";
+
+const mark = await editMarks();
+<h1 {...mark("copy/hero_title")}>{title}</h1>
+```
+
+A ref is `copy/<copy key>`. Marks, the editor script and the frame permission exist only for a browser that opened the page from the Visual Editor (a signed link that lasts an hour); visitors get none of them and the site keeps `X-Frame-Options: SAMEORIGIN`. An element with only text in it is edited in place; anything else, and a run of text beside other elements, opens a side panel in Site Manager. In visual mode, `getCopy()` (and the helpers built on it) adds an invisible tag to each text and rich value, which the editor reads and removes, so a value is found exactly wherever it shows. Code that compares or slices Site Copy text should use `getCopyUntagged()` for that, or compare after `stripTags()` from `site-manager-kit/visual-tags`. A site that marks every value itself can turn the word matching off with `<VisualEditing autoMark={false} />`. While a plain text value is open in the side panel, the page shows the words as they're typed (unsaved, only in that browser); rich text changes on save.
+
+A value that comes from another section of Site Manager (a floor plan's name, the phone number, an FAQ answer) is marked `link/<section key>`, for example `mark("link/floor_plans")`. Clicking it in the Visual Editor offers a link to that section instead of an edit.
+
+#### Copy keys
+
+Declare every piece of text and every photo the site is built with in `src/copy-keys.ts`, with its starting text, and read it through those names so a key is never typed twice:
+
+```ts
+import { defineCopyKeys } from "site-manager-kit/copy-keys";
+
+export const COPY = defineCopyKeys({
+  "home.hero.title": { label: "Home page headline", kind: "text", maxLength: 80, text: "Welcome home" },
+  "home.intro": { label: "Home page introduction", kind: "rich", text: "<p>Our story...</p>" },
+  "home.hero.photo": { label: "Home page photo", kind: "image", image: "/images/hero.jpg", alt: "The pool at dusk" },
+});
+```
+
+Keys are lowercase letters and numbers separated by dots, dashes or underscores; labels are written for the client, since they see them in Site Manager. An image is a path to a file in `public/`. A bad key fails the build.
+
+Serve them to Site Manager in `app/api/blueprint/copy-keys/route.ts`, signed like the health route:
+
+```ts
+import { copyKeysRoute } from "site-manager-kit/copy-keys-route";
+import { COPY } from "@/copy-keys";
+
+export const GET = copyKeysRoute(COPY);
+```
+
+Name keys by where they sit on the page, so Site Manager's Pages shows them in named sections and item cards: `<page>.<section>.<field>`, and `<page>.<section>.<list>.<n>.<field>` for repeating items, `n` counting from 1 (`home.process.steps.2.title`). Pages names a section from its own `label`, `eyebrow`, `title` or `heading` text and an item from its `title`, `label` or `name`, so give them one where it fits.
+
+A list whose items people may move, add or remove takes a rule in the second argument (1.26.0). `addRemove` also allows reordering, and works on the item slots you declare, so declare as many as the page has room for and show only items with something in them. Leave out any list where something about an item stays in code by position, like an icon:
+
+```ts
+export const COPY = defineCopyKeys(
+  {
+    "home.process.steps.1.title": { label: "Home page, process, step, title", kind: "text", text: "Call us" },
+    "home.process.steps.2.title": { label: "Home page, process, step, title", kind: "text", text: "" },
+  },
+  { lists: { "home.process.steps": { addRemove: true } } },
+);
+```
+
+In Site Manager, **Site Copy > Sync from Website** creates the declared keys with their starting text, updates labels and limits, and fills empty values. It never overwrites text someone changed and never deletes a key. After launch, the starting text is only used for new or empty keys.
+
+### 4. Sitemap, robots and redirects
+
+`app/sitemap.ts`:
+
+```ts
+import { sitemap } from "site-manager-kit";
+
+export default function Sitemap() {
+  return sitemap();
+}
+```
+
+`app/robots.ts`:
+
+```ts
+import { robots } from "site-manager-kit";
+
+export default function Robots() {
+  return robots();
+}
+```
+
+`src/proxy.ts` (or `proxy.ts` at the root when there's no `src` folder):
+
+```ts
+import { NextResponse, type NextRequest } from "next/server";
+import { handleRedirect } from "site-manager-kit/redirects";
+
+export async function proxy(request: NextRequest) {
+  return (await handleRedirect(request)) ?? NextResponse.next();
+}
+
+export const config = { matcher: ["/((?!_next|api|favicon.ico).*)"] };
+```
+
+Robots disallows everything until the site goes live in the wizard, so a site under construction never gets indexed.
+
+### 5. Metadata on every page
+
+```ts
+import { pageMetadata } from "site-manager-kit";
+
+export const generateMetadata = () => pageMetadata("/floor-plans");
+```
+
+For a detail page, build the path from the params:
+
+```ts
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  return pageMetadata(`/floor-plans/${slug}`);
+}
+```
+
+Each path must match the page's address on the live site, because that is the key Search Listings uses.
+
+### Missing pages and IndexNow
+
+Report visits to addresses the site doesn't have, so Site Manager can list them under Redirects, Not Found:
+
+```tsx
+// app/api/not-found/route.ts
+export { notFoundRoute as POST } from "site-manager-kit/not-found";
+
+// app/not-found.tsx, anywhere in the page
+import { NotFoundReporter } from "site-manager-kit/not-found-reporter";
+<NotFoundReporter />
+```
+
+Serve the IndexNow key from `src/proxy.ts`, before redirects: `const key = await handleIndexNow(request); if (key) return key;` (import from `site-manager-kit/indexnow`). It answers only `/{key}.txt` for Site Manager's key.
+
+### Structured data
+
+Search engines read a summary of the business from every page. Build it from the site you already fetched and write it with `<StructuredData />` in the root layout; record pages add their own type and breadcrumbs:
+
+```tsx
+import { StructuredData, businessJsonLd, breadcrumbJsonLd, breadcrumbsFor, eventJsonLd } from "site-manager-kit";
+
+// app/layout.tsx
+<StructuredData blocks={[businessJsonLd(site)]} />
+
+// app/events/[slug]/page.tsx
+const url = `${site.websiteUrl}/events/${event.slug}`;
+<StructuredData blocks={[eventJsonLd(event, site, url), breadcrumbJsonLd(breadcrumbsFor(`/events/${event.slug}`, site.websiteUrl!, { "/events": "Events", [`/events/${event.slug}`]: event.title }))]} />
+```
+
+`listingJsonLd` and `floorPlanJsonLd` work the same way. Empty facts are left out. Search Listings' structured data check reads the result.
+
+### 6. Content
+
+Replace hardcoded content with kit reads, one page at a time. Keep the design exactly as it is; only where the text and numbers come from changes.
+
+```tsx
+import { copyText, formatMoney, getFloorPlans, getSite } from "site-manager-kit";
+
+export default async function Home() {
+  const [site, plans] = await Promise.all([getSite(), getFloorPlans()]);
+  return (
+    <>
+      <h1>{await copyText("home.hero.title", site?.business.displayName)}</h1>
+      {plans.map((p) => (
+        <p key={p.slug}>
+          {p.name} from {formatMoney(p.startingRent) ?? "Call for pricing"}
+        </p>
+      ))}
+    </>
+  );
+}
+```
+
+Images from Site Manager come with their size and alt text. Show them with `next/image`, which serves resized, modern versions:
+
+```tsx
+import Image from "next/image";
+import { imageProps } from "site-manager-kit";
+
+const img = imageProps(plan.image);
+{img ? <Image {...img} sizes="(min-width: 768px) 50vw, 100vw" /> : null}
+```
+
+Without a known size, `imageProps` uses `fill`, so the image needs a sized box with `position: relative`.
+
+Visitor tracking: add `<SiteAnalytics />` once inside `<body>` in `app/layout.tsx`. It adds StackOS's tracking script with the key the agency sets on the site's Connection tab, and adds nothing while there's no key.
+
+```tsx
+import { SiteAnalytics } from "site-manager-kit/analytics";
+import { SiteAttribution } from "site-manager-kit/attribution";
+
+<body>
+  {children}
+  <SiteAnalytics />
+  <SiteAttribution />
+</body>
+```
+
+Where leads came from: `<SiteAttribution />` remembers the visitor's first `utm_` values, landing page and referring site for the browser tab (session storage, no cookie, so no consent banner), and `FormGuard` sends them with every form. Leads then show under their source in Site Manager (Leads > Leads by Source). Links made with Link Tools carry the `utm_` values.
+
+
+The full list of reads is in the kit README. Rules that matter:
+
+- Money is a decimal string like `"1450.00"`. Show it with `formatMoney`, never `Number()`.
+- Show availability with `availabilityText(plan)`, which follows the site's setting in Site Manager: "Available now" by default, the exact count only when the site chose it, and nothing when it's unknown. Don't print `availableCount` yourself; it's kept for older sites and is `null` when availability is unknown, never 0.
+- A plan with a running special has `concession.effectiveRent`. Show it next to the regular rent, never instead of it: `effectiveRentText(plan)` gives "$2,207.12 effective".
+- To compare plans side by side, `comparisonRows(plans)` gives one row per fact (bedrooms, size, rent, layout, availability) and per feature, ready for a table.
+- A section that is turned off for the site answers with `BlueprintError` code `module_off`. Only read sections the site has on.
+
+### 7. Forms
+
+A form is a small client component, so it can show the result, plus a server page that hands it `FormGuard` (the guard signs its render time on the server).
+
+`app/contact/ContactForm.tsx`:
+
+```tsx
+"use client";
+
+import { useActionState, type ReactNode } from "react";
+import { formAction } from "site-manager-kit/forms";
+
+export function ContactForm({ guard }: { guard: ReactNode }) {
+  const [state, action, pending] = useActionState(formAction.bind(null, "inquiry"), null);
+  if (state?.ok) return <p>{state.successMessage}</p>;
+  return (
+    <form action={action}>
+      <input name="name" required />
+      <input name="email" type="email" required />
+      <textarea name="message" />
+      {guard}
+      {state && !state.ok ? <p>{state.error === "invalid" ? "Check the highlighted fields." : "That didn't send. Try again in a moment."}</p> : null}
+      <button disabled={pending}>Send</button>
+    </form>
+  );
+}
+```
+
+`app/contact/page.tsx`:
+
+```tsx
+import { FormGuard } from "site-manager-kit/form-guard";
+import { ContactForm } from "./ContactForm";
+
+export default function Contact() {
+  return <ContactForm guard={<FormGuard />} />;
+}
+```
+
+The field names must match the form's fields in Site Manager (Forms > the form). For phone fields use `<PhoneInput name="phone" />` from `site-manager-kit/phone`: it formats as the visitor types, (555) 123-4567, the format Site Manager checks and stores. A field's `help` (from `getForm`) is a short line to show under it. `state.error` is `invalid` (with `state.fields` naming each field's problem), `rate_limited`, `slot_taken` (booking forms) or `unavailable`. Suspected spam answers like a normal submission and lands in Site Manager's spam folder. Don't pass `submitForm` straight to `<form action>`: it returns a result, which a plain form action can't. A form with its own signed timer, or a send with no form (a remembered visitor's one-click download), passes `submitForm(key, data, { timedBySite: true })` after the site's own checks: the FormGuard timer is skipped, the honeypot and BotID still apply.
+
+#### Booking forms
+
+A form whose kind is Booking (set by the agency in Site Manager) also needs one of the site's open times, set under Forms > Booking Times. Read them with `getBookingSlots` (never cached, since every booking changes them) and send the chosen `start` as the `bp_slot` field:
+
+```tsx
+// app/tour/page.tsx
+import { Suspense } from "react";
+import { connection } from "next/server";
+import { getBookingSlots } from "site-manager-kit";
+import { FormGuard } from "site-manager-kit/form-guard";
+import { TourForm } from "./TourForm";
+
+export default function Tour() {
+  // With Cache Components on, only the open times render per visit; the rest of the page stays static.
+  return (
+    <Suspense fallback={<p>Finding open times...</p>}>
+      <Times />
+    </Suspense>
+  );
+}
+
+async function Times() {
+  await connection();
+  const slots = await getBookingSlots("tour", { days: 14 });
+  return <TourForm days={slots?.days ?? []} guard={<FormGuard />} />;
+}
+```
+
+```tsx
+// app/tour/TourForm.tsx, inside the <form> from the contact example
+{days.map((d) => (
+  <fieldset key={d.date}>
+    <legend>{d.date}</legend>
+    {d.slots.map((s) => (
+      <label key={s.start}>
+        <input type="radio" name="bp_slot" value={s.start} required /> {s.label}
+      </label>
+    ))}
+  </fieldset>
+))}
+```
+
+`state.error` can also be `slot_taken` when someone booked that time a moment earlier: show the times again. Times are in the site's time zone (`slots.timezone`), and a day with no open times has an empty `slots` list.
+
+Protect each page that posts a form with BotID, in `instrumentation-client.ts`. It goes in `src/` when the app has a `src` folder, and at the project root otherwise; in the wrong place it's silently ignored and BotID warns about a misconfiguration:
+
+```ts
+import { initBotId } from "botid/client/core";
+
+initBotId({ protect: [{ path: "/contact", method: "POST" }] });
+```
+
+### Waitlist (apartment sites)
+
+With the Waitlist section on in Site Manager, visitors can ask to hear when a floor plan, or any plan with their bedroom count, has a home available. Site Manager emails them once when it opens, with a link to leave the list. The form uses `FormGuard` and the same spam checks as other forms.
+
+On a plan page, send the plan's slug in a hidden field. A general form can offer one picker from `waitlistChoices(await getWaitlistOptions())`, which lists each bedroom count and the plans with nothing open now.
+
+```tsx
+"use client";
+
+import { useActionState, type ReactNode } from "react";
+import { waitlistAction } from "site-manager-kit/waitlist";
+
+export function WaitlistForm({ plan, guard }: { plan: string; guard: ReactNode }) {
+  const [state, action, pending] = useActionState(waitlistAction, null);
+  if (state?.ok) return <p>You're on the list. We'll email you when one opens.</p>;
+  return (
+    <form action={action}>
+      <input type="hidden" name="floorPlan" value={plan} />
+      <input name="email" type="email" required />
+      <input name="moveIn" type="date" />
+      {guard}
+      <button disabled={pending}>Notify Me</button>
+    </form>
+  );
+}
+```
+
+Fields: `floorPlan` (a slug) or `bedrooms` (a number), or one `choice` (`plan:<slug>` or `beds:<n>`), plus `email`, and optionally `name`, `phone` and `moveIn` (`YYYY-MM-DD`). `state.error` is `invalid` with `fields`, `rate_limited` or `unavailable`. Add the page to BotID's `protect` list like any form page.
+
+### Website chat
+
+With Website Chat on and live in Site Manager (kit 1.25.0), a chat button shows on every page. It answers visitors only from the site's published content in Site Manager, says when it doesn't know and gives the contact details, and turns visitors who want a tour, a quote or a call back into leads with the conversation attached. It runs on the site's own AI key, set in Site Manager.
+
+Add the route the chat talks to. It keeps the API key on the server, sends Site Manager only a hash of the visitor's address, and refuses requests that don't come from the website's own pages:
+
+```ts
+// app/api/blueprint/chat/route.ts
+export { GET, POST } from "site-manager-kit/chat-route";
+```
+
+Then put the component once inside `<body>` in `app/layout.tsx`. It renders nothing until the chat is live, and nothing when Website Chat is off for the site:
+
+```tsx
+import { SiteChat } from "site-manager-kit/chat";
+
+<SiteChat />
+```
+
+It takes the site's accent from Site Manager and follows the visitor's light or dark setting. Props, all optional: `accent` (a CSS color), `theme` (`"auto"`, `"light"` or `"dark"`), `position` (`"right"` or `"left"`), `offset` (pixels to raise it above a cookie bar) and `endpoint` (when the route lives somewhere else). Text on the accent switches between dark and white so a light accent stays readable.
+
+- Replies stream in as they're written. The conversation follows the visitor from page to page in the same tab, and a random visitor id in the browser's storage is the only thing kept there; Site Manager stores only its hash.
+- When a visitor wants a person, the chat offers a short form (name, email or phone, message). With Booking Times on and a booking form chosen in Site Manager, it offers open times and books one. Leads arrive like form submissions, with the source "Website chat".
+- Add the route to BotID's `protect` list to check for bots before Site Manager is asked: `{ path: "/api/blueprint/chat", method: "POST" }`. Site Manager limits each visitor and the site either way.
+- `getChatConfig()` (from `site-manager-kit/chat`) reads the settings if the site builds its own chat. The route's answers are NDJSON lines: `start` with the conversation id, `delta` with text, and `done` saying whether it couldn't answer and whether to offer a hand-off (`parseChatLines` reads them).
+
+### 8. Caching
+
+- Every kit read is cached for an hour and refreshed the moment content changes in Site Manager, through the revalidate route. Don't add your own `revalidate` or `cache: "no-store"` around kit reads.
+- A refresh never makes a visitor wait: the first visit after a change gets the page as it was and rebuilds it in the background, and the next visit shows the change. Site Manager refreshes only the sections a change affects.
+- Pages that only use kit reads can stay static. Don't call `cookies()` or `headers()` on them unless the page needs it.
+- Redirects are cached for 5 minutes in the proxy and cleared when they change.
+- After a deploy, the first visit to each page fills the cache. Nothing needs warming.
+- Pages are prerendered from Site Manager at build time, so a build needs Site Manager to be reachable. If a build fails with `fetch failed`, check `BLUEPRINT_URL`.
+- A page with a form renders on each request (`FormGuard` does this), so its timing check always has a fresh render time.
+
+### 9. Check it
+
+1. `npm run build` passes.
+2. Deploy (or run `npm run dev` with the env vars) and open the site. Content shows, and `/sitemap.xml` and `/robots.txt` load.
+3. In the wizard, press **Check Connection**. Both "connected" and "bot protection, honeypot and timing checks are on" must show.
+4. Change a piece of site copy in Site Manager and reload the page: the new text shows within a few seconds.
+5. Send a test form from a Link Tools link and confirm it arrives in Leads under that link's source.
+
+### 10. Wiring audit
+
+Run it after a new build, after adding or changing a page or section, and before Go live:
+
+```bash
+npx site-manager-kit audit
+```
+
+It reads `BLUEPRINT_URL` and `BLUEPRINT_API_KEY` from `.env.local` (or `--env <file>`; use the production values, it only reads), loads `src/copy-keys.ts` (`--keys <file>` for another), and writes `.wiring/report.md`. Every item is one of:
+
+- **Wired**: the site reads it from Site Manager.
+- **Not wired**: Site Manager has it, but editing it changes nothing on the website (a key the site never asks for, a section that's on but never read, a Business Info field the code ignores). Fails the audit.
+- **Missing in Site Manager**: the site uses it, but Site Manager has no such field (a key not synced yet, a form key with no form). Fails the audit.
+- **Hard-coded**: the code keeps its own copy of a Site Manager value, with file and line. Reported, never failing, since a fallback can be on purpose.
+- **Unknown**: the audit couldn't tell (the copy keys file didn't load, a section it doesn't know yet).
+
+Exit codes: 0 wired, 1 something Not wired or missing, 2 it couldn't run. Folders it shouldn't scan (an old admin, scripts) go in `package.json`:
+
+```json
+"siteManagerAudit": { "ignore": ["src/admin"], "keysFile": "src/copy-keys.ts" }
+```
+
+**Upload the result** so Site Manager shows it (the site's Wiring tab, the wiring score on Overview, and the Portfolio column):
+
+```bash
+npx site-manager-kit audit --upload
+```
+
+It needs a **Wiring audit** key from the site's API Keys tab, in `BLUEPRINT_AUDIT_KEY` (beside the website's own key, never in place of it). An audit key reads content and uploads results, and can't send forms or anything else, so it's the one to keep on a developer's computer or as a CI secret. When it's set, the audit reads with it too. A failed upload exits 2.
+
+**Deploys**: the health route sends `deployId` (`VERCEL_DEPLOYMENT_ID`, else `VERCEL_GIT_COMMIT_SHA`), so Site Manager notices each deploy and runs its own website check the same day, flagging problems the deploy brought in.
+
+Site Manager's `docs/wiring.md` explains the whole process and how to fix each kind of gap.
+
+### Launch checklist
+
+- [ ] Every page reads its content and metadata from Site Manager, and the design is unchanged.
+- [ ] `sitemap.ts`, `robots.ts`, `proxy.ts`, and the revalidate and health routes are in place.
+- [ ] Every form uses `FormGuard`, and its page is protected in `instrumentation-client.ts`.
+- [ ] `<SiteAttribution />` is in the root layout, so leads record their source.
+- [ ] The five env vars are set in Vercel for Production and Preview.
+- [ ] System Status shows every check ok.
+- [ ] `npx site-manager-kit audit` reports nothing Not wired or missing in Site Manager.
+- [ ] Search Listings has every page with a target keyword, and the legal pages are published.
+- [ ] Go live in the wizard (this lets search engines in), then add the site to `docs/SITES.md`.
+
+### Blog
+
+With the Blog section on, a site reads posts, categories and tags. Set the Blog posts page pattern in Site Manager (Search Listings, page addresses) to match the site's route, for example `/blog/{slug}`, so each post gets its search listing, sitemap entry and `url`.
+
+```tsx
+import { blogPostingJsonLd, getPost, getPosts, pageMetadata } from "site-manager-kit";
+
+// app/blog/page.tsx
+const { posts, paging } = await getPosts({ page, perPage: 12 });
+
+// app/blog/[slug]/page.tsx
+export const generateMetadata = async ({ params }) => pageMetadata(`/blog/${(await params).slug}`);
+const post = await getPost(slug); // null: notFound()
+const ld = JSON.stringify(blogPostingJsonLd(post, { publisherName: site.business.displayName })).replace(/</g, "\\u003c");
+<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: ld }} />
+```
+
+RSS: `app/blog/rss.xml/route.ts` with
+
+```ts
+import { rssRoute } from "site-manager-kit/rss-route";
+export const GET = rssRoute();
+```
+
+Posts are in the sitemap already (Site Manager lists every published post's page). Category pages aren't pages in Site Manager; add them to `sitemap([...])` from `getBlogCategories()` if the site has them.
+
+## Reference: content reads
+
+Available: `getSite`, `getCopy`, `copyText`, `copyImage(key)` (a built-in photo from an image key), `getReviews({ featured, sort })`, `getFloorPlans`, `getFloorPlan(slug)` (with units), `getUnitMaps()` (site plan drawings with open units placed on them), `getAmenities({ category })`, `getFees` (with `requiredMonthlyTotal`), `getPetPolicy`, `getParking`, `getSpecials`, `getEvents({ from, limit })`, `getEvent(slug)`, `getServices({ category })`, `getService(slug)`, `getLocations`, `getNearbyPlaces({ category })` (with `walkMinutes`, `driveMinutes`, `transitMinutes` and `school`; `category: "commute"` for commute times), `getForm(key)`, `getBookingSlots(key, { from, days })` (never cached), `getLegal`, `getLegalDoc(slug)`, plus the real estate reads below. Each returns `null` (or an empty list) when there's nothing, and throws `BlueprintError` when Site Manager answers with an error, for example `module_off`.
+Available: `getSite`, `getCopy`, `copyText`, `getReviews({ featured, sort })`, `getFloorPlans`, `getFloorPlan(slug)` (with units), `getAmenities({ category })`, `getFees` (with `requiredMonthlyTotal`), `getPetPolicy`, `getParking`, `getPolicies` (leasing policies), `getResidentResources` (the residents page sections), `pickupText` and `leaseTermsText`, `getSpecials`, `getEvents({ from, limit })`, `getEvent(slug)`, `getLocations`, `getNearbyPlaces({ category })` (with `walkMinutes`, `driveMinutes`, `transitMinutes` and `school`; `category: "commute"` for commute times), `getForm(key)`, `getBookingSlots(key, { from, days })` (never cached), `getLegal`, `getLegalDoc(slug)`, plus the real estate reads below. Each returns `null` (or an empty list) when there's nothing, and throws `BlueprintError` when Site Manager answers with an error, for example `module_off`.
+Available: `getSite`, `getCopy`, `copyText`, `getReviews({ featured, sort })`, `getFloorPlans`, `getFloorPlan(slug)` (with units), `getAmenities({ category })`, `getFees` (with `requiredMonthlyTotal`), `getPetPolicy`, `getParking`, `getSpecials`, `getEvents({ from, limit })`, `getEvent(slug)`, `getLocations`, `getNearbyPlaces({ category })` (with `walkMinutes`, `driveMinutes`, `transitMinutes` and `school`; `category: "commute"` for commute times), `getForm(key)`, `getBookingSlots(key, { from, days })` (never cached), `getLegal`, `getLegalDoc(slug)`, `getFaq`, `getFaqSet(key)`, `getAnnouncements`, `getDownloads`, plus the real estate reads below. Each returns `null` (or an empty list) when there's nothing, and throws `BlueprintError` when Site Manager answers with an error, for example `module_off`.
+Available: `getSite`, `getCopy`, `copyText`, `getReviews({ featured })`, `getFloorPlans`, `getFloorPlan(slug)` (with units), `getAmenities({ category })`, `getFees` (with `requiredMonthlyTotal`), `getPetPolicy`, `getParking`, `getSpecials`, `getEvents({ from, limit })`, `getEvent(slug)`, `getLocations`, `getNearbyPlaces({ category })` (with `walkMinutes`, `driveMinutes` and `school`), `getForm(key)`, `getBookingSlots(key, { from, days })` (never cached), `getLegal`, `getLegalDoc(slug)`, `getPosts({ page, perPage, category, tag })`, `getPost(slug)`, `getBlogCategories`, `getBlogCategory(slug, { page, perPage })`, `getBlogTags`, `getBlogFeed({ limit })`. Each returns `null` (or an empty list) when there's nothing, and throws `BlueprintError` when Site Manager answers with an error, for example `module_off`.
+
+Money is always a decimal string like `"1450.00"`. Format it with `formatMoney`, never `Number()`.
+
+`availableCount` is `null` when a floor plan lists no units: availability is unknown, not zero. Prefer `availability` (`{ status, count }`, with `count` only when the site shows exact numbers) through `availabilityText`.
+
+Floor plan helpers: `availabilityText(plan, labels?)`, `effectiveRentText(plan)` and `comparisonRows(plans)`.
+
+Real estate reads (1.6.0; listing details and past sales from 1.8.0; open houses and the agent filter from 1.10.0): `getListings({ status, minPrice, maxPrice, beds, type, featured, agent, area, limit })` (active first, each with `featuredImage`, `imageCount`, `badge`, `pricePerSqft` and its `agent`), `getListing(slug)` (adds `images`, `features`, `schools`, `history` and `transactions`: past sales, newest first, with buyer and seller only when the agent shows them), `getTeam`, `getTeamMember(slug)` and `getPaymentDefaults`. `status` takes one status or a list (`coming_soon`, `active`, `pending`, `sold`); off market listings never come back. Prices filter on the sold price for sold listings. Listings also carry `daysOnMarket`, `interior`, `exterior`, `lotDetails`, `parking`, `utilities`, `hoaName`, `hoaIncludes`, `taxes` and `openHouses` (upcoming only, each with a ready `label`); empty lists and nulls mean not known. `agent` takes a team member's short name, for an agent page with their listings. `getSoldListings({ area, agent, limit })` lists sold homes (each with `soldPrice` and `soldOn`) for a sold portfolio.
+
+Area guides (1.17.0): `getAreas()` and `getArea(slug)` return each area's `descriptionHtml`, `photos`, `highlights`, `schools` and `listingCount`; `getListings({ area: slug })` gives the homes in it. A listing is in an area when its neighborhood matches the area's name or one of its `otherNames`, ignoring case.
+Waitlist (1.18.0): `getWaitlistOptions()` (the plans, with whether each has a home open, and the bedroom counts), `waitlistChoices(options)` and `readWaitlistForm(formData)`; the form action is `waitlistAction` from `site-manager-kit/waitlist`.
+
+Real estate reads (1.6.0; listing details and past sales from 1.8.0; open houses and the agent filter from 1.10.0): `getListings({ status, minPrice, maxPrice, beds, type, featured, agent, limit })` (active first, each with `featuredImage`, `imageCount`, `badge`, `pricePerSqft` and its `agent`), `getListing(slug)` (adds `images`, `features`, `schools`, `history` and `transactions`: past sales, newest first, with buyer and seller only when the agent shows them), `getTeam`, `getTeamMember(slug)` and `getPaymentDefaults`. `status` takes one status or a list (`coming_soon`, `active`, `pending`, `sold`); off market listings never come back. Prices filter on the sold price for sold listings. Listings also carry `daysOnMarket`, `interior`, `exterior`, `lotDetails`, `parking`, `utilities`, `hoaName`, `hoaIncludes`, `taxes` and `openHouses` (upcoming only, each with a ready `label`); empty lists and nulls mean not known. `agent` takes a team member's short name, for an agent page with their listings.
+
+Services (1.12.0): each has `price.kind` (`none`, `fixed`, `range`, `starting_at`, `call`), `price.from` and `price.to` as decimal strings, an optional `price.note` ("per hour") and `price.label`, ready-to-show text like "Starting at $150" (null when no price is shown). `serviceJsonLd(service, site, url)` returns schema.org `Service` structured data for the page; render it in a `<script type="application/ld+json">`.
+
+Listing helpers: `listingAddress(listing)`, `listingPrice(listing)` (the sold price once sold), `bathsText(baths)` ("3.0" becomes "3"), `lotText(lot)` ("1.02 acres"), `hoaText(hoa)` ("$85 per month") and `estimatePayment(price, defaults, hoa?)`. The estimate uses whole-cent integer math and returns `null` until the site sets a rate, down payment and term in Site Manager (Listings > Settings), so show nothing rather than a guess. Always label it as an estimate.
+
+```tsx
+const [listing, defaults] = await Promise.all([getListing(slug), getPaymentDefaults()]);
+const estimate = listing ? estimatePayment(listingPrice(listing), defaults, listing.hoa) : null;
+// estimate?.total is a decimal string: formatMoney(estimate.total)
+```
+
+FAQ, announcements and downloads (1.15.0), for any kind of site:
+
+- `getFaq({ category })` gives `{ categories, questions }`, questions in category order. `getFaqSet(key)` gives one named set a page asks for (like `"leasing-page"`), its questions in the set's order, or `null` when there's no such set. Each question has `answerHtml` and `answerText`. `faqJsonLd(questions)` builds FAQPage structured data; render it with `jsonLdScript`, and only for the questions the page shows:
+
+  ```tsx
+  <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: jsonLdScript(faqJsonLd(set.questions)) }} />
+  ```
+
+- `getAnnouncements()` gives the notices live now, urgent first. It is never served before a start or past an end: the cached copy is used only until Site Manager's next start or end, then read fresh. Call it at request time, inside a Suspense boundary after `await connection()`, not in a prerendered shell. `announcementsLiveAt(list, now)` is the filter it uses.
+- `getDownloads({ category })` gives published files (`brochure`, `menu`, `application`, `price_sheet`, `other`). Link to each one's `url`: it goes through Site Manager, which counts the download and sends the file. `fileSizeText(bytes)` gives "2.4 MB".
+
+## Development
+
+```bash
+npm install
+npm test
+npm run typecheck
+```