v0.17.0

What's Changed

• feat(appliance): in-VM Traefik router — unified HTTP ingress (ADR-105 step 1) by @aaronsb in #517
• feat(appliance): Traefik TLS cert path — EXTERNAL_URL + 4 cert modes (ADR-105) by @aaronsb in #518
• docs: consolidate 154 docs → 47 pages (Diátaxis taxonomy + voice guide + generated reference) by @aaronsb in #519
• docs(adr): normalize ADR frontmatter + enforce the decision graph by @aaronsb in #520
• docs(adr): renumber legacy ADRs into domain bands; retire the 1–99 range by @aaronsb in #521
• feat(docs): add doc catalog librarian tool by @aaronsb in #522
• feat(tls): in-container DNS-01 (porkbun) for letsencrypt mode by @aaronsb in #523
• fix(appliance): make the appliance build + deploy on modern Docker (first cube deploy) by @aaronsb in #524
• fix(appliance): web OAuth client_id/redirect in router overlay (login 400) by @aaronsb in #526
• docs(self-host): remote virt-manager console gotchas (cube) by @aaronsb in #525
• feat(appliance): declarative host-management login (Cockpit/console) by @aaronsb in #527
• feat(appliance): Cockpit behind Traefik at /cockpit (trusted cert) by @aaronsb in #528
• docs(appliance): screenshot placeholders for management surfaces by @aaronsb in #529
• feat(appliance): configurable /cockpit access control + auth hardening by @aaronsb in #530
• feat(appliance): ADR-119 config-delivery model + OVA bootstrap-seed publishing by @aaronsb in #531

Full Changelog: v0.16.0...v0.17.0

v0.16.0

Knowledge Graph System v0.16.0

22 commits since v0.15.1. This release lands ADR-103 Stage 2 — the x86 thin
appliance and its single-box control plane — alongside the #502 security
hardening, the nomic-first local-embedding default, and the ontology-layer
restore work.

Component versions: platform 0.16.0 · CLI @aaronsb/kg-cli 0.14.0
(unchanged) · FUSE kg-fuse 0.12.1 (unchanged).

Images are published multi-arch (linux/amd64 + linux/arm64) to GHCR at
ghcr.io/aaronsb/knowledge-graph-system/kg-{api,web,operator,postgres}:0.16.0.

Added

Thin appliance — x86 (ADR-103 Stage 2)

• appliance/ build (libguestfs virt-customize): a minimal Debian host with
  Docker + the repo at /opt/kg, emitting qcow2 + OVA. Container images are
  pulled on first boot (thin), not baked.
• Bake/first-boot split with a no-baked-secrets invariant — per-instance
  ENCRYPTION_KEY/POSTGRES_PASSWORD/etc. are minted on first power-on via
  operator.sh init --headless, never shipped in the image.
• Single-box control plane (three ascending-privilege layers): cloud-init
  declarative provisioning (provision.env), a console TUI (DCUI on tty1), and
  Cockpit (:9090) for host management.
• Nomic text + vision embedding models baked into kg-api for offline first
  boot. Appliance surface branded Kappa Graph.

Embeddings

• Local nomic-embed-text-v1.5 (768-dim, on-device, no API key) is now the
  default embedding profile. Reasoning/extraction still uses a remote LLM.

Restore (ADR-102 follow-on, #505)

• Rehydrate the :Ontology + :DocumentMeta layers from Sources; seed the
  primordial ontology on a clean install.

Security

• #502 — fresh production init no longer ships a weak/password
POSTGRES_PASSWORD; infra ports (postgres, garage) bind loopback-only; a
  fail-closed startup assertion refuses placeholder secrets.

Changed (CI)

• Appliance CI is now an integration test of the published GHCR images
  (operator.sh init --image-source=ghcr + health check) rather than an
  emulated qcow2 build — CI integrates already-built containers, it never
  builds them (#516).
• Tag pushes no longer trigger GH container builds; added a shell-syntax lint.

Architecture

• ADR-103 — distribution strategy: nomic-first thin appliance.
• ADR-104 — unified provisioning, install-path convergence, first-run claim
  protocol (Draft).

v0.15.0

Knowledge Graph System v0.15.0

127 commits since v0.14.0. This release lands the ADR-102 backup/restore
overhaul, the ADR-207 freshness contract, ADR-705 capability gating with
mid-session expiry handling, and ADR-802/803 vision-provider support.

Component versions: platform 0.15.0 · CLI @aaronsb/kg-cli 0.14.0 ·
FUSE kg-fuse 0.12.1 (unchanged).

Added

Backup & restore — kg-backup/2 (ADR-102)

• New self-describing kg-backup/2 export format with a versioned header.
• kg admin verify-backup — validate a backup without restoring it.
• Offline backup validator, including a concept embedding-dimension check.
• kg restore --mode {idempotent,adjacent,integration} replaces the old
  --merge/--deps flags, with an adjacent-mode ID-remap layer.
• kg restore --epoch {simple,faithful} — faithful epoch-replay restore with
  replay orchestration, an eligibility gate, and source-embedding rehydration.
• ConceptMatcher integration engine ported into the API.

Freshness contract (ADR-207)

• Trustworthy committed-epoch watermark; the freshness tick is now universal
  across all mutation kinds.
• Grounding, confidence, and artifact caches migrated onto the freshness
  contract; artifact regenerate / cleanup / stale-guidance UX.
• graph_accel.generation declared as a co-advancing sub-counter.

Capability gating & sessions (ADR-705)

• Declarative capability-gating primitives with a gating-adoption linter for the
  web UI.
• Session status endpoint + 401 interceptor for mid-session token expiry.
• Ambient session-treatment banner.

Vision providers (ADR-802 / ADR-803)

• kg admin vision commands (config / providers / set) and a vision-provider
  selector card in the System tab.
• Image index decoupled from the text embedding space.
• Active vision-provider slot — resolve, persist, configure.

Ontology, vocabulary & admin (ADR-701)

• Vocabulary tab wired to the ontology lifecycle, with a Recent Runs log.
• Admin/operator UI controls for worker lanes, ontology delete, and tombstones.
• Global candidate-concept retrieval for reasoner context.

Changed

• Vision provider hierarchy collapsed into the unified AIProvider interface.
• serialization.py split into a serialization/ package.
• Dead backup/restore code (TS + Python) purged after the ADR-102 migration.
• CLI doc generator now driven from the command registry instead of a static list.
• CLI publishing moved to npm OIDC Trusted Publishing (no token, no 2FA) via CI.

Fixed

• Capture pg_restore exit codes and restore into an empty DB (#397, #398).
• True-replace rollback (#483) and orphaned-epoch reconciliation (#485).
• Refractory gate — defer cycles while ingestion is in flight.
• Disable retired Anthropic model snapshots in seed + sketch reconcile.
• Detect OpenAI describe_image data-URL MIME from magic bytes.
• FUSE: use path-derived ontology in document frontmatter.

Container images

docker pull ghcr.io/aaronsb/knowledge-graph-system/kg-api:0.15.0
docker pull ghcr.io/aaronsb/knowledge-graph-system/kg-web:0.15.0
docker pull ghcr.io/aaronsb/knowledge-graph-system/kg-operator:0.15.0

Upgrade: sudo ./operator.sh upgrade

v0.12.0

What's Changed

• fix(fuse): poll active jobs so .ingesting flags clear automatically by @aaronsb in #354
• feat(embeddings): point size mapping and convex hulls for t-SNE by @aaronsb in #356
• feat(graph): require evidence on manual concept creation by @aaronsb in #358
• ADR-800: Dynamic model catalog and OpenRouter support by @aaronsb in #357
• feat(web): V2 unified 3D renderer (ADR-702 phase 1) by @aaronsb in #360
• fix(cli): narrow axios response headers to string at use sites by @aaronsb in #361
• chore(ways): refresh project-local way frontmatter to embed-aware schema by @aaronsb in #362
• refactor(web): unify exploration action layer (ADR-500 / -083 / -034 affirmation) by @aaronsb in #363
• refactor(web): retire V1, promote unified-engine 3D to canonical by @aaronsb in #365
• feat(web): add 2D projection to the unified engine (force-2d-v2) by @aaronsb in #366
• refactor(web): Phase C — consolidate to one Force Graph plugin by @aaronsb in #367
• feat(web): Document Explorer adopts the unified engine (ADR-702 phase 4) by @aaronsb in #368
• feat(web): multi-select relationship-type + ontology filters by @aaronsb in #369
• feat(web): incremental graph physics — calm node growth on poke by @aaronsb in #371
• feat(web): platonic-solid glyph nodes with two-tone faceted material by @aaronsb in #373
• feat(web): startup auto-zoom + Force Graph / Document Explorer parity by @aaronsb in #374
• feat: uniform DB-driven provider configuration contract (ADR-801) by @aaronsb in #376
• feat(vision): catalog-driven vision model selection (reaffirms ADR-801) by @aaronsb in #380
• ADR-203: Graph epoch event log (addresses #187) by @aaronsb in #381
• ADR-203 exposure: epoch event log + concept lifetime via MCP/CLI by @aaronsb in #382
• ADR-204: Node type & abstract-property representation (Draft, renumbered from 203) by @aaronsb in #372
• fix(providers): forced tool_use + catalog-driven model resolution by @aaronsb in #389
• test(program-executor): update mocks for dispatch_cypher 3-arg signature by @aaronsb in #390
• refactor(adr-203): rename graph_epochs kind 'breathing' to 'annealing' by @aaronsb in #391
• feat(ontology): ADR-703 ontology lifecycle administration interface (MVP) by @aaronsb in #392
• fix(annealing): repair promotion source assignment + autonomous approval by @aaronsb in #393
• fix(annealing): make the cycle idempotent — stop re-proposing queued/done work by @aaronsb in #394

Full Changelog: v0.11.0...v0.12.0

v0.11.0

What's New

Worker Lane Visibility (ADR-100)

• CLI: kg admin workers and kg admin workers lanes commands for slot utilization, queue depth, and active job monitoring
• Web UI: Workers section in Admin > System tab with tile summary, lane status bars, and active job list
• MCP: workers/status resource exposing lane configuration and slot utilization

Platform Reliability

• AGE label race condition fix: Pre-create all 47 graph labels (vertex + edge) at schema init, preventing "relation already exists" errors on first ingest of a fresh install
• Retry logic in Cypher executor: _execute_cypher now retries on AGE label creation races (2 attempts with rollback) as defense-in-depth
• OAuth recovery: Fix auth key cleanup after platform redeploy (--force logout now clears all auth keys)
• Migration 053 registration: Add missing schema_migrations INSERT that caused init warnings

Timestamp Consistency

• ADR-202: Proposed normalization of 15 bare TIMESTAMP columns to TIMESTAMPTZ with draft SQL migration
• Client-side Z-append: Worker duration displays now correctly parse UTC timestamps regardless of client timezone (CLI, web, MCP)

Operator & Init Fixes

• Embedding init: Operator init scripts use --provider local instead of hardcoded embedding ID (broken after migration 055 reorder)
• Font scaling: Appearance preferences now include a font scale slider (75%-150%)

Install / Upgrade

New install:

curl -fsSL https://raw.githubusercontent.com/aaronsb/knowledge-graph-system/main/install.sh | bash

Existing install:

sudo ./operator.sh upgrade

CLI (npm):

npm install -g @aaronsb/kg-cli@0.11.0

FUSE (PyPI):

pipx upgrade kg-fuse