Knowl v0.5.0

Knowl v0.5.0 — Policy-Aware Maintenance and Isolated Validation

Knowl v0.5.0 makes source maintenance respond safely to policy changes even
when source revisions do not change. It also preserves open-world links from
accepted source material while preventing one invalid generated document from
blocking unrelated valid updates.

Highlights

Policy-aware source maintenance

• A deterministic, non-secret policy generation now participates in durable
  maintenance identity. Changing an output-affecting rule, including the
  effective read ceiling, makes an unchanged source revision eligible for one
  new bounded maintenance cycle.
• Documents that previously failed the former 32,768-character ceiling can be
  reconsidered under the current 262,144-character default without editing the
  source. Repeated scans under the same generation converge without duplicate
  work.
• Automatic reconsideration remains limited to safe source-policy transitions.
  Staging, provider, and unknown failures retain their explicit manual retry
  gate.

Open-world links and provenance isolation

• Unresolved original links proven to exist in accepted Markdown are preserved
  and reported through bounded, redacted diagnostics instead of invalidating
  source staging.
• Newly invented unresolved links, malformed paths, and escaping targets remain
  rejected.
• Invalid Knowl-owned provenance such as citation.unknown_source is isolated
  to the affected document. Valid sibling documents can still commit and reach
  the index, while the prior canonical version of a rejected document remains
  readable.
• Catalog edits that would publish a broken graph are withheld with the smallest
  deterministic dependent closure.

Durable recovery and Git source hardening

• SQLite and PostgreSQL persist maintenance generation and bounded diagnostics
  with equivalent retry, restart, and idempotent replay behavior.
• Legacy rows use an explicit compatibility path, including safe replay of
  empty pre-diagnostics state, without weakening malformed-state checks.
• Git cache lineage and repository identity checks reject stale, rebound, or
  structurally incomplete cache state while preserving bounded recovery.

Compatibility and upgrade

The HTTP, MCP, provider, source configuration, and canonical Markdown contracts
remain compatible. This release adds operational-store migrations for
maintenance generation and diagnostics. The migrations preserve existing
operations and source history.

1. Stop active writers and back up the workspace and operational store.
2. Deploy ghcr.io/baldaworks/knowl:v0.5.0 and wait for /readyz.
3. Run knowl run or the configured synchronization workflow.
4. Inspect knowl source status for policy-triggered work, unresolved original
   links, isolated document rejections, and any failures that still require a
   manual class-filtered retry.

Rolling back across the new operational migrations requires restoring the
pre-upgrade operational database. Canonical Markdown and accepted raw source
history remain unchanged and portable.

Published artifact

The release workflow publishes and attests a multi-platform Linux image for
amd64 and arm64 to:

ghcr.io/baldaworks/knowl:v0.5.0

Pin the immutable digest emitted by the GitHub Release for production
deployments.

Validation

The release gate verifies modules and generated OpenAPI bindings, runs the full
race-enabled Go suite, vulnerability and architecture checks, strict linting,
the PostgreSQL integration contract, and a release-shaped persistent-volume
sidecar smoke test before publishing.

Published artifact

ghcr.io/baldaworks/knowl@sha256:367fa037eaa3f8ce0133bbfbf1c416293e24353ca0a9f3b0a19f21b3328c3bea

Knowl v0.4.0

Knowl v0.4.0 — Connected Sources and Publishable Wikis

Knowl v0.4.0 expands the complete source-to-publication workflow: it can read
remote Git repositories, recover and retry durable maintenance, organize a
semantic wiki explicitly, and export the result as a portable OKF bundle with
an llms.txt navigation document.

Highlights

Remote Git sources

• Configured remote Git sources join filesystem sources under the same bounded
  synchronization, status, retry, and maintenance lifecycle.
• HTTPS and SSH authentication remain external to configuration. SSH host keys,
  immutable repository identity, ref movement, cache size, and pack transfer
  limits are validated fail-closed.
• Branch rewrites, moved tags, and repository rebinding require explicit
  operator acknowledgement; logs and errors redact credentials and content.

Durable one-shot operation and recovery

• knowl run performs a bounded source sync, drains queued maintenance, and
  optionally reconciles hierarchy without keeping the HTTP service running.
• Failed maintenance records stable failure classes and bounded retry state.
  Operators can preview or requeue selected failures with knowl source retry.
• Recovery resumes durable work after interruption while preserving the last
  successful source checkpoint and searchable wiki projection.

Semantic hierarchy and publication

• knowl hierarchy reconcile explicitly reorganizes ordinary pages into a
  subject-first, root-reachable OKF catalog graph. Planning is deterministic,
  bounded, staged, and conflict-checked; source synchronization never invokes
  hierarchy implicitly.
• knowl export okf copies the canonical portable wiki without raw evidence,
  operational state, configuration, or databases.
• knowl export llms-txt renders bundle-relative navigation to stdout or a
  selected file, with optional title, summary, and public base URL.

Retrieval and ingestion fixes

• Search indexes semantic OKF tags and falls back to native relaxed matching
  when a strict query has no results.
• Git synchronization closes acceptance gaps around rewritten refs, cache
  safety, bounded traversal, and provenance continuity.
• The default wiki document ceiling is now 262,144 characters instead of
  32,768. Documents at the limit are accepted; larger documents still fail
  before provider invocation, alongside the independent 4 MiB byte guard.

Compatibility and upgrade

The HTTP, MCP, and embedded Go ownership model remains unchanged. This release
adds operational-store migrations for generic hierarchy operations, semantic
tag projection, retry state, and Git repository identity. The migrations are
additive and preserve existing source operations and canonical Markdown.

1. Stop active writers and back up the workspace and operational store.
2. Deploy ghcr.io/baldaworks/knowl:v0.4.0 and wait for /readyz.
3. Review any new Git source configuration, especially credentials,
   known_hosts, repository identity, and rewrite policy.
4. Run knowl run or the existing source synchronization workflow, then inspect
   knowl source status until maintenance is terminal.
5. Optionally run knowl hierarchy reconcile, validate the workspace, and
   generate publication output with knowl export okf and
   knowl export llms-txt.

After the first hierarchy operation, rolling back the binary also requires
restoring the pre-upgrade operational database. The canonical Markdown
workspace remains portable and can rebuild a fresh projection.

Published artifact

The release workflow publishes and attests a multi-platform Linux image for
amd64 and arm64 to:

ghcr.io/baldaworks/knowl:v0.4.0

Pin the immutable digest emitted by the GitHub Release for production
deployments.

Validation

The release gate verifies modules and generated OpenAPI bindings, runs the full
race-enabled Go suite, vulnerability and architecture checks, strict linting,
the PostgreSQL integration contract, and a release-shaped persistent-volume
sidecar smoke test before publishing.

Published artifact

ghcr.io/baldaworks/knowl@sha256:d1b847cc33475a2ec7cf4999431e1e3066632e544d1c8b223b933e88ff737f32

Knowl v0.3.1

Knowl v0.3.1 — Legacy Provenance Backfill

Knowl v0.3.1 fixes source-filtered retrieval after upgrading a workspace whose
raw revisions were accepted before configured-source provenance was stored in
raw manifests.

Fix

• Reconciliation enriches a legacy raw manifest with its validated
  source_document identity while reusing the already accepted immutable
  source bytes; unchanged documents are not fetched from the connector again.
• The enrichment is one-way and conflict-safe: existing provenance cannot be
  replaced by a different document identity.
• The projection rebuilt by the same source sync now records
  source_documents and page-to-source relations for semantic pages that cite
  those legacy revisions. knowl retrieve --source <id> therefore returns the
  same relevant semantic evidence as unfiltered retrieval.

Bootstrap and sync.on_start remain optional. Source documents remain outside
the portable semantic wiki, and legacy wiki/sources/<source_id>/** mirrors
remain excluded.

Upgrade

1. Stop active writers and back up the complete workspace and operational
   store.
2. Deploy ghcr.io/baldaworks/knowl:v0.3.1.
3. Run knowl source sync --all once. The sync backfills legacy provenance and
   rebuilds the projection even when all maintenance operations are already
   terminal.
4. Verify both unfiltered retrieval and --source retrieval for an existing
   semantic page.

Published artifact

The release workflow publishes and attests a multi-platform Linux image for
amd64 and arm64 to:

ghcr.io/baldaworks/knowl:v0.3.1

Pin the digest emitted by the GitHub Release for production deployments.

Published artifact

ghcr.io/baldaworks/knowl@sha256:8039d9d6941eaf0f94577f094d8885d3ccf1f3aec001959012d914b034283f16

Knowl v0.3.0

Knowl v0.3.0 — Semantic Source Maintenance

Knowl v0.3.0 turns configured sources into immutable evidence for one
maintainer-owned semantic wiki. Source revisions no longer become pages inside
the portable OKF bundle.

Breaking changes

• A runnable Host must have either an explicitly injected maintainer or a valid
  knowl.provider selected from runtime.providers. The maintainer provider is
  now required before readiness.
• Filesystem synchronization stores exact accepted revisions under raw/ and
  no longer materializes active wiki/sources/<source_id>/** mirrors.
• A successful source sync means raw acceptance and durable maintenance
  reservation. Model-backed wiki updates complete asynchronously and are
  reported separately by source status.

Bootstrap remains optional. sync.on_start also remains explicit per-source
configuration and may be disabled in favor of manual synchronization.

Semantic wiki behavior

• The maintainer creates and updates root-reachable semantic OKF entities,
  concepts, syntheses, and catalogs instead of copying source paths.
• Curated factual pages must cite accepted raw refs. Updates preserve unrelated
  source lineages and may replace only an older revision from the same source
  document lineage.
• Related evidence from multiple configured sources can support one page.
  Retrieval returns its sorted source_documents collection, and filtering by
  any contributing source returns the shared page.
• Catalog and source-mirror control pages are excluded from retrieval evidence.
  SQLite and PostgreSQL use the same rebuildable page-to-source projection.

Upgrade

1. Stop active writers and back up the complete workspace and operational
   store.
2. Configure runtime.providers and select one with knowl.provider before
   starting the new image.
3. Deploy ghcr.io/baldaworks/knowl:v0.3.0 and wait for /readyz.
4. Run knowl source sync --all, then inspect each knowl source status.
5. Wait for queued maintenance operations to commit and verify unfiltered and
   source-filtered retrieval.

On each source's next successful reconciliation, Knowl removes only that
source's legacy derived wiki/sources/<source_id>/** subtree through staged
recovery. Existing raw revisions and curated semantic pages remain unchanged.
Upstream deletion tombstones source state but does not implicitly delete
accumulated knowledge.

Source status exposes deterministic bounded queued, replayed, committed, and
failed maintenance counts and samples. Structured logs correlate source,
document, revision, and operation identifiers without source bodies, prompts,
credentials, or provider secrets.

Published artifact

The release workflow publishes and attests a multi-platform Linux image for
amd64 and arm64 to:

ghcr.io/baldaworks/knowl:v0.3.0

Pin the digest emitted by the GitHub Release for production deployments.

Validation

The release gate verifies modules and generated OpenAPI bindings, runs the full
race-enabled Go suite, vulnerability and architecture checks, strict linting,
the PostgreSQL integration contract, and a release-shaped persistent-volume
sidecar smoke test before publishing.

Published artifact

ghcr.io/baldaworks/knowl@sha256:b197e3273fd214f8f38c85de0ecb656650675cbbc155b7835a05ca4027df2d0c

Knowl v0.1.0

Knowl v0.1.0 — Crash-safe Knowledge Loop

Knowl v0.1.0 is the first release of the self-hosted knowledge sidecar for
agentic applications: durable project knowledge for agents.

What is proven

• Accepted immutable sources and their execution descriptors survive restart.
• One application runner resumes work to a terminal completed or failed
  operation with at-least-once execution and idempotent canonical commit.
• Markdown and immutable raw sources remain canonical; SQLite/PostgreSQL and
  lexical search remain rebuildable projections.
• Lexical results are relevance ordered and return match-centered bounded
  excerpts. Source-aware maintenance context updates existing decisions instead
  of creating semantic duplicates.
• The deterministic project-decisions corpus reaches 12/12 expected top-five
  retrieval hits through MCP, HTTP, SQLite, and PostgreSQL with source refs.
• HTTP business endpoints and MCP require the configured operator bearer token;
  /healthz and /readyz remain public probes.

The public business contract still contains exactly three operations:
knowl_retrieve, knowl_ingest, and knowl_operation over MCP, with their
equivalent HTTP control-plane routes.

Run the image

docker pull ghcr.io/baldaworks/knowl:v0.1.0
docker run --rm \
  -p 127.0.0.1:8080:8080 \
  -e KNOWL_OPERATOR_TOKEN=replace-with-a-strong-secret \
  -v knowl-data:/var/lib/knowl \
  ghcr.io/baldaworks/knowl:v0.1.0

The release workflow appends the immutable manifest digest to the GitHub
Release. Production deployments should replace the mutable tag with
ghcr.io/baldaworks/knowl@sha256:<published-digest>.

GET /readyz becomes successful only after workspace recovery, durable-work
resumption setup, and projection preparation. Persist /var/lib/knowl; it owns
the canonical raw/Markdown workspace and SQLite operational state.

Upgrade and rollback

1. Back up or snapshot the persistent volume according to local policy.
2. Stop the old container without deleting /var/lib/knowl.
3. Start v0.1.0 by immutable digest with the same volume and operator token.
4. Wait for /readyz, then verify authenticated retrieve and operation reads.

For rollback, stop the new container and run the previous known-good image
digest against the retained volume. Do not discard pending operations, delete
the volume, or run destructive down migrations. Additive operational schema is
retained for forward recovery.

Known limits

v0.1.0 intentionally has no UI, connector zoo, embeddings, multi-tenancy,
Git synchronization, generic memory API, or section-level provenance. Hosts
decide which events are durable and generate final user answers; Knowl maintains
inspectable project knowledge and returns bounded provenance-backed evidence.

Published artifact

ghcr.io/baldaworks/knowl@sha256:deea20c3a79c7f5a927ed282a7d85579061f043104f171b17f4874d82fd6443f