docs: add sync frontmatter and drop em-dashes from docs/

Makes docs/ syncable into developer-docs as the Frontends section, with
this repo staying the single source of truth (#124).

- Add Starlight frontmatter (title, description, sidebar.order) to all
  eight pages, and drop the H1 now that the frontmatter carries the
  title. GitHub renders the frontmatter as a table, nested sidebar.order
  included, so the title is still visible here; keeping both would mean
  five of the eight pages carrying a title that disagrees with their H1.
  This also makes the sync a pure rsync, as caffeinelabs/motoko does.
  No anchor moves: every cross-page link targets an H2 or H3.
- Replace all 124 em-dashes. developer-docs bans U+2014 repo-wide; doing
  it here rather than in their postprocess keeps the published page and
  the file in this repo byte-identical, which is what makes the sync
  trustworthy. Definition bullets take the `- **Term.** Sentence.` form
  already used in routing.md; prose takes a colon, semicolon, comma, or
  parentheses per sentence.
- Point the custom-domains link at the live URL. The old
  building-apps/frontends/... form is the retired portal layout and only
  survives on a redirect.
- Make the three links that escape docs/ (ARCHITECTURE.md,
  README.md#releasing, examples/spa) absolute GitHub URLs, so no link
  rewriting is needed on the sync side.
- Fix the stale example version in overview.md: v1.0.0 -> v0.3.3.

The `<version>` placeholder convention in overview.md is unchanged.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: marc0olo

docs/access-protection.md

@@ -1,16 +1,21 @@
-# Access protection (private apps)
+---
+title: "Access protection"
+description: "Put a login page in front of a private or preview site with revocable, expiring access tokens"
+sidebar:
+  order: 6
+---
 
 By default every deployed app is public. **Access protection** puts a login screen
 in front of it: unauthenticated visitors get a certified redirect to your login
 page (or a `401` for non-page assets) instead of your content. It's meant to
-**deter casual/public access** to in-progress or preview work — not to provide
+**deter casual/public access** to in-progress or preview work, not to provide
 confidentiality against a determined attacker (see [Threat model](#threat-model)).
 
 Access is a set of **labeled tokens**. The cookie *is* the token: a visitor presents
 a token, the canister sets it as a cookie, and every request re-validates that cookie
 against the token store. A classic single "password" is just one long-lived token.
 
-When protection is off, the app is **completely unchanged** — no gate, no extra
+When protection is off, the app is **completely unchanged**: no gate, no extra
 headers, no cost difference. Everything below applies only once you enable it.
 
 ## Quick start
@@ -30,7 +35,7 @@ icp canister call frontend issue_token \
   '(record { label = "owner"; ttl_secs = 31536000 : nat32; value = opt "my-passphrase" })'
 ```
 
-That's it — `https://<canister-id>.icp0.io/` now redirects strangers to
+That's it: `https://<canister-id>.icp0.io/` now redirects strangers to
 `/login.html`, and visitors who present `my-passphrase` get in.
 
 > **Enable before the first sync for a brand-new private app.** Enabling on an empty
@@ -42,29 +47,29 @@ That's it — `https://<canister-id>.icp0.io/` now redirects strangers to
 | Method | Call | Effect |
 |---|---|---|
 | Issue | `issue_token '(record { label = "<label>"; ttl_secs = <secs> : nat32; value = opt "<value>" })'` | Mints a token and **returns its value**. Pass `value = null` (or leave the field out) to get a high-entropy random token instead of a chosen passphrase. |
-| Revoke | `revoke_token '("<label>")'` | Removes every token with that label — **live**, so the next request bearing it is rejected. |
+| Revoke | `revoke_token '("<label>")'` | Removes every token with that label. Takes effect **live**, so the next request bearing it is rejected. |
 | List | `list_tokens '()'` | Returns `{ label; expires_at }` for every live token (controller-only). |
 | Status | `check_protection_status '()'` | `Disabled`, `Enabled`, or `EnabledLoginPageMissing` (controller-only). |
 | Disable | `disable_protection '()'` | Turns the gate off and drops all tokens. |
 
-Always pass the argument explicitly — `'()'` for the methods that take none. Given no
+Always pass the argument explicitly (`'()'` for the methods that take none). Given no
 argument, `icp canister call` opens an interactive prompt instead of sending an empty one.
 
-Each token has its **own expiry** and is **individually revocable** — revoking one
+Each token has its **own expiry** and is **individually revocable**: revoking one
 leaked share doesn't disturb anyone else. Expired tokens are rejected immediately
 whether or not they've been swept, and are garbage-collected as new ones are issued.
 
 **Random vs. chosen value.** A random token (omit the chosen value) is unguessable
 and never transits the subnet in readable form. A chosen passphrase is typeable but
 brute-forceable, and is visible to node operators in the block that carries the
-`issue_token` call — acceptable under the threat model, but prefer random tokens for
-share links.
+`issue_token` call. That is acceptable under the threat model, but prefer random
+tokens for share links.
 
 ## The login page
 
 The login page is **your own asset**, synced in `dist/` and named when you
 `enable_protection`. The canister serves it certified like any other page; it is the
-**only gate-exempt path**, so it must be **fully self-contained** — inline its CSS and
+**only gate-exempt path**, so it must be **fully self-contained**: inline its CSS and
 JS, and use `data:` URIs for images. Any external subresource it referenced would
 itself be gated and fail to load for a logged-out visitor.
 
@@ -105,7 +110,7 @@ A minimal page that does both:
 
 | Request | Response |
 |---|---|
-| An HTML page (or any path with no exact asset — SPA routes, 404s) | Certified `307 → <login_page>` |
+| An HTML page (or any path with no exact asset, such as SPA routes and 404s) | Certified `307 → <login_page>` |
 | A non-HTML asset (JS/CSS/image/JSON) | Certified `401` (a redirect would hand a `<script>` the wrong content type) |
 | The login page itself | Always served (gate-exempt) |
 
@@ -116,12 +121,12 @@ cookie-blind boundary cache can never replay one visitor's response to another.
 
 `check_protection_status` reports one of:
 
-- **`Disabled`** — public app.
-- **`Enabled`** — gate on, login page present.
-- **`EnabledLoginPageMissing`** — gate on, but the named login-page asset isn't
+- **`Disabled`**: public app.
+- **`Enabled`**: gate on, login page present.
+- **`EnabledLoginPageMissing`**: gate on, but the named login-page asset isn't
   synced. The app **stays protected** (no content is served); requests redirect to a
-  page that 404s until you sync it. It **self-heals** to `Enabled` once the page lands
-  — no need to re-enable.
+  page that 404s until you sync it. It **self-heals** to `Enabled` once the page
+  lands, with no need to re-enable.
 
 The gate **fails closed**: a sync that removes the login page, or enabling before the
 first sync, never exposes content.
@@ -136,27 +141,27 @@ store, so a token replayed against another canister isn't in *its* store.
 
 The canister serves **response-only** certified responses: the HTTP gateway (and any
 verifier) checks that each response is an *authentic, certified* response for the
-requested path — but **not** which of several certified responses the canister chose to
-return. Choosing one is ordinary application logic.
+requested path, but **not** which of several certified responses the canister chose
+to return. Choosing one is ordinary application logic.
 
 That is the same mechanism the canister already uses to serve more than one response
-per URL — different content encodings, `200` vs `304`, `206` range responses, and the
+per URL: different content encodings, `200` vs `304`, `206` range responses, and the
 redirect/rewrite rules that serve one asset's body under another path. Access
 protection has the same shape: under every protected path the canister certifies
-**both** the asset's normal responses **and** a certified *unauthenticated sibling* —
-the `307 → <login_page>` (HTML pages) or the `401` (other types). At serve time it
-reads the `certified_assets_access` cookie and returns the sibling when it's missing or
-invalid, the real asset when it's valid — each one independently verified by the
+**both** the asset's normal responses **and** a certified *unauthenticated sibling*,
+either the `307 → <login_page>` (HTML pages) or the `401` (other types). At serve time
+it reads the `certified_assets_access` cookie and returns the sibling when it's missing
+or invalid, the real asset when it's valid; each one is independently verified by the
 gateway. The login page's path additionally carries the certified `302 + Set-Cookie`
 redeem (one per token) and the `401` re-prompt, so a login `POST` is honored only
 because its outcome is certified too.
 
 **Why not certify the request?** Doing so would let the canister prove *which* request
-it answered, but request certification hashes the whole `Cookie` header verbatim — it
-can't match on a single *named* cookie. Nor would it fire: the canister sets its own
+it answered, but request certification hashes the whole `Cookie` header verbatim, so
+it can't match on a single *named* cookie. Nor would it fire: the canister sets its own
 `ic_env` cookie on HTML responses, so a browser always sends
 `Cookie: ic_env=…; certified_assets_access=…`, never a bare value. Picking one cookie
-out of many is necessarily app-side logic — hence response-only.
+out of many is necessarily app-side logic, hence response-only.
 
 **The caveat this creates.** Because the cookie→response choice is uncertified app
 logic, *which* response a request receives is **not** covered by the certificate. An
@@ -168,16 +173,16 @@ and it sets up the trust boundary the threat model below makes precise.
 ## Threat model
 
 This is **access gating, not confidentiality.** Under the IC's honest-replica /
-honest-boundary-node assumption — the same assumption all query serving already makes
-— unauthorized visitors can't pull your content. But:
+honest-boundary-node assumption (the same assumption all query serving already
+makes), unauthorized visitors can't pull your content. But:
 
 - Asset bytes and the token store live in replicated canister state, so a **node
   operator can read both**. Protection does not hide content from operators. (Random
   token values are stored hashed; a low-entropy chosen passphrase is still
   brute-forceable, like any password hash.)
 - TLS terminates at the boundary node, which sees the cookie in clear.
-- There is **no brute-force protection, lockout, or rate-limiting** — login attempts
+- There is **no brute-force protection, lockout, or rate-limiting**: login attempts
   are unbilled, untracked queries. The deterrent is high-entropy random tokens.
 
-Use it to keep a preview or in-progress app out of public view — not to protect
+Use it to keep a preview or in-progress app out of public view, not to protect
 secrets from a determined adversary.

docs/headers.md

@@ -1,7 +1,12 @@
-# Custom headers
+---
+title: "Custom headers"
+description: "The _headers file: cache-control, security headers, content types, and how rules combine"
+sidebar:
+  order: 4
+---
 
 Add a file named `_headers` to the root of your asset directory to attach response
-headers — cache-control, a Content Security Policy, other security headers — to files
+headers (cache-control, a Content Security Policy, other security headers) to files
 on your site. The syntax follows [Netlify's `_headers`](https://docs.netlify.com/manage/routing/headers/):
 a path pattern on its own line, followed by indented `Name: value` lines.
 
@@ -20,28 +25,28 @@ A blank line or a `#` comment ends a block.
 
 A pattern is an absolute path (leading `/`) with an optional `*` wildcard:
 
-- `/index.html` — one exact file (the home page).
-- `/about.html` — likewise, one exact file.
-- `/assets/*` — everything under `/assets/`.
-- `/*.css` — every file ending in `.css`.
-- `/*` — every file.
+- `/index.html`: one exact file (the home page).
+- `/about.html`: likewise, one exact file.
+- `/assets/*`: everything under `/assets/`.
+- `/*.css`: every file ending in `.css`.
+- `/*`: every file.
 
 The single `*` matches any run of characters, including `/`. There is no `**`, no
 `?`, and no `:placeholder` capture (see [why dynamic rules aren't supported](redirects.md#what-isnt-supported-dynamic-rules)).
 
 ### Patterns match files, not URLs
 
-A pattern is matched against the **path of the file inside your directory** — its
-asset key — not against the URL a visitor typed. For most sites the two are the same
+A pattern is matched against the **path of the file inside your directory** (its
+asset key), not against the URL a visitor typed. For most sites the two are the same
 string and the distinction never comes up, but it matters wherever a URL and a file
 differ:
 
 - **Clean URLs.** Write `/about.html`, not `/about`, and `/index.html` for the home
   page. There is no file at `/`, so a `/` pattern matches nothing at all.
 - **Rewrites.** A `200` [rewrite](redirects.md) serves its target file's contents,
   and reuses that file's headers. So the headers for `/article` come from the pattern
-  matching `/content/article.html`. For a [SPA](routing.md#single-page-apps-spa) — where
-  a single `/*` rewrite serves the shell at every client route — this means a
+  matching `/content/article.html`. For a [SPA](routing.md#single-page-apps-spa), where
+  a single `/*` rewrite serves the shell at every client route, this means a
   `Cache-Control` declared for `/index.html` reaches all of them, and a block written
   against a route like `/dashboard/*` matches no file and does nothing.
 - **Redirects.** A `3xx` rule is the one exception: it synthesizes its own response
@@ -51,7 +56,7 @@ differ:
 ## How rules combine
 
 A file can match several blocks at once, and **all matching blocks contribute** their
-headers — patterns don't override each other wholesale. For a single header name:
+headers; patterns don't override each other wholesale. For a single header name:
 
 - Values from different matching blocks are combined into one header, comma-separated
   (per the HTTP spec).
@@ -76,7 +81,7 @@ Unlike other headers, `Content-Type` is single-valued and first-match-wins.
 
 ## No headers are added for you
 
-The canister applies **no default headers** — no `Cache-Control`, no security headers,
+The canister applies **no default headers**: no `Cache-Control`, no security headers,
 no CSP. If you want them, declare them in `_headers`. The only response headers the
 canister manages on its own are the ones tied to how it serves and certifies content:
 `Content-Type`, `Content-Encoding`, `ETag`, `Content-Range` (on large-asset
@@ -92,7 +97,7 @@ A useful baseline to copy and adapt:
   Referrer-Policy: strict-origin-when-cross-origin
   Content-Security-Policy: default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'
 
-# Fingerprinted build assets never change — cache them hard
+# Fingerprinted build assets never change, so cache them hard
 /assets/*
   Cache-Control: public, max-age=31536000, immutable
 
@@ -107,8 +112,8 @@ HTML responses, so don't reuse that name.
 ## Reserved headers
 
 Some headers can't be set in `_headers`. The canister either computes them itself or
-they have no meaning for a certified asset served through the IC HTTP gateway — a
-wrong value would corrupt the response or simply be unverifiable. Rather than silently
+they have no meaning for a certified asset served through the IC HTTP gateway, where
+a wrong value would corrupt the response or simply be unverifiable. Rather than silently
 ignore these (as some CDNs do, which leads to confusing bugs), the sync plugin
 **rejects them at deploy time** with an explanatory error, so you find out
 immediately.
@@ -124,5 +129,5 @@ immediately.
 | `IC-Certificate`, `IC-CertificateExpression` | These carry the response certificate and are canister-managed. |
 | `Location` | A `Location` here wouldn't redirect (the status stays `200`). Use [`_redirects`](redirects.md) instead. |
 
-This list is intentionally conservative and may be relaxed in future releases — it's
+This list is intentionally conservative and may be relaxed in future releases; it's
 easier to allow a header later than to start rejecting one that sites already rely on.