Skip to main content

​
canonic status

Show the current canonic project root, config version, and local state presence.
Prints the project root, canonic.yaml config version (or a config error if invalid), whether .canonic/ (local state) is present, the serving contract schema version, and a one-line summary of served-answer events (count, error count, p95 latency) if any exist. This is always a safe “what’s my next step” command. Run it whenever you’re unsure of project state. The serving contract schema is currently 2.2. It moved from 2.0 across two additive bumps: 2.1 added the E14 trust tier to QueryMetadata, and 2.2 added the trust tier to every logged AnswerEvent plus the new answer_outcome event kind.

​
canonic validate

Validate every contract against the project’s semantic sources, read-only, no connection required.
Checks that every metric binding’s canonical.source/measure, every guardrail’s applies_to, every finality rule, and every assertion resolve against semantics/ and contracts/. These are the same cross-surface checks canonic ingest already runs before writing a diff. canonic validate makes them available as a standalone check, so a broken contract (for example a semi_additive binding whose source grain column isn’t declared as a dimension) is caught before it reaches a query instead of failing the next time an agent asks for that metric. Exits non-zero with a structured error (--json supported) on the first violation found.

​
canonic audit

Show event-log figures from the local .canonic/ store: counts, error distribution, latency, bytes scanned, and freshness.
Output includes the onboarding funnel (setup started → connection added → bootstrap completed → first answer served → first curated review completed, each with a timestamp once reached), overall answer counts and latency percentiles, bytes scanned, stale-answer and guardrail-hit counts, an error distribution table, and a table of the most recent answers. When answer_outcome events are present (see canonic outcome mark below), the report also shows:
  • Trust calibration: outcome verdicts bucketed by E14 trust tier, so you can see whether caution predicts incorrect materially more often than trusted. This is the metric that validates whether E14’s tiers are actually predictive.
  • Correction recurrence: bindings with more than one incorrect outcome. A rising count means the feedback loop isn’t closing: the same canonical definition keeps getting marked wrong.
  • Feedback loop: a table of every binding with any wrong_definition outcome history, with columns binding, wrong_definition count, distinct markers, whether it’s crossed the E4 evidence gate (gated (E4)), and whether it’s currently capping the E14 trust tier (trust capped). Shown even below the gate, so a pattern is visible before it fires. Also included in --json under "feedback". See Feedback loop (E11) and the feedback block in config schema.

​
canonic audit --bundle

Writes a single JSON file for attaching to a bug report: canonic/Python/platform version, the serving contract schema, the redacted canonic.yaml (connection secrets are already stored as references such as env:/keyring:/file: rather than literals, and free-form connector params entries are additionally redacted defensively), and the onboarding funnel plus event-log summary. Contains no query results. Nothing is sent anywhere. Review the file yourself before attaching it.

​
canonic outcome mark

Record a correct/incorrect ground-truth mark on a served answer, with an attribution reason-code when incorrect. canonic outcome mark itself only records the outcome to the local event log and never mutates any contract file. Recurring wrong_definition outcomes are acted on separately, by the feedback loop (E11): once a binding crosses the feedback config’s pattern thresholds, canonic ingest flags it as E4 contradiction evidence, and it caps the binding’s trust tier at caution.
The reason-code is an attribution safeguard, not a formality: only wrong_definition implicates the canonical binding used and is eligible to become contradiction evidence downstream. wrong_data and wrong_interpretation are recorded but never flag the binding. unspecified carries the lowest weight. Passing --reason together with --verdict correct fails with VALIDATION_FAILED (exit 9): a reason only makes sense for an incorrect verdict.