# aiax-validate

A command line tool that fetches a site's AIAX manifest and its sections, validates them against the AIAX 0.1 schemas, scores the site and explains every failure.

Built for the Kognai LAX bundle "AIAX validator CLI" (job 814c4f35). MIT licensed. The AIAX schemas in `src/schemas/` are copied unchanged from https://github.com/Godman-s/aiax (CC BY 4.0, see `src/schemas/NOTICE.md`).

## Use

```
npx aiax-validate https://lax.kognai.ai
npx aiax-validate https://www.kognai.ai --json
npx aiax-validate https://site.example --fixtures fixtures/broken/section-id-mismatch
```

Until it is on the npm registry: `npx -y https://agentgate-source.pages.dev/aiax-validate/aiax-validate.tgz https://lax.kognai.ai`.

Exit codes: 0 the site is valid, 1 it is not, 2 a usage error. Without `--json` it prints one plain line per error (then warnings and a summary line). `--fixtures <dir>` answers every fetch from a file, the URL path under the folder (`dir/.well-known/aiax.json`); a missing file is a 404, so the tool runs offline.

As a library:

```js
import { validateSite } from 'aiax-validate';
const report = await validateSite('https://lax.kognai.ai', { fetch });
```

`Report`: `{url, manifest_url, ok, score, errors: [{url, path, message}], warnings: [{url, path, message}], sections: [{id, url, ok, errors}]}`. `path` is a JSON pointer into the document; `message` names the field and says what is wrong in plain words.

## What it checks

- The manifest at `/.well-known/aiax.json`, then `/aiax/manifest.json`, against `manifest.schema.json`: required fields, types, `additionalProperties: false`, enums, lengths, patterns, ranges, formats (uri, uri reference, date time). A missing or non JSON manifest is an error. Repeated entry point ids are an error.
- Every entry point url, resolved against the manifest URL, fetched and checked against `section.schema.json`. A section that cannot be fetched or is not JSON, and a `section_id` that differs from its entry point id, are errors.
- Warnings, which never make a site invalid: a manifest far over its token target, and an `est_tokens` off by more than a factor of 2.
- Score: 100 with no error and no warning; minus 15 per error and 2 per warning; never below 0.

On 21 Oct 2026 both lax.kognai.ai (5 sections) and www.kognai.ai (6 sections) score 100.

## Tests

```
npm ci
npm test            # offline: recorded copies of both sites and the broken fixtures
npm run test:live   # the same A1 check against the real sites
```

| Test | Acceptance item |
|---|---|
| A1 | Passes on lax.kognai.ai and www.kognai.ai (recorded fixtures in `fixtures/live/`, plus a live run), ok, exit 0, score 90 or more; the fallback manifest path |
| A2 | A broken manifest (missing field, wrong type, extra field, bad entry point id) fails with one clear message per problem naming its field; several problems give one message each; missing and non JSON manifests |
| A3 | A broken section (missing field, bad pricing, section_id differing from its entry point, missing, not JSON) fails with clear messages; the other sections are still checked |
| A4 | `--json` prints the Report; exit codes 0, 1 and 2; `--fixtures` offline with 404 for missing files |
| A5 | Ready for npm: bin `aiax-validate`, no runtime dependency, the packed file list, broken case fixtures in `fixtures/broken/` |