(LLM-authored slop README)

clank-right

One Vento template for the AGENTS.md of many repositories. The template lives here; what each repository wants from it lives in a comment at the top of that repository's AGENTS.md, next to the sections that are the repository's own.

Its code conventions also go into the account-wide instructions for claude.ai and chatgpt.com; see Chatbots.

Usage

Put bin/ on your PATH (or run pnpm clank-right ... from this directory).

clank-right check [--diff] [DIR...]
clank-right update [--commit-existing-changes MESSAGE] [DIR...]
clank-right chatbots

check reports which repositories' AGENTS.md differ from what the template generates, or match it but aren't committed; --diff shows how. update regenerates each differing AGENTS.md and commits it, alone: other staged changes stay staged, and if AGENTS.md itself already has uncommitted changes, that repository is skipped so nothing gets committed unreviewed. Once you've reviewed them, update --commit-existing-changes MESSAGE commits them first, alone, with MESSAGE, and the regeneration follows as its own commit. If git refuses a commit (a hook, signing), the regenerated file stays in place and staged, and both commands report it as not committed until you commit it.

Without DIRs, both commands go through every repository listed in ~/.config/clank-right/projects.txt ($XDG_CONFIG_HOME is honoured when set). clank-right update . regenerates the repository you're in.

What a managed AGENTS.md looks like

<!-- clank-right
# This file is generated by `clank-right` ...
# ... (the tool writes these lines; they explain exactly this)

languages    = ["typescript", "svelte", "sql"]
effection    = true
web_design   = "2010"
color_scheme = "dark"
-->

# Environment
...
# Thoughts for when there is programming involved
...
# Project map            <- the repository's own sections go here
...
# After making changes
...

The header is an HTML comment whose leading # lines belong to the tool and whose remaining lines are the repository's options, in TOML. Everything after the header is H1 sections. Sections whose heading the template emits are regenerated from the template; any other section is the repository's own and is kept verbatim, in order, between "Thoughts for when there is programming involved" and "After making changes". (check and update tell you when a template-owned section is about to disappear because the options no longer produce it, or because the template renamed it.)

Options

Every option has a default, so an empty header is valid.

Option	Default	Effect
languages	[]	typescript/javascript/svelte select the Node sections; svelte picks svelte-check; c/cpp/csharp add the brace rules; sql adds the DDL paragraph. Also rust, go, python, nix, zsh.
package_manager	"pnpm"	"bun" tells agents to use bun, not npm or pnpm, in the Node code; "pnpm" tells them to use pnpm, not npm.
effection	false	Lists effection under "Libraries to use".
libraries_extra	[]	More "Libraries to use" items, each as the text after the bullet, e.g. ["`ventojs` for templating."].
web_design	"none"	"2010" for the standard section; "custom" keeps the repository's own # Web design section.
color_scheme	"both"	"light", "dark", or "both", for the "2010" web design.
sandbox_note	""	Appended to the sandbox hostname bullet, e.g. "you're unable to hit production".
tools_extra	[]	Installed tools worth mentioning, e.g. ["ffmpeg"]; listed after uv.
checks	[]	Steps before committing, in order: "sqlx" (./make-sqlx-data), "pnpm" (lint/check/test; needs package_manager = "pnpm"), "cargo" (cargo test).
commit_style	"template"	"nixpkgs" replaces the commit template with nixpkgs-style commits.
extra	{}	A table of markdown (no # headings) appended at named points: environment, code_conventions, web_design (for the "2010" design only; a "custom" section already is the project's), checks.

Facts that change over time (model names, the NixOS version, the curl-impersonate binary) are set at the top of templates/AGENTS.md.vto.

Adding a repository

1. Put a header at the top of its AGENTS.md (or create the file with just a header).
2. Add the repository's path to ~/.config/clank-right/projects.txt, one per line; ~ is your home directory and # starts a comment line.
3. Run clank-right update . --commit-existing-changes "AGENTS.md: add clank-right header" in it.

Chatbots

templates/chatbot.vto holds the account-wide instructions for claude.ai and chatgpt.com, ending with templates/code_conventions.vto: the rules under every AGENTS.md's "Code conventions", with the Node and brace rules on. clank-right chatbots renders it into chatbots/claude.md (where the template's claude is true) and chatbots/chatgpt.md in this checkout. Neither site has an API for these settings, so paste each file by hand: claude.ai's Settings → "Instructions for Claude", and chatgpt.com's Settings → Personalization → Custom instructions. The latter takes at most 5,000 characters on the paid plans, and clank-right chatbots refuses to write more.

The files are committed, so their history tells you when to paste again. pnpm test fails while they don't match the templates.

Changing the template

Edit the templates in templates/, run clank-right chatbots, and commit the templates together with any change it made to chatbots/, which is then yours to paste. Then clank-right check --diff shows what changes where, and clank-right update commits it everywhere.

To rename a heading that the template emits, rename it in TEMPLATE_HEADINGS in src/sections.ts too, and add the old name to FORMER_TEMPLATE_HEADINGS there. Otherwise every file still under the old heading keeps that section as its own, next to the same text under the new one.

Development

pnpm lint
pnpm check
pnpm test