Skip to content

Administration

The operator surface is CLI-first. Everything here is audited.

Keys and identity

telha api-key create --tenant <t> --org <o> --data-dir <d>   # machine API key (printed once)
telha api-key worker-token --worker-id w1                     # ingestion worker token
telha api-key mcp-token --tenant <t> --org <o>                # MCP session token

Machine credential classes are fenced: an ingestion worker token can never lease clarification or embedding jobs; a connector token can only delete records from its own connector's namespace; only the clarify service token may submit an answer on behalf of a verified person.

Human sign-in is OIDC SSO (Entra ID first): roles come from IdP group mappings, deny-by-default. An unmapped user gets 403, not viewer access. Sessions are server-side (revocation is immediate; role downgrades apply on the next request after refresh). There is no password auth and no demo auth.

Backups (do this before anything else matters)

telha backup create  --out D:\telha-backups              # online, safe under writes
telha backup verify  --from D:\telha-backups\telha-backup-<stamp>
telha backup restore --from <stamp-dir> --data-dir <EMPTY-dir>

Rules the tool enforces (not conventions, enforced):

  • Restore verifies every file hash first and refuses on any mismatch.
  • Restore targets an empty directory only, replays any erasure-ledger entries newer than the backup, and runs the consistency check before the restored directory may serve. There is no bypass flag.
  • Retention (backup.keep) prunes old backups only after a new one is created AND verified.

Two backup surfaces, always together: the core data_dir AND the app-layer PostgreSQL (it holds encryption key records, the audit log, sessions, and the subject index). The runbook pairs telha backup create with a pg_dump; a core-only artifact is marked partial. Schedule via [backup] enabled=true, interval_hours, keep or an external scheduler. Off-host copying is your job in v1: rsync or object-store sync the backup directory.

Tripwire on record: if checkpoints regularly exceed 30 minutes or artifacts exceed 50GB, the incremental-backup design reopens.

telha retention policy set --tenant <t> --label INVOICE --action archive_then_delete --archive-days 2555 --delete-days 2920
telha retention preview   # ALWAYS look before the window fires
telha retention hold set --tenant <t> --label COMPLAINT --reason "Case 44-B"

The model, in one breath: nothing expires unless a policy says so; the clock is how long since the record last changed (knowledge age, not business validity); expiry removes whole entities only; archives must verify before any delete runs; legal holds beat policy and are re-checked immediately before every delete; GDPR erasure beats holds. Every action lands in the erasure ledger with completion proofs. preview shows eligible counts, hold-blocked counts, archive size estimates, and backlog before anything acts.

Policy management is operator-only in v1, deliberately: retention is data destruction on a timer.

Clarification operations

telha clarify ls --state conflicted        # what needs a steward
telha clarify show <id>                    # delivery history, skip reasons, responses
telha clarify answer <id> --index 1        # answer from the CLI (editor scope)
telha clarify review <id> --bind <index>   # steward override on conflicts
telha clarify queue                        # attention queue

Watch the steward digest for dead-lettered questions and skip-reason patterns (they reveal identity gaps or missing app installs, both fixable).

Connectors

telha connector ls|status|run <name>. Status shows last sync, cursor age, processed/skipped/failed. Auth failures dead-letter with a CONNECTOR_AUTH_FAILED audit event (re-consent at the source, then run to resume). An expired delta cursor triggers a clean full resync by itself.

Encryption notes

Classified fields are encrypted in the app layer (XChaCha20-Poly1305, per-tenant keys wrapped by your KMS) before core storage; core, indexes, embeddings, and backups only ever see ciphertext for those fields. Consequences to know: classified fields are not searchable (by design, stated honestly), and losing the PostgreSQL key records means losing classified content, which is why PG is a first-class backup surface. Key inventory and rotation live in the enterprise admin view; rotation re-encrypts forward without rewriting history.

Health and monitoring

/healthz, /readyz, structured JSON logs with request ids, per-request tenant spans, scan-selectivity counters, nightly benchmark gates (a >20% p50 regression fails the build), and audit events for every sensitive operation. The operator console (PR-086) will put dashboards over these; until then the CLI and logs are the interface.