readiness-audit 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,11 @@
1
+ # Changelog
2
+
3
+ ## 1.0.0 (2026-10-05)
4
+
5
+ First public release.
6
+
7
+ - **The standard (STANDARD.md):** items in eight groups: discovery (D), web search (W), API (A), MCP (M), skills (S), engagement (E), measurement and tests (T), next level (N). Each has an ID, a level (required, recommended, only if true, next level) and the reason for its level.
8
+ - **The scorecard (`readiness-audit`):** 32 checks in one read-only pass: 19 required, 11 recommended and 2 next-level. It samples up to 20 sitemap pages for search and up to 5 skill files, prints `--json`, and builds a status page across several sites with `--matrix`, including recorded T5 and T6 results from `--recorded`.
9
+ - **Safe to point at any site:** it follows redirects itself and refuses private, local and non-http addresses at every hop, so a site's sitemap, share images, skills, catalog or DNS record can't send it to `localhost` or a cloud metadata address. It keeps to about six requests at a time.
10
+ - **The agent usability test (T5):** a procedure, a runner for Claude Code, and a results format (docs/usability-test.md).
11
+ - **Repo:** CI on Node 20, 22 and 24; a release workflow that publishes to npm through trusted publishing; contributing and security guides; issue templates.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Geeks Accelerator
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,66 @@
1
- # Temporary Holding Version
1
+ # Agent and Search Readiness
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![CI](https://github.com/geeks-accelerator/agent-and-search-readiness/actions/workflows/ci.yml/badge.svg)](https://github.com/geeks-accelerator/agent-and-search-readiness/actions/workflows/ci.yml)
4
+
5
+ A standard and a scorecard for making a site findable and usable by AI agents and by search engines.
6
+
7
+ AI agents find a site through discovery files, MCP registries, skills and search. People find it through Google, Bing and the AI answer engines built on them. Both then need the first call to work, and a reason to come back. This repo holds:
8
+
9
+ - **[STANDARD.md](STANDARD.md):** what to build, item by item, each with an ID, a level and the reason it's at that level. It covers discovery files, search, the API, MCP servers, skills, engagement, measurement and tests.
10
+ - **`readiness-audit`:** a command-line scorecard that checks a live site against everything the standard can verify from outside, about 30 checks in one pass.
11
+
12
+ ## Score a site
13
+
14
+ ```
15
+ npx readiness-audit example.com
16
+ ```
17
+
18
+ It needs Node 20 or later and has no dependencies. It only reads: GET requests, plus a few POSTs that create nothing (an MCP `initialize`, `server/discover` and `tools/list`, and an empty POST to `/`). It keeps to about six requests at a time, and it won't follow a link the site supplies (in its sitemap, share images, skills, catalog or DNS record) to a private or local address, at any redirect. It prints a pass, warning or failure for each check, with the reason, and exits with code 1 when a required check fails, so it can gate a deploy.
19
+
20
+ ```
21
+ readiness-audit <domain> [--mcp /path] [--no-mcp] [--no-api] [--json]
22
+ readiness-audit --matrix <domain> <domain> ... [--recorded results.json]
23
+ ```
24
+
25
+ | Option | What it does |
26
+ |---|---|
27
+ | `--mcp /path` | where your hosted MCP endpoint lives (default `/mcp`) |
28
+ | `--no-mcp` | skip the hosted MCP checks |
29
+ | `--no-api` | skip the API checks, for a site with no public API |
30
+ | `--json` | print the results as JSON |
31
+ | `--matrix` | score several sites and print a markdown status page |
32
+ | `--recorded file` | with `--matrix`, add your recorded T5 and T6 results (format: [examples/recorded.json](examples/recorded.json)) |
33
+
34
+ From a clone, run `node bin/readiness-audit.mjs example.com`.
35
+
36
+ ## What it checks, and what it can't
37
+
38
+ The scorecard covers what's visible from outside. It checks:
39
+ - robots.txt, the sitemap and llms.txt;
40
+ - security.txt and the honesty of the A2A path;
41
+ - false declarations;
42
+ - a sample of up to 20 pages for titles, canonical URLs, indexability, structured data, link previews and page structure;
43
+ - the OpenAPI document and the API's error answers;
44
+ - the hosted MCP edge and the MCP tools;
45
+ - a sample of skill files: spec names and descriptions, and links to llms.txt and the API reference;
46
+ - markdown negotiation, the AI catalog, the DNS AID record, the API catalog, auth.md and the skills index.
47
+
48
+ It can't see whether `next_steps` guide well, whether input is forgiving, whether skills ask before acting in public, or whether you have tests. The standard marks those items "review" or "test". The agent usability test (T5) measures what all of it is for: whether a fresh agent, given only your domain and a goal, succeeds. [docs/usability-test.md](docs/usability-test.md) has the procedure and a runner. A high score is not the goal.
49
+
50
+ ## Use it in your project
51
+
52
+ Point to [STANDARD.md](STANDARD.md) from your repo instead of copying it (§14 has a short stub), and pin the scorecard to a major version: `npx readiness-audit@1 <domain>`. To run it on a schedule in GitHub Actions, see [examples/github-action.yml](examples/github-action.yml).
53
+
54
+ ## Where it comes from
55
+
56
+ Six projects wrote down what they do for agents and search: [animalhouse.ai](https://animalhouse.ai), [inbed.ai](https://inbed.ai), [magnifica.family](https://magnifica.family), [drifts.bot](https://drifts.bot), [achurch.ai](https://achurch.ai) and [botsmatter.live](https://botsmatter.live). The standard merges their notes and settles where they disagreed, using the specs and production request logs. It was revised after each project's own agent reviewed it.
57
+
58
+ An item is in the standard when most projects should do it, not because one project happens to. Specs that are still drafts are marked as such, with dates. If you find something wrong or out of date, open an issue or a pull request.
59
+
60
+ ## Contributing
61
+
62
+ See [CONTRIBUTING.md](CONTRIBUTING.md). To report a security problem, see [SECURITY.md](SECURITY.md).
63
+
64
+ ## License
65
+
66
+ MIT