@nebulacomponents/citable 1.4.0 → 1.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulacomponents/citable",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "Production-grade SEO, AEO, and GEO agent skill with auditable detection, claim governance, evidence validation, and multi-agent installation.",
   "keywords": [
     "seo",
@@ -52,6 +52,8 @@
     "test:integration": "node --test --test-concurrency=1 --test-reporter=spec 'tests/integration/**/*.test.js'",
     "test:e2e": "node --test --test-concurrency=1 'tests/e2e/**/*.test.js'",
     "build:dist": "node scripts/build-dist.js",
+    "release:prepare": "node scripts/release-process.js prepare",
+    "release:validate": "node scripts/release-process.js validate",
     "prepack": "npm run build:dist"
   },
   "bin": {
@@ -86,6 +88,7 @@
   "dependencies": {
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
+    "csv-parse": "^7.0.1",
     "js-yaml": "^5.2.1",
     "node-html-parser": "^9.0.0"
   },

package/schemas/connection.schema.json

@@ -0,0 +1,32 @@
+{
+  "$id": "citable://schemas/connection.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Optional connector state registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "updated", "entries"],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "connections" },
+    "updated": { "type": "string", "format": "date-time" },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["connection_id", "provider", "state", "authentication", "scopes", "limitations"],
+        "properties": {
+          "connection_id": { "type": "string", "pattern": "^CONNECTION-[A-Z0-9][A-Z0-9_-]*$" },
+          "provider": { "type": "string", "minLength": 1 },
+          "property_id": { "type": ["string", "null"] },
+          "state": { "type": "string", "enum": ["not_configured", "configured", "synchronized", "partial", "authorization_expired", "permission_denied", "quota_limited", "temporarily_unavailable"] },
+          "authentication": { "type": "string", "enum": ["none", "environment", "os_keychain", "external_secret_manager", "owner_import"] },
+          "scopes": { "type": "array", "items": { "type": "string" } },
+          "last_synchronized_at": { "type": ["string", "null"], "format": "date-time" },
+          "cursor": { "type": ["string", "null"] },
+          "limitations": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    }
+  }
+}

package/schemas/intervention.schema.json

@@ -0,0 +1,33 @@
+{
+  "$id": "citable://schemas/intervention.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Intervention registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "updated", "entries"],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "interventions" },
+    "updated": { "type": "string", "format": "date-time" },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["intervention_id", "name", "status", "deployed_at", "affected_urls", "finding_ids", "objective_ids", "limitations"],
+        "properties": {
+          "intervention_id": { "type": "string", "pattern": "^INTERVENTION-[A-Z0-9][A-Z0-9_-]*$" },
+          "name": { "type": "string", "minLength": 1 },
+          "status": { "type": "string", "enum": ["planned", "deployed", "rolled_back", "superseded"] },
+          "deployed_at": { "type": ["string", "null"], "format": "date-time" },
+          "commit": { "type": ["string", "null"] },
+          "pull_request": { "type": ["string", "null"] },
+          "affected_urls": { "type": "array", "items": { "type": "string" } },
+          "finding_ids": { "type": "array", "items": { "type": "string" } },
+          "objective_ids": { "type": "array", "items": { "type": "string", "pattern": "^OBJECTIVE-" } },
+          "limitations": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    }
+  }
+}

package/schemas/metric.schema.json

@@ -0,0 +1,42 @@
+{
+  "$id": "citable://schemas/metric.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Metric registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "updated", "entries"],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "metrics" },
+    "updated": { "type": "string", "format": "date-time" },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["metric_id", "name", "provider", "external_name", "unit", "value_type", "aggregation", "direction", "dimensions", "limitations"],
+        "properties": {
+          "metric_id": { "type": "string", "pattern": "^METRIC-[A-Z0-9][A-Z0-9_-]*$" },
+          "name": { "type": "string", "minLength": 1 },
+          "description": { "type": "string" },
+          "provider": { "type": "string", "minLength": 1 },
+          "external_name": { "type": "string", "minLength": 1 },
+          "unit": { "type": "string", "enum": ["count", "ratio", "percent", "currency", "duration_ms", "position", "score", "custom"] },
+          "custom_unit": { "type": "string", "minLength": 1 },
+          "value_type": { "type": "string", "enum": ["integer", "number"] },
+          "aggregation": { "type": "string", "enum": ["sum", "average", "minimum", "maximum", "latest", "provider_defined"] },
+          "direction": { "type": "string", "enum": ["increase", "decrease", "maintain", "contextual"] },
+          "dimensions": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+          "limitations": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+          "status": { "type": "string", "enum": ["active", "deprecated"] }
+        },
+        "allOf": [
+          {
+            "if": { "properties": { "unit": { "const": "custom" } } },
+            "then": { "required": ["custom_unit"] }
+          }
+        ]
+      }
+    }
+  }
+}

package/schemas/objective.schema.json

@@ -0,0 +1,65 @@
+{
+  "$id": "citable://schemas/objective.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Objective registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "updated", "entries"],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "objectives" },
+    "updated": { "type": "string", "format": "date-time" },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["objective_id", "name", "status", "primary_metrics", "supporting_metrics", "guardrails", "cohort", "comparison"],
+        "properties": {
+          "objective_id": { "type": "string", "pattern": "^OBJECTIVE-[A-Z0-9][A-Z0-9_-]*$" },
+          "name": { "type": "string", "minLength": 1 },
+          "description": { "type": "string" },
+          "owner": { "type": ["string", "null"] },
+          "status": { "type": "string", "enum": ["draft", "active", "paused", "archived"] },
+          "primary_metrics": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/definitions/metricRef" } },
+          "supporting_metrics": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/definitions/metricRef" } },
+          "guardrails": { "type": "array", "items": { "$ref": "#/definitions/guardrail" } },
+          "cohort": { "$ref": "#/definitions/cohort" },
+          "comparison": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["baseline_days", "evaluation_days", "minimum_observations"],
+            "properties": {
+              "baseline_days": { "type": "integer", "minimum": 1 },
+              "evaluation_days": { "type": "integer", "minimum": 1 },
+              "minimum_observations": { "type": "integer", "minimum": 1 }
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "metricRef": { "type": "string", "pattern": "^METRIC-[A-Z0-9][A-Z0-9_-]*$" },
+    "guardrail": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["metric_id", "operator", "threshold"],
+      "properties": {
+        "metric_id": { "$ref": "#/definitions/metricRef" },
+        "operator": { "type": "string", "enum": ["gte", "lte", "increase_by", "decrease_by", "no_regression"] },
+        "threshold": { "type": "number" }
+      }
+    },
+    "cohort": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["urls", "queries", "labels"],
+      "properties": {
+        "urls": { "type": "array", "items": { "type": "string" } },
+        "queries": { "type": "array", "items": { "type": "string" } },
+        "labels": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/observation.schema.json

@@ -7,7 +7,7 @@
   "required": ["observation_id", "kind", "state", "collected_at", "collection_method", "confidence", "source", "evidence_hash", "data"],
   "properties": {
     "observation_id": { "type": "string", "minLength": 1 },
-    "kind": { "type": "string", "enum": ["render", "index", "citation", "citation_review", "crawler_log", "passage", "canonical_freshness", "performance", "corroboration"] },
+    "kind": { "type": "string", "enum": ["render", "index", "citation", "citation_review", "crawler_log", "passage", "canonical_freshness", "performance", "corroboration", "metric"] },
     "state": { "type": "string", "enum": ["observed", "not_observed", "not_evidenced", "incomplete", "review_required", "failed"] },
     "collected_at": { "type": "string", "format": "date-time" },
     "collection_method": { "type": "string", "enum": ["live_api", "browser", "owner_import", "synthetic_fetch", "static_analysis", "human_review"] },

package/skill/SKILL.md

@@ -7,7 +7,7 @@ description: >
   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: 1.4.0
+version: 1.5.1
 ---
 
 # Citable — search & generative discoverability governance
@@ -88,6 +88,10 @@ citable action-plan [run-id]          # ordered actions, blockers, semantic gate
 citable observe <mode> [options]      # render/index/citation/log/passage/consensus/performance evidence
 citable apply --input <spec> [--write] # reviewed, hash-locked remediation; dry run by default
 citable monitor [runA runB]           # observation regression alerts
+citable metrics import --provider <name> --input <csv|json>
+citable objectives init --input <json|yaml> [--write]
+citable objectives validate
+citable evaluate [objective-id] [--ref-date YYYY-MM-DD]
 ```
 
 Audit scopes: `technical seo aeo geo architecture entity claims evidence schema
@@ -144,8 +148,9 @@ mandatory.
 
 ## Registries are the source of truth
 
-`.citable/` holds nine YAML registries (queries, prompts, entities, claims,
-evidence, pages, crawlers, competitors, experiments), all schema-validated
+`.citable/` holds YAML registries for queries, prompts, entities, claims,
+evidence, pages, crawlers, competitors, experiments, metrics, objectives,
+interventions, and optional connection state, all schema-validated
 (`schemas/*.schema.json`) with referential integrity checks. Rules:
 
 - Never overwrite registry content without history — use the loader/saver in

package/skill/commands/README.md

@@ -24,11 +24,14 @@ intent, not executability, so statuses are strict:
 | /citable observe | implemented — render, index, citation, crawler-log, passage, consensus, performance, and corroboration evidence |
 | /citable apply | implemented — reviewed, hash-locked source replacements; dry run by default |
 | /citable monitor | implemented — compares immutable observation runs and emits evidence-linked alerts |
+| /citable metrics import | implemented — validates declared CSV/JSON metrics and writes immutable observations |
+| /citable objectives init / validate | implemented — user-owned metric selection, cohorts, windows, and guardrails |
+| /citable evaluate | implemented — independent baseline/evaluation comparisons with inconclusive handling |
 | /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 | partially implemented by `observe render`; mobile/cross-browser and interaction exploration remain |
-| /citable measure seo/aeo/geo, test-prompts, monitor-crawlers, monitor-contradictions | partially implemented by observation imports, Google/CrUX live APIs, custom citation adapters, and monitor comparisons |
+| /citable measure seo/aeo/geo, test-prompts, monitor-crawlers, monitor-contradictions | partially implemented by metric/observation imports, objective evaluation, Google/CrUX live APIs, custom citation adapters, and monitor comparisons |
 
 Shared refusal conditions (all commands): any action that would fabricate
 facts, citations, evidence, authorship, reviews, corroboration, or hidden

package/skill/commands/measurement.md

@@ -10,6 +10,23 @@ imports, and a disclosed custom citation-adapter protocol. It does not claim
 Bing AI Performance automation or equivalence between an API adapter and a
 consumer answer product. Preserve collector and product mode on every result.
 
+# implemented metric and objective workflow
+
+`citable metrics import --provider <name> --input <csv|json>` validates every
+row against a declared entry in `metrics.yaml` and writes immutable metric
+observations. `citable objectives init --input <json|yaml>` is dry-run by
+default; `--write` adds the validated objective with registry history.
+`citable objectives validate` checks contracts and metric references.
+`citable evaluate [objective-id]` compares independent baseline and evaluation
+windows, deduplicates repeated evidence, and reports each metric and guardrail
+separately. Insufficient data is `inconclusive`, never zero. Results describe
+temporal association and do not establish causation.
+
+Metrics, objectives, interventions, and connection state are optional. The
+absence of provider credentials is `not_configured`, not a finding and not
+evidence of zero activity. Credentials must never enter registries or evidence
+packages.
+
 # measure seo
 Inputs the operator exports (Search Console/Bing/analytics CSV or JSON).
 Workflow: validate segmentation (brand vs non-brand, intent, page type,

package/src/cli/index.js

@@ -15,6 +15,7 @@ import { actionPlan } from '../commands/actionPlan.js';
 import { observe } from '../commands/observe.js';
 import { applyRemediation } from '../commands/applyRemediation.js';
 import { monitor } from '../commands/monitor.js';
+import { evaluateObjective, importMetrics, initializeObjective, validateObjectives } from '../commands/measurement.js';
 
 const HELP = `citable — SEO / AEO / GEO audit, remediation, validation, and governance
 
@@ -41,6 +42,10 @@ Commands
                             consensus, performance, or corroboration evidence
   apply                     Apply a reviewed, hash-locked remediation spec
   monitor [runA runB]       Compare observation runs and emit regression alerts
+  metrics import            Import declared metric observations from CSV/JSON
+  objectives init           Validate/add one objective from --input (--write to save)
+  objectives validate       Validate objective contracts and metric references
+  evaluate [objective-id]   Compare objective baseline and evaluation windows
   self-upgrade              Check for a newer version and upgrade the npx cache
 
 Options
@@ -167,6 +172,29 @@ export async function main(argv = process.argv.slice(2), options = {}) {
         if (r.summary.critical_or_high > 0) process.exitCode = 1;
         break;
       }
+      case 'metrics': {
+        if (args._[0] !== 'import') throw new Error('usage: citable metrics import --provider <name> --input <csv|json>');
+        const r = importMetrics(root, { input: args.input, provider: args.provider });
+        out(args, `metrics import: ${r.summary.total} observation(s) from ${args.provider}\nEvidence package: ${r.dir}`, r);
+        break;
+      }
+      case 'objectives': {
+        const mode = args._[0];
+        if (mode === 'init') {
+          const r = initializeObjective(root, { input: args.input, write: args.write });
+          out(args, `objectives init: ${r.objective.objective_id} ${r.written ? 'written' : 'valid (dry run; use --write to save)'}`, r);
+        } else if (mode === 'validate') {
+          const r = validateObjectives(root);
+          out(args, `objectives validate: ${r.ok ? 'OK' : 'PROBLEMS'} (${r.count} objective(s))${r.problems.length ? `\n${r.problems.map((problem) => `  - ${problem}`).join('\n')}` : ''}`, r);
+          if (!r.ok) process.exitCode = 1;
+        } else throw new Error('usage: citable objectives <init|validate> [--input <json|yaml>] [--write]');
+        break;
+      }
+      case 'evaluate': {
+        const r = evaluateObjective(root, { objectiveId: args._[0], refDate: args.refDate });
+        out(args, `evaluate ${r.objective_id}: ${r.status}\n` + r.metrics.map((metric) => `  ${metric.metric_id}: ${metric.state}${metric.state === 'observed' ? ` (${metric.baseline} → ${metric.evaluation})` : ''}`).join('\n') + `\n${r.interpretation}`, r);
+        break;
+      }
       case 'self-upgrade': {
         const output = await selfUpgradeCommand(argv.slice(1));
         console.log(output);

package/src/commands/measurement.js

@@ -0,0 +1,205 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse as parseCsv } from 'csv-parse/sync';
+import { loadRegistries, saveRegistry } from '../registries/index.js';
+import { envelope, observationRun } from '../observations/common.js';
+import { parseRefDate, readJson, readYaml } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+function inputDocument(file) {
+  if (!file) throw new Error('--input <file> is required');
+  if (!fs.existsSync(file)) throw new Error(`input not found: ${file}`);
+  const raw = fs.readFileSync(file, 'utf8');
+  const ext = path.extname(file).toLowerCase();
+  if (ext === '.csv') return { raw, rows: parseCsv(raw, { columns: true, skip_empty_lines: true, trim: true }), file: path.resolve(file) };
+  const value = ext === '.yaml' || ext === '.yml' ? readYaml(file) : readJson(file);
+  return { raw, rows: Array.isArray(value) ? value : value.rows || value.entries || [value], file: path.resolve(file) };
+}
+
+function numericValue(raw, type, rowNumber) {
+  if (raw === '' || raw == null) throw new Error(`row ${rowNumber}: value is required`);
+  const value = Number(raw);
+  if (!Number.isFinite(value)) throw new Error(`row ${rowNumber}: value must be numeric`);
+  if (type === 'integer' && !Number.isInteger(value)) throw new Error(`row ${rowNumber}: value must be an integer`);
+  return value;
+}
+
+function isoTime(raw, field, rowNumber) {
+  if (!raw || Number.isNaN(new Date(raw).getTime())) throw new Error(`row ${rowNumber}: ${field} must be a valid date-time`);
+  return new Date(raw).toISOString();
+}
+
+export function importMetrics(root, { input, provider }) {
+  if (!provider) throw new Error('metrics import requires --provider <name>');
+  const source = inputDocument(input);
+  if (!source.rows.length) throw new Error('metric import contains no rows');
+  const { registries, problems } = loadRegistries(root);
+  if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
+  const definitions = new Map(registries.metrics.entries.map((metric) => [metric.metric_id, metric]));
+  const observations = source.rows.map((row, index) => {
+    const rowNumber = index + 1;
+    const metric = definitions.get(row.metric_id);
+    if (!metric) throw new Error(`row ${rowNumber}: unknown metric_id ${row.metric_id || '(missing)'}`);
+    if (metric.status === 'deprecated') throw new Error(`row ${rowNumber}: metric ${metric.metric_id} is deprecated`);
+    if (metric.provider.toLowerCase() !== String(provider).toLowerCase()) {
+      throw new Error(`row ${rowNumber}: metric ${metric.metric_id} belongs to ${metric.provider}, not ${provider}`);
+    }
+    const observedAt = isoTime(row.observed_at || row.date, 'observed_at', rowNumber);
+    const dimensions = {};
+    for (const dimension of metric.dimensions) {
+      if (row[dimension] != null && row[dimension] !== '') dimensions[dimension] = String(row[dimension]);
+    }
+    const data = {
+      metric_id: metric.metric_id,
+      provider: metric.provider,
+      external_name: metric.external_name,
+      value: numericValue(row.value, metric.value_type, rowNumber),
+      unit: metric.unit === 'custom' ? metric.custom_unit : metric.unit,
+      aggregation: metric.aggregation,
+      observed_at: observedAt,
+      period_start: row.period_start ? isoTime(row.period_start, 'period_start', rowNumber) : observedAt,
+      period_end: row.period_end ? isoTime(row.period_end, 'period_end', rowNumber) : observedAt,
+      dimensions,
+      source_row: rowNumber,
+    };
+    if (new Date(data.period_start) > new Date(data.period_end)) throw new Error(`row ${rowNumber}: period_start is after period_end`);
+    return envelope('metric', data, {
+      method: 'owner_import',
+      source: source.file,
+      raw: JSON.stringify(row),
+      limitations: metric.limitations,
+    });
+  });
+  return observationRun(root, 'metrics import', source.file, observations, { rawInputs: { metric_import: source.raw } });
+}
+
+function readObjectiveInput(input) {
+  const document = inputDocument(input);
+  if (document.rows.length !== 1) throw new Error('objectives init requires exactly one objective');
+  return document.rows[0];
+}
+
+export function initializeObjective(root, { input, write = false }) {
+  const objective = readObjectiveInput(input);
+  const { registries, problems } = loadRegistries(root);
+  if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
+  const candidate = { ...registries.objectives, entries: [...registries.objectives.entries, objective] };
+  const check = validateAgainst('objective.schema.json', candidate);
+  if (!check.valid) throw new Error(`objective violates contract: ${check.errors.join('; ')}`);
+  if (registries.objectives.entries.some((item) => item.objective_id === objective.objective_id)) throw new Error(`objective ${objective.objective_id} already exists`);
+  const metricIds = new Set(registries.metrics.entries.map((item) => item.metric_id));
+  const refs = [...objective.primary_metrics, ...objective.supporting_metrics, ...objective.guardrails.map((item) => item.metric_id)];
+  const unknown = [...new Set(refs.filter((ref) => !metricIds.has(ref)))];
+  if (unknown.length) throw new Error(`objective references unknown metrics: ${unknown.join(', ')}`);
+  if (write) saveRegistry(root, 'objectives', candidate);
+  return { objective, written: write, file: path.join(root, '.citable', 'objectives.yaml') };
+}
+
+export function validateObjectives(root) {
+  const { registries, problems } = loadRegistries(root);
+  const objectiveProblems = problems.filter((problem) => problem.startsWith('objectives/') || problem.startsWith('objectives.yaml'));
+  return { ok: objectiveProblems.length === 0, problems: objectiveProblems, count: registries.objectives.entries.length };
+}
+
+function metricObservations(root) {
+  const runs = path.join(root, '.citable', 'runs');
+  if (!fs.existsSync(runs)) return [];
+  const items = [];
+  for (const run of fs.readdirSync(runs)) {
+    const dir = path.join(runs, run, 'observations');
+    if (!fs.existsSync(dir)) continue;
+    for (const file of fs.readdirSync(dir).filter((name) => name.endsWith('-metric.json'))) {
+      const item = readJson(path.join(dir, file));
+      if (item.kind === 'metric') items.push(item);
+    }
+  }
+  return [...new Map(items.map((item) => [item.evidence_hash, item])).values()];
+}
+
+function inCohort(data, cohort) {
+  const url = data.dimensions.url || data.dimensions.page || null;
+  const query = data.dimensions.query || null;
+  const labels = String(data.dimensions.labels || data.dimensions.label || '').split(',').map((label) => label.trim()).filter(Boolean);
+  const urlMatch = !cohort.urls.length || (url && cohort.urls.some((pattern) => pattern.endsWith('*') ? url.startsWith(pattern.slice(0, -1)) : url === pattern));
+  const queryMatch = !cohort.queries.length || (query && cohort.queries.includes(query));
+  const labelMatch = !cohort.labels.length || cohort.labels.some((label) => labels.includes(label));
+  return urlMatch && queryMatch && labelMatch;
+}
+
+function aggregate(values, method) {
+  if (!values.length) return null;
+  if (method === 'sum') return values.reduce((sum, value) => sum + value, 0);
+  if (method === 'minimum') return Math.min(...values);
+  if (method === 'maximum') return Math.max(...values);
+  if (method === 'latest') return values.at(-1);
+  return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+function evaluateGuardrail(guardrail, metric, definition) {
+  if (metric.state !== 'observed') return { ...guardrail, state: 'inconclusive', passed: null, reason: 'metric comparison is inconclusive' };
+  let passed;
+  if (guardrail.operator === 'gte') passed = metric.evaluation >= guardrail.threshold;
+  else if (guardrail.operator === 'lte') passed = metric.evaluation <= guardrail.threshold;
+  else if (guardrail.operator === 'increase_by') passed = metric.relative_change != null && metric.relative_change >= guardrail.threshold;
+  else if (guardrail.operator === 'decrease_by') passed = metric.relative_change != null && metric.relative_change <= -guardrail.threshold;
+  else if (definition.direction === 'increase') passed = metric.evaluation >= metric.baseline;
+  else if (definition.direction === 'decrease') passed = metric.evaluation <= metric.baseline;
+  else if (definition.direction === 'maintain') passed = metric.relative_change != null && Math.abs(metric.relative_change) <= guardrail.threshold;
+  else return { ...guardrail, state: 'inconclusive', passed: null, reason: 'contextual metric requires a user-defined directional guardrail' };
+  return { ...guardrail, state: 'observed', passed, reason: passed ? 'observed condition met' : 'observed condition not met' };
+}
+
+export function evaluateObjective(root, { objectiveId, refDate }) {
+  const { registries, problems } = loadRegistries(root);
+  if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
+  const objective = objectiveId ? registries.objectives.entries.find((item) => item.objective_id === objectiveId) : registries.objectives.entries[0];
+  if (!objective) throw new Error(objectiveId ? `objective not found: ${objectiveId}` : 'no objective configured');
+  const definitions = new Map(registries.metrics.entries.map((item) => [item.metric_id, item]));
+  const end = parseRefDate(refDate);
+  end.setUTCHours(23, 59, 59, 999);
+  const evaluationStart = new Date(end); evaluationStart.setUTCDate(evaluationStart.getUTCDate() - objective.comparison.evaluation_days + 1); evaluationStart.setUTCHours(0, 0, 0, 0);
+  const baselineEnd = new Date(evaluationStart.getTime() - 1);
+  const baselineStart = new Date(baselineEnd); baselineStart.setUTCDate(baselineStart.getUTCDate() - objective.comparison.baseline_days + 1); baselineStart.setUTCHours(0, 0, 0, 0);
+  const all = metricObservations(root).filter((item) => inCohort(item.data, objective.cohort));
+  const metricIds = [...new Set([...objective.primary_metrics, ...objective.supporting_metrics, ...objective.guardrails.map((item) => item.metric_id)])];
+  const metrics = metricIds.map((metricId) => {
+    const definition = definitions.get(metricId);
+    const observations = all.filter((item) => item.data.metric_id === metricId).sort((a, b) => a.data.observed_at.localeCompare(b.data.observed_at));
+    const baselineRows = observations.filter((item) => new Date(item.data.observed_at) >= baselineStart && new Date(item.data.observed_at) <= baselineEnd);
+    const evaluationRows = observations.filter((item) => new Date(item.data.observed_at) >= evaluationStart && new Date(item.data.observed_at) <= end);
+    const aggregatable = definition.aggregation !== 'provider_defined';
+    const enough = aggregatable && baselineRows.length >= objective.comparison.minimum_observations && evaluationRows.length >= objective.comparison.minimum_observations;
+    const baseline = enough ? aggregate(baselineRows.map((item) => item.data.value), definition.aggregation) : null;
+    const evaluation = enough ? aggregate(evaluationRows.map((item) => item.data.value), definition.aggregation) : null;
+    return {
+      metric_id: metricId,
+      provider: definition.provider,
+      state: enough ? 'observed' : 'inconclusive',
+      baseline,
+      evaluation,
+      absolute_change: enough ? evaluation - baseline : null,
+      relative_change: enough && baseline !== 0 ? (evaluation - baseline) / Math.abs(baseline) : null,
+      baseline_observations: baselineRows.length,
+      evaluation_observations: evaluationRows.length,
+      limitations: [
+        ...definition.limitations,
+        ...(!aggregatable ? ['provider_defined aggregation requires an explicit normalized aggregation before evaluation'] : []),
+        ...(aggregatable && !enough ? [`requires at least ${objective.comparison.minimum_observations} observations in each window`] : []),
+      ],
+    };
+  });
+  const guardrails = objective.guardrails.map((guardrail) => {
+    const metric = metrics.find((item) => item.metric_id === guardrail.metric_id);
+    return evaluateGuardrail(guardrail, metric, definitions.get(guardrail.metric_id));
+  });
+  return {
+    objective_id: objective.objective_id,
+    objective_name: objective.name,
+    windows: { baseline_start: baselineStart.toISOString(), baseline_end: baselineEnd.toISOString(), evaluation_start: evaluationStart.toISOString(), evaluation_end: end.toISOString() },
+    metrics,
+    guardrails,
+    guardrail_status: guardrails.some((item) => item.state === 'inconclusive') ? 'inconclusive' : guardrails.some((item) => !item.passed) ? 'not_met' : 'met',
+    status: metrics.every((metric) => metric.state === 'observed') ? 'observed' : 'inconclusive',
+    interpretation: 'Changes are temporal associations. This evaluation does not establish that an intervention caused an observed outcome.',
+  };
+}

package/src/installer/index.js

@@ -105,6 +105,8 @@ export function parseInstallerArgs(argv) {
     help: false,
     version: false,
     failOnUpdate: false,
+    installMode: 'copy',
+    skillSelection: null,
     _: [],
   };
 
@@ -118,17 +120,29 @@ export function parseInstallerArgs(argv) {
     else if (arg === '--dry-run') args.dryRun = true;
     else if (arg === '--force') args.force = true;
     else if (arg === '--json') args.json = true;
-    else if (arg === '--all') args.all = true;
+    else if (arg === '--all') { args.all = true; args.yes = true; }
     else if (arg === '--help' || arg === '-h') args.help = true;
     else if (arg === '--version' || arg === '-v') args.version = true;
-    else if (arg === '--project' || arg === '--local') args.scope = mergeScope(args.scope, 'project');
-    else if (arg === '--global' || arg === '--user') args.scope = mergeScope(args.scope, 'global');
+    else if (arg === '--project' || arg === '--local' || arg === '-p') args.scope = mergeScope(args.scope, 'project');
+    else if (arg === '--global' || arg === '--user' || arg === '-g') args.scope = mergeScope(args.scope, 'global');
+    else if (arg === '--copy') args.installMode = 'copy';
+    else if (arg === '--symlink') throw new CitableInstallerError('--symlink is not supported: Citable uses hashed managed copies for atomic validation and safe uninstall', EXIT_CODES.invalidArguments);
     else if (arg === '--fail-on-update') args.failOnUpdate = true;
     else if (arg === '--providers') {
       if (i + 1 >= argv.length) throw new CitableInstallerError('--providers requires a value', EXIT_CODES.invalidArguments);
       args.providersRaw = argv[++i];
     } else if (arg.startsWith('--providers=')) {
       args.providersRaw = arg.slice('--providers='.length);
+    } else if (arg === '--agent' || arg === '-a') {
+      if (i + 1 >= argv.length) throw new CitableInstallerError(`${arg} requires a value`, EXIT_CODES.invalidArguments);
+      args.providersRaw = [args.providersRaw, argv[++i]].filter(Boolean).join(',');
+    } else if (arg.startsWith('--agent=')) {
+      args.providersRaw = [args.providersRaw, arg.slice('--agent='.length)].filter(Boolean).join(',');
+    } else if (arg === '--skill' || arg === '-s') {
+      if (i + 1 >= argv.length) throw new CitableInstallerError(`${arg} requires a value`, EXIT_CODES.invalidArguments);
+      args.skillSelection = argv[++i];
+    } else if (arg.startsWith('--skill=')) {
+      args.skillSelection = arg.slice('--skill='.length);
     } else if (arg === '--scope') {
       if (i + 1 >= argv.length) throw new CitableInstallerError('--scope requires a value', EXIT_CODES.invalidArguments);
       args.scope = mergeScope(args.scope, normalizeScopeValue(argv[++i]));
@@ -141,7 +155,16 @@ export function parseInstallerArgs(argv) {
     }
   }
 
-  if (args.providersRaw !== null) {
+  if (args.skillSelection !== null && !['citable', '*'].includes(String(args.skillSelection).trim().toLowerCase())) {
+    throw new CitableInstallerError(`this package contains only the citable skill; unsupported --skill value: ${args.skillSelection}`, EXIT_CODES.invalidArguments);
+  }
+
+  if (args.all) {
+    if (args.providersRaw !== null) throw new CitableInstallerError('--all cannot be combined with --providers or --agent', EXIT_CODES.invalidArguments);
+    args.providerSelection = { kind: 'all', providers: PROVIDER_IDS, unknown: [] };
+  }
+
+  if (args.providersRaw !== null && !args.providerSelection) {
     const parsed = parseProviderList(args.providersRaw);
     if (parsed.unknown.length) {
       const supported = PROVIDER_IDS.join(', ');
@@ -1102,12 +1125,17 @@ Install examples
   npx @nebulacomponents/citable install
   npx @nebulacomponents/citable install --yes
   npx @nebulacomponents/citable install --providers=claude,codex,cursor --project --yes
+  npx @nebulacomponents/citable install --agent claude-code --agent codex --skill citable --copy -p -y
   npx @nebulacomponents/citable install --providers=all --global --dry-run
 
 Options
-  --providers=<list>        Provider ids, detected, or all
-  --project, --local        Install/check project-local skill locations
-  --global, --user          Install/check user-global skill locations
+  --providers=<list>        Provider ids, detected, all, or *
+  --agent=<id>, -a <id>     Repeatable provider alias compatible with skills CLI
+  --skill=<name>, -s <name> Select citable or * (this package contains one skill)
+  --all                     Select every provider and confirm non-interactively
+  --copy                    Use managed copies (default and only install mode)
+  --project, --local, -p    Install/check project-local skill locations
+  --global, --user, -g      Install/check user-global skill locations
   --scope=<project|global>  Scope equivalent
   --yes, -y                 Confirm non-interactively
   --dry-run                 Preview filesystem changes without mutation

package/src/installer/providers.js

@@ -130,7 +130,7 @@ export function parseProviderList(value) {
   if (!raw) return { kind: 'explicit', providers: [], unknown: [] };
   const lowered = raw.toLowerCase();
   if (lowered === 'detected') return { kind: 'detected', providers: [], unknown: [] };
-  if (lowered === 'all') return { kind: 'all', providers: PROVIDER_IDS, unknown: [] };
+  if (lowered === 'all' || lowered === '*') return { kind: 'all', providers: PROVIDER_IDS, unknown: [] };
 
   const providers = [];
   const unknown = [];