canonic status
Show the current canonic project root, config version, and local state presence.
canonic.yaml config version (or a config error if invalid), whether .canonic/ (local state) is present, the serving contract schema version, the project fingerprint, 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 project fingerprint is a hash over the contents of canonic.yaml, contracts/ and semantics/. It is the same value contract_info returns for a running daemon, so a mismatch shows that the daemon serves other files than the ones on disk. The same project gives the same value on every machine.
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.
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. It also checks the links between metrics and knowledge pages: a metric’s knowledge_refs must name global pages, and a page’s metrics must name active metrics. Declarations that are accepted but have no effect are reported as warnings and do not fail the run, among them a guardrail’s knowledge_refs id that is not a global page.
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
cautionpredictsincorrectmaterially more often thantrusted. This is the metric that validates whether E14’s tiers are actually predictive. - Correction recurrence: bindings with more than one
incorrectoutcome. 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_definitionoutcome history, with columnsbinding,wrong_definitioncount, distinctmarkers, 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--jsonunder"feedback". See Feedback loop (E11) and thefeedbackblock in config schema.
canonic audit --bundle
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.
canonic gc
Prune local state under .canonic/ that has outlived its retention. Dry-run by default.
Event-log segments follow
retention_days and max_segments under instrumentation.events. With neither set, nothing is removed. Rotation already applies the same limits automatically, so gc is for applying a tightened policy right away. Pending-diffs runs are audit artifacts, so they are never touched unless you pass the flag, and a run with any proposal still pending or an unreadable status.yaml is always kept. --json prints the applied flag plus the event_segments and pending_diffs lists with sizes.