@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.
- package/CHANGELOG.md +66 -0
- package/README.md +1 -1
- package/dist/universal/.agents/skills/citable/SKILL.md +11 -6
- package/dist/universal/.agents/skills/citable/VERSION +1 -1
- package/dist/universal/.agents/skills/citable/commands/README.md +4 -1
- package/dist/universal/.agents/skills/citable/commands/observe-and-act.md +12 -5
- package/dist/universal/.agents/skills/citable/commands/reporting.md +57 -0
- package/dist/universal/.agents/skills/citable/manifest.json +10 -9
- package/dist/universal/.agents/skills/citable/schemas/observation.schema.json +1 -1
- package/dist/universal/.agents/skills/citable/schemas/schedule.schema.json +1 -1
- package/dist/universal/.claude/agents/citable/manifest.json +2 -2
- package/dist/universal/.claude/skills/citable/SKILL.md +11 -6
- package/dist/universal/.claude/skills/citable/VERSION +1 -1
- package/dist/universal/.claude/skills/citable/commands/README.md +4 -1
- package/dist/universal/.claude/skills/citable/commands/observe-and-act.md +12 -5
- package/dist/universal/.claude/skills/citable/commands/reporting.md +57 -0
- package/dist/universal/.claude/skills/citable/manifest.json +10 -9
- package/dist/universal/.claude/skills/citable/schemas/observation.schema.json +1 -1
- package/dist/universal/.claude/skills/citable/schemas/schedule.schema.json +1 -1
- package/dist/universal/.cursor/skills/citable/SKILL.md +11 -6
- package/dist/universal/.cursor/skills/citable/VERSION +1 -1
- package/dist/universal/.cursor/skills/citable/commands/README.md +4 -1
- package/dist/universal/.cursor/skills/citable/commands/observe-and-act.md +12 -5
- package/dist/universal/.cursor/skills/citable/commands/reporting.md +57 -0
- package/dist/universal/.cursor/skills/citable/manifest.json +10 -9
- package/dist/universal/.cursor/skills/citable/schemas/observation.schema.json +1 -1
- package/dist/universal/.cursor/skills/citable/schemas/schedule.schema.json +1 -1
- package/dist/universal/.gemini/skills/citable/SKILL.md +11 -6
- package/dist/universal/.gemini/skills/citable/VERSION +1 -1
- package/dist/universal/.gemini/skills/citable/commands/README.md +4 -1
- package/dist/universal/.gemini/skills/citable/commands/observe-and-act.md +12 -5
- package/dist/universal/.gemini/skills/citable/commands/reporting.md +57 -0
- package/dist/universal/.gemini/skills/citable/manifest.json +10 -9
- package/dist/universal/.gemini/skills/citable/schemas/observation.schema.json +1 -1
- package/dist/universal/.gemini/skills/citable/schemas/schedule.schema.json +1 -1
- package/dist/universal/.github/skills/citable/SKILL.md +11 -6
- package/dist/universal/.github/skills/citable/VERSION +1 -1
- package/dist/universal/.github/skills/citable/commands/README.md +4 -1
- package/dist/universal/.github/skills/citable/commands/observe-and-act.md +12 -5
- package/dist/universal/.github/skills/citable/commands/reporting.md +57 -0
- package/dist/universal/.github/skills/citable/manifest.json +10 -9
- package/dist/universal/.github/skills/citable/schemas/observation.schema.json +1 -1
- package/dist/universal/.github/skills/citable/schemas/schedule.schema.json +1 -1
- package/dist/universal/.kiro/skills/citable/SKILL.md +11 -6
- package/dist/universal/.kiro/skills/citable/VERSION +1 -1
- package/dist/universal/.kiro/skills/citable/commands/README.md +4 -1
- package/dist/universal/.kiro/skills/citable/commands/observe-and-act.md +12 -5
- package/dist/universal/.kiro/skills/citable/commands/reporting.md +57 -0
- package/dist/universal/.kiro/skills/citable/manifest.json +10 -9
- package/dist/universal/.kiro/skills/citable/schemas/observation.schema.json +1 -1
- package/dist/universal/.kiro/skills/citable/schemas/schedule.schema.json +1 -1
- package/dist/universal/.opencode/skills/citable/SKILL.md +11 -6
- package/dist/universal/.opencode/skills/citable/VERSION +1 -1
- package/dist/universal/.opencode/skills/citable/commands/README.md +4 -1
- package/dist/universal/.opencode/skills/citable/commands/observe-and-act.md +12 -5
- package/dist/universal/.opencode/skills/citable/commands/reporting.md +57 -0
- package/dist/universal/.opencode/skills/citable/manifest.json +10 -9
- package/dist/universal/.opencode/skills/citable/schemas/observation.schema.json +1 -1
- package/dist/universal/.opencode/skills/citable/schemas/schedule.schema.json +1 -1
- package/dist/universal/.pi/agent/skills/citable/SKILL.md +11 -6
- package/dist/universal/.pi/agent/skills/citable/VERSION +1 -1
- package/dist/universal/.pi/agent/skills/citable/commands/README.md +4 -1
- package/dist/universal/.pi/agent/skills/citable/commands/observe-and-act.md +12 -5
- package/dist/universal/.pi/agent/skills/citable/commands/reporting.md +57 -0
- package/dist/universal/.pi/agent/skills/citable/manifest.json +10 -9
- package/dist/universal/.pi/agent/skills/citable/schemas/observation.schema.json +1 -1
- package/dist/universal/.pi/agent/skills/citable/schemas/schedule.schema.json +1 -1
- package/dist/universal/.qoder/skills/citable/SKILL.md +11 -6
- package/dist/universal/.qoder/skills/citable/VERSION +1 -1
- package/dist/universal/.qoder/skills/citable/commands/README.md +4 -1
- package/dist/universal/.qoder/skills/citable/commands/observe-and-act.md +12 -5
- package/dist/universal/.qoder/skills/citable/commands/reporting.md +57 -0
- package/dist/universal/.qoder/skills/citable/manifest.json +10 -9
- package/dist/universal/.qoder/skills/citable/schemas/observation.schema.json +1 -1
- package/dist/universal/.qoder/skills/citable/schemas/schedule.schema.json +1 -1
- package/dist/universal/.rovodev/skills/citable/SKILL.md +11 -6
- package/dist/universal/.rovodev/skills/citable/VERSION +1 -1
- package/dist/universal/.rovodev/skills/citable/commands/README.md +4 -1
- package/dist/universal/.rovodev/skills/citable/commands/observe-and-act.md +12 -5
- package/dist/universal/.rovodev/skills/citable/commands/reporting.md +57 -0
- package/dist/universal/.rovodev/skills/citable/manifest.json +10 -9
- package/dist/universal/.rovodev/skills/citable/schemas/observation.schema.json +1 -1
- package/dist/universal/.rovodev/skills/citable/schemas/schedule.schema.json +1 -1
- package/dist/universal/.trae/skills/citable/SKILL.md +11 -6
- package/dist/universal/.trae/skills/citable/VERSION +1 -1
- package/dist/universal/.trae/skills/citable/commands/README.md +4 -1
- package/dist/universal/.trae/skills/citable/commands/observe-and-act.md +12 -5
- package/dist/universal/.trae/skills/citable/commands/reporting.md +57 -0
- package/dist/universal/.trae/skills/citable/manifest.json +10 -9
- package/dist/universal/.trae/skills/citable/schemas/observation.schema.json +1 -1
- package/dist/universal/.trae/skills/citable/schemas/schedule.schema.json +1 -1
- package/dist/universal/.trae-cn/skills/citable/SKILL.md +11 -6
- package/dist/universal/.trae-cn/skills/citable/VERSION +1 -1
- package/dist/universal/.trae-cn/skills/citable/commands/README.md +4 -1
- package/dist/universal/.trae-cn/skills/citable/commands/observe-and-act.md +12 -5
- package/dist/universal/.trae-cn/skills/citable/commands/reporting.md +57 -0
- package/dist/universal/.trae-cn/skills/citable/manifest.json +10 -9
- package/dist/universal/.trae-cn/skills/citable/schemas/observation.schema.json +1 -1
- package/dist/universal/.trae-cn/skills/citable/schemas/schedule.schema.json +1 -1
- package/dist/universal/manifest.json +124 -112
- package/package.json +1 -1
- package/schemas/observation.schema.json +1 -1
- package/schemas/schedule.schema.json +1 -1
- package/skill/SKILL.md +11 -6
- package/skill/commands/README.md +4 -1
- package/skill/commands/observe-and-act.md +12 -5
- package/skill/commands/reporting.md +57 -0
- package/src/cli/index.js +78 -11
- package/src/commands/connect.js +29 -0
- package/src/commands/context.js +15 -0
- package/src/commands/delivery.js +86 -2
- package/src/commands/monitor.js +35 -0
- package/src/commands/observe.js +3 -1
- package/src/commands/reportDashboard.js +21 -0
- package/src/commands/reportShareOfVoice.js +60 -0
- package/src/connectors/http.js +6 -3
- package/src/connectors/index.js +3 -1
- package/src/connectors/webflow.js +224 -0
- package/src/connectors/wordpress.js +226 -0
- package/src/detectors/geoReco.js +101 -0
- package/src/monitoring/alertDelivery.js +98 -0
- package/src/observations/common.js +10 -0
- package/src/observations/stance.js +261 -0
- package/src/reporting/dashboard.js +254 -0
- 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.
|
|
3
|
+
"version": "1.15.0",
|
|
4
4
|
"managedBy": "citable-cli",
|
|
5
5
|
"provider": "rovodev",
|
|
6
6
|
"providerName": "Rovo Dev",
|
|
7
7
|
"scope": "bundle",
|
|
8
|
-
"sourcePackage": "@nebulacomponents/citable@1.
|
|
8
|
+
"sourcePackage": "@nebulacomponents/citable@1.15.0",
|
|
9
9
|
"variantPath": ".rovodev/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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
108
|
+
"SKILL.md": "sha256:b1aaeca8a5b2489e904d6d68491b9df409b5ec4599868e91892bb70c13771422",
|
|
108
109
|
"templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
|
|
109
|
-
"VERSION": "sha256:
|
|
110
|
+
"VERSION": "sha256:d5b1f46669d1cff3be556b1656732c8777ad8ad3f3d05459cfb11dadb1f17d19"
|
|
110
111
|
},
|
|
111
|
-
"treeHash": "sha256:
|
|
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.
|
|
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]
|
|
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.
|
|
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
|
|
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]
|
|
97
|
-
|
|
98
|
-
changes
|
|
99
|
-
|
|
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.
|
|
3
|
+
"version": "1.15.0",
|
|
4
4
|
"managedBy": "citable-cli",
|
|
5
5
|
"provider": "trae",
|
|
6
6
|
"providerName": "Trae",
|
|
7
7
|
"scope": "bundle",
|
|
8
|
-
"sourcePackage": "@nebulacomponents/citable@1.
|
|
8
|
+
"sourcePackage": "@nebulacomponents/citable@1.15.0",
|
|
9
9
|
"variantPath": ".trae/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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
108
|
+
"SKILL.md": "sha256:b1aaeca8a5b2489e904d6d68491b9df409b5ec4599868e91892bb70c13771422",
|
|
108
109
|
"templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
|
|
109
|
-
"VERSION": "sha256:
|
|
110
|
+
"VERSION": "sha256:d5b1f46669d1cff3be556b1656732c8777ad8ad3f3d05459cfb11dadb1f17d19"
|
|
110
111
|
},
|
|
111
|
-
"treeHash": "sha256:
|
|
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.
|
|
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]
|
|
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.
|
|
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
|
|
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]
|
|
97
|
-
|
|
98
|
-
changes
|
|
99
|
-
|
|
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.
|
|
3
|
+
"version": "1.15.0",
|
|
4
4
|
"managedBy": "citable-cli",
|
|
5
5
|
"provider": "trae-cn",
|
|
6
6
|
"providerName": "Trae CN",
|
|
7
7
|
"scope": "bundle",
|
|
8
|
-
"sourcePackage": "@nebulacomponents/citable@1.
|
|
8
|
+
"sourcePackage": "@nebulacomponents/citable@1.15.0",
|
|
9
9
|
"variantPath": ".trae-cn/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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
108
|
+
"SKILL.md": "sha256:b1aaeca8a5b2489e904d6d68491b9df409b5ec4599868e91892bb70c13771422",
|
|
108
109
|
"templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
|
|
109
|
-
"VERSION": "sha256:
|
|
110
|
+
"VERSION": "sha256:d5b1f46669d1cff3be556b1656732c8777ad8ad3f3d05459cfb11dadb1f17d19"
|
|
110
111
|
},
|
|
111
|
-
"treeHash": "sha256:
|
|
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"] },
|