# Kibble installation contract: section 24 of 29 (guide version 3)

> This is **one section only**, not the whole contract. Complete document: https://www.usekibble.dev/AI/guide.md

## 24. Hosting and synchronizing the site manifest {#manifest}

### Host it on the site (preferred)

- Serve the manifest at `https://<primary or registered host>/kibble/site.json` as static JSON (`Content-Type: application/json`) with an `ETag` or `Last-Modified` header. Most static hosts do this for you.
- Make sure the path returns the file, not the site’s HTML page: many SPAs answer every path with `index.html`, which Kibble refuses.
- Use `mode: "patch"` for a hosted file. With `replace`, removing an entry would archive it; Kibble never does that automatically, but an admin reviewing the change would see it.
- Do not put the manifest behind authentication, cookies or a redirect to another host. Kibble sends no credentials and follows at most three redirects, only to registered hosts of the property.
- The manifest is public: everything in it is visible to anyone. That is why it may hold public business data only.

### How it reaches Kibble

1. A Kibble property admin opens Catalog → Settings → Site manifest, chooses Sync from site, and enters (or accepts) the URL. Registering a URL never fetches anything.
2. The admin presses **Check site**. Kibble fetches the file once, validates it, and shows a preview: additions, changes, archives, report-namespace changes and anything that would replace a correction made in Kibble.
3. The admin applies it. The initial synchronization is always applied by a person; a file being reachable never applies it.
4. Optionally the admin turns on **automatic checks** (at most once a day) and chooses whether new entries and name changes may apply without review.

Without a hosted file (GTM-only, CMS-only, or a booking engine that cannot host files), give the JSON to an admin to upload in Catalog → Settings → Site manifest → Import. Preview and apply work the same way.

### Automatic checks: what may change without review

| Change in the site file | Automatic check |
| --- | --- |
| New entry | Applied only if the admin allowed additions. |
| Name, short name or locality of an entry the site provided | Applied only if the admin allowed name changes. |
| Anything about an entry corrected in Kibble | Never applied: Kibble corrections win. Waits for review. An admin can return the entry to the site’s values with **Use the site’s value** in its Catalog drawer (offered only when the last fetched site file lists it). |
| Page or image URL, provenance, reactivating an archived entry | Waits for review. |
| An entry missing from a replace manifest (archive) | Waits for review. Nothing is ever deleted. |
| A report namespace set or changed | Waits for review (it re-names retained history). |
| Invalid file, wrong content type, too large, unreachable | Nothing changes; the last applied catalog stays. The check is retried later with back-off. |

If any change in a check needs review, nothing from that check is applied; the admin sees the whole preview. Name changes update report presentation immediately and never change counts or rebuild reports.

### Network rules Kibble follows

- https only, on a host registered for the property; default port only; no user names, query strings or fragments.
- Private, loopback, link-local, metadata and other non-public addresses are refused, checked on the address actually connected to (DNS rebinding cannot bypass it). Redirects are re-checked.
- No cookies, authorization or forwarded headers are sent; TLS is verified; 10 seconds and 256 KiB at most; conditional requests (`If-None-Match`, `If-Modified-Since`).
- Kibble fetches only the registered manifest URL: never URLs found inside the manifest, never images or pages, never during report rendering or visitor requests.
- Automatic checks: at most one request per property per day (spread across the day), fewer after failures; one catalog write per applied change.

END OF SECTION manifest