@nebulacomponents/citable 0.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## 1.2.0 — 2026-07-18
+
+### Added
+
+- **`self-upgrade` command** — checks npm registry for the latest version and upgrades the npx cache if a newer version is available:
+  - `npx @nebulacomponents/citable self-upgrade` — check and upgrade
+  - `npx @nebulacomponents/citable self-upgrade --check` — check only, no upgrade
+  - `npx @nebulacomponents/citable self-upgrade --json` — machine-readable output
+  - Uses Node's built-in `fetch` (no extra deps), 10s timeout, graceful offline error
+- **6 new tests** for self-upgrade (current, update-available, registry failure × 2 each for human/JSON output)
+
+### Changed
+
+- Test count: 84 → 90
+
+## 1.1.0 — 2026-07-18
+
+### Added
+
+- **AGENT namespace** — 10 agent-readiness detectors based on [isitagentready.com](https://isitagentready.com/) checks:
+  - **AGENT-001** `AI bot rules absent from robots.txt` — checks for GPTBot, ClaudeBot, PerplexityBot, anthropic-ai, and other AI crawler rules
+  - **AGENT-002** `Link response headers absent` — HTTP Link headers for agent discovery (sitemap, MCP, API catalog)
+  - **AGENT-003** `llms.txt missing` — llmstxt.org structured Markdown for LLM consumption
+  - **AGENT-004** `MCP Server Card not discoverable` — `/.well-known/mcp` for Model Context Protocol server auto-discovery (API sites only)
+  - **AGENT-005** `A2A Agent Card not discoverable` — `/.well-known/agent.json` for Google A2A inter-agent discovery (agent sites only)
+  - **AGENT-006** `Markdown content negotiation not supported` — `Accept: text/markdown` / Cloudflare Markdown for Agents
+  - **AGENT-007** `Web Bot Auth not declared` — Cloudflare Web Bot Auth for authenticated bot access
+  - **AGENT-008** `Content-Signals header absent` — Cloudflare Content Signals for AI usage permissions
+  - **AGENT-009** `auth.md not present` — `/auth.md` authentication documentation for agent consumers (API/auth sites only)
+  - **AGENT-010** `Agentic commerce protocols not declared` — x402, MPP, UCP, ACP payment protocol signals (commerce sites only)
+- **38 new tests** for AGENT detectors
+- **`agent-readiness` discipline** added to finding schema
+- **`file` subject type** added to finding schema
+
+### Changed
+
+- Detector count: 102/15 namespaces (0.1.0) → 109/17 (1.0.0) → **119/18 namespaces** (this release)
+- Test count: 46 → 84
+
+## 1.0.0 — 2026-07-18
+
+**First production release.**
+
+### Added
+
+- **HREFLANG namespace** — 3 detectors for international SEO validation:
+  - HREFLANG-001: hreflang link validation (valid hreflang values)
+  - HREFLANG-002: self-reference check (page should reference itself)
+  - HREFLANG-003: x-default presence (missing default language fallback)
+- **CWV namespace** — 3 infrastructure detectors for Core Web Vitals readiness:
+  - CWV-001: LCP potential blockers (render-blocking scripts, images without dimensions)
+  - CWV-002: preconnect hints for fonts
+  - CWV-003: image optimization checks (format, dimensions, lazy loading)
+
+  > **Limitation:** no field or lab data collection; the CWV detectors check
+  > infrastructure readiness, not performance.
+- **URL fetch resilience** — retry with exponential backoff + jitter, 5xx handling
+- **CI workflow** — GitHub Actions for Node 22 matrix testing
+
+### Changed
+
+- **Detector count** — now 109 detectors across 17 namespaces
+- **Documentation** — fixed test count (33 → 46), updated README/CLAUDE.md/AGENTS.md
+
+### Fixed
+
+- CI workflow compatibility — use actions@v4, Node 22 (not v6, Node 24)
+- npm-publish workflow — fixed version check for new packages
+
 ## 0.1.0 — 2026-07-18
 
 Initial MVP.

package/README.md

@@ -16,8 +16,8 @@ generator, not a Lighthouse wrapper, not an "AI visibility score".
 - **Persistent registries** (`.citable/`): queries, prompts, entities, claims,
   evidence, pages, crawler policies, competitors, experiments — all
   JSON-Schema validated with referential integrity and history-preserving saves.
-- **102 detectors** across 15 namespaces (TECH, CRAWL, ARCH, PAGE, ANS,
-  ENTITY, CLAIM, EVD, SCHEMA, LINK, EXT, GEO, RECO, LIFE, MEAS), each with
+- **119 detectors** across 18 namespaces (TECH, CRAWL, ARCH, PAGE, ANS,
+  ENTITY, CLAIM, EVD, SCHEMA, LINK, EXT, GEO, RECO, LIFE, MEAS, HREFLANG, CWV, AGENT), each with
   remediation, verification, severity, and determinism declared.
 - **Evidence packages** for every run: manifest, findings, report, captured
   robots/sitemaps/headers/schema/link graph, checksums.
@@ -28,6 +28,12 @@ generator, not a Lighthouse wrapper, not an "AI visibility score".
   mandatory human-review conditions.
 - **Multi-agent distribution**: Claude Code, Codex-compatible, Cursor, Gemini,
   generic — generated from one canonical `skill/` source.
+- **Agent-readiness detectors** (AGENT namespace): agents are both readers
+  and writers of your site — `llms.txt` and Markdown content negotiation shape
+  what they consume; MCP Server Cards and A2A Agent Cards expose what they can
+  invoke; Content-Signals and Web Bot Auth govern the permissions they receive.
+  Citable checks all of these in one pass alongside the rest of your
+  SEO/AEO/GEO signal surface.
 
 ## Install
 

package/dist/universal/.agents/skills/citable/VERSION

@@ -1 +1 @@
-0.1.0
+1.2.0

package/dist/universal/.agents/skills/citable/manifest.json

@@ -1,11 +1,11 @@
 {
   "name": "citable",
-  "version": "0.1.0",
+  "version": "1.2.0",
   "managedBy": "citable-cli",
   "provider": "codex",
   "providerName": "OpenAI Codex",
   "scope": "bundle",
-  "sourcePackage": "@nebulacomponents/citable@0.1.0",
+  "sourcePackage": "@nebulacomponents/citable@1.2.0",
   "variantPath": ".agents/skills/citable",
   "files": {
     "commands/ingest.md": "sha256:cf35659aecd9d0e160909003efdbe056864fc5d824c71b4ef0ee801ce07ff598",
@@ -38,7 +38,7 @@
     "schemas/entity.schema.json": "sha256:12f9222122255c86059185bc66e528e2828b430f7abc5683e6759774eb555553",
     "schemas/evidence.schema.json": "sha256:a78d39cd1d66c89198b0ecc9af48c8d3d8659c7b5cbb9f96c43d18fcf2b4aeb7",
     "schemas/experiment.schema.json": "sha256:704ea5c14cd4409c3a1806b8b1c124bcd9f2fe9e313dfa93662889bed0cb6441",
-    "schemas/finding.schema.json": "sha256:2366bbbd0f6359ecc8d262979b159811ad10d2eaacc4816d5075bc6f7e9efc13",
+    "schemas/finding.schema.json": "sha256:85907cd04cd8d2fe24a1e618e0df7160f6d56aa1818db501f345aebce5eb5edb",
     "schemas/page.schema.json": "sha256:195d2f91d67550627c7047fd8e98d08dc386bc5858a02239d6c23b99193eaac2",
     "schemas/project.schema.json": "sha256:ea48fdb6480f7047ba4594bd5908bc1f79c1ad6b9a2c204df900959b5f203dc6",
     "schemas/prompt-result.schema.json": "sha256:b55be47d7d58d7b1dd8c3b1e849e24e55216212c592cde7eb836953379b85737",
@@ -48,7 +48,7 @@
     "scripts/README.md": "sha256:1c3e952950ef353849621b07c5f615bf7cd20cc5654da4635492a7bd6384e747",
     "SKILL.md": "sha256:637bb755bca6a2225c5b69edab0b8be7dff294e784d7ce25cec23546b847324c",
     "templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
-    "VERSION": "sha256:e9dd8507f4bf0c6f42458e41aea833ad0bd3f6127272335eee9bf4d58541ed67"
+    "VERSION": "sha256:1e5b51cde515396a9fa762909cf8ca6584ccc564b325d2eebeea76175fe95c4d"
   },
-  "treeHash": "sha256:7b3f30bfd6e7c79f549a4ca9a2269a32afa899a995437ed9b1b8d7e86d562bf2"
+  "treeHash": "sha256:ced29038005c4b29321f3ddb6c77cd8749a917b96983da422ed5677443be395a"
 }

package/dist/universal/.agents/skills/citable/schemas/finding.schema.json

@@ -3,54 +3,184 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Finding",
   "type": "object",
-  "required": ["finding_id", "detector_id", "run_id", "timestamp", "discipline", "subject", "observation", "classification", "remediation", "verification", "status"],
+  "required": [
+    "finding_id",
+    "detector_id",
+    "run_id",
+    "timestamp",
+    "discipline",
+    "subject",
+    "observation",
+    "classification",
+    "remediation",
+    "verification",
+    "status"
+  ],
   "properties": {
-    "finding_id": { "$ref": "citable://schemas/common.defs.json#/definitions/id" },
-    "detector_id": { "$ref": "citable://schemas/common.defs.json#/definitions/id" },
-    "run_id": { "type": "string" },
-    "timestamp": { "type": "string" },
-    "discipline": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": ["seo", "aeo", "geo"] } },
+    "finding_id": {
+      "$ref": "citable://schemas/common.defs.json#/definitions/id"
+    },
+    "detector_id": {
+      "$ref": "citable://schemas/common.defs.json#/definitions/id"
+    },
+    "run_id": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string"
+    },
+    "discipline": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "enum": [
+          "seo",
+          "aeo",
+          "geo",
+          "agent-readiness"
+        ]
+      }
+    },
     "subject": {
       "type": "object",
-      "required": ["type", "identifier"],
+      "required": [
+        "type",
+        "identifier"
+      ],
       "properties": {
-        "type": { "type": "string", "enum": ["url", "page", "source_file", "registry_entry", "site", "schema_block", "link", "crawler", "claim", "evidence", "entity", "prompt", "query", "experiment", "run"] },
-        "identifier": { "type": "string" },
-        "url": { "type": "string" },
-        "source_file": { "type": "string" },
-        "source_location": { "type": "string" },
-        "rendered_selector": { "type": "string" }
+        "type": {
+          "type": "string",
+          "enum": [
+            "url",
+            "page",
+            "source_file",
+            "registry_entry",
+            "site",
+            "schema_block",
+            "link",
+            "crawler",
+            "claim",
+            "evidence",
+            "entity",
+            "prompt",
+            "query",
+            "experiment",
+            "run",
+            "file"
+          ]
+        },
+        "identifier": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        },
+        "source_file": {
+          "type": "string"
+        },
+        "source_location": {
+          "type": "string"
+        },
+        "rendered_selector": {
+          "type": "string"
+        }
       }
     },
     "observation": {
       "type": "object",
-      "required": ["summary", "evidence"],
+      "required": [
+        "summary",
+        "evidence"
+      ],
       "properties": {
-        "summary": { "type": "string", "minLength": 1 },
-        "evidence": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "evidence": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        },
         "captured_value": {},
         "expected_value": {}
       }
     },
     "classification": {
       "type": "object",
-      "required": ["finding_type", "severity", "confidence", "deterministic", "impact"],
+      "required": [
+        "finding_type",
+        "severity",
+        "confidence",
+        "deterministic",
+        "impact"
+      ],
       "properties": {
-        "finding_type": { "type": "string", "enum": ["deterministic_observation", "evidence_backed_semantic_finding", "probabilistic_inference", "strategic_hypothesis", "experiment_result", "untestable_condition"] },
-        "severity": { "type": "string", "enum": ["critical", "high", "medium", "low", "informational", "experimental"] },
-        "confidence": { "type": "string", "enum": ["confirmed", "high", "medium", "low", "unknown"] },
-        "deterministic": { "type": "boolean" },
+        "finding_type": {
+          "type": "string",
+          "enum": [
+            "deterministic_observation",
+            "evidence_backed_semantic_finding",
+            "probabilistic_inference",
+            "strategic_hypothesis",
+            "experiment_result",
+            "untestable_condition"
+          ]
+        },
+        "severity": {
+          "type": "string",
+          "enum": [
+            "critical",
+            "high",
+            "medium",
+            "low",
+            "informational",
+            "experimental"
+          ]
+        },
+        "confidence": {
+          "type": "string",
+          "enum": [
+            "confirmed",
+            "high",
+            "medium",
+            "low",
+            "unknown"
+          ]
+        },
+        "deterministic": {
+          "type": "boolean"
+        },
         "impact": {
           "type": "object",
           "properties": {
-            "retrieval": { "$ref": "#/definitions/impactLevel" },
-            "ranking": { "$ref": "#/definitions/impactLevel" },
-            "citation": { "$ref": "#/definitions/impactLevel" },
-            "representation": { "$ref": "#/definitions/impactLevel" },
-            "legal": { "$ref": "#/definitions/impactLevel" },
-            "reputational": { "$ref": "#/definitions/impactLevel" },
-            "conversion": { "$ref": "#/definitions/impactLevel" },
-            "maintainability": { "$ref": "#/definitions/impactLevel" }
+            "retrieval": {
+              "$ref": "#/definitions/impactLevel"
+            },
+            "ranking": {
+              "$ref": "#/definitions/impactLevel"
+            },
+            "citation": {
+              "$ref": "#/definitions/impactLevel"
+            },
+            "representation": {
+              "$ref": "#/definitions/impactLevel"
+            },
+            "legal": {
+              "$ref": "#/definitions/impactLevel"
+            },
+            "reputational": {
+              "$ref": "#/definitions/impactLevel"
+            },
+            "conversion": {
+              "$ref": "#/definitions/impactLevel"
+            },
+            "maintainability": {
+              "$ref": "#/definitions/impactLevel"
+            }
           }
         }
       }
@@ -58,44 +188,117 @@
     "reasoning": {
       "type": "object",
       "properties": {
-        "applicable_requirement": { "type": "string" },
-        "explanation": { "type": "string" },
-        "assumptions": { "type": "array", "items": { "type": "string" } },
-        "limitations": { "type": "array", "items": { "type": "string" } }
+        "applicable_requirement": {
+          "type": "string"
+        },
+        "explanation": {
+          "type": "string"
+        },
+        "assumptions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "limitations": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
       }
     },
     "remediation": {
       "type": "object",
-      "required": ["preferred"],
+      "required": [
+        "preferred"
+      ],
       "properties": {
-        "preferred": { "type": "string" },
-        "alternatives": { "type": "array", "items": { "type": "string" } },
-        "unsafe_shortcuts": { "type": "array", "items": { "type": "string" } },
-        "owner": { "type": ["string", "null"] },
-        "review_required": { "type": "boolean" }
+        "preferred": {
+          "type": "string"
+        },
+        "alternatives": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "unsafe_shortcuts": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "owner": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "review_required": {
+          "type": "boolean"
+        }
       }
     },
     "verification": {
       "type": "object",
-      "required": ["method"],
+      "required": [
+        "method"
+      ],
       "properties": {
-        "method": { "type": "string" },
-        "expected_result": { "type": "string" },
-        "detector_to_rerun": { "type": "string" }
+        "method": {
+          "type": "string"
+        },
+        "expected_result": {
+          "type": "string"
+        },
+        "detector_to_rerun": {
+          "type": "string"
+        }
       }
     },
     "status": {
       "type": "object",
-      "required": ["state"],
+      "required": [
+        "state"
+      ],
       "properties": {
-        "state": { "type": "string", "enum": ["open", "acknowledged", "in_remediation", "resolved", "accepted_risk", "false_positive"] },
-        "first_seen": { "type": "string" },
-        "last_seen": { "type": "string" },
-        "resolved_at": { "type": ["string", "null"] }
+        "state": {
+          "type": "string",
+          "enum": [
+            "open",
+            "acknowledged",
+            "in_remediation",
+            "resolved",
+            "accepted_risk",
+            "false_positive"
+          ]
+        },
+        "first_seen": {
+          "type": "string"
+        },
+        "last_seen": {
+          "type": "string"
+        },
+        "resolved_at": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
       }
     }
   },
   "definitions": {
-    "impactLevel": { "type": "string", "enum": ["none", "low", "medium", "high", "unknown"] }
+    "impactLevel": {
+      "type": "string",
+      "enum": [
+        "none",
+        "low",
+        "medium",
+        "high",
+        "unknown"
+      ]
+    }
   }
-}
+}

package/dist/universal/.claude/skills/citable/VERSION

@@ -1 +1 @@
-0.1.0
+1.2.0

package/dist/universal/.claude/skills/citable/manifest.json

@@ -1,11 +1,11 @@
 {
   "name": "citable",
-  "version": "0.1.0",
+  "version": "1.2.0",
   "managedBy": "citable-cli",
   "provider": "claude",
   "providerName": "Claude Code",
   "scope": "bundle",
-  "sourcePackage": "@nebulacomponents/citable@0.1.0",
+  "sourcePackage": "@nebulacomponents/citable@1.2.0",
   "variantPath": ".claude/skills/citable",
   "files": {
     "commands/ingest.md": "sha256:cf35659aecd9d0e160909003efdbe056864fc5d824c71b4ef0ee801ce07ff598",
@@ -38,7 +38,7 @@
     "schemas/entity.schema.json": "sha256:12f9222122255c86059185bc66e528e2828b430f7abc5683e6759774eb555553",
     "schemas/evidence.schema.json": "sha256:a78d39cd1d66c89198b0ecc9af48c8d3d8659c7b5cbb9f96c43d18fcf2b4aeb7",
     "schemas/experiment.schema.json": "sha256:704ea5c14cd4409c3a1806b8b1c124bcd9f2fe9e313dfa93662889bed0cb6441",
-    "schemas/finding.schema.json": "sha256:2366bbbd0f6359ecc8d262979b159811ad10d2eaacc4816d5075bc6f7e9efc13",
+    "schemas/finding.schema.json": "sha256:85907cd04cd8d2fe24a1e618e0df7160f6d56aa1818db501f345aebce5eb5edb",
     "schemas/page.schema.json": "sha256:195d2f91d67550627c7047fd8e98d08dc386bc5858a02239d6c23b99193eaac2",
     "schemas/project.schema.json": "sha256:ea48fdb6480f7047ba4594bd5908bc1f79c1ad6b9a2c204df900959b5f203dc6",
     "schemas/prompt-result.schema.json": "sha256:b55be47d7d58d7b1dd8c3b1e849e24e55216212c592cde7eb836953379b85737",
@@ -48,7 +48,7 @@
     "scripts/README.md": "sha256:1c3e952950ef353849621b07c5f615bf7cd20cc5654da4635492a7bd6384e747",
     "SKILL.md": "sha256:637bb755bca6a2225c5b69edab0b8be7dff294e784d7ce25cec23546b847324c",
     "templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
-    "VERSION": "sha256:e9dd8507f4bf0c6f42458e41aea833ad0bd3f6127272335eee9bf4d58541ed67"
+    "VERSION": "sha256:1e5b51cde515396a9fa762909cf8ca6584ccc564b325d2eebeea76175fe95c4d"
   },
-  "treeHash": "sha256:7b3f30bfd6e7c79f549a4ca9a2269a32afa899a995437ed9b1b8d7e86d562bf2"
+  "treeHash": "sha256:ced29038005c4b29321f3ddb6c77cd8749a917b96983da422ed5677443be395a"
 }