Feat/add llm txt (#33)

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Montana <montanawong@gmail.com>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Author: 4 people

.claude/commands/agents.md

@@ -0,0 +1,66 @@
+---
+description: Regenerate the public AGENTS.md routing document, or check whether it is stale
+---
+
+Manage the generated `public/AGENTS.md` — the **public** agent routing document
+served at `<origin>/AGENTS.md`.
+
+Argument: `$ARGUMENTS` — one of `check`, `status`, `force`, or empty.
+
+## Two different files
+
+Get this right before doing anything:
+
+- **`/AGENTS.md`** at the repo root is hand-written, follows the
+  [agents.md](https://agents.md/) spec, and describes how to work *in* this
+  repo. It is in no generator's `outputs`. Never regenerate it.
+- **`public/AGENTS.md`** is generated by `scripts/agents.mjs` and tells external
+  developers' agents how to use the site: routing rules, freshness, network
+  reference, route list.
+
+This command only concerns the second one.
+
+## Normally you do not need this
+
+`githooks/post-commit` runs it automatically when a commit message contains
+`agents.md`, and on any added, deleted, or renamed route file:
+
+```sh
+git commit -m "docs: refresh agents.md"
+```
+
+## What to do
+
+**No argument** — regenerate only if the route tree or config changed:
+
+```sh
+git diff --name-only HEAD -- src/app app llms.config.mjs
+node scripts/agents.mjs
+git diff --stat public/AGENTS.md
+```
+
+**`force`** — regenerate regardless.
+
+**`check`** — report staleness and validation failures without writing; exit 1
+if stale:
+
+```sh
+node scripts/agents.mjs --check
+```
+
+**`status`** — size, mtime, route count, config. Never fails.
+
+## When reviewing the diff
+
+Check these specifically, because they are the parts that would be damaging
+rather than merely wrong:
+
+- Each chain ID sits in the same `### ` block as its own RPC URL. A transposed
+  `8453` / `84532` reads perfectly fine and would have an agent signing against
+  the wrong network. There is a test for this; if it is failing, do not
+  work around it.
+- Ephemeral networks publish a note about where to read live values, not a
+  fabricated chain ID.
+- The routing rules still say which source wins on a conflict.
+
+To change content, edit `llms.config.mjs` — not the generated file.

.claude/commands/llms.md

@@ -0,0 +1,69 @@
+---
+description: Regenerate llms.txt and llms-full.txt, or check whether they are stale
+---
+
+Manage the generated `public/llms.txt` and `public/llms-full.txt`.
+
+Argument: `$ARGUMENTS` — one of `check`, `status`, `install`, or empty.
+
+## Normally you do not need this
+
+`githooks/post-commit` runs `scripts/llms.mjs` automatically when a commit
+message contains `llms.txt` (case-insensitive), and when a route file is added,
+deleted, or renamed. So the day-to-day flow is just:
+
+```sh
+git commit -m "feat: add a snapshots page; updates llms.txt"
+```
+
+Use `/llms` when you want to preview output before committing, regenerate
+without committing, or set the hook up on a fresh clone.
+
+## What to do
+
+**No argument** — regenerate and show what changed:
+
+```sh
+node scripts/llms.mjs
+git diff --stat public/llms.txt public/llms-full.txt
+```
+
+Report which files changed and summarise the diff. If nothing changed, say so
+plainly rather than implying work happened.
+
+**`check`** — report staleness without writing. Exit 1 means stale, invalid, or
+sitemap drift:
+
+```sh
+node scripts/llms.mjs --check
+```
+
+Relay the metadata-source breakdown. Any count under `metadata fallback` means
+those routes have no usable `export const metadata` and are being listed with a
+humanized slug — name them and suggest either adding metadata to the page or a
+`routes` override in `llms.config.mjs`.
+
+**`status`** — sizes, mtimes, config, route count, drift. Never fails:
+
+```sh
+node scripts/llms.mjs --status
+```
+
+**`install`** — set up the hook on this clone:
+
+```sh
+./githooks/install.sh
+```
+
+Then confirm it is repo-scoped: `git config --global --get core.hooksPath`
+should print nothing.
+
+## Do not
+
+- Edit `public/llms.txt` or the autogen region of `public/llms-full.txt` by
+  hand. Change the page's `export const metadata` or `llms.config.mjs` instead.
+- Touch the `<!-- LLMS_EXTRAS_START -->` … `<!-- LLMS_EXTRAS_END -->` region
+  unless the user asked for a prose change. That region is hand-written and
+  preserved verbatim across regenerations.
+- Confuse `public/AGENTS.md` (generated) with `/AGENTS.md` at the repo root
+  (hand-written, never generated).

AGENTS.md

@@ -0,0 +1,70 @@
+# AGENTS.md
+
+Instructions for coding agents working in this repository, per the
+[agents.md](https://agents.md/) convention. Agents read the nearest AGENTS.md in
+the directory tree, so a package in a monorepo can add its own.
+
+> This file is hand-written and is never generated. The **public** agent routing
+> document — the one served at `/AGENTS.md` for external developers and their
+> agents — is `public/AGENTS.md`, generated by `scripts/agents.mjs`. Do not edit
+> that one by hand; your changes will be overwritten on the next commit that
+> mentions `agents.md`.
+
+## Setup commands
+
+- Install deps: `npm install`
+- Start dev server: `npm run dev`
+- Build: `npm run build`
+- Install git hooks (once per clone): `./githooks/install.sh`
+
+## Generated files — do not edit
+
+These are written by `scripts/llms.mjs` and `scripts/agents.mjs`:
+
+- `public/llms.txt`
+- `public/llms-full.txt`
+- `public/AGENTS.md`
+
+To change their contents, edit the source instead:
+
+- **A page's title or description** → that route's `export const metadata` in
+  its `page.tsx`. This is the same metadata Next uses for SEO, so there is one
+  source of truth rather than two.
+- **Ordering, sections, network reference, routing rules, freshness** →
+  `llms.config.mjs`.
+- **Hand-written prose inside `llms-full.txt`** → edit between the
+  `<!-- LLMS_EXTRAS_START -->` and `<!-- LLMS_EXTRAS_END -->` markers directly
+  in `public/llms-full.txt`. That region is preserved verbatim across
+  regenerations; everything outside it is not.
+
+Check whether they are current: `npm run llms -- --check`
+
+## Regenerating
+
+Include `llms.txt` or `agents.md` in your commit message and the post-commit
+hook regenerates and creates one follow-up commit:
+
+```
+git commit -m "feat: add snapshots page; updates llms.txt"
+```
+
+Adding, deleting, or renaming a `page.tsx` triggers it automatically. To opt out
+of a single commit, use `SKIP_DOCS_HOOK=1` or put `[skip-docs]` in the message.
+
+## Code style
+
+<!-- Replace with this project's real conventions. -->
+
+- TypeScript strict mode
+- Follow the existing formatter config; do not reformat unrelated files
+
+## Testing
+
+- Run the llms-kit suite: `node --test tests/`
+- Include liveness checks against the deployed site: `LLMS_LIVE=1 node --test tests/`
+
+## Pull requests
+
+- Keep the generated-file commit separate from your own work — the hook already
+  does this for you. Do not squash it away; it is what makes the generated diff
+  reviewable.

README.md

@@ -22,6 +22,8 @@ npm run dev                  # http://localhost:3000
 - `npm run lint` — eslint (next/core-web-vitals)
 - `npm run typecheck` — `tsc --noEmit`
 - `npm test` — vitest
+- `npm run llms` / `npm run agents` — regenerate the agent index files
+- `npm run docs:check` — verify the agent index is current (CI gate)
 
 ## Structure
 
@@ -39,6 +41,24 @@ See `.env.example`. `NEXT_PUBLIC_VIBENET_*` are public URLs. The snapshots API
 needs Cloudflare R2 credentials (`BASE_*_R2_*`), which are secrets set in the
 Vercel project settings.
 
+## Agent index (llms.txt / AGENTS.md)
+
+`public/llms.txt`, `public/llms-full.txt`, and `public/AGENTS.md` are generated
+from the route tree by the scripts in `scripts/`. A `post-commit` git hook keeps
+them fresh: mention `llms.txt` or `agents.md` in a commit message (or add/rename
+a route file) and the hook regenerates them in a follow-up commit.
+
+The hook is off until you enable it in your clone — `core.hooksPath` is a local
+git setting and can't be committed, so each clone opts in once:
+
+```bash
+./githooks/install.sh   # scope: --local; never touches global/system git config
+```
+
+Bypass a single commit with `SKIP_DOCS_HOOK=1 git commit …` or a `[skip-docs]`
+message. To disable: `./githooks/uninstall.sh`. See `githooks/README.md` for
+details.
+
 ## Deployment
 
 Deployed on Vercel. Push to the default branch to ship; pull requests get