@nebulacomponents/citable 1.14.0 → 1.15.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.
Files changed (125) hide show
  1. package/CHANGELOG.md +66 -0
  2. package/README.md +1 -1
  3. package/dist/universal/.agents/skills/citable/SKILL.md +11 -6
  4. package/dist/universal/.agents/skills/citable/VERSION +1 -1
  5. package/dist/universal/.agents/skills/citable/commands/README.md +4 -1
  6. package/dist/universal/.agents/skills/citable/commands/observe-and-act.md +12 -5
  7. package/dist/universal/.agents/skills/citable/commands/reporting.md +57 -0
  8. package/dist/universal/.agents/skills/citable/manifest.json +10 -9
  9. package/dist/universal/.agents/skills/citable/schemas/observation.schema.json +1 -1
  10. package/dist/universal/.agents/skills/citable/schemas/schedule.schema.json +1 -1
  11. package/dist/universal/.claude/agents/citable/manifest.json +2 -2
  12. package/dist/universal/.claude/skills/citable/SKILL.md +11 -6
  13. package/dist/universal/.claude/skills/citable/VERSION +1 -1
  14. package/dist/universal/.claude/skills/citable/commands/README.md +4 -1
  15. package/dist/universal/.claude/skills/citable/commands/observe-and-act.md +12 -5
  16. package/dist/universal/.claude/skills/citable/commands/reporting.md +57 -0
  17. package/dist/universal/.claude/skills/citable/manifest.json +10 -9
  18. package/dist/universal/.claude/skills/citable/schemas/observation.schema.json +1 -1
  19. package/dist/universal/.claude/skills/citable/schemas/schedule.schema.json +1 -1
  20. package/dist/universal/.cursor/skills/citable/SKILL.md +11 -6
  21. package/dist/universal/.cursor/skills/citable/VERSION +1 -1
  22. package/dist/universal/.cursor/skills/citable/commands/README.md +4 -1
  23. package/dist/universal/.cursor/skills/citable/commands/observe-and-act.md +12 -5
  24. package/dist/universal/.cursor/skills/citable/commands/reporting.md +57 -0
  25. package/dist/universal/.cursor/skills/citable/manifest.json +10 -9
  26. package/dist/universal/.cursor/skills/citable/schemas/observation.schema.json +1 -1
  27. package/dist/universal/.cursor/skills/citable/schemas/schedule.schema.json +1 -1
  28. package/dist/universal/.gemini/skills/citable/SKILL.md +11 -6
  29. package/dist/universal/.gemini/skills/citable/VERSION +1 -1
  30. package/dist/universal/.gemini/skills/citable/commands/README.md +4 -1
  31. package/dist/universal/.gemini/skills/citable/commands/observe-and-act.md +12 -5
  32. package/dist/universal/.gemini/skills/citable/commands/reporting.md +57 -0
  33. package/dist/universal/.gemini/skills/citable/manifest.json +10 -9
  34. package/dist/universal/.gemini/skills/citable/schemas/observation.schema.json +1 -1
  35. package/dist/universal/.gemini/skills/citable/schemas/schedule.schema.json +1 -1
  36. package/dist/universal/.github/skills/citable/SKILL.md +11 -6
  37. package/dist/universal/.github/skills/citable/VERSION +1 -1
  38. package/dist/universal/.github/skills/citable/commands/README.md +4 -1
  39. package/dist/universal/.github/skills/citable/commands/observe-and-act.md +12 -5
  40. package/dist/universal/.github/skills/citable/commands/reporting.md +57 -0
  41. package/dist/universal/.github/skills/citable/manifest.json +10 -9
  42. package/dist/universal/.github/skills/citable/schemas/observation.schema.json +1 -1
  43. package/dist/universal/.github/skills/citable/schemas/schedule.schema.json +1 -1
  44. package/dist/universal/.kiro/skills/citable/SKILL.md +11 -6
  45. package/dist/universal/.kiro/skills/citable/VERSION +1 -1
  46. package/dist/universal/.kiro/skills/citable/commands/README.md +4 -1
  47. package/dist/universal/.kiro/skills/citable/commands/observe-and-act.md +12 -5
  48. package/dist/universal/.kiro/skills/citable/commands/reporting.md +57 -0
  49. package/dist/universal/.kiro/skills/citable/manifest.json +10 -9
  50. package/dist/universal/.kiro/skills/citable/schemas/observation.schema.json +1 -1
  51. package/dist/universal/.kiro/skills/citable/schemas/schedule.schema.json +1 -1
  52. package/dist/universal/.opencode/skills/citable/SKILL.md +11 -6
  53. package/dist/universal/.opencode/skills/citable/VERSION +1 -1
  54. package/dist/universal/.opencode/skills/citable/commands/README.md +4 -1
  55. package/dist/universal/.opencode/skills/citable/commands/observe-and-act.md +12 -5
  56. package/dist/universal/.opencode/skills/citable/commands/reporting.md +57 -0
  57. package/dist/universal/.opencode/skills/citable/manifest.json +10 -9
  58. package/dist/universal/.opencode/skills/citable/schemas/observation.schema.json +1 -1
  59. package/dist/universal/.opencode/skills/citable/schemas/schedule.schema.json +1 -1
  60. package/dist/universal/.pi/agent/skills/citable/SKILL.md +11 -6
  61. package/dist/universal/.pi/agent/skills/citable/VERSION +1 -1
  62. package/dist/universal/.pi/agent/skills/citable/commands/README.md +4 -1
  63. package/dist/universal/.pi/agent/skills/citable/commands/observe-and-act.md +12 -5
  64. package/dist/universal/.pi/agent/skills/citable/commands/reporting.md +57 -0
  65. package/dist/universal/.pi/agent/skills/citable/manifest.json +10 -9
  66. package/dist/universal/.pi/agent/skills/citable/schemas/observation.schema.json +1 -1
  67. package/dist/universal/.pi/agent/skills/citable/schemas/schedule.schema.json +1 -1
  68. package/dist/universal/.qoder/skills/citable/SKILL.md +11 -6
  69. package/dist/universal/.qoder/skills/citable/VERSION +1 -1
  70. package/dist/universal/.qoder/skills/citable/commands/README.md +4 -1
  71. package/dist/universal/.qoder/skills/citable/commands/observe-and-act.md +12 -5
  72. package/dist/universal/.qoder/skills/citable/commands/reporting.md +57 -0
  73. package/dist/universal/.qoder/skills/citable/manifest.json +10 -9
  74. package/dist/universal/.qoder/skills/citable/schemas/observation.schema.json +1 -1
  75. package/dist/universal/.qoder/skills/citable/schemas/schedule.schema.json +1 -1
  76. package/dist/universal/.rovodev/skills/citable/SKILL.md +11 -6
  77. package/dist/universal/.rovodev/skills/citable/VERSION +1 -1
  78. package/dist/universal/.rovodev/skills/citable/commands/README.md +4 -1
  79. package/dist/universal/.rovodev/skills/citable/commands/observe-and-act.md +12 -5
  80. package/dist/universal/.rovodev/skills/citable/commands/reporting.md +57 -0
  81. package/dist/universal/.rovodev/skills/citable/manifest.json +10 -9
  82. package/dist/universal/.rovodev/skills/citable/schemas/observation.schema.json +1 -1
  83. package/dist/universal/.rovodev/skills/citable/schemas/schedule.schema.json +1 -1
  84. package/dist/universal/.trae/skills/citable/SKILL.md +11 -6
  85. package/dist/universal/.trae/skills/citable/VERSION +1 -1
  86. package/dist/universal/.trae/skills/citable/commands/README.md +4 -1
  87. package/dist/universal/.trae/skills/citable/commands/observe-and-act.md +12 -5
  88. package/dist/universal/.trae/skills/citable/commands/reporting.md +57 -0
  89. package/dist/universal/.trae/skills/citable/manifest.json +10 -9
  90. package/dist/universal/.trae/skills/citable/schemas/observation.schema.json +1 -1
  91. package/dist/universal/.trae/skills/citable/schemas/schedule.schema.json +1 -1
  92. package/dist/universal/.trae-cn/skills/citable/SKILL.md +11 -6
  93. package/dist/universal/.trae-cn/skills/citable/VERSION +1 -1
  94. package/dist/universal/.trae-cn/skills/citable/commands/README.md +4 -1
  95. package/dist/universal/.trae-cn/skills/citable/commands/observe-and-act.md +12 -5
  96. package/dist/universal/.trae-cn/skills/citable/commands/reporting.md +57 -0
  97. package/dist/universal/.trae-cn/skills/citable/manifest.json +10 -9
  98. package/dist/universal/.trae-cn/skills/citable/schemas/observation.schema.json +1 -1
  99. package/dist/universal/.trae-cn/skills/citable/schemas/schedule.schema.json +1 -1
  100. package/dist/universal/manifest.json +124 -112
  101. package/package.json +1 -1
  102. package/schemas/observation.schema.json +1 -1
  103. package/schemas/schedule.schema.json +1 -1
  104. package/skill/SKILL.md +11 -6
  105. package/skill/commands/README.md +4 -1
  106. package/skill/commands/observe-and-act.md +12 -5
  107. package/skill/commands/reporting.md +57 -0
  108. package/src/cli/index.js +78 -11
  109. package/src/commands/connect.js +29 -0
  110. package/src/commands/context.js +15 -0
  111. package/src/commands/delivery.js +86 -2
  112. package/src/commands/monitor.js +35 -0
  113. package/src/commands/observe.js +3 -1
  114. package/src/commands/reportDashboard.js +21 -0
  115. package/src/commands/reportShareOfVoice.js +60 -0
  116. package/src/connectors/http.js +6 -3
  117. package/src/connectors/index.js +3 -1
  118. package/src/connectors/webflow.js +224 -0
  119. package/src/connectors/wordpress.js +226 -0
  120. package/src/detectors/geoReco.js +101 -0
  121. package/src/monitoring/alertDelivery.js +98 -0
  122. package/src/observations/common.js +10 -0
  123. package/src/observations/stance.js +261 -0
  124. package/src/reporting/dashboard.js +254 -0
  125. package/src/reporting/shareOfVoice.js +362 -0
@@ -0,0 +1,57 @@
1
+ ---
2
+ command: /citable report dashboard [--last N] [--since <run-id>]
3
+ purpose: Fold the summary each audit run already recorded into a cross-run Markdown table and self-contained HTML page without deriving new findings, scores, or causal explanations.
4
+ preconditions: [at least one finalized audit run under .citable/runs/ with a summary.json]
5
+ failure_behaviour: fewer than two audit runs -> explicit insufficient-history state, not a trend; unreadable summary or manifest -> run reported under skipped runs; non-integer --last -> fail
6
+ artifacts_created: [.citable/reports/dashboard.md, .citable/reports/dashboard.html]
7
+ ---
8
+
9
+ # Cross-run evidence reporting
10
+
11
+ 1. Run `citable report dashboard` to read severity counts, retrieval
12
+ eligibility, source extraction and support, and observed citation presence
13
+ rate across run history. Every value is copied from a run's own
14
+ `summary.json`. The command runs no detector, opens no network connection,
15
+ and never edits an immutable run package.
16
+ 2. Treat the output as derived, not canonical. It is written to
17
+ `.citable/reports/`, alongside `monitor` and `action-plan` derived
18
+ artifacts. The evidence of record remains `.citable/runs/<run-id>/`.
19
+ 3. Window the history with `--since <run-id>` (keeps that run and everything
20
+ after it) and `--last N` (keeps the final N runs). Run IDs sort
21
+ chronologically, so both filters are deterministic.
22
+ 4. Read fewer than two runs as no trend. With zero or one run the dashboard
23
+ states insufficient history explicitly instead of drawing a line through a
24
+ single point. Direction, rate of change, and improvement are not established
25
+ by one observation.
26
+ 5. Read skipped runs as a gap in the series, not as absence of a problem. A run
27
+ whose `summary.json` or `manifest.json` cannot be parsed, and an observation
28
+ run whose summary records no severity or posture, is listed with its reason
29
+ rather than counted as zero findings.
30
+ 6. Read a falling count as an observed difference between runs, not as proof
31
+ that a condition was fixed. Use `citable compare-snapshots` to establish
32
+ whether two runs are comparable at all — detector set, configuration,
33
+ observation method, and tool version all change what a count means.
34
+
35
+ # Refusal boundary
36
+
37
+ Do not present the dashboard as an AI visibility score, a ranking forecast, or
38
+ a measure of citation likelihood. The three posture dimensions are reported
39
+ separately and are never combined into a single number. Do not interpolate,
40
+ estimate, or carry forward a missing value: a run with no evidenced citation
41
+ presence rate is omitted from that trend line, not filled in. Do not attribute
42
+ any observed change to a specific intervention.
43
+
44
+ # Share of voice and competitor reporting
45
+
46
+ 1. Run `citable report share-of-voice [--last N] [--since <run-id>]` to evaluate
47
+ first-party and competitor citation presence and share across recorded
48
+ `observe citation` runs.
49
+ 2. Contested competitor domains are loaded from `.citable/competitors.yaml`.
50
+ Citations whose canonical URL matches declared competitor domains are joined
51
+ into per-prompt and aggregate shares.
52
+ 3. Competitor share is calculated strictly from evidenced observations; missing
53
+ observations or unevaluated prompts are never filled with fabricated zeros or
54
+ interpolated estimates.
55
+ 4. Outputs are written to `.citable/reports/share-of-voice.md` and
56
+ `.citable/reports/share-of-voice.html`.
57
+
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "citable",
3
- "version": "1.14.0",
3
+ "version": "1.15.0",
4
4
  "managedBy": "citable-cli",
5
5
  "provider": "github",
6
6
  "providerName": "GitHub Copilot",
7
7
  "scope": "bundle",
8
- "sourcePackage": "@nebulacomponents/citable@1.14.0",
8
+ "sourcePackage": "@nebulacomponents/citable@1.15.0",
9
9
  "variantPath": ".github/skills/citable",
10
10
  "agentProfiles": {
11
11
  "status": "unsupported",
@@ -22,11 +22,12 @@
22
22
  "commands/ingest.md": "sha256:cf35659aecd9d0e160909003efdbe056864fc5d824c71b4ef0ee801ce07ff598",
23
23
  "commands/measurement.md": "sha256:9cade6dfec23338e18aa67ede3335ac9e2888dc577a7d4d8e3ceac948bce403f",
24
24
  "commands/media-evidence.md": "sha256:f2218feabe3360a2c9d569a5fa9b70d4b33a83a270d657151635e6f404fb34e0",
25
- "commands/observe-and-act.md": "sha256:847d35aa6cd5b32dea4cd82fd4a5e84343676fd7e45c5e3a10393a00f6b288a7",
25
+ "commands/observe-and-act.md": "sha256:32ad048f14610de0e9a00a7faf27ff18ec0d892f5b20d568f519e44a7ffc0faf",
26
26
  "commands/optimize-page.md": "sha256:35866f3d7cdeef0376ea7a7d7036085a9b9cf95bbb300ecf4bd77610ebd74d85",
27
27
  "commands/page-work.md": "sha256:965a66e59bdf7b0da482d26fade53b3d265885ece5d463fe83b0789ebefaef3e",
28
28
  "commands/plan-audit.md": "sha256:69875c9654e13b84566dafb16afe5afe08cffb9f3bded1f2d8d2261ae871c869",
29
- "commands/README.md": "sha256:c27f69e0e33712e00f780c0988c7b033650c17d3450baea33f2b14212be8438e",
29
+ "commands/README.md": "sha256:a8242f715219a549ad4b40a3573b62e1d2249a76a3162622e0cd61f80682d971",
30
+ "commands/reporting.md": "sha256:b4e7003d291180ddac574915ebc17a05faac0a72acf5ae2f21bcaa59d273e7ad",
30
31
  "commands/reviews.md": "sha256:902904aaa405fe5724cf0662c7a5a36eab9a4fe0eb81cbd95ffa2fff946e0ac8",
31
32
  "commands/validate-render.md": "sha256:a8e1d04d40b84d57c35039250d98c6a7302cd44a148a8c3b9d9cfb92678c4347",
32
33
  "policies/crawler-policy-template.md": "sha256:15c88a4eeb21f53f71e5250dd3eb2d2791a814b304eaefce8bb30e2bdf2e2e59",
@@ -83,7 +84,7 @@
83
84
  "schemas/media-manifest.schema.json": "sha256:3f37301aab9e913fa7febb15c720ed6384b106f12cef8d26cdd12d93fd85b41f",
84
85
  "schemas/metric.schema.json": "sha256:2ada648e7274a8d78cc9d6e7ed616f91faa79cf9ed07613e2c1fc53b247aac8d",
85
86
  "schemas/objective.schema.json": "sha256:94404dc95d04a6641ea7b9654317d0222793251ad44d3dfd2875738622a36025",
86
- "schemas/observation.schema.json": "sha256:bdf0c16230d3666e9dba8f9110d45944e5f7e94c37ac51e483a879628c30ce77",
87
+ "schemas/observation.schema.json": "sha256:a5daabab86dacaa1a81e1f4c4900a0332bb3bf657ffeed60e5c6e0c5a8e5b7da",
87
88
  "schemas/page.schema.json": "sha256:11d116b22ab79c152cfc7bbbec3a00cebe6dcd8ea2845b0ce819c15111fb0166",
88
89
  "schemas/project.schema.json": "sha256:ea48fdb6480f7047ba4594bd5908bc1f79c1ad6b9a2c204df900959b5f203dc6",
89
90
  "schemas/prompt-result.schema.json": "sha256:b55be47d7d58d7b1dd8c3b1e849e24e55216212c592cde7eb836953379b85737",
@@ -100,13 +101,13 @@
100
101
  "schemas/run.schema.json": "sha256:46c3178620f3a358d936d535aeadb83454b9b35b551e53e6615cc9862063dacb",
101
102
  "schemas/sampling-plan.schema.json": "sha256:005f70f149baaacd7de698548d556d3e401c630978748271b0e14a74726dd413",
102
103
  "schemas/scenario.schema.json": "sha256:3f5bc2032d08f973600db068f475176a0e4706b33be42f99c778fe755a0ff38b",
103
- "schemas/schedule.schema.json": "sha256:0f02174ab0fc7bbbce9759fd358b18ed97cc683c76933fd3001cf053c499b157",
104
+ "schemas/schedule.schema.json": "sha256:645df065bf33577a960c0bf8bb97e141e9326840303569468dae8a553d468482",
104
105
  "schemas/source-identity-chain.schema.json": "sha256:a65d9c12eaed1bd6b637c66a2f9362c17287fdfcb454d8676fb611d2d28aa019",
105
106
  "schemas/variance.schema.json": "sha256:68389f64f0a3be13ff8951e8eefba9a5c31d0738325cb47e37c1a8435bea48f0",
106
107
  "scripts/README.md": "sha256:9eee4e8beb4579a183bd714c9dd24b83abd020753eada5caeffae004739d60b5",
107
- "SKILL.md": "sha256:8211b720ae293517fb1d23260ab3d0d39d7228f20f442f6f642513c708cf1954",
108
+ "SKILL.md": "sha256:b1aaeca8a5b2489e904d6d68491b9df409b5ec4599868e91892bb70c13771422",
108
109
  "templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
109
- "VERSION": "sha256:bb0df1bd902faba507c15975eb9973e695f2732f760d851b4f9c7ba17068f5ff"
110
+ "VERSION": "sha256:d5b1f46669d1cff3be556b1656732c8777ad8ad3f3d05459cfb11dadb1f17d19"
110
111
  },
111
- "treeHash": "sha256:1045c67e6f937af236960d4c12fbc3f87c969b405b3559522dd6a1e7342cd924"
112
+ "treeHash": "sha256:d0e363afa74d831ac7721911acf254eb3c8b613d3c56cc55b596d99c789cc7c7"
112
113
  }
@@ -7,7 +7,7 @@
7
7
  "required": ["observation_id", "kind", "state", "collected_at", "collection_method", "confidence", "source", "evidence_hash", "data"],
8
8
  "properties": {
9
9
  "observation_id": { "type": "string", "minLength": 1 },
10
- "kind": { "type": "string", "enum": ["render", "browser_journey", "index", "citation", "citation_review", "crawler_log", "crawler_probe", "regional_network", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric", "media_pdf", "media_transcript", "media_image", "representation_drift"] },
10
+ "kind": { "type": "string", "enum": ["render", "browser_journey", "index", "citation", "citation_review", "crawler_log", "crawler_probe", "regional_network", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric", "media_pdf", "media_transcript", "media_image", "representation_drift", "stance"] },
11
11
  "state": { "type": "string", "enum": ["observed", "not_observed", "not_evidenced", "incomplete", "review_required", "failed"] },
12
12
  "collected_at": { "type": "string", "format": "date-time" },
13
13
  "collection_method": { "type": "string", "enum": ["live_api", "browser", "owner_import", "synthetic_fetch", "static_analysis", "human_review"] },
@@ -1,4 +1,4 @@
1
1
  {
2
2
  "$id":"citable://schemas/schedule.schema.json","$schema":"http://json-schema.org/draft-07/schema#","title":"Audit schedule registry","type":"object","additionalProperties":false,"required":["version","kind","updated","entries"],
3
- "properties":{"version":{"const":1},"kind":{"const":"schedules"},"updated":{"type":"string","format":"date-time"},"entries":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["schedule_id","name","status","cron","owner","expected_tool_version","audit","retention_days","limitations"],"properties":{"schedule_id":{"type":"string","pattern":"^SCHEDULE-[A-Z0-9][A-Z0-9_-]*$"},"name":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","paused","retired"]},"cron":{"type":"string","minLength":5},"owner":{"type":"string","minLength":1},"expected_tool_version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+$"},"audit":{"type":"object","additionalProperties":false,"required":["target","scope"],"properties":{"target":{"type":"string","minLength":1},"scope":{"type":["string","null"]},"base_url":{"type":["string","null"]}}},"retention_days":{"type":"integer","minimum":1},"limitations":{"type":"array","minItems":1,"items":{"type":"string"}}}}}}
3
+ "properties":{"version":{"const":1},"kind":{"const":"schedules"},"updated":{"type":"string","format":"date-time"},"entries":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["schedule_id","name","status","cron","owner","expected_tool_version","audit","retention_days","limitations"],"properties":{"schedule_id":{"type":"string","pattern":"^SCHEDULE-[A-Z0-9][A-Z0-9_-]*$"},"name":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","paused","retired"]},"cron":{"type":"string","minLength":5},"owner":{"type":"string","minLength":1},"expected_tool_version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+$"},"audit":{"type":"object","additionalProperties":false,"required":["target","scope"],"properties":{"target":{"type":"string","minLength":1},"scope":{"type":["string","null"]},"base_url":{"type":["string","null"]}}},"monitor":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"webhook_url":{"type":"string"},"min_severity":{"type":"string","enum":["informational","medium","high","critical"]}}},"retention_days":{"type":"integer","minimum":1},"limitations":{"type":"array","minItems":1,"items":{"type":"string"}}}}}}
4
4
  }
@@ -7,7 +7,7 @@ description: >
7
7
  generative engine optimization, structured data governance, claim substantiation,
8
8
  crawler policy, entity consistency, content discoverability, or wants a site audited
9
9
  for how search and AI systems will retrieve, understand, cite, or recommend it.
10
- version: 1.14.0
10
+ version: 1.15.0
11
11
  ---
12
12
 
13
13
  # Citable — evidence and change control for search and AI citation readiness
@@ -95,7 +95,8 @@ citable schema --target <dir|url>
95
95
  citable validate [registries|claims|evidence|schema|links]
96
96
  citable compare-snapshots [runA runB]
97
97
  citable action-plan [run-id] # ordered actions, blockers, semantic gates, verification
98
- citable observe <mode> [options] # render/index/citation/log/probe/passage/consensus/performance evidence
98
+ citable observe <mode> [options] # render/index/citation/log/probe/passage/consensus/performance/stance evidence
99
+ citable observe stance --input <citations|prompts.json> [--entity <id>]
99
100
  citable observe bing --dataset <search_performance|ai_performance> --input <csv|json>
100
101
  citable observe probes --target <url> [--region <label>]
101
102
  citable observe network --input <regional-network-import.json>
@@ -103,13 +104,17 @@ citable observe render --target <url> [--interactions] [--resume-run <run-id>]
103
104
  citable observe render --input <browser-evidence-plan.json>
104
105
  citable observe performance --target <url> --lighthouse [--repeat 1..5]
105
106
  citable apply --input <spec> [--write] # reviewed, hash-locked remediation; dry run by default
106
- citable monitor [runA runB] # observation regression alerts
107
+ citable monitor [runA runB] [--webhook <url>] [--min-severity <sev>] # observation regression alerts
108
+ citable report dashboard [--last N] [--since <run-id>] # cross-run evidence trend (Markdown + HTML)
109
+ citable report share-of-voice [--last N] [--since <run-id>] # competitor citation share (Markdown + HTML)
107
110
  citable metrics import --provider <name> --input <csv|json>
108
111
  citable connect status
109
- citable connect configure --provider <gsc|ga4> --connection-id <id> --property-id <id> [--credential-env <name>] [--write]
110
- citable connect discover --provider <gsc|ga4>
112
+ citable connect configure --provider <gsc|ga4|wordpress|webflow> --connection-id <id> --property-id <id> [--credential-env <name>] [--write]
113
+ citable connect discover --provider <gsc|ga4|wordpress|webflow>
111
114
  citable connect validate --connection-id <id>
112
115
  citable connect sync --connection-id <id> --start-date YYYY-MM-DD --end-date YYYY-MM-DD
116
+ citable connect read --connection-id <id> --target-id <id>
117
+ citable connect apply --connection-id <id> --input <cms-spec.json> [--write]
113
118
  citable connect disconnect --connection-id <id> [--write]
114
119
  citable objectives init --input <json|yaml> [--write]
115
120
  citable objectives validate
@@ -121,7 +126,7 @@ citable reviews prioritize [--write]
121
126
  citable reviews plan --input <json|yaml> [--write]
122
127
  citable reviews sample <sampling-plan-id> [--write]
123
128
  citable reviews evaluate
124
- citable schedules run <schedule-id> [--ref-date YYYY-MM-DD]
129
+ citable schedules run <schedule-id> [--ref-date YYYY-MM-DD] [--monitor] [--webhook <url>]
125
130
  citable project github <run-id>
126
131
  citable observe media --input <manifest.json> [--ocr]
127
132
  citable observe representation --input <release-manifest.json> --target <controlled-url>
@@ -1 +1 @@
1
- 1.14.0
1
+ 1.15.0
@@ -21,9 +21,12 @@ intent, not executability, so statuses are strict:
21
21
  | /citable validate, validate-claims, validate-evidence, validate-schema, validate-links | implemented |
22
22
  | /citable compare-snapshots / validate-regression | implemented |
23
23
  | /citable action-plan | implemented — writes ordered, source-run-bound action artifacts outside immutable evidence packages |
24
- | /citable observe | implemented — render, index, citation, crawler-log, passage, consensus, performance, and corroboration evidence |
24
+ | /citable observe | implemented — render, index, citation, crawler-log, passage, consensus, performance, corroboration, and stance evidence |
25
25
  | /citable apply | implemented — reviewed, hash-locked source replacements; dry run by default |
26
+ | /citable connect status / configure / discover / validate / sync / read / apply / disconnect | implemented — GA4, GSC, WordPress, and Webflow adapters with hash-locked CMS remediation |
26
27
  | /citable monitor | implemented — compares immutable observation runs and emits evidence-linked alerts |
28
+ | /citable report dashboard | implemented — folds each run's recorded summary into a cross-run Markdown/HTML trend; derives no new findings and no combined score |
29
+ | /citable report share-of-voice | implemented — joins competitor registry against recorded citation observations to compute verified share-of-citation |
27
30
  | /citable metrics import | implemented — validates declared CSV/JSON metrics and writes immutable observations |
28
31
  | /citable objectives init / validate | implemented — user-owned metric selection, cohorts, windows, and guardrails |
29
32
  | /citable evaluate | implemented — independent baseline/evaluation comparisons with inconclusive handling |
@@ -91,9 +91,16 @@ reviewer, matches the exact file hash, and identifies exactly one source string.
91
91
  `--write` applies only after all operations validate. Build, tests, semantic
92
92
  review, re-audit, and snapshot comparison remain mandatory afterward.
93
93
 
94
- ## Monitoring
94
+ ## Monitoring and alert delivery
95
95
 
96
- `monitor [runA runB]` reports state changes, missing observations, index loss,
97
- canonical disagreement, and citation-presence changes. Alerts are evidence
98
- changes, not causal explanations or ranking conclusions. Schedule it in CI at
99
- the cadence defined by lifecycle and experiment records.
96
+ `monitor [runA runB] [--webhook <url>] [--min-severity <level>]` reports state
97
+ changes, missing observations, index loss, canonical disagreement, and
98
+ citation-presence changes. With `--webhook`, detected regressions matching or
99
+ exceeding `--min-severity` (default `medium`) are dispatched as sealed JSON
100
+ alert payloads and logged under `.citable/monitoring/deliveries/`. Destination
101
+ URLs must be public network destinations (private/loopback addresses are blocked).
102
+ Alerts are evidence changes, not causal explanations or ranking conclusions.
103
+
104
+ Scheduled monitoring (`schedules run <id> --monitor [--webhook <url>]`) automatically
105
+ compares the scheduled audit against the preceding baseline run and dispatches
106
+ regression alerts when configured in `schedules.yaml`.
@@ -0,0 +1,57 @@
1
+ ---
2
+ command: /citable report dashboard [--last N] [--since <run-id>]
3
+ purpose: Fold the summary each audit run already recorded into a cross-run Markdown table and self-contained HTML page without deriving new findings, scores, or causal explanations.
4
+ preconditions: [at least one finalized audit run under .citable/runs/ with a summary.json]
5
+ failure_behaviour: fewer than two audit runs -> explicit insufficient-history state, not a trend; unreadable summary or manifest -> run reported under skipped runs; non-integer --last -> fail
6
+ artifacts_created: [.citable/reports/dashboard.md, .citable/reports/dashboard.html]
7
+ ---
8
+
9
+ # Cross-run evidence reporting
10
+
11
+ 1. Run `citable report dashboard` to read severity counts, retrieval
12
+ eligibility, source extraction and support, and observed citation presence
13
+ rate across run history. Every value is copied from a run's own
14
+ `summary.json`. The command runs no detector, opens no network connection,
15
+ and never edits an immutable run package.
16
+ 2. Treat the output as derived, not canonical. It is written to
17
+ `.citable/reports/`, alongside `monitor` and `action-plan` derived
18
+ artifacts. The evidence of record remains `.citable/runs/<run-id>/`.
19
+ 3. Window the history with `--since <run-id>` (keeps that run and everything
20
+ after it) and `--last N` (keeps the final N runs). Run IDs sort
21
+ chronologically, so both filters are deterministic.
22
+ 4. Read fewer than two runs as no trend. With zero or one run the dashboard
23
+ states insufficient history explicitly instead of drawing a line through a
24
+ single point. Direction, rate of change, and improvement are not established
25
+ by one observation.
26
+ 5. Read skipped runs as a gap in the series, not as absence of a problem. A run
27
+ whose `summary.json` or `manifest.json` cannot be parsed, and an observation
28
+ run whose summary records no severity or posture, is listed with its reason
29
+ rather than counted as zero findings.
30
+ 6. Read a falling count as an observed difference between runs, not as proof
31
+ that a condition was fixed. Use `citable compare-snapshots` to establish
32
+ whether two runs are comparable at all — detector set, configuration,
33
+ observation method, and tool version all change what a count means.
34
+
35
+ # Refusal boundary
36
+
37
+ Do not present the dashboard as an AI visibility score, a ranking forecast, or
38
+ a measure of citation likelihood. The three posture dimensions are reported
39
+ separately and are never combined into a single number. Do not interpolate,
40
+ estimate, or carry forward a missing value: a run with no evidenced citation
41
+ presence rate is omitted from that trend line, not filled in. Do not attribute
42
+ any observed change to a specific intervention.
43
+
44
+ # Share of voice and competitor reporting
45
+
46
+ 1. Run `citable report share-of-voice [--last N] [--since <run-id>]` to evaluate
47
+ first-party and competitor citation presence and share across recorded
48
+ `observe citation` runs.
49
+ 2. Contested competitor domains are loaded from `.citable/competitors.yaml`.
50
+ Citations whose canonical URL matches declared competitor domains are joined
51
+ into per-prompt and aggregate shares.
52
+ 3. Competitor share is calculated strictly from evidenced observations; missing
53
+ observations or unevaluated prompts are never filled with fabricated zeros or
54
+ interpolated estimates.
55
+ 4. Outputs are written to `.citable/reports/share-of-voice.md` and
56
+ `.citable/reports/share-of-voice.html`.
57
+
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "citable",
3
- "version": "1.14.0",
3
+ "version": "1.15.0",
4
4
  "managedBy": "citable-cli",
5
5
  "provider": "kiro",
6
6
  "providerName": "Kiro",
7
7
  "scope": "bundle",
8
- "sourcePackage": "@nebulacomponents/citable@1.14.0",
8
+ "sourcePackage": "@nebulacomponents/citable@1.15.0",
9
9
  "variantPath": ".kiro/skills/citable",
10
10
  "agentProfiles": {
11
11
  "status": "unsupported",
@@ -22,11 +22,12 @@
22
22
  "commands/ingest.md": "sha256:cf35659aecd9d0e160909003efdbe056864fc5d824c71b4ef0ee801ce07ff598",
23
23
  "commands/measurement.md": "sha256:9cade6dfec23338e18aa67ede3335ac9e2888dc577a7d4d8e3ceac948bce403f",
24
24
  "commands/media-evidence.md": "sha256:f2218feabe3360a2c9d569a5fa9b70d4b33a83a270d657151635e6f404fb34e0",
25
- "commands/observe-and-act.md": "sha256:847d35aa6cd5b32dea4cd82fd4a5e84343676fd7e45c5e3a10393a00f6b288a7",
25
+ "commands/observe-and-act.md": "sha256:32ad048f14610de0e9a00a7faf27ff18ec0d892f5b20d568f519e44a7ffc0faf",
26
26
  "commands/optimize-page.md": "sha256:35866f3d7cdeef0376ea7a7d7036085a9b9cf95bbb300ecf4bd77610ebd74d85",
27
27
  "commands/page-work.md": "sha256:965a66e59bdf7b0da482d26fade53b3d265885ece5d463fe83b0789ebefaef3e",
28
28
  "commands/plan-audit.md": "sha256:69875c9654e13b84566dafb16afe5afe08cffb9f3bded1f2d8d2261ae871c869",
29
- "commands/README.md": "sha256:c27f69e0e33712e00f780c0988c7b033650c17d3450baea33f2b14212be8438e",
29
+ "commands/README.md": "sha256:a8242f715219a549ad4b40a3573b62e1d2249a76a3162622e0cd61f80682d971",
30
+ "commands/reporting.md": "sha256:b4e7003d291180ddac574915ebc17a05faac0a72acf5ae2f21bcaa59d273e7ad",
30
31
  "commands/reviews.md": "sha256:902904aaa405fe5724cf0662c7a5a36eab9a4fe0eb81cbd95ffa2fff946e0ac8",
31
32
  "commands/validate-render.md": "sha256:a8e1d04d40b84d57c35039250d98c6a7302cd44a148a8c3b9d9cfb92678c4347",
32
33
  "policies/crawler-policy-template.md": "sha256:15c88a4eeb21f53f71e5250dd3eb2d2791a814b304eaefce8bb30e2bdf2e2e59",
@@ -83,7 +84,7 @@
83
84
  "schemas/media-manifest.schema.json": "sha256:3f37301aab9e913fa7febb15c720ed6384b106f12cef8d26cdd12d93fd85b41f",
84
85
  "schemas/metric.schema.json": "sha256:2ada648e7274a8d78cc9d6e7ed616f91faa79cf9ed07613e2c1fc53b247aac8d",
85
86
  "schemas/objective.schema.json": "sha256:94404dc95d04a6641ea7b9654317d0222793251ad44d3dfd2875738622a36025",
86
- "schemas/observation.schema.json": "sha256:bdf0c16230d3666e9dba8f9110d45944e5f7e94c37ac51e483a879628c30ce77",
87
+ "schemas/observation.schema.json": "sha256:a5daabab86dacaa1a81e1f4c4900a0332bb3bf657ffeed60e5c6e0c5a8e5b7da",
87
88
  "schemas/page.schema.json": "sha256:11d116b22ab79c152cfc7bbbec3a00cebe6dcd8ea2845b0ce819c15111fb0166",
88
89
  "schemas/project.schema.json": "sha256:ea48fdb6480f7047ba4594bd5908bc1f79c1ad6b9a2c204df900959b5f203dc6",
89
90
  "schemas/prompt-result.schema.json": "sha256:b55be47d7d58d7b1dd8c3b1e849e24e55216212c592cde7eb836953379b85737",
@@ -100,13 +101,13 @@
100
101
  "schemas/run.schema.json": "sha256:46c3178620f3a358d936d535aeadb83454b9b35b551e53e6615cc9862063dacb",
101
102
  "schemas/sampling-plan.schema.json": "sha256:005f70f149baaacd7de698548d556d3e401c630978748271b0e14a74726dd413",
102
103
  "schemas/scenario.schema.json": "sha256:3f5bc2032d08f973600db068f475176a0e4706b33be42f99c778fe755a0ff38b",
103
- "schemas/schedule.schema.json": "sha256:0f02174ab0fc7bbbce9759fd358b18ed97cc683c76933fd3001cf053c499b157",
104
+ "schemas/schedule.schema.json": "sha256:645df065bf33577a960c0bf8bb97e141e9326840303569468dae8a553d468482",
104
105
  "schemas/source-identity-chain.schema.json": "sha256:a65d9c12eaed1bd6b637c66a2f9362c17287fdfcb454d8676fb611d2d28aa019",
105
106
  "schemas/variance.schema.json": "sha256:68389f64f0a3be13ff8951e8eefba9a5c31d0738325cb47e37c1a8435bea48f0",
106
107
  "scripts/README.md": "sha256:9eee4e8beb4579a183bd714c9dd24b83abd020753eada5caeffae004739d60b5",
107
- "SKILL.md": "sha256:8211b720ae293517fb1d23260ab3d0d39d7228f20f442f6f642513c708cf1954",
108
+ "SKILL.md": "sha256:b1aaeca8a5b2489e904d6d68491b9df409b5ec4599868e91892bb70c13771422",
108
109
  "templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
109
- "VERSION": "sha256:bb0df1bd902faba507c15975eb9973e695f2732f760d851b4f9c7ba17068f5ff"
110
+ "VERSION": "sha256:d5b1f46669d1cff3be556b1656732c8777ad8ad3f3d05459cfb11dadb1f17d19"
110
111
  },
111
- "treeHash": "sha256:1045c67e6f937af236960d4c12fbc3f87c969b405b3559522dd6a1e7342cd924"
112
+ "treeHash": "sha256:d0e363afa74d831ac7721911acf254eb3c8b613d3c56cc55b596d99c789cc7c7"
112
113
  }
@@ -7,7 +7,7 @@
7
7
  "required": ["observation_id", "kind", "state", "collected_at", "collection_method", "confidence", "source", "evidence_hash", "data"],
8
8
  "properties": {
9
9
  "observation_id": { "type": "string", "minLength": 1 },
10
- "kind": { "type": "string", "enum": ["render", "browser_journey", "index", "citation", "citation_review", "crawler_log", "crawler_probe", "regional_network", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric", "media_pdf", "media_transcript", "media_image", "representation_drift"] },
10
+ "kind": { "type": "string", "enum": ["render", "browser_journey", "index", "citation", "citation_review", "crawler_log", "crawler_probe", "regional_network", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric", "media_pdf", "media_transcript", "media_image", "representation_drift", "stance"] },
11
11
  "state": { "type": "string", "enum": ["observed", "not_observed", "not_evidenced", "incomplete", "review_required", "failed"] },
12
12
  "collected_at": { "type": "string", "format": "date-time" },
13
13
  "collection_method": { "type": "string", "enum": ["live_api", "browser", "owner_import", "synthetic_fetch", "static_analysis", "human_review"] },
@@ -1,4 +1,4 @@
1
1
  {
2
2
  "$id":"citable://schemas/schedule.schema.json","$schema":"http://json-schema.org/draft-07/schema#","title":"Audit schedule registry","type":"object","additionalProperties":false,"required":["version","kind","updated","entries"],
3
- "properties":{"version":{"const":1},"kind":{"const":"schedules"},"updated":{"type":"string","format":"date-time"},"entries":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["schedule_id","name","status","cron","owner","expected_tool_version","audit","retention_days","limitations"],"properties":{"schedule_id":{"type":"string","pattern":"^SCHEDULE-[A-Z0-9][A-Z0-9_-]*$"},"name":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","paused","retired"]},"cron":{"type":"string","minLength":5},"owner":{"type":"string","minLength":1},"expected_tool_version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+$"},"audit":{"type":"object","additionalProperties":false,"required":["target","scope"],"properties":{"target":{"type":"string","minLength":1},"scope":{"type":["string","null"]},"base_url":{"type":["string","null"]}}},"retention_days":{"type":"integer","minimum":1},"limitations":{"type":"array","minItems":1,"items":{"type":"string"}}}}}}
3
+ "properties":{"version":{"const":1},"kind":{"const":"schedules"},"updated":{"type":"string","format":"date-time"},"entries":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["schedule_id","name","status","cron","owner","expected_tool_version","audit","retention_days","limitations"],"properties":{"schedule_id":{"type":"string","pattern":"^SCHEDULE-[A-Z0-9][A-Z0-9_-]*$"},"name":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","paused","retired"]},"cron":{"type":"string","minLength":5},"owner":{"type":"string","minLength":1},"expected_tool_version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+$"},"audit":{"type":"object","additionalProperties":false,"required":["target","scope"],"properties":{"target":{"type":"string","minLength":1},"scope":{"type":["string","null"]},"base_url":{"type":["string","null"]}}},"monitor":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"webhook_url":{"type":"string"},"min_severity":{"type":"string","enum":["informational","medium","high","critical"]}}},"retention_days":{"type":"integer","minimum":1},"limitations":{"type":"array","minItems":1,"items":{"type":"string"}}}}}}
4
4
  }
@@ -7,7 +7,7 @@ description: >
7
7
  generative engine optimization, structured data governance, claim substantiation,
8
8
  crawler policy, entity consistency, content discoverability, or wants a site audited
9
9
  for how search and AI systems will retrieve, understand, cite, or recommend it.
10
- version: 1.14.0
10
+ version: 1.15.0
11
11
  ---
12
12
 
13
13
  # Citable — evidence and change control for search and AI citation readiness
@@ -95,7 +95,8 @@ citable schema --target <dir|url>
95
95
  citable validate [registries|claims|evidence|schema|links]
96
96
  citable compare-snapshots [runA runB]
97
97
  citable action-plan [run-id] # ordered actions, blockers, semantic gates, verification
98
- citable observe <mode> [options] # render/index/citation/log/probe/passage/consensus/performance evidence
98
+ citable observe <mode> [options] # render/index/citation/log/probe/passage/consensus/performance/stance evidence
99
+ citable observe stance --input <citations|prompts.json> [--entity <id>]
99
100
  citable observe bing --dataset <search_performance|ai_performance> --input <csv|json>
100
101
  citable observe probes --target <url> [--region <label>]
101
102
  citable observe network --input <regional-network-import.json>
@@ -103,13 +104,17 @@ citable observe render --target <url> [--interactions] [--resume-run <run-id>]
103
104
  citable observe render --input <browser-evidence-plan.json>
104
105
  citable observe performance --target <url> --lighthouse [--repeat 1..5]
105
106
  citable apply --input <spec> [--write] # reviewed, hash-locked remediation; dry run by default
106
- citable monitor [runA runB] # observation regression alerts
107
+ citable monitor [runA runB] [--webhook <url>] [--min-severity <sev>] # observation regression alerts
108
+ citable report dashboard [--last N] [--since <run-id>] # cross-run evidence trend (Markdown + HTML)
109
+ citable report share-of-voice [--last N] [--since <run-id>] # competitor citation share (Markdown + HTML)
107
110
  citable metrics import --provider <name> --input <csv|json>
108
111
  citable connect status
109
- citable connect configure --provider <gsc|ga4> --connection-id <id> --property-id <id> [--credential-env <name>] [--write]
110
- citable connect discover --provider <gsc|ga4>
112
+ citable connect configure --provider <gsc|ga4|wordpress|webflow> --connection-id <id> --property-id <id> [--credential-env <name>] [--write]
113
+ citable connect discover --provider <gsc|ga4|wordpress|webflow>
111
114
  citable connect validate --connection-id <id>
112
115
  citable connect sync --connection-id <id> --start-date YYYY-MM-DD --end-date YYYY-MM-DD
116
+ citable connect read --connection-id <id> --target-id <id>
117
+ citable connect apply --connection-id <id> --input <cms-spec.json> [--write]
113
118
  citable connect disconnect --connection-id <id> [--write]
114
119
  citable objectives init --input <json|yaml> [--write]
115
120
  citable objectives validate
@@ -121,7 +126,7 @@ citable reviews prioritize [--write]
121
126
  citable reviews plan --input <json|yaml> [--write]
122
127
  citable reviews sample <sampling-plan-id> [--write]
123
128
  citable reviews evaluate
124
- citable schedules run <schedule-id> [--ref-date YYYY-MM-DD]
129
+ citable schedules run <schedule-id> [--ref-date YYYY-MM-DD] [--monitor] [--webhook <url>]
125
130
  citable project github <run-id>
126
131
  citable observe media --input <manifest.json> [--ocr]
127
132
  citable observe representation --input <release-manifest.json> --target <controlled-url>
@@ -1 +1 @@
1
- 1.14.0
1
+ 1.15.0
@@ -21,9 +21,12 @@ intent, not executability, so statuses are strict:
21
21
  | /citable validate, validate-claims, validate-evidence, validate-schema, validate-links | implemented |
22
22
  | /citable compare-snapshots / validate-regression | implemented |
23
23
  | /citable action-plan | implemented — writes ordered, source-run-bound action artifacts outside immutable evidence packages |
24
- | /citable observe | implemented — render, index, citation, crawler-log, passage, consensus, performance, and corroboration evidence |
24
+ | /citable observe | implemented — render, index, citation, crawler-log, passage, consensus, performance, corroboration, and stance evidence |
25
25
  | /citable apply | implemented — reviewed, hash-locked source replacements; dry run by default |
26
+ | /citable connect status / configure / discover / validate / sync / read / apply / disconnect | implemented — GA4, GSC, WordPress, and Webflow adapters with hash-locked CMS remediation |
26
27
  | /citable monitor | implemented — compares immutable observation runs and emits evidence-linked alerts |
28
+ | /citable report dashboard | implemented — folds each run's recorded summary into a cross-run Markdown/HTML trend; derives no new findings and no combined score |
29
+ | /citable report share-of-voice | implemented — joins competitor registry against recorded citation observations to compute verified share-of-citation |
27
30
  | /citable metrics import | implemented — validates declared CSV/JSON metrics and writes immutable observations |
28
31
  | /citable objectives init / validate | implemented — user-owned metric selection, cohorts, windows, and guardrails |
29
32
  | /citable evaluate | implemented — independent baseline/evaluation comparisons with inconclusive handling |
@@ -91,9 +91,16 @@ reviewer, matches the exact file hash, and identifies exactly one source string.
91
91
  `--write` applies only after all operations validate. Build, tests, semantic
92
92
  review, re-audit, and snapshot comparison remain mandatory afterward.
93
93
 
94
- ## Monitoring
94
+ ## Monitoring and alert delivery
95
95
 
96
- `monitor [runA runB]` reports state changes, missing observations, index loss,
97
- canonical disagreement, and citation-presence changes. Alerts are evidence
98
- changes, not causal explanations or ranking conclusions. Schedule it in CI at
99
- the cadence defined by lifecycle and experiment records.
96
+ `monitor [runA runB] [--webhook <url>] [--min-severity <level>]` reports state
97
+ changes, missing observations, index loss, canonical disagreement, and
98
+ citation-presence changes. With `--webhook`, detected regressions matching or
99
+ exceeding `--min-severity` (default `medium`) are dispatched as sealed JSON
100
+ alert payloads and logged under `.citable/monitoring/deliveries/`. Destination
101
+ URLs must be public network destinations (private/loopback addresses are blocked).
102
+ Alerts are evidence changes, not causal explanations or ranking conclusions.
103
+
104
+ Scheduled monitoring (`schedules run <id> --monitor [--webhook <url>]`) automatically
105
+ compares the scheduled audit against the preceding baseline run and dispatches
106
+ regression alerts when configured in `schedules.yaml`.
@@ -0,0 +1,57 @@
1
+ ---
2
+ command: /citable report dashboard [--last N] [--since <run-id>]
3
+ purpose: Fold the summary each audit run already recorded into a cross-run Markdown table and self-contained HTML page without deriving new findings, scores, or causal explanations.
4
+ preconditions: [at least one finalized audit run under .citable/runs/ with a summary.json]
5
+ failure_behaviour: fewer than two audit runs -> explicit insufficient-history state, not a trend; unreadable summary or manifest -> run reported under skipped runs; non-integer --last -> fail
6
+ artifacts_created: [.citable/reports/dashboard.md, .citable/reports/dashboard.html]
7
+ ---
8
+
9
+ # Cross-run evidence reporting
10
+
11
+ 1. Run `citable report dashboard` to read severity counts, retrieval
12
+ eligibility, source extraction and support, and observed citation presence
13
+ rate across run history. Every value is copied from a run's own
14
+ `summary.json`. The command runs no detector, opens no network connection,
15
+ and never edits an immutable run package.
16
+ 2. Treat the output as derived, not canonical. It is written to
17
+ `.citable/reports/`, alongside `monitor` and `action-plan` derived
18
+ artifacts. The evidence of record remains `.citable/runs/<run-id>/`.
19
+ 3. Window the history with `--since <run-id>` (keeps that run and everything
20
+ after it) and `--last N` (keeps the final N runs). Run IDs sort
21
+ chronologically, so both filters are deterministic.
22
+ 4. Read fewer than two runs as no trend. With zero or one run the dashboard
23
+ states insufficient history explicitly instead of drawing a line through a
24
+ single point. Direction, rate of change, and improvement are not established
25
+ by one observation.
26
+ 5. Read skipped runs as a gap in the series, not as absence of a problem. A run
27
+ whose `summary.json` or `manifest.json` cannot be parsed, and an observation
28
+ run whose summary records no severity or posture, is listed with its reason
29
+ rather than counted as zero findings.
30
+ 6. Read a falling count as an observed difference between runs, not as proof
31
+ that a condition was fixed. Use `citable compare-snapshots` to establish
32
+ whether two runs are comparable at all — detector set, configuration,
33
+ observation method, and tool version all change what a count means.
34
+
35
+ # Refusal boundary
36
+
37
+ Do not present the dashboard as an AI visibility score, a ranking forecast, or
38
+ a measure of citation likelihood. The three posture dimensions are reported
39
+ separately and are never combined into a single number. Do not interpolate,
40
+ estimate, or carry forward a missing value: a run with no evidenced citation
41
+ presence rate is omitted from that trend line, not filled in. Do not attribute
42
+ any observed change to a specific intervention.
43
+
44
+ # Share of voice and competitor reporting
45
+
46
+ 1. Run `citable report share-of-voice [--last N] [--since <run-id>]` to evaluate
47
+ first-party and competitor citation presence and share across recorded
48
+ `observe citation` runs.
49
+ 2. Contested competitor domains are loaded from `.citable/competitors.yaml`.
50
+ Citations whose canonical URL matches declared competitor domains are joined
51
+ into per-prompt and aggregate shares.
52
+ 3. Competitor share is calculated strictly from evidenced observations; missing
53
+ observations or unevaluated prompts are never filled with fabricated zeros or
54
+ interpolated estimates.
55
+ 4. Outputs are written to `.citable/reports/share-of-voice.md` and
56
+ `.citable/reports/share-of-voice.html`.
57
+
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "citable",
3
- "version": "1.14.0",
3
+ "version": "1.15.0",
4
4
  "managedBy": "citable-cli",
5
5
  "provider": "opencode",
6
6
  "providerName": "OpenCode",
7
7
  "scope": "bundle",
8
- "sourcePackage": "@nebulacomponents/citable@1.14.0",
8
+ "sourcePackage": "@nebulacomponents/citable@1.15.0",
9
9
  "variantPath": ".opencode/skills/citable",
10
10
  "agentProfiles": {
11
11
  "status": "unsupported",
@@ -22,11 +22,12 @@
22
22
  "commands/ingest.md": "sha256:cf35659aecd9d0e160909003efdbe056864fc5d824c71b4ef0ee801ce07ff598",
23
23
  "commands/measurement.md": "sha256:9cade6dfec23338e18aa67ede3335ac9e2888dc577a7d4d8e3ceac948bce403f",
24
24
  "commands/media-evidence.md": "sha256:f2218feabe3360a2c9d569a5fa9b70d4b33a83a270d657151635e6f404fb34e0",
25
- "commands/observe-and-act.md": "sha256:847d35aa6cd5b32dea4cd82fd4a5e84343676fd7e45c5e3a10393a00f6b288a7",
25
+ "commands/observe-and-act.md": "sha256:32ad048f14610de0e9a00a7faf27ff18ec0d892f5b20d568f519e44a7ffc0faf",
26
26
  "commands/optimize-page.md": "sha256:35866f3d7cdeef0376ea7a7d7036085a9b9cf95bbb300ecf4bd77610ebd74d85",
27
27
  "commands/page-work.md": "sha256:965a66e59bdf7b0da482d26fade53b3d265885ece5d463fe83b0789ebefaef3e",
28
28
  "commands/plan-audit.md": "sha256:69875c9654e13b84566dafb16afe5afe08cffb9f3bded1f2d8d2261ae871c869",
29
- "commands/README.md": "sha256:c27f69e0e33712e00f780c0988c7b033650c17d3450baea33f2b14212be8438e",
29
+ "commands/README.md": "sha256:a8242f715219a549ad4b40a3573b62e1d2249a76a3162622e0cd61f80682d971",
30
+ "commands/reporting.md": "sha256:b4e7003d291180ddac574915ebc17a05faac0a72acf5ae2f21bcaa59d273e7ad",
30
31
  "commands/reviews.md": "sha256:902904aaa405fe5724cf0662c7a5a36eab9a4fe0eb81cbd95ffa2fff946e0ac8",
31
32
  "commands/validate-render.md": "sha256:a8e1d04d40b84d57c35039250d98c6a7302cd44a148a8c3b9d9cfb92678c4347",
32
33
  "policies/crawler-policy-template.md": "sha256:15c88a4eeb21f53f71e5250dd3eb2d2791a814b304eaefce8bb30e2bdf2e2e59",
@@ -83,7 +84,7 @@
83
84
  "schemas/media-manifest.schema.json": "sha256:3f37301aab9e913fa7febb15c720ed6384b106f12cef8d26cdd12d93fd85b41f",
84
85
  "schemas/metric.schema.json": "sha256:2ada648e7274a8d78cc9d6e7ed616f91faa79cf9ed07613e2c1fc53b247aac8d",
85
86
  "schemas/objective.schema.json": "sha256:94404dc95d04a6641ea7b9654317d0222793251ad44d3dfd2875738622a36025",
86
- "schemas/observation.schema.json": "sha256:bdf0c16230d3666e9dba8f9110d45944e5f7e94c37ac51e483a879628c30ce77",
87
+ "schemas/observation.schema.json": "sha256:a5daabab86dacaa1a81e1f4c4900a0332bb3bf657ffeed60e5c6e0c5a8e5b7da",
87
88
  "schemas/page.schema.json": "sha256:11d116b22ab79c152cfc7bbbec3a00cebe6dcd8ea2845b0ce819c15111fb0166",
88
89
  "schemas/project.schema.json": "sha256:ea48fdb6480f7047ba4594bd5908bc1f79c1ad6b9a2c204df900959b5f203dc6",
89
90
  "schemas/prompt-result.schema.json": "sha256:b55be47d7d58d7b1dd8c3b1e849e24e55216212c592cde7eb836953379b85737",
@@ -100,13 +101,13 @@
100
101
  "schemas/run.schema.json": "sha256:46c3178620f3a358d936d535aeadb83454b9b35b551e53e6615cc9862063dacb",
101
102
  "schemas/sampling-plan.schema.json": "sha256:005f70f149baaacd7de698548d556d3e401c630978748271b0e14a74726dd413",
102
103
  "schemas/scenario.schema.json": "sha256:3f5bc2032d08f973600db068f475176a0e4706b33be42f99c778fe755a0ff38b",
103
- "schemas/schedule.schema.json": "sha256:0f02174ab0fc7bbbce9759fd358b18ed97cc683c76933fd3001cf053c499b157",
104
+ "schemas/schedule.schema.json": "sha256:645df065bf33577a960c0bf8bb97e141e9326840303569468dae8a553d468482",
104
105
  "schemas/source-identity-chain.schema.json": "sha256:a65d9c12eaed1bd6b637c66a2f9362c17287fdfcb454d8676fb611d2d28aa019",
105
106
  "schemas/variance.schema.json": "sha256:68389f64f0a3be13ff8951e8eefba9a5c31d0738325cb47e37c1a8435bea48f0",
106
107
  "scripts/README.md": "sha256:9eee4e8beb4579a183bd714c9dd24b83abd020753eada5caeffae004739d60b5",
107
- "SKILL.md": "sha256:8211b720ae293517fb1d23260ab3d0d39d7228f20f442f6f642513c708cf1954",
108
+ "SKILL.md": "sha256:b1aaeca8a5b2489e904d6d68491b9df409b5ec4599868e91892bb70c13771422",
108
109
  "templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
109
- "VERSION": "sha256:bb0df1bd902faba507c15975eb9973e695f2732f760d851b4f9c7ba17068f5ff"
110
+ "VERSION": "sha256:d5b1f46669d1cff3be556b1656732c8777ad8ad3f3d05459cfb11dadb1f17d19"
110
111
  },
111
- "treeHash": "sha256:1045c67e6f937af236960d4c12fbc3f87c969b405b3559522dd6a1e7342cd924"
112
+ "treeHash": "sha256:d0e363afa74d831ac7721911acf254eb3c8b613d3c56cc55b596d99c789cc7c7"
112
113
  }
@@ -7,7 +7,7 @@
7
7
  "required": ["observation_id", "kind", "state", "collected_at", "collection_method", "confidence", "source", "evidence_hash", "data"],
8
8
  "properties": {
9
9
  "observation_id": { "type": "string", "minLength": 1 },
10
- "kind": { "type": "string", "enum": ["render", "browser_journey", "index", "citation", "citation_review", "crawler_log", "crawler_probe", "regional_network", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric", "media_pdf", "media_transcript", "media_image", "representation_drift"] },
10
+ "kind": { "type": "string", "enum": ["render", "browser_journey", "index", "citation", "citation_review", "crawler_log", "crawler_probe", "regional_network", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric", "media_pdf", "media_transcript", "media_image", "representation_drift", "stance"] },
11
11
  "state": { "type": "string", "enum": ["observed", "not_observed", "not_evidenced", "incomplete", "review_required", "failed"] },
12
12
  "collected_at": { "type": "string", "format": "date-time" },
13
13
  "collection_method": { "type": "string", "enum": ["live_api", "browser", "owner_import", "synthetic_fetch", "static_analysis", "human_review"] },