nacre: Skill for Claude Code

Adding an audit event

Contract: docs/audit.md. The audit log is a product feature, not a debug log — "show me which documents your agent read last quarter" has to get a precise answer, which means completeness matters more than volume.

Always recorded

Every search with the doc_id list it returned; every document access; every grant issued and revoked; every login and token issue; every organization configuration change; every reindex start; every denial.

Denials are the most useful lines in the file and the easiest to miss, because the code path producing one is usually an early return. If you add a branch that refuses access — including one that surfaces as 404 on the wire — it writes an event with result: "deny".

Never recorded

Document contents. Chunk text. Full query text unless NACRE_AUDIT_QUERY_TEXT=true; the default stores query_hash instead, which is enough to investigate an incident and not enough to leak through the journal.

An audit log that leaks what it is auditing is worse than none, because it is retained for 400 days by default and exported to a SIEM.

Shape

{
  "org_id": "uuid",
  "actor": { "type": "service_account", "id": "uuid", "label": "svc-support-bot" },
  "surface": "mcp",              // api | mcp | admin | system
  "client":  "claude-code/2.1",  // from the client's _meta
  "action":  "search",
  "target":  { "layers": ["contracts"], "returned_docs": ["uuid"], "top_k": 10 },
  "result":  "allow",            // allow | deny | error
  "detail":  { "query_hash": "sha256:…", "latency_ms": 128, "acl_version": 42 },
  "request_id": "01JQ8…"
}

request_id is mandatory and matches the field in the HTTP error body and the OpenTelemetry trace. That correspondence is the whole investigative story; an event without it is close to useless.

Ordering

Write the event before the response goes out. A lost event is worse than a slow response. Do not move the write into a fire-and-forget background task to save latency — if that is genuinely needed, it needs a durable queue and a discussion, not a void promise.