@nebulacomponents/citable 0.1.0

package/schemas/prompt-result.schema.json

@@ -0,0 +1,37 @@
+{
+  "$id": "citable://schemas/prompt-result.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Prompt test observation",
+  "type": "object",
+  "required": ["observation_id", "prompt_id", "engine", "prompt_text", "date_time", "locale"],
+  "properties": {
+    "observation_id": { "type": "string" },
+    "prompt_id": { "type": "string" },
+    "engine": { "type": "string" },
+    "model": { "type": ["string", "null"] },
+    "interface": { "type": "string" },
+    "account_state": { "type": "string", "enum": ["clean", "logged_in", "controlled", "unknown"] },
+    "authentication_state": { "type": "string" },
+    "location": { "type": "string" },
+    "locale": { "type": "string" },
+    "language": { "type": "string" },
+    "date_time": { "type": "string" },
+    "prompt_text": { "type": "string" },
+    "prompt_variant": { "type": ["string", "null"] },
+    "follow_up_context": { "type": ["string", "null"] },
+    "answer_text": { "type": "string" },
+    "retrieved_sources": { "type": "array", "items": { "type": "string" } },
+    "citations": { "type": "array", "items": { "type": "string" } },
+    "mention_status": { "type": "string", "enum": ["mentioned", "not_mentioned", "ambiguous"] },
+    "recommendation_status": { "type": "string", "enum": ["recommended", "conditionally_recommended", "not_recommended", "not_applicable", "ambiguous"] },
+    "position": { "type": ["integer", "null"] },
+    "factual_accuracy": { "type": "string", "enum": ["accurate", "partially_accurate", "inaccurate", "not_assessed"] },
+    "entity_confusion": { "type": "boolean" },
+    "material_omissions": { "type": "array", "items": { "type": "string" } },
+    "sentiment": { "type": "string", "enum": ["positive", "neutral", "negative", "mixed", "not_assessed"] },
+    "run_index": { "type": "integer", "minimum": 1 },
+    "runs_in_series": { "type": "integer", "minimum": 1 },
+    "variance_notes": { "type": ["string", "null"] },
+    "evaluator": { "type": "string" }
+  }
+}

package/schemas/prompt.schema.json

@@ -0,0 +1,41 @@
+{
+  "$id": "citable://schemas/prompt.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Prompt registry",
+  "allOf": [{ "$ref": "citable://schemas/common.defs.json#/definitions/registryFile" }],
+  "properties": {
+    "kind": { "const": "prompts" },
+    "entries": { "items": { "$ref": "#/definitions/prompt" } }
+  },
+  "definitions": {
+    "prompt": {
+      "type": "object",
+      "required": ["prompt_id", "canonical_prompt", "prompt_class", "status"],
+      "properties": {
+        "prompt_id": { "$ref": "citable://schemas/common.defs.json#/definitions/id" },
+        "canonical_prompt": { "type": "string", "minLength": 3 },
+        "variants": { "type": "array", "items": { "type": "string" } },
+        "prompt_class": { "type": "string", "enum": ["definition", "problem", "category", "comparison", "recommendation", "evaluation", "objection", "adversarial", "multi_constraint", "follow_up"] },
+        "intent": { "type": "string" },
+        "audiences": { "type": "array", "items": { "type": "string" } },
+        "funnel_stage": { "type": "string" },
+        "target_entities": { "type": "array", "items": { "type": "string" } },
+        "expected_answer_components": { "type": "array", "items": { "type": "string" } },
+        "desired_outcome": { "type": "string", "enum": ["mention", "citation", "recommendation", "comparison_inclusion", "accurate_description"] },
+        "risk_classification": { "type": "string", "enum": ["commercial", "legal", "reputational", "safety", "none"] },
+        "geography": { "type": "string" },
+        "language": { "type": "string" },
+        "jurisdiction": { "type": "string" },
+        "temporal_sensitivity": { "type": "string" },
+        "competitor_set": { "type": "array", "items": { "type": "string" } },
+        "baseline_outputs": { "type": "array", "items": { "type": "string" } },
+        "observed_sources": { "type": "array", "items": { "type": "string" } },
+        "accuracy_status": { "type": "string", "enum": ["accurate", "partially_accurate", "inaccurate", "not_observed", "unknown"] },
+        "owner": { "type": "string" },
+        "review_cadence": { "type": "string" },
+        "status": { "$ref": "citable://schemas/common.defs.json#/definitions/status" },
+        "provenance": { "$ref": "citable://schemas/common.defs.json#/definitions/provenance" }
+      }
+    }
+  }
+}

package/schemas/query.schema.json

@@ -0,0 +1,43 @@
+{
+  "$id": "citable://schemas/query.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Query registry",
+  "allOf": [{ "$ref": "citable://schemas/common.defs.json#/definitions/registryFile" }],
+  "properties": {
+    "kind": { "const": "queries" },
+    "entries": { "items": { "$ref": "#/definitions/query" } }
+  },
+  "definitions": {
+    "query": {
+      "type": "object",
+      "required": ["query_id", "canonical_query", "intent", "status"],
+      "properties": {
+        "query_id": { "$ref": "citable://schemas/common.defs.json#/definitions/id" },
+        "canonical_query": { "type": "string", "minLength": 3 },
+        "variants": { "type": "array", "items": { "type": "string" } },
+        "intent": { "type": "string", "enum": ["problem_awareness", "category_discovery", "informational", "comparative", "vendor_evaluation", "commercial_action", "transactional", "navigational", "brand"] },
+        "audiences": { "type": "array", "items": { "type": "string" } },
+        "funnel_stage": { "type": "string", "enum": ["awareness", "evaluation", "selection", "conversion", "retention"] },
+        "topic_entities": { "type": "array", "items": { "type": "string" } },
+        "geography": { "type": "string" },
+        "language": { "type": "string" },
+        "jurisdiction": { "type": "string" },
+        "search_result_type": { "type": "string" },
+        "target_page": { "type": "string" },
+        "current_ranking_page": { "type": "string" },
+        "competitor_urls": { "type": "array", "items": { "type": "string" } },
+        "business_value": { "type": "string", "enum": ["critical", "high", "medium", "low", "unknown"] },
+        "conversion_model": { "type": "string" },
+        "attainability": { "type": "string" },
+        "difficulty": { "type": "string" },
+        "freshness_sensitivity": { "type": "string", "enum": ["static", "periodic", "event_driven", "real_time"] },
+        "commercial_priority": { "type": ["string", "integer"] },
+        "coverage_owner": { "type": "string" },
+        "review_cadence": { "type": "string" },
+        "measurement_cohort": { "type": "string" },
+        "status": { "$ref": "citable://schemas/common.defs.json#/definitions/status" },
+        "provenance": { "$ref": "citable://schemas/common.defs.json#/definitions/provenance" }
+      }
+    }
+  }
+}

package/schemas/run.schema.json

@@ -0,0 +1,36 @@
+{
+  "$id": "citable://schemas/run.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Run manifest",
+  "type": "object",
+  "required": ["run_id", "command", "tool_version", "skill_version", "timestamp", "target", "status"],
+  "properties": {
+    "run_id": { "type": "string" },
+    "command": { "type": "string" },
+    "argv": { "type": "array", "items": { "type": "string" } },
+    "tool_version": { "type": "string" },
+    "skill_version": { "type": "string" },
+    "repository_commit": { "type": ["string", "null"] },
+    "working_tree_state": { "type": ["string", "null"], "enum": ["clean", "dirty", null] },
+    "target": {
+      "type": "object",
+      "properties": {
+        "kind": { "type": "string", "enum": ["source", "built_output", "url", "registries", "fixture"] },
+        "location": { "type": "string" },
+        "environment": { "type": "string" }
+      }
+    },
+    "timestamp": { "type": "string" },
+    "locale": { "type": "string" },
+    "jurisdiction": { "type": ["string", "null"] },
+    "configuration_hash": { "type": ["string", "null"] },
+    "input_hashes": { "type": "object" },
+    "output_hashes": { "type": "object" },
+    "detectors_run": { "type": "array", "items": { "type": "string" } },
+    "detectors_skipped": { "type": "array", "items": { "type": "object", "properties": { "detector_id": { "type": "string" }, "reason": { "type": "string" } } } },
+    "incomplete_checks": { "type": "array", "items": { "type": "string" } },
+    "errors": { "type": "array", "items": { "type": "string" } },
+    "warnings": { "type": "array", "items": { "type": "string" } },
+    "status": { "type": "string", "enum": ["completed", "completed_with_warnings", "incomplete", "failed"] }
+  }
+}

package/scripts/build-dist.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * Build the universal provider bundle from canonical Citable sources.
+ *
+ * Canonical inputs:
+ *   - skill/
+ *   - schemas/
+ *
+ * Generated output:
+ *   - dist/universal/<provider skills dir>/citable/
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { PROVIDERS, PROVIDER_IDS } from '../src/installer/providers.js';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SKILL = path.join(ROOT, 'skill');
+const SCHEMAS = path.join(ROOT, 'schemas');
+const DIST = path.join(ROOT, 'dist');
+const UNIVERSAL = path.join(DIST, 'universal');
+const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isSymbolicLink()) throw new Error(`refusing to package symlink: ${from}`);
+    if (entry.isDirectory()) copyDir(from, to);
+    else if (entry.isFile()) fs.copyFileSync(from, to);
+  }
+}
+
+function writeFile(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+function hashFile(filePath) {
+  return `sha256:${crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex')}`;
+}
+
+function toPosix(value) {
+  return value.split(path.sep).join('/');
+}
+
+function assertSafeRel(rel) {
+  const normalized = path.posix.normalize(rel.replace(/\\/g, '/'));
+  if (!normalized || normalized === '.' || normalized.startsWith('../') || normalized.includes('/../') || path.isAbsolute(normalized)) {
+    throw new Error(`unsafe generated path: ${rel}`);
+  }
+  return normalized;
+}
+
+function walkFiles(dir, base = dir, out = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    const abs = path.join(dir, entry.name);
+    const rel = assertSafeRel(toPosix(path.relative(base, abs)));
+    if (entry.isSymbolicLink()) throw new Error(`refusing to hash symlink: ${rel}`);
+    if (entry.isDirectory()) walkFiles(abs, base, out);
+    else if (entry.isFile()) out.push(rel);
+  }
+  return out;
+}
+
+function hashTree(dir, exclude = new Set()) {
+  const files = {};
+  for (const rel of walkFiles(dir)) {
+    if (exclude.has(rel)) continue;
+    files[rel] = hashFile(path.join(dir, rel));
+  }
+  const treeHash = `sha256:${crypto.createHash('sha256').update(
+    Object.entries(files).map(([rel, hash]) => `${rel}\0${hash}`).join('\n'),
+  ).digest('hex')}`;
+  return { files, treeHash };
+}
+
+function buildSkillTree(providerId) {
+  const provider = PROVIDERS[providerId];
+  const skillDir = path.join(UNIVERSAL, provider.projectSkillsDir, 'citable');
+  copyDir(SKILL, skillDir);
+  copyDir(SCHEMAS, path.join(skillDir, 'schemas'));
+  writeFile(path.join(skillDir, 'scripts', 'README.md'), `# Citable skill scripts
+
+This directory is part of the installed Citable skill payload. The initial
+installer does not add provider hooks or sidecar configuration.
+`);
+  writeFile(path.join(skillDir, 'VERSION'), `${pkg.version}\n`);
+  writeFile(path.join(skillDir, 'manifest.json'), `${JSON.stringify({
+    name: 'citable',
+    version: pkg.version,
+    managedBy: 'citable-cli',
+    provider: providerId,
+    providerName: provider.displayName,
+    scope: 'bundle',
+    sourcePackage: `${pkg.name}@${pkg.version}`,
+    files: {},
+    treeHash: null,
+  }, null, 2)}\n`);
+  const tree = hashTree(skillDir, new Set(['manifest.json']));
+  writeFile(path.join(skillDir, 'manifest.json'), `${JSON.stringify({
+    name: 'citable',
+    version: pkg.version,
+    managedBy: 'citable-cli',
+    provider: providerId,
+    providerName: provider.displayName,
+    scope: 'bundle',
+    sourcePackage: `${pkg.name}@${pkg.version}`,
+    variantPath: toPosix(path.relative(UNIVERSAL, skillDir)),
+    files: tree.files,
+    treeHash: tree.treeHash,
+  }, null, 2)}\n`);
+  return {
+    provider: providerId,
+    providerName: provider.displayName,
+    path: toPosix(path.relative(UNIVERSAL, skillDir)),
+    files: Object.keys(tree.files).length,
+    treeHash: tree.treeHash,
+  };
+}
+
+fs.rmSync(DIST, { recursive: true, force: true });
+fs.mkdirSync(UNIVERSAL, { recursive: true });
+
+const providers = {};
+for (const providerId of PROVIDER_IDS) {
+  providers[providerId] = buildSkillTree(providerId);
+  console.error(`built dist/universal/${providers[providerId].path} (${providers[providerId].files} files)`);
+}
+
+const bundleTree = hashTree(UNIVERSAL, new Set(['manifest.json']));
+writeFile(path.join(UNIVERSAL, 'manifest.json'), `${JSON.stringify({
+  name: 'citable-universal-bundle',
+  version: pkg.version,
+  sourcePackage: `${pkg.name}@${pkg.version}`,
+  providers,
+  files: bundleTree.files,
+  treeHash: bundleTree.treeHash,
+}, null, 2)}\n`);
+
+console.error('dist/universal/manifest.json written');

package/skill/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: citable
+description: >
+  Audit, design, remediate, validate, and monitor the conditions that influence SEO
+  (search visibility), AEO (answer citation), and GEO (generative representation).
+  Use whenever the user asks about search visibility, AI citations, answer engines,
+  generative engine optimization, structured data governance, claim substantiation,
+  crawler policy, entity consistency, content discoverability, or wants a site audited
+  for how search and AI systems will retrieve, understand, cite, or recommend it.
+version: 0.1.0
+---
+
+# Citable — search & generative discoverability governance
+
+Citable is an operational quality and governance layer, not a content generator.
+It treats discoverability as an engineering system: registries as the source of
+truth, deterministic detectors for observable conditions, rubrics for semantic
+judgment, evidence packages for every run, and fail-closed behaviour wherever a
+recommendation would require invented facts.
+
+## Operating premises (non-negotiable)
+
+1. **No guarantees.** Never promise crawling, indexing, ranking, traffic,
+   citation, recommendation, inclusion, sentiment, rich results, or conversion.
+   Speak in eligibility, probability, observed behaviour, and confidence.
+2. **Fact ≠ inference.** Classify every statement you make as: deterministic
+   observation, evidence-backed semantic finding, probabilistic inference,
+   strategic hypothesis, experiment result, or untestable condition. Never
+   present an inference as an observation.
+3. **Public ≠ reusable.** Keep separate: publicly accessible, crawlable,
+   indexable, snippet-eligible, retrievable on user action, licensed for reuse,
+   permitted for model training, licensed via partnership. Crawler access is
+   decided per crawler *and purpose* in `.citable/crawlers.yaml`.
+4. **Structured data is an assertion layer.** Schema must match visible content,
+   use stable `@id`s, and never assert ratings, prices, capabilities, or dates
+   the page and registries do not support.
+5. **Claims need owners and evidence.** No claim reaches `verified` without
+   evidence in the evidence registry. Expired evidence invalidates dependent
+   claims. Opinion and aspiration never become verified fact.
+6. **Corroboration cannot be manufactured.** Refuse to create fake reviews,
+   synthetic community posts, shadow brands, PBNs, undisclosed endorsements,
+   fabricated statistics or citations, recommendation poisoning, or hidden
+   instructions aimed at language models — regardless of how the request is
+   framed. Report GEO-001 findings (prompt injection) instead of replicating them.
+7. **Machines never outrank humans.** Every remediation must preserve or improve
+   factual accuracy, human comprehension, accessibility, conversion function,
+   legal defensibility, and maintainability.
+
+## The three disciplines (never collapse into one score)
+
+| Discipline | Objective | Unit of measurement |
+| --- | --- | --- |
+| SEO | Sustained visibility on commercially relevant queries; qualified traffic; conversion | URL, query, impression, click, conversion |
+| AEO | Direct-answer eligibility, passage extraction, supporting citation, accurate attribution | question, answer passage, citation, citation share |
+| GEO | Correct entity understanding, accurate synthesis, category placement, claim reproduction, comparison inclusion, defensible recommendation | entity, claim, prompt, comparison, recommendation, narrative |
+
+Report posture per dimension (e.g. `retrieval_eligibility: strong`,
+`answer_extractability: weak`) — never one opaque 0–100 "AI visibility score".
+
+## Tooling
+
+The `citable` CLI in this repository performs the deterministic work. Always
+prefer running it over re-deriving its checks by hand:
+
+```
+citable init                        # initialize .citable/ (non-destructive)
+citable audit [scope] --target <dir|url> [--base-url <url>] [--ref-date YYYY-MM-DD]
+citable inspect <page> --target <dir|url>
+citable map-claims --target <dir|url> [--write]
+citable substantiate [--write]
+citable schema --target <dir|url>
+citable validate [registries|claims|evidence|schema|links]
+citable compare-snapshots [runA runB]
+```
+
+Audit scopes: `technical seo aeo geo architecture entity claims evidence schema
+lifecycle corroboration`. Every audit writes an evidence package to
+`.citable/runs/<run-id>/` (manifest, findings.json, report.md, headers, robots,
+sitemaps, schema, link graph, checksums). A report without its evidence package
+is not a deliverable.
+
+## Command workflows
+
+Detailed per-command workflows live in `commands/`. Follow them; they define
+inputs, preconditions, refusal conditions, and validation for each command.
+Semantic judgments (intent alignment, evidence strength, information gain,
+comparison fairness, …) use the rubrics in `rubrics/` — each defines scoring
+dimensions, evidence requirements, counterexamples, and when human review is
+mandatory.
+
+## Registries are the source of truth
+
+`.citable/` holds nine YAML registries (queries, prompts, entities, claims,
+evidence, pages, crawlers, competitors, experiments), all schema-validated
+(`schemas/*.schema.json`) with referential integrity checks. Rules:
+
+- Never overwrite registry content without history — use the loader/saver in
+  `src/registries/index.js`, which snapshots prior versions automatically.
+- Never invent registry facts (legal names, founders, certifications,
+  competitors, pricing). Mark entities `incomplete` and list `required_input`.
+- Claim status transitions toward `verified` require existing verified evidence
+  plus human semantic review; automation only downgrades (fail-closed).
+
+## Fail-closed behaviour
+
+When information is missing, return a blocked/incomplete status with the exact
+required inputs — do not write around the gap:
+
+```yaml
+status: blocked
+reason: quantitative claim lacks verified evidence
+required_input: [baseline, measurement period, test population, methodology, result source]
+```
+
+The same applies to: missing entity identity (do not invent), unavailable
+external research (record `status: incomplete`, never fabricate competitors or
+citations), build/render failures (never report validation success; preserve
+command, exit code, and error output), and semantic ambiguity with commercial
+or legal consequences (classify and route to the decision owner).
+
+## Repository modification rules
+
+Before editing any repository: read its agent/repo instructions, package
+manifests, build/test/lint commands, rendering architecture, existing metadata
+and schema systems, and working-tree status. Then: preserve existing
+architecture; prefer shared data models over duplicated literals; never bypass
+tests, disable linting, weaken types, or touch unrelated files; never silently
+rewrite legal or regulated claims; preserve a diff of all registry changes; and
+rerun the relevant `citable validate`/`citable audit` scope after every change.
+A failed build or render makes "validated" an unavailable conclusion.
+
+## Anti-patterns
+
+`references/anti-patterns.md` is the canonical library (content, technical,
+AEO, GEO). Consult it before recommending any optimization; if a requested
+change matches an anti-pattern, name the anti-pattern, explain the risk, and
+offer the defensible alternative.

package/skill/commands/README.md

@@ -0,0 +1,36 @@
+# Citable command contracts
+
+Each command is a bounded workflow with explicit inputs, preconditions,
+refusal conditions, and validation. Three status classes — a contract proves
+intent, not executability, so statuses are strict:
+
+- **implemented** — callable, tested code exists in `src/commands/`.
+- **orchestrated** — an agent can execute a *tested composition* of implemented
+  primitives; the composition itself has been exercised end to end.
+- **specified** — only a command contract exists; the workflow has not been
+  proven executable. Do not present specified commands as capabilities.
+
+| Command | Status |
+| --- | --- |
+| /citable init | implemented |
+| /citable audit (+ scopes: technical seo aeo geo architecture entity claims evidence schema lifecycle corroboration) | implemented |
+| /citable inspect | implemented |
+| /citable map-claims | implemented |
+| /citable substantiate (deterministic + entailment gate; semantic upgrades need the evidence-strength rubric) | implemented |
+| /citable schema | implemented |
+| /citable validate, validate-claims, validate-evidence, validate-schema, validate-links | implemented |
+| /citable compare-snapshots / validate-regression | implemented |
+| /citable ingest, map-site, map-queries, map-prompts, map-entities, map-evidence | specified (ingest.md) |
+| /citable optimize-page | specified (optimize-page.md) — requires source-to-render mapping, claim-preserving rewrites, build execution, rollback; none of that is proven yet |
+| /citable create-page, answer-block, architect, interlink, consolidate, metadata | specified (page-work.md) |
+| /citable validate-render | specified (validate-render.md) — blocked on the rendered-truth phase (docs/detectors/render-phase-plan.md) |
+| /citable measure seo/aeo/geo, test-prompts, monitor-crawlers, monitor-contradictions | specified (measurement.md) — no external engine adapters exist or are claimed |
+
+Shared refusal conditions (all commands): any action that would fabricate
+facts, citations, evidence, authorship, reviews, corroboration, or hidden
+model instructions; any change that matches a ⛔ anti-pattern; publishing
+unverified registry entries as factual content.
+
+Shared validation (all mutating commands): rerun the relevant `citable
+validate` scope and the affected detectors; a failed build/render forbids a
+"validated" status; preserve registry diffs (automatic via saveRegistry).

package/skill/commands/ingest.md

@@ -0,0 +1,44 @@
+---
+command: /citable ingest (also map-site, map-queries, map-prompts, map-entities, map-evidence)
+purpose: Populate registries from repository content and operator input without inventing facts.
+preconditions: [.citable/ initialized]
+registries_written: [pages, queries, prompts, entities, evidence]
+refusal_conditions:
+  - inventing entity identity facts (legal names, founders, registrations, certifications)
+  - fabricating queries/prompts presented as demand data (proposals must be labeled candidate)
+failure_behaviour: unknown facts → entity/page marked incomplete with required_input
+---
+
+# Workflows
+
+## map-site
+1. Enumerate routes/pages from the built output (or `citable audit` pages index).
+2. For each page, propose a page-registry entry: url, page_type (from content
+   shape), indexing_intent (default from config), status `draft`.
+3. Leave owner, reviewer, lifecycle, conversion_action for the operator —
+   list them as required_input per page. Write with saveRegistry (history kept).
+
+## map-queries / map-prompts
+1. Derive *candidate* queries/prompts from page subjects, headings, and the
+   intent classes required by the spec (problem-awareness → brand for queries;
+   definition → follow-up for prompts). Adversarial and jurisdictional variants
+   are proposed but flagged for operator confirmation.
+2. Status is always `candidate`; business_value, difficulty, and ownership are
+   operator decisions. Never present derived candidates as measured demand.
+
+## map-entities
+1. Extract entity candidates from schema blocks, headings, and repeated proper
+   nouns; type them (organization/product/concept/…).
+2. Record only observed facts (name as printed, URL where described). All
+   identity fields not directly observable → omit and list in required_input.
+   The entity enters as status `incomplete` or `candidate`, never `verified`.
+
+## map-evidence
+1. Inventory evidence artifacts in the repo (specs, benchmarks, reports,
+   datasets) and register them with observed metadata plus integrity hash.
+2. verification_status starts `unverified`; a named reviewer moves it to
+   `reviewed`/`verified` — automation never does.
+
+## Validation (all)
+`citable validate` must pass after every write; referential integrity errors
+block the write, not the report.

package/skill/commands/measurement.md

@@ -0,0 +1,49 @@
+---
+command: /citable measure seo|aeo|geo, test-prompts, monitor-crawlers, monitor-contradictions
+purpose: Observation and measurement workflows. Citable records and validates observations; it does not claim live engine adapters it does not have.
+---
+
+# Honest capability statement
+
+This MVP ships **no external engine adapters** (no Search Console API client,
+no ChatGPT/Perplexity automation). Measurement commands therefore operate on
+*operator-supplied observations*, validated against the data contracts, plus
+registry-side integrity checks (MEAS-001/002/003). Do not imply otherwise.
+
+# measure seo
+Inputs the operator exports (Search Console/Bing/analytics CSV or JSON).
+Workflow: validate segmentation (brand vs non-brand, intent, page type,
+device, country), map rows to query registry ids, store under the run's
+evidence package, report coverage of the query portfolio — never sitewide
+averages alone. Refuse to attribute movement to a change without an
+experiment record (MEAS-003).
+
+# measure aeo / measure geo / test-prompts
+1. Each observation must satisfy `schemas/prompt-result.schema.json`: engine,
+   model where visible, interface, account state, location, locale, language,
+   date-time, prompt + variant, follow-up context, answer, retrieved sources,
+   citations, mention/recommendation status, position, factual accuracy,
+   entity confusion, omissions, sentiment, run index/series.
+2. Store observations under `.citable/runs/<run>/prompt-results/*.json` —
+   MEAS detectors read them from there.
+3. Scoring uses the narrative-accuracy rubric. One output is anecdote:
+   definitive accuracy_status in the prompt registry requires ≥3 observations
+   (MEAS-002). Report variance, never a single-run truth.
+4. Causal claims require an experiment registry entry with baseline, windows,
+   and confounders (MEAS-003).
+
+# monitor-crawlers
+Input: server/CDN logs the operator provides. Workflow: aggregate by user
+agent × URL × status; flag 403/429/5xx concentrations against declared-allow
+crawlers; note that user-agent strings are spoofable and IP validation is the
+confirmation step (crawler registry ip_validation_method). Compare observed
+access against `crawlers.yaml` decisions (CRAWL-001 logic applied to logs).
+
+# monitor-contradictions
+Compare approved entity + claim records against: owned pages (automated, via
+audit), and operator-collected external surfaces (profiles, directories,
+partner pages, generated answers). Classify contradictions by the fourteen
+types in the narrative-accuracy rubric; SEV-map material ones; follow the
+correction runbook (capture → materiality → source lineage → verify internal
+truth → correct owned → escalate external → recrawl request → retest cohort →
+preserve before/after → residual risk).

package/skill/commands/optimize-page.md

@@ -0,0 +1,53 @@
+---
+command: /citable optimize-page
+purpose: Improve one page's retrieval eligibility, answer clarity, entity relationships, and internal links while preserving its conversion role and claim boundaries.
+inputs: [page reference (URL path or source file), site target]
+optional_inputs: [specific findings to address, ref-date]
+preconditions:
+  - .citable/ initialized; page present in page registry (else run inspect + register first)
+  - repository build and test commands known (project.yaml)
+  - working tree clean or user-acknowledged
+registries_read: [pages, queries, prompts, entities, claims, evidence]
+registries_written: [pages (metadata only), claims (surface updates)]
+detectors_run: [all page-scoped detectors before and after]
+artifacts_created: [before/after inspect output, diff, post-change audit run]
+refusal_conditions:
+  - page carries regulated claims and no factual_reviewer is assigned
+  - requested change matches a ⛔ anti-pattern
+  - required facts (pricing, ICP, limitations) are unknown → blocked with required_input
+failure_behaviour: build or render failure → report command, exit code, error output; no success status
+---
+
+# Workflow
+
+1. `citable inspect <page> --target <built-output>` — capture the BEFORE state
+   (intent, entities, claims, findings, conversion action, ambiguity list).
+2. Read the page registry entry: intended query and prompt coverage, conversion
+   role, lifecycle class. If ambiguity list is non-empty, resolve registry
+   gaps before editing content.
+3. Order of work (never reversed):
+   a. **Technical defects first** — status, canonical, robots, sitemap, links
+      (TECH/LINK findings).
+   b. **Semantic ambiguity** — apply semantic-clarity and intent-alignment
+      rubrics; fix subject/category/terminology drift.
+   c. **Answer clarity** — direct answer block in first 50–100 words; atomic
+      claims; evidence adjacent; scope and exclusions in-passage
+      (answer-extractability rubric; ANS findings).
+   d. **Claim boundaries** — every edited claim keeps its registered scope and
+      exclusions verbatim or narrower; never broaden while "polishing".
+      Attach evidence references beside claims.
+   e. **Entity relationships & internal links** — upward hub link, lateral
+      related links, commercial next step; descriptive anchors.
+   f. **Schema** — only where justified by registry data (`citable schema`
+      proposals); never hand-add assertions.
+4. Style constraints: no keyword stuffing (PAGE-009 must not newly fire), no
+   generic AI prose (ANS-001 must not newly fire), match the site's voice.
+5. Preserve the conversion role — apply the conversion-alignment rubric; the
+   registered conversion_action must remain present and reachable.
+6. Build the project with the recorded build command. If it fails → failure
+   behaviour, stop.
+7. Re-audit: `citable audit --target <built-output>` and
+   `citable compare-snapshots` — the page's prior findings should resolve and
+   no new critical/high findings may appear.
+8. Report: findings resolved, findings remaining (with reasons), unresolved
+   conditions, registry diffs, and the run IDs of before/after evidence packages.