afdocs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dachary Carey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# afdocs
+
+Test your documentation site against the [Agent-Friendly Documentation Spec](https://agentdocsspec.com).
+
+Agents don't use docs like humans. They hit truncation limits, get walls of CSS instead of content, can't follow cross-host redirects, and don't know about quality-of-life improvements like `llms.txt` or `.md` docs pages that would make life swell. Maybe this is because the industry has lacked guidance - until now.
+
+afdocs runs 19 checks across 7 categories to evaluate how well your docs serve agent consumers.
+
+## Quick start
+
+```bash
+npx afdocs check https://docs.example.com
+```
+
+Example output:
+
+```
+Agent-Friendly Docs Check: https://react.dev
+
+llms-txt
+  ✓ llms-txt-exists: llms.txt found at 1 location(s)
+  ✓ llms-txt-valid: llms.txt follows the proposed structure
+  ✓ llms-txt-size: llms.txt is 14,347 characters (under 50,000 threshold)
+  ✓ llms-txt-links-resolve: All 50 tested links resolve (177 total links)
+  ✓ llms-txt-links-markdown: 50/50 links point to markdown content (100%)
+
+Summary
+  5 passed, 14 skipped (19 total)
+```
+
+## Install
+
+```bash
+npm install afdocs
+```
+
+## CLI usage
+
+```bash
+# Run all checks
+afdocs check https://docs.example.com
+
+# Run specific checks
+afdocs check https://docs.example.com --checks llms-txt-exists,llms-txt-valid,llms-txt-size
+
+# JSON output
+afdocs check https://docs.example.com --format json
+
+# Adjust thresholds
+afdocs check https://docs.example.com --pass-threshold 30000 --fail-threshold 80000
+```
+
+### Options
+
+| Option                  | Default  | Description                          |
+| ----------------------- | -------- | ------------------------------------ |
+| `--format <format>`     | `text`   | Output format: `text` or `json`      |
+| `--checks <ids>`        | all      | Comma-separated list of check IDs    |
+| `--max-concurrency <n>` | `3`      | Maximum concurrent HTTP requests     |
+| `--request-delay <ms>`  | `200`    | Delay between requests               |
+| `--max-links <n>`       | `50`     | Maximum links to test in link checks |
+| `--pass-threshold <n>`  | `50000`  | Size pass threshold (characters)     |
+| `--fail-threshold <n>`  | `100000` | Size fail threshold (characters)     |
+
+### Exit codes
+
+- `0` if all checks pass or warn
+- `1` if any check fails
+
+## Programmatic API
+
+```ts
+import { runChecks, createContext, getCheck } from 'afdocs';
+
+// Run all checks
+const report = await runChecks('https://docs.example.com');
+
+// Run a single check
+const ctx = createContext('https://docs.example.com');
+const check = getCheck('llms-txt-exists')!;
+const result = await check.run(ctx);
+```
+
+## Test helpers
+
+afdocs includes vitest helpers so you can add agent-friendliness checks to your docs site's test suite.
+
+### Config-driven
+
+Create `agent-docs.config.yml`:
+
+```yaml
+url: https://docs.example.com
+checks:
+  - llms-txt-exists
+  - llms-txt-valid
+  - llms-txt-size
+```
+
+Then in your test file:
+
+```ts
+import { describeAgentDocs } from 'afdocs/helpers';
+
+describeAgentDocs();
+```
+
+This reads the config and generates one test assertion covering all specified checks.
+
+### Direct imports
+
+```ts
+import { createContext, getCheck } from 'afdocs';
+import { describe, it, expect } from 'vitest';
+
+describe('agent-friendliness', () => {
+  it('has a valid llms.txt', async () => {
+    const ctx = createContext('https://docs.example.com');
+    const check = getCheck('llms-txt-exists')!;
+    const result = await check.run(ctx);
+    expect(result.status).toBe('pass');
+  });
+});
+```
+
+## Checks
+
+19 checks across 7 categories. Checks marked with \* are not yet implemented and will return `skip`.
+
+### Category 1: llms.txt
+
+| Check                     | Description                                               |
+| ------------------------- | --------------------------------------------------------- |
+| `llms-txt-exists`         | Whether `llms.txt` is discoverable at candidate locations |
+| `llms-txt-valid`          | Whether `llms.txt` follows the llmstxt.org structure      |
+| `llms-txt-size`           | Whether `llms.txt` fits within agent truncation limits    |
+| `llms-txt-links-resolve`  | Whether URLs in `llms.txt` return 200                     |
+| `llms-txt-links-markdown` | Whether URLs in `llms.txt` point to markdown content      |
+
+### Category 2: Markdown Availability
+
+| Check                     | Description                                       |
+| ------------------------- | ------------------------------------------------- |
+| `markdown-url-support` \* | Whether `.md` URL variants return markdown        |
+| `content-negotiation` \*  | Whether the server honors `Accept: text/markdown` |
+
+### Category 3: Page Size and Truncation Risk
+
+| Check                       | Description                                      |
+| --------------------------- | ------------------------------------------------ |
+| `page-size-markdown` \*     | Character count when served as markdown          |
+| `page-size-html` \*         | Character count of HTML and post-conversion size |
+| `content-start-position` \* | How far into the response actual content begins  |
+
+### Category 4: Content Structure
+
+| Check                             | Description                                        |
+| --------------------------------- | -------------------------------------------------- |
+| `tabbed-content-serialization` \* | Whether tabbed content creates oversized output    |
+| `section-header-quality` \*       | Whether headers in tabbed sections include context |
+| `markdown-code-fence-validity` \* | Whether markdown has unclosed code fences          |
+
+### Category 5: URL Stability and Redirects
+
+| Check                  | Description                                     |
+| ---------------------- | ----------------------------------------------- |
+| `http-status-codes` \* | Whether error pages return correct status codes |
+| `redirect-behavior` \* | Whether redirects are same-host HTTP redirects  |
+
+### Category 6: Agent Discoverability Directives
+
+| Check                   | Description                                              |
+| ----------------------- | -------------------------------------------------------- |
+| `llms-txt-directive` \* | Whether pages include a directive pointing to `llms.txt` |
+
+### Category 7: Observability and Content Health
+
+| Check                        | Description                                    |
+| ---------------------------- | ---------------------------------------------- |
+| `llms-txt-freshness` \*      | Whether `llms.txt` reflects current site state |
+| `markdown-content-parity` \* | Whether markdown and HTML versions match       |
+| `cache-header-hygiene` \*    | Whether cache headers allow timely updates     |
+
+## Check dependencies
+
+Some checks depend on others. If a dependency doesn't pass, the dependent check is skipped automatically.
+
+- `llms-txt-valid`, `llms-txt-size`, `llms-txt-links-resolve`, `llms-txt-links-markdown` require `llms-txt-exists`
+- `page-size-markdown` requires `markdown-url-support` or `content-negotiation`
+- `section-header-quality` requires `tabbed-content-serialization`
+- `markdown-code-fence-validity` requires `markdown-url-support` or `content-negotiation`
+- `llms-txt-freshness` requires `llms-txt-exists`
+- `markdown-content-parity` requires `markdown-url-support` or `content-negotiation`
+
+## Responsible use
+
+afdocs makes HTTP requests to the sites it checks. It enforces delays between requests (200ms default), caps concurrent connections, and honors `Retry-After` headers. The goal is to help documentation teams improve agent accessibility, not to load-test their infrastructure.
+
+## License
+
+MIT

package/bin/afdocs.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../dist/cli/index.js';
+run(process.argv);

package/dist/checks/agent-discoverability/llms-txt-directive.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=llms-txt-directive.d.ts.map

package/dist/checks/agent-discoverability/llms-txt-directive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms-txt-directive.d.ts","sourceRoot":"","sources":["../../../src/checks/agent-discoverability/llms-txt-directive.ts"],"names":[],"mappings":""}

package/dist/checks/agent-discoverability/llms-txt-directive.js

@@ -0,0 +1,17 @@
+import { registerCheck } from '../registry.js';
+async function check(_ctx) {
+    return {
+        id: 'llms-txt-directive',
+        category: 'agent-discoverability',
+        status: 'skip',
+        message: 'Not yet implemented',
+    };
+}
+registerCheck({
+    id: 'llms-txt-directive',
+    category: 'agent-discoverability',
+    description: 'Whether pages include a directive pointing to llms.txt',
+    dependsOn: [],
+    run: check,
+});
+//# sourceMappingURL=llms-txt-directive.js.map

package/dist/checks/agent-discoverability/llms-txt-directive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms-txt-directive.js","sourceRoot":"","sources":["../../../src/checks/agent-discoverability/llms-txt-directive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG/C,KAAK,UAAU,KAAK,CAAC,IAAkB;IACrC,OAAO;QACL,EAAE,EAAE,oBAAoB;QACxB,QAAQ,EAAE,uBAAuB;QACjC,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,qBAAqB;KAC/B,CAAC;AACJ,CAAC;AAED,aAAa,CAAC;IACZ,EAAE,EAAE,oBAAoB;IACxB,QAAQ,EAAE,uBAAuB;IACjC,WAAW,EAAE,wDAAwD;IACrE,SAAS,EAAE,EAAE;IACb,GAAG,EAAE,KAAK;CACX,CAAC,CAAC"}

package/dist/checks/content-structure/markdown-code-fence-validity.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=markdown-code-fence-validity.d.ts.map

package/dist/checks/content-structure/markdown-code-fence-validity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-code-fence-validity.d.ts","sourceRoot":"","sources":["../../../src/checks/content-structure/markdown-code-fence-validity.ts"],"names":[],"mappings":""}

package/dist/checks/content-structure/markdown-code-fence-validity.js

@@ -0,0 +1,17 @@
+import { registerCheck } from '../registry.js';
+async function check(_ctx) {
+    return {
+        id: 'markdown-code-fence-validity',
+        category: 'content-structure',
+        status: 'skip',
+        message: 'Not yet implemented',
+    };
+}
+registerCheck({
+    id: 'markdown-code-fence-validity',
+    category: 'content-structure',
+    description: 'Whether markdown contains unclosed code fences',
+    dependsOn: [['markdown-url-support', 'content-negotiation']],
+    run: check,
+});
+//# sourceMappingURL=markdown-code-fence-validity.js.map

package/dist/checks/content-structure/markdown-code-fence-validity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-code-fence-validity.js","sourceRoot":"","sources":["../../../src/checks/content-structure/markdown-code-fence-validity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG/C,KAAK,UAAU,KAAK,CAAC,IAAkB;IACrC,OAAO;QACL,EAAE,EAAE,8BAA8B;QAClC,QAAQ,EAAE,mBAAmB;QAC7B,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,qBAAqB;KAC/B,CAAC;AACJ,CAAC;AAED,aAAa,CAAC;IACZ,EAAE,EAAE,8BAA8B;IAClC,QAAQ,EAAE,mBAAmB;IAC7B,WAAW,EAAE,gDAAgD;IAC7D,SAAS,EAAE,CAAC,CAAC,sBAAsB,EAAE,qBAAqB,CAAC,CAAC;IAC5D,GAAG,EAAE,KAAK;CACX,CAAC,CAAC"}

package/dist/checks/content-structure/section-header-quality.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=section-header-quality.d.ts.map

package/dist/checks/content-structure/section-header-quality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-header-quality.d.ts","sourceRoot":"","sources":["../../../src/checks/content-structure/section-header-quality.ts"],"names":[],"mappings":""}

package/dist/checks/content-structure/section-header-quality.js

@@ -0,0 +1,17 @@
+import { registerCheck } from '../registry.js';
+async function check(_ctx) {
+    return {
+        id: 'section-header-quality',
+        category: 'content-structure',
+        status: 'skip',
+        message: 'Not yet implemented',
+    };
+}
+registerCheck({
+    id: 'section-header-quality',
+    category: 'content-structure',
+    description: 'Whether headers in tabbed sections include variant context',
+    dependsOn: ['tabbed-content-serialization'],
+    run: check,
+});
+//# sourceMappingURL=section-header-quality.js.map

package/dist/checks/content-structure/section-header-quality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-header-quality.js","sourceRoot":"","sources":["../../../src/checks/content-structure/section-header-quality.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG/C,KAAK,UAAU,KAAK,CAAC,IAAkB;IACrC,OAAO;QACL,EAAE,EAAE,wBAAwB;QAC5B,QAAQ,EAAE,mBAAmB;QAC7B,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,qBAAqB;KAC/B,CAAC;AACJ,CAAC;AAED,aAAa,CAAC;IACZ,EAAE,EAAE,wBAAwB;IAC5B,QAAQ,EAAE,mBAAmB;IAC7B,WAAW,EAAE,4DAA4D;IACzE,SAAS,EAAE,CAAC,8BAA8B,CAAC;IAC3C,GAAG,EAAE,KAAK;CACX,CAAC,CAAC"}

package/dist/checks/content-structure/tabbed-content-serialization.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tabbed-content-serialization.d.ts.map

package/dist/checks/content-structure/tabbed-content-serialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tabbed-content-serialization.d.ts","sourceRoot":"","sources":["../../../src/checks/content-structure/tabbed-content-serialization.ts"],"names":[],"mappings":""}

package/dist/checks/content-structure/tabbed-content-serialization.js

@@ -0,0 +1,17 @@
+import { registerCheck } from '../registry.js';
+async function check(_ctx) {
+    return {
+        id: 'tabbed-content-serialization',
+        category: 'content-structure',
+        status: 'skip',
+        message: 'Not yet implemented',
+    };
+}
+registerCheck({
+    id: 'tabbed-content-serialization',
+    category: 'content-structure',
+    description: 'Whether tabbed/accordion content serializes into oversized output',
+    dependsOn: [],
+    run: check,
+});
+//# sourceMappingURL=tabbed-content-serialization.js.map

package/dist/checks/content-structure/tabbed-content-serialization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tabbed-content-serialization.js","sourceRoot":"","sources":["../../../src/checks/content-structure/tabbed-content-serialization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG/C,KAAK,UAAU,KAAK,CAAC,IAAkB;IACrC,OAAO;QACL,EAAE,EAAE,8BAA8B;QAClC,QAAQ,EAAE,mBAAmB;QAC7B,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,qBAAqB;KAC/B,CAAC;AACJ,CAAC;AAED,aAAa,CAAC;IACZ,EAAE,EAAE,8BAA8B;IAClC,QAAQ,EAAE,mBAAmB;IAC7B,WAAW,EAAE,mEAAmE;IAChF,SAAS,EAAE,EAAE;IACb,GAAG,EAAE,KAAK;CACX,CAAC,CAAC"}

package/dist/checks/index.d.ts

@@ -0,0 +1,22 @@
+import './llms-txt/llms-txt-exists.js';
+import './llms-txt/llms-txt-valid.js';
+import './llms-txt/llms-txt-size.js';
+import './llms-txt/llms-txt-links-resolve.js';
+import './llms-txt/llms-txt-links-markdown.js';
+import './markdown-availability/markdown-url-support.js';
+import './markdown-availability/content-negotiation.js';
+import './page-size/page-size-markdown.js';
+import './page-size/page-size-html.js';
+import './page-size/content-start-position.js';
+import './content-structure/tabbed-content-serialization.js';
+import './content-structure/section-header-quality.js';
+import './content-structure/markdown-code-fence-validity.js';
+import './url-stability/http-status-codes.js';
+import './url-stability/redirect-behavior.js';
+import './agent-discoverability/llms-txt-directive.js';
+import './observability/llms-txt-freshness.js';
+import './observability/markdown-content-parity.js';
+import './observability/cache-header-hygiene.js';
+export { getCheck, getAllChecks, getChecksSorted } from './registry.js';
+export { extractMarkdownLinks } from './llms-txt/llms-txt-valid.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/checks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/checks/index.ts"],"names":[],"mappings":"AAGA,OAAO,+BAA+B,CAAC;AACvC,OAAO,8BAA8B,CAAC;AACtC,OAAO,6BAA6B,CAAC;AACrC,OAAO,sCAAsC,CAAC;AAC9C,OAAO,uCAAuC,CAAC;AAG/C,OAAO,iDAAiD,CAAC;AACzD,OAAO,gDAAgD,CAAC;AAGxD,OAAO,mCAAmC,CAAC;AAC3C,OAAO,+BAA+B,CAAC;AACvC,OAAO,uCAAuC,CAAC;AAG/C,OAAO,qDAAqD,CAAC;AAC7D,OAAO,+CAA+C,CAAC;AACvD,OAAO,qDAAqD,CAAC;AAG7D,OAAO,sCAAsC,CAAC;AAC9C,OAAO,sCAAsC,CAAC;AAG9C,OAAO,+CAA+C,CAAC;AAGvD,OAAO,uCAAuC,CAAC;AAC/C,OAAO,4CAA4C,CAAC;AACpD,OAAO,yCAAyC,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/checks/index.js

@@ -0,0 +1,30 @@
+// Import all check modules to trigger registration
+// Category 1: llms.txt
+import './llms-txt/llms-txt-exists.js';
+import './llms-txt/llms-txt-valid.js';
+import './llms-txt/llms-txt-size.js';
+import './llms-txt/llms-txt-links-resolve.js';
+import './llms-txt/llms-txt-links-markdown.js';
+// Category 2: Markdown Availability
+import './markdown-availability/markdown-url-support.js';
+import './markdown-availability/content-negotiation.js';
+// Category 3: Page Size
+import './page-size/page-size-markdown.js';
+import './page-size/page-size-html.js';
+import './page-size/content-start-position.js';
+// Category 4: Content Structure
+import './content-structure/tabbed-content-serialization.js';
+import './content-structure/section-header-quality.js';
+import './content-structure/markdown-code-fence-validity.js';
+// Category 5: URL Stability
+import './url-stability/http-status-codes.js';
+import './url-stability/redirect-behavior.js';
+// Category 6: Agent Discoverability
+import './agent-discoverability/llms-txt-directive.js';
+// Category 7: Observability
+import './observability/llms-txt-freshness.js';
+import './observability/markdown-content-parity.js';
+import './observability/cache-header-hygiene.js';
+export { getCheck, getAllChecks, getChecksSorted } from './registry.js';
+export { extractMarkdownLinks } from './llms-txt/llms-txt-valid.js';
+//# sourceMappingURL=index.js.map

package/dist/checks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/checks/index.ts"],"names":[],"mappings":"AAAA,mDAAmD;AAEnD,uBAAuB;AACvB,OAAO,+BAA+B,CAAC;AACvC,OAAO,8BAA8B,CAAC;AACtC,OAAO,6BAA6B,CAAC;AACrC,OAAO,sCAAsC,CAAC;AAC9C,OAAO,uCAAuC,CAAC;AAE/C,oCAAoC;AACpC,OAAO,iDAAiD,CAAC;AACzD,OAAO,gDAAgD,CAAC;AAExD,wBAAwB;AACxB,OAAO,mCAAmC,CAAC;AAC3C,OAAO,+BAA+B,CAAC;AACvC,OAAO,uCAAuC,CAAC;AAE/C,gCAAgC;AAChC,OAAO,qDAAqD,CAAC;AAC7D,OAAO,+CAA+C,CAAC;AACvD,OAAO,qDAAqD,CAAC;AAE7D,4BAA4B;AAC5B,OAAO,sCAAsC,CAAC;AAC9C,OAAO,sCAAsC,CAAC;AAE9C,oCAAoC;AACpC,OAAO,+CAA+C,CAAC;AAEvD,4BAA4B;AAC5B,OAAO,uCAAuC,CAAC;AAC/C,OAAO,4CAA4C,CAAC;AACpD,OAAO,yCAAyC,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/checks/llms-txt/llms-txt-exists.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=llms-txt-exists.d.ts.map

package/dist/checks/llms-txt/llms-txt-exists.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms-txt-exists.d.ts","sourceRoot":"","sources":["../../../src/checks/llms-txt/llms-txt-exists.ts"],"names":[],"mappings":""}

package/dist/checks/llms-txt/llms-txt-exists.js

@@ -0,0 +1,107 @@
+import { registerCheck } from '../registry.js';
+/**
+ * Build candidate URLs for llms.txt discovery.
+ * Per spec: {base_url}/llms.txt, {origin}/llms.txt, {origin}/docs/llms.txt
+ * Deduplicates.
+ */
+function getCandidateUrls(baseUrl, origin) {
+    const candidates = new Set();
+    candidates.add(`${baseUrl}/llms.txt`);
+    candidates.add(`${origin}/llms.txt`);
+    candidates.add(`${origin}/docs/llms.txt`);
+    return Array.from(candidates);
+}
+function isCrossHostRedirect(originalUrl, finalUrl) {
+    try {
+        const original = new URL(originalUrl);
+        const final_ = new URL(finalUrl);
+        return original.host !== final_.host;
+    }
+    catch {
+        return false;
+    }
+}
+async function checkLlmsTxtExists(ctx) {
+    const candidates = getCandidateUrls(ctx.baseUrl, ctx.origin);
+    const discovered = [];
+    const checkedUrls = [];
+    for (const url of candidates) {
+        try {
+            const response = await ctx.http.fetch(url);
+            const contentType = response.headers.get('content-type') ?? '';
+            const isText = contentType.includes('text/');
+            checkedUrls.push({
+                url,
+                status: response.status,
+                redirected: response.redirected,
+                finalUrl: response.redirected ? response.url : undefined,
+            });
+            if (response.ok && isText) {
+                const content = await response.text();
+                // Check it's not an HTML error page
+                const looksLikeHtml = content.trimStart().startsWith('<!') || content.trimStart().startsWith('<html');
+                if (!looksLikeHtml && content.trim().length > 0) {
+                    const crossHost = response.redirected && isCrossHostRedirect(url, response.url);
+                    discovered.push({
+                        url,
+                        content,
+                        status: response.status,
+                        redirected: response.redirected,
+                        redirectUrl: response.redirected ? response.url : undefined,
+                        crossHostRedirect: crossHost,
+                    });
+                }
+            }
+        }
+        catch {
+            checkedUrls.push({ url, status: 0, redirected: false });
+        }
+    }
+    // Store discovered files for downstream checks
+    const details = {
+        candidateUrls: checkedUrls,
+        discoveredFiles: discovered,
+    };
+    if (discovered.length === 0) {
+        return {
+            id: 'llms-txt-exists',
+            category: 'llms-txt',
+            status: 'fail',
+            message: `No llms.txt found at any candidate location (${candidates.join(', ')})`,
+            details,
+        };
+    }
+    // Check if any discovered files were only reachable via cross-host redirect
+    const allCrossHost = discovered.every((f) => f.crossHostRedirect);
+    if (allCrossHost) {
+        return {
+            id: 'llms-txt-exists',
+            category: 'llms-txt',
+            status: 'warn',
+            message: 'llms.txt found but only reachable via cross-host redirect (agents may not follow it)',
+            details,
+        };
+    }
+    // Note if multiple locations serve different content
+    if (discovered.length > 1) {
+        const contents = discovered.map((f) => f.content);
+        const allSame = contents.every((c) => c === contents[0]);
+        details.multipleLocations = true;
+        details.sameContent = allSame;
+    }
+    return {
+        id: 'llms-txt-exists',
+        category: 'llms-txt',
+        status: 'pass',
+        message: `llms.txt found at ${discovered.length} location(s)`,
+        details,
+    };
+}
+registerCheck({
+    id: 'llms-txt-exists',
+    category: 'llms-txt',
+    description: 'Whether llms.txt is discoverable at any of the candidate locations',
+    dependsOn: [],
+    run: checkLlmsTxtExists,
+});
+//# sourceMappingURL=llms-txt-exists.js.map

package/dist/checks/llms-txt/llms-txt-exists.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms-txt-exists.js","sourceRoot":"","sources":["../../../src/checks/llms-txt/llms-txt-exists.ts"],"names":[],"mappings":"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"}

package/dist/checks/llms-txt/llms-txt-links-markdown.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=llms-txt-links-markdown.d.ts.map

package/dist/checks/llms-txt/llms-txt-links-markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms-txt-links-markdown.d.ts","sourceRoot":"","sources":["../../../src/checks/llms-txt/llms-txt-links-markdown.ts"],"names":[],"mappings":""}