# Agents

This file is both the public agent note for https://life.ayushrai.site/agents.md and the repository guide for coding agents.

## Using the public site

Read https://life.ayushrai.site/llms.txt before calling anything. The homepage returns markdown when the request sends `Accept: text/markdown` or comes from a known AI crawler. `?mode=agent` returns JSON with endpoints and authentication. The sandbox is `GET /api/v1/sandbox/`. Prefer trailing slashes on API paths (`/ask/`, `/api/v1/jobs/`). `POST /api/v1/jobs/` returns `202` with a poll `Location`. Protected paths return 401 with `WWW-Authenticate` until you follow https://life.ayushrai.site/auth.md. Local agent checks: `npm run check:agent`. External discovery blockers are listed in `docs/EXTERNAL_DISCOVERY.md`.

## Editing this repository

LifeOS is Ayush Rai's personal knowledge base and the static site served at https://life.ayushrai.site/.

- `knowledge/` is the source of truth for facts. Prefer updating an entity there, then the generated HTML.
- `sites/` is the public HTML. The homepage is generated by `node scripts/build-home.js` from `knowledge/_system/homepage.yaml` and `knowledge/person/profile.yaml`.
- Agent discovery files (`llms.txt`, `.well-known/`, `api/`, and `discovery/`) describe the public site. Keep them aligned with the pages. Files in `discovery/` are served at root URLs (`/auth.md`, `/openapi.json`, `/pricing.md`, ...) through rewrites in `vercel.json`; add a rewrite when you add one.
- Keep the repository root limited to deploy config, `llms.txt`, `robots.txt`, `sitemap.xml`, `AGENTS.md`, `README.md`, and the agent plugin manifests (`plugin.json`, `mcp.json`).
- Do not invent metrics, audience sizes, street addresses, or employer impact claims.
- Do not use em dashes (U+2014). `npm run qa` fails on them.
- Do not commit `knowledge/github/repositories/expert-o/` or anything matching the secrets rules in `.gitignore`.
- Preview with `npm run local` (Vercel dev on port 3000: middleware, rewrites, and `api/` functions). `npm start` is a plain static server and does not apply rewrites. Vercel serves this repository as static files plus the `api/` functions and `middleware.js`.
- After homepage edits, run `npm run build:home` and commit the generated `sites/www/index.html` and `sites/www/index.md`. There is no Vercel build step that regenerates them.

Humans who open `/` get the homepage HTML (rewritten from `sites/www/`). `/sites/www` permanently redirects to `/`. Agents that send `Accept: text/markdown`, a known bot user agent, or `?mode=agent` get markdown or JSON instead.