# Knowl v0.2.0 — Multi-source Wiki Sync

Knowl v0.2.0 adds a production, provider-free filesystem source engine and an
OKF v0.2 canonical representation for durable read-only wiki mirrors in sidecar
and embedded modes.

## What is proven

- Multiple named sources use `(source_id, document_id, revision)` identity, so
  equal relative paths do not collide.
- Initial, unchanged, selective update, complete deletion, interrupted scan,
  restart, and source-failure isolation converge through one production Host.
- Unchanged documents are not fetched or rewritten. Deleted active mirrors are
  tombstoned only after a complete scan; immutable raw history is retained.
- Retrieval accepts optional source filters and returns source ID, document ID,
  revision, canonical URI, title, and bounded snippet evidence.
- `knowl source list`, `source sync <id>`, `source sync --all`, and
  `source status <id>` use the same engine as embedded Host calls.
- Retrieval, lint, health, MCP reads, and source workflows require no maintainer
  provider. Provider-free ingest remains registered and returns the stable
  `maintainer_unavailable` outcome.
- MCP still exposes exactly `knowl_retrieve`, `knowl_ingest`, and
  `knowl_operation`; no source-management tool was added.
- Canonical `wiki/` is a directly portable OKF v0.2 bundle. Structured OKF
  metadata is preserved through filesystem, SQLite/PostgreSQL, CLI, HTTP, and
  MCP surfaces; reserved controls are never evidence.
- Attested Computation declarations remain inert metadata and are never run.

## Bootstrap compatibility

`knowl bootstrap wiki <path>`, `knowl bootstrap obsidian <path>`, and
`knowl bootstrap okf <path>` are the fresh-workspace adoption commands. They
construct deterministic `bootstrap-wiki`, `bootstrap-obsidian`, or
`bootstrap-okf` filesystem sources and perform one
shared-engine sync. Mirrors live below `wiki/sources/<source_id>/**`; bootstrap
does not replace curated `wiki/index.md`.

A newly generated bootstrap config is provider-free and retains its source.
When an operator-owned config already exists, bootstrap preserves it unchanged;
add the corresponding source entry explicitly for later ongoing sync.

Legacy canonical workspaces, including those with legacy `wiki/notes/**`, are
never silently migrated. Back up the workspace and run `knowl migrate okf-v0.2`;
the journaled, idempotent command preserves
legacy content, archives the exact prior log, commits its marker last, and
rebuilds projections. Then configure named sources, verify mirrors and retrieval
evidence, and curate or retire legacy pages according to local policy.

## Sidecar operation

Mount every source root read-only and keep `/var/lib/knowl` persistent. The
checked-in sidecar example provides `engineering` and `operations` fixtures,
on-start sync, five-minute intervals, and capped retry without a provider.
Source failures do not change readiness; inspect durable source status and keep
serving the last successful snapshot while resolving the failing root.

## Upgrade and rollback

1. Back up the persistent workspace/operational store.
2. Update configuration with unique filesystem source IDs and read-only roots.
3. Start v0.2.0 and wait for `/readyz`.
4. Run `knowl source list`, `knowl source sync --all`, and per-source status.
5. Verify unfiltered and source-filtered retrieval before changing legacy pages.

Rollback by stopping the new process and restoring the prior image/config
together. Do not delete `raw/`, `.knowl/`, or source mirrors: new raw revisions
and source state are non-destructive evidence, while older binaries may ignore
the additive state. Never run destructive down migrations.

## Intentional limits

v0.2.0 is pull-only and filesystem-first. It does not add Git or remote-wiki
adapters, write-back, export/publish, cross-source deduplication, automatic
synthesis, embeddings, UI, or source-management HTTP/MCP operations.

## Validation

The rollout gate runs full Go tests, focused race tests, strict golangci-lint,
module verification, integration-tagged PostgreSQL source tests, sidecar/config
parsing, and source-layer/packaging audits.
