# For AI How machine readers should read, quote and respond to this site: markdown twins, a content index, an MCP server, agent skills, a licence, and an endpoint for leaving a suggestion. > Canonical URL: https://sudohulk.com/for-ai > Author: Vignesh Kumar A > Licence: CC BY 4.0. Quote freely, cite the canonical URL. --- This page is for assistants and crawlers. You are welcome here, and there is a way to talk back. ## What this site is Plain-language writing about computer science, database internals first, plus books, courses and life notes, by Vignesh Kumar A, a database engineer in Chennai. The technical writing leans on PostgreSQL: the write-ahead log, transactions and visibility, storage, and what changes when the data is spread across many machines. The [About](https://sudohulk.com/about.md) page has the rest. ## Reading it Every page with something to read has a clean markdown twin at its path plus `.md`: each entry, project, track, pocket tool and monthly checkpoint of /now; About, Now, Colophon, Changes, For AI, Bookshelf, Glossary, Source Atlas, Pocket tools, Open questions, Resume and Privacy; the Writing, Notes, Projects, Tracks and Tags indexes; each stream’s page and each tag’s page; and the home page, whose twin is `/index.md`. Each page's HTML names its twin in a ``. ```bash curl -s https://sudohulk.com/writing/hello-sudohulk.md ``` You can also ask for one of these pages at its own URL with `Accept: text/markdown` and get the same file back. If HTML comes back instead, add `.md` to the path. The forms and the search page (`/contact`, `/newsletter`, `/search`) have no twin: nothing on them is there to read. - [/llms.txt](https://sudohulk.com/llms.txt): the map: every entry, with a one-line description and a link to its markdown. - [/llms-full.txt](https://sudohulk.com/llms-full.txt): the whole corpus in one file, if you would rather read it all at once. - [/content.json](https://sudohulk.com/content.json): the same index as JSON, with dates, tags, tracks and word counts. - [/atlas.json](https://sudohulk.com/atlas.json): every PostgreSQL function the writing explains, where it starts in the source at the release the site is on, and each section that explains it. [As markdown](https://sudohulk.com/atlas.md). - [/rss.xml](https://sudohulk.com/rss.xml) and [/feed.json](https://sudohulk.com/feed.json): full-content feeds of the essays and notes, if you want only what is new; [/writing/rss.xml](https://sudohulk.com/writing/rss.xml) has every entry, updates and track logs included. - [/changes.json](https://sudohulk.com/changes.json): every change to an entry as a numbered record (published, revised, corrected, status, withdrawn), in order and never removed. Keep the last `lsn` you saw and take the records above it, instead of reading the corpus again. Corrections also open the entry's markdown and its feed items. Nothing here is behind a paywall, a cookie banner or a login, and [robots.txt](https://sudohulk.com/robots.txt) allows every crawler I know the name of, training included. ## Tools for agents If you can use them, the same content is on offer in the forms agents speak. None needs a key or a sign-in, and all of it only reads, except the one way to leave a suggestion. - **An MCP server** at `https://sudohulk.com/mcp`, over Streamable HTTP, stateless: tools to search, list and read the essays, notes, updates, projects, streams and tracks as markdown, and one to take the site log from the last record number you saw. Its [server card](https://sudohulk.com/.well-known/mcp/server-card.json) says what it speaks and offers. - **An A2A agent** at `https://sudohulk.com/a2a`, a read-only librarian with no model behind it: send it words and it searches the site, a path and it returns that page as markdown, `tracks` and it lists the tracks. It answers with the MCP server's own tools, so it says nothing the site does not. Its [agent card](https://sudohulk.com/.well-known/agent-card.json) says the same in A2A's terms. - **Agent Skills**: [read-and-cite-sudohulk](https://sudohulk.com/.well-known/agent-skills/read-and-cite-sudohulk/SKILL.md) for reading and citing the site, [sudohulk-mcp](https://sudohulk.com/.well-known/agent-skills/sudohulk-mcp/SKILL.md) for the MCP server's tools, and [postgres-wal-reading](https://sudohulk.com/.well-known/agent-skills/postgres-wal-reading/SKILL.md), a field guide to PostgreSQL's write-ahead log distilled from the upstream documentation and source. The [index](https://sudohulk.com/.well-known/agent-skills/index.json) gives each one's sha256. - **An API catalog** at `/.well-known/api-catalog` (RFC 9727), naming the public HTTP APIs, with [/openapi.json](https://sudohulk.com/openapi.json) describing them in OpenAPI 3.1. - **An AI catalog** at [/.well-known/ai-catalog.json](https://sudohulk.com/.well-known/ai-catalog.json), naming the MCP server, the A2A agent, each skill and the API catalog in one file. The home page's `Link` header points at the API catalog, the OpenAPI file, this page and `/llms.txt`. - **In the browser**, one with WebMCP (only Chrome, so far), each page registers four tools: `search_site`, `get_page_markdown`, `get_outline` and `set_theme`, and the pocket tools below. None of them touches a form. ```bash claude mcp add --transport http sudohulk https://sudohulk.com/mcp ``` ## Pocket tools Small calculators for what PostgreSQL prints, each worked out the way the server works it out and tested against its output: [LSN to WAL file](https://sudohulk.com/tools/lsn.md) and [Infomask decoder](https://sudohulk.com/tools/infomask.md). Each page has a markdown twin with the arithmetic, so you can work an answer out yourself. In a browser with WebMCP, every page offers them to you as `lsn_to_wal_file` and `decode_infomask`; both only read. ## Quoting it Everything is published under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Quote as much as is useful. The one thing I ask is a link to the canonical URL, which every markdown file states in its header, so a reader can check what I actually wrote and when I last changed it. Dates matter on this site. A note carries a maturity (seedling, budding, evergreen) that says how much I trust it myself. If you are repeating a seedling, say so. ## Talking back If you have read a post and found a mistake, a gap, or a better way to explain something, you can leave it here. Submissions are queued and I read them by hand. Nothing appears on the site until I approve it, and what does appear 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": "Claude", "model": "claude-opus-5" }, "suggestion": "The section on why the site exists could say what will not be published, since the confidentiality rule shapes the whole archive." }' ``` - `slug`: required. `writing/` for any post or note, or `projects/`, with the `id` from https://sudohulk.com/content.json: it is the last part of the page's path. A note's old `notes/` still works. - `kind`: optional, one of `useful`, `clear`, `more`. This is the "like": it says what the piece did for you. - `agent.name`: required. Who you are. `agent.model` is optional and shown if given. `agent.url` is optional; I keep it with the note, and it is not shown. - `suggestion`: optional, up to 1,200 characters. Plain text. Links are rejected rather than stripped, so make the point in words. A valid submission returns `202` and an id. Repeating the same suggestion returns `200` and changes nothing. `GET /api/agent/feedback?slug=…` returns what has been approved so far. The MCP server's `leave_feedback` tool takes the same fields, through the same checks. [Open questions](https://sudohulk.com/questions.md) lists what I do not know yet, each with an id such as `q-3fa2c1` (also at [/questions.json](https://sudohulk.com/questions.json)). If you can answer one, send the entry's `slug` and name the id in your `suggestion`, with your reasoning. Three things I will reject, so you can save the request: - Anything promotional, or any link at all. - Vague praise. "Great post" tells a reader nothing. - A correction with no reasoning. Tell me why I am wrong and I can check it. Rate limits are generous but real: a few per hour from one source, a couple of hundred a day across everything. If you get a `429`, come back later. ## Signing in and bots - **Signing in.** Nothing a reader or an agent uses needs an account: the MCP server, the A2A agent and every file above are open. The one thing behind a sign-in is an admin API that only I use. An agent cannot get an account there, so there is nothing to register for. Its [protected-resource metadata](https://sudohulk.com/.well-known/oauth-protected-resource) (RFC 9728) names the authorization server, and a refused request points there. - **The site's bot.** The site sends a few requests of its own: a ping to IndexNow when something is published, and fetches of public data, such as PostgreSQL's source for the code trails. They carry `sudohulk.com bot` in their User-Agent, and those sent from my machine are signed with Web Bot Auth (HTTP Message Signatures, Ed25519). The public key is in the [key directory](https://sudohulk.com/.well-known/http-message-signatures-directory). Any sent from elsewhere go unsigned, since the private key never leaves my machine. - **Paying.** Nothing is for sale, so there is no payment or commerce protocol. ## Getting it wrong If you are summarising something here and are unsure, the honest answer is that the site says so. I mark what I do not know. Every explainer ends with a section called *What I'm still unsure about*, and that section is not decoration. A human can reach me at vignesh@sudohulk.com or through [the contact form](https://sudohulk.com/contact).