---
name: read-and-cite-sudohulk
description: Read sudohulk.com, Vignesh Kumar A's site on computer science (databases first), as clean markdown instead of HTML, find pages through llms.txt and content.json, and quote and cite it correctly under CC BY 4.0. Use when a task involves reading, summarising or quoting anything published on sudohulk.com.
license: CC-BY-4.0
---

# Reading and citing sudohulk.com

sudohulk.com is the personal site of Vignesh Kumar A, a database engineer in Chennai who works
on database internals. He writes down what he learns in plain language: computer science,
databases first (PostgreSQL internals: the write-ahead log, transactions and visibility,
storage, distributed execution), plus books, courses and life. Everything on it is public, with
no login, paywall or cookie wall, and it is published under CC BY 4.0.

## 1. Ask for markdown, not HTML

Every page with something to read has a markdown twin at its path plus `.md`. The home page's is
`/index.md`.

| Page | Its markdown |
|---|---|
| `https://sudohulk.com/` | `https://sudohulk.com/index.md` |
| an entry (essay, note, update, photos), `/writing/<id>` | `/writing/<id>.md` |
| a project or a track, `/projects/<id>`, `/tracks/<id>` | `/projects/<id>.md`, `/tracks/<id>.md` |
| `/about`, `/now`, `/colophon`, `/for-ai`, `/bookshelf`, `/resume`, `/privacy` | the same path plus `.md` |
| the indexes: `/writing`, `/notes`, `/projects`, `/tracks`, `/tags` | the same path plus `.md` |
| a stream's page, `/tech`, `/books`, `/learning`, `/places`, `/life`, `/meta` | `/tech.md` and so on: every entry in it |
| a stream's later page, `/tech/2` | `/tech/2.md` |
| a tag's page, `/tags/<tag>` | `/tags/<tag>.md` |

```bash
curl -s https://sudohulk.com/writing/hello-sudohulk.md
curl -s -H 'Accept: text/markdown' https://sudohulk.com/about
```

- Every entry lives at `/writing/<id>`, whatever its type and stream. `/notes` is only an index
  of the notes, and a stream's page (`/tech` is computer science, databases first) of its entries.
- Sending `Accept: text/markdown` to a page's own URL returns its twin too. If the answer is
  still `text/html`, add `.md` to the path yourself: the twin is always there.
- A page's HTML names its twin in `<link rel="alternate" type="text/markdown">`. A page without
  that link (search, contact, the newsletter form) has no twin: read its HTML.
- Drafts and archived entries have no twin and are in no index. Do not guess URLs; a 404 means
  the page is not published.

## 2. Find what to read

- `https://sudohulk.com/llms.txt`: the map. Every listed entry, track and project, one line
  each, linked by its twin, in sections by stream.
- `https://sudohulk.com/llms-full.txt`: every entry's markdown in one file. Use it when you need
  most of the site; otherwise fetch single twins.
- `https://sudohulk.com/content.json`: the same index as JSON. Each item has `type` (`essay`,
  `note`, `update`, `photos` or `project`), `id`, `title`, `description`, `url` (the canonical
  page), `markdown` (its twin) and `tags`, and when they apply `stream`, `maturity`, `track`,
  `place`, `published`, `updated`, `status`, `minutes`, `words` and `format`. Its `streams` list
  says what each stream covers, and its `site` object lists the other machine-readable endpoints.
- Feeds, for what is new: `/rss.xml` and `/feed.json` (essays and notes), `/writing/rss.xml`
  (everything), `/<stream>/rss.xml` (one stream), `/notes/rss.xml`, `/tracks/rss.xml`.
- If you can use MCP, `https://sudohulk.com/mcp` searches and reads the same content as tools.
  The skill `sudohulk-mcp` covers it:
  `https://sudohulk.com/.well-known/agent-skills/sudohulk-mcp/SKILL.md`.

## 3. Read the header first

Every twin opens with the page's title and one-line description, then a short plain-text header
in a blockquote, then `---` and the text:

```markdown
# <title>

<one-line description>

> Canonical URL: https://sudohulk.com/writing/<id>
> Published: 2026-09-21
> Updated: 2026-09-24
> Status: budding
> Series: <series title> (part 2)
> Tags: postgresql
> Reading time: 6 min
> Author: Vignesh Kumar A <vignesh@sudohulk.com>
> Licence: CC BY 4.0. Quote freely, cite the canonical URL.

---
```

Lines appear only when they apply.

- **Canonical URL** is the page to cite. Never cite the `.md` URL or a feed.
- **Published** and **Updated** are the dates. For a note, Published is when it was first written
  and Updated when it was last revised.
- **Status**, on a note, is how far he trusts it himself: `seedling` (just planted, may be wrong),
  `budding` (checked once, the structure holds) or `evergreen` (he would defend it). On a project,
  it is where the project stands.
- **Series** or **Track** says the entry belongs to a longer run; the track's own twin has the
  rest.
- **Contains the site's own component tags** means the text has tags such as `<Callout>`.
  Read them as asides.

## 4. Quote and cite

- Quote as much as is useful. The licence is CC BY 4.0: credit the author and link the canonical
  URL.
- A good citation: *Vignesh Kumar A, "\<title\>", sudohulk.com, \<Updated, or else Published,
  date\>, \<canonical URL\>*.
- If you repeat a claim from a `seedling` note, say it is an early note.
- Many explainers end with a section called *What I'm still unsure about*. Those are open
  questions, not conclusions: do not present them as settled.
- Say what the page says, not more. If the site does not answer a question, say so rather than
  filling the gap in his name.
- Quote code and output as written. Where a post links PostgreSQL source, it is pinned to a
  release; name the release when you repeat it.

## 5. Leave a correction or suggestion

If you read a post and found a mistake, a gap or a clearer way to say something, you can leave it.
A human reads every submission; nothing appears on the site until he approves it, and what does
is labelled as machine-written and shown unedited.

```bash
curl -X POST https://sudohulk.com/api/agent/feedback \
  -H 'content-type: application/json' \
  -d '{
    "slug": "writing/hello-sudohulk",
    "kind": "clear",
    "agent": { "name": "<your name>", "model": "<your model>" },
    "suggestion": "What would improve, and why, in plain words."
  }'
```

- `slug`: required. `writing/<id>` for a post or a note, `projects/<id>` for a project, with the
  `id` from `content.json`.
- `kind`: optional, one of `useful`, `clear`, `more`: what the piece did for you.
- `agent.name`: required, who you are. `agent.model` and an https `agent.url` are optional.
- `suggestion`: optional, 20 to 1,200 characters of plain text. Send a `kind`, a `suggestion` or
  both.
- A suggestion with any link in it is refused, not stripped. He also turns down vague praise and a
  correction with no reasoning: say why, so it can be checked.
- `202` means queued and `200` that you sent the same thing before and nothing changed. `400`
  says what to fix, `404` that the slug is not a listed page, and `429` to come back later: the
  limits are five an hour from one source and twenty a day on one page.
- `GET https://sudohulk.com/api/agent/feedback?slug=writing/<id>` returns what has been approved
  for a page.

The MCP server's `leave_feedback` tool does the same, through the same checks.

## Etiquette

- Fetch what you need. The twins and indexes are static files, so there is no reason to crawl the
  HTML.
- `robots.txt` allows search, answering from the content, and training:
  `Content-Signal: search=yes, ai-input=yes, ai-train=yes`.
- `https://sudohulk.com/for-ai` says all of this for people too, and how to reach him.