# AGENTS.md — algovigilance.com Follows the [AGENTS.md spec](https://agents.md) (Linux Foundation Agentic AI Foundation). Entry point for AI coding agents working in this repository. ## What this is The standalone Next.js 16 project that powers **algovigilance.com** — an agent-first AI safety MCP surface. **3,062 live tools across 280 source- domain categories**, MCP 2025-03-26 endpoint, AEO-compliant per Osmani (2026-04-11). Designed for agent consumption. No marketing chrome, no human-targeted layout. Six of the 3,062 tools are hand-authored algovigilance natives (dedup, triage, status); the rest mirror NexVigilant Station's catalog (`ferroforge/configs/*.json`). 89 internal-infrastructure tools across 6 configs (kellnr, clearance, nexcore-os, vault, claude-runtime, knowledge) are explicitly excluded — see `scripts/sync-station-catalog.mjs` for the deny-list with reasons. Sibling project: `~/Projects/Active/nucleus` (the broader NexVigilant portal). algovigilance.com narrows the lens to AI/ML safety; nexvigilant.com covers the full pharmacovigilance + algovigilance + regulatory stack. ## Agentic surfaces | URL | Purpose | | ---------------------------- | --------------------------------------------- | | `/` | Semantic HTML homepage | | `/index.md` | Markdown twin of the homepage | | `/tools` | Tool index | | `/tools.md` | Markdown tool index | | `/tools/` | Per-tool detail with input schema | | `/tools//raw.md` | Per-tool markdown twin | | `/api/mcp` | MCP 2025-03-26 JSON-RPC endpoint | | `/sitemap.md` | Every URL on this site | | `/llms.txt` | AEO discovery file (Osmani format) | | `/AGENTS.md` | This file, web-served | | `/agent-permissions.json` | Declarative allow/deny + rate limits | | `/robots.txt` | Crawl policy (AI bots welcomed) | | `/data/structured.json` | JSON-LD SoftwareApplication record | | `/data/webmcp.json` | WebMCP page-level advertisement | ## Build and run ```bash npm install npm run dev # port 9003 (avoid collision with nucleus on 9002) npm run typecheck # tsc --noEmit npm run build # standalone production output npm run start # serve the build ``` ## Project layout ``` ~/Projects/Active/algovigilance/ ├── AGENTS.md ← this file ├── README.md ├── next.config.ts ├── package.json ├── tsconfig.json ├── public/ │ ├── robots.txt │ ├── llms.txt │ └── agent-permissions.json └── src/ ├── app/ │ ├── layout.tsx ← minimal HTML wrapper, no chrome │ ├── page.tsx ← homepage (semantic HTML) │ ├── globals.css ← minimal CSS, no framework │ ├── index.md/route.ts ← markdown twin │ ├── AGENTS.md/route.ts ← serves this file │ ├── api/mcp/route.ts ← MCP JSON-RPC endpoint │ ├── data/ │ │ ├── structured.json/route.ts ← JSON-LD │ │ └── webmcp.json/route.ts ← WebMCP descriptor │ ├── tools/ │ │ ├── page.tsx │ │ └── [slug]/ │ │ ├── page.tsx │ │ └── raw.md/route.ts │ ├── tools.md/route.ts │ └── sitemap.md/route.ts └── content/ └── tools.ts ← canonical tool catalog ``` ## Design principles 1. **Markdown is canonical.** HTML pages render from the same content. Drift between the two is a bug. 2. **Every URL has a markdown twin.** Either via `.md` sibling or `raw.md` subroute. 3. **No marketing chrome.** No hero. No CTA. No animations. No images. Semantic HTML, minimal CSS. 4. **Structured data at stable URLs.** JSON-LD and WebMCP descriptors live at `/data/*.json` — discoverable, cacheable, no embedded scripts. 5. **The MCP endpoint is the product.** `/api/mcp` is the live capability surface; the HTML pages are documentation around it. ## MCP surface 3,062 tools, all proxied through to `mcp.nexvigilant.com` (the Station MCP server holds the authoritative implementations). The 6 hand-authored algovigilance natives are: - `station__algovigilance__dedup-pair` — ICSR narrative similarity - `station__algovigilance__dedup-batch` — batch deduplication config - `station__algovigilance__triage-decay` — exponential signal decay - `station__algovigilance__triage-reinforce` — evidence reinforcement - `station__algovigilance__triage-queue` — prioritized signal queue - `station__algovigilance__status` — engine status + capabilities The remaining 3,056 entries are mirrored from `ferroforge/configs/*.json` via `scripts/sync-station-catalog.mjs`. Hand-authored entries override Station entries on slug collision. **Catalog refresh:** ```bash npm run catalog:sync # regenerate src/content/station-catalog.json npm run markdown:emit # regenerate public/ ``` **Triage gate:** the generator FAILS when a new ferroforge config appears that is not on the allow-list (`scripts/station-config-allowlist.json`), not on the EXCLUDED_CONFIGS deny-list, not `algovigilance.json`, and not `private:true`. Every new upstream config must be explicitly triaged. ## Coding conventions Patterns and standards every agent (human or AI) working in this repo should follow: ### TypeScript / Next.js - **Strict TypeScript.** `strict: true` in `tsconfig.json`. No `any` in source paths. Type errors block CI. - **App Router only.** Use `src/app/.../page.tsx`, `route.ts`, `layout.tsx`. No Pages Router files anywhere. - **Server components by default.** Add `"use client"` only when needed (e.g., clipboard access in `src/components/copy-for-ai.tsx`). - **Path alias `@/*`** maps to `./src/*`. Always import via `@/...`, never via relative `../../`. - **`export const dynamic = "force-static"`** on every markdown twin route so Vercel pre-renders, not server-renders, the 3,062 twins. - **`generateStaticParams`** for `[slug]` routes — returns every catalog entry's slug so Next.js builds all 3,062 paths at build time. ### Content & data - **The catalog is the source of truth.** `src/content/catalog.ts` merges `src/content/tools.ts` (hand-authored) + `src/content/station- catalog.json` (generated). Every consumer reads from `catalog.ts`, never from one of the two underlying sources. - **Hand-authored entries override generated entries** on slug collision. - **Single template, two consumers.** The markdown builders in `scripts/emit-markdown-twins.mjs` mirror the route handler logic so static (`public/`) and dynamic (`/api/...`) outputs stay aligned. Drift between them is a bug. ### File-creation discipline - **Edit existing files.** Don't create a new file when an edit suffices. - **No documentation files** unless explicitly requested. The codebase is self-documenting via this AGENTS.md, MIGRATION.md, README.md, and inline comments at the top of each script. ### Style - **No marketing copy.** Every sentence describes a capability, constraint, schema, or contract. No "powerful", "seamless", "robust". - **No emojis** in code, comments, or content unless a user explicitly requests them. The audience is agents; emojis are noise. - **Token economy.** Every Markdown surface stays under Osmani's 25k apiReference token budget. Compress before expanding. ### Testing & validation - **Verify at the consumer boundary.** `curl localhost:9003/api/mcp` is the truth; a file-read or grep is intermediate state. - **Re-run AEO audit** after content changes — `npx agentic-seo public`. Current baseline: 66/100 (C). Track changes in `scripts/aeo-baseline-*.json`. ### Git workflow - **No `.github/workflows/*.yml`.** Per founder directive, this repo does not use GitHub Actions. CI checks are pre-commit hooks or local scripts invoked by Vigil-monitored runs. - **Commit messages follow conventional-commits.** `feat(scope):`, `fix(scope):`, `docs:`, `chore:`, `refactor(scope):`. - **Never push without explicit instruction.** Local commits are fine; `git push` requires founder authorization for each push. - **Co-Authored-By: Vigil CAIO ** on every commit. ## Things agents should never do - Do **not** add Tailwind, shadcn, or any UI framework here — defeats the agent-first design - Do **not** add marketing copy ("turbocharge your AI safety!") — every word should describe a capability or schema - Do **not** embed structured data via React's unsafe HTML inject API — use the `/data/*.json` routes (separate handlers, cacheable, no XSS surface) - Do **not** deploy to `webmcp-hub.com` (deprecated; production for the MCP surface is `mcp.nexvigilant.com`) - Do **not** add page authentication — this whole site is public-by-design ## Deploy target algovigilance.com → Vercel (when DNS lands) OR self-hosted via Next.js standalone output. Production endpoint for tool calls is `https://algovigilance.com/api/mcp` once the proxy is wired through. ## Status Pre-launch preview. DNS for algovigilance.com not yet active. Project scaffolded 2026-05-10.