# docs.shabinder.in — instructions for LLMs

Personal docs and research hub for Shabinder. Private GitHub repo
`Shabinder/docs.shabinder.in`, branch `main`. Served from Cloudflare Pages at
https://docs.shabinder.in.

**Pages are private by default.** A page is readable only by people named in a
Cloudflare Access policy unless it is explicitly marked public. Never mark a
page public unless the human asked for it in that turn.

## Publish a page

1. **Pick a section and slug.** Sections: `research`, `plans`, `reports`,
   `runbooks`. Slug is lowercase kebab-case, e.g. `redpanda-cloud-topics-wedge`.

2. **Write one self-contained `index.html`** to `public/<section>/<slug>/index.html`.
   It serves at `https://docs.shabinder.in/<section>/<slug>/`. Keep any assets
   (images, data files) inside that same folder and reference them relatively.

3. **Link the site theme** so the page looks like it belongs here:

   ```html
   <link rel="stylesheet" href="/theme/theme.css">
   ```

   Then style against the CSS custom properties it defines rather than
   hardcoding colours: `--paper`, `--surface`, `--surface-2`, `--rule`, `--ink`,
   `--ink-2`, `--ink-3`, `--accent`, `--accent-ink`, `--accent-wash`, `--good`,
   `--warn`, `--bad`; type with `--font-sans`, `--font-serif`, `--font-mono` and
   the `--step--1` … `--step-3` scale; spacing with `--sp-1` … `--sp-8`. Dark
   mode comes free if you use the tokens and set nothing literal. Your page
   keeps its own layout and components — only the palette and type are shared.
   `docs/TEMPLATE.html` is a working starting point.

4. **Register it.** Add one entry to `registry.json` under `docs`:

   ```json
   {
     "path": "research/redpanda-cloud-topics-wedge",
     "title": "Why Cloud Topics stopped serving historical reads",
     "summary": "One sentence a reader can decide from.",
     "visibility": "private",
     "date": "2026-09-20",
     "tags": ["redpanda", "incident"],
     "kind": "artifact"
   }
   ```

   `visibility` is `"private"` or `"public"` and nothing else. **Default to
   `"private"`.** An unregistered folder fails the build on purpose: content
   served with no visibility rule is a leak.

5. **Commit both files together** — the HTML and the registry entry. The build
   validates the registry before it builds, so a missing entry, a dead path or
   a bad visibility value stops the deploy rather than shipping.

## Upload without cloning

Use `gh` if it is authenticated (it is, for this human):

```sh
gh api repos/Shabinder/docs.shabinder.in/contents/public/research/<slug>/index.html \
  -X PUT -f message="add <slug>" -f branch=main \
  -f content="$(base64 < ./index.html | tr -d '\n')"
```

Updating an existing file needs its current blob sha: GET the same path first,
then pass `-f sha="<sha>"`. Registry edits must read the current
`registry.json`, add the entry, and PUT it back with its sha — never overwrite
it blind, you will drop other people's entries.

Prefer a local clone plus `git push` when you already have one. It is one
operation instead of three and it cannot race.

## Making a page public

Only when asked. Change that doc's `visibility` to `"public"`, then the human
(or CI) runs:

```sh
npm run access:plan    # shows what would change
npm run access:apply   # writes it
```

Until Access is synced, a page marked public in the registry is still gated.
The registry is intent; Cloudflare Access is enforcement.

## Rules

- Never commit tokens, credentials, connection strings, or personal data.
- Never edit another page's folder, or `public/theme/`, or files under `src/`
  unless the human asked for a site change rather than a page.
- Never set `site.default_visibility` to `public`.
- Tell the human the URL when you are done, and say whether it is public or private.