CLAUDE.md

Project Overview

@canonry/agent-readiness — an open-source website agent readiness audit engine and single umbrella Claude Code / ClawHub skill. Scores how well AI agents and answer engines can reach, read, and cite a site across 16 factors. Formerly @canonry/aeo-audit (and @ainyc/aeo-audit before that); the CHANGELOG keeps the old names in past entries.

Website: https://canonry.ai

Tech Stack

• Language: TypeScript (ESM)
• Runtime: Node.js >= 20
• Package manager: pnpm
• HTML parsing: Cheerio
• Build: TypeScript compiler to dist/
• Typecheck: tsc --noEmit
• Test runner: tsx --test
• Linter: ESLint v9 flat config

Commands

pnpm install    # Install dependencies
pnpm run typecheck  # Static typecheck
pnpm run build      # Compile src/*.ts to dist/
pnpm test           # Run all tests
pnpm lint           # Run linter

Key Files

src/
  index.ts           # Main entry: runAgentReadinessAudit(url, options)
  scoring.ts         # Factor definitions, weights, score calculation
  fetch-page.ts      # URL fetching with SSRF protection
  errors.ts          # AgentReadinessError class
  cli.ts             # CLI argument parsing
  formatters/        # json, markdown, text output formatters
  analyzers/         # Per-factor analyzer modules (16 core + 2 optional) plus shared helpers.ts
  types.ts           # Shared audit/report TypeScript types
dist/                # Compiled publishable ESM output
bin/
  agent-readiness.js # CLI entry point -> dist/cli.js
skills/agent-readiness/ # Single umbrella Claude Code / ClawHub skill
test/                # Unit and integration tests

Architecture

• Each analyzer receives a context object { $, html, url, headers, auxiliary, structuredData, textContent, pageTitle } and returns { score, findings, recommendations }
• Scores are weighted and normalized in scoring.ts. Weights are RELATIVE and do NOT sum to 100 (the core set sums to 111); the score divides by the actual total of the factors it scored. Each factor carries sharePct, its real share of the score. Never present weight as a percentage
• A factor an analyzer reports applicable: false for is excluded from the score entirely, weight and all (factorApplies in scoring.ts), so a page is not marked down for lacking something it has no reason to have
• Geographic signals is optional (excluded by default); when included, weights renormalize
• The --factors flag allows running a subset of analyzers
• SSRF protection blocks private IPs and hostnames in fetch-page.ts
• The crawler's network identity (User-Agent AINYC-AEO-Audit/1.0 in fetch-page.ts, robots.txt token ainyc-aeo-audit in crawl.ts) is deliberately unchanged across package renames. Sites may have robots.txt rules for it, and Canonry drops traffic with that User-Agent from client traffic reports. Never rename it as part of a branding change
• Published entrypoints resolve to compiled dist/ output; run pnpm run build before local CLI smoke tests

Code Conventions

• Functional style, no classes except AgentReadinessError
• Always use clampScore() for score calculations
• Findings types: found, missing, info, timeout, unreachable
• Unused vars starting with _ are ignored by ESLint

Documentation

Any change to user-visible CLI surface must update all three of these in the same change:

1. printHelp() in src/cli.ts — Options list and Examples block
2. docs/cli.md — the relevant mode section, the Flag reference table, and the Exit codes section (flags, examples, and any defaults). The root README.md only carries a handful of headline examples; the full CLI surface lives in docs/cli.md.
3. skills/agent-readiness/SKILL.md — Examples and the relevant mode section (e.g. ### Sitemap Mode)

This applies to:

• Adding, renaming, or removing a flag
• Changing a default value (e.g. sitemap --limit default of 200) — the default must be stated in the help string, docs/cli.md, and SKILL.md
• Adding a new CLI mode (e.g. --sitemap) — document flags, defaults, exit-code behavior, and an example invocation in all three places
• Changing exit-code semantics or output format options

Before opening a PR that touches src/cli.ts, grep docs/cli.md and SKILL.md for the affected flag name to confirm everything still matches.

The README's terminal image (docs/images/readme/hero.svg) is rendered from a real audit of test/fixtures/site. When a change alters the text report (src/formatters/text.ts, factor names, or scoring of the sample site), regenerate it with pnpm run build && node scripts/render-readme-hero.mjs.

Versioning

Follows semver. Bump version in package.json on every change that ships:

• Patch (1.3.x) — bug fixes, scoring corrections, internal refactors with no API change
• Minor (1.x.0) — new analyzers, new CLI flags, new exported helpers (backwards-compatible)
• Major (x.0.0) — breaking changes to the public API or scoring weights that would change existing audit results

The ClawHub skill version must match package.json.

ClawHub Publishing

CI publishes the skill; there is no manual step. When a push to main changes the version in package.json, .github/workflows/publish.yml publishes the npm package and then runs clawhub publish skills/agent-readiness with that version and the commit subject as the changelog. A skills/agent-readiness/SKILL.md change therefore ships with the next version bump.

Publishing by hand

Only needed if the workflow failed, and rerunning it (workflow_dispatch on main) is usually the better fix. To publish by hand anyway, from the repo root:

clawhub whoami   # should print your handle (e.g. arberx); if not, run `clawhub login`
clawhub publish skills/agent-readiness --version <semver> --changelog "<description of changes>"

--version must be valid semver and must match package.json.

ClawHub Security Guidelines

ClawHub flags skills as suspicious when they request excessive capabilities. Follow these rules to stay under the threshold:

• Pin npx versions — use the current major (@8) instead of @latest. The @latest tag is a supply chain risk because a compromised publish can hijack all users immediately. Never pin an exact version (@8.0.0): the major pin already gives users every patch and minor release without a skill update. Bump it only in the release that changes the major.
• Minimize Bash patterns — only declare the single npx command end users need. Do not include local dev commands (pnpm run build, node bin/...) in the published skill; those are for contributors, not consumers.
• Avoid generic Bash patterns — Bash(agent-readiness *) is too broad and could match other binaries. Always use the fully qualified npx @canonry/agent-readiness@8 * form.
• Scope file permissions narrowly — only request Edit/Write for file types the skill actually modifies. Use Write(filename) for specific files (e.g., llms.txt, robots.txt) instead of broad Edit(*.txt) patterns.
• Keep shell injection guards — the Argument Safety section in SKILL.md is required. Never remove it.

GitHub Actions Conventions

• Single trigger path per release flow. If the workflow auto-creates a tag, do not also trigger on that tag pattern — the self-pushed tag will re-fire the workflow, causing a duplicate publish that fails with 403 on npm.
• Never interpolate step outputs directly into run: blocks. Use an env: block to pass values into shell scripts: env: { VERSION: "${{ steps.x.outputs.version }}" } then reference $VERSION in the script. Direct ${{ }} interpolation in run: is a script-injection vector.
• Scope permissions to the minimum required per job. If only one step needs contents: write (e.g., pushing a tag), prefer splitting it into a separate job with its own permissions block rather than elevating the entire job.
• Declare explicit permissions on every job. Omitting the permissions block inherits the repository default, which may be write-all. Always declare at minimum contents: read.